@webpieces/rules-config 0.4.497 → 0.4.499

package/src/subagent-provenance.d.ts

@@ -4,7 +4,32 @@ export declare const PROVENANCE_SKIPPED = "skipped";
 export declare class ProvenanceResult {
     status: string;
     detail: string;
-    constructor(status: string, detail: string);
+    agentIds: Record<string, string>;
+    constructor(status: string, detail: string, agentIds?: Record<string, string>);
+}
+/**
+ * What ONE credited reviewer actually DID, read from its own transcript. Data-only (per CLAUDE.md).
+ *
+ * `verifyDistinct` answers "did a reviewer of this type run?" — an INTEGRITY question, and it blocks. This
+ * answers "did it look at the change?" — a QUALITY question, and it only warns. The distinction is
+ * deliberate; see {@link SubagentProvenanceService.evidenceFor}.
+ */
+export declare class ReviewerEvidence {
+    agentType: string;
+    agentId: string;
+    readDiff: boolean;
+    readDoc: boolean;
+    toolCallCount: number;
+    offRepoSearches: number;
+    constructor(agentType: string, agentId: string, readDiff?: boolean, readDoc?: boolean, toolCallCount?: number, offRepoSearches?: number);
+}
+/** What to look for when reading reviewer transcripts. Data-only — avoids a 5-param method. */
+export declare class EvidenceRequest {
+    branch: string;
+    agentIds: Record<string, string>;
+    diffDir: string;
+    docPaths: Record<string, string>;
+    constructor(branch: string, agentIds: Record<string, string>, diffDir?: string, docPaths?: Record<string, string>);
 }
 /**
  * Verifies — from the Claude Code harness's OWN artifacts, never from anything the model asserts — that
@@ -28,6 +53,35 @@ export declare class ProvenanceResult {
 export declare class SubagentProvenanceService {
     verify(expectedAgentType: string, branch: string): ProvenanceResult;
     verifyDistinct(expectedAgentTypes: readonly string[], branch: string): ProvenanceResult;
+    /**
+     * What each credited reviewer actually READ, from its own transcript.
+     *
+     * `verifyDistinct` proves a reviewer of the right type RAN. It cannot tell a reviewer that read the diff
+     * and thought about it from one that wrote a verdict having opened nothing. This closes that gap — and
+     * the motivating case is real: one reviewer spent 14 of 26 tool calls grepping `node_modules` because
+     * nothing had told it where anything was, which `offRepoSearches` now makes visible.
+     *
+     * WARNING-ONLY by default, for three reasons, and `requireDiffEvidence` must stay opt-in until at least
+     * one repo has watched it:
+     *   1. The transcript layout is undocumented Claude Code internals. A format change would wedge every
+     *      consumer's PR with no self-service recovery — `sidechainOnBranch` is already lenient for exactly
+     *      this reason, and blocking on a richer read of the same files would be less safe, not more.
+     *   2. A reviewer can legitimately receive the diff another way (inlined into its prompt, say).
+     *   3. verifyDistinct is the INTEGRITY signal and rightly blocks; this is a QUALITY signal. Conflating
+     *      them would let a transcript-parsing quirk refuse a PR that a real reviewer really did review.
+     *
+     * Returns [] outside a Claude Code session, matching verify/verifyDistinct's SKIP behavior.
+     */
+    evidenceFor(request: EvidenceRequest): ReviewerEvidence[];
+    private evidenceFromTranscript;
+    private transcriptPath;
+    /**
+     * Every tool_use input in a transcript, JSON-stringified. Stringified rather than walked field-by-field
+     * because the shape differs per tool (Read takes file_path, Bash takes command, Grep takes path) and a
+     * substring test over the serialized input is both simpler and robust to a tool we have not seen.
+     */
+    private toolInputsOf;
+    private mentions;
     private inClaudeSession;
     private skipped;
     private findMatchingAgentId;

package/src/subagent-provenance.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SubagentProvenanceService = exports.ProvenanceResult = exports.PROVENANCE_SKIPPED = exports.PROVENANCE_MISSING = exports.PROVENANCE_OK = void 0;
+exports.SubagentProvenanceService = exports.EvidenceRequest = exports.ReviewerEvidence = exports.ProvenanceResult = exports.PROVENANCE_SKIPPED = exports.PROVENANCE_MISSING = exports.PROVENANCE_OK = void 0;
 const tslib_1 = require("tslib");
 const fs = tslib_1.__importStar(require("fs"));
 const path = tslib_1.__importStar(require("path"));
