@north-light/crouter 0.3.232 → 0.3.234

package/dist/core/runtime/stream-watchdog.js

@@ -13,23 +13,18 @@
 // generation so settlement records an automatic pi→provider connection fault;
 // the existing fault-retry machinery owns re-driving the turn. The broker
 // process — and its in-memory queues — survives instead of being killed.
-const DEFAULT_STREAM_WATCHDOG_MS = 5 * 60_000; // 5 minutes.
-// Comfortably under the daemon's 20-minute WEDGE_QUIET_MS hard kick (crtrd.ts),
-// so this is the common-case recovery path and the daemon kick becomes the rare
-// backstop. Generous enough that a live, healthy stream never trips it: a
-// single LLM turn's own network round-trips (message_update deltas,
-// tool_execution_start/update/end) land well inside 5 minutes. The watchdog
-// covers ONLY time awaiting the provider: the broker disarms it while a tool is
-// executing (a legitimately silent tool can run longer than the timeout — see
-// broker.ts relayEvent) and rearms it once the last in-flight tool ends, so a
-// slow-but-live turn is never mistaken for a dead one.
-export function resolveStreamWatchdogMs() {
-    const raw = process.env['CRTR_STREAM_WATCHDOG_MS'];
-    if (raw === undefined)
-        return DEFAULT_STREAM_WATCHDOG_MS;
-    const n = Number(raw);
-    return Number.isFinite(n) && n > 0 ? n : DEFAULT_STREAM_WATCHDOG_MS;
-}
+// The default is 5 minutes, comfortably under the daemon's 20-minute
+// WEDGE_QUIET_MS hard kick (crtrd.ts), so this is the common-case recovery
+// path and the daemon kick becomes the rare backstop. Generous enough that a
+// live, healthy stream never trips it: a single LLM turn's own network
+// round-trips (message_update deltas, tool_execution_start/update/end) land
+// well inside 5 minutes. The watchdog covers ONLY time awaiting the provider:
+// the broker disarms it while a tool is executing (a legitimately silent tool
+// can run longer than the timeout — see broker.ts relayEvent) and rearms it
+// once the last in-flight tool ends, so a slow-but-live turn is never mistaken
+// for a dead one. See `envStreamWatchdogMs()` (`shared/env.ts`) for the parsed
+// `CRTR_STREAM_WATCHDOG_MS` accessor and default value.
+import { envStreamWatchdogMs } from '../../shared/env.js';
 /**
  * A single-timer dead-man's switch: `poke(token)` (re)arms it, `clear()`
  * disarms it, and `onStall(token)` fires exactly once if `poke()` isn't called
@@ -50,7 +45,7 @@ export class StreamWatchdog {
     ms;
     constructor(onStall, ms) {
         this.onStall = onStall;
-        this.ms = ms ?? resolveStreamWatchdogMs();
+        this.ms = ms ?? envStreamWatchdogMs();
     }
     /** Proof of progress — (re)arm the timer for `token`, canceling any prior
      *  countdown. The fired `onStall` receives THIS arm's token. Inert while

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

@@ -10,9 +10,7 @@ import { normalizeTmuxPassthrough } from '../config.js';
 import { withExclusiveDirectoryLock } from '../exclusive-lock.js';
 import { surfaceTmuxStyleArgs } from './surface-bg.js';
 import { runTmux as tmux, shellQuote } from './tmux-driver.js';
-// ---------------------------------------------------------------------------
 // Crouter-owned tmux bindings
-// ---------------------------------------------------------------------------
 const TMUX_BINDING_MANIFEST = '@crtr_keybindings_manifest';
 const ROOT_TABLE = 'root';
 const LEAF_MENU_ACTIONS = {

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

@@ -7,6 +7,18 @@ declare function tmux(args: string[]): {
     stderr: string;
 };
 export declare function inTmux(): boolean;
+/** Is any tmux SESSION currently up? `tmux list-sessions` exits 0 iff a server
+ *  is running with at least one session, non-zero otherwise (including "no
+ *  server"). This is the boot-time/bash-tooling probe — distinct from
+ *  `tmuxClientsReachable`, which asks whether a server is reachable at all
+ *  regardless of session count and is the human-surface gate. */
+export declare function tmuxSessionsReachable(): boolean;
+/** Is the tmux SERVER reachable at all? `tmux list-clients` exits 0 whenever a
+ *  server is up (even with zero attached clients), non-zero when no server is
+ *  running. This is the human-surface gate (core/spawn.ts's
+ *  `tmuxServerReachable`) — distinct from `tmuxSessionsReachable`, which
+ *  additionally requires a session to exist. */
+export declare function tmuxClientsReachable(): boolean;
 /** The pane currently displaying `nodeId`, found by the authoritative `@crtr_node`
  *  pane tag — set by EVERY viewer (a bare `surface attach`, a focus split, a
  *  spawned viewer) on connect. Scans all panes (`list-panes -a`); the reverse of

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

@@ -7,9 +7,8 @@ import { execFile, spawnSync } from 'node:child_process';
 import { encodeAttachControlInput, } from '../keybindings/index.js';
 import { bundledPiCommandForShell } from './pi-cli.js';
 import { shellQuote } from '../../shared/shell-quote.js';
-// ---------------------------------------------------------------------------
+import { envPiBinaryOverride } from '../../shared/env.js';
 // tmux invocation
-// ---------------------------------------------------------------------------
 export { shellQuote };
 function tmux(args) {
     const r = spawnSync('tmux', args, { encoding: 'utf8' });
@@ -25,6 +24,22 @@ function tmuxOnSocket(socket, args) {
 export function inTmux() {
     return process.env['TMUX'] !== undefined && process.env['TMUX'] !== '';
 }
+/** Is any tmux SESSION currently up? `tmux list-sessions` exits 0 iff a server
+ *  is running with at least one session, non-zero otherwise (including "no
+ *  server"). This is the boot-time/bash-tooling probe — distinct from
+ *  `tmuxClientsReachable`, which asks whether a server is reachable at all
+ *  regardless of session count and is the human-surface gate. */
+export function tmuxSessionsReachable() {
+    return spawnSync('tmux', ['list-sessions'], { encoding: 'utf8', stdio: 'ignore' }).status === 0;
+}
+/** Is the tmux SERVER reachable at all? `tmux list-clients` exits 0 whenever a
+ *  server is up (even with zero attached clients), non-zero when no server is
+ *  running. This is the human-surface gate (core/spawn.ts's
+ *  `tmuxServerReachable`) — distinct from `tmuxSessionsReachable`, which
+ *  additionally requires a session to exist. */
+export function tmuxClientsReachable() {
+    return spawnSync('tmux', ['list-clients', '-F', '#{client_name}'], { encoding: 'utf8' }).status === 0;
+}
 /** The pane currently displaying `nodeId`, found by the authoritative `@crtr_node`
  *  pane tag — set by EVERY viewer (a bare `surface attach`, a focus split, a
  *  spawned viewer) on connect. Scans all panes (`list-panes -a`); the reverse of
@@ -63,9 +78,7 @@ export function currentTmux() {
     const [session, window, pane] = r.stdout.split('\t');
     return { session, window, pane };
 }
-// ---------------------------------------------------------------------------
 // Sessions + windows
-// ---------------------------------------------------------------------------
 export function sessionExists(name) {
     return tmux(['has-session', '-t', name]).ok;
 }
@@ -517,9 +530,7 @@ export function panePid(pane) {
 export function respawnPaneInPlace(pane) {
     return tmux(['respawn-pane', '-k', '-t', pane]).ok;
 }
-// ---------------------------------------------------------------------------
 // pi command assembly
-// ---------------------------------------------------------------------------
 /** Turn a pi argv array into a single shell command string.
  *
  *  The binary defaults to `CRTR_PI_BINARY` when that env var is set, else the
@@ -530,12 +541,10 @@ export function respawnPaneInPlace(pane) {
  *  explicit `binary` arg still overrides the env. The value may be a multi-word
  *  launcher (e.g. `node --import tsx/esm host.ts`); only argv entries are
  *  shell-quoted, so a multi-word binary is spliced verbatim ahead of them. */
