@webpieces/repo-workflow-core 0.0.1

package/src/review-identity-stamp.d.ts

@@ -0,0 +1,82 @@
+import { AtomicFile } from '@webpieces/tooling-common';
+import { DotWebpieces } from '@webpieces/tooling-common';
+/** The ONE sanctioned way a reviewer submits a checklist verdict (issue #863). */
+export declare const WRITE_REVIEW_BIN = "wp-write-review";
+/** The flag that names the checklist a `wp-write-review` call submits for. */
+export declare const WRITE_REVIEW_CHECKLIST_FLAG = "--checklist";
+/** Where the stamps live, beneath this worktree's tooling-owned state dir (never the AI-writable one). */
+export declare const REVIEW_STAMP_DIR = "review-stamps";
+/**
+ * How long a stamp stays usable. The hook writes it a few milliseconds before the harness starts the very
+ * Bash command it stamped, so anything older than this is left over from a call that never reached the bin
+ * — and must not be available to lend its identity to a later caller.
+ */
+export declare const REVIEW_STAMP_MAX_AGE_MS = 120000;
+/**
+ * WHO is running a `pnpm wp-write-review` Bash call, as the HARNESS reported it to the PreToolUse hook.
+ * Data-only (per CLAUDE.md), and its field names are the JSON keys on disk.
+ *
+ * WHY a hook stamp and not the environment (issue #863). A Bash-invoked bin sees only its env, and the env
+ * cannot answer "is this a subagent?" in either harness:
+ *   - Claude Code exports `CLAUDE_CODE_SESSION_ID`, which is the PARENT session's id in a subagent too, and
+ *     no agent id at all — a reviewer and its coordinator have byte-identical identity env.
+ *   - Codex exports `CODEX_SESSION_ID` / `CODEX_THREAD_ID`, and nothing documents (or has been measured to
+ *     show) that a spawned subagent gets a thread id of its own rather than inheriting the coordinator's.
+ * The hook payload DOES carry the answer, in both harnesses, on the same key: `agent_id` is empty for the
+ * main loop and populated for a subagent. So the hook — which sees every Bash call before it runs — writes
+ * that identity here for each checklist the command names, and the bin consumes it.
+ *
+ * NOT tamper-proof, and not claimed to be: an agent can write this file by hand. It moves forging a verdict
+ * from "write one JSON file" (what a coordinator did on two merged PRs) to a deliberate, auditable forgery of
+ * tooling state outside the AI-writable dir — the same bar SubagentProvenanceService sets.
+ */
+export declare class ReviewIdentityStamp {
+    checklistId: string;
+    aiType: string;
+    sessionId: string;
+    agentId: string;
+    agentType: string;
+    cwd: string;
+    stampedAt: string;
+    constructor(checklistId: string, aiType: string, sessionId: string, agentId: string, agentType: string, cwd: string, stampedAt: string);
+}
+/**
+ * Writes (from the PreToolUse hook) and consumes (from `wp-write-review`) {@link ReviewIdentityStamp}s.
+ *
+ * Both ends resolve the path from their OWN working directory through {@link DotWebpieces.local}, which is
+ * keyed by git's answer for that tree — so the hook's payload cwd and the bin's process cwd land on the same
+ * file for the same worktree, and two worktrees never share a stamp.
+ *
+ * `@injectable(bindingScopeValues.Singleton)` so it is injected by type; {@link reviewIdentityStamps} is the
+ * instance the dependency-free hook adapter uses.
+ */
+export declare class ReviewIdentityStampService {
+    private readonly dotDir;
+    private readonly atomicFile;
+    constructor(dotDir?: DotWebpieces, atomicFile?: AtomicFile);
+    /**
+     * The checklist ids a Bash command submits verdicts for, or [] when it does not invoke the bin at all.
+     * Every `--checklist <id>` / `--checklist=<id>` is returned, because one reviewer covering several
+     * checklists may chain several submissions into one command.
+     */
+    invokedChecklists(command: string): string[];
+    /**
+     * True when the stamp names the COORDINATING agent rather than a subagent: no agent id, or an agent id
+     * equal to the session id (a harness that fills the main loop's agent id with the session id instead of
+     * leaving it empty). The coordinator may never submit a reviewer's verdict — that is the whole point.
+     */
+    isCoordinator(stamp: ReviewIdentityStamp): boolean;
+    stampPath(startDir: string, checklistId: string): string;
+    /** Best-effort: a stamp that cannot be written makes the bin refuse, which is the safe direction. */
+    write(startDir: string, stamp: ReviewIdentityStamp): void;
+    /**
+     * Read AND delete the stamp for one checklist. null when there is none, it is unreadable, or it is
+     * older than {@link REVIEW_STAMP_MAX_AGE_MS}. Deleted on read so one hook call vouches for one
+     * submission; a delete that fails (a sandbox that denies it) is harmless, because age bounds it anyway.
+     */
+    take(startDir: string, checklistId: string, nowMs?: number): ReviewIdentityStamp | null;
+    private read;
+    private remove;
+}
+/** The instance the hook adapter uses — it runs without a DI container (see hook-core.ts). */
+export declare const reviewIdentityStamps: ReviewIdentityStampService;

