@north-light/api 0.3.580 → 0.3.588

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

@@ -0,0 +1,204 @@
+// session/connection.ts — how a viewer gets onto a broker: resolving the
+// local or remote attach target, dialing it, the role it claims in the hello
+// handshake, and the optional pre-wait for a socket still being bound.
+//
+// Everything here runs BEFORE the TUI takes over the terminal, which is the
+// point: a missing broker must exit non-zero with a plain CLI error, not paint
+// an alternate screen first. Nothing here launches anything — attach holds ONLY
+// a socket; the engine is started server-side by crtrd (`reviveNode`, the one
+// sanctioned launcher), never here.
+import { createConnection } from 'node:net';
+import { apiSocketPath, viewSocketPath } from '../../../core/canvas/paths.js';
+import { BrokerClient, BrokerUnavailableError, RelayTransport } from '../../../core/broker-client/index.js';
+import { resolveRemoteCanvasTarget } from '../../../core/remote-canvas-target.js';
+import { ApiCanvasSource, cliCanvasSource, cliClient, rethrowAsCliError } from '../../../commands/api-client.js';
+import { InputError } from '../../../core/io.js';
+import { readMachineConfig } from '../../../daemon/machine-link/config.js';
+import { personBearer } from '../../../core/directory/person-credential.js';
+/** The person bearer is cached until 30 s before it ends; a viewer redials with whatever the target holds at that moment, so a shorter timer keeps it fresh. */
+const BEARER_REFRESH_MS = 15_000;
+/** A relay target for an imported Mac: the cloud control plane, with the signed-in person's bearer. `relayToken` is read at each dial. */
+export async function machineRelayTarget(apiUrl, directoryUrl) {
+    let bearer = await personBearer(directoryUrl);
+    const timer = setInterval(() => { personBearer(directoryUrl).then((fresh) => { bearer = fresh; }, () => { }); }, BEARER_REFRESH_MS);
+    timer.unref();
+    return { previewEndpoint: apiUrl, get relayToken() { return bearer; } };
+}
+/** The hello handshake's initial role: controller unless `--observer`. A remote
+ *  attach (`--canvas`) claims it too; crtrd admits a controller only for a
+ *  caller with `message` permission on the node (`read` admits an observer) and
+ *  closes the socket before any frame reaches the broker otherwise. */
+export function resolveHelloRole(observer) {
+    return observer ? 'observer' : 'controller';
+}
+/** bootRoot spawns the viewer BEFORE its freshly-launched broker has bound
+ *  view.sock, so the viewer's own CLI boot (~0.4s of module load) overlaps the
+ *  broker's ~1s startup instead of serializing after it. When that spawner set
+ *  CRTR_ATTACH_WAIT_MS, poll the socket with throwaway probe connects until it
+ *  accepts or the deadline passes — then fall through and let the normal
+ *  one-shot connect race surface the usual BrokerUnavailableError. Without the
+ *  env var this is a no-op: a plain `crtr surface attach` keeps its fail-fast
+ *  "attach does NOT launch the engine" contract. */
+export async function preWaitForViewSocket(nodeId) {
+    const waitMs = Number(process.env['CRTR_ATTACH_WAIT_MS'] ?? '');
+    if (!Number.isFinite(waitMs) || waitMs <= 0)
+        return;
+    const sockPath = viewSocketPath(nodeId);
+    const deadline = Date.now() + waitMs;
+    while (Date.now() < deadline) {
+        const ok = await new Promise((resolveProbe) => {
+            const probe = createConnection(sockPath);
+            const settle = (v) => {
+                probe.destroy();
+                resolveProbe(v);
+            };
+            probe.once('connect', () => settle(true));
+            probe.once('error', () => settle(false));
+        });
+        if (ok)
+            return;
+        await new Promise((r) => setTimeout(r, 100));
+    }
+}
+/** Resolve the target, revive the node if it is dormant (server-side), and dial
+ *  the broker. Rejects with a plain `InputError` — no terminal has been taken
+ *  over at this point, so a failure here is an ordinary non-zero CLI exit. */
+export async function connectToNode(nodeId, canvasName, wakeParked = true) {
+    // An imported Mac has no local canvas API: its canvas and its brokers' viewer channels are reached through the cloud control plane,
+    // so attach without `--canvas` dials the cloud with the person's sign-in. It is still the person's own attach, not a `--canvas` view:
+    // `remote` stays false, so the viewer claims the controller role like any local attach.
+    const remote = canvasName !== undefined;
+    const machine = remote ? undefined : readMachineConfig();
+    // Attach must NOT silently honor a durable `crtr canvas use` selection: the
+    // local branch has a hard local-unix-socket assumption baked into its
+    // not-found and reconnect-give-up handling, so an implicit remote redirect
+    // (from a `canvas use cloud` some other command left active) would be
+    // surprising for a command whose whole meaning is "attach to a node on THIS
+    // canvas". Go remote ONLY when `--canvas` was passed on THIS invocation —
+    // never fall through to resolveCanvasSource's activeCanvas precedence, which
+    // is right for `node inspect`/`canvas browse` but not here.
+    const canvasSource = canvasName !== undefined ? cliCanvasSource({ canvasName }) : new ApiCanvasSource();
+    // A remote node id never exists in THIS machine's canvas.db, so the local
+    // not-found guard is wrong for `--canvas`. Build a minimal local `meta`
+    // stand-in instead: `meta.cwd` is a legitimately viewer-local concern
+    // (theming, this pane's own git status) — not a remote-node concern — so
+    // pointing it at the CLI's own cwd is correct, not a hack. The `getRow`-based
+    // reconnect give-up is the other local-canvas dependency `--canvas` must skip;
+    // it gates on `remote` at its own use site, not here.
+    let meta;
+    let nodeIdentity;
+    let transport;
+    let initialSnapshot;
+    let initialCommands;
+    if (canvasName !== undefined) {
+        meta = { cwd: process.cwd() };
+        transport = new RelayTransport(nodeId, resolveRemoteCanvasTarget(canvasName));
+    }
+    else {
+        const localMeta = await canvasSource.getNode(nodeId);
+        if (localMeta === null) {
+            throw new InputError({
+                error: 'not_found',
+                message: `no node: ${nodeId}`,
+                received: nodeId,
+                next: 'List nodes with `crtr node inspect list`.',
+            });
+        }
+        meta = localMeta;
+        nodeIdentity = localMeta;
+        // Attach revives a dormant node (B2 acceptance): the server-side
+        // ensureAttach runs reviveNode (the ONE sanctioned launcher) and waits for
+        // the broker's view socket, returning socket_path === viewSocketPath(nodeId).
+        // The viewer connects through crtrd's Unix-socket WebSocket bridge after
+        // this ensure. The daemon, not the broker, owns attending viewer presence.
+        try {
+            const attach = await cliClient().ensureAttach(nodeId, { resume: true, revive: true, wakeParked });
+            if (attach.parked) {
+                const saved = await cliClient().getSnapshot(nodeId);
+                // The API DTO stays dependency-light and structural; this viewer is the
+                // consumer that knows the complete broker snapshot contract.
+                initialSnapshot = saved.snapshot;
+                initialCommands = saved.commands;
+            }
+        }
+        catch (err) {
+            rethrowAsCliError(err, 'The node may be finalized or otherwise not attachable.');
+        }
+        // Local only: remote attach reaches crtrd over WebSocket rather than a
+        // local socket file, so `--canvas` has nothing to pre-wait on. An offline
+        // parked focus has deliberately no socket to wait for.
+        if (machine !== undefined)
+            transport = new RelayTransport(nodeId, await machineRelayTarget(machine.apiUrl, machine.directoryUrl));
+        else {
+            if (initialSnapshot === undefined)
+                await preWaitForViewSocket(nodeId);
+            transport = new RelayTransport(nodeId, { socketPath: apiSocketPath() });
+        }
+    }
+    const socket = new BrokerClient(nodeId, { transport });
+    /** One error shape for a connect-time failure, whether the connect race below
+     *  caught it or the deferred `assertConnected` checkpoint did. */
+    const toAttachError = (err) => {
+        if (err instanceof BrokerUnavailableError) {
+            return new InputError({
+                error: 'no_broker',
+                message: err.message,
+                received: nodeId,
+                next: 'Focus or revive the node first — attach needs a running headless broker.',
+            });
+        }
+        return new InputError({
+            error: 'socket_error',
+            message: `could not attach to node ${nodeId}: ${String(err?.message ?? err)}`,
+            received: nodeId,
+            next: 'Check the node has a running headless broker.',
+        });
+    };
+    // A remote crtrd attach connection can close after its WebSocket upgrade when
+    // its broker socket drops. Install a listener before dialing and keep it
+    // through synchronous TUI/editor setup, so `assertConnected` can surface any
+    // terminal startup failure at its one checkpoint immediately before permanent
+    // socket wiring. Failures after that are mid-session and belong to the
+    // reconnect supervisor, as they do for a local socket.
+    let terminalStartupError;
+    socket.on('error', (err) => {
+        if (terminalStartupError === undefined)
+            terminalStartupError = err;
+    });
+    // Connect FIRST (race connect/error) so a missing broker exits non-zero
+    // cleanly, BEFORE the TUI takes over the terminal. Offline parked focus is
+    // the one intentional exception: reconnect owns its first dial after paint.
+    if (initialSnapshot === undefined) {
+        await new Promise(async (resolve, reject) => {
+            const onConnect = () => {
+                cleanup();
+                resolve();
+            };
+            const onErr = (err) => {
+                cleanup();
+                reject(err);
+            };
+            const cleanup = () => {
+                socket.off('connect', onConnect);
+                socket.off('error', onErr);
+            };
+            socket.on('connect', onConnect);
+            socket.on('error', onErr);
+            socket.connect();
+        }).catch((err) => {
+            throw toAttachError(err);
+        });
+    }
+    return {
+        remote,
+        canvasSource,
+        meta,
+        nodeIdentity,
+        socket,
+        ...(initialSnapshot === undefined ? {} : { initialSnapshot, initialCommands }),
+        assertConnected: () => {
+            if (initialSnapshot === undefined && terminalStartupError !== undefined)
+                throw toAttachError(terminalStartupError);
+        },
+    };
+}

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

