harnery 0.36.0 → 0.38.0

package/dist/lib/browser/critique.js

@@ -17,7 +17,7 @@
 //      false pass. That keeps this portable — the tiling, prompt, and
 //      orchestration live here; the model call lives in the host.
 import { PNG } from "pngjs";
-import { bandOversizedRect, snappedBandRects } from "./tiling.js";
+import { bandOversizedRect, bandsCoveringRects, snappedBandRects, } from "./tiling.js";
 export const DEFAULT_CRITIQUE_RUBRIC = [
     "You are reviewing one vertical slice of a rendered web page for visual defects.",
     "Report ONLY concrete, visible problems a careful designer would flag:",
@@ -71,6 +71,15 @@ export function bandRects(pageHeight, pageWidth, bandHeight, overlap) {
  * the provider would downscale. Atom coordinates must be in the same pixel
  * space as the screenshot (identical at deviceScaleFactor 1; scale them if
  * the capture DPR differs).
+ *
+ * `hitRects` (document-space rectangles a deterministic gate already flagged)
+ * add bands past the `maxTiles` cap: every full-page band that intersects a
+ * hit rect and was dropped by the cap is cut as well, labelled `hit band N`
+ * (N is the band's 1-based position in the full band list, and the tile's
+ * `index` is that position minus one), and appended after the kept bands.
+ * `coverage` stays honest about the kept prefix; `hitBands` counts the
+ * extras. Ignored for selector tiling (`elementRects`), which has no cap to
+ * look past in that sense.
  */
 export function tilesFromFullPage(fullPageBuffer, opts) {
     const png = PNG.sync.read(fullPageBuffer);
@@ -105,8 +114,7 @@ export function tilesFromFullPage(fullPageBuffer, opts) {
             height: b.height,
         }));
     }
-    const tiles = [];
-    for (const rect of rects.slice(0, opts.maxTiles)) {
+    const cutTile = (rect) => {
         const sx = Math.max(0, Math.min(Math.round(rect.x), png.width - 1));
         const sy = Math.max(0, Math.min(Math.round(rect.y), png.height - 1));
         const w = Math.max(1, Math.min(Math.round(rect.width), png.width - sx));
@@ -119,7 +127,7 @@ export function tilesFromFullPage(fullPageBuffer, opts) {
             const dstStart = row * w * 4;
             png.data.copy(dst.data, dstStart, srcStart, srcStart + w * 4);
         }
-        tiles.push({
+        return {
             index: rect.index,
             label: rect.label,
             scrollY: sy,
@@ -127,9 +135,29 @@ export function tilesFromFullPage(fullPageBuffer, opts) {
             width: w,
             height: h,
             pngBase64: PNG.sync.write(dst).toString("base64"),
-        });
+        };
+    };
+    const kept = rects.slice(0, opts.maxTiles);
+    const tiles = kept.map(cutTile);
+    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)) {
+            const band = rects[index];
+            if (!band)
+                continue;
+            tiles.push(cutTile({ ...band, label: `hit band ${index + 1}` }));
+            hitBands++;
+        }
     }
