@tangle-network/agent-bench 0.1.0

package/src/browser/process-adapter.ts

@@ -0,0 +1,146 @@
+/**
+ * Language-agnostic browser-agent adapter over a process boundary.
+ *
+ * This is how we avoid overfitting to our own driver: ANY browser agent becomes a
+ * `BrowserAgentAdapter` by speaking one JSON protocol over stdio — no shared SDK,
+ * no TypeScript requirement. A Python `browser-use` runner, our TS `bad` CLI, or a
+ * hosted service all plug in identically.
+ *
+ * Protocol (stdio):
+ *   - The harness spawns `cmd ...args`, writes a BrowserTask as one JSON line to
+ *     the child's stdin, and closes stdin.
+ *   - The child runs its agent and writes EXACTLY one JSON object — a BrowserRun —
+ *     to stdout (anything on stderr is logged, ignored for parsing).
+ *   - Non-zero exit, no JSON, or a malformed run → throw (fail loud; a driver that
+ *     can't conform is not silently scored zero).
+ *
+ * The child is responsible only for producing a faithful trajectory + final state.
+ * The VERDICT is never the child's to give — `judgeBrowserRun` derives it from the
+ * benchmark's deterministic SuccessSpec against the returned final state.
+ */
+
+import { spawn } from 'node:child_process'
+import type { BrowserAgentAdapter, BrowserRun, BrowserStep, BrowserTask } from './agent-adapter'
+
+export interface ProcessAdapterOptions {
+  /** Attribution id for head-to-head (e.g. 'browser-use', 'bad'). */
+  id: string
+  /** Executable to spawn (e.g. 'python', 'node', 'bad'). */
+  cmd: string
+  /** Fixed args before the per-task protocol (e.g. ['runners/browser_use_runner.py']). */
+  args?: string[]
+  /** Extra env for the child (model keys, etc.). Merged over process.env. */
+  env?: Record<string, string>
+  /** Hard ceiling per task in ms (default 300_000). */
+  timeoutMs?: number
+  /** Working directory for the child. */
+  cwd?: string
+}
+
+/** Build a BrowserAgentAdapter that delegates to an external process speaking the
+ *  JSON protocol above. */
+export function processBrowserAdapter(opts: ProcessAdapterOptions): BrowserAgentAdapter {
+  const timeoutMs = opts.timeoutMs ?? 300_000
+  return {
+    id: opts.id,
+    async run(task: BrowserTask): Promise<BrowserRun> {
+      const stdout = await runChild(opts, JSON.stringify(task), timeoutMs)
+      const run = parseRun(stdout, task, opts.id)
+      return run
+    },
+  }
+}
+
+function runChild(opts: ProcessAdapterOptions, input: string, timeoutMs: number): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(opts.cmd, opts.args ?? [], {
+      cwd: opts.cwd,
+      env: { ...process.env, ...opts.env },
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
+    let out = ''
+    let err = ''
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL')
+      reject(new Error(`browser adapter '${opts.id}' timed out after ${timeoutMs}ms`))
+    }, timeoutMs)
+    child.stdout.on('data', (d) => (out += d.toString()))
+    child.stderr.on('data', (d) => (err += d.toString()))
+    child.on('error', (e) => {
+      clearTimeout(timer)
+      reject(new Error(`browser adapter '${opts.id}' failed to spawn ${opts.cmd}: ${e.message}`))
+    })
+    child.on('close', (code) => {
+      clearTimeout(timer)
+      if (code !== 0) {
+        reject(new Error(`browser adapter '${opts.id}' exited ${code}: ${err.slice(-400) || out.slice(-400)}`))
+        return
+      }
+      resolve(out)
+    })
+    child.stdin.write(input)
+    child.stdin.end()
+  })
+}
+
+/** Parse + validate the child's BrowserRun. The last complete JSON object on stdout
+ *  is the result (drivers may print progress lines before it). Fail loud on a shape
+ *  that the judge cannot trust. */
+function parseRun(stdout: string, task: BrowserTask, driverId: string): BrowserRun {
+  const obj = lastJsonObject(stdout)
+  if (!obj) throw new Error(`browser adapter '${driverId}' produced no JSON BrowserRun for task ${task.id}`)
+  if (typeof obj.finalUrl !== 'string' || !Array.isArray(obj.steps)) {
+    throw new Error(`browser adapter '${driverId}' BrowserRun missing finalUrl/steps for task ${task.id}`)
+  }
+  const steps: BrowserStep[] = (obj.steps as unknown[]).map((s, i) => {
+    const o = (s ?? {}) as Record<string, unknown>
+    return {
+      index: typeof o.index === 'number' ? o.index : i,
+      url: typeof o.url === 'string' ? o.url : '',
+      action: typeof o.action === 'string' ? o.action : 'step',
+      target: typeof o.target === 'string' ? o.target : undefined,
+      reasoning: typeof o.reasoning === 'string' ? o.reasoning : undefined,
+      screenshotPath: typeof o.screenshotPath === 'string' ? o.screenshotPath : undefined,
+      actionBounds: isBounds(o.actionBounds) ? (o.actionBounds as BrowserStep['actionBounds']) : undefined,
+    }
+  })
+  const usage =
+    obj.usage && typeof obj.usage === 'object'
+      ? {
+          input: Number((obj.usage as Record<string, unknown>).input) || 0,
+          output: Number((obj.usage as Record<string, unknown>).output) || 0,
+        }
+      : undefined
+  return {
+    taskId: task.id,
+    steps,
+    finalUrl: obj.finalUrl as string,
+    finalDom: typeof obj.finalDom === 'string' ? obj.finalDom : undefined,
+    answer: typeof obj.answer === 'string' ? obj.answer : undefined,
+    selfReportedSuccess: typeof obj.selfReportedSuccess === 'boolean' ? obj.selfReportedSuccess : undefined,
+    usage,
+    costUsd: typeof obj.costUsd === 'number' ? obj.costUsd : undefined,
+    driverId,
+  }
+}
+
+function isBounds(v: unknown): boolean {
+  if (!v || typeof v !== 'object') return false
+  const o = v as Record<string, unknown>
+  return ['x', 'y', 'width', 'height'].every((k) => typeof o[k] === 'number')
+}
+
+/** Find the last top-level JSON object in mixed stdout (progress lines + result). */
+function lastJsonObject(s: string): Record<string, unknown> | null {
+  for (let i = s.lastIndexOf('{'); i >= 0; i = s.lastIndexOf('{', i - 1)) {
+    const slice = s.slice(i)
+    try {
+      const parsed = JSON.parse(slice)
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) return parsed as Record<string, unknown>
+    } catch {
+      // keep scanning earlier '{'
+    }
+    if (i === 0) break
+  }
+  return null
+}

