@north-light/crouter 0.3.154

package/dist/clients/attach/session/editor-frame.js

@@ -0,0 +1,136 @@
+// session/editor-frame.ts — the EDITOR CHROME topic: everything painted onto
+// the editor's frame itself — border + title-chip styling, the bottom-right
+// context badge, the session-title chip, and the git context in the top border.
+//
+// The frame is a cue, not chrome for its own sake: a leading `!`/`!!` recolors
+// the whole editor to say "this goes to a shell, not the agent", and otherwise
+// the border tracks the engine's thinking level.
+import { basename } from 'node:path';
+import { modeIcon, personaLabel } from '../../../core/canvas/labels.js';
+import { colorChipStyle, defaultTitleStyle, thinkingBorderColor, thinkingTitleStyle } from '../input/titled-editor.js';
+import { fetchGitInfo } from '../chrome/git-info.js';
+/** Nerd Font terminal glyph marks a one-shot node; resident nodes need no
+ *  lifecycle glyph because they persist by default. */
+const TERMINAL_NODE_ICON = '\uf489';
+/** Derive the shell-mode cue from the editor contents. Leading whitespace is
+ *  ignored so pasted commands and indented text still toggle correctly. */
+export function deriveBashMode(text) {
+    const lead = text.trimStart();
+    return lead.startsWith('!!') ? 2 : lead.startsWith('!') ? 1 : 0;
+}
+/** Resolve the editor border + title-chip styles for the current shell cue. */
+export function resolveEditorFrameStyles(bashMode, thinkingLevel, pal) {
+    if (bashMode === 2) {
+        return {
+            borderColor: pal.bashModeAlt,
+            titleStyle: (s) => `\x1b[102m\x1b[30m\x1b[1m ${s} \x1b[0m`,
+        };
+    }
+    if (bashMode === 1) {
+        return {
+            borderColor: pal.bashMode,
+            titleStyle: (s) => `\x1b[42m\x1b[97m\x1b[1m ${s} \x1b[0m`,
+        };
+    }
+    return {
+        borderColor: thinkingBorderColor(thinkingLevel, pal.border),
+        titleStyle: thinkingTitleStyle(thinkingLevel, defaultTitleStyle),
+    };
+}
+/** The editor-chrome collaborator: owns the shell/bash level (`deriveBashMode`
+ *  over `editor.onChange` is its ONE writer) and the `/color` chip override,
+ *  and paints every frame-attached adornment — border hue, title chip, context
+ *  badge, and git context. */
+export function createEditorChrome(ctx, hooks) {
+    const { meta, tui, pal, editor } = ctx;
+    // Shell/bash mode: the editor text leads with `!`. Tracks pi's interactive
+    // `isBashMode`, which recolors the editor border green as a visual cue (#7).
+    // Three levels: 0 = off, 1 = `!` (output goes to the agent's context), 2 = `!!`
+    // (output hidden from the agent). The level drives BOTH the border hue (dull vs
+    // bright green) and a status-bar segment explaining what will happen.
+    let bashMode = 0;
+    // `/color` override for the name chip — null means the default (thinking-
+    // tracking) chip. Bash mode still wins: the green frame is a live safety cue.
+    let chipColor = null;
+    const syncContextBadge = (dir = basename(meta.cwd) || meta.cwd) => {
+        const identity = hooks.nodeIdentity();
+        const lifecycle = identity?.lifecycle === 'terminal' ? `${TERMINAL_NODE_ICON} ` : '';
+        const persona = identity ? ` · ${personaLabel(identity)}` : '';
+        editor.contextBadge = `${lifecycle}${dir}${persona}`;
+    };
+    // Normalize an icon-and-kind session label so persona remains exclusively in
+    // the bottom-right badge while the viewer is attached.
+    const displaySessionTitle = (sessionName) => {
+        const identity = hooks.nodeIdentity();
+        const raw = sessionName ?? '';
+        if (raw === '' || identity === undefined)
+            return raw;
+        const legacyPrefix = `${modeIcon(identity.mode)} `;
+        const withoutIcon = raw.startsWith(legacyPrefix) ? raw.slice(legacyPrefix.length) : raw;
+        const withoutKind = withoutIcon.endsWith(` ${identity.kind}`)
+            ? withoutIcon.slice(0, -identity.kind.length - 1)
+            : withoutIcon;
+        return withoutKind === identity.kind ? '' : withoutKind;
+    };
+    // Paint the editor border + title chip. Shell/bash mode (leading `!`) wins and
+    // forces the whole frame green (#7); otherwise the hue tracks the thinking
+    // level. One place so the onChange bash toggle and live-state updates agree.
+    const paintFrame = () => {
+        const frame = resolveEditorFrameStyles(bashMode, hooks.thinkingLevel(), pal);
+        editor.borderColor = frame.borderColor;
+        editor.titleStyle = frame.titleStyle;
+        editor.contextBadgeStyle = frame.titleStyle;
+        if (bashMode === 0 && chipColor !== null) {
+            const style = colorChipStyle(chipColor);
+            if (style !== undefined)
+                editor.titleStyle = style;
+        }
+    };
+    // Recolor the editor when `!` enters/leaves the front of the input (#7). pi's
+    // interactive mode does the same off `editor.onChange`.
+    editor.onChange = (text) => {
+        hooks.onTextChange(text);
+        const next = deriveBashMode(text);
+        if (next !== bashMode) {
+            bashMode = next;
+            paintFrame();
+            hooks.renderFooter(); // the status segment tracks the bash level
+        }
+        tui.requestRender();
+    };
+    // Git context painted into the RIGHT of the editor's top border: branch and
+    // status symbols (● dirty, ⇡ ahead, ⇣ behind). The cwd leaf lives in the
+    // editor's bottom-right node and workspace badge. Refreshed by the poll.
+    const renderGitInfo = (info) => {
+        const parts = [];
+        if (info.branch)
+            parts.push(pal.info(`⎇ ${info.branch}`));
+        const sym = [];
+        if (info.dirty)
+            sym.push(pal.warning('●'));
+        if (info.ahead > 0)
+            sym.push(pal.active(`⇡${info.ahead}`));
+        if (info.behind > 0)
+            sym.push(pal.active(`⇣${info.behind}`));
+        if (sym.length > 0)
+            parts.push(sym.join(''));
+        // A trailing space keeps the symbols off the very last border cell.
+        editor.info = parts.length > 0 ? ` ${parts.join(pal.muted(' · '))} ` : '';
+        syncContextBadge(info.dir);
+        tui.requestRender();
+    };
+    return {
+        bashMode: () => bashMode,
+        setChipColor: (color) => {
+            chipColor = color;
+            paintFrame();
+            tui.requestRender();
+        },
+        paintFrame,
+        setTitle: (sessionName) => {
+            editor.title = displaySessionTitle(sessionName);
+        },
+        syncContextBadge: () => syncContextBadge(),
+        pollGit: () => fetchGitInfo(meta.cwd, renderGitInfo),
+    };
+}

package/dist/clients/attach/session/editor-inventory.d.ts

@@ -0,0 +1,59 @@
+import { CombinedAutocompleteProvider } from '@earendil-works/pi-tui';
+import type { BrokerDataFrame, RefMeta } from '../../../core/runtime/broker-protocol.js';
+import { type PreviewableCommand } from '../slash/prompt-preview.js';
+import type { AttachBindings } from './bindings.js';
+import type { AttachSession } from './context.js';
+export declare function buildAttachAutocompleteProvider(cwd: string, fdPath: string | null, commands?: ReadonlyArray<{
+    name: string;
+    description?: string;
+}>, remote?: boolean, createProvider?: (items: ReadonlyArray<{
+    name: string;
+    description?: string;
+}>, cwd: string, fdPath: string | null) => CombinedAutocompleteProvider): CombinedAutocompleteProvider;
+/** Requests the broker's memory-ref inventory (`request({type:'list_memory_refs'})`)
+ *  and drives `setMemoryRefs` — the epoch-guarded lifecycle behind inline memory
+ *  references. Every `reset()` call:
+ *  1. bumps a monotonic epoch, immediately superseding any still-in-flight
+ *     request from a prior `reset()` (a stale welcome/reload/reconnect);
+ *  2. clears the inventory synchronously via `setMemoryRefs([])`, so a
+ *     partially-typed ref never keeps highlighting/completing against a
+ *     dead broker's stale names;
+ *  3. issues one correlated request and installs its `refs` ONLY if the reply
+ *     both belongs to the latest epoch AND is a well-formed
+ *     `list_memory_refs` data frame.
+ *  A timeout, rejection, or malformed/mismatched `kind` degrades silently to
+ *  the already-empty inventory — no retry, no local fallback. Command and ref
+ *  arrival are independent: this coordinator never touches command state. */
+export interface MemoryRefRefreshCoordinator {
+    reset: () => void;
+}
+export declare function createMemoryRefRefreshCoordinator(setMemoryRefs: (refs: ReadonlyArray<RefMeta>, engineLeadingCommandNames: ReadonlyArray<string>) => void, request: (frame: {
+    type: 'list_memory_refs';
+}) => Promise<BrokerDataFrame>): MemoryRefRefreshCoordinator;
+/** The verbs `runAttach` still needs from the inventory owner. Nothing outside
+ *  this module writes the command/ref state — the orchestrator only feeds
+ *  arrivals in (`setCommands`, `resetMemoryRefs`) and mirrors editor text
+ *  (`syncCommandPreview`). */
+export interface EditorInventory {
+    /** Install the broker's command metadata (frames wiring: `get_commands`). */
+    setCommands: (next?: ReadonlyArray<PreviewableCommand>) => void;
+    /** Restart the epoch-guarded ref-inventory lifecycle (welcome / `/reload`). */
+    resetMemoryRefs: () => void;
+    /** Recompute the loaded-command preview from the current editor text. */
+    syncCommandPreview: (text: string) => void;
+    /** tmux/nvim popup showing the loaded prompt template's exact payload. */
+    inspectLoadedCommand: () => void;
+}
+export interface EditorInventoryHooks {
+    setNotice: (msg: string) => void;
+    /** Live binding snapshot — read at call time so a `/reload` is honored. */
+    bindings: () => AttachBindings;
+    /** Resolved once in `runAttach`; never changes for the session. */
+    fdPath: string | null;
+}
+/** Owns everything the editor can complete against — the merged slash-command
+ *  list, the loaded-command preview, the broker's raw command metadata, and the
+ *  memory-ref inventory — plus the popup that inspects the loaded template.
+ *  Construction seeds the command list with builtins-only (`setCommands()`), so
+ *  autocomplete works before the broker's first `get_commands` ack. */
+export declare function createEditorInventory(ctx: Pick<AttachSession, 'remote' | 'meta' | 'socket' | 'tui' | 'editor'>, hooks: EditorInventoryHooks): EditorInventory;

package/dist/clients/attach/session/editor-inventory.js

@@ -0,0 +1,161 @@
+// session/editor-inventory.ts — what the editor knows it can complete against:
+// the slash-command list, the loaded-command preview, and the broker's
+// memory-ref inventory. `createEditorInventory` OWNS that state — nothing
+// outside this module writes it.
+//
+// Both inventories arrive independently (a command reply and a ref reply race
+// each other), so neither may rebuild the editor's provider having silently
+// dropped the other — everything funnels through one `syncEditorInventories`
+// seam. The builders below stay pure so that contract is testable without a
+// socket, TUI, or broker.
+import { execFile } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { CombinedAutocompleteProvider } from '@earendil-works/pi-tui';
+import { formatBinding } from '../../../core/keybindings/index.js';
+import { inTmux, shellQuote } from '../../../core/runtime/placement-tmux.js';
+import { surfaceTmuxStyleArgs } from '../../../core/runtime/surface-bg.js';
+import { RefAwareAutocompleteProvider } from '../input/ref-autocomplete.js';
+import { CANVAS_SLASH_COMMANDS, locallyConsumedCommandNames, slashCommandList } from '../slash/dispatch.js';
+import { loadedCommandPreview } from '../slash/prompt-preview.js';
+export function buildAttachAutocompleteProvider(cwd, fdPath, commands, remote = false, createProvider = (items, cwd, path) => new CombinedAutocompleteProvider([...items], cwd, path)) {
+    return createProvider([...slashCommandList(commands, remote)], cwd, fdPath);
+}
+export function createMemoryRefRefreshCoordinator(setMemoryRefs, request) {
+    let epoch = 0;
+    return {
+        reset: () => {
+            const myEpoch = ++epoch;
+            setMemoryRefs([], []);
+            void request({ type: 'list_memory_refs' })
+                .then((data) => {
+                if (myEpoch !== epoch)
+                    return; // a newer reset (reconnect/reload) superseded this one
+                if (data.kind !== 'list_memory_refs')
+                    return; // malformed/mismatched reply — stay empty
+                setMemoryRefs(data.refs, data.engineLeadingCommandNames);
+            })
+                .catch(() => {
+                // Timeout / rejected request — the immediate clear above already left
+                // the inventory empty; no retry, no local fallback.
+            });
+        },
+    };
+}
+/** Owns everything the editor can complete against — the merged slash-command
+ *  list, the loaded-command preview, the broker's raw command metadata, and the
+ *  memory-ref inventory — plus the popup that inspects the loaded template.
+ *  Construction seeds the command list with builtins-only (`setCommands()`), so
+ *  autocomplete works before the broker's first `get_commands` ack. */
+export function createEditorInventory(ctx, hooks) {
+    const { remote, meta, socket, tui, editor } = ctx;
+    let commands = [];
+    let commandPreview;
+    // The broker's RAW command metadata (`undefined` until the first get_commands
+    // ack — kept distinct from `[]`, same undefined-vs-empty contract
+    // `buildAttachAutocompleteProvider` already relies on) and the broker's raw
+    // memory-ref inventory, kept SEPARATE from each other and from the merged
+    // `commands` preview list above: a late reply to one inventory must rebuild
+    // the provider/highlight sets from the CURRENT value of the other, never
+    // drop it. `syncEditorInventories` is the single place that reads both.
+    let brokerCommands;
+    let memoryRefs = [];
+    // The broker's `engineLeadingCommandNames` from the latest `list_memory_refs`
+    // reply (design: inline memory references, review Major 6) — leading tokens
+    // the ENGINE independently consumes, kept separate from the viewer-local
+    // `locallyConsumedCommandNames()` set and fed to the editor's untrimmed
+    // engine-suppression rule via `setEngineCommandNames`.
+    let engineLeadingCommandNames = [];
+    const commandInspectHint = () => {
+        const bindings = hooks.bindings();
+        return bindings.gestures('crtr.attach.command.inspect').length > 0
+            ? `${formatBinding(bindings, 'crtr.attach.command.inspect')} inspect`
+            : 'inspect binding disabled';
+    };
+    const syncCommandPreview = (text) => {
+        commandPreview = loadedCommandPreview(text, commands);
+        editor.loadedCommand = commandPreview === undefined
+            ? undefined
+            : { name: commandPreview.name, content: commandPreview.content, inspectHint: commandInspectHint() };
+    };
+    // Atomically rebuild the editor's provider/highlight state from whatever
+    // command + ref inventory is CURRENTLY known — the one seam `setCommands` and
+    // `setMemoryRefs` both call, so a command-only or ref-only response can never
+    // rebuild the provider having silently dropped the other inventory (T3
+    // ownership note: this module combines command metadata, ref metadata,
+    // provider rebuild, and editor highlight sets in one place). Command-only
+    // autocomplete is unchanged: `RefAwareAutocompleteProvider` fully delegates
+    // leading-slash and every non-ref context to the wrapped command provider, so
+    // refs never enter command completion or the loaded-command preview (which
+    // reads only `commands`, never `memoryRefs`).
+    const syncEditorInventories = () => {
+        const commandProvider = buildAttachAutocompleteProvider(meta.cwd, hooks.fdPath, brokerCommands, remote);
+        editor.setAutocompleteProvider(new RefAwareAutocompleteProvider(memoryRefs, commandProvider));
+        editor.setResolvedRefNames(memoryRefs.map((ref) => ref.name));
+        // Two independent suppression inventories (review Major 6): the viewer-local
+        // set (everything `dispatchSlashCommand` handles entirely locally, trimmed
+        // rule) and the broker's own `engineLeadingCommandNames` (untrimmed rule) —
+        // never the merged display/completion list `slashCommandList` returns.
+        editor.setLocalCommandNames(locallyConsumedCommandNames());
+        editor.setEngineCommandNames(engineLeadingCommandNames);
+        syncCommandPreview(editor.getText());
+    };
+    // Slash-command autocomplete starts with builtins + native canvas commands,
+    // then incorporates engine commands and prompt templates from get_commands.
+    // Template bodies stay alongside their autocomplete metadata so the editor can
+    // reveal the exact expanded payload before the user submits it. Responsible
+    // ONLY for the command side of the inventory — always ends with
+    // `syncEditorInventories()` so a command update never rebuilds the provider
+    // without the current ref inventory.
+    const setCommands = (next) => {
+        brokerCommands = next;
+        // Viewer-owned commands are intercepted before anything reaches the broker,
+        // so they must lead preview lookup too. Their lack of expansion metadata
+        // deliberately suppresses any shadowed extension/template disclosure.
+        commands = [
+            ...CANVAS_SLASH_COMMANDS.map((command) => ({ ...command, source: 'builtin' })),
+            ...(next ?? []),
+        ];
+        syncEditorInventories();
+    };
+    // Responsible ONLY for the ref side of the inventory — mirrors `setCommands`,
+    // always ending with the same `syncEditorInventories()` seam. Ref arrival
+    // must repaint decoration on already-typed prose immediately (the design's
+    // "gains decoration immediately" contract), so this is the one place that
+    // requests a render after an inventory change.
+    const setMemoryRefs = (next, nextEngineLeadingCommandNames) => {
+        memoryRefs = next;
+        engineLeadingCommandNames = nextEngineLeadingCommandNames;
+        syncEditorInventories();
+        tui.requestRender();
+    };
+    setCommands();
+    // The correlated ref-inventory lifecycle (design: inline memory references,
+    // T3 terminal integration). `socket.request` is the same observer-safe
+    // read-op channel local and remote attach already share, so this is
+    // transport-agnostic for free. Reset from `welcome` and a successful
+    // `/reload` — see the frames wiring in `runAttach`.
+    const memoryRefRefresh = createMemoryRefRefreshCoordinator(setMemoryRefs, (f) => socket.request(f));
+    const inspectLoadedCommand = () => {
+        if (commandPreview === undefined) {
+            hooks.setNotice('No prompt-template command is loaded in the editor');
+            return;
+        }
+        if (!inTmux()) {
+            hooks.setNotice('Command inspection requires tmux');
+            return;
+        }
+        const dir = mkdtempSync(join(tmpdir(), 'crtr-command-'));
+        const path = join(dir, `${commandPreview.name.replace(/[^A-Za-z0-9_.-]/g, '-')}.md`);
+        writeFileSync(path, `# /${commandPreview.name}\n\nInvocation: \`${commandPreview.invocation.replaceAll('`', '\\`')}\`\n\n${commandPreview.content}\n`, 'utf8');
+        const cmd = `if command -v nvim >/dev/null 2>&1; then exec nvim -R -- ${shellQuote(path)}; else printf 'nvim is required to inspect loaded commands. Install Neovim and retry.\\n'; printf 'Press Enter to close.'; read _; fi`;
+        execFile('tmux', ['display-popup', '-E', '-w', '90%', '-h', '85%', ...surfaceTmuxStyleArgs(), cmd], () => rmSync(dir, { recursive: true, force: true }));
+    };
+    return {
+        setCommands,
+        resetMemoryRefs: () => memoryRefRefresh.reset(),
+        syncCommandPreview,
+        inspectLoadedCommand,
+    };
+}

package/dist/clients/attach/session/focus-events.d.ts

@@ -0,0 +1,4 @@
+export declare const FOCUS_REPORTING_ON = "\u001B[?1004h";
+export declare const FOCUS_REPORTING_OFF = "\u001B[?1004l";
+export declare const FOCUS_IN = "\u001B[I";
+export declare const FOCUS_OUT = "\u001B[O";

package/dist/clients/attach/session/focus-events.js

@@ -0,0 +1,12 @@
+// session/focus-events.ts — terminal focus reporting (DECSET 1004).
+//
+// The terminal (or tmux, per pane, with `focus-events on`) sends FOCUS_IN /
+// FOCUS_OUT as the viewer gains and loses focus. The viewer enables reporting
+// after `tui.start()`, reads the events in its global input listener to drive
+// the editor's hollow cursor, and DISABLES reporting again during terminal
+// restore — so the enable and the disable live in different modules and share
+// these constants rather than re-spelling the escape sequences.
+export const FOCUS_REPORTING_ON = '\x1b[?1004h';
+export const FOCUS_REPORTING_OFF = '\x1b[?1004l';
+export const FOCUS_IN = '\x1b[I';
+export const FOCUS_OUT = '\x1b[O';

package/dist/clients/attach/session/frames.d.ts

@@ -0,0 +1,43 @@
+import type { AgentSessionEvent } from '@earendil-works/pi-coding-agent';
+import type { BrokerToClient, RpcExtensionUIRequest } from '../../../core/runtime/broker-protocol.js';
+import { type PreviewableCommand } from '../slash/prompt-preview.js';
+import type { AttachSession } from './context.js';
+export interface FrameEffects {
+    /** Fold the frame through the shared reducer and repaint whatever slice of
+     *  chrome changed. Runs FIRST for every frame, before any case below. */
+    foldState: (frame: BrokerToClient) => void;
+    /** The transcript. Only the writes this switch performs are listed, so a
+     *  reader can see the whole render coupling from the type. */
+    chat: {
+        applySnapshot: (snapshot: Extract<BrokerToClient, {
+            type: 'welcome';
+        }>['snapshot']) => Promise<void> | void;
+        handleEvent: (event: AgentSessionEvent) => void;
+        bashStart: (command: string, excludeFromContext?: boolean) => void;
+        bashOutput: (chunk: string) => void;
+        bashEnd: (frame: Extract<BrokerToClient, {
+            type: 'bash_end';
+        }>) => void;
+    };
+    setNotice: (message: string) => void;
+    /** Repaint the status line — for the frames whose footer effect is NOT
+     *  derivable from session state (the on-disk bash-job scan). */
+    renderFooter: () => void;
+    /** Put the editor's text back (tree navigation restores it for re-editing). */
+    setEditorText: (text: string) => void;
+    /** Show/dismiss a blocking extension dialog. */
+    attachDialog: (req: RpcExtensionUIRequest) => void;
+    dismissDialog: (id: string) => void;
+    /** Replace the command inventory (`undefined` clears it pending a fresh ack). */
+    setCommands: (next?: ReadonlyArray<PreviewableCommand>) => void;
+    /** Clear + refetch the memory-ref inventory, superseding anything in flight. */
+    resetMemoryRefs: () => void;
+    /** Re-read the node's persona/lifecycle from the canvas. */
+    refreshNodeIdentity: () => void;
+    /** Re-resolve user keybindings after a `/reload` (and re-install the tmux side). */
+    reloadBindings: () => void;
+    /** "sonnet medium" — the label a model or thinking change announces. */
+    modelThinkingLabel: () => string | undefined;
+}
+/** Build the single `frame` handler the socket is wired to. */
+export declare function createFrameHandler(ctx: Pick<AttachSession, 'socket'>, fx: FrameEffects): (frame: BrokerToClient) => void;

package/dist/clients/attach/session/frames.js

@@ -0,0 +1,170 @@
+// session/frames.ts — what this terminal DOES about each broker frame.
+//
+// Every fact a frame carries is folded by the shared pure reducer
+// (`core/session-model`), which the web SPA folds too — that shared fold is
+// what keeps the two viewers from drifting, and it happens in `foldState`
+// before anything here runs. What is left, and all this file owns, is the
+// LOCAL effects: transcript writes, notices, editor text, and the correlated
+// refetches a fresh broker forces.
+//
+// The rule for adding a case: if the frame changes something a reader could
+// see in the reducer's state, it belongs in the reducer, not here.
+import { writeClipboardText } from '../../../core/clipboard-text.js';
+import { parsePreviewableCommands } from '../slash/prompt-preview.js';
+import { mark } from '../../../core/timing.js';
+/** Build the single `frame` handler the socket is wired to. */
+export function createFrameHandler(ctx, fx) {
+    const { socket } = ctx;
+    /** The two refetches a FRESH broker forces. A broker that just came up
+     *  (post-crash-revive, post-refresh, or a redial after sleep/Wi-Fi loss) has
+     *  no memory of this viewer's inventories, and `/reload` can replace both
+     *  corpora under a live one — same recovery either way. The epoch bump inside
+     *  `resetMemoryRefs` supersedes any request still in flight from a PRIOR
+     *  connection, so a late reply can never overwrite the fresh inventory. */
+    const refetchInventories = () => {
+        socket.send({ type: 'get_commands' });
+        fx.resetMemoryRefs();
+    };
+    const handleAck = (frame) => {
+        // get_commands replies with the broker's merged command list as JSON in
+        // `detail` — rebuild the autocomplete provider with it (slashCommandList
+        // re-appends the native canvas commands, deduped).
+        if (frame.for === 'get_commands' && frame.ok && frame.detail) {
+            try {
+                fx.setCommands(parsePreviewableCommands(frame.detail));
+            }
+            catch {
+                /* malformed — keep the current provider */
+            }
+            return;
+        }
+        // navigate_tree's detail is the navigated-to user message's text (pi
+        // parity: the tree navigator restores it to the editor for re-editing);
+        // the rewound transcript itself arrives via the broker's re-welcome.
+        if (frame.for === 'navigate_tree' && frame.ok) {
+            if (frame.detail)
+                fx.setEditorText(frame.detail);
+            return;
+        }
+        if (frame.for === 'share') {
+            if (frame.ok && frame.detail) {
+                fx.setNotice(`Shared: ${frame.detail}`);
+                writeClipboardText(frame.detail);
+            }
+            else if (!frame.ok) {
+                fx.setNotice(`share failed: ${frame.detail ?? 'unknown error'}`);
+            }
+            return;
+        }
+        if (frame.for === 'clone' && !frame.ok) {
+            fx.setNotice(`clone failed: ${frame.detail ?? 'unknown error'}`);
+            return;
+        }
+        if (!frame.ok) {
+            fx.setNotice(`command failed: ${frame.for}${frame.detail ? ` — ${frame.detail}` : ''}`);
+            return;
+        }
+        // Confirm commands whose effect is otherwise invisible — without this a
+        // `/reload` looks like it did nothing (the engine reloads silently).
+        if (frame.for === 'reload') {
+            fx.reloadBindings();
+            // `session.reload()` can replace extension command metadata AND the
+            // resolvable memory-ref corpus (a memory doc added/edited/removed). Drop
+            // the old inventory and its disclosure immediately, so a partially-typed
+            // ref or command never keeps completing against a stale one; only a fresh
+            // ack may repopulate it.
+            fx.setCommands();
+            refetchInventories();
+            fx.setNotice('Reloaded keybindings, extensions, skills, prompts, and themes');
+        }
+    };
+    /** A relayed AgentSessionEvent — everything not in the switch below. */
+    const handleSessionEvent = (event) => {
+        fx.chat.handleEvent(event);
+        if (event.type === 'thinking_level_changed') {
+            fx.setNotice(fx.modelThinkingLabel() ?? `Thinking level: ${event.level}`);
+        }
+        else if (event.type === 'tool_execution_start' || event.type === 'tool_execution_end') {
+            // R4: a bash tool call starting or ending changes what the on-disk job
+            // scan (oldestRunningBashJobStartedAtMs, read inside the status line)
+            // would return, so repaint immediately rather than waiting for the next
+            // 5s chrome poll — no session state to track, just the repaint.
+            fx.renderFooter();
+        }
+    };
+    let markedWelcome = false;
+    return (frame) => {
+        fx.foldState(frame);
+        switch (frame.type) {
+            case 'welcome': {
+                // The end of the front-door clock under CRTR_TIMING: the first frame
+                // carrying engine state, i.e. the moment the pane stops being empty
+                // chrome. Only the first one is marked — reconnects re-welcome.
+                if (!markedWelcome) {
+                    markedWelcome = true;
+                    mark('viewer.welcome');
+                }
+                // Every fact this welcome carries — role, agentDir, pi's state, the
+                // context seed, the retained display levels, and the queue reset a fresh
+                // broker needs (it has no memory of this viewer's queue panel, and an
+                // empty queue emits no `queue_update` to overwrite it) — was already
+                // folded by `foldState`. What remains here is local: the transcript, and
+                // the refetches this viewer owns.
+                //
+                // applySnapshot yields to the event loop between chunks for a large
+                // non-streaming catch-up (so stdin drains during construction); it runs
+                // synchronously for a streaming snapshot. Fire without await — nothing
+                // below reads the constructed view, and applySnapshot requests its own
+                // final render. ChatView is a single ordered writer: live frames that
+                // arrive mid-build defer and replay in wire order once it finishes, and
+                // a second welcome supersedes an older build outright — so this void
+                // call cannot interleave transcripts.
+                void fx.chat.applySnapshot(frame.snapshot);
+                // A fresh broker may reflect a new node persona or lifecycle.
+                fx.refreshNodeIdentity();
+                refetchInventories();
+                if (frame.pending_dialog != null)
+                    fx.attachDialog(frame.pending_dialog);
+                break;
+            }
+            case 'model_changed': {
+                // The broker's own post-set_model/cycle_model announcement (pi emits no
+                // engine event for a model switch) already moved the footer's model
+                // through the reducer. Announce the resulting model + thinking level.
+                const modelLabel = fx.modelThinkingLabel();
+                if (modelLabel)
+                    fx.setNotice(modelLabel);
+                break;
+            }
+            case 'error':
+                fx.setNotice(frame.code === 'read_only' ? 'read-only' : `error: ${frame.message}`);
+                break;
+            case 'ack':
+                handleAck(frame);
+                break;
+            case 'extension_ui_request':
+                // pi's uniform envelope: the three display METHODS are session state the
+                // reducer already folded and `foldState` already painted. Everything
+                // else — notify and the blocking four — is a live TUI overlay we own.
+                if (frame.method !== 'setStatus' && frame.method !== 'setWidget' && frame.method !== 'setTitle') {
+                    fx.attachDialog(frame);
+                }
+                break;
+            case 'extension_ui_dismiss':
+                fx.dismissDialog(frame.id);
+                break;
+            case 'bash_start':
+                fx.chat.bashStart(frame.command, frame.excludeFromContext);
+                break;
+            case 'bash_output':
+                fx.chat.bashOutput(frame.chunk);
+                break;
+            case 'bash_end':
+                fx.chat.bashEnd(frame);
+                break;
+            default:
+                handleSessionEvent(frame);
+                break;
+        }
+    };
+}

package/dist/clients/attach/session/identity.d.ts

@@ -0,0 +1,16 @@
+import type { NodeMeta } from '../../../core/canvas/types.js';
+import type { AttachSession } from './context.js';
+export type NodeIdentity = Pick<NodeMeta, 'kind' | 'mode' | 'lifecycle'> | undefined;
+export interface IdentityHooks {
+    /** Drop a late refresh that lands after the viewer is gone. */
+    isTornDown: () => boolean;
+    /** Repaint the badge/chip the identity feeds. */
+    onChanged: () => void;
+}
+export interface NodeIdentityOwner {
+    current: () => NodeIdentity;
+    /** Re-read from the canvas source. Fire-and-forget; failures are ignored
+     *  (the badge simply keeps its last known value). */
+    refresh: () => void;
+}
+export declare function createNodeIdentity(ctx: Pick<AttachSession, 'nodeId' | 'canvasSource'>, initial: NodeIdentity, hooks: IdentityHooks): NodeIdentityOwner;

package/dist/clients/attach/session/identity.js

@@ -0,0 +1,25 @@
+// session/identity.ts — the OWNER of the attached node's canvas identity
+// (kind/mode/lifecycle), which the editor's context badge and lifecycle chip
+// render from.
+//
+// It is the one connection fact that is NOT fixed at connect time: a remote
+// attach starts without an identity and fills it in from the relayed canvas,
+// and a fresh broker can report a new persona or lifecycle. Hence an owner with
+// a refresh verb rather than a value on `AttachSession`.
+export function createNodeIdentity(ctx, initial, hooks) {
+    let identity = initial;
+    return {
+        current: () => identity,
+        refresh: () => {
+            void ctx.canvasSource
+                .getNode(ctx.nodeId)
+                .then((node) => {
+                if (hooks.isTornDown() || node === null)
+                    return;
+                identity = node;
+                hooks.onChanged();
+            })
+                .catch(() => undefined);
+        },
+    };
+}