-    return tiles;
+    const coverage = {
+        page_height_px: png.height,
+        reviewed_height_px: kept.reduce((max, rect) => Math.max(max, Math.min(png.height, Math.round(rect.y + rect.height))), 0),
+        bands_total: rects.length,
+        bands_reviewed: kept.length,
+        capped: rects.length > kept.length,
+    };
+    return { tiles, coverage, hitBands };
 }
 /**
  * Validate + normalize a provider's raw output into CritiqueFindings. Tolerant

package/dist/lib/browser/index.d.ts

@@ -1,15 +1,19 @@
 export { type AssertOp, type AssertResult, type AssertSpec, buildAssertCheck, parseAssertSpec, } from "./asserts.js";
 export { Browser, type BrowserOptions, BrowserSessionActionError, type BrowserSessionControl, type BrowserSessionInspection, type BrowserSessionLocator, type BrowserSessionNavigation, type BrowserSessionNavigationType, type BrowserSessionScreenshot, type BrowserSessionStatus, type BrowserSessionTab, type ConsoleEvent, type Diagnostics, type FailedRequest, type NavigateResult, type PageErrorEvent, } from "./client.js";
 export type { CheckRect, ContentAnnotationBox, ContentChecksRequest, ContentChecksResult, ContrastHit, ContrastResult, ImageHealthResult, ImageHit, PlaceholderHit, PlaceholderResult, TruncationHit, TruncationResult, } from "./content-checks.js";
-export { bandRects, type CritiqueFinding, type CritiqueProvider, type CritiqueResult, type CritiqueTile, DEFAULT_CRITIQUE_RUBRIC, normalizeFindings, runCritique, tilesFromFullPage, } from "./critique.js";
+export { bandRects, type CritiqueCoverage, type CritiqueFinding, type CritiqueProvider, type CritiqueResult, type CritiqueTile, DEFAULT_CRITIQUE_RUBRIC, normalizeFindings, runCritique, tilesFromFullPage, } from "./critique.js";
 export { captureDevOverlay, type DevOverlayError, type DevOverlayResult, } from "./dev-overlay.js";
 export type { AlignChild, AlignCluster, AlignResult, ClipIssue, ClipResult, CrowdPair, CrowdResult, GapCluster, GapPair, GapResult, LayoutAxis, LayoutElementMeasurement, LayoutExclusion, LayoutLintRequest, LayoutLintResult, LayoutOutcome, LayoutRect, OverlapIssue, OverlapResult, } from "./geometry.js";
 export { buildLayoutLintCheck } from "./geometry.js";
 export { isWSL, wslHeadedLaunchArgs } from "./launch-args.js";
 export type { OverflowElement, OverflowResult, WidthResult, } from "./layout.js";
 export { serializeNetscapeCookies, writeNetscapeCookieFile, } from "./netscape-cookies.js";
+export { type JudgedContext, type JudgePageReviewPackOptions, type JudgePageReviewPackResult, judgePageReviewPack, toCritiqueRecords, } from "./page-review-judge.js";
+export { buildInspectionPlan, type FinalizePageReviewPackInput, finalizePageReviewPack, findingsSchemaDocument, listPackContexts, PAGE_REVIEW_FINDINGS_SCHEMA, PAGE_REVIEW_PACK_DIRNAME, PAGE_REVIEW_PACK_SCHEMA, type PageReviewContextCapture, type PageReviewContextRecord, type PageReviewCritiqueRecord, type PageReviewGateRecord, type PageReviewInspectionPlan, type PageReviewPackManifest, type PageReviewTileRecord, packPaths, readPackContext, readPackDom, readPackFullPage, readPackManifest, readPackSignature, readPackTiles, renderReviewMarkdown, writePackContext, } from "./page-review-pack.js";
 export { type BrowserProxy, type BrowserProxyGate, browserProxyFromEnv, browserProxyGateFromEnv, extractObservedIp, WEBRTC_PROXY_ONLY_ARG, } from "./proxy.js";
 export { buildQaManifest, type ChangeClass, type ClassifyOptions, classifySignatures, fnv1a32, type ManifestOptions, type QaClassification, type QaContext, type QaManifest, type QaNodeSignature, type QaScope, type QaSignature, type QaStylesheetSignature, } from "./qa-plan.js";
+export { defaultQaRunExec, QA_RUN_HEADLESS_ONLY_ENV, QA_RUN_RESULT_FILENAME, type QaRunExec, type QaRunExecOptions, type QaRunExecResult, type QaRunMatrixOptions, runQaMatrix, } from "./qa-run.js";
+export { computeVerdict, contextIdFor, mergeCoverage, QA_RUN_JOB_SCHEMA_VERSION, QA_RUN_RESULT_SCHEMA_VERSION, type QaRunBlocker, type QaRunCheck, type QaRunCommandOutcome, type QaRunContext, type QaRunCritiqueOutcome, type QaRunCritiquePool, type QaRunInteraction, type QaRunJob, type QaRunJobValidation, type QaRunPolicy, type QaRunResult, type QaRunReviewPack, type QaRunVerdict, validateQaRunJob, } from "./qa-run-contracts.js";
 export { listQaSnapshotTargets, loadQaSnapshot, QA_SNAPSHOT_DIR, type QaSnapshotStoreOptions, qaSnapshotKey, type ResolvedQaBaseline, resolveQaBaseline, type StoredQaSnapshot, saveQaSnapshot, } from "./qa-snapshot.js";
 export type { RuntHit, RuntsResult, } from "./runts.js";
 export { BROWSER_SESSION_MAX_FILL_BYTES, BROWSER_SESSION_MAX_FRAME_BYTES, BROWSER_SESSION_MAX_INSPECTION_TEXT_BYTES, BROWSER_SESSION_PROTOCOL_VERSION, type BrowserSessionDescriptor, BrowserSessionError, type BrowserSessionRequest, type BrowserSessionResponse, type BrowserSessionResult, type BrowserSessionServer, type BrowserSessionTarget, browserSessionTransport, readBrowserSessionDescriptor, sendBrowserSessionRequest, startBrowserSessionServer, } from "./session-control.js";

package/dist/lib/browser/index.d.ts.map

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

package/dist/lib/browser/index.js

@@ -5,8 +5,12 @@ export { captureDevOverlay, } from "./dev-overlay.js";
 export { buildLayoutLintCheck } from "./geometry.js";
 export { isWSL, wslHeadedLaunchArgs } from "./launch-args.js";
 export { serializeNetscapeCookies, writeNetscapeCookieFile, } from "./netscape-cookies.js";
+export { judgePageReviewPack, toCritiqueRecords, } from "./page-review-judge.js";
+export { buildInspectionPlan, finalizePageReviewPack, findingsSchemaDocument, listPackContexts, PAGE_REVIEW_FINDINGS_SCHEMA, PAGE_REVIEW_PACK_DIRNAME, PAGE_REVIEW_PACK_SCHEMA, packPaths, readPackContext, readPackDom, readPackFullPage, readPackManifest, readPackSignature, readPackTiles, renderReviewMarkdown, writePackContext, } from "./page-review-pack.js";
 export { browserProxyFromEnv, browserProxyGateFromEnv, extractObservedIp, WEBRTC_PROXY_ONLY_ARG, } from "./proxy.js";
 export { buildQaManifest, classifySignatures, fnv1a32, } from "./qa-plan.js";
+export { defaultQaRunExec, QA_RUN_HEADLESS_ONLY_ENV, QA_RUN_RESULT_FILENAME, runQaMatrix, } from "./qa-run.js";
+export { computeVerdict, contextIdFor, mergeCoverage, QA_RUN_JOB_SCHEMA_VERSION, QA_RUN_RESULT_SCHEMA_VERSION, validateQaRunJob, } from "./qa-run-contracts.js";
 export { listQaSnapshotTargets, loadQaSnapshot, QA_SNAPSHOT_DIR, qaSnapshotKey, resolveQaBaseline, saveQaSnapshot, } from "./qa-snapshot.js";
 export { BROWSER_SESSION_MAX_FILL_BYTES, BROWSER_SESSION_MAX_FRAME_BYTES, BROWSER_SESSION_MAX_INSPECTION_TEXT_BYTES, BROWSER_SESSION_PROTOCOL_VERSION, BrowserSessionError, browserSessionTransport, readBrowserSessionDescriptor, sendBrowserSessionRequest, startBrowserSessionServer, } from "./session-control.js";
 export { bandOversizedRect, cutCost, snappedBandRects, } from "./tiling.js";

package/dist/lib/browser/page-review-judge.d.ts

@@ -0,0 +1,64 @@
+import type { CritiqueProvider } from "./critique.js";
+import { type PageReviewContextRecord, type PageReviewCritiqueRecord } from "./page-review-pack.js";
+import { type CritiqueReusePlan } from "./qa-reuse.js";
+import { type QaSnapshotStoreOptions } from "./qa-snapshot.js";
+export interface JudgePageReviewPackOptions {
+    packDir: string;
+    /** Host-injected vision call. Absent: every context reports `skipped`. */
+    provider: CritiqueProvider | undefined;
+    rubric: string;
+    /** Vision calls in flight across the whole pack. Default: the provider's
+     * own concurrency, then 4. */
+    concurrency?: number;
+    /** Subset of context ids to judge (default: every context in the pack). */
+    contextIds?: string[];
+    /** Band-diff reuse against persisted snapshots keyed by `target`. */
+    reuse?: {
+        target: string;
+        store?: QaSnapshotStoreOptions;
+        mismatchThreshold?: number;
+    };
+    /** Absolute epoch-ms deadline. Workers stop claiming tiles once past it;
+     * a context with unjudged tiles reports `incomplete`, never `pass`. */
+    deadlineAt?: number;
+    onLog?: (message: string) => void;
+}
+export interface JudgedContext extends PageReviewCritiqueRecord {
+    record: PageReviewContextRecord;
+    /** Tiles selected for review that the pool never reached (deadline). */
+    tiles_unjudged: number;
+    reuse?: Pick<CritiqueReusePlan, "tiles_total" | "tiles_reused" | "tiles_reviewed" | "invalidation" | "mismatch_threshold">;
+}
+export interface JudgePageReviewPackResult {
+    contexts: JudgedContext[];
+    pool: {
+        concurrency: number;
+        wall_time_ms: number;
+        provider: string;
+    };
+    tiles_total: number;
+    tiles_reviewed: number;
+    tiles_reused: number;
+    outcome: "pass" | "fail" | "skipped" | "incomplete";
+    provider_meta?: Record<string, unknown>;
+}
+/**
+ * Orientation the provider reads before the rubric: which band this tile is,
+ * where it sits on the page, how much of it repeats a neighbour, whether it
+ * touches the page top or bottom, and how it was captured. A tile edge that
+ * continues in the next band is not a clipped element, and a fixed header at
+ * the top of a scrolled-band capture is not a layout defect; the preamble
+ * says so where the pixels cannot. Adds context only: the finding taxonomy
+ * the rubric defines is unchanged. Empty for an unknown tile id.
+ */
+export declare function tileRubricPreamble(record: PageReviewContextRecord, tileId: string): string;
+/**
+ * Judge every tile in the pack through one pool. Findings keep the tiler
+ * index (`tile`) for compatibility with `CritiqueFinding` and add the pack's
+ * stable `tile_id`. A provider throw on one tile becomes a `high`
+ * `provider-error` finding for that tile; nothing else is affected.
+ */
+export declare function judgePageReviewPack(options: JudgePageReviewPackOptions): Promise<JudgePageReviewPackResult>;
+/** Strip the in-memory `record` so the result can be written into the pack. */
+export declare function toCritiqueRecords(result: JudgePageReviewPackResult): PageReviewCritiqueRecord[];
+//# sourceMappingURL=page-review-judge.d.ts.map

