@erclx/aitk 3.30.0 → 3.32.0

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

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

package/claude/skills/claude-autoship/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: claude-autoship
-description: Chains implement → verify → review → ship after a feature plan is approved. Reads the plan for the current branch, runs the full pipeline in one session, and stops on any failure or non-minor review finding. Use when asked to "autoship", "ship this feature end to end", or "run the chain". Do NOT auto-trigger. Requires an approved plan file.
+description: Chains implement → verify → review → ship after a feature plan is approved. Reads the plan the caller names, or the plan for the current branch when none is named, runs the full pipeline in one session, and stops on any failure or non-minor review finding. Use when asked to "autoship", "ship this feature end to end", or "run the chain". Do NOT auto-trigger. Requires an approved plan file.
 disable-model-invocation: true
 ---
 
@@ -11,8 +11,8 @@ Chain the post-plan pipeline in a single run. Every step has a stop condition. S
 ## Guards
 
 - All `.claude/plans/` and `.claude/review/` reads resolve at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`.
-- Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. This skill takes the stop rather than the `latest` fallback, since it commits and opens a pull request. If empty, stop: `❌ Detached HEAD. Checkout the feature branch first.`
-- If `.claude/plans/feature-<slug>.md` does not exist at the main worktree root, stop: `❌ No approved plan at .claude/plans/feature-<slug>.md. Run /claude-feature first.`
+- Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. This skill takes the stop rather than the `latest` fallback, since it commits and opens a pull request. If empty, stop: `❌ Detached HEAD. Checkout the feature branch first.` Every later step keys its output on this slug, being the worktree, the review receipt, the branch, and the memory proposal, regardless of which plan Step 1 reads.
+- Resolve `<plan>` in Step 1, ahead of any other read.
 - If the working tree has uncommitted changes unrelated to the plan, stop: `❌ Uncommitted changes outside the plan. Commit or stash before autoshipping.`
 
 ## Diff baseline
@@ -39,7 +39,12 @@ If the two commands differ, the session is already in a linked worktree. Continu
 
 ## Step 1: read the plan
 
-Read `.claude/plans/feature-<slug>.md` at the main worktree root. This file is the scope for this run.
+Resolve `<plan>` in this order, stopping at the first match:
+
+1. **Caller-supplied.** The invocation carried an argument. Accept it as a plan path or a bare slug, in the same position `claude-worktree` tier 0 accepts its name. A bare slug resolves to `.claude/plans/feature-<slug>.md`, and a path is taken as given, relative to the main worktree root. If it does not resolve to a file, stop: `❌ No plan at <path>. Path was supplied, not derived, so check it and re-run.`
+2. **Derived.** `.claude/plans/feature-<slug>.md`, from the `<slug>` the Guards derived. If it does not exist, stop: `❌ No approved plan at .claude/plans/feature-<slug>.md. Run /claude-feature first.`
+
+Read `<plan>` at the main worktree root. This file is the scope for this run.
 
 Its sections and its answer contract are fixed by `${CLAUDE_SKILL_DIR}/../../standards/plan.md`. A blank `- Answer:` accepts the `- Suggested:` line above it, so an unanswered question is a decision this run executes rather than a reason to stop.
 
@@ -152,7 +157,8 @@ Every stop point leaves recoverable state. The user resumes manually from the ap
 
 | Stop point                         | Recovery                                                                                                                                       |
 | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| No plan                            | Run `/claude-feature` to create one                                                                                                            |
+| No plan (derived)                  | Run `/claude-feature` to create one                                                                                                            |
+| No plan (caller-supplied)          | Check the path or slug passed to autoship, then re-run                                                                                         |
 | No diff baseline                   | Fetch origin so a merge base resolves against `main`, then re-run autoship                                                                     |
 | Empty changed-file list            | Re-run once the plan produces tracked output. Ship gitignored output outside the chain, never by tracking it.                                  |
 | Branch collision on worktree entry | `claude-worktree` Step 5 found `<slug>` already as a local branch. Resolve manually (rename or delete the stale branch), then re-run autoship. |

package/claude/skills/claude-orchestrate/references/orchestrator-dispatch.md

@@ -7,9 +7,9 @@ Run this at loop step 4, for a `## Run now` row whose plan is verified and whose
 
 ## Derive the candidate
 
