@erclx/canon 4.12.0 → 4.14.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.12.0",
+  "version": "4.14.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/canon-feedback-file/SKILL.md

@@ -69,6 +69,8 @@ Detect whether `canon` is on PATH:
 command -v canon >/dev/null 2>&1
 ```
 
+Before either pipe below, run the scan in `${CLAUDE_SKILL_DIR}/../../standards/publish.md` against the composed block. `.canon/review/` is gitignored, so no hook reaches either write, and this scan is the only gate. The banned-character half runs on both branches, including the local write. The phase-label half applies only on the `--github` branch, where the block reaches a remote.
+
 If present, pipe the block to `canon feedback`. The CLI writes to its own repo's `.canon/review/feedback/feedback-<slug>-<ts>.md` and prints the absolute path on stdout:
 
 ```bash

package/claude/skills/canon-feedback-triage/SKILL.md

@@ -45,7 +45,7 @@ State the class and the one-line reason per issue before routing. Do not batch u
 
 - Direct fix: rename the branch to a conventional name (invoke `git-branch`), make the edit, then open the PR with `git-pr`.
 - Plan-worthy: invoke `claude-feature` with the issue body as the feature description. Let it write the plan and stop. Hand the plan slug back to the user. Do not implement.
-- Needs clarification: `gh issue comment <n> --body "<one question>"`, then move on.
+- Needs clarification: run the scan in `${CLAUDE_SKILL_DIR}/../../standards/publish.md` against the question first, since it reaches the remote with nothing else checking it and this scan is the only gate. Then `gh issue comment <n> --body "<one question>"`, and move on.
 
 Match one issue to one branch and one PR. A single feedback issue is a single unit of work.
 
@@ -54,7 +54,7 @@ Match one issue to one branch and one PR. A single feedback issue is a single un
 Link every fix back to its issue so the queue drains on merge.
 
 - For a PR-backed fix, add a `Closes #<n>` line to the PR body so GitHub closes the issue on merge. When `git-pr` regenerates the body, keep that line.
-- For a fix that ships without a PR, close it directly: `gh issue close <n> --comment "Fixed in <commit or PR url>."`
+- For a fix that ships without a PR, run the scan in `${CLAUDE_SKILL_DIR}/../../standards/publish.md` against the close message first, since it reaches the remote with nothing else checking it and this scan is the only gate. Then close it directly: `gh issue close <n> --comment "Fixed in <commit or PR url>."`
 - For a plan-worthy route, leave the issue open. It closes when the resulting PR merges with its `Closes #<n>` line.
 
 ## Notes

package/claude/skills/claude-pr-review/SKILL.md

@@ -119,7 +119,7 @@ Test every ticked box too, bounded to one naming a file or a command. Confirm wh
 
 Test what `## Key Changes` claims against the diff it describes, with `canon pr key-changes <number> --json`. This repository squash-merges, so that section becomes the commit message and the record on the trunk once the branch is gone, which is the same thing a stale ticked box corrupts. Branch on the record rather than on the exit code, which a shell function wrapping `canon` can flatten to zero.
 
-Read `unmet` as a `should-fix` finding under the same `**PR body**` block the stale box takes, one entry per path, quoting the bullet the record carries on `preview` and naming the `head` the comparison ran at. Read the bullet before filing it, since one class survives the reader: a bullet citing where something is defined while claiming an edit elsewhere, which puts a real path in the claim region and points the change at a locative the path does not name. Report that as the class rather than as a stale claim. A body is edited between pushes, so the reading is true at that commit and can be false a minute later. Read `unnamed` as a question rather than a finding, since the class covers a real omission and equally a lockfile, a generated asset, or a regenerated index that earns no bullet, and raise it only where a reader would want the bullet. Report `unresolved` nowhere: a path written partially was judged in neither direction and says nothing about the body.
+Read `unmet` as a `should-fix` finding under the same `**PR body**` block the stale box takes, one entry per path, quoting the bullet the record carries on `preview` and naming the `head` the comparison ran at. Read the bullet before filing it, since one class survives the reader: a bullet citing where something is defined while claiming an edit elsewhere, which puts a real path in the claim region and points the change at a locative the path does not name. Report that as the class rather than as a stale claim. A body is edited between pushes, so the reading is true at that commit and can be false a minute later. Read `unnamed` for yourself and raise nothing off the count. The class still covers a real omission and equally a generated asset or a regenerated index that earns no bullet, and the entries the reader can name as owing none are already held apart under `incidental`. Open the section and confirm no bullet names the file before putting a single one to the author, because this instruction has sent the question to three pull requests in one day over bullets that had named the files all along, and one of those authors added bullets nobody needed. Report `unresolved` and `incidental` nowhere: the first was judged in neither direction and the second owes no bullet, so neither says anything about the body.
 
 A `reason` of `no-claims` means the reader resolved no path out of a section that exists, which is the extractor failing over prose rather than the body being wrong. Say so and raise nothing. `no-section` is the body carrying no such heading, which is a finding only where the pull request template asks for one.
 

package/docs/agents/commands.md

@@ -51,6 +51,7 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 | `canon migrate record-tree`   | Repoint the old-root citations inside the records themselves, scoped to the live folders and reporting every line without `--write` (`--root`, `--json`)              |
 | `canon sessions list`         | Resolve live sessions to the worktree and branch each holds, filtered by `--branch` (`--json`)                                                                        |
 | `canon worktrees list`        | Report which worktrees are reclaimable, keyed on the pull request having merged, with every refusal and the removal route named (`--json`)                            |
+| `canon worktrees reclaim`     | Remove every reclaimable worktree and the branch behind it, reporting without acting under `--dry-run`                                                                |
 | `canon comments scan`         | Measure comment density by language and comment kind, with a trend recomputed from git                                                                                |
 | `canon context audit`         | Report required sections, length, cited paths, reference form, catalog tables, provenance, superseded-decision narration, and index drift                             |
 | `canon markdown audit`        | Fail any markdown path on a banned character, word, or spelling, and report the structural checkpoints                                                                |

package/docs/agents/index.md

@@ -23,7 +23,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Indexes](indexes.md): Flags, exit codes, and JSON shape for canon indexes regen, plus when it auto-stages what it rewrote
 - [Install and sync](install-and-sync.md): What each install and sync verb writes, refuses, or leaves alone, and how drift is attributed in a target project
 - [Intake](intake.md): Reading intake folder counts and items, the three read states an item can be in, landing a batch of selections in one cluster, the refusal reasons, and why a call is scoped to one file
-- [Key Changes bijection](key-changes.md): Comparing the files a pull request body's Key Changes names against its own diff, the two directions and why they are graded apart, the span rules the extractor was measured into, and the three refusals that separate a clean pass from a read that produced nothing
+- [Key Changes bijection](key-changes.md): Comparing the files a pull request body's Key Changes names against its own diff, the two directions and the split inside each that decides what is worth raising, the span rules the extractor was measured into, and the three refusals that separate a clean pass from a read that produced nothing
 - [Label coverage](label-coverage.md): Reading a changed set against the pull request label map, the two tables it matches, how a gap is separated from a decision, and why an absent map is an answer
 - [Markdown audit](markdown-audit.md): Running the audit over any markdown path, where its bans and checkpoints are read from, what each check reports, and why the ban half gates while the structural half reports
 - [Output shape](output-shape.md): Two framed shapes every command renders into, how JSON and --names modes keep stdout clean, and the exit discipline that lets piped output drain
