@webpieces/ai-hook-rules 0.4.508 → 0.4.510

package/src/core/effective-tree.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EffectiveTreeResolver = exports.EffectiveTree = void 0;
+exports.atRoot = atRoot;
+const tslib_1 = require("tslib");
+const path = tslib_1.__importStar(require("path"));
+const child_process_1 = require("child_process");
+const rules_config_1 = require("@webpieces/rules-config");
+const command_scan_1 = require("./command-scan");
+const shell_segment_scan_1 = require("./rules/shell-segment-scan");
+/** Data-only (per CLAUDE.md, classes for data). */
+class EffectiveTree {
+    /** The pre-`cd` cwd the hook was handed. For an agent in a worktree this is the primary clone. */
+    shellCwd;
+    /** The directory the command really runs in, after its own leading `cd`/`pushd` run. */
+    effectiveCwd;
+    /** The tree root to JUDGE: the owning worktree root, the foreign repo root, or the governed root. */
+    root;
+    /** The root that owns webpieces.config.json — where config and excludePaths come from. */
+    governedRoot;
+    kind;
+    /** The command acts on a tree other than the shell's own — messages must steer with `cd <root> &&`. */
+    redirected;
+    constructor(shellCwd, effectiveCwd, root, governedRoot, kind) {
+        this.shellCwd = shellCwd;
+        this.effectiveCwd = effectiveCwd;
+        this.root = root;
+        this.governedRoot = governedRoot;
+        this.kind = kind;
+        this.redirected = path.resolve(root) !== path.resolve(shellCwd);
+    }
+}
+exports.EffectiveTree = EffectiveTree;
+class EffectiveTreeResolver {
+    scanner;
+    worktrees = new rules_config_1.WorktreeService();
+    shell;
+    constructor(scanner = new command_scan_1.CommandScanner()) {
+        this.scanner = scanner;
+        this.shell = new shell_segment_scan_1.ShellSegmentScan(scanner);
+    }
+    resolve(command, shellCwd, governedRoot) {
+        const effectiveCwd = this.effectiveCwd(command, shellCwd);
+        const kindAndRoot = this.classify(effectiveCwd, governedRoot);
+        return new EffectiveTree(shellCwd, effectiveCwd, kindAndRoot.root, governedRoot, kindAndRoot.kind);
+    }
+    /**
+     * The cwd a command actually runs from, resolving a LEADING run of `cd`/`pushd` in the command.
+     *
+     * ONLY a leading run counts. Once a non-cd command appears it has ALREADY run in the current dir,
+     * so a later `cd` must not retroactively pull it out of scope — otherwise a trailing
+     * `… && cd <exempt-tree>` would exempt the WHOLE line, smuggling a root-level `git push` past the
+     * guards. `cd a && cd b && git …` resolves left to right, matching the shell.
+     *
+     * Segmentation is ShellSegmentScan's (over CommandScanner), so quoting is handled exactly as the
+     * guards handle it: `echo "cd sub && git push"` is ONE opaque segment whose first word is `echo`,
+     * so the quoted `cd` is never picked up and cannot be weaponised into a scope escape.
+     */
+    effectiveCwd(command, shellCwd) {
+        let effective = shellCwd;
+        for (const segment of this.scanner.commandSegments(command)) {
+            const words = this.shell.effectiveWords(segment);
+            if (words[0] !== 'cd' && words[0] !== 'pushd')
+                break;
+            if (words[1] !== undefined)
+                effective = path.resolve(effective, words[1]);
+        }
+        return effective;
+    }
+    classify(effectiveCwd, governedRoot) {
+        // Fast path — no `cd`, or a `cd` within the governed tree. No worktree enumeration needed, and
+        // the nested-clone check keeps its exact previous behaviour.
+        if (this.isInside(effectiveCwd, governedRoot)) {
+            const gitRoot = gitToplevel(effectiveCwd);
+            if (gitRoot === null)
+                return new TreeClassification('primary', governedRoot);
+            if (path.resolve(gitRoot) === path.resolve(governedRoot))
+                return new TreeClassification('primary', governedRoot);
+            return new TreeClassification('foreign', gitRoot);
+        }
+        // Outside the governed tree: is it a linked worktree of the SAME repo? Longest match wins, so a
+        // worktree nested under another resolves to the innermost one.
+        const owner = this.owningWorktree(effectiveCwd, governedRoot);
+        if (owner !== null) {
+            return new TreeClassification(owner.isMain ? 'primary' : 'worktree', owner.path);
+        }
+        const gitRoot = gitToplevel(effectiveCwd);
+        if (gitRoot === null)
+            return new TreeClassification('outside', governedRoot);
+        if (path.resolve(gitRoot) === path.resolve(governedRoot))
+            return new TreeClassification('primary', governedRoot);
+        return new TreeClassification('foreign', gitRoot);
+    }
+    owningWorktree(dir, governedRoot) {
+        let best = null;
+        for (const tree of this.worktrees.listWorktrees(governedRoot)) {
+            if (!this.isInside(dir, tree.path))
+                continue;
+            if (best === null || tree.path.length > best.path.length)
+                best = tree;
+        }
+        return best;
+    }
+    /** Is `dir` the directory `root` itself, or somewhere beneath it? Pure path math, no filesystem. */
+    isInside(dir, root) {
+        const relative = path.relative(path.resolve(root), path.resolve(dir));
+        return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+    }
+}
+exports.EffectiveTreeResolver = EffectiveTreeResolver;
+/** Data-only carrier for the two values classify() decides together. */
+class TreeClassification {
+    kind;
+    root;
+    constructor(kind, root) {
+        this.kind = kind;
+        this.root = root;
+    }
+}
+/** The steering prefix every remedy needs: `cd` does not persist between tool calls, so a bare
+ *  remedy runs in whatever directory the NEXT call starts in — which is never the tree we judged. */
+// webpieces-disable no-function-outside-class -- one-line path/string formatter shared by the guards' message builders; a class around it would be ceremony
+function atRoot(root, command) {
+    return `cd ${root} && ${command}`;
+}
+// The git repo root of `dir`, or null when it is not in a git repo / git is unavailable. `status !== 0`
+// IS the expected "not a repo" answer (spawnSync does not throw on a non-zero exit), so no try/catch.
+// webpieces-disable no-function-outside-class -- sibling of atRoot(); this module is the resolver plus its two pure helpers
+function gitToplevel(dir) {
+    const r = (0, child_process_1.spawnSync)('git', ['-C', dir, 'rev-parse', '--show-toplevel'], { encoding: 'utf8' });
+    if (r.status !== 0)
+        return null;
+    const root = (r.stdout ?? '').trim();
+    return root !== '' ? root : null;
+}
+//# sourceMappingURL=effective-tree.js.map

