@webpieces/repo-workflow-core 0.0.1

package/src/worktree-lock-verdicts.js

@@ -0,0 +1,225 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorktreeLockVerdicts = exports.LockDecision = exports.LockEvidence = exports.HARNESS_NOT_CONSULTED = exports.LOCK_LIVENESS_UNVERIFIABLE = void 0;
+const tslib_1 = require("tslib");
+const inversify_1 = require("inversify");
+const agent_worktree_lock_1 = require("./agent-worktree-lock");
+const harness_agent_activity_1 = require("./harness-agent-activity");
+const worktrees_1 = require("./worktrees");
+/**
+ * What a `git worktree lock` DOES to a worktree's cleanup verdict.
+ *
+ * Separate from agent-worktree-lock.ts (which only parses a lock reason) and from
+ * harness-agent-activity.ts (which only asks the harness about an agent): this is the POLICY built on
+ * top of that evidence — what stops a reap, what a spared lock is allowed to CLAIM about who took it,
+ * and what an overridden one has to leave on the verdict so the reaper knows to clear it.
+ *
+ * ─── WHY THE POLICY CHANGED ──────────────────────────────────────────────────────────────────────
+ * It used to be one question, asked of the kernel: is the pid in the lock reason still running? That
+ * pid is the Claude Code SESSION process, shared by every subagent, so the answer was yes for the
+ * whole life of a session and every agent worktree was spared forever — nine against a cap of five,
+ * with one agent running, each carrying the sentence "that agent is working in here" about agents
+ * whose PRs had already merged. Both halves were defects: the reap never happened, and the message
+ * asserted something nobody knew.
+ *
+ * ─── THE DECISION TABLE, AND THE ONE RULE BEHIND IT ──────────────────────────────────────────────
+ *
+ *      HARNESS STATE MAY ONLY VETO A REAP. IT MAY NEVER LICENSE ONE.
+ *
+ * The licence comes solely from the branch/commit evidence wp-cleanup already computes and already
+ * gets right. So, for a lock this repo can read as the harness's own:
+ *
+ *   branch evidence does NOT say deletable          → SPARE. The harness is not even consulted; it
+ *                                                     cannot promote a spare into a reap.
+ *   deletable, but the worktree is DIRTY            → SPARE, unconditionally. Uncommitted or
+ *                                                     untracked files are work no archive tag can
+ *                                                     bring back. This one overrides everything,
+ *                                                     including the explicit flag.
+ *   deletable, clean, harness says the agent is
+ *   mid-tool-call and writing                       → SPARE. The veto.
+ *   deletable, clean, harness says returned /
+ *   long-stale / cannot tell                        → judge it on its branch like any unlocked tree,
+ *                                                     clearing the lock on the way out.
+ *
+ * `--ignore-stale-locks` moves ONE line of that table: it lets a locked worktree whose branch is not
+ * provably dead be classified on its real branch and commit state anyway (so a zero-commit husk gets
+ * reaped and a worktree holding unique commits reaches the numbered block a human can answer). It
+ * does not touch the dirty rail or the live-agent veto, because neither of those is what the caller
+ * is complaining about when they pass it.
+ *
+ * ─── SCOPE: AGENT LOCKS ONLY ─────────────────────────────────────────────────────────────────────
+ * Every override applies ONLY to a lock this file can read as the harness's own. A lock reason naming
+ * anything else — a human's "dean is debugging", or nothing at all — is still an instruction from
+ * somebody, and wp-cleanup still obeys it.
+ */
+/**
+ * The exact phrase a spared "we cannot tell" verdict carries, exported so wp-cleanup can spot those
+ * worktrees and offer the flag that judges them on their branch instead.
+ *
+ * ONE spelling, shared: the alternative is the caller re-deriving the same condition from a second
+ * copy of the sentence, which is how a message and the code that keys off it drift apart.
+ */
+exports.LOCK_LIVENESS_UNVERIFIABLE = 'whether that agent is still running cannot be verified';
+/**
+ * The stand-in for "the harness was never asked", used on the paths where asking could not change the
+ * answer. It is UNKNOWN, so a caller that consults it anyway still fails safe.
+ */
+exports.HARNESS_NOT_CONSULTED = new harness_agent_activity_1.AgentActivity(harness_agent_activity_1.AGENT_ACTIVITY_UNKNOWN, 'the harness was not consulted');
+// Data-only (per CLAUDE.md, classes for data). Everything `decide` rules on, as one value — see
+// `gather`, which is the only thing that builds one outside a test.
+class LockEvidence {
+    /** The lock reason verbatim, straight out of `git worktree list --porcelain`. */
+    lockReason;
+    /** What the harness says about the agent named in that reason, or HARNESS_NOT_CONSULTED. */
+    activity;
+    /** Does `git status --porcelain` report anything, or could it not answer? Either way: held. */
+    workInFlight;
+    /** Why it is held, in git's terms — printed verbatim, because the two reasons differ for a human. */
+    workInFlightReason;
+    /** Is the branch this worktree holds ALREADY provably dead by the ordinary verdicts? */
+    branchDeletable;
+    /** The caller said to treat a standing agent lock as no evidence at all. */
+    ignoreStaleAgentLocks;
+    constructor(lockReason, activity, workInFlight, workInFlightReason, branchDeletable, ignoreStaleAgentLocks) {
+        this.lockReason = lockReason;
+        this.activity = activity;
+        this.workInFlight = workInFlight;
+        this.workInFlightReason = workInFlightReason;
+        this.branchDeletable = branchDeletable;
+        this.ignoreStaleAgentLocks = ignoreStaleAgentLocks;
+    }
+}
+exports.LockEvidence = LockEvidence;
+/**
+ * Data-only. The one verdict this file produces: spare or override, the sentence that says WHY, and
+ * the agent lock the reaper will have to clear if the worktree goes.
+ *
+ * ONE class rather than a spare-path method and an override-path method, because the two answers are
+ * mutually exclusive readings of the same evidence, and two methods is how they drift apart — which
+ * is precisely what happened before: the old spared message and the old stale-lock test were computed
+ * from the same pid by different code, and only one of them was ever corrected.
+ */
+class LockDecision {
+    /** True: leave this worktree alone, and `reason` is the whole story. */
+    spare;
+    /** Spared: why it was left. Overridden: the clause appended to the branch's own verdict. */
+    reason;
+    /** The agent lock to clear on the way out — null when nothing may be cleared. */
+    lock;
+    constructor(spare, reason, lock) {
+        this.spare = spare;
+        this.reason = reason;
+        this.lock = lock;
+    }
+}
+exports.LockDecision = LockDecision;
+let WorktreeLockVerdicts = class WorktreeLockVerdicts {
+    agentLocks;
+    harness;
+    worktrees;
+    // Defaulted like BranchReaper's collaborators, so the non-DI call sites can just
+    // `new WorktreeLockVerdicts()` while inversify still injects the singletons from a container.
+    constructor(agentLocks = new agent_worktree_lock_1.AgentWorktreeLockReader(), harness = new harness_agent_activity_1.HarnessAgentActivityReader(), worktrees = new worktrees_1.WorktreeService()) {
+        this.agentLocks = agentLocks;
+        this.harness = harness;
+        this.worktrees = worktrees;
+    }
+    /**
+     * Collect what `decide` rules on — and, just as deliberately, DECLINE to collect the two
+     * expensive facts when they cannot change the answer.
+     *
+     * `git status --porcelain` and a walk of the harness's state tree are gathered only when a reap
+     * is otherwise on the table: the lock is one this repo can read as the harness's own, and either
+     * the branch is already provably dead or the caller asked for locks to be ignored. That is not an
+     * optimisation dressed up as a rule — harness state may only VETO a reap, never license one, so on
+     * a path with no reap to veto there is nothing to ask, and asking would invite a later reader to
+     * let the answer decide something.
+     */
+    gather(tree, branchDeletable, ignoreStaleAgentLocks) {
+        const lock = this.agentLocks.parse(tree.lockReason);
+        if (lock === null || (!branchDeletable && !ignoreStaleAgentLocks)) {
+            return new LockEvidence(tree.lockReason, exports.HARNESS_NOT_CONSULTED, false, '', branchDeletable, ignoreStaleAgentLocks);
+        }
+        const held = this.worktrees.workInFlight(tree.path);
+        return new LockEvidence(tree.lockReason, this.harness.activityOf(lock.agent, tree.path), held.held, held.reason, branchDeletable, ignoreStaleAgentLocks);
+    }
+    /**
+     * Spare this locked worktree, or judge it on its branch like any unlocked one — with the sentence
+     * that says which piece of evidence decided it.
+     *
+     * The order below IS the decision table in the class header, in the same order, for the same
+     * reasons. Read it there.
+     */
+    decide(evidence) {
+        const lock = this.agentLocks.parse(evidence.lockReason);
+        if (lock === null)
+            return new LockDecision(true, this.foreignLockReason(evidence.lockReason), null);
+        if (!evidence.branchDeletable && !evidence.ignoreStaleAgentLocks) {
+            return new LockDecision(true, this.unverifiableReason(lock), null);
+        }
+        if (evidence.workInFlight) {
+            return new LockDecision(true, `locked by claude agent ${lock.agent}, and the worktree ${evidence.workInFlightReason} — `
+                + 'nothing archives that, so it is left exactly where it is', null);
+        }
+        if (evidence.activity.state === harness_agent_activity_1.AGENT_ACTIVITY_LIVE) {
+            return new LockDecision(true, `locked by claude agent ${lock.agent}, and the Claude Code harness says `
+                + `${evidence.activity.detail} — that agent is working in here`, null);
+        }
+        if (evidence.branchDeletable) {
+            return new LockDecision(false, `the lock from claude agent ${lock.agent} did not stop this — the worktree is clean, its `
+                + `branch is already dead, and ${evidence.activity.detail}`, lock);
+        }
+        return new LockDecision(false, `the lock from claude agent ${lock.agent} was treated as no evidence, as asked`, lock);
+    }
+    /**
+     * WHY a locked worktree was left alone when the lock is NOT the harness's — reporting what the
+     * reason SAYS, never who we imagine wrote it.
+     *
+     * This used to read `locked by a human — do not touch` for every lock in existence, which named an
+     * actor nothing in the evidence identifies: the lock reason is the ONLY thing we have, a human may
+     * have locked it, so may some other tool, and asserting either is the same defect whichever way it
+     * lands.
+     */
+    foreignLockReason(lockReason) {
+        if (lockReason === '') {
+            return 'locked with no reason recorded — nothing says who locked it or why, so it is left alone';
+        }
+        return `locked, reason "${lockReason}" — that is not a claude agent lock, so who locked it `
+            + 'is unknown; left alone';
+    }
+    /**
+     * The sentence that replaced "pid N still running — that agent is working in here".
+     *
+     * It says only what is known: which agent the reason names, that the pid in it cannot answer the
+     * question because it is the shared session process, and that nothing else made the worktree
+     * provably dead either. No claim about anybody working — and no claim about the harness, which on
+     * this path was deliberately never asked, because its answer could not have changed the outcome.
+     */
+    unverifiableReason(lock) {
+        return `locked by claude agent ${lock.agent}; ${exports.LOCK_LIVENESS_UNVERIFIABLE} — the recorded pid `
+            + `${String(lock.pid)} is the shared Claude Code session process, not the agent's. Its branch `
+            + 'is not provably dead either, so it is left alone';
+    }
+    /**
+     * Stamp an overridden verdict with the lock the reap must CLEAR: git refuses to remove a locked
+     * worktree, and the reason has to say why a lock is being overridden at all.
+     *
+     * Applied to every verdict the fall-through can produce, not just the deletable one, because the
+     * spared cases are exactly where a human reads the reason and asks "wasn't that locked?".
+     */
+    annotate(verdict, decision) {
+        if (decision === null || decision.spare || decision.lock === null)
+            return verdict;
+        verdict.unlockBeforeRemove = true;
+        verdict.reason = `${verdict.reason}; ${decision.reason}`;
+        return verdict;
+    }
+};
+exports.WorktreeLockVerdicts = WorktreeLockVerdicts;
+exports.WorktreeLockVerdicts = WorktreeLockVerdicts = tslib_1.__decorate([
+    (0, inversify_1.injectable)(inversify_1.bindingScopeValues.Singleton),
+    tslib_1.__metadata("design:paramtypes", [agent_worktree_lock_1.AgentWorktreeLockReader,
+        harness_agent_activity_1.HarnessAgentActivityReader,
+        worktrees_1.WorktreeService])
+], WorktreeLockVerdicts);
+//# sourceMappingURL=worktree-lock-verdicts.js.map

