Skip to content

feat(j5): start Crew members on their first assignment - #755

Merged
bryantderosier merged 16 commits into
j5/743-agent-setup-crew-approvalfrom
j5/745-members-start-with-work
Nov 3, 2026
Merged

bryantderosier merged 16 commits into
j5/743-agent-setup-crew-approvalfrom
j5/745-members-start-with-work

Conversation

@bryantderosier

@bryantderosier bryantderosier commented Oct 27, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Crew approval currently starts every member before there is an assignment. I create waiting seats, save their approved introductions, and deliver each introduction with the first assignment the provider accepts. Later assignments carry net roster changes. Closes #745.

Fleet and spawned-member views show Not started, and a seat whose first start failed shows its failed or interrupted label instead.

Review fixes since the first version:

  • Stop before the send: the roster is only marked delivered when the provider actually got the turn, so a Stop in between doesn't drop the introduction (25ef2b7bae).
  • Steering: a message steered into a busy seat carries the Crew context too, through one small hook in ProviderTurnControlService recorded in FORK.md (25ef2b7bae).
  • Introduction after a rebuilt conversation: the seat records which provider conversation got its introduction and gets it again when that changes, such as after a model switch or a failed native resume (25ef2b7bae).
  • Fast path: ordinary threads skip the Crew path again, with one indexed seat check, so FORK case 106 is true (25ef2b7bae).
  • Authored text: removed the unwrap of the old context envelope, so a message that starts with the marker reaches the member unchanged (25ef2b7bae, 32f5dde873).
  • Failed first start: Fleet and the sidebar show the run label instead of "Not started" (bee2e47a34).
  • Migration: dropped four unused pending_* columns (25ef2b7bae).

I left two nits: the roster still shows a persona's id rather than its display name, and notStarted stays optional because a member with no seat-context row reads as NULL. Worktree preparation remains separate from provider startup. This PR targets j5/743-agent-setup-crew-approval and preserves the approved #751 proposal/editor UI through its parent update.

Evidence

At 9f04c4637f, on top of #754, after the stack was rebased onto j5/main. The CI typecheck command exits 0 here:

  • Server src/j5/a2a src/j5/agents src/mcp plus the two ProviderTurn* tests pass (1275 tests), web src/j5 passes (519) and contracts passes (718).
    cd apps/server && vp test run src/j5/a2a/migrations/049_CrewSeatActivation.test.ts src/j5/a2a/Migrations.test.ts
  • New cases use real SQLite with the real provider-start and control services: a Stop before the send leaves the roster unmarked, a steered message carries a newly added reviewer, a replaced native conversation gets the introduction again and an unchanged one doesn't, a non-seat thread keeps upstream's turn start, and a failed first start reads as failed in both row surfaces.

Earlier evidence at c081af1245:

  • 179 tests passed across 10 focused files:
    vp test run apps/server/src/j5/a2a/CrewDeliveryContext.test.ts apps/server/src/j5/a2a/CrewDeliveryContext.integration.test.ts apps/server/src/orchestration-v2/ProviderTurnStartService.test.ts apps/server/src/j5/a2a/CrewLaunchService.test.ts apps/server/src/j5/a2a/CrewLaunchReporter.test.ts apps/server/src/j5/a2a/AgentCrewInstanceService.test.ts apps/server/src/j5/a2a/CrewProposalService.test.ts apps/server/src/j5/a2a/migrations/048_CrewSeatActivation.test.ts apps/web/src/j5/a2a/ThreadA2ARenderer.test.tsx apps/web/src/j5/crew/crewState.test.ts
  • Regressions cover retired waiting worktree seats, replay after retirement, continued use of a started retired member, provider refusal, and current roster context after real queued edit/reorder/cancel commands. The provider-start regression exercises a retained native conversation without a history handoff and verifies provider acceptance precedes acknowledgment.
  • Crew context is included in prompt budgeting. Stored assignment text and shared author prefixes stay unchanged; their subscriptions need no extra invalidation. Queued A2A previews and sender extraction understand older context-wrapped envelopes.
  • Server and web typechecks passed: vp exec tsc-rs --noEmit -p apps/server/tsconfig.json and vp exec tsc-rs --noEmit -p apps/web/tsconfig.json.
  • Targeted formatting/lint and git diff --check passed. Lint retains the existing react(exhaustive-effect-dependencies) warning in ThreadA2ARenderer.tsx.

Not verified: Real provider turns, end-to-end approval/first-assignment behavior, desktop, mobile, remote/relay, and tunnel testing remain unrun. The tests use real orchestration/SQL paths with mocked provider boundaries. No new paid-model turns, browser captures, interaction video, or repo-wide checks ran for this repair. Earlier independent reviews covered the prior head; the repair has not had a new independent review.