@@ -45,4 +45,4 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Tasks](tasks.md): Selecting a shipped task by stem or pull request, recording a number and closing an outcome, the refusal reasons, the board and backlog checks validate runs, and why the board root defaults to the main worktree
 - [Teach](teach.md): Listing learning workspaces and the ordinal a new one takes, opening one with its required files, recording sources and glossary terms, resolving what the next lesson needs before it is written, the refusal reasons, and why every write here runs through a verb
 - [Test order](test-order.md): Reading where an implementation reached history ahead of its test, how a pair is decided, the three verdicts, the coverage the pairing cannot reach, and why the check reports rather than gates
-- [Worktrees](worktrees.md): Reporting which worktrees are reclaimable, why the reading keys on the pull request rather than on git ancestry, the refusals it names, and the two removal shapes
+- [Worktrees](worktrees.md): Reporting which worktrees are reclaimable, removing the ones that are, why the reading keys on the pull request rather than on git ancestry, the refusals it names, and the two removal shapes

package/docs/agents/key-changes.md

@@ -1,6 +1,6 @@
 ---
 title: Key Changes bijection
-description: Comparing the files a pull request body's Key Changes names against its own diff, the two directions and why they are graded apart, the span rules the extractor was measured into, and the three refusals that separate a clean pass from a read that produced nothing
+description: Comparing the files a pull request body's Key Changes names against its own diff, the two directions and the split inside each that decides what is worth raising, the span rules the extractor was measured into, and the three refusals that separate a clean pass from a read that produced nothing
 ---
 
 # Key Changes bijection
@@ -32,19 +32,24 @@ That view caps its file list at 100 rows and says nothing about having done so,
 
 They are reported apart because they want different tolerances.
 
-- **`unmet`** is a whole path the body claims and the diff does not carry. This is the graded direction and it sets the exit code. A bullet naming an untouched file is wrong more often than not, and it corrupts the record that reaches the trunk.
-- **`unnamed`** is a changed file no bullet reached. Reported with no grade, since the class covers a real omission and equally a lockfile, a generated asset, or a regenerated index that earns no bullet. Grading it would fire on nearly every branch.
-- **`unresolved`** is a path written partially, such as `claude-worker/SKILL.md` for a file under `claude/skills/`. It is judged in neither direction.
+- **`unmet`** is a whole path the body claims ahead of its bullet's first comma and the diff does not carry. This is the graded direction and it sets the exit code. A bullet naming an untouched file is wrong more often than not, and it corrupts the record that reaches the trunk.
+- **`unnamed`** is a changed file no bullet reached that a reader might have wanted one for. Reported with no grade, since a change can be too small to describe and still be correctly absent. Grading it would fire on nearly every branch.
+- **`incidental`** is a changed file no bullet reached that owes none: a test beside its subject, anything under a fixture or snapshot folder, and a lockfile a package manager writes. Held apart so the count above reads, and reported rather than dropped so a run still says what it set aside.
+- **`unresolved`** is a path the reading could not judge either way. Two causes reach it: a path written partially, such as `claude-worker/SKILL.md` for a file under `claude/skills/`, and a path past its bullet's first comma.
 
-A partial path can credit a changed file and can never accuse one. Nothing separates a path written short from a path written wrong, so the asymmetry keeps the accusing direction to spans the tree can anchor.
+Each direction splits on one question, which is whether the evidence is strong enough to raise with a person. A partial path and a trailing path can each credit a changed file and can never accuse one, because nothing separates a path written short from a path written wrong, or a second claim from a file cited for context. Neither split drops anything: what comes out of `unmet` lands in `unresolved` and what comes out of `unnamed` lands in `incidental`, so a count a reader can act on never costs a file the run stayed silent about.
+
+A generated asset and a regenerated index belong in the incidental class and are deliberately absent from it, because neither has a spelling that holds outside one project. Guessing at one would set aside a file that did owe a bullet, which hides a real omission, where leaving them out only leaves the count where it already was.
 
 ## What counts as a claim
 
 Only `## Key Changes` is read. `## Technical Context` legitimately names files a branch never touched, such as an install stamp inside a target, so widening the read manufactures a finding out of every argument an author made for the change.
 
-Inside the section, the claim region of a bullet ends at its first comma outside a backticked span. That one lever was chosen by measurement. Over the 23 merged pull requests in this repository carrying the section, reading whole bullets reported 16 paths as claimed-but-untouched and every one was a file the body named for context. Cutting at the comma left 110 claims of the original 149 and took the false reports to 2. A list of sixteen clause-opening words tried beside it removed nothing the comma had not already removed, because this corpus punctuates every one of them.
+Inside the section, every backticked span in a bullet is read, and the bullet's first comma outside a span divides the ones that can accuse from the ones that can only credit. That one lever was chosen by measurement. Over the 23 merged pull requests in this repository carrying the section, reading whole bullets reported 16 paths as claimed-but-untouched and every one was a file the body named for context. Cutting at the comma left 110 claims of the original 149 and took the false reports to 2. A list of sixteen clause-opening words tried beside it removed nothing the comma had not already removed, because this corpus punctuates every one of them.
+
+The cut used to decide whether a span was read at all, and the paths past the comma fell out of the claim set into `unnamed`. That was accepted on the ground that the ungraded direction does no damage, and it did: `claude-pr-review` read `unnamed` as a question to put to the branch author, so on 2026-09-01 the question went to three pull requests over bullets that had named the files all along. Reading the whole bullet as claims outright is the obvious repair and the corpus refuses it, taking `unmet` from 10 to 19 over the 40 most recent merged pull requests carrying the section, with all nine additions in the context class the cut exists to exclude. Reading the whole bullet and gating the accusation on the cut gives claims 243 to 314 and unnamed 1124 to 1058 with `unmet` identical entry for entry.
 
-A span inside the claim region has to survive all of these:
+A span anywhere in the bullet has to survive all of these:
 
 | Rule                                              | What it keeps out                                      |
 | ------------------------------------------------- | ------------------------------------------------------ |
@@ -88,16 +93,18 @@ An empty extraction read as a clean pass is the failure shape this repository ha
 
 ## What it was measured against
 
-Driven over the 40 most recent merged pull requests in this repository, 23 of which carry the section, the shipped verb reported zero unmet paths and one `no-claims` refusal. The naive extractor it replaced reported 16.
+Driven over the 40 most recent merged pull requests in this repository at the time, 23 of which carry the section, the shipped verb reported zero unmet paths and one `no-claims` refusal. The naive extractor it replaced reported 16.
+
+The re-measurement behind the trailing-path split is a wider corpus and its numbers do not compare to those. It takes the 40 most recent merged pull requests that carry the section, which reaches back through 90 merges rather than 40, and the reader reports 10 unmet over it. Those 10 predate the split and survive it entry for entry, which is the check that the widening moved nothing into the graded direction. Three name a gitignored path a diff can never carry and one is the definition-site class named below. The remaining six were not run down, so the residual over that corpus is 10 rather than zero and how much of it is the reader rather than the bodies is unmeasured.
 
 The first body written after that corpus closed produced two, which is what the no-change marker and the open class above come from. One was the disclaiming bullet and the rule now covers it at no cost to the corpus. The other is the definition-site class, left open with the report naming it.
 
 The bound is that the corpus is one repository writing to one house style. A project that punctuates differently loses claims to the comma cut rather than gaining false ones, since every rule above drops rather than invents, so the check degrades toward silence rather than toward noise.
 
-What it cannot see is a bullet claiming a change to a file the branch did touch for another reason, a path written without backticks, and a claim in a second coordinated clause after the comma. The last of those falls to the ungraded direction rather than out of the reading.
+What it cannot see is a bullet claiming a change to a file the branch did touch for another reason, and a path written without backticks. A claim in a second coordinated clause after the comma is read and credited, and it stays out of the graded direction, since nothing here separates it from a file the same clause cites for context.
 
 One class stays open and is named rather than closed. A bullet can cite where something is defined while claiming an edit somewhere else, as `#1274` does with "Name the slug transform in `standards/slug.md` inline in the same step". The path is a definition site, the edit target is the step, and separating the two needs the sentence parsed rather than cut. A finding on such a bullet is this class rather than a stale claim, and a reader weighing an `unmet` path checks whether the bullet's real target is a locative the path does not name.
 
 ## Where it runs
 
