@crouton-kit/crouter 0.3.32 → 0.3.33

package/dist/core/view/transport-local.js

@@ -8,6 +8,7 @@
 // source's parse() job.
 import { execFile } from 'node:child_process';
 import { readFile } from 'node:fs/promises';
+import { openLocalStream } from './stream-local.js';
 const MAX_BUFFER = 10 * 1024 * 1024;
 export function createLocalTransport(opts = {}) {
     const baseCwd = opts.cwd ?? process.cwd();
@@ -19,6 +20,9 @@ export function createLocalTransport(opts = {}) {
                 case 'http': return sendHttp(req);
             }
         },
+        open(req, handlers) {
+            return openLocalStream(req, handlers);
+        },
     };
 }
 function sendExec(req, baseCwd) {

package/dist/core/view/transport.d.ts

@@ -1,4 +1,10 @@
-import type { SourceRequest, RawResponse } from './contract.js';
+import type { SourceRequest, RawResponse, StreamRequest, StreamChannel, SourceError } from './contract.js';
+export interface StreamHandlers {
+    onFrame(frame: unknown): void;
+    onClose(reason: string): void;
+    onError(err: SourceError): void;
+}
 export interface Transport {
     send(req: SourceRequest): Promise<RawResponse>;
+    open(req: StreamRequest, handlers: StreamHandlers): StreamChannel;
 }

package/dist/daemon/crtrd.d.ts

@@ -1,4 +1,6 @@
 import { type NodeRow } from '../core/canvas/index.js';
+import { FAULT_QUIET_MS } from '../core/runtime/fault.js';
+export { FAULT_QUIET_MS };
 import { isPidAlive } from '../core/canvas/pid.js';
 export declare const YIELD_STALL_GRACE_MS: number;
 /** Refresh-stall decision (§H refresh-authority; audit 2026-06-09, Bug 1 — node
@@ -17,25 +19,6 @@ export declare const YIELD_STALL_GRACE_MS: number;
  *  after running `node yield` mid-turn, and a working engine must never be
  *  killed), and the state has persisted past YIELD_STALL_GRACE_MS. */
 export declare function yieldStallVerdict(piPidAlive: boolean | null, intent: NodeRow['intent'], busy: boolean, stalledFor: number | null): 'leave' | 'pending' | 'kill';
-export declare const ERROR_STALL_QUIET_MS: number;
-/** The §I wedge signature, from a session-jsonl tail: the LAST assistant
- *  message stopped with 'error' (retry budget exhausted — pi appends the error
- *  turn and parks). Returns its errorMessage for the daemon log (the "why it
- *  wedged" trace), or null when the last assistant turn ended any other way —
- *  'stop'/'length' is a healthy park, 'aborted' is a human Esc, and trailing
- *  non-assistant lines (toolResults, an injected user message) are walked past.
- *  The first line of a mid-file tail cut fails JSON.parse and is skipped. */
-export declare function trailingEngineError(tail: string | null): string | null;
-/** Error-stall decision (§I; gh issue #4 — node mqaeqzdu-0746b3b7, a 9h zombie
- *  after an Anthropic outage). Pure, mirroring yieldStallVerdict; the kill side
- *  effects live in handleErrorStall.
- *
- *  'kill' ONLY when ALL of: engine alive, NO pending intent (refresh is §H's
- *  domain; idle-release chose dormancy), the turn is over (busy absent — a node
- *  wedged mid-bash must be recovered by killing the subprocess, never the node),
- *  the session file has been quiet past ERROR_STALL_QUIET_MS, and its last
- *  assistant message stopped with 'error'. */
-export declare function errorStallVerdict(piPidAlive: boolean | null, intent: NodeRow['intent'], busy: boolean, quietForMs: number | null, trailingError: boolean): 'leave' | 'kill';
 export type LivenessVerdict = 'leave' | 'pending' | 'revive';
 /** Decide what to do with a node whose engine pid is DEAD, from how long it's
  *  been dead. Pure — the time/revive side effects live in handleNodeLiveness;
@@ -50,6 +33,7 @@ export declare function readPidfile(): number | null;
 export { isPidAlive };
 /** True when a crtrd process is already running (pidfile exists + pid alive). */
 export declare function isDaemonRunning(): boolean;
+/** Supervision tick over the daemon's current live set. */
 export declare function superviseTick(now?: number): Promise<void>;
 export interface DaemonOpts {
     /** Milliseconds between supervision polls. Default 2000. */

package/dist/daemon/crtrd.js

@@ -10,8 +10,8 @@
 // reaps a node on pane/window state. All node liveness routes through
 // handleNodeLiveness:
 //   • Poll every intervalMs (default 2000ms).
-//   • pid alive → leave; but enforce a stuck refresh-yield (§H) and a
-//     wedged-engine error-stall (§I, see below).
+//   • pid alive → leave; but enforce a stuck refresh-yield and active-fault
+//     recovery when a parked broker is due.
 //   • pid null + pi_session_id set → relaunch in flight; leave.
 //   • pid null + pi_session_id null → after a boot grace, crash + surface boot
 //     failure (the broker exited before session_start).
@@ -28,30 +28,39 @@
 // grace, it force-kills the engine itself (handleYieldStall) so the dead-pid
 // refresh path then revives it fresh.
 //
-// §I error-stall: an engine whose turn ends with stopReason 'error' (e.g. a
-// provider outage exhausted the SDK retry budget) is left PARKED by the
-// stophook ("stay alive for re-steering") — but a headless node has no human to
-// re-steer it, so the broker stays alive, status stays 'active', and the pid-only
-// liveness check reads it healthy FOREVER (gh issue #4: a 9h zombie). The daemon
-// is the authority here too: when a live, not-busy node with no pending intent
-// has a session file that is QUIET past a grace AND whose last assistant message
-// stopped with 'error', it kills the engine (handleErrorStall) so the ordinary
-// dead-pid crash path grace-revives RESUME on the saved session — the exact
-// manual recovery (kill broker + canvas revive) that fixes these by hand.
+// An engine whose turn ends with stopReason 'error' (e.g. a provider outage
+// exhausted the SDK retry budget) is left parked by the stophook ("stay alive
+// for re-steering") — but a headless node has no human to re-steer it, so the
+// broker stays alive, status stays 'active', and the pid-only liveness check
+// reads it healthy forever. The daemon is the authority here too: when a live,
+// not-busy node with no pending intent has a session file that is quiet past
+// the recovery window and whose last assistant message stops with 'error', the
+// daemon keeps the live broker parked and retries it via the inbox-based
+// fault-recovery pass so the ordinary dead-pid crash path never needs an
+// out-of-band launch.
+// dead-pid crash path grace-revives RESUME on the saved session — the manual
+// recovery (kill broker + canvas revive) that fixes these by hand.
 //
 // Single-instance guarantee
-//   A PID file at crtrHome()/crtrd.pid prevents double-runs. On start, if the
-//   file exists and the recorded pid is alive, we refuse to start (exit 0).
-//   On stop (SIGINT/SIGTERM/exit) we remove the file.
-import { writeFileSync, readFileSync, rmSync, existsSync, mkdirSync, statSync, openSync, readSync, closeSync, } from 'node:fs';
-import { join } from 'node:path';
+//   A PID file prevents double-runs. On start, if the file exists and the
+//   recorded pid is alive, we refuse to start (exit 0). Hearth guests set
+//   CRTR_PIDFILE to keep this process-local on recreate; otherwise it defaults
+//   to crtrHome()/crtrd.pid. On stop (SIGINT/SIGTERM/exit) we remove the file.
+import { writeFileSync, readFileSync, rmSync, existsSync, mkdirSync, statSync, } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
 import { crtrHome, nodeDir, jobDir } from '../core/canvas/paths.js';
 import { listNodes, getRow, getNode, dueWakes, consumeWake, advanceWake, listFocuses, closeFocusRow, } from '../core/canvas/index.js';
 import { transition } from '../core/runtime/lifecycle.js';
 import { isBusy } from '../core/runtime/busy.js';
+import { FAULT_QUIET_MS } from '../core/runtime/fault.js';
+import { logger } from '../core/log.js';
+export { FAULT_QUIET_MS };
 import { isPidAlive } from '../core/canvas/pid.js';
 import { listLivePanes, tearDownNode } from '../core/runtime/placement.js';
 import { reviveNode } from '../core/runtime/revive.js';
+import { isBrokerLive } from '../core/runtime/model-swap.js';
+import { reloadAuthLive } from '../core/runtime/auth-reload.js';
 import { spawnChild } from '../core/runtime/spawn.js';
 import { wakeOriginFrom } from '../core/runtime/bearings.js';
 import { pushUrgent } from '../core/feed/feed.js';
@@ -78,6 +87,7 @@ async function surfaceBootFailure(meta) {
     await pushUrgent(meta.node_id, body, { from: meta.node_id });
 }
 const DEFAULT_INTERVAL_MS = 2000;
+const log = logger('crtrd');
 // How long a node's broker pid may be observed dead before the daemon revives
 // it. MUST exceed worst-case broker boot time: a refresh / crash-revive
 // transiently shows a dead OLD pid for the gap between the old broker exiting
@@ -184,151 +194,77 @@ function handleYieldStall(row, pid, now) {
         }
     }
 }
