docs: sessions self-name — AO Master Orchestrator + per-work worker renames

[polymath-orchestrator]

Closes #21.

Orchestration-layer change only — no ao source touched (vanilla rule). All mechanisms were verified live on the implementing session (agent-orchestrator-9) before being written into policy.

What changed

• Repo extensions (agent-instructions/source/55-extensions.md) — new Session self-naming rules for every ao-hosted session: on claiming a work item and on every queue item transition, set the ao display name (ao session rename "$SID" "#<issue> <slug>", 20-char cap) and — claude-code harness only — the Claude Code session title via tmux send-keys -t "$SID" -l '/rename …' + Enter into the session's own pane (the same injection path ao send uses; verified safe mid-turn). Never rename the tmux session itself: its name is the ao session id and ao addresses the pane by it.
• Orchestrator standing policy (agent-instructions/source/60-orchestrator.md) — the orchestrator self-names at startup: AO Master Orch on the ao side (20-char cap), full AO Master Orchestrator as the Claude Code title. Spawn --name "#<issue> <slug>" kept; spawn prompts must now carry the worker self-rename duty.
• Fleet cap corrected 4 → 8 per Nick's directive of 2026-07-06 (the fragment was stale against that instruction). Flagging for reviewer attention since it rests on an operator directive outside this diff.
• package.json — added the missing agents / agents:check / agents:system scripts that the generated-file banner and scripts/polyscribe.sh usage notes already referenced (bug found while building, shipped in-PR per rule 8).
• AGENTS.md / AGENTS.shared.md / CLAUDE.md / GEMINI.md regenerated via the assembler; agents:check passes.

Live verification evidence

1. ao session rename agent-orchestrator-9 "#21 self-name" — succeeded from inside the session; name visible in ao session get --json (displayName).
2. Cap probe: a 22-char rename was accepted by the CLI rename path — confirming the known upstream gap (spawn/API enforce maxDisplayNameLen=20, rename doesn't; upstream Session rename accepts display names longer than the 20-character cap that spawn enforces AgentWrapper/agent-orchestrator#2375/fix(session): enforce 20-char display name cap on rename AgentWrapper/agent-orchestrator#2383) — hence policy pins names to ≤20 chars.
3. tmux send-keys … '/rename #21 self-name' + Enter against the session's own pane mid-turn → Session renamed to: #21 self-name in the Claude Code UI without disturbing the running turn.
4. tmux surface intentionally untouched: tmux display-message -p '#S' = agent-orchestrator-9 = the ao session id ao uses for send-keys addressing.

Deviation from AC as written: no scratch worker was spawned to watch a rename (worker sessions don't spawn workers — dispatch is the orchestrator's; fleet-cap discipline). The identical mechanism — a session renaming itself on both surfaces — is what was verified live, on this session.

Follow-ups filed (findings, not changes — vanilla rule)

• ao gap: session displayName has no first-class path to the harness session title #28 — ao gap: displayName has no first-class path to the harness session title (agent:noauto).
• ao gap: backend/internal/cli spawn tests fail under ambient AO_SESSION_ID/AO_PROJECT_ID (no env isolation) #31 — pre-existing: backend/internal/cli spawn tests fail under ambient AO_SESSION_ID/AO_PROJECT_ID (every ao worker env); proof and upstream-shaped fix in the issue (agent:noauto).

Gates

• Backend: go build ./... && go vet ./... && go test ./... — green (test run with AO_SESSION_ID/AO_PROJECT_ID cleared per ao gap: backend/internal/cli spawn tests fail under ambient AO_SESSION_ID/AO_PROJECT_ID (no env isolation) #31; failures reproduce on unmodified main).
• Frontend: tsc --noEmit — green.
• npm run agents:check — no drift.

🤖 Generated with Claude Code

https://claude.ai/code/session_01XeeHG3EbzwMa4vtpvitrqn

---

^{Need help on this PR? Tag /codesmith with what you need. Autofix is disabled.}

[Copilot]

Pull request overview

Updates the repository’s orchestration-layer instruction set to keep ao-hosted sessions self-named (ao displayName + Claude Code title where supported), and wires the missing npm scripts used to assemble/regenerate the agent instruction files.

Changes:

• Add “Session self-naming” policy (rename on claim + on each queue transition) and document the claude-code /rename via tmux send-keys.
• Update orchestrator standing policy (orchestrator self-names at startup; fleet cap 4 → 8; reinforce worker self-rename duty in spawn prompts).
• Add agents / agents:check / agents:system scripts and regenerate the assembled instruction files.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
package.json	Adds missing scripts for building/checking/system-installing assembled agent instruction files.
agent-instructions/source/55-extensions.md	Introduces the repo extension policy for session self-naming across surfaces.
agent-instructions/source/60-orchestrator.md	Updates orchestrator policy to self-name and to require worker self-rename behavior; updates fleet cap.
AGENTS.md	Regenerated assembled instructions (Codex identity + shared body).
AGENTS.shared.md	Regenerated identity-free shared-body artifact.
CLAUDE.md	Regenerated assembled instructions (Claude identity + shared body).
GEMINI.md	Regenerated assembled instructions (Gemini identity + shared body).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.