package/src/review-identity-stamp.js

@@ -0,0 +1,172 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reviewIdentityStamps = exports.ReviewIdentityStampService = exports.ReviewIdentityStamp = exports.REVIEW_STAMP_MAX_AGE_MS = exports.REVIEW_STAMP_DIR = exports.WRITE_REVIEW_CHECKLIST_FLAG = exports.WRITE_REVIEW_BIN = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const inversify_1 = require("inversify");
+const tooling_common_1 = require("@webpieces/tooling-common");
+const tooling_common_2 = require("@webpieces/tooling-common");
+const to_error_1 = require("@webpieces/tooling-common/to-error");
+/** The ONE sanctioned way a reviewer submits a checklist verdict (issue #863). */
+exports.WRITE_REVIEW_BIN = 'wp-write-review';
+/** The flag that names the checklist a `wp-write-review` call submits for. */
+exports.WRITE_REVIEW_CHECKLIST_FLAG = '--checklist';
+/** Where the stamps live, beneath this worktree's tooling-owned state dir (never the AI-writable one). */
+exports.REVIEW_STAMP_DIR = 'review-stamps';
+/**
+ * How long a stamp stays usable. The hook writes it a few milliseconds before the harness starts the very
+ * Bash command it stamped, so anything older than this is left over from a call that never reached the bin
+ * — and must not be available to lend its identity to a later caller.
+ */
+exports.REVIEW_STAMP_MAX_AGE_MS = 120_000;
+/**
+ * WHO is running a `pnpm wp-write-review` Bash call, as the HARNESS reported it to the PreToolUse hook.
+ * Data-only (per CLAUDE.md), and its field names are the JSON keys on disk.
+ *
+ * WHY a hook stamp and not the environment (issue #863). A Bash-invoked bin sees only its env, and the env
+ * cannot answer "is this a subagent?" in either harness:
+ *   - Claude Code exports `CLAUDE_CODE_SESSION_ID`, which is the PARENT session's id in a subagent too, and
+ *     no agent id at all — a reviewer and its coordinator have byte-identical identity env.
+ *   - Codex exports `CODEX_SESSION_ID` / `CODEX_THREAD_ID`, and nothing documents (or has been measured to
+ *     show) that a spawned subagent gets a thread id of its own rather than inheriting the coordinator's.
+ * The hook payload DOES carry the answer, in both harnesses, on the same key: `agent_id` is empty for the
+ * main loop and populated for a subagent. So the hook — which sees every Bash call before it runs — writes
+ * that identity here for each checklist the command names, and the bin consumes it.
+ *
+ * NOT tamper-proof, and not claimed to be: an agent can write this file by hand. It moves forging a verdict
+ * from "write one JSON file" (what a coordinator did on two merged PRs) to a deliberate, auditable forgery of
+ * tooling state outside the AI-writable dir — the same bar SubagentProvenanceService sets.
+ */
+class ReviewIdentityStamp {
+    checklistId;
+    aiType; // 'claude-code' | 'codex' — the adapter's answer, never the model's
+    sessionId;
+    agentId; // '' ⇒ the MAIN loop, i.e. the coordinating agent
+    agentType;
+    cwd;
+    stampedAt; // ISO
+    // eslint-disable-next-line @typescript-eslint/max-params
+    constructor(checklistId, aiType, sessionId, agentId, agentType, cwd, stampedAt) {
+        this.checklistId = checklistId;
+        this.aiType = aiType;
+        this.sessionId = sessionId;
+        this.agentId = agentId;
+        this.agentType = agentType;
+        this.cwd = cwd;
+        this.stampedAt = stampedAt;
+    }
+}
+exports.ReviewIdentityStamp = ReviewIdentityStamp;
+/**
+ * Writes (from the PreToolUse hook) and consumes (from `wp-write-review`) {@link ReviewIdentityStamp}s.
+ *
+ * Both ends resolve the path from their OWN working directory through {@link DotWebpieces.local}, which is
+ * keyed by git's answer for that tree — so the hook's payload cwd and the bin's process cwd land on the same
+ * file for the same worktree, and two worktrees never share a stamp.
+ *
+ * `@injectable(bindingScopeValues.Singleton)` so it is injected by type; {@link reviewIdentityStamps} is the
+ * instance the dependency-free hook adapter uses.
+ */
+let ReviewIdentityStampService = class ReviewIdentityStampService {
+    dotDir;
+    atomicFile;
+    constructor(dotDir = tooling_common_2.dotWebpieces, atomicFile = new tooling_common_1.AtomicFile()) {
+        this.dotDir = dotDir;
+        this.atomicFile = atomicFile;
+    }
+    /**
+     * The checklist ids a Bash command submits verdicts for, or [] when it does not invoke the bin at all.
+     * Every `--checklist <id>` / `--checklist=<id>` is returned, because one reviewer covering several
+     * checklists may chain several submissions into one command.
+     */
+    invokedChecklists(command) {
+        if (!new RegExp(`\\b${exports.WRITE_REVIEW_BIN}\\b`).test(command))
+            return [];
+        const ids = [];
+        const flag = /--checklist(?:=|\s+)(["']?)([A-Za-z0-9._-]+)\1/g;
+        let match = flag.exec(command);
+        while (match !== null) {
+            if (!ids.includes(match[2]))
+                ids.push(match[2]);
+            match = flag.exec(command);
+        }
+        return ids;
+    }
+    /**
+     * True when the stamp names the COORDINATING agent rather than a subagent: no agent id, or an agent id
+     * equal to the session id (a harness that fills the main loop's agent id with the session id instead of
+     * leaving it empty). The coordinator may never submit a reviewer's verdict — that is the whole point.
+     */
+    isCoordinator(stamp) {
+        return stamp.agentId.trim() === '' || stamp.agentId === stamp.sessionId;
+    }
+    stampPath(startDir, checklistId) {
+        return this.dotDir.localFile(startDir, exports.REVIEW_STAMP_DIR, `${checklistId.replace(/[^A-Za-z0-9._-]/g, '_')}.json`);
+    }
+    /** Best-effort: a stamp that cannot be written makes the bin refuse, which is the safe direction. */
+    write(startDir, stamp) {
+        // webpieces-disable no-unmanaged-exceptions -- chokepoint: the hook must never fail a tool call over its own bookkeeping
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            this.atomicFile.writeJsonAtomic(this.stampPath(startDir, stamp.checklistId), stamp);
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            void error;
+        }
+    }
+    /**
+     * Read AND delete the stamp for one checklist. null when there is none, it is unreadable, or it is
+     * older than {@link REVIEW_STAMP_MAX_AGE_MS}. Deleted on read so one hook call vouches for one
+     * submission; a delete that fails (a sandbox that denies it) is harmless, because age bounds it anyway.
+     */
+    take(startDir, checklistId, nowMs = Date.now()) {
+        const file = this.stampPath(startDir, checklistId);
+        const stamp = this.read(file);
+        this.remove(file);
+        if (stamp === null || stamp.checklistId !== checklistId)
+            return null;
+        const age = nowMs - Date.parse(stamp.stampedAt);
+        if (!Number.isFinite(age) || age < 0 || age > exports.REVIEW_STAMP_MAX_AGE_MS)
+            return null;
+        return stamp;
+    }
+    read(file) {
+        if (!fs.existsSync(file))
+            return null;
+        // webpieces-disable no-unmanaged-exceptions -- chokepoint: an unreadable stamp is no stamp
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            // webpieces-disable no-any-unknown -- opaque parsed JSON, narrowed field-by-field below
+            const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+            // webpieces-disable no-any-unknown -- one opaque JSON value, narrowed to a string
+            const str = (v) => (typeof v === 'string' ? v : '');
+            return new ReviewIdentityStamp(str(raw['checklistId']), str(raw['aiType']), str(raw['sessionId']), str(raw['agentId']), str(raw['agentType']), str(raw['cwd']), str(raw['stampedAt']));
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            void error;
+            return null;
+        }
+    }
+    remove(file) {
+        // webpieces-disable no-unmanaged-exceptions -- chokepoint: a stamp that cannot be deleted still expires
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            fs.rmSync(file, { force: true });
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            void error;
+        }
+    }
+};
+exports.ReviewIdentityStampService = ReviewIdentityStampService;
+exports.ReviewIdentityStampService = ReviewIdentityStampService = tslib_1.__decorate([
+    (0, inversify_1.injectable)(inversify_1.bindingScopeValues.Singleton),
+    tslib_1.__metadata("design:paramtypes", [tooling_common_2.DotWebpieces,
+        tooling_common_1.AtomicFile])
+], ReviewIdentityStampService);
+/** The instance the hook adapter uses — it runs without a DI container (see hook-core.ts). */
+exports.reviewIdentityStamps = new ReviewIdentityStampService();
+//# sourceMappingURL=review-identity-stamp.js.map

