@crouton-kit/crouter 0.3.14 → 0.3.15

package/dist/core/runtime/tmux.js

@@ -8,6 +8,7 @@
 // root) or switch-client + select-window (across roots). done/dead nodes close
 // their window; reviving opens a fresh one.
 import { spawn, spawnSync } from 'node:child_process';
+import { readConfig } from '../config.js';
 // ---------------------------------------------------------------------------
 // Shell quoting + tmux invocation
 // ---------------------------------------------------------------------------
@@ -69,7 +70,8 @@ function envFlags(env) {
 }
 /** Open a background window for a node and run `command` in it. `-d` keeps it
  *  detached so it doesn't steal focus or become the current window. Returns the
- *  new window id.
+ *  new window id AND the pane id it created (the durable `%pane_id`, LOCATION's
+ *  anchor) — callers that only need the window destructure `.window`.
  *
  *  Target is `${session}:` (trailing colon = the session, no window index) plus
  *  `-a` (insert after the current window) so tmux allocates the next free index.
@@ -78,7 +80,8 @@ function envFlags(env) {
  *  "create window failed: index N in use" whenever the active window is not the
  *  last one (common when base-index is 0 but the live window sits at index 1).
  *  `-a` also keeps node windows off index 0, which is reserved for the optional
- *  dashboard. */
+ *  dashboard. The explicit `-t ${session}:` target is the §2.2 HARD DRIVER
+ *  INVARIANT — never let new-window fall back to tmux's global current session. */
 export function openNodeWindow(opts) {
     const r = tmux([
         'new-window',
@@ -86,7 +89,7 @@ export function openNodeWindow(opts) {
         '-a',
         '-P',
         '-F',
-        '#{window_id}',
+        '#{window_id}\t#{pane_id}',
         '-t',
         `${opts.session}:`,
         '-n',
@@ -96,7 +99,40 @@ export function openNodeWindow(opts) {
         ...envFlags(opts.env),
         opts.command,
     ]);
-    return r.ok ? r.stdout : null;
+    if (!r.ok)
+        return null;
+    const [window, pane] = r.stdout.split('\t');
+    if (window === undefined || window === '' || pane === undefined || pane === '') {
+        return null;
+    }
+    return { window, pane };
+}
+/** Split `targetPane`'s window, opening a NEW pane beside it running `command`,
+ *  and return the new pane id (the durable `%id`). The ONLY new-pane-beside verb
+ *  (Q3: a focus opened side-by-side). `-d` keeps the caller's pane active; `-h`
+ *  makes the split side-by-side (left/right), the default for a focus viewport.
+ *
+ *  §2.2 HARD DRIVER INVARIANT: `targetPane` is REQUIRED — a bare `split-window`
+ *  would split tmux's global current pane, which can leak a pane into an
+ *  unrelated user session (the exact bug this design kills). The explicit
+ *  `-t <targetPane>` makes the destination structurally un-leakable. Returns
+ *  null if tmux fails. */
+export function splitWindow(targetPane, opts) {
+    const r = tmux([
+        'split-window',
+        '-d',
+        ...(opts.vertical === true ? [] : ['-h']),
+        '-P',
+        '-F',
+        '#{pane_id}',
+        '-t',
+        targetPane,
+        '-c',
+        opts.cwd,
+        ...envFlags(opts.env),
+        opts.command,
+    ]);
+    return r.ok && r.stdout !== '' ? r.stdout : null;
 }
 /** Bring a node's window forefront. Switches client across roots when needed. */
 export function focusWindow(session, window) {
@@ -112,6 +148,14 @@ export function focusWindow(session, window) {
 export function closeWindow(window) {
     return tmux(['kill-window', '-t', window]).ok;
 }
+/** Close a single PANE. Its window closes automatically once this was the last
+ *  pane, but sibling panes survive — so co-located nodes (several agents sharing
+ *  one window via swap-pane focus) are torn down one at a time instead of all
+ *  at once by a window kill. Pane ids are the stable vehicle handle; windows
+ *  shift under swap-pane focus, so pane-granular teardown is the correct unit. */
+export function closePane(pane) {
+    return tmux(['kill-pane', '-t', pane]).ok;
+}
 /** The active pane id of a window. Node windows are single-pane, so this is the
  *  node's pane. Returns null if the window is gone or tmux fails. */
 export function paneOfWindow(session, window) {
@@ -126,8 +170,11 @@ export function windowOfPane(pane) {
     const r = tmux(['display-message', '-p', '-t', pane, '#{window_id}']);
     return r.ok && r.stdout !== '' ? r.stdout : null;
 }
-/** The session + window a pane currently lives in. Used by demote to place the
- *  recycled root's meta on the pane it respawns into. Null if tmux fails. */
+/** The session + window a pane currently lives in (`display-message -p -t %id`).
+ *  The §2.4 reconciliation read-back: resolve a node's/focus's CURRENT
+ *  window/session from its durable pane id before any act, so crtr follows a
+ *  manual `move-pane`/`join-pane`/`break-pane` instead of fighting it. Null if
+ *  the pane is gone or tmux fails. */
 export function paneLocation(pane) {
     const r = tmux(['display-message', '-p', '-t', pane, '#{session_name}\t#{window_id}']);
     if (!r.ok)
@@ -137,6 +184,31 @@ export function paneLocation(pane) {
         return null;
     return { session, window };
 }
+/** Does this pane id still exist? A `display-message` probe on the `%id` — the
+ *  v3 PRIMARY liveness probe (§1.2/§2.2), replacing window-existence so a user
+ *  moving a pane to another window/session never reads as "gone". True iff tmux
+ *  knows the pane.
+ *
+ *  NOTE: `display-message -p -t <gone-pane>` EXITS 0 with EMPTY output (it does
+ *  not error on an unresolvable pane target) — so an `.ok` check alone would
+ *  report a dead pane as alive, defeating the whole point of pane-existence
+ *  liveness. We therefore require the echoed `#{pane_id}` to equal the requested
+ *  pane: a live pane echoes its own id, a gone/bogus one yields empty. */
+export function paneExists(pane) {
+    const r = tmux(['display-message', '-p', '-t', pane, '#{pane_id}']);
+    return r.ok && r.stdout === pane;
+}
+/** Relocate a pane into another session as its own window WITHOUT killing the
+ *  process in it — `break-pane -d` moves the pane out of its current window (the
+ *  pi keeps generating) into a fresh window in `session`; `-d` leaves the caller's
+ *  client where it is rather than following the pane to the background, and `-a`
+ *  allocates the next free window index (same dodge as openNodeWindow). The
+ *  "detach to background" driver behind `node lifecycle --detach`. Best-effort;
+ *  false if tmux refuses (e.g. the pane is gone). The caller reconciles presence
+ *  so the canvas follows the move. */
+export function breakPaneToSession(pane, session) {
+    return tmux(['break-pane', '-d', '-a', '-s', pane, '-t', `${session}:`]).ok;
+}
 /** Swap `targetPane` into `callerPane`'s layout slot, IN PLACE. `-d` keeps the
  *  caller's window active, so the target's pane appears where the caller is
  *  rather than navigating the client off to the target's window. The caller's
@@ -147,26 +219,34 @@ export function swapPaneInPlace(targetPane, callerPane) {
         return true;
     return tmux(['swap-pane', '-d', '-s', targetPane, '-t', callerPane]).ok;
 }
-/** Re-exec a command in an EXISTING pane, in place. `-k` kills the pane's
- *  current process (e.g. a yielding pi) and starts `command` in the same pane
- *  — the window/pane survives, so an interactive session is never dropped to a
- *  shell and no window churns. Used by refresh-yield.
- *
- *  Spawned DETACHED (own process group, unref'd) so the request reaches the
- *  tmux server even though killing the pane tears down the caller's own pi.
- *  Returns true once the request was dispatched. */
-export function respawnPane(opts) {
+/** The `respawn-pane -k` argv for `opts`. `-k` kills the pane's current process
+ *  (e.g. a yielding pi) and re-execs `command` in the SAME pane, preserving its
+ *  `%id` (§1.5 F3: a frozen focus pane resumes in place, no new window). The
+ *  explicit `-t opts.pane` is the §2.2 HARD DRIVER INVARIANT — respawn must name
+ *  its target pane, never tmux's global current pane. */
+function respawnPaneArgs(opts) {
+    return [
+        'respawn-pane',
+        '-k',
+        '-c',
+        opts.cwd,
+        ...envFlags(opts.env),
+        '-t',
+        opts.pane,
+        opts.command,
+    ];
+}
+/** Re-exec a command in an EXISTING pane, in place — DETACHED. Spawned in its own
+ *  process group (unref'd) so the request reaches the tmux server even though
+ *  `-k` tears down the caller's own pi mid-flight. Used when a node respawns ITS
+ *  OWN pane (refresh-yield): the dispatch can't be awaited because it kills the
+ *  awaiter. Returns true once the request was dispatched. */
+export function respawnPaneDetached(opts) {
     try {
-        const child = spawn('tmux', [
-            'respawn-pane',
-            '-k',
-            '-c',
-            opts.cwd,
-            ...envFlags(opts.env),
-            '-t',
-            opts.pane,
-            opts.command,
-        ], { detached: true, stdio: 'ignore' });
+        const child = spawn('tmux', respawnPaneArgs(opts), {
+            detached: true,
+            stdio: 'ignore',
+        });
         child.unref();
         return true;
     }
@@ -174,6 +254,19 @@ export function respawnPane(opts) {
         return false;
     }
 }
+/** Re-exec a command in an EXISTING pane, in place — SYNCHRONOUS. Runs the
+ *  `respawn-pane` to completion and reports the real exit status. Used when the
+ *  caller is NOT the pane being respawned (e.g. the daemon resuming a frozen
+ *  focus pane), so it can confirm the respawn landed. Returns true on success. */
+export function respawnPaneSync(opts) {
+    return tmux(respawnPaneArgs(opts)).ok;
+}
+/** @deprecated Use respawnPaneDetached. Retained so existing refresh-yield
+ *  callers stay green while the placement layer migrates onto the explicit
+ *  sync/detached split. */
+export function respawnPane(opts) {
+    return respawnPaneDetached(opts);
+}
 // ---------------------------------------------------------------------------
 // pi command assembly
 // ---------------------------------------------------------------------------
@@ -216,12 +309,55 @@ export function switchClient(session) {
     return tmux(['switch-client', '-t', session]).ok;
 }
 // ---------------------------------------------------------------------------
+// Multi-pane layout (used by `canvas tmux-spread`)
+// ---------------------------------------------------------------------------
+/** Move a source pane into a destination window (`tmux join-pane`). The source
+ *  pane's running process (e.g. a child's live pi) is preserved; its now-empty
+ *  source window auto-closes. Best-effort; false if tmux fails. */
+export function joinPane(srcPane, dstWindow) {
+    return tmux(['join-pane', '-s', srcPane, '-t', dstWindow]).ok;
+}
+/** Apply a named tmux layout to a window (`tmux select-layout`). Use
+ *  `main-vertical` for one wide pane on the left + the rest stacked right.
+ *  Best-effort; never throws. */
+export function selectLayout(window, layout) {
+    return tmux(['select-layout', '-t', window, layout]).ok;
+}
+/** Set a tmux window option (`tmux set-window-option`). Used to size the main
+ *  pane (`main-pane-width`) before a main-vertical layout. Best-effort. */
+export function setWindowOption(window, name, value) {
+    return tmux(['set-window-option', '-t', window, name, value]).ok;
+}
+/** Toggle `remain-on-exit` on a window (§1.5 F3). `on` keeps a focus pane on
+ *  screen after its pi exits — the viewport survives (F1), the final transcript
+ *  is preserved, and `respawn-pane -k` can resurrect the node into the SAME pane
+ *  id. NOTE (§1.5/§2.5, spike-confirmed): a dead/frozen pane is reaped only by
+ *  `kill-pane`/`respawn-pane`, NEVER by toggling this off — the toggle does not
+ *  reap an already-dead pane. Best-effort; never throws. */
+export function setRemainOnExit(window, on) {
+    return tmux(['set-window-option', '-t', window, 'remain-on-exit', on ? 'on' : 'off']).ok;
+}
+/** Type a literal (e.g. a `/graph` slash command) into a pane and press Enter
+ *  (`tmux send-keys -t <pane> '<text>' Enter`). Requires the pane's editor be
+ *  empty, same limitation as the menu's `/promote` item. Best-effort. */
+export function sendKeysEnter(pane, text) {
+    return tmux(['send-keys', '-t', pane, text, 'Enter']).ok;
+}
+// ---------------------------------------------------------------------------
 // Prefix menu — Alt+C opens a which-key-style tmux display-menu of crouter
 // actions. Installed on the running server at root boot; idempotent (a re-bind
 // overwrites the previous one). Items shell out to `crtr`, passing the active
 // pane so an action targets the agent currently in front of you.
 // ---------------------------------------------------------------------------
-/** Bind Alt+C to the crouter action menu. Best-effort; false if tmux fails. */
+/** Reserved mnemonic keys owned by the built-in menu items below — a custom
+ *  `prefixBind` may not claim these (the built-in item wins). */
+const RESERVED_MENU_KEYS = new Set(['o', 'd', 'D', 'x', 'b']);
+/** Bind Alt+C to the crouter action menu. Best-effort; false if tmux fails.
+ *  The built-in items (promote/demote/detach/close/browse) are static; the canvas-nav
+ *  chords (graph/manager/expand/report-N + any custom prefixBind) are appended
+ *  from `canvasNav.prefixBinds`, each routed through `crtr canvas chord` (or, for
+ *  the `__graph__` sentinel, a `send-keys '/graph'`) so the menu stays static
+ *  while behaviour is config-driven. */
 export function installMenuBinding() {
     const sess = nodeSession();
     const title = ' crtr ';
@@ -230,9 +366,46 @@ export function installMenuBinding() {
         // the slash command delivers the orchestration guidance into the node's
         // context, which a bare `run-shell` (output discarded) could not.
         { name: 'promote to orchestrator', key: 'o', cmd: `send-keys -t '#{pane_id}' '/promote' Enter` },
-        { name: 'finish agent + recycle pane', key: 'd', cmd: `run-shell "crtr node demote --pane '#{pane_id}'"` },
-        { name: 'browse background agents', key: 'g', cmd: `switch-client -t ${sess}` },
+        // `d` demotes the agent to TERMINAL in place: no finalize, no kill — it keeps
+        // running where it is, and because it is now terminal it is forced to push a
+        // final up the spine when it finishes. `D` ALSO detaches it to the background
+        // `crtr` session (frees the pane; the pi keeps generating). Neither ends it.
+        { name: 'demote to terminal', key: 'd', cmd: `run-shell "crtr node lifecycle terminal --pane '#{pane_id}' >/dev/null 2>&1"` },
+        { name: 'detach to background', key: 'D', cmd: `run-shell "crtr node lifecycle terminal --pane '#{pane_id}' --detach >/dev/null 2>&1"` },
+        // Close cascades down the subscribes_to spine (kills the subtree's windows,
+        // marks them canceled); revivable. Output discarded — the keypress just acts.
+        { name: 'close agent + subtree', key: 'x', cmd: `run-shell "crtr node close --pane '#{pane_id}' >/dev/null 2>&1"` },
+        // Re-keyed g→b so `g` is free for the canvas-nav GRAPH toggle (below).
+        { name: 'browse background agents', key: 'b', cmd: `switch-client -t ${sess}` },
     ];
+    // Canvas-nav chords from config (default: g→graph, m→manager, e→expand). The
+    // `__graph__` sentinel toggles the in-pi GRAPH modal via send-keys; every
+    // other bind shells the chord dispatcher, which resolves the pane's node and
+    // interpolates the bind at popup time. Keys colliding with the built-ins are
+    // skipped (the built-in wins).
+    let prefixBinds = {};
+    try {
+        prefixBinds = readConfig('user').canvasNav.prefixBinds;
+    }
+    catch { /* defaults below */ }
+    for (const [key, bind] of Object.entries(prefixBinds)) {
+        if (key.length !== 1 || RESERVED_MENU_KEYS.has(key))
+            continue;
+        const name = bind.desc !== undefined && bind.desc !== '' ? bind.desc : `chord ${key}`;
+        const cmd = bind.run === '__graph__'
+            ? `send-keys -t '#{pane_id}' '/graph' Enter`
+            : `run-shell "crtr canvas chord --pane '#{pane_id}' --key ${key} >/dev/null 2>&1"`;
+        items.push({ name, key, cmd });
+    }
+    // Focus report N: nine generated chord items (1..9), each resolved by the
+    // dispatcher to subscriptionsOf(self)[N-1] at popup time.
+    for (let n = 1; n <= 9; n++) {
+        items.push({
+            name: `focus report ${n}`,
+            key: `${n}`,
+            cmd: `run-shell "crtr canvas chord --pane '#{pane_id}' --key ${n} >/dev/null 2>&1"`,
+        });
+    }
     // tmux's -x sets the menu's LEFT edge. To sit the box INSIDE the pane's
     // top-right corner, shift x left by the box width (longest line + tmux chrome:
     // borders + padding + the right-aligned mnemonic-key column) via format math.

package/dist/core/spawn.js

@@ -78,6 +78,21 @@ export function spawnAndDetach(opts) {
         return { status: 'spawn-failed', message: msg };
     }
     const paneId = split.stdout.trim();
+    // Force `remain-on-exit off` at PANE scope on the new pane. remain-on-exit is
+    // a pane option (tmux 3.x) inherited from the window-scoped value, and the
+    // canvas runtime arms `remain-on-exit on` on a node's vehicle/focus WINDOW
+    // (F3 freeze, see runtime/tmux.ts setRemainOnExit). A split-window pane opened
+    // into that window inherits the `on`, so the humanloop TUI pane would linger
+    // as a dead pane ("pane is dead (status 0, …)") when `crtr human _run` exits 0
+    // instead of closing. Overriding at pane scope destroys this pane on clean
+    // exit WITHOUT touching the window's value (focus freeze still works) or the
+    // user's global config. Best-effort: harmless no-op on tmux where the option
+    // is window-only.
+    if (paneId !== '') {
+        spawnSync('tmux', ['set-option', '-p', '-t', paneId, 'remain-on-exit', 'off'], {
+            stdio: 'ignore',
+        });
+    }
     // Schedule self-kill of the originating pane.
     scheduleKillCurrentPane(opts.killAfterSeconds);
     return {

package/dist/daemon/crtrd.d.ts

@@ -1,9 +1,20 @@
+export type LivenessVerdict = 'leave' | 'pending' | 'revive';
+/** 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.
+ *    piPidAlive: true=alive, false=dead, null=no pid recorded (legacy node, or a
+ *      relaunch in flight) — leave those to the pane-gone pass.
+ *    deadFor: ms since first observed dead, or null on the first observation. */
+export declare function livenessVerdict(piPidAlive: boolean | null, deadFor: number | null): LivenessVerdict;
 /** Read the pid stored in the pidfile, or null if absent / malformed. */
 export declare function readPidfile(): number | null;
-/** True if a process with `pid` is currently alive (signal-0 probe). */
+/** 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 declare function isPidAlive(pid: number): boolean;
 /** True when a crtrd process is already running (pidfile exists + pid alive). */
 export declare function isDaemonRunning(): boolean;
+export declare function superviseTick(now?: number): Promise<void>;
 export interface DaemonOpts {
     /** Milliseconds between supervision polls. Default 2000. */
     intervalMs?: number;

package/dist/daemon/crtrd.js

@@ -3,15 +3,18 @@
 // Sole responsibility: supervise tmux window exit and revive nodes. No
 // orchestration logic lives here. The daemon is a process-lifecycle watcher.
 //
-// Model
+// Model (v3: liveness is PANE-existence, not window-existence — a manual
+// move-pane/join-pane/break-pane must never read as a node death)
 //   • Poll every intervalMs (default 2000ms).
-//   • For each active|idle node: check whether its tmux window is still alive.
-//   • Window alive → healthy, skip.
-//   • Window gone + intent==='refresh' → fresh respawn (node asked to yield).
-//   • Window gone + intent==='idle-release' → node freed its own pane while
+//   • For each active|idle 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.
+//   • Pane gone + intent==='refresh' → fresh respawn (node asked to yield).
+//   • Pane gone + intent==='idle-release' → node freed its own pane while
 //     dormant; clear the stale window ref and revive (resume) when its inbox
 //     gains an unseen entry.
-//   • Window gone + any other intent → crash: mark 'dead'.
+//   • Pane gone + any other intent → crash: mark 'dead'.
 //   • Nodes with no tmux placement (inline roots) are skipped.
 //
 // Single-instance guarantee
@@ -21,11 +24,91 @@
 import { writeFileSync, readFileSync, rmSync, existsSync, mkdirSync, } from 'node:fs';
 import { join } from 'node:path';
 import { crtrHome } from '../core/canvas/paths.js';
-import { listNodes, setStatus, getNode, updateNode, } from '../core/canvas/index.js';
-import { windowAlive } from '../core/runtime/tmux.js';
+import { listNodes, getRow, setPresence, getNode, } from '../core/canvas/index.js';
+import { transition } from '../core/runtime/lifecycle.js';
+import { isNodePaneAlive, reconcile } from '../core/runtime/placement.js';
 import { reviveNode } from '../core/runtime/revive.js';
+import { pushUrgent } from '../core/feed/feed.js';
 import { readInboxSince, readCursor } from '../core/feed/inbox.js';
+/** Surface a vehicle that never booted.
+ *
+ *  `spawnChild` returns status="active" the instant the tmux window opens — it
+ *  does NOT wait for pi to come up, because boot is inherently slow (and slower
+ *  under load) and racing it would either block the spawner or false-fail a
+ *  slow-but-healthy launch. The cost of that optimism: a pi that dies before its
+ *  first session_start (so `pi_session_id` was never recorded) is invisible —
+ *  the parent believes its child is running. When the daemon later finds the
+ *  pane gone with no session ever bound, 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`. */
+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 });
+}
 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
+// refresh (reviveInPlace) transiently shows a dead OLD pid for the gap between
+// the old pi dying and the fresh pi booting + re-recording its pid, and we must
+// not double-spawn into that gap.
+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();
+/** 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.
+ *    piPidAlive: true=alive, false=dead, null=no pid recorded (legacy node, or a
+ *      relaunch in flight) — leave those to the pane-gone pass.
+ *    deadFor: ms since first observed dead, or null on the first observation. */
+export function livenessVerdict(piPidAlive, deadFor) {
+    if (piPidAlive !== false)
+        return 'leave';
+    if (deadFor === null || deadFor < REVIVE_GRACE_MS)
+        return 'pending';
+    return 'revive';
+}
+/** A node whose tmux PANE is alive: pane-existence does NOT prove pi is
+ *  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) {
+    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.
+    if (row.intent === 'idle-release') {
+        unhealthySince.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
+        return;
+    }
+    const since = unhealthySince.get(id);
+    const verdict = livenessVerdict(piPidAlive, since === undefined ? null : now - since);
+    if (verdict === 'pending') {
+        if (since === undefined)
+            unhealthySince.set(id, now);
+        return;
+    }
+    // 'revive' — pi has been dead past the grace window while its window lived on.
+    unhealthySince.delete(id);
+    // A refresh-yield wants fresh context (re-read the roadmap); any other death
+    // 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`);
+    reviveNode(id, { resume });
+}
 // ---------------------------------------------------------------------------
 // Pidfile
 // ---------------------------------------------------------------------------
@@ -54,14 +137,16 @@ 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). */
+/** 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 {
-        return false;
+    catch (e) {
+        return e.code === 'EPERM';
     }
 }
 /** True when a crtrd process is already running (pidfile exists + pid alive). */
@@ -72,7 +157,7 @@ export function isDaemonRunning() {
 // ---------------------------------------------------------------------------
 // Supervisor tick
 // ---------------------------------------------------------------------------
-async function superviseTick() {
+export async function superviseTick(now = Date.now()) {
     let rows;
     try {
         rows = listNodes({ status: ['active', 'idle'] });
@@ -83,33 +168,62 @@ async function superviseTick() {
     }
     for (const row of rows) {
         try {
-            // listNodes returns the lightweight NodeRow; we need the full NodeMeta
-            // for tmux_session, window, intent, and pi_session_id.
-            const meta = getNode(row.node_id);
-            if (meta === null)
-                continue; // vanished between list and get
-            // Nodes without tmux placement are inline roots — not daemon-managed.
-            if (meta.tmux_session == null || meta.window == null)
+            // 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.
+            // Nodes with no tmux placement at all are inline roots — not daemon-
+            // managed. Pane-anchored: a node still counts as placed if it has a pane
+            // even when its derived window/session cache is null.
+            if (row.tmux_session == null && row.window == null && row.pane == null)
                 continue;
-            if (windowAlive(meta.tmux_session, meta.window))
-                continue; // healthy
-            // Window is gone. Branch on why.
-            if (meta.intent === 'refresh') {
+            if (isNodePaneAlive(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);
+                continue;
+            }
+            // The pane is gone. Branch on why.
+            unhealthySince.delete(row.node_id); // pane-gone path owns it now
+            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 });
             }
-            else if (meta.intent === 'idle-release') {
+            else if (row.intent === 'idle-release') {
                 // The node freed its own window on purpose while dormant. Drop the stale
                 // window ref and keep it 'idle'; the inbox-poll pass below revives it
                 // (resume) the moment a subscribed worker delivers.
-                updateNode(row.node_id, { window: null });
+                setPresence(row.node_id, { tmux_session: row.tmux_session, window: null });
             }
             else {
-                // Window vanished without the node completing or refreshing — a crash.
-                process.stderr.write(`[crtrd] dead ${row.node_id} (window gone, intent=${String(meta.intent)})\n`);
-                setStatus(row.node_id, 'dead');
+                // The pane vanished without the node completing or refreshing. Split the
+                // two ways that happens: a vehicle that NEVER BOOTED (pi exited before
+                // its first session_start, so pi_session_id is still null) versus a
+                // genuine mid-run CRASH (it had booted, so pi_session_id is set). Both
+                // are dead, but a never-booted node is a spawn failure the parent was
+                // never told about — surface it up the spine instead of dying quietly.
+                transition(row.node_id, 'crash');
+                // Boot-failed vs crashed turns on pi_session_id, an IDENTITY field — the
+                // one place this pass still reads meta. surfaceBootFailure also wants the
+                // full meta (name/kind) for its message.
+                const meta = getNode(row.node_id);
+                if (meta !== null && meta.pi_session_id == null) {
+                    process.stderr.write(`[crtrd] boot-failed ${row.node_id} (pane gone before pi ever started)\n`);
+                    try {
+                        await surfaceBootFailure(meta);
+                    }
+                    catch (err) {
+                        process.stderr.write(`[crtrd] surfaceBootFailure ${row.node_id} error: ${err.message}\n`);
+                    }
+                }
+                else {
+                    process.stderr.write(`[crtrd] dead ${row.node_id} (pane gone, intent=${String(row.intent)})\n`);
+                }
             }
         }
         catch (err) {
@@ -123,15 +237,19 @@ async function superviseTick() {
     // exit; any entry past it is undelivered work — resume the node to handle it.
     for (const row of rows) {
         try {
-            const meta = getNode(row.node_id);
-            if (meta === null)
+            // Re-read the ROW for fresh runtime (the first pass may have mutated it);
+            // no meta needed — status/intent/window/tmux_session all live in the row.
+            const r = getRow(row.node_id);
+            if (r === null)
                 continue;
-            if (meta.status !== 'idle' || meta.intent !== 'idle-release')
+            if (r.status !== 'idle' || r.intent !== 'idle-release')
                 continue;
-            // If a window is somehow alive, the in-process watcher owns delivery.
-            if (meta.window != null && windowAlive(meta.tmux_session ?? '', meta.window)) {
+            // 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).
+            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`);

package/dist/pi-extensions/__tests__/canvas-stophook-agentend.test.d.ts

@@ -0,0 +1 @@
+export {};