harnery 0.37.0 → 0.38.0

package/src/lib/browser/qa-run.ts

@@ -11,32 +11,126 @@
 //
 // Toolkit tier: this module must not import src/core (layering check).
 
-import { execFile } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { cpus, freemem, loadavg, totalmem } from "node:os";
+import { basename, join } from "node:path";
+import { type CritiqueProvider, DEFAULT_CRITIQUE_RUBRIC } from "./critique.js";
+import { type JudgedContext, judgePageReviewPack, toCritiqueRecords } from "./page-review-judge.js";
+import {
+  finalizePageReviewPack,
+  gateHitsFromEnvelope,
+  PAGE_REVIEW_DEFAULT_RETENTION_MINUTES,
+  PAGE_REVIEW_FINDINGS_FILENAME,
+  PAGE_REVIEW_PACK_DIRNAME,
+  PAGE_REVIEW_PACK_SCHEMA,
+  PAGE_REVIEW_REVIEW_FILENAME,
+  type PageReviewContextRecord,
+  type PageReviewCritiqueRecord,
+  type PageReviewGateRecord,
+  readPackContext,
+  readPackDom,
+  readPackFullPage,
+  readPackManifest,
+  readPackSignature,
+} from "./page-review-pack.js";
 import type { QaManifest } from "./qa-plan.js";
+import { type PersistedCritique, QA_CRITIQUE_CONTRACT_VERSION, rubricDigest } from "./qa-reuse.js";
 import {
+  computeJobDigest,
   computeVerdict,
   mergeCoverage,
   QA_RUN_RESULT_SCHEMA_VERSION,
+  QA_RUN_STATUS_SCHEMA_VERSION,
   type QaRunBlocker,
   type QaRunCommandOutcome,
   type QaRunContext,
+  type QaRunCritiqueLatency,
   type QaRunCritiqueOutcome,
+  type QaRunCritiquePool,
+  type QaRunHostSample,
   type QaRunJob,
   type QaRunResult,
+  type QaRunReviewPack,
+  type QaRunStage,
+  type QaRunStatusDocument,
+  type QaRunStatusState,
 } from "./qa-run-contracts.js";
+import { type QaSnapshotStoreOptions, saveQaSnapshot } from "./qa-snapshot.js";
 
-/** Set on critique children unless the job permits metered critique: the
- * host's critique provider must stay on subscription-backed headless
- * harnesses and surface exhaustion instead of falling back to a metered API. */
+/** Set on the runner's own environment before the host's critique provider is
+ * loaded for the judge stage, unless the job permits metered critique: the
+ * provider must stay on subscription-backed headless harnesses and surface
+ * exhaustion instead of falling back to a metered API. */
 export const QA_RUN_HEADLESS_ONLY_ENV = "HARNERY_CRITIQUE_HEADLESS_ONLY";
 
 /** Result document written into the run's output directory. */
 export const QA_RUN_RESULT_FILENAME = "page-qa-result.json";
 
+/** Pointer document written into the parent output directory after every
+ * run, naming the newest run's directory and verdict. Consumers resolve the
+ * current result through this pointer instead of guessing at loose files. */
+export const QA_RUN_LATEST_FILENAME = "latest.json";
+
+export interface QaRunLatestPointerInput {
+  run_id: string;
+  dir: string;
+  completed_at: string;
+  verdict: QaRunResult["verdict"];
+}
+
+/**
+ * Publish the parent directory's latest-result pointer without allowing an
+ * older completion to replace a newer one. Both runner and manual evidence
+ * use this writer so every producer preserves the same ordering invariant.
+ */
+export function writeLatestPointer(outParent: string, input: QaRunLatestPointerInput): string {
+  const pointerPath = join(outParent, QA_RUN_LATEST_FILENAME);
+  let pointerIsNewer = true;
+  try {
+    const existing = JSON.parse(readFileSync(pointerPath, "utf8")) as {
+      completed_at?: unknown;
+    };
+    if (typeof existing.completed_at === "string") {
+      const existingCompletedAt = Date.parse(existing.completed_at);
+      const candidateCompletedAt = Date.parse(input.completed_at);
+      pointerIsNewer =
+        Number.isNaN(existingCompletedAt) || candidateCompletedAt >= existingCompletedAt;
+    }
+  } catch {
+    // No readable pointer yet: this result becomes the first one.
+  }
+
+  if (pointerIsNewer) {
+    const pointer = {
+      schema_version: 1,
+      ...input,
+      result: join(input.dir, QA_RUN_RESULT_FILENAME),
+    };
+    const pointerTmp = join(outParent, `.${QA_RUN_LATEST_FILENAME}.${input.run_id}.tmp`);
+    writeFileSync(pointerTmp, `${JSON.stringify(pointer, null, 2)}\n`);
+    renameSync(pointerTmp, pointerPath);
+  }
+  return pointerPath;
+}
+
+/** Live status document beside the result (QaRunStatusDocument): written at
+ * start, every stage boundary, and on a heartbeat timer, so a disconnected
+ * client can tell a running job from a dead one without guessing. */
+export const QA_RUN_STATUS_FILENAME = "run-status.json";
+
+/** The effective validated job, written into the run directory so a
+ * reconnecting client can re-derive the job digest (`qa-verify --job`). */
+export const QA_RUN_JOB_FILENAME = "job.json";
+
+const STATUS_HEARTBEAT_MS = 15_000;
+
 const DEFAULT_COMMAND_TIMEOUT_MS = 120_000;
+const DEFAULT_RUN_DEADLINE_MS = 900_000;
 const DEFAULT_COMMAND_CONCURRENCY = 2;
+/** Gate-hit rectangles forwarded to one context's capture child (`--review-pack-hit-rect`). */
+const REVIEW_PACK_HIT_RECTS_PER_CONTEXT = 50;
 const EXEC_MAX_BUFFER = 16 * 1024 * 1024;
 
 /** The planner's deterministic vocabulary is an executable contract, not a
@@ -70,8 +164,31 @@ export interface QaRunExecResult {
 /** Injectable child-process executor. `argv[0]` is the executable. */
 export type QaRunExec = (argv: string[], options: QaRunExecOptions) => Promise<QaRunExecResult>;
 
