@webpieces/pr-gate 0.4.688 → 0.4.689

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/pr-gate",
-  "version": "0.4.688",
+  "version": "0.4.689",
   "description": "Gated PR system: 3-point squash-merge, merge validation gate, and red/yellow/green PR dashboard. Standalone scripts, no Nx dependency required.",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -15,7 +15,7 @@
     "directory": "packages/tooling/pr-gate"
   },
   "dependencies": {
-    "@webpieces/rules-config": "0.4.688",
+    "@webpieces/rules-config": "0.4.689",
     "@inversifyjs/binding-decorators": "1.1.5",
     "inversify": "7.10.4",
     "reflect-metadata": "0.2.2"

package/src/scripts/commands/checkout-clean-main-command.js

@@ -5,6 +5,7 @@ const tslib_1 = require("tslib");
 const inversify_1 = require("inversify");
 const rules_config_1 = require("@webpieces/rules-config");
 const cleanup_command_1 = require("./cleanup-command");
+const cleanup_options_1 = require("./cleanup-options");
 const main_checkout_1 = require("./main-checkout");
 const working_tree_gate_1 = require("./working-tree-gate");
 const SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n';
@@ -71,7 +72,11 @@ let CheckoutCleanMainCommand = class CheckoutCleanMainCommand {
         const untracked = this.workingTreeGate.assertNoTrackedChanges(repoRoot);
         const stashed = this.mainCheckout.goToMain(repoRoot, untracked);
         this.reportUntracked(untracked, stashed);
-        await this.cleanupCommand.run();
+        // No flags: this is the "go to main and take out the trash" path, so cleanup behaves exactly as a
+        // bare `pnpm wp-cleanup` does here — reap what is provably dead and every zero-commit husk, ask
+        // (or report) about the rest. Spelled out rather than defaulted so that if CleanupOptions ever
+        // grows a field, this call site is a compile error instead of a silent old behaviour.
+        await this.cleanupCommand.run(new cleanup_options_1.CleanupOptions(new cleanup_options_1.DeleteSelection(cleanup_options_1.FLAG_DELETE_BRANCHES, false, ''), new cleanup_options_1.DeleteSelection(cleanup_options_1.FLAG_DELETE_WORKTREES, false, ''), false, false));
         this.sweep(repoRoot);
         this.reportStashed(stashed);
     }

package/src/scripts/commands/checkout-clean-main-command.js.map

@@ -1 +1 @@
-{"version":3,"file":"checkout-clean-main-command.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/commands/checkout-clean-main-command.ts"],"names":[],"mappings":"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","sourcesContent":["import { injectable, bindingScopeValues } from 'inversify';\nimport {\n    OrphanDirSweeper,\n    RepoRootFinder,\n    dotWebpieces,\n} from '@webpieces/rules-config';\n\nimport { CleanupCommand } from './cleanup-command';\nimport { MainCheckout, StashedFiles } from './main-checkout';\nimport { WorkingTreeGate, UntrackedFiles } from './working-tree-gate';\n\nconst SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\n';\n\n/**\n * `wp-checkout-clean-main` — go to main, get main, and take out the trash. ONE command, because the three\n * are one intention and splitting them is what let the third never happen.\n *\n * ─── ITS RELATIONSHIP TO `git checkout main && git pull origin main` (READ BEFORE \"DELETING\" THAT) ────\n * That pair was already the enforced spelling: bare `git checkout main` is blocked precisely so the pull\n * rides along. This command is the same pairing with cleanup and the sweep welded on, and the WORKFLOW\n * messages now prescribe this instead — two spellings where one sweeps and one does not is shim shape\n * #1, an agent types whichever is accepted and the corpses accumulate forever.\n *\n * The raw pair is NOT deleted, and the reason is a constraint that outranks the shim rule: it is a\n * TERMINAL ENTRY ON THE L0 ALLOWLIST (`CHECKOUT_MAIN_PULL_CMD` in ai-hook-rules\n * `src/bin/l0-allowlist.ts`, consumed as an L0 cure in `src/core/l0-matrix.ts`) — one of\n * the few commands still permitted while an L0 block denies every other tool call. In exactly that\n * state, `node_modules` is the thing that is untrustworthy, so a `pnpm wp-*` bin is the one kind of cure\n * that cannot be relied on to run. The same reasoning covers the L0 shim's own fix option in\n * `templates/ai-hook.sh` (rendered from `src/bin/shim-drift-fix.ts`).\n *\n * So the end state is TWO LAYERS, not a deletion, and it is now in place:\n *   • L0 recovery (l0-allowlist, shim-drift-fix, l0-matrix) → keeps the raw pair. It is not a shim\n *     there; it is the only thing that works when the package manager's output is what is in doubt.\n *   • the WORKFLOW layer (stale-main-bash-guard's preferred cure, merged-branch-message/-bash-guard,\n *     TreeRecovery's cleanupSteps and updateMainSteps, the L2 rows/doc, CLAUDE.md's \"Finishing a\n *     Feature\") → prescribes `pnpm wp-checkout-clean-main`, and no longer prints the pair.\n *\n * The pair remains ALLOWED as a Bash command in both layers — this changed what the guards TEACH, not\n * what they permit. Blocking it would have deleted the L0 escape along with the shim.\n *\n * ─── WHY GOING TO MAIN IS THE RIGHT MOMENT TO SWEEP ───────────────────────────────────────────────────\n * The corpses appear when git moves the working tree onto a base where the tracked files under some\n * directory are gone. Landing a PR and returning to main is when every developer does that, on every\n * clone, roughly once per merged PR — so a sweep bolted here converges the whole team's machines with no\n * new trigger, no git hook to distribute, and no background daemon. It is also the quietest moment in the\n * day to move directories: nothing is building, no dev server is watching files.\n *\n * ─── WHY THE ORDER IS FIXED AND NOT PARALLEL ──────────────────────────────────────────────────────────\n * Cleanup runs BEFORE the sweep and not beside it. `wp-cleanup` removes dead worktrees, which changes\n * what is on disk, and a scan racing that would be reading a tree mid-demolition. The scan is one\n * ignore-walk and costs about a second; there is no wall-clock worth buying with that race.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class CheckoutCleanMainCommand {\n    constructor(\n        private readonly repoRootFinder: RepoRootFinder,\n        private readonly cleanupCommand: CleanupCommand,\n        private readonly orphanDirSweeper: OrphanDirSweeper,\n        private readonly workingTreeGate: WorkingTreeGate,\n        private readonly mainCheckout: MainCheckout,\n    ) {}\n\n    async run(): Promise<void> {\n        const repoRoot = this.repoRootFinder.resolveRepoRoot(process.cwd());\n        process.stdout.write(`${SEP}🧹 Checkout main, pull, clean\\n${SEP}\\n`);\n        if (this.isLinkedWorktree(repoRoot)) {\n            await this.sweepOnly(repoRoot);\n            return;\n        }\n        const untracked = this.workingTreeGate.assertNoTrackedChanges(repoRoot);\n        const stashed = this.mainCheckout.goToMain(repoRoot, untracked);\n        this.reportUntracked(untracked, stashed);\n        await this.cleanupCommand.run();\n        this.sweep(repoRoot);\n        this.reportStashed(stashed);\n    }\n\n    /**\n     * A linked worktree has no main to check out — `git checkout main` FATALS there with \"main is already\n     * checked out at <primary clone>\", which is a footgun CLAUDE.md currently has to warn about in prose.\n     * So the command does the half that IS meaningful here (worktrees accumulate corpses too, if a\n     * long-lived one keeps merging main in) and says plainly where the other half lives.\n     */\n    private async sweepOnly(repoRoot: string): Promise<void> {\n        process.stdout.write(\n            'This is a linked WORKTREE. main is checked out in the primary clone, so there is nothing\\n'\n            + 'here to check out or pull — sweeping this tree only.\\n\\n'\n            + 'Most worktrees never need this: `wp-cleanup` removes the whole directory once its branch\\n'\n            + 'lands, which takes any orphan directories inside it along. Run this command again from the\\n'\n            + 'primary clone to go to main there.\\n\\n');\n        this.sweep(repoRoot);\n        return Promise.resolve();\n    }\n\n    private isLinkedWorktree(repoRoot: string): boolean {\n        const dirs = dotWebpieces.gitDirs(repoRoot);\n        return dirs !== null && dirs.isLinkedWorktree;\n    }\n\n    /**\n     * Say which untracked files were let through, AFTER the move — so nobody has to wonder whether the\n     * files still sitting in their tree came along for the ride. Printed rather than refused on: see\n     * `WorkingTreeGate` for why an untracked file is not the hazard a tracked one is.\n     *\n     * Silent when the checkout had to stash: those files are NOT sitting in the tree any more, and\n     * \"nothing about them changed\" would be a lie. `reportStashed` speaks for that case instead.\n     */\n    private reportUntracked(untracked: UntrackedFiles, stashed: StashedFiles): void {\n        if (!stashed.isEmpty()) return;\n        const rendered = untracked.render();\n        if (rendered === '') return;\n        process.stdout.write(`\\n${rendered}`);\n    }\n\n    /**\n     * The stash banner goes LAST, on purpose. It is the one thing in this command's output a reader\n     * must not miss — their files left the working tree — and the cleanup and sweep that follow the\n     * checkout print enough to scroll it away if it were emitted where it happened.\n     */\n    private reportStashed(stashed: StashedFiles): void {\n        const rendered = stashed.render();\n        if (rendered === '') return;\n        process.stdout.write(`\\n${rendered}`);\n    }\n\n    /**\n     * Sweep, then print. Never throws: the checkout and pull above already succeeded, and a tidier is not\n     * permitted to turn somebody's completed sync into a failed command.\n     */\n    private sweep(repoRoot: string): void {\n        const report = this.orphanDirSweeper.sweep(repoRoot, new Date());\n        const rendered = report.render();\n        if (rendered === '') return;\n        process.stdout.write(`\\n${rendered}`);\n    }\n}\n"]}
+{"version":3,"file":"checkout-clean-main-command.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/commands/checkout-clean-main-command.ts"],"names":[],"mappings":"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","sourcesContent":["import { injectable, bindingScopeValues } from 'inversify';\nimport {\n    OrphanDirSweeper,\n    RepoRootFinder,\n    dotWebpieces,\n} from '@webpieces/rules-config';\n\nimport { CleanupCommand } from './cleanup-command';\nimport {\n    CleanupOptions,\n    DeleteSelection,\n    FLAG_DELETE_BRANCHES,\n    FLAG_DELETE_WORKTREES,\n} from './cleanup-options';\nimport { MainCheckout, StashedFiles } from './main-checkout';\nimport { WorkingTreeGate, UntrackedFiles } from './working-tree-gate';\n\nconst SEP = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\\n';\n\n/**\n * `wp-checkout-clean-main` — go to main, get main, and take out the trash. ONE command, because the three\n * are one intention and splitting them is what let the third never happen.\n *\n * ─── ITS RELATIONSHIP TO `git checkout main && git pull origin main` (READ BEFORE \"DELETING\" THAT) ────\n * That pair was already the enforced spelling: bare `git checkout main` is blocked precisely so the pull\n * rides along. This command is the same pairing with cleanup and the sweep welded on, and the WORKFLOW\n * messages now prescribe this instead — two spellings where one sweeps and one does not is shim shape\n * #1, an agent types whichever is accepted and the corpses accumulate forever.\n *\n * The raw pair is NOT deleted, and the reason is a constraint that outranks the shim rule: it is a\n * TERMINAL ENTRY ON THE L0 ALLOWLIST (`CHECKOUT_MAIN_PULL_CMD` in ai-hook-rules\n * `src/bin/l0-allowlist.ts`, consumed as an L0 cure in `src/core/l0-matrix.ts`) — one of\n * the few commands still permitted while an L0 block denies every other tool call. In exactly that\n * state, `node_modules` is the thing that is untrustworthy, so a `pnpm wp-*` bin is the one kind of cure\n * that cannot be relied on to run. The same reasoning covers the L0 shim's own fix option in\n * `templates/ai-hook.sh` (rendered from `src/bin/shim-drift-fix.ts`).\n *\n * So the end state is TWO LAYERS, not a deletion, and it is now in place:\n *   • L0 recovery (l0-allowlist, shim-drift-fix, l0-matrix) → keeps the raw pair. It is not a shim\n *     there; it is the only thing that works when the package manager's output is what is in doubt.\n *   • the WORKFLOW layer (stale-main-bash-guard's preferred cure, merged-branch-message/-bash-guard,\n *     TreeRecovery's cleanupSteps and updateMainSteps, the L2 rows/doc, CLAUDE.md's \"Finishing a\n *     Feature\") → prescribes `pnpm wp-checkout-clean-main`, and no longer prints the pair.\n *\n * The pair remains ALLOWED as a Bash command in both layers — this changed what the guards TEACH, not\n * what they permit. Blocking it would have deleted the L0 escape along with the shim.\n *\n * ─── WHY GOING TO MAIN IS THE RIGHT MOMENT TO SWEEP ───────────────────────────────────────────────────\n * The corpses appear when git moves the working tree onto a base where the tracked files under some\n * directory are gone. Landing a PR and returning to main is when every developer does that, on every\n * clone, roughly once per merged PR — so a sweep bolted here converges the whole team's machines with no\n * new trigger, no git hook to distribute, and no background daemon. It is also the quietest moment in the\n * day to move directories: nothing is building, no dev server is watching files.\n *\n * ─── WHY THE ORDER IS FIXED AND NOT PARALLEL ──────────────────────────────────────────────────────────\n * Cleanup runs BEFORE the sweep and not beside it. `wp-cleanup` removes dead worktrees, which changes\n * what is on disk, and a scan racing that would be reading a tree mid-demolition. The scan is one\n * ignore-walk and costs about a second; there is no wall-clock worth buying with that race.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class CheckoutCleanMainCommand {\n    constructor(\n        private readonly repoRootFinder: RepoRootFinder,\n        private readonly cleanupCommand: CleanupCommand,\n        private readonly orphanDirSweeper: OrphanDirSweeper,\n        private readonly workingTreeGate: WorkingTreeGate,\n        private readonly mainCheckout: MainCheckout,\n    ) {}\n\n    async run(): Promise<void> {\n        const repoRoot = this.repoRootFinder.resolveRepoRoot(process.cwd());\n        process.stdout.write(`${SEP}🧹 Checkout main, pull, clean\\n${SEP}\\n`);\n        if (this.isLinkedWorktree(repoRoot)) {\n            await this.sweepOnly(repoRoot);\n            return;\n        }\n        const untracked = this.workingTreeGate.assertNoTrackedChanges(repoRoot);\n        const stashed = this.mainCheckout.goToMain(repoRoot, untracked);\n        this.reportUntracked(untracked, stashed);\n        // No flags: this is the \"go to main and take out the trash\" path, so cleanup behaves exactly as a\n        // bare `pnpm wp-cleanup` does here — reap what is provably dead and every zero-commit husk, ask\n        // (or report) about the rest. Spelled out rather than defaulted so that if CleanupOptions ever\n        // grows a field, this call site is a compile error instead of a silent old behaviour.\n        await this.cleanupCommand.run(new CleanupOptions(\n            new DeleteSelection(FLAG_DELETE_BRANCHES, false, ''),\n            new DeleteSelection(FLAG_DELETE_WORKTREES, false, ''),\n            false, false));\n        this.sweep(repoRoot);\n        this.reportStashed(stashed);\n    }\n\n    /**\n     * A linked worktree has no main to check out — `git checkout main` FATALS there with \"main is already\n     * checked out at <primary clone>\", which is a footgun CLAUDE.md currently has to warn about in prose.\n     * So the command does the half that IS meaningful here (worktrees accumulate corpses too, if a\n     * long-lived one keeps merging main in) and says plainly where the other half lives.\n     */\n    private async sweepOnly(repoRoot: string): Promise<void> {\n        process.stdout.write(\n            'This is a linked WORKTREE. main is checked out in the primary clone, so there is nothing\\n'\n            + 'here to check out or pull — sweeping this tree only.\\n\\n'\n            + 'Most worktrees never need this: `wp-cleanup` removes the whole directory once its branch\\n'\n            + 'lands, which takes any orphan directories inside it along. Run this command again from the\\n'\n            + 'primary clone to go to main there.\\n\\n');\n        this.sweep(repoRoot);\n        return Promise.resolve();\n    }\n\n    private isLinkedWorktree(repoRoot: string): boolean {\n        const dirs = dotWebpieces.gitDirs(repoRoot);\n        return dirs !== null && dirs.isLinkedWorktree;\n    }\n\n    /**\n     * Say which untracked files were let through, AFTER the move — so nobody has to wonder whether the\n     * files still sitting in their tree came along for the ride. Printed rather than refused on: see\n     * `WorkingTreeGate` for why an untracked file is not the hazard a tracked one is.\n     *\n     * Silent when the checkout had to stash: those files are NOT sitting in the tree any more, and\n     * \"nothing about them changed\" would be a lie. `reportStashed` speaks for that case instead.\n     */\n    private reportUntracked(untracked: UntrackedFiles, stashed: StashedFiles): void {\n        if (!stashed.isEmpty()) return;\n        const rendered = untracked.render();\n        if (rendered === '') return;\n        process.stdout.write(`\\n${rendered}`);\n    }\n\n    /**\n     * The stash banner goes LAST, on purpose. It is the one thing in this command's output a reader\n     * must not miss — their files left the working tree — and the cleanup and sweep that follow the\n     * checkout print enough to scroll it away if it were emitted where it happened.\n     */\n    private reportStashed(stashed: StashedFiles): void {\n        const rendered = stashed.render();\n        if (rendered === '') return;\n        process.stdout.write(`\\n${rendered}`);\n    }\n\n    /**\n     * Sweep, then print. Never throws: the checkout and pull above already succeeded, and a tidier is not\n     * permitted to turn somebody's completed sync into a failed command.\n     */\n    private sweep(repoRoot: string): void {\n        const report = this.orphanDirSweeper.sweep(repoRoot, new Date());\n        const rendered = report.render();\n        if (rendered === '') return;\n        process.stdout.write(`\\n${rendered}`);\n    }\n}\n"]}

