@broberg/lens-daemon 0.1.5 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@broberg/lens-daemon",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "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,7 +15,7 @@
     "sharp": "^0.33.5",
     "turndown": "^7.2.4",
     "zod": "^3.23.8",
-    "@broberg/lens-engine": "0.10.2",
+    "@broberg/lens-engine": "0.11.0",
     "@broberg/lens-svg": "0.1.0"
   },
   "devDependencies": {

package/src/flow.ts

@@ -233,6 +233,8 @@ export interface FlowStepResult {
   index: number;
   type: string;
   label: string;
+  /** F009.122 — the named browser this step ran in. Absent = the default one. */
+  browser?: string;
   status: 'pass' | 'fail' | 'skip';
   testid: string | null;
   detail: string | null;
@@ -449,7 +451,12 @@ function isValidTarget(t: unknown): boolean {
  *  FlowStep union above; flow-step-fields.test.ts reads the union from source and
  *  fails if the two drift. An unknown field is REFUSED: `inspect` with a guessed
  *  `selector` used to run a whole-page dump in silence (cardmem, flow b62ffca3). */
-const SHARED_STEP_FIELDS = ['type', 'label', 'timeout', 'timeout_ms'];
+const SHARED_STEP_FIELDS = ['type', 'label', 'timeout', 'timeout_ms', 'browser'];
+
+/** F009.122 — a step may name the browser it runs in. Each name is its own browser
+ *  context (own cookies + storage), opened on first use and kept open for the rest
+ *  of the run, so two people can be driven at the same time. `main` is the default. */
+const BROWSER_NAME = /^[a-z][a-z0-9_-]{0,23}$/;
 const TARGETED = ['testid', 'target'];
 export const STEP_FIELDS: Record<string, string[]> = {
   goto: ['path'],
@@ -484,7 +491,7 @@ export const STEP_FIELDS: Record<string, string[]> = {
   loop: ['data', 'steps', 'parallel'],
 };
 
-function validateAndNormalizeSteps(steps: unknown[], depth = 0): void {
+function validateAndNormalizeSteps(steps: unknown[], depth = 0, inParallel = false): void {
   if (depth > 3) throw new Error('flow loops nested too deep (max 3)');
   for (const [index, raw] of steps.entries()) {
     const s = raw as FlowStep & Record<string, unknown>;
@@ -518,13 +525,29 @@ function validateAndNormalizeSteps(steps: unknown[], depth = 0): void {
     if (s.type === 'loop') {
       if (!Array.isArray((s as { data?: unknown }).data)) throw new Error('loop step requires data[]');
       if (!Array.isArray((s as { steps?: unknown }).steps)) throw new Error('loop step requires steps[]');
-      validateAndNormalizeSteps((s as { steps: unknown[] }).steps, depth + 1);
+      const par = (s as { parallel?: unknown }).parallel;
+      validateAndNormalizeSteps((s as { steps: unknown[] }).steps, depth + 1, inParallel || (typeof par === 'number' && par > 1));
     }
     // F213.3 — control-flow + composite verbs.
     if (s.type === 'conditional') {
       if (typeof (s as { present?: unknown }).present !== 'boolean') throw new Error('conditional step requires a boolean present');
       if (!Array.isArray((s as { steps?: unknown }).steps)) throw new Error('conditional step requires steps[]');
-      validateAndNormalizeSteps((s as { steps: unknown[] }).steps, depth + 1);
+      validateAndNormalizeSteps((s as { steps: unknown[] }).steps, depth + 1, inParallel);
+    }
+    // F009.122 — the browser a step runs in. Refused where it cannot mean anything:
+    // a loop/conditional is not run in a browser (its children are), and a parallel
+    // loop iteration already owns a context of its own.
+    if ('browser' in s) {
+      const b = (s as { browser?: unknown }).browser;
+      if (typeof b !== 'string' || !BROWSER_NAME.test(b)) {
+        throw new Error(`step ${index} (${s.type}): browser must be a lowercase name like "anna" or "b" (${BROWSER_NAME}), got ${JSON.stringify(b)}`);
+      }
+      if (s.type === 'loop' || s.type === 'conditional') {
+        throw new Error(`step ${index} (${s.type}): browser goes on the steps inside a ${s.type}, not on the ${s.type} itself`);
+      }
+      if (inParallel) {
+        throw new Error(`step ${index} (${s.type}): browser is not allowed inside a parallel loop — each iteration already runs in its own browser`);
+      }
     }
     if (s.type === 'autocomplete') {
       if (typeof (s as { value?: unknown }).value !== 'string') throw new Error('autocomplete step requires a string value');
@@ -815,7 +838,13 @@ function parseStepBlock(lines: IndentLine[], start: number, minIndent: number):
       i = nextJ;
       continue;
     }
-    steps.push(parseManuscriptStep(body));
+    // F009.122 — `- in <name>: <step>` runs the step in that named browser.
+    const inM = body.match(/^in\s+([^\s:]+)\s*:\s*(.+)$/);
+    if (inM) {
+      steps.push(Object.assign(parseManuscriptStep(inM[2]!), { browser: inM[1]! }));
+    } else {
+      steps.push(parseManuscriptStep(body));
+    }
     i++;
   }
   return [steps, i];
@@ -1667,7 +1696,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[]): 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): Promise<Buffer | null | { __inspect: string } | { __via: string; __build?: string; __redirect?: string }> {
   switch (step.type) {
     case 'goto': {
       const p = subst(step.path, vars);
@@ -1706,7 +1735,7 @@ async function execStep(page: Page, step: FlowStep, base: string, vars: Record<s
       // used to pass as success, which is the half of the fleet save-rule this
       // instrument could not perform.
       if (step.valueFrom) {
-        await fillSecret(loc, step.valueFrom, localPath, remaining, pwSink, anchorOf(step));
+        await fillSecret(loc, step.valueFrom, secretRoot, remaining, pwSink, anchorOf(step));
         return via ? { __via: via } : null;
       }
       const filledValue = subst(step.value ?? '', vars);
@@ -2207,6 +2236,12 @@ export interface RunFlowOptions {
   /** F213.6 — repo root for resolving an uploadFile step's fixture path. The
    *  path is sandboxed to this dir (no `../` escape). Absent → only data: URIs. */
   localPath?: string;
+  /** F009.121 — the repo root a `fill valueFrom {path}` may read from, ALREADY
+   *  checked against the daemon sandbox by the caller. Absent → only {env} works.
+   *  Kept apart from localPath on purpose: a secret file is typed into whatever
+   *  page the caller named, so an unsandboxed root would let a flow post any file
+   *  the daemon can read to any URL. */
+  secretRoot?: string;
   /** 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. */
@@ -2373,12 +2408,60 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
         skipFill(s.steps, idx, vars, detail);
         idx += flattenCount(s.steps);
       } else {
-        record({ index: idx, type: s.type, label: s.label ?? describe(s), status: 'skip', testid: testidOf(s), detail, screenshot: null });
+        const b = (s as { browser?: string }).browser;
+        record({ index: idx, type: s.type, label: s.label ?? describe(s), ...(b ? { browser: b } : {}), status: 'skip', testid: testidOf(s), detail, screenshot: null });
         idx += 1;
       }
     }
   };
 
+  // ── F009.122 · named browsers ────────────────────────────────────────────
+  // Each name gets its own context through the SAME withPage the default browser
+  // uses (same auth, storage seed, viewport, engine), held open until the run ends.
+  // The steps stay sequential; the browsers are concurrent — that is what lets
+  // «A types, then B sees it» be measured with B's own timeout.
+  const browsers = new Map<string, { page: Promise<Page>; release: () => void; closed: Promise<unknown> }>();
+  const pageFor = (name: string, main: Page): Promise<Page> => {
+    if (name === 'main') return Promise.resolve(main);
+    const open = browsers.get(name);
+    if (open) return open.page;
+    let release!: () => void;
+    const held = new Promise<void>((r) => (release = r));
+    let resolvePage!: (p: Page) => void;
+    let rejectPage!: (e: unknown) => void;
+    const pagePromise = new Promise<Page>((res, rej) => {
+      resolvePage = res;
+      rejectPage = rej;
+    });
+    const closed = withPage(
+      { prepareContext: prepare, seedStorage, viewport: opts.viewport, engine: opts.engine, locale: opts.locale, timezone: opts.timezone, reducedMotion: opts.reducedMotion },
+      async (p) => {
+        collectFailures(p);
+        resolvePage(p);
+        await held;
+      },
+    ).catch((err) => rejectPage(err));
+    browsers.set(name, { page: pagePromise, release, closed });
+    return pagePromise;
+  };
+  const closeBrowsers = async () => {
+    for (const b of browsers.values()) b.release();
+    await Promise.all([...browsers.values()].map((b) => b.closed));
+    browsers.clear();
+  };
+  // Where each browser's page landed is that browser's own fact. Swapped on every
+  // change of browser, so a goto in B can neither move A's ejection baseline nor
+  // reset A's navigation clock.
+  let currentBrowser = 'main';
+  const navStates = new Map<string, { urlAtLoad: string | null; navActionPending: boolean; onWrongPage: string | null; lastNavAt: number }>();
+  const switchBrowser = (name: string) => {
+    if (name === currentBrowser) return;
+    navStates.set(currentBrowser, { urlAtLoad, navActionPending, onWrongPage, lastNavAt });
+    const next = navStates.get(name) ?? { urlAtLoad: null, navActionPending: false, onWrongPage: null, lastNavAt: Date.now() };
+    ({ urlAtLoad, navActionPending, onWrongPage, lastNavAt } = next);
+    currentBrowser = name;
+  };
+
   // Run a step-list on `page` starting at `startIndex`. Returns whether a
   // non-loop step failed (so the caller can stop THIS sequence).
   async function runSeq(page: Page, steps: FlowStep[], vars: Record<string, unknown>, startIndex: number): Promise<{ failedHere: boolean }> {
@@ -2453,6 +2536,11 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
       const i = idx;
       idx += 1;
       const label = step.label ?? describe(step);
+      // F009.122 — which browser this step runs in. `sp` is the page every line
+      // below acts on; the loop's own `page` is the default browser.
+      const browserName = (step as { browser?: string }).browser ?? 'main';
+      const onBrowser = browserName !== 'main' ? { browser: browserName } : {};
+      let sp: Page = page;
       if (i < from) {
         record({ index: i, type: step.type, label, status: 'skip', testid: testidOf(step), detail: 'resumed past', screenshot: null });
         continue;
@@ -2468,7 +2556,9 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
       // matter most, and a sink scoped to the try is unreachable from the catch.
       const sink: CriticSink = { critic: null };
       try {
-        const out = await execStep(page, step, base, vars, opts.critic ?? 'off', opts.localPath, sink, filledPasswords, notListening);
+        switchBrowser(browserName);
+        sp = await pageFor(browserName, page);
+        const out = 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;
         const via = obj && '__via' in obj ? (obj as { __via: string }).__via : null;
@@ -2490,7 +2580,7 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
         // would call that an ejection on every single run.
         if (formsAVerdict(step.type)) formedAVerdict = true;
         if (NAVIGATES_BY_DESIGN.has(step.type)) {
-          urlAtLoad = safeUrl(page) ?? urlAtLoad;
+          urlAtLoad = safeUrl(sp) ?? urlAtLoad;
           // A goto is already settled — Playwright waited for it. Any OTHER
           // navigating action may commit after it returns, so it leaves a note
           // saying "one URL change after this is mine". See classifyUrlChange.
@@ -2500,7 +2590,7 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
           // under it, that opinion is void — and `page.url()` is a synchronous
           // read of state Playwright already holds, so this costs nothing and
           // adds no polling (the tax AC4 forbids).
-          const verdict = classifyUrlChange({ loaded: urlAtLoad, current: safeUrl(page) ?? urlAtLoad, navActionPending });
+          const verdict = classifyUrlChange({ loaded: urlAtLoad, current: safeUrl(sp) ?? urlAtLoad, navActionPending });
           if (verdict.kind === 'flow-navigation') {
             urlAtLoad = verdict.rebaseTo;
             navActionPending = false;
@@ -2519,6 +2609,7 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
           index: i,
           type: step.type,
           label,
+          ...onBrowser,
           status: 'pass',
           ...navOffset,
           ms_step_duration: Date.now() - stepStartedAt,
@@ -2541,7 +2632,7 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
         const msg = err instanceof Error ? err.message : String(err);
         let shot: Buffer | null = null;
         try {
-          shot = (await takeShot(page, 'viewport', null, 5000)).screenshot;
+          shot = (await takeShot(sp, 'viewport', null, 5000)).screenshot;
         } catch {
           // page may be in a bad state — a missing failure shot is acceptable
         }
@@ -2575,6 +2666,7 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
           index: i,
           type: step.type,
           label,
+          ...onBrowser,
           // Still 'fail' — a broken probe is never less than a failure.
           status: 'fail',
           // F213.11 — on the FAILING step above all: a lost write is exactly where
@@ -2682,7 +2774,15 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
             // cookie read failed — leave authReach null rather than invent a verdict
           }
         }
-        const r = await runSeq(page, flow.steps, {}, 0);
+        let r: { failedHere: boolean };
+        try {
+          r = await runSeq(page, flow.steps, {}, 0);
+        } finally {
+          // F009.122 — the named browsers close with the run, before the default one,
+          // and the end-of-run checks below are about the DEFAULT browser's page.
+          await closeBrowsers();
+          switchBrowser('main');
+        }
         if (r.failedHere) aborted = true; // a TOP-LEVEL step failed → flow aborts
         // ── F213.10 · the window, and why it has to exist at all ──────────────
         //

package/src/mcp.ts

@@ -321,7 +321,7 @@ export const TOOLS = [
       // A hand-written list in a tool description is the only thing most callers
       // ever read, and ours had drifted to 9 of 26: three repos reported an
       // existing verb as missing because of it.
-      `Run an E2E manuscript flow: drive a site step-by-step in one authed page. Steps (${[...STEP_TYPES].length}): ${[...STEP_TYPES].join(' / ')}. testid-anchored steps use [data-testid]; a fill can take valueFrom:{path}|{env} instead of value to type a password without it ever appearing in the run (F009.121, password inputs only); fillSelector/clickSelector use a raw CSS selector + optional cross-origin frame chain to reach a 3rd-party iframe a testid can\'t (e.g. Stripe PCI card fields), and waitForUrl asserts the redirect back to our origin. Stops + pins a screenshot on the first failing step. Returns a per-step report with screenshot_url per step. This is full End-to-End — it can create users, submit forms, complete a Stripe test payment, etc. (set mutates:true for write flows). Scoped to the project slug.`,
+      `Run an E2E manuscript flow: drive a site step-by-step in one authed page — or several: any step may carry browser:"<name>" to run in its own browser (own cookies + storage), opened on first use and kept open beside the default one, so two users can be driven at once (F009.122). Steps (${[...STEP_TYPES].length}): ${[...STEP_TYPES].join(' / ')}. testid-anchored steps use [data-testid]; a fill can take valueFrom:{path}|{env} instead of value to type a password without it ever appearing in the run (F009.121, password inputs only); fillSelector/clickSelector use a raw CSS selector + optional cross-origin frame chain to reach a 3rd-party iframe a testid can\'t (e.g. Stripe PCI card fields), and waitForUrl asserts the redirect back to our origin. Stops + pins a screenshot on the first failing step. Returns a per-step report with screenshot_url per step. This is full End-to-End — it can create users, submit forms, complete a Stripe test payment, etc. (set mutates:true for write flows). Scoped to the project slug.`,
     inputSchema: {
       type: 'object',
       required: ['project', 'flow'],
@@ -373,7 +373,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]" · "- upload [input-testid] = <fixture>" · "- assert: <js>" · "- screenshot label" · frame-aware "- fillSelector <css> = <value> @frame <iframe>" and "- clickSelector <css> @frame <iframe>" · "- waitForUrl <substring>". 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]" · "- upload [input-testid] = <fixture>" · "- 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

@@ -4,7 +4,7 @@
 // login form with a test account, and the only way before was the plaintext
 // password in the manuscript.
 import { readFile } from 'node:fs/promises';
-import { isAbsolute, join } from 'node:path';
+import { resolve, sep } from 'node:path';
 import type { Locator } from 'playwright';
 import { fillAndVerify } from './fill.ts';
 import type { FilledPassword } from './password-in-url.ts';
@@ -13,7 +13,7 @@ import type { ValueFrom } from './flow.ts';
 /** Read the secret. Every error names WHERE it looked and never WHAT it found. */
 export async function readSecret(
   vf: ValueFrom,
-  localPath: string | undefined,
+  secretRoot: string | undefined,
   env: Record<string, string | undefined> = process.env,
 ): Promise<string> {
   if ('env' in vf) {
@@ -21,15 +21,17 @@ export async function readSecret(
     if (!v) throw new Error(`fill valueFrom: env ${vf.env} is not set in the daemon`);
     return v;
   }
-  let p = vf.path;
-  if (!isAbsolute(p)) {
-    // The F009.22 lesson: a relative path resolved against the daemon's own cwd
-    // reads some other repo's file. Relative means "relative to local_path" or
-    // nothing.
-    if (!localPath) {
-      throw new Error(`fill valueFrom: relative path "${p}" needs local_path — it is never resolved against the daemon's own directory`);
-    }
-    p = join(localPath, p);
+  // The file is typed into whatever page the caller named, so it must live
+  // inside a repo the daemon sandbox allows (secretRoot is checked by the
+  // caller) — never anywhere else the daemon user can read. Same containment
+  // rule as an uploadFile fixture.
+  if (!secretRoot) {
+    throw new Error('fill valueFrom {path} needs local_path inside the daemon sandbox — the secret file must live in that repo (use {env} otherwise)');
+  }
+  const root = resolve(secretRoot);
+  const p = resolve(root, vf.path);
+  if (p !== root && !p.startsWith(root + sep)) {
+    throw new Error(`fill valueFrom: path escapes the repo root: ${vf.path}`);
   }
   let raw: string;
   try {
@@ -50,7 +52,7 @@ export async function readSecret(
 export async function fillSecret(
   loc: Locator,
   vf: ValueFrom,
-  localPath: string | undefined,
+  secretRoot: string | undefined,
   timeout: number,
   pwSink: FilledPassword[] | undefined,
   anchor: string,
@@ -64,7 +66,7 @@ export async function fillSecret(
   if (!isPassword) {
     throw new Error('fill valueFrom only fills a password input (type="password") — any other field would show the secret in every later screenshot');
   }
-  const secret = await readSecret(vf, localPath, env);
+  const secret = await readSecret(vf, secretRoot, env);
   try {
     await fillAndVerify(loc, secret, timeout);
   } catch {

package/src/service.ts

@@ -8,6 +8,7 @@
 // dashboard + cc point <img>/links at the daemon, the same way the rest of
 // the SPA already talks to 127.0.0.1:7475.
 
+import { resolveSandboxedPath } from './sandbox.ts';
 import { randomUUID } from 'node:crypto';
 import sharp from 'sharp';
 import { durabilityOf } from './durability.ts';
@@ -299,6 +300,19 @@ function projectLocale(deps: LensDeps, project: string): { locale?: string; time
   return row?.local_path ? manifestLocale(row.local_path, deps.sandboxRoots) : null;
 }
 
+/** F009.121 — the root a `fill valueFrom {path}` may read under: the caller's
+ *  local_path, but only once the daemon sandbox has accepted it. Outside the
+ *  sandbox (or absent) there is no root, so only {env} works — a secret file is
+ *  typed into a page the caller chose, and must not be any file the daemon can read. */
+export function secretRootOf(localPath: string | undefined, sandboxRoots: string[]): string | undefined {
+  if (!localPath) return undefined;
+  try {
+    return resolveSandboxedPath(localPath, sandboxRoots);
+  } catch {
+    return undefined; // refused by the sandbox; fill reports "needs local_path inside the daemon sandbox"
+  }
+}
+
 export function resolveVerifyAuth(
   deps: LensDeps,
   project: string,
@@ -926,6 +940,7 @@ export async function lensRunFlow(deps: LensDeps, input: RunFlowInput) {
     viewport: coerceViewport(input.viewport, input.device),
     critic: input.critic,
     localPath: input.local_path, // F213.6 — sandbox root for uploadFile fixture paths
+    secretRoot: secretRootOf(input.local_path, deps.sandboxRoots), // F009.121
     record: input.record === true, // F255.5 — opt-in .webm of the whole run
     storage: coerceStorageSeed(input.storage), // F074.97 — seed saved client state
   });
@@ -988,6 +1003,7 @@ export async function lensRunManuscript(deps: LensDeps, input: RunManuscriptInpu
     reducedMotion: input.reduced_motion,
     viewport: coerceViewport(input.viewport, input.device), // F252.2 — mobile-only UI E2E in manuscripts
     localPath: input.local_path, // F213.6 — uploadFile fixture root
+    secretRoot: secretRootOf(input.local_path, deps.sandboxRoots), // F009.121
     record: input.record === true, // F255.5 — opt-in .webm of the whole run
     storage: coerceStorageSeed(input.storage), // F074.97 — seed saved client state
   });