-`claude-pr-review` Step 3 calls it and files an `unmet` path as a `should-fix` finding under the `**PR body**` block the stale ticked box already takes, since what both corrupt is the merge record rather than a file in the diff. A body is edited between pushes, so a finding names the head the comparison ran at.
+`claude-pr-review` Step 3 calls it and files an `unmet` path as a `should-fix` finding under the `**PR body**` block the stale ticked box already takes, since what both corrupt is the merge record rather than a file in the diff. A body is edited between pushes, so a finding names the head the comparison ran at. `unnamed` is read there and raised off no count, since the step's own history is a question sent over bullets that already answered it. `unresolved` and `incidental` are reported nowhere.

package/docs/agents/worktrees.md

@@ -1,6 +1,6 @@
 ---
 title: Worktrees
-description: Reporting which worktrees are reclaimable, why the reading keys on the pull request rather than on git ancestry, the refusals it names, and the two removal shapes
+description: Reporting which worktrees are reclaimable, removing the ones that are, why the reading keys on the pull request rather than on git ancestry, the refusals it names, and the two removal shapes
 ---
 
 # Worktrees
@@ -24,6 +24,25 @@ Exit codes: `0` every worktree was read, `1` refused. The refusal carries a `rea
 
 An exit code says nothing about a call made from a session, since a shell profile may wrap the binary in a function taking its status from a later command. Read the record's `reason` rather than the exit when a skill consumes this.
 
+## Reclaim
+
+`canon worktrees reclaim` removes every worktree the reading above called reclaimable, and the branch behind each one.
+
+```bash
+canon worktrees reclaim --dry-run
+canon worktrees reclaim
+```
+
+| Option      | Behavior                                    |
+| ----------- | ------------------------------------------- |
+| `--dry-run` | Report what would be removed without acting |
+
+Removal sits on the default path rather than behind an apply flag. Report-only is what the `list` verb already did, and what it produced was a hand cleanup: eight directories deleted outside git in one afternoon, each leaving the registration and the branch that `git worktree remove` would have taken with it. A flag a reader has to remember is one nobody passes the first time, and the first time is when the directories are still there.
+
+Each entry unlocks, removes, then deletes its branch, and the sequence is the same whether the directory still stands or is already gone. A run carrying a directory that is gone sweeps stale registrations once between the removals and the branch deletes, since a branch git still reads as held by a worktree cannot be deleted. That sweep is the one step reaching past the reclaimable set, because git takes no path to scope it: it clears the bookkeeping for every directory already gone, refused entries included, and deletes no branch and no directory of its own.
+
+Exit codes: `0` every reclaimable worktree was removed or there were none, `1` refused or a removal failed. A reading that could not reach the merge state refuses every entry rather than falling back to a default, since that state is the one input deciding whether a branch is safe to delete.
+
 ## What makes a worktree reclaimable
 
 All three hold: its branch has a merged pull request, its working tree is clean, and no live session holds the directory. Each alone has a case where removal loses something, so `refusals` names every failing condition rather than the first.
@@ -31,6 +50,7 @@ All three hold: its branch has a merged pull request, its working tree is clean,
 | Refusal                  | What it means                                           |
 | ------------------------ | ------------------------------------------------------- |
 | `main-worktree`          | The main worktree, which is never reclaimable           |
+| `current-worktree`       | The worktree the command is running in                  |
 | `detached-head`          | No branch, so nothing names a pull request              |
 | `no-merged-pull-request` | Its branch has no merged pull request                   |
 | `uncommitted-changes`    | Work no history stands behind, untracked files included |
@@ -39,6 +59,10 @@ All three hold: its branch has a merged pull request, its working tree is clean,
 
 Uncommitted work is the condition that gates rather than warns. A worktree is gitignored scratch with no history behind it, so a directory removed with unstaged changes takes them somewhere nothing recovers.
 
+A directory already deleted by hand is clean rather than unreadable, so the merged and session checks decide it like any other worktree. Reading the two together is what reported eight reclaimable worktrees as unreadable, since `git status` exits the same way for a path that is gone and one it could not read.
+
+The worktree the command runs in refuses on position rather than on state. Git removes the directory a caller is standing in without complaint, and every later call scoped to that directory then fails, so a run that took it would leave the branches after it undeleted and report the failures against the worktrees rather than the cause.
+
 ## Why the pull request rather than git ancestry
 
 Ancestry is the reading anyone reaches for and it fails in both directions on a repository that squash merges. A merged branch is never an ancestor of the trunk there, so `git merge-base --is-ancestor` calls shipped work unmerged. Measured against nine worktrees, it named five of six lingering branches unmerged, each of which had a merged pull request, reporting them 2 to 6 commits ahead.
@@ -52,7 +76,7 @@ The read is one `gh pr list --state merged` for the whole repository rather than
 `route` names which one applies rather than choosing it, since picking wrong strands state.
 
 - `session`: a live session holds the directory, and `claude rm <name>` removes the session and its worktree together. The `sessions` field carries the names, and a name is whatever string the session was launched under, spaces included, so quote it.
-- `worktree`: the session has ended, and `git worktree remove` with a branch delete is the pair.
+- `worktree`: the session has ended, and `canon worktrees reclaim` is what runs the remove and the branch delete.
 - `null`: the main worktree, which no removal shape reaches.
 
 A held worktree is refused rather than reported reclaimable, and its route is reported for whoever decides to act on it. Deleting a directory underneath a live session is the case that has to refuse.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.12.0",
+  "version": "4.14.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/cli.ts

@@ -83,7 +83,7 @@ function showHelp(): void {
     `${GREY}│${NC}    records [cmd]      ${GREY}# Session records under .claude/ (validate, size, push, pull)${NC}`,
     `${GREY}│${NC}    sessions [cmd]     ${GREY}# Resolve live sessions to worktree and branch (list)${NC}`,
     `${GREY}│${NC}    targets [cmd]      ${GREY}# Report the projects this toolkit installed into (list, pulls)${NC}`,
-    `${GREY}│${NC}    worktrees [cmd]    ${GREY}# Report which worktrees are reclaimable (list)${NC}`,
+    `${GREY}│${NC}    worktrees [cmd]    ${GREY}# Reclaim the worktrees whose branches merged (list, reclaim)${NC}`,
     `${GREY}│${NC}    secrets [cmd]      ${GREY}# Read the shipped tree for credential-shaped values (scan)${NC}`,
     `${GREY}│${NC}    deps [cmd]         ${GREY}# Read the resolved dependency set for advisories (audit)${NC}`,
     `${GREY}│${NC}    labels [cmd]       ${GREY}# Read a changed set against the pull request label map (audit)${NC}`,
