Skip to content

feat(j5): archiving a Crew removes its clean, merged worktrees - #756

Merged
bryantderosier merged 17 commits into
j5/745-members-start-with-workfrom
j5/748-archive-removes-clean-worktrees
Nov 3, 2026
Merged

bryantderosier merged 17 commits into
j5/745-members-start-with-workfrom
j5/748-archive-removes-clean-worktrees

Conversation

@bryantderosier

@bryantderosier bryantderosier commented Oct 27, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Archiving a Crew leaves every seat's worktree on disk forever, and I was going through them by hand even though most are clean with their work merged. Now J5's archive removes the worktrees it created for a Crew's seats when they're clean, merged, not shared, and not in use, and it keeps the branch. Anything that fails a check stays where it is and shows up in the archive result with the reason, which is what #749 will build its Inbox approval on. Closes #748.

This is the first PR on top of #755 (j5/745-members-start-with-work), so the base is that branch and not j5/main.

  • Record: a seat on a new worktree gets a row in j5_crew_worktree (migration 050: thread, project, path, branch, created at), written when the thread first gets a worktreePath. Worktrees from before this ships have no row and are never touched. Only Crew seats are recorded, since that's the only place J5's archive can reach.
  • Check and remove: after the archive commits, each recorded worktree is removed only if it has no tracked changes or untracked non-ignored files, its HEAD is in the fetched default branch (or a merged PR's head SHA is that exact commit, so squash and rebase merges count), no other unarchived thread uses the path, and no live provider session is inside it. It takes withWorkspaceLease, rechecks, and runs git worktree remove without force. The branch and the thread's recorded branch/path stay. A fetch or PR lookup failure keeps the worktree as unverified. Nothing here can fail the archive.
  • Result: worktrees: [{path, branch, outcome, reason}] on the archive outcome, CrewArchiveResponse, and the j5_archive_crew result. Outcomes are removed | kept | failed; reasons are uncommitted_changes, unmerged_commits, shared, in_use, unverified, failed.
  • Guards: removal also refuses a worktree that is some project's root (kept as shared) or has a terminal open (kept as in_use), the same two checks upstream's storage cleanup has, and the real removal no longer treats the Crew's own seats as exempt from the sharing check.
  • Warnings: both archive dialogs (the sidebar one and Fleet's Archive crew) now list which worktrees would be removed and which kept, from one new read (j5.archive.readCrewWorktrees), labeled as an estimate because it can't fetch or look up PRs.
  • Unarchive and fork: a removed worktree comes back through upstream's existing repair on the next turn. There's a test against real git that proves it. I didn't touch the repair, so a failed repair is still only logged. I'm okay with that for now.
  • My ruling on the cascade: archiving a Captain from upstream's sidebar goes through the same Crew archive, so it cleans up too. The sidebar button itself is unchanged.

Docs: crews.md AC19 and its definition line, and archive-flow.md (definition, AC9, AC12), now describe the new promise instead of "archiving never deletes a worktree".

Evidence

At 0cf98aa683, on top of #755, after the stack was rebased onto j5/main. vp run -r typecheck (the CI command) exits 0 here, server src/j5/a2a src/j5/agents src/mcp passes (1264 tests) and web src/j5/a2a src/j5/fleet passes (116). The new cases run real git: a worktree that is a project root or holds one is kept, a worktree with a running terminal is kept, an exited or unrelated terminal doesn't keep it, and a seat unarchived into a worktree after the archive blocks its removal. The results below are from 66dec39c7a, before the rebase and the review fixes:

  • 904 server tests passed (1 skipped) across src/j5/a2a and src/j5/agents, including the new ones:
    cd apps/server && vp test run src/j5/a2a src/j5/agents
  • CrewWorktrees.test.ts runs real git against a bare origin and real worktrees. It covers clean and merged (removed), uncommitted tracked or untracked files (kept), ignored files (don't block), committed but unmerged (kept), a squash-merged PR (removed, after a branch rename), a merged PR for a different commit (kept), shared with an unarchived thread (kept), a live session including one in a subfolder (kept), a worktree with no row (untouched), a locked worktree (failed), fetch and PR lookup failures (unverified), and unarchive after removal.
    CrewWorktrees.integration.test.ts drives a real ThreadLaunch to confirm the recorder sees the real event shape.
  • 115 web tests passed for the dialog logic: cd apps/web && vp test run src/j5/a2a src/j5/fleet
  • 717 contracts tests passed: cd packages/contracts && vp test run
  • Server and web typecheck report 0 errors: vp run typecheck in each.

Not verified: the sidebar's archive dialog, the worktrees list in a real j5_archive_crew result, and unarchive plus repair of a removed worktree on a live server (the last one is covered against real git in CrewWorktrees.test.ts). The Live testing section below has the rest. I didn't run repo-wide checks.

Merge Danger

Door: one-way. Migration 050 adds a table that stays after a revert, and removal deletes a worktree directory from disk. Only clean, merged ones go and the branch is kept, so the checkout can be recreated, but ignored files in it (.env, node_modules, build output) are gone for good.

Blast Radius: archiving a Crew, however it's reached: Fleet's Archive crew, j5_archive_crew, and the cascade from archiving a Captain. A wrong check here deletes a checkout, so the checks are what I'd look at hardest.

Things I know are rough:

  • in_use will be common right after an archive. Archive doesn't release provider sessions (only deletion does) and idle release takes about 30 minutes, so seats archived soon after working often keep their worktree. Calling j5_archive_crew again later retries them, but there's no UI for that yet.
  • A worktree that is some project's root, or that has a terminal open, is kept, the same two guards upstream's storage cleanup has (project root and open terminal show as shared and in_use).
  • A worktree created while the server was down isn't recorded, so it's never removed. That fails safe.

After merge: nothing. #749 picks up the kept entries.

UI changes

Fleet's Archive crew dialog already existed. It now lists the worktrees that will be removed and kept. I haven't captured a before shot yet; I'll add one with a base server in a final live pass, so the "new" in the table below means the worktree section is new, not the dialog.

Before After
Fleet's Archive crew dialog, estimating one worktree removed and one kept (uncommitted changes) new Fleet's Archive crew dialog, estimating one worktree removed and one kept (uncommitted changes), after
The same dialog while sessions are still open: both worktrees kept new The same dialog while sessions are still open: both worktrees kept, after

The sidebar's archive dialog renders the same ArchiveWarningContent, but I couldn't open it: its entry is a native context menu the test browser can't reach.

Live testing

Ran on the whole stack at 1d4ff9bdf6 (it contains this layer's head, before the stack was rebased onto j5/main), in an isolated test home from j5-live-test with no flags. Nothing touched my real install.

  • A Captain proposed a two-seat Crew with each seat on a new worktree, and I approved it. Both worktrees got a j5_crew_worktree row as they were created (I read the table).
  • Straight after the seats finished, Fleet's dialog listed both worktrees as kept, "a session is open in it". That's the in_use rough edge above, seen live.
  • After a server restart (which drops the provider sessions) I left an untracked file in one worktree myself and reopened the dialog. It listed the clean one under "removed, if still clean and merged at archive time" and the other under kept, "has uncommitted changes".
  • I archived. On disk, the clean worktree's directory was gone and its branch was still there. The dirty one was untouched, and so were three other worktrees in the repo (two the Captain made with plain git, one a seat made itself) since they have no row. The archive request took 415 ms in the trace, and the row stays after removal.

Not exercised live: the sidebar dialog (above), a squash-merged PR (the test home has no GitHub), the result list in j5_archive_crew, unarchive and repair, and a Crew created before this change. Only Claude and Codex ran, and the test home can't cover a second machine or a relay.

Upstream impact

None. Everything is under J5-owned paths. Upstream's sidebar archive and its repair code are untouched, so there's no FORK.md or register entry.

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 — new states, 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) — entry points (Fleet live; MCP and cascade by test), clients (web; no mobile Crew surface), contracts, and the reverse (unarchive/repair, by test) are covered; the sidebar dialog and connection modes were not exercised live
  • 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 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

@bryantderosier bryantderosier self-assigned this Oct 27, 2026
@github-actions github-actions Bot added the vouch:trusted PR author is trusted by repo permissions or the VOUCHED list. label Oct 27, 2026
@bryantderosier
bryantderosier added this pull request to stack #753 October 27, 2026 18:15
@github-actions github-actions Bot added the size:XL 500-999 effective changed lines (test files excluded in mixed PRs). label Oct 27, 2026
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 22:36
@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: #756

Live (Astra, stack tip):

  • A clean, merged worktree was removed and its branch kept. Dirty and unmerged worktrees were kept with the right reasons (dialog states, open sessions).
  • The sidebar's Captain archive dialog opened and showed the cascade (sidebar).
  • Unarchiving a seat whose worktree was removed recreated the checkout, and a real Haiku turn ran in it.

Should fix: two guards upstream's cleanup already has are missing. CrewWorktrees.check() (around :345-385) checks thread bindings and live provider sessions only. Upstream storageCleanup.ts also refuses in two more cases:

  • A worktree that is some project's root (:301-315). A project opened at the seat's worktree (by a person, or by t3_project_create) has threads with worktreePath null, so sharedWithOthers can't see them. Archiving the Crew would remove that project's root.
  • An open terminal (:239, :746). The PR already notes this gap.

Copy both guards rather than re-deriving a subset.

Nit: cleanup passes own = seats (:525). getThreadWorktreePaths already excludes archived threads, so own can only hide a seat that was unarchived between the archive commit and cleanup. That is exactly the binding that should block removal. Only estimate needs own; pass an empty set for the real removal.

Process

  • The description says migration 049; it's 050.
  • "CI is green on this head" was written before J5 CI finished; the run was later cancelled.
  • The Fleet archive dialog existed before this PR, so it needs a before shot, not "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/748-archive-removes-clean-worktrees branch from 2ffedcf to 8d5d73c 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/748-archive-removes-clean-worktrees branch from 8d5d73c to 7b7973c 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:XL 500-999 effective changed lines (test files excluded in mixed PRs). and removed size:XL 500-999 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 and others added 5 commits October 29, 2026 08:18
Rewrites Crews AC19 and its definition line, and the Archive flow definition,
AC9 and AC12, for the new promise; updates the j5_archive_crew contract and
the personas user guide.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
The Effect language service flags chained Effect.provide calls, and tsc-rs
treats the warning as a failed typecheck in CI.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…has a terminal open (#748)

Archiving a Crew removed worktrees on the strength of thread bindings and live provider sessions
alone. A project opened at a seat's worktree has threads with no worktree path, and a terminal
there holds no session, so both could lose their folder. CrewWorktrees now applies the two guards
storage cleanup applies: a project rooted in the worktree keeps it as shared, and a running
terminal keeps it as in use. The archive dialog's estimate and the real removal share the check.

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

Cleanup exempted the Crew's own seats from the shared check. Archived threads are never in the
bindings it reads, so the exemption could only hide a seat unarchived since the archive committed,
which is exactly the binding that must keep its worktree. Only the pre-archive estimate needs it.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…eads it (#748)

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.

Nit: the recorder can record a worktree J5 didn't create. The recorder (CrewWorktrees.ts:194-218) records the first worktreePath set on any waiting worktree seat, whoever set it. Since #755 defers preparation to the first assignment, a t3_worktree_handoff or metadata update before then can point the seat at an existing worktree, and that worktree gets recorded as created by J5.

The clean, merged and branch-kept checks keep the harm small, but it breaks the "only worktrees J5 created" line in crews.md. Suggestion: record only when the branch matches the seat's workspace.branch, or document the gap.

@Jacksondr5

Copy link
Copy Markdown
Owner

Jackson's decision, relayed by the review lead (Claude Opus 5.5): archiving a Crew should close its members' provider sessions.

Today archive interrupts running turns but leaves each session live until the 30-minute idle release. The cleanup then keeps the worktree as in_use, so archiving right after the work tends to remove nothing. Those worktrees also aren't in the Inbox item and are never retried. Closing the sessions as part of the archive lets the clean, merged ones go straight away.

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

The worktree estimate moves into the shared archive-flow module so the
mobile warning sheet reads it too.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…ed as J5's to remove

A waiting seat could be pointed at an existing worktree by a handoff or a metadata update
before its first assignment, and the recorder wrote that worktree down as created by J5.
It now records only the metadata update committed by the seat's own preparation.

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

An archive interrupted each seat's turn but left its provider session open, so the
cleanup that followed kept most worktrees as in use. Each seat's session is now read
before its archive commits, then closed after, and a session another thread is still
attached to is left open.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…leanup 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
  • Recorder: it only records the metadata update the seat's own first-assignment preparation commits now, so a handoff or other update can't get a worktree recorded as ours (1f44f7c9be). The one gap is a retried preparation, which stays unrecorded and so is never removed. It's noted in crews.md.
  • Close sessions on archive: archive now closes each seat's provider session before the cleanup runs, so clean merged worktrees go right away (463a4d121a). A session another thread still uses (Codex shares one) stays open, and that worktree is kept as in use.

@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
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@bryantderosier
bryantderosier merged commit a74c4d0 into j5/main Nov 3, 2026
35 checks passed
@bryantderosier
bryantderosier deleted the j5/748-archive-removes-clean-worktrees branch November 3, 2026 01:30

This branch was successfully deployed

1 active deployment
Preview — dbaa09fb 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: archiving removes clean, merged worktrees

2 participants