Merge Danger

Door: One-way for persisted state: migration 49 creates and backfills j5_crew_seat_context; reverting code leaves that table and its records behind. The repair adds no migration.

Blast Radius: Crew seat creation and assignment delivery, worktree startup, shared-conversation context, Fleet/member status, and A2A message presentation.

The four previously recorded P2 findings are addressed:

  1. A waiting member cannot bypass its Crew's retirement by reopening only the seat. Worktree guards remain active for retired started members too.
  2. Accepted queued messages no longer consume the introduction or roster notice. The selected assignment receives current context at provider start, after queue editing, cancellation, and reordering.
  3. Crew delivery no longer changes stored_prefix, so connected author reads cannot retain an obsolete Crew prefix.
  4. Queued A2A formatting and participant extraction unwrap older Crew context before parsing the delivery envelope.

After merge: Migration 49 runs through the normal J5 migration path.

UI changes

Waiting seats display Not started in Fleet and spawned-member views. The matching synthetic fixture below shows the change from Idle to Not started, including the Crew summary count. Both captures are 1280×800 from isolated local web clients.

Before (f2a1b38cbd) After (39343ebf9b)
Waiting seats before: Idle Waiting seats after: Not started

The images are uploaded to j5/evidence; GitHub API readback matches the local PNGs byte for byte. Direct raw-image fetch verification was blocked by the local corporate proxy (Zscaler HTTP 403). No video was recorded in this screenshot-only pass.

Live testing

Partial web verification at head 39343ebf9bb848bcc6ab7f0f4ce32040504f16eb, compared with base f2a1b38cbdb94d96227a3ca6d2f04c44c555309f, using node scripts/j5/setup-agent-live-test.ts --base origin/j5/743-agent-setup-crew-approval. I opened both isolated clients, expanded the Fleet Crew and sidebar member group, and captured the waiting labels. These are synthetic SQLite presentation fixtures, written while servers were stopped; they do not prove approval, delivery, or provider startup. No provider calls were made. Those screenshots cover the historical head. This repair changes context delivery and queue preview parsing; it has focused regression coverage but no fresh live provider/browser pass.

The base install initially missed the repository’s existing @pierre/diffs patch; applying that tracked patch to its installed dependency restored the client. No source changes were needed. Both test servers were stopped after capture.

Hand verification should approve a shared-workspace Crew and a worktree Crew, confirm no member provider starts at approval, send a first assignment, verify the introduction and approved workspace, then change the roster and confirm the next assignment carries the net change. Repeat through human chat, agent messaging, and playbook delivery; cover queued edit/cancel/reorder and archive/reopen after the review fixes.

Upstream impact

apps/server/src/orchestration-v2/runtimeLayer.ts wires the J5 dispatch guard and Crew delivery service into the shared runtime. ProviderTurnStartService.ts delegates the selected assignment to the J5 service around provider delivery, including its budgeting path. ProviderTurnStartService.test.ts covers that integration without a history handoff. These J5-only hooks and all three file-table rows are recorded in FORK.md case 106. Ordinary non-Crew messages retain their text and upstream delivery semantics. Production provider adapters are unchanged.

