@north-light/crouter 0.3.154

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

@@ -0,0 +1,29 @@
+// session/banner.ts — the crouton banner's session facts.
+//
+// Every field is best-effort: a missing one just drops its line from the
+// banner, so a viewer never fails to open over cosmetic metadata.
+import { homedir } from 'node:os';
+import { loadProfileManifest } from '../../../core/profiles/manifest.js';
+import { currentVersion } from '../../../core/self-update.js';
+export function buildBannerInfo(meta) {
+    let version;
+    try {
+        version = currentVersion();
+    }
+    catch { /* skip version line */ }
+    let profile;
+    try {
+        if (meta.profile_id)
+            profile = loadProfileManifest(meta.profile_id).manifest.name;
+    }
+    catch { /* skip profile line */ }
+    let cwd = meta.cwd;
+    if (cwd) {
+        const home = homedir();
+        if (cwd === home)
+            cwd = '~';
+        else if (cwd.startsWith(home + '/'))
+            cwd = '~' + cwd.slice(home.length);
+    }
+    return { version, profile, cwd };
+}

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

@@ -0,0 +1,12 @@
+import { type BindingId, type BindingResolution } from '../../../core/keybindings/index.js';
+export type AttachBindingId = Extract<BindingId, `crtr.attach.${string}` | 'crtr.mode.cycle'>;
+export type AttachBindings = BindingResolution<BindingId>;
+export { inboxOpenHint } from '../../../core/keybindings/index.js';
+export declare function matchesAttachBinding(bindings: AttachBindings, id: AttachBindingId, data: string): boolean;
+export declare function dispatchAttachBinding(bindings: AttachBindings, data: string, actions: Record<AttachBindingId, () => void>): boolean;
+export declare function detachHint(bindings: AttachBindings): string | undefined;
+/** Re-resolve the user's binding catalog and republish it to every consumer:
+ *  the graph overlay's own snapshot and (in tmux) the crouter-owned tmux
+ *  bindings. Binding diagnostics must never fail an attach, so an install error
+ *  is swallowed. */
+export declare function refreshAttachBindingSnapshot(resolve: () => AttachBindings, setGraphBindings: (bindings: AttachBindings) => void, inTmuxNow: () => boolean, install: (bindings: AttachBindings) => void): AttachBindings;

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

@@ -0,0 +1,52 @@
+// session/bindings.ts — the viewer's key-gesture layer: which crouter bindings
+// the attach surface itself consumes, and how a live snapshot is refreshed.
+//
+// Every attach-owned gesture is resolved from the SAME user binding catalog the
+// tmux installer binds from (`core/keybindings`), never from ad-hoc key
+// literals, so a user's rebind is honored by the viewer and tmux alike.
+import { matchesKey } from '@earendil-works/pi-tui';
+import { formatBinding, matchesPiTuiInput, } from '../../../core/keybindings/index.js';
+export { inboxOpenHint } from '../../../core/keybindings/index.js';
+export function matchesAttachBinding(bindings, id, data) {
+    return matchesPiTuiInput(bindings, id, data, (input, gesture) => matchesKey(input, gesture));
+}
+export function dispatchAttachBinding(bindings, data, actions) {
+    for (const id of [
+        'crtr.attach.detach',
+        'crtr.attach.clear-or-detach',
+        'crtr.mode.cycle',
+        'crtr.attach.graph.toggle',
+        'crtr.attach.model-ladder.next',
+        'crtr.attach.model-ladder.previous',
+        'crtr.attach.command.inspect',
+        'crtr.attach.file-review',
+    ]) {
+        if (matchesAttachBinding(bindings, id, data)) {
+            actions[id]();
+            return true;
+        }
+    }
+    return false;
+}
+export function detachHint(bindings) {
+    for (const id of ['crtr.attach.clear-or-detach', 'crtr.attach.detach']) {
+        if (bindings.gestures(id).length > 0)
+            return formatBinding(bindings, id);
+    }
+    return undefined;
+}
+/** Re-resolve the user's binding catalog and republish it to every consumer:
+ *  the graph overlay's own snapshot and (in tmux) the crouter-owned tmux
+ *  bindings. Binding diagnostics must never fail an attach, so an install error
+ *  is swallowed. */
+export function refreshAttachBindingSnapshot(resolve, setGraphBindings, inTmuxNow, install) {
+    const bindings = resolve();
+    setGraphBindings(bindings);
+    if (inTmuxNow()) {
+        try {
+            install(bindings);
+        }
+        catch { /* attaching must not fail on binding diagnostics */ }
+    }
+    return bindings;
+}