-/** Default executor: execFile with argv arrays only (never a shell string),
- * closed stdin, bounded output buffers, and the policy timeout. */
+/** Grace between the timeout's SIGTERM and the follow-up SIGKILL. A child
+ * that catches SIGTERM (Bun installs a handler by default) gets this long to
+ * exit before the kill is made non-negotiable. */
+export const QA_RUN_KILL_GRACE_MS = 5_000;
+
+/** After the group SIGKILL, how long to wait for stdio to drain before
+ * destroying the streams and settling anyway. An escaped grandchild (setsid)
+ * can hold the pipes open forever; the result must not wait on it. */
+const KILL_DRAIN_MS = 2_000;
+
+/** Default executor: spawn with argv arrays only (never a shell string),
+ * closed stdin, bounded output buffers, and the policy timeout.
+ *
+ * Timeout enforcement is escalated and group-wide, via `spawn` rather than
+ * `execFile` for two live-verified reasons. First, a child that catches
+ * SIGTERM while awaiting its own grandchildren turns a single polite kill
+ * into an unbounded wait (a critique command outlived its 120s cap by 10x).
+ * Second, `execFile` resolves only when the child's stdio closes, and an
+ * orphaned grandchild inheriting the pipe keeps it open after the child is
+ * dead — so even a delivered kill did not settle the call. The child is
+ * therefore spawned detached into its own process group; at the deadline the
+ * whole group gets SIGTERM, then SIGKILL after a grace, and the result
+ * settles on exit with whatever output drained, never waiting on a pipe an
+ * orphan still holds. A timed-out command reports an error even if the child
+ * then exits 0 — a result produced after the deadline cannot be trusted. */
 export const defaultQaRunExec: QaRunExec = (argv, options) =>
   new Promise((resolvePromise) => {
     const [command, ...args] = argv;
@@ -79,47 +196,122 @@ export const defaultQaRunExec: QaRunExec = (argv, options) =>
       resolvePromise({ exitCode: null, stdout: "", stderr: "", error: "empty argv" });
       return;
     }
-    const child = execFile(
-      command,
-      args,
-      {
-        timeout: options.timeoutMs,
-        maxBuffer: EXEC_MAX_BUFFER,
-        env: options.env,
-        killSignal: "SIGTERM",
-      },
-      (err, stdout, stderr) => {
-        const out = String(stdout ?? "");
-        const errOut = String(stderr ?? "");
-        if (!err) {
-          resolvePromise({ exitCode: 0, stdout: out, stderr: errOut });
-          return;
-        }
-        const failure = err as NodeJS.ErrnoException & {
-          code?: number | string;
-          killed?: boolean;
-          signal?: NodeJS.Signals | null;
-        };
-        if (typeof failure.code === "number") {
-          // Completed with a nonzero exit code: a real outcome, not an error.
-          resolvePromise({ exitCode: failure.code, stdout: out, stderr: errOut });
+    // Windows has no process groups; the direct-child kill is the best
+    // available fallback there.
+    const groupKill = process.platform !== "win32";
+    const child = spawn(command, args, {
+      env: options.env,
+      stdio: ["ignore", "pipe", "pipe"],
+      ...(groupKill ? { detached: true } : {}),
+    });
+
+    let stdout = "";
+    let stderr = "";
+    let outBytes = 0;
+    let timedOut = false;
+    let overflowed = false;
+    let settled = false;
+    let termTimer: ReturnType<typeof setTimeout> | undefined;
+    let killTimer: ReturnType<typeof setTimeout> | undefined;
+    let drainTimer: ReturnType<typeof setTimeout> | undefined;
+
+    const settle = (result: QaRunExecResult): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(termTimer);
+      clearTimeout(killTimer);
+      clearTimeout(drainTimer);
+      resolvePromise(result);
+    };
+
+    const signalGroup = (signal: NodeJS.Signals): void => {
+      const pid = child.pid;
+      if (!pid) return;
+      if (groupKill) {
+        try {
+          process.kill(-pid, signal);
           return;
+        } catch {
+          // Group already gone, or the leader died before setpgid: fall
+          // through to the direct child so the kill still lands somewhere.
         }
-        const reason =
-          failure.killed || failure.signal
-            ? `killed by ${failure.signal ?? "signal"} (timeout ${options.timeoutMs}ms)`
-            : failure.message || "spawn failed";
-        resolvePromise({ exitCode: null, stdout: out, stderr: errOut, error: reason });
-      },
-    );
-    child.stdin?.end();
+      }
+      try {
+        child.kill(signal);
+      } catch {
+        // Nothing left to kill.
+      }
+    };
+
+    const collect = (chunk: Buffer | string, sink: "stdout" | "stderr"): void => {
+      const text = String(chunk);
+      outBytes += text.length;
+      if (sink === "stdout") stdout += text;
+      else stderr += text;
+      if (outBytes > EXEC_MAX_BUFFER && !overflowed) {
+        overflowed = true;
+        signalGroup("SIGKILL");
+      }
+    };
+    child.stdout?.on("data", (chunk) => collect(chunk, "stdout"));
+    child.stderr?.on("data", (chunk) => collect(chunk, "stderr"));
+
+    child.on("error", (err) => {
+      settle({ exitCode: null, stdout, stderr, error: err.message || "spawn failed" });
+    });
+
+    const finish = (code: number | null, signal: NodeJS.Signals | null): void => {
+      if (timedOut) {
+        settle({
+          exitCode: null,
+          stdout,
+          stderr,
+          error: `timed out after ${options.timeoutMs}ms (process group killed)`,
+        });
+      } else if (overflowed) {
+        settle({
+          exitCode: null,
+          stdout,
+          stderr,
+          error: `output exceeded ${EXEC_MAX_BUFFER} bytes (process group killed)`,
+        });
+      } else if (signal) {
+        settle({ exitCode: null, stdout, stderr, error: `killed by ${signal}` });
+      } else {
+        settle({ exitCode: code, stdout, stderr });
+      }
+    };
+
+    // "close" is the clean path: process exited AND stdio drained. "exit"
+    // arms the drain failsafe so an orphan holding the pipes cannot postpone
+    // the result forever.
+    child.on("close", (code, signal) => finish(code, signal));
+    child.on("exit", (code, signal) => {
+      drainTimer = setTimeout(() => {
+        child.stdout?.destroy();
+        child.stderr?.destroy();
+        finish(code, signal);
+      }, KILL_DRAIN_MS);
+      drainTimer.unref?.();
+    });
+
+    termTimer = setTimeout(() => {
+      timedOut = true;
+      signalGroup("SIGTERM");
+    }, options.timeoutMs);
+    killTimer = setTimeout(() => signalGroup("SIGKILL"), options.timeoutMs + QA_RUN_KILL_GRACE_MS);
+    termTimer.unref?.();
+    killTimer.unref?.();
   });
 
 export interface QaRunMatrixOptions {
   /** A validated job (see validateQaRunJob — the runner trusts its shape). */
   job: QaRunJob;
-  /** Directory for artifacts and the result document. Created if missing. */
-  outDir: string;
+  /** PARENT directory for run output. Every invocation creates its own
+   * `run-<run_id>/` beneath it for artifacts and the result document, and
+   * maintains `latest.json` in the parent — a reused parent can therefore
+   * never present an older run's result as the current one. */
+  outParent: string;
   /** argv prefix that reaches the host CLI's browse command, e.g.
    * `[process.execPath, cliScript, "browse"]`. */
   browseArgv: string[];
@@ -129,6 +321,41 @@ export interface QaRunMatrixOptions {
   childEnv?: NodeJS.ProcessEnv;
   /** Progress callback for human-facing per-stage lines. */
   onLog?: (message: string) => void;
+  /** Run ID override (tests). Default: crypto.randomUUID(). */
+  runId?: string;
+  /** Working-tree revision probe supplied by the caller (the CLI probes git
+   * once). Ignored when the job itself pins tested_revision. */
+  revisionProbe?: { tested_revision?: string; worktree_dirty?: boolean };
+  /** Machine-wide admission gate. When present the runner acquires a slot
+   * before any browser work, records the wait as wall_time_ms.queue (never
+   * part of total), and finalizes an incomplete result with an "admission"
+   * blocker when acquisition fails — the evidence trail survives a full
+   * queue. The returned function releases the slot; the runner calls it at
+   * finalize, and a crashed runner's slot is reclaimed by dead-PID pruning. */
+  admission?: {
+    resource: string;
+    acquire: (onWait: (message: string) => void) => Promise<() => void>;
+    /** Snapshot of the other holders of the resource, sampled alongside host
+     * pressure so an incomplete run names what it was competing with. */
+    holders?: () => Array<{ label: string; pid: number }>;
+  };
+  /** Host-injected vision call for the judge stage. The judge runs in this
+   * process over the pack on disk, after every capture browser has closed. */
+  critiqueProvider?: CritiqueProvider;
+  /** Lazy alternative to `critiqueProvider`; called once, after the
+   * headless-only environment has been applied. */
+  critiqueProviderLoader?: () => Promise<CritiqueProvider | undefined>;
+  /** QA snapshot store override (tests, host-managed cache locations). */
+  snapshotStore?: QaSnapshotStoreOptions;
+  /** Renders the command a reader can run to judge the pack later; shown in
+   * the pack's review.md when the judge did not run. */
+  reviewPackJudgeCommand?: (packDir: string) => string;
+  /** True when the run writes into the managed artifact store: the pack's
+   * manifest then says `managed: true` and the expiry sweep may delete it
+   * once `policy.review_pack_retention_minutes` (default 90) have passed
+   * since the judge finished. A pack under an explicit out dir stays
+   * unmanaged and is never deleted automatically. */
+  reviewPackManaged?: boolean;
 }
 
 interface TimedExec {
@@ -264,49 +491,190 @@ function parseConsoleFailures(envelope: Record<string, unknown> | undefined): st
   return failures;
 }
 
-interface EnvelopeCritique {
-  tiles?: number;
-  provider?: boolean;
-  outcome?: string;
-  findings?: Array<{ severity?: string; category?: string; description?: string }>;
-  provider_meta?: Record<string, unknown>;
-  error?: string;
-}
-
-function providerLabel(critique: EnvelopeCritique | undefined): string {
-  const meta = critique?.provider_meta;
-  if (meta) {
-    for (const key of ["provider", "route", "model"]) {
-      const value = meta[key];
-      if (typeof value === "string" && value.length > 0) return value;
-    }
+/**
+ * Lift per-backend vision latency out of the envelope's provider_meta. The
+ * shape is host-owned (`providers[name].latency_ms = {count, p50, p95}`), so
+ * read defensively: a malformed entry or one with zero calls is dropped.
+ * Without this the runner kept only the provider label, and a slow tile was
+ * visible in `ps` and nowhere in the result document.
+ */
+function critiqueLatency(
+  providerMeta: Record<string, unknown> | undefined,
+): Record<string, QaRunCritiqueLatency> | undefined {
+  const providers = providerMeta?.providers;
+  if (!providers || typeof providers !== "object" || Array.isArray(providers)) return undefined;
+  const out: Record<string, QaRunCritiqueLatency> = {};
+  for (const [name, state] of Object.entries(providers as Record<string, unknown>)) {
+    const lat = (state as { latency_ms?: unknown } | null)?.latency_ms as
+      | { count?: unknown; p50?: unknown; p95?: unknown }
+      | undefined;
+    if (!lat || typeof lat !== "object") continue;
+    const { count, p50, p95 } = lat;
+    if (typeof count !== "number" || count <= 0) continue;
+    if (typeof p50 !== "number" || typeof p95 !== "number") continue;
+    out[name] = { count, p50, p95 };
   }
-  return critique?.provider ? "host" : "none";
+  return Object.keys(out).length > 0 ? out : undefined;
 }
 
 /**
  * Execute the whole QA matrix for one validated job and return the result
  * (also written to `<outDir>/page-qa-result.json`). Stages: plan →
- * deterministic gates (bounded pool) → interactions (serial) → critique (one
- * context at a time; the critique provider owns tile concurrency) → snapshot.
- * The verdict is computeVerdict over everything recorded — fail-closed.
+ * deterministic gates (bounded pool) → interactions (serial) → capture (each
+ * context rendered once into the run's page review pack through the same
+ * pool, browser closed) → critique (one in-process pool of vision calls over
+ * every tile of every context, no browser open) → snapshot (persisted from
+ * the pack's files in signoff). The verdict is computeVerdict over
+ * everything recorded — fail-closed.
  */
 export async function runQaMatrix(options: QaRunMatrixOptions): Promise<QaRunResult> {
-  const { job, outDir, browseArgv } = options;
+  const { job, outParent, browseArgv } = options;
   const exec = options.exec ?? defaultQaRunExec;
   const log = options.onLog ?? (() => {});
   const timeoutMs = job.policy?.command_timeout_ms ?? DEFAULT_COMMAND_TIMEOUT_MS;
   const concurrency = job.policy?.command_concurrency ?? DEFAULT_COMMAND_CONCURRENCY;
+
+  const hostSample = (): QaRunHostSample => {
+    const holders = options.admission?.holders?.() ?? undefined;
+    return {
+      captured_at: new Date().toISOString(),
+      loadavg_1m: loadavg()[0] ?? 0,
+      free_mem_bytes: freemem(),
+      total_mem_bytes: totalmem(),
+      cpu_count: cpus().length,
+      // Exclude this run itself: a holder list that names the sampler tells
+      // the reader nothing about contention.
+      ...(holders ? { competing: holders.filter((holder) => holder.pid !== process.pid) } : {}),
+    };
+  };
+  const stageHostSamples: Partial<Record<QaRunStage, QaRunHostSample>> = {};
+
+  const runId = options.runId ?? randomUUID();
+  const outDir = join(outParent, `run-${runId}`);
   mkdirSync(outDir, { recursive: true });
+  const startedAtIso = new Date().toISOString();
+  writeFileSync(join(outDir, QA_RUN_JOB_FILENAME), `${JSON.stringify(job, null, 2)}\n`);
 
+  // Live status: state + stage + heartbeat, written atomically so a client
+  // that lost its terminal can distinguish this run being alive from dead.
+  let statusState: QaRunStatusState = "running";
+  let statusStage: QaRunStage | null = null;
+  let statusQueue: QaRunStatusDocument["queue"];
+  let statusVerdict: QaRunStatusDocument["verdict"];
+  const writeStatus = (): void => {
+    const status: QaRunStatusDocument = {
+      schema_version: QA_RUN_STATUS_SCHEMA_VERSION,
+      run_id: runId,
+      pid: process.pid,
+      state: statusState,
+      stage: statusStage,
+      started_at: startedAtIso,
+      updated_at: new Date().toISOString(),
+      ...(statusQueue ? { queue: statusQueue } : {}),
+      ...(statusVerdict ? { verdict: statusVerdict } : {}),
+    };
+    try {
+      const tmp = join(outDir, `.${QA_RUN_STATUS_FILENAME}.tmp`);
+      writeFileSync(tmp, `${JSON.stringify(status, null, 2)}\n`);
+      renameSync(tmp, join(outDir, QA_RUN_STATUS_FILENAME));
+    } catch {
+      // Status is advisory; the result document is the authoritative record.
+    }
+  };
+  const heartbeat = setInterval(writeStatus, STATUS_HEARTBEAT_MS);
+  heartbeat.unref();
+
+  /** Enter a stage: record the host pressure it starts under and refresh the
+   * live status document in one place. */
+  const enterStage = (stage: QaRunStage): void => {
+    statusStage = stage;
+    stageHostSamples[stage] = hostSample();
+    writeStatus();
+  };
+
+  const revision: Pick<
+    QaRunResult["run"],
+    "tested_revision" | "revision_source" | "worktree_dirty"
+  > =
+    job.tested_revision !== undefined
+      ? { tested_revision: job.tested_revision, revision_source: "job" }
+      : options.revisionProbe?.tested_revision !== undefined
+        ? {
+            tested_revision: options.revisionProbe.tested_revision,
+            revision_source: "git",
+            ...(options.revisionProbe.worktree_dirty !== undefined
+              ? { worktree_dirty: options.revisionProbe.worktree_dirty }
+              : {}),
+          }
+        : { revision_source: "unknown" };
+  const jobDigest = computeJobDigest(job);
+  const wall: QaRunResult["wall_time_ms"] = {
+    plan: 0,
+    gates: 0,
+    interactions: 0,
+    capture: 0,
+    critique: 0,
+    snapshot: 0,
+    total: 0,
+  };
+
+  // ------------------------------------------------------------- admission
+  // Queue wait happens before the runner clock starts: wall_time_ms.total
+  // stays pure runner time and the wait is reported as wall_time_ms.queue.
+  let releaseAdmission: (() => void) | undefined;
+  let admissionFailure: string | undefined;
+  if (options.admission) {
+    statusState = "queued";
+    statusQueue = {
+      resource: options.admission.resource,
+      waiting_since: new Date().toISOString(),
+    };
+    writeStatus();
+    const queueStart = Date.now();
+    try {
+      releaseAdmission = await options.admission.acquire((message) => {
+        log(message);
+        writeStatus();
+      });
+    } catch (err: unknown) {
+      admissionFailure = err instanceof Error ? err.message : String(err);
+    }
+    wall.queue = Date.now() - queueStart;
+    statusQueue = undefined;
+  }
+  statusState = "running";
+  writeStatus();
+
+  const hostStart = hostSample();
   const startedAt = Date.now();
-  const wall = { plan: 0, gates: 0, interactions: 0, critique: 0, snapshot: 0, total: 0 };
   const blockers: QaRunBlocker[] = [];
+  // Overall deadline: the clock starts after admission (pure runner time) and
+  // is consulted before every command, so the worst overshoot is one command
+  // timeout plus the kill grace. Exceeding it fails closed as incomplete.
+  const runDeadlineMs = job.policy?.run_deadline_ms ?? DEFAULT_RUN_DEADLINE_MS;
+  let deadlineHit = false;
+  const pastDeadline = (): boolean => {
+    if (deadlineHit) return true;
+    if (Date.now() - startedAt < runDeadlineMs) return false;
+    deadlineHit = true;
+    blockers.push({
+      stage: "deadline",
+      reason:
+        `run deadline of ${runDeadlineMs}ms exceeded — remaining commands were skipped and ` +
+        "the result finalized as incomplete (raise policy.run_deadline_ms for a legitimately " +
+        "larger matrix)",
+    });
+    log(`deadline: ${runDeadlineMs}ms exceeded, skipping remaining commands`);
+    return true;
+  };
   const commands: QaRunCommandOutcome[] = [];
   const critique: QaRunCritiqueOutcome[] = [];
+  const stagesRun: QaRunStage[] = [];
   let manifest: QaManifest | null = null;
   let contexts: QaRunContext[] = [];
   let snapshot: QaRunResult["snapshot"] = { saved: false };
+  let critiquePool: QaRunCritiquePool | undefined;
+  let reviewPack: QaRunReviewPack | undefined;
 
   const baseEnv: NodeJS.ProcessEnv = { ...process.env, ...options.childEnv };
 
@@ -328,15 +696,44 @@ export async function runQaMatrix(options: QaRunMatrixOptions): Promise<QaRunRes
 
   const finalize = (): QaRunResult => {
     wall.total = Date.now() - startedAt;
+    // Prefix semantics: the last stage the run progressed THROUGH cleanly.
+    // Stages are pushed in execution order; the first blocked stage ends the
+    // clean prefix, so a gate-blocked run reports "plan" even though the
+    // (empty) interactions stage technically executed afterwards.
+    const blockedStages = new Set(blockers.map((blocker) => blocker.stage));
+    let lastCompletedStage: QaRunStage | null = null;
+    for (const stage of stagesRun) {
+      if (blockedStages.has(stage)) break;
+      lastCompletedStage = stage;
+    }
     const result: QaRunResult = {
       schema_version: QA_RUN_RESULT_SCHEMA_VERSION,
+      evidence_source: "runner",
+      run: {
+        run_id: runId,
+        started_at: startedAtIso,
+        completed_at: new Date().toISOString(),
+        ...revision,
+        job_digest: jobDigest,
+        out_dir: outDir,
+      },
+      host: {
+        start: hostStart,
+        finish: hostSample(),
+        ...(Object.keys(stageHostSamples).length > 0 ? { stages: stageHostSamples } : {}),
+      },
+      last_completed_stage: lastCompletedStage,
       target: job.target,
-      ...(job.tested_revision !== undefined ? { tested_revision: job.tested_revision } : {}),
+      ...(revision.tested_revision !== undefined
+        ? { tested_revision: revision.tested_revision }
+        : {}),
       mode: job.mode,
       qa_plan: manifest,
       contexts,
       commands,
       critique,
+      ...(critiquePool ? { critique_pool: critiquePool } : {}),
+      ...(reviewPack ? { review_pack: reviewPack } : {}),
       snapshot,
       wall_time_ms: { ...wall },
       blockers,
@@ -349,9 +746,29 @@ export async function runQaMatrix(options: QaRunMatrixOptions): Promise<QaRunRes
       }),
     };
     writeFileSync(join(outDir, QA_RUN_RESULT_FILENAME), `${JSON.stringify(result, null, 2)}\n`);
+    writeLatestPointer(outParent, {
+      run_id: runId,
+      dir: basename(outDir),
+      completed_at: result.run.completed_at,
+      verdict: result.verdict,
+    });
+    statusState = "completed";
+    statusStage = null;
+    statusVerdict = result.verdict;
+    writeStatus();
+    clearInterval(heartbeat);
+    releaseAdmission?.();
     return result;
   };
 
+  if (admissionFailure !== undefined) {
+    blockers.push({
+      stage: "admission",
+      reason: `no admission slot for browser work: ${admissionFailure}`,
+    });
+    return finalize();
+  }
+
   // Base render arguments shared by every per-context invocation.
   const contextRenderArgs = (ctx: QaRunContext): string[] => [
     "--viewport",
@@ -360,6 +777,13 @@ export async function runQaMatrix(options: QaRunMatrixOptions): Promise<QaRunRes
     ...(ctx.args ?? []),
   ];
 
+  // The planner's tile ceiling and every critique child must agree on the
+  // per-context band cap, or the predicted cost and the real coverage drift.
+  const critiqueMaxTilesArgs =
+    job.policy?.critique_max_tiles !== undefined
+      ? ["--check-critique-max-tiles", String(job.policy.critique_max_tiles)]
+      : [];
+
   // ------------------------------------------------------------------ plan
   const planArgv = [
     ...browseArgv,
@@ -367,13 +791,16 @@ export async function runQaMatrix(options: QaRunMatrixOptions): Promise<QaRunRes
     "--qa-plan",
     "--json",
     "--no-screenshot",
+    ...critiqueMaxTilesArgs,
     ...(job.qa_hints?.scopes ?? []).flatMap((selector) => ["--qa-scope", selector]),
     ...(job.qa_hints?.states?.length ? ["--qa-states", job.qa_hints.states.join(",")] : []),
   ];
   log(`plan: ${job.target}`);
+  enterStage("plan");
   const planStart = Date.now();
   const plan = await timedExec(planArgv, baseEnv);
   wall.plan = Date.now() - planStart;
+  stagesRun.push("plan");
   let planEnvelope: Record<string, unknown> | undefined;
   if (!plan.res.error && plan.res.exitCode === 0) {
     try {
@@ -449,8 +876,10 @@ export async function runQaMatrix(options: QaRunMatrixOptions): Promise<QaRunRes
   const enforceConsole = manifest.checks.deterministic.includes("console");
   const checks = job.checks ?? [];
   const gateOutcomes = new Array<QaRunCommandOutcome>(contexts.length);
+  enterStage("gates");
   const gatesStart = Date.now();
   await runPool(contexts, concurrency, async (ctx, index) => {
+    if (pastDeadline()) return;
     const applicable = checks.filter(
       (check) => check.contexts === undefined || check.contexts.includes(ctx.id),
     );
@@ -466,6 +895,10 @@ export async function runQaMatrix(options: QaRunMatrixOptions): Promise<QaRunRes
       ...contextRenderArgs(ctx),
       "--out",
       outPrefix,
+      // When the manifest requires a visual pass, the capture stage writes the
+      // full-page PNG into the pack, so the gate trio carries no screenshot;
+      // nothing reads the gate PNG (the envelope JSON is the evidence).
+      ...(manifest.checks.visual !== "none" ? ["--no-screenshot"] : []),
       ...manifestGateArgs,
       ...applicable.flatMap((check) => check.args),
     ];
@@ -515,11 +948,14 @@ export async function runQaMatrix(options: QaRunMatrixOptions): Promise<QaRunRes
     };
   });
   wall.gates = Date.now() - gatesStart;
+  stagesRun.push("gates");
   // Manifest order regardless of completion order: outcomes were written by
-  // context index, so a straight push preserves it.
-  commands.push(...gateOutcomes);
+  // context index, so a straight push preserves it. Deadline-skipped slots
+  // are empty: the single deadline blocker is their record.
+  commands.push(...gateOutcomes.filter((outcome) => outcome !== undefined));
 
   // ---------------------------------------------------------- interactions
+  enterStage("interactions");
   const interactionsStart = Date.now();
   const declaredStates = new Set((job.interaction_states ?? []).map((state) => state.name));
   const manifestStates = [
@@ -538,6 +974,7 @@ export async function runQaMatrix(options: QaRunMatrixOptions): Promise<QaRunRes
     }
   }
   for (const state of job.interaction_states ?? []) {
+    if (pastDeadline()) break;
     const outPrefix = join(outDir, `interaction-${state.name}`);
     const argv = [
       ...browseArgv,
@@ -587,151 +1024,391 @@ export async function runQaMatrix(options: QaRunMatrixOptions): Promise<QaRunRes
     });
   }
   wall.interactions = Date.now() - interactionsStart;
