Skip to content

fix(j5): pin a new Crew worktree to a commit so branch renames don't break launches - #761

Merged
bryantderosier merged 17 commits into
j5/747-adjudication-requestfrom
j5/752-pin-worktree-base-commit
Nov 3, 2026
Merged

bryantderosier merged 17 commits into
j5/747-adjudication-requestfrom
j5/752-pin-worktree-base-commit

Conversation

@bryantderosier

@bryantderosier bryantderosier commented Oct 28, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

A Crew proposal took a new worktree's base from a branch name, and J5 renamed that branch before I approved, so preview said the member was unavailable and blocked the whole roster. Keeping a mutable branch name as the launch dependency lets routine renaming invalidate a proposal. This pins a new worktree's base to a commit when the proposal is accepted and launches from that commit. Closes #752.

This is stacked on #747, so the base is j5/747-adjudication-request. It is built on the rebased stack, which includes #660's replay-conflict behavior.

  • The pin: an optional full-SHA baseCommit on a worktree seat's workspace choice, with baseRef kept as the readable label. It lives in the stored seats, the approved seats and the seat context, which are JSON already, so there's no migration.
  • When it's taken: at propose and when a member is added, after validation and after the replay check, so a retry never re-pins. A ref that doesn't resolve is refused at once, naming the member and the ref, and no unapprovable proposal is stored. Automatic approval and direct additions use the same pinned seats.
  • Preview and approval: a saved pin is checked by existence only. An unpinned seat has its ref resolved at that moment and shown, and the approval token binds it. Editing a member's base or its "start from origin" box on the card drops the pin, so the new choice is resolved, previewed and approved again. A plain refresh never advances a pin.
  • Preparation: Crews: members start when there's work for them #745's first assignment hands upstream's worktree preparation {baseRef: <sha>, startFromOrigin: false}, so nothing moves the pin afterwards. A branch renamed, moved or deleted after acceptance doesn't change the revision while the commit still exists. A vanished commit fails visibly with the member and the short SHA named at preview and approval.
  • Start from origin: the pin is taken after fetching origin for that ref and pins the origin tip, falling back to the local ref if there is no origin branch. A network fetch happens during propose and preview for those members only.
  • The Captain's checkout: a ref equal to the Captain's checked-out branch (or HEAD) resolves live to that checkout's current commit, ignoring uncommitted changes. No new sentinel in the contract or the MCP tool.
  • Already-open proposals: the first preview resolves the stored ref and shows it, and approval binds it. If the ref is already gone, preview refuses naming the member, the ref and the edit needed. Nothing is written to the open row.
  • The card: each new-worktree member shows New worktree from <ref> @ <8-char sha>, with the full SHA in a tooltip.
  • gh-merge-base: a worktree prepared from a pin gets no gh-merge-base and the setup tracker shows the SHA as its base, because upstream derives both from a branch name. I decided to accept that rather than edit upstream's preparation. It's documented, and gh pr create from such a worktree needs an explicit base.

Docs: the workspace paragraph in agent-tools.md (tool descriptions in tools.ts kept in sync) and crews.md.

Evidence

