@reticlehq/server 2.12.0 → 2.13.1

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

@@ -22,6 +22,21 @@ export interface PooledPage {
      * "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 {
@@ -74,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.
      *
@@ -101,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).

package/dist/pool/browser-pool.js

@@ -15,6 +15,11 @@ import { unreachableUrlIn } from '@reticlehq/core';
 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.
@@ -31,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();
@@ -73,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.
      *
@@ -116,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()]
@@ -124,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).

package/dist/pool/playwright-launcher.js

@@ -40,6 +40,15 @@ 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())),
                     };

package/dist/project/project-tools.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 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 { cloudFetch, fetchProjectRegressionFromCloud, resolveCloudConfig, } from '../cloud/cloud-sync.js';
@@ -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,

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

@@ -55,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 {
@@ -51,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/run-store.d.ts

@@ -19,6 +19,16 @@ export type ReadRunResult = {
 interface RunStoreOptions {
     retention?: number;
     slack?: number;
+    /**
+     * Called after a run artifact is safely on disk. Used to wake cloud sync so a finished
+     * verification reaches the dashboard promptly instead of waiting for the next timer tick.
+     *
+     * A callback rather than a dependency on the sync daemon: the store's job is durability, and a
+     * store that imported the cloud would make "write a run" fail whenever the cloud did. It is
+     * invoked AFTER the rename, so nothing can observe a run that is not yet readable, and it must
+     * never throw — see the call site.
+     */
+    onWrote?: () => void;
 }
 export declare class RunStore {
     #private;

package/dist/runs/run-store.js

@@ -15,11 +15,13 @@ export class RunStore {
     #root;
     #retention;
     #slack;
+    #onWrote;
     constructor(fs, root, opts = {}) {
         this.#fs = fs;
         this.#root = root;
         this.#retention = opts.retention ?? RUN_RETENTION;
         this.#slack = opts.slack ?? RUN_RETENTION_SLACK;
+        this.#onWrote = opts.onWrote;
     }
     /**
      * Write one run artifact. Creates .reticle/runs/ first; byte-stable (fixed indent + trailing newline).
@@ -37,6 +39,14 @@ export class RunStore {
         const tmp = `${path}${TMP_EXT}`;
         await this.#fs.writeFile(tmp, `${JSON.stringify(run, null, JSON_INDENT)}\n`);
         await this.#fs.rename(tmp, path);
+        // AFTER the rename: a listener that reads the run back must find it there. Swallowed, because
+        // this is a notification — a sync that cannot be woken must never fail the write it followed.
+        try {
+            this.#onWrote?.();
+        }
+        catch {
+            // Not this store's problem, and not worth failing a durable write over.
+        }
         await this.#pruneOld();
     }
     /**

package/dist/runs/verification-sync.d.ts

@@ -1,16 +1,5 @@
-/**
- * Turn an MCP verification (a `reticle_flow_verify` suite run) into a first-class ReticleVerificationRun:
- * assemble the artifact from the already-computed replays, persist it to .reticle/runs/ (so
- * `reticle_run_export` and CI can read it), and — when logged in (cloud creds set) — best-effort push it
- * to the cloud's `POST /v1/runs` so the team's dashboard Runs tab shows what the agent just verified.
- *
- * This is the artifact tier that maps to the dashboard's "Runs" (the OEM/CI-consumable verdict); the
- * lighter per-flow RunRecord that feeds regression memory is synced separately in flow-replay-run.ts.
- * Both are best-effort + opt-in: no creds → the artifact still lands on disk, nothing leaves the machine.
- */
 import { type FlowReplayResult } from '@reticlehq/core';
 import type { ToolDeps } from '../tools/tools.js';
-/** A replay plus the wall-clock time it took — the shape the verify handler already collects. */
 export interface TimedReplay {
     replay: FlowReplayResult;
     durationMs: number;

package/dist/runs/verification-sync.js

@@ -8,6 +8,7 @@
  * lighter per-flow RunRecord that feeds regression memory is synced separately in flow-replay-run.ts.
  * Both are best-effort + opt-in: no creds → the artifact still lands on disk, nothing leaves the machine.
  */
+import { mcpClientIdentity } from '../mcp/client-identity.js';
 import { RunAgentKind, RunFramework, RunProfile, RunTrigger, } from '@reticlehq/core';
 import { homedir } from 'node:os';
 import { buildVerificationRun } from './build-verification-run.js';
@@ -17,6 +18,9 @@ import { RunStore } from './run-store.js';
 import { cloudFetch, syncRunToCloud, SyncOutcome } from '../cloud/cloud-sync.js';
 import { resolveProjectCloud } from '../cloud/cloud-config.js';
 import { log } from '../log.js';
+/** A replay plus the wall-clock time it took — the shape the verify handler already collects. */
+/** The author of record when no MCP peer introduced itself — a CLI run, or a client that skipped the handshake. */
+const RETICLE_MCP_AGENT_ID = 'reticle-mcp';
 /** Assemble the ReticleVerificationRun artifact for a verify suite (pure — no IO). */
 function assembleRun(deps, timed, projectId) {
     const flows = timed.map((t) => mapReplayToFlowResult(t.replay, t.durationMs));
@@ -25,7 +29,20 @@ function assembleRun(deps, timed, projectId) {
         durationMs: flows.reduce((sum, f) => sum + f.durationMs, 0),
         profile: RunProfile.DEV,
         project: { name: projectId ?? 'reticle', framework: RunFramework.OTHER },
-        agent: { id: 'reticle-mcp', kind: RunAgentKind.CODING_AGENT },
+        /*
+         * WHICH agent drove this, not merely THAT one did.
+         *
+         * This was hardcoded to 'reticle-mcp', so every run in every workspace claimed the same author.
+         * A dashboard built on it could say "an agent verified this" and never "Claude Code verified
+         * this, Cursor broke it" — which is the question a team actually has once more than one agent
+         * touches the repo. The name is the client's own claim from the MCP handshake; a plain CLI run
+         * with no MCP peer keeps the old id, because inventing a vendor there would be worse than
+         * admitting we do not know.
+         */
+        agent: {
+            id: mcpClientIdentity().name ?? RETICLE_MCP_AGENT_ID,
+            kind: RunAgentKind.CODING_AGENT,
+        },
         trigger: { kind: RunTrigger.MANUAL },
         changedFiles: [],
         flows,
@@ -62,5 +79,9 @@ export async function persistAndSyncVerificationRun(deps, timed, projectId) {
     if (result.outcome !== SyncOutcome.SYNCED) {
         log('cloud-run-sync-failed', { runId: run.runId, status: result.status, error: result.error });
     }
+    // The run is up; its CONTEXT is not. Nudged rather than pushed inline, so the counters and flows
+    // ride the ordinary cycle (with its cursor and its overlap guard) instead of growing a second,
+    // subtly different upload path here.
+    deps.onRunPersisted?.();
     return run.runId;
 }

package/dist/runs/verify-server.d.ts

@@ -18,7 +18,14 @@ export interface VerifyServerOptions {
 }
 /** Build the request listener. Reads + size-caps the body, then hands off to the pure handler. */
 export declare function createVerifyRequestListener(opts: VerifyServerOptions): http.RequestListener;
-/** Start the verify server on localhost. Resolves once listening; returns the bound server + port. */
+/**
+ * Start the verify server on localhost. Resolves once listening; returns the bound server + port.
+ *
+ * A failed bind REJECTS, naming the verify port. It used to emit `'error'` with no listener, so an
+ * EADDRINUSE on `--http-port` crashed the daemon with a raw stack, and the parent `serve` reported
+ * only that the daemon "did not come up" on the BRIDGE port — the one port that was fine (#687).
+ * Rejecting lets the daemon's start-failure path say what actually could not be honoured.
+ */
 export declare function startVerifyServer(opts: VerifyServerOptions, port: number): Promise<{
     server: http.Server;
     port: number;

package/dist/runs/verify-server.js

@@ -83,13 +83,25 @@ async function writeResponse(req, res, opts, raw) {
     res.writeHead(result.status, JSON_HEADERS);
     res.end(JSON.stringify(result.body));
 }
-/** Start the verify server on localhost. Resolves once listening; returns the bound server + port. */
+/**
+ * Start the verify server on localhost. Resolves once listening; returns the bound server + port.
+ *
+ * A failed bind REJECTS, naming the verify port. It used to emit `'error'` with no listener, so an
+ * EADDRINUSE on `--http-port` crashed the daemon with a raw stack, and the parent `serve` reported
+ * only that the daemon "did not come up" on the BRIDGE port — the one port that was fine (#687).
+ * Rejecting lets the daemon's start-failure path say what actually could not be honoured.
+ */
 export function startVerifyServer(opts, port) {
     const server = http.createServer(createVerifyRequestListener(opts));
     server.requestTimeout = REQUEST_TIMEOUT_MS;
     server.headersTimeout = HEADERS_TIMEOUT_MS;
-    return new Promise((resolve) => {
+    return new Promise((resolve, reject) => {
+        const onError = (err) => {
+            reject(new Error(`the verify HTTP endpoint could not bind ${LOCALHOST}:${String(port)} — ${err.message}`));
+        };
+        server.once('error', onError);
         server.listen(port, LOCALHOST, () => {
+            server.removeListener('error', onError);
             const address = server.address();
             const boundPort = 'object' === typeof address && address !== null ? address.port : port;
             resolve({ server, port: boundPort });

package/dist/session/command-timeout.d.ts

@@ -9,8 +9,11 @@ import { AppRuntime } from '@reticlehq/core';
  * developer goes hunting through their own code for a fault that is not there.
  *
  * This advice previously blamed occlusion — "macOS suspends an occluded or off-Space WKWebView" —
- * which is false, and was the kind of wrong steer this function exists to prevent. A LOADED Tauri
- * webview keeps answering while minimized, app-hidden, occluded, and on another Space.
+ * which is false for those states, and was the kind of wrong steer this function exists to prevent.
+ * A LOADED Tauri webview keeps answering while minimized, occluded, and on another Space. `hide()`
+ * after load is the remaining headless path: a hidden macOS WKWebView has been observed to go quiet
+ * after a pause, but that is not something every machine demonstrates, so this message names it as
+ * a candidate rather than a fact.
  *
  * It then over-corrected: it asserted the hidden-before-load ordering as FACT. But the only evidence
  * here is `hidden === true` — the ordering is never observed. Measured on a Tauri shell pointed at an

package/dist/session/command-timeout.js

@@ -11,11 +11,12 @@ const ONE_WAY_ADVICE = 'The page is ALIVE — the SDK last reported to the bridg
     'replaced mid-session, a proxy buffering one way) rather than at your app.';
 const HIDDEN_ADVICE = 'The page last reported itself hidden, and this is a WKWebView (Tauri) window, so the webview is ' +
     'most likely not running the page at all. Two known causes, commonest first: (1) the window was ' +
-    'hidden BEFORE its first page load — a webview that has never been presented never loads, so hide ' +
+    'hidden BEFORE its first page load — a webview that has never been presented never loads, so park ' +
     'it from `on_page_load` instead of `setup` (see `reticle_tauri::on_page_load`, which does this for ' +
-    'RETICLE_HEADLESS=1); once the page HAS loaded, hiding it is safe. (2) the window never presented ' +
-    'for another reason — check that it is declared with a visible size and that the page URL actually ' +
-    'loaded. If neither fits, the page is reachable but not executing, which is worth reporting.';
+    'RETICLE_HEADLESS=1). (2) the window was hidden after load and then went quiet — that has been ' +
+    'observed on a hidden macOS WKWebView after a pause, even though capture still works; park it ' +
+    'off-screen rather than calling hide. If neither fits, the page is reachable but not executing, ' +
+    'which is worth reporting.';
 /** True when this session is a WebKit desktop shell — the only runtime that suffers this. */
 function isWebKitDesktop(context) {
     if (AppRuntime.TAURI === context.runtime)

package/dist/session/lease-visibility.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Telling the human that the agent went somewhere they cannot see.
+ *
+ * A lease is a separate pooled context, and it is the highest-value path in the product for
+ * autonomous work. It also has one failure mode that is entirely about people: the HUD lives in the
+ * human's OWN tab, so while an agent drives a lease that tab shows nothing at all. An idle agent and
+ * a busy one are then indistinguishable from the only seat a human occupies.
+ *
+ * That is not hypothetical. An agent followed the daemon's own throttle recommendation into a lease,
+ * drove fifteen calls, and the developer watching an empty HUD asked why nothing was running. The
+ * product was working perfectly and looked broken, which is the worst combination available.
+ *
+ * The fix rides on machinery that already exists — `pushNarration` posts `ReticleCommand.NARRATE`
+ * and every SDK in the field already renders it — so nothing here moves the wire contract. It is a
+ * message to tabs that are ALREADY connected, not a new capability.
+ */
+/** The minimum a session has to expose to be a candidate watcher. Structural, so tests need no SDK. */
+export interface WatcherCandidate {
+    id: string;
+    projectId: string | undefined;
+}
+/**
+ * Shown on a watching human's HUD when an agent takes a lease.
+ *
+ * States the fact and its consequence, because the fact alone ("agent leased a context") does not
+ * tell somebody why their screen is still. The consequence is the whole reason to say anything.
+ */
+export declare const AGENT_DRIVING_ELSEWHERE = "An agent is driving a separate leased context \u2014 its actions will not appear in this tab.";
+/** Shown when the lease is released, so a HUD that went quiet is explained in both directions. */
+export declare const AGENT_DRIVING_HERE_AGAIN = "The agent released its separate context \u2014 this tab is live again.";
+/**
+ * Shown to a tab that CONNECTS while a lease is already open.
+ *
+ * The acquire-time notice only reaches tabs that were already connected, so opening the app — or
+ * merely reloading it — during a lease landed somebody on a silent HUD with nothing explaining it.
+ * That is the same dark-HUD failure the acquire notice exists to prevent, arrived at from the other
+ * direction, and it is the more common one: a person opens the dashboard BECAUSE they want to watch.
+ *
+ * Worded for arrival rather than for a change of state — nothing just happened from this tab's point
+ * of view, so "an agent is driving elsewhere" would describe an event it never saw.
+ */
+export declare const AGENT_ALREADY_DRIVING_ELSEWHERE = "An agent is already driving a separate leased context \u2014 its actions will not appear in this tab.";
+/**
+ * Whether a session arriving now should be told a lease is already running.
+ *
+ * Same rules as `watchersToNotify`, expressed for one session: never tell a leased context about
+ * itself, and never tell somebody watching app A about a lease against app B.
+ */
+export declare function shouldGreetWithLeaseNotice(session: WatcherCandidate, leasedSessionIds: readonly string[], leasedProjectIds: readonly (string | undefined)[]): boolean;
+/**
+ * Which connected sessions belong to a human who should be told.
+ *
+ * Two exclusions, both deliberate:
+ *
+ * - Leased sessions. They ARE the agent's context; narrating "an agent is driving elsewhere" into
+ *   the tab doing the driving is noise, and with several leases open they would talk about each
+ *   other. Membership comes from the pool rather than an id prefix, because a naming convention is
+ *   not a fact and `pool.leasedSessionIds()` is.
+ *
+ * - Other projects. One daemon serves many, and somebody watching app A does not need to hear about
+ *   a lease taken against app B. A session that declares no project is NOT excluded: an older SDK
+ *   sends no projectId, and silently dropping those would reintroduce the dark HUD for exactly the
+ *   people least likely to work out why.
+ *
+ * Pure: no IO, no clock, no session objects. The caller does the posting.
+ */
+export declare function watchersToNotify(sessions: readonly WatcherCandidate[], leasedSessionIds: readonly string[], projectId: string | undefined): string[];