package/src/worktree-lock-verdicts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-lock-verdicts.js","sourceRoot":"","sources":["../../../../../packages/tooling/repo-workflow-core/src/worktree-lock-verdicts.ts"],"names":[],"mappings":"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","sourcesContent":["import { injectable, bindingScopeValues } from 'inversify';\n\nimport { AgentWorktreeLock, AgentWorktreeLockReader } from './agent-worktree-lock';\nimport {\n    AGENT_ACTIVITY_LIVE,\n    AGENT_ACTIVITY_UNKNOWN,\n    AgentActivity,\n    HarnessAgentActivityReader,\n} from './harness-agent-activity';\nimport { DeletableWorktree } from './merged-branch-verdicts';\nimport { Worktree, WorktreeService } from './worktrees';\n\n/**\n * What a `git worktree lock` DOES to a worktree's cleanup verdict.\n *\n * Separate from agent-worktree-lock.ts (which only parses a lock reason) and from\n * harness-agent-activity.ts (which only asks the harness about an agent): this is the POLICY built on\n * top of that evidence — what stops a reap, what a spared lock is allowed to CLAIM about who took it,\n * and what an overridden one has to leave on the verdict so the reaper knows to clear it.\n *\n * ─── WHY THE POLICY CHANGED ──────────────────────────────────────────────────────────────────────\n * It used to be one question, asked of the kernel: is the pid in the lock reason still running? That\n * pid is the Claude Code SESSION process, shared by every subagent, so the answer was yes for the\n * whole life of a session and every agent worktree was spared forever — nine against a cap of five,\n * with one agent running, each carrying the sentence \"that agent is working in here\" about agents\n * whose PRs had already merged. Both halves were defects: the reap never happened, and the message\n * asserted something nobody knew.\n *\n * ─── THE DECISION TABLE, AND THE ONE RULE BEHIND IT ──────────────────────────────────────────────\n *\n *      HARNESS STATE MAY ONLY VETO A REAP. IT MAY NEVER LICENSE ONE.\n *\n * The licence comes solely from the branch/commit evidence wp-cleanup already computes and already\n * gets right. So, for a lock this repo can read as the harness's own:\n *\n *   branch evidence does NOT say deletable          → SPARE. The harness is not even consulted; it\n *                                                     cannot promote a spare into a reap.\n *   deletable, but the worktree is DIRTY            → SPARE, unconditionally. Uncommitted or\n *                                                     untracked files are work no archive tag can\n *                                                     bring back. This one overrides everything,\n *                                                     including the explicit flag.\n *   deletable, clean, harness says the agent is\n *   mid-tool-call and writing                       → SPARE. The veto.\n *   deletable, clean, harness says returned /\n *   long-stale / cannot tell                        → judge it on its branch like any unlocked tree,\n *                                                     clearing the lock on the way out.\n *\n * `--ignore-stale-locks` moves ONE line of that table: it lets a locked worktree whose branch is not\n * provably dead be classified on its real branch and commit state anyway (so a zero-commit husk gets\n * reaped and a worktree holding unique commits reaches the numbered block a human can answer). It\n * does not touch the dirty rail or the live-agent veto, because neither of those is what the caller\n * is complaining about when they pass it.\n *\n * ─── SCOPE: AGENT LOCKS ONLY ─────────────────────────────────────────────────────────────────────\n * Every override applies ONLY to a lock this file can read as the harness's own. A lock reason naming\n * anything else — a human's \"dean is debugging\", or nothing at all — is still an instruction from\n * somebody, and wp-cleanup still obeys it.\n */\n\n/**\n * The exact phrase a spared \"we cannot tell\" verdict carries, exported so wp-cleanup can spot those\n * worktrees and offer the flag that judges them on their branch instead.\n *\n * ONE spelling, shared: the alternative is the caller re-deriving the same condition from a second\n * copy of the sentence, which is how a message and the code that keys off it drift apart.\n */\nexport const LOCK_LIVENESS_UNVERIFIABLE = 'whether that agent is still running cannot be verified';\n\n/**\n * The stand-in for \"the harness was never asked\", used on the paths where asking could not change the\n * answer. It is UNKNOWN, so a caller that consults it anyway still fails safe.\n */\nexport const HARNESS_NOT_CONSULTED = new AgentActivity(\n    AGENT_ACTIVITY_UNKNOWN, 'the harness was not consulted');\n\n// Data-only (per CLAUDE.md, classes for data). Everything `decide` rules on, as one value — see\n// `gather`, which is the only thing that builds one outside a test.\nexport class LockEvidence {\n    /** The lock reason verbatim, straight out of `git worktree list --porcelain`. */\n    lockReason: string;\n    /** What the harness says about the agent named in that reason, or HARNESS_NOT_CONSULTED. */\n    activity: AgentActivity;\n    /** Does `git status --porcelain` report anything, or could it not answer? Either way: held. */\n    workInFlight: boolean;\n    /** Why it is held, in git's terms — printed verbatim, because the two reasons differ for a human. */\n    workInFlightReason: string;\n    /** Is the branch this worktree holds ALREADY provably dead by the ordinary verdicts? */\n    branchDeletable: boolean;\n    /** The caller said to treat a standing agent lock as no evidence at all. */\n    ignoreStaleAgentLocks: boolean;\n\n    constructor(\n        lockReason: string,\n        activity: AgentActivity,\n        workInFlight: boolean,\n        workInFlightReason: string,\n        branchDeletable: boolean,\n        ignoreStaleAgentLocks: boolean,\n    ) {\n        this.lockReason = lockReason;\n        this.activity = activity;\n        this.workInFlight = workInFlight;\n        this.workInFlightReason = workInFlightReason;\n        this.branchDeletable = branchDeletable;\n        this.ignoreStaleAgentLocks = ignoreStaleAgentLocks;\n    }\n}\n\n/**\n * Data-only. The one verdict this file produces: spare or override, the sentence that says WHY, and\n * the agent lock the reaper will have to clear if the worktree goes.\n *\n * ONE class rather than a spare-path method and an override-path method, because the two answers are\n * mutually exclusive readings of the same evidence, and two methods is how they drift apart — which\n * is precisely what happened before: the old spared message and the old stale-lock test were computed\n * from the same pid by different code, and only one of them was ever corrected.\n */\nexport class LockDecision {\n    /** True: leave this worktree alone, and `reason` is the whole story. */\n    spare: boolean;\n    /** Spared: why it was left. Overridden: the clause appended to the branch's own verdict. */\n    reason: string;\n    /** The agent lock to clear on the way out — null when nothing may be cleared. */\n    lock: AgentWorktreeLock | null;\n\n    constructor(spare: boolean, reason: string, lock: AgentWorktreeLock | null) {\n        this.spare = spare;\n        this.reason = reason;\n        this.lock = lock;\n    }\n}\n\n@injectable(bindingScopeValues.Singleton)\nexport class WorktreeLockVerdicts {\n    // Defaulted like BranchReaper's collaborators, so the non-DI call sites can just\n    // `new WorktreeLockVerdicts()` while inversify still injects the singletons from a container.\n    constructor(\n        private readonly agentLocks: AgentWorktreeLockReader = new AgentWorktreeLockReader(),\n        private readonly harness: HarnessAgentActivityReader = new HarnessAgentActivityReader(),\n        private readonly worktrees: WorktreeService = new WorktreeService(),\n    ) {}\n\n    /**\n     * Collect what `decide` rules on — and, just as deliberately, DECLINE to collect the two\n     * expensive facts when they cannot change the answer.\n     *\n     * `git status --porcelain` and a walk of the harness's state tree are gathered only when a reap\n     * is otherwise on the table: the lock is one this repo can read as the harness's own, and either\n     * the branch is already provably dead or the caller asked for locks to be ignored. That is not an\n     * optimisation dressed up as a rule — harness state may only VETO a reap, never license one, so on\n     * a path with no reap to veto there is nothing to ask, and asking would invite a later reader to\n     * let the answer decide something.\n     */\n    gather(tree: Worktree, branchDeletable: boolean, ignoreStaleAgentLocks: boolean): LockEvidence {\n        const lock = this.agentLocks.parse(tree.lockReason);\n        if (lock === null || (!branchDeletable && !ignoreStaleAgentLocks)) {\n            return new LockEvidence(tree.lockReason, HARNESS_NOT_CONSULTED, false, '',\n                branchDeletable, ignoreStaleAgentLocks);\n        }\n        const held = this.worktrees.workInFlight(tree.path);\n        return new LockEvidence(\n            tree.lockReason, this.harness.activityOf(lock.agent, tree.path), held.held, held.reason,\n            branchDeletable, ignoreStaleAgentLocks);\n    }\n\n    /**\n     * Spare this locked worktree, or judge it on its branch like any unlocked one — with the sentence\n     * that says which piece of evidence decided it.\n     *\n     * The order below IS the decision table in the class header, in the same order, for the same\n     * reasons. Read it there.\n     */\n    decide(evidence: LockEvidence): LockDecision {\n        const lock = this.agentLocks.parse(evidence.lockReason);\n        if (lock === null) return new LockDecision(true, this.foreignLockReason(evidence.lockReason), null);\n\n        if (!evidence.branchDeletable && !evidence.ignoreStaleAgentLocks) {\n            return new LockDecision(true, this.unverifiableReason(lock), null);\n        }\n        if (evidence.workInFlight) {\n            return new LockDecision(true,\n                `locked by claude agent ${lock.agent}, and the worktree ${evidence.workInFlightReason} — `\n                + 'nothing archives that, so it is left exactly where it is', null);\n        }\n        if (evidence.activity.state === AGENT_ACTIVITY_LIVE) {\n            return new LockDecision(true,\n                `locked by claude agent ${lock.agent}, and the Claude Code harness says `\n                + `${evidence.activity.detail} — that agent is working in here`, null);\n        }\n        if (evidence.branchDeletable) {\n            return new LockDecision(false,\n                `the lock from claude agent ${lock.agent} did not stop this — the worktree is clean, its `\n                + `branch is already dead, and ${evidence.activity.detail}`, lock);\n        }\n        return new LockDecision(false,\n            `the lock from claude agent ${lock.agent} was treated as no evidence, as asked`, lock);\n    }\n\n    /**\n     * WHY a locked worktree was left alone when the lock is NOT the harness's — reporting what the\n     * reason SAYS, never who we imagine wrote it.\n     *\n     * This used to read `locked by a human — do not touch` for every lock in existence, which named an\n     * actor nothing in the evidence identifies: the lock reason is the ONLY thing we have, a human may\n     * have locked it, so may some other tool, and asserting either is the same defect whichever way it\n     * lands.\n     */\n    private foreignLockReason(lockReason: string): string {\n        if (lockReason === '') {\n            return 'locked with no reason recorded — nothing says who locked it or why, so it is left alone';\n        }\n        return `locked, reason \"${lockReason}\" — that is not a claude agent lock, so who locked it `\n            + 'is unknown; left alone';\n    }\n\n    /**\n     * The sentence that replaced \"pid N still running — that agent is working in here\".\n     *\n     * It says only what is known: which agent the reason names, that the pid in it cannot answer the\n     * question because it is the shared session process, and that nothing else made the worktree\n     * provably dead either. No claim about anybody working — and no claim about the harness, which on\n     * this path was deliberately never asked, because its answer could not have changed the outcome.\n     */\n    private unverifiableReason(lock: AgentWorktreeLock): string {\n        return `locked by claude agent ${lock.agent}; ${LOCK_LIVENESS_UNVERIFIABLE} — the recorded pid `\n            + `${String(lock.pid)} is the shared Claude Code session process, not the agent's. Its branch `\n            + 'is not provably dead either, so it is left alone';\n    }\n\n    /**\n     * Stamp an overridden verdict with the lock the reap must CLEAR: git refuses to remove a locked\n     * worktree, and the reason has to say why a lock is being overridden at all.\n     *\n     * Applied to every verdict the fall-through can produce, not just the deletable one, because the\n     * spared cases are exactly where a human reads the reason and asks \"wasn't that locked?\".\n     */\n    annotate(verdict: DeletableWorktree, decision: LockDecision | null): DeletableWorktree {\n        if (decision === null || decision.spare || decision.lock === null) return verdict;\n        verdict.unlockBeforeRemove = true;\n        verdict.reason = `${verdict.reason}; ${decision.reason}`;\n        return verdict;\n    }\n}\n"]}

