@jphutchins/code-review 0.1.0-alpha.11 → 0.1.0-alpha.13

package/dist/index.js

@@ -178,6 +178,16 @@ ${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 parseFindingsMarker = (body) => {
+  const match = /<!-- code-review:findings-json;base64 ([A-Za-z0-9+/=]+) -->/.exec(body);
+  const b64 = match?.[1];
+  if (b64 === void 0) return null;
+  try {
+    return JSON.parse(Buffer.from(b64, "base64").toString("utf-8"));
+  } catch {
+    return null;
+  }
+};
 var escapeFence = (text) => text.replace(/```/g, "`` ` ``");
 var projectPatch = (patch) => {
   if (patch === void 0) return { kind: "none" };
@@ -234,6 +244,7 @@ var render = (input) => {
     postedAt: input.postedAt ?? "",
     severityCounts: input.severityCounts ?? computeSeverityCounts(input.findings.findings),
     strays: (input.strays ?? []).map(sanitizeFinding),
+    unanchoredCount: input.unanchoredCount ?? 0,
     inlineDisposition: input.inlineDisposition ?? null,
     runUrl: input.runUrl ?? null,
     jsonUrl: input.jsonUrl ?? null,
@@ -355,7 +366,7 @@ var buildInlineComments = (findings, diff, context) => {
     }
     return comment;
   });
-  return { comments, strays };
+  return { comments, strays, inDiff };
 };
 var renderStraysSection = (strays) => {
   if (strays.length === 0) return "";
@@ -660,7 +671,7 @@ var decideGate = (state, nudges, maxNudges, draftPath, kind) => {
     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.`
+      `Write it to ${draftPath}, then run "code-review validate ${draftPath} --kind ${kind} --explain" until it exits 0 before ending your turn (--explain prints the schema when the shape is wrong).`
     ].join("\n")
   };
 };
@@ -724,19 +735,26 @@ var stopHookSettings = (command) => ({
 
 // src/budget.ts
 var DEADLINE_ENV = "CODE_REVIEW_DEADLINE_EPOCH";
-var DEFAULT_RESERVE = { frac: 0.15, flatUsd: 0.02, flatMs: 12e4 };
+var DEFAULT_RESERVE = {
+  frac: 0.15,
+  growth: 0.25,
+  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);
+var axisSeverity = (a, reserve) => {
+  const usedFrac = Math.min(1, Math.max(0, a.used / a.limit));
+  const effFrac = reserve.frac + reserve.growth * usedFrac;
+  const hardReserve = Math.max(a.flat, effFrac * 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);
+  const worst = [costAxis(i), timeAxis(i)].filter((a) => a !== null).reduce((max, a) => Math.max(max, axisSeverity(a, i.reserve)), 0);
   return worst === 2 ? { kind: "hard" } : worst === 1 ? { kind: "soft" } : { kind: "ok" };
 };
 var pct = (n) => `${String(Math.round(n * 100))}%`;
@@ -744,7 +762,7 @@ 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 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} --explain\` until it passes (--explain prints the exact schema when the shape is wrong). Other tools are blocked until that draft is written.` : `Wind down investigation and write your COMPLETE findings to ${draftPath} now, then run \`code-review validate ${draftPath} --explain\` (it prints the exact schema if the shape is wrong) \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)}`;
@@ -838,6 +856,7 @@ var budgetHookCommand = (draftPath, opts) => [
   ...opts.wall ? ["--wall", shellQuote(opts.wall)] : [],
   ...opts.prices ? ["--prices", shellQuote(opts.prices)] : [],
   ...opts.reserveFrac ? ["--reserve-frac", shellQuote(opts.reserveFrac)] : [],
+  ...opts.reserveGrowth ? ["--reserve-growth", shellQuote(opts.reserveGrowth)] : [],
   ...opts.reserveUsd ? ["--reserve-usd", shellQuote(opts.reserveUsd)] : [],
   ...opts.reserveWall ? ["--reserve-wall", shellQuote(opts.reserveWall)] : []
 ].join(" ");
@@ -1081,25 +1100,50 @@ var parseHtmlUrl = (raw) => {
     return void 0;
   }
 };
-var postInlineReview = async (repo, prNumber, headSha, comments, stickyUrl, marker, ghApi) => {
+var commentPayload = (c) => ({
+  path: c.path,
+  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: formatMarkdown(c.body)
+});
+var postInlineReview = async (repo, prNumber, headSha, comments, inDiff, stickyUrl, marker, ghApi) => {
   const pointer = reviewBodyPointer(headSha, stickyUrl, marker);
-  const body = JSON.stringify({
+  const reviewBody = (withComments) => JSON.stringify({
     body: pointer,
     commit_id: headSha,
     event: "COMMENT",
-    comments: comments.map((c) => ({
-      path: c.path,
-      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: formatMarkdown(c.body)
-    }))
+    comments: withComments ? comments.map(commentPayload) : []
   });
-  const stdout = await ghApi(
-    [`repos/${repo}/pulls/${String(prNumber)}/reviews`, "--input", "-"],
-    body
-  );
-  return parseHtmlUrl(stdout);
+  const reviewsEndpoint = [`repos/${repo}/pulls/${String(prNumber)}/reviews`, "--input", "-"];
+  try {
+    const stdout = await ghApi(reviewsEndpoint, reviewBody(true));
+    return { url: parseHtmlUrl(stdout), inlinePosted: comments.length, unposted: [] };
+  } catch (err) {
+    if (comments.length === 0) throw err;
+    process.stderr.write(
+      `Warning: the batched inline review on PR #${String(prNumber)} was rejected (${err instanceof Error ? err.message : String(err)}) \u2014 posting the review body-only, then each comment individually to keep the ones GitHub accepts (issue #57)
+`
+    );
+    const url = parseHtmlUrl(await ghApi(reviewsEndpoint, reviewBody(false)));
+    const commentsEndpoint = [`repos/${repo}/pulls/${String(prNumber)}/comments`, "--input", "-"];
+    const unposted = [];
+    let inlinePosted = 0;
+    for (const [i, c] of comments.entries()) {
+      try {
+        await ghApi(commentsEndpoint, JSON.stringify({ commit_id: headSha, ...commentPayload(c) }));
+        inlinePosted += 1;
+      } catch (e) {
+        const finding = inDiff[i];
+        if (finding) unposted.push(finding);
+        process.stderr.write(
+          `Warning: inline comment on ${c.path}:${String(c.line)} rejected (${e instanceof Error ? e.message : String(e)}) \u2014 surfacing that finding in the sticky instead (issue #57)
+`
+        );
+      }
+    }
+    return { url, inlinePosted, unposted };
+  }
 };
 var findBotComment = async (repo, prNumber, botLogin, marker, ghApi) => {
   const stdout = await ghApi(
@@ -1166,10 +1210,7 @@ var fetchBotReviews = async (repo, prNumber, botLogin, ghApi) => {
     return [];
   }
   if (!Array.isArray(reviews)) return [];
-  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 : ""
-  }));
+  return reviews.filter(isBotReview).filter((r) => r.user.login === botLogin && r.state !== "DISMISSED").map((r) => ({ id: r.id }));
 };
 var dismissReviews = async (repo, prNumber, ids, ghApi) => {
   for (const id of ids) {
@@ -1192,16 +1233,15 @@ var dismissReviews = async (repo, prNumber, ids, 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 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}}}}}}}}";
 var MINIMIZE_COMMENT_MUTATION = "mutation($id:ID!){minimizeComment(input:{subjectId:$id,classifier:OUTDATED}){minimizedComment{isMinimized}}}";
