agent-dealer 0.2.0 → 1.0.0

package/bundle/server/dist/coordinator/usage-cap.integration.test.js

@@ -0,0 +1,193 @@
+// packages/server/src/coordinator/usage-cap.integration.test.ts
+//
+// NOT-111 acceptance: cap detection → deferral without spending attempt/infra budgets.
+import { test, before, beforeEach, after } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+process.env.AGENT_DEALER_HOME = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-cap-int-"));
+process.env.MAX_COORDINATOR_CONCURRENCY = "1";
+process.env.COORDINATOR_HEARTBEAT_MS = "20";
+process.env.COORDINATOR_FAIL_BACKOFF_MS = "0";
+process.env.COORDINATOR_POLL_INTERVAL_MS = "50";
+process.env.USAGE_CAP_FALLBACK_COOLDOWN_MS = "60000";
+const fixturePath = path.join(path.dirname(fileURLToPath(import.meta.url)), "../runners/fixtures/claude-rate-limit-rejected.ndjson");
+const { migrate, getDb } = await import("../db/index.js");
+const { createAgent } = await import("../repository/agents.js");
+const { createIssue, getIssue } = await import("../repository/issues.js");
+const { listWorkItemsForIssue } = await import("../repository/work-items.js");
+const { listWorkflowEventsForIssue } = await import("../repository/workflow-events.js");
+const { recordRuntimeAvailability } = await import("../repository/runtime-availability.js");
+const { startWorkflow } = await import("./commands.js");
+const { registerEffectHandler, resetEffectHandlers } = await import("./effect-registry.js");
+const { runCoordinatorTick, drainCoordinator } = await import("./worker-loop.js");
+const { recordUsageCapFromLog } = await import("../runners/usage-cap.js");
+before(() => migrate());
+beforeEach(() => {
+    getDb().exec(`
+    DELETE FROM review_publications;
+    DELETE FROM work_items;
+    DELETE FROM human_actions;
+    DELETE FROM workflow_events;
+    DELETE FROM findings;
+    DELETE FROM worker_sessions;
+    DELETE FROM artifacts;
+    DELETE FROM usage_events;
+    DELETE FROM workflow_instances;
+    DELETE FROM issues;
+    DELETE FROM runtime_availability;
+  `);
+});
+after(() => resetEffectHandlers());
+async function pump(max = 10) {
+    for (let i = 0; i < max; i++) {
+        await runCoordinatorTick();
+        await drainCoordinator();
+        await new Promise((r) => setTimeout(r, 30));
+    }
+}
+test("in-flight cap defers work item without incrementing attempt_count or infra_attempts", async () => {
+    const repo = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-cap-repo-"));
+    const dev = createAgent({ name: "dev-cap", runtime: "claude_code", deckId: "00000000-0000-4000-a000-000000000099" });
+    const rev = createAgent({ name: "rev-cap", runtime: "claude_code", deckId: "00000000-0000-4000-a000-000000000099" });
+    const issueId = createIssue({
+        title: "Cap test",
+        description: "d",
+        acceptanceCriteria: "ac",
+        repo,
+        baseBranch: "main",
+        developerAgentId: dev.id,
+        reviewerAgentId: rev.id,
+        maxReviewRounds: 2,
+        maxInfraAttempts: 1,
+        source: "manual"
+    }).id;
+    registerEffectHandler("developer", async () => {
+        const until = new Date(Date.now() + 120_000).toISOString();
+        recordRuntimeAvailability({
+            runtime: "claude_code",
+            unavailableUntil: until,
+            reason: "claude_code usage capped — five_hour limit rejected",
+            evidence: { test: true }
+        });
+        return {
+            kind: "usage_capped",
+            until,
+            reason: "claude_code usage capped — five_hour limit rejected"
+        };
+    });
+    const started = startWorkflow(issueId);
+    assert.equal(started.ok, true);
+    if (started.ok !== true)
+        return;
+    const before = listWorkItemsForIssue(issueId)[0];
+    assert.equal(before.attemptCount, 0);
+    await pump();
+    const issue = getIssue(issueId);
+    assert.equal(issue.infraAttempts, 0);
+    const items = listWorkItemsForIssue(issueId);
+    assert.equal(items.length, 1);
+    const item = items[0];
+    assert.equal(item.status, "pending");
+    assert.equal(item.attemptCount, 0);
+    assert.ok(Date.parse(item.availableAt) > Date.now());
+    const events = listWorkflowEventsForIssue(issueId);
+    assert.ok(events.some((e) => e.type === "worker.deferred"));
+});
+test("pending item on capped runtime is not spawned before until (pre-spawn deferral)", async () => {
+    const repo = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-cap-repo2-"));
+    const dev = createAgent({ name: "dev-cap2", runtime: "claude_code", deckId: "00000000-0000-4000-a000-000000000099" });
+    const rev = createAgent({ name: "rev-cap2", runtime: "claude_code", deckId: "00000000-0000-4000-a000-000000000099" });
+    const until = new Date(Date.now() + 300_000).toISOString();
+    recordRuntimeAvailability({
+        runtime: "claude_code",
+        unavailableUntil: until,
+        reason: "claude_code usage capped — test"
+    });
+    let spawnCalls = 0;
+    registerEffectHandler("developer", async () => {
+        spawnCalls++;
+        return { kind: "no_pr" };
+    });
+    const issueId = createIssue({
+        title: "Pre-spawn cap",
+        description: "d",
+        acceptanceCriteria: "ac",
+        repo,
+        baseBranch: "main",
+        developerAgentId: dev.id,
+        reviewerAgentId: rev.id,
+        maxReviewRounds: 2,
+        maxInfraAttempts: 3,
+        source: "manual"
+    }).id;
+    startWorkflow(issueId);
+    await pump(3);
+    assert.equal(spawnCalls, 0);
+    const item = listWorkItemsForIssue(issueId)[0];
+    assert.equal(item.status, "pending");
+    assert.equal(item.attemptCount, 0);
+    assert.ok(Date.parse(item.availableAt) > Date.now());
+    assert.ok(listWorkflowEventsForIssue(issueId).some((e) => e.type === "worker.deferred"));
+});
+test("deferral past the ceiling escalates to policy_escalation instead of deferring forever", async () => {
+    const prevCeiling = process.env.USAGE_CAP_DEFERRAL_CEILING_MS;
+    process.env.USAGE_CAP_DEFERRAL_CEILING_MS = "50";
+    try {
+        const { listHumanActionsForIssue } = await import("../repository/human-actions.js");
+        const repo = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-cap-ceiling-"));
+        const dev = createAgent({ name: "dev-ceiling", runtime: "claude_code", deckId: "00000000-0000-4000-a000-000000000099" });
+        const rev = createAgent({ name: "rev-ceiling", runtime: "claude_code", deckId: "00000000-0000-4000-a000-000000000099" });
+        const issueId = createIssue({
+            title: "Ceiling test",
+            description: "d",
+            acceptanceCriteria: "ac",
+            repo,
+            baseBranch: "main",
+            developerAgentId: dev.id,
+            reviewerAgentId: rev.id,
+            maxReviewRounds: 2,
+            maxInfraAttempts: 3,
+            source: "manual"
+        }).id;
+        // Every attempt reports the same hard cap — availableAt is a few ms out so the next
+        // pump tick re-attempts quickly, letting the 50ms ceiling elapse across two deferrals.
+        registerEffectHandler("developer", async () => {
+            const until = new Date(Date.now() + 5).toISOString();
+            return {
+                kind: "usage_capped",
+                until,
+                reason: "claude_code usage capped — plan limit rejected"
+            };
+        });
+        const started = startWorkflow(issueId);
+        assert.equal(started.ok, true);
+        await pump(1); // first cap observation — defers, starts the ceiling clock
+        assert.equal(getIssue(issueId).status, "developing");
+        await new Promise((r) => setTimeout(r, 60)); // elapse the 50ms deferral ceiling
+        await pump(); // second cap observation — ceiling exceeded, escalates
+        const issue = getIssue(issueId);
+        assert.equal(issue.status, "needs_human");
+        const escalation = listHumanActionsForIssue(issueId).find((a) => a.status === "open");
+        assert.equal(escalation?.actionType, "policy_escalation");
+        const items = listWorkItemsForIssue(issueId);
+        assert.equal(items.length, 1);
+        assert.equal(items[0].status, "done", "escalation finishes the work item rather than deferring it again");
+        const events = listWorkflowEventsForIssue(issueId);
+        assert.equal(events.filter((e) => e.type === "worker.deferred").length, 1, "exactly one deferral before escalation");
+        assert.ok(events.some((e) => e.type === "worker.failed"));
+    }
+    finally {
+        if (prevCeiling === undefined)
+            delete process.env.USAGE_CAP_DEFERRAL_CEILING_MS;
+        else
+            process.env.USAGE_CAP_DEFERRAL_CEILING_MS = prevCeiling;
+    }
+});
+test("fixture log records runtime_availability with resetsAt", () => {
+    const cap = recordUsageCapFromLog(fixturePath, "claude_code", Date.parse("2026-01-01T00:00:00.000Z"));
+    assert.ok(cap);
+    assert.equal(cap.unavailableUntil, new Date(1784283600 * 1000).toISOString());
+});

