@reticlehq/server 2.4.0 → 2.6.0

package/dist/cli.js

@@ -2,30 +2,35 @@
 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 { stateDirProblem } from './daemon/state-dir.js';
+import { reticleStateHome } from './daemon/daemon.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, removePid, spawnDaemon, discoverDaemonPort, writeDaemonRegistry, logPath, } from './daemon/daemon.js';
+import { PortPresence, probePresence, presenceIsUsable, describePresence, } from './daemon/port-presence.js';
+import { waitForDaemon, startMcpProxy, probeDaemon, proxyLog, setProxyLogPort, } from './mcp/mcp-proxy.js';
+import { installDaemonResilience, installProxyResilience, recordExitReason, DaemonExitReason, } from './daemon/daemon-resilience.js';
+import { IdleShutdown, resolveIdleShutdownMs, resolveIdleCheckMs } from './daemon/idle-shutdown.js';
+import { DaemonHeartbeat, resolveHeartbeatMs } from './daemon/heartbeat.js';
+import { everServedToolCall } from './daemon/daemon-usefulness.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,15 +38,50 @@ 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);
 }
 function handleServe(parsed) {
-    if (isRunning(parsed.port)) {
+    void serveWithHonestExit(parsed);
+}
+/**
+ * Report the BIND, not the spawn.
+ *
+ * `serve` used to log `reticle_daemon_spawned` and exit 0 unconditionally, while the child died at
+ * `reticle_daemon_start_failed` with an EADDRINUSE nothing joined back to the parent. Three surfaces
+ * then disagreed about what was true and none of them named the port.
+ *
+ * Two changes, both about saying what is actually the case: refuse up front when the port is held by
+ * something that is not a Reticle daemon (a spawn there cannot succeed), and after spawning, wait
+ * for the daemon to actually answer before claiming it started.
+ */
+async function serveWithHonestExit(parsed) {
+    const presence = await probePresence(parsed.port, {
+        tcpOpen: probeDaemon,
+        status: fetchStatus,
+    });
+    if (presence === PortPresence.DAEMON) {
         log('reticle_daemon_already_running', { port: parsed.port });
         return;
     }
+    if (presence === PortPresence.FOREIGN) {
+        log('reticle_daemon_start_refused', {
+            port: parsed.port,
+            presence,
+            reason: describePresence(presence, parsed.port),
+        });
+        process.stderr.write(`${describePresence(presence, parsed.port)}\n`);
+        process.exit(1);
+        return;
+    }
     const scriptPath = process.argv[1];
     if (scriptPath === undefined) {
         log('reticle_serve_no_script', {});
@@ -62,11 +102,50 @@ function handleServe(parsed) {
             daemonArgs.push(HTTP_TOKEN_FLAG, parsed.httpToken);
     }
     spawnDaemon(process.execPath, scriptPath, daemonArgs, parsed.port);
+    // The child binds asynchronously and, when it cannot, exits 1 long after this process would have
+    // reported success. Wait for it to ANSWER — `/status` responding is the only evidence a daemon
+    // exists that does not come from the pid file the child may never have earned.
+    const bound = await waitForPresence(parsed.port, PortPresence.DAEMON, SERVE_BIND_TIMEOUT_MS);
+    if (!bound) {
+        const settled = await probePresence(parsed.port, { tcpOpen: probeDaemon, status: fetchStatus });
+        log('reticle_daemon_start_failed_parent', {
+            port: parsed.port,
+            presence: settled,
+            reason: describePresence(settled, parsed.port),
+            log: logPath(parsed.port),
+            stateDir: stateDirProblem(reticleStateHome()) === undefined ? 'writable' : 'unwritable',
+        });
+        // Name the CAUSE when we can see it. An unwritable state directory is a first-run failure mode
+        // (locked-down home, read-only container mount, managed profile) that produced only "nothing is
+        // listening" — the symptom restated — and then pointed at a log INSIDE that directory, which
+        // cannot exist. Found by stress-testing 2.6.0 with `chmod 555 ~/.reticle`.
+        const dirProblem = stateDirProblem(reticleStateHome());
+        process.stderr.write(dirProblem === undefined
+            ? `the daemon did not come up on :${String(parsed.port)} — ${describePresence(settled, parsed.port)}\n` +
+                `see ${logPath(parsed.port)}\n`
+            : `the daemon did not come up on :${String(parsed.port)}.\n${dirProblem}\n`);
+        process.exit(1);
+        return;
+    }
     log('reticle_daemon_spawned', { port: parsed.port, ...(parsed.http ? { http: true } : {}) });
 }
+/** How long `serve` waits for the child to bind. Generous: a cold daemon start is seconds. */
+const SERVE_BIND_TIMEOUT_MS = 15_000;
+const PRESENCE_POLL_MS = 150;
+async function waitForPresence(port, want, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const presence = await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus });
+        if (presence === want)
+            return true;
+        if (Date.now() >= deadline)
+            return false;
+        await new Promise((resolve) => setTimeout(resolve, PRESENCE_POLL_MS));
+    }
+}
 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 +171,31 @@ function handleStop(port, quiet) {
 }
 function handleStatus(port) {
     const pid = readPid(port);
-    if (pid === null || !isAlive(pid)) {
-        log('reticle_status', { port, running: false });
+    if (null === pid || !isAlive(pid)) {
+        // `running: false` on its own has been reported about a port that was demonstrably occupied,
+        // because the pid file is not the port. Ask the port before answering.
+        void probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus }).then((presence) => {
+            log('reticle_status', {
+                port,
+                running: presenceIsUsable(presence),
+                presence,
+                ...(presence === PortPresence.FOREIGN ? { reason: describePresence(presence, port) } : {}),
+            });
+        });
         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 +265,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 +287,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 +312,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 +320,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) });
