@north-light/crouter 0.3.170 → 0.3.172

package/dist/core/runtime/tmux.js

@@ -7,14 +7,15 @@
 // 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 { 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, encodeAttachControlInput, formatGesture, resolveUserKeybindings, } from '../keybindings/index.js';
+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';
-import { inboxToggleTmuxCommand } from '@crouton-kit/humanloop';
 // ---------------------------------------------------------------------------
 // Shell quoting + tmux invocation
 // ---------------------------------------------------------------------------
@@ -30,6 +31,9 @@ function tmux(args) {
         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'] !== '';
 }
@@ -311,8 +315,7 @@ export function listLivePanes() {
     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. */
+ *  '#{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;
@@ -329,8 +332,6 @@ export function displayMessage(message, pane, ms = 4000) {
     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;
@@ -342,6 +343,121 @@ 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
@@ -472,12 +588,12 @@ 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: 'resume node', action: { kind: 'keys', keys: '/resume-node' } },
+    '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 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.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 bash command', action: { kind: 'direct', run: 'node bash background --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.
@@ -486,10 +602,11 @@ const LEAF_MENU_ACTIONS = {
     '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: '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.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' } },
@@ -601,10 +718,17 @@ const TMUX_NAMED_KEYS = {
     space: 'Space', up: 'Up', down: 'Down', left: 'Left', right: 'Right',
     pageup: 'PPage', pagedown: 'NPage', home: 'Home', end: 'End',
 };
-function tmuxKey(stroke) {
+function normalizedStrokeParts(stroke) {
+    if (stroke === '+')
+        return { key: '+', modifiers: [] };
+    if (stroke.endsWith('++'))
+        return { key: '+', modifiers: stroke.slice(0, -2).split('+') };
     const parts = stroke.split('+');
-    let key = parts.pop();
-    const modifiers = new Set(parts);
+    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
@@ -622,9 +746,8 @@ function tmuxKey(stroke) {
     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;
+    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 = [];
@@ -659,8 +782,8 @@ function resolvedMenuActions(bindings) {
     const attachItems = boundMenuItems(ATTACH_CONTROL_BINDINGS.map(({ menuId }) => menuId), entries, bindings);
     if (attachItems.length > 0) {
         entries.set('crtr.tmux.menu.attach', {
-            description: 'attach ›',
-            action: { kind: 'submenu', title: ' attach ', items: attachItems },
+            description: 'attach viewer ›',
+            action: { kind: 'submenu', title: ' attach viewer ', items: attachItems },
         });
     }
     const showItems = boundMenuItems([
@@ -668,8 +791,8 @@ function resolvedMenuActions(bindings) {
         'crtr.tmux.menu.context',
     ], entries, bindings);
     entries.set('crtr.tmux.menu.show', {
-        description: 'show ›',
-        action: { kind: 'submenu', title: ' show node ', items: showItems },
+        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
@@ -677,8 +800,8 @@ function resolvedMenuActions(bindings) {
     // 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: 'view settings ›',
-        action: { kind: 'submenu', title: ' view settings ', items: viewSettingsItems },
+        description: 'display ›',
+        action: { kind: 'submenu', title: ' display ', items: viewSettingsItems },
     });
     const issueItems = boundMenuItems([
         'crtr.tmux.menu.issue.idea',
@@ -716,6 +839,7 @@ function menuItems(bindings, entries) {
         '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',
@@ -743,37 +867,194 @@ function menuItems(bindings, entries) {
     }
     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 match = line.match(/^bind-key\s+(?:-r\s+)?-T\s+\S+\s+(\S+)\s+/);
-        return match?.[1] === key;
+        const parsed = parseTmuxBinding(line);
+        return parsed?.table === table && parsed.key === key;
     }) ?? null;
 }
-function sequenceTable(prefix) {
-    return `crtr-${Buffer.from(prefix).toString('hex')}`;
+/** 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: [], existed: false };
+        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);
-        if (!Array.isArray(value) || value.some((pair) => typeof pair !== 'object' || pair === null || typeof pair.table !== 'string' || typeof pair.key !== 'string'))
+        // 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: value, existed: true };
+        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
@@ -838,18 +1119,49 @@ function removeLegacyInboxBindings(manifestPairs) {
     }
     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();
-        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()) {
+/** 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();
@@ -857,15 +1169,61 @@ export function installTmuxBindings(bindings = resolveUserKeybindings()) {
         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) {
-        const result = tmux(['unbind-key', '-T', pair.table, pair.key]);
+        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) => {
@@ -873,7 +1231,7 @@ export function installTmuxBindings(bindings = resolveUserKeybindings()) {
             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]);
+        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;
@@ -906,32 +1264,51 @@ export function installTmuxBindings(bindings = resolveUserKeybindings()) {
         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);
+    // 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;
         }
-    }
-    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` });
+        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 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 record = { ...desired, key, original, wrapper, state: 'owned' };
+        wrappers.push(record);
+        newlyWrapped.push(record);
     }
-    const save = tmux(['set-option', '-s', TMUX_BINDING_MANIFEST, JSON.stringify(installed)]);
-    if (!save.ok)
+    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 };
 }