@jphutchins/code-review 0.1.0-alpha.21 → 0.1.0-alpha.23

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { defineCommand, runMain } from 'citty';
-import { readFileSync, writeFileSync, statSync, readdirSync } from 'fs';
-import { resolve as resolve$1, join, dirname, basename } from 'path';
+import { readFileSync, writeFileSync, statSync, copyFileSync, readdirSync } from 'fs';
+import { resolve as resolve$1, join, dirname, basename, extname } from 'path';
 import { Eta } from 'eta';
 import parseDiff from 'parse-diff';
 import { Ajv2020 } from 'ajv/dist/2020.js';
@@ -178,6 +178,11 @@ ${marker}` : "";
 };
 var findingsPointer = (findings, jsonUrl, limit = EMBED_LIMIT) => encodeMarker(findings, jsonUrl, limit);
 var findingPointer = (finding, schemaVersion, jsonUrl, limit = EMBED_LIMIT) => encodeMarker({ schema_version: schemaVersion, findings: [finding] }, jsonUrl, limit);
+var ZERO_SHA = "0000000000000000000000000000000000000000";
+var parseReviewedSha = (body) => {
+  const sha = /<!-- reviewed-sha: ([0-9a-fA-F]{40}) -->/.exec(body)?.[1]?.toLowerCase();
+  return sha && sha !== ZERO_SHA ? sha : null;
+};
 var parseFindingsMarker = (body) => {
   const match = /<!-- code-review:findings-json;base64 ([A-Za-z0-9+/=]+) -->/.exec(body);
   const b64 = match?.[1];
@@ -251,8 +256,7 @@ var render = (input) => {
     findingsPointer: input.findingsPointer ?? findingsPointer(input.findings, input.jsonUrl),
     reviewUrl: input.reviewUrl ?? null,
     formatTokens: (n) => Number.isFinite(n) && n >= 0 ? n.toLocaleString("en-US") : "\u2014",
-    // Cost cells render N/A (never a false $0.00) when no real price map was provided — there are
-    // real tokens spent, we simply have no rates to price them (SPEC §6.2).
+    // N/A (never a false $0.00) when no real price map was provided — real tokens, no rates to price them.
     formatCost: (n) => !pricesProvided ? "N/A" : Number.isFinite(n) ? n > 0 && n.toFixed(2) === "0.00" ? "<$0.01" : `$${n.toFixed(2)}` : "\u2014",
     formatDuration: (ms) => {
       if (!Number.isFinite(ms) || ms < 0) return "\u2014";
@@ -383,6 +387,14 @@ var renderStraysSection = (strays) => {
   ].join("\n");
 };
 var asRecord = (u) => typeof u === "object" && u !== null && !Array.isArray(u) ? u : null;
+var errMsg = (e) => e instanceof Error ? e.message : String(e);
+var tryParseJson = (text) => {
+  try {
+    return { ok: true, value: JSON.parse(text) };
+  } catch {
+    return { ok: false };
+  }
+};
 var readFileOrNull = (path) => {
   try {
     return readFileSync(path, "utf-8");
@@ -683,7 +695,7 @@ var draftState = (draftPath, resolveSchema) => {
     if (err instanceof Error && err.code === "ENOENT") {
       return { kind: "missing" };
     }
-    return { kind: "unreadable", error: err instanceof Error ? err.message : String(err) };
+    return { kind: "unreadable", error: errMsg(err) };
   }
   let parsed;
   try {
@@ -691,20 +703,20 @@ var draftState = (draftPath, resolveSchema) => {
   } catch (err) {
     return {
       kind: "invalid",
-      errors: [`not valid JSON: ${err instanceof Error ? err.message : String(err)}`]
+      errors: [`not valid JSON: ${errMsg(err)}`]
     };
   }
   let schemaPath;
   try {
     schemaPath = resolveSchema(parsed);
   } catch (err) {
-    return { kind: "invalid", errors: [err instanceof Error ? err.message : String(err)] };
+    return { kind: "invalid", errors: [errMsg(err)] };
   }
   try {
     const { valid, errors } = validateAgainstSchema(parsed, schemaPath);
     return valid ? { kind: "valid" } : { kind: "invalid", errors };
   } catch (err) {
-    return { kind: "invalid", errors: [err instanceof Error ? err.message : String(err)] };
+    return { kind: "invalid", errors: [errMsg(err)] };
   }
 };
 var readNudges = (counterPath) => {
@@ -805,6 +817,10 @@ var writesToDraft = (toolName, toolInput, draftPath) => {
 };
 var singleWriterMessage = (draftPath) => `Only the main agent may write ${draftPath}. When a subagent writes it too, the concurrent writers clobber each other and the review comes out empty. Do NOT write, edit, or redirect into ${draftPath} \u2014 instead, return the findings you discovered in your reply (the field names are in the schema); the main agent collects every subagent's reported findings and writes the draft itself.`;
 var seedMarkerPath = (draftPath) => `${draftPath}.seed`;