package/src/browser/run-to-spans.ts

@@ -0,0 +1,105 @@
+/**
+ * Pure converter: a neutral `BrowserRun` (from any `BrowserAgentAdapter`) → a
+ * `Span[]` trace run-capsule renders into a navigation film. One `kind:'tool'`
+ * span per `BrowserStep` (`browser.<action>`); when a step carries a
+ * `screenshotPath`, the file is read and inlined as a base64 `data:` URI on
+ * `attributes.screenshot` — run-capsule renders from the inline blob, NOT a path,
+ * so a raw path would silently render nothing.
+ *
+ * Kept pure + spawn-free (the adapter already ran the browser) so the mapping is
+ * unit-testable against a fixture without launching Chromium. Timestamps are
+ * synthesized monotonically from `opts.startTs` (default 0) — deterministic for
+ * the verify; the live caller passes `Date.now()`.
+ */
+
+import { readFile } from 'node:fs/promises'
+import type { Span } from '@tangle-network/agent-eval'
+import type { BrowserRun, BrowserStep } from './agent-adapter'
+
+export interface BrowserRunToSpansOptions {
+  /** Base timestamp; each emitted span advances by 1ms. Default 0 (deterministic). */
+  startTs?: number
+  /** Cap on inlined screenshot bytes before base64 (skip oversized frames). Default 8 MiB. */
+  maxScreenshotBytes?: number
+}
+
+const PNG = Buffer.from([0x89, 0x50, 0x4e, 0x47])
+const JPG = Buffer.from([0xff, 0xd8, 0xff])
+
+/** Sniff the on-disk image mime from magic bytes; default png. */
+function imageMime(buf: Buffer): string {
+  if (buf.subarray(0, 4).equals(PNG)) return 'image/png'
+  if (buf.subarray(0, 3).equals(JPG)) return 'image/jpeg'
+  return 'image/png'
+}
+
+/** Resolve a step's frame to an inline `data:` URI for the film. Prefers an
+ *  already-inline `step.screenshot` (e.g. bad's base64, whose sink is reaped),
+ *  else reads `step.screenshotPath` off disk. Fail-soft: an unset / unreadable /
+ *  oversized frame drops the image, never the span — the navigation step still
+ *  belongs in the film. */
+async function resolveFrame(step: BrowserStep, maxBytes: number): Promise<string | undefined> {
+  if (step.screenshot) {
+    return step.screenshot.length <= maxBytes * 2 ? step.screenshot : undefined
+  }
+  if (!step.screenshotPath) return undefined
+  const buf = await readFile(step.screenshotPath).catch(() => undefined)
+  if (!buf || buf.length === 0 || buf.length > maxBytes) return undefined
+  return `data:${imageMime(buf)};base64,${buf.toString('base64')}`
+}
+
+/**
+ * Map a `BrowserRun` to a run-capsule-ready `Span[]`. Async because it reads the
+ * step screenshots off disk. The returned trace is ordered by step index; the
+ * agent's final answer (extraction tasks) becomes a trailing generic span so the
+ * film closes on the result.
+ */
+export async function browserRunToSpans(
+  run: BrowserRun,
+  opts: BrowserRunToSpansOptions = {},
+): Promise<Span[]> {
+  const maxBytes = opts.maxScreenshotBytes ?? 8 * 1024 * 1024
+  let ts = opts.startTs ?? 0
+  const tick = (): number => (ts += 1)
+  const runId = `browser-${run.taskId}`
+
+  const spans: Span[] = []
+  for (const step of run.steps) {
+    const action = step.action || 'navigate'
+    const screenshot = await resolveFrame(step, maxBytes)
+    const startedAt = tick()
+    spans.push({
+      spanId: `s-${step.index}`,
+      runId,
+      kind: 'tool',
+      name: `browser ${action}`,
+      toolName: `browser.${action}`,
+      args: { url: step.url, target: step.target, reasoning: step.reasoning },
+      startedAt,
+      endedAt: tick(),
+      status: 'ok',
+      // attributes is the run-capsule contract: inline base64 screenshot + the
+      // action box for a replay cursor overlay. Only set keys that are present.
+      attributes: {
+        ...(screenshot ? { screenshot } : {}),
+        ...(step.actionBounds ? { actionBounds: step.actionBounds } : {}),
+      },
+    } as Span)
+  }
+
+  if (run.answer) {
+    const startedAt = tick()
+    spans.push({
+      spanId: 's-answer',
+      runId,
+      kind: 'custom',
+      name: 'final answer',
+      startedAt,
+      endedAt: tick(),
+      status: 'ok',
+      attributes: { answer: run.answer, finalUrl: run.finalUrl },
+    } as Span)
+  }
+
+  return spans
+}

