@reticlehq/server 3.1.0 → 3.2.0

package/dist/command/cli/lifecycle/daemon-lifecycle.js

@@ -0,0 +1,198 @@
+/**
+ * Starting, stopping and restarting the daemon — the three commands that decide whether a `reticle`
+ * process exists, and the waiting each of them has to do to answer honestly.
+ *
+ * Lifted out of `cli.ts` for the reason `cli-launch.ts` was before it: that file sat at exactly the
+ * thousand-line cap, so the next line added to it — to any command, related or not — failed the
+ * build. This is the largest group in it that is one idea rather than several.
+ *
+ * The idea is: a lifecycle command must report what is actually the case, and the only way to know
+ * that is to wait and look. `serve` waits for the daemon to ANSWER before claiming it started,
+ * because the child binds asynchronously and a parent that reports the spawn reports a guess.
+ * `stop` waits for the process to be gone and escalates when it is not, because a daemon that
+ * ignores SIGTERM is the one situation `stop` exists for. `restart` reports its two halves
+ * separately, because "killed nothing" and "killed it but could not start a new one" leave the user
+ * in different places and one exit code cannot say which.
+ */
+import { log } from '../../../log.js';
+import { RETICLE_VERIFY_DEFAULT_PORT } from '../../../index.js';
+import { verifyEndpointMismatch } from '../../../status-payload.js';
+import { probeDaemon } from '../../../surface/mcp/mcp-proxy.js';
+import { stateDirProblem } from '../../daemon/state-dir.js';
+import { readPid, isAlive, removePid, spawnDaemon, logPath, reticleStateHome, } from '../../daemon/daemon.js';
+import { readDaemonStartupCause } from '../../daemon/lifetime/startup-failure.js';
+import { PortPresence, probePresence, describePresence, } from '../../daemon/binding/port-presence.js';
+import { daemonSpawnArgs } from '../daemon-start-options.js';
+import { fetchStatus } from '../../daemon/binding/daemon-status-probe.js';
+import { runKill } from '../cli-kill.js';
+export function handleServe(parsed) {
+    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) {
+        // A daemon that is already up was started with ITS flags, not these — `serve` only attaches.
+        // Exiting 0 here regardless is how `--http-port` came to be accepted and ignored (#687): the
+        // running daemon kept serving whatever it was started with, and the flag vanished without a
+        // word. Ask the daemon which verify port it actually serves and refuse when it is not the one
+        // requested — a flag that cannot be honoured must say so, not report success.
+        if (parsed.http) {
+            const mismatch = verifyEndpointMismatch(await fetchStatus(parsed.port), parsed.httpPort ?? RETICLE_VERIFY_DEFAULT_PORT);
+            if (mismatch !== undefined) {
+                log('reticle_daemon_start_refused', { port: parsed.port, reason: mismatch });
+                process.stderr.write(`${mismatch}\n`);
+                process.exit(1);
+                return;
+            }
+        }
+        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', {});
+        process.exit(1);
+        return;
+    }
+    const daemonArgs = daemonSpawnArgs(parsed);
+    const startupStartedAt = Date.now();
+    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 });
+        const startupCause = readDaemonStartupCause(logPath(parsed.port), startupStartedAt);
+        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',
+            ...(startupCause === undefined ? {} : { cause: startupCause }),
+        });
+        // 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. Reproduced with `chmod 555 ~/.reticle`.
+        const dirProblem = stateDirProblem(reticleStateHome());
+        process.stderr.write(dirProblem === undefined
+            ? startupCause === 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${startupCause}\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;
+/** How long a daemon gets to shut down on its own before `stop` stops asking politely. */
+const GRACEFUL_STOP_MS = 5000;
+/** How long after SIGKILL before we accept the process is not ours to kill and say so. */
+const FORCED_STOP_MS = 2000;
+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));
+    }
+}
+export function handleStop(port, quiet) {
+    const pid = readPid(port);
+    if (null === pid || !isAlive(pid)) {
+        removePid(port);
+        if (!quiet)
+            log('reticle_daemon_not_running', { port });
+        return;
+    }
+    process.kill(pid, 'SIGTERM');
+    const started = Date.now();
+    let escalated = false;
+    const poll = setInterval(() => {
+        if (!isAlive(pid)) {
+            clearInterval(poll);
+            removePid(port);
+            if (!quiet)
+                log('reticle_daemon_stopped', { port, pid, ...(escalated ? { escalated } : {}) });
+            return;
+        }
+        const waited = Date.now() - started;
+        // A daemon that ignores SIGTERM is WEDGED — which is the one situation `stop` exists for. Giving
+        // up here left the port held, the pid file stale, and a human running `kill -9` by hand at the
+        // first two minutes of setup. Escalate instead: graceful first, then unconditional.
+        if (!escalated && waited > GRACEFUL_STOP_MS) {
+            escalated = true;
+            try {
+                process.kill(pid, 'SIGKILL');
+            }
+            catch {
+                // Already gone between the liveness check and here — the next tick reports it stopped.
+            }
+            return;
+        }
+        if (waited > GRACEFUL_STOP_MS + FORCED_STOP_MS) {
+            clearInterval(poll);
+            // Surviving SIGKILL means the pid is not ours to kill (permissions) or is an unkillable
+            // zombie. Neither is retryable, and both need the pid named so a human can act on it.
+            if (!quiet)
+                log('reticle_daemon_stop_timeout', { port, pid, escalated });
+            process.exit(1);
+        }
+    }, 100);
+}
+/**
+ * `reticle restart` — free the port, then put a daemon back on it and prove it bound.
+ *
+ * The two halves are reported separately on purpose. A restart that killed the old daemon and then
+ * could not start a new one leaves the user in a different place from one that could not kill
+ * anything at all, and a single `ok: false` cannot tell them which happened.
+ */
+export async function handleRestart(port, force) {
+    const freed = await runKill(port, force);
+    if (!freed) {
+        log('reticle_restart_aborted', {
+            port,
+            reason: 'the port was not freed, so nothing was started — the old holder is still there',
+        });
+        process.exit(1);
+        return;
+    }
+    // Reuses `serve`'s path, which waits for the daemon to ANSWER before claiming it started and exits
+    // non-zero when it does not. A restart that reports success for a daemon that never bound is the
+    // same lie `serve` already stopped telling.
+    await serveWithHonestExit({ port, headless: true, http: false });
+}

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

