@reticlehq/server 2.2.1 → 2.4.0

package/dist/tools/invoke-tool.js

@@ -1,7 +1,13 @@
 import { healthEnvelope } from '../session/session-health.js';
-import { getTelemetry, TelemetryEventKind } from '../telemetry/telemetry.js';
+import { TelemetryActor, TelemetryEventKind } from '@reticlehq/core';
+import { getSessionMetrics } from '../telemetry/session-metrics.js';
+import { getTelemetry } from '../telemetry/telemetry.js';
+import { VERIFICATION_TOOLS } from './feedback-tools.js';
+import { takeUpdateNudge } from '../update/update-nudge.js';
+import { bugsInResult } from '../telemetry/bug-found.js';
 import { asString } from './tools-helpers.js';
 import { ReticleTool } from './tool-names.js';
+import { takeFeedbackPrompt } from './feedback-tools.js';
 /**
  * The live-session tools whose result MUST carry the
  * session-health envelope. Owned in ONE place — not retrofitted per handler — so a throttled tab
@@ -12,12 +18,17 @@ export const SESSION_BOUND_TOOLS = new Set([
     ReticleTool.SNAPSHOT,
     ReticleTool.QUERY,
     ReticleTool.INSPECT,
+    ReticleTool.COVERAGE,
+    ReticleTool.VERIFY_CHANGE,
     ReticleTool.ACT,
     ReticleTool.ACT_SEQUENCE,
     ReticleTool.ACT_AND_WAIT,
     ReticleTool.OBSERVE,
     ReticleTool.WAIT_FOR,
     ReticleTool.ASSERT,
+    // Reads the live page as well as the event window, so a throttled tab can make it compare a stale
+    // render against fresh data — exactly the case the health envelope exists to disclose.
+    ReticleTool.RECONCILE,
     ReticleTool.NETWORK,
     ReticleTool.CONSOLE,
     ReticleTool.ANIMATIONS,
@@ -56,10 +67,74 @@ export const SESSION_EXEMPT_TOOLS = new Set([
     ReticleTool.VIEWPORT, // own contract (applied/width/height); provider-driven, not a live-DOM read
     ReticleTool.ANNOTATE, // annotates a recording's steps; pure disk-side metadata, no live DOM read
     ReticleTool.LEASE, // merged acquire/release — its sessionId is a pool lease id, not a live session
+    // Its sessionId only enriches the report with the tab's runtime/engine, and it must stay callable
+    // when NO session exists — "nothing ever connected" is feedback we especially want.
+    ReticleTool.FEEDBACK,
 ]);
 function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+/**
+ * Emit `verification_completed` when a verification tool produced a verdict.
+ *
+ * Read off the RESULT here rather than emitted from `decideVerified`, which is where the verdict is
+ * actually decided: that function is pure, and the repo's rules keep clocks, IO and side effects out
+ * of pure logic for good reason. Reading the result also means all four verification tools are covered
+ * by one site instead of four handler edits, and a fifth is covered the moment it joins the set.
+ *
+ * `falseGreenCaught` is the one that matters: the assertion PASSED and Reticle still refused to call
+ * it verified. That is the product's entire thesis reduced to a boolean, and it is the number worth
+ * putting in front of an investor — not "tools were called" but "this many greens were caught lying".
+ */
+function recordVerification(toolName, result, durationMs) {
+    if (!VERIFICATION_TOOLS.has(toolName))
+        return;
+    const verified = typeof result['verified'] === 'string' ? result['verified'] : undefined;
+    // flow_verify reports `status: pass|fail`; assert reports a boolean `pass`. Accept either shape so
+    // the whole family is covered without normalizing four tools' contracts for a metric's convenience.
+    const passed = typeof result['pass'] === 'boolean'
+        ? result['pass']
+        : result['status'] === 'pass'
+            ? true
+            : undefined;
+    if (verified === undefined && passed === undefined)
+        return; // not a verdict-bearing result
+    const metrics = getSessionMetrics();
+    metrics.recordVerification();
+    void getTelemetry().emit(TelemetryEventKind.VERIFICATION_COMPLETED, {
+        actor: TelemetryActor.AGENT,
+        verification: {
+            via: toolName,
+            verified: verified ?? (passed === true ? 'yes' : 'no'),
+            passed: passed ?? verified === 'yes',
+            falseGreenCaught: passed === true && verified === 'no',
+            durationMs,
+        },
+    });
+}
+/**
+ * Emit one `bug_found` per defect in a tool result, and count it into the session.
+ *
+ * The outcome metric: everything else measures whether Reticle is used, this measures whether it
+ * works. Discrete events rather than only a counter, because the KIND distribution is the argument —
+ * "we found 4,000 bugs" is a claim, "1,200 were greens that lied" is evidence.
+ */
+function reportBugsFound(toolName, result) {
+    const bugs = bugsInResult(toolName, result);
+    if (bugs.length === 0)
+        return;
+    const metrics = getSessionMetrics();
+    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);
+        void getTelemetry().emit(TelemetryEventKind.BUG_FOUND, {
+            actor: TelemetryActor.AGENT,
+            bug: { ...bug, repeat: !first },
+        });
+    }
+}
 /**
  * The single entry point both the MCP server and the programmatic invoker call instead of
  * `tool.handler` directly. Runs the handler, then — for a live-session tool returning a plain
@@ -68,8 +143,16 @@ function isPlainObject(value) {
  */
 export async function runTool(tool, deps, args) {
     // Both dispatch paths (MCP + programmatic) pass through here — the one place "which tool is mostly
-    // used" can be counted. Fire-and-forget: telemetry never delays or fails a tool call.
-    void getTelemetry().emit(TelemetryEventKind.TOOL, { tool: tool.name });
+    // used" can be counted. This used to EMIT an event per call; it now increments an in-process counter
+    // that leaves once, with the session summary. A verification loop is 50–200 calls, and PostHog bills
+    // per event — so the old design made the telemetry bill scale with how hard people used the product,
+    // to answer a question the histogram answers better. Counting is also free: no network, no promise,
+    // nothing to fail on a tool call's hot path.
+    // Started/settled as a pair rather than a bare counter: several agents can be inside runTool at
+    // once, so a single "last start" field would attribute one tool's duration to another. The returned
+    // closure carries this call's own identity, which is also what makes peak-concurrency measurable.
+    const settleTiming = getSessionMetrics().startToolCall(tool.name, args);
+    const startedAt = Date.now();
     const rawSessionId = asString(args['sessionId']);
     const bound = SESSION_BOUND_TOOLS.has(tool.name);
     // Resolve the session identity ONCE, up front, for a live-session tool. The lease heartbeat must
@@ -90,7 +173,35 @@ export async function runTool(tool, deps, args) {
     const leaseId = session?.id ?? rawSessionId;
     if (leaseId !== undefined)
         deps.pool?.touch(leaseId);
-    const result = await tool.handler(deps, args);
+    let raw;
+    try {
+        raw = await tool.handler(deps, args);
+    }
+    finally {
+        // In a `finally` so a THROWN call still settles: otherwise every failing tool would leak a
+        // concurrency slot and peakConcurrentTools would climb forever on an unhealthy session.
+        settleTiming(Date.now() - startedAt);
+    }
+    // The human-feedback ask rides out on the first VERIFICATION that completes — the one moment the
+    // experience is fresh and there is something concrete to react to. It is spliced BEFORE the
+    // session-bound early return, because two of the four verification tools (flow_verify,
+    // verify_change) are session-EXEMPT and would otherwise never carry it.
+    if (isPlainObject(raw)) {
+        recordVerification(tool.name, raw, Date.now() - startedAt);
+        reportBugsFound(tool.name, raw);
+    }
+    const prompt = isPlainObject(raw) ? takeFeedbackPrompt(tool.name) : undefined;
+    // Same one-shot channel as the feedback ask: the agent is mid-task, so anything it would have to go
+    // and ASK for is something it will never ask for. Spliced on ANY tool result, not just a
+    // verification, because an out-of-date install is worth mentioning whatever the agent is doing.
+    const update = isPlainObject(raw) ? takeUpdateNudge() : undefined;
+    const result = prompt === undefined && update === undefined
+        ? raw
+        : {
+            ...raw,
+            ...(prompt !== undefined ? { feedback_prompt: prompt } : {}),
+            ...(update !== undefined ? { update_available: update } : {}),
+        };
     if (!bound || !isPlainObject(result))
         return result;
     // Reuse the session resolved above so the health envelope describes the SAME session the handler
@@ -112,4 +223,3 @@ export async function runTool(tool, deps, args) {
         envelope['session_age_warning'] = warning;
     return Object.keys(envelope).length > 0 ? { ...result, ...envelope } : result;
 }
-//# sourceMappingURL=invoke-tool.js.map

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

@@ -44,4 +44,3 @@ export declare function acquireLeasedSession(pool: {
 }>;
 export declare function waitForLeasedSession(isConnected: () => boolean, sleeper?: (ms: number) => Promise<void>, attempts?: number, pollMs?: number): Promise<boolean>;
 export declare const LEASE_TOOLS: ToolDef[];
-//# sourceMappingURL=lease-tools.d.ts.map

package/dist/tools/lease-tools.js

@@ -94,7 +94,7 @@ export async function waitForLeasedSession(isConnected, sleeper = sleep, attempt
 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_release when the flow is done.',
+        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()
@@ -120,7 +120,7 @@ export const LEASE_TOOLS = [
                 throw new Error(POOL_UNAVAILABLE);
             const url = asString(args['url']);
             if (url === undefined || url.length === 0)
-                throw new Error('reticle_lease_acquire requires a url');
+                throw new Error('reticle_lease{action:"acquire"} requires a url');
             const projectId = asString(args['projectId']);
             const sessionId = newLeaseId();
             const navUrl = appendReticleParams(url, sessionId, projectId);
@@ -153,7 +153,9 @@ export const LEASE_TOOLS = [
         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_acquire.'),
+            sessionId: z
+                .string()
+                .describe('The leased sessionId returned by reticle_lease{action:"acquire"}.'),
         },
         outputSchema: {
             released: z.boolean(),
@@ -165,11 +167,10 @@ export const LEASE_TOOLS = [
                 throw new Error(POOL_UNAVAILABLE);
             const sessionId = asString(args['sessionId']);
             if (sessionId === undefined || sessionId.length === 0) {
-                throw new Error('reticle_lease_release requires a sessionId');
+                throw new Error('reticle_lease{action:"release"} requires a sessionId');
             }
             await pool.release(sessionId);
             return { released: true, leased: pool.activeCount() };
         },
     },
 ];
-//# sourceMappingURL=lease-tools.js.map

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

@@ -40,4 +40,3 @@ export interface MergePlan {
  */
 export declare function applyMerges(tools: readonly ToolDef[], plans: readonly MergePlan[], retired?: readonly string[]): ToolDef[];
 export declare function mergeTools(spec: MergeSpec): ToolDef;
-//# sourceMappingURL=merge-tools.d.ts.map

package/dist/tools/merge-tools.js

@@ -63,4 +63,3 @@ export function mergeTools(spec) {
         },
     };
 }
-//# sourceMappingURL=merge-tools.js.map

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

@@ -1,3 +1,2 @@
 import { type ToolDef } from './tool-kit.js';
 export declare const OBSERVE_TOOLS: ToolDef[];
-//# sourceMappingURL=observe-tools.d.ts.map

package/dist/tools/observe-tools.js

@@ -6,12 +6,14 @@ import { z } from 'zod';
 import { ReticleCommand, DEFAULT_ASSERT_TIMEOUT_MS } from '@reticlehq/core';
 import { ReticleTool } from './tool-names.js';
 import { buildReactionReport } from '../events/reaction.js';
+import { findContradictions } from '../events/contradictions.js';
 import { evaluatePredicate, waitForPredicate, PredicateSchema } from '../events/predicate.js';
 import { matchNet, matchConsole, isConsoleEvent, eventMatchesFilters, netEmptyHint, consoleEmptyHint, reconcileNet, projectNetCall, projectConsoleLog, } from '../events/event-filters.js';
 import { applyEventBudget, costHint, withSizeCost, DEFAULT_QUERY_LIMIT, } from '../session/output-budget.js';
 import { healthEnvelope, bufferEnvelope } from '../session/session-health.js';
-import { isPresenceOnlyAssertion, PRESENCE_ONLY_ADVICE } from './assert-grade.js';
-import { buildCoverageStatement, blindSpotsFromState } from '../honesty/blind-spots.js';
+import { assertsDerivedIpcStatus, DERIVED_IPC_STATUS_ADVICE, isPresenceOnlyAssertion, PRESENCE_ONLY_ADVICE, } from './assert-grade.js';
+import { assertVerdict } from './assert-verdict.js';
+import { bodiesNotCaptured } from '../honesty/uncaptured-bodies.js';
 import { withControl } from '../session/control-envelope.js';
 import { asString, asNumber } from './tools-helpers.js';
 import { sessionIdShape, commandOrThrow } from './tool-kit.js';
@@ -39,18 +41,39 @@ const bufferOutputShape = {
 function lastActSourceOnFailure(session, pass) {
     if (pass)
         return {};
-    const source = session.lastActSource();
+    const source = session.lastAct.source();
     return source === undefined ? {} : { source };
 }
+/**
+ * Drop `sessionId` from an event in a response the caller scoped to ONE session.
+ *
+ * The caller passed that id in the request, so echoing it on every event is the request quoted back
+ * once per row. Measured on a live app it was 25% of a four-event `reticle_observe` payload, and it
+ * grows linearly with the timeline — a fifty-event window spends ~2.5KB restating a fact the caller
+ * supplied. The id stays on the wire between SDK and bridge, where events from different sessions
+ * really do interleave; it is only redundant at this boundary.
+ */
+function withoutConstantSessionId(event) {
+    if (typeof event !== 'object' || event === null)
+        return event;
+    const { sessionId: _sessionId, ...rest } = event;
+    return rest;
+}
 export const OBSERVE_TOOLS = [
     {
         name: ReticleTool.OBSERVE,
+        example: { since: 0 },
         description: 'Return the timeline of everything the app did in a window (DOM/network/route/console/animation/signal), with a summary. Use after an action. Pass `max_events` to cap the timeline to the most recent N (older events are dropped and counted in cost.droppedOldest). Every result carries a `cost:{events,bytes}` hint so you can self-budget your next call.',
         inputSchema: {
             window_ms: z
                 .number()
+                .positive()
+                // A non-positive window silently produced a FUTURE cursor, so the tool returned zero events
+                // and echoed the nonsense value back — indistinguishable from a genuinely quiet page. An
+                // agent that fumbles this argument gets a clean "nothing happened" instead of being told the
+                // question was malformed, which is the exact confusion this layer exists to refuse.
                 .optional()
-                .describe('Time window to look back. Default: 2000ms. Ignored when `since` is provided.'),
+                .describe('Time window to look back, in ms (must be > 0). Default: 2000. Ignored when `since` is provided.'),
             since: z
                 .number()
                 .optional()
@@ -71,6 +94,7 @@ export const OBSERVE_TOOLS = [
                 'type (e.g. "net.request"). Omit to return all types.'),
             max_events: z
                 .number()
+                .nonnegative()
                 .optional()
                 .describe('Cap the timeline to the most recent N events. Older events are counted in cost.droppedOldest.'),
             ...sessionIdShape,
@@ -91,6 +115,17 @@ export const OBSERVE_TOOLS = [
                 animations: z.number(),
                 signals: z.number(),
             }),
+            // Cross-channel disagreement in this window. Omitted when there is none, so a clean action
+            // costs zero tokens and a contradiction is impossible to scroll past.
+            contradictions: z
+                .array(z.object({
+                kind: z.string(),
+                claim: z.string(),
+                counter: z.string(),
+                detail: z.string(),
+            }))
+                .optional()
+                .describe('Channels that DISAGREE about this action — e.g. the UI advanced while its request failed. Each is a false green: the screen looks right and the app is wrong.'),
             cost: z.object({
                 events: z.number(),
                 bytes: z.number(),
@@ -121,9 +156,22 @@ export const OBSERVE_TOOLS = [
             // Output budget: cap to the most recent N (no silent caps — droppedOldest is surfaced in cost).
             const { events: budgeted, droppedOldest } = applyEventBudget(filtered, asNumber(args['max_events']));
             const report = buildReactionReport(budgeted, windowMs);
+            // Run over the FILTERED-but-unbudgeted window: a contradiction must not vanish because the
+            // timeline was capped for tokens. Detection is cheap; the events are already in hand.
+            // The act that opened this window is not in `args` — observe is a separate call — so its action
+            // and in-target mutation count are read back off the session. Without them the "this click did
+            // nothing" check is unreachable on the ordinary act-then-observe flow, which is most of them.
+            // Only when the act actually falls inside the window being judged — judging a click with a
+            // window that starts after it would accuse a control of doing nothing during a period it was
+            // never asked about.
+            const actCursor = session.lastAct.cursor();
+            const judgingTheAct = actCursor !== undefined && actCursor >= since;
+            const contradictions = findContradictions(filtered, judgingTheAct ? session.lastAct.effect() : {});
             // carry session health — a throttled tab means the observed timeline may be incomplete.
             return withControl(session, {
                 ...report,
+                events: report.events.map(withoutConstantSessionId),
+                ...(contradictions.length > 0 ? { contradictions } : {}),
                 cost: costHint(report, budgeted.length, droppedOldest),
                 ...healthEnvelope(session),
                 ...bufferEnvelope(session),
@@ -132,9 +180,10 @@ export const OBSERVE_TOOLS = [
     },
     {
         name: ReticleTool.WAIT_FOR,
+        example: { predicate: { kind: 'state', path: 'todos.length', equals: 3 } },
         description: 'Block until a predicate is satisfied (or already true in the recent buffer), else time out. Returns matching evidence or a near-miss diagnosis. By default it only counts events since your last act, so a signal buffered BEFORE the action can never fake a pass; pass `since` (an observe/act cursor) to widen or narrow that window explicitly.',
         inputSchema: {
-            predicate: PredicateSchema.describe('Predicate to wait for: { signal }, { net }, { element }, { kind: "state", store, path, equals } (assert a registered store\'s value directly — the source of truth no DOM read can reach; equals takes a literal or { $gte | $contains | $length } pattern), { kind: "settled", quietMs } (deterministic network + DOM idle — prefer this over a fixed sleep), or a combination via allOf/anyOf.'),
+            predicate: PredicateSchema.describe('Predicate to wait for: { signal }, { net }, { element }, { kind: "net", ok: false } (assert on the OUTCOME — the honest field for IPC, which has no status code), { kind: "state", store, path, equals } (assert a registered store\'s value directly — the source of truth no DOM read can reach; equals takes a literal or { $gte | $contains | $length } pattern), { kind: "settled", quietMs } (deterministic network + DOM idle — prefer this over a fixed sleep), or a combination via allOf/anyOf.'),
             timeout_ms: z.number().optional().describe('Maximum wait in milliseconds. Default: 4000.'),
             since: z
                 .number()
@@ -171,7 +220,7 @@ export const OBSERVE_TOOLS = [
             const session = deps.sessions.resolve(asString(args['sessionId']));
             const predicate = PredicateSchema.parse(args['predicate']);
             // Honesty: explicit since wins; else default to the last act's cursor; else the whole buffer.
-            const since = asNumber(args['since']) ?? session.lastActCursor() ?? 0;
+            const since = asNumber(args['since']) ?? session.lastAct.cursor() ?? 0;
             const verdict = await waitForPredicate(session, predicate, asNumber(args['timeout_ms']) ?? DEFAULT_ASSERT_TIMEOUT_MS, since);
             // match reticle_assert — wrap with control + session health (throttle matters most while blocking)
             // and the buffer envelope, so a verdict reached over an evicted window says so.
@@ -185,6 +234,7 @@ export const OBSERVE_TOOLS = [
     },
     {
         name: ReticleTool.ASSERT,
+        example: { predicate: { kind: 'signal', name: 'todos:loaded' } },
         description: 'Evaluate a predicate (optionally waiting up to timeout_ms). Returns { pass, evidence, failureReason? }. The end of every verify loop. Prefer a { signal } or { net } consequence over { element }/{ text } presence — a passing presence-only assertion returns `advice` because a wrong/healed element can fake it. By default it only counts events since your last act, so a stale buffered signal can never fake a pass; pass `since` (an observe/act cursor) to set the window explicitly.',
         inputSchema: {
             predicate: PredicateSchema.describe('Predicate to evaluate: { signal }, { net }, { element } or a combination.'),
@@ -240,40 +290,27 @@ export const OBSERVE_TOOLS = [
             const predicate = PredicateSchema.parse(args['predicate']);
             const timeout = asNumber(args['timeout_ms']) ?? 0;
             // Honesty: explicit since wins; else default to the last act's cursor; else the whole buffer.
-            const since = asNumber(args['since']) ?? session.lastActCursor() ?? 0;
+            const since = asNumber(args['since']) ?? session.lastAct.cursor() ?? 0;
             const verdict = timeout > 0
                 ? await waitForPredicate(session, predicate, timeout, since)
                 : await evaluatePredicate(session, predicate, since);
             // A GREEN presence-only assertion is the dangerous case (a wrong element can fake it) — nudge
             // toward a consequence. Never on a failing verdict (moot) or when a signal/net is asserted.
-            const advice = verdict.pass && isPresenceOnlyAssertion(predicate) ? { advice: PRESENCE_ONLY_ADVICE } : {};
-            // A verdict reached over an evicted buffer can be a FALSE NEGATIVE: "no console error" may
-            // simply mean the error aged out. reticle_console has always disclosed this on the same window;
-            // the verdict path — the one an agent actually gates on — did not. Omitted when nothing dropped.
-            // Coverage, on the verdict an agent actually gates on.
-            //
-            // Scope caveat, stated because it is a real limitation and not a bug: blind spots are tracked
-            // per SESSION, not per assertion window. So a cross-origin iframe seen once marks every later
-            // verdict in that session partial, including ones about a region it cannot affect. That errs
-            // toward over-warning, which is the correct direction for an honesty signal — the failure this
-            // guards against is a green that implies coverage it never had, and the opposite error (a
-            // needless caveat) costs the agent a sentence.
-            //
-            // act_and_wait has always disclosed this; plain assert did not — so a GREEN assert on a page
-            // with a cross-origin iframe or a closed shadow root read as "the page is correct" when the
-            // honest claim is "nothing failed in the part I could see". That is the false-green shape this
-            // project exists to prevent, sitting on the most-used verdict path. Omitted entirely when
-            // coverage is full, so an intact page pays nothing and the field's PRESENCE is the warning.
-            const spots = blindSpotsFromState(session.blindSpots());
-            const statement = buildCoverageStatement(spots);
-            const coverage = statement.coverage === 'partial'
-                ? {
-                    coverage: statement.note ?? 'partial',
-                    coverage_spots: statement.spots.map((sp) => ({ kind: sp.kind, count: sp.count })),
-                }
-                : {};
+            // Two nudges, both only on a GREEN verdict (a failing one is moot): a presence-only assertion
+            // a wrong element can fake, and an assertion pinned to a status Reticle derived rather than one
+            // a server sent. Neither blocks — the assertion still passes; they steer the next one.
+            const advice = !verdict.pass
+                ? {}
+                : isPresenceOnlyAssertion(predicate)
+                    ? { advice: PRESENCE_ONLY_ADVICE }
+                    : assertsDerivedIpcStatus(predicate)
+                        ? { advice: DERIVED_IPC_STATUS_ADVICE }
+                        : {};
+            const { decision, contradictions, coverage } = await assertVerdict(session, predicate, verdict.pass, since);
             return withControl(session, {
+                ...decision,
                 ...verdict,
+                ...(contradictions.length > 0 ? { contradictions } : {}),
                 ...advice,
                 ...coverage,
                 ...lastActSourceOnFailure(session, verdict.pass),
@@ -284,7 +321,8 @@ export const OBSERVE_TOOLS = [
     },
     {
         name: ReticleTool.NETWORK,
-        description: 'Filtered list of network calls. Fast path for "did POST /x return 200?". A zero-match filter returns a `hint` { totalInWindow, present[] } of the calls that DID fire, so a miss is diagnosable.',
+        example: { urlContains: '/api/todos', method: 'POST' },
+        description: 'Filtered list of network calls. Fast path for "did POST /x return 200?". A zero-match filter returns a `hint` { totalInWindow, present[] } of the calls that DID fire, so a miss is diagnosable. Desktop IPC (`ipc://`) has no status code — the 200/500 there is derived, so filter on `ok` for those.',
         inputSchema: {
             since: z
                 .number()
@@ -304,8 +342,13 @@ export const OBSERVE_TOOLS = [
                 .describe('HTTP method filter: GET | POST | PUT | DELETE | PATCH etc.'),
             urlContains: z.string().optional().describe('Substring that the request URL must contain.'),
             status: z.number().optional().describe('HTTP status code filter (e.g. 200, 404, 500).'),
+            ok: z
+                .boolean()
+                .optional()
+                .describe('Outcome filter: false keeps only calls that FAILED, true only those that succeeded. The filter to use for desktop IPC (`ipc://`), whose status code is derived. A still-pending call matches neither.'),
             limit: z
                 .number()
+                .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.'),
             ...sessionIdShape,
@@ -318,6 +361,10 @@ export const OBSERVE_TOOLS = [
                 .describe('Total matches before `limit` — present only when capped.'),
             droppedOldest: z.number().optional().describe('How many older matches `limit` dropped.'),
             hint: z.object({ totalInWindow: z.number(), present: z.array(z.string()) }).optional(),
+            bodiesNotCaptured: z
+                .string()
+                .optional()
+                .describe('Present when a POST/PUT/PATCH was returned and body capture is OFF — an absent body means unseen, not empty. Carries the one-line fix.'),
             cost: z.object({ bytes: z.number(), tokens: z.number() }).optional(),
             ...bufferOutputShape,
         },
@@ -327,6 +374,7 @@ export const OBSERVE_TOOLS = [
             const method = asString(args['method']);
             const urlContains = asString(args['urlContains']);
             const status = asNumber(args['status']);
+            const ok = typeof args['ok'] === 'boolean' ? args['ok'] : undefined;
             const limit = asNumber(args['limit']);
             const buffer = bufferEnvelope(session);
             // Completed calls + unresolved in-flight requests (a hung request shows as pending).
@@ -335,7 +383,7 @@ export const OBSERVE_TOOLS = [
                 until: asNumber(args['until']),
                 actionId: asString(args['actionId']),
             }));
-            const matched = allNet.filter((e) => matchNet(e, method, urlContains, status));
+            const matched = allNet.filter((e) => matchNet(e, method, urlContains, status, ok));
             // zero-match filter returns what DID fire, not a bare [].
             if (matched.length === 0 && allNet.length > 0) {
                 return withSizeCost({ calls: matched, hint: netEmptyHint(allNet), ...buffer });
@@ -343,13 +391,17 @@ 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);
-            return withSizeCost(droppedOldest > 0
-                ? { calls, total: matched.length, droppedOldest, ...buffer }
-                : { calls, ...buffer });
+            return withSizeCost({
+                calls,
+                ...(droppedOldest > 0 ? { total: matched.length, droppedOldest } : {}),
+                ...bodiesNotCaptured(calls),
+                ...buffer,
+            });
         },
     },
     {
         name: ReticleTool.CONSOLE,
+        example: { level: 'error' },
         description: 'Console/error log. Fast path for "were there any errors during this flow?". When a level filter matches nothing, returns a `hint` { totalInWindow, byLevel } so 0 errors is distinguishable from a silent page.',
         inputSchema: {
             level: z
@@ -370,6 +422,7 @@ export const OBSERVE_TOOLS = [
                 .describe('Keep only log entries attributed to this action — "what did action N log".'),
             limit: z
                 .number()
+                .nonnegative()
                 .optional()
                 .describe('Keep only the most recent N matching entries (older are dropped and counted in droppedOldest) — cuts tokens when a page spams the console. Defaults to 200 when omitted; pass a higher number for more, or scope with since/until.'),
             ...sessionIdShape,
@@ -419,4 +472,3 @@ export const OBSERVE_TOOLS = [
         handler: (deps, args) => commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.ANIMATIONS, {}),
     },
 ];
-//# sourceMappingURL=observe-tools.js.map

package/dist/tools/profiles.d.ts

@@ -6,7 +6,7 @@ import type { ToolDef } from './tools.js';
  *
  * MEASURED surface sizes (assert them with profile-reachability.test.ts rather than trusting prose —
  * every count previously written here was wrong, and the token figures below derive from those counts):
- *   core 14 · standard 32 · hybrid 14 · full 41 · dynamic 2
+ *   core 15 · standard 32 · hybrid 15 · full 43 · dynamic 2
  * core and hybrid are both 14 because a trimmed profile now also advertises the two meta-tools, which
  * is what keeps an un-advertised tool reachable through reticle_run.
  *
@@ -35,4 +35,3 @@ export declare const TOOL_PROFILE_ENV = "RETICLE_TOOL_PROFILE";
 export declare const CORE_TOOL_NAMES: ReadonlySet<string>;
 export declare function resolveToolProfile(explicit?: string): ToolProfile;
 export declare function filterTools(tools: ToolDef[], profile: ToolProfile): ToolDef[];
-//# sourceMappingURL=profiles.d.ts.map

package/dist/tools/profiles.js

@@ -6,7 +6,7 @@ import { ReticleTool } from './tool-names.js';
  *
  * MEASURED surface sizes (assert them with profile-reachability.test.ts rather than trusting prose —
  * every count previously written here was wrong, and the token figures below derive from those counts):
- *   core 14 · standard 32 · hybrid 14 · full 41 · dynamic 2
+ *   core 15 · standard 32 · hybrid 15 · full 43 · dynamic 2
  * core and hybrid are both 14 because a trimmed profile now also advertises the two meta-tools, which
  * is what keeps an un-advertised tool reachable through reticle_run.
  *
@@ -32,22 +32,37 @@ export const TOOL_PROFILE = {
 };
 export const TOOL_PROFILE_ENV = 'RETICLE_TOOL_PROFILE';
 // The set an agent needs to verify a change end-to-end. Tool DEFINITIONS are re-sent every turn, so a
-// smaller surface compounds. Measured per-turn surface cost (bench/first-drive, o200k proxy):
-// core 6,479 tok · standard 13,951 · full 20,441 — the hybrid default is far cheaper per turn than
-// advertising everything. STALE: these were measured against a 12/40/56-tool surface that no longer
-// exists (it is now 14/32/41 after the merge and the escape-hatch change), so treat the ratio as
-// directional and the absolute numbers as needing a re-measure before they are quoted anywhere.
+// smaller surface compounds.
+//
+// MEASURED per-turn `tools/list` cost — the bytes an MCP client re-sends EVERY turn — taken off the
+// real wire (spawn `mcp`, read tools/list, measure the serialized result), not estimated:
+//
+//   dynamic     2 tools    1,531 B   ~383 tok/turn
+//   core       15 tools   14,104 B  ~3,526 tok/turn
+//   hybrid     15 tools   14,104 B  ~3,526 tok/turn
+//   standard   32 tools   26,769 B  ~6,692 tok/turn
+//   full       43 tools  105,061 B ~26,265 tok/turn
+//
+// These REPLACE the previous figures (core 6,479 / standard 13,951 / full 20,441), which the comment
+// itself flagged as stale. Two of the three moved in opposite directions, which is why re-measuring
+// mattered: the lean profiles got much CHEAPER because they now drop the advertised outputSchema,
+// while `full` got much more EXPENSIVE because it still carries it — the gap between lean and full is
+// 7.4x, not the ~3x the old numbers implied.
+//
+// Where the remaining cost sits, on the hybrid default: inputSchema is 76% of the payload (parameter
+// descriptions are half of that), tool descriptions are 12%, and outputSchema is already ~0. So the
+// next real saving is in parameter prose, not in dropping more tools.
 //
 // There is a floor, though: an 8-tool cut (dropping act/navigate/wait_for/sessions) was MEASURED to
-// regress real-agent accuracy 5/5 → 3/5, because the model loses scaffolding and wanders on harder
-// flows. These 12 are the lean sweet spot. Direct network/console stay (far more discoverable than
-// observe-with-filters → fewer turns, better verdicts).
+// regress real-agent accuracy 5/5 -> 3/5, because the model loses scaffolding and wanders on harder
+// flows. Direct network/console stay (far more discoverable than observe-with-filters -> fewer turns,
+// better verdicts).
 //
-// Evidence status: the original 5/5 figure came from a single gpt-4o run and is STALE as a
-// justification. Current-model evidence is indirect but real — the cost-delta run
-// (bench/fix-loop/COST-DELTA.md) drove this hybrid default on a current model and fixed 4/4 cells with
-// ~25% FEWER tool calls than the baseline. A formal core-vs-hybrid A/B on a current model is
-// still UNRUN; do not quote the 5/5 number as if it were current. See bench/agent-loop-and-replay.md.
+// Evidence status: the 5/5 figure came from a single gpt-4o run and is STALE as a justification.
+// Current-model evidence is indirect but real — the cost-delta run (bench/fix-loop/COST-DELTA.md)
+// drove this hybrid default on a current model and fixed 4/4 cells with ~25% FEWER tool calls than
+// the baseline. A formal core-vs-hybrid A/B on a current model is still UNRUN; do not quote the 5/5
+// number as if it were current. See bench/agent-loop-and-replay.md.
 export const CORE_TOOL_NAMES = new Set([
     ReticleTool.SESSIONS,
     ReticleTool.NAVIGATE,
@@ -61,11 +76,24 @@ export const CORE_TOOL_NAMES = new Set([
     ReticleTool.WAIT_FOR,
     ReticleTool.ASSERT,
     ReticleTool.STATE,
+    // INSPECT is what turns a finding into an EDIT: it maps a DOM node to `src/App.tsx:104`. Finding a
+    // bug is half the job; knowing which file to open is the half that makes the agent useful, and it
+    // is the one capability here with no substitute in any other verification tool. It sat in
+    // `standard`, so under the default profile an agent had to already know it existed and reach it
+    // through reticle_run — which, observed over a full 43-tool drive, means it never gets called.
+    // The measured floor that justifies a lean core was about CUTTING to 8 (accuracy 5/5 → 3/5), not
+    // about holding at 12; one tool of schema tax to close the find→fix loop is the right trade.
+    ReticleTool.INSPECT,
+    // FEEDBACK is in every profile for the same reason INSPECT is: a tool an agent has to already know
+    // about, and reach through reticle_run, is a tool that never gets called. That is fatal here in a way
+    // it is not elsewhere — an unadvertised feedback channel collects nothing, which is indistinguishable
+    // from not having built one. It is also the cheapest tool on the surface to carry (three params) and
+    // the only one whose whole purpose is telling us which of the other fifteen are failing.
+    ReticleTool.FEEDBACK,
 ]);
 const STANDARD_TOOL_NAMES = new Set([
     ...CORE_TOOL_NAMES,
     ReticleTool.ACT_SEQUENCE,
-    ReticleTool.INSPECT,
     ReticleTool.NETWORK,
     ReticleTool.CONSOLE,
     ReticleTool.ANIMATIONS,
@@ -109,4 +137,3 @@ export function filterTools(tools, profile) {
         return tools.filter((t) => STANDARD_TOOL_NAMES.has(t.name));
     return tools;
 }
-//# sourceMappingURL=profiles.js.map

package/dist/tools/query-paginate.d.ts

@@ -19,4 +19,3 @@
  * number that is silently wrong. `count` survives because it is a scalar. Trust it over the array.
  */
 export declare function paginateQueryResult(result: unknown, limit: number | undefined, countOnly: boolean): unknown;
-//# sourceMappingURL=query-paginate.d.ts.map

package/dist/tools/query-paginate.js

@@ -45,4 +45,3 @@ export function paginateQueryResult(result, limit, countOnly) {
         return { ...record, total, truncated: true };
     return result;
 }
-//# sourceMappingURL=query-paginate.js.map

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

@@ -1,3 +1,2 @@
 import { type ToolDef } from './tool-kit.js';
 export declare const READ_TOOLS: ToolDef[];
-//# sourceMappingURL=read-tools.d.ts.map