@north-light/api 0.3.580 → 0.3.588

package/dist/commands/surface/node/id.js

@@ -0,0 +1,38 @@
+// `crtr surface node id` — copy a viewer's node id.
+import { defineLeaf } from '../../../core/command.js';
+import { InputError } from '../../../core/io.js';
+import { writeClipboardText } from '../../../core/clipboard-text.js';
+import { displayMessage } from '../../../core/runtime/tmux-chrome.js';
+import { nodeInPane } from './placement.js';
+export const surfaceNodeIdLeaf = defineLeaf({
+    name: 'id',
+    description: 'copy the focused node id to the system clipboard',
+    whenToUse: 'you need the id of the node in a tmux pane for a follow-up command or external reference',
+    help: {
+        name: 'surface node id',
+        summary: 'copy the node resolved from a tmux pane to the system clipboard',
+        params: [
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane id whose focused node to copy. Defaults to $TMUX_PANE / your current pane.' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The focused node id copied to the system clipboard.' },
+        ],
+        outputKind: 'object',
+        effects: ['Writes the focused node id to the system clipboard and shows a transient tmux confirmation.'],
+    },
+    run: async (input) => {
+        const pane = input['pane'] ?? process.env['TMUX_PANE'];
+        const nodeId = nodeInPane(pane);
+        if (nodeId === undefined) {
+            displayMessage('crtr: no node in pane', pane);
+            throw new InputError({ error: 'no_node', message: 'no node found in this pane', next: 'Pass --pane <pane-id> for a pane showing an active node.' });
+        }
+        if (!writeClipboardText(nodeId)) {
+            displayMessage('crtr: copy failed', pane);
+            throw new InputError({ error: 'clipboard_write_failed', message: 'could not write the node id to the system clipboard', next: 'Make a system clipboard tool available, then retry.' });
+        }
+        displayMessage('crtr: node id copied', pane);
+        return { node_id: nodeId };
+    },
+    render: (r) => `Copied node id: ${r['node_id']}`,
+});

package/dist/commands/surface/node/pin.d.ts

@@ -0,0 +1 @@
+export declare const surfaceNodePinLeaf: import("../../../core/command.js").LeafDef;

package/dist/commands/surface/node/pin.js

@@ -0,0 +1,42 @@
+// `crtr surface node pin` — navigator pin control for a viewer.
+import { defineLeaf } from '../../../core/command.js';
+import { InputError } from '../../../core/io.js';
+import { displayMessage } from '../../../core/runtime/tmux-chrome.js';
+import { loadPins, savePins } from '../../../core/canvas/browse/pins.js';
+import { nodeInPane } from './placement.js';
+export const surfaceNodePinLeaf = defineLeaf({
+    name: 'pin',
+    description: 'pin or unpin the node in a tmux pane in the canvas navigator',
+    whenToUse: 'you want the conversation in this pane starred at the top of your canvas navigator (the same pin `canvas browse` toggles), without opening the navigator to do it',
+    help: {
+        name: 'surface node pin',
+        summary: 'toggle the canvas-navigator pin on the node resolved from a tmux pane — a local, per-user view preference that sorts the node to the top of your navigator and fills its Pinned tab, mutating nothing on the canvas',
+        params: [
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane id whose focused node to pin. Defaults to $TMUX_PANE / your current pane.' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The node whose pin was toggled.' },
+            { name: 'pinned', type: 'boolean', required: true, constraint: 'True when the node is now pinned, false when the pin was removed.' },
+        ],
+        outputKind: 'object',
+        effects: ['Toggles the node in the per-user navigator pin set and shows a transient tmux confirmation.'],
+    },
+    run: async (input) => {
+        const pane = input['pane'] ?? process.env['TMUX_PANE'];
+        const nodeId = nodeInPane(pane);
+        if (nodeId === undefined) {
+            displayMessage('crtr: no node in pane', pane);
+            throw new InputError({ error: 'no_node', message: 'no node found in this pane', next: 'Pass --pane <pane-id> for a pane showing an active node.' });
+        }
+        const pins = loadPins();
+        const pinned = !pins.has(nodeId);
+        if (pinned)
+            pins.add(nodeId);
+        else
+            pins.delete(nodeId);
+        savePins(pins);
+        displayMessage(pinned ? 'crtr: conversation pinned' : 'crtr: conversation unpinned', pane);
+        return { node_id: nodeId, pinned };
+    },
+    render: (r) => (r['pinned'] === true ? `Pinned ${r['node_id']} in the canvas navigator.` : `Unpinned ${r['node_id']}.`),
+});