package/src/core/effective-tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"effective-tree.js","sourceRoot":"","sources":["../../../../../../packages/tooling/ai-hook-rules/src/core/effective-tree.ts"],"names":[],"mappings":"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","sourcesContent":["import * as path from 'path';\nimport { spawnSync } from 'child_process';\n\nimport { WorktreeService, Worktree } from '@webpieces/rules-config';\n\nimport { CommandScanner } from './command-scan';\nimport { ShellSegmentScan } from './rules/shell-segment-scan';\n\n/**\n * WHICH TREE does a Bash command actually act on? The ONE resolver every bash guard and the\n * force-to-root check share.\n *\n * WHY it has to exist at all: an agent's Bash tool does NOT persist `cd` between calls (verified —\n * a standalone `cd <worktree>` followed by `pwd` in the next call reports the primary clone again).\n * So an agent working in a linked worktree writes self-contained `cd <worktree> && …` commands, and\n * the shell cwd the PreToolUse hook is handed is ALWAYS the primary clone. Every guard that reasons\n * from that cwd judges the wrong tree on every single call. Three field sightings in one session:\n * an `ls` of a path outside every repo blocked as \"this branch is merged\"; a version-drift cure\n * (`pnpm install`) that could not be typed from the directory that needed it; and a command aimed at\n * `/private/tmp` blocked because the PRIMARY clone's main was behind — with a remedy (`git pull` in\n * the primary clone) the agent had been explicitly forbidden to run.\n *\n * Two separate copies of the cwd logic used to exist (the runner's foreign-repo/excludePaths check\n * and force-to-root). They are both this class now: two resolvers WILL disagree about which tree you\n * are in, and a guard that disagrees with the guard beside it is worse than either being wrong.\n *\n * Resolution, in order:\n *   1. `effectiveCwd` — the leading run of `cd`/`pushd` in the command itself, resolved left to right.\n *   2. If that sits under the governed root, the tree is the governed root unless git says the\n *      directory belongs to a DIFFERENT repo (a nested clone under `repositories/**`) → foreign.\n *   3. Otherwise ask git for the worktree list. A LINKED WORKTREE of the governed repo is MANAGED —\n *      it is the same project, just another checkout — so guards run, keyed on THAT tree's branch and\n *      its own `.webpieces/` cache. Before this, a linked worktree read as a different git toplevel\n *      and so as FOREIGN, which silently disabled every guard for `cd <worktree> && …` commands.\n *   4. Anything else that is a git repo → foreign (out of scope, hands-off, as before).\n *   5. Not a git repo at all (`cd /tmp && …`) → OUTSIDE. The guards still run — an absolute path back\n *      into the repo must still be judged — but nothing the command names relative to `/tmp` is\n *      workspace content, which is what ContentReadScan uses `effectiveCwd` for.\n */\nexport type TreeKind = 'primary' | 'worktree' | 'foreign' | 'outside';\n\n/** Data-only (per CLAUDE.md, classes for data). */\nexport class EffectiveTree {\n    /** The pre-`cd` cwd the hook was handed. For an agent in a worktree this is the primary clone. */\n    readonly shellCwd: string;\n    /** The directory the command really runs in, after its own leading `cd`/`pushd` run. */\n    readonly effectiveCwd: string;\n    /** The tree root to JUDGE: the owning worktree root, the foreign repo root, or the governed root. */\n    readonly root: string;\n    /** The root that owns webpieces.config.json — where config and excludePaths come from. */\n    readonly governedRoot: string;\n    readonly kind: TreeKind;\n    /** The command acts on a tree other than the shell's own — messages must steer with `cd <root> &&`. */\n    readonly redirected: boolean;\n\n    constructor(shellCwd: string, effectiveCwd: string, root: string, governedRoot: string, kind: TreeKind) {\n        this.shellCwd = shellCwd;\n        this.effectiveCwd = effectiveCwd;\n        this.root = root;\n        this.governedRoot = governedRoot;\n        this.kind = kind;\n        this.redirected = path.resolve(root) !== path.resolve(shellCwd);\n    }\n}\n\nexport class EffectiveTreeResolver {\n    private readonly worktrees = new WorktreeService();\n    private readonly shell: ShellSegmentScan;\n\n    constructor(private readonly scanner: CommandScanner = new CommandScanner()) {\n        this.shell = new ShellSegmentScan(scanner);\n    }\n\n    resolve(command: string, shellCwd: string, governedRoot: string): EffectiveTree {\n        const effectiveCwd = this.effectiveCwd(command, shellCwd);\n        const kindAndRoot = this.classify(effectiveCwd, governedRoot);\n        return new EffectiveTree(shellCwd, effectiveCwd, kindAndRoot.root, governedRoot, kindAndRoot.kind);\n    }\n\n    /**\n     * The cwd a command actually runs from, resolving a LEADING run of `cd`/`pushd` in the command.\n     *\n     * ONLY a leading run counts. Once a non-cd command appears it has ALREADY run in the current dir,\n     * so a later `cd` must not retroactively pull it out of scope — otherwise a trailing\n     * `… && cd <exempt-tree>` would exempt the WHOLE line, smuggling a root-level `git push` past the\n     * guards. `cd a && cd b && git …` resolves left to right, matching the shell.\n     *\n     * Segmentation is ShellSegmentScan's (over CommandScanner), so quoting is handled exactly as the\n     * guards handle it: `echo \"cd sub && git push\"` is ONE opaque segment whose first word is `echo`,\n     * so the quoted `cd` is never picked up and cannot be weaponised into a scope escape.\n     */\n    effectiveCwd(command: string, shellCwd: string): string {\n        let effective = shellCwd;\n        for (const segment of this.scanner.commandSegments(command)) {\n            const words = this.shell.effectiveWords(segment);\n            if (words[0] !== 'cd' && words[0] !== 'pushd') break;\n            if (words[1] !== undefined) effective = path.resolve(effective, words[1]);\n        }\n        return effective;\n    }\n\n    private classify(effectiveCwd: string, governedRoot: string): TreeClassification {\n        // Fast path — no `cd`, or a `cd` within the governed tree. No worktree enumeration needed, and\n        // the nested-clone check keeps its exact previous behaviour.\n        if (this.isInside(effectiveCwd, governedRoot)) {\n            const gitRoot = gitToplevel(effectiveCwd);\n            if (gitRoot === null) return new TreeClassification('primary', governedRoot);\n            if (path.resolve(gitRoot) === path.resolve(governedRoot)) return new TreeClassification('primary', governedRoot);\n            return new TreeClassification('foreign', gitRoot);\n        }\n\n        // Outside the governed tree: is it a linked worktree of the SAME repo? Longest match wins, so a\n        // worktree nested under another resolves to the innermost one.\n        const owner = this.owningWorktree(effectiveCwd, governedRoot);\n        if (owner !== null) {\n            return new TreeClassification(owner.isMain ? 'primary' : 'worktree', owner.path);\n        }\n\n        const gitRoot = gitToplevel(effectiveCwd);\n        if (gitRoot === null) return new TreeClassification('outside', governedRoot);\n        if (path.resolve(gitRoot) === path.resolve(governedRoot)) return new TreeClassification('primary', governedRoot);\n        return new TreeClassification('foreign', gitRoot);\n    }\n\n    private owningWorktree(dir: string, governedRoot: string): Worktree | null {\n        let best: Worktree | null = null;\n        for (const tree of this.worktrees.listWorktrees(governedRoot)) {\n            if (!this.isInside(dir, tree.path)) continue;\n            if (best === null || tree.path.length > best.path.length) best = tree;\n        }\n        return best;\n    }\n\n    /** Is `dir` the directory `root` itself, or somewhere beneath it? Pure path math, no filesystem. */\n    private isInside(dir: string, root: string): boolean {\n        const relative = path.relative(path.resolve(root), path.resolve(dir));\n        return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));\n    }\n}\n\n/** Data-only carrier for the two values classify() decides together. */\nclass TreeClassification {\n    readonly kind: TreeKind;\n    readonly root: string;\n\n    constructor(kind: TreeKind, root: string) {\n        this.kind = kind;\n        this.root = root;\n    }\n}\n\n/** The steering prefix every remedy needs: `cd` does not persist between tool calls, so a bare\n *  remedy runs in whatever directory the NEXT call starts in — which is never the tree we judged. */\n// webpieces-disable no-function-outside-class -- one-line path/string formatter shared by the guards' message builders; a class around it would be ceremony\nexport function atRoot(root: string, command: string): string {\n    return `cd ${root} && ${command}`;\n}\n\n// The git repo root of `dir`, or null when it is not in a git repo / git is unavailable. `status !== 0`\n// IS the expected \"not a repo\" answer (spawnSync does not throw on a non-zero exit), so no try/catch.\n// webpieces-disable no-function-outside-class -- sibling of atRoot(); this module is the resolver plus its two pure helpers\nfunction gitToplevel(dir: string): string | null {\n    const r = spawnSync('git', ['-C', dir, 'rev-parse', '--show-toplevel'], { encoding: 'utf8' });\n    if (r.status !== 0) return null;\n    const root = (r.stdout ?? '').trim();\n    return root !== '' ? root : null;\n}\n"]}

