@reticlehq/server 2.11.0 → 2.12.0

package/dist/mcp/attach-memory.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Two durable bits about the CLIENT side of the install: has an MCP client ever started Reticle's
+ * MCP server on this port, and has one ever asked it for the tool list.
+ *
+ * Some hosts register the server, start it, and then never send `tools/list` until the client is
+ * restarted. The agent has no Reticle tools, the user has no message, and from our side that install
+ * is byte-identical to one somebody wired and abandoned: daemon idle, no sessions, nothing to say.
+ * `status` could report "registered" and "connected"; it could not report the state in between,
+ * which is the one with an answer ("restart your client").
+ *
+ * Both bits record something that HAPPENED — the proxy ran, a `tools/list` arrived — never an
+ * inference from a config file. A config entry proves somebody wrote a line of JSON; it does not
+ * prove a client ever read it, which is precisely the thing in question here.
+ *
+ * Deliberately the same shape as `connection-memory.ts`: one small JSON file per port under the
+ * daemon's state home, best-effort in both directions. It is a HINT, so every failure degrades to
+ * "we do not know" rather than throwing — a diagnostic that can crash the process it is diagnosing
+ * is worse than no diagnostic at all.
+ *
+ * KNOWN LIMIT, and why the messages below say so out loud: the record is per PORT, not per client.
+ * Two clients on one machine share it, so a healthy one masks a broken one, and the record itself
+ * only begins on the version that introduced it — a long-working install reads as never attached
+ * until its client next starts the server. Both limits are stated in the text the user reads,
+ * because an honest "here is what I can see, here is what to check" beats a confident wrong no.
+ */
+/** What the client side of this install has been observed doing on this port. */
+export declare const AttachState: {
+    /** No client has started Reticle's MCP server here, as far as this record goes. */
+    readonly NEVER_ATTACHED: "never-attached";
+    /** A client started it and never asked for the tool list — the state that needs a restart. */
+    readonly NEVER_ENUMERATED: "never-enumerated";
+    /** Started and enumerated. Nothing to say. */
+    readonly ENUMERATED: "enumerated";
+};
+export type AttachState = (typeof AttachState)[keyof typeof AttachState];
+/** Record that an MCP client started the proxy on this port. */
+export declare function rememberProxyStarted(stateDir: string, port: number): void;
+/**
+ * Record that a client asked for the tool list on this port.
+ *
+ * Enumeration implies attachment — a `tools/list` cannot arrive at a server nobody started — so this
+ * sets both bits, and a record written by an older proxy that only ever set one is still read
+ * correctly.
+ */
+export declare function rememberEnumerated(stateDir: string, port: number): void;
+/** Which of the three client-side states this port is in. */
+export declare function attachState(stateDir: string, port: number): AttachState;
+/**
+ * The sentence to print for a state, or `undefined` when there is nothing to fix.
+ *
+ * The healthy case has to stay silent: advice printed beside a working client reads as though
+ * something is still wrong, which is its own kind of lie.
+ */
+export declare function describeAttachState(state: AttachState): string | undefined;
+/** What `reticle status` reports about the client side of the install. */
+export interface AttachStatusFields {
+    mcpClient: AttachState;
+    mcpClientAction?: string;
+}
+/**
+ * The client-side fields for one `status` run.
+ *
+ * The state is reported on EVERY run, healthy included — "the client has read the tools" is the
+ * fact that was missing, and reporting it only when broken leaves the reader unable to tell a
+ * healthy client from a version too old to look. The advice rides along only when there is any.
+ */
+export declare function attachStatusFields(stateDir: string, port: number): AttachStatusFields;

package/dist/mcp/attach-memory.js

