@reticlehq/server 2.12.0 → 2.13.0

package/dist/mcp/mcp-proxy.js

@@ -1,7 +1,7 @@
 import * as http from 'node:http';
-import { localInitializeResponse, isHandshakeLine, drainLines, MAX_STDIN_LINE_BYTES, } from './proxy-handshake.js';
-import { isToolsListRequest, ToolCatalogCache } from './tool-catalog-cache.js';
-import { rememberEnumerated, rememberProxyStarted } from './attach-memory.js';
+import { localInitializeResponse, degradedInstructions, isHandshakeLine, drainLines, MAX_STDIN_LINE_BYTES, } from './proxy-handshake.js';
+import { isToolCallRequest, isToolsListRequest, ToolCatalogCache } from './tool-catalog-cache.js';
+import { rememberEnumerated, rememberProxyStarted, rememberToolCalled } 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';
@@ -16,6 +16,7 @@ import { readProjectId } from '../cli/cli-port.js';
 import { PEER_VERSION_PARAM, PEER_CONTRACT_PARAM } from '../version/peer-announce.js';
 import { onStreamDrop, onClientRequest, onReconnectBudgetSpent, onQueueExpired, OnDrop, OnRequest, } from './proxy-lifecycle.js';
 import { describePresence, probePresence } from '../daemon/port-presence.js';
+import { flushProxySessionMetrics } from '../telemetry/proxy-telemetry.js';
 /**
  * The same `/status` probe `doctor`, `status` and `kill` ask with. Reused rather than re-written:
  * the whole defect this import closes was the proxy answering a DIFFERENT question from every other
@@ -28,11 +29,11 @@ import { fetchStatus as fetchDaemonStatus } from '../cli/cli-launch.js';
  */
 export { accountProxyLogWrite, proxyLog, proxyLogPath, PROXY_LOG_CHECK_BYTES, recoverOversizedProxyLog, setProxyLogPort, } from './proxy-log.js';
 import { proxyLog } from './proxy-log.js';
-import { log } from '../log.js';
 import { OutageReason, OutageStage, reportMcpOutage } from './mcp-outage.js';
-/** Reconnect backoff: linear, capped, so a briefly-restarting daemon is picked up fast. */
-const RECONNECT_BASE_MS = 250;
-const RECONNECT_CAP_MS = 5_000;
+import { postToSession } from './mcp-post-transport.js';
+import { reconnectDelayMs } from './proxy-backoff.js';
+export { reconnectDelayMs, RECONNECT_BASE_MS, RECONNECT_CAP_MS } from './proxy-backoff.js';
+export { MCP_PROXY_HTTP_AGENT_OPTIONS, postToSession, shouldRetryUnsentPost, } from './mcp-post-transport.js';
 /**
  * How many consecutive failed reconnects before the proxy stops RETRYING. It does not stop serving:
  * the budget ends the retry loop and the proxy goes dormant, where the handshake and `tools/list`
@@ -51,9 +52,6 @@ export const MAX_RECONNECT_ATTEMPTS = (() => {
     const raw = Number(process.env[ReticleEnv.RECONNECT_ATTEMPTS]);
     return Number.isInteger(raw) && raw > 0 ? raw : DEFAULT_MAX_RECONNECT_ATTEMPTS;
 })();
-export function reconnectDelayMs(attempt) {
-    return Math.min(RECONNECT_BASE_MS * attempt, RECONNECT_CAP_MS);
-}
 /** JSON-RPC id the proxy uses for its own replayed `initialize` — never one the client could send. */
 export const RECONNECT_INITIALIZE_ID = '__reticle_proxy_reinit';
 function parseJsonRpc(line) {
@@ -254,49 +252,6 @@ export class HandshakeReplay {
         return true;
     }
 }
