@north-light/crouter 0.3.232 → 0.3.234

package/dist/migrations/corpus.js

@@ -17,6 +17,7 @@
 // so node target metadata comes from each node's durable meta.json — the source
 // of truth the database index is rebuilt from — through its existing read-only
 // helper. Missing or corrupt metadata remains a global blocker.
+import { envProfileId } from '../shared/env.js';
 import { readdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { readMetaObject } from '../core/canvas/meta-file.js';
@@ -79,7 +80,7 @@ function nodeStoresWithDocs() {
  *  so discovery must run after that lane, not against `listProfiles()`. */
 export async function discoverCorpus(opts) {
     const cwd = realpathOrSelf(opts.cwd ?? process.cwd());
-    const selectedProfileId = process.env['CRTR_PROFILE_ID'] || null;
+    const selectedProfileId = envProfileId() || null;
     const explicitDirs = opts.explicitDirs ?? [];
     const roots = [];
     const rootSeen = new Set();
@@ -336,9 +337,7 @@ export async function discoverCorpus(opts) {
         nodeMetadata,
     };
 }
-// ---------------------------------------------------------------------------
 // Snapshots
-// ---------------------------------------------------------------------------
 /** Read every discovered store's documents. `preloaded` supplies the per-store
  *  convergent lane's FOLDED snapshots so the corpus plans against the bytes a
  *  write run leaves behind — identical under `--dry-run`, where the same fold
@@ -387,9 +386,7 @@ export function buildCorpusSnapshot(discovery, snapshots) {
     }));
     return makeCorpusSnapshot(stores, discovery.targets, discovery.roots);
 }
-// ---------------------------------------------------------------------------
 // The runner
-// ---------------------------------------------------------------------------
 function cloneCorpus(corpus) {
     const stores = corpus.stores.map((store) => ({
         ...store,

package/dist/migrations/registry.js

@@ -1,5 +1,18 @@
-// The ordered state-migration registry — ONE list for both lanes, so a cut
-// that spans canvas-db and document stores ships as adjacent entries.
+// The ordered state-migration registry — the SECOND of this repo's three
+// migration homes, and the one for on-disk memory documents, profile
+// manifests, and the corpus lane, driven by `crtr sys migrate`. ONE list for
+// both non-journaled lanes here, so a cut that spans canvas-db and document
+// stores ships as adjacent entries (the journaled lane's entries splice into
+// `../core/canvas/migrations.ts`'s `MIGRATIONS` chain at its tail).
+//
+// The other two homes:
+//   - `../core/canvas/migrations.ts` — canvas.db's own versioned schema chain,
+//     gated by `PRAGMA user_version`. Steps there may freely read node meta,
+//     query other tables mid-step, and build shell commands from canvas data
+//     — exactly what this registry's import contract (below) forbids, which
+//     is why that chain is not expressed as registrants here.
+//   - `../daemon/boot-migrations.ts` — filesystem repairs that run
+//     unconditionally at every daemon boot, outside any version gate.
 //
 // Authoring contract (each migration is one file, `NNN-<desc>.ts`, or one
 // directory, `NNN-<desc>/index.ts`, appended here in order):

package/dist/pi-extensions/__tests__/canvas-stophook-agentend.test.js

@@ -221,7 +221,6 @@ test('queued continuation finishes before natural-stop routing commits', { timeo
     assert.equal(shutdown, true, 'settlement routes from the completed continuation');
     assert.equal(getNode('leaf')?.intent ?? null, null, 'the intermediate natural stop never idle-released the node');
 });
-// ---------------------------------------------------------------------------
 // §5.1 — the §1.7 settlement branch map on the focuses table. Every assertion is
 // on the canvas focuses/runtime rows after firing agent_settled (TMUX_PANE is
 // cleared in beforeEach). NOTE (broker-host cut): the placement read `focusOf`
@@ -232,7 +231,6 @@ test('queued continuation finishes before natural-stop routing commits', { timeo
 // but-not-yet-realized viewer, which liveOrPrune passes through). status='done'
 // is reached by setting the runtime row directly (the branch reads
 // getNode(nodeId).status).
-// ---------------------------------------------------------------------------
 test('§5.1.2 truly-done + focused → focus row CLOSED, own presence nulled (Q1)', async () => {
     // R carries a LOCATION so the close-path presence-null is observable.
     createNode(node('R', { parent: null, lifecycle: 'terminal', pane: '%r', tmux_session: 'Suser', window: '@wr' }));
@@ -323,10 +321,8 @@ test('refresh-yield (intent=refresh) writes NO push — silent to subscribers',
     assert.equal(readInboxSince('root').length, 0, 'a yield is silent: NO inbox pointer');
     assert.equal(pi.injected.length, 0, 'no reprompt on a refresh-yield');
 });
-// ---------------------------------------------------------------------------
 // turn_end — stale-⚠ fix: reaching turn_end proves the current provider
 // round-trip and any wedge episode are both over, so both fault links clear.
-// ---------------------------------------------------------------------------
 /** A turn_end event carrying one assistant text block. */
 function turnEndEvent(text) {
     return { message: { role: 'assistant', content: [{ type: 'text', text }] } };

package/dist/pi-extensions/__tests__/pre-command-gate.test.d.ts

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

package/dist/pi-extensions/__tests__/pre-command-gate.test.js

@@ -0,0 +1,220 @@
+// Regression: the `pre-command` gate holds a bash command BEFORE it runs and
+// releases it once its memory is in the transcript. The release is not a stored
+// decision — it is the exposure ledger, and that is exactly what makes it
+// fragile:
+//
+//   • Compaction drops the delivered guidance out of the transcript while the
+//     ledger still claims it was delivered. Without the demotion pass the doc is
+//     held once and then silently absent for the rest of the session. Worse, a
+//     demotion that left a rankless entry behind would crash the node's whole
+//     substrate on its next load — so the ledger is reloaded FROM DISK here.
+//   • pi preflights the siblings of one assistant message sequentially and then
+//     executes them concurrently, so without a per-turn flag the second sibling
+//     would find the doc already exposed and slip past the hold its sibling just
+//     raised.
+//   • A session whose corpus carries no `pre-command` doc at all is the common
+//     case and must never pay a daemon round-trip. Proven by closing the daemon:
+//     if the short-circuit stopped working the call would fail loud.
+//
+// The gate runs against the real canvas api server, so the subject the matcher
+// gates on is the one crtrd actually serves.
+//
+// Run: node --conditions=crtr-src --import tsx/esm --test src/pi-extensions/__tests__/pre-command-gate.test.ts
+import { test, before, beforeEach, afterEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { registerCanvasDocSubstrate } from '../canvas-doc-substrate.js';
+import { createNode } from '../../core/canvas/canvas.js';
+import { closeDb } from '../../core/canvas/db.js';
+import { apiSocketPath } from '../../core/canvas/paths.js';
+import { resetScopeCache } from '../../core/scope.js';
+import { loadContextExposureState } from '../../core/substrate/injected-store.js';
+import { clearSessionCache } from '../../core/substrate/session-cache.js';
+import { createApiServer } from '../../daemon/api/server.js';
+const DOCTRINE_BODY = 'PRE-COMMAND-DOCTRINE-BODY';
+let home;
+let cwd;
+let server = null;
+let origCwd;
+let origHome;
+let origNode;
+let origProfile;
+async function waitForSocket(path) {
+    for (let i = 0; i < 200; i++) {
+        if (existsSync(path))
+            return;
+        await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+    throw new Error(`api socket never bound at ${path}`);
+}
+async function closeServer() {
+    const running = server;
+    server = null;
+    if (running !== null)
+        await running.close();
+}
+/** A user-scope doc that holds every `deploy …` invocation until it is read. */
+function writeDoctrineDoc(event) {
+    const store = join(home, 'user', '.crouter', 'memory');
+    mkdirSync(store, { recursive: true });
+    const path = join(store, 'deploy-doctrine.md');
+    writeFileSync(path, '---\nkind: knowledge\n' +
+        'when-and-why-to-read: When deploying, this knowledge should be read because it carries the approval boundary.\n' +
+        `surfaces:\n  - {on: ${event}, at: content, match: "deploy*"}\n---\n` +
+        `${DOCTRINE_BODY}\n`);
+    clearSessionCache();
+    return realpathSync(path);
+}
+/** A canvas node the api server can assemble a subject for, selected as the
+ *  session's node. Each test uses its own id: the extension's exposure state is
+ *  a per-node process singleton. */
+function seedNode(id) {
+    createNode({
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd,
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+    });
+    mkdirSync(join(home, 'nodes', id), { recursive: true });
+    process.env['CRTR_NODE_ID'] = id;
+}
+/** The registered extension, driven through the pi events it actually binds. */
+function registerSubstrate() {
+    const handlers = new Map();
+    registerCanvasDocSubstrate({
+        on(event, handler) {
+            const bound = handlers.get(event) ?? [];
+            bound.push(handler);
+            handlers.set(event, bound);
+        },
+    });
+    async function fire(event, payload) {
+        const bound = handlers.get(event) ?? [];
+        assert.equal(bound.length, 1, `the substrate binds exactly one ${event} handler`);
+        return await bound[0](payload, {});
+    }
+    return {
+        toolCall: (toolName, input) => fire('tool_call', { toolName, input }),
+        bash: (command) => fire('tool_call', { toolName: 'bash', input: { command } }),
+        endTurn: async () => void (await fire('turn_end', {})),
+        compact: async () => void (await fire('session_compact', {})),
+    };
+}
+function assertHeld(result, what) {
+    assert.ok(result !== undefined, `${what} is held`);
+    assert.equal(result.block, true);
+    assert.ok(result.reason.startsWith('HELD — nothing ran.'), `the held result opens with the notice; got: ${result.reason}`);
+    return result;
+}
+before(() => {
+    origCwd = process.cwd();
+    origHome = process.env['HOME'];
+    origNode = process.env['CRTR_NODE_ID'];
+    origProfile = process.env['CRTR_PROFILE_ID'];
+});
+beforeEach(async () => {
+    closeDb();
+    if (home)
+        rmSync(home, { recursive: true, force: true });
+    home = mkdtempSync(join(tmpdir(), 'crtr-pre-command-'));
+    cwd = join(home, 'user', 'work');
+    mkdirSync(cwd, { recursive: true });
+    process.chdir(cwd);
+    process.env['HOME'] = join(home, 'user');
+    process.env['CRTR_HOME'] = home;
+    delete process.env['CRTR_NODE_ID'];
+    delete process.env['CRTR_PROFILE_ID'];
+    resetScopeCache();
+    clearSessionCache();
+    server = createApiServer();
+    await waitForSocket(apiSocketPath());
+});
+afterEach(async () => {
+    try {
+        await closeServer();
+    }
+    finally {
+        process.chdir(origCwd);
+    }
+});
+after(() => {
+    process.chdir(origCwd);
+    closeDb();
+    if (home)
+        rmSync(home, { recursive: true, force: true });
+    resetScopeCache();
+    clearSessionCache();
+    delete process.env['CRTR_HOME'];
+    if (origHome === undefined)
+        delete process.env['HOME'];
+    else
+        process.env['HOME'] = origHome;
+    if (origNode === undefined)
+        delete process.env['CRTR_NODE_ID'];
+    else
+        process.env['CRTR_NODE_ID'] = origNode;
+    if (origProfile === undefined)
+        delete process.env['CRTR_PROFILE_ID'];
+    else
+        process.env['CRTR_PROFILE_ID'] = origProfile;
+});
+test('a matching command is held with its doc, every sibling in the message with it, and the re-issue runs', async () => {
+    const docPath = writeDoctrineDoc('pre-command');
+    seedNode('gate-hold');
+    const pi = registerSubstrate();
+    const held = assertHeld(await pi.bash('deploy prod'), 'the first matching command');
+    assert.ok(held.reason.includes(DOCTRINE_BODY), `the doc rides back as the blocked call's result; got: ${held.reason}`);
+    assert.match(held.reason, /re-issue your WHOLE command/, 'the copy steers a whole-command re-issue, never one clause');
+    // Exposure is registered AT BLOCK TIME — physical identity and content alias
+    // both — and that single fact is what releases the re-issue below.
+    const afterBlock = loadContextExposureState('gate-hold');
+    assert.deepEqual(afterBlock.exposures.get(docPath), { transcript: 3 }, 'the held doc is recorded as delivered');
+    assert.equal(afterBlock.exposures.size, 2, 'the content alias is recorded alongside the path');
+    // Siblings of the same assistant message. The doc is already exposed, so
+    // without the per-turn flag the render would come back empty and let them
+    // through. The flag covers the whole message, matching or not: every command
+    // in it was authored under the worldview this doc just corrected.
+    const sibling = assertHeld(await pi.bash('deploy staging'), 'a matching sibling');
+    assert.match(sibling.reason, /Another command in this same message/);
+    assertHeld(await pi.bash('ls -la'), 'a non-matching sibling of a held command');
+    await pi.endTurn();
+    // The release: the doc is in the transcript, so there is nothing left to
+    // deliver and nothing left to hold.
+    assert.equal(await pi.bash('deploy prod'), undefined, 'the identical command re-issued in a later turn runs');
+    assert.equal(await pi.bash('ls -la'), undefined, 'a command matching nothing is untouched');
+});
+test('compaction re-arms the hold and leaves an exposure ledger that reloads', async () => {
+    const docPath = writeDoctrineDoc('pre-command');
+    seedNode('gate-compact');
+    const pi = registerSubstrate();
+    assertHeld(await pi.bash('deploy prod'), 'the first matching command');
+    await pi.endTurn();
+    assert.equal(await pi.bash('deploy prod'), undefined, 'the doc is in the transcript, so the command runs');
+    await pi.endTurn();
+    await pi.compact();
+    // Reloaded from disk: the demotion must DELETE the rankless entry rather than
+    // leave `{}` behind, which the v3 loader rejects outright — this call is the
+    // proof it did.
+    const afterCompact = loadContextExposureState('gate-compact');
+    assert.equal(afterCompact.exposures.has(docPath), false, 'compaction forgets the delivery that compaction dropped');
+    assert.equal(afterCompact.exposures.size, 0, 'the content alias is forgotten too, and no rankless entry survives');
+    const reheld = assertHeld(await pi.bash('deploy prod'), 'the same command after compaction');
+    assert.ok(reheld.reason.includes(DOCTRINE_BODY), 'guidance the transcript no longer carries is delivered again');
+});
+test('a corpus with no pre-command doc never reaches the daemon', async () => {
+    writeDoctrineDoc('command');
+    seedNode('gate-quiet');
+    const pi = registerSubstrate();
+    // No daemon. Every path below must return before the subject lookup; one that
+    // does not fails loud with `daemon_unavailable` instead of passing quietly.
+    await closeServer();
+    assert.equal(await pi.toolCall('read', { file: '/tmp/x' }), undefined, 'a non-bash call is not the gate’s business');
+    assert.equal(await pi.toolCall('bash', { command: '   ' }), undefined, 'a bash call carrying no command is not held');
+    assert.equal(await pi.bash('deploy prod'), undefined, 'a post-execution `command` doc never holds anything');
+});

package/dist/pi-extensions/broker-local.js

@@ -3,6 +3,7 @@
 // These helpers are intentionally independent of the canvas state store. A
 // broker may read its own context files directly, but all node metadata reads
 // and generated-name writes go through crtrd's broker operation projection.
+import { envHomeOverride } from '../shared/env.js';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
@@ -14,7 +15,7 @@ function contextDir(nodeId) {
     if (nodeId === '' || nodeId === '.' || nodeId === '..' || /[\\/\0]/u.test(nodeId)) {
         throw new TypeError('node_id must be a non-empty path segment');
     }
-    const canvasHome = process.env['CRTR_HOME']?.trim() || join(homedir(), CRTR_DIR_NAME, 'canvas');
+    const canvasHome = envHomeOverride()?.trim() || join(homedir(), CRTR_DIR_NAME, 'canvas');
     return join(canvasHome, 'nodes', nodeId, 'context');
 }
 /** Persist a bare root's first real interactive message without clobbering an

package/dist/pi-extensions/canvas-bash-valve.js

@@ -24,6 +24,7 @@
 // Deviation from upstream: this backend pins `bash` as the shell (upstream
 // consults user shell config via non-exported helpers). Acceptable — crtr's
 // agents are bash-contract anyway.
+import { envBashValveMs, envNodeId } from '../shared/env.js';
 import { spawn } from 'node:child_process';
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, rmSync, statSync, writeFileSync, } from 'node:fs';
 import { homedir } from 'node:os';
@@ -34,20 +35,12 @@ import { PREVIEW_RESULT_PATH_ENV, previewResultPath } from '../core/preview-resu
 import { resolveAdmittedHostCommand } from '../core/runtime/spawn-env.js';
 import { Type } from 'typebox';
 import { createBashToolDefinition } from '@earendil-works/pi-coding-agent';
-// ---------------------------------------------------------------------------
 // Deadline — 5 minutes by default, overridable via CRTR_BASH_VALVE_MS
 // (undocumented; test-only seam so the E2E valve check doesn't sleep 5m).
-// ---------------------------------------------------------------------------
-const DEFAULT_VALVE_MS = 5 * 60 * 1000;
 const POLL_MS = 200;
 function resolveValveMs() {
-    const raw = process.env['CRTR_BASH_VALVE_MS'];
-    if (raw === undefined)
-        return DEFAULT_VALVE_MS;
-    const n = Number(raw);
-    return Number.isFinite(n) && n > 0 ? n : DEFAULT_VALVE_MS;
+    return envBashValveMs();
 }
-// ---------------------------------------------------------------------------
 // The detached supervisor. Spawned with `detached: true` so it becomes its
 // own process-group leader (pgid === its pid) — killing `-pgid` reaches the
 // real command and anything it forked, even after this pi process exits.
@@ -59,7 +52,6 @@ function resolveValveMs() {
 //
 // `--` before the paths is a dummy $0 (a standard `bash -c script -- args`
 // idiom) so the real payload lands at $1 onward.
-// ---------------------------------------------------------------------------
 // The elapsed rendering mirrors formatBashElapsed() in core/bash-jobs.ts
 // (`12s` / `3m 40s` / `1h 04m`) so the completion message reads the same as the
 // handoff notice; it measures TOTAL runtime, foreground portion included.
@@ -166,12 +158,10 @@ function readExitCode(path) {
         return null;
     }
 }
-// ---------------------------------------------------------------------------
 // Long-sleep guard. A command that opens with `sleep <long>` is a node burning
 // a live window to wait on a clock — the runtime already has waiting primitives
 // that cost nothing (`crtr cron` for a scheduled wake, `crtr node wait deadline`
 // for an inbox-vs-deadline race). Anything over 10s is refused before it runs.
-// ---------------------------------------------------------------------------
 const MAX_INLINE_SLEEP_SECONDS = 10;
 const SLEEP_UNIT_SECONDS = { s: 1, m: 60, h: 3600, d: 86400 };
 /** Seconds a leading `sleep ...` will block for, or null when the command does
@@ -371,10 +361,7 @@ export function createValveOperations(nodeId, contextDir, takePurpose = () => nu
         },
     };
 }
-// ---------------------------------------------------------------------------
 // Extension
-// ---------------------------------------------------------------------------
-// ---------------------------------------------------------------------------
 // `purpose` — the one line a person reads while a command runs
 //
 // An optional deviation from taking pi's definition verbatim, and the only one
@@ -396,7 +383,6 @@ export function createValveOperations(nodeId, contextDir, takePurpose = () => nu
 // Upstream ask: pi's own bash tool should carry this (Claude Code's bash tool
 // has shipped an equivalent `description` field for years). Until it does, the
 // field is re-declared here on top of pi's schema rather than forked into it.
-// ---------------------------------------------------------------------------
 const PURPOSE_DESCRIPTION = [
     'One short clause naming what this step is FOR, in the words of the person you',
     'are working for — "Reading the Acme thread", not "Fetching emails" and never',
@@ -437,7 +423,7 @@ export function createValveToolDefinition(nodeId, contextDir, cwd, exposePurpose
     return { ...schemaDefinition, execute };
 }
 export default function (pi) {
-    const nodeId = process.env['CRTR_NODE_ID'];
+    const nodeId = envNodeId();
     if (nodeId === undefined || nodeId.trim() === '')
         return; // inert — builtin bash stays
     const contextDir = process.env['CRTR_CONTEXT_DIR'];

package/dist/pi-extensions/canvas-context-intro.js

@@ -22,6 +22,7 @@
 //
 // Plain TS-with-types — no imports from @earendil-works/* so this compiles inside
 // crouter's own tsc build without a dep on the pi packages.
+import { envNodeId } from '../shared/env.js';
 import { CONTEXT_INTRO_CUSTOM_TYPE, formatCard, parseCard } from '../shared/generated-context.js';
 import { brokerExtensionState } from '../core/runtime/broker/daemon-ops.js';
 import { buildContextBearingsFromState, buildForkBearingsFromState, buildProjectContextBlockForBroker, renderPreferencesFromState, } from '../core/runtime/broker-extension-render.js';
@@ -35,9 +36,7 @@ import { truncateToWidth } from './truncate.js';
  *  the block builder in `core/runtime/bearings.ts` because the warm-pool claim's
  *  live delivery needs it too; re-exported here as this module's own surface. */
 export { CONTEXT_INTRO_CUSTOM_TYPE };
-// ---------------------------------------------------------------------------
 // Block builder
-// ---------------------------------------------------------------------------
 /** Build the full bearings baseline for a conversation without inherited
  *  crouter context. Exported for testing. */
 export async function buildContextIntro(nodeId, target) {
@@ -50,9 +49,7 @@ export async function buildForkContextIntro(nodeId) {
     const state = await brokerExtensionState(nodeId);
     return buildForkBearingsFromState(state, situationalContextEnvelope(nodeId) ?? '');
 }
-// ---------------------------------------------------------------------------
 // Collapsed-by-default rendering
-// ---------------------------------------------------------------------------
 /** Pull the plain text out of a custom message's content (string or blocks). */
 function messageText(message) {
     if (typeof message.content === 'string')
@@ -127,16 +124,14 @@ export function renderContextMessage(message, options, theme) {
         },
     };
 }
-// ---------------------------------------------------------------------------
 // Extension
-// ---------------------------------------------------------------------------
 /** Register new-context baseline assembly; a strict resume changes nothing. */
 export function registerCanvasContextIntro(pi) {
     // Collapse the block to a one-liner until the user expands tool output (Ctrl+O).
     // Harmless to register outside TUI mode (it's only consulted while rendering).
     pi.registerMessageRenderer(CONTEXT_INTRO_CUSTOM_TYPE, renderContextMessage);
     pi.on('session_start', async (event, ctx) => {
-        const nodeId = process.env['CRTR_NODE_ID'];
+        const nodeId = envNodeId();
         if (nodeId === undefined || nodeId.trim() === '')
             return;
         const reason = event?.reason;

package/dist/pi-extensions/canvas-doc-substrate.d.ts

@@ -29,9 +29,23 @@ interface ToolResultCtxLike {
 type ToolResultResultLike = {
     content: ContentBlockLike[];
 } | void;
+/** tool_call: fired BEFORE the tool runs. Returning `{block: true, reason}`
+ *  stops it — nothing executes, no `tool_result` fires, and `reason` becomes the
+ *  call's synthesized error result, carrying arbitrary-length text. */
+interface ToolCallEventLike {
+    toolName: string;
+    input?: unknown;
+}
+type ToolCallResultLike = {
+    block: true;
+    reason: string;
+} | void;
 interface PiLike {
     on(event: 'before_agent_start', handler: (event: BeforeAgentStartEventLike) => BeforeAgentStartResultLike | void | Promise<BeforeAgentStartResultLike | void>): void;
     on(event: 'session_start', handler: (event: unknown, ctx: unknown) => void | Promise<void>): void;
+    on(event: 'session_compact', handler: (event: unknown, ctx: unknown) => void | Promise<void>): void;
+    on(event: 'turn_end', handler: (event: unknown, ctx: unknown) => void | Promise<void>): void;
+    on(event: 'tool_call', handler: (event: ToolCallEventLike, ctx: unknown) => ToolCallResultLike | Promise<ToolCallResultLike>): void;
     on(event: 'tool_result', handler: (event: ToolResultEventLike, ctx: ToolResultCtxLike) => ToolResultResultLike | Promise<ToolResultResultLike>): void;
 }
 export declare function registerCanvasDocSubstrate(pi: PiLike): void;

package/dist/pi-extensions/canvas-doc-substrate.js

@@ -7,29 +7,62 @@
 //
 // before_agent_start splices the context's frozen preference snapshot after the
 // native tool list. Successful read/bash results append matching memory through
-// the shared context exposure state. Pure rendering lives in core/substrate/.
+// the shared context exposure state. A bash call matching a `pre-command` doc is
+// BLOCKED before it runs and the doc comes back as its synthesized error result.
+// Pure rendering lives in core/substrate/.
 //
 // Plain TS-with-types — NO imports from @earendil-works/* (a local structural
 // PiLike interface stands in), so it compiles inside crouter's own tsc build
 // with no dep on the pi packages. Mirrors canvas-context-intro.ts.
+import { envNodeId } from '../shared/env.js';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { brokerExtensionState } from '../core/runtime/broker/daemon-ops.js';
 import { renderPreferencesFromState } from '../core/runtime/broker-extension-render.js';
-import { renderOnCommandDocsForSubject, renderOnReadDocsForSubject } from '../core/substrate/on-read.js';
+import { corpusHasPreCommandSurfaces, demotePreCommandExposures, renderOnCommandDocsForSubject, renderOnReadDocsForSubject, renderPreCommandDocsForSubject, } from '../core/substrate/on-read.js';
 import { clearSessionCache } from '../core/substrate/session-cache.js';
 import { cloneContextExposureState, exposureTarget, freezePreferenceSnapshot, loadContextExposureState, mergeContextExposureState, replaceContextExposureState, saveContextExposureState, sharedContextExposureState, } from '../core/substrate/injected-store.js';
 import { autoLoadedContextInner, mergeAutoLoadedContext } from './envelope-merge.js';
-// ---------------------------------------------------------------------------
 // Extension
-// ---------------------------------------------------------------------------
 /** The stable seam that closes pi's native "Available tools" list. We splice the
  *  substrate's boot sections right before it — the agent decides which capability
  *  to reach for while reading the tools, so memory docs/preferences must sit
  *  there, not far below. Falls back to appending if absent. */
 const TOOLS_ANCHOR = '\n\nGuidelines:';
+/** The bash command string a tool call carries, or `null` when there is none. */
+function bashCommandOf(input) {
+    const command = input?.command;
+    return typeof command === 'string' && command.trim() !== '' ? command : null;
+}
+/** The blocked call's synthesized error result. A blocked command is discarded
+ *  IN FULL — pi executes none of it — so the copy must steer a re-issue of the
+ *  WHOLE command, never of one clause: when the same command also built its own
+ *  input (a heredoc, a `>` redirect, a `$(…)`), that setup did not run either,
+ *  and re-issuing only the tail would act on stale or missing data. */
+function heldReason(rendered) {
+    return [
+        'HELD — nothing ran.',
+        '',
+        'Your bash command was NOT executed. It matched memory you had not yet read, and that memory is below.',
+        '',
+        'Read it, then re-issue your WHOLE command unchanged — every clause of it, including any heredoc, redirect, or `$(…)` that built its input, because none of that ran either. The re-issue executes: this memory is now in your transcript, so there is nothing left to deliver and nothing left to hold.',
+        '',
+        rendered,
+    ].join('\n');
+}
+/** The follow-on notice for a SIBLING command in the same assistant message.
+ *  pi preflights siblings sequentially and then executes them concurrently, so
+ *  without one flag per turn the second sibling would find the doc already
+ *  exposed and slip past the hold its sibling just raised. */
+const HELD_SIBLING_REASON = [
+    'HELD — nothing ran.',
+    '',
+    'Your bash command was NOT executed. Another command in this same message was held against memory you had not read, and that memory was returned with it.',
+    '',
+    'Read it, then re-issue your WHOLE command unchanged. The re-issue executes.',
+].join('\n');
 export function registerCanvasDocSubstrate(pi) {
-    const nodeId = process.env['CRTR_NODE_ID'];
+    const nodeId = envNodeId();
     if (nodeId === undefined || nodeId.trim() === '')
         return; // not a canvas node — inert
     // One in-place state object is shared with context-intro and rehydrated on a
@@ -57,6 +90,45 @@ export function registerCanvasDocSubstrate(pi) {
             systemPrompt: `${event.systemPrompt.slice(0, idx)}\n\n${block}${event.systemPrompt.slice(idx)}`,
         };
     });
+    // One flag per assistant turn: the first hold covers every matching command
+    // in the same message.
+    let blockedThisTurn = false;
+    pi.on('turn_end', () => {
+        blockedThisTurn = false;
+    });
+    // Compaction drops delivered guidance out of the transcript while the ledger
+    // still records it as delivered. Forget those deliveries so the holds re-arm.
+    pi.on('session_compact', () => {
+        mergeContextExposureState(contextExposure, loadContextExposureState(nodeId));
+        demotePreCommandExposures(contextExposure);
+        saveContextExposureState(nodeId, contextExposure);
+        blockedThisTurn = false;
+    });
+    pi.on('tool_call', async (event) => {
+        if (event.toolName !== 'bash')
+            return;
+        const command = bashCommandOf(event.input);
+        if (command === null)
+            return;
+        // The common case is a corpus with no pre-command doc at all, and it must
+        // cost nothing — short-circuit before the daemon round-trip below.
+        if (!corpusHasPreCommandSurfaces())
+            return;
+        if (blockedThisTurn)
+            return { block: true, reason: HELD_SIBLING_REASON };
+        const state = await brokerExtensionState(nodeId);
+        mergeContextExposureState(contextExposure, loadContextExposureState(nodeId));
+        const next = cloneContextExposureState(contextExposure);
+        const rendered = renderPreCommandDocsForSubject(state.subject, command, exposureTarget(next, 'transcript'));
+        // Everything this command matches is already in the transcript: the hold is
+        // released and the command runs.
+        if (rendered === '')
+            return;
+        blockedThisTurn = true;
+        saveContextExposureState(nodeId, next);
+        replaceContextExposureState(contextExposure, next);
+        return { block: true, reason: heldReason(rendered) };
+    });
     pi.on('tool_result', async (event, ctx) => {
         if (event.isError === true)
             return;

package/dist/pi-extensions/canvas-goal-capture.js

@@ -29,6 +29,7 @@
 //
 // Plain TS-with-types — no imports from @earendil-works/* so this compiles inside
 // crouter's own tsc build without a dep on the pi packages.
+import { envNodeId } from '../shared/env.js';
 import { captureGoalIfAbsent, generateAndCommitInitialName, } from './broker-local.js';
 import { parseCard } from '../shared/generated-context.js';
 /**
@@ -41,7 +42,7 @@ import { parseCard } from '../shared/generated-context.js';
 export function registerCanvasGoalCapture(pi) {
     pi.on('input', (event) => {
         try {
-            const nodeId = process.env['CRTR_NODE_ID'];
+            const nodeId = envNodeId();
             if (nodeId === undefined || nodeId.trim() === '')
                 return; // not a canvas node
             const text = (event.text ?? '').trim();