@jaybeeuu/agent-cortex 2.5.1 → 2.6.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 2.6.0
+
+### Minor Changes
+
+- c14bf85: `ctx version` now reports the installed harness versions beside the running CLI version: one line per installed harness read from the fingerprint its installer wrote (`~/.agent-cortex/pi/package.json`, `~/.agent-cortex/claude/.claude-plugin/plugin.json`), marked `current`, `stale`, `ahead` when the installed copy is newer, or `unknown` when the fingerprint is missing or unreadable. `ctx version --json` prints the same data as records. The command is read-only — no install, no network, no writes — and `--version` still prints the bare CLI version.
+
+### Patch Changes
+
+- ccb1788: Add `skills/workflow/ralph/scripts/prune-worktrees.mjs`, the deterministic pass that converges the
+  ralph worktree set with bead state. It scans `.agent-cortex/worktrees/*`, classifies each directory
+  by its bead as a closed-bead worktree, an open-bead worktree, or an orphan, and removes a
+  closed-bead worktree with its local and remote branch. A dirty tree, a locked worktree, or an
+  unpushed branch refuses that worktree with the reason. Orphans are reported only, and
+  `--remove-orphans` is the single path that removes one.
+
 ## 2.5.1
 
 ### Patch Changes

package/README.md

@@ -478,6 +478,30 @@ re-registers it; `--output <dir>` generates a preview only). The only committed
 so never edit anything under it. CI validates the Claude materialiser (structural checks on
 a temp-dir install) so sources and installer can never silently diverge.
 
+## Checking installed versions (`agent-cortex version`)
+
+`agent-cortex version` prints the running CLI version, then one line for each installed
+harness: its name, the version its installer recorded, and a marker. The fingerprint is the
+manifest the installer already writes — `~/.agent-cortex/pi/package.json` for pi and
+`~/.agent-cortex/claude/.claude-plugin/plugin.json` for Claude Code — so the report needs no
+separate state file.
+
+```sh
+agent-cortex version            # CLI version, then one line per installed harness
+agent-cortex version --json     # the same data as JSON records
+agent-cortex --version          # the bare CLI version, for scripts
+```
+
+The marker is `current` when the installed copy matches the running CLI, `stale` when it is
+older, and `ahead` when it is newer — a downgraded CLI leaves its installs ahead of it. A
+harness root that exists with a missing or broken fingerprint reports `unknown` for both the
+version and the marker, because an install that cannot be read is never reported as `current`.
+Only plain release versions are compared, so a prerelease on either side also reports
+`unknown`. A harness with no installer gets no line.
+
+The command is read-only: it stats and reads those manifests, and never installs, writes, or
+reaches the network.
+
 ## Migrating a beads workspace
 
 `agent-cortex migrate` brings the `.beads` workspace it runs in — any repo, not just this

package/bin/agent-cortex.mjs

@@ -1,6 +1,11 @@
 #!/usr/bin/env node
 
 import { parseArgs, buildHelpText, resolveProgramName, validateHarness } from "../lib/cli.mjs";
