@north-light/api 0.3.580 → 0.3.588

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

@@ -0,0 +1,743 @@
+// tmux bindings — crouter-owned keybinding manifest persistence and reconciliation.
+//
+// Raw tmux process invocation stays in tmux-driver.ts. This module owns the
+// persistent binding manifest, key parsing, and installation.
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { 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 '../exclusive-lock.js';
+import { surfaceTmuxStyleArgs } from './surface-bg.js';
+import { runTmux as tmux, shellQuote } from './tmux-driver.js';
+// 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' } },
+    'crtr.tmux.menu.dashboard': { description: 'dashboard', action: { kind: 'direct', run: 'surface dashboard --pane {pane}' } },
+    'crtr.tmux.menu.fork': { description: 'fork into idle root', action: { kind: 'direct', run: 'node fork --pane {pane}' } },
+    // Mode demote is the mirror of `/promote`: `node config` persists the change;
+    // the broker appends its pending context before the next provider response.
+    'crtr.tmux.menu.demote-mode': { description: 'demote to base node', action: { kind: 'command', run: 'node config --mode base --pane {pane}' } },
+    'crtr.tmux.menu.demote': { description: 'demote to terminal (finish when done)', action: { kind: 'command', run: 'node lifecycle demote --pane {pane}' } },
+    'crtr.tmux.menu.make-resident': { description: 'make resident (interactable)', action: { kind: 'command', run: 'node config --lifecycle resident --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.show-working': { description: 'show/hide working', action: { kind: 'keys', keys: '/show-working' } },
+    'crtr.tmux.menu.context': { description: 'context + reports', action: { kind: 'keys', keys: '/context' } },
+    // The settings page lays out a grouped rail beside a content panel; the
+    // default dialog-sized popup clipped both the rail and the models matrix.
+    'crtr.tmux.menu.providers': { description: 'settings', action: { kind: 'popup', run: 'sys settings', size: { w: '90%', h: '85%' } } },
+    // A snapshot-built menu cannot render live toggle state, so this opens the
+    // panel rather than flipping a setting from the menu row.
+    'crtr.tmux.menu.provider-options': { description: 'provider options', action: { kind: 'popup', run: 'sys settings --page provider-options', size: { w: '90%', h: '85%' } } },
+    'crtr.tmux.menu.plugins': { description: 'plugins', action: { kind: 'popup', run: 'pkg browse', size: { w: '90%', h: '85%' } } },
+    'crtr.tmux.menu.analytics': { description: 'analytics', action: { kind: 'popup', run: 'canvas analytics --pane {pane}', size: { w: '90%', h: '85%' } } },
+    // Three zones side by side over a corpus of hundreds of documents: the list
+    // spends every column it is given on canonical names. Near-full rather than
+    // full, so the pane border still marks it as a popup.
+    'crtr.tmux.menu.context-admin': { description: 'context surface', action: { kind: 'popup', run: 'sys context admin', size: { w: '98%', h: '96%' } } },
+    '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(' ');
+}
+/** Popups default to a small dialog. A surface that has to lay out its own
+ *  navigation and a content panel side by side asks for the larger size. */
+const DEFAULT_POPUP_SIZE = { w: '60%', h: '50%' };
+function chordCommand(run, interactive = false, size = DEFAULT_POPUP_SIZE) {
+    const command = `crtr canvas chord --pane '#{pane_id}' --run ${shellQuote(escapeTmuxFormats(run))}${interactive ? ' --interactive' : ''}`;
+    return interactive
+        ? {
+            argv: ['display-popup', '-E', '-w', size.w, '-h', size.h, '-d', '#{pane_current_path}', command],
+            menu: `display-popup -E -w ${size.w} -h ${size.h} -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, action.size);
+        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) {
+    return tmuxKeyNames(stroke)[0];
+}
+/** Every tmux key name one physical chord can arrive as, most specific first.
+ *
+ *  tmux derives the name from the bytes the terminal sent, and a terminal sends
+ *  different bytes for the same chord depending on whether extended keys are
+ *  active — which changes per pane, since the pane's application turns them on.
+ *  tmux does not normalize across those encodings, so a chord bound under one
+ *  name is simply dead under the others. Verified against tmux 3.7b by writing
+ *  raw bytes to an attached client; for Alt+Shift+F:
+ *
+ *    ESC F           (legacy meta prefix)                -> `M-F`
+ *    ESC [70;4u  / ESC [27;4;70~   (shifted keysym)      -> `M-S-F`
+ *    ESC [102;4u / ESC [27;4;102~  (base keysym)         -> `M-S-f`
+ *
+ *  Shift alone never survives as a modifier — every encoding of Shift+G lands
+ *  on `G` — so only chords that pair Shift with Ctrl or Alt carry aliases. */
+function tmuxKeyNames(stroke) {
+    let { key, modifiers: modifierParts } = normalizedStrokeParts(stroke);
+    const modifiers = new Set(modifierParts);
+    const name = (character, shift) => [
+        modifiers.has('ctrl') ? 'C-' : '',
+        modifiers.has('alt') ? 'M-' : '',
+        shift ? 'S-' : '',
+        TMUX_NAMED_KEYS[character] ?? character,
+    ].join('');
+    if (modifiers.has('shift') && key.length === 1 && /[a-z]/.test(key)) {
+        const shifted = key.toUpperCase();
+        // Shift-only: tmux always collapses it into the uppercase character.
+        if (!modifiers.has('ctrl') && !modifiers.has('alt'))
+            return [name(shifted, false)];
+        return [name(shifted, true), name(shifted, false), name(key, true)];
+    }
+    return [name(key, modifiers.has('shift'))];
+}
+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', 'crtr.tmux.menu.show-working'], 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.dashboard',
+        '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-mode',
+        'crtr.tmux.menu.demote',
+        'crtr.tmux.menu.make-resident',
+        'crtr.tmux.menu.detach',
+        'crtr.tmux.menu.close-subtree',
+    ]));
+    addGroup('System', boundItems([
+        'crtr.tmux.menu.providers',
+        'crtr.tmux.menu.provider-options',
+        'crtr.tmux.menu.plugins',
+        'crtr.tmux.menu.analytics',
+        'crtr.tmux.menu.context-admin',
+        '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;
+}
+/** The argv of the exact `display-menu` Alt+C installs, for a caller that has no
+ *  key to press — the viewer's `/menu`. The menu is built from the same
+ *  resolved bindings and actions, so it can never drift from the keyboard path.
+ *  Run it with `-t <pane>` so the `#{pane_id}` formats resolve to that pane. */
+export function crouterMenuTmuxArgs(bindingSnapshot) {
+    const bindings = bindingSnapshot ?? resolveUserKeybindingSettings().bindings;
+    return buildMenuArgs(' crtr ', menuItems(bindings, resolvedMenuActions(bindings)));
+}
+/** 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(' > ') && tmuxKeyNames(gesture).some((key) => occupied.has(key)));
+}
+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);
+}
+// --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 surface inbox --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;
+            for (const key of tmuxKeyNames(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 matches neither the fingerprint nor the original crouter
+    // recorded 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.
+    //
+    // A live line equal to the ORIGINAL is not a rebind. It is the user's own tmux
+    // config re-sourced over the wrapper, which every `source-file` and every fresh
+    // tmux server does. Relinquishing there disarmed passthrough silently and
+    // permanently for anyone whose config binds a key crouter wraps, so that case
+    // falls through with nothing to restore — the wrap pass below re-reads the live
+    // line as the original and wraps it again. It also releases a key already stuck
+    // relinquished: matching the recorded original is proof the user did not rebind
+    // it to something of their own.
+    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 (live !== null && live === prior.original)
+            continue;
+        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}`,
+            });
+        }
+    }
+    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')) {
+        for (const key of tmuxKeyNames(gesture))
+            install(ROOT_TABLE, key, 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)) {
+            for (const key of tmuxKeyNames(gesture))
+                install(ROOT_TABLE, key, 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)) {
+            for (const key of tmuxKeyNames(gesture))
+                install(ROOT_TABLE, key, 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 };
+}