-/**
- * POST one JSON-RPC line into the daemon's session. Resolves null on success, or a short reason
- * when the request never reached a server that will answer it.
- *
- * It used to resolve `void` in every case, logging the failure and moving on. That is the THIRD way
- * a call goes unanswered, and the only one neither `streamLossReplies` nor the queue timer can see:
- * the SSE stream is healthy (so nothing drops) and the request was forwarded (so nothing is queued),
- * but the POST leg is its own TCP connection and an ECONNRESET on it means the daemon never received
- * the call. Nobody was ever going to reply, and the caller waited for its own timeout.
- */
-function postToSession(url, body) {
-    return new Promise((resolve) => {
-        const parsed = new URL(url);
-        const bodyBuf = Buffer.from(body, 'utf8');
-        const options = {
-            host: parsed.hostname,
-            port: parsed.port !== '' ? parseInt(parsed.port, 10) : 80,
-            path: `${parsed.pathname}${parsed.search}`,
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                'Content-Length': bodyBuf.byteLength,
-            },
-        };
-        const req = http.request(options, (res) => {
-            const status = res.statusCode ?? 0;
-            const rejected = status < 200 || status >= 300;
-            if (rejected) {
-                // A non-2xx from the daemon MCP endpoint used to be swallowed, hanging the JSON-RPC call
-                // client-side with no diagnostic. It is a refusal: no response is coming over the stream.
-                log('reticle_mcp_proxy_post_non2xx', { status, path: options.path });
-            }
-            res.resume(); // drain so the socket is reused
-            resolve(rejected ? `daemon rejected the call with HTTP ${String(status)}` : null);
-        });
-        req.on('error', (err) => {
-            log('reticle_mcp_proxy_post_error', { error: err.message });
-            resolve(`post failed: ${err.message}`);
-        });
-        req.write(bodyBuf);
-        req.end();
-    });
-}
 /**
  * Turn an `endpoint` frame's data into a POST target, or null when there is nothing usable in it.
  *
@@ -439,6 +394,17 @@ ensureDaemon) {
         let daemonRetiring = false;
         /** Why the stream we are currently trying to replace went away — carried onto the recovery. */
         let lastDropReason = OutageReason.OTHER;
