@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/core/runtime/tmux.js

@@ -9,6 +9,7 @@
 // their window; reviving opens a fresh one.
 import { spawnSync } from 'node:child_process';
 import { readConfig } from '../config.js';
+import { defaultCanvasNavConfig } from '../../types.js';
 import { surfaceTmuxStyleArgs } from './surface-bg.js';
 // ---------------------------------------------------------------------------
 // Shell quoting + tmux invocation
@@ -48,12 +49,32 @@ export function currentTmux() {
 export function sessionExists(name) {
     return tmux(['has-session', '-t', name]).ok;
 }
+/** Force bracketed-paste capabilities on for every terminal on this tmux server.
+ *
+ *  Many terminfo entries lack the Enbp/Dsbp (enable/disable bracketed paste)
+ *  capabilities. Without them tmux never asks the outer terminal to wrap pastes,
+ *  so a multi-line paste arrives as raw `\r` and the inner app (pi, zsh, …)
+ *  submits on the first newline — i.e. one paste lands as several messages.
+ *  Declaring the caps for `*` restores bracketed paste so pastes stay atomic.
+ *
+ *  `terminal-overrides` is a server option, so this is set once per server and
+ *  is idempotent: we only append our entry when the Enbp marker isn't already
+ *  present (e.g. the user's own tmux.conf already declares it). Must run only
+ *  once a server exists — set-option errors out with no server running — so
+ *  callers invoke it AFTER ensuring a session. */
+function ensureBracketedPaste() {
+    const current = tmux(['show-options', '-s', 'terminal-overrides']).stdout;
+    if (current.includes('Enbp='))
+        return;
+    tmux(['set-option', '-sga', 'terminal-overrides', '*:Enbp=\E[?2004h:Dsbp=\E[?2004l']);
+}
 /** Create a detached session rooted at `cwd` if it doesn't exist. The session
  *  name is a root's tmux home; every node under that root is a window in it. */
 export function ensureSession(name, cwd) {
-    if (sessionExists(name))
-        return;
-    tmux(['new-session', '-d', '-s', name, '-c', cwd]);
+    if (!sessionExists(name)) {
+        tmux(['new-session', '-d', '-s', name, '-c', cwd]);
+    }
+    ensureBracketedPaste();
 }
 function envFlags(env) {
     const out = [];
@@ -149,6 +170,31 @@ export function closeWindow(window) {
 export function renameWindow(window, name) {
     return tmux(['rename-window', '-t', window, name]).ok;
 }
+/** Break a single PANE out into a BRAND-NEW window of its own (`tmux break-pane
+ *  -d`). `-d` keeps the new window in the background (does not switch the client
+ *  to it); `-s <pane>` names the source pane — the §2.2 HARD DRIVER INVARIANT, so
+ *  the break never falls back to tmux's global current pane. The pane keeps its
+ *  durable `%id` across the move (only its window changes), so callers can keep
+ *  using the same pane handle. Returns the new `{window, pane}` location, or null
+ *  if tmux fails. Used by `canvas tmux-spread` to lift the caller's viewer into a
+ *  fresh window before tiling sibling viewers beside it. */
+export function breakPane(pane) {
+    const r = tmux([
+        'break-pane',
+        '-d',
+        '-P',
+        '-F',
+        '#{window_id}\t#{pane_id}',
+        '-s',
+        pane,
+    ]);
+    if (!r.ok)
+        return null;
+    const [window, p] = r.stdout.split('\t');
+    if (window === undefined || window === '' || p === undefined || p === '')
+        return null;
+    return { window, pane: p };
+}
 /** Close a single PANE. Its window closes automatically once this was the last
  *  pane, but sibling panes survive — so co-located nodes (several agents sharing
  *  one window via swap-pane focus) are torn down one at a time instead of all
@@ -201,7 +247,7 @@ export function paneExists(pane) {
 }
 /** Does this pane exist AND have its command still RUNNING (`#{pane_dead}` = 0)?
  *  Distinguishes a pane genuinely hosting a live process from a remain-on-exit
- *  corpse frozen after exit (`pane_dead` = 1). Node viewer panes run `crtr attach`
+ *  corpse frozen after exit (`pane_dead` = 1). Node viewer panes run `crtr surface attach`
  *  as the pane command, so pane-running ⟹ a live viewer occupies it. */
 export function paneRunning(pane) {
     const r = tmux(['display-message', '-p', '-t', pane, '#{pane_id}\t#{pane_dead}']);
@@ -226,6 +272,17 @@ export function paneCurrentPath(pane) {
     const r = tmux(['display-message', '-p', '-t', pane, '#{pane_current_path}']);
     return r.ok && r.stdout !== '' ? r.stdout : null;
 }
+/** Flash a transient status-line toast on the client showing `pane` (or the
+ *  current client when `pane` is omitted). `ms` sets the display duration. Used
+ *  by `crtr canvas issue new` to confirm a capture from inside its popup.
+ *  Best-effort; never throws. */
+export function displayMessage(message, pane, ms = 4000) {
+    const args = ['display-message', '-d', String(ms)];
+    if (pane !== undefined && pane !== '')
+        args.push('-t', pane);
+    args.push(message);
+    return tmux(args).ok;
+}
 /** Set a PANE-scoped tmux option (`tmux set-option -p -t <pane> <name> <value>`).
  *  Used to tag a pane with the view id it currently hosts (`@crtr_view`) so the
  *  view-nav cycle can read it back and switch to the next/prev view in place.
@@ -311,6 +368,21 @@ export function windowAlive(session, window) {
 export function selectWindow(session, window) {
     return tmux(['select-window', '-t', `${session}:${window}`]).ok;
 }
+/** Apply a named tmux layout to a window (`tmux select-layout -t <window>
+ *  <layout>`). `canvas tmux-spread` calls it with `tiled` to evenly grid every
+ *  viewer pane in the spread window (and between splits, to redistribute space so
+ *  the next split has room). Best-effort; false if tmux fails. */
+export function selectLayout(window, layout) {
+    return tmux(['select-layout', '-t', window, layout]).ok;
+}
+/** Make a pane the ACTIVE pane in its window (`tmux select-pane -t <pane>`). A
+ *  `split-window -d` keeps the CALLER active, so a freshly-opened viewer pane is
+ *  not focused until this runs — `focus` calls it so picking a node (e.g. from the
+ *  alt+g graph) lands the keyboard on the new viewer. Best-effort; false if tmux
+ *  fails. */
+export function selectPane(pane) {
+    return tmux(['select-pane', '-t', pane]).ok;
+}
 /** Switch the tmux client to a different session (cross-session focus). Runs
  *  `tmux switch-client -t <session>`. Best-effort; never throws. The caller is
  *  responsible for following up with selectWindow to land on the right window. */
@@ -329,91 +401,73 @@ export function sendKeysEnter(pane, text) {
 // ---------------------------------------------------------------------------
 // Prefix menu — Alt+C opens a which-key-style tmux display-menu of crouter
 // actions. Installed on the running server at root boot; idempotent (a re-bind
-// overwrites the previous one). Items shell out to `crtr`, passing the active
-// pane so an action targets the agent currently in front of you.
+// overwrites the previous one). Menu entries are data-driven: tmux renders the
+// action tree, and every `crtr` / `popup` action routes through `crtr canvas
+// chord` so node-relative vars resolve in one safe place.
 // ---------------------------------------------------------------------------
-/** Reserved mnemonic keys owned by the built-in menu items below — a custom
- *  `prefixBind` may not claim these (the built-in item wins). */
-const RESERVED_MENU_KEYS = new Set(['o', 'r', 'd', 'D', 'x']);
-/** Bind Alt+C to the crouter action menu. Best-effort; false if tmux fails.
- *  The built-in items (promote/resume/demote/detach/close) are static; the canvas-nav
- *  chords (default g→graph, m→manager + any custom prefixBind) are appended
- *  from `canvasNav.prefixBinds`, each routed through `crtr canvas chord` (or, for
- *  the `__graph__` sentinel, a `send-keys '/graph'`) so the menu stays static
- *  while behaviour is config-driven. */
+function escapeTmuxFormats(value) {
+    return value.replace(/#/g, '##');
+}
+function runShellCmd(shellCmd) {
+    return `run-shell ${shellQuote(shellCmd)}`;
+}
+function tmuxCmd(args) {
+    return args.map(shellQuote).join(' ');
+}
+function chordShellCmd(run) {
+    return runShellCmd(`crtr canvas chord --pane '#{pane_id}' --run ${shellQuote(escapeTmuxFormats(run))} >/dev/null 2>&1`);
+}
+function popupCmd(run) {
+    return `display-popup -E -w 60% -h 50% -d "#{pane_current_path}" ${shellQuote(`crtr canvas chord --pane '#{pane_id}' --run ${shellQuote(escapeTmuxFormats(run))} --interactive`)}`;
+}
+function keysCmd(keys) {
+    return `send-keys -t '#{pane_id}' ${shellQuote(escapeTmuxFormats(keys))} Enter`;
+}
+function buildMenuArgs(title, items) {
+    const safeTitle = escapeTmuxFormats(title);
+    const args = ['display-menu', '-T', `#[align=centre]${safeTitle}`, ...surfaceTmuxStyleArgs()];
+    const boxW = Math.max(safeTitle.length, ...items.map((i) => escapeTmuxFormats(i.desc).length)) + 6;
+    const nudgeX = 1;
+    const nudgeY = 3;
+    args.push('-x', `#{e|-:#{pane_right},${boxW + nudgeX}}`, '-y', `#{e|+:#{pane_top},${nudgeY}}`);
+    for (const item of items) {
+        args.push(escapeTmuxFormats(item.desc), escapeTmuxFormats(item.key), renderAction(item.action, item.desc));
+    }
+    args.push('-esc / q to close', '', '');
+    return args;
+}
+function renderAction(action, label) {
+    const kind = action.kind ?? 'crtr';
+    switch (kind) {
+        case 'keys':
+            return keysCmd(action.keys);
+        case 'popup':
+            return popupCmd(action.run);
+        case 'menu':
+            return tmuxCmd(buildMenuArgs(label, action.items));
+        case 'crtr':
+            return chordShellCmd(action.run);
+        default:
+            throw new Error(`unknown canvas action kind: ${kind}`);
+    }
+}
+/** Bind Alt+C to the crouter action menu. Best-effort; false if tmux fails. */
 export function installMenuBinding() {
-    const title = ' crtr ';
-    const items = [
-        // Promote types `/promote` into the agent's pane rather than shelling out:
-        // the slash command delivers the orchestration guidance into the node's
-        // context, which a bare `run-shell` (output discarded) could not.
-        { name: 'promote to orchestrator', key: 'o', cmd: `send-keys -t '#{pane_id}' '/promote' Enter` },
-        // Resume types `/resume-node` into the agent's pane: the slash command opens
-        // a whole-canvas picker (incl. dormant nodes) and revives the choice via
-        // `crtr node focus` — the only sync-safe open (routes through reviveNode).
-        { name: 'resume node', key: 'r', cmd: `send-keys -t '#{pane_id}' '/resume-node' Enter` },
-        // `d` runs `node demote`: flip the agent to TERMINAL in place — no finalize,
-        // no kill — it keeps running where it is, and because it is now terminal it
-        // is forced to push a final up the spine when it finishes. `D` runs `node
-        // demote --detach`, which ALSO closes the agent's viewer pane (frees the
-        // pane; the detached broker keeps generating). Neither ends it.
-        { name: 'demote to terminal', key: 'd', cmd: `run-shell "crtr node demote --pane '#{pane_id}' >/dev/null 2>&1"` },
-        { name: 'detach to background', key: 'D', cmd: `run-shell "crtr node demote --pane '#{pane_id}' --detach >/dev/null 2>&1"` },
-        // Close cascades down the subscribes_to spine (kills the subtree's windows,
-        // marks them canceled); revivable. Output discarded — the keypress just acts.
-        { name: 'close agent + subtree', key: 'x', cmd: `run-shell "crtr node close --pane '#{pane_id}' >/dev/null 2>&1"` },
-    ];
-    // Canvas-nav chords from config (default: g→graph, m→manager). The
-    // `__graph__` sentinel toggles the in-pi GRAPH modal via send-keys; every
-    // other bind shells the chord dispatcher, which resolves the pane's node and
-    // interpolates the bind at popup time. Keys colliding with the built-ins are
-    // skipped (the built-in wins).
-    let prefixBinds = {};
+    let prefixBinds;
     try {
         prefixBinds = readConfig('user').canvasNav.prefixBinds;
     }
-    catch { /* defaults below */ }
+    catch {
+        prefixBinds = defaultCanvasNavConfig().prefixBinds;
+    }
+    const items = [];
     for (const [key, bind] of Object.entries(prefixBinds)) {
-        if (key.length !== 1 || RESERVED_MENU_KEYS.has(key))
+        if (key.length !== 1)
             continue;
-        const name = bind.desc !== undefined && bind.desc !== '' ? bind.desc : `chord ${key}`;
-        const cmd = bind.run === '__graph__'
-            ? `send-keys -t '#{pane_id}' '/graph' Enter`
-            : `run-shell "crtr canvas chord --pane '#{pane_id}' --key ${key} >/dev/null 2>&1"`;
-        items.push({ name, key, cmd });
+        const desc = bind.desc ?? `chord ${key}`;
+        items.push({ key, desc, action: bind });
     }
-    // Dismiss hint. A tmux display-menu always closes on its native cancel keys
-    // (Escape / q / C-c), encoding-independent. We do NOT try to catch a re-pressed
-    // Alt+C: under `extended-keys on` (common, and what pi negotiates) the second
-    // Alt+C reaches the overlay as a CSI-u key (`\033[99;3u`) that tmux's menu does
-    // NOT match against an `M-c` mnemonic item, so a "close menu" row keyed M-c
-    // never fires and the menu just sits open (verified in tmux 3.6b: legacy Esc+c
-    // closes, CSI-u does not). Instead, a disabled (`-` prefix → dim, unselectable)
-    // last row tells the user the close keys that always work. Placed last so it
-    // reads as chrome below the actions.
-    items.push({ name: '-esc / q to close', key: '', cmd: '' });
-    // tmux's -x sets the menu's LEFT edge. To sit the box INSIDE the pane's
-    // top-right corner, shift x left by the box width (longest line + tmux chrome:
-    // borders + padding + the right-aligned mnemonic-key column) via format math.
-    const boxW = Math.max(title.length, ...items.map((i) => i.name.length)) + 6;
-    // Fine-tune nudges off the pane's top-right corner: a hair further left and
-    // one row down so the box doesn't kiss the pane border.
-    const nudgeX = 1; // extra columns left
-    const nudgeY = 3; // rows down
-    const args = [
-        'bind-key', '-n', 'M-c', 'display-menu',
-        '-T', `#[align=centre]${title}`,
-        // Frame the menu on the theme's distinct-surface background so it doesn't
-        // blend into the pane behind it (CTO ruling). Empty in the front door (theme
-        // not loaded there); the attach viewer re-installs this with the style once
-        // it has themed — see attach-cmd.ts.
-        ...surfaceTmuxStyleArgs(),
-        '-x', `#{e|-:#{pane_right},${boxW + nudgeX}}`,
-        '-y', `#{e|+:#{pane_top},${nudgeY}}`,
-    ];
-    for (const it of items)
-        args.push(it.name, it.key, it.cmd);
-    return tmux(args).ok;
+    return tmux(['bind-key', '-n', 'M-c', ...buildMenuArgs(' crtr ', items)]).ok;
 }
 // ---------------------------------------------------------------------------
 // Nav bindings — Alt+] / Alt+[ DFS-walk the canvas one window at a time. Each
@@ -447,7 +501,7 @@ export function installNavBindings() {
 // is claimed, and bare Alt pairs are a minefield in real configs (e.g. Alt+,/. 
 // and Alt+]/.[ commonly bound to window/pane nav). The bracket lives in the
 // private table, so it also sidesteps the M-[ vs CSI-introducer ambiguity that
-// dogs installNavBindings' Alt+[. Each key shells `crtr view cycle`, passing the
+// dogs installNavBindings' Alt+[. Each key shells surface-view cycle, passing the
 // active pane; cycle reads the pane's @crtr_view tag and respawns it on the
 // next/prev view. Output discarded so the keypress never pops a results view.
 // Installed at root boot alongside the node nav + Alt+C menu.
@@ -469,11 +523,11 @@ export function installViewNavBindings() {
     ]).ok;
     const next = tmux([
         'bind-key', '-T', 'crtr-view', ']', 'run-shell',
-        `crtr view cycle --dir next --pane '#{pane_id}' >/dev/null 2>&1`,
+        `crtr surface view cycle --dir next --pane '#{pane_id}' >/dev/null 2>&1`,
     ]).ok;
     const prev = tmux([
         'bind-key', '-T', 'crtr-view', '[', 'run-shell',
-        `crtr view cycle --dir prev --pane '#{pane_id}' >/dev/null 2>&1`,
+        `crtr surface view cycle --dir prev --pane '#{pane_id}' >/dev/null 2>&1`,
     ]).ok;
     return enter && next && prev;
 }

package/dist/core/runtime/view-socket-client.d.ts

@@ -0,0 +1,46 @@
+import { EventEmitter } from 'node:events';
+import { type NodeRow } from '../canvas/index.js';
+import { type BrokerDataFrame, type BrokerToClient, type ClientToBroker, type DequeueFrame, type GetSettingsFrame, type GetTreeFrame, type ListModelsFrame, type ListScopedModelsFrame, type ListSessionsFrame } from './broker-protocol.js';
+export type ReadOpRequest = Omit<ListModelsFrame, 'id'> | Omit<ListSessionsFrame, 'id'> | Omit<GetTreeFrame, 'id'> | Omit<GetSettingsFrame, 'id'> | Omit<ListScopedModelsFrame, 'id'> | Omit<DequeueFrame, 'id'>;
+export declare function reconnectShouldGiveUp(row: NodeRow | null): boolean;
+export declare class BrokerUnavailableError extends Error {
+    readonly nodeId: string;
+    constructor(nodeId: string);
+}
+export interface ViewSocketClientOptions {
+    emitUnmatchedDataFrames?: boolean;
+}
+export interface ViewSocketClient {
+    on(event: 'connect', listener: () => void): this;
+    on(event: 'frame', listener: (frame: BrokerToClient) => void): this;
+    on(event: 'close', listener: () => void): this;
+    on(event: 'error', listener: (err: Error) => void): this;
+    once(event: 'connect', listener: () => void): this;
+    once(event: 'frame', listener: (frame: BrokerToClient) => void): this;
+    once(event: 'close', listener: () => void): this;
+    once(event: 'error', listener: (err: Error) => void): this;
+    off(event: 'connect', listener: () => void): this;
+    off(event: 'error', listener: (err: Error) => void): this;
+}
+export declare class ViewSocketClient extends EventEmitter {
+    private readonly nodeId;
+    private socket;
+    private decoder;
+    private closeEmitted;
+    private readonly emitUnmatchedDataFrames;
+    private pending;
+    constructor(nodeId: string, options?: ViewSocketClientOptions);
+    private recordSocketFault;
+    request(frame: ReadOpRequest): Promise<BrokerDataFrame>;
+    private rejectAllPending;
+    get socketPath(): string;
+    connect(): void;
+    redial(): Promise<void>;
+    send(frame: ClientToBroker): void;
+    close(): void;
+    private onData;
+    private onError;
+    private onClose;
+    private destroy;
+    private emitError;
+}

package/dist/core/runtime/view-socket-client.js

@@ -0,0 +1,203 @@
+import { EventEmitter } from 'node:events';
+import { randomUUID } from 'node:crypto';
+import { createConnection } from 'node:net';
+import { classify } from '../fault-classifier.js';
+import { viewSocketPath } from '../canvas/paths.js';
+import { clearFault, recordFault } from './fault.js';
+import { CLIENT_READ_CAPS, encodeFrame, FrameDecoder, FrameOverflowError, } from './broker-protocol.js';
+const REQUEST_TIMEOUT_MS = 10_000;
+export function reconnectShouldGiveUp(row) {
+    if (row === null)
+        return true;
+    return row.status === 'done' || row.status === 'dead' || row.status === 'canceled';
+}
+export class BrokerUnavailableError extends Error {
+    nodeId;
+    constructor(nodeId) {
+        super(`node ${nodeId} has no running broker — focus or revive it first`);
+        this.nodeId = nodeId;
+        this.name = 'BrokerUnavailableError';
+    }
+}
+export class ViewSocketClient extends EventEmitter {
+    nodeId;
+    socket;
+    decoder = new FrameDecoder(CLIENT_READ_CAPS);
+    closeEmitted = false;
+    emitUnmatchedDataFrames;
+    pending = new Map();
+    constructor(nodeId, options = {}) {
+        super();
+        this.nodeId = nodeId;
+        this.emitUnmatchedDataFrames = options.emitUnmatchedDataFrames ?? false;
+    }
+    recordSocketFault(op, err) {
+        const classified = classify('viewer↔broker', err);
+        recordFault(this.nodeId, {
+            link: 'viewer↔broker',
+            op,
+            kind: classified.kind,
+            retry: op === 'redial'
+                ? { disposition: 'auto', by: 'client' }
+                : { disposition: 'manual' },
+            message: err instanceof Error ? err.message : String(err),
+        });
+    }
+    request(frame) {
+        const id = randomUUID();
+        return new Promise((resolve, reject) => {
+            const sock = this.socket;
+            if (sock === undefined || sock.destroyed) {
+                reject(new Error(`cannot issue '${frame.type}': no live broker connection`));
+                return;
+            }
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`request '${frame.type}' timed out after ${REQUEST_TIMEOUT_MS}ms`));
+            }, REQUEST_TIMEOUT_MS);
+            if (typeof timer.unref === 'function')
+                timer.unref();
+            this.pending.set(id, { resolve, reject, timer });
+            this.send({ ...frame, id });
+        });
+    }
+    rejectAllPending(reason) {
+        for (const { reject, timer } of this.pending.values()) {
+            clearTimeout(timer);
+            reject(new Error(reason));
+        }
+        this.pending.clear();
+    }
+    get socketPath() {
+        return viewSocketPath(this.nodeId);
+    }
+    connect() {
+        const socket = createConnection(this.socketPath);
+        this.socket = socket;
+        socket.on('connect', () => {
+            clearFault(this.nodeId, { link: 'viewer↔broker' });
+            this.emit('connect');
+        });
+        socket.on('data', (chunk) => this.onData(chunk));
+        socket.on('error', (err) => this.onError(err, 'connect'));
+        socket.on('close', () => this.onClose());
+    }
+    redial() {
+        this.destroy();
+        this.decoder = new FrameDecoder(CLIENT_READ_CAPS);
+        this.closeEmitted = false;
+        return new Promise((resolve, reject) => {
+            const socket = createConnection(this.socketPath);
+            this.socket = socket;
+            let settled = false;
+            socket.on('connect', () => {
+                if (settled)
+                    return;
+                settled = true;
+                clearFault(this.nodeId, { link: 'viewer↔broker' });
+                this.emit('connect');
+                resolve();
+            });
+            socket.on('data', (chunk) => this.onData(chunk));
+            socket.on('error', (err) => {
+                if (settled) {
+                    this.onError(err, 'redial');
+                    return;
+                }
+                settled = true;
+                this.recordSocketFault('redial', err);
+                try {
+                    socket.destroy();
+                }
+                catch {
+                    /* ignore */
+                }
+                reject(err);
+            });
+            socket.on('close', () => this.onClose());
+        });
+    }
+    send(frame) {
+        const sock = this.socket;
+        if (sock === undefined || sock.destroyed)
+            return;
+        try {
+            sock.write(encodeFrame(frame));
+        }
+        catch {
+            /* dead socket — 'close' will fire and drive teardown */
+        }
+    }
+    close() {
+        this.destroy();
+    }
+    onData(chunk) {
+        let frames;
+        try {
+            frames = this.decoder.push(chunk);
+        }
+        catch (err) {
+            const msg = err instanceof FrameOverflowError
+                ? `broker sent an oversized frame (${err.message}) — disconnecting`
+                : `failed to decode a broker frame: ${String(err)}`;
+            this.rejectAllPending(msg);
+            this.emitError(new Error(msg));
+            this.destroy();
+            return;
+        }
+        for (const raw of frames) {
+            const frame = raw;
+            if (frame.type === 'data') {
+                const entry = typeof frame.id === 'string' ? this.pending.get(frame.id) : undefined;
+                if (entry) {
+                    this.pending.delete(frame.id);
+                    clearTimeout(entry.timer);
+                    entry.resolve(frame);
+                }
+                else if (this.emitUnmatchedDataFrames) {
+                    this.emit('frame', frame);
+                }
+                continue;
+            }
+            if (frame.type === 'error' && typeof frame.id === 'string' && this.pending.has(frame.id)) {
+                const entry = this.pending.get(frame.id);
+                this.pending.delete(frame.id);
+                clearTimeout(entry.timer);
+                entry.reject(new Error(frame.message || `request failed: ${frame.code}`));
+                continue;
+            }
+            this.emit('frame', frame);
+        }
+    }
+    onError(err, op) {
+        this.recordSocketFault(op, err);
+        if (err.code === 'ECONNREFUSED' || err.code === 'ENOENT') {
+            this.emitError(new BrokerUnavailableError(this.nodeId));
+        }
+        else {
+            this.emitError(new Error(`view socket error: ${err.message}`));
+        }
+    }
+    onClose() {
+        if (this.closeEmitted)
+            return;
+        this.closeEmitted = true;
+        this.rejectAllPending('broker connection closed');
+        this.emit('close');
+    }
+    destroy() {
+        const sock = this.socket;
+        if (sock !== undefined && !sock.destroyed) {
+            try {
+                sock.destroy();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    emitError(err) {
+        if (this.listenerCount('error') > 0)
+            this.emit('error', err);
+    }
+}

package/dist/core/scope.d.ts

@@ -1,9 +1,18 @@
 import type { InstalledPlugin, Scope } from '../types.js';
 export declare function builtinViewsRoot(): string;
 export declare function builtinMemoryRoot(): string;
+export declare function builtinPiPackagesDir(): string;
+export declare function builtinPiPackageDir(name: string): string;
 export declare function userScopeRoot(): string;
 export declare function findProjectScopeRoot(startDir?: string): string | null;
+/** Every project scope root visible from `startDir`, nearest first. Each
+ *  ancestor directory with a `.crouter/` contributes memory/preferences to the
+ *  current workspace; the nearest root still wins for writes and duplicate doc
+ *  names. The user-global `~/.crouter/` is excluded because it is the separate
+ *  user scope, not a project ancestor. */
+export declare function findProjectScopeRoots(startDir?: string): string[];
 export declare function projectScopeRoot(startDir?: string): string | null;
+export declare function projectScopeRoots(startDir?: string): string[];
 export declare function scopeRoot(scope: Scope): string | null;
 export declare function requireScopeRoot(scope: Scope): string;
 export declare function ensureProjectScopeRoot(startDir?: string): string;

package/dist/core/scope.js

@@ -24,38 +24,60 @@ export function builtinMemoryRoot() {
     const pkgDir = dirname(coreDir); // src/ or dist/
     return join(pkgDir, 'builtin-memory');
 }
+export function builtinPiPackagesDir() {
+    const thisFile = fileURLToPath(import.meta.url);
+    const coreDir = dirname(thisFile);
+    const pkgDir = dirname(coreDir); // src/ or dist/
+    return join(pkgDir, 'builtin-pi-packages');
+}
+export function builtinPiPackageDir(name) {
+    return join(builtinPiPackagesDir(), name);
+}
 export function userScopeRoot() {
     return join(homedir(), CRTR_DIR_NAME);
 }
+function isProjectScopeDir(candidate, userRoot) {
+    if (candidate === userRoot || !existsSync(candidate))
+        return false;
+    try {
+        return statSync(candidate).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 export function findProjectScopeRoot(startDir = process.cwd()) {
     if (cachedProjectRoot !== undefined)
         return cachedProjectRoot;
+    const roots = findProjectScopeRoots(startDir);
+    cachedProjectRoot = roots[0] ?? null;
+    return cachedProjectRoot;
+}
+/** Every project scope root visible from `startDir`, nearest first. Each
+ *  ancestor directory with a `.crouter/` contributes memory/preferences to the
+ *  current workspace; the nearest root still wins for writes and duplicate doc
+ *  names. The user-global `~/.crouter/` is excluded because it is the separate
+ *  user scope, not a project ancestor. */
+export function findProjectScopeRoots(startDir = process.cwd()) {
+    const roots = [];
     const userRoot = userScopeRoot();
     let dir = resolve(startDir);
     while (true) {
         const candidate = join(dir, CRTR_DIR_NAME);
-        if (candidate !== userRoot && existsSync(candidate)) {
-            try {
-                if (statSync(candidate).isDirectory()) {
-                    cachedProjectRoot = candidate;
-                    return candidate;
-                }
-            }
-            catch {
-                /* fall through */
-            }
-        }
+        if (isProjectScopeDir(candidate, userRoot))
+            roots.push(candidate);
         const parent = dirname(dir);
-        if (parent === dir) {
-            cachedProjectRoot = null;
-            return null;
-        }
+        if (parent === dir)
+            return roots;
         dir = parent;
     }
 }
 export function projectScopeRoot(startDir) {
     return findProjectScopeRoot(startDir);
 }
+export function projectScopeRoots(startDir) {
+    return findProjectScopeRoots(startDir);
+}
 export function scopeRoot(scope) {
     // The builtin scope has no scope-root dir: its only content is memory
     // (builtinMemoryRoot) and views (builtinViewsRoot), both hard special cases.

package/dist/core/substrate/index.d.ts

@@ -5,5 +5,5 @@ export type { NodeConfigSubject } from './subject.js';
 export { gatePasses } from './gate.js';
 export { INDEX_NAME, isIndexName, indexDirOf, displayName, buildCeilingIndex, effectiveRung, } from './ceiling.js';
 export type { Surface } from './ceiling.js';
-export { renderPreferencesSection, renderKnowledgeBlock, renderMemoryGuidance, } from './render.js';
+export { renderPreferencesSection, renderKnowledgeBlock, } from './render.js';
 export { renderOnReadDocs } from './on-read.js';

package/dist/core/substrate/index.js

@@ -15,5 +15,5 @@ parseSubstrateFrontmatter, parseSubstrateDoc, previewLine, } from './schema.js';
 export { scopeForCwd, spineDepth, assembleNodeSubject } from './subject.js';
 export { gatePasses } from './gate.js';
 export { INDEX_NAME, isIndexName, indexDirOf, displayName, buildCeilingIndex, effectiveRung, } from './ceiling.js';
-export { renderPreferencesSection, renderKnowledgeBlock, renderMemoryGuidance, } from './render.js';
+export { renderPreferencesSection, renderKnowledgeBlock, } from './render.js';
 export { renderOnReadDocs } from './on-read.js';