fix(crews): a Crew follows its Captain through every lifecycle step

[bryantderosier]

Important

⚠️ Merge order: merge these in this exact order

This PR is part of the Crews stack. Merge top to bottom, one at a time, and let each land on j5/main before the next. #352 isn't in the stack but has to merge before this PR.

1. fix(crews): Crew notices report only what the platform measured #292: Crew notices report only what the platform measured (adds migration 020) ✅ merged
2. fix(crews): no seat launches into a retired Crew or under a gone Captain #271: No seat launches into a retired Crew or under a gone Captain ✅ merged
3. fix(crews): unit stop and archive finish over a seat that was never created #279: Unit stop and archive finish over a seat that was never created ✅ merged
4. fix(crews): a proposal launches once and reports every seat #313: A proposal launches once and reports every seat (adds migration 021) ✅ merged
5. fix(crews): Crew groups keep seats without thread facts as unknown #300: Crew groups keep seats without thread facts as unknown ✅ merged
6. fix(crews): J5 stream daemons start from the event store's high-water mark #352: J5 stream daemons start from the event store's real high-water mark (fixes fix(crews): J5 stream daemons replay all history on every boot (high-water reads an empty table) #349). Not stacked, but it must merge before this PR.
7. fix(crews): a Crew follows its Captain through every lifecycle step #315: A Crew follows its Captain through every lifecycle step (adds migration 022) ⬅️ this PR
8. feat(crews): custom seats default to Full access and the roster flags seats that will stop #347: custom seats default to Full access

Why #352 goes first: without it the finish notifier's stream starts at sequence 0 and replays every event on boot. This PR's cascade also acts on thread.unarchived, thread.settled, and thread.unsettled, so a restart would settle, unsettle, and restore Crews from history (#349).

Problem

My rule is that there's never a Crew without its Captain (#312). Before this, only archive and delete moved the Crew with its Captain:

• Unarchiving a Captain brought back the Captain alone, and the Crews its archive retired stayed retired with their seat threads archived.
• Settling or unsettling a Captain touched only the Captain, so the Fleet page could show a settled Captain whose seats were still Active.

What I changed

• apps/server/src/j5/a2a/CrewCaptainArchiveCascade.ts → handleStoredEvent:
  • thread.archived/thread.deleted still retire the Captain's live Crews as units. They now pass withCaptain: true, so the Crew records that it retired with its Captain.
  • thread.unarchived → restore: unarchives each archived seat thread, then clears the Crew's retired stamp (restoreWithCaptain), all under crews.serialize. The lifecycle reactor already restores each seat's agent from the thread.unarchived event.
  • thread.settled/thread.unsettled → moveSeats: sends thread.settle to each unsettled seat, or thread.unsettle (reason user) to each settled seat.
• Same file → reconcile (the boot sweep): retires live Crews whose Captain is archived or gone, as j5/main already did. No restart recovery for restore, settle, or unsettle (Jackson, 2026-09-26): each Crew step runs once and a failure is logged.
• Same file → retire, restore, and settle command ids include the triggering event (or, on the sweep, the Captain's archive time), so archive → Undo → archive gets fresh ids. Settle skips seats with a pending request, a live run, or background work, as upstream's auto-settle does. Seat reads go through getThreadProjectionIfPresent.
• AgentCrewInstanceService.ts: markArchived(id, archivedAt, { withCaptain }), listRetiredWithCaptain(captainThreadId?), and restoreWithCaptain(id), which is compare-and-set on retired_with_captain = 1.
• ArchiveCrewService.ts: ArchiveCrewInput.withCaptain is passed through to the store.
• migrations/022_CrewRetiredWithCaptain.ts: retired_with_captain INTEGER NOT NULL DEFAULT 0 on j5_agent_crew_instance.
• Upstream Undo on a Captain's archive, after the upstream sync: the sync withheld upstream's archive Undo notice whenever an archive might retire a Captain's Crews (decision feat: A2 - send deliver reply loop #7, 2026-09-24), because unarchiving the Captain didn't bring them back. This PR makes that unarchive bring them back, so I removed the undoable plumbing: apps/web/src/hooks/useThreadActions.ts → archiveThread is upstream's again, the Sidebar, header menu (useThreadActionMenu.ts), and LegacySidebar.tsx doors call it as upstream does, and archiveFlow.ts drops archiveMayRetireCrews (with its test and archiveUndo.test.ts).
• Docs: docs/j5/product/features/crews.md (the new "A Crew follows its Captain" rule, AC17, AC20, History), fleet-page.md AC28, docs/user/personas.md, and FORK.md case 21.

Why this shape

• The cascade is where the event arrives. Upstream has already committed an archive, settle, or unarchive by the time J5 sees it, from any door (web sidebar, mobile swipe, MCP organize tool). So the one reactor on the stored-event stream carries the Crews along, the same way it already did for archive.
• The flag is needed for unarchive. Without it, the Captain's unarchive would also revive a Crew retired on purpose through Archive crew or archive_crew. Crews retired before migration 022 read as retired on their own, so none of them come back unexpectedly.
• Unsettle only reaches settled seats. thread.unsettle sets the "active" override, which also blocks upstream's automatic settlement. Sending it to a seat that never settled would change that seat's behavior for no reason.
• No restart recovery (Jackson, 2026-09-26). After a server restart the person should expect manual repair (Embed the 2026-09-26 review principles in product, process and agent docs #327). An unarchive that stops partway is repaired by archiving and unarchiving the Captain again, which re-runs restore and skips seats already back.
• I rejected dropping the cascade (the first plan for A Crew's lifecycle follows its Captain #312, where an archive touches one agent). A Crew outliving its Captain has no owner to report to, and the UI would need a place for Crews without a Captain. I rejected that direction.

Invariants

• A Captain's archive, delete, unarchive, settle, and unsettle each move every seat of the Crews it commands. A seat's own lifecycle event commands nothing.
• A Crew restored by the Captain's unarchive is exactly one that retired with that Captain (retired_with_captain = 1).
• A restore stamps the Crew live last, so a restore cut short leaves the Crew retired with its Captain until the Captain is archived and unarchived again.
• Command ids derive from the Captain, the Crew, the seat, the operation, and the triggering event (or the Captain's archive time on the sweep), so a replayed event converges on the same commands while a later archive gets its own.
• A seat is still never archived on its own (FORK.md case 37 is unchanged).

Surfaces

Surface	Decision
Entry points (chat, Settings, command palette, keybinding)	Changed through the server: whichever door archives, unarchives, settles, or unsettles a Captain, the cascade follows the committed event. No client entry point changed.
Clients (web, desktop, mobile)	Unaffected in UI. Mobile's archive and settle swipes are covered because the cascade runs on the server.
Providers	Unaffected because this is thread lifecycle, not provider behavior.
Contracts (packages/contracts)	Unaffected; nothing on the wire changed.
Reverse states	Changed: archive ↔ unarchive and settle ↔ unsettle both reverse for the whole Crew.
Connection modes (local, remote, tunnel)	Unaffected because this is server-side only.
Upstream files / FORK.md	Four upstream web files return to upstream's shape (useThreadActions.ts, useThreadActionMenu.ts, Sidebar.tsx, LegacySidebar.tsx), since the Undo carve-out is gone. FORK.md case 21 describes the wider cascade and the returned Undo.
Docs	Changed: crews.md, fleet-page.md, docs/user/personas.md.

Out of scope

• docs(crews): sync the Crews pages and tool contract with what ships #306 (docs sync) records in crews.md History that "Crews never unarchive as a unit", which was true before this PR. They're in different stacks, so whichever of docs(crews): sync the Crews pages and tool contract with what ships #306 and this PR lands second reconciles that line; I'll do it in the second one's merge.
• Snooze doesn't cascade. I left it out on purpose when I scoped A Crew's lifecycle follows its Captain #312.
• A lone seat still can't be archived on its own. That's my ruling on A Crew's lifecycle follows its Captain #312, so it stays refused.

Upgrade and data

• Migration 022 adds retired_with_captain with default 0. Crews already retired read as retired on their own and aren't restored by a later unarchive of their Captain.
• Migration order in this stack: 020 is fix(crews): Crew notices report only what the platform measured #292's, then 021 in fix(crews): a proposal launches once and reports every seat #313 and 022 here, so fix(crews): Crew notices report only what the platform measured #292 merges first.
• Older clients are unaffected.

Verification

• vp test run apps/server/src/j5 apps/web/src/j5: 1,013 tests pass (1 skipped).
• New tests:
  • Settling a Captain settles only its unsettled seats, a replay converges on the same command id, and unsettling reaches only the settled seat.
  • Unarchiving a Captain unarchives its archived seat threads, skips a never-created seat, and restores the Crew. A seat's own unarchive does nothing.
  • Archive → unarchive → archive retires the Crew again with fresh command ids; settle leaves a busy seat alone; a failed Crew step is tried once and the next Crew still runs.
  • The store restores only a Crew that retired with its Captain, restoring twice is a no-op, and a later archive on its own isn't restorable.
  • The cascade's archive call carries withCaptain: true.
• apps/server and apps/web typecheck with exit 0. Lint is clean on the changed files.

Review focus

• The returned Undo: undoing a Captain's archive relies on the cascade handling thread.archived before thread.unarchived for the same Captain. Both ride the one stored-event stream in order, so the Crews retire and then come back.
• CrewCaptainArchiveCascade.restore: it unarchives seats outside the archive path's per-seat lifecycle service and relies on the lifecycle reactor's thread.unarchived handling to restore each seat's agent. Challenge whether anything else a Crew retirement closes (Exchanges, placement) should reopen.
• moveSeats on thread.settled from upstream's automatic settlement: it gives the seats an explicit settled override, which the settlement sweep itself wouldn't.

Closes #312

Claude Opus 5.5 via Claude Code in J5 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: f6d1063d-2fb8-4dd5-b752-4b25f951ef71

---

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

[Jacksondr5]

[Review panel: Opus 5.5 + Astra] FORK.md: the file-table row for a file this PR edits is stale.

This PR edits apps/web/src/hooks/useThreadActionMenu.ts, but FORK.md's file table still lists it as | A | 19 — deleted orphan hook |. The file exists and differs from upstream pin 67a2be0f by +39/−28, mostly case 21's archiveWithPreflight wrapping of the header archive door, and case 21's text names the file ("header menu (useThreadActionMenu)"). The row predates this PR (it came in with the upstream sync), but this PR edits the file, so it should leave the row accurate: | A | 21 |, since the case-19 note no longer applies.

The rest checks out. useThreadActions.ts is now byte-identical to the pin, so it correctly needs no row. The Sidebar/LegacySidebar/useThreadActionMenu archive: () => archiveThread(threadRef, { onArchived }) calls match upstream's shape, and the case 21 text is accurate.

[Jacksondr5]

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

Docs: missing History line. This PR rewrites docs/j5/product/features/fleet-page.md AC28 (a retired Crew now comes back with its Captain) but adds no line to that file's History. Please add one, and fix "who approved it and why" in the same line while you're there: the roster has no approver (see the comment on #306).

[Jacksondr5]

Heads-up for the register of divergences (added in #329, docs/j5/product/upstream.md): once this PR restores Undo on a Captain's archive, its entry "Archive Undo is withheld when Crews may retire" should be removed, with a History line, and "A Crew follows its Captain" checked against what ships. If #329 lands first, do it in this PR; if this lands first, I'll fold it into #329.

[bryantderosier]

@Jacksondr5 Everything from the panel and your 2026-09-26 decisions is in (1e5fc2a, b2abd86):

• Retire command ids: now include the triggering event, or the Captain's archive time on the sweep, so archive → Undo → archive works. There's a test for it.
• No restart recovery: the startup sweep's restore and settle legs are gone, and so are both retry loops. The sweep that retires an archived or gone Captain's Crews stays.
• Settle cascade: skips seats with a pending runtime request, a live run, or background work. Unsettle is as built.
• Seat reads: go through getThreadProjectionIfPresent.
• Docs:
  • AC18 uses your wording, and the Definition no longer contradicts it.
  • One line says Undo and unarchive don't restore interrupted runs or dropped Exchanges.
  • The repair path for an unarchive that stops partway is documented.
  • fleet-page.md has its History line, and "who approved it and why" became "why it joined" there and in crews.md AC20.
• FORK.md: the useThreadActionMenu.ts row now points at case 21, and case 21 describes the cascade as built.
• docs(j5): agents know what J5 owns and stop before changing upstream's product #329's Undo divergence entry: upstream.md isn't on j5/main yet, so I'll leave that to docs(j5): agents know what J5 owns and stop before changing upstream's product #329 as you offered.

I also merged #313's docs fixes and the latest j5/main. CI is running.

[Jacksondr5]

[Review panel: Opus 5.5 + Astra] Merge prerequisite: the cascade's stream replays all history on every boot (#349).

This bug is already on j5/main, not introduced here. CrewSeatFinishNotifier starts the stream this cascade rides from MAX(sequence) FROM orchestration_v2_events, and since the upstream sync that table is always empty; events live in orchestration_events. So every boot feeds the whole event history through CrewCaptainArchiveCascade.handleStoredEvent.

On j5/main this already retires live Crews: Astra reproduced a restart that replayed an old Captain archive, which retired 2 Crews and archived 4 seats while the Captain stayed live (details in #349).

This PR widens the damage, because the cascade now also acts on replayed thread.unarchived, thread.settled, and thread.unsettled. With command ids derived from the event id, every historical event this cascade never handled gets fresh commands on the first boot after merge. Old Captain settles and unsettles would then override a person's later per-seat choice, and an old unarchive can briefly restore a Crew with retired_with_captain = 1 under a Captain that is archived now.

Please land the #349 fix before this merges, or in this PR: take the high-water mark from the event store's latestSequence(). Everything else on this PR's round-one threads verifies; replies follow.

[Jacksondr5]

[Review panel: Opus 5.5 + Astra] Verified in b2abd86:

• FORK.md (round one): the useThreadActionMenu.ts row now reads A | 21. Case 21 describes the cascade as built and says unarchive, settle, and unsettle have no restart recovery.
• fleet-page.md (round one) has its History line, and "who approved it" became "why it joined" there and in crews.md AC20.

The one open item on this PR is the #349 merge prerequisite above.

[Jacksondr5]

[Review panel: Opus 5.5 + Astra]

Round-two web verification: archive → Undo → archive retires the Crew again. Undo and Settings unarchive restore the Crew and its seats. Before/after use the same seeded Crew, light theme, and 1440×1000 viewport.

After archiving a Captain — before: no Undo control.

After archiving a Captain — after: Undo is available.

Settings unarchive — before: the Crew remains retired.

Settings unarchive — after: the Crew and all three seats are restored in Fleet.

Watch archive → Undo → archive.

Busy-seat check also passes: settling the Captain skipped a running seat and a seat awaiting approval, settled the idle seat, and unsettling the Captain reached only the settled seat.

Restart remains FAIL due to #349, already posted as a merge prerequisite. The removed settle sweep is fixed, but the legacy high-water query replays old lifecycle events. The paired baseline screenshots used a test-only cursor marker to isolate UI behavior from that replay; the main archive/Undo and busy-seat tests used the unmodified review tip.

[bryantderosier]

@Jacksondr5 The #349 fix is up as #352. The finish notifier and the launch reporter now start their streams, and SilenceDetector seeds its cursor, from EventSinkV2.latestSequence(). A failed read retries and never falls back to 0, and there are regression tests for each. I'll hold #315 until #352 merges, and I've added that to its merge-order banner. #313 and #300 have merged, so I'm bringing #315 up to date with j5/main now.

[Jacksondr5]

Posted by an AI agent on Jackson's behalf.

Approved. The review panel (Opus 5.5 + Astra) verified every round-one finding, in code and live on a copy of real data, with evidence on this PR:

• archive → Undo → archive retires the Crew again;
• settling a Captain skips busy seats, and unsettling reaches only settled ones;
• the startup restore and settle steps and the retry loops are gone;
• AC18 uses Jackson's wording.

The only new commit since the review is the merge of j5/main after #292, #313 and #300 landed.

Merge after #353 (the #349 restart-replay fix). Without it, a restart replays history through this cascade too, including unarchive, settle and unsettle.

[Jacksondr5]

Posted by an AI agent on Jackson's behalf.

Correction to the approval above: the #349 fix to merge first is #352 (Bryant's), not #353, which was a duplicate and is closed. Merge #352 first, then this PR.