@north-light/crouter 0.3.172 → 0.3.174

package/dist/core/runtime/tmux.js

@@ -1,1314 +0,0 @@
-// tmux placement — one window per active node.
-//
-//   session = a root        window = a node        window 0 = optional dashboard
-//
-// Background windows run but don't render — only the current window draws. That
-// is the "detached but switchable" model: nothing tiles, you never see a node's
-// UI unless you switch to it. Bring one forefront with select-window (within a
-// root) or switch-client + select-window (across roots). done/dead nodes close
-// their window; reviving opens a fresh one.
-import { execFile, spawnSync } from 'node:child_process';
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
-import { homedir, tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { ATTACH_CONTROL_BINDINGS, BINDING_CATALOG, BINDING_IDS, encodeAttachControlInput, formatGesture, isAttachPaneBinding, resolveUserKeybindingSettings, } from '../keybindings/index.js';
-import { normalizeTmuxPassthrough } from '../config.js';
-import { withExclusiveDirectoryLock } from '../human/convention.js';
-import { bundledPiCommandForShell } from './pi-cli.js';
-import { surfaceTmuxStyleArgs } from './surface-bg.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;
-}
-/** 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;
-}
-/** 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;
-}
-// ---------------------------------------------------------------------------
-// Crouter-owned tmux bindings
-// ---------------------------------------------------------------------------
-const TMUX_BINDING_MANIFEST = '@crtr_keybindings_manifest';
-const ROOT_TABLE = 'root';
-const LEAF_MENU_ACTIONS = {
-    'crtr.tmux.menu.promote': { description: 'promote to orchestrator', action: { kind: 'keys', keys: '/promote' } },
-    'crtr.tmux.menu.resume': { description: 'find node', action: { kind: 'keys', keys: '/resume-node' } },
-    'crtr.tmux.menu.fork': { description: 'fork into idle root', action: { kind: 'direct', run: 'node fork --pane {pane}' } },
-    'crtr.tmux.menu.demote': { description: 'demote (finish when done)', action: { kind: 'command', run: 'node lifecycle demote --pane {pane}' } },
-    'crtr.tmux.menu.detach': { description: 'demote + close viewer', action: { kind: 'command', run: 'node lifecycle demote --pane {pane} --detach' } },
-    'crtr.tmux.menu.close-subtree': { description: 'close agent + subtree', action: { kind: 'command', run: 'node lifecycle close --pane {pane}' } },
-    'crtr.tmux.menu.background-bash': { description: 'background running bash', action: { kind: 'direct', run: 'node bash background --pane {pane}' } },
-    // M-S-r, not M-R: with extended-keys csi-u tmux encodes M-R as alt+uppercase-R
-    // WITHOUT the shift modifier bit, which pi-tui's `alt+shift+r` matcher rejects;
-    // M-S-r carries shift+alt and lands as the same chord the keyboard produces.
-    'crtr.tmux.menu.file-review': { description: 'review a file', action: { kind: 'raw-keys', keys: 'M-S-r' } },
-    'crtr.tmux.menu.metadata': { description: 'metadata', action: { kind: 'keys', keys: '/node-metadata' } },
-    'crtr.tmux.menu.fold-tools': { description: 'fold finished tool calls', action: { kind: 'keys', keys: '/fold-tools' } },
-    'crtr.tmux.menu.context': { description: 'context + reports', action: { kind: 'keys', keys: '/context' } },
-    'crtr.tmux.menu.providers': { description: 'settings', action: { kind: 'popup', run: 'sys setup' } },
-    'crtr.tmux.menu.graph': { description: 'canvas graph', action: { kind: 'keys', keys: '/graph' } },
-    'crtr.tmux.menu.focus-manager': { description: 'go to manager', action: { kind: 'command', run: 'surface node focus {manager}' } },
-    'crtr.tmux.menu.copy-id': { description: 'copy node id', action: { kind: 'command', run: 'surface node id --pane {pane}' } },
-    'crtr.tmux.menu.reload-viewer': { description: 'reload viewer', action: { kind: 'direct', run: 'surface reload --pane {pane}' } },
-    'crtr.tmux.menu.recap': { description: 'generate recap', action: { kind: 'keys', keys: '/recap' } },
-    'crtr.tmux.menu.pin': { description: 'pin conversation', action: { kind: 'direct', run: 'surface node pin --pane {pane}' } },
-    'crtr.tmux.menu.issue.idea': { description: 'idea', action: { kind: 'popup', run: 'canvas issue new --type idea' } },
-    'crtr.tmux.menu.issue.bug': { description: 'bug', action: { kind: 'popup', run: 'canvas issue new --type bug' } },
-};
-function escapeTmuxFormats(value) {
-    return value.replace(/#/g, '##');
-}
-function tmuxCommand(args) {
-    return args.map(shellQuote).join(' ');
-}
-function chordCommand(run, interactive = false) {
-    const command = `crtr canvas chord --pane '#{pane_id}' --run ${shellQuote(escapeTmuxFormats(run))}${interactive ? ' --interactive' : ''}`;
-    return interactive
-        ? {
-            argv: ['display-popup', '-E', '-w', '60%', '-h', '50%', '-d', '#{pane_current_path}', command],
-            menu: `display-popup -E -w 60% -h 50% -d "#{pane_current_path}" ${shellQuote(command)}`,
-        }
-        : {
-            argv: ['run-shell', `${command} >/dev/null 2>&1`],
-            menu: `run-shell ${shellQuote(`${command} >/dev/null 2>&1`)}`,
-        };
-}
-/** Dispatch an action straight to a `crtr` invocation, skipping the
- *  `canvas chord` hop entirely. Only sound for an action whose sole
- *  interpolation need is `{pane}` — tmux expands it natively as `#{pane_id}` at
- *  keypress time (a real tmux format, substituted AFTER escaping the static
- *  run text so the `#` here is never doubled), so chord's node-resolution
- *  round trip buys nothing. `-b` keeps dispatch non-blocking. */
-function directCommand(run) {
-    const argv = escapeTmuxFormats(run).replace('{pane}', '#{pane_id}');
-    const command = `crtr ${argv} >/dev/null 2>&1`;
-    return {
-        argv: ['run-shell', '-b', command],
-        menu: `run-shell -b ${shellQuote(command)}`,
-    };
-}
-/** One command constructor serves both display-menu selections and direct root
- *  shortcuts. Each result carries the argv bind-key needs plus the stable menu
- *  serialization existing Alt+C installs already use. */
-function menuActionCommand(action) {
-    switch (action.kind) {
-        case 'disabled': return null;
-        case 'separator': return null;
-        // Choosing any menu item closes it; refresh-client is the deliberately
-        // inert command that lets the prefix shortcut choose this close row.
-        case 'dismiss': return { argv: ['refresh-client'], menu: 'refresh-client' };
-        case 'keys': {
-            const keys = escapeTmuxFormats(action.keys);
-            return {
-                // A root binding already runs in the pressed key's pane context. Its
-                // target must stay implicit: bind-key does not expand `#{pane_id}` in
-                // send-keys' target argument. A menu command is serialized later and
-                // does need the pane captured when the menu opened.
-                argv: ['send-keys', keys, 'Enter'],
-                menu: `send-keys -t '#{pane_id}' ${shellQuote(keys)} Enter`,
-            };
-        }
-        case 'raw-keys': {
-            const keys = escapeTmuxFormats(action.keys);
-            return {
-                argv: ['send-keys', keys],
-                menu: `send-keys -t '#{pane_id}' ${shellQuote(keys)}`,
-            };
-        }
-        case 'literal-input': {
-            const input = escapeTmuxFormats(action.input);
-            return {
-                argv: ['send-keys', '-l', input],
-                menu: `send-keys -l -t '#{pane_id}' ${shellQuote(input)}`,
-            };
-        }
-        case 'command': return chordCommand(action.run);
-        case 'direct': return directCommand(action.run);
-        case 'popup': return chordCommand(action.run, true);
-        case 'submenu': {
-            const argv = buildMenuArgs(action.title, action.items);
-            return { argv, menu: tmuxCommand(argv) };
-        }
-    }
-}
-function renderMenuAction(action) {
-    return menuActionCommand(action)?.menu ?? '';
-}
-/** Visible width of a menu item name: style markup (`#[...]`) takes no cells. */
-function menuItemWidth(description) {
-    return description.replace(/#\[[^\]]*\]/g, '').length;
-}
-function buildMenuArgs(title, items) {
-    const safeTitle = escapeTmuxFormats(title);
-    const widestItem = items.reduce((width, item) => Math.max(width, menuItemWidth(item.description)), 0);
-    const args = ['display-menu', '-T', `#[align=centre]${safeTitle}`, ...surfaceTmuxStyleArgs()];
-    args.push('-x', `#{e|-:#{pane_right},${Math.max(safeTitle.length, widestItem) + 7}}`, '-y', '#{e|+:#{pane_top},3}', '--');
-    for (const item of items) {
-        // A separator is a single empty name with key and command omitted; tmux
-        // draws it as a horizontal rule. A header (disabled) name is a crouter-owned
-        // literal carrying `#[...]` style markup, so it skips format escaping.
-        if (item.action.kind === 'separator') {
-            args.push('');
-            continue;
-        }
-        const name = item.action.kind === 'disabled' ? item.description : escapeTmuxFormats(item.description);
-        args.push(name, item.selector, renderMenuAction(item.action));
-    }
-    args.push('', '-esc / q to close', '', '');
-    return args;
-}
-const TMUX_NAMED_KEYS = {
-    enter: 'Enter', escape: 'Escape', tab: 'Tab', backspace: 'BSpace', delete: 'DC',
-    space: 'Space', up: 'Up', down: 'Down', left: 'Left', right: 'Right',
-    pageup: 'PPage', pagedown: 'NPage', home: 'Home', end: 'End',
-};
-function normalizedStrokeParts(stroke) {
-    if (stroke === '+')
-        return { key: '+', modifiers: [] };
-    if (stroke.endsWith('++'))
-        return { key: '+', modifiers: stroke.slice(0, -2).split('+') };
-    const parts = stroke.split('+');
-    return { key: parts.pop(), modifiers: parts };
-}
-function tmuxKey(stroke) {
-    let { key, modifiers: modifierParts } = normalizedStrokeParts(stroke);
-    const modifiers = new Set(modifierParts);
-    if (modifiers.has('shift') && key.length === 1 && /[a-z]/.test(key)) {
-        // tmux names a shifted printable with its uppercase character even when an
-        // extended-key terminal also preserves Shift as a modifier: Alt+Shift+F is
-        // `M-S-F`. Shift by itself needs only the uppercase character (`F`).
-        key = key.toUpperCase();
-        if (!modifiers.has('ctrl') && !modifiers.has('alt'))
-            modifiers.delete('shift');
-    }
-    key = TMUX_NAMED_KEYS[key] ?? key;
-    const prefix = [
-        modifiers.has('ctrl') ? 'C-' : '',
-        modifiers.has('alt') ? 'M-' : '',
-        modifiers.has('shift') ? 'S-' : '',
-    ].join('');
-    return `${prefix}${key}`;
-}
-function menuSelector(stroke) {
-    const { key, modifiers } = normalizedStrokeParts(stroke);
-    return modifiers.includes('shift') && /[a-z]/.test(key) ? key.toUpperCase() : key === 'space' ? ' ' : key;
-}
-function boundMenuItems(ids, entries, bindings) {
-    const items = [];
-    for (const id of ids) {
-        const entry = entries.get(id);
-        if (entry === undefined)
-            continue;
-        for (const gesture of bindings.gestures(id)) {
-            items.push({ description: entry.description, selector: menuSelector(gesture), action: entry.action });
-        }
-    }
-    return items;
-}
-/** Resolve the complete action descriptor set once. Submenu openers point at
- *  the same child MenuItems the prefix menu renders, so their direct global
- *  shortcuts cannot drift from the menu path. */
-function resolvedMenuActions(bindings) {
-    const entries = new Map();
-    for (const [id, entry] of Object.entries(LEAF_MENU_ACTIONS)) {
-        if (entry !== undefined)
-            entries.set(id, entry);
-    }
-    for (const { menuId, actionId } of ATTACH_CONTROL_BINDINGS) {
-        const definition = BINDING_CATALOG.find((candidate) => candidate.id === actionId);
-        if (definition === undefined)
-            throw new Error(`missing attach binding definition ${actionId}`);
-        entries.set(menuId, {
-            description: definition.name.toLowerCase(),
-            action: { kind: 'literal-input', input: encodeAttachControlInput(actionId) },
-        });
-    }
-    const attachItems = boundMenuItems(ATTACH_CONTROL_BINDINGS.map(({ menuId }) => menuId), entries, bindings);
-    if (attachItems.length > 0) {
-        entries.set('crtr.tmux.menu.attach', {
-            description: 'attach viewer ›',
-            action: { kind: 'submenu', title: ' attach viewer ', items: attachItems },
-        });
-    }
-    const showItems = boundMenuItems([
-        'crtr.tmux.menu.metadata',
-        'crtr.tmux.menu.context',
-    ], entries, bindings);
-    entries.set('crtr.tmux.menu.show', {
-        description: 'inspect ›',
-        action: { kind: 'submenu', title: ' inspect node ', items: showItems },
-    });
-    // How this viewer PAINTS the transcript, as opposed to what it shows. Each item
-    // is a toggle the viewer applies to its own render state (a `/`-command sent to
-    // the pane); a tmux menu is built once and cannot show live state, so the item
-    // reads as the action and the viewer answers with a notice.
-    const viewSettingsItems = boundMenuItems(['crtr.tmux.menu.fold-tools'], entries, bindings);
-    entries.set('crtr.tmux.menu.view-settings', {
-        description: 'display ›',
-        action: { kind: 'submenu', title: ' display ', items: viewSettingsItems },
-    });
-    const issueItems = boundMenuItems([
-        'crtr.tmux.menu.issue.idea',
-        'crtr.tmux.menu.issue.bug',
-    ], entries, bindings);
-    entries.set('crtr.tmux.menu.issues', {
-        description: 'create ›',
-        action: { kind: 'submenu', title: ' create ', items: issueItems },
-    });
-    return entries;
-}
-function menuItems(bindings, entries) {
-    const boundItems = (ids) => boundMenuItems(ids, entries, bindings);
-    const items = [];
-    const addGroup = (heading, groupItems) => {
-        if (groupItems.length === 0)
-            return;
-        if (items.length > 0)
-            items.push({ description: '', selector: '', action: { kind: 'separator' } });
-        items.push({ description: `-#[bold]${heading}`, selector: '', action: { kind: 'disabled' } }, ...groupItems);
-    };
-    // Explore changes what is in view or opens a canvas-level browser. Current
-    // node acts on the agent in this pane without changing its lifecycle.
-    addGroup('Explore', boundItems([
-        'crtr.tmux.menu.resume',
-        'crtr.tmux.menu.graph',
-        'crtr.tmux.menu.focus-manager',
-        'crtr.tmux.menu.show',
-        'crtr.tmux.menu.view-settings',
-    ]));
-    addGroup('Current node', boundItems([
-        'crtr.tmux.menu.attach',
-        'crtr.tmux.menu.background-bash',
-        'crtr.tmux.menu.file-review',
-        'crtr.tmux.menu.pin',
-        'crtr.tmux.menu.copy-id',
-        'crtr.tmux.menu.reload-viewer',
-        'crtr.tmux.menu.recap',
-    ]));
-    addGroup('Lifecycle', boundItems([
-        'crtr.tmux.menu.fork',
-        'crtr.tmux.menu.promote',
-        'crtr.tmux.menu.demote',
-        'crtr.tmux.menu.detach',
-        'crtr.tmux.menu.close-subtree',
-    ]));
-    addGroup('System', boundItems([
-        'crtr.tmux.menu.providers',
-        'crtr.tmux.menu.issues',
-    ]));
-    const prefixGestures = bindings.gestures('crtr.tmux.menu.open');
-    if (prefixGestures.length > 0 && items.length > 0) {
-        items.push({ description: '', selector: '', action: { kind: 'separator' } });
-        for (const gesture of prefixGestures) {
-            items.push({
-                description: `${formatGesture(gesture)} to close`,
-                // Menu selectors accept tmux key notation, including modifiers. This
-                // is intentionally the exact binding that opened the menu.
-                selector: tmuxKey(gesture),
-                action: { kind: 'dismiss' },
-            });
-        }
-    }
-    return items;
-}
-/** Read one token from tmux's sourceable `list-keys` output. Key names that
- * contain punctuation are quoted, so splitting on whitespace would make their
- * displayed token differ from the key name accepted by bind/unbind commands. */
-function readTmuxToken(line, from) {
-    let index = from;
-    while (index < line.length && /\s/.test(line[index]))
-        index += 1;
-    if (index >= line.length)
-        return null;
-    let quote = null;
-    let value = '';
-    while (index < line.length) {
-        const char = line[index];
-        if (quote === null && /\s/.test(char))
-            break;
-        if (quote === null && (char === "'" || char === '"')) {
-            quote = char;
-            index += 1;
-            continue;
-        }
-        if (quote === char) {
-            quote = null;
-            index += 1;
-            continue;
-        }
-        if (char === '\\' && quote !== "'" && index + 1 < line.length) {
-            value += line[index + 1];
-            index += 2;
-            continue;
-        }
-        value += char;
-        index += 1;
-    }
-    return { value, end: index };
-}
-function parseTmuxBinding(line) {
-    const commandName = readTmuxToken(line, 0);
-    if (commandName?.value !== 'bind-key')
-        return null;
-    let cursor = commandName.end;
-    let repeat = false;
-    while (true) {
-        const token = readTmuxToken(line, cursor);
-        if (token === null)
-            return null;
-        cursor = token.end;
-        if (token.value === '-r') {
-            repeat = true;
-            continue;
-        }
-        if (token.value !== '-T')
-            continue;
-        const table = readTmuxToken(line, cursor);
-        if (table === null)
-            return null;
-        const key = readTmuxToken(line, table.end);
-        if (key === null)
-            return null;
-        return {
-            table: table.value,
-            key: key.value,
-            command: line.slice(key.end).trimStart(),
-            repeat,
-        };
-    }
-}
-function bindingAt(table, key) {
-    const result = tmux(['list-keys', '-T', table]);
-    if (!result.ok)
-        return null;
-    return result.stdout.split('\n').find((line) => {
-        const parsed = parseTmuxBinding(line);
-        return parsed?.table === table && parsed.key === key;
-    }) ?? null;
-}
-/** Effective crouter gestures that tmux's root table currently consumes before
- * pane input can see them. One list-keys snapshot serves the whole query. */
-export function occupiedTmuxRootGestures(gestures) {
-    const result = tmux(['list-keys', '-T', ROOT_TABLE]);
-    if (!result.ok)
-        return [];
-    const occupied = new Set(result.stdout.split('\n').flatMap((line) => {
-        const parsed = parseTmuxBinding(line);
-        return parsed?.table === ROOT_TABLE ? [parsed.key] : [];
-    }));
-    return gestures.filter((gesture) => !gesture.includes(' > ') && occupied.has(tmuxKey(gesture)));
-}
-function isInstalledPair(value) {
-    return typeof value === 'object' && value !== null
-        && typeof value.table === 'string'
-        && typeof value.key === 'string';
-}
-function isWrappedRootBinding(value) {
-    if (typeof value !== 'object' || value === null)
-        return false;
-    const wrapper = value;
-    return typeof wrapper.bindingId === 'string'
-        && BINDING_IDS.has(wrapper.bindingId)
-        && typeof wrapper.gesture === 'string'
-        && typeof wrapper.key === 'string'
-        && (typeof wrapper.original === 'string' || wrapper.original === null)
-        && typeof wrapper.wrapper === 'string'
-        && (wrapper.state === 'owned' || wrapper.state === 'relinquished');
-}
-function readManifest() {
-    const option = tmux(['show-options', '-s', '-q', TMUX_BINDING_MANIFEST]);
-    if (!option.ok)
-        return null;
-    if (option.stdout === '')
-        return { pairs: [], wrappers: [] };
-    const result = tmux(['show-options', '-s', '-qv', TMUX_BINDING_MANIFEST]);
-    if (!result.ok)
-        return null;
-    try {
-        const value = JSON.parse(result.stdout);
-        // Before passthrough wrappers, the manifest was the pair array itself.
-        if (Array.isArray(value))
-            return value.every(isInstalledPair) ? { pairs: value, wrappers: [] } : null;
-        if (typeof value !== 'object' || value === null)
-            return null;
-        const manifest = value;
-        if (!Array.isArray(manifest.pairs) || !manifest.pairs.every(isInstalledPair)
-            || !Array.isArray(manifest.wrappers) || !manifest.wrappers.every(isWrappedRootBinding))
-            return null;
-        return { pairs: manifest.pairs, wrappers: manifest.wrappers };
-    }
-    catch {
-        return null;
-    }
-}
-function writeManifest(manifest) {
-    return tmux(['set-option', '-s', TMUX_BINDING_MANIFEST, JSON.stringify(manifest)]);
-}
-/** Tmux parses semicolons once more even when argv already isolated them. */
-function tmuxKeyArgument(key) {
-    return key.replace(/\\/g, '\\\\').replace(/;/g, '\\;');
-}
-function tmuxCommandToken(value) {
-    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/;/g, '\\;')}"`;
-}
-/** A top-level separator is printed as `\;` in a bind-key line, but the same
- * sequence is literal after the command tail becomes one if-shell branch. */
-function bindingCommandForBranch(command) {
-    let quote = null;
-    let out = '';
-    for (let index = 0; index < command.length; index += 1) {
-        const char = command[index];
-        if (quote === null && (char === "'" || char === '"')) {
-            quote = char;
-            out += char;
-            continue;
-        }
-        if (quote === char) {
-            quote = null;
-            out += char;
-            continue;
-        }
-        if (char === '\\' && index + 1 < command.length) {
-            const next = command[index + 1];
-            if (quote === null && next === ';') {
-                out += ';';
-            }
-            else {
-                out += char + next;
-            }
-            index += 1;
-            continue;
-        }
-        out += char;
-    }
-    return out;
-}
-function sourceBindingLine(line) {
-    const dir = mkdtempSync(join(tmpdir(), 'crtr-tmux-binding-'));
-    const file = join(dir, 'binding.conf');
-    try {
-        writeFileSync(file, `${line}\n`, 'utf8');
-        return tmux(['source-file', file]);
-    }
-    finally {
-        rmSync(dir, { recursive: true, force: true });
-    }
-}
-function restoreWrappedBinding(wrapper) {
-    return wrapper.original === null
-        ? tmux(['unbind-key', '-T', ROOT_TABLE, tmuxKeyArgument(wrapper.key)])
-        : sourceBindingLine(wrapper.original);
-}
-// Crouter's own pre-manifest root bindings. Reconciliation always adopts an
-// untracked binding matching these crouter-specific markers, even when a partial
-// ownership manifest already exists. Older installs could leave M-c outside a
-// later manifest that tracked only newly-added bindings; treating that stale
-// menu as foreign made every future menu update silently skip it.
-const LEGACY_ROOT_BINDINGS = [
-    { key: 'M-c', markers: ['display-menu', 'promote to orchestrator', 'crtr canvas chord', 'new issue / todo'] },
-    // Later pre-manifest menu generations dropped the 'new issue / todo' row, so
-    // they need their own marker set (still crouter-specific via the chord verb).
-    { key: 'M-c', markers: ['display-menu', 'promote to orchestrator', 'crtr canvas chord'] },
-    { key: 'M-]', markers: ['run-shell', '--dir next', "--pane '#{pane_id}'"] },
-    { key: 'M-[', markers: ['run-shell', '--dir prev', "--pane '#{pane_id}'"] },
-    { key: 'M-v', markers: ['switch-client', '-T crtr-view'] },
-];
-// The inbox toggle is a crouter-owned root binding, resolved from keybindings.json
-// and installed through the manifest sweep like every sibling. Root bindings
-// matching these markers that are NOT tracked in the manifest are hl-owned
-// strays; reconciliation removes them (and the state file naming their key) so
-// the manifest stays the sole owner of the inbox command.
-const LEGACY_INBOX_MARKERS = ['run-shell', 'hl inbox toggle'];
-const LEGACY_INBOX_DEFAULT_KEY = 'M-i';
-export function legacyInboxKeyFile() {
-    const stateHome = process.env['XDG_STATE_HOME'] || join(homedir(), '.local', 'state');
-    return join(stateHome, 'humanloop', 'inbox-key');
-}
-function adoptLegacyBindings() {
-    for (const legacy of LEGACY_ROOT_BINDINGS) {
-        const existing = bindingAt(ROOT_TABLE, legacy.key);
-        if (existing !== null && legacy.markers.every((marker) => existing.includes(marker))) {
-            tmux(['unbind-key', '-T', ROOT_TABLE, legacy.key]);
-        }
-    }
-}
-// Enforce the manifest's sole ownership of the inbox command: any hl-owned
-// inbox binding not tracked in the manifest is unbound, and the humanloop
-// state file is discarded. Runs on every reconciliation regardless of whether
-// a manifest already exists. Checks the default key plus the key the state
-// file records (the file's value only locates a stray binding — it is never
-// imported into crouter config). A key tracked in the manifest is crouter's
-// own and left alone; a foreign non-hl binding never matches the markers and
-// is preserved. Idempotent: with no file and no untracked hl binding, a no-op.
-function removeLegacyInboxBindings(manifestPairs) {
-    const owned = new Set(manifestPairs.filter((pair) => pair.table === ROOT_TABLE).map((pair) => pair.key));
-    const keys = new Set([LEGACY_INBOX_DEFAULT_KEY]);
-    const file = legacyInboxKeyFile();
-    try {
-        const configured = readFileSync(file, 'utf8').trim();
-        if (configured !== '')
-            keys.add(configured);
-    }
-    catch { /* no state file: only the default key can hold a stale binding */ }
-    for (const key of keys) {
-        if (owned.has(key))
-            continue;
-        const existing = bindingAt(ROOT_TABLE, key);
-        if (existing !== null && LEGACY_INBOX_MARKERS.every((marker) => existing.includes(marker))) {
-            tmux(['unbind-key', '-T', ROOT_TABLE, key]);
-        }
-    }
-    try {
-        rmSync(file, { force: true });
-    }
-    catch { /* best-effort */ }
-}
-// --quiet keeps the background `run-shell -b` binding from printing its result JSON, which
-// tmux would otherwise surface as a view-mode overlay on the active pane. The popup opening
-// is the feedback; a genuine failure still prints through the CLI toggle action. This deliberately
-// invokes bare `crtr` from PATH: it is installed once and must resolve to the selected generation,
-// not the sealed generation that installed it. The neighboring `crtr surface node cycle` builders
-// share that property.
-export function inboxToggleTmuxCommand() {
-    return ['run-shell', '-b', 'crtr human inbox toggle --quiet --tmux-socket "#{socket_path}" --tmux-client "#{client_name}" --target-pane "#{pane_id}"'];
-}
-function actionCommand(id) {
-    switch (id) {
-        case 'crtr.tmux.node.next': return ['run-shell', `crtr surface node cycle --dir next --pane '#{pane_id}' >/dev/null 2>&1`];
-        case 'crtr.tmux.node.previous': return ['run-shell', `crtr surface node cycle --dir prev --pane '#{pane_id}' >/dev/null 2>&1`];
-        case 'crtr.tmux.inbox.toggle': return inboxToggleTmuxCommand();
-        default: throw new Error(`no tmux command for ${id}`);
-    }
-}
-/** A directory beside the server socket serializes every process driving that
- * exact tmux server. Outside tmux, ask the default server for its socket first;
- * an unavailable server uses one per-user fallback lock for the error path. */
-function tmuxBindingLockPath() {
-    const envSocket = process.env['TMUX']?.split(',')[0]?.trim();
-    if (envSocket !== undefined && envSocket !== '')
-        return `${envSocket}.crtr-keybindings.lock`;
-    const result = tmux(['display-message', '-p', '#{socket_path}']);
-    if (result.ok && result.stdout !== '')
-        return `${result.stdout}.crtr-keybindings.lock`;
-    const user = typeof process.getuid === 'function' ? process.getuid() : 'user';
-    return join(tmpdir(), `crtr-tmux-keybindings-${user}.lock`);
-}
-/** Reconcile the tmux server with one immutable crouter settings snapshot.
- * Passing snapshots is hermetic; the no-argument front door reads both user
- * settings from the same config read. The server lock covers the entire
- * manifest read, restore, install, fingerprint, and write transition. */
-export function installTmuxBindings(bindingSnapshot, passthroughSnapshot = []) {
-    return withExclusiveDirectoryLock(tmuxBindingLockPath(), () => reconcileTmuxBindings(bindingSnapshot, passthroughSnapshot));
-}
-function reconcileTmuxBindings(bindingSnapshot, passthroughSnapshot = []) {
-    const userSettings = bindingSnapshot === undefined ? resolveUserKeybindingSettings() : undefined;
-    const bindings = bindingSnapshot ?? userSettings.bindings;
-    const passthrough = bindingSnapshot === undefined
-        ? userSettings.tmuxPassthrough
-        : normalizeTmuxPassthrough(passthroughSnapshot);
-    const diagnostics = [];
-    const installed = [];
-    const manifest = readManifest();
-    if (manifest === null) {
-        diagnostics.push({ code: 'tmux-error', message: `tmux is unavailable or ${TMUX_BINDING_MANIFEST} is malformed` });
-        return { ok: false, installed, diagnostics };
-    }
-    const desiredWrappers = new Map();
-    for (const bindingId of passthrough) {
-        const definition = BINDING_CATALOG.find((candidate) => candidate.id === bindingId);
-        if (definition === undefined || !isAttachPaneBinding(definition))
-            continue;
-        for (const gesture of bindings.gestures(bindingId)) {
-            if (gesture.includes(' > '))
-                continue;
-            const key = tmuxKey(gesture);
-            if (!desiredWrappers.has(key))
-                desiredWrappers.set(key, { bindingId, gesture });
-        }
-    }
-    // Restore every wrapper crouter still owns before the ordinary binding sweep.
-    // A live line that differs from the fingerprint is a user's later rebind: it
-    // is protected from this and every later reconciliation until they toggle the
-    // passthrough preference off and on again.
-    const protectedRootKeys = new Set();
-    const wrappers = [];
-    for (const prior of manifest.wrappers) {
-        const desired = desiredWrappers.get(prior.key);
-        const live = bindingAt(ROOT_TABLE, prior.key);
-        if (prior.state === 'relinquished' || live !== prior.wrapper) {
-            protectedRootKeys.add(prior.key);
-            if (desired !== undefined) {
-                wrappers.push({ ...prior, ...desired, state: 'relinquished' });
-            }
-            continue;
-        }
-        const restored = restoreWrappedBinding(prior);
-        if (!restored.ok) {
-            protectedRootKeys.add(prior.key);
-            wrappers.push(prior);
-            diagnostics.push({
-                code: 'tmux-error',
-                bindingId: prior.bindingId,
-                gesture: prior.gesture,
-                message: `could not restore tmux binding ${ROOT_TABLE}:${prior.key}: ${restored.stderr}`,
-            });
-        }
-    }
-    adoptLegacyBindings();
-    removeLegacyInboxBindings(manifest.pairs);
-    for (const pair of manifest.pairs) {
-        if (pair.table === ROOT_TABLE && protectedRootKeys.has(pair.key))
-            continue;
-        const result = tmux(['unbind-key', '-T', pair.table, tmuxKeyArgument(pair.key)]);
-        if (!result.ok && bindingAt(pair.table, pair.key) !== null) {
-            diagnostics.push({ code: 'tmux-error', message: `could not remove crouter binding ${pair.table}:${pair.key}: ${result.stderr}` });
-        }
-    }
-    if (diagnostics.some((diagnostic) => diagnostic.code === 'tmux-error')) {
-        const save = writeManifest({ pairs: manifest.pairs, wrappers });
-        if (!save.ok)
-            diagnostics.push({ code: 'tmux-error', message: `could not save crouter tmux ownership manifest: ${save.stderr}` });
-        return { ok: false, installed, diagnostics };
-    }
-    const install = (table, key, command, id, gesture) => {
-        if (bindingAt(table, key) !== null) {
-            diagnostics.push({ code: 'occupied', bindingId: id, gesture, message: `${table}:${key} is already bound by tmux; ${id} was not installed` });
-            return false;
-        }
-        const result = tmux(['bind-key', '-T', table, tmuxKeyArgument(key), ...command]);
-        if (!result.ok) {
-            diagnostics.push({ code: 'tmux-error', bindingId: id, gesture, message: `could not install ${id}: ${result.stderr}` });
-            return false;
-        }
-        installed.push({ table, key });
-        return true;
-    };
-    const menuActions = resolvedMenuActions(bindings);
-    const menuCommand = buildMenuArgs(' crtr ', menuItems(bindings, menuActions));
-    for (const gesture of bindings.gestures('crtr.tmux.menu.open')) {
-        install(ROOT_TABLE, tmuxKey(gesture), menuCommand, 'crtr.tmux.menu.open', gesture);
-    }
-    for (const definition of BINDING_CATALOG) {
-        if (definition.pair?.field !== 'menu')
-            continue;
-        const paired = BINDING_CATALOG.find((candidate) => candidate.id === definition.pair?.pairedId);
-        if (paired?.pair?.field !== 'global')
-            continue;
-        const menuId = definition.id;
-        const globalId = paired.id;
-        const entry = menuActions.get(menuId);
-        const command = entry === undefined ? null : menuActionCommand(entry.action);
-        if (command === null)
-            throw new Error(`no direct tmux action for paired menu binding ${menuId}`);
-        for (const gesture of bindings.gestures(globalId)) {
-            install(ROOT_TABLE, tmuxKey(gesture), command.argv, globalId, gesture);
-        }
-    }
-    for (const id of ['crtr.tmux.node.next', 'crtr.tmux.node.previous', 'crtr.tmux.inbox.toggle']) {
-        for (const gesture of bindings.gestures(id))
-            install(ROOT_TABLE, tmuxKey(gesture), actionCommand(id), id, gesture);
-    }
-    // Wrap only occupied roots. Unoccupied gestures already reach the pane and do
-    // not need crouter ownership. Re-read the installed line as the fingerprint;
-    // tmux canonicalizes quoting and braces in ways hand serialization cannot.
-    const newlyWrapped = [];
-    for (const [key, desired] of desiredWrappers) {
-        if (protectedRootKeys.has(key))
-            continue;
-        const original = bindingAt(ROOT_TABLE, key);
-        if (original === null)
-            continue;
-        const parsed = parseTmuxBinding(original);
-        if (parsed === null || parsed.command === '') {
-            diagnostics.push({ code: 'tmux-error', bindingId: desired.bindingId, gesture: desired.gesture, message: `could not parse occupied tmux binding ${ROOT_TABLE}:${key}` });
-            continue;
-        }
-        const result = tmux([
-            'bind-key',
-            ...(parsed.repeat ? ['-r'] : []),
-            '-T', ROOT_TABLE, tmuxKeyArgument(key),
-            'if-shell', '-F', '#{!=:#{@crtr_attach},}',
-            `send-keys ${tmuxCommandToken(key)}`,
-            bindingCommandForBranch(parsed.command),
-        ]);
-        if (!result.ok) {
-            diagnostics.push({ code: 'tmux-error', bindingId: desired.bindingId, gesture: desired.gesture, message: `could not wrap ${ROOT_TABLE}:${key}: ${result.stderr}` });
-            continue;
-        }
-        const wrapper = bindingAt(ROOT_TABLE, key);
-        if (wrapper === null || !wrapper.includes('@crtr_attach')) {
-            diagnostics.push({ code: 'tmux-error', bindingId: desired.bindingId, gesture: desired.gesture, message: `could not fingerprint wrapped tmux binding ${ROOT_TABLE}:${key}` });
-            continue;
-        }
-        const record = { ...desired, key, original, wrapper, state: 'owned' };
-        wrappers.push(record);
-        newlyWrapped.push(record);
-    }
-    const save = writeManifest({ pairs: installed, wrappers });
-    if (!save.ok) {
-        diagnostics.push({ code: 'tmux-error', message: `could not save crouter tmux ownership manifest: ${save.stderr}` });
-        // A wrapper without restoration data is unsafe. Put each newly wrapped key
-        // back immediately when manifest persistence fails.
-        for (const wrapper of newlyWrapped) {
-            if (bindingAt(ROOT_TABLE, wrapper.key) === wrapper.wrapper)
-                restoreWrappedBinding(wrapper);
-        }
-    }
-    return { ok: diagnostics.every((diagnostic) => diagnostic.code !== 'tmux-error'), installed, diagnostics };
-}