@crouton-kit/crouter 0.3.18 → 0.3.19

package/dist/daemon/crtrd.js

@@ -1,12 +1,14 @@
 // crtrd — the thin supervisor daemon. One instance per canvas.
 //
-// Sole responsibility: supervise tmux window exit and revive nodes. No
-// orchestration logic lives here. The daemon is a process-lifecycle watcher.
+// Sole responsibility: supervise engine-container exit (a tmux pane or a
+// headless broker process — `host_kind`) and revive nodes. No orchestration
+// logic lives here. The daemon is a process-lifecycle watcher.
 //
-// Model (v3: liveness is PANE-existence, not window-existence — a manual
-// move-pane/join-pane/break-pane must never read as a node death)
+// Model (v3: tmux liveness is PANE-existence, not window-existence — a manual
+// move-pane/join-pane/break-pane must never read as a node death; broker-hosted
+// nodes are supervised via their recorded pid — see handleBrokerLiveness)
 //   • Poll every intervalMs (default 2000ms).
-//   • For each active|idle node: check whether its tmux PANE is still alive
+//   • For each active|idle tmux node: check whether its tmux PANE is still alive
 //     (isNodePaneAlive; window-existence is only a legacy/no-pane fallback).
 //   • Pane alive → reconcile its LOCATION (follow any manual move; lazy-backfill
 //     a legacy row's pane), then judge pi liveness — healthy, skip otherwise.
@@ -25,16 +27,21 @@
 //   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, } from 'node:fs';
+import { writeFileSync, readFileSync, rmSync, existsSync, mkdirSync, statSync, } from 'node:fs';
 import { join } from 'node:path';