package/src/browser/run-to-spans.verify.ts

@@ -0,0 +1,89 @@
+/**
+ * Deterministic self-check for browserRunToSpans —
+ * `tsx src/browser/run-to-spans.verify.ts`.
+ *
+ * Proves the run-capsule film contract: each BrowserStep becomes a kind:'tool'
+ * `browser.<action>` span; a step's screenshotPath is READ and inlined as a
+ * base64 `data:` URI on attributes.screenshot (NEVER passed through as a raw
+ * path — the regression that renders an empty film); a missing screenshot drops
+ * the image but keeps the step's span.
+ */
+
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import type { BrowserRun } from './agent-adapter'
+import { browserRunToSpans } from './run-to-spans'
+
+let failures = 0
+function check(name: string, cond: boolean, detail = ''): void {
+  if (cond) console.log(`  ✓ ${name}`)
+  else {
+    failures += 1
+    console.log(`  ✗ ${name} ${detail}`)
+  }
+}
+
+const dir = mkdtempSync(join(tmpdir(), 'run-to-spans-'))
+// A 1x1 PNG on disk — the magic bytes make imageMime resolve to image/png.
+const pngBytes = Buffer.from(
+  '89504e470d0a1a0a0000000d49484452000000010000000108060000001f15c4890000000a49444154789c6360000002000154a24f7d0000000049454e44ae426082',
+  'hex',
+)
+const shotPath = join(dir, 'step-1.png')
+writeFileSync(shotPath, pngBytes)
+
+const run: BrowserRun = {
+  taskId: 'usps-track',
+  driverId: 'bad',
+  steps: [
+    { index: 1, url: 'https://tools.usps.com/', action: 'navigate', target: 'tracking input', screenshotPath: shotPath },
+    { index: 2, url: 'https://tools.usps.com/go/TrackConfirmAction', action: 'click', target: 'Track button', actionBounds: { x: 10, y: 20, width: 80, height: 30 } },
+  ],
+  finalUrl: 'https://tools.usps.com/go/TrackConfirmAction',
+  answer: 'Delivered',
+  selfReportedSuccess: true,
+}
+
+console.log('browserRunToSpans verify:')
+
+const spans = await browserRunToSpans(run, { startTs: 1000 })
+
+check('one tool span per step + a trailing answer span', spans.length === 3, `got ${spans.length}`)
+const s1 = spans[0]
+const s2 = spans[1]
+const answer = spans[2]
+check('step 1 is a kind:tool browser.navigate span', s1?.kind === 'tool' && (s1 as { toolName?: string }).toolName === 'browser.navigate')
+check('step 1 args carry the url + target', (s1 as { args?: { url?: string; target?: string } }).args?.url === 'https://tools.usps.com/' && (s1 as { args?: { target?: string } }).args?.target === 'tracking input')
+
+const shot = (s1?.attributes?.screenshot ?? '') as string
+check('screenshotPath was READ + inlined as a base64 data URI (not a path)', shot.startsWith('data:image/png;base64,') && shot.length > 60, shot.slice(0, 40))
+check('the raw on-disk path is NEVER present in the span', !JSON.stringify(s1).includes(shotPath))
+
+check('step 2 has no screenshot (none provided) but still emits a span', s2?.kind === 'tool' && s2?.attributes?.screenshot === undefined)
+check('step 2 carries the actionBounds overlay', JSON.stringify(s2?.attributes?.actionBounds) === JSON.stringify({ x: 10, y: 20, width: 80, height: 30 }))
+
+check('the answer span closes the film', answer?.kind === 'custom' && answer?.name === 'final answer' && (answer?.attributes as { answer?: string })?.answer === 'Delivered')
+check('timestamps are monotonic from startTs', (s1?.startedAt ?? 0) >= 1000 && (answer?.startedAt ?? 0) > (s1?.startedAt ?? 0))
+
+// Inline base64 screenshot (the real `bad` case — state.screenshot, no disk path):
+// used directly, no file read.
+const inlineRun = await browserRunToSpans({
+  taskId: 't', driverId: 'bad', finalUrl: 'https://x.test',
+  steps: [{ index: 1, url: 'https://x.test', action: 'click', screenshot: 'data:image/jpeg;base64,/9j/INLINE' }],
+})
+check('inline step.screenshot is carried through directly (no disk read)', (inlineRun[0]?.attributes?.screenshot as string) === 'data:image/jpeg;base64,/9j/INLINE')
+
+// A run whose only screenshot path is unreadable: span stays, image drops (fail-soft).
+const ghost = await browserRunToSpans({
+  taskId: 't', driverId: 'bad', finalUrl: '', steps: [{ index: 1, url: 'about:blank', action: 'navigate', screenshotPath: '/no/such/frame.png' }],
+})
+check('unreadable screenshot drops the image but keeps the step span', ghost.length === 1 && ghost[0]?.attributes?.screenshot === undefined)
+
+rmSync(dir, { recursive: true, force: true })
+
+if (failures > 0) {
+  console.log(`\n❌ ${failures} check(s) failed`)
+  process.exit(1)
+}
+console.log('\n✅ browserRunToSpans verified — steps → tool spans, screenshots inlined as base64, no raw paths')

