@jphutchins/code-review 0.1.0-alpha.1 → 0.1.0-alpha.10

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { defineCommand, runMain } from 'citty';
-import { readFileSync, writeFileSync } from 'fs';
-import { resolve as resolve$1, join } from 'path';
+import { readFileSync, writeFileSync, readdirSync } from 'fs';
+import { resolve as resolve$1, join, dirname } from 'path';
 import { Eta } from 'eta';
 import parseDiff from 'parse-diff';
 import { Ajv2020 } from 'ajv/dist/2020.js';
@@ -53,43 +53,196 @@ var computeCost = (models, prices, warn = defaultWarn) => {
   };
 };
 
+// src/patch.ts
+var HUNK_HEADER_RE = /^@@ -(\d+)(?:,\d+)? \+\d+(?:,\d+)? @@/;
+var hunkOldStart = (line) => {
+  const raw = HUNK_HEADER_RE.exec(line)?.[1];
+  return raw !== void 0 ? Number(raw) : null;
+};
+var classifyBodyLine = (line) => {
+  if (line.startsWith(" ")) return { kind: "context", text: line.slice(1) };
+  if (line.startsWith("-")) return { kind: "removed", text: line.slice(1) };
+  if (line.startsWith("+")) return { kind: "added", text: line.slice(1) };
+  return null;
+};
+var trimmedMiddle = (body) => {
+  const first = body.findIndex((l) => l.kind !== "context");
+  if (first === -1) return [];
+  const last = body.findLastIndex((l) => l.kind !== "context");
+  return body.slice(first, last + 1);
+};
+var isContiguousChange = (middle) => {
+  if (middle.some((l) => l.kind === "context")) return false;
+  const firstAdded = middle.findIndex((l) => l.kind === "added");
+  if (firstAdded === -1) return true;
+  return middle.slice(0, firstAdded).every((l) => l.kind === "removed") && middle.slice(firstAdded).every((l) => l.kind === "added");
+};
+var removedRange = (body, oldStart) => body.reduce(
+  (acc, line) => line.kind === "added" ? acc : {
+    lineNumber: acc.lineNumber + 1,
+    firstRemoved: line.kind === "removed" && acc.firstRemoved === null ? acc.lineNumber : acc.firstRemoved,
+    lastRemoved: line.kind === "removed" ? acc.lineNumber : acc.lastRemoved
+  },
+  { lineNumber: oldStart, firstRemoved: null, lastRemoved: null }
+);
+var drop = (reason) => ({
+  kind: "drop",
+  reason
+});
+var keep = (reason) => ({
+  kind: "keep",
+  reason
+});
+var parseHunk = (patch) => {
+  const rawLines = patch.split("\n");
+  const lines = rawLines.length > 0 && rawLines[rawLines.length - 1] === "" ? rawLines.slice(0, -1) : rawLines;
+  const headerHits = lines.reduce(
+    (acc, line, index) => {
+      const oldStart = hunkOldStart(line);
+      return oldStart !== null ? [...acc, { index, oldStart }] : acc;
+    },
+    []
+  );
+  if (headerHits.length !== 1) {
+    return drop(`expected exactly one hunk, got ${String(headerHits.length)}`);
+  }
+  const hit = headerHits[0];
+  if (hit === void 0) return drop("malformed hunk header");
+  const bodyRaw = lines.slice(hit.index + 1).filter((line) => !line.startsWith("\\"));
+  const classified = bodyRaw.map(classifyBodyLine);
+  if (classified.some((line) => line === null)) return drop("malformed hunk body line");
+  const body = classified.filter((line) => line !== null);
+  return { kind: "ok", oldStart: hit.oldStart, body };
+};
+var validatePatch = (patch, fileLines) => {
+  const parsed = parseHunk(patch);
+  if (parsed.kind === "drop") return parsed;
+  const { oldStart, body } = parsed;
+  const oldSideTexts = body.filter((l) => l.kind !== "added").map((l) => l.text);
+  const expected = fileLines.slice(oldStart - 1, oldStart - 1 + oldSideTexts.length);
+  const oldSideMatches = expected.length === oldSideTexts.length && expected.every((line, i) => line === oldSideTexts[i]);
+  if (!oldSideMatches) {
+    return drop(
+      `patch context does not match the file at lines ${String(oldStart)}..${String(oldStart + oldSideTexts.length - 1)}`
+    );
+  }
+  if (!isContiguousChange(trimmedMiddle(body))) {
+    return drop("change is not a single contiguous block");
+  }
+  const removedCount = body.filter((l) => l.kind === "removed").length;
+  const addedCount = body.filter((l) => l.kind === "added").length;
+  if (removedCount === 0 && addedCount === 0) return drop("hunk contains no changes");
+  if (removedCount === 0) {
+    return keep("pure insertion applies cleanly but has no removed range to anchor a suggestion");
+  }
+  const { firstRemoved, lastRemoved } = removedRange(body, oldStart);
+  if (firstRemoved === null || lastRemoved === null) return drop("malformed hunk body");
+  return { kind: "anchored", startLine: firstRemoved, endLine: lastRemoved };
+};
+var patchToSuggestion = (patch) => {
+  const parsed = parseHunk(patch);
+  if (parsed.kind === "drop") return parsed;
+  const { body } = parsed;
+  if (!isContiguousChange(trimmedMiddle(body))) {
+    return drop("change is not a single contiguous block");
+  }
+  const removedCount = body.filter((l) => l.kind === "removed").length;
+  const addedLines = body.filter((l) => l.kind === "added");
+  if (removedCount === 0 && addedLines.length === 0) return drop("hunk contains no changes");
+  if (removedCount === 0) return drop("pure insertion can't be expressed as a suggestion");
+  return addedLines.map((l) => l.text).join("\n");
+};
+
+// src/surface.ts
+var severityEmoji = (s) => {
+  switch (s) {
+    case "critical":
+      return "\u{1F534}";
+    case "major":
+      return "\u{1F7E0}";
+    case "minor":
+      return "\u{1F535}";
+    case "nit":
+      return "\u26AA";
+    default:
+      return "\u2753";
+  }
+};
+var EMBED_LIMIT = 4e4;
+var AGENTS_STOP_DIRECTIVE = "<!-- AGENTS: STOP \u2014 do not parse the prose below; decode this findings JSON and read schema_version first. -->";
+var encodeMarker = (document, jsonUrl, limit) => {
+  const b64 = Buffer.from(JSON.stringify(document), "utf-8").toString("base64");
+  const marker = b64.length <= limit ? `<!-- code-review:findings-json;base64 ${b64} -->` : jsonUrl ? `<!-- code-review:findings-json ${jsonUrl} -->` : "";
+  return marker ? `${AGENTS_STOP_DIRECTIVE}
+${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 escapeFence = (text) => text.replace(/```/g, "`` ` ``");
+var projectPatch = (patch) => {
+  if (patch === void 0) return { kind: "none" };
+  const lowered = patchToSuggestion(patch);
+  return typeof lowered === "string" ? { kind: "suggestion", text: escapeFence(lowered) } : { kind: "patch", raw: escapeFence(patch) };
+};
+var formatConfidence = (n) => n.toFixed(2);
+var reviewBodyPointer = (headSha, stickyUrl, marker) => {
+  const sha7 = headSha.slice(0, 7);
+  const linkLine = stickyUrl ? `\u{1F916} Automated code review for \`${sha7}\` \u2014 see the [summary comment](${stickyUrl}) for the verdict, walkthrough, and cost.` : `\u{1F916} Automated code review for \`${sha7}\` \u2014 see the summary comment for the verdict, walkthrough, and cost.`;
+  return marker ? `${marker}
+
+${linkLine}` : linkLine;
+};
+
 // src/render.ts
