@reticlehq/server 2.8.0 → 2.9.0

package/dist/tools/invoke-tool.js

@@ -1,11 +1,11 @@
 import { healthEnvelope } from '../session/session-health.js';
-import { TelemetryActor, TelemetryEventKind, TRANSPORT_LIMITS, } from '@reticlehq/core';
+import { TelemetryActor, TelemetryEventKind, TRANSPORT_LIMITS, fingerprintFinding, } from '@reticlehq/core';
 import { getSessionMetrics } from '../telemetry/session-metrics.js';
 import { getTelemetry } from '../telemetry/telemetry.js';
 import { takeUpdateNudge } from '../update/update-nudge.js';
 import { takeVersionSkew } from '../version/version-nudge.js';
 import { noteToolCall } from '../daemon/daemon-usefulness.js';
-import { bugsInResult } from '../telemetry/bug-found.js';
+import { bugsInResult, routeOf } from '../telemetry/bug-found.js';
 import { noteToolServed, reportToolRefused } from '../telemetry/tool-refused.js';
 import { buildErrorPayload, refusalReasonFor } from './error-recovery.js';
 import { resultIsError } from '../mcp/mcp-is-error.js';
@@ -17,6 +17,7 @@ import { takeFeedbackPrompt } from './feedback-tools.js';
 import { takeFeedbackUndelivered } from '../telemetry/feedback-delivery.js';
 import { noteRefsMinted, wrongTabRefusal } from '../session/ref-provenance.js';
 import { span } from '../trace.js';
+import { deltaForToolResult, impactSnapshot, initImpact, recordImpact, } from '../impact/impact-recorder.js';
 import { frictionOf, inviteFor } from './feedback-invite.js';
 /**
  * The live-session tools whose result MUST carry the
@@ -141,14 +142,19 @@ function reportBugsFound(toolName, result) {
     if (0 === bugs.length)
         return;
     const metrics = getSessionMetrics();
+    const route = routeOf(result);
     for (const bug of bugs) {
         // `recordBug` answers whether this kind is new to the session, which is the only thing that
         // separates "another defect" from "the same defect again". Counting instances as defects is how
         // a published number inflates itself.
         const first = metrics.recordBug(bug.kind);
+        const identity = route !== undefined
+            ? { kind: bug.kind, source: bug.source, route }
+            : { kind: bug.kind, source: bug.source };
+        const fingerprint = fingerprintFinding(identity);
         void getTelemetry().emit(TelemetryEventKind.BUG_FOUND, {
             actor: TelemetryActor.AGENT,
-            bug: { ...bug, repeat: !first },
+            bug: { ...bug, repeat: !first, fingerprint },
         });
     }
 }
@@ -239,6 +245,9 @@ export async function runTool(tool, deps, args) {
     // closure carries this call's own identity, which is also what makes peak-concurrency measurable.
     // A daemon that has served even one tool call is doing a job for somebody; see daemon-usefulness.
     noteToolCall();
+    // The impact record needs the project's own `.reticle` root, and this is the first place every
+    // call knows it. Idempotent: the first root wins for the daemon's lifetime.
+    initImpact({ reticleRoot: deps.reticleRoot });
     // An oversized argument is refused BEFORE the handler deserialises it.
     //
     // tool-fuzz failed CI on the invariant that matters most — `every tool answers every hostile call`
@@ -352,6 +361,14 @@ export async function runTool(tool, deps, args) {
     // throw path would have measured half the wall and called it the whole of it, the same way `isError`
     // once did. A call that was served clears the retry chain, so the next refusal after it is a first
     // refusal rather than a retry of something unrelated.
+    // The user's own record of what Reticle did for them. Same chokepoint as everything else that
+    // counts, for the same reason: a second recording site is a second thing to forget. Separate
+    // store from telemetry - this one never leaves the machine.
+    recordImpact(deltaForToolResult(raw, Date.now() - startedAt, resultIsError(raw)));
+    // ...and the tab being driven is told, so the report is live rather than a thing you reload.
+    // Optional-call, not optional-chain-on-the-object: a test double is a partial Session, and a
+    // courtesy push must never be the reason a tool call throws.
+    session?.pushImpact?.(impactSnapshot);
     if (resultIsError(raw))
         reportRefusal(tool.name, raw.error);
     else {

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

@@ -5,13 +5,35 @@
  * — 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 declare function leaseNotConnectedHint(url: string, port: number): string;
+/** What the daemon can say for certain at the moment a lease comes back unconnected. */
+export interface LeaseEvidence {
+    /** A dial WAS made and turned away, with the reason. The only certain cause there is. */
+    refusal?: string;
+    /** An app for this project has connected on this port before (durable, survives a restart). */
+    previouslyConnected?: boolean;
+    /** The project has been through `init` — so recommending it again cannot help. */
+    initialized?: boolean;
+    /** The framework `.reticle.json` declares, used to rank rather than to decorate. */
+    framework?: string;
+    /**
+     * Whether any Reticle marker was found in the page the lease loaded.
+     *
+     * The single bit that separates the two commonest cases — "this app ships no SDK" and "the SDK
+     * loaded but could not reach the daemon" — which today produce identical messages. Absent means
+     * NOT CHECKED, and an absent bit prints nothing: a marker check that could not run must not be
+     * reported as a marker that was not found.
+     */
+    sdkMarker?: boolean;
+}
+export declare function leaseNotConnectedHint(url: string, port: number, evidence?: LeaseEvidence): string;

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