@@ -0,0 +1,59 @@
+import type { Container, TUI } from '@earendil-works/pi-tui';
+import type { ClientRole } from '../../../core/runtime/broker-protocol.js';
+import type { CanvasSource } from '../../../core/canvas/source.js';
+import type { NodeMeta } from '../../../core/canvas/types.js';
+import type { BrokerClient } from '../../../core/broker-client/index.js';
+import type { AttachPalette } from '../config.js';
+import type { TitledEditor } from '../input/titled-editor.js';
+/** The pinned cockpit plus transcript/header regions, in frame render order.
+ *  Owned by the layout step; every painter writes into exactly one of these. */
+export interface AttachContainers {
+    /** Scrolling transcript source, rendered by the virtualized viewport. */
+    readonly chat: Container;
+    /** Pinned recap above the transcript; empty when no recap widget exists. */
+    readonly header: Container;
+    /** Extension widgets placed `aboveEditor`, including the inactivity brief. */
+    readonly aboveWidgets: Container;
+    /** Live activity loader, fixed at the top of the bottom region. */
+    readonly activity: Container;
+    /** Relationship roster / wait rows, below the editor. */
+    readonly reports: Container;
+    /** Pending steering messages, above the editor. */
+    readonly queued: Container;
+    /** Native pickers (/model etc.), inline directly under the editor. */
+    readonly pickerPanel: Container;
+    /** The inline ticket page (chrome/ticket-panel.ts), below the recap header
+     *  — the expanded form of the strip's notification row. */
+    readonly ticketPanel: Container;
+    /** Extension widgets placed `belowEditor`. */
+    readonly belowWidgets: Container;
+    /** The status line. */
+    readonly footer: Container;
+}
+export interface AttachSession {
+    /** The node this viewer drives. On a remote attach this id is meaningful only
+     *  to the remote canvas — never to local disk. */
+    readonly nodeId: string;
+    /** THE single remote fact (not a read-only fact: `role` decides driving), derived once in `runAttach` from
+     *  `--canvas` and threaded from here. No collaborator may re-derive it. */
+    readonly remote: boolean;
+    /** THE single capability fact, resolved once in `runAttach` by
+     *  `resolveHelloRole(observer)` and claimed in every hello (including
+     *  reconnects), so it can never be renegotiated mid-session. `'observer'`
+     *  makes this viewer read-only: no collaborator may emit a mutating frame or
+     *  drive the node out of band. */
+    readonly role: ClientRole;
+    /** Viewer-LOCAL concerns only: `cwd` drives theming and this pane's own git
+     *  status, and is the CLI's own cwd for a remote attach — never the remote
+     *  node's directory. */
+    readonly meta: Pick<NodeMeta, 'cwd' | 'profile_id' | 'grantee'>;
+    /** Canvas read authority for chrome and the graph overlay: an API source
+     *  locally, a relayed source under `--canvas`. */
+    readonly canvasSource: CanvasSource;
+    /** The one socket to the node's headless broker. Attach owns no engine. */
+    readonly socket: BrokerClient;
+    readonly tui: TUI;
+    readonly pal: AttachPalette;
+    readonly editor: TitledEditor;
+    readonly containers: AttachContainers;
+}

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

@@ -0,0 +1,16 @@
+// session/context.ts — the named home for an attach session's STABLE facts.
+//
+// Held as closure locals inside `runAttach`, pulling any block out of it would
+// mean inventing a bespoke parameter list for that block alone.
+// `AttachSession` gives the state one declaration; each
+// collaborator then names the slice it needs as a `Pick<AttachSession, …>`
+// view, so the module's dependencies are a *projection* of one truth rather
+// than a hand-maintained bag that can drift from it.
+//
+// SCOPE — this holds only what is built once and never reassigned: the
+// identity/transport facts, the TUI, the palette, the editor, and the layout
+// containers. Reassignable session state (the folded `SessionState`, the notice
+// string, bash mode, the ask counts) deliberately stays in `runAttach` and
+// reaches collaborators through explicit getters/callbacks on their own deps
+// argument, so nothing here can be silently mutated behind a reader's back.
+export {};

package/dist/clients/attach/session/document-links.d.ts

@@ -0,0 +1,12 @@
+import type { CanvasSource } from '../../../core/canvas/source.js';
+export declare function createDocumentLinks(opts: {
+    selfNodeId: string;
+    remote: boolean;
+    canvasSource: CanvasSource;
+    port: number;
+    fetchSecret: () => Promise<string>;
+    onSecretError: (err: unknown) => void;
+    refresh: () => void;
+}): {
+    dispose(): void;
+};

