lane-end's close-out gate: refuse while the sweep still finds the lane's trees, branches, scratch, caches or residue, --inventory-only as the logged door, and lane-worktrees add records every tree it makes (#163)

[brettheap]

What

The close-out gate of #163, stacked on #169's branch (feat/lane-worktrees-report) because it reads #168's exit contract. Lane 3 retargets it to main once #169 lands.

1. lane-end <lane> asks lane-worktrees sweep: one act that archives, rescues and removes a lane's abandoned worktrees, branches, scratch and killed-suite sandboxes after an ungraceful swap — dry run first, rescue branch or bundle before any removal, never a live writer #162's sweep before it ends a lane, and refuses while anything of the lane's is still on disk. After the in-flight guard and before any write (on --dry-run too), it runs
   lane-worktrees sweep <lane> --branches --include-scratch --include-caches --dry-run --porcelain
   and reads lane-worktrees sweep: retire a lane's abandoned worktrees, rescue first, never a live writer (#162, part 1 of 2) #168's contract:

   • 3 (something to retire) and 2 (the sweep refused the lane, or a read failed): refused, exit 2. The refusal names every tree, branch, scratch directory and cache the table gives the lane, relays the sweep's own reason where it refused, and prints the table command and the --yes that would retire them, saying --yes is off until lane-worktrees: review findings deferred from #168/#169 (incl. five --yes data-loss paths found after the two-round cap) #170;
   • any other exit, or no lane-worktrees beside the command: the gate was never read, so exit 1, never a pass;
   • 0: passes, unless one of the two checks below finds something.

2. Two reads of the gate's own, beside the table:

   • git status --porcelain --ignored on every tree of the lane's. A tree holding only an .env or a node_modules is named as holding them and never as clean. The sweep's own status read leaves ignored files out.
   • Residue. Any entry directly under the lane's own root, .lane-worktrees/<lane>/, that no tree, scratch or cache row names: for example a directory a removed tree left its ignored files in, or a brief. No sweep row reaches these, and they refuse even when the sweep answered 0. A cache row refuses at 0 too. The sweep's exit leaves caches out because they are never the lane's work, but lane-end close-out gate: refuse to end a lane whose inventory still has worktrees, branches, scratch or caches — the dry-run sweep first, lane-end --sweep --yes to retire them in the same run; landing retires its own tree #163 names them as something a lane leaves behind.

3. --inventory-only is the one door past the gate. The lane ends whatever the gate answered (found, refused, unreadable). Nothing on disk is touched, and the trees stay in the lane's Crash-consistent lane worktree recovery: a lane now says WHERE its session stopped — RUNNING → SWAPPING → SWAPPED with a generation/operation fence, a machine-readable worktree inventory taken at every handoff, and a resume reconciliation that reports and resets nothing #97 inventory, where lane-worktrees: the daily estate report, and nothing new lands beside the code (#162, part 2) #169's daily report lists them as an ended lane's. The reason it was let past is logged in two places:

   • the row's closing phrase gains ENDED WITH --inventory-only: <what the gate found>; they stay in its #97 inventory;
   • the lane's own ENDED/RETIRED line carries inventory-only: the close-out gate (sweep exit 3) found 2 tree(s) and 1 scratch dir(s) left; lane-worktrees sweep <lane> … names them.

   It does not pass the in-flight guard (that is --force), and when the gate passes it changes nothing.

4. Creation registers the tree: lane-worktrees add <lane> <slice> [--branch <b>] [--from <ref>] [--checkout <dir>] [--dry-run].

   • It makes <parent of the lane's dir>/.lane-worktrees/<lane>/<slice> as a git worktree of the lane's checkout, then records it with lanes-edit.sh set-lane-tree in the same act.
   • A new branch is made --no-track, so a bare git push never aims a writer's commits at the branch it was cut from.
   • A record that fails after the tree is made takes the fresh tree and its new branch back out (exit 2). Only if that undo also fails is the exit 1, with the record command printed.

   The lane tooling performed no git worktree add before this. lane-start makes no writer worktrees: grep -n 'worktree add' lane-start lane-end lane lane-handoff lanes-edit.sh matches only comments. Every writer's tree was a git worktree add typed into a brief, and the inventory was written only at a handoff. That is how lane 3's inventory was empty while nine trees under its root were its own. A tree made any other way (a brief's hand git worktree add, the harness's isolation: worktree) stays FOREIGN until lanes-edit.sh set-lane-tree <lane> <path> records it. That existing verb is the "adopt" of lane-end close-out gate: refuse to end a lane whose inventory still has worktrees, branches, scratch or caches — the dry-run sweep first, lane-end --sweep --yes to retire them in the same run; landing retires its own tree #163's fold, and no second verb was added for it.

5. One fix in lane-worktrees sweep: retire a lane's abandoned worktrees, rescue first, never a live writer (#162, part 1 of 2) #168's sweep that the gate needed. --branches read a lane directory that is no repository as a branch read that failed (a keep row, retire), which would have held the gate shut for every lane started outside a checkout. _branch_checkouts now skips a directory git says is no repository. A repository that cannot be read is still a keep. Found by the suite's own repoQ-1, whose recorded dir is a plain directory.

Deliberately left out

• --yes stays out of lane-end until lane-worktrees: review findings deferred from #168/#169 (incl. five --yes data-loss paths found after the two-round cap) #170 lands. There is no lane-end --sweep --yes in this PR. The seam is left: --sweep is a parsed word that refuses by name ("--sweep is not built … switched off until lane-worktrees: review findings deferred from #168/#169 (incl. five --yes data-loss paths found after the two-round cap) #170 lands"), so nothing else can take it. The refusal prints the --yes command that will retire the trees once lane-worktrees: review findings deferred from #168/#169 (incl. five --yes data-loss paths found after the two-round cap) #170 switches it back on (and, where the lane is held by this session, the --live it needs). Rows the sweep's --yes leaves anyway (keep, live, load-bearing, list) are counted and said to be a person's.

• Not built from lane-end close-out gate: refuse to end a lane whose inventory still has worktrees, branches, scratch or caches — the dry-run sweep first, lane-end --sweep --yes to retire them in the same run; landing retires its own tree #163's body, and needing lane 3's call (keep lane-end close-out gate: refuse to end a lane whose inventory still has worktrees, branches, scratch or caches — the dry-run sweep first, lane-end --sweep --yes to retire them in the same run; landing retires its own tree #163 open for them, or file them):

  • "Landing retires too", the lane-land / squash-land.sh half;
  • the two UserPromptSubmit guard checks of the first fold (an unrecorded repository under the estate, stray scratch);
  • the ignored-size threshold check of the second fold in that guard.

  This PR's --ignored read and residue check are the lane-end side of the second fold.

A consequence the lane owner should know

The sweep refuses (2) while any other lane's inventory record under the same control root cannot be read (#168's rule). So a broken sidecar anywhere in an estate's .lane-state now refuses every lane-end there until it is fixed or --inventory-only is the word. The suite's #91 section leaves such dangling sidecars on purpose. For that reason:

