@north-light/crouter 0.3.154

package/dist/daemon/fleet.d.ts

@@ -0,0 +1,81 @@
+import { type NodeMeta } from '../core/canvas/index.js';
+import type { FleetEntry, FleetExitStatus, FleetRegistry } from '../core/runtime/fleet.js';
+import type { HostHandle } from '../core/runtime/host.js';
+/** Surface a vehicle that never booted (or exhausted its respawn budget).
+ *
+ *  A pi that dies before its first session_start (so `pi_session_id` was never
+ *  recorded) is invisible to its parent — the spawn returned optimistically.
+ *  When the daemon observes that death it errors LOUDLY up the spine: an
+ *  urgent push so the parent learns the child failed to launch instead of just
+ *  seeing a silent `dead`. */
+export declare function surfaceBootFailure(meta: NodeMeta): Promise<void>;
+/** Event-driven follow-up human-work settlement at daemon-detected node death
+ *  (design-followup-consult-v2.md §B.4 step 4). Re-runs the consult-outbox
+ *  reconcile scan right where the daemon first observes a death, so an `armed`
+ *  row whose fork just died with no final report becomes the ticket's error
+ *  result immediately. A no-op for every crash that isn't a consult/visual
+ *  fork. Best-effort, mirrors the startup call's error handling. */
+export declare function reconcileFollowUpWorkOnCrash(id: string): void;
+/** Whether a dead relaunch should resume the saved session strictly, or retry
+ *  as a fresh cycle instead. A cycling attempt (cycle_pending) that dies
+ *  before session_start must retry AS a cycle — a strict reopen only restores
+ *  the transcript at an idle prompt, it cannot restart the dead engine turn.
+ *  A dirty interrupted BUSY turn also requests a cycle; a broker-certified
+ *  clean abort is handled explicitly by classifyDeadNode before this fallback. */
+export declare function retryResumeMode(meta: Pick<NodeMeta, 'cycle_pending'> | null, interruptedTurn?: boolean): boolean;
+export type DeadNodeAction = 'forget' | 'respawn-fresh' | 'dormant' | 'respawn-cycle' | 'respawn-resume' | 'boot-failure';
+/** The narrow durable state the policy table reads. Structural (a Pick, not
+ *  NodeMeta itself) so tests fabricate table rows directly. */
+export type DeadNodeRow = Pick<NodeMeta, 'status' | 'intent' | 'pi_session_id' | 'cycle_pending' | 'private_fork_phase'>;
+/** One pure function producing the action for a node known-dead. Used at
+ *  exactly two call sites — an exit-policy job and the startup recovery sweep
+ *  (design D-12) — so exit recovery and startup recovery can never diverge.
+ *  Evaluated in table order; `busy` is the on-disk busy marker. A clean-abort
+ *  certificate is written by the broker only after Pi persisted its aborted
+ *  entry; without it, a set busy marker means a dirty mid-turn crash. */
+export declare function classifyDeadNode(row: DeadNodeRow | null, busy: boolean, cleanAbort?: boolean): DeadNodeAction;
+/** An exit with uptime at or above this resets the consecutive-failure
+ *  counter before classification; a shorter-lived exit increments it. */
+export declare const HEALTHY_UPTIME_MS = 60000;
+/** At this many consecutive short-lived exits the respawn loop terminalizes:
+ *  transition('crash') + surfaceBootFailure + doctrine wake, counter cleared. */
+export declare const MAX_RESPAWN_ATTEMPTS = 6;
+/** Backoff before the next respawn given the consecutive-failure count.
+ *  Zero failures → immediate (the sub-second yield respawn D-3 buys); the
+ *  n-th delayed attempt waits min(5s·2^n, 10min). */
+export declare function respawnBackoffMs(consecutiveFailures: number): number;
+export interface DaemonFleetOpts {
+    /** This daemon's epoch id (randomBytes(8).toString('hex'), minted by
+     *  runDaemon after the ownership claim). */
+    epoch: string;
+    /** The serial work lane. Exit-policy jobs and backoff respawns run here,
+     *  strictly one at a time with ticks. */
+    enqueue: (job: () => void | Promise<void>) => void;
+    /** Injectable clock for tests. */
+    now?: () => number;
+}
+export declare class DaemonFleet implements FleetRegistry {
+    #private;
+    constructor(opts: DaemonFleetOpts);
+    epoch(): string;
+    register(nodeId: string, handle: HostHandle): void;
+    has(nodeId: string): boolean;
+    get(nodeId: string): FleetEntry | undefined;
+    size(): number;
+    entries(): Iterable<[string, FleetEntry]>;
+    forget(nodeId: string): void;
+    onChildExit(nodeId: string, status: FleetExitStatus): void;
+    deliverExit(nodeId: string, status: FleetExitStatus): void;
+    /** Startup recovery sweep entry (design flow C step 2 / D-12): classify a
+     *  known-dead row and enact immediately through the SAME table exit events
+     *  use. Returns the action so the caller can capacity-gate launches. */
+    recoverDeadNode(nodeId: string): Promise<DeadNodeAction>;
+    /** A revive refusal before its launch try/catch leaves the row active but
+     *  with no fleet entry. Convert that otherwise-silent strand into the same
+     *  terminal outcome as a boot failure. The fresh read avoids duplicating
+     *  reviveNode's launch-failure crash path. */
+    terminalizeIfStillNonTerminal(nodeId: string, event: string, error: unknown): Promise<boolean>;
+    /** Daemon shutdown: cancel every pending backoff respawn. Live processes
+     *  are torn down by the daemon's fleet-teardown stage, not here. */
+    dispose(): void;
+}

