Skip to content

feat(j5): a Captain can replace a crew seat - #935

Merged
Jacksondr5 merged 8 commits into
feat/persona-model-switchfrom
feat/crew-seat-replacement
Nov 8, 2026
Merged

Jacksondr5 merged 8 commits into
feat/persona-model-switchfrom
feat/crew-seat-replacement

Conversation

@bryantderosier

@bryantderosier bryantderosier commented Nov 6, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

A Crew member sometimes needs to run on a different model. The usual case is a reviewer whose model just wrote the work it's about to review. A Captain could add a new member, but the new member couldn't take over the old one's Playbook steps, because a step has exactly one owner and an addition can only claim unowned steps. Now j5_request_crew_member takes an optional replaces (a seat name), and the new member takes the seat over. Closes #784.

  • Launch first, then move. Additions normally reserve their roster row before they spawn, and the member table is keyed by (crew, seat name). So a replacement doesn't reserve anything:
    • Under the Crew's lock, it checks that the old seat is still a live member and that the new name is free apart from that seat. Then it spawns the new member.
    • Only once the new member's thread exists does one store write (replaceMember) do the swap. It moves the replaced seat's unfinished steps to the new member, moves the old row into the new j5_agent_crew_replaced_member table with the steps it finished and who replaced it, puts the new member at the old member's position, and bumps the version.
    • This is safe because a seat with no membership can't be messaged (CrewSeatInactiveError). A failed launch writes no roster rows, and the original keeps its steps and keeps running.
  • Unfinished steps are the run's current step plus every later step the seat owns, in the live order. They're read inside the locked swap, right before it, so a step call that moved the run while the replacement waited for the Crew is accounted for. The new member's brief lists the same steps. If there's no active run, every step it owns moves. If the run's definition can't be read, the replacement is refused, because the server can't tell which steps are finished.
  • After the swap:
    • The old member's turn is interrupted with stopThread, the same helper j5_stop_agent and Crew stop use, with no message to it.
    • A current step it held is handed to the new owner by the new PlaybookCrewRelay.handOver. That's a reselect of the current step, the same path j5_playbook_reselect takes. If the hand-off to the old thread is still pending, it's marked skipped first, so a drain can't send the step to the retired member.
    • The stop and the hand-off are both keyed by the request, so retrying the same client_request_id finishes whichever one didn't happen.
  • The replaced member is a plain agent until its Crew is archived. Its row has left j5_agent_crew_member, so findMembership returns null. It doesn't count toward the cap and gets no Crew deliveries or finish notices. Its thread and finished steps stay readable. Archiving the Crew archives it too, and cleans up its worktree like a seat's. Unarchiving the Captain brings its thread back, but it stays replaced.
  • Who it's held to. The new member is an agent pick, so Personas: agents pick personas, and who picked sets the limits #781's access cap applies. For Personas: reviewers prefer a different model from the author #782, the Crew default for a reviewer's authors now includes replaced members that weren't flagged reviewers, because their work is still in the Crew's. reviews may name a replaced seat.
  • Continuity. The new member's brief ends with "You replace seat X, which ran on M. Its thread is T; read it with t3_thread_read before continuing." Its playbook block lists the steps it took over.
  • Refusals name the reason: an unknown seat, an already replaced seat, or the Captain itself ("a Captain can't replace itself").
  • Contracts and web. FleetAgent and SpawnedChild get an optional replaced (crewName, seat, replacedBy). The Fleet row and the Captain's expander show the replaced member as "Replaced by ", with the new member in the Crew. Mobile shows Crew members as ordinary agents, so nothing changes there.
j5_request_crew_member(replaces)
  └─ CrewProposalService.requestMember   validate replaces (unknown / replaced / Captain)
     └─ … fulfil → unfinishedSteps(run) → CrewLaunchService.addSeats(replacement)
        └─ replaceSeat  [Crew lock]  re-check → spawn → crews.replaceMember (one write)
  └─ finishReplacement  stopThread(old) → relay.handOver (reselect current step if old held it)

