@broberg/lens-daemon 0.1.14 → 0.1.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@broberg/lens-daemon",
-  "version": "0.1.14",
+  "version": "0.1.18",
   "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.33.5",
     "turndown": "^7.2.4",
     "zod": "^3.23.8",
-    "@broberg/lens-svg": "0.1.0",
-    "@broberg/lens-engine": "0.13.1"
+    "@broberg/lens-engine": "0.13.1",
+    "@broberg/lens-svg": "0.1.0"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.10.6",

package/src/extension-flow.ts

@@ -15,6 +15,7 @@
 
 import { cp, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
+import type { BrowserContext } from 'playwright';
 import { join } from 'node:path';
 
 interface Manifest {
@@ -80,3 +81,84 @@ export async function prepareExtension(path: string, grantHostAccess: boolean):
 export const SIMULATED_ACCESS_NOTE =
   'host access SIMULATED: the extension ran from a temporary copy that may read every page, ' +
   'standing in for the toolbar click (activeTab) a headless run cannot make';
+
+/** F009.126 — write `values` into the loaded extension's chrome.storage.local, from
+ *  the extension's own context (MV3 service worker, or MV2 background page), so the
+ *  popup's first render already finds them — a login it keeps there, for example.
+ *  Read back and compared, so a seed that did not land fails the run here instead
+ *  of showing up later as a popup that is mysteriously logged out. */
+export async function seedExtensionStorage(context: BrowserContext, values: Record<string, unknown>): Promise<void> {
+  const keys = Object.keys(values);
+  // An MV3 service worker can be stopped and restarted by Chrome at any moment, and an
+  // evaluate on the stopped one never settles — observed as a 90 s hang under a loaded
+  // test suite, never in isolation. So every attempt has a deadline, and each retry asks
+  // the context for the worker that is live NOW instead of reusing the old handle.
+  let back: Record<string, unknown> | null | undefined;
+  let lastError = 'no attempt made';
+  for (let attempt = 1; attempt <= SEED_ATTEMPTS && back === undefined; attempt++) {
+    const target =
+      context.serviceWorkers()[0] ??
+      context.backgroundPages()[0] ??
+      (await context.waitForEvent('serviceworker', { timeout: SEED_DEADLINE_MS }).catch(() => undefined));
+    if (!target) {
+      lastError = 'no service worker or background page to write chrome.storage.local from';
+      continue;
+    }
+    try {
+      back = await deadline(
+        target.evaluate(async (v: Record<string, unknown>) => {
+          const c = (globalThis as unknown as { chrome: { storage?: { local: { set(x: object): Promise<void>; get(k: string[]): Promise<Record<string, unknown>> } } } }).chrome;
+          if (!c.storage) return null;
+          await c.storage.local.set(v);
+          return c.storage.local.get(Object.keys(v));
+        }, values),
+        SEED_DEADLINE_MS,
+      );
+    } catch (err) {
+      lastError = err instanceof Error ? err.message : String(err);
+    }
+  }
+  if (back === undefined) throw new Error(`storage_local: could not write chrome.storage.local after ${SEED_ATTEMPTS} attempts — ${lastError}`);
+  if (!back) throw new Error('storage_local: the extension has no chrome.storage — its manifest does not request the "storage" permission, so there is nowhere to seed');
+  const missing = keys.filter((k) => !sameJson(back![k], values[k]));
+  if (missing.length) throw new Error(`storage_local: chrome.storage.local did not keep ${missing.join(', ')} — read back differs from what was written`);
+}
+
+const SEED_ATTEMPTS = 3;
+const SEED_DEADLINE_MS = 5_000;
+
+/** Reject after `ms` instead of waiting forever on a call that will never settle. */
+export function deadline<T>(p: Promise<T>, ms: number): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const t = setTimeout(() => reject(new Error(`no answer within ${ms} ms`)), ms);
+    t.unref?.();
+    p.then(
+      (v) => {
+        clearTimeout(t);
+        resolve(v);
+      },
+      (e) => {
+        clearTimeout(t);
+        reject(e);
+      },
+    );
+  });
+}
+
+/** F009.127 — structural equality for JSON values, blind to object key ORDER.
+ *  chrome.storage hands an object back with its keys reordered, so comparing
+ *  JSON text refused a login object that had landed perfectly. Array order and
+ *  every value still count. Exported for test. */
+export function sameJson(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (typeof a !== typeof b || a === null || b === null || typeof a !== 'object') return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  if (Array.isArray(a)) {
+    const bb = b as unknown[];
+    return a.length === bb.length && a.every((v, i) => sameJson(v, bb[i]));
+  }
+  const ao = a as Record<string, unknown>;
+  const bo = b as Record<string, unknown>;
+  const ak = Object.keys(ao);
+  return ak.length === Object.keys(bo).length && ak.every((k) => Object.hasOwn(bo, k) && sameJson(ao[k], bo[k]));
+}