-Resolve `<slug>` from the row's plan the way `claude-worktree` Step 2 resolves a plan-matched name, per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. Resolve `<type>` off that plan's `## Summary` and `**Files to touch:**` lines, per `${CLAUDE_SKILL_DIR}/../../standards/branch.md`, defaulting to `feat` when the lines settle nothing. The candidate branch is `<type>/<slug>`.
+Resolve `<slug>` from `<plan>`, the row's plan file, the way `claude-worktree` Step 2 resolves a plan-matched name, per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. Resolve `<type>` off that plan's `## Summary` and `**Files to touch:**` lines, per `${CLAUDE_SKILL_DIR}/../../standards/branch.md`, defaulting to `feat` when the lines settle nothing. The candidate branch is `<type>/<slug>`.
 
-This is the branch the worker takes, not a guess at one it will derive for itself. Carry the exact string into the launch below. Both halves of that derivation have already disagreed in production: one run checked `docs/remaining-skill-verdicts` against a worker that took `docs/skill-verdicts-decide`, and a later one checked `fix/path-form-hook` against a worker that took `feat/path-form-hook`. A check against a branch nobody uses verifies nothing, and the run dies anyway, since `claude-autoship` resolves its plan from the slug the worker actually took.
+This is the branch the worker takes, not a guess at one it will derive for itself. Carry the exact string into the launch below. Both halves of that derivation have already disagreed in production: one run checked `docs/remaining-skill-verdicts` against a worker that took `docs/skill-verdicts-decide`, and a later one checked `fix/path-form-hook` against a worker that took `feat/path-form-hook`. A check against a branch nobody uses verifies nothing, and a slug mismatch no longer fails the run downstream on its own, since `claude-autoship` now takes `<plan>` directly rather than resolving it from the worker's own branch. The check above is what has to catch a wrong candidate now.
 
 ## Check the branch is unclaimed
 
@@ -46,12 +46,12 @@ Name `<model>` on the launch, and pick it against the task rather than copying w
 ## Dispatch
 
 ```bash
-claude --bg --model <model> -n "orchestrator-<slug>" "Run /aitk:claude-worktree <type>/<slug>, then /aitk:claude-autoship .claude/tasks/<task-file>.md"
+claude --bg --model <model> -n "orchestrator-<slug>" "Run /aitk:claude-worktree <type>/<slug>, then /aitk:claude-autoship <plan>"
 ```
 
 `--bg, --background` starts the session as a background agent and returns immediately, `-n, --name` sets the display name `aitk sessions list` reads back for the worker cap, and `--model` overrides the inheritance the section above measured.
 
-The worktree call comes first and carries the branch as its argument, which is tier 0 of `claude-worktree` Step 2 and the only tier a caller can reach. `claude-autoship` Step 0 then finds the session already in a linked worktree and continues, which is a path it already documents. Autoship still resolves its plan, since the slug inside a dispatcher-named `<type>/<slug>` is the slug the dispatcher read off that plan.
+The worktree call comes first and carries the branch as its argument, which is tier 0 of `claude-worktree` Step 2 and the only tier a caller can reach. `claude-autoship` Step 0 then finds the session already in a linked worktree and continues, which is a path it already documents. The autoship call carries `<plan>`, the same file this runbook already read to derive the branch, so its Step 1 takes it as the caller-supplied plan rather than re-deriving one from the slug the worker's branch happens to carry.
 
 Naming the branch in prose instead was tried and closes nothing, because no tier of that ladder reads the prompt. A worker launched onto `main` cannot match tier 1, a board carrying more than one plan puts tier 2 out of reach, and tier 3 tells it to ask a person who is not there. Four workers took the right branch that way, by inference rather than by contract, which is the same judgment both live disagreements came from.
 

package/claude/skills/claude-orchestrate/references/orchestrator-sweep.md

