@reticlehq/server 3.3.0 → 3.4.0

package/dist/portal/session/session.d.ts

@@ -91,6 +91,8 @@ export declare class Session implements HandshakeFacts {
      * `reticle_session{action:"end"}` — a flag on the record, not on the page — could not help.
      */
     unresponsive(): boolean;
+    /** False once the socket is closing or closed: dropping this record then orphans nothing. */
+    socketOpen(): boolean;
     /** Wall-clock age of the session in milliseconds. */
     staleMs(): number;
     /** The document the most recent stamped event was observed under. See `#documentId`. */
@@ -114,6 +116,9 @@ export declare class Session implements HandshakeFacts {
      * against the same control after a re-render gave it a different ref.
      */
     private recordActedLabelFrom;
+    /** A control whose action PROVED its declared consequence — the coverage ledger's `proved`. */
+    recordProvedFrom(actPayload: unknown): void;
+    provedLabels(): ReadonlySet<string>;
     actedRefs(): ReadonlySet<string>;
     noteRateLimited(dropped: number): void;
     blindSpots(): Readonly<Record<string, number>>;

package/dist/portal/session/session.js

@@ -16,7 +16,7 @@ import { isKnownRealm, EventType, HumanControlDataSchema, HumanControlKind, Huma
 import { RingBuffer } from '@reticlehq/engine/window/ring-buffer.js';
 import { readJournalWriteLoss, readQueryEvents, } from '../../memory/journal/journal-query.js';
 import {} from '@reticlehq/engine/window/ambient.js';
-import { ObservedState } from './facts/observed-state.js';
+import { ObservedState, controlLabelsOf } from './facts/observed-state.js';
 import { recordBrowserLatency, recordHudUse, recordSdkFailure, } from '../../telemetry/session-metrics.js';
 import { LiveControl } from './human/live-control.js';
 import { ReviewStore } from './human/review-store.js';
@@ -241,6 +241,10 @@ export class Session {
     unresponsive() {
         return this.#unansweredCommands >= UNRESPONSIVE_AFTER_TIMEOUTS;
     }
+    /** False once the socket is closing or closed: dropping this record then orphans nothing. */
+    socketOpen() {
+        return this.#socket.readyState === WS_OPEN;
+    }
     /** Wall-clock age of the session in milliseconds. */
     staleMs() {
         return this.#clock() - this.#startedAt;
@@ -352,24 +356,16 @@ export class Session {
      * against the same control after a re-render gave it a different ref.
      */
     recordActedLabelFrom(result) {
-        const payload = result.result;
-        if (typeof payload !== 'object' || null === payload)
-            return;
-        const record = payload;
-        // The TESTID first: it is the strongest identity a control has and it survives any re-render.
-        // Coverage previously matched only on `role "name"`, so a control with a testid but no accessible
-        // name — or on a stack where the act reply carried neither — was unrecognisable after a
-        // re-render, and coverage read `exercised: 0` however much work had been done.
-        const testid = record['testid'];
-        if ('string' === typeof testid && testid.length > 0)
-            this.#observed.recordActedLabel(testid);
-        const role = record['role'];
-        const name = record['name'];
-        if (typeof role !== 'string' || typeof name !== 'string')
-            return;
-        if (0 === role.length || 0 === name.length)
-            return;
-        this.#observed.recordActedLabel(`${role} "${name}"`);
+        for (const label of controlLabelsOf(result.result))
+            this.#observed.recordActedLabel(label);
+    }
+    /** A control whose action PROVED its declared consequence — the coverage ledger's `proved`. */
+    recordProvedFrom(actPayload) {
+        for (const label of controlLabelsOf(actPayload))
+            this.#observed.recordProvedLabel(label);
+    }
+    provedLabels() {
+        return this.#observed.provedLabels();
     }
     actedRefs() {
         return this.#observed.actedRefs();

package/dist/surface/http-server.d.ts

@@ -10,7 +10,8 @@ export interface SharedServer {
      */
     attachMcp(factory: () => McpServer): void;
     /** Register the JSON the daemon returns from GET /status (live sessions + health for `reticle status`). */
-    attachStatus(provider: () => unknown): void;
+    /** `held`: the request carried STATUS_HOLD_QUERY — a setup run is waiting on this daemon. */
+    attachStatus(provider: (held: boolean) => unknown): void;
     /**
      * Register the handler behind POST /drive: open a driveable browser at `url` and answer with the
      * session it registered.

package/dist/surface/http-server.js

@@ -1,6 +1,6 @@
 import * as http from 'node:http';
 import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
-import { MCP_SSE_PATH, MCP_MESSAGE_PATH, MCP_SHUTDOWN_EVENT, STATUS_PATH, DRIVE_PATH, } from '@reticlehq/core';
+import { MCP_SSE_PATH, MCP_MESSAGE_PATH, MCP_SHUTDOWN_EVENT, STATUS_PATH, STATUS_HOLD_QUERY, DRIVE_PATH, } from '@reticlehq/core';
 import { getSessionMetrics } from '../telemetry/session-metrics.js';
 import { noteAgentPeer, PEER_VERSION_PARAM, PEER_CONTRACT_PARAM, } from '../command/version/peer-announce.js';
 import { log } from '../log.js';
@@ -76,7 +76,9 @@ export function createSharedServer(options = {}) {
             }
         }
         if ('GET' === req.method && path === STATUS_PATH) {
-            const body = JSON.stringify(statusProvider?.() ?? { running: true });
+            // A setup run waiting on this daemon says so on its polls; see daemon-usefulness.
+            const held = url.searchParams.has(STATUS_HOLD_QUERY);
+            const body = JSON.stringify(statusProvider?.(held) ?? { running: true });
             res.writeHead(200, { 'Content-Type': 'application/json' });
             res.end(body);
             return;

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

@@ -1,11 +1,11 @@
 export { SseFrameParser, type SseFrame } from './sse-frame-parser.js';
-export { probeDaemon, waitForDaemon } from './proxy/proxy-daemon-probe.js';
+export { probeDaemon, waitForDaemon, waitForDaemonBind } from './proxy/proxy-daemon-probe.js';
 /**
  * Re-exported so every existing caller (and every spec) keeps importing the proxy's log from the
  * proxy. Where the code lives is a file-size decision; where it is imported from is an API.
  */
 export { accountProxyLogWrite, proxyLog, proxyLogPath, PROXY_LOG_CHECK_BYTES, recoverOversizedProxyLog, setProxyLogPort, } from './proxy/proxy-log.js';
-export { reconnectDelayMs, RECONNECT_BASE_MS, RECONNECT_CAP_MS } from './proxy/proxy-backoff.js';
+export { reconnectDelayMs } from './proxy/proxy-backoff.js';
 export { MCP_PROXY_HTTP_AGENT_OPTIONS, postToSession, shouldRetryUnsentPost, type PostFailure, } from './proxy/mcp-post-transport.js';
 /**
  * Overridable so the survival spec can reach exhaustion in seconds instead of minutes — the same

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

@@ -6,7 +6,7 @@ import { toolsChangedNotification } from './proxy/proxy-handshake.js';
 import { LOOPBACK_HOST, MCP_SSE_PATH, MCP_SHUTDOWN_EVENT, ReticleEnv, CONTRACT_FINGERPRINT, } from '@reticlehq/core';
 import { SseFrameParser } from './sse-frame-parser.js';
 export { SseFrameParser } from './sse-frame-parser.js';
-export { probeDaemon, waitForDaemon } from './proxy/proxy-daemon-probe.js';
+export { probeDaemon, waitForDaemon, waitForDaemonBind } from './proxy/proxy-daemon-probe.js';
 import { probeDaemon } from './proxy/proxy-daemon-probe.js';
 import { SERVER_VERSION } from '../../command/version/identity/server-version.js';
 import { buildServerInstructions } from './server-instructions.js';
@@ -33,7 +33,7 @@ import { OutageReason, OutageStage, reportMcpOutage } from './faults/mcp-outage.
 import { postToSession } from './proxy/mcp-post-transport.js';
 import { reconnectDelayMs } from './proxy/proxy-backoff.js';
 import { PROXY_IDLE_EXIT_EVENT, ProxyIdleExit, resolveProxyIdleExitMs } from './proxy-idle-exit.js';
-export { reconnectDelayMs, RECONNECT_BASE_MS, RECONNECT_CAP_MS } from './proxy/proxy-backoff.js';
+export { reconnectDelayMs } from './proxy/proxy-backoff.js';
 export { MCP_PROXY_HTTP_AGENT_OPTIONS, postToSession, shouldRetryUnsentPost, } from './proxy/mcp-post-transport.js';
 /**
  * How many consecutive failed reconnects before the proxy stops RETRYING. It does not stop serving:

package/dist/surface/mcp/mcp.js

@@ -103,7 +103,7 @@ import { firstSentence } from '../tools/first-sentence.js';
  * making it a pointer costs nothing.
  */
 const PREDICATE_KINDS = 'Predicate object: { kind, ...fields }. kind is one of element | text | net | route | console | ' +
-    'animation | signal | state | settled | allOf | anyOf | not.';
+    'animation | signal | state | settled | compare | allOf | anyOf | not.';
 /**
  * Said once per turn: the bug-catching options, and where to get the rest of the field grammar.
  *
@@ -118,9 +118,11 @@ const PREDICATE_KINDS = 'Predicate object: { kind, ...fields }. kind is one of e
  * paying for six.
  */
 const PREDICATE_FIELD_GRAMMAR_HINT = ' Bug-catching options: net.count (exact request count — catches double-submit), ' +
-    'net.bodyMatches (a shallow JSON match on what the SERVER answered — say the FIELD and its value, ' +
+    'net.bodyMatches (a JSON field match on what the SERVER answered — say the FIELD (a dotted path reaches nested ones) and its value, ' +
     'because a substring of the body matches key names too), net.requestBodyMatches (the same on what ' +
     'the UI SENT — the verdict for "applying this filter actually puts it in the payload"), ' +
+    '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 ' +
     'grammar of a kind.';

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/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>;
 }
 /**