@crouton-kit/crouter 0.3.14 → 0.3.16

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;
@@ -28,7 +23,8 @@ export interface OpenWindowOpts {
 }
 /** Open a background window for a node and run `command` in it. `-d` keeps it
  *  detached so it doesn't steal focus or become the current window. Returns the
- *  new window id.
+ *  new window id AND the pane id it created (the durable `%pane_id`, LOCATION's
+ *  anchor) — callers that only need the window destructure `.window`.
  *
  *  Target is `${session}:` (trailing colon = the session, no window index) plus
  *  `-a` (insert after the current window) so tmux allocates the next free index.
@@ -37,12 +33,41 @@ export interface OpenWindowOpts {
  *  "create window failed: index N in use" whenever the active window is not the
  *  last one (common when base-index is 0 but the live window sits at index 1).
  *  `-a` also keeps node windows off index 0, which is reserved for the optional
- *  dashboard. */
-export declare function openNodeWindow(opts: OpenWindowOpts): string | null;
+ *  dashboard. The explicit `-t ${session}:` target is the §2.2 HARD DRIVER
+ *  INVARIANT — never let new-window fall back to tmux's global current session. */
+export declare function openNodeWindow(opts: OpenWindowOpts): {
+    window: string;
+    pane: string;
+} | null;
+export interface SplitWindowOpts {
+    cwd: string;
+    env: Record<string, string>;
+    /** The full command to run in the new pane (already a shell string). */
+    command: string;
+    /** Stack the new pane below instead of beside (default: beside, `-h`). */
+    vertical?: boolean;
+}
+/** Split `targetPane`'s window, opening a NEW pane beside it running `command`,
+ *  and return the new pane id (the durable `%id`). The ONLY new-pane-beside verb
+ *  (Q3: a focus opened side-by-side). `-d` keeps the caller's pane active; `-h`
+ *  makes the split side-by-side (left/right), the default for a focus viewport.
+ *
+ *  §2.2 HARD DRIVER INVARIANT: `targetPane` is REQUIRED — a bare `split-window`
+ *  would split tmux's global current pane, which can leak a pane into an
+ *  unrelated user session (the exact bug this design kills). The explicit
+ *  `-t <targetPane>` makes the destination structurally un-leakable. Returns
+ *  null if tmux fails. */
+export declare function splitWindow(targetPane: string, opts: SplitWindowOpts): string | null;
 /** Bring a node's window forefront. Switches client across roots when needed. */
 export declare function focusWindow(session: string, window: string): boolean;
 /** Close a node's window (drop it from the UI). */
 export declare function closeWindow(window: string): boolean;
+/** Close a single PANE. Its window closes automatically once this was the last
+ *  pane, but sibling panes survive — so co-located nodes (several agents sharing
+ *  one window via swap-pane focus) are torn down one at a time instead of all
+ *  at once by a window kill. Pane ids are the stable vehicle handle; windows
+ *  shift under swap-pane focus, so pane-granular teardown is the correct unit. */
+export declare function closePane(pane: string): boolean;
 /** The active pane id of a window. Node windows are single-pane, so this is the
  *  node's pane. Returns null if the window is gone or tmux fails. */
 export declare function paneOfWindow(session: string, window: string): string | null;
@@ -51,12 +76,35 @@ export declare function paneOfWindow(session: string, window: string): string |
  *  are not, so the node→window mapping must be re-derived from the pane. Returns
  *  null if the pane is gone or tmux fails. */
 export declare function windowOfPane(pane: string): string | null;
-/** The session + window a pane currently lives in. Used by demote to place the
- *  recycled root's meta on the pane it respawns into. Null if tmux fails. */
+/** The session + window a pane currently lives in (`display-message -p -t %id`).
+ *  The §2.4 reconciliation read-back: resolve a node's/focus's CURRENT
+ *  window/session from its durable pane id before any act, so crtr follows a
+ *  manual `move-pane`/`join-pane`/`break-pane` instead of fighting it. Null if
+ *  the pane is gone or tmux fails. */
 export declare function paneLocation(pane: string): {
     session: string;
     window: string;
 } | null;