package/bundle/server/dist/coordinator/usage.js

@@ -0,0 +1,40 @@
+import { extractResultText, parseNdjsonFile } from "../runners/stream-json.js";
+import { normalizeCodexEvents, parseCodexJsonl } from "../runners/codex-jsonl.js";
+import fs from "node:fs";
+const EMPTY = { tokensIn: null, tokensOut: null, costUsd: null };
+/** Best-effort: a missing/unparseable log never blocks recording the session's duration. */
+export function extractSpawnUsage(logPath, runtime) {
+    if (!fs.existsSync(logPath))
+        return EMPTY;
+    const events = runtime === "codex_local"
+        ? normalizeCodexEvents(parseCodexJsonl(fs.readFileSync(logPath, "utf8")))
+        : parseNdjsonFile(logPath);
+    const result = events.find((e) => e.type === "result");
+    const usage = result?.usage ?? {};
+    return {
+        tokensIn: usage.input_tokens ?? usage.inputTokens ?? null,
+        tokensOut: usage.output_tokens ?? usage.outputTokens ?? null,
+        costUsd: typeof result?.total_cost_usd === "number" ? result.total_cost_usd : null,
+    };
+}
+/**
+ * The final assistant message text out of a developer/reviewer session's raw ndjson log
+ * — never the raw multi-event stream `spawnCli` hands back as its in-memory `transcript`.
+ * That raw stream is not a single coherent document: with `--stream-partial-output`
+ * (cursor) the same growing answer appears as many overlapping partial fragments before
+ * its final, complete form, so any parser (e.g. reviewer-result.ts's fenced-JSON regex)
+ * run directly against it can match an early, truncated fragment instead of the finished
+ * output. Reuses the exact per-runtime `type: "result"` extraction `extractSpawnUsage`
+ * already applies to the same log, so both stay in sync with how each runtime's events
+ * are parsed/normalized. Falls back to the raw transcript when nothing parses (e.g. a
+ * crash before any structured event, or a non-stream-json output format) so callers never
+ * regress to less text than they had before this extraction existed.
+ */
+export function extractResultTranscript(logPath, runtime, fallback) {
+    if (!fs.existsSync(logPath))
+        return fallback;
+    const events = runtime === "codex_local"
+        ? normalizeCodexEvents(parseCodexJsonl(fs.readFileSync(logPath, "utf8")))
+        : parseNdjsonFile(logPath);
+    return extractResultText(events) ?? fallback;
+}

