harnery 0.45.2 → 0.46.1

package/src/lib/browser/geometry.ts

@@ -151,6 +151,8 @@ export interface CrowdResult {
 }
 
 export interface LayoutLintRequest {
+  /** Explicit traversal budget; omission retains each rule's existing limit. */
+  scanNodeBudget?: number;
   align: Array<{ selector: string; axis: LayoutAxis; tolerancePx: number }>;
   gap: Array<{
     selector: string;
@@ -204,9 +206,26 @@ export function intersectRects(a: LayoutRect, b: LayoutRect): LayoutRect | null
  */
 export function buildLayoutLintCheck(): (request: LayoutLintRequest) => LayoutLintResult {
   return (request) => {
-    const CHILD_LIMIT = 1_000;
-    const TEXT_LIMIT = 1_000;
+    if (
+      request.scanNodeBudget !== undefined &&
+      (!Number.isSafeInteger(request.scanNodeBudget) ||
+        request.scanNodeBudget < 1 ||
+        request.scanNodeBudget > 100_000)
+    ) {
+      throw new Error("scanNodeBudget must be an integer from 1 to 100000.");
+    }
+    const CHILD_LIMIT = request.scanNodeBudget ?? 1_000;
+    const TEXT_LIMIT = request.scanNodeBudget ?? 1_000;
     const ISSUE_LIMIT = 100;
+    const translationOnly = (transform: string): boolean => {
+      if (!transform || transform === "none") return true;
+      try {
+        const matrix = new DOMMatrixReadOnly(transform);
+        return matrix.is2D && matrix.a === 1 && matrix.b === 0 && matrix.c === 0 && matrix.d === 1;
+      } catch {
+        return false;
+      }
+    };
     // Chromium geometry is fractional even when authored CSS is integral.
     // Differences below half a CSS pixel are rasterization noise, not clipping.
     const SUBPIXEL_EPSILON = 0.5;
@@ -673,17 +692,22 @@ export function buildLayoutLintCheck(): (request: LayoutLintRequest) => LayoutLi
         container: Element,
         seed: LayoutRect,
         seedLabel: string,
-      ): { allowed: LayoutRect; clippedBy: { x: string; y: string } } => {
+      ): { allowed: LayoutRect; clippedBy: { x: string; y: string }; supported: boolean } => {
         let allowed = { ...seed };
+        let supported = true;
         const clippedBy = { x: seedLabel, y: seedLabel };
         const free = { x: false, y: false };
         let current: Element | null = start;
         while (current && container.contains(current)) {
           const style = getComputedStyle(current);
-          if (style.clipPath && style.clipPath !== "none")
+          if (style.clipPath && style.clipPath !== "none") {
             unsupported.add(`${labelOf(current)}:clip-path`);
-          if (style.transform && style.transform !== "none")
+            supported = false;
+          }
+          if (!translationOnly(style.transform)) {
             unsupported.add(`${labelOf(current)}:transform`);
+            supported = false;
+          }
           // The container bounds by default even when it does not CSS-clip,
           // since it is the scope the caller asked about -- but a scroller
           // hands its axis back whether it is the scope or an ancestor.
@@ -727,7 +751,7 @@ export function buildLayoutLintCheck(): (request: LayoutLintRequest) => LayoutLi
           if (scope) break;
           current = current.parentElement;
         }
-        return { allowed, clippedBy };
+        return { allowed, clippedBy, supported };
       };
 
       const nearestBlockOwner = (node: Node, scope: Element): Element | null => {
@@ -755,6 +779,15 @@ export function buildLayoutLintCheck(): (request: LayoutLintRequest) => LayoutLi
             excluded.push({ index, tag: element.tagName.toLowerCase(), reason: "visually-hidden" });
             return;
           }
+          const ownStyle = getComputedStyle(element);
+          if (!translationOnly(ownStyle.transform)) {
+            unsupported.add(`${labelOf(element)}:transform`);
+            return;
+          }
+          if (ownStyle.clipPath && ownStyle.clipPath !== "none") {
+            unsupported.add(`${labelOf(element)}:clip-path`);
+            return;
+          }
           const rect = element.getBoundingClientRect();
           if (rect.width <= 0 || rect.height <= 0) {
             excluded.push({ index, tag: element.tagName.toLowerCase(), reason: "zero-area" });
@@ -783,7 +816,8 @@ export function buildLayoutLintCheck(): (request: LayoutLintRequest) => LayoutLi
             seedLabel = labelOf(owner);
           }
           const chain = clipChain(element.parentElement, container, seed, seedLabel);
-          recordIssue(measure(element, index, false), chain.allowed, chain.clippedBy);
+          if (chain.supported)
+            recordIssue(measure(element, index, false), chain.allowed, chain.clippedBy);
         });
 
         const walker = document.createTreeWalker(container, NodeFilter.SHOW_TEXT);
@@ -825,7 +859,7 @@ export function buildLayoutLintCheck(): (request: LayoutLintRequest) => LayoutLi
           let current: Element | null = owner;
           while (current && container.contains(current)) {
             const transform = getComputedStyle(current).transform;
-            if (transform && transform !== "none") {
+            if (!translationOnly(transform)) {
               unsupported.add(`${labelOf(current)}:transform`);
               transformed = true;
               break;
@@ -851,6 +885,7 @@ export function buildLayoutLintCheck(): (request: LayoutLintRequest) => LayoutLi
             seed.width = Math.max(0, seed.right - seed.left);
           }
           const chain = clipChain(owner, container, seed, labelOf(owner));
+          if (!chain.supported) continue;
           const allowed = chain.allowed;
           const clippedBy = chain.clippedBy;
           const range = document.createRange();
@@ -877,7 +912,7 @@ export function buildLayoutLintCheck(): (request: LayoutLintRequest) => LayoutLi
       // Border radius keeps the rectangular padding-box contract; only shapes
       // the rectangle cannot certify contribute to unsupported geometry.
       const outcome: LayoutOutcome =
-        issues.length > 0 ? "fail" : unsupported.size > 0 ? "unknown" : "pass";
+        issues.length > 0 ? "fail" : unsupported.size > 0 || truncated ? "unknown" : "pass";
       return {
         rule: "clip" as const,
         selector,
@@ -966,7 +1001,7 @@ export function buildLayoutLintCheck(): (request: LayoutLintRequest) => LayoutLi
     // and badges (radius ≥ half their smaller side) are inline controls, not
     // layout cards, and are excluded too. Plain blocks with no panel chrome
     // and no panel descendants stay out of the peer list.
-    const PARENT_LIMIT = 2000;
+    const PARENT_LIMIT = request.scanNodeBudget ?? 2000;
     const PANEL_DESCENDANT_LIMIT = 100;
     const OVERLAP_EPS = 1;
     const STRUCTURAL_TAGS = new Set([
@@ -1036,13 +1071,18 @@ export function buildLayoutLintCheck(): (request: LayoutLintRequest) => LayoutLi
     const collectPanelFaces = (
       element: Element,
       selfIsPanel: boolean,
+      onTruncated: () => void,
     ): LayoutElementMeasurement[] => {
       if (selfIsPanel) return [measure(element, 0, false)];
       const faces: LayoutElementMeasurement[] = [];
       const descendants = element.querySelectorAll("*");
-      for (let i = 0; i < descendants.length && faces.length < PANEL_DESCENDANT_LIMIT; i++) {
+      for (let i = 0; i < descendants.length; i++) {
         const child = descendants[i];
         if (!child || !isInFlowBox(child) || !isPanel(child)) continue;
+        if (faces.length >= PANEL_DESCENDANT_LIMIT) {
+          onTruncated();
+          break;
+        }
         faces.push(measure(child, faces.length, false));
       }
       return faces;
@@ -1054,6 +1094,7 @@ export function buildLayoutLintCheck(): (request: LayoutLintRequest) => LayoutLi
     // panels separated only by chrome still get a face-to-face check.
     const collectCrowdPeers = (
       parent: Element,
+      onTruncated: () => void,
     ): Array<{
       kind: "panel" | "composite";
       faces: LayoutElementMeasurement[];
@@ -1063,11 +1104,12 @@ export function buildLayoutLintCheck(): (request: LayoutLintRequest) => LayoutLi
         faces: LayoutElementMeasurement[];
       }> = [];
       const children = [...parent.children];
+      if (children.length > CHILD_LIMIT) onTruncated();
       for (let index = 0; index < children.length && index < CHILD_LIMIT; index++) {
         const element = children[index];
         if (!element || !isInFlowBox(element)) continue;
         const selfIsPanel = isPanel(element);
-        const faces = collectPanelFaces(element, selfIsPanel);
+        const faces = collectPanelFaces(element, selfIsPanel, onTruncated);
         if (faces.length === 0) continue;
         out.push({
           kind: selfIsPanel ? "panel" : "composite",
@@ -1149,7 +1191,9 @@ export function buildLayoutLintCheck(): (request: LayoutLintRequest) => LayoutLi
       const limit = Math.min(parents.length, PARENT_LIMIT);
       for (let p = 0; p < limit; p++) {
         const parent = parents[p]!;
-        const peers = collectCrowdPeers(parent);
+        const peers = collectCrowdPeers(parent, () => {
+          truncated = true;
+        });
         for (let i = 1; i < peers.length; i++) {
           const beforePeer = peers[i - 1]!;
           const afterPeer = peers[i]!;
@@ -1178,7 +1222,12 @@ export function buildLayoutLintCheck(): (request: LayoutLintRequest) => LayoutLi
         rule: "crowd" as const,
         selector,
         found: true,
-        outcome: issues.length > 0 ? ("fail" as const) : ("pass" as const),
+        outcome:
+          issues.length > 0
+            ? ("fail" as const)
+            : truncated
+              ? ("unknown" as const)
+              : ("pass" as const),
         minGapPx,
         issues,
         truncated,

package/src/lib/browser/index.ts

@@ -38,15 +38,20 @@ export type {
   TruncationResult,
 } from "./content-checks.js";
 export {
+  addCritiqueUsage,
   bandRects,
   type CritiqueCoverage,
   type CritiqueFinding,
   type CritiqueProvider,
   type CritiqueResult,
   type CritiqueTile,
+  type CritiqueUsage,
+  type CritiqueUsageTotals,
   DEFAULT_CRITIQUE_RUBRIC,
+  formatCritiqueUsage,
   normalizeFindings,
   runCritique,
+  sumCritiqueUsage,
   tilesFromFullPage,
 } from "./critique.js";
 export {

package/src/lib/browser/page-review-contracts.ts

@@ -6,7 +6,12 @@ export const PAGE_REVIEW_CAPTURE_PLAN_SCHEMA = "harnery-page-review-capture-plan
 export const PAGE_REVIEW_NATIVE_EVIDENCE_SCHEMA = "harnery-page-review-native-evidence/v2";
 export const PAGE_REVIEW_DECISIONS_SCHEMA = "harnery-page-review-decisions/v1";
 export const PAGE_REVIEW_DEFAULT_TILE_BUDGET = 96;
-export const PAGE_REVIEW_MAX_TILE_BUDGET = 400;
+/** Hard ceiling on vision calls in one critique invocation (a qa-run pack,
+ * a review-pack judge, or a browse --check-critique). Each call is a separate
+ * model session, so the ceiling bounds what one run can spend whatever the
+ * job asks for. Pages that need more bands than this get a sampled review
+ * (ADR 0224). */
+export const PAGE_REVIEW_MAX_TILE_BUDGET = 160;
 
 /** Rectangles are native image pixels, never CSS pixels or overview pixels. */
 export interface PageReviewRect {

package/src/lib/browser/page-review-judge.ts

@@ -9,8 +9,20 @@
 //
 // Toolkit tier: this module must not import src/core (layering check).
 
-import type { CritiqueFinding, CritiqueProvider, CritiqueTile } from "./critique.js";
-import type { PageReviewNativeEvidence } from "./page-review-contracts.js";
+import {
+  addCritiqueUsage,
+  type CritiqueFinding,
+  type CritiqueProvider,
+  type CritiqueTile,
+  type CritiqueUsage,
+  type CritiqueUsageTotals,
+  formatCritiqueUsage,
+  sumCritiqueUsage,
+} from "./critique.js";
+import {
+  PAGE_REVIEW_MAX_TILE_BUDGET,
+  type PageReviewNativeEvidence,
+} from "./page-review-contracts.js";
 import {
   buildPackNativeEvidence,
   PAGE_REVIEW_CRITIQUE_SCHEMA,
@@ -69,6 +81,8 @@ export interface JudgePageReviewPackResult {
   tiles_reused: number;
   outcome: "pass" | "fail" | "skipped" | "incomplete";
   provider_meta?: Record<string, unknown>;
+  /** Tokens summed over the tiles sent to the provider; absent when none were. */
+  usage?: CritiqueUsageTotals;
 }
 
 interface WorkItem {
@@ -262,9 +276,24 @@ export async function judgePageReviewPack(
   });
 
   let meta: Record<string, unknown> | undefined;
+  let usage: CritiqueUsageTotals | undefined;
   let concurrency = 0;
   const tileTimings: Array<QaRunCritiqueTileTiming | undefined> = new Array(work.length);
-  if (provider && work.length > 0) {
+  // Filled, not sparse: filter() skips holes, which would drop unreported tiles.
+  const tileUsage: Array<CritiqueUsage | undefined> = Array.from(
+    { length: work.length },
+    () => undefined,
+  );
+  // Every vision call is a separate model session. A pack above the ceiling
+  // (an older pack, or one assembled by hand) is refused whole rather than
+  // judged in part, so no flag or pack can turn one judge into hundreds of calls.
+  const overCeiling =
+    work.length > PAGE_REVIEW_MAX_TILE_BUDGET
+      ? `pack needs ${work.length} vision calls, above the per-run ceiling of ` +
+        `${PAGE_REVIEW_MAX_TILE_BUDGET}; recapture it with a smaller tile budget`
+      : undefined;
+  if (overCeiling) log(`judge: refused — ${overCeiling}`);
+  if (provider && work.length > 0 && !overCeiling) {
     concurrency = Math.max(
       1,
       Math.min(options.concurrency ?? provider.concurrency ?? 4, work.length),
@@ -283,7 +312,14 @@ export async function judgePageReviewPack(
         const tileStarted = performance.now();
         let tileOutcome: QaRunCritiqueTileTiming["outcome"] = "passed";
         try {
-          const found = await provider({ url: item.url, rubric: item.rubric, tile: item.tile });
+          const found = await provider({
+            url: item.url,
+            rubric: item.rubric,
+            tile: item.tile,
+            reportUsage: (usage) => {
+              tileUsage[i] = addCritiqueUsage(tileUsage[i], usage);
+            },
+          });
           for (const finding of found) {
             entry.findings.push({ ...finding, tile: item.tile.index, tile_id: item.tile.id });
           }
@@ -302,12 +338,16 @@ export async function judgePageReviewPack(
             tile_id: item.tile.id,
             duration_ms: Math.max(0, Math.round(performance.now() - tileStarted)),
             outcome: tileOutcome,
+            ...(tileUsage[i] ? { usage: tileUsage[i] } : {}),
           };
         }
       }
     };
     await Promise.all(Array.from({ length: concurrency }, () => worker()));
     meta = provider.meta?.();
+    // Only tiles the pool reached count; an unreached tile spent nothing.
+    usage = sumCritiqueUsage(tileUsage.filter((_, index) => tileTimings[index] !== undefined));
+    log(`judge: ${formatCritiqueUsage(usage)}`);
   } else if (provider) {
     meta = provider.meta?.();
   }
@@ -319,11 +359,13 @@ export async function judgePageReviewPack(
     const unjudged = entry.review.filter((tile) => !entry.judged.has(tile.id)).length;
     const outcome: JudgedContext["outcome"] = !provider
       ? "skipped"
-      : findings.some((f) => f.severity === "high")
-        ? "fail"
-        : unjudged > 0 || entry.record.capture_incomplete
-          ? "incomplete"
-          : "pass";
+      : overCeiling
+        ? "incomplete"
+        : findings.some((f) => f.severity === "high")
+          ? "fail"
+          : unjudged > 0 || entry.record.capture_incomplete
+            ? "incomplete"
+            : "pass";
     return {
       context_id: entry.record.id,
       provider: provider ? label : "none",
@@ -334,12 +376,14 @@ export async function judgePageReviewPack(
       outcome,
       findings,
       coverage: entry.record.coverage,
-      ...(provider
-        ? {}
-        : {
+      ...(!provider
+        ? {
             error:
               "no critiqueProvider injected by the host (see HarneryProgramContext.critiqueProvider)",
-          }),
+          }
+        : overCeiling
+          ? { error: overCeiling }
+          : {}),
       record: entry.record,
       evidence: {
         schema: PAGE_REVIEW_CRITIQUE_SCHEMA,
@@ -381,6 +425,7 @@ export async function judgePageReviewPack(
     tiles_reused: tilesReused,
     outcome,
     ...(meta ? { provider_meta: meta } : {}),
+    ...(usage ? { usage } : {}),
   };
 }
 

package/src/lib/browser/page-review-pack.ts

@@ -328,6 +328,9 @@ export interface PageReviewCritiqueRecord {
   outcome: "pass" | "fail" | "skipped" | "incomplete";
   findings: Array<CritiqueFinding & { tile_id: string }>;
   coverage: CritiqueCoverage;
+  /** Set by a signoff whose complete review would exceed the per-run tile
+   * ceiling: the capped coverage is the accepted, sampled review (ADR 0224). */
+  coverage_mode?: "sampled";
   error?: string;
   evidence?: {
     schema: string;
@@ -1364,7 +1367,12 @@ export function resolvePackVerdict(
         (row.outcome === "skipped" && machine_outcome !== "skipped"),
     ) ??
       false) ||
-    manifest.contexts?.some((c) => c.capture_incomplete || c.coverage.capped) ||
+    manifest.contexts?.some(
+      (c) =>
+        c.capture_incomplete ||
+        (c.coverage.capped &&
+          !critique?.some((row) => row.context_id === c.id && row.coverage_mode === "sampled")),
+    ) ||
     false;
   const reviewed_outcome: PageReviewVerdict["reviewed_outcome"] =
     blocking > 0
@@ -2067,8 +2075,11 @@ export function renderReviewMarkdown(
   );
   lines.push("|---|---|---|---|---|---|---|---|---|");
   for (const ctx of contexts) {
+    const sampled = manifest.critique?.some(
+      (row) => row.context_id === ctx.id && row.coverage_mode === "sampled",
+    );
     const cov = ctx.coverage.capped
-      ? `${ctx.coverage.bands_reviewed}/${ctx.coverage.bands_total} bands, capped`
+      ? `${ctx.coverage.bands_reviewed}/${ctx.coverage.bands_total} bands, ${sampled ? "sampled" : "capped"}`
       : "complete";
     const contacts = ctx.contact_sheet
       ? `[${CONTACT_SHEET_FILENAME}](${ctx.contact_sheet.file})`

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

@@ -18,6 +18,8 @@
 // Toolkit tier: this module must not import src/core (layering check).
 
 import { createHash } from "node:crypto";
+import type { CritiqueUsage, CritiqueUsageTotals } from "./critique.js";
+import { PAGE_REVIEW_MAX_TILE_BUDGET } from "./page-review-contracts.js";
 import type { QaContext, QaManifest } from "./qa-plan.js";
 
 export const QA_RUN_JOB_SCHEMA_VERSION = 1 as const;
@@ -152,6 +154,9 @@ export interface QaRunCritiqueTileTiming {
   tile_id: string;
   duration_ms: number;
   outcome: "passed" | "failed";
+  /** Tokens the provider reported for this tile, retries included. Absent
+   * when the backend reports none; that is unknown, not zero. */
+  usage?: CritiqueUsage;
 }
 
 /** What share of the page the critique tiles covered, lifted from the browse
@@ -184,6 +189,11 @@ export interface QaRunCritiqueOutcome {
   dismissed?: Array<{ finding_key: string; target: string; disposition: string }>;
   /** Tile coverage of the page. Absent when the capture died or reported none. */
   coverage?: QaRunCritiqueCoverage;
+  /** `full`: every band reviewed. `capped`: bands left out; a signoff blocker.
+   * `sampled`: signoff on a page whose complete review would exceed the
+   * per-run tile ceiling; every edge band, gate hit, and required scope was
+   * reviewed and the uncovered intervals are listed in `coverage` (ADR 0224). */
+  coverage_mode?: "full" | "capped" | "sampled";
 }
 
 /** The judge stage as one unit: every context's tiles through one bounded
@@ -199,6 +209,8 @@ export interface QaRunCritiquePool {
   latency_ms?: Record<string, QaRunCritiqueLatency>;
   /** One entry per attempted tile, in context and tile order. */
   tile_timings?: QaRunCritiqueTileTiming[];
+  /** Tokens summed over the attempted tiles. */
+  usage?: CritiqueUsageTotals;
 }
 
 /** Where the run's page review pack lives: the on-disk evidence an agent can
@@ -518,8 +530,15 @@ export function validateQaRunJob(value: unknown): QaRunJobValidation {
     }
     if (p?.critique_tile_budget !== undefined) {
       const n = p.critique_tile_budget;
-      if (typeof n !== "number" || !Number.isInteger(n) || n < 8 || n > 400) {
-        errors.push("policy.critique_tile_budget must be an integer between 8 and 400");
+      if (
+        typeof n !== "number" ||
+        !Number.isInteger(n) ||
+        n < 8 ||
+        n > PAGE_REVIEW_MAX_TILE_BUDGET
+      ) {
+        errors.push(
+          `policy.critique_tile_budget must be an integer between 8 and ${PAGE_REVIEW_MAX_TILE_BUDGET}`,
+        );
       }
     }
     if (p?.command_concurrency !== undefined) {
@@ -542,8 +561,15 @@ export function validateQaRunJob(value: unknown): QaRunJobValidation {
     }
     if (p?.critique_max_tiles !== undefined) {
       const n = p.critique_max_tiles;
-      if (typeof n !== "number" || !Number.isInteger(n) || n < 1 || n > 400) {
-        errors.push("policy.critique_max_tiles must be an integer between 1 and 400");
+      if (
+        typeof n !== "number" ||
+        !Number.isInteger(n) ||
+        n < 1 ||
+        n > PAGE_REVIEW_MAX_TILE_BUDGET
+      ) {
+        errors.push(
+          `policy.critique_max_tiles must be an integer between 1 and ${PAGE_REVIEW_MAX_TILE_BUDGET}`,
+        );
       }
     }
     if (p?.critique_pool !== undefined) {

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

@@ -24,6 +24,7 @@ import {
 } from "./page-review-budget.js";
 import {
   PAGE_REVIEW_DEFAULT_TILE_BUDGET,
+  PAGE_REVIEW_MAX_TILE_BUDGET,
   type PageReviewCapturePlan,
   type PageReviewContextAllocation,
 } from "./page-review-contracts.js";
@@ -911,10 +912,29 @@ export async function runQaMatrix(options: QaRunMatrixOptions): Promise<QaRunRes
       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 bandArgs = (ctx: QaRunContext): string[] => {
+    const args = [
+      ...contextRenderArgs(ctx),
+      ...(job.checks ?? [])
+        .filter((check) => check.contexts === undefined || check.contexts.includes(ctx.id))
+        .flatMap((check) => check.args),
+    ];
+    let requested = "1400";
+    for (let i = 0; i < args.length; i++) {
+      if (args[i] === "--check-critique-band") requested = args[i + 1] ?? "";
+      else if (args[i]?.startsWith("--check-critique-band=")) {
+        requested = args[i]!.slice("--check-critique-band=".length);
+      }
+    }
+    // A larger explicit request needs a declared route budget. Missing or
+    // invalid metadata must not turn capture planning into an unbounded path.
+    const budget = provider?.tileBudgetPx;
+    const cap = budget !== undefined && Number.isFinite(budget) && budget >= 200 ? budget : 1400;
+    return [
+      "--check-critique-band",
+      String(Math.max(200, Math.min(Number.parseInt(requested, 10), cap))),
+    ];
+  };
   const scopeArgs =
     visual === "full-page"
       ? []
@@ -961,7 +981,7 @@ export async function runQaMatrix(options: QaRunMatrixOptions): Promise<QaRunRes
             "--qa-state",
             ctx.state,
             ...scopeArgs,
-            ...bandArgs,
+            ...bandArgs(ctx),
             ...critiqueMaxTilesArgs,
           ]
         : []),
@@ -1185,6 +1205,10 @@ export async function runQaMatrix(options: QaRunMatrixOptions): Promise<QaRunRes
 
   enterStage("capture");
   const captureStart = Date.now();
+  // Candidate tiles a complete review of every context would need. Above the
+  // per-run ceiling, signoff accepts a sampled critique (ADR 0224).
+  let fullCoverageTiles = 0;
+  const sampledContexts = new Set<string>();
   if (runsVisual) {
     writeFileSync(
       join(outDir, "preliminary-gates.json"),
@@ -1205,6 +1229,7 @@ export async function runQaMatrix(options: QaRunMatrixOptions): Promise<QaRunRes
           );
         return candidate;
       });
+      fullCoverageTiles = plans.reduce((sum, plan) => sum + plan.candidates.length, 0);
       const ceilings =
         job.policy?.critique_max_tiles === undefined
           ? undefined
@@ -1263,7 +1288,7 @@ export async function runQaMatrix(options: QaRunMatrixOptions): Promise<QaRunRes
           .flatMap((check) => check.args),
         ...scopeArgs,
         ...critiqueMaxTilesArgs,
-        ...bandArgs,
+        ...bandArgs(ctx),
       ];
       log(
         `capture ${ctx.id}${scopeArgs.length > 0 ? ` [${manifest.scopes.map((s) => s.selector).join(",")}]` : ""}`,
@@ -1398,6 +1423,7 @@ export async function runQaMatrix(options: QaRunMatrixOptions): Promise<QaRunRes
       provider: judged.pool.provider,
       ...(latency ? { latency_ms: latency } : {}),
       tile_timings: judged.tile_timings,
+      ...(judged.usage ? { usage: judged.usage } : {}),
     };
     for (const row of judged.contexts) {
       judgedById.set(row.context_id, row);
@@ -1477,17 +1503,43 @@ export async function runQaMatrix(options: QaRunMatrixOptions): Promise<QaRunRes
         });
       }
       // Selected bands may leave gaps anywhere. Signoff needs complete
-      // coverage, while review mode reports what was actually captured.
+      // coverage when the whole page fits under the per-run ceiling. Past
+      // it, complete coverage is unavailable by policy, so signoff accepts a
+      // sampled critique that still reviewed every edge band, gate hit, and
+      // required scope; the deterministic gates covered the whole page.
+      let coverageMode: QaRunCritiqueOutcome["coverage_mode"] = row.coverage
+        ? row.coverage.capped
+          ? "capped"
+          : "full"
+        : undefined;
       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_tile_budget (and any explicit per-context ceiling) for full signoff coverage",
-        });
+        // Without the allocation record nothing proves the required regions
+        // were selected, so a sampled signoff is refused.
+        const allocated = row.record.allocation_coverage;
+        const requiredOmitted = allocated
+          ? [
+              ...allocated.omitted_gate_hits.map((id) => `gate hit ${id}`),
+              ...allocated.omitted_scopes.map((scope) => `scope ${scope}`),
+            ]
+          : ["its allocation record (recapture this context)"];
+        if (fullCoverageTiles > PAGE_REVIEW_MAX_TILE_BUDGET && requiredOmitted.length === 0) {
+          coverageMode = "sampled";
+          sampledContexts.add(row.context_id);
+        } else {
+          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)` +
+              (requiredOmitted.length > 0
+                ? `; the budget left out ${requiredOmitted.join(", ")}. Raise ` +
+                  `policy.critique_tile_budget (at most ${PAGE_REVIEW_MAX_TILE_BUDGET}) so every gate hit and scope is reviewed`
+                : `; the full page needs ${fullCoverageTiles} tiles, so raise ` +
+                  `policy.critique_tile_budget (and any explicit per-context ceiling) to ${fullCoverageTiles}`),
+          });
+        }
       }
       const scopeById = new Map(row.record.tiles.map((tile) => [tile.id, tile.scope]));
       critique.push({
@@ -1497,6 +1549,7 @@ export async function runQaMatrix(options: QaRunMatrixOptions): Promise<QaRunRes
         tiles_reviewed: row.tiles_reviewed,
         tiles_reused: row.tiles_reused,
         outcome: contextOutcome,
+        ...(coverageMode ? { coverage_mode: coverageMode } : {}),
         ...(dismissed.length > 0 ? { dismissed } : {}),
         findings: row.findings.map((finding) => {
           const selector = scopeById.get(finding.tile_id);
@@ -1510,7 +1563,15 @@ export async function runQaMatrix(options: QaRunMatrixOptions): Promise<QaRunRes
         coverage: row.coverage,
       });
     }
-    finalizePack("critique", toCritiqueRecords(judged), judged.pool);
+    finalizePack(
+      "critique",
+      toCritiqueRecords(judged).map((record) =>
+        sampledContexts.has(record.context_id)
+          ? { ...record, coverage_mode: "sampled" as const }
+          : record,
+      ),
+      judged.pool,
+    );
   }
   if (runsVisual) restoreHeadlessOnly();
   wall.critique = Date.now() - critiqueStart;