@reticlehq/server 3.1.0 → 3.3.0

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

@@ -3,8 +3,9 @@
  * These are thin clients over the `/v1` API; the logic is server-side and these verbs just surface it.
  * Credentials live under `~/.reticle`: `session.json` (human token from `reticle login`) and
  * `credentials.json` (per-project api keys from `reticle link`). The non-secret repo binding + sync policy
- * is `<repo>/.reticle/cloud.json`. Auth for a command = `RETICLE_CLOUD_KEY` env (agent) OR the login token.
+ * is `<repo>/.reticle/cloud.json`. Auth for a command = `RETICLE_API_KEY` env (agent) OR the login token.
  */
+import { apiKeyFrom } from '@reticlehq/core';
 import { mkdir, writeFile } from 'node:fs/promises';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { homedir } from 'node:os';
@@ -188,8 +189,8 @@ const cmdProject = async (argv) => {
         // Name BOTH hosts when there is a session for a different one. "Run reticle login" on its own is
         // baffling to somebody who just did — the useful fact is that they logged in somewhere else.
         err(null !== active && normalizeUrl(active.url) !== url
-            ? `signed in to ${normalizeUrl(active.url)}, but this command targets ${url} — run \`reticle login --url ${url}\`, or set RETICLE_CLOUD_KEY`
-            : `not signed in to ${url} — run \`reticle login --url ${url}\`, or set RETICLE_CLOUD_KEY`);
+            ? `signed in to ${normalizeUrl(active.url)}, but this command targets ${url} — run \`reticle login --url ${url}\`, or set RETICLE_API_KEY`
+            : `not signed in to ${url} — run \`reticle login --url ${url}\`, or set RETICLE_API_KEY`);
         return 2;
     }
     const sub = argv[0];
@@ -232,7 +233,7 @@ const cmdProject = async (argv) => {
 };
 /**
  * `reticle link [--project <id>]` — bind THIS repo to a cloud project. With a login token it MINTS a
- * project-scoped key (no pasting); with a pre-set RETICLE_CLOUD_KEY it resolves the key's project via
+ * project-scoped key (no pasting); with a pre-set RETICLE_API_KEY it resolves the key's project via
  * whoami. Writes the non-secret binding to <repo>/.reticle/cloud.json and the secret key to
  * ~/.reticle/credentials.json (keyed by projectId).
  */