package/src/core/rules/branch-creation-guard.d.ts

@@ -15,6 +15,7 @@ export declare class BranchCreationGuardRule extends BashRuleBase<BranchCreation
     private readonly mergedBranches;
     private capCache;
     private worktreeCapCache;
+    private capFreshness;
     private worktreeAdd;
     private get branchFormat();
     private get subBranchNaming();
@@ -72,6 +73,25 @@ export declare class BranchCreationGuardRule extends BashRuleBase<BranchCreation
      * so the cap starts enforcing on its own.
      */
     private checkBranchCap;
+    /**
+     * The cache, with entries for branches/worktrees that no longer exist dropped, plus its age recorded.
+     *
+     * Reconciling is the fix for the phantom count: the file is written by a detached refresher and is
+     * DELIBERATELY allowed to go stale, so it keeps naming branches deleted minutes ago and worktrees
+     * already removed. Quoting it verbatim is how the guard announced "8 parked local branches … none of
+     * them are dead" over a repo that had ONE, and then blocked a legitimate `git worktree add` on that
+     * figure. `reconcile` re-checks existence with instant local git reads; it does NOT re-derive any
+     * verdict (that needs the network and belongs in the refresher).
+     */
+    private loadReconciledCache;
+    /**
+     * The "N of them are dead" sentence — or an honest refusal to say a number.
+     *
+     * A count read off a stale file is a claim the guard cannot stand behind, and this guard's numbers
+     * are acted on: they decide whether an agent goes and deletes things. When the cache is too old,
+     * say so and point at the command that recomputes from scratch, rather than asserting a figure.
+     */
+    private deadDetail;
     /**
      * The branch cap, yielding by ONE when the agent is standing on an already-merged branch.
      *
@@ -96,51 +116,4 @@ export declare class BranchCreationGuardRule extends BashRuleBase<BranchCreation
      * budget for it would just silently cost you one worktree.
      */
     private checkWorktreeCap;
