@reticlehq/server 2.6.0 → 2.7.0

package/dist/init/snippets.js

@@ -50,7 +50,7 @@ export function nextReticleDevFile(port, projectId, testids = [], stores = []) {
     const fields = '' === base ? '' : `${base.slice(1, -1).trim()}, `;
     const ids = testids.map((t) => `'${t}'`).join(', ');
     const storeBlock = 0 === stores.length
-        ? '      // No state library detected. If you add one, register it here — see docs/usage.md.'
+        ? '      // No state library detected. If you add one, register it here — see node_modules/@reticlehq/server/docs/usage.md.'
         : stores.map((h) => `      // import your store, then: ${h}`).join('\n');
     return `'use client';
 import { useEffect } from 'react';
@@ -174,7 +174,7 @@ Start the daemon BEFORE \`astro dev\`, so the token file exists when the config
 export function viteDevModuleFile(testids, stores) {
     const ids = testids.map((t) => `'${t}'`).join(', ');
     const storeBlock = 0 === stores.length
-        ? '  // No state library detected. If you add one, register it here — see docs/usage.md.'
+        ? '  // No state library detected. If you add one, register it here — see node_modules/@reticlehq/server/docs/usage.md.'
         : stores.map((h) => `  // import your store, then: ${h}`).join('\n');
     return `// Dev-only. Imported automatically by @reticlehq/vite-plugin — you do not need to import it.
 // Self-guards on import.meta.env.DEV, so it is a no-op in a production build.
@@ -216,8 +216,22 @@ export const NEXT_LAYOUT_MANUAL = `Mount <ReticleDev /> in your root layout (app
  * where a bare `@reticlehq/react` import resolves. A bare import in a plain index.html does NOT resolve in
  * the browser, so we never tell a bundled app to do that (the old advice silently failed for CRA).
  */
-export function htmlManual(port, projectId) {
-    const arg = connectArg(port, projectId);
+export function htmlManual(port, projectId, pairingToken) {
+    const base = connectArg(port, projectId);
+    // The token belongs INSIDE the call the user pastes. Every other stack has a build step to inline
+    // it (the Vite plugin's `define`, Next's NEXT_PUBLIC_*, Astro's config, CRA's .env); this path has
+    // none, so `init` inlines the literal it already read. Without it the bridge closes the socket
+    // with AUTH_FAILED and no session ever appears — see Bridge's hello handler.
+    const withToken = pairingToken === undefined || 0 === pairingToken.length
+        ? base
+        : `{ ${[base.length > 0 ? base.slice(1, -1).trim() : '', `token: '${pairingToken}'`]
+            .filter((p) => p.length > 0)
+            .join(', ')} }`;
+    const tokenNote = pairingToken === undefined || 0 === pairingToken.length
+        ? ''
+        : `\n\n  The \`token\` is this machine's pairing token, read from ~/.reticle/pairing-token. Keep it: the
+  bridge REJECTS a connect without it ("authentication failed") and no session appears. It is
+  per-machine and local-only, so do not commit it — a teammate's daemon mints their own.`;
     return `No Vite/Next plugin detected — wire the dev-only connect by hand. Pick the form for your setup:
 
   • Bundled app (Create React App, webpack, Parcel, Vue/Svelte CLI, etc.) — add to your ENTRY module
@@ -226,9 +240,9 @@ export function htmlManual(port, projectId) {
       if (window.location.hostname === 'localhost') {
         void import('@reticlehq/react').then(({ reticle, install }) => {
           install();
-          reticle.connect(${arg});
+          reticle.connect(${withToken});
         });
-      }
+      }${tokenNote}
 
   • Plain static HTML with no build step — the browser can't resolve the bare '@reticlehq/react' import, so
     bundle the SDK once (e.g. \`npx esbuild\`) and point a dev-only <script type="module"> at the output,
@@ -282,6 +296,57 @@ declare const __RETICLE_ROOT__: string | undefined;
 declare const __RETICLE_SDK_VERSION__: string | undefined;
 `;
 }
+/** Where a Nuxt dev-only client plugin belongs. `.client` keeps it out of SSR; Nuxt auto-registers it. */
+export const NUXT_PLUGIN_PATH = 'app/plugins/reticle.client.ts';
+/**
+ * The Nuxt recipe, written out in full because every trap in it is one somebody actually hit.
+ *
+ * Reported from the field, in the order they were hit: `init` classified a Nuxt 4 app as `html`, so
+ * it installed a package named `@reticlehq/react` (with `react` in its peer dependencies) into a Vue
+ * codebase — the reporter only continued after auditing our dist to confirm there are no React
+ * imports at runtime, which most people will not do. It then handed over a snippet guarded on
+ * `window.location.hostname === 'localhost'`, which fails twice over in Nuxt: `window` does not
+ * exist during SSR, and the dev host here was a hosts-file alias (required for the backend's
+ * white-label origin detection), so the guard was false and the connect never ran — no error, no log
+ * line, nothing to debug. And nothing said a running dev server does not pick up a new plugin.
+ *
+ * So: `import.meta.dev` (build-time, host-independent) instead of a hostname check, `.client.ts`
+ * instead of an SSR guard, the framework-neutral sensor instead of the React kit, the non-localhost
+ * flag named up front, and the restart said out loud.
+ */
+export function nuxtManual(port, projectId) {
+    const base = connectArg(port, projectId);
+    const fields = '' === base ? '' : base.slice(1, -1).trim();
+    const connect = '' === fields ? 'reticle.connect()' : `reticle.connect({ ${fields} })`;
+    return `Nuxt owns its own Vite instance and renders its own HTML, so there is no vite.config to patch
+and no index.html to inject into. Wire it with a dev-only CLIENT plugin, which is Nuxt's own idiom:
+
+1. Create ${NUXT_PLUGIN_PATH}:
+
+     export default defineNuxtPlugin(() => {
+       // import.meta.dev is the correct guard: it is resolved at build time, so it does not care
+       // what hostname you develop on. Do NOT guard on window.location.hostname === 'localhost' —
+       // that is false on any hosts-file alias or LAN address, and window does not exist in SSR.
+       if (!import.meta.dev) return
+       void import('@reticlehq/browser').then(({ reticle }) => {
+         ${connect}
+       })
+     })
+
+   The .client.ts suffix is load-bearing: it is what keeps this out of the server bundle.
+
+2. Restart the dev server. A dev server that is already running does not pick up a new plugin —
+   it will not appear in .nuxt/plugins/client.mjs, and the app will come up with no SDK at all.
+
+3. If your dev host is anything other than localhost (a hosts-file alias, a LAN IP, a tunnel), add
+   allowNonLocalhost: true to that connect call. Without it the SDK loads and then refuses, and the
+   only sign is one line in the browser console.
+
+The package is @reticlehq/browser — the framework-neutral sensor. DOM, network, console, routing and
+source file:line all work in Vue. What you do not get is React component identity, which is the only
+thing the React adapter adds. There is no Nuxt app in this project's CI, so this path is UNVERIFIED:
+if something does not work, please open an issue.`;
+}
 /**
  * Root-level project config for Reticle. Written by `reticle init`; read by `reticle mcp` for the port
  * and by tooling for the stable projectId (the app's identity across port changes).

package/dist/mcp/mcp-proxy.js

@@ -8,7 +8,7 @@ import { join } from 'node:path';
 import { LOOPBACK_HOST, MCP_SSE_PATH, ReticleDir, ReticleEnv, CONTRACT_FINGERPRINT, } from '@reticlehq/core';
 import { SERVER_VERSION } from '../version/server-version.js';
 import { PEER_VERSION_PARAM, PEER_CONTRACT_PARAM } from '../version/peer-announce.js';
-import { onStreamDrop, onClientRequest, onReconnectBudgetSpent, OnDrop, OnRequest, } from './proxy-lifecycle.js';
+import { onStreamDrop, onClientRequest, onReconnectBudgetSpent, onQueueExpired, OnDrop, OnRequest, } from './proxy-lifecycle.js';
 import { log } from '../log.js';
 import { OutageStage, reportMcpOutage } from './mcp-outage.js';
 const DEFAULT_DAEMON_READY_TIMEOUT_MS = 10_000;
@@ -441,9 +441,16 @@ ensureDaemon) {
                 stdinQueue.splice(0);
                 for (const reply of streamLossReplies(pending, 'no daemon could be reached'))
                     emit(reply);
+                // The expiry is the proof that the reconnect we believed was in flight is not coming — a
+                // wedged port accepts the socket and never serves SSE, so `connect` neither resolves nor
+                // rejects and `dormant` would otherwise stay false forever. Going dormant is what makes the
+                // NEXT request re-probe the port instead of queueing behind a reconnect that will never
+                // land, and it is the only path by which a daemon started AFTER we gave up is ever found.
+                dormant = onQueueExpired() === OnDrop.DORMANT;
                 proxyLog('reticle_mcp_proxy_queue_expired', {
                     port,
-                    note: 'answered queued requests instead of holding them for a daemon that never arrived',
+                    dormant,
+                    note: 'answered queued requests and went dormant; the next client request re-probes the port',
                 });
             }, QUEUE_WAIT_MS);
             queueTimer.unref();
@@ -518,7 +525,7 @@ ensureDaemon) {
             attempts++;
             // Once per process: this session has now lost its tools at least once, which is the number
             // that says whether the transport work actually landed for real users. `pendingLost` is the
-            // part an agent can FEEL — 320 of 321 measured drops killed nothing in flight.
+            // part an agent can FEEL — almost every measured drop killed nothing in flight.
             reportMcpOutage(OutageStage.FIRST, { reason, attempts, pendingLost });
             // The severe stage: we are about to stop retrying. Reported so the share of sessions where
             // MCP never came back on its own is a number rather than an anecdote.

package/dist/mcp/mcp.js

@@ -18,6 +18,7 @@ import { SERVER_VERSION } from '../version/server-version.js';
 import { MCP_SERVER_NAME } from '../init/mcp.js';
 import { setMcpClientNameHook } from '../telemetry/feedback-context.js';
 import { getSessionMetrics } from '../telemetry/session-metrics.js';
+import { parsePredicate } from '../events/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
@@ -272,6 +273,17 @@ export function installFriendlyArgErrors(server, examples, allowedKeys = new Map
             // McpError.message already carries "MCP error -32602: "; re-wrapping would print it twice.
             const raw = error instanceof Error ? error.message : String(error);
             const detail = raw.replace(/^MCP error -?\d+:\s*/, '');
+            // A malformed PREDICATE gets the sentence, not the array. The SDK validates tool input against
+            // the same zod schema and throws a serialized issue list — so the readable message
+            // `parsePredicate` exists to produce was being generated only on paths that never run over
+            // MCP, which is every path a real agent uses. Found by driving a live app: `reticle_assert`
+            // answered a near-miss predicate with a raw zod array naming the unknown keys and not one
+            // field that would have worked. It already carries its own guidance, so the generic example is
+            // dropped rather than argued with.
+            const predicateHelp = predicateMessage(args);
+            if (predicateHelp !== undefined) {
+                throw new McpError(ErrorCode.InvalidParams, predicateHelp);
+            }
             const example = examples.get(toolName);
             const help = example === undefined
                 ? ` Call reticle_tools { names: ["${toolName}"] } for its parameters.`
@@ -280,6 +292,29 @@ export function installFriendlyArgErrors(server, examples, allowedKeys = new Map
         }
     };
 }
