@reticlehq/server 3.3.0 → 3.5.0

package/dist/command/daemon/lifetime/daemon-usefulness.js

@@ -19,6 +19,7 @@
  * anybody could lose. When it does shut down, the MCP proxy reconnects and `ensureDaemon` spawns a
  * fresh one on the next call, which is a path already exercised hundreds of times a day.
  */
+import { STATUS_HOLD_MS } from '@reticlehq/core';
 /** Set the first time any tool is dispatched through runTool — the chokepoint every path shares. */
 let servedToolCall = false;
 export function noteToolCall() {
@@ -27,9 +28,30 @@ export function noteToolCall() {
 export function everServedToolCall() {
     return servedToolCall;
 }
+/**
+ * How long one hold from a setup run keeps the daemon from idling out. `init` renews it on a timer
+ * well inside this window for as long as it runs, so a run that dies stops holding within it.
+ */
+export const SETUP_HOLD_MS = STATUS_HOLD_MS;
+/**
+ * When a setup run last said it is waiting on this daemon — see STATUS_HOLD_QUERY.
+ *
+ * `init` starts the daemon and can then wait on the app longer than the idle grace: a cold desktop
+ * build, a slow first compile. The daemon counted none of that as activity, idled out
+ * (`reticle_daemon_idle_exit`) while init was still waiting for the app to dial it, and the app came
+ * up to a closed port.
+ */
+let setupHeldAt;
+export function noteSetupHold(now) {
+    setupHeldAt = now;
+}
+function setupHolding(now) {
+    return undefined !== setupHeldAt && now - setupHeldAt < SETUP_HOLD_MS;
+}
 /** Tests only. */
 export function resetDaemonUsefulness() {
     servedToolCall = false;
+    setupHeldAt = undefined;
 }
 /**
  * True when the daemon has done nothing for anyone and has nothing to lose by exiting.
@@ -49,13 +71,14 @@ export function isUselessDaemon(facts) {
  * clause the shutdown watcher could never fire on the many daemons that spawn in a directory with
  * no app and sit there for the length of an editor session.
  */
-export function buildIdlePredicate(agentConnected, sessions, pool) {
-    return () => (!agentConnected() ||
-        isUselessDaemon({
-            servedToolCall: everServedToolCall(),
-            everConnected: sessions.everConnected(),
-            activeLeases: pool.activeCount(),
-        })) &&
+export function buildIdlePredicate(agentConnected, sessions, pool, now = () => Date.now()) {
+    return () => !setupHolding(now()) &&
+        (!agentConnected() ||
+            isUselessDaemon({
+                servedToolCall: everServedToolCall(),
+                everConnected: sessions.everConnected(),
+                activeLeases: pool.activeCount(),
+            })) &&
         0 === sessions.count() &&
         0 === pool.activeCount();
 }

package/dist/command/dev/stale-issue-guard.d.ts

@@ -8,10 +8,9 @@
  *
  * ## Why `fixed-pending-release` is an accepted answer
  *
- * Work fixed on an unreleased branch is legitimately still open; the issue closes when the version
- * ships. The label is what tells a contributor not to start, so the label — not the closure — is
- * what this guard is actually asking for. That is also why the fix is cheap: nobody has to change
- * when they close things, only to say so.
+ * Work that is already ON the release branch is legitimately still open; the issue closes when the
+ * version ships. The label is that fact. It is not a fact about an open pull request. Applying it
+ * there is what told contributors a fix had shipped when the pull request was still unmerged.
  *
  * Pure. The git log and the GitHub lookup belong to the caller, which is what makes every branch
  * below testable without a network or a repo.

package/dist/command/dev/stale-issue-guard.js

@@ -8,10 +8,9 @@
  *
  * ## Why `fixed-pending-release` is an accepted answer
  *
- * Work fixed on an unreleased branch is legitimately still open; the issue closes when the version
- * ships. The label is what tells a contributor not to start, so the label — not the closure — is
- * what this guard is actually asking for. That is also why the fix is cheap: nobody has to change
- * when they close things, only to say so.
+ * Work that is already ON the release branch is legitimately still open; the issue closes when the
+ * version ships. The label is that fact. It is not a fact about an open pull request. Applying it
+ * there is what told contributors a fix had shipped when the pull request was still unmerged.
  *
  * Pure. The git log and the GitHub lookup belong to the caller, which is what makes every branch
  * below testable without a network or a repo.
@@ -61,9 +60,10 @@ export function staleIssues(claimed, issues) {
 /** The message the guard prints. Held here so the check and its tests cannot describe it differently. */
 export function staleIssueReport(stale) {
     const list = stale.map((n) => `#${String(n)}`).join(', ');
+    const pronoun = 1 === stale.length ? 'it' : 'them';
     return (`${list} ${1 === stale.length ? 'is' : 'are'} still OPEN, and a commit on this branch says it ` +
-        `closes ${1 === stale.length ? 'it' : 'them'}. Anyone browsing the tracker reads that as work ` +
-        `nobody has started. Close ${1 === stale.length ? 'it' : 'them'}, or label ` +
-        `${1 === stale.length ? 'it' : 'them'} \`${PENDING_RELEASE_LABEL}\` if the fix is waiting on a ` +
-        `release. This has cost three contributors an evening each; it is not bookkeeping.`);
+        `closes ${pronoun}. Anyone browsing the tracker reads that as work nobody has started. Close ` +
+        `${pronoun} when this merges. Do not apply \`${PENDING_RELEASE_LABEL}\` from an open pull ` +
+        `request: that label means the fix is already on the release branch and waiting for the version ` +
+        `to ship. Applying it earlier is what sent contributors away from work that was not merged.`);
 }

package/dist/command/setup/bringup/connect-lease.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The connect proof for a run with no system browser to lean on: `init --no-open`, CI, a container,
+ * an agent, or a launcher that failed.
+ *
+ * Opens the app in a lease on the daemon at `port`, over the MCP transport every daemon serves --
+ * the same route `reticle verify` takes, so there is no second browser stack and no second daemon
+ * fighting this one for the port.
+ */
+/** A lease this run opened, and the way to hand it back; or why it could not be opened. */
+type LeaseOutcome = {
+    readonly sessionId: string;
+    readonly release: () => Promise<void>;
+} | {
+    readonly failed: string;
+};
+export declare function openLeaseFor(port: number, url: string, token: string | undefined): Promise<LeaseOutcome>;
+export {};

package/dist/command/setup/bringup/connect-lease.js

@@ -0,0 +1,38 @@
+/**
+ * The connect proof for a run with no system browser to lean on: `init --no-open`, CI, a container,
+ * an agent, or a launcher that failed.
+ *
+ * Opens the app in a lease on the daemon at `port`, over the MCP transport every daemon serves --
+ * the same route `reticle verify` takes, so there is no second browser stack and no second daemon
+ * fighting this one for the port.
+ */
+import { acquireLease, connectOverSse, endpointFor, releaseLease, } from '../../cli/adhoc-verdict.js';
+const reason = (error) => (error instanceof Error ? error.message : String(error));
+export async function openLeaseFor(port, url, token) {
+    let caller;
+    try {
+        caller = await connectOverSse(endpointFor(port, token));
+    }
+    catch (error) {
+        return { failed: `could not reach the daemon on port ${String(port)}: ${reason(error)}` };
+    }
+    const close = () => caller.close().catch(() => undefined);
+    try {
+        const got = await acquireLease(caller, url);
+        if ('failed' in got) {
+            await close();
+            return { failed: got.failed.join(' ') };
+        }
+        return {
+            sessionId: got.leased,
+            release: async () => {
+                await releaseLease(caller, got.leased);
+                await close();
+            },
+        };
+    }
+    catch (error) {
+        await close();
+        return { failed: reason(error) };
+    }
+}

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/dev-server-wait.d.ts

@@ -25,6 +25,8 @@ export interface WaitFacts {
     readonly quietForMs: number;
     /** Milliseconds since the wait began. */
     readonly elapsedMs: number;
+    /** Explicit caller limit; otherwise a busy build keeps the default ceiling. */
+    readonly budgetMs?: number | undefined;
     /**
      * How long silence may mean "still starting" on THIS machine. Defaults to QUIET_MEANS_HUNG_MS.
      *

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

@@ -38,7 +38,7 @@ export function judgeWait(facts) {
         return WaitVerdict.READY;
     if (facts.launcherExited)
         return WaitVerdict.DEAD;
-    if (facts.elapsedMs >= WAIT_CEILING_MS)
+    if (facts.elapsedMs >= (facts.budgetMs ?? WAIT_CEILING_MS))
         return WaitVerdict.HUNG;
     // Output IS progress. Silence is what distinguishes a build from a wedge.
     return facts.quietForMs >= (facts.quietMeansHungMs ?? QUIET_MEANS_HUNG_MS)

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 {};