@crouton-kit/crouter 0.3.15 → 0.3.17

package/dist/core/runtime/nodes.js

@@ -14,11 +14,20 @@
 //             is also recorded.
 import { randomBytes } from 'node:crypto';
 import { createNode, getNode, subscribe, recordSpawn, } from '../canvas/index.js';
-import { nodeSession } from './tmux.js';
 /** Generate a node id in the same shape as job ids (time-sortable + random). */
 export function newNodeId() {
     return `${Date.now().toString(36)}-${randomBytes(4).toString('hex')}`;
 }
+/** The single, shared tmux session that ALL canvas node windows live in.
+ *  Overridable with CRTR_NODE_SESSION (default `crtr`). Every root and every
+ *  child opens a window here rather than cluttering the user's own working
+ *  session — switch to it to browse the whole live graph, ignore it otherwise.
+ *  Pure policy (env only, no tmux call), so it lives in the node layer, not the
+ *  driver; the tmux driver imports it from here for installMenuBinding's use. */
+export function nodeSession() {
+    const v = process.env['CRTR_NODE_SESSION'];
+    return v !== undefined && v !== '' ? v : 'crtr';
+}
 // ---------------------------------------------------------------------------
 // REVIVE-HOME (home_session) — the durable session a node is (re)opened into
 // ---------------------------------------------------------------------------

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

@@ -2,6 +2,9 @@ import { type NodeRow, type FocusRow } from '../canvas/index.js';
 import { homeSessionOf } from './nodes.js';
 export { homeSessionOf };
 export type { FocusRow };
+export { piCommand, paneLocation, currentTmux, inTmux, ensureSession, openNodeWindow, focusWindow, windowAlive, windowOfPane, respawnPane, } from './tmux.js';
+export type { RespawnPaneOpts } from './tmux.js';
+export { nodeSession } from './nodes.js';
 /** The focus a node occupies, or null. UNIQUE(node_id) ⇒ at most one. */
 export declare function focusOf(nodeId: string): FocusRow | null;
 /** Is this node on a viewport? */