package/dist/clients/attach/session/chrome-refresh.d.ts

@@ -0,0 +1,34 @@
+import type { AttachSession } from './context.js';
+export interface ChromeRefreshHooks {
+    /** True once teardown has begun — stops both the loop and a re-arm. */
+    isTornDown: () => boolean;
+    /** The viewer's transient notice slot — the ONLY failure channel here. */
+    setNotice: (msg: string) => void;
+    /** Repaint the relationship roster (chrome/roster.ts refresh). */
+    refreshRoster: () => Promise<void>;
+    /** Repaint the graph overlay if open. */
+    refreshGraph: () => void;
+    renderFooter: () => void;
+    renderExtensionWidgets: () => void;
+    /** Re-poll this pane's own git context (owned by the editor chrome). */
+    pollGit: () => void;
+}
+export interface ChromeRefresh {
+    /** Refresh all canvas chrome (panels + overlay if open). Coalescing: an
+     *  overlapping request collapses into one queued re-run instead of stacking. */
+    refresh: () => void;
+    /** The live ask-count map, keyed by node id. */
+    asks: () => Record<string, number>;
+    /** Report an async chrome failure through the notice slot — NEVER stderr:
+     *  this process owns an alternate-screen TUI, and a stray stderr write paints
+     *  raw bytes through the current frame and corrupts it. The last good chrome
+     *  snapshot is simply kept; the trimmed cause rides along so a persistent
+     *  failure (e.g. a stale viewer generation talking to a newer crtrd) is
+     *  diagnosable from the pane. */
+    reportFailure: (label: string, cause?: unknown) => void;
+    /** Run the initial poll and arm the interval. Call once, after `tui.start()`. */
+    start: () => void;
+    /** Clear the interval. Called from teardown's `stopLocal`. */
+    stop: () => void;
+}
+export declare function createChromeRefresh(ctx: Pick<AttachSession, 'nodeId' | 'canvasSource'>, hooks: ChromeRefreshHooks): ChromeRefresh;

package/dist/clients/attach/session/chrome-refresh.js