+/** Does this pane id still exist? A `display-message` probe on the `%id` — the
+ *  v3 PRIMARY liveness probe (§1.2/§2.2), replacing window-existence so a user
+ *  moving a pane to another window/session never reads as "gone". True iff tmux
+ *  knows the pane.
+ *
+ *  NOTE: `display-message -p -t <gone-pane>` EXITS 0 with EMPTY output (it does
+ *  not error on an unresolvable pane target) — so an `.ok` check alone would
+ *  report a dead pane as alive, defeating the whole point of pane-existence
+ *  liveness. We therefore require the echoed `#{pane_id}` to equal the requested
+ *  pane: a live pane echoes its own id, a gone/bogus one yields empty. */
+export declare function paneExists(pane: string): boolean;
+/** Relocate a pane into another session as its own window WITHOUT killing the
+ *  process in it — `break-pane -d` moves the pane out of its current window (the
+ *  pi keeps generating) into a fresh window in `session`; `-d` leaves the caller's
+ *  client where it is rather than following the pane to the background, and `-a`
+ *  allocates the next free window index (same dodge as openNodeWindow). The
+ *  "detach to background" driver behind `node lifecycle --detach`. Best-effort;
+ *  false if tmux refuses (e.g. the pane is gone). The caller reconciles presence
+ *  so the canvas follows the move. */
+export declare function breakPaneToSession(pane: string, session: string): boolean;
 /** Swap `targetPane` into `callerPane`'s layout slot, IN PLACE. `-d` keeps the
  *  caller's window active, so the target's pane appears where the caller is
  *  rather than navigating the client off to the target's window. The caller's
@@ -71,16 +119,34 @@ export interface RespawnPaneOpts {
     /** The full command to run in the pane (already a shell string). */
     command: string;
 }
-/** Re-exec a command in an EXISTING pane, in place. `-k` kills the pane's
- *  current process (e.g. a yielding pi) and starts `command` in the same pane
- *  — the window/pane survives, so an interactive session is never dropped to a
- *  shell and no window churns. Used by refresh-yield.
- *
- *  Spawned DETACHED (own process group, unref'd) so the request reaches the
- *  tmux server even though killing the pane tears down the caller's own pi.
- *  Returns true once the request was dispatched. */
+/** Re-exec a command in an EXISTING pane, in place — DETACHED. Spawned in its own
+ *  process group (unref'd) so the request reaches the tmux server even though
+ *  `-k` tears down the caller's own pi mid-flight. Used when a node respawns ITS
+ *  OWN pane (refresh-yield): the dispatch can't be awaited because it kills the
+ *  awaiter. Returns true once the request was dispatched. */
+export declare function respawnPaneDetached(opts: RespawnPaneOpts): boolean;
+/** Re-exec a command in an EXISTING pane, in place — SYNCHRONOUS. Runs the
+ *  `respawn-pane` to completion and reports the real exit status. Used when the
+ *  caller is NOT the pane being respawned (e.g. the daemon resuming a frozen
+ *  focus pane), so it can confirm the respawn landed. Returns true on success. */
+export declare function respawnPaneSync(opts: RespawnPaneOpts): boolean;
+/** @deprecated Use respawnPaneDetached. Retained so existing refresh-yield
+ *  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
@@ -97,7 +163,34 @@ export declare function selectWindow(session: string, window: string): boolean;
  *  `tmux switch-client -t <session>`. Best-effort; never throws. The caller is
  *  responsible for following up with selectWindow to land on the right window. */
 export declare function switchClient(session: string): boolean;
