@reticlehq/server 3.4.0 → 3.6.0

package/dist/command/setup/bringup/dev-server-wait.d.ts

@@ -25,6 +25,8 @@ export interface WaitFacts {
     readonly quietForMs: number;
     /** Milliseconds since the wait began. */
     readonly elapsedMs: number;
+    /** Explicit caller limit; otherwise a busy build keeps the default ceiling. */
+    readonly budgetMs?: number | undefined;
     /**
      * How long silence may mean "still starting" on THIS machine. Defaults to QUIET_MEANS_HUNG_MS.
      *
@@ -57,6 +59,14 @@ export declare const WAIT_CEILING_MS: number;
  */
 export declare function judgeWait(facts: WaitFacts): WaitVerdict;
 export declare function portBusyMessage(output: string): string | undefined;
+/**
+ * The dev server died before serving: say so, and quote the end of what it printed.
+ *
+ * Without the tail the reason was invisible: a missing `vite` binary printed `vite: command not
+ * found` to its own log, setup said only "exited without serving anything", and its first remedy
+ * ("start the dev server yourself") failed the same way.
+ */
+export declare function devServerDiedMessage(output: string): string;
 export declare function announcedUrl(output: string): string | undefined;
 /**
  * The url to watch: whatever the tool announced, else one composed from a port we OBSERVED our own

package/dist/command/setup/bringup/dev-server-wait.js

@@ -38,7 +38,7 @@ export function judgeWait(facts) {
         return WaitVerdict.READY;
     if (facts.launcherExited)
         return WaitVerdict.DEAD;
-    if (facts.elapsedMs >= WAIT_CEILING_MS)
+    if (facts.elapsedMs >= (facts.budgetMs ?? WAIT_CEILING_MS))
         return WaitVerdict.HUNG;
     // Output IS progress. Silence is what distinguishes a build from a wedge.
     return facts.quietForMs >= (facts.quietMeansHungMs ?? QUIET_MEANS_HUNG_MS)
@@ -61,6 +61,25 @@ export function portBusyMessage(output) {
     return (`port ${port} is already in use — something else is serving there, so this launcher did not ` +
         `bind. Pass --url http://localhost:${port} if that process is this app, or free the port and re-run.`);
 }
+/** How many of the dev server's last lines a failure quotes. Enough for a stack's first frames. */
+const DIED_TAIL_LINES = 6;
+/**
+ * The dev server died before serving: say so, and quote the end of what it printed.
+ *
+ * Without the tail the reason was invisible: a missing `vite` binary printed `vite: command not
+ * found` to its own log, setup said only "exited without serving anything", and its first remedy
+ * ("start the dev server yourself") failed the same way.
+ */
+export function devServerDiedMessage(output) {
+    const tail = output
+        .split('\n')
+        .map((line) => line.trimEnd())
+        .filter((line) => 0 < line.trim().length)
+        .slice(-DIED_TAIL_LINES);
+    return 0 === tail.length
+        ? 'The dev server exited without serving anything, and printed nothing.'
+        : `The dev server exited without serving anything. The last it printed:\n${tail.map((line) => `    ${line}`).join('\n')}`;
+}
 /** A url the dev server announced, if it has announced one. Never composed, only read. */
 const URL_IN_OUTPUT = /https?:\/\/(?:localhost|127\.0\.0\.1|\[::1\]):\d+/;
 export function announcedUrl(output) {

package/dist/command/setup/init/init-port.d.ts

@@ -12,4 +12,8 @@ export declare function portForInit(explicit: number | undefined, configured: nu
     daemonProjects: (port: number) => Promise<readonly string[]>;
     daemonPresent: (port: number) => Promise<boolean>;
     pickPort: (preferred: number) => Promise<number>;
+    /** The daemon on `port` was started from this project's directory or one above it. */
+    daemonStartedHere?: (port: number) => boolean;
 }): Promise<number | undefined>;
+/** Is `dir` the same directory as `cwd`, or an ancestor of it? */
+export declare function isSameOrAbove(dir: string, cwd: string): boolean;

package/dist/command/setup/init/init-port.js

@@ -8,6 +8,7 @@
  *
  * Undefined means the default.
  */
+import { relative, isAbsolute } from 'node:path';
 import { RETICLE_DEFAULT_PORT, ReticleEnv } from '@reticlehq/core';
 const MAX_PORT = 65_535;
 /**
@@ -34,6 +35,10 @@ export async function portForInit(explicit, configured, projectId, deps) {
     // config as a `port` nobody chose.
     if (!(await deps.daemonPresent(RETICLE_DEFAULT_PORT)))
         return undefined;
+    // Started here — by this project's own editor MCP, typically — so it is ours whatever project id
+    // it recorded. Moving off it strands that agent: an MCP resolves its port once, at startup.
+    if (true === deps.daemonStartedHere?.(RETICLE_DEFAULT_PORT))
+        return undefined;
     // The bridge's own rule: it refuses a page only when it has served exactly ONE other project. A
     // daemon serving nobody, several projects, or ours accepts this one. A project that has never
     // been through init has no id yet, so a single named holder is somebody else.
@@ -42,3 +47,8 @@ export async function portForInit(explicit, configured, projectId, deps) {
         return undefined;
     return deps.pickPort(RETICLE_DEFAULT_PORT + 1);
 }
+/** Is `dir` the same directory as `cwd`, or an ancestor of it? */
+export function isSameOrAbove(dir, cwd) {
+    const rel = relative(dir, cwd);
+    return '' === rel || (!rel.startsWith('..') && !isAbsolute(rel));
+}

package/dist/command/setup/init/init-runtime.d.ts

@@ -6,6 +6,16 @@
  * every command harder to read.
  */
 import { type InitResult } from '@reticlehq/init';
+/**
+ * Does the served document name the SDK, so its absence means a stale dev server?
+ *
+ * A Next App Router page names its client components in the flight data inlined into the HTML —
+ * `reticle-dev.tsx`, measured on Next 16 under Turbopack and webpack alike. Reported from a Next app
+ * whose dev server was already running before init: setup waited on a page that could never connect
+ * and said nothing, because Next was assumed to carry the SDK only in its bundle. The Pages Router
+ * names chunks, not modules, so it stays silent.
+ */
+export declare function htmlCarriesSdk(framework: string, exists: (path: string) => boolean): boolean;
 /** Just enough of the parsed command to decide and run. */
 interface InitRuntimeArgs {
     readonly port: number | undefined;

package/dist/command/setup/init/init-runtime.js

@@ -6,8 +6,9 @@
  * every command harder to read.
  */
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { RETICLE_DEFAULT_PORT } from '@reticlehq/core';
-import { FEEDBACK_HINT, Framework } from '@reticlehq/init';
+import { join } from 'node:path';
+import { InitConfirmation, RETICLE_DEFAULT_PORT } from '@reticlehq/core';
+import { FEEDBACK_HINT, Framework, InitFailure } from '@reticlehq/init';
 import { confirmInstall, nodeConfirmDeps } from '../terminal/confirm.js';
 import { writeLicenseKey } from '../license-key.js';
 import { registerOtherAgents, runSetupCommand } from '../setup-command.js';
@@ -20,6 +21,8 @@ import { probeDaemon } from '../../../surface/mcp/proxy/proxy-daemon-probe.js';
 import { fetchStatus } from '../../daemon/binding/daemon-status-probe.js';
 import { collectEnv, DEFAULT_PHASE_TIMEOUT_MS } from '../setup-options.js';
 import { staticPageDevCommand } from '../bringup/static-page-server.js';
+import { SetupPhase } from '../run-setup.js';
+import { reportInitOutcome } from '../../../telemetry/init-telemetry.js';
 /** How often the runtime phases look again: fast enough not to be the wait, slow enough to be free. */
 const POLL_MS = 250;
 /**
@@ -28,6 +31,22 @@ const POLL_MS = 250;
  * of the document can never see it. See `htmlCarriesSdk` in run-setup.ts.
  */
 const HTML_CARRIES_SDK = new Set([Framework.VITE, Framework.HTML]);
+/** The connect component `init` writes for a Next App Router project. */
+const NEXT_APP_CONNECT = ['app', 'src/app'].flatMap((d) => ['tsx', 'jsx', 'js'].map((ext) => `${d}/reticle-dev.${ext}`));
+/**
+ * Does the served document name the SDK, so its absence means a stale dev server?
+ *
+ * A Next App Router page names its client components in the flight data inlined into the HTML —
+ * `reticle-dev.tsx`, measured on Next 16 under Turbopack and webpack alike. Reported from a Next app
+ * whose dev server was already running before init: setup waited on a page that could never connect
+ * and said nothing, because Next was assumed to carry the SDK only in its bundle. The Pages Router
+ * names chunks, not modules, so it stays silent.
+ */
+export function htmlCarriesSdk(framework, exists) {
+    if (HTML_CARRIES_SDK.has(framework))
+        return true;
+    return Framework.NEXT === framework && NEXT_APP_CONNECT.some(exists);
+}
 /** Registration is global MCP wiring, so both flags that disown it are read here. */
 function wantsAgents(parsed) {
     return false !== parsed.agents && false !== parsed.mcp;
@@ -59,9 +78,9 @@ function printRelaunch(parsed, io, cwd) {
 }
 export async function continueAfterInit(parsed, result, io, cwd) {
     const port = parsed.port ?? RETICLE_DEFAULT_PORT;
-    // Before anything else: the key belongs in .env whichever way this run ends, and the CLI folds a
-    // project-local .env into the environment on every invocation.
-    if (undefined !== parsed.licenseKey) {
+    // Real installs persist the key whichever way setup ends. A preview must leave .env and
+    // .gitignore untouched, just as it leaves project wiring and agent configuration untouched.
+    if (!parsed.dryRun && undefined !== parsed.licenseKey) {
         const written = writeLicenseKey(cwd, parsed.licenseKey, licenseIo);
         io.print(written.message);
     }
@@ -79,9 +98,12 @@ export async function continueAfterInit(parsed, result, io, cwd) {
         // has: nothing reaches back into a machine that installed Reticle a version ago, so the
         // upgrade path is re-running init, and the light form of init has to be enough to carry it.
         // A dry run writes nothing anywhere, including here.
-        if (true === parsed.filesOnly && wantsAgents(parsed))
+        if (!parsed.dryRun && true === parsed.filesOnly && wantsAgents(parsed)) {
             registerOtherAgents(io.print);
+        }
         return confirmInstall(result, io, nodeConfirmDeps(port)).then(() => {
+            if (true === parsed.json)
+                process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
             if (!result.ok)
                 process.exit(1);
         });
@@ -96,8 +118,15 @@ export async function continueAfterInit(parsed, result, io, cwd) {
     if (context === undefined) {
         // Nothing was established, so there is nothing to run against. init has already said why.
         ask();
+        if (true === parsed.json)
+            process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
         process.exit(1);
     }
+    const reportFailure = (reason) => {
+        if (result.outcome !== undefined) {
+            reportInitOutcome({ ...result.outcome, ok: false, reason });
+        }
+    };
     // A PENDING connect step is not a reason to skip the runtime phase, and treating it as one made
     // `init` stop with "paste this snippet" while never looking at the app.
     //
@@ -113,10 +142,17 @@ export async function continueAfterInit(parsed, result, io, cwd) {
     // Before the connect wait, never after: a bridge held by a stranger makes a session impossible,
     // so going ahead spends the entire budget and then reports what reads as an instrumentation
     // problem — the one place that is fine. See bridge-port.ts.
-    const refusal = bridgeOccupied(await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus }), port);
+    const refusal = bridgeOccupied(await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus }).catch((error) => {
+        reportFailure(InitFailure.RUNTIME_ERROR);
+        throw error;
+    }), port);
     if (refusal !== undefined) {
+        reportFailure(InitFailure.BRIDGE_OCCUPIED);
         io.print(refusal);
         ask();
+        if (true === parsed.json) {
+            process.stdout.write(`${JSON.stringify({ ok: false, reason: InitFailure.BRIDGE_OCCUPIED }, null, 2)}\n`);
+        }
         process.exit(1);
     }
     return runSetupCommand({
@@ -136,9 +172,12 @@ export async function continueAfterInit(parsed, result, io, cwd) {
         // keeps deciding, so nobody who passed nothing waits less than they used to.
         ...(undefined === parsed.timeoutSeconds
             ? {}
-            : { connectBudgetMs: parsed.timeoutSeconds * 1000 }),
+            : {
+                connectBudgetMs: parsed.timeoutSeconds * 1000,
+                startupBudgetMs: parsed.timeoutSeconds * 1000,
+            }),
         pollMs: POLL_MS,
-        htmlCarriesSdk: HTML_CARRIES_SDK.has(context.framework),
+        htmlCarriesSdk: htmlCarriesSdk(context.framework, (rel) => existsSync(join(context.appDir, rel))),
         // A plain page with no dev script gets Reticle's own static server, so the page is actually
         // served and the connect can be proved, instead of stopping at "start the app yourself".
         ...(() => {
@@ -153,6 +192,26 @@ export async function continueAfterInit(parsed, result, io, cwd) {
         })(),
         ...(undefined === parsed.url ? {} : { suppliedUrl: parsed.url }),
     }, (line) => io.print(line)).then((outcome) => {
+        if (result.outcome !== undefined) {
+            const init = {
+                ...result.outcome,
+                ok: outcome.ok,
+            };
+            if (outcome.ok) {
+                delete init.reason;
+                init.confirmation = InitConfirmation.CONNECTED;
+            }
+            else {
+                // A failed startup does not establish whether a daemon or instrumented page exists.
+                // Keep the watcher's no_daemon/no_session/no_page classifications for observed facts.
+                delete init.confirmation;
+                init.reason =
+                    outcome.reachedPhase === SetupPhase.DEV_SERVER
+                        ? InitFailure.DEV_SERVER
+                        : InitFailure.APP_CONNECTION;
+            }
+            reportInitOutcome(init);
+        }
         // One object, so an agent reads a result instead of interpreting a report.
         if (true === parsed.json) {
             process.stdout.write(`${JSON.stringify(outcome, null, 2)}\n`);
@@ -201,5 +260,8 @@ export async function continueAfterInit(parsed, result, io, cwd) {
             io.print(`   ${i + 1}. ${step}`);
         ask();
         process.exit(1);
+    }, (error) => {
+        reportFailure(InitFailure.RUNTIME_ERROR);
+        throw error;
     });
 }

package/dist/command/setup/node-effects.js

@@ -23,6 +23,8 @@ import { reticleStateHome } from '../daemon/daemon.js';
 import { descendants, parseLsofPorts, parseNetstatListeners, parseWmicProcesses, } from './terminal/listeners.js';
 import { isAddressMiss, loopbackProbeUrls } from './probe/loopback-probe-urls.js';
 const WINDOWS = 'win32' === process.platform;
+/** Astro otherwise daemonizes automatically when it detects an agent terminal. */
+const ASTRO_DEV_BACKGROUND_ENV = 'ASTRO_DEV_BACKGROUND';
 /** A page fetch that is slow is a page fetch that failed, for our purposes. */
 const PROBE_TIMEOUT_MS = 5_000;
 /** The supervisor that owns the server's output and keeps its log bounded. */
@@ -64,7 +66,10 @@ export class OwnedDevServer {
             detached: !WINDOWS,
             // Nothing of ours: the supervisor holds the server's pipes, and init holds none of its.
             stdio: 'ignore',
-            env: { ...process.env, ...env },
+            // Reticle already provides the detached supervisor. Astro's agent auto-backgrounding
+            // would escape its process group and leave the recorded handover PID pointing at a dead
+            // launcher, so re-init and cleanup could no longer find or stop the actual server.
+            env: { ...process.env, ...env, [ASTRO_DEV_BACKGROUND_ENV]: '1' },
         });
         this.log = log;
         this.cwd = cwd;
@@ -101,7 +106,8 @@ export class OwnedDevServer {
         catch {
             /* not written yet */
         }
-        return Date.now() - lastOutputAt;
+        // Filesystem timestamps can include a fractional millisecond beyond Date.now()'s integer.
+        return Math.max(0, Date.now() - lastOutputAt);
     }
     /** Ports anything in this server's process tree is listening on. */
     listeningPorts() {

package/dist/command/setup/remaining-steps.js

@@ -34,7 +34,8 @@ export function remainingSteps(p) {
             '`reticle_*` tools, ending in `reticle_act_and_wait` or `reticle_assert` — those two are ' +
             'what produce a verdict. Or hand the whole drive to Reticle with `reticle_verify { action: ' +
             '"explore", persona: "<who does what>" }`, which records what it drove so later runs replay ' +
-            'with no model in the loop; that route needs ANTHROPIC_API_KEY.');
+            'with no model in the loop; that route runs on the Reticle platform and needs a linked ' +
+            'project (`reticle connect`); every plan, Free included, has monthly Harness credits.');
     }
     // Whether anything is actually outstanding, read BEFORE the docs pointer is added -- that line is
     // an offer, not a task, and a run with nothing left still gets it.

package/dist/command/setup/run-setup.d.ts

@@ -55,6 +55,11 @@ export interface DaemonReason {
 export interface OwnedBrowser {
     readonly sessionId: string;
     readonly release: () => Promise<void>;
+    /**
+     * The page never dialled in, so the lease injected Reticle's own reader. That session proves the
+     * reader, not this install, and must never end onboarding as "connected".
+     */
+    readonly zeroInstall?: boolean;
 }
 export interface SetupEffects {
     /** Start the dev server. Resolves once started; the caller owns stopping it. */
@@ -132,6 +137,8 @@ export interface SetupInput {
      * before setup could say what was wrong.
      */
     readonly connectBudgetMs?: number | undefined;
+    /** Explicit --timeout for startup; absent preserves the adaptive build wait. */
+    readonly startupBudgetMs?: number | undefined;
     readonly openBrowser: boolean;
     /** Web, Electron or Tauri. Desktop changes three things; see desktop-shape.ts. */
     readonly shape: AppShape;

package/dist/command/setup/run-setup.js

@@ -13,7 +13,7 @@
  * way of going wrong, and the alternative to injecting them is a test that boots a real dev server
  * and a real browser to find out what happens when neither works.
  */
-import { judgeWait, portBusyMessage, QUIET_MEANS_HUNG_MS, urlToWatch, WaitVerdict, } from './bringup/dev-server-wait.js';
+import { judgeWait, devServerDiedMessage, portBusyMessage, QUIET_MEANS_HUNG_MS, urlToWatch, WaitVerdict, } from './bringup/dev-server-wait.js';
 import { connectProgressLine, waitProgressLine } from './terminal/wait-progress.js';
 /**
  * Windows gets longer to say something before silence counts as a wedge.
@@ -159,6 +159,7 @@ export async function runSetupPhases(input, fx) {
                     serving,
                     quietForMs: fx.devServerQuietForMs(),
                     elapsedMs: fx.now() - startedAt,
+                    budgetMs: input.startupBudgetMs,
                     quietMeansHungMs: WINDOWS_QUIET_MEANS_HUNG_MS_APPLIES
                         ? WINDOWS_QUIET_MEANS_HUNG_MS
                         : QUIET_MEANS_HUNG_MS,
@@ -176,16 +177,22 @@ export async function runSetupPhases(input, fx) {
                     break;
                 }
                 if (WaitVerdict.DEAD === verdict) {
-                    note(portBusyMessage(fx.devServerOutput()) ??
-                        'The dev server exited without serving anything.');
+                    note(portBusyMessage(fx.devServerOutput()) ?? devServerDiedMessage(fx.devServerOutput()));
                     return stop(input, SetupPhase.DEV_SERVER, {}, notes);
                 }
                 if (WaitVerdict.HUNG === verdict) {
                     // Says BOTH were checked. A server that prints nothing but IS listening is the CRA case and
                     // must not be failed, so a reader has to be able to tell "we looked at the log" from "we
                     // looked at the log AND the ports".
-                    note('The dev server neither printed a URL nor bound a port, so setup has nothing to open. ' +
-                        'Check its log, or pass --url with the address it serves.');
+                    const within = input.startupBudgetMs !== undefined && fx.now() - startedAt >= input.startupBudgetMs
+                        ? ` within ${String(input.startupBudgetMs)}ms`
+                        : undefined;
+                    note((undefined === watching
+                        ? `The dev server neither printed a URL nor bound a port${within ?? ''}, so setup has nothing to open. `
+                        : undefined !== within
+                            ? `The dev server did not become ready${within}. `
+                            : `The dev server stopped making progress before ${watching} became ready. `) +
+                        'Check its log, increase --timeout for a slow build, or pass --url with the address it serves.');
                     return stop(input, SetupPhase.DEV_SERVER, {}, notes);
                 }
                 await fx.sleep(input.pollMs);
@@ -227,6 +234,23 @@ export async function runSetupPhases(input, fx) {
     // dialled the bridge" over a correct install. With a lease to fall back on it is entered too, and
     // only the system browser is skipped.
     const canLease = undefined !== fx.openLease;
+    const injected = new Set();
+    /**
+     * The lease to keep, or undefined. A lease whose page only connected through Reticle's injected
+     * reader is handed straight back and its session excluded: it would otherwise be picked below and
+     * report a plain server with no SDK as an instrumented app.
+     */
+    const keepLease = async (owned) => {
+        if ('failed' in owned) {
+            note(`Could not open ${url} in a Reticle-owned browser either: ${owned.failed}`);
+            return undefined;
+        }
+        if (true !== owned.zeroInstall)
+            return owned;
+        injected.add(owned.sessionId);
+        await releaseLease(owned);
+        return undefined;
+    };
     if (null === alreadyConnected && policy.openBrowser && (input.openBrowser || canLease)) {
         // SERVED is the precondition, not SDK_PRESENT: a url that answers nothing is the only state
         // where a window is certainly useless. Whether the SDK is in the served HTML is a DIFFERENT
@@ -255,14 +279,9 @@ export async function runSetupPhases(input, fx) {
             const launcherFailed = input.openBrowser ? await fx.openBrowser(url) : undefined;
             openedBrowser = input.openBrowser;
             if (undefined !== fx.openLease && (!input.openBrowser || undefined !== launcherFailed)) {
-                const owned = await fx.openLease(url);
-                if ('failed' in owned) {
-                    note(`Could not open ${url} in a Reticle-owned browser either: ${owned.failed}`);
-                }
-                else {
-                    lease = owned;
+                lease = await keepLease(await fx.openLease(url));
+                if (undefined !== lease)
                     openedBrowser = true;
-                }
             }
         }
     }
@@ -283,7 +302,8 @@ export async function runSetupPhases(input, fx) {
     while (null === session) {
         // On a desktop app, only the desktop window counts. AppShape and the runtime a page reports use
         // the same three names, so the shape IS the requirement — see session-pick.
-        session = pickSession(await fx.listSessions(), url, before, requiredRuntime);
+        const listedNow = (await fx.listSessions()).filter((s) => !injected.has(s.sessionId));
+        session = pickSession(listedNow, url, before, requiredRuntime);
         if (null !== session)
             break;
         if (deadline <= fx.now())
@@ -296,13 +316,7 @@ export async function runSetupPhases(input, fx) {
             !isDesktop(input.shape) &&
             fx.now() - waitStartedAt >= SYSTEM_BROWSER_GRACE_MS) {
             leaseFallbackTried = true;
-            const owned = await fx.openLease(url);
-            if ('failed' in owned) {
-                note(`Could not open ${url} in a Reticle-owned browser either: ${owned.failed}`);
-            }
-            else {
-                lease = owned;
-            }
+            lease = await keepLease(await fx.openLease(url));
             continue;
         }
         // Not in silence: a desktop run used to print one line and then nothing for ten minutes.
@@ -363,9 +377,8 @@ export async function runSetupPhases(input, fx) {
     // `<url>` stays a placeholder in this string on purpose: `guidance-commands-run` feeds every
     // command we print to the real parser, and an interpolated value reads there as a missing operand.
     // The live url is named in the sentence instead, where a reader needs it anyway.
-    // Both routes, because `explore` needs a model: without ANTHROPIC_API_KEY it answers "No model
-    // configured to drive the app". Naming only that one hands the reader a dead end on any machine
-    // without a key, which is the same defect this release spent its time removing everywhere else.
+    // Both routes, because `explore` runs on the platform: without a linked project it refuses.
+    // Naming only that one hands the reader a dead end on any machine without one.
     // A heading and a numbered list rather than one paragraph: a reader scans for what to do next.
     //
     // This was a single 524-character note, measured on a real first run: eighty-three words, no
@@ -385,8 +398,8 @@ export async function runSetupPhases(input, fx) {
     note('  1. Drive one flow and end it with `reticle_act_and_wait` or `reticle_assert`. Those two ' +
         'produce a verdict; nothing else does.');
     note('  2. Or hand over the whole drive: `reticle_verify { action: "explore", persona: "<who does ' +
-        'what>" }` records what it drove, so later runs replay with no model in the loop. Needs ' +
-        'ANTHROPIC_API_KEY.');
+        'what>" }` records what it drove, so later runs replay with no model in the loop. Runs on ' +
+        'the Reticle platform: needs a linked project (`reticle connect`); Free includes monthly Harness credits.');
     return {
         ok: true,
         reachedPhase: SetupPhase.CONNECT,

package/dist/command/setup/setup-command.d.ts

@@ -30,7 +30,8 @@ interface SetupCommandInput extends Omit<SetupInput, 'shape'> {
     /** The bridge's pairing token, for the MCP transport a connect-proof lease is opened over. */
     readonly pairingToken?: string | undefined;
 }
-export declare function registerOtherAgents(print: (line: string) => void): void;
+/** Returns how many agents it wrote a config for, so a caller does not then say "none found". */
+export declare function registerOtherAgents(print: (line: string) => void): number;
 type SetupCommandResult = SetupOutcome;
 export declare function runSetupCommand(input: SetupCommandInput, print: (line: string) => void): Promise<SetupCommandResult>;
 export {};

package/dist/command/setup/setup-command.js

@@ -89,6 +89,7 @@ function hasElectronDependency(dir) {
  */
 /** `agent`, `agents`. */
 const agentWord = (n) => (1 === n ? 'agent' : 'agents');
+/** Returns how many agents it wrote a config for, so a caller does not then say "none found". */
 export function registerOtherAgents(print) {
     const platform = process.platform;
     const home = homedir();
@@ -124,6 +125,7 @@ export function registerOtherAgents(print) {
     for (const noted of approvals.filter((a) => undefined !== a.warn)) {
         print(`  ⚠ ${noted.name}: ${String(noted.warn)}`);
     }
+    return wrote.length;
 }
 /**
  * Run the phases against the real world.

package/dist/command/setup/setup-mcp.d.ts

@@ -32,6 +32,8 @@ export interface SetupMcpResult {
     readonly detected: readonly string[];
     readonly registered: readonly string[];
     readonly alreadyThere: readonly string[];
+    /** Automatic registration was attempted but failed. */
+    readonly failed: readonly string[];
     /**
      * Clients whose config this will NOT rewrite, and which therefore still need a human.
      *

package/dist/command/setup/setup-mcp.js

@@ -4,6 +4,7 @@ export function setupMcp(io) {
     const detected = [];
     const registered = [];
     const alreadyThere = [];
+    const failed = [];
     const manual = [];
     /*
      * Claude Code first, because nothing else can find it.
@@ -30,6 +31,8 @@ export function setupMcp(io) {
             const cmd = claudeAddCommand();
             if (io.runCli(cmd.command, cmd.args))
                 registered.push(McpClient.CLAUDE_CODE);
+            else
+                failed.push(McpClient.CLAUDE_CODE);
         }
     }
     for (const client of detectMcpClients(io)) {
@@ -47,8 +50,13 @@ export function setupMcp(io) {
             manual.push({ id: client.id, configPath: client.configPath, docs: spec.docs });
             continue;
         }
-        io.writeFile(client.configPath, merged.content);
-        registered.push(client.id);
+        try {
+            io.writeFile(client.configPath, merged.content);
+            registered.push(client.id);
+        }
+        catch {
+            failed.push(client.id);
+        }
     }
     /*
      * Both INSTALL steps, reported from the one place that knows the answer.
@@ -69,7 +77,8 @@ export function setupMcp(io) {
          * SKIPPED when there was nothing to register with — not failed. Nothing went wrong; there was
          * simply no agent here, and counting that as our failure would hide the ones that are.
          *
-         * FAILED when every client we found needs a hand. That case used to fall through to COMPLETED,
+         * FAILED when no detected client is usable, whether registration failed or needs a hand.
+         * That case used to fall through to COMPLETED,
          * so the cohort with the tools registered NOWHERE was counted among the successful installs, and
          * the one number that says "did this machine get Reticle" read yes for the people it read no
          * for. Registering some and not others is still COMPLETED: the agent they are using may well be
@@ -79,11 +88,11 @@ export function setupMcp(io) {
             ? OnboardingStepStatus.SKIPPED
             : 0 === registered.length && alreadyThere.length > 0
                 ? OnboardingStepStatus.SKIPPED
-                : 0 === registered.length && 0 === alreadyThere.length && manual.length > 0
+                : 0 === registered.length && 0 === alreadyThere.length
                     ? OnboardingStepStatus.FAILED
                     : OnboardingStepStatus.COMPLETED,
     });
-    return { detected, registered, alreadyThere, manual };
+    return { detected, registered, alreadyThere, failed, manual };
 }
 /** Everything this machine could be asked about, for the report when nothing was found. */
 export function knownClientLabels() {

package/dist/command/version/peer-announce.d.ts

@@ -1,4 +1,8 @@
 export declare const PEER_VERSION_PARAM = "peerVersion";
 export declare const PEER_CONTRACT_PARAM = "peerContract";
-/** Compare an attaching agent process against this daemon, and queue the nudge when they disagree. */
-export declare function noteAgentPeer(version: string | null, contract: string | null): void;
+/**
+ * Compare an attaching agent process against this daemon: the skew to tell THAT connection, or
+ * undefined when they agree. Returned rather than queued daemon-wide, because it is true only for the
+ * agent that announced it (#1136).
+ */
+export declare function agentPeerSkew(version: string | null, contract: string | null): string | undefined;

package/dist/command/version/peer-announce.js

@@ -13,12 +13,15 @@
  */
 import { CONTRACT_FINGERPRINT } from '@reticlehq/core';
 import { SERVER_VERSION } from './identity/server-version.js';
-import { daemonFix, describeSkew, SkewPair } from './version-skew.js';
-import { noteVersionSkew } from './version-nudge.js';
+import { daemonFix, describeSkew } from './version-skew.js';
 export const PEER_VERSION_PARAM = 'peerVersion';
 export const PEER_CONTRACT_PARAM = 'peerContract';
-/** Compare an attaching agent process against this daemon, and queue the nudge when they disagree. */
-export function noteAgentPeer(version, contract) {
+/**
+ * Compare an attaching agent process against this daemon: the skew to tell THAT connection, or
+ * undefined when they agree. Returned rather than queued daemon-wide, because it is true only for the
+ * agent that announced it (#1136).
+ */
+export function agentPeerSkew(version, contract) {
     const skew = describeSkew({
         what: "the agent's MCP server",
         version: version ?? undefined,
@@ -27,6 +30,5 @@ export function noteAgentPeer(version, contract) {
         // MCP server, so the daemon is the newer half whenever the announcing agent is behind.
         fix: daemonFix(SERVER_VERSION, version ?? undefined),
     }, { version: SERVER_VERSION, contract: CONTRACT_FINGERPRINT });
-    if (skew !== undefined)
-        noteVersionSkew(SkewPair.DAEMON, skew);
+    return skew;
 }

package/dist/command/version/version-nudge.d.ts

@@ -11,7 +11,7 @@
  * result, then goes quiet until the skew CHANGES. Told, not nagged: a banner on every call is one an
  * agent learns to skip, and it would cost those tokens on every call for the rest of the session.
  */
-import type { SkewPair } from './version-skew.js';
+import { SkewPair } from './version-skew.js';
 interface VersionSkewNudge {
     pair: SkewPair;
     action: string;
@@ -21,8 +21,20 @@ interface VersionSkewNudge {
  * a second tab on a third version is news; the same tab reconnecting is not.
  */
 export declare function noteVersionSkew(pair: SkewPair, action: string): void;
-/** The next undelivered skew, once. */
-export declare function takeVersionSkew(): VersionSkewNudge | undefined;
+/**
+ * A daemon skew bound to the one MCP connection whose server announced it, told once (#1136).
+ *
+ * The page pair stays in the daemon-wide queue: it is a fact about a tab, true for whoever asks.
+ * This pair is a fact about the CALLER, and telling it to a different caller is advice to restart
+ * a server that is fine, or to run `reticle stop` and cut every agent on the daemon.
+ */
+export declare function connectionSkew(action: string): {
+    take(): string | undefined;
+};
+/** The next undelivered skew, once: this connection's own first, then the daemon-wide queue. */
+export declare function takeVersionSkew(connection?: {
+    take(): string | undefined;
+}): VersionSkewNudge | undefined;
 /**
  * Splice pending skew onto a tool-error payload.
  *
@@ -36,6 +48,8 @@ export declare function takeVersionSkewOnto(payload: {
     error: string;
     recovery?: string;
     feedback?: string;
+}, connection?: {
+    take(): string | undefined;
 }): Record<string, unknown>;
 /** Tests only — drop the module state so each case starts clean. */
 export declare function resetVersionSkew(): void;