-// §I error-stall grace: how long a node's session .jsonl must have been QUIET
-// (no append — mtime is the clock, so it survives daemon restarts) before a
-// trailing-error engine is declared wedged and killed. Generous enough that an
-// in-flight recovery (the human re-steering, a parent's message waking a new
-// turn via the live inbox-watcher — both of which append and reset the clock)
-// always wins, while a true zombie recovers in minutes instead of never.
-export const ERROR_STALL_QUIET_MS = 5 * 60_000;
-// Per-node SIGTERM timestamps for §I kill escalation, mirroring yieldTermAt.
-const errorTermAt = new Map();
-// Memoized tail inspection per node, keyed on the session file's mtime so the
-// (rare) 64KB tail read happens once per file change, not once per 2s tick.
-const errorTailMemo = new Map();
-const TAIL_BYTES = 64 * 1024;
-/** Read the last TAIL_BYTES of a file. null on any failure (absent file reads
- *  as "nothing to inspect", never as evidence of a wedge). */
-function readTail(path) {
-    try {
-        const size = statSync(path).size;
-        const len = Math.min(TAIL_BYTES, size);
-        if (len === 0)
-            return null;
-        const fd = openSync(path, 'r');
-        try {
-            const buf = Buffer.alloc(len);
-            readSync(fd, buf, 0, len, size - len);
-            return buf.toString('utf8');
-        }
-        finally {
-            closeSync(fd);
-        }
-    }
-    catch {
-        return null;
-    }
-}
-/** The §I wedge signature, from a session-jsonl tail: the LAST assistant
- *  message stopped with 'error' (retry budget exhausted — pi appends the error
- *  turn and parks). Returns its errorMessage for the daemon log (the "why it
- *  wedged" trace), or null when the last assistant turn ended any other way —
- *  'stop'/'length' is a healthy park, 'aborted' is a human Esc, and trailing
- *  non-assistant lines (toolResults, an injected user message) are walked past.
- *  The first line of a mid-file tail cut fails JSON.parse and is skipped. */
-export function trailingEngineError(tail) {
-    if (tail === null)
-        return null;
-    const lines = tail.split('\n');
-    for (let i = lines.length - 1; i >= 0; i--) {
-        const line = lines[i].trim();
-        if (line === '')
-            continue;
-        let msg;
-        try {
-            msg = JSON.parse(line)?.message;
-        }
-        catch {
-            continue; // a cut fragment (tail boundary) or non-JSON line
-        }
-        if (msg?.role !== 'assistant')
-            continue;
-        if (msg.stopReason !== 'error')
-            return null;
-        return typeof msg.errorMessage === 'string' && msg.errorMessage !== ''
-            ? msg.errorMessage
-            : 'engine error (no errorMessage recorded)';
-    }
-    return null;
+// ---------------------------------------------------------------------------
+// Auth-reload fan (one /login → every live broker follows)
+// ---------------------------------------------------------------------------
+/** Path of the shared pi credentials file every broker reads. VENDORED from pi
+ *  `config.getAuthPath()` (= `<agentDir>/auth.json`) the same way spawn.ts
+ *  vendors the sessions root: a ROOT import of pi's `getAgentDir` would eager-
+ *  load the heavy pi SDK index, so we mirror its resolution — `PI_CODING_AGENT_DIR`
+ *  env, else `~/.pi/agent`. Re-sync on a pi SDK bump that moves auth.json. */
+function piAuthPath() {
+    const env = process.env['PI_CODING_AGENT_DIR'];
+    const agentDir = env !== undefined && env !== '' ? env : join(homedir(), '.pi', 'agent');
+    return join(agentDir, 'auth.json');
 }
-/** Error-stall decision (§I; gh issue #4 — node mqaeqzdu-0746b3b7, a 9h zombie
- *  after an Anthropic outage). Pure, mirroring yieldStallVerdict; the kill side
- *  effects live in handleErrorStall.
+// Last-observed auth.json mtime, for the daemon's change-watch. Lazily seeded on
+// the first poll that sees the file (so daemon start never fans a spurious
+// reload), then updated on every detected change. In-memory only — a daemon
+// restart re-seeds from the current file, so at most one missed change spans the
+// restart gap (re-login during a ~1s restart), which a human just redoes.
+let knownAuthMtimeMs = null;
+/** Watch the shared auth.json mtime and, on a change, fan a live `reload_auth`
+ *  to every live broker so one `/login` propagates across the whole canvas. The
+ *  broker that performed the login already self-reloaded; re-reloading it is
+ *  harmless (authStorage.reload() is idempotent), so we don't exclude it.
  *
- *  'kill' ONLY when ALL of: engine alive, NO pending intent (refresh is §H's
- *  domain; idle-release chose dormancy), the turn is over (busy absent — a node
- *  wedged mid-bash must be recovered by killing the subprocess, never the node),
- *  the session file has been quiet past ERROR_STALL_QUIET_MS, and its last
- *  assistant message stopped with 'error'. */
-export function errorStallVerdict(piPidAlive, intent, busy, quietForMs, trailingError) {
-    if (piPidAlive !== true)
-        return 'leave';
-    if (intent !== null)
-        return 'leave';
-    if (busy)
-        return 'leave';
-    if (quietForMs === null || quietForMs < ERROR_STALL_QUIET_MS)
-        return 'leave';
-    if (!trailingError)
-        return 'leave';
-    return 'kill';
-}
-/** Enact an error-stall (§I): when the verdict is 'kill', SIGTERM the parked
- *  engine (escalating to SIGKILL after KILL_ESCALATE_MS, like §H — a broker
- *  wedged after an outage may not run graceful handlers). intent is null, so
- *  once the pid dies the ordinary crash branch in handleNodeLiveness grace-
- *  revives RESUME on the saved session — the conversation is preserved and the
- *  revive kickoff prompts the node to continue. No grace clock of our own: the
- *  session file's mtime IS the clock (any append — a re-steer, an inbox-watcher
- *  wake, a new turn — resets it). */
-function handleErrorStall(row, pid, now) {
-    const id = row.node_id;
-    if (row.intent !== null || isBusy(id)) {
-        errorTermAt.delete(id);
-        return;
-    }
-    const file = getNode(id)?.pi_session_file;
-    if (file == null)
-        return;
+ *  Rides the existing ~2s poll, so several rapid writes from one login collapse
+ *  to a single observed mtime change → a single fan. Each broker is reloaded
+ *  under its own try/catch (Promise.allSettled): a broker mid-shutdown or whose
+ *  socket refuses connect is logged and skipped, never aborting the others. */
+async function handleAuthReload(now) {
     let mtimeMs;
     try {
-        mtimeMs = statSync(file).mtimeMs;
+        mtimeMs = statSync(piAuthPath()).mtimeMs;
     }
     catch {
-        return; // session file unreadable — no evidence, never kill on "can't tell"
+        return; // no auth.json yet (never logged in) — nothing to watch
     }
-    const quietFor = now - mtimeMs;
-    if (quietFor < ERROR_STALL_QUIET_MS) {
-        errorTermAt.delete(id);
+    if (knownAuthMtimeMs === null) {
+        knownAuthMtimeMs = mtimeMs; // seed on first sight; never fan on daemon start
         return;
     }
-    let memo = errorTailMemo.get(id);
-    if (memo === undefined || memo.mtimeMs !== mtimeMs) {
-        memo = { mtimeMs, error: trailingEngineError(readTail(file)) };
-        errorTailMemo.set(id, memo);
+    if (mtimeMs === knownAuthMtimeMs)
+        return;
+    knownAuthMtimeMs = mtimeMs;
+    // Enumerate live brokers (pid alive + view.sock present) only when auth
+    // actually changed — the rare path, so the extra list/stat cost is paid only
+    // on a real login, never every tick.
+    let live;
+    try {
+        live = listNodes({ status: ['active', 'idle'] })
+            .filter((r) => r.kind !== 'human')
+            .map((r) => getNode(r.node_id))
+            .filter((m) => m !== null && isBrokerLive(m))
+            .map((m) => m.node_id);
     }
-    if (errorStallVerdict(true, row.intent, false, quietFor, memo.error !== null) !== 'kill')
+    catch (err) {
+        process.stderr.write(`[crtrd] auth-reload enumerate error: ${err.message}\n`);
         return;
-    const termed = errorTermAt.get(id);
-    if (termed === undefined) {
-        process.stderr.write(`[crtrd] kill ${id} (error-stall: engine parked on a trailing error turn, session quiet ${Math.round(quietFor / 1000)}s — SIGTERM; last error: ${String(memo.error).slice(0, 200)})\n`);
-        try {
-            process.kill(pid, 'SIGTERM');
-        }
-        catch {
-            /* already gone */
-        }
-        errorTermAt.set(id, now);
     }
-    else if (now - termed >= KILL_ESCALATE_MS) {
-        process.stderr.write(`[crtrd] kill ${id} (error-stall: pi ${pid} survived SIGTERM — SIGKILL)\n`);
+    if (live.length === 0)
+        return;
+    const results = await Promise.allSettled(live.map(async (id) => {
         try {
-            process.kill(pid, 'SIGKILL');
+            await reloadAuthLive(id);
         }
-        catch {
-            /* already gone */
+        catch (err) {
+            process.stderr.write(`[crtrd] auth-reload ${id} failed: ${err.message}\n`);
+            throw err;
         }
-    }
+    }));
+    const ok = results.filter((r) => r.status === 'fulfilled').length;
+    process.stderr.write(`[crtrd] auth-reload: auth.json changed — fanned to ${live.length} live broker(s) (${ok} ok, ${live.length - ok} failed)\n`);
 }
 /** Decide what to do with a node whose engine pid is DEAD, from how long it's
  *  been dead. Pure — the time/revive side effects live in handleNodeLiveness;
@@ -354,12 +290,14 @@ export function livenessVerdict(piPidAlive, deadFor) {
  *      with the turn over) and, once the engine has sat alive past the grace,
  *      kills it — so the daemon, not the (possibly stale) in-process stophook, is
  *      the authority on refresh, and the dead-pid refresh branch below then
- *      revives it fresh. AND enforce §I: handleErrorStall self-guards (no-op
- *      unless intent is null with the turn over) and kills an engine parked on a
- *      trailing-error turn whose session has been quiet past the grace, so the
- *      crash branch below grace-revives it RESUME.
+ *      revives it fresh. Fault recovery now runs in a separate pass: live,
+ *      daemon-owned provider faults are retried by inbox nudge, while dead-pid
+ *      crashes still fall through the ordinary resume path below.
  *    • pid null + pi_session_id set (a relaunch in flight — reviveNode clears
- *      pi_pid right after launch) → leave; the fresh engine re-records its pid.
+ *      pi_pid right after launch) → leave through a boot grace; a healthy engine
+ *      re-records its pid well within it. If the grace ELAPSES with still no pid,
+ *      the relaunch died after the pid-clear → grace-revive RESUME on the saved
+ *      session (else the node strands 'active' with no engine forever).
  *    • pid null + pi_session_id null (NEVER booted) → normally the sub-second SDK
  *      boot gap, but a broker that throws BEFORE session_start records no pid and
  *      no session ever — so after a boot grace with STILL nothing, crash +
@@ -380,37 +318,50 @@ async function handleNodeLiveness(row, now, revivedThisTick) {
     if (pid != null && isPidAlive(pid)) {
         unhealthySince.delete(id);
         handleYieldStall(row, pid, now);
-        handleErrorStall(row, pid, now);
         return;
     }
     if (pid == null) {
-        // No supervised pid recorded. Two very different cases turn on pi_session_id:
-        //   • a relaunch in flight — reviveNode clears pi_pid right after launch, but
-        //     the node ALREADY booted once (pi_session_id captured), so the fresh
-        //     engine re-records its pid within a tick or two; leave it.
-        //   • a NEVER-BOOTED broker (pi_session_id null) — normally the sub-second SDK
-        //     boot gap, BUT a broker that THROWS before session_start (malformed
-        //     broker-launch.json, SessionManager.open on a missing .jsonl, a loader/
-        //     registry/createAgentSession failure, the fork / bare-id guards, or
-        //     broker-cli's own fatal catch) records NO pid and NO session — EVER.
-        //     With pid==null read unconditionally as "still booting" that strands the
-        //     node 'active' with no engine forever and its parent waits on a dead
-        //     child. After a boot grace with STILL no pid AND no session, crash +
+        // No supervised pid recorded. BOTH sub-cases run the SAME boot grace clock and
+        // differ only in how it ENDS, keyed on pi_session_id:
+        //   • session SET — either a relaunch in flight (reviveNode clears pi_pid right
+        //     after launch; the fresh engine re-records within a tick or two, well
+        //     inside the grace, and the pid-alive branch above clears the clock) OR a
+        //     relaunch whose broker DIED after the pid-clear and before it re-recorded.
+        //     The healthy case never reaches the grace; if the grace DOES elapse with
+        //     still no pid, the relaunch is dead → grace-revive RESUME on the saved
+        //     session. Returning unconditionally here (the old behavior) read null+
+        //     session as "in flight" FOREVER and stranded such a node 'active' with no
+        //     engine — its parent waiting on a dead child indefinitely.
+        //   • session NULL — normally the sub-second SDK boot gap, BUT a broker that
+        //     THROWS before session_start (malformed broker-launch.json, SessionManager
+        //     .open on a missing .jsonl, a loader/registry/createAgentSession failure,
+        //     the fork / bare-id guards, or broker-cli's own fatal catch) records NO
+        //     pid and NO session — EVER. After the grace with STILL nothing, crash +
         //     surfaceBootFailure up the spine (M-1).
+        // The 20s grace doubles as the double-spawn guard: a healthy relaunch always
+        // re-records its pid well within it, so neither branch can fire on one.
         const meta = getNode(id);
-        if (meta === null || meta.pi_session_id != null) {
-            unhealthySince.delete(id); // relaunch in flight (or identity already bound)
+        if (meta === null) {
+            unhealthySince.delete(id); // row gone from meta — nothing to supervise
             return;
         }
         const since = unhealthySince.get(id);
         if (since === undefined) {
-            unhealthySince.set(id, now); // start the boot-grace clock
+            unhealthySince.set(id, now); // start the boot grace clock
             return;
         }
         if (now - since < REVIVE_GRACE_MS)
             return; // still inside the boot grace
-        // Boot grace elapsed, still no pid and no session → the broker never booted.
         unhealthySince.delete(id);
+        if (meta.pi_session_id != null) {
+            // Grace elapsed with a session but still no pid → a relaunch that died after
+            // the pid-clear, before re-record. Resume it on the saved session.
+            process.stderr.write(`[crtrd] revive ${id} (stranded relaunch — pid never re-recorded)\n`);
+            reviveNode(id, { resume: true });
+            revivedThisTick.add(id); // third-pass bare double-spawn guard (Maj-4)
+            return;
+        }
+        // Grace elapsed with no pid AND no session → the broker never booted.
         process.stderr.write(`[crtrd] boot-failed ${id} (broker exited before session_start)\n`);
         transition(id, 'crash');
         try {
@@ -421,12 +372,10 @@ async function handleNodeLiveness(row, now, revivedThisTick) {
         }
         return;
     }
-    // The engine pid is DEAD — any pending refresh/error-stall clock is moot (the
-    // dead-pid paths below own recovery now). Branch on intent.
+    // The engine pid is DEAD — the dead-pid paths below own recovery now. Branch
+    // on intent.
     yieldStallSince.delete(id);
     yieldTermAt.delete(id);
-    errorTermAt.delete(id);
-    errorTailMemo.delete(id);
     if (row.intent === 'refresh') {
         // Clean yield — or the §H force-kill above just landed — → respawn FRESH,
         // immediately (no grace wait).
@@ -578,11 +527,12 @@ function gcStaleFocuses() {
 // Pidfile
 // ---------------------------------------------------------------------------
 function pidfilePath() {
-    return join(crtrHome(), 'crtrd.pid');
+    const override = process.env['CRTR_PIDFILE'];
+    return override !== undefined && override !== '' ? override : join(crtrHome(), 'crtrd.pid');
 }
 function writePidfile() {
-    // Ensure the canvas home exists before writing.
-    mkdirSync(crtrHome(), { recursive: true });
+    // Ensure the pidfile parent exists before writing.
+    mkdirSync(dirname(pidfilePath()), { recursive: true });
     writeFileSync(pidfilePath(), String(process.pid), 'utf8');
 }
 function removePidfile() {
@@ -615,7 +565,18 @@ export function isDaemonRunning() {
 // ---------------------------------------------------------------------------
 // Supervisor tick
 // ---------------------------------------------------------------------------
+/** Supervision tick over the daemon's current live set. */
 export async function superviseTick(now = Date.now()) {
+    // Auth-reload fan FIRST, independent of node supervision: a change to the
+    // shared auth.json propagates a live credential reload to every broker. Kept
+    // ahead of the listNodes guard below so a transient list error in the
+    // supervision passes never skips an auth fan (it does its own enumeration).
+    try {
+        await handleAuthReload(now);
+    }
+    catch (err) {
+        process.stderr.write(`[crtrd] handleAuthReload error: ${err.message}\n`);
+    }
     let rows;
     try {
         rows = listNodes({ status: ['active', 'idle'] });
@@ -801,7 +762,7 @@ export async function superviseTick(now = Date.now()) {
                     // stored recipe) so the born node's kickoff leads with a <crtr-wake>
                     // block — it learns, by construction, that a timer birthed it (and, for
                     // a spawn-cron, that it is one run of a standing job).
-                    spawnChild({ ...recipe, wakeOrigin: wakeOriginFrom(w) });
+                    await spawnChild({ ...recipe, wakeOrigin: wakeOriginFrom(w) });
                     notifiedWakeFailures.delete(w.wakeup_id); // success clears the dedup latch
                 }
                 catch (err) {
@@ -842,7 +803,7 @@ export function runDaemon(opts = {}) {
     }
     const interval = opts.intervalMs ?? DEFAULT_INTERVAL_MS;
     writePidfile();
-    process.stderr.write(`[crtrd] started (pid ${process.pid}, interval ${interval}ms)\n`);
+    log.info(`started (pid ${process.pid}, interval ${interval}ms)`);
     let running = true;
     // Cleanup — idempotent.
     const cleanup = () => {

package/dist/daemon/manage.d.ts

@@ -6,11 +6,28 @@ export interface SpawnDaemonResult {
     /** PID of the already-running daemon, if it was already up. */
     existing_pid?: number;
 }
+export interface DaemonStartupDeps {
+    readPidfile?: () => number | null;
+    isPidAlive?: (pid: number) => boolean;
+    childExited?: () => {
+        code: number | null;
+        signal: NodeJS.Signals | null;
+    } | null;
+    sleepMs?: (ms: number) => Promise<void> | void;
+    now?: () => number;
+}
+/** 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.
+ *
+ *  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>;
 /** 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(): SpawnDaemonResult;
+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). */

package/dist/daemon/manage.js

@@ -9,7 +9,7 @@ import { fileURLToPath } from 'node:url';
 import { mkdirSync } from 'node:fs';
 import { crtrHome } from '../core/canvas/paths.js';
 import { hostExecPath } from '../core/runtime/branded-host.js';
-import { isDaemonRunning, readPidfile } from './crtrd.js';
+import { isDaemonRunning, readPidfile, isPidAlive } from './crtrd.js';
 // ---------------------------------------------------------------------------
 // Entry point resolution
 // ---------------------------------------------------------------------------
@@ -21,11 +21,45 @@ function resolveCrtrdEntry() {
     const here = dirname(fileURLToPath(import.meta.url));
     return join(here, 'crtrd-cli.js');
 }
+// Cold guests can take a few seconds to settle their pidfile + liveness probe.
+const STARTUP_VERIFY_WINDOW_MS = 5_000;
+const STARTUP_VERIFY_POLL_MS = 10;
+function sleepMs(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+/** 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.
+ *
+ *  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 = STARTUP_VERIFY_WINDOW_MS, deps = {}) {
+    const read = deps.readPidfile ?? readPidfile;
+    const alive = deps.isPidAlive ?? isPidAlive;
+    const exited = deps.childExited;
+    const sleep = deps.sleepMs ?? sleepMs;
+    const now = deps.now ?? Date.now;
+    const deadline = now() + timeoutMs;
+    while (now() <= deadline) {
+        const owner = read();
+        if (owner !== null && alive(owner))
+            return owner === pid ? null : owner;
+        const exitState = exited?.();
+        if (exitState !== null && exitState !== undefined) {
+            const exitDetail = exitState.signal !== null ? `by ${exitState.signal}` : `with exit code ${exitState.code ?? '?'}`;
+            throw new Error(`daemon ${pid} exited before becoming ready (${exitDetail})`);
+        }
+        await sleep(STARTUP_VERIFY_POLL_MS);
+    }
+    throw new Error(`daemon ${pid} did not become ready within ${timeoutMs}ms`);
+}
 /** 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 function spawnDaemon() {
+export async function spawnDaemon() {
     if (isDaemonRunning()) {
         return { started: false, existing_pid: readPidfile() ?? undefined };
     }
@@ -41,7 +75,20 @@ export function spawnDaemon() {
         stdio: 'ignore',
     });
     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();
+    const existingPid = await verifyDaemonStartup(pid, STARTUP_VERIFY_WINDOW_MS, {
+        childExited: () => exitState,
+    });
+    if (existingPid !== null) {
+        return { started: false, existing_pid: existingPid };
+    }
     return { started: true, pid };
 }
 // ---------------------------------------------------------------------------
@@ -51,12 +98,10 @@ export function spawnDaemon() {
  *  Silently swallows spawn errors (the canvas still works without the daemon;
  *  nodes just won't be auto-revived). */
 export function ensureDaemon() {
-    try {
-        if (!isDaemonRunning())
-            spawnDaemon();
-    }
-    catch {
-        // Intentionally silent — a missing dist/daemon/crtrd-cli.js (dev mode,
-        // pre-build) must not break the calling command.
+    if (!isDaemonRunning()) {
+        void spawnDaemon().catch(() => {
+            // Intentionally silent — a missing dist/daemon/crtrd-cli.js (dev mode,
+            // pre-build) must not break the calling command.
+        });
     }
 }