package/src/review-identity-stamp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"review-identity-stamp.js","sourceRoot":"","sources":["../../../../../packages/tooling/repo-workflow-core/src/review-identity-stamp.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'fs';\nimport { injectable, bindingScopeValues } from 'inversify';\nimport { AtomicFile } from '@webpieces/tooling-common';\nimport { DotWebpieces, dotWebpieces } from '@webpieces/tooling-common';\nimport { toError } from '@webpieces/tooling-common/to-error';\n\n/** The ONE sanctioned way a reviewer submits a checklist verdict (issue #863). */\nexport const WRITE_REVIEW_BIN = 'wp-write-review';\n\n/** The flag that names the checklist a `wp-write-review` call submits for. */\nexport const WRITE_REVIEW_CHECKLIST_FLAG = '--checklist';\n\n/** Where the stamps live, beneath this worktree's tooling-owned state dir (never the AI-writable one). */\nexport const REVIEW_STAMP_DIR = 'review-stamps';\n\n/**\n * How long a stamp stays usable. The hook writes it a few milliseconds before the harness starts the very\n * Bash command it stamped, so anything older than this is left over from a call that never reached the bin\n * — and must not be available to lend its identity to a later caller.\n */\nexport const REVIEW_STAMP_MAX_AGE_MS = 120_000;\n\n/**\n * WHO is running a `pnpm wp-write-review` Bash call, as the HARNESS reported it to the PreToolUse hook.\n * Data-only (per CLAUDE.md), and its field names are the JSON keys on disk.\n *\n * WHY a hook stamp and not the environment (issue #863). A Bash-invoked bin sees only its env, and the env\n * cannot answer \"is this a subagent?\" in either harness:\n *   - Claude Code exports `CLAUDE_CODE_SESSION_ID`, which is the PARENT session's id in a subagent too, and\n *     no agent id at all — a reviewer and its coordinator have byte-identical identity env.\n *   - Codex exports `CODEX_SESSION_ID` / `CODEX_THREAD_ID`, and nothing documents (or has been measured to\n *     show) that a spawned subagent gets a thread id of its own rather than inheriting the coordinator's.\n * The hook payload DOES carry the answer, in both harnesses, on the same key: `agent_id` is empty for the\n * main loop and populated for a subagent. So the hook — which sees every Bash call before it runs — writes\n * that identity here for each checklist the command names, and the bin consumes it.\n *\n * NOT tamper-proof, and not claimed to be: an agent can write this file by hand. It moves forging a verdict\n * from \"write one JSON file\" (what a coordinator did on two merged PRs) to a deliberate, auditable forgery of\n * tooling state outside the AI-writable dir — the same bar SubagentProvenanceService sets.\n */\nexport class ReviewIdentityStamp {\n    checklistId: string;\n    aiType: string;       // 'claude-code' | 'codex' — the adapter's answer, never the model's\n    sessionId: string;\n    agentId: string;      // '' ⇒ the MAIN loop, i.e. the coordinating agent\n    agentType: string;\n    cwd: string;\n    stampedAt: string;    // ISO\n\n    // eslint-disable-next-line @typescript-eslint/max-params\n    constructor(checklistId: string, aiType: string, sessionId: string, agentId: string, agentType: string, cwd: string, stampedAt: string) {\n        this.checklistId = checklistId;\n        this.aiType = aiType;\n        this.sessionId = sessionId;\n        this.agentId = agentId;\n        this.agentType = agentType;\n        this.cwd = cwd;\n        this.stampedAt = stampedAt;\n    }\n}\n\n/**\n * Writes (from the PreToolUse hook) and consumes (from `wp-write-review`) {@link ReviewIdentityStamp}s.\n *\n * Both ends resolve the path from their OWN working directory through {@link DotWebpieces.local}, which is\n * keyed by git's answer for that tree — so the hook's payload cwd and the bin's process cwd land on the same\n * file for the same worktree, and two worktrees never share a stamp.\n *\n * `@injectable(bindingScopeValues.Singleton)` so it is injected by type; {@link reviewIdentityStamps} is the\n * instance the dependency-free hook adapter uses.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class ReviewIdentityStampService {\n    constructor(\n        private readonly dotDir: DotWebpieces = dotWebpieces,\n        private readonly atomicFile: AtomicFile = new AtomicFile(),\n    ) {}\n\n    /**\n     * The checklist ids a Bash command submits verdicts for, or [] when it does not invoke the bin at all.\n     * Every `--checklist <id>` / `--checklist=<id>` is returned, because one reviewer covering several\n     * checklists may chain several submissions into one command.\n     */\n    invokedChecklists(command: string): string[] {\n        if (!new RegExp(`\\\\b${WRITE_REVIEW_BIN}\\\\b`).test(command)) return [];\n        const ids: string[] = [];\n        const flag = /--checklist(?:=|\\s+)([\"']?)([A-Za-z0-9._-]+)\\1/g;\n        let match = flag.exec(command);\n        while (match !== null) {\n            if (!ids.includes(match[2])) ids.push(match[2]);\n            match = flag.exec(command);\n        }\n        return ids;\n    }\n\n    /**\n     * True when the stamp names the COORDINATING agent rather than a subagent: no agent id, or an agent id\n     * equal to the session id (a harness that fills the main loop's agent id with the session id instead of\n     * leaving it empty). The coordinator may never submit a reviewer's verdict — that is the whole point.\n     */\n    isCoordinator(stamp: ReviewIdentityStamp): boolean {\n        return stamp.agentId.trim() === '' || stamp.agentId === stamp.sessionId;\n    }\n\n    stampPath(startDir: string, checklistId: string): string {\n        return this.dotDir.localFile(startDir, REVIEW_STAMP_DIR, `${checklistId.replace(/[^A-Za-z0-9._-]/g, '_')}.json`);\n    }\n\n    /** Best-effort: a stamp that cannot be written makes the bin refuse, which is the safe direction. */\n    write(startDir: string, stamp: ReviewIdentityStamp): void {\n        // webpieces-disable no-unmanaged-exceptions -- chokepoint: the hook must never fail a tool call over its own bookkeeping\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            this.atomicFile.writeJsonAtomic(this.stampPath(startDir, stamp.checklistId), stamp);\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n        }\n    }\n\n    /**\n     * Read AND delete the stamp for one checklist. null when there is none, it is unreadable, or it is\n     * older than {@link REVIEW_STAMP_MAX_AGE_MS}. Deleted on read so one hook call vouches for one\n     * submission; a delete that fails (a sandbox that denies it) is harmless, because age bounds it anyway.\n     */\n    take(startDir: string, checklistId: string, nowMs: number = Date.now()): ReviewIdentityStamp | null {\n        const file = this.stampPath(startDir, checklistId);\n        const stamp = this.read(file);\n        this.remove(file);\n        if (stamp === null || stamp.checklistId !== checklistId) return null;\n        const age = nowMs - Date.parse(stamp.stampedAt);\n        if (!Number.isFinite(age) || age < 0 || age > REVIEW_STAMP_MAX_AGE_MS) return null;\n        return stamp;\n    }\n\n    private read(file: string): ReviewIdentityStamp | null {\n        if (!fs.existsSync(file)) return null;\n        // webpieces-disable no-unmanaged-exceptions -- chokepoint: an unreadable stamp is no stamp\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            // webpieces-disable no-any-unknown -- opaque parsed JSON, narrowed field-by-field below\n            const raw = JSON.parse(fs.readFileSync(file, 'utf8')) as Record<string, unknown>;\n            // webpieces-disable no-any-unknown -- one opaque JSON value, narrowed to a string\n            const str = (v: unknown): string => (typeof v === 'string' ? v : '');\n            return new ReviewIdentityStamp(\n                str(raw['checklistId']), str(raw['aiType']), str(raw['sessionId']), str(raw['agentId']),\n                str(raw['agentType']), str(raw['cwd']), str(raw['stampedAt']));\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return null;\n        }\n    }\n\n    private remove(file: string): void {\n        // webpieces-disable no-unmanaged-exceptions -- chokepoint: a stamp that cannot be deleted still expires\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            fs.rmSync(file, { force: true });\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n        }\n    }\n}\n\n/** The instance the hook adapter uses — it runs without a DI container (see hook-core.ts). */\nexport const reviewIdentityStamps = new ReviewIdentityStampService();\n"]}