-import { crtrHome } from '../core/canvas/paths.js';
-import { listNodes, getRow, setPresence, getNode, hasActiveLiveSubscription, } from '../core/canvas/index.js';
+import { crtrHome, nodeDir, jobDir } from '../core/canvas/paths.js';
+import { listNodes, getRow, setPresence, getNode, hasActiveLiveSubscription, hasPendingSelfWake, 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 { isNodePaneAlive, reconcile } from '../core/runtime/placement.js';
+import { isPidAlive } from '../core/canvas/pid.js';
+import { reconcile, listLivePanes, tearDownNode } from '../core/runtime/placement.js';
+import { hostFor } from '../core/runtime/host.js';
 import { reviveNode } from '../core/runtime/revive.js';
-import { pushUrgent } from '../core/feed/feed.js';
-import { readInboxSince, readCursor } from '../core/feed/inbox.js';
+import { spawnChild } from '../core/runtime/spawn.js';
+import { wakeOriginFrom } from '../core/runtime/bearings.js';
+import { pushUrgent, pushUpdate } from '../core/feed/feed.js';
+import { appendInbox, readInboxSince, readCursor } from '../core/feed/inbox.js';
+import { nextSlotAfter } from '../core/wake.js';
 /** Surface a vehicle that never booted.
  *
  *  `spawnChild` returns status="active" the instant the tmux window opens — it
@@ -55,6 +62,37 @@ async function surfaceBootFailure(meta) {
         `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 });
 }
+/** Wake an inbox-waiting PARENT when the daemon ends a child the child did NOT
+ *  end itself — a mid-generation CRASH (the pane died inside a turn) or a quiet-
+ *  turn FINALIZE (the pane was dismissed after the turn ended with nothing live
+ *  to wait for). Mirrors surfaceBootFailure: a single push fanned to
+ *  subscribersOf(child), so a purely-inbox-waiting parent is woken on the SAME
+ *  channel as a `push final` — its live inbox-watcher, or this daemon's dormant-
+ *  revive second pass. Without it a parent that delegated and just stopped hangs
+ *  forever on these outcomes (D-1 finding: today only `push final` / never-booted
+ *  wake it). The doctrine "delegate and stop; the runtime wakes you" requires
+ *  EVERY terminal child outcome to reach the parent.
+ *
+ *  Fires ONLY on genuine death — NEVER on healthy dormancy. The CALLER owns that
+ *  boundary: this is invoked from the crash + finalize branches only; a child
+ *  that ended its turn still awaiting a live grandchild OR holding a pending
+ *  self-wake routes to `release` (revivable) and never reaches here. A CRASH is
+ *  URGENT (a fault, like a boot failure); a quiet FINALIZE is a normal update (a
+ *  clean dismissal — wake the dormant parent without interrupting a live one
+ *  mid-turn). */
+async function surfaceChildDeath(meta, cause) {
+    if (cause === 'crash') {
+        await pushUrgent(meta.node_id, `⚠ Child died — \`${meta.name}\` (${meta.kind}) was killed mid-task.\n\n` +
+            `Its pi vehicle went away mid-generation (the pane was closed or crashed while it was ` +
+            `working), so it never pushed a final report. Re-spawn it if the work still needs doing.`, { from: meta.node_id });
+    }
+    else {
+        await pushUpdate(meta.node_id, `\`${meta.name}\` (${meta.kind}) ended without a final report.\n\n` +
+            `Its turn ended and its pane was closed with nothing live left to wait for, so the runtime ` +
+            `finalized it. It pushed no \`final\` — check its reports/ for anything it left, and re-spawn ` +
+            `if the result is incomplete.`, { from: meta.node_id });
+    }
+}
 const DEFAULT_INTERVAL_MS = 2000;
 // How long a node's pi may be observed dead-while-its-window-lives before the
 // daemon revives it. MUST exceed worst-case pi boot time: a normal in-place
@@ -65,6 +103,134 @@ const REVIVE_GRACE_MS = 20_000;
 // Per-node first-observed-dead timestamps, for the grace window above. In-memory
 // only — a daemon restart resets it (worst case: one extra grace interval).
 const unhealthySince = new Map();
+// How long a node may sit with intent='refresh', its turn OVER (busy marker
+// absent) and its pi still ALIVE before the daemon concludes the yield stalled
+// and kills the pi. The healthy window is seconds: agent_end dispatches the
+// in-place respawn (which kills the old pi) immediately after clearing busy.
+// Minutes of that state means the shutdown/respawn path hung (observed at
+// ~200k-token contexts) and nothing else will ever unstick it — the daemon
+// only revives DEAD pis.
+export const YIELD_STALL_GRACE_MS = 3 * 60_000;
+// After a yield-stall SIGTERM, how long the pi gets to die gracefully before
+// escalating to SIGKILL (a pi hung at context overflow may not run handlers).
+const KILL_ESCALATE_MS = 20_000;
+// Per-node yield-stall clocks (audit 2026-06-09, Bug 1). In-memory like
+// unhealthySince — a daemon restart resets them (worst case: one extra grace).
+const yieldStallSince = new Map();
+const yieldTermAt = new Map();
+// Wake-failure dedup latch (third pass): wakeup_ids we've already fail-loud
+// notified about, so a permanently-broken spawn-cron (or a quarantined recurrence)
+// notifies the armer ONCE and then stays quiet until the next success or cancel —
+// the unrotated, append-only inbox.jsonl must not be flooded (Min-9). In-memory
+// only, like unhealthySince; a daemon restart resets it (worst case: one repeat
+// notice). A successful spawn clears its entry so a future failure re-notifies.
+const notifiedWakeFailures = new Set();
+// How old a spawned-but-sessionless node must be before the daemon treats it as
+// "never launched" and relaunches it. MUST generously exceed worst-case pi boot
+// under load: a healthy fresh spawn is sessionless (no pi_session_id, no pid,
+// zero cycles) for its whole boot, and relaunching into that window would
+// double-spawn.
+export const NEVER_LAUNCHED_GRACE_MS = 5 * 60_000;
+/** Never-launched decision (audit 2026-06-09, Bug 4 — node mq45b6ch-9ecc2f03):
+ *  a spawn that opened its window but whose pi never came up leaves a row with
+ *  ZERO cycles, NO session, NO pid — and, when the window lingers (e.g. a
+ *  remain-on-exit corpse), the live-pane pass read "no pid to judge" and left it
+ *  forever; the parent waited on a node that was never going to run. Pure core:
+ *  a node that has ever booted (session recorded) or ever been revived (cycles
+ *  bumped) is NOT never-launched — the cycles gate also bounds this to ONE
+ *  automatic retry (the relaunch bumps cycles), so a persistently failing
+ *  launch can't loop. Age below the grace is a normal in-flight boot. */
+export function neverLaunchedVerdict(piSessionId, cycles, ageMs) {
+    if (piSessionId != null || cycles > 0)
+        return 'leave';
+    return ageMs >= NEVER_LAUNCHED_GRACE_MS ? 'relaunch' : 'leave';
+}
+/** Enact the never-launched relaunch for a pane-alive, pid-less node (Bug 4):
+ *  verify against meta (pi_session_id is identity, read on demand), reap the
+ *  stale spawn window, and relaunch fresh via reviveNode — whose kickoff
+ *  carries the node's goal (context/initial-prompt.md) when no roadmap exists,
+ *  so the relaunched worker receives its original mandate. */
+function handleNeverLaunched(row, now, revivedThisTick) {
+    const age = now - Date.parse(row.created); // NaN compares false → leave
+    if (!(age >= NEVER_LAUNCHED_GRACE_MS))
+        return;
+    const meta = getNode(row.node_id);
+    if (meta === null)
+        return;
+    if (neverLaunchedVerdict(meta.pi_session_id ?? null, meta.cycles ?? 0, age) !== 'relaunch') {
+        return;
+    }
+    process.stderr.write(`[crtrd] relaunch ${row.node_id} (spawned but never launched: 0 cycles, no session, age ${Math.round(age / 1000)}s)\n`);
+    tearDownNode(row.node_id); // reap the stale spawn pane — reviveNode opens a fresh window
+    reviveNode(row.node_id, { resume: false });
+    revivedThisTick.add(row.node_id);
+}
+/** Yield-stall decision (audit 2026-06-09, Bug 1 — node mq5v9hfa-74493d45 and
+ *  three sibling orchestrators): a `node yield` records intent='refresh' and
+ *  agent_end dispatches the in-place respawn, but at very large contexts the pi
+ *  process can HANG instead of exiting — leaving pi alive, the turn over, and
+ *  the intent pending forever. The daemon only revives DEAD pis, so without
+ *  this verdict the node is permanently stuck (no revive, no wake). Pure core,
+ *  mirroring livenessVerdict; the kill side effects live in handleYieldStall.
+ *
+ *  'kill' ONLY when ALL of: pi alive, intent='refresh', the turn is over (busy
+ *  marker absent — a node may legitimately keep working for many minutes after
+ *  running `node yield` mid-turn, and a working pi must never be killed), and
+ *  the state has persisted past YIELD_STALL_GRACE_MS. */
+export function yieldStallVerdict(piPidAlive, intent, busy, stalledFor) {
+    if (piPidAlive !== true)
+        return 'leave';
+    if (intent !== 'refresh')
+        return 'leave';
+    if (busy)
+        return 'leave';
+    if (stalledFor === null || stalledFor < YIELD_STALL_GRACE_MS)
+        return 'pending';
+    return 'kill';
+}
+/** Enact a yield-stall (Bug 1): clock the stalled state, then SIGTERM the hung
+ *  pi (escalating to SIGKILL if it survives KILL_ESCALATE_MS — a pi hung at
+ *  context overflow may never run its handlers). Once the pi is dead the
+ *  ORDINARY machinery finishes the job: the pane-alive/pi-dead grace path
+ *  revives with resume=false (intent is still 'refresh'), i.e. the fresh
+ *  roadmap-revive the yield asked for. Safe against a graceful SIGTERM
+ *  shutdown racing us: markCleanExitDone no-ops while intent is pending, so a
+ *  dying pi can't mis-finalize the node. */
+function handleYieldStall(row, pid, now) {
+    const id = row.node_id;
+    if (row.intent !== 'refresh' || isBusy(id)) {
+        yieldStallSince.delete(id);
+        yieldTermAt.delete(id);
+        return;
+    }
+    const since = yieldStallSince.get(id);
+    if (since === undefined) {
+        yieldStallSince.set(id, now);
+        return;
+    }
+    if (yieldStallVerdict(true, row.intent, false, now - since) !== 'kill')
+        return;
+    const termed = yieldTermAt.get(id);
+    if (termed === undefined) {
+        process.stderr.write(`[crtrd] kill ${id} (yield-stall: pi ${pid} still alive ${Math.round((now - since) / 1000)}s after its refresh-yield turn ended — SIGTERM)\n`);
+        try {
+            process.kill(pid, 'SIGTERM');
+        }
+        catch {
+            /* already gone */
+        }
+        yieldTermAt.set(id, now);
+    }
+    else if (now - termed >= KILL_ESCALATE_MS) {
+        process.stderr.write(`[crtrd] kill ${id} (yield-stall: pi ${pid} survived SIGTERM — SIGKILL)\n`);
+        try {
+            process.kill(pid, 'SIGKILL');
+        }
+        catch {
+            /* already gone */
+        }
+    }
+}
 /** Decide what to do with a node whose tmux pane is alive, from its pi
  *  liveness and how long it's been dead. Pure — the time-and-tmux side effects
  *  live in handleLiveWindow; this is the unit-testable core.
@@ -82,22 +248,41 @@ export function livenessVerdict(piPidAlive, deadFor) {
  *  alive (an inline root runs pi under a persistent login shell that survives
  *  pi's death), so gauge liveness on the recorded pid and revive a dead pi once
  *  it's been dead past the grace window. */
-function handleLiveWindow(row, now) {
+function handleLiveWindow(row, now, revivedThisTick) {
     const id = row.node_id;
-    // A deliberately-frozen focused-dormant node (intent=idle-release) keeps its
-    // pane alive via remain-on-exit (F3, §3c). Do NOT grace-revive it here — it is
-    // waiting for a worker's inbox push, which the second pass delivers. Grace-
-    // reviving would pre-empt that and churn the frozen focus pane.
+    // Defensive: an idle-release node whose pane is still alive must NOT be
+    // grace-revived here — it is dormant BY CHOICE and is woken only by a worker's
+    // inbox push (the second pass below); grace-reviving would pre-empt that and
+    // churn the pane. (Focused-await nodes now stay pi-LIVE instead of releasing —
+    // see the stophook awaiting branch — so reaching this with a live pane is rare;
+    // the guard stays as a cheap safety net, e.g. a remain-on-exit pane frozen for
+    // a done-node's manager handoff.)
     if (row.intent === 'idle-release') {
         unhealthySince.delete(id);
+        yieldStallSince.delete(id);
+        yieldTermAt.delete(id);
         return;
     }
     const pid = row.pi_pid;
     const piPidAlive = pid == null ? null : isPidAlive(pid);
     if (piPidAlive !== false) {
         unhealthySince.delete(id); // alive, or no pid to judge — nothing pending
+        if (piPidAlive === null) {
+            // No pid recorded: a legacy row, a relaunch in flight — or a spawn whose
+            // pi NEVER came up while its window lingers (Bug 4). Judge the last case.
+            handleNeverLaunched(row, now, revivedThisTick);
+        }
+        else {
+            // pi ALIVE: judge a hung refresh-yield (Bug 1) — alive is not healthy
+            // when the node yielded, its turn ended, and the pi never exited.
+            handleYieldStall(row, pid, now);
+        }
         return;
     }
+    // pi is DEAD — any pending yield-stall clock is moot (the normal dead-pi
+    // grace path below owns recovery now).
+    yieldStallSince.delete(id);
+    yieldTermAt.delete(id);
     const since = unhealthySince.get(id);
     const verdict = livenessVerdict(piPidAlive, since === undefined ? null : now - since);
     if (verdict === 'pending') {
@@ -111,8 +296,219 @@ function handleLiveWindow(row, now) {
     // resumes the saved conversation. reviveNode opens a fresh window and clears
     // pi_pid, so the next tick won't re-fire on this stale pid.
     const resume = row.intent !== 'refresh';
-    process.stderr.write(`[crtrd] revive ${id} (pi dead, pane alive, intent=${String(row.intent)})\n`);
+    // A broker has no pane — say so (review Mn-4); the tmux wording is unchanged.
+    const where = row.host_kind === 'broker' ? 'broker, no pane' : 'pane alive';
+    process.stderr.write(`[crtrd] revive ${id} (pi dead, ${where}, intent=${String(row.intent)})\n`);
     reviveNode(id, { resume });
+    // Record for the third pass's bare double-spawn guard (Maj-4): this node's
+    // pi_pid is now NULL until the fresh pi re-records it, so a same-tick bare wake
+    // would otherwise read it as "not live" and double-spawn pi on the same .jsonl.
+    revivedThisTick.add(id);
+}
+/** A broker-hosted node has NO tmux pane — its only liveness signal is the
+ *  recorded broker pid (the engine-container pid the stophook records on
+ *  session_start, exactly like tmux pi). So the pane-gone user-close routing
+ *  never applies: every unexpected death is a genuine crash. Reuses the EXISTING
+ *  supervision primitive UNCHANGED — pid signal-0 + REVIVE_GRACE_MS grace +
+ *  unhealthySince + revivedThisTick — NO new machinery (decision §1.7 / R3).
+ *  Cases:
+ *    • pid alive → leave; clear any stale grace timer.
+ *    • pid null + pi_session_id set (a relaunch in flight — reviveNode clears
+ *      pi_pid right after launch) → leave; the fresh broker re-records its pid.
+ *    • 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 +
+ *      surfaceBootFailure (the broker analog of the tmux never-booted path, M-1).
+ *    • pid dead + intent==='refresh' → clean yield: respawn FRESH immediately, no
+ *      grace wait (matches the tmux refresh path / design "as today").
+ *    • pid dead + intent==='idle-release' → dormant by choice; leave, the second
+ *      pass revives (resume) on the next unseen inbox entry.
+ *    • pid dead + any other intent (crash / no clean intent) → grace-revive
+ *      RESUME on the saved .jsonl via handleLiveWindow. Its internal resume is
+ *      `row.intent !== 'refresh'`, which is true here (refresh + idle-release are
+ *      already handled above), so it resumes — no explicit resume flag needed. */
+async function handleBrokerLiveness(row, now, revivedThisTick) {
+    const id = row.node_id;
+    const pid = row.pi_pid;
+    // The broker engine is live → nothing pending; clear any boot/grace timer.
+    if (pid != null && isPidAlive(pid)) {
+        unhealthySince.delete(id);
+        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
+        //     broker 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. Mirror the tmux never-booted path: after a boot grace with STILL
+        //     no pid AND no session, crash + surfaceBootFailure up the spine (M-1).
+        const meta = getNode(id);
+        if (meta === null || meta.pi_session_id != null) {
+            unhealthySince.delete(id); // relaunch in flight (or identity already bound)
+            return;
+        }
+        const since = unhealthySince.get(id);
+        if (since === undefined) {
+            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);
+        process.stderr.write(`[crtrd] boot-failed ${id} (broker exited before session_start)\n`);
+        transition(id, 'crash');
+        try {
+            await surfaceBootFailure(meta);
+        }
+        catch (err) {
+            process.stderr.write(`[crtrd] surfaceBootFailure ${id} error: ${err.message}\n`);
+        }
+        return;
+    }
+    // The broker pid is dead. Branch on intent.
+    if (row.intent === 'refresh') {
+        // Clean yield → respawn FRESH, immediately (no grace wait).
+        process.stderr.write(`[crtrd] revive ${id} (broker refresh-yield)\n`);
+        reviveNode(id, { resume: false });
+        revivedThisTick.add(id); // third-pass bare double-spawn guard (Maj-4)
+        return;
+    }
+    if (row.intent === 'idle-release') {
+        // Freed itself while dormant → leave idle; the second pass revives it
+        // (resume) the moment its inbox gains an unseen entry.
+        unhealthySince.delete(id);
+        return;
+    }
+    // Any other intent → grace-revive RESUME, reusing handleLiveWindow's
+    // livenessVerdict → REVIVE_GRACE_MS → unhealthySince → revivedThisTick path
+    // unchanged (it re-probes the now-dead pid and accrues the grace window).
+    handleLiveWindow(row, now, revivedThisTick);
+}
+/** Fail loud for a drifted/broken wake (design §6.6/Q5): wake the ARMER DIRECTLY
+ *  via appendInbox — NOT pushUrgent, which fans to subscribersOf(owner), and a
+ *  DETACHED spawn has no subscribers (so the armer would never be reached); the
+ *  literal {from:null} is also a type error for pushUrgent. Deduped per wakeup_id
+ *  (notify once, suppress until the next success/cancel via notifiedWakeFailures)
+ *  so a broken spawn-cron can't flood the unrotated inbox.jsonl. Falls back to a
+ *  loud daemon-log line when the owner no longer resolves to a node. */
+function failLoudWake(w, label, body) {
+    if (notifiedWakeFailures.has(w.wakeup_id))
+        return;
+    notifiedWakeFailures.add(w.wakeup_id);
+    if (getRow(w.owner_id) !== null) {
+        appendInbox(w.owner_id, {
+            from: null,
+            tier: 'urgent',
+            kind: 'urgent',
+            label,
+            data: { body },
+        });
+    }
+    else {
+        process.stderr.write(`[crtrd] wake ${w.wakeup_id} failed (owner ${w.owner_id} gone): ${body}\n`);
+    }
+}
+// How long a dead node's on-disk record must have been QUIET (no meta/telemetry
+// write) before its leftover placement is reaped. A fresh crash keeps its pane
+// around this long so a human can read the corpse; a long-dead node's orphaned
+// pane is torn down on sight.
+export const DEAD_REAP_GRACE_MS = 10 * 60_000;
+/** ms since the node's durable record was last written (meta.json / job/
+ *  telemetry.json mtimes — the files every live cycle touches). Infinity when
+ *  neither exists: no disk evidence reads as ancient, not fresh. Deliberately
+ *  NOT inbox.jsonl — children keep appending to a dead manager's inbox, which
+ *  must not hold its corpse un-reapable forever. */
+function msSinceDiskActivity(nodeId, now) {
+    let latest = 0;
+    for (const p of [join(nodeDir(nodeId), 'meta.json'), join(jobDir(nodeId), 'telemetry.json')]) {
+        try {
+            const m = statSync(p).mtimeMs;
+            if (m > latest)
+                latest = m;
+        }
+        catch {
+            /* absent — contributes nothing */
+        }
+    }
+    return latest === 0 ? Number.POSITIVE_INFINITY : now - latest;
+}
+/** Reap the leftover PLACEMENT of long-dead nodes (audit 2026-06-09, Bug 3 —
+ *  node mq3l84it-40f6e8ac, a dead resident whose orphaned pane + focus row sat
+ *  untouched for ~36h). The daemon supervises only active|idle rows, so a node
+ *  that lands `dead` while still holding a pane is invisible to every pass and
+ *  its residue leaks forever.
+ *
+ *  Deliberate REAP-not-REVIVE decision: a dead node is NOT auto-revived. `dead`
+ *  means crashed — auto-resurrecting a crashed RESIDENT (a human conversation)
+ *  would pop dead chats back open unbidden, and the daemon's contract is to
+ *  supervise live nodes, not to undo terminal states. A dead resident's wake
+ *  sources remain the human ones (`node msg --tier critical`, focus, `canvas
+ *  revive`), all of which still work after this reap. What we DO reclaim is the
+ *  physical residue: kill the orphaned pane, drop the focus row, null the
+ *  LOCATION (tearDownNode). The node row, its edges, and all on-disk state stay
+ *  intact, so a later manual revive keeps its full graph — the leak was the
+ *  pane/focus/presence, not the row. Grace: only after DEAD_REAP_GRACE_MS of
+ *  disk quiet, so a just-crashed pane survives long enough to be inspected. */
+function reapDeadResidue(now) {
+    let rows;
+    try {
+        rows = listNodes({ status: ['dead'] });
+    }
+    catch (err) {
+        process.stderr.write(`[crtrd] reapDeadResidue list error: ${err.message}\n`);
+        return;
+    }
+    for (const row of rows) {
+        try {
+            if (row.pane == null && row.window == null && row.tmux_session == null)
+                continue;
+            if (msSinceDiskActivity(row.node_id, now) < DEAD_REAP_GRACE_MS)
+                continue;
+            process.stderr.write(`[crtrd] reap ${row.node_id} (dead, placement leaked: pane=${String(row.pane)} window=${String(row.window)})\n`);
+            tearDownNode(row.node_id);
+        }
+        catch (err) {
+            process.stderr.write(`[crtrd] error reaping ${row.node_id}: ${err.message}\n`);
+        }
+    }
+}
+/** GC stale focus rows (audit 2026-06-09, Bug 5): nothing else deletes a focuses
+ *  row when its pane dies outside the sanctioned teardown paths (a user
+ *  kill-pane, a tmux server restart, a crashed swap), so dead-pane rows
+ *  accumulate forever — the audit found 15 of 21 rows pointing at gone panes,
+ *  and a stale row both lies to graphSurfaceTarget and blocks its node from
+ *  being adopted into a fresh viewport (UNIQUE node_id). Sweep them here: one
+ *  batched `list-panes -a` probe (never a per-row display-message), deleting
+ *  rows whose recorded pane no longer exists. A pane-less row (a bridge/unplaced
+ *  viewport) has nothing to verify and is left alone. On a FAILED probe (tmux
+ *  unreachable — daemon racing a server restart) we skip the sweep entirely:
+ *  "can't tell" must never mass-delete every viewport. */
+function gcStaleFocuses() {
+    try {
+        const rows = listFocuses();
+        if (rows.length === 0)
+            return;
+        const live = listLivePanes();
+        if (live === null)
+            return; // probe failed — never GC on "can't tell"
+        for (const f of rows) {
+            if (f.pane === null || live.has(f.pane))
+                continue;
+            process.stderr.write(`[crtrd] gc focus ${f.focus_id} (pane ${f.pane} gone, occupant ${f.node_id})\n`);
+            closeFocusRow(f.focus_id);
+        }
+    }
+    catch (err) {
+        process.stderr.write(`[crtrd] gcStaleFocuses error: ${err.message}\n`);
+    }
 }
 // ---------------------------------------------------------------------------
 // Pidfile
@@ -142,18 +538,11 @@ export function readPidfile() {
     const n = Number(raw);
     return Number.isFinite(n) && n > 0 ? n : null;
 }
-/** True if a process with `pid` is currently alive (signal-0 probe). `kill(pid,
- *  0)` throws ESRCH when the process is gone; EPERM means it exists but isn't
- *  ours — still alive. */
-export function isPidAlive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (e) {
-        return e.code === 'EPERM';
-    }
-}
+// isPidAlive now lives in canvas/pid.ts (the one shared signal-0 probe at the
+// lowest layer, so canvas/, runtime/, AND daemon/ all import it down). Re-
+// exported here to preserve the public surface consumed by commands/daemon.ts
+// and the grace-clock test.
+export { isPidAlive };
 /** True when a crtrd process is already running (pidfile exists + pid alive). */
 export function isDaemonRunning() {
     const pid = readPidfile();
@@ -171,8 +560,22 @@ export async function superviseTick(now = Date.now()) {
         process.stderr.write(`[crtrd] listNodes error: ${err.message}\n`);
         return;
     }
+    // Node-ids revived in pass 1 + pass 2 THIS tick — the third pass's bare branch
+    // skips them so it never launches a second pi on the same .jsonl (Maj-4).
+    const revivedThisTick = new Set();
     for (const row of rows) {
         try {
+            // Broker-hosted node: it has NO tmux placement (tmux_session/window/pane
+            // are all NULL) but IS daemon-supervised via its recorded broker pid.
+            // Route it here BEFORE the inline-root carve-out below (which would
+            // wrongly skip a broker on the all-NULL placement) AND before the
+            // pane-gone block, whose first act (unhealthySince.delete) would wipe the
+            // broker's grace timer every tick. This single placement does both jobs
+            // (decision §1.6) — no edit to the carve-out is needed.
+            if (row.host_kind === 'broker') {
+                await handleBrokerLiveness(row, now, revivedThisTick);
+                continue;
+            }
             // Runtime (tmux_session, window, intent, pi_pid) is now authoritative IN
             // the row — no per-node getNode re-read. Only the boot-failure split below
             // still needs identity (pi_session_id), read on demand there.
@@ -181,23 +584,46 @@ export async function superviseTick(now = Date.now()) {
             // even when its derived window/session cache is null.
             if (row.tmux_session == null && row.window == null && row.pane == null)
                 continue;
-            if (isNodePaneAlive(row)) {
+            if (hostFor(row).isAlive(row)) {
                 // The pane is up — but that alone doesn't mean pi is. Reconcile first
                 // (follow any manual pane move, and lazy-backfill a legacy row's pane
                 // from its live window), then judge pi liveness off the fresh row. The
                 // alive-gate means reconcile here only ever FOLLOWS/backfills — never
                 // nulls the LOCATION out from under the gone-branches below.
                 reconcile(row.node_id);
-                handleLiveWindow(getRow(row.node_id) ?? row, now);
+                handleLiveWindow(getRow(row.node_id) ?? row, now, revivedThisTick);
                 continue;
             }
             // The pane is gone. Branch on why.
             unhealthySince.delete(row.node_id); // pane-gone path owns it now
+            yieldStallSince.delete(row.node_id);
+            yieldTermAt.delete(row.node_id);
+            // Zombie vehicle (audit 2026-06-09, Bug 2 — node mq4ms6n4-fbc455cd): the
+            // pane died but its pi SURVIVED (pi can outlive the pane's SIGHUP). Every
+            // branch below assumes "pane gone ⇒ pi gone"; with a live orphan that
+            // assumption corrupts — the headless pi keeps re-arming its inbox watcher
+            // with no pane a human can reach, the second pass's pi-liveness gate skips
+            // a released node forever, and a refresh-revive would run a second pi
+            // beside it. There is no legitimate pane-gone+pi-alive state (in-place
+            // respawns keep the pane id; teardown paths null presence before reaping),
+            // so kill the orphan first, then route normally. SIGKILL, not SIGTERM: an
+            // orphaned pi's shutdown hooks mutating canvas state mid-routing is
+            // exactly what we're fencing out.
+            if (row.pi_pid != null && isPidAlive(row.pi_pid)) {
+                process.stderr.write(`[crtrd] kill ${row.node_id} (zombie pi ${row.pi_pid}: pane gone, pi alive)\n`);
+                try {
+                    process.kill(row.pi_pid, 'SIGKILL');
+                }
+                catch {
+                    /* raced its own death — fine */
+                }
+            }
             if (row.intent === 'refresh') {
                 // The node set intent=refresh before stopping — a clean yield. Respawn
                 // fresh so it re-reads its roadmap/context dir.
                 process.stderr.write(`[crtrd] revive ${row.node_id} (refresh-yield)\n`);
                 reviveNode(row.node_id, { resume: false });
+                revivedThisTick.add(row.node_id); // third-pass bare double-spawn guard (Maj-4)
             }
             else if (row.intent === 'idle-release') {
                 // The node freed its own window on purpose while dormant. Drop the stale
@@ -206,8 +632,11 @@ export async function superviseTick(now = Date.now()) {
                 setPresence(row.node_id, { tmux_session: row.tmux_session, window: null });
             }
             else {
-                // The pane vanished without the node yielding or releasing. Route on what
-                // the node was DOING at pane-kill time — not every gone pane is a death:
+                // The pane vanished without the node yielding or releasing — most often
+                // the user CLOSED it (kill-pane/kill-window), which crtr cannot tell apart
+                // from a window death. Closing a pane is a benign "get it off my screen",
+                // NOT an orphan-the-work kill, so route on what the node was DOING and keep
+                // anything with outstanding work REVIVABLE:
                 //   • never-booted (pi_session_id null) → crash + surface boot failure.
                 //     A spawn failure the parent was never told about — it had no turn to
                 //     finish, so it can never be a finalize. (Boot-failed vs crashed turns
@@ -218,18 +647,47 @@ export async function superviseTick(now = Date.now()) {
                 //     killed inside a turn: a genuine mid-run death. (The pane is gone, so
                 //     pi is dead; we read isBusy WITHOUT the usual AND-pidAlive guard on
                 //     purpose — here a stale marker IS the proof it died mid-turn.)
-                //   • finished its turn (busy ABSENT) but still awaiting a LIVE child →
-                //     crash (→dead) for now. (This waiting-on-a-live-child case may later
-                //     route to a revivable-idle instead of a hard death.)
-                //   • finished its turn AND awaiting nothing live → finalize (→done): it
-                //     did its own work and the pane was closed to dismiss it.
+                //   • finished its turn (busy ABSENT) but STILL WAITING — awaiting a LIVE
+                //     child OR holding a pending self-wake → RELEASE (→idle + idle-release),
+                //     NOT dead, and NO parent wake. This is HEALTHY DORMANCY (the same
+                //     boundary the stop-guard draws): real orchestration / a scheduled
+                //     clock is outstanding; killing it would orphan in-flight work, and
+                //     waking its parent here would re-create the spurious-wake storm the
+                //     wake doctrine exists to kill. Drop the stale window; the second /
+                //     wakeups pass revives it on the next child push or clock fire.
+                //   • finished its turn AND nothing live to wait for AND no pending clock →
+                //     finalize (→done): it did its own work and the pane was closed to
+                //     dismiss it. GENUINE death → wake the inbox-waiting parent.
                 const meta = getNode(row.node_id);
                 const neverBooted = meta !== null && meta.pi_session_id == null;
-                if (!neverBooted &&
-                    !isBusy(row.node_id) &&
-                    !hasActiveLiveSubscription(row.node_id)) {
+                const finishedTurn = !neverBooted && !isBusy(row.node_id);
+                // The death-vs-dormancy boundary, drawn EXACTLY where the stop-guard draws
+                // it (stop-guard.ts): a live active subscription OR a pending self-wake is
+                // a legitimate wait. Only a finished node with NEITHER is genuinely done.
+                const stillWaiting = hasActiveLiveSubscription(row.node_id) || hasPendingSelfWake(row.node_id);
+                if (finishedTurn && !stillWaiting) {
                     transition(row.node_id, 'finalize');
-                    process.stderr.write(`[crtrd] done ${row.node_id} (pane gone after turn end, no live child)\n`);
+                    process.stderr.write(`[crtrd] done ${row.node_id} (pane gone after turn end, nothing live to wait for)\n`);
+                    // Wake the inbox-waiting parent: the child ended without a `push final`
+                    // and was dismissed; without this the daemon-finalize reaches no one
+                    // (D-1) and a purely-inbox-waiting parent hangs forever.
+                    if (meta !== null) {
+                        try {
+                            await surfaceChildDeath(meta, 'finalize');
+                        }
+                        catch (err) {
+                            process.stderr.write(`[crtrd] surfaceChildDeath(finalize) ${row.node_id} error: ${err.message}\n`);
+                        }
+                    }
+                }
+                else if (finishedTurn) {
+                    // Still legitimately waiting (a live child OR a pending self-wake) →
+                    // revivable, NOT a death: closing the pane must not orphan in-flight
+                    // work, and healthy dormancy must NOT wake the parent. Clear the stale
+                    // window; the second / wakeups pass revives it.
+                    setPresence(row.node_id, { tmux_session: row.tmux_session, window: null, pane: null });
+                    transition(row.node_id, 'release');
+                    process.stderr.write(`[crtrd] release ${row.node_id} (pane gone while still waiting → revivable, no parent wake)\n`);
                 }
                 else {
                     transition(row.node_id, 'crash');
@@ -243,7 +701,18 @@ export async function superviseTick(now = Date.now()) {
                         }
                     }
                     else {
-                        process.stderr.write(`[crtrd] dead ${row.node_id} (pane gone, intent=${String(row.intent)})\n`);
+                        process.stderr.write(`[crtrd] dead ${row.node_id} (pane gone mid-generation, intent=${String(row.intent)})\n`);
+                        // Wake the inbox-waiting parent on a GENUINE mid-run death (D-1): a
+                        // booted child whose pane died inside a turn is unambiguously dead
+                        // (busy marker present), never healthy dormancy.
+                        if (meta !== null) {
+                            try {
+                                await surfaceChildDeath(meta, 'crash');
+                            }
+                            catch (err) {
+                                process.stderr.write(`[crtrd] surfaceChildDeath(crash) ${row.node_id} error: ${err.message}\n`);
+                            }
+                        }
                     }
                 }
             }
@@ -267,21 +736,168 @@ export async function superviseTick(now = Date.now()) {
             if (r.status !== 'idle' || r.intent !== 'idle-release')
                 continue;
             // The in-process inbox-watcher only owns delivery while pi is actually LIVE.
-            // A frozen focused-dormant pane (remain-on-exit, F3) is pane-ALIVE but
-            // pi-DEAD — no watcher — so the daemon must wake it. Gate the skip on pi
-            // liveness, NOT pane presence (which would skip a frozen pane forever, §3c).
+            // A released node is pi-DEAD with no watcher — whether its pane is GONE
+            // (unfocused release) or still ALIVE (a remain-on-exit pane frozen for a
+            // done-node's manager handoff) — so the daemon must wake it. Gate the skip
+            // on pi liveness, NOT pane presence (which would skip a frozen pane
+            // forever, §3c).
             if (r.pi_pid != null && isPidAlive(r.pi_pid))
                 continue;
             const entries = readInboxSince(row.node_id, readCursor(row.node_id));
             if (entries.length > 0) {
                 process.stderr.write(`[crtrd] revive ${row.node_id} (idle-release, inbox)\n`);
                 reviveNode(row.node_id, { resume: true });
+                revivedThisTick.add(row.node_id); // third-pass bare double-spawn guard (Maj-4)
             }
         }
         catch (err) {
             process.stderr.write(`[crtrd] error polling inbox ${row.node_id}: ${err.message}\n`);
         }
     }
+    // Third pass: FIRE DUE SCHEDULED WAKES (the wakeups engine, migration v7).
+    // Runs immediately AFTER the inbox second pass — the ordering is load-bearing
+    // (design §6.4): a same-tick inbox revive runs cancelDeadlinesFor (inside
+    // reviveNode) BEFORE this pass's dueWakes query, so an event that wins a
+    // deadline deletes its row before it can fire. The pass-2 inbox loop above is
+    // otherwise untouched (design D3) — it stays the generic wake-on-message path
+    // that noted/deadline rely on; the only addition is the revivedThisTick.add
+    // observation that the bare branch below needs to avoid a double-spawn.
+    // For each due row, in fire_at order, settle the row FIRST (advance-or-consume
+    // — crash-safety, design D4) THEN enact by kind, wrapped per-row so one bad
+    // wake never kills the tick.
+    const nowIso = new Date(now).toISOString();
+    const nowDate = new Date(now);
+    let due;
+    try {
+        due = dueWakes(nowIso);
+    }
+    catch (err) {
+        process.stderr.write(`[crtrd] dueWakes error: ${err.message}\n`);
+        due = [];
+    }
+    for (const w of due) {
+        try {
+            // 1. Advance-or-consume FIRST (design D4): settle the row's pending state
+            //    before ANY side effect, so a daemon crash mid-fire can never double-
+            //    fire (a double SPAWN is the worst case — structurally prevented here).
+            if (w.recur == null) {
+                consumeWake(w.wakeup_id);
+            }
+            else {
+                let nextFire;
+                try {
+                    nextFire = nextSlotAfter(w.recur, nowDate);
+                }
+                catch (err) {
+                    // The recur is unparseable (parseCadence validates at arm time, so this
+                    // is a rare backstop — a corrupted/foreign row). Leaving a past-fire_at
+                    // row pending would re-qualify it EVERY tick (silent CPU spin, enact
+                    // never reached), so quarantine it (consume) + fail loud ONCE; never
+                    // re-query it each tick (Min-8).
+                    consumeWake(w.wakeup_id);
+                    failLoudWake(w, '⚠ recurrence quarantined', `Scheduled wake ${w.wakeup_id} has an unparseable recurrence and was removed: ` +
+                        `${err.message}\n\nRe-arm it with a valid cadence.`);
+                    continue;
+                }
+                advanceWake(w.wakeup_id, nextFire);
+            }
+            // 2. Enact by kind.
+            if (w.kind === 'bare') {
+                // A bare wake leaves NO inbox entry, so pass 2 can never wake it — it
+                // must revive DIRECTLY with resume:false (re-reads roadmap; AC-N2).
+                const target = w.node_id == null ? null : getRow(w.node_id);
+                if (target === null)
+                    continue; // target gone (the FK cascade reaped it)
+                // Same-tick double-spawn guard (Maj-4): pass 1/2 (or an earlier bare row
+                // this pass) may have revived this node THIS tick — reviveNode clears
+                // pi_pid to NULL before the fresh pi re-records it, so the pi_pid==null
+                // liveness check below would falsely read "not live" and a second
+                // reviveNode would launch a SECOND pi on the same .jsonl (corruption).
+                // (Pane-existence is the WRONG guard — it would no-op a frozen-focus bare
+                // wake, which is pane-alive/pi-dead by design.)
+                if (revivedThisTick.has(target.node_id))
+                    continue;
+                // pi live → no-op (AC-E3 bare): an already-awake node needs no revive.
+                if (target.pi_pid != null && isPidAlive(target.pi_pid))
+                    continue;
+                process.stderr.write(`[crtrd] wake ${target.node_id} (bare alarm)\n`);
+                // wakeReason carries the timer provenance so the fresh-revive kickoff
+                // leads with a <crtr-wake> block (Invariant B/D: the node learns a clock,
+                // not an event, woke it) instead of a generic context-refresh framing.
+                reviveNode(target.node_id, { resume: false, wakeReason: wakeOriginFrom(w) });
+                revivedThisTick.add(target.node_id);
+            }
+            else if (w.kind === 'noted') {
+                // Deliver the note; the UNMODIFIED pass 2 wakes the dormant target next
+                // tick (AC-N1), or its live in-process watcher delivers it (AC-E3 noted).
+                if (w.node_id == null)
+                    continue;
+                const p = w.payload;
+                // Mark the delivery as a SCHEDULED wake (Invariant D): the woken node sees
+                // only the rendered digest (inbox inlines label/body, never arbitrary
+                // data keys), so the timer signal MUST ride the visible label — the same
+                // ⏰ family deadline uses — so a noted wake is distinguishable from a plain
+                // `node msg`, not indistinguishable from it.
+                appendInbox(w.node_id, {
+                    from: w.owner_id ?? null,
+                    tier: 'normal',
+                    kind: 'message',
+                    label: `⏰ scheduled wake — ${p.label}`,
+                    data: { body: p.body },
+                });
+            }
+            else if (w.kind === 'deadline') {
+                // Same delivery as noted but URGENT tier. The woken node sees only the
+                // RENDERED digest (inbox inlines label/body, NEVER arbitrary data keys),
+                // so the timeout signal MUST ride the visible label/body (Maj-8);
+                // data.timeout is a machine-readable mirror only. body is always non-
+                // empty (the surface supplies a default timeout note when none is
+                // authored, Maj-7). One-shot — already consumed in step 1.
+                if (w.node_id == null)
+                    continue;
+                const p = w.payload;
+                appendInbox(w.node_id, {
+                    from: w.owner_id ?? null,
+                    tier: 'urgent',
+                    kind: 'message',
+                    label: `⏰ deadline reached — ${p.label}`,
+                    data: { body: p.body, timeout: true },
+                });
+            }
+            else if (w.kind === 'spawn') {
+                // Re-derives LaunchSpec live (AC-W2); payload.parent is the non-null
+                // resolved armer id (T2/T7 guarantee it), so spawnChild never throws the
+                // "requires a calling node" error even for a --root recipe.
+                const recipe = w.payload;
+                try {
+                    // Spread in the wake provenance at fire time (in-memory only; never the
+                    // 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) });
+                    notifiedWakeFailures.delete(w.wakeup_id); // success clears the dedup latch
+                }
+                catch (err) {
+                    // Fail loud by waking the ARMER DIRECTLY (design §6.6/Q5). The row was
+                    // already settled in step 1, so this is never a hot retry loop; a
+                    // permanently-broken spawn-cron stays deduped-noisy until cancel.
+                    failLoudWake(w, '⚠ deferred spawn failed', `Deferred spawn (${recipe.kind} @ ${recipe.cwd}) failed: ` +
+                        `${err.message}\n\nRe-home (fix the cwd/parent) or re-arm the wake.`);
+                }
+            }
+        }
+        catch (err) {
+            // One bad wake never kills the tick.
+            process.stderr.write(`[crtrd] error firing wake ${w.wakeup_id}: ${err.message}\n`);
+        }
+    }
+    // Fourth pass: reap the leftover placement of long-dead nodes (Bug 3), then
+    // sweep focus rows whose pane died outside the sanctioned teardown paths
+    // (Bug 5). Reap first so the GC also catches any focus row a reaped pane
+    // strands; last overall so neither races a focus a same-tick revive just
+    // re-anchored.
+    reapDeadResidue(now);
+    gcStaleFocuses();
 }
 /** Start the supervisor loop.
  *