@reticlehq/server 2.13.1 → 2.14.0

package/dist/tools/lease-tools.js

@@ -16,7 +16,7 @@ import { readProjectFramework, readProjectId } from '../cli/cli-port.js';
 import { hasConnectedBefore } from '../session/connection-memory.js';
 import { AGENT_DRIVING_ELSEWHERE, AGENT_DRIVING_HERE_AGAIN, watchersToNotify, } from '../session/lease-visibility.js';
 import { reticleStateHome } from '../daemon/daemon.js';
-import { RETICLE_URL_PARAM, RETICLE_DEFAULT_PORT } from '@reticlehq/core';
+import { LeaseNotReadyReason, REDACTED_VALUE, RETICLE_URL_PARAM, RETICLE_DEFAULT_PORT, ReticleCommand, SeedStorageSchema, scrubKnownSecrets, } from '@reticlehq/core';
 import { ReticleTool } from './tool-names.js';
 import { asString } from './tools-helpers.js';
 import { chromiumHint } from '../cli/chromium-hint.js';
@@ -84,13 +84,67 @@ export function appendReticleParams(url, session, projectId) {
         return `${url}${sep}${RETICLE_URL_PARAM.SESSION}=${encodeURIComponent(session)}${proj}`;
     }
 }
+function redactExactValue(text, value) {
+    if (0 === value.length)
+        return text;
+    const escaped = value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return text.replace(new RegExp(`(^|[^a-zA-Z0-9])${escaped}(?=$|[^a-zA-Z0-9])`, 'g'), `$1${REDACTED_VALUE}`);
+}
+/**
+ * Scrub known secret shapes and raw seedStorage values (cookies, localStorage, sessionStorage)
+ * from an error string before it reaches daemon logs, metrics, or MCP error responses.
+ */
+export function scrubSeedFromError(text, seed) {
+    let out = scrubKnownSecrets(text);
+    if (undefined !== seed && null !== seed && 'object' === typeof seed) {
+        const s = seed;
+        const cookies = s['cookies'];
+        if (undefined !== cookies && null !== cookies) {
+            if (Array.isArray(cookies)) {
+                for (const c of cookies) {
+                    if (undefined !== c && null !== c && 'object' === typeof c) {
+                        const val = c['value'];
+                        if (undefined !== val && 'string' === typeof val) {
+                            out = redactExactValue(out, val);
+                        }
+                    }
+                }
+            }
+            else if ('object' === typeof cookies) {
+                for (const v of Object.values(cookies)) {
+                    if ('string' === typeof v) {
+                        out = redactExactValue(out, v);
+                    }
+                }
+            }
+        }
+        const local = s['local'];
+        if (undefined !== local && null !== local && 'object' === typeof local) {
+            for (const v of Object.values(local)) {
+                if ('string' === typeof v) {
+                    out = redactExactValue(out, v);
+                }
+            }
+        }
+        const session = s['session'];
+        if (undefined !== session && null !== session && 'object' === typeof session) {
+            for (const v of Object.values(session)) {
+                if ('string' === typeof v) {
+                    out = redactExactValue(out, v);
+                }
+            }
+        }
+    }
+    return out;
+}
 /**
  * Turn a raw navigation failure (Playwright's `page.goto: net::ERR_… at <url>\nCall log:…`, often
  * with ANSI codes) into a short, clean reason — so the agent/user sees "is the app running?" instead
  * of an internals-leaking wall of text.
  */
