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

apps/server/src/j5/a2a/CrewProposalService.ts

@@ -732,7 +732,8 @@ export const layer = Layer.effect(
         const resolved = yield* resolveRuntime(captain, seats);
         if (input.approvalToken !== crewApprovalToken(proposal, captain, resolved))
           return yield* new CrewProposalRequestError({
-            detail: "The crew runtime preview is missing or has changed since it was shown.",
+            detail:
+              "The crew runtime preview is missing or has changed since it was shown: the roster, a seat's runtime, or the Captain's branch or worktree may have changed.",
             nextStep: "Refresh the preview and review the current settings before approving.",
           });
         const claimed = yield* claim(proposal, "approve", seats);

docs/j5/product/features/crews.md

@@ -47,7 +47,7 @@ The platform ships the machinery — propose, gate, spawn, render, remind, notif
 
 1. Asking for a Crew in ordinary chat causes the current agent to propose a roster before doing the delegated work. The thread retains its persona, model, and policy; saved personas are optional and there is no Crew slash command.
 2. A roster proposal renders inline above the Captain's composer; the person can remove seats, add personas from the library or a custom seat (Custom crew member is the first choice; it takes a name and required instructions, and exposes editable harness, model, reasoning, and access controls), then approve the final roster or decline.
-3. Initial roster and Inbox addition cards show every seat's saved definition or custom-seat choice, instructions, harness, model, reasoning level, and access; the Captain's reason for a seat is read in that seat's edit dialog. Editing the roster or any member’s runtime setting refreshes the server preview. Missing, unavailable, or stale previews cannot approve a launch; approval launches the exact validated runtime configuration, including advertised defaults.
+3. Initial roster and Inbox addition cards show every seat's saved definition or custom-seat choice, instructions, harness, model, reasoning level, and access; the Captain's reason for a seat is read in that seat's edit dialog. Editing the roster or any member’s runtime setting refreshes the server preview. The preview also binds the Captain's project, branch, worktree, and interaction mode, so changing any of them needs a fresh preview. Missing, unavailable, or stale previews cannot approve a launch; approval launches the exact validated runtime configuration, including advertised defaults.
 4. A seat naming an agent missing from or disabled in the library, a duplicate seat name, or a roster past twelve seats is refused to the Captain with the next step, before anything spawns; prose is never parsed.
 5. Filing a proposal or a seat request is itself the human gate and works under every sandbox and approval policy, including Codex approval policy `never`.
 
@@ -114,4 +114,5 @@ The platform ships the machinery — propose, gate, spawn, render, remind, notif
 - 2026-09-18 — the recovery path after Jackson's third and fourth rounds: a decline cleans up before it is recorded and releases every row its proposal minted; a retry retires seats the person dropped or renamed; every resolution claims the gate first (`approving`, `declining`) so two devices cannot undo each other, with a boot sweep settling a claim the server lost; only a genuine not-found reads as a missing seat thread; the sidebar poll re-reads every row still showing a chip so a retired Crew's Captain clears (Bryant; [record](../../worklog/2026-09-16-crew-command-decoupling.md)).
 - 2026-09-18 — one launch report after Jackson's dogfood: the approved gate notice waits until every seat has started or failed to start, names what the person changed against the proposal and each seat's outcome with the run's error, and a boot sweep reports a launch the server lost; a failed first turn is a launch outcome, not a finish; the finish notice leads with how the run ended and carries the error; the silence detector stays quiet about a seat failure its Captain already hears; a dead seat reads as failed on the Fleet row and the expander; the spawn-time refusal names its reason (Bryant; [record](../../worklog/2026-09-16-crew-command-decoupling.md)).
 - 2026-09-16 — `/crew` decoupled from the `crew-captain` saved agent: the command sends the brief with the platform's crew-composition guidance to whatever agent the thread runs as, from a fresh draft or an existing thread, and the bundled example is retired; a Captain may command several Crews at once, each a named, collapsible group with its own Stop on the sidebar expander (Bryant; [record](../../worklog/2026-09-16-crew-command-decoupling.md)).
+- 2026-09-24 — AC3 states that the approval preview binds the Captain's project, branch, worktree, and interaction mode, so a branch switch needs a fresh preview ([#231](https://github.com/Jacksondr5/j5code/issues/231)).
 - 2026-09-24 — the J5 document is named "handoff artifact" to distinguish it from upstream's context handoffs.

docs/user/personas.md

@@ -46,7 +46,7 @@ A crew is a group of agents that one agent, the Captain, runs as a unit for one
 
 > Put together a crew to follow @docs/runbooks/release.md for the 2.4 release and report back when the PR is green.
 
-The agent uses the conversation to propose a roster above the composer. Each member has a responsibility, a reason for joining, and instructions. Members may use saved personas or be custom agents created for this task. You can remove members, add a saved persona, or add a custom seat with a name and instructions, then approve or decline. Custom members start with the Captain's runtime settings. Before approval, you can change their harness, model, reasoning level, and access, whether the agent proposed the member or you added it manually. Selecting a saved persona uses that persona's configured runtime policy. No special Captain persona is needed, and one Captain can coordinate several crews in the same conversation. Before you approve, each member shows its resolved harness, model, reasoning level, and access. Changing the roster refreshes these details. If the configuration changes before launch, review the refreshed settings and approve again.
+The agent uses the conversation to propose a roster above the composer. Each member has a responsibility, a reason for joining, and instructions. Members may use saved personas or be custom agents created for this task. You can remove members, add a saved persona, or add a custom seat with a name and instructions, then approve or decline. Custom members start with the Captain's runtime settings. Before approval, you can change their harness, model, reasoning level, and access, whether the agent proposed the member or you added it manually. Selecting a saved persona uses that persona's configured runtime policy. No special Captain persona is needed, and one Captain can coordinate several crews in the same conversation. Before you approve, each member shows its resolved harness, model, reasoning level, and access. Changing the roster refreshes these details. If the configuration changes before launch, review the refreshed settings and approve again. The preview also covers the Captain's branch and worktree, so switching the Captain's branch before you approve means reviewing a fresh preview. A member on an ACP registry harness offers only **Approval required** and **Full access**, because those harnesses can't enforce **Accept edits** or **Auto**.
 
 Members can talk directly to each other and their Captain, and Captains can coordinate with other Captains. They share findings, questions, blockers, and results as messages while work continues; creating a report is not a prerequisite for communication. Active Astra runs can receive peer messages during work; other providers receive queued messages at the next safe turn boundary.