@broberg/lens-daemon 0.0.0-stage → 0.1.0

package/src/browser.ts

@@ -0,0 +1,440 @@
+// F074.1 — Lens browser manager.
+//
+// Owns a single WARM headless Chromium for the daemon. The browser is
+// launched lazily on first capture and reused across captures (launch is
+// ~300ms; reusing it makes a capture-catalogue batch fast). An idle timer
+// closes it after ~5 min of inactivity so a quiet daemon doesn't hold a
+// Chromium process forever.
+//
+// Each capture gets its OWN browser context (isolated cookies/storage) so
+// auth (F074.4) and concurrent captures never bleed into each other. The
+// context + page are always closed in a finally, even on capture error.
+
+import {
+  chromium,
+  webkit,
+  firefox,
+  type Browser,
+  type BrowserContext,
+  type BrowserType,
+  type Page,
+} from 'playwright';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { READINESS_INIT_SCRIPT } from './readiness.ts';
+import { applyStorageSeed, type StoragePayload } from './seed-storage.ts';
+
+const IDLE_TIMEOUT_MS = 5 * 60 * 1000;
+
+// F098.9 — Lens can drive any of the three engines. Chromium is the default;
+// webkit/firefox let Lens catch Safari-only / cross-engine bugs (backdrop-filter
+// containing-block, -webkit quirks, 100vh/dvh, sticky) that chromium renders
+// fine — the class of bug chromium-only Lens would falsely stamp GREEN.
+export type LensEngine = 'chromium' | 'webkit' | 'firefox';
+const ENGINES: Record<LensEngine, BrowserType> = { chromium, webkit, firefox };
+
+// One warm browser PER engine, launched lazily + reused. Keyed by engine so a
+// webkit capture doesn't relaunch chromium and vice-versa.
+const browsers = new Map<LensEngine, Promise<Browser>>();
+let idleTimer: ReturnType<typeof setTimeout> | null = null;
+
+/**
+ * F346.46 — CHROMIUM GETS A SYNTHETIC MICROPHONE AND CAMERA.
+ *
+ * Without these, `getUserMedia` in a Lens run HANGS: headless Chromium has no
+ * capture device and no human to answer the permission prompt, so the promise
+ * never settles and the flow dies on a timeout that says nothing about why.
+ * Measured 16 Sep 2026 — an assert calling getUserMedia({audio:true}) timed the
+ * whole manuscript out.
+ *
+ * That made a whole class of feature UNTESTABLE by our own tool: anything that
+ * records. Scope's recorder is exactly that, and it shipped a defect (nothing
+ * was ever captured, and nothing said so) which an E2E run would have caught on
+ * the first try.
+ *
+ *   --use-fake-device-for-media-stream  a synthetic mic + camera, so tracks exist
+ *   --use-fake-ui-for-media-stream      auto-grant, so nothing waits on a human
+ *   --autoplay-policy=no-user-gesture-required  a captured stream can play back
+ *
+ * THE FAKE MIC EMITS A TONE, NOT SILENCE — Chromium's synthetic audio device is
+ * a beep. That matters for what a recording test can prove: the CHAIN (bytes
+ * produced, buffered, uploaded, stored) is real and fully exercised; the WORDS
+ * are not, because a tone transcribes to nothing. A run must therefore assert on
+ * chunk counts and bytes, never on transcript text, or it asserts something the
+ * fixture cannot deliver.
+ *
+ * Chromium only: webkit/firefox reject unknown args, and a rejected arg takes
+ * the whole launch down.
+ */
+const CHROMIUM_ARGS = [
+  // Hardening for constrained, loopback-bound hosts.
+  '--disable-dev-shm-usage',
+  '--no-sandbox',
+  // Media capture, so a recording surface can actually be driven.
+  '--use-fake-device-for-media-stream',
+  '--use-fake-ui-for-media-stream',
+  '--autoplay-policy=no-user-gesture-required',
+];
+
+async function launch(engine: LensEngine): Promise<Browser> {
+  const args = engine === 'chromium' ? CHROMIUM_ARGS : [];
+  return ENGINES[engine].launch({ headless: true, args });
+}
+
+/** Get the warm browser for an engine, launching it on first use. Re-launches
+ *  if a previous instance crashed / disconnected. */
+export async function getBrowser(engine: LensEngine = 'chromium'): Promise<Browser> {
+  let p = browsers.get(engine);
+  if (!p) {
+    p = launch(engine).catch((err) => {
+      browsers.delete(engine);
+      throw err;
+    });
+    browsers.set(engine, p);
+  }
+  const browser = await p;
+  if (!browser.isConnected()) {
+    browsers.delete(engine);
+    return getBrowser(engine);
+  }
+  return browser;
+}
+
+// Wedge watchdog (lens-gap, 2026-06-13 incident): a Chromium that is alive but
+// unresponsive (isConnected() true, every CDP call hangs) used to hang EVERY
+// withPage call until a daemon restart — the idle timer never fired because
+// each retry re-armed it on entry. Guard the engine-touching awaits with a
+// deadline; on timeout, discard the wedged browser and retry once fresh.
+const WEDGE_TIMEOUT_MS = 20_000;
+
+function withDeadline<T>(p: Promise<T>, ms: number, what: string): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const t = setTimeout(
+      () => reject(new Error(`lens browser wedged: ${what} exceeded ${ms}ms`)),
+      ms,
+    );
+    t.unref?.();
+    p.then(
+      (v) => {
+        clearTimeout(t);
+        resolve(v);
+      },
+      (e) => {
+        clearTimeout(t);
+        reject(e);
+      },
+    );
+  });
+}
+
+/** Drop the cached browser immediately and force-close it in the background
+ *  (close on a wedged process may itself hang — never await it). */
+function discardBrowser(engine: LensEngine): void {
+  const p = browsers.get(engine);
+  browsers.delete(engine);
+  if (p) void p.then((b) => b.close()).catch(() => {});
+}
+
+function armIdleTimer(): void {
+  if (idleTimer) clearTimeout(idleTimer);
+  idleTimer = setTimeout(() => {
+    void closeBrowser();
+  }, IDLE_TIMEOUT_MS);
+  // Don't keep the daemon process alive just for the idle timer.
+  idleTimer.unref?.();
+}
+
+/** Close the warm browser + cancel the idle timer. Called by the idle
+ *  timeout and on daemon shutdown. Safe to call when nothing is open. */
+export async function closeBrowser(): Promise<void> {
+  if (idleTimer) {
+    clearTimeout(idleTimer);
+    idleTimer = null;
+  }
+  const all = [...browsers.values()];
+  browsers.clear();
+  await Promise.all(
+    all.map(async (p) => {
+      try {
+        const browser = await p;
+        if (browser.isConnected()) await browser.close();
+      } catch {
+        // already gone — nothing to close
+      }
+    }),
+  );
+}
+
+export interface WithPageOptions {
+  /** F098.9 — which engine to drive (default chromium). */
+  engine?: LensEngine;
+  viewport?: { width: number; height: number };
+  deviceScaleFactor?: number;
+  /** F125.2 — disable the page's Content-Security-Policy so injected scripts
+   *  (Readability via addScriptTag) run on CSP-strict sites (Medium etc.).
+   *  Scrape-only; Lens captures leave it false. */
+  bypassCSP?: boolean;
+  /** F125.2 — override the browser User-Agent. Must match the UA the captured
+   *  cf_clearance cookie was minted with, or Cloudflare re-challenges. */
+  userAgent?: string;
+  /** F074.57 — BCP-47 locale for the browser context, e.g. "da-DK". Decides
+   *  navigator.language, Accept-Language, and every Intl/toLocaleString result.
+   *  UNSET means unset: no key reaches Playwright, so existing baselines cannot
+   *  move for anyone who has not asked for this. */
+  locale?: string;
+  /** F074.57 — IANA timezone, e.g. "Europe/Copenhagen". Measured 2026-08-23: with
+   *  this unset the context inherits the HOST machine's zone, so the same page
+   *  renders different dates on the Mac and on Cloud Lens. Same unset rule. */
+  timezone?: string;
+  /** F074.59 — what this context reports for `prefers-reduced-motion`.
+   *
+   *  DEFAULT 'reduce', which is exactly what every run did before this option
+   *  existed (see the comment on reducedMotion in contextOptions for WHY that
+   *  default is right and must stay). 'no-preference' is the opt-in that lets a
+   *  run SEE motion — the animation blind spot F074.59 exists to close.
+   *
+   *  Unlike locale/timezone this is NOT spread-if-present: "unset" here has a
+   *  concrete meaning ('reduce'), not "pass nothing", because passing nothing
+   *  would hand the fleet a different browser than it has been photographing. */
+  reducedMotion?: 'reduce' | 'no-preference';
+  /** F125.2 — mask the navigator.webdriver automation flag so anti-bot walls
+   *  (Cloudflare) treat the page like a real browser. Scrape-only. */
+  stealth?: boolean;
+  /** F074.4 hook: run against the fresh context BEFORE the page is created
+   *  (e.g. inject auth cookies / storageState). */
+  prepareContext?: (context: BrowserContext) => Promise<void>;
+  /** F074.97 — localStorage/sessionStorage to write BEFORE the first navigation,
+   *  so the app's own first render already sees it. Built by storagePayload()
+   *  from the run's target url, which is where the origin guard comes from.
+   *  NULL/absent registers NO init script at all — that is the negative control
+   *  that keeps every existing baseline in the fleet byte-identical. */
+  seedStorage?: StoragePayload | null;
+  /** F144.19 — record the whole session to a .webm in this dir. Playwright
+   *  writes the file when the context closes; read the path via page.video()?.path()
+   *  AFTER withPage resolves. Used for live-liveness PROOF captures (an LSD that
+   *  updates in real time can't be shown by a single screenshot). */
+  recordVideoDir?: string;
+  /** F074.69 — load an UNPACKED browser extension and drive its own pages.
+   *
+   *  Without this, no extension in the fleet has any visual gate: an extension
+   *  popup lives at chrome-extension://<id>/popup.html, and that id only exists
+   *  in a browser launched WITH the extension. Serving dist/popup.html over http
+   *  is not a substitute — the popup calls chrome.storage on mount, throws with
+   *  no chrome API, and photographs blank or as a stub that LOOKS like the
+   *  product. That screenshot on a store listing would be fabricated.
+   *
+   *  This is a SECOND launch path, not a flag on the warm browser: extensions
+   *  need launchPersistentContext with a real user-data dir on disk. */
+  extension?: { path: string };
+}
+
+/** Exported for test: F074.57's central promise to everyone who did NOT ask for
+ *  a locale is that an unset one passes NOTHING to Playwright. That is a claim
+ *  about this object, so it is asserted on this object. */
+export function contextOptions(opts: WithPageOptions) {
+  return {
+    bypassCSP: opts.bypassCSP ?? false,
+    ...(opts.userAgent ? { userAgent: opts.userAgent } : {}),
+    // F074.57 — spread-if-present, never `locale: opts.locale ?? undefined`. An
+    // explicit `undefined` key is still a key, and the point of "unset" here is
+    // that Playwright receives NOTHING and every existing baseline stays valid.
+    ...(opts.locale ? { locale: opts.locale } : {}),
+    ...(opts.timezone ? { timezoneId: opts.timezone } : {}),
+    viewport: opts.viewport ?? { width: 1280, height: 800 },
+    // Default scale factor 1 keeps screenshots deterministic across machines
+    // (a retina 2x shot diffs noisily against a 1x baseline).
+    deviceScaleFactor: opts.deviceScaleFactor ?? 1,
+    // Lens captures localhost dev-servers, which commonly serve HTTPS with a
+    // self-signed / mkcert cert (cms-admin :3010 must be HTTPS). Trust them —
+    // this is a local dev tool, not a public crawler.
+    ignoreHTTPSErrors: true,
+    // F098.8 — emulate prefers-reduced-motion: reduce. Two wins: (1) an app that
+    // gates a perpetual requestAnimationFrame loop (trail's constellation canvas)
+    // on this media query stops animating, freeing the headless main thread so
+    // the initial render + auth microtask (/api/auth/me) resolve instead of
+    // starving past the wait timeout → blank capture; (2) motion-stable baselines
+    // (a mid-animation frame otherwise yields a false pixel-diff). Apps SHOULD
+    // honour prefers-reduced-motion anyway — this is correct a11y, not a hack.
+    // F074.59 — per-run, defaulting to the F098.8 behaviour above. A caller that
+    // asks for 'no-preference' gets a browser that can actually SEE an animation;
+    // everyone else gets the byte-identical context they had yesterday, which is
+    // the promise that lets this ship without touching a single baseline.
+    reducedMotion: opts.reducedMotion ?? ('reduce' as const),
+    // F126.11 — grant clipboard access so a "copy" button can be proven on its
+    // SUCCESS path, not only on its failure path.
+    //
+    // xrt81 (#21085) closed a card with this stated openly rather than ticked:
+    // pressing their copy button in the automated browser produced "Couldn't
+    // copy — select the address and copy it yourself". The message is good and
+    // the fallback works, but the green confirmation had never been seen. Every
+    // copy button in the fleet was in that position — verifiable only when it
+    // fails.
+    //
+    // That is the day's theme arriving from the opposite end. Everywhere else we
+    // found green without coverage; here the coverage was impossible, so the card
+    // had to say so. It should not have to: Chromium simply denies the permission
+    // by default and Playwright can grant it per context.
+    //
+    // Chromium-only — webkit and firefox reject unknown permission names and
+    // would fail every capture on those engines. Wrapped so an engine that does
+    // not know the name is unaffected rather than broken.
+    ...(opts.engine === undefined || opts.engine === 'chromium'
+      ? {
+          // F346.46 — MICROPHONE AND CAMERA GRANTED TOO. The launch flags give
+          // Chromium a synthetic device; this grants the PAGE permission to open
+          // it. Both halves are needed: without the flag there is no device and
+          // getUserMedia rejects; without the grant it waits for a human who is
+          // not there, and the flow dies on a timeout that names nothing.
+          permissions: ['clipboard-read', 'clipboard-write', 'microphone', 'camera'],
+        }
+      : {}),
+    // F144.19 — optional session video recording (live-liveness proof).
+    ...(opts.recordVideoDir
+      ? { recordVideo: { dir: opts.recordVideoDir, size: opts.viewport ?? { width: 1280, height: 800 } } }
+      : {}),
+  };
+}
+
+/** Run `fn` with a fresh isolated context + page, then tear both down.
+ *  Resets the idle timer on entry so an active daemon keeps its browser warm. */
+/** F074.69 — the id Chromium generated for the loaded extension, handed to the
+ *  caller. It is derived at LOAD time, so it is read back from the extension's
+ *  service-worker URL rather than guessed — a manuscript cannot hardcode it. */
+export interface LoadedExtension {
+  id: string;
+  path: string;
+}
+
+/** F074.69 — MEASURED before the design depended on the answer (probe, 2026-08-29):
+ *
+ *    bundled chromium, headless          serviceWorker=false  id=null   NOT LOADED
+ *    bundled chromium, --headless=new    serviceWorker=false  id=null   NOT LOADED
+ *    bundled chromium, headed            serviceWorker=true   id=cacc…  works
+ *    channel:'chromium', headless        serviceWorker=true   id=cacc…  works
+ *
+ *  So the answer to the plan's open question — "does it need a head?" — is NO,
+ *  but only off the CHANNEL build. Playwright's bundled headless is the
+ *  chromium-headless-shell, which has no extension support at all; the full
+ *  Chromium binary does, in the new headless mode. That distinction is the whole
+ *  reason this can run on a headless host (and therefore on Cloud Lens) instead
+ *  of needing a screen. */
+const EXTENSION_CHANNEL = 'chromium';
+
+async function launchWithExtension(
+  opts: WithPageOptions,
+  extPath: string,
+): Promise<{ context: BrowserContext; extension: LoadedExtension; userDataDir: string }> {
+  const userDataDir = await mkdtemp(join(tmpdir(), 'lens-ext-'));
+  const context = await chromium.launchPersistentContext(userDataDir, {
+    ...contextOptions(opts),
+    headless: true,
+    channel: EXTENSION_CHANNEL,
+    args: [
+      `--disable-extensions-except=${extPath}`,
+      `--load-extension=${extPath}`,
+      '--disable-dev-shm-usage',
+      '--no-sandbox',
+    ],
+  });
+  // MV3 registers a service worker; MV2 a background page. Wait for whichever
+  // appears — the id lives in its URL host either way.
+  let worker = context.serviceWorkers()[0];
+  if (!worker) {
+    worker = await context
+      .waitForEvent('serviceworker', { timeout: 15_000 })
+      .catch(() => undefined as never);
+  }
+  const bg = worker?.url() ?? context.backgroundPages()[0]?.url();
+  if (!bg) {
+    await context.close().catch(() => {});
+    await rm(userDataDir, { recursive: true, force: true }).catch(() => {});
+    throw new Error(
+      `extension at ${extPath} loaded no service worker or background page within 15s — ` +
+        'its id cannot be resolved, so nothing can be captured from it. Check that the path is ' +
+        'an UNPACKED build directory containing manifest.json (not a .zip, not the source dir).',
+    );
+  }
+  return { context, extension: { id: new URL(bg).host, path: extPath }, userDataDir };
+}
+
+export async function withPage<T>(
+  opts: WithPageOptions,
+  fn: (page: Page, context: BrowserContext, extension?: LoadedExtension) => Promise<T>,
+): Promise<T> {
+  armIdleTimer();
+  const engine = opts.engine ?? 'chromium';
+
+  // F074.69 — the extension path is its own launch, its own lifecycle, its own
+  // cleanup. It deliberately does NOT reuse the warm browser.
+  if (opts.extension) {
+    if (engine !== 'chromium') {
+      // Refused with a reason rather than failing oddly further in — the same
+      // posture lens_export takes for PDF. The planned Safari extension is a
+      // different problem and is not covered by pretending this works.
+      throw new Error(
+        `extensions are chromium-only; engine "${engine}" cannot load one. ` +
+          'Drop the engine option or pass engine:"chromium".',
+      );
+    }
+    const { context, extension, userDataDir } = await launchWithExtension(opts, opts.extension.path);
+    try {
+      await context.addInitScript(READINESS_INIT_SCRIPT);
+      if (opts.prepareContext) await opts.prepareContext(context);
+      // F074.97 — AFTER prepareContext on purpose: init scripts run in
+      // registration order, so a per-run seed outranks the same key inside an
+      // auth storageState blob. A per-call instruction is the more specific one.
+      await applyStorageSeed(context, opts.seedStorage ?? null);
+      // A persistent context opens with a page already; reuse it rather than
+      // leaving a blank one behind.
+      const page = context.pages()[0] ?? (await context.newPage());
+      if (opts.viewport) await page.setViewportSize(opts.viewport);
+      return await fn(page, context, extension);
+    } finally {
+      await withDeadline(context.close(), 5_000, 'extension context close').catch(() => {});
+      // The user-data dir is ours and nobody else's; leaving it leaks a real
+      // directory per capture.
+      await rm(userDataDir, { recursive: true, force: true }).catch(() => {});
+    }
+  }
+
+  const makeContext = async (): Promise<BrowserContext> => {
+    const browser = await withDeadline(getBrowser(engine), WEDGE_TIMEOUT_MS, 'browser launch');
+    return withDeadline(
+      browser.newContext(contextOptions(opts)),
+      WEDGE_TIMEOUT_MS,
+      'newContext',
+    );
+  };
+  let context: BrowserContext;
+  try {
+    context = await makeContext();
+  } catch (err) {
+    if (!(err instanceof Error && err.message.includes('lens browser wedged'))) throw err;
+    discardBrowser(engine);
+    // One retry on a fresh launch; a second wedge propagates to the caller.
+    context = await makeContext();
+  }
+  try {
+    if (opts.stealth) {
+      // Mask the most-checked automation signal before any page script runs.
+      await context.addInitScript(() => {
+        Object.defineProperty(navigator, 'webdriver', { get: () => undefined });
+      });
+    }
+    // F213.8 — observe listener registration before ANY page script runs, so a
+    // flow can later ask whether the page is actually listening rather than
+    // whether it merely painted. Unconditional on purpose: it must be installed
+    // before we know whether this run will ask, and it costs one wrapped
+    // function call per addEventListener. It only records; it never blocks.
+    await context.addInitScript(READINESS_INIT_SCRIPT);
+    if (opts.prepareContext) await opts.prepareContext(context);
+    // F074.97 — see the extension branch above: seed AFTER auth, before any page.
+    await applyStorageSeed(context, opts.seedStorage ?? null);
+    const page = await context.newPage();
+    return await fn(page, context);
+  } finally {
+    // close() on a wedged browser can hang too — bounded, then best-effort.
+    await withDeadline(context.close(), 5_000, 'context close').catch(() => {});
+  }
+}

