@reticlehq/server 3.2.0 → 3.4.0

package/dist/surface/mcp/proxy-idle-exit.d.ts

@@ -10,7 +10,7 @@
 export declare const PROXY_IDLE_EXIT_MS: number;
 /** The local diagnostic emitted before an abandoned proxy exits. */
 export declare const PROXY_IDLE_EXIT_EVENT = "reticle_mcp_proxy_idle_exit";
-export interface ProxyIdleExitOptions {
+interface ProxyIdleExitOptions {
     /** Called once after the client link has stayed quiet for the whole grace. */
     onExit: (idleMs: number) => void;
     /** True while a request or queued message still needs an answer. */
@@ -43,3 +43,4 @@ export declare class ProxyIdleExit {
  * zero as the explicit opt-out. Invalid values retain the conservative one-day default.
  */
 export declare function resolveProxyIdleExitMs(raw: string | undefined): number;
+export {};

package/dist/surface/mcp/server-instructions.js

@@ -31,11 +31,22 @@ import { surfaceVocabulary, listOf } from './surface-vocabulary.js';
  * measured reason. A briefing that names a tool the agent was not given does not merely confuse it;
  * it makes the agent stop using the product altogether.
  */
-const verdictDiscipline = (v) => `Reticle verifies a running web app from the inside: go (${v.navigate}), look (${listOf(v.look, v.find)}), act and prove in one hop (${v.actAndWait}), observe (${listOf(v.observe, v.state, v.network, v.console)}), assert (${v.assert}). Verify a user-facing change against the real app before you call it done, and never weaken a check to make it pass.
+/*
+ * `reticle gate` is FOLDED INTO the done sentence rather than given a paragraph, and that is the
+ * budget rule working rather than a stylistic choice.
+ *
+ * The instruction block has a hard byte cap whose own note says a raise must be paid for with a
+ * measurement, and that if one cannot be shown the right answer is to cut an older sentence. There
+ * is no measurement for `gate`: it is built, it has anti-reward-hacking, and it appeared in no
+ * surface an agent reads, which is an argument and not a number. Cutting a measured sentence to
+ * make room for an unmeasured one would be strictly worse. So it costs about a hundred characters
+ * inside the sentence that already names the exact moment it applies to, and the cap did not move.
+ */
+const verdictDiscipline = (v) => `Reticle verifies a running web app from the inside: go (${v.navigate}), look (${listOf(v.look, v.find)}), act and prove in one hop (${v.actAndWait}), observe (${listOf(v.observe, v.state, v.network, v.console)}), assert (${v.assert}). Verify a user-facing change against the real app before you call it done — \`npx @reticlehq/server gate --since <ref>\` fails unless a passing artifact covers every flow your edits affect — and never weaken a check to make it pass.
 
-Only ${v.actAndWait} and ${v.assert} produce a verdict. ${v.act.length > 0 ? `${v.act} and e` : 'E'}verything else moves or reads the app and proves nothing, so a drive that ends without one of those two has no result however many tools it used. Prefer ${v.actAndWait}({ ref, action, until }) — it names the expected consequence BEFORE the action, which is the difference between a check and a rationalisation. Only verified:"yes" is a pass — "unknown" means Reticle could not tell what happened, "no-fault" means nothing was declared to prove. Report either as not proved.
+Only ${v.act.length > 0 ? `${v.actAndWait}, ${v.assert} and ${v.act}{steps}` : `${v.actAndWait} and ${v.assert}`} produce a verdict. Everything else moves or reads the app and proves nothing, so a drive that ends without one of those two has no result however many tools it used. Prefer ${v.actAndWait}({ ref, action, until }) — it names the expected consequence BEFORE the action, which is the difference between a check and a rationalisation. Only verified:"yes" is a pass — "unknown" means Reticle could not tell what happened, "no-fault" means nothing was declared to prove. Report either as not proved.
 
-A "yes" over a clean capture IS the answer — re-reading the page after one finds the same state. When every consequence you set out to check has one, stop.
+Done is the journey's END proved, not its first step: drive each step your change touches and give the last an \`until\` naming the end state (\`durable: true\` if it must persist). A "yes" on it over a clean capture IS the answer — stop.
 
 DIAGNOSING a bug? Read the source first — Reticle proves what the app DOES, not why. Drive to CONFIRM a fix, not to find one.`;
 /**
@@ -73,13 +84,15 @@ const replayFirst = (v) => {
  *
  * Deliberately concrete: the command, what it does to the app, and the call that confirms it. A
  * general instruction to "set Reticle up" is the state these agents are already in — they have the
- * tools and no app, and nothing tells them that combination is incomplete. It also names the dev
- * server restart, because a plugin added to a config the running server already read is the single
- * most common way this step half-succeeds.
+ * tools and no app, and nothing tells them that combination is incomplete. `init` starts the dev
+ * server and opens the app itself, so the restart is named only for the case it cannot cover: a dev
+ * server that was already running read the config before `init` edited it, which is the single most
+ * common way this step half-succeeds. Telling every agent to restart sent them to kill the server
+ * `init` had just started.
  */
 const firstMoveFor = (v) => `FIRST: no app has ever connected to Reticle in this project, so nothing here can be verified yet. Having these tools is not the same as being set up — the tools reach a daemon, and the daemon has nothing to look at until the app itself is instrumented.
 
-Fix that before anything else: run \`npx @reticlehq/server init\` in the project, then RESTART the dev server (a plugin added to a config the running server already read is not in the bundle), then load the app in a browser. Confirm with ${v.sessions} — a session listed there is the proof, and until one appears no other tool can tell you anything about this app.`;
+Fix that before anything else: run \`npx @reticlehq/server init\` in the project. It starts the dev server and opens the app itself; only if a dev server was ALREADY running without Reticle, restart it and reload the tab. Confirm with ${v.sessions} — a session listed there is the proof, and until one appears no other tool can tell you anything about this app.`;
 /**
  * When to reach for the tools that are advertised but never explained, and how to reach the two
  * that are explained but not advertised. Both halves of the same defect.
@@ -100,7 +113,7 @@ Fix that before anything else: run \`npx @reticlehq/server init\` in the project
  */
 const reachFor = (v) => {
     const lines = [
-        `${v.observe} is the evidence channel: everything the page did since a cursor, in one read. Take it BEFORE you call a build broken — measured, stripping the observation tools TRIPLED false alarms, because an agent that stops observing reaches for the verdict without the evidence. ${v.settle} settles a page that is changing without you; ${v.inspect} maps an element to its source file:line, which turns a finding into an edit${v.yield.length > 0 ? `; ${v.yield} hands the tab back to the human` : ''}.`,
+        `${v.observe} is the evidence channel: everything the page did since a cursor, in one read. Take it BEFORE you call a build broken — measured, stripping the observation tools TRIPLED false alarms. ${v.settle} settles a page that is changing without you; ${v.inspect} maps an element to its source file:line, which turns a finding into an edit${v.yield.length > 0 ? `; ${v.yield} hands the tab back to the human` : ''}.`,
     ];
     // Said ONLY when both halves are advertised. A catalogue with no way to invoke what it lists sends
     // the agent at a tool it cannot call and then off the product entirely — see

package/dist/surface/tools/act/after-match.d.ts

@@ -0,0 +1,17 @@
+/**
+ * What act_and_wait does between the moment its predicate first holds and the moment it grades.
+ *
+ * The predicate resolves the INSTANT it holds, which on an optimistically-navigating app is while
+ * the write is still in flight — so the verdict was taken over a window the app had not finished,
+ * and came back `unknown / unsettled` asking the CALLER to re-check. A login that genuinely
+ * succeeded returned at 492ms of an 8000ms budget with every corroborating channel agreeing. So the
+ * rest of the budget the caller already granted is spent here, in three steps, each deciding
+ * nothing on its own.
+ */
+import type { Predicate } from '@reticlehq/core';
+import { waitForInFlight } from './settle-in-flight.js';
+import { revertedAfterMatch } from './durable.js';
+type Waited = Parameters<typeof waitForInFlight>[0] & Parameters<typeof revertedAfterMatch>[0];
+/** Returns the sentence to fail with when the consequence reverted, else undefined. */
+export declare function finishAfterMatch(session: Waited, until: Predicate, since: number, baselines: Parameters<typeof revertedAfterMatch>[3], remaining: () => number): Promise<string | undefined>;
+export {};

package/dist/surface/tools/act/after-match.js

@@ -0,0 +1,30 @@
+/**
+ * What act_and_wait does between the moment its predicate first holds and the moment it grades.
+ *
+ * The predicate resolves the INSTANT it holds, which on an optimistically-navigating app is while
+ * the write is still in flight — so the verdict was taken over a window the app had not finished,
+ * and came back `unknown / unsettled` asking the CALLER to re-check. A login that genuinely
+ * succeeded returned at 492ms of an 8000ms budget with every corroborating channel agreeing. So the
+ * rest of the budget the caller already granted is spent here, in three steps, each deciding
+ * nothing on its own.
+ */
+import { waitForInFlight } from './settle-in-flight.js';
+import { waitForReaction } from './react-grace.js';
+import { revertedAfterMatch } from './durable.js';
+/** Returns the sentence to fail with when the consequence reverted, else undefined. */
+export async function finishAfterMatch(session, until, since, baselines, remaining) {
+    const sleep = { sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)) };
+    // 1. Follow any open request to its response. A response that arrives as a FAILURE still
+    // contradicts — and now arrives INSIDE the window, where the detector can see it at all — while a
+    // request still open when the budget runs out reports unsettled, an honest limit rather than an
+    // early exit. Costs nothing on the common path, where no request is in flight.
+    await waitForInFlight(session, since, remaining(), sleep);
+    // 2. Then the app's REACTION to that response. Close the window between the response and the
+    // re-render and every channel agrees the app took a successful write and did nothing —
+    // `response-ignored`, a `verified:"no"` on a correct app, produced entirely by where we stopped
+    // looking. Paid only in the shape that would otherwise be accused, and short enough that a
+    // genuinely dropped response is still reported.
+    await waitForReaction(session, since, remaining(), sleep);
+    // 3. Then ask whether what held still holds — see revertedAfterMatch.
+    return revertedAfterMatch(session, until, since, baselines);
+}

package/dist/surface/tools/act/already-true.d.ts

@@ -0,0 +1,40 @@
+import type { Predicate } from '@reticlehq/engine/question/predicate/predicate-schema.js';
+import type { PredicateSession } from '@reticlehq/engine/question/predicate/predicate-session.js';
+import type { Baselines } from '@reticlehq/engine/question/predicate/predicate.js';
+/** Everything the pre-action check learned, which is three facts about one reading. */
+export interface AlreadyTrueReading {
+    /** The consequence held BEFORE the action, so the action proved nothing about it. */
+    alreadyTrue: boolean;
+    /** That pre-existing match was against something hidden — a stronger reason to doubt the claim. */
+    alreadyTrueHiddenMatch: boolean;
+    /**
+     * WHAT was already true, kept rather than discarded.
+     *
+     * `already_true` tells an agent its assertion held before it acted; the next question is always
+     * "true how?" and it was unanswerable, because the reading decided the bit and was then thrown
+     * away. Afterwards the action has run and the state may have moved, so the one moment that
+     * mattered is gone. Present only when the answer is yes: a verdict that was genuinely caused
+     * carries its own evidence and needs no baseline beside it.
+     */
+    alreadyTrueEvidence?: unknown;
+    /**
+     * What each comparing leaf was reading BEFORE the action — the predicate language's past tense.
+     *
+     * Taken here because this is already the one place that looks at the app before it is touched,
+     * and a second pre-action pass would be a second round trip for a reading we are standing next
+     * to. Empty unless the caller actually asked for a comparison, so nothing pays for it.
+     */
+    baselines: Baselines;
+}
+/**
+ * Ask whether the declared consequence was already true, once, before the action.
+ *
+ * Only for predicates that read live DOM state. Event-based ones are floored at this act's cursor
+ * and cannot be satisfied by the past, so they need no pre-check and pay nothing. One extra query,
+ * on the path where a green is otherwise unfalsifiable.
+ *
+ * Gathered here rather than as three locals at the call site because they are three readings OF ONE
+ * THING, and `act-tools.ts` sits on the 1000-line cohesion cap: the rule says split before adding,
+ * and this is the unit that wanted splitting.
+ */
+export declare function readAlreadyTrue(session: PredicateSession, until: Predicate | undefined, since: number): Promise<AlreadyTrueReading>;

package/dist/surface/tools/act/already-true.js

@@ -0,0 +1,36 @@
+import { evaluatePredicate } from '@reticlehq/engine/question/predicate/predicate.js';
+import { readsDomState } from '@reticlehq/engine/evidence/already-true.js';
+import { alreadyTrueHiddenMatch as alreadyTrueHiddenMatchOf } from '@reticlehq/engine/evidence/already-true.js';
+import { captureBaselines } from '@reticlehq/engine/evidence/baseline.js';
+/**
+ * Ask whether the declared consequence was already true, once, before the action.
+ *
+ * Only for predicates that read live DOM state. Event-based ones are floored at this act's cursor
+ * and cannot be satisfied by the past, so they need no pre-check and pay nothing. One extra query,
+ * on the path where a green is otherwise unfalsifiable.
+ *
+ * Gathered here rather than as three locals at the call site because they are three readings OF ONE
+ * THING, and `act-tools.ts` sits on the 1000-line cohesion cap: the rule says split before adding,
+ * and this is the unit that wanted splitting.
+ */
+export async function readAlreadyTrue(session, until, since) {
+    // Before the pre-check, because the pre-check EVALUATES the predicate and a relative leaf with no
+    // baseline yet would report `inconclusive` — reading the app twice to answer a question we had
+    // not taken the reading for.
+    const baselines = await captureBaselines(session, until);
+    const precheck = until !== undefined && readsDomState(until)
+        ? await evaluatePredicate(session, until, since, false, baselines)
+        : undefined;
+    const alreadyTrue = precheck?.pass ?? false;
+    if (!alreadyTrue || until === undefined) {
+        return { alreadyTrue: false, alreadyTrueHiddenMatch: false, baselines };
+    }
+    return {
+        alreadyTrue: true,
+        baselines,
+        // The pre-check evidence is already in hand, so asking whether the match was against something
+        // hidden costs nothing and lets the message name it (#889).
+        alreadyTrueHiddenMatch: alreadyTrueHiddenMatchOf(until, precheck?.evidence),
+        ...(precheck?.evidence === undefined ? {} : { alreadyTrueEvidence: precheck.evidence }),
+    };
+}

package/dist/surface/tools/act/durable.d.ts

@@ -0,0 +1,69 @@
+/**
+ * `act_and_wait { durable: true }` — after a yes, reload and ask again.
+ *
+ * Every verdict is scoped to one action's window, so "saved" was proved by the toast that said so,
+ * and nothing ever asked whether the thing was still there once the page came back. That is the
+ * difference between a UI that advanced and a change that persisted, and it was reachable only by
+ * hand: navigate, then a separate assert that nothing tied to the action that caused it.
+ *
+ * Only the part of `until` that describes the page as it IS can be asked of a fresh document. A
+ * request or a signal happened once, in a window that died with the old document; a route is read
+ * from route events a reload does not replay. So those clauses are dropped, never re-asserted.
+ */
+import { z } from 'zod';
+import { type Predicate } from '@reticlehq/core';
+import type { decideVerified } from '@reticlehq/engine/evidence/verified.js';
+type VerifiedVerdict = ReturnType<typeof decideVerified>;
+import { evaluatePredicate } from '@reticlehq/engine/question/predicate/predicate.js';
+import type { Session } from '../../../portal/session/session.js';
+export declare const durableArg: z.ZodOptional<z.ZodBoolean>;
+export declare const durableOutput: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+/** The part of a predicate a fresh document can answer, or undefined when there is none. */
+export declare function durablePart(p: Predicate): Predicate | undefined;
+/**
+ * What the re-check found. `held` absent means no answer: the page never came back to be asked, or
+ * it came back and could not answer (`inconclusive`).
+ */
+export interface Durability {
+    held?: boolean;
+    observed?: string;
+    skipped?: string;
+    inconclusive?: string;
+}
+/**
+ * A re-check's predicate result, as durability. Only a page that ANSWERED can say the consequence is
+ * gone: an unreadable one (its store not up yet) or one the tab left mid-read is no answer, and
+ * reporting either as "did not persist" is a confident no about something nobody saw.
+ */
+export declare function durabilityOf(verdict: {
+    pass: boolean;
+    observed?: string | undefined;
+    inconclusive?: string | undefined;
+    observationLost?: boolean | undefined;
+}): Durability;
+/**
+ * Apply `durable` to a decided verdict. Pure over `recheck`, which the caller supplies — see
+ * reloadAndRecheck for the one that reloads a real page.
+ */
+export declare function withDurability(asked: unknown, until: Predicate, decision: VerifiedVerdict, recheck: (part: Predicate) => Promise<Durability>): Promise<{
+    decision: VerifiedVerdict;
+    durable?: Durability;
+}>;
+/** Reload the page, wait for it to re-announce itself, and ask `part` of the fresh document. */
+export declare function reloadAndRecheck(deps: {
+    sessions: {
+        get(id: string): Session | undefined;
+    };
+    now: () => number;
+}, session: Session, part: Predicate, timeoutMs: number): Promise<Durability>;
+/**
+ * Whether the page-state part of a consequence that held has since gone — an optimistic UI that
+ * rolled back. Returns the sentence to fail with, or undefined when it still holds.
+ *
+ * The wait resolves the instant a predicate holds, and the in-flight wait after it only follows a
+ * request to its response. A row that appeared and was removed a tick later, with no failing
+ * request to contradict it, was a yes. Only element/text/state clauses are re-read: a request or a
+ * signal does not un-happen, and re-reading `settled` on a page that polls would accuse it falsely.
+ */
+export declare function revertedAfterMatch(session: Parameters<typeof evaluatePredicate>[0], until: Predicate, since: number, baselines: Parameters<typeof evaluatePredicate>[4]): Promise<string | undefined>;
+export {};

package/dist/surface/tools/act/durable.js

@@ -0,0 +1,139 @@
+/**
+ * `act_and_wait { durable: true }` — after a yes, reload and ask again.
+ *
+ * Every verdict is scoped to one action's window, so "saved" was proved by the toast that said so,
+ * and nothing ever asked whether the thing was still there once the page came back. That is the
+ * difference between a UI that advanced and a change that persisted, and it was reachable only by
+ * hand: navigate, then a separate assert that nothing tied to the action that caused it.
+ *
+ * Only the part of `until` that describes the page as it IS can be asked of a fresh document. A
+ * request or a signal happened once, in a window that died with the old document; a route is read
+ * from route events a reload does not replay. So those clauses are dropped, never re-asserted.
+ */
+import { z } from 'zod';
+import { PredicateKind, ReticleCommand, Verified, VerifiedReason, } from '@reticlehq/core';
+import { evaluatePredicate, waitForPredicate, } from '@reticlehq/engine/question/predicate/predicate.js';
+import { RELOAD_RECONNECT_TIMEOUT_MS, waitForReconnect, } from '../../../portal/session/session-reconnect.js';
+export const durableArg = z
+    .boolean()
+    .optional()
+    .describe('After a yes, reload and require the element/text/state part of `until` to hold again.');
+// Loose and undescribed on purpose: the output surface is re-sent every turn. `because` carries
+// the answer; this is the detail — { held?, observed?, skipped? }.
+export const durableOutput = z.record(z.unknown()).optional();
+const RE_READABLE = new Set([
+    PredicateKind.ELEMENT,
+    PredicateKind.TEXT,
+    PredicateKind.STATE,
+]);
+/** The part of a predicate a fresh document can answer, or undefined when there is none. */
+export function durablePart(p) {
+    if (PredicateKind.ALL_OF === p.kind) {
+        const kept = p.predicates.map(durablePart).filter((c) => c !== undefined);
+        if (0 === kept.length)
+            return undefined;
+        return 1 === kept.length ? kept[0] : { kind: PredicateKind.ALL_OF, predicates: kept };
+    }
+    // Narrowing an OR to the branches that survive would change the claim, not re-check it.
+    if (PredicateKind.ANY_OF === p.kind)
+        return p.predicates.every((c) => durablePart(c) === c) ? p : undefined;
+    if (PredicateKind.NOT === p.kind)
+        return durablePart(p.predicate) === p.predicate ? p : undefined;
+    return RE_READABLE.has(p.kind) ? p : undefined;
+}
+/**
+ * A re-check's predicate result, as durability. Only a page that ANSWERED can say the consequence is
+ * gone: an unreadable one (its store not up yet) or one the tab left mid-read is no answer, and
+ * reporting either as "did not persist" is a confident no about something nobody saw.
+ */
+export function durabilityOf(verdict) {
+    const observed = verdict.observed === undefined ? {} : { observed: verdict.observed };
+    if (true === verdict.pass)
+        return { held: true, ...observed };
+    if (verdict.inconclusive !== undefined)
+        return { inconclusive: verdict.inconclusive, ...observed };
+    if (true === verdict.observationLost)
+        return observed;
+    return { held: false, ...observed };
+}
+/**
+ * Apply `durable` to a decided verdict. Pure over `recheck`, which the caller supplies — see
+ * reloadAndRecheck for the one that reloads a real page.
+ */
+export async function withDurability(asked, until, decision, recheck) {
+    if (true !== asked || Verified.YES !== decision.verified)
+        return { decision };
+    const part = durablePart(until);
+    if (part === undefined) {
+        const skipped = 'nothing declared describes the page itself — a request or a signal happens once and cannot be seen again after a reload; add an element, text or state clause';
+        return { decision, durable: { skipped } };
+    }
+    const durable = await recheck(part);
+    if (true === durable.held)
+        return { decision, durable };
+    if (durable.inconclusive !== undefined) {
+        return {
+            durable,
+            decision: {
+                verified: Verified.UNKNOWN,
+                verifiedReason: VerifiedReason.INCONCLUSIVE,
+                because: `the consequence held, but the reloaded page could not answer whether it still does (${durable.inconclusive})`,
+            },
+        };
+    }
+    if (durable.held === undefined) {
+        return {
+            durable,
+            decision: {
+                verified: Verified.UNKNOWN,
+                verifiedReason: VerifiedReason.OBSERVATION_LOST,
+                because: `the consequence held, but the page did not come back after the reload to be asked again${durable.observed === undefined ? '' : ` (${durable.observed})`}`,
+            },
+        };
+    }
+    return {
+        durable,
+        decision: {
+            verified: Verified.NO,
+            verifiedReason: VerifiedReason.ASSERTION_FAILED,
+            because: `the consequence held, then was gone after a reload — it did not persist${durable.observed === undefined ? '' : ` (observed ${durable.observed})`}`,
+        },
+    };
+}
+/** Reload the page, wait for it to re-announce itself, and ask `part` of the fresh document. */
+export async function reloadAndRecheck(deps, session, part, timeoutMs) {
+    // Same floor navigate { reload } sets: nothing from the old document may answer for the new one.
+    session.lastAct.markNavigated(session.elapsed());
+    const sent = await session.command(ReticleCommand.REFRESH, { hard: false });
+    if (!sent.ok)
+        return { observed: sent.error ?? 'the reload was refused' };
+    const back = await waitForReconnect({
+        current: () => deps.sessions.get(session.id),
+        previous: session,
+        timeoutMs: Math.max(timeoutMs, RELOAD_RECONNECT_TIMEOUT_MS),
+        now: deps.now,
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    });
+    const fresh = back ? deps.sessions.get(session.id) : undefined;
+    if (fresh === undefined)
+        return {};
+    return durabilityOf(await waitForPredicate(fresh, part, timeoutMs, 0));
+}
+/**
+ * Whether the page-state part of a consequence that held has since gone — an optimistic UI that
+ * rolled back. Returns the sentence to fail with, or undefined when it still holds.
+ *
+ * The wait resolves the instant a predicate holds, and the in-flight wait after it only follows a
+ * request to its response. A row that appeared and was removed a tick later, with no failing
+ * request to contradict it, was a yes. Only element/text/state clauses are re-read: a request or a
+ * signal does not un-happen, and re-reading `settled` on a page that polls would accuse it falsely.
+ */
+export async function revertedAfterMatch(session, until, since, baselines) {
+    const part = durablePart(until);
+    if (part === undefined)
+        return undefined;
+    const now = await evaluatePredicate(session, part, since, true, baselines);
+    if (true === now.pass || now.inconclusive !== undefined)
+        return undefined;
+    return `held, then reverted before the action finished${now.observed === undefined ? '' : ` — now ${now.observed}`}`;
+}

package/dist/surface/tools/act/navigation/navigate-arrival.d.ts

@@ -17,6 +17,7 @@
  * 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 { Session } from '../../../../portal/session/session.js';
 import type { SessionManager } from '../../../../portal/session/session-manager.js';
 import type { NavigateArrival } from './navigate-result.js';
 /**
@@ -24,6 +25,12 @@ import type { NavigateArrival } from './navigate-result.js';
  * 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;
+/**
+ * The navigation target as an absolute URL, resolved against the tab being navigated — the same
+ * resolution the browser applies. An agent passes a path (`/orders?id=4`) as often as a full URL,
+ * and `samePage` cannot parse a path, so without this a relative navigation could never confirm.
+ */
+export declare function absoluteTarget(target: string, base: string): string;
 /**
  * Which session an arrival may be attributed to.
  *
@@ -39,14 +46,20 @@ export declare const ARRIVAL_TIMEOUT_MS = 5000;
  */
 export interface ArrivalScope {
     /**
-     * The session the navigation was dispatched to.
+     * The actual Session object that received the navigation command.
+     *
+     * A full-document navigation can destroy this session and reconnect the new document
+     * with the same id or a different id, so successor detection needs the original object.
+     */
+    navigatedSession: Session;
+    /**
+     * The URL the session was on before navigation started.
      *
-     * 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.
+     * This lets us distinguish "the navigation is still in progress" from
+     * "the app redirected the newly arrived document somewhere else."
      */
-    navigatedId: string;
-    /** Sessions already on the target BEFORE dispatch. They cannot be evidence of this arrival. */
+    navigatedFrom: string;
+    /** Sessions already on the target before dispatch cannot prove this navigation arrived. */
     priorIds: ReadonlySet<string>;
 }
 /**

package/dist/surface/tools/act/navigation/navigate-arrival.js

@@ -17,6 +17,7 @@
  * 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 { awaitDocumentSuccessor } from '../../../../portal/session/session-successor.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.
@@ -41,6 +42,19 @@ function samePage(a, b) {
         return false;
     }
 }
+/**
+ * The navigation target as an absolute URL, resolved against the tab being navigated — the same
+ * resolution the browser applies. An agent passes a path (`/orders?id=4`) as often as a full URL,
+ * and `samePage` cannot parse a path, so without this a relative navigation could never confirm.
+ */
+export function absoluteTarget(target, base) {
+    try {
+        return new URL(target, base).href;
+    }
+    catch {
+        return target;
+    }
+}
 /**
  * The sessions already on `target` — the set `ArrivalScope.priorIds` is built from, sampled before
  * the navigation is dispatched.
@@ -56,19 +70,27 @@ export function idsAtTarget(sessions, target) {
     }
     return ids;
 }
-function findArrival(sessions, target, scope) {
+function findArrival(sessions, target, scope, currentSession) {
     let arrived = null;
     for (const s of sessions.all()) {
-        if (!samePage(s.url, target))
+        // The currently tracked document gets priority because it is the strongest
+        // evidence of where this navigation went.
+        if (s.id === currentSession.id) {
+            if (samePage(s.url, target)) {
+                return { sessionId: s.id };
+            }
+            // Intermediate routes are not necessarily redirects. Keep polling so
+            // the document has a chance to reach the requested target.
             continue;
-        // The tab we drove is the answer whenever it is there, not a tie broken by scan order.
-        if (s.id === scope.navigatedId)
-            return { sessionId: s.id };
+        }
+        // A different session that was already at the target cannot prove this
+        // navigation arrived.
         if (scope.priorIds.has(s.id))
             continue;
-        // Keep looking rather than returning: the driven session may still be ahead of us.
-        if (null === arrived)
-            arrived = { sessionId: s.id };
+        if (samePage(s.url, target)) {
+            if (null === arrived)
+                arrived = { sessionId: s.id };
+        }
     }
     return arrived;
 }
@@ -83,11 +105,39 @@ const REAL_CLOCK = {
 export async function awaitArrival(sessions, target, scope, timeoutMs = ARRIVAL_TIMEOUT_MS, clock = REAL_CLOCK) {
     const deadline = clock.now() + timeoutMs;
     for (;;) {
-        const found = findArrival(sessions, target, scope);
+        // Keep checking the live session registry for the entire caller-provided
+        // budget. This is important because a document can disconnect and reconnect
+        // under another id, and the new session may be at the requested target,
+        // including on a different origin.
+        const found = findArrival(sessions, target, scope, scope.navigatedSession);
         if (found !== null)
             return found;
         if (clock.now() >= deadline)
-            return null;
+            break;
         await clock.sleep(POLL_MS);
     }
+    // Only after the navigation wait has expired do we use successor detection.
+    // At this point it is no longer being used to decide whether the requested
+    // navigation arrived. It only helps explain where the replaced document
+    // landed when the target was never observed.
+    const current = sessions.get(scope.navigatedSession.id);
+    if (current !== undefined) {
+        if (!samePage(current.url, scope.navigatedFrom) && !samePage(current.url, target)) {
+            return {
+                sessionId: current.id,
+                landedOn: current.url,
+            };
+        }
+        return null;
+    }
+    const successor = await awaitDocumentSuccessor(sessions, scope.navigatedSession, 0, clock);
+    if (successor !== null &&
+        !samePage(successor.url, target) &&
+        !samePage(successor.url, scope.navigatedFrom)) {
+        return {
+            sessionId: successor.id,
+            landedOn: successor.url,
+        };
+    }
+    return null;
 }

package/dist/surface/tools/act/navigation/navigate-result.d.ts

@@ -1,18 +1,7 @@
-/**
- * The honest envelope for a navigation nobody can confirm.
- *
- * `window.location.assign(url)` returns before the page moves, and the SDK that would report on the
- * new document is destroyed by the navigation itself. So a successful NAVIGATE means the browser
- * accepted the instruction — not that anything arrived. Driven against a dead URL it returned
- * `{"ok":true}` while the session died, which is the worst combination available: the agent believes
- * it navigated, is looking at nothing, and has lost Reticle.
- *
- * `reticle_act` already draws this line — `dispatched` (sent) versus `settled` (a frame flushed).
- * This gives navigate the same honesty without changing what it does.
- */
 /** The session the SDK reconnected as after the page moved, when one was observed in the window. */
 export interface NavigateArrival {
     sessionId: string;
+    landedOn?: string;
 }
 export declare function navigateResult(result: {
     ok?: unknown;

package/dist/surface/tools/act/navigation/navigate-result.js

@@ -1,3 +1,16 @@
+/**
+ * The honest envelope for a navigation nobody can confirm.
+ *
+ * `window.location.assign(url)` returns before the page moves, and the SDK that would report on the
+ * new document is destroyed by the navigation itself. So a successful NAVIGATE means the browser
+ * accepted the instruction — not that anything arrived. Driven against a dead URL it returned
+ * `{"ok":true}` while the session died, which is the worst combination available: the agent believes
+ * it navigated, is looking at nothing, and has lost Reticle.
+ *
+ * `reticle_act` already draws this line — `dispatched` (sent) versus `settled` (a frame flushed).
+ * This gives navigate the same honesty without changing what it does.
+ */
+import { NAVIGATION_REDIRECT_NOTE } from '@reticlehq/core';
 export function navigateResult(result, 
 /**
  * Arrival, if the daemon saw the SDK come back. `null` keeps the original honest envelope.
@@ -26,12 +39,17 @@ waitedMs) {
     if (!ok)
         return base;
     if (arrival !== null) {
+        const redirected = 'string' === typeof arrival.landedOn;
         return {
             ...base,
-            confirmed: true,
-            // The SDK that reconnects after a navigation is a NEW session with a new id. Returning it here
-            // is the difference between a confirmation and a confirmation the agent can act on.
+            confirmed: !redirected,
             sessionId: arrival.sessionId,
+            ...(redirected
+                ? {
+                    landedOn: arrival.landedOn,
+                    note: `${NAVIGATION_REDIRECT_NOTE} Landed on: ${arrival.landedOn}`,
+                }
+                : {}),
         };
     }
     return {

package/dist/surface/tools/act/proved-controls.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Remember the control an act_and_wait PROVED, for the coverage ledger's `proved` level.
+ *
+ * Structural rather than `Session`, and optional, so a test stub that never proves anything need not
+ * implement it — the same reason `beginAction` is optional on the crawl session.
+ */
+export declare function noteProved(session: {
+    recordProvedFrom?: (actPayload: unknown) => void;
+}, verified: string, actPayload: unknown): void;