@erclx/canon 4.12.0 → 4.13.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.13.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/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

@@ -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/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.13.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/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/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 }
+}