@@ -168,16 +171,32 @@ export interface FocusResult {
     revived: boolean;
 }
 /** PURE disposition of a focus's outgoing occupant after a retarget swap (§2.5/
- *  §1.3): a still-generating node moves to backstage (F2); a holder pane or a
- *  done/dormant node has its (now-backstage) pane reaped (Invariant P: a
- *  not-focused + not-generating node has NO pane). Unit-testable in isolation. */
+ *  §1.3). Four signals decide one of three fates; unit-testable in isolation:
+ *    - `kill`     — a holder pane (no row) or a done/dead/canceled node: reap the
+ *                   (now-backstage) pane (Invariant P: not-focused + not-live ⇒
+ *                   no pane).
+ *    - `backstage`— a human-driven RESIDENT node (editor/root/orchestrator — NEVER
+ *                   despawned on focus-away), or a terminal worker that is
+ *                   genuinely MID-TURN (Invariant F2 — keeps running off-screen).
+ *    - `release`  — a PARKED terminal viewer (live but not mid-turn): a node
+ *                   revived only for inspection. Despawn it back to dormant
+ *                   (transition `release` → idle/idle-release) and reap its pane;
+ *                   the daemon revives it on its inbox, or the user re-focuses.
+ *                   This is the bug fix: such a node was misclassified as
+ *                   generating and left stuck active forever.
+ *  Order matters: `resident` is checked BEFORE `generating` so a resident node is
+ *  always kept warm regardless of whether it happens to be mid-turn. */
 export type OutgoingAction = {
     kind: 'backstage';
 } | {
     kind: 'kill';
+} | {
+    kind: 'release';
 };
 export declare function outgoingDisposition(o: {
     exists: boolean;
+    live: boolean;
+    resident: boolean;
     generating: boolean;
 }): OutgoingAction;
 /** Open a NEW viewport (§2.3, F4) — the ONLY path a new pane appears in a user
@@ -195,7 +214,7 @@ export declare function openFocus(callerPane: string, opts?: {
  *  `remain-on-exit` so a clean exit FREEZES the pane rather than detaching the
  *  terminal (F1). A background `--root` does NOT call this (§6): it stays a plain
  *  window until the user `node focus`es it. No-op when the pane or this node is
- *  already a focus. Mirrors focus.ptr via setFocus (the transitional bridge). */
+ *  already a focus. The focus row IS the record — no pointer to mirror. */
 export declare function registerRootFocus(nodeId: string, pane: string, session: string | null, window: string | null): FocusRow | null;
 /** retargetFocus — the unified hot-swap (§2.5, Invariant P + Q5). Swap `incoming`
  *  onto focus `focusId`'s viewport, keeping the screen position invariant (no new
@@ -207,9 +226,10 @@ export declare function registerRootFocus(nodeId: string, pane: string, session:
  *    - `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.
- *  Arms remain-on-exit on the viewport (F3) and mirrors focus.ptr (setFocus). */
+ *    - 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 declare function retargetFocus(focusId: string, incoming: string, revive: Reviver): FocusResult;
 /** The front door for `node focus` / `node cycle` (§2.3): resolve which focus the
  *  caller's pane acts on, then retarget `nodeId` onto it.
@@ -218,8 +238,8 @@ export declare function retargetFocus(focusId: string, incoming: string, revive:
  *    - else → retarget the caller pane's focus IN PLACE (`focusByPane`); if the
  *      caller's pane is not yet a viewport, adopt it as one (occupied by whatever
  *      node sits there now — `callerNode`, else resolved by pane).
- *    - no caller pane (not in tmux) → best-effort: mirror focus.ptr, report
- *      not-in-place. */
+ *    - no caller pane (not in tmux) → best-effort: reconcile + report status,
+ *      not-in-place (no viewport to swap into). */
 export declare function focus(nodeId: string, opts: {
     pane?: string;
     newPane?: boolean;
@@ -230,7 +250,7 @@ export declare function focus(nodeId: string, opts: {
  *  Reconcile first (follow a manual move / backfill a legacy pane), close the
  *  focus row it occupies (if any), kill its pane (pane-keyed via the durable
  *  `%id` — the window collapses once its last pane goes), and null its LOCATION.
- *  Mirrors focus.ptr when this node was the current focus. Best-effort tmux; the
+ *  The focus row close is the record. Best-effort tmux; the
  *  DB writes always land. The pane kill is the sole teardown unit (Q1/§6: a
  *  split-pane focus returns its space to the surviving split; a standalone-window
  *  focus closes the window). */
@@ -269,6 +289,15 @@ export declare function recycleFocusPane(nodeId: string, pane: string, launch: R
  *  manager's old backstage slot; the caller nulls this node's presence so nothing
  *  tracks the corpse. */
 export declare function handFocusToManager(focusId: string, managerId: string | null): boolean;
+/** Q1 close-to-shell for a truly-done focused node with no successor (§1.6 /
+ *  flow (b)): close its focus row and DISARM the pane's
+ *  freeze (`remain-on-exit` off) so it reaps when the finishing pi exits. The
+ *  stophook calls this instead of `tearDownNode` because it runs INSIDE the pane
+ *  it is closing: it cannot `closePane` its own pane (self-saw), but it is still
+ *  alive to disarm the freeze, so the pane closes on exit (return-to-shell)
+ *  rather than freezing into an orphan. (Keeps the stophook off the tmux driver,
+ *  §2.1.) */
+export declare function closeFocusToShell(focusId: string, nodeId: string): void;
 export interface SpreadResult {
     window: string | null;
     session: string | null;

package/dist/core/runtime/placement.js

@@ -1,9 +1,9 @@
 // placement.ts — the Placement MODEL layer (Steps 3–5).
 //
 // Above tmux.ts (the Surface/driver), below the daemon and the runtime ops. This
-// is the first module under the §2.1 rule: "only placement.ts / tmux-chrome.ts
-// import the tmux driver." (The import-lint is warn-only until Step 8, so the
-// other direct importers staying is fine for now.)
+// is the sanctioned model-over-driver under the §2.1 rule: "only placement.ts /
+// tmux-chrome.ts import the tmux driver" (enforced by the §5.1 import-lint). Every
+// other runtime/command module reaches the driver through placement's re-exports.
 //
 // Responsibilities, all keyed on the durable tmux `%pane_id` (§1.2/§2.4, Q6):
 //
@@ -26,14 +26,18 @@
 // 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 { paneExists, paneLocation, paneOfWindow, windowAlive, windowOfPane, ensureSession, openNodeWindow, respawnPaneSync, respawnPaneDetached, breakPaneToSession, nodeSession, splitWindow, swapPaneInPlace, setRemainOnExit, closePane, currentTmux, joinPane, selectLayout, setWindowOption, switchClient, selectWindow, } from './tmux.js';
-import { homeSessionOf, newNodeId } from './nodes.js';
-import { setFocus, getFocus } from './presence.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." Step 1 put the implementation in nodes.ts; the
-// presence.ts→placement.ts consolidation (Steps 6/8) is where it physically
-// moves — until then placement just re-exports it (no churn).
+// "where does this node live."
 export { homeSessionOf };
+// Placement is the sanctioned model-over-driver (§2.1): non-placement runtime /
+// command modules that legitimately need a raw driver verb get it from here, so
+// the §5.1 lint can hold "only placement.ts / tmux-chrome.ts import tmux.ts".
+export { piCommand, paneLocation, currentTmux, inTmux, ensureSession, openNodeWindow, focusWindow, windowAlive, windowOfPane, respawnPane, } from './tmux.js';
+export { nodeSession } from './nodes.js';
 // ---------------------------------------------------------------------------
 // Focus reads (Step 4) — COMPOSE over the canvas focuses table (§2.3/§4).
 //
@@ -42,12 +46,10 @@ export { homeSessionOf };
 // way it composes setPresence. A node occupies at most one focus (UNIQUE
 // node_id, Q5), so focusOf returns a single row.
 //
-// NOTE on openFocus: §2.3/§4 list `openFocus` (split-window + setRemainOnExit +
-// openFocusRow) under Step 4, but it is NOT CALLED until Step 6 (root-boot focus
-// #1 + `node focus --new-pane`). The tmux-composing half is therefore DEFERRED
-// to Step 6; Step 4 ships only the canvas setter `openFocusRow` + these reads +
-// the focus.ptr dual-write bridge (presence.ts). retargetFocus /
-// reviveIntoPlacement are likewise Steps 5/6, not here.
+// The `focuses` table (canvas/focuses.ts) is the CANONICAL focus store — there is
+// no focus.ptr file and no dual-write bridge. openFocus / retargetFocus /
+// registerRootFocus / handFocusToManager write focus rows directly; these reads
+// compose over them.
 // ---------------------------------------------------------------------------
 /** The focus a node occupies, or null. UNIQUE(node_id) ⇒ at most one. */
 export function focusOf(nodeId) {
@@ -277,6 +279,17 @@ export function detachToBackground(nodeId, pane) {
     const session = nodeSession();
     ensureSession(session, row.cwd);
     const ok = breakPaneToSession(target, session);
+    if (ok) {
+        // The node left its viewport for the backstage: it is now generating but
+        // UNFOCUSED (Invariant P / §1.3 "evicted from a focus … generating →
+        // backstage, no focus"). Close any focus row it held so it does not linger
+        // as a phantom viewport — the pane %id survives the break, so the row would
+        // otherwise keep resolving (`focusByPane`/`listFocuses`). A pure detach has
+        // no successor, so it closes the row (cf. `demote`, which hands it off).
+        const f = focusOf(nodeId);
+        if (f !== null)
+            closeFocusRow(f.focus_id);
+    }
     reconcile(nodeId); // presence now points at the crtr window
     return ok;
 }
@@ -303,22 +316,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
@@ -369,7 +397,7 @@ export function openFocus(callerPane, opts = {}) {
  *  `remain-on-exit` so a clean exit FREEZES the pane rather than detaching the
  *  terminal (F1). A background `--root` does NOT call this (§6): it stays a plain
  *  window until the user `node focus`es it. No-op when the pane or this node is
- *  already a focus. Mirrors focus.ptr via setFocus (the transitional bridge). */
+ *  already a focus. The focus row IS the record — no pointer to mirror. */
 export function registerRootFocus(nodeId, pane, session, window) {
     const byPane = getFocusByPane(pane);
     if (byPane !== null)
@@ -380,7 +408,6 @@ export function registerRootFocus(nodeId, pane, session, window) {
     const focusId = newFocusId();
     openFocusRow(focusId, pane, session, nodeId);
     armRemainOnExit(window);
-    setFocus(nodeId);
     return getFocusById(focusId);
 }
 /** retargetFocus — the unified hot-swap (§2.5, Invariant P + Q5). Swap `incoming`
@@ -393,9 +420,10 @@ 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.
- *  Arms remain-on-exit on the viewport (F3) and mirrors focus.ptr (setFocus). */
+ *    - 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);
     if (f === null)
@@ -436,7 +464,6 @@ export function retargetFocus(focusId, incoming, revive) {
         const loc = paneLocation(pin);
         commitFocusTxn(f.focus_id, incoming, pin, loc, outgoing, { kind: 'kill' }, null, null);
         armRemainOnExit(loc?.window);
-        setFocus(incoming);
         return { focused: true, session: loc?.session ?? f.session, inPlace: true, revived };
     }
     // The hot-swap: incoming's pane → the viewport slot; outgoing's pane →
@@ -446,14 +473,25 @@ 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);
-    setFocus(incoming);
     return { focused: true, session: pinLoc?.session ?? f.session, inPlace: true, revived };
 }
 /** The ONE atomic txn (§2.5): point the focus row at `pin`, set its occupant to
@@ -473,6 +511,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 });
             }
         }
@@ -490,16 +529,15 @@ function commitFocusTxn(focusId, incoming, pin, pinLoc, outgoing, action, outLoc
  *    - else → retarget the caller pane's focus IN PLACE (`focusByPane`); if the
  *      caller's pane is not yet a viewport, adopt it as one (occupied by whatever
  *      node sits there now — `callerNode`, else resolved by pane).
- *    - no caller pane (not in tmux) → best-effort: mirror focus.ptr, report
- *      not-in-place. */
+ *    - no caller pane (not in tmux) → best-effort: reconcile + report status,
+ *      not-in-place (no viewport to swap into). */
 export function focus(nodeId, opts) {
     const meta = getNode(nodeId);
     if (meta === null)
         return { focused: false, session: null, inPlace: false, revived: false };
     const callerPane = opts.pane ?? process.env['TMUX_PANE'] ?? currentTmux()?.pane;
     if (callerPane === undefined || callerPane === '') {
-        // Not in tmux — no viewport to swap into. Mirror the pointer; report status.
-        setFocus(nodeId);
+        // Not in tmux — no viewport to swap into. Reconcile and report status.
         reconcile(nodeId);
         return { focused: isNodePaneAlive(nodeId), session: meta.tmux_session ?? null, inPlace: false, revived: false };
     }
@@ -507,13 +545,21 @@ export function focus(nodeId, opts) {
         const opened = openFocus(callerPane, {});
         if (opened === null)
             return { focused: false, session: null, inPlace: false, revived: false };
-        return retargetFocus(opened.focus_id, nodeId, opts.revive);
+        const res = retargetFocus(opened.focus_id, nodeId, opts.revive);
+        // Failed to place the incoming node — reap the just-opened HOLDER pane + its
+        // focus row so a failed `--new-pane` leaves no orphan viewport (F4 / Invariant
+        // P). The success path already reaps the holder via the hot-swap.
+        if (!res.focused) {
+            if (opened.pane !== null)
+                closePane(opened.pane);
+            closeFocusRow(opened.focus_id);
+        }
+        return res;
     }
     let f = focusByPane(callerPane);
     if (f === null)
         f = ensureFocusAtPane(callerPane, opts.callerNode);
     if (f === null) {
-        setFocus(nodeId);
         return { focused: false, session: meta.tmux_session ?? null, inPlace: false, revived: false };
     }
     return retargetFocus(f.focus_id, nodeId, opts.revive);
@@ -544,7 +590,7 @@ function ensureFocusAtPane(pane, callerNode) {
  *  Reconcile first (follow a manual move / backfill a legacy pane), close the
  *  focus row it occupies (if any), kill its pane (pane-keyed via the durable
  *  `%id` — the window collapses once its last pane goes), and null its LOCATION.
- *  Mirrors focus.ptr when this node was the current focus. Best-effort tmux; the
+ *  The focus row close is the record. Best-effort tmux; the
  *  DB writes always land. The pane kill is the sole teardown unit (Q1/§6: a
  *  split-pane focus returns its space to the surviving split; a standalone-window
  *  focus closes the window). */
@@ -558,8 +604,6 @@ export function tearDownNode(nodeId) {
     if (pane !== null && paneExists(pane))
         closePane(pane);
     setPresence(nodeId, { pane: null, tmux_session: null, window: null });
-    if (getFocus() === nodeId)
-        setFocus('');
 }
 /** Demote's in-pane relaunch (§2.3, flow (e)): respawn `nodeId`'s launch into an
  *  EXISTING `pane`, keeping the durable `%id` (respawn-pane -k), and record its
@@ -611,7 +655,6 @@ export function handFocusToManager(focusId, managerId) {
     if (getFocusByNode(managerId) !== null)
         return false; // manager already focused elsewhere
     setFocusOccupant(focusId, managerId);
-    setFocus(managerId);
     // MAJOR 1 — LIVE backstage manager → swap it into the focus slot now. DORMANT
     // managers (no live pane / dead pi) fall through unchanged: the daemon revives
     // them into the frozen %m async.
@@ -625,6 +668,20 @@ export function handFocusToManager(focusId, managerId) {
     }
     return true; // still "took focus" — caller doesn't close
 }
+/** Q1 close-to-shell for a truly-done focused node with no successor (§1.6 /
+ *  flow (b)): close its focus row and DISARM the pane's
+ *  freeze (`remain-on-exit` off) so it reaps when the finishing pi exits. The
+ *  stophook calls this instead of `tearDownNode` because it runs INSIDE the pane
+ *  it is closing: it cannot `closePane` its own pane (self-saw), but it is still
+ *  alive to disarm the freeze, so the pane closes on exit (return-to-shell)
+ *  rather than freezing into an orphan. (Keeps the stophook off the tmux driver,
+ *  §2.1.) */
+export function closeFocusToShell(focusId, nodeId) {
+    closeFocusRow(focusId);
+    const win = getNode(nodeId)?.window;
+    if (win != null && win !== '')
+        setRemainOnExit(win, false);
+}
 /** Join each of `childIds`' live panes into `targetId`'s window, lay them out
  *  (target wide on the left, children stacked right), and focus it. Reconcile
  *  drives both the target resolution and the per-join fix-up (a joined pane keeps
@@ -658,6 +715,5 @@ export function spreadNode(targetId, childIds, opts = {}) {
         selectLayout(targetWindow, 'main-vertical');
     }
     const focused = switchClient(targetSession) && selectWindow(targetSession, targetWindow);
-    setFocus(targetId);
     return { window: targetWindow, session: targetSession, joined, focused };
 }

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,42 +15,44 @@
 // 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';
-import { getNode, updateNode, setPresence, clearPid, subscriptionsOf, unsubscribe, view, reportsDir, inboxPath, nodeDir, openDb, } from '../canvas/index.js';
+import { getNode, updateNode, setPresence, clearPid, setFocusOccupant, subscriptionsOf, unsubscribe, view, reportsDir, inboxPath, nodeDir, openDb, } from '../canvas/index.js';
 import { transition } from './lifecycle.js';
-import { paneLocation, nodeSession } from './tmux.js';
-import { tearDownNode } from './placement.js';
+import { paneLocation, tearDownNode, focusOf } from './placement.js';
 import { buildLaunchSpec } from './launch.js';
 import { roadmapPath } from './roadmap.js';
-import { spawnNode, newNodeId } from './nodes.js';
-import { setFocus } from './presence.js';
+import { spawnNode, newNodeId, nodeSession } from './nodes.js';
 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);
         }
@@ -79,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 = [];
@@ -153,7 +155,6 @@ export function handleNewSession(nodeId, newSessionId, pane, deps = {}, newSessi
         return { path: 'relaunch', newNodeId: result.newNodeId };
     }
     catch {
-        setFocus(nodeId);
         resetRoot(nodeId, newSessionId, newSessionFile);
         return { path: 'reset-root' };
     }
@@ -167,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
@@ -184,11 +185,12 @@ export function relaunchRoot(oldId, pane, deps = {}) {
     // back, leaving the old root EXACTLY as it was (no hand-rolled compensation).
     // Only the *detached* respawn (the async pane kill) lands outside the txn — it
     // must, since it kills this caller, and by then COMMIT has made the new state
-    // durable. setFocus is a file write, not in the txn; the catch restores it.
+    // durable. The focus repoint (step 4) is INSIDE the txn, so a ROLLBACK undoes
+    // it automatically — there is no file to restore.
     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
@@ -210,13 +212,18 @@ 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 (file write — restored by the catch on rollback).
-        setFocus(newId);
+        // 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
+        //    ROLLBACK path restores the old occupant automatically (no file to restore).
+        const oldFocus = focusOf(oldId);
+        if (oldFocus !== null)
+            setFocusOccupant(oldFocus.focus_id, newId);
         // 5) Re-exec pi in this pane bound to newId; the dispatch is the LAST thing
         //    inside the txn. If it throws the txn rolls back (old root untouched); on
         //    success we COMMIT and the async detached kill of this pane lands after.
@@ -237,10 +244,8 @@ export function relaunchRoot(oldId, pane, deps = {}) {
             rmSync(nodeDir(newId), { recursive: true, force: true });
         }
         catch { /* */ }
-        try {
-            setFocus(oldId);
-        }
-        catch { /* */ } // focus is a file op, outside the txn
+        // The focus repoint was inside the txn; ROLLBACK already restored the old
+        // occupant — nothing to undo here.
         throw err instanceof Error ? err : new Error(String(err));
     }
     return { newNodeId: newId };

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

@@ -1,5 +1,5 @@
 import { type NodeMeta } from '../canvas/index.js';
-import { type RespawnPaneOpts } from './tmux.js';
+import { type RespawnPaneOpts } from './placement.js';
 /** Pick the `--session` source for a revive. resume=true prefers the absolute
  *  session-file path (immune to cwd; pi opens it directly) and keeps the bare
  *  session id as the fallback for older nodes booted before pi_session_file was

package/dist/core/runtime/revive.js

@@ -19,8 +19,8 @@ import { transition } from './lifecycle.js';
 import { buildPiArgv } from './launch.js';
 import { buildReviveKickoff, drainBearings } from './kickoff.js';
 import { FRONT_DOOR_ENV } from './front-door.js';
-import { piCommand, respawnPane, nodeSession } from './tmux.js';
-import { reviveIntoPlacement, reconcile, isNodePaneAlive, homeSessionOf } from './placement.js';
+import { reviveIntoPlacement, reconcile, isNodePaneAlive, homeSessionOf, piCommand, respawnPane, } from './placement.js';
+import { nodeSession } from './nodes.js';
 /** signal-0 liveness probe for a pi pid (mirrors the daemon's isPidAlive). A
  *  null pid (legacy / never-booted) reads dead. */
 function pidAlive(pid) {