@reticlehq/server 2.7.0 → 2.9.0

package/dist/tools/lease-hint.js

@@ -5,20 +5,71 @@
  * — it does not wait for the human's tab. Measured over a day: lease sessions had a median of 30
  * tool calls and produced 46% of all bugs found, against a median of 1 call for everything else.
  *
- * When it fails it is almost always a PORT MISMATCH: the tab loads, and the app's SDK dials the port
- * it was BUILT with, which need not be the daemon that issued the lease. Verified by driving it —
- * against a matching daemon `acquire` returns ready:true and the session is driveable immediately;
- * against a different one the tab connects to the OTHER daemon instead.
- *
  * The old hint asked "is <url> running with @reticlehq/core enabled?", which is the one thing that
- * cannot be in doubt: the pool just navigated a real browser to it. Naming the true cause first is
- * the difference between a two-minute fix and abandoning the best path Reticle has.
+ * cannot be in doubt: the pool just navigated a real browser to it. Its replacement then swung to
+ * the other confident-but-unevidenced claim — "the usual cause is a PORT MISMATCH" — and the daemon
+ * ended up contradicting ITSELF inside one response, saying in `reticle_sessions` that a session had
+ * connected earlier "so the wiring is correct" and here that the port was probably wrong. Across a
+ * batch of field reports on four apps the port was correct every single time, and `reticle init`
+ * would have been the wrong action every single time.
+ *
+ * So: rank by what the daemon actually knows, and fall back to the differential only when it knows
+ * nothing. A cause we hold positive evidence against is not printed at all.
  */