+/**
+ * The readable reason a predicate argument did not parse, or undefined when the predicate is fine.
+ *
+ * Undefined matters as much as the message: a call can fail validation for a reason that has nothing
+ * to do with the predicate (a bad `timeout_ms`, a missing `ref`), and replacing that error with a
+ * predicate explanation would be confidently wrong. Re-parsing is the honest test — if it parses,
+ * the predicate is not what broke.
+ */
+function predicateMessage(args) {
+    if (typeof args !== 'object' || null === args)
+        return undefined;
+    const record = args;
+    const predicate = record['predicate'] ?? record['until'];
+    if (predicate === undefined)
+        return undefined;
+    try {
+        parsePredicate(predicate);
+        return undefined;
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : undefined;
+    }
+}
 /**
  * Answer a call for a real-but-un-advertised tool with the way to make it work.
  *

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

@@ -44,6 +44,25 @@ export declare function onStreamDrop(daemonListening: boolean): OnDrop;
  * whether the server survives.
  */
 export declare function onReconnectBudgetSpent(): OnDrop;
+/**
+ * What to do when queued requests expire with nothing connected. Always DORMANT.
+ *
+ * This is the hole that produced the worst report we have had: a first-run daemon came up wedged, the
+ * proxy spent its budget against it, and from then on every call returned −32001 — including after
+ * the human killed the wedged process and started a healthy daemon on the same port. The proxy never
+ * looked again.
+ *
+ * The cause is a state that lies. `WAKE` clears `dormant` and starts a reconnect; if that reconnect
+ * neither resolves nor rejects (exactly what a wedged port does — it accepts the socket and never
+ * serves SSE), `dormant` stays false forever. Every later request then reads as "a reconnect is
+ * already coming" and QUEUEs, the queue expires, and the request is answered with a failure. Nothing
+ * in that loop ever re-probes the port, so a daemon that appears afterwards is invisible.
+ *
+ * Expiring the queue is the proof that the in-flight reconnect is not coming. Going dormant makes the
+ * NEXT client request wake and re-probe — which is the only thing that can discover a daemon that
+ * arrived late, and it costs nothing when one has not.
+ */
+export declare function onQueueExpired(): OnDrop;
 /** What to do with a client message. */
 export declare const OnRequest: {
     /** Connected — post it straight through. */

package/dist/mcp/proxy-lifecycle.js

@@ -47,6 +47,27 @@ export function onStreamDrop(daemonListening) {
 export function onReconnectBudgetSpent() {
     return OnDrop.DORMANT;
 }
+/**
+ * What to do when queued requests expire with nothing connected. Always DORMANT.
+ *
+ * This is the hole that produced the worst report we have had: a first-run daemon came up wedged, the
+ * proxy spent its budget against it, and from then on every call returned −32001 — including after
+ * the human killed the wedged process and started a healthy daemon on the same port. The proxy never
+ * looked again.
+ *
+ * The cause is a state that lies. `WAKE` clears `dormant` and starts a reconnect; if that reconnect
+ * neither resolves nor rejects (exactly what a wedged port does — it accepts the socket and never
+ * serves SSE), `dormant` stays false forever. Every later request then reads as "a reconnect is
+ * already coming" and QUEUEs, the queue expires, and the request is answered with a failure. Nothing
+ * in that loop ever re-probes the port, so a daemon that appears afterwards is invisible.
+ *
+ * Expiring the queue is the proof that the in-flight reconnect is not coming. Going dormant makes the
+ * NEXT client request wake and re-probe — which is the only thing that can discover a daemon that
+ * arrived late, and it costs nothing when one has not.
+ */
+export function onQueueExpired() {
+    return OnDrop.DORMANT;
+}
 /** What to do with a client message. */
 export const OnRequest = {
     /** Connected — post it straight through. */

package/dist/pool/playwright-launcher.js

@@ -8,6 +8,7 @@
 import { BrowserLaunchKind } from '@reticlehq/core';
 import { getSessionMetrics } from '../telemetry/session-metrics.js';
 import { classifyConnectFailure } from '../telemetry/connect-failure.js';
+import { chromiumInstallCommand, bundledPlaywrightVersion } from '../cli/chromium-hint.js';
 /**
  * How a leased tab navigates. Pure, and exported, because the decision in it is worth a test while
  * the rest of this file needs a real Chromium.
@@ -48,8 +49,15 @@ function wrapBrowser(browser) {
         onDisconnected: (handler) => browser.on('disconnected', handler),
     };
 }
-/** The fix for the most common first-run failure: Chromium isn't installed for Playwright. */
-const CHROMIUM_MISSING_HINT = 'Chromium is not installed for Playwright. Run: npx playwright install chromium';
+/**
+ * The fix for the most common first-run failure: Chromium isn't installed for Playwright.
+ *
+ * Pinned to the playwright this process bundles. Unpinned, `npx` fetches the latest playwright and
+ * installs ITS browser revision — a build this launcher will never look at — so the user follows the
+ * advice, it succeeds, and the next launch fails identically. Shares one builder with `doctor` so the
+ * two cannot suggest different commands for the same missing browser.
+ */
+const CHROMIUM_MISSING_HINT = `Chromium is not installed for Playwright. Run: ${chromiumInstallCommand(bundledPlaywrightVersion())}`;
 /** A Launcher that boots a real headless Chromium and adapts it to the pool's interface. */
 export function playwrightLauncher(opts = {}) {
     const headless = opts.headless ?? true;

package/dist/session/live-control-tools.js

@@ -93,12 +93,37 @@ export const LIVE_CONTROL_TOOLS = [
         description: 'Drain and return any messages the human queued from the panel since the last poll. Use to ' +
             'explicitly check for human guidance without acting.',
         inputSchema: { ...sessionIdShape },
-        outputSchema: { messages: z.array(z.unknown()) },
+        outputSchema: {
+            messages: z.array(z.unknown()),
+            delivered: z
+                .array(z.unknown())
+                .optional()
+                .describe('Present ONLY when this poll found nothing new but the human HAS spoken this session: everything they said, including what was already handed to you inline on an earlier tool result. An empty `messages` never means silence.'),
+        },
         handler: (deps, args) => {
             const session = deps.sessions.resolve(asString(args['sessionId']));
+            const messages = session.drainInbox();
+            if (messages.length > 0)
+                return Promise.resolve({ messages });
+            // Nothing NEW is not the same as nothing said. The inbox has two consumers — this poll and the
+            // control envelope spliced onto every tool result — and delivery is destructive, so a message
+            // handed over inline moments ago left this call reporting an empty queue with a note that read
+            // as "the human has said nothing". Reported from the field, from both ends: the agent believed
+            // it, and the person who typed the message got silence with no sign it had been seen.
+            const history = session.inboxHistory();
+            if (history.length > 0) {
+                return Promise.resolve({
+                    messages,
+                    delivered: [...history],
+                    note: `nothing NEW since your last poll — but the human has sent ` +
+                        `${String(history.length)} message(s) this session, listed in \`delivered\`. They were ` +
+                        `handed to you inline on an earlier tool result, which is why this queue is empty. An ` +
+                        `empty \`messages\` never means the human has said nothing.`,
+                });
+            }
             // An empty inbox and a panel that is not wired both return `[]`. The first means the human has
             // said nothing; the second means an agent is waiting on a channel that does not exist.
-            return Promise.resolve(noteEmptyRead({ messages: session.drainInbox() }, 'messages', {
+            return Promise.resolve(noteEmptyRead({ messages }, 'messages', {
                 noun: 'messages from the human since the last poll',
             }));
         },
@@ -126,16 +151,26 @@ export const LIVE_CONTROL_TOOLS = [
             marks: z.array(z.unknown()),
             pendingCount: z.number(),
             resolved: z.boolean().optional(),
+            resolvedNote: z
+                .string()
+                .optional()
+                .describe('The note on the mark that was actually retired. CHECK IT against the mark you meant to resolve: a bare `resolved:true` cannot tell you it closed the right one, and ids are only meaningful while the session that issued them lives.'),
         },
         handler: (deps, args) => {
             const session = deps.sessions.resolve(asString(args['sessionId']));
             const resolveId = asString(args['resolve']);
             let resolved;
+            let resolvedNote;
             if (resolveId !== undefined) {
                 // Grab the note BEFORE retiring it so we can close the loop visually for the human.
                 const mark = session.allMarks().find((m) => m.id === resolveId);
                 resolved = session.resolveMark(resolveId);
                 if (resolved && mark !== undefined) {
+                    // Echoed back to the CALLER too, not only to the panel. A bare `resolved:true` is equally
+                    // consistent with "I retired the bug you fixed" and "I retired somebody else's", and an
+                    // agent hit exactly that — it closed a mark the human had recorded minutes later while
+                    // the two it had actually fixed vanished with no record.
+                    resolvedNote = mark.note;
                     // The human watching the panel sees their flagged bug get marked fixed (fire-and-forget).
                     session.pushNarration(`✓ fixed: ${mark.note}`);
                 }
@@ -148,6 +183,8 @@ export const LIVE_CONTROL_TOOLS = [
             };
             if (resolved !== undefined)
                 out.resolved = resolved;
+            if (resolvedNote !== undefined)
+                out.resolvedNote = resolvedNote;
             return Promise.resolve(out);
         },
     },

package/dist/session/live-control.d.ts

@@ -4,15 +4,6 @@ export interface InboxMessage {
     text: string;
     t: number;
 }
-/**
- * The human-in-the-loop half of a session: its lifecycle state, and the one-way inbox a person uses
- * to talk to the agent driving their browser.
- *
- * Server-owned on purpose — a paused session has to stay paused even if the page reloads, so this
- * cannot live in the tab. Split out of Session because it shares nothing with the transport, the
- * ring buffer, or the journal: it is state a HUMAN changes, on a human's timescale, while everything
- * else in Session is driven by the event stream.
- */
 export declare class LiveControl {
     #private;
     state(): SessionState;
@@ -22,6 +13,13 @@ export declare class LiveControl {
     setState(next: SessionState): void;
     /** Queue a human note. Empty/whitespace-only text is ignored so a stray enter cannot spam the agent. */
     push(text: string, t: number): void;
+    /**
+     * Everything the human has said this session, including what has already been delivered.
+     *
+     * Read-only and non-destructive by design — this is the answer to "did the human say anything
+     * while I was away", which a destructive drain can never give twice.
+     */
+    history(): readonly InboxMessage[];
     /** Return the queued notes AND clear them — delivered once, so a hint never repeats. */
     drain(): InboxMessage[];
     /** Diagnostic read of the inbox depth (does not clear). */

package/dist/session/live-control.js

@@ -8,9 +8,29 @@ import { HumanControlKind, SessionState } from '@reticlehq/core';
  * ring buffer, or the journal: it is state a HUMAN changes, on a human's timescale, while everything
  * else in Session is driven by the event stream.
  */
+/**
+ * How many delivered messages a session remembers.
+ *
+ * Enough that an agent picking up a long session can see what was said; bounded because a session
+ * can run for hours and this is a convenience, not a record.
+ */
+const HISTORY_CAP = 200;
 export class LiveControl {
     #state = SessionState.ACTIVE;
     #inbox = [];
+    /**
+     * Everything the human has said this session, delivered or not.
+     *
+     * The inbox has TWO consumers — the control envelope on every tool result, and the explicit
+     * message poll — and `drain` is destructive, so whichever ran first took the message and the other
+     * reported an empty queue. That produced a confident "no messages from the human since the last
+     * poll" about a message the human had definitely sent, with no way for the agent to tell the
+     * difference and no acknowledgement for the person who typed it.
+     *
+     * Delivered-once stays: a guidance hint that repeats every turn is noise. This only stops the
+     * delivery from being the same event as the forgetting.
+     */
+    #history = [];
     state() {
         return this.#state;
     }
@@ -29,7 +49,20 @@ export class LiveControl {
         const trimmed = text.trim();
         if (0 === trimmed.length)
             return;
-        this.#inbox.push({ text: trimmed, t });
+        const message = { text: trimmed, t };
+        this.#inbox.push(message);
+        this.#history.push(message);
+        if (this.#history.length > HISTORY_CAP)
+            this.#history.splice(0, this.#history.length - HISTORY_CAP);
+    }
+    /**
+     * Everything the human has said this session, including what has already been delivered.
+     *
+     * Read-only and non-destructive by design — this is the answer to "did the human say anything
+     * while I was away", which a destructive drain can never give twice.
+     */
+    history() {
+        return this.#history;
     }
     /** Return the queued notes AND clear them — delivered once, so a hint never repeats. */
     drain() {

package/dist/session/no-session-diagnosis.d.ts

@@ -1,10 +1,10 @@
 /**
  * Turning "no browser session connected" from a dead end into a next action.
  *
- * This is the most consequential sentence in the product. Measured over a day of telemetry: 74% of
- * sessions never call a Reticle tool, and of the ones that do, half make exactly ONE call — usually
- * `reticle_sessions` — and stop. Ten of those thirteen never touched a browser, and every recorded
- * session error is this one. The agent asks whether anything is connected, is told no, and leaves.
+ * This is the most consequential sentence in the product. Most sessions never call a Reticle tool at
+ * all, and of the ones that do, a large share make exactly ONE call — usually `reticle_sessions` —
+ * and stop. Almost none of those ever touched a browser, and this is the session error they hit. The
+ * agent asks whether anything is connected, is told no, and leaves.
  *
  * The old message asked the agent to check two things it cannot see from where it stands ("is your
  * app running with the SDK enabled?", "does it point at this port?"). The daemon can actually tell

package/dist/session/no-session-diagnosis.js

@@ -1,10 +1,10 @@
 /**
  * Turning "no browser session connected" from a dead end into a next action.
  *
- * This is the most consequential sentence in the product. Measured over a day of telemetry: 74% of
- * sessions never call a Reticle tool, and of the ones that do, half make exactly ONE call — usually
- * `reticle_sessions` — and stop. Ten of those thirteen never touched a browser, and every recorded
- * session error is this one. The agent asks whether anything is connected, is told no, and leaves.
+ * This is the most consequential sentence in the product. Most sessions never call a Reticle tool at
+ * all, and of the ones that do, a large share make exactly ONE call — usually `reticle_sessions` —
+ * and stop. Almost none of those ever touched a browser, and this is the session error they hit. The
+ * agent asks whether anything is connected, is told no, and leaves.
  *
  * The old message asked the agent to check two things it cannot see from where it stands ("is your
  * app running with the SDK enabled?", "does it point at this port?"). The daemon can actually tell
@@ -30,12 +30,12 @@ const RETRY = SELF_RECOVERING_MARKER;
  * The way out that needs no human at all.
  *
  * `reticle_lease` opens a browser Reticle drives itself, instead of waiting for somebody's tab to
- * dial in. Measured over a day of telemetry it is the single strongest predictor of a session that
- * works: the 5 sessions that used it had a MEDIAN of 30 tool calls and produced 46% of every bug
- * found, against a median of 1 call for the 20 active sessions that did not — and not one
- * single-call bounce used one. It is also advertised on no profile except `full`, so an agent only
- * ever finds it if it already knew it existed. Naming it HERE puts it in front of the agent at the
- * one moment it is the answer, and costs nothing on the turns when it is not.
+ * dial in. In the field it is the single strongest predictor of a session that works: sessions that
+ * use it drive an order of magnitude more tool calls than those that do not, they account for a
+ * disproportionate share of every bug found, and no single-call bounce has ever used one. It is also
+ * advertised on no profile except `full`, so an agent only ever finds it if it already knew it
+ * existed. Naming it HERE puts it in front of the agent at the one moment it is the answer, and
+ * costs nothing on the turns when it is not.
  *
  * Only offered when the app is known to carry the SDK: leasing an uninstrumented app just burns a
  * browser and comes back `ready:false`.
@@ -51,15 +51,23 @@ const SELF_SERVE = 'You do not have to wait for the human: reticle_lease {action
  * evidence that was never gathered.
  */
 /**
- * The second half of the answer for a project that never went through `init`.
+ * The one cause that produces a PERFECTLY healthy everything and still never connects.
  *
- * Held separately because it must appear ONLY when the project is uninstrumented — telling a wired
- * project to re-run `init` sends the reader back to a step that already succeeded, which is its own
- * kind of wrong answer.
+ * The SDK refuses to dial from a page that is not on localhost unless `allowNonLocalhost` is set.
+ * That is deliberate — Reticle must not be reachable from a page it does not trust — but the refusal
+ * happens page-side, so the daemon sees only silence, `doctor` sees only a healthy daemon, and every
+ * checklist item passes. Reported from the field by an agent on a hosts-file alias (the normal setup
+ * for white-label and multi-tenant apps): the whole setup was lost to a flag named in no checklist,
+ * and `init`'s own fallback snippet guards on `hostname === 'localhost'`, so on such a host the
+ * connect never runs and there is not even a console line to find.
+ *
+ * Only offered on the wired-and-listening branch: that is where a correctly installed app that
+ * cannot connect actually lands.
  */
-const UNINSTRUMENTED = 'Separately: this project has not been through `reticle init`, which is what installs the SDK ' +
-    'and wires it into the build — so even once the dev server is up, the app will carry no SDK and ' +
-    "no session will appear. Run `reticle init` in the app's directory too.";
+const NON_LOCALHOST_GATE = 'One more cause that leaves every other check healthy: if the app is served on anything other ' +
+    'than localhost (a hosts-file alias, a LAN IP, a tunnel), the SDK refuses to connect unless it ' +
+    'is given `allowNonLocalhost: true` — the refusal is page-side, so nothing here can see it. ' +
+    "Check the browser console for that message and pass the flag in the app's reticle.connect().";
 const SCANNED_PORTS = [...DEV_SERVER_PORTS].join(', ');
 export function diagnoseNoSession(facts) {
     const { everConnected, initialized, listening, port } = facts;
@@ -84,26 +92,49 @@ export function diagnoseNoSession(facts) {
             `the app (or run \`reticle open\`), or reload the tab. ${SELF_SERVE} ${RETRY}`);
     }
     if (0 === listening.length) {
+        // Lead with the stronger EVIDENCE, and do not overstate what it is.
+        //
+        // `initialized` is one thing only: whether a `.reticle.json` sits in the directory this daemon
+        // is running in. It is NOT "this project has never been through `reticle init`", and the two
+        // come apart constantly — a monorepo whose daemon runs at the root while the app lives in
+        // `apps/web`, or any app wired by the babel/vite plugin rather than by `init`. An earlier
+        // version of this branch asserted the strong claim and led with it, on the reasoning that it was
+        // a certainty while the port scan was a guess. It is not a certainty. Caught driving Reticle's
+        // OWN repo, where the message told an agent the project had never been through `init` about a
+        // fixture that is instrumented and working — "the one sentence I was most likely to act on was
+        // wrong", which is the exact failure this whole file exists to prevent.
+        //
+        // So: report what was actually checked, name the directory, and name the case where the absence
+        // is expected rather than diagnostic.
+        if (!initialized) {
+            return ('no browser session connected. Two things to weigh, and neither of them is proof. ' +
+                `(1) Nothing is listening on the ports Reticle scans (${SCANNED_PORTS}), so the dev server ` +
+                'may not be running — ask the human to start it (`npm run dev`). That scan is narrow ' +
+                'though: a server on any other port is invisible to it, so if the app IS running, ask for ' +
+                'its URL rather than assuming it is down. ' +
+                '(2) There is no `.reticle.json` in the directory this daemon is running in. That is the ' +
+                "file `reticle init` writes, so the app may carry no Reticle SDK — but check the app's " +
+                'OWN directory before re-running `init`: in a monorepo the daemon often runs at the root ' +
+                'while the app lives in a subdirectory, and an app wired by the Vite or Babel plugin ' +
+                `carries the SDK without that file at all. ${RETRY}`);
+        }
         return ('no browser session connected, and nothing is listening on the ports Reticle scans ' +
             `(${SCANNED_PORTS}). The likeliest cause by far is that the dev server is not running: ask ` +
             'the human to start it (`npm run dev`), then open the app in a browser. ' +
             // The caveat is here rather than omitted because the scan is NARROW, and the old sentence
-            // spent its confidence as though an empty result from eleven ports were proof of absence.
-            // Reported from a scripted drive of 2.5.0: this branch asserted the app was not running while
-            // it served 200 on :7699. A dev server on any other port — 4173 from `vite preview`, 1420
-            // from Tauri, 5175 from a second Vite, anything passed to --port — is invisible to it.
+            // spent its confidence as though an empty result were proof of absence. Reported twice: a
+            // scripted drive of 2.5.0 asserted the app was not running while it served 200 on :7699, and
+            // an agent was told nothing was listening while a dev server answered on :5000 under a custom
+            // hostname. The common defaults have since been added to the scanned set, which narrows the
+            // gap and cannot close it — anything passed to `--port` is still invisible.
             'That scan is narrow, so it is not proof: a server on any other port is invisible to it. If ' +
             // Deliberately NOT offering reticle_lease here, and a test pins that: a lease opens a URL, and
             // if nothing is listening there is nothing at any URL to open. Asking for the real one is the
             // only move that can recover the :7699 case.
             'the app IS running, ask the human for its URL rather than assuming it is down. ' +
-            // BOTH facts at once when the project was never wired. This branch fires before the
-            // `!initialized` one, so an uninstrumented project used to be told only "start your dev
-            // server" — the reader starts it, calls again, and is told ONLY THEN that no app carries the
-            // SDK. Two round trips to learn two things the daemon knew on the first call, and this is the
-            // largest cohort in the funnel (#171): 77 users attached an agent and never instrumented an
-            // app. They have a daemon (they registered the MCP server) and no SDK anywhere.
-            `${initialized ? '' : UNINSTRUMENTED} ${RETRY}`);
+            // Reachable only for a project that HAS been through `init` — the uninstrumented case is
+            // answered above, leading with that certainty instead of behind this scan's guess.
+            `${RETRY}`);
     }
     if (!initialized) {
         return (`no browser session connected, but something IS listening on port ${ports} — so a server is ` +
@@ -116,5 +147,5 @@ export function diagnoseNoSession(facts) {
         `wired for Reticle — so the app is either serving a build made before the wiring landed, or ` +
         `dialling a different daemon than this one (this daemon is on ${String(port)}). Ask the human ` +
         'to restart the dev server and hard-reload the page; if it still does not appear, check that ' +
-        `the app's reticle port matches ${String(port)}. ${SELF_SERVE} ${RETRY}`);
+        `the app's reticle port matches ${String(port)}. ${NON_LOCALHOST_GATE} ${SELF_SERVE} ${RETRY}`);
 }

package/dist/session/review-store.d.ts

@@ -21,6 +21,15 @@ export interface ReviewMark {
     at: number;
     status: MarkStatus;
 }
+/** Tests only — assertions on `m1` must not depend on which test ran first. */
+export declare function resetMarkIdsForTest(): void;
+/** What `resolve` actually did, including WHICH mark — so a caller can verify it hit the right one. */
+export interface ResolveOutcome {
+    resolved: boolean;
+    id: string;
+    /** The retired mark's note. Absent when nothing was resolved. */
+    note?: string;
+}
 export declare class ReviewStore {
     #private;
     /** Store a new mark (status pending) stamped with the caller-supplied session-relative time. */
@@ -36,4 +45,14 @@ export declare class ReviewStore {
      * false for an unknown id or an already-resolved mark (so resolve is idempotent).
      */
     resolve(id: string): boolean;
+    /**
+     * Resolve, and say WHICH mark was retired.
+     *
+     * The bare boolean is what made the misattribution silent: `{"resolved":true}` is equally
+     * consistent with "I retired the bug you fixed" and "I retired somebody else's". Echoing the note
+     * lets a caller check the answer against what it believed it was resolving, which is exactly what
+     * the agent that hit this asked for — it had been re-reading the whole list after every resolve
+     * and hand-diffing the notes to get the same assurance.
+     */
+    resolveDetail(id: string): ResolveOutcome;
 }