package/src/browser/ui-reviewer.ts

@@ -0,0 +1,200 @@
+/**
+ * Driver-agnostic UI-REVIEWER PANEL — the design-review analogue of the
+ * browser-agent harness (./agent-adapter.ts).
+ *
+ * "More reviewers, the better": run a PANEL of UI reviewers over the same target
+ * and union their findings — #114's runLoop ui-auditor, browser-agent-driver's
+ * `bad design-audit`, a future reviewer — each a pluggable `UiReviewerAdapter`,
+ * none of them owning the verdict.
+ *
+ * Attestability is the spine, exactly as in agent-adapter.ts: a UI design verdict
+ * is SUBJECTIVE if it comes from an LLM/heuristic, so the panel NEVER lets a
+ * reviewer's own findings or headline score (e.g. a `healthScore`) be the verdict.
+ * The attestable verdict is derived ONLY from the DETERMINISTIC floor a reviewer
+ * MEASURES — axe a11y violations + WCAG AA contrast — re-applied by `judgeUiFloor`.
+ * Subjective findings are surfaced (deduped, attributed) but never gate.
+ *
+ * A reviewer that contributes no deterministic measurements adds findings to the
+ * panel but cannot, by itself, produce an attestable verdict — that is fail-loud,
+ * not a silent pass.
+ */
+
+/** What to review: a site + the routes to visit. */
+export interface UiReviewTarget {
+  url: string
+  /** Route labels/paths to audit; defaults to a single 'home' at `url`. */
+  routes?: { label: string; url: string }[]
+  viewport?: { width: number; height: number }
+  /** Playwright storageState for authenticated review. */
+  storageState?: string
+}
+
+/** A SUBJECTIVE finding (LLM/heuristic). Surfaced + deduped, never the verdict. */
+export interface UiFinding {
+  reviewerId: string
+  /** Lens/category (consistency, hierarchy, accessibility, contrast, ux-flow, …). */
+  lens: string
+  severity: 'critical' | 'major' | 'minor'
+  route: string
+  title: string
+  observation: string
+  impact?: string
+  suggestedFix?: string
+  /** CSS/Playwright selector, when the reviewer pins one — used for dedup. */
+  selector?: string
+}
+
+/** The DETERMINISTIC floor — MEASURED, not judged. This is the attestable layer
+ *  (mirrors browser-agent-driver's `measurements`: axe + WCAG contrast). */
+export interface DesignMeasurements {
+  /** axe a11y violations with rule id + impact. */
+  a11yViolations: { id: string; impact?: string }[]
+  /** WCAG AA contrast pass rate in [0,1] over `contrastTotalChecked` text elements. */
+  contrastAaPassRate: number
+  contrastAaFailures: number
+  contrastTotalChecked: number
+}
+
+/** One reviewer's result for one route. */
+export interface UiReviewRun {
+  reviewerId: string
+  route: string
+  findings: UiFinding[]
+  /** Present only if the reviewer measured the deterministic floor. */
+  measurements?: DesignMeasurements
+  /** The reviewer's OWN headline score (e.g. healthScore 0-100). Recorded for
+   *  comparison, NEVER the verdict. */
+  selfReportedScore?: number
+  usage?: { input: number; output: number }
+  costUsd?: number
+}
+
+/** The general seam every UI reviewer implements — `bad design-audit`, the #114
+ *  ui-auditor, a hosted service. `review` returns one run per route. */
+export interface UiReviewerAdapter {
+  readonly id: string
+  review(target: UiReviewTarget): Promise<UiReviewRun[]>
+}
+
+/** Thresholds for the deterministic blocking gate (defaults mirror the
+ *  browser-agent-driver design-audit floor: 5+ critical a11y OR >25% contrast fail). */
+export interface UiFloorGateConfig {
+  maxCriticalA11y?: number
+  maxContrastFailRate?: number
+}
+
+const A11Y_CRITICAL = new Set(['critical', 'serious'])
+
+/**
+ * The ATTESTABLE verdict — derived ONLY from the deterministic floor across the
+ * runs that measured it. Ignores subjective findings AND selfReportedScore.
+ * resolved = no blocking deterministic issues; score = deterministic design-health
+ * in [0,1] (contrast pass rate × a11y cleanliness). Fail-loud if NO run measured
+ * the floor — a panel of purely-subjective reviewers cannot attest a verdict.
+ */
+export function judgeUiFloor(
+  runs: ReadonlyArray<UiReviewRun>,
+  cfg: UiFloorGateConfig = {},
+): { resolved: boolean; score: number; detail: string } {
+  const maxCriticalA11y = cfg.maxCriticalA11y ?? 5
+  const maxContrastFailRate = cfg.maxContrastFailRate ?? 0.25
+  const measured = runs.filter((r) => r.measurements)
+  if (measured.length === 0) {
+    throw new Error(
+      'judgeUiFloor: no reviewer produced deterministic measurements (axe/contrast) — ' +
+        'subjective findings are not attestable; add a reviewer with a measured floor',
+    )
+  }
+  let criticalA11y = 0
+  let worstContrastFailRate = 0
+  let passRateSum = 0
+  for (const r of measured) {
+    const m = r.measurements as DesignMeasurements
+    criticalA11y += m.a11yViolations.filter((v) => v.impact != null && A11Y_CRITICAL.has(v.impact)).length
+    const failRate = 1 - m.contrastAaPassRate
+    if (failRate > worstContrastFailRate) worstContrastFailRate = failRate
+    passRateSum += m.contrastAaPassRate
+  }
+  const blocking = criticalA11y >= maxCriticalA11y || worstContrastFailRate > maxContrastFailRate
+  const avgContrastPass = passRateSum / measured.length
+  // a11y cleanliness: 1 when no critical issues, decaying toward 0 as they approach the cap.
+  const a11yHealth = Math.max(0, 1 - criticalA11y / maxCriticalA11y)
+  const score = Number((0.6 * avgContrastPass + 0.4 * a11yHealth).toFixed(4))
+  return {
+    resolved: !blocking,
+    score,
+    detail: JSON.stringify({
+      criticalA11y,
+      worstContrastFailRate: Number(worstContrastFailRate.toFixed(4)),
+      avgContrastPass: Number(avgContrastPass.toFixed(4)),
+      measuredReviewers: measured.map((r) => r.reviewerId),
+      blocking,
+    }),
+  }
+}
+
+/** Dedup key for a finding across reviewers: same lens + route + (selector or a
+ *  normalized title) is one issue, regardless of how many reviewers flagged it. */
+function findingKey(f: UiFinding): string {
+  const anchor = f.selector?.trim() || f.title.toLowerCase().replace(/\s+/g, ' ').trim()
+  return `${f.lens.toLowerCase()}|${f.route}|${anchor}`
+}
+
+export interface UiPanelFinding extends UiFinding {
+  /** All reviewers that independently flagged this issue (consensus signal). */
+  flaggedBy: string[]
+}
+
+export interface UiPanelResult {
+  perReviewer: Record<string, UiReviewRun[]>
+  /** Deduped union of findings across reviewers, each tagged with who flagged it. */
+  findings: UiPanelFinding[]
+  /** The attestable deterministic-floor verdict (NOT a vote over findings). */
+  verdict: { resolved: boolean; score: number; detail: string }
+}
+
+/**
+ * Run a PANEL of reviewers over one target, union+dedup their subjective findings
+ * (attributed, with a consensus count), and attest the deterministic floor. A
+ * reviewer that throws is recorded as empty (its absence is visible in
+ * perReviewer), never silently merged as a pass.
+ */
+export async function runUiReviewerPanel(
+  target: UiReviewTarget,
+  reviewers: ReadonlyArray<UiReviewerAdapter>,
+  cfg: UiFloorGateConfig = {},
+): Promise<UiPanelResult> {
+  if (reviewers.length === 0) throw new Error('runUiReviewerPanel: no reviewers given')
+  const settled = await Promise.all(
+    reviewers.map(async (rev) => {
+      try {
+        return { id: rev.id, runs: await rev.review(target) }
+      } catch (err) {
+        return { id: rev.id, runs: [] as UiReviewRun[], error: err instanceof Error ? err.message : String(err) }
+      }
+    }),
+  )
+  const perReviewer: Record<string, UiReviewRun[]> = {}
+  const allRuns: UiReviewRun[] = []
+  for (const s of settled) {
+    perReviewer[s.id] = s.runs
+    allRuns.push(...s.runs)
+  }
+  const byKey = new Map<string, UiPanelFinding>()
+  for (const run of allRuns) {
+    for (const f of run.findings) {
+      const key = findingKey(f)
+      const existing = byKey.get(key)
+      if (existing) {
+        if (!existing.flaggedBy.includes(f.reviewerId)) existing.flaggedBy.push(f.reviewerId)
+      } else {
+        byKey.set(key, { ...f, flaggedBy: [f.reviewerId] })
+      }
+    }
+  }
+  return {
+    perReviewer,
+    findings: [...byKey.values()],
+    verdict: judgeUiFloor(allRuns, cfg),
+  }
+}

