@broberg/lens-daemon 0.0.0-stage → 0.1.0

package/src/critic-vision.ts

@@ -0,0 +1,205 @@
+// F126.2 — Vision composition critic (the model half).
+//
+// The complement to the deterministic geometry critic (critic-dom.ts). Geometry
+// catches what you can MEASURE — overlap, occlusion, clipped text, off-viewport,
+// contrast. Vision catches what you can only JUDGE — "this looks broken /
+// unbalanced / off-brand / illegible on a busy background / wrong hierarchy."
+//
+// It costs a metered model call per screenshot (@broberg/ai-sdk, Haiku vision —
+// cheapest-good-enough), so it is PER-PROJECT OPT-IN: the caller only invokes it
+// when projects.settings_json.composition_critic.vision === true (F126.3). This
+// module makes a call ONLY when asked; it never runs itself.
+
+import type { CriticSeverity } from './critic-dom.ts';
+
+export interface VisionFinding {
+  kind: 'vision';
+  severity: CriticSeverity;
+  /** Roughly where on the screen ("top-right", "the header", "primary button"). */
+  region: string;
+  message: string;
+}
+
+export interface VisionCriticResult {
+  findings: VisionFinding[];
+  /** Why the pass produced nothing actionable, if so: 'no-ai' (no key) | 'error'. */
+  skipped?: 'no-ai' | 'error';
+  /** Concrete model used, for the run report. */
+  model?: string;
+}
+
+// The free vision-model selector. A catalog key; resolved to a concrete route.
+export type VisionModelKey = string;
+
+export interface VisionModelSpec {
+  key: VisionModelKey;
+  label: string;
+  provider: string;
+  model: string;
+  transport: 'http';
+  inputPer1M: number;
+  outputPer1M: number;
+  /** EU-hosted → GDPR-safe for screenshots that may carry PII. */
+  eu: boolean;
+  /** Provider key(s); ANY present → the model is available. */
+  requiredEnvAny: string[];
+}
+
+// Default = mistral-large: EU/GDPR-safe (Lens screenshots can carry PII —
+// usernames/emails on authed screens) + cheap + functional. Geometry already
+// owns spatial overlaps (free, exact), so vision is the soft aesthetic bonus.
+// mistral-small = cheapest EU but weaker. NO paid-Anthropic route (house rule —
+// the haiku/sonnet options were removed 2026-06-30 with the API-key purge).
+// (Validated 2026-06-11 vs the ✕-over-badge + a fuzzy-aesthetic case; Christian
+// chose mistral-large. magistral-medium errored/empties → excluded; ai.chat +
+// system-role beat ai.vision prompt-only for instruction-following → kept.)
+// F008.28 — dated ids, never `-latest` (D-385d97): the same ids @broberg/ai-sdk
+// pins its smart/cheap tiers to, with its prices. vision-models-pinned.test.ts holds it.
+export const VISION_MODELS: VisionModelSpec[] = [
+  { key: 'mistral-large', label: 'Mistral Large (EU · GDPR-safe)', provider: 'mistral', model: 'mistral-large-2512', transport: 'http', inputPer1M: 0.5, outputPer1M: 1.5, eu: true, requiredEnvAny: ['MISTRAL_API_KEY'] },
+  { key: 'mistral-small', label: 'Mistral Small (EU · cheapest)', provider: 'mistral', model: 'mistral-small-2603', transport: 'http', inputPer1M: 0.15, outputPer1M: 0.6, eu: true, requiredEnvAny: ['MISTRAL_API_KEY'] },
+];
+
+export const DEFAULT_VISION_MODEL: VisionModelKey = 'mistral-large';
+
+function specFor(key: VisionModelKey | undefined): VisionModelSpec {
+  return VISION_MODELS.find((m) => m.key === key) ?? VISION_MODELS.find((m) => m.key === DEFAULT_VISION_MODEL)!;
+}
+function envPresent(spec: VisionModelSpec): boolean {
+  return spec.requiredEnvAny.some((e) => !!process.env[e]);
+}
+/** The chosen model if its key is armed, else the cheapest available (so a pick
+ *  whose provider key isn't set still produces findings rather than skipping). */
+function resolveSpec(key: VisionModelKey | undefined): VisionModelSpec | null {
+  const chosen = specFor(key);
+  if (envPresent(chosen)) return chosen;
+  return VISION_MODELS.filter(envPresent).sort((a, b) => a.inputPer1M - b.inputPer1M)[0] ?? null;
+}
+
+/** Catalog + per-model availability — single source for the Settings selector. */
+export function listVisionModels() {
+  return {
+    default: DEFAULT_VISION_MODEL,
+    models: VISION_MODELS.map((m) => ({
+      key: m.key,
+      label: m.label,
+      eu: m.eu,
+      input_per_m: m.inputPer1M,
+      output_per_m: m.outputPer1M,
+      available: envPresent(m),
+    })),
+  };
+}
+
+const SYSTEM = [
+  'You are a UI composition critic. You are shown ONE screenshot of a single app screen.',
+  'Report ONLY genuine VISUAL composition problems a careful designer would flag:',
+  'overlapping or colliding elements, a control sitting on top of text, text that is',
+  'clipped / truncated / unreadable, content cut off or off-screen, low contrast,',
+  'broken visual hierarchy, or anything that plainly "looks broken".',
+  'Do NOT comment on content, wording, taste, or features. If the screen looks',
+  'coherent, return an empty list. Be terse and concrete.',
+].join(' ');
+
+const PROMPT = [
+  'Return ONLY a JSON object, no prose, no markdown fence:',
+  '{"findings":[{"severity":"high|medium|low","region":"<short where>","issue":"<short what>"}]}',
+  'high = a real defect that blocks shipping (text hidden, control unusable, content cut off).',
+  'medium = noticeable but not blocking. low = minor polish.',
+  'Empty findings array if the composition holds together.',
+].join(' ');
+
+// Lazy, daemon-local AI client. Dynamic import so an absent/broken SDK can never
+// crash the daemon — the caller just gets `skipped:'no-ai'`. Mirrors the
+// mcp-tools getCardmemAi() builder; the daemon stands up its own (no cross-dep).
+let aiPromise: Promise<{ chat?: (req: unknown) => Promise<{ text: string; usage: { model: string } }> } | null> | undefined;
+function getDaemonAi() {
+  if (!aiPromise) {
+    aiPromise = (async () => {
+      try {
+        const sdk = await import('@broberg/ai-sdk');
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const providers: Record<string, any> = {};
+        // Mistral (EU) is the DEFAULT vision provider (screenshots can carry PII).
+        if (process.env.MISTRAL_API_KEY) providers.mistral = sdk.mistralAdapter({ apiKey: process.env.MISTRAL_API_KEY });
+        // OpenRouter = transport for the Gemini last-resort fallback only (never default).
+        if (process.env.OPENROUTER_API_KEY) providers.openrouter = sdk.openrouterAdapter({ apiKey: process.env.OPENROUTER_API_KEY });
+        if (Object.keys(providers).length === 0) return null;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return sdk.createAI({ providers: providers as any }) as any;
+      } catch {
+        return null;
+      }
+    })();
+  }
+  return aiPromise;
+}
+
+/** Run the vision critic over a PNG screenshot. Makes exactly one model call.
+ *  Only call this when the project has opted into vision (F126.3). */
+export async function runVisionCritic(
+  screenshot: Buffer,
+  opts: { purpose?: string; model?: VisionModelKey } = {},
+): Promise<VisionCriticResult> {
+  const ai = await getDaemonAi();
+  const spec = resolveSpec(opts.model);
+  if (!ai || !ai.chat || !spec) return { findings: [], skipped: 'no-ai' };
+  // Mistral (EU) is the default; Gemini-via-OpenRouter is the last-resort fallback
+  // only (never default), used if the EU primary errors.
+  const fallback =
+    process.env.OPENROUTER_API_KEY && spec.provider !== 'openrouter'
+      ? [{ provider: 'openrouter', model: 'google/gemini-2.5-flash', transport: 'http' }]
+      : [];
+  try {
+    // ai.chat with a system role beats ai.vision (prompt-only) for this
+    // instruction-heavy critic task (validated 2026-06-11) — keep ai.chat.
+    const res = await ai.chat({
+      system: SYSTEM,
+      messages: [
+        {
+          role: 'user',
+          content: [
+            { type: 'text', text: PROMPT },
+            { type: 'image', image: screenshot, mimeType: 'image/png' },
+          ],
+        },
+      ],
+      override: { provider: spec.provider, model: spec.model, transport: spec.transport },
+      fallback,
+      maxTokens: 700,
+      temperature: 0,
+      purpose: opts.purpose ?? 'composition-critic',
+    });
+    const text = typeof res.text === 'string' ? res.text : '';
+    return { findings: parseFindings(text), model: res.usage?.model ?? spec.model };
+  } catch {
+    return { findings: [], skipped: 'error' };
+  }
+}
+
+const SEVERITIES: CriticSeverity[] = ['high', 'medium', 'low'];
+
+/** Defensive parse — strip any markdown fence, take the first JSON object,
+ *  coerce to VisionFinding[]. A malformed model reply yields []. */
+export function parseFindings(text: string): VisionFinding[] {
+  try {
+    if (typeof text !== 'string') return [];
+    const cleaned = text.replace(/```json\s*|```/g, '').trim();
+    const start = cleaned.indexOf('{');
+    const end = cleaned.lastIndexOf('}');
+    if (start < 0 || end <= start) return [];
+    const obj = JSON.parse(cleaned.slice(start, end + 1));
+    const raw = Array.isArray(obj?.findings) ? obj.findings : [];
+    const out: VisionFinding[] = [];
+    for (const f of raw) {
+      const sev = SEVERITIES.includes(f?.severity) ? (f.severity as CriticSeverity) : 'medium';
+      const region = typeof f?.region === 'string' ? f.region.slice(0, 60) : 'screen';
+      const issue = typeof f?.issue === 'string' ? f.issue.slice(0, 200) : '';
+      if (!issue) continue;
+      out.push({ kind: 'vision', severity: sev, region, message: issue });
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}

package/src/critic.ts

@@ -0,0 +1,73 @@
+// F126.4 — composition-critic orchestrator. Runs the requested engine(s) against
+// a live page + its screenshot and rolls their findings into one report the
+// Lens capture/verify result carries. Geometry (critic-dom) is free + always
+// available; vision (critic-vision) is a metered call gated by the caller (the
+// F095 Review gate reads the project's composition_critic.vision setting and
+// passes 'both' vs 'dom').
+
+import type { Page } from 'playwright';
+import { runDomCritic, type DomFinding } from './critic-dom.ts';
+import { runVisionCritic, type VisionFinding, type VisionModelKey } from './critic-vision.ts';
+
+export type CriticMode = 'off' | 'dom' | 'vision' | 'both';
+
+export interface CriticReport {
+  mode: CriticMode;
+  dom: DomFinding[];
+  vision: VisionFinding[];
+  high: number;
+  medium: number;
+  low: number;
+  /** Concrete vision model used, if vision ran. */
+  visionModel?: string;
+  /** Why vision produced nothing, if it was requested but didn't run. */
+  visionSkipped?: 'no-ai' | 'error';
+}
+
+export function emptyCritic(mode: CriticMode = 'off'): CriticReport {
+  return { mode, dom: [], vision: [], high: 0, medium: 0, low: 0 };
+}
+
+/** Run the requested critic engines. `dom` is deterministic + free; `vision`
+ *  costs one model call. Returns a combined report with severity rollups. */
+export async function runCritic(
+  page: Page,
+  screenshot: Buffer,
+  mode: CriticMode,
+  visionModelKey?: VisionModelKey,
+): Promise<CriticReport> {
+  if (mode === 'off') return emptyCritic('off');
+  const dom = mode === 'dom' || mode === 'both' ? await runDomCritic(page) : [];
+  let vision: VisionFinding[] = [];
+  let visionModel: string | undefined;
+  let visionSkipped: 'no-ai' | 'error' | undefined;
+  if (mode === 'vision' || mode === 'both') {
+    const r = await runVisionCritic(screenshot, { purpose: 'composition-critic', model: visionModelKey });
+    vision = r.findings;
+    visionModel = r.model;
+    visionSkipped = r.skipped;
+  }
+  const all = [...dom, ...vision];
+  return {
+    mode,
+    dom,
+    vision,
+    high: all.filter((f) => f.severity === 'high').length,
+    medium: all.filter((f) => f.severity === 'medium').length,
+    low: all.filter((f) => f.severity === 'low').length,
+    visionModel,
+    visionSkipped,
+  };
+}
+
+/** A compact, gate-friendly one-liner. */
+export function criticSummary(r: CriticReport | null): string {
+  if (!r || r.mode === 'off') return 'composition critic off';
+  return `composition: ${r.high} high · ${r.medium} medium · ${r.low} low (${r.dom.length} geometry, ${r.vision.length} vision)`;
+}
+
+/** The single highest-severity finding's human message, for a fail reason. */
+export function topFindingMessage(r: CriticReport): string | null {
+  const high = [...r.dom, ...r.vision].find((f) => f.severity === 'high');
+  return high?.message ?? null;
+}

package/src/daemon-routes.ts

@@ -0,0 +1,333 @@
+// lens F001.5 — the Lens routes that used to be registered one by one in the
+// cardmem daemon's index.ts (lines 1270–1661 at cardmem ed10516f), folded into
+// the package router so the daemon mounts ONE thing: createLensRouter(deps).
+//
+// Bodies are moved verbatim; only three references changed:
+//   config.sandbox_roots → deps.sandboxRoots
+//   config.port          → deps.port
+//   lensStorage          → deps.storage
+// and `err instanceof SandboxError` became isSandboxError(err), because the
+// sandbox (and its error class) stays the daemon's — see sandbox.ts.
+
+import type { Hono } from 'hono';
+import { scrapeArticle } from './scrape.ts';
+import { startCaptureSession, finishCaptureSession, cancelCaptureSession, execCaptureSession, parseExecBody } from './capture-session.ts';
+import { listVisionModels } from './critic-vision.ts';
+import { lensCaptureCatalogue, lensRunFlow, artifactUrl, type LensDeps } from './service.ts';
+import { loadManifest, manifestToCatalogue, inventoryTestIds, inventoryInteractiveGaps, inventoryChromeDrift, manifestFlows } from './manifest.ts';
+import { inventorySwallowedErrors } from './swallowed-errors.ts';
+import { flowTestIds, proposeFlow } from './flow.ts';
+import { checkAnchors, decideVerdict } from './gate.ts';
+import { runRecord } from './record-run.ts';
+
+/** The daemon's SandboxError, recognised by name — the class itself is the daemon's. */
+const isSandboxError = (err: unknown): err is Error => err instanceof Error && err.name === 'SandboxError';
+
+export function registerDaemonRoutes(r: Hono, deps: LensDeps): void {
+  // F126.4 — vision-model catalog + availability (single source for the Settings
+  // composition-critic selector). Availability reflects which provider keys this
+  // daemon actually has armed.
+  r.get('/vision-models', (c) => c.json(listVisionModels()));
+
+  // F074.6 — manifest-driven catalogue + data-testid inventory. These read
+  // project files (sandbox-sensitive).
+  r.post('/catalogue', async (c) => {
+    const body = (await c.req.json().catch(() => ({}))) as { local_path?: string; base_url?: string };
+    if (!body.local_path) return c.json({ ok: false, error: 'local_path required' }, 400);
+    try {
+      const manifest = loadManifest(body.local_path, deps.sandboxRoots);
+      const result = await lensCaptureCatalogue(deps, manifestToCatalogue(manifest, body.base_url));
+      return c.json({ ok: true, ...result });
+    } catch (err) {
+      if (isSandboxError(err)) return c.json({ ok: false, error: `sandbox: ${err.message}` }, 403);
+      return c.json({ ok: false, error: err instanceof Error ? err.message : String(err) }, 400);
+    }
+  });
+
+  r.post('/testid-inventory', async (c) => {
+    const body = (await c.req.json().catch(() => ({}))) as { local_path?: string };
+    if (!body.local_path) return c.json({ ok: false, error: 'local_path required' }, 400);
+    try {
+      const inv = inventoryTestIds(body.local_path, deps.sandboxRoots);
+      // upmetrics #4 — also surface the interactive-gap count so the inventory
+      // answers "what still needs a testid", not just "what exists".
+      const gaps = inventoryInteractiveGaps(body.local_path, deps.sandboxRoots);
+      return c.json({ ok: true, ...inv, interactive_gaps: gaps.total_gaps, files_with_gaps: gaps.files_with_gaps });
+    } catch (err) {
+      if (isSandboxError(err)) return c.json({ ok: false, error: `sandbox: ${err.message}` }, 403);
+      return c.json({ ok: false, error: err instanceof Error ? err.message : String(err) }, 400);
+    }
+  });
+
+  // upmetrics #4 — the actionable list: interactive elements (buttons/inputs/
+  // selects/onClick) missing a data-testid, so step-2 instrumentation is concrete.
+  r.post('/testid-gaps', async (c) => {
+    const body = (await c.req.json().catch(() => ({}))) as { local_path?: string };
+    if (!body.local_path) return c.json({ ok: false, error: 'local_path required' }, 400);
+    try {
+      return c.json({ ok: true, ...inventoryInteractiveGaps(body.local_path, deps.sandboxRoots) });
+    } catch (err) {
+      if (isSandboxError(err)) return c.json({ ok: false, error: `sandbox: ${err.message}` }, 403);
+      return c.json({ ok: false, error: err instanceof Error ? err.message : String(err) }, 400);
+    }
+  });
+
+  // F074.32 — static scan for code that takes the data and drops the error. No
+  // browser: it reads source. Same body/sandbox contract as /lens/testid-gaps.
+  r.post('/swallowed-errors', async (c) => {
+    const body = (await c.req.json().catch(() => ({}))) as { local_path?: string };
+    if (!body.local_path) return c.json({ ok: false, error: 'local_path required' }, 400);
+    try {
+      return c.json({ ok: true, ...inventorySwallowedErrors(body.local_path, deps.sandboxRoots) });
+    } catch (err) {
+      if (isSandboxError(err)) return c.json({ ok: false, error: `sandbox: ${err.message}` }, 403);
+      return c.json({ ok: false, error: err instanceof Error ? err.message : String(err) }, 400);
+    }
+  });
+
+  // F125.2 — Lens scrape: an arbitrary article URL → clean markdown. Body: { url, storage_state_path? }.
+  r.post('/scrape', async (c) => {
+    const body = (await c.req.json().catch(() => ({}))) as { url?: string; storage_state_path?: string };
+    if (!body.url) return c.json({ ok: false, error: 'url required' }, 400);
+    try {
+      const result = await scrapeArticle(body.url, { storageStatePath: body.storage_state_path });
+      return c.json({ ok: true, ...result });
+    } catch (err) {
+      return c.json({ ok: false, error: err instanceof Error ? err.message : String(err) }, 400);
+    }
+  });
+
+  // F240.6 — headed capture-session. Open a VISIBLE browser so a human logs in to a
+  // 2FA-gated site, then dump the Playwright storageState to a local file. The
+  // response carries only the path + counts, never the session bytes.
+  r.post('/capture-session/start', async (c) => {
+    const body = (await c.req.json().catch(() => ({}))) as {
+      url?: string;
+      state_path?: string;
+      email?: string;
+      password?: string;
+      load_state_path?: string;
+    };
+    if (!body.url) return c.json({ ok: false, error: 'url required' }, 400);
+    if (!body.state_path) return c.json({ ok: false, error: 'state_path required' }, 400);
+    try {
+      const r = await startCaptureSession({
+        url: body.url,
+        statePath: body.state_path,
+        email: body.email,
+        password: body.password,
+        loadStatePath: body.load_state_path,
+      });
+      // F240.10 — pass the window verdict through UNCHANGED. A remote caller is the
+      // one who has to tell a human "the browser is open"; it must see what the
+      // engine actually concluded, including "no verdict".
+      return c.json({
+        ok: true,
+        session_id: r.sessionId,
+        url: r.url,
+        state_path: r.statePath,
+        loaded: r.loaded,
+        login: r.login,
+        window_visible: r.windowVisible,
+        window_check: r.windowCheck,
+      });
+    } catch (err) {
+      return c.json({ ok: false, error: err instanceof Error ? err.message : String(err) }, 400);
+    }
+  });
+
+  // F240.7 — drive fill/click/screenshot steps against the OPEN capture-session
+  // browser. Credential VALUES ride in step.value over loopback ONLY.
+  r.post('/capture-session/exec', async (c) => {
+    // F240.9 — PARSED, not cast.
+    const parsed = parseExecBody(await c.req.json().catch(() => ({})));
+    if (!parsed.ok) return c.json({ ok: false, error: parsed.error }, 400);
+    const body = parsed.value;
+    try {
+      const sessionId = body.session_id;
+      const r = await execCaptureSession({
+        sessionId,
+        steps: body.steps,
+        saveShot: async (buffer, index) => {
+          const key = `capture-sessions/${sessionId}/${Date.now()}-${index}.png`;
+          await deps.storage.put(key, buffer);
+          return artifactUrl(deps.port, key) ?? '';
+        },
+      });
+      return c.json(r);
+    } catch (err) {
+      return c.json({ ok: false, error: err instanceof Error ? err.message : String(err) }, 400);
+    }
+  });
+
+  r.post('/capture-session/finish', async (c) => {
+    const body = (await c.req.json().catch(() => ({}))) as { session_id?: string };
+    if (!body.session_id) return c.json({ ok: false, error: 'session_id required' }, 400);
+    try {
+      const r = await finishCaptureSession({ sessionId: body.session_id });
+      return c.json(r);
+    } catch (err) {
+      return c.json({ ok: false, error: err instanceof Error ? err.message : String(err) }, 400);
+    }
+  });
+
+  r.post('/capture-session/cancel', async (c) => {
+    const body = (await c.req.json().catch(() => ({}))) as { session_id?: string };
+    if (!body.session_id) return c.json({ ok: false, error: 'session_id required' }, 400);
+    const r = await cancelCaptureSession(body.session_id);
+    return c.json(r);
+  });
+
+  // F312 — LENS VIDEO. F312.25 — THIN: the handler lives in record-run.ts so the
+  // MCP verb `lens_record` runs the SAME code rather than a copy.
+  r.post('/record', async (c) => {
+    const raw = (await c.req.json().catch(() => ({}))) as Record<string, unknown>;
+    const out = await runRecord(raw, { config: { port: deps.port, sandbox_roots: deps.sandboxRoots }, storage: deps.storage });
+    const { status, ...rest } = out;
+    return c.json(rest, status as 200 | 400);
+  });
+
+  // F123.4 — design-consistency structural check (the F086-twin for layout).
+  r.post('/chrome-drift', async (c) => {
+    const body = (await c.req.json().catch(() => ({}))) as {
+      local_path?: string;
+      layout_component?: string;
+      shell_marker?: string;
+    };
+    if (!body.local_path) return c.json({ ok: false, error: 'local_path required' }, 400);
+    try {
+      return c.json({
+        ok: true,
+        ...inventoryChromeDrift(body.local_path, deps.sandboxRoots, {
+          layoutComponent: body.layout_component,
+          shellMarker: body.shell_marker,
+        }),
+      });
+    } catch (err) {
+      if (isSandboxError(err)) return c.json({ ok: false, error: `sandbox: ${err.message}` }, 403);
+      return c.json({ ok: false, error: err instanceof Error ? err.message : String(err) }, 400);
+    }
+  });
+
+  // F074.7 — Lens gate: manifest + testid inventory + catalogue → a single
+  // green/red verdict + action.
+  r.post('/gate', async (c) => {
+    const body = (await c.req.json().catch(() => ({}))) as { local_path?: string; base_url?: string };
+    if (!body.local_path) return c.json({ ok: false, error: 'local_path required' }, 400);
+    try {
+      const manifest = loadManifest(body.local_path, deps.sandboxRoots);
+      const inventory = inventoryTestIds(body.local_path, deps.sandboxRoots);
+      const anchors = checkAnchors(manifest, inventory.testids.map((t) => t.testid));
+      const catalogue = await lensCaptureCatalogue(deps, manifestToCatalogue(manifest, body.base_url));
+      const gate = decideVerdict(catalogue, anchors);
+      return c.json({ ok: true, gate, anchors, catalogue });
+    } catch (err) {
+      if (isSandboxError(err)) return c.json({ ok: false, error: `sandbox: ${err.message}` }, 403);
+      return c.json({ ok: false, error: err instanceof Error ? err.message : String(err) }, 400);
+    }
+  });
+
+  // F082.3 — flow-gate: run every manuscript flow in a project's manifest +
+  // cross-check each [data-testid] the steps reference against the repo's
+  // inventory (a missing anchor is a hard block). One green/red verdict.
+  r.post('/flow-gate', async (c) => {
+    const body = (await c.req.json().catch(() => ({}))) as { local_path?: string; base_url?: string };
+    if (!body.local_path) return c.json({ ok: false, error: 'local_path required' }, 400);
+    try {
+      const manifest = loadManifest(body.local_path, deps.sandboxRoots);
+      const inventory = inventoryTestIds(body.local_path, deps.sandboxRoots);
+      const known = new Set(inventory.testids.map((t) => t.testid));
+      const flows = manifestFlows(manifest, body.base_url);
+      if (flows.length === 0) {
+        return c.json({ ok: true, gate: { verdict: 'green', reason: 'no flows declared' }, flows: [] });
+      }
+      const results = [];
+      for (const flow of flows) {
+        const missing = flowTestIds(flow).filter((t) => !known.has(t));
+        if (missing.length > 0) {
+          // Hard block: a step targets an anchor that doesn't exist in the repo.
+          results.push({ flow: flow.name, status: 'blocked', missing_anchors: missing });
+          continue;
+        }
+        // upmetrics (F074.11 closeout) — the gate must inherit the manifest's
+        // statePath auth too: passing local_path lets effectiveFlowAuth resolve it.
+        const run = await lensRunFlow(deps, { project: manifest.project, flow, local_path: body.local_path });
+        results.push({ flow: flow.name, status: run.status, flow_run_id: run.flow_run_id, failed_at: run.failed_at, reason: run.reason });
+      }
+      const bad = results.filter((r) => r.status !== 'pass');
+      const gate = {
+        verdict: bad.length === 0 ? 'green' : 'red',
+        total: results.length,
+        passed: results.filter((r) => r.status === 'pass').length,
+        blocked: results.filter((r) => r.status === 'blocked').length,
+        failed: results.filter((r) => r.status === 'fail' || r.status === 'error').length,
+      };
+      return c.json({ ok: true, gate, flows: results });
+    } catch (err) {
+      if (isSandboxError(err)) return c.json({ ok: false, error: `sandbox: ${err.message}` }, 403);
+      return c.json({ ok: false, error: err instanceof Error ? err.message : String(err) }, 400);
+    }
+  });
+
+  // F082.5 STRETCH — discovery: propose a candidate smoke-flow from the project's
+  // manifest routes + their [data-testid] anchors, no hand-written manuscript.
+  r.post('/propose-flow', async (c) => {
+    const body = (await c.req.json().catch(() => ({}))) as { local_path?: string; base_url?: string };
+    if (!body.local_path) return c.json({ ok: false, error: 'local_path required' }, 400);
+    try {
+      const manifest = loadManifest(body.local_path, deps.sandboxRoots);
+      const extractTestid = (sel?: string | number): string | null => {
+        if (typeof sel !== 'string') return null;
+        const m = sel.match(/\[data-testid=["']?([^"'\]]+)["']?\]/);
+        return m ? m[1]! : null;
+      };
+      const seen = new Set<string>();
+      const surfaces: Array<{ path: string; testid: string }> = [];
+      for (const s of manifest.surfaces) {
+        const testid = extractTestid(s.selector) ?? extractTestid(s.waitFor);
+        if (!testid) continue;
+        const key = `${s.path}|${testid}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        surfaces.push({ path: s.path, testid });
+      }
+      const flow = proposeFlow(`${manifest.project}-smoke`, body.base_url ?? manifest.base_url, surfaces);
+      return c.json({ ok: true, flow, surface_count: surfaces.length });
+    } catch (err) {
+      if (isSandboxError(err)) return c.json({ ok: false, error: `sandbox: ${err.message}` }, 403);
+      return c.json({ ok: false, error: err instanceof Error ? err.message : String(err) }, 400);
+    }
+  });
+
+  // F082 — hermetic E2E self-test fixture: a self-contained form the flow
+  // executor can drive end-to-end with NO external site + NO auth.
+  r.get('/_selftest', (c) =>
+    c.html(`<!doctype html><html><head><meta charset="utf-8"><title>Lens self-test</title></head>
+<body data-testid="fixture-root" style="font-family:system-ui;padding:24px">
+  <h1 data-testid="fixture-title">Lens E2E self-test</h1>
+  <label>Name <input data-testid="name" /></label>
+  <label>Role <select data-testid="role"><option value="">—</option><option value="admin">admin</option><option value="user">user</option></select></label>
+  <label><input type="checkbox" data-testid="agree" /> Agree</label>
+  <button data-testid="submit">Create</button>
+  <div data-testid="success" style="display:none"></div>
+  <!-- F082.6 / upmetrics #2 — async-hydrating node: empty on mount, text after a
+       beat. A one-shot expectText races this; a polling expectText settles. -->
+  <div data-testid="hydrated"></div>
+  <script>
+    setTimeout(function () {
+      document.querySelector('[data-testid=hydrated]').textContent = 'loaded-data sdk 0.1.4';
+    }, 400);
+    document.querySelector('[data-testid=submit]').addEventListener('click', function () {
+      var name = document.querySelector('[data-testid=name]').value.trim();
+      var role = document.querySelector('[data-testid=role]').value;
+      var agree = document.querySelector('[data-testid=agree]').checked;
+      var out = document.querySelector('[data-testid=success]');
+      if (name && role && agree) {
+        out.textContent = 'Created: ' + name + ' (' + role + ')';
+        out.style.display = 'block';
+      }
+    });
+  </script>
+</body></html>`),
+  );
+}

package/src/durability.ts

@@ -0,0 +1,18 @@
+// lens F001.5 — what a piece of Lens evidence is worth once the machine that made
+// it is gone. Logic moved verbatim (comments shortened) from cardmem packages/shared/src/evidence-durability.ts
+// (ed10516f). Lens WRITES artifact_backend, so Lens owns what it means; cardmem's
+// gate re-exports this from @broberg/lens-daemon after the cutover.
+
+/** What a piece of evidence is worth once the machine that made it is gone. */
+export type EvidenceDurability = 'durable' | 'local_only' | 'unknown';
+
+/**
+ * Classify a stored backend value. The `null` branch is load-bearing: `?? 'local'`
+ * would silently claim a measurement for every historic row, `?? 'durable'` would
+ * be catastrophic. "We did not record this" must never become a reading.
+ */
+export function durabilityOf(backend: string | null | undefined): EvidenceDurability {
+  if (backend === 'tigris') return 'durable';
+  if (backend === 'local') return 'local_only';
+  return 'unknown';
+}