+var lastValidPath = (draftPath) => {
+  const ext = extname(draftPath);
+  return join(dirname(draftPath), `${basename(draftPath, ext)}.last-valid${ext}`);
+};
 var mainHasWrittenDraft = (draftMtimeMs, seedMarkerMtimeMs) => draftMtimeMs !== null && (seedMarkerMtimeMs === null || draftMtimeMs > seedMarkerMtimeMs);
 var spawnFloorMessage = (draftPath) => `Write your own first-pass findings to ${draftPath} before spawning subagents \u2014 a review must never depend on subagents alone, and a pre-seeded draft does not count until you have revised it yourself this run. Write ${draftPath} from what you have read so far (preliminary findings are fine), run \`code-review validate ${draftPath} --explain\` until it passes, then fan out; your subagents run in the background, so keep refining the draft as their reports arrive.`;
 var forceBackgroundSpawn = (toolInput) => ({
@@ -821,6 +837,10 @@ var denyPreTool = (reason) => ({
     permissionDecisionReason: reason
   }
 });
+var isSubagentHookInput = (input) => {
+  const agentId = asRecord(input)?.["agent_id"];
+  return typeof agentId === "string" && agentId.length > 0;
+};
 var evaluateBudgetHook = (input, params) => {
   const rec = asRecord(input);
   const inputs = {
@@ -831,8 +851,7 @@ var evaluateBudgetHook = (input, params) => {
     reserve: params.reserve
   };
   const phase = decideBudget(inputs);
-  const agentId = rec?.["agent_id"];
-  const isSubagent = typeof agentId === "string" && agentId.length > 0;
+  const isSubagent = isSubagentHookInput(input);
   switch (rec?.["hook_event_name"]) {
     case "PostToolBatch":
       return phase.kind === "ok" ? {} : {
@@ -1123,7 +1142,7 @@ var loadTestReport = (path) => {
     raw = JSON.parse(readFileSync(path, "utf-8"));
   } catch (err) {
     process.stderr.write(
-      `Warning: could not read test report at ${path}: ${err instanceof Error ? err.message : String(err)} \u2014 omitting test panel
+      `Warning: could not read test report at ${path}: ${errMsg(err)} \u2014 omitting test panel
 `
     );
     return void 0;
@@ -1139,12 +1158,9 @@ var loadTestReport = (path) => {
   return decoded.right;
 };
 var parseHtmlUrl = (raw) => {
-  try {
-    const parsed = JSON.parse(raw);
-    return typeof parsed.html_url === "string" ? parsed.html_url : void 0;
-  } catch {
-    return void 0;
-  }
+  const parsed = tryParseJson(raw);
+  const htmlUrl = parsed.ok ? asRecord(parsed.value)?.["html_url"] : void 0;
+  return typeof htmlUrl === "string" ? htmlUrl : void 0;
 };
 var commentPayload = (c) => ({
   path: c.path,
@@ -1168,7 +1184,7 @@ var postInlineReview = async (repo, prNumber, headSha, comments, inDiff, stickyU
   } catch (err) {
     if (comments.length === 0) throw err;
     process.stderr.write(
-      `Warning: the batched inline review on PR #${String(prNumber)} was rejected (${err instanceof Error ? err.message : String(err)}) \u2014 posting the review body-only, then each comment individually to keep the ones GitHub accepts (issue #57)
+      `Warning: the batched inline review on PR #${String(prNumber)} was rejected (${errMsg(err)}) \u2014 posting the review body-only, then each comment individually to keep the ones GitHub accepts (issue #57)
 `
     );
     const url = parseHtmlUrl(await ghApi(reviewsEndpoint, reviewBody(false)));
@@ -1183,7 +1199,7 @@ var postInlineReview = async (repo, prNumber, headSha, comments, inDiff, stickyU
         const finding = inDiff[i];
         if (finding) unposted.push(finding);
         process.stderr.write(
-          `Warning: inline comment on ${c.path}:${String(c.line)} rejected (${e instanceof Error ? e.message : String(e)}) \u2014 surfacing that finding in the sticky instead (issue #57)
+          `Warning: inline comment on ${c.path}:${String(c.line)} rejected (${errMsg(e)}) \u2014 surfacing that finding in the sticky instead (issue #57)
 `
         );
       }
@@ -1210,12 +1226,11 @@ var findBotComment = async (repo, prNumber, botLogin, marker, ghApi) => {
   return { id: parsed.id, body: parsed.body };
 };
 var parseCommentRef = (raw) => {
-  try {
-    const parsed = JSON.parse(raw);
-    return typeof parsed.id === "number" && typeof parsed.html_url === "string" ? { id: parsed.id, html_url: parsed.html_url } : null;
-  } catch {
-    return null;
-  }
+  const parsed = tryParseJson(raw);
+  const rec = parsed.ok ? asRecord(parsed.value) : null;
+  const id = rec?.["id"];
+  const html_url = rec?.["html_url"];
+  return typeof id === "number" && typeof html_url === "string" ? { id, html_url } : null;
 };
 var patchComment = async (repo, commentId, body, ghApi) => {
   const stdout = await ghApi(
@@ -1273,7 +1288,7 @@ var dismissReviews = async (repo, prNumber, ids, ghApi) => {
       );
     } catch (err) {
       process.stderr.write(
-        `Warning: failed to dismiss prior review #${String(id)} on PR #${String(prNumber)}: ${err instanceof Error ? err.message : String(err)}
+        `Warning: failed to dismiss prior review #${String(id)} on PR #${String(prNumber)}: ${errMsg(err)}
 `
       );
     }
@@ -1325,7 +1340,7 @@ var listPriorBotCommentIds = async (repo, prNumber, botLogin, ghApi) => {
     ]);
   } catch (err) {
     process.stderr.write(
-      `Warning: could not list review threads to minimize stale comments on PR #${String(prNumber)}: ${err instanceof Error ? err.message : String(err)}
+      `Warning: could not list review threads to minimize stale comments on PR #${String(prNumber)}: ${errMsg(err)}
 `
     );
     return [];
@@ -1347,7 +1362,7 @@ var minimizeComments = async (prNumber, ids, ghApi) => {
       minimized += 1;
     } catch (err) {
       process.stderr.write(
-        `Warning: failed to minimize a stale review comment on PR #${String(prNumber)}: ${err instanceof Error ? err.message : String(err)}
+        `Warning: failed to minimize a stale review comment on PR #${String(prNumber)}: ${errMsg(err)}
 `
       );
     }
@@ -1558,7 +1573,7 @@ var post = async (input, ghApi = runGhApi) => {
       );
     } catch (err) {
       process.stderr.write(
-        `Warning: failed to update the sticky summary after the review: ${err instanceof Error ? err.message : String(err)}
+        `Warning: failed to update the sticky summary after the review: ${errMsg(err)}
 `
       );
     }
@@ -1648,7 +1663,7 @@ var downloadFailingJobLogs = async (repo, runId, outDir, ghApi) => {
       writeFileSync(join(outDir, `job_${String(job.id)}.log`), log);
     } catch (err) {
       process.stderr.write(
-        `Warning: failed to download logs for job ${String(job.id)}: ${err instanceof Error ? err.message : String(err)} \u2014 continuing with the logs retrieved so far
+        `Warning: failed to download logs for job ${String(job.id)}: ${errMsg(err)} \u2014 continuing with the logs retrieved so far
 `
       );
     }
@@ -1754,13 +1769,6 @@ var gateCandidate = (kind, rawCandidate) => {
   const resolution = resolve(kind, candidate);
   return resolution.kind === "ok" ? { version: resolution.version, candidate } : null;
 };
-var tryParseJson = (text) => {
-  try {
-    return { ok: true, value: JSON.parse(text) };
-  } catch {
-    return { ok: false };
-  }
-};
 var candidateFromJsonText = (kind, text) => {
   if (text === null) return null;
   const parsed = tryParseJson(text);
@@ -1789,6 +1797,10 @@ var ladderFailureDiagnostics = (input) => {
     lines.push(
       input.agentFilePath === void 0 ? "agent-file rung: no --agent-file given" : `agent-file rung: ${input.agentFilePath} did not validate (or was unreadable)`
     );
+    if (input.agentFileFallbackPath !== void 0)
+      lines.push(
+        `last-valid rung: ${input.agentFileFallbackPath} did not validate (or was absent)`
+      );
   }
   lines.push(
     isNullish(native.structuredOutput) ? "structured_output rung: absent (null) \u2014 the CLI's --json-schema likely did not enforce" : "structured_output rung: present but did not validate against the schema"
@@ -1815,13 +1827,16 @@ var okOutcome = (gated) => ({
 });
 var extractStructured = (input) => {
   const native = parseNativeForExtraction(input.native);
+  if (input.kind === "findings") {
+    for (const path of [input.agentFilePath, input.agentFileFallbackPath]) {
+      if (path === void 0) continue;
+      const fromFile = candidateFromJsonText(input.kind, readFileOrNull(path));
+      if (fromFile) return okOutcome(fromFile);
+    }
+  }
   if (isErrorEnvelope(native)) {
     return { kind: "error-envelope", detail: describeErrorEnvelope(native) };
   }
-  if (input.kind === "findings" && input.agentFilePath !== void 0) {
-    const fromFile = candidateFromJsonText(input.kind, readFileOrNull(input.agentFilePath));
-    if (fromFile) return okOutcome(fromFile);
-  }
   if (native.structuredOutput !== void 0) {
     const fromStructured = gateCandidate(input.kind, native.structuredOutput);
     if (fromStructured) return okOutcome(fromStructured);
@@ -1841,9 +1856,10 @@ var extractStructured = (input) => {
       };
     }
   }
+  const fallbackRung = input.agentFileFallbackPath ? ", last-valid snapshot" : "";
   return {
     kind: "none",
-    detail: `no --agent-file, structured_output, JSON result, or fenced block validated against the ${input.kind} schema`
+    detail: `no --agent-file${fallbackRung}, structured_output, JSON result, or fenced block validated against the ${input.kind} schema`
   };
 };
 
@@ -1880,8 +1896,13 @@ var mapModelUsage = (modelUsage) => Object.entries(modelUsage).map(([model, entr
   ...entry.cacheReadInputTokens !== void 0 ? { cache_read_tokens: entry.cacheReadInputTokens } : {},
   ...entry.cacheCreationInputTokens !== void 0 ? { cache_write_tokens: entry.cacheCreationInputTokens } : {}
 }));
-var findingsOutcome = (native, agentFilePath) => {
-  const ladder = extractStructured({ kind: "findings", native, agentFilePath });
+var findingsOutcome = (native, agentFilePath, agentFileFallbackPath) => {
+  const ladder = extractStructured({
+    kind: "findings",
+    native,
+    agentFilePath,
+    agentFileFallbackPath
+  });
   if (ladder.kind !== "ok")
     return { kind: "telemetry-only", reason: describeLadderFailure(ladder) };
   const resolution = resolve("findings", ladder.candidate);
@@ -1923,8 +1944,8 @@ var nativeTelemetry = (native, meta) => resolveTelemetry(
   meta
 );
 var absentTelemetry = (meta) => resolveTelemetry({ models: [], turns: 0, durationMs: 0, vendorCostUsd: null }, meta);
-var buildEnvelope = (telemetry, native, agentFilePath) => {
-  const outcome = findingsOutcome(native, agentFilePath);
+var buildEnvelope = (telemetry, native, agentFilePath, agentFileFallbackPath) => {
+  const outcome = findingsOutcome(native, agentFilePath, agentFileFallbackPath);
   switch (outcome.kind) {
     case "ok":
       return { schema_version: outcome.version, findings: outcome.findings, ...telemetry };
@@ -1943,11 +1964,25 @@ var adapt = (adapterName, native, agentFilePath, meta = {}) => {
     // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- exhaustive by design; AdapterName grows (e.g. "opencode") without collapsing this switch to an if
     case "claude-code": {
       if (native === void 0 || native === null)
-        return right(buildEnvelope(absentTelemetry(meta), void 0, agentFilePath));
+        return right(
+          buildEnvelope(
+            absentTelemetry(meta),
+            void 0,
+            agentFilePath,
+            meta.agentFileFallbackPath
+          )
+        );
       const decoded = ClaudeCodeEnvelopeCodec.decode(native);
       if (decoded._tag === "Left")
         return left("native envelope does not match the Claude Code output shape");
-      return right(buildEnvelope(nativeTelemetry(decoded.right, meta), native, agentFilePath));
+      return right(
+        buildEnvelope(
+          nativeTelemetry(decoded.right, meta),
+          native,
+          agentFilePath,
+          meta.agentFileFallbackPath
+        )
+      );
     }
   }
 };
@@ -1971,8 +2006,7 @@ var readJSON = (path) => {
   try {
     return JSON.parse(readFileSync(resolve$1(path), "utf-8"));
   } catch (err) {
-    fail(`Cannot read ${path}: ${err instanceof Error ? err.message : String(err)}`);
-    throw new Error("unreachable", { cause: err });
+    return fail(`Cannot read ${path}: ${errMsg(err)}`);
   }
 };
 var fail = (msg) => {
@@ -1985,19 +2019,19 @@ var readJSONOrAbsent = (path) => {
     try {
       return { text: readFileSync(resolve$1(path), "utf-8") };
     } catch (err) {
-      return { error: err instanceof Error ? err.message : String(err) };
+      return { error: errMsg(err) };
     }
   })();
   if ("error" in read) {
     process.stderr.write(
-      `code-review: native envelope ${path} could not be read (${read.error}) \u2014 proceeding with no native telemetry (issue #39)
+      `code-review: native envelope ${path} could not be read (${read.error}) \u2014 proceeding with no native telemetry
 `
     );
     return void 0;
   }
   if (read.text.trim() === "") {
     process.stderr.write(
-      `code-review: native envelope ${path} is empty \u2014 proceeding with no native telemetry (issue #39)
+      `code-review: native envelope ${path} is empty \u2014 proceeding with no native telemetry
 `
     );
     return void 0;
@@ -2006,7 +2040,7 @@ var readJSONOrAbsent = (path) => {
     return JSON.parse(read.text);
   } catch (err) {
     process.stderr.write(
-      `code-review: native envelope ${path} is not valid JSON (${err instanceof Error ? err.message : String(err)}) \u2014 proceeding with no native telemetry (issue #39)
+      `code-review: native envelope ${path} is not valid JSON (${errMsg(err)}) \u2014 proceeding with no native telemetry
 `
     );
     return void 0;
@@ -2022,34 +2056,29 @@ var readStdinJSON = () => {
     }
   })();
   if (raw.trim() === "") return null;
-  try {
-    return JSON.parse(raw);
-  } catch {
-    return null;
-  }
+  const parsed = tryParseJson(raw);
+  return parsed.ok ? parsed.value : null;
 };
 var decode = (either, label) => {
   try {
     return unsafeUnwrap(either);
   } catch {
-    fail(`${label} does not match expected shape`);
+    return fail(`${label} does not match expected shape`);
   }
-  throw new Error("unreachable");
 };
 var unwrapAdapt = (either) => {
   try {
     if (either._tag === "Left") throw new Error(either.left);
     return either.right;
   } catch (err) {
-    fail(err instanceof Error ? err.message : String(err));
+    return fail(errMsg(err));
   }
-  throw new Error("unreachable");
 };
 var transcriptFallbackFrom = (path) => {
   const tree = readTranscriptTree(resolve$1(path));
   if (tree.missing)
     process.stderr.write(
-      `code-review adapt: transcript ${path} is unreadable \u2014 no telemetry fallback (issue #36)
+      `code-review adapt: transcript ${path} is unreadable \u2014 no telemetry fallback
 `
     );
   const usage = sumTranscriptUsage(tree.entries);
@@ -2192,7 +2221,7 @@ var costCmd = defineCommand({
 var checkCostCmd = defineCommand({
   meta: {
     name: "check-cost",
-    description: "Sum real USD spend from a live/finished Claude Code transcript tree (main session + subagents) against a price map \u2014 the correct cost when no clean result envelope exists (issue #36) and the outlook the review agent tracks in flight (issue #38)"
+    description: "Sum real USD spend from a Claude Code transcript tree (main + subagents) against a price map"
   },
   args: {
     transcript: {
@@ -2209,7 +2238,7 @@ var checkCostCmd = defineCommand({
     const tree = readTranscriptTree(resolve$1(args.transcript));
     if (tree.missing) {
       process.stderr.write(
-        `code-review check-cost: transcript ${args.transcript} is unreadable \u2014 reporting zero spend (issue #36)
+        `code-review check-cost: transcript ${args.transcript} is unreadable \u2014 reporting zero spend
 `
       );
     }
@@ -2257,10 +2286,21 @@ var transcriptPathOf = (input) => {
   const tp = (typeof input === "object" && input !== null ? input : {})["transcript_path"];
   return typeof tp === "string" ? tp : void 0;
 };
+var snapshotIfValid = (draftPath) => {
+  try {
+    if (extractStructured({ kind: "findings", native: void 0, agentFilePath: draftPath }).kind === "ok")
+      copyFileSync(draftPath, lastValidPath(draftPath));
+  } catch (err) {
+    process.stderr.write(
+      `code-review: could not snapshot the last-valid draft (${errMsg(err)}) \u2014 any prior snapshot is unchanged
+`
+    );
+  }
+};
 var budgetHookCmd = defineCommand({
   meta: {
     name: "budget-hook",
-    description: "Self-dispatching Claude Code hook for budget discipline (issue #38): on PostToolBatch, steer the agent to converge once spend or wall-clock enters its soft wind-down reserve; on PreToolUse, inside the hard reserve, deny the budget-burning tools (subagent spawns, arbitrary shell, web) while leaving the draft-delivery path open. At every phase, the main agent's subagent spawns are denied until it has written its own first-pass draft (seed-draft's sidecar marker tells the seed apart), and permitted spawns are rewritten to run in the background so no batch join can block the spawner (issue #73). Reads the hook payload on stdin, measures spend from its transcript, and decides on $ and/or time. Degrades to a no-op on any error."
+    description: "Self-dispatching Claude Code budget hook: on PostToolBatch steer the agent to converge as spend/wall-clock nears the budget; on PreToolUse deny budget-burning tools under the hard reserve, gate subagent spawns until the main agent has drafted, and run permitted spawns in the background. Reads the hook payload on stdin; degrades to a no-op on error."
   },
   args: {
     draft: {
@@ -2329,13 +2369,13 @@ var budgetHookCmd = defineCommand({
           mtimeMsOf(seedMarkerPath(draftPath))
         )
       });
+      if (asRecord(input)?.["hook_event_name"] === "PostToolBatch" && !isSubagentHookInput(input))
+        snapshotIfValid(draftPath);
       process.stdout.write(`${JSON.stringify(output)}
 `);
     } catch (err) {
-      process.stderr.write(
-        `code-review budget-hook: degrading to no-op \u2014 ${err instanceof Error ? err.message : String(err)}
-`
-      );
+      process.stderr.write(`code-review budget-hook: degrading to no-op \u2014 ${errMsg(err)}
+`);
       process.stdout.write("{}\n");
     }
   }
@@ -2343,7 +2383,7 @@ var budgetHookCmd = defineCommand({
 var printSettingsCmd = defineCommand({
   meta: {
     name: "print-settings",
-    description: "Emit ONE Claude Code --settings JSON composing the review agent's discipline (issue #38): the Stop deliverable gate plus the budget hooks (PreToolUse forced convergence + PostToolBatch steer) wired from one self-dispatching command. The review job generates this once and passes it as --settings."
+    description: "Emit one Claude Code --settings JSON composing the Stop deliverable gate and the budget hooks (PreToolUse convergence + PostToolBatch steer) from one self-dispatching command"
   },
   args: {
     draft: {
@@ -2429,7 +2469,7 @@ var printSettingsCmd = defineCommand({
 var deadlineCmd = defineCommand({
   meta: {
     name: "deadline",
-    description: "Print the run's absolute deadline as Unix epoch seconds (now + --wall). The review job exports this as CODE_REVIEW_DEADLINE_EPOCH right before `claude -p` so every budget hook \u2014 the main agent's and each fan-out subagent's \u2014 measures the SAME true remaining wall instead of its own transcript's start, which reads \u22480 in a fresh subagent and leaves the fan-out unsteered (issue #45)."
+    description: "Print the run's absolute deadline as Unix epoch seconds (now + --wall) \u2014 exported as CODE_REVIEW_DEADLINE_EPOCH so every budget hook (main and subagents) measures the same remaining wall"
   },
   args: {
     wall: {
@@ -2510,13 +2550,17 @@ ${printableSchema(schemaPath)}
 var seedDraftCmd = defineCommand({
   meta: {
     name: "seed-draft",
-    description: "Write a valid findings $DRAFT before the review runs: the decoded findings from a prior review when one exists and still validates (incremental re-review), else an empty-but-valid scaffold \u2014 so a valid draft exists from turn 0 (issues #52, #53). Also drops a sidecar marker beside the seed so the budget hook can tell the untouched seed from a draft the agent wrote itself (issue #73). Prints the mode chosen (prior|empty|none \u2014 none when even the scaffold write failed) to stdout; always exits 0"
+    description: "Write a valid findings $DRAFT before the review runs: the decoded findings from a prior review when one exists and still validates (incremental re-review), else an empty-but-valid scaffold \u2014 so a valid draft exists from turn 0. Also drops a sidecar marker beside the seed so the budget hook can tell the untouched seed from a draft the agent wrote itself. Prints the mode to stdout (prior-same|prior-new when seeded, by whether the prior review examined this same commit; empty-had-prior when a prior review exists but its findings could not be loaded; empty on a first review; none when even the scaffold write failed) and always exits 0"
   },
   args: {
     prior: {
       type: "string",
       description: "Path to the prior-review JSON gather staged ({ id, body }, or the literal null); its embedded base64 findings marker is decoded and becomes the seed when it validates against the schema"
     },
+    "head-sha": {
+      type: "string",
+      description: "Current head SHA, compared against the prior review's embedded reviewed-sha to distinguish a same-commit re-review from a new-commit one; an unknown or mismatched prior SHA is treated as a new commit"
+    },
     out: {
       type: "string",
       description: "Path to write the seed $DRAFT to (an absolute path outside the worktree)",
@@ -2550,12 +2594,12 @@ var seedDraftCmd = defineCommand({
         writeFileSync(seedMarkerPath(outPath), "code-review seed marker\n");
       } catch (err) {
         process.stderr.write(
-          `Warning: could not write the seed marker beside ${outPath} (${err instanceof Error ? err.message : String(err)}) \u2014 the seeded draft will count as agent-written
+          `Warning: could not write the seed marker beside ${outPath} (${errMsg(err)}) \u2014 the seeded draft will count as agent-written
 `
         );
       }
     };
-    const writeEmptyScaffold = () => {
+    const writeScaffold = () => {
       try {
         writeFileSync(outPath, `${JSON.stringify(noticeFindings(""), null, 2)}
 `);
@@ -2564,16 +2608,16 @@ var seedDraftCmd = defineCommand({
           `Seeded ${outPath} with an empty valid scaffold \u2014 no decodable prior findings to build on
 `
         );
-        process.stdout.write("empty\n");
+        return true;
       } catch (err) {
         process.stderr.write(
-          `Warning: could not write the seed scaffold to ${outPath} (${err instanceof Error ? err.message : String(err)}) \u2014 the agent will create $DRAFT itself
+          `Warning: could not write the seed scaffold to ${outPath} (${errMsg(err)}) \u2014 the agent will create $DRAFT itself
 `
         );
-        process.stdout.write("none\n");
+        return false;
       }
     };
-    const priorFindings = (() => {
+    const priorBody = (() => {
       if (!args.prior) return null;
       const raw = (() => {
         try {
@@ -2582,46 +2626,47 @@ var seedDraftCmd = defineCommand({
           return null;
         }
       })();
-      const body = typeof raw === "object" && raw !== null && "body" in raw && typeof raw.body === "string" ? raw.body : null;
-      return body === null ? null : parseFindingsMarker(body);
+      return typeof raw === "object" && raw !== null && "body" in raw && typeof raw.body === "string" ? raw.body : null;
     })();
-    if (priorFindings === null) {
-      writeEmptyScaffold();
-      return;
-    }
-    const seededFromPrior = (() => {
+    const priorFindings = priorBody === null ? null : parseFindingsMarker(priorBody);
+    const seededFromPrior = priorFindings === null ? false : (() => {
       try {
         const schemaPath = args.schema ? resolve$1(args.schema) : schemaPathFor(kind, args["schema-version"]);
         if (!validateAgainstSchema(priorFindings, schemaPath).valid) return false;
         writeFileSync(outPath, `${JSON.stringify(priorFindings, null, 2)}
 `);
         writeSeedMarker();
+        const priorList = priorFindings.findings;
+        const count = Array.isArray(priorList) ? priorList.length : 0;
+        process.stderr.write(
+          `Seeded ${outPath} from the prior review (${String(count)} finding(s))
+`
+        );
         return true;
       } catch (err) {
         process.stderr.write(
-          `Warning: could not seed from the prior review (${err instanceof Error ? err.message : String(err)}) \u2014 falling back to the empty scaffold
+          `Warning: could not seed from the prior review (${errMsg(err)}) \u2014 falling back to the empty scaffold
 `
         );
         return false;
       }
     })();
-    if (seededFromPrior) {
-      const priorList = priorFindings.findings;
-      const count = Array.isArray(priorList) ? priorList.length : 0;
-      process.stderr.write(
-        `Seeded ${outPath} from the prior review (${String(count)} finding(s)) \u2014 verify each still holds against the current diff and refine in place
-`
-      );
-      process.stdout.write("prior\n");
-    } else {
-      writeEmptyScaffold();
-    }
+    const mode = (() => {
+      if (seededFromPrior) {
+        const priorSha = priorBody === null ? null : parseReviewedSha(priorBody);
+        return args["head-sha"] && priorSha && priorSha === args["head-sha"].toLowerCase() ? "prior-same" : "prior-new";
+      }
+      if (!writeScaffold()) return "none";
+      return priorBody === null ? "empty" : "empty-had-prior";
+    })();
+    process.stdout.write(`${mode}
+`);
   }
 });
 var adaptCmd = defineCommand({
   meta: {
     name: "adapt",
-    description: "Map a native agent-CLI result envelope onto the abstract SPEC \xA76.1 envelope"
+    description: "Map a native agent-CLI result envelope onto the abstract SPEC envelope"
   },
   args: {
     native: {
@@ -2638,6 +2683,10 @@ var adaptCmd = defineCommand({
       type: "string",
       description: "Path to a file the agent was told to write its own validated findings JSON to (wins over the native envelope's structured_output/result when it validates)"
     },
+    "agent-file-fallback": {
+      type: "string",
+      description: "Path to the last-valid findings snapshot, tried after --agent-file and before the native envelope; recovers the last valid state when a wall-clock kill left --agent-file truncated, so the review posts that instead of a 'did not complete' notice"
+    },
     route: {
       type: "string",
       description: 'Review route label to stamp into the envelope (e.g. "full review" or "mechanic")'
@@ -2648,7 +2697,7 @@ var adaptCmd = defineCommand({
     },
     transcript: {
       type: "string",
-      description: "Path to the session transcript (the main .jsonl). Its tree (main + subagents) is the source of the true wall + turn count \u2014 the native envelope only sees the main agent and under-reports a fan-out (issue #59) \u2014 and refills per-model usage too when the native has none (a wall-clock kill leaves it empty, so cost is real not $0.00 \u2014 issues #39/#36)"
+      description: "Path to the session transcript (main .jsonl). Its tree (main + subagents) gives the true wall + turn count the native envelope under-reports, and refills per-model usage when the native envelope is empty (e.g. after a wall-clock kill)"
     }
   },
   run: async ({ args }) => {
@@ -2656,6 +2705,7 @@ var adaptCmd = defineCommand({
       adapt(requireAdapterName(args.adapter), readJSONOrAbsent(args.native), args["agent-file"], {
         route: args.route,
         effort: args.effort,
+        agentFileFallbackPath: args["agent-file-fallback"],
         ...args.transcript ? {
           transcriptFallback: () => transcriptFallbackFrom(args.transcript)
         } : {}
@@ -2666,11 +2716,7 @@ var adaptCmd = defineCommand({
   }
 });
 var isExtractSchemaKind = (s) => s === "findings" || s === "triage";
-var requireExtractSchemaKind = (name) => {
-  if (isExtractSchemaKind(name)) return name;
-  fail(`Unknown kind "${name}" for extract \u2014 expected one of: findings, triage`);
-  throw new Error("unreachable");
-};
+var requireExtractSchemaKind = (name) => isExtractSchemaKind(name) ? name : fail(`Unknown kind "${name}" for extract \u2014 expected one of: findings, triage`);
 var failClosedTriage = (outcome) => ({
   safe: false,
   reasons: describeLadderFailure(outcome)
@@ -2764,7 +2810,7 @@ var validateFinding = (finding, repoRoot) => {
 var validatePatchesCmd = defineCommand({
   meta: {
     name: "validate-patches",
-    description: "Validate each finding's patch against the real PR-head tree, aligning the finding's range and keeping the patch when it anchors, keeping it unaligned when it's a pure insertion, or dropping it when it doesn't apply (issue #10)"
+    description: "Validate each finding's patch against the real PR-head tree: align the finding's range and keep the patch when it anchors, keep it unaligned for a pure insertion, or drop it when it doesn't apply"
   },
   args: {
     findings: {
@@ -2788,24 +2834,15 @@ var validatePatchesCmd = defineCommand({
 `);
   }
 });
-var requireAdapterName = (name) => {
-  if (isAdapterName(name)) return name;
-  fail(`Unknown adapter "${name}" \u2014 supported: claude-code`);
-  throw new Error("unreachable");
-};
+var requireAdapterName = (name) => isAdapterName(name) ? name : fail(`Unknown adapter "${name}" \u2014 supported: claude-code`);
 var isSchemaKind = (s) => s === "findings" || s === "triage" || s === "prices";
-var requireSchemaKind = (name) => {
-  if (isSchemaKind(name)) return name;
-  fail(`Unknown schema "${name}" \u2014 expected one of: findings, triage, prices`);
-  throw new Error("unreachable");
-};
+var requireSchemaKind = (name) => isSchemaKind(name) ? name : fail(`Unknown schema "${name}" \u2014 expected one of: findings, triage, prices`);
 var requireSchemaPath = (kind, version) => {
   try {
     return schemaPathFor(kind, version);
   } catch (err) {
-    fail(err instanceof Error ? err.message : String(err));
+    return fail(errMsg(err));
   }
-  throw new Error("unreachable");
 };
 var printSchemaCmd = defineCommand({
   meta: {
@@ -2911,7 +2948,7 @@ var stopGateCmd = defineCommand({
         bumpNudges(counterPath, nudges);
       } catch (err) {
         process.stderr.write(
-          `stop-gate: cannot persist nudge counter at ${counterPath} \u2192 allowing to avoid an unbounded block loop: ${err instanceof Error ? err.message : String(err)}
+          `stop-gate: cannot persist nudge counter at ${counterPath} \u2192 allowing to avoid an unbounded block loop: ${errMsg(err)}
 `
         );
         return;
@@ -3062,7 +3099,7 @@ var main = defineCommand({
   meta: {
     name: "code-review",
     version: packageVersion,
-    description: "Deterministic commenter for agentic PR review \u2014 gather, render, inline, post, adapt, extract, validate-patches, cost, check-cost, validate, seed-draft, stop-gate, budget-hook, print-settings, and deadline"
+    description: "Deterministic commenter for agentic PR review"
   },
   subCommands: {
     gather: gatherCmd,
@@ -3087,6 +3124,6 @@ if (!process.env["VITEST"]) {
   await runMain(main);
 }
 
-export { main };
+export { main, snapshotIfValid };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map