@@ -17,7 +17,7 @@ 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 './launch/cli-launch.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';
@@ -80,7 +80,7 @@ export async function handleMcp(opts) {
     // 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);
+    const resilience = installProxyResilience(process, proxyLog);
     /**
      * Make sure a daemon is on the port, spawning one if not.
      *
@@ -163,7 +163,9 @@ export async function handleMcp(opts) {
         // 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) => {
+        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),

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

@@ -7,6 +7,7 @@
  * 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";
 /**
@@ -39,7 +40,7 @@ export declare function readProjectPort(cwd: string): number | undefined;
  * 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): string | undefined;
+export declare function readProjectId(cwd: string): ProjectId | undefined;
 /**
  * The framework `reticle init` stamped into `.reticle.json`, when there is one.
  *

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

@@ -9,6 +9,7 @@
  */
 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';
 /**
@@ -76,8 +77,11 @@ export function readProjectPort(cwd) {
  */
 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 id;
+        return asProjectId(id);
     return undefined;
 }
 /**

package/dist/command/cli/status/status-lines.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `reticle status`, rendered for a person.
+ *
+ * The command printed one line of JSON and nothing else. Its own source called it "the second-most
+ * run command and the one a HUMAN types" — and the answer to that human was
+ * `{"t":"…","event":"reticle_status","port":4400,"running":true,…}`. It is worse than that now that
+ * agents run it: an agent's terminal output is read by the person sitting behind it, so a machine
+ * line is a line two readers have to decode and only one of them can.
+ *
+ * The JSON stays, unchanged, on stderr — it is documented, and it is what a log is for. This is the
+ * same facts on stdout, in the shape `doctor` already uses, so the two commands read as one tool.
+ *
+ * Pure, and tolerant: it is handed the very object the log line is built from, narrows it without
+ * trusting it, and prints what it can recognise. A status that cannot be rendered must still be
+ * logged, so nothing here may throw.
+ */
+/** Every row label this block can print. The one spelling; nothing writes a label inline. */
+export declare const StatusLabel: {
+    readonly DAEMON: "daemon";
+    readonly SESSIONS: "sessions";
+    readonly AGENT_LINK: "agent link";
+    readonly NEXT: "next";
+    readonly SPLIT_BRAIN: "split brain";
+    readonly UPDATE: "update";
+};
+export type StatusLabel = (typeof StatusLabel)[keyof typeof StatusLabel];
+/** The block to print on stdout, one string per line, heading first. */
+export declare function statusLines(fields: Record<string, unknown>): string[];

package/dist/command/cli/status/status-lines.js