+        /**
+         * What the outage had already cost when the proxy went dormant.
+         *
+         * The wake path clears `attempts` before dialling, and it must: a wake is a fresh retry budget,
+         * and sharing the previous outage's spent budget would put the proxy dormant again on its first
+         * failure. But the recovery report is guarded on `attempts > 0`, so clearing it also erased the
+         * evidence that there was anything to recover FROM — and dormancy is the commonest outage class
+         * we have, which made every recovery of that class invisible. Carried across the wake so the
+         * budget resets and the accounting does not.
+         */
+        let attemptsBeforeDormant = 0;
         /**
          * When the proxy started, and how many times the first connect has been refused since.
          *
@@ -461,13 +427,20 @@ ensureDaemon) {
                 const msg = parseJsonRpc(line);
                 if (null === msg || msg.id === undefined || !pending.take(msg.id))
                     return;
+                if (failure.transport) {
+                    reportMcpOutage(OutageStage.FIRST, {
+                        reason: OutageReason.CONNECT_ERROR,
+                        attempts: failure.attempts,
+                        pendingLost: 1,
+                    });
+                }
                 proxyLog('reticle_mcp_proxy_post_unanswered', {
                     port,
                     method: String(msg.method),
-                    reason: failure,
+                    reason: failure.reason,
                     note: 'the stream is still up, so nothing else would ever have answered this call',
                 });
-                emit(transportLossReply(msg.id, failure));
+                emit(transportLossReply(msg.id, failure.reason));
             });
         };
         function onSseEvent(event, data, p) {
@@ -487,9 +460,11 @@ ensureDaemon) {
                 // off and never reaching the budget that puts the proxy dormant. Measured: 32 retries in 8s.
                 // Report the recovery BEFORE the counter is cleared: `attempts` is what coming back actually
                 // cost, and it is the only number that can falsify the drop event. See OutageStage.RECOVERED.
-                if (attempts > 0)
-                    reportMcpOutage(OutageStage.RECOVERED, { reason: lastDropReason, attempts });
+                const cost = attempts + attemptsBeforeDormant;
+                if (cost > 0)
+                    reportMcpOutage(OutageStage.RECOVERED, { reason: lastDropReason, attempts: cost });
                 attempts = 0;
+                attemptsBeforeDormant = 0;
                 // The new session's McpServer has never seen the client's initialize — replay it first, then
                 // flush whatever the client sent while we were reconnecting.
                 for (const line of replay.replayLines())
@@ -710,10 +685,10 @@ ensureDaemon) {
         const armLocalHandshake = (line) => {
             if (handshakeAnswered)
                 return;
-            // Ask the same question the daemon would, from the same durable memory, so the client gets
-            // the same answer it would have got had a daemon been up to give it.
-            const response = localInitializeResponse(line, proxyInstructions(port));
-            if (null === response)
+            // Only an `initialize` REQUEST is ours to answer. Asked with no instructions because the ones
+            // we will actually send name the reason the daemon failed, and the reason is not known until
+            // the deliver closure runs — see degradedInstructions.
+            if (null === localInitializeResponse(line, ''))
                 return;
             // Take the debt NOW, not when the timer fires.
             //
@@ -732,6 +707,13 @@ ensureDaemon) {
             deliverHandshakeLocally = (reason) => {
                 if (handshakeAnswered || postUrl !== null)
                     return;
+                // Built here, not at arm time, so the notice can name WHY no daemon answered. The client
+                // reads `instructions` exactly once, at initialize, and this response is the only one it
+                // will ever get — so a handshake that does not say it is unbacked never says it at all.
+                // See degradedInstructions for the field report this closes.
+                const response = localInitializeResponse(line, degradedInstructions(proxyInstructions(port), port, reason));
+                if (null === response)
+                    return;
                 handshakeAnswered = true;
                 deliverHandshakeLocally = undefined;
                 // The catalog we are about to serve is ours, not the daemon's, so it has to be corrected
@@ -779,6 +761,11 @@ ensureDaemon) {
                 // that never asks look identical to one that asked and was refused.
                 if (isToolsListRequest(trimmed))
                     rememberEnumerated(reticleStateHome(), port);
+                // The hop every other check misses. Recorded on the REQUEST rather than a reply, because
+                // the question is whether anything ever left the agent — a call that leaves and gets no
+                // answer is a different fault from one that was never made, and only this side sees it.
+                if (isToolCallRequest(trimmed))
+                    rememberToolCalled(reticleStateHome(), port);
                 const action = onClientRequest(postUrl !== null, dormant);
                 if (action === OnRequest.SEND && postUrl !== null) {
                     forward(postUrl, trimmed);
@@ -805,6 +792,8 @@ ensureDaemon) {
                 // flushed once the new session's `endpoint` frame arrives.
                 if (action === OnRequest.WAKE) {
                     dormant = false;
+                    // Budget reset, accounting preserved. See attemptsBeforeDormant.
+                    attemptsBeforeDormant += attempts;
                     attempts = 0;
                     void (ensureDaemon?.() ?? Promise.resolve())
                         .then(() => connect(false))
@@ -832,7 +821,8 @@ ensureDaemon) {
         process.stdin.on('end', () => {
             const quit = (code) => {
                 stopped = true;
-                process.exit(code);
+                // Await: fire-and-forget here is how daemon_stopped never arrived.
+                void flushProxySessionMetrics().finally(() => process.exit(code));
             };
             if (0 === pending.unanswered.length) {
                 quit(0);

package/dist/mcp/mcp.js

@@ -11,6 +11,7 @@ import { buildDynamicTools } from '../tools/dynamic-tools.js';
 import { runTool, SESSION_BOUND_TOOLS } from '../tools/invoke-tool.js';
 import { sessionEnvelopeShape } from '../tools/tool-kit.js';
 import { buildErrorPayload } from '../tools/error-recovery.js';
+import { takeVersionSkewOnto } from '../version/version-nudge.js';
 import { resultIsError } from './mcp-is-error.js';
 import { buildServerInstructions } from './server-instructions.js';
 import { unadvertisedToolHelp } from '../tools/unadvertised-help.js';
@@ -514,7 +515,12 @@ tools = TOOLS) {
                 // Every error the agent hits should answer "what next?", not just "what broke".
                 return {
                     isError: true,
-                    content: [{ type: 'text', text: JSON.stringify(buildErrorPayload(message)) }],
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(takeVersionSkewOnto(buildErrorPayload(message))),
+                        },
+                    ],
                 };
             }
         });

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

@@ -0,0 +1,11 @@
+/**
+ * Reconnect backoff, shared by the SSE stream and the POST leg.
+ *
+ * Its own module only because both halves need it and they must not import each other: the proxy
+ * owns the stream, the post transport owns the request, and a cycle between them to reach three
+ * lines of arithmetic would be the wrong price.
+ */
+/** Linear and capped, so a briefly-restarting daemon is picked up fast. */
+export declare const RECONNECT_BASE_MS = 250;
+export declare const RECONNECT_CAP_MS = 5000;
+export declare function reconnectDelayMs(attempt: number): number;