package/src/flow-store.ts

@@ -9,7 +9,7 @@ import { randomUUID } from 'node:crypto';
 import type { LensFlowRunRow } from './schema.ts';
 import { artifactKeys, type LensStorage } from './storage.ts';
 import { enqueueArtifacts } from './artifact-uploads.ts';
-import type { FlowResult, FailedResponse } from './flow.ts';
+import type { FlowDownload, FlowResult, FailedResponse } from './flow.ts';
 
 /** A per-step entry as persisted (screenshot bytes already offloaded to an
  *  artifact key — null when the step took no shot). */
@@ -110,6 +110,18 @@ export async function recordFlowRun(
     await storage.put(videoKey, result.video);
   }
 
+  // F009.128 — downloaded files go where the stills go; the row keeps only the key.
+  const storedDownloads: Array<Omit<FlowDownload, 'bytes'> & { key?: string }> = [];
+  for (const [n, d] of (result.downloads ?? []).entries()) {
+    const { bytes, ...meta } = d;
+    let key: string | undefined;
+    if (bytes) {
+      key = artifactKeys.flowDownload(projectSlug, id, n, d.name);
+      await storage.put(key, bytes);
+    }
+    storedDownloads.push({ ...meta, ...(key ? { key } : {}) });
+  }
+
   const row: LensFlowRunRow = {
     id,
     project_slug: projectSlug,
@@ -157,6 +169,8 @@ export async function recordFlowRun(
       ...(result.extension ? { extension: result.extension } : {}),
       ...(result.password_in_url ? { password_in_url: result.password_in_url } : {}),
       ...(result.not_listening ? { not_listening: result.not_listening } : {}),
+      // F009.128 — always written when the run reported it, empty included.
+      ...(result.downloads ? { downloads: storedDownloads } : {}),
     }),
   };
 

package/src/flow.ts

@@ -24,7 +24,7 @@ import {
   type Target,
 } from '@broberg/lens-engine';
 import { withPage, type LensEngine } from './browser.ts';
-import { defaultPopupOf, prepareExtension, SIMULATED_ACCESS_NOTE } from './extension-flow.ts';
+import { deadline, defaultPopupOf, prepareExtension, seedExtensionStorage, SIMULATED_ACCESS_NOTE } from './extension-flow.ts';
 import { authPrepare, type AuthConfig, type AuthEnv } from './auth/index.ts';
 import { takeShot, settleForShot } from './capture.ts';
 import { runCritic, topFindingMessage, type CriticMode, type CriticReport } from './critic.ts';
@@ -158,7 +158,11 @@ export type FlowStep =
   // F009.125 — open the loaded extension's popup as its own page in the SAME browser,
   // then put the page under test back in front so the extension sees it as the active
   // tab (measured). `path` defaults to the manifest's action.default_popup.