package/bundle/server/dist/coordinator/usage.test.js

@@ -0,0 +1,69 @@
+// packages/server/src/coordinator/usage.test.ts
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { extractResultTranscript, extractSpawnUsage } from "./usage.js";
+function writeLog(lines) {
+    const file = path.join(fs.mkdtempSync(path.join(os.tmpdir(), "dealer-usage-")), "session.ndjson");
+    fs.writeFileSync(file, lines.map((l) => JSON.stringify(l)).join("\n"));
+    return file;
+}
+test("extractSpawnUsage reads claude-shaped stream-json usage/cost", () => {
+    const logPath = writeLog([
+        { type: "system", subtype: "init" },
+        { type: "assistant", message: { content: [{ type: "text", text: "hi" }] } },
+        { type: "result", total_cost_usd: 0.0421, usage: { input_tokens: 1000, output_tokens: 200 } },
+    ]);
+    const usage = extractSpawnUsage(logPath, "claude_code");
+    assert.equal(usage.tokensIn, 1000);
+    assert.equal(usage.tokensOut, 200);
+    assert.equal(usage.costUsd, 0.0421);
+});
+test("extractSpawnUsage reads codex-shaped jsonl usage (no cost field)", () => {
+    const logPath = writeLog([
+        { type: "turn.completed", usage: { input_tokens: 500, cached_input_tokens: 100, output_tokens: 50 } },
+    ]);
+    const usage = extractSpawnUsage(logPath, "codex_local");
+    assert.equal(usage.tokensIn, 500);
+    assert.equal(usage.tokensOut, 50);
+    assert.equal(usage.costUsd, null);
+});
+test("extractSpawnUsage returns nulls for a missing log file", () => {
+    const usage = extractSpawnUsage("/does/not/exist.ndjson", "claude_code");
+    assert.deepEqual(usage, { tokensIn: null, tokensOut: null, costUsd: null });
+});
+test("extractSpawnUsage returns nulls when no result event is present", () => {
+    const logPath = writeLog([{ type: "assistant", message: { content: [] } }]);
+    const usage = extractSpawnUsage(logPath, "claude_code");
+    assert.deepEqual(usage, { tokensIn: null, tokensOut: null, costUsd: null });
+});
+// Regression for the bug this extractor was added to fix: with `--stream-partial-output`
+// (cursor), the same growing answer streams as repeated partial fragments before its
+// final, complete form — a truncated fence can appear in the raw stream well before the
+// finished one. Parsing the raw stdout directly (the old behavior) risks matching that
+// earlier, incomplete fragment; extracting the final `type: "result"` event's text first
+// sidesteps that regardless of what came before it in the stream.
+test("extractResultTranscript returns the final result text, not an earlier partial fragment", () => {
+    const logPath = writeLog([
+        { type: "system", subtype: "init" },
+        // An earlier partial-output chunk containing what looks like an (incomplete) fence.
+        { type: "assistant", message: { content: [{ type: "text", text: '```json\n{"verdict": "appro' }] } },
+        { type: "result", result: '```json\n{"verdict":"approved"}\n```' },
+    ]);
+    const text = extractResultTranscript(logPath, "cursor_local", "fallback");
+    assert.equal(text, '```json\n{"verdict":"approved"}\n```');
+});
+test("extractResultTranscript reads codex-shaped jsonl via the normalized result event", () => {
+    const logPath = writeLog([
+        { type: "item.completed", item: { type: "agent_message", text: '```json\n{"verdict":"approved"}\n```' } },
+    ]);
+    const text = extractResultTranscript(logPath, "codex_local", "fallback");
+    assert.equal(text, '```json\n{"verdict":"approved"}\n```');
+});
+test("extractResultTranscript falls back to the raw transcript when nothing parses", () => {
+    assert.equal(extractResultTranscript("/does/not/exist.ndjson", "claude_code", "raw fallback text"), "raw fallback text");
+    const logPath = writeLog([{ type: "assistant", message: { content: [] } }]);
+    assert.equal(extractResultTranscript(logPath, "claude_code", "raw fallback text"), "raw fallback text");
+});