apps/server/src/orchestration-v2/Orchestrator.ts and the orchestration contracts gain one server-only command, platform-message.record, which records a platform message in a thread without starting a run. A member's introduction and roster changes use it so they're visible in the member's thread. It's in FORK.md case 106 and register entry D43 (Jackson's decision, approved by Bryant).

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 — historical screenshots attached; fresh provider timing/interaction video remains unrecorded
  • 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
  • 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 — J5 Crew behavior; no upstream product divergence introduced
  • Surfaces: entry points, clients, providers, contracts, reverse states, connection modes (see AGENTS.md) — static/shared-path coverage only; live coverage outstanding
  • Docs: definitions under docs/j5/product/ and user docs rewritten where this changes them

Implementation and repair: GPT-6.1 Sol through the Codex harness. Earlier-head independent reviews: GPT-6 Astra and Claude Opus 5.5.

What a member was told

Added by the review panel after merge, from a live test of the merged code on an isolated test server. The card is new, so there's no before. The red provider error in the first image is tracked separately in #913.

After
A member's thread with the Introduction and Roster changed cards collapsed A member's thread with the Introduction and Roster changed cards collapsed, after
The Introduction card expanded, showing what the model read The Introduction card expanded, showing what the model read, after

@vercel

vercel Bot commented Oct 27, 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 2, 2026 10:37pm UTC

Request Review

@github-actions github-actions Bot added vouch:trusted PR author is trusted by repo permissions or the VOUCHED list. size:XL 500-999 effective changed lines (test files excluded in mixed PRs). labels Oct 27, 2026
@bryantderosier bryantderosier self-assigned this Oct 27, 2026
@bryantderosier bryantderosier linked an issue Oct 27, 2026 that may be closed by this pull request
16 tasks
@bryantderosier
bryantderosier added this pull request to stack #753 October 27, 2026 15:37
bryantderosier added a commit that referenced this pull request Oct 27, 2026
@bryantderosier
bryantderosier marked this pull request as ready for review October 27, 2026 17:43
@coderabbitai

coderabbitai Bot commented Oct 27, 2026 •

Copy link
Copy Markdown

Important

  • Trigger review

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

Run configuration
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

@Jacksondr5

Copy link
Copy Markdown
Owner

Panel review: #755

Live (Astra, stack tip): with real Haiku and Luna seats, no provider session existed before the first assignment (Not started). The first turns carried the introduction, and a later added member reached the next assignment as a roster delta. The tester checked native session files, the database and receipts.

Should fix: a seat whose first turn fails still says "Not started". Reproduced live: the tester broke the test server's Codex path and sent a Luna seat its first assignment. The run failed, the Captain showed the red line, and the Crew summary said "1 failed". The seat's own row in Fleet and in the sidebar still said "Not started" (Fleet row, sidebar). delivered_roster is set only when the provider accepts the turn (CrewTurnContext.ts:138-140), so notStarted stays true. FleetPage.tsx:752-755 and threads/SpawnedChildren.tsx:286-289 both check notStarted before seatRunLabel. Check the run label first.

Should fix: a seat loses its introduction on a context handoff. The brief, seat instructions, <crew_collaboration> and roster go into the provider prompt only (CrewTurnContext.ts:126-140). The stored turn keeps the assignment alone, and delivered_roster is set right away. When a new provider thread is built from stored history, the introduction is gone and nothing re-sends it. That happens on a model or provider switch (by the person or t3_thread_configure), or when a Codex native resume fails (ContextHandoffService.ts:449-460, ProviderTurnStartService.ts:738-755). Before this PR the introduction was the stored first message, so it survived. A smaller fix: record which native thread the introduction went to, and send the full introduction again when that changes.

Before merge (the migration is one-way): 049_CrewSeatActivation.ts creates pending_command_id, pending_message_id, pending_prefix and pending_roster. Nothing writes a value to them. The only write sets them to NULL (CrewTurnContext.ts:116), a leftover from the earlier design. Drop them before the table ships.

Dead code that can bite. crewDeliveryAssignment (contracts/src/j5/crewDeliveryContext.ts) unwraps "older context-wrapped envelopes" that only existed at an unmerged head. It's called from ThreadA2ARenderer.tsx (4 sites) and on every assignment in CrewTurnContext.ts:138. That's despite its own "call only on platform-owned delivery message ids" comment, so a person's message that starts with <j5_crew_delivery_context> would be silently cut. Delete it.

Nits

  • Fast path off for every thread. runtimeLayer.ts:175 always provides CrewTurnContext, so Option.isNone(crewTurnContext) (ProviderTurnStartService.ts:1277) is never true. Every turn on every thread now goes through makeDeliverySession and a j5_crew_seat_context read. Every message.dispatch takes the KeyedLock plus a receipt and context read (CrewDeliveryContext.ts:48-62). The behaviour is unchanged, but FORK case 89's "Non-Crew threads keep upstream delivery unchanged" overstates it. Either ask once whether the thread is a seat and keep upstream's fast path, or reword case 89.
  • Persona id instead of name. The first-turn roster is rebuilt with agentDisplayName: member.agentId ?? "custom" (CrewTurnContext.ts:75-80), so it shows the persona id, not its display name.
  • notStarted is never absent. Migration 049 backfills every member, so the optional notStarted in the contracts and the undefined branch in CrewLaunchReporter can become a plain boolean.
  • Process. The description says migration 48 and 048_CrewSeatActivation.test.ts; it's 049. FORK's file table has two ProviderTurnStartService.test.ts rows with different status codes.

Review panel for the #750–#762 stack, judged as the code that lands at da64b2795c: Claude Opus 5.5 (lead and three code reviewers), GPT-6.1-Sol (process, docs, CI) and GPT-6-Astra (live test on an isolated server, Haiku 5.5 and GPT-6 Luna turns). Every finding here was agreed by the whole panel. Product questions are with Jackson and are not listed. Posted by Claude Opus 5.5 via J5 Code.

@BastiHu BastiHu 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.

Inline findings from the crew review of #750, #751, #754 and #755, checked against this PR's current diff. Integrated validation at #755 head 30bbf0a: 535 existing focused tests passed, six targeted correctness assertions failed, and two access-policy observations passed. Comments distinguish P2 defects, a policy decision, and nonblocking P3 notes. No source changes were made.

Comment thread apps/web/src/j5/fleet/FleetPage.tsx Resolved
bryantderosier and others added 6 commits October 29, 2026 08:17
Record a seat's context as delivered only when the provider took the send,
so a start stopped or superseded before startTurn leaves it owed. A steered
message to a busy seat now carries the current context too. The full
introduction is sent again when the provider conversation it reached is
replaced (model or provider switch, lost native session). Threads that are
not Crew seats skip the Crew path entirely again. Drops the four unused
pending_* columns from migration 49.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…arted (#745)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
The unwrap only served an envelope shape that was never merged, and it would
cut authored text that begins with the marker.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…ey now behave (#745)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…745)

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

Copy link
Copy Markdown
Owner

Review panel: Claude Opus 5.5 (lead) and GPT-6.1 Sol. We reviewed the whole stack at 16cb7824a1. Both reviewers agreed.

Should-fix: every turn and steer on a seat bumps the crew and fleet change feeds. prepare always returns a delivered effect when a context row exists, and that effect is the UPDATE plus changes.notify("crew","fleet") (CrewTurnContext.ts:155-165). deliver runs it after every accepted send, and the steering wrapper does the same.

A 20-message review loop makes every client re-read Crew proposals, runtime requests and sidebar chips 20 times. Only the first delivery, or a roster or conversation change, changes anything. Suggestion: skip the UPDATE and notify when the roster JSON and conversation are unchanged.

Nits

  • FleetPage.test.tsx and SpawnedChildren.test.tsx (new) render to static markup to assert a label. AGENTS.md asks us not to do that, and seatQuietLabel is already covered in crewState.test.ts. We'd delete both.
  • The delivered roster uses member.agentId ?? "custom" (CrewTurnContext.ts:109), so the display name from launch is replaced by the persona id. You listed this already; we confirmed it in the source.

@Jacksondr5

Copy link
Copy Markdown
Owner

Jackson's decision, relayed by the review lead (Claude Opus 5.5): a member's introduction must be visible in its own thread.

Since this PR, approval stores the brief, roster, collaboration rules and seat instructions in j5_crew_seat_context, and J5 adds them to the first assignment for the model only. The member's timeline starts with the Captain's assignment, and the brief card (SpawnBrief) no longer appears. Roster-change notices reach the member the same invisible way.

Please make what the member was told visible in its thread.

bryantderosier and others added 6 commits November 2, 2026 09:09
…nt layer

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…e label

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
… the roster keeps launch names

A follow-up or steer to a seat whose roster and conversation are unchanged no longer
updates the seat context or bumps the crew and fleet feeds. The delivered roster names
each seat as it was launched instead of by persona id.

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

Copy link
Copy Markdown
Collaborator Author

Went through both comments:

  • Feeds bumped on every turn: fixed. A seat's roster and conversation are only written, and the feeds only notified, when something changed. Follow-ups and steers do neither now (cc57ff9119).
  • Static-markup tests: deleted both and added the seat label cases to crewState.test.ts (9b368df8e2).
  • agentId ?? "custom": the delivered roster uses the name from launch now (cc57ff9119).
  • Introduction visible in the member's thread: not done yet. Orchestrator has no way to add a message to a thread without starting a turn, so it needs an upstream edit or a separate J5 read/render. I'm sorting out which with Jackson before I touch it.

bryantderosier and others added 2 commits November 2, 2026 11:38
A record-only platform message joins a thread's history without starting a
run. When a seat's prompt carrying the introduction or a roster change is
accepted, the seat's thread records that text once.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
The introduction and each roster change appear as a collapsed card that
opens to the text the model read, on web and mobile. Records the new
internal command in FORK.md (case 106) and the register (D43).

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

Copy link
Copy Markdown
Collaborator Author

Did the introduction one too. Once the provider takes a prompt that carried the intro or a roster change, the member's thread records exactly what the model read as a collapsed card (0f5140efea, b0ea47ef20). It's a new record-only orchestrator command, so it doesn't start or queue a run, and it's recorded once per change even on a retry. It's an upstream edit to Orchestrator.ts and the contracts, so it's in FORK.md case 106 and a new register entry D43. Mobile shows it as a card with a tappable header. The card sits after the assignment, not at the very top where the old brief card was.

@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 2, 2026
…t imports it (#745)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@bryantderosier
bryantderosier merged commit 4eb598a into j5/main Nov 3, 2026
35 checks passed
@bryantderosier
bryantderosier deleted the j5/745-members-start-with-work branch November 3, 2026 01:30

This branch was successfully deployed

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

Labels

size:XXL 1,000+ 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.

Crews: members start when there's work for them

3 participants