@reticlehq/server 3.3.0 → 3.4.0

package/dist/command/setup/bringup/dev-server-files.d.ts

@@ -0,0 +1,68 @@
+/**
+ * What `init` leaves in the state home about a dev server it handed over: the log, its one rotated
+ * predecessor, and a record of where the server is.
+ *
+ * All keyed on the app directory, beside the daemon logs and so outside the project: no bundler
+ * watcher ever sees them change (a `.reticle/` write inside the app once put Vite into a continuous
+ * full-reload loop), and two projects never share a file.
+ */
+import { z } from 'zod';
+export declare function devServerLogName(cwd: string): string;
+/** Where a handed-over server is: enough to find it again and to prove it is still that server. */
+declare const HandedOverSchema: z.ZodObject<{
+    pid: z.ZodNumber;
+    url: z.ZodString;
+    appDir: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    pid: number;
+    appDir: string;
+}, {
+    url: string;
+    pid: number;
+    appDir: string;
+}>;
+export type HandedOver = z.infer<typeof HandedOverSchema>;
+/**
+ * Written when `init` leaves a server running, so the next `init` can attach to it.
+ *
+ * Only Vite announces itself (through its plugin). Re-running init while a Next or Angular server
+ * it had started was still up spawned a second `dev`, which failed with "port 3000 is already in use
+ * — something else is serving there" — the something being the server init itself had left.
+ */
+export declare function recordHandOver(dir: string, record: HandedOver): void;
+/**
+ * The url of the server `init` handed over for `appDir`, when that process is alive AND the url
+ * still answers — both, because a recycled pid proves nothing and a url answering proves only that
+ * SOMETHING is there. Undefined otherwise, and the caller starts one.
+ */
+export declare function handedOverUrl(dir: string, appDir: string, deps: {
+    alive: (pid: number) => boolean;
+    answers: (url: string) => Promise<boolean>;
+}): Promise<string | undefined>;
+/**
+ * Stop the server `init` handed over for `appDir`, and forget it. True when one was stopped.
+ *
+ * For a port move: Next reads the daemon url into `NEXT_PUBLIC_RETICLE_URL` once, when `next dev`
+ * starts, so attaching to the running server after `init --port <new>` left the page dialling the
+ * old port — which the same run had just stopped. Only a server this record proves init started is
+ * touched; one the user started is theirs to restart.
+ */
+export declare function stopHandedOver(dir: string, appDir: string, deps: {
+    alive: (pid: number) => boolean;
+    kill: (pid: number) => void;
+}): boolean;
+/**
+ * Remove what servers that are gone left behind: their logs, rotated logs and records.
+ *
+ * Every run wrote a log per project and nothing ever deleted one, so the state home kept a file for
+ * every app `init` had ever started. A record whose pid is dead takes its logs with it; a log with no
+ * record at all goes once it is old. `keep` is the app about to start, whose files are replaced
+ * anyway.
+ */
+export declare function sweepDeadDevServers(dir: string, deps: {
+    alive: (pid: number) => boolean;
+    now: number;
+    keep?: string;
+}): void;
+export {};

package/dist/command/setup/bringup/dev-server-files.js

