@reticlehq/server 3.3.0 → 3.5.0

package/dist/surface/mcp/proxy/proxy-daemon-probe.d.ts

@@ -3,8 +3,12 @@ export declare function daemonPollDelayMs(attempt: number): number;
  * Returns true if something is already listening on the reticle port.
  * Uses a plain TCP probe so we don't create a side-effectful SSE session
  * inside the daemon just to check reachability.
+ *
+ * `host` defaults to loopback, which is every caller's actual target — except `bootSession`
+ * (reticlehq/reticle#1165 review), whose Bridge can bind a non-default host via `RETICLE_HOST`.
+ * Hardcoding loopback here made that preflight check the wrong address.
  */
-export declare function probeDaemon(port: number): Promise<boolean>;
+export declare function probeDaemon(port: number, host?: string): Promise<boolean>;
 /**
  * Poll until a Reticle daemon is SERVING on `port`, or the deadline passes.
  *
@@ -20,3 +24,11 @@ export declare function waitForDaemon(port: number, probes?: {
     tcpOpen: (port: number) => Promise<boolean>;
     status: (port: number) => Promise<unknown>;
 }): Promise<void>;
+/**
+ * Poll until `/status` on `port` answers as a Reticle daemon; false once the bound passes.
+ *
+ * One rule for the three commands that start a daemon. `init` used to borrow `waitForDaemon`'s
+ * shorter reconnect budget, and on a cold fresh HOME it printed "could not start the Reticle
+ * daemon" over a daemon that bound seconds later. Bounded polling, never a fixed sleep.
+ */
+export declare function waitForDaemonBind(port: number): Promise<boolean>;

package/dist/surface/mcp/proxy/proxy-daemon-probe.js

@@ -24,8 +24,12 @@ export function daemonPollDelayMs(attempt) {
  * Returns true if something is already listening on the reticle port.
  * Uses a plain TCP probe so we don't create a side-effectful SSE session
  * inside the daemon just to check reachability.
+ *
+ * `host` defaults to loopback, which is every caller's actual target — except `bootSession`
+ * (reticlehq/reticle#1165 review), whose Bridge can bind a non-default host via `RETICLE_HOST`.
+ * Hardcoding loopback here made that preflight check the wrong address.
  */
-export function probeDaemon(port) {
+export function probeDaemon(port, host = LOOPBACK_HOST) {
     return new Promise((resolve) => {
         const socket = new net.Socket();
         socket.setTimeout(500);
@@ -38,7 +42,7 @@ export function probeDaemon(port) {
             socket.destroy();
             resolve(false);
         });
-        socket.connect(port, LOOPBACK_HOST);
+        socket.connect(port, host);
     });
 }
 /**
@@ -69,3 +73,24 @@ export async function waitForDaemon(port, probes = { tcpOpen: probeDaemon, statu
     throw new Error(`reticle daemon did not become ready on port ${String(port)} within ` +
         `${String(DAEMON_READY_TIMEOUT_MS)}ms — ${describePresence(presence, port)}`);
 }
+/** How long a spawned daemon gets to bind before `serve`, `restart` or `init` gives up on it. */
+const BIND_TIMEOUT_MS = 15_000;
+const BIND_POLL_MS = 150;
+/**
+ * Poll until `/status` on `port` answers as a Reticle daemon; false once the bound passes.
+ *
+ * One rule for the three commands that start a daemon. `init` used to borrow `waitForDaemon`'s
+ * shorter reconnect budget, and on a cold fresh HOME it printed "could not start the Reticle
+ * daemon" over a daemon that bound seconds later. Bounded polling, never a fixed sleep.
+ */
+export async function waitForDaemonBind(port) {
+    const deadline = Date.now() + BIND_TIMEOUT_MS;
+    for (;;) {
+        const presence = await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus });
+        if (presence === PortPresence.DAEMON)
+            return true;
+        if (Date.now() >= deadline)
+            return false;
+        await delay(BIND_POLL_MS);
+    }
+}

package/dist/surface/mcp/proxy/proxy-log.js

@@ -6,11 +6,9 @@
  * keep that file from becoming the largest thing on the user's disk.
  */
 import { appendFileSync, mkdirSync, renameSync, statSync, truncateSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { ReticleDir } from '@reticlehq/core';
 import { log } from '../../../log.js';
-import { MAX_DAEMON_LOG_BYTES, recoverOversizedLog, rotateDaemonLog, } from '../../../command/daemon/daemon.js';
+import { MAX_DAEMON_LOG_BYTES, recoverOversizedLog, rotateDaemonLog, reticleStateHome, } from '../../../command/daemon/daemon.js';
 /**
  * Which port this proxy serves, for the log file name. Set once at startup.
  *
@@ -79,7 +77,7 @@ export function setProxyLogPort(port) {
 /** The proxy's own log file, so a silent drop leaves a readable trace the agent can go read. */
 export function proxyLogPath(port = logPort) {
     const name = port === undefined ? 'mcp-proxy.log' : `proxy-${String(port)}.log`;
-    return join(homedir(), ReticleDir.ROOT, name);
+    return join(reticleStateHome(), name);
 }
 /**
  * Log to stderr (which the agent host usually swallows) AND to ~/.reticle/proxy-<port>.log, which it
@@ -96,7 +94,7 @@ export function proxyLogPath(port = logPort) {
 export function proxyLog(event, fields = {}) {
     log(event, fields);
     try {
-        const dir = join(homedir(), ReticleDir.ROOT);
+        const dir = reticleStateHome();
         mkdirSync(dir, { recursive: true });
         // WITH A TIMESTAMP. This file is the only record of an outage that survives the session, and
         // without one it cannot answer the two questions anyone brings to it: when did this happen, and

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

@@ -44,9 +44,9 @@ import { surfaceVocabulary, listOf } from './surface-vocabulary.js';
  */
 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.`;
 /**
@@ -84,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.
@@ -111,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/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';
 /**
@@ -45,14 +46,20 @@ export declare function absoluteTarget(target: string, base: string): string;
  */
 export interface ArrivalScope {
     /**
-     * The session the navigation was dispatched to.
+     * The actual Session object that received the navigation command.
      *
-     * 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.
+     * 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.
      */
-    navigatedId: string;
-    /** Sessions already on the target BEFORE dispatch. They cannot be evidence of this arrival. */
+    navigatedSession: Session;
+    /**
+     * The URL the session was on before navigation started.
+     *
+     * This lets us distinguish "the navigation is still in progress" from
+     * "the app redirected the newly arrived document somewhere else."
+     */
+    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.
@@ -69,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;
 }
@@ -96,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;

package/dist/surface/tools/act/proved-controls.js

@@ -0,0 +1,11 @@
+import { Verified } from '@reticlehq/core';
+/**
+ * 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 function noteProved(session, verified, actPayload) {
+    if (Verified.YES === verified)
+        session.recordProvedFrom?.(actPayload);
+}

package/dist/surface/tools/act/sequence-grade.d.ts

@@ -35,6 +35,11 @@ export interface StepExpectation {
     /** What was seen instead, on a miss — the half of the answer a repair actually needs. */
     observed?: string;
     expected?: string;
+    /**
+     * Contradiction kinds positively observed in this step's window — deciding ones only, the same
+     * filter act_and_wait applies. A held step with one is a UI that advanced over a failed write.
+     */
+    contradicted?: readonly string[];
 }
 export interface SequenceGrade {
     verified: Verified;