-var escapeBackticks = (text) => text.replace(/```/g, "`` ` ``");
 var escapePipes = (text) => text.replace(/\|/g, "\\|");
 var escapeCodeBackticks = (text) => text.replace(/`/g, "-");
 var sanitizeFinding = (f) => ({
   ...f,
   title: escapePipes(f.title),
   path: escapeCodeBackticks(f.path),
-  suggestion: f.suggestion ? escapeBackticks(f.suggestion) : f.suggestion
+  patchProjection: projectPatch(f.patch)
 });
+var emptySeverityCounts = () => ({
+  critical: 0,
+  major: 0,
+  minor: 0,
+  nit: 0
+});
+var computeSeverityCounts = (findings) => findings.reduce(
+  (acc, f) => f.severity in acc ? { ...acc, [f.severity]: acc[f.severity] + 1 } : acc,
+  emptySeverityCounts()
+);
 var render = (input) => {
   const eta = new Eta({ autoTrim: false });
   const usageAvailable = input.envelope !== null;
   const costReport = input.envelope ? computeCost(input.envelope.models, input.prices) : null;
-  const route = input.route;
+  const pricesProvided = input.pricesProvided ?? true;
+  const route = input.route ?? input.envelope?.route ?? null;
+  const effort = input.effort ?? input.envelope?.effort ?? null;
   const modelNames = input.envelope ? input.envelope.models.map((m) => m.model).join(", ") : "";
-  const findings = input.findings.findings.map(sanitizeFinding);
-  const safeFindings = { ...input.findings, findings };
-  const uniqueFiles = [...new Set(findings.map((f) => f.path))];
   return eta.renderString(input.template, {
-    findings: safeFindings,
+    findings: input.findings,
     envelope: input.envelope,
     usageAvailable,
     costReport,
+    pricesProvided,
     route,
-    effort: input.effort ?? null,
+    effort,
     modelNames,
     testReport: input.testReport ?? null,
     reviewedSha: input.reviewedSha ?? "0000000000000000000000000000000000000000",
-    totalCount: findings.length,
-    fileCount: uniqueFiles.length,
-    // REC-CO-1: nits (and only nits) fold into <details>; everything else stays visible.
-    visibleFindings: findings.filter((f) => f.severity !== "nit"),
-    nitFindings: findings.filter((f) => f.severity === "nit"),
-    suggestionCount: findings.filter((f) => f.suggestion).length,
+    postedAt: input.postedAt ?? "",
+    severityCounts: input.severityCounts ?? computeSeverityCounts(input.findings.findings),
+    strays: (input.strays ?? []).map(sanitizeFinding),
+    inlineDisposition: input.inlineDisposition ?? null,
+    runUrl: input.runUrl ?? null,
+    jsonUrl: input.jsonUrl ?? null,
+    findingsPointer: input.findingsPointer ?? findingsPointer(input.findings, input.jsonUrl),
+    reviewUrl: input.reviewUrl ?? null,
     formatTokens: (n) => Number.isFinite(n) && n >= 0 ? n.toLocaleString("en-US") : "\u2014",
-    formatCost: (n) => Number.isFinite(n) ? `$${n.toFixed(3)}` : "\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).
+    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";
       const s = Math.round(ms / 1e3);
@@ -107,20 +260,8 @@ var render = (input) => {
           return `\u2753 ${v}`;
       }
     },
-    severityEmoji: (s) => {
-      switch (s) {
-        case "critical":
-          return "\u{1F534}";
-        case "major":
-          return "\u{1F7E0}";
-        case "minor":
-          return "\u{1F535}";
-        case "nit":
-          return "\u26AA";
-        default:
-          return "\u2753";
-      }
-    }
+    severityEmoji,
+    formatConfidence
   });
 };
 var key = (path, line) => `${path}:${String(line)}`;
@@ -177,33 +318,33 @@ var partitionFindings = (findings, index) => {
 };
 
 // src/inline.ts
-var escapeBackticks2 = (text) => text.replace(/```/g, "`` ` ``");
-var buildCommentBody = (f) => {
-  const parts = [f.body];
-  if (f.suggestion !== null && f.suggestion !== void 0) {
-    const safe = escapeBackticks2(f.suggestion);
-    parts.push(`\`\`\`suggestion
-${safe}
-\`\`\``);
-  }
-  return parts.join("\n\n");
-};
-var renderCommentBody = (f, eta, template) => {
-  return eta.renderString(template, {
+var formatModels = (models) => models.length > 0 ? models.map((m) => `\`${m}\``).join("/") : "an AI model";
+var renderCommentBody = (f, eta, template, modelsText, jsonUrl, pointer) => (
+  // Eta.renderString returns string | Promise<string>; with autoTrim:false it's always sync.
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
+  eta.renderString(template, {
     ...f,
-    suggestion: f.suggestion !== null && f.suggestion !== void 0 ? escapeBackticks2(f.suggestion) : null
-  });
-};
-var buildInlineComments = (findings, diff, inlineTemplate) => {
+    patchProjection: projectPatch(f.patch),
+    severityEmoji,
+    formatConfidence,
+    modelsText,
+    jsonUrl: jsonUrl ?? null,
+    findingsPointer: pointer
+  })
+);
+var buildInlineComments = (findings, diff, context) => {
+  const { inlineTemplate, models = [], jsonUrl, findings: fullFindings } = context;
   const index = indexDiff(diff);
   const { inDiff, strays } = partitionFindings(findings, index);
-  const eta = inlineTemplate ? new Eta({ autoTrim: false }) : null;
+  const eta = new Eta({ autoTrim: false });
+  const modelsText = formatModels(models);
   const comments = inDiff.map((f) => {
+    const pointer = fullFindings ? findingPointer(f, fullFindings.schema_version, jsonUrl) : "";
     const comment = {
       path: f.path,
       line: f.end_line,
       side: defaultSide(f.side),
-      body: eta && inlineTemplate ? renderCommentBody(f, eta, inlineTemplate) : buildCommentBody(f)
+      body: renderCommentBody(f, eta, inlineTemplate, modelsText, jsonUrl, pointer)
     };
     if (f.start_line < f.end_line) {
       return {
@@ -230,6 +371,119 @@ var renderStraysSection = (strays) => {
     ...items
   ].join("\n");
 };
+var asRecord = (u) => typeof u === "object" && u !== null && !Array.isArray(u) ? u : null;
+var readFileOrNull = (path) => {
+  try {
+    return readFileSync(path, "utf-8");
+  } catch {
+    return null;
+  }
+};
+
+// src/transcript.ts
+var numField = (rec, key2) => {
+  const v = rec[key2];
+  return typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : 0;
+};
+var messageUsage = (entry) => {
+  const rec = asRecord(entry);
+  if (rec === null || rec["type"] !== "assistant") return null;
+  const msg = asRecord(rec["message"]);
+  if (msg === null) return null;
+  const model = msg["model"];
+  const usage = asRecord(msg["usage"]);
+  if (typeof model !== "string" || usage === null) return null;
+  const id = msg["id"];
+  return {
+    id: typeof id === "string" ? id : null,
+    model,
+    input: numField(usage, "input_tokens"),
+    output: numField(usage, "output_tokens"),
+    cacheRead: numField(usage, "cache_read_input_tokens"),
+    cacheWrite: numField(usage, "cache_creation_input_tokens")
+  };
+};
+var tsMsOf = (entry) => {
+  const rec = asRecord(entry);
+  const ts = rec?.["timestamp"];
+  if (typeof ts !== "string") return null;
+  const ms = Date.parse(ts);
+  return Number.isNaN(ms) ? null : ms;
+};
+var EMPTY_TOTALS = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+var parseJsonl = (text) => text.split("\n").filter((line) => line.trim() !== "").flatMap((line) => {
+  try {
+    return [JSON.parse(line)];
+  } catch {
+    return [];
+  }
+});
+var sumTranscriptUsage = (entries) => {
+  const summed = entries.reduce(
+    (acc, entry) => {
+      const u = messageUsage(entry);
+      if (u === null) return acc;
+      if (u.id !== null && acc.seen.has(u.id)) return acc;
+      if (u.id !== null) acc.seen.add(u.id);
+      const prev = acc.totals.get(u.model) ?? EMPTY_TOTALS;
+      acc.totals.set(u.model, {
+        input: prev.input + u.input,
+        output: prev.output + u.output,
+        cacheRead: prev.cacheRead + u.cacheRead,
+        cacheWrite: prev.cacheWrite + u.cacheWrite
+      });
+      return { totals: acc.totals, turns: acc.turns + 1, seen: acc.seen };
+    },
+    { totals: /* @__PURE__ */ new Map(), turns: 0, seen: /* @__PURE__ */ new Set() }
+  );
+  const models = [...summed.totals].map(([model, t4]) => ({
+    model,
+    input_tokens: t4.input,
+    output_tokens: t4.output,
+    cache_read_tokens: t4.cacheRead,
+    cache_write_tokens: t4.cacheWrite
+  }));
+  const bounds = entries.reduce(
+    (acc, entry) => {
+      const ms = tsMsOf(entry);
+      if (ms === null) return acc;
+      return {
+        min: acc.min === null || ms < acc.min ? ms : acc.min,
+        max: acc.max === null || ms > acc.max ? ms : acc.max
+      };
+    },
+    { min: null, max: null }
+  );
+  return {
+    models,
+    turns: summed.turns,
+    durationMs: bounds.min !== null && bounds.max !== null ? bounds.max - bounds.min : 0,
+    firstTsMs: bounds.min,
+    lastTsMs: bounds.max
+  };
+};
+var subagentFiles = (mainPath) => {
+  try {
+    return readdirSync(join(dirname(mainPath), "subagents")).filter((name) => name.endsWith(".jsonl")).map((name) => join(dirname(mainPath), "subagents", name));
+  } catch {
+    return [];
+  }
+};
+var readTranscriptTree = (mainPath) => {
+  const mainText = readFileOrNull(mainPath);
+  const mainEntries = mainText === null ? [] : parseJsonl(mainText);
+  const inlineSidechains = mainEntries.some((e) => asRecord(e)?.["isSidechain"] === true);
+  const siblings = inlineSidechains ? [] : subagentFiles(mainPath);
+  const siblingReads = siblings.flatMap((path) => {
+    const text = readFileOrNull(path);
+    return text === null ? [] : [{ path, entries: parseJsonl(text) }];
+  });
+  return {
+    entries: [...mainEntries, ...siblingReads.flatMap((r) => r.entries)],
+    files: [...mainText === null ? [] : [mainPath], ...siblingReads.map((r) => r.path)],
+    missing: mainText === null
+  };
+};
 var SeverityCodec = t.union([
   t.literal("critical"),
   t.literal("major"),
@@ -257,14 +511,16 @@ var FindingShape = t.intersection([
     end_line: LineNumber,
     severity: SeverityCodec,
     title: t.string,
-    body: t.string
+    description: t.string,
+    reasoning: t.string,
+    confidence: Confidence
   }),
   t.partial({
     side: SideCodec,
-    suggestion: t.union([t.string, t.null]),
-    confidence: Confidence,
     code: t.string,
-    code_url: t.string
+    code_url: t.string,
+    recommendation: t.string,
+    patch: t.string
   })
 ]);
 var EndGeStart = t.refinement(
@@ -310,7 +566,9 @@ var ResultEnvelopeCodec = t.intersection([
     duration_ms: TokenCount
   }),
   t.partial({
-    vendor_cost_usd: t.union([t.number, t.null])
+    vendor_cost_usd: t.union([t.number, t.null]),
+    route: t.string,
+    effort: t.string
   })
 ]);
 var ModelPricesCodec = t.type({
@@ -338,7 +596,13 @@ var TestSummaryCodec = t.intersection([
     failures: t.array(TestFailureCodec)
   })
 ]);
-var DEFAULT_SCHEMA_VERSION = "0.2.0";
+var DEFAULT_SCHEMA_VERSION = "0.4.0";
+var noticeFindings = (summary) => ({
+  schema_version: DEFAULT_SCHEMA_VERSION,
+  summary,
+  verdict: "comment",
+  findings: []
+});
 
 // src/validate.ts
 var addFormats = _addFormats;
@@ -374,10 +638,221 @@ var unsafeUnwrap = (decoded) => {
   if (decoded._tag === "Right") return decoded.right;
   throw new Error("io-ts decode failed \u2014 data does not match expected shape");
 };
+
+// src/stop-gate.ts
+var whatsWrong = (state, draftPath, kind) => {
+  switch (state.kind) {
+    case "missing":
+      return `${draftPath} does not exist yet`;
+    case "unreadable":
+      return `${draftPath} could not be read: ${state.error}`;
+    case "invalid":
+      return `${draftPath} does not validate against the ${kind} schema:
+${state.errors.map((e) => `  - ${e}`).join("\n")}`;
+  }
+};
+var decideGate = (state, nudges, maxNudges, draftPath, kind) => {
+  if (state.kind === "valid") return { kind: "allow" };
+  if (nudges >= maxNudges) return { kind: "allow" };
+  return {
+    kind: "block",
+    reason: [
+      `This review is not complete \u2014 ${whatsWrong(state, draftPath, kind)}`,
+      `The only deliverable is a ${kind} document that validates against the ${kind} schema \u2014 run "code-review print-schema ${kind}" to see the exact shape.`,
+      `Write it to ${draftPath}, then run "code-review validate ${draftPath} --kind ${kind}" until it exits 0 before ending your turn.`
+    ].join("\n")
+  };
+};
+var draftState = (draftPath, resolveSchema) => {
+  let raw;
+  try {
+    raw = readFileSync(draftPath, "utf-8");
+  } catch (err) {
+    if (err instanceof Error && err.code === "ENOENT") {
+      return { kind: "missing" };
+    }
+    return { kind: "unreadable", error: err instanceof Error ? err.message : String(err) };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    return {
+      kind: "invalid",
+      errors: [`not valid JSON: ${err instanceof Error ? err.message : String(err)}`]
+    };
+  }
+  let schemaPath;
+  try {
+    schemaPath = resolveSchema(parsed);
+  } catch (err) {
+    return { kind: "invalid", errors: [err instanceof Error ? err.message : String(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)] };
+  }
+};
+var readNudges = (counterPath) => {
+  try {
+    const n = Number.parseInt(readFileSync(counterPath, "utf-8").trim(), 10);
+    return Number.isInteger(n) && n >= 0 ? n : 0;
+  } catch {
+    return 0;
+  }
+};
+var bumpNudges = (counterPath, current) => {
+  writeFileSync(counterPath, `${String(current + 1)}
+`);
+};
+var shellQuote = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
+var defaultHookCommand = (draftPath, opts) => [
+  "code-review stop-gate --draft",
+  shellQuote(draftPath),
+  ...opts.kind ? ["--kind", shellQuote(opts.kind)] : [],
+  ...opts.schema ? ["--schema", shellQuote(opts.schema)] : [],
+  ...opts.schemaVersion ? ["--schema-version", shellQuote(opts.schemaVersion)] : [],
+  ...opts.maxNudges ? ["--max-nudges", shellQuote(opts.maxNudges)] : [],
+  ...opts.counter ? ["--counter", shellQuote(opts.counter)] : []
+].join(" ");
+var stopHookSettings = (command) => ({
+  hooks: { Stop: [{ hooks: [{ type: "command", command }] }] }
+});
+
+// src/budget.ts
+var DEFAULT_RESERVE = { frac: 0.15, flatUsd: 0.02, flatMs: 12e4 };
+var SOFT_MULTIPLE = 2;
+var costAxis = (i) => i.spentUsd !== null && i.budgetUsd !== null && i.budgetUsd > 0 ? { used: i.spentUsd, limit: i.budgetUsd, flat: i.reserve.flatUsd } : null;
+var timeAxis = (i) => i.elapsedMs !== null && i.wallMs !== null && i.wallMs > 0 ? { used: i.elapsedMs, limit: i.wallMs, flat: i.reserve.flatMs } : null;
+var axisSeverity = (a, frac) => {
+  const hardReserve = Math.max(a.flat, frac * a.limit);
+  const remaining = a.limit - a.used;
+  if (remaining <= hardReserve) return 2;
+  if (remaining <= SOFT_MULTIPLE * hardReserve) return 1;
+  return 0;
+};
+var decideBudget = (i) => {
+  const worst = [costAxis(i), timeAxis(i)].filter((a) => a !== null).reduce((max, a) => Math.max(max, axisSeverity(a, i.reserve.frac)), 0);
+  return worst === 2 ? { kind: "hard" } : worst === 1 ? { kind: "soft" } : { kind: "ok" };
+};
+var pct = (n) => `${String(Math.round(n * 100))}%`;
+var money = (n) => `$${n.toFixed(2)}`;
+var mins = (ms) => `${(ms / 6e4).toFixed(1)}m`;
+var spendClause = (i) => i.spentUsd === null ? null : i.budgetUsd !== null && i.budgetUsd > 0 ? `spent ${money(i.spentUsd)}/${money(i.budgetUsd)} (${pct(i.spentUsd / i.budgetUsd)})` : `spent ${money(i.spentUsd)}`;
+var timeClause = (i) => i.elapsedMs === null ? null : i.wallMs !== null && i.wallMs > 0 ? `${mins(i.elapsedMs)}/${mins(i.wallMs)} elapsed (${pct(i.elapsedMs / i.wallMs)})` : `${mins(i.elapsedMs)} elapsed`;
+var directive = (phase, draftPath) => phase.kind === "hard" ? `Budget nearly exhausted \u2014 STOP all new investigation now. Write your COMPLETE findings to ${draftPath} and run \`code-review validate ${draftPath}\` until it passes. Other tools are blocked until that draft is written.` : `Wind down investigation and write your COMPLETE findings to ${draftPath} now, then validate \u2014 you may run out of budget before you finish otherwise.`;
+var budgetMessage = (i, phase, draftPath) => {
+  const status = [spendClause(i), timeClause(i)].filter((c) => c !== null).join(" \xB7 ");
+  return `Budget check \u2014 ${status}. ${directive(phase, draftPath)}`;
+};
+var invokesCodeReviewValidate = (toolInput) => {
+  const cmd = asRecord(toolInput)?.["command"];
+  return typeof cmd === "string" && /\bcode-review\s+validate(?![\w-])/.test(cmd);
+};
+var SPAWN_TOOLS = /* @__PURE__ */ new Set(["Agent", "Task"]);
+var WEB_TOOLS = /* @__PURE__ */ new Set(["WebFetch", "WebSearch"]);
+var blockedDuringConvergence = (toolName, toolInput) => {
+  if (SPAWN_TOOLS.has(toolName) || WEB_TOOLS.has(toolName)) return true;
+  if (toolName === "Bash") return !invokesCodeReviewValidate(toolInput);
+  return false;
+};
+var evaluateBudgetHook = (input, params) => {
+  const rec = asRecord(input);
+  const inputs = {
+    spentUsd: params.spentUsd,
+    budgetUsd: params.budgetUsd,
+    elapsedMs: params.elapsedMs,
+    wallMs: params.wallMs,
+    reserve: params.reserve
+  };
+  const phase = decideBudget(inputs);
+  switch (rec?.["hook_event_name"]) {
+    case "PostToolBatch":
+      return phase.kind === "ok" ? {} : {
+        hookSpecificOutput: {
+          hookEventName: "PostToolBatch",
+          additionalContext: budgetMessage(inputs, phase, params.draftPath)
+        }
+      };
+    case "PreToolUse": {
+      if (phase.kind !== "hard") return {};
+      const toolName = rec["tool_name"];
+      if (typeof toolName === "string" && blockedDuringConvergence(toolName, rec["tool_input"]))
+        return {
+          hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: "deny",
+            permissionDecisionReason: budgetMessage(inputs, phase, params.draftPath)
+          }
+        };
+      return {};
+    }
+    default:
+      return {};
+  }
+};
+var parseWallMs = (raw) => {
+  const m = /^(\d+(?:\.\d+)?)(ms|s|m|h)?$/.exec(raw.trim());
+  if (m === null) return null;
+  const [, num = "", unit = "s"] = m;
+  const n = Number.parseFloat(num);
+  if (!Number.isFinite(n)) return null;
+  switch (unit) {
+    case "ms":
+      return n;
+    case "s":
+      return n * 1e3;
+    case "m":
+      return n * 6e4;
+    default:
+      return n * 36e5;
+  }
+};
+var parseFraction = (raw, fallback) => {
+  if (raw === void 0) return fallback;
+  const n = Number.parseFloat(raw);
+  return Number.isFinite(n) && n >= 0 && n <= 1 ? n : fallback;
+};
+var budgetHookCommand = (draftPath, opts) => [
+  "code-review budget-hook --draft",
+  shellQuote(draftPath),
+  ...opts.budgetUsd ? ["--budget-usd", shellQuote(opts.budgetUsd)] : [],
+  ...opts.wall ? ["--wall", shellQuote(opts.wall)] : [],
+  ...opts.prices ? ["--prices", shellQuote(opts.prices)] : [],
+  ...opts.reserveFrac ? ["--reserve-frac", shellQuote(opts.reserveFrac)] : [],
+  ...opts.reserveUsd ? ["--reserve-usd", shellQuote(opts.reserveUsd)] : [],
+  ...opts.reserveWall ? ["--reserve-wall", shellQuote(opts.reserveWall)] : []
+].join(" ");
+
+// src/format.ts
+var FENCE_RE = /^\s*```/;
+var scanLine = (state, line) => {
+  if (FENCE_RE.test(line)) {
+    return { lines: [...state.lines, line], inFence: !state.inFence, blankRun: 0 };
+  }
+  if (state.inFence) {
+    return { lines: [...state.lines, line], inFence: true, blankRun: 0 };
+  }
+  const trimmed = line.replace(/[ \t]+$/, "");
+  if (trimmed !== "") {
+    return { lines: [...state.lines, trimmed], inFence: false, blankRun: 0 };
+  }
+  const blankRun = state.blankRun + 1;
+  return blankRun === 1 ? { lines: [...state.lines, ""], inFence: false, blankRun } : { ...state, blankRun };
+};
+var formatMarkdown = (md) => {
+  const { lines } = md.split("\n").reduce(scanLine, { lines: [], inFence: false, blankRun: 0 });
+  return `${lines.join("\n").replace(/\n+$/, "")}
+`;
+};
+var pad2 = (n) => String(n).padStart(2, "0");
+var formatUtc = (d) => `${String(d.getUTCFullYear())}-${pad2(d.getUTCMonth() + 1)}-${pad2(d.getUTCDate())} ${pad2(d.getUTCHours())}:${pad2(d.getUTCMinutes())} UTC`;
 var identity = (decoded) => decoded;
 var findingsTable = [
   {
-    minor: "0.2",
+    minor: "0.4",
     defaultVersion: DEFAULT_SCHEMA_VERSION,
     schemaFile: "findings.schema.json",
     codec: FindingsCodec,
@@ -502,7 +977,6 @@ var fetchDiff = async (repo, prNumber, ghApi) => ghApi([
 // src/post.ts
 var DEFAULT_MARKER = "<!-- code-review -->";
 var MAX_SUGGESTION_LINES = 10;
-var REVIEWED_SHA_RE = /<!-- reviewed-sha: ([0-9a-f]{7,40}) -->/;
 var countSuggestionLines = (text) => text.split("\n").length;
 var checkLongSuggestions = (comments) => {
   const longFiles = [];
@@ -522,13 +996,6 @@ var checkLongSuggestions = (comments) => {
   });
   return { comments: adjusted, longFiles };
 };
-var extractReviewedSha = (commentBody) => REVIEWED_SHA_RE.exec(commentBody)?.[1] ?? null;
-var noticeFindings = (message) => ({
-  schema_version: DEFAULT_SCHEMA_VERSION,
-  summary: `### \u26A0\uFE0F ${message}`,
-  verdict: "comment",
-  findings: []
-});
 var loadFindings = (path) => {
   let raw;
   try {
@@ -590,9 +1057,18 @@ var loadTestReport = (path) => {
   }
   return decoded.right;
 };
-var postInlineReview = async (repo, prNumber, headSha, comments, ghApi) => {
+var parseHtmlUrl = (raw) => {
+  try {
+    const parsed = JSON.parse(raw);
+    return typeof parsed.html_url === "string" ? parsed.html_url : void 0;
+  } catch {
+    return void 0;
+  }
+};
+var postInlineReview = async (repo, prNumber, headSha, comments, stickyUrl, marker, ghApi) => {
+  const pointer = reviewBodyPointer(headSha, stickyUrl, marker);
   const body = JSON.stringify({
-    body: "",
+    body: pointer,
     commit_id: headSha,
     event: "COMMENT",
     comments: comments.map((c) => ({
@@ -600,10 +1076,14 @@ var postInlineReview = async (repo, prNumber, headSha, comments, ghApi) => {
       line: c.line,
       side: c.side,
       ...c.start_line !== void 0 && c.start_side !== void 0 ? { start_line: c.start_line, start_side: c.start_side } : {},
-      body: c.body
+      body: formatMarkdown(c.body)
     }))
   });
-  await ghApi([`repos/${repo}/pulls/${String(prNumber)}/reviews`, "--input", "-"], body);
+  const stdout = await ghApi(
+    [`repos/${repo}/pulls/${String(prNumber)}/reviews`, "--input", "-"],
+    body
+  );
+  return parseHtmlUrl(stdout);
 };
 var findBotComment = async (repo, prNumber, botLogin, marker, ghApi) => {
   const stdout = await ghApi(
@@ -623,33 +1103,45 @@ var findBotComment = async (repo, prNumber, botLogin, marker, ghApi) => {
   const parsed = JSON.parse(last);
   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;
+  }
+};
 var patchComment = async (repo, commentId, body, ghApi) => {
-  await ghApi(
+  const stdout = await ghApi(
     [`repos/${repo}/issues/comments/${String(commentId)}`, "--input", "-"],
     JSON.stringify({ body })
   );
+  const htmlUrl = parseHtmlUrl(stdout);
+  return htmlUrl !== void 0 ? { html_url: htmlUrl } : null;
 };
 var postComment = async (repo, prNumber, body, ghApi) => {
-  await ghApi(
+  const stdout = await ghApi(
     [`repos/${repo}/issues/${String(prNumber)}/comments`, "--input", "-"],
     JSON.stringify({ body })
   );
+  return parseCommentRef(stdout);
 };
 var upsertSticky = async (repo, prNumber, existing, body, ghApi) => {
   if (existing !== null) {
-    await patchComment(repo, existing.id, body, ghApi);
+    const patched = await patchComment(repo, existing.id, body, ghApi);
     process.stderr.write(
       `Updated sticky comment #${String(existing.id)} on PR #${String(prNumber)}
 `
     );
-  } else {
-    await postComment(repo, prNumber, body, ghApi);
-    process.stderr.write(`Posted new sticky comment on PR #${String(prNumber)}
-`);
+    return { id: existing.id, url: patched?.html_url };
   }
+  const posted = await postComment(repo, prNumber, body, ghApi);
+  process.stderr.write(`Posted new sticky comment on PR #${String(prNumber)}
+`);
+  return posted ? { id: posted.id, url: posted.html_url } : null;
 };
 var isBotReview = (r) => typeof r === "object" && r !== null && typeof r.id === "number" && typeof r.state === "string" && typeof r.user?.login === "string";
-var fetchBotReviewIds = async (repo, prNumber, botLogin, ghApi) => {
+var fetchBotReviews = async (repo, prNumber, botLogin, ghApi) => {
   const stdout = await ghApi([`repos/${repo}/pulls/${String(prNumber)}/reviews`, "--paginate"]);
   let reviews;
   try {
@@ -658,10 +1150,12 @@ var fetchBotReviewIds = async (repo, prNumber, botLogin, ghApi) => {
     return [];
   }
   if (!Array.isArray(reviews)) return [];
-  return reviews.filter((r) => isBotReview(r)).filter((r) => r.user.login === botLogin && r.state !== "DISMISSED").map((r) => r.id);
+  return reviews.filter(isBotReview).filter((r) => r.user.login === botLogin && r.state !== "DISMISSED").map((r) => ({
+    id: r.id,
+    commitId: typeof r.commit_id === "string" ? r.commit_id : ""
+  }));
 };
-var dismissPriorBotReviews = async (repo, prNumber, botLogin, ghApi) => {
-  const ids = await fetchBotReviewIds(repo, prNumber, botLogin, ghApi);
+var dismissReviews = async (repo, prNumber, ids, ghApi) => {
   for (const id of ids) {
     try {
       await ghApi(
@@ -682,6 +1176,84 @@ var dismissPriorBotReviews = async (repo, prNumber, botLogin, ghApi) => {
     }
   }
 };
+var REVIEW_THREAD_COMMENTS_QUERY = "query($owner:String!,$name:String!,$pr:Int!){repository(owner:$owner,name:$name){pullRequest(number:$pr){reviewThreads(first:100){pageInfo{hasNextPage}nodes{comments(first:100){nodes{id isMinimized author{login} originalCommit{oid}}}}}}}}";
+var MINIMIZE_COMMENT_MUTATION = "mutation($id:ID!){minimizeComment(input:{subjectId:$id,classifier:OUTDATED}){minimizedComment{isMinimized}}}";
+var supersededCommentId = (c, headSha, logins) => {
+  if (typeof c !== "object" || c === null) return null;
+  const o = c;
+  const login = o.author?.login;
+  const oid = o.originalCommit?.oid;
+  return typeof o.id === "string" && o.isMinimized !== true && typeof login === "string" && logins.includes(login) && typeof oid === "string" && oid !== headSha ? o.id : null;
+};
+var supersededBotCommentIds = (raw, headSha, botLogin) => {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { ids: [], truncated: false };
+  }
+  const conn = parsed.data?.repository?.pullRequest?.reviewThreads;
+  const truncated = conn?.pageInfo?.hasNextPage === true;
+  const nodes = conn?.nodes;
+  if (!Array.isArray(nodes)) return { ids: [], truncated };
+  const logins = [botLogin.replace(/\[bot\]$/, ""), botLogin];
+  const ids = nodes.flatMap((t4) => {
+    const cnodes = t4.comments?.nodes;
+    return Array.isArray(cnodes) ? cnodes.map((c) => supersededCommentId(c, headSha, logins)).filter((id) => id !== null) : [];
+  });
+  return { ids, truncated };
+};
+var minimizeSupersededComments = async (repo, prNumber, headSha, botLogin, ghApi) => {
+  const slash = repo.indexOf("/");
+  if (slash <= 0) return;
+  const owner = repo.slice(0, slash);
+  const name = repo.slice(slash + 1);
+  let raw;
+  try {
+    raw = await ghApi([
+      "graphql",
+      "-f",
+      `query=${REVIEW_THREAD_COMMENTS_QUERY}`,
+      "-f",
+      `owner=${owner}`,
+      "-f",
+      `name=${name}`,
+      "-F",
+      `pr=${String(prNumber)}`
+    ]);
+  } 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)}
+`
+    );
+    return;
+  }
+  const { ids, truncated } = supersededBotCommentIds(raw, headSha, botLogin);
+  if (truncated) {
+    process.stderr.write(
+      `Note: PR #${String(prNumber)} has more than 100 review threads \u2014 only the first 100 were scanned for stale bot comments
+`
+    );
+  }
+  let minimized = 0;
+  for (const id of ids) {
+    try {
+      await ghApi(["graphql", "-f", `query=${MINIMIZE_COMMENT_MUTATION}`, "-f", `id=${id}`]);
+      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)}
+`
+      );
+    }
+  }
+  if (minimized > 0) {
+    process.stderr.write(
+      `Minimized ${String(minimized)} stale inline comment(s) from superseded reviews on PR #${String(prNumber)}
+`
+    );
+  }
+};
 var post = async (input, ghApi = runGhApi) => {
   const candidates = await fetchPrCandidates(input.repo, input.headSha, ghApi);
   const resolution = resolvePr(candidates, input.headBranch);
@@ -706,24 +1278,28 @@ var post = async (input, ghApi = runGhApi) => {
     DEFAULT_MARKER,
     ghApi
   );
-  const previousReviewedSha = existingSticky ? extractReviewedSha(existingSticky.body) : null;
-  const isRerunOfSameSha = previousReviewedSha !== null && previousReviewedSha === input.headSha;
   const prices = JSON.parse(readFileSync(input.pricesPath, "utf-8"));
   const decodedPrices = PriceMapCodec.decode(prices);
   if (decodedPrices._tag === "Left") {
     throw new Error(`Price map at ${input.pricesPath} does not match the expected shape`);
   }
   const template = readFileSync(input.templatePath, "utf-8");
-  const inlineTemplate = input.inlineTemplatePath ? readFileSync(input.inlineTemplatePath, "utf-8") : void 0;
-  const renderNotice = (message) => render({
-    findings: noticeFindings(message),
-    envelope: null,
-    prices: decodedPrices.right,
-    template,
-    route: input.route,
-    reviewedSha: input.headSha,
-    effort: input.effort
-  });
+  const inlineTemplate = readFileSync(input.inlineTemplatePath, "utf-8");
+  const renderNotice = (message) => formatMarkdown(
+    render({
+      findings: noticeFindings(`### \u26A0\uFE0F ${message}`),
+      envelope: null,
+      prices: decodedPrices.right,
+      pricesProvided: input.pricesProvided,
+      template,
+      route: input.route,
+      reviewedSha: input.headSha,
+      effort: input.effort,
+      runUrl: input.runUrl,
+      jsonUrl: input.jsonUrl,
+      postedAt: input.postedAt
+    })
+  );
   if (isEmptyDiff(diff)) {
     await upsertSticky(
       input.repo,
@@ -749,27 +1325,36 @@ var post = async (input, ghApi = runGhApi) => {
   const envelope = loadEnvelope(input.envelopePath);
   const testReport = input.testReportPath ? loadTestReport(input.testReportPath) : void 0;
   if (envelope === null) {
-    const body2 = render({
-      findings,
-      envelope: null,
-      prices: decodedPrices.right,
-      template,
-      route: input.route,
-      reviewedSha: input.headSha,
-      effort: input.effort,
-      testReport
-    });
-    await upsertSticky(input.repo, prNumber, existingSticky, body2, ghApi);
+    const body = formatMarkdown(
+      render({
+        findings,
+        envelope: null,
+        prices: decodedPrices.right,
+        pricesProvided: input.pricesProvided,
+        template,
+        route: input.route,
+        reviewedSha: input.headSha,
+        effort: input.effort,
+        testReport,
+        inlineDisposition: { kind: "no-envelope" },
+        runUrl: input.runUrl,
+        jsonUrl: input.jsonUrl,
+        postedAt: input.postedAt
+      })
+    );
+    await upsertSticky(input.repo, prNumber, existingSticky, body, ghApi);
     process.stderr.write(
       "Result envelope missing or malformed \u2014 posted sticky summary without usage/cost data; no inline review\n"
     );
     process.exit(0);
   }
-  const { comments: rawComments, strays } = buildInlineComments(
-    findings.findings,
-    diff,
-    inlineTemplate
-  );
+  const findingsMarker = findingsPointer(findings, input.jsonUrl);
+  const { comments: rawComments, strays } = buildInlineComments(findings.findings, diff, {
+    inlineTemplate,
+    models: envelope.models.map((m) => m.model),
+    findings,
+    jsonUrl: input.jsonUrl
+  });
   const { comments, longFiles } = checkLongSuggestions(rawComments);
   for (const wf of longFiles) {
     process.stderr.write(
@@ -777,43 +1362,87 @@ var post = async (input, ghApi = runGhApi) => {
 `
     );
   }
-  let body = render({
+  const botReviews = comments.length > 0 ? await fetchBotReviews(input.repo, prNumber, input.botLogin, ghApi) : [];
+  const alreadyReviewedThisSha = botReviews.some((r) => r.commitId === input.headSha);
+  const initialDisposition = comments.length > 0 ? alreadyReviewedThisSha ? { kind: "suppressed-existing-review", sha: input.headSha } : void 0 : strays.length > 0 ? { kind: "none-in-diff" } : void 0;
+  const commonRenderInput = {
     findings,
     envelope,
     prices: decodedPrices.right,
+    pricesProvided: input.pricesProvided,
     template,
     route: input.route,
     reviewedSha: input.headSha,
     effort: input.effort,
-    testReport
-  });
-  const straysMd = renderStraysSection(strays);
-  if (straysMd.length > 0) body += straysMd;
-  if (longFiles.length > 0) {
-    body += `
+    testReport,
+    severityCounts: computeSeverityCounts(findings.findings),
+    strays,
+    runUrl: input.runUrl,
+    jsonUrl: input.jsonUrl,
+    findingsPointer: findingsMarker,
+    postedAt: input.postedAt
+  };
+  const longFilesNote = longFiles.length > 0 ? `
 
 ---
 
-> **Note:** ${String(longFiles.length)} suggestion(s) exceeded GitHub's ~10-line inline suggestion limit and were omitted from inline comments. See the findings above for details.
-`;
-  }
-  if (!isRerunOfSameSha && previousReviewedSha !== null) {
-    await dismissPriorBotReviews(input.repo, prNumber, input.botLogin, ghApi);
-  }
-  await upsertSticky(input.repo, prNumber, existingSticky, body, ghApi);
-  if (isRerunOfSameSha) {
+> **Note:** ${String(longFiles.length)} suggestion(s) exceeded GitHub's ~10-line inline suggestion limit and were omitted from the inline comments; the affected findings remain in the review.
+` : "";
+  const renderBody = (inlineDisposition, reviewUrl2) => formatMarkdown(render({ ...commonRenderInput, inlineDisposition, reviewUrl: reviewUrl2 }) + longFilesNote);
+  const stickyRef = await upsertSticky(
+    input.repo,
+    prNumber,
+    existingSticky,
+    renderBody(initialDisposition),
+    ghApi
+  );
+  if (comments.length === 0) return;
+  if (alreadyReviewedThisSha) {
     process.stderr.write(
-      `Head SHA ${input.headSha} matches the previous review \u2014 updated sticky only, no new inline review
+      `A completed bot review already exists for ${input.headSha} \u2014 updated sticky only, no new inline review
 `
     );
     return;
   }
-  if (comments.length > 0) {
-    await postInlineReview(input.repo, prNumber, input.headSha, comments, ghApi);
-    process.stderr.write(
-      `Posted ${String(comments.length)} inline comments on PR #${String(prNumber)}
+  const stalePriorReviewIds = botReviews.filter((r) => r.commitId !== input.headSha).map((r) => r.id);
+  if (stalePriorReviewIds.length > 0) {
+    await dismissReviews(input.repo, prNumber, stalePriorReviewIds, ghApi);
+  }
+  const reviewUrl = await postInlineReview(
+    input.repo,
+    prNumber,
+    input.headSha,
+    comments,
+    stickyRef?.url,
+    findingsMarker,
+    ghApi
+  );
+  process.stderr.write(
+    `Posted ${String(comments.length)} inline comments on PR #${String(prNumber)}
 `
-    );
+  );
+  await minimizeSupersededComments(input.repo, prNumber, input.headSha, input.botLogin, ghApi);
+  if (stickyRef !== null) {
+    const confirmedDisposition = {
+      kind: "posted",
+      count: comments.length,
+      sha: input.headSha
+    };
+    try {
+      await patchComment(
+        input.repo,
+        stickyRef.id,
+        renderBody(confirmedDisposition, reviewUrl),
+        ghApi
+      );
+      process.stderr.write(`Linked sticky comment #${String(stickyRef.id)} to the review
+`);
+    } catch (err) {
+      process.stderr.write(
+        `Warning: failed to link the sticky summary to the review: ${err instanceof Error ? err.message : String(err)}
+`
+      );
+    }
   }
 };
 var renderOutputs = (result) => {
@@ -952,6 +1581,8 @@ var gather = async (input, ghApi = runGhApi, gitRun = runGit) => {
     diffSize: Buffer.byteLength(diff, "utf8")
   };
 };
+
+// src/extract.ts
 var fieldOf = (raw, key2) => typeof raw === "object" && raw !== null && key2 in raw ? raw[key2] : void 0;
 var parseNativeForExtraction = (raw) => ({
   result: fieldOf(raw, "result"),
@@ -1011,13 +1642,6 @@ var tryParseJson = (text) => {
     return { ok: false };
   }
 };
-var readFileOrNull = (path) => {
-  try {
-    return readFileSync(path, "utf-8");
-  } catch {
-    return null;
-  }
-};
 var candidateFromJsonText = (kind, text) => {
   if (text === null) return null;
   const parsed = tryParseJson(text);
@@ -1025,7 +1649,7 @@ var candidateFromJsonText = (kind, text) => {
 };
 var FENCE_OPEN = /^\s*(`{3,})/;
 var FENCE_MARKER_ONLY = /^`+$/;
-var scanLine = (state, line) => {
+var scanLine2 = (state, line) => {
   if (state.openLength === null) {
     const opened = FENCE_OPEN.exec(line)?.[1]?.length;
     return opened !== void 0 ? { blocks: state.blocks, openLength: opened, buffer: [] } : state;
@@ -1034,7 +1658,27 @@ var scanLine = (state, line) => {
   const closes = FENCE_MARKER_ONLY.test(trimmed) && trimmed.length >= state.openLength;
   return closes ? { blocks: [...state.blocks, state.buffer.join("\n")], openLength: null, buffer: [] } : { ...state, buffer: [...state.buffer, line] };
 };
-var scanFencedBlocks = (text) => text.split("\n").reduce(scanLine, { blocks: [], openLength: null, buffer: [] }).blocks;
+var scanFencedBlocks = (text) => text.split("\n").reduce(scanLine2, { blocks: [], openLength: null, buffer: [] }).blocks;
+var ladderFailureDiagnostics = (input) => {
+  const native = parseNativeForExtraction(input.native);
+  const preview = (s) => {
+    const flat = s.replace(/\s+/g, " ").trim();
+    return flat.length > 200 ? `${flat.slice(0, 200)}\u2026` : flat;
+  };
+  const lines = [];
+  if (input.kind === "findings") {
+    lines.push(
+      input.agentFilePath === void 0 ? "agent-file rung: no --agent-file given" : `agent-file rung: ${input.agentFilePath} did not validate (or was unreadable)`
+    );
+  }
+  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"
+  );
+  lines.push(
+    typeof native.result === "string" ? `result rung: ${String(native.result.length)} chars, ${String(scanFencedBlocks(native.result).length)} fenced JSON block(s), none validated; preview: ${preview(native.result)}` : "result rung: absent or not a string"
+  );
+  return lines.join("\n");
+};
 var describeLadderFailure = (outcome) => {
   switch (outcome.kind) {
     case "error-envelope":
@@ -1117,36 +1761,74 @@ 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 adaptClaudeCode = (native, agentFilePath) => {
-  const outcome = extractStructured({ kind: "findings", native, agentFilePath });
-  if (outcome.kind !== "ok") {
-    return left(describeLadderFailure(outcome));
-  }
-  const resolution = resolve("findings", outcome.candidate);
-  return resolution.kind === "ok" ? right({
-    schema_version: resolution.version,
-    findings: resolution.value,
+var findingsOutcome = (native, agentFilePath) => {
+  const ladder = extractStructured({ kind: "findings", native, agentFilePath });
+  if (ladder.kind !== "ok")
+    return { kind: "telemetry-only", reason: describeLadderFailure(ladder) };
+  const resolution = resolve("findings", ladder.candidate);
+  return resolution.kind === "ok" ? { kind: "ok", version: resolution.version, findings: resolution.value } : {
+    kind: "telemetry-only",
+    reason: "internal error: the extraction ladder validated a candidate the registry then rejected"
+  };
+};
+var withMeta = (base, meta) => ({
+  ...base,
+  ...meta.route ? { route: meta.route } : {},
+  ...meta.effort ? { effort: meta.effort } : {}
+});
+var nativeTelemetry = (native, meta) => withMeta(
+  {
     models: mapModelUsage(native.modelUsage),
     turns: native.num_turns,
     duration_ms: native.duration_ms,
     vendor_cost_usd: native.total_cost_usd ?? null
-  }) : left(
-    "internal error: the extraction ladder validated a candidate the registry then rejected"
-  );
+  },
+  meta
+);
+var absentTelemetry = (meta) => withMeta({ models: [], turns: 0, duration_ms: 0, vendor_cost_usd: null }, meta);
+var buildEnvelope = (telemetry, native, agentFilePath) => {
+  const outcome = findingsOutcome(native, agentFilePath);
+  switch (outcome.kind) {
+    case "ok":
+      return { schema_version: outcome.version, findings: outcome.findings, ...telemetry };
+    case "telemetry-only":
+      return {
+        schema_version: DEFAULT_SCHEMA_VERSION,
+        findings: noticeFindings(`### \u26A0\uFE0F Review did not complete
+
+${outcome.reason}`),
+        ...telemetry
+      };
+  }
 };
-var adapt = (adapterName, native, agentFilePath) => {
+var adapt = (adapterName, native, agentFilePath, meta = {}) => {
   switch (adapterName) {
     // 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));
       const decoded = ClaudeCodeEnvelopeCodec.decode(native);
-      if (decoded._tag === "Left") {
+      if (decoded._tag === "Left")
         return left("native envelope does not match the Claude Code output shape");
-      }
-      return adaptClaudeCode(decoded.right, agentFilePath);
+      return right(buildEnvelope(nativeTelemetry(decoded.right, meta), native, agentFilePath));
     }
   }
 };
 
+// src/settings.ts
+var composeReviewSettings = (opts) => {
+  const budgetCommand = budgetHookCommand(opts.draftPath, opts.budget);
+  return {
+    hooks: {
+      Stop: [
+        { hooks: [{ type: "command", command: defaultHookCommand(opts.draftPath, opts.stop) }] }
+      ],
+      PreToolUse: [{ hooks: [{ type: "command", command: budgetCommand }] }],
+      PostToolBatch: [{ hooks: [{ type: "command", command: budgetCommand }] }]
+    }
+  };
+};
+
 // src/index.ts
 var readJSON = (path) => {
   try {
@@ -1161,6 +1843,54 @@ var fail = (msg) => {
 `);
   process.exit(1);
 };
+var readJSONOrAbsent = (path) => {
+  const read = (() => {
+    try {
+      return { text: readFileSync(resolve$1(path), "utf-8") };
+    } catch (err) {
+      return { error: err instanceof Error ? err.message : String(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)
+`
+    );
+    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)
+`
+    );
+    return void 0;
+  }
+  try {
+    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)
+`
+    );
+    return void 0;
+  }
+};
+var readStdinJSON = () => {
+  if (process.stdin.isTTY) return null;
+  const raw = (() => {
+    try {
+      return readFileSync(0, "utf-8");
+    } catch {
+      return "";
+    }
+  })();
+  if (raw.trim() === "") return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+};
 var decode = (either, label) => {
   try {
     return unsafeUnwrap(either);
@@ -1181,12 +1911,13 @@ var unwrapAdapt = (either) => {
 var bundledPath = (...segments) => resolve$1(import.meta.dirname, "..", ...segments);
 var packageVersion = JSON.parse(readFileSync(bundledPath("package.json"), "utf-8")).version;
 var resolveTemplatePath = (templateArg) => templateArg ? resolve$1(templateArg) : bundledPath("templates", "comment.eta");
-var resolvePricesPath = (pricesArg) => {
-  if (pricesArg) return resolve$1(pricesArg);
+var resolveInlineTemplatePath = (templateArg) => templateArg ? resolve$1(templateArg) : bundledPath("templates", "inline.eta");
+var resolvePrices = (pricesArg) => {
+  if (pricesArg) return { kind: "provided", path: resolve$1(pricesArg) };
   process.stderr.write(
-    "code-review: no --prices given \u2014 using the bundled example prices (all zero); cost figures will be $0\n"
+    "code-review: no --prices given \u2014 cost will be reported as N/A (no price map to recompute from)\n"
   );
-  return bundledPath("schema", "prices.example.json");
+  return { kind: "absent", path: bundledPath("schema", "prices.example.json") };
 };
 var TEST_REPORT_DESCRIPTION = 'Path to a JSON test summary: {"passed": number, "failed": number, "total": number, "failures"?: [{"name": string, "message"?: string}]}';
 var renderCmd = defineCommand({
@@ -1219,12 +1950,11 @@ var renderCmd = defineCommand({
     },
     route: {
       type: "string",
-      description: 'Review route label (e.g. "full review" or "mechanic")',
-      required: true
+      description: "Review route label; overrides the envelope's route when set (default: read from the envelope)"
     },
     effort: {
       type: "string",
-      description: 'Effort label to render in the route line (e.g. "max" or "low"); omitted when absent'
+      description: "Effort label; overrides the envelope's effort when set (default: read from the envelope)"
     },
     "test-report": {
       type: "string",
@@ -1235,19 +1965,21 @@ var renderCmd = defineCommand({
     const findings = decode(FindingsCodec.decode(readJSON(args.findings)), "findings");
     const envelope = decode(ResultEnvelopeCodec.decode(readJSON(args.usage)), "envelope");
     const templatePath = resolveTemplatePath(args.template);
-    const pricesPath = resolvePricesPath(args.prices);
-    const prices = decode(PriceMapCodec.decode(readJSON(pricesPath)), "prices");
+    const priceResolution = resolvePrices(args.prices);
+    const prices = decode(PriceMapCodec.decode(readJSON(priceResolution.path)), "prices");
     const template = readFileSync(templatePath, "utf-8");
     const testReport = args["test-report"] ? decode(TestSummaryCodec.decode(readJSON(args["test-report"])), "test report") : void 0;
     const output = render({
       findings,
       envelope,
       prices,
+      pricesProvided: priceResolution.kind === "provided",
       template,
       reviewedSha: args["reviewed-sha"],
       route: args.route,
       effort: args.effort,
-      testReport
+      testReport,
+      postedAt: formatUtc(/* @__PURE__ */ new Date())
     });
     process.stdout.write(output);
   }
@@ -1270,14 +2002,17 @@ var inlineCmd = defineCommand({
     },
     template: {
       type: "string",
-      description: "Path to inline comment Eta template (default: built-in format)"
+      description: "Path to inline comment Eta template (default: bundled templates/inline.eta)"
     }
   },
   run: async ({ args }) => {
     const findings = decode(FindingsCodec.decode(readJSON(args.findings)), "findings");
     const diff = readFileSync(resolve$1(args.diff), "utf-8");
-    const inlineTemplate = args.template ? readFileSync(resolve$1(args.template), "utf-8") : void 0;
-    const { comments, strays } = buildInlineComments(findings.findings, diff, inlineTemplate);
+    const inlineTemplate = readFileSync(resolveInlineTemplatePath(args.template), "utf-8");
+    const { comments, strays } = buildInlineComments(findings.findings, diff, {
+      inlineTemplate,
+      findings
+    });
     process.stdout.write(
       JSON.stringify({ comments, strays, stray_markdown: renderStraysSection(strays) }, null, 2)
     );
@@ -1307,8 +2042,217 @@ var costCmd = defineCommand({
     process.stdout.write(JSON.stringify(report, null, 2));
   }
 });
-var declaredSchemaVersion = (raw) => typeof raw === "object" && raw !== null && "schema_version" in raw ? typeof raw.schema_version === "string" ? raw.schema_version : void 0 : void 0;
-var derivedSchemaVersion = (kind, raw) => kind === "findings" ? declaredSchemaVersion(raw) : void 0;
+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)"
+  },
+  args: {
+    transcript: {
+      type: "positional",
+      description: "Path to the session transcript JSONL (the hook's transcript_path)",
+      required: true
+    },
+    prices: {
+      type: "string",
+      description: "Path to price map JSON (default: bundled schema/prices.example.json \u2014 token totals stay real, cost reads as $0)"
+    }
+  },
+  run: async ({ args }) => {
+    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)
+`
+      );
+    }
+    const usage = sumTranscriptUsage(tree.entries);
+    const priceResolution = resolvePrices(args.prices);
+    const prices = decode(PriceMapCodec.decode(readJSON(priceResolution.path)), "prices");
+    const report = computeCost(usage.models, prices);
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          ...report,
+          turns: usage.turns,
+          durationMs: usage.durationMs,
+          transcripts: tree.files,
+          pricesProvided: priceResolution.kind === "provided"
+        },
+        null,
+        2
+      )}
+`
+    );
+  }
+});
+var tryReadPrices = (path) => {
+  try {
+    const decoded = PriceMapCodec.decode(JSON.parse(readFileSync(resolve$1(path), "utf-8")));
+    return decoded._tag === "Right" ? decoded.right : null;
+  } catch {
+    return null;
+  }
+};
+var parseBudgetUsd = (raw) => {
+  if (raw === void 0) return null;
+  const n = Number.parseFloat(raw);
+  return Number.isFinite(n) && n >= 0 ? n : null;
+};
+var transcriptPathOf = (input) => {
+  const tp = (typeof input === "object" && input !== null ? input : {})["transcript_path"];
+  return typeof tp === "string" ? tp : void 0;
+};
+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. 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."
+  },
+  args: {
+    draft: {
+      type: "string",
+      description: "Path to the findings draft that is the sole permitted write target under forced convergence",
+      required: true
+    },
+    "budget-usd": {
+      type: "string",
+      description: "Dollar budget for the run; the cost axis is measured against it (needs --prices)"
+    },
+    wall: {
+      type: "string",
+      description: "Wall-clock budget (e.g. 20m, 1200s, 2h); the time axis is measured against it"
+    },
+    prices: {
+      type: "string",
+      description: "Price map JSON to recompute real spend from the transcript (omit to disable the cost axis)"
+    },
+    "reserve-frac": {
+      type: "string",
+      description: "Wind-down headroom as a fraction of each budget: converge once less than this remains (default: 0.15; the soft steer tier reserves 2\xD7 this)"
+    },
+    "reserve-usd": {
+      type: "string",
+      description: "Flat dollar wind-down floor, whichever is larger with --reserve-frac (default: 0.02)"
+    },
+    "reserve-wall": {
+      type: "string",
+      description: "Flat wall-clock wind-down floor (e.g. 2m, 120s), whichever is larger with --reserve-frac (default: 2m)"
+    }
+  },
+  run: async ({ args }) => {
+    try {
+      const draftPath = resolve$1(args.draft);
+      const input = readStdinJSON();
+      const transcriptPath = transcriptPathOf(input);
+      const tree = transcriptPath ? readTranscriptTree(resolve$1(transcriptPath)) : void 0;
+      const usage = tree ? sumTranscriptUsage(tree.entries) : void 0;
+      const prices = args.prices ? tryReadPrices(args.prices) : null;
+      const spentUsd = prices !== null && usage ? computeCost(usage.models, prices).totalCostUSD : null;
+      const output = evaluateBudgetHook(input, {
+        spentUsd,
+        budgetUsd: parseBudgetUsd(args["budget-usd"]),
+        elapsedMs: usage?.firstTsMs != null ? Math.max(0, Date.now() - usage.firstTsMs) : null,
+        wallMs: args.wall ? parseWallMs(args.wall) : null,
+        reserve: {
+          frac: parseFraction(args["reserve-frac"], DEFAULT_RESERVE.frac),
+          flatUsd: parseBudgetUsd(args["reserve-usd"]) ?? DEFAULT_RESERVE.flatUsd,
+          flatMs: args["reserve-wall"] ? parseWallMs(args["reserve-wall"]) ?? DEFAULT_RESERVE.flatMs : DEFAULT_RESERVE.flatMs
+        },
+        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.stdout.write("{}\n");
+    }
+  }
+});
+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."
+  },
+  args: {
+    draft: {
+      type: "string",
+      description: "Path to the findings draft the agent must produce \u2014 the Stop gate's target and the only write allowed under forced convergence",
+      required: true
+    },
+    kind: {
+      type: "string",
+      description: "Schema kind for the Stop gate: findings | triage | prices (default: findings)"
+    },
+    schema: {
+      type: "string",
+      description: "Path to a schema file for the Stop gate (wins over --kind)"
+    },
+    "schema-version": {
+      type: "string",
+      description: "Schema major.minor for the Stop gate (default: the draft's declared version)"
+    },
+    "max-nudges": {
+      type: "string",
+      description: "Stop-gate nudge budget before relenting (default: 5)"
+    },
+    counter: {
+      type: "string",
+      description: "Path for the Stop-gate nudge counter (default: <draft>.nudges)"
+    },
+    "budget-usd": {
+      type: "string",
+      description: "Dollar budget the cost axis is measured against (needs --prices)"
+    },
+    wall: {
+      type: "string",
+      description: "Wall-clock budget the time axis is measured against (e.g. 20m, 1200s)"
+    },
+    prices: {
+      type: "string",
+      description: "Price map JSON to recompute real spend from the transcript"
+    },
+    "reserve-frac": {
+      type: "string",
+      description: "Wind-down headroom as a fraction of each budget (default: 0.15; soft tier is 2\xD7)"
+    },
+    "reserve-usd": {
+      type: "string",
+      description: "Flat dollar wind-down floor, whichever is larger with --reserve-frac (default: 0.02)"
+    },
+    "reserve-wall": {
+      type: "string",
+      description: "Flat wall-clock wind-down floor (e.g. 2m), whichever is larger with --reserve-frac (default: 2m)"
+    }
+  },
+  run: async ({ args }) => {
+    if (args.kind && !["findings", "triage", "prices"].includes(args.kind))
+      fail(`--kind must be one of findings|triage|prices (got '${args.kind}')`);
+    const settings = composeReviewSettings({
+      draftPath: resolve$1(args.draft),
+      stop: {
+        kind: args.kind,
+        schema: args.schema,
+        schemaVersion: args["schema-version"],
+        maxNudges: args["max-nudges"],
+        counter: args.counter
+      },
+      budget: {
+        budgetUsd: args["budget-usd"],
+        wall: args.wall,
+        prices: args.prices,
+        reserveFrac: args["reserve-frac"],
+        reserveUsd: args["reserve-usd"],
+        reserveWall: args["reserve-wall"]
+      }
+    });
+    process.stdout.write(`${JSON.stringify(settings)}
+`);
+  }
+});
+var derivedSchemaVersion = (kind, raw) => kind === "findings" ? declaredVersion(raw) : void 0;
 var validateCmd = defineCommand({
   meta: {
     name: "validate",
@@ -1367,11 +2311,22 @@ var adaptCmd = defineCommand({
     "agent-file": {
       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)"
+    },
+    route: {
+      type: "string",
+      description: 'Review route label to stamp into the envelope (e.g. "full review" or "mechanic")'
+    },
+    effort: {
+      type: "string",
+      description: 'Effort label to stamp into the envelope (e.g. "max" or "low")'
     }
   },
   run: async ({ args }) => {
     const envelope = unwrapAdapt(
-      adapt(requireAdapterName(args.adapter), readJSON(args.native), args["agent-file"])
+      adapt(requireAdapterName(args.adapter), readJSONOrAbsent(args.native), args["agent-file"], {
+        route: args.route,
+        effort: args.effort
+      })
     );
     process.stdout.write(`${JSON.stringify(envelope, null, 2)}
 `);
@@ -1416,16 +2371,18 @@ var extractCmd = defineCommand({
   run: async ({ args }) => {
     requireAdapterName(args.adapter);
     const kind = requireExtractSchemaKind(args.kind);
-    const outcome = extractStructured({
-      kind,
-      native: readJSON(args.native),
-      agentFilePath: args["agent-file"]
-    });
+    const input = { kind, native: readJSON(args.native), agentFilePath: args["agent-file"] };
+    const outcome = extractStructured(input);
     if (outcome.kind === "ok") {
       process.stdout.write(`${JSON.stringify(outcome.candidate, null, 2)}
 `);
       return;
     }
+    if (outcome.kind === "none" || outcome.kind === "ambiguous") {
+      process.stderr.write(`extract: recovery failed \u2014
+${ladderFailureDiagnostics(input)}
+`);
+    }
     if (kind === "triage") {
       process.stdout.write(`${JSON.stringify(failClosedTriage(outcome), null, 2)}
 `);
@@ -1434,6 +2391,70 @@ var extractCmd = defineCommand({
     fail(describeLadderFailure(outcome));
   }
 });
+var withoutPatch = (finding) => {
+  const copy = { ...finding };
+  delete copy.patch;
+  return copy;
+};
+var readFileLines = (path) => {
+  try {
+    const rawLines = readFileSync(path, "utf-8").split("\n");
+    return rawLines.length > 0 && rawLines[rawLines.length - 1] === "" ? rawLines.slice(0, -1) : rawLines;
+  } catch {
+    return null;
+  }
+};
+var validateFinding = (finding, repoRoot) => {
+  if (finding.patch === void 0) return finding;
+  const lines = readFileLines(resolve$1(repoRoot, finding.path));
+  if (lines === null) {
+    process.stderr.write(
+      `validate-patches: ${finding.path}: could not read file at "${repoRoot}" \u2014 dropping patch
+`
+    );
+    return withoutPatch(finding);
+  }
+  const result = validatePatch(finding.patch, lines);
+  switch (result.kind) {
+    case "anchored":
+      return { ...finding, start_line: result.startLine, end_line: result.endLine };
+    case "keep":
+      return finding;
+    case "drop":
+      process.stderr.write(
+        `validate-patches: ${finding.path}:${String(finding.start_line)}: ${result.reason} \u2014 dropping patch
+`
+      );
+      return withoutPatch(finding);
+  }
+};
+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)"
+  },
+  args: {
+    findings: {
+      type: "positional",
+      description: "Path to findings JSON",
+      required: true
+    },
+    "repo-root": {
+      type: "string",
+      description: "Directory to resolve each finding's path against \u2014 the review job's checked-out, clean PR-head tree (default: .)"
+    }
+  },
+  run: async ({ args }) => {
+    const findings = decode(FindingsCodec.decode(readJSON(args.findings)), "findings");
+    const repoRoot = args["repo-root"] ? resolve$1(args["repo-root"]) : process.cwd();
+    const validated = {
+      ...findings,
+      findings: findings.findings.map((f) => validateFinding(f, repoRoot))
+    };
+    process.stdout.write(`${JSON.stringify(validated, null, 2)}
+`);
+  }
+});
 var requireAdapterName = (name) => {
   if (isAdapterName(name)) return name;
   fail(`Unknown adapter "${name}" \u2014 supported: claude-code`);
@@ -1456,7 +2477,7 @@ var requireSchemaPath = (kind, version) => {
 var printSchemaCmd = defineCommand({
   meta: {
     name: "print-schema",
-    description: "Print a bundled schema JSON"
+    description: "Print a bundled schema JSON, ready to hand to a CLI's --json-schema (the $schema draft declaration is stripped)"
   },
   args: {
     name: {
@@ -1472,7 +2493,103 @@ var printSchemaCmd = defineCommand({
   run: async ({ args }) => {
     const schemaKind = requireSchemaKind(args.name);
     const schemaPath = requireSchemaPath(schemaKind, args["schema-version"]);
-    process.stdout.write(readFileSync(schemaPath, "utf-8"));
+    const schema = JSON.parse(readFileSync(schemaPath, "utf-8"));
+    const enforcementSchema = Object.fromEntries(
+      Object.entries(schema).filter(([key2]) => key2 !== "$schema")
+    );
+    process.stdout.write(`${JSON.stringify(enforcementSchema, null, 2)}
+`);
+  }
+});
+var MAX_NUDGES_DEFAULT = 5;
+var drainStdin = () => {
+  if (process.stdin.isTTY) return;
+  try {
+    readFileSync(0);
+  } catch {
+  }
+};
+var requireMaxNudges = (raw) => {
+  if (raw === void 0) return MAX_NUDGES_DEFAULT;
+  if (!/^\d+$/.test(raw)) {
+    fail(`--max-nudges must be a non-negative integer; got "${raw}"`);
+  }
+  const n = Number.parseInt(raw, 10);
+  if (n < 1) {
+    fail(`--max-nudges must be >= 1 \u2014 a gate that never blocks must be omitted, not set to ${raw}`);
+  }
+  return n;
+};
+var stopGateCmd = defineCommand({
+  meta: {
+    name: "stop-gate",
+    description: "Claude Code Stop-hook gate: refuse to let the agent end its turn until --draft validates against the schema (bounded by --max-nudges). With --print-settings, emit the --settings JSON that wires this as the Stop hook."
+  },
+  args: {
+    draft: {
+      type: "string",
+      description: "Path to the findings document the agent must produce and keep valid",
+      required: true
+    },
+    kind: {
+      type: "string",
+      description: "Schema kind to validate against: findings | triage | prices (default: findings)"
+    },
+    schema: { type: "string", description: "Path to a schema file (wins over --kind)" },
+    "schema-version": {
+      type: "string",
+      description: "Schema major.minor to validate against (default: the draft's declared version)"
+    },
+    "max-nudges": {
+      type: "string",
+      description: `Times to block before relenting so the step fails downstream as before (default: ${String(MAX_NUDGES_DEFAULT)})`
+    },
+    counter: {
+      type: "string",
+      description: "Path for the nudge counter (default: <draft>.nudges)"
+    },
+    "print-settings": {
+      type: "boolean",
+      description: "Print the Stop-hook settings JSON that wires this gate, then exit"
+    }
+  },
+  run: async ({ args }) => {
+    const draftPath = resolve$1(args.draft);
+    if (args["print-settings"]) {
+      const command = defaultHookCommand(draftPath, {
+        kind: args.kind,
+        schema: args.schema,
+        schemaVersion: args["schema-version"],
+        maxNudges: args["max-nudges"],
+        counter: args.counter
+      });
+      process.stdout.write(`${JSON.stringify(stopHookSettings(command))}
+`);
+      return;
+    }
+    drainStdin();
+    const kind = requireSchemaKind(args.kind || "findings");
+    const maxNudges = requireMaxNudges(args["max-nudges"]);
+    const counterPath = args.counter ? resolve$1(args.counter) : `${draftPath}.nudges`;
+    const state = draftState(
+      draftPath,
+      (parsed) => args.schema ? resolve$1(args.schema) : schemaPathFor(kind, args["schema-version"] || derivedSchemaVersion(kind, parsed))
+    );
+    const nudges = readNudges(counterPath);
+    const decision = decideGate(state, nudges, maxNudges, draftPath, kind);
+    if (decision.kind === "block") {
+      try {
+        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)}
+`
+        );
+        return;
+      }
+      process.stdout.write(`${JSON.stringify({ decision: "block", reason: decision.reason })}
+`);
+    }
   }
 });
 var gatherCmd = defineCommand({
@@ -1559,12 +2676,11 @@ var postCmd = defineCommand({
     },
     "inline-template": {
       type: "string",
-      description: "Path to inline comment Eta template (default: built-in format)"
+      description: "Path to inline comment Eta template (default: bundled templates/inline.eta)"
     },
     route: {
       type: "string",
-      description: 'Review route label (e.g. "full review" or "mechanic")',
-      required: true
+      description: "Review route label; overrides the envelope's route when set (default: read from the envelope)"
     },
     "bot-login": {
       type: "string",
@@ -1576,27 +2692,40 @@ var postCmd = defineCommand({
     },
     effort: {
       type: "string",
-      description: 'Effort label to render in the route line (e.g. "max" or "low"); omitted when absent'
+      description: "Effort label; overrides the envelope's effort when set (default: read from the envelope)"
     },
     "test-report": {
       type: "string",
       description: TEST_REPORT_DESCRIPTION
+    },
+    "run-url": {
+      type: "string",
+      description: "Workflow run URL (transcript/traces), rendered as a link in the LLM Disclosure aside"
+    },
+    "json-url": {
+      type: "string",
+      description: "URL to the machine-readable findings JSON artifact, pointed at from the sticky and each inline comment"
     }
   },
   run: async ({ args }) => {
+    const priceResolution = resolvePrices(args.prices);
     await post({
       repo: args.repo,
       headSha: args["head-sha"],
       botLogin: args["bot-login"] || "github-actions[bot]",
       findingsPath: args.findings,
       envelopePath: args.usage,
-      pricesPath: resolvePricesPath(args.prices),
+      pricesPath: priceResolution.path,
+      pricesProvided: priceResolution.kind === "provided",
       templatePath: resolveTemplatePath(args.template),
-      inlineTemplatePath: args["inline-template"] ? resolve$1(args["inline-template"]) : void 0,
+      inlineTemplatePath: resolveInlineTemplatePath(args["inline-template"]),
       route: args.route,
       headBranch: args["head-branch"],
       effort: args.effort,
-      testReportPath: args["test-report"]
+      testReportPath: args["test-report"],
+      runUrl: args["run-url"],
+      jsonUrl: args["json-url"],
+      postedAt: formatUtc(/* @__PURE__ */ new Date())
     });
   }
 });
@@ -1604,7 +2733,7 @@ var main = defineCommand({
   meta: {
     name: "code-review",
     version: packageVersion,
-    description: "Deterministic commenter for agentic PR review \u2014 gather, render, inline, post, adapt, extract, cost, and validate findings JSON"
+    description: "Deterministic commenter for agentic PR review \u2014 gather, render, inline, post, adapt, extract, validate-patches, cost, check-cost, validate, stop-gate, budget-hook, and print-settings"
   },
   subCommands: {
     gather: gatherCmd,
@@ -1612,10 +2741,15 @@ var main = defineCommand({
     inline: inlineCmd,
     post: postCmd,
     cost: costCmd,
+    "check-cost": checkCostCmd,
     validate: validateCmd,
     adapt: adaptCmd,
     extract: extractCmd,
-    "print-schema": printSchemaCmd
+    "validate-patches": validatePatchesCmd,
+    "print-schema": printSchemaCmd,
+    "stop-gate": stopGateCmd,
+    "budget-hook": budgetHookCmd,
+    "print-settings": printSettingsCmd
   }
 });
 if (!process.env["VITEST"]) {