harnery 0.37.0 → 0.38.0

package/dist/lib/browser/qa-run-contracts.d.ts

@@ -1,6 +1,12 @@
 import type { QaContext, QaManifest } from "./qa-plan.js";
 export declare const QA_RUN_JOB_SCHEMA_VERSION: 1;
-export declare const QA_RUN_RESULT_SCHEMA_VERSION: 1;
+export declare const QA_RUN_RESULT_SCHEMA_VERSION: 4;
+/** How a result's evidence was produced. `runner` means the qa-run matrix
+ * executed the checks itself. `manual` means an operator or agent performed
+ * the checks by hand and recorded them (qa-record); such a result can report
+ * a defect but can never claim a pass, because nothing re-executable proved
+ * the absence of one. */
+export type QaRunEvidenceSource = "runner" | "manual";
 /** One rendering context the runner will capture and check. */
 export interface QaRunContext {
     /** Stable ID, unique within the job; also the artifact prefix component.
@@ -46,6 +52,26 @@ export interface QaRunPolicy {
     command_concurrency?: number;
     /** Per-command timeout in milliseconds (default 120000). */
     command_timeout_ms?: number;
+    /** Overall runner deadline in milliseconds (default 900000). When the run
+     * exceeds it, remaining commands are skipped, a `deadline` blocker is
+     * recorded, and the result finalizes as incomplete — releasing the
+     * admission slot instead of holding it open-endedly. */
+    run_deadline_ms?: number;
+    /** Full-page critique bands per context (browse `--check-critique-max-tiles`,
+     * default 24). Raise it when a tall page must be reviewed end to end and the
+     * per-tile cost is accepted; each critique row's `coverage` records what the
+     * run actually saw, which is why this knob can stay out of the job digest. */
+    critique_max_tiles?: number;
+    /** Vision calls in flight during the judge stage, across every context of
+     * the run (1 to 16). Default: the host provider's own concurrency. The
+     * capture stage closes every browser before judging starts, so this knob
+     * costs model-call parallelism, never browser memory. */
+    critique_pool?: number;
+    /** Minutes the run's page review pack lives after the judge finishes before
+     * the whole pack directory is deleted (default 90; 1 to 43200). The result
+     * document keeps every finding inline, so a run stays reportable after its
+     * pack is gone. */
+    review_pack_retention_minutes?: number;
 }
 export interface QaRunJob {
     schema_version: typeof QA_RUN_JOB_SCHEMA_VERSION;
@@ -86,6 +112,26 @@ export interface QaRunCommandOutcome {
     };
     wall_time_ms: number;
 }
+/** Vision-call latency one critique backend reported over the judge pool,
+ * in milliseconds over the tile calls it served. The percentiles are the
+ * provider's own sample across every context (one pool, one sample). */
+export interface QaRunCritiqueLatency {
+    count: number;
+    p50: number;
+    p95: number;
+}
+/** What share of the page the critique tiles covered, lifted from the browse
+ * envelope. `capped` means the tiler dropped bands past its per-context
+ * maximum; in signoff mode that is a blocker, in review mode a flag. Across
+ * several scope commands the heights take the worst case and the band counts
+ * add. */
+export interface QaRunCritiqueCoverage {
+    page_height_px: number;
+    reviewed_height_px: number;
+    bands_total: number;
+    bands_reviewed: number;
+    capped: boolean;
+}
 export interface QaRunCritiqueOutcome {
     context_id: string;
     provider: string;
@@ -97,16 +143,131 @@ export interface QaRunCritiqueOutcome {
         severity: string;
         summary: string;
         selector?: string;
+        tile?: string;
     }>;
+    /** Tile coverage of the page. Absent when the capture died or reported none. */
+    coverage?: QaRunCritiqueCoverage;
+}
+/** The judge stage as one unit: every context's tiles through one bounded
+ * pool of vision calls, with no browser open. `latency_ms` is the backends'
+ * own per-call sample over the whole pool, keyed by backend name. */
+export interface QaRunCritiquePool {
+    concurrency: number;
+    tiles_total: number;
+    tiles_reviewed: number;
+    tiles_reused: number;
+    wall_time_ms: number;
+    provider: string;
+    latency_ms?: Record<string, QaRunCritiqueLatency>;
+}
+/** Where the run's page review pack lives: the on-disk evidence an agent can
+ * review without a browser (tiles, DOM, coverage, `review.md`, and the
+ * delegated-review `findings.json`). */
+export interface QaRunReviewPack {
+    schema: string;
+    dir: string;
+    review: string;
+    findings: string;
+    /** When the pack directory is deleted (ISO). Absent when the run never
+     * reached the point of knowing (capture failed before any context landed). */
+    expires_at?: string;
+    /** Bytes on disk at finalize time. */
+    size_bytes?: number;
 }
 export interface QaRunBlocker {
-    stage: "validate" | "plan" | "gates" | "interactions" | "critique" | "snapshot" | "result";
+    stage: "validate" | "admission" | "plan" | "gates" | "interactions" | "capture" | "critique" | "snapshot" | "deadline" | "result";
     context_id?: string;
     reason: string;
 }
 export type QaRunVerdict = "passed" | "failed" | "incomplete";
