vouchington-tooling 0.52.1 → 0.53.0

package/README.md

@@ -230,6 +230,33 @@ Host-lock environment:
 `git_worktree_canonical_path_hash <path>` helper resolves the physical path and prints a stable
 `d` plus the first 12 lowercase hexadecimal characters of its SHA-256 digest.
 
+## Reclaiming finished worktrees
+
+`vouchington worktree reclaim [--yes] [--json]` removes git worktrees whose work is done. It is a
+dry run unless `--yes` is passed. It prints one line per worktree (`reclaimed`, `would reclaim`, or
+`kept: <reason>`, control characters escaped), or `{ dryRun, worktrees }` with `--json`.
+
+It skips the main checkout, the caller's own worktree, and locked, bare, detached and missing
+worktrees. Any other worktree is kept, with a reason, unless all of these hold:
+
+- `git status` (untracked files and submodules included) is empty, and no index entry is
+  assume-unchanged or skip-worktree.
+- `gh pr list --head <branch>` has a merged or closed pull request from this repository (not a
+  fork) whose `headRefOid` equals HEAD, and no open pull request from this repository. That PR also
+  proves HEAD is published, so squash merges whose branch was deleted are reclaimed. A `gh` failure,
+  or a query returning 1000 results, keeps the worktree.
+
+With `--yes`, HEAD and cleanliness are checked again right before `git worktree remove <path>` runs.
+It is never forced, and a refusal from git is reported as kept. Ignored files (for example `.env`, `node_modules`, build output) are deleted with the worktree, exactly as `git worktree remove` does; keep anything you need outside ignored paths or commit it. An unexpected error on one worktree is reported as `kept: error: <message>` and the run carries on. There is no `prune`, no branch
+deletion, and git runs with `core.fsmonitor=false`.
+
+Known limitations: git cannot check and remove a worktree atomically, so a worktree that changes in the moment between the final check and `git worktree remove` can still be removed; the final check runs immediately before removal to keep that window small.
+
+This is NOT a security boundary. Run it as a trusted user or agent, and do not grant it as an
+unconditional allow rule. It has no teardown hook: per-worktree resources such as databases and
+containers are reclaimed afterwards by the consumer's own orphan cleanup, because the worktree is
+gone.
+
 ## Library
 
 ```ts

package/dist/cli/commands/worktree.d.mts

@@ -0,0 +1,2 @@
+/** `vouchington worktree reclaim [--yes] [--json]`: exits 2 on bad usage, 1 when git cannot list. */
+export declare function runWorktreeCommand(args: readonly string[], env?: NodeJS.ProcessEnv, cwd?: string): number;

package/dist/cli/commands/worktree.mjs

@@ -0,0 +1,21 @@
+import { formatReport, reclaimWorktrees } from "../../git-worktrees/reclaim.mjs";
+import { commandUsage } from "../usage.mjs";
+/** `vouchington worktree reclaim [--yes] [--json]`: exits 2 on bad usage, 1 when git cannot list. */
+export function runWorktreeCommand(args, env = process.env, cwd = process.cwd()) {
+    const [subcommand, ...flags] = args;
+    const unknown = flags.find((flag) => flag !== '--yes' && flag !== '--json');
+    if (subcommand !== 'reclaim' || unknown !== undefined) {
+        process.stderr.write(`vouchington: expected: reclaim [--yes] [--json]\n${commandUsage('worktree')}`);
+        return 2;
+    }
+    try {
+        const report = reclaimWorktrees(flags.includes('--yes'), { cwd, env });
+        const json = flags.includes('--json');
+        process.stdout.write(json ? `${JSON.stringify(report)}\n` : formatReport(report));
+        return 0;
+    }
+    catch (error) {
+        process.stderr.write(`vouchington: ${error.message}\n`);
+        return 1;
+    }
+}

package/dist/cli/index.mjs

@@ -20,6 +20,7 @@ import { runLinkSkill } from "./commands/link-skill.mjs";
 import { runRetrospectiveFactsCommand } from "./commands/retrospective-facts.mjs";
 import { runAgentBlackboardCommand } from "./commands/agent-blackboard.mjs";
 import { runMcpCommand } from "./commands/mcp.mjs";
+import { runWorktreeCommand } from "./commands/worktree.mjs";
 import { runWithHostLock } from "./commands/with-host-lock.mjs";
 import { runFreshBase } from "./commands/fresh-base.mjs";
 import { runRequireUpToDate } from "./commands/require-up-to-date.mjs";
@@ -134,6 +135,8 @@ export function runCli(argv = process.argv) {
             return runAgentBlackboardCommand(parsed.args);
         case 'mcp':
             return runMcpCommand(parsed.args);
+        case 'worktree':
+            return runWorktreeCommand(parsed.args);
         case 'require-up-to-date':
             return runRequireUpToDate(parsed);
         case 'fresh-base':

package/dist/cli/parse-forwarded-commands.d.mts

@@ -37,6 +37,9 @@ type ForwardedCommand = {
 } | {
     kind: 'mcp';
     args: string[];
+} | {
+    kind: 'worktree';
+    args: string[];
 };
 export declare function parseForwardedCommand(command: string | undefined, args: string[]): ForwardedCommand | undefined;
 export {};

package/dist/cli/parse-forwarded-commands.mjs

@@ -25,5 +25,7 @@ export function parseForwardedCommand(command, args) {
         return { kind: 'agent-blackboard', args };
     if (command === 'mcp')
         return { kind: 'mcp', args };
+    if (command === 'worktree')
+        return { kind: 'worktree', args };
     return undefined;
 }

package/dist/cli/parse.d.mts

@@ -66,6 +66,9 @@ export type ParsedCli = {
 } | {
     kind: 'mcp';
     args: string[];
+} | {
+    kind: 'worktree';
+    args: string[];
 } | {
     kind: 'require-up-to-date';
     remote: string;

package/dist/cli/usage.d.mts

@@ -1,4 +1,4 @@
-export declare const USAGE = "Usage: vouchington <command> [options]\n\nCommands:\n  runner-port-policy   Print or validate a runner port policy\n  with-host-lock       Run a command under a host-wide lock\n  gha-runtime-audit             Audit successful GitHub Actions job runtimes\n  require-up-to-date            Require HEAD to include a fetched remote branch\n  fresh-base                    Classify the worktree against a remote base branch\n  gitleaks-directory-scan       Scan a directory with Gitleaks\n  ast-grep-examples             Run AST-grep rule examples\n  ast-grep-pack                 Print shipped unconditional AST-grep pack paths as JSON\n  gha-workspace-policy          Check GitHub Actions workspace safety policy\n  gha-output                    Write a collision-safe multiline GITHUB_OUTPUT record\n  gha-needs-results             Fail if required GitHub Actions job results failed\n  download-with-diagnostics     Download a URL and report HTTP status on failure\n  download-optional-run-artifacts  Download optional artifacts from the current run\n  host-pressure-diagnostics     Print a bounded host memory/OOM/PSI snapshot\n  allocate-browser-safe-ports   Allocate Fetch-safe localhost ports\n  diagnose-port-collision       Capture bounded localhost port diagnostics\n  prepare-trivy-db              Download the Trivy vulnerability database\n  gha-artifacts-cleanup         Delete classified GitHub Actions artifacts\n  http-origin                   Validate an optional HTTP(S) origin\n  vitest-blob-manifest          Stamp a vitest-blob-manifest:v1 identity file\n  vitest-report-attempt         Write or read a Vitest report-attempt marker\n  prepare-vitest-reports        Validate and select Vitest report JSON files\n  pnpm-install                  Install a pnpm workspace with retry and release-age fail-fast\n  check-cache-size              Measure a path and decide whether to save a GHA cache\n  make-shard-matrix             Emit a [1..N] GitHub Actions shard matrix\n  load-runner-env               Overlay a runner env file onto GITHUB_ENV with injection guards\n  clean-workspace               Reset a persistent-runner workspace with a fork-PR trust gate\n  install-github-release        Download a checksum-verified GitHub Release binary\n  run-with-timeout              Run a command with GNU timeout or a Perl fallback\n  lint-links                    Two-pass lychee: internal links fail, external warn\n  materialize-pr-context        Dump PR title/body/files/diff/comments and #N crawl\n  wait-for-apt-locks            Wait until apt/dpkg lock files are free\n  install-playwright-chromium-arm64  Install Playwright Chromium from browsers.json\n  ghcr-package-retention        Delete old GHCR package versions (KEEP_MIN or --main-history)\n  harness-admission-lane        Compute a GITHUB_RUN_ID admission lane for fleet fan-out\n  harness-assert-gates          Fail if any named HARNESS_*_ENABLED gate is enabled\n  gha-collaborator-trust        Classify authors as write-access collaborators or not\n  nuget-central-version         Validate a Directory.Packages.props PackageVersion delta\n  swift-semantic-equal          Compare Swift sources ignoring comments and whitespace\n  post-review                   Post one COMMENT review from a staged payload file\n  stage-review-payload          Validate a review payload file into a staging directory\n  retrospective-transcript      Format facts from Claude-compatible, Codex, or Grok transcripts\n  link-skill                    Link one packaged skill into an explicit consumer directory\n  retrospective-facts           Gather immutable facts for a retrospective\n  agent-blackboard              Probe and journal an Agent Blackboard deployment\n  mcp                           Serve the agent-blackboard journal tools over stdio (MCP)\n\nOptions:\n  -h, --help       Show this help\n  -v, --version    Print the package version\n\nrunner-port-policy\n  (no args)              Print the shipped policy as JSON\n  --file <path>          Validate and print a policy file\n  --reserved <port>      Print true if the port is reserved\n\nwith-host-lock\n  --name <family>\n  [--slots <n>]\n  --timeout-seconds <n>\n  [--command-timeout-seconds <n>]\n  [--failure-diagnostics <absolute-script>]\n  [--on-acquire-timeout fail|run-unlocked]\n  -- <command> [args...]\n\ngha-runtime-audit\n  [--repository owner/name]   Default GITHUB_REPOSITORY\n  [--branch main]\n  [--median-threshold-floor <seconds>]    Off unless set. Must be below the ceiling\n  [--median-threshold-ceiling <seconds>]  Default 360. Flags a five-sample median above this\n  --pr-workflow <name|/regex/>     Repeatable\n  --push-workflow <name|/regex/>   Repeatable\n\nrequire-up-to-date --remote <name> --branch <name>\nfresh-base [--remote <name>] [--branch <name>] [--skip-fetch]\ngitleaks-directory-scan --config <path> [--directory <path>]\nast-grep-examples --rules <directory> --config <path>\nast-grep-pack\ngha-workspace-policy [--root <directory>] [--workflow-directory <directory>] [--action-directory <directory>]\n\ngha-output <name>\ngha-needs-results [label]\ndownload-with-diagnostics <url> <destination> [-- curl-args...]\ndownload-optional-run-artifacts (--name <name>... | --pattern <pattern>) --dir <directory>\nhost-pressure-diagnostics\nallocate-browser-safe-ports <count> [--policy path] [--forbidden-ports path]\ndiagnose-port-collision [--ports \"2200 2216\"] [--output-dir PATH]\nprepare-trivy-db\ngha-artifacts-cleanup run --run-id <id> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\ngha-artifacts-cleanup sweep --older-than-hours <n> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\nhttp-origin [--field NAME] [value]\nvitest-blob-manifest <suite> [reports-directory]\nvitest-report-attempt <write DIRECTORY SUITE|read ROOT>\nprepare-vitest-reports [primary-directory] [fallback-directory] [output-directory]\npnpm-install --runner-lifecycle persistent|ephemeral|ephemeral-full --install-scripts true|false\ncheck-cache-size <path> <max-bytes> <label>\nmake-shard-matrix <total>\nload-runner-env\nclean-workspace\ninstall-github-release --repo owner/name --version X --asset 'name-{platform}.tar.gz' --bin name [--tag-prefix PREFIX] [--expected-sha256 SHA256] [--no-checksum] [--checksums-asset NAME] [--version-flag FLAG] [--bin-dir DIR]\nrun-with-timeout <timeout-seconds> <kill-after-seconds> <command...>\nlint-links [--offline] [--config PATH] [--glob PATTERN] [files...]\nmaterialize-pr-context\nwait-for-apt-locks\ninstall-playwright-chromium-arm64 [name:archive...]\nghcr-package-retention [--main-history] [--apply|--dry-run] [<url-encoded-package>...]\nharness-admission-lane <lanes>\nharness-assert-gates <gate>...\ngha-collaborator-trust <owner/repo> [--allow-bot <login>]... < authors.json\nnuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>\nswift-semantic-equal <base> <head> <file.swift>\npost-review\nstage-review-payload optional|required <source> <destination>\nretrospective-transcript [--session-id ID] [--jsonl PATH] [--projects-dir PATH] [--codex-sessions-dir PATH] [--grok-sessions-dir PATH]\nlink-skill <name> --source-root <skills-dir> --target-root <consumer-skills-dir>  Link a packaged or repository-local skill\nretrospective-facts (--pr NUMBER | --branch NAME | --no-pr) [--repo OWNER/NAME] [--raw]\nagent-blackboard probe\nagent-blackboard session-start [--skip-env NAME] [--setup-hint TEXT] [--docs-path PATH] [--restore-hint TEXT] [--timeout-ms N]  (SessionStart hook; payload on stdin)\nagent-blackboard journal append --mode interactive|autonomous --source-event-id ID --work-outcome OUTCOME --coverage-status STATUS --session-id UUID --agent NAME --version VERSION --file PATH --repository OWNER/NAME [--repository OWNER/NAME ...] [--parent-session-id UUID] [--timestamp ISO8601] [--coverage-source SOURCE,...] [--dropped-count N] [--outbox-directory PATH]\nagent-blackboard journal entries --session-id UUID\nagent-blackboard journal status --session-id UUID --outbox-directory PATH\nagent-blackboard journal flush --outbox-directory PATH [--session-id UUID]\nInteractive journal append requires --outbox-directory PATH.\nagent-blackboard journal is deprecated and being phased out: agents journal through the mcp server.\nagent-blackboard snapshot partition --snapshot PATH --checksum SHA256 --counts '{\"sessions\":N,\"entries\":N,\"records\":N,\"bytes\":N}'\nagent-blackboard snapshot cleanup [--snapshot PATH] [--partition-directory PATH --receipt JSON]\nmcp\n  (no args)              Serve journal_append, journal_entries, outbox_status, outbox_flush,\n                         session_ensure, retrospective_check, retrospective_save,\n                         pr_validate, pr_create, pr_update,\n                         snapshot_export, snapshot_cleanup, and session_archive over stdio.\n                         Needs the optional @modelcontextprotocol/sdk peer (and zod).\n                         Launch it from inside the repository's git worktree.\n";
+export declare const USAGE = "Usage: vouchington <command> [options]\n\nCommands:\n  runner-port-policy   Print or validate a runner port policy\n  with-host-lock       Run a command under a host-wide lock\n  gha-runtime-audit             Audit successful GitHub Actions job runtimes\n  require-up-to-date            Require HEAD to include a fetched remote branch\n  fresh-base                    Classify the worktree against a remote base branch\n  gitleaks-directory-scan       Scan a directory with Gitleaks\n  ast-grep-examples             Run AST-grep rule examples\n  ast-grep-pack                 Print shipped unconditional AST-grep pack paths as JSON\n  gha-workspace-policy          Check GitHub Actions workspace safety policy\n  gha-output                    Write a collision-safe multiline GITHUB_OUTPUT record\n  gha-needs-results             Fail if required GitHub Actions job results failed\n  download-with-diagnostics     Download a URL and report HTTP status on failure\n  download-optional-run-artifacts  Download optional artifacts from the current run\n  host-pressure-diagnostics     Print a bounded host memory/OOM/PSI snapshot\n  allocate-browser-safe-ports   Allocate Fetch-safe localhost ports\n  diagnose-port-collision       Capture bounded localhost port diagnostics\n  prepare-trivy-db              Download the Trivy vulnerability database\n  gha-artifacts-cleanup         Delete classified GitHub Actions artifacts\n  http-origin                   Validate an optional HTTP(S) origin\n  vitest-blob-manifest          Stamp a vitest-blob-manifest:v1 identity file\n  vitest-report-attempt         Write or read a Vitest report-attempt marker\n  prepare-vitest-reports        Validate and select Vitest report JSON files\n  pnpm-install                  Install a pnpm workspace with retry and release-age fail-fast\n  check-cache-size              Measure a path and decide whether to save a GHA cache\n  make-shard-matrix             Emit a [1..N] GitHub Actions shard matrix\n  load-runner-env               Overlay a runner env file onto GITHUB_ENV with injection guards\n  clean-workspace               Reset a persistent-runner workspace with a fork-PR trust gate\n  install-github-release        Download a checksum-verified GitHub Release binary\n  run-with-timeout              Run a command with GNU timeout or a Perl fallback\n  lint-links                    Two-pass lychee: internal links fail, external warn\n  materialize-pr-context        Dump PR title/body/files/diff/comments and #N crawl\n  wait-for-apt-locks            Wait until apt/dpkg lock files are free\n  install-playwright-chromium-arm64  Install Playwright Chromium from browsers.json\n  ghcr-package-retention        Delete old GHCR package versions (KEEP_MIN or --main-history)\n  harness-admission-lane        Compute a GITHUB_RUN_ID admission lane for fleet fan-out\n  harness-assert-gates          Fail if any named HARNESS_*_ENABLED gate is enabled\n  gha-collaborator-trust        Classify authors as write-access collaborators or not\n  nuget-central-version         Validate a Directory.Packages.props PackageVersion delta\n  swift-semantic-equal          Compare Swift sources ignoring comments and whitespace\n  post-review                   Post one COMMENT review from a staged payload file\n  stage-review-payload          Validate a review payload file into a staging directory\n  retrospective-transcript      Format facts from Claude-compatible, Codex, or Grok transcripts\n  link-skill                    Link one packaged skill into an explicit consumer directory\n  retrospective-facts           Gather immutable facts for a retrospective\n  agent-blackboard              Probe and journal an Agent Blackboard deployment\n  mcp                           Serve the agent-blackboard journal tools over stdio (MCP)\n  worktree                      Reclaim finished git worktrees (dry run unless --yes)\n\nOptions:\n  -h, --help       Show this help\n  -v, --version    Print the package version\n\nrunner-port-policy\n  (no args)              Print the shipped policy as JSON\n  --file <path>          Validate and print a policy file\n  --reserved <port>      Print true if the port is reserved\n\nwith-host-lock\n  --name <family>\n  [--slots <n>]\n  --timeout-seconds <n>\n  [--command-timeout-seconds <n>]\n  [--failure-diagnostics <absolute-script>]\n  [--on-acquire-timeout fail|run-unlocked]\n  -- <command> [args...]\n\ngha-runtime-audit\n  [--repository owner/name]   Default GITHUB_REPOSITORY\n  [--branch main]\n  [--median-threshold-floor <seconds>]    Off unless set. Must be below the ceiling\n  [--median-threshold-ceiling <seconds>]  Default 360. Flags a five-sample median above this\n  --pr-workflow <name|/regex/>     Repeatable\n  --push-workflow <name|/regex/>   Repeatable\n\nrequire-up-to-date --remote <name> --branch <name>\nfresh-base [--remote <name>] [--branch <name>] [--skip-fetch]\ngitleaks-directory-scan --config <path> [--directory <path>]\nast-grep-examples --rules <directory> --config <path>\nast-grep-pack\ngha-workspace-policy [--root <directory>] [--workflow-directory <directory>] [--action-directory <directory>]\n\ngha-output <name>\ngha-needs-results [label]\ndownload-with-diagnostics <url> <destination> [-- curl-args...]\ndownload-optional-run-artifacts (--name <name>... | --pattern <pattern>) --dir <directory>\nhost-pressure-diagnostics\nallocate-browser-safe-ports <count> [--policy path] [--forbidden-ports path]\ndiagnose-port-collision [--ports \"2200 2216\"] [--output-dir PATH]\nprepare-trivy-db\ngha-artifacts-cleanup run --run-id <id> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\ngha-artifacts-cleanup sweep --older-than-hours <n> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\nhttp-origin [--field NAME] [value]\nvitest-blob-manifest <suite> [reports-directory]\nvitest-report-attempt <write DIRECTORY SUITE|read ROOT>\nprepare-vitest-reports [primary-directory] [fallback-directory] [output-directory]\npnpm-install --runner-lifecycle persistent|ephemeral|ephemeral-full --install-scripts true|false\ncheck-cache-size <path> <max-bytes> <label>\nmake-shard-matrix <total>\nload-runner-env\nclean-workspace\ninstall-github-release --repo owner/name --version X --asset 'name-{platform}.tar.gz' --bin name [--tag-prefix PREFIX] [--expected-sha256 SHA256] [--no-checksum] [--checksums-asset NAME] [--version-flag FLAG] [--bin-dir DIR]\nrun-with-timeout <timeout-seconds> <kill-after-seconds> <command...>\nlint-links [--offline] [--config PATH] [--glob PATTERN] [files...]\nmaterialize-pr-context\nwait-for-apt-locks\ninstall-playwright-chromium-arm64 [name:archive...]\nghcr-package-retention [--main-history] [--apply|--dry-run] [<url-encoded-package>...]\nharness-admission-lane <lanes>\nharness-assert-gates <gate>...\ngha-collaborator-trust <owner/repo> [--allow-bot <login>]... < authors.json\nnuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>\nswift-semantic-equal <base> <head> <file.swift>\npost-review\nstage-review-payload optional|required <source> <destination>\nretrospective-transcript [--session-id ID] [--jsonl PATH] [--projects-dir PATH] [--codex-sessions-dir PATH] [--grok-sessions-dir PATH]\nlink-skill <name> --source-root <skills-dir> --target-root <consumer-skills-dir>  Link a packaged or repository-local skill\nretrospective-facts (--pr NUMBER | --branch NAME | --no-pr) [--repo OWNER/NAME] [--raw]\nagent-blackboard probe\nagent-blackboard session-start [--skip-env NAME] [--setup-hint TEXT] [--docs-path PATH] [--restore-hint TEXT] [--timeout-ms N]  (SessionStart hook; payload on stdin)\nagent-blackboard journal append --mode interactive|autonomous --source-event-id ID --work-outcome OUTCOME --coverage-status STATUS --session-id UUID --agent NAME --version VERSION --file PATH --repository OWNER/NAME [--repository OWNER/NAME ...] [--parent-session-id UUID] [--timestamp ISO8601] [--coverage-source SOURCE,...] [--dropped-count N] [--outbox-directory PATH]\nagent-blackboard journal entries --session-id UUID\nagent-blackboard journal status --session-id UUID --outbox-directory PATH\nagent-blackboard journal flush --outbox-directory PATH [--session-id UUID]\nInteractive journal append requires --outbox-directory PATH.\nagent-blackboard journal is deprecated and being phased out: agents journal through the mcp server.\nagent-blackboard snapshot partition --snapshot PATH --checksum SHA256 --counts '{\"sessions\":N,\"entries\":N,\"records\":N,\"bytes\":N}'\nagent-blackboard snapshot cleanup [--snapshot PATH] [--partition-directory PATH --receipt JSON]\nmcp\n  (no args)              Serve journal_append, journal_entries, outbox_status, outbox_flush,\n                         session_ensure, retrospective_check, retrospective_save,\n                         pr_validate, pr_create, pr_update,\n                         snapshot_export, snapshot_cleanup, and session_archive over stdio.\n                         Needs the optional @modelcontextprotocol/sdk peer (and zod).\n                         Launch it from inside the repository's git worktree.\n\nworktree reclaim [--yes] [--json]\n  Dry run by default. Removes clean, fully pushed worktrees whose same-repository PR for the\n  branch is merged or closed at exactly HEAD, using git worktree remove (never forced).\n  Skips the main checkout, the current worktree, and locked, bare or detached worktrees.\n";
 export declare function printUsage(stream?: NodeJS.WritableStream): void;
 export declare function commandNames(usage?: string): string[];
 export declare function commandUsage(command: string, usage?: string): string;

package/dist/cli/usage.mjs

@@ -47,6 +47,7 @@ Commands:
   retrospective-facts           Gather immutable facts for a retrospective
   agent-blackboard              Probe and journal an Agent Blackboard deployment
   mcp                           Serve the agent-blackboard journal tools over stdio (MCP)
+  worktree                      Reclaim finished git worktrees (dry run unless --yes)
 
 Options:
   -h, --help       Show this help
@@ -134,6 +135,11 @@ mcp
                          snapshot_export, snapshot_cleanup, and session_archive over stdio.
                          Needs the optional @modelcontextprotocol/sdk peer (and zod).
                          Launch it from inside the repository's git worktree.
+
+worktree reclaim [--yes] [--json]
+  Dry run by default. Removes clean, fully pushed worktrees whose same-repository PR for the
+  branch is merged or closed at exactly HEAD, using git worktree remove (never forced).
+  Skips the main checkout, the current worktree, and locked, bare or detached worktrees.
 `;
 export function printUsage(stream = process.stdout) {
     stream.write(USAGE);

package/dist/git-worktrees/assess.d.mts

@@ -0,0 +1,14 @@
+import { type RunOptions } from './run.mts';
+export type Assessment = {
+    readonly head: string;
+} | {
+    readonly reason: string;
+};
+export declare function readRepository(main: RunOptions): string | undefined;
+/** Clean status and no hidden index entries. Returns the HEAD commit or a reason. */
+export declare function assessLocal(worktree: RunOptions): Assessment;
+/**
+ * Needs a merged or closed same-repository PR for this branch whose head is exactly HEAD. That
+ * also proves HEAD is published on GitHub, so deleted branches (squash merges) need no remote ref.
+ */
+export declare function assessPullRequest(branch: string, head: string, repository: string | undefined, main: RunOptions): string | undefined;

package/dist/git-worktrees/assess.mjs

@@ -0,0 +1,68 @@
+import { git, LOCAL_ENV, run, withoutVariables } from "./run.mjs";
+const FINISHED = new Set(['MERGED', 'CLOSED']);
+function parseJson(text) {
+    try {
+        return text === undefined ? undefined : JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Repo-local git variables, GH_REPO and GH_HOST must not redirect the lookup away from the main checkout. */
+function runGh(args, main) {
+    const env = withoutVariables(main.env, [...LOCAL_ENV, 'GH_REPO', 'GH_HOST']);
+    return run('gh', args, { cwd: main.cwd, env });
+}
+export function readRepository(main) {
+    const repo = parseJson(runGh(['repo', 'view', '--json', 'nameWithOwner'], main));
+    return repo?.nameWithOwner?.toLowerCase();
+}
+/** Clean status and no hidden index entries. Returns the HEAD commit or a reason. */
+export function assessLocal(worktree) {
+    const status = git(['status', '--porcelain', '--untracked-files=all', '--ignore-submodules=none'], worktree);
+    if (status === undefined)
+        return { reason: 'cannot read status' };
+    if (status !== '')
+        return { reason: 'uncommitted changes' };
+    const files = git(['ls-files', '-v', '-z'], worktree);
+    if (files === undefined)
+        return { reason: 'cannot read index' };
+    if (files.split('\0').some((entry) => /^[a-zS]/.test(entry))) {
+        return { reason: 'hidden index entries (assume-unchanged or skip-worktree)' };
+    }
+    const headOutput = git(['rev-parse', 'HEAD'], worktree);
+    if (headOutput === undefined)
+        return { reason: 'cannot read HEAD' };
+    const head = headOutput.trim();
+    return { head };
+}
+const PAGE = 1000;
+function listPulls(branch, state, main) {
+    const fields = 'state,headRefOid,isCrossRepository,headRepository,headRepositoryOwner';
+    const args = ['pr', 'list', '--head', branch, '--state', state, '--limit', String(PAGE)];
+    const listed = parseJson(runGh([...args, '--json', fields], main));
+    return Array.isArray(listed) && listed.length < PAGE ? listed : undefined;
+}
+/**
+ * Needs a merged or closed same-repository PR for this branch whose head is exactly HEAD. That
+ * also proves HEAD is published on GitHub, so deleted branches (squash merges) need no remote ref.
+ */
+export function assessPullRequest(branch, head, repository, main) {
+    if (repository === undefined)
+        return 'cannot read repository';
+    // Open PRs are queried on their own so a long history cannot hide one; a full page is unreadable.
+    const open = listPulls(branch, 'open', main);
+    const all = listPulls(branch, 'all', main);
+    if (open === undefined || all === undefined)
+        return 'cannot read PR state';
+    const own = [...open, ...all].filter((pr) => pr.isCrossRepository === false &&
+        `${pr.headRepositoryOwner?.login}/${pr.headRepository?.name}`.toLowerCase() === repository);
+    if (own.some((pr) => pr.state === 'OPEN'))
+        return 'open PR';
+    const finished = own.filter((pr) => FINISHED.has(pr.state));
+    if (finished.length === 0)
+        return 'no finished PR from this repository';
+    if (!finished.some((pr) => pr.headRefOid === head))
+        return 'PR head differs from HEAD';
+    return undefined;
+}

package/dist/git-worktrees/list.d.mts

@@ -0,0 +1,10 @@
+export interface WorktreeRecord {
+    readonly path: string;
+    readonly branch?: string;
+    readonly head?: string;
+    readonly locked: boolean;
+    readonly bare: boolean;
+    readonly detached: boolean;
+}
+/** Parses `git worktree list --porcelain -z` (NUL fields, an empty field ends each record). */
+export declare function parseWorktreeList(porcelain: string | undefined): WorktreeRecord[];

package/dist/git-worktrees/list.mjs

@@ -0,0 +1,34 @@
+const BRANCH_PREFIX = 'branch refs/heads/';
+function parseRecord(fields) {
+    const path = fields.find((field) => field.startsWith('worktree '))?.slice('worktree '.length);
+    if (path === undefined)
+        return undefined;
+    const branch = fields
+        .find((field) => field.startsWith(BRANCH_PREFIX))
+        ?.slice(BRANCH_PREFIX.length);
+    const head = fields.find((field) => field.startsWith('HEAD '))?.slice('HEAD '.length);
+    return {
+        path,
+        locked: fields.some((field) => field === 'locked' || field.startsWith('locked ')),
+        bare: fields.includes('bare'),
+        detached: fields.includes('detached'),
+        ...(branch === undefined ? {} : { branch }),
+        ...(head === undefined ? {} : { head }),
+    };
+}
+/** Parses `git worktree list --porcelain -z` (NUL fields, an empty field ends each record). */
+export function parseWorktreeList(porcelain) {
+    const records = [];
+    let fields = [];
+    for (const field of [...(porcelain ?? '').split('\0'), '']) {
+        if (field !== '') {
+            fields.push(field);
+            continue;
+        }
+        const record = parseRecord(fields);
+        if (record !== undefined)
+            records.push(record);
+        fields = [];
+    }
+    return records;
+}

package/dist/git-worktrees/reclaim.d.mts

@@ -0,0 +1,15 @@
+import { type RunOptions } from './run.mts';
+interface ReclaimEntry {
+    readonly path: string;
+    readonly branch: string;
+    readonly status: 'reclaimed' | 'would reclaim' | 'kept';
+    readonly reason?: string;
+}
+export interface ReclaimReport {
+    readonly dryRun: boolean;
+    readonly worktrees: ReclaimEntry[];
+}
+/** Lists finished worktrees and, with `yes`, removes them with a plain (never forced) `git worktree remove`. */
+export declare function reclaimWorktrees(yes: boolean, runtime: RunOptions): ReclaimReport;
+export declare function formatReport(report: ReclaimReport): string;
+export {};

package/dist/git-worktrees/reclaim.mjs

@@ -0,0 +1,80 @@
+import { existsSync, realpathSync } from 'node:fs';
+import { sep } from 'node:path';
+import { assessLocal, assessPullRequest, readRepository } from "./assess.mjs";
+import { parseWorktreeList } from "./list.mjs";
+import { git } from "./run.mjs";
+/** Assesses (and with `yes` removes) one worktree; undefined means it is not a candidate. */
+function reclaimOne(record, context) {
+    const { path, branch, locked, bare, detached } = record;
+    if (locked || bare || detached || branch === undefined)
+        return undefined;
+    if (!existsSync(path) || realpathSync(path) === context.selfReal)
+        return undefined;
+    const keep = (reason) => ({ path, branch, status: 'kept', reason });
+    const nests = (paths) => paths.some((other) => other.startsWith(path + sep));
+    if (nests(context.registered)) {
+        return keep('contains another worktree');
+    }
+    const worktree = { cwd: path, env: context.runtime.env };
+    const local = assessLocal(worktree);
+    if ('reason' in local)
+        return keep(local.reason);
+    const reason = assessPullRequest(branch, local.head, context.repository, context.mainRun);
+    if (reason !== undefined)
+        return keep(reason);
+    if (!context.yes)
+        return { path, branch, status: 'would reclaim' };
+    const again = assessLocal(worktree);
+    const pullAgain = assessPullRequest(branch, local.head, context.repository, context.mainRun);
+    const listed = parseWorktreeList(git(['worktree', 'list', '--porcelain', '-z'], context.runtime));
+    const same = listed.some((entry) => entry.path === path && entry.branch === branch && entry.head === local.head);
+    if (nests(listed.map((entry) => entry.path)))
+        return keep('contains another worktree');
+    if ('reason' in again || again.head !== local.head || pullAgain !== undefined || !same)
+        return keep('changed since check');
+    if (git(['worktree', 'remove', path], { ...context.mainRun, timeout: 0 }) === undefined) {
+        return keep('git worktree remove refused');
+    }
+    return { path, branch, status: 'reclaimed' };
+}
+/** Lists finished worktrees and, with `yes`, removes them with a plain (never forced) `git worktree remove`. */
+export function reclaimWorktrees(yes, runtime) {
+    const listing = git(['worktree', 'list', '--porcelain', '-z'], runtime);
+    const self = git(['rev-parse', '--show-toplevel'], runtime)?.replace(/\n$/, '');
+    const [main, ...others] = parseWorktreeList(listing);
+    if (main === undefined || !self)
+        throw new Error('not inside a git worktree');
+    const mainRun = { cwd: main.path, env: runtime.env };
+    const context = {
+        yes,
+        runtime,
+        mainRun,
+        selfReal: realpathSync(self),
+        registered: [main, ...others].map((record) => record.path),
+        repository: readRepository(mainRun),
+    };
+    const worktrees = [];
+    for (const record of others) {
+        try {
+            const entry = reclaimOne(record, context);
+            if (entry !== undefined)
+                worktrees.push(entry);
+        }
+        catch (error) {
+            const reason = `error: ${error.message}`;
+            worktrees.push({ path: record.path, branch: record.branch, status: 'kept', reason });
+        }
+    }
+    return { dryRun: !yes, worktrees };
+}
+function escape(text) {
+    return text.replace(/\p{Cc}/gu, (char) => `\\x${char.charCodeAt(0).toString(16).padStart(2, '0')}`);
+}
+export function formatReport(report) {
+    return report.worktrees
+        .map((entry) => {
+        const status = entry.status === 'kept' ? `kept: ${entry.reason}` : entry.status;
+        return `${escape(entry.path)}: ${escape(status)}\n`;
+    })
+        .join('');
+}

package/dist/git-worktrees/reclaim.test-helpers.d.mts

@@ -0,0 +1,16 @@
+export interface Fixture {
+    readonly root: string;
+    readonly main: string;
+    readonly caller: string;
+    readonly env: NodeJS.ProcessEnv;
+    git(cwd: string, ...args: string[]): string;
+    /** Adds a worktree on a new branch with one commit; optionally pushes it to origin. */
+    addWorktree(name: string, options?: {
+        push?: boolean;
+        dir?: string;
+    }): string;
+    /** Writes the fake `gh pr list` answer; a PR with no head defaults to the branch tip. */
+    setPrs(branch: string, prs: object[]): void;
+    cleanup(): void;
+}
+export declare function createFixture(): Fixture;

package/dist/git-worktrees/reclaim.test-helpers.mjs

@@ -0,0 +1,113 @@
+import { execFileSync } from 'node:child_process';
+import { chmodSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+// Answers `gh repo view` and `gh pr list --head <branch>` from files, like the real CLI.
+const FAKE_GH = `#!${process.execPath}
+const fs = require('node:fs')
+const args = process.argv.slice(2)
+const env = process.env
+if (env.FAKE_GH_FAIL) process.exit(1)
+if (env.FAKE_GH_NO_GIT_DIR && env.GIT_DIR) process.exit(1)
+if (args[0] === 'repo') {
+  console.log(JSON.stringify({ nameWithOwner: env.GH_REPO || 'Acme/Widgets' }))
+  process.exit(0)
+}
+if (env.FAKE_GH_GARBAGE) {
+  console.log('not json')
+  process.exit(0)
+}
+const state = args[args.indexOf('--state') + 1]
+// Simulates a change that lands between the first assessment and the re-check.
+if (state === 'all') {
+  const { execFileSync } = require('node:child_process')
+  const run = (cwd, ...a) => execFileSync('git', a, { cwd, stdio: 'ignore' })
+  if (env.FAKE_GH_NEST && !fs.existsSync(env.FAKE_GH_DIR + '/nested')) {
+    fs.writeFileSync(env.FAKE_GH_DIR + '/nested', '')
+    run(env.FAKE_GH_NEST, 'worktree', 'add', '-b', 'kid', 'sub/kid')
+  }
+  if (env.FAKE_GH_TOUCH) fs.writeFileSync(env.FAKE_GH_TOUCH, 'x')
+  if (env.FAKE_GH_SWITCH) run(env.FAKE_GH_SWITCH, 'checkout', '-b', 'switched')
+  if (env.FAKE_GH_ADVANCE) {
+    run(env.FAKE_GH_ADVANCE, 'commit', '--allow-empty', '-m', 'late')
+    run(env.FAKE_GH_ADVANCE, 'push', 'origin', 'HEAD')
+  }
+}
+const branch = args[args.indexOf('--head') + 1]
+const file = env.FAKE_GH_DIR + '/' + branch.replaceAll('/', '_') + '.json'
+let pulls = fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, 'utf8')) : []
+if (state === 'open') pulls = pulls.filter((pr) => pr.state === 'OPEN')
+const pad = Number(env['FAKE_GH_PAD_' + state.toUpperCase()] || 0)
+for (let i = 0; i < pad; i += 1) pulls.push({ state: 'CLOSED' })
+console.log(JSON.stringify(pulls))
+// Reopen every PR after the first full answer, as if it changed before the re-check.
+if (state === 'all' && env.FAKE_GH_REOPEN && !fs.existsSync(file + '.reopened')) {
+  fs.writeFileSync(file, JSON.stringify(pulls.map((pr) => ({ ...pr, state: 'OPEN' }))))
+  fs.writeFileSync(file + '.reopened', '')
+}
+`;
+const realGit = execFileSync('which', ['git'], { encoding: 'utf8' }).trim();
+export function createFixture() {
+    const root = realpathSync(mkdtempSync(join(tmpdir(), 'worktree-reclaim-')));
+    const bin = join(root, 'bin');
+    const ghDir = join(root, 'gh');
+    mkdirSync(bin);
+    mkdirSync(ghDir);
+    writeFileSync(join(bin, 'gh'), FAKE_GH);
+    chmodSync(join(bin, 'gh'), 0o755);
+    // A git wrapper that fails any invocation containing the words in FAKE_GIT_FAIL, to reach error paths.
+    writeFileSync(join(bin, 'git'), `#!/bin/sh\ncase " $* " in *" $FAKE_GIT_FAIL "*) [ -n "$FAKE_GIT_FAIL" ] && exit 1;; esac\nexec '${realGit}' "$@"\n`);
+    chmodSync(join(bin, 'git'), 0o755);
+    const env = {
+        ...process.env,
+        PATH: `${bin}:${process.env.PATH ?? ''}`,
+        FAKE_GH_DIR: ghDir,
+        GIT_CONFIG_GLOBAL: '/dev/null',
+        GIT_CONFIG_SYSTEM: '/dev/null',
+        GIT_AUTHOR_NAME: 'Test',
+        GIT_AUTHOR_EMAIL: 'test@example.com',
+        GIT_COMMITTER_NAME: 'Test',
+        GIT_COMMITTER_EMAIL: 'test@example.com',
+    };
+    const git = (cwd, ...args) => execFileSync('git', args, { cwd, env, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+    const origin = join(root, 'origin.git');
+    const main = join(root, 'main');
+    git(root, 'init', '--bare', '-b', 'main', origin);
+    git(root, 'init', '-b', 'main', main);
+    writeFileSync(join(main, 'README.md'), 'base\n');
+    git(main, 'add', '.');
+    git(main, 'commit', '-m', 'base');
+    git(main, 'remote', 'add', 'origin', origin);
+    git(main, 'push', '-u', 'origin', 'main');
+    const caller = join(root, 'worktrees', 'caller');
+    git(main, 'worktree', 'add', '-b', 'caller', caller);
+    return {
+        root,
+        main,
+        caller,
+        env,
+        git,
+        addWorktree: (name, options = {}) => {
+            const path = join(root, 'worktrees', options.dir ?? name);
+            git(main, 'worktree', 'add', '-b', name, path);
+            writeFileSync(join(path, `${name}.txt`), `${name}\n`);
+            git(path, 'add', '.');
+            git(path, 'commit', '-m', name);
+            if (options.push)
+                git(path, 'push', '-u', 'origin', name);
+            return path;
+        },
+        setPrs: (branch, prs) => {
+            const tip = git(main, 'rev-parse', `refs/heads/${branch}`).trim();
+            const filled = prs.map((pr) => ({
+                headRefOid: tip,
+                isCrossRepository: false,
+                headRepository: { name: 'Widgets' },
+                headRepositoryOwner: { login: 'acme' },
+                ...pr,
+            }));
+            writeFileSync(join(ghDir, `${branch.replaceAll('/', '_')}.json`), JSON.stringify(filled));
+        },
+        cleanup: () => rmSync(root, { force: true, recursive: true }),
+    };
+}

package/dist/git-worktrees/run.d.mts

@@ -0,0 +1,13 @@
+export interface RunOptions {
+    readonly cwd: string;
+    readonly env: NodeJS.ProcessEnv;
+    /** Milliseconds before a read-only call is killed; 0 for none (worktree removal). */
+    readonly timeout?: number;
+}
+/** Runs a command without a shell; returns stdout, or undefined when it fails to start or exits non-zero. */
+export declare function run(file: string, args: readonly string[], options: RunOptions): string | undefined;
+export declare const LOCAL_ENV: string[];
+/** A copy of `env` without the named variables. */
+export declare function withoutVariables(env: NodeJS.ProcessEnv, names: readonly string[]): NodeJS.ProcessEnv;
+/** git with fsmonitor disabled so a repository config can never execute a hook. */
+export declare function git(args: readonly string[], options: RunOptions): string | undefined;

package/dist/git-worktrees/run.mjs

@@ -0,0 +1,50 @@
+import { execFileSync } from 'node:child_process';
+/** Runs a command without a shell; returns stdout, or undefined when it fails to start or exits non-zero. */
+export function run(file, args, options) {
+    try {
+        return execFileSync(file, args, {
+            cwd: options.cwd,
+            env: options.env,
+            encoding: 'utf8',
+            maxBuffer: 64 * 1024 * 1024,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: options.timeout ?? 120_000,
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
+// Repo-local overrides (see `git rev-parse --local-env-vars`): the cwd must pick the repository.
+export const LOCAL_ENV = [
+    'GIT_DIR',
+    'GIT_WORK_TREE',
+    'GIT_INDEX_FILE',
+    'GIT_OBJECT_DIRECTORY',
+    'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+    'GIT_COMMON_DIR',
+    'GIT_PREFIX',
+    'GIT_NAMESPACE',
+    'GIT_CONFIG',
+    'GIT_CONFIG_PARAMETERS',
+    'GIT_CONFIG_COUNT',
+    'GIT_GRAFT_FILE',
+    'GIT_IMPLICIT_WORK_TREE',
+    'GIT_INTERNAL_SUPER_PREFIX',
+    'GIT_SHALLOW_FILE',
+    'GIT_REPLACE_REF_BASE',
+    'GIT_NO_REPLACE_OBJECTS',
+    'GIT_QUARANTINE_PATH',
+];
+/** A copy of `env` without the named variables. */
+export function withoutVariables(env, names) {
+    const copy = { ...env };
+    for (const name of names)
+        delete copy[name];
+    return copy;
+}
+/** git with fsmonitor disabled so a repository config can never execute a hook. */
+export function git(args, options) {
+    const env = withoutVariables(options.env, LOCAL_ENV);
+    return run('git', ['-c', 'core.fsmonitor=false', ...args], { ...options, env });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.52.1",
+  "version": "0.53.0",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {