@north-light/crouter 0.3.173 → 0.3.175

package/dist/commands/search.js

@@ -12,7 +12,7 @@ export function registerSearch() {
         rootEntry: {
             concept: 'web search for agents — find pages, get grounded answers, extract page content (Exa)',
             desc: 'search the web, answer a question with citations, or extract content from known URLs',
-            useWhen: 'you need information from the live web — current events, documentation, sources, facts beyond your training. Use web for relevant pages with excerpts, answer for one synthesized cited answer, and contents for clean text from URLs you already hold. This reaches PUBLIC pages read-only: for anything behind the user’s login, or any action inside a web app, drive their own browser with `crtr device`, and to call a service’s API server-side use `crtr connector`. Needs an Exa API key (EXA_API_KEY or ~/.crouter/exa.key).',
+            useWhen: 'you need information from the live web — current events, documentation, sources, facts beyond your training. Use web for relevant pages with excerpts, answer for one synthesized cited answer, and contents for clean text from URLs you already hold. This reaches public pages read-only, not logged-in pages or service APIs. Needs an Exa API key (EXA_API_KEY or ~/.crouter/exa.key).',
         },
         help: {
             name: 'search',

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

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

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

@@ -0,0 +1,83 @@
+// `crtr surface node cycle` — walk live viewers in DFS order.
+import { defineLeaf } from '../../../core/command.js';
+import { cliCanvasSource, getNodeOrNull, rethrowAsCliError } from '../../api-client.js';
+import { currentTmux, focusViewer, nodeInPane } from './placement.js';
+/** Every live node in DFS pre-order across the whole forest. The spawn tree is
+ *  the `parent` field; children inherit their parent's row order (created), so
+ *  the walk descends into a node's children before moving to its siblings —
+ *  exactly "next in pre-order is your first child". Roots are live nodes with no
+ *  live parent (a done/dead parent orphans its live children up to the top).
+ *  Cycle-safe: a final pass appends any node a cycle kept from being reached. */
+async function liveDfsOrder() {
+    const rows = await cliCanvasSource().listNodes({ status: ['active', 'idle'] }).catch(rethrowAsCliError); // ORDER BY created
+    const liveIds = new Set(rows.map((r) => r.node_id));
+    const childrenOf = new Map();
+    for (const r of rows) {
+        const p = r.parent;
+        if (p != null && liveIds.has(p)) {
+            const arr = childrenOf.get(p) ?? [];
+            arr.push(r.node_id);
+            childrenOf.set(p, arr);
+        }
+    }
+    const out = [];
+    const seen = new Set();
+    const visit = (id) => {
+        if (seen.has(id))
+            return;
+        seen.add(id);
+        out.push(id);
+        for (const c of childrenOf.get(id) ?? [])
+            visit(c);
+    };
+    for (const r of rows)
+        if (r.parent == null || !liveIds.has(r.parent))
+            visit(r.node_id);
+    for (const r of rows)
+        visit(r.node_id); // stragglers (parent cycles)
+    return out;
+}
+export const surfaceNodeCycleLeaf = defineLeaf({
+    name: 'cycle',
+    description: 'DFS-walk to the next/prev live node\'s viewer',
+    whenToUse: 'sweeping the canvas one viewer at a time, descending into children before siblings (bound to Alt+] forward / Alt+[ back). Use `surface node focus` instead to jump straight to a named node',
+    help: {
+        name: 'surface node cycle',
+        summary: 'focus the next/previous live node\'s viewer in DFS pre-order — the canvas walked one viewer at a time, descending into a node\'s children before its siblings (bound to Alt+] forward / Alt+[ back)',
+        params: [
+            { kind: 'flag', name: 'dir', type: 'enum', choices: ['next', 'prev'], required: false, default: 'next', constraint: 'Direction along the pre-order: next (Alt+], rightward/deeper into children) or prev (Alt+[, back). Wraps at the ends.' },
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane to cycle FROM. Defaults to $TMUX_PANE / your current pane. The Alt+] / Alt+[ bindings pass this for you.' },
+        ],
+        output: [
+            { name: 'focused', type: 'boolean', required: true, constraint: 'True when the neighbor was brought into view.' },
+            { name: 'node_id', type: 'string', required: false, constraint: 'The node now in front of you.' },
+            { name: 'name', type: 'string', required: false, constraint: 'Its display name.' },
+            { name: 'from', type: 'string', required: false, constraint: 'The node you cycled away from.' },
+        ],
+        outputKind: 'object',
+        effects: ['Brings the neighbor\'s viewer forefront beside the caller (like `surface node focus`); the viewer you were watching drops to the background.', 'Relaunches the neighbor\'s broker first if it was dormant.'],
+    },
+    run: async (input) => {
+        const pane = input['pane'] ?? process.env['TMUX_PANE'] ?? currentTmux()?.pane ?? undefined;
+        const dir = (input['dir'] ?? 'next');
+        const fromId = nodeInPane(pane);
+        if (fromId === undefined)
+            return { focused: false };
+        const order = await liveDfsOrder();
+        const i = order.indexOf(fromId);
+        if (i === -1 || order.length < 2)
+            return { focused: false, node_id: fromId, from: fromId };
+        const step = dir === 'next' ? 1 : -1;
+        const targetId = order[(i + step + order.length) % order.length];
+        const target = await getNodeOrNull(targetId);
+        if (target === null)
+            return { focused: false, from: fromId };
+        // Placement brings the neighbor's viewer forefront beside the caller; the
+        // server (ensureAttach, inside focusViewer) relaunches its broker if dormant.
+        const res = await focusViewer(targetId, { cwd: target.cwd, name: target.name, pane });
+        return { focused: res.focused, node_id: targetId, name: target.name, from: fromId };
+    },
+    render: (r) => r['focused'] === true
+        ? `Cycled to "${r['name'] ?? ''}" (${r['node_id']}) — from ${r['from'] ?? '?'}.`
+        : 'No other live node to focus.',
+});

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

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

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

@@ -0,0 +1,67 @@
+// `crtr surface node focus` — bring one viewer forward.
+import { defineLeaf } from '../../../core/command.js';
+import { InputError } from '../../../core/io.js';
+import { inboxHint } from '../../../core/keybindings/index.js';
+import { cliClient, rethrowAsCliError } from '../../api-client.js';
+import { currentTmux, displayPopup, focusViewer, shellQuote } from './placement.js';
+export const surfaceNodeFocusLeaf = defineLeaf({
+    name: 'focus',
+    description: 'bring a node into view without accidentally reviving finished work',
+    whenToUse: 'you want to bring a specific node into view — live nodes open or move their viewer beside your current pane; completed, canceled, or crashed nodes open their saved transcript instead. Use `node lifecycle revive` only when you deliberately want to relaunch a dormant agent. Use `surface node cycle` to walk neighbors, and `node message send` to steer without leaving where you are',
+    help: {
+        name: 'surface node focus',
+        summary: 'bring a node into view — attach to a live broker, or open a saved transcript for a non-live node without reviving it',
+        params: [
+            { kind: 'positional', name: 'node', required: true, constraint: 'Node id to focus.' },
+            { kind: 'flag', name: 'new-pane', type: 'bool', required: false, constraint: 'Always open a NEW viewer SIDE-BY-SIDE with your current pane instead of moving/reusing the node\'s existing viewer. Two agents on screen at once (F4).' },
+            { kind: 'flag', name: 'in-place', type: 'bool', required: false, constraint: 'Re-exec the --pane pane ONTO this node, REPLACING whatever viewer it showed (a swap in place, not a split beside). Backs the attach viewer\'s subagent scroll+swap (↓ into the reports roster, Enter dives into the child right in your pane). MUST be driven from OUTSIDE that pane\'s process tree (e.g. `tmux run-shell`) — respawn-pane -k kills whatever runs in it. Mutually exclusive with --new-pane.' },
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane id to focus beside (default: caller TMUX_PANE). Used by the canvas browser popup to focus back into the originating pane.' },
+        ],
+        output: [
+            { name: 'focused', type: 'boolean', required: true, constraint: 'True when the node\'s viewer was brought into view.' },
+            { name: 'session', type: 'string', required: false, constraint: 'The tmux session the viewer lives in.' },
+            { name: 'revived', type: 'boolean', required: true, constraint: 'True when focusing a live node had to relaunch its broker; false for a saved-transcript inspection.' },
+            { name: 'in_place', type: 'boolean', required: true, constraint: 'True when an existing viewer was navigated to (no new pane); false when a fresh viewer pane was opened or moved beside you.' },
+        ],
+        outputKind: 'object',
+        effects: ['For active/idle nodes: opens/moves the one surface-attach viewer beside the caller, or navigates to its existing viewer.', 'For done/dead/canceled nodes: opens a read-only saved transcript popup. It does not launch a broker or change node status.', 'With --new-pane/--in-place on a live node: controls whether the viewer splits beside or replaces the caller pane.'],
+    },
+    run: async (input) => {
+        const id = input['node'];
+        const node = await cliClient()
+            .getNode(id)
+            .catch((err) => rethrowAsCliError(err, 'List nodes with `crtr node inspect list`.'));
+        // A kind:'human' node is a control-plane ASK (a humanloop deck on the human's
+        // screen), NOT a pi conversation — it has no session. Reviving one boots a
+        // confused blank "you have been revived" pi, so refuse rather than focus it.
+        // (The nav/resume UIs already hide human nodes; this guards a hand-typed id.)
+        if (node.kind === 'human') {
+            throw new InputError({
+                error: 'not_focusable',
+                message: `node ${id} is a human-ask (kind:human), not a conversation — it has no pi session to focus.`,
+                next: `The pending question is queued for the human (${inboxHint()} opens the inbox); see it with \`crtr human list\`, or retract it with \`crtr human cancel ${id}\`.`,
+            });
+        }
+        // Opening history is not resuming work. A terminal/canceled/crashed node has
+        // no live broker to attach to, so show its persisted transcript in a popup;
+        // `node lifecycle revive` remains the explicit state-changing operation.
+        if (node.status !== 'active' && node.status !== 'idle') {
+            const pane = input['pane'] ?? process.env['TMUX_PANE'] ?? currentTmux()?.pane;
+            const focused = pane !== undefined && pane !== ''
+                ? displayPopup(pane, node.cwd, `crtr node inspect transcript ${shellQuote(id)}`)
+                : false;
+            return { focused, session: null, revived: false, in_place: false };
+        }
+        // Local viewer tail: open/move the broker-backed viewer beside the caller.
+        // The server (ensureAttach) owns the revive + view.sock wait; pure tmux ops
+        // own the pane placement.
+        const res = await focusViewer(id, {
+            cwd: node.cwd,
+            name: node.name,
+            pane: input['pane'],
+            newPane: input['newPane'] === true,
+            inPlace: input['inPlace'] === true,
+        });
+        return { focused: res.focused, session: res.session, revived: res.revived, in_place: res.inPlace };
+    },
+});

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

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

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,46 @@
+import { closePane, currentTmux, displayPopup, paneCurrentPath, paneExists, panePid, paneStartCommand, respawnPaneInPlace, respawnPaneSync, shellQuote, viewerSplitEnv } from '../../../core/runtime/placement-tmux.js';
+export { closePane, currentTmux, displayPopup, paneCurrentPath, paneExists, panePid, paneStartCommand, respawnPaneInPlace, respawnPaneSync, shellQuote, viewerSplitEnv };
+export declare function viewerEnv(): Record<string, string>;
+/** The live viewer pane for `nodeId` (the pane a surface-attach viewer tagged
+ *  `@crtr_node`), or undefined. Pure tag scan over live panes. */
+export declare function viewerPaneOf(nodeId: string): string | undefined;
+interface FocusViewerOpts {
+    cwd: string;
+    name: string;
+    pane?: string;
+    newPane?: boolean;
+    inPlace?: boolean;
+}
+interface FocusViewerResult {
+    focused: boolean;
+    session: string | null;
+    inPlace: boolean;
+    revived: boolean;
+}
+/** Bring a node's ONE viewer forefront beside (or navigated to) the caller —
+ *  the pure-tmux port of placement.ts `focus()`. The server (`ensureAttach`)
+ *  owns the broker revive + the view.sock accept-wait; the `@crtr_node` pane tag
+ *  is the viewer registry. crtr is tmux-only: no caller pane ⇒ not focused. */
+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
+ *  re-plumbed CLI no longer reads 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,124 @@
+// `crtr surface node` — pure tmux placement for node viewers.
+import { closePane, currentTmux, displayPopup, ensureSession, getPaneOption, listLivePanes, openNodeWindow, paneCurrentPath, paneExists, paneLocation, panePid, paneStartCommand, renameWindow, respawnPaneInPlace, respawnPaneSync, selectLayout, selectPane, selectWindow, setPaneOption, shellQuote, splitWindow, switchClient, viewerSplitEnv, windowOfPane, } from '../../../core/runtime/placement-tmux.js';
+import { cliClient, rethrowAsCliError } from '../../api-client.js';
+export { closePane, currentTmux, displayPopup, paneCurrentPath, paneExists, panePid, paneStartCommand, respawnPaneInPlace, respawnPaneSync, shellQuote, viewerSplitEnv };
+export function viewerEnv() {
+    const crtrHome = process.env['CRTR_HOME'];
+    return crtrHome !== undefined ? { CRTR_HOME: crtrHome } : {};
+}
+/** The live viewer pane for `nodeId` (the pane a surface-attach viewer tagged
+ *  `@crtr_node`), or undefined. Pure tag scan over live panes. */
+export function viewerPaneOf(nodeId) {
+    const panes = listLivePanes();
+    if (panes === null)
+        return undefined;
+    for (const pane of panes) {
+        if (getPaneOption(pane, '@crtr_node') === nodeId)
+            return pane;
+    }
+    return undefined;
+}
+/** Open a fresh surface-attach viewer SPLIT beside `callerPane` and rebalance
+ *  its window to even side-by-side widths. Pure tmux. */
+function openBesideCaller(callerPane, nodeId, cwd, callerSession, revived) {
+    const opened = splitWindow(callerPane, { cwd, env: viewerEnv(), command: `crtr surface attach to ${nodeId}` });
+    if (opened === null)
+        return { focused: false, session: null, inPlace: false, revived };
+    const loc = paneLocation(opened);
+    if (loc !== null)
+        selectLayout(loc.window, 'even-horizontal');
+    selectPane(opened);
+    return { focused: true, session: loc?.session ?? callerSession, inPlace: false, revived };
+}
+/** Bring a node's ONE viewer forefront beside (or navigated to) the caller —
+ *  the pure-tmux port of placement.ts `focus()`. The server (`ensureAttach`)
+ *  owns the broker revive + the view.sock accept-wait; the `@crtr_node` pane tag
+ *  is the viewer registry. crtr is tmux-only: no caller pane ⇒ not focused. */
+export async function focusViewer(nodeId, opts) {
+    const callerPane = opts.pane ?? process.env['TMUX_PANE'] ?? currentTmux()?.pane;
+    if (callerPane === undefined || callerPane === '') {
+        return { focused: false, session: null, inPlace: false, revived: false };
+    }
+    // (a) Server ensures the broker engine is alive + its view.sock accepts.
+    const attach = await cliClient().ensureAttach(nodeId).catch(rethrowAsCliError);
+    const revived = attach.revived;
+    const callerSession = paneLocation(callerPane)?.session ?? null;
+    // (b0) --in-place → the caller pane BECOMES this node's viewer, replacing what
+    //      it showed. Must be driven from OUTSIDE that pane's process tree.
+    if (opts.inPlace === true) {
+        const priorNodeId = getPaneOption(callerPane, '@crtr_node');
+        const existing = viewerPaneOf(nodeId);
+        if (existing !== undefined && existing !== callerPane && paneExists(existing))
+            closePane(existing);
+        try {
+            setPaneOption(callerPane, '@crtr_node', '');
+        }
+        catch { /* best-effort */ }
+        const window = windowOfPane(callerPane);
+        const env = priorNodeId !== undefined && priorNodeId !== ''
+            ? { ...viewerEnv(), CRTR_ATTACH_ROSTER: priorNodeId }
+            : viewerEnv();
+        const ok = respawnPaneSync({ pane: callerPane, cwd: opts.cwd, env, command: `crtr surface attach to ${nodeId}` });
+        if (ok && window !== null)
+            renameWindow(window, opts.name);
+        return { focused: ok, session: callerSession, inPlace: true, revived };
+    }
+    // (b) --new-pane → always a fresh viewer beside the caller; drop any prior
+    //     viewer this node holds elsewhere (one viewer per node).
+    if (opts.newPane === true) {
+        const prior = viewerPaneOf(nodeId);
+        if (prior !== undefined && paneExists(prior))
+            closePane(prior);
+        return openBesideCaller(callerPane, nodeId, opts.cwd, callerSession, revived);
+    }
+    // (c) Reuse the node's existing tagged viewer wherever it already lives.
+    const existing = viewerPaneOf(nodeId);
+    if (existing !== undefined) {
+        const loc = paneLocation(existing);
+        if (loc !== null) {
+            switchClient(loc.session);
+            selectWindow(loc.session, loc.window);
+            selectPane(existing);
+            return { focused: true, session: loc.session, inPlace: true, revived };
+        }
+    }
+    // (d) No live viewer → open one beside the caller.
+    return openBesideCaller(callerPane, nodeId, opts.cwd, callerSession, revived);
+}
+/** 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
+ *  re-plumbed CLI no longer reads 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-node.js

@@ -1,6 +1,9 @@
 // `crtr surface node` — screen navigation for canvas-node viewers.
 import { defineBranch } from '../core/command.js';
-import { surfaceNodeCycleLeaf, surfaceNodeFocusLeaf, surfaceNodeIdLeaf, surfaceNodePinLeaf } from './node.js';
+import { surfaceNodeFocusLeaf } from './surface/node/focus.js';
+import { surfaceNodeCycleLeaf } from './surface/node/cycle.js';
+import { surfaceNodeIdLeaf } from './surface/node/id.js';
+import { surfaceNodePinLeaf } from './surface/node/pin.js';
 export function registerSurfaceNode() {
     return defineBranch({
         name: 'node',

package/dist/commands/surface-reload.js

@@ -9,8 +9,7 @@ import { spawnSync } from 'node:child_process';
 import { defineLeaf } from '../core/command.js';
 import { InputError } from '../core/io.js';
 import { displayMessage } from '../core/runtime/tmux-chrome.js';
-import { paneCurrentPath, paneStartCommand, panePid, respawnPaneInPlace, respawnPaneSync, viewerSplitEnv, } from '../core/runtime/placement-tmux.js';
-import { nodeInPane } from './node.js';
+import { nodeInPane, paneCurrentPath, panePid, paneStartCommand, respawnPaneInPlace, respawnPaneSync, viewerSplitEnv, } from './surface/node/placement.js';
 /** True when `rootPid` (the pane's `#{pane_pid}`) or any descendant of it is a
  *  live `crtr surface attach to <nodeId>` viewer process. This is how a
  *  shell-hosted viewer is recognized: older panes were opened as a login shell

package/dist/commands/surface-tmux-spread.js

@@ -1,7 +1,7 @@
 // `crtr surface tmux-spread <node>` — explode the local subtree into a tiled grid.
 //
 // A genuine viewer-placement decision (tile every live viewer in a subtree into
-// one window), so it lives under `surface` alongside view/attach/workspace/web.
+// one window), so it lives under `surface` alongside the other viewer-placement commands.
 // The command expands the graph being watched: the caller's
 // own viewer pane is broken out into a BRAND-NEW window, then a surface-attach
 // viewer pane is tiled beside it for every broker-alive node in the local

package/dist/commands/surface.js

@@ -2,41 +2,26 @@
 //
 // Groups the screen-facing surface families under one canonical noun.
 import { defineBranch } from '../core/command.js';
-import { registerWeb } from '../clients/web/web-cmd.js';
 import { registerAttach } from '../clients/attach/command.js';
 import { tmuxSpreadLeaf } from './surface-tmux-spread.js';
 import { surfaceEditLeaf } from './surface-edit.js';
 import { registerSurfaceNode } from './surface-node.js';
 import { surfaceInspectLeaf } from './surface-inspect.js';
 import { surfaceReloadLeaf } from './surface-reload.js';
-function namespaceForSurface(node) {
-    node.help.name = `surface ${node.help.name}`;
-    if (node.kind === 'branch') {
-        node.description = node.rootEntry?.concept ?? node.description ?? '';
-        node.whenToUse = node.rootEntry?.useWhen ?? node.whenToUse ?? '';
-        for (const child of node.children)
-            namespaceForSurface(child);
-    }
-}
 export function registerSurface() {
-    const attach = registerAttach();
-    const web = registerWeb();
-    for (const child of [attach, web]) {
-        child.tier = 'important';
-        namespaceForSurface(child);
-    }
+    const attach = registerAttach('surface', 'important');
     return defineBranch({
         name: 'surface',
         rootEntry: {
-            concept: 'screen-facing surfaces — node viewers, live broker attachment, the Inspector, and the browser shell',
+            concept: 'screen-facing surfaces — node viewers, live broker attachment, and the Inspector',
             desc: 'open and manage screen-facing surfaces',
-            useWhen: 'you need a UI or presentation surface rather than a node, document, or graph operation — node-viewer navigation, live broker attachment, node inspection, or the browser-hosted shell',
+            useWhen: 'you need a UI or presentation surface rather than a node, document, or graph operation — node-viewer navigation, live broker attachment, node inspection, tmux placement, or an editor pane',
         },
         help: {
             name: 'surface',
             summary: 'open and manage screen-facing surfaces',
-            model: 'Choose `node` for navigation among node viewers. The other commands open a broker attachment, node Inspector, browser shell, subtree spread, or adjacent editor pane.',
+            model: 'Choose `node` for navigation among node viewers. The other commands open a broker attachment, node Inspector, subtree spread, reload, or adjacent editor pane.',
         },
-        children: [registerSurfaceNode(), attach, web, surfaceInspectLeaf, surfaceReloadLeaf, tmuxSpreadLeaf, surfaceEditLeaf],
+        children: [registerSurfaceNode(), attach, surfaceInspectLeaf, surfaceReloadLeaf, tmuxSpreadLeaf, surfaceEditLeaf],
     });
 }