Skip to content

feat(j5): one Inbox approval for worktrees with unfinished work - #762

Merged
bryantderosier merged 21 commits into
j5/752-pin-worktree-base-commitfrom
j5/749-worktree-cleanup-approval
Nov 3, 2026
Merged

bryantderosier merged 21 commits into
j5/752-pin-worktree-base-commitfrom
j5/749-worktree-cleanup-approval

Conversation

@bryantderosier

@bryantderosier bryantderosier commented Oct 28, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

After #748, archiving a Crew removes every worktree that's safe to remove and keeps the rest. The kept ones hold uncommitted changes or commits that never merged, and I have to find each one and decide by hand. This files one Inbox item per archive that lists those worktrees, and I decide once: remove all, remove the ones I pick, or keep all. Closes #749.

This is stacked on #752, so the base is j5/752-pin-worktree-base-commit. The mockup I approved is artifacts/design/ui/09-worktree-cleanup.html (in the J5 artifacts store, linked on the issue).

  • The item: a Crew archive that keeps any worktree for uncommitted changes or unmerged commits files exactly one item, however many seats it covered. Worktrees kept as shared, in use or unverified aren't listed. Each row shows the thread and branch, uncommitted files, commits not on the default branch, and the PR link when it has one, measured once when the archive keeps it. The item says removal keeps the branch and discards uncommitted changes.
  • Not a ledger exchange: every Inbox ask is joined to an agent's exchange, and this item has no agent sender. It's its own item type with one new table (migration 051), its own read and answer RPCs, and the existing inbox read key bumped, the way Crew runtime approvals already sit beside the asks. The ask list and its join are untouched.
  • The answer: { itemId, removePaths }. Remove all is every path, keep all is an empty list that clears the item and changes nothing, and a path that isn't in the item is refused. The item resolves once, and a second answer is refused. Only an Owner with the operate scope can answer, and agents get no tool for it.
  • Recheck: before removing each approved worktree J5 skips it if HEAD, the uncommitted-file list or what is in those files differs from what was filed (a nested repository or a status git cut off can't be compared, so it's skipped), another unarchived thread is now bound to it, or a live session is open in it. A path that's gone or no longer a worktree is skipped quietly. Removal reuses Crews: archiving removes clean, merged worktrees #748's lease and re-read.
  • Outcomes: removed, kept (I chose to), skipped (changed, shared, in use, gone, unverified) or failed (with git's error). One failure doesn't stop the rest. The item shows them in place, then moves to the Answered shelf. There's no retry.
  • Filing: one item per Crew, open or answered, so an archive replay files nothing new even after Keep all, and an open item counts in the Inbox badge.
  • The page: a new component after the asks list, with nothing selected by default, Keep all, Select all (disabled once everything is picked) and Remove selected (n), five rows then "Show N more", FYI urgency and "J5" as the sender.

Docs: inbox.md (the definition and AC18–AC22), archive-flow.md and crews.md.

Evidence

At 16cb7824a1, on top of #752. Server typecheck exits 0 here:

  • 890 server tests passed (cd apps/server && vp test run src/j5/a2a), with the 11 new CrewWorktrees tests running against real git: one item for many worktrees, remove all, remove some, keep all, an archive that runs again after keeping all, a recheck that skips a worktree whose already-changed files changed again, one with a nested repository, a changed worktree, a second answer refused, a removal failure, and a worktree removed elsewhere while the item is open. A migration 051 test checks one item per Crew.
  • 182 client-runtime tests (cd packages/client-runtime && vp test run src/j5) and 531 web j5 tests, including 14 new logic tests for selection, counts, the five-row slice, outcome grouping, reasons and the refusal mapping.
  • The permission tests are extended: the answer needs the operate scope, and the MCP tool list is unchanged, so no agent can answer.
  • Lint with --report-unused-disable-directives and vp fmt exit 0. The one set-state-in-effect warning at HumanInboxPage.tsx:613 is in the existing person-scope reset effect, which my edits only moved.

Not verified: a long list (more than five rows), a partial failure, a refused second answer, a non-Owner view and an item answered on another device (the logic is tested, but I haven't seen them rendered). I didn't run repo-wide checks.

Merge Danger

Door: one-way. Migration 051 adds a table that stays after a revert, and an approved removal deletes a worktree directory from disk, including its uncommitted changes. The branch is kept, so the commits survive, but uncommitted files are gone for good. I approve that per worktree, and the item says so before I do.

Blast Radius: every Crew archive, however it's reached: Fleet's Archive crew, j5_archive_crew and the cascade from archiving a Captain. It adds a new item to the Inbox page and its badge.

Things worth knowing:

  • The recheck baseline is HEAD plus a digest of git status and the content hash of each changed file, so a further edit to a file that was already modified is caught. A nested repository or a status over 64 KB can't be compared, so those worktrees are always skipped and have to be removed by hand.
  • The approved removal passes force, because git refuses to remove a worktree with uncommitted changes and every worktree here has some. A locked worktree still fails and is reported.
  • The server doesn't record who answered, so the result has no "You answered" line, and the rows say "commits not on the default branch" instead of naming it.

After merge: nothing.

UI changes

The Inbox item is new, so there's no before.

Before After
The cleanup item in the Inbox: one item for the archive, nothing selected, Remove selected disabled new The cleanup item in the Inbox: one item for the archive, nothing selected, Remove selected disabled, after
After removing one worktree: the item stays in place with what was removed and what was kept new After removing one worktree: the item stays in place with what was removed and what was kept, 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.

  • I archived a Crew whose two worktrees had different unfinished work (one uncommitted file, one unmerged commit). The Fleet dialog listed both as kept with their reasons, and the archive filed one Inbox item, FYI, sender J5, with nothing selected and Remove selected disabled at 0.
  • I picked one worktree and removed it. The item stayed in place as "1 removed · 1 kept (Not picked)". On disk, the picked worktree's directory was gone and its branch remained, and the other worktree was untouched.

Not exercised live: a long list, a partial failure, a refused second answer, a non-Owner view, another device, and unarchive after a removal.

Upstream impact

None. Everything is under J5-owned paths.

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) — Fleet and the Inbox ran live on Claude; the cascade, j5_archive_crew and the remaining states 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.

@Jacksondr5

Copy link
Copy Markdown
Owner

Panel review: #762

Live (Astra, stack tip):

  • One cleanup item was filed. Removing the dirty worktree and keeping the unmerged one worked, and the branches were kept (open, resolved).
  • A second tab reconciled (second tab).
  • Unarchive and a real turn recreated the removed checkout (reopened).

Should fix before merge: the recheck before a forced removal misses content changes. It was proven three ways: a scratch test against this code, and two separate git experiments. measure() and the baseline branch of check() (CrewWorktrees.ts:362-370, :457-498) compare HEAD plus a sha256 of git status --porcelain, which lists names and status codes, not contents. Removal then uses force: true (:438). The recheck misses these, and all of them are deleted without anyone having seen them:

  • Edits to files that were already dirty. The item is filed showing "2 uncommitted files". The person, or an unarchived agent, keeps editing those same files. Remove then deletes the new work.
  • Status output over 64 KB. The baseline path ignores stdoutTruncated (:269).
  • Commits inside an untracked nested repo.

The scratch test overwrote both listed files after filing, answered, got removed, and the worktree with the new content was gone. Compare content, not status, and treat truncated output as "changed". The other way out is to approve removal only for worktrees that are clean when the person answers: unmerged commits only, branch kept, no force. That drops the force flag, the baseline and this bug together, but it changes the approved design, so Jackson is deciding that part.

Nit: archiving again after "Keep all" files a duplicate. 051's unique index is partial (WHERE decided_at IS NULL). ArchiveCrewService.ts:503-511 re-runs cleanup on an archive replay, and fileCleanup uses a fresh id (:513). So after "Keep all", a j5_archive_crew replay files a new item for the same worktrees.

Nit: the answer controls use the Operate-scope permissionAtom, but the server requires Owner (see #760). 051 also has no dedicated migration test.

Docs across the stack (Jackson reviews these, so for reference):

  • inbox.md's definition and AC1 don't mention the cleanup item next to AC18–22.
  • archive-flow.md "Archiving one agent removes nothing" needs the Captain exception, and AC3 still promises the workspace survives unconditionally.
  • agent-tools.md:268 says "An accepted proposal is not checked again". That is true of a retry, not of preview or approval.
  • overview.md's Inbox summary still reads "open asks".

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.

@Jacksondr5

Copy link
Copy Markdown
Owner

Review panel: Claude Opus 5.5 (lead) and GPT-6.1 Sol. We reviewed the whole stack (#750 → #762) at 16cb7824a1 as one merge. Both reviewers agreed on every finding below.

Should-fix

  1. A second archive of the same Crew never files a cleanup item. Migration 051 puts a unique index on crew_instance_id, and fileCleanup (CrewWorktrees.ts:607) inserts with ON CONFLICT DO NOTHING. But restoreWithCaptain brings a Crew back when its Captain is unarchived.

    • Scenario: archive the Captain, and the item covers seat A. Unarchive it, and seat B commits unmerged work. Archive again: B is kept as unfinished, and nothing reaches the Inbox.
    • The first item also stays open while the Crew is live again.
    • Suggestion: key the item on the archive (crew + archived_at) rather than the Crew, so a replay of one archive still dedupes. Withdraw an open item on restore.
  2. An approved removal can orphan commits the item says are kept. The approved path removes with force (CrewWorktrees.ts:531), and the item says removal keeps the branch, which is thread.branch ?? createdBranch (:633). Nothing checks that HEAD is reachable from that branch.

    • Scenario: a seat ran git checkout --detach or git switch -c other, then committed. The item shows "branch X · N commits". After removal, those commits are reachable only from the reflog.
    • Suggestion: one merge-base --is-ancestor HEAD refs/heads/<branch> in measure or the recheck. If it fails, skip the worktree as unverified.
  3. The recheck baseline ignores the index. snapshotOf (CrewWorktrees.ts:343-366) hashes porcelain status and the working-tree files, but not staged content. A file can stay MM with identical working content while its staged blob changes. The digest is the same, so the forced removal discards the newly staged work.

    • Reproduced with real git: the index went from "staged first" to "staged NEW", and both digests were 87baf444….
    • Suggestion: add git write-tree (the index tree id) to the baseline.

Nits

  1. The answer buttons and the server disagree on who may answer. The buttons are gated on permissionAtom (operate scope), but the RPC uses requireOwner.
    • A Collaborator with operate scope sees enabled Remove and Keep buttons, then gets "Only an Owner of this server archives a Crew".
    • The open-inbox count also adds cleanup items for people who can't answer them.
    • The Inbox header counts cleanup items as "questions".

Live, Sol archived a worktree Crew and got one item for the dirty worktree. Removing it from the Inbox deleted the directory and kept the branch.

bryantderosier and others added 10 commits November 2, 2026 09:34
…val layer

The Inbox's open count still includes worktree cleanups, which the
mobile Inbox doesn't show yet; the Inbox doc says so.

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

The cleanup item is now keyed on the archive (the Crew and its archived stamp), so the same archive
run again still files nothing, while a Crew restored with its Captain and archived a second time
files a new one. Bringing the Crew back withdraws an item still open for the earlier archive. An
answered item stays as the record. Migration 051 is edited in place: it is only in this unmerged stack.

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

An approved removal keeps the branch, so work only counts as kept when HEAD is reachable from that
branch. A seat that detached or switched branches and then committed is kept as unverified, and the
recheck refuses it too.

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

The baseline now includes the index tree, so a file that stays modified in the same way with the
same working copy, while its staged content changes, no longer matches and the removal is skipped.
An index git cannot write a tree for (unmerged entries) never matches, so the worktree is kept.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Answering a cleanup is the Owner's call, but the buttons were gated on operate scope, so a
Collaborator saw them enabled and was refused on press, and the Inbox counted items they could not
answer. The answer now needs the settings scope an Owner's device holds, on the client and the
server, the cleanup list and the open count are an Owner's alone, and the Inbox header counts
cleanups as their own clause instead of as questions.

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

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

Copy link
Copy Markdown
Collaborator Author

Went through the list:

  1. Second archive: the item is keyed on the archive now, so a re-archive after restore files its own, and restoring a Crew with its Captain withdraws an open one (2a7be7490c).
  2. Orphaned commits: a worktree whose HEAD isn't held by its branch is kept as unverified and never offered for removal, and the recheck refuses the same case (cabe7159bf).
  3. Index in the baseline: the recheck baseline includes git write-tree now. Added a test with the staged-first to staged-NEW case (d700a5cdd4).
  4. Who can answer: the buttons now need the same Owner level the server checks, the list and the bell count only show cleanups to an Owner, and the Inbox header counts them as their own thing instead of questions (a2c758518c).

One call I made: a withdrawn item is just deleted, so nothing records it ever existed. Easy to change to a withdrawn outcome if you'd rather.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
bryantderosier and others added 2 commits November 2, 2026 17:33
…e uses are no longer exported (#749)

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 b85f262 into j5/main Nov 3, 2026
35 checks passed
@bryantderosier
bryantderosier deleted the j5/749-worktree-cleanup-approval branch November 3, 2026 01:30
@Jacksondr5

Copy link
Copy Markdown
Owner

Re-review after merge by the panel, Claude Opus 5.5 and GPT-6.1 Sol. We read your fixes on merged j5/main, and Sol tested the risky ones live. They hold. One real nit came out of it, filed as #913.

One note for your own machines: migrations 049 and 051 changed in place after 16cb7824a1. Those versions never reached j5/main or a release, so no code change is needed, but any home that ran an older stack branch keeps the old tables and fails with "no such column: agent_display_name" or "archived_at". Reset those homes.

This branch was successfully deployed

1 active deployment
Preview — a8464361 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: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: one Inbox approval for worktrees with unfinished work

2 participants