@@ -0,0 +1,131 @@
+/**
+ * What `init` leaves in the state home about a dev server it handed over: the log, its one rotated
+ * predecessor, and a record of where the server is.
+ *
+ * All keyed on the app directory, beside the daemon logs and so outside the project: no bundler
+ * watcher ever sees them change (a `.reticle/` write inside the app once put Vite into a continuous
+ * full-reload loop), and two projects never share a file.
+ */
+import { createHash } from 'node:crypto';
+import { readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { ROTATED_SUFFIX } from './dev-server-log-cap.js';
+const DEV_SERVER_PREFIX = 'dev-server-';
+const LOG_SUFFIX = '.log';
+const RECORD_SUFFIX = '.json';
+/**
+ * A log with no record is from a build before records existed, so there is no pid to ask. Anything
+ * this old is from a server long gone; a live one that went this quiet loses a file it was not using.
+ */
+const UNRECORDED_LOG_MAX_AGE_MS = 24 * 60 * 60_000;
+const OWN_FILE = /^dev-server-([0-9a-f]{12})\.(?:log|log\.1|json)$/;
+function keyOf(cwd) {
+    return createHash('sha256').update(cwd).digest('hex').slice(0, 12);
+}
+export function devServerLogName(cwd) {
+    return `${DEV_SERVER_PREFIX}${keyOf(cwd)}${LOG_SUFFIX}`;
+}
+function recordName(cwd) {
+    return `${DEV_SERVER_PREFIX}${keyOf(cwd)}${RECORD_SUFFIX}`;
+}
+/** Where a handed-over server is: enough to find it again and to prove it is still that server. */
+const HandedOverSchema = z.object({
+    pid: z.number().int().positive(),
+    url: z.string().min(1),
+    appDir: z.string().min(1),
+});
+/**
+ * Written when `init` leaves a server running, so the next `init` can attach to it.
+ *
+ * Only Vite announces itself (through its plugin). Re-running init while a Next or Angular server
+ * it had started was still up spawned a second `dev`, which failed with "port 3000 is already in use
+ * — something else is serving there" — the something being the server init itself had left.
+ */
+export function recordHandOver(dir, record) {
+    try {
+        writeFileSync(join(dir, recordName(record.appDir)), JSON.stringify(record));
+    }
+    catch {
+        // Without the record the next run starts a server as it always did. Never fail a handover on it.
+    }
+}
+function readRecord(path) {
+    try {
+        const parsed = HandedOverSchema.safeParse(JSON.parse(readFileSync(path, 'utf8')));
+        return parsed.success ? parsed.data : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The url of the server `init` handed over for `appDir`, when that process is alive AND the url
+ * still answers — both, because a recycled pid proves nothing and a url answering proves only that
+ * SOMETHING is there. Undefined otherwise, and the caller starts one.
+ */
+export async function handedOverUrl(dir, appDir, deps) {
+    const record = readRecord(join(dir, recordName(appDir)));
+    if (undefined === record || record.appDir !== appDir || !deps.alive(record.pid))
+        return undefined;
+    return (await deps.answers(record.url)) ? record.url : undefined;
+}
+/**
+ * Stop the server `init` handed over for `appDir`, and forget it. True when one was stopped.
+ *
+ * For a port move: Next reads the daemon url into `NEXT_PUBLIC_RETICLE_URL` once, when `next dev`
+ * starts, so attaching to the running server after `init --port <new>` left the page dialling the
+ * old port — which the same run had just stopped. Only a server this record proves init started is
+ * touched; one the user started is theirs to restart.
+ */
+export function stopHandedOver(dir, appDir, deps) {
+    const path = join(dir, recordName(appDir));
+    const record = readRecord(path);
+    if (undefined === record || record.appDir !== appDir || !deps.alive(record.pid))
+        return false;
+    deps.kill(record.pid);
+    rmSync(path, { force: true });
+    return true;
+}
+/**
+ * Remove what servers that are gone left behind: their logs, rotated logs and records.
+ *
+ * Every run wrote a log per project and nothing ever deleted one, so the state home kept a file for
+ * every app `init` had ever started. A record whose pid is dead takes its logs with it; a log with no
+ * record at all goes once it is old. `keep` is the app about to start, whose files are replaced
+ * anyway.
+ */
+export function sweepDeadDevServers(dir, deps) {
+    let files;
+    try {
+        files = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    const keepKey = undefined === deps.keep ? undefined : keyOf(deps.keep);
+    // Exactly the names this module writes, so nothing else in the state home can match.
+    const keys = new Set(files.map((f) => OWN_FILE.exec(f)?.[1]).filter((k) => undefined !== k));
+    for (const key of keys) {
+        if (key === keepKey)
+            continue;
+        const log = join(dir, `${DEV_SERVER_PREFIX}${key}${LOG_SUFFIX}`);
+        const recordPath = join(dir, `${DEV_SERVER_PREFIX}${key}${RECORD_SUFFIX}`);
+        const record = readRecord(recordPath);
+        const dead = undefined === record
+            ? deps.now - lastWrittenAt(log) > UNRECORDED_LOG_MAX_AGE_MS
+            : !deps.alive(record.pid);
+        if (!dead)
+            continue;
+        for (const path of [log, `${log}${ROTATED_SUFFIX}`, recordPath])
+            rmSync(path, { force: true });
+    }
+}
+function lastWrittenAt(path) {
+    try {
+        return statSync(path).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+}

package/dist/command/setup/bringup/dev-server-log-cap.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The dev server's log, with a ceiling — and the small process that enforces it.
+ *
+ * The handed-over dev server wrote straight into a file descriptor, which is what keeps it alive once
+ * `init` exits (a pipe whose reader has gone is an EPIPE on the next write). But a descriptor nobody
+ * reads has no ceiling: an upstream echo loop — TanStack devtools and Vite 8 forwarding each other's
+ * console lines — grew `~/.reticle/dev-server-<hash>.log` to 2.9 GB in about five minutes.
+ *
+ * So the server's output goes through a pipe again, and the reader on the other end is THIS script,
+ * run as its own process in the server's process group rather than inside `init`. It lives exactly
+ * as long as the server's output does: it exits when the pipes close, never before, so the EPIPE
+ * that killed handed-over servers cannot come back. It ignores the signals a group stop sends, for
+ * the same reason — the server gets them too, and may still be writing on its way out.
+ *
+ * The bound is rotation, not truncation: past the cap the file is renamed to `<log>.1` (replacing
+ * the previous one) and a fresh file started, so disk use stays under twice the cap while the most
+ * recent output — the part anybody reads — is always there.
+ *
+ * Why not truncate from the daemon on a timer: the daemon idles out on its own schedule and a
+ * handed-over server does not, so the one bound that matters would stop being enforced exactly when
+ * nobody is watching. A reader that shares the server's lifetime cannot be outlived by it.
+ */
+/** Per file. The log and its one rotated predecessor together never exceed twice this. */
+export declare const DEV_SERVER_LOG_CAP_BYTES: number;
+/** The single predecessor a rotation keeps. */
+export declare const ROTATED_SUFFIX = ".1";
+/** Appends to `path`, rotating it to `path.1` whenever the next write would pass `capBytes`. */
+export declare class BoundedLog {
+    #private;
+    private readonly path;
+    private readonly capBytes;
+    constructor(path: string, capBytes?: number);
+    write(chunk: Buffer): void;
+    close(): void;
+}

package/dist/command/setup/bringup/dev-server-log-cap.js

@@ -0,0 +1,121 @@
+/**
+ * The dev server's log, with a ceiling — and the small process that enforces it.
+ *
+ * The handed-over dev server wrote straight into a file descriptor, which is what keeps it alive once
+ * `init` exits (a pipe whose reader has gone is an EPIPE on the next write). But a descriptor nobody
+ * reads has no ceiling: an upstream echo loop — TanStack devtools and Vite 8 forwarding each other's
+ * console lines — grew `~/.reticle/dev-server-<hash>.log` to 2.9 GB in about five minutes.
+ *
+ * So the server's output goes through a pipe again, and the reader on the other end is THIS script,
+ * run as its own process in the server's process group rather than inside `init`. It lives exactly
+ * as long as the server's output does: it exits when the pipes close, never before, so the EPIPE
+ * that killed handed-over servers cannot come back. It ignores the signals a group stop sends, for
+ * the same reason — the server gets them too, and may still be writing on its way out.
+ *
+ * The bound is rotation, not truncation: past the cap the file is renamed to `<log>.1` (replacing
+ * the previous one) and a fresh file started, so disk use stays under twice the cap while the most
+ * recent output — the part anybody reads — is always there.
+ *
+ * Why not truncate from the daemon on a timer: the daemon idles out on its own schedule and a
+ * handed-over server does not, so the one bound that matters would stop being enforced exactly when
+ * nobody is watching. A reader that shares the server's lifetime cannot be outlived by it.
+ */
+import { spawn } from 'node:child_process';
+import { closeSync, openSync, renameSync, writeSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+/** Per file. The log and its one rotated predecessor together never exceed twice this. */
+export const DEV_SERVER_LOG_CAP_BYTES = 8 * 1024 * 1024;
+const APPEND = 'a';
+const TRUNCATE = 'w';
+/** The single predecessor a rotation keeps. */
+export const ROTATED_SUFFIX = '.1';
+/** Appends to `path`, rotating it to `path.1` whenever the next write would pass `capBytes`. */
+export class BoundedLog {
+    path;
+    capBytes;
+    /** Undefined only between a rotation's close and a reopen that failed; the next write retries. */
+    #fd;
+    #size = 0;
+    constructor(path, capBytes = DEV_SERVER_LOG_CAP_BYTES) {
+        this.path = path;
+        this.capBytes = capBytes;
+        this.#fd = openSync(path, APPEND);
+    }
+    write(chunk) {
+        try {
+            if (this.#fd === undefined || (0 < this.#size && this.#size + chunk.length > this.capBytes)) {
+                this.#rotate();
+            }
+            const fd = this.#fd;
+            if (fd === undefined)
+                return;
+            // A single chunk bigger than the cap is kept only in its tail: it is still bounded.
+            const kept = chunk.length > this.capBytes ? chunk.subarray(chunk.length - this.capBytes) : chunk;
+            writeSync(fd, kept);
+            this.#size += kept.length;
+        }
+        catch {
+            // Disk full, a removed state dir: the output is lost, the server is not. Never throw here.
+        }
+    }
+    close() {
+        const fd = this.#fd;
+        this.#fd = undefined;
+        if (fd === undefined)
+            return;
+        try {
+            closeSync(fd);
+        }
+        catch {
+            /* already closed */
+        }
+    }
+    /**
+     * Close, rename to the predecessor, reopen. A rename that fails (the rotated name is taken, or on
+     * Windows something holds the file) truncates in place instead: the predecessor is lost, the bound
+     * and the newest output are not. It used to leave the descriptor closed, and every later write
+     * vanished inside `write`'s catch.
+     */
+    #rotate() {
+        this.close();
+        let flags = APPEND;
+        try {
+            renameSync(this.path, `${this.path}${ROTATED_SUFFIX}`);
+        }
+        catch {
+            flags = TRUNCATE;
+        }
+        this.#fd = openSync(this.path, flags);
+        this.#size = 0;
+    }
+}
+/** Arguments are `<log path> <cap bytes> <shell command>`, the way `OwnedDevServer` spawns this. */
+function main(argv) {
+    const [logPath, cap, command] = argv;
+    if (undefined === logPath || undefined === command)
+        process.exit(2);
+    const log = new BoundedLog(logPath, Number(cap) || DEV_SERVER_LOG_CAP_BYTES);
+    // Stopping the group signals both of us. The server decides when it is done; this outlives it.
+    for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP'])
+        process.on(signal, () => { });
+    const child = spawn(command, {
+        shell: true,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: process.env,
+    });
+    child.stdout.on('data', (chunk) => log.write(chunk));
+    child.stderr.on('data', (chunk) => log.write(chunk));
+    // `close`, not `exit`: every byte the server wrote is read before this process goes.
+    child.on('close', (code) => {
+        log.close();
+        process.exit(code ?? 1);
+    });
+    child.on('error', () => {
+        log.close();
+        process.exit(1);
+    });
+}
+const entry = process.argv[1];
+if (undefined !== entry && import.meta.url === pathToFileURL(entry).href) {
+    main(process.argv.slice(2));
+}

package/dist/command/setup/bringup/ensure-daemon.d.ts

@@ -8,12 +8,35 @@
  * dial and setup ends with "the SDK is in the page and never dialled the bridge" — the SDK being
  * blamed for the absence of the thing it was dialling.
  *
- * Idempotent by construction: an alive daemon for this project is adopted, and one belonging to
- * somebody else is refused rather than stolen, which is the same rule `reticle mcp` follows.
+ * Idempotent by construction: a daemon that speaks our wire contract is adopted. One that does NOT
+ * is not usable, however healthy its `/status`: an older Reticle turns away every hello from the page
+ * init just instrumented ("bridge refused the connection: invalid message"), and init used to adopt
+ * it anyway, wait out its budget, and blame the page. So a skewed daemon nobody is using is replaced
+ * (stopped by its LISTENER, never `lsof -ti`, which also kills the agent's MCP proxy), and one with
+ * live sessions is left alone with the exact command to run once they are done.
+ *
+ * A stranger on the port that is not a Reticle daemon at all is refused before this runs; see
+ * `bridge-port.ts`.
  */
+import type { DaemonRegistryEntry } from '@reticlehq/core/artifacts';
 interface EnsureDaemonDeps {
+    /**
+     * Whether a daemon's `/status` body says it speaks a different wire contract from this build.
+     * Injected: the judge is `daemonSkew` in cli-launch, the same rule `reticle mcp` warns with.
+     */
+    readonly skewed: (status: unknown) => boolean;
     readonly usable: (port: number) => Promise<boolean>;
+    /** The daemon's `/status` body, or undefined. */
+    readonly status: (port: number) => Promise<unknown>;
+    /** Stop the daemon on the port. True once the port is free. */
+    readonly replace: (port: number) => Promise<boolean>;
     readonly spawn: (port: number) => boolean;
+    /**
+     * A live process already owns this port's pid file — a daemon mid-start that this spawn lost the
+     * lock to. That is exactly what `spawn` returning false means on a fresh HOME where the editor's
+     * `reticle mcp` got there first, and it is a reason to wait, not to give up.
+     */
+    readonly starting: (port: number) => boolean;
     readonly waitReady: (port: number) => Promise<unknown>;
     readonly scriptPath: string | undefined;
 }
@@ -21,10 +44,48 @@ export declare const EnsureDaemon: {
     /** Something usable was already there. */
     readonly ADOPTED: "adopted";
     readonly STARTED: "started";
+    /** A daemon on another wire contract, serving nobody, was stopped and ours started in its place. */
+    readonly REPLACED: "replaced";
+    /** A daemon on another wire contract is serving live sessions, so it was left alone. */
+    readonly SKEWED_IN_USE: "skewed-in-use";
     /** Could not be started, and the caller has to say so rather than blame the page. */
     readonly UNAVAILABLE: "unavailable";
 };
 export type EnsureDaemon = (typeof EnsureDaemon)[keyof typeof EnsureDaemon];
-export declare function ensureDaemon(port: number, deps: EnsureDaemonDeps): Promise<EnsureDaemon>;
-export declare function nodeEnsureDaemonDeps(): EnsureDaemonDeps;
+interface EnsureDaemonResult {
+    readonly state: EnsureDaemon;
+    /** One line for the person watching, when the state needs one. */
+    readonly message?: string;
+}
+export declare function ensureDaemon(port: number, deps: EnsureDaemonDeps): Promise<EnsureDaemonResult>;
+interface RetireDeps {
+    /** Every LIVE daemon in the registry. */
+    readonly registered: () => readonly DaemonRegistryEntry[];
+    readonly status: (port: number) => Promise<unknown>;
+    /** Stop the daemon on the port by its listener. True once the port is free. */
+    readonly stop: (port: number) => Promise<boolean>;
+}
+/**
+ * Stop this project's daemons on any port but `port`, the one init is about to use. Returns the
+ * ports stopped.
+ *
+ * `init --port <new>` started a daemon on the new port and left the old one serving: the build
+ * plugin found both, dialled the old one, and init — waiting on the new one — exited 1 with
+ * "connected to a DIFFERENT Reticle daemon". A daemon another project's tab is still on is left
+ * alone, because stopping it would take that app down to fix this one. Stopped by its listener
+ * (`runKill` without force), never `lsof -ti`, which also kills the agent's MCP proxy.
+ */
+export declare function retireMovedDaemons(projectId: string | undefined, port: number, deps: RetireDeps): Promise<number[]>;
+/** The real registry, `/status` and listener-only stop. */
+export declare function nodeRetireDeps(): RetireDeps;
+/**
+ * Hold the daemon on `port` until the returned release is called, by renewing a hold on its
+ * `/status` well inside the hold window.
+ *
+ * `init` starts the daemon and can then wait on the app for longer than the idle grace — a cold
+ * desktop build, a slow first compile. None of that counted as activity, and the daemon init had
+ * just started idled out (`reticle_daemon_idle_exit`) while init was still waiting on it.
+ */
+export declare function holdDaemon(port: number): () => void;
+export declare function nodeEnsureDaemonDeps(skewed: (status: unknown) => boolean): EnsureDaemonDeps;
 export {};

package/dist/command/setup/bringup/ensure-daemon.js

@@ -8,51 +8,170 @@
  * dial and setup ends with "the SDK is in the page and never dialled the bridge" — the SDK being
  * blamed for the absence of the thing it was dialling.
  *
- * Idempotent by construction: an alive daemon for this project is adopted, and one belonging to
- * somebody else is refused rather than stolen, which is the same rule `reticle mcp` follows.
+ * Idempotent by construction: a daemon that speaks our wire contract is adopted. One that does NOT
+ * is not usable, however healthy its `/status`: an older Reticle turns away every hello from the page
+ * init just instrumented ("bridge refused the connection: invalid message"), and init used to adopt
+ * it anyway, wait out its budget, and blame the page. So a skewed daemon nobody is using is replaced
+ * (stopped by its LISTENER, never `lsof -ti`, which also kills the agent's MCP proxy), and one with
+ * live sessions is left alone with the exact command to run once they are done.
+ *
+ * A stranger on the port that is not a Reticle daemon at all is refused before this runs; see
+ * `bridge-port.ts`.
  */
 import { log } from '../../../log.js';
-import { spawnDaemon } from '../../daemon/daemon.js';
+import { isAlive, readPid, reticleStateHome, spawnDaemon } from '../../daemon/daemon.js';
+import { readDaemonRegistry } from '../../daemon/daemon-resolve.js';
+import { LOOPBACK_HOST, STATUS_HOLD_MS } from '@reticlehq/core';
 import { probePresence, presenceIsUsable } from '../../daemon/binding/port-presence.js';
-import { waitForDaemon, probeDaemon } from '../../../surface/mcp/mcp-proxy.js';
+import { probeDaemon, waitForDaemonBind } from '../../../surface/mcp/mcp-proxy.js';
 import { daemonSpawnArgs } from '../../cli/daemon-start-options.js';
-import { fetchStatus } from '../../daemon/binding/daemon-status-probe.js';
+import { fetchStatus, summarizeStatus } from '../../daemon/binding/daemon-status-probe.js';
+import { runKill } from '../../cli/cli-kill.js';
 export const EnsureDaemon = {
     /** Something usable was already there. */
     ADOPTED: 'adopted',
     STARTED: 'started',
+    /** A daemon on another wire contract, serving nobody, was stopped and ours started in its place. */
+    REPLACED: 'replaced',
+    /** A daemon on another wire contract is serving live sessions, so it was left alone. */
+    SKEWED_IN_USE: 'skewed-in-use',
     /** Could not be started, and the caller has to say so rather than blame the page. */
     UNAVAILABLE: 'unavailable',
 };
-export async function ensureDaemon(port, deps) {
-    if (await deps.usable(port))
-        return EnsureDaemon.ADOPTED;
+/** A string field off the /status body, or undefined on a daemon too old to report it. */
+function statusString(payload, key) {
+    if ('object' !== typeof payload || null === payload)
+        return undefined;
+    const value = Reflect.get(payload, key);
+    return 'string' === typeof value && 0 < value.length ? value : undefined;
+}
+async function spawnAndWait(port, deps) {
     if (undefined === deps.scriptPath)
-        return EnsureDaemon.UNAVAILABLE;
-    if (!deps.spawn(port))
-        return EnsureDaemon.UNAVAILABLE;
+        return false;
+    // A lost spawn race is not a failed start: `init` printed "could not start the Reticle daemon"
+    // over a daemon that bound seconds later. Only a spawn that failed with nobody else starting one
+    // is a reason to stop without waiting.
+    if (!deps.spawn(port) && !deps.starting(port))
+        return false;
     try {
         // Readiness means the port ACCEPTS, not that a child was spawned: a readiness signal that
         // precedes readiness is worse than none, because what waits on it stops waiting too early.
         await deps.waitReady(port);
     }
     catch {
-        return EnsureDaemon.UNAVAILABLE;
+        return false;
+    }
+    return deps.usable(port);
+}
+export async function ensureDaemon(port, deps) {
+    if (await deps.usable(port)) {
+        const status = await deps.status(port);
+        if (!deps.skewed(status))
+            return { state: EnsureDaemon.ADOPTED };
+        const theirs = statusString(status, 'version') ?? 'an older build';
+        const { sessionCount } = summarizeStatus(status);
+        if (0 < sessionCount) {
+            return {
+                state: EnsureDaemon.SKEWED_IN_USE,
+                message: `The Reticle daemon on port ${String(port)} is ${theirs}, which speaks a different wire ` +
+                    `contract than this init, so it will refuse your app — and ` +
+                    `${String(sessionCount)} session(s) are still using it, so init will not stop it. When ` +
+                    `they are done, run \`npx @reticlehq/server kill --port ${String(port)}\` and re-run init.`,
+            };
+        }
+        if (!(await deps.replace(port)))
+            return { state: EnsureDaemon.UNAVAILABLE };
+        return (await spawnAndWait(port, deps))
+            ? {
+                state: EnsureDaemon.REPLACED,
+                message: `replaced the idle Reticle daemon on port ${String(port)} (${theirs}), which speaks a ` +
+                    `different wire contract and would have refused your app, with a current one.`,
+            }
+            : { state: EnsureDaemon.UNAVAILABLE };
+    }
+    return (await spawnAndWait(port, deps))
+        ? { state: EnsureDaemon.STARTED }
+        : { state: EnsureDaemon.UNAVAILABLE };
+}
+/**
+ * Stop this project's daemons on any port but `port`, the one init is about to use. Returns the
+ * ports stopped.
+ *
+ * `init --port <new>` started a daemon on the new port and left the old one serving: the build
+ * plugin found both, dialled the old one, and init — waiting on the new one — exited 1 with
+ * "connected to a DIFFERENT Reticle daemon". A daemon another project's tab is still on is left
+ * alone, because stopping it would take that app down to fix this one. Stopped by its listener
+ * (`runKill` without force), never `lsof -ti`, which also kills the agent's MCP proxy.
+ */
+export async function retireMovedDaemons(projectId, port, deps) {
+    if (undefined === projectId || 0 === projectId.length)
+        return [];
+    const stopped = [];
+    for (const entry of deps.registered()) {
+        if (entry.projectId !== projectId || entry.port === port)
+            continue;
+        const { sessions } = summarizeStatus(await deps.status(entry.port));
+        const shared = sessions.some((s) => undefined !== s.projectId && projectId !== s.projectId);
+        if (shared)
+            continue;
+        if (await deps.stop(entry.port))
+            stopped.push(entry.port);
     }
-    return (await deps.usable(port)) ? EnsureDaemon.STARTED : EnsureDaemon.UNAVAILABLE;
+    return stopped;
+}
+/** The real registry, `/status` and listener-only stop. */
+export function nodeRetireDeps() {
+    return {
+        registered: () => readDaemonRegistry(reticleStateHome()).filter((e) => isAlive(e.pid)),
+        status: (port) => fetchStatus(port),
+        stop: (port) => runKill(port, false),
+    };
+}
+/**
+ * Hold the daemon on `port` until the returned release is called, by renewing a hold on its
+ * `/status` well inside the hold window.
+ *
+ * `init` starts the daemon and can then wait on the app for longer than the idle grace — a cold
+ * desktop build, a slow first compile. None of that counted as activity, and the daemon init had
+ * just started idled out (`reticle_daemon_idle_exit`) while init was still waiting on it.
+ */
+export function holdDaemon(port) {
+    const renew = () => void fetchStatus(port, LOOPBACK_HOST, true);
+    renew();
+    const timer = setInterval(renew, STATUS_HOLD_MS / 3);
+    timer.unref();
+    return () => clearInterval(timer);
 }
-export function nodeEnsureDaemonDeps() {
+export function nodeEnsureDaemonDeps(skewed) {
     return {
+        skewed,
         usable: async (port) => presenceIsUsable(await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus })),
+        status: (port) => fetchStatus(port),
+        // `reticle kill` without `--force`: it signals only the LISTENER, and only one that answers
+        // /status, so the agent's MCP proxy on the same port survives.
+        replace: (port) => runKill(port, false),
         spawn: (port) => {
             const scriptPath = process.argv[1];
             if (undefined === scriptPath)
                 return false;
             const started = spawnDaemon(process.execPath, scriptPath, daemonSpawnArgs({ port, headless: true, http: false }), port);
-            log('reticle_setup_daemon_started', { port, started });
+            // For a log or a pipe. On a terminal it was a JSON line in the middle of `init`'s output, read
+            // by a person, about a step the next lines already report in words.
+            if (true !== process.stderr.isTTY)
+                log('reticle_setup_daemon_started', { port, started });
             return started;
         },
-        waitReady: (port) => waitForDaemon(port),
+        starting: (port) => {
+            const pid = readPid(port);
+            return null !== pid && isAlive(pid);
+        },
+        // The same wait `reticle restart` does: poll until `/status` answers as a daemon, bounded. A
+        // cold daemon on a fresh HOME outlived the proxy's shorter reconnect budget this used to borrow.
+        waitReady: async (port) => {
+            if (!(await waitForDaemonBind(port)))
+                throw new Error(`no daemon bound :${String(port)}`);
+            return undefined;
+        },
         scriptPath: process.argv[1],
     };
 }

package/dist/command/setup/bringup/static-page-server.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The dev server `init` starts for a plain HTML page that has none of its own.
+ *
+ * A directory holding only `index.html` (and a script or two) used to be wired correctly — init
+ * writes the connect snippet into the page — and then stop at "No dev command … start the app
+ * yourself and pass --url". The one thing left between that user and a connected session was a web
+ * server, which is the one thing a page like that never had. So init starts this one, the same way it
+ * starts `npm run dev`, and the rest of setup (wait, open, prove the connect) runs unchanged.
+ *
+ * It is run as its own process (`node static-page-server.js --dir <app>`), not inside init, because it
+ * has to outlive init exactly like any handed-over dev server. It imports nothing but Node, so the
+ * built file runs on its own.
+ *
+ * Loopback only, on both families: a page served to the LAN would publish the pairing token the
+ * snippet carries.
+ */
+export declare const STATIC_PAGE_INDEX = "index.html";
+/** Where the search for a free port starts when none is given — clear of Vite's 5173 run. */
+export declare const STATIC_PAGE_FIRST_PORT = 5500;
+export interface StaticPageServer {
+    readonly url: string;
+    close(): Promise<void>;
+}
+export declare function startStaticPageServer(opts: {
+    root: string;
+    port: number;
+}): Promise<StaticPageServer>;
+/**
+ * The command setup runs for a page with no dev server of its own, or undefined when this is not
+ * that page. Quoted so an app path with a space survives the shell.
+ */
+export declare function staticPageDevCommand(opts: {
+    appDir: string;
+    isStaticPage: boolean;
+}): string | undefined;