@reticlehq/server 3.8.2 → 3.9.0

package/dist/command/setup/agent-next-steps.d.ts

@@ -0,0 +1,77 @@
+import { McpClient } from '@reticlehq/init';
+import { AgentClient } from '@reticlehq/core/telemetry';
+import type { SetupMcpResult } from './setup-mcp.js';
+/** What registration did for one client. */
+export declare const AgentReg: {
+    /** The Claude Code plugin carries Reticle. */
+    readonly PLUGIN: "plugin";
+    readonly ADDED: "added";
+    readonly ALREADY: "already";
+    readonly FAILED: "failed";
+    readonly MANUAL: "manual";
+    /** Found, and Reticle is not in its config. Read-only callers (`status`) only. */
+    readonly MISSING: "missing";
+};
+export type AgentReg = (typeof AgentReg)[keyof typeof AgentReg];
+export interface AgentRow {
+    readonly id: McpClient;
+    readonly reg: AgentReg;
+    /** The config path for a hand edit. */
+    readonly path?: string;
+    /** The command to retry a failed CLI registration, with the launcher that run used. */
+    readonly retry?: string;
+    /** The plugin AND a user-scope `reticle` entry: the client has two servers. */
+    readonly duplicate?: boolean;
+    /** The entry is the floating npx form: the note that names the commands that replace it. */
+    readonly stale?: string;
+}
+/**
+ * The rows for one `setupMcp` run, in its order.
+ *
+ * @param launcher the installed bin that run registered (`SetupMcpIo.launcher`), so a retry line
+ *   names the same command.
+ */
+export declare function agentRows(result: SetupMcpResult, launcher?: string): AgentRow[];
+/** The "Your agents:" block: one line per client, each with its own next step. */
+export declare function agentLines(rows: readonly AgentRow[]): string[];
+/** The clients worth waiting for: the ones that have Reticle registered. */
+export declare function awaitedClients(rows: readonly AgentRow[]): AgentClient[];
+/** One agent, as `reticle status` reports it. */
+export interface AgentStatus {
+    readonly name: string;
+    readonly connected: boolean;
+    /** The step still missing. Absent when connected. */
+    readonly next?: string;
+    /** The line a person reads: "Connected: Cursor ✓", or the name and the step still missing. */
+    readonly said: string;
+}
+/** Per client: connected, or the exact step still missing. */
+export declare function agentStatuses(rows: readonly AgentRow[], connected: ReadonlySet<string>): AgentStatus[];
+/** The lines the installer prints after its wait. */
+export declare function connectionLines(rows: readonly AgentRow[], connected: ReadonlySet<string>): string[];
+/** The clock the wait runs on. Injected, so a test does not wait. */
+export interface WaitClock {
+    now(): number;
+    sleep(ms: number): Promise<void>;
+}
+/**
+ * Poll `read` until every client in `want` has connected, or `budgetMs` has passed. Returns the
+ * last read. Bounded: it never waits longer than the budget.
+ */
+export declare function waitForAgents(want: readonly string[], read: () => ReadonlySet<string>, clock: WaitClock, budgetMs: number, pollMs: number): Promise<ReadonlySet<string>>;
+/** `$CLAUDE_CONFIG_DIR`, else home: where Claude Code keeps `.claude.json`. */
+export declare function claudeStateDir(): string;
+/** What `installedAgentRows` reads. It never writes. */
+export interface AgentProbe {
+    exists(path: string): boolean;
+    readFile(path: string): string | null;
+    homeDir(): string;
+}
+/**
+ * The agents on this machine and whether Reticle is in each config, read only. For `reticle status`,
+ * which must not register anything and must not spawn a client CLI.
+ *
+ * @param claudeStateDir the directory that holds `.claude.json`: `$CLAUDE_CONFIG_DIR`, else home.
+ * @param launcher the installed bin a new registration would use, for the stale-entry fix.
+ */
+export declare function installedAgentRows(io: AgentProbe, projectDir: string | undefined, pluginActive: boolean, claudeStateDir?: string, launcher?: string): AgentRow[];

package/dist/command/setup/agent-next-steps.js