+import {
+  collectVersionReport,
+  formatVersionReport,
+  serialiseVersionReport,
+} from "../lib/harness-versions.mjs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { readFile } from "node:fs/promises";
@@ -45,8 +50,22 @@ async function readPackageVersion() {
 }
 
 if (parsed.command === "version") {
+  if (parsed.optionError) {
+    process.stderr.write(`${parsed.optionError}\n`);
+    process.exit(1);
+  }
   try {
-    process.stdout.write(`${await readPackageVersion()}\n`);
+    const cliVersion = await readPackageVersion();
+    // `--version` prints the bare version for scripts; the `version` subcommand
+    // adds one line per installed harness, read from the installers'
+    // fingerprints (read-only — no install, no network, no writes).
+    if (parsed.report === true) {
+      const report = await collectVersionReport({ cli: cliVersion });
+      const output = parsed.json === true ? serialiseVersionReport(report) : formatVersionReport(report);
+      process.stdout.write(`${output}\n`);
+    } else {
+      process.stdout.write(`${cliVersion}\n`);
+    }
   } catch (err) {
     process.stderr.write(`${/** @type {Error} */ (err).message}\n`);
     process.exit(1);

package/lib/cli.mjs

@@ -5,6 +5,8 @@ import { basename } from "node:path";
  * populated only for the commands that accept them.
  * @typedef {object} ParsedArgs
  * @property {"help" | "version" | "install" | "migrate" | "unknown"} command
+ * @property {boolean} [report] `version` subcommand: report installed harnesses too
+ * @property {boolean} [json] `version --json`: print the report as JSON
  * @property {string | null} [harness]
  * @property {string} [name]
  * @property {string} [optionError]
@@ -69,6 +71,20 @@ export function parseArgs(argv, programName = DEFAULT_PROGRAM_NAME) {
 
   const [command, ...rest] = argv;
 
+  if (command === "version") {
+    // The `version` subcommand reports the installed harness versions; the
+    // `--version` flag above stays a bare CLI version for scripts.
+    let json = false;
+    for (const arg of rest) {
+      if (arg === "--json") {
+        json = true;
+        continue;
+      }
+      return { command: "version", report: true, optionError: `Unknown option "${arg}". Run "${programName} --help" for usage.` };
+    }
+    return json ? { command: "version", report: true, json } : { command: "version", report: true };
+  }
+
   if (command === "install") {
     let harness = null;
     let i = 0;
@@ -231,6 +247,13 @@ Commands:
                         --apply         Apply every pending step, verifying each
                         --dir <path>    Read idea files from <path> instead of
                                         docs/ideas (step v2's source)
+  version             Print the running CLI version, then one line per installed
+                      harness: its name, the version its installer recorded, and
+                      a marker comparing the two — current, stale, ahead (the
+                      installed copy is newer), or unknown (no readable
+                      fingerprint). Read-only: no install, no network, no writes.
+                      Options:
+                        --json          Print the same data as JSON records
   --help, -h          Show this help text
   --version, -V       Print the package version`;
 }

package/lib/harness-versions.mjs

@@ -0,0 +1,156 @@
+// The read side of the installers' fingerprints: `ctx version` reports which
+// harnesses are installed and how their version compares with the running CLI.
+//
+// Read-only by construction — the module only stats and reads, so the command
+// path never writes, installs, or reaches the network. A harness with no
+// installer gets no entry in the table, so it can never appear in the report.
+
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { isDirectory } from "../scripts/lib/fs.mjs";
+
+/**
+ * Where one harness records the version it was installed at: an artifact root
+ * under the home install directory, and the version file inside it.
+ * @typedef {object} HarnessFingerprint
+ * @property {"claude" | "pi"} harness
+ * @property {string[]} root Path segments of the artifact root, relative to home
+ * @property {string[]} file Path segments of the version file, relative to the root
+ */
+
+// Ordered as the installers are listed; the report keeps this order.
+/** @type {HarnessFingerprint[]} */
+const HARNESS_FINGERPRINTS = [
+  { harness: "claude", root: [".agent-cortex", "claude"], file: [".claude-plugin", "plugin.json"] },
+  { harness: "pi", root: [".agent-cortex", "pi"], file: ["package.json"] },
+];
+
+/**
+ * How an installed copy relates to the running CLI. `unknown` covers both a
+ * fingerprint that cannot be read and a version that is not a plain release —
+ * an unreadable install is never reported as `current`.
+ * @typedef {"current" | "stale" | "ahead" | "unknown"} Staleness
+ */
+
+/**
+ * One installed harness in the report.
+ * @typedef {object} HarnessVersion
+ * @property {string} harness
+ * @property {string} installed The installed version, or "unknown"
+ * @property {string} cli The running CLI version
+ * @property {Staleness} staleness
+ */
+
+/**
+ * Everything the `version` command reports.
+ * @typedef {object} VersionReport
+ * @property {string} cli The running CLI version
+ * @property {HarnessVersion[]} harnesses One entry per installed harness
+ */
+
+const UNKNOWN = "unknown";
+
+// Only plain releases are compared. A prerelease or a range is not "current"
+// just because its numeric core matches, so it reports unknown instead.
+const PLAIN_RELEASE = /^(\d+)\.(\d+)\.(\d+)$/;
+
+/**
+ * Compare two plain semver releases.
+ * @param {string} a
+ * @param {string} b
+ * @returns {-1 | 0 | 1 | null} The order, or null when either side is not a plain release
+ */
+function compareReleases(a, b) {
+  const left = PLAIN_RELEASE.exec(a);
+  const right = PLAIN_RELEASE.exec(b);
+  if (left === null || right === null) return null;
+  for (let segment = 1; segment <= 3; segment++) {
+    const l = Number(left[segment]);
+    const r = Number(right[segment]);
+    if (l !== r) return l < r ? -1 : 1;
+  }
+  return 0;
+}
+
+/**
+ * @param {string | null} installed null when the fingerprint is unreadable
+ * @param {string} cli
+ * @returns {Staleness}
+ */
+function stalenessOf(installed, cli) {
+  if (installed === null) return "unknown";
+  const order = compareReleases(installed, cli);
+  if (order === null) return "unknown";
+  if (order < 0) return "stale";
+  return order > 0 ? "ahead" : "current";
+}
+
+/**
+ * Read the version one harness recorded at install time.
+ * @param {string} home
+ * @param {HarnessFingerprint} fingerprint
+ * @returns {Promise<{ installed: boolean, version: string | null }>} `installed`
+ *   is false when the artifact root is absent; `version` is null when the
+ *   fingerprint is missing, malformed, or carries no version string
+ */
+async function readInstalledVersion(home, fingerprint) {
+  const root = join(home, ...fingerprint.root);
+  if (!(await isDirectory(root))) return { installed: false, version: null };
+  try {
+    /** @type {{ version?: unknown }} */
+    const manifest = JSON.parse(await readFile(join(root, ...fingerprint.file), "utf-8"));
+    const version = manifest?.version;
+    return { installed: true, version: typeof version === "string" && version !== "" ? version : null };
+  } catch {
+    return { installed: true, version: null };
+  }
+}
+
+/**
+ * Report the running CLI version and the installed version of every harness
+ * whose artifact root exists.
+ * @param {{ cli: string, home?: string }} options `home` defaults to the real
+ *   home directory; tests pass a fixture directory
+ * @returns {Promise<VersionReport>}
+ */
+export async function collectVersionReport({ cli, home = homedir() }) {
+  /** @type {HarnessVersion[]} */
+  const harnesses = [];
+  for (const fingerprint of HARNESS_FINGERPRINTS) {
+    const { installed, version } = await readInstalledVersion(home, fingerprint);
+    if (!installed) continue;
+    harnesses.push({
+      harness: fingerprint.harness,
+      installed: version ?? UNKNOWN,
+      cli,
+      staleness: stalenessOf(version, cli),
+    });
+  }
+  return { cli, harnesses };
+}
+
+/**
+ * Render the report as the default, human-readable output: the CLI version on
+ * the first line, then one line per installed harness. A harness whose version
+ * could not be read prints `unknown` twice — once for the version and once for
+ * the marker, because neither is known.
+ * @param {VersionReport} report
+ * @returns {string} Text without a trailing newline
+ */
+export function formatVersionReport(report) {
+  const lines = [report.cli];
+  for (const entry of report.harnesses) {
+    lines.push(`${entry.harness} ${entry.installed} ${entry.staleness}`);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Render the report as JSON, one record per installed harness.
+ * @param {VersionReport} report
+ * @returns {string} JSON without a trailing newline
+ */
+export function serialiseVersionReport(report) {
+  return JSON.stringify(report, null, 2);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaybeeuu/agent-cortex",
-  "version": "2.5.1",
+  "version": "2.6.0",
   "description": "Personal PI package with custom agents, skills, and extensions",
   "keywords": [
     "pi-package"

package/skills/workflow/ralph/REFERENCE.md

@@ -204,6 +204,27 @@ For each parent task bead (`<parent-id>`):
 
 ---
 
+## Pruning Worktrees
+
+A worktree outlives its bead: ralph leaves the directory behind when a feature closes, and a crashed run leaves one with no bead at all. `skills/workflow/ralph/scripts/prune-worktrees.mjs` converges `.agent-cortex/worktrees/*` with bead state.
+
+```bash
+node skills/workflow/ralph/scripts/prune-worktrees.mjs                  # remove closed-bead worktrees, report the rest
+node skills/workflow/ralph/scripts/prune-worktrees.mjs --remove-orphans # also remove open-bead and missing-bead worktrees
+```
+
+**Candidacy comes from bead state, never from git ancestry.** The repo squash-merges, so every landed branch still reports as unmerged. A directory named after a bead that `bd show` reports `closed` is the only proof that admits removal; an open bead, a missing bead, or a bead `bd` could not answer for is kept unless `--remove-orphans` asks otherwise. A bead `bd` could not read is never removed, whatever the flags say.
+
+**A candidate that fails a guard is refused, and the reason is printed.** The guards are: dirty working tree, `locked` worktree, detached HEAD, directory not registered with git, branch with no upstream, and branch with unpushed commits.
+
+**Removal is three commands.** `git worktree remove <path>`, then `git branch -D <branch>`, then `git push origin --delete <branch>`. The remote branch name is the worktree's own checked-out branch, so ralph's `feature/<parent-id>` deletes `origin/feature/<parent-id>`. A remote ref that git already reports as gone is not a failure.
+
+**Exit status is 1 whenever any scanned worktree survived the run.** An open bead counts as survival, so a normal run against a live backlog exits 1. Read the per-worktree report; do not treat the status as a verdict on the worktree you asked about.
+
+**An unregistered stale directory is refused forever.** Earlier git runs may have dropped its registration, so every scan reports it and never removes it. Clean it up by hand: `git worktree prune`, then `rm -rf <path>`.
+
+---
+
 ## Feature PR Gate
 
 When the `document` chore for a parent task completes:

package/skills/workflow/ralph/SKILL.md

@@ -96,7 +96,7 @@ bd show <id>                   # full detail, including the worker's notes
 - **Multi-feature epics** (two or more feature task children): the epic runs on `epic/<epic-id>`, based on `origin/main` — never local `main`. Each `execution:afk` parent task runs on `feature/<parent-id>`, based from its epic branch, in the dedicated worktree `.agent-cortex/worktrees/<parent-id>`.
 - Feature PR gate: `feature/<parent-id>` → `epic/<epic-id>` (or → `main` for single-feature epics). Epic PR gate: `epic/<epic-id>` → `main`.
 - **Never stack branches.** `feature/<parent-id>` is based on `epic/<epic-id>` (or `origin/main`), never on another `feature/*`. A dependency between two tasks lives in the bead graph (`bd dep add <waiting> <blocked-on>`) so the dependent task stays out of `bd ready` until its dependency has merged — stacking the branch defeats that gate by hand and costs a rebase-on-squash later (see `git-workflow` rule 3).
-- Branch/worktree setup and the PR commands live in REFERENCE.md (_Feature branches and worktrees_, _Feature PR gate_).
+- Branch/worktree setup and the PR commands live in REFERENCE.md (_Feature branches and worktrees_, _Feature PR gate_). Closed-bead worktrees are reclaimed by `skills/workflow/ralph/scripts/prune-worktrees.mjs`, which removes worktrees whose bead is closed, reports the rest, and removes an orphan only with `--remove-orphans` (REFERENCE.md, _Pruning Worktrees_).
 
 ### 7. HITL pause and shutdown
 

package/skills/workflow/ralph/scripts/prune-worktrees.mjs

@@ -0,0 +1,346 @@
+// Converges the ralph worktree set with bead state.
+//
+// Ralph runs each bead in `.agent-cortex/worktrees/<bead-id>` and leaves the
+// worktree behind after the bead closes; crashed runs leave orphans. This pass
+// reads bead state, not git ancestry: this repo squash-merges, so every ancestry
+// test reports a landed branch as unmerged.
+//
+// Zero dependencies: run with `node prune-worktrees.mjs`.
+
+import { execFile } from 'node:child_process';
+import { readdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { promisify } from 'node:util';
+import { pathToFileURL } from 'node:url';
+
+const execFileAsync = promisify(execFile);
+
+// BD_PATH env override lets machines where bd is not on PATH pin a location.
+const BD_PATH = process.env.BD_PATH || 'bd';
+
+/** @typedef {'closed-bead' | 'open-bead' | 'orphan' | 'unclassified'} Classification */
+/** @typedef {'removed' | 'kept' | 'refused'} Outcome */
+
+/**
+ * @typedef {object} WorktreeEntry
+ * @property {string} id                  Bead id, taken from the directory name.
+ * @property {string} path                Absolute path of the worktree.
+ * @property {string | null} branch       Checked-out branch, or null when unknown.
+ * @property {Classification} classification
+ * @property {string} beadStatus          Raw `bd` status, or `'missing'`.
+ * @property {Outcome} outcome
+ * @property {string[]} reasons           Why the worktree was not removed.
+ */
+
+/**
+ * @typedef {object} PruneResult
+ * @property {WorktreeEntry[]} entries
+ * @property {number} exitCode
+ */
+
+/**
+ * The text of a failed child-process call: git's stderr when it has one, the
+ * error message otherwise.
+ * @param {unknown} error
+ * @returns {string}
+ */
+function errorText(error) {
+  if (typeof error === 'object' && error !== null) {
+    const { stderr, message } = /** @type {{ stderr?: unknown, message?: unknown }} */ (error);
+    if (typeof stderr === 'string' && stderr.trim() !== '') return stderr;
+    if (typeof message === 'string') return message;
+  }
+  return String(error);
+}
+
+/**
+ * @param {unknown} error
+ * @returns {boolean} true when the error is a missing path, not a failure.
+ */
+function isMissingPath(error) {
+  return typeof error === 'object' && error !== null && /** @type {{ code?: unknown }} */ (error).code === 'ENOENT';
+}
+
+/** @type {(args: string[]) => Promise<string>} */
+async function runBd(args) {
+  const { stdout } = await execFileAsync(BD_PATH, args, { encoding: 'utf-8' });
+  return stdout;
+}
+
+/**
+ * Run git in `cwd` and report the outcome rather than throwing: a refusal is an
+ * expected domain result here, not an emergency.
+ * @param {string} cwd
+ * @param {string[]} args
+ * @returns {Promise<{ ok: true, stdout: string } | { ok: false, stderr: string }>}
+ */
+async function runGit(cwd, args) {
+  try {
+    const { stdout } = await execFileAsync('git', args, { cwd, encoding: 'utf-8' });
+    return { ok: true, stdout };
+  } catch (error) {
+    return { ok: false, stderr: errorText(error) };
+  }
+}
+
+/**
+ * List the worktree directories under `.agent-cortex/worktrees`, ignoring
+ * everything else on disk. A missing directory means nothing to prune.
+ * @param {string} repoRoot
+ * @returns {Promise<string[]>} absolute paths, sorted for stable output.
+ */
+async function listWorktreePaths(repoRoot) {
+  const worktreesDir = join(repoRoot, '.agent-cortex', 'worktrees');
+  /** @type {import('node:fs').Dirent[]} */
+  let dirents;
+  try {
+    dirents = await readdir(worktreesDir, { withFileTypes: true });
+  } catch (error) {
+    if (isMissingPath(error)) return [];
+    throw error;
+  }
+  return dirents
+    .filter((dirent) => dirent.isDirectory())
+    .map((dirent) => join(worktreesDir, dirent.name))
+    .sort();
+}
+
+/**
+ * Map each registered worktree path to its checked-out branch and lock state.
+ * @param {string} repoRoot
+ * @returns {Promise<Map<string, { branch: string | null, locked: string | null }>>}
+ */
+async function readRegisteredWorktrees(repoRoot) {
+  const result = await runGit(repoRoot, ['worktree', 'list', '--porcelain']);
+  /** @type {Map<string, { branch: string | null, locked: string | null }>} */
+  const registered = new Map();
+  if (!result.ok) return registered;
+
+  for (const block of result.stdout.split('\n\n')) {
+    const lines = block.split('\n');
+    const pathLine = lines.find((line) => line.startsWith('worktree '));
+    if (pathLine === undefined) continue;
+    const branchLine = lines.find((line) => line.startsWith('branch '));
+    const lockedLine = lines.find((line) => line.startsWith('locked'));
+    registered.set(pathLine.slice('worktree '.length), {
+      branch: branchLine === undefined ? null : branchLine.slice('branch refs/heads/'.length),
+      locked: lockedLine === undefined ? null : lockedLine.slice('locked'.length).trim(),
+    });
+  }
+  return registered;
+}
+
+/**
+ * Resolve one worktree's bead and classify it.
+ * @param {string} id
+ * @param {(args: string[]) => Promise<string>} exec
+ * @returns {Promise<{ classification: Classification, beadStatus: string }>}
+ */
+async function classifyBead(id, exec) {
+  let stdout;
+  try {
+    stdout = await exec(['show', id, '--json']);
+  } catch (error) {
+    const message = errorText(error);
+    if (/not found|no issues found/i.test(message)) {
+      return { classification: 'orphan', beadStatus: 'missing' };
+    }
+    return { classification: 'unclassified', beadStatus: `error: ${message.trim()}` };
+  }
+
+  const beads = JSON.parse(stdout);
+  const bead = (Array.isArray(beads) ? beads[0] : beads) ?? {};
+  const status = String(bead.status ?? 'unknown');
+  return { classification: status === 'closed' ? 'closed-bead' : 'open-bead', beadStatus: status };
+}
+
+/**
+ * Reasons git refuses to tear a worktree down. A worktree removed anyway would
+ * throw away uncommitted work or an unpushed branch, so every reason keeps the
+ * worktree in place.
+ * @param {{ path: string, registered: { branch: string | null, locked: string | null } | undefined }} target
+ * @param {(cwd: string, args: string[]) => Promise<{ ok: true, stdout: string } | { ok: false, stderr: string }>} git
+ * @returns {Promise<{ branch: string | null, reasons: string[] }>}
+ */
+async function findRefusals({ path, registered }, git) {
+  /** @type {string[]} */
+  const reasons = [];
+
+  if (registered === undefined) {
+    return { branch: null, reasons: ['not a registered git worktree'] };
+  }
+  if (registered.locked !== null) {
+    reasons.push(registered.locked === '' ? 'worktree is locked' : `worktree is locked: ${registered.locked}`);
+  }
+  if (registered.branch === null) {
+    return { branch: null, reasons: [...reasons, 'worktree is not on a branch'] };
+  }
+
+  const status = await git(path, ['status', '--porcelain']);
+  if (!status.ok) return { branch: registered.branch, reasons: [...reasons, `worktree cannot be read: ${status.stderr.trim()}`] };
+  const dirtyPaths = status.stdout.split('\n').filter((line) => line !== '').length;
+  if (dirtyPaths > 0) reasons.push(`worktree is dirty: ${dirtyPaths} uncommitted path(s)`);
+
+  const upstream = await git(path, ['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}']);
+  if (!upstream.ok) {
+    reasons.push(`branch ${registered.branch} has no remote-tracking branch`);
+    return { branch: registered.branch, reasons };
+  }
+  const trackingRef = upstream.stdout.trim();
+  const unpushed = await git(path, ['rev-list', '--count', `${trackingRef}..HEAD`]);
+  if (!unpushed.ok) return { branch: registered.branch, reasons: [...reasons, `branch ${registered.branch} cannot be compared with ${trackingRef}: ${unpushed.stderr.trim()}`] };
+  const unpushedCommits = Number.parseInt(unpushed.stdout.trim(), 10);
+  if (unpushedCommits > 0) {
+    reasons.push(`branch ${registered.branch} has ${unpushedCommits} commit(s) not pushed to ${trackingRef}`);
+  }
+
+  return { branch: registered.branch, reasons };
+}
+
+/**
+ * Remove a worktree and its branch, locally and on the remote.
+ * @param {string} repoRoot
+ * @param {{ path: string, branch: string }} target
+ * @param {(cwd: string, args: string[]) => Promise<{ ok: true, stdout: string } | { ok: false, stderr: string }>} git
+ * @returns {Promise<{ ok: true } | { ok: false, reasons: string[] }>}
+ */
+async function removeWorktree(repoRoot, { path, branch }, git) {
+  /** @type {string[]} */
+  const reasons = [];
+
+  const removed = await git(repoRoot, ['worktree', 'remove', path]);
+  if (!removed.ok) {
+    return { ok: false, reasons: [`git worktree remove failed: ${removed.stderr.trim()}`] };
+  }
+
+  const local = await git(repoRoot, ['branch', '-D', branch]);
+  if (!local.ok) reasons.push(`local branch ${branch} could not be deleted: ${local.stderr.trim()}`);
+
+  const remote = await git(repoRoot, ['push', 'origin', '--delete', branch]);
+  const remoteGone = /remote ref does not exist/i.test(remote.ok ? '' : remote.stderr);
+  if (!remote.ok && !remoteGone) {
+    reasons.push(`remote branch ${branch} could not be deleted: ${remote.stderr.trim()}`);
+  }
+
+  return reasons.length === 0 ? { ok: true } : { ok: false, reasons };
+}
+
+/**
+ * Converge `.agent-cortex/worktrees` with bead state: remove closed-bead
+ * worktrees, report everything else.
+ * @param {object} options
+ * @param {string} options.repoRoot                              Repository to prune.
+ * @param {boolean} [options.removeOrphans]                       Also remove worktrees whose bead is open or missing.
+ * @param {(args: string[]) => Promise<string>} [options.exec]    bd runner; injectable for tests.
+ * @param {(cwd: string, args: string[]) => Promise<{ ok: true, stdout: string } | { ok: false, stderr: string }>} [options.git]  git runner; injectable for tests.
+ * @returns {Promise<PruneResult>}
+ */
+export async function pruneWorktrees({ repoRoot, exec = runBd, removeOrphans = false, git = runGit }) {
+  const registered = await readRegisteredWorktrees(repoRoot);
+  /** @type {WorktreeEntry[]} */
+  const entries = [];
+
+  for (const path of await listWorktreePaths(repoRoot)) {
+    const id = path.slice(dirname(path).length + 1);
+    const { classification, beadStatus } = await classifyBead(id, exec);
+
+    /** @type {WorktreeEntry} */
+    const entry = { id, path, branch: registered.get(path)?.branch ?? null, classification, beadStatus, outcome: 'kept', reasons: [] };
+
+    // A closed bead is the proof. Anything else — an open bead, a missing bead,
+    // a bead bd could not answer for — is only removed on explicit request, and
+    // an unreadable bead is never removed at all.
+    const wanted = classification === 'closed-bead' || (classification !== 'unclassified' && removeOrphans);
+    if (wanted) {
+      const { branch, reasons } = await findRefusals({ path, registered: registered.get(path) }, git);
+      entry.branch = branch;
+      if (reasons.length > 0) {
+        entry.outcome = 'refused';
+        entry.reasons = reasons;
+      } else if (branch === null) {
+        entry.outcome = 'refused';
+        entry.reasons = ['worktree is not on a branch'];
+      } else {
+        const removal = await removeWorktree(repoRoot, { path, branch }, git);
+        entry.outcome = removal.ok ? 'removed' : 'refused';
+        if (!removal.ok) entry.reasons = removal.reasons;
+      }
+    }
+
+    entries.push(entry);
+  }
+
+  return { entries, exitCode: entries.some((entry) => entry.outcome !== 'removed') ? 1 : 0 };
+}
+
+// ─── CLI ──────────────────────────────────────────────────────────────────────
+
+const USAGE = `Usage: node prune-worktrees.mjs [--remove-orphans]
+
+Removes worktrees under .agent-cortex/worktrees whose bead is closed, then
+reports the rest. A worktree whose bead is open or missing is an orphan: it is
+only removed when --remove-orphans is passed. Run from anywhere inside the
+repository.
+`;
+
+/** Every flag the CLI accepts. */
+const REMOVE_ORPHANS_FLAG = '--remove-orphans';
+
+class UsageError extends Error {}
+
+/**
+ * Resolve the repository root from any directory inside it — the main checkout
+ * or a linked worktree. The shared `.git` directory is one level below the root
+ * in both cases.
+ * @param {string} cwd
+ * @returns {Promise<string | null>}
+ */
+async function resolveRepoRoot(cwd) {
+  const result = await runGit(cwd, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+  return result.ok ? dirname(result.stdout.trim()) : null;
+}
+
+/**
+ * @param {object} options
+ * @param {string[]} options.argv                                  CLI arguments (without node/script).
+ * @param {string} [options.cwd]                                   Directory the CLI was invoked from. * @param {(args: string[]) => Promise<string>} [options.exec]      bd runner; injectable for tests.
+ * @param {(cwd: string, args: string[]) => Promise<{ ok: true, stdout: string } | { ok: false, stderr: string }>} [options.git]
+ * @param {(chunk: string) => void} [options.write]                  stdout sink; injectable for tests.
+ * @returns {Promise<number>} process exit code.
+ */
+export async function runCli({ argv, cwd = process.cwd(), exec = runBd, git = runGit, write = (chunk) => process.stdout.write(chunk) }) {
+  if (argv.includes('--help') || argv.includes('-h')) {
+    write(USAGE);
+    return 0;
+  }
+  const unknown = argv.filter((arg) => arg !== REMOVE_ORPHANS_FLAG);
+  if (unknown.length > 0) throw new UsageError(`unexpected argument: ${unknown[0]}`);
+  const removeOrphans = argv.includes(REMOVE_ORPHANS_FLAG);
+
+  const repoRoot = await resolveRepoRoot(cwd);
+  if (repoRoot === null) throw new Error('not inside a git repository');
+
+  const { entries, exitCode } = await pruneWorktrees({ repoRoot, exec, removeOrphans, git });
+
+  write(`Scanning ${join(repoRoot, '.agent-cortex', 'worktrees')}\n`);
+  for (const entry of entries) {
+    const detail = entry.reasons.length > 0 ? ` — ${entry.reasons.join('; ')}` : '';
+    write(`  ${entry.id.padEnd(24)} ${entry.classification.padEnd(13)} ${entry.outcome}${detail}\n`);
+  }
+  const removed = entries.filter((entry) => entry.outcome === 'removed').length;
+  write(`Removed ${removed} of ${entries.length} worktree(s).\n`);
+
+  return exitCode;
+}
+
+// Only run the CLI when invoked directly, so tests can import the module.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  runCli({ argv: process.argv.slice(2) })
+    .then((code) => {
+      process.exitCode = code;
+    })
+    .catch((error) => {
+      process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+      process.exitCode = error instanceof UsageError ? 2 : 1;
+    });
+}