@north-light/crouter 0.3.173 → 0.3.175

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

@@ -0,0 +1,598 @@
+// 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 { bundledPiCommandForShell } from './pi-cli.js';
+// ---------------------------------------------------------------------------
+// Shell quoting + tmux invocation
+// ---------------------------------------------------------------------------
+/** POSIX single-quote escaping for one shell word. */
+export function shellQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+function tmux(args) {
+    const r = spawnSync('tmux', args, { encoding: 'utf8' });
+    return {
+        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'] !== '';
+}
+/** 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 };
+}
+// ---------------------------------------------------------------------------
+// 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(['display-popup', '-E', '-t', pane, '-d', cwd, '-w', '90%', '-h', '90%', command]).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) {
+    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}\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;
+}
+/** 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 !== ''));
+}
+/** 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. */
+export function displayMessage(message, pane, ms = 4000) {
+    const args = ['display-message', '-d', String(ms)];
+    if (pane !== undefined && pane !== '')
+        args.push('-t', pane);
+    args.push(message);
+    return tmux(args).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 result = spawnSync('ps', ['-ax', '-o', 'pid=,ppid=,command='], { encoding: 'utf8' });
+    if (result.status !== 0 || typeof result.stdout !== 'string')
+        return null;
+    const childrenOf = new Map();
+    const commandOf = new Map();
+    for (const line of result.stdout.split('\n')) {
+        const match = /^\s*(\d+)\s+(\d+)\s+(.*)$/.exec(line);
+        if (match === null)
+            continue;
+        const pid = Number(match[1]);
+        const parentPid = Number(match[2]);
+        commandOf.set(pid, match[3]);
+        const children = childrenOf.get(parentPid) ?? [];
+        children.push(pid);
+        childrenOf.set(parentPid, 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. */
+export function displayClientMessage(socket, client, text) {
+    const args = ['display-message'];
+    if (client !== undefined && client !== '')
+        args.push('-c', client);
+    args.push(text);
+    return tmuxOnSocket(socket, args).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) {
+    const command = `tmux ${respawnPaneArgs(opts).map(shellQuote).join(' ')} >/dev/null 2>&1`;
+    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;
+}
+/** 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 = process.env['CRTR_PI_BINARY'] ?? 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 };

package/dist/core/runtime/view-socket.d.ts

@@ -0,0 +1,14 @@
+/** The shared cold-start deadline (ms) a freshly-opened viewer waits for its
+ * broker's view.sock — one source of truth for CRTR_ATTACH_WAIT_MS. */
+export declare const BROKER_VIEW_SOCKET_WAIT_MS = 30000;
+/** Resolve true exactly when `sockPath` accepts a connection within `timeoutMs`. */
+export declare function probeViewSocket(sockPath: string, timeoutMs: number): Promise<boolean>;
+/** Bounded retry for the revive leaf, which has no launch handle to observe. */
+export declare function waitForViewSocketReady(nodeId: string): Promise<boolean>;
+/** Wait for a launched broker's view.sock, failing fast when its launch handle
+ * exits. `exited` remains optional for existing callers that only need the same
+ * bounded readiness deadline without a handle. */
+export declare function waitForBrokerViewSocket(nodeId: string, exited?: Promise<{
+    code: number | null;
+    signal: NodeJS.Signals | null;
+}>): Promise<boolean>;