@@ -241,7 +242,7 @@ const cmdLink = async (argv) => {
     const url = baseUrl(await readSession(), f['url']);
     // Same rule as every other authed verb: the token is looked up by the host it will be sent to.
     const session = await readSessionFor(url);
-    const envKey = process.env['RETICLE_CLOUD_KEY'];
+    const envKey = apiKeyFrom(process.env);
     /*
      * Read the existing binding FIRST, because it decides which project a bare `link` targets.
      * Re-running `link` is ordinary — rotating a key, repointing an environment — and it must land in
@@ -361,7 +362,7 @@ const cmdLink = async (argv) => {
         }
     }
     else {
-        err('run `reticle login` first, or set RETICLE_CLOUD_KEY to link with an existing key');
+        err('run `reticle login` first, or set RETICLE_API_KEY to link with an existing key');
         return 2;
     }
     const reticleDir = join(process.cwd(), RETICLE_DIR);

package/dist/command/cli/cloud-kit.d.ts

@@ -1,6 +1,4 @@
 import { type Session } from './auth/cloud-session.js';
-/** Where `reticle login` dials when nothing says otherwise: the hosted service. */
-export declare const DEFAULT_URL = "https://app.reticle.sh";
 export declare const RETICLE_DIR = ".reticle";
 export declare const SESSION_FILE = "session.json";
 export declare const CREDENTIALS_FILE = "credentials.json";

package/dist/command/cli/cloud-kit.js

@@ -8,6 +8,7 @@
  * `cloud-login` is the first to move — and it is a real seam rather than a file-size dodge: nothing
  * here knows what a project, a credential or a link is.
  */
+import { apiKeyFrom } from '@reticlehq/core';
 import { readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
@@ -15,7 +16,7 @@ import { z } from 'zod';
 import { cloudFetch } from '../../memory/cloud/cloud-sync.js';
 import { normalizeUrl, readSessionFrom, resolveSessionFor, sessionPath, } from './auth/cloud-session.js';
 /** Where `reticle login` dials when nothing says otherwise: the hosted service. */
-export const DEFAULT_URL = 'https://app.reticle.sh';
+const DEFAULT_URL = 'https://app.reticle.sh';
 export const RETICLE_DIR = '.reticle';
 export const SESSION_FILE = 'session.json';
 export const CREDENTIALS_FILE = 'credentials.json';
@@ -83,12 +84,7 @@ export const baseUrl = (session, explicit) => {
     return DEFAULT_URL;
 };
 /** Bearer for a command: an explicit api key (agent) wins, else the human login token. */
-export const bearer = (session) => {
-    const key = process.env['RETICLE_CLOUD_KEY'];
-    if (key !== undefined && key.length > 0)
-        return key;
-    return session?.token ?? null;
-};
+export const bearer = (session) => apiKeyFrom(process.env) ?? session?.token ?? null;
 /** One `/v1` call. Throws a friendly Error on a non-2xx so the command surfaces it and exits 1. */
 export const api = async (method, url, token, body) => {
     const headers = {};

package/dist/command/cli/config/config-discovery.d.ts

@@ -32,5 +32,17 @@ export interface ConfigDiscovery {
     /** Every directory checked, in the order checked. The answer to "are you sure?". */
     searched: string[];
 }
+/**
+ * Has this directory ever been through `init` — is there a `.reticle.json` in it?
+ *
+ * A single directory, not a walk: the caller is asking whether THIS tree invited Reticle in, which
+ * is what decides whether a session with no resolvable project may write here at all. An ancestor's
+ * config says nothing about that, so the up-walk `discoverProjectConfigs` does would answer a
+ * different question and answer it yes too often.
+ *
+ * Lives here so the question stays in the directory that owns the config file, rather than every
+ * caller importing the basename and re-deriving the join.
+ */
+export declare function hasProjectConfig(directory: string): boolean;
 export declare function discoverProjectConfigs(cwd: string): ConfigDiscovery;
 export {};

package/dist/command/cli/config/config-discovery.js

@@ -114,6 +114,25 @@ function firstSegment(glob) {
     const [first] = glob.split('/');
     return first ?? '';
 }
+/**
+ * Has this directory ever been through `init` — is there a `.reticle.json` in it?
+ *
+ * A single directory, not a walk: the caller is asking whether THIS tree invited Reticle in, which
+ * is what decides whether a session with no resolvable project may write here at all. An ancestor's
+ * config says nothing about that, so the up-walk `discoverProjectConfigs` does would answer a
+ * different question and answer it yes too often.
+ *
+ * Lives here so the question stays in the directory that owns the config file, rather than every
+ * caller importing the basename and re-deriving the join.
+ */
+export function hasProjectConfig(directory) {
+    try {
+        return existsSync(join(directory, RETICLE_CONFIG_BASENAME));
+    }
+    catch {
+        return false;
+    }
+}
 export function discoverProjectConfigs(cwd) {
     const searched = [];
     const found = [];

package/dist/command/cli/doctor/doctor-rows.d.ts

@@ -40,6 +40,18 @@ export declare const DoctorRow: {
      * verification." Every row in this list checks a COMPONENT; none checked a LINK.
      */
     readonly AGENT_LINK: "agent link";
+    /**
+     * Which of `localhost`'s two answers reaches the bridge, printed only when they disagree.
+     *
+     * The daemon binds `127.0.0.1` and `loopback-alias.ts` forwards `[::1]` to it, best-effort —
+     * a machine with IPv6 off, or something already holding `[::1]:port`, leaves the daemon serving
+     * IPv4 alone and must not be fatal. But `localhost` is a NAME, and Windows Chrome tries the IPv6
+     * answer first, so on that combination the SDK's documented default URL cannot reach a daemon that
+     * is running perfectly. The only record of the alias failing was a field on one JSON log line.
+     *
+     * Conditional like `version`: a healthy machine answers on both and prints nothing.
+     */
+    readonly LOOPBACK: "loopback";
     readonly BRIDGE_PORT: "bridge port";
     readonly PORT_CHECK: "port check";
     readonly SIBLING: "sibling";

package/dist/command/cli/doctor/doctor-rows.js

@@ -40,6 +40,18 @@ export const DoctorRow = {
      * verification." Every row in this list checks a COMPONENT; none checked a LINK.
      */
     AGENT_LINK: 'agent link',
+    /**
+     * Which of `localhost`'s two answers reaches the bridge, printed only when they disagree.
+     *
+     * The daemon binds `127.0.0.1` and `loopback-alias.ts` forwards `[::1]` to it, best-effort —
+     * a machine with IPv6 off, or something already holding `[::1]:port`, leaves the daemon serving
+     * IPv4 alone and must not be fatal. But `localhost` is a NAME, and Windows Chrome tries the IPv6
+     * answer first, so on that combination the SDK's documented default URL cannot reach a daemon that
+     * is running perfectly. The only record of the alias failing was a field on one JSON log line.
+     *
+     * Conditional like `version`: a healthy machine answers on both and prints nothing.
+     */
+    LOOPBACK: 'loopback',
     BRIDGE_PORT: 'bridge port',
     PORT_CHECK: 'port check',
     SIBLING: 'sibling',

package/dist/command/cli/doctor/doctor-sessions-line.d.ts

@@ -1,5 +1,5 @@
 /** What this reads off `/status`. Everything is optional — an older daemon may send none of it. */
-export interface SessionFacts {
+interface SessionFacts {
     sessionCount?: unknown;
     why?: unknown;
 }
@@ -10,3 +10,4 @@ export interface SessionsLine {
     why?: string;
 }
 export declare function sessionsLine(facts: SessionFacts): SessionsLine;
+export {};

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

@@ -11,7 +11,7 @@ import { log } from '../../../log.js';
 import { probePresence, describePresence } from '../../daemon/binding/port-presence.js';
 import { probeDaemon } from '../../../surface/mcp/mcp-proxy.js';
 import { readPid } from '../../daemon/daemon.js';
-import { fetchStatus } from '../launch/cli-launch.js';
+import { fetchStatus } from '../../daemon/binding/daemon-status-probe.js';
 import { captureLookup, findPortHolder } from '../ports/port-holder.js';
 import { DriveMode, decideDriveMode, describeAttached, driveForeignHolder, driveHeadlessOnAttach, driveRaceLost, requestDriveSession, } from './drive-attach.js';
 export function handleDrive(parsed) {

package/dist/command/cli/launch/cli-launch.d.ts

@@ -3,26 +3,7 @@
  * "show me the app" flow (`reticle open`). Split out of cli.ts so that file stays under the size cap.
  * The decision logic is pure (unit-tested); the IO (fetch, OS browser launch) is injected/isolated.
  */
-/** One connected tab as `reticle status` reports it — the at-a-glance health line. */
-interface StatusSession {
-    sessionId: string;
-    url: string;
-    throttled: boolean;
-    stale: boolean;
-    pendingMarks: number;
-    /** The tab is attached and answering nothing — see Session.unresponsive. Absent on an older daemon. */
-    unresponsive?: true;
-}
-/**
- * Reduce the daemon's /status JSON to the compact view `reticle status` prints. Pure: narrows the
- * untrusted wire payload (never `any`) and tolerates a missing/partial body so a malformed response
- * degrades to "running, 0 sessions" instead of throwing.
- */
-export declare function summarizeStatus(payload: unknown): {
-    sessionCount: number;
-    sessions: StatusSession[];
-    why?: string;
-};
+export { summarizeStatus } from '../../daemon/binding/daemon-status-probe.js';
 /**
  * Warn when the daemon already on this port is a different version than this CLI, and attach anyway.
  *
@@ -31,8 +12,6 @@ export declare function summarizeStatus(payload: unknown): {
  * another agent's session on a version bump, which is worse than a loud line.
  */
 export declare function warnOnDaemonSkew(port: number): Promise<void>;
-/** GET the daemon's /status JSON. Resolves to the parsed body, or undefined on any failure. */
-export declare function fetchStatus(port: number): Promise<unknown>;
 /** What `reticle open` should do: reuse an already-connected tab, open a new one, or ask for a url. */
 type OpenDecision = {
     action: 'reuse';
@@ -53,6 +32,7 @@ type OpenDecision = {
  * Decide what `reticle open [url]` does, given the currently-connected tabs. Pure.
  * - no url + a tab connected → reuse it (the app is already open; don't spawn a duplicate).
  * - no url + nothing connected → ask for one.
+ * - a HIDDEN tab is not a candidate: the url is opened instead (its own url, when none was given).
  * - url + a tab already AT that url → reuse it (idempotent — re-running never piles up tabs).
  * - url + a tab on that origin but another page → keep it, and say so (`left-as-is`).
  * - url + no matching tab → open it.
@@ -67,6 +47,7 @@ type OpenDecision = {
 export declare function decideOpen(all: {
     url: string;
     unresponsive?: boolean;
+    hidden?: boolean;
 }[], url: string | undefined): OpenDecision;
 /** The OS command that opens a URL in the default browser, per platform. Pure — unit-tested. */
 export declare function openCommand(url: string, platform: NodeJS.Platform): {
@@ -89,4 +70,3 @@ export declare function openInBrowser(url: string, platform?: NodeJS.Platform, r
  * by spawning a real launcher on a developer machine.
  */
 export declare function launcherFailure(code: number | null, signal: NodeJS.Signals | null): string | null;
-export {};

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

@@ -1,46 +1,19 @@
-import * as http from 'node:http';
 import { NodePlatform } from '../../../machine/platform.js';
 import { spawn } from 'node:child_process';
-import { isOpaqueOrigin, LOOPBACK_HOST, STATUS_PATH } from '@reticlehq/core';
+import { isOpaqueOrigin } from '@reticlehq/core';
 import { daemonFix, describeSkew } from '../../version/version-skew.js';
 import { CONTRACT_FINGERPRINT } from '@reticlehq/core';
 import { SERVER_VERSION } from '../../version/identity/server-version.js';
 import { log } from '../../../log.js';
-import { loopbackAgent } from '../../../surface/loopback-agent.js';
+import { fetchStatus } from '../../daemon/binding/daemon-status-probe.js';
 /**
- * Reduce the daemon's /status JSON to the compact view `reticle status` prints. Pure: narrows the
- * untrusted wire payload (never `any`) and tolerates a missing/partial body so a malformed response
- * degrades to "running, 0 sessions" instead of throwing.
+ * CLI launch + status helpers — the daemon-introspection (`reticle status`) and the one-command
+ * "show me the app" flow (`reticle open`). Split out of cli.ts so that file stays under the size cap.
+ * The decision logic is pure (unit-tested); the IO (fetch, OS browser launch) is injected/isolated.
  */
-export function summarizeStatus(payload) {
-    if (typeof payload !== 'object' || null === payload)
-        return { sessionCount: 0, sessions: [] };
-    const obj = payload;
-    // Carried through to the printed line: with no sessions this is the whole answer, and dropping it
-    // here would silently undo the reason it is on the wire.
-    const why = 'string' === typeof obj['why'] ? obj['why'] : undefined;
-    const raw = Array.isArray(obj['sessions']) ? obj['sessions'] : [];
-    const sessions = raw
-        .map((s) => {
-        if (typeof s !== 'object' || null === s)
-            return null;
-        const r = s;
-        const sessionId = 'string' === typeof r['sessionId'] ? r['sessionId'] : '';
-        if ('' === sessionId)
-            return null;
-        return {
-            sessionId,
-            url: 'string' === typeof r['url'] ? r['url'] : '',
-            throttled: true === r['throttled'],
-            stale: true === r['stale'],
-            pendingMarks: 'number' === typeof r['pendingMarks'] ? r['pendingMarks'] : 0,
-            ...(true === r['unresponsive'] ? { unresponsive: true } : {}),
-        };
-    })
-        .filter((s) => s !== null);
-    const sessionCount = 'number' === typeof obj['sessionCount'] ? obj['sessionCount'] : sessions.length;
-    return { sessionCount, sessions, ...(why === undefined ? {} : { why }) };
-}
+// Parsing the daemon's /status payload lives beside the probe that fetches it; re-exported here for
+// the callers that already import it from this module.
+export { summarizeStatus } from '../../daemon/binding/daemon-status-probe.js';
 /** A string field off the /status body, or undefined on a daemon too old to report it. */
 function statusField(payload, key) {
     if (typeof payload !== 'object' || null === payload)
@@ -68,39 +41,6 @@ export async function warnOnDaemonSkew(port) {
     if (skew !== undefined)
         log('reticle_daemon_skew', { port, warning: skew });
 }
-/** How long the daemon /status probe waits before giving up — a local loopback call is near-instant. */
-const STATUS_PROBE_TIMEOUT_MS = 1000;
-/** GET the daemon's /status JSON. Resolves to the parsed body, or undefined on any failure. */
-export function fetchStatus(port) {
-    return new Promise((resolve) => {
-        const req = http.get({
-            host: LOOPBACK_HOST,
-            port,
-            path: STATUS_PATH,
-            timeout: STATUS_PROBE_TIMEOUT_MS,
-            // Shares the proxy's keep-alive agent: the proxy calls this on every reconnect, and a socket
-            // per probe is the same churn the POST leg was fixed for.
-            agent: loopbackAgent,
-        }, (res) => {
-            let body = '';
-            res.setEncoding('utf8');
-            res.on('data', (chunk) => (body += chunk));
-            res.on('end', () => {
-                try {
-                    resolve(JSON.parse(body));
-                }
-                catch {
-                    resolve(undefined);
-                }
-            });
-        });
-        req.on('error', () => resolve(undefined));
-        req.on('timeout', () => {
-            req.destroy();
-            resolve(undefined);
-        });
-    });
-}
 function sameOrigin(a, b) {
     try {
         const origin = new URL(a).origin;
@@ -118,6 +58,7 @@ function sameOrigin(a, b) {
  * Decide what `reticle open [url]` does, given the currently-connected tabs. Pure.
  * - no url + a tab connected → reuse it (the app is already open; don't spawn a duplicate).
  * - no url + nothing connected → ask for one.
+ * - a HIDDEN tab is not a candidate: the url is opened instead (its own url, when none was given).
  * - url + a tab already AT that url → reuse it (idempotent — re-running never piles up tabs).
  * - url + a tab on that origin but another page → keep it, and say so (`left-as-is`).
  * - url + no matching tab → open it.
@@ -133,10 +74,28 @@ export function decideOpen(all, url) {
     // A tab that has stopped answering is not a tab you can be handed. `open` is the command a caller
     // reaches for to RECOVER, and reusing the wedged one left no way out short of killing the daemon:
     // ending the session only flips a flag on the record, it does not make the page answer.
-    const sessions = all.filter((s) => true !== s.unresponsive);
+    //
+    // A HIDDEN tab is excluded for the same reason. `open` means "show me the app", and a backgrounded
+    // tab is the one definition of an app nobody is being shown: the browser starves its timers, rAF
+    // and pointer gestures, so checks that depend on them come back inconclusive even where the
+    // behaviour works. Reported from the field as `open` answering `reusing` for a hidden tab and
+    // three checks that could never resolve. Opening the url instead costs one foreground tab and the
+    // hidden one is left exactly where it was — nothing is navigated out from under anybody.
+    //
+    // HIDDEN, not `throttled`: throttled is `hidden || stale`, and a stale-but-visible tab is usually
+    // a quiet page that drives fine. Excluding those would pile up a duplicate tab per run, which is
+    // the thing the origin match below exists to prevent.
+    const sessions = all.filter((s) => true !== s.unresponsive && true !== s.hidden);
     if (url === undefined) {
         const first = sessions[0];
-        return first !== undefined ? { action: 'reuse', url: first.url } : { action: 'need-url' };
+        if (first !== undefined)
+            return { action: 'reuse', url: first.url };
+        // Nothing visible to hand back, but a hidden tab still knows the url the caller would have
+        // typed. Opening it is the whole request; `need-url` would ask for something already in hand.
+        const backgrounded = all.find((s) => true === s.hidden);
+        return backgrounded !== undefined
+            ? { action: 'open', url: backgrounded.url }
+            : { action: 'need-url' };
     }
     const exact = sessions.find((s) => s.url === url);
     if (exact !== undefined)

package/dist/command/cli/lifecycle/daemon-lifecycle.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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.
+ */
+export declare function handleServe(parsed: {
+    port: number;
+    driveUrl?: string;
+    headless: boolean;
+    http: boolean;
+    httpPort?: number;
+    httpToken?: string;
+}): void;
+export declare function handleStop(port: number, quiet: boolean): void;
+/**
+ * `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 declare function handleRestart(port: number, force: boolean): Promise<void>;

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),