@@ -0,0 +1,93 @@
+// session/chrome-refresh.ts — the canvas-chrome refresh/poll engine: the
+// ask-count map (this module is its ONE writer; everything else reads it
+// through `asks()`), the coalescing refresh loop, and the low-rate 5s poll
+// that catches canvas changes which emit no broker event.
+/** Low-rate canvas-chrome poll cadence. */
+const ASKS_POLL_MS = 5_000;
+export function createChromeRefresh(ctx, hooks) {
+    const { nodeId, canvasSource } = ctx;
+    let asksMap = {};
+    let asksTimer;
+    const reportFailure = (label, cause) => {
+        const detail = (cause instanceof Error ? cause.message : cause === undefined ? '' : String(cause))
+            .replace(/\s+/g, ' ')
+            .trim()
+            .slice(0, 120);
+        hooks.setNotice(detail === '' ? `${label} delayed` : `${label} delayed — ${detail}`);
+    };
+    // Refresh all canvas chrome (panels + overlay if open) from the active canvas source.
+    let chromeRefreshInFlight = false;
+    let chromeRefreshQueued = false;
+    const refresh = () => {
+        chromeRefreshQueued = true;
+        if (chromeRefreshInFlight)
+            return;
+        chromeRefreshInFlight = true;
+        void (async () => {
+            try {
+                while (chromeRefreshQueued && !hooks.isTornDown()) {
+                    chromeRefreshQueued = false;
+                    try {
+                        await hooks.refreshRoster();
+                    }
+                    catch (err) {
+                        reportFailure('canvas panel refresh', err);
+                    }
+                    hooks.refreshGraph();
+                }
+            }
+            finally {
+                chromeRefreshInFlight = false;
+                if (chromeRefreshQueued && !hooks.isTornDown())
+                    refresh();
+            }
+        })().catch((err) => reportFailure('canvas chrome refresh', err));
+    };
+    const climbRootFromSource = async (self) => {
+        let cur = self;
+        const seen = new Set([cur]);
+        for (;;) {
+            const mgr = (await canvasSource.subscribersOf(cur).catch(() => []))[0]?.node_id;
+            if (mgr === undefined || seen.has(mgr))
+                break;
+            seen.add(mgr);
+            cur = mgr;
+        }
+        return cur;
+    };
+    // Low-rate canvas-chrome refresh: repaint panels/overlay from the active canvas
+    // source (child status flips emit no broker event) and re-poll the ask map asynchronously.
+    const pollChrome = () => {
+        refresh();
+        hooks.renderExtensionWidgets();
+        hooks.pollGit();
+        // R4: re-evaluate the bash-hint threshold on the existing 5s cadence, so a
+        // long-running SILENT bash call (no tool-execution update in between) still
+        // surfaces the hint without a new per-call timer.
+        hooks.renderFooter();
+        void (async () => {
+            const root = await climbRootFromSource(nodeId);
+            const counts = await canvasSource.ticketCountsForView(root);
+            if (JSON.stringify(counts) !== JSON.stringify(asksMap)) {
+                asksMap = counts;
+                refresh();
+                hooks.renderFooter(); // the closed-inbox footer total tracks asksMap
+            }
+        })().catch((err) => reportFailure('canvas attention refresh', err));
+    };
+    return {
+        refresh,
+        asks: () => asksMap,
+        reportFailure,
+        start: () => {
+            pollChrome();
+            asksTimer = setInterval(pollChrome, ASKS_POLL_MS);
+            if (typeof asksTimer.unref === 'function')
+                asksTimer.unref();
+        },
+        stop: () => {
+            if (asksTimer !== undefined)
+                clearInterval(asksTimer);
+        },
+    };
+}

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