package/dist/mcp/proxy-backoff.js

@@ -0,0 +1,13 @@
+/**
+ * Reconnect backoff, shared by the SSE stream and the POST leg.
+ *
+ * Its own module only because both halves need it and they must not import each other: the proxy
+ * owns the stream, the post transport owns the request, and a cycle between them to reach three
+ * lines of arithmetic would be the wrong price.
+ */
+/** Linear and capped, so a briefly-restarting daemon is picked up fast. */
+export const RECONNECT_BASE_MS = 250;
+export const RECONNECT_CAP_MS = 5_000;
+export function reconnectDelayMs(attempt) {
+    return Math.min(RECONNECT_BASE_MS * attempt, RECONNECT_CAP_MS);
+}

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

@@ -1,3 +1,4 @@
+export declare function daemonPollDelayMs(attempt: number): number;
 /**
  * Returns true if something is already listening on the reticle port.
  * Uses a plain TCP probe so we don't create a side-effectful SSE session

package/dist/mcp/proxy-daemon-probe.js

@@ -11,9 +11,13 @@ const DAEMON_READY_TIMEOUT_MS = Number.isFinite(envDaemonReadyTimeoutMs) && envD
     ? envDaemonReadyTimeoutMs
     : DEFAULT_DAEMON_READY_TIMEOUT_MS;
 const DAEMON_POLL_INTERVAL_MS = 100;
+const DAEMON_POLL_MAX_INTERVAL_MS = 1_000;
 function delay(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+export function daemonPollDelayMs(attempt) {
+    return Math.min(DAEMON_POLL_INTERVAL_MS * attempt, DAEMON_POLL_MAX_INTERVAL_MS);
+}
 /**
  * Returns true if something is already listening on the reticle port.
  * Uses a plain TCP probe so we don't create a side-effectful SSE session
@@ -38,11 +42,13 @@ export function probeDaemon(port) {
 /** Poll until the daemon's HTTP port accepts connections or the deadline is reached. */
 export async function waitForDaemon(port) {
     const deadline = Date.now() + DAEMON_READY_TIMEOUT_MS;
+    let attempt = 0;
     while (Date.now() < deadline) {
         const reachable = await probeDaemon(port);
         if (reachable)
             return;
-        await delay(DAEMON_POLL_INTERVAL_MS);
+        attempt++;
+        await delay(daemonPollDelayMs(attempt));
     }
     throw new Error(`reticle daemon did not become ready on port ${port} within ${DAEMON_READY_TIMEOUT_MS}ms`);
 }

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

@@ -44,6 +44,29 @@ instructions?: string): string | null;
  * where it is honoured and costs one line where it is not.
  */
 export declare function toolsChangedNotification(catalogWasLocal: boolean): string | null;
