@tokenfactory/acc-runner 0.43.0 → 0.44.1

package/dist/runtime/reviewer.js

@@ -24,6 +24,10 @@ import { prepareReviewWorktree, ReviewFetchError } from "./worktree.js";
 import { isEmptyReviewDiff } from "../review-diff-guard.js";
 import { diffFilePaths, splitDiffByFile } from "./review-diff.js";
 import { planReviewChunks, partitionAbsenceClaims, MAX_REVIEW_CHUNKS, REVIEWER_ABSENCE_ESCALATION_REASON, DISCARDED_CLAIM_PREFIX, } from "./review-chunking.js";
+import { decisionProvenanceReason, reconcileReviewDecision, PROSE_KEYWORD_OVERRIDE_REASON, } from "./decision-provenance.js";
+import { describePromptRenderBleed, findPromptRenderBleed, substitutePlaceholders, } from "./prompt-substitute.js";
+import { abstainReasons, describeAbstainForLog, } from "./reviewer-abstain.js";
+import { chargeReviewAttempt, classifyReviewCost, openReviewCostContext, reviewCostLedger, reviewCostOverrunReason, reviewCostRunawayReason, } from "./review-cost-cap.js";
 import { classifyTeardownFailure } from "../review-worktree-cleanup.js";
 // Byte-identical to prompts/reviewer-agent.md. The runner does not have
 // the markdown file at runtime (the package ships without prompts/) so
