@jphutchins/code-review 0.1.0-alpha.39 → 0.1.0-alpha.40

package/dist/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { defineCommand, runMain } from 'citty';
-import { readFileSync, writeFileSync, statSync, copyFileSync, readdirSync } from 'fs';
+import { readFileSync, writeFileSync, copyFileSync, statSync, readdirSync } from 'fs';
 import { randomBytes } from 'crypto';
 import { resolve as resolve$1, join, dirname, basename, extname } from 'path';
 import { Eta } from 'eta';
@@ -37,6 +37,15 @@ var SchemaVersion = t.refinement(
   (s) => SCHEMA_VERSION_RE.test(s),
   "SchemaVersion"
 );
+var UriString = t.refinement(
+  t.string,
+  (s) => !/\s/.test(s) && URL.canParse(s),
+  "UriString"
+);
+var FindingRuleCodec = t.partial({
+  code: t.string,
+  code_url: UriString
+});
 var FindingShape = t.intersection([
   t.type({
     path: t.string,
@@ -48,10 +57,9 @@ var FindingShape = t.intersection([
     reasoning: t.string,
     confidence: Confidence
   }),
+  FindingRuleCodec,
   t.partial({
     side: SideCodec,
-    code: t.string,
-    code_url: t.string,
     recommendation: t.string,
     patch: t.string
   })
@@ -62,13 +70,41 @@ var EndGeStart = t.refinement(
   "EndGeStart"
 );
 var FindingCodec = t.exact(EndGeStart);
+var SystemicRequired = t.type({
+  title: t.string,
+  description: t.string,
+  severity: SeverityCodec,
+  reasoning: t.string,
+  confidence: Confidence
+});
+var SystemicOptional = t.partial({
+  finding_codes: t.array(t.string),
+  paths: t.array(t.string)
+});
+var SystemicProblemShape = t.intersection([SystemicRequired, FindingRuleCodec, SystemicOptional]);
+var SYSTEMIC_KEYS = /* @__PURE__ */ new Set([
+  ...Object.keys(SystemicRequired.props),
+  ...Object.keys(FindingRuleCodec.props),
+  ...Object.keys(SystemicOptional.props)
+]);
+var SystemicProblemStrict = t.refinement(
+  SystemicProblemShape,
+  (s) => Object.keys(s).every((k) => SYSTEMIC_KEYS.has(k)),
+  "SystemicProblemStrict"
+);
+var SystemicProblemCodec = t.exact(SystemicProblemStrict);
 var FindingsCodec = t.exact(
-  t.type({
-    schema_version: SchemaVersion,
-    summary: t.string,
-    verdict: VerdictCodec,
-    findings: t.array(FindingCodec)
-  })
+  t.intersection([
+    t.type({
+      schema_version: SchemaVersion,
+      summary: t.string,
+      verdict: VerdictCodec,
+      findings: t.array(FindingCodec)
+    }),
+    t.partial({
+      systemic_problems: t.array(SystemicProblemCodec)
+    })
+  ])
 );
 var TriageCodec = t.type({
   safe: t.boolean,
@@ -134,13 +170,7 @@ var TestSummaryCodec = t.intersection([
     failures: t.array(TestFailureCodec)
   })
 ]);
-var DEFAULT_SCHEMA_VERSION = "0.5.0";
-var emptyFindings = (summary) => ({
-  schema_version: DEFAULT_SCHEMA_VERSION,
-  summary,
-  verdict: "comment",
-  findings: []
-});
+var DEFAULT_SCHEMA_VERSION = "0.6.0";
 var incompleteFindings = (summary) => ({
   schema_version: DEFAULT_SCHEMA_VERSION,
   summary,
@@ -308,8 +338,9 @@ var severityEmoji = (s) => {
       return "\u2753";
   }
 };
-var EMBED_LIMIT = 4e4;
+var EMBED_LIMIT = 40200;
 var AGENTS_STOP_DIRECTIVE = "<!-- AGENTS: STOP \u2014 do not parse the prose below; decode this findings JSON and read schema_version first. -->";
+var b64LengthOf = (document) => Buffer.from(JSON.stringify(document), "utf-8").toString("base64").length;
 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} -->` : "";
@@ -324,12 +355,24 @@ var decodeBase64Json = (b64) => {
   }
 };
 var findingsPointer = (findings, jsonUrl, limit = EMBED_LIMIT) => encodeMarker(findings, jsonUrl, limit);
+var findingsMarkerForm = (findings, jsonUrl, limit = EMBED_LIMIT) => {
+  if (b64LengthOf(findings) <= limit) return "embedded";
+  return jsonUrl ? "link" : "omitted";
+};
 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 ROUTE_RE = /<!-- reviewed-route: ([^>]*) -->/;
+var parseReviewedRoute = (body) => ROUTE_RE.exec(body)?.[1] || null;
+var isFullReviewSticky = (body) => {
+  const route = parseReviewedRoute(body);
+  return route === "full review" || route !== "mechanic" && parseRounds(body).length > 0;
+};
+var COMPLETED_ANCESTOR_MARKER = "<!-- review-complete-ancestor -->";
+var parseCompletedAncestor = (body) => body.includes(COMPLETED_ANCESTOR_MARKER);
 var REVIEW_COMPLETE_MARKER = "<!-- review-complete -->";
 var parseReviewComplete = (body) => body.includes(REVIEW_COMPLETE_MARKER);
 var parseFindingsMarker = (body) => {
@@ -343,38 +386,233 @@ var isSeverityCounts = (u) => typeof u === "object" && u !== null && SEVERITIES.
   const v = u[k];
   return typeof v === "number" && Number.isSafeInteger(v) && v >= 0;
 });
+var MAX_CODES_PER_ROUND = 8;
+var hasCode = (codes, code) => codes !== void 0 && Object.prototype.hasOwnProperty.call(codes, code);
+var escapeCodeBackticks = (code) => code.replace(/`/g, "-").replace(/\r?\n/g, " ");
+var normalizeCodeCounts = (codes, priorCodes) => {
+  if (typeof codes !== "object" || codes === null || Array.isArray(codes)) return void 0;
+  const entries = Object.entries(codes).filter(
+    (e) => typeof e[1] === "number" && Number.isSafeInteger(e[1]) && e[1] > 0
+  ).sort((a, b) => {
+    if (b[1] !== a[1]) return b[1] - a[1];
+    const aPrior = hasCode(priorCodes, a[0]) ? 1 : 0;
+    const bPrior = hasCode(priorCodes, b[0]) ? 1 : 0;
+    if (aPrior !== bPrior) return bPrior - aPrior;
+    return a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0;
+  });
+  if (entries.length === 0) return void 0;
+  const sorted = entries.sort((a, b) => {
+    if (b[1] !== a[1]) return b[1] - a[1];
+    const aPrior = hasCode(priorCodes, a[0]) ? 1 : 0;
+    const bPrior = hasCode(priorCodes, b[0]) ? 1 : 0;
+    if (aPrior !== bPrior) return bPrior - aPrior;
+    return a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0;
+  });
+  const base = sorted.slice(0, MAX_CODES_PER_ROUND);
+  const priorKept = sorted.slice(MAX_CODES_PER_ROUND).filter(([code]) => hasCode(priorCodes, code)).slice(0, MAX_CODES_PER_ROUND);
+  return Object.fromEntries([...base, ...priorKept]);
+};
 var parseRounds = (body) => {
   const b64 = ROUNDS_RE.exec(body)?.[1];
   if (b64 === void 0) return [];
   const decoded = decodeBase64Json(b64);
-  return Array.isArray(decoded) ? decoded.filter(isSeverityCounts) : [];
+  if (!Array.isArray(decoded)) return [];
+  return decoded.filter(isSeverityCounts).map((u) => {
+    const rec = u;
+    const codes = normalizeCodeCounts(rec["codes"]);
+    const sha = rec["sha"];
+    const shaStr = typeof sha === "string" && sha !== "" ? sha : void 0;
+    const round = rec["round"];
+    const roundNum = typeof round === "number" && Number.isSafeInteger(round) && round >= 1 ? round : void 0;
+    const base = codes === void 0 ? { critical: u.critical, major: u.major, minor: u.minor, nit: u.nit } : { critical: u.critical, major: u.major, minor: u.minor, nit: u.nit, codes };
+    const kept = shaStr === void 0 ? base : { ...base, sha: shaStr };
+    return roundNum === void 0 ? kept : { ...kept, round: roundNum };
+  });
+};
+var ROUNDS_MARKER_LIMIT = 8e3;
+var roundsMarker = (rounds) => {
+  if (rounds.length === 0) return "";
+  const serialize = (kept2) => `<!-- code-review:rounds;base64 ${Buffer.from(JSON.stringify(kept2), "utf-8").toString("base64")} -->`;
+  const stripCodes = (n) => rounds.map(
+    (r, i) => i < n ? { critical: r.critical, major: r.major, minor: r.minor, nit: r.nit } : r
+  );
+  let stripped = 0;
+  while (stripped < rounds.length && serialize(stripCodes(stripped)).length > ROUNDS_MARKER_LIMIT) {
+    stripped += 1;
+  }
+  const kept = stripCodes(stripped);
+  const bounded = serialize(kept).length > ROUNDS_MARKER_LIMIT ? kept.slice(-8) : kept;
+  return serialize(bounded);
 };
-var roundsMarker = (rounds) => rounds.length === 0 ? "" : `<!-- code-review:rounds;base64 ${Buffer.from(JSON.stringify(rounds), "utf-8").toString("base64")} -->`;
 var roundChip = (c) => {
   const parts = SEVERITIES.filter((k) => c[k] > 0).map((k) => `${severityEmoji(k)}${String(c[k])}`);
   return parts.length === 0 ? "clean" : parts.join(" ");
 };
 var TRAJECTORY_CHIPS = 8;
-var roundsSummary = (rounds) => {
-  if (rounds.length === 0) return "";
+var roundsSummary = (rounds, count = rounds.length) => {
+  if (count === 0) return "";
   const chips = rounds.slice(-TRAJECTORY_CHIPS).map(roundChip);
-  const trajectory = rounds.length > TRAJECTORY_CHIPS ? `\u2026 \u2192 ${chips.join(" \u2192 ")}` : chips.join(" \u2192 ");
-  return `**Round ${String(rounds.length)}** \xB7 ${trajectory}`;
+  const trajectory = chips.length === 0 ? "" : rounds.length > TRAJECTORY_CHIPS ? `\u2026 \u2192 ${chips.join(" \u2192 ")}` : chips.join(" \u2192 ");
+  return trajectory === "" ? `**Round ${String(count)}**` : `**Round ${String(count)}** \xB7 ${trajectory}`;
+};
+var computeCodeCounts = (findings, systemic = []) => {
+  const counts = /* @__PURE__ */ new Map();
+  for (const code of [
+    ...findings.map((f) => f.code),
+    ...systemic.flatMap((s) => [s.code, ...s.finding_codes ?? []])
+  ]) {
+    if (code === void 0 || code === "") continue;
+    counts.set(code, (counts.get(code) ?? 0) + 1);
+  }
+  return Object.fromEntries(counts);
+};
+var roundRecord = (counts, codes, priorCodes, sha, round) => {
+  const normalized = normalizeCodeCounts(codes, priorCodes);
+  const record3 = normalized === void 0 ? { ...counts } : { ...counts, codes: normalized };
+  return {
+    ...record3,
+    ...sha !== void 0 ? { sha } : {},
+    ...round !== void 0 ? { round } : {}
+  };
+};
+var consecutiveCodeStreaks = (rounds) => {
+  const entries = [];
+  if (rounds.length === 0) return {};
+  const lastCodes = rounds[rounds.length - 1]?.codes;
+  if (lastCodes === void 0) return {};
+  for (const code of Object.keys(lastCodes)) {
+    let streak = 0;
+    let startIndex = rounds.length;
+    for (let i = rounds.length - 1; i >= 0; i--) {
+      const codes = rounds[i]?.codes;
+      if (codes === void 0 || !hasCode(codes, code)) break;
+      if (i > 0 && rounds[i]?.sha !== void 0 && rounds[i]?.sha === rounds[i - 1]?.sha && hasCode(rounds[i - 1]?.codes, code)) {
+        continue;
+      }
+      streak += 1;
+      startIndex = i;
+    }
+    if (streak > 0) {
+      entries.push([code, { streak, startRound: rounds[startIndex]?.round ?? startIndex + 1 }]);
+    }
+  }
+  return Object.fromEntries(entries);
+};
+var DEFAULT_METASTASIS_STREAK = 3;
+var metastasisNote = (rounds, minStreak = DEFAULT_METASTASIS_STREAK) => {
+  const flagged = Object.entries(consecutiveCodeStreaks(rounds)).filter(([, s]) => s.streak >= minStreak).sort((a, b) => b[1].streak - a[1].streak);
+  if (flagged.length === 0) return "";
+  const lines = flagged.map(
+    ([code, s]) => `> **\`${escapeCodeBackticks(code)}\`** \u2014 findings in ${String(s.streak)} consecutive rounds.`
+  );
+  return [
+    "> [!WARNING]",
+    "> **Scope metastasis** \u2014 findings keep recurring in the same mechanism across consecutive rounds; each fix keeps enabling the next finding in that machinery. Consider whether a structural fix (change the shape, not the edge case) or a scope narrowing would converge this faster.",
+    ...lines
+  ].join("\n");
+};
+var computeSameRootNotes = (priorRounds, findings, currentSha) => {
+  const codes = findings.map((f) => f.code).filter((c) => c !== void 0 && c !== "");
+  const entries = [];
+  for (const code of codes) {
+    let lastRound = 0;
+    for (let i = priorRounds.length - 1; i >= 0; i--) {
+      if (currentSha !== void 0 && priorRounds[i]?.sha === currentSha) continue;
+      if (i > 0 && priorRounds[i]?.sha !== void 0 && priorRounds[i]?.sha === priorRounds[i - 1]?.sha && hasCode(priorRounds[i - 1]?.codes, code))
+        continue;
+      const count = priorRounds[i]?.codes?.[code];
+      if (count !== void 0 && count > 0) {
+        lastRound = priorRounds[i]?.round ?? i + 1;
+        break;
+      }
+    }
+    if (lastRound > 0) {
+      entries.push([
+        code,
+        `Same mechanism as round ${String(lastRound)} (\`${escapeCodeBackticks(code)}\`) \u2014 the prior fix in this area re-opened it; consider a structural fix or a scope narrowing.`
+      ]);
+    }
+  }
+  return Object.fromEntries(entries);
 };
 var CONVERGENCE_WEIGHTS = { critical: 4, major: 2, minor: 1, nit: 0 };
 var DEFAULT_CONVERGENCE_THRESHOLD = 1;
 var convergenceScore = (counts) => SEVERITIES.reduce((sum, k) => sum + counts[k] * CONVERGENCE_WEIGHTS[k], 0);
 var convergenceSummary = (counts, threshold = DEFAULT_CONVERGENCE_THRESHOLD) => {
+  const { score, converged } = convergenceSignal(counts, threshold);
+  return converged ? `**Convergence** \u{1F3C1} ${String(score)} \u2264 ${String(threshold)} \u2014 converged` : `**Convergence** \u{1F504} ${String(score)} > ${String(threshold)} \u2014 iterating`;
+};
+var SURFACE_SCHEMA_VERSION = "0.7.0";
+var convergenceSignal = (counts, threshold = DEFAULT_CONVERGENCE_THRESHOLD) => {
   const score = convergenceScore(counts);
-  return score <= threshold ? `**Convergence** \u{1F3C1} ${String(score)} \u2264 ${String(threshold)} \u2014 converged` : `**Convergence** \u{1F504} ${String(score)} > ${String(threshold)} \u2014 iterating`;
+  return { score, threshold, converged: score <= threshold };
+};
+var signalForRound = (round, counts, threshold = DEFAULT_CONVERGENCE_THRESHOLD) => ({ round, convergence: convergenceSignal(counts, threshold) });
+var surfaceFindings = (findings, signal) => {
+  const agentDoc = Object.fromEntries(
+    Object.entries(findings).filter(([key2]) => key2 !== "round" && key2 !== "convergence")
+  );
+  return {
+    ...agentDoc,
+    schema_version: SURFACE_SCHEMA_VERSION,
+    ...signal === null ? {} : signal
+  };
+};
+var signalMarker = (signal) => `<!-- code-review:signal;base64 ${Buffer.from(
+  JSON.stringify({ schema_version: SURFACE_SCHEMA_VERSION, ...signal }),
+  "utf-8"
+).toString("base64")} -->`;
+var surfacedFindingsPointer = (findings, signal, jsonUrl) => {
+  const marker = findingsPointer(surfaceFindings(findings, signal), jsonUrl);
+  if (signal === null || marker.includes("<!-- code-review:findings-json;base64 ")) return marker;
+  return marker === "" ? signalMarker(signal) : `${marker}
+${signalMarker(signal)}`;
+};
+var SIGNAL_RE = /<!-- code-review:signal;base64 ([A-Za-z0-9+/=]+) -->/;
+var parseSignalMarker = (body) => {
+  const b64 = SIGNAL_RE.exec(body)?.[1];
+  if (b64 === void 0) return null;
+  return parseSurfaceSignal(decodeBase64Json(b64));
+};
+var parseSurfaceSignal = (doc) => {
+  if (typeof doc !== "object" || doc === null || Array.isArray(doc)) return null;
+  const o = doc;
+  const declared = o["schema_version"];
+  if (typeof declared !== "string" || !SURFACE_SCHEMA_VERSIONS.includes(declared)) return null;
+  const round = o["round"];
+  const convergence = o["convergence"];
+  if (typeof round !== "number" || !Number.isSafeInteger(round) || round < 1) return null;
+  if (typeof convergence !== "object" || convergence === null) return null;
+  const c = convergence;
+  if (typeof c["score"] !== "number" || !Number.isFinite(c["score"]) || typeof c["threshold"] !== "number" || !Number.isFinite(c["threshold"]) || typeof c["converged"] !== "boolean") {
+    return null;
+  }
+  return {
+    round,
+    convergence: { score: c["score"], threshold: c["threshold"], converged: c["converged"] }
+  };
+};
+var SURFACE_SCHEMA_VERSIONS = [SURFACE_SCHEMA_VERSION];
+var stripSurfaceFields = (doc) => {
+  if (typeof doc !== "object" || doc === null || Array.isArray(doc)) return doc;
+  const o = doc;
+  const declared = o["schema_version"];
+  if (typeof declared !== "string" || !SURFACE_SCHEMA_VERSIONS.includes(declared)) return doc;
+  const rest = Object.fromEntries(
+    Object.entries(o).filter(([key2]) => key2 !== "convergence" && key2 !== "round")
+  );
+  return { ...rest, schema_version: DEFAULT_SCHEMA_VERSION };
 };
 var carryForwardMarkers = (body) => {
   const findings = /<!-- code-review:findings-json[^>]*-->/.exec(body)?.[0];
   const reviewedSha = /<!-- reviewed-sha: [0-9a-fA-F]{40} -->/.exec(body)?.[0];
+  const reviewedRoute = ROUTE_RE.exec(body)?.[0];
   const rounds = ROUNDS_RE.exec(body)?.[0];
+  const signal = SIGNAL_RE.exec(body)?.[0];
+  const completedAncestor = parseReviewComplete(body) || parseCompletedAncestor(body) ? COMPLETED_ANCESTOR_MARKER : void 0;
   const findingsBlock = findings ? `${AGENTS_STOP_DIRECTIVE}
 ${findings}` : void 0;
-  return [findingsBlock, reviewedSha, rounds].filter((m) => m !== void 0).join("\n\n");
+  return [findingsBlock, reviewedSha, reviewedRoute, completedAncestor, rounds, signal].filter((m) => m !== void 0).join("\n\n");
 };
 var escapeFence = (text) => text.replace(/```/g, "`` ` ``");
 var projectPatch = (patch) => {
@@ -393,13 +631,18 @@ ${linkLine}` : linkLine;
 
 // src/render.ts
 var escapePipes = (text) => text.replace(/\|/g, "\\|");
-var escapeCodeBackticks = (text) => text.replace(/`/g, "-");
 var sanitizeFinding = (f) => ({
   ...f,
   title: escapePipes(f.title),
   path: escapeCodeBackticks(f.path),
   patchProjection: projectPatch(f.patch)
 });
+var sanitizeSystemic = (s) => ({
+  ...s,
+  title: escapePipes(s.title),
+  ...s.paths !== void 0 ? { paths: s.paths.map(escapeCodeBackticks) } : {},
+  ...s.finding_codes !== void 0 ? { finding_codes: s.finding_codes.map(escapeCodeBackticks) } : {}
+});
 var emptySeverityCounts = () => ({
   critical: 0,
   major: 0,
@@ -410,6 +653,11 @@ var computeSeverityCounts = (findings) => findings.reduce(
   (acc, f) => f.severity in acc ? { ...acc, [f.severity]: acc[f.severity] + 1 } : acc,
   emptySeverityCounts()
 );
+var isReviewVerdict = (verdict) => verdict !== "error";
+var computeRoundCounts = (findings) => (findings.systemic_problems ?? []).reduce(
+  (acc, s) => s.severity in acc ? { ...acc, [s.severity]: acc[s.severity] + 1 } : acc,
+  computeSeverityCounts(findings.findings)
+);
 var isConvergenceRound = (route, incomplete) => route === "full review" && !incomplete;
 var render = (input) => {
   const eta = new Eta({ autoTrim: false });
@@ -423,7 +671,10 @@ var render = (input) => {
   const modelNames = input.envelope ? input.envelope.models.map((m) => m.model).join(", ") : "";
   const severityCounts = input.severityCounts ?? computeSeverityCounts(input.findings.findings);
   const rounds = input.rounds ?? [];
-  const isFullReviewRound = (input.convergenceRound ?? isConvergenceRound(route, incomplete)) && input.findings.verdict !== "error";
+  const sameRootNotes = input.sameRootNotes ?? computeSameRootNotes(rounds.slice(0, -1), input.findings.findings);
+  const isFullReviewRound = (input.convergenceRound ?? (isConvergenceRound(route, incomplete) && rounds.length > 0)) && isReviewVerdict(input.findings.verdict);
+  const convergenceCounts = rounds[rounds.length - 1] ?? computeRoundCounts(input.findings);
+  const advisoryAllowed = isFullReviewRound;
   return eta.renderString(input.template, {
     findings: input.findings,
     envelope: input.envelope,
@@ -439,15 +690,27 @@ var render = (input) => {
     reviewedSha: input.reviewedSha ?? "0000000000000000000000000000000000000000",
     postedAt: input.postedAt ?? "",
     severityCounts,
-    convergenceSummary: isFullReviewRound ? convergenceSummary(severityCounts, input.convergenceThreshold) : "",
+    convergenceSummary: isFullReviewRound ? convergenceSummary(convergenceCounts, input.convergenceThreshold) : "",
     strays: (input.strays ?? []).map(sanitizeFinding),
+    systemic: (input.findings.systemic_problems ?? []).map(sanitizeSystemic),
     unanchoredCount: input.unanchoredCount ?? 0,
     inlineDisposition: input.inlineDisposition ?? null,
     runUrl: input.runUrl ?? null,
     jsonUrl: input.jsonUrl ?? null,
-    findingsPointer: input.findingsPointer ?? findingsPointer(input.findings, input.jsonUrl),
+    findingsPointer: input.findingsPointer ?? surfacedFindingsPointer(
+      input.findings,
+      // The fallback embeds a signal exactly when the badge renders — never beside a suppressed
+      // badge, and from the same counts the badge reads. It assumes a post-style history (the
+      // caller appends this run's counts last), numbering the round exactly as the trajectory
+      // label does; post always supplies the marker, so this path cannot disagree with it in
+      // production (issue #141 review r4).
+      isFullReviewRound && rounds.length > 0 ? signalForRound(rounds.length, convergenceCounts, input.convergenceThreshold) : null,
+      input.jsonUrl
+    ),
     roundsMarker: roundsMarker(rounds),
-    roundsSummary: roundsSummary(rounds),
+    roundsSummary: roundsSummary(rounds, input.roundCount),
+    metastasisNote: advisoryAllowed ? metastasisNote(rounds) : "",
+    sameRootNotes: advisoryAllowed ? sameRootNotes : {},
     reviewUrl: input.reviewUrl ?? null,
     formatTokens: (n) => Number.isFinite(n) && n >= 0 ? n.toLocaleString("en-US") : "\u2014",
     // N/A (never a false $0.00) when no real price map was provided — real tokens, no rates to price them.
@@ -530,7 +793,7 @@ var partitionFindings = (findings, index) => {
 
 // src/inline.ts
 var formatModels = (models) => models.length > 0 ? models.map((m) => `\`${m}\``).join("/") : "an AI model";
-var renderCommentBody = (f, eta, template, modelsText, jsonUrl, pointer) => (
+var renderCommentBody = (f, eta, template, modelsText, jsonUrl, pointer, sameRootNote) => (
   // 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, {
@@ -540,7 +803,8 @@ var renderCommentBody = (f, eta, template, modelsText, jsonUrl, pointer) => (
     formatConfidence,
     modelsText,
     jsonUrl: jsonUrl ?? null,
-    findingsPointer: pointer
+    findingsPointer: pointer,
+    sameRootNote
   })
 );
 var buildInlineComments = (findings, diff, context) => {
@@ -551,11 +815,12 @@ var buildInlineComments = (findings, diff, context) => {
   const modelsText = formatModels(models);
   const comments = inDiff.map((f) => {
     const pointer = fullFindings ? findingPointer(f, fullFindings.schema_version, jsonUrl) : "";
+    const sameRootNote = f.code !== void 0 && f.code !== "" && context.sameRootNotes !== void 0 && Object.prototype.hasOwnProperty.call(context.sameRootNotes, f.code) ? context.sameRootNotes[f.code] ?? "" : "";
     const comment = {
       path: f.path,
       line: f.end_line,
       side: defaultSide(f.side),
-      body: renderCommentBody(f, eta, inlineTemplate, modelsText, jsonUrl, pointer)
+      body: renderCommentBody(f, eta, inlineTemplate, modelsText, jsonUrl, pointer, sameRootNote)
     };
     if (f.start_line < f.end_line) {
       return {
@@ -901,13 +1166,20 @@ var writesToDraft = (toolName, toolInput, draftPath) => {
   return false;
 };
 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) => {
+var SEED_SENTINEL = "code-review seed sentinel \u2014 not a review; replace this file with your findings review.";
+var normalizedDraft = (draftText) => typeof draftText === "string" ? draftText.replace(/^\uFEFF/, "").trim() : "";
+var isSeedSentinel = (draftText) => normalizedDraft(draftText) === SEED_SENTINEL;
+var mainHasWrittenDraft = (draftText) => {
+  const normalized = normalizedDraft(draftText);
+  return normalized !== "" && normalized !== SEED_SENTINEL;
+};
+var sidecarPath = (draftPath, postfix) => {
   const ext = extname(draftPath);
-  return join(dirname(draftPath), `${basename(draftPath, ext)}.last-valid${ext}`);
+  return join(dirname(draftPath), `${basename(draftPath, ext)}${postfix}${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 priorContextPath = (draftPath) => sidecarPath(draftPath, ".prior");
+var lastValidPath = (draftPath) => sidecarPath(draftPath, ".last-valid");
+var spawnFloorMessage = (draftPath) => `Write your own first-pass findings to ${draftPath} before spawning subagents \u2014 a review must never depend on subagents alone, and the pre-seeded $DRAFT is a non-review sentinel: it does not count until you have replaced it with your own review. 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) => ({
   hookSpecificOutput: {
     hookEventName: "PreToolUse",
@@ -953,7 +1225,7 @@ var evaluateBudgetHook = (input, params) => {
       if (phase.kind === "hard" && blockedDuringConvergence(toolName, rec["tool_input"]))
         return denyPreTool(budgetMessage(inputs, phase, params.draftPath, isSubagent));
       if (SPAWN_TOOLS.has(toolName)) {
-        if (!isSubagent && !params.mainDraftWritten)
+        if (!isSubagent && !params.mainDraftWritten())
           return denyPreTool(spawnFloorMessage(params.draftPath));
         return forceBackgroundSpawn(rec["tool_input"]);
       }
@@ -1110,6 +1382,14 @@ var findingsTable = [
   },
   {
     minor: "0.5",
+    defaultVersion: "0.5.0",
+    schemaFile: "findings.schema.json",
+    codec: FindingsCodec,
+    normalize: identity,
+    latest: false
+  },
+  {
+    minor: "0.6",
     defaultVersion: DEFAULT_SCHEMA_VERSION,
     schemaFile: "findings.schema.json",
     codec: FindingsCodec,
@@ -1152,9 +1432,9 @@ var formatErrors = (errors) => errors.map(describeValidationError);
 var declaredVersion = (raw) => typeof raw === "object" && raw !== null && "schema_version" in raw ? typeof raw.schema_version === "string" ? raw.schema_version : void 0 : void 0;
 var supportedVersions = (kind) => tableFor(kind).map((entry) => entry.minor);
 var defaultVersion = (kind) => {
-  const latest2 = tableFor(kind).find((entry) => entry.latest);
-  if (!latest2) throw new Error(`Registry invariant violated \u2014 no latest entry for "${kind}"`);
-  return latest2.defaultVersion;
+  const latest = tableFor(kind).find((entry) => entry.latest);
+  if (!latest) throw new Error(`Registry invariant violated \u2014 no latest entry for "${kind}"`);
+  return latest.defaultVersion;
 };
 var bundledSchemaPath = (relativePath) => resolve$1(import.meta.dirname, "..", "schema", relativePath);
 var schemaPathFor = (kind, version) => {
@@ -1282,8 +1562,111 @@ var fetchDiff = async (repo, prNumber, ghApi) => ghApi([
   "Accept: application/vnd.github.v3.diff"
 ]);
 
+// src/checkrun.ts
+var CHECK_RUN_NAME = "Code review";
+var settled = /* @__PURE__ */ new Set(["success", "neutral", "skipped"]);
+var runIdFromUrl = (runUrl) => {
+  const m = /\/actions\/runs\/(\d+)\/?$/.exec(runUrl);
+  return m?.[1] ?? null;
+};
+var ownedCheck = (checks, runUrl) => {
+  const runId = runIdFromUrl(runUrl);
+  if (runId === null) return null;
+  return checks.find((c) => c.detailsUrl !== null && c.detailsUrl.endsWith(`/runs/${runId}`)) ?? null;
+};
+var decideCheckAction = (checks, intent, runUrl) => {
+  const owned = ownedCheck(checks, runUrl);
+  switch (intent) {
+    case "in_progress":
+      return owned !== null ? { kind: "noop", reason: "this run's check is already in progress" } : { kind: "create", status: "in_progress" };
+    case "neutral":
+      if (owned === null) return { kind: "create", status: "completed", conclusion: "neutral" };
+      return owned.status === "completed" && owned.conclusion === "neutral" ? { kind: "noop", reason: "the check already records this completed review" } : { kind: "patch", id: owned.id, status: "completed", conclusion: "neutral" };
+    case "failure":
+      if (owned === null) return { kind: "create", status: "completed", conclusion: "failure" };
+      if (owned.status === "completed" && owned.conclusion !== null && settled.has(owned.conclusion))
+        return { kind: "noop", reason: "a completed review already recorded this head" };
+      return owned.status === "completed" && owned.conclusion === "failure" ? { kind: "noop", reason: "the check already records this failure" } : { kind: "patch", id: owned.id, status: "completed", conclusion: "failure" };
+    case "cancelled":
+      return { kind: "noop", reason: "cancelled is handled via decideCancelledAction" };
+  }
+};
+var decideCancelledAction = (checks, runUrl) => {
+  const owned = ownedCheck(checks, runUrl);
+  if (owned === null) return { kind: "noop", reason: "no check was created by this run to settle" };
+  if (owned.status === "completed" && owned.conclusion === "cancelled")
+    return { kind: "noop", reason: "the check already records this cancelled run" };
+  if (owned.status === "completed" && owned.conclusion !== null && settled.has(owned.conclusion))
+    return { kind: "noop", reason: "a completed review already recorded this head" };
+  return { kind: "patch", id: owned.id, status: "completed", conclusion: "cancelled" };
+};
+var CHECK_JQ = ".check_runs[] | {id: .id, status: .status, conclusion: .conclusion, detailsUrl: .details_url}";
+var fetchChecks = async (repo, headSha, ghApi) => parseJsonl(
+  await ghApi([
+    `repos/${repo}/commits/${headSha}/check-runs?check_name=${encodeURIComponent(CHECK_RUN_NAME)}&per_page=100`,
+    "--paginate",
+    "--jq",
+    CHECK_JQ
+  ])
+);
+var output = (intent, runUrl) => {
+  switch (intent) {
+    case "in_progress":
+      return {
+        title: "Code review in progress",
+        summary: `The review is running \u2014 [see the run](${runUrl}).`
+      };
+    case "neutral":
+      return {
+        title: "Code review complete",
+        summary: `The review was posted \u2014 [see the run](${runUrl}).`
+      };
+    case "failure":
+      return {
+        title: "Code review did not complete",
+        summary: `The review job failed \u2014 [see the run](${runUrl}). Re-request the review; do not treat this round as spent.`
+      };
+    case "cancelled":
+      return {
+        title: "Code review superseded",
+        summary: `This review run was cancelled \u2014 [see the run](${runUrl}). No action needed.`
+      };
+  }
+};
+var checkRun = async (input, ghApi = runGhApi) => {
+  const checks = await fetchChecks(input.repo, input.headSha, ghApi);
+  const action = input.intent === "cancelled" ? decideCancelledAction(checks, input.runUrl) : decideCheckAction(checks, input.intent, input.runUrl);
+  if (action.kind === "noop") {
+    process.stderr.write(`code-review check-run: ${action.reason} \u2014 leaving it
+`);
+    return;
+  }
+  const body = action.kind === "create" ? {
+    name: CHECK_RUN_NAME,
+    head_sha: input.headSha,
+    status: action.status,
+    details_url: input.runUrl,
+    ...action.conclusion ? { conclusion: action.conclusion } : {},
+    output: output(input.intent, input.runUrl)
+  } : {
+    status: action.status,
+    conclusion: action.conclusion,
+    details_url: input.runUrl,
+    output: output(input.intent, input.runUrl)
+  };
+  const endpoint = action.kind === "create" ? [`--method`, `POST`, `repos/${input.repo}/check-runs`, `--input`, `-`] : [
+    `--method`,
+    `PATCH`,
+    `repos/${input.repo}/check-runs/${String(action.id)}`,
+    `--input`,
+    `-`
+  ];
+  await ghApi(endpoint, JSON.stringify(body));
+};
+
 // src/post.ts
 var DEFAULT_MARKER = "<!-- code-review -->";
+var EMPTY_MECHANIC_LEAVE_MESSAGE = "The CI-fix pass found no issues and the sticky already reflects a completed full review \u2014 leaving it in place\n";
 var MAX_SUGGESTION_LINES = 10;
 var countSuggestionLines = (text) => text.split("\n").length;
 var checkLongSuggestions = (comments) => {
@@ -1608,12 +1991,33 @@ var post = async (input, ghApi = runGhApi) => {
   );
   const existingComplete = existingSticky !== null && parseReviewComplete(existingSticky.body);
   const wouldBuryCompleted = (incomplete) => incomplete && existingComplete;
+  const priorIsFullReview = (body) => isFullReviewSticky(body) || parseReviewedRoute(body) === null && (parseReviewComplete(body) || parseCompletedAncestor(body));
+  const emptyMechanicWouldBury = (route, incomplete) => route === "mechanic" && !incomplete && findings.findings.length === 0 && existingSticky !== null && priorIsFullReview(existingSticky.body);
   const priorRounds = existingSticky !== null ? parseRounds(existingSticky.body) : [];
-  const leaveInPlace = () => {
+  const priorSignal = existingSticky === null ? null : parseSignalMarker(existingSticky.body) ?? parseSurfaceSignal(parseFindingsMarker(existingSticky.body));
+  const findingsMarkerFor = (findings2, signal2) => {
+    const pointer = surfacedFindingsPointer(findings2, signal2, input.jsonUrl);
+    return signal2 !== null || priorSignal === null ? pointer : `${pointer}
+${signalMarker(priorSignal)}`;
+  };
+  const leaveInPlace = (message) => {
     process.stderr.write(
-      `Review did not complete and the sticky already reflects a completed review \u2014 leaving it in place
-`
+      message ?? "Review did not complete and the sticky already reflects a completed review \u2014 leaving it in place\n"
+    );
+    process.exit(0);
+  };
+  const emptyMechanicLeaveOrNote = async (sticky) => {
+    if (existingComplete) leaveInPlace(EMPTY_MECHANIC_LEAVE_MESSAGE);
+    const priorSha = parseReviewedSha(sticky.body);
+    const body = formatMarkdown(
+      noticeBody(
+        `${DEFAULT_MARKER}
+
+\u26A0\uFE0F **CI-fix pass completed with no findings** for \`${input.headSha.slice(0, 7)}\` \u2014 the completed full review of \`${priorSha ? priorSha.slice(0, 7) : "an earlier commit"}\` is preserved below.`,
+        sticky.body
+      )
     );
+    await upsertSticky(input.repo, prNumber, sticky, body, ghApi);
     process.exit(0);
   };
   const prices = JSON.parse(readFileSync(input.pricesPath, "utf-8"));
@@ -1623,24 +2027,34 @@ var post = async (input, ghApi = runGhApi) => {
   }
   const template = readFileSync(input.templatePath, "utf-8");
   const inlineTemplate = readFileSync(input.inlineTemplatePath, "utf-8");
-  const renderNotice = (message) => formatMarkdown(
-    render({
-      findings: incompleteFindings(`### \u26A0\uFE0F ${message}`),
-      envelope: null,
-      incomplete: true,
-      prices: decodedPrices.right,
-      pricesProvided: input.pricesProvided,
-      template,
-      route: input.route,
-      reviewedSha: input.headSha,
-      effort: input.effort,
-      rounds: priorRounds,
-      convergenceRound: false,
-      runUrl: input.runUrl,
-      jsonUrl: input.jsonUrl,
-      postedAt: input.postedAt
-    })
-  );
+  const renderNotice = (message) => {
+    const findings2 = incompleteFindings(`### \u26A0\uFE0F ${message}`);
+    return formatMarkdown(
+      render({
+        findings: findings2,
+        envelope: null,
+        incomplete: true,
+        prices: decodedPrices.right,
+        pricesProvided: input.pricesProvided,
+        template,
+        route: input.route,
+        reviewedSha: input.headSha,
+        effort: input.effort,
+        rounds: priorRounds,
+        sameRootNotes: {},
+        roundCount: priorSignal?.round ?? priorRounds.length,
+        convergenceRound: false,
+        runUrl: input.runUrl,
+        jsonUrl: input.jsonUrl,
+        // A notice's own blob stays clean: verdict "error" + a carried "converged" would read as a
+        // stop signal for a run that produced no verdict (issue #141 review r2). The prior signal
+        // survives on the sticky in the compact marker (findingsMarkerFor), and the carried-forward
+        // trajectory (rounds marker) remains the historical record.
+        findingsPointer: findingsMarkerFor(findings2, null),
+        postedAt: input.postedAt
+      })
+    );
+  };
   if (isEmptyDiff(diff)) {
     if (wouldBuryCompleted(true)) leaveInPlace();
     await upsertSticky(
@@ -1667,9 +2081,12 @@ var post = async (input, ghApi = runGhApi) => {
   const findings = findingsResult.findings;
   const envelope = loadEnvelope(input.envelopePath);
   const testReport = input.testReportPath ? loadTestReport(input.testReportPath) : void 0;
+  const effectiveRoute = input.route ?? envelope?.route;
   if (envelope === null) {
     const envelopelessIncomplete = isIncompleteFindings(findings);
     if (wouldBuryCompleted(envelopelessIncomplete)) leaveInPlace();
+    if (emptyMechanicWouldBury(effectiveRoute, envelopelessIncomplete) && existingSticky !== null)
+      await emptyMechanicLeaveOrNote(existingSticky);
     const body = formatMarkdown(
       render({
         findings,
@@ -1678,15 +2095,23 @@ var post = async (input, ghApi = runGhApi) => {
         prices: decodedPrices.right,
         pricesProvided: input.pricesProvided,
         template,
-        route: input.route,
+        route: effectiveRoute,
         reviewedSha: input.headSha,
         effort: input.effort,
         rounds: priorRounds,
+        sameRootNotes: {},
+        roundCount: priorSignal?.round ?? priorRounds.length,
         convergenceRound: false,
         testReport,
         inlineDisposition: { kind: "no-envelope" },
         runUrl: input.runUrl,
         jsonUrl: input.jsonUrl,
+        // Same signal rule as the main path: only a completed-review doc carries the prior signal
+        // in its blob; an error-verdict doc preserves it in the compact marker instead.
+        findingsPointer: findingsMarkerFor(
+          findings,
+          isReviewVerdict(findings.verdict) ? priorSignal : null
+        ),
         postedAt: input.postedAt
       })
     );
@@ -1698,7 +2123,10 @@ var post = async (input, ghApi = runGhApi) => {
   }
   const thisIncomplete = envelope.incomplete === true || isIncompleteFindings(findings);
   if (wouldBuryCompleted(thisIncomplete)) leaveInPlace();
-  const findingsMarker = findingsPointer(findings, input.jsonUrl);
+  if (emptyMechanicWouldBury(effectiveRoute, thisIncomplete) && existingSticky !== null)
+    await emptyMechanicLeaveOrNote(existingSticky);
+  const isRound = isConvergenceRound(effectiveRoute, thisIncomplete) && isReviewVerdict(findings.verdict);
+  const sameRootNotes = isRound ? computeSameRootNotes(priorRounds, findings.findings, input.headSha.slice(0, 12)) : {};
   const {
     comments: rawComments,
     strays,
@@ -1707,7 +2135,8 @@ var post = async (input, ghApi = runGhApi) => {
     inlineTemplate,
     models: envelope.models.map((m) => m.model),
     findings,
-    jsonUrl: input.jsonUrl
+    jsonUrl: input.jsonUrl,
+    sameRootNotes
   });
   const { comments, longFiles } = checkLongSuggestions(rawComments);
   for (const wf of longFiles) {
@@ -1719,9 +2148,31 @@ var post = async (input, ghApi = runGhApi) => {
   const botReviews = await fetchBotReviews(input.repo, prNumber, input.botLogin, ghApi);
   const initialDisposition = comments.length === 0 && strays.length > 0 ? { kind: "none-in-diff" } : void 0;
   const currentCounts = computeSeverityCounts(findings.findings);
-  const effectiveRoute = input.route ?? envelope.route;
-  const isRound = isConvergenceRound(effectiveRoute, thisIncomplete);
-  const rounds = isRound ? [...priorRounds, currentCounts] : priorRounds;
+  const currentCodes = computeCodeCounts(findings.findings, findings.systemic_problems ?? []);
+  const priorLastCodes = priorRounds.length > 0 ? priorRounds[priorRounds.length - 1]?.codes : void 0;
+  const roundNumber = Math.max(priorSignal?.round ?? priorRounds.length, priorRounds.length) + 1;
+  const rounds = isRound ? [
+    ...priorRounds,
+    roundRecord(
+      computeRoundCounts(findings),
+      currentCodes,
+      priorLastCodes,
+      input.headSha.slice(0, 12),
+      roundNumber
+    )
+  ] : priorRounds;
+  const signal = isRound ? signalForRound(roundNumber, computeRoundCounts(findings), input.convergenceThreshold) : thisIncomplete || !isReviewVerdict(findings.verdict) ? null : priorSignal;
+  const findingsMarker = findingsMarkerFor(findings, signal);
+  const markerForm = findingsMarkerForm(surfaceFindings(findings, signal), input.jsonUrl);
+  if (markerForm === "link") {
+    process.stderr.write(
+      "Warning: the findings-json marker exceeds the embed limit \u2014 degraded to the jsonUrl-link form; a decoding agent must fetch the artifact instead of the embedded JSON\n"
+    );
+  } else if (markerForm === "omitted") {
+    process.stderr.write(
+      "Warning: the findings-json marker exceeds the embed limit and no --json-url was given \u2014 the machine-readable channel is omitted from the posted surfaces\n"
+    );
+  }
   const commonRenderInput = {
     findings,
     envelope,
@@ -1729,12 +2180,14 @@ var post = async (input, ghApi = runGhApi) => {
     prices: decodedPrices.right,
     pricesProvided: input.pricesProvided,
     template,
-    route: input.route,
+    route: effectiveRoute,
     reviewedSha: input.headSha,
     effort: input.effort,
     testReport,
     severityCounts: currentCounts,
     rounds,
+    sameRootNotes,
+    roundCount: signal?.round ?? priorSignal?.round ?? priorRounds.length,
     convergenceThreshold: input.convergenceThreshold,
     convergenceRound: isRound,
     strays,
@@ -1817,15 +2270,22 @@ var post = async (input, ghApi = runGhApi) => {
     }
   }
 };
-var announceBody = (headSha, runUrl, existingBody) => {
-  const notice = `${DEFAULT_MARKER}
-
-\u{1F504} **Code review in progress** for \`${headSha.slice(0, 7)}\` \u2014 see the [workflow run](${runUrl}) for progress; this comment is updated with the review when it completes.`;
+var noticeBody = (lead, existingBody) => {
   const carried = existingBody ? carryForwardMarkers(existingBody) : "";
-  return carried ? `${notice}
+  return carried ? `${lead}
 
-${carried}` : notice;
+${carried}` : lead;
+};
+var bodyRefsRun = (body, runUrl) => {
+  const runId = runIdFromUrl(runUrl);
+  return runId === null ? body.includes(runUrl) : new RegExp(`/actions/runs/${runId}(?!\\d)`).test(body);
 };
+var announceBody = (headSha, runUrl, existingBody) => noticeBody(
+  `${DEFAULT_MARKER}
+
+\u{1F504} **Code review in progress** for \`${headSha.slice(0, 7)}\` \u2014 see the [workflow run](${runUrl}) for progress; this comment is updated with the review when it completes.`,
+  existingBody
+);
 var announce = async (input, ghApi = runGhApi) => {
   const candidates = await fetchPrCandidates(input.repo, input.headSha, ghApi);
   const resolution = resolvePr(candidates, input.headBranch);
@@ -1858,15 +2318,18 @@ var announce = async (input, ghApi = runGhApi) => {
     ghApi
   );
 };
-var incompleteBody = (headSha, runUrl, existingBody) => {
-  const notice = `${DEFAULT_MARKER}
+var incompleteBody = (headSha, runUrl, existingBody) => noticeBody(
+  `${DEFAULT_MARKER}
 
-\u26A0\uFE0F **Code review did not complete** for \`${headSha.slice(0, 7)}\` \u2014 the review job failed ([run](${runUrl})). Re-request the review; do not treat this round as spent.`;
-  const carried = existingBody ? carryForwardMarkers(existingBody) : "";
-  return carried ? `${notice}
+\u26A0\uFE0F **Code review did not complete** for \`${headSha.slice(0, 7)}\` \u2014 the review job failed ([run](${runUrl})). Re-request the review; do not treat this round as spent.`,
+  existingBody
+);
+var cancelledBody = (headSha, runUrl, existingBody) => noticeBody(
+  `${DEFAULT_MARKER}
 
-${carried}` : notice;
-};
+\u21A9\uFE0F **Code review superseded** for \`${headSha.slice(0, 7)}\` \u2014 this run was cancelled before completing, typically because a newer review run started on this branch. No action needed. [View the cancelled run](${runUrl}) for the record.`,
+  existingBody
+);
 var reportIncomplete = async (input, ghApi = runGhApi) => {
   const candidates = await fetchPrCandidates(input.repo, input.headSha, ghApi);
   const resolution = resolvePr(candidates, input.headBranch);
@@ -1889,8 +2352,13 @@ var reportIncomplete = async (input, ghApi = runGhApi) => {
 `);
     return;
   }
-  if (existing !== null && !existing.body.includes(input.runUrl)) {
+  if (existing !== null && !bodyRefsRun(existing.body, input.runUrl)) {
     process.stderr.write(`Sticky belongs to another run \u2014 leaving it in place
+`);
+    return;
+  }
+  if (input.cancelled && existing === null) {
+    process.stderr.write(`Cancelled review has no sticky to supersede \u2014 leaving it absent
 `);
     return;
   }
@@ -1898,94 +2366,10 @@ var reportIncomplete = async (input, ghApi = runGhApi) => {
     input.repo,
     resolution.prNumber,
     existing,
-    incompleteBody(input.headSha, input.runUrl, existing?.body),
+    input.cancelled ? cancelledBody(input.headSha, input.runUrl, existing?.body) : incompleteBody(input.headSha, input.runUrl, existing?.body),
     ghApi
   );
 };
-
-// src/checkrun.ts
-var CHECK_RUN_NAME = "Code review";
-var latest = (checks) => checks.reduce(
-  (best, c) => best === null || c.id > best.id ? c : best,
-  null
-);
-var isOpen = (status) => status === "in_progress" || status === "queued";
-var settled = /* @__PURE__ */ new Set(["success", "neutral", "skipped"]);
-var decideCheckAction = (checks, intent) => {
-  const head = latest(checks);
-  switch (intent) {
-    case "in_progress":
-      return head !== null && isOpen(head.status) ? { kind: "noop", reason: "a check is already in progress for this head" } : { kind: "create", status: "in_progress" };
-    case "neutral":
-      if (head === null) return { kind: "create", status: "completed", conclusion: "neutral" };
-      return head.status === "completed" && head.conclusion === "neutral" ? { kind: "noop", reason: "the check already records this completed review" } : { kind: "patch", id: head.id, status: "completed", conclusion: "neutral" };
-    case "failure":
-      if (head === null) return { kind: "create", status: "completed", conclusion: "failure" };
-      if (head.status === "completed" && head.conclusion !== null && settled.has(head.conclusion))
-        return { kind: "noop", reason: "a completed review already recorded this head" };
-      return head.status === "completed" && head.conclusion === "failure" ? { kind: "noop", reason: "the check already records this failure" } : { kind: "patch", id: head.id, status: "completed", conclusion: "failure" };
-  }
-};
-var CHECK_JQ = ".check_runs[] | {id: .id, status: .status, conclusion: .conclusion}";
-var fetchChecks = async (repo, headSha, ghApi) => parseJsonl(
-  await ghApi([
-    `repos/${repo}/commits/${headSha}/check-runs?check_name=${encodeURIComponent(CHECK_RUN_NAME)}&per_page=100`,
-    "--paginate",
-    "--jq",
-    CHECK_JQ
-  ])
-);
-var output = (intent, runUrl) => {
-  switch (intent) {
-    case "in_progress":
-      return {
-        title: "Code review in progress",
-        summary: `The review is running \u2014 [see the run](${runUrl}).`
-      };
-    case "neutral":
-      return {
-        title: "Code review complete",
-        summary: `The review was posted \u2014 [see the run](${runUrl}).`
-      };
-    case "failure":
-      return {
-        title: "Code review did not complete",
-        summary: `The review job failed \u2014 [see the run](${runUrl}). Re-request the review; do not treat this round as spent.`
-      };
-  }
-};
-var checkRun = async (input, ghApi = runGhApi) => {
-  const action = decideCheckAction(
-    await fetchChecks(input.repo, input.headSha, ghApi),
-    input.intent
-  );
-  if (action.kind === "noop") {
-    process.stderr.write(`code-review check-run: ${action.reason} \u2014 leaving it
-`);
-    return;
-  }
-  const body = action.kind === "create" ? {
-    name: CHECK_RUN_NAME,
-    head_sha: input.headSha,
-    status: action.status,
-    details_url: input.runUrl,
-    ...action.conclusion ? { conclusion: action.conclusion } : {},
-    output: output(input.intent, input.runUrl)
-  } : {
-    status: action.status,
-    conclusion: action.conclusion,
-    details_url: input.runUrl,
-    output: output(input.intent, input.runUrl)
-  };
-  const endpoint = action.kind === "create" ? [`--method`, `POST`, `repos/${input.repo}/check-runs`, `--input`, `-`] : [
-    `--method`,
-    `PATCH`,
-    `repos/${input.repo}/check-runs/${String(action.id)}`,
-    `--input`,
-    `-`
-  ];
-  await ghApi(endpoint, JSON.stringify(body));
-};
 var DURATION_RE = /^(\d+)(h|m|s)$/;
 var USD_RE = /^\$(\d+(?:\.\d+)?)$/;
 var toSeconds = (n, unit) => unit === "h" ? n * 3600 : unit === "m" ? n * 60 : n;
@@ -2192,12 +2576,12 @@ var resolveCiRun = async (repo, headSha, workflowName, ghApi) => {
 `
     );
   }
-  const latest2 = runs.filter((r) => r.name === workflowName).reduce(
+  const latest = runs.filter((r) => r.name === workflowName).reduce(
     (best, r) => best === null || r.run_number > best.run_number ? r : best,
     null
   );
   return {
-    run: latest2 === null ? null : { id: latest2.id, status: latest2.status ?? "unknown", conclusion: latest2.conclusion },
+    run: latest === null ? null : { id: latest.id, status: latest.status ?? "unknown", conclusion: latest.conclusion },
     seenNames: [...new Set(runs.flatMap((r) => r.name === null ? [] : [r.name]))]
   };
 };
@@ -2748,28 +3132,21 @@ var nativeTelemetry = (native, meta) => resolveTelemetry(
 );
 var absentTelemetry = (meta) => resolveTelemetry({ models: [], turns: 0, durationMs: 0, vendorCostUsd: null }, meta);
 var buildEnvelope = (telemetry, native, agentFilePath, agentFileFallbackPath, seedUnrevised) => {
-  if (seedUnrevised)
-    return {
-      schema_version: DEFAULT_SCHEMA_VERSION,
-      findings: incompleteFindings(
-        "### \u26A0\uFE0F Review did not complete\n\nThe review agent did not write a review (its draft is the untouched pre-seed). See the workflow logs."
-      ),
-      incomplete: true,
-      ...telemetry
-    };
   const outcome = findingsOutcome(native, agentFilePath, agentFileFallbackPath);
   switch (outcome.kind) {
     case "ok":
       return { schema_version: outcome.version, findings: outcome.findings, ...telemetry };
-    case "telemetry-only":
+    case "telemetry-only": {
+      const reason = seedUnrevised ? "the review agent did not write a review (its draft is still the pre-seeded sentinel)" : outcome.reason;
       return {
         schema_version: DEFAULT_SCHEMA_VERSION,
         findings: incompleteFindings(`### \u26A0\uFE0F Review did not complete
 
-${outcome.reason}`),
+${reason}`),
         incomplete: true,
         ...telemetry
       };
+    }
   }
 };
 var adapt = (adapterName, native, agentFilePath, meta = {}) => {
@@ -2848,6 +3225,21 @@ var buildSandboxConfig = (opts) => ({
   filesystem: { allowRead: [], denyRead: [], allowWrite: ["/"], denyWrite: [] }
 });
 
+// src/scope.ts
+var SCOPE_SEPARATOR_RE = /[\s,;]+/;
+var parseScope = (raw) => {
+  const trimmed = raw?.trim();
+  if (trimmed === void 0 || trimmed === "") return { kind: "absent" };
+  if (UNSAFE_IN_SUMMARY.test(trimmed)) {
+    return {
+      kind: "invalid",
+      reason: 'scope contains a character (newline, carriage return, backtick, "<", ">", or "|") that would corrupt the review prompt \u2014 use plain language names/tags'
+    };
+  }
+  const languages = Array.from(new Set(trimmed.split(SCOPE_SEPARATOR_RE).filter((t7) => t7 !== "")));
+  return languages.length === 0 ? { kind: "absent" } : { kind: "ok", languages };
+};
+
 // src/index.ts
 var readJSON = (path) => {
   try {
@@ -3010,6 +3402,9 @@ var renderCmd = defineCommand({
     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 route = args.route || envelope.route || null;
+    const isRound = isConvergenceRound(route, envelope.incomplete === true || isIncompleteFindings(findings)) && isReviewVerdict(findings.verdict);
+    const counts = computeRoundCounts(findings);
     const output2 = render({
       findings,
       envelope,
@@ -3020,6 +3415,7 @@ var renderCmd = defineCommand({
       route: args.route,
       effort: args.effort,
       testReport,
+      rounds: isRound ? [counts] : [],
       convergenceThreshold: parseConvergenceThreshold(args["convergence-threshold"]),
       postedAt: formatUtc(/* @__PURE__ */ new Date())
     });
@@ -3153,21 +3549,33 @@ var parseConvergenceThreshold = (raw) => {
   }
   return n;
 };
-var mtimeMsOf = (path) => {
+var transcriptPathOf = (input) => {
+  const tp = (typeof input === "object" && input !== null ? input : {})["transcript_path"];
+  return typeof tp === "string" ? tp : void 0;
+};
+var statMtimeMsOrNull = (path) => {
   try {
     return statSync(path).mtimeMs;
   } catch {
     return null;
   }
 };
-var transcriptPathOf = (input) => {
-  const tp = (typeof input === "object" && input !== null ? input : {})["transcript_path"];
-  return typeof tp === "string" ? tp : void 0;
+var statSizeOrNull = (path) => {
+  try {
+    return statSync(path).size;
+  } catch {
+    return null;
+  }
 };
 var snapshotIfValid = (draftPath) => {
   try {
+    const snapPath = lastValidPath(draftPath);
+    const draftMtime = statMtimeMsOrNull(draftPath);
+    if (draftMtime === null) return;
+    const snapMtime = statMtimeMsOrNull(snapPath);
+    if (snapMtime !== null && draftMtime <= snapMtime) return;
     if (extractStructured({ kind: "findings", native: void 0, agentFilePath: draftPath }).kind === "ok")
-      copyFileSync(draftPath, lastValidPath(draftPath));
+      copyFileSync(draftPath, snapPath);
   } catch (err) {
     process.stderr.write(
       `code-review: could not snapshot the last-valid draft (${errMsg(err)}) \u2014 any prior snapshot is unchanged
@@ -3242,10 +3650,8 @@ var budgetHookCmd = defineCommand({
           flatMs: args["reserve-wall"] ? parseWallMs(args["reserve-wall"]) ?? DEFAULT_RESERVE.flatMs : DEFAULT_RESERVE.flatMs
         },
         draftPath,
-        mainDraftWritten: mainHasWrittenDraft(
-          mtimeMsOf(draftPath),
-          mtimeMsOf(seedMarkerPath(draftPath))
-        )
+        // Lazy: the spawn gate is the only consumer, and the hook fires on every tool event.
+        mainDraftWritten: () => mainHasWrittenDraft(readFileOrNull(draftPath))
       });
       if (asRecord(input)?.["hook_event_name"] === "PostToolBatch" && !isSubagentHookInput(input))
         snapshotIfValid(draftPath);
@@ -3428,12 +3834,12 @@ ${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. 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"
+    description: "Initialize $DRAFT before the review runs: write a NON-REVIEW SENTINEL (no recovery path can validate it as a review), and deliver the decoded findings of a prior review OUT-OF-BAND to a read-only context file beside the draft when one exists and still validates (incremental re-review). Skips a prior that never completed (an error-verdict notice) or that a CI-fix mechanic pass produced \u2014 the seed chain is route-aware. Prints the mode to stdout (prior-same|prior-new when prior context was delivered, 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 sentinel 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"
+      description: "Path to the prior-review JSON gather staged ({ id, body }, or the literal null); its embedded base64 findings marker is decoded and delivered as re-review context when it validates against the schema"
     },
     "head-sha": {
       type: "string",
@@ -3441,7 +3847,7 @@ var seedDraftCmd = defineCommand({
     },
     out: {
       type: "string",
-      description: "Path to write the seed $DRAFT to (an absolute path outside the worktree)",
+      description: "Path to write the sentinel $DRAFT to (an absolute path outside the worktree)",
       required: true
     },
     kind: {
@@ -3454,7 +3860,7 @@ var seedDraftCmd = defineCommand({
     },
     "schema-version": {
       type: "string",
-      description: "Schema major.minor to validate the prior findings against (default: the kind's latest \u2014 an older-shaped prior review then falls back to the empty scaffold)"
+      description: "Schema major.minor to validate the prior findings against (default: the kind's latest \u2014 an older-shaped prior review then delivers no context)"
     }
   },
   run: async ({ args }) => {
@@ -3467,29 +3873,17 @@ var seedDraftCmd = defineCommand({
 `
       );
     }
-    const writeSeedMarker = () => {
+    const writeSentinel = () => {
       try {
-        writeFileSync(seedMarkerPath(outPath), "code-review seed marker\n");
-      } catch (err) {
+        writeFileSync(outPath, SEED_SENTINEL);
         process.stderr.write(
-          `Warning: could not write the seed marker beside ${outPath} (${errMsg(err)}) \u2014 the seeded draft will count as agent-written
-`
-        );
-      }
-    };
-    const writeScaffold = () => {
-      try {
-        writeFileSync(outPath, `${JSON.stringify(emptyFindings(""), null, 2)}
-`);
-        writeSeedMarker();
-        process.stderr.write(
-          `Seeded ${outPath} with an empty valid scaffold \u2014 no decodable prior findings to build on
+          `Seeded ${outPath} with the non-review sentinel \u2014 the agent must replace it with its review
 `
         );
         return true;
       } catch (err) {
         process.stderr.write(
-          `Warning: could not write the seed scaffold to ${outPath} (${errMsg(err)}) \u2014 the agent will create $DRAFT itself
+          `Warning: could not write the seed sentinel to ${outPath} (${errMsg(err)}) \u2014 the agent will create $DRAFT itself
 `
         );
         return false;
@@ -3506,24 +3900,30 @@ var seedDraftCmd = defineCommand({
       })();
       return typeof raw === "object" && raw !== null && "body" in raw && typeof raw.body === "string" ? raw.body : null;
     })();
-    const priorFindings = priorBody === null ? null : parseFindingsMarker(priorBody);
+    const priorFindings = priorBody === null ? null : stripSurfaceFields(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;
+        const resolution = resolve("findings", priorFindings);
+        if (resolution.kind !== "ok") return false;
+        if (isIncompleteFindings(resolution.value)) return false;
+        if (parseReviewedRoute(priorBody ?? "") !== "full review") return false;
+        writeFileSync(outPath, SEED_SENTINEL);
+        writeFileSync(
+          priorContextPath(outPath),
+          `${JSON.stringify(priorFindings, null, 2)}
+`
+        );
+        const count = resolution.value.findings.length;
         process.stderr.write(
-          `Seeded ${outPath} from the prior review (${String(count)} finding(s))
+          `Seeded ${outPath} with the sentinel and wrote the prior review (${String(count)} finding(s)) to ${priorContextPath(outPath)} as context
 `
         );
         return true;
       } catch (err) {
         process.stderr.write(
-          `Warning: could not seed from the prior review (${errMsg(err)}) \u2014 falling back to the empty scaffold
+          `Warning: could not seed from the prior review (${errMsg(err)}) \u2014 seeding the sentinel only
 `
         );
         return false;
@@ -3534,7 +3934,7 @@ var seedDraftCmd = defineCommand({
         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";
+      if (!writeSentinel()) return "none";
       return priorBody === null ? "empty" : "empty-had-prior";
     })();
     process.stdout.write(`${mode}
@@ -3580,7 +3980,8 @@ var adaptCmd = defineCommand({
   },
   run: async ({ args }) => {
     const agentFile = args["agent-file"];
-    const seedUnrevised = agentFile ? !mainHasWrittenDraft(mtimeMsOf(agentFile), mtimeMsOf(seedMarkerPath(agentFile))) : false;
+    const agentFileSize = agentFile ? statSizeOrNull(agentFile) : null;
+    const seedUnrevised = agentFileSize !== null && agentFileSize <= Buffer.byteLength(SEED_SENTINEL) + 2 && isSeedSentinel(readFileOrNull(agentFile));
     const envelope = unwrapAdapt(
       adapt(requireAdapterName(args.adapter), readJSONOrAbsent(args.native), agentFile, {
         route: args.route,
@@ -4077,11 +4478,11 @@ var announceCmd = defineCommand({
     );
   }
 });
-var isCheckIntent = (s) => s === "in_progress" || s === "neutral" || s === "failure";
+var isCheckIntent = (s) => s === "in_progress" || s === "neutral" || s === "failure" || s === "cancelled";
 var checkRunCmd = defineCommand({
   meta: {
     name: "check-run",
-    description: "Upsert the native 'Code review' check-run on the head SHA \u2014 the attribution surface that appears in the PR's own checks list and (writing to the base repo) works for fork PRs too. `in_progress` at review start, `neutral` when the review completes, `failure` when it didn't. Forward-only: `failure` never overwrites a completed review."
+    description: "Upsert the native 'Code review' check-run on the head SHA \u2014 the attribution surface that appears in the PR's own checks list and (writing to the base repo) works for fork PRs too. `in_progress` at review start, `neutral` when the review completes, `failure` when it didn't, `cancelled` when a cancelled review settles its own check (matched by details_url, so it never touches a superseding run's check). Forward-only: `failure`/`cancelled` never overwrite a completed review."
   },
   args: {
     repo: { type: "string", description: "Repository (owner/name)", required: true },
@@ -4092,19 +4493,19 @@ var checkRunCmd = defineCommand({
     },
     status: {
       type: "positional",
-      description: "One of: in_progress, neutral, failure",
+      description: "One of: in_progress, neutral, failure, cancelled",
       required: true
     },
     "run-url": {
       type: "string",
-      description: "Workflow run URL the check-run's details link to",
+      description: "Workflow run URL the check-run's details link to (also the ownership key for `cancelled`)",
       required: true
     }
   },
   run: async ({ args }) => {
     if (!isCheckIntent(args.status)) {
       process.stderr.write(
-        `::warning::code-review check-run: unrecognized status "${annotationSafe(args.status)}" \u2014 expected in_progress, neutral, or failure; skipping
+        `::warning::code-review check-run: unrecognized status "${annotationSafe(args.status)}" \u2014 expected in_progress, neutral, failure, or cancelled; skipping
 `
       );
       return;
@@ -4125,7 +4526,7 @@ var checkRunCmd = defineCommand({
 var reportIncompleteCmd = defineCommand({
   meta: {
     name: "report-incomplete",
-    description: "Post (or update) the sticky when a review job hard-failed and posted nothing \u2014 an attributed 'did not complete' notice linking the run, telling the reader to re-request. Never buries a completed review, and never overwrites a superseding run's live in-progress placeholder. (A cancelled review is left to the superseding run that took over.)"
+    description: "Post (or update) the sticky when a review job hard-failed and posted nothing \u2014 an attributed 'did not complete' notice linking the run, telling the reader to re-request; with --cancelled, the informational 'superseded \u2014 no action needed' notice instead (issue #139). Never buries a completed review, and never overwrites a superseding run's live in-progress placeholder."
   },
   args: {
     repo: { type: "string", description: "Repository (owner/name)", required: true },
@@ -4146,6 +4547,10 @@ var reportIncompleteCmd = defineCommand({
     "head-branch": {
       type: "string",
       description: "Head branch to disambiguate the PR when multiple share a commit"
+    },
+    cancelled: {
+      type: "boolean",
+      description: "This run was CANCELLED before completing (typically superseded by a newer run on the same branch) \u2014 post the informational 'superseded' notice, not the failure notice (issue #139)"
     }
   },
   run: async ({ args }) => {
@@ -4154,10 +4559,11 @@ var reportIncompleteCmd = defineCommand({
       headSha: args["head-sha"],
       botLogin: args["bot-login"] || "github-actions[bot]",
       runUrl: args["run-url"],
-      headBranch: args["head-branch"]
+      headBranch: args["head-branch"],
+      cancelled: args.cancelled
     }).catch(
       (err) => process.stderr.write(
-        `::warning::code-review report-incomplete: could not post the failure notice (${annotationSafe(errMsg(err))}) \u2014 continuing
+        `::warning::code-review report-incomplete: could not post the notice (${annotationSafe(errMsg(err))}) \u2014 continuing
 `
       )
     );
@@ -4321,6 +4727,30 @@ var awaitCiCmd = defineCommand({
     process.stdout.write(renderCiOutputs(outcome));
   }
 });
+var checkScopeCmd = defineCommand({
+  meta: {
+    name: "check-scope",
+    description: "Validate + normalize the workflow's `scope` input \u2014 the languages/inputs the project accepts (issue #139). Prints the normalized space-separated language list for splicing into the review prompt, or nothing when the scope is empty (the reviewer then infers it from the README's first paragraph). Fails loudly on a malformed value, so a config typo never silently corrupts the prompt it is spliced into."
+  },
+  args: {
+    scope: {
+      type: "string",
+      description: 'The raw scope value \u2014 whitespace/comma/semicolon-separated language names (e.g. "C C++"); empty \u21D2 absent'
+    }
+  },
+  run: ({ args }) => {
+    const parsed = parseScope(args.scope);
+    switch (parsed.kind) {
+      case "absent":
+        return;
+      case "invalid":
+        return fail(`check-scope: ${parsed.reason}`);
+      case "ok":
+        process.stdout.write(`${parsed.languages.join(" ")}
+`);
+    }
+  }
+});
 var sandboxConfigCmd = defineCommand({
   meta: {
     name: "sandbox-config",
@@ -4391,6 +4821,7 @@ var main = defineCommand({
     post: postCmd,
     announce: announceCmd,
     "check-run": checkRunCmd,
+    "check-scope": checkScopeCmd,
     "report-incomplete": reportIncompleteCmd,
     cost: costCmd,
     "check-cost": checkCostCmd,