package/dist/commands/surface/node/placement.d.ts

@@ -0,0 +1,30 @@
+import { closePane, currentTmux, displayPopup, paneCurrentPath, paneExists, panePid, paneStartCommand, respawnPaneInPlace, respawnPaneSync, shellQuote, viewerSplitEnv } from '../../../core/runtime/placement-tmux.js';
+import { viewerEnv, viewerPaneOf, type FocusViewerOpts, type FocusViewerResult } from '../../../core/runtime/focus-viewer.js';
+export { closePane, currentTmux, displayPopup, paneCurrentPath, paneExists, panePid, paneStartCommand, respawnPaneInPlace, respawnPaneSync, shellQuote, viewerSplitEnv };
+export { viewerEnv, viewerPaneOf };
+/** `focusViewer` bound to the CLI's daemon client, with daemon failures
+ *  rethrown as clean CLI errors. The implementation is shared with the attach
+ *  viewer in `core/runtime/focus-viewer.ts`. */
+export declare function focusViewer(nodeId: string, opts: FocusViewerOpts): Promise<FocusViewerResult>;
+/** Open a viewer for a freshly-spawned --root node in a FRESH WINDOW in the
+ *  caller's current tmux session (the --root spawn-viewer path). Pure tmux; the
+ *  broker is already launching server-side, so the attach pane self-polls the
+ *  cold socket. Returns the opened window/session, empty when not in tmux. */
+export declare function openSpawnViewer(nodeId: string, cwd: string, name: string): {
+    window?: string;
+    session?: string;
+};
+/** The node "in front of you" in a tmux pane, resolved PURELY from the pane's
+ *  `@crtr_node` tag. Defaults to $TMUX_PANE / the caller's current pane when
+ *  `pane` is omitted — shared by `node lifecycle recycle` / `node lifecycle
+ *  demote` / `node config --lifecycle` / `node lifecycle close` / `surface node cycle`,
+ *  and the `canvas chord` leaf.
+ *
+ *  A `crtr surface attach` viewer self-tags its pane with the node it views
+ *  (`@crtr_node`) — the tag IS the handle (a broker engine runs DETACHED with
+ *  window=null, so there is no window→node fallback). Kept SYNC + tag-only: the
+ *  CLI does not read canvas state to confirm the tagged node is
+ *  still live, so a stale tag (attach SIGKILLed without clearing) resolves until
+ *  the pane is respawned. Callers that mutate then re-validate the id via the
+ *  API (getNode 404 → clean error). */
+export declare function nodeInPane(pane?: string): string | undefined;

package/dist/commands/surface/node/placement.js

@@ -0,0 +1,49 @@
+// `crtr surface node` — pure tmux placement for node viewers.
+import { closePane, currentTmux, displayPopup, ensureSession, getPaneOption, openNodeWindow, paneCurrentPath, paneExists, panePid, paneStartCommand, respawnPaneInPlace, respawnPaneSync, selectPane, selectWindow, shellQuote, viewerSplitEnv, } from '../../../core/runtime/placement-tmux.js';
+import { focusViewer as focusViewerWith, viewerEnv, viewerPaneOf, } from '../../../core/runtime/focus-viewer.js';
+import { cliClient, rethrowAsCliError } from '../../api-client.js';
+export { closePane, currentTmux, displayPopup, paneCurrentPath, paneExists, panePid, paneStartCommand, respawnPaneInPlace, respawnPaneSync, shellQuote, viewerSplitEnv };
+export { viewerEnv, viewerPaneOf };
+/** `focusViewer` bound to the CLI's daemon client, with daemon failures
+ *  rethrown as clean CLI errors. The implementation is shared with the attach
+ *  viewer in `core/runtime/focus-viewer.ts`. */
+export async function focusViewer(nodeId, opts) {
+    return focusViewerWith(cliClient(), nodeId, opts).catch(rethrowAsCliError);
+}
+/** Open a viewer for a freshly-spawned --root node in a FRESH WINDOW in the
+ *  caller's current tmux session (the --root spawn-viewer path). Pure tmux; the
+ *  broker is already launching server-side, so the attach pane self-polls the
+ *  cold socket. Returns the opened window/session, empty when not in tmux. */
+export function openSpawnViewer(nodeId, cwd, name) {
+    const loc = currentTmux();
+    const session = loc?.session;
+    if (session === undefined || session === '')
+        return {};
+    ensureSession(session, cwd);
+    const opened = openNodeWindow({ session, name, cwd, env: viewerEnv(), command: `crtr surface attach to ${nodeId}` });
+    if (opened === null)
+        return {};
+    selectWindow(session, opened.window);
+    selectPane(opened.pane);
+    return { window: opened.window, session };
+}
+/** The node "in front of you" in a tmux pane, resolved PURELY from the pane's
+ *  `@crtr_node` tag. Defaults to $TMUX_PANE / the caller's current pane when
+ *  `pane` is omitted — shared by `node lifecycle recycle` / `node lifecycle
+ *  demote` / `node config --lifecycle` / `node lifecycle close` / `surface node cycle`,
+ *  and the `canvas chord` leaf.
+ *
+ *  A `crtr surface attach` viewer self-tags its pane with the node it views
+ *  (`@crtr_node`) — the tag IS the handle (a broker engine runs DETACHED with
+ *  window=null, so there is no window→node fallback). Kept SYNC + tag-only: the
+ *  CLI does not read canvas state to confirm the tagged node is
+ *  still live, so a stale tag (attach SIGKILLed without clearing) resolves until
+ *  the pane is respawned. Callers that mutate then re-validate the id via the
+ *  API (getNode 404 → clean error). */
+export function nodeInPane(pane) {
+    const resolvePane = pane ?? process.env['TMUX_PANE'] ?? currentTmux()?.pane;
+    if (resolvePane === undefined || resolvePane === '')
+        return undefined;
+    const tagged = getPaneOption(resolvePane, '@crtr_node');
+    return tagged !== undefined && tagged !== '' ? tagged : undefined;
+}

