@reticlehq/server 3.8.1 → 3.9.0

package/dist/start-wiring.d.ts

@@ -3,14 +3,39 @@ import type { StartOptions } from './start-options.js';
 import type { Bridge } from './portal/bridge/bridge.js';
 import type { RealInputProvider } from './portal/input/real-input.js';
 import { BrowserPool } from './portal/pool/browser-pool.js';
+import { type PageErrorJournal } from './portal/pool/page-error-journal.js';
+import type { PooledPageError } from './portal/pool/pool-contract.js';
 import { type InjectedConnect } from './portal/pool/zero-install.js';
+import type { NonceMinter } from './portal/production/production-activation.js';
 /**
  * Build the shared browser pool (one headless Chromium, N capped isolated leased contexts). Lazy —
  * no Chromium launches until the first lease — so creating it is free even when never used.
  */
 /** Where the zero-install reader connects: this daemon's own bridge, with its pairing token. */
 export declare function readerConnect(port: number, token: string | undefined): InjectedConnect;
-export declare function createBrowserPool(headless: boolean, reader: InjectedConnect): BrowserPool;
+/**
+ * The zero-install script for pages that connect to `reader`, built on first use and kept: the
+ * page that needs it is one whose app never connected. Undefined when this install has no reader.
+ *
+ * A page that is not on loopback gets a nonce minted for its origin in place of the pairing token.
+ * The bridge admits a WebSocket from an origin only while a nonce names it, so the reader on a
+ * deployed page was refused with a 403 (#2016). The nonce also keeps the machine's pairing token
+ * out of a page that somebody else serves.
+ *
+ * ponytail: the nonce lives for one drive (SESSION_NONCE_TTL_MS). A lease reloaded after that
+ * dials with a dead nonce; mint per navigation if that is ever seen.
+ */
+export declare function zeroInstallLoader(reader: InjectedConnect, nonces?: Pick<NonceMinter, 'mint'>): (url?: string) => string | undefined;
+export declare function createBrowserPool(headless: boolean, reader: InjectedConnect, onPageError?: (leaseId: string, error: PooledPageError) => void, onLeaseClosed?: (leaseId: string) => void, nonces?: Pick<NonceMinter, 'mint'>): BrowserPool;
+/**
+ * Journal the uncaught page errors the pool hears into the session that connects for that lease.
+ *
+ * The pool sees every throw its pages make from before the first navigation; the SDK only exists
+ * afterwards. Without this wiring an import-time crash — a blank page with no error text anywhere
+ * (#1966) — was invisible to the agent driving it. Returns the journal so the pool's sink can be
+ * handed over; the bridge hook is registered here.
+ */
+export declare function attachPageErrorJournal(bridge: Bridge): PageErrorJournal;
 /**
  * Route CDP-authoritative network detail onto the driven session's journal.
  *
@@ -26,7 +51,9 @@ export declare function makeNetworkDetailRouter(bridge: Bridge, driveUrl: string
  * so a failed launch never leaks a WS port. A past divergence between the two paths let daemon mode
  * run with a different setup — this removes that risk.
  */