+/**
+ * What a locally-answered handshake must say about itself.
+ *
+ * The proxy answering `initialize` is right — a hang gives the agent no tools AND no diagnosis — but
+ * the response it sent was INDISTINGUISHABLE from a daemon's. Same `serverInfo`, same capabilities,
+ * same `instructions`. So the client marked the server installed and enabled, the agent got a tool
+ * list that was cached at best and empty at worst, and nothing anywhere connected the two facts.
+ *
+ * Reported from the field, from two different agent hosts at once: the marketplace showed Reticle
+ * installed with the whole tool surface enabled, and the agent asked to verify a flow reported that
+ * RETICLE WAS NOT PRESENT ON THE MACHINE — while the daemon was running and a browser session was
+ * live. That conclusion is the reasonable reading of an empty surface with no explanation attached,
+ * and it is unrecoverable: the proxy's own recovery is "the next client request re-probes the port",
+ * and a client holding zero tools never makes another request.
+ *
+ * `instructions` is the channel because it is the only one that survives an empty catalog. It rides
+ * on the initialize result, which SUCCEEDED, and every host we target puts it in front of the model.
+ * A tool description cannot reach an agent that was handed no tools.
+ *
+ * The healthy block is kept underneath rather than replaced: an agent that IS about to get a working
+ * surface (the common case — the first call wakes a daemon) still needs to know how to drive it.
+ */
+export declare function degradedInstructions(healthy: string, port: number, reason: string): string;
 /**
  * The largest single JSON-RPC line the proxy will accumulate from a client.
  *

package/dist/mcp/proxy-handshake.js

@@ -103,6 +103,37 @@ export function toolsChangedNotification(catalogWasLocal) {
         return null;
     return JSON.stringify({ jsonrpc: '2.0', method: TOOLS_CHANGED_NOTIFICATION });
 }
+/**
+ * What a locally-answered handshake must say about itself.
+ *
+ * The proxy answering `initialize` is right — a hang gives the agent no tools AND no diagnosis — but
+ * the response it sent was INDISTINGUISHABLE from a daemon's. Same `serverInfo`, same capabilities,
+ * same `instructions`. So the client marked the server installed and enabled, the agent got a tool
+ * list that was cached at best and empty at worst, and nothing anywhere connected the two facts.
+ *
+ * Reported from the field, from two different agent hosts at once: the marketplace showed Reticle
+ * installed with the whole tool surface enabled, and the agent asked to verify a flow reported that
+ * RETICLE WAS NOT PRESENT ON THE MACHINE — while the daemon was running and a browser session was
+ * live. That conclusion is the reasonable reading of an empty surface with no explanation attached,
+ * and it is unrecoverable: the proxy's own recovery is "the next client request re-probes the port",
+ * and a client holding zero tools never makes another request.
+ *
+ * `instructions` is the channel because it is the only one that survives an empty catalog. It rides
+ * on the initialize result, which SUCCEEDED, and every host we target puts it in front of the model.
+ * A tool description cannot reach an agent that was handed no tools.
+ *
+ * The healthy block is kept underneath rather than replaced: an agent that IS about to get a working
+ * surface (the common case — the first call wakes a daemon) still needs to know how to drive it.
+ */
+export function degradedInstructions(healthy, port, reason) {
+    return `DEGRADED SURFACE — READ THIS BEFORE ANY reticle_* CALL: no Reticle daemon answered on port ${String(port)} (${reason}), so this handshake was completed by the Reticle MCP proxy itself, not by Reticle's daemon. Any tool list you were handed came from a cache or is empty — it is not evidence that anything is behind it.
+
+Reticle IS installed: this process is Reticle. Do NOT report it as missing, not present, or not installed — that is the wrong diagnosis and it is the one this state reliably produces. The right one is that the daemon is not reachable yet.
+
+Your next reticle_* call starts a daemon and then either works or fails with the specific reason. If you have NO reticle_* tools at all, say exactly that to the user and tell them to run \`reticle doctor\` in a terminal — it reports what is holding port ${String(port)} and whether a daemon can start at all.
+
+${healthy}`;
+}
 /**
  * The largest single JSON-RPC line the proxy will accumulate from a client.
  *

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

@@ -23,6 +23,14 @@
  * status`'s "registered, never enumerated" state — see attach-memory.ts.
  */
 export declare function isToolsListRequest(line: string): boolean;
