@north-light/crouter 0.3.154

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

@@ -0,0 +1,696 @@
+// 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 (review m2 — 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';
+/** 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`, `/view`, `/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: '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: 'promote', description: 'Promote this node to an orchestrator — /promote, or /promote <kind> to specialize' },
+    { name: 'resume-node', description: 'Open the canvas navigator (search/scope/sort/tree) and resume the chosen node' },
+    { name: 'view', description: 'Open a view in a popup — bare for the picker, or /view <name> to open that view directly' },
+    { name: 'context', description: 'Browse this node + its subscriptions’ context dirs in a read-only nvim popup' },
+    { name: 'node-metadata', description: 'Inspect this node — identity, lifecycle, runtime, graph, artifacts, 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' },
+];
+const CANVAS_NAMES = new Set(CANVAS_SLASH_COMMANDS.map((c) => c.name));
+/** Native canvas commands that shell a LOCAL `crtr` mutation or read against
+ *  `ctx.nodeId` — unsafe for a remote attach (Phase 3 review 2, findings-fix-
+ *  review.md §1): `/promote` shells `crtr node promote --node` locally,
+ *  `/resume-node` opens local `crtr canvas browse` whose Enter path focuses a
+ *  local node, `/context` opens local `crtr node inspect context`. `/graph`
+ *  (the in-process GRAPH overlay, already remote-safe — see overlays/graph.ts)
+ *  and `/view` (a self-contained popup unrelated to `nodeId`) stay available. */
+const REMOTE_UNSAFE_CANVAS_NAMES = new Set(['promote', 'resume-node', 'context', 'node-metadata', 'rename', 'clear', 'mcp']);
+/** Native canvas commands an OBSERVER may not run — the ones that drive the
+ *  engine or mutate the node, whether by frame or by shelling the crtr CLI:
+ *  `/clear` sends `new_session`; `/promote` shells `crtr node promote` and then
+ *  triggers a turn; `/rename` sends `set_session_name` and shells `crtr node
+ *  config --name`; `/resume-node` opens the navigator whose Enter path focuses
+ *  (and so revives) a node; `/mcp`'s panel actions ride a `prompt` frame into
+ *  the engine. Deliberately NOT here — genuinely read-only or viewer-local:
+ *  `/graph` (in-process overlay), `/context` and `/node-metadata` (read-only
+ *  inspection popups), `/color` (this pane's tmux border + this viewer's name
+ *  chip). */
+const OBSERVER_UNSAFE_CANVAS_NAMES = new Set(['clear', 'promote', 'rename', 'resume-node', 'view', 'mcp']);
+/** 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 Phase-4 engine method — scoped out (review m2). */
+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));
+/** Builtin slash commands safe to run from a READ-ONLY viewer — a REMOTE
+ *  attach (`--canvas`) or an `--observer` one —
+ *  everything else in `BUILTIN_SLASH_COMMANDS` either drives the engine
+ *  (`/model`, `/new`, `/compact`, `/name`, `/resume`, `/fork`, `/tree`,
+ *  `/settings`, `/share`, `/clone`, `/import`, `/reload`, `/scoped-models`
+ *  selection) or is viewer-local but operates on the WRONG host for a remote
+ *  node (`/login`, `/logout` — LOCAL `auth.json` via `defaultAgentDir()`, not
+ *  the remote broker's; for an observer, credentials it may not swap under a
+ *  running engine). Blocked BEFORE the switch so a read-only viewer never even
+ *  opens the picker only to have the eventual selection frame swallowed by
+ *  InputController's `emitCommand` gate (defense-in-depth #2, not the only
+ *  defense — see input/controller.ts DRIVE_FRAME_TYPES). */
+const READ_ONLY_SAFE_BUILTIN_NAMES = new Set(['copy', 'session', 'changelog', 'hotkeys', 'quit']);
+/** THE capability gate for a read-only viewer, keyed on the two fixed facts a
+ *  session resolves once (`remote`, `role`) — so the answer for a given command
+ *  cannot change mid-session. Returns the refusal notice, or `undefined` when
+ *  this viewer may run the command. Both `dispatchSlashCommand` (so a direct
+ *  caller is safe) and the InputController's submit path (so a refusal is
+ *  reported before command dispatch) consult this one function; there is no
+ *  second policy anywhere. */
+function readOnlyRefusal(name, ctx) {
+    const canvas = CANVAS_NAMES.has(name);
+    const builtinUnsafe = BUILTIN_NAMES.has(name) && !READ_ONLY_SAFE_BUILTIN_NAMES.has(name);
+    if (ctx.remote === true) {
+        if (canvas && REMOTE_UNSAFE_CANVAS_NAMES.has(name)) {
+            return `/${name} is not available for a remote attach (--canvas) — it acts on this machine's local canvas`;
+        }
+        if (builtinUnsafe)
+            return `/${name} is not available for a remote attach (--canvas) — view-only`;
+    }
+    if (ctx.remote !== true && (ctx.role ?? 'controller') !== 'controller') {
+        if ((canvas && OBSERVER_UNSAFE_CANVAS_NAMES.has(name)) || builtinUnsafe) {
+            return `/${name} is not available to a read-only observer attach (--observer) — it would drive this node`;
+        }
+    }
+    return undefined;
+}
+/** The same gate, entered from raw editor text: the InputController asks BEFORE
+ *  dispatching so a refused command is reported without reaching command
+ *  dispatch. Unrecognized (extension) commands answer `undefined` here — they
+ *  ride the normal `prompt` path, which the controller's own drive gate covers. */
+export function readOnlySlashRefusal(text, ctx) {
+    const m = /^\/(\S+)\s*([\s\S]*)$/.exec(text.trim());
+    if (!m)
+        return undefined;
+    return readOnlyRefusal(m[1], ctx);
+}
+/** 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 (design: inline memory
+ *  references, review Major 6/terminal). 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]);
+}
+/** 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 m = /^\/(\S+)\s*([\s\S]*)$/.exec(text.trim());
+    if (!m)
+        return false;
+    const name = m[1];
+    const arg = m[2].trim();
+    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 'resume':
+            if (!arg)
+                return openOrHint(ctx.openSessionPicker, ctx, 'session', '/resume <session-path>');
+            ctx.send({ type: 'switch_session', path: 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;
+        // --- recognized builtins with no Phase-4 wire path --------------------
+        case 'hotkeys':
+            ctx.notify(`/${name} is not available in attach (Phase 4)`);
+            return true;
+        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 `REMOTE_UNSAFE_CANVAS_NAMES` when `remote`, which are structurally
+ *  omitted rather than offered-then-blocked, so a remote attach's autocomplete
+ *  never advertises a command `dispatchCanvasCommand` would refuse to run. */
+function withCanvasCommands(commands, remote) {
+    const seen = new Set(commands.map((c) => c.name));
+    const offerable = remote ? CANVAS_SLASH_COMMANDS.filter((c) => !REMOTE_UNSAFE_CANVAS_NAMES.has(c.name)) : CANVAS_SLASH_COMMANDS;
+    return [...commands, ...offerable.filter((c) => !seen.has(c.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 = BUILTIN_SLASH_COMMANDS, remote = false) {
+    return withCanvasCommands(commands, remote).map((c) => ({ name: c.name, description: c.description }));
+}
+/** Same list as flat autocomplete items (value/label/description). */
+export function commandAutocompleteItems(commands = BUILTIN_SLASH_COMMANDS, remote = false) {
+    return withCanvasCommands(commands, remote).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 'promote':
+            promoteNode(arg, ctx);
+            return true;
+        case 'resume-node':
+            // Open the full-screen canvas navigator as a popup; on Enter it focuses the
+            // chosen node back into THIS pane via `crtr surface node focus`.
+            return resumeNode(ctx);
+        case 'view':
+            // Bare `/view` opens the picker, `/view <name>` opens that view directly —
+            // each as a self-contained popup (no node-focus, no return-pane).
+            return openView(arg, ctx);
+        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 '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);
+        default:
+            ctx.notify(`/${name} is not available in attach`);
+            return true;
+    }
+}
+/** `/promote [kind]` — the live promote path (the broker is headless, so promotion
+ *  has no in-engine command). Shells `crtr node promote --json` for
+ *  this node (out-of-process), notifies the result, then triggers a turn so the
+ *  persona injector steers in the new-role guidance at the turn boundary — exactly
+ *  as the node would by running the command itself. */
+function promoteNode(arg, ctx) {
+    const nodeId = (ctx.nodeId ?? process.env['CRTR_NODE_ID'] ?? '').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 rmPath = (result.roadmap_path ?? '').trim();
+        ctx.notify(`Promoted to ${result.kind ?? 'orchestrator'} orchestrator — authoring roadmap${rmPath !== '' ? ` (${rmPath})` : ''}.`);
+        // Trigger a turn so the persona injector (canvas-stophook turn_end) fires and
+        // delivers the new-role guidance — 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 = (ctx.nodeId ?? process.env['CRTR_NODE_ID'] ?? '').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-node`. Opens `crtr canvas browse` as a tmux popup, initially scoped
+ *  to this node's profile (with all dirs visible); on Enter it focuses the chosen
+ *  node back into this pane via `crtr surface node focus --pane`. */
+function resumeNode(ctx) {
+    const origPane = process.env['TMUX_PANE'];
+    if (process.env['TMUX'] === undefined || origPane === undefined || origPane === '') {
+        ctx.notify('/resume-node needs tmux');
+        return true;
+    }
+    const cwd = shellQuote(ctx.cwd ?? process.cwd());
+    const profile = ctx.profileId === undefined || ctx.profileId === '' ? '' : ` --profile-id ${shellQuote(ctx.profileId)}`;
+    const cmd = `crtr canvas browse --return-pane ${origPane} --cwd ${cwd}${profile}`;
+    popup(cmd);
+    return true;
+}
+/** `/view [name]`. Bare opens the picker; with a name it opens that view directly. Self-contained
+ *  popup — no node-focus, no return-pane. */
+function openView(arg, ctx) {
+    if (process.env['TMUX'] === undefined) {
+        ctx.notify('/view needs tmux');
+        return true;
+    }
+    const name = arg.trim();
+    const cmd = name === '' ? 'crtr surface view pick' : `crtr surface view run ${shellQuote(name)}`;
+    popup(cmd);
+    return true;
+}
+/** `/context`. Opens `crtr node inspect context` as a popup — a
+ *  read-only nvim explorer over 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 = (ctx.nodeId ?? process.env['CRTR_NODE_ID'] ?? '').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;
+}
+/** 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) {
+    try {
+        execFile('tmux', ['display-popup', '-E', '-w', '90%', '-h', '85%', ...surfaceTmuxStyleArgs(), cmd], () => {
+            /* best-effort: popup is self-contained */
+        });
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** Single-quote a string for safe interpolation into a `sh -c` command line. */
+function shellQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+// ---------------------------------------------------------------------------
+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}`;
+}