+/** Runner stages in execution order. `last_completed_stage` names the last
+ * one that finished without contributing a blocker. */
+export declare const QA_RUN_STAGES: readonly ["plan", "gates", "interactions", "capture", "critique", "snapshot"];
+export type QaRunStage = (typeof QA_RUN_STAGES)[number];
+/** Identity of one runner invocation. This block is what makes a result
+ * verifiable evidence rather than a loose file: a consumer matches it against
+ * the invocation being reported (see assessQaRunEvidence) instead of trusting
+ * whatever sits in a reused directory. */
+export interface QaRunIdentity {
+    /** Minted per invocation (crypto.randomUUID). */
+    run_id: string;
+    /** ISO-8601 UTC bounds of the invocation. */
+    started_at: string;
+    completed_at: string;
+    /** Git SHA or content identifier of what was tested, when resolvable. */
+    tested_revision?: string;
+    /** Where tested_revision came from: the job document, a git probe of the
+     * working directory, or nowhere (`unknown`, tested_revision absent). */
+    revision_source: "job" | "git" | "unknown";
+    /** `git status --porcelain` was non-empty when the run started — a revision
+     * alone does not prove content. Absent when no git probe ran. */
+    worktree_dirty?: boolean;
+    /** SHA-256 over the effective validated job (computeJobDigest). */
+    job_digest: string;
+    /** Absolute run directory the result was written into. A result found
+     * elsewhere has been moved or copied and fails evidence assessment. */
+    out_dir: string;
+}
+export declare const QA_RUN_STATUS_SCHEMA_VERSION: 1;
+export type QaRunStatusState = "launching" | "queued" | "running" | "completed";
+/** Live status document (`run-status.json`) beside the result in every run
+ * directory. Written at start, every stage boundary, and on a heartbeat
+ * timer, so a client that lost its terminal (e.g. a Windows-to-WSL bridge
+ * disconnect) can mechanically distinguish a running job from a dead one:
+ * non-terminal state + dead PID + no result document = dead. The result
+ * document stays authoritative once the run completes. */
+export interface QaRunStatusDocument {
+    schema_version: typeof QA_RUN_STATUS_SCHEMA_VERSION;
+    run_id: string;
+    /** PID of the process executing the matrix (the detach parent records the
+     * child's PID in its initial `launching` write; the child overwrites). */
+    pid: number;
+    state: QaRunStatusState;
+    /** Stage currently executing; null before plan and after completion. */
+    stage: QaRunStage | null;
+    started_at: string;
+    /** Heartbeat. Stage boundaries and a periodic timer both refresh it. */
+    updated_at: string;
+    /** Present only while state is "queued". */
+    queue?: {
+        resource: string;
+        waiting_since: string;
+    };
+    /** Present only once state is "completed". */
+    verdict?: QaRunVerdict;
+}
+/** Host-pressure sample. Captured at start, at every stage boundary, and at
+ * finish, so an incomplete run carries the load context that produced it and
+ * names the other heavy jobs it was competing with. */
+export interface QaRunHostSample {
+    captured_at: string;
+    loadavg_1m: number;
+    free_mem_bytes: number;
+    total_mem_bytes: number;
+    cpu_count: number;
+    /** Other holders of the admission resource at sample time. Present only
+     * when the run queued; an empty array means the run had the host to
+     * itself. This is what turns "it was slow" into "it was slow because these
+     * three jobs held slots". */
+    competing?: Array<{
+        label: string;
+        pid: number;
+    }>;
+}
 export interface QaRunResult {
     schema_version: typeof QA_RUN_RESULT_SCHEMA_VERSION;
+    /** Runner-executed or hand-recorded. A manual result never reads passed. */
+    evidence_source: QaRunEvidenceSource;
+    run: QaRunIdentity;
+    host: {
+        start: QaRunHostSample;
+        finish: QaRunHostSample;
+        /** Sample taken as each stage began, so a stall is attributable to the
+         * stage that was running and the load at that moment. */
+        stages?: Partial<Record<QaRunStage, QaRunHostSample>>;
+    };
+    /** Null when the run never completed a stage cleanly (e.g. plan failed). */
+    last_completed_stage: QaRunStage | null;
     target: string;
     tested_revision?: string;
     mode: "signoff" | "review";
@@ -116,6 +277,11 @@ export interface QaRunResult {
     contexts: QaRunContext[];
     commands: QaRunCommandOutcome[];
     critique: QaRunCritiqueOutcome[];
+    /** Present once the judge stage ran (even when it skipped for lack of a
+     * provider); absent when the run stopped before it. */
+    critique_pool?: QaRunCritiquePool;
+    /** Present once the capture stage wrote at least one context. */
+    review_pack?: QaRunReviewPack;
     snapshot: {
         saved: boolean;
         path?: string;
@@ -124,9 +290,17 @@ export interface QaRunResult {
         plan: number;
         gates: number;
         interactions: number;
+        /** Browser time: rendering every context into the review pack. */
+        capture: number;
+        /** Judge time: vision calls over the pack, no browser open. */
         critique: number;
         snapshot: number;
+        /** Runner stages only — admission queue wait is deliberately excluded
+         * (see `queue`) so total stays pure runner time. */
         total: number;
+        /** Milliseconds spent waiting for a machine-wide admission slot before
+         * any browser work. Absent when the run did not queue. */
+        queue?: number;
     };
     blockers: QaRunBlocker[];
     verdict: QaRunVerdict;
@@ -153,21 +327,51 @@ export declare function contextIdFor(context: QaContext): string;
  * returned list is what the runner executes and what the result reports.
  */
 export declare function mergeCoverage(manifest: QaManifest, job: QaRunJob): QaRunContext[];
+/** SHA-256 hex digest over the effective validated job (after the CLI merges
+ * its authoritative `target` and `mode`). `policy` is excluded: concurrency,
+ * timeout, and metered-critique knobs change how the run executes, not what
+ * it proves, and CLI flags mutate them after the job file is read — including
+ * them would make the same job file verify differently across invocations. */
+export declare function computeJobDigest(job: QaRunJob): string;
+export interface QaEvidenceExpectations {
+    /** Exact run ID the caller expects (from the invocation it just made). */
+    run_id?: string;
+    /** Revision the evidence must have tested. A result whose revision_source
+     * is `unknown` cannot satisfy a revision expectation — fail-closed. */
+    tested_revision?: string;
+    /** Digest of the effective job the evidence must have run. */
+    job_digest?: string;
+    /** ISO-8601 floor: a run started before this instant is stale. */
+    not_started_before?: string;
+    /** Maximum age of completed_at in milliseconds, evaluated against `now`. */
+    max_age_ms?: number;
+    /** Evaluation instant for max_age_ms (ISO-8601; default: current time). */
+    now?: string;
+    /** Directory the result file was read from. Compared against the recorded
+     * run.out_dir: a moved or copied result is not evidence for its new home. */
+    found_in_dir?: string;
+}
+export interface QaEvidenceAssessment {
+    fresh: boolean;
+    /** Empty when fresh; each entry names one independent staleness reason. */
+    reasons: string[];
+    run?: QaRunIdentity;
+    verdict?: QaRunVerdict;
+}
 /**
- * Compute the terminal verdict from completed evidence. The rules are the
- * existing page-QA signoff contract, fail-closed:
- *   - any blocker → incomplete (a blocker is a fact the run could not
- *     establish, so a defect cannot be ruled out);
- *   - any failed or unknown command/critique outcome → failed when the check
- *     completed and found a defect, incomplete when the outcome is unknown;
- *   - signoff mode additionally requires the snapshot to have been saved.
- * `passed` is only reachable when every input proves out.
+ * Assess whether a result document is fresh evidence for the invocation the
+ * caller has in mind. Fail-closed: a document without a verifiable identity
+ * block (schema v1 or foreign JSON) is stale by definition, and every
+ * expectation mismatch is reported, not just the first.
  */
+export declare function assessQaRunEvidence(document: unknown, expectations?: QaEvidenceExpectations): QaEvidenceAssessment;
 export declare function computeVerdict(input: {
     mode: QaRunJob["mode"];
     blockers: QaRunBlocker[];
     commands: QaRunCommandOutcome[];
     critique: QaRunCritiqueOutcome[];
     snapshotSaved: boolean;
+    /** Defaults to `runner`. `manual` caps the verdict at incomplete. */
+    evidenceSource?: QaRunEvidenceSource;
 }): QaRunVerdict;
 //# sourceMappingURL=qa-run-contracts.d.ts.map

package/dist/lib/browser/qa-run-contracts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"qa-run-contracts.d.ts","sourceRoot":"","sources":["../../../src/lib/browser/qa-run-contracts.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"qa-run-contracts.d.ts","sourceRoot":"","sources":["../../../src/lib/browser/qa-run-contracts.ts"],"names":[],"mappings":"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"}

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

@@ -16,8 +16,20 @@
 //     secret-shaped fields before any browser or model work starts.
 //
 // Toolkit tier: this module must not import src/core (layering check).
+import { createHash } from "node:crypto";
 export const QA_RUN_JOB_SCHEMA_VERSION = 1;
-export const QA_RUN_RESULT_SCHEMA_VERSION = 1;
+export const QA_RUN_RESULT_SCHEMA_VERSION = 4;
+/** Runner stages in execution order. `last_completed_stage` names the last
+ * one that finished without contributing a blocker. */
+export const QA_RUN_STAGES = [
+    "plan",
+    "gates",
+    "interactions",
+    "capture",
+    "critique",
+    "snapshot",
+];
+export const QA_RUN_STATUS_SCHEMA_VERSION = 1;
 // ---------------------------------------------------------------------------
 // Job validation
 // ---------------------------------------------------------------------------
@@ -162,6 +174,30 @@ export function validateQaRunJob(value) {
                 errors.push("policy.command_timeout_ms must be an integer ≥ 1000");
             }
         }
+        if (p?.run_deadline_ms !== undefined) {
+            const n = p.run_deadline_ms;
+            if (typeof n !== "number" || !Number.isInteger(n) || n < 10_000) {
+                errors.push("policy.run_deadline_ms must be an integer ≥ 10000");
+            }
+        }
+        if (p?.critique_max_tiles !== undefined) {
+            const n = p.critique_max_tiles;
+            if (typeof n !== "number" || !Number.isInteger(n) || n < 1 || n > 200) {
+                errors.push("policy.critique_max_tiles must be an integer between 1 and 200");
+            }
+        }
+        if (p?.critique_pool !== undefined) {
+            const n = p.critique_pool;
+            if (typeof n !== "number" || !Number.isInteger(n) || n < 1 || n > 16) {
+                errors.push("policy.critique_pool must be an integer between 1 and 16");
+            }
+        }
+        if (p?.review_pack_retention_minutes !== undefined) {
+            const n = p.review_pack_retention_minutes;
+            if (typeof n !== "number" || !Number.isInteger(n) || n < 1 || n > 43_200) {
+                errors.push("policy.review_pack_retention_minutes must be an integer between 1 and 43200");
+            }
+        }
     }
     scanForSecrets(job, "job", errors);
     if (errors.length > 0)
@@ -211,11 +247,110 @@ export function mergeCoverage(manifest, job) {
  *   - signoff mode additionally requires the snapshot to have been saved.
  * `passed` is only reachable when every input proves out.
  */
+// ---------------------------------------------------------------------------
+// Run identity: job digest + evidence assessment
+// ---------------------------------------------------------------------------
+/** Recursively key-sort plain objects so the digest is stable under key
+ * order. Arrays keep their order — it is semantically meaningful (contexts,
+ * argv arrays). */
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (value && typeof value === "object") {
+        const record = value;
+        const sorted = {};
+        for (const key of Object.keys(record).sort())
+            sorted[key] = canonicalize(record[key]);
+        return sorted;
+    }
+    return value;
+}
+/** SHA-256 hex digest over the effective validated job (after the CLI merges
+ * its authoritative `target` and `mode`). `policy` is excluded: concurrency,
+ * timeout, and metered-critique knobs change how the run executes, not what
+ * it proves, and CLI flags mutate them after the job file is read — including
+ * them would make the same job file verify differently across invocations. */
+export function computeJobDigest(job) {
+    const { policy: _policy, ...identityBearing } = job;
+    return createHash("sha256")
+        .update(JSON.stringify(canonicalize(identityBearing)))
+        .digest("hex");
+}
+/**
+ * Assess whether a result document is fresh evidence for the invocation the
+ * caller has in mind. Fail-closed: a document without a verifiable identity
+ * block (schema v1 or foreign JSON) is stale by definition, and every
+ * expectation mismatch is reported, not just the first.
+ */
+export function assessQaRunEvidence(document, expectations = {}) {
+    const reasons = [];
+    if (!document || typeof document !== "object" || Array.isArray(document)) {
+        return { fresh: false, reasons: ["document is not a result object"] };
+    }
+    const result = document;
+    if (result.schema_version !== QA_RUN_RESULT_SCHEMA_VERSION) {
+        return {
+            fresh: false,
+            reasons: [
+                `schema_version is ${JSON.stringify(result.schema_version)}, not ` +
+                    `${QA_RUN_RESULT_SCHEMA_VERSION} — pre-identity results carry nothing to verify`,
+            ],
+        };
+    }
+    const run = result.run;
+    if (!run ||
+        typeof run.run_id !== "string" ||
+        typeof run.started_at !== "string" ||
+        typeof run.completed_at !== "string" ||
+        typeof run.job_digest !== "string") {
+        return { fresh: false, reasons: ["result carries no complete run-identity block"] };
+    }
+    if (expectations.run_id !== undefined && run.run_id !== expectations.run_id) {
+        reasons.push(`run_id ${run.run_id} is not the expected ${expectations.run_id}`);
+    }
+    if (expectations.job_digest !== undefined && run.job_digest !== expectations.job_digest) {
+        reasons.push("job_digest does not match the expected job definition");
+    }
+    if (expectations.tested_revision !== undefined) {
+        if (run.revision_source === "unknown" || run.tested_revision === undefined) {
+            reasons.push(`a revision expectation was given but the run recorded revision_source "unknown"`);
+        }
+        else if (run.tested_revision !== expectations.tested_revision) {
+            reasons.push(`tested_revision ${run.tested_revision} is not the expected ${expectations.tested_revision}`);
+        }
+    }
+    if (expectations.not_started_before !== undefined) {
+        if (Date.parse(run.started_at) < Date.parse(expectations.not_started_before)) {
+            reasons.push(`run started ${run.started_at}, before the freshness floor ${expectations.not_started_before}`);
+        }
+    }
+    if (expectations.max_age_ms !== undefined) {
+        const now = expectations.now !== undefined ? Date.parse(expectations.now) : Date.now();
+        const age = now - Date.parse(run.completed_at);
+        if (Number.isNaN(age) || age > expectations.max_age_ms) {
+            reasons.push(`run completed ${run.completed_at}, older than the ${expectations.max_age_ms}ms maximum age`);
+        }
+    }
+    if (expectations.found_in_dir !== undefined && run.out_dir !== expectations.found_in_dir) {
+        reasons.push(`result was found in ${expectations.found_in_dir} but records out_dir ${run.out_dir} — ` +
+            "a moved or copied result is not evidence for its new location");
+    }
+    return {
+        fresh: reasons.length === 0,
+        reasons,
+        run: run,
+        ...(result.verdict !== undefined ? { verdict: result.verdict } : {}),
+    };
+}
 export function computeVerdict(input) {
     const failed = input.commands.some((command) => command.outcome === "failed") ||
         input.critique.some((entry) => entry.outcome === "failed");
     if (failed)
         return "failed";
+    // Hand-recorded evidence can prove a defect but never its absence: nothing
+    // re-executable ran, so a manual result stops at incomplete by contract.
+    if (input.evidenceSource === "manual")
+        return "incomplete";
     const unknown = input.commands.some((command) => command.outcome === "unknown") ||
         input.critique.some((entry) => entry.outcome === "unknown");
     if (input.blockers.length > 0 || unknown)

package/dist/lib/browser/qa-run.d.ts

@@ -1,10 +1,36 @@
+import { type CritiqueProvider } from "./critique.js";
 import { type QaRunJob, type QaRunResult } 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 { type QaSnapshotStoreOptions } 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 declare const QA_RUN_HEADLESS_ONLY_ENV = "HARNERY_CRITIQUE_HEADLESS_ONLY";
 /** Result document written into the run's output directory. */
 export declare 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 declare 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 declare function writeLatestPointer(outParent: string, input: QaRunLatestPointerInput): string;
+/** 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 declare 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 declare const QA_RUN_JOB_FILENAME = "job.json";
 export interface QaRunExecOptions {
     /** Hard per-command timeout in milliseconds. */
     timeoutMs: number;
@@ -22,14 +48,34 @@ 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 declare const QA_RUN_KILL_GRACE_MS = 5000;
+/** 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 declare const defaultQaRunExec: QaRunExec;
 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[];
@@ -39,13 +85,57 @@ 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;
 }
 /**
  * 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 declare function runQaMatrix(options: QaRunMatrixOptions): Promise<QaRunResult>;
 //# sourceMappingURL=qa-run.d.ts.map

package/dist/lib/browser/qa-run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"qa-run.d.ts","sourceRoot":"","sources":["../../../src/lib/browser/qa-run.ts"],"names":[],"mappings":"AAiBA,OAAO,EAQL,KAAK,QAAQ,EACb,KAAK,WAAW,EACjB,MAAM,uBAAuB,CAAC;AAE/B;;gFAEgF;AAChF,eAAO,MAAM,wBAAwB,mCAAmC,CAAC;AAEzE,+DAA+D;AAC/D,eAAO,MAAM,sBAAsB,wBAAwB,CAAC;AAiB5D,MAAM,WAAW,gBAAgB;IAC/B,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf;8CAC0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,sEAAsE;AACtE,MAAM,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;AAEhG;mEACmE;AACnE,eAAO,MAAM,gBAAgB,EAAE,SAyC3B,CAAC;AAEL,MAAM,WAAW,kBAAkB;IACjC,4EAA4E;IAC5E,GAAG,EAAE,QAAQ,CAAC;IACd,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf;oDACgD;IAChD,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IAC7B,0DAA0D;IAC1D,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AA2JD;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC,CA0enF"}
+{"version":3,"file":"qa-run.d.ts","sourceRoot":"","sources":["../../../src/lib/browser/qa-run.ts"],"names":[],"mappings":"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"}