@crouton-kit/crouter 0.3.32 → 0.3.33

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
@@ -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

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/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';

package/dist/core/substrate/on-read.js

@@ -23,6 +23,14 @@
 // the doc fires only on its trigger, never positionally on every read under its
 // scope. The two explicit triggers compose by OR.
 //
+// D6 — an explicitly-triggered doc also PIERCES the INDEX ceiling: it surfaces at
+// its OWN fileReadVisibility, not min(own, ancestor INDEX rungs). The ceiling is
+// the mechanism for collapsing a subtree's BOOT + POSITIONAL on-read surface; a
+// cross-cutting applies-to/read-when trigger is the author deliberately opting
+// ONE doc into surfacing when a specific file is read, so a `none`-capped
+// ancestor INDEX (the default for a reference plugin pulled by name) must not
+// veto it. Same stance as D5 — the explicit trigger is the more specific signal.
+//
 // Each candidate runs the substrate pipeline at its fileReadVisibility rung:
 //   parse → gatePasses(doc, assembleNodeSubject(nodeId)) → render
 //   (content → body, preview → previewLine, name → bare tag, none → skip).
@@ -157,7 +165,7 @@ function positionalCandidates(absReadFile) {
                     // D5: a doc with an explicit read-trigger (applies-to/read-when) does
                     // NOT fire positionally — it surfaces only via that trigger.
                     if (doc && !hasExplicitTrigger(doc))
-                        out.push({ doc, realpath: real, order: depth });
+                        out.push({ doc, realpath: real, order: depth, explicit: false });
                 }
             }
         }
@@ -218,7 +226,7 @@ function appliesToCandidates(absReadFile, taken) {
         if (!globs.some((g) => globMatches(g, absReadFile, owningRootOf(doc))))
             continue;
         taken.add(real);
-        out.push({ doc, realpath: real, order: -1 });
+        out.push({ doc, realpath: real, order: -1, explicit: true });
     }
     return out;
 }
@@ -261,7 +269,7 @@ function readWhenCandidates(readFileFm, taken) {
         if (!evalCondition(doc.readWhen, readFileFm))
             continue;
         taken.add(real);
-        out.push({ doc, realpath: real, order: -1 });
+        out.push({ doc, realpath: real, order: -1, explicit: true });
     }
     return out;
 }
@@ -350,7 +358,11 @@ export function renderOnReadDocs(nodeId, readFilePath, seen = new Set()) {
         try {
             if (!gatePasses(c.doc, subject))
                 continue; // gated out for this node
-            const rung = effectiveRung(c.doc, ceil, 'fileReadVisibility');
+            // D6: an explicit applies-to/read-when trigger pierces the INDEX ceiling
+            // and renders at the doc's own rung; positional docs honor the ceiling.
+            const rung = c.explicit
+                ? c.doc.fileReadVisibility
+                : effectiveRung(c.doc, ceil, 'fileReadVisibility');
             const doc = rung === c.doc.fileReadVisibility && displayName(c.doc.name) === c.doc.name
                 ? c.doc
                 : { ...c.doc, fileReadVisibility: rung, name: displayName(c.doc.name) };

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

@@ -1,19 +1,16 @@
-/** The `<preferences>` system-prompt block: every eligible `kind: preference`
- *  doc in one tree at its effective rung (the preference default rung is
- *  `preview` → the routing line). Returns '' when nothing is eligible. */
+/** The system-prompt memory block: the always-present memory-usage guidance,
+ *  then (when any are eligible) the `kind: preference` docs in one tree at their
+ *  effective rung (the preference default rung is `preview` → the routing line).
+ *  ALWAYS returns a non-empty `<memory kind="preference">` block — the guidance
+ *  frame is unconditional, so the system-prompt splice is never empty even when
+ *  no preference is eligible. */
 export declare function renderPreferencesSection(nodeId: string): string;
-/** The `<knowledge>` block embedded INSIDE the `<crtr-context>` session_start
- *  message (bearings.ts pushes the returned string into the block, or drops it
+/** The `<memory kind="knowledge">` block embedded in the session_start bearings
+ *  message (bearings.ts pushes it as a SIBLING of `<crtr-bearings>`, or drops it
  *  when ''). The consultable catalog: every eligible `kind: knowledge` resolver
  *  doc at its effective rung (most surface only as `[+N more]` counts unless
  *  author-promoted) PLUS the node-local memory docs (any kind), the latter
  *  floored to `name` so a `none`-rung node-local doc still shows its name rather
- *  than collapsing into a count. Procedural skills and factual references both
- *  live here now — they merged into the one `knowledge` kind. Returns '' when
- *  nothing is eligible. */
+ *  than collapsing into a count. Procedural guidance and factual references both
+ *  live here as `knowledge`. Returns '' when nothing is eligible. */
 export declare function renderKnowledgeBlock(nodeId: string): string;
-/** The memory-hygiene directive spliced into the system prompt after the
- *  preferences block. ALWAYS present for a canvas node (the memory system always
- *  exists), so the system-prompt splice stays non-empty even when both trees are
- *  empty. Guidance about USING the memory system, not a per-doc surface. */
-export declare function renderMemoryGuidance(): string;