-export function leaseNotConnectedHint(url, port) {
-    return (`the leased tab loaded ${url} but never dialled this daemon (port ${String(port)}). The usual ` +
-        `cause is a PORT MISMATCH: the app's SDK connects to the port it was BUILT with, so a daemon on ` +
-        `a different port never hears from it — check the app's reticle port (\`.reticle.json\`, ` +
-        `RETICLE_PORT, or the build plugin's \`port\`) matches ${String(port)}, or start the daemon on ` +
-        `the port the app expects. If the app carries no Reticle SDK at all, run \`reticle init\` in it ` +
-        `first. The tab stays leased either way — release it with reticle_lease{action:"release"}.`);
+const NUXT = 'nuxt';
+const PORT_DIFFERENTIAL = "The usual cause is a PORT MISMATCH: the app's SDK connects to the port it was BUILT with, so a " +
+    "daemon on a different port never hears from it — check the app's reticle port (`.reticle.json`, " +
+    "RETICLE_PORT, or the build plugin's `port`), or start the daemon on the port the app expects.";
+/**
+ * The causes that actually occur on a wired app, in the order they occur. Mirrors the no-session
+ * diagnosis deliberately: two surfaces answering the same question must not rank it differently.
+ */
+const REAL_CAUSES = 'Causes that produce exactly this and are NOT a port problem: (a) the SDK is in the bundle but ' +
+    '`connect()` is never reached — a dev-mode guard or a missing runtime-config value returning ' +
+    'early, which emits nothing at all; (b) the dev server was started BEFORE the Reticle plugin was ' +
+    'added, so it is not in the bundle — restart it, HMR is not enough; (c) a peer dependency is ' +
+    'missing (typically `@reticlehq/react` in a non-React app) so the dynamic import fails silently; ' +
+    '(d) the page is not on localhost, where the SDK needs BOTH `allowNonLocalhost: true` and a ' +
+    'pairing token — the flag alone is not sufficient.';
+const NUXT_FIRST = 'This project is Nuxt: the most likely cause by a distance is a dev server that predates the ' +
+    'Reticle plugin, because Nuxt does NOT register a newly added plugin on HMR. Restart `nuxt dev` ' +
+    'and re-acquire before investigating anything else.';
+const RELEASE = 'The tab stays leased either way — release it with reticle_lease{action:"release"}.';
+function markerClause(sdkMarker) {
+    if (sdkMarker === undefined)
+        return '';
+    return sdkMarker
+        ? ' A Reticle SDK marker WAS found in the page that loaded, so the app does ship the SDK — the ' +
+            'question is only why it did not reach this daemon.'
+        : ' No Reticle SDK marker was found in the page that loaded. That is a check of the SERVED ' +
+            'document, so a lazily-imported SDK can still be missed — but combined with the rest it ' +
+            'points at a bundle that carries no Reticle at all, i.e. wiring that never took effect.';
+}
+export function leaseNotConnectedHint(url, port, evidence = {}) {
+    const opening = `the leased tab loaded ${url} but never dialled this daemon (port ${String(port)}).`;
+    const marker = markerClause(evidence.sdkMarker);
+    // 1. A recorded refusal. The only cause with proof behind it, so nothing outranks it.
+    if (evidence.refusal !== undefined) {
+        return `${opening} A dial DID arrive and was refused: ${evidence.refusal}${marker} ${RELEASE}`;
+    }
+    // 2. Nuxt, whose most likely cause differs from every other framework's and which `init` warns
+    //    about at install time — while this hint never mentioned it.
+    const nuxt = evidence.framework?.toLowerCase() === NUXT ? ` ${NUXT_FIRST}` : '';
+    // 3. Proven wiring. Blaming the port here is the self-contradiction this rewrite exists to end.
+    if (true === evidence.previouslyConnected) {
+        return (`${opening} An app for this project HAS connected on this port before, so the port and the ` +
+            `wiring are both correct — what is failing is the SDK reaching initialise on the page.${nuxt}` +
+            `${marker} ${REAL_CAUSES} ${RELEASE}`);
+    }
+    // 4. Wired, but never seen connect. Rank the real causes; keep the port differential last, where
+    //    the evidence for it actually sits.
+    if (true === evidence.initialized) {
+        return `${opening}${nuxt}${marker} ${REAL_CAUSES} If none of those, it may be dialling a different daemon than this one: check the app's reticle port matches ${String(port)}. ${RELEASE}`;
+    }
+    // 5. Nothing known. The differential, plus the possibility this app carries no SDK at all —
+    //    except when the marker check already ruled that out, which is the whole reason for the bit.
+    const noSdk = true === evidence.sdkMarker
+        ? ''
+        : ' If the app carries no Reticle SDK at all, run `reticle init` in it first.';
+    return `${opening}${nuxt}${marker} ${PORT_DIFFERENTIAL}${noSdk} ${REAL_CAUSES} ${RELEASE}`;
 }

package/dist/tools/lease-tools.d.ts

@@ -20,6 +20,26 @@ export declare function appendReticleParams(url: string, session: string, projec
  * of an internals-leaking wall of text.
  */
 export declare function cleanNavError(err: unknown): string;
+/**
+ * The session a lease's tab actually registered as, or undefined while nothing has.
+ *
+ * Normally that is the lease id: `appendReticleParams` stamps `__reticle_session` on the URL and the
+ * SDK adopts it. An app that passes an explicit `session` to `connect()` keeps its own name instead,
+ * which is legitimate — a single-app fixture does it deliberately so a battery can address it by a
+ * known id. Matching on the lease id alone could never see those tabs, so the lease reported
+ * `ready: false` and a hint blaming a port mismatch while the session was connected and driveable.
+ *
+ * The URL marker is the evidence, and it is what makes this safe: two concurrent leases on one origin
+ * carry different markers, so neither can adopt the other's tab. Parsed rather than substring-matched,
+ * so `lease-abc` cannot claim `lease-abcdef`.
+ */
+export declare function resolveLeasedSessionId(sessions: {
+    get: (id: string) => unknown;
+    all: () => {
+        id: string;
+        url?: string;
+    }[];
+}, leaseId: string): string | undefined;
 /**
  * Poll until the leased tab's SDK has actually registered on the bridge, so the sessionId we return
  * is immediately usable (the page navigates first, then connects a moment later — without this wait
@@ -38,9 +58,28 @@ export declare function acquireLeasedSession(pool: {
         sessionId: string;
         release: () => Promise<void>;
     }>;
-}, hasSession: (id: string) => boolean, url: string, projectId?: string): Promise<{
+    /** Optional so a test double need not implement it; the real pool always does. */
+    alias?: (registeredId: string, leaseId: string) => void;
+}, sessions: {
+    get: (id: string) => unknown;
+    all: () => {
+        id: string;
+        url?: string;
+    }[];
+}, url: string, projectId?: string): Promise<{
     sessionId: string;
     release: () => Promise<void>;
 }>;
 export declare function waitForLeasedSession(isConnected: () => boolean, sleeper?: (ms: number) => Promise<void>, attempts?: number, pollMs?: number): Promise<boolean>;
