@reticlehq/server 2.14.0 → 3.2.0

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

@@ -0,0 +1,176 @@
+/**
+ * `reticle mcp` — the process an editor launches, and the one whose failure a user experiences as
+ * "the MCP server disconnected".
+ *
+ * Split out of `cli.ts` when that file passed the 1000-line backstop. It earns its own module rather
+ * than being an arbitrary slice: everything here is about ONE decision — which daemon this agent
+ * talks to for the rest of its life — and the port resolution at the top is the fix for agents on
+ * different projects silently sharing one daemon, one identity and one blast radius.
+ */
+import { log } from '../../log.js';
+import { isAlive, spawnDaemon, reticleStateHome } from '../daemon/daemon.js';
+import { PortPresence, probePresence, presenceIsUsable, describePresence, } from '../daemon/binding/port-presence.js';
+import { waitForDaemon, startMcpProxy, probeDaemon, proxyLog, setProxyLogPort, } from '../../surface/mcp/mcp-proxy.js';
+import { installProxyResilience } from '../daemon/daemon-resilience.js';
+import { readProjectId } from './ports/resolve/cli-port.js';
+import { resolveMcpPort, daemonProjectAt } from '../daemon/daemon-resolve.js';
+import { daemonSpawnArgs } from './daemon-start-options.js';
+import { WakeAction, decideWake } from '../daemon/wake-decision.js';
+import { pickDaemonPortToBind } from '../daemon/binding/free-port.js';
+import { fetchStatus } from '../daemon/binding/daemon-status-probe.js';
+import { migrateApprovals } from '../setup/approval-migration.js';
+import { ReticleEnv } from '@reticlehq/core';
+import { agentIo } from '../setup/agent-io.js';
+import { SERVER_VERSION } from '../version/identity/server-version.js';
+import { homedir } from 'node:os';
+/**
+ * MCP proxy mode: ensures the daemon is running, then bridges Claude Code's
+ * stdin/stdout to the daemon's SSE endpoint. This is the recommended way to
+ * configure Reticle in.mcp.json — users never need to manage the daemon manually.
+ *
+ * Pass --drive <url> to have the daemon launch its own Playwright browser at that
+ * URL. The agent then has full autonomous control without relying on the user's browser.
+ */
+export async function handleMcp(opts) {
+    const { driveUrl, headless, http, httpPort, httpToken } = opts;
+    // Decided before anything else, because every line below is about ONE port and the wrong one means
+    // serving another project's daemon. `resolveMcpPort` prefers our own daemon wherever it moved to,
+    // takes the requested port when it is free or unclaimed, and relocates to an OS-assigned port
+    // rather than adopting a daemon that belongs to somebody else.
+    //
+    // Synchronous-looking on purpose: a probe is one loopback connect, and doing it here keeps the
+    // proxy's transport built around a single fixed number. Making the proxy chase a moving port would
+    // mean reworking the reconnect path, which is the one piece whose failure reads to a user as
+    // "the MCP server disappeared mid-session".
+    // Read once and reused by the wake path below: the boot resolution and every later wake must be
+    // defending the SAME identity, and computing it twice is how they drift apart.
+    // Before the port work, because it is the only moment we are guaranteed to get on a machine that
+    // installed Reticle before the pre-approval rules existed. Once per version, never a create that
+    // supersedes an allowlist we cannot read, and it cannot throw: see approval-migration.
+    // A sandboxed state dir means a test, a gate or a fixture, none of which are asking us to rewrite
+    // the real user's editor configuration.
+    if (undefined === process.env[ReticleEnv.STATE_DIR]) {
+        migrateApprovals({
+            io: agentIo,
+            home: homedir(),
+            platform: process.platform,
+            stateHome: reticleStateHome(),
+            version: SERVER_VERSION,
+            log,
+        });
+    }
+    const projectId = readProjectId(process.cwd());
+    const port = await resolveMcpPort(opts.port, projectId, reticleStateHome(), {
+        alive: isAlive,
+        daemonPresent: async (p) => presenceIsUsable(await probePresence(p, { tcpOpen: probeDaemon, status: fetchStatus })),
+        pickPort: (p) => pickDaemonPortToBind(p),
+    });
+    if (port !== opts.port) {
+        log('reticle_mcp_port_relocated', {
+            requested: opts.port,
+            port,
+            reason: 'the requested port serves a different project',
+        });
+    }
+    // The proxy IS the MCP server the editor launched. Nothing respawns it, so an uncaught throw here
+    // is what a user experiences as "the MCP server disconnected — open /mcp and reconnect". Log it,
+    // report it, keep serving: the reconnect and dormant paths already know how to rebuild the only
+    // state this process has. See installProxyResilience for why its rule inverts the daemon's.
+    // The proxy's crash handlers must write to the proxy's LOG FILE, not just stderr. The editor
+    // swallows stderr, so wiring these to `log` meant a crash was handled and then unrecorded — the
+    // failure a user reports as "it disconnected" left nothing behind to read.
+    setProxyLogPort(port);
+    const resilience = installProxyResilience(process, proxyLog);
+    /**
+     * Make sure a daemon is on the port, spawning one if not.
+     *
+     * Called on first start AND on every reconnect. The proxy used to only retry the socket, so a
+     * daemon that exited — crashed, `reticle stop`, or self-shut-down as idle — meant the retries hit
+     * a dead port until the budget ran out and the agent's MCP server exited with it. Reticle simply
+     * disappeared mid-session with nothing said. Respawning here makes the reconnect self-healing.
+     */
+    const ensure = async () => {
+        // The same question every other surface asks. It used to be a bare TCP connect, so a stranger on
+        // the bridge port answered "a daemon is here" — the proxy connected, the stream ended, and each
+        // client request woke into the identical non-answer. Rejecting here is what puts the proxy
+        // dormant with a reason, instead of pretending the wake succeeded.
+        const presence = await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus });
+        // Identity, not just presence. `resolveMcpPort` above already refuses to adopt a stranger's
+        // daemon at boot; this is the same question asked on every WAKE, which is where it was missing.
+        //
+        // Reachable by ordinary use, with no error anywhere: a daemon retires on its idle timer and
+        // frees the port, another project's daemon binds it, and this project's dormant proxy wakes
+        // straight onto it. The agent then drives, asserts and reports a verdict about a DIFFERENT
+        // APPLICATION. That is worse than the disconnect it was reintroduced under the cover of, because
+        // a disconnect is visible and this is a false green wearing a valid session.
+        const wake = decideWake(presence, daemonProjectAt(port, reticleStateHome()), projectId);
+        if (WakeAction.USE === wake)
+            return;
+        if (WakeAction.REFUSE === wake) {
+            throw new Error(PortPresence.DAEMON === presence
+                ? `the daemon on port ${String(port)} belongs to a different project, so this one will ` +
+                    'not adopt it. Stop it, or start this project on its own port.'
+                : describePresence(presence, port));
+        }
+        const scriptPath = process.argv[1];
+        if (scriptPath === undefined) {
+            log('reticle_mcp_no_script', {});
+            process.exit(1);
+        }
+        const daemonArgs = daemonSpawnArgs({
+            port,
+            headless,
+            http,
+            ...(driveUrl !== undefined ? { driveUrl } : {}),
+            ...(httpPort !== undefined ? { httpPort } : {}),
+            ...(httpToken !== undefined ? { httpToken } : {}),
+        });
+        spawnDaemon(process.execPath, scriptPath, daemonArgs, port);
+        // Announce the daemon only once the PORT ACCEPTS. This line used to be written the instant the
+        // child was spawned, which on a Windows first bootstrap meant `reticle_mcp_daemon_started`
+        // followed about ten seconds later by `reticle_mcp_daemon_unavailable` and a first
+        // `reticle_sessions` that expired. A readiness signal that precedes readiness is worse than
+        // none: a client that believes it stops waiting for the thing that has not happened.
+        await waitForDaemon(port);
+        log('reticle_mcp_daemon_started', { port, ...(driveUrl !== undefined ? { driveUrl } : {}) });
+    };
+    // Start the proxy WHATEVER happened to the daemon.
+    //
+    // This used to exit(1) when `ensure` failed, which is the third way an MCP server disappears on a
+    // user: something else is holding the bridge port — a foreign daemon from another project, a
+    // half-dead process, a port a colleague's tool grabbed — the spawned daemon cannot bind, and the
+    // editor shows a server that failed to start. Nothing about that is unrecoverable: the proxy
+    // answers `initialize` itself, serves the cached catalog, and its wake path retries a daemon on
+    // every client request. Present-and-complaining beats absent, because absent needs a human.
+    // `void`: the chain handles its own failure and the process must not wait on it — the proxy is
+    // started from `finally` either way.
+    void ensure()
+        .catch((err) => {
+        log('reticle_mcp_daemon_unavailable', {
+            error: err instanceof Error ? err.message : String(err),
+            note: 'serving anyway — the next tool call will try to start a daemon again',
+        });
+    })
+        .finally(() => {
+        // Also `void`: the proxy runs for the life of the process and is never awaited by anyone.
+        //
+        // The `.catch` is load-bearing despite that. `startMcpProxy` rejects when its FIRST connect
+        // fails — which is precisely the case this block exists to tolerate, a daemon that is not
+        // there yet — and with nothing attached that reject became an unhandledRejection. Reported
+        // from a win32 user as a crash reading `connect ECONNREFUSED` with an EMPTY frame list,
+        // because the stack of a refused socket is entirely node internals and the privacy filter
+        // keeps only Reticle frames. So the one path we most want diagnosable arrived as an anonymous
+        // crash. The proxy itself is unaffected — it has already installed its stdin reader and goes
+        // on serving from cache, waking a daemon on the next request — which is exactly why this
+        // must be logged as the expected condition it is rather than reported as a defect.
+        void startMcpProxy(port, ensure, undefined, () => {
+            resilience.noteUsableSession();
+        }).catch((err) => {
+            log('reticle_mcp_proxy_first_connect_failed', {
+                port,
+                error: err instanceof Error ? err.message : String(err),
+                note: 'serving from cache; the next client request will try to start a daemon',
+            });
+        });
+    });
+}

