@reticlehq/server 2.14.0 → 3.2.0

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

@@ -0,0 +1,100 @@
+/**
+ * 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.
+ */
+/** One connected tab as `reticle status` reports it — the at-a-glance health line. */
+interface StatusSession {
+    sessionId: string;
+    url: string;
+    throttled: boolean;
+    /**
+     * The tab is backgrounded. Reported by the daemon on every session; `false` on one too old to say,
+     * which reads as visible — the conservative answer, since it keeps the reuse this command has
+     * always done rather than opening a tab on a guess.
+     */
+    hidden: 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;
+    /** The same diagnosis without the differential, for a surface a person reads. */
+    whyLead?: string;
+};
+/**
+ * Warn when the daemon already on this port is a different version than this CLI, and attach anyway.
+ *
+ * Attaching to whatever owns the port is the point of a daemon — but it means an upgrade does not
+ * take effect until that daemon dies, and nothing used to say so. Killing it here would take out
+ * another agent's session on a version bump, which is worse than a loud line.
+ */
+export declare function warnOnDaemonSkew(port: number): Promise<void>;
+/** What `reticle open` should do: reuse an already-connected tab, open a new one, or ask for a url. */
+type OpenDecision = {
+    action: 'reuse';
+    url: string;
+}
+/** A tab on that origin exists, but on another page — kept, and NOT reported as done. */
+ | {
+    action: 'left-as-is';
+    url: string;
+    requested: string;
+} | {
+    action: 'open';
+    url: string;
+} | {
+    action: 'need-url';
+};
+/**
+ * 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.
+ *
+ * The origin match is why re-running this never piles up tabs, and it stays. What changed is the
+ * REPORT: matching by origin meant `reticle open http://localhost:3000/settings` answered `reusing`
+ * for a tab sitting on `http://localhost:3000/` and exited 0, so the caller read a success for a page
+ * that was never opened. Navigating the tab instead was the other option and is worse: `reticle open`
+ * is run by a human whose browser this is, and yanking the page they are looking at to somewhere else
+ * is a bigger surprise than being told where the tab actually is.
+ */
+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): {
+    cmd: string;
+    args: string[];
+};
+/**
+ * Launch the default browser at `url` (detached). The spawn is injected so tests stay hermetic.
+ *
+ * Resolves to whether the launch COMMAND started — not to whether a page appeared. It used to return
+ * nothing at all and the caller printed `{"opened": url}` unconditionally, so a launcher that failed
+ * outright still reported success. Reported from the field as twenty minutes lost chasing a phantom
+ * port problem while nothing had ever opened.
+ */
+export declare function openInBrowser(url: string, platform?: NodeJS.Platform, run?: (cmd: string, args: string[]) => Promise<string | null>): Promise<string | null>;
+/**
+ * What a finished launcher means, or null when nothing is wrong.
+ *
+ * Exported for its own tests: the headless case is the one that matters and it cannot be produced
+ * 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

@@ -0,0 +1,216 @@
+import { NodePlatform } from '../../../machine/platform.js';
+import { spawn } from 'node:child_process';
+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 { 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.
+ */
+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;
+    // Absent on a daemon older than this field, which is why every reader falls back to `why`.
+    const whyLead = 'string' === typeof obj['whyLead'] ? obj['whyLead'] : 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'],
+            hidden: true === r['hidden'],
+            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 }),
+        ...(whyLead === undefined ? {} : { whyLead }),
+    };
+}
+/** 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)
+        return undefined;
+    const value = payload[key];
+    return 'string' === typeof value && value.length > 0 ? value : undefined;
+}
+/**
+ * Warn when the daemon already on this port is a different version than this CLI, and attach anyway.
+ *
+ * Attaching to whatever owns the port is the point of a daemon — but it means an upgrade does not
+ * take effect until that daemon dies, and nothing used to say so. Killing it here would take out
+ * another agent's session on a version bump, which is worse than a loud line.
+ */
+export async function warnOnDaemonSkew(port) {
+    const status = await fetchStatus(port);
+    const daemonVersion = statusField(status, 'version');
+    const skew = describeSkew({
+        what: 'the daemon already running on this port',
+        version: daemonVersion,
+        contract: statusField(status, 'contract'),
+        // The daemon is the peer here and this process is the agent side.
+        fix: daemonFix(daemonVersion, SERVER_VERSION),
+    }, { version: SERVER_VERSION, contract: CONTRACT_FINGERPRINT });
+    if (skew !== undefined)
+        log('reticle_daemon_skew', { port, warning: skew });
+}
+function sameOrigin(a, b) {
+    try {
+        const origin = new URL(a).origin;
+        // Two opaque origins (desktop webviews, file:// docs) BOTH stringify to "null", so comparing them
+        // would call every desktop app the same app and reuse the wrong session. Never match on opaque.
+        if (isOpaqueOrigin(origin))
+            return false;
+        return origin === new URL(b).origin;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 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.
+ *
+ * The origin match is why re-running this never piles up tabs, and it stays. What changed is the
+ * REPORT: matching by origin meant `reticle open http://localhost:3000/settings` answered `reusing`
+ * for a tab sitting on `http://localhost:3000/` and exited 0, so the caller read a success for a page
+ * that was never opened. Navigating the tab instead was the other option and is worse: `reticle open`
+ * is run by a human whose browser this is, and yanking the page they are looking at to somewhere else
+ * is a bigger surprise than being told where the tab actually is.
+ */
+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.
+    //
+    // 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];
+        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)
+        return { action: 'reuse', url: exact.url };
+    const onOrigin = sessions.find((s) => sameOrigin(s.url, url));
+    return onOrigin !== undefined
+        ? { action: 'left-as-is', url: onOrigin.url, requested: url }
+        : { action: 'open', url };
+}
+/**
+ * Percent-encode the cmd.exe metacharacters that `start` re-parses so a URL can't break out into
+ * command execution on Windows (`?next=x&calc` → command chaining). `%` is left untouched so an
+ * already-encoded URL isn't double-encoded; the browser decodes the escapes back to the real URL.
+ */
+function encodeForWindowsStart(url) {
+    return url.replace(/[&^|<>()"'!]/g, (ch) => `%${ch.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+/** The OS command that opens a URL in the default browser, per platform. Pure — unit-tested. */
+export function openCommand(url, platform) {
+    if (NodePlatform.MACOS === platform)
+        return { cmd: 'open', args: [url] };
+    if (NodePlatform.WINDOWS === platform) {
+        return { cmd: 'cmd', args: ['/c', 'start', '', encodeForWindowsStart(url)] };
+    }
+    return { cmd: 'xdg-open', args: [url] };
+}
+/**
+ * Launch the default browser at `url` (detached). The spawn is injected so tests stay hermetic.
+ *
+ * Resolves to whether the launch COMMAND started — not to whether a page appeared. It used to return
+ * nothing at all and the caller printed `{"opened": url}` unconditionally, so a launcher that failed
+ * outright still reported success. Reported from the field as twenty minutes lost chasing a phantom
+ * port problem while nothing had ever opened.
+ */
+export async function openInBrowser(url, platform = process.platform, run = defaultRun) {
+    const { cmd, args } = openCommand(url, platform);
+    return run(cmd, args);
+}
+/**
+ * What a finished launcher means, or null when nothing is wrong.
+ *
+ * Exported for its own tests: the headless case is the one that matters and it cannot be produced
+ * by spawning a real launcher on a developer machine.
+ */
+export function launcherFailure(code, signal) {
+    if (null !== signal)
+        return `the browser launcher was killed by ${signal}`;
+    // null code with no signal: it never reported an outcome in the window we waited. Some desktop
+    // launchers stay attached rather than handing off, and inventing a failure there would be worse
+    // than the silence — it would send someone to fix a browser that opened.
+    if (null === code || 0 === code)
+        return null;
+    return (`the browser launcher exited ${String(code)} — on a machine with no browser (CI, a container, ` +
+        'an SSH session, WSL with no host browser) it starts fine and then has nothing to open');
+}
+/** How long to wait for the launcher to hand off before assuming it did. */
+const LAUNCHER_EXIT_MS = 2_000;
+/** null when the launcher opened something; the failure message when it did not. */
+function defaultRun(cmd, args) {
+    return new Promise((resolve) => {
+        const child = spawn(cmd, args, { detached: true, stdio: 'ignore' });
+        let settled = false;
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(value);
+        };
+        // An unhandled 'error' on a ChildProcess throws — and ENOENT on the launcher is exactly the case
+        // this function exists to report, so it must be listened for either way.
+        child.on('error', (err) => finish(err.message));
+        // The EXIT, not the spawn. Answering "did the command begin" reported success on every headless
+        // box, where the launcher begins perfectly well and then finds nothing to open — see
+        // launcherFailure. Every launcher we use hands off and exits immediately, so this costs nothing
+        // on the path where it works.
+        child.on('exit', (code, signal) => finish(launcherFailure(code, signal)));
+        // ...and a launcher that stays attached must not hold up the install.
+        const timer = setTimeout(() => {
+            child.unref();
+            finish(null);
+        }, LAUNCHER_EXIT_MS);
+        timer.unref?.();
+    });
+}

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 });
+}