package/dist/clients/attach/session/document-links.js

@@ -0,0 +1,43 @@
+import { noteDocLinksChanged, setDocLinkContext } from '../render/doc-links.js';
+export function createDocumentLinks(opts) {
+    const names = new Map();
+    let rosterLoaded = false;
+    let disposed = false;
+    let secret;
+    if (!opts.remote)
+        void opts.fetchSecret().then((value) => {
+            secret = value;
+            noteDocLinksChanged();
+            if (!disposed)
+                opts.refresh();
+        }, opts.onSecretError);
+    const loadRoster = () => {
+        if (rosterLoaded)
+            return;
+        rosterLoaded = true;
+        // The lean roster carries every name; the full node list only for a source without one.
+        const source = opts.canvasSource;
+        const rows = source.panelRoster
+            ? source.panelRoster().then((roster) => roster.nodes)
+            : source.listNodes();
+        void rows.then((rows) => {
+            for (const row of rows)
+                names.set(row.node_id, row.name);
+            noteDocLinksChanged();
+            if (!disposed)
+                opts.refresh();
+        }, () => { rosterLoaded = false; });
+    };
+    const context = {
+        selfNodeId: opts.selfNodeId,
+        nodeName: (nodeId) => {
+            const name = names.get(nodeId);
+            if (name === undefined)
+                loadRoster();
+            return name;
+        },
+        urlFor: (ref) => opts.remote || secret === undefined ? undefined : `http://127.0.0.1:${opts.port}/r/${ref.split('/').map(encodeURIComponent).join('/')}?t=${secret}`,
+    };
+    setDocLinkContext(context);
+    return { dispose() { disposed = true; setDocLinkContext(undefined); } };
+}

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