-export function cleanNavError(err) {
-    const msg = err instanceof Error ? err.message : String(err);
+export function cleanNavError(err, seed) {
+    const rawMsg = err instanceof Error ? err.message : String(err);
+    const msg = scrubSeedFromError(rawMsg, seed);
     // Strip ANSI color codes (ESC[…m) Playwright emits — built via fromCharCode to keep the
     // control character out of a regex literal (no-control-regex).
     const ansi = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, 'g');
@@ -106,6 +160,44 @@ export function cleanNavError(err) {
         .trim()
         .slice(0, 100);
 }
+/**
+ * Determine if a required seedStorage application precondition failed.
+ *
+ * Checks strong signals:
+ * 1. HTTP 401/403 status on the initial navigation.
+ * 2. Cross-origin redirect when localStorage or sessionStorage was requested (skipped by origin-scoping).
+ * 3. Clear redirect to an authentication/login endpoint when the requested URL was not a login page.
+ *
+ * Normal app redirects (e.g. / → /dashboard) are valid and return undefined.
+ */
+export function evaluateSeedPrecondition(requestedUrl, actualUrl, seed, navStatus) {
+    if (401 === navStatus || 403 === navStatus) {
+        return `HTTP ${navStatus} returned on initial seeded navigation to ${requestedUrl}`;
+    }
+    if (actualUrl === undefined || '' === actualUrl.trim())
+        return undefined;
+    let reqParsed;
+    let actParsed;
+    try {
+        reqParsed = new URL(requestedUrl);
+        actParsed = new URL(actualUrl);
+    }
+    catch {
+        return undefined;
+    }
+    // Cross-origin redirect when local or session storage was requested
+    const hasStorage = (undefined !== seed.local && 0 < Object.keys(seed.local).length) ||
+        (undefined !== seed.session && 0 < Object.keys(seed.session).length);
+    if (hasStorage && reqParsed.origin !== actParsed.origin) {
+        return `seeded storage precondition not established: cross-origin redirect from ${reqParsed.origin} to ${actParsed.origin} skipped origin-scoped storage injection`;
+    }
+    // Clear redirect to an authentication/login endpoint when the requested URL was not a login page
+    const isAuthPath = (pathname) => /(?:^|\/)(?:login|signin|sign-in|auth\/login|auth\/signin|session\/new)(?:$|\/)/i.test(pathname);
+    if (!isAuthPath(reqParsed.pathname) && isAuthPath(actParsed.pathname)) {
+        return `seeded authentication precondition not established: redirected from ${reqParsed.pathname} to login page (${actParsed.pathname})`;
+    }
+    return undefined;
+}
 /** A fresh, collision-resistant lease id. Uses crypto at the I/O boundary (not pure logic). */
 function newLeaseId() {
     const uuid = 'function' === typeof globalThis.crypto?.randomUUID
@@ -176,6 +268,46 @@ function sessionParamOf(url) {
 }
 const LEASE_READY_ATTEMPTS = 100;
 const LEASE_READY_POLL_MS = 100;
+/**
+ * How long a liveness probe waits for the tab to say anything at all.
+ *
+ * Short on purpose. This is not "finish the work", it is "are you there" — a page executing
+ * JavaScript answers a no-argument command in single-digit milliseconds, and a wedged one is not
+ * going to answer in two seconds either.
+ */
+const LEASE_PROBE_TIMEOUT_MS = 1_500;
+/**
+ * Does this tab still answer?
+ *
+ * `ready: true` used to mean "a row is in the sessions map", which is how a lease came back ready
+ * and was then rejected by `snapshot`, `state` and `console`. Presence is not liveness: the map
+ * still holds a tab that is attached, streaming events, and answering nothing (#692).
+ *
+ * ANY reply counts, including one that reports the command failed. The question is whether the SDK
+ * answers at all, not what it says — so an SDK too old to know the command replies
+ * `unknown command '…'`, and that is proof. Only the absence of a reply is evidence of absence:
+ * `PendingCommands.track` REJECTS on timeout and on a dropped socket, and resolves on every real
+ * answer, so the two cases are already separated for us.
+ *
+ * `CAPABILITIES` is the probe because it takes no arguments and returns a small fixed list. No new
+ * wire command is introduced: this rides an existing round trip.
+ *
+ * Fails OPEN. A registry entry with no `command` is a shape this code did not put there, and
+ * turning a lease that works into a refusal over a probe that could not run would be a worse
+ * failure than the one being fixed.
+ */
+export async function probeLeaseAlive(session, timeoutMs = LEASE_PROBE_TIMEOUT_MS) {
+    const send = session?.command;
+    if (send === undefined)
+        return true;
+    try {
+        await send.call(session, ReticleCommand.CAPABILITIES, {}, timeoutMs);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /**
  * Poll until the leased tab's SDK has actually registered on the bridge, so the sessionId we return
@@ -188,9 +320,18 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
  * Returns the session id plus its release; the caller must release in a finally so a crashed flow never
  * leaks a pool slot and starves the rest of the suite.
  */
-export async function acquireLeasedSession(pool, sessions, url, projectId) {
+export async function acquireLeasedSession(pool, sessions, url, projectId, seedStorage) {
     const sessionId = newLeaseId();
-    const lease = await pool.acquire(appendReticleParams(url, sessionId, projectId), { sessionId });
+    let lease;
+    try {
+        lease = await pool.acquire(appendReticleParams(url, sessionId, projectId), {
+            sessionId,
+            ...(seedStorage !== undefined ? { seedStorage } : {}),
+        });
+    }
+    catch (err) {
+        throw new Error(scrubSeedFromError(err instanceof Error ? err.message : String(err), seedStorage));
+    }
     // Resolved, not assumed — see resolveLeasedSessionId. The parallel suite replays against whatever
     // id comes back, so handing it the lease id for an app that named its own session sent every flow
     // in the run at a session that does not exist.
@@ -201,7 +342,17 @@ export async function acquireLeasedSession(pool, sessions, url, projectId) {
     });
     if (registeredId !== undefined)
         pool.alias?.(registeredId, lease.sessionId);
-    return { sessionId: registeredId ?? lease.sessionId, release: () => lease.release() };
+    const effectiveId = registeredId ?? lease.sessionId;
+    if (seedStorage !== undefined) {
+        const session = sessions.get(effectiveId);
+        if (session?.setPreconditionFailure !== undefined) {
+            const failureReason = evaluateSeedPrecondition(url, session.url, seedStorage, lease.navStatus);
+            if (failureReason !== undefined) {
+                session.setPreconditionFailure(failureReason);
+            }
+        }
+    }
+    return { sessionId: effectiveId, release: () => lease.release() };
 }
 export async function waitForLeasedSession(isConnected, sleeper = sleep, attempts = LEASE_READY_ATTEMPTS, pollMs = LEASE_READY_POLL_MS) {
     for (let i = 0; i < attempts; i++) {
@@ -220,6 +371,12 @@ export async function waitForLeasedSession(isConnected, sleeper = sleep, attempt
  * handler keeps that literal — the drive route dispatches through `runTool`, so it is counted like
  * any other call instead of being a second, invisible dispatch path.
  */
+// Serializes lease acquisitions on the same origin so concurrent callers (e.g. seeded replacements)
+// do not race and establish multiple overlapping contexts on that origin.
+const originAcquireLocks = new Map();
+export function hasOriginLock(origin) {
+    return originAcquireLocks.has(origin);
+}
 export const LEASE_ACQUIRE_TOOL = {
     name: ReticleTool.LEASE_ACQUIRE,
     description: 'Lease a fresh isolated headless browser context from the shared pool and navigate it to the app URL (the app must already be running and embed @reticlehq/core). If this origin is already leased and still connected, this returns THAT session rather than minting a second tab — a second acquire on the same origin poisons default session resolution. Returns the sessionId the leased tab registers — pass it to other tools. The pool keeps all leases in ONE browser and caps concurrency; if at capacity this waits for a free slot. Release with reticle_lease{action:"release"} when the flow is done. PREFER AN ALREADY-OPEN TAB: if reticle_sessions lists a non-leased session for this app, drive THAT instead — a lease is invisible to the person watching the app, whose HUD lives in their own tab, and a tab flagged hidden/throttled is often still driveable. Lease for isolation you actually need (a second identity, a clean context, parallel flows) or when driving the open tab has failed — this call answers with `preferExisting` when a live tab was available.',
@@ -231,13 +388,18 @@ export const LEASE_ACQUIRE_TOOL = {
             .string()
             .optional()
             .describe('Stable project id to stamp on the leased tab so the agent can scope to it.'),
+        seedStorage: SeedStorageSchema.optional().describe('Initial storage state (localStorage, sessionStorage, cookies) to seed before the first navigation (e.g. to start already authenticated).'),
     },
     outputSchema: {
         sessionId: z.string(),
         url: z.string(),
         ready: z
             .boolean()
-            .describe('Whether the leased tab connected — false ⇒ the app may not embed @reticlehq/core.'),
+            .describe('Whether the leased tab is connected AND answering. On a reused lease this is probed, not assumed — a row in the session map is presence, not liveness. False ⇒ read notReadyReason.'),
+        notReadyReason: z
+            .enum([LeaseNotReadyReason.SDK_NEVER_DIALLED, LeaseNotReadyReason.SDK_STOPPED_ANSWERING])
+            .optional()
+            .describe('Present only when ready is false. sdk_never_dialled ⇒ nothing connected within the wait, so check the install (the app may not embed @reticlehq/core). sdk_stopped_answering ⇒ an SDK did connect and has stopped replying, so the tab is wedged and needs recovering, not reinstalling.'),
         expiresInMs: z
             .number()
             .describe('Milliseconds until this lease expires if untouched. Each tool call that targets this session resets the clock. Plan your work to finish or re-acquire before this runs out.'),
@@ -278,83 +440,156 @@ export const LEASE_ACQUIRE_TOOL = {
             }
         }
         const projectId = asString(args['projectId']);
+        const seedStorageArg = args['seedStorage'];
+        let validatedSeed;
+        if (seedStorageArg !== undefined) {
+            const parsed = SeedStorageSchema.safeParse(seedStorageArg);
+            if (!parsed.success) {
+                const issuesMsg = scrubSeedFromError(parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join(', '), seedStorageArg);
+                throw new Error(`reticle_lease{action:"acquire"} seedStorage is invalid: ${issuesMsg}`);
+            }
+            validatedSeed = parsed.data;
+        }
         // Sampled BEFORE acquiring: afterwards this lease is itself a session, and the point is to name
         // a tab that already existed. A human's open tab is the one they can watch, so if one is here
         // the agent should be told at the moment it is choosing — not after it has gone dark on them.
         const alreadyOpen = liveTabFor(deps, projectId);
         const origin = originOf(url);
-        const existing = origin === undefined ? undefined : pool.leaseIdOnOrigin?.(origin);
-        if (existing !== undefined && origin !== undefined) {
-            if (deps.sessions.get(existing) !== undefined) {
-                pool.touch(existing);
-                return {
-                    sessionId: existing,
-                    url,
-                    ready: true,
-                    reused: true,
-                    expiresInMs: pool.leaseTtlMs(),
-                    leased: pool.activeCount(),
-                    queued: pool.queuedCount(),
-                    hint: alreadyHeldHint(existing, origin),
-                    ...(alreadyOpen === undefined
-                        ? {}
-                        : { preferExisting: { sessionId: alreadyOpen, note: PREFER_EXISTING_NOTE } }),
-                };
-            }
-            // The lease is still held but the tab has gone — a reload dropped the session. Free the
-            // slot and mint, rather than handing back a dead id or leaving both contexts occupied.
-            await pool.release(existing);
+        const priorLock = origin !== undefined ? originAcquireLocks.get(origin) : undefined;
+        let releaseLock;
+        let lockPromise;
+        if (origin !== undefined) {
+            lockPromise = new Promise((resolve) => {
+                releaseLock = resolve;
+            });
+            originAcquireLocks.set(origin, lockPromise);
+        }
+        if (priorLock !== undefined) {
+            await priorLock.catch(() => undefined);
         }
-        const sessionId = newLeaseId();
-        const navUrl = appendReticleParams(url, sessionId, projectId);
-        let lease;
         try {
-            lease = await pool.acquire(navUrl, { sessionId });
+            const existing = origin === undefined ? undefined : pool.leaseIdOnOrigin?.(origin);
+            if (validatedSeed !== undefined && existing !== undefined) {
+                // Caller explicitly requested storage seeding: do not reuse an existing context on this origin,
+                // release it so the new lease starts clean with the caller-provided state.
+                await pool.release(existing);
+            }
+            else if (existing !== undefined && origin !== undefined) {
+                // Resolved, not looked up — the same resolver the mint path below uses, for the same reason
+                // it states: an app that names its own session registers under that name, so the id the pool
+                // holds is not always an id the other tools accept. A direct `sessions.get` missed exactly
+                // those apps and fell through to the release, which frees a LIVE lease and mints a second
+                // context — the tab-poisoning this branch exists to prevent, reached through the branch
+                // itself. It bites when the first acquire returned `ready: false`, since the mint path only
+                // aliases once its wait has resolved, so nothing recorded the app's own name (#692).
+                const resolved = resolveLeasedSessionId(deps.sessions, existing);
+                if (resolved !== undefined) {
+                    // The other name this lease answers to, told to the pool exactly as the mint path tells it.
+                    // A no-op when the id resolved to itself; load-bearing when it did not, because every later
+                    // touch and release arrives under the id being handed back here.
+                    pool.alias(resolved, existing);
+                    pool.touch(existing);
+                    // Probed only HERE, never on the mint path below. There, the readiness wait resolved
+                    // moments ago and IS the liveness evidence; on reuse the last evidence may be minutes
+                    // old, or there may be none at all — `unresponsive` is set by past commands failing, and
+                    // its own contract says absence means "answering, OR NOT ASKED YET". So the happy path of
+                    // a first acquire pays nothing for this.
+                    const alive = await probeLeaseAlive(deps.sessions.get(resolved));
+                    return {
+                        sessionId: resolved,
+                        url,
+                        ready: alive,
+                        ...(alive ? {} : { notReadyReason: LeaseNotReadyReason.SDK_STOPPED_ANSWERING }),
+                        reused: true,
+                        expiresInMs: pool.leaseTtlMs(),
+                        leased: pool.activeCount(),
+                        queued: pool.queuedCount(),
+                        hint: alreadyHeldHint(resolved, origin),
+                        ...(alreadyOpen === undefined
+                            ? {}
+                            : { preferExisting: { sessionId: alreadyOpen, note: PREFER_EXISTING_NOTE } }),
+                    };
+                }
+                // The lease is still held but the tab has gone — a reload dropped the session, and no session
+                // anywhere is driving it. Free the slot and mint, rather than handing back a dead id or
+                // leaving both contexts occupied.
+                await pool.release(existing);
+            }
+            const sessionId = newLeaseId();
+            const navUrl = appendReticleParams(url, sessionId, projectId);
+            let lease;
+            try {
+                lease = await pool.acquire(navUrl, {
+                    sessionId,
+                    ...(validatedSeed !== undefined ? { seedStorage: validatedSeed } : {}),
+                });
+            }
+            catch (err) {
+                if (err instanceof Error && err.message.startsWith('Storage seeding failed')) {
+                    throw new Error(scrubSeedFromError(err.message, validatedSeed));
+                }
+                // A raw page.goto failure is noisy and leaks the internal URL params — surface a clean,
+                // actionable message instead.
+                throw new Error(`could not open ${url} — is the app running there? (${cleanNavError(err, validatedSeed)})`);
+            }
+            // Wait for the leased tab's SDK to connect so the returned sessionId is usable right away.
+            // Resolved rather than assumed: an app that names its own session registers under that name,
+            // and the id we hand back has to be the one the agent can actually drive.
+            let registeredId;
+            const ready = await waitForLeasedSession(() => {
+                registeredId = resolveLeasedSessionId(deps.sessions, lease.sessionId);
+                return registeredId !== undefined;
+            });
+            // Tell the pool the other name this lease answers to. Every later touch and release arrives
+            // under the id we are about to hand back, and the pool is keyed by the id it navigated with;
+            // without this the touches miss, the lease ages out despite continuous activity, and the
+            // reaper closes the context mid-flow. See BrowserPool.alias and #157.
+            if (registeredId !== undefined)
+                pool.alias(registeredId, lease.sessionId);
+            const effectiveSessionId = registeredId ?? lease.sessionId;
+            const session = deps.sessions.get(effectiveSessionId);
+            if (validatedSeed !== undefined && session !== undefined) {
+                const failureReason = evaluateSeedPrecondition(url, session.url, validatedSeed, lease.navStatus);
+                if (failureReason !== undefined) {
+                    session.setPreconditionFailure?.(failureReason);
+                }
+            }
+            // The lease now exists, so any HUD a human is watching has just gone dark. Say so.
+            tellWatchers(deps, projectId, AGENT_DRIVING_ELSEWHERE);
+            // ready means the SDK dialled in — not that contracts match. Carry the skew warning on acquire
+            // so the agent does not learn it only after a CDP tool invents a closed page (#688).
+            const versionSkew = registeredId === undefined ? undefined : deps.sessions.get(registeredId)?.versionSkew;
+            return {
+                sessionId: registeredId ?? lease.sessionId,
+                url,
+                ready,
+                // The other half of the pair. `ready: false` carried two opposite situations under one
+                // word: no SDK ever dialled in (look at the install) versus one dialled in and stopped
+                // answering (recover the tab). They want different next actions, so they get names.
+                ...(ready ? {} : { notReadyReason: LeaseNotReadyReason.SDK_NEVER_DIALLED }),
+                expiresInMs: pool.leaseTtlMs(),
+                leased: pool.activeCount(),
+                queued: pool.queuedCount(),
+                ...(alreadyOpen === undefined
+                    ? {}
+                    : {
+                        preferExisting: {
+                            sessionId: alreadyOpen,
+                            note: PREFER_EXISTING_NOTE,
+                        },
+                    }),
+                ...(versionSkew === undefined ? {} : { versionSkew }),
+                ...(ready
+                    ? {}
+                    : { hint: await notConnectedHint(deps, url, pool.dialFailureUrl?.(lease.sessionId)) }),
+            };
         }
-        catch (err) {
-            // A raw page.goto failure is noisy and leaks the internal URL params — surface a clean,
-            // actionable message instead.
-            throw new Error(`could not open ${url} — is the app running there? (${cleanNavError(err)})`);
+        finally {
+            releaseLock?.();
+            if (origin !== undefined && originAcquireLocks.get(origin) === lockPromise) {
+                originAcquireLocks.delete(origin);
+            }
         }
-        // Wait for the leased tab's SDK to connect so the returned sessionId is usable right away.
-        // Resolved rather than assumed: an app that names its own session registers under that name,
-        // and the id we hand back has to be the one the agent can actually drive.
-        let registeredId;
-        const ready = await waitForLeasedSession(() => {
-            registeredId = resolveLeasedSessionId(deps.sessions, lease.sessionId);
-            return registeredId !== undefined;
-        });
-        // Tell the pool the other name this lease answers to. Every later touch and release arrives
-        // under the id we are about to hand back, and the pool is keyed by the id it navigated with;
-        // without this the touches miss, the lease ages out despite continuous activity, and the
-        // reaper closes the context mid-flow. See BrowserPool.alias and #157.
-        if (registeredId !== undefined)
-            pool.alias(registeredId, lease.sessionId);
-        // The lease now exists, so any HUD a human is watching has just gone dark. Say so.
-        tellWatchers(deps, projectId, AGENT_DRIVING_ELSEWHERE);
-        // ready means the SDK dialled in — not that contracts match. Carry the skew warning on acquire
-        // so the agent does not learn it only after a CDP tool invents a closed page (#688).
-        const versionSkew = registeredId === undefined ? undefined : deps.sessions.get(registeredId)?.versionSkew;
-        return {
-            sessionId: registeredId ?? lease.sessionId,
-            url,
-            ready,
-            expiresInMs: pool.leaseTtlMs(),
-            leased: pool.activeCount(),
-            queued: pool.queuedCount(),
-            ...(alreadyOpen === undefined
-                ? {}
-                : {
-                    preferExisting: {
-                        sessionId: alreadyOpen,
-                        note: PREFER_EXISTING_NOTE,
-                    },
-                }),
-            ...(versionSkew === undefined ? {} : { versionSkew }),
-            ...(ready
-                ? {}
-                : { hint: await notConnectedHint(deps, url, pool.dialFailureUrl?.(lease.sessionId)) }),
-        };
     },
 };
 /** The whole not-connected diagnosis, gathered and worded. Split out so the acquire path stays flat. */
@@ -405,7 +640,7 @@ const LEASE_RELEASE_TOOL = {
  * when both exist the visible one is the better default and the agent should hear that here, where
  * it is choosing, rather than discover it when somebody asks why nothing is happening.
  */
-export const PREFER_EXISTING_NOTE = 'a non-leased tab for this app was already connected — that is the one a human can see, and this lease is not. Unless you need an isolated context (a second identity, a clean profile, parallel flows), release this lease and drive that sessionId instead.';
+const PREFER_EXISTING_NOTE = 'a non-leased tab for this app was already connected — that is the one a human can see, and this lease is not. Unless you need an isolated context (a second identity, a clean profile, parallel flows), release this lease and drive that sessionId instead.';
 /**
  * The first live non-leased session for this project, if any.
  *

package/dist/tools/lineage-tools.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `reticle_lineage` — where a runtime value came from.
+ *
+ * When a verdict is `no`, or a contradiction fires, the next question is always the same. Today an
+ * agent answers it by hand: `reticle_state` for the value, `reticle_network` for the requests,
+ * `reticle_observe` for the window, then correlates the three itself — spending tokens and judgement
+ * on a join the daemon can do once from data it already holds.
+ *
+ * READ-ONLY BY CONSTRUCTION. It produces no verdict, so it is registered in `TOOLS` and deliberately
+ * NOT in the verification set, and nothing on an assert path reaches it. The decision logic lives in
+ * `events/lineage.ts` and is where the honesty rules are argued; this file is the surface.
+ */
+import type { ToolDef } from './tools.js';
+export declare const LINEAGE_TOOLS: ToolDef[];

package/dist/tools/lineage-tools.js

@@ -0,0 +1,64 @@
+/**
+ * `reticle_lineage` — where a runtime value came from.
+ *
+ * When a verdict is `no`, or a contradiction fires, the next question is always the same. Today an
+ * agent answers it by hand: `reticle_state` for the value, `reticle_network` for the requests,
+ * `reticle_observe` for the window, then correlates the three itself — spending tokens and judgement
+ * on a join the daemon can do once from data it already holds.
+ *
+ * READ-ONLY BY CONSTRUCTION. It produces no verdict, so it is registered in `TOOLS` and deliberately
+ * NOT in the verification set, and nothing on an assert path reaches it. The decision logic lives in
+ * `events/lineage.ts` and is where the honesty rules are argued; this file is the surface.
+ */
+import { z } from 'zod';
+import { ReticleTool } from './tool-names.js';
+import { traceLineage } from '../events/lineage.js';
+import { asString } from './tools-helpers.js';
+import { cursorSchema } from './numeric-bounds.js';
+export const LINEAGE_TOOLS = [
+    {
+        name: ReticleTool.LINEAGE,
+        example: { path: 'user.profile.name' },
+        description: 'Trace BACKWARDS from a runtime value: which state change set it, which signal preceded that, and which request preceded the signal. Read-only — it draws no verdict and changes nothing. The state change is OBSERVED; every link above it is an INFERENCE from timing and says so in its own text. Where several candidates could explain a link it names ALL of them rather than choosing, because timing alone cannot justify the choice — so a chain here is a place to look, never a proven cause. Use it after a `no` verdict or a contradiction, instead of correlating reticle_state, reticle_network and reticle_observe by hand.',
+        inputSchema: {
+            path: z
+                .string()
+                .describe('The state path to trace, e.g. "user.profile.name". Matched as a substring.'),
+            value: z
+                .string()
+                .optional()
+                .describe('Narrow to the change that set THIS value, when the path changed more than once.'),
+            since: cursorSchema
+                .optional()
+                .describe('Only consider events after this cursor (from an act or observe result).'),
+            ...{},
+        },
+        outputSchema: {
+            found: z
+                .boolean()
+                .describe('False when the path was never seen to change — not the same as an empty chain.'),
+            chain: z
+                .array(z.object({
+                kind: z.string(),
+                text: z.string(),
+                observed: z.boolean(),
+                candidates: z.array(z.string()).optional(),
+            }))
+                .describe('Most recent change first. `observed` is true only for events we hold; every join is false.'),
+            note: z
+                .string()
+                .optional()
+                .describe('Why the chain stops where it does, when it stops early.'),
+        },
+        handler: (deps, args) => {
+            const session = deps.sessions.resolve(asString(args['sessionId']));
+            const since = 'number' === typeof args['since'] ? args['since'] : 0;
+            const path = asString(args['path']) ?? '';
+            const value = asString(args['value']);
+            return Promise.resolve(traceLineage(session.eventsSince(since), {
+                path,
+                ...(value === undefined ? {} : { value }),
+            }));
+        },
+    },
+];

package/dist/tools/merge-tools.js

@@ -51,9 +51,7 @@ export function mergeTools(spec) {
         description: spec.description,
         ...(spec.example === undefined ? {} : { example: spec.example }),
         inputSchema: {
-            action: z
-                .enum(actionNames)
-                .describe(`Which operation to run: ${actionNames.join(' | ')}.`),
+            action: z.enum(actionNames).describe('Which operation to run.'),
             ...unionShape(spec.actions),
         },
         handler: (deps, args) => {

package/dist/tools/navigate-arrival.d.ts

@@ -10,9 +10,53 @@
  * Bounded and best-effort by construction: a navigation to a page that is not instrumented, or not
  * there at all, must still return promptly with `confirmed:false` rather than hanging. The clock and
  * the sleep are injected so this is testable without waiting on a real one.
+ *
+ * The bound is the CALLER'S to set. It was a fixed 5s that `reticle_navigate` did not expose, and a
+ * Nuxt SPA reattaching under HMR was measured coming back in 30–60s — so every navigation to it
+ * answered `confirmed:false` while the app was still on its way, and nothing the agent could pass
+ * would make the daemon wait. `assert` / `wait_for` / `act_and_wait` all spend the caller's
+ * `timeout_ms` (resolve-within.ts); this is the same budget applied to the same wait.
  */
 import type { SessionManager } from '../session/session-manager.js';
 import type { NavigateArrival } from './navigate-result.js';
+/**
+ * The default when the caller gives no `timeout_ms`: long enough for a dev server to serve a page
+ * and the SDK to dial back; short enough to not hang. A caller who knows the app is slower says so.
+ */
+export declare const ARRIVAL_TIMEOUT_MS = 5000;
+/**
+ * Which session an arrival may be attributed to.
+ *
+ * Arrival means a session is at the target BECAUSE OF THIS NAVIGATION. The scan had no notion of
+ * that: it returned the first session whose page matched, whoever it belonged to. A stale row parked
+ * on the origin — in the field report, one belonging to a different app that had previously held the
+ * same port — therefore answered for a navigation it had nothing to do with, and `reticle_navigate`
+ * reported ITS id as the session the caller had arrived at. Targeting was never wrong; the result
+ * was (#785).
+ *
+ * `sessions.all()` is Map insertion order, so the older stale row is scanned FIRST. That made the
+ * wrong id the likely answer rather than a coin flip.
+ */
+export interface ArrivalScope {
+    /**
+     * The session the navigation was dispatched to.
+     *
+     * Exempt from the exclusion below, because it is legitimately at the target both before and after
+     * a navigation that keeps the document — a reload, or a same-page route change. Excluding it would
+     * report `confirmed: false` for the navigations most likely to have worked.
+     */
+    navigatedId: string;
+    /** Sessions already on the target BEFORE dispatch. They cannot be evidence of this arrival. */
+    priorIds: ReadonlySet<string>;
+}
+/**
+ * The sessions already on `target` — the set `ArrivalScope.priorIds` is built from, sampled before
+ * the navigation is dispatched.
+ *
+ * Shares `samePage` with the arrival scan on purpose: "was it already there" and "is it there now"
+ * are the same question asked at two moments, and two spellings of it would eventually disagree.
+ */
+export declare function idsAtTarget(sessions: SessionManager, target: string): ReadonlySet<string>;
 export interface ArrivalClock {
     now: () => number;
     sleep: (ms: number) => Promise<void>;
@@ -21,4 +65,4 @@ export interface ArrivalClock {
  * Poll until a session is present at `target`, or the budget runs out. Returns `null` on timeout —
  * never throws, because a failure to confirm is a legitimate answer, not an error.
  */
-export declare function awaitArrival(sessions: SessionManager, target: string, timeoutMs?: number, clock?: ArrivalClock): Promise<NavigateArrival | null>;
+export declare function awaitArrival(sessions: SessionManager, target: string, scope: ArrivalScope, timeoutMs?: number, clock?: ArrivalClock): Promise<NavigateArrival | null>;