@reticlehq/server 3.5.0 → 3.7.0

package/dist/surface/mcp/mcp.js

@@ -1,4 +1,5 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { randomUUID } from 'node:crypto';
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
 import { isPredicateParam } from '@reticlehq/engine/question/predicate/predicate-eval.js';
@@ -8,7 +9,7 @@ import { filterTools, describeToolSurface, TOOL_SURFACE, } from '../tools/tool-s
 import { ReticleTool } from '@reticlehq/core';
 import { SHARED_PARAM_SHORT } from './shared-params.js';
 import { buildDynamicTools } from '../tools/dynamic-tools.js';
-import { runTool, SESSION_BOUND_TOOLS } from '../tools/invoke-tool.js';
+import { runTool } from '../tools/invoke-tool.js';
 import { sessionEnvelopeShape, newSnapshotCache } from '../tools/tool-kit.js';
 import { buildErrorPayload } from '../tools/error-recovery.js';
 import { takeVersionSkewOnto } from '../../command/version/version-nudge.js';
@@ -37,15 +38,20 @@ import { SERVER_VERSION } from '../../command/version/identity/server-version.js
 import { setMcpClientNameHook } from '../../telemetry/feedback-context.js';
 import { getSessionMetrics } from '../../telemetry/session-metrics.js';
 import { reportMcpConnected } from '../../telemetry/mcp-connection.js';
+import { noteAgentAttached, noteAgentDetached, runAsAgent } from '../../hooks/coding-agents.js';
 import { parsePredicate } from '@reticlehq/engine/question/predicate/predicate-parse.js';
 /**
- * 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
- * own keys win over the permissive envelope defaults (e.g. ACT keeps its typed `session` shape).
- * Non-session-bound tools (and tools with no outputSchema) are returned unchanged.
+ * Merge the runtime-spliced envelope into a tool's declared outputSchema so structuredContent
+ * validation keeps those fields instead of rejecting the call. The tool's own keys win over the
+ * permissive envelope defaults (e.g. ACT keeps its typed `session` shape).
+ *
+ * EVERY tool with an output schema, not only the session-bound ones: `runTool` adds `next`,
+ * `update_available`, `version_skew` and the feedback keys to any tool's result, and a session-exempt
+ * tool with a strict schema (`reticle_context`) failed the whole call on a validating client the
+ * first time one of them rode on it.
  */