@@ -137,6 +137,7 @@ function showHelp(): void {
     `${GREY}│${NC}    canon records push --json`,
     `${GREY}│${NC}    canon sessions list --json`,
     `${GREY}│${NC}    canon worktrees list --json`,
+    `${GREY}│${NC}    canon worktrees reclaim --dry-run`,
     `${GREY}│${NC}    canon secrets scan --json`,
     `${GREY}│${NC}    canon deps audit --json`,
     `${GREY}│${NC}    canon labels audit --json`,

package/src/commands/pr.ts

@@ -107,12 +107,14 @@ export function register(program: Command): void {
         'bullet names leaves it incomplete.',
         '',
         'The two directions carry different weight:',
-        '  unmet      a whole path the body claims and the diff does not carry,',
-        '             which is the graded direction',
-        '  unnamed    a changed file no bullet reached, reported without a grade,',
-        '             since a lockfile or a generated asset earns no bullet',
-        '  unresolved a path written partially, which can credit a changed file',
-        '             and never accuse one',
+        "  unmet      a whole path the body claims ahead of its bullet's first",
+        '             comma and the diff does not carry, the graded direction',
+        '  unnamed    a changed file no bullet reached that a reader might have',
+        '             wanted one for, reported without a grade',
+        '  incidental a changed file no bullet reached that owes none: a test, a',
+        '             fixture, or a lockfile, held apart so the count above reads',
+        '  unresolved a path written partially, or one past its first comma,',
+        '             which can credit a changed file and never accuse one',
         '',
         `Only ## ${KEY_CHANGES} is read. ## Technical Context legitimately names`,
         'files a branch never touched, so widening the read manufactures findings.',
@@ -361,11 +363,16 @@ async function runKeyChanges(
       )
     }
   }
+  if (report.incidental.length > 0) {
+    logInfo(
+      `${plural(report.incidental.length, 'further changed file')} set aside as owing no bullet, whole in the --json record.`,
+    )
+  }
 
   if (report.unresolved.length > 0) {
     logStep('Unresolved')
     logInfo(
-      `${plural(report.unresolved.length, 'path')} written partially, so neither direction judged it.`,
+      `${plural(report.unresolved.length, 'path')} written partially or trailing its bullet's first comma, so neither direction judged it.`,
     )
     for (const claim of report.unresolved) logInfo(claim.path)
   }
@@ -384,6 +391,7 @@ async function runKeyChanges(
         claims: report.claims,
         unmet: report.unmet,
         unnamed: report.unnamed,
+        incidental: report.incidental,
         unresolved: report.unresolved,
       })}\n`,
     )

package/src/commands/upgrade.ts

@@ -32,6 +32,13 @@ interface UpgradeRecord {
   readonly latest?: string
   readonly state: 'upgraded' | 'current' | 'cancelled' | 'refused'
   readonly reason?: string
+  /**
+   * One rendered line for a caller that reports the outcome without parsing
+   * the rest of the record, such as `.husky/post-merge`. `current` reuses
+   * `describeSkew` verbatim so its wording never drifts from the line `canon
+   * sync --check` and `canon claude skills drift` already report.
+   */
+  readonly message: string
 }
 
 export function register(program: Command): void {
@@ -116,6 +123,7 @@ async function runUpgrade(opts: UpgradeOptions): Promise<number> {
       ...base(before, manager, command, skew),
       after: before,
       state: 'current',
+      message: describeSkew(skew),
     })
     return 0
   }
@@ -152,7 +160,11 @@ async function applyUpgrade(
   if (!proceed) {
     logWarn('Cancelled')
     outro()
-    emit(opts, { ...base(before, manager, command, skew), state: 'cancelled' })
+    emit(opts, {
+      ...base(before, manager, command, skew),
+      state: 'cancelled',
+      message: `Cancelled. ${describeSkew(skew)}`,
+    })
     return 0
   }
 
@@ -169,10 +181,11 @@ async function applyUpgrade(
   })
 
   if (result.exitCode !== 0) {
+    const target = latestOf(skew) ?? UNKNOWN_LABEL
     return refuse(
       opts,
       before,
-      `\`${command.join(' ')}\` exited ${result.exitCode}. Run it yourself to read what it reported.`,
+      `\`${command.join(' ')}\` exited ${result.exitCode} moving from ${before} to ${target}. Run it yourself to read what it reported.`,
       manager,
     )
   }
@@ -186,16 +199,23 @@ async function applyUpgrade(
     ...base(before, manager, command, skew),
     after,
     state: 'upgraded',
+    message: upgradedMessage(before, after),
   })
   return 0
 }
 