+/**
+ * Is this line a client CALLING a tool?
+ *
+ * The one fact that separates a working agent link from a merely-registered one. Listing the tools
+ * proves a client read the catalogue; it proves nothing about whether a request can cross to the
+ * daemon, and the field reports those two states looking identical from every other angle.
+ */
+export declare function isToolCallRequest(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

@@ -35,6 +35,18 @@ function parse(line) {
 export function isToolsListRequest(line) {
     return parse(line)?.method === LIST_METHOD;
 }
+/** The JSON-RPC method a client sends to actually USE a tool, as opposed to listing them. */
+const CALL_METHOD = 'tools/call';
+/**
+ * Is this line a client CALLING a tool?
+ *
+ * The one fact that separates a working agent link from a merely-registered one. Listing the tools
+ * proves a client read the catalogue; it proves nothing about whether a request can cross to the
+ * daemon, and the field reports those two states looking identical from every other angle.
+ */
+export function isToolCallRequest(line) {
+    return parse(line)?.method === CALL_METHOD;
+}
 export class ToolCatalogCache {
     #tools;
     /** Watch a line coming BACK from the daemon; remember it if it is a tool catalog. */

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

@@ -0,0 +1,2 @@
+import type { ToolDef } from '../tools/tools.js';
+export declare const MEMORY_TOOLS: ToolDef[];

package/dist/memory/memory-tools.js

@@ -0,0 +1,82 @@
+/**
+ * `reticle_memory` — ask the project what it already knows.
+ *
+ * Shared memory reached three callers before this one: the sync writes it, flow replay consults it
+ * automatically, and `reticle memory` prints it at a terminal. The one who could not ask was the
+ * agent doing the work — mid-drive, holding a question, with a whole tool surface and nothing on it
+ * for "what has this team already established about checkout?".
+ *
+ * That matters twice over. An agent that can read the corpus stops re-deriving what a colleague
+ * proved last week; and because the read is attributed, the coverage map's fetch counts finally
+ * measure something — they were zero across an entire real corpus, not because the knowledge was
+ * useless but because consulting it was a separate act nobody performed.
+ */
+import { z } from 'zod';
+import { ReticleTool } from '../tools/tool-names.js';
+import { countSchema } from '../tools/numeric-bounds.js';
+import { sessionIdShape } from '../tools/tool-kit.js';
+import { asNumber, asString } from '../tools/tools-helpers.js';
+import { sessionRoot } from '../project/session-root.js';
+import { MemoryUnavailable, readProjectMemory } from './project-memory.js';
+import { homedir } from 'node:os';
+/**
+ * Enough to orient on, not enough to flood a context.
+ *
+ * A busy subject on a real project runs to dozens of statements; an agent asking a question wants
+ * the ones that settle it. `total` always rides along, so the cap is never silent.
+ */
+const DEFAULT_LIMIT = 10;
+/** What to do next, per reason. A refusal that does not say how to fix it is a dead end. */
+const ADVICE = {
+    [MemoryUnavailable.NOT_LINKED]: 'this project is not linked to a Reticle workspace, so there is no shared memory to read. Run `npx @reticlehq/server login` in the project to link it.',
+    [MemoryUnavailable.DISABLED]: 'this project is linked but memory sync is turned off in .reticle/cloud.json, so nothing is being shared. Enable `sync.memory` to use it.',
+    [MemoryUnavailable.UNREACHABLE]: 'the workspace could not be reached, or refused the key. Nothing is wrong with this project — try again, or check the link with `reticle status`.',
+};
+export const MEMORY_TOOLS = [
+    {
+        name: ReticleTool.MEMORY,
+        description: 'Ask what THIS PROJECT already knows — the shared memory its team has built up, written by every engineer who verified something and readable by every agent since. Use it BEFORE re-deriving how a feature is supposed to behave: a colleague may already have proved it, and a statement marked `proved` was established by a real verdict rather than written down. With { subject } it narrows to one area (a flow name, or a route like "checkout"); without, it returns across the project. Each entry carries the flow and the source file it is about, so a claim can be checked. The read is recorded as an agent consultation, which is what the dashboard\'s per-flow fetch counts are built from. Returns { subject, known, total } or { error, reason, advice } when this project is not linked to a workspace.',
+        inputSchema: {
+            subject: z
+                .string()
+                .optional()
+                .describe('Narrow to one area — a flow name ("checkout-pay") or a route segment ("issues"). Omit to read across the whole project. Subjects come from the coverage map; an unknown one returns nothing rather than erroring.'),
+            limit: countSchema
+                .optional()
+                .describe(`Most relevant N statements. Defaults to ${String(DEFAULT_LIMIT)}. Proved statements rank first, so a small limit still returns the settled ones. \`total\` always reports the true count.`),
+            ...sessionIdShape,
+        },
+        outputSchema: {
+            subject: z.string().nullable().optional(),
+            known: z.array(z.unknown()).optional(),
+            total: z.number().optional(),
+            error: z.string().optional(),
+            reason: z.string().optional(),
+            advice: z.string().optional(),
+        },
+        handler: async (deps, args) => {
+            /*
+             * The APP's root, not the daemon's.
+             *
+             * `deps.reticleRoot` is wherever the daemon was launched, which for a user-scoped MCP
+             * registration is almost never the project being driven — so the link file it reads is the
+             * wrong one or absent, and every project silently reads as "not attached". The same defect
+             * has now been fixed three times in this codebase; routing through sessionRoot is what stops
+             * a fourth.
+             */
+            const root = sessionRoot(deps, asString(args['sessionId']));
+            const subject = asString(args['subject']);
+            const result = await readProjectMemory(deps.fs, root, homedir(), process.env, {
+                subject,
+                limit: asNumber(args['limit']) ?? DEFAULT_LIMIT,
+            });
+            if (!result.ok)
+                return {
+                    error: 'no shared memory available for this project',
+                    reason: result.reason,
+                    advice: ADVICE[result.reason],
+                };
+            return { subject: result.subject, known: result.known, total: result.total };
+        },
+    },
+];

package/dist/memory/project-memory.d.ts

@@ -0,0 +1,34 @@
+import type { FileSystemPort } from '../project/fs-port.js';
+/** Named so a read from the tool surface is distinguishable from the CLI's and from replay's. */
+export declare const MCP_AGENT_ID = "reticle-mcp";
+/** Why a lookup returned nothing. Each one is a different thing for the agent to do next. */
+export declare const MemoryUnavailable: {
+    /** No `.reticle/cloud.json` — this project has never been linked to a workspace. */
+    readonly NOT_LINKED: "not-linked";
+    /** Linked, but the link says not to sync memory. A setting, not a failure. */
+    readonly DISABLED: "memory-sync-disabled";
+    /** The server was reached and said no, or could not be reached at all. */
+    readonly UNREACHABLE: "unreachable";
+};
+export type MemoryUnavailable = (typeof MemoryUnavailable)[keyof typeof MemoryUnavailable];
+export interface KnownThing {
+    statement: string;
+    status: string;
+    flowName: string | null;
+    sourceFile: string | null;
+    subject: string;
+}
+export type ProjectMemoryResult = {
+    ok: true;
+    subject: string | null;
+    known: KnownThing[];
+    total: number;
+} | {
+    ok: false;
+    reason: MemoryUnavailable;
+};
+export declare const rankKnown: (things: readonly KnownThing[]) => KnownThing[];
+export declare function readProjectMemory(fs: FileSystemPort, root: string, home: string, env: NodeJS.ProcessEnv, opts: {
+    subject?: string | undefined;
+    limit: number;
+}): Promise<ProjectMemoryResult>;

package/dist/memory/project-memory.js

@@ -0,0 +1,96 @@
+/**
+ * What the PROJECT knows, read on demand.
+ *
+ * Shared memory reached three places before this one: the sync writes it, flow replay consults it
+ * automatically, and `reticle memory` prints it at a terminal. The one caller who could not ask was
+ * the agent actually doing the work — mid-drive, holding a question, with 44 tools and none of them
+ * "what does this team already know about checkout?". That is the gap this closes, and it is the
+ * difference between a corpus and a wiki nobody opens.
+ *
+ * The read is ATTRIBUTED. It carries an agent header, so the coverage map counts it as a
+ * consultation and a manager can see which flows are actually being pulled and by whom — the
+ * question the fetch counters exist to answer and could not while nothing was reading.
+ */
+import { cloudFetch } from '../cloud/cloud-sync.js';
+import { resolveProjectCloud } from '../cloud/cloud-config.js';
+/** Named so a read from the tool surface is distinguishable from the CLI's and from replay's. */
+export const MCP_AGENT_ID = 'reticle-mcp';
+/** Why a lookup returned nothing. Each one is a different thing for the agent to do next. */
+export const MemoryUnavailable = {
+    /** No `.reticle/cloud.json` — this project has never been linked to a workspace. */
+    NOT_LINKED: 'not-linked',
+    /** Linked, but the link says not to sync memory. A setting, not a failure. */
+    DISABLED: 'memory-sync-disabled',
+    /** The server was reached and said no, or could not be reached at all. */
+    UNREACHABLE: 'unreachable',
+};
+/** Defensive: the wire is somebody else's server, so every field is checked before it is trusted. */
+const asKnown = (raw) => {
+    if (null === raw || typeof raw !== 'object')
+        return null;
+    const r = raw;
+    const statement = r['statement'];
+    if (typeof statement !== 'string' || 0 === statement.length)
+        return null;
+    return {
+        statement,
+        status: 'string' === typeof r['status'] ? r['status'] : 'unknown',
+        flowName: 'string' === typeof r['flowName'] ? r['flowName'] : null,
+        sourceFile: 'string' === typeof r['sourceFile'] ? r['sourceFile'] : null,
+        subject: 'string' === typeof r['subject'] ? r['subject'] : 'unsorted',
+    };
+};
+/**
+ * Proved first, then the rest.
+ *
+ * An agent reading this is about to act on it, and a statement a verdict has actually established
+ * is worth more than one somebody merely wrote down. Stable within each group so the same call
+ * twice returns the same order — an unstable list reads as the corpus churning when it has not.
+ */
+const PROVED = 'proved';
+export const rankKnown = (things) => [
+    ...things.filter((t) => PROVED === t.status),
+    ...things.filter((t) => PROVED !== t.status),
+];
+export async function readProjectMemory(fs, root, home, env, opts) {
+    const cloud = await resolveProjectCloud(fs, root, home, env);
+    if (null === cloud.config)
+        return { ok: false, reason: MemoryUnavailable.NOT_LINKED };
+    if (!cloud.policy.memory)
+        return { ok: false, reason: MemoryUnavailable.DISABLED };
+    const query = opts.subject === undefined ? '' : `?subject=${encodeURIComponent(opts.subject)}`;
+    try {
+        const res = await cloudFetch(`${cloud.config.url}/v1/memory${query}`, {
+            method: 'GET',
+            headers: {
+                authorization: `Bearer ${cloud.config.apiKey}`,
+                // What makes this read COUNT as an agent consulting the corpus rather than a human
+                // browsing — the distinction the dashboard's "times an agent consulted it" rests on.
+                'x-reticle-agent': MCP_AGENT_ID,
+            },
+        });
+        if (200 !== res.status)
+            return { ok: false, reason: MemoryUnavailable.UNREACHABLE };
+        // `cloudFetch` returns a real Response, so the body is a METHOD. Reading `res.json` as a
+        // property yields the function, and every downstream field is undefined — a silent "the project
+        // knows nothing" that is indistinguishable from the honest empty case. It cost a live drive to
+        // find once already.
+        const body = (await res.json());
+        const entries = body?.entries;
+        if (!Array.isArray(entries))
+            return { ok: false, reason: MemoryUnavailable.UNREACHABLE };
+        const known = entries.map(asKnown).filter((k) => k !== null);
+        return {
+            ok: true,
+            subject: opts.subject ?? null,
+            // Capped for the agent's context, but `total` always reports the truth so the cap is never
+            // silent — a truncated list that looks complete is how an agent concludes a project knows
+            // less than it does.
+            known: rankKnown(known).slice(0, opts.limit),
+            total: known.length,
+        };
+    }
+    catch {
+        return { ok: false, reason: MemoryUnavailable.UNREACHABLE };
+    }
+}

package/dist/oracles/propose-consequences.js

@@ -1,4 +1,5 @@
 import { EventType, PredicateKind } from '@reticlehq/core';
+import { routePathOf } from '../events/predicate-route.js';
 const TIER = { SIGNAL: 0, CONSEQUENCE: 1, PRESENCE: 2 };
 function pathname(url) {
     if (typeof url !== 'string')
@@ -66,10 +67,18 @@ export function proposeConsequences(events) {
                 break;
             }
             case EventType.ROUTE_CHANGE: {
-                const to = data['pathname'];
-                if ('string' === typeof to) {
+                const docPath = data['pathname'];
+                if ('string' === typeof docPath) {
+                    // `pathname`, not `to`: the evaluator has never accepted `to`, so this surface was handing
+                    // the agent a predicate reticle_assert refuses with "unknown field to". A proposal that
+                    // cannot be evaluated is worse than no proposal — see the schema check in the test.
+                    //
+                    // And the ROUTER's path, not the document's: under a hash router the document pathname is
+                    // `/` on every page, so proposing it proposes an assertion that says nothing about where
+                    // the app went.
+                    const to = routePathOf(docPath, 'string' === typeof data['hash'] ? data['hash'] : '');
                     add(`route:${to}`, {
-                        predicate: { kind: PredicateKind.ROUTE, to },
+                        predicate: { kind: PredicateKind.ROUTE, pathname: to },
                         tier: TIER.CONSEQUENCE,
                         label: `route changes to ${to}`,
                         weak: false,