• this PR's own section builds its estate beside $HOME/projects and exports its own LANES_LANE_STATE_ROOT (put back at its end);
• the one existing case it reached, the workstation-seam lane-end repoWS-1 --force, now passes --inventory-only beside --force, with a comment saying why. Its assertions about the host name are unchanged.

Tests

tests/test_lane_helpers.sh, new section == opensoft/openRepoTools#163 …, with its own repository, bare origin, lanes repoCG-*, .lane-worktrees roots and control root under the suite's sandbox. The suite now copies lane-worktrees into its sandbox bin beside the other commands.

case	holds
add --dry-run	prints the path, makes nothing
add	a worktree of the lane's checkout, on the slice's branch, recorded in lane-trees (path, branch, checkout)
add --branch --from origin/main	the branch tracks nothing
add refusals	existing path (names set-lane-tree), lane with no directory, bad slice (64), a sweep flag (64)
add with the record failing (read-only trees/)	refused, the fresh tree and the new branch are gone
lane-end passes	a lane with nothing on disk, next to another lane's recorded trees in the same checkout
lane-end passes	a lane started outside any repository (the --branches fix)
lane-end refuses on 3	names both trees, the .env via git status --ignored, the untracked file, the scratch, the table, the --yes and #170, the door; row and log unchanged; also on --dry-run
--sweep	refused by name
--inventory-only past 3	the row says ENDED WITH --inventory-only and sweep exit 3, the ENDED line logs the reason, the tree and its inventory record are untouched
sweep refuses (2)	a hand-made tree under the lane root with no #97 snapshot: refused, relaying the sweep's reason; no --yes offered
residue	a plain directory under the lane root: refused at sweep 0, named, then ends once it is gone
cache	node_modules under the lane root: refused at sweep 0
branch	an unpublished local branch with this lane's Lane: trailer, held by no tree: refused, and list is said to be a person's
unreadable gate	a sweep that exits 7, and no sweep at all: exit 1, nothing written; --inventory-only ends it and the row says so
the door's scope	--inventory-only with a fork's --retire <pid> and with --retire-dormant: refused by name
round 1: add whose git worktree add fails after making the tree	a failing post-checkout hook: the registered tree and the new branch are taken back out, exit 2
round 1: unlistable lane root	mode 000: the gate is unread, exit 1, nothing written
round 2: the hook commits, then fails	the clean tree goes, the branch is KEPT holding the hook's commit, exit 1
round 2: unlistable root and the sweep answering 3	still exit 1, and the branch is still named

