@reticlehq/server 2.13.0 → 2.14.0

package/dist/pool/browser-pool.js

@@ -11,6 +11,7 @@
  */
 /** The minimal page surface the pool drives. Real Playwright `Page` satisfies this. */
 import { unreachableUrlIn } from '@reticlehq/core';
+import { seedStorageInto } from './storage-seed.js';
 /** 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). */
@@ -147,7 +148,26 @@ export class BrowserPool {
             return;
         this.#aliases.set(registeredId, leaseId);
     }
-    /** The lease this id refers to: itself, or whatever it is an alias for. */
+    /**
+     * The lease this id refers to: itself, or whatever it is an alias for.
+     *
+     * EVERY AGENT-FACING LOOKUP MUST GO THROUGH THIS. A leased page runs the SDK, which dials and
+     * registers under its OWN session id, so the id `reticle_sessions` shows an agent is routinely the
+     * alias rather than the lease key. Four capabilities used the raw map instead — screenshots,
+     * hover, network mocks and the dial-failure diagnostic — and every one of them refused for a
+     * lease that was alive and working, addressed by the only id the agent had been given.
+     *
+     * `reticle_network_mock` is where that surfaced: it reported `no-cdp-provider` in every
+     * configuration a reporter could reach, including after `reticle drive`, and the recommendation it
+     * printed ("start with `reticle drive <url>`") could not fix it because the provider was never the
+     * problem. Their conclusion was that error-path verification was impossible without shipping
+     * failure-injection code inside the application — which is exactly what an external mock exists to
+     * avoid.
+     *
+     * `acquire` and `#release` are the two exceptions and must stay raw: the first is registering the
+     * lease key itself before any alias can exist, and the second must delete that key rather than
+     * whatever it points at.
+     */
     #leaseIdOf(sessionId) {
         return this.#active.has(sessionId) ? sessionId : (this.#aliases.get(sessionId) ?? sessionId);
     }