package/dist/daemon/fleet.js

@@ -0,0 +1,405 @@
+// src/daemon/fleet.ts — the daemon's broker fleet: the ChildProcess-handle
+// registry (the ONE normal liveness authority), the exit-policy classifier
+// (invariant-5 policy table), and the event-driven respawn throttle.
+//
+// Constructed by runDaemon with the serial work lane's `enqueue` and this
+// daemon's epoch id, then injected into core via `bindFleet` BEFORE the API
+// server or any tick starts. Exit events never run policy inline on the Node
+// event callback — they enqueue a job on the serial lane, so policy never
+// interleaves with a tick's row reads (design D-3).
+//
+// Row state (status/intent/busy marker/session identity), never exit codes,
+// is the policy input (design D-4): the stophook writes the exit's explanation
+// before every deliberate exit, and that durable state is robust to every kill
+// path. Codes/signals are logged for diagnostics only. The single timing
+// input is uptime, used only by the throttle.
+import { getNode, subscribersOf, reconcileFollowUpWork, reconcileVisualWork } from '../core/canvas/index.js';
+import { fullName } from '../core/canvas/labels.js';
+import { isSafeNodeId } from '../core/canvas/paths.js';
+import { transition } from '../core/runtime/lifecycle.js';
+import { fanDoctrineWake } from '../core/runtime/close.js';
+import { hasCleanAbort, isBusy } from '../core/runtime/busy.js';
+import { reviveNode } from '../core/runtime/revive.js';
+import { pushUrgent } from '../core/feed/feed.js';
+import { emitEvent } from '../core/events/emit.js';
+// ---------------------------------------------------------------------------
+// Shared crash helpers (moved from crtrd.ts — the fleet's policy paths are now
+// their primary consumers; crtrd imports them back for its surviving passes).
+// ---------------------------------------------------------------------------
+/** Surface a vehicle that never booted (or exhausted its respawn budget).
+ *
+ *  A pi that dies before its first session_start (so `pi_session_id` was never
+ *  recorded) is invisible to its parent — the spawn returned optimistically.
+ *  When the daemon observes that death it errors LOUDLY up the spine: an
+ *  urgent push so the parent learns the child failed to launch instead of just
+ *  seeing a silent `dead`. */
+export async function surfaceBootFailure(meta) {
+    const body = `⚠ Spawn failed — \`${meta.name}\` (${meta.kind}) never started.\n\n` +
+        `Its pi vehicle exited before the session came up (no pi_session_id was ever ` +
+        `recorded), so the node produced no output. This is almost always a transient ` +
+        `launch failure — e.g. resource pressure when several nodes boot at once — not ` +
+        `a fault in the task itself.\n\n` +
+        `If the work still needs doing, re-spawn it; if spawns keep dying, spawn fewer at a time.`;
+    await pushUrgent(meta.node_id, body, { from: meta.node_id });
+}
+/** Surface a recovery refusal that happened before a broker could launch. */
+async function surfaceRecoveryFailure(meta, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const body = `⚠ Recovery failed — \`${meta.name}\` (${meta.kind}) could not be relaunched.\n\n` +
+        `The daemon refused this recovery before starting a broker: ${message}\n\n` +
+        `The node is now dead. Fix the recorded launch configuration, then revive it if the work still needs doing.`;
+    await pushUrgent(meta.node_id, body, { from: meta.node_id });
+}
+/** Event-driven follow-up human-work settlement at daemon-detected node death
+ *  (design-followup-consult-v2.md §B.4 step 4). Re-runs the consult-outbox
+ *  reconcile scan right where the daemon first observes a death, so an `armed`
+ *  row whose fork just died with no final report becomes the ticket's error
+ *  result immediately. A no-op for every crash that isn't a consult/visual
+ *  fork. Best-effort, mirrors the startup call's error handling. */
+export function reconcileFollowUpWorkOnCrash(id) {
+    try {
+        reconcileFollowUpWork();
+        reconcileVisualWork();
+    }
+    catch (err) {
+        emitEvent({
+            level: 'error',
+            event: 'consult.outbox.reconcile_failed',
+            ...(isSafeNodeId(id) ? { node_id: id } : {}),
+            error: err,
+            fields: {
+                phase: 'crash',
+                ...(isSafeNodeId(id) ? {} : { affected_node_id: id }),
+            },
+        });
+    }
+}
+/** Whether a dead relaunch should resume the saved session strictly, or retry
+ *  as a fresh cycle instead. A cycling attempt (cycle_pending) that dies
+ *  before session_start must retry AS a cycle — a strict reopen only restores
+ *  the transcript at an idle prompt, it cannot restart the dead engine turn.
+ *  A dirty interrupted BUSY turn also requests a cycle; a broker-certified
+ *  clean abort is handled explicitly by classifyDeadNode before this fallback. */
+export function retryResumeMode(meta, interruptedTurn = false) {
+    return meta?.cycle_pending !== true && !interruptedTurn;
+}
+/** One pure function producing the action for a node known-dead. Used at
+ *  exactly two call sites — an exit-policy job and the startup recovery sweep
+ *  (design D-12) — so exit recovery and startup recovery can never diverge.
+ *  Evaluated in table order; `busy` is the on-disk busy marker. A clean-abort
+ *  certificate is written by the broker only after Pi persisted its aborted
+ *  entry; without it, a set busy marker means a dirty mid-turn crash. */
+export function classifyDeadNode(row, busy, cleanAbort = false) {
+    if (row === null)
+        return 'forget'; // row 1: row deleted
+    if (row.status === 'done' || row.status === 'canceled' || row.status === 'dead')
+        return 'forget'; // row 2
+    if (row.intent === 'refresh')
+        return 'respawn-fresh'; // row 3
+    if (row.intent === 'idle-release')
+        return 'dormant'; // row 4
+    if (cleanAbort && row.pi_session_id != null)
+        return 'respawn-resume'; // row 5: broker-certified interrupted turn
+    if (busy)
+        return 'respawn-cycle'; // row 6: dirty interrupted turn
+    if (row.pi_session_id != null)
+        return retryResumeMode(row, false) ? 'respawn-resume' : 'respawn-cycle'; // row 7
+    if (row.private_fork_phase === 'fork_pending')
+        return 'respawn-fresh'; // row 8: bounded fork-birth retry
+    return 'boot-failure'; // row 9
+}
+// ---------------------------------------------------------------------------
+// Respawn throttle (replaces the stranded-relaunch counters, event-driven)
+// ---------------------------------------------------------------------------
+/** An exit with uptime at or above this resets the consecutive-failure
+ *  counter before classification; a shorter-lived exit increments it. */
+export const HEALTHY_UPTIME_MS = 60_000;
+/** At this many consecutive short-lived exits the respawn loop terminalizes:
+ *  transition('crash') + surfaceBootFailure + doctrine wake, counter cleared. */
+export const MAX_RESPAWN_ATTEMPTS = 6;
+const RESPAWN_BACKOFF_BASE_MS = 5_000;
+const RESPAWN_BACKOFF_MAX_MS = 10 * 60_000;
+/** Backoff before the next respawn given the consecutive-failure count.
+ *  Zero failures → immediate (the sub-second yield respawn D-3 buys); the
+ *  n-th delayed attempt waits min(5s·2^n, 10min). */
+export function respawnBackoffMs(consecutiveFailures) {
+    if (consecutiveFailures <= 0)
+        return 0;
+    return Math.min(RESPAWN_BACKOFF_BASE_MS * 2 ** (consecutiveFailures - 1), RESPAWN_BACKOFF_MAX_MS);
+}
+export class DaemonFleet {
+    #epoch;
+    #enqueue;
+    #now;
+    #map = new Map();
+    #throttle = new Map();
+    constructor(opts) {
+        this.#epoch = opts.epoch;
+        this.#enqueue = opts.enqueue;
+        this.#now = opts.now ?? Date.now;
+    }
+    epoch() {
+        return this.#epoch;
+    }
+    register(nodeId, handle) {
+        if (this.#map.has(nodeId)) {
+            throw new Error(`fleet: ${nodeId} already has a live broker entry — refusing a second launch (programming error)`);
+        }
+        if (handle.pid === null) {
+            throw new Error(`fleet: refusing to register ${nodeId} with no pid`);
+        }
+        // A live registration supersedes any scheduled backoff respawn: the node
+        // is alive again (a manual revive won the race), so the pending respawn
+        // must not fire a second launch.
+        const throttle = this.#throttle.get(nodeId);
+        if (throttle?.timer !== undefined) {
+            clearTimeout(throttle.timer);
+            throttle.timer = undefined;
+        }
+        this.#map.set(nodeId, {
+            pid: handle.pid,
+            launchedAt: this.#now(),
+            handle,
+            consecutiveFailures: throttle?.failures ?? 0,
+        });
+    }
+    has(nodeId) {
+        return this.#map.has(nodeId);
+    }
+    get(nodeId) {
+        return this.#map.get(nodeId);
+    }
+    size() {
+        return this.#map.size;
+    }
+    entries() {
+        return this.#map.entries();
+    }
+    forget(nodeId) {
+        this.#map.delete(nodeId);
+        this.#clearThrottle(nodeId);
+    }
+    onChildExit(nodeId, status) {
+        // Remove the entry BEFORE enqueuing the policy job: the slot is freed at
+        // exit, which is what makes exit-driven 1:1 respawns cap-exempt (D-7).
+        const entry = this.#map.get(nodeId);
+        this.#map.delete(nodeId);
+        const launchedAt = entry?.launchedAt ?? null;
+        this.#enqueue(() => this.#runExitPolicy(nodeId, status, launchedAt));
+    }
+    deliverExit(nodeId, status) {
+        this.onChildExit(nodeId, status);
+    }
+    /** Startup recovery sweep entry (design flow C step 2 / D-12): classify a
+     *  known-dead row and enact immediately through the SAME table exit events
+     *  use. Returns the action so the caller can capacity-gate launches. */
+    async recoverDeadNode(nodeId) {
+        return this.#applyPolicy(nodeId, 'sweep');
+    }
+    /** A revive refusal before its launch try/catch leaves the row active but
+     *  with no fleet entry. Convert that otherwise-silent strand into the same
+     *  terminal outcome as a boot failure. The fresh read avoids duplicating
+     *  reviveNode's launch-failure crash path. */
+    async terminalizeIfStillNonTerminal(nodeId, event, error) {
+        const meta = getNode(nodeId);
+        if (meta === null || meta.status === 'done' || meta.status === 'canceled' || meta.status === 'dead')
+            return false;
+        await this.#terminalize(nodeId, meta, {
+            event,
+            wake: `Child crashed — ${fullName(meta)} (${nodeId}) could not be relaunched and is now dead. ` +
+                `It stays dead until you revive it — \`crtr node lifecycle revive ${nodeId}\`.`,
+            surface: () => surfaceRecoveryFailure(meta, error),
+        });
+        return true;
+    }
+    /** Daemon shutdown: cancel every pending backoff respawn. Live processes
+     *  are torn down by the daemon's fleet-teardown stage, not here. */
+    dispose() {
+        for (const state of this.#throttle.values()) {
+            if (state.timer !== undefined) {
+                clearTimeout(state.timer);
+                state.timer = undefined;
+            }
+        }
+    }
+    #clearThrottle(nodeId) {
+        const state = this.#throttle.get(nodeId);
+        if (state?.timer !== undefined)
+            clearTimeout(state.timer);
+        this.#throttle.delete(nodeId);
+    }
+    async #runExitPolicy(nodeId, status, launchedAt) {
+        const uptimeMs = launchedAt === null ? null : Math.max(0, this.#now() - launchedAt);
+        // A newer launch may own this node by the time the lane reaches this job
+        // (an API revive raced the exit event onto the lane). The exit belonged to
+        // the OLD process; the node is alive — nothing to recover, but preserve the
+        // observation without charging the fresh launch's throttle budget.
+        if (this.#map.has(nodeId)) {
+            this.#emitExitObserved(nodeId, status, uptimeMs, this.#throttle.get(nodeId)?.failures ?? 0);
+            return;
+        }
+        const state = this.#throttle.get(nodeId) ?? { failures: 0 };
+        if (state.timer !== undefined) {
+            clearTimeout(state.timer);
+            state.timer = undefined;
+        }
+        // Healthy uptime resets the counter BEFORE classification; a short-lived
+        // exit (or a synthetic exit with no known launch time) increments it.
+        if (uptimeMs !== null && uptimeMs >= HEALTHY_UPTIME_MS) {
+            state.failures = 0;
+            this.#throttle.delete(nodeId);
+        }
+        else {
+            state.failures += 1;
+            this.#throttle.set(nodeId, state);
+        }
+        this.#emitExitObserved(nodeId, status, uptimeMs, state.failures);
+        await this.#applyPolicy(nodeId, 'exit');
+    }
+    #emitExitObserved(nodeId, status, uptimeMs, consecutiveFailures) {
+        emitEvent({
+            level: 'info',
+            event: 'broker.exit.observed',
+            ...(isSafeNodeId(nodeId) ? { node_id: nodeId } : {}),
+            fields: {
+                ...(isSafeNodeId(nodeId) ? {} : { affected_node_id: nodeId }),
+                code: status.code,
+                signal: status.signal,
+                uptime_ms: uptimeMs,
+                consecutive_failures: consecutiveFailures,
+            },
+        });
+    }
+    async #applyPolicy(nodeId, origin) {
+        const meta = getNode(nodeId);
+        const cleanAbort = hasCleanAbort(nodeId);
+        const action = classifyDeadNode(meta, isBusy(nodeId), cleanAbort);
+        switch (action) {
+            case 'forget':
+                // Fanouts for terminal exits already happened at the transition site.
+                this.#clearThrottle(nodeId);
+                break;
+            case 'dormant':
+                // Chosen dormancy is not a failure — the counter does not survive it.
+                // The pathological wake→fault→release→wake loop is bounded by the
+                // tick's pass-2 cursor-keyed retry cap (D-11), not this throttle.
+                this.#clearThrottle(nodeId);
+                break;
+            case 'boot-failure':
+                await this.#terminalize(nodeId, meta, {
+                    event: 'broker.boot.failed',
+                    wake: `Child crashed — ${fullName(meta)} (${nodeId}) exited before its session ever came up and is now dead. ` +
+                        `It stays dead until you revive it — \`crtr node lifecycle revive ${nodeId}\`.`,
+                });
+                break;
+            case 'respawn-fresh':
+            case 'respawn-cycle':
+            case 'respawn-resume':
+                await this.#respawn(nodeId, meta, action, origin, cleanAbort);
+                break;
+        }
+        return action;
+    }
+    async #respawn(nodeId, meta, action, origin, cleanAbort) {
+        const state = this.#throttle.get(nodeId) ?? { failures: 0 };
+        if (state.failures >= MAX_RESPAWN_ATTEMPTS) {
+            await this.#terminalize(nodeId, meta, {
+                event: 'broker.respawn.exhausted',
+                wake: `Child crashed — ${fullName(meta)} (${nodeId}) kept dying shortly after launch (${state.failures} consecutive ` +
+                    `short-lived exits) and is now dead. It stays dead until you revive it — \`crtr node lifecycle revive ${nodeId}\`.`,
+            });
+            return;
+        }
+        // Only a fresh exit consults the backoff: a matured timer and the startup
+        // sweep enact immediately (the timer already WAS the backoff, and startup
+        // counters are empty for a fresh epoch).
+        if (origin === 'exit') {
+            const delay = respawnBackoffMs(state.failures);
+            if (delay > 0) {
+                state.timer = setTimeout(() => {
+                    state.timer = undefined;
+                    // A fresh policy job re-reads the row, so a node closed/canceled
+                    // during the backoff lands in table row 2 and the respawn evaporates.
+                    this.#enqueue(async () => { await this.#applyPolicy(nodeId, 'timer'); });
+                }, delay);
+                this.#throttle.set(nodeId, state);
+                emitEvent({
+                    level: 'info',
+                    event: 'broker.respawn.deferred',
+                    ...(isSafeNodeId(nodeId) ? { node_id: nodeId } : {}),
+                    fields: {
+                        ...(isSafeNodeId(nodeId) ? {} : { affected_node_id: nodeId }),
+                        action,
+                        backoff_ms: delay,
+                        consecutive_failures: state.failures,
+                    },
+                });
+                return;
+            }
+        }
+        emitEvent({
+            level: 'info',
+            event: 'broker.respawn.started',
+            ...(isSafeNodeId(nodeId) ? { node_id: nodeId } : {}),
+            fields: {
+                ...(isSafeNodeId(nodeId) ? {} : { affected_node_id: nodeId }),
+                action,
+                origin,
+                consecutive_failures: state.failures,
+            },
+        });
+        try {
+            reviveNode(nodeId, {
+                resume: action === 'respawn-resume',
+                wakeReason: cleanAbort ? 'runtime-restart-abort' : undefined,
+            });
+        }
+        catch (err) {
+            emitEvent({
+                level: 'error',
+                event: 'broker.respawn.failed',
+                ...(isSafeNodeId(nodeId) ? { node_id: nodeId } : {}),
+                error: err,
+                fields: {
+                    ...(isSafeNodeId(nodeId) ? {} : { affected_node_id: nodeId }),
+                    action,
+                    origin,
+                },
+            });
+            // Launch failures terminalize inside reviveNode, but its preflight
+            // refusals (for example cwd_missing) happen before that catch. Re-read
+            // before terminalizing so the launch path's settled terminal row wins.
+            await this.terminalizeIfStillNonTerminal(nodeId, 'broker.respawn.refused', err);
+        }
+    }
+    /** Terminal outcome shared by table row 8 and throttle exhaustion:
+     *  transition('crash') + consult-outbox reconcile + surfaceBootFailure +
+     *  doctrine wake, counter cleared. */
+    async #terminalize(nodeId, meta, opts) {
+        this.#clearThrottle(nodeId);
+        emitEvent({
+            level: 'error',
+            event: opts.event,
+            ...(isSafeNodeId(nodeId) ? { node_id: nodeId } : { fields: { affected_node_id: nodeId } }),
+        });
+        transition(nodeId, 'crash');
+        reconcileFollowUpWorkOnCrash(nodeId);
+        try {
+            await (opts.surface ?? (() => surfaceBootFailure(meta)))();
+        }
+        catch (err) {
+            emitEvent({
+                level: 'error',
+                event: 'broker.boot_failure_surface.failed',
+                ...(isSafeNodeId(nodeId) ? { node_id: nodeId } : { fields: { affected_node_id: nodeId } }),
+                error: err,
+            });
+        }
+        try {
+            fanDoctrineWake(nodeId, subscribersOf(nodeId), opts.wake, { reason: 'child-crashed', child: nodeId });
+        }
+        catch {
+            /* best-effort, mirrors every other fan-out in the daemon */
+        }
+    }
+}

