@north-light/crouter 0.3.308 → 0.3.310

package/dist/core/canvas/browse/app.js

@@ -253,17 +253,30 @@ export async function runBrowse(opts) {
             if (r !== undefined)
                 slice.push(r);
         }
+        // The row this frame is FOR. Everything below awaits disk and daemon I/O, and
+        // renderFrame reads state.cursor live — so a keystroke landing mid-await would
+        // otherwise paint the newly selected row's header above the previous row's
+        // (or no) conversation, which is what made the panel flash empty while
+        // scrolling. Drop a frame whose selection has moved instead: scheduleFlush's
+        // drain loop guarantees the keystroke that moved it gets its own flush.
+        const selectedId = curRow()?.id;
+        const stale = () => curRow()?.id !== selectedId;
         await enrichRowsFromSource(source, slice, askCounts);
-        const cur = curRow();
-        if (cur !== undefined) {
-            const r = rowOf(cur.id);
+        if (stale())
+            return;
+        if (selectedId !== undefined) {
+            const r = rowOf(selectedId);
             if (r !== undefined) {
                 await loadPreviewFromSource(source, r);
+                if (stale())
+                    return;
                 // The chat transcript is the side panel's body, so it is read for the
                 // SELECTED row only — never on the background warm pass, where one ordered
                 // transcript per node would hold the whole canvas's conversations in memory.
                 if (previewLayout(size.cols, previewOn).mode === 'side')
                     await loadTranscriptFromSource(source, r);
+                if (stale())
+                    return;
             }
         }
         const frame = renderFrame({
@@ -771,6 +784,7 @@ export async function runBrowse(opts) {
         // Search. Starting a search ranks by relevance (decision) so the best prompt/
         // name match floats to the top as you type.
         if (action === 'crtr.browse.search') {
+            startWarm();
             state.search = true;
             state.query = '';
             state.sort = 'relevance';
@@ -842,31 +856,42 @@ export async function runBrowse(opts) {
     }
     setupTerminal();
     await flush();
-    // Background corpus warmer: after the instant first paint, progressively enrich
-    // + load-preview every row (in small chunks, off the event loop) so the prompt
-    // super-search corpus lights up shortly after the instant name/kind/id search.
-    // Mutates row objects only; re-flushes solely while a live search is open so new
-    // matches surface. Stops as soon as the terminal is restored (quit/resume/crash).
-    const warmRows = [...tree.nodes.values()].map((n) => n.row);
-    let warmIdx = 0;
-    const WARM_CHUNK = 30;
-    const warmChunk = async () => {
-        if (restored)
-            return;
-        const end = Math.min(warmIdx + WARM_CHUNK, warmRows.length);
-        const slice = warmRows.slice(warmIdx, end);
-        await enrichRowsFromSource(source, slice, askCounts);
-        await Promise.all(slice.map((r) => loadPreviewFromSource(source, r)));
-        warmIdx = end;
-        // A live search may match the freshly-warmed prompts → recompute + repaint.
-        if (state.search && state.query !== '') {
-            recompute(curRow()?.id);
-            scheduleFlush();
-        }
-        if (warmIdx < warmRows.length)
-            setImmediate(() => { void warmChunk().catch((err) => logAsyncFailure('background warm failed', err)); });
+    // Background corpus warmer: progressively enrich + load-preview every row (in
+    // small chunks, off the event loop) so the prompt super-search corpus lights up
+    // shortly after the instant name/kind/id search. Mutates row objects only;
+    // re-flushes solely while a live search is open so new matches surface. Stops as
+    // soon as the terminal is restored (quit/resume/crash).
+    //
+    // It runs on the FIRST search, not at boot. The pass reads a session file per
+    // node, and the only thing it feeds is prompt-text search — so paying for it at
+    // launch charged every user who merely navigates for a corpus they never query,
+    // and each chunk's disk read stalled the loop in front of their keystrokes.
+    let warmStarted = false;
+    const startWarm = () => {
+        if (warmStarted)
+            return;
+        warmStarted = true;
+        const warmRows = [...tree.nodes.values()].map((n) => n.row);
+        let warmIdx = 0;
+        const WARM_CHUNK = 30;
+        const warmChunk = async () => {
+            if (restored)
+                return;
+            const end = Math.min(warmIdx + WARM_CHUNK, warmRows.length);
+            const slice = warmRows.slice(warmIdx, end);
+            await enrichRowsFromSource(source, slice, askCounts);
+            await Promise.all(slice.map((r) => loadPreviewFromSource(source, r)));
+            warmIdx = end;
+            // A live search may match the freshly-warmed prompts → recompute + repaint.
+            if (state.search && state.query !== '') {
+                recompute(curRow()?.id);
+                scheduleFlush();
+            }
+            if (warmIdx < warmRows.length)
+                setImmediate(() => { void warmChunk().catch((err) => logAsyncFailure('background warm failed', err)); });
+        };
+        setImmediate(() => { void warmChunk().catch((err) => logAsyncFailure('background warm failed', err)); });
     };
-    setImmediate(() => { void warmChunk().catch((err) => logAsyncFailure('background warm failed', err)); });
     await new Promise(() => {
         const onData = (data) => {
             try {

package/dist/core/canvas/browse/render.js

@@ -764,6 +764,15 @@ function transcriptLines(turns, query, width, height, caps) {
     }
     return blocks.reverse().flat().slice(-height);
 }
+/** What an empty panel body MEANS. `(no conversation yet)` is a claim about the
+ *  node; it is only true once the session has actually been read. Until then the
+ *  same blank body means the read is still in flight, and printing the claim made a
+ *  node the panel had simply not gotten to yet look like a node that had never
+ *  spoken. */
+function emptyBodyNote(r) {
+    const read = r.transcriptLoaded === true || r.previewLoaded === true;
+    return read ? `${DIM}(no conversation yet)${RESET}` : `${DIM}(loading…)${RESET}`;
+}
 /** The turns the panel paints. A node that was never revived has no session, so its
  *  spawn prompt and last reply stand in — the panel then still reads as a chat
  *  rather than going blank, and a remote canvas (no local session file) keeps a body. */
@@ -836,7 +845,7 @@ function sidePanelBody(r, width, height, caps, now, query, showReport) {
                 ? { text: `${hits} ${hits === 1 ? 'turn' : 'turns'}`, fg: FG_BRIGHT_CYAN }
                 : { text: 'matched on name', fg: FG_GRAY })];
         const body = transcriptLines(turns, query, width, height - 1, caps);
-        out.push(...(body.length === 0 ? [`${DIM}(no conversation yet)${RESET}`] : body));
+        out.push(...(body.length === 0 ? [emptyBodyNote(r)] : body));
         return out.slice(0, height);
     }
     const rep = r.report;
@@ -878,7 +887,7 @@ function sidePanelBody(r, width, height, caps, now, query, showReport) {
     if (chatH >= 2) {
         out.push(sectionRule('CHAT', width, caps));
         const body = transcriptLines(panelTurns(r), '', width, chatH, caps);
-        out.push(...(body.length === 0 ? [`${DIM}(no conversation yet)${RESET}`] : body));
+        out.push(...(body.length === 0 ? [emptyBodyNote(r)] : body));
     }
     if (stateBlock.length > 0) {
         while (out.length < height - stateBlock.length)

package/dist/core/canvas/render-source.js

@@ -12,7 +12,7 @@
 // ./status-glyph.js, ./node-recap.js, ../runtime/fault.js, ../frontmatter.js,
 // ./paths.js, ./remote-canvas-source.js, and TYPE-ONLY ./source.js + ./types.js. Do NOT import ./canvas.js, ./attention.js,
 // ./focuses.js, or ./db.js here — that is the whole point of the split.
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, statSync, openSync, readSync, closeSync } from 'node:fs';
 import { join } from 'node:path';
 import { RemoteCanvasSource } from './remote-canvas-source.js';
 import { fullName } from './labels.js';
@@ -227,6 +227,58 @@ export function readNewestReport(nodeId) {
     const text = rest.replace(/\s+/g, ' ').trim();
     return { kind, ts, heading, body: text.length > REPORT_BODY_CAP ? text.slice(0, REPORT_BODY_CAP) : text };
 }
+/** Read only the two ENDS of a pi session jsonl that any preview actually needs.
+ *
+ *  A session file grows without bound — this canvas holds 2 GB of them across ~1900
+ *  nodes, the largest single file 67 MB — and every reader below wants either the
+ *  FIRST few prompts or the LAST few turns. Slurping the whole file to find them is
+ *  what made the browse preview panel stall the event loop for seconds at a time.
+ *
+ *  A file at or under head+tail is read whole, so small sessions (nearly all of
+ *  them) behave exactly as before. Above that, one head slice and one tail slice are
+ *  read positionally. The line adjacent to each cut is dropped: it is a fragment of
+ *  a record that continues outside the window, and a partial line is not parseable
+ *  JSON. Never throws; returns null when there is no readable session file. */
+const PARTS_HEAD_BYTES = 1 << 20;
+const PARTS_TAIL_BYTES = 1 << 20;
+const TRANSCRIPT_TAIL_BYTES = 4 << 20;
+function readSessionWindow(sessionFile, headBytes, tailBytes) {
+    if (sessionFile === undefined || sessionFile === null || sessionFile === '')
+        return null;
+    try {
+        if (!existsSync(sessionFile))
+            return null;
+        const size = statSync(sessionFile).size;
+        if (size <= headBytes + tailBytes) {
+            const lines = readFileSync(sessionFile, 'utf8').split('\n');
+            return { head: lines, tail: lines };
+        }
+        const fd = openSync(sessionFile, 'r');
+        try {
+            const slice = (start, length) => {
+                if (length <= 0)
+                    return [];
+                const buf = Buffer.allocUnsafe(length);
+                const got = readSync(fd, buf, 0, length, start);
+                return buf.subarray(0, got).toString('utf8').split('\n');
+            };
+            const head = slice(0, headBytes);
+            const tail = slice(size - tailBytes, tailBytes);
+            // Drop the fragment on the inside edge of each cut.
+            if (head.length > 0)
+                head.pop();
+            if (tail.length > 0)
+                tail.shift();
+            return { head, tail };
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch {
+        return null;
+    }
+}
 /** The node's session-derived preview text in ONE file read (today's two reads,
  *  folded): EVERY user prompt across the pi session (`prompts` — the whole
  *  conversation, not just the spawn prompt) AND the LAST assistant message text
@@ -239,21 +291,13 @@ export function readNewestReport(nodeId) {
 const CONVO_CAP = 8192;
 const CONVO_MSG_CAP = 2048;
 export function readSessionParts(sessionFile) {
-    if (sessionFile === undefined || sessionFile === null || sessionFile === '')
+    const win = readSessionWindow(sessionFile, PARTS_HEAD_BYTES, PARTS_TAIL_BYTES);
+    if (win === null)
         return {};
-    let lines;
-    try {
-        if (!existsSync(sessionFile))
-            return {};
-        lines = readFileSync(sessionFile, 'utf8').split('\n');
-    }
-    catch {
-        return {};
-    }
     // Forward pass: every user prompt, joined + capped.
     const parts = [];
     let total = 0;
-    for (const line of lines) {
+    for (const line of win.head) {
         // Cheap prefilter: skip every line that isn't a user-role message before the
         // (relatively costly) JSON.parse. Pi writes compact JSON (no spaces), but
         // tolerate the spaced form too.
@@ -286,8 +330,8 @@ export function readSessionParts(sessionFile) {
     }
     // Backward pass: the newest assistant message carrying text.
     let lastAssistant;
-    for (let i = lines.length - 1; i >= 0; i--) {
-        const line = lines[i];
+    for (let i = win.tail.length - 1; i >= 0; i--) {
+        const line = win.tail[i];
         if (line === '' || (line.indexOf('"role":"assistant"') === -1 && line.indexOf('"role": "assistant"') === -1))
             continue;
         let rec;
@@ -319,19 +363,13 @@ const TRANSCRIPT_MSG_CAP = 4096;
  *  with no text (tool-only turns), so the result reads as a chat rather than a log.
  *  One file read; never throws; empty for a node that was never revived. */
 export function readTranscript(sessionFile) {
-    if (sessionFile === undefined || sessionFile === null || sessionFile === '')
-        return [];
-    let lines;
-    try {
-        if (!existsSync(sessionFile))
-            return [];
-        lines = readFileSync(sessionFile, 'utf8').split('\n');
-    }
-    catch {
+    // Only the last TRANSCRIPT_TURNS survive, so this is a pure tail read: the head
+    // window is 0 and the tail is sized to hold far more than that many turns.
+    const win = readSessionWindow(sessionFile, 0, TRANSCRIPT_TAIL_BYTES);
+    if (win === null)
         return [];
-    }
     const turns = [];
-    for (const line of lines) {
+    for (const line of win.tail) {
         // Same cheap prefilter as readSessionParts: skip every line that cannot be a
         // user or assistant message before paying for JSON.parse.
         if (line === '')

package/dist/core/command.js

@@ -460,6 +460,14 @@ export async function parseArgv(params, tokens, options) {
             continue;
         }
         if (positionalValues.length > 0) {
+            // Defer this rejection until flags are parsed: a leaf-specific recovery
+            // may depend on a target flag that follows the positional body.
+            if (stdinParam !== undefined && positionalParams.length === 0) {
+                positionalValues.push(token);
+                positionalWasSupplied = true;
+                i++;
+                continue;
+            }
             // A leaf that also declares a `stdin` param treats its stdin value as
             // write-only/sensitive by convention (`profile env set`'s value, etc.).
             // An unexpected extra positional is the likely secret-as-argv mistake, so
@@ -484,6 +492,13 @@ export async function parseArgv(params, tokens, options) {
     // genuinely piped, non-empty stdin is ambiguous and errors loudly.
     let stdinWasSupplied = false;
     if (stdinParam !== undefined) {
+        if (positionalValues.length > 1 && positionalParams.length === 0) {
+            const conflict = stdinParam.positionalStdinConflict?.(result);
+            if (conflict !== undefined) {
+                throw parseArgvError('bad_invocation', conflict.message, undefined, conflict.field, conflict.next);
+            }
+            throw parseArgvError('bad_invocation', `unexpected extra positional argument (value withheld: this leaf reads "${stdinParam.name}" from stdin, never argv)`, undefined, undefined, `Pipe it on stdin instead of passing it as a positional argument.`);
+        }
         if (positionalValues.length > 0 && positionalParams.length === 0 && stdinParam.allowPositional !== false) {
             const positionalValue = positionalValues[0];
             if (positionalValue === '-') {

package/dist/core/feed/inbox.js

@@ -18,7 +18,7 @@ import { resolveRef } from '../canvas/history.js';
 import { emitEvent } from '../events/emit.js';
 import { errorClassFromError } from '../events/errors.js';
 import { generateOperationId, operationIdContext, validateOperationId } from '../events/operation-id.js';
-import { formatInboxCard } from '../../shared/generated-context.js';
+import { formatInboxCard, formatInboxRefInstruction } from '../../shared/generated-context.js';
 import { renderBirthAnnouncementBody } from '../../shared/birth-announcement.js';
 const INBOX_ENTRY_ID = /^(?!0{32}$)[0-9a-f]{32}$/;
 function validateInboxEntryId(value) {
@@ -387,12 +387,14 @@ function entryBody(e) {
         return birth;
     const report = inlineReport(e);
     if (report !== null)
-        return report.trimEnd();
+        return `${report.trimEnd()}\n\n${formatInboxRefInstruction(e.ref)}`;
     const body = inlineBody(e);
     if (body === '')
-        return e.label;
+        return e.ref === undefined ? e.label : `${e.label}\n\n${formatInboxRefInstruction(e.ref)}`;
     const { text, clipped } = clipBody(body);
-    return clipped && e.ref === undefined ? `${text}\n… (body clipped)` : text;
+    if (e.ref !== undefined)
+        return `${text}\n\n${formatInboxRefInstruction(e.ref)}`;
+    return clipped ? `${text}\n… (body clipped)` : text;
 }
 function cardEntry(e) {
     return {

package/dist/core/runtime/bearings-render.js

@@ -151,13 +151,13 @@ export function buildProjectContextBlock(cwd) {
  *  subsection of <crtr-bearings>. */
 export function contextDirNote(nodeId) {
     return (`Your context directory is \`${contextDir(nodeId)}\` (also in the env as \`$CRTR_CONTEXT_DIR\`) — ` +
-        'durable scratch space on disk, and the one place the other nodes on the canvas can read from. ' +
+        'durable scratch space on disk where you write documents to share with other nodes on the canvas. ' +
         'Put documents here that you want to share by reference instead of re-explaining them in a ' +
         'prompt: specs, designs, findings, notes worth pointing a sibling, child, or parent at. It is a ' +
         'shared document store, not a task tracker. **Address it by absolute path** — write artifacts as ' +
         '`$CRTR_CONTEXT_DIR/<name>.md` (or the full path above). Your working dir is the project, NOT ' +
-        'this directory, so a bare relative `context/...` lands in the repo, not here — and other nodes ' +
-        'can only read what is actually here. When you report a file, report its absolute path.');
+        'this directory, so a bare relative `context/...` lands in the repo, not here. When you report a ' +
+        'file, report its absolute path.');
 }
 /** The profile-purview note — rendered ONLY when the profile resolves to a
  *  manifest that names at least one project dir. Phrased as PURVIEW, not a cwd

package/dist/core/runtime/broker/inbox.js

@@ -2,7 +2,7 @@
 // broker only reads its own files and uses daemon-projected report senders.
 import { existsSync, readFileSync } from 'node:fs';
 import { inboxPath, nodeDir } from '../../canvas/paths.js';
-import { formatInboxCard } from '../../../shared/generated-context.js';
+import { formatInboxCard, formatInboxRefInstruction } from '../../../shared/generated-context.js';
 import { renderBirthAnnouncementBody } from '../../../shared/birth-announcement.js';
 const ENTRY_ID = /^(?!0{32}$)[0-9a-f]{32}$/;
 const BODY_MAX_LINES = 12;
@@ -146,12 +146,14 @@ function entryBody(entry, reportNodes) {
         return birth;
     const report = inlineReport(entry, reportNodes);
     if (report !== null)
-        return report.trimEnd();
+        return `${report.trimEnd()}\n\n${formatInboxRefInstruction(entry.ref)}`;
     const body = inlineBody(entry);
     if (body === '')
-        return entry.label;
+        return entry.ref === undefined ? entry.label : `${entry.label}\n\n${formatInboxRefInstruction(entry.ref)}`;
     const { text, clipped } = clipBody(body);
-    return clipped && entry.ref === undefined ? `${text}\n… (body clipped)` : text;
+    if (entry.ref !== undefined)
+        return `${text}\n\n${formatInboxRefInstruction(entry.ref)}`;
+    return clipped ? `${text}\n… (body clipped)` : text;
 }
 function cardEntry(entry, reportNodes) {
     return {

package/dist/core/runtime/fleet.js

@@ -31,7 +31,7 @@ export function brokerCapReached(cap, live) {
     return new InputError({
         error: 'broker_cap_reached',
         message: `no broker slot is free — ${live} live brokers at the cap of ${cap}.`,
-        next: `Finish or close a live node (\`crtr canvas render\` shows them), or raise the cap with CRTR_MAX_LIVE_BROKERS, then retry.`,
+        next: `Finish or close a live node (\`crtr canvas dashboard\` shows them), or raise the cap with CRTR_MAX_LIVE_BROKERS, then retry.`,
     });
 }
 let bound;

package/dist/core/runtime/placement.d.ts

@@ -1,6 +1,6 @@
 import { type FocusRow } from '../canvas/index.js';
 export type { FocusRow };
-export { splitWindow, breakPane, selectLayout, selectPane, focusWindow, selectWindow, switchClient, openNodeWindow, ensureSession, paneLocation, paneExists, paneRunning, paneCurrentPath, currentTmux, inTmux, paneOfNode, setPaneOption, getPaneOption, piCommand, shellQuote, respawnPaneSync, closePane, displayPopup, windowOfPane, renameWindow, paneOfWindow, windowAlive, listLivePanes, } from './tmux-driver.js';
+export { splitWindow, breakPane, selectLayout, selectPane, focusWindow, selectWindow, switchClient, openNodeWindow, ensureSession, paneLocation, paneExists, paneRunning, paneCurrentPath, currentTmux, inTmux, paneOfNode, setPaneOption, getPaneOption, piCommand, shellQuote, respawnPaneSync, closePane, displayPopup, windowOfPane, renameWindow, paneOfWindow, windowAlive, listLivePanes, listLivePanesAsync, } from './tmux-driver.js';
 export type { RespawnPaneOpts } from './tmux-driver.js';
 export { installTmuxBindings } from './tmux-bindings.js';
 export type { TmuxInstalledPair, TmuxInstallDiagnostic, TmuxInstallResult } from './tmux-bindings.js';

package/dist/core/runtime/placement.js

@@ -47,7 +47,7 @@ import { isPidAlive } from '../canvas/pid.js';
 // `piCommand`, `paneCurrentPath`, and `shellQuote` remain available to command
 // modules that need to build or inspect tmux pane commands without importing
 // tmux-driver.ts directly.
-export { splitWindow, breakPane, selectLayout, selectPane, focusWindow, selectWindow, switchClient, openNodeWindow, ensureSession, paneLocation, paneExists, paneRunning, paneCurrentPath, currentTmux, inTmux, paneOfNode, setPaneOption, getPaneOption, piCommand, shellQuote, respawnPaneSync, closePane, displayPopup, windowOfPane, renameWindow, paneOfWindow, windowAlive, listLivePanes, } from './tmux-driver.js';
+export { splitWindow, breakPane, selectLayout, selectPane, focusWindow, selectWindow, switchClient, openNodeWindow, ensureSession, paneLocation, paneExists, paneRunning, paneCurrentPath, currentTmux, inTmux, paneOfNode, setPaneOption, getPaneOption, piCommand, shellQuote, respawnPaneSync, closePane, displayPopup, windowOfPane, renameWindow, paneOfWindow, windowAlive, listLivePanes, listLivePanesAsync, } from './tmux-driver.js';
 export { installTmuxBindings } from './tmux-bindings.js';
 // Viewer registry reads — COMPOSE over the canvas focuses table (§2.3/§4).
 //

package/dist/core/runtime/tmux-driver.d.ts

@@ -158,6 +158,13 @@ export declare function paneRunning(pane: string): boolean;
  *  liveness sweeps (e.g. the daemon's stale-focus GC) don't pay a per-pane
  *  display-message each. */
 export declare function listLivePanes(): Set<string> | null;
+/** The same probe without blocking the event loop, for callers running inside
+ *  crtrd's detached work. The daemon runs this sweep on every supervision tick,
+ *  and a blocking fork/exec there freezes the API socket — which every CLI
+ *  command and every live broker's inbox poll shares — for its full duration.
+ *  Identical contract to `listLivePanes`: null means the probe failed (no
+ *  server, timeout), which a GC pass must treat as "can't tell" and skip. */
+export declare function listLivePanesAsync(): Promise<Set<string> | null>;
 /** The working directory of a pane (`display-message -p -t <pane>
  *  '#{pane_current_path}'`). Null if tmux fails. */
 export declare function paneCurrentPath(pane: string): string | null;

package/dist/core/runtime/tmux-driver.js

@@ -315,6 +315,26 @@ export function listLivePanes() {
         return null;
     return new Set(r.stdout.split('\n').filter((p) => p !== ''));
 }
+const PANE_PROBE_TIMEOUT_MS = 2000;
+/** The same probe without blocking the event loop, for callers running inside
+ *  crtrd's detached work. The daemon runs this sweep on every supervision tick,
+ *  and a blocking fork/exec there freezes the API socket — which every CLI
+ *  command and every live broker's inbox poll shares — for its full duration.
+ *  Identical contract to `listLivePanes`: null means the probe failed (no
+ *  server, timeout), which a GC pass must treat as "can't tell" and skip. */
+export async function listLivePanesAsync() {
+    const stdout = await new Promise((resolve) => {
+        try {
+            execFile('tmux', ['list-panes', '-a', '-F', '#{pane_id}'], { encoding: 'utf8', timeout: PANE_PROBE_TIMEOUT_MS, maxBuffer: 4 * 1024 * 1024 }, (err, out) => resolve(err ? null : out));
+        }
+        catch {
+            resolve(null);
+        }
+    });
+    if (stdout === null)
+        return null;
+    return new Set(stdout.trim().split('\n').filter((p) => p !== ''));
+}
 /** The working directory of a pane (`display-message -p -t <pane>
  *  '#{pane_current_path}'`). Null if tmux fails. */
 export function paneCurrentPath(pane) {

package/dist/core/substrate/on-read.d.ts

@@ -85,10 +85,12 @@ export declare function renderOnCommandDocsForSubject(subject: NodeConfigSubject
  * its matching rung or above, which is the release — the caller lets the
  * command through. */
 export declare function renderPreCommandDocsForSubject(subject: NodeConfigSubject, command: string, target?: ExposureTarget, accounting?: DeliveryAccounting): string;
-/** Does ANY doc in this session's corpus carry a `pre-command` entry? The
- * short-circuit a pre-execution caller checks first: with no such doc — the
- * common case — no command need ever pay for a subject lookup. */
-export declare function corpusHasPreCommandSurfaces(): boolean;
+/** Whether this command matches a `command` surface before its node-config
+ * gate is evaluated. A matching gate still requires a subject lookup. */
+export declare function corpusHasCommandSurfaceForCommand(command: string): boolean;
+/** Whether this command matches a `pre-command` surface before its node-config
+ * gate is evaluated. A matching gate still requires a subject lookup. */
+export declare function corpusHasPreCommandSurfaceForCommand(command: string): boolean;
 /** Forget the transcript exposure of every `pre-command` doc, re-arming their
  * holds. Compaction drops delivered guidance out of the transcript while the
  * ledger still claims it was delivered, so without this pass a doc could be

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

@@ -43,7 +43,7 @@
 import { sep } from 'node:path';
 import { realpathOrSelf } from '../fs-utils.js';
 import { ambientMemoryTarget, listAllMemoryDocs, loadMemoryTargetView, } from '../memory-resolver.js';
-import { owningRootOf } from './surface-match.js';
+import { commandEntryMatches, owningRootOf, preCommandEntryMatches } from './surface-match.js';
 import { demoteDocumentTranscriptExposure, documentExposedAtOrAbove, emptyContextExposureState, exposedAtOrAbove, exposureTarget, registerDocumentExposure, registerExposure, } from './injected-store.js';
 import { planDelivery } from './plan.js';
 import { parseSubstrateDoc, previewLine, rungRank } from './schema.js';
@@ -288,11 +288,19 @@ export function renderPreCommandDocsForSubject(subject, command, target = transi
 function carriesPreCommandEntry(doc) {
     return doc.surfaces.some((entry) => entry.on === 'pre-command');
 }
-/** Does ANY doc in this session's corpus carry a `pre-command` entry? The
- * short-circuit a pre-execution caller checks first: with no such doc — the
- * common case — no command need ever pay for a subject lookup. */
-export function corpusHasPreCommandSurfaces() {
-    return resolvedDocs().some(({ doc }) => carriesPreCommandEntry(doc));
+function hasCommandSurfaceForCommand(command, event) {
+    const entryMatches = event === 'command' ? commandEntryMatches : preCommandEntryMatches;
+    return resolvedDocs().some(({ doc }) => doc.surfaces.some((entry) => entryMatches(entry, command)));
+}
+/** Whether this command matches a `command` surface before its node-config
+ * gate is evaluated. A matching gate still requires a subject lookup. */
+export function corpusHasCommandSurfaceForCommand(command) {
+    return hasCommandSurfaceForCommand(command, 'command');
+}
+/** Whether this command matches a `pre-command` surface before its node-config
+ * gate is evaluated. A matching gate still requires a subject lookup. */
+export function corpusHasPreCommandSurfaceForCommand(command) {
+    return hasCommandSurfaceForCommand(command, 'pre-command');
 }
 /** Forget the transcript exposure of every `pre-command` doc, re-arming their
  * holds. Compaction drops delivered guidance out of the transcript while the

package/dist/core/substrate/surface-match.d.ts

@@ -18,13 +18,21 @@ export declare function matchesReadEntry(entry: SurfaceEntry, doc: Pick<Substrat
 /** Does a `memory-read` entry on a carrier anchored at `routingAnchor` fit a
  *  resolved read of the doc known by its exact canonical `name`? */
 export declare function matchesMemoryReadEntry(entry: SurfaceEntry, routingAnchor: string, subject: NodeConfigSubject | null, name: string): boolean;
+/** Does a `command` entry's parsed command pattern fit, without evaluating its
+ * node-config gate? Callers use this only to determine whether resolving a
+ * subject could be necessary; delivery must still use `matchesCommandEntry`. */
+export declare function commandEntryMatches(entry: SurfaceEntry, command: string): boolean;
 /** Does a `command` entry fit the executed command string? */
 export declare function matchesCommandEntry(entry: SurfaceEntry, subject: NodeConfigSubject | null, command: string): boolean;
+/** Does a `pre-command` entry's parsed command pattern fit, without evaluating
+ * its node-config gate? Callers use this only to determine whether resolving a
+ * subject could be necessary; delivery must still use `matchesPreCommandEntry`. */
+export declare function preCommandEntryMatches(entry: SurfaceEntry, command: string): boolean;
 /** Does a `pre-command` entry fit a command that is ABOUT to run? The same
- *  glob machinery `command` uses — one matcher, one semantics — applied to the
- *  command with its heredoc bodies stripped. Subshell parentheses, backticks,
- *  and path-prefixed binaries stay unhandled: this is a guardrail against the
- *  faithful-but-uninformed action, not an enforcement boundary. */
+ * glob machinery `command` uses — one matcher, one semantics — applied to the
+ * command with its heredoc bodies stripped. Subshell parentheses, backticks,
+ * and path-prefixed binaries stay unhandled: this is a guardrail against the
+ * faithful-but-uninformed action, not an enforcement boundary. */
 export declare function matchesPreCommandEntry(entry: SurfaceEntry, subject: NodeConfigSubject | null, command: string): boolean;
 /** What an event occurrence exposes for matching. A field the event does not
  *  use is ignored; a field the event needs and lacks matches nothing. */

package/dist/core/substrate/surface-match.js

@@ -157,22 +157,31 @@ function commandGlobMatches(glob, command) {
         .filter(({ tokens }) => tokens.length > 0)
         .some(({ tokens }) => segmentMatches(pattern, tokens));
 }
+/** Does a `command` entry's parsed command pattern fit, without evaluating its
+ * node-config gate? Callers use this only to determine whether resolving a
+ * subject could be necessary; delivery must still use `matchesCommandEntry`. */
+export function commandEntryMatches(entry, command) {
+    return entry.on === 'command' && entry.match !== undefined && entry.match.some((g) => commandGlobMatches(g, command));
+}
 /** Does a `command` entry fit the executed command string? */
 export function matchesCommandEntry(entry, subject, command) {
-    if (entry.on !== 'command' || entry.match === undefined || !surfaceEntryGatePasses(entry, subject))
+    return commandEntryMatches(entry, command) && surfaceEntryGatePasses(entry, subject);
+}
+/** Does a `pre-command` entry's parsed command pattern fit, without evaluating
+ * its node-config gate? Callers use this only to determine whether resolving a
+ * subject could be necessary; delivery must still use `matchesPreCommandEntry`. */
+export function preCommandEntryMatches(entry, command) {
+    if (entry.on !== 'pre-command' || entry.match === undefined)
         return false;
-    return entry.match.some((g) => commandGlobMatches(g, command));
+    return entry.match.some((g) => commandGlobMatches(g, stripHeredocs(command)));
 }
 /** Does a `pre-command` entry fit a command that is ABOUT to run? The same
- *  glob machinery `command` uses — one matcher, one semantics — applied to the
- *  command with its heredoc bodies stripped. Subshell parentheses, backticks,
- *  and path-prefixed binaries stay unhandled: this is a guardrail against the
- *  faithful-but-uninformed action, not an enforcement boundary. */
+ * glob machinery `command` uses — one matcher, one semantics — applied to the
+ * command with its heredoc bodies stripped. Subshell parentheses, backticks,
+ * and path-prefixed binaries stay unhandled: this is a guardrail against the
+ * faithful-but-uninformed action, not an enforcement boundary. */
 export function matchesPreCommandEntry(entry, subject, command) {
-    if (entry.on !== 'pre-command' || entry.match === undefined || !surfaceEntryGatePasses(entry, subject))
-        return false;
-    const stripped = stripHeredocs(command);
-    return entry.match.some((g) => commandGlobMatches(g, stripped));
+    return preCommandEntryMatches(entry, command) && surfaceEntryGatePasses(entry, subject);
 }
 /** Does ONE entry of `event` fit this occurrence — constraints and the entry's
  *  own gate together? */

package/dist/core/worktree-mutation-async.js

@@ -247,9 +247,8 @@ export async function abandonManagedWorktreeAsync(nodeId, by) {
                 cleanBase = base;
         }
         catch (error) {
-            if (!(error instanceof WorktreeError) || error.code !== 'missing_base_branch' || head !== current.base_sha)
+            if (!(error instanceof WorktreeError) || error.code !== 'missing_base_branch')
                 throw error;
-            cleanBase = current.base_sha;
         }
         const at = new Date().toISOString();
         const status = await runGit(current.path, ['status', '--porcelain'], 'status_failed', 'Inspect the worktree manually, then retry.');

package/dist/core/worktree.d.ts

@@ -76,7 +76,6 @@ export interface AbandonManagedWorktreeResult {
     worktree_path: string;
     branch_deleted: boolean;
 }
-export declare function abandonManagedWorktree(nodeId: string, by: string): AbandonManagedWorktreeResult;
 /** Recovery guidance for a vanished checkout whose refs do not prove that its
  * work is delivered. This deliberately never recommends `worktree close`:
  * that command cannot operate on the absent checkout. */