package/src/browser/ui-reviewer.verify.ts

@@ -0,0 +1,94 @@
+/**
+ * Deterministic self-check for the UI-reviewer panel — `tsx src/browser/ui-reviewer.verify.ts`.
+ *
+ * Defends the same property as the browser harness: the verdict is ATTESTABLE —
+ * it comes from the measured deterministic floor (axe + contrast), never a
+ * reviewer's subjective findings or self-reported headline score.
+ */
+
+import {
+  judgeUiFloor,
+  runUiReviewerPanel,
+  type UiReviewRun,
+  type UiReviewerAdapter,
+  type UiReviewTarget,
+} from './ui-reviewer'
+
+let failures = 0
+function check(name: string, cond: boolean, detail = '') {
+  if (cond) console.log(`  ✓ ${name}`)
+  else {
+    failures += 1
+    console.log(`  ✗ ${name} ${detail}`)
+  }
+}
+
+const clean: UiReviewRun = {
+  reviewerId: 'bad',
+  route: 'home',
+  findings: [],
+  measurements: { a11yViolations: [], contrastAaPassRate: 0.99, contrastAaFailures: 1, contrastTotalChecked: 120 },
+  selfReportedScore: 92,
+}
+// A reviewer SCREAMING success (healthScore 100) while the measured floor is blocking.
+const liar: UiReviewRun = {
+  reviewerId: 'bad',
+  route: 'home',
+  findings: [],
+  selfReportedScore: 100,
+  measurements: {
+    a11yViolations: [
+      { id: 'color-contrast', impact: 'serious' },
+      { id: 'aria-required', impact: 'critical' },
+      { id: 'label', impact: 'critical' },
+      { id: 'button-name', impact: 'critical' },
+      { id: 'link-name', impact: 'serious' },
+    ],
+    contrastAaPassRate: 0.5,
+    contrastAaFailures: 60,
+    contrastTotalChecked: 120,
+  },
+}
+
+console.log('ui-reviewer panel verify:')
+
+const okV = judgeUiFloor([clean])
+check('clean floor → resolved=true, high score', okV.resolved === true && okV.score > 0.9, okV.detail)
+
+const liarV = judgeUiFloor([liar])
+check('self-reported 100 IGNORED — measured floor blocks → resolved=false', liarV.resolved === false, liarV.detail)
+check('blocking score is low', liarV.score < 0.6, liarV.detail)
+
+// fail-loud: a purely-subjective panel (no measurements) cannot attest.
+let threw = false
+try {
+  judgeUiFloor([{ reviewerId: 'ui-auditor', route: 'home', findings: [], selfReportedScore: 80 }])
+} catch {
+  threw = true
+}
+check('no measured floor → throws (subjective findings are not attestable)', threw)
+
+// panel dedup + consensus across two reviewers flagging the same issue.
+const finding = (reviewerId: string) => ({
+  reviewerId,
+  lens: 'contrast',
+  severity: 'major' as const,
+  route: 'home',
+  title: 'Low contrast on primary CTA',
+  observation: 'x',
+  selector: 'button.cta',
+})
+const revA: UiReviewerAdapter = { id: 'bad', async review() { return [{ ...clean, reviewerId: 'bad', findings: [finding('bad')] }] } }
+const revB: UiReviewerAdapter = { id: 'ui-auditor', async review() { return [{ reviewerId: 'ui-auditor', route: 'home', findings: [finding('ui-auditor')] }] } }
+const target: UiReviewTarget = { url: 'https://example.com' }
+const panel = await runUiReviewerPanel(target, [revA, revB])
+check('panel dedups the same issue across reviewers to ONE finding', panel.findings.length === 1, `got ${panel.findings.length}`)
+check('deduped finding records BOTH reviewers (consensus)', (panel.findings[0]?.flaggedBy ?? []).length === 2, JSON.stringify(panel.findings[0]?.flaggedBy))
+check('panel verdict comes from the measured reviewer (bad), resolved=true', panel.verdict.resolved === true, panel.verdict.detail)
+check('perReviewer records both reviewers', Object.keys(panel.perReviewer).length === 2)
+
+if (failures > 0) {
+  console.log(`\n❌ ${failures} check(s) failed`)
+  process.exit(1)
+}
+console.log('\n✅ UI-reviewer panel verified — verdict is the measured floor, self-report ignored, findings deduped across reviewers')