+export function upgradedMessage(before: string, after: string): string {
+  return after === before
+    ? `Reinstalled ${after}, unchanged.`
+    : `Upgraded ${before} to ${after}.`
+}
+
 function base(
   before: string,
   manager: Manager,
   command: readonly string[],
   skew: SkewReport,
-): Omit<UpgradeRecord, 'state'> {
+): Omit<UpgradeRecord, 'state' | 'message'> {
   const latest = latestOf(skew)
 
   return {
@@ -221,11 +241,28 @@ function refuse(
     before,
     state: 'refused',
     reason,
+    message: reason,
   })
   return 1
 }
 
 function emit(opts: UpgradeOptions, record: UpgradeRecord): void {
   if (opts.json !== true) return
-  process.stdout.write(`${JSON.stringify(record)}\n`)
+  process.stdout.write(
+    `${JSON.stringify({ ...record, message: singleLine(record.message) })}\n`,
+  )
+}
+
+/**
+ * `message` is the one field carrying arbitrary text: `describeSkew`'s
+ * `unknown` branch embeds a registry error verbatim, and a registry answering
+ * with HTML produces one already carrying a double quote. `.husky/post-merge`
+ * reads this field with a pattern rather than a parser, so a quote makes it
+ * through `JSON.stringify` as an escaped `\"` that the pattern stops at,
+ * truncating the line it prints. Collapsing whitespace and swapping the quote
+ * for an apostrophe here, once, is what keeps every emitter of `message` from
+ * having to reason about that reader.
+ */
+export function singleLine(text: string): string {
+  return text.replace(/\s+/g, ' ').replace(/"/g, "'")
 }

package/src/commands/worktrees.ts

@@ -2,6 +2,7 @@ import type { Command } from 'commander'
 import {
   intro,
   logInfo,
+  logRemove,
   logStep,
   logWarn,
   outro,
@@ -10,17 +11,26 @@ import {
 } from '@/ui'
 import {
   type Refusal,
+  type ReclaimReport,
   reclaimReport,
   type Unreadable,
   type WorktreeVerdict,
 } from '@/worktrees/reclaim'
+import { mainWorktreeRoot } from '@/worktree'
+import { removeReclaimable, type RemovalOutcome } from '@/worktrees/remove'
 
 interface ListCommandOptions {
   readonly json?: boolean
 }
 
+interface ReclaimCommandOptions {
+  readonly dryRun?: boolean
+}
+
 const REFUSALS: Record<Refusal, string> = {
   'main-worktree': 'the main worktree, which is never reclaimable',
+  'current-worktree':
+    'the worktree this command is running in, so removing it would take the run with it',
   'detached-head': 'detached HEAD, so no branch names a pull request',
   'no-merged-pull-request': 'no merged pull request for its branch',
   'uncommitted-changes': 'uncommitted work no history stands behind',
@@ -37,10 +47,37 @@ const UNREADABLE: Record<Unreadable, string> = {
     'The session roster could not be read, so nothing was read about which worktrees are still held.',
 }
 
+const CONDITIONS = [
+  'A worktree is reclaimable when all three hold: its branch has a merged',
+  'pull request, its working tree is clean, and no live session holds it.',
+  'Each alone has a case where removal loses something, so "refusals"',
+  'carries every failing condition rather than the first.',
+  '',
+  'The merged state comes from gh rather than from git ancestry. A',
+  'repository that squash merges never makes a merged branch an ancestor',
+  'of its trunk, so ancestry calls shipped work unmerged and calls an',
+  'abandoned branch sitting at a release commit merged.',
+  '',
+  'A directory already deleted by hand reads as clean rather than as',
+  'unreadable, so the merged and session checks decide it like any other.',
+  '',
+  'The main worktree is never reclaimable, and neither is the one this',
+  'command is running in, since git removes the directory a caller stands',
+  'in and every later call scoped to it then fails.',
+  '',
+  'An unreadable input refuses the whole reading rather than reporting',
+  'every worktree as not reclaimable, since an absent merge state and a',
+  'branch with no merged pull request produce the same empty answer.',
+  '',
+  'The merge read covers the most recent 200 merged pull requests. A',
+  'worktree older than that reads as having none and is refused, which',
+  'keeps a directory rather than removing one.',
+]
+
 export function register(program: Command): void {
   const worktrees = program
     .command('worktrees')
-    .description('Report which worktrees are reclaimable and which are not')
+    .description('Report which worktrees are reclaimable, and reclaim them')
     .helpOption('-h, --help', 'Show this help message')
 
   worktrees
@@ -58,29 +95,13 @@ export function register(program: Command): void {
         '  0  every worktree was read',
         '  1  refused, with the reason on stderr',
         '',
-        'A worktree is reclaimable when all three hold: its branch has a merged',
-        'pull request, its working tree is clean, and no live session holds it.',
-        'Each alone has a case where removal loses something, so "refusals"',
-        'carries every failing condition rather than the first.',
-        '',
-        'The merged state comes from gh rather than from git ancestry. A',
-        'repository that squash merges never makes a merged branch an ancestor',
-        'of its trunk, so ancestry calls shipped work unmerged and calls an',
-        'abandoned branch sitting at a release commit merged.',
+        ...CONDITIONS,
         '',
         'This reports and removes nothing. "route" names which removal shape',
         'applies: "session" when a live session holds the directory, where',
         '`claude rm <name>` takes the session and its worktree together, and',
-        '"worktree" when the session has ended, where `git worktree remove`',
-        'and a branch delete are the pair.',
-        '',
-        'An unreadable input refuses the whole reading rather than reporting',
-        'every worktree as not reclaimable, since an absent merge state and a',
-        'branch with no merged pull request produce the same empty answer.',
-        '',
-        'The merge read covers the most recent 200 merged pull requests. A',
-        'worktree older than that reads as having none and is refused, which',
-        'keeps a directory rather than removing one.',
+        '"worktree" when the session has ended, where `canon worktrees',
+        'reclaim` is the pair of a remove and a branch delete.',
         '',
         'Examples:',
         '  canon worktrees list',
@@ -91,6 +112,64 @@ export function register(program: Command): void {
     .action(async (opts: ListCommandOptions) => {
       process.exitCode = await runList(opts)
     })
+
+  worktrees
+    .command('reclaim')
+    .description(
+      'Remove every reclaimable worktree and the branch behind it, unless --dry-run',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--dry-run', 'Report what would be removed without removing it')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  every reclaimable worktree was removed, or there were none',
+        '  1  refused, or a removal failed, with the reason on stderr',
+        '',
+        ...CONDITIONS,
+        '',
+        'Removal runs on the default path rather than behind an apply flag,',
+        'because report-only is what produced the hand cleanup this verb was',
+        'filed against. Each removal unlocks the worktree, removes it, then',
+        'deletes its branch, and a run carrying a directory that is already',
+        'gone sweeps stale registrations once before the branch deletes.',
+        '',
+        'It deletes only what a reading called reclaimable. A worktree a live',
+        'session holds is refused rather than removed, since `claude rm <name>`',
+        'is what takes a session and its worktree together.',
+        '',
+        'The stale-registration sweep is the one step that reaches wider, since',
+        'git takes no path to scope it. It clears the bookkeeping for every',
+        'directory already gone, refused entries included, and deletes no branch',
+        'and no directory of its own.',
+        '',
+        'Examples:',
+        '  canon worktrees reclaim --dry-run',
+        '  canon worktrees reclaim',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: ReclaimCommandOptions) => {
+      process.exitCode = await runReclaim(opts)
+    })
+}
+
+/**
+ * Frames an unreadable reading the same way for both verbs.
+ *
+ * The merge state is the one input that decides whether a branch is safe to
+ * delete, so a reading that could not reach it refuses every entry rather than
+ * falling back to a default. Sharing the frame keeps the removal from growing a
+ * second answer to the question the report already answers.
+ */
+function reportUnreadable(
+  report: Extract<ReclaimReport, { kind: 'unreadable' }>,
+): void {
+  logStep('Refused')
+  logWarn(UNREADABLE[report.reason])
+  logInfo(report.detail)
 }
 
 async function runList(opts: ListCommandOptions): Promise<number> {
@@ -99,9 +178,7 @@ async function runList(opts: ListCommandOptions): Promise<number> {
   intro('canon worktrees list')
 
   if (report.kind === 'unreadable') {
-    logStep('Refused')
-    logWarn(UNREADABLE[report.reason])
-    logInfo(report.detail)
+    reportUnreadable(report)
     outro()
 
     if (opts.json) {
@@ -133,6 +210,86 @@ async function runList(opts: ListCommandOptions): Promise<number> {
   return 0
 }
 
+async function runReclaim(opts: ReclaimCommandOptions): Promise<number> {
+  const dryRun = opts.dryRun ?? false
+  const cwd = process.cwd()
+  const report = await reclaimReport({ cwd })
+
+  intro(
+    dryRun ? 'canon worktrees reclaim (dry-run)' : 'canon worktrees reclaim',
+  )
+
+  if (report.kind === 'unreadable') {
+    reportUnreadable(report)
+    outro()
+    return 1
+  }
+
+  const reclaimable = report.worktrees.filter((entry) => entry.reclaimable)
+
+  logStep('Reclaimable')
+  if (reclaimable.length === 0) {
+    logInfo('None. Every worktree fails at least one condition.')
+    outro()
+    return 0
+  }
+
+  logInfo(plural(reclaimable.length, 'worktree'))
+  pipeOutput(reclaimable.map(describe).join('\n'))
+
+  if (dryRun) {
+    logStep('Dry run')
+    logWarn('Nothing was removed. Run this again without --dry-run to remove.')
+    outro()
+    return 0
+  }
+
+  // Every git call in the removal is scoped to the main root rather than to the
+  // caller's directory, which a removal earlier in the same run can delete out
+  // from under the ones after it. The reading above stays on the caller's
+  // directory, since that is what tells it which worktree it is standing in.
+  const removal = await removeReclaimable(reclaimable, {
+    cwd: await mainWorktreeRoot(),
+  })
+
+  logStep('Removed')
+  for (const outcome of removal.outcomes) reportOutcome(outcome)
+  if (removal.pruned) {
+    logInfo(
+      'Swept the stale worktree registrations left by a deleted directory.',
+    )
+  }
+
+  const failed = removal.outcomes.filter((outcome) => !outcome.removed)
+  if (failed.length > 0) {
+    logWarn(
+      `${plural(failed.length, 'worktree')} could not be removed. Read the reason above and clear it by hand.`,
+    )
+    outro()
+    return 1
+  }
+
+  outro()
+  return 0
+}
+
+/** Names what happened to one entry, with the failing step where it did not close. */
+function reportOutcome(outcome: RemovalOutcome): void {
+  const branch = outcome.branch ?? 'detached'
+
+  if (outcome.removed) {
+    logRemove(`${outcome.path}  ${branch}`)
+    return
+  }
+
+  const step =
+    outcome.failedAt === 'branch'
+      ? 'the worktree went but its branch stayed'
+      : 'the worktree could not be removed'
+  logWarn(`${outcome.path}  ${branch}: ${step}.`)
+  if (outcome.detail) pipeOutput(outcome.detail)
+}
+
 function reportWorktrees(worktrees: readonly WorktreeVerdict[]): void {
   logStep('Worktrees')
 
@@ -153,7 +310,7 @@ function reportWorktrees(worktrees: readonly WorktreeVerdict[]): void {
   }
 
   logWarn(
-    `${plural(reclaimable.length, 'worktree')} can be reclaimed. This reports and removes nothing, so run the named command yourself.`,
+    `${plural(reclaimable.length, 'worktree')} can be reclaimed. This reports and removes nothing, so run \`canon worktrees reclaim\` to clear them.`,
   )
 }
 
@@ -183,9 +340,14 @@ function describe(verdict: WorktreeVerdict): string {
     return `${head}\n  Refused: ${reasons.join('; ')}.${routes.join('')}`
   }
 
+  // The directory being gone already is the state that used to refuse, so the
+  // row says so rather than leaving a reader to wonder what it is acting on.
+  const tree = verdict.missing
+    ? 'its directory is already gone'
+    : 'the tree is clean'
+
   return [
     head,
-    `  Reclaimable. Pull request #${verdict.pullRequest} merged it, the tree is clean, and no session holds it.`,
-    `  Remove with: git worktree remove ${verdict.path} && git branch -D ${held}`,
+    `  Reclaimable. Pull request #${verdict.pullRequest} merged it, ${tree}, and no session holds it.`,
   ].join('\n')
 }

package/src/pr/bijection.ts

@@ -24,17 +24,35 @@ export interface BijectionReport {
    */
   readonly unmet: readonly PathClaim[]
   /**
-   * Claims whose first segment names no entry in the tree, so the comparison
-   * could not judge them either way. Reported so a run says what it declined
-   * rather than counting a partial spelling as met.
+   * Claims no changed file answers that the comparison could not judge either
+   * way, reported so a run says what it declined rather than counting them met.
+   *
+   * Two causes land here. A claim whose first segment names no entry in the
+   * tree is a path written partially, and one past its bullet's first comma is
+   * a path the reader cannot separate from a file cited for context. Both are
+   * evidence strong enough to credit a changed file and too weak to accuse one,
+   * so neither reaches `unmet`, and the cause is on the claim rather than in a
+   * bucket of its own: a reader acts on both the same way, by opening the
+   * bullet on `preview`.
    */
   readonly unresolved: readonly PathClaim[]
   /**
-   * Changed files no claim reaches. Reported without a severity, since the
-   * class covers a real omission and equally a lockfile, a generated asset, or
-   * a regenerated index that legitimately earns no bullet.
+   * Changed files no claim reaches that a reader might have wanted a bullet
+   * for. Reported without a severity, since a change can be too small to
+   * describe and still be correctly absent from the section.
    */
   readonly unnamed: readonly string[]
+  /**
+   * Changed files no claim reaches that owe no bullet in the first place.
+   *
+   * Held apart rather than dropped, so a run still says what it set aside.
+   * `#1331` reported seven unnamed files of which four were a test or a
+   * fixture, which is what makes the raw count unreadable: a number mixing
+   * files that owe a bullet with files that never could cannot be acted on at
+   * any value, and the reviewing skill reads `unnamed` as a question to a
+   * branch author.
+   */
+  readonly incidental: readonly string[]
 }
 
 export type Bijection =
@@ -50,6 +68,32 @@ export interface BijectionInput {
   readonly title?: string
 }
 
+/**
+ * A changed file that owes no bullet, so its absence from the section is not a
+ * gap a reader would want reported.
+ *
+ * Three classes, each conventional rather than named for this repository: a
+ * test beside the subject it covers, anything under a fixture or snapshot
+ * folder, and a lockfile a package manager writes. All three change constantly
+ * as a consequence of work the section describes in its own terms, which is why
+ * a body naming them reads as noise rather than as diligence.
+ *
+ * A generated asset and a regenerated index belong in the class and are
+ * deliberately absent, because neither has a spelling that holds outside one
+ * project. Guessing at one would set aside a file that did owe a bullet, which
+ * is the direction that hides a real omission, where leaving them out only
+ * leaves the count where it already was.
+ */
+const INCIDENTAL: readonly RegExp[] = [
+  /(?:^|\/)[^/]+\.(?:test|spec)\.[A-Za-z0-9]+$/,
+  /(?:^|\/)(?:__tests__|__fixtures__|__snapshots__|fixtures|testdata)\//,
+  /(?:^|\/)(?:bun\.lockb?|package-lock\.json|yarn\.lock|pnpm-lock\.yaml|Cargo\.lock|Gemfile\.lock|poetry\.lock|uv\.lock|composer\.lock|go\.sum)$/,
+]
+
+function owesNoBullet(path: string): boolean {
+  return INCIDENTAL.some((pattern) => pattern.test(path))
+}
+
 /**
  * Whether one changed path is the file, or a file under the folder, a claim
  * names.
@@ -80,6 +124,13 @@ function covers(claim: PathClaim, path: string): boolean {
  * correct. Merging them into one count would either grade the second or excuse
  * the first.
  *
+ * Each direction then splits again on the same question, which is whether the
+ * evidence is strong enough to raise with a person. A claim reaches `unmet`
+ * only when it is both whole and leading, and a changed file reaches `unnamed`
+ * only when a bullet was owed for it. What each split sets aside is still
+ * reported, under `unresolved` and `incidental`, so a count a reader can act on
+ * never comes at the price of a file the run stayed silent about.
+ *
  * Pure, so the whole judgment is testable against a fixture. The caller reads
  * the body, the changed set, and the tree roots and hands all three in.
  */
@@ -104,10 +155,12 @@ export function compareKeyChanges(input: BijectionInput): Bijection {
     const hits = input.changed.filter((path) => covers(claim, path))
     for (const path of hits) named.add(path)
     if (hits.length > 0) continue
-    if (claim.anchored) unmet.push(claim)
+    if (claim.anchored && claim.leading) unmet.push(claim)
     else unresolved.push(claim)
   }
 
+  const reached = input.changed.filter((path) => !named.has(path))
+
   return {
     kind: 'measured',
     head: input.head,
@@ -115,7 +168,8 @@ export function compareKeyChanges(input: BijectionInput): Bijection {
     claims: read.claims,
     unmet,
     unresolved,
-    unnamed: input.changed.filter((path) => !named.has(path)),
+    unnamed: reached.filter((path) => !owesNoBullet(path)),
+    incidental: reached.filter(owesNoBullet),
   }
 }
 

package/src/pr/paths.ts

@@ -24,6 +24,16 @@ export interface PathClaim {
    * genuinely wrong one.
    */
   readonly anchored: boolean
+  /**
+   * True when the span sits ahead of the bullet's first comma.
+   *
+   * A trailing span is a path the bullet names without the reader being able to
+   * tell a second claim from a file cited for context, so it credits a changed
+   * file and never accuses one. Same asymmetry as `anchored`, on a second
+   * question: both mark evidence strong enough to confirm and too weak to
+   * accuse with.
+   */
+  readonly leading: boolean
   /** The span exactly as the body wrote it, before the line suffix came off. */
   readonly span: string
   /** One-based index of the bullet inside the section. */
@@ -101,7 +111,7 @@ function maskSpans(text: string): string {
 }
 
 /**
- * The part of a bullet that asserts a change, which ends at its first comma.
+ * The part of a bullet that can accuse, which ends at its first comma.
  *
  * This is the one lever that separates a claim from a mention, and it was
  * chosen by measurement rather than by grammar. Over the 23 merged pull
@@ -113,10 +123,27 @@ function maskSpans(text: string): string {
  * removed nothing the comma had not already removed, because this corpus
  * punctuates every one of them.
  *
- * What it costs is a claim in a second coordinated clause, as in "Add `x` to
- * `a.ts`, and delete the old inline `y` from `b.ts`", where `b.ts` stops being
- * claimed and falls to the unnamed direction instead. That direction reports
- * without grading, so the cost lands where it does no damage.
+ * The cut used to bound what the scan collected at all, and that is the half
+ * that came out. A path past the comma was left out of the claim set entirely
+ * and fell to the unnamed direction, accepted here on the ground that the
+ * direction reports without grading. It graded anyway, one consumer removed:
+ * `claude-pr-review` reads `unnamed` as a question to put to the branch author,
+ * and on 2026-09-01 the question went to three pull requests over bullets that
+ * had named the files all along, with `#1329` gaining bullets it did not need.
+ *
+ * Collecting the whole bullet as claims was measured against the 40 most recent
+ * merged pull requests carrying the section and is not the repair: it takes
+ * `unmet` from 10 to 19, and every one of the nine is the class the cut was
+ * tuned to exclude, as in `#1276`'s "following the frame, the stream split, and
+ * the exit ladder `src/commands/labels.ts` already carries". So the scan reads
+ * the whole bullet and this cut decides `leading` instead, which is what lets a
+ * trailing path credit a changed file while `unmet` stays where the corpus put
+ * it. The same 40 give claims 243 to 314, unnamed 1124 to 1058, and unmet 10
+ * either way.
+ *
+ * `disclaimsChange` reads this region too, and for its own reason rather than
+ * by sharing this one: a disclaimer opens its bullet, so the cut reaches every
+ * one the corpus carries, and `NO_CHANGE` below records what depends on that.
  */
 function claimRegion(bullet: string): string {
   const at = maskSpans(bullet).indexOf(',')
@@ -149,8 +176,8 @@ function claimRegion(bullet: string): string {
 const NO_CHANGE =
   /\b(?:untouched|unchanged)\b|\bas written\b|^\s*(?:do not|don't|never)\b/i
 
-function disclaimsChange(region: string): boolean {
-  return NO_CHANGE.test(maskSpans(region))
+function disclaimsChange(bullet: string): boolean {
+  return NO_CHANGE.test(maskSpans(claimRegion(bullet)))
 }
 
 /**
@@ -296,12 +323,12 @@ export function extractKeyChangePaths(
       trimmed.length > PREVIEW_LIMIT
         ? `${trimmed.slice(0, PREVIEW_LIMIT)}…`
         : trimmed
-    const region = claimRegion(trimmed)
-    if (disclaimsChange(region)) continue
+    if (disclaimsChange(trimmed)) continue
 
+    const accusesBefore = claimRegion(trimmed).length
     let claimed = false
 
-    for (const match of region.matchAll(BACKTICKED)) {
+    for (const match of trimmed.matchAll(BACKTICKED)) {
       const span = match[1] ?? ''
       const bare = span.replace(LINE_SUFFIX, '')
 
@@ -317,6 +344,9 @@ export function extractKeyChangePaths(
       const resolved = resolveSpan(bare)
       if (resolved === undefined) continue
       claimed = true
+      // First occurrence wins, across bullets as well as inside one. A path
+      // named trailing here and leading three bullets later keeps the weaker
+      // reading, which loses an accusation and can never add one.
       if (seen.has(resolved.path)) continue
       seen.add(resolved.path)
 
@@ -324,6 +354,7 @@ export function extractKeyChangePaths(
         path: resolved.path,
         directory: resolved.directory,
         anchored: roots.has(resolved.path.slice(0, resolved.path.indexOf('/'))),
+        leading: (match.index ?? 0) < accusesBefore,
         span,
         bullet: index + 1,
         preview,

package/src/worktree.ts

@@ -9,15 +9,21 @@ import { gitEnv } from '@/git-env'
  * files the session has edited only if it resolves the root this way. The
  * working directory is not a substitute, since a caller invoking from a
  * subdirectory would resolve a root holding none of the trees a verb reads.
+ *
+ * The directory to resolve from is an argument so a caller holding a root of
+ * its own asks about that one rather than about wherever the process happens to
+ * stand, which is what a verb driven by an injected root needs.
  */
-export async function currentWorktreeRoot(): Promise<string> {
-  const result = await $`git rev-parse --show-toplevel`
+export async function currentWorktreeRoot(
+  cwd: string = process.cwd(),
+): Promise<string> {
+  const result = await $`git -C ${cwd} rev-parse --show-toplevel`
     .env(gitEnv())
     .quiet()
     .nothrow()
-  if (result.exitCode !== 0) return process.cwd()
+  if (result.exitCode !== 0) return cwd
 
-  return result.stdout.toString().trim() || process.cwd()
+  return result.stdout.toString().trim() || cwd
 }
 
 /**

package/src/worktrees/reclaim.ts

@@ -1,5 +1,6 @@
 import { $ } from 'bun'
 import { execa } from 'execa'
+import { existsSync } from 'node:fs'
 import { gitEnv } from '@/git-env'
 import {
   repositoryOf,
@@ -7,7 +8,11 @@ import {
   resolveSessions,
   type SessionReport,
 } from '@/sessions/resolve'
-import { listWorktrees, type WorktreeEntry } from '@/worktree'
+import {
+  currentWorktreeRoot,
+  listWorktrees,
+  type WorktreeEntry,
+} from '@/worktree'
 
 const GH_TIMEOUT_MS = 30_000
 
@@ -21,6 +26,7 @@ const MERGED_LIMIT = 200
 /** Why one worktree cannot be reclaimed, one entry per failing condition. */
 export type Refusal =
   | 'main-worktree'
+  | 'current-worktree'
   | 'detached-head'
   | 'no-merged-pull-request'
   | 'uncommitted-changes'
@@ -52,6 +58,11 @@ export interface WorktreeVerdict {
   /** The names of the live sessions holding this worktree, which is what `claude rm` takes. */
   readonly sessions: readonly string[]
   readonly route: RemovalRoute
+  /**
+   * True when the directory is already gone and only the registration remains,
+   * which is what decides whether a sweep is owed after the removals.
+   */
+  readonly missing: boolean
 }
 
 export interface MergedPullRequest {
@@ -71,6 +82,11 @@ export interface StatusReport {
   /** False when the status read itself failed, so a clean `dirty` says nothing. */
   readonly readable: boolean
   readonly dirty: boolean
+  /**
+   * True when no directory stands at the path. Readable and clean rather than
+   * unreadable, since nothing is there to hold work.
+   */
+  readonly missing: boolean
 }
 
 export type ReclaimReport =
@@ -153,19 +169,33 @@ async function mergedPullRequests(cwd: string): Promise<MergedReport> {
 /**
  * Reports whether a worktree holds work no history is behind.
  *
- * Untracked files count, since a worktree is gitignored scratch and a directory
- * removed with them takes them nowhere recoverable. A failed read is separated
- * from a clean tree, because the two produce the same empty output and only one
- * of them is safe to act on.
+ * Untracked files count for a directory that still exists, since a worktree is
+ * gitignored scratch and a directory removed with them takes them nowhere
+ * recoverable.
+ *
+ * Three states rather than two. A directory that is gone holds nothing at all,
+ * so it reads as clean and leaves the merged and session checks to decide. A
+ * read that failed is separated from both, because it produces the same empty
+ * output as a clean tree and only one of them is safe to act on. The directory
+ * test runs first because `git status` exits 128 for a missing path and for an
+ * unreadable one alike, which folded the two into one refusal and reported
+ * every hand-deleted worktree as unreadable.
  */
 async function worktreeStatus(path: string): Promise<StatusReport> {
+  if (!existsSync(path)) return { readable: true, dirty: false, missing: true }
+
   const result = await $`git -C ${path} status --porcelain`
     .env(gitEnv())
     .quiet()
     .nothrow()
-  if (result.exitCode !== 0) return { readable: false, dirty: false }
+  if (result.exitCode !== 0)
+    return { readable: false, dirty: false, missing: false }
 
-  return { readable: true, dirty: result.stdout.toString().trim().length > 0 }
+  return {
+    readable: true,
+    dirty: result.stdout.toString().trim().length > 0,
+    missing: false,
+  }
 }
 
 /**
@@ -195,6 +225,7 @@ function holders(
 function verdict(
   entry: WorktreeEntry,
   isMain: boolean,
+  isCurrent: boolean,
   status: StatusReport,
   merged: ReadonlyMap<string, number>,
   sessions: readonly ResolvedSession[],
@@ -206,6 +237,13 @@ function verdict(
   const refusals: Refusal[] = []
 
   if (isMain) refusals.push('main-worktree')
+  // Git removes the directory a caller is standing in without complaint, and
+  // every later call scoped to that directory then fails, so a run that took it
+  // would leave the branches behind it undeleted and report the failures as the
+  // worktrees' own. The main worktree is already refused above, so this names
+  // only a linked one.
+  else if (isCurrent) refusals.push('current-worktree')
+
   if (entry.branch === null) refusals.push('detached-head')
   else if (pullRequest === null) refusals.push('no-merged-pull-request')
 
@@ -226,6 +264,7 @@ function verdict(
     // here rather than in the reporter keeps the record and the framed output
     // answering the same way, since the two consumers act on different halves.
     route: isMain ? null : held.length > 0 ? 'session' : 'worktree',
+    missing: status.missing,
   }
 }
 
@@ -259,11 +298,12 @@ export async function reclaimReport(
   const readStatus = opts.worktreeStatus ?? worktreeStatus
   const resolve = opts.resolve ?? resolveSessions
 
-  const [entries, merged, sessions, repository] = await Promise.all([
+  const [entries, merged, sessions, repository, current] = await Promise.all([
     listAll(cwd),
     readMerged(cwd),
     resolve(),
     repositoryOf(cwd),
+    currentWorktreeRoot(cwd),
   ])
 
   if (merged.kind === 'unreadable') {
@@ -295,7 +335,8 @@ export async function reclaimReport(
     verdict(
       entry,
       index === 0,
-      statuses[index] ?? { readable: false, dirty: false },
+      entry.path === current,
+      statuses[index] ?? { readable: false, dirty: false, missing: false },
       byBranch,
       sessions.sessions,
       repository,

package/src/worktrees/remove.ts

@@ -0,0 +1,158 @@
+import { $ } from 'bun'
+import { gitEnv } from '@/git-env'
+import type { WorktreeVerdict } from '@/worktrees/reclaim'
+
+/** Which half of the removal a failure landed on, so a reader repairs the right one. */
+export type RemovalStep = 'remove' | 'branch'
+
+export interface RemovalOutcome {
+  readonly path: string
+  readonly branch: string | null
+  readonly removed: boolean
+  /** Null on success, so a reader branches on the step rather than on a message. */
+  readonly failedAt: RemovalStep | null
+  readonly detail: string | null
+}
+
+export interface RemovalReport {
+  readonly outcomes: readonly RemovalOutcome[]
+  /** True when the stale-registration sweep ran, which only a missing directory owes. */
+  readonly pruned: boolean
+}
+
+export interface GitResult {
+  readonly exitCode: number
+  readonly stderr: string
+}
+
+export interface RemovalOptions {
+  /**
+   * Where every git call runs. Required rather than defaulted, since the one
+   * value a default could carry is the process directory and that is the unsafe
+   * one: a caller standing in a worktree this run removes loses the ground the
+   * calls after it resolve against. A compiler error is what a caller gets
+   * instead of that failure.
+   */
+  readonly cwd: string
+  readonly git?: (cwd: string, args: readonly string[]) => Promise<GitResult>
+}
+
+async function runGit(
+  cwd: string,
+  args: readonly string[],
+): Promise<GitResult> {
+  const result = await $`git -C ${cwd} ${args}`.env(gitEnv()).quiet().nothrow()
+
+  return {
+    exitCode: result.exitCode,
+    stderr: result.stderr.toString().trim(),
+  }
+}
+
+/**
+ * Removes every worktree a reading called reclaimable, and the branch behind it.
+ *
+ * The sequence is unlock, remove, then delete the branch, and it is the same
+ * whether the directory still exists or is already gone. `git worktree remove`
+ * takes a stale registration as readily as a live directory, measured at git
+ * 2.43.0, so the missing case needs no command of its own.
+ *
+ * Every command runs from `opts.cwd`, which belongs at the main worktree root
+ * and never at the directory a caller happens to stand in. A removal earlier in
+ * the run deletes that directory, and each `git -C` after it fails against a
+ * path that is gone, so the branches behind those entries survive and the run
+ * reports the failures against the worktrees rather than against the removal
+ * that pulled the ground out.
+ *
+ * The unlock runs on every entry and its result is not read, since `git worktree
+ * unlock` exits 128 with "is not locked" for the ordinary case. Reading the lock
+ * state first would buy a second parse of the porcelain to answer what the next
+ * command answers anyway, and a lock that genuinely refuses to lift surfaces as
+ * the remove failing rather than being swallowed.
+ *
+ * `git worktree prune` sweeps once after the removals rather than per entry,
+ * because it clears every stale registration in one pass and takes no path to
+ * scope it. It runs ahead of the branch deletes rather than at the very end: a
+ * branch git still reads as held by a worktree cannot be deleted, and a sweep
+ * placed after that pass would leave the branch standing with nothing left in
+ * the listing to find it by.
+ */
+export async function removeReclaimable(
+  verdicts: readonly WorktreeVerdict[],
+  opts: RemovalOptions,
+): Promise<RemovalReport> {
+  const { cwd } = opts
+  const git = opts.git ?? runGit
+  const targets = verdicts.filter((entry) => entry.reclaimable)
+
+  const removals: { target: WorktreeVerdict; result: GitResult }[] = []
+  for (const target of targets) {
+    await git(cwd, ['worktree', 'unlock', target.path])
+    removals.push({
+      target,
+      result: await git(cwd, ['worktree', 'remove', target.path]),
+    })
+  }
+
+  // Reported from the sweep's own exit rather than from whether it was owed, so
+  // a run that tried and failed does not read as one that cleared the tree.
+  const sweep = targets.some((target) => target.missing)
+    ? await git(cwd, ['worktree', 'prune'])
+    : null
+  const pruned = sweep !== null && sweep.exitCode === 0
+
+  const outcomes: RemovalOutcome[] = []
+  for (const { target, result } of removals) {
+    outcomes.push(await deleteBranch(target, result, cwd, git))
+  }
+
+  return { outcomes, pruned }
+}
+
+/**
+ * Closes one entry by deleting its branch, or reports why it was left standing.
+ *
+ * A remove that failed against a directory which still exists stops the entry
+ * here. Git refuses to delete a branch a registered worktree holds, and forcing
+ * past that strands a registration pointing at a branch that no longer exists.
+ * A missing directory carries on, since the sweep above is what clears the
+ * registration in that case and the delete reports for itself when it did not.
+ */
+async function deleteBranch(
+  target: WorktreeVerdict,
+  removal: GitResult,
+  cwd: string,
+  git: (cwd: string, args: readonly string[]) => Promise<GitResult>,
+): Promise<RemovalOutcome> {
+  const { path, branch } = target
+
+  if (removal.exitCode !== 0 && !target.missing) {
+    return {
+      path,
+      branch,
+      removed: false,
+      failedAt: 'remove',
+      detail: removal.stderr || null,
+    }
+  }
+
+  // A reclaimable verdict always names a branch, since a detached head is one of
+  // the refusals. The read is here so a caller passing a verdict of its own is
+  // answered rather than handed a delete with no name in it.
+  if (branch === null) {
+    return { path, branch, removed: true, failedAt: null, detail: null }
+  }
+
+  const deleted = await git(cwd, ['branch', '-D', branch])
+  if (deleted.exitCode !== 0) {
+    return {
+      path,
+      branch,
+      removed: false,
+      failedAt: 'branch',
+      detail: deleted.stderr || null,
+    }
+  }
+
+  return { path, branch, removed: true, failedAt: null, detail: null }
+}