@north-light/crouter 0.3.301 → 0.3.303

package/dist/core/memory-resolver.d.ts

@@ -145,6 +145,8 @@ export interface MemoryResolutionOpts extends MemoryCandidateOpts {
      *  boot render, on-read resolvedDocs, the slash-command snapshot, and
      *  persona resolution, which stay on the flat ancestor+profile stack. */
     includeDescendants?: boolean;
+    /** Report when bounded descendant discovery omits an owner. Defaults to the inverse of `quiet`, so callers can preserve quiet malformed-document handling while still making an incomplete corpus visible to their caller. */
+    reportDiscovery?: boolean;
 }
 /** A loaded corpus and the exact-identity queries over it. */
 export interface MemoryView {
@@ -195,7 +197,7 @@ export declare function openProjectMemoryStore(ownerDir: string): MemoryStoreDes
 /** Every store a target sees, in precedence order: node, each project store
  *  nearest-first (its enabled plugins after it), then profile, user, builtin.
  *  One real store reached twice contributes once, at its first position. */
-export declare function memoryStoresInPrecedence(target: MemoryTarget, scope?: MemoryScope, includeDescendants?: boolean, quiet?: boolean): MemoryStoreDescriptor[];
+export declare function memoryStoresInPrecedence(target: MemoryTarget, scope?: MemoryScope, includeDescendants?: boolean, reportDiscovery?: boolean): MemoryStoreDescriptor[];
 /** The native (non-plugin) MOUNTED store dirs in resolution precedence.
  *  Addresses a store directly when the document itself may be absent, which is
  *  how a DELETED doc's revision log is still found: history outlives the doc,

package/dist/core/memory-resolver.js

@@ -193,7 +193,7 @@ export function openProjectMemoryStore(ownerDir) {
 /** Every store a target sees, in precedence order: node, each project store
  *  nearest-first (its enabled plugins after it), then profile, user, builtin.
  *  One real store reached twice contributes once, at its first position. */
-export function memoryStoresInPrecedence(target, scope, includeDescendants = false, quiet = false) {
+export function memoryStoresInPrecedence(target, scope, includeDescendants = false, reportDiscovery = true) {
     const out = [];
     const projectStores = (crtrRoot, projectMemory) => {
         out.push(projectStoreDescriptor(dirname(crtrRoot), join(crtrRoot, 'memory'), projectMemory));
@@ -211,7 +211,7 @@ export function memoryStoresInPrecedence(target, scope, includeDescendants = fal
             // nested one. They carry the neutral ceiling — no profile entry names
             // them, and descendant discovery is off for every automatic delivery path.
             if (includeDescendants) {
-                for (const root of descendantStoreRoots(annotated.map(({ root: r }) => r), quiet)) {
+                for (const root of descendantStoreRoots(annotated.map(({ root: r }) => r), reportDiscovery)) {
                     projectStores(root, NEUTRAL_PROJECT_MEMORY);
                 }
             }
@@ -438,7 +438,7 @@ function makeView(stores, docs, scope) {
  *  with its migration remedy and contributes nothing. */
 export function loadMemoryTargetView(target, opts = {}) {
     const quiet = opts.quiet ?? false;
-    const stores = memoryStoresInPrecedence(target, opts.scope, opts.includeDescendants ?? false, quiet);
+    const stores = memoryStoresInPrecedence(target, opts.scope, opts.includeDescendants ?? false, opts.reportDiscovery ?? !quiet);
     const docs = [];
     for (const store of stores) {
         if (store.mountStatus === 'absent')

package/dist/core/nested-stores.d.ts

@@ -9,7 +9,7 @@
  * excluding centrally gives the resolver and lint the identical call with no
  * duplicated dedupe logic.
  */
-export declare function descendantStoreRoots(ancestorRoots: string[], quiet?: boolean): string[];
+export declare function descendantStoreRoots(ancestorRoots: string[], reportBudgetExceeded?: boolean): string[];
 /** Complete descendant-store discovery for state migrations. Unlike the
  *  interactive addressing lane, this filesystem walk has no time or depth
  *  budget, crosses embedded repositories, admits plugin-only `.crouter` roots,

package/dist/core/nested-stores.js

@@ -39,7 +39,7 @@ const cache = new Map();
  * excluding centrally gives the resolver and lint the identical call with no
  * duplicated dedupe logic.
  */
-export function descendantStoreRoots(ancestorRoots, quiet = false) {
+export function descendantStoreRoots(ancestorRoots, reportBudgetExceeded = true) {
     const key = [...ancestorRoots].sort().join('\n');
     const cached = cache.get(key);
     if (cached !== undefined)
@@ -56,8 +56,8 @@ export function descendantStoreRoots(ancestorRoots, quiet = false) {
         owners.push(owner);
     }
     const tripBudget = (owner) => {
-        if (!quiet) {
-            warn(`memory: nested-store discovery under ${owner} exceeded its ${TIME_BUDGET_MS}ms budget — nested stores may be missing from this listing; register deep stores explicitly (add their dirs to the selected profile's projects)`);
+        if (reportBudgetExceeded) {
+            warn(`memory: nested-store discovery under ${owner} exceeded its ${TIME_BUDGET_MS}ms budget — this result may omit nested stores. To read a document from a known nested store, pass its owner as \`--dir <owner>\`; that exact-store read bypasses discovery.`);
         }
     };
     const found = [];

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

@@ -237,5 +237,5 @@ export function buildIdentityAssertion(nodeId, kind, mode, forkFrom, sourceLabel
 export function worktreeNote(worktree) {
     if (worktree?.state !== 'open')
         return '';
-    return `Branch: \`${worktree.branch}\`\nWorktree: \`${worktree.path}\`\nBase: \`${worktree.base_ref}\` @ \`${worktree.base_sha}\`\nCommit work here. Land it with \`crtr node worktree close\` before finishing. Auto-drop applies only when the worktree is clean (no uncommitted changes) and nothing remains to land (zero commits ahead of the base, or its commits are already contained in the base); unlanded commits (commits not already contained in the base) or uncommitted changes require an explicit close/landing decision.`;
+    return `Branch: \`${worktree.branch}\`\nWorktree: \`${worktree.path}\`\nBase: \`${worktree.base_ref}\` @ \`${worktree.base_sha}\`\nCommit work here. Before finishing, land it with \`crtr node worktree close\` or keep the checkout and branch when the worktree is clean and its exact tip exists on any branch on origin. Auto-drop applies only when the worktree is clean (no uncommitted changes) and nothing remains to land (zero commits ahead of the base, or its commits are already contained in the base); otherwise, unlanded commits or uncommitted changes block finalization.`;
 }

package/dist/core/runtime/broker/fault-retry.d.ts

@@ -25,6 +25,7 @@ export declare class FaultRetry {
     private readonly notFoundModels;
     private providerFallbackInFlight;
     private notFoundFallbackInFlight;
+    private stagedCapacityFailure;
     constructor(deps: FaultRetryDeps);
     clearTimer(): void;
     reset(): void;
@@ -54,6 +55,9 @@ export declare class FaultRetry {
     schedule(): void;
     private maybeSwitchProviderForRetry;
     private maybeFallbackOnUnusableModel;
+    private nextEligibleFallbackRoute;
+    private targetCannotFitContext;
+    private stageCapacityFailure;
     private recordPendingProviderFault;
     private sessionFile;
     private pendingEpisodeMatches;

package/dist/core/runtime/broker/fault-retry.js

@@ -22,6 +22,11 @@ export class FaultRetry {
     notFoundModels = new Set();
     providerFallbackInFlight = null;
     notFoundFallbackInFlight = null;
+    // A fallback can learn its target cannot hold this session before the
+    // current turn settles. Keep that outcome here rather than on the engine's
+    // agent_end staging field: message_end precedes agent_end, which resets that
+    // field for the ordinary provider result.
+    stagedCapacityFailure = null;
     constructor(deps) {
         this.deps = deps;
     }
@@ -35,6 +40,7 @@ export class FaultRetry {
         this.clearTimer();
         this.providerFallbackInFlight = null;
         this.notFoundFallbackInFlight = null;
+        this.stagedCapacityFailure = null;
     }
     onEvent(event) {
         this.maybeSwitchProviderForRetry(event);
@@ -54,6 +60,8 @@ export class FaultRetry {
         const watchdogAbort = generation.stagedWatchdogAbort;
         const refreshAbort = generation.stagedRefreshAbort;
         const overflowFailure = generation.stagedOverflowFailure;
+        const capacityFailure = this.stagedCapacityFailure?.generation === generation ? this.stagedCapacityFailure : null;
+        this.stagedCapacityFailure = null;
         generation.stagedProviderAgentEnd = null;
         generation.stagedWatchdogAbort = false;
         generation.stagedRefreshAbort = false;
@@ -76,12 +84,12 @@ export class FaultRetry {
             : { since: episodeFault.since, anchorEntryId: episodeFault.anchorEntryId, attempt: episodeFault.retry.attempt };
         const messages = Array.isArray(agentEnd?.messages) ? agentEnd.messages : [];
         const last = [...messages].reverse().find((message) => typeof message === 'object' && message !== null && message.role === 'assistant');
-        if (overflowFailure !== null) {
+        if (capacityFailure !== null || overflowFailure !== null) {
             clearFault(this.deps.nodeId, { link: 'pi→provider' });
             clearProviderRetryEpisode(this.deps.nodeId);
             recordFault(this.deps.nodeId, {
                 link: 'pi→provider', op: 'context overflow recovery', kind: 'context-overflow', retry: { disposition: 'fatal' },
-                message: overflowFailure.errorMessage, anchorEntryId: settledSession.sessionManager.getLeafId?.() ?? undefined,
+                message: capacityFailure?.errorMessage ?? overflowFailure.errorMessage, anchorEntryId: settledSession.sessionManager.getLeafId?.() ?? undefined,
             });
             return;
         }
@@ -250,9 +258,23 @@ export class FaultRetry {
         const routes = expandModelCandidates(routeRequest, envNodeCwd() ?? this.deps.cfg.cwd, envProfileId());
         const current = parseModelSpec(currentSpec);
         const liveRank = routes.find((candidate) => `${candidate.providerId}/${candidate.modelId}` === current.modelSpec && candidate.thinkingLevel === current.thinkingLevel)?.rank;
-        const nextRoute = liveRank === undefined ? undefined : routes.slice(liveRank + 1).find((candidate) => !this.failedRetryRoutes.has(candidate.routeId) && resolveProviderCandidates([{ ...candidate, ...probeRouteAvailability(candidate, this.deps.registryOf(candidateServices)), automaticFallback: true }]).candidates.length > 0);
-        if (nextRoute === undefined)
+        const fallback = liveRank === undefined
+            ? { route: undefined, capacityExhausted: false }
+            : this.nextEligibleFallbackRoute(routes.slice(liveRank + 1), this.deps.registryOf(candidateServices), candidateSession.getContextUsage()?.tokens, (candidate) => !this.failedRetryRoutes.has(candidate.routeId));
+        if (fallback.route === undefined) {
+            if (fallback.capacityExhausted) {
+                this.stageCapacityFailure(generation, candidateSession);
+                // Pi creates its retry AbortController immediately after it emits this
+                // event. Defer the abort so it cancels that controller, then lets the
+                // normal agent_settled path publish the staged fatal outcome.
+                queueMicrotask(() => {
+                    if (this.deps.installedGeneration() === generation && this.deps.currentSession() === candidateSession)
+                        candidateSession.abortRetry();
+                });
+            }
             return;
+        }
+        const nextRoute = fallback.route;
         const fallbackPromise = (async () => {
             const target = this.deps.registryOf(candidateServices).find(nextRoute.providerId, nextRoute.modelId);
             if (!target)
@@ -290,9 +312,15 @@ export class FaultRetry {
         const routeRequest = modelRequestFromConfig(this.deps.cfg.model, envModelIntent(), false);
         const routes = routeRequest ? expandModelCandidates(routeRequest, envNodeCwd() ?? this.deps.cfg.cwd, envProfileId()) : [];
         const liveRank = routes.find((candidate) => `${candidate.providerId}/${candidate.modelId}` === current.modelSpec && candidate.thinkingLevel === current.thinkingLevel)?.rank;
-        const nextRoute = liveRank === undefined ? undefined : routes.slice(liveRank + 1).find((candidate) => !this.notFoundModels.has(`${candidate.providerId}/${candidate.modelId}`) && resolveProviderCandidates([{ ...candidate, ...probeRouteAvailability(candidate, this.deps.registryOf(candidateServices)), automaticFallback: true }]).candidates.length > 0);
-        if (!nextRoute)
+        const fallback = liveRank === undefined
+            ? { route: undefined, capacityExhausted: false }
+            : this.nextEligibleFallbackRoute(routes.slice(liveRank + 1), this.deps.registryOf(candidateServices), candidateSession.getContextUsage()?.tokens, (candidate) => !this.notFoundModels.has(`${candidate.providerId}/${candidate.modelId}`));
+        if (fallback.route === undefined) {
+            if (fallback.capacityExhausted)
+                this.stageCapacityFailure(generation, candidateSession);
             return;
+        }
+        const nextRoute = fallback.route;
         const target = `${nextRoute.providerId}/${nextRoute.modelId}${nextRoute.thinkingLevel ? `:${nextRoute.thinkingLevel}` : ''}`;
         const fallbackPromise = (async () => {
             const model = this.deps.registryOf(candidateServices).find(nextRoute.providerId, nextRoute.modelId);
@@ -323,6 +351,38 @@ export class FaultRetry {
         });
         this.notFoundFallbackInFlight = fallbackPromise;
     }
+    nextEligibleFallbackRoute(routes, registry, contextTokens, include) {
+        let available = 0;
+        let tooSmall = 0;
+        for (const candidate of routes) {
+            if (!include(candidate))
+                continue;
+            if (resolveProviderCandidates([{ ...candidate, ...probeRouteAvailability(candidate, registry), automaticFallback: true }]).candidates.length === 0)
+                continue;
+            const target = registry.find(candidate.providerId, candidate.modelId);
+            if (target === undefined)
+                continue;
+            available++;
+            if (this.targetCannotFitContext(target.contextWindow, contextTokens)) {
+                tooSmall++;
+                continue;
+            }
+            return { route: candidate, capacityExhausted: false };
+        }
+        return { route: undefined, capacityExhausted: available > 0 && available === tooSmall };
+    }
+    targetCannotFitContext(contextWindow, contextTokens) {
+        return Number.isFinite(contextWindow) && Number.isFinite(contextTokens) && contextWindow < contextTokens;
+    }
+    stageCapacityFailure(generation, session) {
+        const tokens = session.getContextUsage()?.tokens;
+        this.stagedCapacityFailure = {
+            generation,
+            errorMessage: Number.isFinite(tokens)
+                ? `All available fallback models have context windows smaller than the current conversation (${tokens} tokens).`
+                : 'All available fallback models have context windows smaller than the current conversation.',
+        };
+    }
     recordPendingProviderFault(session, input) {
         const sessionFile = this.sessionFile(session);
         // A pathless session cannot be crash-recovered, but its live broker still

package/dist/core/runtime/close.js

@@ -2,9 +2,11 @@
 //
 // Closing a node tears down the focused node and every descendant it
 // EXCLUSIVELY owns, walking DOWN the subscribes_to spine (subscriptionsOf = a
-// node's reports/children). Nothing is deleted: pi_session_id, the canvas
-// edges, and all on-disk state persist, so any closed node can later be revived
-// (`crtr node lifecycle revive` / focus → `pi --session <id>`). A close is a pause, not a reap.
+// node's reports/children). A node that never produced substantive assistant
+// output is reaped and cannot be revived. Streaming nodes and nodes with an open
+// managed worktree are retained; other closed nodes keep their pi session,
+// canvas edges, and on-disk state for a later revive (`crtr node lifecycle
+// revive` / focus → `pi --session <id>`).
 //
 // Per node, in this order — the order matters twice:
 //
@@ -171,9 +173,9 @@ export function closeNode(rootId, opts = {}) {
             // Surviving managers captured BEFORE any teardown — a reap (below) deletes
             //    this node's edges, so the step-4 fan-out must read them up front.
             const survivors = subscribersOf(id).filter((s) => !closing.has(s.node_id));
-            // 0) An EMPTY node (engine never produced an assistant message) is a useless
-            //    shell — don't park it as a canceled husk, reap it outright (engine +
-            //    viewer + row + dir). reapIfEmpty handles the teardown; when it fires we
+            // 0) A node with no substantive assistant output is a useless shell — don't
+            //    park it as a canceled husk; reap it outright (engine + viewer + row +
+            //    dir). reapIfEmpty handles the teardown; when it fires we
             //    skip the cancel transition + resume notice (the node is gone) but still
             //    fan the "child gone" wake out to surviving managers below.
             if (!reapIfEmpty(id)) {

package/dist/core/runtime/stop-guard.js

@@ -23,7 +23,7 @@
 //                      manual cleanup.
 //   • otherwise      → a TERMINAL node with nothing live to wait for and no
 //                      final pushed. Re-prompt it to finish or escalate.
-import { hasActiveLiveSubscription, hasLiveMessageWait, hasPendingCancelOnWakeCron, getNode, contextDir } from '../canvas/index.js';
+import { hasActiveLiveSubscription, hasLiveMessageWait, hasPendingCronWake, getNode, contextDir } from '../canvas/index.js';
 import { activeBackgroundBashJobs } from '../bash-jobs.js';
 import { formatCard, formatStructuredOutputReprompt, STALL_REPROMPT } from '../../shared/generated-context.js';
 import { readOutputRequest } from './structured-output.js';
@@ -41,12 +41,12 @@ function formatInvalidStructuredOutputReprompt(error) {
         `After resolving the file, retry with \`crtr push result\` (or \`crtr push result --decline "<reason>" --code <token>\` when the schema cannot be honestly satisfied). ` +
         `If this is unexpected, escalate to the user using \`crtr human send\`.`);
 }
-/** The wake sources that legitimize a terminal node's dormancy: a pending
- * cancel-on-wake deadline, an active subscription to a live publisher, an
- * explicit live controller wait, or a live background bash job whose completion
- * sends an inbox message. Parentage alone is deliberately absent. */
+/** The wake sources that legitimize a terminal node's dormancy: a pending cron
+ * wake, an active subscription to a live publisher, an explicit live controller
+ * wait, or a live background bash job whose completion sends an inbox message.
+ * Parentage alone is deliberately absent. */
 function wakeCapableWait(nodeId, backgroundJobsRunning) {
-    if (hasPendingCancelOnWakeCron(nodeId))
+    if (hasPendingCronWake(nodeId))
         return 'scheduled';
     if (hasActiveLiveSubscription(nodeId)
         || hasLiveMessageWait(nodeId)

package/dist/core/shell-segments.d.ts

@@ -0,0 +1,42 @@
+/** One shell word. `opaque` marks a token whose text came from inside quotes:
+ *  it is data, so it must never be treated as an executable or a matched
+ *  command word. */
+export type CommandToken = {
+    text: string;
+    opaque: boolean;
+};
+/** One shell segment: the raw text as the author wrote it, its leading
+ *  `VAR=value` assignments, and the remaining words — so `tokens[0]` is the
+ *  executable. An assignment-only segment (`export`-less `FOO=bar`) has
+ *  assignments and no tokens; the distinction matters, because a leading
+ *  assignment applies ONLY to the command in its own segment.
+ *
+ *  `background` marks a segment ended by a single `&`. It runs in a subshell,
+ *  so nothing it assigns or `cd`s reaches the commands after it. */
+export type CommandSegment = {
+    text: string;
+    assignments: string[];
+    tokens: CommandToken[];
+    background: boolean;
+};
+/** One raw segment and whether a single `&` — not `&&` — ended it. */
+export type RawSegment = {
+    text: string;
+    background: boolean;
+};
+/** Split a command into shell segments on unquoted `;`, newline, `&&`, `||`,
+ *  `|`, and a single `&`. Subshell parentheses and backticks are left inside
+ *  their segment. Heredoc bodies are a separate pre-read concern (see
+ *  `stripHeredocs`). */
+export declare function splitCommandSegments(command: string): RawSegment[];
+/** Tokenize one segment into shell words, marking quoted spans opaque. */
+export declare function tokenizeCommandSegment(segment: string): CommandToken[];
+/** Every non-empty command segment, paired with its raw text. */
+export declare function commandSegments(command: string): CommandSegment[];
+/** Remove heredoc BODIES (the stdin data between `<<DELIM` and its closing
+ *  `DELIM` line) from a command before it is read. The opening line is kept —
+ *  `crtr push final <<'EOF'` is still a real `push final` invocation — but the
+ *  body lines, which are data fed on stdin and never executed as commands, are
+ *  dropped. Without this, a doc-writing command whose body merely MENTIONS a
+ *  matched invocation would have its whole call held or refused. */
+export declare function stripHeredocs(command: string): string;

package/dist/core/shell-segments.js

@@ -0,0 +1,169 @@
+// shell-segments.ts — best-effort shell text reading, shared by everything in
+// crtr that has to reason about a command string it did not execute: the doc
+// substrate's `command`/`pre-command` surface matching and the bash valve's
+// refusals. Pure text in, structure out; no execution, no expansion.
+//
+// This is deliberately NOT a shell parser. Subshells, backticks, process
+// substitution, and path-prefixed binaries stay unhandled. Every caller must
+// treat a miss as "this text did not obviously do X", never as "this text
+// cannot do X".
+/** Split a command into shell segments on unquoted `;`, newline, `&&`, `||`,
+ *  `|`, and a single `&`. Subshell parentheses and backticks are left inside
+ *  their segment. Heredoc bodies are a separate pre-read concern (see
+ *  `stripHeredocs`). */
+export function splitCommandSegments(command) {
+    const segments = [];
+    let current = '';
+    let quote = null;
+    let escaped = false;
+    const finish = (background = false) => {
+        segments.push({ text: current, background });
+        current = '';
+    };
+    for (let i = 0; i < command.length; i += 1) {
+        const ch = command[i];
+        if (escaped) {
+            current += ch;
+            escaped = false;
+            continue;
+        }
+        if (ch === '\\' && quote !== "'") {
+            current += ch;
+            escaped = true;
+            continue;
+        }
+        if (quote !== null) {
+            current += ch;
+            if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === "'" || ch === '"') {
+            current += ch;
+            quote = ch;
+            continue;
+        }
+        if (ch === '\n' || ch === ';') {
+            finish();
+            continue;
+        }
+        if ((ch === '&' || ch === '|') && command[i + 1] === ch) {
+            finish();
+            i += 1;
+            continue;
+        }
+        if (ch === '|') {
+            finish();
+            continue;
+        }
+        if (ch === '&') {
+            finish(true);
+            continue;
+        }
+        current += ch;
+    }
+    finish();
+    return segments;
+}
+/** Tokenize one segment into shell words, marking quoted spans opaque. */
+export function tokenizeCommandSegment(segment) {
+    const tokens = [];
+    let text = '';
+    let opaque = false;
+    let started = false;
+    let quote = null;
+    let escaped = false;
+    const finish = () => {
+        if (started)
+            tokens.push({ text, opaque });
+        text = '';
+        opaque = false;
+        started = false;
+    };
+    for (let i = 0; i < segment.length; i += 1) {
+        const ch = segment[i];
+        if (escaped) {
+            text += ch;
+            started = true;
+            escaped = false;
+            continue;
+        }
+        if (ch === '\\' && quote !== "'") {
+            escaped = true;
+            started = true;
+            continue;
+        }
+        if (quote !== null) {
+            started = true;
+            if (ch === quote) {
+                quote = null;
+            }
+            else {
+                text += ch;
+            }
+            continue;
+        }
+        if (ch === "'" || ch === '"') {
+            quote = ch;
+            opaque = true;
+            started = true;
+            continue;
+        }
+        if (/\s/.test(ch)) {
+            finish();
+            continue;
+        }
+        text += ch;
+        started = true;
+    }
+    if (escaped)
+        text += '\\';
+    finish();
+    return tokens;
+}
+/** Every non-empty command segment, paired with its raw text. */
+export function commandSegments(command) {
+    return splitCommandSegments(command)
+        .map(({ text, background }) => {
+        const tokens = tokenizeCommandSegment(text);
+        let first = 0;
+        while (first < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[first].text))
+            first += 1;
+        return { text: text.trim(), assignments: tokens.slice(0, first).map((t) => t.text), tokens: tokens.slice(first), background };
+    })
+        .filter((segment) => segment.assignments.length > 0 || segment.tokens.length > 0);
+}
+const HEREDOC_OPEN = /<<(-?)\s*(["']?)([A-Za-z_][A-Za-z0-9_]*)\2/g;
+/** Remove heredoc BODIES (the stdin data between `<<DELIM` and its closing
+ *  `DELIM` line) from a command before it is read. The opening line is kept —
+ *  `crtr push final <<'EOF'` is still a real `push final` invocation — but the
+ *  body lines, which are data fed on stdin and never executed as commands, are
+ *  dropped. Without this, a doc-writing command whose body merely MENTIONS a
+ *  matched invocation would have its whole call held or refused. */
+export function stripHeredocs(command) {
+    const lines = command.split('\n');
+    const out = [];
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        out.push(line);
+        i += 1;
+        // Every heredoc opened on this line, left to right; their bodies stack and
+        // are consumed in that order.
+        const delims = [];
+        HEREDOC_OPEN.lastIndex = 0;
+        let m;
+        while ((m = HEREDOC_OPEN.exec(line)) !== null)
+            delims.push({ name: m[3], dash: m[1] === '-' });
+        for (const d of delims) {
+            while (i < lines.length) {
+                // `<<-` strips leading TABS from the body and the closing delimiter.
+                const probe = d.dash ? lines[i].replace(/^\t+/, '') : lines[i];
+                i += 1;
+                if (probe === d.name)
+                    break; // closing delimiter line — drop it, stop
+            }
+        }
+    }
+    return out.join('\n');
+}

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

@@ -20,15 +20,6 @@ export declare function matchesReadEntry(entry: SurfaceEntry, doc: Pick<Substrat
 export declare function matchesMemoryReadEntry(entry: SurfaceEntry, routingAnchor: string, subject: NodeConfigSubject | null, name: string): boolean;
 /** Does a `command` entry fit the executed command string? */
 export declare function matchesCommandEntry(entry: SurfaceEntry, subject: NodeConfigSubject | null, command: string): boolean;
-/** Remove heredoc BODIES (the stdin data between `<<DELIM` and its closing
- *  `DELIM` line) from a command before it is matched. The opening line is kept
- *  — `crtr push final <<'EOF'` is still a real `push final` invocation — but the
- *  body lines, which are data fed on stdin and never executed as commands, are
- *  dropped. Without this a doc-writing command whose body merely MENTIONS a
- *  matched invocation would have its whole call held. Post-execution `command`
- *  delivery does not need this (a spurious late injection costs a paragraph);
- *  a `pre-command` block costs the agent a turn, so it does. */
-export declare function stripHeredocs(command: string): string;
 /** 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,