docs(crews): say why a preview goes stale and why ACP seats lack auto modes

[bryantderosier]

Problem

Two correct behaviors at the roster gate surprised a person the first time (#231). The approval preview token binds the Captain's project, branch, worktree, and interaction mode (crewRuntimePreview.ts), so switching the Captain's branch between preview and approval failed with "preview has changed" and nothing said why. And seats on an ACP registry harness can't use Auto-accept edits or Auto, because the harness can't enforce them, but the seat editor hid those options without explanation.

What I changed

• docs/j5/product/features/crews.md AC3: one sentence that the preview binds the Captain's project, branch, worktree, and interaction mode, plus a History line.
• docs/user/personas.md, Crews section: one sentence each for the branch binding and the missing access modes on ACP harnesses.
• apps/server/src/j5/a2a/CrewProposalService.ts: the stale-preview refusal names the roster, a seat's runtime, and the Captain's branch or worktree as what may have changed. Message text only.

Why this shape

The binding is correct: approval must launch exactly what was shown. So the fix is saying why, in the card message the person already sees and in the docs, not changing the behavior.

Invariants

• No behavior change; the refusal still fires on the same token mismatch.

Surfaces

Surface	Decision
Entry points (chat, Settings, command palette, keybinding)	Unaffected.
Clients (web, desktop, mobile)	The card shows the server's message, so web and desktop get the clearer text with no client change.
Providers	Unaffected.
Contracts (packages/contracts)	Unchanged.
Reverse states	n/a.
Connection modes (local, remote, tunnel)	Unaffected.
Upstream files / FORK.md	None.
Docs	crews.md AC3 and History, docs/user/personas.md.

Out of scope

None. #344 has merged, so the seat editor, the server's ACP seat error, and this PR's user-guide sentence all use upstream's names (Supervised, Auto-accept edits).

Upgrade and data

None.

Verification

• CrewProposalService.test.ts: 15 passed. No test pins the message text, and I didn't add one that would only mirror the string.
• Server typecheck clean.

Review focus

• Whether the refusal should also name the interaction mode. I kept it to the causes a person can actually change from the card.

Closes #231

Claude Opus 5.5 via Claude Code

🤖 Generated with Claude Code

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Repository: Jacksondr5/j5code/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 7bfb6000-be09-43c4-af56-d07a5cea15de

---

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

[Jacksondr5]

[Review panel: Opus 5.5 + coordinator (Opus 5.5)]

Rebase needed. The CrewProposalService.ts hunk conflicts with #313, which rewrites resolve. On #313's branch the stale-preview refusal still carries the old text, so re-apply the new message after rebasing.

Docs: the new crews.md History line has no attribution, while every other line names who decided and links a record; suggest "(Bryant; #231)". It also sits after the out-of-order 2026-09-16 line. Once #306 restores date order, it belongs with the other 2026-09-24 lines.

[Jacksondr5]

Decision (Jackson, 2026-09-26): use upstream's access-mode names everywhere. Upstream's composer labels the modes Supervised, Auto-accept edits, Auto and Full access. J5's copies say "Approval required" and "Accept edits". Please fold the rename into this PR, since it's the same topic:

• apps/web/src/j5/crew/crewSeatRuntime.ts CREW_ACCESS_OPTIONS: use upstream's labels and descriptions verbatim ("Ask before commands and file changes.", "Auto-approve edits, ask before other actions.", …). Keep the J5 copy rather than exporting upstream's module-private list: an upstream edit isn't worth it.
• The server strings that name the mode: crewRuntimePreview.ts ("Approval required") and both ACP messages in CrewLaunchService.ts ("Choose Approval required or Full access" → "Choose Supervised or Full access").
• The docs: docs/user/personas.md and crews.md should use Supervised and Auto-accept edits, so the "Out of scope" note in this PR's description goes away.

[bryantderosier]

@Jacksondr5 An update on #307:

• History attribution: added "(Bryant; Document the approval token's branch binding and the ACP access restriction #231)". The line moves into date order with the other 2026-09-24 lines once docs(crews): sync the Crews pages and tool contract with what ships #306 restores that order.
• Access-mode rename: I agree with the rename, but I've done it as its own PR, fix(crews): use upstream's access-mode names #344, because it's UI labels and server strings rather than docs. It uses upstream's labels and descriptions verbatim in CREW_ACCESS_OPTIONS, and "Supervised" in the runtime preview and both ACP messages. Once fix(crews): use upstream's access-mode names #344 lands, this PR's docs take the new names and the "Out of scope" note goes.
• Rebase against fix(crews): a proposal launches once and reports every seat #313: the CrewProposalService.ts conflict gets resolved in whichever of docs(crews): say why a preview goes stale and why ACP seats lack auto modes #307 and fix(crews): a proposal launches once and reports every seat #313 lands second, and then I'll re-apply the new stale-preview message.

I merged the latest j5/main.

[Jacksondr5]

[Review panel: Opus 5.5 + coordinator (Opus 5.5)]

Round two, at 8077983:

• History attribution: verified. The line ends "(Bryant; #231)". Moving it into date order waits on docs(crews): sync the Crews pages and tool contract with what ships #306, as you say.
• Rebase against fix(crews): a proposal launches once and reports every seat #313: still pending. Resolving it in whichever of docs(crews): say why a preview goes stale and why ACP seats lack auto modes #307 and fix(crews): a proposal launches once and reports every seat #313 lands second is fine. Re-apply the new stale-preview message there.
• Access-mode names: still pending in the docs. The split into fix(crews): use upstream's access-mode names #344 is accepted. fix(crews): use upstream's access-mode names #344 must merge before docs(crews): say why a preview goes stale and why ACP seats lack auto modes #307. After that, this PR's docs/user/personas.md sentence should read "offers only Supervised and Full access, because those harnesses can't enforce Auto-accept edits or Auto", and the "Out of scope" note in the description goes away. Until then, merging docs(crews): say why a preview goes stale and why ACP seats lack auto modes #307 would ship a user doc that names modes the app no longer shows.

[bryantderosier]

@Jacksondr5 Agreed on all three. Nothing changes here until #344 and #313 merge. After #344, I'll change the docs/user/personas.md sentence to "offers only Supervised and Full access, because those harnesses can't enforce Auto-accept edits or Auto", and I'll drop the Out-of-scope note. #313 is merging now, so I'll resolve the CrewProposalService.ts conflict here and re-apply the new stale-preview message. #307 won't merge before either of those.