package/dist/command/cli/ports/port-holder.js

@@ -0,0 +1,123 @@
+/**
+ * Who is holding the bridge port.
+ *
+ * `doctor` is what a user runs when the agent cannot reach the bridge, and the commonest real cause
+ * is that something else is on 4400. It already stopped saying "nothing is listening" for that case,
+ * but it did not say WHICH process — so the reader's next move was a shell command they had to know.
+ *
+ * Naming the holder is also the safe answer to a trap this project has hit for real: the obvious
+ * lookup, `lsof -ti tcp:4400 | xargs kill -9`, ALSO kills the agent's own `reticle mcp` proxy,
+ * because that proxy holds a client connection to the same port and `-ti` does not filter to
+ * listeners. Every invocation here is `-sTCP:LISTEN`, and the message never suggests `-ti`.
+ *
+ * The parser is pure and the lookup takes an injected exec, so the rule is tested on every platform
+ * while the shelling out stays at the call site.
+ */
+import { spawnSync } from 'node:child_process';
+/** Bound on the holder lookup. A hung `lsof` must not hang the commands that diagnose hangs. */
+const LOOKUP_TIMEOUT_MS = 2_000;
+/**
+ * Run a lookup and return its stdout, or null if it could not run.
+ *
+ * Null on ANY failure — no lsof (every Windows user, a slim container), a non-zero exit, a throw.
+ * This is a diagnostic nicety inside the commands people run when things are already broken; it must
+ * never be the reason one of them fails. Every caller handles the null by saying it could not
+ * identify the holder, rather than asserting the holder is not ours — a claim it has no evidence
+ * for, and one that was wrong for every Windows user.
+ */
+export function captureLookup(command, args) {
+    try {
+        const result = spawnSync(command, [...args], { encoding: 'utf8', timeout: LOOKUP_TIMEOUT_MS });
+        return 0 === result.status && 'string' === typeof result.stdout ? result.stdout : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** `lsof -F pc` emits one field per line, prefixed by its selector: `p<pid>`, `c<command>`. */
+const PID_FIELD = 'p';
+const COMMAND_FIELD = 'c';
+/**
+ * The FIRST listener in `lsof -nP -iTCP:<port> -sTCP:LISTEN -F pc` output, or null.
+ *
+ * First, not "the only one": a dual-stack listener (IPv4 + IPv6) is reported twice, and on a port
+ * conflict the answer the reader needs is "something is there, here is what" rather than an
+ * exhaustive list. A second `p` record ends the first.
+ *
+ * Null on anything incomplete. Half an answer — a pid with no command — prints worse than the
+ * un-named message it would replace, which is the same mistake as the port lie this command fixed.
+ */
+export function parsePortHolder(stdout) {
+    let pid;
+    let command;
+    for (const raw of stdout.split('\n')) {
+        const line = raw.trim();
+        if (0 === line.length)
+            continue;
+        const value = line.slice(1);
+        if (line.startsWith(PID_FIELD)) {
+            if (pid !== undefined)
+                break; // a second record: the first one is the answer
+            const parsed = Number(value);
+            if (!Number.isInteger(parsed) || parsed <= 0)
+                return null;
+            pid = parsed;
+            continue;
+        }
+        if (line.startsWith(COMMAND_FIELD) && command === undefined)
+            command = value;
+    }
+    return pid === undefined || command === undefined ? null : { pid, command };
+}
+/** What `doctor` prints for a port held by something that is not a Reticle daemon. */
+export function describeForeignHolder(port, holder, 
+/**
+ * The pid we recorded for this port, from the daemon pid file.
+ *
+ * When it matches the process actually holding the port, the port is held by OUR daemon — one
+ * that accepts TCP and never answers `/status`, i.e. wedged. That classifies as FOREIGN, which is
+ * right for "can anything bind this?" and wrong to say out loud: the reader goes hunting a
+ * stranger, and the fix that works (`reticle stop`, it respawns on the next call) is never named.
+ */
+ourPid) {
+    // Naming the command matters more than naming the process. "Stop that process" describes an
+    // outcome and leaves the reader to invent a route to it, and the route they invent is the `-ti`
+    // pipeline that takes their agent's proxy down with the holder.
+    const tail = 'a daemon cannot bind it. Free it with `reticle kill --force` (it signals the listener only, ' +
+        "never the agent's mcp proxy), or run Reticle on a different port (`--port`), then retry.";
+    if (null === holder) {
+        /**
+         * We could not identify the holder — no `lsof` (every Windows user, a large share of the
+         * installed base; also a slim container), or the lookup timed out.
+         *
+         * This used to assert the port was held by "another process that is not a Reticle daemon",
+         * which is a claim the null case has NO evidence for. It is also the likeliest thing to be
+         * wrong: reaching here at all means presence is FOREIGN — the port accepts TCP and never
+         * answers `/status` — and the commonest cause of that is OUR OWN daemon, wedged. So on the one
+         * platform where the lookup cannot run, `doctor` sent the reader hunting a stranger and never
+         * named `reticle stop`, the fix that actually works.
+         *
+         * Say what is known, and name the recorded pid when there is one.
+         */
+        const ours = ourPid !== null && ourPid !== undefined
+            ? ` Reticle's own records show pid ${String(ourPid)} for this port — if that process is ` +
+                'still around it is a wedged Reticle daemon, and `reticle stop` clears it.'
+            : '';
+        return `port ${String(port)} is held by a process Reticle could not identify — ${tail}${ours}`;
+    }
+    if (ourPid !== null && ourPid !== undefined && ourPid === holder.pid) {
+        return (`port ${String(port)} is held by YOUR Reticle daemon (pid ${String(holder.pid)}), and it is ` +
+            'not responding — running but wedged, so nothing can use it and nothing else can bind the ' +
+            'port. Stop it with `reticle stop`; the next tool call starts a fresh one.');
+    }
+    return (`port ${String(port)} is held by pid ${String(holder.pid)} ("${holder.command}"), which is not ` +
+        `a Reticle daemon — ${tail}`);
+}
+/** The lookup itself. `exec` is injected so the shelling out never runs in a unit test. */
+export function findPortHolder(port, exec) {
+    // -n/-P skip DNS and service-name lookups (slow, and irrelevant here). -sTCP:LISTEN is the part
+    // that matters: without it this also reports the agent's own MCP proxy, which is a client of the
+    // port, not its owner.
+    const out = exec('lsof', ['-nP', `-iTCP:${String(port)}`, '-sTCP:LISTEN', '-F', 'pc']);
+    return null === out ? null : parsePortHolder(out);
+}

package/dist/command/cli/ports/resolve/cli-port.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Port resolution for the reticle CLI. Split out so it can be unit-tested independently.
+ *
+ * Priority (highest → lowest):
+ * 1. --port flag (parsed by parseCliArgs, already overrides defaultPort)
+ * 2. RETICLE_PORT env var
+ * 3..reticle.json "port" field in the cwd ← per-project isolation
+ * 4. RETICLE_DEFAULT_PORT (4400)
+ */
+import { type ProjectId } from '@reticlehq/core';
+/** The project config `reticle init` writes. */
+export declare const RETICLE_CONFIG_BASENAME = ".reticle.json";
+/**
+ * Find the nearest `.reticle.json` at or above `cwd`, and return its parsed contents.
+ *
+ * Every reader below used to join the basename onto `cwd` and stop there, so a process whose
+ * working directory was one level away from the config behaved exactly like a project that had
+ * never been through `init`: no port, no projectId, no journal setting, and a diagnostic that told
+ * the user to run an install they had already run. Every layout that hits it — an app wired in a
+ * subdirectory, an agent running from a repo root, a worktree beside its
+ * main checkout — and they are all the same missing walk.
+ *
+ * Returns undefined when nothing is found, which keeps every caller's existing default intact.
+ */
+export declare function findProjectConfig(cwd: string): Record<string, unknown> | undefined;
+/**
+ * The dev-server port heuristics live in `@reticlehq/init` — `existing-config.ts` is what diagnoses
+ * a `.reticle.json` whose `port` is the app's own dev-server port, and the scaffolder may not import
+ * the daemon. Re-exported here so the runtime readers (the dev-server probe, the no-session
+ * diagnosis, and `cli.ts`) are unchanged.
+ */
+export { DEV_SERVER_PORTS, isLikelyDevServerPort, devServerPortWarning } from '@reticlehq/init';
+/**
+ * Read the port stored in the project's .reticle.json (written by `reticle init`).
+ * Returns undefined if the file is absent, unreadable, or has no valid numeric port.
+ */
+export declare function readProjectPort(cwd: string): number | undefined;
+/**
+ * Read the stable projectId stored in the project's .reticle.json (written by `reticle init`). The daemon
+ * uses it as the default resolve scope so auto-selection stays within the active app. Returns
+ * undefined if the file is absent/unreadable or has no non-empty string projectId.
+ */
+export declare function readProjectId(cwd: string): ProjectId | undefined;
+/**
+ * The framework `reticle init` stamped into `.reticle.json`, when there is one.
+ *
+ * Read so the no-session diagnosis can RANK its causes instead of printing one static differential.
+ * Nuxt is the case that pays for this: it does not register a newly added plugin on HMR, so a dev
+ * server older than the wiring is its single most likely cause — `init` warns about it at install
+ * time and the hint the agent reads hours later never mentioned it.
+ */
+export declare function readProjectFramework(cwd: string): string | undefined;
+/**
+ * Whether the durable causal journal is enabled. On by default (the journal IS the loop); off only via
+ * explicit opt-out — `.reticle.json` `"journal": false`, or `RETICLE_JOURNAL` set to `0`/`false`. The env
+ * wins so CI/tests can force it off without editing the project file.
+ */
+export declare function readJournalEnabled(cwd: string, env: string | undefined): boolean;
+/**
+ * Resolve the daemon port from all available sources in priority order.
+ * Pass `portFlag` when the user explicitly supplied --port; pass `undefined` to fall through.
+ */
+export declare function resolvePort(portFlag: number | undefined, envPort: number | undefined, projectPort: number | undefined, defaultPort: number): number;
+/**
+ * Detect a port mismatch between the daemon and the project's SDK configuration.
+ *
+ * Returns a diagnostic string when the daemon port differs from what `.reticle.json` declares.
+ * The SDK reads `.reticle.json` at build/connect time, so a mismatch means the app will dial a
+ * port nothing is listening on — the silent no-connect that #261 documents.
+ */
+export declare function diagnosePortMismatch(daemonPort: number, projectPort: number | undefined): string | undefined;

package/dist/command/cli/ports/resolve/cli-port.js

@@ -0,0 +1,140 @@
+/**
+ * Port resolution for the reticle CLI. Split out so it can be unit-tested independently.
+ *
+ * Priority (highest → lowest):
+ * 1. --port flag (parsed by parseCliArgs, already overrides defaultPort)
+ * 2. RETICLE_PORT env var
+ * 3..reticle.json "port" field in the cwd ← per-project isolation
+ * 4. RETICLE_DEFAULT_PORT (4400)
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { asProjectId } from '@reticlehq/core';
+/** The project config `reticle init` writes. */
+export const RETICLE_CONFIG_BASENAME = '.reticle.json';
+/**
+ * How far up to look for the project config before giving up.
+ *
+ * A cap rather than "walk to the filesystem root" so a process started somewhere unrelated cannot
+ * silently adopt a config from a distant ancestor and dial a port that belongs to another project.
+ * Deep enough for the layouts that actually broke: an app in `frontend/` or `apps/web/`, a git
+ * worktree checked out beside its main repo, and an agent whose cwd is a package inside a monorepo.
+ */
+const MAX_CONFIG_SEARCH_DEPTH = 6;
+/**
+ * Find the nearest `.reticle.json` at or above `cwd`, and return its parsed contents.
+ *
+ * Every reader below used to join the basename onto `cwd` and stop there, so a process whose
+ * working directory was one level away from the config behaved exactly like a project that had
+ * never been through `init`: no port, no projectId, no journal setting, and a diagnostic that told
+ * the user to run an install they had already run. Every layout that hits it — an app wired in a
+ * subdirectory, an agent running from a repo root, a worktree beside its
+ * main checkout — and they are all the same missing walk.
+ *
+ * Returns undefined when nothing is found, which keeps every caller's existing default intact.
+ */
+export function findProjectConfig(cwd) {
+    let dir = resolve(cwd);
+    for (let depth = 0; depth <= MAX_CONFIG_SEARCH_DEPTH; depth += 1) {
+        try {
+            const raw = readFileSync(`${dir}/${RETICLE_CONFIG_BASENAME}`, 'utf8');
+            const config = JSON.parse(raw);
+            if ('object' === typeof config && config !== null && !Array.isArray(config)) {
+                return config;
+            }
+        }
+        catch {
+            // Absent, unreadable, or not JSON at this level — keep walking.
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return undefined;
+}
+/**
+ * The dev-server port heuristics live in `@reticlehq/init` — `existing-config.ts` is what diagnoses
+ * a `.reticle.json` whose `port` is the app's own dev-server port, and the scaffolder may not import
+ * the daemon. Re-exported here so the runtime readers (the dev-server probe, the no-session
+ * diagnosis, and `cli.ts`) are unchanged.
+ */
+export { DEV_SERVER_PORTS, isLikelyDevServerPort, devServerPortWarning } from '@reticlehq/init';
+/**
+ * Read the port stored in the project's .reticle.json (written by `reticle init`).
+ * Returns undefined if the file is absent, unreadable, or has no valid numeric port.
+ */
+export function readProjectPort(cwd) {
+    const p = findProjectConfig(cwd)?.['port'];
+    if ('number' === typeof p && Number.isInteger(p) && p > 0 && p < 65536)
+        return p;
+    return undefined;
+}
+/**
+ * Read the stable projectId stored in the project's .reticle.json (written by `reticle init`). The daemon
+ * uses it as the default resolve scope so auto-selection stays within the active app. Returns
+ * undefined if the file is absent/unreadable or has no non-empty string projectId.
+ */
+export function readProjectId(cwd) {
+    const id = findProjectConfig(cwd)?.['projectId'];
+    // MINTED HERE. The other provenance boundary: the `projectId` key of a project's own
+    // `.reticle.json`. Like HELLO's field, it is a project's id because of WHERE it was read, not
+    // because of what it looks like.
+    if ('string' === typeof id && id.length > 0)
+        return asProjectId(id);
+    return undefined;
+}
+/**
+ * The framework `reticle init` stamped into `.reticle.json`, when there is one.
+ *
+ * Read so the no-session diagnosis can RANK its causes instead of printing one static differential.
+ * Nuxt is the case that pays for this: it does not register a newly added plugin on HMR, so a dev
+ * server older than the wiring is its single most likely cause — `init` warns about it at install
+ * time and the hint the agent reads hours later never mentioned it.
+ */
+export function readProjectFramework(cwd) {
+    const framework = findProjectConfig(cwd)?.['framework'];
+    if ('string' === typeof framework && framework.length > 0)
+        return framework;
+    return undefined;
+}
+/**
+ * Whether the durable causal journal is enabled. On by default (the journal IS the loop); off only via
+ * explicit opt-out — `.reticle.json` `"journal": false`, or `RETICLE_JOURNAL` set to `0`/`false`. The env
+ * wins so CI/tests can force it off without editing the project file.
+ */
+export function readJournalEnabled(cwd, env) {
+    if (env !== undefined) {
+        const v = env.trim().toLowerCase();
+        if ('0' === v || 'false' === v || 'off' === v)
+            return false;
+        if ('1' === v || 'true' === v || 'on' === v)
+            return true;
+    }
+    if (false === findProjectConfig(cwd)?.['journal'])
+        return false;
+    return true;
+}
+/**
+ * Resolve the daemon port from all available sources in priority order.
+ * Pass `portFlag` when the user explicitly supplied --port; pass `undefined` to fall through.
+ */
+export function resolvePort(portFlag, envPort, projectPort, defaultPort) {
+    return portFlag ?? envPort ?? projectPort ?? defaultPort;
+}
+/**
+ * Detect a port mismatch between the daemon and the project's SDK configuration.
+ *
+ * Returns a diagnostic string when the daemon port differs from what `.reticle.json` declares.
+ * The SDK reads `.reticle.json` at build/connect time, so a mismatch means the app will dial a
+ * port nothing is listening on — the silent no-connect that #261 documents.
+ */
+export function diagnosePortMismatch(daemonPort, projectPort) {
+    if (projectPort === undefined)
+        return undefined;
+    if (projectPort === daemonPort)
+        return undefined;
+    return (`.reticle.json says "port": ${String(projectPort)} but this daemon is on :${String(daemonPort)}` +
+        ` — the SDK will dial :${String(projectPort)} and never connect. ` +
+        `Either start the daemon with --port ${String(projectPort)}, or update .reticle.json to match.`);
+}

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

@@ -0,0 +1,29 @@
+import type { OnboardingStep } from '@reticlehq/core/telemetry';
+/**
+ * The terminal half of `reticle setup mcp`.
+ *
+ * The decision it makes and the IO it needs are split, so the decision is testable without a home
+ * directory — the same shape `init` uses, and for the same reason: every setup bug worth catching
+ * has been in what gets WRITTEN and where, which is exactly the part a real filesystem hides.
+ */
+/**
+ * The reporter arrives from the CALLER, one more level up than it feels like it should.
+ *
+ * `cli/` does not reach `telemetry/` and adding that edge made a mutual pair — two directories that
+ * each need the other cannot be read, moved or tested apart. `command/` already reaches telemetry,
+ * so the entry point supplies it and every layer below stays a function of its arguments.
+ */
+export type StepReporter = (step: OnboardingStep) => void;
+export declare function handleSetupMcp(reportStep: StepReporter, standalone?: boolean): void;
+/**
+ * `reticle setup install` — the Node half of the one-line installer.
+ *
+ * Reports what the shell measured, then does the thing the shell deliberately does not: register
+ * with the coding agents on this machine. One implementation, so the Windows launcher is a handful
+ * of lines that cannot meaningfully drift from this one.
+ */
+export declare function handleSetupInstall(opts: {
+    runtimeSecs: number;
+    installSecs: number;
+    mcp: boolean;
+}, reportStep: StepReporter): void;

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

@@ -0,0 +1,107 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { probeCli } from '@reticlehq/init';
+import { installClosing, tutorialShownSteps } from './tutorial.js';
+import { setupMcp, knownClientLabels } from '../setup/setup-mcp.js';
+import { reportInstallSteps } from '../setup/setup-install.js';
+import { registerOtherAgents } from '../setup/setup-command.js';
+export function handleSetupMcp(reportStep, standalone = true) {
+    const io = {
+        exists: (p) => existsSync(p),
+        readFile: (p) => {
+            try {
+                return readFileSync(p, 'utf8');
+            }
+            catch {
+                return null;
+            }
+        },
+        writeFile: (p, contents) => {
+            mkdirSync(dirname(p), { recursive: true });
+            writeFileSync(p, contents);
+        },
+        homeDir: () => homedir(),
+        print: (line) => process.stdout.write(`${line}\n`),
+        reportStep,
+        // `probeCli`, not a bare `execFileSync`: on Windows `claude` is a `.cmd` shim that cannot be
+        // spawned without a shell, so the plain call threw ENOENT for every Windows user and the
+        // installer reported their machine had no coding agent on it. init has always spawned through
+        // the shell-and-quoting rules `probeCli` carries; this used to be a second copy without them.
+        // A refusal is still not fatal — the other clients register, and calling one refusal a failed
+        // run would hide the ones that worked.
+        runCli: (command, args) => probeCli(command, args),
+    };
+    const result = setupMcp(io);
+    if (0 === result.detected.length) {
+        // Even with no file-backed client, the broader set may still have somewhere to write.
+        registerOtherAgents((line) => {
+            io.print(line);
+        });
+        // Named rather than a bare "none found". A person whose agent IS installed needs to know
+        // whether we looked for it at all, and the list is the difference between "we did not find
+        // yours" and "we do not support yours".
+        io.print(`No coding agent config found. Looked for: ${knownClientLabels().join(', ')}.`);
+        io.print('Install one, then run `reticle setup mcp` again.');
+        return;
+    }
+    for (const id of result.registered)
+        io.print(`  registered  ${id}`);
+    for (const id of result.alreadyThere)
+        io.print(`  already     ${id}`);
+    // Said, not skipped. These are the clients whose format we will not rewrite, and they used to be
+    // counted as registered: the line below is the difference between a user who adds four lines to
+    // one file and a user who believes they are set up and has no tools.
+    for (const client of result.manual) {
+        io.print(`  BY HAND     ${client.id}: add the reticle entry to ${client.configPath}`);
+        if (client.docs !== undefined)
+            io.print(`              see ${client.docs}`);
+    }
+    /*
+     * The OTHER agents, which `init` already reaches and this did not.
+     *
+     * There are two registration paths and I shipped one: `MCP_CLIENTS` covers eight file-backed
+     * clients, and `registerOtherAgents` covers the rest — VS Code's USER scope, Zed, Copilot CLI,
+     * Warp, Kiro, Amazon Q, Cline, Amp, Continue, Factory Droid. Found by running the installer and
+     * `init` back to back in one sandbox: the installer said "registered cursor" and init then said
+     * "registered the MCP server with 10 more agent(s)".
+     *
+     * "Set up the MCP everywhere" has to mean everywhere, and an installer that reaches fewer agents
+     * than `init` sends somebody to a project directory to finish a job that had no reason to be
+     * half-done.
+     */
+    registerOtherAgents((line) => {
+        io.print(line);
+    });
+    // Said on every run, attended or not: a registration only takes effect when the agent re-reads
+    // its config, and an agent that was already open is the commonest reason "it did not work".
+    io.print('');
+    io.print('Restart your agent for it to pick up the new server.');
+    // Only when this IS the whole command. Inside the installer the tour follows, and its own closing
+    // already names `reticle init` — printing it here too put the same instruction twice, ten lines
+    // apart, with the tour sandwiched between them.
+    if (standalone)
+        io.print('Then: cd <your project> && reticle init');
+}
+/**
+ * `reticle setup install` — the Node half of the one-line installer.
+ *
+ * Reports what the shell measured, then does the thing the shell deliberately does not: register
+ * with the coding agents on this machine. One implementation, so the Windows launcher is a handful
+ * of lines that cannot meaningfully drift from this one.
+ */
+export function handleSetupInstall(opts, reportStep) {
+    reportInstallSteps({ runtimeSecs: opts.runtimeSecs, installSecs: opts.installSecs }, reportStep);
+    if (opts.mcp) {
+        handleSetupMcp(reportStep, false);
+    }
+    else {
+        process.stdout.write('Skipping MCP registration (--no-mcp).\n');
+    }
+    // Installation and onboarding are one script, so the tour prints here and is not gated on
+    // anything — see installClosing for the heuristic this replaced and why it reached nobody.
+    process.stdout.write(`${installClosing()}\n`);
+    // Shown, so the ONBOARD steps are a fact rather than a guess.
+    for (const step of tutorialShownSteps())
+        reportStep(step);
+}