@@ -14,12 +14,55 @@ exports.PROVENANCE_SKIPPED = 'skipped'; // no CLAUDE_CODE_SESSION_ID (plain term
 class ProvenanceResult {
     status; // PROVENANCE_OK | PROVENANCE_MISSING | PROVENANCE_SKIPPED
     detail; // human-readable explanation for the warning/error/dashboard
-    constructor(status, detail) {
+    // agentIds credited, keyed by agentType, so an evidence pass does not re-scan to find them again.
+    agentIds;
+    constructor(status, detail, agentIds = {}) {
         this.status = status;
         this.detail = detail;
+        this.agentIds = agentIds;
     }
 }
 exports.ProvenanceResult = ProvenanceResult;
+/**
+ * What ONE credited reviewer actually DID, read from its own transcript. Data-only (per CLAUDE.md).
+ *
+ * `verifyDistinct` answers "did a reviewer of this type run?" — an INTEGRITY question, and it blocks. This
+ * answers "did it look at the change?" — a QUALITY question, and it only warns. The distinction is
+ * deliberate; see {@link SubagentProvenanceService.evidenceFor}.
+ */
+class ReviewerEvidence {
+    agentType;
+    agentId;
+    readDiff; // opened the materialized diff dir (or its own instructions file)
+    readDoc; // opened its checklist's guidance doc
+    toolCallCount;
+    offRepoSearches; // tool calls that reached into node_modules — the archaeology signal
+    // eslint-disable-next-line @typescript-eslint/max-params
+    constructor(agentType, agentId, readDiff = false, readDoc = false, toolCallCount = 0, offRepoSearches = 0) {
+        this.agentType = agentType;
+        this.agentId = agentId;
+        this.readDiff = readDiff;
+        this.readDoc = readDoc;
+        this.toolCallCount = toolCallCount;
+        this.offRepoSearches = offRepoSearches;
+    }
+}
+exports.ReviewerEvidence = ReviewerEvidence;
+/** What to look for when reading reviewer transcripts. Data-only — avoids a 5-param method. */
+class EvidenceRequest {
+    branch;
+    agentIds; // agentType → agentId, straight from ProvenanceResult
+    diffDir; // '' when nothing was materialized
+    docPaths; // agentType → its checklist doc path ('' when none)
+    // eslint-disable-next-line @typescript-eslint/max-params
+    constructor(branch, agentIds, diffDir = '', docPaths = {}) {
+        this.branch = branch;
+        this.agentIds = agentIds;
+        this.diffDir = diffDir;
+        this.docPaths = docPaths;
+    }
+}
+exports.EvidenceRequest = EvidenceRequest;
 /**
  * Verifies — from the Claude Code harness's OWN artifacts, never from anything the model asserts — that
  * a subagent of a given `agentType` actually ran during the current session on the current branch. Used
@@ -66,16 +109,111 @@ let SubagentProvenanceService = class SubagentProvenanceService {
         const dirs = this.allSubagentsDirs();
         const missing = [];
         const usedAgentIds = new Set();
+        const credited = {};
         for (const type of expectedAgentTypes) {
             const agentId = this.findMatchingAgentId(dirs, type, branch, usedAgentIds);
             if (agentId === '')
                 missing.push(type);
-            else
+            else {
                 usedAgentIds.add(agentId);
+                credited[type] = agentId;
+            }
         }
         return missing.length === 0
-            ? new ProvenanceResult(exports.PROVENANCE_OK, `verified ${expectedAgentTypes.length} distinct reviewer subagent(s) ran`)
-            : new ProvenanceResult(exports.PROVENANCE_MISSING, `these reviewer subagents did not run on this branch (spawn each as its OWN subagent — do not self-certify): ${missing.join(', ')}`);
+            ? new ProvenanceResult(exports.PROVENANCE_OK, `verified ${expectedAgentTypes.length} distinct reviewer subagent(s) ran`, credited)
+            : new ProvenanceResult(exports.PROVENANCE_MISSING, `these reviewer subagents did not run on this branch (spawn each as its OWN subagent — do not self-certify): ${missing.join(', ')}`, credited);
+    }
+    /**
+     * What each credited reviewer actually READ, from its own transcript.
+     *
+     * `verifyDistinct` proves a reviewer of the right type RAN. It cannot tell a reviewer that read the diff
+     * and thought about it from one that wrote a verdict having opened nothing. This closes that gap — and
+     * the motivating case is real: one reviewer spent 14 of 26 tool calls grepping `node_modules` because
+     * nothing had told it where anything was, which `offRepoSearches` now makes visible.
+     *
+     * WARNING-ONLY by default, for three reasons, and `requireDiffEvidence` must stay opt-in until at least
+     * one repo has watched it:
+     *   1. The transcript layout is undocumented Claude Code internals. A format change would wedge every
+     *      consumer's PR with no self-service recovery — `sidechainOnBranch` is already lenient for exactly
+     *      this reason, and blocking on a richer read of the same files would be less safe, not more.
+     *   2. A reviewer can legitimately receive the diff another way (inlined into its prompt, say).
+     *   3. verifyDistinct is the INTEGRITY signal and rightly blocks; this is a QUALITY signal. Conflating
+     *      them would let a transcript-parsing quirk refuse a PR that a real reviewer really did review.
+     *
+     * Returns [] outside a Claude Code session, matching verify/verifyDistinct's SKIP behavior.
+     */
+    evidenceFor(request) {
+        if (!this.inClaudeSession())
+            return [];
+        const dirs = this.allSubagentsDirs();
+        const out = [];
+        for (const agentType of Object.keys(request.agentIds)) {
+            const agentId = request.agentIds[agentType];
+            const jsonl = this.transcriptPath(dirs, agentId);
+            if (jsonl === '') {
+                out.push(new ReviewerEvidence(agentType, agentId));
+                continue;
+            }
+            out.push(this.evidenceFromTranscript(agentType, agentId, jsonl, request));
+        }
+        return out;
+    }
+    // eslint-disable-next-line @typescript-eslint/max-params
+    evidenceFromTranscript(agentType, agentId, jsonl, request) {
+        const inputs = this.toolInputsOf(jsonl);
+        const docPath = request.docPaths[agentType] ?? '';
+        // The instructions file counts as "read the diff": it lives in the same per-branch dir, it is what
+        // the reviewer is told to open first, and it inlines the diff paths. A reviewer that opened it and
+        // then its own diff files is the intended path; treating only the diff dir as proof would flag it.
+        const readDiff = request.diffDir !== '' && this.mentions(inputs, request.diffDir);
+        return new ReviewerEvidence(agentType, agentId, readDiff, docPath !== '' && this.mentions(inputs, docPath), inputs.length, inputs.filter((i) => i.includes('node_modules')).length);
+    }
+    // The absolute path of agent-<id>.jsonl across all session dirs, or '' if it is not there.
+    transcriptPath(dirs, agentId) {
+        for (const dir of dirs) {
+            const candidate = path.join(dir, `agent-${agentId}.jsonl`);
+            if (fs.existsSync(candidate))
+                return candidate;
+        }
+        return '';
+    }
+    /**
+     * Every tool_use input in a transcript, JSON-stringified. Stringified rather than walked field-by-field
+     * because the shape differs per tool (Read takes file_path, Bash takes command, Grep takes path) and a
+     * substring test over the serialized input is both simpler and robust to a tool we have not seen.
+     */
+    toolInputsOf(jsonl) {
+        const out = [];
+        // webpieces-disable no-unmanaged-exceptions -- chokepoint: an unreadable transcript yields no evidence, never a crash
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            for (const line of fs.readFileSync(jsonl, 'utf8').split('\n')) {
+                if (line.trim() === '')
+                    continue;
+                const rec = this.parseLine(line);
+                const message = rec?.['message'];
+                if (typeof message !== 'object' || message === null)
+                    continue;
+                // webpieces-disable no-any-unknown -- opaque transcript record, narrowed by the guard above
+                const content = message['content'];
+                if (!Array.isArray(content))
+                    continue;
+                for (const block of content) {
+                    // webpieces-disable no-any-unknown -- opaque content block, only `type`/`input` are read
+                    const b = block;
+                    if (b['type'] === 'tool_use')
+                        out.push(JSON.stringify(b['input'] ?? {}));
+                }
+            }
+        }
+        catch (err) {
+            const error = (0, to_error_1.toError)(err);
+            void error;
+        }
+        return out;
+    }
+    mentions(inputs, needle) {
+        return inputs.some((i) => i.includes(needle));
     }
     // Are we running under Claude Code at all? (CI / plain terminal → provenance is unverifiable → SKIP.)
     inClaudeSession() {

package/src/subagent-provenance.js.map

@@ -1 +1 @@
-{"version":3,"file":"subagent-provenance.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/subagent-provenance.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'fs';\nimport * as path from 'path';\nimport * as os from 'os';\nimport { injectable, bindingScopeValues } from 'inversify';\nimport { toError } from './to-error';\n\n// Outcome of a provenance check.\nexport const PROVENANCE_OK = 'ok';           // a matching reviewer subagent demonstrably ran on this branch\nexport const PROVENANCE_MISSING = 'missing'; // session known, but no matching subagent artifact found → refuse (BLOCK)\nexport const PROVENANCE_SKIPPED = 'skipped'; // no CLAUDE_CODE_SESSION_ID (plain terminal / CI) → warn + pass\n\nexport class ProvenanceResult {\n    status: string; // PROVENANCE_OK | PROVENANCE_MISSING | PROVENANCE_SKIPPED\n    detail: string; // human-readable explanation for the warning/error/dashboard\n\n    constructor(status: string, detail: string) {\n        this.status = status;\n        this.detail = detail;\n    }\n}\n\n/**\n * Verifies — from the Claude Code harness's OWN artifacts, never from anything the model asserts — that\n * a subagent of a given `agentType` actually ran during the current session on the current branch. Used\n * to enforce a checklist's optional `subagent:` field: that an INDEPENDENT reviewer looked, rather than\n * the coding agent self-certifying.\n *\n * The harness writes, beside each subagent transcript:\n *   ~/.claude/projects/<cwd-slug>/<sessionId>/subagents/agent-<id>.meta.json  → { agentType, spawnDepth, … }\n *   ~/.claude/projects/<cwd-slug>/<sessionId>/subagents/agent-<id>.jsonl      → record 0 { isSidechain, gitBranch, … }\n * `agentType`/`spawnDepth`/`isSidechain` are written by Claude Code, not by the model. We locate the dir\n * by the unique sessionId (globbing `projects/&#42;/<sessionId>/subagents`), so the cwd-slug never has to be\n * derived/guessed.\n *\n * IMPORTANT — this is NOT tamper-proof. A determined agent can `cat >` a fake agent-*.meta.json. This\n * raises the bar from \"trust the model's word\" to \"deliberate, auditable forgery outside the repo\"; it\n * is not cryptographic. Say so wherever `subagent:` is documented.\n *\n * `@injectable(bindingScopeValues.Singleton)` so it is drawn in the DI design and injected by type.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class SubagentProvenanceService {\n    // Verify a subagent of `expectedAgentType` ran on `branch`. Absent CLAUDE_CODE_SESSION_ID (plain\n    // terminal / CI) returns SKIPPED — the feature must not break non-Claude-Code consumers.\n    verify(expectedAgentType: string, branch: string): ProvenanceResult {\n        if (!this.inClaudeSession()) return this.skipped(`the \"${expectedAgentType}\" reviewer subagent`);\n        const dirs = this.allSubagentsDirs();\n        const agentId = this.findMatchingAgentId(dirs, expectedAgentType, branch);\n        return agentId !== ''\n            ? new ProvenanceResult(PROVENANCE_OK, `verified \"${expectedAgentType}\" reviewer subagent ran (agent ${agentId}).`)\n            : new ProvenanceResult(PROVENANCE_MISSING,\n                `No \"${expectedAgentType}\" reviewer subagent ran on this branch — a separate reviewer of that type must review this checklist.`);\n    }\n\n    // Verify EVERY expected reviewer subagent ran on `branch` as a DISTINCT run — the coding agent may not\n    // self-certify, and one reviewer may not stand in for several. SKIPPED (pass) without a session id.\n    //\n    // Scoped by BRANCH across ALL sessions (not the current session): once a reviewer ran on this branch in\n    // any session, a later re-push in a NEW session still finds it, so the review is NOT forced to re-run.\n    // That is what keeps \"review once per branch\" true across sessions. A PR opened outside the gated flow\n    // still has no review-<id>.json, so wp-finish forces the review regardless of provenance.\n    verifyDistinct(expectedAgentTypes: readonly string[], branch: string): ProvenanceResult {\n        if (expectedAgentTypes.length === 0) return new ProvenanceResult(PROVENANCE_OK, 'no reviewer subagents required');\n        if (!this.inClaudeSession()) return this.skipped('reviewer subagents');\n        const dirs = this.allSubagentsDirs();\n        const missing: string[] = [];\n        const usedAgentIds = new Set<string>();\n        for (const type of expectedAgentTypes) {\n            const agentId = this.findMatchingAgentId(dirs, type, branch, usedAgentIds);\n            if (agentId === '') missing.push(type);\n            else usedAgentIds.add(agentId);\n        }\n        return missing.length === 0\n            ? new ProvenanceResult(PROVENANCE_OK, `verified ${expectedAgentTypes.length} distinct reviewer subagent(s) ran`)\n            : new ProvenanceResult(PROVENANCE_MISSING,\n                `these reviewer subagents did not run on this branch (spawn each as its OWN subagent — do not self-certify): ${missing.join(', ')}`);\n    }\n\n    // Are we running under Claude Code at all? (CI / plain terminal → provenance is unverifiable → SKIP.)\n    private inClaudeSession(): boolean {\n        return (process.env['CLAUDE_CODE_SESSION_ID'] ?? '').trim() !== '';\n    }\n\n    private skipped(what: string): ProvenanceResult {\n        return new ProvenanceResult(PROVENANCE_SKIPPED,\n            `CLAUDE_CODE_SESSION_ID not set — cannot verify ${what} ran (plain terminal / CI). Skipping the provenance check.`);\n    }\n\n    // The agentId of a matching subagent run for `agentType` on `branch`, searched across ALL sessions'\n    // subagent dirs (branch-scoped, so a run from a prior session still counts). '' if none. `exclude`\n    // skips agentIds already credited to another checklist so one run can't satisfy two.\n    private findMatchingAgentId(dirs: readonly string[], agentType: string, branch: string, exclude: ReadonlySet<string> = new Set()): string {\n        for (const dir of dirs) {\n            for (const metaFile of this.metaFiles(dir)) {\n                const agentId = this.agentIdOf(metaFile);\n                if (exclude.has(agentId)) continue;\n                const meta = this.readJson(path.join(dir, metaFile));\n                if (!meta || meta['agentType'] !== agentType) continue;\n                const spawnDepth = meta['spawnDepth'];\n                if (typeof spawnDepth !== 'number' || spawnDepth < 1) continue;\n                if (this.sidechainOnBranch(dir, agentId, branch)) return agentId;\n            }\n        }\n        return '';\n    }\n\n    // Every `projects/*/<session>/subagents` dir that exists — matching by the recorded gitBranch (not by\n    // session id) is what makes provenance survive across sessions.\n    private allSubagentsDirs(): string[] {\n        const projects = path.join(os.homedir(), '.claude', 'projects');\n        if (!fs.existsSync(projects)) return [];\n        const out: string[] = [];\n        for (const proj of this.readDir(projects)) {\n            const projDir = path.join(projects, proj);\n            for (const session of this.readDir(projDir)) {\n                const candidate = path.join(projDir, session, 'subagents');\n                if (fs.existsSync(candidate)) out.push(candidate);\n            }\n        }\n        return out;\n    }\n\n    private metaFiles(dir: string): string[] {\n        return this.readDir(dir).filter((f: string): boolean => f.endsWith('.meta.json'));\n    }\n\n    // agent-<id>.meta.json → <id>\n    private agentIdOf(metaFile: string): string {\n        return metaFile.replace(/^agent-/, '').replace(/\\.meta\\.json$/, '');\n    }\n\n    // Cross-check the sibling transcript's record 0: isSidechain true (a real subagent, not the main\n    // loop) and, when recorded, the same branch. Lenient on branch drift (a leftover …wpN suffix from a\n    // mid-flight branch rename) and on a missing jsonl (meta already matched — accept, best-effort).\n    private sidechainOnBranch(dir: string, agentId: string, branch: string): boolean {\n        const jsonl = path.join(dir, `agent-${agentId}.jsonl`);\n        if (!fs.existsSync(jsonl)) return true;\n        const first = this.firstNonEmptyLine(jsonl);\n        if (first === '') return true;\n        const rec = this.parseLine(first);\n        if (!rec) return true;\n        if (rec['isSidechain'] !== true) return false;\n        const gitBranch = rec['gitBranch'];\n        if (typeof gitBranch !== 'string' || gitBranch === '') return true;\n        return this.stripWp(gitBranch) === this.stripWp(branch);\n    }\n\n    private stripWp(branch: string): string {\n        return branch.replace(/-?wp\\d+$/i, '');\n    }\n\n    private readDir(dir: string): string[] {\n        // webpieces-disable no-unmanaged-exceptions -- chokepoint: an unreadable dir yields [] (best-effort provenance)\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            return fs.readdirSync(dir);\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return [];\n        }\n    }\n\n    private firstNonEmptyLine(filePath: string): string {\n        // webpieces-disable no-unmanaged-exceptions -- chokepoint: unreadable transcript → '' (best-effort)\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            for (const line of fs.readFileSync(filePath, 'utf8').split('\\n')) {\n                if (line.trim() !== '') return line;\n            }\n            return '';\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return '';\n        }\n    }\n\n    // webpieces-disable no-any-unknown -- opaque parsed JSON object, keys read by the caller\n    private readJson(filePath: string): Record<string, unknown> | null {\n        // webpieces-disable no-unmanaged-exceptions -- chokepoint: malformed meta.json → null (skipped)\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            // webpieces-disable no-any-unknown -- parsed JSON is opaque until narrowed by the caller\n            return JSON.parse(fs.readFileSync(filePath, 'utf8')) as Record<string, unknown>;\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return null;\n        }\n    }\n\n    // webpieces-disable no-any-unknown -- one opaque JSONL record, keys read by the caller\n    private parseLine(line: string): Record<string, unknown> | null {\n        // webpieces-disable no-unmanaged-exceptions -- chokepoint: malformed JSONL record → null\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            // webpieces-disable no-any-unknown -- parsed JSON is opaque until narrowed by the caller\n            return JSON.parse(line) as Record<string, unknown>;\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return null;\n        }\n    }\n}\n"]}
+{"version":3,"file":"subagent-provenance.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/subagent-provenance.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'fs';\nimport * as path from 'path';\nimport * as os from 'os';\nimport { injectable, bindingScopeValues } from 'inversify';\nimport { toError } from './to-error';\n\n// Outcome of a provenance check.\nexport const PROVENANCE_OK = 'ok';           // a matching reviewer subagent demonstrably ran on this branch\nexport const PROVENANCE_MISSING = 'missing'; // session known, but no matching subagent artifact found → refuse (BLOCK)\nexport const PROVENANCE_SKIPPED = 'skipped'; // no CLAUDE_CODE_SESSION_ID (plain terminal / CI) → warn + pass\n\nexport class ProvenanceResult {\n    status: string; // PROVENANCE_OK | PROVENANCE_MISSING | PROVENANCE_SKIPPED\n    detail: string; // human-readable explanation for the warning/error/dashboard\n    // agentIds credited, keyed by agentType, so an evidence pass does not re-scan to find them again.\n    agentIds: Record<string, string>;\n\n    constructor(status: string, detail: string, agentIds: Record<string, string> = {}) {\n        this.status = status;\n        this.detail = detail;\n        this.agentIds = agentIds;\n    }\n}\n\n/**\n * What ONE credited reviewer actually DID, read from its own transcript. Data-only (per CLAUDE.md).\n *\n * `verifyDistinct` answers \"did a reviewer of this type run?\" — an INTEGRITY question, and it blocks. This\n * answers \"did it look at the change?\" — a QUALITY question, and it only warns. The distinction is\n * deliberate; see {@link SubagentProvenanceService.evidenceFor}.\n */\nexport class ReviewerEvidence {\n    agentType: string;\n    agentId: string;\n    readDiff: boolean;       // opened the materialized diff dir (or its own instructions file)\n    readDoc: boolean;        // opened its checklist's guidance doc\n    toolCallCount: number;\n    offRepoSearches: number; // tool calls that reached into node_modules — the archaeology signal\n\n    // eslint-disable-next-line @typescript-eslint/max-params\n    constructor(agentType: string, agentId: string, readDiff = false, readDoc = false, toolCallCount = 0, offRepoSearches = 0) {\n        this.agentType = agentType;\n        this.agentId = agentId;\n        this.readDiff = readDiff;\n        this.readDoc = readDoc;\n        this.toolCallCount = toolCallCount;\n        this.offRepoSearches = offRepoSearches;\n    }\n}\n\n/** What to look for when reading reviewer transcripts. Data-only — avoids a 5-param method. */\nexport class EvidenceRequest {\n    branch: string;\n    agentIds: Record<string, string>; // agentType → agentId, straight from ProvenanceResult\n    diffDir: string;                  // '' when nothing was materialized\n    docPaths: Record<string, string>; // agentType → its checklist doc path ('' when none)\n\n    // eslint-disable-next-line @typescript-eslint/max-params\n    constructor(branch: string, agentIds: Record<string, string>, diffDir = '', docPaths: Record<string, string> = {}) {\n        this.branch = branch;\n        this.agentIds = agentIds;\n        this.diffDir = diffDir;\n        this.docPaths = docPaths;\n    }\n}\n\n/**\n * Verifies — from the Claude Code harness's OWN artifacts, never from anything the model asserts — that\n * a subagent of a given `agentType` actually ran during the current session on the current branch. Used\n * to enforce a checklist's optional `subagent:` field: that an INDEPENDENT reviewer looked, rather than\n * the coding agent self-certifying.\n *\n * The harness writes, beside each subagent transcript:\n *   ~/.claude/projects/<cwd-slug>/<sessionId>/subagents/agent-<id>.meta.json  → { agentType, spawnDepth, … }\n *   ~/.claude/projects/<cwd-slug>/<sessionId>/subagents/agent-<id>.jsonl      → record 0 { isSidechain, gitBranch, … }\n * `agentType`/`spawnDepth`/`isSidechain` are written by Claude Code, not by the model. We locate the dir\n * by the unique sessionId (globbing `projects/&#42;/<sessionId>/subagents`), so the cwd-slug never has to be\n * derived/guessed.\n *\n * IMPORTANT — this is NOT tamper-proof. A determined agent can `cat >` a fake agent-*.meta.json. This\n * raises the bar from \"trust the model's word\" to \"deliberate, auditable forgery outside the repo\"; it\n * is not cryptographic. Say so wherever `subagent:` is documented.\n *\n * `@injectable(bindingScopeValues.Singleton)` so it is drawn in the DI design and injected by type.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class SubagentProvenanceService {\n    // Verify a subagent of `expectedAgentType` ran on `branch`. Absent CLAUDE_CODE_SESSION_ID (plain\n    // terminal / CI) returns SKIPPED — the feature must not break non-Claude-Code consumers.\n    verify(expectedAgentType: string, branch: string): ProvenanceResult {\n        if (!this.inClaudeSession()) return this.skipped(`the \"${expectedAgentType}\" reviewer subagent`);\n        const dirs = this.allSubagentsDirs();\n        const agentId = this.findMatchingAgentId(dirs, expectedAgentType, branch);\n        return agentId !== ''\n            ? new ProvenanceResult(PROVENANCE_OK, `verified \"${expectedAgentType}\" reviewer subagent ran (agent ${agentId}).`)\n            : new ProvenanceResult(PROVENANCE_MISSING,\n                `No \"${expectedAgentType}\" reviewer subagent ran on this branch — a separate reviewer of that type must review this checklist.`);\n    }\n\n    // Verify EVERY expected reviewer subagent ran on `branch` as a DISTINCT run — the coding agent may not\n    // self-certify, and one reviewer may not stand in for several. SKIPPED (pass) without a session id.\n    //\n    // Scoped by BRANCH across ALL sessions (not the current session): once a reviewer ran on this branch in\n    // any session, a later re-push in a NEW session still finds it, so the review is NOT forced to re-run.\n    // That is what keeps \"review once per branch\" true across sessions. A PR opened outside the gated flow\n    // still has no review-<id>.json, so wp-finish forces the review regardless of provenance.\n    verifyDistinct(expectedAgentTypes: readonly string[], branch: string): ProvenanceResult {\n        if (expectedAgentTypes.length === 0) return new ProvenanceResult(PROVENANCE_OK, 'no reviewer subagents required');\n        if (!this.inClaudeSession()) return this.skipped('reviewer subagents');\n        const dirs = this.allSubagentsDirs();\n        const missing: string[] = [];\n        const usedAgentIds = new Set<string>();\n        const credited: Record<string, string> = {};\n        for (const type of expectedAgentTypes) {\n            const agentId = this.findMatchingAgentId(dirs, type, branch, usedAgentIds);\n            if (agentId === '') missing.push(type);\n            else {\n                usedAgentIds.add(agentId);\n                credited[type] = agentId;\n            }\n        }\n        return missing.length === 0\n            ? new ProvenanceResult(PROVENANCE_OK, `verified ${expectedAgentTypes.length} distinct reviewer subagent(s) ran`, credited)\n            : new ProvenanceResult(PROVENANCE_MISSING,\n                `these reviewer subagents did not run on this branch (spawn each as its OWN subagent — do not self-certify): ${missing.join(', ')}`,\n                credited);\n    }\n\n    /**\n     * What each credited reviewer actually READ, from its own transcript.\n     *\n     * `verifyDistinct` proves a reviewer of the right type RAN. It cannot tell a reviewer that read the diff\n     * and thought about it from one that wrote a verdict having opened nothing. This closes that gap — and\n     * the motivating case is real: one reviewer spent 14 of 26 tool calls grepping `node_modules` because\n     * nothing had told it where anything was, which `offRepoSearches` now makes visible.\n     *\n     * WARNING-ONLY by default, for three reasons, and `requireDiffEvidence` must stay opt-in until at least\n     * one repo has watched it:\n     *   1. The transcript layout is undocumented Claude Code internals. A format change would wedge every\n     *      consumer's PR with no self-service recovery — `sidechainOnBranch` is already lenient for exactly\n     *      this reason, and blocking on a richer read of the same files would be less safe, not more.\n     *   2. A reviewer can legitimately receive the diff another way (inlined into its prompt, say).\n     *   3. verifyDistinct is the INTEGRITY signal and rightly blocks; this is a QUALITY signal. Conflating\n     *      them would let a transcript-parsing quirk refuse a PR that a real reviewer really did review.\n     *\n     * Returns [] outside a Claude Code session, matching verify/verifyDistinct's SKIP behavior.\n     */\n    evidenceFor(request: EvidenceRequest): ReviewerEvidence[] {\n        if (!this.inClaudeSession()) return [];\n        const dirs = this.allSubagentsDirs();\n        const out: ReviewerEvidence[] = [];\n        for (const agentType of Object.keys(request.agentIds)) {\n            const agentId = request.agentIds[agentType];\n            const jsonl = this.transcriptPath(dirs, agentId);\n            if (jsonl === '') {\n                out.push(new ReviewerEvidence(agentType, agentId));\n                continue;\n            }\n            out.push(this.evidenceFromTranscript(agentType, agentId, jsonl, request));\n        }\n        return out;\n    }\n\n    // eslint-disable-next-line @typescript-eslint/max-params\n    private evidenceFromTranscript(agentType: string, agentId: string, jsonl: string, request: EvidenceRequest): ReviewerEvidence {\n        const inputs = this.toolInputsOf(jsonl);\n        const docPath = request.docPaths[agentType] ?? '';\n        // The instructions file counts as \"read the diff\": it lives in the same per-branch dir, it is what\n        // the reviewer is told to open first, and it inlines the diff paths. A reviewer that opened it and\n        // then its own diff files is the intended path; treating only the diff dir as proof would flag it.\n        const readDiff = request.diffDir !== '' && this.mentions(inputs, request.diffDir);\n        return new ReviewerEvidence(\n            agentType, agentId, readDiff,\n            docPath !== '' && this.mentions(inputs, docPath),\n            inputs.length,\n            inputs.filter((i: string): boolean => i.includes('node_modules')).length,\n        );\n    }\n\n    // The absolute path of agent-<id>.jsonl across all session dirs, or '' if it is not there.\n    private transcriptPath(dirs: readonly string[], agentId: string): string {\n        for (const dir of dirs) {\n            const candidate = path.join(dir, `agent-${agentId}.jsonl`);\n            if (fs.existsSync(candidate)) return candidate;\n        }\n        return '';\n    }\n\n    /**\n     * Every tool_use input in a transcript, JSON-stringified. Stringified rather than walked field-by-field\n     * because the shape differs per tool (Read takes file_path, Bash takes command, Grep takes path) and a\n     * substring test over the serialized input is both simpler and robust to a tool we have not seen.\n     */\n    private toolInputsOf(jsonl: string): string[] {\n        const out: string[] = [];\n        // webpieces-disable no-unmanaged-exceptions -- chokepoint: an unreadable transcript yields no evidence, never a crash\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            for (const line of fs.readFileSync(jsonl, 'utf8').split('\\n')) {\n                if (line.trim() === '') continue;\n                const rec = this.parseLine(line);\n                const message = rec?.['message'];\n                if (typeof message !== 'object' || message === null) continue;\n                // webpieces-disable no-any-unknown -- opaque transcript record, narrowed by the guard above\n                const content = (message as Record<string, unknown>)['content'];\n                if (!Array.isArray(content)) continue;\n                for (const block of content) {\n                    // webpieces-disable no-any-unknown -- opaque content block, only `type`/`input` are read\n                    const b = block as Record<string, unknown>;\n                    if (b['type'] === 'tool_use') out.push(JSON.stringify(b['input'] ?? {}));\n                }\n            }\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n        }\n        return out;\n    }\n\n    private mentions(inputs: readonly string[], needle: string): boolean {\n        return inputs.some((i: string): boolean => i.includes(needle));\n    }\n\n    // Are we running under Claude Code at all? (CI / plain terminal → provenance is unverifiable → SKIP.)\n    private inClaudeSession(): boolean {\n        return (process.env['CLAUDE_CODE_SESSION_ID'] ?? '').trim() !== '';\n    }\n\n    private skipped(what: string): ProvenanceResult {\n        return new ProvenanceResult(PROVENANCE_SKIPPED,\n            `CLAUDE_CODE_SESSION_ID not set — cannot verify ${what} ran (plain terminal / CI). Skipping the provenance check.`);\n    }\n\n    // The agentId of a matching subagent run for `agentType` on `branch`, searched across ALL sessions'\n    // subagent dirs (branch-scoped, so a run from a prior session still counts). '' if none. `exclude`\n    // skips agentIds already credited to another checklist so one run can't satisfy two.\n    private findMatchingAgentId(dirs: readonly string[], agentType: string, branch: string, exclude: ReadonlySet<string> = new Set()): string {\n        for (const dir of dirs) {\n            for (const metaFile of this.metaFiles(dir)) {\n                const agentId = this.agentIdOf(metaFile);\n                if (exclude.has(agentId)) continue;\n                const meta = this.readJson(path.join(dir, metaFile));\n                if (!meta || meta['agentType'] !== agentType) continue;\n                const spawnDepth = meta['spawnDepth'];\n                if (typeof spawnDepth !== 'number' || spawnDepth < 1) continue;\n                if (this.sidechainOnBranch(dir, agentId, branch)) return agentId;\n            }\n        }\n        return '';\n    }\n\n    // Every `projects/*/<session>/subagents` dir that exists — matching by the recorded gitBranch (not by\n    // session id) is what makes provenance survive across sessions.\n    private allSubagentsDirs(): string[] {\n        const projects = path.join(os.homedir(), '.claude', 'projects');\n        if (!fs.existsSync(projects)) return [];\n        const out: string[] = [];\n        for (const proj of this.readDir(projects)) {\n            const projDir = path.join(projects, proj);\n            for (const session of this.readDir(projDir)) {\n                const candidate = path.join(projDir, session, 'subagents');\n                if (fs.existsSync(candidate)) out.push(candidate);\n            }\n        }\n        return out;\n    }\n\n    private metaFiles(dir: string): string[] {\n        return this.readDir(dir).filter((f: string): boolean => f.endsWith('.meta.json'));\n    }\n\n    // agent-<id>.meta.json → <id>\n    private agentIdOf(metaFile: string): string {\n        return metaFile.replace(/^agent-/, '').replace(/\\.meta\\.json$/, '');\n    }\n\n    // Cross-check the sibling transcript's record 0: isSidechain true (a real subagent, not the main\n    // loop) and, when recorded, the same branch. Lenient on branch drift (a leftover …wpN suffix from a\n    // mid-flight branch rename) and on a missing jsonl (meta already matched — accept, best-effort).\n    private sidechainOnBranch(dir: string, agentId: string, branch: string): boolean {\n        const jsonl = path.join(dir, `agent-${agentId}.jsonl`);\n        if (!fs.existsSync(jsonl)) return true;\n        const first = this.firstNonEmptyLine(jsonl);\n        if (first === '') return true;\n        const rec = this.parseLine(first);\n        if (!rec) return true;\n        if (rec['isSidechain'] !== true) return false;\n        const gitBranch = rec['gitBranch'];\n        if (typeof gitBranch !== 'string' || gitBranch === '') return true;\n        return this.stripWp(gitBranch) === this.stripWp(branch);\n    }\n\n    private stripWp(branch: string): string {\n        return branch.replace(/-?wp\\d+$/i, '');\n    }\n\n    private readDir(dir: string): string[] {\n        // webpieces-disable no-unmanaged-exceptions -- chokepoint: an unreadable dir yields [] (best-effort provenance)\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            return fs.readdirSync(dir);\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return [];\n        }\n    }\n\n    private firstNonEmptyLine(filePath: string): string {\n        // webpieces-disable no-unmanaged-exceptions -- chokepoint: unreadable transcript → '' (best-effort)\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            for (const line of fs.readFileSync(filePath, 'utf8').split('\\n')) {\n                if (line.trim() !== '') return line;\n            }\n            return '';\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return '';\n        }\n    }\n\n    // webpieces-disable no-any-unknown -- opaque parsed JSON object, keys read by the caller\n    private readJson(filePath: string): Record<string, unknown> | null {\n        // webpieces-disable no-unmanaged-exceptions -- chokepoint: malformed meta.json → null (skipped)\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            // webpieces-disable no-any-unknown -- parsed JSON is opaque until narrowed by the caller\n            return JSON.parse(fs.readFileSync(filePath, 'utf8')) as Record<string, unknown>;\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return null;\n        }\n    }\n\n    // webpieces-disable no-any-unknown -- one opaque JSONL record, keys read by the caller\n    private parseLine(line: string): Record<string, unknown> | null {\n        // webpieces-disable no-unmanaged-exceptions -- chokepoint: malformed JSONL record → null\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            // webpieces-disable no-any-unknown -- parsed JSON is opaque until narrowed by the caller\n            return JSON.parse(line) as Record<string, unknown>;\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            return null;\n        }\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-branches';
+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;
+}