package/dist/commands/surface-dashboard.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../core/command.js';
+export declare const surfaceDashboardLeaf: LeafDef;

package/dist/commands/surface-dashboard.js

@@ -0,0 +1,138 @@
+// `crtr surface dashboard` — put the live-roots dashboard into a tmux pane.
+//
+// The screen (clients/dashboard) only ever runs as a pane's start command. This command is the
+// one entry path: it classifies the target pane by its tmux start command, then either respawns
+// it (a crouter viewer) or opens the dashboard in a new detached window and swaps it into the
+// pane's place, so whatever ran there keeps running behind it. Run on a pane that already shows
+// the dashboard, it returns the pane to the conversation it showed before. Outside tmux it prints
+// a static listing.
+import { defineLeaf } from '../core/command.js';
+import { envProfileId } from '../shared/env.js';
+import { getDefaultProfileId } from '../core/profiles/default-binding.js';
+import { SECTION_ORDER, SECTION_TITLE, sectionOf } from '../clients/dashboard/model.js';
+import { closeWindow, currentTmux, displayMessage, getPaneOption, openNodeWindow, paneCurrentCommand, paneCurrentPath, paneLocation, paneStartCommand, renameWindow, respawnPaneSync, setPaneOption, shellQuote, swapPanes, viewerSplitEnv, windowOfPane, } from '../core/runtime/placement-tmux.js';
+import { cliClient } from './api-client.js';
+const RUN_ENV = 'CRTR_DASHBOARD_RUN';
+/** Pane option: the conversation the pane showed when the dashboard replaced it. */
+const RETURN_OPTION = '@crtr_dashboard_return';
+async function profileFor(explicit, pane, cwd) {
+    if (explicit !== undefined && explicit !== '')
+        return explicit;
+    const node = pane === undefined ? undefined : getPaneOption(pane, '@crtr_node');
+    if (node !== undefined && node !== '') {
+        try {
+            const profile = (await cliClient().getNode(node)).profile_id;
+            if (profile !== null && profile !== undefined)
+                return profile;
+        }
+        catch { /* fall through to the environment and the directory default */ }
+    }
+    return envProfileId() ?? getDefaultProfileId(cwd) ?? undefined;
+}
+async function printListing(profileId) {
+    const res = await cliClient().liveRoots(profileId === undefined ? {} : { profile: profileId });
+    const lines = [];
+    for (const section of SECTION_ORDER) {
+        const rows = res.rows.filter((r) => sectionOf(r) === section);
+        if (rows.length === 0)
+            continue;
+        lines.push(`${SECTION_TITLE[section]} (${rows.length})`);
+        for (const r of rows) {
+            const marks = [r.running_count > 0 ? `⟳ ${r.running_count}` : '', r.asks > 0 ? `? ${r.asks}` : '', r.fault !== null ? '⚠' : ''].filter((m) => m !== '').join(' ');
+            lines.push(`  ${r.name}  ${r.state_line ?? r.goal ?? ''}${marks === '' ? '' : `  ${marks}`}`);
+        }
+    }
+    process.stdout.write(`${lines.length === 0 ? 'no live conversations' : lines.join('\n')}\n`);
+}
+export const surfaceDashboardLeaf = defineLeaf({
+    name: 'dashboard',
+    description: 'show the profile’s live root conversations in a tmux pane — which need the person, which run, which are idle',
+    whenToUse: 'the person asks to see all their running conversations in one place, or you are wiring a key to it. It is a screen for the person, not a read: use `canvas dashboard` for a one-shot tree you can pipe',
+    help: {
+        name: 'surface dashboard',
+        summary: 'put the dashboard in a tmux pane: live root conversations in Waiting for you / Running / Idle, Enter opens one in that pane, n starts a new background conversation. Outside tmux it prints the same listing as text',
+        params: [
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane that shows the dashboard. Default: $TMUX_PANE. A pane running a crouter viewer is respawned; any other pane (a shell, an editor) is swapped for a new window that runs the dashboard, and its program keeps running in the background window. A pane already showing the dashboard returns to the conversation it showed before.' },
+            { kind: 'flag', name: 'profile-id', type: 'string', required: false, constraint: 'Exact profile id to list. Default: the profile of the conversation shown in the pane, then $CRTR_PROFILE_ID, then the pane directory’s pinned default profile; absent means all profiles.' },
+        ],
+        output: [],
+        outputKind: 'object',
+        effects: [
+            'Respawns the target pane onto the dashboard (a crouter viewer’s engine keeps running), or opens a new tmux window with the dashboard and swaps it into the pane’s place.',
+            'On a pane already showing the dashboard: opens the conversation that pane showed before the dashboard, in that pane; with none recorded, shows a tmux message and changes nothing.',
+            'Never kills a pane that is not running a crouter viewer or dashboard.',
+            'Inside the dashboard, Enter runs `surface node focus` for the chosen conversation, `n` creates a root conversation, `x` finishes one.',
+        ],
+    },
+    run: async (input) => {
+        const explicitProfile = input['profileId'];
+        // Run mode: the placed pane's own process.
+        if (process.env[RUN_ENV] === '1') {
+            delete process.env[RUN_ENV];
+            const { runDashboard } = await import('../clients/dashboard/app.js');
+            const profileId = explicitProfile ?? envProfileId() ?? getDefaultProfileId(process.cwd()) ?? undefined;
+            await runDashboard({ profileId, cwd: process.cwd() });
+            return;
+        }
+        if (process.env['TMUX'] === undefined || process.env['TMUX'] === '') {
+            await printListing(explicitProfile ?? envProfileId() ?? getDefaultProfileId(process.cwd()) ?? undefined);
+            return;
+        }
+        const pane = input['pane'] ?? process.env['TMUX_PANE'] ?? currentTmux()?.pane;
+        if (pane === undefined || pane === '') {
+            displayMessage('crtr: no pane to show the dashboard in');
+            throw new Error('no tmux pane to show the dashboard in — pass --pane <id>');
+        }
+        const fail = (message) => {
+            displayMessage(`crtr: ${message}`, pane);
+            throw new Error(message);
+        };
+        const start = paneStartCommand(pane)?.replace(/^"|"$/g, '');
+        if (start === undefined)
+            return fail(`pane ${pane} is not reachable`);
+        if (start.startsWith('crtr surface dashboard')) {
+            const back = getPaneOption(pane, RETURN_OPTION);
+            if (back === undefined || back === '') {
+                displayMessage('crtr: no conversation to return to from this dashboard', pane);
+                return;
+            }
+            const client = cliClient();
+            const node = await client.getNode(back).catch(() => null);
+            if (node === null)
+                return fail('the conversation this pane showed before no longer exists');
+            const { focusNode } = await import('../core/runtime/focus-viewer.js');
+            const res = await focusNode(client, node, { pane, inPlace: true, keepOtherViewers: true });
+            if (!res.focused)
+                fail(`could not return to ${node.name}`);
+            return;
+        }
+        const cwd = paneCurrentPath(pane) ?? process.cwd();
+        const profileId = await profileFor(explicitProfile, pane, cwd);
+        const command = `crtr surface dashboard${profileId === undefined ? '' : ` --profile-id ${shellQuote(profileId)}`}`;
+        const env = { ...viewerSplitEnv(), [RUN_ENV]: '1' };
+        if (start.startsWith('crtr surface attach to ')) {
+            const shown = getPaneOption(pane, '@crtr_node');
+            if (shown !== undefined && shown !== '')
+                setPaneOption(pane, RETURN_OPTION, shown);
+            if (!respawnPaneSync({ pane, cwd, env, command }))
+                fail(`tmux could not respawn pane ${pane}`);
+            return;
+        }
+        const location = paneLocation(pane);
+        if (location === null)
+            return fail(`pane ${pane} is not in a tmux window`);
+        const opened = openNodeWindow({ session: location.session, name: 'dashboard', cwd, env, command });
+        if (opened === null)
+            return fail('tmux could not open a window for the dashboard');
+        const displaced = paneCurrentCommand(pane);
+        const error = swapPanes(opened.pane, pane);
+        if (error !== null) {
+            closeWindow(opened.window);
+            return fail(`could not show the dashboard: ${error}`);
+        }
+        const backgroundWindow = windowOfPane(pane);
+        if (backgroundWindow !== null && displaced !== undefined)
+            renameWindow(backgroundWindow, displaced);
+    },
+    render: () => '',
+});

