@north-light/api 0.3.580 → 0.3.587

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

@@ -0,0 +1,713 @@
+// tmux driver — low-level tmux invocation, pane/window placement, and viewer state.
+//
+// This module owns the raw tmux process boundary. Higher-level binding
+// reconciliation lives in tmux-bindings.ts; placement remains the sanctioned
+// runtime facade for consumers that need these verbs.
+import { execFile, spawnSync } from 'node:child_process';
+import { encodeAttachControlInput, } from '../keybindings/index.js';
+import { listProcessTable } from '../canvas/pid.js';
+import { bundledPiCommandForShell } from './pi-cli.js';
+import { shellQuote } from '../../shared/shell-quote.js';
+import { envPiBinaryOverride } from '../../shared/env.js';
+// tmux invocation
+export { shellQuote };
+/** Longest a tmux subprocess may run. A hung tmux server otherwise blocks the caller (and, in the daemon, its event loop) forever. */
+const TMUX_TIMEOUT_MS = 5000;
+function tmux(args) {
+    const r = spawnSync('tmux', args, { encoding: 'utf8', timeout: TMUX_TIMEOUT_MS, killSignal: 'SIGKILL' });
+    return {
+        timedOut: r.error?.code === 'ETIMEDOUT',
+        ok: r.status === 0,
+        stdout: (r.stdout ?? '').trim(),
+        stderr: (r.stderr ?? '').trim(),
+    };
+}
+function tmuxOnSocket(socket, args) {
+    return socket === undefined || socket === '' ? tmux(args) : tmux(['-S', socket, ...args]);
+}
+export function inTmux() {
+    return process.env['TMUX'] !== undefined && process.env['TMUX'] !== '';
+}
+/** Is any tmux SESSION currently up? `tmux list-sessions` exits 0 iff a server
+ *  is running with at least one session, non-zero otherwise (including "no
+ *  server"). This is the boot-time/bash-tooling probe — distinct from
+ *  `tmuxClientsReachable`, which asks whether a server is reachable at all
+ *  regardless of session count and is the human-surface gate. */
+export function tmuxSessionsReachable() {
+    return spawnSync('tmux', ['list-sessions'], { encoding: 'utf8', stdio: 'ignore', timeout: TMUX_TIMEOUT_MS, killSignal: 'SIGKILL' }).status === 0;
+}
+/** Is the tmux SERVER reachable at all? `tmux list-clients` exits 0 whenever a
+ *  server is up (even with zero attached clients), non-zero when no server is
+ *  running. This is the human-surface gate (core/spawn.ts's
+ *  `tmuxServerReachable`) — distinct from `tmuxSessionsReachable`, which
+ *  additionally requires a session to exist. */
+export function tmuxClientsReachable() {
+    return spawnSync('tmux', ['list-clients', '-F', '#{client_name}'], { encoding: 'utf8', timeout: TMUX_TIMEOUT_MS, killSignal: 'SIGKILL' }).status === 0;
+}
+/** The pane currently displaying `nodeId`, found by the authoritative `@crtr_node`
+ *  pane tag — set by EVERY viewer (a bare `surface attach`, a focus split, a
+ *  spawned viewer) on connect. Scans all panes (`list-panes -a`); the reverse of
+ *  `nodeInPane`. Unlike the focus TABLE (which only `registerViewerFocus` writes,
+ *  so it misses attach-viewed nodes), the tag is on any pane showing the node.
+ *  Returns the pane id, or null when no pane shows it. Works headless (no $TMUX). */
+export function paneOfNode(nodeId) {
+    if (nodeId === '')
+        return null;
+    const r = tmux(['list-panes', '-a', '-F', '#{pane_id}\t#{@crtr_node}']);
+    if (!r.ok)
+        return null;
+    for (const line of r.stdout.split('\n')) {
+        const tab = line.indexOf('\t');
+        if (tab < 0)
+            continue;
+        if (line.slice(tab + 1) === nodeId) {
+            const pane = line.slice(0, tab);
+            if (pane !== '')
+                return pane;
+        }
+    }
+    return null;
+}
+/** Where the caller currently is, or null if not inside tmux. */
+export function currentTmux() {
+    if (!inTmux())
+        return null;
+    const r = tmux([
+        'display-message',
+        '-p',
+        '#{session_name}\t#{window_id}\t#{pane_id}',
+    ]);
+    if (!r.ok)
+        return null;
+    const [session, window, pane] = r.stdout.split('\t');
+    return { session, window, pane };
+}
+/** True when a `tmux` binary runs on PATH. */
+export function tmuxAvailable() {
+    const r = spawnSync('tmux', ['-V'], { stdio: 'ignore', timeout: TMUX_TIMEOUT_MS, killSignal: 'SIGKILL' });
+    return r.error === undefined && r.status === 0;
+}
+/** Run tmux attached to THIS terminal (stdio inherited) — for a foreground
+ *  `new-session`/`attach-session` that hands the terminal to tmux — and return
+ *  its exit status. */
+export function tmuxInteractive(args) {
+    const r = spawnSync('tmux', args, { stdio: 'inherit' });
+    return r.status ?? 1;
+}
+// Sessions + windows
+export function sessionExists(name) {
+    return tmux(['has-session', '-t', name]).ok;
+}
+/** Force bracketed-paste capabilities on for every terminal on this tmux server.
+ *
+ *  Many terminfo entries lack the Enbp/Dsbp (enable/disable bracketed paste)
+ *  capabilities. Without them tmux never asks the outer terminal to wrap pastes,
+ *  so a multi-line paste arrives as raw `\r` and the inner app (pi, zsh, …)
+ *  submits on the first newline — i.e. one paste lands as several messages.
+ *  Declaring the caps for `*` restores bracketed paste so pastes stay atomic.
+ *
+ *  `terminal-overrides` is a server option, so this is set once per server and
+ *  is idempotent when a valid escaped Enbp capability is already present,
+ *  including a user's own override. Must run only once a server exists —
+ *  set-option errors out with no server running — so callers invoke it AFTER
+ *  ensuring a session. */
+function ensureBracketedPaste() {
+    const current = tmux(['show-options', '-s', 'terminal-overrides']).stdout;
+    if (/Enbp=\\+E/.test(current))
+        return;
+    // Emit a LITERAL backslash-E (`\\E`) so tmux's option parser resolves it to ESC.
+    // A single `\E` in this JS source collapses to the letter `E`, which stores a
+    // broken `Enbp=E[?2004h` (no ESC) and silently disables bracketed paste.
+    tmux(['set-option', '-sga', 'terminal-overrides', '*:Enbp=\\E[?2004h:Dsbp=\\E[?2004l']);
+}
+/** Server-level tmux prerequisites for crtr's viewer surfaces, applied once a
+ *  server exists (callers invoke via ensureSession). Currently: bracketed paste
+ *  capability (above) and `focus-events on`, which forwards terminal focus
+ *  in/out (DECSET 1004) to the program in each pane — the attach viewer uses it
+ *  to hollow out the editor cursor in blurred panes. */
+function ensureServerOptions() {
+    ensureBracketedPaste();
+    tmux(['set-option', '-s', 'focus-events', 'on']);
+}
+/** Create a detached session rooted at `cwd` if it doesn't exist. The session
+ *  name is a root's tmux home; every node under that root is a window in it. */
+export function ensureSession(name, cwd) {
+    if (!sessionExists(name)) {
+        tmux(['new-session', '-d', '-s', name, '-c', cwd]);
+    }
+    ensureServerOptions();
+}
+function envFlags(env) {
+    const out = [];
+    for (const [k, v] of Object.entries(env))
+        out.push('-e', `${k}=${v}`);
+    return out;
+}
+/** 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 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.
+ *  Passing a bare session name resolves to the session's *active window*, which
+ *  makes new-window try to create AT that occupied index and fail with
+ *  "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. 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',
+        '-d',
+        '-a',
+        '-P',
+        '-F',
+        '#{window_id}\t#{pane_id}',
+        '-t',
+        `${opts.session}:`,
+        '-n',
+        opts.name,
+        '-c',
+        opts.cwd,
+        ...envFlags(opts.env),
+        opts.command,
+    ]);
+    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']),
+        ...(opts.before === true ? ['-b'] : []),
+        ...(opts.size !== undefined ? ['-l', String(opts.size)] : []),
+        '-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();
+    const sameRoot = here?.session === session;
+    if (!sameRoot) {
+        if (!tmux(['switch-client', '-t', session]).ok)
+            return false;
+    }
+    return tmux(['select-window', '-t', window]).ok;
+}
+/** Close a node's window (drop it from the UI). */
+export function closeWindow(window) {
+    return tmux(['kill-window', '-t', window]).ok;
+}
+/** Rename a window (`tmux rename-window -t <window> <name>`). Used by the
+ *  root relaunch to re-title the viewer window when its pane is re-pointed at
+ *  the freshly-minted node. Best-effort; false if tmux fails. */
+export function renameWindow(window, name) {
+    return tmux(['rename-window', '-t', window, name]).ok;
+}
+/** Break a single PANE out into a BRAND-NEW window of its own (`tmux break-pane
+ *  -d`). `-d` keeps the new window in the background (does not switch the client
+ *  to it); `-s <pane>` names the source pane — the §2.2 HARD DRIVER INVARIANT, so
+ *  the break never falls back to tmux's global current pane. The pane keeps its
+ *  durable `%id` across the move (only its window changes), so callers can keep
+ *  using the same pane handle. Returns the new `{window, pane}` location, or null
+ *  if tmux fails. Used by `surface tmux-spread` to lift the caller's viewer into a
+ *  fresh window before tiling sibling viewers beside it. */
+export function breakPane(pane) {
+    const r = tmux([
+        'break-pane',
+        '-d',
+        '-P',
+        '-F',
+        '#{window_id}\t#{pane_id}',
+        '-s',
+        pane,
+    ]);
+    if (!r.ok)
+        return null;
+    const [window, p] = r.stdout.split('\t');
+    if (window === undefined || window === '' || p === undefined || p === '')
+        return null;
+    return { window, pane: p };
+}
+/** 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;
+}
+/** Open a command in a tmux popup anchored to a pane. The command is a shell
+ * string because tmux executes popup payloads through the user's shell. */
+export function displayPopup(pane, cwd, command) {
+    return tmux(displayPopupArgs(pane, cwd, command)).ok;
+}
+/** `displayPopup` without blocking the event loop. tmux holds `display-popup -E`
+ *  open until the popup closes, so an interactive process (the attach viewer)
+ *  that opens one in-process must not wait on it synchronously. */
+export function displayPopupAsync(pane, cwd, command) {
+    return new Promise((resolve) => {
+        try {
+            const child = execFile('tmux', displayPopupArgs(pane, cwd, command), (err) => resolve(err === null));
+            child.stdin?.end();
+        }
+        catch {
+            resolve(false);
+        }
+    });
+}
+function displayPopupArgs(pane, cwd, command) {
+    return ['display-popup', '-E', '-t', pane, '-d', cwd, '-w', '90%', '-h', '90%', command];
+}
+/** 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) {
+    const r = tmux(['display-message', '-p', '-t', `${session}:${window}`, '#{pane_id}']);
+    return r.ok && r.stdout !== '' ? r.stdout : null;
+}
+/** The window a pane currently lives in. Used after a swap-pane to learn which
+ *  slot the caller's pane occupied — pane ids are stable across swaps, windows
+ *  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 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} #{window_id}']);
+    if (!r.ok)
+        return null;
+    const match = /^(.*) (@\d+)$/.exec(r.stdout);
+    if (match === null || match[1] === '')
+        return null;
+    return { session: match[1], window: match[2] };
+}
+/** The index tmux shows for a window target (`#{window_index}`) — the number a
+ *  person sees in the status line and presses after the prefix. Null if the
+ *  target is gone or tmux fails. */
+export function windowIndex(target) {
+    const r = tmux(['display-message', '-p', '-t', target, '#{window_index}']);
+    if (!r.ok || !/^\d+$/.test(r.stdout))
+        return null;
+    return Number.parseInt(r.stdout, 10);
+}
+/** 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) {
+    return paneState(pane) === 'live';
+}
+function paneStateFrom(pane, r) {
+    if (r.timedOut)
+        return 'unknown';
+    return r.ok && r.stdout === pane ? 'live' : 'gone';
+}
+/** {@link paneExists} that tells a timed-out probe apart from a pane that is gone. */
+export function paneState(pane) {
+    return paneStateFrom(pane, tmux(['display-message', '-p', '-t', pane, '#{pane_id}']));
+}
+/** {@link paneState} without blocking the event loop, bounded by the same timeout. */
+export async function paneStateAsync(pane, timeoutMs = TMUX_TIMEOUT_MS) {
+    return await new Promise((resolve) => {
+        try {
+            execFile('tmux', ['display-message', '-p', '-t', pane, '#{pane_id}'], { encoding: 'utf8', timeout: timeoutMs, killSignal: 'SIGKILL' }, (err, out) => {
+                const timedOut = err !== null && err.killed === true;
+                resolve(paneStateFrom(pane, { ok: err === null, stdout: String(out).trim(), timedOut }));
+            });
+        }
+        catch {
+            resolve('gone');
+        }
+    });
+}
+/** Does this pane exist AND have its command still RUNNING (`#{pane_dead}` = 0)?
+ *  Distinguishes a pane genuinely hosting a live process from a remain-on-exit
+ *  corpse frozen after exit (`pane_dead` = 1). Node viewer panes run `crtr surface attach`
+ *  as the pane command, so pane-running ⟹ a live viewer occupies it. */
+export function paneRunning(pane) {
+    const r = tmux(['display-message', '-p', '-t', pane, '#{pane_id}\t#{pane_dead}']);
+    return r.ok && r.stdout === `${pane}\t0`;
+}
+/** Every live pane id on the server (`list-panes -a`), as a Set for membership
+ *  probes. Returns null when tmux is unreachable (no server / transient failure)
+ *  so callers can tell "no panes" apart from "can't tell" — a GC pass must skip,
+ *  never mass-delete, on a failed probe. One subprocess call total, so batch
+ *  liveness sweeps (e.g. the daemon's stale-focus GC) don't pay a per-pane
+ *  display-message each. */
+export function listLivePanes() {
+    const r = tmux(['list-panes', '-a', '-F', '#{pane_id}']);
+    if (!r.ok)
+        return null;
+    return new Set(r.stdout.split('\n').filter((p) => p !== ''));
+}
+const PANE_PROBE_TIMEOUT_MS = 2000;
+/** The same probe without blocking the event loop, for callers running inside
+ *  crtrd's detached work. The daemon runs this sweep on every supervision tick,
+ *  and a blocking fork/exec there freezes the API socket — which every CLI
+ *  command and every live broker's inbox poll shares — for its full duration.
+ *  Identical contract to `listLivePanes`: null means the probe failed (no
+ *  server, timeout), which a GC pass must treat as "can't tell" and skip. */
+export async function listLivePanesAsync() {
+    const stdout = await new Promise((resolve) => {
+        try {
+            execFile('tmux', ['list-panes', '-a', '-F', '#{pane_id}'], { encoding: 'utf8', timeout: PANE_PROBE_TIMEOUT_MS, maxBuffer: 4 * 1024 * 1024 }, (err, out) => resolve(err ? null : out));
+        }
+        catch {
+            resolve(null);
+        }
+    });
+    if (stdout === null)
+        return null;
+    return new Set(stdout.trim().split('\n').filter((p) => p !== ''));
+}
+/** The working directory of a pane (`display-message -p -t <pane>
+ *  '#{pane_current_path}'`). Null if tmux fails. */
+export function paneCurrentPath(pane) {
+    const r = tmux(['display-message', '-p', '-t', pane, '#{pane_current_path}']);
+    return r.ok && r.stdout !== '' ? r.stdout : null;
+}
+/** The pane's current cell dimensions, or null when tmux cannot describe it. */
+export function paneSize(pane) {
+    const r = tmux(['display-message', '-p', '-t', pane, '#{pane_width}\t#{pane_height}']);
+    if (!r.ok)
+        return null;
+    const [colsStr, rowsStr] = r.stdout.split('\t');
+    const cols = Number.parseInt(colsStr, 10);
+    const rows = Number.parseInt(rowsStr, 10);
+    if (Number.isInteger(cols) && cols > 0 && Number.isInteger(rows) && rows > 0) {
+        return { cols, rows };
+    }
+    return null;
+}
+/** Flash a transient status-line toast on the client showing `pane` (or the
+ *  current client when `pane` is omitted). `ms` sets the display duration. Used
+ *  by `crtr canvas issue new` to confirm a capture from inside its popup.
+ *  Best-effort; never throws. */
+/** Show a transient toast in the target client's status line.
+ *
+ *  `-C` is load-bearing, not decoration: without it tmux STOPS painting that
+ *  client's panes for the whole delay, so every crtr toast freezes a live
+ *  viewer mid-turn until the message expires or a keypress dismisses it. The
+ *  flag is newer than the tmux versions crouter still runs on, and a tmux that
+ *  rejects it prints usage and shows nothing — so a rejected call retries in
+ *  the plain form, where the toast is worth more than the paint stall. */
+export function displayMessage(message, pane, ms = 4000) {
+    const args = (paneKeepsPainting) => {
+        const argv = ['display-message', ...(paneKeepsPainting ? ['-C'] : []), '-d', String(ms)];
+        if (pane !== undefined && pane !== '')
+            argv.push('-t', pane);
+        argv.push(message);
+        return argv;
+    };
+    return tmux(args(true)).ok || tmux(args(false)).ok;
+}
+/** Set a PANE-scoped tmux option (`tmux set-option -p -t <pane> <name> <value>`).
+ *  Best-effort; never throws. */
+export function setPaneOption(pane, name, value) {
+    return tmux(['set-option', '-p', '-t', pane, name, value]).ok;
+}
+/** Read a PANE-scoped tmux option value (`tmux show-options -p -t <pane> -q -v
+ *  <name>`): `-v` prints only the value, `-q` suppresses the unknown-option
+ *  error so an unset option yields an empty string. undefined if tmux fails. */
+export function getPaneOption(pane, name) {
+    const r = tmux(['show-options', '-p', '-t', pane, '-q', '-v', name]);
+    return r.ok ? r.stdout : undefined;
+}
+/** Pane option recording when an attach viewer was last started or focused.
+ *  `liveViewerPanes` uses it to select the most recently used viewer. */
+export const VIEWER_STAMP_OPTION = '@crtr_viewer_at';
+let lastViewerStampMs = 0;
+let viewerStampQueue = Promise.resolve();
+/** Stamp a viewer pane without blocking the input path that observed focus.
+ *  Stamps are monotonically increasing and their tmux writes are serialized, so
+ *  two rapid focus events cannot leave an older pane with the newer stamp. */
+export function stampViewerPaneAsync(pane) {
+    if (pane === '')
+        return;
+    const stampMs = Math.max(Date.now(), lastViewerStampMs + 1);
+    lastViewerStampMs = stampMs;
+    viewerStampQueue = viewerStampQueue.then(() => new Promise((resolve) => {
+        try {
+            execFile('tmux', ['set-option', '-p', '-t', pane, VIEWER_STAMP_OPTION, String(stampMs)], () => resolve());
+        }
+        catch {
+            resolve();
+        }
+    }));
+}
+function escapeRegex(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function looksLikeViewerCommand(command, nodeId) {
+    const unquoted = command.replace(/^"|"$/g, '');
+    return new RegExp(`(?:^|\\s)surface\\s+attach\\s+to\\s+${escapeRegex(nodeId)}(?:\\s|$)`).test(unquoted);
+}
+function readProcessTree() {
+    const table = listProcessTable();
+    if (table === null)
+        return null;
+    const childrenOf = new Map();
+    const commandOf = new Map();
+    for (const { pid, ppid, command } of table) {
+        commandOf.set(pid, command);
+        const children = childrenOf.get(ppid) ?? [];
+        children.push(pid);
+        childrenOf.set(ppid, children);
+    }
+    return { childrenOf, commandOf };
+}
+function processTreeHasViewer(tree, rootPid, nodeId) {
+    const pending = [rootPid];
+    while (pending.length > 0) {
+        const pid = pending.pop();
+        if (looksLikeViewerCommand(tree.commandOf.get(pid) ?? '', nodeId))
+            return true;
+        const children = tree.childrenOf.get(pid);
+        if (children !== undefined)
+            pending.push(...children);
+    }
+    return false;
+}
+/** List viewer panes tagged by a running local attach viewer. Pane tags can
+ *  survive a killed process, so every tag must match a viewer for the same node.
+ *  Shell-hosted viewers are recognized through their live child process. Unstamped
+ *  valid viewers remain eligible at stamp zero while an older viewer rolls forward. */
+export function liveViewerPanes(socket) {
+    const listed = tmuxOnSocket(socket, [
+        'list-panes', '-a', '-F',
+        '#{pane_id}\t#{session_name}\t#{@crtr_node}\t#{@crtr_viewer_at}',
+    ]);
+    if (!listed.ok || listed.stdout === '')
+        return [];
+    const viewers = [];
+    let processTree;
+    for (const line of listed.stdout.split('\n')) {
+        const [pane, session, nodeId, stamp] = line.split('\t');
+        if (pane === undefined || pane === '' || session === undefined || session === '' || nodeId === undefined || nodeId === '')
+            continue;
+        const command = tmuxOnSocket(socket, [
+            'display-message', '-p', '-t', pane,
+            '#{pane_current_command}\t#{pane_start_command}\t#{pane_pid}',
+        ]);
+        if (!command.ok)
+            continue;
+        const [currentCommand = '', startCommand = '', pid] = command.stdout.split('\t');
+        const directViewer = looksLikeViewerCommand(currentCommand, nodeId) || looksLikeViewerCommand(startCommand, nodeId);
+        if (!directViewer) {
+            processTree ??= readProcessTree();
+            const rootPid = Number.parseInt(pid, 10);
+            if (processTree === null || !Number.isInteger(rootPid) || rootPid <= 0 || !processTreeHasViewer(processTree, rootPid, nodeId))
+                continue;
+        }
+        const parsedStamp = Number.parseInt(stamp ?? '', 10);
+        viewers.push({
+            pane,
+            session,
+            nodeId,
+            stampMs: Number.isSafeInteger(parsedStamp) && parsedStamp >= 0 ? parsedStamp : 0,
+        });
+    }
+    return viewers;
+}
+/** Deliver one private attach-control sequence literally into a viewer pane.
+ *  `-l` bypasses tmux key-table lookup, so delivery cannot re-trigger a root
+ *  binding that initiated it. */
+export function sendAttachControl(socket, pane, actionId) {
+    return tmuxOnSocket(socket, ['send-keys', '-l', '-t', pane, encodeAttachControlInput(actionId)]).ok;
+}
+/** Show a tmux status-line message on a specific client when one is known.
+ *  `-C` for the same reason as `displayMessage`: the client's panes must keep
+ *  painting while the message sits in its status line. */
+export function displayClientMessage(socket, client, text) {
+    const args = (paneKeepsPainting) => {
+        const argv = ['display-message', ...(paneKeepsPainting ? ['-C'] : [])];
+        if (client !== undefined && client !== '')
+            argv.push('-c', client);
+        argv.push(text);
+        return argv;
+    };
+    return tmuxOnSocket(socket, args(true)).ok || tmuxOnSocket(socket, args(false)).ok;
+}
+/** 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 — 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;
+}
+/** Queue an in-place respawn through the tmux server. A program running IN the
+ * target pane must use this instead of `respawnPaneSync`: `respawn-pane -k`
+ * terminates that program, while this server-owned shell outlives the pane
+ * process long enough to run the respawn. The returned status only confirms
+ * tmux accepted the queued command. */
+export function respawnPaneInBackground(opts) {
+    return runShellInBackground(`tmux ${respawnPaneArgs(opts).map(shellQuote).join(' ')} >/dev/null 2>&1`);
+}
+/** Run a shell command from the tmux server (`run-shell -b`), outside the
+ * caller's process tree, so it outlives the caller's pane or popup. The returned
+ * status only confirms tmux accepted the command. */
+export function runShellInBackground(command) {
+    return tmux(['run-shell', '-b', command]).ok;
+}
+/** The command line a pane was originally started with (`#{pane_start_command}`)
+ *  — the exact command `respawn-pane` with no argument re-runs. undefined when
+ *  tmux is unreachable or the pane is gone. */
+export function paneStartCommand(pane) {
+    const r = tmux(['display-message', '-p', '-t', pane, '#{pane_start_command}']);
+    return r.ok ? r.stdout : undefined;
+}
+/** Swap two panes' places on screen (`swap-pane -s a -t b`). The panes keep their ids and
+ *  processes; only their positions (and windows) exchange. Returns tmux's error text on
+ *  failure, null on success. */
+export function swapPanes(source, target) {
+    const r = tmux(['swap-pane', '-s', source, '-t', target]);
+    return r.ok ? null : (r.stderr === '' ? 'tmux swap-pane failed' : r.stderr);
+}
+/** The foreground command name of a pane (`#{pane_current_command}`). */
+export function paneCurrentCommand(pane) {
+    const r = tmux(['display-message', '-p', '-t', pane, '#{pane_current_command}']);
+    return r.ok && r.stdout !== '' ? r.stdout : undefined;
+}
+/** The pane's root process pid (`#{pane_pid}`) — the process tmux launched in
+ *  the pane (the viewer itself, or the login shell hosting it). undefined when
+ *  tmux is unreachable or the pane is gone. */
+export function panePid(pane) {
+    const r = tmux(['display-message', '-p', '-t', pane, '#{pane_pid}']);
+    if (!r.ok)
+        return undefined;
+    const pid = Number.parseInt(r.stdout, 10);
+    return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+}
+/** Kill a pane's current process and re-run the SAME command line it was
+ *  started with (`respawn-pane -k` with no command reuses the pane's original
+ *  command). Used to hot-reload a viewer pane in place: the fresh process
+ *  re-resolves `crtr` and picks up the currently selected runtime generation,
+ *  while the pane id, geometry, and the node's broker are untouched. */
+export function respawnPaneInPlace(pane) {
+    return tmux(['respawn-pane', '-k', '-t', pane]).ok;
+}
+// pi command assembly
+/** 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
+ *  bundled pi CLI launched with the current Node binary. CRTR_PI_BINARY is a
+ *  TEST-ONLY substitution seam: 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 depending on tmux/shell PATH inheritance. An
+ *  explicit `binary` arg still overrides the env. The value may be a multi-word
+ *  launcher (e.g. `node --import tsx/esm host.ts`); only argv entries are
+ *  shell-quoted, so a multi-word binary is spliced verbatim ahead of them. */
+export function piCommand(argv, binary = envPiBinaryOverride() ?? bundledPiCommandForShell(shellQuote)) {
+    return [binary, ...argv.map(shellQuote)].join(' ');
+}
+// Window liveness helpers (used by the supervisor daemon)
+/** 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
+ *  string reported by tmux (e.g. `@1`, `@2`, …). */
+export function listWindowIds(session) {
+    const r = tmux(['list-windows', '-t', session, '-F', '#{window_id}']);
+    if (!r.ok || r.stdout === '')
+        return [];
+    return r.stdout.split('\n').filter((s) => s !== '');
+}
+/** True when both `session` and `window` are present (non-null/undefined) and
+ *  the window currently exists inside the session. False whenever either arg
+ *  is absent, the session is gone, or tmux does not know the window. */
+export function windowAlive(session, window) {
+    if (session == null || window == null)
+        return false;
+    return listWindowIds(session).includes(window);
+}
+// 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. */
+export function selectWindow(session, window) {
+    return tmux(['select-window', '-t', `${session}:${window}`]).ok;
+}
+/** Apply a named tmux layout to a window (`tmux select-layout -t <window>
+ *  <layout>`). `surface tmux-spread` calls it with `tiled` to evenly grid every
+ *  viewer pane in the spread window (and between splits, to redistribute space so
+ *  the next split has room). Best-effort; false if tmux fails. */
+export function selectLayout(window, layout) {
+    return tmux(['select-layout', '-t', window, layout]).ok;
+}
+/** Make a pane the ACTIVE pane in its window (`tmux select-pane -t <pane>`). A
+ *  `split-window -d` keeps the CALLER active, so a freshly-opened viewer pane is
+ *  not focused until this runs — `focus` calls it so picking a node (e.g. from the
+ *  alt+g graph) lands the keyboard on the new viewer. Best-effort; false if tmux
+ *  fails. */
+export function selectPane(pane) {
+    return tmux(['select-pane', '-t', pane]).ok;
+}
+/** Switch the tmux client to a different session (cross-session focus). Runs
+ *  `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 function switchClient(session) {
+    return tmux(['switch-client', '-t', session]).ok;
+}
+// send-keys (chrome — used by the prefix menu + nav bindings)
+/** 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;
+}
+// Binding reconciliation needs the raw tmux invocation primitive but no other
+// module may reach around the driver boundary.
+export { tmux as runTmux };