feat(agents): declare and refresh subject aliases (#1701, slice 2)

[decode2]

Linked issue

Refs #1701

PR type

• New feature (type:feature)

Summary

• Declare a short subject through existing orchestrator_session_id only when Pi's canonical session name is empty; return the alias beside the stable routing ID.
• Preserve existing names and human renames; refresh names using the existing heartbeat, without a second alias store, timer or model call.
• Ship parent-only declaration guidance with privacy boundaries and prompt-budget coverage.

Changes

Surface	Change
extensions/gentle-agents.ts	Optional subject declaration and session-bound canonical-name source.
lib/orchestrator-presence.ts	Shared sanitizer and heartbeat name refresh.
Agent/presence/budget tests	Declaration, idle rename, human-name preservation, stale contexts, replacement and shipped guidance.
assets/orchestrator.md, activity docs, ODD	Correct parent-only expectation, limits and work-unit evidence.

Verification

• Meaningful RED/GREEN for declaration and heartbeat rename.
• Final presence/discovery/agents/budget suite: 228 passed, 0 failed.
• Type ratchet: 186 recorded diagnostics, no regressions; not clean compilation.
• Runtime module check: 8 modules match.
• Registered-tool harness: no child launch, custom message or user message.
• Default prompt fits unchanged 8,192-byte guard including controlled long assets root.
• Native assessment: medium, runtime large writer, under budget; self-verification stands. Additional bounded read-only spot check passed.
• Full CI and interactive live-model/Windows validation: not claimed locally.

Contributor checklist

• Approved issue referenced, exactly one type label.
• Tests/docs with behavior, Conventional Commits, no AI attribution.
• No shell scripts or skills modified; shellcheck/skill-load checks N/A.
• Canonical names remain sole alias truth; names never authenticate or replace routing IDs.

Chain context

Field	Value
Strategy	Stacked PRs, incorporate in order
Position	2
Base / dependency	feat/1701-coordination-discovery, #1714
Starts at	6bf09b38
Ends with	Subject declarations and idle canonical-name refresh
Follow-up	Authoritative repository/worktree identity and scope lifecycle; #1702 consultations.
Review budget	232 changed lines / 400
Rollback	Optional naming and label-source changes plus related tests/docs; prior discovery remains usable.

main
 └── #1714 Recognizable discovery
      └── 📍 This PR: subject aliases
           └── Next: repository/worktree scope (#1701)
                └── Later: consultations/owner decisions (#1702)

No complete #1701 closure: repository identity and extended registered-workspace projection remain next work. Structural prompt checks establish expected behavior, not proof that every model obeys it. No merge, auto-merge, push to main or runtime reload.

Summary by CodeRabbit

• New Features

  • Sessions can now receive a short, sanitized display name based on the task subject. Existing names and later human renames are preserved.
  • Presence labels refresh to reflect current session names, while stable session IDs continue to handle routing.

• Bug Fixes

  • Prevented stale sessions from updating presence labels. Presence entries are cleaned up if publishing fails.

• Documentation

  • Clarified when session subjects are set, which task details appear in activity, and how session names and labels are handled.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 337ff114-74d3-4dbb-a3d1-1c1dd9c29ad3

📥 Commits

Reviewing files that changed from the base of the PR and between e7fef45 and c658623.

📒 Files selected for processing (8)

• assets/orchestrator-delegation.md
• docs/gentle-agents-activity.md
• extensions/gentle-agents.ts
• lib/orchestrator-presence.ts
• odd/tasks/agent-coordination.md
• tests/gentle-agents.test.ts
• tests/orchestrator-budget.test.ts
• tests/orchestrator-presence.test.ts

 _______________________________________
< We're gonna need a bigger bug zapper. >
 ---------------------------------------
  \
   \   (\__/)
       (•ㅅ•)
       / 　 づ

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}