package/src/worktree-lock-verdicts.d.ts

@@ -0,0 +1,149 @@
+import { AgentWorktreeLock, AgentWorktreeLockReader } from './agent-worktree-lock';
+import { AgentActivity, HarnessAgentActivityReader } from './harness-agent-activity';
+import { DeletableWorktree } from './merged-branch-verdicts';
+import { Worktree, WorktreeService } from './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.
+ */
+export declare const 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.
+ */
+export declare const HARNESS_NOT_CONSULTED: AgentActivity;
+export declare class LockEvidence {
+    /** The lock reason verbatim, straight out of `git worktree list --porcelain`. */
+    lockReason: string;
+    /** What the harness says about the agent named in that reason, or HARNESS_NOT_CONSULTED. */
+    activity: AgentActivity;
+    /** Does `git status --porcelain` report anything, or could it not answer? Either way: held. */
+    workInFlight: boolean;
+    /** Why it is held, in git's terms — printed verbatim, because the two reasons differ for a human. */
+    workInFlightReason: string;
+    /** Is the branch this worktree holds ALREADY provably dead by the ordinary verdicts? */
+    branchDeletable: boolean;
+    /** The caller said to treat a standing agent lock as no evidence at all. */
+    ignoreStaleAgentLocks: boolean;
+    constructor(lockReason: string, activity: AgentActivity, workInFlight: boolean, workInFlightReason: string, branchDeletable: boolean, ignoreStaleAgentLocks: boolean);
+}
+/**
+ * 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.
+ */
+export declare class LockDecision {
+    /** True: leave this worktree alone, and `reason` is the whole story. */
+    spare: boolean;
+    /** Spared: why it was left. Overridden: the clause appended to the branch's own verdict. */
+    reason: string;
+    /** The agent lock to clear on the way out — null when nothing may be cleared. */
+    lock: AgentWorktreeLock | null;
+    constructor(spare: boolean, reason: string, lock: AgentWorktreeLock | null);
+}
+export declare class WorktreeLockVerdicts {
+    private readonly agentLocks;
+    private readonly harness;
+    private readonly worktrees;
+    constructor(agentLocks?: AgentWorktreeLockReader, harness?: HarnessAgentActivityReader, worktrees?: WorktreeService);
+    /**
+     * 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: Worktree, branchDeletable: boolean, ignoreStaleAgentLocks: boolean): LockEvidence;
+    /**
+     * 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: LockEvidence): LockDecision;
+    /**
+     * 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.
+     */
+    private foreignLockReason;
+    /**
+     * 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.
+     */
+    private unverifiableReason;
+    /**
+     * 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: DeletableWorktree, decision: LockDecision | null): DeletableWorktree;
+}