@reticlehq/server 2.11.0 → 2.13.0

package/dist/pool/browser-pool.d.ts

@@ -9,7 +9,6 @@
  * The browser is injected via a `Launcher` so all lifecycle logic is testable without real Chromium;
  * the thin Playwright adapter that satisfies these interfaces lives separately.
  */
-/** The minimal page surface the pool drives. Real Playwright `Page` satisfies this. */
 export interface PooledPage {
     goto(url: string, opts?: {
         timeoutMs?: number;
@@ -17,6 +16,27 @@ export interface PooledPage {
     close(): Promise<void>;
     /** Fires when THIS page's renderer crashes — lets the pool reclaim just this lease, not the fleet. */
     onCrash(handler: () => void): void;
+    /**
+     * Fires for each console message the page logs. OPTIONAL: a fake that does not implement it makes
+     * the pool record nothing, which is the correct degradation — an absent dial address must read as
+     * "the page said nothing", never as "the page dialled correctly".
+     */
+    onConsole?(handler: (text: string) => void): void;
+    /**
+     * Capture the page as a PNG. OPTIONAL, like `onConsole`: a fake that does not implement it makes
+     * the pool report "no provider", which is the correct degradation — an absent screenshotter must
+     * read as "this context cannot be captured", never as a blank image that a visual diff would then
+     * compare against and pass.
+     */
+    screenshot?(opts?: {
+        fullPage?: boolean;
+    }): Promise<Uint8Array>;
+    /**
+     * Move the real pointer to (x, y) so CSS `:hover` applies. OPTIONAL, like `screenshot`: a fake
+     * that does not implement it makes hover refuse rather than dispatch a synthetic mouseover that
+     * reports dispatched/settled while the styles never ran.
+     */
+    hover?(x: number, y: number): Promise<void>;
 }
 /** An isolated browsing context (cookies/storage). Real Playwright `BrowserContext` satisfies this. */
 export interface PooledContext {
@@ -69,6 +89,16 @@ export declare class BrowserPool {
     queuedCount(): number;
     /** The sessionIds of every currently leased context — used to report/group leased sessions. */
     leasedSessionIds(): string[];
+    /**
+     * The public session id of an active lease on this origin, if we already hold one.
+     *
+     * The lease TOOL reuses that id instead of minting a second context: a second acquire on the same
+     * origin used to leave both tabs connected and poison default session resolution (#600). The pool's
+     * own `acquire` still mints — the parallel suite needs isolation on purpose.
+     *
+     * Prefers the alias the agent was given, when the app registered under its own name.
+     */
+    leaseIdOnOrigin(origin: string): string | undefined;
     /**
      * Release a lease by its sessionId (closes the context, frees the slot). No-op if unknown.
      *
@@ -96,16 +126,50 @@ export declare class BrowserPool {
      * Reclaim leases untouched for longer than the TTL — a hung/crashed agent never holds a slot
      * forever. Returns the released sessionIds. This is the fault-tolerance backstop for the pool.
      */
+    /**
+     * Capture a leased page, or undefined when this session is not a lease or cannot be captured.
+     *
+     * A lease IS a real browser page, so the pixels were always available — the visual tools simply had
+     * no route to them and answered "no provider" for every context an agent can actually get. That
+     * made visual regression impossible on exactly the isolated contexts the pool exists to hand out.
+     *
+     * Touches the lease like any other tool call, so capturing keeps it alive rather than letting the
+     * reaper take it out from under a diff.
+     */
+    screenshotLease(sessionId: string, opts?: {
+        fullPage?: boolean;
+    }): Promise<Uint8Array | undefined>;
+    /**
+     * Move the real pointer on a leased page, or false when this session is not a lease or cannot
+     * hover. Same optional-capability contract as screenshotLease: absence must read as "could not
+     * hover", never as a successful dispatch of a synthetic mouseover.
+     *
+     * Touches the lease like any other tool call, so hovering keeps it alive.
+     */
+    hoverLease(sessionId: string, x: number, y: number): Promise<boolean>;
     sweepExpired(): Promise<string[]>;
     /**
      * How many leases this pool has reclaimed for going stale.
      *
-     * Read by the no-session diagnosis: an aged-out lease used to be reported as "the tab was closed
-     * … ask the human to reopen the app", which is wrong on every clause and sent one reporter looking
-     * for a port mismatch (#157). A count is enough — the message says "likeliest", not "certainly",
-     * because nothing here knows WHICH session the caller just lost.
+     * Kept for reporting. NOT a basis for diagnosis: it is a lifetime total that never resets, so
+     * `count > 0` latches true forever after the first reap. Ask `wasReapedLease` instead, which
+     * answers about a specific session.
      */
     reapedLeaseCount(): number;
+    /**
+     * Did THIS session id belong to a lease this pool aged out?
+     *
+     * The question the no-session diagnosis actually has. It used to ask `reapedLeaseCount() > 0`,
+     * which meant that once any lease had ever aged out, every closed human tab for the rest of the
+     * daemon's life was reported as an expired lease — and the recovery that followed
+     * (`reticle_lease {acquire}`) would open an unauthenticated headless context and lose the app
+     * session (#611).
+     *
+     * Only the last {@link MAX_REMEMBERED_REAPED_LEASES} are remembered, so this answers `false` for
+     * a lease reaped long enough ago that thousands have followed. That direction is the safe one:
+     * it falls back to the generic "the tab was closed" wording rather than inventing a lease.
+     */
+    wasReapedLease(sessionId: string): boolean;
     /**
      * Lease an isolated context, navigate it to `url`, and return a handle. If the pool is at capacity,
      * waits FIFO until a slot frees (or until `signal` aborts, if provided).
@@ -114,6 +178,12 @@ export declare class BrowserPool {
         signal?: AbortSignal;
         sessionId?: string;
     }): Promise<Lease>;
+    /**
+     * The websocket address this lease's page reported it could not reach, if it reported one.
+     *
+     * Undefined means the page said nothing — never that it dialled the right place.
+     */
+    dialFailureUrl(sessionId: string): string | undefined;
     /** Close every context and the browser. Pending waiters are rejected (the pool is terminal now). */
     shutdown(): Promise<void>;
 }

package/dist/pool/browser-pool.js

@@ -9,10 +9,17 @@
  * The browser is injected via a `Launcher` so all lifecycle logic is testable without real Chromium;
  * the thin Playwright adapter that satisfies these interfaces lives separately.
  */
+/** The minimal page surface the pool drives. Real Playwright `Page` satisfies this. */
+import { unreachableUrlIn } from '@reticlehq/core';
 /** Default lease time-to-live: a lease untouched for this long is presumed orphaned and reclaimed. */
 export const DEFAULT_LEASE_TTL_MS = 5 * 60_000;
 /** Default cap on how long a lease's initial navigation may take before it fails (frees the slot). */
 const DEFAULT_NAV_TIMEOUT_MS = 30_000;
+/**
+ * How many reaped lease ids to remember. Only the most recent departure is ever asked about, so
+ * this is slack for a burst sweep, not a history.
+ */
+const MAX_REMEMBERED_REAPED_LEASES = 64;
 /**
  * Owns a single browser and leases isolated contexts out of it, capped at `maxContexts`.
  * Not exported as a singleton — the daemon owns one instance.
@@ -29,6 +36,18 @@ export class BrowserPool {
     #closed = false;
     /** Leases reclaimed for going stale — see reapedLeaseCount(). */
     #reapedLeases = 0;
+    /**
+     * The session ids of recently reaped leases, most recent last.
+     *
+     * The count above answers "has anything ever aged out", which is not a
+     * question any caller actually has: it latches true for the life of the
+     * daemon (#611). The ids answer the question the no-session diagnosis is
+     * really asking — was THIS session a lease that aged out — so a closed
+     * human tab is no longer blamed on an expired lease forever after.
+     *
+     * Bounded because a long-lived daemon reaps unboundedly many.
+     */
+    #reapedLeaseIds = [];
     #active = new Map();
     /** Registered-session-id → lease id, for apps that keep their own session name. See `alias`. */
     #aliases = new Map();
@@ -71,6 +90,34 @@ export class BrowserPool {
     leasedSessionIds() {
         return [...this.#active.keys()];
     }
+    /**
+     * The public session id of an active lease on this origin, if we already hold one.
+     *
+     * The lease TOOL reuses that id instead of minting a second context: a second acquire on the same
+     * origin used to leave both tabs connected and poison default session resolution (#600). The pool's
+     * own `acquire` still mints — the parallel suite needs isolation on purpose.
+     *
+     * Prefers the alias the agent was given, when the app registered under its own name.
+     */
+    leaseIdOnOrigin(origin) {
+        for (const [leaseId, lease] of this.#active) {
+            let leaseOrigin;
+            try {
+                leaseOrigin = new URL(lease.url).origin;
+            }
+            catch {
+                continue;
+            }
+            if (leaseOrigin !== origin)
+                continue;
+            for (const [alias, id] of this.#aliases) {
+                if (id === leaseId)
+                    return alias;
+            }
+            return leaseId;
+        }
+        return undefined;
+    }
     /**
      * Release a lease by its sessionId (closes the context, frees the slot). No-op if unknown.
      *
@@ -114,6 +161,50 @@ export class BrowserPool {
      * Reclaim leases untouched for longer than the TTL — a hung/crashed agent never holds a slot
      * forever. Returns the released sessionIds. This is the fault-tolerance backstop for the pool.
      */
+    /**
+     * Capture a leased page, or undefined when this session is not a lease or cannot be captured.
+     *
+     * A lease IS a real browser page, so the pixels were always available — the visual tools simply had
+     * no route to them and answered "no provider" for every context an agent can actually get. That
+     * made visual regression impossible on exactly the isolated contexts the pool exists to hand out.
+     *
+     * Touches the lease like any other tool call, so capturing keeps it alive rather than letting the
+     * reaper take it out from under a diff.
+     */
+    async screenshotLease(sessionId, opts = {}) {
+        const lease = this.#active.get(sessionId);
+        if (lease === undefined || lease.page.screenshot === undefined)
+            return undefined;
+        this.touch(sessionId);
+        try {
+            return await lease.page.screenshot(opts);
+        }
+        catch {
+            // A capture that fails is not a broken lease. Report "could not capture" and leave the lease
+            // usable — the alternative is losing a working context to one bad frame.
+            return undefined;
+        }
+    }
+    /**
+     * Move the real pointer on a leased page, or false when this session is not a lease or cannot
+     * hover. Same optional-capability contract as screenshotLease: absence must read as "could not
+     * hover", never as a successful dispatch of a synthetic mouseover.
+     *
+     * Touches the lease like any other tool call, so hovering keeps it alive.
+     */
+    async hoverLease(sessionId, x, y) {
+        const lease = this.#active.get(sessionId);
+        if (lease === undefined || lease.page.hover === undefined)
+            return false;
+        this.touch(sessionId);
+        try {
+            await lease.page.hover(x, y);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     async sweepExpired() {
         const now = this.#now();
         const expired = [...this.#active.entries()]
@@ -122,19 +213,39 @@ export class BrowserPool {
         for (const sessionId of expired)
             await this.#release(sessionId);
         this.#reapedLeases += expired.length;
+        for (const sessionId of expired) {
+            this.#reapedLeaseIds.push(sessionId);
+            if (this.#reapedLeaseIds.length > MAX_REMEMBERED_REAPED_LEASES)
+                this.#reapedLeaseIds.shift();
+        }
         return expired;
     }
     /**
      * How many leases this pool has reclaimed for going stale.
      *
-     * Read by the no-session diagnosis: an aged-out lease used to be reported as "the tab was closed
-     * … ask the human to reopen the app", which is wrong on every clause and sent one reporter looking
-     * for a port mismatch (#157). A count is enough — the message says "likeliest", not "certainly",
-     * because nothing here knows WHICH session the caller just lost.
+     * Kept for reporting. NOT a basis for diagnosis: it is a lifetime total that never resets, so
+     * `count > 0` latches true forever after the first reap. Ask `wasReapedLease` instead, which
+     * answers about a specific session.
      */
     reapedLeaseCount() {
         return this.#reapedLeases;
     }
+    /**
+     * Did THIS session id belong to a lease this pool aged out?
+     *
+     * The question the no-session diagnosis actually has. It used to ask `reapedLeaseCount() > 0`,
+     * which meant that once any lease had ever aged out, every closed human tab for the rest of the
+     * daemon's life was reported as an expired lease — and the recovery that followed
+     * (`reticle_lease {acquire}`) would open an unauthenticated headless context and lose the app
+     * session (#611).
+     *
+     * Only the last {@link MAX_REMEMBERED_REAPED_LEASES} are remembered, so this answers `false` for
+     * a lease reaped long enough ago that thousands have followed. That direction is the safe one:
+     * it falls back to the generic "the tab was closed" wording rather than inventing a lease.
+     */
+    wasReapedLease(sessionId) {
+        return this.#reapedLeaseIds.includes(sessionId);
+    }
     /**
      * Lease an isolated context, navigate it to `url`, and return a handle. If the pool is at capacity,
      * waits FIFO until a slot frees (or until `signal` aborts, if provided).
@@ -147,6 +258,7 @@ export class BrowserPool {
         await this.#waitForSlot(opts.signal);
         const sessionId = opts.sessionId ?? this.#genId();
         let context;
+        let pending;
         try {
             const browser = await this.#ensureBrowser();
             context = await browser.newContext();
@@ -156,6 +268,19 @@ export class BrowserPool {
             page.onCrash(() => {
                 void this.#release(sessionId);
             });
+            // Listen BEFORE goto: the SDK's connect attempt races the navigation's own resolution, and a
+            // listener attached afterwards misses the first failures — the only ones logged before the
+            // retry backoff stretches out.
+            page.onConsole?.((text) => {
+                const dialled = unreachableUrlIn(text);
+                if (dialled === undefined)
+                    return;
+                const active = this.#active.get(sessionId);
+                if (active !== undefined)
+                    active.dialFailureUrl = dialled;
+                else
+                    pending = dialled; // logged during goto, before the lease is registered below
+            });
             await page.goto(url, { timeoutMs: this.#navTimeout });
             // The browser can crash WHILE goto is resolving; #onCrash then clears #active and zeroes
             // #occupied. Registering the lease now would resurrect a dead entry against a crashed browser with
@@ -163,7 +288,13 @@ export class BrowserPool {
             // no longer the live browser, bail — the catch below closes the context and returns the slot.
             if (this.#browser !== browser)
                 throw new Error('browser crashed during navigation');
-            this.#active.set(sessionId, { context, page, url, touchedAt: this.#now() });
+            this.#active.set(sessionId, {
+                context,
+                page,
+                url,
+                touchedAt: this.#now(),
+                ...(pending === undefined ? {} : { dialFailureUrl: pending }),
+            });
             return {
                 sessionId,
                 url,
@@ -179,6 +310,14 @@ export class BrowserPool {
             throw err;
         }
     }
+    /**
+     * The websocket address this lease's page reported it could not reach, if it reported one.
+     *
+     * Undefined means the page said nothing — never that it dialled the right place.
+     */
+    dialFailureUrl(sessionId) {
+        return this.#active.get(sessionId)?.dialFailureUrl;
+    }
     /** Close every context and the browser. Pending waiters are rejected (the pool is terminal now). */
     async shutdown() {
         this.#closed = true; // set first so any woken waiter rejects instead of relaunching a browser

package/dist/pool/playwright-launcher.js

@@ -6,6 +6,7 @@
  * Headless by default — the pool exists for fault-tolerant headless multi-agent testing.
  */
 import { BrowserLaunchKind } from '@reticlehq/core';
+import { chromiumLaunchOptions } from '../chromium-launch-options.js';
 import { getSessionMetrics } from '../telemetry/session-metrics.js';
 import { classifyConnectFailure } from '../telemetry/connect-failure.js';
 import { chromiumInstallCommand, bundledPlaywrightVersion } from '../cli/chromium-hint.js';
@@ -39,7 +40,17 @@ function wrapBrowser(browser) {
                     return {
                         goto: (url, opts) => page.goto(url, gotoOptions(opts?.timeoutMs)),
                         close: () => page.close(),
+                        // Playwright returns a Buffer; Uint8Array is what the visual store and differ take.
+                        screenshot: async (opts) => new Uint8Array(await page.screenshot({ fullPage: true === opts?.fullPage })),
+                        // Three moves, same as performGesture: a single move to the center can be a no-op if
+                        // the pointer was already there, and CSS :hover needs a native hit-test to apply.
+                        hover: async (x, y) => {
+                            await page.mouse.move(x, y);
+                            await page.mouse.move(x + 1, y);
+                            await page.mouse.move(x, y);
+                        },
                         onCrash: (handler) => page.on('crash', handler),
+                        onConsole: (handler) => page.on('console', (msg) => handler(msg.text())),
                     };
                 },
                 close: () => context.close(),
@@ -72,7 +83,7 @@ export function playwrightLauncher(opts = {}) {
         // number that actually costs memory and the one that explains a slow machine.
         const settle = getSessionMetrics().recordConnectAttempt(BrowserLaunchKind.POOLED);
         try {
-            const browser = wrapBrowser(await chromium.launch({ headless }));
+            const browser = wrapBrowser(await chromium.launch(chromiumLaunchOptions(headless)));
             settle();
             return browser;
         }

package/dist/project/fs-port.d.ts

@@ -36,7 +36,10 @@ export interface FileSystemPort {
     /** Modification time in epoch ms — for recency-based retention pruning. Rejects if absent. */
     stat(path: string): Promise<{
         mtimeMs: number;
+        size: number;
     }>;
+    /** Resolve symlinks to their real path — for upload trust-boundary checks. Rejects if absent. */
+    realpath(path: string): Promise<string>;
     /** ENOENT classifier — narrows unknown without `any`, so callers can distinguish missing-file. */
     isNotFound(error: unknown): boolean;
 }

package/dist/project/fs-port.js

@@ -1,4 +1,4 @@
-import { access, appendFile, mkdir, open, readdir, readFile, rename, rm, stat, writeFile, } from 'node:fs/promises';
+import { access, appendFile, mkdir, open, readdir, readFile, realpath, rename, rm, stat, writeFile, } from 'node:fs/promises';
 /** Production adapter — the single import site of node:fs/promises in the server. */
 export function createNodeFileSystem() {
     return {
@@ -46,8 +46,9 @@ export function createNodeFileSystem() {
         },
         stat: async (path) => {
             const s = await stat(path);
-            return { mtimeMs: s.mtimeMs };
+            return { mtimeMs: s.mtimeMs, size: s.size };
         },
+        realpath: (path) => realpath(path),
         isNotFound: (error) => 'ENOENT' === error?.code,
     };
 }

package/dist/project/memory-fs.js

@@ -78,7 +78,12 @@ export function createMemoryFs() {
             return Promise.resolve();
         },
         stat(path) {
-            return written.has(norm(path)) ? Promise.resolve({ mtimeMs: 0 }) : Promise.reject(notFound());
+            return written.has(norm(path))
+                ? Promise.resolve({ mtimeMs: 0, size: 0 })
+                : Promise.reject(notFound());
+        },
+        realpath(path) {
+            return written.has(norm(path)) ? Promise.resolve(norm(path)) : Promise.reject(notFound());
         },
         isNotFound(error) {
             return 'ENOENT' === error?.code;

package/dist/project/project-tools.js

@@ -1,9 +1,10 @@
 import { z } from 'zod';
-import { ProjectReadError, RunKind, RunStatus } from '@reticlehq/core';
+import { ProjectReadError, RunStatus } from '@reticlehq/core';
 import { ReticleTool } from '../tools/tool-names.js';
+import { countSchema } from '../tools/numeric-bounds.js';
 import { sessionIdShape } from '../tools/tool-kit.js';
 import { asNumber, asString } from '../tools/tools-helpers.js';
-import { fetchProjectRegressionFromCloud, resolveCloudConfig } from '../cloud/cloud-sync.js';
+import { cloudFetch, fetchProjectRegressionFromCloud, resolveCloudConfig, } from '../cloud/cloud-sync.js';
 import { RunStore } from '../runs/run-store.js';
 import { diffRuns as diffVerificationRuns, } from '../runs/run-diff.js';
 const REGRESSION_STATUSES = new Set([
@@ -45,7 +46,7 @@ async function cloudRegression(deps, sessionId) {
     catch {
         projectId = undefined;
     }
-    const report = await fetchProjectRegressionFromCloud(config, projectId, (url, init) => fetch(url, init));
+    const report = await fetchProjectRegressionFromCloud(config, projectId, cloudFetch);
     return report ?? undefined;
 }
 /** The two most-recent runs for `name`, oldest-first, or undefined if there are fewer than two. */
@@ -84,11 +85,10 @@ async function lastTwoRunArtifacts(deps) {
 export const PROJECT_TOOLS = [
     {
         name: ReticleTool.PROJECT,
-        description: 'Read cross-run history from .reticle/project.json — the memory of how past runs behaved. With { name } it also returns the last run for that flow plus a diff-vs-last summary (status change, regressed flag, consoleErrors/driftSteps deltas) so you can answer "did it behave like last time?". `diff` is the lightweight status/console/drift delta vs the previous run of that NAME; `runDiff` is the per-flow duration/status delta between the two most-recent full verification artifacts ("step 3: 412ms -> 987ms (+140%), +2 requests"). When logged in to Reticle Cloud, also returns `cloud`: the team\'s server-side regression report (broken/changed flows vs before) — the durable memory a fresh or context-lost agent can rely on even when local history is empty. Returns { runs, learned?, lastRun?, diff?, runDiff?, cloud? } or { error, reason, cloud? }.',
+        description: 'Read cross-run history from .reticle/project.json — the memory of how past runs behaved. With { name } it also returns the last run for that flow plus a diff-vs-last summary (status change, regressed flag, consoleErrors/driftSteps deltas) so you can answer "did it behave like last time?". `diff` is the lightweight status/console/drift delta vs the previous run of that NAME; `runDiff` is the per-flow duration/status delta between the two most-recent full verification artifacts ("step 3: 412ms -> 987ms (+140%), +2 requests"). When logged in to Reticle, also returns `cloud`: the team\'s server-side regression report (broken/changed flows vs before) — the durable memory a fresh or context-lost agent can rely on even when local history is empty. Returns { runs, learned?, lastRun?, diff?, runDiff?, cloud? } or { error, reason, cloud? }.',
         inputSchema: {
             name: z.string().optional().describe('Filter runs by this name. Omit to return all runs.'),
-            limit: z
-                .number()
+            limit: countSchema
                 .optional()
                 .describe('Most-recent N runs to return. Defaults to 25 — the full history is unbounded and grows with every run (measured at ~20KB / ~5,000 tokens on a modest project), which is a large slice of an agent context for data it mostly does not read. `totalRuns` always reports the true count, so a cap is never silent.'),
             ...sessionIdShape,
@@ -152,33 +152,4 @@ export const PROJECT_TOOLS = [
             });
         },
     },
-    {
-        name: ReticleTool.RUN_RECORD,
-        description: 'Explicitly record a run outcome into .reticle/project.json (the manual companion to the auto-record on reticle_flow_replay). Use it to log the result of an assertion sequence or a manual journey so future runs can diff against it. Returns { recorded:true, name, status }.',
-        inputSchema: {
-            name: z.string().describe('Run name for grouping in reticle_project history.'),
-            status: z.nativeEnum(RunStatus).describe('Outcome: pass | fail | drift | error'),
-            kind: z.nativeEnum(RunKind).optional(),
-            summary: z.string().optional().describe('One-line human summary of what this run covered.'),
-            ...sessionIdShape,
-        },
-        outputSchema: {
-            recorded: z.boolean(),
-            runName: z.string(),
-            status: z.string(),
-        },
-        handler: async (deps, args) => {
-            const name = asString(args['name']) ?? '';
-            const status = args['status'];
-            const kindArg = args['kind'];
-            const summary = asString(args['summary']);
-            await deps.project.recordRun({
-                kind: 'string' === typeof kindArg ? kindArg : RunKind.MANUAL,
-                name,
-                status,
-                ...(summary !== undefined ? { summary } : {}),
-            });
-            return { recorded: true, runName: name, status };
-        },
-    },
 ];

package/dist/project/reticle-dir.d.ts

@@ -15,6 +15,8 @@ export interface ReticleDirPaths {
     project: string;
     /**.../.reticle/impact.json (what Reticle has done for this user, local only) */
     impact: string;
+    /**.../.reticle/intent.json (what changes were supposed to make true — git-checked) */
+    intent: string;
     /**.../.reticle/visual (PNG baselines + diffs) */
     visual: string;
     /**.../.reticle/runs (verification-run artifacts) */
@@ -53,9 +55,22 @@ export declare function isValidSessionId(sessionId: string): sessionId is Sessio
  */
 export declare function isValidRunId(runId: string): runId is RunId;
 /** The PNG baseline path for `name`.reticle/visual/<name>.png). */
-export declare function visualPath(root: string, name: string): string;
+export declare function visualPath(root: string, name: string, runtime?: string): string;
+/**
+ * The directory a visual artifact belongs in, scoped by the runtime that produced it.
+ *
+ * An Electron window, a Tauri webview and a browser tab render the same url differently — different
+ * chrome, different fonts, a different device pixel ratio, a webview that is not the browser at all.
+ * One shared baseline makes every cross-runtime diff wrong, and the quiet direction is the dangerous
+ * one: a baseline overwritten from another runtime turns a later real regression into a pass.
+ *
+ * Scoped the way flows already are. A DESKTOP runtime gets a subdir; web, an unknown runtime, and
+ * everything captured before this existed stay on the flat path — the SDK has no screenshotter, so
+ * every pre-existing baseline came from a driven browser, and moving them would orphan them.
+ */
+export declare function visualDir(root: string, runtime?: string): string;
 /** The overlay-diff PNG path for `name`.reticle/visual/<name>.diff.png). */
-export declare function visualDiffPath(root: string, name: string): string;
+export declare function visualDiffPath(root: string, name: string, runtime?: string): string;
 /**
  * Path to a flow file. With a `projectId`, the flow lives in a per-project subdir
  * (`.reticle/flows/<projectId>/<name>.json`) so a shared daemon serving many apps can't collide two

package/dist/project/reticle-dir.js

@@ -1,4 +1,5 @@
 import { join } from 'node:path';
+import { AppRuntime } from '@reticlehq/core';
 import { CONTRACT_FILE_VERSION, ContractFileSchema, ContractReadError, FLOW_NAME_PATTERN, ReticleDir, } from '@reticlehq/core';
 export function reticleDirPaths(root) {
     return {
@@ -8,6 +9,7 @@ export function reticleDirPaths(root) {
         baselines: join(root, ReticleDir.BASELINES_SUBDIR),
         project: join(root, ReticleDir.PROJECT_FILE),
         impact: join(root, ReticleDir.IMPACT_FILE),
+        intent: join(root, ReticleDir.INTENT_FILE),
         visual: join(root, ReticleDir.VISUAL_SUBDIR),
         runs: join(root, ReticleDir.RUNS_SUBDIR),
         sessions: join(root, ReticleDir.SESSIONS_SUBDIR),
@@ -50,12 +52,28 @@ export function isValidRunId(runId) {
     return FLOW_NAME_PATTERN.test(runId) && !runId.includes('..');
 }
 /** The PNG baseline path for `name`.reticle/visual/<name>.png). */
-export function visualPath(root, name) {
-    return join(root, ReticleDir.VISUAL_SUBDIR, `${name}.png`);
+export function visualPath(root, name, runtime) {
+    return join(visualDir(root, runtime), `${name}.png`);
+}
+/**
+ * The directory a visual artifact belongs in, scoped by the runtime that produced it.
+ *
+ * An Electron window, a Tauri webview and a browser tab render the same url differently — different
+ * chrome, different fonts, a different device pixel ratio, a webview that is not the browser at all.
+ * One shared baseline makes every cross-runtime diff wrong, and the quiet direction is the dangerous
+ * one: a baseline overwritten from another runtime turns a later real regression into a pass.
+ *
+ * Scoped the way flows already are. A DESKTOP runtime gets a subdir; web, an unknown runtime, and
+ * everything captured before this existed stay on the flat path — the SDK has no screenshotter, so
+ * every pre-existing baseline came from a driven browser, and moving them would orphan them.
+ */
+export function visualDir(root, runtime) {
+    const visual = join(root, ReticleDir.VISUAL_SUBDIR);
+    return runtime === undefined || AppRuntime.WEB === runtime ? visual : join(visual, runtime);
 }
 /** The overlay-diff PNG path for `name`.reticle/visual/<name>.diff.png). */
-export function visualDiffPath(root, name) {
-    return join(root, ReticleDir.VISUAL_SUBDIR, `${name}.diff.png`);
+export function visualDiffPath(root, name, runtime) {
+    return join(visualDir(root, runtime), `${name}.diff.png`);
 }
 /**
  * Path to a flow file. With a `projectId`, the flow lives in a per-project subdir

package/dist/runs/context-tools.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDef } from '../tools/tool-kit.js';
+export declare const CONTEXT_TOOLS: ToolDef[];