@reticlehq/server 3.7.0 → 3.8.1

package/dist/surface/mcp/proxy/proxy-handshake.js

@@ -15,7 +15,7 @@
  * finally established (see `replayLines`), so the daemon still gets its handshake in order.
  */
 import { SERVER_VERSION } from '../../../command/version/identity/server-version.js';
-import { MCP_SERVER_NAME } from '@reticlehq/core';
+import { MCP_SERVER_NAME, WRITING_RULE_SHORT } from '@reticlehq/core';
 /** The version we answer with if the client proposed none. */
 const FALLBACK_PROTOCOL_VERSION = '2024-11-05';
 /**
@@ -28,7 +28,8 @@ const FALLBACK_PROTOCOL_VERSION = '2024-11-05';
  * connected, initialized and toolless until a human notices.
  */
 export const TOOLS_CHANGED_NOTIFICATION = 'notifications/tools/list_changed';
-function parseLine(line) {
+/** A line as a JSON-RPC object, or null when it is not JSON or not an object. */
+export function parseLine(line) {
     try {
         const parsed = JSON.parse(line);
         return 'object' === typeof parsed && parsed !== null ? parsed : null;
@@ -103,6 +104,8 @@ export function toolsChangedNotification(catalogWasLocal) {
         return null;
     return JSON.stringify({ jsonrpc: '2.0', method: TOOLS_CHANGED_NOTIFICATION });
 }
+/** Says that the degraded text is shorter than the healthy one. */
+const DEGRADED_OMITTED = 'This text omits the replay and argument notes.';
 /**
  * What a locally-answered handshake must say about itself.
  *
@@ -122,17 +125,23 @@ export function toolsChangedNotification(catalogWasLocal) {
  * 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.
+ * The healthy block is kept underneath: 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. Only its part up to the
+ * writing rule is kept. Claude Code shows about the first 4,096 characters, and the notice plus the
+ * whole block came to about 4,600, so the client cut the writing rule. The text says what it left
+ * out, so the cut is not silent.
  */
 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.
+    const ruleAt = healthy.indexOf(WRITING_RULE_SHORT);
+    const kept = -1 === ruleAt ? healthy : healthy.slice(0, ruleAt + WRITING_RULE_SHORT.length);
+    const omitted = kept.length < healthy.length ? `\n\n${DEGRADED_OMITTED}` : '';
+    return `DEGRADED SURFACE. READ THIS BEFORE ANY reticle_* CALL. No Reticle daemon answered on port ${String(port)} (${reason}). The Reticle MCP proxy answered this handshake, not the daemon. A tool list you got is from a cache or is empty: it proves nothing.
 
-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.
+Reticle IS installed: this process is Reticle. Do NOT report it as missing or not installed. 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.
+Your next reticle_* call starts a daemon. Then it works, or it fails with the reason. If you have NO reticle_* tools, tell the user that, and tell them to run \`npx @reticlehq/server doctor\` in a terminal. It shows what holds port ${String(port)} and if a daemon can start.
 
-${healthy}`;
+${kept}${omitted}`;
 }
 /**
  * The largest single JSON-RPC line the proxy will accumulate from a client.
@@ -190,3 +199,62 @@ export function drainLines(buffer, chunk, maxLineBytes = MAX_STDIN_LINE_BYTES, d
         discarding: restOversized,
     };
 }
+/** 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';
+const INITIALIZE_METHOD = 'initialize';
+const INITIALIZED_METHOD = 'notifications/initialized';
+/**
+ * Makes a reconnect invisible to the client.
+ *
+ * The daemon builds a FRESH `McpServer` per SSE connection, so a reconnected session has never seen
+ * the client's `initialize` — every subsequent `tools/call` would hit an uninitialized server. The
+ * proxy therefore remembers the handshake the client sent once and replays it into each new session.
+ * The replay is re-issued under a reserved id so the daemon's response to it can be dropped rather
+ * than reaching the client's stdout, where a duplicate JSON-RPC id would be a protocol violation.
+ */
+export class HandshakeReplay {
+    #initialize = null;
+    #initialized = null;
+    #pendingReplayId = null;
+    /** Record one outbound client line. Cheap enough to call for every stdin message. */
+    observeOutbound(line) {
+        const msg = parseLine(line);
+        if (null === msg) {
+            return;
+        }
+        // The first initialize is the session's identity; a client re-issuing one does not change it.
+        if (msg.method === INITIALIZE_METHOD && null === this.#initialize) {
+            this.#initialize = line;
+        }
+        else if (msg.method === INITIALIZED_METHOD) {
+            this.#initialized = line;
+        }
+    }
+    /** Lines to POST into a freshly-established session, before any queued client traffic. */
+    replayLines() {
+        if (null === this.#initialize) {
+            return [];
+        }
+        const msg = parseLine(this.#initialize);
+        if (null === msg) {
+            return [];
+        }
+        this.#pendingReplayId = RECONNECT_INITIALIZE_ID;
+        const reinit = { ...msg, id: RECONNECT_INITIALIZE_ID };
+        return null === this.#initialized
+            ? [JSON.stringify(reinit)]
+            : [JSON.stringify(reinit), this.#initialized];
+    }
+    /** True when this inbound daemon line is the echo of our replayed handshake and must not be forwarded. */
+    shouldSuppressInbound(line) {
+        if (null === this.#pendingReplayId) {
+            return false;
+        }
+        const msg = parseLine(line);
+        if (null === msg || msg.id !== this.#pendingReplayId) {
+            return false;
+        }
+        this.#pendingReplayId = null; // one response per replay — anything later is not ours to swallow
+        return true;
+    }
+}

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

@@ -1,5 +1,6 @@
 import { ReticleTool, WRITING_RULE_SHORT } from '@reticlehq/core';
 import { SHARED_PARAM_GUIDANCE } from './shared-params.js';
+import { wiringConsent } from '../tools/empty-session-list.js';
 import { defaultAdvertisedNames } from '../tools/tool-surface.js';
 import { surfaceVocabulary, listOf } from './surface-vocabulary.js';
 /**
@@ -35,8 +36,8 @@ import { surfaceVocabulary, listOf } from './surface-vocabulary.js';
  * `reticle gate` is FOLDED INTO the done sentence rather than given a paragraph, and that is the
  * budget rule working rather than a stylistic choice.
  *
- * The instruction block has a hard byte cap whose own note says a raise must be paid for with a
- * measurement, and that if one cannot be shown the right answer is to cut an older sentence. There
+ * The instruction block has a hard cap: about what a client shows of it (see the test). It cannot be
+ * raised, so a new sentence must cut an older one. There
  * is no measurement for `gate`: it is built, it has anti-reward-hacking, and it appeared in no
  * surface an agent reads, which is an argument and not a number. Cutting a measured sentence to
  * make room for an unmeasured one would be strictly worse. So it costs about a hundred characters
@@ -44,9 +45,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 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\`.
+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. Prefer ${v.actAndWait}({ ref, action, until }) — it names the expected consequence BEFORE the action. 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.${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.` : ''}
+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.` : ''}
 
 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,7 +78,7 @@ 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 — 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)}`;
+    return `Changed code? Replay before you drive. ${ask}${v.replayChange} replays them for one verified + because. "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
@@ -85,7 +86,7 @@ const replayFirst = (v) => {
  */
 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.`;
+    : ` Drivers: you, or the Harness (${v.explore}; opt-in, no setup score needed): poll its runId; never start two.`;
 /**
  * The first move, for a project no app has ever connected to.
  *
@@ -100,12 +101,27 @@ const driveOnce = (v) => 0 === v.explore.length
 // 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.
+const firstMoveFor = (v, appHere) => `FIRST: when this session started, no app had connected to Reticle in this project, so \`init\` has not wired it.${verifyNowFor(v)}
 
-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.';
+To wire it for good: ${wiringConsent()} ${v.sessions} changes no file. A session on this project's app listed there is the proof that it is wired.${appHere ? TELL_THE_USER : ''}`;
+/**
+ * A verdict before any wiring. The lead used to say that until the app was wired "no other tool can
+ * tell you anything about this app", which is false: the lease reads any running page with
+ * Reticle's own reader. Measured with `claude -p` on a fresh Vite app with the MCP registered and no
+ * `init`: the agent made no Reticle call and wrote, ran and deleted a Playwright script instead.
+ */
+// A real agent given no URL source started a second dev server beside the user's own.
+const urlFrom = (v) => '' === v.sessions
+    ? ''
+    : ` Get <URL> from next_step.lease in ${v.sessions}. Do not start a second dev server.`;
+function verifyNowFor(v) {
+    if ('' === v.zeroInstall)
+        return '';
+    return ` To check a change now, with no file changed: \`${v.zeroInstall}\` opens it in Reticle's own browser. Use it instead of writing a browser script.${urlFrom(v)}`;
+}
+const UNWIRED_LEAD_END = 'is the proof that it is wired.';
 // 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.';
+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 ask the consent question above.';
 /** 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, '');
@@ -133,13 +149,13 @@ export function localizeInstructions(instructions, appHere) {
  */
 const reachFor = (v) => {
     const lines = [
-        `${v.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. ${v.settle} settles a page that is changing without you; ${v.inspect} maps an element to its source file:line, which turns a finding into an edit${v.yield.length > 0 ? `; ${v.yield} hands the tab back to the human` : ''}.`,
+        `${v.observe} is the evidence channel: everything the page did since a cursor, in one read. Take it BEFORE you call a build broken. ${v.settle} settles a page that is changing without you; ${v.inspect} maps an element to its source file:line, which turns a finding into an edit${v.yield.length > 0 ? `; ${v.yield} hands the tab back to the human` : ''}.`,
     ];
     // Said ONLY when both halves are advertised. A catalogue with no way to invoke what it lists sends
     // the agent at a tool it cannot call and then off the product entirely — see
     // 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.`);
+        lines.push(`${v.coldTail} Two to know early: ${ReticleTool.RUN}({ tool: "${ReticleTool.CONTEXT}", args: {} }) returns what this run already established, and ${ReticleTool.RUN}({ tool: "${ReticleTool.INTENT}", args: { action: "declare", request: "<user's words, verbatim>" } }), once per request, declares what the work is MEANT to do.`);
         // 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)` : ''}.`);
@@ -147,7 +163,7 @@ const reachFor = (v) => {
     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: 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.`;
+const feedbackAsk = (v) => `Feedback is first-class: once per session, when Reticle broke, lied, missed something, cost too many calls, or the install, wiring or setup gave you trouble, send \`${v.feedback}\` and carry on. Tools unreachable? \`npx @reticlehq/server 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
@@ -179,9 +195,12 @@ export function buildServerInstructions(state) {
      * into a dead end.
      */
     const replay = replayFirst(v);
+    // The writing rule sits beside the feedback ask, the text it is most about, and not at the end:
+    // a client that cuts the block cuts the end first.
+    const feedback = `${feedbackAsk(v)}\n\n${WRITING_RULE_SHORT}`;
     const base = state.previouslyConnected
-        ? `${verdictDiscipline(v)}\n\n${reachFor(v)}\n\n${feedbackAsk(v)}`
-        : `${firstMove}\n\n${verdictDiscipline(v)}\n\n${feedbackAsk(v)}`;
+        ? `${verdictDiscipline(v)}\n\n${reachFor(v)}\n\n${feedback}`
+        : `${firstMove}\n\n${verdictDiscipline(v)}\n\n${feedback}`;
     const withReplay = replay.length > 0 ? `${base}\n\n${replay}` : base;
-    return `${withReplay}\n\n${SHARED_PARAM_GUIDANCE}\n\n${WRITING_RULE_SHORT}`;
+    return `${withReplay}\n\n${SHARED_PARAM_GUIDANCE}`;
 }

package/dist/surface/mcp/shared-params.d.ts

@@ -1,3 +1,4 @@
+import type { z } from 'zod';
 /**
  * Parameters that mean the same thing on every tool, documented ONCE instead of every turn.
  *
@@ -23,5 +24,12 @@
 export declare const SHARED_PARAM_SHORT: Readonly<Record<string, string>>;
 /** The full text, sent once at initialize. Everything trimmed above is restated here. */
 export declare const SHARED_PARAM_GUIDANCE: string;
+/**
+ * The short form for one parameter, or undefined when it keeps its own text.
+ *
+ * `since` is a cursor (a number) on every tool but `reticle_verify`, where it is a git ref. That one
+ * keeps its own description, so the cursor text never reaches a parameter that takes a ref.
+ */
+export declare function sharedParamShort(name: string, schema: z.ZodTypeAny): string | undefined;
 /** Is this a parameter whose guidance now lives in the instructions block? */
 export declare function isSharedParam(name: string): boolean;

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

@@ -22,7 +22,7 @@
 /** 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 act/observe, or a git ref.',
+    since: 'Cursor (a number) from a prior act or observe result.',
     limit: 'Cap descriptors to the first N.',
 };
 /** The full text, sent once at initialize. Everything trimmed above is restated here. */
@@ -30,6 +30,20 @@ export const SHARED_PARAM_GUIDANCE = 'Arguments that mean the same thing on ever
     '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, or a git ref when verifying a change. `limit` — caps returned descriptors.';
+/** A value only a string-typed `since` accepts. */
+const GIT_REF_PROBE = 'main';
+/**
+ * The short form for one parameter, or undefined when it keeps its own text.
+ *
+ * `since` is a cursor (a number) on every tool but `reticle_verify`, where it is a git ref. That one
+ * keeps its own description, so the cursor text never reaches a parameter that takes a ref.
+ */
+export function sharedParamShort(name, schema) {
+    if ('since' === name && schema.safeParse(GIT_REF_PROBE).success) {
+        return undefined;
+    }
+    return SHARED_PARAM_SHORT[name];
+}
 /** 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/sse-frame-parser.d.ts

@@ -17,3 +17,14 @@ export declare class SseFrameParser {
     #private;
     push(chunk: string): SseFrame[];
 }
+/**
+ * Turn an `endpoint` frame's data into a POST target, or null when there is nothing usable in it.
+ *
+ * An empty (or whitespace) data field is the shape a malformed daemon response takes, and it used to
+ * be accepted: `postUrl` became `''`, which is not `null`, so the proxy considered itself CONNECTED
+ * and posted every subsequent message to the empty string. Each one failed, the queue never armed
+ * its deadline because nothing was ever queued, and the agent held a session that could not carry a
+ * single call. Refusing the frame keeps the proxy in its disconnected path, which already knows how
+ * to reconnect and how to answer what it cannot send.
+ */
+export declare function buildSessionUrl(rawData: string, port: number): string | null;

package/dist/surface/mcp/sse-frame-parser.js

@@ -1,3 +1,4 @@
+import { LOOPBACK_HOST } from '@reticlehq/core';
 /**
  * Incremental SSE frame parser for the MCP front door.
  *
@@ -39,3 +40,20 @@ export class SseFrameParser {
         return frames;
     }
 }
+/**
+ * Turn an `endpoint` frame's data into a POST target, or null when there is nothing usable in it.
+ *
+ * An empty (or whitespace) data field is the shape a malformed daemon response takes, and it used to
+ * be accepted: `postUrl` became `''`, which is not `null`, so the proxy considered itself CONNECTED
+ * and posted every subsequent message to the empty string. Each one failed, the queue never armed
+ * its deadline because nothing was ever queued, and the agent held a session that could not carry a
+ * single call. Refusing the frame keeps the proxy in its disconnected path, which already knows how
+ * to reconnect and how to answer what it cannot send.
+ */
+export function buildSessionUrl(rawData, port) {
+    const trimmed = rawData.trim();
+    if ('' === trimmed) {
+        return null;
+    }
+    return trimmed.startsWith('/') ? `http://${LOOPBACK_HOST}:${port}${trimmed}` : trimmed;
+}

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

@@ -43,6 +43,8 @@ export interface SurfaceVocabulary {
     heal: string;
     /** Start or poll a Harness drive, or empty when the surface cannot reach it. */
     explore: string;
+    /** Open the running app with Reticle's own reader and no file changed, or empty. */
+    zeroInstall: 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

@@ -9,6 +9,18 @@ function callOf(advertised, direct, parent, action) {
     // slot costs a capability the agent has to discover; a wrong name costs the whole product.
     return '';
 }
+// The URL is the one the session list names. A bare "<the running app's URL>" sent a real agent to
+// start a second dev server on a port it chose, beside the user's own.
+const ZERO_INSTALL_ARGS = `{ action: "acquire", url: "<URL>" }`;
+/** The zero-install lease, direct where it is advertised, through `reticle_run` where that is. */
+function zeroInstallCall(advertised) {
+    if (advertised.has(ReticleTool.LEASE))
+        return `${ReticleTool.LEASE} ${ZERO_INSTALL_ARGS}`;
+    if (advertised.has(ReticleTool.RUN)) {
+        return `${ReticleTool.RUN}({ tool: "${ReticleTool.LEASE}", args: ${ZERO_INSTALL_ARGS} })`;
+    }
+    return '';
+}
 /** Drop the empty slots, so a sentence never reads "look (), find ()". */
 export function listOf(...calls) {
     return calls.filter((call) => call.length > 0).join(' / ');
@@ -53,5 +65,6 @@ export function surfaceVocabulary(advertisedNames) {
         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'),
+        zeroInstall: zeroInstallCall(advertised),
     };
 }

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

@@ -35,6 +35,8 @@ export declare class ToolCatalogCache {
     #private;
     /** Watch a line coming BACK from the daemon; remember it if it is a tool catalog. */
     observe(line: string): void;
+    /** Hold a list that did not come from the daemon: the static catalog, while the daemon starts. */
+    remember(tools: unknown[]): void;
     has(): boolean;
     /**
      * A response to `request` from the cached catalog, or null when this is not a tools/list request or

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

@@ -53,8 +53,15 @@ export class ToolCatalogCache {
     observe(line) {
         const msg = parse(line);
         const tools = msg?.result?.tools;
-        if (Array.isArray(tools) && tools.length > 0)
+        if (Array.isArray(tools) && tools.length > 0) {
             this.#tools = tools;
+        }
+    }
+    /** Hold a list that did not come from the daemon: the static catalog, while the daemon starts. */
+    remember(tools) {
+        if (tools.length > 0) {
+            this.#tools = tools;
+        }
     }
     has() {
         return this.#tools !== undefined;
@@ -65,13 +72,16 @@ export class ToolCatalogCache {
      * id is not an answer, it is noise the client will never match.
      */
     answer(request) {
-        if (this.#tools === undefined)
+        if (this.#tools === undefined) {
             return null;
+        }
         const msg = parse(request);
-        if (msg?.method !== LIST_METHOD)
+        if (msg?.method !== LIST_METHOD) {
             return null;
-        if (msg.id === undefined || null === msg.id)
+        }
+        if (msg.id === undefined || null === msg.id) {
             return null;
+        }
         return JSON.stringify({ jsonrpc: '2.0', id: msg.id, result: { tools: this.#tools } });
     }
 }

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

@@ -1,11 +1,10 @@
 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 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.";
     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 unreachable: (url: string | undefined) => string;
     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;
@@ -16,6 +15,8 @@ export interface AccountInput {
     dashboardUrl?: string;
     /** The platform's `/v1/model/config` answer; undefined when unlinked, null when it did not answer. */
     platform: Record<string, unknown> | null | undefined;
+    /** Where the linked cloud is, said when it does not answer. */
+    cloudUrl?: string;
 }
 /** The facts and the next step. Pure: the tool's I/O is in `readAccount`. */
 export declare function accountFacts(input: AccountInput): Record<string, unknown>;

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

@@ -1,15 +1,15 @@
 /**
  * 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,
+ * reports to the dashboard, the plan and credits left, whether Reticle Harness is on,
  * 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.
+ * plan and credits), so the agent and the HUD cannot disagree. No setup score gates the Harness.
  */
 import { z } from 'zod';
-import { ReticleTool, asRecord, asString } from '@reticlehq/core';
+import { CONNECT_COMMAND, 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';
@@ -17,16 +17,13 @@ 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.',
+    SIGN_IN: `The user is not signed in to Reticle. Ask them to run \`${CONNECT_COMMAND}\` in the app folder: it signs them in and links this project.`,
+    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 \`${CONNECT_COMMAND}\` in the app folder.`,
+    unreachable: (url) => `Reticle Cloud${url === undefined ? '' : ` at ${url}`} did not answer, so credits and the Harness are not known now. ` +
+        'The project is still linked: ask the user to check the connection, then read the account again. 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>" }' +
@@ -49,7 +46,7 @@ export function accountFacts(input) {
     if (input.platform === undefined)
         return { ...base, next: ACCOUNT_NEXT.LINK };
     if (null === input.platform)
-        return { ...base, next: ACCOUNT_NEXT.UNREACHABLE };
+        return { ...base, next: ACCOUNT_NEXT.unreachable(input.cloudUrl) };
     const p = input.platform;
     const rawCredits = asRecord(p['credits']);
     const used = num(rawCredits['used']);
@@ -74,18 +71,10 @@ export function accountFacts(input) {
     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 }) } }),
@@ -98,19 +87,15 @@ export function accountFacts(input) {
     };
     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);
+        : !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;
+async function platformConfig(platform) {
     if (null === platform)
         return undefined;
     try {
@@ -138,17 +123,21 @@ async function readAccount(deps, sessionId) {
     const snapshot = impactSnapshot(root);
     const account = snapshot?.account;
     const dashboardUrl = root === undefined ? undefined : readDashboardUrl(root);
+    // The tab's own project's link, as the Harness reads it: the daemon's own folder may be unlinked
+    // (or another project) while the tab's is linked, and the answer was "press Link this project".
+    const platform = (await deps.linkedCloud?.(root).catch(() => null)) ?? null;
     return accountFacts({
         signedIn: true === account?.signedIn,
         ...(account?.org === undefined ? {} : { workspace: account.org }),
         ...(dashboardUrl === undefined ? {} : { dashboardUrl }),
-        platform: await platformConfig(deps),
+        platform: await platformConfig(platform),
+        ...(null === platform ? {} : { cloudUrl: platform.url }),
     });
 }
 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.',
+        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, 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.'),
         },

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

@@ -1,4 +1,6 @@
 import { ActionType } from '@reticlehq/core';
+/** A Harness call goes to a payment provider's origin only when its journey asked to pay. */
+export declare function assertNotPaymentNavigation(url: string): void;
 export declare function assertNotDestructive(action: ActionType, innerArgs: Record<string, unknown>, inspected: unknown): void;
 /**
  * A drag is judged on BOTH ends. Dropping a harmless row onto "Delete" is destructive, and the