-var supersededCommentId = (c, headSha, logins) => {
+var priorBotCommentId = (c, 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;
+  return typeof o.id === "string" && o.isMinimized !== true && typeof login === "string" && logins.includes(login) ? o.id : null;
 };
-var supersededBotCommentIds = (raw, headSha, botLogin) => {
+var priorBotCommentIds = (raw, botLogin) => {
   let parsed;
   try {
     parsed = JSON.parse(raw);
@@ -1215,13 +1255,13 @@ var supersededBotCommentIds = (raw, headSha, botLogin) => {
   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 Array.isArray(cnodes) ? cnodes.map((c) => priorBotCommentId(c, logins)).filter((id) => id !== null) : [];
   });
   return { ids, truncated };
 };
-var minimizeSupersededComments = async (repo, prNumber, headSha, botLogin, ghApi) => {
+var listPriorBotCommentIds = async (repo, prNumber, botLogin, ghApi) => {
   const slash = repo.indexOf("/");
-  if (slash <= 0) return;
+  if (slash <= 0) return [];
   const owner = repo.slice(0, slash);
   const name = repo.slice(slash + 1);
   let raw;
@@ -1242,15 +1282,18 @@ var minimizeSupersededComments = async (repo, prNumber, headSha, botLogin, ghApi
       `Warning: could not list review threads to minimize stale comments on PR #${String(prNumber)}: ${err instanceof Error ? err.message : String(err)}
 `
     );
-    return;
+    return [];
   }
-  const { ids, truncated } = supersededBotCommentIds(raw, headSha, botLogin);
+  const { ids, truncated } = priorBotCommentIds(raw, 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
 `
     );
   }
+  return ids;
+};
+var minimizeComments = async (prNumber, ids, ghApi) => {
   let minimized = 0;
   for (const id of ids) {
     try {
@@ -1365,7 +1408,11 @@ var post = async (input, ghApi = runGhApi) => {
     process.exit(0);
   }
   const findingsMarker = findingsPointer(findings, input.jsonUrl);
-  const { comments: rawComments, strays } = buildInlineComments(findings.findings, diff, {
+  const {
+    comments: rawComments,
+    strays,
+    inDiff
+  } = buildInlineComments(findings.findings, diff, {
     inlineTemplate,
     models: envelope.models.map((m) => m.model),
     findings,
@@ -1379,8 +1426,7 @@ var post = async (input, ghApi = runGhApi) => {
     );
   }
   const botReviews = 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 initialDisposition = comments.length === 0 && strays.length > 0 ? { kind: "none-in-diff" } : void 0;
   const commonRenderInput = {
     findings,
     envelope,
@@ -1404,7 +1450,15 @@ var post = async (input, ghApi = runGhApi) => {
 
 > **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 renderBody = (inlineDisposition, reviewUrl2, straysOverride, unanchoredCount2) => formatMarkdown(
+    render({
+      ...commonRenderInput,
+      ...straysOverride ? { strays: straysOverride } : {},
+      ...unanchoredCount2 !== void 0 ? { unanchoredCount: unanchoredCount2 } : {},
+      inlineDisposition,
+      reviewUrl: reviewUrl2
+    }) + longFilesNote
+  );
   const stickyRef = await upsertSticky(
     input.repo,
     prNumber,
@@ -1412,49 +1466,53 @@ var post = async (input, ghApi = runGhApi) => {
     renderBody(initialDisposition),
     ghApi
   );
-  if (alreadyReviewedThisSha) {
-    process.stderr.write(
-      `A completed bot review already exists for ${input.headSha} \u2014 updated sticky only, no new review
-`
-    );
-    return;
-  }
-  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(
+  const priorInlineComments = await listPriorBotCommentIds(
+    input.repo,
+    prNumber,
+    input.botLogin,
+    ghApi
+  );
+  const {
+    url: reviewUrl,
+    inlinePosted,
+    unposted
+  } = await postInlineReview(
     input.repo,
     prNumber,
     input.headSha,
     comments,
+    inDiff,
     stickyRef?.url,
     findingsMarker,
     ghApi
   );
   process.stderr.write(
-    `Posted a review with ${String(comments.length)} inline comment(s) on PR #${String(prNumber)}
+    `Posted a review with ${String(inlinePosted)} inline comment(s) on PR #${String(prNumber)}
 `
   );
-  await minimizeSupersededComments(input.repo, prNumber, input.headSha, input.botLogin, ghApi);
-  if (comments.length > 0 && stickyRef !== null) {
-    const confirmedDisposition = {
-      kind: "posted",
-      count: comments.length,
-      sha: input.headSha
-    };
+  const priorReviewIds = botReviews.map((r) => r.id);
+  if (priorReviewIds.length > 0) {
+    await dismissReviews(input.repo, prNumber, priorReviewIds, ghApi);
+  }
+  await minimizeComments(prNumber, priorInlineComments, ghApi);
+  const unanchoredCount = unposted.length;
+  const finalStrays = unanchoredCount > 0 ? [...unposted, ...strays] : strays;
+  if (stickyRef !== null && (inlinePosted > 0 || unanchoredCount > 0)) {
+    const finalDisposition = inlinePosted > 0 ? { kind: "posted", count: inlinePosted, sha: input.headSha } : { kind: "inline-unavailable" };
     try {
       await patchComment(
         input.repo,
         stickyRef.id,
-        renderBody(confirmedDisposition, reviewUrl),
+        renderBody(finalDisposition, reviewUrl, finalStrays, unanchoredCount),
         ghApi
       );
-      process.stderr.write(`Linked sticky comment #${String(stickyRef.id)} to the review
-`);
+      process.stderr.write(
+        `Updated sticky comment #${String(stickyRef.id)} to reflect the review
+`
+      );
     } catch (err) {
       process.stderr.write(
-        `Warning: failed to link the sticky summary to the review: ${err instanceof Error ? err.message : String(err)}
+        `Warning: failed to update the sticky summary after the review: ${err instanceof Error ? err.message : String(err)}
 `
       );
     }
@@ -1792,18 +1850,18 @@ var withMeta = (base, meta) => ({
   ...meta.effort ? { effort: meta.effort } : {}
 });
 var resolveTelemetry = (native, meta) => {
-  const fb = native.models.length === 0 ? meta.transcriptFallback?.() : void 0;
-  const useFallback = fb !== void 0 && fb.models.length > 0;
+  const fb = (() => {
+    try {
+      return meta.transcriptFallback?.();
+    } catch {
+      return void 0;
+    }
+  })();
+  const wallTurns = fb !== void 0 && fb.durationMs > 0 ? { turns: fb.turns, duration_ms: fb.durationMs } : { turns: native.turns, duration_ms: native.durationMs };
   return withMeta(
-    useFallback ? {
-      models: [...fb.models],
-      turns: fb.turns,
-      duration_ms: fb.durationMs,
-      vendor_cost_usd: native.vendorCostUsd
-    } : {
-      models: native.models,
-      turns: native.turns,
-      duration_ms: native.durationMs,
+    {
+      models: native.models.length > 0 ? native.models : fb ? [...fb.models] : native.models,
+      ...wallTurns,
       vendor_cost_usd: native.vendorCostUsd
     },
     meta
@@ -2171,7 +2229,11 @@ var budgetHookCmd = defineCommand({
     },
     "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)"
+      description: "Base 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-growth": {
+      type: "string",
+      description: "How much the reserve grows as a budget is spent \u2014 added at full usage, so convergence lands earlier the longer the run has gone (default: 0.25; 0 = flat reserve)"
     },
     "reserve-usd": {
       type: "string",
@@ -2204,6 +2266,7 @@ var budgetHookCmd = defineCommand({
         wallMs,
         reserve: {
           frac: parseFraction(args["reserve-frac"], DEFAULT_RESERVE.frac),
+          growth: parseFraction(args["reserve-growth"], DEFAULT_RESERVE.growth),
           flatUsd: parseBudgetUsd(args["reserve-usd"]) ?? DEFAULT_RESERVE.flatUsd,
           flatMs: args["reserve-wall"] ? parseWallMs(args["reserve-wall"]) ?? DEFAULT_RESERVE.flatMs : DEFAULT_RESERVE.flatMs
         },
@@ -2265,7 +2328,11 @@ var printSettingsCmd = defineCommand({
     },
     "reserve-frac": {
       type: "string",
-      description: "Wind-down headroom as a fraction of each budget (default: 0.15; soft tier is 2\xD7)"
+      description: "Base wind-down headroom as a fraction of each budget (default: 0.15; soft tier is 2\xD7)"
+    },
+    "reserve-growth": {
+      type: "string",
+      description: "How much the reserve grows as a budget is spent, converging earlier the longer the run has gone (default: 0.25; 0 = flat)"
     },
     "reserve-usd": {
       type: "string",
@@ -2293,6 +2360,7 @@ var printSettingsCmd = defineCommand({
         wall: args.wall,
         prices: args.prices,
         reserveFrac: args["reserve-frac"],
+        reserveGrowth: args["reserve-growth"],
         reserveUsd: args["reserve-usd"],
         reserveWall: args["reserve-wall"]
       }
@@ -2324,6 +2392,13 @@ var deadlineCmd = defineCommand({
   }
 });
 var derivedSchemaVersion = (kind, raw) => kind === "findings" ? declaredVersion(raw) : void 0;
+var printableSchema = (schemaPath) => {
+  const schema = JSON.parse(readFileSync(schemaPath, "utf-8"));
+  const enforcementSchema = Object.fromEntries(
+    Object.entries(schema).filter(([key2]) => key2 !== "$schema")
+  );
+  return JSON.stringify(enforcementSchema, null, 2);
+};
 var validateCmd = defineCommand({
   meta: {
     name: "validate",
@@ -2346,6 +2421,10 @@ var validateCmd = defineCommand({
     "schema-version": {
       type: "string",
       description: "Schema major.minor version to validate against (default: the document's declared schema_version for findings, or the kind's latest)"
+    },
+    explain: {
+      type: "boolean",
+      description: "On failure, also print the schema after the errors \u2014 its field descriptions are the authoritative spec, so the document can be fixed in one pass instead of by trial and error"
     }
   },
   run: async ({ args }) => {
@@ -2359,10 +2438,117 @@ var validateCmd = defineCommand({
       process.stderr.write("\u274C invalid\n");
       for (const e of errors) process.stderr.write(`  - ${e}
 `);
+      if (args.explain) {
+        process.stderr.write(
+          `
+The ${kind} document must conform to this schema (the field descriptions are the authoritative spec \u2014 match the property names exactly):
+${printableSchema(schemaPath)}
+`
+        );
+      }
       process.exit(1);
     }
   }
 });
+var seedDraftCmd = defineCommand({
+  meta: {
+    name: "seed-draft",
+    description: "Write a valid findings $DRAFT before the review runs: the decoded findings from a prior review when one exists and still validates (incremental re-review), else an empty-but-valid scaffold \u2014 so a valid draft exists from turn 0 (issues #52, #53). Prints the mode chosen (prior|empty|none \u2014 none when even the scaffold write failed) to stdout; 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"
+    },
+    out: {
+      type: "string",
+      description: "Path to write the seed $DRAFT to (an absolute path outside the worktree)",
+      required: true
+    },
+    kind: {
+      type: "string",
+      description: "Schema kind to validate the prior findings against (default: findings)"
+    },
+    schema: {
+      type: "string",
+      description: "Path to a schema file (wins over --kind/--schema-version)"
+    },
+    "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)"
+    }
+  },
+  run: async ({ args }) => {
+    const outPath = resolve$1(args.out);
+    const kindArg = args.kind || "findings";
+    const kind = isSchemaKind(kindArg) ? kindArg : "findings";
+    if (kind !== kindArg) {
+      process.stderr.write(
+        `Warning: unknown --kind "${kindArg}" \u2014 validating against "findings"
+`
+      );
+    }
+    const writeEmptyScaffold = () => {
+      try {
+        writeFileSync(outPath, `${JSON.stringify(noticeFindings(""), null, 2)}
+`);
+        process.stderr.write(
+          `Seeded ${outPath} with an empty valid scaffold \u2014 no decodable prior findings to build on
+`
+        );
+        process.stdout.write("empty\n");
+      } catch (err) {
+        process.stderr.write(
+          `Warning: could not write the seed scaffold to ${outPath} (${err instanceof Error ? err.message : String(err)}) \u2014 the agent will create $DRAFT itself
+`
+        );
+        process.stdout.write("none\n");
+      }
+    };
+    const priorFindings = (() => {
+      if (!args.prior) return null;
+      const raw = (() => {
+        try {
+          return JSON.parse(readFileSync(resolve$1(args.prior), "utf-8"));
+        } catch {
+          return null;
+        }
+      })();
+      const body = typeof raw === "object" && raw !== null && "body" in raw && typeof raw.body === "string" ? raw.body : null;
+      return body === null ? null : parseFindingsMarker(body);
+    })();
+    if (priorFindings === null) {
+      writeEmptyScaffold();
+      return;
+    }
+    const seededFromPrior = (() => {
+      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)}
+`);
+        return true;
+      } catch (err) {
+        process.stderr.write(
+          `Warning: could not seed from the prior review (${err instanceof Error ? err.message : String(err)}) \u2014 falling back to the empty scaffold
+`
+        );
+        return false;
+      }
+    })();
+    if (seededFromPrior) {
+      const priorList = priorFindings.findings;
+      const count = Array.isArray(priorList) ? priorList.length : 0;
+      process.stderr.write(
+        `Seeded ${outPath} from the prior review (${String(count)} finding(s)) \u2014 verify each still holds against the current diff and refine in place
+`
+      );
+      process.stdout.write("prior\n");
+    } else {
+      writeEmptyScaffold();
+    }
+  }
+});
 var adaptCmd = defineCommand({
   meta: {
     name: "adapt",
@@ -2393,7 +2579,7 @@ var adaptCmd = defineCommand({
     },
     transcript: {
       type: "string",
-      description: "Path to the session transcript (the main .jsonl); when the native envelope carries no per-model usage \u2014 a wall-clock kill leaves it empty (issue #39) \u2014 telemetry is recovered from the transcript tree (main + subagents) so cost is real, not $0.00 (issue #36)"
+      description: "Path to the session transcript (the main .jsonl). Its tree (main + subagents) is the source of the true wall + turn count \u2014 the native envelope only sees the main agent and under-reports a fan-out (issue #59) \u2014 and refills per-model usage too when the native has none (a wall-clock kill leaves it empty, so cost is real not $0.00 \u2014 issues #39/#36)"
     }
   },
   run: async ({ args }) => {
@@ -2571,11 +2757,7 @@ var printSchemaCmd = defineCommand({
   run: async ({ args }) => {
     const schemaKind = requireSchemaKind(args.name);
     const schemaPath = requireSchemaPath(schemaKind, args["schema-version"]);
-    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)}
+    process.stdout.write(`${printableSchema(schemaPath)}
 `);
   }
 });
@@ -2811,7 +2993,7 @@ var main = defineCommand({
   meta: {
     name: "code-review",
     version: packageVersion,
-    description: "Deterministic commenter for agentic PR review \u2014 gather, render, inline, post, adapt, extract, validate-patches, cost, check-cost, validate, stop-gate, budget-hook, print-settings, and deadline"
+    description: "Deterministic commenter for agentic PR review \u2014 gather, render, inline, post, adapt, extract, validate-patches, cost, check-cost, validate, seed-draft, stop-gate, budget-hook, print-settings, and deadline"
   },
   subCommands: {
     gather: gatherCmd,
@@ -2821,6 +3003,7 @@ var main = defineCommand({
     cost: costCmd,
     "check-cost": checkCostCmd,
     validate: validateCmd,
+    "seed-draft": seedDraftCmd,
     adapt: adaptCmd,
     extract: extractCmd,
     "validate-patches": validatePatchesCmd,