@@ -172,7 +192,7 @@ export class BrowserPool {
      * reaper take it out from under a diff.
      */
     async screenshotLease(sessionId, opts = {}) {
-        const lease = this.#active.get(sessionId);
+        const lease = this.#active.get(this.#leaseIdOf(sessionId));
         if (lease === undefined || lease.page.screenshot === undefined)
             return undefined;
         this.touch(sessionId);
@@ -193,7 +213,7 @@ export class BrowserPool {
      * Touches the lease like any other tool call, so hovering keeps it alive.
      */
     async hoverLease(sessionId, x, y) {
-        const lease = this.#active.get(sessionId);
+        const lease = this.#active.get(this.#leaseIdOf(sessionId));
         if (lease === undefined || lease.page.hover === undefined)
             return false;
         this.touch(sessionId);
@@ -205,6 +225,46 @@ export class BrowserPool {
             return false;
         }
     }
+    /**
+     * Install network mocks on a leased page, or false when this session is not a lease or cannot
+     * intercept. Same optional-capability contract as screenshotLease: absence must read as "could not
+     * mock", never as a stub that applied to nothing.
+     *
+     * Touches the lease like any other tool call, so mocking keeps it alive.
+     */
+    /**
+     * Resize a leased page's viewport, or report that this page cannot be resized.
+     *
+     * Alias-resolved like every other agent-facing capability — see `#leaseIdOf`.
+     *
+     * Touches the lease like any other tool call, so resizing keeps it alive.
+     */
+    async setViewportLease(sessionId, size) {
+        const lease = this.#active.get(this.#leaseIdOf(sessionId));
+        if (lease === undefined || lease.page.setViewport === undefined)
+            return false;
+        this.touch(sessionId);
+        try {
+            await lease.page.setViewport(size);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async setMocksLease(sessionId, rules) {
+        const lease = this.#active.get(this.#leaseIdOf(sessionId));
+        if (lease === undefined || lease.page.installMocks === undefined)
+            return false;
+        this.touch(sessionId);
+        try {
+            await lease.page.installMocks(rules);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     async sweepExpired() {
         const now = this.#now();
         const expired = [...this.#active.entries()]
@@ -259,6 +319,7 @@ export class BrowserPool {
         const sessionId = opts.sessionId ?? this.#genId();
         let context;
         let pending;
+        let pendingDialogMessage;
         try {
             const browser = await this.#ensureBrowser();
             context = await browser.newContext();
@@ -281,23 +342,69 @@ export class BrowserPool {
                 else
                     pending = dialled; // logged during goto, before the lease is registered below
             });
-            await page.goto(url, { timeoutMs: this.#navTimeout });
+            // Same "listen before goto" reasoning as onConsole above: a dialog opened during the initial
+            // navigation (an app that confirms something in an onload handler) must still be dismissed, not
+            // just ones opened after the lease is registered.
+            page.onDialog?.((dialog) => {
+                const active = this.#active.get(sessionId);
+                if (active !== undefined)
+                    active.lastDialogMessage = dialog.message;
+                else
+                    pendingDialogMessage = dialog.message;
+                void dialog.dismiss();
+            });
+            let seedHandle;
+            let checkSeedError;
+            if (opts.seedStorage !== undefined) {
+                const seedResult = await seedStorageInto(context, page, url, opts.seedStorage);
+                seedHandle = seedResult?.handle;
+                checkSeedError = seedResult?.checkError;
+            }
+            let navRes;
+            try {
+                navRes = await page.goto(url, { timeoutMs: this.#navTimeout });
+                checkSeedError?.();
+            }
+            finally {
+                if (seedHandle !== undefined) {
+                    await seedHandle.dispose().catch(() => undefined);
+                }
+            }
             // 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
             // the slot count out of sync (drifting below #active.size, eventually exceeding the cap). If we're
             // 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');
+            let navStatus;
+            if (null !== navRes && 'object' === typeof navRes && 'status' in navRes) {
+                const s = navRes.status;
+                if ('function' === typeof s) {
+                    try {
+                        const code = s.call(navRes);
+                        if ('number' === typeof code)
+                            navStatus = code;
+                    }
+                    catch {
+                        // ignore
+                    }
+                }
+                else if ('number' === typeof s) {
+                    navStatus = s;
+                }
+            }
             this.#active.set(sessionId, {
                 context,
                 page,
                 url,
                 touchedAt: this.#now(),
                 ...(pending === undefined ? {} : { dialFailureUrl: pending }),
+                ...(pendingDialogMessage === undefined ? {} : { lastDialogMessage: pendingDialogMessage }),
             });
             return {
                 sessionId,
                 url,
+                ...(navStatus !== undefined ? { navStatus } : {}),
                 release: () => this.#release(sessionId),
             };
         }
@@ -316,7 +423,14 @@ export class BrowserPool {
      * Undefined means the page said nothing — never that it dialled the right place.
      */
     dialFailureUrl(sessionId) {
-        return this.#active.get(sessionId)?.dialFailureUrl;
+        return this.#active.get(this.#leaseIdOf(sessionId))?.dialFailureUrl;
+    }
+    /**
+     * The message of the most recent native dialog (`confirm`/`alert`/`prompt`) auto-dismissed on this
+     * lease, if any. Diagnostic only — the dialog itself is already gone by the time this is readable.
+     */
+    lastDialogMessage(sessionId) {
+        return this.#active.get(this.#leaseIdOf(sessionId))?.lastDialogMessage;
     }
     /** Close every context and the browser. Pending waiters are rejected (the pool is terminal now). */
     async shutdown() {

package/dist/pool/playwright-launcher.js

@@ -5,11 +5,12 @@
  *
  * Headless by default — the pool exists for fault-tolerant headless multi-agent testing.
  */
-import { BrowserLaunchKind } from '@reticlehq/core';
+import { BrowserLaunchKind } from '@reticlehq/core/telemetry';
 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';
+import { chromiumInstallCommand, chromiumInstallDepsCommand, bundledPlaywrightVersion, } from '../cli/chromium-hint.js';
+import { installNetworkMocks } from '../input/network-mock.js';
 /**
  * How a leased tab navigates. Pure, and exported, because the decision in it is worth a test while
  * the rest of this file needs a real Chromium.
@@ -49,10 +50,22 @@ function wrapBrowser(browser) {
                             await page.mouse.move(x + 1, y);
                             await page.mouse.move(x, y);
                         },
+                        installMocks: (rules) => installNetworkMocks(page, [...rules]),
+                        setViewport: (size) => page.setViewportSize(size),
                         onCrash: (handler) => page.on('crash', handler),
                         onConsole: (handler) => page.on('console', (msg) => handler(msg.text())),
+                        onDialog: (handler) => page.on('dialog', (dialog) => handler({ message: dialog.message(), dismiss: () => dialog.dismiss() })),
+                        addInitScript: async (script, arg) => {
+                            const handle = (await page.addInitScript(script, arg));
+                            const dispose = handle?.dispose;
+                            if ('function' !== typeof dispose) {
+                                throw new Error('Storage seeding failed: Playwright page.addInitScript did not return a disposable handle');
+                            }
+                            return { dispose: () => dispose() };
+                        },
                     };
                 },
+                addCookies: (cookies) => context.addCookies(cookies),
                 close: () => context.close(),
             };
         },
@@ -69,6 +82,14 @@ function wrapBrowser(browser) {
  * two cannot suggest different commands for the same missing browser.
  */
 const CHROMIUM_MISSING_HINT = `Chromium is not installed for Playwright. Run: ${chromiumInstallCommand(bundledPlaywrightVersion())}`;
+/**
+ * A DIFFERENT first-run failure from the one above: the browser binary is already there, but the
+ * host is missing the OS-level shared libraries (e.g. `libnspr4.so`) Playwright's own
+ * host-requirement check refuses to launch without. `npx playwright install chromium` does nothing
+ * for this — it re-downloads a binary that was never the problem — so this needs its own hint
+ * pointing at `install-deps`, pinned the same way and for the same reason as the one above.
+ */
+const CHROMIUM_MISSING_DEPS_HINT = `Chromium is installed, but the host system is missing shared-library dependencies it needs. Run: ${chromiumInstallDepsCommand(bundledPlaywrightVersion())}`;
 /** A Launcher that boots a real headless Chromium and adapts it to the pool's interface. */
 export function playwrightLauncher(opts = {}) {
     const headless = opts.headless ?? true;
@@ -91,6 +112,12 @@ export function playwrightLauncher(opts = {}) {
             settle(classifyConnectFailure(err));
             // Turn Playwright's raw "Executable doesn't exist" into the one command that fixes it.
             const msg = err instanceof Error ? err.message : String(err);
+            // Checked FIRST: Playwright's host-requirement validation error also contains
+            // "browserType.launch", so the generic check below would otherwise misdiagnose it as a
+            // missing binary and send the user through a fix that changes nothing.
+            if (/host system is missing dependencies/i.test(msg)) {
+                throw new Error(CHROMIUM_MISSING_DEPS_HINT);
+            }
             if (/executable doesn.?t exist|playwright install|browsertype\.launch/i.test(msg)) {
                 throw new Error(CHROMIUM_MISSING_HINT);
             }

package/dist/pool/storage-seed.d.ts

@@ -0,0 +1,23 @@
+import { type SeedStorage } from '@reticlehq/core';
+import type { InitScriptHandle, PooledContext, PooledCookie, PooledPage } from './browser-pool.js';
+export declare function targetOriginOf(navUrl: string): string | undefined;
+export declare function normalizeCookies(cookies: SeedStorage['cookies'], navUrl: string): PooledCookie[];
+export interface StorageSeedResult {
+    handle?: InitScriptHandle;
+    checkError?: () => void;
+}
+/**
+ * Seed initial storage state (cookies, localStorage, sessionStorage) into a leased context and page
+ * before the first navigation happens.
+ *
+ * Cookies are injected into the BrowserContext cookie jar so the initial HTTP GET to the target URL
+ * already carries the Cookie header (including httpOnly session cookies).
+ *
+ * Local and session storage are injected via an init script evaluated after document creation but
+ * before any inline or bundled application scripts run. The init script is scoped strictly to the
+ * top-level target origin document (not child iframes or external redirect origins).
+ *
+ * Returns a handle that allows the caller to dispose of the init script once the initial navigation
+ * has resolved, ensuring one-time semantics (reloads or future navigations do not reapply the seed).
+ */
+export declare function seedStorageInto(context: PooledContext, page: PooledPage, targetUrl: string, seed: SeedStorage): Promise<StorageSeedResult | void>;

package/dist/pool/storage-seed.js

@@ -0,0 +1,198 @@
+import { REDACTED_VALUE, scrubKnownSecrets } from '@reticlehq/core';
+export function targetOriginOf(navUrl) {
+    try {
+        const origin = new URL(navUrl).origin;
+        return origin !== 'null' ? origin : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function normalizeCookies(cookies, navUrl) {
+    if (cookies === undefined)
+        return [];
+    let baseUrl;
+    try {
+        const u = new URL(navUrl);
+        baseUrl = `${u.protocol}//${u.host}/`;
+    }
+    catch {
+        baseUrl = undefined;
+    }
+    const out = [];
+    if (Array.isArray(cookies)) {
+        for (const c of cookies) {
+            const cookieObj = {
+                name: c.name,
+                value: c.value,
+            };
+            if (c.domain !== undefined)
+                cookieObj.domain = c.domain;
+            if (c.path !== undefined) {
+                cookieObj.path = c.path;
+            }
+            else if (c.domain !== undefined && c.url === undefined) {
+                cookieObj.path = '/';
+            }
+            if (c.url !== undefined) {
+                cookieObj.url = c.url;
+            }
+            else if (c.domain === undefined && baseUrl !== undefined) {
+                cookieObj.url = baseUrl;
+            }
+            if (c.httpOnly !== undefined)
+                cookieObj.httpOnly = c.httpOnly;
+            if (c.secure !== undefined)
+                cookieObj.secure = c.secure;
+            if (c.sameSite !== undefined)
+                cookieObj.sameSite = c.sameSite;
+            if (c.expires !== undefined)
+                cookieObj.expires = c.expires;
+            out.push(cookieObj);
+        }
+    }
+    else if ('object' === typeof cookies && null !== cookies) {
+        for (const [name, value] of Object.entries(cookies)) {
+            const cookieObj = {
+                name,
+                value,
+            };
+            if (baseUrl !== undefined) {
+                cookieObj.url = baseUrl;
+            }
+            else {
+                cookieObj.path = '/';
+            }
+            out.push(cookieObj);
+        }
+    }
+    return out;
+}
+/**
+ * Seed initial storage state (cookies, localStorage, sessionStorage) into a leased context and page
+ * before the first navigation happens.
+ *
+ * Cookies are injected into the BrowserContext cookie jar so the initial HTTP GET to the target URL
+ * already carries the Cookie header (including httpOnly session cookies).
+ *
+ * Local and session storage are injected via an init script evaluated after document creation but
+ * before any inline or bundled application scripts run. The init script is scoped strictly to the
+ * top-level target origin document (not child iframes or external redirect origins).
+ *
+ * Returns a handle that allows the caller to dispose of the init script once the initial navigation
+ * has resolved, ensuring one-time semantics (reloads or future navigations do not reapply the seed).
+ */
+export async function seedStorageInto(context, page, targetUrl, seed) {
+    const hasCookies = seed.cookies !== undefined &&
+        (Array.isArray(seed.cookies) ? seed.cookies.length > 0 : Object.keys(seed.cookies).length > 0);
+    const hasLocal = seed.local !== undefined && Object.keys(seed.local).length > 0;
+    const hasSession = seed.session !== undefined && Object.keys(seed.session).length > 0;
+    if (hasCookies && context.addCookies === undefined) {
+        throw new Error('Storage seeding failed: browser context does not support cookie seeding');
+    }
+    if ((hasLocal || hasSession) && page.addInitScript === undefined) {
+        throw new Error('Storage seeding failed: page does not support storage seeding via init script');
+    }
+    if (hasCookies && context.addCookies !== undefined) {
+        const cookiesToSet = normalizeCookies(seed.cookies, targetUrl);
+        if (cookiesToSet.length > 0) {
+            try {
+                await context.addCookies(cookiesToSet);
+            }
+            catch (err) {
+                let rawMsg = err instanceof Error ? err.message : String(err);
+                for (const c of cookiesToSet) {
+                    if (undefined !== c.value && 'string' === typeof c.value && 0 !== c.value.length) {
+                        const escaped = c.value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+                        rawMsg = rawMsg.replace(new RegExp(`(^|[^a-zA-Z0-9])${escaped}(?=$|[^a-zA-Z0-9])`, 'g'), `$1${REDACTED_VALUE}`);
+                    }
+                }
+                rawMsg = scrubKnownSecrets(rawMsg);
+                throw new Error(`Storage seeding failed: cookie injection failed (${rawMsg})`);
+            }
+        }
+    }
+    let handle;
+    let capturedError;
+    if (hasLocal || hasSession) {
+        page.onConsole?.((text) => {
+            if (text.startsWith('__reticle_seed_error:')) {
+                capturedError = text.slice('__reticle_seed_error:'.length);
+            }
+        });
+        const targetOrigin = targetOriginOf(targetUrl);
+        const added = await page.addInitScript?.(({ local, session, targetOrigin, }) => {
+            const win = (globalThis.window ??
+                globalThis);
+            // Only seed the top-level document frame
+            if (win.top !== win)
+                return;
+            // Only seed when the page is at the intended target origin
+            if (undefined !== targetOrigin && win.location?.origin !== targetOrigin)
+                return;
+            let seedError;
+            if (undefined !== local) {
+                try {
+                    const storage = win.localStorage;
+                    if (!storage) {
+                        seedError = 'localStorage is not available';
+                    }
+                    else {
+                        for (const [k, v] of Object.entries(local)) {
+                            storage.setItem(k, v);
+                        }
+                    }
+                }
+                catch (err) {
+                    let errName = 'write error';
+                    if (null !== err && 'object' === typeof err && 'name' in err) {
+                        const name = err.name;
+                        if ('string' === typeof name) {
+                            errName = name;
+                        }
+                    }
+                    seedError = `localStorage write failed: ${errName}`;
+                }
+            }
+            if (undefined === seedError && undefined !== session) {
+                try {
+                    const storage = win.sessionStorage;
+                    if (!storage) {
+                        seedError = 'sessionStorage is not available';
+                    }
+                    else {
+                        for (const [k, v] of Object.entries(session)) {
+                            storage.setItem(k, v);
+                        }
+                    }
+                }
+                catch (err) {
+                    let errName = 'write error';
+                    if (null !== err && 'object' === typeof err && 'name' in err) {
+                        const name = err.name;
+                        if ('string' === typeof name) {
+                            errName = name;
+                        }
+                    }
+                    seedError = `sessionStorage write failed: ${errName}`;
+                }
+            }
+            if (undefined !== seedError) {
+                console.error(`__reticle_seed_error:${seedError}`);
+            }
+        }, { local: seed.local, session: seed.session, targetOrigin });
+        if (undefined === added || 'function' !== typeof added.dispose) {
+            throw new Error('Storage seeding failed: init script disposal is not supported by page');
+        }
+        handle = added;
+    }
+    const checkError = () => {
+        if (capturedError !== undefined) {
+            throw new Error(`Storage seeding failed: ${capturedError}`);
+        }
+    };
+    return {
+        ...(handle !== undefined ? { handle } : {}),
+        checkError,
+    };
+}

package/dist/project/artifact-root.d.ts

@@ -48,7 +48,7 @@ export declare const ArtifactRootReason: {
     readonly AMBIGUOUS: "ambiguous";
 };
 export type ArtifactRootReason = (typeof ArtifactRootReason)[keyof typeof ArtifactRootReason];
-export interface ArtifactRootQuery {
+interface ArtifactRootQuery {
     /** The connected session's HELLO projectId, when it sent one. */
     projectId: string | undefined;
     /** Every project this machine knows about. Supplied, not gathered here — this stays pure. */
@@ -81,3 +81,4 @@ export declare function resolveArtifactRoot(query: ArtifactRootQuery): ArtifactR
  * the one confirmed a moment ago is the better survivor.
  */
 export declare function projectCandidatesFrom(discovery: ConfigDiscovery, registry: ProjectRegistry): ProjectCandidate[];
+export {};

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

@@ -1,5 +1,5 @@
 import type { FileSystemPort } from './fs-port.js';
-export interface MemoryFs {
+interface MemoryFs {
     fs: FileSystemPort;
     /** Every file written, keyed by normalised absolute path. */
     written: Map<string, string>;
@@ -7,3 +7,4 @@ export interface MemoryFs {
     dirs: Set<string>;
 }
 export declare function createMemoryFs(): MemoryFs;
+export {};

package/dist/project/reticle-dir.js

@@ -1,5 +1,5 @@
 import { join } from 'node:path';
-import { AppRuntime } from '@reticlehq/core';
+import { AppRuntime } from '@reticlehq/core/telemetry';
 import { CONTRACT_FILE_VERSION, ContractFileSchema, ContractReadError, FLOW_NAME_PATTERN, ReticleDir, } from '@reticlehq/core';
 export function reticleDirPaths(root) {
     return {

package/dist/project/session-root.d.ts

@@ -13,3 +13,11 @@ import type { ToolDeps } from '../tools/tool-kit.js';
  * behaviour every call site had before the resolver existed.
  */
 export declare function sessionRoot(deps: ToolDeps, sessionId: string | undefined): string;
+/**
+ * The connected session's projectId, or undefined when there is no session to ask.
+ *
+ * `sessions.resolve` throws when nothing is connected, when the id names no session, and when
+ * several are connected and none was named. All three mean the same thing here — we cannot tell
+ * which project this call is about — and none of them is a reason to fail the caller's tool.
+ */
+export declare function sessionProjectId(deps: ToolDeps, sessionId: string | undefined): string | undefined;

package/dist/project/session-root.js

@@ -12,7 +12,7 @@
  * behaviour every call site had before the resolver existed.
  */
 export function sessionRoot(deps, sessionId) {
-    return deps.artifactRootFor?.(sessionProjectIdOf(deps, sessionId)).root ?? deps.reticleRoot;
+    return deps.artifactRootFor?.(sessionProjectId(deps, sessionId)).root ?? deps.reticleRoot;
 }
 /**
  * The connected session's projectId, or undefined when there is no session to ask.
@@ -21,7 +21,14 @@ export function sessionRoot(deps, sessionId) {
  * several are connected and none was named. All three mean the same thing here — we cannot tell
  * which project this call is about — and none of them is a reason to fail the caller's tool.
  */
-function sessionProjectIdOf(deps, sessionId) {
+/*
+ * Exported alongside `sessionRoot`, and that is the point rather than a convenience. A caller that
+ * takes the ROOT from the session and the PROJECT ID from somewhere else has resolved half an
+ * address, which is the defect the comment above predicted and `loadNamedFlows` then shipped: it
+ * read the id from `readProjectId(process.cwd())` while its root came from here. Both halves come
+ * from this file so they cannot disagree again.
+ */
+export function sessionProjectId(deps, sessionId) {
     try {
         return deps.sessions.resolve(sessionId).projectId;
     }

package/dist/runs/reticle-runner.d.ts

@@ -9,7 +9,7 @@
  * top of this — the orchestration and the verdict live here so the MCP path and the API produce the
  * same artifact byte-for-byte.
  */
-import type { FlowReplayResult, ReticleVerificationRun, RunId } from '@reticlehq/core';
+import { type FlowReplayResult, type ReticleVerificationRun, type RunId, type VerifyProgressEvent } from '@reticlehq/core';
 import { type VerificationRunInput } from './build-verification-run.js';
 import { type ChangedFileInput, type RiskPolicy } from './risk-classify.js';
 /** The live capabilities ReticleRunner needs. Injected so tests pass fakes (no CDP, no session). */
@@ -23,6 +23,14 @@ export interface RunnerPort {
     /** Injected run-id generator (no Math.random in logic) — the live adapter supplies a branded uuid. */
     newRunId(): RunId;
 }
+/**
+ * Narration for a run in flight. Optional, and never load-bearing.
+ *
+ * A verification is silent for its whole duration, so anything watching from outside cannot tell a
+ * run that is working from one that has died. This is the seam that makes the difference visible.
+ * It reports what is HAPPENING; the artifact remains the only record of what was PROVED.
+ */
+export type VerifyProgressListener = (event: VerifyProgressEvent) => void;
 /** Run metadata the caller supplies; flows + verdict are produced by verify. */
 export interface VerifyOptions {
     names?: string[];
@@ -34,6 +42,11 @@ export interface VerifyOptions {
     changedFiles?: ChangedFileInput[];
     /** Which touched surfaces block the verdict (require human confirmation). */
     policy?: RiskPolicy;
+    /**
+     * Called as each flow starts and finishes. Best-effort by contract: a listener that throws is
+     * swallowed, because a REPORTER must never be able to fail the thing it is reporting on.
+     */
+    onProgress?: VerifyProgressListener;
 }
 export declare class ReticleRunner {
     #private;

package/dist/runs/reticle-runner.js

@@ -10,6 +10,7 @@
  * same artifact byte-for-byte.
  */
 import { reportRunTelemetry } from '../telemetry/run-telemetry.js';
+import { boundFlowName, RunFlowStatus, VerifyPhase, } from '@reticlehq/core';
 import { buildVerificationRun } from './build-verification-run.js';
 import { mapReplayToFlowResult } from './replay-mapping.js';
 import { buildRepairPackets } from './repair-prompt.js';
@@ -26,14 +27,50 @@ export class ReticleRunner {
      */
     async verify(opts) {
         const names = opts.names ?? (await this.#port.listFlows());
+        /*
+         * Emitting NEVER throws into the run. A dashboard, a log or an editor is watching, and none of
+         * them is worth failing a verification for — so a listener that blows up is dropped here rather
+         * than unwinding a suite somebody is waiting on.
+         */
+        const emit = (event) => {
+            try {
+                opts.onProgress?.(event);
+            }
+            catch {
+                /* a reporter cannot fail the thing it reports on */
+            }
+        };
+        const total = names.length;
+        // Announced BEFORE the loop: "step 3" without "of 12" does not answer the only question a
+        // person watching is actually asking, which is whether to keep waiting.
+        emit({ phase: VerifyPhase.FLOWS_FOUND, total, at: this.#port.now() });
         const replays = [];
         const flows = [];
-        for (const name of names) {
+        for (const [index, name] of names.entries()) {
             const start = this.#port.now();
+            emit({
+                phase: VerifyPhase.FLOW_STARTED,
+                index,
+                total,
+                name: boundFlowName(name),
+                at: start,
+            });
             const replay = await this.#port.replayFlow(name);
             replays.push(replay);
-            flows.push(mapReplayToFlowResult(replay, this.#port.now() - start));
+            const mapped = mapReplayToFlowResult(replay, this.#port.now() - start);
+            flows.push(mapped);
+            emit({
+                phase: VerifyPhase.FLOW_FINISHED,
+                index,
+                total,
+                name: boundFlowName(name),
+                // A convenience for colouring a row while the run is live. The VERDICT is computed from the
+                // graded artifact below and never from this.
+                ok: mapped.status === RunFlowStatus.PASS,
+                at: this.#port.now(),
+            });
         }
+        emit({ phase: VerifyPhase.GRADING, total, at: this.#port.now() });
         const changedFiles = classifyChangedFiles(opts.changedFiles ?? []);
         const risks = buildRisks(changedFiles, opts.policy);
         const failurePackets = buildRepairPackets(replays);

package/dist/session/attachment-history.d.ts

@@ -16,7 +16,7 @@
  * needs to wait four seconds to check a four-second gap is a test nobody runs.
  */
 /** What an agent needs to know about the continuity of one session. */
-export interface Attachment {
+interface Attachment {
     /** How long THIS attachment has lasted. Resets on reconnect — it is not the session's lifetime. */
     connectedSinceMs: number;
     /** How many times this session dropped and came back. Zero means it never left. */
@@ -44,3 +44,4 @@ export declare class AttachmentHistory {
      */
     of(sessionId: string): Attachment | undefined;
 }
+export {};