@reticlehq/server 3.9.0 → 3.10.0

package/dist/portal/session/session-manager.js

@@ -6,6 +6,7 @@ import { AttachmentHistory } from './presence/attachment-history.js';
 import { claimedSessionOf, openedBeforeDeparture, pickDocumentSuccessor, } from './session-successor.js';
 import { SESSION_DISCONNECTED_REASON, SESSION_PARKED_REASON } from './facts/session-replaced.js';
 import { isErrorDocument } from './session-info.js';
+import { carryOnNewDocument, departedNetworkOf, } from './facts/departed-network.js';
 /** Core's `originOf`, re-exported for this module's existing importers. */
 export { originOf };
 /**
@@ -37,18 +38,10 @@ function scopeSessions(sessions, scope) {
  * target it: both facts are already in hand here.
  */
 export function scopeMissError(connected, scope) {
-    const who = scope?.projectId !== undefined
-        ? `project '${scope.projectId}'`
-        : scope?.url !== undefined
-            ? `your app at ${scope.url}`
-            : 'the active project';
+    const who = scopeName(scope);
     const anyUntagged = connected.some((s) => s.projectId === undefined);
     const anyTagged = connected.some((s) => s.projectId !== undefined);
-    const how = anyUntagged && !anyTagged
-        ? 'with no projectId'
-        : anyUntagged && anyTagged
-            ? 'under a different project or with no projectId'
-            : 'under a different project';
+    const how = whereConnected(anyUntagged, anyTagged);
     const listed = connected
         .map((s) => s.projectId !== undefined
         ? `'${s.projectId}' (${s.url}, sessionId '${s.id}')`
@@ -62,6 +55,48 @@ export function scopeMissError(connected, scope) {
         `${listed}. The daemon scopes to the .reticle.json of the directory it was started in, so ` +
         `this is a scope mismatch, not a dead app. ${advice}`);
 }
+/** What the scope names, in the words of the refusal. */
+function scopeName(scope) {
+    if (scope?.projectId !== undefined) {
+        return `project '${scope.projectId}'`;
+    }
+    if (scope?.url !== undefined) {
+        return `your app at ${scope.url}`;
+    }
+    return 'the active project';
+}
+/** Where the connected sessions are, given which of them carry a projectId. */
+function whereConnected(anyUntagged, anyTagged) {
+    if (!anyUntagged) {
+        return 'under a different project';
+    }
+    if (!anyTagged) {
+        return 'with no projectId';
+    }
+    return 'under a different project or with no projectId';
+}
+/**
+ * A session's rank for auto-selection: lower is better.
+ *
+ * 0 = non-throttled (visible + recently-heard), 1 = throttled (hidden or stale heartbeat),
+ * 2 = an error document, 3 = attached but not answering commands. A wedged tab keeps streaming
+ * events, so recency RATES IT HIGHEST — it was beating a healthy sibling on the one signal scoring
+ * looked at, and every call auto-targeted the one tab guaranteed to time out. An error document (a
+ * dev server's 404 that still mounted the SDK) ranks below any working page, hidden or not: it is
+ * never the app the agent was asked about.
+ */
+function rankOf(session) {
+    if (session.unresponsive()) {
+        return 3;
+    }
+    if (isErrorDocument(session.page)) {
+        return 2;
+    }
+    if (session.throttled()) {
+        return 1;
+    }
+    return 0;
+}
 /**
  * Owns the set of connected browser sessions and the smart auto-selection that resolves which one a
  * tool targets when the agent omits an explicit sessionId. Extracted from session.ts so each file
@@ -96,6 +131,11 @@ export class SessionManager {
     #tombstones = new Map();
     /** The tabs already open when each tombstoned session departed: siblings, never its successor. */
     #siblingsAtDeparture = new Map();
+    /**
+     * The network record each departed document made after the agent's last act, kept until the same
+     * tab's next document connects (#1944). Bounded with the tombstones. See departed-network.ts.
+     */
+    #departedNetwork = new Map();
     /**
      * The active project's scope, set once from the daemon's .reticle.json. When a tool resolves a session
      * without passing its own scope, this is applied — so auto-selection is project-scoped by default
@@ -145,10 +185,24 @@ export class SessionManager {
         // that silently fails to register is a leak nothing would report.
         declareDrivenRedactionKeys(session.id, session.redactKeys);
         this.#attachment.attached(session.id);
+        this.#carryDepartedNetwork(session, previous);
         this.#tombstones.delete(session.id);
         this.#siblingsAtDeparture.delete(session.id);
         return previous;
     }
+    /**
+     * Give a new document the requests its tab's previous document made after the last act (#1944).
+     * `previous` is that document when its socket has not closed yet; else the record kept at removal.
+     */
+    #carryDepartedNetwork(session, previous) {
+        const departed = previous !== undefined && previous !== session
+            ? departedNetworkOf(previous)
+            : this.#departedNetwork.get(session.id);
+        this.#departedNetwork.delete(session.id);
+        if (departed !== undefined) {
+            carryOnNewDocument(session, departed);
+        }
+    }
     /**
      * The other tabs of the same app as `driven`.
      *
@@ -173,6 +227,7 @@ export class SessionManager {
         session.disconnect(SESSION_PARKED_REASON);
         this.remove(session);
         this.#tombstones.delete(session.id);
+        this.#departedNetwork.delete(session.id);
     }
     isParked(sessionId) {
         return this.#parked.has(sessionId);
@@ -188,6 +243,13 @@ export class SessionManager {
         // the reconnect is exactly where that matters.
         this.#attachment.detached(session.id);
         this.#rememberTombstone(session);
+        // Kept only beside a tombstone, so the tombstone cap bounds it too.
+        const departedNetwork = this.#tombstones.has(session.id)
+            ? departedNetworkOf(session)
+            : undefined;
+        if (departedNetwork !== undefined) {
+            this.#departedNetwork.set(session.id, departedNetwork);
+        }
         return this.#sessions.delete(session.id);
     }
     #rememberTombstone(session) {
@@ -216,6 +278,7 @@ export class SessionManager {
             }
             this.#tombstones.delete(oldest);
             this.#siblingsAtDeparture.delete(oldest);
+            this.#departedNetwork.delete(oldest);
         }
     }
     #successorOf(sessionId) {
@@ -239,6 +302,10 @@ export class SessionManager {
     get(sessionId) {
         return this.#sessions.get(sessionId);
     }
+    /** The id the same tab connected as after this session's page went away, if one has. */
+    successorId(sessionId) {
+        return this.#successorOf(sessionId)?.id;
+    }
     /**
      * Did this id belong to a session that has since disconnected?
      *
@@ -515,33 +582,11 @@ export class SessionManager {
         return (`no connected session with id '${sessionId}'.${ended} Your app's tabs: ${named}. ` +
             'Retry with one of those, or omit sessionId entirely and let Reticle scope to your project.');
     }
-    resolve(sessionId, scope) {
-        if (sessionId !== undefined) {
-            const found = this.#sessions.get(sessionId) ?? this.#successorOf(sessionId);
-            if (found === undefined) {
-                throw new Error(this.#unknownSessionError(sessionId));
-            }
-            found.markAgentActivity(); // liveness — a targeted tool keeps the session alive / revives it
-            return found;
-        }
-        if (0 === this.#sessions.size) {
-            const closure = this.lastClosure();
-            // A diagnosis beats a checklist: it names which of the three causes this actually is.
-            const hint = this.#noSessionHint?.();
-            // BOTH, when there are both — the two answer different questions and the pair is strictly
-            // more than either. This used to be an either/or, and a recorded refusal DISCARDED the whole
-            // diagnosis: the one case where the daemon has hard evidence about why nothing is connected
-            // was also the one case where it threw away everything else it had learned, including the
-            // port scan and the next action. The refusal leads, because it is the fact.
-            const refusal = closure === undefined
-                ? ''
-                : ` NOTE: the bridge REFUSED or closed a connection recently — "${closure.reason}". The app is probably still running and trying to connect: it was turned away, and the SDK does not retry after a policy close. The reason above names the fix — do not go looking for a stopped dev server.`;
-            // Hand the branch code to the refusal that is about to be reported for this throw. The
-            // diagnosis is computed HERE and the refusal is classified from the message downstream, so
-            // without this every no-session refusal lands in one undifferentiated bucket (#615).
-            notePendingNoSessionReason(this.#noSessionReason?.());
-            throw new Error(`${hint ?? NO_SESSION_CONNECTED_ERROR}${refusal}${NO_SESSION_NAVIGATE_FIX}`);
-        }
+    /**
+     * The sessions an id-less call may choose from: in the project scope, then in the caller's own
+     * checkout. Throws when those scopes leave nothing, or leave tabs of more than one project.
+     */
+    #candidates(scope) {
         // Scope to the agent's active project FIRST, so a stray tab from another app/origin (e.g. a
         // leftover dashboard on a different port) is structurally unselectable — it never enters the
         // candidate set, no matter how recently it was heard from. This is the anti-cross-talk guard.