-  | { type: 'openPopup'; path?: string; label?: string; timeout?: number };
+  | { type: 'openPopup'; path?: string; label?: string; timeout?: number }
+  // F009.126 — pass when the run made a matching request (page, popup, any page in the
+  // run's browser). `url` is a substring, or a regex with match:"regex" (a path like
+  // "/api/clips" would otherwise read as a /pattern/flags literal). Fails listing what WAS seen.
+  | { type: 'expectRequest'; url: string; match?: 'contains' | 'regex'; method?: string; status?: number; label?: string; timeout?: number };
 
 export interface Flow {
   name: string;
@@ -187,6 +191,9 @@ export interface Flow {
 export interface FlowExtension {
   path: string;
   grant_host_access?: boolean;
+  /** F009.126 — written to the extension's chrome.storage.local before step 0, so a
+   *  popup that keeps its login there starts signed in (OAuth cannot run headless). */
+  storage_local?: Record<string, unknown>;
 }
 
 /**
@@ -352,7 +359,36 @@ export class InstrumentError extends Error {
   }
 }
 
+/** F009.128 — one file the run's browser downloaded. `bytes` is dropped once the
+ *  store has written it; a reader gets `url` instead. */
+export interface FlowDownload {
+  name: string;
+  size: number;
+  /** Which page triggered it: the page under test, the extension popup, or another. */
+  page: 'page' | 'popup' | 'other';
+  /** Index of the step that was running when it started; null before the first. */
+  step: number | null;
+  bytes?: Buffer;
+  error?: string;
+  /** Not kept because a limit was hit (MAX_DOWNLOADS / MAX_DOWNLOAD_BYTES). */
+  skipped?: 'cap';
+}
+export const MAX_DOWNLOADS = 10;
+export const MAX_DOWNLOAD_BYTES = 25 * 1024 * 1024;
+const DOWNLOAD_SETTLE_MS = 5_000;
+const DOWNLOAD_FINISH_MS = 30_000;
+
+/** F009.128 — wait for the run's downloads, bounded. Whatever has not finished by
+ *  then is marked as such, never dropped and never waited on forever. Exported for test. */
+export async function finishDownloads(pending: Promise<void>[], downloads: FlowDownload[], ms: number): Promise<void> {
+  await deadline(Promise.allSettled(pending), ms).catch(() => {
+    for (const d of downloads) if (!d.bytes && !d.error && !d.skipped) d.error = `did not finish within ${ms} ms`;
+  });
+}
+
 export interface FlowResult {
+  /** F009.128 — files the run downloaded. Always present on a finished run. */
+  downloads?: FlowDownload[];
   /** 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?: { id: string; path: string; host_access: 'as-built' | 'simulated'; note?: string } | null;
@@ -425,6 +461,8 @@ export const STEP_TYPES = new Set([
   'waitForReady',
   // F009.125 — drive a loaded extension's popup
   'openPopup',
+  // F009.126 — assert a request the run made
+  'expectRequest',
 ]);
 
 /** Validate + normalise an untrusted flow (HTTP/MCP boundary). Throws on the
@@ -458,13 +496,21 @@ export function parseFlow(input: unknown): Flow {
   if (f.extension !== undefined) {
     const e = f.extension as unknown as Record<string, unknown>;
     const keys = e && typeof e === 'object' && !Array.isArray(e) ? Object.keys(e) : null;
-    if (!keys || typeof e.path !== 'string' || !e.path || keys.some((k) => k !== 'path' && k !== 'grant_host_access')) {
-      throw new Error('flow.extension must be {path: "<unpacked build dir>", grant_host_access?: boolean}');
+    if (!keys || typeof e.path !== 'string' || !e.path || keys.some((k) => k !== 'path' && k !== 'grant_host_access' && k !== 'storage_local')) {
+      throw new Error('flow.extension must be {path: "<unpacked build dir>", grant_host_access?: boolean, storage_local?: {…}}');
     }
     if (e.grant_host_access !== undefined && typeof e.grant_host_access !== 'boolean') {
       throw new Error('flow.extension.grant_host_access must be a boolean');
     }
-    extension = { path: e.path, ...(e.grant_host_access === true ? { grant_host_access: true } : {}) };
+    const sl = e.storage_local;
+    if (sl !== undefined && (sl === null || typeof sl !== 'object' || Array.isArray(sl))) {
+      throw new Error('flow.extension.storage_local must be an object of {key: JSON value} — it is passed to chrome.storage.local.set as-is');
+    }
+    extension = {
+      path: e.path,
+      ...(e.grant_host_access === true ? { grant_host_access: true } : {}),
+      ...(sl !== undefined ? { storage_local: sl as Record<string, unknown> } : {}),
+    };
   }
   validateAndNormalizeSteps(f.steps);
   if (!extension && usesPopup(f.steps as FlowStep[])) {
@@ -482,6 +528,40 @@ export function parseFlow(input: unknown): Flow {
   };
 }
 
+function requestRegex(u: string): RegExp {
+  try {
+    return new RegExp(u);
+  } catch (err) {
+    throw new Error(`expectRequest: url ${u} is not a valid regex — ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+/** F009.126 — one request the run's browser made, as expectRequest sees it. */
+export interface SeenRequest {
+  method: string;
+  url: string;
+  /** Playwright's resource type; 'document' is a navigation (and what a link download is). */
+  type?: string;
+  /** null while in flight, or when it failed before a response. */
+  status: number | null;
+  failed?: string;
+}
+
+/** F009.126 — does this request satisfy the step? Exported for test. */
+export function requestMatches(r: SeenRequest, want: { url: string; match?: 'contains' | 'regex'; method?: string; status?: number }): boolean {
+  const urlOk = want.match === 'regex' ? requestRegex(want.url).test(r.url) : r.url.includes(want.url);
+  if (!urlOk) return false;
+  if (want.method && r.method.toUpperCase() !== want.method.toUpperCase()) return false;
+  if (want.status !== undefined && r.status !== want.status) return false;
+  return true;
+}
+
+/** Query strings can carry tokens; a failure report shows the path only. */
+function redactQuery(u: string): string {
+  const q = u.indexOf('?');
+  return q === -1 ? u : `${u.slice(0, q)}?…`;
+}
+
 function usesPopup(steps: FlowStep[]): boolean {
   return steps.some(
     (st) =>
@@ -551,6 +631,7 @@ export const STEP_FIELDS: Record<string, string[]> = {
   conditional: ['testid', 'present', 'steps'],
   loop: ['data', 'steps', 'parallel'],
   openPopup: ['path'],
+  expectRequest: ['url', 'match', 'method', 'status'],
 };
 
 function validateAndNormalizeSteps(steps: unknown[], depth = 0, inParallel = false): void {
@@ -633,6 +714,20 @@ function validateAndNormalizeSteps(steps: unknown[], depth = 0, inParallel = fal
       }
       if ('browser' in s || inParallel) throw new Error(`step ${index} (openPopup): the popup opens in the main browser only`);
     }
+    if (s.type === 'expectRequest') {
+      const r = s as { url?: unknown; match?: unknown; method?: unknown; status?: unknown };
+      if (typeof r.url !== 'string' || !r.url) throw new Error(`step ${index} (expectRequest): url is required — a substring, or a regex with match:"regex"`);
+      if (r.match !== undefined && r.match !== 'contains' && r.match !== 'regex') {
+        throw new Error(`step ${index} (expectRequest): match must be "contains" (default) or "regex"`);
+      }
+      if (r.match === 'regex') requestRegex(r.url); // throws on a bad pattern now, not mid-run
+      if (r.method !== undefined && (typeof r.method !== 'string' || !/^[A-Za-z]+$/.test(r.method))) {
+        throw new Error(`step ${index} (expectRequest): method must be an HTTP method like "POST"`);
+      }
+      if (r.status !== undefined && (typeof r.status !== 'number' || !Number.isInteger(r.status) || r.status < 100 || r.status > 599)) {
+        throw new Error(`step ${index} (expectRequest): status must be an HTTP status code (100–599)`);
+      }
+    }
     if (s.type === 'autocomplete') {
       if (typeof (s as { value?: unknown }).value !== 'string') throw new Error('autocomplete step requires a string value');
       if (typeof (s as { option?: unknown }).option !== 'string') throw new Error('autocomplete step requires a string option testid');
@@ -1365,6 +1460,7 @@ function describe(step: FlowStep): string {
     case 'conditional': return `${step.present ? 'if' : 'unless'} [${step.testid}]`;
     case 'loop': return 'loop';
     case 'openPopup': return `openPopup ${step.path ?? '(manifest popup)'}`;
+    case 'expectRequest': return `expectRequest ${step.method ? `${step.method.toUpperCase()} ` : ''}${step.url}${step.status ? ` → ${step.status}` : ''}`;
     case 'waitForBuild': return `waitForBuild${step.sha ? ` ${step.sha.slice(0, 8)}` : ' (changed)'}`;
     // F255.4 — show the offset in the step label so a positioned click is
     // recognisable in the report (a plain "click canvas" hides where it aimed).
@@ -1497,6 +1593,14 @@ export async function clickAndActivate(
     if (t === 'xhr' || t === 'fetch' || t === 'document') requests += 1;
   };
   page.on('request', onRequest);
+  // F009.128 — a download IS an effect. A button whose only job is a download
+  // (a blob handed to <a download>) touches no DOM and makes no request, so it
+  // read as a silent no-op and got pressed twice: two files for one click.
+  let downloaded = false;
+  const onDownload = () => {
+    downloaded = true;
+  };
+  page.on('download', onDownload);
   const urlBefore = page.url();
   await page
     .evaluate(() => {
@@ -1541,7 +1645,7 @@ export async function clickAndActivate(
       const mutations = await page
         .evaluate(() => (window as unknown as { __lensMut?: number }).__lensMut ?? 0)
         .catch(() => 1); // page navigated away → that IS an effect
-      if (mutations > 0 || requests > 0 || page.url() !== urlBefore) return false;
+      if (mutations > 0 || requests > 0 || downloaded || page.url() !== urlBefore) return false;
       const focusMoved = await page
         .evaluate(
           ([before, clicked]) => {
@@ -1564,6 +1668,7 @@ export async function clickAndActivate(
     return true;
   } finally {
     page.off('request', onRequest);
+    page.off('download', onDownload);
     await focusBefore.dispose().catch(() => {});
     await target?.dispose().catch(() => {});
     await page
@@ -2329,6 +2434,8 @@ async function execStep(page: Page, step: FlowStep, base: string, vars: Record<s
       throw new Error('loop steps are flattened before execution');
     case 'openPopup':
       throw new Error('openPopup steps are handled by runSeq, never execStep');
+    case 'expectRequest':
+      throw new Error('expectRequest steps are handled by runSeq, never execStep');
   }
 }
 
@@ -2674,6 +2781,7 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
       // F213.11 — read BEFORE the step runs, so the number is "how long after the
       // page loaded did this start", never "how long did it take".
       const stepStartedAt = Date.now();
+      currentStep = i;
       const msAfterNav = stepStartedAt - lastNavAt;
       // F213.13 — a goto's reading is measured from the PREVIOUS navigation, so it
       // is not the same quantity as its siblings and must not sit in their column.
@@ -2693,6 +2801,8 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
         const out =
           step.type === 'openPopup'
             ? 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);
         const obj = out !== null && !Buffer.isBuffer(out) && typeof out === 'object' ? out : null;
         const inspect = obj && '__inspect' in obj ? (obj as { __inspect: string }).__inspect : null;
@@ -2859,6 +2969,87 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
     extCtx.popup = popup;
     return null;
   };
+  // F009.128 — files the run downloads. A download is awaited before the context
+  // closes; otherwise the bytes die with the browser and the report says nothing.
+  const downloads: FlowDownload[] = [];
+  const pendingDownloads: Promise<void>[] = [];
+  let currentStep: number | null = null;
+  const watchDownloads = (context: BrowserContext): void => {
+    const hooked = new WeakSet<Page>();
+    const hook = (p: Page) => {
+      if (hooked.has(p)) return;
+      hooked.add(p);
+      p.on('download', (d) => {
+        const entry: FlowDownload = {
+          name: d.suggestedFilename(),
+          size: 0,
+          page: p === extCtx?.popup ? 'popup' : p === extCtx?.main || p === videoPage ? 'page' : 'other',
+          step: currentStep,
+        };
+        downloads.push(entry);
+        if (downloads.length > MAX_DOWNLOADS) {
+          entry.skipped = 'cap';
+          pendingDownloads.push(d.cancel().catch(() => {}));
+          return;
+        }
+        pendingDownloads.push(
+          (async () => {
+            const failure = await d.failure();
+            // `??=`: once the run gave up waiting, the context closing cancels the
+            // download — and 'canceled' would hide that it simply never finished.
+            if (failure) {
+              entry.error ??= failure;
+              return;
+            }
+            const path = await d.path();
+            const bytes = await readFile(path);
+            entry.size = bytes.length;
+            if (bytes.length > MAX_DOWNLOAD_BYTES) entry.skipped = 'cap';
+            else entry.bytes = bytes;
+          })().catch((err) => {
+            entry.error ??= err instanceof Error ? err.message : String(err);
+          }),
+        );
+      });
+    };
+    context.pages().forEach(hook);
+    context.on('page', hook);
+  };
+  // F009.126 — every request the run's main browser makes, from the first step on.
+  const seenRequests: SeenRequest[] = [];
+  const watchRequests = (context: BrowserContext): void => {
+    const byReq = new Map<object, SeenRequest>();
+    context.on('request', (req) => {
+      const r: SeenRequest = { method: req.method(), url: req.url(), status: null, type: req.resourceType() };
+      byReq.set(req, r);
+      seenRequests.push(r);
+    });
+    context.on('requestfinished', async (req) => {
+      const r = byReq.get(req);
+      if (r) r.status = (await req.response().catch(() => null))?.status() ?? null;
+    });
+    context.on('requestfailed', (req) => {
+      const r = byReq.get(req);
+      if (r) r.failed = req.failure()?.errorText ?? 'failed';
+    });
+  };
+  const expectRequest = async (step: Extract<FlowStep, { type: 'expectRequest' }>, vars: Record<string, unknown>): Promise<null> => {
+    const want = { url: subst(step.url, vars), match: step.match, method: step.method, status: step.status };
+    const deadline = Date.now() + stepTimeout(step);
+    for (;;) {
+      if (seenRequests.some((r) => requestMatches(r, want))) return null;
+      if (Date.now() >= deadline) break;
+      await new Promise((res) => setTimeout(res, 100));
+    }
+    const seen = seenRequests
+      .filter((r) => !/^(data|chrome-extension):/.test(r.url))
+      .slice(-10)
+      .map((r) => `${r.method} ${redactQuery(r.url)} → ${r.failed ? `failed (${r.failed})` : r.status ?? 'no response'}`);
+    throw new Error(
+      `no request matched ${want.method ? `${want.method.toUpperCase()} ` : ''}${want.url}${want.status ? ` → ${want.status}` : ''}. ` +
+        (seen.length ? `Seen (last ${seen.length}): ${seen.join('; ')}.` : 'The run made no http(s) requests at all.'),
+    );
+  };
   const readVideo = async (): Promise<Buffer | null> => {
     if (!videoDir) return null;
     try {
@@ -2912,8 +3103,11 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
       async (page, context, ext) => {
         videoPage = page;
         collectFailures(page);
+        watchRequests(context);
+        watchDownloads(context);
         if (ext && flow.extension && prepared) {
           extCtx = { context, id: ext.id, main: page, popup: null };
+          if (flow.extension.storage_local) await seedExtensionStorage(context, flow.extension.storage_local);
           extensionInfo = {
             id: ext.id,
             path: flow.extension.path,
@@ -3012,6 +3206,22 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
         } catch {
           // page already closed — final_url stays null (not measured)
         }
+        // F009.128 — before the context (and the files) go away. A link download is a
+        // navigation whose 'download' event fires only once its headers arrive, which can
+        // be AFTER the last step returned; so wait for navigations still in flight (bounded)
+        // and only then for the downloads they turned into. Runs with nothing in flight
+        // pay nothing.
+        // A navigation Chromium turns into a download is ABORTED as a request
+        // (net::ERR_ABORTED) and only then raises 'download' — so count those too.
+        const settleUntil = Date.now() + DOWNLOAD_SETTLE_MS;
+        const navInFlight = () => seenRequests.some((r) => r.type === 'document' && r.status === null && !r.failed);
+        const becameDownload = () => seenRequests.filter((r) => r.type === 'document' && (r.failed ?? '').includes('ERR_ABORTED')).length;
+        while (Date.now() < settleUntil && (navInFlight() || downloads.length < becameDownload())) {
+          await new Promise((res) => setTimeout(res, 100));
+        }
+        // Bounded: a download that never finishes must not hang the run. Whatever is
+        // still unfinished is reported as such, never dropped.
+        await finishDownloads(pendingDownloads, downloads, DOWNLOAD_FINISH_MS);
       },
     );
   } catch (err) {
@@ -3019,7 +3229,7 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
     // Keep the recording even on a crash — watching HOW it broke is the whole point.
     const video = await readVideo();
     await prepared?.cleanup();
-    return { ...(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' };
+    return { downloads, ...(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' };
   }
 
   const video = await readVideo();
@@ -3073,6 +3283,7 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
     // context can never disagree about it.
     reduced_motion: opts.reducedMotion ?? 'reduce',
     ...(extensionInfo ? { extension: extensionInfo } : {}),
+    downloads,
   };
 }
 

package/src/mcp.ts

@@ -364,16 +364,17 @@ export const TOOLS = [
               type: 'object',
               required: ['path'],
               description:
-                'F009.125 — run the flow in a Chromium with this UNPACKED extension loaded (the build dir holding manifest.json; relative = relative to local_path; must be inside the daemon sandbox). Then: {type:"openPopup", path?} opens the popup (default: the manifest action.default_popup) as its own page and keeps the page under test as the extension\'s ACTIVE tab (measured), and any step with in:"popup" runs in the popup. grant_host_access:true loads a TEMPORARY COPY with <all_urls> host access, standing in for the toolbar click (activeTab) a headless run cannot make — without it chrome.scripting on the page fails ("Cannot access contents of the page"). The original build is never written; the report carries extension {id, host_access:"simulated"|"as-built"}. CHROMIUM ONLY.',
+                'F009.125 — run the flow in a Chromium with this UNPACKED extension loaded (the build dir holding manifest.json; relative = relative to local_path; must be inside the daemon sandbox). Then: {type:"openPopup", path?} opens the popup (default: the manifest action.default_popup) as its own page and keeps the page under test as the extension\'s ACTIVE tab (measured), and any step with in:"popup" runs in the popup. grant_host_access:true loads a TEMPORARY COPY with <all_urls> host access, standing in for the toolbar click (activeTab) a headless run cannot make — without it chrome.scripting on the page fails ("Cannot access contents of the page"). The original build is never written; the report carries extension {id, host_access:"simulated"|"as-built"}. CHROMIUM ONLY. F009.126 — storage_local:{key: JSON} is written to the extension\'s chrome.storage.local before step 0 (read back and compared), so a popup that keeps its login there starts signed in; needs the "storage" permission in the manifest. Pair with {type:"expectRequest", url, match?:"contains"|"regex", method?, status?} to assert a request the page, popup or extension worker made (fails listing what was seen).',
               properties: {
                 path: { type: 'string' },
                 grant_host_access: { type: 'boolean' },
+                storage_local: { type: 'object', description: 'F009.126 — {key: JSON value} for chrome.storage.local, set before step 0.' },
               },
             },
             steps: {
               type: 'array',
               description: 'Ordered steps. Each has a "type"; testid-anchored steps carry a "testid". fillSelector/clickSelector carry a CSS "selector" + optional "frame" (one iframe selector or an outer→inner string[] chain) to reach a cross-origin iframe; fillSelector also carries "value". waitForUrl carries a "url" substring. A "loop" step has data[] + steps[] and substitutes {{field}}/{{__index}}.',
-              items: { type: 'object', required: ['type'], properties: { type: { type: 'string' }, testid: { type: 'string' }, selector: { type: 'string' }, frame: { type: ['string', 'array'], items: { type: 'string' } }, url: { type: 'string' }, value: { type: 'string' }, text: { type: 'string' }, path: { type: 'string' }, js: { type: 'string' }, label: { type: 'string' }, timeout: { type: 'number' }, sha: { type: 'string', description: 'F255.7 — waitForBuild step: the commit sha to wait for. Omit to wait for any change from the build live when the step starts.' }, at: { type: 'string', description: 'F255.4 — click a POINT inside the element instead of its centre: "50%,28%" (fraction of the box) or "40,120" (css px). For canvas/3D surfaces where the centre hits nothing. Works on click + clickSelector.' }, activate: { type: 'string', enum: ['auto', 'click', 'enter'], description: 'F255.1 — how a button is fired. auto (default) clicks and falls back to focus+Enter only if nothing observable happened; enter forces focus+Enter (Angular/MDC forms); click keeps mouse-only.' }, in: { type: 'string', enum: ['popup'], description: 'F009.125 — run this step in the extension popup an earlier openPopup opened (needs flow.extension).' } } },
+              items: { type: 'object', required: ['type'], properties: { type: { type: 'string' }, testid: { type: 'string' }, selector: { type: 'string' }, frame: { type: ['string', 'array'], items: { type: 'string' } }, url: { type: 'string' }, value: { type: 'string' }, text: { type: 'string' }, path: { type: 'string' }, js: { type: 'string' }, label: { type: 'string' }, timeout: { type: 'number' }, sha: { type: 'string', description: 'F255.7 — waitForBuild step: the commit sha to wait for. Omit to wait for any change from the build live when the step starts.' }, at: { type: 'string', description: 'F255.4 — click a POINT inside the element instead of its centre: "50%,28%" (fraction of the box) or "40,120" (css px). For canvas/3D surfaces where the centre hits nothing. Works on click + clickSelector.' }, activate: { type: 'string', enum: ['auto', 'click', 'enter'], description: 'F255.1 — how a button is fired. auto (default) clicks and falls back to focus+Enter only if nothing observable happened; enter forces focus+Enter (Angular/MDC forms); click keeps mouse-only.' }, in: { type: 'string', enum: ['popup'], description: 'F009.125 — run this step in the extension popup an earlier openPopup opened (needs flow.extension).' }, method: { type: 'string', description: 'F009.126 — expectRequest: HTTP method to require, e.g. "POST".' }, status: { type: 'number', description: 'F009.126 — expectRequest: response status to require, e.g. 201.' } } },
             },
           },
         },

package/src/service.ts

@@ -666,11 +666,16 @@ function parseAuthJson(raw: string | null | undefined): { source: string; adapte
 /** NULL = the row predates the column, so we have no answer; `{}` = the run
  *  looked and found nothing. Malformed JSON is reported as unknown rather than
  *  as "clean": a parse failure must never read as an all-clear. */
-function parseFindingsJson(raw: string | null | undefined): Record<string, unknown> | null {
+function parseFindingsJson(raw: string | null | undefined, port?: number): Record<string, unknown> | null {
   if (raw == null) return null;
   try {
     const v = JSON.parse(raw);
-    return v && typeof v === 'object' ? (v as Record<string, unknown>) : null;
+    if (!v || typeof v !== 'object') return null;
+    // F009.128 — a stored download carries its storage key; a reader gets a url.
+    if (port !== undefined && Array.isArray(v.downloads)) {
+      v.downloads = v.downloads.map(({ key, ...d }: { key?: string }) => (key ? { ...d, url: artifactUrl(port, key) } : d));
+    }
+    return v as Record<string, unknown>;
   } catch {
     return null;
   }
@@ -748,7 +753,7 @@ export function flowRunView(row: LensFlowRunRow, port: number) {
     // and lens_list_flow_runs for the string and found neither — "the instrument
     // measures right and nobody is told", which is the same shape as the probe
     // that sat unwired to `fill` for a month.
-    findings: parseFindingsJson(row.findings_json),
+    findings: parseFindingsJson(row.findings_json, port),
     steps,
     // F255.5 — present only when the run was recorded. Same artifact mechanism as
     // the step screenshots, so a consumer fetches it exactly the same way.
@@ -869,7 +874,7 @@ export function toCloudFlowResult(result: EngineFlowResult, row: LensFlowRunRow,
     // (a CI runner with no daemon) is the consumer LEAST able to go and look
     // somewhere else, so leaving them off this shape would be the gap at its
     // worst.
-    findings: parseFindingsJson(row.findings_json),
+    findings: parseFindingsJson(row.findings_json, port),
     steps: result.steps.map((s) => ({
       index: s.index,
       action: s.action,

package/src/storage.ts

@@ -118,6 +118,9 @@ export const artifactKeys = {
     `${project}/flows/${flowRunId}/step-${stepIndex}.png`,
   // F255.5 — the whole driven run as a video, alongside its step stills.
   flowVideo: (project: string, flowRunId: string) => `${project}/flows/${flowRunId}/run.webm`,
+  // F009.128 — a file the run downloaded. Numbered so two files with one name both survive.
+  flowDownload: (project: string, flowRunId: string, n: number, name: string) =>
+    `${project}/flows/${flowRunId}/download-${n}-${name.replace(/[^\w.-]+/g, '_').slice(0, 120)}`,
   // F074.63 — a vector export (PDF). Its own prefix, not runs/: an export is not
   // a capture, carries no baseline and must never be diffed against one.
   exportDoc: (project: string, exportId: string, ext: string) =>