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

AGENTS.md

@@ -215,6 +215,25 @@ Shared skills describe *process* and resolve the *who/how* from this contract:
   a bad change here takes down the whole fleet; a human reviews those merges.
 - **Env:** sessions run with `POLYPOWERS_AUTOMERGE=1` and
   `POLYPOWERS_REPO=polymath-ventures/agent-orchestrator` (project config).
+- **Session self-naming (ao-hosted sessions):** keep your session's name in
+  sync with your current work item so the dashboard and the Claude Code
+  session list read like a live work log. Workers set both surfaces on
+  claiming a work item and again on every queue item transition. Your ao
+  session id is `SID="${AO_SESSION_ID:-$(tmux display-message -p '#S')}"`
+  (ao injects the env var; tmux is the fallback). Derive `<slug>` from the
+  issue title: lowercase `[a-z0-9-]` only, everything else stripped — never
+  interpolate a raw title into a shell command.
+  - ao display name: `ao session rename "$SID" "#<issue> <slug>"` — 20-char
+    cap (enforced at spawn/API; the CLI rename path currently skips the
+    check, so never rely on a longer name sticking). Visible in the
+    dashboard and `ao session get`; the `ao session ls` table doesn't show
+    it yet (gap tracked in GH #28).
+  - Claude Code session title (claude-code harness only):
+    `tmux send-keys -t "$SID" -l '/rename #<issue> <slug>'` then
+    `tmux send-keys -t "$SID" Enter` — verified safe mid-turn. Other
+    harnesses have no title surface; ao display name only.
+  - Never rename the tmux session itself — its name IS the ao session id and
+    ao addresses the pane by it.
 
 ## Orchestrator standing policy
 
@@ -263,9 +282,20 @@ worker on a deploy.
 
 ### Fleet caps + naming
 
-Hard cap: **4 concurrent workers per project** (check `ao session ls` before
-every spawn; queue the rest). Every spawn gets `--name "#<issue> <slug>"` so
-the dashboard reads like a work log.
+Hard cap: **8 concurrent workers per project** (raised from 4 by Nick,
+2026-07-06; check `ao session ls` before every spawn; queue the rest).
+
+The dashboard and Claude Code session list are the work log — three naming
+duties:
+- **Yourself, at startup:** `ao session rename
+  "${AO_SESSION_ID:-$(tmux display-message -p '#S')}" "AO Master Orch"`
+  (shortened for the 20-char ao cap), and set the full
+  "AO Master Orchestrator" as your Claude Code session title via the
+  send-keys `/rename` mechanics in Repo extensions → Session self-naming.
+- **Every spawn** gets `--name "#<issue> <slug>"` (≤20 chars).
+- **Every spawn prompt** instructs the worker to self-rename per Session
+  self-naming (Repo extensions): on claiming its work item, and again on
+  every queue item transition.
 
 ### Always-running supervision
 

AGENTS.shared.md

@@ -215,6 +215,25 @@ Shared skills describe *process* and resolve the *who/how* from this contract:
   a bad change here takes down the whole fleet; a human reviews those merges.
 - **Env:** sessions run with `POLYPOWERS_AUTOMERGE=1` and
   `POLYPOWERS_REPO=polymath-ventures/agent-orchestrator` (project config).
+- **Session self-naming (ao-hosted sessions):** keep your session's name in
+  sync with your current work item so the dashboard and the Claude Code
+  session list read like a live work log. Workers set both surfaces on
+  claiming a work item and again on every queue item transition. Your ao
+  session id is `SID="${AO_SESSION_ID:-$(tmux display-message -p '#S')}"`
+  (ao injects the env var; tmux is the fallback). Derive `<slug>` from the
+  issue title: lowercase `[a-z0-9-]` only, everything else stripped — never
+  interpolate a raw title into a shell command.
+  - ao display name: `ao session rename "$SID" "#<issue> <slug>"` — 20-char
+    cap (enforced at spawn/API; the CLI rename path currently skips the
+    check, so never rely on a longer name sticking). Visible in the
+    dashboard and `ao session get`; the `ao session ls` table doesn't show
+    it yet (gap tracked in GH #28).
+  - Claude Code session title (claude-code harness only):
+    `tmux send-keys -t "$SID" -l '/rename #<issue> <slug>'` then
+    `tmux send-keys -t "$SID" Enter` — verified safe mid-turn. Other
+    harnesses have no title surface; ao display name only.
+  - Never rename the tmux session itself — its name IS the ao session id and
+    ao addresses the pane by it.
 
 ## Orchestrator standing policy
 
@@ -263,9 +282,20 @@ worker on a deploy.
 
 ### Fleet caps + naming
 
-Hard cap: **4 concurrent workers per project** (check `ao session ls` before
-every spawn; queue the rest). Every spawn gets `--name "#<issue> <slug>"` so
-the dashboard reads like a work log.
+Hard cap: **8 concurrent workers per project** (raised from 4 by Nick,
+2026-07-06; check `ao session ls` before every spawn; queue the rest).
+
+The dashboard and Claude Code session list are the work log — three naming
+duties:
+- **Yourself, at startup:** `ao session rename
+  "${AO_SESSION_ID:-$(tmux display-message -p '#S')}" "AO Master Orch"`
+  (shortened for the 20-char ao cap), and set the full
+  "AO Master Orchestrator" as your Claude Code session title via the
+  send-keys `/rename` mechanics in Repo extensions → Session self-naming.
+- **Every spawn** gets `--name "#<issue> <slug>"` (≤20 chars).
+- **Every spawn prompt** instructs the worker to self-rename per Session
+  self-naming (Repo extensions): on claiming its work item, and again on
+  every queue item transition.
 
 ### Always-running supervision
 

CLAUDE.md

@@ -215,6 +215,25 @@ Shared skills describe *process* and resolve the *who/how* from this contract:
   a bad change here takes down the whole fleet; a human reviews those merges.
 - **Env:** sessions run with `POLYPOWERS_AUTOMERGE=1` and
   `POLYPOWERS_REPO=polymath-ventures/agent-orchestrator` (project config).
+- **Session self-naming (ao-hosted sessions):** keep your session's name in
+  sync with your current work item so the dashboard and the Claude Code
+  session list read like a live work log. Workers set both surfaces on
+  claiming a work item and again on every queue item transition. Your ao
+  session id is `SID="${AO_SESSION_ID:-$(tmux display-message -p '#S')}"`
+  (ao injects the env var; tmux is the fallback). Derive `<slug>` from the
+  issue title: lowercase `[a-z0-9-]` only, everything else stripped — never
+  interpolate a raw title into a shell command.
+  - ao display name: `ao session rename "$SID" "#<issue> <slug>"` — 20-char
+    cap (enforced at spawn/API; the CLI rename path currently skips the
+    check, so never rely on a longer name sticking). Visible in the
+    dashboard and `ao session get`; the `ao session ls` table doesn't show
+    it yet (gap tracked in GH #28).
+  - Claude Code session title (claude-code harness only):
+    `tmux send-keys -t "$SID" -l '/rename #<issue> <slug>'` then
+    `tmux send-keys -t "$SID" Enter` — verified safe mid-turn. Other
+    harnesses have no title surface; ao display name only.
+  - Never rename the tmux session itself — its name IS the ao session id and
+    ao addresses the pane by it.
 
 ## Orchestrator standing policy
 
@@ -263,9 +282,20 @@ worker on a deploy.
 
 ### Fleet caps + naming
 
-Hard cap: **4 concurrent workers per project** (check `ao session ls` before
-every spawn; queue the rest). Every spawn gets `--name "#<issue> <slug>"` so
-the dashboard reads like a work log.
+Hard cap: **8 concurrent workers per project** (raised from 4 by Nick,
+2026-07-06; check `ao session ls` before every spawn; queue the rest).
+
+The dashboard and Claude Code session list are the work log — three naming
+duties:
+- **Yourself, at startup:** `ao session rename
+  "${AO_SESSION_ID:-$(tmux display-message -p '#S')}" "AO Master Orch"`
+  (shortened for the 20-char ao cap), and set the full
+  "AO Master Orchestrator" as your Claude Code session title via the
+  send-keys `/rename` mechanics in Repo extensions → Session self-naming.
+- **Every spawn** gets `--name "#<issue> <slug>"` (≤20 chars).
+- **Every spawn prompt** instructs the worker to self-rename per Session
+  self-naming (Repo extensions): on claiming its work item, and again on
+  every queue item transition.
 
 ### Always-running supervision
 

GEMINI.md

@@ -215,6 +215,25 @@ Shared skills describe *process* and resolve the *who/how* from this contract:
   a bad change here takes down the whole fleet; a human reviews those merges.
 - **Env:** sessions run with `POLYPOWERS_AUTOMERGE=1` and
   `POLYPOWERS_REPO=polymath-ventures/agent-orchestrator` (project config).
+- **Session self-naming (ao-hosted sessions):** keep your session's name in
+  sync with your current work item so the dashboard and the Claude Code
+  session list read like a live work log. Workers set both surfaces on
+  claiming a work item and again on every queue item transition. Your ao
+  session id is `SID="${AO_SESSION_ID:-$(tmux display-message -p '#S')}"`
+  (ao injects the env var; tmux is the fallback). Derive `<slug>` from the
+  issue title: lowercase `[a-z0-9-]` only, everything else stripped — never
+  interpolate a raw title into a shell command.
+  - ao display name: `ao session rename "$SID" "#<issue> <slug>"` — 20-char
+    cap (enforced at spawn/API; the CLI rename path currently skips the
+    check, so never rely on a longer name sticking). Visible in the
+    dashboard and `ao session get`; the `ao session ls` table doesn't show
+    it yet (gap tracked in GH #28).
+  - Claude Code session title (claude-code harness only):
+    `tmux send-keys -t "$SID" -l '/rename #<issue> <slug>'` then
+    `tmux send-keys -t "$SID" Enter` — verified safe mid-turn. Other
+    harnesses have no title surface; ao display name only.
+  - Never rename the tmux session itself — its name IS the ao session id and
+    ao addresses the pane by it.
 
 ## Orchestrator standing policy
 
@@ -263,9 +282,20 @@ worker on a deploy.
 
 ### Fleet caps + naming
 
-Hard cap: **4 concurrent workers per project** (check `ao session ls` before
-every spawn; queue the rest). Every spawn gets `--name "#<issue> <slug>"` so
-the dashboard reads like a work log.
+Hard cap: **8 concurrent workers per project** (raised from 4 by Nick,
+2026-07-06; check `ao session ls` before every spawn; queue the rest).
+
+The dashboard and Claude Code session list are the work log — three naming
+duties:
+- **Yourself, at startup:** `ao session rename
+  "${AO_SESSION_ID:-$(tmux display-message -p '#S')}" "AO Master Orch"`
+  (shortened for the 20-char ao cap), and set the full
+  "AO Master Orchestrator" as your Claude Code session title via the
+  send-keys `/rename` mechanics in Repo extensions → Session self-naming.
+- **Every spawn** gets `--name "#<issue> <slug>"` (≤20 chars).
+- **Every spawn prompt** instructs the worker to self-rename per Session
+  self-naming (Repo extensions): on claiming its work item, and again on
+  every queue item transition.
 
 ### Always-running supervision
 

agent-instructions/README.md

@@ -0,0 +1,22 @@
+# agent-instructions
+
+Source fragments for the generated agent instruction files at the repo root
+(`AGENTS.md`, `AGENTS.shared.md`, `CLAUDE.md`, `GEMINI.md`). Never edit the
+generated files — edit the fragments, then regenerate:
+
+```bash
+npm run agents          # rebuild the four repo-root files + length report
+npm run agents:check    # CI-style drift check (exit 1 if generated files are stale)
+npm run agents:system   # rebuild the global $HOME instruction files — see note
+```
+
+Layout (assembled in this order by `scripts/polyscribe.sh`):
+
+- `source/NN-*.md` — shared body fragments, concatenated in numeric order.
+  `30-polypowers.md` is `@sx-managed` (refreshed by nickify) — don't hand-edit.
+- `agent-overrides/{codex,claude,agy}.md` — the per-agent identity appended to
+  that agent's file only.
+- `system/` — **not committed in this repo.** It is seeded by the agent-vault
+  tooling on provisioned accounts; `npm run agents:system` fails on a bare
+  checkout with `missing .../agent-instructions/system` — that's expected, not
+  a bug. The other two scripts work on any checkout.

agent-instructions/source/55-extensions.md

@@ -10,3 +10,22 @@
   a bad change here takes down the whole fleet; a human reviews those merges.
 - **Env:** sessions run with `POLYPOWERS_AUTOMERGE=1` and
   `POLYPOWERS_REPO=polymath-ventures/agent-orchestrator` (project config).
+- **Session self-naming (ao-hosted sessions):** keep your session's name in
+  sync with your current work item so the dashboard and the Claude Code
+  session list read like a live work log. Workers set both surfaces on
+  claiming a work item and again on every queue item transition. Your ao
+  session id is `SID="${AO_SESSION_ID:-$(tmux display-message -p '#S')}"`
+  (ao injects the env var; tmux is the fallback). Derive `<slug>` from the
+  issue title: lowercase `[a-z0-9-]` only, everything else stripped — never
+  interpolate a raw title into a shell command.
+  - ao display name: `ao session rename "$SID" "#<issue> <slug>"` — 20-char
+    cap (enforced at spawn/API; the CLI rename path currently skips the
+    check, so never rely on a longer name sticking). Visible in the
+    dashboard and `ao session get`; the `ao session ls` table doesn't show
+    it yet (gap tracked in GH #28).
+  - Claude Code session title (claude-code harness only):
+    `tmux send-keys -t "$SID" -l '/rename #<issue> <slug>'` then
+    `tmux send-keys -t "$SID" Enter` — verified safe mid-turn. Other
+    harnesses have no title surface; ao display name only.
+  - Never rename the tmux session itself — its name IS the ao session id and
+    ao addresses the pane by it.

agent-instructions/source/60-orchestrator.md

@@ -45,9 +45,20 @@ worker on a deploy.
 
 ### Fleet caps + naming
 
-Hard cap: **4 concurrent workers per project** (check `ao session ls` before
-every spawn; queue the rest). Every spawn gets `--name "#<issue> <slug>"` so
-the dashboard reads like a work log.
+Hard cap: **8 concurrent workers per project** (raised from 4 by Nick,
+2026-07-06; check `ao session ls` before every spawn; queue the rest).
+
+The dashboard and Claude Code session list are the work log — three naming
+duties:
+- **Yourself, at startup:** `ao session rename
+  "${AO_SESSION_ID:-$(tmux display-message -p '#S')}" "AO Master Orch"`
+  (shortened for the 20-char ao cap), and set the full
+  "AO Master Orchestrator" as your Claude Code session title via the
+  send-keys `/rename` mechanics in Repo extensions → Session self-naming.
+- **Every spawn** gets `--name "#<issue> <slug>"` (≤20 chars).
+- **Every spawn prompt** instructs the worker to self-rename per Session
+  self-naming (Repo extensions): on claiming its work item, and again on
+  every queue item transition.
 
 ### Always-running supervision
 

package.json

@@ -2,6 +2,9 @@
 	"name": "agent-orchestrator",
 	"private": true,
 	"scripts": {
+		"agents": "bash scripts/polyscribe.sh",
+		"agents:check": "bash scripts/polyscribe.sh --check",
+		"agents:system": "bash scripts/polyscribe.sh --system",
 		"lint": "cd backend && go test ./... && go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.12.2 run --path-mode=abs",
 		"frontend:typecheck": "npm --prefix frontend run typecheck",
 		"sqlc": "cd backend && go run github.com/sqlc-dev/sqlc/cmd/sqlc@v1.31.1 generate",