-export function withSessionEnvelope(name, outputSchema) {
-    if (outputSchema === undefined || !SESSION_BOUND_TOOLS.has(name))
+export function withSessionEnvelope(_name, outputSchema) {
+    if (outputSchema === undefined)
         return outputSchema;
     return { ...sessionEnvelopeShape, ...outputSchema };
 }
@@ -134,7 +140,7 @@ const COMPACT_PREDICATE_DESCRIPTION = `${PREDICATE_KINDS}${PREDICATE_FIELD_GRAMM
  * schema cost; the first clause keeps each param's purpose and any enum hints. Params without a
  * description pass through unchanged. Predicate params are replaced wholesale — see above.
  */
-function leanZodShape(shape, predicateAnchor) {
+function leanZodShape(shape, advertised, predicateAnchor) {
     const out = {};
     // The navigation hint is said ONCE per turn, so it is anchored to one parameter — not one tool.
     // A tool can carry two predicate parameters (a canonical name plus a neighbouring tool's alias),
@@ -160,8 +166,13 @@ function leanZodShape(shape, predicateAnchor) {
             out[key] = schema.describe(shared);
             continue;
         }
+        // Through the same rewrite as tool descriptions: a parameter that says "a ref from
+        // reticle_snapshot" names a tool this surface does not have.
         const desc = schema.description;
-        out[key] = 'string' === typeof desc ? schema.describe(firstSentence(desc)) : schema;
+        out[key] =
+            'string' === typeof desc
+                ? schema.describe(liveCallText(firstSentence(desc), advertised))
+                : schema;
     }
     return out;
 }
@@ -182,6 +193,27 @@ export function encodeResult(result, encoding) {
     }
     return encoding === PRETTY_VALUE ? JSON.stringify(result, null, 2) : JSON.stringify(result);
 }
+const PROGRESS_NOTIFICATION = 'notifications/progress';
+/**
+ * The request's cancellation and, when the client sent a progress token, a progress reporter. A
+ * long call (a Harness drive's wait) reports each step, so a client that resets its timeout on
+ * progress keeps waiting instead of abandoning a call that is working.
+ */
+export function toolCallOf(extra) {
+    const token = extra?._meta?.progressToken;
+    const send = extra?.sendNotification;
+    return {
+        ...(extra?.signal === undefined ? {} : { signal: extra.signal }),
+        ...(token === undefined || send === undefined
+            ? {}
+            : {
+                progress: (progress, message) => void send({
+                    method: PROGRESS_NOTIFICATION,
+                    params: { progressToken: token, progress, message },
+                }).catch(() => undefined),
+            }),
+    };
+}
 /**
  * The tools a profile advertises directly.
  *
@@ -292,9 +324,13 @@ export function advertisedConfig(tool, advertised, profile) {
         // Against the advertised set, for the same reason results are: `reticle_navigate`'s own
         // description told the reader to confirm a reload with `reticle_sessions`, on the surface
         // where that name is gone. A description is advice like any other.
-        liveCallText(terse ? firstSentence(tool.description) : tool.description, new Set(advertised.map((each) => each.name))), tool.example),
+        // Not on the meta-tools: they exist to name what is reachable only through `reticle_run`,
+        // and rewriting those names to advertised ones turned `reticle_tools` into nonsense.
+        isMetaTool
+            ? tool.description
+            : liveCallText(terse ? firstSentence(tool.description) : tool.description, new Set(advertised.map((each) => each.name))), tool.example),
         inputSchema: terse
-            ? leanZodShape(tool.inputSchema, tool.name === anchor ? undefined : anchor)
+            ? leanZodShape(tool.inputSchema, new Set(advertised.map((each) => each.name)), tool.name === anchor ? undefined : anchor)
             : tool.inputSchema,
         ...(outputSchema !== undefined ? { outputSchema } : {}),
     };
@@ -416,8 +452,10 @@ function installUnadvertisedToolHelp(server, advertised, known) {
             return original(asCallOf(request, moved.tool, moved.action), extra);
         }
         const help = name === undefined ? undefined : unadvertisedToolHelp(name, advertised, known);
+        // A failed RESULT, not a JSON-RPC error: a client that reads only `result` rendered the error
+        // as an empty success, and the agent believed `reticle_flow_save` had saved its flow.
         if (help !== undefined)
-            throw new McpError(ErrorCode.InvalidParams, help);
+            return { content: [{ type: 'text', text: help }], isError: true };
         return original(request, extra);
     });
 }
@@ -491,7 +529,7 @@ tools = tableForSurface(profile)) {
      * runs once per client connection, which makes it the right owner; a caller that supplies its own
      * store keeps it.
      */
-    const deps = { snapshots: newSnapshotCache(), ...rawDeps };
+    const deps = { snapshots: newSnapshotCache(), attachId: randomUUID(), ...rawDeps };
     const encoding = (process.env[ENCODING_ENV] ?? '').toLowerCase();
     // Which surface this daemon advertises. The 18-tool default and the 48-tool full surface are
     // different products from inside an agent's context, so outcomes are only comparable when the
@@ -499,7 +537,7 @@ tools = tableForSurface(profile)) {
     getSessionMetrics().recordSurface(profile);
     const server = new McpServer(SERVER_INFO, {
         instructions: buildServerInstructions({
-            previouslyConnected,
+            ...('boolean' === typeof previouslyConnected ? { previouslyConnected } : previouslyConnected),
             // The surface this server is about to serve. Without it the briefing describes the tools this
             // package SHIPS rather than the ones this daemon advertises, and on any trimmed surface that
             // is a briefing for a different product — measured cost: an agent that stopped driving.
@@ -523,12 +561,15 @@ tools = tableForSurface(profile)) {
         if (info?.name === undefined)
             return;
         getSessionMetrics().recordClient(info.name, info.version);
+        // So the HUD can say which agent is connected, and credit a note to the one that read it.
+        noteAgentAttached(deps.attachId, info.name);
         // The one signal that separates "Reticle is running" from "somebody is USING it", reported from
         // the first moment it can carry WHO. It used to fire from the SSE `connect()` resolution, which
         // happens before the handshake — so every connect row was anonymous, and the field meant to say
         // which agent client converts best was empty on every event ever sent.
-        reportMcpConnected(info.name);
+        void runAsAgent(deps.attachId, () => Promise.resolve(reportMcpConnected(info.name)));
     };
+    server.server.onclose = () => noteAgentDetached(deps.attachId);
     // Which agent is on the other end, for a feedback report. Registered as a lazy hook rather than
     // read here: the handshake has not happened yet at construction time, and a report filed twenty
     // tool calls later is exactly when we want the answer.
@@ -610,9 +651,12 @@ tools = tableForSurface(profile)) {
         // clients. This removes the single largest remaining slice of the per-request tax (~36% of the
         // hybrid payload) with no loss the agent can observe.
         const config = advertisedConfig(tool, advertised, profile);
-        registerTool(tool.name, config, async (args) => {
+        registerTool(tool.name, config, async (args, extra) => {
             try {
-                const result = await runTool(tool, deps, args);
+                // Inside the caller's connection, so the telemetry this call emits after its handler (the
+                // verdict, a defect, a refusal) is credited to the agent that made it, not to whichever
+                // agent is attached.
+                const result = await runAsAgent(deps.attachId, () => runTool(tool, deps, args, toolCallOf(extra)));
                 // A tool this codebase did not write may not hand the agent a verdict.
                 //
                 // Only reached for a tool absent from the first-party table, so the shipped surface pays a

package/dist/surface/mcp/proxy/drive-calls.d.ts

@@ -0,0 +1,10 @@
+/** A `tools/call` of reticle_verify explore, directly or through the reticle_run hatch. */
+export declare function isHarnessDriveCall(msg: {
+    method?: unknown;
+    params?: unknown;
+}): boolean;
+/**
+ * A drive lives in the daemon, not in the call: a lost connection does not end it, and retrying the
+ * call as if it had not run pays for a second drive.
+ */
+export declare const MSG_DRIVE_MAY_BE_RUNNING: string;

package/dist/surface/mcp/proxy/drive-calls.js

@@ -0,0 +1,27 @@
+/** Which proxied calls are Harness drives, and what to tell an agent whose drive call was lost. */
+import { ReticleTool } from '@reticlehq/core';
+const TOOLS_CALL = 'tools/call';
+const EXPLORE_ACTION = 'explore';
+/** A `tools/call` of reticle_verify explore, directly or through the reticle_run hatch. */
+export function isHarnessDriveCall(msg) {
+    if (TOOLS_CALL !== msg.method)
+        return false;
+    const params = (msg.params ?? {});
+    const args = (params.arguments ?? {});
+    if (ReticleTool.VERIFY_EXPLORE === params.name)
+        return true;
+    if (ReticleTool.VERIFY === params.name)
+        return EXPLORE_ACTION === args['action'];
+    if (ReticleTool.RUN !== params.name)
+        return false;
+    const inner = (args['args'] ?? {});
+    return (ReticleTool.VERIFY_EXPLORE === args['tool'] ||
+        (ReticleTool.VERIFY === args['tool'] && EXPLORE_ACTION === inner['action']));
+}
+/**
+ * A drive lives in the daemon, not in the call: a lost connection does not end it, and retrying the
+ * call as if it had not run pays for a second drive.
+ */
+export const MSG_DRIVE_MAY_BE_RUNNING = `The Harness drive this call started or polled may still be running in the daemon. Once ` +
+    `Reticle reconnects, call ${ReticleTool.VERIFY} {action:"explore"} with no runId to get the ` +
+    `running drive back (it will not start a second), then poll it by runId.`;

package/dist/surface/mcp/proxy/mcp-post-transport.js

@@ -7,6 +7,7 @@
  * saying honestly that it never arrived — and the file it came from is about the SSE stream.
  */
 import * as http from 'node:http';
+import { MCP_CLIENT_DIRECTORY_HEADER } from '@reticlehq/core';
 import { log } from '../../../log.js';
 import { getSessionMetrics } from '../../../telemetry/session-metrics.js';
 import { reconnectDelayMs } from './proxy-backoff.js';
@@ -47,6 +48,10 @@ export function postToSession(url, body, request = (options, callback) => http.r
             headers: {
                 'Content-Type': 'application/json',
                 'Content-Length': bodyBuf.byteLength,
+                // The project this proxy was started in. The daemon serves every project; without this
+                // it can only see the directory it itself started in. Percent-encoded: a cwd such as
+                // `/work/项目` is not a legal header value, and Node throws before the request is sent.
+                [MCP_CLIENT_DIRECTORY_HEADER]: encodeURIComponent(process.cwd()),
             },
         };
         // A keep-alive socket carries historical bytes; retry safety depends on this request's delta.

package/dist/surface/mcp/server-instructions.d.ts

@@ -1,4 +1,6 @@
-interface InstructionState {
+/** The nudge set for the AGENT's directory: a shared daemon briefs from where IT started. */
+export declare function localizeInstructions(instructions: string, appHere: boolean): string;
+export interface InstructionState {
     /**
      * The names this surface actually advertises. Every tool the prose mentions is resolved from it.
      *
@@ -15,6 +17,7 @@ interface InstructionState {
      * is whether this install has EVER worked, not whether it is working this second.
      */
     previouslyConnected: boolean;
+    appHere?: boolean;
 }
 /** The instructions this daemon should advertise, given what it knows about the project. */
 /**
@@ -23,4 +26,3 @@ interface InstructionState {
  * repeated across every parameter description. See shared-params.ts.
  */
 export declare function buildServerInstructions(state: InstructionState): string;
-export {};

package/dist/surface/mcp/server-instructions.js

@@ -1,4 +1,4 @@
-import { ReticleTool } from '@reticlehq/core';
+import { ReticleTool, WRITING_RULE_SHORT } from '@reticlehq/core';
 import { SHARED_PARAM_GUIDANCE } from './shared-params.js';
 import { defaultAdvertisedNames } from '../tools/tool-surface.js';
 import { surfaceVocabulary, listOf } from './surface-vocabulary.js';
@@ -44,9 +44,9 @@ import { surfaceVocabulary, listOf } from './surface-vocabulary.js';
  */
 const verdictDiscipline = (v) => `Reticle verifies a running web app from the inside: go (${v.navigate}), look (${listOf(v.look, v.find)}), act and prove in one hop (${v.actAndWait}), observe (${listOf(v.observe, v.state, v.network, v.console)}), assert (${v.assert}). Verify a user-facing change against the real app before you call it done — \`npx @reticlehq/server gate --since <ref>\` fails unless a passing artifact covers every flow your edits affect — and never weaken a check to make it pass.
 
-Only ${v.act.length > 0 ? `${v.actAndWait}, ${v.assert} and ${v.act}{steps}` : `${v.actAndWait} and ${v.assert}`} produce a verdict. Everything else moves or reads the app and proves nothing, so a drive that ends without one of those two has no result however many tools it used. Prefer ${v.actAndWait}({ 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 ${v.act.length > 0 ? `${v.actAndWait}, ${v.assert} and ${v.act}{steps}` : `${v.actAndWait} and ${v.assert}`} produce a verdict. Everything else proves nothing; a drive without one has no result. Prefer ${v.actAndWait}({ 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" and "no-fault" (nothing declared) are not proved, never failed. When a verdict catches what reading the code missed, say Reticle found it. Do a result's \`next\`.
 
-Done is the journey's END proved, not its first step: drive each step your change touches and give the last an \`until\` naming the end state (\`durable: true\` if it must persist). A "yes" on it over a clean capture IS the answer — stop.
+Done is the journey's END proved, not its first step: drive each step your change touches and give the last an \`until\` naming the end state (\`durable: true\` if it must persist). A "yes" on it over a clean capture IS the answer — stop.${v.act.length > 0 ? ` Several steps? ONE ${v.act}{ steps: [{ target, action, expect }] } drives them all and stops at the first expect that fails; the last expect is the end state.` : ''}
 
 DIAGNOSING a bug? Read the source first — Reticle proves what the app DOES, not why. Drive to CONFIRM a fix, not to find one.`;
 /**
@@ -77,8 +77,15 @@ const replayFirst = (v) => {
     if (0 === v.replayChange.length)
         return '';
     const ask = v.affected.length > 0 ? `${v.affected} names the saved flows covering your edits; ` : '';
-    return `Changed code? Replay before you drive. ${ask}${v.replayChange} replays them for one verified + because — hundreds of tokens where driving the same journey costs tens of thousands. "yes": proved, stop. "no": names the step that broke. "unknown": NO saved flow covers it, so nothing was proved — drive it, and never report it as passing. What you drive by hand is saved as a flow automatically.`;
+    return `Changed code? Replay before you drive. ${ask}${v.replayChange} replays them for one verified + because — far cheaper than driving it again. "yes": proved, stop. "no": names the step that broke. "unknown": NO saved flow covers it, so nothing was proved — drive it, and never report it as passing. What you drive by hand is saved as a flow automatically.${driveOnce(v)}`;
 };
+/**
+ * A drive outlives a client's timeout, so its call answers with a run id instead of waiting for the
+ * end; an agent that retried instead of polling paid for a second drive.
+ */
+const driveOnce = (v) => 0 === v.explore.length
+    ? ''
+    : ` Drivers: you, or the Harness (${v.explore}; opt-in at 80% instrumentation): poll its runId; never start two.`;
 /**
  * The first move, for a project no app has ever connected to.
  *
@@ -90,9 +97,22 @@ const replayFirst = (v) => {
  * common way this step half-succeeds. Telling every agent to restart sent them to kill the server
  * `init` had just started.
  */
-const firstMoveFor = (v) => `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.
+// The lead is a snapshot, not a present fact: these instructions are sent ONCE, at the handshake, and
+// the app can connect a minute later. Stated as fact, it kept agents running setup while the session
+// list showed the app connected (#1362).
+const firstMoveFor = (v, appHere) => `FIRST: when this session started, no app had connected to Reticle in this project. Having these tools is not the same as being set up — the tools reach a daemon that has nothing to look at until the app is instrumented.
 
-Fix that before anything else: run \`npx @reticlehq/server init\` in the project. It starts the dev server and opens the app itself; only if a dev server was ALREADY running without Reticle, restart it and reload the tab. Confirm with ${v.sessions} — a session listed there is the proof, and until one appears no other tool can tell you anything about this app.`;
+Fix that first: call ${v.sessions}. Its first call wires the app (\`init\`, dev server, browser) and \`wired\` lists the files it changed; tell the user. If it answers \`run_init\`, run that command in the app's directory. A session on this project's app listed there is the proof; until one appears no other tool can tell you anything about this app.${appHere ? TELL_THE_USER : ''}`;
+const UNWIRED_LEAD_END = 'can tell you anything about this app.';
+// An agent never asked to verify anything never reads "fix that first"; this makes it raise wiring.
+const TELL_THE_USER = ' If none is listed, this directory holds a web app that is not wired: in your first reply, even if their request is unrelated, tell the user in one line and offer to wire it (the first session call does it). Do it only if they agree; if they decline, do not raise it again.';
+/** The nudge set for the AGENT's directory: a shared daemon briefs from where IT started. */
+export function localizeInstructions(instructions, appHere) {
+    const without = instructions.replace(TELL_THE_USER, '');
+    if (!appHere || !without.includes(UNWIRED_LEAD_END))
+        return without;
+    return without.replace(UNWIRED_LEAD_END, `${UNWIRED_LEAD_END}${TELL_THE_USER}`);
+}
 /**
  * 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.
@@ -120,16 +140,14 @@ const reachFor = (v) => {
     // surface-vocabulary.ts. Where there is no cold tail, there is nothing to say about reaching it.
     if (v.coldTail.length > 0) {
         lines.push(`${v.coldTail} Two to know early: ${ReticleTool.RUN}({ tool: "${ReticleTool.CONTEXT}", args: {} }) returns what this run already established, after a compaction or handover, and ${ReticleTool.RUN}({ tool: "${ReticleTool.INTENT}", args: { action: "declare", ... } }) declares what a change was MEANT to do, so the verdict has something to check against other than itself.`);
+        // Measured: in 8 real agent runs asked to test an app, none read what Reticle already held
+        // first, and none could tell its user the credits or the Harness state.
+        lines.push(`Before testing, read what Reticle knows: ${ReticleTool.RUN}({ tool: "${ReticleTool.MEMORY}", args: {} })${v.yield.length > 0 ? ` and ${ReticleTool.SESSION} {action:"account"} (plan, credits, Harness)` : ''}.`);
     }
     return lines.join('\n\n');
 };
 /** The feedback ask. Constant: an agent that cannot get set up is the report we most need. */
-const feedbackAsk = (v) => `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 \`${v.feedback}\` the moment you notice, then carry on with your task:
-- Reticle broke, lied, or could not see something you needed (\`bug\` / \`gap\` / \`ambiguity\`).
-- You wished it could do something, or something works but costs too many calls (\`feature_request\` / \`improvement\`).
-- The install, the wiring, or the setup itself gave you trouble — including anything you had to work around by hand.
-
-Nothing is too minor, and a report costs one call. If the tools are unreachable (setup unfinished, daemon down), file the same report from the shell instead: \`reticle feedback --agent --kind <one of those kinds> "what happened"\`. Report defects in RETICLE — a bug you find in the app under test is Reticle working, and belongs in your answer to the user.`;
+const feedbackAsk = (v) => `Feedback is first-class here: once per session, when Reticle got in your way, send \`${v.feedback}\` and carry on — it broke, lied or missed something (\`bug\` / \`gap\` / \`ambiguity\`), cost too many calls or lacked something (\`improvement\` / \`feature_request\`), or the install, the wiring, or the setup gave you trouble. Tools unreachable? \`reticle feedback --agent --kind <kind> "what happened"\`. A bug in the app under test belongs in your answer to the user.`;
 /** The instructions this daemon should advertise, given what it knows about the project. */
 /**
  * Instructions are sent ONCE at initialize; the tool surface is re-sent every turn, and costs an
@@ -146,7 +164,7 @@ export function buildServerInstructions(state) {
     // passing a surface, so a stale fallback here is what every agent reaching Reticle through
     // `reticle mcp` reads — naming tools the surface it is being served does not have.
     const v = surfaceVocabulary(state.advertised ?? defaultAdvertisedNames());
-    const firstMove = firstMoveFor(v);
+    const firstMove = firstMoveFor(v, true === state.appHere);
     /*
      * Said in BOTH states, and gated only on whether the surface can reach replay.
      *
@@ -165,5 +183,5 @@ export function buildServerInstructions(state) {
         ? `${verdictDiscipline(v)}\n\n${reachFor(v)}\n\n${feedbackAsk(v)}`
         : `${firstMove}\n\n${verdictDiscipline(v)}\n\n${feedbackAsk(v)}`;
     const withReplay = replay.length > 0 ? `${base}\n\n${replay}` : base;
-    return `${withReplay}\n\n${SHARED_PARAM_GUIDANCE}`;
+    return `${withReplay}\n\n${SHARED_PARAM_GUIDANCE}\n\n${WRITING_RULE_SHORT}`;
 }

package/dist/surface/mcp/shared-params.js

@@ -22,14 +22,14 @@
 /** The short form left in the per-turn schema. Must still make sense with no instructions at all. */
 export const SHARED_PARAM_SHORT = {
     sessionId: 'Target a specific tab. Omit unless you mean one — see instructions.',
-    since: 'Cursor from a prior reticle_act/reticle_observe.',
+    since: 'Cursor from a prior act/observe, or a git ref.',
     limit: 'Cap descriptors to the first N.',
 };
 /** The full text, sent once at initialize. Everything trimmed above is restated here. */
 export const SHARED_PARAM_GUIDANCE = 'Arguments that mean the same thing on every tool: `sessionId` — omit unless you mean a specific ' +
     'tab; Reticle scopes to your project, prefers the active one, and refuses rather than guesses when ' +
     'ambiguous. `since` — a cursor from a prior act/observe, bounding an observation to what came ' +
-    'after it. `limit` — caps returned descriptors, cutting tokens on broad queries.';
+    'after it, or a git ref when verifying a change. `limit` — caps returned descriptors.';
 /** Is this a parameter whose guidance now lives in the instructions block? */
 export function isSharedParam(name) {
     return Object.hasOwn(SHARED_PARAM_SHORT, name);

package/dist/surface/mcp/surface-vocabulary.d.ts

@@ -41,6 +41,8 @@ export interface SurfaceVocabulary {
     replayAll: string;
     /** Rebind a drifted locator, or empty when the surface cannot reach it. */
     heal: string;
+    /** Start or poll a Harness drive, or empty when the surface cannot reach it. */
+    explore: string;
 }
 /** Drop the empty slots, so a sentence never reads "look (), find ()". */
 export declare function listOf(...calls: readonly string[]): string;

package/dist/surface/mcp/surface-vocabulary.js

@@ -52,5 +52,6 @@ export function surfaceVocabulary(advertisedNames) {
         replayChange: call(ReticleTool.VERIFY_CHANGE, ReticleTool.VERIFY, 'change'),
         replayAll: call(ReticleTool.FLOW_REPLAY, ReticleTool.VERIFY, 'flows'),
         heal: advertised.has(ReticleTool.FLOW_HEAL) ? ReticleTool.FLOW_HEAL : '',
+        explore: call(ReticleTool.VERIFY_EXPLORE, ReticleTool.VERIFY, 'explore'),
     };
 }

package/dist/surface/tools/account-tool.d.ts

@@ -0,0 +1,22 @@
+import type { ToolDef } from './tool-kit.js';
+/** What the agent is told to do next, in plain words: one step, the first one that applies. */
+export declare const ACCOUNT_NEXT: {
+    readonly SIGN_IN: "The user is not signed in to Reticle. Ask them to run `reticle connect` in the app folder: it signs them in and links this project. A new account gets 10 free credits.";
+    readonly LINK: "This project does not report to the dashboard yet. Ask the user to press \"Link this project\" on the Harness page of the HUD, or to run `reticle connect` in the app folder.";
+    readonly UNREACHABLE: "The Reticle platform did not answer, so credits and the Harness are not known now. Local checks still work.";
+    readonly NO_CREDITS: (said: string) => string;
+    readonly locked: (percent: number, missing: string) => string;
+    readonly OFF: "Reticle Harness is off for this project. The user can switch it on in the HUD (the Harness row at the foot of the Agent Log) or on the dashboard.";
+    readonly NO_PROVIDER: "The platform has no model provider set, so Reticle Harness cannot run now. Tell the user; it is not on their side.";
+    readonly ready: (typical: number | undefined, max: number | undefined) => string;
+};
+export interface AccountInput {
+    signedIn: boolean;
+    workspace?: string;
+    dashboardUrl?: string;
+    /** The platform's `/v1/model/config` answer; undefined when unlinked, null when it did not answer. */
+    platform: Record<string, unknown> | null | undefined;
+}
+/** The facts and the next step. Pure: the tool's I/O is in `readAccount`. */
+export declare function accountFacts(input: AccountInput): Record<string, unknown>;
+export declare const ACCOUNT_TOOLS: ToolDef[];

package/dist/surface/tools/account-tool.js

@@ -0,0 +1,157 @@
+/**
+ * Where the user stands with Reticle, for the coding agent: signed in or not, whether this project
+ * reports to the dashboard, the plan and credits left, whether Reticle Harness is on and unlocked,
+ * what a Harness run costs, and the one thing to do next.
+ *
+ * In 16 real Claude Code and Codex runs, no agent could answer "how many credits do I have" or "can
+ * the Harness run" from a tool: those facts lived only in the HUD and the dashboard. This reads the
+ * same sources they do (the HUD's snapshot for the account, the platform's model config for the
+ * plan, credits and gate), so the agent and the HUD cannot disagree.
+ */
+import { z } from 'zod';
+import { ReticleTool, asRecord, asString } from '@reticlehq/core';
+import { creditsUsageText } from '@reticlehq/core/hud';
+import { impactSnapshot } from '../../memory/impact/impact-recorder.js';
+import { readDashboardUrl } from '../../memory/project/sync-status.js';
+import { sessionRoot } from '../../memory/project/session-root.js';
+import { platformHeaders } from '../../features/harness/platform/server-driver.js';
+const CONFIG_PATH = '/v1/model/config';
+const CONFIG_TIMEOUT_MS = 3_000;
+const UNLOCK_PERCENT = 80;
+/** What the agent is told to do next, in plain words: one step, the first one that applies. */
+export const ACCOUNT_NEXT = {
+    SIGN_IN: 'The user is not signed in to Reticle. Ask them to run `reticle connect` in the app folder: it signs them in and links this project. A new account gets 10 free credits.',
+    LINK: 'This project does not report to the dashboard yet. Ask the user to press "Link this project" on the Harness page of the HUD, or to run `reticle connect` in the app folder.',
+    UNREACHABLE: 'The Reticle platform did not answer, so credits and the Harness are not known now. Local checks still work.',
+    NO_CREDITS: (said) => `${said} Reticle Harness cannot run until the user gets more credits on the dashboard's Plan and usage page.`,
+    locked: (percent, missing) => 
+    // The platform's own sentence already names the score and the gaps: said once, not twice.
+    `${0 < missing.length ? missing : `Setup score ${String(percent)}%: Reticle Harness needs ${String(UNLOCK_PERCENT)}%.`} Offer to close these gaps, then drive one flow to raise the score.`,
+    OFF: 'Reticle Harness is off for this project. The user can switch it on in the HUD (the Harness row at the foot of the Agent Log) or on the dashboard.',
+    NO_PROVIDER: 'The platform has no model provider set, so Reticle Harness cannot run now. Tell the user; it is not on their side.',
+    ready: (typical, max) => 'Reticle Harness is on and ready: reticle_verify { action: "explore", persona: "<the journey, with the text the page must show at the end in quotes>" }' +
+        (typical === undefined
+            ? '.'
+            : `. A run costs about ${String(typical)} credits${max === undefined ? '' : `, at most ${String(max)}`}.`),
+};
+const num = (v) => ('number' === typeof v ? v : undefined);
+const str = (v) => ('string' === typeof v ? v : undefined);
+/** The facts and the next step. Pure: the tool's I/O is in `readAccount`. */
+export function accountFacts(input) {
+    const base = {
+        signedIn: input.signedIn,
+        ...(input.workspace === undefined ? {} : { workspace: input.workspace }),
+        linked: input.platform !== undefined,
+        ...(input.dashboardUrl === undefined ? {} : { dashboardUrl: input.dashboardUrl }),
+    };
+    if (!input.signedIn)
+        return { ...base, next: ACCOUNT_NEXT.SIGN_IN };
+    if (input.platform === undefined)
+        return { ...base, next: ACCOUNT_NEXT.LINK };
+    if (null === input.platform)
+        return { ...base, next: ACCOUNT_NEXT.UNREACHABLE };
+    const p = input.platform;
+    const rawCredits = asRecord(p['credits']);
+    const used = num(rawCredits['used']);
+    const limit = num(rawCredits['limit']);
+    const plan = asRecord(p['plan']);
+    const daysLeft = num(plan['daysLeft']);
+    const kind = str(rawCredits['kind']);
+    const credits = used === undefined || limit === undefined
+        ? undefined
+        : {
+            used,
+            limit,
+            left: Math.max(0, limit - used),
+            ...(kind === undefined ? {} : { kind }),
+            said: creditsUsageText({
+                used,
+                limit,
+                ...('free' === kind || 'trial' === kind || 'paid' === kind ? { kind } : {}),
+                ...(daysLeft === undefined ? {} : { daysLeft }),
+            }),
+        };
+    const runCost = asRecord(p['harnessRunCredits']);
+    const typical = num(runCost['typical']);
+    const max = num(runCost['max']);
+    const lock = asRecord(p['harnessLock']);
+    const score = num(p['coverageScore']);
+    const percent = score === undefined ? undefined : Math.floor(score * 100 + 1e-9);
+    const unlocked = true === p['harnessUnlocked'];
+    const provider = str(p['provider']);
+    const providerReady = provider === undefined ? true : asRecord(p['available'])[provider] !== false;
+    const harness = {
+        on: true === p['harnessEnabled'],
+        unlocked,
+        ...(percent === undefined ? {} : { setupScore: percent }),
+        ...(str(lock['reason']) === undefined ? {} : { missing: str(lock['reason']) }),
+        ...(str(lock['prompt']) === undefined ? {} : { setupPrompt: str(lock['prompt']) }),
+        ...(typical === undefined
+            ? {}
+            : { runCredits: { typical, ...(max === undefined ? {} : { max }) } }),
+    };
+    const facts = {
+        ...base,
+        ...(0 === Object.keys(plan).length ? {} : { plan }),
+        ...(credits === undefined ? {} : { credits }),
+        harness,
+    };
+    const next = credits !== undefined && 0 === credits.left
+        ? ACCOUNT_NEXT.NO_CREDITS(credits.said)
+        : !unlocked
+            ? ACCOUNT_NEXT.locked(percent ?? 0, str(lock['reason']) ?? '')
+            : !providerReady
+                ? ACCOUNT_NEXT.NO_PROVIDER
+                : !harness.on
+                    ? ACCOUNT_NEXT.OFF
+                    : ACCOUNT_NEXT.ready(typical, max);
+    return { ...facts, next };
+}
+/** The platform's model config with this project's linked key; undefined unlinked, null on no answer. */
+async function platformConfig(deps) {
+    // The project's own link, not the environment: an agent asks about the project it is in.
+    const platform = (await deps.linkedCloud?.()) ?? null;
+    if (null === platform)
+        return undefined;
+    try {
+        const res = await fetch(`${platform.url.replace(/\/+$/, '')}${CONFIG_PATH}`, {
+            method: 'GET',
+            headers: platformHeaders(platform),
+            signal: AbortSignal.timeout(CONFIG_TIMEOUT_MS),
+        });
+        if (!res.ok)
+            return null;
+        return asRecord(JSON.parse(await res.text()));
+    }
+    catch {
+        return null;
+    }
+}
+async function readAccount(deps, sessionId) {
+    let root;
+    try {
+        root = sessionRoot(deps, sessionId);
+    }
+    catch {
+        root = undefined; // no tab: the account still answers, without a project
+    }
+    const snapshot = impactSnapshot(root);
+    const account = snapshot?.account;
+    const dashboardUrl = root === undefined ? undefined : readDashboardUrl(root);
+    return accountFacts({
+        signedIn: true === account?.signedIn,
+        ...(account?.org === undefined ? {} : { workspace: account.org }),
+        ...(dashboardUrl === undefined ? {} : { dashboardUrl }),
+        platform: await platformConfig(deps),
+    });
+}
+export const ACCOUNT_TOOLS = [
+    {
+        name: ReticleTool.ACCOUNT,
+        description: 'Where the user stands with Reticle: signed in or not, whether this project reports to the dashboard, the plan and credits left, whether Reticle Harness is on and unlocked, the setup score and what is missing, what a Harness run costs, and the one thing to do next. Read it before you tell the user anything about credits, the plan or the Harness.',
+        inputSchema: {
+            sessionId: z.string().optional().describe('Target a specific tab. Omit unless you mean one.'),
+        },
+        handler: async (deps, args) => readAccount(deps, asString(args['sessionId'])),
+    },
+];

package/dist/surface/tools/act/act-danger.d.ts

@@ -18,3 +18,14 @@ export declare function assertDragNotDestructive(innerArgs: Record<string, unkno
 export declare const NATIVE_INPUT_UNSUPPORTED: string;
 /** Refuse rather than silently drop a native-input request the act-then-wait path cannot honour. */
 export declare function assertNativeInputSupported(innerArgs: Record<string, unknown>): void;
+/**
+ * The agent's own declaration counts as the confirmation, for that one control.
+ *
+ * `reticle_act_and_wait { target: { role: "button", name: "Place order" }, until }` names the
+ * control by the very words the guard flags AND names the consequence before acting: asking again
+ * for `confirmDangerous` cost a round trip per step on a shop's ordinary path and protected nothing.
+ * A `ref` or `testid` does not count — neither says what the control does, and a stale ref is
+ * exactly how the wrong button gets pressed. A Harness call never takes this path: its outward
+ * guard decides alone.
+ */
+export declare function confirmedByDeclaration(innerArgs: Record<string, unknown>, target: unknown, declared: boolean): Record<string, unknown>;