At c41cbaa78e, on top of #747. vp run -r typecheck (the CI command) exits 0 on the stack tip:

  • 212 server tests passed across the touched files and the mcp, EnvelopeFormatter and runtimeLayer tests, plus 5 contracts tests and 112 web j5/crew tests:
    cd apps/server && vp test run src/j5/a2a src/mcp
  • spawnWorkspacePin.test.ts runs real git: a branch moved, renamed and deleted with the commit kept, a missing pinned commit, and the origin fetch showing the pin doesn't advance when origin moves again.
  • The service tests cover a rename between proposal and approval, a rename between approval and preparation, an already-stale ref at propose, a base edit, a retry versus a changed-argument conflict (fix(j5): reject changed spawn and Crew proposal replays #660's behavior), automatic and direct launch paths, and an already-open proposal pinned at its first preview.
  • Full stack tip (b8a42e0bc0, after the stack was rebased onto j5/main): server 1298, web 1150, contracts 736, client-runtime 182, provider-core 205 and shared 1680 tests pass.

Not verified: an already-open proposal from before this change, a start-from-origin member, an automatic approval and a direct addition on a live server (tests cover them). I didn't run repo-wide checks.

Merge Danger

Door: two-way. The pin is an optional field in stored JSON and there's no migration. After a revert an old proposal's extra field is simply ignored.

Blast Radius: every Crew proposal and addition that includes a new-worktree member.

Things worth knowing:

  • Proposals that need human approval now run the worktree workspace checks when they're proposed, as automatic ones already did. A colliding new branch name is refused at propose instead of at preview. Shared and existing-worktree members aren't checked there.
  • A direct j5_spawn_agent with start_from_origin now fetches origin once while the spawn is accepted. Preparation still fetches as before, and direct spawns don't use the pin.
  • If a pinned commit disappears after approval, upstream's preparation fails the run in the member's own thread with git's error. I added no extra pre-check.
  • CrewProposalService.ts, CrewLaunchService.ts and spawnWorkspace.ts are the likeliest to conflict with anything else in the Crew launch path.

After merge: nothing.

UI changes

One new line under each new-worktree member on the roster card.

Before After
A new-worktree member on the roster card shows the commit it will start from new A new-worktree member on the roster card shows the commit it will start from, after

Live testing

Ran on the whole stack at da64b2795c, before the last rebase onto j5/main, in an isolated test home from j5-live-test. Claude Haiku 5.5.

  • A Captain proposed a Crew of two members, each on a new worktree from main. The card showed New worktree from main @ c02a2d96 for both.
  • After the proposal existed I renamed main in the test repo, then approved. Approval succeeded, and git shows both new worktrees at c02a2d96. The Captain's checkout was on the renamed branch.

Not exercised live: an already-open proposal from before the change, start from origin, automatic approval and a direct addition.

Upstream impact

None. Everything is under J5-owned paths, and I used GitVcsDriver.resolveCommit instead of adding a method to upstream's GitWorkflowService.

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 — a new line, so no before; 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 edited
  • 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 — no upstream behavior changes
  • Surfaces: entry points, clients, providers, contracts, reverse states, connection modes (see AGENTS.md) — the roster card and the proposal path ran live on Claude; automatic approval, direct additions and start from origin are covered by tests only
  • Docs: definitions under docs/j5/product/ and user docs rewritten where this changes them

Claude Sonnet 5.5 through the Claude Code harness in J5 Code.

🤖 Generated with Claude Code

@vercel

vercel Bot commented Oct 28, 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 3, 2026 12:50am UTC

Request Review

@bryantderosier
bryantderosier added this pull request to stack #753 October 28, 2026 02:19
bryantderosier added a commit that referenced this pull request Oct 28, 2026
@bryantderosier
bryantderosier marked this pull request as ready for review October 28, 2026 02:24
@coderabbitai

coderabbitai Bot commented Oct 28, 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

CodeRabbit Verify

  • Run CodeRabbit Verify to test the changes in this pull request.

@github-actions github-actions Bot added size:L 100-499 effective changed lines (test files excluded in mixed PRs). vouch:trusted PR author is trusted by repo permissions or the VOUCHED list. labels Oct 28, 2026
@Jacksondr5

Copy link
Copy Markdown
Owner

Panel review: #761

Live (Astra, stack tip): new-worktree members showed @ <sha> (card). Renaming main after the proposal and then approving worked, and the first worktree's HEAD was exactly the pinned SHA. Auto-approved worktree seats worked too.

No code findings. The panel checked that the pin is taken after the replay check, that proposalRequest strips baseCommit so retries match, and that the approval token covers the pinned seats.

Process nit: the roster card existed before, so it needs a before shot rather than "new".


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.

@bryantderosier
bryantderosier removed this pull request from stack #753 October 28, 2026 11:45
@bryantderosier
bryantderosier force-pushed the j5/752-pin-worktree-base-commit branch from d630b46 to 6cb5575 Compare October 28, 2026 11:45
@bryantderosier
bryantderosier added this pull request to stack #771 October 28, 2026 11:48
@bryantderosier
bryantderosier force-pushed the j5/752-pin-worktree-base-commit branch from 6cb5575 to b28ee63 Compare October 28, 2026 12:06
@github-actions github-actions Bot added size:XXL 1,000+ effective changed lines (test files excluded in mixed PRs). size:L 100-499 effective changed lines (test files excluded in mixed PRs). and removed size:L 100-499 effective changed lines (test files excluded in mixed PRs). size:XXL 1,000+ effective changed lines (test files excluded in mixed PRs). labels Oct 28, 2026
@bryantderosier
bryantderosier force-pushed the j5/752-pin-worktree-base-commit branch from b28ee63 to c8160e1 Compare October 28, 2026 16:49
@bryantderosier

Copy link
Copy Markdown
Collaborator Author

Thanks for the live check. Rebased onto the updated #760 and pushed (c8160e1a24), no code changes. On the before shot: you're right, the roster card isn't new. I'll add a before image in the final live pass and update the body then.

bryantderosier and others added 5 commits October 29, 2026 08:18
…lved to (#752)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…al is accepted (#752)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…oval and preparation (#752)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…hen proposed (#752)

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: a fetch failure refuses every worktree seat. In spawnWorkspace.ts:466-482, resolveBase calls git.fetchRemote without a catch. The catch-all in inspect (:520) then turns the whole checkout into readable: false.

Effects:

  • One start_from_origin seat makes propose and preview refuse every worktree seat, with "The project's git repository can't be read".
  • It also breaks the documented local fallback: a local-only branch with origin present fails in fetchRemote before remoteBranchExists is reached.
  • A plain j5_spawn_agent with start_from_origin (SpawnAgentService.ts ~525) now fetches during acceptance and fails the same way. Direct spawns don't use the pin.

Suggestion:

  • Treat a missing origin branch as the local fallback the docs describe.
  • On a real network or auth failure, refuse that one seat by name rather than silently pinning a stale ref, since the person chose origin.
  • Don't fetch for direct spawns.
  • Add a test with an unreachable remote.

bryantderosier and others added 8 commits November 2, 2026 09:31
…layer

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
A start_from_origin base whose fetch fails no longer makes the whole
checkout unreadable, which refused every worktree seat and every direct
spawn. That seat is refused by name with a next step; other seats resolve,
and a base with no origin branch still falls back to the local ref. A
direct j5_spawn_agent checks that its base exists without fetching.

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

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

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>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@bryantderosier

Copy link
Copy Markdown
Collaborator Author

Fixed in 3be37dbfca. A failed fetch only refuses the seat that picked origin, by name, with a next step; the other seats still resolve and nothing gets pinned to a stale ref. A branch that isn't on origin falls back to the local ref like the docs say, and direct j5_spawn_agent calls don't fetch at all. Added tests with an unreachable origin.

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

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@bryantderosier
bryantderosier merged commit e910a03 into j5/main Nov 3, 2026
35 checks passed
@bryantderosier
bryantderosier deleted the j5/752-pin-worktree-base-commit branch November 3, 2026 01:30

This branch was successfully deployed

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

Labels

size:L 100-499 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: branch renames do not break worktree launches

2 participants