@north-light/api 0.3.580 → 0.3.587

package/dist/clients/attach/slash/dispatch.js

@@ -0,0 +1,748 @@
+// slash/dispatch.ts — builtin slash-command parse + dispatch for `crtr surface attach` (C6).
+//
+// Builtin slash commands are NOT engine-interpreted: `session.prompt('/model')`
+// ships "/model" to the LLM as literal text. So the viewer recognizes the 21
+// vendored `BUILTIN_SLASH_COMMANDS` itself and dispatches the matching
+// `ClientToBroker` command frame; only EXTENSION commands (anything the viewer
+// doesn't recognize) fall through to be sent as a `prompt` for the engine's
+// extension runner to handle.
+//
+// SELECTORS — native interactive pickers. `/model`, `/resume`, `/fork`, `/tree`,
+// `/settings`, `/scoped-models` open pi's real `*SelectorComponent`s as overlays,
+// fed by the operator-view read-op `data` frames (broker-protocol) over the
+// socket. With no arg they open the picker (via the `openXPicker` SlashContext
+// callbacks the InputController exposes, fed by its read-op request channel —
+// which viewer.ts MUST wire via `onRequest: (f) => socket.request(f)`). With an
+// arg the same resolved value is sent directly (`/model <provider/id>`, `/resume
+// <path>`, `/fork <entryId>`, `/tree <entryId>`) without the UI. If the request
+// channel is unwired the picker degrades to the arg-form notice. (Verified
+// against pi 0.79.1 — `ScopedModelsSelectorComponent` is the one selector pi does
+// not re-export, so /scoped-models renders read-only via a SelectList.)
+//
+// SCOPED OUT (no engine method): `/login`, `/logout`, `/share`,
+// `/trust` — a brief "not supported in attach" notice, never a frame.
+import { execFile } from 'node:child_process';
+import { BUILTIN_SLASH_COMMANDS } from '../../../core/runtime/pi-vendored.js';
+import { surfaceTmuxStyleArgs } from '../../../core/runtime/surface-bg.js';
+import { crouterMenuTmuxArgs } from '../../../core/runtime/tmux-bindings.js';
+import { viewerOperationForSlash } from '../input/capabilities.js';
+import { shellQuote } from '../../../shared/shell-quote.js';
+/** Canvas slash-commands — implemented NATIVE in the viewer, the ONLY live host:
+ *  the broker binds mode:'rpc', so broker pi-extensions never run their
+ *  interactive (mode==='tui') paths. `/promote` triggers a turn after shelling
+ *  `crtr node promote`; `/resume-node` and `/context` each shell a `crtr`
+ *  subcommand via `tmux display-popup` (the viewer runs inside a tmux pane);
+ *  `/graph` toggles the in-process overlay. Exported so the editor folds these
+ *  into the slash autocomplete list. */
+export const CANVAS_SLASH_COMMANDS = [
+    { name: 'tutorial', description: 'The guided crouter tutorial — your agent teaches it, one lesson at a time' },
+    { name: 'menu', description: 'Open the crouter action menu — the same menu as Alt+C, for when Option/Alt does not work in your terminal' },
+    { name: 'clear', description: 'Clear the conversation and free context — a fresh, empty session (like /new)' },
+    { name: 'graph', description: 'Toggle the canvas GRAPH view (your local subscription tree)' },
+    { name: 'inbox', description: 'Toggle the human inbox — pending asks and reviews for you' },
+    { name: 'promote', description: 'Promote this node to an orchestrator — /promote, or /promote <kind> to specialize' },
+    { name: 'resume', description: 'Open the canvas navigator and swap THIS pane onto the chosen node; parked residents wake only on submitted input' },
+    { name: 'resume-session', description: 'Switch this node onto one of its saved pi sessions — picker, or /resume-session <session-path>' },
+    { name: 'context', description: 'Browse the files in this node’s and its subscriptions’ context dirs in a read-only nvim popup' },
+    { name: 'plugins', description: 'Open the interactive plugin browser for this machine' },
+    { name: 'node-metadata', description: 'Inspect this node — identity, lifecycle, runtime, graph, output, paths, and agent surfaces' },
+    { name: 'mcp', description: 'MCP servers — status from the adapter’s config/cache; Enter (or /mcp <server>) connects, reconnects, or re-auths' },
+    { name: 'rename', description: 'Rename this node everywhere — node row, viewer window, session chip, tmux pane: /rename <name>' },
+    { name: 'color', description: 'Color this node — tmux pane outline + name chip: /color <color> (red, blue, #rrggbb, …) or /color none' },
+    { name: 'mouse', description: 'Toggle mouse wheel scrolling and drag-select — off restores tmux drag-select and copy-mode mouse' },
+    { name: 'copy-message', description: 'Copy the newest message visible in the transcript viewport' },
+    { name: 'copy-tool', description: 'Copy the newest tool call output' },
+    { name: 'copy-transcript', description: 'Copy every copyable transcript block' },
+    { name: 'fold-tools', description: 'View setting — fold every FINISHED tool call to its single call line (Alt+C → z → f)' },
+    { name: 'show-working', description: 'Consolidated replies — show or hide the working behind each reply (Alt+C → z → w)' },
+];
+/** Prior names still dispatched natively but kept OUT of autocomplete, so
+ *  muscle memory keeps working while the palette shows one canonical entry.
+ *  Normalized to the canonical name before any gate or dispatch runs. */
+const CANVAS_ALIASES = new Map([['resume-node', 'resume']]);
+const CANVAS_NAMES = new Set([...CANVAS_SLASH_COMMANDS.map((c) => c.name), ...CANVAS_ALIASES.keys()]);
+/** tmux named colours accepted by `/color` (plus `colourN`/`#rrggbb`, validated
+ *  by pattern). Mirrors tmux's colour-name table so a typo is rejected with the
+ *  options rather than silently ignored by tmux. */
+const TMUX_NAMED_COLORS = new Set([
+    'black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white',
+    'brightred', 'brightgreen', 'brightyellow', 'brightblue', 'brightmagenta', 'brightcyan',
+    'orange', 'grey', 'gray', 'default',
+]);
+/** Builtins with no engine method — scoped out. */
+const SCOPED_OUT = new Set(['trust']);
+/** Valid `/settings thinking` levels — the `SetThinkingLevelFrame['level']`
+ *  union (= AgentSession['thinkingLevel'], pi-agent-core ThinkingLevel),
+ *  mirrored as a runtime set so an invalid arg is rejected with the options
+ *  rather than shipped as a frame the engine would throw on. Built from a
+ *  `Record<level, true>` so the build fails BOTH ways if the union drifts: a
+ *  missing key (union GAINED a level) or an extra key (union dropped one). */
+const THINKING_LEVELS = new Set(Object.keys({
+    off: true,
+    minimal: true,
+    low: true,
+    medium: true,
+    high: true,
+    xhigh: true,
+    max: true,
+}));
+const BUILTIN_NAMES = new Set(BUILTIN_SLASH_COMMANDS.map((c) => c.name));
+function nodeIdFor(ctx) {
+    return ctx.capabilities.nodeId;
+}
+function profileIdFor(ctx) {
+    return ctx.capabilities.profileId;
+}
+function readOnlyRefusal(name, ctx) {
+    const operation = viewerOperationForSlash(name, BUILTIN_NAMES.has(name), CANVAS_NAMES.has(name));
+    return operation === undefined ? undefined : ctx.capabilities.refusal(operation, name);
+}
+/** Every leading-command name this viewer consumes ENTIRELY locally — the
+ *  message never reaches the engine as prose, whether dispatched or blocked
+ *  with a notice (a remote-unsafe canvas/builtin command still returns
+ *  `true` from `dispatchSlashCommand` — swallowed with a notice, never
+ *  forwarded as prose — so it counts as consumed here too, independent of
+ *  `remote`). Exactly BUILTIN_NAMES ∪ CANVAS_NAMES ∪ SCOPED_OUT — every name
+ *  `dispatchSlashCommand` returns `true` for. Used ONLY for terminal
+ *  ref-decoration suppression (`input/titled-editor.ts`); never merged into
+ *  command completion, which is `slashCommandList` — a different,
+ *  remote-filtered, broker-augmented list. */
+export function locallyConsumedCommandNames() {
+    return new Set([...BUILTIN_NAMES, ...CANVAS_NAMES, ...SCOPED_OUT]);
+}
+function parseSlashCommand(text) {
+    const match = /^\/(\S+)\s*([\s\S]*)$/.exec(text.trim());
+    return match === null ? undefined : { name: match[1], arg: match[2].trim() };
+}
+/** True if `text` is a leading-slash command (vs. a normal prompt). */
+export function isSlashCommand(text) {
+    return text.trimStart().startsWith('/');
+}
+/**
+ * Parse + dispatch a leading-slash command. Returns `true` if it was handled
+ * (a recognized builtin or a scoped-out notice) — the caller then clears the
+ * editor and sends nothing else. Returns `false` for an UNRECOGNIZED command,
+ * which the caller forwards to the engine as a `prompt` (extension command).
+ */
+export function dispatchSlashCommand(text, ctx) {
+    const command = parseSlashCommand(text);
+    if (command === undefined)
+        return false;
+    const { arg } = command;
+    const name = CANVAS_ALIASES.get(command.name) ?? command.name;
+    if (SCOPED_OUT.has(name)) {
+        ctx.notify(`/${name} is not supported in attach (Phase 4)`);
+        return true;
+    }
+    // Canvas commands (reimplemented native in the viewer) — handled before the
+    // builtin gate since they are neither pi builtins nor engine-extension commands.
+    if (CANVAS_NAMES.has(name)) {
+        const refusal = readOnlyRefusal(name, ctx);
+        if (refusal !== undefined) {
+            ctx.notify(refusal);
+            return true;
+        }
+        return dispatchCanvasCommand(name, arg, ctx);
+    }
+    // Unknown to us AND not a builtin → let the engine's extension runner have it.
+    if (!BUILTIN_NAMES.has(name))
+        return false;
+    const refusal = readOnlyRefusal(name, ctx);
+    if (refusal !== undefined) {
+        ctx.notify(refusal);
+        return true;
+    }
+    switch (name) {
+        // direct frames
+        case 'new':
+            ctx.send({ type: 'new_session' });
+            return true;
+        case 'reload':
+            ctx.send({ type: 'reload' });
+            return true;
+        case 'compact':
+            ctx.send({ type: 'compact', instructions: arg || undefined });
+            return true;
+        case 'quit':
+            // A viewer "quit" DETACHES — the shared engine keeps running (one-writer).
+            // onQuit tears the viewer down locally (which sends `bye` itself). Falling
+            // back to a bare `bye` would just make the broker close the socket, which
+            // the viewer reconnects to — so the detach MUST go through onQuit.
+            if (ctx.onQuit) {
+                ctx.onQuit();
+                return true;
+            }
+            ctx.send({ type: 'bye' });
+            ctx.notify('Detaching — the engine keeps running');
+            return true;
+        // frames needing one argument
+        case 'name':
+            if (!arg)
+                return usage(ctx, '/name <display name>');
+            ctx.send({ type: 'set_session_name', name: arg });
+            return true;
+        case 'export': {
+            const { path, format } = parseExport(arg, ctx.cwd ?? process.cwd());
+            ctx.send({ type: 'export', path, format });
+            ctx.notify(`Exporting session → ${path}`);
+            return true;
+        }
+        case 'import':
+            // `/import` resumes a session built from a JSONL file → switch_session.
+            if (!arg)
+                return usage(ctx, '/import <path-to-session.jsonl>');
+            ctx.send({ type: 'switch_session', path: arg });
+            return true;
+        // value-picker builtins: native picker (no arg) OR direct value (arg)
+        case 'model':
+            if (!arg)
+                return openOrHint(ctx.openModelPicker, ctx, 'model', '/model <provider/id>');
+            ctx.send({ type: 'set_model', model: arg });
+            return true;
+        case 'fork':
+            if (!arg)
+                return openOrHint(ctx.openForkPicker, ctx, 'fork point', '/fork <entryId>');
+            ctx.send({ type: 'fork', entryId: arg });
+            return true;
+        case 'tree':
+            if (!arg)
+                return openOrHint(ctx.openTreePicker, ctx, 'tree', '/tree <entryId>');
+            ctx.send({ type: 'navigate_tree', targetId: arg });
+            return true;
+        case 'scoped-models':
+            if (ctx.openScopedModelsPicker) {
+                ctx.openScopedModelsPicker();
+                return true;
+            }
+            ctx.notify('The scoped-models view needs the read-op channel, which this viewer has not wired');
+            return true;
+        // settings (sub-command form; interactive menu needs read ops)
+        case 'settings':
+            return handleSettings(arg, ctx);
+        // read-only / informational
+        case 'session':
+            ctx.notify(describeSession(ctx.state));
+            return true;
+        case 'copy':
+            // Copy the last assistant message to the clipboard — viewer-owned (the text
+            // is in the ChatView; no engine round-trip). viewer.ts does the actual copy.
+            if (ctx.onCopy) {
+                ctx.onCopy();
+                return true;
+            }
+            ctx.notify('/copy is not available in this viewer');
+            return true;
+        // auth commands — viewer-local OAuth/API-key flows
+        case 'login':
+            if (ctx.openLoginPicker) {
+                ctx.openLoginPicker();
+                return true;
+            }
+            ctx.notify('/login is not available in this viewer');
+            return true;
+        case 'logout':
+            if (ctx.openLogoutPicker) {
+                ctx.openLogoutPicker();
+                return true;
+            }
+            ctx.notify('/logout is not available in this viewer');
+            return true;
+        // share / clone / changelog
+        case 'share':
+            ctx.send({ type: 'share' });
+            ctx.notify('Sharing session…');
+            return true;
+        case 'clone':
+            ctx.send({ type: 'clone' });
+            ctx.notify('Cloning session…');
+            return true;
+        case 'changelog':
+            ctx.notify('/changelog: see https://github.com/earendil-works/pi for release notes (no bundled changelog in this build)');
+            return true;
+        case 'hotkeys':
+            if (ctx.onHelp) {
+                ctx.onHelp();
+                return true;
+            }
+            ctx.notify('/hotkeys is not available in this viewer');
+            return true;
+        // recognized builtins with no Phase-4 wire path
+        default:
+            // A builtin we listed but didn't special-case: treat as unsupported
+            // rather than leak it to the LLM as literal text.
+            ctx.notify(`/${name} is not available in attach (Phase 4)`);
+            return true;
+    }
+}
+/** Append the native canvas commands to a command list, skipping any already
+ *  present (so they survive whatever list Unit Q feeds in — builtins, or the
+ *  broker's `get_commands` result). The canvas commands are viewer-owned,
+ *  so they are always surfaced in autocomplete regardless of the source list —
+ *  EXCEPT commands its capability object does not permit, which are structurally
+ *  omitted rather than offered-then-blocked, so autocomplete never advertises a
+ *  command `dispatchCanvasCommand` would refuse to run. */
+function withCanvasCommands(commands, capabilities) {
+    const permitted = (name) => {
+        const operation = viewerOperationForSlash(name, false, true);
+        return operation === undefined || capabilities.permits(operation);
+    };
+    const offerable = CANVAS_SLASH_COMMANDS.filter((command) => permitted(command.name));
+    // A canvas command that REPURPOSES a builtin name (`/resume`) keeps that name's
+    // slot in the incoming list but carries the canvas description and the canvas
+    // capability gate — so autocomplete never advertises pi's meaning for a command
+    // this viewer redefines, and never offers one it would refuse to run.
+    const canvasByName = new Map(CANVAS_SLASH_COMMANDS.map((command) => [command.name, command]));
+    const merged = commands.flatMap((command) => {
+        const canvas = canvasByName.get(command.name);
+        if (canvas === undefined)
+            return [command];
+        return permitted(command.name) ? [canvas] : [];
+    });
+    const seen = new Set(commands.map((c) => c.name));
+    return [...merged, ...offerable.filter((command) => !seen.has(command.name))];
+}
+/** Build slash-command autocomplete entries from the merged command list (the
+ *  broker's `get_commands` result, which T7 may inject) — defaults to the
+ *  vendored builtins. The native canvas commands are always appended (minus the
+ *  remote-unsafe ones when `remote`). Shaped for pi-tui's `CombinedAutocompleteProvider`. */
+export function slashCommandList(commands, capabilities) {
+    return withCanvasCommands(commands ?? BUILTIN_SLASH_COMMANDS, capabilities).map((c) => ({ name: c.name, description: c.description }));
+}
+/** Same list as flat autocomplete items (value/label/description). */
+export function commandAutocompleteItems(commands, capabilities) {
+    return withCanvasCommands(commands ?? BUILTIN_SLASH_COMMANDS, capabilities).map((c) => ({ value: `/${c.name}`, label: `/${c.name}`, description: c.description }));
+}
+// Canvas commands — native reimplementations of the canvas chrome extensions.
+/** Dispatch one of the native canvas commands. Always returns `true` (the
+ *  command is viewer-owned — never forwarded to the engine as a prompt). */
+function dispatchCanvasCommand(name, arg, ctx) {
+    // The capability gate (`readOnlyRefusal`) already ran in dispatchSlashCommand,
+    // so everything reaching here is a command this viewer may run.
+    switch (name) {
+        case 'clear':
+            // Claude-Code ergonomics: `/clear` == `/new` — drop the conversation and
+            // start an empty session (context freed). The broker's new_session re-
+            // emits a `welcome`, whose applySnapshot resetChat()s the pane, so the
+            // transcript is wiped too. Aliased here so muscle memory works.
+            ctx.send({ type: 'new_session' });
+            return true;
+        case 'graph':
+            // `/graph` opens the attach viewer's in-process GRAPH overlay, not a tmux
+            // popup. Dispatch reaches it through the viewer integration's `onGraph` hook.
+            if (ctx.onGraph)
+                ctx.onGraph();
+            else
+                ctx.notify('The GRAPH overlay is not wired into the viewer yet');
+            return true;
+        case 'inbox':
+            if (ctx.onInbox)
+                ctx.onInbox();
+            else
+                ctx.notify('The inbox surface is not wired into the viewer yet');
+            return true;
+        case 'menu':
+            return openActionMenu(ctx);
+        case 'tutorial':
+            // Routing only: one `prompt` frame pointing the agent at `crtr sys tutorial`.
+            // The lesson text lives in that command, never here, and the literal
+            // `/tutorial` the user typed is consumed locally — never forwarded as prose.
+            ctx.send({
+                type: 'prompt',
+                text: 'The user asked for the crouter tutorial. Run `crtr sys tutorial -h`, pick the track that matches what they want to learn, and teach it one lesson per invocation — in your own words, letting them try each thing before you move on.',
+            });
+            return true;
+        case 'promote':
+            promoteNode(arg, ctx);
+            return true;
+        case 'resume':
+            // Open the full-screen canvas navigator as a popup; on Enter it swaps THIS
+            // pane onto the chosen node via `crtr surface node focus --in-place`.
+            if (arg)
+                return usage(ctx, '/resume — no argument; use /resume-session <path> to switch pi sessions');
+            return resumeNode(ctx);
+        case 'resume-session':
+            // The pi session picker: rebind THIS node onto a different saved session
+            // file (recovering a conversation the node cycled away from).
+            if (!arg)
+                return openOrHint(ctx.openSessionPicker, ctx, 'session', '/resume-session <session-path>');
+            ctx.send({ type: 'switch_session', path: arg });
+            return true;
+        case 'mcp':
+            // MCP server status panel — viewer-local reads of the adapter's on-disk
+            // config sources/cache (see overlays/mcp.ts); the actions (connect /
+            // auth-start) ride a `prompt` frame to the engine, where the adapter
+            // runtime actually lives. `/mcp <server>` acts on that server directly.
+            if (ctx.openMcpPicker)
+                ctx.openMcpPicker(arg || undefined);
+            else
+                ctx.notify('The MCP panel is not wired into this viewer');
+            return true;
+        case 'context':
+            // A read-only nvim explorer over this node's + its subscriptions' context
+            // dirs, as a self-contained popup.
+            return openContext(ctx);
+        case 'plugins':
+            return openPlugins(ctx);
+        case 'node-metadata':
+            if (ctx.onNodeMetadata)
+                ctx.onNodeMetadata();
+            else
+                ctx.notify('Node metadata is not wired into this viewer');
+            return true;
+        case 'rename':
+            renameNode(arg, ctx);
+            return true;
+        case 'color':
+            return colorNode(arg, ctx);
+        case 'fold-tools':
+            // Viewer-local render state only — no frame, no CLI, no node mutation.
+            if (ctx.onFoldTools)
+                ctx.onFoldTools();
+            else
+                ctx.notify('The fold-tools view setting is not wired into this viewer');
+            return true;
+        case 'show-working':
+            // Viewer-local render state only — no frame, no CLI, no node mutation.
+            if (ctx.onShowWorking)
+                ctx.onShowWorking();
+            else
+                ctx.notify('The show-working view setting is not wired into this viewer');
+            return true;
+        case 'mouse':
+            // Viewer-local render state only — no frame, no CLI, no node mutation.
+            if (ctx.onToggleMouse)
+                ctx.onToggleMouse();
+            else
+                ctx.notify('Mouse reporting is not wired into this viewer');
+            return true;
+        case 'copy-message':
+            if (ctx.onCopyTarget)
+                ctx.onCopyTarget('message');
+            else
+                ctx.notify('/copy-message is not available in this viewer');
+            return true;
+        case 'copy-tool':
+            if (ctx.onCopyTarget)
+                ctx.onCopyTarget('tool');
+            else
+                ctx.notify('/copy-tool is not available in this viewer');
+            return true;
+        case 'copy-transcript':
+            if (ctx.onCopyTarget)
+                ctx.onCopyTarget('transcript');
+            else
+                ctx.notify('/copy-transcript is not available in this viewer');
+            return true;
+        default:
+            ctx.notify(`/${name} is not available in attach`);
+            return true;
+    }
+}
+/** `/promote [kind]` shells the out-of-process mutation, reports it, then
+ * triggers a turn whose provider gate appends the pending transition context. */
+function promoteNode(arg, ctx) {
+    const nodeId = nodeIdFor(ctx).trim();
+    if (nodeId === '') {
+        ctx.notify('/promote: no node to promote (viewer has no node id)');
+        return;
+    }
+    const kind = arg.trim().toLowerCase();
+    ctx.notify(kind ? `Promoting → ${kind}…` : 'Promoting…');
+    const argv = ['node', 'promote', '--node', nodeId, '--json'];
+    if (kind !== '')
+        argv.push('--kind', kind);
+    // execFile has no `stdio` option (it always pipes stdin) — end the
+    // child's stdin immediately so an inherited held-open pipe can never hang
+    // a future body-leaf invocation here (see readStdinRaw's contract in
+    // io.ts), the same non-hang guarantee pi bash tool and the bash valve
+    // supervisor get from an ignored stdin.
+    const child = execFile('crtr', argv, { timeout: 15_000, maxBuffer: 4 * 1024 * 1024 }, (err, stdout) => {
+        // On a non-zero exit crtr still prints the structured error to stdout, so
+        // prefer its `message` over the raw throw.
+        let result = null;
+        let errMsg = null;
+        try {
+            result = JSON.parse(stdout);
+        }
+        catch {
+            result = null;
+        }
+        if (err && result === null) {
+            const out = typeof err.stdout === 'string' ? err.stdout : '';
+            try {
+                const payload = JSON.parse(out);
+                errMsg = typeof payload.message === 'string' ? payload.message : null;
+            }
+            catch {
+                errMsg = null;
+            }
+            if (errMsg === null)
+                errMsg = err.message;
+        }
+        if (result === null) {
+            ctx.notify(`promote failed: ${errMsg ?? 'unknown error'}`);
+            return;
+        }
+        const rmRef = (result.roadmap_ref ?? '').trim();
+        ctx.notify(`Promoted to ${result.kind ?? 'orchestrator'} orchestrator — authoring roadmap${rmRef !== '' ? ` (${rmRef})` : ''}.`);
+        // Trigger a turn so the pending transition lands before the promoted
+        // node's response; the viewer's only turn trigger is `prompt`.
+        ctx.send({
+            type: 'prompt',
+            text: 'You have just been promoted to an orchestrator. Your new-role guidance is arriving — read it, author your roadmap, and start delegating.',
+        });
+    });
+    child.stdin?.end();
+}
+/** `/rename <name>` — rename this node EVERYWHERE the name shows (à la Claude
+ *  Code's rename): (1) the pi session name, which is what the editor's title
+ *  chip ("bubble") paints — sent as a `set_session_name` frame so the chip
+ *  updates on the session_info_changed round-trip; (2) the tmux pane title
+ *  (visible with pane-border-status / terminal titles); (3) the canvas node row
+ *  via `crtr node config --name`, which also renames the live viewer window. */
+function renameNode(arg, ctx) {
+    const nodeId = nodeIdFor(ctx).trim();
+    if (nodeId === '') {
+        ctx.notify('/rename: no node to rename (viewer has no node id)');
+        return;
+    }
+    if (arg === '') {
+        ctx.notify('Usage: /rename <name>');
+        return;
+    }
+    // 1. Session name → the editor title chip repaints when the state echoes back.
+    ctx.send({ type: 'set_session_name', name: arg });
+    // 2. tmux pane title (best-effort; no-op outside tmux).
+    const pane = process.env['TMUX_PANE'];
+    if (process.env['TMUX'] !== undefined && pane !== undefined && pane !== '') {
+        execFile('tmux', ['select-pane', '-t', pane, '-T', arg], () => {
+            /* best-effort */
+        });
+    }
+    // 3. Canvas node row + live viewer window.
+    execFile('crtr', ['node', 'config', '--node', nodeId, '--name', arg, '--json'], { timeout: 15_000, maxBuffer: 4 * 1024 * 1024 }, (err, stdout) => {
+        if (err) {
+            // On a non-zero exit crtr still prints the structured error to stdout.
+            let msg = null;
+            try {
+                const payload = JSON.parse(stdout);
+                msg = typeof payload.message === 'string' ? payload.message : null;
+            }
+            catch {
+                msg = null;
+            }
+            ctx.notify(`rename failed: ${msg ?? err.message}`);
+            return;
+        }
+        ctx.notify(`Renamed node → ${arg}`);
+    });
+}
+/** Promisified one-shot tmux call — resolves stdout ('' on error; best-effort). */
+function tmuxCall(args) {
+    return new Promise((resolve) => {
+        execFile('tmux', args, { timeout: 5_000 }, (err, stdout) => resolve(err ? '' : stdout));
+    });
+}
+/** Paint (or clear) THIS pane's border color. `pane-border-style` is a WINDOW
+ *  option — tmux silently hoists a `set-option -p` to window scope, painting
+ *  every pane — so per-pane color rides a per-pane user option instead: the
+ *  color lands in `@crtr_color` on this pane only, and the window's border
+ *  styles are set ONCE to a format tmux expands per pane (`fg=#{@crtr_color}`
+ *  when set, else the style that was in effect before — baked in at install
+ *  time so uncolored panes keep the user's theme). Clearing just unsets
+ *  `@crtr_color`; the format's fallback branch restores the original look. */
+async function paintPaneBorder(pane, value, clear) {
+    if (clear) {
+        await tmuxCall(['set-option', '-p', '-u', '-t', pane, '@crtr_color']);
+        return;
+    }
+    await tmuxCall(['set-option', '-p', '-t', pane, '@crtr_color', value]);
+    for (const opt of ['pane-border-style', 'pane-active-border-style']) {
+        const cur = (await tmuxCall(['show-options', '-wqv', '-t', pane, opt])).trim();
+        if (cur.includes('@crtr_color'))
+            continue; // our format is already installed on this window
+        // Bake the pre-existing effective style into the fallback branch (window
+        // value, else global, else tmux's defaults) — commas escaped so they don't
+        // split the #{?,,} conditional.
+        let base = cur !== '' ? cur : (await tmuxCall(['show-options', '-gqv', opt])).trim();
+        if (base === '')
+            base = opt === 'pane-active-border-style' ? 'fg=green' : 'default';
+        const fmt = `#{?#{!=:#{@crtr_color},},fg=#{@crtr_color},${base.replace(/,/g, '#,')}}`;
+        await tmuxCall(['set-option', '-w', '-t', pane, opt, fmt]);
+    }
+}
+/** `/color <color>` — color this node's two identity surfaces in one stroke:
+ *  the tmux PANE OUTLINE (via `paintPaneBorder` above — per-pane, not the whole
+ *  window) and the editor's NAME CHIP (the bubble `/rename` names), via the
+ *  `onColor` hook viewer.ts wires. Ephemeral by design: the border rides the
+ *  tmux pane and the chip lives in this viewer process. `/color none` clears
+ *  both. Remote-SAFE: both surfaces are local to this viewer. */
+function colorNode(arg, ctx) {
+    const value = arg.trim().toLowerCase();
+    if (value === '') {
+        ctx.notify('Usage: /color <color> — a name (red, blue, orange…), colourN, or #rrggbb; /color none to clear');
+        return true;
+    }
+    const clear = value === 'none' || value === 'clear';
+    const valid = clear || TMUX_NAMED_COLORS.has(value) || /^colour\d{1,3}$/.test(value) || /^#[0-9a-f]{6}$/.test(value);
+    if (!valid) {
+        ctx.notify(`Invalid color "${value}" — use a tmux colour name (${['red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'orange'].join(', ')}, …), colourN, or #rrggbb`);
+        return true;
+    }
+    // Pane outline — per-pane @crtr_color + a per-pane-expanded window format,
+    // so only THIS node's pane recolors (fire-and-forget; best-effort).
+    const pane = process.env['TMUX_PANE'];
+    const inTmux = process.env['TMUX'] !== undefined && pane !== undefined && pane !== '';
+    if (inTmux)
+        void paintPaneBorder(pane, value, clear);
+    // Name chip — the viewer owns the editor, so this rides the onColor hook.
+    ctx.onColor?.(clear ? null : value);
+    ctx.notify(clear ? 'Node color cleared' : `Node colored ${value}${inTmux ? '' : ' (chip only — no tmux pane)'}`);
+    return true;
+}
+/** `/resume`. Opens `crtr canvas browse` as a tmux popup, initially scoped to
+ *  this node's profile (with all dirs visible); on Enter the navigator respawns
+ *  THIS pane onto the chosen node (`crtr surface node focus --pane --in-place`),
+ *  so resuming replaces the viewer you invoked it from. */
+function resumeNode(ctx) {
+    const origPane = process.env['TMUX_PANE'];
+    if (process.env['TMUX'] === undefined || origPane === undefined || origPane === '') {
+        ctx.notify('/resume needs tmux');
+        return true;
+    }
+    const cwd = shellQuote(ctx.cwd ?? process.cwd());
+    const profileId = profileIdFor(ctx);
+    const profile = profileId === undefined || profileId === '' ? '' : ` --profile-id ${shellQuote(profileId)}`;
+    const cmd = `crtr canvas browse --return-pane ${origPane} --cwd ${cwd}${profile}`;
+    // The navigator earns a near-full screen: at this size it lays the preview out as
+    // a right-hand column beside the rows instead of a bottom strip.
+    popup(cmd, { w: '97%', h: '95%' });
+    return true;
+}
+/** `/menu`. Opens the crouter action menu — the very `display-menu` Alt+C
+ *  installs (built by `crouterMenuTmuxArgs` from the same bindings), targeted at
+ *  this viewer's pane. The route for a terminal whose Option key does not send Alt. */
+function openActionMenu(ctx) {
+    const pane = process.env['TMUX_PANE'];
+    if (process.env['TMUX'] === undefined || pane === undefined || pane === '') {
+        ctx.notify('/menu needs tmux — the crouter action menu is a tmux menu');
+        return true;
+    }
+    try {
+        execFile('tmux', ['display-menu', '-t', pane, ...crouterMenuTmuxArgs().slice(1)], (err) => {
+            if (err)
+                ctx.notify(`/menu failed: ${err.message.split('\n')[0]}`);
+        });
+    }
+    catch (err) {
+        ctx.notify(`/menu failed: ${err.message}`);
+    }
+    return true;
+}
+/** `/context`. Opens `crtr node inspect context` as a popup — a
+ *  read-only nvim explorer over the files in this node's + its subscriptions' context dirs.
+ *  Self-contained popup — no node-focus, no return-pane. */
+function openContext(ctx) {
+    if (process.env['TMUX'] === undefined) {
+        ctx.notify('/context needs tmux');
+        return true;
+    }
+    // The popup runs server-side and won't reliably inherit CRTR_NODE_ID, so pass
+    // this viewer's node id explicitly (mirrors /promote, /resume-node).
+    const nodeId = nodeIdFor(ctx).trim();
+    if (nodeId === '') {
+        ctx.notify('/context: no node to root on (viewer has no node id)');
+        return true;
+    }
+    popup(`crtr node inspect context --node ${shellQuote(nodeId)}`);
+    return true;
+}
+/** `/plugins`. Opens the local plugin browser as a self-contained popup. */
+function openPlugins(ctx) {
+    if (process.env['TMUX'] === undefined) {
+        ctx.notify('/plugins needs tmux');
+        return true;
+    }
+    popup('crtr pkg browse');
+    return true;
+}
+/** Open `cmd` as a fire-and-forget tmux display-popup (same geometry as the canvas
+ *  extensions). tmux runs the trailing string through `sh -c`; the popup owns its
+ *  screen and closes itself when the command exits, dropping back to this pane. */
+function popup(cmd, size = { w: '90%', h: '85%' }) {
+    try {
+        execFile('tmux', ['display-popup', '-E', '-w', size.w, '-h', size.h, ...surfaceTmuxStyleArgs(), cmd], () => {
+            /* best-effort: popup is self-contained */
+        });
+    }
+    catch {
+        /* best-effort */
+    }
+}
+function usage(ctx, form) {
+    ctx.notify(`Usage: ${form}`);
+    return true;
+}
+function pickerHint(ctx, what, form) {
+    ctx.notify(`Interactive ${what} picker isn't available over view.sock yet — use ${form}`);
+    return true;
+}
+/** Open a native picker if its opener is wired; otherwise fall back to the
+ *  text-arg hint. Keeps every value-picker builtin working even when the
+ *  read-op request channel is absent. */
+function openOrHint(open, ctx, what, form) {
+    if (open) {
+        open();
+        return true;
+    }
+    return pickerHint(ctx, what, form);
+}
+function handleSettings(arg, ctx) {
+    const [sub, ...rest] = arg.split(/\s+/);
+    const value = rest.join(' ').trim();
+    switch (sub) {
+        case 'thinking':
+            if (!value)
+                return usage(ctx, '/settings thinking <level>');
+            if (!THINKING_LEVELS.has(value)) {
+                ctx.notify(`Invalid thinking level "${value}" — choose one of: ${[...THINKING_LEVELS].join(', ')}`);
+                return true;
+            }
+            ctx.send({ type: 'set_thinking_level', level: value });
+            return true;
+        case 'auto-retry':
+            ctx.send({ type: 'set_auto_retry', enabled: parseBool(value) });
+            return true;
+        case 'auto-compaction':
+            ctx.send({ type: 'set_auto_compaction', enabled: parseBool(value) });
+            return true;
+        case '':
+            // Bare `/settings` opens the native settings menu (falls back to the
+            // sub-command summary when the picker channel is unwired).
+            if (ctx.openSettingsPicker) {
+                ctx.openSettingsPicker();
+                return true;
+            }
+            return settingsSummary(ctx);
+        default:
+            return settingsSummary(ctx);
+    }
+}
+function settingsSummary(ctx) {
+    ctx.notify('Settings: /settings thinking <level> | auto-retry on|off | auto-compaction on|off');
+    return true;
+}
+function parseBool(value) {
+    return /^(on|true|yes|1|enabled?)$/i.test(value.trim());
+}
+function parseExport(arg, cwd) {
+    const path = arg || `${cwd}/pi-export-${Date.now()}.html`;
+    const format = path.endsWith('.jsonl') ? 'jsonl' : 'html';
+    return { path, format };
+}
+function describeSession(state) {
+    if (!state)
+        return 'Session info unavailable';
+    const name = state.sessionName ? `"${state.sessionName}" ` : '';
+    return `Session ${name}${state.sessionId} · model ${state.model?.id ?? 'unknown'} · thinking ${state.thinkingLevel}`;
+}