-export declare function resolveRealInput(options: StartOptions, onNavigateError: () => Promise<void>, onNetworkDetail?: (detail: NetworkDetail) => void): Promise<{
+export declare function resolveRealInput(options: StartOptions, onNavigateError: () => Promise<void>, onNetworkDetail?: (detail: NetworkDetail) => void, 
+/** Where a driven page with no SDK connects the zero-install reader. Absent: it gets none. */
+reader?: InjectedConnect): Promise<{
     realInput?: RealInputProvider;
     owned?: {
         dispose: () => Promise<void>;

package/dist/start-wiring.js

@@ -23,7 +23,10 @@ import { SERVER_VERSION } from './command/version/identity/server-version.js';
 import { CdpRealInputProvider, LaunchedRealInputProvider } from './portal/input/real-input.js';
 import { BrowserPool } from './portal/pool/browser-pool.js';
 import { playwrightLauncher, resolveMaxContexts } from './portal/pool/playwright-launcher.js';
+import { makePageErrorJournal } from './portal/pool/page-error-journal.js';
+import { resolveLeasedSessionId } from './surface/tools/lease-tools.js';
 import { readReaderBundle, zeroInstallScript as zeroInstallScriptFor, } from './portal/pool/zero-install.js';
+import { offLoopbackOrigin } from './portal/pool/context-permissions.js';
 /**
  * Build the shared browser pool (one headless Chromium, N capped isolated leased contexts). Lazy —
  * no Chromium launches until the first lease — so creating it is free even when never used.
@@ -32,26 +35,84 @@ import { readReaderBundle, zeroInstallScript as zeroInstallScriptFor, } from './
 export function readerConnect(port, token) {
     return { url: bridgeWsUrl(port), ...(token === undefined ? {} : { token }) };
 }
-export function createBrowserPool(headless, reader) {
-    const maxContexts = resolveMaxContexts(process.env[ReticleEnv.MAX_CONTEXTS], cpus().length);
-    const genSessionId = () => `lease-${'function' === typeof globalThis.crypto?.randomUUID
-        ? globalThis.crypto.randomUUID()
-        : String(Date.now())}`;
-    // Built on first use and kept: the page that needs it is one whose app never connected.
+/**
+ * The zero-install script for pages that connect to `reader`, built on first use and kept: the
+ * page that needs it is one whose app never connected. Undefined when this install has no reader.
+ *
+ * A page that is not on loopback gets a nonce minted for its origin in place of the pairing token.
+ * The bridge admits a WebSocket from an origin only while a nonce names it, so the reader on a
+ * deployed page was refused with a 403 (#2016). The nonce also keeps the machine's pairing token
+ * out of a page that somebody else serves.
+ *
+ * ponytail: the nonce lives for one drive (SESSION_NONCE_TTL_MS). A lease reloaded after that
+ * dials with a dead nonce; mint per navigation if that is ever seen.
+ */
+export function zeroInstallLoader(reader, nonces) {
     let script;
-    const zeroInstallScript = () => {
+    return (url) => {
+        const origin = offLoopbackOrigin(url);
+        if (origin !== undefined && nonces !== undefined) {
+            const bundle = readReaderBundle();
+            if (bundle === undefined) {
+                return undefined;
+            }
+            return zeroInstallScriptFor(bundle, {
+                url: reader.url,
+                token: nonces.mint({ origin }).nonce,
+            });
+        }
         if (script === undefined) {
             const bundle = readReaderBundle();
             script = bundle === undefined ? null : zeroInstallScriptFor(bundle, reader);
         }
         return script ?? undefined;
     };
+}
+export function createBrowserPool(headless, reader, onPageError, onLeaseClosed, nonces) {
+    const maxContexts = resolveMaxContexts(process.env[ReticleEnv.MAX_CONTEXTS], cpus().length);
+    const genSessionId = () => `lease-${'function' === typeof globalThis.crypto?.randomUUID
+        ? globalThis.crypto.randomUUID()
+        : String(Date.now())}`;
     return new BrowserPool(playwrightLauncher({ headless }), {
         maxContexts,
         genSessionId,
-        zeroInstallScript,
+        zeroInstallScript: zeroInstallLoader(reader, nonces),
+        // The reader dials this origin; a lease off loopback adds it to the page CSP (#2016).
+        daemonOrigin: new URL(reader.url).origin,
         launchHeaded: playwrightLauncher({ headless: false }),
+        ...(onPageError === undefined ? {} : { onPageError }),
+        ...(onLeaseClosed === undefined ? {} : { onLeaseClosed }),
+    });
+}
+/**
+ * Journal the uncaught page errors the pool hears into the session that connects for that lease.
+ *
+ * The pool sees every throw its pages make from before the first navigation; the SDK only exists
+ * afterwards. Without this wiring an import-time crash — a blank page with no error text anywhere
+ * (#1966) — was invisible to the agent driving it. Returns the journal so the pool's sink can be
+ * handed over; the bridge hook is registered here.
+ */
+export function attachPageErrorJournal(bridge) {
+    const journal = makePageErrorJournal({
+        resolveSession: (leaseId) => {
+            // Same resolution the lease tool uses: the lease id, or the id of a session whose URL
+            // carries the lease marker — an app that registered under its own name still reaches its lease.
+            const id = resolveLeasedSessionId(bridge.sessions, leaseId);
+            if (id === undefined) {
+                return undefined;
+            }
+            const session = bridge.sessions.get(id);
+            return session === undefined ? undefined : session;
+        },
+    });
+    bridge.attachSessionCreate((session) => journal.onSessionCreate(session));
+    // The daemon runs for days; both of the journal's maps are keyed by things that end, so both
+    // endings are hooked. The bridge's end hook is additive — the durable journal's teardown runs too.
+    bridge.attachSessionEnd((session) => {
+        journal.onSessionEnd(session.id);
+        return Promise.resolve();
     });
+    return journal;
 }
 /**
  * Route CDP-authoritative network detail onto the driven session's journal.
@@ -98,7 +159,9 @@ export function makeNetworkDetailRouter(bridge, driveUrl) {
  * so a failed launch never leaks a WS port. A past divergence between the two paths let daemon mode
  * run with a different setup — this removes that risk.
  */
-export async function resolveRealInput(options, onNavigateError, onNetworkDetail) {
+export async function resolveRealInput(options, onNavigateError, onNetworkDetail, 
+/** Where a driven page with no SDK connects the zero-install reader. Absent: it gets none. */
+reader) {
     const driveUrl = options.driveUrl;
     if (driveUrl !== undefined && driveUrl.length > 0) {
         const headless = options.headless ?? true;
@@ -114,6 +177,7 @@ export async function resolveRealInput(options, onNavigateError, onNetworkDetail
                 ...(injectConnect !== undefined ? { injectConnect } : {}),
                 ...(storageState !== undefined ? { storageState } : {}),
                 ...(onNetworkDetail !== undefined ? { onNetworkDetail } : {}),
+                ...(reader !== undefined ? { zeroInstallScript: zeroInstallLoader(reader) } : {}),
             }));
         const launched = factory({ driveUrl, headless });
         try {

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

@@ -5,6 +5,8 @@ import { localInitializeResponse, degradedInstructions, isHandshakeLine, drainLi
 export { HandshakeReplay, RECONNECT_INITIALIZE_ID } from './proxy/proxy-handshake.js';
 import { isToolCallRequest, isToolsListRequest, ToolCatalogCache } from './tool-catalog-cache.js';
 import { rememberEnumerated, rememberProxyStarted, rememberToolCalled } from './attach-memory.js';
+import { initializeClientName, rememberAgentConnected } from './peer/agents-connected.js';
+import { agentClientOf } from '../../hooks/coding-agents.js';
 import { toolsChangedNotification } from './proxy/proxy-handshake.js';
 import { LOOPBACK_HOST, MCP_SSE_PATH, MCP_SHUTDOWN_EVENT, ReticleEnv, CONTRACT_FINGERPRINT, ProxyExitReason, PROXY_ID_PARAM, } from '@reticlehq/core';
 import { SseFrameParser, buildSessionUrl } from './sse-frame-parser.js';
@@ -17,7 +19,8 @@ import { hasAnyProjectConnectedBefore } from '../../memory/recall/prior/connecti
 import { projectIdsAt } from '../../command/cli/ports/resolve/cli-port.js';
 import { PEER_VERSION_PARAM, PEER_CONTRACT_PARAM, agentSessionQuery, } from '../../command/version/peer-announce.js';
 import { onStreamDrop, onClientRequest, onReconnectBudgetSpent, onQueueExpired, OnDrop, OnRequest, } from './proxy/proxy-lifecycle.js';
-import { describePresence, probePresence } from '../../command/daemon/binding/port-presence.js';
+import { probePresence } from '../../command/daemon/binding/port-presence.js';
+import { describePortState } from '../../command/daemon/port-state.js';
 import { PROXY_ID, flushProxyExit, noteProxyDrop, noteProxyToolCall, } from '../../telemetry/proxy-telemetry.js';
 export { flushProxyExit, reportWakeRefused } from '../../telemetry/proxy-telemetry.js';
 import { detectStack } from '../../telemetry/feedback-context.js';
@@ -513,7 +516,7 @@ boot) {
                     // The sentence `doctor` has always been able to say, in the log the agent's own process
                     // writes. A FOREIGN holder used to be indistinguishable from a free port here, and the
                     // proxy spun against it instead of saying which one it was.
-                    const sentence = describePresence(presence, port);
+                    const sentence = describePortState(presence, port);
                     proxyLog('reticle_mcp_proxy_dormant', { port, presence, note: sentence });
                     // Nothing is coming that could answer the client's handshake through this port, and the
                     // proxy now knows that rather than merely suspecting it. Waiting out LOCAL_HANDSHAKE_MS
@@ -792,6 +795,11 @@ boot) {
                 if (isToolsListRequest(trimmed)) {
                     rememberEnumerated(reticleStateHome(), port);
                 }
+                // WHICH agent connected, so the installer and `status` can say "Connected: Cursor ✓".
+                const client = agentClientOf(initializeClientName(trimmed));
+                if (client !== undefined) {
+                    rememberAgentConnected(reticleStateHome(), client);
+                }
                 // The hop every other check misses. Recorded on the REQUEST rather than a reply, because
                 // the question is whether anything ever left the agent — a call that leaves and gets no
                 // answer is a different fault from one that was never made, and only this side sees it.

package/dist/surface/mcp/mcp.js

@@ -12,6 +12,7 @@ import { buildDynamicTools, descriptionOf } from '../tools/dynamic-tools.js';
 import { runTool } from '../tools/invoke-tool.js';
 import { sessionEnvelopeShape, newSnapshotCache } from '../tools/tool-kit.js';
 import { buildErrorPayload, codedRefusalOf } from '../tools/error-recovery.js';
+import { withRepeatHint } from '../tools/repeat-hint.js';
 import { connectionSkew, takeVersionSkewOnto } from '../../command/version/version-nudge.js';
 import { resultIsError } from './faults/mcp-is-error.js';
 import { consumerVerdictRefusal, reservedVerdictKeysIn } from './consumer-verdict-guard.js';
@@ -149,8 +150,9 @@ function leanZodShape(shape, advertised, predicateAnchor) {
     let hintSpent = predicateAnchor !== undefined;
     for (const [key, schema] of Object.entries(shape)) {
         if (isPredicateParam(schema)) {
-            // Every tool keeps the kinds; only the navigation hint is anchored.
-            const compact = z.record(z.string(), z.unknown());
+            // Every tool keeps the kinds; only the navigation hint is anchored. A bare string is visible
+            // text (core's `PredicateSchema`), so the SDK must let it through to that parse.
+            const compact = z.union([z.string(), z.record(z.string(), z.unknown())]);
             out[key] = (schema.isOptional() ? compact.optional() : compact).describe(hintSpent ? PREDICATE_KINDS : COMPACT_PREDICATE_DESCRIPTION);
             hintSpent = true;
             continue;
@@ -769,7 +771,7 @@ tools = tableForSurface(profile)) {
                     content: [
                         {
                             type: 'text',
-                            text: JSON.stringify(liveCallValues(takeVersionSkewOnto(buildErrorPayload(message, codedRefusalOf(error)), deps.peerSkew), advertisedNames)),
+                            text: JSON.stringify(liveCallValues(takeVersionSkewOnto(withRepeatHint(buildErrorPayload(message, codedRefusalOf(error)), error), deps.peerSkew), advertisedNames)),
                         },
                     ],
                 };

package/dist/surface/mcp/peer/agents-connected.d.ts

@@ -0,0 +1,6 @@
+/** The `AgentClient` values of every agent that has connected. Empty on a missing or broken file. */
+export declare function connectedAgentClients(stateDir: string): ReadonlySet<string>;
+/** Record that `client` (an `AgentClient` value) connected. Written once per client. */
+export declare function rememberAgentConnected(stateDir: string, client: string): void;
+/** `clientInfo.name` of an MCP `initialize` request line, or undefined for any other line. */
+export declare function initializeClientName(line: string): string | undefined;

package/dist/surface/mcp/peer/agents-connected.js

@@ -0,0 +1,58 @@
+/**
+ * Which coding agents have connected to Reticle on this machine, by name.
+ *
+ * `attach-memory.ts` records that SOME client attached on a port. It cannot say which one, so with
+ * two agents a healthy one hides a broken one. This record keeps the client that the MCP
+ * `initialize` handshake names, as its closed `AgentClient` value. It is machine wide, because the
+ * installer runs before there is a project and therefore before there is a port.
+ *
+ * The proxy writes it when the request arrives. It records a fact that happened, never an inference
+ * from a config file. Best-effort in both directions: a hint never breaks the client path.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const RECORD_FILE = 'agents-connected.json';
+const INITIALIZE_METHOD = 'initialize';
+/** The `AgentClient` values of every agent that has connected. Empty on a missing or broken file. */
+export function connectedAgentClients(stateDir) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(stateDir, RECORD_FILE), 'utf8'));
+        return new Set(Array.isArray(parsed) ? parsed.filter((v) => 'string' === typeof v) : []);
+    }
+    catch {
+        return new Set();
+    }
+}
+/** Record that `client` (an `AgentClient` value) connected. Written once per client. */
+export function rememberAgentConnected(stateDir, client) {
+    const known = connectedAgentClients(stateDir);
+    if (known.has(client)) {
+        return;
+    }
+    try {
+        mkdirSync(stateDir, { recursive: true });
+        writeFileSync(join(stateDir, RECORD_FILE), JSON.stringify([...known, client]), 'utf8');
+    }
+    catch {
+        // An unwritable state home is reported elsewhere; it must not break the client path.
+    }
+}
+/** `clientInfo.name` of an MCP `initialize` request line, or undefined for any other line. */
+export function initializeClientName(line) {
+    try {
+        const msg = JSON.parse(line);
+        if ('object' !== typeof msg || null === msg) {
+            return undefined;
+        }
+        const { method, params } = msg;
+        if (INITIALIZE_METHOD !== method || 'object' !== typeof params || null === params) {
+            return undefined;
+        }
+        const info = params.clientInfo;
+        const name = 'object' === typeof info && null !== info ? info.name : undefined;
+        return 'string' === typeof name && 0 < name.length ? name : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -1,6 +1,7 @@
 import * as net from 'node:net';
 import { LOOPBACK_HOST } from '@reticlehq/core';
-import { describePresence, presenceIsUsable, probePresence, PortPresence, } from '../../../command/daemon/binding/port-presence.js';
+import { presenceIsUsable, probePresence, PortPresence, } from '../../../command/daemon/binding/port-presence.js';
+import { describePortState } from '../../../command/daemon/port-state.js';
 import { fetchStatus } from '../../../command/daemon/binding/daemon-status-probe.js';
 import { isAlive, readPid } from '../../../command/daemon/daemon.js';
 const DEFAULT_DAEMON_READY_TIMEOUT_MS = 10_000;
@@ -21,6 +22,16 @@ function delay(ms) {
 export function daemonPollDelayMs(attempt) {
     return Math.min(DAEMON_POLL_INTERVAL_MS * attempt, DAEMON_POLL_MAX_INTERVAL_MS);
 }
+const CONNECTION_RESET = 'ECONNRESET';
+/**
+ * A loopback connect to a port with no listener is refused at once. A timeout means a listener
+ * whose queue is full because it accepts nothing: a daemon stuck in its exit (#1937). Read as
+ * "free", that made `status` say the port was free while a process held it.
+ *
+ * Not on Windows: it retries a refused loopback connect for about two seconds, so there a timeout
+ * is also what a free port gives.
+ */
+const TIMEOUT_MEANS_HELD = 'win32' !== process.platform;
 /**
  * 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
@@ -38,10 +49,11 @@ export function probeDaemon(port, host = LOOPBACK_HOST) {
             socket.destroy();
             resolve(true);
         });
-        socket.on('error', () => resolve(false));
+        // A reset is an answer from a listener, not "nothing listens".
+        socket.on('error', (err) => resolve(CONNECTION_RESET === err.code));
         socket.on('timeout', () => {
             socket.destroy();
-            resolve(false);
+            resolve(TIMEOUT_MEANS_HELD);
         });
         socket.connect(port, host);
     });
@@ -70,7 +82,7 @@ export async function waitForDaemon(port, probes = { tcpOpen: probeDaemon, statu
             return;
         if (false === probes.alive?.()) {
             throw new Error(`the reticle daemon on port ${String(port)} exited before it was ready — ` +
-                describePresence(presence, port));
+                describePortState(presence, port));
         }
         attempt++;
         await delay(daemonPollDelayMs(attempt));
@@ -79,7 +91,7 @@ export async function waitForDaemon(port, probes = { tcpOpen: probeDaemon, statu
     // means something is squatting the port. Reporting only the timeout sent readers hunting the
     // wrong one.
     throw new Error(`reticle daemon did not become ready on port ${String(port)} within ` +
-        `${String(DAEMON_READY_TIMEOUT_MS)}ms — ${describePresence(presence, port)}`);
+        `${String(DAEMON_READY_TIMEOUT_MS)}ms — ${describePortState(presence, port)}`);
 }
 /** True while the process in the daemon pid file for `port` runs. */
 export function daemonProcessAlive(port) {

package/dist/surface/tools/act/act-preflight.js

@@ -11,6 +11,7 @@
  * outcome than "unknown".
  */
 import { PredicateSchema } from '@reticlehq/engine/question/predicate/predicate-schema.js';
+import { parsePredicate } from '@reticlehq/engine/question/predicate/predicate-parse.js';
 import { SESSION_REF, isGlobalPressCall, unissuedRefRefusal } from '@reticlehq/core';
 import { isDocumentGoneError } from '../../../portal/session/facts/session-replaced.js';
 import { SessionReplacedError } from '../../../portal/session/page-commands/pending-commands.js';
@@ -77,8 +78,9 @@ const STEP_STRUCTURE_KEYS = new Set([
 export function sequenceStepArgs(step) {
     const flat = {};
     for (const [key, value] of Object.entries(step)) {
-        if (!STEP_STRUCTURE_KEYS.has(key))
+        if (!STEP_STRUCTURE_KEYS.has(key)) {
             flat[key] = value;
+        }
     }
     const nested = step['args'];
     if ('string' === typeof nested) {
@@ -96,6 +98,22 @@ export function sequenceStepArgs(step) {
     }
     return { ...flat, ...(null !== nested && 'object' === typeof nested ? nested : {}) };
 }
+/**
+ * Why `parsePredicate` refuses this `expect`, as the sentence `reticle_assert` gives.
+ *
+ * Called only after `PredicateSchema` has refused the value, so the parse throws. The schema stays
+ * the test for refusal: `parsePredicate` also refuses a value that the schema accepts, and this
+ * check must not refuse more than it did before.
+ */
+function expectParseIssue(value) {
+    try {
+        parsePredicate(value);
+        return '';
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+}
 export function assertSequenceSteps(steps) {
     if (0 === steps.length) {
         throw new Error('reticle_act_sequence was given no steps. Pass steps: [{ ref, action, args? }] or [{ target, action, args? }] — nothing was acted on.');
@@ -118,18 +136,15 @@ export function assertSequenceSteps(steps) {
          * declared; nothing told it the declaration was discarded, and that sentence invites it to add
          * the very thing it just wrote. Same false green as an unreadable key, through a key this tool
          * does read.
+         *
+         * The reason is the sentence `reticle_assert` gives for the same predicate: the field that failed
+         * and the fields that work. A fixed sentence with generic examples did not say that `css` is not a
+         * `query` field, so the caller had to guess again. That sentence also carries the schema's own
+         * words, such as the keys it saw when it could not tell the kind.
          */
-        const parsed = step['expect'] === undefined ? undefined : PredicateSchema.safeParse(step['expect']);
-        if (parsed !== undefined && !parsed.success) {
-            // The schema's own words, such as the keys it saw when it could not tell the kind.
-            const said = parsed.error.issues
-                .filter((issue) => 'custom' === issue.code)
-                .map((issue) => ` ${issue.message}.`)
-                .join('');
-            throw new Error(`step ${String(i)} carries an \`expect\` this tool cannot parse.${said} ` +
-                'A consequence is a predicate object with a `kind` — e.g. { kind: "signal", name: ' +
-                '"order:placed" }, { kind: "element", by: "testid", value: "receipt" }, or ' +
-                '{ kind: "settled" } — the same shape reticle_act_and_wait takes as `until`. ' +
+        if (step['expect'] !== undefined && !PredicateSchema.safeParse(step['expect']).success) {
+            throw new Error(`step ${String(i)} carries an \`expect\` this tool cannot parse: ` +
+                `${expectParseIssue(step['expect'])} ` +
                 'Refused rather than dropped, because a step whose declaration was discarded reports ' +
                 'as a step that declared nothing. Nothing was acted on.');
         }
@@ -145,10 +160,12 @@ export function assertSequenceSteps(steps) {
             }
             return;
         }
-        if (step['target'] !== undefined)
+        if (step['target'] !== undefined) {
             return;
-        if (isGlobalPressCall(step))
+        }
+        if (isGlobalPressCall(step)) {
             return;
+        }
         throw new Error(`step ${String(i)} has no \`ref\` or \`target\`. ` +
             'Sequence steps take `ref` (from reticle_query/reticle_snapshot) or `target` ' +
             '(e.g. { testid } or { label }), the same locator reticle_act accepts. ' +
@@ -165,13 +182,15 @@ export function preflightAct(actArgs, until) {
     // the agent its trusted click had happened. See act-danger.
     assertNativeInputSupported(actArgs);
     const unevaluable = unevaluablePredicateReason(until);
-    if (unevaluable !== undefined)
+    if (unevaluable !== undefined) {
         throw new Error(unevaluable);
+    }
     // A predicate that was already true when it was written answered `no-fault` / `already_true` —
     // verdict-shaped, and carrying no proof of anything the action did. See vacuousPredicateReason.
     const vacuous = vacuousPredicateReason(until);
-    if (vacuous !== undefined)
+    if (vacuous !== undefined) {
         throw new Error(vacuous);
+    }
 }
 /**
  * Dispatch a write, or report that its outcome went unobserved.
@@ -191,8 +210,9 @@ export async function dispatchAct(send) {
         return await send();
     }
     catch (error) {
-        if (error instanceof SessionReplacedError || isDocumentGoneError(error))
+        if (error instanceof SessionReplacedError || isDocumentGoneError(error)) {
             return null;
+        }
         throw error;
     }
 }

package/dist/surface/tools/act/act-target.js

@@ -48,7 +48,9 @@ export async function resolveActTarget(session, args,
  * was ignored.
  */
 appearanceMs) {
-    const ref = asString(args['ref']);
+    // A ref inside the target object (`target: { ref }`) is the same instruction as a top-level ref.
+    // Read as a query it named nothing, and the step failed with "Nothing was searched".
+    const ref = asString(args['ref']) ?? asString(asRecord(args['target'])['ref']);
     if (ref !== undefined && ref.length > 0) {
         // Refused here, at the boundary, and never re-read as a `target`: guessing what an arbitrary
         // string meant is the silent re-resolution the stale-ref refusal exists to prevent.

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

@@ -9,9 +9,16 @@
  * nothing on its own.
  */
 import type { Predicate } from '@reticlehq/core';
+import { evaluatePredicate, type EvalResult } from '@reticlehq/engine/question/predicate/predicate.js';
 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>;
+/**
+ * A green that rests only on hidden matches, read again until a match shows, for at most
+ * SHOWN_GRACE_MS. Returns the reading that shows one, or `verdict` unchanged. Nothing is predicted:
+ * the verdict is judged on what the page painted, and a node that stays hidden stays `hidden_match`.
+ */
+export declare function awaitShownMatch(session: Parameters<typeof evaluatePredicate>[0], until: Predicate, since: number, baselines: Parameters<typeof evaluatePredicate>[4], verdict: EvalResult, remaining: () => number): Promise<EvalResult>;
 export {};

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

@@ -8,6 +8,8 @@
  * rest of the budget the caller already granted is spent here, in three steps, each deciding
  * nothing on its own.
  */
+import { hiddenMatchNote } from '@reticlehq/engine/evidence/already-true.js';
+import { evaluatePredicate, } from '@reticlehq/engine/question/predicate/predicate.js';
 import { waitForInFlight } from './settle-in-flight.js';
 import { waitForReaction } from './react-grace.js';
 import { revertedAfterMatch } from './durable.js';
@@ -28,3 +30,34 @@ export async function finishAfterMatch(session, until, since, baselines, remaini
     // 3. Then ask whether what held still holds — see revertedAfterMatch.
     return revertedAfterMatch(session, until, since, baselines);
 }
+/**
+ * How long a match that holds only on hidden nodes gets to show. An entrance fade or a toast mounted
+ * at opacity 0 reads hidden for its first frame, and the wait matched on that frame. A node hidden
+ * by design pays this once, on a verdict that is `unknown` either way.
+ */
+const SHOWN_GRACE_MS = 1000;
+/** Poll cadence — the same as the reaction grace. */
+const SHOWN_POLL_MS = 50;
+/**
+ * A green that rests only on hidden matches, read again until a match shows, for at most
+ * SHOWN_GRACE_MS. Returns the reading that shows one, or `verdict` unchanged. Nothing is predicted:
+ * the verdict is judged on what the page painted, and a node that stays hidden stays `hidden_match`.
+ */
+export async function awaitShownMatch(session, until, since, baselines, verdict, remaining) {
+    if (!verdict.pass || hiddenMatchNote(until, verdict.evidence) === undefined) {
+        return verdict;
+    }
+    // Counted in reads, not read off the session clock, so a clock that does not move still ends it.
+    const reads = Math.floor(Math.min(SHOWN_GRACE_MS, remaining()) / SHOWN_POLL_MS);
+    for (let read = 0; read < reads; read += 1) {
+        await new Promise((resolve) => setTimeout(resolve, SHOWN_POLL_MS));
+        const now = await evaluatePredicate(session, until, since, true, baselines);
+        if (!now.pass) {
+            return verdict;
+        }
+        if (hiddenMatchNote(until, now.evidence) === undefined) {
+            return now;
+        }
+    }
+    return verdict;
+}

package/dist/surface/tools/act/resolve-target.d.ts

@@ -9,6 +9,8 @@ export type TargetResolution = {
     readonly kind: 'error';
     readonly message: string;
 };
+/** The words before the nearest-target list in a no_match refusal. The repeat hint reads after it. */
+export declare const NEAREST_TARGETS_LEAD = " The nearest targets on the page, most similar first: ";
 /**
  * Turn a target QUERY into the single ref an action can be performed on.
  *