@@ -0,0 +1,117 @@
+/**
+ * `reticle status`, rendered for a person.
+ *
+ * The command printed one line of JSON and nothing else. Its own source called it "the second-most
+ * run command and the one a HUMAN types" — and the answer to that human was
+ * `{"t":"…","event":"reticle_status","port":4400,"running":true,…}`. It is worse than that now that
+ * agents run it: an agent's terminal output is read by the person sitting behind it, so a machine
+ * line is a line two readers have to decode and only one of them can.
+ *
+ * The JSON stays, unchanged, on stderr — it is documented, and it is what a log is for. This is the
+ * same facts on stdout, in the shape `doctor` already uses, so the two commands read as one tool.
+ *
+ * Pure, and tolerant: it is handed the very object the log line is built from, narrows it without
+ * trusting it, and prints what it can recognise. A status that cannot be rendered must still be
+ * logged, so nothing here may throw.
+ */
+/** Every row label this block can print. The one spelling; nothing writes a label inline. */
+export const StatusLabel = {
+    DAEMON: 'daemon',
+    SESSIONS: 'sessions',
+    AGENT_LINK: 'agent link',
+    NEXT: 'next',
+    SPLIT_BRAIN: 'split brain',
+    UPDATE: 'update',
+};
+const LABELS = Object.values(StatusLabel);
+/** The heading, so a reader can tell which command produced the block. */
+const HEADING = 'reticle status';
+const INDENT = '  ';
+/** Padded off the longest label, for the same reason `doctor` does it: the column IS the legibility. */
+const LABEL_COLUMN = LABELS.reduce((widest, l) => Math.max(widest, l.length), 0) + 2;
+const OK = '✓';
+const NOT_OK = '✗';
+function row(label, rest) {
+    return `${INDENT}${label.padEnd(LABEL_COLUMN)}${rest}`;
+}
+/** A continuation line under a row: indented past the label column, carrying no label of its own. */
+function continuation(rest) {
+    return `${INDENT}${' '.repeat(LABEL_COLUMN)}${rest}`;
+}
+function str(fields, key) {
+    const v = fields[key];
+    return 'string' === typeof v && v.length > 0 ? v : undefined;
+}
+function num(fields, key) {
+    const v = fields[key];
+    return 'number' === typeof v ? v : undefined;
+}
+function sessionViews(fields) {
+    const raw = fields['sessions'];
+    if (!Array.isArray(raw))
+        return [];
+    return raw.flatMap((s) => {
+        if ('object' !== typeof s || null === s)
+            return [];
+        const r = s;
+        // Each of these explains something a reader would otherwise call a bug: a throttled or hidden
+        // tab answers slowly, a stale one answers about a page that has moved on, and an unresponsive
+        // one does not answer at all.
+        const notes = [
+            true === r['throttled'] ? 'throttled' : undefined,
+            true === r['hidden'] ? 'hidden' : undefined,
+            true === r['stale'] ? 'stale' : undefined,
+            true === r['unresponsive'] ? 'unresponsive' : undefined,
+        ].filter((n) => n !== undefined);
+        return [{ url: str(r, 'url') ?? '(no url reported)', notes }];
+    });
+}
+/** The block to print on stdout, one string per line, heading first. */
+export function statusLines(fields) {
+    const port = num(fields, 'port');
+    const at = port === undefined ? '' : ` on :${String(port)}`;
+    const pid = num(fields, 'pid');
+    const running = true === fields['running'];
+    const lines = [HEADING];
+    lines.push(row(StatusLabel.DAEMON, running
+        ? `${OK} running${at}${pid === undefined ? '' : ` (pid ${String(pid)})`}`
+        : `${NOT_OK} not running${at}`));
+    // What was actually ON the port, when the pid file said nothing useful. "A stranger holds this"
+    // and "nothing is here" were the same output once, and the true sentence was said by nothing a
+    // person sees — so the word belongs in the prose, not only in the event.
+    const presence = str(fields, 'presence');
+    if (presence !== undefined)
+        lines.push(continuation(`port presence: ${presence}`));
+    // The refusal a FOREIGN port produces. It is the whole answer when it is present, so it rides the
+    // daemon row rather than waiting for a `next` that is not built in that branch.
+    const reason = str(fields, 'reason');
+    if (reason !== undefined)
+        lines.push(continuation(reason));
+    if (running) {
+        const count = num(fields, 'sessionCount') ?? 0;
+        lines.push(row(StatusLabel.SESSIONS, count > 0
+            ? `${OK} ${String(count)} page${1 === count ? '' : 's'} connected`
+            : `${NOT_OK} no page connected`));
+        for (const s of sessionViews(fields)) {
+            lines.push(continuation(`${s.url}${0 === s.notes.length ? '' : `  (${s.notes.join(', ')})`}`));
+        }
+        // The daemon's own explanation for an empty session list, which outranks anything this command
+        // could infer — it is the one holding the connection.
+        const why = str(fields, 'why');
+        if (why !== undefined)
+            lines.push(continuation(why));
+    }
+    const client = str(fields, 'mcpClient');
+    if (client !== undefined)
+        lines.push(row(StatusLabel.AGENT_LINK, client));
+    for (const [label, key] of [
+        [StatusLabel.NEXT, 'nextAction'],
+        [StatusLabel.SPLIT_BRAIN, 'splitBrain'],
+        [StatusLabel.UPDATE, 'updateAvailable'],
+    ]) {
+        const value = str(fields, key);
+        if (value !== undefined)
+            lines.push(row(label, value));
+    }
+    return lines;
+}

package/dist/command/cli.d.ts

@@ -2,5 +2,5 @@
 import { parseCliArgs, CLI_USAGE } from './cli/cli-parse.js';
 export { parseCliArgs, CLI_USAGE };
 export type { CliResult } from './cli/cli-parse.js';
-export declare function handleStatus(port: number): Promise<void>;
+export declare function handleStatus(port: number, json?: boolean): Promise<void>;
 export declare function main(): void;