@north-light/crouter 0.3.154

package/dist/core/runtime/tmux.js

@@ -0,0 +1,858 @@
+// 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 { spawnSync } from 'node:child_process';
+import { readFileSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { formatGesture, resolveUserKeybindings, } from '../keybindings/index.js';
+import { bundledPiCommandForShell } from './pi-cli.js';
+import { surfaceTmuxStyleArgs } from './surface-bg.js';
+import { inboxToggleTmuxCommand } from '@crouton-kit/humanloop';
+// ---------------------------------------------------------------------------
+// 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(),
+    };
+}
+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}'`). Used to preserve a view monitor's cwd across a
+ *  view-cycle respawn so project-scoped views still resolve. 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>`).
+ *  Used to tag a pane with the view id it currently hosts (`@crtr_view`) so the
+ *  view-nav cycle can read it back and switch to the next/prev view in place.
+ *  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;
+}
+/** 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 MENU_ACTIONS = {
+    'crtr.tmux.menu.promote': { description: 'promote to orchestrator', action: { kind: 'keys', keys: '/promote' } },
+    'crtr.tmux.menu.resume': { description: 'resume 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 to terminal', action: { kind: 'command', run: 'node lifecycle demote --pane {pane}' } },
+    'crtr.tmux.menu.detach': { description: 'detach to background', 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 bash command', 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.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: 'graph view', action: { kind: 'keys', keys: '/graph' } },
+    'crtr.tmux.menu.focus-manager': { description: 'focus 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.pin': { description: 'pin conversation', action: { kind: 'direct', run: 'surface node pin --pane {pane}' } },
+    'crtr.tmux.menu.open': undefined,
+    'crtr.tmux.menu.show': undefined,
+    'crtr.tmux.menu.issues': undefined,
+    'crtr.tmux.menu.issue.idea': undefined,
+    'crtr.tmux.menu.issue.bug': undefined,
+    'crtr.tmux.node.next': undefined,
+    'crtr.tmux.node.previous': undefined,
+    'crtr.tmux.inbox.toggle': undefined,
+    'crtr.tmux.view.next': undefined,
+    'crtr.tmux.view.previous': undefined,
+};
+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
+        ? `display-popup -E -w 60% -h 50% -d "#{pane_current_path}" ${shellQuote(command)}`
+        : `run-shell ${shellQuote(`${command} >/dev/null 2>&1`)}`;
+}
+/** Dispatch a menu 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
+ *  selection 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 the menu selection non-blocking. */
+function directCommand(run) {
+    const argv = escapeTmuxFormats(run).replace('{pane}', '#{pane_id}');
+    return `run-shell -b ${shellQuote(`crtr ${argv} >/dev/null 2>&1`)}`;
+}
+function renderMenuAction(action) {
+    switch (action.kind) {
+        case 'disabled': return '';
+        case 'separator': return '';
+        // 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 'refresh-client';
+        case 'keys': return `send-keys -t '#{pane_id}' ${shellQuote(escapeTmuxFormats(action.keys))} Enter`;
+        case 'raw-keys': return `send-keys -t '#{pane_id}' ${shellQuote(escapeTmuxFormats(action.keys))}`;
+        case 'command': return chordCommand(action.run);
+        case 'direct': return directCommand(action.run);
+        case 'popup': return chordCommand(action.run, true);
+        case 'submenu': return tmuxCommand(buildMenuArgs(action.title, action.items));
+    }
+}
+/** 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 tmuxKey(stroke) {
+    const parts = stroke.split('+');
+    let key = parts.pop();
+    const modifiers = new Set(parts);
+    if (modifiers.has('shift') && key.length === 1 && /[a-z]/.test(key)) {
+        key = key.toUpperCase();
+        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 parts = stroke.split('+');
+    const key = parts.at(-1);
+    return parts.includes('shift') && /[a-z]/.test(key) ? key.toUpperCase() : key === 'space' ? ' ' : key;
+}
+function menuItems(bindings) {
+    const boundItems = (ids) => {
+        const items = [];
+        for (const id of ids) {
+            const entry = MENU_ACTIONS[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;
+    };
+    const issueItems = [];
+    for (const [id, description, type] of [
+        ['crtr.tmux.menu.issue.idea', 'idea', 'idea'],
+        ['crtr.tmux.menu.issue.bug', 'bug', 'bug'],
+    ]) {
+        for (const gesture of bindings.gestures(id)) {
+            issueItems.push({ description, selector: menuSelector(gesture), action: { kind: 'popup', run: `canvas issue new --type ${type}` } });
+        }
+    }
+    const lifecycleItems = boundItems([
+        'crtr.tmux.menu.promote',
+        'crtr.tmux.menu.demote',
+        'crtr.tmux.menu.detach',
+        'crtr.tmux.menu.close-subtree',
+    ]);
+    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);
+    };
+    const showItems = boundItems([
+        'crtr.tmux.menu.metadata',
+        'crtr.tmux.menu.context',
+    ]);
+    const exploreItems = boundItems([
+        'crtr.tmux.menu.resume',
+        'crtr.tmux.menu.graph',
+        'crtr.tmux.menu.focus-manager',
+    ]);
+    if (showItems.length > 0) {
+        for (const gesture of bindings.gestures('crtr.tmux.menu.show')) {
+            exploreItems.push({
+                description: 'show ›',
+                selector: menuSelector(gesture),
+                action: { kind: 'submenu', title: ' show node ', items: showItems },
+            });
+        }
+    }
+    // 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', exploreItems);
+    addGroup('Current node', boundItems([
+        'crtr.tmux.menu.background-bash',
+        'crtr.tmux.menu.file-review',
+        'crtr.tmux.menu.pin',
+        'crtr.tmux.menu.copy-id',
+        'crtr.tmux.menu.reload-viewer',
+    ]));
+    addGroup('Lifecycle', [
+        ...boundItems(['crtr.tmux.menu.fork']),
+        ...lifecycleItems,
+    ]);
+    const systemItems = boundItems(['crtr.tmux.menu.providers']);
+    if (issueItems.length > 0) {
+        for (const gesture of bindings.gestures('crtr.tmux.menu.issues')) {
+            systemItems.push({
+                description: 'create ›',
+                selector: menuSelector(gesture),
+                action: { kind: 'submenu', title: ' create ', items: issueItems },
+            });
+        }
+    }
+    addGroup('System', systemItems);
+    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;
+}
+function bindingAt(table, key) {
+    const result = tmux(['list-keys', '-T', table]);
+    if (!result.ok)
+        return null;
+    return result.stdout.split('\n').find((line) => {
+        const match = line.match(/^bind-key\s+(?:-r\s+)?-T\s+\S+\s+(\S+)\s+/);
+        return match?.[1] === key;
+    }) ?? null;
+}
+function sequenceTable(prefix) {
+    return `crtr-${Buffer.from(prefix).toString('hex')}`;
+}
+function readManifest() {
+    const option = tmux(['show-options', '-s', '-q', TMUX_BINDING_MANIFEST]);
+    if (!option.ok)
+        return null;
+    if (option.stdout === '')
+        return { pairs: [], existed: false };
+    const result = tmux(['show-options', '-s', '-qv', TMUX_BINDING_MANIFEST]);
+    if (!result.ok)
+        return null;
+    try {
+        const value = JSON.parse(result.stdout);
+        if (!Array.isArray(value) || value.some((pair) => typeof pair !== 'object' || pair === null || typeof pair.table !== 'string' || typeof pair.key !== 'string'))
+            return null;
+        return { pairs: value, existed: true };
+    }
+    catch {
+        return null;
+    }
+}
+// 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 */ }
+}
+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();
+        case 'crtr.tmux.view.next': return ['run-shell', `crtr surface view cycle --dir next --pane '#{pane_id}' >/dev/null 2>&1`];
+        case 'crtr.tmux.view.previous': return ['run-shell', `crtr surface view cycle --dir prev --pane '#{pane_id}' >/dev/null 2>&1`];
+        default: throw new Error(`no tmux command for ${id}`);
+    }
+}
+/** Reconcile the tmux server with one immutable crouter binding snapshot. */
+export function installTmuxBindings(bindings = resolveUserKeybindings()) {
+    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 };
+    }
+    adoptLegacyBindings();
+    removeLegacyInboxBindings(manifest.pairs);
+    for (const pair of manifest.pairs) {
+        const result = tmux(['unbind-key', '-T', pair.table, 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')) {
+        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, 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 menuCommand = buildMenuArgs(' crtr ', menuItems(bindings));
+    for (const gesture of bindings.gestures('crtr.tmux.menu.open')) {
+        install(ROOT_TABLE, tmuxKey(gesture), menuCommand, 'crtr.tmux.menu.open', 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);
+    }
+    const sequences = new Map();
+    for (const id of ['crtr.tmux.view.next', 'crtr.tmux.view.previous']) {
+        for (const gesture of bindings.gestures(id)) {
+            const [first, second] = gesture.split(' > ');
+            const prefix = tmuxKey(first);
+            const entries = sequences.get(prefix) ?? [];
+            entries.push({ id, gesture, second: tmuxKey(second) });
+            sequences.set(prefix, entries);
+        }
+    }
+    for (const [prefix, entries] of sequences) {
+        if (bindingAt(ROOT_TABLE, prefix) !== null) {
+            for (const entry of entries)
+                diagnostics.push({ code: 'occupied', bindingId: entry.id, gesture: entry.gesture, message: `${ROOT_TABLE}:${prefix} is already bound by tmux; ${entry.id} was not installed` });
+            continue;
+        }
+        const table = sequenceTable(prefix);
+        let children = 0;
+        for (const entry of entries)
+            if (install(table, entry.second, actionCommand(entry.id), entry.id, entry.gesture))
+                children++;
+        if (children > 0)
+            install(ROOT_TABLE, prefix, ['switch-client', '-T', table], entries[0].id, entries[0].gesture);
+    }
+    const save = tmux(['set-option', '-s', TMUX_BINDING_MANIFEST, JSON.stringify(installed)]);
+    if (!save.ok)
+        diagnostics.push({ code: 'tmux-error', message: `could not save crouter tmux ownership manifest: ${save.stderr}` });
+    return { ok: diagnostics.every((diagnostic) => diagnostic.code !== 'tmux-error'), installed, diagnostics };
+}