package/src/build-marker.ts

@@ -0,0 +1,197 @@
+// F255.7 — wait for the deployed build to actually be serving before a flow verifies it.
+//
+// The failure this exists to kill: GitHub Actions reports a deploy as `success` while the
+// machines are still rolling, Lens runs against the PREVIOUS build, and everything passes.
+// That green run is worse than a red one — it verifies real behaviour, just of the code you
+// replaced, so nothing in the output looks suspicious (fd-sundhed, 2026-07-30).
+//
+// The contract: every cardmem-enrolled app reports the git sha of the RUNNING build in
+// `build` at GET /api/health. A convention, not per-flow config — per-flow means each repo
+// has to remember to wire it, and the repo that forgets is exactly the one that gets the
+// false green. A contract you can skip only protects the people who did not need it.
+//
+// Four rules this module exists to enforce, three of them learned the hard way:
+//   1. Wait for a KNOWN sha when the caller has one. "Wait until it CHANGES" hangs when the
+//      flow starts mid-rollout with the new value already live — which is precisely when
+//      someone is impatient and runs the verification early.
+//   2. Require N CONSECUTIVE matching polls. A fleet mid-roll answers old/new/old, so a
+//      single hit on the one machine that finished is not proof the rollout is done.
+//   3. Fetch from HERE, never through the page. A service worker serves a cached build, so
+//      a page-side poll happily reports the new marker on a page running the old code.
+//   4. A missing marker FAILS. Skipping the wait would restore the exact false confidence
+//      the contract removes — only now with a green tick on it.
+
+/** Default path of the marker. The contract path, not a per-flow knob. */
+export const BUILD_MARKER_PATH = '/api/health';
+
+/** Shortest sha prefix accepted as `expected` — git's own default abbreviation. */
+export const MIN_SHA_PREFIX = 7;
+const HEX = /^[0-9a-f]+$/;
+
+export interface WaitForBuildOptions {
+  /** The sha to wait FOR. Omit to fall back to "changed from the value at start". */
+  expected?: string | null;
+  /** Give up after this long (default 180s — a Fly rolling deploy of a few machines). */
+  timeoutMs?: number;
+  /** Gap between polls (default 2s). */
+  intervalMs?: number;
+  /** Consecutive matching reads required before we call it live (default 3). */
+  consecutive?: number;
+  /** Injected for tests. */
+  fetchImpl?: typeof fetch;
+  now?: () => number;
+  sleep?: (ms: number) => Promise<void>;
+}
+
+export interface WaitForBuildResult {
+  build: string;
+  polls: number;
+  waited_ms: number;
+  /** How the target was decided — useful in the step detail. */
+  mode: 'expected-sha' | 'changed-from-start';
+}
+
+export class BuildMarkerError extends Error {}
+
+/** Read the marker once, straight from the runner. Never through the page: see rule 3. */
+export async function readBuildMarker(
+  baseUrl: string,
+  attempt: number,
+  fetchImpl: typeof fetch = fetch,
+): Promise<string> {
+  const url = new URL(BUILD_MARKER_PATH, baseUrl);
+  // Cache-bust on BOTH axes: a query the CDN has never seen, plus no-store, so neither an
+  // edge cache nor the local HTTP cache can hand back a stale marker.
+  url.searchParams.set('_lens_build', String(attempt));
+  let res: Response;
+  try {
+    res = await fetchImpl(url.toString(), {
+      cache: 'no-store',
+      headers: { 'Cache-Control': 'no-cache', Pragma: 'no-cache', Accept: 'application/json' },
+    });
+  } catch (err) {
+    throw new BuildMarkerError(`build marker unreachable at ${url.pathname}: ${(err as Error).message}`);
+  }
+  if (!res.ok) {
+    throw new BuildMarkerError(`build marker returned HTTP ${res.status} at ${url.pathname}`);
+  }
+  let body: unknown;
+  try {
+    body = await res.json();
+  } catch {
+    // The classic shape of this failure: /api/* falls through to the SPA and answers HTML.
+    throw new BuildMarkerError(
+      `build marker at ${url.pathname} did not return JSON — the route probably falls through to the SPA`,
+    );
+  }
+  const build = (body as { build?: unknown })?.build;
+  if (typeof build !== 'string' || build.trim() === '') {
+    throw new BuildMarkerError(
+      `no build marker: ${url.pathname} has no "build" field, so a new build cannot be told from an old one. ` +
+        'Add build = the running git sha (F255.7 contract) before gating a run on it.',
+    );
+  }
+  return build.trim();
+}
+
+/** Block until the app is demonstrably serving the build we are about to verify. */
+export async function waitForBuild(baseUrl: string, opts: WaitForBuildOptions = {}): Promise<WaitForBuildResult> {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const now = opts.now ?? Date.now;
+  const sleep = opts.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
+  const timeoutMs = opts.timeoutMs ?? 180_000;
+  const intervalMs = opts.intervalMs ?? 2_000;
+  const needed = Math.max(1, opts.consecutive ?? 3);
+  const expected = opts.expected?.trim().toLowerCase() || null;
+  // F255.7.1 — a short sha is what agents actually have (`git log --oneline`, handoffs), so
+  // a hex expectation matches as a PREFIX of the served sha. Below git's 7-char default a
+  // prefix stops being a fingerprint, so it is refused before we wait 180s to say so.
+  const expectedHex = expected !== null && HEX.test(expected);
+  if (expectedHex && expected.length < MIN_SHA_PREFIX) {
+    throw new BuildMarkerError(
+      `expected sha "${expected}" is too short — pass at least ${MIN_SHA_PREFIX} hex characters (or the full sha).`,
+    );
+  }
+
+  const startedAt = now();
+  let polls = 0;
+
+  // The first read establishes the baseline for the changed-from-start mode. A missing
+  // marker throws here, before any waiting — the loud failure of rule 4.
+  polls += 1;
+  const first = await readBuildMarker(baseUrl, polls, fetchImpl);
+  const matches = (v: string) => {
+    if (!expected) return v !== first;
+    const served = v.toLowerCase();
+    // A non-hex marker (a version string, a date) keeps exact equality: prefix-matching free
+    // text would turn "v1" into a match for "v1.2" — a false green.
+    return expectedHex && HEX.test(served) ? served.startsWith(expected) : served === expected;
+  };
+
+  // Rule 1: with an explicit sha that is ALREADY live we must not sit waiting for a change
+  // that will never come — so `first` is allowed to count toward the streak.
+  let streak = matches(first) ? 1 : 0;
+  let last = first;
+
+  while (streak < needed) {
+    if (now() - startedAt >= timeoutMs) {
+      const target = expected ? `sha ${expected}` : `any build other than ${first}`;
+      throw new BuildMarkerError(
+        `timed out after ${Math.round((now() - startedAt) / 1000)}s waiting for ${target} — ` +
+          `still serving ${last} after ${polls} polls. The deploy may have failed, or the app is not reporting the new sha.`,
+      );
+    }
+    await sleep(intervalMs);
+    polls += 1;
+    last = await readBuildMarker(baseUrl, polls, fetchImpl);
+    // Rule 2: a non-matching read RESETS the streak. Mid-rollout the fleet answers
+    // old/new/old, and only an unbroken run of matches means every machine has flipped.
+    streak = matches(last) ? streak + 1 : 0;
+  }
+
+  return {
+    build: last,
+    polls,
+    waited_ms: now() - startedAt,
+    mode: expected ? 'expected-sha' : 'changed-from-start',
+  };
+}
+
+/** How long a best-effort marker read may take. Short on purpose: this runs on
+ *  EVERY capture, and a target with no marker (a plain dev server) must cost
+ *  almost nothing. It is a measurement we would like, never one we require. */
+export const OBSERVE_TIMEOUT_MS = 2_000;
+
+/**
+ * F074.30 — read the build a run is about to look at, best-effort.
+ *
+ * Returns the sha, or NULL when the target exposes no marker, is unreachable, or
+ * is too slow. NULL means "not measured" and must never be read as "same build
+ * as the other run": a comparison spanning a null has to refuse rather than
+ * reassure. That is the whole reason this returns null instead of a placeholder
+ * — an empty string or a "unknown" literal would compare equal to itself and
+ * manufacture exactly the false "no regression" this exists to prevent.
+ *
+ * Unlike readBuildMarker it NEVER throws. A capture that would otherwise pass
+ * must not fail because an optional measurement was unavailable.
+ */
+export async function observeBuild(
+  baseUrl: string,
+  opts: { fetchImpl?: typeof fetch; timeoutMs?: number } = {},
+): Promise<string | null> {
+  const timeoutMs = opts.timeoutMs ?? OBSERVE_TIMEOUT_MS;
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  const base = opts.fetchImpl ?? fetch;
+  // Cast: readBuildMarker only ever CALLS this, so Bun's extra `fetch.preconnect`
+  // property on the nominal type is irrelevant here.
+  const withSignal = ((input: Parameters<typeof fetch>[0], init?: RequestInit) =>
+    base(input, { ...init, signal: ctrl.signal })) as unknown as typeof fetch;
+  try {
+    return await readBuildMarker(baseUrl, 0, withSignal);
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}