-    /**
-     * The reap instructions. `deletable` is PRECOMPUTED in the cache, and every entry earned its place
-     * by one of exactly two proofs: a MERGED PR (the work is in main), or zero commits of its own
-     * (there is no work). Deleting the list cannot lose anything — so just run the command.
-     *
-     * The command is `pnpm wp-cleanup`, NOT the `git branch -D a b c` this used to emit. Two reasons,
-     * both learned the hard way: agents read a bare `-D` as destructive and stop to ask (so nothing
-     * was ever cleaned, and this cap kept firing), and the multi-name form aborts wholesale on the
-     * first branch git refuses, stranding every branch after it in the list. wp-cleanup recomputes
-     * the verdicts, deletes one branch per command, and logs each pre-delete SHA.
-     *
-     * The wording must not overstate the safety: the list is NOT uniformly "merged PR" branches, and
-     * a message that tells an agent to delete has to be exactly true about why that's safe.
-     */
-    private capFixHint;
-    /**
-     * The remedy that actually deletes something without loosening anything: SHOW the spared branches
-     * and ASK the human which may go.
-     *
-     * `keep` is the list the tooling refuses to touch on its own — no merged PR, so no proof the work
-     * is safe. That is exactly the list a human can adjudicate in five seconds and the tooling never
-     * can, and it was never printed: the cap said "N branches were SPARED, do not delete those" and
-     * then offered only config edits. So the agent edited the config.
-     *
-     * Every column is read straight off `.webpieces/merged-branches.json` (written by the detached
-     * refresher) — nothing is recomputed on this blocking path. The SHA is there so the human can see
-     * the delete is reversible; the commit count is there so "0 commits" branches are obvious yeses.
-     */
-    private askHumanOption;
-    /**
-     * The worktree reap remedy.
-     *
-     * It is now ONE command — `pnpm wp-cleanup` — and that is the point of it. The hand-written
-     * sequence this used to print (prune → remove each path → one multi-name `git branch -D`) was
-     * correct git, and it was still never run: an AI agent reads a raw `worktree remove` / `-D` as
-     * destructive, asks permission, and stops. A guard whose only actionable remedies are "raise the
-     * cap" and "set turnOffRuleUntilEpoch" is a guard that teaches config edits, which is the exact
-     * failure the cap exists to prevent. wp-cleanup archives each branch as a tag, removes the
-     * directory, then deletes the branch — in that order, because git refuses to delete a branch a
-     * worktree still holds — and it will not touch the primary clone, the tree you are standing in, or
-     * anything with uncommitted work.
-     *
-     * The explicit git sequence is still printed BELOW the command, as reference rather than as the
-     * instruction: when wp-cleanup declines one of these (typically untracked files), the human needs
-     * to see which directory and what git would have run.
-     */
-    private worktreeCapFixHint;
 }

