harnery 0.45.1 → 0.46.0

package/src/lib/browser/content-checks.ts

@@ -36,7 +36,7 @@ export interface PlaceholderHit {
 export interface PlaceholderResult {
   rule: "placeholder";
   found: boolean;
-  outcome: "pass" | "fail";
+  outcome: "pass" | "fail" | "unknown";
   scanned: number;
   truncated: boolean;
   hits: PlaceholderHit[];
@@ -100,6 +100,8 @@ export interface ContrastResult {
 }
 
 export interface ContentChecksRequest {
+  /** Explicit traversal budget; omission retains the existing node cap. */
+  scanNodeBudget?: number;
   placeholder: { scope: string | null } | null;
   image: { scope: string | null; tolerance: number } | null;
   truncation: { scope: string | null; tolerance: number } | null;
@@ -115,7 +117,15 @@ export interface ContentChecksResult {
 
 export function buildContentChecks(): (request: ContentChecksRequest) => ContentChecksResult {
   return (request) => {
-    const NODE_CAP = 6000;
+    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 NODE_CAP = request.scanNodeBudget ?? 6000;
     const HIT_CAP = 100;
 
     const sx = window.scrollX;
@@ -234,6 +244,7 @@ export function buildContentChecks(): (request: ContentChecksRequest) => Content
         // when the trimmed text of a leaf element is exactly the tell).
         if (hits.length < HIT_CAP) {
           const leaves = root.querySelectorAll("*");
+          if (leaves.length > NODE_CAP) truncated = true;
           for (let i = 0; i < leaves.length && i < NODE_CAP; i++) {
             const el = leaves[i];
             if (!el || el.children.length > 0) continue;
@@ -258,7 +269,7 @@ export function buildContentChecks(): (request: ContentChecksRequest) => Content
       placeholder = {
         rule: "placeholder",
         found: root !== null,
-        outcome: root && hits.length === 0 ? "pass" : "fail",
+        outcome: !root || hits.length > 0 ? "fail" : truncated ? "unknown" : "pass",
         scanned,
         truncated,
         hits,

package/src/lib/browser/critique.ts

@@ -18,6 +18,7 @@
 //      orchestration live here; the model call lives in the host.
 
 import { PNG } from "pngjs";
+import { PAGE_REVIEW_MAX_TILE_BUDGET } from "./page-review-contracts.js";
 import {
   bandOversizedRect,
   bandsCoveringRects,
@@ -76,6 +77,87 @@ export interface CritiqueResult {
   error?: string;
   /** Host-reported provider provenance (route, attempts, fallbacks, usage). */
   provider_meta?: Record<string, unknown>;
+  /** Tokens the provider reported across every tile it was called for. */
+  usage?: CritiqueUsageTotals;
+}
+
+/** Tokens one provider call spent, as the host's backend reported them.
+ * `input_tokens` counts every input token, cached or not. */
+export interface CritiqueUsage {
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_input_tokens?: number;
+  cache_write_input_tokens?: number;
+  /** Cost at the backend's list price, when the backend reports one. */
+  cost_usd?: number;
+}
+
+/** Usage summed over tiles. A tile whose provider reported nothing counts in
+ * `tiles_unreported`, never as zero tokens. */
+export interface CritiqueUsageTotals {
+  tiles_reported: number;
+  tiles_unreported: number;
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_input_tokens: number;
+  cache_write_input_tokens: number;
+  /** Present only when every reported tile carried a cost. */
+  cost_usd?: number;
+}
+
+/** Add one call's usage to a tile's running usage (a retried tile reports twice). */
+export function addCritiqueUsage(
+  into: CritiqueUsage | undefined,
+  usage: CritiqueUsage,
+): CritiqueUsage {
+  const n = (v: number | undefined) => (Number.isFinite(v) ? (v as number) : 0);
+  const out: CritiqueUsage = {
+    input_tokens: n(into?.input_tokens) + n(usage.input_tokens),
+    output_tokens: n(into?.output_tokens) + n(usage.output_tokens),
+  };
+  const read = n(into?.cache_read_input_tokens) + n(usage.cache_read_input_tokens);
+  const write = n(into?.cache_write_input_tokens) + n(usage.cache_write_input_tokens);
+  if (read > 0) out.cache_read_input_tokens = read;
+  if (write > 0) out.cache_write_input_tokens = write;
+  const costKnown =
+    usage.cost_usd !== undefined && (into === undefined || into.cost_usd !== undefined);
+  if (costKnown) out.cost_usd = n(into?.cost_usd) + n(usage.cost_usd);
+  return out;
+}
+
+export function sumCritiqueUsage(
+  perTile: ReadonlyArray<CritiqueUsage | undefined>,
+): CritiqueUsageTotals {
+  const reported = perTile.filter((u): u is CritiqueUsage => u !== undefined);
+  const totals: CritiqueUsageTotals = {
+    tiles_reported: reported.length,
+    tiles_unreported: perTile.length - reported.length,
+    input_tokens: 0,
+    output_tokens: 0,
+    cache_read_input_tokens: 0,
+    cache_write_input_tokens: 0,
+  };
+  for (const u of reported) {
+    totals.input_tokens += u.input_tokens;
+    totals.output_tokens += u.output_tokens;
+    totals.cache_read_input_tokens += u.cache_read_input_tokens ?? 0;
+    totals.cache_write_input_tokens += u.cache_write_input_tokens ?? 0;
+  }
+  if (reported.length > 0 && reported.every((u) => u.cost_usd !== undefined)) {
+    totals.cost_usd =
+      Math.round(reported.reduce((sum, u) => sum + (u.cost_usd ?? 0), 0) * 1e6) / 1e6;
+  }
+  return totals;
+}
+
+/** "1,234,567 tokens over 96 tiles (3 unreported), $1.23" for log lines. */
+export function formatCritiqueUsage(totals: CritiqueUsageTotals): string {
+  const tokens = (totals.input_tokens + totals.output_tokens).toLocaleString("en-US");
+  return (
+    `${tokens} tokens over ${totals.tiles_reported} tile(s)` +
+    (totals.tiles_unreported > 0 ? ` (${totals.tiles_unreported} unreported)` : "") +
+    (totals.cost_usd !== undefined ? `, $${totals.cost_usd.toFixed(2)} at list price` : "")
+  );
 }
 
 /**
@@ -93,6 +175,9 @@ export type CritiqueProvider = ((input: {
   url: string;
   rubric: string;
   tile: CritiqueTile;
+  /** Optional sink for the tokens this call spent. A provider that knows its
+   * usage calls it once per backend call; callers that omit it lose nothing. */
+  reportUsage?: (usage: CritiqueUsage) => void;
 }) => Promise<CritiqueFinding[]>) & {
   concurrency?: number;
   meta?: () => Record<string, unknown> | undefined;
@@ -242,12 +327,16 @@ export function tilesFromFullPage(
       pngBase64: PNG.sync.write(dst).toString("base64"),
     };
   };
-  const kept = rects.slice(0, opts.maxTiles);
+  const kept = rects.slice(0, Math.min(opts.maxTiles, PAGE_REVIEW_MAX_TILE_BUDGET));
   const tiles: CritiqueTile[] = kept.map(cutTile);
+  const hitBandCap = Math.min(
+    opts.maxHitBands ?? 50,
+    Math.max(0, PAGE_REVIEW_MAX_TILE_BUDGET - kept.length),
+  );
   let hitBands = 0;
   const banding = !(opts.elementRects && opts.elementRects.length > 0);
   if (banding && opts.hitRects && opts.hitRects.length > 0) {
-    for (const index of bandsCoveringRects(rects, kept.length, opts.hitRects, opts.maxHitBands)) {
+    for (const index of bandsCoveringRects(rects, kept.length, opts.hitRects, hitBandCap)) {
       const band = rects[index];
       if (!band) continue;
       tiles.push(cutTile({ ...band, label: `hit band ${index + 1}` }));
@@ -323,10 +412,23 @@ export async function runCritique(args: {
         "no critiqueProvider injected by the host (see HarneryProgramContext.critiqueProvider)",
     };
   }
+  if (tiles.length > PAGE_REVIEW_MAX_TILE_BUDGET) {
+    return {
+      rule: "critique",
+      tiles: tiles.length,
+      provider: true,
+      findings: [],
+      outcome: "skipped",
+      error:
+        `${tiles.length} tiles exceed the per-invocation ceiling of ${PAGE_REVIEW_MAX_TILE_BUDGET} ` +
+        "vision calls; lower the tile cap",
+    };
+  }
   // Tiles are judged independently, so run them concurrently (bounded) and
   // reassemble findings in tile order so artifacts stay deterministic.
   const concurrency = Math.max(1, Math.min(provider.concurrency ?? 4, tiles.length || 1));
   const perTile: CritiqueFinding[][] = tiles.map(() => []);
+  const perTileUsage: Array<CritiqueUsage | undefined> = tiles.map(() => undefined);
   let cursor = 0;
   const worker = async (): Promise<void> => {
     while (true) {
@@ -334,7 +436,14 @@ export async function runCritique(args: {
       if (i >= tiles.length) return;
       const tile = tiles[i];
       try {
-        const tileFindings = await provider({ url, rubric, tile });
+        const tileFindings = await provider({
+          url,
+          rubric,
+          tile,
+          reportUsage: (usage) => {
+            perTileUsage[i] = addCritiqueUsage(perTileUsage[i], usage);
+          },
+        });
         perTile[i] = tileFindings.map((f) => ({ ...f, tile: tile.index }));
       } catch (err: unknown) {
         perTile[i] = [
@@ -359,5 +468,6 @@ export async function runCritique(args: {
     findings,
     outcome,
     ...(meta ? { provider_meta: meta } : {}),
+    usage: sumCritiqueUsage(perTileUsage),
   };
 }

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})`