lane-worktrees sweep: retire a lane's abandoned worktrees, rescue first, never a live writer (#162, part 1 of 2)

[brettheap]

What

lane-worktrees sweep <lane> — the one act that retires a lane's abandoned worktrees, branches, scratch and killed-suite sandboxes after an ungraceful swap. Dry run by default; --yes performs it. One rule throughout: nothing is deleted that is not first on origin or in a bundle under ${XDG_STATE_HOME:-$HOME/.local/state}/openRepoTools/sweeps/<lane>/<UTC>/, and a tree a live writer owns is never touched. Placed by openRepoTools --install as the seventeenth file (31 artifacts).

This is the first of two stacked PRs for #162 (the core). The second — tests/run.sh's cache/temp relocation, the per-repository venv, the estate-wide --all --report run by lane-start, the <user>-wip .gitignore and the bytecode refusal — is stacked on this branch.

Why

A swap that dies on a usage limit, a killed pane or a crashed harness leaves its writers' trees as they stood, and the protocol's worktree-safety rule (a swap never commits, pushes, stashes, resets or cleans) is right to. Until now nothing retired them afterwards except a person doing it by hand. This makes that procedure one act with a dry run, a rescue before every removal, and one register line per tree.

How it decides

• Which trees are 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's inventory (lanes-edit.sh lane-trees) and the disk — never the derived index (Amendment 14 clause (b)). Registrations of the lane's checkout and checkouts under its two roots that the inventory does not name are FOREIGN: reported and left, unless --include-foreign --word "<verbatim>"; a tree another lane's inventory names is never taken.
• Who may act: 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's lane-reconcile, read before any write (the fetch included). Bound on another host/container (A18(b): unknown, never dead), held by another live session, managed-owned, or any read failed → refused, exit 2. Held by THIS session → --yes needs the coordinator's writer count: --live <worktree> per live writer, or --live none (A17 Addendum 1 (i)).
• "Merged": the register's LANDED line for the branch's PR, or gh pr list's MERGED, into the default branch, and that PR's head must hold the tip. It is never git branch --merged alone (squash merges). An OPEN PR protects its branch before any older merged PR counts.

The disposition table, as implemented (first matching row decides)

tree	disposition	--yes
not in the inventory	foreign	nothing
a process's cwd or open file in it (/proc, else lsof), a tmux pane in it, named by --live, the sweep started inside it, or its recording session live	live	nothing — re-checked at the moment of the act
directory gone, still registered	prune	git worktree remove <path> (that one registration)
directory gone, unregistered	gone	nothing
locked registration; dirty or unpushed submodule; a repo nested inside; a clone with a branch/stash origin lacks	keep	nothing, with the reason
something leans on it (alternates, local-path remote)	load-bearing	never removed; dependents and remedy named
dirty / untracked	wip-rescue+remove	git add -A into a copy of the index → commit-tree → rescue/<lane>/<slice>-<UTC> pushed and seen on origin, bundled, removed
detached, on origin	remove	removed
detached, own commits	rescue+remove	rescue branch pushed, bundled, removed
merged (register or gh)	remove+delete-branch	removed; local branch deleted; remote too where its Lane: trailer is this lane's and it holds nothing beyond the PR
clean, everything on origin	remove	removed; branch stays (an open PR untouched)
unpublished on main/master, or origin diverged	rescue+remove	tip to a rescue branch; never force-pushed
unpublished otherwise	push+remove	pushed as is under its own name — never its upstream's

At removal the head is re-read and the tree must still be clean, or byte for byte the rescued tree. A refused push leaves the tree exactly as it was (the WIP commit is made beside it). Ignored non-cache, non-build files (an .env) are archived first. Also --branches, --include-scratch (tar + sha256 → remove), --include-caches, --include-sandboxes (owning pid gone), --links, --bundle, and sweep --expire (90 days, sweep.conf; never an archive whose rescue branch left origin). Every archive carries MANIFEST.sha256, DISPOSITION.md and rescues.tsv; one NOTED line per tree acted on, written after the act.

