@reticlehq/server 2.11.0 → 2.13.0

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/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,22 @@
  * 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;
+/**
+ * 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

@@ -25,6 +25,28 @@ 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;
+}
+/** 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/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/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,

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) {