@north-light/crouter 0.3.231 → 0.3.233

package/dist/core/runtime/spawn.js

@@ -12,7 +12,7 @@
 import { accessSync, constants, cpSync, readdirSync, existsSync, rmSync } from 'node:fs';
 import { isAbsolute, resolve, join } from 'node:path';
 import { spawnNode, currentNodeContext, rootOfSpine, newNodeId, preflightNodeId } from './nodes.js';
-import { loadProfileManifest } from '../profiles/manifest.js';
+import { resolveProfileOperand } from '../profiles/manifest.js';
 import { selectProfileForCwd, selectProfileForCwdReadOnly } from '../profiles/select.js';
 import { buildLaunchSpecAsync, buildPiArgv } from './launch.js';
 import { createManagedWorktree, rollbackManagedWorktree } from '../worktree.js';
@@ -23,7 +23,7 @@ import { hasRoadmap, seedRoadmap } from './roadmap.js';
 import { buildWakeBearings } from './bearings.js';
 import { canonicalSessionFile, contextDir, findNodeBySessionFile, getNode, fullName, recordPid } from '../canvas/index.js';
 import { jobDir } from '../canvas/paths.js';
-import { openViewerWindow, focusOf, windowOfPane, currentTmux, focusWindow, } from './placement.js';
+import { openViewerWindow, focusOf, windowOfPane, } from './placement.js';
 import { waitForBrokerViewSocket } from './placement-tmux.js';
 import { transition } from './lifecycle.js';
 import { beginBootFaultAttempt } from './fault.js';
@@ -33,6 +33,7 @@ import { ensureDaemon } from '../../daemon/manage.js';
 import { readConfig } from '../config.js';
 import { modelRequestFromConfig, unregisteredConcreteModel } from '../model-routes.js';
 import { openModelRegistry } from './model-registry.js';
+import { MODEL_SPEC_NEXT } from './model-selection.js';
 import { initializeForkContextExposure } from '../substrate/injected-store.js';
 // ---------------------------------------------------------------------------
 // Shared broker-launch wrapper — catch launch/preflight failures at the call
@@ -147,7 +148,7 @@ export function resolveForkSource(value) {
     return resolveSessionUuid(v);
 }
 /** Resolve the profile a spawned child runs under: an explicit `--profile`
- *  operand (id or name) validated through `loadProfileManifest`, else INHERIT
+ *  operand (id, name, or closest match) resolved through `resolveProfileOperand`, else INHERIT
  *  the spawner's current `profile_id` (null when the spawner has none). `--root`
  *  never resets this to null on its own; only an explicit override does. When
  *  there is NO spawner at all — `crtr node new --root` run directly from a
@@ -158,7 +159,10 @@ export async function resolveProfileId(explicit, spawner, cwd, options = {}) {
     if (explicit === null)
         return null;
     if (explicit !== undefined && explicit !== '') {
-        return loadProfileManifest(explicit).profileId;
+        // `explicit` originates as a user-typed `--profile`, so tolerate a near
+        // miss. The CLI normally resolves it to an id first; this covers callers
+        // that reach the daemon with a name.
+        return resolveProfileOperand(explicit).profileId;
     }
     if (spawner !== null)
         return getNode(spawner)?.profile_id ?? null;
@@ -183,7 +187,7 @@ export async function assertLaunchModelRegistered(request, options, registry) {
         return;
     throw usage(`model '${unknown.request.spec}' is not registered in this daemon.`, {
         received: unknown.request.spec,
-        next: 'Pass a registered provider/id, provider/tier where provider is anthropic|openai and tier is ultra|strong|medium|light, a bare tier (ultra|strong|medium|light), or a family alias (opus|sonnet|haiku).',
+        next: MODEL_SPEC_NEXT,
     });
 }
 /** Resolve who a spawn is attributed to. A managed child needs a spine parent
@@ -272,6 +276,7 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
             lifecycle,
             cwd: spawnCwd,
             name: opts.name ?? opts.kind,
+            description: opts.description,
             // A root has no spine parent (top-level, nobody subscribes); it still
             // records spawned_by=spawner when a node (not a human shell) spawned it.
             // A child's parent IS its manager.
@@ -331,11 +336,6 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
         }
         // (The three scoped long-term memory stores are seeded for EVERY node at birth
         // in spawnNode — no orchestrator-gated seeding needed here.)
-        // An ATTENDED --root spawned from inside tmux opens its foreground viewer
-        // in the CALLER'S CURRENT session (below), so it appears where the spawner is
-        // working; a managed child is a headless broker with NO viewer at all, and
-        // so is an unattended terminal root (nobody asked to watch it).
-        const here = attendedRoot ? currentTmux() : null;
         const inv = buildPiArgv(meta, { prompt: kickoff, forkFrom });
         // CRTR_SUBTREE (the spine root) rides the detached broker's env so it can group
         // the subtree; the host sets CRTR_FRONT_DOOR itself.
@@ -377,30 +377,16 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
                 ? 'Resolve the cause named above, then retry.'
                 : `The broker engine exited before binding its view socket. Inspect ${jobDir(meta.node_id)}/broker.log for the underlying cause (a missing dependency, model auth, or a crash), then retry.`);
         }
-        // An ATTENDED --root is spawned to be DRIVEN directly: when the caller is
-        // inside tmux, open ONE foreground viewer in the caller's CURRENT session and
-        // bring it forefront so whoever asked for it picks up the conversation.
-        // Outside tmux a --root opens no viewer (an agent handing a root off); an
-        // UNATTENDED terminal root (rootLifecycle: 'terminal') opens none anywhere —
-        // stealing focus for machinery nobody is watching is the bug, not the
-        // feature. A managed child opens nothing. Viewer placement remains non-fatal
-        // after the readiness proof.
+        // A --root opens NO viewer from here. spawnChild runs daemon-side only, and
+        // the daemon is paneless by construction (manage.ts strips TMUX/TMUX_PANE
+        // from its env precisely so this code cannot resolve someone else's pane),
+        // so a root's foreground viewer is placed by whoever asked for it — the
+        // front door, or `node new`'s own openSpawnViewer in the CLI process. Only a
+        // managed child is placed here, and placement stays non-fatal after the
+        // readiness proof.
         let window = null;
         let session = null;
-        if (attendedRoot && here !== null) {
-            const viewer = openViewerWindow(meta.node_id, here.session, { name: fullName(meta), cwd: opts.cwd });
-            if (viewer !== null && viewer.pane !== null && viewer.pane !== '') {
-                session = here.session;
-                window = windowOfPane(viewer.pane);
-                if (window !== null) {
-                    try {
-                        focusWindow(here.session, window);
-                    }
-                    catch { /* best-effort */ }
-                }
-            }
-        }
-        else if (!root && spawner !== null && readConfig('user').auto_open_child_viewers) {
+        if (!root && spawner !== null && readConfig('user').auto_open_child_viewers) {
             // When enabled, a managed child opens beside a HUMAN actively watching
             // its spawner. Turning the setting off leaves every child headless until
             // someone explicitly focuses or attaches it. The broker is headless

package/dist/core/runtime/structured-output.d.ts

@@ -13,6 +13,12 @@ export type StructuredOutputState = {
     state: 'invalid';
     error: string;
 };
+/** The `--output-schema` transport clause, rendered verbatim by every leaf that
+ *  accepts one. Declared once so the call sites cannot drift apart. */
+export declare const OUTPUT_SCHEMA_TRANSPORT = "A .json file path, or inline JSON beginning with `{`.";
+/** Provider-constrained generation supports the structural subset below; every
+ *  other schema keyword remains model-visible and is checked after generation. */
+export declare const OUTPUT_SCHEMA_CONSTRAINTS = "Generation is constrained by structure alone \u2014 type, properties, required, items, anyOf, and the standard string formats; every other keyword (enum, pattern, minLength, numeric bounds) reaches the model as description text and is checked only after it answers, so an over-constrained schema costs retries.";
 export declare function outputSchemaPath(nodeId: string): string;
 export declare function outputResultPath(nodeId: string): string;
 export declare function parseOutputSchemaValue(value: string | undefined): Record<string, unknown> | null;

package/dist/core/runtime/structured-output.js

@@ -4,6 +4,12 @@ import { randomUUID } from 'node:crypto';
 import { nodeDir, contextDir } from '../canvas/paths.js';
 import { InputError } from '../io.js';
 import { isRecord } from '../../shared/predicates.js';
+/** The `--output-schema` transport clause, rendered verbatim by every leaf that
+ *  accepts one. Declared once so the call sites cannot drift apart. */
+export const OUTPUT_SCHEMA_TRANSPORT = 'A .json file path, or inline JSON beginning with `{`.';
+/** Provider-constrained generation supports the structural subset below; every
+ *  other schema keyword remains model-visible and is checked after generation. */
+export const OUTPUT_SCHEMA_CONSTRAINTS = 'Generation is constrained by structure alone — type, properties, required, items, anyOf, and the standard string formats; every other keyword (enum, pattern, minLength, numeric bounds) reaches the model as description text and is checked only after it answers, so an over-constrained schema costs retries.';
 export function outputSchemaPath(nodeId) {
     return `${nodeDir(nodeId)}/output-schema.json`;
 }

package/dist/core/substrate/__tests__/surface-match-command.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/substrate/__tests__/surface-match-command.test.js

@@ -0,0 +1,89 @@
+// Deliberate, user-approved exception to crouter's standing policy of not using unit tests: glob matching is pure string logic with a large space of near-miss inputs, where a table of real cases is the only economical way to pin behavior, and where BOTH false negatives and false positives are defects.
+//
+// Run: node --conditions=crtr-src --import tsx/esm --test src/core/substrate/__tests__/surface-match-command.test.ts
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { commandDeliveryRung, matchesCommandEntry } from '../surface-match.js';
+const subject = {
+    kind: 'developer',
+    mode: 'base',
+    lifecycle: 'terminal',
+    hasManager: false,
+    cwd: '/tmp/project',
+    scope: 'project',
+    orchestration: { depth: 0 },
+    profile: null,
+};
+function entry(match, on = 'command', at = 'preview') {
+    return { on, at, match };
+}
+test('real command globs match the direct invocation they describe', () => {
+    const cases = [
+        { name: 'linear issues', glob: 'linear *', command: 'linear issues list', expected: true },
+        { name: 'capture screenshot', glob: '*capture *', command: 'capture screenshot --url https://example.com', expected: true },
+        { name: 'grove status', glob: '*grove*', command: 'grove status', expected: true },
+        { name: 'crtr human send', glob: '*crtr human *', command: 'crtr human send --message "Approve this change"', expected: true },
+        { name: 'git commit', glob: '*git commit*', command: 'git commit -m "ship fix"', expected: true },
+        { name: 'git push', glob: '*git push*', command: 'git push origin main', expected: true },
+        { name: 'npm publish', glob: '*npm publish*', command: 'npm publish --access public', expected: true },
+        { name: 'pnpm publish', glob: '*pnpm publish*', command: 'pnpm publish --access public', expected: true },
+        { name: 'termrender doc check', glob: '*termrender*', command: 'termrender doc check ./README.md', expected: true },
+        { name: 'single-character question mark', glob: '*git p?sh*', command: 'git push origin main', expected: true },
+        { name: 'trailing star permits bare tool', glob: 'linear *', command: 'linear', expected: true },
+        { name: 'literal glob is an exact command', glob: 'git status', command: 'git status', expected: true },
+        { name: 'literal glob does not imply arguments', glob: 'git status', command: 'git status --short', expected: false },
+    ];
+    for (const testCase of cases) {
+        assert.equal(matchesCommandEntry(entry([testCase.glob]), subject, testCase.command), testCase.expected, testCase.name);
+    }
+});
+test('a command is found after ordinary shell composition and whitespace variation', () => {
+    const cases = [
+        { name: 'after directory change', glob: 'linear *', command: 'cd apps/core && linear issues list', expected: true },
+        { name: 'after semicolon', glob: '*grove*', command: 'printf ready; grove status', expected: true },
+        { name: 'after or-list', glob: '*crtr human *', command: 'test -f answer.txt || crtr human send --message "Choose one"', expected: true },
+        { name: 'leading environment assignment', glob: 'linear *', command: 'CI=1 linear issues list', expected: true },
+        { name: 'tool inside a pipeline', glob: '*termrender*', command: 'termrender doc check README.md | grep -q error', expected: true },
+        { name: 'tool on the right side of a pipe', glob: '*termrender*', command: 'cat README.md | termrender', expected: true },
+        { name: 'two spaces between tokens', glob: 'linear *', command: 'linear  issues list', expected: true },
+        { name: 'tab between tokens', glob: 'linear *', command: 'linear\tissues list', expected: true },
+        { name: 'trailing newline', glob: 'linear *', command: 'linear issues list\n', expected: true },
+    ];
+    for (const testCase of cases) {
+        assert.equal(matchesCommandEntry(entry([testCase.glob]), subject, testCase.command), testCase.expected, testCase.name);
+    }
+});
+test('command text and token near-misses do not wake a surface', () => {
+    const cases = [
+        { name: 'linear only appears in quoted text', glob: 'linear *', command: 'echo "linear issues list"', expected: false },
+        { name: 'capture only appears in quoted text', glob: '*capture *', command: 'echo "capture screenshot"', expected: false },
+        { name: 'git push only appears in a commit message', glob: '*git push*', command: 'git commit -m "please git push later"', expected: false },
+        { name: 'grove is part of a longer word', glob: '*grove*', command: 'echo grover', expected: false },
+        { name: 'capture is part of a longer word', glob: '*capture *', command: 'printf "%s\\n" mycapture', expected: false },
+        { name: 'linear is part of a filename', glob: 'linear *', command: 'python linear-regression.py', expected: false },
+        { name: 'git commit is a sibling subcommand', glob: '*git commit*', command: 'git commit-tree -m "ship fix"', expected: false },
+        { name: 'termrender only appears in quoted text', glob: '*termrender*', command: 'echo "termrender"', expected: false },
+        // A path mention is not an invocation: an unrelated listing should not wake the grove doc.
+        { name: 'grove only appears in an unrelated path', glob: '*grove*', command: 'ls /tmp/grove/config', expected: false },
+    ];
+    for (const testCase of cases) {
+        assert.equal(matchesCommandEntry(entry([testCase.glob]), subject, testCase.command), testCase.expected, testCase.name);
+    }
+});
+test('entry and match-list composition stays within the command event', () => {
+    const anyGlobCases = [
+        { name: 'second glob satisfies the list', globs: ['*npm publish*', '*pnpm publish*'], command: 'pnpm publish --access public', expected: true },
+        { name: 'no glob satisfies the list', globs: ['*npm publish*', '*pnpm publish*'], command: 'yarn publish', expected: false },
+    ];
+    for (const testCase of anyGlobCases) {
+        assert.equal(matchesCommandEntry(entry(testCase.globs), subject, testCase.command), testCase.expected, testCase.name);
+    }
+    assert.equal(commandDeliveryRung({ surfaces: [entry(['*npm publish*'], 'command', 'name'), entry(['*pnpm publish*'], 'command', 'content')] }, subject, 'pnpm publish --access public'), 'content', 'matching command entries OR together and retain the highest matching rung');
+    const otherEventCases = [
+        { name: 'read entry never fires for a command', on: 'read' },
+        { name: 'memory-read entry never fires for a command', on: 'memory-read' },
+    ];
+    for (const testCase of otherEventCases) {
+        assert.equal(matchesCommandEntry(entry(['linear *'], testCase.on), subject, 'linear issues list'), false, testCase.name);
+    }
+});

package/dist/core/substrate/__tests__/surface-match-pre-command.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/substrate/__tests__/surface-match-pre-command.test.js

@@ -0,0 +1,92 @@
+// Regression: `pre-command` matching holds a command BEFORE it runs, so it
+// costs the agent a whole turn when it fires. Two ways it can be wrong:
+//
+//   • It fires on a mention rather than an invocation. A doc-writing command
+//     whose heredoc body merely quotes a matched invocation must run untouched
+//     — only the heredoc's opening line is a real command.
+//   • It ignores the entry's own `gate`. A doc whose entry excludes this node
+//     must never hold that node's commands.
+//
+// It also pins the shared-routing invariant: the pre-command matcher is the
+// post-execution `command` matcher plus heredoc stripping, and nothing else.
+// One command-glob semantics, not two.
+//
+// Run: node --conditions=crtr-src --import tsx/esm --test src/core/substrate/__tests__/surface-match-pre-command.test.ts
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { matchesCommandEntry, matchesPreCommandEntry, preCommandDeliveryRung } from '../surface-match.js';
+const SUBJECT = {
+    kind: 'developer',
+    mode: 'base',
+    lifecycle: 'terminal',
+    hasManager: true,
+    cwd: '/tmp/project',
+    scope: 'project',
+    orchestration: { depth: 1 },
+    profile: 'northlight',
+};
+function entry(match, gate) {
+    return { on: 'pre-command', at: 'content', match, ...(gate !== undefined ? { gate } : {}) };
+}
+// --- the behaviour this event adds -----------------------------------------
+test('a matched invocation inside a heredoc BODY does not hold the command', () => {
+    const command = [
+        "crtr memory write approvals --body <<'EOF'",
+        'Before you run `crtr integration run --action send`, get approval.',
+        'EOF',
+    ].join('\n');
+    assert.equal(matchesPreCommandEntry(entry(['crtr integration run*']), SUBJECT, command), false);
+});
+test('the same invocation on the heredoc OPENING line still holds the command', () => {
+    const command = ["crtr integration run --action send --body <<'EOF'", 'hello', 'EOF'].join('\n');
+    assert.equal(matchesPreCommandEntry(entry(['crtr integration run*']), SUBJECT, command), true);
+});
+test('a `<<-` heredoc body is stripped too, tabs and all', () => {
+    const command = ['cat <<-EOF', '\tcrtr integration run --action send', '\tEOF'].join('\n');
+    assert.equal(matchesPreCommandEntry(entry(['crtr integration run*']), SUBJECT, command), false);
+});
+test('an unterminated heredoc drops its body rather than leaking it back in', () => {
+    const command = ["crtr memory write d --body <<'EOF'", 'crtr integration run --action send'].join('\n');
+    assert.equal(matchesPreCommandEntry(entry(['crtr integration run*']), SUBJECT, command), false);
+});
+test('an entry whose gate excludes the subject never holds a command', () => {
+    const excluded = entry(['crtr integration run*'], { lifecycle: 'resident' });
+    assert.equal(matchesPreCommandEntry(excluded, SUBJECT, 'crtr integration run --action send'), false);
+    const included = entry(['crtr integration run*'], { lifecycle: 'terminal' });
+    assert.equal(matchesPreCommandEntry(included, SUBJECT, 'crtr integration run --action send'), true);
+});
+test('a `command` entry is never consumed by the pre-command matcher, nor the reverse', () => {
+    const post = { on: 'command', at: 'content', match: ['crtr integration run*'] };
+    assert.equal(matchesPreCommandEntry(post, SUBJECT, 'crtr integration run --action send'), false);
+    assert.equal(matchesCommandEntry(entry(['crtr integration run*']), SUBJECT, 'crtr integration run --action send'), false);
+});
+// --- the rung fold ---------------------------------------------------------
+test('the rung fold returns the highest `at` across matching entries, and none when nothing matches', () => {
+    const doc = {
+        surfaces: [
+            entry(['crtr crustdata person search*']),
+            entry(['crtr integration run*']),
+            { on: 'command', at: 'content', match: ['*'] },
+        ],
+    };
+    assert.equal(preCommandDeliveryRung(doc, SUBJECT, 'crtr integration run --action send'), 'content');
+    assert.equal(preCommandDeliveryRung(doc, SUBJECT, 'ls -la'), 'none');
+});
+// --- shared routing: one command-glob semantics, not two --------------------
+test('outside a heredoc, pre-command matching is exactly the `command` matcher', () => {
+    // The guard against a second command tokenizer drifting away from the first.
+    // Whatever `command` globs mean today, `pre-command` means the same thing —
+    // so a sharpening of command-position matching reaches both events at once.
+    const glob = 'crtr integration run*';
+    for (const command of [
+        'crtr integration run --action send',
+        'cd /tmp && crtr integration run --action send',
+        'echo hi\ncrtr integration run --action send',
+        'NL_ENV=1 crtr integration run --action send',
+        'crtr integration list',
+        'ls -la',
+        'echo "crtr integration run --action send"',
+    ]) {
+        assert.equal(matchesPreCommandEntry(entry([glob]), SUBJECT, command), matchesCommandEntry({ on: 'command', at: 'content', match: [glob] }, SUBJECT, command), `pre-command and command disagreed on: ${JSON.stringify(command)}`);
+    }
+});

package/dist/core/substrate/frontmatter-validation.js

@@ -47,7 +47,7 @@ export function lintSubstrateSurfaces(value) {
                 return `invalid surfaces entry \`match-frontmatter\`: ${JSON.stringify(matchFrontmatter)} (expected a field→matcher object)`;
             }
         }
-        if ((on === 'read' || on === 'memory-read' || on === 'command') && !hasMatch && matchFrontmatter === undefined) {
+        if ((on === 'read' || on === 'memory-read' || on === 'command' || on === 'pre-command') && !hasMatch && matchFrontmatter === undefined) {
             return `invalid surfaces entry: a \`${on}\` entry requires \`match\`${on === 'read' ? ' or `match-frontmatter`' : ''}`;
         }
         const gate = entry['gate'];

package/dist/core/substrate/injected-store.d.ts

@@ -24,6 +24,12 @@ export declare function contentExposureIdentity(body: string): string | null;
 export declare function documentExposedAtOrAbove(state: ContextExposureState, path: string, body: string, rung: Rung): boolean;
 /** Register both the physical document and its non-empty content alias. */
 export declare function registerDocumentExposure(target: ExposureTarget, path: string, body: string, rung: Rung): void;
+/** Forget that a document was delivered into the TRANSCRIPT — both its physical
+ *  identity and its content alias — while leaving any `system` rank intact,
+ *  because the system prompt is rebuilt on every agent run and survives
+ *  compaction. This is what re-arms a `pre-command` hold for guidance that
+ *  compaction dropped out of the transcript. */
+export declare function demoteDocumentTranscriptExposure(state: ContextExposureState, path: string, body: string): void;
 export declare function freezePreferenceSnapshot(state: ContextExposureState, rendered: string): string;
 export declare function cloneContextExposureState(source: ContextExposureState): ContextExposureState;
 export declare function hasTranscriptExposure(state: ContextExposureState): boolean;

package/dist/core/substrate/injected-store.js

@@ -49,6 +49,30 @@ export function registerDocumentExposure(target, path, body, rung) {
     if (contentIdentity !== null)
         registerExposure(target, contentIdentity, rung);
 }
+/** Drop one identity's transcript rank, deleting the entry outright when no
+ *  `system` rank remains. The v3 loader rejects an entry carrying neither rank,
+ *  and the writer serializes the map as-is, so leaving `{}` behind would crash
+ *  the node's substrate on its next load. */
+function dropTranscriptExposure(state, identity) {
+    const ranks = state.exposures.get(identity);
+    if (ranks === undefined)
+        return;
+    if (validRank(ranks.system))
+        state.exposures.set(identity, { system: ranks.system });
+    else
+        state.exposures.delete(identity);
+}
+/** Forget that a document was delivered into the TRANSCRIPT — both its physical
+ *  identity and its content alias — while leaving any `system` rank intact,
+ *  because the system prompt is rebuilt on every agent run and survives
+ *  compaction. This is what re-arms a `pre-command` hold for guidance that
+ *  compaction dropped out of the transcript. */
+export function demoteDocumentTranscriptExposure(state, path, body) {
+    dropTranscriptExposure(state, realpathOrSelf(path));
+    const contentIdentity = contentExposureIdentity(body);
+    if (contentIdentity !== null)
+        dropTranscriptExposure(state, contentIdentity);
+}
 export function freezePreferenceSnapshot(state, rendered) {
     if (state.preferenceSnapshot === null)
         state.preferenceSnapshot = rendered;

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

@@ -1,4 +1,4 @@
-import { type ExposureTarget } from './injected-store.js';
+import { type ContextExposureState, type ExposureTarget } from './injected-store.js';
 import { type Rung, type SubstrateDoc } from './schema.js';
 import type { NodeConfigSubject } from './subject-fields.js';
 interface EventCandidate {
@@ -30,4 +30,20 @@ export declare function memoryReadDocBlocks(subject: NodeConfigSubject | null, e
  * The corpus is the resolved cwd/profile set; a command has no file from which
  * to discover enclosing project stores. */
 export declare function renderOnCommandDocsForSubject(subject: NodeConfigSubject, command: string, target?: ExposureTarget): string;
+/** Surface docs whose `pre-command` entries match a bash command that has NOT
+ * run yet. The exact twin of the post-execution renderer above, and its empty
+ * string is load-bearing: `''` means every matching doc is already exposed at
+ * 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): 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;
+/** 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
+ * held once and then silently absent for the rest of the session. Lives here
+ * rather than in the extension because the corpus accessor is private. */
+export declare function demotePreCommandExposures(state: ContextExposureState): void;
 export {};

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

@@ -20,7 +20,13 @@
 //     workspace-wide context arrives before the task rather than waiting for
 //     an arbitrary first file.
 //   • `command` — a `bash` tool call evaluates the executed command string
-//     against every doc's `command` entries (string globs, `*` crossing `/`).
+//     against every doc's `command` entries (per shell segment, wildcards at
+//     token granularity — see surface-match.ts).
+//   • `pre-command` — a `bash` tool call ABOUT to run evaluates the same way
+//     against every doc's `pre-command` entries, and the call is held until
+//     the matching docs have been delivered. Because delivery registers
+//     exposure, the agent's re-issue of the same command finds nothing left to
+//     deliver and runs.
 //
 // All channels register through one context exposure target, so a document
 // already loaded at the same or a higher rung does not repeat. Each candidate
@@ -36,8 +42,8 @@ import { parseFrontmatterGeneric } from '../frontmatter.js';
 import { listAllMemoryDocs, listProjectMemoryDocs, loadStoreMemoryDocs, openProjectMemoryStore } from '../memory-resolver.js';
 import { userScopeRoot } from '../scope.js';
 import { gatePasses } from './gate.js';
-import { commandDeliveryRung, memoryReadDeliveryRung, owningRootOf, readDeliveryRung, workspaceOpenRung } from './surface-match.js';
-import { documentExposedAtOrAbove, emptyContextExposureState, exposureTarget, registerDocumentExposure, } from './injected-store.js';
+import { commandDeliveryRung, memoryReadDeliveryRung, owningRootOf, preCommandDeliveryRung, readDeliveryRung, workspaceOpenRung } from './surface-match.js';
+import { demoteDocumentTranscriptExposure, documentExposedAtOrAbove, emptyContextExposureState, exposureTarget, registerDocumentExposure, } from './injected-store.js';
 import { minRung, parseSubstrateDoc, previewLine } from './schema.js';
 import { cachedEventCorpusInclusive } from './session-cache.js';
 const JUNK_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', '.cache', '.yalc']);
@@ -242,3 +248,32 @@ export function renderOnCommandDocsForSubject(subject, command, target = transie
     const candidates = resolvedDocs().map(({ doc }) => ({ doc, rung: commandDeliveryRung(doc, subject, command) }));
     return renderCandidates(subject, candidates, target);
 }
+/** Surface docs whose `pre-command` entries match a bash command that has NOT
+ * run yet. The exact twin of the post-execution renderer above, and its empty
+ * string is load-bearing: `''` means every matching doc is already exposed at
+ * its matching rung or above, which is the release — the caller lets the
+ * command through. */
+export function renderPreCommandDocsForSubject(subject, command, target = transientTranscriptTarget()) {
+    const candidates = resolvedDocs().map(({ doc }) => ({ doc, rung: preCommandDeliveryRung(doc, subject, command) }));
+    return renderCandidates(subject, candidates, target);
+}
+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));
+}
+/** 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
+ * held once and then silently absent for the rest of the session. Lives here
+ * rather than in the extension because the corpus accessor is private. */
+export function demotePreCommandExposures(state) {
+    for (const { doc } of resolvedDocs()) {
+        if (carriesPreCommandEntry(doc))
+            demoteDocumentTranscriptExposure(state, doc.path, doc.body);
+    }
+}

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

@@ -15,7 +15,7 @@ export declare function rungAtLeast(r: Rung, min: Rung): boolean;
  *  authored rung against its project relationship's cap. */
 export declare function minRung(a: Rung, b: Rung): Rung;
 export { normalizeNameSegment, normalizeDocName, resolveLocalName as resolveDocName } from '../memory/identity.js';
-export declare const SURFACE_EVENTS: readonly ["boot", "workspace-open", "read", "memory-read", "command"];
+export declare const SURFACE_EVENTS: readonly ["boot", "workspace-open", "read", "memory-read", "command", "pre-command"];
 export type SurfaceEvent = (typeof SURFACE_EVENTS)[number];
 /** The rungs an entry may deliver at. There is no `none` — silence is the
  *  absence of an entry. (`Rung`'s `none` survives only as the internal
@@ -30,8 +30,8 @@ export type SurfaceRung = (typeof SURFACE_RUNGS)[number];
 export interface SurfaceEntry {
     on: SurfaceEvent;
     /** Globs vs the event's subject namespace. Required on read/memory-read/
-     *  command (a read entry may carry `matchFrontmatter` instead); meaningless
-     *  on boot/workspace-open (presence of the entry is the match). */
+     *  command/pre-command (a read entry may carry `matchFrontmatter` instead);
+     *  meaningless on boot/workspace-open (presence of the entry is the match). */
     match?: string[];
     /** Predicate over the read file's own YAML frontmatter — `read` event only.
      *  Frontmatter key `match-frontmatter`. */

package/dist/core/substrate/schema.js

@@ -56,7 +56,7 @@ export { normalizeNameSegment, normalizeDocName, resolveLocalName as resolveDocN
 // no `surfaces` at all does exactly one thing: appears in its directory's
 // listing.
 // ---------------------------------------------------------------------------
-export const SURFACE_EVENTS = ['boot', 'workspace-open', 'read', 'memory-read', 'command'];
+export const SURFACE_EVENTS = ['boot', 'workspace-open', 'read', 'memory-read', 'command', 'pre-command'];
 /** The rungs an entry may deliver at. There is no `none` — silence is the
  *  absence of an entry. (`Rung`'s `none` survives only as the internal
  *  ranking floor, e.g. `bootRung` of a doc with no boot entry.) */
@@ -158,8 +158,8 @@ function parseGate(v) {
         : undefined;
 }
 /** Tolerant `surfaces` parse: a non-array yields `[]`; invalid entries are
- *  dropped (bad `on`, bad `at`, a read/memory-read/command entry left with
- *  neither `match` nor — read only — `match-frontmatter`). `match-frontmatter`
+ *  dropped (bad `on`, bad `at`, a read/memory-read/command/pre-command entry
+ *  left with neither `match` nor — read only — `match-frontmatter`). `match-frontmatter`
  *  on a non-read event is dropped from the entry, which survives iff it still
  *  carries a `match`; an invalid entry `gate` is dropped. Lint owns strict
  *  enforcement; the runtime parser maps over many docs and must never throw. */
@@ -180,7 +180,7 @@ function parseSurfaces(v) {
         const match = parseMatchGlobs(rec['match']);
         const matchFrontmatter = on === 'read' ? parseGate(rec['match-frontmatter']) : undefined;
         const gate = parseGate(rec['gate']);
-        if ((on === 'read' || on === 'memory-read' || on === 'command') &&
+        if ((on === 'read' || on === 'memory-read' || on === 'command' || on === 'pre-command') &&
             match === undefined &&
             matchFrontmatter === undefined) {
             continue;

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

@@ -20,6 +20,21 @@ 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, 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,
+ *  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, command: string): boolean;
 /** The doc's delivery rung for a read of `absReadFile` (already realpathed). */
 export declare function readDeliveryRung(doc: Pick<SubstrateDoc, 'surfaces' | 'path' | 'scope'>, subject: NodeConfigSubject, absReadFile: string, readFrontmatter: Record<string, unknown>): Rung;
 /** The doc's workspace-open rung. Presence of an entry is the match; callers
@@ -33,3 +48,7 @@ export declare function workspaceOpenRung(doc: Pick<SubstrateDoc, 'surfaces'>, s
 export declare function memoryReadDeliveryRung(doc: Pick<SubstrateDoc, 'surfaces'>, routingAnchor: string, subject: NodeConfigSubject | null, name: string): Rung;
 /** The doc's delivery rung for an executed command string. */
 export declare function commandDeliveryRung(doc: Pick<SubstrateDoc, 'surfaces'>, subject: NodeConfigSubject, command: string): Rung;
+/** The doc's delivery rung for a command about to run — the highest `at`
+ *  over the doc's matching `pre-command` entries, folded the same way as every
+ *  other event. */
+export declare function preCommandDeliveryRung(doc: Pick<SubstrateDoc, 'surfaces'>, subject: NodeConfigSubject, command: string): Rung;