Red at the base head (45fa45d): the section run against the base's own lane-end/lane-worktrees (git archive of 45fa45d plus this test file): 25 passed, 72 failed of the section's 97 assertions (the 4 footer guards among the 25). Every case above has at least one assertion that fails there. Two guard cases pass there by design because the base has no gate to refuse wrongly: "a lane with nothing of its own on disk ends" and "a lane started outside any repository ends". The second is red against this head without the _branch_checkouts fix (the suite's repoQ-1 went red that way).

Local runs (Eagle):

• this section at the head (ed36551): 97 passed, 0 failed;
• the suite prefix through Addendum 5: 574 passed, 0 failed;
• the suite prefix through Amendment 15 (which holds the other ending cases, repoZG-1 and repocase-1): 2060 passed, 0 failed;
• the Amendment 13 section on its own: 123 passed;
• test_repo_hygiene.py 152/152, test_lane_worktrees.py 40/40 and the installer help tests 6/6, through a direct harness that calls the test functions, because tests/run.sh waits behind other estates' pytest runs on this workstation.

CI is the record. At ed36551 (and before it at 46f1178) the whole suite is green:

• tests: 1159 passed (40 min);
• tests-no-submodule: 947 passed, 212 skipped;
• tests-windows: 153 passed;
• parse-macos and guard-launch-mode: pass.

tests-macos waits for the ready label.

Review

• Copilot round 1 (2 threads), both fixed in 41b5a6a:

  • a lane root that cannot be listed was read as empty; it is now the gate unread;
  • a git worktree add that fails after making the tree (a failing post-checkout hook) left the tree registered; one take-back now serves both of add's failures.

• Copilot round 2 (3 threads):

  • fixed in ed36551: the take-back deletes a branch it made only while it still points at the start commit add resolved beforehand, so a commit made on it is kept;
  • fixed in ed36551: an unread root is exit 1 whatever the sweep answered;
  • filed as lane-end's close-out gate: should a lane-owned branch whose open PR is fully published hold the lane's end? (Copilot round 2 on #175, after the cap) #178: whether a lane-owned branch with a fully published open PR should hold the gate. That is a question about lane-worktrees sweep: retire a lane's abandoned worktrees, rescue first, never a live writer (#162, part 1 of 2) #168's porcelain contract, which lane-worktrees: close #170's --yes data-loss and gate holes, self-check every removal, switch --yes back on #174 is changing.

  Every thread was answered and resolved. Each fix has a shell-suite case that is red at the head before it.

• Codex was asked after each push and answered over quota.

• Sourcery skipped (review budget).

Part of #163 (the gate half; what remains of #163 is #181)

Refs #162 #168 #169 #170 #97

Lane: openRepoTools-1

🤖 Generated with Claude Code

Summary by Sourcery

Enforce lane close-out cleanliness and provide an inventory-preserving override while ensuring newly created worktrees are recorded and safely rolled back on failure.

New Features:

• Add lane-worktrees add to create lane worktrees and record them in the lane inventory atomically.
• Add lane-end --inventory-only to close lanes without removing on-disk work, while recording the gate result and preserving inventory records.

Bug Fixes:

• Prevent lane close-out from passing when lane-owned trees, branches, scratch, caches, residue, or unreadable state remain.
• Treat unreadable repository metadata as a sweep failure while allowing directories with no repository to pass as absent.
• Clean up worktrees and newly created branches when worktree creation or inventory recording fails, while preserving branches containing new commits.

Enhancements:

• Make lane-end run the worktree sweep and local status/residue checks before writing any ending state, including during dry runs.
• Document the close-out gate, inventory-only behavior, and worktree creation workflow.
• Expand lane and worktree test coverage for gate outcomes, cleanup, unreadable state, residue, caches, and inventory preservation.

Documentation:

• Document the lane close-out gate, --inventory-only, and lane-worktrees add usage and behavior.

Tests:

• Add shell coverage for worktree creation, inventory recording, close-out refusals, override behavior, residue, caches, branches, unreadable gates, and rollback scenarios.
• Add Python coverage for distinguishing unreadable repositories from directories without repositories.

[brettheap]

Results promised in the body:

• The suite prefix through Amendment 15, run locally on Eagle at 10b67c6's scripts: 2060 passed, 0 failed. It holds the other ending cases, including repoZG-1 --force and repocase-1 --force.

• CI at 46f1178, the whole suite:

  • tests: 1159 passed (41 min);
  • tests-no-submodule: 947 passed, 212 skipped;
  • tests-windows: 153 passed, 1006 skipped;
  • parse-macos and guard-launch-mode: pass.

  tests-macos waits for the ready label.

• Round 1 (Copilot, 2 threads): both fixed in 41b5a6a, each with a shell-suite case that is red at 46f1178. The section is now 91 passed locally.

[Copilot]

Copilot review overview

🟡 Changes recommended

Rollback can discard commits, and the gate can miss or misclassify lane-owned leftovers.

Review effort: Balanced
Findings: 2 · 1

Open (3)

• Lane-owned open-PR branches incorrectly allow lane closure · New
• Rollback can delete commits created by post-checkout hooks · New
• Unreadable residue root does not consistently force exit 1 · New

Resolved since last review (2)

• Roll back partially created worktrees after command failure
• Treat unreadable lane roots as a gate failure

Previously missed (1)

In code that hasn't changed since last review

Malformed Git metadata is misclassified as no repository

lane-worktrees:2636

Matching this stderr phrase also classifies a malformed or incomplete .git directory as “no repository”: Git reports “not a git repository” for that state too. The branch read is then skipped and lane-end can pass instead of emitting the required keep row for a repository that could not be read. Distinguish absence of repository metadata from present-but-invalid metadata before returning true.

[brettheap]

@codex review

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud