@crouton-kit/crouter 0.3.15 → 0.3.16

package/dist/core/runtime/launch.js

@@ -33,12 +33,14 @@ export const CANVAS_GOAL_CAPTURE_PATH = resolveExtension('canvas-goal-capture');
 export const CANVAS_PASSIVE_CONTEXT_PATH = resolveExtension('canvas-passive-context');
 export const CANVAS_CONTEXT_INTRO_PATH = resolveExtension('canvas-context-intro');
 export const CANVAS_COMMANDS_PATH = resolveExtension('canvas-commands');
+export const CANVAS_RESUME_PATH = resolveExtension('canvas-resume');
 /** The canvas extensions every node loads, in order: stophook (routing +
  *  telemetry + session-id capture), inbox-watcher (wake), nav (in-editor
  *  graph chrome), goal-capture (persist the first user message as the goal),
  *  passive-context (drain passive backlog as pre-text on the next message),
  *  context-intro (inject the <crtr-context> bearings block as its own session
- *  message, once per brand-new chat), commands (the /promote slash-command).
+ *  message, once per brand-new chat), commands (the /promote slash-command),
+ *  resume (the /resume-node whole-canvas picker → `crtr node focus`).
  *  All self-gate on CRTR_NODE_ID. goal-capture precedes passive-context so it
  *  reads the raw user text. */
 export const CANVAS_EXTENSIONS = [
@@ -49,6 +51,7 @@ export const CANVAS_EXTENSIONS = [
     CANVAS_PASSIVE_CONTEXT_PATH,
     CANVAS_CONTEXT_INTRO_PATH,
     CANVAS_COMMANDS_PATH,
+    CANVAS_RESUME_PATH,
 ];
 /** Bare model aliases resolve to the anthropic provider under pi (avoids the
  *  bedrock default). Anything with a `/` or an unknown name passes through. */

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

@@ -1,6 +1,13 @@
 import { type NodeMeta, type Mode, type Lifecycle, type LaunchSpec } from '../canvas/index.js';
 /** Generate a node id in the same shape as job ids (time-sortable + random). */
 export declare function newNodeId(): string;
+/** 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 declare function nodeSession(): string;
 /** Resolve the tmux session a freshly-born node's window/pane opens into — and
  *  thus its durable REVIVE-HOME (`home_session`). Pure so the birth decision is
  *  unit-testable without a live tmux:

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? */
@@ -195,7 +198,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
@@ -209,7 +212,7 @@ export declare function registerRootFocus(nodeId: string, pane: string, session:
  *      (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). */
+ *  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 +221,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 +233,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 +272,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,16 @@
 // 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';
 // 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 +44,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 +277,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;
 }
@@ -369,7 +380,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 +391,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`
@@ -395,7 +405,7 @@ export function registerRootFocus(nodeId, pane, session, window) {
  *      (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). */
+ *  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 +446,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 →
@@ -453,7 +462,6 @@ export function retargetFocus(focusId, incoming, revive) {
     if (action.kind === 'kill')
         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
@@ -490,16 +498,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 +514,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 +559,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 +573,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 +624,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 +637,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 +684,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.js

@@ -19,14 +19,12 @@
 //
 // 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)
@@ -153,7 +151,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' };
     }
@@ -184,7 +181,8 @@ 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 {
@@ -215,8 +213,12 @@ export function relaunchRoot(oldId, pane, deps = {}) {
         //    parent=null, and all edges.
         transition(oldId, 'reap');
         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 +239,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) {

package/dist/core/runtime/spawn.js

@@ -10,15 +10,15 @@
 //                provenance via spawned_by) brought forefront for direct driving.
 import { spawnSync } from 'node:child_process';
 import { FRONT_DOOR_ENV } from './front-door.js';
-import { spawnNode, currentNodeContext, resolveBirthSession } from './nodes.js';
+import { spawnNode, currentNodeContext, resolveBirthSession, nodeSession } from './nodes.js';
 import { buildLaunchSpec, buildPiArgv } from './launch.js';
 import { writeGoal } from './kickoff.js';
 import { hasRoadmap, seedRoadmap } from './roadmap.js';
 import { seedMemory, seedUserMemory, seedProjectMemory } from './memory.js';
 import { generateSessionName } from './naming.js';
-import { ensureSession, openNodeWindow, piCommand, currentTmux, inTmux, nodeSession, focusWindow, installMenuBinding, installNavBindings, } from './tmux.js';
+import { installMenuBinding, installNavBindings } from './tmux-chrome.js';
 import { setPresence, updateNode, getNode, fullName } from '../canvas/index.js';
-import { registerRootFocus } from './placement.js';
+import { registerRootFocus, ensureSession, openNodeWindow, piCommand, currentTmux, inTmux, focusWindow, } from './placement.js';
 import { transition } from './lifecycle.js';
 import { ensureDaemon } from '../../daemon/manage.js';
 /** Create a root node and bring up its pi. Returns the node; for 'inline' this

package/dist/core/runtime/tmux-chrome.d.ts

@@ -0,0 +1 @@
+export { installMenuBinding, installNavBindings, sendKeysEnter } from './tmux.js';

package/dist/core/runtime/tmux-chrome.js

@@ -0,0 +1,4 @@
+// tmux-chrome.ts — chrome seam (§2.1): stateless keybind/input verbs.
+// The ONLY non-placement module allowed to import the tmux driver, per the
+// §5.1 lint. Re-exports the menu/nav/send-keys verbs callers (spawn, chord) need.
+export { installMenuBinding, installNavBindings, sendKeysEnter } from './tmux.js';

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

@@ -1,11 +1,6 @@
 /** POSIX single-quote escaping for one shell word. */
 export declare function shellQuote(s: string): string;
 export declare function inTmux(): boolean;
-/** 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. */
-export declare function nodeSession(): string;
 export interface TmuxLocation {
     session: string;
     window: string;
@@ -139,7 +134,19 @@ export declare function respawnPaneSync(opts: RespawnPaneOpts): boolean;
  *  callers stay green while the placement layer migrates onto the explicit
  *  sync/detached split. */
 export declare function respawnPane(opts: RespawnPaneOpts): boolean;
-/** Turn a pi argv array into a single shell command string. */
+/** Turn a pi argv array into a single shell command string.
+ *
+ *  The binary defaults to `CRTR_PI_BINARY` when that env var is set, else the
+ *  literal `pi`. This is a TEST-ONLY substitution seam: when CRTR_PI_BINARY is
+ *  unset (every production path) the behavior is byte-identical to exec'ing
+ *  `pi`. The integration-test harness points it at a deterministic fake-pi
+ *  vehicle so a real `crtr node new` reaches the fake instead of the LLM `pi`,
+ *  without any dependence on tmux/shell PATH inheritance — the substitution is
+ *  baked into the command string at build time, in the process that calls
+ *  piCommand. An explicit `binary` arg still overrides the env (no caller passes
+ *  one today). The value may be a multi-word launcher (e.g. `node --import
+ *  tsx/esm host.ts`); only the argv entries are shell-quoted, so a multi-word
+ *  binary is spliced verbatim ahead of them. */
 export declare function piCommand(argv: string[], binary?: string): string;
 /** List all window ids present in `session`. Returns [] if the session does
  *  not exist or tmux fails for any reason. Each entry is the raw window id

package/dist/core/runtime/tmux.js

@@ -9,6 +9,7 @@
 // their window; reviving opens a fresh one.
 import { spawn, spawnSync } from 'node:child_process';
 import { readConfig } from '../config.js';
+import { nodeSession } from './nodes.js';
 // ---------------------------------------------------------------------------
 // Shell quoting + tmux invocation
 // ---------------------------------------------------------------------------
@@ -27,14 +28,6 @@ function tmux(args) {
 export function inTmux() {
     return process.env['TMUX'] !== undefined && process.env['TMUX'] !== '';
 }
-/** 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. */
-export function nodeSession() {
-    const v = process.env['CRTR_NODE_SESSION'];
-    return v !== undefined && v !== '' ? v : 'crtr';
-}
 /** Where the caller currently is, or null if not inside tmux. */
 export function currentTmux() {
     if (!inTmux())
@@ -270,8 +263,20 @@ export function respawnPane(opts) {
 // ---------------------------------------------------------------------------
 // pi command assembly
 // ---------------------------------------------------------------------------
-/** Turn a pi argv array into a single shell command string. */
-export function piCommand(argv, binary = 'pi') {
+/** Turn a pi argv array into a single shell command string.
+ *
+ *  The binary defaults to `CRTR_PI_BINARY` when that env var is set, else the
+ *  literal `pi`. This is a TEST-ONLY substitution seam: when CRTR_PI_BINARY is
+ *  unset (every production path) the behavior is byte-identical to exec'ing
+ *  `pi`. The integration-test harness points it at a deterministic fake-pi
+ *  vehicle so a real `crtr node new` reaches the fake instead of the LLM `pi`,
+ *  without any dependence on tmux/shell PATH inheritance — the substitution is
+ *  baked into the command string at build time, in the process that calls
+ *  piCommand. An explicit `binary` arg still overrides the env (no caller passes
+ *  one today). The value may be a multi-word launcher (e.g. `node --import
+ *  tsx/esm host.ts`); only the argv entries are shell-quoted, so a multi-word
+ *  binary is spliced verbatim ahead of them. */
+export function piCommand(argv, binary = process.env['CRTR_PI_BINARY'] ?? 'pi') {
     return [binary, ...argv.map(shellQuote)].join(' ');
 }
 // ---------------------------------------------------------------------------
@@ -295,7 +300,7 @@ export function windowAlive(session, window) {
     return listWindowIds(session).includes(window);
 }
 // ---------------------------------------------------------------------------
-// Focus helpers (used by the presence layer)
+// Focus helpers (used by the placement layer)
 // ---------------------------------------------------------------------------
 /** Activate a window within its session (same-session navigation). Equivalent
  *  to `tmux select-window -t <session>:<window>`. Best-effort; never throws. */
@@ -351,7 +356,7 @@ export function sendKeysEnter(pane, text) {
 // ---------------------------------------------------------------------------
 /** 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']);
+const RESERVED_MENU_KEYS = new Set(['o', 'r', '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
@@ -366,6 +371,10 @@ 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` },
+        // Resume types `/resume-node` into the agent's pane: the slash command opens
+        // a whole-canvas picker (incl. dormant nodes) and revives the choice via
+        // `crtr node focus` — the only sync-safe open (routes through reviveNode).
+        { name: 'resume node', key: 'r', cmd: `send-keys -t '#{pane_id}' '/resume-node' Enter` },
         // `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

package/dist/pi-extensions/canvas-nav.js

@@ -502,11 +502,19 @@ export function registerCanvasNav(pi) {
         // Budget WITHIN pi's widget cap (see graphWidgetBudget): reserve 1 line for
         // the footer hint, up to 2 for the ↑/↓ "more" indicators, the rest for tree
         // rows. The window then tracks the cursor, so j/k scrolls through the WHOLE
-        // list rather than hitting pi's hard truncation. Two passes settle the
-        // mutual dependency between "how many rows fit" and "are indicators shown".
+        // list rather than hitting pi's hard truncation. The passes settle the
+        // mutual dependency between "how many rows fit" and "are indicators shown":
+        // each ↑/↓ indicator steals a tree row, which can push the cursor out of
+        // view, which moves the window, which changes whether an indicator shows.
+        // This needs up to 3 passes to converge (an indicator appearing shrinks the
+        // window, the smaller window re-homes scrollTop, that re-home can toggle the
+        // *other* indicator). Bailing early (the old 2-pass cap) left the cursor one
+        // row off-screen for a single keypress near the bottom — the arrow vanished
+        // and only the NEXT press scrolled. 4 passes always settles to a stable,
+        // cursor-visible window.
         const treeArea = Math.max(2, graphWidgetBudget() - 1);
         let viewportH = treeArea;
-        for (let pass = 0; pass < 2; pass++) {
+        for (let pass = 0; pass < 4; pass++) {
             if (cursorIdx < scrollTop)
                 scrollTop = cursorIdx;
             if (cursorIdx >= scrollTop + viewportH)

package/dist/pi-extensions/canvas-resume.d.ts

@@ -0,0 +1,22 @@
+interface CommandUI {
+    select(title: string, options: string[]): Promise<string | undefined>;
+    notify(message: string, type?: 'info' | 'warning' | 'error'): void;
+}
+interface CommandCtx {
+    mode: string;
+    ui: CommandUI;
+}
+interface PiLike {
+    registerCommand?(name: string, options: {
+        description?: string;
+        handler: (args: string, ctx: CommandCtx) => void | Promise<void>;
+    }): void;
+}
+/**
+ * Register the /resume-node command on `pi`.
+ *
+ * Returns immediately when CRTR_NODE_ID is absent — the extension is fully
+ * inert in a non-canvas pi session.
+ */
+export declare function registerCanvasResume(pi: PiLike): void;
+export default registerCanvasResume;