@@ -10,6 +10,8 @@ Sweep the board as orchestrator after merging. Run this once per batch of merges
 3. Re-verify every plan already written, not only the ones this sweep writes. A queued plan goes stale from whatever merged while it waited, and the loop's verify step fires at handoff rather than after a merge, so nothing else catches it. Grep each construct the plan names and count the sites against its claim, then open each file rather than trusting its account.
 4. Re-check any precondition a plan states about live state outside the repository. A remote branch, an open issue, or an installed version was true when the plan was written and is not a fact about the tree.
 
+Run `aitk worktrees list` after the pull, which is the first point at which the merges this sweep followed are readable. It owns the reclaim rule and it removes nothing, so read its rows and act on the ones you mean to. Never substitute a git ancestry check for it.
+
 Run `aitk tasks validate` once the board is rewritten and before reporting it. It resolves every plan pointer, accounts every task file against the board and the backlog both, tests the `## Run now` file sets for overlap, and re-takes the two blocker kinds a command can settle. It reports and never writes, so fix each row it names and run it again. A finding it reports is a board defect rather than a task finding, so it goes nowhere but the board.
 
 Then run `orchestrator-parked.md` over the rows the validator listed as untested. Those carry the three blocker kinds no command settles, and the merge this sweep followed changed the tree under every one of them at once while the refill above re-read none. Take the untested rows alone rather than the whole board, since the validator already answered the rest.

package/docs/agents/commands.md

@@ -42,6 +42,7 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | `aitk records push`        | Commit the nine backed record folders and push them to a private records remote (`--json`)                                                                           |
 | `aitk records pull`        | Fetch the records remote and write it back, refusing rather than discarding unpushed records (`--json`)                                                              |
 | `aitk sessions list`       | Resolve live sessions to the worktree and branch each holds, filtered by `--branch` (`--json`)                                                                       |
+| `aitk worktrees list`      | Report which worktrees are reclaimable, keyed on the pull request having merged, with every refusal and the removal route named (`--json`)                           |
 | `aitk comments scan`       | Measure comment density by language and comment kind, with a trend recomputed from git                                                                               |
 | `aitk context audit`       | Report required sections, length, cited paths, reference form, catalog tables, provenance, superseded-decision narration, and index drift                            |
 | `aitk markdown audit`      | Fail any markdown path on a banned character, word, or spelling, and report the structural checkpoints                                                               |

package/docs/agents/index.md

@@ -39,3 +39,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

package/docs/agents/worktrees.md

@@ -0,0 +1,62 @@
+---
+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
+---
+
+# Worktrees
+
+## List
+
+`aitk worktrees list` reports every worktree of the current repository with a reclaim verdict and the reason behind it.
+
+```bash
+aitk worktrees list
+aitk worktrees list --json
+```
+
+| Option   | Behavior                                |
+| -------- | --------------------------------------- |
+| `--json` | Add a machine-readable record on stdout |
+
+It reads and removes nothing. The question it answers is which worktrees the work has finished with, which nothing in the loop asks: a worktree is created per feature and removed by nobody, so directories left by shipped work accumulate for the life of the checkout.
+
+Exit codes: `0` every worktree was read, `1` refused. The refusal carries a `reason` of `gh-missing`, `gh-failed`, or `sessions-unreadable`.
+
+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.
+
+## 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.
+
+| Refusal                  | What it means                                           |
+| ------------------------ | ------------------------------------------------------- |
+| `main-worktree`          | The main worktree, which is never reclaimable           |
+| `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 |
+| `unreadable-worktree`    | The working tree status could not be read               |
+| `held-by-session`        | A live session still holds the directory                |
+
+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.
+
+## 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.
+
+The one branch it did call merged was the one that had to stay. That branch had no pull request at all, sat at a release commit, and its worktree held finished work outside any commit. So the cheap test kept every directory safe to remove and offered the only one that was not.
+
+The read is one `gh pr list --state merged` for the whole repository rather than one call per worktree, which would be a network round trip inside a loop. It covers the most recent 200 merges, so a worktree older than that reads as having none and is refused, which fails in the direction that keeps a directory.
+
+## Two removal shapes
+
+`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.
+- `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.
+
+## What an unreadable input does
+
+It refuses the whole report rather than producing verdicts around the gap. An absent merge state and a branch with no merged pull request return the same empty answer, and so do an absent session roster and a worktree nobody holds. Reporting the second when it was the first is a false clean, and here that ends in a removal rather than in a warning.

package/package.json

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

package/src/cli.ts

@@ -27,6 +27,7 @@ import { register as context } from '@/commands/context'
 import { register as markdown } from '@/commands/markdown'
 import { register as records } from '@/commands/records'
 import { register as sessions } from '@/commands/sessions'
+import { register as worktrees } from '@/commands/worktrees'
 import { register as audits } from '@/commands/audits'
 import { register as secrets } from '@/commands/secrets'
 import { register as deps } from '@/commands/deps'
@@ -71,6 +72,7 @@ function showHelp(): void {
     `${GREY}│${NC}    markdown [cmd]     ${GREY}# Report markdown against the attribute standards (audit)${NC}`,
     `${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}    worktrees [cmd]    ${GREY}# Report which worktrees are reclaimable (list)${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}`,