@@ -0,0 +1,44 @@
+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 { BrokerClient } from '../../../core/broker-client/index.js';
+/** The hello handshake's initial role. A REMOTE attach (`--canvas`) is a
+ *  strictly VIEW-ONLY surface — it must claim observer regardless of
+ *  `--observer`, never controller. Local attach claims controller unless
+ *  `--observer`. Pure so the "remote is always observer" contract is testable
+ *  without constructing a real hello/socket. */
+export declare function resolveHelloRole(remote: boolean, observer: boolean): ClientRole;
+/** 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 declare function preWaitForViewSocket(nodeId: string): Promise<void>;
+/** A connected viewer's transport facts, established before any UI exists. */
+export interface AttachConnection {
+    /** THE single remote/read-only fact for the whole session, derived ONCE here
+     *  from `--canvas`. Every local disk/SQLite read or write keyed on the node id
+     *  gates on this one flag; no collaborator re-derives "is this remote". */
+    readonly remote: boolean;
+    /** Canvas read authority: an API source locally, a relayed source remotely. */
+    readonly canvasSource: CanvasSource;
+    /** Viewer-LOCAL concerns only — `cwd` drives theming and this pane's own git
+     *  status, and is the CLI's own cwd under `--canvas`. */
+    readonly meta: Pick<NodeMeta, 'cwd' | 'profile_id'>;
+    /** The attached node's persona/lifecycle, when this canvas can tell us —
+     *  `undefined` for a remote attach until the viewer refetches it. */
+    readonly nodeIdentity: Pick<NodeMeta, 'kind' | 'mode' | 'lifecycle'> | undefined;
+    /** The one socket to the node's headless broker, already connected. */
+    readonly socket: BrokerClient;
+    /** Re-throw a connect-adjacent failure that landed AFTER `connect` resolved.
+     *  Call once, synchronously, just before permanent socket wiring takes over;
+     *  a no-op if nothing failed. See the never-removed error listener below. */
+    assertConnected(): void;
+}
+/** 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 declare function connectToNode(nodeId: string, canvasName?: string): Promise<AttachConnection>;

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

@@ -0,0 +1,178 @@
+// session/connection.ts — how a viewer gets onto a broker: resolving the
+// local-vs-relay 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 { viewSocketPath } from '../../../core/canvas/paths.js';
+import { BrokerClient, BrokerUnavailableError, RelayTransport } from '../../../core/broker-client/index.js';
+import { resolveRemoteCanvasTarget } from '../../../core/view/remote-canvas-target.js';
+import { ApiCanvasSource, cliCanvasSource, cliClient, rethrowAsCliError } from '../../../commands/api-client.js';
+import { InputError } from '../../../core/io.js';
+/** The hello handshake's initial role. A REMOTE attach (`--canvas`) is a
+ *  strictly VIEW-ONLY surface — it must claim observer regardless of
+ *  `--observer`, never controller. Local attach claims controller unless
+ *  `--observer`. Pure so the "remote is always observer" contract is testable
+ *  without constructing a real hello/socket. */
+export function resolveHelloRole(remote, observer) {
+    return remote || 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) {
+    const remote = canvasName !== undefined;
+    // 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 = remote ? 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 mode-switch
+    // file and the `getRow`-based reconnect give-up are the other local-canvas
+    // dependencies `--canvas` must skip; both gate on `remote` at their own use
+    // sites, not here.
+    let meta;
+    let nodeIdentity;
+    let transport;
+    if (remote) {
+        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 byte relay stays a direct local view.sock hop, so we only TRIGGER the
+        // revive here and let BrokerClient(nodeId) connect over the local socket as
+        // before — this LOCAL process never launches pi or writes the session.
+        try {
+            await cliClient().ensureAttach(nodeId, { resume: true, revive: true });
+        }
+        catch (err) {
+            rethrowAsCliError(err, 'The node may be finalized or otherwise not attachable.');
+        }
+        // Local only: a relay accepts the WS upgrade unconditionally, so there is
+        // no socket file to pre-wait on for `--canvas`.
+        await preWaitForViewSocket(nodeId);
+    }
+    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 relay ACCEPTS the WS upgrade unconditionally and only proves
+    // "no such node/broker" asynchronously — by closing 1011 AFTER the upgrade
+    // completes (`RelayTransport`'s `onClose`, mirroring `server.ts`'s
+    // `bridgeConnection`). That close therefore always lands strictly AFTER the
+    // transport's `connect` event, never before it, so it can never be caught by
+    // a connect-race listener torn down the moment `connect` resolves. Install a
+    // listener that is NEVER removed instead, before dialing at all, so nothing
+    // landing during the caller's synchronous TUI/editor setup has nowhere to go.
+    // `assertConnected` is the caller's one synchronous checkpoint on it, taken
+    // immediately before permanent socket wiring; anything after that is
+    // legitimately mid-session and belongs to the reconnect supervisor, exactly
+    // as it already does 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.
+    await new Promise((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,
+        assertConnected: () => {
+            if (terminalStartupError !== undefined)
+                throw toAttachError(terminalStartupError);
+        },
+    };
+}

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

@@ -0,0 +1,54 @@
+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 bottom-anchored chrome stack plus the scrolling chat, in render order.
+ *  Owned by the layout step; every painter writes into exactly one of these. */
+export interface AttachContainers {
+    /** Scrolling transcript — the only container above the chat/chrome divider. */
+    readonly chat: Container;
+    /** The themed divider itself (suppressed while the recap widget is present). */
+    readonly chrome: Container;
+    /** Extension widgets placed `aboveEditor`, including the inactivity brief. */
+    readonly aboveWidgets: 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;
+    /** 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/read-only fact, 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(remote, 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'>;
+    /** 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.
+//
+// `runAttach` used to hold every one of these as a closure local, which is why
+// pulling any block out of it meant 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/editor-frame.d.ts

@@ -0,0 +1,43 @@
+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'> | 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;
+}
+/** 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;