+/**
+ * Named on its own because `reticle drive <url>` runs it too.
+ *
+ * When a daemon already owns the bridge port, `drive` asks that daemon for a browser instead of
+ * competing for the port (see cli/drive-attach.ts), and the browser it should get is exactly the one
+ * an agent gets: same pool, same isolation, same reporting. Sharing the ToolDef rather than the
+ * handler keeps that literal — the drive route dispatches through `runTool`, so it is counted like
+ * any other call instead of being a second, invisible dispatch path.
+ */
+export declare const LEASE_ACQUIRE_TOOL: ToolDef;
+export declare const LEASE_RELEASE_TOOL: ToolDef;
 export declare const LEASE_TOOLS: ToolDef[];

package/dist/tools/lease-tools.js

@@ -10,9 +10,32 @@
  */
 import { z } from 'zod';
 import { leaseNotConnectedHint } from './lease-hint.js';
+import { readProjectFramework, readProjectId } from '../cli/cli-port.js';
+import { hasConnectedBefore } from '../session/connection-memory.js';
+import { reticleStateHome } from '../daemon/daemon.js';
 import { RETICLE_URL_PARAM, RETICLE_DEFAULT_PORT } from '@reticlehq/core';
 import { ReticleTool } from './tool-names.js';
 import { asString } from './tools-helpers.js';