package/src/core/rules/branch-creation-guard.js

@@ -6,6 +6,7 @@ const rules_config_1 = require("@webpieces/rules-config");
 const types_1 = require("../types");
 const rule_base_1 = require("../rule-base");
 const fix_hint_1 = require("../fix-hint");
+const cap_remedies_1 = require("./cap-remedies");
 const to_error_1 = require("../to-error");
 // Defaults used when the rule has no explicit value in webpieces.config.json.
 // branchFormat is a human sentence telling the AI how to name a branch created off main; it is
@@ -130,6 +131,9 @@ class BranchCreationGuardRule extends rule_base_1.BashRuleBase {
     // Two fields, because the two caps reap different things and their hints share no wording.
     capCache = null;
     worktreeCapCache = null;
+    // How old the cache backing whichever cap fired was, so the hint can SAY "these verdicts are stale"
+    // instead of quoting them as present-tense fact. Null until a cap fires.
+    capFreshness = null;
     // True when the blocked command was a `git worktree add`, so the recovery command we hand back is
     // a worktree command and not a `git checkout -b` the user cannot use here.
     worktreeAdd = false;
@@ -155,10 +159,11 @@ class BranchCreationGuardRule extends rule_base_1.BashRuleBase {
     // convention. The sub-branch affordance only appears under mode 'ON'; 'ON_NO_SUBBRANCHES'
     // hard-blocks it and points instead at the turnOffRuleUntilEpoch escape hatch.
     get fixHint() {
+        const remedies = new cap_remedies_1.CapRemedies(this.capFreshness);
         if (this.worktreeCapCache)
-            return this.worktreeCapFixHint(this.worktreeCapCache);
+            return remedies.worktreeCap(this.worktreeCapCache);
         if (this.capCache)
-            return this.capFixHint(this.capCache);
+            return remedies.branchCap(this.capCache);
         const create = this.worktreeAdd
             ? 'Create it off fresh main: git fetch origin main && git worktree add ../<dir> -b <name> origin/main'
             : 'Create it off fresh main from anywhere (incl. a worktree): git fetch origin main && git checkout -b <name> origin/main';
@@ -193,6 +198,7 @@ class BranchCreationGuardRule extends rule_base_1.BashRuleBase {
     check(ctx) {
         this.capCache = null;
         this.worktreeCapCache = null;
+        this.capFreshness = null;
         // Match against the command with heredoc bodies and prose-in-quotes removed (BashContext
         // computes it for every guard now — this rule's private copy was the original).
         const command = ctx.commandCode;
@@ -324,17 +330,57 @@ class BranchCreationGuardRule extends rule_base_1.BashRuleBase {
         const cap = this.effectiveBranchCap(ctx);
         if (count < cap)
             return null;
-        const cache = this.mergedBranches.readMergedBranches(ctx.workspaceRoot);
+        const cache = this.loadReconciledCache(ctx);
         if (!cache)
             return null;
         this.capCache = cache;
-        const reapable = cache.deletable.length;
-        const detail = reapable > 0
-            ? `${String(reapable)} of them are dead (merged, or holding no commits) and can be deleted right now.`
-            : 'None of them are dead, so none can be auto-reaped — see the options below.';
+        // Only branches that are BOTH still on disk (reconcile guaranteed that) and parked can be
+        // reaped to make room. A cached verdict about a branch a worktree now holds is not a figure
+        // this message may quote at someone.
+        const parkedSet = new Set(parked);
+        const reapable = cache.deletable
+            .filter((entry) => parkedSet.has(entry.branch)).length;
         return new types_1.Violation(1, truncate(ctx.command), `You have ${String(count)} parked local branches (not counting any checked out in a worktree); ` +
             `the cap (branch-creation-guard.maxLocalBranches) is ${String(this.maxLocalBranches)}. ` +
-            `${detail} Clean up before creating another.`);
+            `${this.deadDetail(reapable, 'dead (a MERGED PR backs them)')} Clean up before creating another.`);
+    }
+    /**
+     * The cache, with entries for branches/worktrees that no longer exist dropped, plus its age recorded.
+     *
+     * Reconciling is the fix for the phantom count: the file is written by a detached refresher and is
+     * DELIBERATELY allowed to go stale, so it keeps naming branches deleted minutes ago and worktrees
+     * already removed. Quoting it verbatim is how the guard announced "8 parked local branches … none of
+     * them are dead" over a repo that had ONE, and then blocked a legitimate `git worktree add` on that
+     * figure. `reconcile` re-checks existence with instant local git reads; it does NOT re-derive any
+     * verdict (that needs the network and belongs in the refresher).
+     */
+    loadReconciledCache(ctx) {
+        const raw = this.mergedBranches.readMergedBranches(ctx.workspaceRoot);
+        if (!raw)
+            return null;
+        this.capFreshness = this.mergedBranches.freshness(raw);
+        return this.mergedBranches.reconcile(ctx.workspaceRoot, raw);
+    }
+    /**
+     * The "N of them are dead" sentence — or an honest refusal to say a number.
+     *
+     * A count read off a stale file is a claim the guard cannot stand behind, and this guard's numbers
+     * are acted on: they decide whether an agent goes and deletes things. When the cache is too old,
+     * say so and point at the command that recomputes from scratch, rather than asserting a figure.
+     */
+    deadDetail(reapable, what) {
+        const freshness = this.capFreshness;
+        if (freshness !== null && freshness.stale) {
+            const age = freshness.ageMinutes >= 0
+                ? `${String(freshness.ageMinutes)} minute(s) old`
+                : 'carrying no usable timestamp';
+            return `How many are dead is NOT known right now — the cached verdicts ` +
+                `(.webpieces/merged-branches.json, ${age}) are stale, so no count is asserted. ` +
+                '`pnpm wp-cleanup` recomputes them from scratch.';
+        }
+        if (reapable === 0)
+            return 'None of them are dead, so none can be auto-reaped — see the options below.';
+        return `${String(reapable)} of them are ${what} and wp-cleanup can reap them.`;
     }
     /**
      * The branch cap, yielding by ONE when the agent is standing on an already-merged branch.
@@ -383,153 +429,15 @@ class BranchCreationGuardRule extends rule_base_1.BashRuleBase {
         const count = this.worktrees.linkedWorktrees(ctx.workspaceRoot).length;
         if (count < this.maxWorktrees)
             return null;
-        const cache = this.mergedBranches.readMergedBranches(ctx.workspaceRoot);
+        const cache = this.loadReconciledCache(ctx);
         if (!cache)
             return null;
         this.worktreeCapCache = cache;
         const reapable = cache.worktrees.filter((tree) => tree.deletable).length;
-        const detail = reapable > 0
-            ? `${String(reapable)} of them are dead (merged branch, no commits, or a missing directory) ` +
-                'and can be removed right now.'
-            : 'None of them are dead, so none can be auto-reaped — see the options below.';
         return new types_1.Violation(1, truncate(ctx.command), `You have ${String(count)} linked worktrees; the cap (branch-creation-guard.maxWorktrees) ` +
-            `is ${String(this.maxWorktrees)}. ${detail} Clean up before creating another.`);
-    }
-    /**
-     * The reap instructions. `deletable` is PRECOMPUTED in the cache, and every entry earned its place
-     * by one of exactly two proofs: a MERGED PR (the work is in main), or zero commits of its own
-     * (there is no work). Deleting the list cannot lose anything — so just run the command.
-     *
-     * The command is `pnpm wp-cleanup`, NOT the `git branch -D a b c` this used to emit. Two reasons,
-     * both learned the hard way: agents read a bare `-D` as destructive and stop to ask (so nothing
-     * was ever cleaned, and this cap kept firing), and the multi-name form aborts wholesale on the
-     * first branch git refuses, stranding every branch after it in the list. wp-cleanup recomputes
-     * the verdicts, deletes one branch per command, and logs each pre-delete SHA.
-     *
-     * The wording must not overstate the safety: the list is NOT uniformly "merged PR" branches, and
-     * a message that tells an agent to delete has to be exactly true about why that's safe.
-     */
-    capFixHint(cache) {
-        const options = [];
-        // Nothing auto-reapable → the ASK is the preferred move, and it comes FIRST. This is the whole
-        // point of the option: with an empty `deletable` list the only advice left used to be "raise
-        // maxLocalBranches" / "set turnOffRuleUntilEpoch", and an agent with no human in the loop
-        // edited webpieces.config.json to escape — loosening the very rule that was working correctly.
-        const askFirst = cache.deletable.length === 0;
-        if (cache.deletable.length > 0) {
-            const names = cache.deletable.map((entry) => entry.branch);
-            options.push(new fix_hint_1.Option(`Run: pnpm wp-cleanup — it deletes these ${String(names.length)} dead branches. Each is either ` +
-                `backed by a MERGED PR or has no commits of its own, so no work can be lost, and every delete ` +
-                `is logged with a recover-by-SHA command (see merged-branches.json for the per-branch reason): ` +
-                names.join(' '), true));
-        }
-        const ask = this.askHumanOption(cache, askFirst);
-        if (ask)
-            options.push(ask);
-        options.push(new fix_hint_1.Option('ONLY IF A HUMAN SAYS SO: raise branch-creation-guard.maxLocalBranches in ' +
-            'webpieces.config.json. Editing this config to get past a guard is not a fix you may make on ' +
-            'your own — ask first (use the option above).'));
-        options.push(new fix_hint_1.Option('ONLY IF A HUMAN SAYS SO: set branch-creation-guard.turnOffRuleUntilEpoch (a future epoch) ' +
-            'in webpieces.config.json to bypass this once. Same rule — ask, do not self-approve.'));
-        const kept = cache.keep.length > 0
-            ? ` ${String(cache.keep.length)} unmerged branch(es) with real commits were deliberately SPARED — ` +
-                'do not delete those; a human decides.'
-            : '';
-        return new fix_hint_1.FixHint('Too many local branches — reap the dead ones before creating another.', 'Full detail (deletable + spared, with per-branch reasons) is in .webpieces/merged-branches.json, ' +
-            `refreshed ${cache.timestamp || 'never'}.${kept} Pick one:`, options);
-    }
-    /**
-     * The remedy that actually deletes something without loosening anything: SHOW the spared branches
-     * and ASK the human which may go.
-     *
-     * `keep` is the list the tooling refuses to touch on its own — no merged PR, so no proof the work
-     * is safe. That is exactly the list a human can adjudicate in five seconds and the tooling never
-     * can, and it was never printed: the cap said "N branches were SPARED, do not delete those" and
-     * then offered only config edits. So the agent edited the config.
-     *
-     * Every column is read straight off `.webpieces/merged-branches.json` (written by the detached
-     * refresher) — nothing is recomputed on this blocking path. The SHA is there so the human can see
-     * the delete is reversible; the commit count is there so "0 commits" branches are obvious yeses.
-     */
-    askHumanOption(cache, preferred) {
-        if (cache.keep.length === 0)
-            return null;
-        const rows = cache.keep.map((entry) => {
-            const sha = entry.sha !== '' ? entry.sha : '???????';
-            const pr = entry.pr > 0
-                ? `PR #${String(entry.pr)} ${entry.prState || 'MERGED'}`
-                : (entry.prState !== '' ? `PR ${entry.prState}` : 'no PR');
-            const commits = entry.commits >= 0 ? `${String(entry.commits)} commit(s) of its own` : 'commit count unknown';
-            return `    ${entry.branch}  [${sha}]  ${pr}  ${commits}  — ${entry.reason}`;
-        });
-        return new fix_hint_1.Option(`ASK THE HUMAN which of these ${String(cache.keep.length)} branches may be deleted. They are ` +
-            'not provably dead, so the tooling will not reap them — but a human can decide in seconds, ' +
-            'and deleting one is the correct fix for "too many branches". Paste this list and ask:\n' +
-            rows.join('\n') + '\n' +
-            'Then delete ONLY the ones approved: git branch -D <approved-branch>\n' +
-            '(each is recoverable — `git branch <name> <sha>` restores it at the SHA shown above).\n' +
-            'Do NOT delete any of these without an explicit yes, and do NOT edit webpieces.config.json instead.', preferred);
-    }
-    /**
-     * The worktree reap remedy.
-     *
-     * It is now ONE command — `pnpm wp-cleanup` — and that is the point of it. The hand-written
-     * sequence this used to print (prune → remove each path → one multi-name `git branch -D`) was
-     * correct git, and it was still never run: an AI agent reads a raw `worktree remove` / `-D` as
-     * destructive, asks permission, and stops. A guard whose only actionable remedies are "raise the
-     * cap" and "set turnOffRuleUntilEpoch" is a guard that teaches config edits, which is the exact
-     * failure the cap exists to prevent. wp-cleanup archives each branch as a tag, removes the
-     * directory, then deletes the branch — in that order, because git refuses to delete a branch a
-     * worktree still holds — and it will not touch the primary clone, the tree you are standing in, or
-     * anything with uncommitted work.
-     *
-     * The explicit git sequence is still printed BELOW the command, as reference rather than as the
-     * instruction: when wp-cleanup declines one of these (typically untracked files), the human needs
-     * to see which directory and what git would have run.
-     */
-    worktreeCapFixHint(cache) {
-        const options = [];
-        const dead = cache.worktrees.filter((tree) => tree.deletable);
-        if (dead.length > 0) {
-            const steps = ['git worktree prune'];
-            for (const tree of dead) {
-                // A prunable worktree has no directory left to remove — step 1 already handled it.
-                if (tree.path !== '')
-                    steps.push(`git worktree remove ${tree.path}`);
-            }
-            const branches = dead
-                .map((tree) => tree.branch)
-                .filter((branch) => branch !== '');
-            if (branches.length > 0)
-                steps.push(`git branch -D ${branches.join(' ')}`);
-            options.push(new fix_hint_1.Option(`Run: pnpm wp-cleanup — it REMOVES these ${String(dead.length)} dead worktrees for you. Each ` +
-                'holds a branch backed by a MERGED PR, a branch with no commits of its own, or a directory ' +
-                'that is already gone, so no work can be lost (see merged-branches.json for the per-worktree ' +
-                'reason). It archives every branch as an `archive/<date>/<branch>` tag BEFORE removing ' +
-                'anything, logs each removal with a `recover=` command, and refuses to touch the primary ' +
-                'clone, the worktree you are standing in, or any worktree holding uncommitted work. ' +
-                `Equivalent by hand, in this order (prune first, branches last — git refuses to delete a ` +
-                `branch a worktree still holds): ${steps.join(' && ')}`, true));
-        }
-        else {
-            // Nothing is PROVABLY dead, but wp-cleanup also prompts about the probably-dead ones, so it
-            // is still the remedy that can delete something — and it is still better advice than a knob.
-            options.push(new fix_hint_1.Option('Run: pnpm wp-cleanup — none of these worktrees is provably dead, but it lists the ' +
-                'probably-dead ones (closed-unmerged PR, content already in main, never proposed) with ' +
-                'their branch and reason and asks which to remove. Answer that prompt instead of raising ' +
-                'the cap.', true));
-        }
-        options.push(new fix_hint_1.Option('If you genuinely need more worktrees in flight, raise branch-creation-guard.maxWorktrees ' +
-            'in webpieces.config.json.'));
-        options.push(new fix_hint_1.Option('To bypass this once, set branch-creation-guard.turnOffRuleUntilEpoch (a future epoch) ' +
-            'in webpieces.config.json.'));
-        const spared = cache.worktrees.length - dead.length;
-        const kept = spared > 0
-            ? ` ${String(spared)} worktree(s) were deliberately SPARED (locked, holding unmerged work, or ` +
-                'the one you are standing in) — do not remove those; a human decides.'
-            : '';
-        return new fix_hint_1.FixHint('Too many worktrees — reap the dead ones before creating another.', 'Full detail (deletable + spared, with per-worktree reasons) is in .webpieces/merged-branches.json, ' +
-            `refreshed ${cache.timestamp || 'never'}.${kept} Pick one:`, options);
+            `is ${String(this.maxWorktrees)}. ` +
+            `${this.deadDetail(reapable, 'dead (a MERGED PR backs the branch, or the directory is already gone)')} ` +
+            'Clean up before creating another.');
     }
 }
 exports.BranchCreationGuardRule = BranchCreationGuardRule;