-export function piCommand(argv, binary = process.env['CRTR_PI_BINARY'] ?? bundledPiCommandForShell(shellQuote)) {
+export function piCommand(argv, binary = envPiBinaryOverride() ?? bundledPiCommandForShell(shellQuote)) {
     return [binary, ...argv.map(shellQuote)].join(' ');
 }
-// ---------------------------------------------------------------------------
 // Window liveness helpers (used by the supervisor daemon)
-// ---------------------------------------------------------------------------
 /** List all window ids present in `session`. Returns [] if the session does
  *  not exist or tmux fails for any reason. Each entry is the raw window id
  *  string reported by tmux (e.g. `@1`, `@2`, …). */
@@ -553,9 +562,7 @@ export function windowAlive(session, window) {
         return false;
     return listWindowIds(session).includes(window);
 }
-// ---------------------------------------------------------------------------
 // Focus helpers (used by the placement layer)
-// ---------------------------------------------------------------------------
 /** Activate a window within its session (same-session navigation). Equivalent
  *  to `tmux select-window -t <session>:<window>`. Best-effort; never throws. */
 export function selectWindow(session, window) {
@@ -582,9 +589,7 @@ export function selectPane(pane) {
 export function switchClient(session) {
     return tmux(['switch-client', '-t', session]).ok;
 }
-// ---------------------------------------------------------------------------
 // send-keys (chrome — used by the prefix menu + nav bindings)
-// ---------------------------------------------------------------------------
 /** Type a literal (e.g. a `/graph` slash command) into a pane and press Enter
  *  (`tmux send-keys -t <pane> '<text>' Enter`). Requires the pane's editor be
  *  empty, same limitation as the menu's `/promote` item. Best-effort. */

package/dist/core/runtime/warm-pool.js

@@ -182,9 +182,7 @@ function abandonSpare(nodeId, what, err) {
     catch { /* best-effort */ }
     return null;
 }
-// ---------------------------------------------------------------------------
 // Reaping
-// ---------------------------------------------------------------------------
 /** How long an UNCLAIMED spare is worth its resident broker (~150-300 MB).
  *  A spare exists to make the NEXT create instant; one nobody has claimed in
  *  this long is memory rented for nothing, so it is returned. Over-reaping
@@ -308,9 +306,7 @@ function mint(recipe) {
         }
     })();
 }
-// ---------------------------------------------------------------------------
 // Daemon-start pre-warm
-// ---------------------------------------------------------------------------
 /** How many profiles get a spare at daemon start. Each spare is a resident
  *  broker at ~150-300 MB, so this is deliberately tiny. */
 const PREWARM_PROFILES = 2;

package/dist/core/scope.js

@@ -1,3 +1,4 @@
+import { envProfileId } from '../shared/env.js';
 import { homedir } from 'node:os';
 import { existsSync, statSync } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
@@ -105,7 +106,7 @@ function collectAncestorScopeRoots(startDir, userRoot) {
  *  (`findProjectScopeRootsWithMemory`), a projection layered onto this order
  *  rather than part of it: discovery provenance decides precedence, the
  *  relationship decides the ceiling, and the two never influence each other. */
-export function findProjectScopeRoots(startDir = process.cwd(), profileId = process.env['CRTR_PROFILE_ID'] || null) {
+export function findProjectScopeRoots(startDir = process.cwd(), profileId = envProfileId() || null) {
     return resolveProjectScopeRoots(startDir, profileId).roots;
 }
 /** `findProjectScopeRoots` with each root's profile memory ceiling attached —
@@ -113,7 +114,7 @@ export function findProjectScopeRoots(startDir = process.cwd(), profileId = proc
  *  walk takes that entry's `memory` (first entry in manifest order wins, even
  *  when cwd also reaches the root); every other root takes the neutral
  *  `content` ceiling. */
-export function findProjectScopeRootsWithMemory(startDir = process.cwd(), profileId = process.env['CRTR_PROFILE_ID'] || null) {
+export function findProjectScopeRootsWithMemory(startDir = process.cwd(), profileId = envProfileId() || null) {
     return resolveProjectScopeRoots(startDir, profileId).annotated;
 }
 function resolveProjectScopeRoots(startDir, profileId) {
@@ -195,7 +196,7 @@ export function ensureProjectScopeRoot(startDir = process.cwd()) {
     // cache hit.
     const resolvedStart = resolve(startDir);
     const root = join(resolvedStart, CRTR_DIR_NAME);
-    const profileId = process.env['CRTR_PROFILE_ID'] || null;
+    const profileId = envProfileId() || null;
     // Neutral ceiling: the empty cached stack proves no profile entry's ancestor
     // walk reached this root, since it did not exist to be walked into.
     scopeRootsCache.set(scopeRootsCacheKey(resolvedStart, profileId), {

package/dist/core/spawn.js

@@ -4,7 +4,7 @@
 // (tmuxServerReachable) so it can decide whether to surface a prompt or degrade
 // to the inbox-drain follow-up. The canvas runtime has its own
 // one-window-per-node machinery in core/runtime/placement-tmux.ts.
-import { spawnSync } from 'node:child_process';
+import { tmuxClientsReachable } from './runtime/tmux-driver.js';
 /** Does THIS process sit inside a tmux client (its own $TMUX is set)? NOT the
  *  gate for the human surface — see tmuxServerReachable. A headless-broker child
  *  strips TMUX/TMUX_PANE (broker.ts, anti-stophook-hijack) yet can still drive
@@ -22,6 +22,5 @@ export function isInTmux() {
  *  no server is running — the true "no tmux to surface into" case that should
  *  degrade to the inbox-drain follow-up. */
 export function tmuxServerReachable() {
-    const r = spawnSync('tmux', ['list-clients', '-F', '#{client_name}'], { encoding: 'utf8' });
-    return r.status === 0;
+    return tmuxClientsReachable();
 }

package/dist/core/subscription-state.js

@@ -1,8 +1,9 @@
-import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { createHash } from "node:crypto";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
-import { LockedJsonFile } from "./locked-file.js";
+import { existsSync, readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { atomicWriteJson } from './fs-utils.js';
+import { LockedJsonFile } from './locked-file.js';
 export const ANTHROPIC_PROVIDER_ID = "anthropic";
 export const OPENAI_CODEX_PROVIDER_ID = "openai-codex";
 export const INVALID_REFRESH_TOKEN_BACKOFF_MS = 30 * 24 * 60 * 60 * 1000;
@@ -123,14 +124,6 @@ function parsePoolUnderLock(path, current) {
         throw new Error(`Subscription pool ${path} is corrupt: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
-function writeJsonFile(path, value, mode) {
-    mkdirSync(dirname(path), { recursive: true });
-    const tmp = `${path}.${process.pid}.tmp`;
-    writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, mode === undefined ? "utf8" : { encoding: "utf8", mode });
-    if (mode !== undefined)
-        chmodSync(tmp, mode);
-    renameSync(tmp, path);
-}
 function normalizeStrength(value) {
     return value === "ultra" || value === "strong" || value === "medium" || value === "light" ? value : undefined;
 }
@@ -212,13 +205,13 @@ function assertCandidateRowsStorable(providerId, candidate) {
 // The ONE door every write to a pool file goes through. Both pool invariants -- one account
 // identity per pool, and every candidate row carrying a storable credential -- are properties
 // of the FILE, not of whichever code path happens to be writing, so they are asserted here
-// against the state this write replaces, under the caller's already-held lock. `writeJsonFile`
-// is reached for the pool NOWHERE ELSE: that makes the invariants unbypassable.
+// against the state this write replaces, under the caller's already-held lock. `atomicWriteJson`
+// is reached for the pool NOWHERE ELSE in this file: that makes the invariants unbypassable.
 function persistPool(providerId, poolFile, base, candidate) {
     assertCandidateRowsStorable(providerId, candidate);
     const next = normalizeCredentials(candidate);
     logCredentialSetChange(providerId, base, next);
-    writeJsonFile(poolFile, next, 0o600);
+    atomicWriteJson(poolFile, next, { mode: 0o600 });
     return next;
 }
 // Accounts vanishing from a pool is the failure users actually feel ("I keep having to log in
@@ -721,7 +714,7 @@ export function writeRotationConfig(next) {
         defaultFallbackStrength: normalizeStrength(next.defaultFallbackStrength) ?? current.defaultFallbackStrength ?? DEFAULT_FALLBACK_STRENGTH,
         revertWhenAvailable: next.revertWhenAvailable ?? current.revertWhenAvailable ?? true,
     };
-    writeJsonFile(rotationConfigFile(), merged);
+    atomicWriteJson(rotationConfigFile(), merged);
     return merged;
 }
 export function formatStatusLine(providerId, now = Date.now()) {

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

@@ -22,6 +22,11 @@
 //   • `command` — a `bash` tool call evaluates the executed command string
 //     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
@@ -37,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']);
@@ -243,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/render.js

@@ -140,9 +140,7 @@ function bootCorpus() {
     }
     return { docs, sources };
 }
-// ---------------------------------------------------------------------------
 // Exposure registration
-// ---------------------------------------------------------------------------
 function rendersAtBoot(doc) {
     return isVisible(doc.bootRung) && (doc.bootRung !== 'content' || doc.body.trim() !== '');
 }
@@ -156,9 +154,7 @@ function recordRendered(target, docs) {
         registerDocumentExposure(target, d.path, d.body, d.bootRung);
     }
 }
-// ---------------------------------------------------------------------------
 // Step 2 — display ordering + grouped render.
-// ---------------------------------------------------------------------------
 /** Content-prose ordering rank: general → specific. builtin=0, user=1,
  *  profile=2, project ranks start at 3 and climb by root nearness — the
  *  OUTERMOST ancestor `.crouter/` root ranks lowest (renders first), the
@@ -412,9 +408,7 @@ function buildTree(docs, rootLabel) {
     renderChildren(root, '', lines);
     return lines.join('\n');
 }
-// ---------------------------------------------------------------------------
 // Block prose — the intro legend + the update directive for each kind.
-// ---------------------------------------------------------------------------
 const READ_LEGEND = 'Each %s below shows either its full content (indented beneath its name), a ' +
     '`# read when:` line telling you when to read the full document, or simply its name.';
 const PREFERENCES_INTRO = 'Preferences are how the user wants you to behave — standing directives and corrections. ' +
@@ -487,9 +481,7 @@ export function buildSubPersonaMenu(kind) {
         'dragging unrelated context into it.\n\n' +
         lines.join('\n'));
 }
-// ---------------------------------------------------------------------------
 // 1. Preferences — protocol prose + `<memory kind="preference">` (system prompt).
-// ---------------------------------------------------------------------------
 /** The system-prompt substrate splice, TWO parts in one string.
  *
  *  1. The operating protocol: shipped (builtin/plugin) content-rung bodies as
@@ -548,9 +540,7 @@ function buildPreferencesBlock(subject, target) {
 export function renderPreferencesForSubject(subject, target) {
     return buildPreferencesBlock(subject, target);
 }
-// ---------------------------------------------------------------------------
 // 2. Knowledge — `<memory kind="knowledge">` (the first-message bearings).
-// ---------------------------------------------------------------------------
 /** STEP 1 for the knowledge block, shared by the boot render and the
  *  config-change delta: the resolver's knowledge winners ∪ the node's own store
  *  (any kind), first-wins deduped resolver-first so a same-named node doc
@@ -589,9 +579,7 @@ export function renderKnowledgeForSubject(subject, nodeId, target) {
     // Surfaced INTO this node: swap literal `$CRTR_CONTEXT_DIR` for the real path.
     return interpolateNodePaths(`<memory kind="knowledge">\n${out}\n</memory>`, nodeId);
 }
-// ---------------------------------------------------------------------------
 // 3. The config-change delta — the memory a node's NEW configuration exposes.
-// ---------------------------------------------------------------------------
 const DELTA_PROTOCOL_INTRO = 'Your node configuration changed. This operating protocol is in force for you now:';
 const DELTA_PREFERENCES_INTRO = 'Your new configuration puts these preferences in force — standing directives and corrections ' +
     'from the user. To read one, run `crtr memory read <name>`. ' +

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`. */