v1.93.17.0 stamp: merge main 9cc40e0d03 into #3811 (land)

lib/eval-plan.ts

@@ -39,7 +39,7 @@ export function preregTemplate(title = 'Eval preregistration'): string {
 <!-- One line per metric: name, the pass bar, the direction, and what a miss means for the decision. -->
 
 ## Arms
-<!-- One line per arm: the arm identity first (\`<model>\` or \`<model>#<loadout>\`, the model in lib/pricing.ts, e.g. \`claude-opus-5-5#no-gstack\`), settings, and the per-item cost from \`gstack-eval-plan arms\`. -->
+<!-- One line per arm: the arm identity first (\`<model>\` or \`<model>#<loadout>\`, the model in lib/pricing.ts, e.g. \`claude-opus-5-5#no-gstack\`), settings, and the per-item cost from \`gstack-eval-plan arms\`. Models under test are frontier models (today \`claude-opus-5-5\`, \`gpt-6.1-sol\`) plus at most one named low-cost primary; a Haiku or Sonnet arm only with a stated tier question. -->
 
 ## Comparison
 <!-- \`stack: loaded\` when any arm loads gstack or another skill stack (review variants, preamble loadouts, skill diets, a model panel under a stack); otherwise \`stack: none\` and a \`why:\` line. -->
@@ -292,10 +292,16 @@ export interface DryRunResult {
     reservation_fits_cap?: { ok: boolean; cap: number; max_input_tokens: number; per_arm: Record<string, number | null> };
     /** Present when the caller linted the arms against .gstack/eval-models.json (lib/eval-models.ts). */
     model_rules?: { ok: boolean; source: string; refused: string[] };
+    /** R54: Haiku and Sonnet are not models under test; arms on them alone are refused unless the plan asks about that tier. */
+    frontier: { ok: boolean; small_tier: string[]; tier_question: string | null; recost_usd: Record<string, number> };
   };
   per_item_usd: Record<string, number | null>; excluded_billing: readonly string[]; pass: boolean; stub: 'stub-model (no network, $0)';
 }
-export interface DryRunOptions { input: string; arms: string[]; fields?: string[]; outputBudget?: number; retryPrompt?: string; maxRows?: number; cap?: number; modelRules?: ModelRulesCheck }
+export interface DryRunOptions { input: string; arms: string[]; fields?: string[]; outputBudget?: number; retryPrompt?: string; maxRows?: number; cap?: number; modelRules?: ModelRulesCheck; tierQuestion?: string }
+
+/** Today's frontier models under test (R54, docs/TESTING_INTERNALS.md#frontier-models-under-test); a small-tier plan is re-costed on these. */
+export const FRONTIER_MODELS = ['claude-opus-5-5', 'gpt-6.1-sol'] as const;
+export const isSmallTierModel = (model: string) => /(^|[-/])(haiku|sonnet)(-|$)/i.test(model);
 
 /** Four bytes per token, the estimator every gstack admission uses. */
 export const estimateTokens = (text: string) => Math.ceil(Buffer.byteLength(text, 'utf8') / 4);
@@ -335,9 +341,12 @@ export function dryRun(o: DryRunOptions): DryRunResult {
     checks.reservation_fits_cap = { ok: Object.values(perArm).every(v => v === null || v <= o.cap!), cap: o.cap, max_input_tokens: maxInput, per_arm: perArm };
   }
   if (o.modelRules) checks.model_rules = { ok: o.modelRules.ok, source: o.modelRules.source, refused: o.modelRules.errors.map(e => e.message) };
+  const smallTier = o.arms.filter(a => isSmallTierModel(armModel(a)));
+  const recost = Object.fromEntries(FRONTIER_MODELS.map(m => [m, rows * o.arms.length * estimateCostUsd({ input: avgIn, output: budget }, m)]));
+  checks.frontier = { ok: smallTier.length < o.arms.length || !!o.tierQuestion?.trim(), small_tier: smallTier, tier_question: o.tierQuestion?.trim() || null, recost_usd: recost };
   return {
     schema_version: 1, input: o.input, rows, bad_rows: bad, est_input_tokens: inputTokens, est_output_tokens: rows * budget, arms: o.arms, checks, per_item_usd: perItem,
-    excluded_billing: EXCLUDED_BILLING_CATEGORIES, pass: rows > 0 && bad.length === 0 && checks.price_table.ok && checks.output_budget.ok && checks.retry_prompt.ok && (checks.reservation_fits_cap?.ok ?? true) && (checks.model_rules?.ok ?? true), stub: 'stub-model (no network, $0)',
+    excluded_billing: EXCLUDED_BILLING_CATEGORIES, pass: rows > 0 && bad.length === 0 && checks.price_table.ok && checks.output_budget.ok && checks.retry_prompt.ok && (checks.reservation_fits_cap?.ok ?? true) && (checks.model_rules?.ok ?? true) && checks.frontier.ok, stub: 'stub-model (no network, $0)',
   };
 }
 
@@ -349,6 +358,7 @@ export function renderDryRun(r: DryRunResult): string {
     `CHECK: output-budget ${r.checks.output_budget.ok ? 'ok' : 'too small'} (${r.checks.output_budget.budget} tokens; reasoning floor ${r.checks.output_budget.floor})`,
     `CHECK: retry-prompt ${r.checks.retry_prompt.ok ? `ok — ${JSON.stringify(r.checks.retry_prompt.text)}` : 'missing (pass --retry-prompt <file> with the exact text the run will send)'}`,
     ...(r.checks.reservation_fits_cap ? [renderReservationCheck(r.checks.reservation_fits_cap, r.checks.output_budget.budget)] : []),
+    ...(r.checks.frontier.small_tier.length ? [renderFrontierCheck(r.checks.frontier, r.arms.length)] : []),
     ...(r.checks.model_rules ? [`CHECK: model-rules ${r.checks.model_rules.ok ? 'ok' : `refused ${r.checks.model_rules.refused.join('; ') || 'invalid rules'}`} (source ${r.checks.model_rules.source})`] : []),
     ...Object.entries(r.per_item_usd).map(([m, usd]) => `ESTIMATE: ${m} per_item=${usd === null ? 'unknown (no price)' : `$${usd.toFixed(4)}`} (estimate: excludes ${r.excluded_billing.length} billing categories, see lib/pricing.ts)`),
     `DRY_RUN_RESULT: ${r.pass ? 'pass' : 'fail'}`,
@@ -356,6 +366,13 @@ export function renderDryRun(r: DryRunResult): string {
   return lines.join('\n') + '\n';
 }
 
+function renderFrontierCheck(c: DryRunResult['checks']['frontier'], arms: number): string {
+  const verdict = !c.ok ? 'refused (every arm is Haiku or Sonnet; pass --tier-question "<what the preregistration asks about that tier>" or test a frontier model)'
+    : c.tier_question ? `ok (tier question: ${JSON.stringify(c.tier_question)})` : 'warn (Haiku or Sonnet arms are not models under test)';
+  const recost = Object.entries(c.recost_usd).map(([m, usd]) => `${m} $${usd.toFixed(2)}`).join(', ');
+  return `CHECK: frontier ${verdict} small_tier=${c.small_tier.join(',')}; all ${arms} arm(s) re-costed on frontier prices: ${recost} (docs/TESTING_INTERNALS.md#frontier-models-under-test)`;
+}
+
 function renderReservationCheck(c: NonNullable<DryRunResult['checks']['reservation_fits_cap']>, budget: number): string {
   const worst = Math.max(0, ...Object.values(c.per_arm).filter((v): v is number => v !== null));
   return `CHECK: reservation-fits-cap ${c.ok ? 'ok' : 'exceeds'} ($${worst.toFixed(4)} ${c.ok ? '<=' : '>'} cap $${c.cap.toFixed(2)}) one call = ${c.max_input_tokens} in + ${budget} out tokens`;
@@ -376,6 +393,7 @@ export interface PilotStartOptions { out: string; cap: number; n: number; arms:
 export function startPilot(o: PilotStartOptions): { record: PilotRecord; error?: { code: ResultCodeName; message: string } } {
   const dry = JSON.parse(fs.readFileSync(o.dryRun, 'utf8')) as DryRunResult;
   if (!dry.pass) return { record: null as unknown as PilotRecord, error: { code: 'EVAL_DRY_RUN_FAILED', message: `${o.dryRun} did not pass; the pilot never starts on a failed dry run` } };
+  if (o.arms.length && o.arms.every(a => isSmallTierModel(armModel(a))) && !dry.checks.frontier?.tier_question) return { record: null as unknown as PilotRecord, error: { code: 'EVAL_DRY_RUN_FAILED', message: `every pilot arm is Haiku or Sonnet and ${o.dryRun} records no --tier-question (R54, docs/TESTING_INTERNALS.md#frontier-models-under-test)` } };
   const tokens = o.tokens ?? { input: dry.rows ? Math.ceil(dry.est_input_tokens / dry.rows) : DEFAULT_TOKENS.input, output: dry.checks.output_budget.budget };
   const seat = o.seatMetered ?? [];
   const stray = seat.filter(a => !o.arms.includes(a));

lib/flaky-run.ts

@@ -29,15 +29,23 @@
  *   omits (bun files that fail to load), the run is red and nothing is rerun.
  *   The first report is restored at the --junit path when the run ends; each
  *   rerun's report is kept beside it as <name>.rerun-<n>.xml.
+ * - Quarantine (lib/quarantine.ts) is a larger attempt budget, never a skip:
+ *   a live quarantined test is listed and ledgered on every run and never
+ *   counts as a pass. When every test a whole-command attempt failed is
+ *   quarantined and nothing else is wrong, the command may run again, up to
+ *   QUARANTINE_ATTEMPTS in total; the run is green only on an attempt with the
+ *   runner's full green verdict, so a quarantined failure never turns a red
+ *   attempt green. One that fails every attempt is a hard break. A quarantined
+ *   id missing from a run that included its file is red.
  */
 import * as fs from 'fs';
 import * as path from 'path';
 import { spawn as spawnChild, spawnSync } from 'child_process';
-import { finalAttempt, JunitError, readJunit, type JunitReport, type JunitRunner, type JunitTest } from './junit';
+import { finalAttempt, JunitError, parseTestId, readJunit, type Attempt, type JunitReport, type JunitRunner, type JunitTest } from './junit';
 import { redactFindingSpans } from './redact-engine';
 import { resolveStateRoot } from './state-root';
 
-export type LedgerKind = 'flaky-pass' | 'rerun-fail';
+export type LedgerKind = 'flaky-pass' | 'rerun-fail' | 'quarantined-pass' | 'quarantined-fail' | 'hard-break';
 
 export interface LedgerLine {
   ts: string;
@@ -64,6 +72,8 @@ export interface RunOptions {
   maxReruns: number;
   /** 'command' (default): rerun the whole command. 'test': rerun the failed test alone when the first run is proven complete. */
   rerunScope?: 'command' | 'test';
+  /** Live quarantined test ids (lib/quarantine.ts liveQuarantine): up to QUARANTINE_ATTEMPTS attempts, never a skip. */
+  quarantined?: ReadonlySet<string>;
   cwd?: string;
   env?: NodeJS.ProcessEnv;
   /** Runs one attempt; resolves with its exit status and the tail of its combined output. */
@@ -73,7 +83,7 @@ export interface RunOptions {
 
 export interface TestOutcome {
   test: JunitTest;
-  status: 'flaky-pass' | 'fail' | 'rerun-fail';
+  status: 'flaky-pass' | 'fail' | 'rerun-fail' | 'quarantined-pass' | 'quarantined-fail' | 'hard-break';
   attempts: string[];
   reason?: string;
 }
@@ -88,6 +98,8 @@ export interface RunResult {
   commandExit: number;
   outcomes: TestOutcome[];
   reruns: number;
+  /** Outcomes of quarantined tests (listed, never counted as passes). */
+  quarantined: number;
   /** Why the rerun was the whole command (the default, or why a requested targeted rerun was refused); absent for targeted reruns. */
   wholeRerun?: string;
   ledger: LedgerLine[];
@@ -243,7 +255,7 @@ function rerunProblem(again: Attempted & { report?: JunitReport }, first: JunitR
 }
 
 /** A rerun clears a test only when its command exited 0 and the test ran once and passed on its first attempt. */
-function rerunVerdict(again: Attempted & { report?: JunitReport; error?: JunitError }, t: JunitTest, problem?: string): { status: 'flaky-pass' | 'rerun-fail'; attempts: string[]; reason?: string } {
+function rerunVerdict(again: Attempted & { report?: JunitReport; error?: JunitError }, t: JunitTest, problem?: string): { status: 'flaky-pass' | 'rerun-fail'; attempts: Attempt[]; reason?: string } {
   const match = again.report?.tests.find(x => x.id === t.id);
   if (!match) return { status: 'rerun-fail', attempts: [...t.attempts, 'fail'], reason: again.error ? `rerun: ${again.error.message}` : 'rerun: the report does not contain this test' };
   const attempts = [...t.attempts, ...match.attempts];
@@ -254,11 +266,47 @@ function rerunVerdict(again: Attempted & { report?: JunitReport; error?: JunitEr
   return { status: 'flaky-pass', attempts };
 }
 
+export const QUARANTINE_ATTEMPTS = 3;
+
+const PASSING: ReadonlySet<TestOutcome['status']> = new Set(['flaky-pass', 'quarantined-pass']);
+
+type Ran = Attempted & { report?: JunitReport; error?: JunitError };
+
+/** The runner's own full green verdict for a whole-command attempt: exit 0, no failed or missing test, nothing counted outside the report. */
+function fullGreen(again: Ran, first: JunitReport): boolean {
+  return !!again.report && !again.signal && again.exit === 0 && !rerunProblem(again, first, true);
+}
+
+/**
+ * Whether a red whole-command attempt may be followed by another: only within
+ * the quarantine budget, and only when every test it failed is a live
+ * quarantined test that ran once and nothing else is wrong (a kill, a missing
+ * report, failures outside the report, a first-run test missing).
+ */
+function mayRunAgain(again: Ran, first: JunitReport, quarantined: ReadonlySet<string>, attemptsSoFar: number): boolean {
+  if (attemptsSoFar >= QUARANTINE_ATTEMPTS || again.signal || !again.report) return false;
+  const failedNow = again.report.tests.filter(x => finalAttempt(x) === 'fail');
+  if (!failedNow.length || !failedNow.every(x => quarantined.has(x.id) && x.executions === 1 && x.attempts.length === 1)) return false;
+  if (unreportedFailures(first.runner, again.output, failedNow.length)) return false;
+  const seen = new Set(again.report.tests.map(x => x.id));
+  return first.tests.every(x => seen.has(x.id));
+}
+
+/** A test's attempts over the first run and the given whole-command reruns; a rerun that did not report it counts as a failure. */
+const history = (t: JunitTest, runs: Ran[]): Attempt[] =>
+  [...t.attempts, ...runs.flatMap(r => r.report?.tests.find(x => x.id === t.id)?.attempts ?? ['fail' as const])];
+
+/** A quarantined test passes only when it never failed or an attempt with the runner's full verdict cleared it. */
+const quarantinedStatus = (attempts: string[], cleared: boolean): 'quarantined-pass' | 'quarantined-fail' | 'hard-break' =>
+  cleared || !attempts.includes('fail') ? 'quarantined-pass'
+    : attempts.length >= QUARANTINE_ATTEMPTS && attempts.every(a => a === 'fail') ? 'hard-break' : 'quarantined-fail';
+
 export async function runFlaky(opts: RunOptions): Promise<RunResult> {
   const cwd = opts.cwd ?? process.cwd();
   const env = { ...(opts.env ?? process.env), PLAYWRIGHT_JUNIT_INCLUDE_RETRIES: '1' };
   const now = opts.now ?? (() => new Date());
-  const empty = { tests: 0, outcomes: [], reruns: 0, ledger: [] };
+  const quarantined = opts.quarantined ?? new Set<string>();
+  const empty = { tests: 0, outcomes: [], reruns: 0, quarantined: 0, ledger: [] };
   const first = await attempt(opts, opts.command, cwd, env);
   if (first.signal) return { exitCode: 3, code: 'FLAKY_COMMAND_KILLED', message: `the command was killed by ${first.signal}`, commandExit: first.exit, ...empty };
   if (!first.report) return { exitCode: 3, code: first.error!.code, message: first.error!.message, commandExit: first.exit, ...empty };
@@ -282,15 +330,39 @@ export async function runFlaky(opts: RunOptions): Promise<RunResult> {
   const prov = provenance(cwd, env);
   const line = (t: JunitTest, kind: LedgerKind, by: LedgerLine['rerun_by'], attempts: string[], scope?: LedgerLine['rerun_scope']): LedgerLine =>
     ({ ts: now().toISOString(), runner: 'junit', kind, id: safeText(t.id), file: safeText(t.file), rerun_by: by, ...(scope ? { rerun_scope: scope } : {}), attempts, ...prov, excerpt: safeExcerpt(t.excerpt) });
-  const ledger: LedgerLine[] = runnerFlaky.map(t => line(t, 'flaky-pass', 'runner', t.attempts));
-  const outcomes: TestOutcome[] = runnerFlaky.map(t => ({ test: t, status: 'flaky-pass' as const, attempts: t.attempts }));
+  const isQ = (t: JunitTest) => quarantined.has(t.id);
+  const outcomes: TestOutcome[] = [];
+  const ledger: LedgerLine[] = [];
+  for (const t of runnerFlaky.filter(x => !isQ(x))) {
+    outcomes.push({ test: t, status: 'flaky-pass', attempts: t.attempts });
+    ledger.push(line(t, 'flaky-pass', 'runner', t.attempts));
+  }
+  const settleQ = (t: JunitTest, attempts: string[], cleared: boolean, reason?: string, scope?: LedgerLine['rerun_scope']) => {
+    const status = quarantinedStatus(attempts, cleared);
+    const why = status === 'hard-break' ? `failed all ${attempts.length} attempts: a hard break, not a flake` : status === 'quarantined-fail' ? reason : undefined;
+    outcomes.push({ test: t, status, attempts, ...(why ? { reason: why } : {}) });
+    ledger.push(line(t, status, 'gstack-flaky', attempts, scope));
+  };
+  const settle = (t: JunitTest, attempts: string[], reason: string) => isQ(t) ? settleQ(t, attempts, false, reason) : outcomes.push({ test: t, status: 'fail', attempts, reason });
+  const present = new Set(report.tests.map(t => t.id));
+  const included = new Set(report.tests.map(t => `${t.file}::${t.project}`));
+  for (const id of quarantined) {
+    const p = parseTestId(id);
+    if (!p || present.has(id) || !included.has(`${p.file}::${p.project}`)) continue;
+    const t: JunitTest = { id, file: p.file, project: p.project, path: p.title.split(' > '), attempts: [], executions: 0, excerpt: [] };
+    outcomes.push({ test: t, status: 'quarantined-fail', attempts: [], reason: 'quarantined, and missing from a run that included its file' });
+    ledger.push(line(t, 'quarantined-fail', 'gstack-flaky', []));
+  }
+  const others = failed.filter(t => !isQ(t)).length;
   const eligible: JunitTest[] = [];
   for (const t of failed) {
-    if (t.executions > 1) outcomes.push({ test: t, status: 'fail', attempts: t.attempts, reason: `it ran ${t.executions} times in this report and one failed; not rerun` });
-    else if (t.attempts.length > 1) outcomes.push({ test: t, status: 'fail', attempts: t.attempts, reason: `the runner already retried (${t.attempts.length} attempts)` });
-    else if (failed.length > opts.maxReruns) outcomes.push({ test: t, status: 'fail', attempts: t.attempts, reason: `${failed.length} tests failed, more than --max-reruns ${opts.maxReruns}; not rerun` });
+    const why = t.executions > 1 ? `it ran ${t.executions} times in this report and one failed; not rerun`
+      : t.attempts.length > 1 ? `the runner already retried (${t.attempts.length} attempts)`
+      : !isQ(t) && others > opts.maxReruns ? `${others} tests failed, more than --max-reruns ${opts.maxReruns}; not rerun` : undefined;
+    if (why) settle(t, t.attempts, why);
     else eligible.push(t);
   }
+  const passedQ = report.tests.filter(t => isQ(t) && finalAttempt(t) !== 'fail' && t.attempts.some(a => a !== 'skip'));
   const wholeRerun = !eligible.length ? undefined
     : opts.rerunScope !== 'test' ? 'the default; --rerun-scope test reruns the failed test alone'
     : incompleteRun(report.runner, first.output, first.exit, opts.command, runnerFlaky.length) ?? undefined;
@@ -304,30 +376,42 @@ export async function runFlaky(opts: RunOptions): Promise<RunResult> {
     return again;
   };
   const record = (t: JunitTest, v: ReturnType<typeof rerunVerdict>, scope: 'test' | 'command') => {
+    if (isQ(t)) return settleQ(t, v.attempts, v.status === 'flaky-pass', v.reason, scope);
     outcomes.push({ test: t, status: v.status, attempts: v.attempts, ...(v.reason ? { reason: v.reason } : {}) });
     ledger.push(line(t, v.status, 'gstack-flaky', v.attempts, scope));
   };
+  const runs: Ran[] = [];
   try {
-    if (wholeRerun && outcomes.some(o => o.status === 'fail')) {
-      for (const t of eligible) outcomes.push({ test: t, status: 'fail', attempts: t.attempts, reason: `not rerun: the run is already red, and a rerun would repeat the whole command (${wholeRerun})` });
+    if (wholeRerun && outcomes.some(o => !PASSING.has(o.status))) {
+      for (const t of eligible) settle(t, t.attempts, `not rerun: the run is already red, and a rerun would repeat the whole command (${wholeRerun})`);
     } else if (wholeRerun) {
-      const again = await rerun(opts.command);
-      const problem = rerunProblem(again, report, true);
-      for (const t of eligible) record(t, rerunVerdict(again, t, problem), 'command');
+      do {
+        runs.push(await rerun(opts.command));
+      } while (!fullGreen(runs.at(-1)!, report) && mayRunAgain(runs.at(-1)!, report, quarantined, 1 + runs.length));
+      const decider = runs.at(-1)!;
+      const problem = rerunProblem(decider, report, true);
+      for (const t of eligible) record(t, rerunVerdict(decider, { ...t, attempts: history(t, runs.slice(0, -1)) }, problem), 'command');
     } else if (eligible.length) {
       let interrupted = false;
       for (const t of eligible) {
-        if (interrupted) { outcomes.push({ test: t, status: 'fail', attempts: t.attempts, reason: 'not rerun: an earlier rerun was killed' }); continue; }
-        const again = await rerun([...opts.command, ...rerunSelection(report.runner as 'playwright' | 'bun', t)]);
-        interrupted = !!again.signal;
-        record(t, rerunVerdict(again, t, rerunProblem(again, report, false)), 'test');
+        if (interrupted) { settle(t, t.attempts, 'not rerun: an earlier rerun was killed'); continue; }
+        let v: ReturnType<typeof rerunVerdict> = { status: 'rerun-fail', attempts: t.attempts };
+        for (let budget = isQ(t) ? QUARANTINE_ATTEMPTS - t.attempts.length : 1; budget > 0 && v.status !== 'flaky-pass' && !interrupted; budget--) {
+          const again = await rerun([...opts.command, ...rerunSelection(report.runner as 'playwright' | 'bun', t)]);
+          interrupted = !!again.signal;
+          v = rerunVerdict(again, { ...t, attempts: v.attempts }, rerunProblem(again, report, false));
+        }
+        record(t, v, 'test');
       }
     }
   } finally {
     if (reruns) fs.writeFileSync(junit, firstXml);
   }
-  const red = outcomes.some(o => o.status !== 'flaky-pass');
-  return { exitCode: red ? 1 : 0, tests: report.tests.length, commandExit: first.exit, outcomes, reruns, ...(wholeRerun && reruns ? { wholeRerun } : {}), ledger };
+  const green = runs.length ? fullGreen(runs.at(-1)!, report) : reruns > 0 || first.exit === 0;
+  for (const t of passedQ) settleQ(t, history(t, runs), green, 'the attempt that decided the run was not a full green run', runs.length ? 'command' : undefined);
+  const red = !green || outcomes.some(o => !PASSING.has(o.status));
+  const q = outcomes.filter(o => o.status === 'quarantined-pass' || o.status === 'quarantined-fail' || o.status === 'hard-break').length;
+  return { exitCode: red ? 1 : 0, tests: report.tests.length, commandExit: first.exit, outcomes, reruns, quarantined: q, ...(wholeRerun && reruns ? { wholeRerun } : {}), ledger };
 }
 
 export function ledgerPath(flag: string | undefined, env: NodeJS.ProcessEnv = process.env): string {
@@ -352,9 +436,9 @@ export function renderResult(r: RunResult, ledger: string): string[] {
   const out: string[] = [];
   for (const o of r.outcomes) out.push(`FLAKY: ${o.status} ${safeText(o.test.id)} attempts=${o.attempts.join(',')}${o.reason ? ` (${o.reason})` : ''}`);
   const flaky = r.outcomes.filter(o => o.status === 'flaky-pass').length;
-  const failed = r.outcomes.length - flaky;
+  const failed = r.outcomes.filter(o => !PASSING.has(o.status)).length;
   if (r.wholeRerun) out.push(`FLAKY_RERUN: scope=command (${r.wholeRerun})`);
-  out.push(`FLAKY_RESULT: tests=${r.tests} failed=${failed} flaky=${flaky} reruns=${r.reruns} command_exit=${r.commandExit} verdict=${r.exitCode === 0 ? 'pass' : 'fail'} ledger=${r.ledger.length ? ledger : 'none'}`);
+  out.push(`FLAKY_RESULT: tests=${r.tests} failed=${failed} flaky=${flaky} quarantined=${r.quarantined} reruns=${r.reruns} command_exit=${r.commandExit} verdict=${r.exitCode === 0 ? 'pass' : 'fail'} ledger=${r.ledger.length ? ledger : 'none'}`);
   return out;
 }
 

lib/junit.ts

@@ -137,6 +137,14 @@ function excerptOf(node: XmlNode | undefined): string[] {
 
 export const testId = (file: string, project: string, path: string[]) => `${file}::${project}::${path.join(' > ')}`;
 
+/** The parts of a test id, or null when it is not `<file>::<project>::<title>`. */
+export function parseTestId(id: string): { file: string; project: string; title: string } | null {
+  const i = id.indexOf('::');
+  const j = i < 0 ? -1 : id.indexOf('::', i + 2);
+  if (i <= 0 || j < 0 || j + 2 >= id.length) return null;
+  return { file: id.slice(0, i), project: id.slice(i + 2, j), title: id.slice(j + 2) };
+}
+
 function readCase(tc: XmlNode, runner: JunitRunner): Omit<JunitTest, 'id' | 'executions'> & { hidden: boolean } {
   const suite = tc.parent!;
   let file: string, project = '', path: string[];

lib/pregate/checks/lanes.ts

@@ -27,6 +27,7 @@
  * Incidents: p0-4-pipe-hidden-failure (`false | tail` read as green),
  * p0-4-windows-lane-unrun (a Windows-only change merged with its lane unrun).
  */
+import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { baseInputs, sha256 } from '../context';
@@ -43,17 +44,21 @@ import { verifyFromRun } from '../../run-evidence';
 import { matchesAny } from '../../ship-policy';
 import type { CheckDef, CheckResult, PregateContext, RemoteObligation } from '../types';
 
-/** The test command with `{files}`; detected from the repo when the config does not name one. */
+/** The runner a `.py`-only selection gets; it needs the pytest module importable by python3 (`pytestMissing`). */
+const PYTEST = 'python3 -m pytest {files}';
+
+/** The test command with `{files}`; detected from the repo when the config does not name one. The repo's bun, vitest or jest claims JS/TS files only. */
 export function detectRunner(ctx: Pick<PregateContext, 'config' | 'repoRoot'>, files: readonly string[]): string | null {
   if (ctx.config.runner) return ctx.config.runner;
   const has = (f: string) => fs.existsSync(path.join(ctx.repoRoot, f));
   let pkg: { devDependencies?: Record<string, string>; dependencies?: Record<string, string>; scripts?: Record<string, string> } = {};
   try { pkg = JSON.parse(fs.readFileSync(path.join(ctx.repoRoot, 'package.json'), 'utf8')); } catch { /* no package.json */ }
   const deps = { ...pkg.dependencies, ...pkg.devDependencies };
-  if (has('bunfig.toml') || has('bun.lock') || has('bun.lockb')) return 'bun test {files}';
-  if (deps.vitest) return 'npx vitest run {files}';
-  if (deps.jest) return 'npx jest {files}';
-  if (files.every(f => /\.py$/.test(f)) && files.length) return 'python3 -m pytest {files}';
+  const jsts = files.every(f => /\.[cm]?[jt]sx?$/.test(f));
+  if (jsts && (has('bunfig.toml') || has('bun.lock') || has('bun.lockb'))) return 'bun test {files}';
+  if (jsts && deps.vitest) return 'npx vitest run {files}';
+  if (jsts && deps.jest) return 'npx jest {files}';
+  if (files.every(f => /\.py$/.test(f)) && files.length) return PYTEST;
   if (files.every(f => /\.[cm]?js$/.test(f)) && files.length) return 'node --test {files}';
   if (files.every(f => /\.[cm]?[jt]sx?$/.test(f)) && files.length && Bun.which('bun')) return 'bun test {files}';
   return null;
@@ -113,6 +118,18 @@ export function dartRunner(repoRoot: string, root: string, env: NodeJS.ProcessEn
   return { runner: `${fvm ? 'fvm ' : ''}${tool} test {files}` };
 }
 
+/**
+ * The tool `python3 -m pytest` lacks: `python3` off the PATH of `env`, or `pytest` when that python3, run from the repo root as the
+ * runner is, cannot import it (a `pytest` script on PATH may belong to another interpreter); null when both are there, or when the
+ * probe itself times out or dies, so the run decides.
+ */
+function pytestMissing(repoRoot: string, env: NodeJS.ProcessEnv): string | null {
+  const python = Bun.which('python3', { PATH: env.PATH ?? '' });
+  if (!python) return 'python3';
+  const r = spawnSync(python, ['-c', 'import importlib.util, sys; sys.exit(3 if importlib.util.find_spec("pytest") is None else 0)'], { cwd: repoRoot, env, stdio: 'ignore', timeout: 10_000 });
+  return r.status === 3 ? 'pytest' : null;
+}
+
 /**
  * `cargo test -p <name>` for a crate (cargo runs a crate's tests, never a file list), or the missing tool when cargo is
  * not on PATH. The name comes from the repo's Cargo.toml and reaches a shell and the `{files}` expansion: a name outside
@@ -163,6 +180,23 @@ function packageRunner(repoRoot: string, dir: string, env: NodeJS.ProcessEnv): {
   return { runner: `${PM_EXEC[pm]} ${tool} {files}` };
 }
 
+/**
+ * Whether a JS/TS test imports a value from Playwright's runner in a statement that starts a line: `import … from '@playwright/test'`
+ * (one line or several), a bare import, or `require`. A type-only import (`import type …`, or every specifier `type X`) and a string or
+ * fixture body that mentions the import mid-line do not count.
+ */
+function importsPlaywright(text: string): boolean {
+  const code = text.replace(/\/\*[\s\S]*?\*\/|\/\/[^\n]*/g, '');
+  if (/^[\t ]*(?:import[\t ]*|(?:const|let|var)\b[^=\n]*=[\t ]*require\([\t ]*)['"]@playwright\/test['"]/m.test(code)) return true;
+  for (const m of code.matchAll(/^[\t ]*import(?=[\s{*])([^'"`;]*?)\bfrom[\t ]*['"]@playwright\/test['"]/gm)) {
+    const spec = m[1]!.trim();
+    if (!/^type(?=[\s{*])/.test(spec) && spec.replace(/[{}]/g, '').split(',').some(s => s.trim() && !/^type\s/.test(s.trim()))) return true;
+  }
+  return false;
+}
+/** Playwright's own text when its browsers are not installed on this machine. */
+const PLAYWRIGHT_NO_BROWSERS = /^.*(?:Executable doesn't exist at|download new browsers).*$/m;
+
 /** The run plan: the groups that can run, the files no runner claims, tools missing from PATH, and `.dart` files with no pubspec.yaml above. */
 export interface RunPlan { groups: RunGroup[]; unclaimed: string[]; missing: string[]; noPubspec: string[] }
 
@@ -171,8 +205,11 @@ export interface RunPlan { groups: RunGroup[]; unclaimed: string[]; missing: str
  * Dart tests run from their own package root (a sub-package's imports resolve
  * against its own pubspec); Rust tests run per crate as `cargo test -p <name>`
  * from the crate's workspace root; JS/TS tests owned by a nested package that
- * declares vitest or jest run from that package; the rest go to the detected
- * runner from the repo root. Files no runner claims (a tool missing from PATH,
+ * declares vitest or jest run from that package; a JS/TS test that imports
+ * `@playwright/test` runs through `playwright test` from its nearest package;
+ * the rest go to the detected runner from the repo root, split by language
+ * when no one runner fits them all (`.mjs` + `.py` runs both), and pytest only
+ * when python3 can import it. Files no runner claims (a tool missing from PATH,
  * a `.dart` file outside any package, a `.rs` file outside any crate or in a
  * crate whose name Cargo would reject, no detected runner) are `unclaimed`: the lane is `incomplete`, never a pass.
  */
@@ -182,6 +219,7 @@ export function planRuns(ctx: PregateContext, files: readonly string[]): RunPlan
   const dart = new Map<string, string[]>();
   const cargo = new Map<string, { name: string; cwd: string; files: string[] }>();
   const packages = new Map<string, string[]>();
+  const playwright = new Map<string, string[]>();
   const seen = new Map<string, string | null>();
   const seenPackage = new Map<string, string | null>();
   let model: CargoModel | null = null;
@@ -204,6 +242,7 @@ export function planRuns(ctx: PregateContext, files: readonly string[]): RunPlan
       continue;
     }
     const pkg = /\.[cm]?[jt]sx?$/.test(f) ? nearestRoot(ctx.repoRoot, f, 'package.json', seenPackage) : null;
+    if (pkg !== null && importsPlaywright(readRepoFile(ctx.repoRoot, f) ?? '')) { add(playwright, pkg, under(pkg, f)); continue; }
     if (pkg) {
       if (!pkgRunners.has(pkg)) pkgRunners.set(pkg, packageRunner(ctx.repoRoot, pkg, ctx.env));
       const r = pkgRunners.get(pkg);
@@ -225,12 +264,24 @@ export function planRuns(ctx: PregateContext, files: readonly string[]): RunPlan
     if (r) missing.add(r.missing);
     unclaimed.push(...c.files.map(f => (c.cwd ? `${c.cwd}/${f}` : f)));
   }
-  if (rest.length) {
-    const runner = detectRunner(ctx, rest);
-    if (runner) groups.push({ runner, cwd: '', files: rest });
-    else unclaimed.push(...rest);
+  const language = (f: string) => (/\.py$/.test(f) ? 'py' : /\.[cm]?js$/.test(f) ? 'js' : /\.[cm]?[jt]sx?$/.test(f) ? 'ts' : f);
+  const parts = !rest.length ? [] : detectRunner(ctx, rest) ? [rest] : [...Map.groupBy(rest, language).values()];
+  const byRunner = new Map<string, string[]>();
+  for (const part of parts) {
+    const runner = detectRunner(ctx, part);
+    const lacking = runner === PYTEST ? pytestMissing(ctx.repoRoot, ctx.env) : null;
+    if (lacking) missing.add(lacking);
+    if (runner && !lacking) for (const f of part) add(byRunner, runner, f);
+    else unclaimed.push(...part);
   }
+  for (const [runner, list] of byRunner) groups.push({ runner, cwd: '', files: list });
   for (const [root, list] of [...packages].sort(([a], [b]) => a.localeCompare(b))) groups.push({ runner: (pkgRunners.get(root) as { runner: string }).runner, cwd: root, files: list });
+  for (const [root, list] of [...playwright].sort(([a], [b]) => a.localeCompare(b))) {
+    const pm = packageManager(ctx.repoRoot, root);
+    const bin = pm === 'npm' ? 'npx' : pm;
+    if (onPath(bin, ctx.env)) groups.push({ runner: `${PM_EXEC[pm]} playwright test --reporter=list {files}`, cwd: root, files: list });
+    else { missing.add(bin); unclaimed.push(...list.map(f => (root ? `${root}/${f}` : f))); }
+  }
   return { groups, unclaimed: [...unclaimed, ...noPubspec], missing: [...missing].sort(), noPubspec };
 }
 
@@ -269,11 +320,20 @@ function parseCargo(output: string): RunnerSummary | null {
   return { ran: lines.reduce((n, m) => n + Number(m[1]), 0) + failed, failed };
 }
 
-/** The runner's own summary line: bun, node --test, vitest, jest, pytest, bats, dart/flutter test, cargo test. A bats, dart/flutter or cargo runner's summary is tried first (cargo's only there: its `N passed` lines would misread as another runner's); for any other runner the bats and dart formats are a last resort. `ran: null` when not recognised. Colour codes are dropped and a carriage return ends a line, so a coloured or redrawn verdict still reads. */
+/** playwright test: the last `N failed`, `N interrupted`, `N flaky`, `N passed` and `N skipped` lines (its closing summary, with test names between them; a test's own output earlier does not count); skipped tests did not run. */
+function parsePlaywright(output: string): RunnerSummary | null {
+  if (!/^\s*\d+ (?:passed|failed|flaky|interrupted|skipped)\b/m.test(output)) return null;
+  const count = (word: string) => Number([...output.matchAll(new RegExp(`^\\s*(\\d+) ${word}\\b`, 'gm'))].pop()?.[1] ?? 0);
+  const failed = count('failed') + count('interrupted');
+  return { ran: count('passed') + count('flaky') + failed, failed };
+}
+
+/** The runner's own summary line: bun, node --test, vitest, jest, pytest, bats, dart/flutter test, cargo test, playwright test. A bats, dart/flutter, playwright or cargo runner's summary is tried first (cargo's only there: its `N passed` lines would misread as another runner's); for any other runner the bats and dart formats are a last resort. `ran: null` when not recognised. Colour codes are dropped and a carriage return ends a line, so a coloured or redrawn verdict still reads. */
 export function parseSummary(raw: string, runner = ''): RunnerSummary {
   const output = raw.replace(/\x1b\[[0-9;?]*[A-Za-z]/g, '').replace(/\r/g, '\n');
   if (/(?<![\w-])cargo\s+test(?![\w-])/.test(runner)) return parseCargo(output) ?? { ran: null, failed: null };
   if (/(?<![\w-])bats(?![\w-])/.test(runner)) { const b = parseBats(output); if (b) return b; }
+  if (/(?<![\w-])playwright\s+test(?![\w-])/.test(runner)) { const p = parsePlaywright(output); if (p) return p; }
   const dartRun = /(?<![\w-])(?:dart|flutter)(?![\w-])/.test(runner);
   if (dartRun) { const d = parseDart(output); if (d) return d; }
   let m: RegExpExecArray | null;
@@ -287,19 +347,22 @@ export function parseSummary(raw: string, runner = ''): RunnerSummary {
   return (dartRun ? null : parseDart(output)) ?? parseBats(output) ?? { ran: null, failed: null };
 }
 
-interface LocalRun { exit: number | null; outcome: Supervised['outcome']; signal: string | null; observedStart: boolean; ran: number | null; failed: number | null; tail: string[]; runner: string; command: string; files: string[]; lastFile: string | null; ms: number; error?: string }
+interface LocalRun { exit: number | null; outcome: Supervised['outcome']; signal: string | null; observedStart: boolean; ran: number | null; failed: number | null; tail: string[]; runner: string; command: string; files: string[]; lastFile: string | null; ms: number; error?: string; noBrowsers?: string }
 
 const quote = (f: string) => `'${f.replace(/'/g, `'\\''`)}'`;
 
 async function runOnce(ctx: PregateContext, env: NodeJS.ProcessEnv, g: RunGroup, files: string[], log: string, counter: Counter): Promise<LocalRun> {
-  const joined = files.map(quote).join(' ');
+  // playwright test reads each file argument as a case-insensitive regex: escape it and anchor it to a path segment, so `a[1].spec.ts` runs that file, not `a1.spec.ts`.
+  const args = /(?<![\w-])playwright\s+test(?![\w-])/.test(g.runner) ? files.map(f => `(?:^|/)${f.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}$`) : files;
+  const joined = args.map(quote).join(' ');
   const run = g.runner.replace('{files}', () => joined);
   const command = g.cwd ? `(cd ${quote(g.cwd)} && ${run})` : run;
   const shown = g.cwd ? files.map(f => `${g.cwd}/${f}`) : files;
   const r = await supervise({ command: run, cwd: path.join(ctx.repoRoot, g.cwd), env: { ...env, CI: env.CI ?? '1' }, log, deadline: Date.now() + ctx.timeoutMs, stallMs: ctx.stallTimeoutMs, label: `lanes (${shown.length === 1 ? shown[0] : `${shown.length} files`})`, files, adapter: adapterFor(g.runner), counter, progress: ctx.progress });
   const output = readRange(log, r.start, r.end);
   const summary = parseSummary(output, g.runner);
-  return { exit: r.exit, outcome: r.outcome, signal: r.signal, observedStart: r.observedStart, ...summary, tail: output.trim().split('\n').slice(-25), runner: g.runner, command, files: shown, lastFile: r.lastFile && g.cwd ? `${g.cwd}/${r.lastFile}` : r.lastFile, ms: r.ms, ...(r.error ? { error: r.error } : {}) };
+  const noBrowsers = /(?<![\w-])playwright\s+test(?![\w-])/.test(g.runner) ? PLAYWRIGHT_NO_BROWSERS.exec(output)?.[0].trim().slice(0, 200) : undefined;
+  return { ...(noBrowsers ? { noBrowsers } : {}), exit: r.exit, outcome: r.outcome, signal: r.signal, observedStart: r.observedStart, ...summary, tail: output.trim().split('\n').slice(-25), runner: g.runner, command, files: shown, lastFile: r.lastFile && g.cwd ? `${g.cwd}/${r.lastFile}` : r.lastFile, ms: r.ms, ...(r.error ? { error: r.error } : {}) };
 }
 
 /**
@@ -496,6 +559,9 @@ async function runSelected(ctx: PregateContext, sel: Selection, base: CheckResul
     // only when the runner's binary is off PATH.
     const environment = r.ran === null && r.bad && !r.bad.observedStart ? classifyCommandEnvironment(r.bad.runner, r.tail.join('\n'), r.exit, runtime.env) : null;
     if (environment) return environmentResult(withRun, environment, `the runner exited ${r.exit} before any test was counted (${total} files): ${environment.evidence}`);
+    // Playwright counts a test whose browser is not installed as failed; when every test of every failed run failed and Playwright says so, the machine lacks the browsers.
+    const failedRuns = r.runs.filter(x => x.exit !== 0);
+    if (failedRuns.every(x => x.noBrowsers && x.failed !== null && x.failed === x.ran)) return environmentResult(withRun, { kind: 'missing-binary', evidence: `Playwright browsers not installed (npx playwright install): ${failedRuns[0]!.noBrowsers}`, proof: 'output' }, `every Playwright test failed to launch its browser (${r.failed} of ${r.ran}; ${total} files)`);
     return { ...withRun, status: 'fail', cause: 'diff', code: 'PREGATE_LANE_FAILED', detail: `local lane exited ${r.exit} (${r.failed ?? '?'} failed of ${r.ran ?? '?'} ran; ${total} files; pipefail)`, fix: `read ${r.log}, fix the in-branch failure, rerun gstack-pregate --stage tests` };
   }
   if (r.ran === 0) return { ...withRun, status: 'fail', cause: 'diff', code: 'PREGATE_LANE_FAILED', detail: `ZERO-RUN: the runner reported 0 tests${r.zero ? ` in ${r.zero}` : ''} (${total} selected file(s))`, fix: 'a bad selector, a missing file or a skipped describe; exit 0 is not a pass' };

lib/pregate/checks/literals.ts

@@ -69,7 +69,12 @@ function unquote(v: string): string { return /^['"`]/.test(v) ? v.slice(1, -1) :
  * `/retry.ts.snap`, or `lib/install.ts` for `install.sh`, is not the module (GST-820): a bare stem such as `install` or `retry` is an
  * English word in half the test tree, and a one-character old value (`2`)
  * sits in every test, so that value needs the constant's name (a wrapper
- * version 2 → 3 flagged 575 consumers through the stem alone).
+ * version 2 → 3 flagged 575 consumers through the stem alone), and counts only
+ * in a statement that names it: on the name's line, or on a line that
+ * continues it (the line before ends open, `(` `,` `.` `=`, or the line
+ * starts with `.` `)` `]`), comments excluded (#3492: `$2`, "from revision 2",
+ * `export default 2`). A call-site name (`attempts`, `limit`) is an ordinary
+ * word, so for it the file must also name the module (gstack-evals#97).
  *
  * A version-history row (`[45, "<digest>"]`, the old value first in a
  * bracketed row) is skipped when the same table, a run of consecutive
@@ -94,12 +99,23 @@ export function consumersOf(repoRoot: string, testFiles: readonly string[], chan
   const moduleRe = new RegExp(`(?:^|[/\\\\])${escape(stem)}(?=[^\\w.-]|$|\\.${dts}(?:${exts})(?![\\w.-])|\\.(?!\\w))|(?<![\\w-])${escape(base)}(?![\\w-]|\\.\\w)`, 'm');
   const nameRe = new RegExp(`\\b${escape(change.name)}\\b`);
   const nameRequired = value.length < 2;
+  const callSite = !/^[A-Z]/.test(change.name);
+  const comment = (l: string) => /^\s*(?:\/\/|#|\*|\/\*|<!--)/.test(l);
+  const continues = (prev: string, cur: string) => /[([{,.=+\-*/&|?:\\]\s*$/.test(prev) || /^\s*[.)\]}?:&|+]/.test(cur);
   const hits: string[] = [];
   for (const rel of testFiles) {
     let text: string;
     try { text = fs.readFileSync(path.join(repoRoot, rel), 'utf8'); } catch { continue; }
-    if (!(nameRe.test(text) || (!nameRequired && moduleRe.test(text)))) continue;
+    if (nameRequired ? !(nameRe.test(text) && (!callSite || moduleRe.test(text))) : !(nameRe.test(text) || moduleRe.test(text))) continue;
     const lines = text.split('\n');
+    const named = (i: number) => {
+      if (comment(lines[i]!)) return false;
+      for (let j = i; j >= 0 && i - j < 4; j--) {
+        if (j < i && (comment(lines[j]!) || !continues(lines[j]!, lines[j + 1]!))) return false;
+        if (nameRe.test(lines[j]!)) return true;
+      }
+      return false;
+    };
     const table: number[] = [];
     const tableHasNew: boolean[] = [];
     for (let i = 0; i < lines.length; i++) {
@@ -115,7 +131,7 @@ export function consumersOf(repoRoot: string, testFiles: readonly string[], chan
       if (extended === undefined) { const base = baseText?.(rel); extended = base === null || (base !== undefined && !newRowRe.test(base)); }
       return extended;
     };
-    for (let i = 0; i < lines.length; i++) if (valueRe.test(lines[i]!) && !skip(i)) { hits.push(`${rel}:${i + 1}`); break; }
+    for (let i = 0; i < lines.length; i++) if (valueRe.test(lines[i]!) && (!nameRequired || oldRowRe.test(lines[i]!) || named(i)) && !skip(i)) { hits.push(`${rel}:${i + 1}`); break; }
   }
   return hits;
 }

lib/pregate/init-draft.ts

@@ -79,8 +79,7 @@ export function draftConfig(repoRoot: string): InitDraft {
     const runner = detectRunner({ repoRoot, config: DEFAULT_CONFIG }, list);
     return runner ? `${lang} tests detected at run time: ${runner}` : `no runner detected for ${list.length} ${lang} test file(s); set runner (with {files})`;
   });
-  const mixed = [...groups.keys()].filter(l => l !== 'dart' && l !== 'rust').length > 1 ? '; a selection mixing these languages needs runner set' : '';
-  const runnerNote = notes.length ? notes.join('; ') + mixed : 'no test files found';
+  const runnerNote = notes.length ? notes.join('; ') : 'no test files found';
 
   const selectionTodo = discoverLanes(repoRoot).filter(l => l.runsTests && l.matrixExpression && l.testFiles.length === 0).map(l => l.id);
   const config = { $schema: PREGATE_CONFIG_SCHEMA, runner: null, dependencies, empty_lanes: [], selection: {}, warn: [], strays: { allow: [] } };

lib/pricing.ts

@@ -149,3 +149,66 @@ export function estimateCostUsd(
   const outputCost = tokens.output * row.output_per_mtok / 1_000_000;
   return +(inputCost + cachedCost + outputCost).toFixed(6);
 }
+
+/** Token classes of one Anthropic Messages usage block, as Claude Code's stream-json and session transcripts carry it. */
+export interface AnthropicUsage {
+  input_tokens?: number;
+  output_tokens?: number;
+  cache_read_input_tokens?: number;
+  cache_creation_input_tokens?: number;
+  cache_creation?: { ephemeral_5m_input_tokens?: number; ephemeral_1h_input_tokens?: number };
+}
+
+/** Anthropic bills a prompt-cache write at 1.25x input for the 5-minute TTL and 2x for the 1-hour TTL. */
+export const CACHE_WRITE_MULTIPLIER = { ephemeral_5m: 1.25, ephemeral_1h: 2 } as const;
+
+/**
+ * Cost of one usage block at its model's row, prompt-cache writes included
+ * (unlike estimateCostUsd). Undefined when the model has no price row: an
+ * unpriced model's usage is unknown cost, never zero.
+ */
+export function anthropicUsageCostUsd(usage: AnthropicUsage, model: string | undefined): number | undefined {
+  const row = pricingRow(model);
+  if (!row) return undefined;
+  const count = (value: unknown) => typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : 0;
+  const oneHour = count(usage.cache_creation?.ephemeral_1h_input_tokens);
+  const fiveMinute = typeof usage.cache_creation?.ephemeral_5m_input_tokens === 'number'
+    ? count(usage.cache_creation.ephemeral_5m_input_tokens) : Math.max(0, count(usage.cache_creation_input_tokens) - oneHour);
+  const cachedRate = row.cached_input_per_mtok ?? row.input_per_mtok * 0.1;
+  return (count(usage.input_tokens) * row.input_per_mtok
+    + count(usage.cache_read_input_tokens) * cachedRate
+    + fiveMinute * row.input_per_mtok * CACHE_WRITE_MULTIPLIER.ephemeral_5m
+    + oneHour * row.input_per_mtok * CACHE_WRITE_MULTIPLIER.ephemeral_1h
+    + count(usage.output_tokens) * row.output_per_mtok) / 1_000_000;
+}
+
+/**
+ * Billed cost of a session's assistant messages, subagent (sidechain) turns
+ * included. A message streams as several events sharing one message id whose
+ * usage grows, so each id counts once at its largest output. Each message is
+ * priced at its own model, else `fallbackModel`. Undefined when no message
+ * carries usage or any message's model has no price row.
+ */
+export function streamedUsageCostUsd(
+  events: ReadonlyArray<{ message?: { id?: unknown; model?: unknown; usage?: unknown } } | null | undefined>,
+  fallbackModel?: string,
+): number | undefined {
+  const byId = new Map<string, { model?: string; usage: AnthropicUsage }>();
+  for (const event of events) {
+    const message = event?.message;
+    const usage = message?.usage as AnthropicUsage | undefined;
+    if (!usage || typeof usage !== 'object' || typeof message!.id !== 'string' || message!.model === '<synthetic>') continue;
+    const seen = byId.get(message!.id);
+    if (!seen || (usage.output_tokens ?? 0) >= (seen.usage.output_tokens ?? 0)) {
+      byId.set(message!.id, { model: typeof message!.model === 'string' ? message!.model : fallbackModel, usage });
+    }
+  }
+  if (byId.size === 0) return undefined;
+  let total = 0;
+  for (const { model, usage } of byId.values()) {
+    const cost = anthropicUsageCostUsd(usage, model);
+    if (cost === undefined) return undefined;
+    total += cost;
+  }
+  return +total.toFixed(6);
+}

lib/quarantine.ts

@@ -0,0 +1,447 @@
+/**
+ * gstack-flaky quarantine (GSTA-158 P2): a registry of known-flaky tests at
+ * `.gstack/quarantine.json`. A quarantined test still runs; it gets a larger
+ * attempt budget (lib/flaky-run.ts, QUARANTINE_ATTEMPTS) under the same full
+ * green verdict, and it is never counted as a pass. This file holds the
+ * registry: schema, validation, add/renew/release, `check` against the base
+ * branch, and `report` over downloaded ledgers.
+ *
+ * Rules (docs/flaky.md § Quarantine):
+ * - Every entry has an owner, a ledger link, a failure class (detector,
+ *   harness, timing, model-latency; product defects and infra are refused),
+ *   evidence and an expiry: 7 days by default, at most 14 from entry, and one
+ *   renewal of at most 7 days with new evidence and the owner named again.
+ * - An expired or invalid entry is not quarantined; nothing needs editing.
+ * - Live entries are capped at max(1, 10% of the suite's tests), and 5 for a
+ *   suite under 50 tests.
+ * - `run --base` reads the registry from the base branch so a change cannot
+ *   quarantine the test it breaks; `check --base` refuses an entry added in
+ *   the change that edits its test's file, an entry that disappears without a
+ *   release record, a release record that was removed, and rewritten history.
+ * - gstack's own CASE_QUARANTINE / EVAL_POLICY (paid evals) is a separate
+ *   registry; the two share no schema.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { spawnSync } from 'child_process';
+import { parseTestId, readJunit, type JunitRunner } from './junit';
+import { safeText } from './flaky-run';
+
+export const REGISTRY_PATH = '.gstack/quarantine.json';
+export const FAILURE_CLASSES = ['detector', 'harness', 'timing', 'model-latency'] as const;
+export type FailureClass = typeof FAILURE_CLASSES[number];
+export const DEFAULT_DAYS = 7;
+export const MAX_DAYS = 14;
+export const RENEW_MAX_DAYS = 7;
+export const EXIT_RULE_PASSES = 10;
+const DAY = 86_400_000;
+
+export interface Renewal { renewedAt: string; previousExpiresAt: string; expiresAt: string; owner: string; evidence: string[] }
+
+export interface QuarantineEntry {
+  owner: string;
+  /** Link to the flaky ledger line or issue that tracks the fix. */
+  ledger: string;
+  failureClass: FailureClass;
+  reason: string;
+  evidence: string[];
+  enteredAt: string;
+  expiresAt: string;
+  renewals: Renewal[];
+  /** The suite's test count when the entry was added (`add --junit`), the base of the cap. */
+  suiteTests: number;
+}
+
+export type ReleasedEntry = Omit<QuarantineEntry, 'reason'> & { id: string; releasedAt: string; reason: string; pr: string };
+
+export interface Registry { schema: 1; entries: Record<string, QuarantineEntry>; released: ReleasedEntry[] }
+
+export class QuarantineError extends Error {
+  constructor(readonly code: string, message: string, readonly exitCode: 1 | 2 | 3 = 3) { super(message); }
+}
+
+export const emptyRegistry = (): Registry => ({ schema: 1, entries: {}, released: [] });
+
+/** Live entries allowed for a suite of `tests` tests. */
+export const suiteCap = (tests: number) => tests < 50 ? 5 : Math.max(1, Math.floor(tests / 10));
+
+function git(args: string[], cwd: string): { ok: boolean; out: string } {
+  const r = spawnSync('git', args, { cwd, encoding: 'utf-8', timeout: 15_000 });
+  return { ok: r.status === 0, out: r.stdout ?? '' };
+}
+
+export function repoRoot(cwd: string): string {
+  const r = git(['rev-parse', '--show-toplevel'], cwd);
+  return r.ok && r.out.trim() ? r.out.trim() : cwd;
+}
+
+export function parseRegistry(text: string, source: string): Registry {
+  let data: unknown;
+  try { data = JSON.parse(text); } catch (e) {
+    throw new QuarantineError('FLAKY_QUARANTINE_INVALID', `${source} is not valid JSON (${(e as Error).message})`);
+  }
+  const r = data as Partial<Registry> | null;
+  if (!r || typeof r !== 'object' || r.schema !== 1 || !r.entries || typeof r.entries !== 'object' || Array.isArray(r.entries) || !Array.isArray(r.released)) {
+    throw new QuarantineError('FLAKY_QUARANTINE_INVALID', `${source} is not a schema 1 quarantine registry ({"schema":1,"entries":{},"released":[]})`);
+  }
+  return r as Registry;
+}
+
+function resolveCommit(ref: string, cwd: string): string {
+  if (!ref || ref.startsWith('-')) throw new QuarantineError('FLAKY_QUARANTINE_BASE', `--base ${JSON.stringify(ref)} is not a git ref`, 2);
+  const r = git(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], cwd);
+  if (!r.ok) throw new QuarantineError('FLAKY_QUARANTINE_BASE', `--base ${ref} does not resolve to a commit in ${cwd}`);
+  return r.out.trim();
+}
+
+function registryAt(commit: string, root: string, label: string): Registry {
+  if (!git(['cat-file', '-e', `${commit}:${REGISTRY_PATH}`], root).ok) return emptyRegistry();
+  const shown = git(['show', `${commit}:${REGISTRY_PATH}`], root);
+  if (!shown.ok) throw new QuarantineError('FLAKY_QUARANTINE_BASE', `cannot read ${REGISTRY_PATH} at ${label}`);
+  return parseRegistry(shown.out, `${REGISTRY_PATH} at ${label}`);
+}
+
+/** The registry in the working tree, or at `base` when given; a missing file is an empty registry. */
+export function readRegistry(cwd: string, base?: string): Registry {
+  const root = repoRoot(cwd);
+  if (base !== undefined) return registryAt(resolveCommit(base, root), root, base);
+  const file = path.join(root, REGISTRY_PATH);
+  if (!fs.existsSync(file)) return emptyRegistry();
+  return parseRegistry(fs.readFileSync(file, 'utf-8'), REGISTRY_PATH);
+}
+
+export function writeRegistry(cwd: string, reg: Registry): string {
+  const file = path.join(repoRoot(cwd), REGISTRY_PATH);
+  const entries = Object.fromEntries(Object.keys(reg.entries).sort().map(id => [id, reg.entries[id]!]));
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify({ schema: 1, entries, released: reg.released }, null, 2) + '\n');
+  return file;
+}
+
+const filled = (s: unknown): s is string => typeof s === 'string' && s.trim().length > 0;
+const filledList = (l: unknown): l is string[] => Array.isArray(l) && l.length > 0 && l.every(filled);
+
+export function classRefusal(c: unknown): string | undefined {
+  if (FAILURE_CLASSES.includes(c as FailureClass)) return undefined;
+  if (c === 'product') return 'class product is refused: a product defect is a real red; fix it instead of quarantining it';
+  if (c === 'infra') return 'class infra is refused: an infrastructure red is rerun or fixed as infra, never quarantined';
+  return `class ${JSON.stringify(c)} is not one of ${FAILURE_CLASSES.join(', ')}`;
+}
+
+/** What makes one entry invalid; an invalid entry is never quarantined and `check` refuses it. */
+export function entryProblems(id: string, e: QuarantineEntry, now: Date): string[] {
+  if (!e || typeof e !== 'object') return ['not an object'];
+  const p: string[] = [];
+  if (!parseTestId(id)) p.push('not a test id (<file>::<project>::<title>; gstack-flaky ids prints them)');
+  if (!filled(e.owner)) p.push('no owner');
+  if (!filled(e.ledger)) p.push('no ledger link');
+  if (!filled(e.reason)) p.push('no reason');
+  const cls = classRefusal(e.failureClass);
+  if (cls) p.push(cls);
+  if (!filledList(e.evidence)) p.push('no evidence');
+  if (!(Number.isInteger(e.suiteTests) && e.suiteTests > 0)) p.push('no suiteTests (add records the suite size from --junit)');
+  const entered = Date.parse(e.enteredAt);
+  const expires = Date.parse(e.expiresAt);
+  if (Number.isNaN(entered) || Number.isNaN(expires)) return [...p, 'enteredAt or expiresAt is not a date'];
+  if (entered > now.getTime() + DAY) p.push('enteredAt is in the future');
+  if (!Array.isArray(e.renewals)) return [...p, 'renewals is not a list'];
+  if (e.renewals.length > 1) p.push(`renewed ${e.renewals.length} times; one renewal is allowed, then fix the test or release it`);
+  const firstExpiry = e.renewals.length ? Date.parse(e.renewals[0]?.previousExpiresAt) : expires;
+  if (!(firstExpiry > entered)) p.push('expires before it entered');
+  if (firstExpiry - entered > MAX_DAYS * DAY) p.push(`expires more than ${MAX_DAYS} days after it entered`);
+  for (const r of e.renewals) {
+    if (!r || typeof r !== 'object') { p.push('a renewal is not an object'); continue; }
+    const renewed = Date.parse(r.renewedAt);
+    if (!(renewed >= entered && renewed <= now.getTime() + DAY)) p.push('a renewal is dated before the entry or in the future');
+    if (!filled(r?.owner)) p.push('a renewal names no owner');
+    if (!filledList(r?.evidence) || r.evidence.every(x => filledList(e.evidence) && e.evidence.includes(x))) p.push('a renewal carries no new evidence');
+    const from = Math.max(Date.parse(r?.renewedAt), Date.parse(r?.previousExpiresAt));
+    const until = Date.parse(r?.expiresAt);
+    if (Number.isNaN(from) || Number.isNaN(until) || until - from > RENEW_MAX_DAYS * DAY) p.push(`a renewal is not a date range of at most ${RENEW_MAX_DAYS} days`);
+  }
+  const last = e.renewals.at(-1);
+  if (last && last.expiresAt !== e.expiresAt) p.push('expiresAt differs from the last renewal');
+  return p;
+}
+
+export const isLive = (e: QuarantineEntry, now: Date) => Date.parse(e.expiresAt) > now.getTime();
+
+/** Ids `run` gives the quarantine budget, plus one notice per entry it ignores (expired or invalid). */
+export function liveQuarantine(reg: Registry, now: Date): { ids: Set<string>; notices: string[] } {
+  const ids = new Set<string>();
+  const notices: string[] = [];
+  for (const [id, e] of Object.entries(reg.entries)) {
+    const problems = entryProblems(id, e, now);
+    if (problems.length) notices.push(`FLAKY_QUARANTINE_IGNORED: ${safeText(id)} is not quarantined: ${problems.join('; ')}`);
+    else if (!isLive(e, now)) notices.push(expiredNotice(id, e));
+    else ids.add(id);
+  }
+  return { ids, notices };
+}
+
+const shq = (s: string) => "'" + s.split("'").join(`'"'"'`) + "'";
+export const renewCommand = (id: string) => `gstack-flaky quarantine renew ${shq(safeText(id))} --owner <you> --evidence <new evidence url>`;
+export const releaseCommand = (id: string) => `gstack-flaky quarantine release ${shq(safeText(id))} --reason <why> --pr <fix pr url>`;
+
+export function expiredNotice(id: string, e: QuarantineEntry): string {
+  return `FLAKY_QUARANTINE_EXPIRED: ${safeText(id)} expired ${e.expiresAt.slice(0, 10)} and is not quarantined; renew: ${renewCommand(id)} | release: ${releaseCommand(id)}`;
+}
+
+export interface AddInput { owner?: string; ledger?: string; failureClass?: string; reason?: string; evidence: string[]; days?: number; suiteIds: string[] }
+
+const refuse = (msg: string): never => { throw new QuarantineError('FLAKY_QUARANTINE_REFUSED', msg, 1); };
+
+export function addEntry(reg: Registry, id: string, a: AddInput, now: Date): QuarantineEntry {
+  const days = a.days ?? DEFAULT_DAYS;
+  if (!Number.isInteger(days) || days < 1 || days > MAX_DAYS) refuse(`--days must be a whole number from 1 to ${MAX_DAYS}, got ${a.days}`);
+  const cls = classRefusal(a.failureClass);
+  if (cls) refuse(cls);
+  if (!a.evidence.length) refuse('no evidence: pass --evidence <url> (a failing run, a ledger line) at least once');
+  if (!a.suiteIds.includes(id)) refuse(`${safeText(id)} is not a test in the --junit report (gstack-flaky ids --junit <file> prints the ids)`);
+  if (reg.entries[id]) refuse(`${safeText(id)} already has an entry; renew or release it`);
+  const live = Object.values(reg.entries).filter(e => isLive(e, now)).length;
+  const cap = suiteCap(a.suiteIds.length);
+  if (live + 1 > cap) refuse(`the registry holds ${live} live entries and the cap for a ${a.suiteIds.length}-test suite is ${cap}; fix or release one first`);
+  const entry: QuarantineEntry = {
+    owner: a.owner ?? '', ledger: a.ledger ?? '', failureClass: a.failureClass as FailureClass, reason: a.reason ?? '', evidence: a.evidence,
+    enteredAt: now.toISOString(), expiresAt: new Date(now.getTime() + days * DAY).toISOString(), renewals: [], suiteTests: a.suiteIds.length,
+  };
+  const problems = entryProblems(id, entry, now);
+  if (problems.length) refuse(problems.join('; '));
+  reg.entries[id] = entry;
+  return entry;
+}
+
+export function renewEntry(reg: Registry, id: string, r: { owner?: string; evidence: string[]; days?: number }, now: Date): QuarantineEntry {
+  const e = reg.entries[id] ?? refuse(`${safeText(id)} has no entry to renew`);
+  if (e.renewals.length) refuse(`${safeText(id)} was renewed once already; a second renewal is refused: fix the test or release it`);
+  if (!filled(r.owner)) refuse('renew names the owner again: pass --owner');
+  if (!r.evidence.some(x => filled(x) && !e.evidence.includes(x))) refuse('renew needs new evidence: pass --evidence <url> not already on the entry');
+  const days = r.days ?? RENEW_MAX_DAYS;
+  if (!Number.isInteger(days) || days < 1 || days > RENEW_MAX_DAYS) refuse(`a renewal is 1 to ${RENEW_MAX_DAYS} days, got ${r.days}`);
+  const from = Math.max(now.getTime(), Date.parse(e.expiresAt));
+  const expiresAt = new Date(from + days * DAY).toISOString();
+  e.renewals.push({ renewedAt: now.toISOString(), previousExpiresAt: e.expiresAt, expiresAt, owner: r.owner!, evidence: r.evidence });
+  e.expiresAt = expiresAt;
+  return e;
+}
+
+export function releaseEntry(reg: Registry, id: string, r: { reason?: string; pr?: string }, now: Date): ReleasedEntry {
+  const e = reg.entries[id] ?? refuse(`${safeText(id)} has no entry to release`);
+  if (!filled(r.reason) || !filled(r.pr)) refuse('release needs --reason and --pr (the fix, or the decision to stop quarantining)');
+  const record: ReleasedEntry = { id, ...e, releasedAt: now.toISOString(), reason: r.reason!, pr: r.pr! };
+  reg.released.push(record);
+  delete reg.entries[id];
+  return record;
+}
+
+const liveEntries = (reg: Registry, now: Date) => Object.values(reg.entries).filter(e => e && typeof e === 'object' && isLive(e, now));
+const smallestSuite = (live: QuarantineEntry[]) => Math.min(...live.map(e => e.suiteTests).filter(n => Number.isInteger(n) && n > 0));
+
+/** Structural problems of a whole registry plus the cap, for `check`. */
+export function registryProblems(reg: Registry, now: Date, suiteTests?: number): string[] {
+  const p: string[] = [];
+  for (const [id, e] of Object.entries(reg.entries)) for (const x of entryProblems(id, e, now)) p.push(`${safeText(id)}: ${x}`);
+  for (const r of reg.released) {
+    if (!r || !filled(r.id) || Number.isNaN(Date.parse(r.releasedAt)) || !filled(r.reason) || !filled(r.pr)) p.push(`released record ${JSON.stringify(r?.id)}: needs id, releasedAt, reason and pr`);
+  }
+  const live = liveEntries(reg, now);
+  const tests = suiteTests ?? smallestSuite(live);
+  if (live.length && Number.isFinite(tests) && live.length > suiteCap(tests)) p.push(`${live.length} live entries, over the cap of ${suiteCap(tests)} for a ${tests}-test suite`);
+  return p;
+}
+
+const editsFile = (changed: string[], file: string) => changed.some(f => f === file || f.endsWith(`/${file}`));
+
+/** What a change did to the registry that `check --base` refuses. */
+export function baseProblems(base: Registry, head: Registry, changed: string[]): string[] {
+  const p: string[] = [];
+  for (const [id, e] of Object.entries(head.entries)) {
+    const was = base.entries[id];
+    const t = parseTestId(id);
+    if (!was) {
+      if (t && editsFile(changed, t.file)) p.push(`${safeText(id)}: added in the same change that edits ${t.file}; a change cannot quarantine the test it touches (land the entry on its own, or fix the test)`);
+      continue;
+    }
+    if (was.enteredAt !== e?.enteredAt) p.push(`${safeText(id)}: enteredAt changed from ${was.enteredAt}; release the entry instead of restarting it`);
+    if (JSON.stringify((e?.renewals ?? []).slice(0, was.renewals.length)) !== JSON.stringify(was.renewals)) p.push(`${safeText(id)}: its renewal history was rewritten`);
+  }
+  for (const [id, was] of Object.entries(base.entries)) {
+    if (!(id in head.entries) && !head.released.some(r => r?.id === id && r.enteredAt === was.enteredAt)) p.push(`${safeText(id)}: removed without a release record (use: ${releaseCommand(id)})`);
+  }
+  for (const r of base.released) {
+    if (!head.released.some(h => h?.id === r.id && h.releasedAt === r.releasedAt)) p.push(`${safeText(r.id)}: its release record of ${r.releasedAt} was removed`);
+  }
+  return p;
+}
+
+/** `check`: the working-tree registry alone, and with `base` against what this change did since the merge base. */
+export function checkRegistry(cwd: string, o: { base?: string; suiteTests?: number }, now: Date): { problems: string[]; live: number; cap?: number } {
+  const head = readRegistry(cwd);
+  const problems = registryProblems(head, now, o.suiteTests);
+  if (o.base !== undefined) {
+    const root = repoRoot(cwd);
+    const commit = resolveCommit(o.base, root);
+    const mb = git(['merge-base', commit, 'HEAD'], root);
+    if (!mb.ok) throw new QuarantineError('FLAKY_QUARANTINE_BASE', `no merge base between ${o.base} and HEAD (a shallow clone?)`);
+    const changed = git(['-c', 'core.quotePath=false', 'diff', '--name-only', '-z', mb.out.trim()], root);
+    if (!changed.ok) throw new QuarantineError('FLAKY_QUARANTINE_BASE', `cannot diff against the merge base of ${o.base}`);
+    problems.push(...baseProblems(registryAt(mb.out.trim(), root, `the merge base of ${o.base}`), head, changed.out.split('\0').filter(Boolean)));
+  }
+  const live = liveEntries(head, now);
+  const tests = o.suiteTests ?? smallestSuite(live);
+  return { problems, live: live.length, ...(Number.isFinite(tests) ? { cap: suiteCap(tests) } : {}) };
+}
+
+export interface LedgerRecord { ts: string; kind: string; id: string; attempts?: string[] }
+
+/** Read every JSON line of the given ledger files, and of every .jsonl file under the given directories. */
+export function readLedgers(paths: string[]): { records: LedgerRecord[]; skipped: number } {
+  const files: string[] = [];
+  const walk = (p: string) => {
+    const st = fs.statSync(p, { throwIfNoEntry: false });
+    if (!st) throw new QuarantineError('FLAKY_QUARANTINE_USAGE', `--ledger ${p} does not exist`, 2);
+    if (!st.isDirectory()) { files.push(p); return; }
+    for (const n of fs.readdirSync(p).sort()) {
+      const c = path.join(p, n);
+      if (fs.statSync(c).isDirectory() || n.endsWith('.jsonl')) walk(c);
+    }
+  };
+  paths.forEach(walk);
+  const records: LedgerRecord[] = [];
+  let skipped = 0;
+  for (const f of files) {
+    for (const l of fs.readFileSync(f, 'utf-8').split('\n')) {
+      if (!l.trim()) continue;
+      try {
+        const r = JSON.parse(l) as LedgerRecord;
+        if (filled(r?.id) && filled(r.kind) && filled(r.ts)) records.push(r); else skipped++;
+      } catch { skipped++; }
+    }
+  }
+  return { records, skipped };
+}
+
+const cleanPass = (r: LedgerRecord) => r.kind === 'quarantined-pass' && !(r.attempts ?? []).includes('fail');
+const shortKind = (r: LedgerRecord) => cleanPass(r) ? 'pass' : r.kind === 'quarantined-pass' ? 'flaky' : r.kind === 'quarantined-fail' ? 'fail' : r.kind;
+
+/** `report`: expired entries first, then live entries soonest-expiring first, with ledger history when given. */
+export function reportLines(reg: Registry, now: Date, ledgers?: LedgerRecord[]): string[] {
+  const out: string[] = [];
+  const all = Object.entries(reg.entries).sort((a, b) => Date.parse(a[1].expiresAt) - Date.parse(b[1].expiresAt));
+  const expired = all.filter(([, e]) => !isLive(e, now));
+  const live = all.filter(([, e]) => isLive(e, now));
+  for (const [id, e] of expired) out.push(expiredNotice(id, e));
+  let expiring = 0, ready = 0;
+  for (const [id, e] of live) {
+    const daysLeft = Math.ceil((Date.parse(e.expiresAt) - now.getTime()) / DAY);
+    if (daysLeft <= 2) expiring++;
+    let history = '';
+    if (ledgers) {
+      const sid = safeText(id);
+      const mine = ledgers.filter(r => r.id === sid && Date.parse(r.ts) >= Date.parse(e.enteredAt)).sort((a, b) => Date.parse(a.ts) - Date.parse(b.ts));
+      let streak = 0;
+      for (let i = mine.length - 1; i >= 0 && cleanPass(mine[i]!); i--) streak++;
+      const isReady = streak >= EXIT_RULE_PASSES;
+      if (isReady) ready++;
+      history = ` recent=${mine.slice(-5).map(shortKind).join(',') || 'none'} clean_streak=${streak}${isReady ? ` READY_TO_RELEASE: ${releaseCommand(id)}` : ''}`;
+    }
+    const renewal = e.renewals.length ? 'renewed once; fix or release' : `renew: ${renewCommand(id)}`;
+    out.push(`QUARANTINE: ${safeText(id)} owner=${safeText(e.owner)} class=${e.failureClass} days_left=${daysLeft} expires=${e.expiresAt.slice(0, 10)} ledger=${safeText(e.ledger)}${history}${daysLeft <= 2 ? ` EXPIRING (${renewal})` : ''}`);
+  }
+  out.push(`QUARANTINE_REPORT: live=${live.length} expired=${expired.length} expiring=${expiring} ready=${ledgers ? ready : 'unchecked'} exit_rule=${ledgers ? `checked (${EXIT_RULE_PASSES} consecutive clean passes)` : 'not checked (no --ledger given)'}`);
+  return out;
+}
+
+export const QUARANTINE_USAGE = `Usage:
+  gstack-flaky quarantine add <id> --owner <who> --ledger <url> --class detector|harness|timing|model-latency
+                              --reason <text> --evidence <url> [--evidence <url>...] --junit <file> [--runner <r>] [--days <1-${MAX_DAYS}>]
+  gstack-flaky quarantine renew <id> --owner <who> --evidence <new url> [--days <1-${RENEW_MAX_DAYS}>]
+  gstack-flaky quarantine release <id> --reason <text> --pr <url>
+  gstack-flaky quarantine check [--base <ref>] [--junit <file>]
+  gstack-flaky quarantine report [--ledger <file|dir>...] [--base <ref>]
+
+add/renew/release edit ${REGISTRY_PATH} at the repository root. check validates it
+(owner, ledger, class, evidence, expiry, one renewal, the cap) and, with --base,
+refuses an entry added in the change that edits its test's file, an entry removed
+without a release record, and a removed release record. report lists expired and
+live entries, soonest-expiring first; with --ledger (files or directories of
+downloaded ledgers) it shows recent outcomes and marks entries with ${EXIT_RULE_PASSES}
+consecutive clean passes READY_TO_RELEASE.
+Exit: 0 ok, 1 refused, 2 usage, 3 unreadable registry or base.
+`;
+
+interface CliIO { cwd: string; out: (s: string) => void; now: Date }
+
+const usage = (msg: string): never => { throw new QuarantineError('FLAKY_QUARANTINE_USAGE', msg, 2); };
+
+function parseArgs(argv: string[]) {
+  const flags: Record<string, string[]> = {};
+  const positional: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (!a.startsWith('--')) { positional.push(a); continue; }
+    const v = argv[++i];
+    if (v === undefined) usage(`${a} needs a value`);
+    (flags[a.slice(2)] ??= []).push(v!);
+  }
+  return { flags, positional };
+}
+
+function intFlag(v: string | undefined, name: string): number | undefined {
+  if (v === undefined) return undefined;
+  const n = Number(v);
+  if (!Number.isInteger(n)) usage(`--${name} must be a whole number`);
+  return n;
+}
+
+const ALLOWED: Record<string, string[]> = {
+  add: ['owner', 'ledger', 'class', 'reason', 'evidence', 'junit', 'runner', 'days'], renew: ['owner', 'evidence', 'days'],
+  release: ['reason', 'pr'], check: ['base', 'junit', 'runner'], report: ['ledger', 'base'],
+};
+
+/** The `gstack-flaky quarantine` subcommands; returns the exit code. A JunitError from --junit propagates to the bin. */
+export function quarantineMain(argv: string[], io: CliIO): number {
+  const [sub, ...rest] = argv;
+  if (!sub || sub === '--help' || sub === '-h') { io.out(QUARANTINE_USAGE); return sub ? 0 : 2; }
+  if (!ALLOWED[sub]) usage(`unknown quarantine command ${sub}\n${QUARANTINE_USAGE}`);
+  const { flags, positional } = parseArgs(rest);
+  const unknown = Object.keys(flags).find(f => !ALLOWED[sub]!.includes(f));
+  if (unknown) usage(`${sub} does not take --${unknown}`);
+  const one = (f: string) => flags[f]?.at(-1);
+  const runner = one('runner') as JunitRunner | undefined;
+  if (runner !== undefined && !['playwright', 'bun', 'generic'].includes(runner)) usage('--runner must be playwright, bun or generic');
+  const needsId = sub === 'add' || sub === 'renew' || sub === 'release';
+  if (needsId !== (positional.length === 1) || positional.length > 1) usage(needsId ? `${sub} takes one test id` : `${sub} takes no test id`);
+  if (sub === 'check') {
+    const junit = one('junit');
+    const r = checkRegistry(io.cwd, { base: one('base'), suiteTests: junit ? readJunit(junit, runner).tests.length : undefined }, io.now);
+    for (const p of r.problems) io.out(`QUARANTINE_REFUSED: ${p}\n`);
+    io.out(`QUARANTINE_CHECK: live=${r.live} cap=${r.cap ?? 'none'} base=${one('base') ?? 'none'} verdict=${r.problems.length ? 'fail' : 'pass'}\n`);
+    return r.problems.length ? 1 : 0;
+  }
+  if (sub === 'report') {
+    const ledgers = flags.ledger ? readLedgers(flags.ledger) : undefined;
+    if (ledgers?.skipped) io.out(`QUARANTINE_LEDGER: skipped ${ledgers.skipped} unreadable line(s)\n`);
+    for (const l of reportLines(readRegistry(io.cwd, one('base')), io.now, ledgers?.records)) io.out(`${l}\n`);
+    return 0;
+  }
+  const id = positional[0]!;
+  const reg = readRegistry(io.cwd);
+  let line: string;
+  if (sub === 'add') {
+    const junit = one('junit') ?? refuse('add needs --junit <file> to count the suite and confirm the id exists');
+    const suiteIds = readJunit(junit, runner).tests.map(t => t.id);
+    const e = addEntry(reg, id, { owner: one('owner'), ledger: one('ledger'), failureClass: one('class'), reason: one('reason'), evidence: flags.evidence ?? [], days: intFlag(one('days'), 'days'), suiteIds }, io.now);
+    line = `QUARANTINE_ADDED: ${safeText(id)} owner=${safeText(e.owner)} class=${e.failureClass} expires=${e.expiresAt}`;
+  } else if (sub === 'renew') {
+    const e = renewEntry(reg, id, { owner: one('owner'), evidence: flags.evidence ?? [], days: intFlag(one('days'), 'days') }, io.now);
+    line = `QUARANTINE_RENEWED: ${safeText(id)} owner=${safeText(e.renewals[0]!.owner)} expires=${e.expiresAt} (no further renewal)`;
+  } else {
+    const r = releaseEntry(reg, id, { reason: one('reason'), pr: one('pr') }, io.now);
+    line = `QUARANTINE_RELEASED: ${safeText(id)} pr=${safeText(r.pr)}`;
+  }
+  writeRegistry(io.cwd, reg);
+  io.out(`${line} registry=${REGISTRY_PATH}\n`);
+  return 0;
+}

lib/review-depth.ts

@@ -20,7 +20,7 @@ export type PathClass = 'docs' | 'tests' | 'code';
 export type Depth = 'light' | 'standard' | 'full';
 export type Effort = 'light' | 'medium' | 'full' | 'host';
 export type Role = 'specialist' | 'red-team' | 'adversarial-native' | 'outside-voice' | 'fix-check' | 'targeted';
-export type Step = 'full' | 'scoped' | 'fix-check' | 'done' | 'stop';
+export type Step = 'full' | 'scoped' | 'fix-check' | 'voices' | 'done' | 'stop';
 
 export const SPECIALISTS = ['testing', 'maintainability', 'security', 'performance', 'data-migration', 'api-contract', 'design', 'simplification', 'state-machines'] as const;
 export type Specialist = (typeof SPECIALISTS)[number];
@@ -338,6 +338,12 @@ export interface History {
   /** Runtime lines of the fix range (RANGE_BASE..HEAD) as classifyDiff counts them, 0 when it touches none; undefined or null when the range was not read. */
   rangeRuntimeLines?: number | null;
   pass1Depth?: Depth;
+  /** The diff is gate class (planReview sets it): Step 11's voices run before any stop. */
+  gate?: boolean;
+  /** Step 11's native adversarial pass already ran (planReview sets it from PlanInput.adversarialRan). */
+  adversarialRan?: boolean;
+  /** The approval id of the owner's recorded grant of one scoped fix-check after round 2 (review_loop_exception). */
+  granted?: string;
 }
 export interface NextStep { step: Step; reason: string }
 
@@ -349,8 +355,19 @@ export interface NextStep { step: Step; reason: string }
  * changes no runtime lines; two rounds is the cap (R51: a scoped pass or a fix-check is
  * one): after round 2, below-floor fixes finish with notes, and a blocker open or fixed
  * there, or a gate-class edit there, stops for the owner, whose grant may add one scoped fix-check.
+ * The cap limits fix rounds, not Step 11's voices: on gate class any stop waits for them (GST-967),
+ * and the owner's recorded grant (`granted`) turns the stop after a round-2 full pass with a fixed finding into its
+ * one fix-check; a fix-check never earns another, so the grant cannot repeat.
  */
 export function nextStep(h: History, depth?: Depth): NextStep {
+  const n = loopStep(h, depth);
+  if (n.step !== 'stop') return n;
+  if (h.gate && !h.adversarialRan) return { step: 'voices', reason: `gate class: Step 11's voices (adversarial, outside, targeted) run before the owner's exit, then ask again with --adversarial-ran (${n.reason})` };
+  if (h.granted && !h.blockingOpen && h.last === 'full' && h.fullPasses === FULL_PASS_CAP) return { step: 'fix-check', reason: `the owner's grant ${h.granted} adds one scoped fix-check after round ${FULL_PASS_CAP} (review_loop_exception), never a fourth round` };
+  return n;
+}
+
+function loopStep(h: History, depth?: Depth): NextStep {
   if (h.last === 'none') return { step: 'full', reason: 'pass 1 reviews the whole diff' };
   const fixed = !!(h.fixedBlocking || h.fixedBelow);
   if (h.last === 'fix-check') return h.blockingOpen || h.fixedBlocking || h.touchedGate ? { step: 'stop', reason: `the fix-check ${h.touchedGate && !h.blockingOpen && !h.fixedBlocking ? 'edited a gate-class path' : 'found a blocking finding'}: name it for the owner, whose grant may add one scoped fix-check, never a third round` } : { step: 'done', reason: fixed ? 'round cap 2 reached: the below-floor fixes ship as notes in the PR body and receipt' : 'the fix-check found nothing blocking' };
@@ -475,7 +492,7 @@ export function planReview(i: PlanInput): ReviewPlan {
   const c = classifyDiff(i);
   const depth = decideDepth(c, c.runtimeLines ?? (CLASS_RANK[c.class] >= CLASS_RANK.code ? i.diffLines : 0), i.floor);
   const { class: cls, runtimeLines } = depth;
-  const next = nextStep(i.history, depth.depth);
+  const next = nextStep({ ...i.history, gate: cls === 'gate', adversarialRan: !!i.adversarialRan }, depth.depth);
   const h = i.history;
   const raise = depth.depth === 'light' && (h.fixedBlocking || h.blockingOpen || i.criticalFound);
   const stepDepth: Depth = raise ? 'standard' : depth.depth;
@@ -535,8 +552,11 @@ export function planReview(i: PlanInput): ReviewPlan {
   } else if (next.step === 'fix-check') {
     add('fix-check', 'fix-check', 'full');
     if (numbersChanged) add('outside-voice', 'outside-voice (numbers changed)', 'host');
+  } else if (next.step === 'voices') {
+    add('adversarial-native', 'adversarial', 'full');
+    add('outside-voice', 'outside-voice', 'host');
   }
-  if (i.targeted?.classes.length && ['full', 'scoped', 'fix-check'].includes(next.step)) {
+  if (i.targeted?.classes.length && ['full', 'scoped', 'fix-check', 'voices'].includes(next.step)) {
     if (i.targeted.ran) skipped.push('targeted (already read this product patch)');
     else add('targeted', 'targeted', ROLE_EFFORT.targeted);
   }

lib/ship-receipt-prose.ts

@@ -7,6 +7,7 @@
  */
 import { APPROVALS_FOOTER_END, APPROVALS_TABLE_HEADER } from './approval-record';
 import { RECEIPT_FENCE } from './ship-receipt';
+import { parseReviewLoopException, reviewLoopExceptionLine } from './ship-receipt-depth';
 
 export interface ProseClaim { field: string; prose: number; receipt: number }
 export interface ProseCheck { checked: number; mismatches: ProseClaim[] }
@@ -65,9 +66,24 @@ function withoutApprovalsBlocks(body: string): string {
   return out.join('');
 }
 
+/**
+ * The body without the `Review-loop exception: …` line the receipt's own exception requires (GST-977): write and the
+ * receipt check want it word for word, and it quotes the owner's reason (`outside 1 and 2 skip detector`), not this
+ * PR's counters. Only a line whose trimmed text is that rendered line, the test write applies, is left out (a fenced
+ * copy too, as write accepts one); the same words inside a longer line stay prose. A marker line takes its place so
+ * the text on either side never joins into a claim.
+ */
+function withoutExceptionLine(body: string, exception: unknown): string {
+  if (exception === undefined) return body;
+  const parsed = parseReviewLoopException(exception);
+  if (!parsed.ok) return body;
+  const line = reviewLoopExceptionLine(parsed.exception);
+  return body.split(/(?<=\n)/).map(l => (l.trim() === line ? '(review-loop exception line)\n' : l)).join('');
+}
+
 /**
  * Every `<name>=<n>`, `<name>: <n>` and `<n> <name>` in the prose (the body
- * without its receipt block and its rendered Approvals block), where `<name>` is a counter's leaf key with `_`
+ * without its receipt block, its rendered Approvals block and its review-loop exception line), where `<name>` is a counter's leaf key with `_`
  * matched as `_`, space or `-` and not part of a longer word (`3 pass-through`
  * is not a `pass` claim), compared with the receipt. A leaf key shared by
  * several counters (`pass` under every gate lane, `passed` under gate and ci)
@@ -77,7 +93,7 @@ function withoutApprovalsBlocks(body: string): string {
  * `<n> <name>` claim about the next key (#3513).
  */
 export function checkReceiptProse(receipt: Record<string, unknown>, body: string): ProseCheck {
-  const prose = withoutApprovalsBlocks(body.replace(BLOCK_RE, ''));
+  const prose = withoutExceptionLine(withoutApprovalsBlocks(body.replace(BLOCK_RE, '')), receipt.review_loop_exception);
   const byLeaf = new Map<string, Array<{ field: string; value: number }>>();
   for (const [field, value] of receiptCounters(receipt)) {
     const leaf = field.split('.').at(-1)!;