@@ -117,6 +119,7 @@ function showHelp(): void {
     `${GREY}│${NC}    aitk records size --json`,
     `${GREY}│${NC}    aitk records push --json`,
     `${GREY}│${NC}    aitk sessions list --json`,
+    `${GREY}│${NC}    aitk worktrees list --json`,
     `${GREY}│${NC}    aitk secrets scan --json`,
     `${GREY}│${NC}    aitk deps audit --json`,
     `${GREY}│${NC}    aitk labels audit --json`,
@@ -167,6 +170,7 @@ context(program)
 markdown(program)
 records(program)
 sessions(program)
+worktrees(program)
 secrets(program)
 deps(program)
 labels(program)

package/src/commands/worktrees.ts

@@ -0,0 +1,191 @@
+import type { Command } from 'commander'
+import {
+  intro,
+  logInfo,
+  logStep,
+  logWarn,
+  outro,
+  pipeOutput,
+  plural,
+} from '@/ui'
+import {
+  type Refusal,
+  reclaimReport,
+  type Unreadable,
+  type WorktreeVerdict,
+} from '@/worktrees/reclaim'
+
+interface ListCommandOptions {
+  readonly json?: boolean
+}
+
+const REFUSALS: Record<Refusal, string> = {
+  'main-worktree': 'the main worktree, which is never reclaimable',
+  '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',
+  'unreadable-worktree': 'the working tree could not be read',
+  'held-by-session': 'a live session still holds it',
+}
+
+const UNREADABLE: Record<Unreadable, string> = {
+  'gh-missing':
+    'gh is not on the path, so the merge state could not be read. Install it and run this again.',
+  'gh-failed':
+    'The pull request read failed, so every worktree would report as unmerged whatever its real state. Authenticate gh and run this again.',
+  'sessions-unreadable':
+    'The session roster could not be read, so nothing was read about which worktrees are still held.',
+}
+
+export function register(program: Command): void {
+  const worktrees = program
+    .command('worktrees')
+    .description('Report which worktrees are reclaimable and which are not')
+    .helpOption('-h, --help', 'Show this help message')
+
+  worktrees
+    .command('list')
+    .description(
+      'Report every worktree with a reclaim verdict and the reason behind it',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  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.',
+        '',
+        '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.',
+        '',
+        'Examples:',
+        '  aitk worktrees list',
+        '  aitk worktrees list --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: ListCommandOptions) => {
+      process.exitCode = await runList(opts)
+    })
+}
+
+async function runList(opts: ListCommandOptions): Promise<number> {
+  const report = await reclaimReport({ cwd: process.cwd() })
+
+  intro('aitk worktrees list')
+
+  if (report.kind === 'unreadable') {
+    logStep('Refused')
+    logWarn(UNREADABLE[report.reason])
+    logInfo(report.detail)
+    outro()
+
+    if (opts.json) {
+      process.stdout.write(
+        `${JSON.stringify({
+          reason: report.reason,
+          detail: report.detail,
+          worktrees: [],
+        })}\n`,
+      )
+    }
+
+    return 1
+  }
+
+  reportWorktrees(report.worktrees)
+  outro()
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify({
+        reason: null,
+        detail: null,
+        worktrees: report.worktrees,
+      })}\n`,
+    )
+  }
+
+  return 0
+}
+
+function reportWorktrees(worktrees: readonly WorktreeVerdict[]): void {
+  logStep('Worktrees')
+
+  if (worktrees.length === 0) {
+    logInfo('No worktree resolved here. Run this inside a repository.')
+    return
+  }
+
+  logInfo(plural(worktrees.length, 'worktree'))
+  pipeOutput(worktrees.map(describe).join('\n'))
+
+  const reclaimable = worktrees.filter((entry) => entry.reclaimable)
+
+  logStep('Reclaimable')
+  if (reclaimable.length === 0) {
+    logInfo('None. Every worktree fails at least one condition.')
+    return
+  }
+
+  logWarn(
+    `${plural(reclaimable.length, 'worktree')} can be reclaimed. This reports and removes nothing, so run the named command yourself.`,
+  )
+}
+
+/**
+ * Names the evidence beside the conclusion on every row.
+ *
+ * The reading has two consumers and they act on different halves. The sweep
+ * reads the verdict to decide what to offer, and a person reads it to decide
+ * what to remove, so a row phrased for the first alone leaves the second
+ * removing a directory on a conclusion it cannot check.
+ */
+function describe(verdict: WorktreeVerdict): string {
+  const held = verdict.branch ?? 'detached'
+  const head = `${verdict.path}  ${held}`
+
+  if (!verdict.reclaimable) {
+    const reasons = verdict.refusals.map((refusal) => REFUSALS[refusal])
+    // A name is quoted because a session carries whatever string it was
+    // launched under, spaces included, and one command per name because a
+    // joined list reads as a single argument.
+    const routes =
+      verdict.route === 'session'
+        ? verdict.sessions.map(
+            (name) => `\n  Removal there goes through: claude rm '${name}'`,
+          )
+        : []
+    return `${head}\n  Refused: ${reasons.join('; ')}.${routes.join('')}`
+  }
+
+  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}`,
+  ].join('\n')
+}

