@broberg/lens-daemon 0.0.0-stage → 0.1.0

package/src/capture-session.ts

@@ -0,0 +1,873 @@
+// F240.6 — headed capture-session.
+//
+// Opens a VISIBLE (headed) Chromium so a human can log in to a site that needs
+// interactive auth — 2FA / CAPTCHA (Google Play Console, Apple App Store Connect)
+// — then dumps the resulting Playwright storageState (cookies + origins) to a
+// LOCAL file that another local tool (e.g. storeform's daemon, via `--state`)
+// reuses for headless automation.
+//
+// This is the canonical F112 answer to "Lens can't capture a 2FA login": the
+// capability lives INSIDE the daemon (which owns `playwright` directly), never a
+// raw one-off `playwright open` script. The daemon's warm browser (browser.ts)
+// is headless-only + short-lived; an interactive login is a long-lived,
+// human-paced session, so it gets its OWN headed browser launched here.
+//
+// SECURITY: the storageState holds Christian's real Google/Apple session. It is
+// written to a gitignored local file, never returned over the wire (the finish
+// response carries only the path + cookie/origin COUNTS) and never logged. Writes
+// are confined to ~/.lens/state so a bad state_path can't clobber an arbitrary
+// file. The endpoint is loopback-only (127.0.0.1) behind the daemon's auth.
+
+import { chromium, type Browser, type BrowserContext, type Page } from 'playwright';
+import { z } from 'zod';
+import { mkdirSync, existsSync, copyFileSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, resolve, sep } from 'node:path';
+import { homedir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { fillAndVerify } from './fill.ts';
+
+interface Session {
+  browser: Browser;
+  context: BrowserContext;
+  page: Page;
+  url: string;
+  statePath: string;
+  startedAt: number;
+  timer: ReturnType<typeof setTimeout>;
+  /** F240.8 — `finish` is running. The session stays in the registry while the
+   *  write is in flight, so `cancel` can say IN PROGRESS instead of "unknown". */
+  finishing?: boolean;
+}
+
+/** F240.8 — the narrow shape `finish` actually needs, so the lifecycle can be
+ *  tested without launching Chrome. Same reason `StepPage` exists below: a test
+ *  that cannot construct a session cannot seal an ORDERING property, and the
+ *  ordering is half this card. */
+export interface FinishableSession {
+  browser: { close(): Promise<void> };
+  context: { storageState(): Promise<{ cookies: unknown[]; origins: unknown[] }> };
+  statePath: string;
+  timer: ReturnType<typeof setTimeout>;
+  finishing?: boolean;
+}
+
+/** Launch a HEADED browser that Google's "this browser may not be secure" bot-check
+ *  won't refuse. The defeat recipe: use the REAL installed Chrome (channel:'chrome',
+ *  not Playwright's fingerprinted Chromium), strip the --enable-automation flag, and
+ *  disable the AutomationControlled blink feature. --disable-gpu = software compositing
+ *  (a launchd-context window otherwise paints black). Falls back to bundled chromium
+ *  (still de-flagged) if real Chrome isn't installed. */
+async function launchHeaded(): Promise<{ browser: Browser; appName: string }> {
+  const opts = {
+    headless: false,
+    ignoreDefaultArgs: ['--enable-automation'],
+    args: ['--disable-blink-features=AutomationControlled', '--disable-gpu'],
+  };
+  try {
+    // F240.10 — the macOS app NAME comes back with the browser. Playwright's
+    // Browser handle exposes no process, so the name is the only handle we have
+    // on the thing that has to come to the front — and it differs by channel.
+    return { browser: await chromium.launch({ ...opts, channel: 'chrome' }), appName: 'Google Chrome' };
+  } catch {
+    return { browser: await chromium.launch(opts), appName: 'Chromium' };
+  }
+}
+
+/** Best-effort Google sign-in fill so the human only does 2FA. Google's form is
+ *  multi-page (email → Next → password → Next → 2FA); each step is guarded so a
+ *  changed layout or an early bot-block never throws — the window stays open for
+ *  the human to finish/take over. Returns what actually happened. */
+async function fillGoogleLogin(
+  page: Page,
+  email: string,
+  password: string,
+): Promise<{ emailFilled: boolean; passwordFilled: boolean; url: string; note: string }> {
+  const out = { emailFilled: false, passwordFilled: false, url: page.url(), note: '' };
+  // The deep Play Console URL redirects to accounts.google.com; let the sign-in
+  // page actually land + settle before hunting for the field — otherwise the fill
+  // races the redirect and times out on a not-yet-rendered input.
+  await page.waitForURL(/accounts\.google\.com/, { timeout: 30_000 }).catch(() => {});
+  await page.waitForLoadState('networkidle', { timeout: 10_000 }).catch(() => {});
+  try {
+    const emailInput = page.locator('input[type="email"], input#identifierId').first();
+    await emailInput.waitFor({ state: 'visible', timeout: 30_000 });
+    await emailInput.fill(email);
+    out.emailFilled = true;
+    await page.locator('#identifierNext button, #identifierNext').first().click({ timeout: 5_000 }).catch(async () => {
+      await emailInput.press('Enter');
+    });
+  } catch (err) {
+    out.note = `email step: ${err instanceof Error ? err.message : String(err)}`;
+    out.url = page.url();
+    return out;
+  }
+  try {
+    const pwInput = page.locator('input[type="password"]');
+    await pwInput.waitFor({ state: 'visible', timeout: 15_000 });
+    await pwInput.fill(password);
+    out.passwordFilled = true;
+    await page.locator('#passwordNext button, #passwordNext').first().click({ timeout: 5_000 }).catch(async () => {
+      await pwInput.press('Enter');
+    });
+  } catch (err) {
+    out.note = `password step: ${err instanceof Error ? err.message : String(err)}`;
+  }
+  await page.waitForTimeout(1500);
+  out.url = page.url();
+  return out;
+}
+
+const sessions = new Map<string, Session>();
+
+// Auto-close an abandoned headed login so we never leak a visible browser window
+// on the host (the human closed the tab, forgot, walked away).
+const SESSION_TTL_MS = 15 * 60 * 1000;
+
+// Confine storageState writes to a known-local dir so a bad/hostile state_path
+// can't clobber an arbitrary file on the host. Both fleet-agreed paths for this
+// capability live under ~/.lens/state.
+const STATE_ROOT = resolve(homedir(), '.lens', 'state');
+
+/** Validate + normalise the storageState target path. Absolute-only, confined to
+ *  STATE_ROOT, and a `.json` file. Pure + exported so the confinement gate is
+ *  unit-sealed (the load-bearing security property — no arbitrary-file write). */
+export function validateStatePath(statePath: string): string {
+  if (typeof statePath !== 'string' || statePath.length === 0) {
+    throw new Error('state_path required');
+  }
+  if (!isAbsolute(statePath)) throw new Error('state_path must be an absolute path');
+  const abs = resolve(statePath);
+  if (abs !== STATE_ROOT && !abs.startsWith(STATE_ROOT + sep)) {
+    throw new Error(`state_path must be under ${STATE_ROOT}`);
+  }
+  if (!abs.endsWith('.json')) throw new Error('state_path must end in .json');
+  return abs;
+}
+
+/**
+ * F240.8 — how long `finish` may spend asking the browser for its storageState.
+ *
+ * storeform measured a `finish` that hung for OVER TWO MINUTES on a login-walled
+ * session (#20803). `context.storageState()` carries no timeout of its own, so
+ * the request simply never answered — and because the session had already been
+ * removed from the registry, `cancel` could not reach it either. A bound turns a
+ * hang into an error a caller can act on.
+ */
+const STORAGE_STATE_TIMEOUT_MS = 30_000;
+
+/**
+ * F240.8 — where the pre-overwrite copy of a state file goes.
+ *
+ * The suffix is appended to an ALREADY-validated path, so it cannot escape
+ * STATE_ROOT by construction — and it is re-checked anyway. "It cannot escape by
+ * construction" is an argument; this file holds a real Google session, and the
+ * confinement is the load-bearing security property of this whole module.
+ *
+ * Note it deliberately does NOT go back through validateStatePath: that function
+ * requires a `.json` suffix, which `.bak` is not. Reusing it wholesale would
+ * throw on every backup — the check that matters here is the ROOT confinement,
+ * not the extension.
+ */
+export function backupPathFor(statePath: string): string {
+  const abs = validateStatePath(statePath);
+  const bak = `${abs}.bak`;
+  if (!bak.startsWith(STATE_ROOT + sep)) {
+    throw new Error(`backup path escaped ${STATE_ROOT}: ${bak}`);
+  }
+  return bak;
+}
+
+/**
+ * F240.8 — copy the existing state aside BEFORE it is overwritten.
+ *
+ * WHY A BACKUP AND NOT A "does this look like a login wall?" HEURISTIC, which is
+ * the other option storeform offered: the two failure modes are not symmetric.
+ * A heuristic that guesses wrong in the SKIP direction throws away a good,
+ * freshly-captured session — the thing a human just did 2FA for, and the
+ * expensive thing to recreate. A backup that turns out to be unnecessary costs
+ * one file. So the mechanism must not be able to choose the expensive mistake.
+ *
+ * Returns nulls rather than throwing: losing the human's 2FA work because the
+ * SAFETY net failed would be the bug wearing a different hat.
+ */
+export function backupExistingState(statePath: string): { backupPath: string | null; backupError: string | null } {
+  // A first capture has nothing to preserve. Writing an empty .bak here would
+  // fabricate a recovery point that recovers nothing, which is worse than none:
+  // it answers "is there a backup?" with yes.
+  if (!existsSync(statePath)) return { backupPath: null, backupError: null };
+  try {
+    const bak = backupPathFor(statePath);
+    copyFileSync(statePath, bak);
+    return { backupPath: bak, backupError: null };
+  } catch (err) {
+    return { backupPath: null, backupError: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+/**
+ * F240.8 — bound a promise that has none of its own.
+ *
+ * The loser of the race keeps running; a handler is attached so its eventual
+ * rejection is not reported as unhandled. We cannot cancel Playwright's call,
+ * but closing the browser in the caller's `finally` makes it settle.
+ */
+export async function withTimeout<T>(p: Promise<T>, ms: number, what: string): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  p.catch(() => {});
+  try {
+    return await Promise.race([
+      p,
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`${what} timed out after ${ms}ms`)), ms);
+        timer.unref?.();
+      }),
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+/** F240.7 — validate a storageState path to LOAD into the browser so it opens
+ *  ALREADY logged in (skip the whole login, drive only the step-up 2FA). Same
+ *  confinement as the save path, but the file MUST already exist. */
+export function validateLoadStatePath(loadStatePath: string): string {
+  const abs = validateStatePath(loadStatePath);
+  if (!existsSync(abs)) throw new Error(`load_state_path does not exist: ${abs}`);
+  return abs;
+}
+
+/**
+ * F240.10 — bring the window forward, and be HONEST about whether we know it is
+ * on screen.
+ *
+ * storeform (#20803), while a human waited to do 2FA: *"start answers ok, the
+ * browser reports its URL — but whether there is a window he can click in, I
+ * cannot measure from here. I had to write to him that I could not prove it."*
+ * `ok` proves a process launched and a page navigated. It proves nothing about a
+ * human's screen.
+ *
+ * The same trap is already written into this fleet's own CLAUDE.md as the
+ * VINDUES-FÆLDE: `open -a` returns exit 0 even when the app opens NO window, and
+ * Read.md did exactly that while Christian was told his file was open.
+ *
+ * SO THE FIELD MUST BE ABLE TO SAY "I DON'T KNOW". `window_visible: true` where
+ * nothing was checked would be worse than today's silence, because it SOUNDS like
+ * proof. Three states, and the caller can tell them apart:
+ *
+ *   true   — every step we can take returned without error, and `window_check`
+ *            says which steps those were and what they do NOT prove
+ *   false  — a step failed, and `window_check` says which one and why
+ *   null   — no check exists on this platform. An absent verdict, never a pass.
+ */
+export interface WindowVerdict {
+  window_visible: boolean | null;
+  window_check: string;
+}
+
+/**
+ * macOS activation, by application name.
+ *
+ * Deliberately `tell application "<name>" to activate` rather than a System
+ * Events process poke: the latter needs Accessibility, which a daemon-launched
+ * process frequently does not have — storeform's probe came back empty for
+ * exactly that reason. This route asks the app itself (Automation permission),
+ * and `page.bringToFront()` has already raised OUR window within that app, so
+ * activating the app surfaces the right window rather than an unrelated one.
+ *
+ * A refusal is reported, never swallowed. That is the entire point of the card.
+ */
+async function activateOnDarwin(appName: string): Promise<void> {
+  // The name comes from launchHeaded's own two constants, never from a caller.
+  const proc = Bun.spawn(['osascript', '-e', `tell application "${appName}" to activate`], {
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+  const [code, err] = await Promise.all([proc.exited, new Response(proc.stderr).text()]);
+  if (code !== 0) throw new Error(err.trim().split('\n')[0] || `osascript exited ${code}`);
+}
+
+/**
+ * Raise the page's window and report what could actually be established.
+ *
+ * `bringToFront` moves the tab to the front WITHIN the browser app; it does not
+ * put the app above the terminal that launched it. Both steps are needed, and
+ * neither is allowed to fail `start`: the human may still be able to click the
+ * window, and losing a session over a focus call would be the expensive mistake.
+ */
+export async function surfaceWindow(opts: {
+  bringToFront: () => Promise<void>;
+  appName?: string;
+  platform?: NodeJS.Platform;
+  activate?: (appName: string) => Promise<void>;
+}): Promise<WindowVerdict> {
+  const platform = opts.platform ?? process.platform;
+  const steps: string[] = [];
+
+  try {
+    await opts.bringToFront();
+    steps.push('page.bringToFront()');
+  } catch (err) {
+    return {
+      window_visible: false,
+      window_check: `page.bringToFront() failed: ${msgOf(err)} — the window may exist but could not be raised`,
+    };
+  }
+
+  if (platform !== 'darwin') {
+    // Not a pass. There is no app-activation step here, so the honest answer is
+    // that nothing beyond the tab-level raise was established.
+    return {
+      window_visible: null,
+      window_check: `page.bringToFront() succeeded; no app-activation check exists on ${platform}`,
+    };
+  }
+  if (!opts.appName) {
+    return {
+      window_visible: null,
+      window_check: 'page.bringToFront() succeeded; the browser application name was unavailable, so the app could not be activated',
+    };
+  }
+
+  try {
+    await (opts.activate ?? activateOnDarwin)(opts.appName);
+    steps.push(`activate "${opts.appName}"`);
+  } catch (err) {
+    return {
+      window_visible: false,
+      window_check: `page.bringToFront() succeeded but activating the app failed: ${msgOf(err)} — commonly a missing Accessibility permission; the window may be behind another app`,
+    };
+  }
+
+  // Deliberately not the word "verified". Both calls returning without error is
+  // the strongest thing obtainable without photographing the display, and saying
+  // more than that here is how the field becomes a better-dressed version of the
+  // problem it was added to fix.
+  return {
+    window_visible: true,
+    window_check: `${steps.join(' + ')} both returned without error (not a pixel-level proof that the display shows it)`,
+  };
+}
+
+const msgOf = (err: unknown): string => (err instanceof Error ? err.message : String(err));
+
+/** Open a headed browser at `url` and hold it for an interactive login. If
+ *  `email`+`password` are supplied, best-effort auto-fills the Google sign-in so
+ *  the human only does 2FA. Returns a session_id the caller passes to finish/cancel. */
+export async function startCaptureSession(input: {
+  url: string;
+  statePath: string;
+  email?: string;
+  password?: string;
+  /** F240.7 — a storageState file to LOAD so the browser opens already logged in. */
+  loadStatePath?: string;
+}): Promise<{
+  sessionId: string;
+  url: string;
+  statePath: string;
+  loaded: boolean;
+  login?: { emailFilled: boolean; passwordFilled: boolean; url: string; note: string };
+  /** F240.10 — what could actually be established about the window being on
+   *  screen. `null` means no verdict, which is not a pass. */
+  windowVisible: boolean | null;
+  windowCheck: string;
+}> {
+  let parsed: URL;
+  try {
+    parsed = new URL(input.url);
+  } catch {
+    throw new Error(`invalid url: ${input.url}`);
+  }
+  if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+    throw new Error(`unsupported protocol: ${parsed.protocol} (only http/https)`);
+  }
+  const statePath = validateStatePath(input.statePath);
+  mkdirSync(dirname(statePath), { recursive: true });
+  const loadStatePath = input.loadStatePath ? validateLoadStatePath(input.loadStatePath) : undefined;
+
+  const { browser, appName } = await launchHeaded();
+  // Load an existing storageState so the browser opens ALREADY authenticated
+  // (skip the whole login; drive only the agreement + step-up 2FA). F240.7.
+  const context = await browser.newContext(loadStatePath ? { storageState: loadStatePath } : undefined);
+  // Mask the most-checked automation signal before any page script runs — pairs
+  // with the de-flagged launch so Google's "browser may not be secure" bot-check
+  // treats this like a real user's Chrome.
+  await context.addInitScript(() => {
+    Object.defineProperty(navigator, 'webdriver', { get: () => undefined });
+  });
+  const page = await context.newPage();
+  // Best-effort nav — a slow login portal shouldn't fail start; the human is
+  // driving from here and can navigate themselves if the first load stalls.
+  await page.goto(input.url, { waitUntil: 'domcontentloaded', timeout: 60_000 }).catch(() => {});
+
+  let login: { emailFilled: boolean; passwordFilled: boolean; url: string; note: string } | undefined;
+  if (input.email && input.password) {
+    login = await fillGoogleLogin(page, input.email, input.password);
+  }
+
+  // F240.10 — raise the window and report what we actually know. Never allowed to
+  // fail start: the human may still be able to click it, and losing the session
+  // over a focus call is the expensive mistake.
+  const verdict = await surfaceWindow({
+    bringToFront: () => page.bringToFront(),
+    appName,
+  }).catch((err) => ({
+    window_visible: null as boolean | null,
+    window_check: `the window check itself failed: ${msgOf(err)}`,
+  }));
+
+  const sessionId = randomUUID();
+  const timer = setTimeout(() => {
+    void cancelCaptureSession(sessionId).catch(() => {});
+  }, SESSION_TTL_MS);
+  timer.unref?.();
+  sessions.set(sessionId, { browser, context, page, url: input.url, statePath, startedAt: Date.now(), timer });
+  return {
+    sessionId,
+    url: input.url,
+    statePath,
+    loaded: Boolean(loadStatePath),
+    login,
+    windowVisible: verdict.window_visible,
+    windowCheck: verdict.window_check,
+  };
+}
+
+/**
+ * Dump the live context's storageState to the session's local file, close the
+ * browser, and return the path + counts (never the cookie bytes).
+ *
+ * F240.8 — THIS FUNCTION USED TO DESTROY THE STATE IT REPLACED, TWICE OVER.
+ *
+ * storeform hit both halves in one incident (#20798, #20803) with FD Sundhed due
+ * in both app stores. They called finish on a DEAD Play session and the
+ * logged-OUT storageState went straight over their good file. Their sentence is
+ * the one that matters: "The file was probably worthless already, but I can no
+ * longer PROVE it was." The harm is not the bad file — it is that the evidence
+ * went with it, collapsing "was it already dead?" and "did finish kill it?" into
+ * one unanswerable question.
+ *
+ * The second half is the same mistake one level up. `sessions.delete` ran BEFORE
+ * the risky await, so while finish hung for two minutes, `cancel` answered
+ * "unknown session_id (already finished, cancelled, or timed out)" — three states
+ * it could not tell apart, none of them the true one — and the TTL timer had
+ * already been cleared, so nothing would ever reclaim it. The browser was
+ * orphaned with no way back.
+ *
+ * Both are the same shape: THE FUNCTION REMOVED WHAT YOU WOULD NEED AFTERWARDS,
+ * BEFORE DOING THE THING THAT CAN FAIL. So: copy first, delete last, and bound
+ * the await.
+ */
+export async function finishCaptureSession(input: {
+  sessionId: string;
+  /** F240.8 — injectable so the ORDERING can be tested without launching Chrome. */
+  registry?: Map<string, FinishableSession>;
+  /** F240.8 — injectable so the TIMEOUT is proven on the real path, not only on
+   *  the helper. A suite that must sit for 30s to check a bound gets the bound
+   *  lowered until it is not really tested. */
+  timeoutMs?: number;
+}): Promise<{
+  ok: true;
+  path: string;
+  cookies: number;
+  origins: number;
+  backup_path: string | null;
+  backup_error?: string;
+}> {
+  const reg = input.registry ?? (sessions as unknown as Map<string, FinishableSession>);
+  const s = reg.get(input.sessionId);
+  if (!s) throw new Error('unknown session_id (already finished, cancelled, or timed out)');
+  clearTimeout(s.timer);
+  // Stays in the registry, MARKED. This is the line the incident turned on: a
+  // caller whose finish is hanging must be able to learn that from cancel.
+  s.finishing = true;
+  try {
+    // Before the overwrite, never after — a .bak written afterwards holds the new
+    // bytes, passes an existence check, and preserves nothing.
+    const { backupPath, backupError } = backupExistingState(s.statePath);
+    // storageState() WITHOUT `path`: we write the file ourselves, so a timeout
+    // cannot leave a half-written state, and on failure the existing file is
+    // untouched because nothing was opened for writing at all.
+    const state = await withTimeout(s.context.storageState(), input.timeoutMs ?? STORAGE_STATE_TIMEOUT_MS, 'storageState');
+    writeFileSync(s.statePath, JSON.stringify(state));
+    return {
+      ok: true,
+      path: s.statePath,
+      cookies: state.cookies.length,
+      origins: state.origins.length,
+      backup_path: backupPath,
+      // Reported, never thrown. Losing the human's 2FA work because the SAFETY
+      // net failed would be this same bug wearing a different hat.
+      ...(backupError ? { backup_error: backupError } : {}),
+    };
+  } finally {
+    reg.delete(input.sessionId);
+    await s.browser.close().catch(() => {});
+  }
+}
+
+/**
+ * Discard a session without saving (human aborted, or the TTL fired).
+ *
+ * F240.8 — `status` names WHICH of the three states it found, because the single
+ * "unknown session_id" string conflated them and named none correctly.
+ */
+export async function cancelCaptureSession(
+  sessionId: string,
+  registry?: Map<string, FinishableSession>,
+): Promise<{ ok: true; status: 'cancelled' | 'finish_in_progress' | 'unknown' }> {
+  const reg = registry ?? (sessions as unknown as Map<string, FinishableSession>);
+  const s = reg.get(sessionId);
+  if (!s) return { ok: true, status: 'unknown' };
+  // Do NOT close a browser that finish is mid-write on: that is how a hang
+  // becomes a corrupted save. Report it and let finish's own timeout end it.
+  if (s.finishing) return { ok: true, status: 'finish_in_progress' };
+  clearTimeout(s.timer);
+  reg.delete(sessionId);
+  await s.browser.close().catch(() => {});
+  return { ok: true, status: 'cancelled' };
+}
+
+/** Open sessions (for /status + the finish/cancel caller to see what's live). */
+export function listCaptureSessions(): Array<{ session_id: string; url: string; started_at: number }> {
+  return [...sessions.entries()].map(([id, s]) => ({ session_id: id, url: s.url, started_at: s.startedAt }));
+}
+
+// ── F240.7 — drive steps against the OPEN persistent capture-session page ────
+//
+// A consumer (storeform) opens a headed session (start), then drives the login +
+// 2FA by sending fill/click steps IN BATCHES against the ONE live page, pausing
+// between batches while a human reads the SMS code. runFlow can't do this (it
+// uses a fresh context per call → the 2FA challenge resets). Credential VALUES
+// (password/OTP) ride in step.value over localhost ONLY and are NEVER logged or
+// echoed — the result carries only type/selector/status/detail.
+
+/**
+ * F074.50 — the vocabulary as a runtime VALUE, with the type derived from it.
+ *
+ * It was a TypeScript union, which vanishes at runtime, so the rejection message
+ * could only name the caller's guess. Declaring the list here and deriving
+ * ExecStep['type'] from it means adding a verb is ONE edit and both the type and
+ * the error follow — a hand-written list inside the message would be correct the
+ * day it was typed and quietly wrong at the next verb.
+ *
+ * Deliberately NOT the same list as flow.ts's STEP_TYPES: this surface has
+ * `jsclick` and `eval` and has no `conditional`. Implying one vocabulary for both
+ * would replace a silence with a wrong answer.
+ */
+export const EXEC_STEP_TYPES = [
+  'fill', 'click', 'jsclick', 'waitFor', 'waitForText', 'press', 'goto', 'screenshot', 'eval',
+] as const;
+
+export interface ExecStep {
+  type: (typeof EXEC_STEP_TYPES)[number];
+  /** Target by ONE of: raw css `selector`, `role`(+`name`), or `text`. Apple's
+   *  sign-in + agreement modals have no stable css → role/text is essential. */
+  selector?: string;
+  role?: string;
+  name?: string;
+  text?: string;
+  /** Secret over localhost for `fill` — never logged, never returned. */
+  value?: string;
+  key?: string;
+  url?: string;
+  /** `eval` only — a JS body (may `return`) run in the page. */
+  js?: string;
+  timeout?: number;
+  /** F074.51 — the snake_case alias. Every other name on this wire is snake_case
+   *  (session_id, state_path, load_state_path), so this is the one a caller
+   *  reaches for; it was silently dropped until it was read here. Wins over
+   *  `timeout` when both are present. */
+  timeout_ms?: number;
+  /** click only — skip Playwright's actionability/interception checks. Needed
+   *  when a transparent overlay (e.g. ASC's agreement-modal fade layer) steals
+   *  pointer events from a button a human can click fine. */
+  force?: boolean;
+  /** F240.9 — `waitFor` only: wait this many milliseconds and resolve, with no
+   *  target at all. A human-paced 2FA login genuinely needs a plain time wait,
+   *  and there was no way to express one: storeform sent `{type:'waitFor',
+   *  ms:8000}`, the field was silently dropped, and the step then failed with
+   *  "waitFor needs a selector, role(+name), or text" — an error about a
+   *  different problem entirely. */
+  ms?: number;
+}
+
+/**
+ * F240.9 — the body of POST /lens/capture-session/exec, PARSED rather than cast.
+ *
+ * The route used to write `(await c.req.json()) as { steps?: ExecStep[] }`, and a
+ * cast is not a check: a key TypeScript has never heard of arrives, matches
+ * nothing, and disappears. storeform sent `{type:'waitFor', ms:8000}` and got back
+ * an error about a missing selector — a message describing a different problem,
+ * on a call whose real defect was a field that did nothing.
+ *
+ * THIS IS THE SECOND HALF OF A BUG WE THOUGHT WE HAD CLOSED. Two fields above
+ * `ms`, `timeout_ms` carries the F074.51 comment saying it "was silently dropped
+ * until it was read here" — the same reporter, the same type, the next field, a
+ * week later. Reading one more field closes an instance; refusing unknown fields
+ * closes the class.
+ *
+ * `.strict()` on both levels, so an unknown key is a named 400 instead of silence.
+ */
+export const EXEC_STEP_SCHEMA = z
+  .object({
+    type: z.enum(EXEC_STEP_TYPES),
+    selector: z.string().optional(),
+    role: z.string().optional(),
+    name: z.string().optional(),
+    text: z.string().optional(),
+    value: z.string().optional(),
+    key: z.string().optional(),
+    url: z.string().optional(),
+    js: z.string().optional(),
+    timeout: z.number().optional(),
+    timeout_ms: z.number().optional(),
+    force: z.boolean().optional(),
+    ms: z.number().int().nonnegative().optional(),
+  })
+  .strict();
+
+export const EXEC_BODY_SCHEMA = z
+  .object({
+    session_id: z.string().min(1),
+    steps: z.array(EXEC_STEP_SCHEMA).min(1),
+  })
+  .strict();
+
+/** The fields a step may carry, DERIVED from the schema — so the help text in an
+ *  error cannot drift from what is actually accepted. A hand-written list would
+ *  be right the day it was typed and quietly wrong at the next field. */
+export const EXEC_STEP_FIELDS = Object.keys(EXEC_STEP_SCHEMA.shape);
+
+export type ExecBody = z.infer<typeof EXEC_BODY_SCHEMA>;
+
+/**
+ * Parse an /exec body and, on failure, say something a caller can act on ALONE.
+ *
+ * Zod's own text ("Unrecognized key(s) in object: 'ms'") names the key but not
+ * WHICH step, and a batch is usually a dozen steps long. So the message is built
+ * here: the step index, its type, the offending key, and the fields that ARE
+ * accepted — the last one derived from the schema, never hand-listed.
+ *
+ * The two pre-existing messages are preserved verbatim ('session_id required',
+ * 'steps[] required'): this card tightens what is REJECTED, and quietly renaming
+ * the errors a caller already matches on would be a second, unannounced change.
+ */
+export function parseExecBody(raw: unknown): { ok: true; value: ExecBody } | { ok: false; error: string } {
+  const r = EXEC_BODY_SCHEMA.safeParse(raw);
+  if (r.success) {
+    const bad = r.data.steps.findIndex((s) => s.ms !== undefined && (s.type !== 'waitFor' || targetLabel(s) !== undefined));
+    if (bad >= 0) {
+      const s = r.data.steps[bad]!;
+      return {
+        ok: false,
+        error:
+          s.type !== 'waitFor'
+            ? `step ${bad}: "ms" is only valid on waitFor, not on "${s.type}"`
+            : // Two different waits in one step is a caller mistake, and choosing
+              // one for them silently is exactly how timeout vs timeout_ms became
+              // a bug. Refuse, and name both halves.
+              `step ${bad} (waitFor): "ms" and a target (${targetLabel(s)}) are two different waits — pass one`,
+      };
+    }
+    return { ok: true, value: r.data };
+  }
+
+  for (const issue of r.error.issues) {
+    const [head, index] = issue.path;
+    if (head === 'session_id') return { ok: false, error: 'session_id required' };
+    if (head === 'steps' && issue.path.length === 1) return { ok: false, error: 'steps[] required' };
+    if (issue.code === 'unrecognized_keys') {
+      const where = typeof index === 'number' ? `step ${index}` : 'the request body';
+      const keys = issue.keys.map((k) => `"${k}"`).join(', ');
+      return {
+        ok: false,
+        error:
+          typeof index === 'number'
+            ? `${where}: unknown field ${keys} — accepted: ${EXEC_STEP_FIELDS.join(', ')}`
+            : `${where}: unknown field ${keys}`,
+      };
+    }
+  }
+  const first = r.error.issues[0];
+  const at = first?.path.length ? ` at ${first.path.join('.')}` : '';
+  return { ok: false, error: `invalid exec body${at}: ${first?.message ?? 'unknown error'}` };
+}
+
+export interface ExecStepResult {
+  type: string;
+  target?: string;
+  status: 'pass' | 'fail';
+  detail?: string;
+  /** Set on a `screenshot` step — a daemon artifact URL the caller can fetch. */
+  screenshot_url?: string;
+}
+
+/** The narrow slice of a Playwright Page the runner uses — so runExecSteps is
+ *  unit-testable with a fake page (and the credential-safety property sealed). */
+export interface StepLocator {
+  first(): {
+    fill(value: string, opts?: { timeout?: number }): Promise<void>;
+    click(opts?: { timeout?: number; force?: boolean }): Promise<void>;
+    waitFor(opts?: { state?: 'visible'; timeout?: number }): Promise<void>;
+    press(key: string, opts?: { timeout?: number }): Promise<void>;
+    focus(opts?: { timeout?: number }): Promise<void>;
+    /** Run a fn against the matched element IN the page — used by `jsclick` to
+     *  invoke the element's own click handler directly (no pointer hit-testing,
+     *  so a transparent overlay can't intercept it), and by F213.7's fill
+     *  read-back, which needs the RETURN value. Hence the generic. */
+    evaluate<R>(pageFunction: (el: HTMLElement) => R, arg?: unknown, opts?: { timeout?: number }): Promise<R>;
+  };
+}
+export interface StepPage {
+  locator(selector: string): StepLocator;
+  getByRole(role: string, opts?: { name?: string }): StepLocator;
+  getByText(text: string): StepLocator;
+  goto(url: string, opts?: { timeout?: number }): Promise<unknown>;
+  keyboard: { press(key: string): Promise<void> };
+  screenshot(opts?: { fullPage?: boolean }): Promise<Buffer>;
+  /** Run code IN the page (used by the `eval` step) — e.g. neutralise a
+   *  pointer-events-stealing overlay so a real trusted click can land. */
+  evaluate(pageFunction: (code: string) => unknown, arg: string): Promise<unknown>;
+  url(): string;
+}
+
+/** Persist a screenshot buffer + return a fetchable URL. Injected by the route
+ *  (which owns the daemon storage + port) so this module stays decoupled. */
+export type SaveShot = (buffer: Buffer, index: number) => Promise<string>;
+
+const DEFAULT_STEP_TIMEOUT_MS = 15_000;
+
+/** F240.9 — a plain wait. Not page.waitForTimeout, because that needs a live
+ *  Playwright page and this step deliberately has no target; keeping it here also
+ *  keeps the runner unit-testable with the fake page the other steps use. */
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+/** A short, credential-free label of what a step targeted, for the result. */
+function targetLabel(step: ExecStep): string | undefined {
+  if (step.selector) return step.selector;
+  if (step.role) return `role=${step.role}${step.name ? ` name=${JSON.stringify(step.name)}` : ''}`;
+  if (step.text) return `text=${JSON.stringify(step.text)}`;
+  return undefined;
+}
+
+/** Resolve a step's target by ONE of css selector / role(+name) / visible text. */
+function resolveStepLocator(page: StepPage, step: ExecStep): StepLocator {
+  if (step.selector) return page.locator(step.selector);
+  if (step.role) return page.getByRole(step.role, step.name !== undefined ? { name: step.name } : undefined);
+  if (step.text) return page.getByText(step.text);
+  throw new Error(`${step.type} needs a selector, role(+name), or text`);
+}
+
+/** Run steps in order against a live page. Stops on the first failure (so the
+ *  caller can adjust + retry). NEVER puts step.value in a result — the caller's
+ *  password/OTP must not surface in the payload or any log. Playwright errors
+ *  reference the selector + state, not the fill value. `saveShot` persists a
+ *  `screenshot` step's PNG and yields its URL. */
+export async function runExecSteps(
+  page: StepPage,
+  steps: ExecStep[],
+  saveShot?: SaveShot,
+): Promise<ExecStepResult[]> {
+  const results: ExecStepResult[] = [];
+  let index = 0;
+  for (const step of steps) {
+    const i = index++;
+    const base: ExecStepResult = { type: step.type, target: targetLabel(step), status: 'pass' };
+    try {
+      const t = step.timeout_ms ?? step.timeout ?? DEFAULT_STEP_TIMEOUT_MS;
+      switch (step.type) {
+        case 'fill':
+          // F213.7 — same read-back as the flow engine. The two must not disagree
+          // about whether a write happened.
+          await fillAndVerify(resolveStepLocator(page, step).first(), step.value ?? '', t);
+          break;
+        case 'click':
+          await resolveStepLocator(page, step).first().click({ timeout: t, force: step.force });
+          break;
+        case 'jsclick':
+          // Invoke the element's click handler DIRECTLY in the DOM. A real mouse
+          // click (even force:true) still lands on the top element at the
+          // coordinate — a transparent overlay (ASC's agreement-modal fade layer)
+          // eats it. el.click() bypasses hit-testing entirely.
+          await resolveStepLocator(page, step).first().evaluate((el) => el.click());
+          break;
+        case 'waitFor':
+          // F240.9 — a plain time wait, with no target. The 2FA case is real: a
+          // human is reading an SMS and there is nothing on the page to wait FOR
+          // yet. `ms` and a target together are refused at parse time rather than
+          // resolved by a silent precedence rule.
+          if (step.ms !== undefined) {
+            await sleep(step.ms);
+            break;
+          }
+          await resolveStepLocator(page, step).first().waitFor({ state: 'visible', timeout: t });
+          break;
+        case 'waitForText':
+          if (!step.text) throw new Error('waitForText needs text');
+          await page.getByText(step.text).first().waitFor({ state: 'visible', timeout: t });
+          break;
+        case 'press':
+          if (step.selector || step.role || step.text) {
+            await resolveStepLocator(page, step).first().press(step.key ?? 'Enter', { timeout: t });
+          } else {
+            await page.keyboard.press(step.key ?? 'Enter');
+          }
+          break;
+        case 'goto':
+          if (!step.url) throw new Error('goto needs a url');
+          await page.goto(step.url, { timeout: t });
+          break;
+        case 'screenshot': {
+          const buf = await page.screenshot({ fullPage: false });
+          if (saveShot) base.screenshot_url = await saveShot(buf, i);
+          break;
+        }
+        case 'eval': {
+          // Run arbitrary JS IN the page (Chromium sandbox, NOT the daemon) — the
+          // general escape hatch: neutralise an overlay, read live DOM, etc. The
+          // caller's `return`-style body runs via new Function so `return x` works.
+          // Loopback-only + caller already owns this authed session.
+          if (!step.js) throw new Error('eval needs a js string');
+          const result = await page.evaluate((code) => {
+            // eslint-disable-next-line @typescript-eslint/no-implied-eval, no-new-func
+            const out = new Function(code)();
+            return out === undefined ? null : out;
+          }, step.js);
+          const asText = typeof result === 'string' ? result : JSON.stringify(result);
+          base.detail = asText === undefined ? undefined : asText.slice(0, 1000);
+          break;
+        }
+        default:
+          throw new Error(
+            `unknown step type: ${JSON.stringify((step as ExecStep).type)} — known: ${EXEC_STEP_TYPES.join(', ')}`,
+          );
+      }
+      results.push(base);
+    } catch (err) {
+      results.push({ ...base, status: 'fail', detail: err instanceof Error ? err.message : String(err) });
+      break; // stop the batch on the first failing step
+    }
+  }
+  return results;
+}
+
+/** Drive a batch of steps against an open capture-session's live page. Resets the
+ *  session TTL so a human-paced OTP pause between batches never auto-cancels the
+ *  browser. Returns per-step pass/fail + the current url (never a credential). */
+export async function execCaptureSession(input: {
+  sessionId: string;
+  steps: ExecStep[];
+  saveShot?: SaveShot;
+}): Promise<{ ok: true; url: string; steps: ExecStepResult[] }> {
+  const s = sessions.get(input.sessionId);
+  if (!s) throw new Error('unknown session_id (already finished, cancelled, or timed out)');
+  // Reset the abandon-TTL: an active driven login must not be killed mid-flow
+  // while the human is reading the SMS code.
+  clearTimeout(s.timer);
+  s.timer = setTimeout(() => {
+    void cancelCaptureSession(input.sessionId).catch(() => {});
+  }, SESSION_TTL_MS);
+  s.timer.unref?.();
+  const steps = await runExecSteps(s.page as unknown as StepPage, input.steps, input.saveShot);
+  return { ok: true, url: s.page.url(), steps };
+}