@broberg/lens-daemon 0.1.0 → 0.1.6

package/package.json

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

package/src/artifact-backfill.ts

@@ -15,7 +15,7 @@
 import { readdir, stat } from 'node:fs/promises';
 import { join, relative, sep } from 'node:path';
 import type { LensDeps } from './service.ts';
-import { enqueueArtifact, uploadStats } from './artifact-uploads.ts';
+import { SKIP_DIRS, enqueueArtifact, uploadStats } from './artifact-uploads.ts';
 
 export interface SkippedDir {
   /** The directory as it exists on disk. */
@@ -60,28 +60,14 @@ export interface BackfillResult {
  */
 export const DIR_ALIASES: Record<string, string> = {
   xrt81: 'xrt81-com',
-  'broberg-ai': 'broberg-ai-site',
+  // Reversed 2026-10-13: cardmem's project is `broberg-ai` again and
+  // `broberg-ai-site` no longer exists, so rows written under the old alias
+  // are repointed back (4 uploads failed on 2026-09-28 against the dead name).
+  'broberg-ai-site': 'broberg-ai',
   'torrent-search-api': 'moovyy',
 };
 
-/**
- * Directories that are deliberately NOT uploaded, each with the reason it is held back.
- *
- * These are held back BY DECISION. Today they also happen to fail the project lookup,
- * which means they are currently safe by accident — and an accident is not a policy.
- * Naming them here makes the hold-back survive someone later fixing the lookup.
- *
- * `capture-sessions` is Christian's call, given 2026-08-25 when asked directly whether
- * 329 screenshots of him signing in to App Store Connect and Google Play should go to
- * the cloud: "Nej." No credentials are visible in them (all 329 verified as PNG), and
- * they stay on the machine anyway.
- */
-export const SKIP_DIRS: Record<string, string> = {
-  'capture-sessions': "owner decision 2026-08-25: login recordings stay on the Mac",
-  _external: 'screenshots of third-party sites — not this fleet\'s project history',
-  'lens-statepath-test': 'one-off engine test run, not project history',
-  'lens-mint-test': 'one-off engine test run, not project history',
-};
+export { SKIP_DIRS } from './artifact-uploads.ts';
 
 export type Attribution =
   | { kind: 'project'; slug: string }

package/src/artifact-uploads.ts

@@ -49,11 +49,13 @@ export const UPLOAD_QUEUE_DDL = `
 /** Create the queue table if it is not there. Idempotent. */
 export function ensureUploadQueue(db: Database): void {
   db.exec(UPLOAD_QUEUE_DDL);
-  // Additive for daemons whose table predates F276.5.
-  try {
+  // Additive for daemons whose table predates F276.5. Look first rather than
+  // swallow the ALTER's error: a catch-all would also hide a locked or
+  // read-only database, and the drain would then fail later on a column it
+  // believes exists.
+  const cols = db.query('PRAGMA table_info(lens_artifact_uploads)').all() as { name: string }[];
+  if (!cols.some((c) => c.name === 'claimed_at')) {
     db.exec('ALTER TABLE lens_artifact_uploads ADD COLUMN claimed_at INTEGER');
-  } catch {
-    // column already exists
   }
 }
 
@@ -86,12 +88,37 @@ export const MAX_ATTEMPTS = 5;
  * must not create 6588 duplicates on the second pass. Expressing it in the table
  * rather than in a guard means no caller can forget it.
  */
+/**
+ * Directories that are deliberately NOT uploaded, each with the reason it is held back.
+ *
+ * Applied where a file is QUEUED (enqueueArtifact), not only during a backfill —
+ * otherwise a live flow under `_external` would be held back only by the project
+ * lookup failing, which is the accident this list exists to replace (F006.4).
+ *
+ * These are held back BY DECISION. Today they also happen to fail the project lookup,
+ * which means they are currently safe by accident — and an accident is not a policy.
+ * Naming them here makes the hold-back survive someone later fixing the lookup.
+ *
+ * `capture-sessions` is Christian's call, given 2026-08-25 when asked directly whether
+ * 329 screenshots of him signing in to App Store Connect and Google Play should go to
+ * the cloud: "Nej." No credentials are visible in them (all 329 verified as PNG), and
+ * they stay on the machine anyway.
+ */
+export const SKIP_DIRS: Record<string, string> = {
+  'capture-sessions': "owner decision 2026-08-25: login recordings stay on the Mac",
+  _external: 'screenshots of third-party sites — not this fleet\'s project history',
+  'lens-statepath-test': 'one-off engine test run, not project history',
+  'lens-mint-test': 'one-off engine test run, not project history',
+};
+
+
 export function enqueueArtifact(db: Database, projectSlug: string, key: string | null): void {
   if (!key) return;
+  const skipReason = SKIP_DIRS[key.split('/')[0] ?? ''];
   db.prepare(
-    `INSERT OR IGNORE INTO lens_artifact_uploads (artifact_key, project_slug, status, enqueued_at)
-     VALUES (?, ?, 'pending', ?)`,
-  ).run(key, projectSlug, Date.now());
+    `INSERT OR IGNORE INTO lens_artifact_uploads (artifact_key, project_slug, status, enqueued_at, last_error)
+     VALUES (?, ?, ?, ?, ?)`,
+  ).run(key, projectSlug, skipReason ? 'skipped' : 'pending', Date.now(), skipReason ?? null);
 }
 
 /** Queue several at once — the flow path has one per step. */

package/src/auth/index.ts

@@ -19,6 +19,7 @@
 //   - cookieJwt    : a single named cookie holding a JWT. Covers cms.
 
 import { readFileSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
 import type { BrowserContext } from 'playwright';
 
 export type AuthEnv = Record<string, string | undefined>;
@@ -199,6 +200,12 @@ async function applyMintEndpoint(
   // wins over secretEnv. The secret is NOT in the manifest/call, only its source.
   let secret: string | undefined;
   if (cfg.secretPath) {
+    // F009.22 — a relative path here resolves against the DAEMON's cwd, i.e.
+    // some other repo's secret, which would then be sent to the caller's url.
+    // Callers resolve against their project root first (resolveAuthPaths).
+    if (!isAbsolute(cfg.secretPath)) {
+      throw new Error(`mintEndpoint auth: secretPath must be absolute by the time it is read (got "${cfg.secretPath}") — register the project or pass an absolute path`);
+    }
     try {
       secret = readFileSync(cfg.secretPath, 'utf-8').trim();
     } catch (err) {

package/src/flow.ts

@@ -29,6 +29,7 @@ import { takeShot, settleForShot } from './capture.ts';
 import { runCritic, topFindingMessage, type CriticMode, type CriticReport } from './critic.ts';
 import { waitForBuild, observeBuild } from './build-marker.ts';
 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 {
@@ -44,6 +45,11 @@ import {
 /** F255.1 — how a click activates a button. See `clickAndActivate`. */
 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 FlowStep =
   // F074.51 — `timeout` was absent here while every other verb carried it, so a
   // goto's 30s was unoverridable. Found by the typecheck of this card's own
@@ -62,7 +68,7 @@ export type FlowStep =
   // F255.4 — `at` clicks a POINT inside the element ("50%,28%" or "40,120" px)
   // instead of its centre, for canvas/3D surfaces where the centre hits nothing.
   | { type: 'click'; testid?: string; target?: Target; label?: string; timeout?: number; activate?: ActivateMode; at?: string }
-  | { type: 'fill'; testid?: string; target?: Target; value: string; label?: string; timeout?: number }
+  | { type: 'fill'; testid?: string; target?: Target; value?: string; valueFrom?: ValueFrom; label?: string; timeout?: number }
   | { type: 'select'; testid?: string; target?: Target; value: string; label?: string; timeout?: number }
   | { type: 'check'; testid?: string; target?: Target; label?: string; timeout?: number }
   | { type: 'uncheck'; testid?: string; target?: Target; label?: string; timeout?: number }
@@ -439,9 +445,48 @@ function isValidTarget(t: unknown): boolean {
   return keys.length > 0 && keys.every((k) => TARGET_KEYS.includes(k)) && TARGET_LAYERS.some((k) => k in (t as object));
 }
 
+/** F009.119 — the fields each step type uses, beyond the shared ones. Mirrors the
+ *  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 TARGETED = ['testid', 'target'];
+export const STEP_FIELDS: Record<string, string[]> = {
+  goto: ['path'],
+  click: [...TARGETED, 'activate', 'at'],
+  fill: [...TARGETED, 'value', 'valueFrom'],
+  select: [...TARGETED, 'value'],
+  check: TARGETED,
+  uncheck: TARGETED,
+  waitFor: TARGETED,
+  expectText: [...TARGETED, 'text', 'match'],
+  expectVisible: TARGETED,
+  expectEditable: TARGETED,
+  expectAbsent: ['testid'],
+  expectAnimating: [...TARGETED, 'property'],
+  expectStill: [...TARGETED, 'property'],
+  waitForReady: [...TARGETED, 'events'],
+  expectTopmost: TARGETED,
+  fillSelector: ['selector', 'value', 'frame'],
+  clickSelector: ['selector', 'frame', 'at'],
+  waitForBuild: ['sha'],
+  waitForUrl: ['url'],
+  inspect: ['frame', 'html', 'testid'],
+  assert: ['js'],
+  screenshot: [],
+  clear: TARGETED,
+  press: ['key', 'testid'],
+  drag: ['testid', 'toTestid'],
+  uploadFile: ['testid', 'path'],
+  autocomplete: ['testid', 'value', 'option', 'pickText', 'pickIndex'],
+  capture: ['testid', 'as', 'from'],
+  conditional: ['testid', 'present', 'steps'],
+  loop: ['data', 'steps', 'parallel'],
+};
+
 function validateAndNormalizeSteps(steps: unknown[], depth = 0): void {
   if (depth > 3) throw new Error('flow loops nested too deep (max 3)');
-  for (const raw of steps) {
+  for (const [index, raw] of steps.entries()) {
     const s = raw as FlowStep & Record<string, unknown>;
     if (!s || typeof s !== 'object' || !STEP_TYPES.has(s.type)) {
       // F074.50 — name the ones that DO exist. The list is rendered from
@@ -493,6 +538,21 @@ function validateAndNormalizeSteps(steps: unknown[], depth = 0): void {
     if (s.type === 'capture' && typeof (s as { as?: unknown }).as !== 'string') {
       throw new Error('capture step requires a string "as" name');
     }
+    // F009.121 — a fill carries its value inline OR names where to read a secret
+    // from; never both (which one would win is a guess), never neither.
+    if (s.type === 'fill') {
+      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) {
+        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]) {
+          throw new Error('fill valueFrom must be exactly one of {path: "<file>"} or {env: "<NAME>"}');
+        }
+      }
+    }
     // F074.23 — single-anchor steps accept a string testid OR a self-healing
     // `target` (LocateSpec); the rest still require a string testid.
     const targetable = ['click', 'fill', 'select', 'check', 'uncheck', 'waitFor', 'expectText', 'expectVisible', 'expectEditable', 'expectTopmost', 'clear', 'waitForReady', 'expectAnimating', 'expectStill'];
@@ -564,6 +624,15 @@ function validateAndNormalizeSteps(steps: unknown[], depth = 0): void {
     ) {
       throw new Error(`${s.type} step frame must be a string or string[]`);
     }
+    // Checked LAST, so a step missing its required field keeps the message that
+    // names that field — the more useful one when both are wrong.
+    const allowed = [...SHARED_STEP_FIELDS, ...(STEP_FIELDS[s.type] ?? [])];
+    const unknown = Object.keys(s).filter((k) => !allowed.includes(k));
+    if (unknown.length > 0) {
+      throw new Error(
+        `step ${index} (${s.type}${depth > 0 ? `, nested depth ${depth}` : ''}): unknown field ${unknown.map((k) => JSON.stringify(k)).join(', ')} — ${s.type} accepts: ${allowed.filter((k) => k !== 'type').join(', ')}`,
+      );
+    }
   }
 }
 
@@ -842,6 +911,13 @@ function parseManuscriptStep(s: string): FlowStep {
     case 'expectabsent': return { type: 'expectAbsent', testid: testid() };
     case 'expecttopmost': return { type: 'expectTopmost', testid: testid() };
     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.
+      const from = s.match(/\]\s+from\s+(file|env)\s+(\S.*)$/i);
+      if (from) {
+        const src = from[2]!.trim();
+        return { type: 'fill', testid: testid(), valueFrom: from[1]!.toLowerCase() === 'file' ? { path: src } : { env: src } };
+      }
       const v = s.split('=').slice(1).join('=').trim();
       return { type: 'fill', testid: testid(), value: v };
     }
@@ -1591,7 +1667,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);
@@ -1629,7 +1705,11 @@ async function execStep(page: Page, step: FlowStep, base: string, vars: Record<s
       // 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.
-      const filledValue = subst(step.value, vars);
+      if (step.valueFrom) {
+        await fillSecret(loc, step.valueFrom, secretRoot, remaining, pwSink, anchorOf(step));
+        return via ? { __via: via } : null;
+      }
+      const filledValue = subst(step.value ?? '', vars);
       await fillAndVerify(loc, filledValue, remaining);
       // F074.99 — remember a PASSWORD so the end of the run can notice it coming
       // back in the URL. Read from the element rather than guessed from the name:
@@ -2061,7 +2141,11 @@ async function execStep(page: Page, step: FlowStep, base: string, vars: Record<s
           )
             .slice(0, 60)
             .map(pick);
-          return JSON.stringify({ iframes, inputs, clickables });
+          // F009.119 — name the full-HTML option where the truncation is seen: two
+          // sessions in two days worked around the 400-char cut without knowing
+          // `html:true` existed.
+          const hint = "each element's html is cut at 400 chars; for one element's FULL outerHTML use {type:'inspect', html:true, testid}";
+          return JSON.stringify({ hint, iframes, inputs, clickables });
         }, undefined, { timeout: stepTimeout(step) });
       return { __inspect: String(dump) };
     }
@@ -2123,6 +2207,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. */
@@ -2384,7 +2474,7 @@ 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);
+        const out = await execStep(page, 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;

package/src/gate.ts

@@ -11,10 +11,10 @@
 //      selector instead of a testid is a CONVENTION WARNING (migrate it).
 //
 //   2. decideVerdict() — fold the catalogue result + the anchor report into a
-//      single green/red verdict + an action. F073's review loop OWNS the
-//      execution (auto-merge the PR on green; open a GitHub issue + ping
-//      Discord on red) since it holds the PR + dispatch context; this module
-//      produces the decision it acts on.
+//      single green/red verdict + an action. This module only DECIDES; nothing
+//      here executes it. Today POST /lens/gate returns it as JSON, and cardmem's
+//      F095 Full Auto Review is what moves a green card to Done. A notice on a
+//      red verdict is not built — that is F009.120.
 
 import type { LensManifest } from './manifest.ts';
 

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]; 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. 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" · "- 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>". 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

@@ -0,0 +1,82 @@
+// F009.121 — fill a password field from a file or env var, without the secret
+// ever appearing in the manuscript, the step label, the run report or the stored
+// row. Asked for by scout (F001.4) and broberg-id (F084.97): both prove a real
+// 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 { 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';
+
+/** Read the secret. Every error names WHERE it looked and never WHAT it found. */
+export async function readSecret(
+  vf: ValueFrom,
+  secretRoot: string | undefined,
+  env: Record<string, string | undefined> = process.env,
+): Promise<string> {
+  if ('env' in vf) {
+    const v = env[vf.env];
+    if (!v) throw new Error(`fill valueFrom: env ${vf.env} is not set in the daemon`);
+    return v;
+  }
+  // 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 {
+    raw = await readFile(p, 'utf-8');
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException)?.code ?? 'unreadable';
+    throw new Error(`fill valueFrom: could not read ${p} (${code})`);
+  }
+  // One trailing newline is an editor's, not the password's. vault-get.sh writes
+  // byte-exact, so this only ever removes something a human added.
+  const v = raw.replace(/\r?\n$/, '');
+  if (!v) throw new Error(`fill valueFrom: ${p} is empty`);
+  return v;
+}
+
+/** Type the secret into a PASSWORD field and prove it landed — reporting only
+ *  the shape of a mismatch, never characters. */
+export async function fillSecret(
+  loc: Locator,
+  vf: ValueFrom,
+  secretRoot: string | undefined,
+  timeout: number,
+  pwSink: FilledPassword[] | undefined,
+  anchor: string,
+  env: Record<string, string | undefined> = process.env,
+): Promise<void> {
+  // A password input masks itself in every screenshot. Any other field would
+  // print the secret into the next still, so it is refused rather than filled.
+  const isPassword = await loc
+    .evaluate((el) => (el as HTMLInputElement).type === 'password', undefined, { timeout })
+    .catch(() => false);
+  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, secretRoot, env);
+  try {
+    await fillAndVerify(loc, secret, timeout);
+  } catch {
+    // fillAndVerify's message quotes expected and actual values. For a secret
+    // that IS the leak, so only the length is reported.
+    const got = await loc.inputValue({ timeout: 1000 }).catch(() => null);
+    throw new Error(
+      `fill did not land: expected ${secret.length} characters, the field holds ${got === null ? 'an unreadable value' : `${got.length}`} (value withheld — it is a secret)`,
+    );
+  }
+  // F074.99 — the password-in-URL check still sees it, in memory only.
+  pwSink?.push({ anchor, value: secret });
+}

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,
@@ -308,7 +322,17 @@ export function resolveVerifyAuth(
   const row = deps.db
     .query('SELECT local_path FROM registered_projects WHERE slug = ?')
     .get(project) as { local_path: string } | undefined;
-  if (!row?.local_path) return auth;
+  if (!row?.local_path) {
+    // F009.22 — a RELATIVE credential path with no registered project would be
+    // resolved against the daemon's own cwd, i.e. read another repo's secret
+    // and send it to whatever url the caller named. Refuse instead.
+    if (resolveAuthPaths(auth, '/') !== auth) {
+      throw new Error(
+        `project "${project}" is not registered, so a relative ${auth.adapter === 'storageState' ? 'statePath' : 'secretPath'} cannot be resolved — register the project or pass an absolute path`,
+      );
+    }
+    return auth;
+  }
   return (resolveAuthPaths(auth, row.local_path) as AuthConfig | undefined) ?? auth;
 }
 
@@ -916,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
   });
@@ -978,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
   });