@@ -284,12 +408,20 @@ function handleDaemonInner(parsed) {
             removePid(parsed.port);
             process.exit(1);
         });
-        const shutdown = () => {
+        const shutdown = (reason) => {
+            // Recorded BEFORE the async chain: `installExitTrace` reads it when Node is on its way out,
+            // which is after everything below has run. Without it the exit line says `code: 0` and a
+            // reader cannot tell a tidy stop from the bridge disappearing — see #123.
+            recordExitReason(reason);
             // Awaited before the close/exit chain: `process.exit(0)` kills an in-flight POST, and this is
             // the one event carrying the whole session. A failed send resolves anyway (emit swallows its
             // own errors), so this can delay the exit by at most the send timeout, never prevent it.
             void daemonTelemetry
-                .shutdown()
+                // The reason rides out on the session summary, which is the only event that fires at this
+                // exact moment. The proxy emits the matching `mcp_connection_lost` and cannot know it —
+                // it sees a socket end and nothing more, which is how a scheduled idle exit came to make up
+                // 299 of 321 "outages". See SessionSummary.exit.
+                .shutdown(reason)
                 .then(() => server.close())
                 .then(() => {
                 removePid(parsed.port);
@@ -302,19 +434,43 @@ function handleDaemonInner(parsed) {
                 process.exit(1);
             });
         };
-        process.on('SIGTERM', shutdown);
-        process.on('SIGINT', shutdown);
+        // Wrapped rather than passed directly: a signal handler receives the signal name as its first
+        // argument, which would otherwise arrive as the reason.
+        process.on('SIGTERM', () => shutdown(DaemonExitReason.SIGNAL));
+        process.on('SIGINT', () => shutdown(DaemonExitReason.SIGNAL));
         // 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();
+                shutdown(DaemonExitReason.IDLE);
             },
         });
         idleShutdown.start();
+        // Say so, regularly, so a GAP in this log is itself evidence. `installExitTrace` hooks
+        // `'exit'`, which a SIGKILL never fires — so a killed daemon left nothing behind, and the one
+        // that exited tidily logged `code: 0`. A reader could not tell "shut down cleanly" from "the
+        // bridge every app on this machine needs is gone", and a correct SvelteKit install was written
+        // up as an install failure on exactly that ambiguity. See daemon/heartbeat.ts.
+        new DaemonHeartbeat({
+            log,
+            intervalMs: resolveHeartbeatMs(process.env[ReticleEnv.HEARTBEAT]),
+            facts: () => ({
+                sessions: server.bridge.sessions.count(),
+                served: everServedToolCall(),
+            }),
+        }).start();
     })
         .catch((error) => {
         const message = error instanceof Error ? error.message : String(error);
@@ -333,43 +489,85 @@ 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.
+        //
+        // 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).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',
+            });
+        });
     });
 }
 function handleLegacyDrive(parsed) {
@@ -424,7 +622,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':
@@ -446,7 +648,7 @@ function main() {
             handleTelemetry(parsed.action);
             break;
         case 'feedback':
-            void handleFeedback(parsed.text, parsed.rating, parsed.bug);
+            void handleFeedback(parsed.text, parsed.rating, parsed.bug, parsed.feedbackKind, parsed.agent);
             break;
         case 'identify':
             void handleIdentify(parsed);

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;