The model-facing text changed: the j5_request_crew_member description, the replaces parameter, and one sentence of Captain guidance in orchestrationInstructions.ts. I ran the 33 Claude orchestration cases on Sonnet 5.5, and 62 of 68 samples passed, for about $4.09. Three cases failed some samples. opus-review-too-via-delegate failed 0/2, the known flake, and it's also 0/2 on base. delegates-then-new-thread-with-model and review-followup-ask-sol-to-confirm each passed 1/3. I re-ran those two at 4 samples each on head and on base (a85bc9f), and they scored the same on both (3/4 and 4/4), so they're existing flakes, not regressions. Total eval spend was about $5.31.
node --env-file-if-exists=../.env mcp-tool-use/run.ts --model claude-sonnet-5-5 --cases mcp-tool-use/cases/orchestration.jsonl --out runs/784-sonnet (from evals/)

UI changes

Cropped from 1280x800 on the head test server. Before is the Crew just after launch, and after is the same Crew once the Captain replaced the reviewer:

Before After
Captain's expander under the Captain Captain's expander under the Captain, before Captain's expander under the Captain, after
Fleet rows for the Crew Fleet rows for the Crew, before Fleet rows for the Crew, after

From Jackson's live test of the stack: a replaced member that had finished a run still showed its green Completed in the expander. It now always says who replaced it (6fe827f). The after is from my test home, captured at 6fe827f, where the replaced member never ran, so it shows the label but not a run status being overridden.

Before After
Replaced member in the Captain's expander Replaced member in the Captain's expander, before Replaced member in the Captain's expander, after

Live testing

Partial, at d8847f6, on setup-agent-live-test.ts --base origin/feat/persona-model-switch. I sent two Captain turns on Claude Haiku 5.5, and each was followed by the Captain's automatic launch-report turn.

  • Live: I asked for a builder and reviewer crew and approved the card. Then I asked in plain words to "replace the reviewer with a new reviewer member". The Captain called j5_request_crew_member with replaces:
    • The old reviewer's row landed in j5_agent_crew_replaced_member.
    • The new reviewer took ordinal 1 at version 2, reusing the seat name.
    • The server trace shows the thread.stop.
    • Fleet and the expander show the old member as "Replaced by reviewer", outside the Crew group.
  • Not live: a playbook Crew (steps moving and re-delivery), a failed launch, and the reviewer preference. Those are covered by the tests under Evidence.
  • The "before" captures are from head just before the replacement, not from base. Base can't produce a replaced member, and without one, head and base render these rows the same.