@@ -564,28 +609,20 @@ export class SessionManager {
             // exists to be. Naming the tab and its sessionId costs the agent one extra argument.
             throw new Error(scopeMissError(connected, effectiveScope));
         }
-        if (1 === all.length) {
-            const [only] = all;
-            if (only === undefined) {
-                throw new Error('session lookup failed');
-            }
-            only.markAgentActivity();
-            return only;
-        }
         // Two projects and nothing to choose between them: refuse, BEFORE any scoring.
         //
         // Reported from the field: a call from `apps/next-app-router` was answered by a `rowy-*`
         // session, and `act_and_wait` spent 16.9s returning `verified:'no'` about an app never under
         // test — a confident false verdict, with a source pointer, about code the agent never touched.
         //
-        // The recency rule below cannot prevent it. It asks "is one of these clearly fresher", which is
-        // the right question for two tabs of ONE app and the wrong question for two apps: the fresher
-        // tab of the wrong project is still the wrong project. The reported case had a clear winner,
-        // so the ambiguity check passed and the wrong app was selected.
+        // The recency rule in resolve() cannot prevent it. It asks "is one of these clearly fresher",
+        // which is the right question for two tabs of ONE app and the wrong question for two apps: the
+        // fresher tab of the wrong project is still the wrong project. The reported case had a clear
+        // winner, so the ambiguity check passed and the wrong app was selected.
         //
         // This sits ahead of scoring so freshness cannot rescue it. It only fires when nothing scoped
