fix(sessions): stop pinning the w1-myapp placeholder as Claude's /resume title

[shenlvkang-collab]

Problem

Local Claude spawns pass the tab name as --name (since #243 / 1.16, for cross-session peer names). But --name is also, per claude --help, the name "shown in the prompt box, /resume picker, and terminal title", and a pinned title stops Claude generating its own (/resume shows customTitle ?? aiTitle).

So with the default placeholder names, every conversation of a case lands in /resume as the same w1-myapp / w2-myapp, and none gets Claude's generated title. On one real workspace: 34 of 34 transcripts spawned with --name w<N>-… have a custom-title row and zero ai-title rows; every transcript spawned without it has one. Renaming the tab in Codeman did not help either, because the rename never reached Claude.

Fix

1. Pin only a name the user chose. New Session.cliPinnedName returns the name only when nameSource === 'manual'. It travels to the builders as a separate cliName on CreateSessionOptions / RespawnPaneOptions (and to the direct-PTY buildInteractiveArgs), so the tab / mux name is untouched. Placeholder (w1-myapp) and auto names (w1-myapp: fix the login…) now leave Claude to title the conversation, which restores the generated /resume entry and terminal title.
2. Carry a rename into /resume. PUT /api/sessions/:id/name appends the new name to the conversation's transcript as the {"type":"custom-title"} row that /rename writes (src/claude-session-title.ts). Transcript from the hook-reported path, else findClaudeTranscript. Gated on capabilities.transcript === 'claude-jsonl' and not remote; never creates the file; skips a blank name (an empty customTitle would blank the picker entry instead of falling back). Best effort: a failure logs and the rename still succeeds.

A pane that was spawned with --name re-appends its in-memory title after every turn, so for that case the new name holds from the next spawn (which now pins it). Panes spawned without --name never write a custom-title back, so the appended row sticks immediately.

Trade-off for orchestrators

A worker quick-started with a w<N>- shaped sessionName (e.g. the docs' w9-msgtest) is a placeholder by the existing isGeneratedSessionName rule, so its peer name is now derived. messaging.md and agent-control-plan.md now say to use a descriptive name (msgtest-worker), which is pinned as before.

Tests

• test/claude-resume-title.test.ts: cliPinnedName for placeholder / auto / manual / renamed sessions and the respawn options; appendClaudeCustomTitle appends one row, never creates a file, skips a blank title.
• test/routes/session-name-routes.test.ts: the rename route appends a CJK custom-title with the transcript's conversation id, and writes nothing for a blank name.
• npm test: 405 files passed (the one failure on the first run was cli-registry-no-id-branching catching a mode !== 'claude' I then replaced with the transcript capability). tsc --noEmit, eslint and prettier clean on the touched sources.

🤖 Generated with Claude Code

[Ark0N]

Thanks for this, and for doing the legwork: the diagnosis is right and I reproduced it here before reading the code. claude --help does say --name sets the name shown in the prompt box, the /resume picker and the terminal title, and on my own machine 265 of 407 transcripts carry a custom-title row against 39 with an ai-title, with one --name-spawned transcript holding 64 custom-title rows, which is exactly the re-append-per-turn behaviour you describe. Using capabilities.transcript rather than a CLI id check, and appending the row instead of typing /rename into a live pane, are both the right calls.

Two things I would like fixed before merge.

1. src/web/routes/session-routes.ts:1166: guard on the name actually changing. The route assigns session.name = name and then calls syncClaudeTitle(session) with no comparison. The Session Options name field saves on blur (src/web/public/index.html:1402), and for a placeholder tab it recomposes the identical string: parseSessionPrefix('w1-demo') gives prefix w1-demo with an empty suffix, the input holds that empty suffix, and saveSessionName() builds 'w1-demo' + '' and PUTs it. So a user who clicks into the field and clicks away renames the session to what it already was. That used to be invisible. Now it appends custom-title: w1-demo to the live conversation straight away, putting the placeholder back into /resume, and it flips nameSource to manual, so the next respawn passes --name w1-demo again. Your fix gets undone by an interaction that changes nothing. Capturing the previous name and returning early when it is unchanged covers both halves:

const previous = session.name;
if (name === previous) return { name: previous };

The tab-strip inline rename already guards this way (src/web/public/session-ui.js:3006), so this just makes the two paths agree. A route test that PUTs the same name twice and asserts a single row would pin it.

2. src/web/routes/session-routes.ts:2388: exclude Docker sessions too. The guard excludes session.remote but not session.docker. A Docker-case session runs claude inside the container, whose HOME is /home/agent, so its transcript is never in the host's ~/.claude/projects: every rename there pays a full projects scan for nothing, and with CODEMAN_DOCKER_BRIDGE_HOOKS=1 the in-container hook path is the one case that could resolve to some other host file. || session.remote || session.docker matches the !remote && !docker pairing used elsewhere.

Two smaller things, happy to take them here or in a follow-up:

• skills/codeman/reference/messaging.md:104 now contradicts itself. The paragraph still opens with the live-verified example sessionName: "w9-msgtest" producing peer name w9-msgtest, and three sentences later your warning says a w9- name is exactly what is no longer passed. skills/codeman/reference/endpoints.md:343 still uses "sessionName":"w9-worker" in the quick-start example, and verbs.md:695 still says to pass sessionName to pick the peer name with no caveat. These pages get loaded into agents' context, so the stale example is what fleets will copy. Both plugin mirrors need to stay byte-identical.
• nameSource now decides more than auto-naming (it is what puts --name on the command line), and a rename now writes into Claude's transcript. One line in the "Auto-named sessions" section of CLAUDE.md and docs/architecture-invariants.md would keep the rule files honest; right now the change is recorded only in docs/agent-control-plan.md.

Nits, no action needed unless you want them: RespawnPaneOptions.name is now read by nothing (respawnPane() stopped destructuring it) while its comment still calls it the tab name; the create path (src/session.ts:2293) and the direct-PTY path (:2421) carry cliPinnedName with no test assertion; and the changeset says a rename reaches /resume without the caveat you spelled out in the PR body, that a tab spawned with --name re-appends its own title until the next respawn.

On the trade-off for orchestrators: I am fine with it. The skill joins on the tmux codeman-<id8> column rather than the name, and spawn_worker in the preamble never passes sessionName anyway, so what changes in practice is from-name tagging and readability in ListAgents. There is no way to keep the peer name without also pinning the title, so the title is the right thing to give back to Claude.

Typecheck, lint, format, frontend syntax and the full test gate are all green here (405 files, 7720 tests), same as CI. Push the two fixes and I will merge.