@reticlehq/server 2.10.0 → 2.12.0

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 {};

package/dist/oracles/self-instrument.js

@@ -4,33 +4,39 @@
  * 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 const InstrumentationGapKind = {
-    MISSING_SIGNAL: 'missing-signal',
-    UNREGISTERED_STORE: 'unregistered-store',
-    MISSING_TESTID: 'missing-testid',
-};
+import { InstrumentationGapKind } from '@reticlehq/core';
 /** PascalCase a store name for a `useX.getState` hint (cart → Cart). */
 function pascal(name) {
     return 0 === name.length ? name : name[0]?.toUpperCase() + name.slice(1);
 }
 function insertFor(gap) {
     switch (gap.kind) {
-        case InstrumentationGapKind.MISSING_SIGNAL:
+        case InstrumentationGapKind.NO_SIGNAL_ON_MUTATION:
             return `reticle.signal('${gap.name}');`;
-        case InstrumentationGapKind.UNREGISTERED_STORE:
+        case InstrumentationGapKind.NO_STORE_REGISTERED:
             return `registerStore('${gap.name}', () => use${pascal(gap.name)}.getState());`;
         case InstrumentationGapKind.MISSING_TESTID:
             return `data-testid="${gap.name}"`;
     }
 }
 function rationaleFor(gap) {
-    const base = gap.kind === InstrumentationGapKind.MISSING_SIGNAL
-        ? `emit a consequence signal so verification proves the outcome, not just presence`
-        : gap.kind === InstrumentationGapKind.UNREGISTERED_STORE
-            ? `register the store so state assertions can read the source of truth`
-            : `add a stable testid so the anchor survives refactors`;
-    return gap.context === undefined ? base : `${base} — ${gap.context}`;
+    let base;
+    switch (gap.kind) {
+        case InstrumentationGapKind.NO_SIGNAL_ON_MUTATION:
+            base = `emit a consequence signal so verification proves the outcome, not just presence`;
+            break;
+        case InstrumentationGapKind.NO_STORE_REGISTERED:
+            base = `register the store so state assertions can read the source of truth`;
+            break;
+        case InstrumentationGapKind.MISSING_TESTID:
+            base = `add a stable testid so the anchor survives refactors`;
+            break;
+    }
+    return undefined === gap.context ? base : `${base} — ${gap.context}`;
 }
 /** Turn located capability gaps into ready-to-apply instrumentation proposals. Deterministic. */
 export function proposeInstrumentation(gaps) {

package/dist/pool/browser-pool.d.ts

@@ -9,7 +9,6 @@
  * The browser is injected via a `Launcher` so all lifecycle logic is testable without real Chromium;
  * the thin Playwright adapter that satisfies these interfaces lives separately.
  */
-/** The minimal page surface the pool drives. Real Playwright `Page` satisfies this. */
 export interface PooledPage {
     goto(url: string, opts?: {
         timeoutMs?: number;
@@ -17,6 +16,12 @@ export interface PooledPage {
     close(): Promise<void>;
     /** Fires when THIS page's renderer crashes — lets the pool reclaim just this lease, not the fleet. */
     onCrash(handler: () => void): void;
+    /**
+     * Fires for each console message the page logs. OPTIONAL: a fake that does not implement it makes
+     * the pool record nothing, which is the correct degradation — an absent dial address must read as
+     * "the page said nothing", never as "the page dialled correctly".
+     */
+    onConsole?(handler: (text: string) => void): void;
 }
 /** An isolated browsing context (cookies/storage). Real Playwright `BrowserContext` satisfies this. */
 export interface PooledContext {
@@ -114,6 +119,12 @@ export declare class BrowserPool {
         signal?: AbortSignal;
         sessionId?: string;
     }): Promise<Lease>;
+    /**
+     * The websocket address this lease's page reported it could not reach, if it reported one.
+     *
+     * Undefined means the page said nothing — never that it dialled the right place.
+     */
+    dialFailureUrl(sessionId: string): string | undefined;
     /** Close every context and the browser. Pending waiters are rejected (the pool is terminal now). */
     shutdown(): Promise<void>;
 }

package/dist/pool/browser-pool.js

@@ -9,6 +9,8 @@
  * The browser is injected via a `Launcher` so all lifecycle logic is testable without real Chromium;
  * the thin Playwright adapter that satisfies these interfaces lives separately.
  */
+/** The minimal page surface the pool drives. Real Playwright `Page` satisfies this. */
+import { unreachableUrlIn } from '@reticlehq/core';
 /** Default lease time-to-live: a lease untouched for this long is presumed orphaned and reclaimed. */
 export const DEFAULT_LEASE_TTL_MS = 5 * 60_000;
 /** Default cap on how long a lease's initial navigation may take before it fails (frees the slot). */
@@ -147,6 +149,7 @@ export class BrowserPool {
         await this.#waitForSlot(opts.signal);
         const sessionId = opts.sessionId ?? this.#genId();
         let context;
+        let pending;
         try {
             const browser = await this.#ensureBrowser();
             context = await browser.newContext();
@@ -156,6 +159,19 @@ export class BrowserPool {
             page.onCrash(() => {
                 void this.#release(sessionId);
             });
+            // Listen BEFORE goto: the SDK's connect attempt races the navigation's own resolution, and a
+            // listener attached afterwards misses the first failures — the only ones logged before the
+            // retry backoff stretches out.
+            page.onConsole?.((text) => {
+                const dialled = unreachableUrlIn(text);
+                if (dialled === undefined)
+                    return;
+                const active = this.#active.get(sessionId);
+                if (active !== undefined)
+                    active.dialFailureUrl = dialled;
+                else
+                    pending = dialled; // logged during goto, before the lease is registered below
+            });
             await page.goto(url, { timeoutMs: this.#navTimeout });
             // The browser can crash WHILE goto is resolving; #onCrash then clears #active and zeroes
             // #occupied. Registering the lease now would resurrect a dead entry against a crashed browser with
@@ -163,7 +179,13 @@ export class BrowserPool {
             // no longer the live browser, bail — the catch below closes the context and returns the slot.
             if (this.#browser !== browser)
                 throw new Error('browser crashed during navigation');
-            this.#active.set(sessionId, { context, page, url, touchedAt: this.#now() });
+            this.#active.set(sessionId, {
+                context,
+                page,
+                url,
+                touchedAt: this.#now(),
+                ...(pending === undefined ? {} : { dialFailureUrl: pending }),
+            });
             return {
                 sessionId,
                 url,
@@ -179,6 +201,14 @@ export class BrowserPool {
             throw err;
         }
     }
+    /**
+     * The websocket address this lease's page reported it could not reach, if it reported one.
+     *
+     * Undefined means the page said nothing — never that it dialled the right place.
+     */
+    dialFailureUrl(sessionId) {
+        return this.#active.get(sessionId)?.dialFailureUrl;
+    }
     /** Close every context and the browser. Pending waiters are rejected (the pool is terminal now). */
     async shutdown() {
         this.#closed = true; // set first so any woken waiter rejects instead of relaunching a browser

package/dist/pool/playwright-launcher.js

@@ -6,6 +6,7 @@
  * Headless by default — the pool exists for fault-tolerant headless multi-agent testing.
  */
 import { BrowserLaunchKind } from '@reticlehq/core';
+import { chromiumLaunchOptions } from '../chromium-launch-options.js';
 import { getSessionMetrics } from '../telemetry/session-metrics.js';
 import { classifyConnectFailure } from '../telemetry/connect-failure.js';
 import { chromiumInstallCommand, bundledPlaywrightVersion } from '../cli/chromium-hint.js';
@@ -40,6 +41,7 @@ function wrapBrowser(browser) {
                         goto: (url, opts) => page.goto(url, gotoOptions(opts?.timeoutMs)),
                         close: () => page.close(),
                         onCrash: (handler) => page.on('crash', handler),
+                        onConsole: (handler) => page.on('console', (msg) => handler(msg.text())),
                     };
                 },
                 close: () => context.close(),
@@ -72,7 +74,7 @@ export function playwrightLauncher(opts = {}) {
         // number that actually costs memory and the one that explains a slow machine.
         const settle = getSessionMetrics().recordConnectAttempt(BrowserLaunchKind.POOLED);
         try {
-            const browser = wrapBrowser(await chromium.launch({ headless }));
+            const browser = wrapBrowser(await chromium.launch(chromiumLaunchOptions(headless)));
             settle();
             return browser;
         }

package/dist/project/artifact-root.d.ts

@@ -0,0 +1,83 @@
+import { type ProjectCandidate, type ProjectRegistry } from '@reticlehq/core';
+import type { ConfigDiscovery } from '../cli/config-discovery.js';
+/**
+ * Which `.reticle/` a session's artifacts belong in.
+ *
+ * Everything Reticle persists — flows, the capability contract, baselines, capsules, the cross-run
+ * project memory — used to resolve against the DAEMON's own `process.cwd()`. That is a statement
+ * about where the daemon was launched and it was being read as a statement about which project is
+ * being verified. Those are not the same thing and are usually not even the same tree: a user-scoped
+ * MCP registration is the common case, and the editor that spawns it starts it wherever it likes.
+ *
+ * Three field shapes, one defect: `cwd=/` gave `ENOENT: mkdir '/.reticle'`; a daemon started in
+ * project A wrote project B's flow into A's checkout and reported success without naming the path;
+ * and `verify_change` could only answer "unknown" because no flow could be persisted for it to match
+ * against.
+ *
+ * ## Two sources, one rule
+ *
+ * Candidates arrive from config discovery (which walks out from the daemon's own directory) and from
+ * the user-level project registry (which `init` writes, and which reaches checkouts discovery cannot
+ * see). This function takes the merged list and does not know or care which source an entry came
+ * from — a privileged source would be a second rule, and two rules for one question is how the
+ * answers start disagreeing.
+ *
+ * ## Why matching on projectId, and not a new wire field
+ *
+ * HELLO already stamps `projectId`, and `.reticle.json` already declares the same id sitting next to
+ * the code it configures. The join is therefore available today, for every SDK already in the field.
+ * Adding a `root` to HELLO would move the wire contract, strand every older SDK on the fallback, and
+ * buy nothing this does not already give.
+ *
+ * ## Why it can decline to answer
+ *
+ * Every non-matching branch returns the daemon root and SAYS which branch it was. A wrong root is
+ * worse than no root — it writes a caller's evidence into a tree they never drove — so the ambiguous
+ * case refuses rather than picks, exactly as `discoverProjectConfigs` refuses to pick one config.
+ * The reason travels with the answer so callers can report the surprise instead of hiding it.
+ */
+/** Why the root below is the root. Travels with the answer so a caller can say what happened. */
+export declare const ArtifactRootReason: {
+    /** Exactly one discovered config declares this session's project. The good case. */
+    readonly MATCHED_PROJECT: "matched-project";
+    /** The session declared no projectId — a pre-2.0 SDK. Nothing to match on. */
+    readonly NO_PROJECT_ID: "no-project-id";
+    /** The search ran and nothing it found declares this project. */
+    readonly NO_MATCH: "no-match";
+    /** Two or more checkouts declare this project. Refused rather than guessed. */
+    readonly AMBIGUOUS: "ambiguous";
+};
+export type ArtifactRootReason = (typeof ArtifactRootReason)[keyof typeof ArtifactRootReason];
+export interface ArtifactRootQuery {
+    /** The connected session's HELLO projectId, when it sent one. */
+    projectId: string | undefined;
+    /** Every project this machine knows about. Supplied, not gathered here — this stays pure. */
+    candidates: readonly ProjectCandidate[];
+    /** Where artifacts go when the project cannot be identified. Already a `.reticle` path. */
+    daemonRoot: string;
+}
+export interface ArtifactRoot {
+    /** Absolute path to the `.reticle` directory. Always present, on every branch. */
+    root: string;
+    reason: ArtifactRootReason;
+    /**
+     * The competing project directories, on `AMBIGUOUS` only. A caller that has to explain the refusal
+     * needs to name them; a caller that does not can ignore the field.
+     */
+    candidates?: string[];
+}
+/**
+ * Resolve the artifact root for one session.
+ *
+ * Pure: no IO, no cwd, no clock. The filesystem walk belongs to `discoverProjectConfigs` and is
+ * passed in, which is what makes every branch below testable without a fixture tree.
+ */
+export declare function resolveArtifactRoot(query: ArtifactRootQuery): ArtifactRoot;
+/**
+ * Everything this machine knows about where projects live, from both sources.
+ *
+ * Discovery first, deliberately: it read a `.reticle.json` that exists RIGHT NOW, while the registry
+ * is a cache of something `init` saw once. Order only decides which duplicate survives dedupe, and
+ * the one confirmed a moment ago is the better survivor.
+ */
+export declare function projectCandidatesFrom(discovery: ConfigDiscovery, registry: ProjectRegistry): ProjectCandidate[];