package/dist/commands/surface-edit.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../core/command.js';
+export declare const surfaceEditLeaf: LeafDef;

package/dist/commands/surface-edit.js

@@ -0,0 +1,157 @@
+// `crtr surface edit <file>` — open a file in the user's $EDITOR in a new pane.
+//
+// A genuine viewer-placement decision, so it lives under `surface` alongside
+// view/attach/workspace/tmux-spread. It reuses the §5.1 import-lint front door
+// (splitWindow / currentTmux / paneLocation re-exported through placement),
+// never importing tmux.ts directly.
+//
+// AGENT-TRIGGERED is the primary path: a node's engine runs in a HEADLESS broker
+// with no $TMUX of its own, yet the tmux CLI reaches the running server over its
+// socket regardless (exactly how the headless daemon places every viewer pane).
+// So we do NOT gate on the caller's $TMUX. surface edit opens the editor NEXT TO
+// THE PANE THAT OPENED IT — the resolution, in order:
+//   1. explicit --pane
+//   2. $TMUX_PANE            (a human running this from their own pane)
+//   3. this node's VIEWER pane via paneOfNode($CRTR_NODE_ID) — the pane carrying
+//      this node's @crtr_node tag, set by ANY viewer (attach, focus, spawn). We
+//      scan the tag, NOT the focus table, which a bare `surface attach` never
+//      writes — so attach-viewed nodes resolve correctly.
+//   4. the attached client's active pane
+// If none resolve, the caller has no pane on screen (a BACKGROUND node with no
+// viewer): there is genuinely no "pane that opened it" to sit beside, so we do
+// NOT invent a location — a clean no_pane error. The agent surfaces the file the
+// normal way (a report/push with the path) and it opens beside the node the
+// moment it IS being watched. (Inventing a window per background caller would
+// spew disconnected editor windows into whatever session happened to be attached.)
+//
+// The editor is `$EDITOR` expanded by the new pane's own shell against the
+// inherited tmux server env (like every crtr chrome pane) — no broker-side env
+// read, no host assumption. tmux-native throughout: a web-only surface has no
+// pane to split and resolves to the no_pane error, never a caller of this.
+import { envNodeId } from '../shared/env.js';
+import { existsSync, statSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { currentTmux, splitWindow, paneLocation, paneOfNode, } from '../core/runtime/placement-tmux.js';
+import { shellQuote } from '../shared/shell-quote.js';
+/** Resolve the pane the editor should open BESIDE — the pane that opened this
+ *  command: explicit --pane, the caller's own $TMUX_PANE, the pane where THIS
+ *  node is being watched (its `@crtr_node`-tagged pane, whatever viewer put it
+ *  there — attach, focus, spawn), or the attached client's active pane. Null when
+ *  no pane on the server shows the node (it's headless with no viewer) — there is
+ *  no "pane that opened it" to sit beside. */
+function resolveTargetPane(explicit) {
+    const flag = explicit?.trim();
+    if (flag !== undefined && flag !== '')
+        return flag;
+    const envPane = process.env['TMUX_PANE'];
+    if (envPane !== undefined && envPane !== '')
+        return envPane;
+    // Agent path: split beside the pane where THIS node is being watched. Resolve
+    // it by the authoritative @crtr_node tag (set by any viewer) — NOT the focus
+    // table, which a bare `surface attach` never writes.
+    const nodeId = envNodeId();
+    if (nodeId !== undefined && nodeId !== '') {
+        const pane = paneOfNode(nodeId);
+        if (pane !== null)
+            return pane;
+    }
+    return currentTmux()?.pane ?? null;
+}
+/** The command the new pane runs. The pane INHERITS the tmux server environment
+ *  (like every crtr chrome pane — the subagent viewer panes get theirs the same
+ *  way), and a tmux server started from the human's interactive shell captured
+ *  their $EDITOR there. So we reference $EDITOR by name and let the pane's own
+ *  shell expand it against the inherited env — no broker-side env read, no host
+ *  assumption. If $EDITOR/$VISUAL are genuinely unset the pane surfaces that
+ *  itself; we don't guess a fallback. */
+const EDITOR_EXPR = '${EDITOR:-${VISUAL}}';
+export const surfaceEditLeaf = defineLeaf({
+    name: 'edit',
+    description: "open a file in the user's $EDITOR in a new pane beside the pane that opened this command",
+    whenToUse: "you (an agent) want the user to SEE a file WHILE THEY'RE WATCHING YOU — open it in their $EDITOR in a new pane split beside this node's viewer pane, without them hunting for it. Works headless (the broker reaches the tmux server over its socket). Requires this node to be on screen (a viewer open) or a caller pane; a background node with no viewer gets a no_pane error — report the path instead and it opens beside you once watched",
+    help: {
+        name: 'surface edit',
+        summary: "Open <file> in a new pane running the user's $EDITOR (else $VISUAL), split beside THE PANE THAT OPENED THIS: an explicit --pane, the caller's own $TMUX_PANE, or this node's viewer pane (the pane where the user is watching it). Works from a HEADLESS broker (the tmux server is reached over its socket, no $TMUX needed). A background node with no viewer on screen has no pane to sit beside -> no_pane error. The split is -d, so focus is unchanged",
+        params: [
+            {
+                kind: 'positional',
+                name: 'file',
+                required: true,
+                constraint: 'Path to open. Relative paths resolve against the current working directory.',
+            },
+            {
+                kind: 'flag',
+                name: 'pane',
+                type: 'string',
+                required: false,
+                constraint: "tmux pane id to split beside. Defaults to $TMUX_PANE, else the pane showing this node (its @crtr_node tag), else the attached client's active pane.",
+            },
+            {
+                kind: 'flag',
+                name: 'vertical',
+                type: 'bool',
+                required: false,
+                constraint: 'Split top/bottom instead of the default left/right.',
+            },
+        ],
+        output: [
+            { name: 'pane', type: 'string', required: true, constraint: 'The new pane id running the editor.' },
+            { name: 'session', type: 'string', required: false, constraint: 'The session the editor pane lives in.' },
+            { name: 'file', type: 'string', required: true, constraint: 'The resolved absolute path opened.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            "Opens a NEW pane running the user's $EDITOR (else $VISUAL) on <file> beside the target pane (tmux split-window -d; focus unchanged). Reaches the tmux server over its socket, so it works from a headless broker.",
+            "The editor is $EDITOR expanded by the new pane's own shell against the inherited tmux server env — the same way subagent viewer panes get their env. tmux-native: a web-only surface has no pane to split, so it resolves to a no_pane error rather than being a caller of this.",
+            'Requires a pane that opened it to sit beside — this node’s on-screen viewer, an explicit --pane, or a caller pane. A background node with no viewer errors (no_pane); it does NOT invent a window in some attached session.',
+        ],
+    },
+    run: async (input) => {
+        const raw = input['file'].trim();
+        if (raw === '') {
+            throw new InputError({ error: 'no_file', message: 'no file given', field: 'file', next: 'Pass a path to open.' });
+        }
+        const file = isAbsolute(raw) ? raw : resolve(process.cwd(), raw);
+        if (existsSync(file) && statSync(file).isDirectory()) {
+            throw new InputError({
+                error: 'is_directory',
+                message: `${file} is a directory`,
+                field: 'file',
+                next: 'Pass a file path (surface edit opens a single file in $EDITOR).',
+            });
+        }
+        const target = resolveTargetPane(input['pane']);
+        if (target === null) {
+            throw new InputError({
+                error: 'no_pane',
+                message: 'no pane to open the editor beside — this node has no viewer on screen (it is running in the background).',
+                next: 'Open a viewer on this node (`crtr surface node focus <id>` / `crtr surface attach`) and retry, pass --pane <pane-id>, or run from inside a tmux pane. To just point the user at a file, report its path instead.',
+            });
+        }
+        const command = `${EDITOR_EXPR} ${shellQuote(file)}`;
+        const pane = splitWindow(target, {
+            cwd: process.cwd(),
+            env: {},
+            command,
+            vertical: input['vertical'] === true,
+        });
+        if (pane === null) {
+            throw new InputError({
+                error: 'split_failed',
+                message: `tmux split-window failed for ${target}`,
+                next: 'Ensure the pane still exists and the tmux window has room (try a wider window).',
+            });
+        }
+        return {
+            pane,
+            session: paneLocation(pane)?.session ?? undefined,
+            file,
+        };
+    },
+    render: (out) => {
+        const o = out;
+        return `opened ${o.file} in a new pane (${o.pane})`;
+    },
+});

package/dist/commands/surface-inbox.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../core/command.js';
+export declare const surfaceInboxLeaf: LeafDef;

package/dist/commands/surface-inbox.js

@@ -0,0 +1,98 @@
+// `crtr surface inbox` — the tmux keybinding's target for the human inbox.
+//
+// A screen-facing viewer control, not a ticket verb: it delivers the private
+// attach-control action to one live viewer and focuses it. The human reaches
+// their own inbox through the inbox-toggle key (or `/inbox` in the viewer,
+// which toggles in-process and never shells out here).
+import { defineLeaf } from '../core/command.js';
+import { currentTmux, displayClientMessage, liveViewerPanes, paneLocation, selectPane, selectWindow, sendAttachControl, switchClient, } from '../core/runtime/placement-tmux.js';
+const NO_VIEWER_MESSAGE = 'No crouter viewer is running — attach to a node first (crtr surface attach to <node>).';
+function tmuxSocketFromEnvironment() {
+    const socket = process.env['TMUX']?.split(',')[0]?.trim();
+    return socket === undefined || socket === '' ? undefined : socket;
+}
+function paneForInvocation(explicit) {
+    if (explicit !== undefined && explicit !== '')
+        return explicit;
+    const fromEnv = process.env['TMUX_PANE'];
+    if (fromEnv !== undefined && fromEnv !== '')
+        return fromEnv;
+    return currentTmux()?.pane;
+}
+function newestViewer(a, b) {
+    if (a.stampMs !== b.stampMs)
+        return b.stampMs - a.stampMs;
+    if (a.pane === b.pane)
+        return 0;
+    return a.pane < b.pane ? -1 : 1;
+}
+function selectViewer(viewers, targetPane, clientSession) {
+    const targeted = targetPane === undefined ? undefined : viewers.find((viewer) => viewer.pane === targetPane);
+    if (targeted !== undefined)
+        return targeted;
+    const inClientSession = clientSession === undefined ? [] : viewers.filter((viewer) => viewer.session === clientSession);
+    return [...(inClientSession.length > 0 ? inClientSession : viewers)].sort(newestViewer)[0];
+}
+function focusViewer(viewer, targetPane, clientSession) {
+    if (viewer.pane === targetPane)
+        return;
+    const location = paneLocation(viewer.pane);
+    if (location === null) {
+        selectPane(viewer.pane);
+        return;
+    }
+    if (clientSession !== location.session)
+        switchClient(location.session);
+    selectWindow(location.session, location.window);
+    selectPane(viewer.pane);
+}
+export const surfaceInboxLeaf = defineLeaf({
+    name: 'inbox',
+    description: 'human inbox toggle dispatcher (bound to the inbox-toggle key; not run by hand)',
+    whenToUse: 'never directly — the inbox-toggle keybinding routes the user’s own request through it. An agent that wants a decision uses crtr human send; how the user reaches their inbox is theirs.',
+    tier: 'hidden',
+    hookEligible: false,
+    help: {
+        name: 'surface inbox',
+        summary: 'deliver the human inbox toggle to a live viewer',
+        guide: 'Selection prefers the target pane, then the resolved client session by newest viewer stamp, then newest globally; ties use pane id. The viewer decides whether the delivered toggle opens or closes the surface.',
+        params: [
+            { kind: 'flag', name: 'tmux-socket', type: 'path', required: false, constraint: 'Tmux server socket. Omit to use the first field of $TMUX.' },
+            { kind: 'flag', name: 'tmux-client', type: 'string', required: false, constraint: 'Tmux client name for the status-line message and client-session context.' },
+            { kind: 'flag', name: 'target-pane', type: 'string', required: false, constraint: 'Viewer pane to prefer. Omit to use $TMUX_PANE or the current tmux pane as the selection target.' },
+            { kind: 'flag', name: 'quiet', type: 'bool', required: false, default: false, constraint: 'Suppress the structured command result. A no-viewer status-line message is still shown.' },
+        ],
+        output: [
+            { name: 'action', type: 'opened | skipped', required: true, constraint: 'opened means the private inbox toggle sequence was delivered to a live viewer; it does not assert that the surface is now open. skipped means delivery did not happen.' },
+            { name: 'message', type: 'string', required: false, constraint: 'Present when action is skipped. With no live viewer, the same message is also shown in the tmux status line.' },
+        ],
+        outputKind: 'object',
+        effects: ['Sends the private inbox attach-control sequence to one live viewer and focuses that viewer unless it is already the target pane. Never opens a popup, launches a viewer, or wakes a node. With --quiet, suppresses only the structured result.'],
+    },
+    run: async (input) => {
+        const quiet = input['quiet'];
+        const socket = input['tmuxSocket'] ?? tmuxSocketFromEnvironment();
+        const client = input['tmuxClient'];
+        const targetPane = paneForInvocation(input['targetPane']);
+        if (socket === undefined) {
+            const outcome = { action: 'skipped', message: 'the inbox needs tmux' };
+            return quiet ? undefined : outcome;
+        }
+        const viewers = liveViewerPanes(socket);
+        const targetViewer = targetPane === undefined ? undefined : viewers.find((viewer) => viewer.pane === targetPane);
+        const clientSession = targetViewer?.session ?? (targetPane === undefined ? undefined : paneLocation(targetPane)?.session) ?? currentTmux()?.session;
+        const viewer = selectViewer(viewers, targetPane, clientSession);
+        if (viewer === undefined) {
+            displayClientMessage(socket, client, NO_VIEWER_MESSAGE);
+            const outcome = { action: 'skipped', message: NO_VIEWER_MESSAGE };
+            return quiet ? undefined : outcome;
+        }
+        if (!sendAttachControl(socket, viewer.pane, 'crtr.attach.inbox.toggle')) {
+            const outcome = { action: 'skipped', message: 'could not deliver the inbox toggle to the selected viewer' };
+            return quiet ? undefined : outcome;
+        }
+        focusViewer(viewer, targetPane, clientSession);
+        const outcome = { action: 'opened' };
+        return quiet ? undefined : outcome;
+    },
+});

package/dist/commands/surface-inspect.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../core/command.js';
+export declare const surfaceInspectLeaf: LeafDef;

package/dist/commands/surface-inspect.js

@@ -0,0 +1,41 @@
+import { defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { inspectorCore } from '../core/inspector/core.js';
+import { inspectorText } from '../core/inspector/text.js';
+import { inspectorTui } from '../core/inspector/tui.js';
+import { inTmux } from '../core/runtime/placement-tmux.js';
+import { runInspector } from '../core/inspector/host.js';
+export const surfaceInspectLeaf = defineLeaf({
+    name: 'inspect',
+    description: 'host the native Inspector for one node',
+    whenToUse: 'you want a live native screen for a node’s overview, raw record, owner-scoped crons, and live background bash jobs. Use node inspect show for the underlying one-shot data read instead.',
+    help: {
+        name: 'surface inspect',
+        summary: 'host the native Inspector in this pane (the attach viewer opens it as a tmux popup)',
+        // sections: overview · schedule (armed crons) · jobs (live background bash) · raw
+        params: [
+            { kind: 'positional', name: 'node', required: true, constraint: 'Node id or resolvable reference to inspect.' },
+            { kind: 'flag', name: 'section', type: 'enum', choices: ['overview', 'schedule', 'jobs', 'raw'], required: false, default: 'overview', constraint: 'Section focused when the Inspector opens.' },
+            { kind: 'flag', name: 'read-only', type: 'bool', required: false, constraint: 'Offer no cron cancel or job stop, so the Inspector cannot change canvas state.' },
+        ],
+        output: [],
+        outputKind: 'object',
+        effects: ['Reads node, cron, and background bash job data through crtr subprocesses and crtrd. Takes over the hosting pane (or popup) until it quits.'],
+    },
+    run: async (input) => {
+        const node = input['node'];
+        const section = (input['section'] ?? 'overview');
+        const readOnly = input['readOnly'] === true ? 'true' : 'false';
+        const host = () => runInspector(inspectorCore, inspectorTui, inspectorText, { options: { target: node, section, readOnly } });
+        // Any non-interactive invocation (pipe, redirected stdout) is a static dump.
+        if (!process.stdin.isTTY || !process.stdout.isTTY) {
+            await host();
+            return;
+        }
+        if (!inTmux()) {
+            throw new InputError({ error: 'not_in_tmux', message: 'Inspector is tmux-only for interactive use.', next: 'Run it inside tmux, or pipe `crtr surface inspect <node>` for a static snapshot.' });
+        }
+        await host();
+    },
+    render: () => '',
+});

package/dist/commands/surface-node.d.ts

@@ -0,0 +1,2 @@
+import { type BranchDef } from '../core/command.js';
+export declare function registerSurfaceNode(): BranchDef;