@erclx/aitk 3.30.0 → 3.31.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.31.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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.31.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 }
+}