+  stagesRun.push("interactions");
 
-  // -------------------------------------------------------------- critique
+  // -------------------------------------------------------------- capture
+  // Each context is rendered ONCE into the run's page review pack (full-page
+  // screenshot, tiles as PNG files, DOM, signature) through the same bounded
+  // pool the gates used, and its browser closes before any vision call.
   const visual = manifest.checks.visual;
   const cleanSoFar =
     blockers.length === 0 && commands.every((command) => command.outcome === "passed");
-  const critiqueStart = Date.now();
-  const savedSnapshots = new Map<string, string>();
-  if (cleanSoFar && visual !== "none") {
-    const critiqueEnv: NodeJS.ProcessEnv = job.policy?.allow_metered_critique
-      ? { ...baseEnv }
-      : { ...baseEnv, [QA_RUN_HEADLESS_ONLY_ENV]: "1" };
-    const scopeSelectors =
-      visual === "full-page" ? [undefined] : manifest.scopes.map((s) => s.selector);
-    for (const ctx of contexts) {
-      let tilesTotal = 0;
-      let tilesReviewed = 0;
-      let tilesReused = 0;
-      let provider = "none";
-      let contextOutcome: QaRunCritiqueOutcome["outcome"] = "passed";
-      const findings: QaRunCritiqueOutcome["findings"] = [];
-      for (const [scopeIndex, selector] of scopeSelectors.entries()) {
-        const suffix = scopeSelectors.length > 1 ? `-scope${scopeIndex}` : "";
-        const outPrefix = join(outDir, `${ctx.id}-critique${suffix}`);
-        const argv = [
-          ...browseArgv,
-          job.target,
-          ...contextRenderArgs(ctx),
-          "--out",
-          outPrefix,
-          ...(selector !== undefined ? ["--check-critique", selector] : ["--check-critique"]),
-          "--check-critique-fail",
-          ...(manifest.baseline_source !== "none" ? ["--qa-reuse"] : []),
-          ...(job.mode === "signoff"
-            ? ["--qa-snapshot", "--qa-theme", ctx.theme, "--qa-state", ctx.state]
-            : []),
-        ];
-        log(`critique ${ctx.id}${selector !== undefined ? ` [${selector}]` : ""}`);
-        const { res, wallTimeMs } = await timedExec(argv, critiqueEnv);
-        const jsonPath = `${outPrefix}.json`;
-        const envelope = readEnvelope(jsonPath);
-        const envelopeCritique = envelope?.critique as EnvelopeCritique | undefined;
-        const failures: string[] = [];
-        let commandOutcome: QaRunCommandOutcome["outcome"];
-        if (res.error || (res.exitCode !== 0 && res.exitCode !== 2) || !envelope) {
-          commandOutcome = "unknown";
-          const excerpt = execErrorExcerpt(res);
-          const base = res.error
-            ? res.error
-            : !envelope
-              ? `exit code ${res.exitCode ?? "null"}, missing JSON artifact ${jsonPath}`
-              : `exit code ${res.exitCode ?? "null"}`;
-          const reason = excerpt ? `${base}: ${excerpt}` : base;
+  const packDir = join(outDir, PAGE_REVIEW_PACK_DIRNAME);
+  const capturedRecords: PageReviewContextRecord[] = [];
+  const judgeCommand = options.reviewPackJudgeCommand?.(packDir);
+  // Gate rectangles ride along from each gate's JSON artifact so the pack's
+  // inspection plan can point a runt, a contrast miss, or a clipped element
+  // at the tiles that show it. A missing or unparseable artifact simply
+  // contributes no hits; the gate's `failures` still carry the text.
+  const gateRecords = (): PageReviewGateRecord[] =>
+    commands
+      .filter((command) => command.check_id !== "plan" && command.check_id !== "review-pack")
+      .map((command) => {
+        const hits = command.artifacts.json
+          ? gateHitsFromEnvelope(readEnvelope(command.artifacts.json))
+          : [];
+        return {
+          context_id: command.context_id,
+          check_id: command.check_id,
+          outcome: command.outcome,
+          failures: command.failures,
+          ...(hits.length > 0 ? { hits } : {}),
+        };
+      });
+  const finalizePack = (
+    stage: QaRunStage,
+    critiqueRecords: PageReviewCritiqueRecord[] | null,
+    pool?: { concurrency: number; wall_time_ms: number; provider: string },
+  ): void => {
+    try {
+      finalizePageReviewPack({
+        packDir,
+        target: job.target,
+        ...(revision.tested_revision !== undefined
+          ? { tested_revision: revision.tested_revision }
+          : {}),
+        contexts: capturedRecords,
+        gates: gateRecords(),
+        critique: critiqueRecords,
+        ...(pool ? { pool } : {}),
+        ...(judgeCommand ? { judgeCommand } : {}),
+        createdAt: startedAtIso,
+        // The retention clock restarts at each finalize, so it ends
+        // `retention_minutes` after the judge (or after capture when the
+        // judge never runs).
+        retention: {
+          expires_at: new Date(
+            Date.now() +
+              (job.policy?.review_pack_retention_minutes ?? PAGE_REVIEW_DEFAULT_RETENTION_MINUTES) *
+                60_000,
+          ).toISOString(),
+          managed: options.reviewPackManaged === true,
+        },
+      });
+      const written = readPackManifest(packDir);
+      reviewPack = {
+        schema: PAGE_REVIEW_PACK_SCHEMA,
+        dir: packDir,
+        review: join(packDir, PAGE_REVIEW_REVIEW_FILENAME),
+        findings: join(packDir, PAGE_REVIEW_FINDINGS_FILENAME),
+        ...(written.retention ? { expires_at: written.retention.expires_at } : {}),
+        ...(written.size_bytes !== undefined ? { size_bytes: written.size_bytes } : {}),
+      };
+    } catch (err: unknown) {
+      blockers.push({
+        stage,
+        reason: `page review pack could not be finalized: ${err instanceof Error ? err.message : String(err)}`,
+      });
+    }
+  };
+
+  // The provider is loaded once, before capture, so the capture children can
+  // clamp band height to the routed model's vision budget (what browse does
+  // for --check-critique) and the judge reuses the same instance.
+  const priorHeadlessOnly = process.env[QA_RUN_HEADLESS_ONLY_ENV];
+  const restoreHeadlessOnly = (): void => {
+    if (priorHeadlessOnly === undefined) delete process.env[QA_RUN_HEADLESS_ONLY_ENV];
+    else process.env[QA_RUN_HEADLESS_ONLY_ENV] = priorHeadlessOnly;
+  };
+  let provider: CritiqueProvider | undefined;
+  const runsVisual = cleanSoFar && visual !== "none";
+  if (runsVisual) {
+    if (!job.policy?.allow_metered_critique) process.env[QA_RUN_HEADLESS_ONLY_ENV] = "1";
+    try {
+      provider =
+        options.critiqueProvider ??
+        (options.critiqueProviderLoader ? await options.critiqueProviderLoader() : undefined);
+    } catch (err: unknown) {
+      provider = undefined;
+      log(`critique provider failed to load: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  const bandArgs =
+    provider?.tileBudgetPx !== undefined
+      ? ["--check-critique-band", String(Math.max(200, Math.min(1400, provider.tileBudgetPx)))]
+      : [];
+  const scopeArgs =
+    visual === "full-page"
+      ? []
+      : manifest.scopes.flatMap((s) => ["--review-pack-scope", s.selector]);
+  // Gate-hit rectangles ride into each context's capture child so the bands
+  // they land in are cut even past the tile cap (`hit band N` tiles). The
+  // gates ran first, so the rects are known before the page is captured.
+  const hitRectsByContext = new Map<string, string[]>();
+  for (const gate of gateRecords()) {
+    for (const hit of gate.hits ?? []) {
+      const list = hitRectsByContext.get(gate.context_id) ?? [];
+      if (list.length >= REVIEW_PACK_HIT_RECTS_PER_CONTEXT) break;
+      const r = hit.rect;
+      list.push(
+        [r.x, r.y, Math.max(0, r.width), Math.max(0, r.height)].map((n) => Math.round(n)).join(","),
+      );
+      hitRectsByContext.set(gate.context_id, list);
+    }
+  }
+  const hitRectArgs = (contextId: string): string[] =>
+    (hitRectsByContext.get(contextId) ?? []).flatMap((spec) => ["--review-pack-hit-rect", spec]);
+
+  enterStage("capture");
+  const captureStart = Date.now();
+  if (runsVisual) {
+    const captureOutcomes = new Array<QaRunCommandOutcome>(contexts.length);
+    const captureRecords = new Array<PageReviewContextRecord | undefined>(contexts.length);
+    await runPool(contexts, concurrency, async (ctx, index) => {
+      if (pastDeadline()) return;
+      const outPrefix = join(outDir, `${ctx.id}-capture`);
+      const argv = [
+        ...browseArgv,
+        job.target,
+        ...contextRenderArgs(ctx),
+        "--out",
+        outPrefix,
+        "--no-screenshot",
+        "--review-pack",
+        packDir,
+        "--review-pack-context",
+        ctx.id,
+        "--qa-theme",
+        ctx.theme,
+        "--qa-state",
+        ctx.state,
+        ...(visual === "scoped" ? ["--no-review-pack-bands"] : []),
+        ...scopeArgs,
+        ...critiqueMaxTilesArgs,
+        ...bandArgs,
+        ...hitRectArgs(ctx.id),
+      ];
+      log(
+        `capture ${ctx.id}${scopeArgs.length > 0 ? ` [${manifest.scopes.map((s) => s.selector).join(",")}]` : ""}`,
+      );
+      const { res, wallTimeMs } = await timedExec(argv, baseEnv);
+      const jsonPath = `${outPrefix}.json`;
+      const envelope = readEnvelope(jsonPath);
+      const report = envelope?.reviewPack as { context_id?: string } | undefined;
+      const failures: string[] = [];
+      let outcome: QaRunCommandOutcome["outcome"];
+      let record: PageReviewContextRecord | undefined;
+      if (!res.error && res.exitCode === 0 && envelope && report?.context_id) {
+        try {
+          record = readPackContext(packDir, report.context_id);
+          outcome = "passed";
+        } catch (err: unknown) {
+          outcome = "unknown";
+          const reason = `pack context unreadable: ${err instanceof Error ? err.message : String(err)}`;
           failures.push(reason);
-          blockers.push({
-            stage: "critique",
-            context_id: ctx.id,
-            reason: `critique command did not complete: ${reason}`,
-          });
-          contextOutcome = "unknown";
-        } else {
-          tilesTotal += envelopeCritique?.tiles ?? 0;
-          const reuse = envelope.qaReuse as
-            | { tiles_reused?: number; tiles_reviewed?: number }
-            | undefined;
-          tilesReused += reuse?.tiles_reused ?? 0;
-          tilesReviewed += reuse?.tiles_reviewed ?? envelopeCritique?.tiles ?? 0;
-          provider = providerLabel(envelopeCritique);
-          for (const finding of envelopeCritique?.findings ?? []) {
-            findings.push({
-              severity: finding.severity ?? "unknown",
-              summary: finding.category
-                ? `${finding.category}: ${finding.description ?? ""}`
-                : (finding.description ?? ""),
-              ...(selector !== undefined ? { selector } : {}),
-            });
-          }
-          if (envelopeCritique?.outcome === "pass" && res.exitCode === 0) {
-            commandOutcome = "passed";
-          } else if (envelopeCritique?.outcome === "fail") {
-            commandOutcome = "failed";
-            failures.push(`critique found ${envelopeCritique.findings?.length ?? 0} defect(s)`);
-            contextOutcome = "failed";
-          } else {
-            // "skipped" (no provider / exhausted headless list) or anything
-            // unrecognized: the review did not happen, so nothing is proven.
-            commandOutcome = "unknown";
-            const detail = envelopeCritique?.error ?? "critique reported no conclusive outcome";
-            failures.push(detail);
-            blockers.push({
-              stage: "critique",
-              context_id: ctx.id,
-              reason: job.policy?.allow_metered_critique
-                ? `critique did not complete: ${detail}`
-                : `critique did not complete under the headless-only policy ` +
-                  `(${QA_RUN_HEADLESS_ONLY_ENV}=1; permit metered fallback with ` +
-                  `policy.allow_metered_critique / --allow-metered): ${detail}`,
-            });
-            if (contextOutcome !== "failed") contextOutcome = "unknown";
-          }
-          if (job.mode === "signoff") {
-            const saved = (envelope.qaPlan as { snapshotSaved?: { path?: string } } | undefined)
-              ?.snapshotSaved;
-            if (saved?.path) savedSnapshots.set(ctx.id, saved.path);
-          }
+          blockers.push({ stage: "capture", context_id: ctx.id, reason });
         }
-        commands.push({
+      } else {
+        outcome = "unknown";
+        const excerpt = execErrorExcerpt(res);
+        const base = res.error
+          ? res.error
+          : !envelope
+            ? `exit code ${res.exitCode ?? "null"}, missing JSON artifact ${jsonPath}`
+            : !report?.context_id
+              ? `exit code ${res.exitCode ?? "null"}, envelope carries no reviewPack record`
+              : `exit code ${res.exitCode ?? "null"}`;
+        const reason = excerpt ? `${base}: ${excerpt}` : base;
+        failures.push(reason);
+        blockers.push({
+          stage: "capture",
           context_id: ctx.id,
-          check_id: "critique",
-          argv,
-          exit_code: res.exitCode,
-          outcome: commandOutcome,
-          failures,
-          artifacts: gatherArtifacts(outPrefix),
-          wall_time_ms: wallTimeMs,
+          reason: `capture command did not complete: ${reason}`,
         });
       }
-      critique.push({
+      captureOutcomes[index] = {
         context_id: ctx.id,
-        provider,
-        tiles_total: tilesTotal,
-        tiles_reviewed: tilesReviewed,
-        tiles_reused: tilesReused,
-        outcome: contextOutcome,
-        findings,
-      });
-      if (job.mode === "signoff" && contextOutcome === "passed" && !savedSnapshots.has(ctx.id)) {
+        check_id: "review-pack",
+        argv,
+        exit_code: res.exitCode,
+        outcome,
+        failures,
+        artifacts: gatherArtifacts(outPrefix),
+        wall_time_ms: wallTimeMs,
+      };
+      captureRecords[index] = record;
+    });
+    commands.push(...captureOutcomes.filter((outcome) => outcome !== undefined));
+    capturedRecords.push(
+      ...captureRecords.filter((record): record is PageReviewContextRecord => Boolean(record)),
+    );
+    // The pack is readable from here on even if the judge never runs.
+    if (capturedRecords.length > 0) finalizePack("capture", null);
+  }
+  wall.capture = Date.now() - captureStart;
+  if (runsVisual) stagesRun.push("capture");
+
+  // -------------------------------------------------------------- critique
+  // One pool of vision calls across every captured context, from disk. No
+  // browser is open during this stage.
+  enterStage("critique");
+  const critiqueStart = Date.now();
+  const judgedById = new Map<string, JudgedContext>();
+  if (runsVisual && capturedRecords.length > 0 && !pastDeadline()) {
+    const judged = await judgePageReviewPack({
+      packDir,
+      provider,
+      rubric: DEFAULT_CRITIQUE_RUBRIC,
+      ...(job.policy?.critique_pool !== undefined ? { concurrency: job.policy.critique_pool } : {}),
+      contextIds: capturedRecords.map((record) => record.id),
+      ...(manifest.baseline_source !== "none"
+        ? {
+            reuse: {
+              target: job.target,
+              ...(options.snapshotStore ? { store: options.snapshotStore } : {}),
+            },
+          }
+        : {}),
+      deadlineAt: startedAt + runDeadlineMs,
+      onLog: log,
+    });
+    const latency = critiqueLatency(judged.provider_meta);
+    critiquePool = {
+      concurrency: judged.pool.concurrency,
+      tiles_total: judged.tiles_total,
+      tiles_reviewed: judged.tiles_reviewed,
+      tiles_reused: judged.tiles_reused,
+      wall_time_ms: judged.pool.wall_time_ms,
+      provider: judged.pool.provider,
+      ...(latency ? { latency_ms: latency } : {}),
+    };
+    for (const row of judged.contexts) {
+      judgedById.set(row.context_id, row);
+      let contextOutcome: QaRunCritiqueOutcome["outcome"] =
+        row.outcome === "pass" ? "passed" : row.outcome === "fail" ? "failed" : "unknown";
+      if (row.outcome === "skipped") {
+        const detail = row.error ?? "critique reported no conclusive outcome";
         blockers.push({
-          stage: "snapshot",
-          context_id: ctx.id,
-          reason: "signoff critique passed but no QA snapshot was persisted for the context",
+          stage: "critique",
+          context_id: row.context_id,
+          reason: job.policy?.allow_metered_critique
+            ? `critique did not complete: ${detail}`
+            : `critique did not complete under the headless-only policy ` +
+              `(${QA_RUN_HEADLESS_ONLY_ENV}=1; permit metered fallback with ` +
+              `policy.allow_metered_critique / --allow-metered): ${detail}`,
+        });
+      } else if (row.outcome === "incomplete") {
+        blockers.push({
+          stage: "critique",
+          context_id: row.context_id,
+          reason:
+            `judge did not review ${row.tiles_unjudged} of ${row.tiles_total} tile(s) before the ` +
+            "run deadline; nothing is proven for them",
+        });
+      }
+      // A capped capture holds the top of the page and nothing below it.
+      // Signoff cannot rest on that; review mode keeps the row honest via
+      // `coverage` and leaves the verdict to the tiles that were seen.
+      if (job.mode === "signoff" && row.coverage.capped && contextOutcome !== "failed") {
+        contextOutcome = "unknown";
+        blockers.push({
+          stage: "critique",
+          context_id: row.context_id,
+          reason:
+            `critique coverage capped: ${row.coverage.bands_reviewed} of ${row.coverage.bands_total} bands ` +
+            `reviewed (${row.coverage.reviewed_height_px} of ${row.coverage.page_height_px} px); raise ` +
+            "policy.critique_max_tiles to review the whole page in signoff mode",
         });
       }
+      const scopeById = new Map(row.record.tiles.map((tile) => [tile.id, tile.scope]));
+      critique.push({
+        context_id: row.context_id,
+        provider: row.provider,
+        tiles_total: row.tiles_total,
+        tiles_reviewed: row.tiles_reviewed,
+        tiles_reused: row.tiles_reused,
+        outcome: contextOutcome,
+        findings: row.findings.map((finding) => {
+          const selector = scopeById.get(finding.tile_id);
+          return {
+            severity: finding.severity,
+            summary: `${finding.category}: ${finding.description}`,
+            tile: `${row.context_id}/${finding.tile_id}`,
+            ...(selector !== undefined ? { selector } : {}),
+          };
+        }),
+        coverage: row.coverage,
+      });
     }
+    finalizePack("critique", toCritiqueRecords(judged), judged.pool);
   }
+  if (runsVisual) restoreHeadlessOnly();
   wall.critique = Date.now() - critiqueStart;
+  if (runsVisual) stagesRun.push("critique");
 
   // -------------------------------------------------------------- snapshot
-  // Critique invocations carry --qa-snapshot in signoff mode. When the
-  // manifest requires no visual pass (visual === "none"), a passing signoff
-  // still needs its baseline persisted, so a dedicated snapshot pass runs.
+  // Signoff persists each context's baseline from the pack's own files (no
+  // browser). The critique rides along only when the whole tile set was
+  // freshly judged, uncapped, and unscoped — a partial or scoped review must
+  // never become the next baseline's finding record. When the manifest
+  // required no visual pass, a dedicated browse --qa-snapshot pass still runs.
+  enterStage("snapshot");
   const snapshotStart = Date.now();
-  if (job.mode === "signoff" && visual === "none" && blockers.length === 0) {
+  const savedSnapshots = new Map<string, string>();
+  if (job.mode === "signoff" && runsVisual) {
+    for (const record of capturedRecords) {
+      if (pastDeadline()) break;
+      const row = judgedById.get(record.id);
+      const persistCritique =
+        row !== undefined &&
+        (row.outcome === "pass" || row.outcome === "fail") &&
+        !record.coverage.capped &&
+        row.tiles_reused === 0 &&
+        row.tiles_unjudged === 0 &&
+        record.scopes.length === 0;
+      const persisted: PersistedCritique | undefined =
+        persistCritique && row
+          ? {
+              contract_version: QA_CRITIQUE_CONTRACT_VERSION,
+              rubric_digest: rubricDigest(DEFAULT_CRITIQUE_RUBRIC),
+              outcome: row.outcome as "pass" | "fail",
+              findings: row.findings.map(({ tile_id: _tileId, ...finding }) => finding),
+              tiles: record.tiles.map((tile) => ({
+                index: tile.index,
+                label: tile.label,
+                x: tile.x,
+                scrollY: tile.scrollY,
+                width: tile.width,
+                height: tile.height,
+              })),
+            }
+          : undefined;
+      try {
+        const saved = saveQaSnapshot(
+          job.target,
+          { viewport: record.viewport, theme: record.theme, state: record.state },
+          {
+            signature: readPackSignature(packDir, record),
+            domHtml: readPackDom(packDir, record),
+            screenshotPng: readPackFullPage(packDir, record),
+            ...(persisted ? { critique: persisted } : {}),
+          },
+          options.snapshotStore ?? {},
+        );
+        savedSnapshots.set(record.id, saved.path);
+        log(`snapshot ${record.id}: saved${persisted ? " with critique" : ""}`);
+      } catch (err: unknown) {
+        blockers.push({
+          stage: "snapshot",
+          context_id: record.id,
+          reason: `snapshot could not be persisted from the pack: ${err instanceof Error ? err.message : String(err)}`,
+        });
+      }
+    }
+    for (const row of critique) {
+      if (row.outcome === "passed" && !savedSnapshots.has(row.context_id)) {
+        blockers.push({
+          stage: "snapshot",
+          context_id: row.context_id,
+          reason: "signoff critique passed but no QA snapshot was persisted for the context",
+        });
+      }
+    }
+  } else if (job.mode === "signoff" && visual === "none" && blockers.length === 0) {
     const stillClean = commands.every((command) => command.outcome === "passed");
     if (stillClean) {
       for (const ctx of contexts) {
+        if (pastDeadline()) break;
         const outPrefix = join(outDir, `${ctx.id}-snapshot`);
         const argv = [
           ...browseArgv,
@@ -773,6 +1450,7 @@ export async function runQaMatrix(options: QaRunMatrixOptions): Promise<QaRunRes
     }
   }
   wall.snapshot = Date.now() - snapshotStart;
+  if (job.mode === "signoff") stagesRun.push("snapshot");
 
   if (job.mode === "signoff") {
     const allSaved = contexts.length > 0 && contexts.every((ctx) => savedSnapshots.has(ctx.id));