@broberg/lens-daemon 0.1.36 → 0.1.38

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@broberg/lens-daemon",
-  "version": "0.1.36",
+  "version": "0.1.38",
   "description": "The Lens module of the cardmem daemon (flows, critic, coverage, capture sessions, the /lens/* routes and the cardmem-lens MCP) as a package. The daemon mounts createLensRouter(deps) + createLensMcpRouter(deps). Bun runtime.",
   "type": "module",
   "license": "MIT",
@@ -15,8 +15,8 @@
     "sharp": "^0.35.5",
     "turndown": "^7.2.4",
     "zod": "^3.23.8",
-    "@broberg/lens-engine": "0.14.1",
-    "@broberg/lens-svg": "0.1.1"
+    "@broberg/lens-svg": "0.1.1",
+    "@broberg/lens-engine": "0.14.1"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.10.6",

package/src/browser.ts

@@ -11,6 +11,7 @@
 // context + page are always closed in a finally, even on capture error.
 
 import { bindProfileChannel, claimProfile, killOwnBrowsersOn, profileDir, type ProfileChannel } from './profiles.ts';
+import { launchWithRepair, type BrowserRepair } from './ensure-chromium.ts';
 import {
   chromium,
   webkit,
@@ -80,7 +81,15 @@ const CHROMIUM_ARGS = [
 
 async function launch(engine: LensEngine): Promise<Browser> {
   const args = engine === 'chromium' ? CHROMIUM_ARGS : [];
-  return ENGINES[engine].launch({ headless: true, args });
+  // F010.1 — a deleted browser is installed and the launch retried, not a fleet-wide outage.
+  return launchWithRepair(engine, () => ENGINES[engine].launch({ headless: true, args }), (r) => lastRepairs.push(r));
+}
+
+/** F010.1 — repairs made since the last read; a run reads (and clears) them into
+ *  its report. Read-and-clear, so one repair is reported once. */
+const lastRepairs: BrowserRepair[] = [];
+export function takeBrowserRepairs(): BrowserRepair[] {
+  return lastRepairs.splice(0, lastRepairs.length);
 }
 
 /** Get the warm browser for an engine, launching it on first use. Re-launches
@@ -353,7 +362,7 @@ async function launchWithExtension(
     if (profile) bindProfileChannel(profile, EXTENSION_CHANNEL);
     userDataDir = profile ? profileDir(profile) : await mkdtemp(join(tmpdir(), 'lens-ext-'));
     try {
-      context = await chromium.launchPersistentContext(userDataDir, {
+      context = await launchWithRepair('chromium', () => chromium.launchPersistentContext(userDataDir, {
         ...contextOptions(opts),
         headless: true,
         channel: EXTENSION_CHANNEL,
@@ -364,7 +373,7 @@ async function launchWithExtension(
           '--disable-dev-shm-usage',
           '--no-sandbox',
         ],
-      });
+      }), (r) => lastRepairs.push(r));
     } catch (err) {
       lastLaunchError = err instanceof Error ? err.message.split('\n')[0]! : String(err);
       if (!profile) await rm(userDataDir, { recursive: true, force: true }).catch(() => {});

package/src/ensure-chromium.ts

@@ -14,7 +14,7 @@ import { spawn } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
-import { chromium } from 'playwright';
+import { chromium, firefox, webkit } from 'playwright';
 
 export interface ChromiumExpectation {
   installed: boolean;
@@ -116,3 +116,115 @@ export function ensureChromium(): Promise<{
 
   return inFlight;
 }
+
+// ── F010.1 — repair at the moment of need, for every engine ────────────────────
+//
+// ensureChromium() runs once at daemon boot and installs the FULL Chromium only.
+// On 25 Oct the browsers were deleted while the daemon was running, and the warm
+// headless launch uses chromium-headless-shell, which boot never checked: every
+// run fleet-wide failed until a hand reinstalled. Now a launch that fails because
+// its binary is missing installs that engine's browsers (from the daemon's own
+// pinned Playwright, same as boot) and is retried once.
+
+export type BrowserEngine = 'chromium' | 'webkit' | 'firefox';
+
+/** What `playwright install` must fetch for an engine to launch in every mode Lens uses. */
+const INSTALL_NAMES: Record<BrowserEngine, string[]> = {
+  chromium: ['chromium', 'chromium-headless-shell', 'ffmpeg'],
+  webkit: ['webkit'],
+  firefox: ['firefox'],
+};
+
+export function isMissingBrowserError(err: unknown): boolean {
+  return /Executable doesn't exist/.test(err instanceof Error ? err.message : String(err));
+}
+
+type Installer = (names: string[]) => Promise<{ ok: boolean; error?: string }>;
+
+const spawnInstaller: Installer = (names) =>
+  new Promise((resolve) => {
+    let cliPath: string;
+    try {
+      cliPath = resolvePlaywrightCli();
+    } catch (err) {
+      resolve({ ok: false, error: `cannot resolve playwright CLI: ${err instanceof Error ? err.message : String(err)}` });
+      return;
+    }
+    console.log(`[lens] browser missing — installing ${names.join(', ')} via ${cliPath} …`);
+    const child = spawn(process.execPath, [cliPath, 'install', ...names], { stdio: 'inherit', env: process.env });
+    child.on('error', (err) => resolve({ ok: false, error: err.message }));
+    child.on('exit', (code) => resolve(code === 0 ? { ok: true } : { ok: false, error: `playwright install exited ${code}` }));
+  });
+
+let installer: Installer = spawnInstaller;
+/** Test seam: replace the installer (null restores the real one). */
+export function setBrowserInstaller(fn: Installer | null): void {
+  installer = fn ?? spawnInstaller;
+}
+
+// One install per engine at a time: two runs that hit the gap together share it.
+const engineInFlight = new Map<BrowserEngine, Promise<{ ok: boolean; error?: string }>>();
+
+export function installBrowsers(engine: BrowserEngine): Promise<{ ok: boolean; error?: string }> {
+  let p = engineInFlight.get(engine);
+  if (!p) {
+    p = installer(INSTALL_NAMES[engine]).finally(() => engineInFlight.delete(engine));
+    engineInFlight.set(engine, p);
+  }
+  return p;
+}
+
+export interface BrowserRepair {
+  engine: BrowserEngine;
+  ms: number;
+}
+
+/** Run a launch; if it fails ONLY because the browser binary is missing, install
+ *  that engine's browsers and retry once. Any other error propagates untouched. */
+export async function launchWithRepair<T>(
+  engine: BrowserEngine,
+  launch: () => Promise<T>,
+  onRepaired?: (r: BrowserRepair) => void,
+): Promise<T> {
+  try {
+    return await launch();
+  } catch (err) {
+    if (!isMissingBrowserError(err)) throw err;
+    const t0 = Date.now();
+    const inst = await installBrowsers(engine);
+    if (!inst.ok) {
+      throw new Error(`${engine} browser is missing and could not be installed: ${inst.error ?? 'unknown'} — original: ${(err as Error).message.split('\n')[0]}`);
+    }
+    const out = await launch();
+    onRepaired?.({ engine, ms: Date.now() - t0 });
+    return out;
+  }
+}
+
+/** For /health: does each engine's browser binary exist where this daemon looks?
+ *  chromium is reported for both the full build and the headless shell, because
+ *  the warm headless launch needs the shell (the 25 Oct gap boot never checked). */
+export function browsersPresent(): Record<string, boolean> {
+  const has = (f: () => string) => {
+    try {
+      return existsSync(f());
+    } catch {
+      return false;
+    }
+  };
+  const full = (() => {
+    try {
+      return chromium.executablePath();
+    } catch {
+      return '';
+    }
+  })();
+  const m = /^(.*[\\/])chromium-(\d+)[\\/]/.exec(full);
+  const shellDir = m ? join(m[1]!, `chromium_headless_shell-${m[2]}`) : '';
+  return {
+    chromium: has(() => full),
+    'chromium-headless-shell': shellDir ? existsSync(shellDir) : false,
+    webkit: has(() => webkit.executablePath()),
+    firefox: has(() => firefox.executablePath()),
+  };
+}

package/src/flow.ts

@@ -23,7 +23,7 @@ import {
   type AssertOutcome,
   type Target,
 } from '@broberg/lens-engine';
-import { withPage, type LensEngine, type RunBrowser } from './browser.ts';
+import { takeBrowserRepairs, withPage, type LensEngine, type RunBrowser } from './browser.ts';
 import { collectNetworkShapes, type NetworkShapesOptions, type NetworkShapesReport } from './network-shapes.ts';
 import { deadline, defaultPopupOf, prepareExtension, seedExtensionStorage, SIMULATED_ACCESS_NOTE } from './extension-flow.ts';
 import { authPrepare, fetchMintJson, persistStorageState, persistTarget, type AuthConfig, type AuthEnv } from './auth/index.ts';
@@ -34,6 +34,7 @@ import { fillAndVerify } from './fill.ts';
 import { fillSecret } from './secret-fill.ts';
 import { storagePayload, type StorageSeed } from './seed-storage.ts';
 import { passwordInUrl, type FilledPassword, type PasswordInUrlFinding } from './password-in-url.ts';
+import { assertTestMailbox, cleanupMail, fillFromMail, httpMailSource, type MailFrom, type MailSource } from './mail-fill.ts';
 import {
   EDIT_EVENTS,
   waitForListening,
@@ -50,7 +51,9 @@ export type ActivateMode = 'auto' | 'click' | 'enter';
 /** F009.121 — where a `fill` reads a SECRET from instead of carrying it inline:
  *  a gitignored file (absolute, or relative to the run's local_path) or a daemon
  *  env var. The value is read at run time and never echoed. */
-export type ValueFrom = { path: string } | { env: string };
+export type SecretFrom = { path: string } | { env: string };
+/** F009.137 — or a code that arrives by mail (the test mailbox only). */
+export type ValueFrom = SecretFrom | { mail: MailFrom };
 
 /** F009.123 — a drag by an offset, in css pixels from the source's centre. */
 export type DragOffset = { x: number; y: number };
@@ -421,6 +424,11 @@ export interface FlowResult {
   /** F009.131 — set when auth.persist was asked for: whether the renewed login was
    *  written back to statePath, and why not when it was not. Never a value. */
   auth_persisted?: { ok: boolean; reason?: string };
+  /** F010.1 — browsers the daemon reinstalled because their binary was missing. */
+  browser_repaired?: Array<{ engine: string; ms: number }>;
+  /** F009.137 — mails this run consumed for a code, and how many were removed
+   *  after. Present only when a step read mail. Never a code or a body. */
+  mail?: { consumed: number; cleaned: number; reason?: string };
   /** F009.125 — the extension this run loaded: its id (read at load time), the
    *  build path the caller named, and whether host access was SIMULATED on a copy. */
   extension?: {
@@ -855,8 +863,21 @@ function validateAndNormalizeSteps(steps: unknown[], depth = 0, inParallel = fal
       const hasValue = typeof (s as { value?: unknown }).value === 'string';
       const vf = (s as { valueFrom?: unknown }).valueFrom;
       if (hasValue && vf !== undefined) throw new Error('fill step takes value OR valueFrom, not both');
-      if (!hasValue && vf === undefined) throw new Error('fill step requires a string value or valueFrom {path} | {env}');
-      if (vf !== undefined) {
+      if (!hasValue && vf === undefined) throw new Error('fill step requires a string value or valueFrom {path} | {env} | {mail}');
+      // F009.137 — a code from mail: only the test mailbox, checked here at parse time.
+      if (vf && typeof vf === 'object' && 'mail' in (vf as object)) {
+        const m = (vf as { mail?: unknown }).mail as Record<string, unknown> | null;
+        if (!m || typeof m !== 'object' || typeof m.to !== 'string' || Object.keys(m).some((k) => !['to', 'subject', 'match', 'timeout'].includes(k))) {
+          throw new Error('fill valueFrom.mail must be {to: "<address>", subject?, match?, timeout?}');
+        }
+        assertTestMailbox(m.to);
+        if (m.match !== undefined) {
+          try { new RegExp(String(m.match)); } catch { throw new Error(`fill from mail: match /${String(m.match)}/ is not a valid regex`); }
+        }
+        if (m.timeout !== undefined && !(typeof m.timeout === 'number' && m.timeout > 0 && m.timeout <= 300_000)) {
+          throw new Error('fill from mail: timeout must be 1..300000 ms');
+        }
+      } else if (vf !== undefined) {
         const keys = vf && typeof vf === 'object' && !Array.isArray(vf) ? Object.keys(vf) : [];
         const k = keys[0];
         if (keys.length !== 1 || (k !== 'path' && k !== 'env') || typeof (vf as Record<string, unknown>)[k] !== 'string' || !(vf as Record<string, string>)[k]) {
@@ -1242,6 +1263,18 @@ function parseManuscriptStep(s: string): FlowStep {
     case 'fill': {
       // F009.121 — "fill [pw] from file <path>" / "from env <NAME>": the secret
       // is read at run time, so the manuscript (and its label) never holds it.
+      // F009.137 — "fill [code] from mail to <addr> [subject ~ <text>] [match /<re>/]".
+      const mail = s.match(/\]\s+from\s+mail\s+to\s+(\S+)(.*)$/i);
+      if (mail) {
+        const rest = mail[2]!;
+        const re = rest.match(/\bmatch\s+\/(.+)\/\s*$/i);
+        const subj = rest.replace(/\bmatch\s+\/.+\/\s*$/i, '').match(/\bsubject\s*~\s*(.+?)\s*$/i);
+        return {
+          type: 'fill',
+          testid: testid(),
+          valueFrom: { mail: { to: mail[1]!, ...(subj ? { subject: subj[1]!.trim() } : {}), ...(re ? { match: re[1]! } : {}) } },
+        };
+      }
       const from = s.match(/\]\s+from\s+(file|env)\s+(\S.*)$/i);
       if (from) {
         const src = from[2]!.trim();
@@ -2043,7 +2076,7 @@ async function sampleMotion(
 const MOTION_SAMPLE_MS = 250;
 
 
-async function execStep(page: Page, step: FlowStep, base: string, vars: Record<string, unknown>, critic: CriticMode, localPath?: string, sink?: CriticSink, pwSink?: FilledPassword[], readySink?: NotListeningFinding[], secretRoot?: string): Promise<Buffer | null | { __inspect: string } | { __via: string; __build?: string; __redirect?: string }> {
+async function execStep(page: Page, step: FlowStep, base: string, vars: Record<string, unknown>, critic: CriticMode, localPath?: string, sink?: CriticSink, pwSink?: FilledPassword[], readySink?: NotListeningFinding[], secretRoot?: string, mailCtx?: { source: MailSource; consumed: Array<{ to: string; id: string }> }): Promise<Buffer | null | { __inspect: string } | { __via: string; __build?: string; __redirect?: string }> {
   switch (step.type) {
     case 'goto': {
       const p = subst(step.path, vars);
@@ -2076,11 +2109,17 @@ async function execStep(page: Page, step: FlowStep, base: string, vars: Record<s
       return via ? { __via: via } : null;
     }
     case 'fill': {
+      const stepStart = Date.now(); // F009.137 — only mail received after this counts
       const { loc, via, remaining } = await locate(page, step);
       await consultReadiness(page, loc, step, readySink);
       // F213.7 — fill proves its own write; a silent no-op or a prepended value
       // used to pass as success, which is the half of the fleet save-rule this
       // instrument could not perform.
+      if (step.valueFrom && 'mail' in step.valueFrom) {
+        if (!mailCtx) throw new Error('fill from mail: this run has no mail source');
+        await fillFromMail(loc, step.valueFrom.mail, stepStart, mailCtx.source, mailCtx.consumed, remaining);
+        return via ? { __via: via } : null;
+      }
       if (step.valueFrom) {
         await fillSecret(loc, step.valueFrom, secretRoot, remaining, pwSink, anchorOf(step));
         return via ? { __via: via } : null;
@@ -2621,6 +2660,9 @@ export interface RunFlowOptions {
    *  page the caller named, so an unsandboxed root would let a flow post any file
    *  the daemon can read to any URL. */
   secretRoot?: string;
+  /** F009.137 — where `fill … from mail` reads; defaults to mail-mcp over HTTP
+   *  (LENS_MAIL_API/LENS_MAIL_KEY). Injected by tests. */
+  mailSource?: MailSource;
   /** F255.5 — record the whole driven run to a .webm, returned as FlowResult.video.
    *  Off by default: recording costs disk + a little time on every run, and most flows
    *  only need the per-step stills. */
@@ -2954,7 +2996,7 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
             ? await openPopup(step)
             : step.type === 'expectRequest'
             ? await expectRequest(step, vars)
-            : await execStep(sp, step, base, vars, opts.critic ?? 'off', opts.localPath, sink, filledPasswords, notListening, opts.secretRoot);
+            : await execStep(sp, step, base, vars, opts.critic ?? 'off', opts.localPath, sink, filledPasswords, notListening, opts.secretRoot, mailCtx);
         const obj = out !== null && !Buffer.isBuffer(out) && typeof out === 'object' ? out : null;
         const inspect = obj && '__inspect' in obj ? (obj as { __inspect: string }).__inspect : null;
         const via = obj && '__via' in obj ? (obj as { __via: string }).__via : null;
@@ -3127,6 +3169,12 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
   const shapesRef: { c: ReturnType<typeof collectNetworkShapes> | null } = { c: null };
   let networkShapesReport: NetworkShapesReport | undefined;
   const persistPath = persistTarget(flow.auth);
+  // F009.137 — every mail a step consumes is removed when the run ends, pass or fail.
+  const mailCtx = { source: opts.mailSource ?? httpMailSource(), consumed: [] as Array<{ to: string; id: string }> };
+  let mailReport: FlowResult['mail'];
+  const finishMail = async () => {
+    if (mailCtx.consumed.length && !mailReport) mailReport = await cleanupMail(mailCtx.consumed, mailCtx.source);
+  };
   let authPersisted: FlowResult['auth_persisted'] = persistPath ? { ok: false, reason: 'the run ended before the login could be saved' } : undefined;
   const pendingDownloads: Promise<void>[] = [];
   let currentStep: number | null = null;
@@ -3405,9 +3453,11 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
     // F009.133 — what was collected before the crash is still in memory; say it.
     if (shapesRef.c && !networkShapesReport) networkShapesReport = await shapesRef.c.finish();
     await prepared?.cleanup();
-    return { downloads, ...(networkShapesReport ? { network_shapes: networkShapesReport } : {}), ...(authPersisted ? { auth_persisted: authPersisted } : {}), ...(extensionInfo ? { extension: extensionInfo } : {}), name: flow.name, status: 'error', steps: results.sort((a, b) => a.index - b.index), failed_at: firstFailedAt, reason: leadWithRedirect(reason, firstRedirect), duration_ms: Date.now() - startedAt, video, build: observedBuild, final_url: finalUrl, redirected: firstRedirect, password_in_url: passwordInUrl(finalUrl, filledPasswords), not_listening: notListening[0] ?? null, reduced_motion: opts.reducedMotion ?? 'reduce' };
+    await finishMail();
+    return { downloads, ...(mailReport ? { mail: mailReport } : {}), ...(networkShapesReport ? { network_shapes: networkShapesReport } : {}), ...(authPersisted ? { auth_persisted: authPersisted } : {}), ...(extensionInfo ? { extension: extensionInfo } : {}), name: flow.name, status: 'error', steps: results.sort((a, b) => a.index - b.index), failed_at: firstFailedAt, reason: leadWithRedirect(reason, firstRedirect), duration_ms: Date.now() - startedAt, video, build: observedBuild, final_url: finalUrl, redirected: firstRedirect, password_in_url: passwordInUrl(finalUrl, filledPasswords), not_listening: notListening[0] ?? null, reduced_motion: opts.reducedMotion ?? 'reduce' };
   }
 
+  await finishMail(); // F009.137 — consumed mail is removed, pass or fail
   const video = await readVideo();
   // F009.125 — the temporary copy (if any) is ours alone; the original is never touched.
   await prepared?.cleanup();
@@ -3459,6 +3509,9 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
     // context can never disagree about it.
     reduced_motion: opts.reducedMotion ?? 'reduce',
     ...(authPersisted ? { auth_persisted: authPersisted } : {}),
+    ...(mailReport ? { mail: mailReport } : {}),
+    // F010.1 — a missing browser this run had to reinstall, said out loud.
+    ...((() => { const r = takeBrowserRepairs(); return r.length ? { browser_repaired: r } : {}; })()),
     ...(extensionInfo ? { extension: extensionInfo } : {}),
     ...(networkShapesReport ? { network_shapes: networkShapesReport } : {}),
     downloads,

package/src/http.ts

@@ -5,6 +5,7 @@
 // all hit these. Artifact bytes are served here too, so an <img> in the
 // dashboard points straight at the daemon.
 
+import { browsersPresent } from './ensure-chromium.ts';
 import { Hono } from 'hono';
 import { setSandboxResolver } from './sandbox.ts';
 import { registerDaemonRoutes } from './daemon-routes.ts';
@@ -79,6 +80,8 @@ export function createLensRouter(deps: LensDeps): Hono {
 
   // F276.1/F276.4 — the upload queue: what it holds, and one drain pass.
   r.get('/uploads', (c) => c.json({ ok: true, ...uploadStats(deps.db) }));
+  // F010.1 — does each engine's browser binary exist where this daemon looks?
+  r.get('/browsers', (c) => c.json({ ok: true, browsers: browsersPresent() }));
   r.post('/uploads/drain', handle(async (body) => {
     const b = (body ?? {}) as { batch?: number };
     return drainUploads(deps.db, deps.storage, deps.cloud?.() ?? null, { batch: b.batch });

package/src/index.ts

@@ -16,7 +16,7 @@ export { durabilityOf, type EvidenceDurability } from './durability.ts';
 export { setSandboxResolver, type SandboxResolver } from './sandbox.ts';
 // Lifecycle the daemon owns: provision Chromium at boot, drain the evidence
 // upload queue on its timer, close the warm browser on shutdown.
-export { ensureChromium } from './ensure-chromium.ts';
+export { ensureChromium, browsersPresent } from './ensure-chromium.ts';
 export { drainUploads } from './artifact-uploads.ts';
 export { closeBrowser } from './browser.ts';
 

package/src/mail-fill.ts

@@ -0,0 +1,176 @@
+// F009.137 — fill a field with a code that arrives by mail, read through the
+// fleet's mail-mcp (owner's choice, 25 Oct: no IMAP client of Lens' own).
+//
+// Two rules from the owner shape everything here:
+//   * only the TEST mailbox may be read — never his own inbox (a HelpDesk test
+//     burst landed there the night before this was built);
+//   * every mail a test consumes is cleaned up afterwards.
+// The code, the mail body and the key never reach a report, a step detail or an
+// error. A screenshot taken after the fill can show the field: a one-time code is
+// spent by then, and hiding it would mean not photographing the form at all.
+import type { Locator } from 'playwright';
+import { fillAndVerify } from './fill.ts';
+
+export interface MailFrom {
+  to: string;
+  /** Substring the subject must contain (case-insensitive). */
+  subject?: string;
+  /** Regex source for the code; the first capture group (or whole match) is used. */
+  match?: string;
+  /** How long to wait for the mail, ms. Default {@link MAIL_WAIT_MS}. */
+  timeout?: number;
+}
+
+export interface Mail {
+  id: string;
+  from: string;
+  /** The To header — carries the +tag the mailbox itself does not. */
+  to: string;
+  subject: string;
+  /** epoch ms */
+  receivedAt: number;
+  text: string;
+}
+
+/** The one door to the mailbox — mail-mcp's contract (mail-mcp F001.17): a
+ *  long-poll `wait` that returns the newest matching mail (+ the code when a
+ *  pattern is given), and `remove`. The HTTP implementation talks to mail-mcp;
+ *  tests pass a fake. */
+export interface MailSource {
+  wait(q: { to: string; since: number; subject?: string; codePattern: string; timeoutSeconds: number }): Promise<{ found: false } | { found: true; code: string | null; mail: Mail }>;
+  remove(q: { to: string; id: string }): Promise<void>;
+}
+
+export const MAIL_WAIT_MS = 60_000;
+export const DEFAULT_CODE = '\\b\\d{6}\\b';
+
+// The test mailbox and its agreed aliases — one place. Anything else is refused
+// at parse time, so a flow can never read or clean the owner's inbox.
+const TEST_MAILBOXES = ['webhouse.developer@gmail.com', 'jam@jams.party'];
+
+export function assertTestMailbox(addr: string): void {
+  const m = /^([^@+\s]+)(\+[^@\s]*)?@([^@\s]+)$/.exec(addr.trim().toLowerCase());
+  const base = m ? `${m[1]}@${m[3]}` : '';
+  if (!TEST_MAILBOXES.includes(base)) {
+    throw new Error(`fill from mail: ${addr} is not the test mailbox — only ${TEST_MAILBOXES.join(', ')} (and their +tags) may be read`);
+  }
+}
+
+/** mail-mcp addresses the MAILBOX (jam@jams.party); a +tag is only visible in
+ *  the mail's own To header. */
+export function mailboxOf(addr: string): string {
+  return addr.trim().toLowerCase().replace(/\+[^@]*@/, '@');
+}
+
+export function codeIn(mail: Mail, match: string | undefined): string | null {
+  const re = new RegExp(match ?? DEFAULT_CODE);
+  const m = re.exec(`${mail.subject}\n${mail.text}`);
+  return m ? (m[1] ?? m[0]) : null;
+}
+
+/** Wait for a mail to `mf.to` received at/after `since`, return its code + id.
+ *  mail-mcp holds each call open for at most 55 s, so a longer wait is several
+ *  calls; the overall bound is ours. */
+export async function waitForMailCode(
+  mf: MailFrom,
+  since: number,
+  source: MailSource,
+  now: () => number = Date.now,
+): Promise<{ code: string; id: string }> {
+  const timeout = mf.timeout ?? MAIL_WAIT_MS;
+  const until = now() + timeout;
+  const pattern = mf.match ?? DEFAULT_CODE;
+  for (;;) {
+    const left = Math.max(1, Math.min(55, Math.ceil((until - now()) / 1000)));
+    const r = await source.wait({ to: mailboxOf(mf.to), since, ...(mf.subject ? { subject: mf.subject } : {}), codePattern: pattern, timeoutSeconds: left });
+    // A +tag addresses ONE run: a mail to jam+other@ in the same mailbox is someone
+    // else's code and must not be typed here.
+    const forUs = (m: Mail) => mailboxOf(mf.to) === mf.to.trim().toLowerCase() || m.to.toLowerCase().includes(mf.to.trim().toLowerCase());
+    if (r.found && r.mail.receivedAt >= since && forUs(r.mail)) {
+      // Our own regex decides, so the code means the same thing whatever the
+      // server's pattern dialect; the server's code is only a fallback.
+      const code = codeIn(r.mail, pattern) ?? r.code;
+      if (code) return { code, id: r.mail.id };
+    }
+    if (now() >= until) {
+      throw new Error(
+        `fill from mail: no mail to ${mf.to}${mf.subject ? ` with subject ~ "${mf.subject}"` : ''} carrying a code arrived within ${Math.round(timeout / 1000)} s (counting mail received after ${new Date(since).toISOString()})`,
+      );
+    }
+  }
+}
+
+/** Fill the field with the code and record the mail for cleanup. Errors carry
+ *  lengths, never the code. */
+export async function fillFromMail(
+  loc: Locator,
+  mf: MailFrom,
+  since: number,
+  source: MailSource,
+  consumed: Array<{ to: string; id: string }>,
+  timeout: number,
+): Promise<void> {
+  const { code, id } = await waitForMailCode(mf, since, source);
+  consumed.push({ to: mailboxOf(mf.to), id });
+  try {
+    await fillAndVerify(loc, code, timeout);
+  } catch {
+    throw new Error(`fill from mail did not land: expected a ${code.length}-character code in the field (value withheld)`);
+  }
+}
+
+/** Remove every consumed mail. Never throws — the run's verdict is about the
+ *  page; the cleanup result is reported beside it. */
+export async function cleanupMail(consumed: Array<{ to: string; id: string }>, source: MailSource): Promise<{ consumed: number; cleaned: number; reason?: string }> {
+  let cleaned = 0;
+  let reason: string | undefined;
+  for (const { to, id } of consumed) {
+    try {
+      await source.remove({ to, id });
+      cleaned++;
+    } catch (err) {
+      reason = `could not remove mail ${id}: ${err instanceof Error ? err.message.split('\n')[0] : String(err)}`;
+    }
+  }
+  return { consumed: consumed.length, cleaned, ...(reason ? { reason } : {}) };
+}
+
+/** mail-mcp's read API over HTTP (contract: mail-mcp F001.17, recorded in
+ *  docs/features/F009.137-fill-from-mail.md). Base URL and key come from the
+ *  daemon's own env (LENS_MAIL_API, LENS_MAIL_KEY) — never from a caller. */
+export function httpMailSource(env: Record<string, string | undefined> = process.env): MailSource {
+  const base = (env.LENS_MAIL_API ?? 'https://mailmcp.webhouse.net').replace(/\/$/, '');
+  const key = env.LENS_MAIL_KEY;
+  const post = async (path: string, body: unknown, ms: number) => {
+    if (!key) throw new Error('fill from mail: the daemon has no mail-mcp key (LENS_MAIL_KEY)');
+    const r = await fetch(`${base}${path}`, {
+      method: 'POST',
+      headers: { 'x-mailmcp-key': key, 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(ms),
+    });
+    if (!r.ok) throw new Error(`mail-mcp ${path} answered ${r.status}`);
+    return (await r.json()) as Record<string, unknown>;
+  };
+  return {
+    async wait(q) {
+      const j = await post('/api/mail/wait', {
+        to: q.to,
+        since: q.since,
+        code_pattern: q.codePattern,
+        timeout_seconds: q.timeoutSeconds,
+        ...(q.subject ? { subject_contains: q.subject } : {}),
+      }, (q.timeoutSeconds + 10) * 1000);
+      if (!j.found) return { found: false };
+      const m = j.message as { id: string; from: string; to?: string; subject: string; received_at: string | number; body?: string };
+      return {
+        found: true,
+        code: typeof j.code === 'string' ? j.code : null,
+        mail: { id: m.id, from: m.from, to: m.to ?? '', subject: m.subject, receivedAt: new Date(m.received_at).getTime(), text: m.body ?? '' },
+      };
+    },
+    async remove(q) {
+      await post('/api/mail/delete', { to: q.to, id: q.id }, 30_000);
+    },
+  };
+}

package/src/mcp.ts

@@ -405,7 +405,7 @@ export const TOOLS = [
   {
     name: 'lens_run_manuscript',
     description:
-      `Compile a human-readable markdown manuscript (fmc-automation style: "# flow: name", "base: <url>", then one "- <verb> …" per line) into a flow and run it E2E. VERBS (${MANUSCRIPT_VERBS.length}, this is the complete list): ${MANUSCRIPT_VERBS.join(' / ')}. Shapes: "- goto /x" · "- fill [testid] = value" · a PASSWORD without plaintext: "- fill [testid] from file <path>" (absolute, or relative to local_path) or "- fill [testid] from env <NAME>" (F009.121 — password inputs only; the value never appears in the run, the report or a screenshot) · "- click [testid]" · "- press Enter" (global) or "- press Enter [testid]" (on a focused element) · "- expectText [testid] ~ text" · "- drag [source] -> [target]" or "- drag [node] by 120,-40" (a canvas offset; both move in 10 mousemoves so React Flow / d3-drag nodes really move — "steps N" to change, F009.123) · "- upload [input-testid] = <fixture>" · an input with NO testid, also inside an open shadow root: "- uploadSelector <css> = <fixture>[, <fixture>]" (F009.136; fixtures repo-relative to local_path or data:) · "- assert: <js>" · "- screenshot label" · frame-aware "- fillSelector <css> = <value> @frame <iframe>" and "- clickSelector <css> @frame <iframe>" · "- waitForUrl <substring>". TWO BROWSERS AT ONCE (F009.122): prefix a step with "in <name>:" — "- in b: goto /" · "- in b: expectText [note] == Hej" — and it runs in its own browser (own cookies + storage), open alongside the default one for the rest of the run; steps without the prefix run in the default browser. Click modifiers: "- click [testid] via enter" (F255.1, for Angular/MDC buttons a mouse click does not activate) and "- click [testid] @ 50%,28%" (F255.4, aim at a point inside a canvas/3D surface). A field that already HOLDS a value may no longer render an input — a combobox typically swaps to its selected state, so "fill" times out there while "press ArrowDown" / "press Enter" still drive it (fd-sundhed, 2026-08-21). The authoring shortcut — write prose, not JSON.`,
+      `Compile a human-readable markdown manuscript (fmc-automation style: "# flow: name", "base: <url>", then one "- <verb> …" per line) into a flow and run it E2E. VERBS (${MANUSCRIPT_VERBS.length}, this is the complete list): ${MANUSCRIPT_VERBS.join(' / ')}. Shapes: "- goto /x" · "- fill [testid] = value" · a PASSWORD without plaintext: "- fill [testid] from file <path>" (absolute, or relative to local_path) or "- fill [testid] from env <NAME>" (F009.121 — password inputs only; the value never appears in the run, the report or a screenshot) · "- click [testid]" · "- press Enter" (global) or "- press Enter [testid]" (on a focused element) · "- expectText [testid] ~ text" · "- drag [source] -> [target]" or "- drag [node] by 120,-40" (a canvas offset; both move in 10 mousemoves so React Flow / d3-drag nodes really move — "steps N" to change, F009.123) · "- upload [input-testid] = <fixture>" · an input with NO testid, also inside an open shadow root: "- uploadSelector <css> = <fixture>[, <fixture>]" (F009.136; fixtures repo-relative to local_path or data:) · a CODE FROM MAIL: "- fill [testid] from mail to jam@jams.party subject ~ Jam match /\\b\\d{6}\\b/" (F009.137 — waits ≤60 s for a mail received after the step started, read through mail-mcp; only the test mailbox webhouse.developer@gmail.com / jam@jams.party; the mail is deleted after the run, report carries mail {consumed, cleaned}; the code never appears in the report) · "- assert: <js>" · "- screenshot label" · frame-aware "- fillSelector <css> = <value> @frame <iframe>" and "- clickSelector <css> @frame <iframe>" · "- waitForUrl <substring>". TWO BROWSERS AT ONCE (F009.122): prefix a step with "in <name>:" — "- in b: goto /" · "- in b: expectText [note] == Hej" — and it runs in its own browser (own cookies + storage), open alongside the default one for the rest of the run; steps without the prefix run in the default browser. Click modifiers: "- click [testid] via enter" (F255.1, for Angular/MDC buttons a mouse click does not activate) and "- click [testid] @ 50%,28%" (F255.4, aim at a point inside a canvas/3D surface). A field that already HOLDS a value may no longer render an input — a combobox typically swaps to its selected state, so "fill" times out there while "press ArrowDown" / "press Enter" still drive it (fd-sundhed, 2026-08-21). The authoring shortcut — write prose, not JSON.`,
     inputSchema: {
       type: 'object',
       required: ['project', 'manuscript'],

package/src/secret-fill.ts

@@ -8,11 +8,11 @@ import { resolve, sep } from 'node:path';
 import type { Locator } from 'playwright';
 import { fillAndVerify } from './fill.ts';
 import type { FilledPassword } from './password-in-url.ts';
-import type { ValueFrom } from './flow.ts';
+import type { SecretFrom } from './flow.ts';
 
 /** Read the secret. Every error names WHERE it looked and never WHAT it found. */
 export async function readSecret(
-  vf: ValueFrom,
+  vf: SecretFrom,
   secretRoot: string | undefined,
   env: Record<string, string | undefined> = process.env,
 ): Promise<string> {
@@ -51,7 +51,7 @@ export async function readSecret(
  *  the shape of a mismatch, never characters. */
 export async function fillSecret(
   loc: Locator,
-  vf: ValueFrom,
+  vf: SecretFrom,
   secretRoot: string | undefined,
   timeout: number,
   pwSink: FilledPassword[] | undefined,