package/dist/lib/browser/page-review-judge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-review-judge.d.ts","sourceRoot":"","sources":["../../../src/lib/browser/page-review-judge.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAmB,gBAAgB,EAAgB,MAAM,eAAe,CAAC;AACrF,OAAO,EAEL,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,EAI9B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,KAAK,iBAAiB,EAAqB,MAAM,eAAe,CAAC;AAC1E,OAAO,EAAkB,KAAK,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAE/E,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,QAAQ,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf;kCAC8B;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,qEAAqE;IACrE,KAAK,CAAC,EAAE;QACN,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,sBAAsB,CAAC;QAC/B,iBAAiB,CAAC,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF;2EACuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,aAAc,SAAQ,wBAAwB;IAC7D,MAAM,EAAE,uBAAuB,CAAC;IAChC,wEAAwE;IACxE,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,IAAI,CACV,iBAAiB,EACjB,aAAa,GAAG,cAAc,GAAG,gBAAgB,GAAG,cAAc,GAAG,oBAAoB,CAC1F,CAAC;CACH;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,IAAI,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IACtE,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,YAAY,CAAC;IACpD,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAUD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,uBAAuB,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CA2E1F;AAaD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,yBAAyB,CAAC,CA4KpC;AAED,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,yBAAyB,GAAG,wBAAwB,EAAE,CAI/F"}

