@reticlehq/server 2.4.0 → 2.5.0

package/dist/{cloud-cli.js → cli/cloud-cli.js}

@@ -7,15 +7,16 @@
  * is `<repo>/.reticle/cloud.json`. Auth for a command = `RETICLE_CLOUD_KEY` env (agent) OR the login token.
  */
 import { mkdir, writeFile, readFile } from 'node:fs/promises';
+import { NodePlatform } from '../platform.js';
 import { spawn } from 'node:child_process';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { z } from 'zod';
-import { createNodeFileSystem } from './project/fs-port.js';
-import { RunStore } from './runs/run-store.js';
-import { resolveProjectCloud } from './cloud/cloud-config.js';
-import { syncRunToCloud, SyncOutcome } from './cloud/cloud-sync.js';
+import { createNodeFileSystem } from '../project/fs-port.js';
+import { RunStore } from '../runs/run-store.js';
+import { resolveProjectCloud } from '../cloud/cloud-config.js';
+import { syncRunToCloud, SyncOutcome } from '../cloud/cloud-sync.js';
 const DEFAULT_URL = 'http://localhost:8890';
 const RETICLE_DIR = '.reticle';
 const SESSION_FILE = 'session.json';
@@ -162,8 +163,12 @@ const DevicePollSchema = z.object({
 });
 /** Best-effort open the approval page in the default browser; the printed URL is the headless fallback. */
 const openBrowser = (target) => {
-    const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
-    const args = process.platform === 'win32' ? ['/c', 'start', '', target] : [target];
+    const cmd = NodePlatform.MACOS === process.platform
+        ? 'open'
+        : NodePlatform.WINDOWS === process.platform
+            ? 'cmd'
+            : 'xdg-open';
+    const args = NodePlatform.WINDOWS === process.platform ? ['/c', 'start', '', target] : [target];
     try {
         const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
         child.on('error', () => undefined);
@@ -193,18 +198,18 @@ const cmdLoginDevice = async () => {
     for (;;) {
         await sleep(intervalMs);
         const poll = DevicePollSchema.parse(await api('POST', `${url}/v1/auth/device/token`, null, { deviceCode: started.deviceCode }));
-        if (poll.status === 'approved' && poll.token !== undefined && poll.org !== undefined) {
+        if ('approved' === poll.status && poll.token !== undefined && poll.org !== undefined) {
             await writeSession(url, poll.token, poll.org.name);
             return 0;
         }
-        if (poll.status === 'pending') {
+        if ('pending' === poll.status) {
             if (Date.now() > started.expiresAt) {
                 err('device login expired — run `reticle login` again');
                 return 1;
             }
             continue;
         }
-        err(poll.status === 'denied'
+        err('denied' === poll.status
             ? 'device login was denied in the browser'
             : 'device login expired — run `reticle login` again');
         return 1;
@@ -264,7 +269,7 @@ const cmdWhoami = async () => {
             verify: cloud.verify,
         },
     });
-    if (cloud.config === null)
+    if (null === cloud.config)
         hint('this repo is not attached — run `reticle link`');
     return 0;
 };
@@ -273,18 +278,18 @@ const cmdProject = async (argv) => {
     const session = await readSession();
     const token = bearer(session);
     const url = baseUrl(session);
-    if (token === null) {
+    if (null === token) {
         err('run `reticle login` first, or set RETICLE_CLOUD_KEY');
         return 2;
     }
     const sub = argv[0];
-    if (sub === 'ls') {
+    if ('ls' === sub) {
         emit(await api('GET', `${url}/v1/projects`, token));
         return 0;
     }
-    if (sub === 'create') {
+    if ('create' === sub) {
         const name = argv.slice(1).join(' ').trim();
-        if (name.length === 0) {
+        if (0 === name.length) {
             err('usage: reticle project create <name>');
             return 2;
         }
@@ -293,17 +298,17 @@ const cmdProject = async (argv) => {
         hint(`next: \`reticle link --project ${created.projectId}\` to bind this repo`);
         return 0;
     }
-    if (sub === 'rename') {
+    if ('rename' === sub) {
         const id = argv[1];
         const name = argv.slice(2).join(' ').trim();
-        if (id === undefined || name.length === 0) {
+        if (id === undefined || 0 === name.length) {
             err('usage: reticle project rename <projectId> <new name>');
             return 2;
         }
         emit(await api('PATCH', `${url}/v1/projects/${encodeURIComponent(id)}`, token, { name }));
         return 0;
     }
-    if (sub === 'rm' || sub === 'delete') {
+    if ('rm' === sub || 'delete' === sub) {
         const id = argv[1];
         if (id === undefined) {
             err('usage: reticle project rm <projectId>');
@@ -357,7 +362,7 @@ const cmdLink = async (argv) => {
     await mkdir(reticleDir, { recursive: true });
     const linkPath = join(reticleDir, CLOUD_LINK_FILE);
     const prev = await readJson(linkPath);
-    const prevObj = typeof prev === 'object' && prev !== null ? prev : {};
+    const prevObj = 'object' === typeof prev && prev !== null ? prev : {};
     const cloudJson = {
         projectId,
         projectName,
@@ -369,7 +374,7 @@ const cmdLink = async (argv) => {
     await mkdir(home(), { recursive: true });
     const credPath = join(home(), CREDENTIALS_FILE);
     const creds = (await readJson(credPath)) ?? {};
-    const credObj = typeof creds === 'object' && creds !== null ? creds : {};
+    const credObj = 'object' === typeof creds && creds !== null ? creds : {};
     credObj[projectId] = key;
     await writeFile(credPath, `${JSON.stringify(credObj, null, 2)}\n`);
     emit({ linked: projectName, projectId, cloudJson: linkPath, credentials: credPath });
@@ -381,15 +386,15 @@ const cmdConfig = async (argv) => {
     const f = flags(argv);
     const linkPath = join(process.cwd(), RETICLE_DIR, CLOUD_LINK_FILE);
     const raw = await readJson(linkPath);
-    if (raw === null || typeof raw !== 'object') {
+    if (null === raw || typeof raw !== 'object') {
         err('no .reticle/cloud.json here — run `reticle link` first');
         return 2;
     }
     const cfg = raw;
-    const sync = typeof cfg['sync'] === 'object' && cfg['sync'] !== null
+    const sync = 'object' === typeof cfg['sync'] && cfg['sync'] !== null
         ? cfg['sync']
         : { runs: true, memory: true, flows: true };
-    const onoff = (v) => v === 'on' ? true : v === 'off' ? false : undefined;
+    const onoff = (v) => 'on' === v ? true : 'off' === v ? false : undefined;
     for (const k of ['runs', 'memory', 'flows']) {
         if (f[k] === undefined)
             continue;
@@ -417,7 +422,7 @@ const cmdPush = async () => {
     const fs = createNodeFileSystem();
     const reticleRoot = join(process.cwd(), RETICLE_DIR);
     const cloud = await resolveProjectCloud(fs, reticleRoot, homedir(), process.env);
-    if (cloud.config === null) {
+    if (null === cloud.config) {
         err('cloud not attached here — run `reticle link` (or set RETICLE_CLOUD_URL/KEY)');
         return 1;
     }
@@ -448,7 +453,7 @@ const cmdPush = async () => {
 const repoCloud = async () => {
     const fs = createNodeFileSystem();
     const cloud = await resolveProjectCloud(fs, join(process.cwd(), RETICLE_DIR), homedir(), process.env);
-    if (cloud.config === null)
+    if (null === cloud.config)
         throw new Error('cloud not attached here — run `reticle link` (or set RETICLE_CLOUD_URL/KEY)');
     return cloud.config;
 };

package/dist/cli.d.ts

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
-import { parseCliArgs, CLI_USAGE } from './cli-parse.js';
+import { parseCliArgs, CLI_USAGE } from './cli/cli-parse.js';
 export { parseCliArgs, CLI_USAGE };
-export type { CliResult } from './cli-parse.js';
+export type { CliResult } from './cli/cli-parse.js';

package/dist/cli.js

@@ -2,30 +2,30 @@
 import { pathToFileURL } from 'node:url';
 import { realpathSync } from 'node:fs';
 import { join } from 'node:path';
-import { handleWatch, handleCapsules, handleGate, loadNamedFlows, resolveChangedFiles, } from './cli-flow-commands.js';
+import { handleWatch, handleCapsules, handleGate, loadNamedFlows, resolveChangedFiles, } from './cli/cli-flow-commands.js';
 import { RETICLE_DEFAULT_PORT, ReticleDir, ReticleEnv } from '@reticlehq/core';
 import { loadDotEnv } from './telemetry/dev-repo.js';
 import { createNodeFileSystem } from './project/fs-port.js';
 import { affectedSavedFlows } from './flows/flow-sources.js';
-import { checkForUpdate } from './update/update-checker.js';
-import { applyUpdate, rollback } from './update/updater.js';
+import { availableUpdate } from './update/update-nudge.js';
+import { handleUpdate, handleRollback } from './cli/cli-update-commands.js';
 import { start, startDaemon } from './index.js';
-import { isCloudCommand, runCloudCommand } from './cloud-cli.js';
-import { SERVER_VERSION } from './server-version.js';
+import { isCloudCommand, runCloudCommand } from './cli/cloud-cli.js';
+import { SERVER_VERSION } from './version/server-version.js';
 import { log } from './log.js';
-import { readPid, isAlive, isRunning, removePid, spawnDaemon, discoverDaemonPort, writeDaemonRegistry, } from './daemon.js';
-import { waitForDaemon, startMcpProxy, probeDaemon } from './mcp-proxy.js';
-import { installDaemonResilience } from './daemon-resilience.js';
-import { IdleShutdown, resolveIdleShutdownMs } from './idle-shutdown.js';
-import { fetchStatus, summarizeStatus, decideOpen, openInBrowser } from './cli-launch.js';
-import { handleVerify } from './cli-verify.js';
+import { readPid, isAlive, isRunning, removePid, spawnDaemon, discoverDaemonPort, writeDaemonRegistry, } from './daemon/daemon.js';
+import { waitForDaemon, startMcpProxy, probeDaemon, proxyLog, setProxyLogPort, } from './mcp/mcp-proxy.js';
+import { installDaemonResilience, installProxyResilience } from './daemon/daemon-resilience.js';
+import { IdleShutdown, resolveIdleShutdownMs, resolveIdleCheckMs } from './daemon/idle-shutdown.js';
+import { fetchStatus, summarizeStatus, warnOnDaemonSkew, decideOpen, openInBrowser, } from './cli/cli-launch.js';
+import { handleVerify } from './cli/cli-verify.js';
 import { summarizeHunt } from './hunt/hunt-report.js';
 import { runInit } from './init/run.js';
-import { handleDoctor } from './cli-doctor.js';
+import { handleDoctor } from './cli/cli-doctor.js';
 import { buildNodeIo } from './init/node-io.js';
 import { describeLicense } from './license/license.js';
-import { isLikelyDevServerPort, devServerPortWarning, readProjectPort, readProjectId } from './cli-port.js';
-import { DAEMON_INNER_COMMAND, PORT_FLAG, DRIVE_FLAG, HEADED_FLAG, HTTP_FLAG, HTTP_PORT_FLAG, HTTP_TOKEN_FLAG, parseCliArgs, CLI_USAGE, } from './cli-parse.js';
+import { isLikelyDevServerPort, devServerPortWarning, readProjectPort, readProjectId, } from './cli/cli-port.js';
+import { DAEMON_INNER_COMMAND, PORT_FLAG, DRIVE_FLAG, HEADED_FLAG, HTTP_FLAG, HTTP_PORT_FLAG, HTTP_TOKEN_FLAG, parseCliArgs, CLI_USAGE, } from './cli/cli-parse.js';
 import { handleFeedback, handleIdentify, handleTelemetry } from './telemetry/feedback-cli.js';
 import { installDaemonTelemetry } from './telemetry/daemon-telemetry.js';
 import { reportCliRun } from './telemetry/cli-telemetry.js';
@@ -33,7 +33,14 @@ import { reportCliRun } from './telemetry/cli-telemetry.js';
 export { parseCliArgs, CLI_USAGE };
 function handleInit(parsed) {
     const cwd = process.cwd();
-    const result = runInit({ cwd, port: parsed.port, mcp: parsed.mcp, dryRun: parsed.dryRun, install: parsed.install }, buildNodeIo(cwd));
+    const result = runInit({
+        cwd,
+        port: parsed.port,
+        mcp: parsed.mcp,
+        dryRun: parsed.dryRun,
+        install: parsed.install,
+        ...(parsed.app === undefined ? {} : { app: parsed.app }),
+    }, buildNodeIo(cwd));
     if (!result.ok)
         process.exit(1);
 }
@@ -66,7 +73,7 @@ function handleServe(parsed) {
 }
 function handleStop(port, quiet) {
     const pid = readPid(port);
-    if (pid === null || !isAlive(pid)) {
+    if (null === pid || !isAlive(pid)) {
         removePid(port);
         if (!quiet)
             log('reticle_daemon_not_running', { port });
@@ -92,17 +99,22 @@ function handleStop(port, quiet) {
 }
 function handleStatus(port) {
     const pid = readPid(port);
-    if (pid === null || !isAlive(pid)) {
+    if (null === pid || !isAlive(pid)) {
         log('reticle_status', { port, running: false });
         return;
     }
     // The daemon is up — ask it for live sessions + health so status is at-a-glance, not just a pid.
     void fetchStatus(port).then((payload) => {
+        // `status` is the second-most-run command and the one a HUMAN types. The update nudge otherwise
+        // only rides a tool result, which the majority of daemons never produce — so the people most in
+        // need of an upgrade were the ones with no path to hearing about it.
+        const update = availableUpdate();
+        const nudge = update === undefined ? {} : { updateAvailable: update };
         if (payload === undefined) {
-            log('reticle_status', { port, running: true, pid });
+            log('reticle_status', { port, running: true, pid, ...nudge });
             return;
         }
-        log('reticle_status', { port, running: true, pid, ...summarizeStatus(payload) });
+        log('reticle_status', { port, running: true, pid, ...summarizeStatus(payload), ...nudge });
     });
 }
 /** Print the running package version (resolved once in server-version.ts). */
@@ -172,43 +184,15 @@ async function handleHunt(dir) {
         });
     }
 }
-/** `reticle update` — install the latest server version and restart (moved off the MCP surface). */
-async function handleUpdate() {
-    try {
-        const manifest = await checkForUpdate(SERVER_VERSION, () => Date.now());
-        if (!manifest.updateAvailable || manifest.latestVersion === undefined) {
-            log('reticle_update', {
-                ok: false,
-                message: 'already on the latest version',
-                version: SERVER_VERSION,
-            });
-            return;
-        }
-        log('reticle_update', { ok: true, from: SERVER_VERSION, to: manifest.latestVersion });
-        await applyUpdate(manifest.latestVersion); // calls process.exit; Claude Code restarts
-    }
-    catch (error) {
-        log('reticle_update_failed', { error: error instanceof Error ? error.message : String(error) });
-        process.exitCode = 1;
-    }
-}
-/** `reticle rollback` — restore the previous server version and restart. */
-async function handleRollback() {
-    try {
-        await rollback(); // calls process.exit
-    }
-    catch (error) {
-        log('reticle_rollback_failed', {
-            error: error instanceof Error ? error.message : String(error),
-        });
-        process.exitCode = 1;
-    }
-}
 /** Ensure a daemon is reachable on `port` (probe the real port; spawn + wait only if nothing's there). */
 function ensureDaemon(port) {
-    return probeDaemon(port).then((listening) => {
+    return probeDaemon(port).then(async (listening) => {
+        // Attaching to whatever already owns the port is the whole point of a daemon — but it means an
+        // upgrade does NOT take effect until that daemon dies, and nothing used to say so. Say it here,
+        // where both versions are in hand, and keep attaching: killing another agent's daemon on a
+        // version bump is worse than a loud warning.
         if (listening)
-            return undefined;
+            return warnOnDaemonSkew(port);
         const scriptPath = process.argv[1];
         if (scriptPath === undefined)
             throw new Error('cannot locate the reticle daemon script');
@@ -222,6 +206,24 @@ function ensureDaemon(port) {
  * the daemon, then reuses the already-connected tab or opens a new browser at the url. Idempotent:
  * re-running never piles up duplicate tabs.
  */
+/** How long `reticle open` waits for the launched page to register before reporting on it. */
+const OPEN_SESSION_WAIT_MS = 8000;
+/**
+ * Poll until a NEW session shows up, or the wait runs out. Returns whether one did.
+ *
+ * Compares against the count taken before launching rather than against zero, so opening a second
+ * app while one is already connected is not reported as an instant success.
+ */
+async function waitForNewSession(port, before) {
+    const deadline = Date.now() + OPEN_SESSION_WAIT_MS;
+    while (Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, 400));
+        const { sessions } = summarizeStatus(await fetchStatus(port));
+        if (sessions.length > before)
+            return true;
+    }
+    return false;
+}
 function handleOpen(requestedPort, url) {
     probeDaemon(requestedPort)
         .then((here) => (here ? requestedPort : (discoverDaemonPort() ?? requestedPort)))
@@ -229,7 +231,7 @@ function handleOpen(requestedPort, url) {
         await ensureDaemon(port);
         const { sessions } = summarizeStatus(await fetchStatus(port));
         const decision = decideOpen(sessions, url);
-        if (decision.action === 'need-url') {
+        if ('need-url' === decision.action) {
             log('reticle_open', {
                 port,
                 error: 'no app connected — pass a url: reticle open <url>. Desktop app (Electron/Tauri)? ' +
@@ -237,12 +239,53 @@ function handleOpen(requestedPort, url) {
             });
             return;
         }
-        if (decision.action === 'reuse') {
+        if ('reuse' === decision.action) {
             log('reticle_open', { port, reusing: decision.url });
             return;
         }
-        openInBrowser(decision.url);
-        log('reticle_open', { port, opened: decision.url });
+        // A tab on the right origin, on the WRONG page. Kept (that is what stops a tab piling up per
+        // run) but never reported as done: `reusing` here read as "your url is open" for a page nobody
+        // had opened.
+        if ('left-as-is' === decision.action) {
+            log('reticle_open', {
+                port,
+                reusing: decision.url,
+                requested: decision.requested,
+                note: `a tab is connected on this origin but sitting on ${decision.url} — it was LEFT THERE, ` +
+                    `not navigated to ${decision.requested}. Drive it with reticle_navigate, or open the url ` +
+                    'in the browser yourself.',
+            });
+            return;
+        }
+        const launchError = await openInBrowser(decision.url);
+        if (launchError !== null) {
+            log('reticle_open', {
+                port,
+                error: `could not launch a browser: ${launchError}`,
+                recovery: 'Open the url yourself, or run `reticle doctor` — it checks the pieces this command ' +
+                    'depends on.',
+            });
+            process.exit(1);
+            return;
+        }
+        // Say whether a SESSION appeared, not merely that a launcher was invoked. `{"opened": url}`
+        // was printed unconditionally, so a run where nothing ever opened looked identical to a run
+        // where it did — reported from the field as twenty minutes lost to a phantom port problem.
+        const connected = await waitForNewSession(port, sessions.length);
+        log('reticle_open', {
+            port,
+            opened: decision.url,
+            connected,
+            ...(connected
+                ? {}
+                : {
+                    note: 'the browser was launched but no Reticle session appeared. The app may still be ' +
+                        'loading, or it is not wired to this bridge — run `reticle doctor`, and check the ' +
+                        'app connects on port ' +
+                        String(port) +
+                        '.',
+                }),
+        });
     })
         .catch((err) => {
         log('reticle_open', { error: err instanceof Error ? err.message : String(err) });
@@ -306,9 +349,18 @@ function handleDaemonInner(parsed) {
         process.on('SIGINT', shutdown);
         // Self-shut-down when idle so a detached daemon (and any headless Chromium it launched) never
         // lingers on the user's machine after the editor closes. Reuses the same clean shutdown path.
+        const attachedGraceEnv = process.env[ReticleEnv.IDLE_ATTACHED];
         const idleShutdown = new IdleShutdown({
             graceMs: resolveIdleShutdownMs(process.env[ReticleEnv.IDLE_SHUTDOWN]),
+            checkIntervalMs: resolveIdleCheckMs(process.env[ReticleEnv.IDLE_CHECK]),
             isIdle: server.isIdle ?? (() => false),
+            ...(server.agentAttached === undefined ? {} : { agentAttached: server.agentAttached }),
+            // Only when the var is actually SET. `resolveIdleShutdownMs(undefined)` returns the 5-minute
+            // DEFAULT, so passing it unconditionally would override the derived attached grace with the
+            // very number this change exists to stop using — shipping the bug while looking fixed.
+            ...(attachedGraceEnv === undefined || '' === attachedGraceEnv.trim()
+                ? {}
+                : { attachedGraceMs: resolveIdleShutdownMs(attachedGraceEnv) }),
             onShutdown: () => {
                 log('reticle_daemon_idle_exit', { port: parsed.port });
                 shutdown();
@@ -333,43 +385,69 @@ function handleDaemonInner(parsed) {
  */
 function handleMcp(opts) {
     const { port, driveUrl, headless, http, httpPort, httpToken } = opts;
-    // Probe the port first — a daemon with a stale PID file is still usable.
-    // Only spawn when nothing is actually listening on the port.
-    probeDaemon(port)
-        .then((listening) => {
-        if (!listening) {
-            const scriptPath = process.argv[1];
-            if (scriptPath === undefined) {
-                log('reticle_mcp_no_script', {});
-                process.exit(1);
-                return;
-            }
-            const daemonArgs = [DAEMON_INNER_COMMAND, PORT_FLAG, String(port)];
-            if (driveUrl !== undefined) {
-                daemonArgs.push(DRIVE_FLAG, driveUrl);
-                if (!headless)
-                    daemonArgs.push(HEADED_FLAG);
-            }
-            // Forward the HTTP-verify flags too (previously silently dropped for `reticle mcp`).
-            if (http) {
-                daemonArgs.push(HTTP_FLAG);
-                if (httpPort !== undefined)
-                    daemonArgs.push(HTTP_PORT_FLAG, String(httpPort));
-                if (httpToken !== undefined)
-                    daemonArgs.push(HTTP_TOKEN_FLAG, httpToken);
-            }
-            spawnDaemon(process.execPath, scriptPath, daemonArgs, port);
-            log('reticle_mcp_daemon_started', {
-                port,
-                ...(driveUrl !== undefined ? { driveUrl } : {}),
-            });
+    // 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);
+    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 () => {
+        if (await probeDaemon(port))
+            return;
+        const scriptPath = process.argv[1];
+        if (scriptPath === undefined) {
+            log('reticle_mcp_no_script', {});
+            process.exit(1);
         }
-        return waitForDaemon(port).then(() => startMcpProxy(port));
-    })
+        const daemonArgs = [DAEMON_INNER_COMMAND, PORT_FLAG, String(port)];
+        if (driveUrl !== undefined) {
+            daemonArgs.push(DRIVE_FLAG, driveUrl);
+            if (!headless)
+                daemonArgs.push(HEADED_FLAG);
+        }
+        // Forward the HTTP-verify flags too (previously silently dropped for `reticle mcp`).
+        if (http) {
+            daemonArgs.push(HTTP_FLAG);
+            if (httpPort !== undefined)
+                daemonArgs.push(HTTP_PORT_FLAG, String(httpPort));
+            if (httpToken !== undefined)
+                daemonArgs.push(HTTP_TOKEN_FLAG, httpToken);
+        }
+        spawnDaemon(process.execPath, scriptPath, daemonArgs, port);
+        log('reticle_mcp_daemon_started', { port, ...(driveUrl !== undefined ? { driveUrl } : {}) });
+        await waitForDaemon(port);
+    };
+    // 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) => {
-        const message = err instanceof Error ? err.message : String(err);
-        log('reticle_mcp_proxy_error', { error: message });
-        process.exit(1);
+        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.
+        void startMcpProxy(port, ensure);
     });
 }
 function handleLegacyDrive(parsed) {
@@ -424,7 +502,11 @@ function main() {
     const parsed = parseCliArgs(argv, defaultPort, process.env['CI'] !== undefined);
     switch (parsed.kind) {
         case 'error':
+            // Two audiences, two channels. The structured line is for logs and scripts; the plain text is
+            // for the person who just typed the command. Emitting only the JSON meant a single typo came
+            // back as an escaped one-line wall of the entire help text — see the ParseError builders.
             log('reticle_usage_error', { message: parsed.message });
+            process.stderr.write(parsed.message === CLI_USAGE ? `${CLI_USAGE}\n` : `${parsed.message}\n\n${CLI_USAGE}\n`);
             process.exit(1);
             break;
         case 'init':

package/dist/cloud/cloud-config.d.ts

@@ -13,7 +13,6 @@ export interface SyncPolicy {
     /** Sync saved flow files (the shared regression suite). */
     flows: boolean;
 }
-export declare const DEFAULT_SYNC_POLICY: SyncPolicy;
 /** Where a verification actually executes. Reserved for the hosted-runner path; default local. */
 export declare const VerifyMode: {
     readonly LOCAL: "local";

package/dist/cloud/cloud-config.js

@@ -16,10 +16,10 @@ import { resolveCloudConfig } from './cloud-sync.js';
 export const CLOUD_LINK_FILE = 'cloud.json';
 /** `~/.reticle/credentials.json` — the user's per-cloud-project API keys (the only secret). */
 export const CREDENTIALS_FILE = 'credentials.json';
-export const DEFAULT_SYNC_POLICY = { runs: true, memory: true, flows: true };
+const DEFAULT_SYNC_POLICY = { runs: true, memory: true, flows: true };
 /** Where a verification actually executes. Reserved for the hosted-runner path; default local. */
 export const VerifyMode = { LOCAL: 'local', SERVER: 'server' };
-const asBool = (v, fallback) => (typeof v === 'boolean' ? v : fallback);
+const asBool = (v, fallback) => ('boolean' === typeof v ? v : fallback);
 /** Read + JSON-parse a file, or null on any problem (missing/malformed) — never throws. */
 async function readJson(fs, path) {
     try {
@@ -33,14 +33,14 @@ async function readJson(fs, path) {
 }
 /** Validate the shape of `.reticle/cloud.json`. Requires projectId + url; policy/verify default in. */
 function parseLink(raw) {
-    if (typeof raw !== 'object' || raw === null)
+    if (typeof raw !== 'object' || null === raw)
         return null;
     const o = raw;
-    if (typeof o.projectId !== 'string' || o.projectId.length === 0)
+    if (typeof o.projectId !== 'string' || 0 === o.projectId.length)
         return null;
-    if (typeof o.url !== 'string' || o.url.length === 0)
+    if (typeof o.url !== 'string' || 0 === o.url.length)
         return null;
-    const sync = typeof o.sync === 'object' && o.sync !== null ? o.sync : {};
+    const sync = 'object' === typeof o.sync && o.sync !== null ? o.sync : {};
     return {
         projectId: o.projectId,
         url: o.url,
@@ -54,10 +54,10 @@ function parseLink(raw) {
 }
 /** Look up the API key for a cloud project id in the user credentials map. */
 function credentialFor(raw, projectId) {
-    if (typeof raw !== 'object' || raw === null)
+    if (typeof raw !== 'object' || null === raw)
         return null;
     const key = raw[projectId];
-    return typeof key === 'string' && key.length > 0 ? key : null;
+    return 'string' === typeof key && key.length > 0 ? key : null;
 }
 /**
  * Resolve the cloud picture for a project rooted at `reticleRoot`. Reads the project's link file + the
@@ -66,7 +66,7 @@ function credentialFor(raw, projectId) {
  */
 export async function resolveProjectCloud(fs, reticleRoot, homeDir, env) {
     const link = parseLink(await readJson(fs, join(reticleRoot, CLOUD_LINK_FILE)));
-    if (link === null) {
+    if (null === link) {
         // No per-project link → the env vars are the whole story (legacy single-project / CI behaviour).
         return {
             config: resolveCloudConfig(env),

package/dist/cloud/cloud-sync.d.ts

@@ -15,12 +15,6 @@ export declare const CloudEnv: {
     readonly URL: "RETICLE_CLOUD_URL";
     readonly KEY: "RETICLE_CLOUD_KEY";
 };
-/** Paths the OSS server pushes to (match the cloud app's contract). */
-export declare const CLOUD_FLOWS_PATH = "/v1/flows";
-export declare const CLOUD_RUNS_PATH = "/v1/runs";
-export declare const CLOUD_PROJECT_RUNS_PATH = "/v1/project/runs";
-export declare const CLOUD_PROJECT_REGRESSION_PATH = "/v1/project/regression";
-export declare const CLOUD_VERIFICATIONS_PATH = "/v1/verifications";
 export interface CloudConfig {
     url: string;
     apiKey: string;
@@ -33,7 +27,7 @@ export declare const SyncOutcome: {
     readonly FAILED: "failed";
 };
 export type SyncOutcome = (typeof SyncOutcome)[keyof typeof SyncOutcome];
-export interface SyncResult {
+interface SyncResult {
     outcome: SyncOutcome;
     status?: number;
     error?: string;