Evidence

  • CrewProposalService.test.ts, "a Captain replaces a seat: its unfinished steps, its current step and its turn move to the new member". This goes through the real launcher and a real playbook run at step build:
    • Refused: an unknown seat, replaces: "captain", and a seat above the Captain's access. Each refusal changes nothing.
    • A launch whose home can't be recorded leaves the roster exactly as it was and stops nobody.
    • planner → planner-2: only the unfinished review moves, and plan stays on the replaced row. The old thread gets one thread.stop, and the new member gets no step notice, because build isn't its step. Its brief names the old seat, its model and its thread, and lists review.
    • Replacing planner again is refused as already replaced.
    • builder → builder (same name): the new member owns build, gets exactly one step notice, and the run reports it as holding the step. Retrying the call sends nothing new, and the old builder is no longer a member.
  • CrewProposalService.test.ts, "a replacement on a Crew without a playbook is an addition and a stop".
  • CrewProposalService.test.ts, "a replacement takes the steps unfinished when it gets the Crew, not when it asked". A next holds the Crew's lock with the run at plan while the replacement asks and waits for the lock. Once the run moves to build, plan stays on the replaced row and only review moves. This failed on d8847f6, where plan moved too.
  • CrewProposalService.test.ts, "a retry after a replacement's stop failed finishes the stop and hand-off once". The swap lands and then the stop fails. Retrying the same request twice stops the old builder under one command id and hands build over exactly once, with no second swap and no version bump.
  • AgentCrewInstanceService.test.ts:
    • "swaps a replacement in for a seat, moving only its unfinished steps": the moved and kept steps, the version bump, findMembership, the cap no longer counting the old member, idempotent replay, and that it stays out after an unarchive.
    • "refuses a replacement that would give a step two owners, writing nothing".
  • PlaybookCrewRelay.test.ts:
    • A step already handed to the predecessor is handed to the replacement once.
    • A hand-off still pending toward the old thread goes to the replacement and never to the old thread.
    • A step not yet reached goes to the replacement when the run gets there.
  • CrewLaunchService.test.ts, "a reviewer added after a builder was replaced avoids both builders' models": terra (old) and sol (new) are both avoided, so the reviewer lands on luna.
    vp test run src/j5/a2a/CrewProposalService.test.ts src/j5/a2a/AgentCrewInstanceService.test.ts src/j5/playbooks/PlaybookCrewRelay.test.ts src/j5/a2a/CrewLaunchService.test.ts (from apps/server)
  • From the review, CrewProposalService.test.ts. Each of these fails without its fix:
    • "of two replacements of one seat, the second is refused and its request declined": the second request is told "Seat reviewer was already replaced." and no request stays open.
    • "a step claimed while a replacement waits for the Crew refuses it before it spawns": a scribe claims review while the replacement waits for the lock, and the replacement is refused with no thread.create.
    • "two replacements on a full Crew both go through": at 12 seats, both swaps land while the first is still an open request.
    • The main replacement test now also checks that a replacement that never got its home archives the thread it created.
  • ArchiveCrewService.test.ts, "archives a replaced member with its Crew and cleans up its worktree like a seat's": the confirmation lists critic (replaced) beside the seats, its turn is interrupted under its own command id, and its thread is archived and its worktree cleaned up.
  • CrewCaptainArchiveCascade.test.ts, "unarchiving a Captain brings a replaced member's thread back, still replaced". The store test above checks that it stays off the roster after the unarchive.
  • vp run check:changed at 6fe827f, on feat(j5): people can switch a persona worker's model #934's 4fd8a2a: format, lint, knip, typecheck (32 packages) and tests (34 files) all pass.

Not verified:

  • On a live server I only replaced a seat on a Crew without a playbook. Moving steps, re-delivery, a failed launch and the reviewer preference are covered by the tests above, not live.
  • Mobile has no changes and wasn't run.
  • If the server crashes between the swap and the stop, the old member's running turn keeps going until the Captain retries the same call. I accepted that rather than adding a sweep.

Merge Danger

Door: one-way, in a small way. Migration 052 adds a table. After a revert, replaced members' rows stay in that table and nothing reads them. Those members stay off their Crews, which is the state they were left in.

Blast Radius: Crew additions. The new path only runs when replaces is set. Additions without it go through the same reservation path as before. The reviewer-author change affects reviewers added to a Crew that has replaced members.

After merge: nothing.

Checklist

  • One concern: the description has no "also"
  • Tests cover the changed behavior (backend changes ship with focused tests)
  • UI changes: before/after screenshots above, and a video for motion or interaction (no motion)
  • Live testing: the section above says what ran live and what did not
  • Upstream-owned files: each one is recorded in FORK.md (case text and file-table row) in this PR (none touched)
  • Upstream product: any change to what upstream's product does has a human decision linked above and a register entry in docs/j5/product/upstream.md (none)
  • Surfaces: entry points, clients, providers, contracts, reverse states, connection modes (see AGENTS.md)
  • Docs: definitions under docs/j5/product/ and user docs rewritten where this changes them

Claude Opus 5.5 in J5 Code (Claude Code harness).

🤖 Generated with Claude Code

@bryantderosier bryantderosier added the enhancement New feature or request label Nov 6, 2026
@bryantderosier bryantderosier self-assigned this Nov 6, 2026
@vercel

vercel Bot commented Nov 6, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
j5-code Ready Ready Preview Nov 7, 2026 11:19pm UTC

Request Review

bryantderosier added a commit that referenced this pull request Nov 6, 2026
@github-actions github-actions Bot added the vouch:trusted PR author is trusted by repo permissions or the VOUCHED list. label Nov 6, 2026
@bryantderosier
bryantderosier added this pull request to stack #933 November 6, 2026 16:17
@github-actions github-actions Bot added the size:XL 500-999 effective changed lines (test files excluded in mixed PRs). label Nov 6, 2026
@bryantderosier
bryantderosier marked this pull request as ready for review November 6, 2026 17:09
@coderabbitai