package/dist/lib/browser/page-review-judge.js

@@ -0,0 +1,270 @@
+// Judge a page review pack: one bounded pool of vision calls over every tile
+// of every context, read from disk, with no browser open. This is the second
+// half of the capture-then-judge split; `page-review-pack.ts` owns the first.
+//
+// Reuse: when a persisted QA snapshot exists for a context, the band-diff
+// planner compares the pack's own full-page screenshot with the baseline and
+// skips tiles whose pixels provably did not change and carried no baseline
+// finding (false reviews are allowed, false passes never).
+//
+// Toolkit tier: this module must not import src/core (layering check).
+import { readFileSync } from "node:fs";
+import { listPackContexts, readPackContext, readPackFullPage, readPackTiles, } from "./page-review-pack.js";
+import { planCritiqueReuse } from "./qa-reuse.js";
+import { loadQaSnapshot } from "./qa-snapshot.js";
+/**
+ * Orientation the provider reads before the rubric: which band this tile is,
+ * where it sits on the page, how much of it repeats a neighbour, whether it
+ * touches the page top or bottom, and how it was captured. A tile edge that
+ * continues in the next band is not a clipped element, and a fixed header at
+ * the top of a scrolled-band capture is not a layout defect; the preamble
+ * says so where the pixels cannot. Adds context only: the finding taxonomy
+ * the rubric defines is unchanged. Empty for an unknown tile id.
+ */
+export function tileRubricPreamble(record, tileId) {
+    const tile = record.tiles.find((entry) => entry.id === tileId);
+    if (!tile)
+        return "";
+    const pageHeight = record.page.height;
+    const top = tile.scrollY;
+    const bottom = tile.scrollY + tile.height;
+    const lines = [];
+    if (tile.scope !== undefined) {
+        lines.push(`Tile ${tile.id}: selector tile for ${tile.scope} (${tile.label}), ` +
+            `document y ${top}-${bottom} px of a ${pageHeight} px tall page.`);
+    }
+    else {
+        const bands = record.tiles
+            .filter((entry) => entry.scope === undefined)
+            .sort((a, b) => a.scrollY - b.scrollY || a.index - b.index);
+        const n = bands.findIndex((entry) => entry.id === tile.id);
+        const capped = record.coverage.capped
+            ? ` (the page has ${record.coverage.bands_total} bands; those past the cap are not in this pack)`
+            : "";
+        lines.push(`Tile ${tile.id}: band ${n + 1} of ${bands.length}${capped}, ` +
+            `document y ${top}-${bottom} px of a ${pageHeight} px tall page.`);
+        const prev = bands[n - 1];
+        const next = bands[n + 1];
+        const overlaps = [];
+        if (prev) {
+            const above = Math.max(0, prev.scrollY + prev.height - top);
+            overlaps.push(above > 0
+                ? `its top ${above} px repeat the bottom of ${prev.id}`
+                : `it starts where ${prev.id} ends, with no overlap`);
+        }
+        if (next) {
+            const below = Math.max(0, bottom - next.scrollY);
+            overlaps.push(below > 0
+                ? `its bottom ${below} px repeat the top of ${next.id}`
+                : `it ends where ${next.id} starts, with no overlap`);
+        }
+        if (overlaps.length > 0) {
+            const joined = overlaps.join("; ");
+            lines.push(`${joined.charAt(0).toUpperCase()}${joined.slice(1)}.`);
+        }
+    }
+    const touchesTop = top <= 0;
+    const touchesBottom = bottom >= pageHeight;
+    if (touchesTop && touchesBottom) {
+        lines.push("This tile covers the whole page height.");
+    }
+    else if (touchesTop) {
+        lines.push("This tile touches the page top; content cut at its bottom edge continues in the next band.");
+    }
+    else if (touchesBottom) {
+        lines.push("This tile touches the page bottom; content cut at its top edge continues in the previous band.");
+    }
+    else {
+        lines.push("This tile is interior: content cut at its top and bottom edges continues in the neighbouring bands.");
+    }
+    const source = record.capture_fidelity?.source ?? "full-page";
+    lines.push(source === "scrolled-bands"
+        ? "Capture source: scrolled-bands (the viewport was scrolled to this band and clipped, because " +
+            "the full-page screenshot disagreed with the viewport render). Fixed and sticky elements " +
+            "are shown once, at their document position, as a full-page screenshot shows them; a " +
+            "fixed bar that is absent from this band is therefore not a defect."
+        : "Capture source: full-page (one full-page screenshot, cropped to this band).");
+    return lines.join(" ");
+}
+function providerLabel(meta, present) {
+    if (meta) {
+        for (const key of ["provider", "active_harness", "route", "model"]) {
+            const value = meta[key];
+            if (typeof value === "string" && value.length > 0)
+                return value;
+            if (Array.isArray(value) && typeof value[0] === "string")
+                return value[0];
+        }
+    }
+    return present ? "host" : "none";
+}
+/**
+ * Judge every tile in the pack through one pool. Findings keep the tiler
+ * index (`tile`) for compatibility with `CritiqueFinding` and add the pack's
+ * stable `tile_id`. A provider throw on one tile becomes a `high`
+ * `provider-error` finding for that tile; nothing else is affected.
+ */
+export async function judgePageReviewPack(options) {
+    const { packDir, provider, rubric } = options;
+    const log = options.onLog ?? (() => { });
+    const ids = options.contextIds ?? listPackContexts(packDir);
+    const records = ids.map((id) => readPackContext(packDir, id));
+    const started = Date.now();
+    const perContext = records.map((record) => {
+        const tiles = readPackTiles(packDir, record);
+        let review = tiles;
+        let reuse;
+        // Reuse only for unscoped captures: scope tiles share tiler indices with
+        // the bands, and a mixed set would mis-associate baseline findings.
+        // Never for a scrolled-bands context: its tiles were cut from scrolled
+        // viewport captures, not from the full-page PNG the band diff compares.
+        const scrolled = record.capture_fidelity?.source === "scrolled-bands";
+        if (options.reuse && provider && scrolled) {
+            log(`judge ${record.id}: band-diff reuse skipped (tiles came from scrolled bands)`);
+        }
+        if (options.reuse && provider && record.scopes.length === 0 && !scrolled) {
+            const context = {
+                viewport: record.viewport,
+                theme: record.theme,
+                state: record.state,
+            };
+            const stored = loadQaSnapshot(options.reuse.target, context, options.reuse.store ?? {});
+            if (stored?.screenshotPath && stored.critique) {
+                reuse = planCritiqueReuse({
+                    baselineScreenshot: readFileSync(stored.screenshotPath),
+                    baselineCritique: stored.critique,
+                    currentScreenshot: readPackFullPage(packDir, record),
+                    tiles,
+                    rubric,
+                    ...(options.reuse.mismatchThreshold !== undefined
+                        ? { mismatchThreshold: options.reuse.mismatchThreshold }
+                        : {}),
+                });
+                const keep = new Set(reuse.review.map((tile) => tile.index));
+                // planCritiqueReuse returns CritiqueTile objects; re-attach ids by
+                // tiler index so the pool cites the pack's stable tile ids.
+                review = tiles.filter((tile) => keep.has(tile.index));
+                log(`judge ${record.id}: ${reuse.tiles_reused}/${reuse.tiles_total} tiles reused (band-diff)` +
+                    (reuse.invalidation ? ` — ${reuse.invalidation}` : ""));
+            }
+        }
+        return { record, tiles, review, ...(reuse ? { reuse } : {}), findings: [], judged: new Set() };
+    });
+    const work = [];
+    perContext.forEach((entry, contextIndex) => {
+        for (const tile of entry.review) {
+            const preamble = tileRubricPreamble(entry.record, tile.id);
+            work.push({
+                contextIndex,
+                tile,
+                url: entry.record.url,
+                rubric: preamble ? `${preamble}\n\n${rubric}` : rubric,
+            });
+        }
+    });
+    let meta;
+    let concurrency = 0;
+    if (provider && work.length > 0) {
+        concurrency = Math.max(1, Math.min(options.concurrency ?? provider.concurrency ?? 4, work.length));
+        log(`judge: ${work.length} tile(s) across ${records.length} context(s), pool ${concurrency}`);
+        let cursor = 0;
+        const worker = async () => {
+            while (true) {
+                if (options.deadlineAt !== undefined && Date.now() >= options.deadlineAt)
+                    return;
+                const i = cursor++;
+                if (i >= work.length)
+                    return;
+                const item = work[i];
+                const entry = perContext[item.contextIndex];
+                if (!entry)
+                    continue;
+                entry.judged.add(item.tile.id);
+                try {
+                    const found = await provider({ url: item.url, rubric: item.rubric, tile: item.tile });
+                    for (const finding of found) {
+                        entry.findings.push({ ...finding, tile: item.tile.index, tile_id: item.tile.id });
+                    }
+                }
+                catch (err) {
+                    entry.findings.push({
+                        tile: item.tile.index,
+                        tile_id: item.tile.id,
+                        severity: "high",
+                        category: "provider-error",
+                        description: `critique provider failed on ${item.tile.label}: ${err instanceof Error ? err.message : String(err)}`,
+                    });
+                }
+            }
+        };
+        await Promise.all(Array.from({ length: concurrency }, () => worker()));
+        meta = provider.meta?.();
+    }
+    else if (provider) {
+        meta = provider.meta?.();
+    }
+    const label = providerLabel(meta, Boolean(provider));
+    const contexts = perContext.map((entry) => {
+        // Deterministic order: by tile id, then insertion.
+        const findings = [...entry.findings].sort((a, b) => a.tile_id.localeCompare(b.tile_id));
+        const unjudged = entry.review.filter((tile) => !entry.judged.has(tile.id)).length;
+        const outcome = !provider
+            ? "skipped"
+            : findings.some((f) => f.severity === "high")
+                ? "fail"
+                : unjudged > 0
+                    ? "incomplete"
+                    : "pass";
+        return {
+            context_id: entry.record.id,
+            provider: provider ? label : "none",
+            tiles_total: entry.tiles.length,
+            tiles_reviewed: entry.review.length - unjudged,
+            tiles_unjudged: unjudged,
+            tiles_reused: entry.reuse?.tiles_reused ?? 0,
+            outcome,
+            findings,
+            coverage: entry.record.coverage,
+            ...(provider
+                ? {}
+                : {
+                    error: "no critiqueProvider injected by the host (see HarneryProgramContext.critiqueProvider)",
+                }),
+            record: entry.record,
+            ...(entry.reuse
+                ? {
+                    reuse: {
+                        tiles_total: entry.reuse.tiles_total,
+                        tiles_reused: entry.reuse.tiles_reused,
+                        tiles_reviewed: entry.reuse.tiles_reviewed,
+                        mismatch_threshold: entry.reuse.mismatch_threshold,
+                        ...(entry.reuse.invalidation ? { invalidation: entry.reuse.invalidation } : {}),
+                    },
+                }
+                : {}),
+        };
+    });
+    const tilesTotal = contexts.reduce((sum, c) => sum + c.tiles_total, 0);
+    const tilesReviewed = contexts.reduce((sum, c) => sum + c.tiles_reviewed, 0);
+    const tilesReused = contexts.reduce((sum, c) => sum + c.tiles_reused, 0);
+    const outcome = !provider
+        ? "skipped"
+        : contexts.some((c) => c.outcome === "fail")
+            ? "fail"
+            : contexts.some((c) => c.outcome === "incomplete")
+                ? "incomplete"
+                : "pass";
+    return {
+        contexts,
+        pool: { concurrency, wall_time_ms: Date.now() - started, provider: label },
+        tiles_total: tilesTotal,
+        tiles_reviewed: tilesReviewed,
+        tiles_reused: tilesReused,
+        outcome,
+        ...(meta ? { provider_meta: meta } : {}),
+    };
+}
+/** Strip the in-memory `record` so the result can be written into the pack. */
+export function toCritiqueRecords(result) {
+    return result.contexts.map(({ record: _record, reuse: _reuse, tiles_unjudged: _unjudged, ...rest }) => rest);
+}