package/bundle/server/dist/coordinator/verification-receipt.js

@@ -0,0 +1,333 @@
+// packages/server/src/coordinator/verification-receipt.ts
+//
+// NOT-130: mine verification commands from a developer session log and persist a
+// SHA-scoped receipt so an infra retry can carry "already green at this tip" evidence
+// without a runtime-level `--resume`. A receipt never instructs the agent to skip — it
+// is evidence. HEAD move (new commits after the checks) invalidates it automatically.
+import { parseNdjsonFile } from "../runners/stream-json.js";
+export const VERIFICATION_RECEIPT_KIND = "verification_receipt";
+/**
+ * A command segment is verification only when a runner invocation starts the segment
+ * (start of string / after && || ; |), not when a keyword appears mid-line in `rg typecheck`.
+ */
+const VERIFICATION_SEGMENT_RE = /^(?:cd\s+\S+\s*(?:&&|;)\s+)*(?:npx\s+|pnpm\s+(?:exec\s+|run\s+)?|yarn\s+(?:run\s+)?|uv\s+run\s+)?(?:npm\s+test\b|npm\s+run\s+(?:test\b[\w:-]*|typecheck\b|flow:verify\b|poc:integration\b)|pytest\b|vitest\b|jest\b|node\s+--test\b)/i;
+/**
+ * Match real commit-shaped invocations, including `git -c … commit`, `git -C dir commit`,
+ * and `git-yubikey-commit`. False positives that clear the receipt are safer than missing
+ * a tip-changing command (which would pin a green suite to an unverified tip).
+ */
+const HEAD_CHANGING_RE = /\bgit(?:-[a-z0-9-]+)?\b[^;&|\n]*\b(?:commit|amend|rebase|reset|merge|cherry-pick|revert|pull|checkout|apply|am)\b/i;
+const REV_PARSE_HEAD_RE = /\bgit(?:\s+-C\s+\S+)?\s+rev-parse\s+HEAD\b/i;
+const FULL_SHA_RE = /\b([0-9a-f]{40})\b/i;
+/** Prefer runner-shaped counts over a bare n/m (dates, coverage ratios, progress). */
+const DETAIL_PATTERNS = [
+    {
+        re: /#\s*pass\s+(\d+)/i,
+        format: (m) => `${m[1]} passed`,
+    },
+    {
+        re: /(\d+)\s+passed,\s*(\d+)\s+total/i,
+        format: (m) => `${m[1]}/${m[2]}`,
+    },
+    {
+        re: /Tests?\s+(\d+)\s+passed/i,
+        format: (m) => `${m[1]} passed`,
+    },
+    {
+        re: /(\d+)\s+passed(?:ing)?\b/i,
+        format: (m) => `${m[1]} passed`,
+    },
+    {
+        re: /(\d+)\s*\/\s*(\d+)\s+tests?\s+passed/i,
+        format: (m) => `${m[1]}/${m[2]}`,
+    },
+];
+export function isVerificationCommand(command) {
+    return command
+        .split(/(?:&&|\|\||;|\|)/)
+        .some((seg) => VERIFICATION_SEGMENT_RE.test(seg.trim()));
+}
+/**
+ * Carry a prior receipt only for interrupted / crashed style retries — not when the job
+ * is to reproduce a CI/check failure at this same SHA (checks_failed).
+ */
+export function shouldCarryVerificationReceipt(retryReason) {
+    if (!retryReason?.trim())
+        return false;
+    if (/PR checks failed|checks failed/i.test(retryReason))
+        return false;
+    return true;
+}
+function normalizeCommand(command) {
+    return command.replace(/\s+/g, " ").trim();
+}
+function toolResultText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .map((part) => {
+        if (typeof part === "string")
+            return part;
+        if (part && typeof part === "object" && typeof part.text === "string") {
+            return part.text;
+        }
+        return "";
+    })
+        .join("\n");
+}
+function outcomeFromClaudeResult(isError, text) {
+    if (isError === true)
+        return "failed";
+    if (/exit code[:\s]+[1-9]\d*/i.test(text))
+        return "failed";
+    if (isError === false)
+        return "passed";
+    if (/exit code[:\s]+0\b/i.test(text))
+        return "passed";
+    return "unknown";
+}
+function outcomeFromExitCode(exitCode) {
+    if (typeof exitCode !== "number")
+        return "unknown";
+    return exitCode === 0 ? "passed" : "failed";
+}
+function detailFromOutput(text) {
+    for (const { re, format } of DETAIL_PATTERNS) {
+        const m = text.match(re);
+        if (!m)
+            continue;
+        const detail = format(m);
+        if (detail)
+            return detail;
+    }
+    return undefined;
+}
+function cursorShellEntry(e) {
+    if (e.type !== "tool_call")
+        return null;
+    const nested = e.tool_call;
+    if (!nested || typeof nested !== "object" || Array.isArray(nested))
+        return null;
+    const shell = nested.shellToolCall;
+    if (!shell || typeof shell !== "object")
+        return null;
+    const args = shell.args;
+    const command = typeof args?.command === "string" ? args.command : "";
+    if (!command)
+        return null;
+    const subtype = typeof e.subtype === "string" ? e.subtype : "";
+    const result = shell.result;
+    let exitCode;
+    let output = "";
+    if (result && typeof result === "object") {
+        if (typeof result.exitCode === "number")
+            exitCode = result.exitCode;
+        else if (typeof result.exit_code === "number")
+            exitCode = result.exit_code;
+        const stdout = typeof result.stdout === "string" ? result.stdout : "";
+        const stderr = typeof result.stderr === "string" ? result.stderr : "";
+        output = [stdout, stderr].filter(Boolean).join("\n");
+    }
+    return {
+        command,
+        exitCode,
+        output,
+        completed: subtype === "completed" || result != null,
+    };
+}
+/** Every Bash/Shell tool_use in an assistant event (parallel batches included). */
+function claudeBashCommands(e) {
+    if (e.type !== "assistant")
+        return [];
+    const msg = e.message;
+    const out = [];
+    for (const c of msg?.content ?? []) {
+        if (c.type === "tool_use" && (c.name === "Bash" || c.name === "Shell") && c.id && c.input?.command) {
+            out.push({ id: c.id, command: c.input.command });
+        }
+    }
+    return out;
+}
+function claudeToolResults(e) {
+    if (e.type !== "user")
+        return [];
+    const msg = e.message;
+    const out = [];
+    for (const c of msg?.content ?? []) {
+        if (c.type !== "tool_result" || typeof c.tool_use_id !== "string")
+            continue;
+        out.push({
+            toolUseId: c.tool_use_id,
+            isError: typeof c.is_error === "boolean" ? c.is_error : undefined,
+            text: toolResultText(c.content),
+        });
+    }
+    return out;
+}
+/**
+ * Walk a session NDJSON log and build a receipt when at least one verification command
+ * completed and we can pin it to a branch SHA that still matches the tip.
+ *
+ * `headShaHint` is the worktree's `git rev-parse HEAD` at persist time — used when the
+ * agent never printed a SHA, and as a gate that the tip has not moved past the checks.
+ */
+export function extractVerificationReceiptFromLog(logPath, opts) {
+    if (!logPath)
+        return null;
+    let events;
+    try {
+        events = parseNdjsonFile(logPath);
+    }
+    catch {
+        return null;
+    }
+    if (!events.length)
+        return null;
+    let observedHead = null;
+    const pendingBash = new Map();
+    /** Last result per normalized command; cleared when HEAD-changing git runs. */
+    const byCommand = new Map();
+    const applyShellCompleted = (command, outcome, output) => {
+        const normalized = normalizeCommand(command);
+        if (!normalized)
+            return;
+        const changesHead = HEAD_CHANGING_RE.test(normalized);
+        const isVerify = isVerificationCommand(normalized);
+        // Compound `npm test && git commit` (or the reverse) is ambiguous — refuse to vouch.
+        if (changesHead && isVerify) {
+            byCommand.clear();
+            observedHead = null;
+            return;
+        }
+        if (changesHead) {
+            // New tip — prior suite results no longer vouch for HEAD.
+            byCommand.clear();
+            observedHead = null;
+        }
+        if (REV_PARSE_HEAD_RE.test(normalized)) {
+            const m = output.trim().match(FULL_SHA_RE);
+            if (m)
+                observedHead = m[1].toLowerCase();
+        }
+        if (!isVerify)
+            return;
+        const detail = detailFromOutput(output);
+        byCommand.set(normalized, {
+            command: normalized.length > 240 ? `${normalized.slice(0, 237)}…` : normalized,
+            outcome,
+            ...(detail ? { detail } : {}),
+        });
+    };
+    for (const e of events) {
+        for (const bash of claudeBashCommands(e)) {
+            pendingBash.set(bash.id, bash.command);
+        }
+        for (const result of claudeToolResults(e)) {
+            const command = pendingBash.get(result.toolUseId);
+            if (!command)
+                continue;
+            pendingBash.delete(result.toolUseId);
+            applyShellCompleted(command, outcomeFromClaudeResult(result.isError, result.text), result.text);
+        }
+        const shell = cursorShellEntry(e);
+        if (shell?.completed) {
+            applyShellCompleted(shell.command, outcomeFromExitCode(shell.exitCode), shell.output);
+        }
+    }
+    const commands = [...byCommand.values()];
+    if (!commands.length)
+        return null;
+    // Only persist when something actually passed — a failed suite is not evidence to skip.
+    if (!commands.some((c) => c.outcome === "passed"))
+        return null;
+    const hint = opts?.headShaHint?.trim().toLowerCase() || null;
+    const headSha = (observedHead ?? hint)?.toLowerCase() ?? null;
+    if (!headSha || !FULL_SHA_RE.test(headSha))
+        return null;
+    // Tip moved after the checks (or agent never re-verified after committing).
+    if (hint && observedHead && hint !== observedHead)
+        return null;
+    // When only headShaHint is available, it is safe iff no HEAD-changing command ran after
+    // the last verification (those clear byCommand, so we would not reach a receipt here).
+    return {
+        headSha,
+        commands,
+        recordedAt: (opts?.now ?? (() => new Date().toISOString()))(),
+    };
+}
+export function parseVerificationReceipt(content) {
+    if (!content || typeof content !== "object")
+        return null;
+    const raw = content;
+    if (typeof raw.headSha !== "string" || !FULL_SHA_RE.test(raw.headSha))
+        return null;
+    if (!Array.isArray(raw.commands) || raw.commands.length === 0)
+        return null;
+    const commands = [];
+    for (const c of raw.commands) {
+        if (!c || typeof c !== "object")
+            continue;
+        const row = c;
+        if (typeof row.command !== "string" || !row.command.trim())
+            continue;
+        const outcome = row.outcome === "passed" || row.outcome === "failed" || row.outcome === "unknown"
+            ? row.outcome
+            : "unknown";
+        commands.push({
+            command: row.command,
+            outcome,
+            ...(typeof row.detail === "string" && row.detail.trim() ? { detail: row.detail.trim() } : {}),
+        });
+    }
+    if (!commands.length)
+        return null;
+    return {
+        headSha: raw.headSha.toLowerCase(),
+        commands,
+        recordedAt: typeof raw.recordedAt === "string" ? raw.recordedAt : new Date(0).toISOString(),
+    };
+}
+/** Null when missing or when HEAD has moved since the receipt was recorded. */
+export function receiptForCurrentHead(receipt, currentHeadSha) {
+    if (!receipt || !currentHeadSha)
+        return null;
+    if (receipt.headSha.toLowerCase() !== currentHeadSha.trim().toLowerCase())
+        return null;
+    return receipt;
+}
+/**
+ * CI already rejected this tip — a later crash/timeout retry at the same SHA must not
+ * re-inject "do not re-run an unchanged green suite" (class: ci-rejected-local-green).
+ */
+export function receiptSupersededByFailedChecks(receipt, checksEvidence) {
+    if (!checksEvidence || checksEvidence.snapshot !== "failure")
+        return false;
+    if (typeof checksEvidence.headSha !== "string" || !checksEvidence.headSha.trim())
+        return false;
+    return checksEvidence.headSha.trim().toLowerCase() === receipt.headSha.toLowerCase();
+}
+function receiptIsUniformlyGreen(receipt) {
+    return receipt.commands.length > 0 && receipt.commands.every((c) => c.outcome === "passed");
+}
+/** Prompt lines under ## Previous attempt — evidence only. */
+export function formatVerificationReceiptSection(receipt) {
+    const short = receipt.headSha.slice(0, 8);
+    const lines = [
+        `### Prior verification receipt`,
+        `At \`${short}\` (\`${receipt.headSha}\`), HEAD is unchanged. Prior session evidence:`,
+    ];
+    for (const c of receipt.commands) {
+        const detail = c.detail ? ` (${c.detail})` : "";
+        lines.push(`- \`${c.command}\` ${c.outcome}${detail}`);
+    }
+    if (receiptIsUniformlyGreen(receipt)) {
+        lines.push(`This is evidence, not an instruction to skip — re-run anything you doubt. Do not re-run an unchanged green suite by default.`);
+    }
+    else {
+        lines.push(`This is evidence, not an instruction to skip — re-run anything you doubt. Treat only commands marked passed as already green; re-check failed or unknown ones.`);
+    }
+    lines.push(``);
+    return lines;
+}