harnery 0.45.1 → 0.46.0

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;

package/src/lib/browser/runts.ts

@@ -39,7 +39,7 @@ export interface RuntsResult {
   outcome: "pass" | "fail" | "unknown";
   /** Text blocks scanned (post length/inline-children filters). */
   scannedBlocks: number;
-  /** True when the block sweep hit the internal cap (very large page). */
+  /** True when the sweep reached its findings limit or the internal block cap. */
   truncated: boolean;
   runts: RuntHit[];
 }
@@ -47,13 +47,20 @@ export interface RuntsResult {
 /**
  * Build the JS function passed to `page.evaluate`. `scope` narrows the sweep
  * to one container (null = whole body); `minChars` filters out tiny labels
- * that can't meaningfully wrap (default 40).
+ * that can't meaningfully wrap (default 40). `maxFindings` bounds the retained
+ * failure list (default 50; integer 1..5000), not the separate 5000-block cap.
  */
 export function buildRuntsCheck(): (args: {
   scope: string | null;
   minChars: number;
+  maxFindings?: number;
 }) => RuntsResult {
-  return ({ scope, minChars }) => {
+  return ({ scope, minChars, maxFindings = 50 }) => {
+    // page.evaluate has no module closure: validate this boundary too, even
+    // when a caller evaluates the built function without the Browser client.
+    if (!Number.isInteger(maxFindings) || maxFindings < 1 || maxFindings > 5000) {
+      throw new Error("maxFindings must be an integer from 1 to 5000.");
+    }
     const INLINE = new Set([
       "B",
       "I",
@@ -74,7 +81,7 @@ export function buildRuntsCheck(): (args: {
     ]);
     const ATOMIC = /@|https?:|\.(com|org|net|io|co)\b|\d-\d{3}/;
     const BLOCK_CAP = 5000;
-    const RUNT_CAP = 50;
+    const RUNT_CAP = maxFindings;
 
     const root = scope ? document.querySelector(scope) : document.body;
     if (!root) {
@@ -128,34 +135,78 @@ export function buildRuntsCheck(): (args: {
       }
       scanned++;
 
-      // Map every word to its visual line by rounding the Range rect top.
-      const lines = new Map<number, { words: string[]; last: DOMRect; node: Node }>();
-      const tw = document.createTreeWalker(el, NodeFilter.SHOW_TEXT);
+      // Inline markup does not create word boundaries. Keep offsets into the
+      // original text nodes so one Range can measure a word split by emphasis
+      // or followed by punctuation in a separate node. BR still separates words.
+      const segments: Array<{ node: Text; start: number; end: number }> = [];
+      let content = "";
+      const tw = document.createTreeWalker(el, NodeFilter.SHOW_TEXT | NodeFilter.SHOW_ELEMENT);
       for (let n = tw.nextNode(); n; n = tw.nextNode()) {
+        if (n instanceof Element && n.tagName === "BR") content += "\n";
+        if (n.nodeType !== Node.TEXT_NODE) continue;
         const value = n.nodeValue ?? "";
-        for (const m of value.matchAll(/\S+/g)) {
-          const r = document.createRange();
-          r.setStart(n, m.index);
-          r.setEnd(n, m.index + m[0].length);
-          const rect = r.getBoundingClientRect();
-          if (!rect.width) continue;
-          const top = Math.round(rect.top);
-          const entry = lines.get(top);
-          if (entry) {
-            entry.words.push(m[0]);
-            entry.last = rect;
-            entry.node = n;
-          } else {
-            lines.set(top, { words: [m[0]], last: rect, node: n });
+        segments.push({
+          node: n as Text,
+          start: content.length,
+          end: content.length + value.length,
+        });
+        content += value;
+      }
+      type Word = { value: string; rect: DOMRect; node: Node };
+      const lines: Array<{ top: number; bottom: number; words: Map<number, Word> }> = [];
+      let segmentIndex = 0;
+      for (const m of content.matchAll(/\S+/g)) {
+        const lexical = /[\p{L}\p{N}]/u.exec(m[0]);
+        if (!lexical) continue; // punctuation alone is not an orphan word
+        const end = m.index + m[0].length;
+        while (segments[segmentIndex] && segments[segmentIndex]!.end <= m.index) segmentIndex++;
+        const first = segments[segmentIndex];
+        if (!first) continue;
+        let endIndex = segmentIndex;
+        while (segments[endIndex] && segments[endIndex]!.end < end) endIndex++;
+        const final = segments[endIndex];
+        if (!final) continue;
+        let wordIndex = segmentIndex;
+        while (segments[wordIndex]!.end <= m.index + lexical.index) wordIndex++;
+        const wordNode = segments[wordIndex]!.node;
+        const range = document.createRange();
+        range.setStart(first.node, m.index - first.start);
+        range.setEnd(final.node, end - final.start);
+        for (const rect of range.getClientRects()) {
+          if (!rect.width || !rect.height) continue;
+          // Different inline fonts have different glyph tops on the same line.
+          // Require substantial vertical overlap rather than exact rounded tops.
+          let line = lines.find(
+            (candidate) =>
+              Math.min(candidate.bottom, rect.bottom) - Math.max(candidate.top, rect.top) >
+              Math.min(candidate.bottom - candidate.top, rect.height) / 2,
+          );
+          if (!line) {
+            line = { top: rect.top, bottom: rect.bottom, words: new Map() };
+            lines.push(line);
           }
+          line.top = Math.min(line.top, rect.top);
+          line.bottom = Math.max(line.bottom, rect.bottom);
+          const previous = line.words.get(m.index)?.rect;
+          const box = previous
+            ? new DOMRect(
+                Math.min(previous.left, rect.left),
+                Math.min(previous.top, rect.top),
+                Math.max(previous.right, rect.right) - Math.min(previous.left, rect.left),
+                Math.max(previous.bottom, rect.bottom) - Math.min(previous.top, rect.top),
+              )
+            : rect;
+          line.words.set(m.index, { value: m[0], rect: box, node: wordNode });
         }
       }
-      const tops = [...lines.keys()].sort((a, b) => a - b);
-      if (tops.length < 2) continue; // single line, no runt risk
-      const lastTop = tops[tops.length - 1];
-      const last = lastTop === undefined ? undefined : lines.get(lastTop);
-      if (last?.words.length !== 1) continue;
-      const word = last.words[0] ?? "";
+      lines.sort((a, b) => a.top - b.top);
+      if (lines.length < 2) continue; // single line, no runt risk
+      const lastLine = lines[lines.length - 1];
+      if (lastLine?.words.size !== 1) continue;
+      const [wordOffset, last] = [...lastLine.words.entries()][0]!;
+      // A word split across visual lines is not a separate final orphan word.
+      if (lines.slice(0, -1).some((line) => line.words.has(wordOffset))) continue;
+      const word = last.value;
       if (ATOMIC.test(word)) continue;
       // A chip is not prose. A lone token whose glyphs live inside a padded,
       // boxed inline element (a <code> chip, pill, or badge) is a UI control:
@@ -165,11 +216,7 @@ export function buildRuntsCheck(): (args: {
       // inline ancestry (tag-based, since flex/grid parents blockify computed
       // display) and skip the finding when a chip hosts it.
       const chipHosted = (() => {
-        for (
-          let e = last.node.parentElement;
-          e && e !== el && INLINE.has(e.tagName);
-          e = e.parentElement
-        ) {
+        for (let e = last.node.parentElement; e && INLINE.has(e.tagName); e = e.parentElement) {
           const cs = getComputedStyle(e);
           const padX =
             (Number.parseFloat(cs.paddingLeft) || 0) + (Number.parseFloat(cs.paddingRight) || 0);
@@ -177,6 +224,7 @@ export function buildRuntsCheck(): (args: {
             (cs.backgroundColor !== "rgba(0, 0, 0, 0)" && cs.backgroundColor !== "transparent") ||
             (Number.parseFloat(cs.borderTopWidth) || 0) > 0;
           if (padX > 0 && boxed) return true;
+          if (e === el) break;
         }
         return false;
       })();
@@ -187,12 +235,12 @@ export function buildRuntsCheck(): (args: {
         word,
         snippet: text.replace(/\s+/g, " ").trim().slice(0, 80),
         rect: {
-          x: Math.round(last.last.x + sx),
-          y: Math.round(last.last.y + sy),
-          width: Math.round(last.last.width),
-          height: Math.round(last.last.height),
+          x: Math.round(last.rect.x + sx),
+          y: Math.round(last.rect.y + sy),
+          width: Math.round(last.rect.width),
+          height: Math.round(last.rect.height),
         },
-        lines: tops.length,
+        lines: lines.length,
       });
       if (runts.length >= RUNT_CAP) {
         truncated = true;

package/src/lib/browser/windows-chrome.ts

@@ -479,6 +479,56 @@ export function stopWindowsChromeProfile(
   return parseStopOutput(result.stdout, profileWindows);
 }
 
+/**
+ * PowerShell that lists the Chrome processes running on the profile matched
+ * by `$Pattern` and prints their ids as a JSON array. It never closes them.
+ */
+export function runningScript(): string {
+  return [
+    "param([string]$Pattern)",
+    "$ErrorActionPreference = 'Stop'",
+    PROFILE_PROCESS_FUNCTION,
+    "$ids = @(Get-ProfileChrome | ForEach-Object { [int]$_.ProcessId })",
+    "[Console]::Out.Write((ConvertTo-Json -Compress -InputObject $ids))",
+  ].join("\r\n");
+}
+
+/** Parse the running script's stdout into process ids. */
+export function parseRunningOutput(stdout: string): number[] {
+  const trimmed = stdout.trim();
+  if (!trimmed) return [];
+  const parsed = JSON.parse(trimmed) as number | number[] | null;
+  if (parsed === null) return [];
+  return (Array.isArray(parsed) ? parsed : [parsed]).map(Number);
+}
+
+/**
+ * Ids of the Chrome processes running on `profileWindows`, for callers that
+ * must leave an open profile alone. Throws when the check cannot run.
+ */
+export function windowsChromeProfileProcesses(profileWindows: string): number[] {
+  const result = runPowerShellScript(
+    "profile-running",
+    runningScript(),
+    ["-Pattern", profileCommandLinePattern(profileWindows)],
+    30_000,
+  );
+  if (result.status !== 0) {
+    throw new Error(
+      `Checking for Chrome on ${profileWindows} failed: ${(result.stderr || result.stdout || result.error?.message || "no output").trim().slice(0, 400)}`,
+    );
+  }
+  return parseRunningOutput(result.stdout);
+}
+
+/** Linux form of a drive-letter Windows path (`C:\x` becomes `/mnt/c/x`). */
+export function windowsPathToWsl(windowsPath: string): string {
+  const match = /^([A-Za-z]):\\(.*)$/.exec(windowsPath);
+  if (!match) throw new Error(`Not a drive-letter path: ${windowsPath}`);
+  const rest = (match[2] ?? "").replace(/\\+/g, "/").replace(/\/+$/, "");
+  return `/mnt/${(match[1] as string).toLowerCase()}${rest ? `/${rest}` : ""}`;
+}
+
 /** Windows form of a `/mnt/<drive>/...` path. */
 export function wslPathToWindows(linuxPath: string): string {
   const match = /^\/mnt\/([a-z])\/(.*)$/.exec(linuxPath);