@@ -0,0 +1,47 @@
+import type { NodeMeta } from '../../../core/canvas/types.js';
+import type { BrokerSnapshot } from '../../../core/runtime/broker-protocol.js';
+import type { AttachPalette } from '../config.js';
+import type { BashMode } from '../chrome/status-line.js';
+import type { AttachSession } from './context.js';
+/** Derive the shell-mode cue from the editor contents. Leading whitespace is
+ *  ignored so pasted commands and indented text still toggle correctly. */
+export declare function deriveBashMode(text: string): 0 | 1 | 2;
+/** Resolve the editor border + title-chip styles for the current shell cue. */
+export declare function resolveEditorFrameStyles(bashMode: 0 | 1 | 2, thinkingLevel: BrokerSnapshot['state']['thinkingLevel'] | undefined, pal: Pick<AttachPalette, 'bashMode' | 'bashModeAlt' | 'border'>): {
+    borderColor: (s: string) => string;
+    titleStyle: (s: string) => string;
+};
+export interface EditorChromeHooks {
+    /** The viewer's live node identity — a `let` runAttach owns and refreshes
+     *  (remote attach starts without one), so it MUST stay a getter. */
+    nodeIdentity: () => Pick<NodeMeta, 'kind' | 'mode' | 'lifecycle' | 'icon'> | undefined;
+    /** The engine's current thinking level, from live session state. */
+    thinkingLevel: () => BrokerSnapshot['state']['thinkingLevel'] | undefined;
+    /** Repaint the status line — the bash-level segment tracks `bashMode`. */
+    renderFooter: () => void;
+    /** Editor text changed — lets the command-preview inventory stay in sync. */
+    onTextChange: (text: string) => void;
+}
+export interface EditorChrome {
+    /** Current shell/bash level, for the status line's segment. */
+    bashMode: () => BashMode;
+    /** The `/color` override for the name chip — null restores the default. */
+    setChipColor: (color: string | null) => void;
+    /** Repaint the editor border + title chip from current bash/thinking state. */
+    paintFrame: () => void;
+    /** Normalize pi's session name into the title chip. */
+    setTitle: (sessionName: string | undefined) => void;
+    /** Repaint the bottom-right cwd + persona badge. */
+    syncContextBadge: () => void;
+    /** Kick an async git-status fetch that repaints the top border. */
+    pollGit: () => void;
+}
+/** Render the generated task icon on every non-empty editor title. Session
+ * names are persisted independently by pi, so this derives the icon from the
+ * canvas identity again whenever a viewer attaches or reloads. */
+export declare function displayEditorTitle(sessionName: string | undefined, identity: Pick<NodeMeta, 'kind' | 'mode' | 'icon'> | undefined): string;
+/** 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 declare function createEditorChrome(ctx: Pick<AttachSession, 'meta' | 'tui' | 'pal' | 'editor'>, hooks: EditorChromeHooks): EditorChrome;

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

@@ -0,0 +1,142 @@
+// 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),
+    };
+}
+/** Render the generated task icon on every non-empty editor title. Session
+ * names are persisted independently by pi, so this derives the icon from the
+ * canvas identity again whenever a viewer attaches or reloads. */
+export function displayEditorTitle(sessionName, identity) {
+    const raw = sessionName ?? '';
+    if (raw === '' || identity === undefined)
+        return raw;
+    const modePrefix = `${modeIcon(identity.mode)} `;
+    const withoutMode = raw.startsWith(modePrefix) ? raw.slice(modePrefix.length) : raw;
+    const icon = (identity.icon ?? '').trim();
+    const iconPrefix = icon === '' ? '' : `${icon} `;
+    const withoutTaskIcon = iconPrefix !== '' && withoutMode.startsWith(iconPrefix)
+        ? withoutMode.slice(iconPrefix.length)
+        : withoutMode;
+    const withoutKind = withoutTaskIcon.endsWith(` ${identity.kind}`)
+        ? withoutTaskIcon.slice(0, -identity.kind.length - 1)
+        : withoutTaskIcon;
+    const name = withoutKind === identity.kind ? '' : withoutKind;
+    return name === '' || icon === '' ? name : `${icon} ${name}`;
+}
+/** 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}`;
+    };
+    // 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 = displayEditorTitle(sessionName, hooks.nodeIdentity());
+        },
+        syncContextBadge: () => syncContextBadge(),
+        pollGit: () => fetchGitInfo(meta.cwd, renderGitInfo),
+    };
+}

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

@@ -0,0 +1,63 @@
+import { CombinedAutocompleteProvider } from '@earendil-works/pi-tui';
+import type { BrokerDataFrame, RefMeta } from '../../../core/runtime/broker-protocol.js';
+import type { FrecencyStore } from '../input/completion-frecency.js';
+import type { ViewerCapabilities } from '../input/capabilities.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;
+}> | undefined, capabilities: ViewerCapabilities, 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;
+    /** Per-user frecency store — biases command/ref completion order by usage. */
+    frecency: FrecencyStore;
+}
+/** 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.
+ *  Input wiring supplies the session capability before first render, seeding
+ *  builtins-only autocomplete before the broker's first `get_commands` ack. */
+export declare function createEditorInventory(ctx: Pick<AttachSession, 'meta' | 'socket' | 'tui' | 'editor'>, capabilities: ViewerCapabilities, hooks: EditorInventoryHooks): EditorInventory;