+import { chromiumHint } from '../cli/chromium-hint.js';
+/**
+ * Everything the daemon already knows about why a leased tab might not have dialled in.
+ *
+ * Gathered here rather than guessed in the hint, because the daemon HAD this evidence all along and
+ * printed a static differential over the top of it — telling one agent in `reticle_sessions` that
+ * the wiring was proven correct and telling it seconds later that the port was probably wrong.
+ */
+function leaseEvidence(deps, port) {
+    const cwd = process.cwd();
+    const projectId = readProjectId(cwd);
+    const refusal = deps.sessions.lastClosure()?.reason;
+    const framework = readProjectFramework(cwd);
+    return {
+        ...(refusal === undefined ? {} : { refusal }),
+        ...(framework === undefined ? {} : { framework }),
+        previouslyConnected: hasConnectedBefore(reticleStateHome(), port, projectId),
+        initialized: projectId !== undefined,
+    };
+}
 const POOL_UNAVAILABLE = 'browser pool unavailable — the lease tools need the daemon-managed pool (start Reticle via `reticle mcp`).';
 /**
  * Append Reticle identity params (__reticle_session, optional __reticle_project) to a URL so the app's own SDK
@@ -64,6 +87,34 @@ function newLeaseId() {
         : `${String(Date.now())}-${String(performance.now())}`;
     return `lease-${uuid}`;
 }
+/**
+ * The session a lease's tab actually registered as, or undefined while nothing has.
+ *
+ * Normally that is the lease id: `appendReticleParams` stamps `__reticle_session` on the URL and the
+ * SDK adopts it. An app that passes an explicit `session` to `connect()` keeps its own name instead,
+ * which is legitimate — a single-app fixture does it deliberately so a battery can address it by a
+ * known id. Matching on the lease id alone could never see those tabs, so the lease reported
+ * `ready: false` and a hint blaming a port mismatch while the session was connected and driveable.
+ *
+ * The URL marker is the evidence, and it is what makes this safe: two concurrent leases on one origin
+ * carry different markers, so neither can adopt the other's tab. Parsed rather than substring-matched,
+ * so `lease-abc` cannot claim `lease-abcdef`.
+ */
+export function resolveLeasedSessionId(sessions, leaseId) {
+    if (sessions.get(leaseId) !== undefined)
+        return leaseId;
+    return sessions.all().find((s) => sessionParamOf(s.url) === leaseId)?.id;
+}
+function sessionParamOf(url) {
+    if (url === undefined)
+        return undefined;
+    try {
+        return new URL(url).searchParams.get(RETICLE_URL_PARAM.SESSION) ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 const LEASE_READY_ATTEMPTS = 100;
 const LEASE_READY_POLL_MS = 100;
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
@@ -78,11 +129,20 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
  * Returns the session id plus its release; the caller must release in a finally so a crashed flow never
  * leaks a pool slot and starves the rest of the suite.
  */
-export async function acquireLeasedSession(pool, hasSession, url, projectId) {
+export async function acquireLeasedSession(pool, sessions, url, projectId) {
     const sessionId = newLeaseId();
     const lease = await pool.acquire(appendReticleParams(url, sessionId, projectId), { sessionId });
-    await waitForLeasedSession(() => hasSession(lease.sessionId));
-    return { sessionId: lease.sessionId, release: () => lease.release() };
+    // Resolved, not assumed — see resolveLeasedSessionId. The parallel suite replays against whatever
+    // id comes back, so handing it the lease id for an app that named its own session sent every flow
+    // in the run at a session that does not exist.
+    let registeredId;
+    await waitForLeasedSession(() => {
+        registeredId = resolveLeasedSessionId(sessions, lease.sessionId);
+        return registeredId !== undefined;
+    });
+    if (registeredId !== undefined)
+        pool.alias?.(registeredId, lease.sessionId);
+    return { sessionId: registeredId ?? lease.sessionId, release: () => lease.release() };
 }
 export async function waitForLeasedSession(isConnected, sleeper = sleep, attempts = LEASE_READY_ATTEMPTS, pollMs = LEASE_READY_POLL_MS) {
     for (let i = 0; i < attempts; i++) {
@@ -92,86 +152,124 @@ export async function waitForLeasedSession(isConnected, sleeper = sleep, attempt
     }
     return isConnected();
 }
-export const LEASE_TOOLS = [
-    {
-        name: ReticleTool.LEASE_ACQUIRE,
-        description: 'Lease a fresh isolated headless browser context from the shared pool and navigate it to the app URL (the app must already be running and embed @reticlehq/core). Returns the sessionId the leased tab registers — pass it to other tools. The pool keeps all leases in ONE browser and caps concurrency; if at capacity this waits for a free slot. Release with reticle_lease{action:"release"} when the flow is done.',
-        inputSchema: {
-            url: z
-                .string()
-                .describe('URL of the already-running app to drive (e.g. http://localhost:3000/dashboard).'),
-            projectId: z
-                .string()
-                .optional()
-                .describe('Stable project id to stamp on the leased tab so the agent can scope to it.'),
-        },
-        outputSchema: {
-            sessionId: z.string(),
-            url: z.string(),
-            ready: z
-                .boolean()
-                .describe('Whether the leased tab connected — false ⇒ the app may not embed @reticlehq/core.'),
-            leased: z.number().describe('How many contexts are currently leased from the pool.'),
-            queued: z.number().describe('How many acquires are waiting for a free slot.'),
-            hint: z.string().optional(),
-        },
-        handler: async (deps, args) => {
-            const pool = deps.pool;
-            if (pool === undefined)
-                throw new Error(POOL_UNAVAILABLE);
-            const url = asString(args['url']);
-            if (url === undefined || 0 === url.length)
-                throw new Error('reticle_lease{action:"acquire"} requires a url');
-            const projectId = asString(args['projectId']);
-            const sessionId = newLeaseId();
-            const navUrl = appendReticleParams(url, sessionId, projectId);
-            let lease;
-            try {
-                lease = await pool.acquire(navUrl, { sessionId });
-            }
-            catch (err) {
-                // A raw page.goto failure is noisy and leaks the internal URL params — surface a clean,
-                // actionable message instead.
-                throw new Error(`could not open ${url} — is the app running there? (${cleanNavError(err)})`);
-            }
-            // Wait for the leased tab's SDK to connect so the returned sessionId is usable right away.
-            const ready = await waitForLeasedSession(() => deps.sessions.get(lease.sessionId) !== undefined);
-            return {
-                sessionId: lease.sessionId,
-                url,
-                ready,
-                leased: pool.activeCount(),
-                queued: pool.queuedCount(),
-                ...(ready
-                    ? {}
-                    : {
-                        hint: leaseNotConnectedHint(url, deps.bridgePort ?? RETICLE_DEFAULT_PORT),
-                    }),
-            };
-        },
+/**
+ * Named on its own because `reticle drive <url>` runs it too.
+ *
+ * When a daemon already owns the bridge port, `drive` asks that daemon for a browser instead of
+ * competing for the port (see cli/drive-attach.ts), and the browser it should get is exactly the one
+ * an agent gets: same pool, same isolation, same reporting. Sharing the ToolDef rather than the
+ * handler keeps that literal — the drive route dispatches through `runTool`, so it is counted like
+ * any other call instead of being a second, invisible dispatch path.
+ */
+export const LEASE_ACQUIRE_TOOL = {
+    name: ReticleTool.LEASE_ACQUIRE,
+    description: 'Lease a fresh isolated headless browser context from the shared pool and navigate it to the app URL (the app must already be running and embed @reticlehq/core). Returns the sessionId the leased tab registers — pass it to other tools. The pool keeps all leases in ONE browser and caps concurrency; if at capacity this waits for a free slot. Release with reticle_lease{action:"release"} when the flow is done.',
+    inputSchema: {
+        url: z
+            .string()
+            .describe('URL of the already-running app to drive (e.g. http://localhost:3000/dashboard).'),
+        projectId: z
+            .string()
+            .optional()
+            .describe('Stable project id to stamp on the leased tab so the agent can scope to it.'),
+    },
+    outputSchema: {
+        sessionId: z.string(),
+        url: z.string(),
+        ready: z
+            .boolean()
+            .describe('Whether the leased tab connected — false ⇒ the app may not embed @reticlehq/core.'),
+        expiresInMs: z
+            .number()
+            .describe('Milliseconds until this lease expires if untouched. Each tool call that targets this session resets the clock. Plan your work to finish or re-acquire before this runs out.'),
+        leased: z.number().describe('How many contexts are currently leased from the pool.'),
+        queued: z.number().describe('How many acquires are waiting for a free slot.'),
+        hint: z.string().optional(),
     },
-    {
-        name: ReticleTool.LEASE_RELEASE,
-        description: 'Release a leased browser context by sessionId, closing it and freeing the pool slot for a queued acquire. Call this when a flow finishes so the pool stays within its concurrency cap.',
-        inputSchema: {
-            sessionId: z
-                .string()
-                .describe('The leased sessionId returned by reticle_lease{action:"acquire"}.'),
-        },
-        outputSchema: {
-            released: z.boolean(),
-            leased: z.number(),
-        },
-        handler: async (deps, args) => {
-            const pool = deps.pool;
-            if (pool === undefined)
-                throw new Error(POOL_UNAVAILABLE);
-            const sessionId = asString(args['sessionId']);
-            if (sessionId === undefined || 0 === sessionId.length) {
-                throw new Error('reticle_lease{action:"release"} requires a sessionId');
+    handler: async (deps, args) => {
+        const pool = deps.pool;
+        if (pool === undefined)
+            throw new Error(POOL_UNAVAILABLE);
+        const url = asString(args['url']);
+        if (url === undefined || 0 === url.length)
+            throw new Error('reticle_lease{action:"acquire"} requires a url');
+        // Preflight the browser before spending the round trip. Without it a missing Playwright Chromium
+        // only surfaces inside pool.acquire, where the launch failure is caught and reported as
+        // "could not open <url> — is the app running?" — sending the caller to debug an app that is
+        // fine. Say the real thing at the first refusal instead. The phrasing carries "Chromium is not
+        // installed" so error-recovery routes it to the NO_POOL fix (install + drive a human tab).
+        if (deps.browserProbe !== undefined) {
+            const probe = await deps.browserProbe();
+            if (!probe.exists) {
+                throw new Error(`Chromium is not installed for Playwright — ${chromiumHint(probe)}`);
             }
-            await pool.release(sessionId);
-            return { released: true, leased: pool.activeCount() };
-        },
+        }
+        const projectId = asString(args['projectId']);
+        const sessionId = newLeaseId();
+        const navUrl = appendReticleParams(url, sessionId, projectId);
+        let lease;
+        try {
+            lease = await pool.acquire(navUrl, { sessionId });
+        }
+        catch (err) {
+            // A raw page.goto failure is noisy and leaks the internal URL params — surface a clean,
+            // actionable message instead.
+            throw new Error(`could not open ${url} — is the app running there? (${cleanNavError(err)})`);
+        }
+        // Wait for the leased tab's SDK to connect so the returned sessionId is usable right away.
+        // Resolved rather than assumed: an app that names its own session registers under that name,
+        // and the id we hand back has to be the one the agent can actually drive.
+        let registeredId;
+        const ready = await waitForLeasedSession(() => {
+            registeredId = resolveLeasedSessionId(deps.sessions, lease.sessionId);
+            return registeredId !== undefined;
+        });
+        // Tell the pool the other name this lease answers to. Every later touch and release arrives
+        // under the id we are about to hand back, and the pool is keyed by the id it navigated with;
+        // without this the touches miss, the lease ages out despite continuous activity, and the
+        // reaper closes the context mid-flow. See BrowserPool.alias and #157.
+        if (registeredId !== undefined)
+            pool.alias(registeredId, lease.sessionId);
+        return {
+            sessionId: registeredId ?? lease.sessionId,
+            url,
+            ready,
+            expiresInMs: pool.leaseTtlMs(),
+            leased: pool.activeCount(),
+            queued: pool.queuedCount(),
+            ...(ready
+                ? {}
+                : (() => {
+                    const bridgePort = deps.bridgePort ?? RETICLE_DEFAULT_PORT;
+                    return {
+                        hint: leaseNotConnectedHint(url, bridgePort, leaseEvidence(deps, bridgePort)),
+                    };
+                })()),
+        };
+    },
+};
+export const LEASE_RELEASE_TOOL = {
+    name: ReticleTool.LEASE_RELEASE,
+    description: 'Release a leased browser context by sessionId, closing it and freeing the pool slot for a queued acquire. Call this when a flow finishes so the pool stays within its concurrency cap.',
+    inputSchema: {
+        sessionId: z
+            .string()
+            .describe('The leased sessionId returned by reticle_lease{action:"acquire"}.'),
+    },
+    outputSchema: {
+        released: z.boolean(),
+        leased: z.number(),
+    },
+    handler: async (deps, args) => {
+        const pool = deps.pool;
+        if (pool === undefined)
+            throw new Error(POOL_UNAVAILABLE);
+        const sessionId = asString(args['sessionId']);
+        if (sessionId === undefined || 0 === sessionId.length) {
+            throw new Error('reticle_lease{action:"release"} requires a sessionId');
+        }
+        await pool.release(sessionId);
+        return { released: true, leased: pool.activeCount() };
     },
-];
+};
+export const LEASE_TOOLS = [LEASE_ACQUIRE_TOOL, LEASE_RELEASE_TOOL];

package/dist/tools/navigate-result.js

@@ -30,7 +30,7 @@ arrival = null) {
     return {
         ...base,
         confirmed: false,
-        note: 'ok means the navigation was DISPATCHED, not that the page arrived — the SDK is torn down by ' +
+        note: 'ok means the navigation was DISPATCHED, not that the page arrived. The SDK is torn down by ' +
             'the navigation itself, so nothing here can see the new document. Call reticle_sessions to ' +
             'confirm a session reconnected at the new URL before acting; if none appears, the page did ' +
             'not load or is not instrumented.',

package/dist/tools/observe-tools.js

@@ -179,7 +179,7 @@ export const OBSERVE_TOOLS = [
             // never asked about.
             const actCursor = session.lastAct.cursor();
             const judgingTheAct = actCursor !== undefined && actCursor >= since;
-            const contradictions = findContradictions(filtered, judgingTheAct ? session.lastAct.effect() : {});
+            const contradictions = findContradictions(filtered, judgingTheAct ? { ...session.lastAct.effect(), actionSince: actCursor } : {});
             // carry session health — a throttled tab means the observed timeline may be incomplete.
             return withControl(session, {
                 ...report,
@@ -262,7 +262,7 @@ export const OBSERVE_TOOLS = [
             // undocumented here, including `route` — and "did submitting the login form navigate away"
             // is the most common thing an agent wants to assert. A field report reached us from an agent
             // that guessed `urlContains` on route (net's spelling) and got unrecognized_keys.
-            'Predicate to evaluate. Kinds: { signal, name } { net, urlContains|method|status|count } ' +
+            'Predicate to evaluate. Kinds: { signal, name } { net, urlContains|method|status|count|bodyContains } ' +
                 '{ state, path|equals } { route, pathname (exact) | contains (path+query+hash) } ' +
                 '{ element, testid|role|text } { text } { console, level|absent } { animation, name } ' +
                 '{ settled } — combine with { allOf | anyOf | not }. Prefer a signal/net/state consequence ' +
@@ -386,6 +386,10 @@ export const OBSERVE_TOOLS = [
                 .nonnegative()
                 .optional()
                 .describe('Keep only the most recent N matching calls (older are dropped and counted in droppedOldest) — cuts tokens on a wide window. Defaults to 200 when omitted; pass a higher number for more, or scope with since/until.'),
+            bodies: z
+                .boolean()
+                .optional()
+                .describe('Include request/response bodies (default true). Pass false for a body-free listing — method, url, status, timing only — for the common "did POST /x return 200?" read. Bodies dominate the payload, so this cuts the cheap case by a large factor.'),
             ...sessionIdShape,
         },
         outputSchema: {
@@ -411,6 +415,8 @@ export const OBSERVE_TOOLS = [
             const status = asNumber(args['status']);
             const ok = 'boolean' === typeof args['ok'] ? args['ok'] : undefined;
             const limit = asNumber(args['limit']);
+            // Default true keeps the current shape; `bodies: false` returns the body-free listing (#401).
+            const bodies = 'boolean' === typeof args['bodies'] ? args['bodies'] : true;
             const buffer = bufferEnvelope(session);
             // Completed calls + unresolved in-flight requests (a hung request shows as pending).
             const allNet = reconcileNet(await session.queryEvents({
@@ -425,14 +431,14 @@ export const OBSERVE_TOOLS = [
             }
             // Default the cap so an omitted `limit` can't dump a whole flooded session (since defaults to 0).
             const { events: budgeted, droppedOldest } = applyEventBudget(matched, limit ?? DEFAULT_QUERY_LIMIT);
-            const calls = budgeted.map(projectNetCall);
+            const calls = budgeted.map((e) => projectNetCall(e, bodies));
             // A zero-match FILTER already reports what did fire (netEmptyHint above). Zero calls at all
             // fell through as a bare `[]`, which is indistinguishable from an observer that is not
             // recording — and those need opposite responses. Say the look happened.
             return withSizeCost(noteEmptyRead({
                 calls,
                 ...(droppedOldest > 0 ? { total: matched.length, droppedOldest } : {}),
-                ...bodiesNotCaptured(calls),
+                ...(bodies ? bodiesNotCaptured(calls) : {}),
                 ...buffer,
             }, 'calls', { noun: 'network calls' }));
         },

package/dist/tools/observed-nothing.js

@@ -28,6 +28,6 @@ export function noteEmptyRead(result, key, context) {
         ...result,
         // The distinction the field sweep could not make: this is a RESULT, not a failure to look.
         observed: true,
-        note: `no ${context.noun}${window} — the observation ran and found none, which is a result, not a missing reading`,
+        note: `no ${context.noun}${window}; the observation ran and found none, which is a result, not a missing reading`,
     };
 }

package/dist/tools/react-grace.d.ts

@@ -0,0 +1,52 @@
+/**
+ * "The app ignored this response" is only sayable once the app has had a chance to read it.
+ *
+ * `response-ignored` fires when a write succeeded on the server and nothing on the client moved. It
+ * is a real and valuable finding — a lost write, a response parsed into the void, a render that never
+ * happened. It is also an ACCUSATION, and it is decided by where a window happens to end.
+ *
+ * Waiting for in-flight requests before taking the verdict made that boundary dangerous in a way it
+ * was not before. Previously the write was still pending when the window closed, so it never reached
+ * the settled list and this rule could not fire at all. Now the response lands inside the window BY
+ * DESIGN — and the app's re-render happens in a later task, a few milliseconds after it. Close the
+ * window in that gap and every channel agrees that the app took a successful write and did nothing.
+ *
+ * The verdict is then `verified:"no"` on a completely correct application, produced entirely by where
+ * we chose to stop looking. For a verification tool that is the more damaging direction of error: a
+ * false green is a missed catch, but a false accusation sends someone to fix code that is not broken,
+ * and it is how the instrument stops being believed.
+ *
+ * So the response is not the end of the window — the app's REACTION to it is. The grace is paid only
+ * in the exact case that would otherwise be accused: a successful mutating write with nothing moved
+ * after it. Every other action returns without a single poll.
+ *
+ * Deliberately short. This covers a task-boundary re-render, not a slow app: if nothing has moved
+ * within the grace, "ignored" has become an honest description and the finding should stand.
+ */
+import type { SettleSource } from './settle-in-flight.js';
+/**
+ * Is this a window that would be wrongly accused if it ended right now?
+ *
+ * True only for the accusable shape: a SUCCESSFUL MUTATING request settled, and nothing has moved. A
+ * read that changed nothing is a prefetch, a failed write is a different finding entirely, and an
+ * action that already moved the UI has nothing to wait for — none of them buy a grace period.
+ *
+ * "Mutating" is read from the same constant the accuser uses rather than restated here. Restating it
+ * is how `IPC` came to be absent from this list and present in that one, so on a desktop app every
+ * successful write skipped the grace and a correct app was told it had ignored its own response.
+ */
+export declare function awaitsReaction(events: readonly {
+    type: string;
+    data: Record<string, unknown>;
+}[]): boolean;
+/**
+ * Wait, bounded by BOTH the grace and the caller's remaining budget, for the app to react to a write
+ * it has just been told succeeded.
+ *
+ * Returns whether the app moved. A `false` is not a verdict — it hands the question back to the
+ * contradiction engine, which will raise `response-ignored` exactly as it does today. The point is
+ * only that by then the app has been given its chance, so the finding means what it says.
+ */
+export declare function waitForReaction(session: SettleSource, since: number, budgetMs: number, opts: {
+    sleep(ms: number): Promise<void>;
+}): Promise<boolean>;