@@ -516,7 +520,7 @@ export function isRetriableError(stderr) {
 function defaultSleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
-export function renderReviewerPrompt(args) {
+export function renderReviewerPromptChecked(args) {
     // RF-3: ONE truncation policy — float the AC-named proof files to the front,
     // cut at a whole-file boundary, and name what was withheld. Under the cap
     // nothing reorders and no notice renders, so the prompt is byte-identical to
@@ -538,14 +542,41 @@ export function renderReviewerPrompt(args) {
     const acceptance = (args.acceptance_criteria ?? [])
         .map((a, i) => `${i + 1}. ${a}`)
         .join("\n");
-    const rendered = REVIEWER_PROMPT_TEMPLATE
-        .replace("{{task_description}}", args.task_description ?? "")
-        .replace("{{acceptance_criteria}}", acceptance)
-        .replace("{{pr_title}}", args.pr_title ?? "")
-        .replace("{{pr_body}}", args.pr_body ?? "")
-        .replace("{{pr_diff}}", diff);
+    // S15-FU/REVIEW-1 (AC1): substitute VERBATIM. `String.replace` with a string
+    // replacement expands `$$`/`$&`/`` $` ``/`$'`/`$n`, so a diff containing `$'`
+    // — e.g. the clean literal `... where seq ~ '^[0-9]+$' order by 1` — used to
+    // splice the template text FOLLOWING `{{pr_diff}}` ("Now answer in this exact
+    // JSON shape…") into the diff, and the reviewer then reported that prose as a
+    // corruption defect in the file (#1933). Never re-introduce a string
+    // replacement here; see ./prompt-substitute.ts.
+    const pairs = reviewerPlaceholderPairs(args, diff, acceptance);
+    const rendered = substitutePlaceholders(REVIEWER_PROMPT_TEMPLATE, pairs);
     const note = truncationInfraNote(omitted, partialFile, prioritized.reordered);
-    return note.length > 0 ? `${rendered}\n\n${note}\n` : rendered;
+    const prompt = note.length > 0 ? `${rendered}\n\n${note}\n` : rendered;
+    return { prompt, bleed: findPromptRenderBleed(REVIEWER_PROMPT_TEMPLATE, prompt, pairs) };
+}
+/**
+ * S15-FU/REVIEW-1 (AC1): the ORDERED placeholder/value pairs a reviewer prompt
+ * substitutes, so the render-integrity check (and its test) can assert that every
+ * one of these values survived into the prompt VERBATIM.
+ * // keep in sync with reviewerPlaceholderPairs in api/_lib/reviewer-agent.ts
+ */
+export function reviewerPlaceholderPairs(args, diff, acceptance) {
+    return [
+        ["{{task_description}}", args.task_description ?? ""],
+        ["{{acceptance_criteria}}", acceptance],
+        ["{{pr_title}}", args.pr_title ?? ""],
+        ["{{pr_body}}", args.pr_body ?? ""],
+        ["{{pr_diff}}", diff],
+    ];
+}
+/**
+ * String façade over `renderReviewerPromptChecked` — the signature every existing
+ * caller and the RF-3 parity tests use. Integrity is enforced at the review seam,
+ * which needs the `bleed` list to build its abstain.
+ */
+export function renderReviewerPrompt(args) {
+    return renderReviewerPromptChecked(args).prompt;
 }
 /* ─────────── REVIEWER-DIFF-CAP: chunked review of an over-cap diff ───────────
  *
@@ -740,7 +771,18 @@ export function extractReviewerDecision(text) {
             "parsed from prose reviewer output (no JSON found)",
             `decision_keyword: ${decision}`,
         ];
-    return { decision, reasons, confidence };
+    // REVIEW-DECISION-PROVENANCE: this verdict was INFERRED from a keyword, not
+    // asserted. PR #1913 persisted a reject this way over an all-"Met." analysis
+    // with no trace of the inference; runReview stamps the marker at submit time.
+    return {
+        decision,
+        reasons,
+        confidence,
+        decision_provenance: {
+            decision_source: "prose_keyword",
+            override_reason: PROSE_KEYWORD_OVERRIDE_REASON,
+        },
+    };
 }
 async function defaultFetchPRMeta(repo, prNumber) {
     const { stdout } = await execa("gh", ["pr", "view", String(prNumber), "-R", repo, "--json", "title,body"], { env: buildEnv() });
@@ -877,16 +919,22 @@ async function cleanupReviewTree(tree, supabase, assignment) {
         await emitReviewWorktreeOrphaned(supabase, assignment, tree.path ?? "", result);
     }
 }
-// M2 (ENGINE-EXTRACT): the coding engine the reviewer drives — the default
-// `claude-code` engine. spawn/argv/result-parse/failure-class behavior is
-// byte-identical to the pre-refactor inline logic now owned by
-// src/engines/claude-code.ts. buildEnv() is the reviewer's base env (mirrors
-// v0.74-B): the engine forwards ANTHROPIC_API_KEY over it when set.
-const engine = getEngine();
-function defaultSpawnClaude(modelId) {
+// M2 (ENGINE-EXTRACT): the coding engine the reviewer drives. Wave 1 fixed
+// this to a single module-level `claude-code` constant — spawn/argv/result-
+// parse/failure-class behavior was byte-identical to the pre-refactor inline
+// logic now owned by src/engines/claude-code.ts. buildEnv() is the reviewer's
+// base env (mirrors v0.74-B): the engine forwards ANTHROPIC_API_KEY over it
+// when set.
+//
+// NS MM-2 (BATCH-ENGINE-DISPATCH): the reviewer now resolves the engine PER
+// REVIEW from the reviewed task's `engine` column (`driveReview` below), so it
+// drives the same CLI the runner built the PR with instead of always assuming
+// claude-code. `getEngine(id)` defaults to claude-code on a null/blank id —
+// unstamped/pre-MM-1 rows are byte-identical to Wave 1.
+function defaultSpawnClaude(modelId, engine) {
     return engine.spawn({ modelId, baseEnv: buildEnv() });
 }
-function parseEnvelope(stdout, fallbackModel) {
+function parseEnvelope(stdout, fallbackModel, engine) {
     const parsed = engine.parseResult(stdout);
     if (!parsed) {
         return { result: stdout.trim(), session_id: null, cost_usd: 0, model: fallbackModel };
@@ -914,10 +962,12 @@ function parseEnvelope(stdout, fallbackModel) {
 export async function runReview(assignment, deps) {
     const fetchMeta = deps.fetchPRMeta ?? defaultFetchPRMeta;
     const prepareTree = deps.prepareReviewTree ?? defaultPrepareReviewTree;
-    const spawnFn = deps.spawnClaude ?? defaultSpawnClaude;
+    // NS MM-2: `spawnFn`'s default needs the REVIEWED task's `engine` column,
+    // which driveReview fetches — so its binding moves there instead of here.
+    // `deps.spawnClaude` (test override) is unaffected either way.
     let outcome;
     try {
-        outcome = await driveReview(assignment, deps, fetchMeta, prepareTree, spawnFn);
+        outcome = await driveReview(assignment, deps, fetchMeta, prepareTree);
     }
     catch (err) {
         // V96 (ADDED SCOPE): a worktree teardown crash that escaped driveReview
@@ -951,18 +1001,34 @@ export async function runReview(assignment, deps) {
             cost_usd: 0,
         };
     }
+    // REVIEW-DECISION-PROVENANCE — the persistence seam. Two stamps, both purely
+    // additive to `reasons` and neither touching the verdict:
+    //   1. a SYNTHESIZED decision (prose fallback) renders its marker, so a
+    //      keyword-inferred verdict is never stored as if the analysis argued it;
+    //   2. reconcile catches a reject whose own reasons record a clean full pass
+    //      and no override rationale (the PR #1913 shape) and flags it.
+    // Applied here, immediately before the RPC, so EVERY path that reaches
+    // submit_review — chunked, single-pass, capacity fallback — is covered.
+    const provenanceNote = outcome.decision_provenance
+        ? [decisionProvenanceReason(outcome.decision_provenance)]
+        : [];
+    const reconciled = reconcileReviewDecision({
+        decision: outcome.decision,
+        reasons: [...outcome.reasons, ...provenanceNote],
+    });
+    const submitted = { ...outcome, reasons: reconciled.reasons };
     const { error } = await deps.supabase.rpc("submit_review", {
         p_review_id: assignment.review_id,
-        p_decision: outcome.decision,
-        p_reasons: outcome.reasons,
-        p_confidence: outcome.confidence,
-        p_session_id: outcome.session_id,
-        p_cost_usd: outcome.cost_usd,
+        p_decision: submitted.decision,
+        p_reasons: submitted.reasons,
+        p_confidence: submitted.confidence,
+        p_session_id: submitted.session_id,
+        p_cost_usd: submitted.cost_usd,
     });
     if (error) {
         process.stderr.write(`[acc-runner] submit_review(${assignment.review_id}) failed: ${error.message}\n`);
     }
-    return outcome;
+    return submitted;
 }
 async function invokeClaude(spawnFn, modelId, prompt) {
     const spawnedAt = Date.now();
@@ -978,7 +1044,7 @@ async function invokeClaude(spawnFn, modelId, prompt) {
     ]);
     return { stdout, stderr, exitCode: exit.exitCode ?? 1, durationMs: Date.now() - spawnedAt };
 }
-async function driveReview(assignment, deps, fetchMeta, prepareTree, spawnFn) {
+async function driveReview(assignment, deps, fetchMeta, prepareTree) {
     const { data, error } = await deps.supabase.rpc("fetch_task_for_runner", {
         p_task_id: assignment.task_id,
     });
@@ -1003,6 +1069,12 @@ async function driveReview(assignment, deps, fetchMeta, prepareTree, spawnFn) {
             cost_usd: 0,
         };
     }
+    // NS MM-2 (BATCH-ENGINE-DISPATCH): resolve the reviewed task's engine ONCE,
+    // right after the task itself is known — mirrors task-runner.ts's
+    // per-task resolution. `getEngine(null)` (an unstamped/pre-MM-1 row)
+    // resolves the same claude-code default Wave 1 always used.
+    const engine = getEngine(task.engine ?? null);
+    const spawnFn = deps.spawnClaude ?? ((modelId) => defaultSpawnClaude(modelId, engine));
     // Look up the org's reviewer policy. The runner-side reviewer needs
     // confidence_threshold + max_cost_usd_per_review to stay consistent
     // with the cron-side gate, since the cron now just lifts the decision
@@ -1075,7 +1147,7 @@ async function driveReview(assignment, deps, fetchMeta, prepareTree, spawnFn) {
             pr_title: meta.title,
             pr_body: meta.body,
             pr_diff: tree.diff,
-        }, policy, deps, spawnFn);
+        }, policy, deps, spawnFn, engine);
     }
     finally {
         // Remove the dedicated review worktree so it can never become a stale
@@ -1096,10 +1168,35 @@ async function driveReview(assignment, deps, fetchMeta, prepareTree, spawnFn) {
  * Past `MAX_REVIEW_CHUNKS` even chunking is not a sane spend, so the review
  * settles as an INFRA outcome the escalation path owns — never a reject.
  */
-async function produceVerdict(input, policy, deps, spawnFn) {
+async function produceVerdict(input, policy, deps, spawnFn, engine) {
+    // REV-COST: ONE cost context per review — the SIZE-SCALED cap plus the
+    // attempt ledger every pass charges into. Derived from the ASSEMBLED diff this
+    // function already holds, so no caller has to change. At or under
+    // REVIEW_CAP_REFERENCE_DIFF_CHARS the cap is EXACTLY the org's flat
+    // `max_cost_usd_per_review` (an ordinary PR is judged against today's number);
+    // above it the cap ramps, bounded by REVIEW_CAP_MAX_MULTIPLE.
+    const costCtx = openReviewCostContext(policy?.max_cost_usd_per_review ?? 0, input.pr_diff.length);
     const chunks = planReviewChunks(input.pr_diff, MAX_DIFF_CHARS);
     if (chunks.length <= 1) {
-        return runClaudeAndDecide(renderReviewerPrompt(input), policy, deps, spawnFn);
+        // S15-FU/REVIEW-1 (AC1 + AC2): render, then PROVE the prompt carries the PR
+        // content verbatim. If any value did not survive substitution, the reviewer
+        // would be judging text the repo does not contain (the #1933 corruption
+        // class) — so ABSTAIN before spawning anything. Never a reject, never a cost.
+        const render = renderReviewerPromptChecked(input);
+        if (render.bleed.length > 0) {
+            const detail = describePromptRenderBleed(render.bleed);
+            process.stderr.write(describeAbstainForLog("prompt_render", detail));
+            return {
+                decision: "reviewer_error",
+                reasons: abstainReasons("prompt_render", [
+                    `rendered reviewer prompt did not carry PR content verbatim: ${detail}`,
+                ]),
+                confidence: 0,
+                session_id: null,
+                cost_usd: 0,
+            };
+        }
+        return stampReviewCost(await runClaudeAndDecide(render.prompt, policy, deps, spawnFn, engine, costCtx), costCtx);
     }
     if (chunks.length > MAX_REVIEW_CHUNKS) {
         return {
@@ -1116,7 +1213,7 @@ async function produceVerdict(input, policy, deps, spawnFn) {
             cost_usd: 0,
         };
     }
-    return runChunkedReview(input, chunks, policy, deps, spawnFn);
+    return runChunkedReview(input, chunks, policy, deps, spawnFn, engine, costCtx);
 }
 /**
  * REVIEWER-DIFF-CAP — read an over-cap diff in `chunks.length` part passes, then
@@ -1129,13 +1226,13 @@ async function produceVerdict(input, policy, deps, spawnFn) {
  * env-broken — short-circuits the whole review with the spend accumulated so far,
  * so an infra fault never degrades into a partial-evidence verdict.
  */
-async function runChunkedReview(input, chunks, policy, deps, spawnFn) {
-    // The cap is checked ONCE against the whole chunked spend below; per-pass it is
-    // disabled so a single part is never judged against the whole-review budget.
-    const passPolicy = policy ? { ...policy, max_cost_usd_per_review: 0 } : null;
-    const cap = policy?.max_cost_usd_per_review ?? 0;
+async function runChunkedReview(input, chunks, policy, deps, spawnFn, engine, costCtx) {
+    // REV-COST: the cap is judged ONCE against the WHOLE chunked spend, because
+    // the shared ledger in `costCtx` accumulates across every part pass. That
+    // replaces the old cap-0 `passPolicy` clone: a single part is still never
+    // judged against the whole-review budget, and the whole review is no longer
+    // judged against a FLAT cap.
     const passes = [];
-    let cost = 0;
     let degraded = false;
     let modelUsed;
     for (const chunk of chunks) {
@@ -1143,53 +1240,80 @@ async function runChunkedReview(input, chunks, policy, deps, spawnFn) {
         // a probe for every chunk. Only the first pass carries it.
         const passDeps = chunk.index === 1 ? deps : { ...deps, authCanary: undefined };
         const prompt = `${renderReviewerPrompt({ ...input, pr_diff: chunk.text })}\n\n${chunkScopeNotice(chunk)}\n`;
-        const out = await runClaudeAndDecide(prompt, passPolicy, passDeps, spawnFn);
-        cost += out.cost_usd;
+        // The RUNAWAY brake lives in finalizeReviewerSuccess, right where the spend
+        // is charged, so a part pass that pushes the WHOLE-review total past the
+        // tolerance short-circuits here as a non-verdict outcome and the remaining
+        // passes never run. An overrun INSIDE the band deliberately does not stop the
+        // review: it finishes and the paid verdict is kept (see the tail).
+        const out = await runClaudeAndDecide(prompt, policy, passDeps, spawnFn, engine, costCtx);
+        const partLedger = reviewCostLedger(costCtx);
         modelUsed = out.model_used ?? modelUsed;
         degraded = degraded || out.capacity_degraded === true;
         if (out.decision !== "approve" && out.decision !== "reject") {
-            return { ...out, cost_usd: cost, capacity_degraded: degraded ? true : out.capacity_degraded };
+            return {
+                ...out,
+                cost_usd: partLedger.total_usd,
+                cost_cap: costCtx.cap,
+                cost_breakdown: partLedger,
+                capacity_degraded: degraded ? true : out.capacity_degraded,
+            };
         }
-        if (cap > 0 && cost > cap)
-            return overChunkedCostCap(cost, cap, modelUsed);
         passes.push({ decision: out.decision, reasons: out.reasons, confidence: out.confidence });
     }
     const allPaths = diffFilePaths(input.pr_diff);
     const evidence = renderSynthesisEvidence(chunks, passes, allPaths);
     const synthPrompt = `${renderReviewerPrompt({ ...input, pr_diff: evidence })}\n\n${synthesisScopeNotice(chunks.length)}\n`;
-    const final = await runClaudeAndDecide(synthPrompt, passPolicy, { ...deps, authCanary: undefined }, spawnFn);
-    cost += final.cost_usd;
+    const final = await runClaudeAndDecide(synthPrompt, policy, { ...deps, authCanary: undefined }, spawnFn, engine, costCtx);
+    const ledger = reviewCostLedger(costCtx);
     modelUsed = final.model_used ?? modelUsed;
     degraded = degraded || final.capacity_degraded === true;
     if (final.decision !== "approve" && final.decision !== "reject") {
-        return { ...final, cost_usd: cost, capacity_degraded: degraded ? true : final.capacity_degraded };
+        return {
+            ...final,
+            cost_usd: ledger.total_usd,
+            cost_cap: costCtx.cap,
+            cost_breakdown: ledger,
+            capacity_degraded: degraded ? true : final.capacity_degraded,
+        };
     }
-    if (cap > 0 && cost > cap)
-        return overChunkedCostCap(cost, cap, modelUsed);
     // Guard FIRST (so a coverage claim can never survive as a verdict), then stamp
     // the coverage telemetry — which must never itself be partitioned as a claim.
     const guarded = guardCoverageClaims({
         ...final,
-        cost_usd: cost,
+        cost_usd: ledger.total_usd,
         model_used: modelUsed,
         capacity_degraded: degraded ? true : undefined,
     });
+    // REV-COST: the overrun note (when the paid spend landed in the tolerance
+    // band) sits between the findings and the coverage telemetry — a real reason,
+    // so it must precede chunkedCoverageReason to keep THAT last.
+    const stamped = stampReviewCost(guarded, costCtx);
     return {
-        ...guarded,
-        reasons: [...guarded.reasons, chunkedCoverageReason(chunks.length, allPaths.length, input.pr_diff.length)],
+        ...stamped,
+        reasons: [...stamped.reasons, chunkedCoverageReason(chunks.length, allPaths.length, input.pr_diff.length)],
     };
 }
-/** Cost-cap parity for the chunked path: the cap applies to the WHOLE review. */
-function overChunkedCostCap(cost, cap, modelUsed) {
+/**
+ * REV-COST — stamp the cost ledger onto a FINISHED review outcome and, when
+ * the chargeable spend landed in the OVERRUN band (over the effective cap, under
+ * the runaway threshold), keep the verdict and add the advisory note.
+ *
+ * Called exactly once per review, after the verdict is assembled — never on a
+ * chunked PART pass, so a budget note can never leak into the synthesis evidence
+ * and be re-read as a finding.
+ */
+function stampReviewCost(out, costCtx) {
+    const ledger = reviewCostLedger(costCtx);
+    const isVerdict = out.decision === "approve" || out.decision === "reject";
+    const overrun = isVerdict && classifyReviewCost(ledger.chargeable_usd, costCtx.cap) === "overrun";
     return {
-        decision: "cost_cap_exceeded",
-        reasons: [
-            `reviewer cost $${cost.toFixed(4)} exceeded cap $${cap.toFixed(2)} across the chunked review`,
-        ],
-        confidence: 0,
-        session_id: null,
-        cost_usd: cost,
-        model_used: modelUsed,
+        ...out,
+        reasons: overrun
+            ? [...out.reasons, reviewCostOverrunReason(costCtx.cap, ledger)]
+            : out.reasons,
+        cost_cap: costCtx.cap,
+        cost_breakdown: ledger,
+        ...(overrun ? { cost_overrun: true } : {}),
     };
 }
 /**
@@ -1200,7 +1324,7 @@ function overChunkedCostCap(cost, cap, modelUsed) {
  * caller (which owns the capacity-fallback re-route). Behaviour of this loop is
  * byte-identical to the pre-RVU-2 inline loop.
  */
-async function invokeReviewerModel(spawnFn, modelId, prompt, sleepFn, maxCapacityRetries) {
+async function invokeReviewerModel(spawnFn, modelId, prompt, sleepFn, maxCapacityRetries, engine) {
     let invokeResult;
     let infraRetries = 0;
     let capacityRetries = 0;
@@ -1247,48 +1371,67 @@ async function invokeReviewerModel(spawnFn, modelId, prompt, sleepFn, maxCapacit
 /** RVU-2: a budget-exempt env-broken (auth) reviewer_error. Decision stays
  *  `reviewer_error` (frozen); the marker reason makes the shared cron treat it
  *  as budget-exempt and alert once. */
-function envBrokenOutcome(modelId, detail) {
+function envBrokenOutcome(modelId, detail, ledger) {
     return {
         decision: "reviewer_error",
         reasons: [REVIEWER_ENV_BROKEN_REASON, `detail: ${(detail ?? "").slice(0, 160)}`],
         confidence: 0,
+        // REV-COST: an auth fault costs nothing and is charged to INFRA, never to
+        // the per-review budget — the review still needs its productive attempt.
+        cost_usd: ledger?.total_usd ?? 0,
         session_id: null,
-        cost_usd: 0,
         model_used: modelId,
         env_broken: true,
+        ...(ledger ? { cost_breakdown: ledger } : {}),
     };
 }
 /** RVU-2: assemble the outcome from a clean (exit 0) reviewer envelope. Cost-cap
- *  parity + parse are unchanged; `degraded` marks a re-routed (lower-tier) run. */
-function finalizeReviewerSuccess(stdout, modelId, degraded, policy) {
-    const envelope = parseEnvelope(stdout, modelId);
-    // Cost cap parity with api/_lib/reviewer-agent.ts. A cap of 0 disables it.
-    if (policy &&
-        policy.max_cost_usd_per_review > 0 &&
-        envelope.cost_usd > policy.max_cost_usd_per_review) {
+ *  parity + parse are unchanged; `degraded` marks a re-routed (lower-tier) run.
+ *  REV-COST: the cap is now the size-scaled decision carried in `costCtx`, and
+ *  only the RUNAWAY band refuses the verdict here. */
+function finalizeReviewerSuccess(stdout, modelId, degraded, costCtx, engine) {
+    const envelope = parseEnvelope(stdout, modelId, engine);
+    // REV-COST: the spawn returned a readable envelope, so this is the review's
+    // PRODUCTIVE attempt — the only class charged to the per-review cap. Parity
+    // with api/_lib/reviewer-agent.ts, which charges at exactly this point.
+    const ledger = chargeReviewAttempt(costCtx, modelId, "productive", envelope.cost_usd);
+    // REV-COST RUNAWAY BACKSTOP. Past `cap × REVIEW_COST_OVERRUN_TOLERANCE`
+    // something is pathological, so the verdict is still refused. Inside the band
+    // the spend is judged AFTER the verdict is assembled (stampReviewCost): the
+    // money is already gone, and discarding a paid verdict only stranded the PR
+    // (#1937 — $18 spent, $8 flat cap, NO verdict) and re-charged the same review
+    // on the next tick. A cap of 0 disables the whole check, as before.
+    if (classifyReviewCost(ledger.chargeable_usd, costCtx.cap) === "runaway") {
         return {
             decision: "cost_cap_exceeded",
-            reasons: [
-                `reviewer cost $${envelope.cost_usd.toFixed(4)} exceeded cap $${policy.max_cost_usd_per_review.toFixed(2)}`,
-            ],
+            reasons: [reviewCostRunawayReason(costCtx.cap, ledger)],
             confidence: 0,
             session_id: envelope.session_id,
-            cost_usd: envelope.cost_usd,
+            cost_usd: ledger.total_usd,
             model_used: modelId,
+            cost_cap: costCtx.cap,
+            cost_breakdown: ledger,
         };
     }
     const decision = extractReviewerDecision(envelope.result);
     if (!decision) {
+        // S15-FU/REVIEW-1 (AC2): a PARSE FAULT is an explicit ABSTAIN. The unparsed
+        // output head is carried as QUARANTINED context (never a finding) so an
+        // operator can diagnose the format drift without any of that text being
+        // scored as a defect.
+        process.stderr.write(describeAbstainForLog("verdict_parse"));
         return {
             decision: "reviewer_error",
-            reasons: [
+            reasons: abstainReasons("verdict_parse", [
                 "could not parse reviewer JSON from claude output",
                 `output_head: ${envelope.result.slice(0, 200)}`,
-            ],
+            ]),
             confidence: 0,
             session_id: envelope.session_id,
-            cost_usd: envelope.cost_usd,
+            cost_usd: ledger.total_usd,
             model_used: modelId,
+            cost_cap: costCtx.cap,
+            cost_breakdown: ledger,
         };
     }
     return {
@@ -1298,6 +1441,11 @@ function finalizeReviewerSuccess(stdout, modelId, degraded, policy) {
         session_id: envelope.session_id,
         cost_usd: envelope.cost_usd,
         model_used: modelId,
+        // REVIEW-DECISION-PROVENANCE: carried as a field (never a reason) so it
+        // survives the coverage/absence guards without being read as a finding.
+        ...(decision.decision_provenance
+            ? { decision_provenance: decision.decision_provenance }
+            : {}),
         // Signal capacity pressure to watch.ts only when the review actually
         // re-routed to a lower tier (leave undefined on the primary-model path).
         capacity_degraded: degraded ? true : undefined,
@@ -1312,7 +1460,7 @@ function finalizeReviewerSuccess(stdout, modelId, degraded, policy) {
  * explicit broken CLI-auth signal surfaces as budget-exempt env_broken rather
  * than looping. Cost-cap / parse behaviour is unchanged.
  */
-async function runClaudeAndDecide(prompt, policy, deps, spawnFn) {
+async function runClaudeAndDecide(prompt, policy, deps, spawnFn, engine, costCtx) {
     const sleepFn = deps.sleep ?? defaultSleep;
     const baseModel = policy?.model_id ?? "claude-sonnet-4-6";
     const maxCapacityRetries = resolveCapacityRetries(process.env[CAPACITY_RETRIES_ENV]);
@@ -1330,7 +1478,7 @@ async function runClaudeAndDecide(prompt, policy, deps, spawnFn) {
             probes = [];
         }
         if (isEnvBrokenReviewerProbe(probes)) {
-            return envBrokenOutcome(primaryModel, "preflight auth canary: repeated silent CLI exit (broken login / rejected key)");
+            return envBrokenOutcome(primaryModel, "preflight auth canary: repeated silent CLI exit (broken login / rejected key)", chargeReviewAttempt(costCtx, primaryModel, "infra_auth", 0));
         }
     }
     let lastCapacityDetail = "reviewer capacity exhausted across all fallback tiers";
@@ -1338,10 +1486,10 @@ async function runClaudeAndDecide(prompt, policy, deps, spawnFn) {
     for (let i = 0; i < chain.length; i++) {
         const modelId = chain[i];
         const isLast = i === chain.length - 1;
-        const invokeResult = await invokeReviewerModel(spawnFn, modelId, prompt, sleepFn, maxCapacityRetries);
+        const invokeResult = await invokeReviewerModel(spawnFn, modelId, prompt, sleepFn, maxCapacityRetries, engine);
         const { stdout, exitCode, stderr: claudeStderr, durationMs } = invokeResult;
         if (exitCode === 0) {
-            return finalizeReviewerSuccess(stdout, modelId, modelId !== primaryModel, policy);
+            return finalizeReviewerSuccess(stdout, modelId, modelId !== primaryModel, costCtx, engine);
         }
         const classified = engine.classifyFailure(exitCode, claudeStderr, stdout, durationMs);
         const combined = `${claudeStderr}\n${stdout}`;
@@ -1353,7 +1501,7 @@ async function runClaudeAndDecide(prompt, policy, deps, spawnFn) {
         if (classified.class === "auth_expired" ||
             classified.class === "env_broken" ||
             isReviewerAuthFailure(combined)) {
-            return envBrokenOutcome(modelId, classified.detail);
+            return envBrokenOutcome(modelId, classified.detail, chargeReviewAttempt(costCtx, modelId, "infra_auth", 0));
         }
         const isCapacity = classified.class === "capacity_exhausted" ||
             classified.class === "claude_unavailable";
@@ -1362,6 +1510,10 @@ async function runClaudeAndDecide(prompt, policy, deps, spawnFn) {
             const resumeMs = extractResetTime(combined);
             if (resumeMs !== null)
                 lastResumeMs = resumeMs;
+            // REV-COST: a 429/overload brownout is INFRA. Recording it makes "N
+            // attempts on one review" visible WITHOUT any of those attempts consuming
+            // the per-review budget the productive attempt needs.
+            const capacityLedger = chargeReviewAttempt(costCtx, modelId, "infra_capacity", 0);
             // Re-route to the next lower catalog tier instead of stalling the lane.
             if (!isLast)
                 continue;
@@ -1377,6 +1529,8 @@ async function runClaudeAndDecide(prompt, policy, deps, spawnFn) {
                 resume_at: lastResumeMs !== null ? new Date(lastResumeMs).toISOString() : null,
                 model_used: modelId,
                 capacity_degraded: true,
+                cost_cap: costCtx.cap,
+                cost_breakdown: capacityLedger,
             };
         }
         // Genuine error (task_error / usage_limit) — legacy reviewer_error, no