@@ -71,4 +71,15 @@ export declare function acquireLeasedSession(pool: {
     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
@@ -129,102 +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.'),
-            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(),
-        },
-        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.
-            // 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
-                    ? {}
-                    : {
-                        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.'),
     },
-    {
-        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');
+    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(),
+    },
+    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/observe-tools.js

@@ -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/react-grace.d.ts

@@ -30,6 +30,10 @@ import type { SettleSource } from './settle-in-flight.js';
  * 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;

package/dist/tools/react-grace.js

@@ -23,7 +23,7 @@
  * 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 { EventType } from '@reticlehq/core';
+import { EventType, MUTATING_METHODS } from '@reticlehq/core';
 /**
  * How long to let the app react. A React commit after a resolved fetch is one or two task hops; this
  * is generous against that and still far too short to paper over an app that genuinely dropped the
@@ -32,7 +32,6 @@ import { EventType } from '@reticlehq/core';
 const REACTION_GRACE_MS = 300;
 /** Poll cadence — the same as the settle wait, for the same reason. */
 const POLL_MS = 50;
-const MUTATING = ['POST', 'PUT', 'PATCH', 'DELETE'];
 /** Movement that would clear `response-ignored`; mirrors `uiAdvanced` in the detector. */
 const MOVEMENT = new Set([
     EventType.DOM_ADDED,
@@ -51,6 +50,10 @@ function moved(events) {
  * 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 function awaitsReaction(events) {
     if (moved(events))
@@ -60,7 +63,7 @@ export function awaitsReaction(events) {
             return false;
         const method = 'string' === typeof e.data['method'] ? e.data['method'].toUpperCase() : '';
         const ok = e.data['ok'];
-        return MUTATING.includes(method) && true === ok;
+        return MUTATING_METHODS.includes(method) && true === ok;
     });
 }
 /**

package/dist/tools/read-tools.js

@@ -39,6 +39,15 @@ function unanchoredWarning(count) {
 const HUD_LEVELS = ['info', 'warn', 'error'];
 const HUD_LEVEL_LIST = HUD_LEVELS.join(' | ');
 const hudLevelEnum = z.enum(HUD_LEVELS);
+/**
+ * How deep an unscoped `reticle_state` read goes before collapsing to size markers.
+ *
+ * 3 keeps every store name and every top-level key visible — enough to see what exists and to name a
+ * `path` — while collapsing the collections that make an unscoped read enormous. Measured on the
+ * bench fixture: unbounded 10,119 B, depth 4 1,323 B, depth 3 596 B, depth 2 322 B. Two loses the
+ * per-store keys, which is the orientation the next call needs.
+ */
+const DEFAULT_STATE_DEPTH = 1;
 export const READ_TOOLS = [
     {
         name: ReticleTool.BASELINE_SAVE,
@@ -395,7 +404,44 @@ export const READ_TOOLS = [
                 return { ...root, storeNames: names };
             }
             if (path === undefined && depth === undefined) {
-                return { ...root, storeNames: names }; // unchanged shape, safe storeNames
+                // An unscoped read used to hand back the WHOLE store tree: 10,119 bytes on this repo's own
+                // fixture. A tool result is not paid once — it stays in the conversation and is re-sent on
+                // every later turn, so one such read cost roughly 34,000 tokens across a 16-turn run.
+                //
+                // The VALUES are bounded; the ENVELOPE is not touched. `{ stores, storeNames, component }`
+                // is the documented shape and callers depend on it — a first attempt applied the bound by
+                // routing through the path selector, which silently changed the reply to `{ found, value }`
+                // and took the component projection and the bridge round-trip with it. Capping in place
+                // keeps every store name and the component read exactly where they were; only collections
+                // deeper than the bound collapse to a marker like "[Array(40)]", which still says what is
+                // there and how much of it.
+                //
+                // A default, not a cap: any explicit `depth` is honoured at any value, and `path` reads a
+                // sub-tree at full fidelity. Nothing became unreachable, only cheaper by default.
+                const stores = root.stores;
+                const bounded = 'object' === typeof stores && null !== stores
+                    ? Object.fromEntries(Object.entries(stores).map(([k, v]) => [k, capDepth(v, DEFAULT_STATE_DEPTH)]))
+                    : undefined;
+                // Say that it was bounded, and only when it actually was. A read that quietly hands back
+                // less than it was asked for is the shape of a false green: the agent sees
+                // `deployments: "[Array(40)]"`, concludes it has read the store, and asserts over a summary.
+                // The marker alone is suggestive; this makes it explicit and names the way to the real value.
+                const trimmed = bounded !== undefined && JSON.stringify(bounded) !== JSON.stringify(stores);
+                return {
+                    ...root,
+                    ...(bounded === undefined ? {} : { stores: bounded }),
+                    storeNames: names,
+                    ...(trimmed
+                        ? {
+                            truncation: {
+                                note: `bounded to depth ${String(DEFAULT_STATE_DEPTH)} per store — this is NOT the ` +
+                                    'whole store. Values shown as "[Array(n)]" or "{…n keys}" were collapsed; read ' +
+                                    'one with { store, path } (e.g. { store:"app", path:"deployments.0" }) or pass ' +
+                                    'an explicit `depth` for more.',
+                            },
+                        }
+                        : {}),
+                };
             }
             // Back-compat: an older browser returned the whole store; scope it here (may already be
             // size-truncated in transit for a very large store — that is the limitation this fix removes