package/src/scripts/commands/cleanup-command.d.ts

@@ -1,36 +1,44 @@
 import { BranchArchiver, BranchReaper, RepoRootFinder } from '@webpieces/rules-config';
 import { WorktreeCleanupSection } from './worktree-cleanup';
+import { CleanupOptions } from './cleanup-options';
 /**
- * wp-cleanup: remove the dead WORKTREES, delete the local branches whose PR is already MERGED, then ASK
- * about the ones that are merely probably-dead.
+ * wp-cleanup: remove the dead WORKTREES, delete the local branches whose PR is already MERGED, REAP
+ * THE ZERO-COMMIT HUSKS, then report everything that is left with the exact command that takes it.
  *
- * A merged PR is the ONLY proof that reaps anything unattended. "Holds no commits" used to be a second
- * proof and no longer is: it is equally the signature of a worktree an agent is working in right now,
- * so it moved into the group this command ASKS about.
+ * ─── WHY A ZERO-COMMIT REF IS REAPED AND NOT ASKED ABOUT ─────────────────────────────────────────
+ * A ref with 0 unique commits is byte-identical to origin/main. Deleting it loses a NAME, not a
+ * commit — and the name comes back with one `git checkout -b`, or from the archive tag this writes
+ * first. It was previously PROMPTED about, for one real reason: a WORKING TREE looks exactly like
+ * that husk from `git worktree add -b` until its first commit, i.e. for exactly the window an agent
+ * is working in it. But that case is DETECTABLE, and detecting it is cheaper than asking a human:
  *
- * WHY WORKTREES ARE PART OF THIS: they were the half that never got reaped. The verdicts existed —
- * merged-branches.ts has been writing a full `DeletableWorktree[]` into the cache all along — and their
- * only consumer used them to BLOCK the next `git worktree add`, never to remove anything. Meanwhile a
- * live worktree pins its branch, so the branch was spared too. Two things the tooling could PROVE were
- * dead, accumulating forever, until the guard refused to create the next branch and the only remedy it
- * could offer was loosening its own cap. See WorktreeCleanupSection and WorktreeReaper.
+ *   · the worktree holds uncommitted or untracked files (`git status --porcelain`) — spared, said out loud
+ *   · the worktree is LOCKED by a live holder (a lock reason naming something present, or a claude
+ *     agent whose pid is still running) — spared by the verdicts before it ever reaches here
+ *   · it is the tree we are standing in, or a detached HEAD — spared, likewise
  *
- * WHY a named command instead of the `git branch -D a b c` the guards used to print: an AI agent
- * reads a raw `-D` as destructive, so it asks permission and stops — which is exactly why branches
- * piled up despite the tooling knowing precisely which ones were dead. `pnpm wp-cleanup` is one
- * boring, allowlistable verb whose safety is a property of the command itself rather than of the
- * agent's judgement about a git flag.
+ * So the bar moved from "prove it is dead" to "prove somebody is holding it", deliberately, because
+ * the cost of being wrong is a re-`checkout -b` and the cost of being cautious was a prompt that
+ * stopped a human's terminal to adjudicate two refs that could not possibly hold work. Refs that DO
+ * carry unique commits keep every bit of the old caution.
  *
- * WHY IT NOW PROMPTS: sparing silently was the other half of the same problem. Every spared branch
- * reported the identical `no merged PR found — a human must decide`, so the human could not decide,
- * so nothing got deleted, so the pile grew until branch-creation-guard refused to make the next branch
- * and an agent went looking for a config knob to loosen. Shown a real classification with unique-commit
- * counts, the human in that session answered in five words: "these should all be delete branches".
- * The prompt is cheap because archiving happens FIRST — a yes costs a tag, not the history.
+ * ─── WHY FLAGS, AND WHY THEY BEAT THE TTY SNIFF ──────────────────────────────────────────────────
+ * `process.stdin.isTTY !== true` used to be the whole basis for "is a human standing here?", and it
+ * is a proxy, not a fact: a human running `pnpm wp-cleanup | tee log` has no tty, an agent on a pty
+ * has one. The sniff stays as the DEFAULT selector; `--delete-branches` / `--delete-worktrees` /
+ * `--interactive` / `--report` let the caller who KNOWS say so, and an explicit flag always wins.
  *
- * All the danger still lives in the verdicts, not here — see BranchReaper for why every AUTOMATICALLY
- * deleted branch is provably dead and recoverable, and note that nothing in the prompted group is ever
- * deleted without an explicit typed answer.
+ * ─── WHY A NON-TTY RUN NOW DELETES NOTHING IT WAS NOT ASKED TO ───────────────────────────────────
+ * It used to silently take the "redundant" groups and print a bare list of names it left. That is
+ * strictly less than the human sees, and — worse — it broke the one invariant that makes numeric
+ * selection safe: THE NUMBERS IN THE FLAG ARE THE NUMBERS JUST PRINTED. A run that deletes half of a
+ * numbered list renumbers the rest, so the `--delete-branches=3,4` it printed would land on entries
+ * 5 and 6 next time. So the unattended path now prints the IDENTICAL numbered, classified block a
+ * human sees plus the exact command that takes it, and takes nothing from that block itself. The
+ * husks it does reap are never IN the block, so reaping them cannot shift a single number.
+ *
+ * All the danger still lives in the verdicts, not here — see BranchReaper for why every automatically
+ * deleted branch is recoverable, and note that EVERY delete on every path here archives first.
  */
 export declare class CleanupCommand {
     private readonly repoRootFinder;
@@ -45,11 +53,19 @@ export declare class CleanupCommand {
      * next one. Reaping the worktree takes its branch with it, and the branch pass then recomputes its
      * verdicts from scratch against the post-removal truth.
      */
-    run(): Promise<void>;
+    run(options: CleanupOptions): Promise<void>;
+    /**
+     * `--report`: the whole classified picture, and NOT ONE DELETE.
+     *
+     * This is the only run whose numbers are guaranteed still valid when the next command starts,
+     * because a run that deletes nothing cannot renumber anything. That is what makes it the honest
+     * first half of `--report` → read the numbers → `--delete-branches=1,3`.
+     */
+    private reportOnly;
+    private wouldReapBlock;
     private cleanUpBranches;
     /**
-     * Reap the provably-dead worktrees, then ASK about the probably-dead ones — the same two-tier
-     * posture the branch half has, because it is the same verdict on the same branch.
+     * Reap the provably-dead worktrees and the zero-commit husks, then decide about the rest.
      *
      * WorktreeReaper enforces the safety rails regardless of what is passed or answered: never the
      * primary clone, never the tree this command is running in, and never `--force` (git's refusal to
@@ -57,6 +73,8 @@ export declare class CleanupCommand {
      * cleanup command becomes a data-loss command).
      */
     private cleanUpWorktrees;
+    private nothingToDo;
+    private huskBlock;
     private report;
     private reapedLine;
     /**
@@ -72,38 +90,41 @@ export declare class CleanupCommand {
      * worktree prompt, which shows both the path and the branch it holds, or it is not offered at all.
      */
     private promptable;
-    private classifiedBlock;
     /**
-     * Ask which of the classified branches to delete. Answers: `all`, `none` (default), or a
-     * comma/space-separated list of the numbers shown.
+     * The zero-commit husks out of a promptable list — reaped by default, and never numbered.
      *
-     * NON-INTERACTIVE (no TTY — CI, a hook, an AGENT'S piped shell) takes everything except
-     * NEVER PROPOSED, and says exactly what it took.
+     * Keeping them OUT of the numbered block is what keeps `--delete-branches=1,3` honest: whatever
+     * this reaps, the entries the caller can name are the same entries in the same order as on the
+     * `--report` run that printed those numbers.
+     *
+     * THE CLASSIFICATION TOKEN IS THE ONLY SPELLING OF "husk". It would read as belt-and-braces to
+     * also accept `commits === 0` here, and it is the opposite: MergedBranchesService.classify tests
+     * commits===0 BEFORE anything else, so a second test can only ever disagree with the verdict — and
+     * disagreeing in the widening direction, auto-reaping something no classification called a husk.
+     */
+    private husks;
+    private rest;
+    private classifiedBlock;
+    /**
+     * Who decides about the numbered block, in priority order:
      *
-     * It used to take nothing at all, on the reasoning that "a prompt nobody can see must never be
-     * read as consent". Correct about consent, wrong about who is standing there: the overwhelmingly
-     * common non-TTY caller is an agent that was TOLD to clean up, and for it the prompt was a dead
-     * end — wp-cleanup deleted nothing, the branch cap still blocked, and the only path left was to
-     * hand the human a table of branches to adjudicate. The human's response to receiving one of
-     * those: "I am tired of AI asking me to cleanup things it can do by itself".
+     *  1. an explicit `--delete-branches` / `--delete-worktrees` — the caller said so, and a caller who
+     *     said so is never overruled by what stdin happens to be attached to;
+     *  2. a terminal, or `--interactive` — ask;
+     *  3. otherwise — take NOTHING, and print the exact command that takes it.
      *
-     * So consent is honoured where it is actually needed rather than everywhere. NEVER PROPOSED is
-     * the group whose commits may be the only copy in existence; it is never taken unattended and is
-     * the one thing left to ask about. The rest — a closed-unmerged PR superseded by later merges,
-     * commits already patch-equivalent in main, a ref identical to origin/main — are redundant by
-     * evidence, and every one of them is archived to an `archive/<date>/<branch>` tag with a
-     * `recover=` command logged before it is touched. An interactive human still gets the full
-     * prompt, including NEVER PROPOSED.
+     * (3) is the case an agent lands in, and it is deliberately empty-handed. See the class comment:
+     * a run that deletes part of a numbered list invalidates the numbers it just printed, and those
+     * numbers are the whole interface the next run is given.
      */
-    private askWhichToDelete;
+    private decide;
     /**
-     * What an unattended run takes: everything promptable except NEVER PROPOSED (see above).
+     * The exact command that takes what this run left — the half a non-tty caller never used to get.
      *
-     * Prints the split either way, because a cleanup that deletes silently is a cleanup nobody can
-     * audit — and the leftover NEVER PROPOSED names are exactly the short question an agent should
-     * put to a human, in place of the six-branch table this replaced.
+     * It states the numbering contract out loud because a shifted number is the one way this command
+     * can delete the wrong ref, and the caller reading this is usually a program.
      */
-    private unattendedPicks;
+    private flagHint;
     private pickByNumber;
     protected question(prompt: string): Promise<string>;
 }