package/src/worktrees/reclaim.ts

@@ -0,0 +1,306 @@
+import { $ } from 'bun'
+import { execa } from 'execa'
+import { gitEnv } from '@/git-env'
+import {
+  repositoryOf,
+  type ResolvedSession,
+  resolveSessions,
+  type SessionReport,
+} from '@/sessions/resolve'
+import { listWorktrees, type WorktreeEntry } from '@/worktree'
+
+const GH_TIMEOUT_MS = 30_000
+
+/**
+ * How many merged pull requests one read covers. A worktree older than this
+ * many merges reads as having none and is refused, which is the safe direction:
+ * the failure keeps a directory rather than removing one.
+ */
+const MERGED_LIMIT = 200
+
+/** Why one worktree cannot be reclaimed, one entry per failing condition. */
+export type Refusal =
+  | 'main-worktree'
+  | 'detached-head'
+  | 'no-merged-pull-request'
+  | 'uncommitted-changes'
+  | 'unreadable-worktree'
+  | 'held-by-session'
+
+/** Why the whole reading was refused, so no verdict was produced at all. */
+export type Unreadable = 'gh-missing' | 'gh-failed' | 'sessions-unreadable'
+
+/**
+ * Which removal shape applies. `session` removes the background session and its
+ * worktree together, and `worktree` removes a directory whose session has
+ * ended. Picking the wrong one strands state, so this is reported rather than
+ * assumed.
+ */
+export type Route = 'session' | 'worktree'
+
+/** No removal shape reaches the main worktree, which is what `null` says. */
+export type RemovalRoute = Route | null
+
+export interface WorktreeVerdict {
+  readonly path: string
+  readonly branch: string | null
+  readonly reclaimable: boolean
+  /** Every failing condition, so a reader sees what to fix rather than a bare refusal. */
+  readonly refusals: readonly Refusal[]
+  /** The pull request that retired the branch, so a report can name what it read. */
+  readonly pullRequest: number | null
+  /** The names of the live sessions holding this worktree, which is what `claude rm` takes. */
+  readonly sessions: readonly string[]
+  readonly route: RemovalRoute
+}
+
+export interface MergedPullRequest {
+  readonly branch: string
+  readonly number: number
+}
+
+export type MergedReport =
+  | { readonly kind: 'read'; readonly merged: readonly MergedPullRequest[] }
+  | {
+      readonly kind: 'unreadable'
+      readonly reason: Extract<Unreadable, 'gh-missing' | 'gh-failed'>
+      readonly detail: string
+    }
+
+export interface StatusReport {
+  /** False when the status read itself failed, so a clean `dirty` says nothing. */
+  readonly readable: boolean
+  readonly dirty: boolean
+}
+
+export type ReclaimReport =
+  | {
+      readonly kind: 'unreadable'
+      readonly reason: Unreadable
+      readonly detail: string
+    }
+  | { readonly kind: 'read'; readonly worktrees: readonly WorktreeVerdict[] }
+
+export interface ReclaimOptions {
+  readonly cwd?: string
+  readonly listWorktrees?: (cwd: string) => Promise<readonly WorktreeEntry[]>
+  readonly mergedPullRequests?: (cwd: string) => Promise<MergedReport>
+  readonly worktreeStatus?: (path: string) => Promise<StatusReport>
+  readonly resolve?: () => Promise<SessionReport>
+}
+
+/**
+ * Reads the pull request state for the whole repository in one call.
+ *
+ * One call rather than one per worktree, since the per-worktree shape is a
+ * network round trip inside a loop and the branches being matched are already
+ * known before any of them runs.
+ */
+async function mergedPullRequests(cwd: string): Promise<MergedReport> {
+  if (Bun.which('gh') === null) {
+    return {
+      kind: 'unreadable',
+      reason: 'gh-missing',
+      detail: 'gh is not on the path, so no merge state could be read.',
+    }
+  }
+
+  const args = [
+    'pr',
+    'list',
+    '--state',
+    'merged',
+    '--limit',
+    String(MERGED_LIMIT),
+    '--json',
+    'headRefName,number',
+  ]
+
+  try {
+    // `gh` resolves its repository through git, so it reads the same
+    // resolution variables a hook exports and they take precedence over `cwd`.
+    // A run from inside one would answer with another repository's merged
+    // branches, and a branch name that recurs across repositories would then
+    // match a merge that happened somewhere else and read a live worktree as
+    // reclaimable, which is the unsafe direction on an unrecoverable removal.
+    const result = await execa('gh', args, {
+      cwd,
+      timeout: GH_TIMEOUT_MS,
+      env: gitEnv(),
+      extendEnv: false,
+    })
+    const rows = JSON.parse(result.stdout) as readonly {
+      headRefName: string
+      number: number
+    }[]
+
+    return {
+      kind: 'read',
+      merged: rows.map((row) => ({
+        branch: row.headRefName,
+        number: row.number,
+      })),
+    }
+  } catch (error) {
+    return {
+      kind: 'unreadable',
+      reason: 'gh-failed',
+      detail: error instanceof Error ? error.message : String(error),
+    }
+  }
+}
+
+/**
+ * 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.
+ */
+async function worktreeStatus(path: string): Promise<StatusReport> {
+  const result = await $`git -C ${path} status --porcelain`
+    .env(gitEnv())
+    .quiet()
+    .nothrow()
+  if (result.exitCode !== 0) return { readable: false, dirty: false }
+
+  return { readable: true, dirty: result.stdout.toString().trim().length > 0 }
+}
+
+/**
+ * Names the live sessions holding one worktree.
+ *
+ * The path match is the direct reading and the branch match is what survives a
+ * path spelled differently on either side, such as a symlinked temporary
+ * directory. The branch half is scoped to the repository, since a branch name
+ * identifies a branch inside one and nothing across a machine.
+ */
+function holders(
+  entry: WorktreeEntry,
+  sessions: readonly ResolvedSession[],
+  repository: string | null,
+): readonly string[] {
+  return sessions
+    .filter(
+      (candidate) =>
+        candidate.worktree === entry.path ||
+        (entry.branch !== null &&
+          candidate.branch === entry.branch &&
+          candidate.repository === repository),
+    )
+    .map((candidate) => candidate.name)
+}
+
+function verdict(
+  entry: WorktreeEntry,
+  isMain: boolean,
+  status: StatusReport,
+  merged: ReadonlyMap<string, number>,
+  sessions: readonly ResolvedSession[],
+  repository: string | null,
+): WorktreeVerdict {
+  const held = holders(entry, sessions, repository)
+  const pullRequest =
+    entry.branch === null ? null : (merged.get(entry.branch) ?? null)
+  const refusals: Refusal[] = []
+
+  if (isMain) refusals.push('main-worktree')
+  if (entry.branch === null) refusals.push('detached-head')
+  else if (pullRequest === null) refusals.push('no-merged-pull-request')
+
+  if (!status.readable) refusals.push('unreadable-worktree')
+  else if (status.dirty) refusals.push('uncommitted-changes')
+
+  if (held.length > 0) refusals.push('held-by-session')
+
+  return {
+    path: entry.path,
+    branch: entry.branch,
+    reclaimable: refusals.length === 0,
+    refusals,
+    pullRequest,
+    sessions: held,
+    // No removal shape reaches the main worktree, and reporting one there
+    // offers a command whose only effect is to break the checkout. Deciding it
+    // 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',
+  }
+}
+
+/**
+ * Reports which worktrees are reclaimable and which are not, with the reason on
+ * each.
+ *
+ * Reclaimable means all three of a merged pull request, a clean working tree,
+ * and no live session holding the directory. Each alone has a case where
+ * removal loses something, and removal is unrecoverable here since a worktree
+ * is gitignored and no history stands behind it.
+ *
+ * The pull request is what decides the first condition rather than git
+ * ancestry. A repository that squash merges never makes a merged branch an
+ * ancestor of its trunk, so the ancestry reading calls shipped work unmerged
+ * and calls an abandoned branch sitting at a release commit merged, which is
+ * wrong in the one direction that removes a directory.
+ *
+ * An unreadable input refuses the whole reading rather than producing verdicts
+ * around it. An absent merge state and a branch with no merged pull request
+ * produce the same empty answer, as do an absent session roster and a worktree
+ * nobody holds, and reporting the second when it was the first is a false clean
+ * that ends in a removal.
+ */
+export async function reclaimReport(
+  opts: ReclaimOptions = {},
+): Promise<ReclaimReport> {
+  const cwd = opts.cwd ?? process.cwd()
+  const listAll = opts.listWorktrees ?? listWorktrees
+  const readMerged = opts.mergedPullRequests ?? mergedPullRequests
+  const readStatus = opts.worktreeStatus ?? worktreeStatus
+  const resolve = opts.resolve ?? resolveSessions
+
+  const [entries, merged, sessions, repository] = await Promise.all([
+    listAll(cwd),
+    readMerged(cwd),
+    resolve(),
+    repositoryOf(cwd),
+  ])
+
+  if (merged.kind === 'unreadable') {
+    return {
+      kind: 'unreadable',
+      reason: merged.reason,
+      detail: merged.detail,
+    }
+  }
+
+  if (sessions.kind !== 'resolved') {
+    return {
+      kind: 'unreadable',
+      reason: 'sessions-unreadable',
+      detail: `No session registry at ${sessions.dir}, so nothing was read about which worktrees are still held.`,
+    }
+  }
+
+  const byBranch = new Map(
+    merged.merged.map((request) => [request.branch, request.number]),
+  )
+  const statuses = await Promise.all(
+    entries.map((entry) => readStatus(entry.path)),
+  )
+
+  // `git worktree list` puts the main worktree first, which is the only signal
+  // separating it from a linked one in the porcelain output.
+  const worktrees = entries.map((entry, index) =>
+    verdict(
+      entry,
+      index === 0,
+      statuses[index] ?? { readable: false, dirty: false },
+      byBranch,
+      sessions.sessions,
+      repository,
+    ),
+  )
+
+  return { kind: 'read', worktrees }
+}