package/dist/daemon/manage.d.ts

@@ -0,0 +1,103 @@
+/** 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
+ *  `process.env['CRTR_BROKER_ENGINE']` 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 declare const DAEMON_ENV_STRIP_KEYS: readonly string[];
+/** 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 declare function sanitizedDaemonEnv(): NodeJS.ProcessEnv;
+/** 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 declare function daemonCommandDeclaresCanvasHome(command: string, home: string): boolean;
+/** 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 declare function findDaemonPids(): number[];
+/** 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 declare function sweepStrayDaemons(keepPid: number | null): number[];
+export interface SpawnDaemonResult {
+    /** True when a new daemon process was spawned. */
+    started: boolean;
+    /** PID of the newly spawned process, if started. */
+    pid?: number;
+    /** PID of the already-running daemon, if it was already up. */
+    existing_pid?: number;
+}
+export declare const DAEMON_VERIFY_WINDOW_MS = 20000;
+export interface DaemonWaitDeps {
+    readPidfile?: () => number | null;
+    isPidAlive?: (pid: number) => boolean;
+    sleepMs?: (ms: number) => Promise<void> | void;
+    now?: () => number;
+}
+export interface DaemonStartupDeps extends DaemonWaitDeps {
+    childExited?: () => {
+        code: number | null;
+        signal: NodeJS.Signals | null;
+    } | null;
+}
+/** 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 declare function verifyDaemonStartup(pid: number, timeoutMs?: number, deps?: DaemonStartupDeps): Promise<number | null>;
+/** 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 declare function waitForDaemonExit(pid: number, timeoutMs?: number, deps?: DaemonWaitDeps): Promise<void>;
+/** 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. `stop` used to send SIGTERM, wait, and throw on
+ *  timeout — before ever reaching the stray sweep — so the one daemon `stop` is
+ *  actually aimed at was the only crtrd process exempt from the SIGKILL backstop.
+ *  A daemon whose shutdown hung (or outran the window) then became permanently
+ *  unstoppable from the CLI: every retry re-sent a SIGTERM it was already
+ *  ignoring, and `start` kept 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 declare function stopDaemonProcess(pid: number, timeoutMs?: number, deps?: DaemonWaitDeps): Promise<'terminated' | 'killed'>;
+/** 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 declare function spawnDaemon(): Promise<SpawnDaemonResult>;
+/** Start the daemon if it is not already running. No-op if already up.
+ *  Silently swallows spawn errors (the canvas still works without the daemon;
+ *  nodes just won't be auto-revived). */
+export declare function ensureDaemon(): void;