@crouter/api 0.3.387 → 0.3.388

package/dist/daemon/manage.js

@@ -0,0 +1,664 @@
+// Daemon management helpers — importable without the full command tree.
+//
+// spawnDaemon() is the low-level spawn call shared by `crtr sys daemon start` and
+// ensureDaemon(). ensureDaemon() is the silent "start if not running" front-
+// door helper called by the canvas runtime before spawning child nodes.
+import { spawn, execFileSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { existsSync, lstatSync, mkdirSync, openSync, closeSync, fstatSync, readSync } from 'node:fs';
+import { crtrHome } from '../core/canvas/paths.js';
+import { listProcessTable } from '../core/canvas/pid.js';
+import { bindDaemonEventSource, eventSource } from '../core/events/source.js';
+import { hostExecPath } from '../core/runtime/branded-host.js';
+// Pulled from the lean db-free pidfile module (NOT crtrd.js, whose module graph
+// reaches openDb) so the CLI daemon front door stays canvas.db-free (plan B-0).
+import { isDaemonRunning, readPidfile, isPidAlive } from './pidfile.js';
+import { DAEMON_STARTUP_WINDOW_MS } from './startup-policy.js';
+import { exclusiveLockOwnerPid } from '../core/exclusive-lock.js';
+import { onDiskMigrationLockPath } from '../core/canvas/paths.js';
+import { envNoDaemonAutostart } from '../shared/env.js';
+import { waitForDaemonAvailability } from '../api/index.js';
+import { localClient } from '../api/node-transport.js';
+// Daemon env sanitization
+/** Env keys that must NEVER reach the daemon process. Restarting crtrd is
+ *  overwhelmingly done from inside an agent node's own bash tool (`crtr sys
+ *  daemon stop && start`), which inherits that node's FULL env — its identity
+ *  (`CRTR_NODE_ID`/`CRTR_KIND`/…, the `nodeEnv()` shape in `core/runtime/
+ *  nodes.ts`), its front-door recursion-guard flag, and any pi-engine
+ *  resolution seam a prior test/dev session left exported. The daemon is a
+ *  singleton supervisor, never "a node" itself, so none of this belongs in its
+ *  env regardless of whether today's code happens to read it — and at least one
+ *  of these IS actively read: `host.ts`'s broker-engine resolution falls back to
+ *  `envBrokerEngine()`'s raw `CRTR_BROKER_ENGINE` read verbatim (nodeEnv() never
+ *  sets that key, so nothing overrides it per child launch), so a daemon that inherits a
+ *  stale/dev override throws inside `headlessBrokerHost.launch()` on EVERY
+ *  relaunch it ever attempts, for its whole lifetime — the 2026-07-06 diagnosis
+ *  root cause behind 19 nodes killed with "failed to relaunch and is now dead". */
+export const DAEMON_ENV_STRIP_KEYS = [
+    // Node identity (nodeEnv() shape) — meaningless for a process supervising
+    // many nodes rather than being one.
+    'CRTR_NODE_ID',
+    'CRTR_KIND',
+    'CRTR_MODE',
+    'CRTR_LIFECYCLE',
+    'CRTR_NODE_CWD',
+    'CRTR_CONTEXT_DIR',
+    'CRTR_CYCLES',
+    'CRTR_PROFILE_ID',
+    'CRTR_PARENT_NODE_ID',
+    // Recursion-guard flag — only meaningful inside a pi engine process.
+    'CRTR_FRONT_DOOR',
+    // Ambient tmux identity of whatever shell first autostarted the daemon. The
+    // daemon is a headless supervisor with no pane of its own, but `spawnNode`
+    // reads `currentTmux()` for a --root's foreground viewer placement; a stale
+    // inherited $TMUX makes that resolve to an arbitrary "current" pane, so a
+    // front-door root (created through crtrd) opens a SECOND viewer window and
+    // focuses it — stealing focus from the front door's own inline attach in the
+    // user's pane.
+    // Strip them so the daemon is truly paneless and leaves root-viewer placement
+    // to the front door. Explicit `-t <target>` tmux ops (focus/window mgmt) are
+    // unaffected — the tmux CLI reaches the server via its default socket.
+    'TMUX',
+    'TMUX_PANE',
+    // Engine-resolution seams NOT overridden per child launch — the proven and
+    // suspected poison vectors.
+    'CRTR_BROKER_ENGINE',
+    'CRTR_PI_BINARY',
+    // Generic Node.js env poisoning (a stray dev/debug flag from the restarting
+    // shell).
+    'NODE_OPTIONS',
+];
+/** A copy of `process.env` with every `DAEMON_ENV_STRIP_KEYS` entry removed.
+ *  Deliberate global config the user actually wants the daemon to see —
+ *  `CRTR_HOME`, `CRTR_SUBTREE`, `CRTR_LOG`, `CRTR_DEBUG`, etc. — passes through
+ *  untouched; only the node-identity/engine-poisoning surface is stripped. */
+export function sanitizedDaemonEnv() {
+    const env = { ...process.env };
+    for (const key of DAEMON_ENV_STRIP_KEYS)
+        delete env[key];
+    return env;
+}
+// Entry point resolution
+/** Locate the package or generation root from a regular build, the standalone
+ *  attach bundle, or a tsx source checkout. */
+function generationRoot() {
+    for (let current = dirname(fileURLToPath(import.meta.url));; current = dirname(current)) {
+        if (existsSync(join(current, 'bin', 'runtime-generation-manifest.mjs')))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            throw new Error(`cannot locate the crouter generation root from ${import.meta.url}`);
+    }
+}
+/** Resolve crtrd's launch argv through the same selector as `bin/crtrd`. The
+ *  selector may choose an ABI-compatible sibling of `runtime/selected`, but
+ *  never the caller's pinned generation. With no selection, a source checkout
+ *  launches through tsx; every other selection failure remains fatal. */
+async function resolveDaemonLaunch() {
+    const root = generationRoot();
+    const manifestUrl = pathToFileURL(join(root, 'bin', 'runtime-generation-manifest.mjs')).href;
+    const { runtimeHome } = (await import(manifestUrl));
+    try {
+        lstatSync(join(runtimeHome(), 'selected'));
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        const tsxLoader = pathToFileURL(createRequire(import.meta.url).resolve('tsx/esm')).href;
+        // `crtr-src` maps the package's `#` subpath imports to src/*.ts; without it
+        // a source-checkout launch would silently resolve them into a stale dist/.
+        return ['--conditions', 'crtr-src', '--import', tsxLoader, join(root, 'src', 'daemon', 'crtrd-cli.ts')];
+    }
+    const selectorUrl = pathToFileURL(join(root, 'bin', 'runtime-selector.mjs')).href;
+    const { tryResolveRuntime } = (await import(selectorUrl));
+    const result = tryResolveRuntime('daemon');
+    if (!result.ok) {
+        throw new Error(`cannot resolve the selected runtime generation's daemon entry: ${result.error}`);
+    }
+    return [result.runtime.entryPath];
+}
+// Stray-daemon sweep
+/** A crtrd declares its owning canvas in argv, so ownership is an exact match
+ *  on this process's canvas home. Untagged daemons retain their own
+ *  supervision and are never counted or killed here. */
+export function daemonCommandDeclaresCanvasHome(command, home) {
+    return command.includes(` --canvas-home ${home} `) || command.endsWith(` --canvas-home ${home}`);
+}
+/** Every crtrd process on this host that declares ownership of this process's
+ *  canvas home, by pid. The `daemon/crtrd` argv segment distinguishes daemons
+ *  from brokers. `ps` is best-effort: failures return no matches, and the
+ *  current process is always excluded. */
+export function findDaemonPids() {
+    const processes = listProcessTable();
+    if (processes === null)
+        return [];
+    const home = crtrHome();
+    const pids = [];
+    for (const { pid, command } of processes) {
+        if (!command.includes('daemon/crtrd'))
+            continue;
+        if (!daemonCommandDeclaresCanvasHome(command, home))
+            continue; // another install/canvas owns it
+        if (pid !== process.pid)
+            pids.push(pid);
+    }
+    return pids;
+}
+/** SIGTERM (then SIGKILL after a short grace) every crtrd daemon process EXCEPT
+ *  `keepPid`. This is the backstop the pidfile alone cannot provide: a daemon
+ *  that survived a prior stop (ignored SIGTERM, or released its ownership lock
+ *  without exiting) keeps running a supervise loop — reviving brokers and
+ *  contending for canvas state — while never appearing in the pidfile again, so
+ *  `stop`'s single recorded-pid signal can never reach it. Returns the pids it
+ *  reaped. Best-effort throughout: a pid that dies between enumeration and signal
+ *  just no-ops. */
+export function sweepStrayDaemons(keepPid) {
+    const strays = findDaemonPids().filter((pid) => pid !== keepPid);
+    for (const pid of strays) {
+        try {
+            process.kill(pid, 'SIGTERM');
+        }
+        catch { /* already gone */ }
+    }
+    if (strays.length === 0)
+        return strays;
+    // Give SIGTERM handlers a beat, then SIGKILL any that ignored it — a stray
+    // daemon that hung its shutdown is exactly the failure mode this exists for.
+    const deadline = Date.now() + 2_000;
+    while (Date.now() < deadline) {
+        if (!strays.some((pid) => isPidAlive(pid)))
+            break;
+        execFileSync('sleep', ['0.1']);
+    }
+    for (const pid of strays) {
+        if (isPidAlive(pid)) {
+            try {
+                process.kill(pid, 'SIGKILL');
+            }
+            catch { /* already gone */ }
+        }
+    }
+    return strays;
+}
+// daemon launch — low-level spawn/exec
+/** Replace PID 1 with the selected daemon generation. Docker keeps a container
+ *  alive only while PID 1 lives, so a handover there must preserve its pid. */
+export async function execDaemon() {
+    const execve = process.execve;
+    if (execve === undefined) {
+        throw new Error(`this Node.js ${process.version} runtime cannot replace PID 1 with the successor daemon`);
+    }
+    const executable = hostExecPath();
+    const launchArgs = await resolveDaemonLaunch();
+    return execve(executable, [executable, ...launchArgs, '--canvas-home', crtrHome()], sanitizedDaemonEnv());
+}
+// Shutdown stays short even though startup may include corpus migration.
+const DAEMON_SHUTDOWN_WINDOW_MS = 20_000;
+const DAEMON_VERIFY_POLL_MS = 10;
+/** A status/start readiness probe must not hang behind a daemon that accepts a
+ * Unix connection but never answers it. */
+const DAEMON_HEALTH_PROBE_TIMEOUT_MS = 1_000;
+/** Make one `/healthz` observation without client-side recovery. The caller owns the availability window, so this probe cannot extend it. */
+export async function probeDaemonHealth(timeoutMs = DAEMON_HEALTH_PROBE_TIMEOUT_MS) {
+    const probeTimeoutMs = Math.min(timeoutMs, DAEMON_HEALTH_PROBE_TIMEOUT_MS);
+    return localClient({ autostart: false, timeoutMs: probeTimeoutMs }).probeHealthz(probeTimeoutMs);
+}
+export function probeErrorMessage(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (typeof error !== 'object' || error === null)
+        return message;
+    const direct = error.code;
+    const cause = error.cause;
+    const code = typeof direct === 'string' ? direct : cause?.code;
+    return typeof code === 'string' && !message.includes(code) ? `${message}: ${code}` : message;
+}
+/** True only when one mandatory Unix API socket probe answers the existing ready health contract. */
+export async function probeDaemonServing(timeoutMs = DAEMON_HEALTH_PROBE_TIMEOUT_MS) {
+    const health = await probeDaemonHealth(timeoutMs);
+    if (health.startup_blocked !== undefined) {
+        const pid = readPidfile() ?? process.pid;
+        throw new DaemonStartupBlockedError(pid, health.startup_blocked);
+    }
+    if (!health.ok)
+        throw new Error('crtrd health check reported not ready');
+}
+/** True only when one mandatory Unix API socket probe answers `/healthz`.
+ * A pidfile identifies an owner; it is never readiness. */
+export async function isDaemonServing() {
+    try {
+        await probeDaemonServing();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function sleepMs(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+/** The spawned daemon process died before it ever became ready — a startup
+ *  failure, not a progressing migration (a live daemon never raises this).
+ *  `stderrTail` is what that run wrote to crtrd.err, so the CLI can say why. */
+export class DaemonExitedBeforeReadyError extends Error {
+    stderrTail;
+    constructor(message, stderrTail) {
+        super(stderrTail === '' ? message : `${message}\n${stderrTail}`);
+        this.name = 'DaemonExitedBeforeReadyError';
+        this.stderrTail = stderrTail;
+    }
+}
+/** A live daemon has bound its repair socket but cannot serve normal work
+ *  until its corpus migration succeeds. */
+export class DaemonStartupBlockedError extends Error {
+    constructor(pid, message) {
+        super(`daemon ${pid} is running but normal startup is blocked: ${message}`);
+        this.name = 'DaemonStartupBlockedError';
+    }
+}
+/** A preparation request cannot succeed unless the live daemon explicitly reports prepared. */
+export class DaemonNotPreparedError extends Error {
+    constructor(pid, startupPhase) {
+        super(startupPhase === undefined
+            ? `daemon ${pid} is serving but did not report the prepared startup phase`
+            : `daemon ${pid} reported startup phase ${startupPhase}, not prepared`);
+        this.name = 'DaemonNotPreparedError';
+    }
+}
+/** Tiny bounded post-spawn guard: wait for the daemon pidfile and live pid to
+ *  appear before reporting success. This catches the "started:true but not yet
+ *  plausibly alive" race without turning startup into a retry loop.
+ *
+ *  One deadline, owner-first polling. A signal or non-zero child exit fails
+ *  immediately. A clean code-0 exit is treated only as a possible ownership-
+ *  claim loser (never readiness on its own): polling continues on the SAME
+ *  deadline for a different live pidfile owner — the winner may publish its
+ *  pidfile deliberately late — and fails at that deadline if none appears. No
+ *  deadline extension and no retry spawn.
+ *
+ *  Returns null when the spawned pid owns the pidfile; returns a different live
+ *  daemon pid when startup lost the race to an already-running daemon. */
+export async function verifyDaemonStartup(pid, timeoutMs = DAEMON_STARTUP_WINDOW_MS, deps = {}, targetPhase = 'ready') {
+    const read = deps.readPidfile ?? readPidfile;
+    const alive = deps.isPidAlive ?? isPidAlive;
+    const exited = deps.childExited;
+    const serving = deps.isDaemonServing;
+    const probeServing = deps.probeDaemonServing ?? (async (remainingMs) => {
+        if (serving !== undefined) {
+            if (await serving())
+                return;
+            throw new Error('crtrd health check reported not ready');
+        }
+        await probeDaemonServing(remainingMs);
+    });
+    const probeHealth = deps.probeDaemonHealth ?? probeDaemonHealth;
+    const sleep = deps.sleepMs ?? sleepMs;
+    const now = deps.now ?? Date.now;
+    let owner = null;
+    let terminalError = null;
+    await waitForDaemonAvailability({
+        windowMs: timeoutMs,
+        pollIntervalMs: DAEMON_VERIFY_POLL_MS,
+        now,
+        sleep,
+        retry: (error) => error !== terminalError,
+        probe: async (remainingMs) => {
+            const candidate = read();
+            if (candidate === null || !alive(candidate)) {
+                const exitState = exited?.();
+                if (exitState !== null && exitState !== undefined) {
+                    if (exitState.signal !== null)
+                        terminalError = new DaemonExitedBeforeReadyError(`daemon ${pid} exited before becoming ready (by ${exitState.signal})`, deps.childStderrTail?.() ?? '');
+                    else if (exitState.code !== 0)
+                        terminalError = new DaemonExitedBeforeReadyError(`daemon ${pid} exited before becoming ready (with exit code ${exitState.code ?? '?'})`, deps.childStderrTail?.() ?? '');
+                    if (terminalError !== null)
+                        throw terminalError;
+                }
+                throw new Error(`daemon ${pid} has no live pidfile owner`);
+            }
+            if (targetPhase === 'ready') {
+                try {
+                    await probeServing(remainingMs);
+                }
+                catch (error) {
+                    if (error instanceof DaemonStartupBlockedError)
+                        terminalError = error;
+                    throw error;
+                }
+                owner = candidate;
+                return;
+            }
+            const health = await probeHealth(remainingMs);
+            if (health.startup_phase === 'prepared') {
+                owner = candidate;
+                return;
+            }
+            if (health.startup_phase === 'blocked') {
+                terminalError = new DaemonStartupBlockedError(candidate, health.startup_blocked ?? 'on-disk migration is blocked');
+                throw terminalError;
+            }
+            if (health.startup_phase === 'ready') {
+                terminalError = new DaemonNotPreparedError(candidate, health.startup_phase);
+                throw terminalError;
+            }
+            throw new Error(`daemon ${candidate} is ${health.startup_phase ?? 'not reporting a startup phase'}; waiting for prepared`);
+        },
+    });
+    return owner === pid ? null : owner;
+}
+/** Wait until a signaled daemon has exited and relinquished its pidfile. This
+ *  makes a following start safe to claim the singleton rather than racing its
+ *  previous owner. */
+export async function waitForDaemonExit(pid, timeoutMs = DAEMON_SHUTDOWN_WINDOW_MS, deps = {}) {
+    const read = deps.readPidfile ?? readPidfile;
+    const alive = deps.isPidAlive ?? isPidAlive;
+    const sleep = deps.sleepMs ?? sleepMs;
+    const now = deps.now ?? Date.now;
+    const deadline = now() + timeoutMs;
+    while (now() <= deadline) {
+        if (!alive(pid) && read() !== pid)
+            return;
+        await sleep(DAEMON_VERIFY_POLL_MS);
+    }
+    throw new Error(`daemon ${pid} did not exit and release its pidfile within ${timeoutMs}ms`);
+}
+/** How long a SIGKILL'd daemon gets to actually leave the process table before
+ *  `stopDaemonProcess` gives up. A killed process is reaped by the kernel, so
+ *  this only absorbs scheduling latency (or an uninterruptible wait). */
+const DAEMON_KILL_WINDOW_MS = 2_000;
+/** How long a failed-to-start daemon gets to go down before the reap gives up.
+ *  Short on purpose: nothing is waiting on this process any more. */
+const DAEMON_REAP_WINDOW_MS = 5_000;
+/** Stop the RECORDED daemon: SIGTERM, and if it does not exit within the wait
+ *  window, escalate to SIGKILL exactly as `sweepStrayDaemons` does for a stray.
+ *
+ *  The escalation is the point. Without it — SIGTERM, wait, throw on timeout,
+ *  never reaching the stray sweep — the one daemon `stop` is actually aimed at
+ *  would be the only crtrd process exempt from the SIGKILL backstop, and a
+ *  daemon whose shutdown hangs (or outruns the window) becomes permanently
+ *  unstoppable from the CLI: every retry re-sends a SIGTERM it is already
+ *  ignoring, and `start` keeps refusing as "already running".
+ *
+ *  A SIGKILL'd daemon runs no exit handler, so it leaves its pidfile behind
+ *  pointing at a dead pid. That is a stale record, not an owner: `readPidfile`
+ *  callers gate on `isPidAlive`, and the next `start` overwrites it. So this
+ *  waits on process death alone after a kill, never on pidfile release.
+ *
+ *  Returns how the daemon went down, for a truthful report. */
+export async function stopDaemonProcess(pid, timeoutMs = DAEMON_SHUTDOWN_WINDOW_MS, deps = {}) {
+    const alive = deps.isPidAlive ?? isPidAlive;
+    const sleep = deps.sleepMs ?? sleepMs;
+    const now = deps.now ?? Date.now;
+    try {
+        process.kill(pid, 'SIGTERM');
+    }
+    catch { /* already gone */ }
+    try {
+        await waitForDaemonExit(pid, timeoutMs, deps);
+        return 'terminated';
+    }
+    catch {
+        // Ignored or hung SIGTERM — the exact failure the stray sweep already kills for.
+    }
+    try {
+        process.kill(pid, 'SIGKILL');
+    }
+    catch { /* already gone */ }
+    const deadline = now() + DAEMON_KILL_WINDOW_MS;
+    while (now() <= deadline) {
+        if (!alive(pid))
+            return 'killed';
+        await sleep(DAEMON_VERIFY_POLL_MS);
+    }
+    throw new Error(`daemon ${pid} survived both SIGTERM and SIGKILL`);
+}
+/** The last `maxBytes` of a log from byte `start` onward, trimmed; '' when it
+ *  cannot be read. Bounded so a runaway log can never flood an error message. */
+function readLogTailFrom(path, start, maxBytes = 2_048) {
+    let fd;
+    try {
+        fd = openSync(path, 'r');
+        const { size } = fstatSync(fd);
+        const from = Math.max(start, size - maxBytes);
+        const length = size - from;
+        if (length <= 0)
+            return '';
+        const buffer = Buffer.alloc(length);
+        readSync(fd, buffer, 0, length, from);
+        return buffer.toString('utf8').trim();
+    }
+    catch {
+        return '';
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch { /* best-effort */ }
+        }
+    }
+}
+/** Spawn crtrd detached. Returns immediately; the child outlives this process.
+ *
+ *  If the daemon is already running, returns {started:false, existing_pid}.
+ *  If spawning fails (e.g. missing dist — run `npm run build` first), throws. */
+export async function spawnDaemon(opts = {}) {
+    if (process.platform === 'linux' && existsSync('/run/crtr/launcher.sock') && !isPidAlive(readPidfile() ?? -1)) {
+        throw new Error('crtrd is managed by the root launcher; it cannot self-daemonize');
+    }
+    const targetPhase = opts.targetPhase ?? 'ready';
+    const recordedPid = readPidfile();
+    if (recordedPid !== null && isPidAlive(recordedPid)) {
+        try {
+            const health = await probeDaemonHealth();
+            if (targetPhase === 'prepared') {
+                if (health.startup_phase === 'prepared') {
+                    return { started: false, existing_pid: recordedPid, startup_phase: health.startup_phase };
+                }
+                throw new DaemonNotPreparedError(recordedPid, health.startup_phase);
+            }
+            if (health.ok) {
+                return {
+                    started: false,
+                    existing_pid: recordedPid,
+                    ...(health.startup_phase === undefined ? {} : { startup_phase: health.startup_phase }),
+                };
+            }
+            return {
+                started: false,
+                existing_pid: recordedPid,
+                running: true,
+                serving: false,
+                probe_error: health.startup_blocked ?? 'crtrd health check reported not ready',
+                ...(health.startup_phase === undefined ? {} : { startup_phase: health.startup_phase }),
+            };
+        }
+        catch (error) {
+            if (error instanceof DaemonNotPreparedError)
+                throw error;
+            return {
+                started: false,
+                existing_pid: recordedPid,
+                running: true,
+                serving: false,
+                probe_error: probeErrorMessage(error),
+            };
+        }
+    }
+    // Ensure the canvas home directory exists so the daemon can write its pidfile.
+    mkdirSync(crtrHome(), { recursive: true });
+    // Launch from the crouter-branded host binary so the daemon shows "crouter"
+    // in macOS Full Disk Access, not "node" (see branded-host). NOTE: when crtrd
+    // is launchd-owned, the plist's ProgramArguments must point at the branded
+    // binary too — this path only covers a manual `crtr sys daemon start`.
+    const launchArgs = await resolveDaemonLaunch();
+    // Route stdout+stderr to an append-mode file instead of discarding them
+    // (stdio:'ignore'). This fd is RAW RESIDUE only — third-party/runtime
+    // output the daemon doesn't control, plus the narrow set of authorized raw
+    // `[crtrd] …` bootstrap/fatal lines that by construction predate or escape
+    // canonical event emission (the pre-bind losing-claim line and a cleanup-
+    // fatal write in crtrd.ts). Without this fd all of it is discarded for any
+    // manually-started daemon, the common case (only a launchd-owned daemon has a
+    // logging plist). Every other daemon diagnostic — including per-node
+    // supervise/relaunch failures — is a canonical `emitEvent` write, not raw
+    // stderr; this file is not where those live. Mirrors host.ts's broker.log
+    // pattern: one fd, both streams, append so a restart keeps history.
+    const errLogPath = join(crtrHome(), 'crtrd.err');
+    const errFd = openSync(errLogPath, 'a');
+    // crtrd.err is append-only across restarts; remember where THIS run starts so
+    // a failure can quote only what this run wrote.
+    const errLogStart = (() => { try {
+        return fstatSync(errFd).size;
+    }
+    catch {
+        return 0;
+    } })();
+    if (eventSource() === undefined)
+        bindDaemonEventSource();
+    // `--canvas-home` declares this daemon's canvas ownership in argv so
+    // findDaemonPids()/sweepStrayDaemons (above) can match its own daemon
+    // exactly instead of scanning the whole machine. crtrd-cli.ts's argv
+    // parsing only looks for `--tcp`, so this extra pair of tokens is inert
+    // there — it exists purely for `ps` visibility.
+    const child = spawn(hostExecPath(), [...launchArgs, '--canvas-home', crtrHome(), ...(targetPhase === 'prepared' ? ['--prepare'] : [])], {
+        detached: true,
+        stdio: ['ignore', errFd, errFd],
+        env: sanitizedDaemonEnv(),
+    });
+    // The child holds its own dup of the fd; release the parent's copy so the
+    // launching process never leaks it.
+    closeSync(errFd);
+    const pid = child.pid;
+    if (pid === undefined) {
+        throw new Error('daemon spawn did not return a pid');
+    }
+    let exitState = null;
+    child.once('exit', (code, signal) => {
+        exitState = { code, signal };
+    });
+    child.unref();
+    // Reap on failure. verifyDaemonStartup gives up at its deadline but the child
+    // it was watching is still running — and a daemon that failed to become ready
+    // is typically parked deep in startup (blocked on the migration lock, whose
+    // own window is DAEMON_STARTUP_WINDOW_MS), so it lingers long after the
+    // spawner walked away. Leaving it is what let repeated autostarts ACCUMULATE
+    // instead of merely repeating: each attempt added a resident process that
+    // outlived the attempt, and the machine went down under the pile rather than
+    // under any single failure.
+    let existingPid;
+    try {
+        existingPid = await verifyDaemonStartup(pid, DAEMON_STARTUP_WINDOW_MS, {
+            childExited: () => exitState,
+            childStderrTail: () => readLogTailFrom(errLogPath, errLogStart),
+        }, targetPhase);
+    }
+    catch (error) {
+        // Reap ONLY a child that is not doing the work. A child holding the on-disk
+        // migration lock is mid-corpus-rewrite: the reap escalates to SIGKILL, and
+        // killing a migration partway through is far worse than the resident
+        // process the reap exists to avoid. Startup verification giving up is a
+        // statement about our patience, not proof the child is stuck — a large
+        // corpus can legitimately outlast the window, and that daemon should be
+        // allowed to finish and serve.
+        const childOwnsMigrationLock = exclusiveLockOwnerPid(onDiskMigrationLockPath()) === pid;
+        if (exitState === null && !childOwnsMigrationLock && !(error instanceof DaemonStartupBlockedError)) {
+            try {
+                await stopDaemonProcess(pid, DAEMON_REAP_WINDOW_MS);
+            }
+            catch { /* best effort */ }
+        }
+        throw error;
+    }
+    if (existingPid !== null) {
+        return { started: false, existing_pid: existingPid, startup_phase: targetPhase };
+    }
+    return { started: true, pid, startup_phase: targetPhase };
+}
+// ensureDaemon — fire-and-forget front-door helper
+/** Whether autostart is suppressed for this invocation. `--no-autostart` or
+ *  `CRTR_NO_DAEMON_AUTOSTART=1` forces fail-loud on a cold socket (spec §7.1) —
+ *  for environments that manage crtrd externally and want the diagnostic, and
+ *  for test lanes, which point `CRTR_HOME` at a throwaway directory: an
+ *  autostarted daemon there is detached and resident, so it outlives both the
+ *  test process and the deleted temp home with nothing left to stop it.
+ *
+ *  This is the ONE gate. `ensureDaemon` below is the only path that spawns a
+ *  daemon implicitly, so the check belongs here rather than at each caller —
+ *  `cliClient()` reads it too, but the in-process spawn/recycle/promote callers
+ *  reach `ensureDaemon` without going through the CLI client at all. An
+ *  explicit `crtr sys daemon start` calls `spawnDaemon` directly and is
+ *  deliberately unaffected. */
+export function autostartDisabled() {
+    return envNoDaemonAutostart() || process.argv.includes('--no-autostart');
+}
+// Autostart rate limiting. `ensureDaemon` is the one implicit spawn path and is
+// reached on every cold socket — including each redial of a long-lived attach
+// client. Unguarded that is an open loop: a daemon that cannot start is retried
+// forever, by every client, with nothing tracking that the last attempt failed
+// for a reason the next one will hit too.
+const AUTOSTART_BACKOFF_BASE_MS = 5_000;
+const AUTOSTART_BACKOFF_MAX_MS = 60_000;
+let autostartInFlight = false;
+let autostartStartupFailure;
+let autostartFailures = 0;
+let autostartNextAttemptAt = 0;
+function autostartBackoffMs(failures) {
+    return Math.min(AUTOSTART_BACKOFF_BASE_MS * 2 ** (failures - 1), AUTOSTART_BACKOFF_MAX_MS);
+}
+/** Reset in-process spawn backoff after a daemon is observed alive. */
+export function resetDaemonAutostart() {
+    autostartStartupFailure = undefined;
+    autostartFailures = 0;
+    autostartNextAttemptAt = 0;
+}
+/** Why the daemon this process autostarted died before becoming ready, or
+ *  undefined while it is starting, running, or exited cleanly (a clean exit may
+ *  be a lost singleton race, so only a non-zero/signal exit counts). A client
+ *  waiting for that daemon polls this so a startup failure ends the wait now
+ *  rather than at the end of the startup window. */
+export function daemonAutostartStartupFailure() {
+    return autostartStartupFailure;
+}
+/** Start the daemon if it is not already running. No-op if already up, if
+ *  autostart is suppressed for this invocation, while an attempt is in flight,
+ *  or while backing off from a recent failure.
+ *  Silently swallows spawn errors (the canvas still works without the daemon;
+ *  nodes just won't be auto-revived). */
+export function ensureDaemon(deps = {}) {
+    const running = deps.isDaemonRunning ?? isDaemonRunning;
+    const spawn = deps.spawnDaemon ?? spawnDaemon;
+    const now = deps.now ?? Date.now;
+    if (autostartDisabled())
+        return;
+    if (autostartInFlight)
+        return;
+    if (now() < autostartNextAttemptAt)
+        return;
+    if (running()) {
+        resetDaemonAutostart();
+        return;
+    }
+    // A failure belongs to the attempt that produced it: this attempt starts with
+    // none, so a client waiting on it is never ended by the previous child's death.
+    autostartStartupFailure = undefined;
+    autostartInFlight = true;
+    void spawn().then(() => {
+        autostartStartupFailure = undefined;
+        autostartFailures = 0;
+        autostartNextAttemptAt = 0;
+    }, (error) => {
+        if (error instanceof DaemonExitedBeforeReadyError) {
+            autostartStartupFailure = error.message;
+        }
+        // Intentionally silent — a missing dist/daemon/crtrd-cli.js (dev mode,
+        // pre-build) must not break the calling command.
+        autostartFailures += 1;
+        autostartNextAttemptAt = now() + autostartBackoffMs(autostartFailures);
+    }).finally(() => {
+        autostartInFlight = false;
+    });
+}

package/dist/daemon/pidfile.d.ts

@@ -0,0 +1,8 @@
+import { isPidAlive } from '../core/canvas/pid.js';
+export { isPidAlive };
+/** Absolute path to crtrd's pidfile. `CRTR_PIDFILE` overrides for tests. */
+export declare function pidfilePath(): string;
+/** Read the pid stored in the pidfile, or null if absent / malformed. */
+export declare function readPidfile(): number | null;
+/** True when a crtrd process is already running (pidfile exists + pid alive). */
+export declare function isDaemonRunning(): boolean;