@@ -0,0 +1,142 @@
+/**
+ * Two durable bits about the CLIENT side of the install: has an MCP client ever started Reticle's
+ * MCP server on this port, and has one ever asked it for the tool list.
+ *
+ * Some hosts register the server, start it, and then never send `tools/list` until the client is
+ * restarted. The agent has no Reticle tools, the user has no message, and from our side that install
+ * is byte-identical to one somebody wired and abandoned: daemon idle, no sessions, nothing to say.
+ * `status` could report "registered" and "connected"; it could not report the state in between,
+ * which is the one with an answer ("restart your client").
+ *
+ * Both bits record something that HAPPENED — the proxy ran, a `tools/list` arrived — never an
+ * inference from a config file. A config entry proves somebody wrote a line of JSON; it does not
+ * prove a client ever read it, which is precisely the thing in question here.
+ *
+ * Deliberately the same shape as `connection-memory.ts`: one small JSON file per port under the
+ * daemon's state home, best-effort in both directions. It is a HINT, so every failure degrades to
+ * "we do not know" rather than throwing — a diagnostic that can crash the process it is diagnosing
+ * is worse than no diagnostic at all.
+ *
+ * KNOWN LIMIT, and why the messages below say so out loud: the record is per PORT, not per client.
+ * Two clients on one machine share it, so a healthy one masks a broken one, and the record itself
+ * only begins on the version that introduced it — a long-working install reads as never attached
+ * until its client next starts the server. Both limits are stated in the text the user reads,
+ * because an honest "here is what I can see, here is what to check" beats a confident wrong no.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** What the client side of this install has been observed doing on this port. */
+export const AttachState = {
+    /** No client has started Reticle's MCP server here, as far as this record goes. */
+    NEVER_ATTACHED: 'never-attached',
+    /** A client started it and never asked for the tool list — the state that needs a restart. */
+    NEVER_ENUMERATED: 'never-enumerated',
+    /** Started and enumerated. Nothing to say. */
+    ENUMERATED: 'enumerated',
+};
+/**
+ * What to do about a client that started Reticle and never listed its tools.
+ *
+ * Names the cause AND the action, like the rest of the doctor/status vocabulary, and names its own
+ * blind spot: this record cannot see WHICH client asked, so it must not tell somebody running two
+ * of them that the one in front of them is the broken one.
+ */
+const NEVER_ENUMERATED_ACTION = 'an MCP client started Reticle on this port and never asked for the tool list, so the tools are ' +
+    'here and your client has not read them — restart your MCP client, which is what makes it list ' +
+    'them again. This record is per port, not per client, so with more than one client registered ' +
+    'the one that never listed may not be the one you are looking at.';
+/**
+ * What to do when nothing has ever attached.
+ *
+ * The hedge is not padding. This record begins the first time a client starts the server on a
+ * version that keeps it, so an install that has worked for months reads as never attached until its
+ * client next starts Reticle — and telling that user their server is unregistered would send them
+ * to re-run `init` over a working setup.
+ */
+const NEVER_ATTACHED_ACTION = 'no MCP client has started Reticle on this port, so either the server is not registered with your ' +
+    'client or nothing has attached since this record began — register it with `npx ' +
+    '@reticlehq/server init`, then restart your MCP client and run status again.';
+const EMPTY = { attached: false, enumerated: false };
+function memoryPath(stateDir, port) {
+    return join(stateDir, `attach-${String(port)}.json`);
+}
+/** The record for a port. Empty on absent, unreadable, or malformed state. */
+function read(stateDir, port) {
+    try {
+        const parsed = JSON.parse(readFileSync(memoryPath(stateDir, port), 'utf8'));
+        if ('object' !== typeof parsed || null === parsed)
+            return EMPTY;
+        const record = parsed;
+        return {
+            attached: true === record.attached,
+            enumerated: true === record.enumerated,
+        };
+    }
+    catch {
+        return EMPTY;
+    }
+}
+/** Write the record back, best-effort. A hint must never be the reason a proxy fails to serve. */
+function write(stateDir, port, record) {
+    try {
+        mkdirSync(stateDir, { recursive: true });
+        writeFileSync(memoryPath(stateDir, port), JSON.stringify(record), 'utf8');
+    }
+    catch {
+        // An unwritable state home is already reported elsewhere; it must not break the client path.
+    }
+}
+/** Record that an MCP client started the proxy on this port. */
+export function rememberProxyStarted(stateDir, port) {
+    const known = read(stateDir, port);
+    if (known.attached)
+        return;
+    write(stateDir, port, { ...known, attached: true });
+}
+/**
+ * Record that a client asked for the tool list on this port.
+ *
+ * Enumeration implies attachment — a `tools/list` cannot arrive at a server nobody started — so this
+ * sets both bits, and a record written by an older proxy that only ever set one is still read
+ * correctly.
+ */
+export function rememberEnumerated(stateDir, port) {
+    const known = read(stateDir, port);
+    if (known.enumerated)
+        return;
+    write(stateDir, port, { attached: true, enumerated: true });
+}
+/** Which of the three client-side states this port is in. */
+export function attachState(stateDir, port) {
+    const known = read(stateDir, port);
+    if (known.enumerated)
+        return AttachState.ENUMERATED;
+    return known.attached ? AttachState.NEVER_ENUMERATED : AttachState.NEVER_ATTACHED;
+}
+/**
+ * The sentence to print for a state, or `undefined` when there is nothing to fix.
+ *
+ * The healthy case has to stay silent: advice printed beside a working client reads as though
+ * something is still wrong, which is its own kind of lie.
+ */
+export function describeAttachState(state) {
+    if (state === AttachState.NEVER_ENUMERATED)
+        return NEVER_ENUMERATED_ACTION;
+    if (state === AttachState.NEVER_ATTACHED)
+        return NEVER_ATTACHED_ACTION;
+    return undefined;
+}
+/**
+ * The client-side fields for one `status` run.
+ *
+ * The state is reported on EVERY run, healthy included — "the client has read the tools" is the
+ * fact that was missing, and reporting it only when broken leaves the reader unable to tell a
+ * healthy client from a version too old to look. The advice rides along only when there is any.
+ */
+export function attachStatusFields(stateDir, port) {
+    const state = attachState(stateDir, port);
+    const action = describeAttachState(state);
+    // OMITTED rather than undefined: `exactOptionalPropertyTypes` is on, and an absent key is also
+    // what keeps the healthy line to one fact.
+    return { mcpClient: state, ...(action === undefined ? {} : { mcpClientAction: action }) };
+}

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

