harnery 0.37.0 → 0.38.0

package/dist/lib/browser/qa-run.js

@@ -10,18 +10,73 @@
 // outcome in the result — nothing is filtered away.
 //
 // 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 { computeVerdict, mergeCoverage, QA_RUN_RESULT_SCHEMA_VERSION, } from "./qa-run-contracts.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. */
+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 { DEFAULT_CRITIQUE_RUBRIC } from "./critique.js";
+import { 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, readPackContext, readPackDom, readPackFullPage, readPackManifest, readPackSignature, } from "./page-review-pack.js";
+import { QA_CRITIQUE_CONTRACT_VERSION, rubricDigest } from "./qa-reuse.js";
+import { computeJobDigest, computeVerdict, mergeCoverage, QA_RUN_RESULT_SCHEMA_VERSION, QA_RUN_STATUS_SCHEMA_VERSION, } from "./qa-run-contracts.js";
+import { saveQaSnapshot } from "./qa-snapshot.js";
+/** 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";
+/**
+ * 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, input) {
+    const pointerPath = join(outParent, QA_RUN_LATEST_FILENAME);
+    let pointerIsNewer = true;
+    try {
+        const existing = JSON.parse(readFileSync(pointerPath, "utf8"));
+        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
  * report-only hint. A job may add checks, but these arguments always run for
@@ -33,38 +88,142 @@ const MANIFEST_DETERMINISTIC_ARGS = {
     truncation: ["--check-truncation", "--check-truncation-fail"],
     placeholder: ["--check-placeholder", "--check-placeholder-fail"],
 };
-/** 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 = (argv, options) => new Promise((resolvePromise) => {
     const [command, ...args] = argv;
     if (!command) {
         resolvePromise({ exitCode: null, stdout: "", stderr: "", error: "empty argv" });
         return;
     }
-    const child = execFile(command, args, {
-        timeout: options.timeoutMs,
-        maxBuffer: EXEC_MAX_BUFFER,
+    // 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,
-        killSignal: "SIGTERM",
-    }, (err, stdout, stderr) => {
-        const out = String(stdout ?? "");
-        const errOut = String(stderr ?? "");
-        if (!err) {
-            resolvePromise({ exitCode: 0, stdout: out, stderr: errOut });
+        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;
+    let killTimer;
+    let drainTimer;
+    const settle = (result) => {
+        if (settled)
             return;
-        }
-        const failure = err;
-        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 });
+        settled = true;
+        clearTimeout(termTimer);
+        clearTimeout(killTimer);
+        clearTimeout(drainTimer);
+        resolvePromise(result);
+    };
+    const signalGroup = (signal) => {
+        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.
+            }
+        }
+        try {
+            child.kill(signal);
+        }
+        catch {
+            // Nothing left to kill.
         }
-        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 });
+    };
+    const collect = (chunk, sink) => {
+        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" });
     });
-    child.stdin?.end();
+    const finish = (code, signal) => {
+        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?.();
 });
 /** One-line tail excerpt of a failed child's output for blockers and
  * failures, preferring stderr and falling back to stdout (browse prints its
@@ -186,39 +345,181 @@ function parseConsoleFailures(envelope) {
     }
     return failures;
 }
-function providerLabel(critique) {
-    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) {
+    const providers = providerMeta?.providers;
+    if (!providers || typeof providers !== "object" || Array.isArray(providers))
+        return undefined;
+    const out = {};
+    for (const [name, state] of Object.entries(providers)) {
+        const lat = state?.latency_ms;
+        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) {
-    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 = () => {
+        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 = {};
+    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 = "running";
+    let statusStage = null;
+    let statusQueue;
+    let statusVerdict;
+    const writeStatus = () => {
+        const status = {
+            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) => {
+        statusStage = stage;
+        stageHostSamples[stage] = hostSample();
+        writeStatus();
+    };
+    const revision = 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 = {
+        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;
+    let admissionFailure;
+    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) {
+            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 = [];
+    // 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 = () => {
+        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 = [];
     const critique = [];
+    const stagesRun = [];
     let manifest = null;
     let contexts = [];
     let snapshot = { saved: false };
+    let critiquePool;
+    let reviewPack;
     const baseEnv = { ...process.env, ...options.childEnv };
     const timedExec = async (argv, env) => {
         const started = Date.now();
@@ -238,15 +539,45 @@ export async function runQaMatrix(options) {
     };
     const finalize = () => {
         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 = null;
+        for (const stage of stagesRun) {
+            if (blockedStages.has(stage))
+                break;
+            lastCompletedStage = stage;
+        }
         const result = {
             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,
@@ -259,8 +590,27 @@ export async function runQaMatrix(options) {
             }),
         };
         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) => [
         "--viewport",
@@ -268,6 +618,11 @@ export async function runQaMatrix(options) {
         ...(ctx.theme === "dark" ? ["--color-scheme", "dark"] : []),
         ...(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,
@@ -275,13 +630,16 @@ export async function runQaMatrix(options) {
         "--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;
     if (!plan.res.error && plan.res.exitCode === 0) {
         try {
@@ -353,8 +711,11 @@ export async function runQaMatrix(options) {
     const enforceConsole = manifest.checks.deterministic.includes("console");
     const checks = job.checks ?? [];
     const gateOutcomes = new Array(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));
         const checkId = [
             ...manifest.checks.deterministic.map((check) => `manifest:${check}`),
@@ -367,6 +728,10 @@ export async function runQaMatrix(options) {
             ...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),
         ];
@@ -419,10 +784,13 @@ export async function runQaMatrix(options) {
         };
     });
     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 = [
@@ -438,6 +806,8 @@ export async function runQaMatrix(options) {
         }
     }
     for (const state of job.interaction_states ?? []) {
+        if (pastDeadline())
+            break;
         const outPrefix = join(outDir, `interaction-${state.name}`);
         const argv = [
             ...browseArgv,
@@ -489,150 +859,377 @@ export async function runQaMatrix(options) {
         });
     }
     wall.interactions = Date.now() - interactionsStart;
-    // -------------------------------------------------------------- critique
+    stagesRun.push("interactions");
+    // -------------------------------------------------------------- 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();
-    if (cleanSoFar && visual !== "none") {
-        const critiqueEnv = 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 = "passed";
-            const 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;
-                const failures = [];
-                let commandOutcome;
-                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;
-                    failures.push(reason);
-                    blockers.push({
-                        stage: "critique",
-                        context_id: ctx.id,
-                        reason: `critique command did not complete: ${reason}`,
-                    });
-                    contextOutcome = "unknown";
+    const packDir = join(outDir, PAGE_REVIEW_PACK_DIRNAME);
+    const capturedRecords = [];
+    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 = () => 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, critiqueRecords, pool) => {
+        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) {
+            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 = () => {
+        if (priorHeadlessOnly === undefined)
+            delete process.env[QA_RUN_HEADLESS_ONLY_ENV];
+        else
+            process.env[QA_RUN_HEADLESS_ONLY_ENV] = priorHeadlessOnly;
+    };
+    let provider;
+    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) {
+            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();
+    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) => (hitRectsByContext.get(contextId) ?? []).flatMap((spec) => ["--review-pack-hit-rect", spec]);
+    enterStage("capture");
+    const captureStart = Date.now();
+    if (runsVisual) {
+        const captureOutcomes = new Array(contexts.length);
+        const captureRecords = new Array(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;
+            const failures = [];
+            let outcome;
+            let record;
+            if (!res.error && res.exitCode === 0 && envelope && report?.context_id) {
+                try {
+                    record = readPackContext(packDir, report.context_id);
+                    outcome = "passed";
                 }
-                else {
-                    tilesTotal += envelopeCritique?.tiles ?? 0;
-                    const reuse = envelope.qaReuse;
-                    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
-                            ?.snapshotSaved;
-                        if (saved?.path)
-                            savedSnapshots.set(ctx.id, saved.path);
-                    }
+                catch (err) {
+                    outcome = "unknown";
+                    const reason = `pack context unreadable: ${err instanceof Error ? err.message : String(err)}`;
+                    failures.push(reason);
+                    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,
+                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) => 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();
+    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 = 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: "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,
+                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,
             });
-            if (job.mode === "signoff" && contextOutcome === "passed" && !savedSnapshots.has(ctx.id)) {
+        }
+        finalizePack("critique", toCritiqueRecords(judged), judged.pool);
+    }
+    if (runsVisual)
+        restoreHeadlessOnly();
+    wall.critique = Date.now() - critiqueStart;
+    if (runsVisual)
+        stagesRun.push("critique");
+    // -------------------------------------------------------------- snapshot
+    // 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();
+    const savedSnapshots = new Map();
+    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 = persistCritique && row
+                ? {
+                    contract_version: QA_CRITIQUE_CONTRACT_VERSION,
+                    rubric_digest: rubricDigest(DEFAULT_CRITIQUE_RUBRIC),
+                    outcome: row.outcome,
+                    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) {
                 blockers.push({
                     stage: "snapshot",
-                    context_id: ctx.id,
+                    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",
                 });
             }
         }
     }
-    wall.critique = Date.now() - critiqueStart;
-    // -------------------------------------------------------------- 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.
-    const snapshotStart = Date.now();
-    if (job.mode === "signoff" && visual === "none" && blockers.length === 0) {
+    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,
@@ -675,6 +1272,8 @@ export async function runQaMatrix(options) {
         }
     }
     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));
         const lastPath = [...savedSnapshots.values()].pop();