The exit contract for #163

lane-worktrees sweep <lane> --dry-run --porcelain: lane row, optional refused row, one tree/branch/scratch/cache/sandbox/link row each, summary <to retire> <trees> <live> <foreign>; exits 0 nothing to retire, 3 something to retire, 2 refused. --yes: 0 done, 1 an act failed part-way; usage 64.

Two defects the real-data dry run caught before review

1. A branch made with git worktree add -b X origin/main tracks origin/main; "push to its upstream" would have pushed a lane's stray commits onto main. The push target is now always the branch's own name (read_tree, with a comment).
2. With --yes the fetch ran before the lane gate refused, so a refused run still wrote FETCH_HEAD. The gate now decides before any write; the parametrized refusal case snapshots the whole estate.

Tests

tests/test_lane_worktrees.py (40 cases after review rounds 1-2 and the adversarial review; fake lanes-edit.sh/gh/tmux, bare origin behind a url.insteadOf, everything under tmp_path; the two last cases run the real lanes-edit.sh):

case	holds
every disposition row in the dry run	13 states row for row; whole-estate snapshot unchanged; no sweeps dir; no register line
--yes performs the table	pushes, rescue branches on origin, WIP subject (lane/slice/UTC/"swept, not reviewed") and parent, bundles, .env archived without bytecode, manifest verifies, one NOTED per tree with no , /—/reserved words
rescue on origin before removal	origin refuses rescue/* → exit 1, tree byte-identical, branch/index unmoved, no NOTED
a live writer is never touched	process cwd and a tmux pane
the coordinator states its writer count	holder = this session: --yes refused without --live; --live <path> keeps it
refused live elsewhere / unread (×4)	bound elsewhere, binding unread, held by another session, holder unread → 2 for dry run and --yes, estate unchanged
managed lane	refused
merged = register or gh, never ancestry	register LANDED beats a stale OPEN; a tip on main with no PR keeps its branch
without gh nothing is merged	LANES_NO_GITHUB=1
--include-foreign takes a word	refused without --word; another lane's tree never taken
--branches	merged deleted (+remote when ours), theirs local only, open PR kept, unpublished listed with tip/distance/owner, rescue/* untouched
scratch and caches	archived without caches; a kept tree's caches removed, a live tree's left
sandboxes	dead .lock pid and old tmp.* removed; young, held and live-lock kept
--links	dangling symlink and moved gitdir pointer listed
load-bearing clone	--shared dependent → never removed, dependents + repack named
--expire	89 kept; 90 and no-rescue expired; kept when the rescue is gone from origin, when it is on origin at another SHA, when the archive has no manifest, and when it holds a file its manifest does not list; retention_days honoured
porcelain exit codes	0 / 3 / 2 and the lane/summary rows
usage	64
real helper: inventory and register line	set-lane-tree inventory → removed; FOREIGN left; the NOTED line lands in the lane's own log
real helper: bound on another host	2 for dry run and --yes
round 1: merge into another base / open PR first	release/1 merge is no landing; open #43 protects despite merged #42; both branches kept
round 1: contested tree	another lane's inventory also names it → kept
round 1: clone with linked worktrees	kept
round 1: unreadable inventory record	refused, exit 2, dry run and --yes, estate unchanged
round 1: lane name resolved first	REPOA-1 → repoA-1 via canon-lane; 66 refuses
round 1: caches of a FOREIGN tree	never taken
round 1: branch deletes need a fetch that worked	origin unreachable under --yes → keep, branch intact
round 1: origin-less worktree, --bundle --yes	bundled and removed, as the dry run says
round 1: unreadable distance to origin	origin's tip object missing → keep

Plus the installer/hygiene suites updated for 17 files / 31 artifacts and lane-worktrees compiled beside lanes-index. Locally every case above was exercised; the tests/run.sh run is queued behind other estates' pytest runs on Eagle, so CI is the record.

Measurements — Eagle, lane openRepoTools-3, read-only dry runs (nothing was run with --yes)

run	time	exit	what it WOULD do
sweep openRepoTools-3 at 7e58b98	10.3 s	0	13 trees, all FOREIGN: the lane's #97 inventory is empty (snapshot NONE — no handoff since #97 landed). This exit 0 was the B1 defect: the gate passed a lane with 7 trees under its own root
sweep openRepoTools-3 --dry-run --porcelain at 296e2f0	12.6 s	2	refused: snapshot NONE, yet 9 trees are the lane's (7 under .lane-worktrees/openRepoTools-3/, 2 in .claude/worktrees by their Lane: trailer); summary 9 13 4 4
sweep openRepoTools-3 --yes --live none at 296e2f0	0.1 s	2	refused: --yes is disabled until opensoft/openRepoTools#170 lands
… --include-foreign --branches --include-scratch --include-caches	11.1 s	3	7 live (3 by a process's cwd — incl. the sibling a14-worktrees writer and this writer's own tree — and 4 FOREIGN active within 24 h); 5 remove+delete-branch (nw-a18, nw-a18-add1, nw-a18-add2, nw-a19 merged by register LANDED; feat/claude-current by gh, PR #134); 1 remove (001-separate-swap-ctx-handoff, clean, on origin); 2 review branches listed, never deleted; 7 scratch dirs to archive (~148 MB: featlist-scratch 86.7 MB, dash-scratch 38.6 MB, wb71-scratch 19.2 MB, a11-scratch 3.2 MB, three small); 0 caches outside the scratch
… --links	27 s (the walk: 245 s → 16.7 s after the scandir commit)	0	402 broken links across /workspace/projects, 99 of them worktree gitdir pointers
… --include-sandboxes	15.7 s	0	61 mktemp sandboxes in /tmp, each over an hour old with no live process standing in, holding or naming it
sweep --expire	0.2 s	0	no archives yet

Review round 1 (Copilot, 23 threads)

22 were taken in bf066fd and documented in ae17742. Each new or extended case fails against 7e58b98 and passes at ae17742:

• merged requires the default branch as base, and open PRs are checked first;
• a failed rev-list is a read error, never "0 ahead";
• clones whose git directory linked worktrees share are kept;
• contested inventory claims are kept;
• unreadable inventory records refuse the sweep;
• canon-lane runs first;
• liveness is asked afresh before the rescue and again just before removal, and an unavailable scan leaves the tree;
• branch deletes are fenced to the judged SHA (update-ref -d <old>, --force-with-lease) and every failure is counted;
• + remote is written only when the remote delete happened;
• --branches fetches its checkouts, and a failed fetch deletes nothing;
• no repository-wide prune;
• a failed ignored-file listing stops the act;
• archive directories are created exclusively;
• scratch removal requires no new writer and unchanged content;
• caches never come from a FOREIGN, live or unknown tree, and the owning tree is rechecked at the act;
• an origin-less tree under --bundle --yes is bundled and removed;
• --expire requires the exact rescued SHA and a whole archive (manifest-verified, rescues.tsv parseable).

The one not taken (tmp.* sandboxes, which carry no ownership evidence) is a design question about #162's own table, filed as #170. Every thread was answered and resolved.

The read-only dry run on this lane at ae17742 gives the same answer as before (exit 3, 10.5 s): 7 live, 5 remove+delete-branch, 1 remove, 7 scratch. The open PR's own branch feat/lane-worktrees-sweep is now keep.

Review round 2 (Copilot, 8 threads)

7 were taken in 3c0b188. Each new or extended case fails against ae17742:

• an unreadable claim by another lane refuses the sweep before any write;
• a submodule's ignored .env keeps the tree;
• ignored files are re-listed at removal and compared with what was archived;
• a reappeared prune candidate is left;
• a pytest sandbox's .lock is re-read at the act;
• tracked() reports an unknown when it cannot read, and the cache is left;
• a manifest entry whose file is gone makes the archive not whole.

The one not taken (unreadable /proc entries of same-account processes) is #170 item 2. On Eagle there are always about 9 of them (6 timeout, 3 ssh-agent), so reading them as unknown would keep every tree on every sweep.

Copilot's third round (5 threads, after the cap): filed as #170 items 4-8 and resolved. These are real --yes / --expire --yes data-loss paths:

• tag-only commits in a clone;
• a submodule's unpublished branches or stash;
• a mirror-style fetch refspec under --prune;
• scratch holding nested trees;
• a bundle-only rescue missing from the ledger.

They should be fixed before the sweep's first --yes on real trees. The dry run, which is all #163's gate reads, is unaffected.

CI at 3c0b188: green. tests 959 passed; tests-no-submodule 751 passed, 208 skipped; tests-windows 153 passed, 806 skipped; guard-launch-mode and parse-macos pass; tests-macos waits for the ready label.

The Opus adversarial review of 3c0b188 (standing in for Codex, which is over quota)

Its verdict was "must not land as is", reproduced with probes against the suite's own Estate fixture. Taken in 5f4bd84 and documented in 296e2f0:

1. --yes and --expire --yes are switched off (exit 2, nothing changed) unless LANE_WORKTREES_ENABLE_YES=1 is set. The test Estate sets it; the manual says it is not for a real estate until lane-worktrees: review findings deferred from #168/#169 (incl. five --yes data-loss paths found after the two-round cap) #170 lands. The dry run, --porcelain and --report are unaffected.
2. B1: an unrecorded tree under .lane-worktrees/<lane>/, or in .claude/worktrees on a branch whose own commits carry the lane's Lane: trailer, is the lane's. A NONE snapshot with such trees is refused, exit 2. Eagle went from exit 0 to exit 2 (table above).
3. B2: subprocess output and git metadata files are decoded with surrogateescape, and an unreadable pytest-of-$USER is a kept row. A catch-all keeps errors no read caught inside the contract: exit 2 on a dry run; under --yes, DISPOSITION.md first, then exit 1.
4. B3: porcelain fields escape \\, TAB, LF and CR, and registrations are read with git worktree list -z. The escaping is documented in --help and the manual.

There are five new cases (40 in all), each failing against 3c0b188. A1-A11, B4-B6, C1, C4-C6 and E1-E7 are in #170's new table; the --yes switch stands until they land.

Part of #162. Refs #97 #161 #163 #164 brettheap/new-workstation#48

Lane: openRepoTools-3

🤖 Generated with Claude Code

Summary by Sourcery

Add a safety-gated, rescue-first sweep command for retiring abandoned lane worktrees without touching live writers or losing recoverable data.

New Features:

• Add the lane-worktrees sweep command for dry-run inspection and controlled retirement of abandoned lane worktrees, branches, scratch areas, caches, sandboxes, and links.
• Provide rescue-first cleanup with origin or bundle preservation, liveness protection, merged-branch handling, archive retention, porcelain output, and defined exit codes.

Bug Fixes:

• Prevent pushes to an upstream such as main by targeting unpublished work under its own branch name.
• Refuse before fetching or writing when lane ownership, reconciliation, or safety information cannot be established.

Enhancements:

• Expand installer support and documentation from sixteen to seventeen shipped files and thirty-one artifacts.
• Add comprehensive coverage for worktree dispositions, safety refusals, rescue behavior, archives, retention, porcelain output, and real helper integration.

Documentation:

• Document sweep usage, ownership rules, disposition behavior, safety guarantees, archive format, retention configuration, and the porcelain contract.

Tests:

• Add an extensive lane-worktrees test suite covering dry runs, cleanup actions, liveness, ownership, branches, caches, sandboxes, links, bundles, expiration, encoding, and refusal cases.

Chores:

• Compile and ship lane-worktrees alongside the existing command set.

[brettheap]

@codex review

[sourcery-ai]

Sorry @brettheap, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 4 days by commenting @sourcery-ai review. Upgrade to get a review now.

[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.

[sourcery-ai]

Reviewer's Guide

Introduces a safety-first lane-worktrees sweep command that inventories and gates lane ownership, protects live writers, rescues recoverable work before any deletion, archives evidence, and exposes porcelain exit semantics; integrates it into the installer and documentation with broad isolated-estate coverage.

Sequence diagram for a safe lane worktree rescue and removal

sequenceDiagram
    participant Sweep as lane-worktrees
    participant Reconcile as lanes-edit.sh
    participant Git as Git repository
    participant Origin as Origin remote
    participant Archive as Sweeps archive
    participant Register as Lane register

    Sweep->>Reconcile: lane-reconcile
    Reconcile-->>Sweep: ownership and writer state
    Sweep->>Git: fetch
    Sweep->>Git: git add -A on a copy of the index
    Sweep->>Git: commit-tree
    Sweep->>Origin: push rescue branch
    Origin-->>Sweep: rescue branch visible
    Sweep->>Archive: write bundle and manifest
    Sweep->>Git: re-read head and verify tree
    Sweep->>Git: git worktree remove path
    Sweep->>Register: lanes-edit.sh log NOTED

Loading

State diagram for lane worktree sweep dispositions

stateDiagram-v2
    [*] --> Inventory
    Inventory --> Foreign: not in lane inventory
    Inventory --> GateRefused: ownership or reconciliation refused
    Inventory --> Live: live writer detected
    Inventory --> Unsafe: locked, dirty dependency, nested repo, or load-bearing
    Inventory --> Candidate: eligible tree
    Candidate --> Rescue: dirty or unpublished work
    Candidate --> Remove: clean and recoverable
    Candidate --> Prune: registered path is gone
    Rescue --> Remove: rescue pushed and bundled
    Remove --> Noted: removal verified
    Prune --> Noted: registration removed
    Foreign --> [*]
    GateRefused --> [*]
    Live --> [*]
    Unsafe --> [*]
    Noted --> [*]

Loading

Flow diagram for the lane-worktrees sweep decision process

flowchart TD
    A[lane-worktrees sweep lane] --> B[Read inventory and disk]
    B --> C[Read lane-reconcile before writes]
    C --> D{Gate refused?}
    D -->|Yes| E[Report refused and exit 2]
    D -->|No| F[Classify trees and related items]
    F --> G{Live writer or foreign?}
    G -->|Live| H[Report live and never touch]
    G -->|Foreign| I[Report foreign and leave]
    G -->|Candidate| J{Recoverable before removal?}
    J -->|Dirty or unpublished| K[Rescue to origin and bundle]
    J -->|Clean and safe| L[Remove or prune registration]
    J -->|Unsafe or load-bearing| M[Keep with reason]
    K --> N[Re-check head and tree]
    L --> N
    N --> O{--yes?}
    O -->|No| P[Dry-run table]
    O -->|Yes| Q[Archive evidence and write NOTED]
    P --> R[Porcelain summary and exit 0 or 3]
    Q --> S[Exit 0 or 1]

Loading

File-Level Changes

Change	Details	Files
Add the lane-worktrees sweep command with dry-run and destructive execution modes, including lane ownership, reconciliation gates, liveness checks, disposition classification, rescue-before-removal, archival, and register logging.	Discover candidates from the lane inventory and filesystem while distinguishing foreign, missing, locked, load-bearing, and live trees. Refuse unsafe operations for remote bindings, unreadable reconciliation state, managed lanes, other live sessions, and unacknowledged writers. Classify branches and worktrees using origin state plus register/GitHub merge evidence, avoiding ancestry-only merge detection. Rescue dirty, detached, diverged, or otherwise unpublished work to origin-backed rescue branches or bundles before removal. Re-check tree state and liveness immediately before acting, preserving trees when pushes or safety checks fail. Write sweep archives, manifests, disposition records, rescue metadata, ignored-file/scratch archives, and post-action NOTED register entries. Support optional branch, scratch, cache, sandbox, link, foreign, bundle, and archive-expiration sweeps with configurable retention and safety thresholds.	lane-worktrees docs/README-lanes.md
Define and test the machine-readable sweep contract and comprehensive safety behavior across simulated and real lane-helper estates.	Add 23 test scenarios covering every disposition, dry-run immutability, rescue failures, live writers, coordinator writer counts, refusal states, merge evidence, foreign trees, auxiliary artifacts, load-bearing clones, expiration, porcelain output, and usage codes. Exercise real lanes-edit.sh inventory/reconciliation/register behavior in end-to-end cases. Use isolated temporary Git estates with fake GitHub, tmux, and helper integrations, including origin URL rewriting and snapshot-based no-change assertions.	tests/test_lane_worktrees.py
Integrate lane-worktrees into installation, documentation, artifact accounting, and hygiene checks as the seventeenth installed file and thirty-first artifact.	Fetch, install, report, and validate the new command alongside existing artifacts while preserving all-or-nothing installation planning. Update user-facing counts, command listings, installer expectations, and historical artifact documentation. Compile the shipped Python command in repository hygiene tests.	openRepoTools README.md AGENTS.md tests/test_install_skill_and_hook.py tests/test_openrepotools_command.py tests/test_repo_hygiene.py

Possibly linked issues

• 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: The PR implements issue 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 core lane-worktrees sweep and is explicitly identified as the first stacked part of that issue.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[Copilot]

Copilot review overview

🟡 Changes recommended

Unresolved cleanup safeguards can delete active resources or recovery data without sufficient ownership, liveness or preservation checks.

Review effort: Balanced
Findings: 16 · 7

Open (23)

• Require PR merges into the intended base branch · New
• Prioritize protection of outstanding open PRs · New
• Treat failed commit-distance reads as unknown · New
• Protect clones with external linked worktrees · New
• Abort cleanup when ignored-file inventory fails · New
• Protect competing inventory claims from tree removal · New
• Fetch all branch-sweep checkouts before destructive actions · New
• Protect foreign trees and unknown-liveness caches · New
• Allocate unique archive directories per sweep · New
• Avoid pruning unrelated registrations on removal failure · New
• Require fresh successful liveness checks before rescue and removal · New
• Prevent ref deletion after branch movement · New
• Recheck liveness and archive contents before scratch deletion · New
• Recheck owning tree liveness before cache deletion · New
• Verify rescue branch SHA before archive expiration · New
• Retain archives when rescue ledger verification fails · New
• Canonicalize lane names before deriving paths and ownership · New
• Refuse cleanup when inventory records are unreadable · New
• Allow origin-less bundle-only cleanup with --yes · New
• Count branch deletion failures in sweep results · New

And 3 more that still need to be addressed.

What changed in this PR

Adds the core lane-worktree retirement command for #162, providing cleanup and recovery support ahead of lifecycle integration.

Changes:

• Adds dry-run planning, rescue, cleanup and archive retention.
• Installs lane-worktrees as the seventeenth shipped file.
• Documents behavior and adds isolated regression coverage.

File	Description
tests/​test_repo_hygiene.py	Compiles the new Python command.
tests/​test_openrepotools_command.py	Updates installer and help expectations.
tests/​test_lane_worktrees.py	Adds sweep and recovery tests.
tests/​test_install_skill_and_hook.py	Updates artifact-count wording.
README.md	Updates installation documentation.
openRepoTools	Installs and advertises the command.
lane-worktrees	Implements sweep planning and execution.
docs/​README-lanes.md	Documents safeguards, options and exit codes.
AGENTS.md	Updates the shipped-file count.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🟡 Changes recommended

Unresolved ownership, liveness, and content-preservation checks can allow deletion of live or unarchived work.

Review effort: Balanced
Findings: 7 · 1

Open (8)

• Unreadable /proc entries can hide live writers · New
• Submodule ignored files can be deleted without archiving · New
• Unreadable competing inventories allow ownership conflicts · New
• Reappeared prune paths can delete restored worktrees · New
• Ignored file changes after archiving can be lost · New
• Stale sandbox owner checks can delete active sandboxes · New
• Failed tracking reads can schedule caches for deletion · New
• Missing manifest entries are not rejected during verification · New

Resolved since last review (23)

• Retain archives when rescue ledger verification fails
• Verify rescue branch SHA before archive expiration
• Recheck owning tree liveness before cache deletion
• Recheck liveness and archive contents before scratch deletion
• Prevent ref deletion after branch movement
• Require fresh successful liveness checks before rescue and removal
• Avoid pruning unrelated registrations on removal failure
• Allocate unique archive directories per sweep
• Protect foreign trees and unknown-liveness caches
• Fetch all branch-sweep checkouts before destructive actions
• Protect competing inventory claims from tree removal
• Abort cleanup when ignored-file inventory fails
• Protect clones with external linked worktrees
• Treat failed commit-distance reads as unknown
• Prioritize protection of outstanding open PRs
• Require PR merges into the intended base branch
• Require ownership and dead-owner evidence for tmp cleanup
• Report branches when ancestry reads fail
• Only record successful remote deletions
• Count branch deletion failures in sweep results

And 3 more resolved.

[Copilot]

Copilot review overview

🔵 Needs a closer look

Unresolved data-preservation risks in destructive cleanup require human review and disposition.

Review effort: Balanced
Findings: 5

Open (5)

• Publication check misses unpublished commits reachable only from tags · New
• Submodule checks miss unpublished branches and stashes · New
• Mirror fetch refspec can make prune delete local-only branches · New
• Scratch cleanup can delete nested protected worktrees · New
• Expiry can delete origin-less detached commits with empty rescue ledger · New

Resolved since last review (8)

• Failed tracking reads can schedule caches for deletion
• Stale sandbox owner checks can delete active sandboxes
• Ignored file changes after archiving can be lost
• Reappeared prune paths can delete restored worktrees
• Unreadable competing inventories allow ownership conflicts
• Submodule ignored files can be deleted without archiving
• Unreadable /proc entries can hide live writers
• Missing manifest entries are not rejected during verification

[Copilot]

Copilot review overview

🔵 Needs a closer look

Unresolved ownership and discovery issues, alongside deferred destructive-operation safeguards, require human review.

Review effort: Balanced
Findings: 1 · 2

Open (3)

• Keep standalone clones foreign to automatic ownership · New
• Refuse incomplete discovery after worktree listing failures · New
• Count unpublished commits on open PR branches · New

Resolved since last review (5)

• Expiry can delete origin-less detached commits with empty rescue ledger
• Scratch cleanup can delete nested protected worktrees
• Mirror fetch refspec can make prune delete local-only branches
• Submodule checks miss unpublished branches and stashes
• Publication check misses unpublished commits reachable only from tags

[Copilot]

Copilot review overview

🔵 Needs a closer look

Ownership and dry-run correctness concerns, alongside deferred cleanup hazards, require a final human landing decision.

Review effort: Balanced
Findings: 3

Open (3)

• Propagate worktree inventory read failures · New
• Resolve nested lane control roots before granting ownership · New
• Check branch publication before marking lane work unfinished · New

Resolved since last review (3)

• Keep standalone clones foreign to automatic ownership
• Count unpublished commits on open PR branches
• Refuse incomplete discovery after worktree listing failures

[Copilot]

Copilot review overview

🔵 Needs a closer look

Unresolved inventory handling and deferred cleanup safety risks require final human review.

Review effort: Balanced
Findings: 1

Open (1)

• Reject malformed sidecar rows instead of silently skipping worktrees · New

Resolved since last review (3)

• Check branch publication before marking lane work unfinished
• Resolve nested lane control roots before granting ownership
• Propagate worktree inventory read failures

[sonarqubecloud]

Quality Gate passed

Issues
54 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