package/src/worktree-reaper.d.ts

@@ -0,0 +1,116 @@
+import { BranchArchiver } from './branch-archiver';
+import { BranchMutationLog, MutationVerb } from './branch-mutation-log';
+import { DeletableWorktree } from './merged-branch-verdicts';
+import { WorktreeService } from './worktrees';
+/**
+ * The EXECUTOR for the dead-WORKTREE verdicts that merged-branches.ts has been computing all along.
+ *
+ * WHY this exists: `DeletableWorktree` was designed for reaping — it carries `path` (what
+ * `git worktree remove` takes) AND `branch` (what `git branch -D` takes afterwards) precisely because
+ * a reap is always those two steps in that order. The reaping was then never wired up. The verdicts
+ * had exactly one consumer, branch-creation-guard, which used them only to BLOCK: at the worktree cap
+ * it printed the reap commands and refused to create the next worktree. Nothing ever ran them.
+ *
+ * That composes into a deadlock, not merely a missing feature. A merged worktree HOLDS its branch, so
+ * the branch lands in `keep` with "checked out in worktree '<path>' — remove that worktree before
+ * deleting the branch". Nothing removes the worktree. Both accumulate forever, and the guard's only
+ * remaining advice is to loosen its own cap — which is the failure the cap exists to prevent. Observed
+ * twice in one day: a `wp-cleanup` run that spared three worktree-held branches with that exact line,
+ * and another that spared seven.
+ *
+ * THE ORDER IS FIXED AND LOAD-BEARING: archive the branch as a tag → `git worktree remove <path>` →
+ * `git branch -D <branch>`.
+ *  - Archive FIRST, and if it fails nothing is deleted. Same rule BranchArchiver already enforces for
+ *    branches: a branch we could not tag is a branch whose only copy would be the reflog.
+ *  - Remove the worktree BEFORE the branch, because git flatly refuses to delete a branch that is
+ *    still checked out somewhere.
+ *
+ * AND NEVER `--force`. Git refuses to remove a worktree with uncommitted changes or untracked files,
+ * and that refusal is the entire safety property here: a worktree removal deletes real FILES, not just
+ * a ref, and an untracked file is by definition something no archive tag captured. A failed removal is
+ * reported and moved past, exactly as a failed branch delete already is.
+ */
+export declare class ReapedWorktree {
+    path: string;
+    branch: string;
+    sha: string;
+    reason: string;
+    pr: number;
+    ok: boolean;
+    error: string;
+    archiveTag: string;
+    /**
+     * Did the BRANCH delete also succeed? A worktree removal that succeeds while the branch delete
+     * fails is a real, reportable half-state — the directory is gone, the branch is still there — and
+     * collapsing it into `ok` would hide it. `ok` means the DIRECTORY is gone; this means the pair is.
+     */
+    branchDeleted: boolean;
+    constructor(treePath: string, branch: string, sha: string, reason: string, pr: number, ok: boolean, error: string);
+}
+/**
+ * The outcome of one worktree reap. `spared` carries the worktrees we refused to touch, each with its
+ * reason, for the same reason ReapResult does: a cleanup silent about what it did NOT remove reads as
+ * "there was nothing else", when those are exactly the ones only a human can rule on.
+ */
+export declare class WorktreeReapResult {
+    reaped: ReapedWorktree[];
+    failed: ReapedWorktree[];
+    spared: DeletableWorktree[];
+    constructor(reaped: ReapedWorktree[], failed: ReapedWorktree[], spared: DeletableWorktree[]);
+}
+export declare class WorktreeReaper {
+    private readonly worktrees;
+    private readonly mutationLog;
+    private readonly archiver;
+    constructor(worktrees?: WorktreeService, mutationLog?: BranchMutationLog, archiver?: BranchArchiver);
+    /**
+     * Reap every worktree in `targets`, skipping any the safety rails refuse.
+     *
+     * `cwd` is passed in rather than read from `process.cwd()` here so the "never remove the tree I am
+     * standing in" rule is testable and so a caller running from a subdirectory still gets the right
+     * answer — the containing WORKTREE is what matters, not the exact directory.
+     *
+     * `targets` is caller-chosen on purpose. wp-cleanup passes the provably-dead ones unattended, and
+     * passes human-approved probably-dead ones on a second call. The safety rails below apply to both:
+     * no answer at a prompt can authorise removing your own cwd or the primary clone.
+     */
+    reapWorktrees(repoRoot: string, cwd: string, verb: MutationVerb, targets: DeletableWorktree[], retention?: string): WorktreeReapResult;
+    /**
+     * The two directories that must never be removed, resolved to absolute paths so a relative
+     * `../foo` in a verdict can still be compared against them.
+     *
+     *  - THE PRIMARY CLONE. It owns `.git`; `git worktree remove` cannot take it, and a caller who
+     *    somehow got it into a target list has a bug we must not execute.
+     *  - THE TREE WE ARE STANDING IN. Removing your own cwd mid-command deletes the files underneath
+     *    the running process — including, when the tooling is invoked by an agent, the checkout the
+     *    agent's next tool call will try to read. merged-branches.ts already declines to mark it
+     *    deletable; this is the second, independent line, because the caller supplies the list.
+     */
+    private protectedPaths;
+    private currentTree;
+    private refuseReason;
+    /**
+     * One worktree: ARCHIVE the branch, REMOVE the directory, then DELETE the branch — and stop at the
+     * first step that fails.
+     *
+     * The prunable case is genuinely different and is why the classification token rides along on the
+     * verdict: the directory is ALREADY gone, so `git worktree remove` fails on it and the reap is
+     * `git worktree prune`. There is also nothing to archive from a directory that no longer exists —
+     * the branch itself is still archived, since it may well still hold the only copy of some work.
+     */
+    private removeOne;
+    private archiveBranch;
+    private archiveFailed;
+    /**
+     * git refused to remove the directory — nearly always because it holds uncommitted changes or
+     * untracked files. Reported with git's own words and moved past. We do NOT retry with `--force`:
+     * an untracked file is work no archive tag captured, and `--force` is how a cleanup command turns
+     * into a data-loss command. The branch is left alone too, since it is still checked out here.
+     */
+    private removalFailed;
+    private log;
+    /** The literal command that puts BOTH the directory and the branch back. */
+    restoreCommand(target: ReapedWorktree): string;
+    private revParse;
+    private capture;
+}