-        // the call — an explicit `sessionId` returns far above, and an explicit or default scope has
-        // already narrowed `all` to one project by here.
+        // the call — an explicit `sessionId` never reaches here, and an explicit or default scope has
+        // already narrowed `all` to one project by here. One session is one project, so it never fires.
         const projects = new Set(all.map((s) => s.projectId).filter((p) => p !== undefined));
         if (projects.size > 1) {
             const listed = all
@@ -598,18 +635,46 @@ export class SessionManager {
                 'never touched — the daemon scopes to the directory it was started in, so running it above ' +
                 'several apps leaves it unable to tell them apart.');
         }
-        // Multiple sessions: score each (lower = better candidate for auto-selection).
-        // 0 = non-throttled (visible + recently-heard), 1 = throttled (hidden or stale heartbeat),
-        // 2 = attached but not answering commands. A wedged tab keeps streaming events, so recency
-        // RATES IT HIGHEST — it was beating a healthy sibling on the one signal scoring looked at, and
-        // every call auto-targeted the one tab guaranteed to time out.
-        const scored = all.map((s) => ({
-            s,
-            // An error document (a dev server's 404 that still mounted the SDK) ranks below any working
-            // page, hidden or not: it is never the app the agent was asked about.
-            score: s.unresponsive() ? 3 : isErrorDocument(s.page) ? 2 : s.throttled() ? 1 : 0,
-            ms: s.lastSeenMs(),
-        }));
+        return all;
+    }
+    resolve(sessionId, scope) {
+        if (sessionId !== undefined) {
+            const found = this.#sessions.get(sessionId) ?? this.#successorOf(sessionId);
+            if (found === undefined) {
+                throw new Error(this.#unknownSessionError(sessionId));
+            }
+            found.markAgentActivity(); // liveness — a targeted tool keeps the session alive / revives it
+            return found;
+        }
+        if (0 === this.#sessions.size) {
+            const closure = this.lastClosure();
+            // A diagnosis beats a checklist: it names which of the three causes this actually is.
+            const hint = this.#noSessionHint?.();
+            // BOTH, when there are both — the two answer different questions and the pair is strictly
+            // more than either. This used to be an either/or, and a recorded refusal DISCARDED the whole
+            // diagnosis: the one case where the daemon has hard evidence about why nothing is connected
+            // was also the one case where it threw away everything else it had learned, including the
+            // port scan and the next action. The refusal leads, because it is the fact.
+            const refusal = closure === undefined
+                ? ''
+                : ` NOTE: the bridge REFUSED or closed a connection recently — "${closure.reason}". The app is probably still running and trying to connect: it was turned away, and the SDK does not retry after a policy close. The reason above names the fix — do not go looking for a stopped dev server.`;
+            // Hand the branch code to the refusal that is about to be reported for this throw. The
+            // diagnosis is computed HERE and the refusal is classified from the message downstream, so
+            // without this every no-session refusal lands in one undifferentiated bucket (#615).
+            notePendingNoSessionReason(this.#noSessionReason?.());
+            throw new Error(`${hint ?? NO_SESSION_CONNECTED_ERROR}${refusal}${NO_SESSION_NAVIGATE_FIX}`);
+        }
+        const all = this.#candidates(scope);
+        if (1 === all.length) {
+            const [only] = all;
+            if (only === undefined) {
+                throw new Error('session lookup failed');
+            }
+            only.markAgentActivity();
+            return only;
+        }
+        // Multiple sessions: score each (lower = better candidate for auto-selection). See rankOf().
+        const scored = all.map((s) => ({ s, score: rankOf(s), ms: s.lastSeenMs() }));
         const bestScore = Math.min(...scored.map((x) => x.score));
         const candidates = scored.filter((x) => x.score === bestScore);
         // Sort candidates by recency (ascending lastSeenMs = most recently active first).
@@ -651,6 +716,44 @@ export class SessionManager {
         best.s.markAgentActivity();
         return best.s;
     }
+    /**
+     * Resolve the session for a call that only some sessions can serve.
+     *
+     * With no sessionId, resolve() chooses by health and recency alone. A lease that could resize the
+     * page lost to a focused tab that could not, and the call was refused (#1959). Here, when exactly
+     * one candidate can serve the call, that candidate is chosen.
+     */
+    async resolveServing(sessionId, canServe) {
+        // A named session, or none connected: resolve() already gives the answer and its refusals.
+        if (sessionId !== undefined || 0 === this.#sessions.size) {
+            return this.resolve(sessionId);
+        }
+        // The same candidates resolve() chooses from, so the project and checkout scopes still apply.
+        // canServe can ask a browser, so each answer is awaited in turn.
+        const serving = [];
+        for (const candidate of this.#candidates()) {
+            if (await canServe(candidate)) {
+                serving.push(candidate);
+            }
+        }
+        // Exactly one can serve the call: there is nothing to guess.
+        const [onlyServing, secondServing] = serving;
+        if (onlyServing !== undefined && secondServing === undefined) {
+            onlyServing.markAgentActivity();
+            return onlyServing;
+        }
+        // None can serve: return the usual choice, so the tool gives its own refusal and its advice.
+        // Several can serve, and the usual choice cannot: choosing among them is a guess, so refuse
+        // and name them. canServe admits only the caller's own sessions, so no other agent's lease is
+        // named here.
+        const chosen = this.resolve();
+        if (0 < serving.length && !serving.includes(chosen)) {
+            const ids = serving.map((s) => `'${s.id}'`).join(', ');
+            throw new Error(`no sessionId was given, and ${String(serving.length)} sessions can serve this call: ` +
+                `${ids}. Pass sessionId to choose one.`);
+        }
+        return chosen;
+    }
 }
 /**
  * Which of a project's tabs belong to the agent's own git checkout.
@@ -679,6 +782,14 @@ export function scopeToCallerCheckout(sessions, caller, checkoutOfTab) {
     if (0 === siblings.length) {
         return { sessions: [] };
     }
+    // The caller is the folder the MCP proxy started in, not always where the agent works. Claude Code
+    // starts the proxy in the main checkout and then moves the agent into a linked worktree (#1916).
+    // So from the main checkout, one linked worktree that serves every tab is the agent's own: drive it.
+    // The tab names its `worktree`. Tabs of two worktrees, or a proxy in a linked worktree, stay refused.
+    const roots = new Set(siblings.map((p) => p.checkout?.root));
+    if (!caller.linked && 1 === roots.size && true === siblings[0]?.checkout?.linked) {
+        return { sessions: siblings.map((p) => p.session) };
+    }
     const listed = siblings
         .map((p) => `${describeCheckout(p.checkout)} (sessionId '${p.session.id}', ${p.session.url})`)
         .join(', ');

package/dist/start-wiring.d.ts

@@ -5,6 +5,7 @@ import type { RealInputProvider } from './portal/input/real-input.js';
 import { BrowserPool } from './portal/pool/browser-pool.js';
 import { type PageErrorJournal } from './portal/pool/page-error-journal.js';
 import type { PooledPageError } from './portal/pool/pool-contract.js';
+import type { BrowserPoolOptions } from './portal/pool/pool-lease.js';
 import { type InjectedConnect } from './portal/pool/zero-install.js';
 import type { NonceMinter } from './portal/production/production-activation.js';
 /**
@@ -26,7 +27,7 @@ export declare function readerConnect(port: number, token: string | undefined):
  * dials with a dead nonce; mint per navigation if that is ever seen.
  */
 export declare function zeroInstallLoader(reader: InjectedConnect, nonces?: Pick<NonceMinter, 'mint'>): (url?: string) => string | undefined;
-export declare function createBrowserPool(headless: boolean, reader: InjectedConnect, onPageError?: (leaseId: string, error: PooledPageError) => void, onLeaseClosed?: (leaseId: string) => void, nonces?: Pick<NonceMinter, 'mint'>): BrowserPool;
+export declare function createBrowserPool(headless: boolean, reader: InjectedConnect, onPageError?: (leaseId: string, error: PooledPageError) => void, onLeaseClosed?: (leaseId: string) => void, nonces?: Pick<NonceMinter, 'mint'>, onDialog?: BrowserPoolOptions['onDialog']): BrowserPool;
 /**
  * Journal the uncaught page errors the pool hears into the session that connects for that lease.
  *

package/dist/start-wiring.js

@@ -68,7 +68,7 @@ export function zeroInstallLoader(reader, nonces) {
         return script ?? undefined;
     };
 }
-export function createBrowserPool(headless, reader, onPageError, onLeaseClosed, nonces) {
+export function createBrowserPool(headless, reader, onPageError, onLeaseClosed, nonces, onDialog) {
     const maxContexts = resolveMaxContexts(process.env[ReticleEnv.MAX_CONTEXTS], cpus().length);
     const genSessionId = () => `lease-${'function' === typeof globalThis.crypto?.randomUUID
         ? globalThis.crypto.randomUUID()
@@ -82,6 +82,7 @@ export function createBrowserPool(headless, reader, onPageError, onLeaseClosed,
         launchHeaded: playwrightLauncher({ headless: false }),
         ...(onPageError === undefined ? {} : { onPageError }),
         ...(onLeaseClosed === undefined ? {} : { onLeaseClosed }),
+        ...(onDialog === undefined ? {} : { onDialog }),
     });
 }
 /**

package/dist/surface/mcp/mcp.js

@@ -7,7 +7,7 @@ import { isToonable, resultToToon, MCP_SERVER_NAME } from '@reticlehq/core';
 import { tableForSurface } from '../tools/tools.js';
 import { filterTools, describeToolSurface, TOOL_SURFACE, toolAnnotations, } from '../tools/tool-surface.js';
 import { ReticleTool } from '@reticlehq/core';
-import { sharedParamShort } from './shared-params.js';
+import { refusedKeyRedirect, sharedParamShort } from './shared-params.js';
 import { buildDynamicTools, descriptionOf } from '../tools/dynamic-tools.js';
 import { runTool } from '../tools/invoke-tool.js';
 import { sessionEnvelopeShape, newSnapshotCache } from '../tools/tool-kit.js';
@@ -132,7 +132,7 @@ const PREDICATE_FIELD_GRAMMAR_HINT = ' Bug-catching options: net.count (exact re
     'compare (page text vs server answer, no expected value: { left:{from:"text",scope}, ' +
     'right:{from:"net",urlContains,path}, as:"number" }), ' +
     'console.absent:true (action completed with a CLEAN ' +
-    'console), absent:true on element/text (it should be gone). Call reticle_tools for the full field ' +
+    'console), absent:true on element/text (gone from the DOM; add visible:true for "not shown"). Call reticle_tools for the full field ' +
     'grammar of a kind.';
 const COMPACT_PREDICATE_DESCRIPTION = `${PREDICATE_KINDS}${PREDICATE_FIELD_GRAMMAR_HINT}`;
 /**
@@ -367,6 +367,7 @@ export function installFriendlyArgErrors(server, examples, allowedKeys = new Map
             const declared = [...(allowedKeys.get(toolName) ?? [])].join(', ');
             throw new McpError(ErrorCode.InvalidParams, `Unknown ${1 === unknown.length ? 'parameter' : 'parameters'} for ${toolName}: ${unknown.join(', ')}. ` +
                 `They were NOT applied — a result computed without them would look like an answer. ` +
+                refusedKeyRedirect(toolName, unknown) +
                 (0 === declared.length ? '' : `${toolName} declares: ${declared}. `) +
                 (example === undefined
                     ? `Call reticle_tools { names: ["${toolName}"] } for its parameters.`

package/dist/surface/mcp/shared-params.d.ts

@@ -33,3 +33,5 @@ export declare const SHARED_PARAM_GUIDANCE: string;
 export declare function sharedParamShort(name: string, schema: z.ZodTypeAny): string | undefined;
 /** Is this a parameter whose guidance now lives in the instructions block? */
 export declare function isSharedParam(name: string): boolean;
+/** The sentences that name the tool for each refused key, or an empty string. */
+export declare function refusedKeyRedirect(toolName: string, refused: readonly string[]): string;

package/dist/surface/mcp/shared-params.js

@@ -1,3 +1,4 @@
+import { ReticleTool } from '@reticlehq/core';
 /**
  * Parameters that mean the same thing on every tool, documented ONCE instead of every turn.
  *
@@ -48,3 +49,33 @@ export function sharedParamShort(name, schema) {
 export function isSharedParam(name) {
     return Object.hasOwn(SHARED_PARAM_SHORT, name);
 }
+/**
+ * Where to go when a tool refuses a parameter that another tool takes (#1944).
+ *
+ * An agent proved a click with `reticle_act_and_wait`, saw a request missing from the act's window,
+ * and asked for a wider window with `since`. The refusal listed what the tool declares and stopped
+ * there, so the agent did not learn that `reticle_assert` reads any window it is given. The refusal
+ * now names that tool.
+ *
+ * A lookup table, keyed by tool and then by the refused parameter. Add a row only where another
+ * tool really does what the refused parameter asked for.
+ */
+const REDIRECTS = {
+    [ReticleTool.ACT_AND_WAIT]: {
+        since: `${ReticleTool.ACT_AND_WAIT} always reads the window that its own action opens. To check a ` +
+            `window that starts earlier, call ${ReticleTool.ASSERT} { predicate, since } with the cursor ` +
+            'from an earlier result.',
+    },
+};
+/** The sentences that name the tool for each refused key, or an empty string. */
+export function refusedKeyRedirect(toolName, refused) {
+    const forTool = REDIRECTS[toolName];
+    if (forTool === undefined) {
+        return '';
+    }
+    return refused
+        .map((key) => (Object.hasOwn(forTool, key) ? forTool[key] : undefined))
+        .filter((line) => line !== undefined)
+        .map((line) => `${line} `)
+        .join('');
+}

package/dist/surface/tools/act/act-observation.d.ts

@@ -10,10 +10,12 @@
  * used from the two points where observation can be lost: a write rejected at dispatch, and a wait
  * cut off mid-predicate.
  */
-import { type ReticleEvent } from '@reticlehq/core';
+import { type Drift, type ReticleEvent } from '@reticlehq/core';
 import type { Session } from '../../../portal/session/session.js';
-import { type SuccessorRegistry } from '../../../portal/session/session-successor.js';
+import { type SuccessorClock, type SuccessorRegistry } from '../../../portal/session/session-successor.js';
 import type { EvalResult } from '@reticlehq/engine/question/predicate/predicate-eval.js';
+/** How long an act whose page navigated away waits for the lease's successor to connect. */
+export declare const NAVIGATION_FOLLOW_GRACE_MS = 8000;
 interface FollowSuccessor {
     sessions: SuccessorRegistry;
     session: Session;
@@ -24,12 +26,27 @@ interface FollowSuccessor {
     predicateStarted: number;
     /** Re-ask the declared consequence on `next`, with whatever budget is left. */
     reevaluate: (next: Session, budgetMs: number) => Promise<EvalResult>;
+    /**
+     * Grace for the OTHER navigation shape (#2009): a FAILURE graded while the action's own form
+     * POST / link navigation was still in flight. The wait spent its budget on the document BEFORE
+     * it left, so nothing was "lost" and no successor was looked for — and the verdict then reads
+     * "still on /login" for a sign-in that worked. When set, a failed verdict waits this long for
+     * the document's successor and re-asks there; when it never connects, the verdict says the page
+     * navigated instead of leaving the failure standing. Undefined keeps the old behaviour.
+     */
+    failedFollowGraceMs?: number;
+    /** The act's own event cursor: the window the departure evidence is read from. */
+    since?: number;
+    /** Injected so tests do not sleep; defaults to the real clock. */
+    clock?: SuccessorClock;
 }
 interface FollowedOutcome {
     session: Session;
     verdict: EvalResult;
     /** True when the wait moved to a new document, so the caller must reset its event cursor. */
     followed: boolean;
+    /** The re-ask ran on the caller's grace — a budget extension declared in the result (#2009). */
+    budgetExtendedMs?: number;
 }
 /**
  * Follow the unique same-origin successor and re-ask there, or leave the verdict untouched.
@@ -56,8 +73,29 @@ export declare function disabledTargetNote(pass: boolean, actResult: unknown): s
  * failure, whichever way the consequence went.
  */
 export declare function unreachableTargetNote(actResult: unknown): string | undefined;
+/**
+ * The drift for the first sub-step of an `ACT_SEQUENCE` result whose target no person could have
+ * clicked, or undefined. The page reports one effect for each sub-step it ran, in order. Synthetic
+ * dispatch reaches an unreachable target all the same, so a sequence is read sub-step by sub-step, as
+ * a single act is. `labelOf` names the sub-step, by its index in this result.
+ */
+export declare function unreachableSubStepDrift(sequenceResult: unknown, labelOf: (at: number) => string): Drift | undefined;
 /** Why the acted target leaves the verdict undecided: no person could reach it, or it was disabled. */
 export declare function actTargetNote(pass: boolean, actResult: unknown): string | undefined;
+/**
+ * The cause and the one fix for a read that came back `unknown`, in place of a bare fact (#1990).
+ * A page whose SDK is behind this daemon may not serve `match` at all, so the fix is the same
+ * SDK-behind sentence the listing shows. On a current page the read ran out of the assertion's own
+ * budget, and the fix is more of it. Any reason that is not a command timeout is returned as it came.
+ */
+export declare function diagnoseTimeout(reason: string | undefined, session: {
+    readonly sdkVersion?: string | undefined;
+}): string | undefined;
+/** Why an act's verdict is `unknown`: a read that timed out, else an unreachable or disabled target. */
+export declare const actInconclusive: (verdict: {
+    pass: boolean;
+    inconclusive?: string | undefined;
+}, actResult: unknown, session: Session) => string | undefined;
 /**
  * The requests of a failed check's window, as its record carries them: method, url, status and the
  * start of the response body (redacted in the page before it was ever sent). Dev tooling is left out.