@@ -0,0 +1,284 @@
+/**
+ * One next step for each coding agent, and whether each one really connected.
+ *
+ * Registration writes a config. An agent reads that config only at a time the client decides, so
+ * "registered" is not "the agent has the tools". This file names, per client, the one step that
+ * loads the tools, and reads which agents did connect (`agents-connected.ts`) to say so.
+ *
+ * Only the Claude Code plugin gets "no restart". Its docs say `/reload-plugins` loads it. For every
+ * other client the step is the conservative one: their docs do not say a running session picks up a
+ * new server.
+ */
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { claudeAddCommand, claudeHasReticle, claudeRemoveUserCommand, claudeStaleEntryNote, claudeUserEntryIsFloating, clientSpec, codexNamesOurServer, ConfigFormat, detectMcpClients, McpClient, } from '@reticlehq/init';
+import { MCP_SERVER_NAME } from '@reticlehq/core';
+import { AgentClient } from '@reticlehq/core/telemetry';
+/** What registration did for one client. */
+export const AgentReg = {
+    /** The Claude Code plugin carries Reticle. */
+    PLUGIN: 'plugin',
+    ADDED: 'added',
+    ALREADY: 'already',
+    FAILED: 'failed',
+    MANUAL: 'manual',
+    /** Found, and Reticle is not in its config. Read-only callers (`status`) only. */
+    MISSING: 'missing',
+};
+/** The one table of client to next step. Change a step here, nowhere else. */
+const AGENT_STEPS = {
+    [McpClient.CLAUDE_CODE]: {
+        name: 'Claude Code',
+        agent: AgentClient.CLAUDE_CODE,
+        step: 'restart Claude Code, then /mcp shows reticle',
+    },
+    [McpClient.CURSOR]: {
+        name: 'Cursor',
+        agent: AgentClient.CURSOR,
+        step: 'restart Cursor, then turn Reticle on in Settings › MCP',
+    },
+    [McpClient.CODEX]: {
+        name: 'Codex',
+        agent: AgentClient.CODEX,
+        step: 'restart Codex, then /mcp shows reticle',
+    },
+    [McpClient.GEMINI]: {
+        name: 'Gemini CLI',
+        agent: AgentClient.GEMINI_CLI,
+        step: 'restart Gemini CLI, then /mcp shows reticle',
+    },
+    [McpClient.WINDSURF]: {
+        name: 'Windsurf',
+        agent: AgentClient.WINDSURF,
+        step: 'restart Windsurf, then turn Reticle on in its MCP settings',
+    },
+    [McpClient.VSCODE]: {
+        name: 'VS Code',
+        agent: AgentClient.VSCODE,
+        step: 'run "Developer: Reload Window" in VS Code',
+    },
+    [McpClient.OPENCODE]: {
+        name: 'OpenCode',
+        agent: AgentClient.OPENCODE,
+        step: 'restart OpenCode',
+    },
+    [McpClient.ANTIGRAVITY]: {
+        name: 'Antigravity',
+        agent: AgentClient.ANTIGRAVITY,
+        step: 'restart Antigravity',
+    },
+};
+const NextStepCopy = {
+    HEADING: 'Your agents:',
+    PLUGIN_ACTIVE: 'plugin active: type /reload-plugins if it is open',
+    PLUGIN_NOT_CONNECTED: 'start Claude Code, or type /reload-plugins in an open session',
+    ADDED: 'added: ',
+    ALREADY: 'already set up',
+    NOT_ADDED: 'not added: ',
+    FAILED: 'registration failed: ',
+    FAILED_FILE: 'check the permissions of its config file, then run `reticle setup mcp`',
+    MANUAL_HEAD: 'add the reticle entry to ',
+    MANUAL_TAIL: ' by hand',
+    MISSING: 'not added: run `reticle setup mcp`',
+    CONNECTED_HEAD: 'Connected: ',
+    CONNECTED_TAIL: ' ✓',
+    NOT_CONNECTED: ' not connected yet: ',
+    DUPLICATE: '    ⚠ a user-scope reticle server is registered too, so Claude Code has two. Remove it: ',
+    STALE: '    ⚠ ',
+};
+const NAME_COLUMN = Math.max(...Object.values(AGENT_STEPS).map((s) => s.name.length)) + 2;
+/**
+ * The rows for one `setupMcp` run, in its order.
+ *
+ * @param launcher the installed bin that run registered (`SetupMcpIo.launcher`), so a retry line
+ *   names the same command.
+ */
+export function agentRows(result, launcher) {
+    const known = (id) => id in AGENT_STEPS;
+    const rows = [];
+    for (const id of result.detected) {
+        if (!known(id)) {
+            continue;
+        }
+        if (result.pluginActive.includes(id)) {
+            rows.push(pluginRow(id, result.duplicates.includes(id)));
+            continue;
+        }
+        const manual = result.manual.find((m) => m.id === id);
+        if (manual !== undefined) {
+            rows.push({ id, reg: AgentReg.MANUAL, path: manual.configPath });
+        }
+        else if (result.failed.includes(id)) {
+            rows.push(McpClient.CLAUDE_CODE === id
+                ? { id, reg: AgentReg.FAILED, retry: claudeAddCommand(launcher).display }
+                : { id, reg: AgentReg.FAILED });
+        }
+        else if (result.alreadyThere.includes(id)) {
+            rows.push(alreadyRow(id, result.stale.includes(id), launcher));
+        }
+        else if (result.registered.includes(id)) {
+            rows.push({ id, reg: AgentReg.ADDED });
+        }
+    }
+    return rows;
+}
+function alreadyRow(id, stale, launcher) {
+    return stale
+        ? { id, reg: AgentReg.ALREADY, stale: claudeStaleEntryNote(launcher) }
+        : { id, reg: AgentReg.ALREADY };
+}
+function pluginRow(id, duplicate) {
+    return duplicate ? { id, reg: AgentReg.PLUGIN, duplicate } : { id, reg: AgentReg.PLUGIN };
+}
+function failedStep(row) {
+    return row.retry === undefined ? NextStepCopy.FAILED_FILE : `run \`${row.retry}\``;
+}
+/** What one row says before anything is known about the connection. */
+function registrationText(row) {
+    const { step } = AGENT_STEPS[row.id];
+    switch (row.reg) {
+        case AgentReg.PLUGIN:
+            return NextStepCopy.PLUGIN_ACTIVE;
+        case AgentReg.ADDED:
+            return `${NextStepCopy.ADDED}${step}`;
+        case AgentReg.ALREADY:
+            return NextStepCopy.ALREADY;
+        case AgentReg.FAILED:
+            return `${NextStepCopy.FAILED}${failedStep(row)}`;
+        case AgentReg.MANUAL:
+            return `${NextStepCopy.NOT_ADDED}${NextStepCopy.MANUAL_HEAD}${row.path ?? ''}${NextStepCopy.MANUAL_TAIL}`;
+        case AgentReg.MISSING:
+            return NextStepCopy.MISSING;
+    }
+}
+/** The "Your agents:" block: one line per client, each with its own next step. */
+export function agentLines(rows) {
+    if (0 === rows.length) {
+        return [];
+    }
+    return [
+        NextStepCopy.HEADING,
+        ...rows.flatMap((row) => {
+            const lines = [`  ${AGENT_STEPS[row.id].name.padEnd(NAME_COLUMN)}${registrationText(row)}`];
+            if (true === row.duplicate) {
+                lines.push(`${NextStepCopy.DUPLICATE}${claudeRemoveUserCommand()}`);
+            }
+            if (row.stale !== undefined) {
+                lines.push(`${NextStepCopy.STALE}${row.stale}`);
+            }
+            return lines;
+        }),
+    ];
+}
+/** A row whose client has Reticle in its config, so a connection can be waited for. */
+function isRegistered(row) {
+    return AgentReg.PLUGIN === row.reg || AgentReg.ADDED === row.reg || AgentReg.ALREADY === row.reg;
+}
+/** The clients worth waiting for: the ones that have Reticle registered. */
+export function awaitedClients(rows) {
+    return rows.filter(isRegistered).map((row) => AGENT_STEPS[row.id].agent);
+}
+function missingStep(row) {
+    if (AgentReg.PLUGIN === row.reg) {
+        return NextStepCopy.PLUGIN_NOT_CONNECTED;
+    }
+    if (isRegistered(row)) {
+        return AGENT_STEPS[row.id].step;
+    }
+    return registrationText(row);
+}
+/** Per client: connected, or the exact step still missing. */
+export function agentStatuses(rows, connected) {
+    return rows.map((row) => {
+        const { name, agent } = AGENT_STEPS[row.id];
+        if (isRegistered(row) && connected.has(agent)) {
+            return {
+                name,
+                connected: true,
+                said: `${NextStepCopy.CONNECTED_HEAD}${name}${NextStepCopy.CONNECTED_TAIL}`,
+            };
+        }
+        const next = missingStep(row);
+        const said = isRegistered(row)
+            ? `${name}${NextStepCopy.NOT_CONNECTED}${next}`
+            : `${name} ${next}`;
+        return { name, connected: false, next, said };
+    });
+}
+/** The lines the installer prints after its wait. */
+export function connectionLines(rows, connected) {
+    return agentStatuses(rows, connected).map((status) => status.said);
+}
+/**
+ * Poll `read` until every client in `want` has connected, or `budgetMs` has passed. Returns the
+ * last read. Bounded: it never waits longer than the budget.
+ */
+export async function waitForAgents(want, read, clock, budgetMs, pollMs) {
+    const start = clock.now();
+    let seen = read();
+    while (!want.every((client) => seen.has(client)) && clock.now() - start < budgetMs) {
+        await clock.sleep(pollMs);
+        seen = read();
+    }
+    return seen;
+}
+const CLAUDE_CONFIG_DIR_ENV = 'CLAUDE_CONFIG_DIR';
+/** `$CLAUDE_CONFIG_DIR`, else home: where Claude Code keeps `.claude.json`. */
+export function claudeStateDir() {
+    return process.env[CLAUDE_CONFIG_DIR_ENV] ?? homedir();
+}
+const CLAUDE_STATE_FILE = '.claude.json';
+/**
+ * Does this client's config name a `reticle` server, in any shape?
+ *
+ * Presence, not "the entry we would write now". An entry that starts an installed launcher, or an
+ * older npx entry, still starts Reticle. `setup mcp` repairs a stale entry; `status` only reports
+ * whether one is there. A file that does not parse reads as absent.
+ */
+function configNamesReticle(spec, existing) {
+    if (ConfigFormat.TOML === spec.format) {
+        return codexNamesOurServer(existing, spec.serversKey);
+    }
+    if (null === existing) {
+        return false;
+    }
+    try {
+        const parsed = JSON.parse(existing);
+        const servers = 'object' === typeof parsed && null !== parsed
+            ? parsed[spec.serversKey]
+            : undefined;
+        return 'object' === typeof servers && null !== servers && MCP_SERVER_NAME in servers;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The agents on this machine and whether Reticle is in each config, read only. For `reticle status`,
+ * which must not register anything and must not spawn a client CLI.
+ *
+ * @param claudeStateDir the directory that holds `.claude.json`: `$CLAUDE_CONFIG_DIR`, else home.
+ * @param launcher the installed bin a new registration would use, for the stale-entry fix.
+ */
+export function installedAgentRows(io, projectDir, pluginActive, claudeStateDir = io.homeDir(), launcher) {
+    const rows = [];
+    if (pluginActive) {
+        // A user-scope entry next to the plugin is a second server.
+        rows.push(pluginRow(McpClient.CLAUDE_CODE, claudeHasReticle(io, undefined, claudeStateDir)));
+    }
+    else if (claudeHasReticle(io, projectDir, claudeStateDir)) {
+        rows.push(alreadyRow(McpClient.CLAUDE_CODE, claudeUserEntryIsFloating(io, claudeStateDir), launcher));
+    }
+    else if (io.exists(join(claudeStateDir, CLAUDE_STATE_FILE))) {
+        rows.push({ id: McpClient.CLAUDE_CODE, reg: AgentReg.MISSING });
+    }
+    for (const client of detectMcpClients(io)) {
+        rows.push({
+            id: client.id,
+            reg: configNamesReticle(clientSpec(client.id), client.existing)
+                ? AgentReg.ALREADY
+                : AgentReg.MISSING,
+        });
+    }
+    return rows;
+}

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

@@ -13,8 +13,11 @@ import { AgentAction, AGENT_CLIENTS, joinFor, parentOf, } from './agent-configs.
 /** Two spaces, because that is what every one of these files already uses. */
 const INDENT = 2;
 const RETICLE_KEY = 'reticle';
-/** A fresh Continue config. YAML is only ever created, never edited. */
-const CONTINUE_YAML = 'mcpServers:\n  - name: reticle\n    type: stdio\n    command: npx\n    args: ["@reticlehq/server", "mcp"]\n';
+/**
+ * A fresh Continue config. YAML is only ever created, never edited. The args are a JSON array,
+ * which is valid YAML flow syntax and keeps a Windows path escaped.
+ */
+const continueYaml = (entry) => `mcpServers:\n  - name: ${RETICLE_KEY}\n    type: stdio\n    command: ${String(entry['command'])}\n    args: ${JSON.stringify(entry['args'])}\n`;
 /**
  * Write what the plan says to write, and nothing else.
  *
@@ -32,8 +35,8 @@ export function applyAgentPlan(plan, io) {
         }
         try {
             io.mkdirp(parentOf(step.file));
-            if (AgentAction.CREATE_YAML === step.action) {
-                io.writeFile(step.file, CONTINUE_YAML);
+            if (AgentAction.CREATE_YAML === step.action && undefined !== step.entry) {
+                io.writeFile(step.file, continueYaml(step.entry));
                 return { ...base, action: 'created' };
             }
             const key = step.key;
@@ -99,10 +102,12 @@ export function applyAgentSkills(io, where) {
     const join = joinFor(where.platform);
     for (const client of AGENT_CLIENTS) {
         const dir = client.skillDir;
-        if (undefined === dir)
+        if (undefined === dir) {
             continue;
-        if (!io.exists(join(where.home, client.marker[where.platform])))
+        }
+        if (!io.exists(join(where.home, client.marker[where.platform]))) {
             continue;
+        }
         try {
             const target = join(where.home, dir);
             io.mkdirp(target);

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

@@ -1,6 +1,7 @@
 import { homedir } from 'node:os';
 import { spanSync } from '../../../trace.js';
 import { hookBinFor } from '../../cli/hook/hook-fast.js';
+import { mcpLauncher } from '../mcp-launcher.js';
 import { reportInitOutcome } from '../../../telemetry/init-telemetry.js';
 import { reportOnboardingStep } from '../../../telemetry/onboarding-funnel.js';
 import { defaultPairingTokenDir, readOrCreatePairingTokenSync, } from '../../../portal/bridge/pairing-token.js';
@@ -44,6 +45,7 @@ export function serverInitHost() {
         hookBin() {
             return hookBinFor(homedir(), process.platform);
         },
+        mcpLauncher,
         insideClaudeCode() {
             return CLAUDE_CODE_MARKER_VALUE === process.env[CLAUDE_CODE_MARKER_ENV];
         },

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

@@ -53,7 +53,12 @@ interface InitRuntimeArgs {
 interface RuntimePrintIo {
     readonly print: (line: string) => void;
 }
+/**
+ * Print the "Your agents:" block, and return the bounded wait for the agents to connect. `mayWait`
+ * false: the wait is a no-op. The caller adds the terminal check. See `agentsBlock`.
+ */
+export type AgentsBlockPort = (print: (line: string) => void, mayWait: boolean) => () => Promise<void>;
 export declare function continueAfterInit(parsed: InitRuntimeArgs, result: InitResult, io: RuntimePrintIo, cwd: string, 
 /** init's ending once the connection is proved: coverage and the agent prompt. See `FirstFlowPort`. */
-firstFlow?: FirstFlowPort): Promise<void>;
+firstFlow?: FirstFlowPort, agentsBlock?: AgentsBlockPort): Promise<void>;
 export {};

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

@@ -7,7 +7,7 @@
  */
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { InitConfirmation, RETICLE_DEFAULT_PORT } from '@reticlehq/core';
+import { InitConfirmation, OnboardingPhase, OnboardingStop, RETICLE_DEFAULT_PORT, } from '@reticlehq/core';
 import { COMMUNITY_HINT, FEEDBACK_HINT, Framework, InitFailure, } from '@reticlehq/init';
 import { confirmInstall, nodeConfirmDeps } from '../terminal/confirm.js';
 import { writeLicenseKey } from '../license-key.js';
@@ -24,11 +24,14 @@ 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';
+import { reportOnboardingStop } from '../../../telemetry/onboarding-funnel.js';
 /** Claude Code marks every process it spawns with this variable set to this value. */
 const CLAUDE_CODE_ENV = 'CLAUDECODE';
 const CLAUDE_CODE_MARKER = '1';
 /** How often the runtime phases look again: fast enough not to be the wait, slow enough to be free. */
 const POLL_MS = 250;
+/** The step an agent without the `reticle_*` tools cannot take. */
+const FIRST_LOOK_STEP = 'first_look';
 /**
  * The shapes whose served HTML carries the SDK marker: Vite injects it into index.html, and a plain
  * HTML page has the snippet pasted in. Everything else connects from the JS bundle, where a fetch
@@ -47,8 +50,9 @@ const NEXT_APP_CONNECT = ['app', 'src/app'].flatMap((d) => ['tsx', 'jsx', 'js'].
  * names chunks, not modules, so it stays silent.
  */
 export function htmlCarriesSdk(framework, exists) {
-    if (HTML_CARRIES_SDK.has(framework))
+    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. */
@@ -68,8 +72,9 @@ const licenseIo = {
  * thing as an install working.
  */
 function printRelaunch(parsed, io, cwd) {
-    if (true !== parsed.relaunch)
+    if (true !== parsed.relaunch) {
         return;
+    }
     io.print(relaunchDecision({
         ...(undefined === process.env['CLAUDE_CODE_SESSION_ID']
             ? {}
@@ -82,13 +87,15 @@ function printRelaunch(parsed, io, cwd) {
 }
 export async function continueAfterInit(parsed, result, io, cwd, 
 /** init's ending once the connection is proved: coverage and the agent prompt. See `FirstFlowPort`. */
-firstFlow) {
+firstFlow, agentsBlock) {
     const port = parsed.port ?? RETICLE_DEFAULT_PORT;
     const stop = () => {
-        if (true === parsed.keepGoing)
+        if (true === parsed.keepGoing) {
             process.exitCode = 1;
-        else
+        }
+        else {
             process.exit(1);
+        }
     };
     // 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.
@@ -114,16 +121,19 @@ firstFlow) {
             registerOtherAgents(io.print);
         }
         return confirmInstall(result, io, nodeConfirmDeps(port)).then(() => {
-            if (true === parsed.json)
+            if (true === parsed.json) {
                 process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-            if (!result.ok)
+            }
+            if (!result.ok) {
                 stop();
+            }
         });
     }
     // From here on init left the ask to us, so it is the last thing on every exit below.
     const ask = (spaced = true) => {
-        if (spaced)
+        if (spaced) {
             io.print('');
+        }
         io.print(FEEDBACK_HINT);
     };
     // `init` deferred its outcome to this phase, so every exit below reports it, and only once: the
@@ -131,8 +141,9 @@ firstFlow) {
     // would double the funnel this event exists to measure.
     let outcomeReported = false;
     const reportOnce = (init) => {
-        if (outcomeReported)
+        if (outcomeReported) {
             return;
+        }
         outcomeReported = true;
         reportInitOutcome(init);
     };
@@ -140,11 +151,13 @@ firstFlow) {
     if (context === undefined) {
         // Nothing was established, so there is nothing to run against. init has already said why, and
         // the outcome it deferred (a failed dependency install, usually) is reported here or nowhere.
-        if (result.outcome !== undefined)
+        if (result.outcome !== undefined) {
             reportOnce(result.outcome);
+        }
         ask();
-        if (true === parsed.json)
+        if (true === parsed.json) {
             process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        }
         stop();
         return;
     }
@@ -188,6 +201,9 @@ firstFlow) {
     // A Ctrl-C during the wait ends the process with no `finally`, so the outcome is reported from the
     // signal itself. The send is detached, so it survives the exit that follows.
     const releaseInterrupt = reportOnInterrupt(() => reportFailure(InitFailure.INTERRUPTED));
+    // The wait for the agents runs last, after the interrupt handler is gone: a Ctrl+C that skips the
+    // wait is not a failed init.
+    let waitForAgents = () => Promise.resolve();
     return runSetupCommand({
         appDir: context.appDir,
         invokedAt: cwd,
@@ -217,10 +233,12 @@ firstFlow) {
         // 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".
         ...(() => {
-            if (undefined !== context.devCommand)
+            if (undefined !== context.devCommand) {
                 return { devCommand: context.devCommand };
-            if (undefined !== parsed.url)
+            }
+            if (undefined !== parsed.url) {
                 return {};
+            }
             const devCommand = staticPageDevCommand({
                 appDir: context.appDir,
                 isStaticPage: Framework.HTML === context.framework,
@@ -249,16 +267,18 @@ firstFlow) {
                     outcome.reachedPhase === SetupPhase.DEV_SERVER
                         ? InitFailure.DEV_SERVER
                         : InitFailure.APP_CONNECTION;
-                if (outcome.stop !== undefined)
+                if (outcome.stop !== undefined) {
                     init.stop = outcome.stop;
+                }
             }
             reportOnce(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`);
-            if (!outcome.ok)
+            if (!outcome.ok) {
                 stop();
+            }
             return;
         }
         io.print('');
@@ -274,7 +294,18 @@ firstFlow) {
         });
         if (undefined !== restart) {
             io.print(restart);
+            // The same block and wait as `reticle setup mcp`. No wait for a failed setup, or inside
+            // `reticle connect`, which signs in next.
+            if (agentsBlock !== undefined) {
+                waitForAgents = agentsBlock(io.print, outcome.ok && true !== parsed.keepGoing);
+            }
             io.print('');
+            // The agent cannot take its first look until it restarts. Detached: init exits soon.
+            reportOnboardingStop({
+                phase: OnboardingPhase.ONBOARD,
+                step: FIRST_LOOK_STEP,
+                stop: OnboardingStop.AGENT_NOT_RESTARTED,
+            }, { detach: true });
         }
         if (outcome.ok && !outcome.flowSaved) {
             // Success, and no flow. Saying "a flow was driven" here would replace a wrong exit code with
@@ -282,8 +313,9 @@ firstFlow) {
             // sentence is read by a person deciding whether their app is verified. It is not.
             // The connect already said "connected, nothing verified yet" and listed what to do next;
             // repeating it here was the same sentence twice, three lines apart.
-            for (const [i, step] of outcome.fallback.entries())
+            for (const [i, step] of outcome.fallback.entries()) {
                 io.print(`   ${String(i + 1)}. ${step}`);
+            }
             // Already spaced by the blank line above when nothing was listed.
             ask(0 < outcome.fallback.length);
             io.print(COMMUNITY_HINT);
@@ -299,15 +331,17 @@ firstFlow) {
         // A run that produced no verdict did not succeed, and the exit code is the one place a caller
         // reads that without parsing anything.
         io.print('⚠ setup did not finish. To carry on from here:');
-        for (const [i, step] of outcome.fallback.entries())
+        for (const [i, step] of outcome.fallback.entries()) {
             io.print(`   ${i + 1}. ${step}`);
+        }
         ask();
         stop();
     }, (error) => {
         reportFailure(InitFailure.RUNTIME_ERROR);
         throw error;
     })
-        .finally(releaseInterrupt);
+        .finally(releaseInterrupt)
+        .then(() => waitForAgents());
 }
 const INTERRUPT_SIGNALS = ['SIGINT', 'SIGTERM'];
 /** 128 + the signal number, which is what a shell reports. */
@@ -319,14 +353,16 @@ function reportOnInterrupt(report) {
             report();
             // Before setup installs its own handler ours may be the only one, and a listener present
             // means Node no longer exits on the signal by itself: without this, Ctrl-C would be ignored.
-            if (1 === process.listenerCount(signal))
+            if (1 === process.listenerCount(signal)) {
                 process.exit(INTERRUPT_EXIT_CODE[signal]);
+            }
         };
         process.on(signal, handler);
         return { signal, handler };
     });
     return () => {
-        for (const { signal, handler } of handlers)
+        for (const { signal, handler } of handlers) {
             process.off(signal, handler);
+        }
     };
 }

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

@@ -0,0 +1,3 @@
+/** `bin/reticle.js`, from `dist/command/setup/mcp-launcher.js`. The real path, not a symlink. */
+export declare const CLI_BIN: string;
+export declare function mcpLauncher(): string | undefined;

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

@@ -0,0 +1,11 @@
+/**
+ * The bin that agent configs start the MCP server from, when this CLI is an install that stays on
+ * disk. Undefined for npx's cache and other run-once copies: see `installedLauncher` in init.
+ */
+import { fileURLToPath } from 'node:url';
+import { installedLauncher } from '@reticlehq/init';
+/** `bin/reticle.js`, from `dist/command/setup/mcp-launcher.js`. The real path, not a symlink. */
+export const CLI_BIN = fileURLToPath(new URL('../../../bin/reticle.js', import.meta.url));
+export function mcpLauncher() {
+    return installedLauncher(CLI_BIN);
+}