@broberg/lens-daemon 0.1.11 → 0.1.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@broberg/lens-daemon",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "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-engine": "0.13.0",
-    "@broberg/lens-svg": "0.1.0"
+    "@broberg/lens-svg": "0.1.0",
+    "@broberg/lens-engine": "0.13.0"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.10.6",

package/src/extension-flow.ts

@@ -0,0 +1,82 @@
+// F009.125 — what a flow needs around an extension build: which popup to open,
+// and (only when asked) a temporary copy of the build that may read the page.
+//
+// MEASURED before this file existed (Jam Clipper's real dist/, M1, 15 Oct 2026):
+//   · a popup opened as its own tab sees the TARGET tab as active once the target
+//     is brought to the front (tabs.query → the target's id, not its own);
+//   · chrome.scripting.executeScript on that tab FAILS without the toolbar gesture:
+//     "Cannot access contents of the page. Extension manifest must request
+//      permission to access the respective host."
+//   · the same call SUCCEEDS on a copy whose manifest adds host access.
+// A headless run cannot press the toolbar button, so `activeTab` can never be
+// granted the way a person grants it. The copy is the honest substitute — and it
+// is opt-in and reported, because a simulated permission must not read as the
+// real gesture.
+
+import { cp, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+interface Manifest {
+  manifest_version?: number;
+  action?: { default_popup?: string };
+  browser_action?: { default_popup?: string };
+  host_permissions?: string[];
+  permissions?: string[];
+}
+
+async function readManifest(dir: string): Promise<Manifest> {
+  let raw: string;
+  try {
+    raw = await readFile(join(dir, 'manifest.json'), 'utf8');
+  } catch {
+    throw new Error(
+      `extension.path ${dir} has no manifest.json — point it at the UNPACKED build directory (e.g. dist/), not the source or a .zip`,
+    );
+  }
+  return JSON.parse(raw) as Manifest;
+}
+
+/** The popup page an `openPopup` step opens when it names none: the one Chrome
+ *  opens on the toolbar click (MV3 `action`, MV2 `browser_action`). */
+export async function defaultPopupOf(dir: string): Promise<string> {
+  const m = await readManifest(dir);
+  const p = m.action?.default_popup ?? m.browser_action?.default_popup;
+  if (!p) {
+    throw new Error(
+      'openPopup: the manifest declares no action.default_popup — name the page with openPopup {path: "…"}',
+    );
+  }
+  return p.replace(/^\/+/, '');
+}
+
+export interface PreparedExtension {
+  /** The directory Chromium loads — the original, or the temporary copy. */
+  dir: string;
+  /** True when host access was added to a copy rather than granted by a gesture. */
+  simulated: boolean;
+  cleanup: () => Promise<void>;
+}
+
+/** The build as-is, or — when `grantHostAccess` — a TEMPORARY COPY whose manifest
+ *  may read every page, standing in for the toolbar gesture a headless run cannot
+ *  make. The original directory is never written to. */
+export async function prepareExtension(path: string, grantHostAccess: boolean): Promise<PreparedExtension> {
+  const manifest = await readManifest(path);
+  if (!grantHostAccess) return { dir: path, simulated: false, cleanup: async () => {} };
+  const dir = await mkdtemp(join(tmpdir(), 'lens-ext-copy-'));
+  await cp(path, dir, { recursive: true });
+  const hostPermissions = [...new Set([...(manifest.host_permissions ?? []), '<all_urls>'])];
+  // MV2 has no host_permissions key; host access lives in `permissions` there.
+  const next: Manifest =
+    manifest.manifest_version === 2
+      ? { ...manifest, permissions: [...new Set([...(manifest.permissions ?? []), '<all_urls>'])] }
+      : { ...manifest, host_permissions: hostPermissions };
+  await writeFile(join(dir, 'manifest.json'), JSON.stringify(next, null, 2));
+  return { dir, simulated: true, cleanup: () => rm(dir, { recursive: true, force: true }) };
+}
+
+/** The one line every report that used the copy carries. */
+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';

package/src/flow-store.ts

@@ -19,6 +19,8 @@ export interface StoredFlowStep {
   label: string;
   /** F009.122 — the named browser the step ran in; absent = the default one. */
   browser?: string;
+  /** F009.125 — the step ran in the extension popup. */
+  in?: 'popup';
   status: 'pass' | 'fail' | 'skip';
   testid: string | null;
   detail: string | null;
@@ -86,6 +88,7 @@ export async function recordFlowRun(
       label: s.label,
       // F009.122 — third-place rule: a field only flow.ts knows reaches nobody.
       ...(s.browser ? { browser: s.browser } : {}),
+      ...(s.in ? { in: s.in } : {}),
       status: s.status,
       testid: s.testid,
       detail: s.detail,
@@ -148,6 +151,10 @@ export async function recordFlowRun(
     // findings were produced in flow.ts and written nowhere until fd-sundhed
     // measured it from a consumer's seat: correct instrument, nobody told.
     findings_json: JSON.stringify({
+      // F009.125 — which extension the run loaded, and whether its host access was
+      // simulated. Kept with the findings because a simulated permission is
+      // something a reader must see before trusting the green.
+      ...(result.extension ? { extension: result.extension } : {}),
       ...(result.password_in_url ? { password_in_url: result.password_in_url } : {}),
       ...(result.not_listening ? { not_listening: result.not_listening } : {}),
     }),

package/src/flow.ts

@@ -14,7 +14,7 @@
 import nodePath from 'node:path';
 import { mkdtemp, readFile, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import type { Locator, Page } from 'playwright';
+import type { BrowserContext, Locator, Page } from 'playwright';
 import {
   resolveTarget,
   isEditableElement,
@@ -24,6 +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 { 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';
@@ -153,7 +154,11 @@ export type FlowStep =
   | { type: 'autocomplete'; testid: string; value: string; option: string; pickText?: string; pickIndex?: number; label?: string; timeout?: number }
   | { type: 'capture'; testid: string; as: string; from?: 'text' | 'value'; label?: string; timeout?: number }
   | { type: 'conditional'; testid: string; present: boolean; steps: FlowStep[]; label?: string; timeout?: number }
-  | { type: 'loop'; data: Array<Record<string, unknown>>; steps: FlowStep[]; label?: string; parallel?: number };
+  | { type: 'loop'; data: Array<Record<string, unknown>>; steps: FlowStep[]; label?: string; parallel?: number }
+  // 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 };
 
 export interface Flow {
   name: string;
@@ -171,9 +176,19 @@ export interface Flow {
    *  ejecting us. Default {@link DEFAULT_EJECT_GRACE_MS}; 0 opts out. Raise it
    *  for an app whose auth check is slow (fd-sundhed's bounced at ~3.6s). */
   eject_grace_ms?: number;
+  /** F009.125 — run the whole flow in a Chromium with this UNPACKED extension
+   *  loaded. `grant_host_access` loads a temporary copy that may read every page,
+   *  standing in for the toolbar click (activeTab) a headless run cannot make;
+   *  the original build is never written, and the report says it was simulated. */
+  extension?: FlowExtension;
   steps: FlowStep[];
 }
 
+export interface FlowExtension {
+  path: string;
+  grant_host_access?: boolean;
+}
+
 /**
  * MEASURED, not chosen. Against a fixture that bounces 800ms after load:
  *
@@ -242,6 +257,8 @@ export interface FlowStepResult {
   label: string;
   /** F009.122 — the named browser this step ran in. Absent = the default one. */
   browser?: string;
+  /** F009.125 — present when the step ran in the extension popup. */
+  in?: 'popup';
   status: 'pass' | 'fail' | 'skip';
   testid: string | null;
   detail: string | null;
@@ -336,6 +353,9 @@ export class InstrumentError extends Error {
 }
 
 export interface FlowResult {
+  /** 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;
   name: string;
   status: 'pass' | 'fail' | 'error';
   steps: FlowStepResult[];
@@ -403,6 +423,8 @@ export const STEP_TYPES = new Set([
   'waitForBuild',
   // F213.8 — readiness gate (the page is listening, not just painted)
   'waitForReady',
+  // F009.125 — drive a loaded extension's popup
+  'openPopup',
 ]);
 
 /** Validate + normalise an untrusted flow (HTTP/MCP boundary). Throws on the
@@ -429,7 +451,25 @@ export function parseFlow(input: unknown): Flow {
   if (f.eject_grace_ms !== undefined && (typeof f.eject_grace_ms !== 'number' || !Number.isFinite(f.eject_grace_ms) || f.eject_grace_ms < 0)) {
     throw new Error('flow.eject_grace_ms must be a non-negative number of milliseconds');
   }
+  // F009.125 — refused when malformed rather than dropped: before this, an unknown
+  // flow-level key vanished in silence, so `extension` would have run the flow
+  // WITHOUT the extension and reported green about a page the extension never saw.
+  let extension: FlowExtension | undefined;
+  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 (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 } : {}) };
+  }
   validateAndNormalizeSteps(f.steps);
+  if (!extension && usesPopup(f.steps as FlowStep[])) {
+    throw new Error('openPopup / in:"popup" need flow.extension — there is no extension loaded to open a popup from');
+  }
   return {
     name: f.name.trim(),
     base_url: f.base_url,
@@ -437,10 +477,20 @@ export function parseFlow(input: unknown): Flow {
     mutates: f.mutates === true,
     ...(f.wait_for_build !== undefined ? { wait_for_build: f.wait_for_build } : {}),
     ...(f.eject_grace_ms !== undefined ? { eject_grace_ms: f.eject_grace_ms } : {}),
+    ...(extension ? { extension } : {}),
     steps: f.steps as FlowStep[],
   };
 }
 
+function usesPopup(steps: FlowStep[]): boolean {
+  return steps.some(
+    (st) =>
+      st.type === 'openPopup' ||
+      (st as { in?: string }).in === 'popup' ||
+      ((st.type === 'loop' || st.type === 'conditional') && usesPopup(st.steps)),
+  );
+}
+
 // F074.23 — light structural check for a self-healing `target` at the HTTP/MCP
 // boundary (the daemon stays zod-free in this validator; the engine's
 // resolveTarget does the real resolution at run time). A bare string is the
@@ -458,7 +508,7 @@ 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', 'browser'];
+const SHARED_STEP_FIELDS = ['type', 'label', 'timeout', 'timeout_ms', 'browser', 'in'];
 
 /** 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
@@ -500,6 +550,7 @@ export const STEP_FIELDS: Record<string, string[]> = {
   capture: ['testid', 'as', 'from'],
   conditional: ['testid', 'present', 'steps'],
   loop: ['data', 'steps', 'parallel'],
+  openPopup: ['path'],
 };
 
 function validateAndNormalizeSteps(steps: unknown[], depth = 0, inParallel = false): void {
@@ -560,6 +611,28 @@ function validateAndNormalizeSteps(steps: unknown[], depth = 0, inParallel = fal
         throw new Error(`step ${index} (${s.type}): browser is not allowed inside a parallel loop — each iteration already runs in its own browser`);
       }
     }
+    // F009.125 — `in: "popup"` runs a step in the extension popup an earlier
+    // openPopup opened. Refused where it cannot mean anything, the same way
+    // `browser` is: the popup lives in the main browser only.
+    if ('in' in s) {
+      const where = (s as { in?: unknown }).in;
+      if (where !== 'popup') throw new Error(`step ${index} (${s.type}): in must be "popup", got ${JSON.stringify(where)}`);
+      if (s.type === 'loop' || s.type === 'conditional' || s.type === 'openPopup') {
+        throw new Error(`step ${index} (${s.type}): in:"popup" goes on the steps that act in the popup, not on a ${s.type}`);
+      }
+      const b = (s as { browser?: unknown }).browser;
+      if (b !== undefined && b !== 'main') {
+        throw new Error(`step ${index} (${s.type}): in:"popup" and browser:${JSON.stringify(b)} cannot be combined — the extension is loaded in the main browser only`);
+      }
+      if (inParallel) throw new Error(`step ${index} (${s.type}): in:"popup" is not allowed inside a parallel loop`);
+    }
+    if (s.type === 'openPopup') {
+      const pth = (s as { path?: unknown }).path;
+      if (pth !== undefined && (typeof pth !== 'string' || !pth || pth.includes('..') || /^[a-z]+:/i.test(pth))) {
+        throw new Error(`step ${index} (openPopup): path must be a page inside the extension, like "popup.html"`);
+      }
+      if ('browser' in s || inParallel) throw new Error(`step ${index} (openPopup): the popup opens in the main browser only`);
+    }
     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');
@@ -1291,6 +1364,7 @@ function describe(step: FlowStep): string {
     case 'capture': return `capture ${step.testid} → {{${step.as}}}`;
     case 'conditional': return `${step.present ? 'if' : 'unless'} [${step.testid}]`;
     case 'loop': return 'loop';
+    case 'openPopup': return `openPopup ${step.path ?? '(manifest popup)'}`;
     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).
@@ -2253,6 +2327,8 @@ async function execStep(page: Page, step: FlowStep, base: string, vars: Record<s
       throw new Error('conditional steps are handled by runSeq, never execStep');
     case 'loop':
       throw new Error('loop steps are flattened before execution');
+    case 'openPopup':
+      throw new Error('openPopup steps are handled by runSeq, never execStep');
   }
 }
 
@@ -2585,7 +2661,11 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
       // 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 } : {};
+      // F009.125 — a popup step says so in the report, the same way a named browser does.
+      const onBrowser = {
+        ...(browserName !== 'main' ? { browser: browserName } : {}),
+        ...((step as { in?: string }).in === 'popup' ? { in: 'popup' as const } : {}),
+      };
       let sp: Page = page;
       if (i < from) {
         record({ index: i, type: step.type, label, status: 'skip', testid: testidOf(step), detail: 'resumed past', screenshot: null });
@@ -2604,7 +2684,16 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
       try {
         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);
+        if ((step as { in?: string }).in === 'popup') {
+          if (!extCtx?.popup) throw new Error('in:"popup" before any openPopup step — open the popup first');
+          sp = extCtx.popup;
+          // Keep the page under test the extension's active tab while the popup is driven.
+          await extCtx.main.bringToFront();
+        }
+        const out =
+          step.type === 'openPopup'
+            ? await openPopup(step)
+            : 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;
@@ -2754,6 +2843,22 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
 
   const videoDir = opts.record ? await mkdtemp(nodePath.join(tmpdir(), 'lens-flow-video-')) : null;
   let videoPage: Page | null = null;
+  // F009.125 — set once the extension's browser is up; read by openPopup / in:"popup".
+  let extCtx: { context: BrowserContext; id: string; main: Page; popup: Page | null } | null = null;
+  let extensionInfo: FlowResult['extension'] = null;
+  const prepared = flow.extension ? await prepareExtension(flow.extension.path, flow.extension.grant_host_access === true) : null;
+  const openPopup = async (step: Extract<FlowStep, { type: 'openPopup' }>): Promise<null> => {
+    if (!extCtx || !flow.extension || !prepared) throw new Error('openPopup needs flow.extension');
+    const path = step.path ?? (await defaultPopupOf(prepared.dir));
+    const popup = await extCtx.context.newPage();
+    collectFailures(popup);
+    await popup.goto(`chrome-extension://${extCtx.id}/${path}`, { timeout: stepTimeout(step) });
+    // MEASURED: with the page under test back in front, the popup's
+    // tabs.query({active, currentWindow}) answers with THAT tab, as on a real click.
+    await extCtx.main.bringToFront();
+    extCtx.popup = popup;
+    return null;
+  };
   const readVideo = async (): Promise<Buffer | null> => {
     if (!videoDir) return null;
     try {
@@ -2778,6 +2883,7 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       skipFill(flow.steps, 0, {}, 'skipped — the build under test never went live');
+      await prepared?.cleanup();
       return {
         name: flow.name,
         status: 'error',
@@ -2801,10 +2907,20 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
         timezone: opts.timezone,
         reducedMotion: opts.reducedMotion,
         ...(videoDir ? { recordVideoDir: videoDir } : {}),
+        ...(prepared ? { extension: { path: prepared.dir } } : {}),
       },
-      async (page, context) => {
+      async (page, context, ext) => {
         videoPage = page;
         collectFailures(page);
+        if (ext && flow.extension && prepared) {
+          extCtx = { context, id: ext.id, main: page, popup: null };
+          extensionInfo = {
+            id: ext.id,
+            path: flow.extension.path,
+            host_access: prepared.simulated ? 'simulated' : 'as-built',
+            ...(prepared.simulated ? { note: SIMULATED_ACCESS_NOTE } : {}),
+          };
+        }
         // F074.36 — measure the credential BEFORE driving, so a run that cannot
         // possibly be authenticated says so instead of producing a confident
         // verdict about a login screen. Only when auth was actually requested:
@@ -2902,10 +3018,13 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
     reason = reason ?? (err instanceof Error ? err.message : String(err));
     // Keep the recording even on a crash — watching HOW it broke is the whole point.
     const video = await readVideo();
-    return { 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 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' };
   }
 
   const video = await readVideo();
+  // F009.125 — the temporary copy (if any) is ours alone; the original is never touched.
+  await prepared?.cleanup();
   results.sort((a, b) => a.index - b.index);
   const anyFail = results.some((s) => s.status === 'fail');
   const baseReason = reason ?? (aborted ? 'flow aborted on a top-level failure' : null);
@@ -2953,6 +3072,7 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
     // ASKED for, defaulted the same way the context does, so the report and the
     // context can never disagree about it.
     reduced_motion: opts.reducedMotion ?? 'reduce',
+    ...(extensionInfo ? { extension: extensionInfo } : {}),
   };
 }
 

package/src/mcp.ts

@@ -360,10 +360,20 @@ export const TOOLS = [
                 'F255.7 — do not start until the app is serving the build under test. A commit sha waits for THAT build; true waits for any change from the build live at run start. Polls GET /api/health for a `build` field (the fleet contract), from the runner with no-store, requiring 3 consecutive matching reads so a fleet mid-rollout cannot end the wait early. Fails loudly if the app exposes no marker. Use it right after a deploy — otherwise a green run may be verifying the build you just replaced.',
             },
             auth: authSchema,
+            extension: {
+              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.',
+              properties: {
+                path: { type: 'string' },
+                grant_host_access: { type: 'boolean' },
+              },
+            },
             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.' } } },
+              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).' } } },
             },
           },
         },

package/src/service.ts

@@ -684,6 +684,7 @@ export function flowRunView(row: LensFlowRunRow, port: number) {
     status: s.status,
     // F009.122 — which named browser ran the step. Absent = the default one.
     ...(s.browser ? { browser: s.browser } : {}),
+    ...(s.in ? { in: s.in } : {}),
     testid: s.testid,
     detail: s.detail,
     ...(s.fault ? { fault: s.fault } : {}),
@@ -929,6 +930,15 @@ export async function runFlatFlow(deps: LensDeps, input: FlatFlowInput) {
 export async function lensRunFlow(deps: LensDeps, input: RunFlowInput) {
   const project = requireProject(input.project);
   const flow = parseFlow(input.flow);
+  // F009.125 — an extension build is loaded into a real browser (and, with
+  // grant_host_access, may read every page), so its directory must be inside the
+  // daemon sandbox like any other repo path. Relative = relative to local_path.
+  if (flow.extension) {
+    const raw = flow.extension.path;
+    const abs = raw.startsWith('/') ? raw : input.local_path ? `${input.local_path.replace(/\/$/, '')}/${raw}` : null;
+    if (!abs) throw new Error('flow.extension.path is relative — pass local_path, or give an absolute path');
+    flow.extension = { ...flow.extension, path: resolveSandboxedPath(abs, deps.sandboxRoots) };
+  }
   // F082.6 — auth reaches flows: own auth (relative paths resolved) or inherit
   // the manifest's. Fixes the blocker where authed routes redirected to login.
   // F074.36 — and the run now REPORTS which of those two it used, or why neither.