@crouton-kit/crouter 0.3.13 → 0.3.15

package/dist/core/runtime/tmux.js

@@ -8,6 +8,7 @@
 // root) or switch-client + select-window (across roots). done/dead nodes close
 // their window; reviving opens a fresh one.
 import { spawn, spawnSync } from 'node:child_process';
+import { readConfig } from '../config.js';
 // ---------------------------------------------------------------------------
 // Shell quoting + tmux invocation
 // ---------------------------------------------------------------------------
@@ -69,7 +70,8 @@ function envFlags(env) {
 }
 /** Open a background window for a node and run `command` in it. `-d` keeps it
  *  detached so it doesn't steal focus or become the current window. Returns the
- *  new window id.
+ *  new window id AND the pane id it created (the durable `%pane_id`, LOCATION's
+ *  anchor) — callers that only need the window destructure `.window`.
  *
  *  Target is `${session}:` (trailing colon = the session, no window index) plus
  *  `-a` (insert after the current window) so tmux allocates the next free index.
@@ -78,7 +80,8 @@ function envFlags(env) {
  *  "create window failed: index N in use" whenever the active window is not the
  *  last one (common when base-index is 0 but the live window sits at index 1).
  *  `-a` also keeps node windows off index 0, which is reserved for the optional
- *  dashboard. */
+ *  dashboard. The explicit `-t ${session}:` target is the §2.2 HARD DRIVER
+ *  INVARIANT — never let new-window fall back to tmux's global current session. */
 export function openNodeWindow(opts) {
     const r = tmux([
         'new-window',
@@ -86,7 +89,7 @@ export function openNodeWindow(opts) {
         '-a',
         '-P',
         '-F',
-        '#{window_id}',
+        '#{window_id}\t#{pane_id}',
         '-t',
         `${opts.session}:`,
         '-n',
@@ -96,27 +99,41 @@ export function openNodeWindow(opts) {
         ...envFlags(opts.env),
         opts.command,
     ]);
-    return r.ok ? r.stdout : null;
-}
-/** Open a background window running a plain login shell (no pi) and return its
- *  window + pane ids. Used by demote: the agent's pi is swapped OUT into this
- *  window's slot and the shell is swapped INTO the caller's pane. `-a` keeps it
- *  off index 0 (reserved for a dashboard), `-d` keeps it from stealing focus. */
-export function openShellWindow(opts) {
-    const r = tmux([
-        'new-window', '-d', '-a', '-P',
-        '-F', '#{window_id}\t#{pane_id}',
-        '-t', `${opts.session}:`,
-        '-n', opts.name,
-        '-c', opts.cwd,
-    ]);
     if (!r.ok)
         return null;
     const [window, pane] = r.stdout.split('\t');
-    if (window === undefined || pane === undefined)
+    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) {
     const here = currentTmux();
@@ -131,6 +148,14 @@ export function focusWindow(session, window) {
 export function closeWindow(window) {
     return tmux(['kill-window', '-t', window]).ok;
 }
+/** Close a single PANE. Its window closes automatically once this was the last
+ *  pane, but sibling panes survive — so co-located nodes (several agents sharing
+ *  one window via swap-pane focus) are torn down one at a time instead of all
+ *  at once by a window kill. Pane ids are the stable vehicle handle; windows
+ *  shift under swap-pane focus, so pane-granular teardown is the correct unit. */
+export function closePane(pane) {
+    return tmux(['kill-pane', '-t', pane]).ok;
+}
 /** The active pane id of a window. Node windows are single-pane, so this is the
  *  node's pane. Returns null if the window is gone or tmux fails. */
 export function paneOfWindow(session, window) {
@@ -145,6 +170,45 @@ 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 (`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)
+        return null;
+    const [session, window] = r.stdout.split('\t');
+    if (session === undefined || session === '' || window === undefined || window === '')
+        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
@@ -155,26 +219,34 @@ export function swapPaneInPlace(targetPane, callerPane) {
         return true;
     return tmux(['swap-pane', '-d', '-s', targetPane, '-t', callerPane]).ok;
 }
-/** Re-exec a command in an EXISTING pane, in place. `-k` kills the pane's
- *  current process (e.g. a yielding pi) and starts `command` in the same pane
- *  — the window/pane survives, so an interactive session is never dropped to a
- *  shell and no window churns. Used by refresh-yield.
- *
- *  Spawned DETACHED (own process group, unref'd) so the request reaches the
- *  tmux server even though killing the pane tears down the caller's own pi.
- *  Returns true once the request was dispatched. */
-export function respawnPane(opts) {
+/** The `respawn-pane -k` argv for `opts`. `-k` kills the pane's current process
+ *  (e.g. a yielding pi) and re-execs `command` in the SAME pane, preserving its
+ *  `%id` (§1.5 F3: a frozen focus pane resumes in place, no new window). The
+ *  explicit `-t opts.pane` is the §2.2 HARD DRIVER INVARIANT — respawn must name
+ *  its target pane, never tmux's global current pane. */
+function respawnPaneArgs(opts) {
+    return [
+        'respawn-pane',
+        '-k',
+        '-c',
+        opts.cwd,
+        ...envFlags(opts.env),
+        '-t',
+        opts.pane,
+        opts.command,
+    ];
+}
+/** Re-exec a command in an EXISTING pane, in place — DETACHED. Spawned in its own
+ *  process group (unref'd) so the request reaches the tmux server even though
+ *  `-k` tears down the caller's own pi mid-flight. Used when a node respawns ITS
+ *  OWN pane (refresh-yield): the dispatch can't be awaited because it kills the
+ *  awaiter. Returns true once the request was dispatched. */
+export function respawnPaneDetached(opts) {
     try {
-        const child = spawn('tmux', [
-            'respawn-pane',
-            '-k',
-            '-c',
-            opts.cwd,
-            ...envFlags(opts.env),
-            '-t',
-            opts.pane,
-            opts.command,
-        ], { detached: true, stdio: 'ignore' });
+        const child = spawn('tmux', respawnPaneArgs(opts), {
+            detached: true,
+            stdio: 'ignore',
+        });
         child.unref();
         return true;
     }
@@ -182,6 +254,19 @@ export function respawnPane(opts) {
         return false;
     }
 }
+/** Re-exec a command in an EXISTING pane, in place — SYNCHRONOUS. Runs the
+ *  `respawn-pane` to completion and reports the real exit status. Used when the
+ *  caller is NOT the pane being respawned (e.g. the daemon resuming a frozen
+ *  focus pane), so it can confirm the respawn landed. Returns true on success. */
+export function respawnPaneSync(opts) {
+    return tmux(respawnPaneArgs(opts)).ok;
+}
+/** @deprecated Use respawnPaneDetached. Retained so existing refresh-yield
+ *  callers stay green while the placement layer migrates onto the explicit
+ *  sync/detached split. */
+export function respawnPane(opts) {
+    return respawnPaneDetached(opts);
+}
 // ---------------------------------------------------------------------------
 // pi command assembly
 // ---------------------------------------------------------------------------
@@ -224,21 +309,140 @@ export function switchClient(session) {
     return tmux(['switch-client', '-t', session]).ok;
 }
 // ---------------------------------------------------------------------------
+// Multi-pane layout (used by `canvas tmux-spread`)
+// ---------------------------------------------------------------------------
+/** Move a source pane into a destination window (`tmux join-pane`). The source
+ *  pane's running process (e.g. a child's live pi) is preserved; its now-empty
+ *  source window auto-closes. Best-effort; false if tmux fails. */
+export function joinPane(srcPane, dstWindow) {
+    return tmux(['join-pane', '-s', srcPane, '-t', dstWindow]).ok;
+}
+/** Apply a named tmux layout to a window (`tmux select-layout`). Use
+ *  `main-vertical` for one wide pane on the left + the rest stacked right.
+ *  Best-effort; never throws. */
+export function selectLayout(window, layout) {
+    return tmux(['select-layout', '-t', window, layout]).ok;
+}
+/** Set a tmux window option (`tmux set-window-option`). Used to size the main
+ *  pane (`main-pane-width`) before a main-vertical layout. Best-effort. */
+export function setWindowOption(window, name, value) {
+    return tmux(['set-window-option', '-t', window, name, value]).ok;
+}
+/** Toggle `remain-on-exit` on a window (§1.5 F3). `on` keeps a focus pane on
+ *  screen after its pi exits — the viewport survives (F1), the final transcript
+ *  is preserved, and `respawn-pane -k` can resurrect the node into the SAME pane
+ *  id. NOTE (§1.5/§2.5, spike-confirmed): a dead/frozen pane is reaped only by
+ *  `kill-pane`/`respawn-pane`, NEVER by toggling this off — the toggle does not
+ *  reap an already-dead pane. Best-effort; never throws. */
+export function setRemainOnExit(window, on) {
+    return tmux(['set-window-option', '-t', window, 'remain-on-exit', on ? 'on' : 'off']).ok;
+}
+/** Type a literal (e.g. a `/graph` slash command) into a pane and press Enter
+ *  (`tmux send-keys -t <pane> '<text>' Enter`). Requires the pane's editor be
+ *  empty, same limitation as the menu's `/promote` item. Best-effort. */
+export function sendKeysEnter(pane, text) {
+    return tmux(['send-keys', '-t', pane, text, 'Enter']).ok;
+}
+// ---------------------------------------------------------------------------
 // Prefix menu — Alt+C opens a which-key-style tmux display-menu of crouter
 // actions. Installed on the running server at root boot; idempotent (a re-bind
 // overwrites the previous one). Items shell out to `crtr`, passing the active
 // pane so an action targets the agent currently in front of you.
 // ---------------------------------------------------------------------------
-/** Bind Alt+C to the crouter action menu. Best-effort; false if tmux fails. */
+/** Reserved mnemonic keys owned by the built-in menu items below — a custom
+ *  `prefixBind` may not claim these (the built-in item wins). */
+const RESERVED_MENU_KEYS = new Set(['o', 'd', 'D', 'x', 'b']);
+/** Bind Alt+C to the crouter action menu. Best-effort; false if tmux fails.
+ *  The built-in items (promote/demote/detach/close/browse) are static; the canvas-nav
+ *  chords (graph/manager/expand/report-N + any custom prefixBind) are appended
+ *  from `canvasNav.prefixBinds`, each routed through `crtr canvas chord` (or, for
+ *  the `__graph__` sentinel, a `send-keys '/graph'`) so the menu stays static
+ *  while behaviour is config-driven. */
 export function installMenuBinding() {
     const sess = nodeSession();
-    return tmux([
+    const title = ' crtr ';
+    const items = [
+        // Promote types `/promote` into the agent's pane rather than shelling out:
+        // 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` },
+        // `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.
+    const boxW = Math.max(title.length, ...items.map((i) => i.name.length)) + 6;
+    // Fine-tune nudges off the pane's top-right corner: a hair further left and
+    // one row down so the box doesn't kiss the pane border.
+    const nudgeX = 1; // extra columns left
+    const nudgeY = 3; // rows down
+    const args = [
         'bind-key', '-n', 'M-c', 'display-menu',
-        '-T', '#[align=centre] crtr ',
-        // Anchor to the top-right of the pane it was called from (tmux clamps it
-        // back on-screen) rather than centring on the whole terminal.
-        '-x', '#{pane_right}', '-y', '#{pane_top}',
-        'detach agent \u2192 background', 'd', `run-shell "crtr node demote --pane '#{pane_id}'"`,
-        'browse background agents', 'g', `switch-client -t ${sess}`,
+        '-T', `#[align=centre]${title}`,
+        '-x', `#{e|-:#{pane_right},${boxW + nudgeX}}`,
+        '-y', `#{e|+:#{pane_top},${nudgeY}}`,
+    ];
+    for (const it of items)
+        args.push(it.name, it.key, it.cmd);
+    return tmux(args).ok;
+}
+// ---------------------------------------------------------------------------
+// Nav bindings — Alt+] / Alt+[ DFS-walk the canvas one window at a time. Each
+// key shells out to `crtr node cycle`, passing the active pane so the walk is
+// relative to the agent in front of you; cycle then swaps the next/prev node
+// into that pane (like `node focus`). Output is discarded so the keypress never
+// pops a results view. Installed at root boot alongside the Alt+C menu.
+// ---------------------------------------------------------------------------
+/** 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
+ *  terminal/tmux disambiguate it from a raw CSI introducer (`extended-keys on`).
+ */
+export function installNavBindings() {
+    const next = tmux([
+        'bind-key', '-n', 'M-]', 'run-shell',
+        `crtr node cycle --dir next --pane '#{pane_id}' >/dev/null 2>&1`,
+    ]).ok;
+    const prev = tmux([
+        'bind-key', '-n', 'M-[', 'run-shell',
+        `crtr node cycle --dir prev --pane '#{pane_id}' >/dev/null 2>&1`,
     ]).ok;
+    return next && prev;
 }

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;