coderabbitai Bot commented Nov 6, 2026 •

Copy link
Copy Markdown

Warning

Review limit reached

  • Run on-demand review

This review includes 27 billable files and costs up to $6.75.

Or wait 38 seconds for your next included review.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration

Commits

Reviewing files that changed from the base of the PR and between 67d58e8 and 488c697.

Files selected for processing: 27

  • apps/server/src/j5/a2a/AgentCrewInstanceService.test.ts
  • apps/server/src/j5/a2a/AgentCrewInstanceService.ts
  • apps/server/src/j5/a2a/AgentCrewProposalService.ts
  • apps/server/src/j5/a2a/ArchiveCrewService.test.ts
  • apps/server/src/j5/a2a/ArchiveCrewService.ts
  • apps/server/src/j5/a2a/CrewCaptainArchiveCascade.test.ts
  • apps/server/src/j5/a2a/CrewCaptainArchiveCascade.ts
  • apps/server/src/j5/a2a/CrewLaunchService.test.ts
  • apps/server/src/j5/a2a/CrewLaunchService.ts
  • apps/server/src/j5/a2a/CrewProposalService.test.ts
  • apps/server/src/j5/a2a/CrewProposalService.ts
  • apps/server/src/j5/a2a/Migrations.test.ts
  • apps/server/src/j5/a2a/Migrations.ts
  • apps/server/src/j5/a2a/fleetRead.ts
  • apps/server/src/j5/a2a/mcp/handlers.ts
  • apps/server/src/j5/a2a/mcp/tools.ts
  • apps/server/src/j5/a2a/migrations/053_CrewSeatReplacement.ts
  • apps/server/src/j5/a2a/spawnedChildrenRead.ts
  • apps/server/src/j5/playbooks/PlaybookCrewRelay.test.ts
  • apps/server/src/j5/playbooks/PlaybookCrewRelay.ts
  • apps/web/src/j5/fleet/FleetPage.tsx
  • apps/web/src/j5/threads/SpawnedChildren.tsx
  • docs/j5/product/a2a/agent-tools.md
  • docs/j5/product/features/crews.md
  • docs/j5/user/personas.md
  • packages/contracts/src/j5.ts
  • packages/provider-core/src/j5/orchestrationInstructions.ts
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

@tyler-barton-horizon tyler-barton-horizon left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Automated review of this layer of stack pingdotgg#933 (diff against its base branch). Findings were not individually verified against the source, so please treat them as likely issues and push back on any that are wrong.

apps/server/src/j5/a2a/ArchiveCrewService.ts:340 (not in this diff): Archive and cleanup loop only over instance.members, so replaced members (now in j5_agent_crew_replaced_member) are never archived and their crew worktrees are never cleaned up when the Crew retires.

