@crouton-kit/crouter 0.3.16 → 0.3.18

package/dist/core/runtime/placement.js

@@ -25,9 +25,11 @@
 // The robustness contract: a manual `move-pane`/`join-pane`/`break-pane` must
 // NEVER read as a node death. Liveness is pane-existence, not window-existence,
 // and reconcile makes crtr follow a move instead of fighting it.
-import { getRow, getRowByPane, getNode, setPresence, openDb, openFocusRow, setFocusOccupant, closeFocusRow, getFocusByNode, getFocusByPane, getFocusById, setFocusPane, listFocuses as listFocusRows, } from '../canvas/index.js';
+import { getRow, getRowByPane, getNode, setPresence, openDb, openFocusRow, setFocusOccupant, closeFocusRow, getFocusByNode, getFocusByPane, getFocusById, setFocusPane, listFocuses as listFocusRows, view, } from '../canvas/index.js';
 import { paneExists, paneLocation, paneOfWindow, windowAlive, windowOfPane, ensureSession, openNodeWindow, respawnPaneSync, respawnPaneDetached, breakPaneToSession, splitWindow, swapPaneInPlace, setRemainOnExit, closePane, currentTmux, joinPane, selectLayout, setWindowOption, switchClient, selectWindow, } from './tmux.js';
 import { homeSessionOf, nodeSession, newNodeId } from './nodes.js';
+import { isBusy } from './busy.js';
+import { transition } from './lifecycle.js';
 // Re-export the durable REVIVE-HOME read so placement is the one front door for
 // "where does this node live."
 export { homeSessionOf };