-/** Bind Alt+C to the crouter action menu. Best-effort; false if tmux fails. */
+/** Move a source pane into a destination window (`tmux join-pane`). The source
+ *  pane's running process (e.g. a child's live pi) is preserved; its now-empty
+ *  source window auto-closes. Best-effort; false if tmux fails. */
+export declare function joinPane(srcPane: string, dstWindow: string): boolean;
+/** Apply a named tmux layout to a window (`tmux select-layout`). Use
+ *  `main-vertical` for one wide pane on the left + the rest stacked right.
+ *  Best-effort; never throws. */
+export declare function selectLayout(window: string, layout: string): boolean;
+/** Set a tmux window option (`tmux set-window-option`). Used to size the main
+ *  pane (`main-pane-width`) before a main-vertical layout. Best-effort. */
+export declare function setWindowOption(window: string, name: string, value: string): boolean;
+/** Toggle `remain-on-exit` on a window (§1.5 F3). `on` keeps a focus pane on
+ *  screen after its pi exits — the viewport survives (F1), the final transcript
+ *  is preserved, and `respawn-pane -k` can resurrect the node into the SAME pane
+ *  id. NOTE (§1.5/§2.5, spike-confirmed): a dead/frozen pane is reaped only by
+ *  `kill-pane`/`respawn-pane`, NEVER by toggling this off — the toggle does not
+ *  reap an already-dead pane. Best-effort; never throws. */
+export declare function setRemainOnExit(window: string, on: boolean): boolean;
+/** Type a literal (e.g. a `/graph` slash command) into a pane and press Enter
+ *  (`tmux send-keys -t <pane> '<text>' Enter`). Requires the pane's editor be
+ *  empty, same limitation as the menu's `/promote` item. Best-effort. */
+export declare function sendKeysEnter(pane: string, text: string): boolean;
+/** Bind Alt+C to the crouter action menu. Best-effort; false if tmux fails.
+ *  The built-in items (promote/demote/detach/close/browse) are static; the canvas-nav
+ *  chords (graph/manager/expand/report-N + any custom prefixBind) are appended
+ *  from `canvasNav.prefixBinds`, each routed through `crtr canvas chord` (or, for
+ *  the `__graph__` sentinel, a `send-keys '/graph'`) so the menu stays static
+ *  while behaviour is config-driven. */
 export declare function installMenuBinding(): boolean;
 /** Bind Alt+] (forward) and Alt+[ (back) to the DFS canvas walk. Best-effort;
  *  false if either bind fails. NOTE: Alt+[ is only delivered cleanly when the

package/dist/core/runtime/tmux.js

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

package/dist/core/spawn.js

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

package/dist/daemon/crtrd.d.ts

@@ -1,9 +1,20 @@
+export type LivenessVerdict = 'leave' | 'pending' | 'revive';
+/** Decide what to do with a node whose tmux pane is alive, from its pi
+ *  liveness and how long it's been dead. Pure — the time-and-tmux side effects
+ *  live in handleLiveWindow; this is the unit-testable core.
+ *    piPidAlive: true=alive, false=dead, null=no pid recorded (legacy node, or a
+ *      relaunch in flight) — leave those to the pane-gone pass.
+ *    deadFor: ms since first observed dead, or null on the first observation. */
+export declare function livenessVerdict(piPidAlive: boolean | null, deadFor: number | null): LivenessVerdict;
 /** Read the pid stored in the pidfile, or null if absent / malformed. */
 export declare function readPidfile(): number | null;
-/** True if a process with `pid` is currently alive (signal-0 probe). */
+/** True if a process with `pid` is currently alive (signal-0 probe). `kill(pid,
+ *  0)` throws ESRCH when the process is gone; EPERM means it exists but isn't
+ *  ours — still alive. */
 export declare function isPidAlive(pid: number): boolean;
 /** True when a crtrd process is already running (pidfile exists + pid alive). */
 export declare function isDaemonRunning(): boolean;
+export declare function superviseTick(now?: number): Promise<void>;
 export interface DaemonOpts {
     /** Milliseconds between supervision polls. Default 2000. */
     intervalMs?: number;