🤖 Generated with Claude Code

};
const owned = stepOwnershipConflict(
id,
current.members.filter((member) => member.seatName !== old.seatName),

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A replacement can claim steps the replaced seat already finished, so one step ends up owned by both.

Seat builder owns [plan, build, test] and the run is at test. The Captain replaces it with steps: ["build"]. Validation (withoutReplaced / memberSteps(live)) and stepOwnershipConflict both pass. The replaced row keeps [plan, build] and the new member owns [build, test], which breaks 'every step keeps one owner', and a later reselect of build goes to the new member.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The replaced row is a record of what that member finished; it isn't an owner any more. Ownership is only the live roster, which is what the relay and the one-owner check read, so build has one owner, the new member. Sending a later reselect of build there is intended. Leaving this as is.

Comment thread packages/contracts/src/j5.ts Resolved
Comment thread apps/web/src/j5/fleet/FleetPage.tsx Resolved
@bryantderosier

Copy link
Copy Markdown
Collaborator Author

On the review-body note about ArchiveCrewService (not in this diff): not archiving a replaced member with its Crew is intended, since it's a plain agent after the swap. The worktree point is fair, though. Crew archive now includes replaced members' J5-created worktrees in its cleanup, under the same rules as seats. That means a replaced member's worktree goes once its own thread has been archived, because cleanup never pulls a worktree out from under a live thread. Fixed in 25b8368.

@bryantderosier

Copy link
Copy Markdown
Collaborator Author

Follow-up on the ArchiveCrewService note: I changed course after looking at the cleanup rule. Archiving a Crew now takes its replaced members with it. They're listed beside the seats as " (replaced)" with any running turn or open ask, their turns get interrupted, and their J5-made worktrees are cleaned up just like a seat's. Unarchiving the Captain brings their threads back too, but they stay replaced. Done in c884bee.

@github-actions github-actions Bot added size:XXL 1,000+ effective changed lines (test files excluded in mixed PRs). and removed size:XL 500-999 effective changed lines (test files excluded in mixed PRs). labels Nov 6, 2026
@bryantderosier

Copy link
Copy Markdown
Collaborator Author

Restacked onto #934's head (2c968db); no changes beyond fitting the lower layers' review fixes.

@bryantderosier
bryantderosier force-pushed the feat/crew-seat-replacement branch from c884bee to 9068716 Compare November 6, 2026 23:22
@github-actions github-actions Bot added size:XL 500-999 effective changed lines (test files excluded in mixed PRs). and removed size:XXL 1,000+ effective changed lines (test files excluded in mixed PRs). labels Nov 6, 2026
@bryantderosier

Copy link
Copy Markdown
Collaborator Author

Restacked onto #934's head (4fd8a2a) for #931's code-block mention fix; no other changes.

bryantderosier and others added 8 commits November 7, 2026 17:56
j5_request_crew_member takes an optional `replaces`. The new member launches
first; only after it exists does one store write move the replaced seat's
unfinished playbook steps to it and move the old member to
j5_agent_crew_replaced_member (migration 052). The old member's turn is then
interrupted with stopThread, and a current step it held is handed to the new
owner through a relay reselect. A failed launch moves nothing. Replaced
members still count as authors for independent reviewers, and Fleet and the
Captain's expander show them as "Replaced by <new member>".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The steps a replacement takes over were read before the addition took the
Crew's lock, so a playbook move that held the lock meanwhile left them stale:
an advance moved a finished step, and a back left an unfinished one on the
retired member. They are now read inside the locked swap, and the new member's
brief lists the same steps. Adds a test for that race and one for retrying a
replacement whose post-swap stop failed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…keeps

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The re-check under the Crew lock now refuses as a seat error, so a second
replacement of the same seat is declined instead of staying open. The new
seat's own step claims are checked there too, before anything spawns. A
replacement whose thread was created but never got its home archives that
thread. The moved steps are computed once, and a replacement skips the
admission cap since it never grows the Crew.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Members the Captain replaced keep the worktree J5 made for their seat. A
Crew's archive now looks at those worktrees under the same rules as seats,
without archiving the replaced members' threads. The docs say so, and the
user doc now says finished steps stay with a replaced member only for the
current run.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A member the Captain replaced stays a plain agent until its Crew is archived.
Then the Crew's archive takes it too: it's listed beside the seats as
"<seat> (replaced)" with its running turn and open asks, its turn is
interrupted, and its J5-made worktree is cleaned up like a seat's. Fleet's
Archive crew dialog lists it. Unarchiving the Captain brings its thread back
with the Crew's, but it stays replaced and off the roster.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
In the Captain's expander, a replaced member's row showed its last run status
(a green Completed, say) instead of who replaced it, because the label only
rendered when there was no status. Being replaced now takes precedence over
the run status in that row.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@Jacksondr5 Jacksondr5 left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved as part of the persona stack (#931 → #938), reviewed and live-tested as one unit. Details on #938.

@Jacksondr5
Jacksondr5 merged commit 499c8d0 into j5/main Nov 8, 2026
55 of 68 checks passed
@Jacksondr5
Jacksondr5 deleted the feat/crew-seat-replacement branch November 8, 2026 02:15

This branch was successfully deployed

1 active deployment
Preview — 488c6974 Deployed Nov 7, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request size:XL 500-999 effective changed lines (test files excluded in mixed PRs). vouch:trusted PR author is trusted by repo permissions or the VOUCHED list.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Personas: a Captain can replace a seat

3 participants