@@ -69,6 +71,42 @@ export function focusedNodes() {
 export function listFocuses() {
     return listFocusRows();
 }
+// ---------------------------------------------------------------------------
+// Graph → focus routing (for surfacing human-in-the-loop prompts)
+// ---------------------------------------------------------------------------
+/** The root of a node's spine: walk the `parent` column up to `parent == null`.
+ *  Cycle-guarded (parents must not cycle, but never loop forever). */
+function rootOfSpine(nodeId) {
+    let cur = nodeId;
+    const seen = new Set();
+    for (;;) {
+        if (seen.has(cur))
+            return cur;
+        seen.add(cur);
+        const row = getRow(cur);
+        if (row === null || row.parent == null)
+            return cur;
+        cur = row.parent;
+    }
+}
+/** The on-screen viewport a human-in-the-loop prompt raised by `nodeId` should
+ *  surface into: the HIGHEST FOCUSED node of nodeId's graph — the focused node
+ *  closest to the graph root, i.e. the session/window the user is actually
+ *  watching this work in. Walks nodeId's spine to its root, enumerates the whole
+ *  tree root-first (`view` is BFS ⇒ shallowest first), and returns the focus row
+ *  of the first node that occupies a viewport. null when nothing in the graph is
+ *  on screen — the caller then surfaces in the user's attached pane rather than
+ *  the backstage node session. PURE (db reads only): no tmux probe, so the pane
+ *  may be stale; the caller liveness-checks before targeting it. */
+export function graphSurfaceTarget(nodeId) {
+    const root = rootOfSpine(nodeId);
+    for (const id of [root, ...view(root)]) {
+        const f = getFocusByNode(id);
+        if (f !== null && f.pane !== null)
+            return f;
+    }
+    return null;
+}
 /** PURE reconciliation decision (§2.4) — unit-testable without a live tmux.
  *  Given the cached row LOCATION and what tmux currently reports, decide the
  *  presence patch. Mirrors the pure-core/impure-shell split (cf. `livenessVerdict`
@@ -314,22 +352,37 @@ function pidAlive(pid) {
         return e.code === 'EPERM';
     }
 }
-/** Is a focus's OUTGOING occupant still GENERATING (a live pi doing work)? A
- *  still-generating node is moved to backstage by a retarget (F2 — it keeps
- *  running off-screen); a holder / done / dormant node has its pane reaped
- *  (Invariant P). A holder or vanished node (row null) is never generating. */
+/** Is a focus's OUTGOING occupant still GENERATING (a live pi actually MID-TURN)?
+ *  A still-generating node is moved to backstage by a retarget (F2 — it keeps
+ *  running off-screen); a holder / done / dormant / merely-parked node has its
+ *  pane reaped or released (Invariant P). A holder or vanished node (row null) is
+ *  never generating.
+ *
+ *  The signal is the mid-turn `busy` marker AND a live pid — NOT pid-alive
+ *  alone. A node revived only for VIEWING is parked at its prompt with a live
+ *  pid between turns; pid-alive would misclassify it as "doing work" and leave
+ *  it stuck backstaged-active forever. `isBusy` is true only inside a turn, so a
+ *  parked viewer reads as not-generating and is released to dormant on
+ *  focus-away. The AND with `pidAlive` makes a stale marker (a pi that crashed
+ *  mid-turn) harmless. */
 function isGenerating(nodeId) {
     const row = getRow(nodeId);
     if (row === null)
         return false;
     if (row.status !== 'active' && row.status !== 'idle')
         return false;
-    return pidAlive(row.pi_pid);
+    return isBusy(nodeId) && pidAlive(row.pi_pid);
 }
 export function outgoingDisposition(o) {
     if (!o.exists)
-        return { kind: 'kill' };
-    return o.generating ? { kind: 'backstage' } : { kind: 'kill' };
+        return { kind: 'kill' }; // holder pane
+    if (!o.live)
+        return { kind: 'kill' }; // done/dead/canceled — reap the pane
+    if (o.resident)
+        return { kind: 'backstage' }; // human-driven node: keep warm
+    if (o.generating)
+        return { kind: 'backstage' }; // mid-turn terminal worker (F2)
+    return { kind: 'release' }; // parked terminal viewer → dormant
 }
 /** The node's pane iff it is a LIVE pane (a generating-unfocused backstage pane,
  *  or a still-live focus pane), else null. The retarget swaps THIS pane into the
@@ -403,8 +456,9 @@ export function registerRootFocus(nodeId, pane, session, window) {
  *    - `swapPaneInPlace(pin, focusPane)`: incoming → the viewport slot; the
  *      outgoing occupant → incoming's old (backstage) slot, %ids preserved
  *      (cross-session swap confirmed by the spike).
- *    - outgoing still generating → backstage (F2); else reap its now-backstage
- *      pane (Invariant P). A holder occupant (no node row) is always reaped.
+ *    - outgoing resident OR still mid-turn → backstage (kept warm / F2); a parked
+ *      terminal viewer → RELEASE (status → idle, pane reaped); a holder or
+ *      done/dormant occupant → reap its now-backstage pane (Invariant P).
  *  Arms remain-on-exit on the viewport (F3); the focus row is the record. */
 export function retargetFocus(focusId, incoming, revive) {
     let f = getFocusById(focusId);
@@ -455,11 +509,23 @@ export function retargetFocus(focusId, incoming, revive) {
     }
     const pinLoc = paneLocation(pin); // now the viewport
     const outLoc = paneLocation(focusPane); // now backstage (outgoing's new home)
-    const action = outgoingDisposition({ exists: getRow(outgoing) !== null, generating: isGenerating(outgoing) });
+    const oRow = getRow(outgoing);
+    const action = outgoingDisposition({
+        exists: oRow !== null,
+        live: oRow?.status === 'active' || oRow?.status === 'idle',
+        resident: oRow?.lifecycle === 'resident',
+        generating: isGenerating(outgoing),
+    });
     commitFocusTxn(f.focus_id, incoming, pin, pinLoc, outgoing, action, outLoc, focusPane);
-    // Reap the outgoing/holder pane (now backstage) when not generating — AFTER
-    // commit (a tmux side effect, outside the txn).
-    if (action.kind === 'kill')
+    // Crash-safety: flip a released (parked terminal viewer) node to dormant
+    // (idle + intent='idle-release') BEFORE reaping its pane, so the daemon never
+    // sees a window-gone live node and races to revive it. Then reap the
+    // outgoing/holder pane (now backstage) for both kill (done/dormant/holder) and
+    // release (parked viewer) — AFTER commit (a tmux side effect, outside the txn).
+    // A still-generating worker or a resident node is backstaged, untouched here.
+    if (action.kind === 'release')
+        transition(outgoing, 'release');
+    if (action.kind === 'kill' || action.kind === 'release')
         closePane(focusPane);
     armRemainOnExit(pinLoc?.window);
     return { focused: true, session: pinLoc?.session ?? f.session, inPlace: true, revived };
@@ -481,6 +547,7 @@ function commitFocusTxn(focusId, incoming, pin, pinLoc, outgoing, action, outLoc
                 setPresence(outgoing, { pane: outgoingPane, tmux_session: outLoc?.session ?? null, window: outLoc?.window ?? null });
             }
             else {
+                // kill | release — the pane is reaped by the caller; null the LOCATION.
                 setPresence(outgoing, { pane: null, tmux_session: null, window: null });
             }
         }

package/dist/core/runtime/reset.d.ts

@@ -1,16 +1,19 @@
-/** Reap the descendant sub-DAG of `rootId`: mark each **done** (the user moved
- *  on — a clean teardown, NOT a fault) + clear intent FIRST, then kill its
+/** Reap the descendant sub-DAG of `rootId`: mark each **canceled** (the user
+ *  moved on — a clean teardown, NOT a fault) + clear intent FIRST, then kill its
  *  window (closes the daemon revive race). Edges are LEFT INTACT — descendants
  *  keep parent=rootId. No wipe. Returns the reaped ids.
  *
- *  Why `done`, and why marking is STILL explicit: a `closeWindow`/`respawn-pane
- *  -k` kill is abrupt and fires NO clean `session_shutdown`, so the general
- *  quit→done rule does NOT auto-resolve a force-killed descendant — we mark it
- *  `done` here. Shared by relaunchRoot (option C) and resetRoot's in-place
- *  fallback, so both leave their descendants `done`. */
+ *  Why `canceled` (A5, human-confirmed 2026-06-06): an externally-reaped node —
+ *  whether via `node close` OR a root reset/relaunch — did not finish its OWN
+ *  work, so it unifies on `canceled`; `done` is reserved for finalize. Why
+ *  marking is STILL explicit: a `closeWindow`/`respawn-pane -k` kill is abrupt
+ *  and fires NO clean `session_shutdown`, so the general quit→done rule does NOT
+ *  auto-resolve a force-killed descendant — we mark it `canceled` here via the
+ *  same `cancel` event the close cascade uses. Shared by relaunchRoot (option C)
+ *  and resetRoot's in-place fallback, so both leave their descendants `canceled`. */
 export declare function reapDescendants(rootId: string): string[];
 export interface ResetRootResult {
-    /** Descendant node ids torn down (window killed + marked done). */
+    /** Descendant node ids torn down (window killed + marked canceled). */
     reaped: string[];
     /** Direct subscriptions dropped off the root. */
     detached: string[];

package/dist/core/runtime/reset.js

@@ -6,7 +6,7 @@
 // behave like re-running `crtr` we have two strategies:
 //
 //   • relaunchRoot (option C) — for a ROOT in a tmux pane: PARK the old root
-//     (mark done, keep its id/edges/pi_session_id intact as history), mint a
+//     (mark canceled, keep its id/edges/pi_session_id intact as history), mint a
 //     FRESH node id, and re-exec pi in the current pane bound to the new id.
 //     The old id never changes meaning; external refs stay valid.
 //   • resetRoot (fallback) — for a non-root child (session-id refresh only) or
@@ -15,7 +15,8 @@
 // Termination semantics: a pi that ends cleanly resolves its node to `done`
 // (markCleanExitDone); only a true crash leaves it `dead`. A force-kill
 // (closeWindow / respawn-pane -k) fires NO clean session_shutdown, so reaped
-// descendants are marked `done` explicitly here.
+// descendants are marked `canceled` explicitly here (A5: an externally-reaped
+// node did not finish its own work — done is reserved for finalize).
 //
 // Best-effort throughout: a tmux/fs failure on one node never aborts the reset.
 import { existsSync, rmSync } from 'node:fs';
@@ -29,26 +30,29 @@ import { relaunchRootInPane } from './revive.js';
 // ---------------------------------------------------------------------------
 // reapDescendants — tear down a root's descendant sub-DAG (shared helper)
 // ---------------------------------------------------------------------------
-/** Reap the descendant sub-DAG of `rootId`: mark each **done** (the user moved
- *  on — a clean teardown, NOT a fault) + clear intent FIRST, then kill its
+/** Reap the descendant sub-DAG of `rootId`: mark each **canceled** (the user
+ *  moved on — a clean teardown, NOT a fault) + clear intent FIRST, then kill its
  *  window (closes the daemon revive race). Edges are LEFT INTACT — descendants
  *  keep parent=rootId. No wipe. Returns the reaped ids.
  *
- *  Why `done`, and why marking is STILL explicit: a `closeWindow`/`respawn-pane
- *  -k` kill is abrupt and fires NO clean `session_shutdown`, so the general
- *  quit→done rule does NOT auto-resolve a force-killed descendant — we mark it
- *  `done` here. Shared by relaunchRoot (option C) and resetRoot's in-place
- *  fallback, so both leave their descendants `done`. */
+ *  Why `canceled` (A5, human-confirmed 2026-06-06): an externally-reaped node —
+ *  whether via `node close` OR a root reset/relaunch — did not finish its OWN
+ *  work, so it unifies on `canceled`; `done` is reserved for finalize. Why
+ *  marking is STILL explicit: a `closeWindow`/`respawn-pane -k` kill is abrupt
+ *  and fires NO clean `session_shutdown`, so the general quit→done rule does NOT
+ *  auto-resolve a force-killed descendant — we mark it `canceled` here via the
+ *  same `cancel` event the close cascade uses. Shared by relaunchRoot (option C)
+ *  and resetRoot's in-place fallback, so both leave their descendants `canceled`. */
 export function reapDescendants(rootId) {
     const reaped = [];
     for (const id of view(rootId)) {
         try {
             // Reap BEFORE tearing down the placement (the crash-safety invariant the
-            // `reap` event encodes): a non-supervised status + cleared intent first, so
+            // `cancel` event encodes): a non-supervised status + cleared intent first, so
             // the daemon can't revive a descendant mid-teardown. tearDownNode then
             // closes any focus row it held, kills its pane (pane-keyed), and nulls its
             // LOCATION.
-            transition(id, 'reap');
+            transition(id, 'cancel');
             tearDownNode(id);
             reaped.push(id);
         }
@@ -77,7 +81,7 @@ export function resetRoot(nodeId, newSessionId, newSessionFile) {
         }
         return { reaped: [], detached: [], reset: false };
     }
-    // 1) Reap the descendant sub-DAG (mark done + kill windows; shared helper).
+    // 1) Reap the descendant sub-DAG (mark canceled + kill windows; shared helper).
     const reaped = reapDescendants(nodeId);
     // 2) Detach the root's own subscriptions so its view is empty.
     const detached = [];
@@ -164,7 +168,7 @@ export function relaunchRoot(oldId, pane, deps = {}) {
     const oldMeta = getNode(oldId);
     if (oldMeta === null || oldMeta.parent != null)
         return null; // defensive: not a root
-    if (oldMeta.status === 'done')
+    if (oldMeta.status === 'canceled')
         return null; // defensive: already parked (rapid double /new)
     const respawn = deps.relaunchRootInPane ?? relaunchRootInPane;
     // Resolve where the new pi will live (pane authoritative; fall back to old
@@ -186,7 +190,7 @@ export function relaunchRoot(oldId, pane, deps = {}) {
     const db = openDb();
     db.exec('BEGIN');
     try {
-        // 1) Reap descendants (mark done + kill windows, keep edges, no wipe).
+        // 1) Reap descendants (mark canceled + kill windows, keep edges, no wipe).
         reapDescendants(oldId);
         // 2) Create the fresh root node (new id, empty context dir via
         //    ensureNodeDirs) seeded active; `yield` adds the refresh safety net so
@@ -208,10 +212,11 @@ export function relaunchRoot(oldId, pane, deps = {}) {
         // of the pane it is respawned into (same pane-recycle rule as demote).
         updateNode(newId, { home_session: loc.session ?? nodeSession() });
         clearPid(newId); // no pi yet → daemon 'leave' until boot records the pid
-        // 3) Park the old root: reap (done + intent cleared) and detach its window so
-        //    it never claims the pane, but KEEP pi_session_id (resumable),
-        //    parent=null, and all edges.
-        transition(oldId, 'reap');
+        // 3) Park the old root: cancel (canceled + intent cleared) and detach its
+        //    window so it never claims the pane, but KEEP pi_session_id (resumable),
+        //    parent=null, and all edges. A5: a superseded old root did not finish its
+        //    own work — it unifies on `canceled` like every other external reap.
+        transition(oldId, 'cancel');
         setPresence(oldId, { window: null, tmux_session: null });
         // 4) Focus follows content: repoint the old root's focus row to the new root
         //    (same pane — respawn-pane -k below keeps the %id). Inside the txn → the

package/dist/core/spawn.d.ts

@@ -1,7 +1,21 @@
 export declare function isInTmux(): boolean;
 export declare function shellQuote(s: string): string;
-/** Count panes in the current tmux window (0 outside tmux / on error). */
+/** Count panes in a tmux window (0 outside tmux / on error). With `targetPane`,
+ *  counts the window THAT pane lives in (the placement decision must reflect the
+ *  window the new pane will actually open into, not the caller's backstage one);
+ *  without it, the caller's current window. */
+export declare function countPanesInWindow(targetPane?: string): number;
+/** Back-compat alias: panes in the caller's current window. */
 export declare function countPanesInCurrentWindow(): number;
+/** Does this tmux pane id still exist? `display-message` EXITS 0 with EMPTY
+ *  output on an unresolvable pane, so test for non-empty stdout, not just `.ok`.
+ *  False outside tmux / on error. */
+export declare function paneAlive(pane: string): boolean;
+/** The active pane of the user's attached tmux client — where they are looking
+ *  right now. `list-clients` first attached client, then its current pane. Used
+ *  to surface a human prompt in the user's view when nothing in the asking
+ *  node's graph is focused. null outside tmux / no client / on error. */
+export declare function attachedClientPane(): string | null;
 /**
  * Schedule a kill-pane on the *current* tmux pane after `delaySeconds`, detached
  * so the caller can return normally before the pane dies. No-op outside tmux,
@@ -23,6 +37,11 @@ export interface DetachOptions {
      *  uses the attached client's currently-focused pane — which drifts if the
      *  user switches windows between kickoff and spawn. */
     targetPane?: string;
+    /** Pass tmux `-d` to new-window so CREATING the window never switches the
+     *  attached client to it (split-window already leaves the client's view put).
+     *  The prompt lands in the target session/window without jumping the user out
+     *  of what they are looking at. No effect on split-h/split-v. */
+    detached?: boolean;
 }
 export interface DetachResult {
     status: 'spawned' | 'spawn-failed' | 'not-in-tmux';

package/dist/core/spawn.js

@@ -13,15 +13,60 @@ export function isInTmux() {
 export function shellQuote(s) {
     return `'${s.replace(/'/g, "'\\''")}'`;
 }
-/** Count panes in the current tmux window (0 outside tmux / on error). */
-export function countPanesInCurrentWindow() {
-    const result = spawnSync('tmux', ['list-panes', '-F', '#{pane_id}'], {
-        encoding: 'utf8',
-    });
+/** Count panes in a tmux window (0 outside tmux / on error). With `targetPane`,
+ *  counts the window THAT pane lives in (the placement decision must reflect the
+ *  window the new pane will actually open into, not the caller's backstage one);
+ *  without it, the caller's current window. */
+export function countPanesInWindow(targetPane) {
+    const args = targetPane !== undefined && targetPane !== ''
+        ? ['list-panes', '-t', targetPane, '-F', '#{pane_id}']
+        : ['list-panes', '-F', '#{pane_id}'];
+    const result = spawnSync('tmux', args, { encoding: 'utf8' });
     if (result.status !== 0)
         return 0;
     return result.stdout.split('\n').filter((line) => line.trim() !== '').length;
 }
+/** Back-compat alias: panes in the caller's current window. */
+export function countPanesInCurrentWindow() {
+    return countPanesInWindow();
+}
+/** Does this tmux pane id still exist? `display-message` EXITS 0 with EMPTY
+ *  output on an unresolvable pane, so test for non-empty stdout, not just `.ok`.
+ *  False outside tmux / on error. */
+export function paneAlive(pane) {
+    if (!isInTmux() || !/^%\d+$/.test(pane))
+        return false;
+    const r = spawnSync('tmux', ['display-message', '-p', '-t', pane, '#{pane_id}'], {
+        encoding: 'utf8',
+    });
+    return r.status === 0 && r.stdout.trim() !== '';
+}
+/** The active pane of the user's attached tmux client — where they are looking
+ *  right now. `list-clients` first attached client, then its current pane. Used
+ *  to surface a human prompt in the user's view when nothing in the asking
+ *  node's graph is focused. null outside tmux / no client / on error. */
+export function attachedClientPane() {
+    if (!isInTmux())
+        return null;
+    const clients = spawnSync('tmux', ['list-clients', '-F', '#{client_name}'], {
+        encoding: 'utf8',
+    });
+    if (clients.status !== 0)
+        return null;
+    const name = clients.stdout
+        .split('\n')
+        .map((l) => l.trim())
+        .find((l) => l !== '');
+    if (name === undefined)
+        return null;
+    const pane = spawnSync('tmux', ['display-message', '-p', '-c', name, '#{pane_id}'], {
+        encoding: 'utf8',
+    });
+    if (pane.status !== 0)
+        return null;
+    const id = pane.stdout.trim();
+    return id !== '' ? id : null;
+}
 /**
  * Schedule a kill-pane on the *current* tmux pane after `delaySeconds`, detached
  * so the caller can return normally before the pane dies. No-op outside tmux,
@@ -53,6 +98,8 @@ export function spawnAndDetach(opts) {
     const splitArgs = [];
     if (opts.placement === 'new-window') {
         splitArgs.push('new-window');
+        if (opts.detached === true)
+            splitArgs.push('-d'); // don't switch the client to it
         if (opts.targetPane !== undefined && opts.targetPane !== '') {
             // -a = insert after target window; -t <pane> resolves to that pane's window.
             splitArgs.push('-a', '-t', opts.targetPane);

package/dist/daemon/crtrd.js

@@ -14,7 +14,11 @@
 //   • 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.
-//   • Pane gone + any other intent → crash: mark 'dead'.
+//   • Pane gone + any other intent → route on what the node was doing:
+//       - never-booted (pi_session_id null) → crash ('dead') + surface boot fail
+//       - mid-generation (busy marker present) → crash ('dead')
+//       - finished its turn, still awaiting a live child → crash ('dead'), for now
+//       - finished its turn, awaiting nothing live → finalize ('done')
 //   • Nodes with no tmux placement (inline roots) are skipped.
 //
 // Single-instance guarantee
@@ -24,8 +28,9 @@
 import { writeFileSync, readFileSync, rmSync, existsSync, mkdirSync, } from 'node:fs';
 import { join } from 'node:path';
 import { crtrHome } from '../core/canvas/paths.js';
-import { listNodes, getRow, setPresence, getNode, } from '../core/canvas/index.js';
+import { listNodes, getRow, setPresence, getNode, hasActiveLiveSubscription, } 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 { reviveNode } from '../core/runtime/revive.js';
 import { pushUrgent } from '../core/feed/feed.js';
@@ -201,28 +206,45 @@ 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 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.
+                // 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:
+                //   • 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
+                //     on pi_session_id, an IDENTITY field — the one place this pass still
+                //     reads meta; surfaceBootFailure also wants name/kind for its message.)
+                //   • MID-GENERATION (busy marker present) → crash (→dead). agent_start
+                //     touched the marker and agent_end never cleared it ⇒ the pane was
+                //     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.
                 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`);
-                    }
+                const neverBooted = meta !== null && meta.pi_session_id == null;
+                if (!neverBooted &&
+                    !isBusy(row.node_id) &&
+                    !hasActiveLiveSubscription(row.node_id)) {
+                    transition(row.node_id, 'finalize');
+                    process.stderr.write(`[crtrd] done ${row.node_id} (pane gone after turn end, no live child)\n`);
                 }
                 else {
-                    process.stderr.write(`[crtrd] dead ${row.node_id} (pane gone, intent=${String(row.intent)})\n`);
+                    transition(row.node_id, 'crash');
+                    if (neverBooted) {
+                        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`);
+                    }
                 }
             }
         }