@@ -47,13 +47,6 @@ export declare class PendingRequests {
  * with the MCP server still perfectly alive. An agent cannot tell that apart from "still working".
  */
 export declare function streamLossReplies(pending: PendingRequests, reason: string, nextStep?: string): string[];
-/**
- * The one shape every "the transport ate your call" answer takes, whichever leg died.
- *
- * `nextStep` is appended when the caller knows one. Without it this reply describes a condition and
- * stops there, which is all a first-run user got out of their first ever tool call.
- */
-export declare function transportLossReply(id: unknown, reason: string, nextStep?: string): string;
 /**
  * How long a request may sit in the queue, unsent, before the proxy answers it itself.
  *

package/dist/mcp/mcp-proxy.js

@@ -1,6 +1,7 @@
 import * as http from 'node:http';
 import { localInitializeResponse, isHandshakeLine, drainLines, MAX_STDIN_LINE_BYTES, } from './proxy-handshake.js';
-import { ToolCatalogCache } from './tool-catalog-cache.js';
+import { isToolsListRequest, ToolCatalogCache } from './tool-catalog-cache.js';
+import { rememberEnumerated, rememberProxyStarted } from './attach-memory.js';
 import { toolsChangedNotification } from './proxy-handshake.js';
 import { LOOPBACK_HOST, MCP_SSE_PATH, MCP_SHUTDOWN_EVENT, ReticleEnv, CONTRACT_FINGERPRINT, } from '@reticlehq/core';
 import { SseFrameParser } from './sse-frame-parser.js';
@@ -141,7 +142,7 @@ const TRANSPORT_LOSS_CODE = -32001;
  * `nextStep` is appended when the caller knows one. Without it this reply describes a condition and
  * stops there, which is all a first-run user got out of their first ever tool call.
  */
-export function transportLossReply(id, reason, nextStep) {
+function transportLossReply(id, reason, nextStep) {
     return JSON.stringify({
         jsonrpc: '2.0',
         id,
@@ -347,6 +348,11 @@ export function startMcpProxy(port,
  */
 ensureDaemon) {
     return new Promise((_resolve, reject) => {
+        // A client just started us, which is the only honest evidence that Reticle is registered with
+        // one at all: a config entry proves somebody wrote JSON, not that a client ever read it. Paired
+        // with the `tools/list` record below, this is what lets `status` name the state in between
+        // "never registered" and "connected" — see attach-memory.ts.
+        rememberProxyStarted(reticleStateHome(), port);
         // Declared before the SSE handler that fills it: the handler is a closure created below but
         // invoked on the first daemon frame, and a `const` referenced before its declaration executes is
         // a runtime throw, not a type error.
@@ -767,6 +773,12 @@ ensureDaemon) {
                     continue;
                 replay.observeOutbound(trimmed);
                 pending.observeOutbound(trimmed);
+                // The ARRIVAL of the request, not the delivery of an answer: "this client asked for the tool
+                // list" is the fact `status` reports on, and a request that arrived and then failed is a
+                // different problem with its own diagnosis. Recording the answer instead would let a host
+                // that never asks look identical to one that asked and was refused.
+                if (isToolsListRequest(trimmed))
+                    rememberEnumerated(reticleStateHome(), port);
                 const action = onClientRequest(postUrl !== null, dormant);
                 if (action === OnRequest.SEND && postUrl !== null) {
                     forward(postUrl, trimmed);

package/dist/mcp/mcp.d.ts

@@ -3,6 +3,8 @@ import { z } from 'zod';
 import { type ToolDeps } from '../tools/tools.js';
 import type { ToolDef } from '../tools/tools.js';
 import { type ToolSurface } from '../tools/tool-surface.js';
+/** The JSON-RPC method the SDK registers its tool dispatcher under. */
+export declare const CALL_TOOL_METHOD = "tools/call";
 /**
  * Merge the runtime-spliced envelope (health/lease/age/control) into a session-bound tool's declared
  * outputSchema so structuredContent validation keeps those fields instead of dropping them. The tool's

package/dist/mcp/mcp.js

@@ -1,7 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
-import { PredicateSchema } from '../events/predicate.js';
+import { isPredicateParam } from '../events/predicate-eval.js';
 import { isToonable, resultToToon, MCP_SERVER_NAME } from '@reticlehq/core';
 import { TOOLS } from '../tools/tools.js';
 import { filterTools, describeToolSurface, TOOL_SURFACE, } from '../tools/tool-surface.js';
@@ -15,7 +15,19 @@ import { resultIsError } from './mcp-is-error.js';
 import { buildServerInstructions } from './server-instructions.js';
 import { unadvertisedToolHelp } from '../tools/unadvertised-help.js';
 /** The JSON-RPC method the SDK registers its tool dispatcher under. */
-const CALL_TOOL_METHOD = 'tools/call';
+export const CALL_TOOL_METHOD = 'tools/call';
+/**
+ * What we say when an SDK internal these patches ride on is no longer there.
+ *
+ * LOG rather than THROW, deliberately. Both patches improve an ERROR MESSAGE; neither is load
+ * bearing for a single tool call, and a throw here runs at server construction, so a renamed
+ * internal in a minor SDK bump would take the whole MCP server down for every user rather than
+ * degrade one message. That trade is backwards. The place a shape change must fail is the gate —
+ * `sdk-private-shape.test.ts` asserts both shapes and reddens CI on the bump — and this line is the
+ * backstop for the one case the gate cannot see: a user whose installed SDK is not the one CI
+ * resolved. The old behaviour, a bare `return`, gave neither.
+ */
+const SDK_SHAPE_MISSING = 'sdk_internal_missing';
 import { log } from '../log.js';
 import { SERVER_VERSION } from '../version/server-version.js';
 import { setMcpClientNameHook } from '../telemetry/feedback-context.js';
@@ -73,23 +85,6 @@ export function firstSentence(description) {
  * Across the three tools that take a predicate that is 72% of the entire advertised input schema — a
  * cost re-sent on every request, forever, to describe a grammar most calls use one variant of.
  */
-/**
- * Is this parameter ACTUALLY the predicate union?
- *
- * This used to be a name check — `new Set(['predicate', 'until'])` — and `until` is overloaded on
- * this surface: the act/assert family means a predicate by it, while reticle_observe / _network /
- * _console mean a NUMBER, an upper cursor bound. So all three had their numeric parameter advertised
- * to the agent as `Predicate object: { kind, ...fields }`, typed as a record, under the DEFAULT
- * profile. An agent believing the schema passes an object, `asNumber` yields undefined, the bound is
- * silently dropped and the tool answers over the wrong window — a wrong answer wearing the shape of
- * an answer.
- *
- * Keying on the schema cannot make that mistake: a parameter is compacted because it IS a predicate.
- */
-function isPredicateParam(schema) {
-    const inner = schema instanceof z.ZodOptional ? schema.unwrap() : schema;
-    return inner === PredicateSchema || inner === PredicateSchema.optional();
-}
 /**
  * What a lean profile advertises in place of the full predicate union.
  *
@@ -246,7 +241,12 @@ export function advertisedConfig(tool, advertised, profile) {
     // `verify` is lean for the same reason `default` is, and more so: it exists to make a verdict
     // cheap, and it was serving FULL descriptions plus outputSchema because the check named only the
     // default. That put 8,207 bytes on the wire for three tools.
-    const lean = profile === TOOL_SURFACE.DEFAULT || profile === TOOL_SURFACE.VERIFY;
+    // `lean` here is the ADJECTIVE (terse descriptions, no output schemas), which every trimmed surface
+    // wants — including TOOL_SURFACE.LEAN, the profile that borrows the word. A trimmed surface serving
+    // full prose plus output schemas is the exact defect that put 8,207 bytes on `verify`'s three tools.
+    const lean = profile === TOOL_SURFACE.DEFAULT ||
+        profile === TOOL_SURFACE.VERIFY ||
+        profile === TOOL_SURFACE.LEAN;
     const terse = lean && !isMetaTool;
     // The first advertised tool carrying a predicate spells the grammar out; the rest point at it.
     const anchor = advertised.find((t) => Object.values(t.inputSchema).some((schema) => isPredicateParam(schema)))?.name;
@@ -270,8 +270,10 @@ function unknownKeys(args, allowed) {
 export function installFriendlyArgErrors(server, examples, allowedKeys = new Map()) {
     const target = server;
     const original = target.validateToolInput;
-    if (typeof original !== 'function')
+    if (typeof original !== 'function') {
+        log(SDK_SHAPE_MISSING, { internal: 'validateToolInput', lost: 'friendly argument errors' });
         return;
+    }
     target.validateToolInput = async (tool, args, toolName) => {
         // An UNKNOWN key is the failure zod cannot catch, because object schemas are non-strict: the key
         // is silently dropped and the tool answers as if it had not been asked. Measured live —
@@ -281,8 +283,14 @@ export function installFriendlyArgErrors(server, examples, allowedKeys = new Map
         const unknown = unknownKeys(args, allowedKeys.get(toolName));
         if (unknown.length > 0) {
             const example = examples.get(toolName);
+            // What the tool DOES declare, in the same breath as what it does not. Naming only the bad key
+            // leaves the caller guessing again, and the next guess costs another round trip — which is the
+            // whole shape of the failure being fixed here. The list is already in hand, and for a tool
+            // with no example (the meta-tools) it is the only thing standing between a typo and a retry.
+            const declared = [...(allowedKeys.get(toolName) ?? [])].join(', ');
             throw new McpError(ErrorCode.InvalidParams, `Unknown ${1 === unknown.length ? 'parameter' : 'parameters'} for ${toolName}: ${unknown.join(', ')}. ` +
                 `They were NOT applied — a result computed without them would look like an answer. ` +
+                (0 === declared.length ? '' : `${toolName} declares: ${declared}. `) +
                 (example === undefined
                     ? `Call reticle_tools { names: ["${toolName}"] } for its parameters.`
                     : `A valid call looks like: ${toolName} ${example}`));
@@ -347,8 +355,13 @@ function installUnadvertisedToolHelp(server, advertised, known) {
     const inner = server.server;
     const handlers = inner._requestHandlers;
     const original = handlers?.get(CALL_TOOL_METHOD);
-    if (handlers === undefined || original === undefined)
+    if (handlers === undefined || original === undefined) {
+        log(SDK_SHAPE_MISSING, {
+            internal: handlers === undefined ? '_requestHandlers' : CALL_TOOL_METHOD,
+            lost: 'unadvertised-tool help',
+        });
         return;
+    }
     handlers.set(CALL_TOOL_METHOD, async (request, extra) => {
         const name = toolNameOf(request);
         const help = name === undefined ? undefined : unadvertisedToolHelp(name, advertised, known);
@@ -439,7 +452,16 @@ tools = TOOLS) {
         .map((tool) => [tool.name, JSON.stringify(tool.example)])), 
     // Every tool in the table, not just the advertised ones: reticle_run dispatches to the full
     // table, so an unadvertised tool reached through the hatch must be just as strict.
-    new Map(tools.map((tool) => [tool.name, new Set(Object.keys(tool.inputSchema))])));
+    //
+    // ...and the advertised list on top of it, because the two META-tools are not in the table — they
+    // are composed onto the surface — so they had no entry, and no entry means no declared keys means
+    // every key allowed. `reticle_tools` took a misnamed argument, dropped it, and answered with the
+    // whole catalogue: a well-formed answer to a question nobody asked, on the one tool whose entire
+    // job is telling an agent what the surface is.
+    new Map([...tools, ...advertised].map((tool) => [
+        tool.name,
+        new Set(Object.keys(tool.inputSchema)),
+    ])));
     for (const tool of advertised) {
         // Output schemas are now the largest slice of the per-request tax (55.6% of the hybrid payload
         // after the predicate fix) and we are the only one of the three MCP servers that sends them.

package/dist/mcp/server-instructions.js

@@ -18,11 +18,31 @@ import { SHARED_PARAM_GUIDANCE } from './shared-params.js';
  * So the lead is state-dependent. A project that has never had an app connect is told the one thing
  * it needs; a project that has is not nagged about a step it already took. The verdict discipline
  * and the feedback ask are constant, because they matter in both states.
+ *
+ * The stopping rule is here for a measured reason. On a HEALTHY app in the competitor benchmark,
+ * this agent spent 22 turns and roughly 3.5x the cheapest competitor's tokens confirming that
+ * nothing was wrong — and it was not payload, which was the smallest of its five runs. It was
+ * turns: three navigations, four queries, a console read, a network read and an assert, on a page
+ * whose first verdict had already come back "yes" over a clean capture. Nothing anywhere told it
+ * when it was finished. Every other instruction here pushes toward MORE checking, which is right
+ * when something is broken and is the whole bill when nothing is.
+ *
+ * The diagnose-from-source rule has the same provenance and a bigger number behind it. Measured on
+ * a fix-and-verify benchmark, split at the call that writes the fix: this agent spent 14 and 18
+ * calls BEFORE its first edit where chrome-devtools-mcp spent 8 and 9 — and the sequences say why.
+ * It drove the app to understand it (snapshot, act, wait_for, snapshot, act, act_and_wait) and only
+ * then opened a file, while the competitor read six files and then looked once. Per-turn cost was
+ * IDENTICAL on the hardest cell (22,575 against 22,466), so the whole gap was turns, and most of
+ * those turns were spent asking a browser a question that only source can answer.
  */
 /** The tools, and the rule that only two of them decide anything. Constant across both states. */
-const VERDICT_DISCIPLINE = `Reticle verifies a running web app from the inside: look (reticle_snapshot / reticle_query), act and prove in one hop (reticle_act_and_wait), observe (reticle_state / reticle_network / reticle_console), assert (reticle_assert). Verify a user-facing change against the real app before you call it done, and never weaken a check to make it pass.
+const VERDICT_DISCIPLINE = `Reticle verifies a running web app from the inside: go (reticle_navigate), look (reticle_snapshot / reticle_query), act and prove in one hop (reticle_act_and_wait), observe (reticle_observe / reticle_state / reticle_network / reticle_console), assert (reticle_assert). Verify a user-facing change against the real app before you call it done, and never weaken a check to make it pass.
+
+Only reticle_act_and_wait and reticle_assert produce a verdict. reticle_act and everything else move or read the app and prove nothing, so a drive that ends without one of those two has no result however many tools it used. Prefer reticle_act_and_wait({ ref, action, until }) — it names the expected consequence BEFORE the action, which is the difference between a check and a rationalisation. Only verified:"yes" is a pass — "unknown" means Reticle could not tell what happened, "no-fault" means nothing was declared to prove. Report either as not proved.
 
-Only reticle_act_and_wait and reticle_assert produce a verdict. reticle_act and everything else move or read the app and prove nothing, so a drive that ends without one of those two has no result however many tools it used. Prefer reticle_act_and_wait({ ref, action, until }) — it names the expected consequence BEFORE the action, which is the difference between a check and a rationalisation. Only verified:"yes" is a pass — "unknown" means Reticle could not tell what happened, "no-fault" means nothing was declared to prove. Report either as not proved.`;
+A "yes" over a clean capture IS the answer — re-reading the page after one finds the same state. When every consequence you set out to check has one, stop.
+
+DIAGNOSING a bug? Read the source first — Reticle proves what the app DOES, not why. Drive to CONFIRM a fix, not to find one.`;
 /**
  * The first move, for a project no app has ever connected to.
  *
@@ -35,6 +55,28 @@ Only reticle_act_and_wait and reticle_assert produce a verdict. reticle_act and
 const FIRST_MOVE = `FIRST: no app has ever connected to Reticle in this project, so nothing here can be verified yet. Having these tools is not the same as being set up — the tools reach a daemon, and the daemon has nothing to look at until the app itself is instrumented.
 
 Fix that before anything else: run \`npx @reticlehq/server init\` in the project, then RESTART the dev server (a plugin added to a config the running server already read is not in the bundle), then load the app in a browser. Confirm with reticle_sessions — a session listed there is the proof, and until one appears no other tool can tell you anything about this app.`;
+/**
+ * When to reach for the tools that are advertised but never explained, and how to reach the two
+ * that are explained but not advertised. Both halves of the same defect.
+ *
+ * An advertised tool arrives as a name and one line of description. That is enough to USE and not
+ * enough to CHOOSE, and `reticle_observe` is the case that proves it costs something: the
+ * measurement recorded on TOOL_SURFACE.VERIFY is that dropping the observation tools TRIPLED false
+ * alarms, because the model stops observing and reaches for the verdict without the evidence. So
+ * observe gets a reason, not a listing.
+ *
+ * The other direction: `reticle_context` and `reticle_intent` sit on the EXTENDED surface, so they
+ * are not in the list an agent is handed. Naming them without their call shape sent an agent at a
+ * tool it could not call, which is worse than silence — it teaches distrust of everything else
+ * here. They are now written the way the skill writes them, as the `reticle_run` call that works.
+ *
+ * Only in the connected state, and that is not a budget trick: an agent whose app has never
+ * connected has nothing to observe, no run to carry forward and nothing to declare an intent
+ * against. Its one instruction is the first move, and adding a second would compete with it.
+ */
+const REACH_FOR = `reticle_observe is the evidence channel: everything the page did since a cursor, in one read. Take it BEFORE you call a build broken — measured, stripping the observation tools TRIPLED false alarms, because an agent that stops observing reaches for the verdict without the evidence. reticle_wait_for settles a page that is changing without you; reticle_inspect maps an element to its source file:line, which turns a finding into an edit; reticle_session {action:"yield"} hands the tab back to the human.
+
+Everything else is one hop: reticle_tools lists it, reticle_run calls it. Two to know early: reticle_run({ tool: "reticle_context", args: {} }) returns what this run already established, after a compaction or handover, and reticle_run({ tool: "reticle_intent", args: { action: "declare", ... } }) declares what a change was MEANT to do, so the verdict has something to check against other than itself.`;
 /** The feedback ask. Constant: an agent that cannot get set up is the report we most need. */
 const FEEDBACK_ASK = `Feedback is first-class here, not a courtesy. Reticle is built FOR agents, so your experience is the only signal that decides what gets built or fixed — and it disappears when your context does. Send it with \`reticle_feedback\` the moment you notice, then carry on with your task:
 - Reticle broke, lied, or could not see something you needed (\`bug\` / \`gap\` / \`ambiguity\`).
@@ -50,7 +92,7 @@ Nothing is too minor, and a report costs one call. If the tools are unreachable
  */
 export function buildServerInstructions(state) {
     const base = state.previouslyConnected
-        ? `${VERDICT_DISCIPLINE}\n\n${FEEDBACK_ASK}`
+        ? `${VERDICT_DISCIPLINE}\n\n${REACH_FOR}\n\n${FEEDBACK_ASK}`
         : `${FIRST_MOVE}\n\n${VERDICT_DISCIPLINE}\n\n${FEEDBACK_ASK}`;
     return `${base}\n\n${SHARED_PARAM_GUIDANCE}`;
 }

package/dist/mcp/tool-catalog-cache.d.ts

@@ -15,6 +15,14 @@
  * its own confidently-wrong answer, and a proxy that has never seen one has nothing honest to serve —
  * so it says nothing rather than inventing a list the agent would then call into.
  */
+/**
+ * Is this client line a request for the tool list?
+ *
+ * Lives here because this module already owns the method name and the tolerant parse. The caller is
+ * the proxy's stdin reader, which records the arrival as the one observable fact behind `reticle
+ * status`'s "registered, never enumerated" state — see attach-memory.ts.
+ */
+export declare function isToolsListRequest(line: string): boolean;
 export declare class ToolCatalogCache {
     #private;
     /** Watch a line coming BACK from the daemon; remember it if it is a tool catalog. */

package/dist/mcp/tool-catalog-cache.js

@@ -25,6 +25,16 @@ function parse(line) {
         return null;
     }
 }
+/**
+ * Is this client line a request for the tool list?
+ *
+ * Lives here because this module already owns the method name and the tolerant parse. The caller is
+ * the proxy's stdin reader, which records the arrival as the one observable fact behind `reticle
+ * status`'s "registered, never enumerated" state — see attach-memory.ts.
+ */
+export function isToolsListRequest(line) {
+    return parse(line)?.method === LIST_METHOD;
+}
 export class ToolCatalogCache {
     #tools;
     /** Watch a line coming BACK from the daemon; remember it if it is a tool catalog. */

package/dist/oracles/flow-instrument-gaps.d.ts

@@ -1,5 +1,5 @@
 import { type FlowStep } from '@reticlehq/core';
-import { type InstrumentationGap } from './self-instrument.js';
+import type { LocatedGap } from './self-instrument.js';
 /**
  * Bridge domain gaps → LOCATED instrumentation gaps. A flow that asserts no consequence should emit one —
  * and the flow's own step anchors carry the source file:line the babel/next plugin stamped, so we know
@@ -12,7 +12,7 @@ export declare function lastSource(steps: readonly FlowStep[]): {
     line: number;
 } | undefined;
 /**
- * Turn unasserted flows into missing-signal gaps at each flow's source location. Flows with no stamped
- * source are skipped (no location to propose). The suggested signal name is `<flow>:done`.
+ * Turn unasserted flows into no-signal-on-mutation gaps at each flow's source location. Flows with
+ * no stamped source are skipped (no location to propose). The suggested signal name is `<flow>:done`.
  */
-export declare function instrumentationGapsForFlows(unassertedFlows: readonly string[], flowStepsByName: ReadonlyMap<string, readonly FlowStep[]>): InstrumentationGap[];
+export declare function instrumentationGapsForFlows(unassertedFlows: readonly string[], flowStepsByName: ReadonlyMap<string, readonly FlowStep[]>): LocatedGap[];

package/dist/oracles/flow-instrument-gaps.js

@@ -1,5 +1,4 @@
-import { AnchorKind } from '@reticlehq/core';
-import { InstrumentationGapKind } from './self-instrument.js';
+import { AnchorKind, InstrumentationGapKind } from '@reticlehq/core';
 /**
  * Bridge domain gaps → LOCATED instrumentation gaps. A flow that asserts no consequence should emit one —
  * and the flow's own step anchors carry the source file:line the babel/next plugin stamped, so we know
@@ -22,8 +21,8 @@ export function lastSource(steps) {
     return found;
 }
 /**
- * Turn unasserted flows into missing-signal gaps at each flow's source location. Flows with no stamped
- * source are skipped (no location to propose). The suggested signal name is `<flow>:done`.
+ * Turn unasserted flows into no-signal-on-mutation gaps at each flow's source location. Flows with
+ * no stamped source are skipped (no location to propose). The suggested signal name is `<flow>:done`.
  */
 export function instrumentationGapsForFlows(unassertedFlows, flowStepsByName) {
     const gaps = [];
@@ -33,7 +32,7 @@ export function instrumentationGapsForFlows(unassertedFlows, flowStepsByName) {
         if (source === undefined)
             continue;
         gaps.push({
-            kind: InstrumentationGapKind.MISSING_SIGNAL,
+            kind: InstrumentationGapKind.NO_SIGNAL_ON_MUTATION,
             file: source.file,
             line: source.line,
             name: `${name}:done`,

package/dist/oracles/self-instrument.d.ts

@@ -4,15 +4,15 @@
  * apply instrumentation proposals as concrete diffs, so the AGENT closes the gap and the app's
  * observability compounds run over run — instead of a human being a prerequisite. Deterministic mapping
  * from a located gap to the code to insert; pure and testable. Result-enrichment wiring is a later step.
+ *
+ * Kinds come from `@reticlehq/core`. A second enum here is how `reticle_domain` used to say
+ * `missing-signal` while honesty said `no-signal-on-mutation` for the same absence.
  */
-export declare const InstrumentationGapKind: {
-    readonly MISSING_SIGNAL: "missing-signal";
-    readonly UNREGISTERED_STORE: "unregistered-store";
-    readonly MISSING_TESTID: "missing-testid";
-};
-export type InstrumentationGapKind = (typeof InstrumentationGapKind)[keyof typeof InstrumentationGapKind];
-export interface InstrumentationGap {
-    kind: InstrumentationGapKind;
+import { InstrumentationGapKind } from '@reticlehq/core';
+/** The three core kinds a located proposal can close. Other kinds are verdict-side, not insert-side. */
+export type LocatableGapKind = typeof InstrumentationGapKind.NO_SIGNAL_ON_MUTATION | typeof InstrumentationGapKind.NO_STORE_REGISTERED | typeof InstrumentationGapKind.MISSING_TESTID;
+export interface LocatedGap {
+    kind: LocatableGapKind;
     file: string;
     line: number;
     /** The name to instrument with — a signal name, store name, or testid. */
@@ -28,5 +28,5 @@ interface InstrumentationProposal {
     rationale: string;
 }
 /** Turn located capability gaps into ready-to-apply instrumentation proposals. Deterministic. */
-export declare function proposeInstrumentation(gaps: readonly InstrumentationGap[]): InstrumentationProposal[];
+export declare function proposeInstrumentation(gaps: readonly LocatedGap[]): InstrumentationProposal[];
 export {};