@north-light/crouter 0.3.232 → 0.3.233

package/dist/builtin-memory/internal/memory-loading.md

@@ -9,7 +9,7 @@ surfaces:
 
 # How memory loads
 
-Every memory doc declares its own delivery in frontmatter `surfaces` entries; the runtime never guesses. Delivery is five events, one rung per entry, document and entry gates, and structural ordering. The authoring contract (flags, routing-line craft) is `crtr memory write -h`; which scope to write to is `internal/agent-shaping`; physical paths are `internal/storage-tiers`. This doc is the mechanics between those: what actually fires, when, and in what order.
+Every memory doc declares its own delivery in frontmatter `surfaces` entries; the runtime never guesses. Delivery is six events, one rung per entry, document and entry gates, and structural ordering. The authoring contract (flags, routing-line craft) is `crtr memory write -h`; which scope to write to is `internal/agent-shaping`; physical paths are `internal/storage-tiers`. This doc is the mechanics between those: what actually fires, when, and in what order.
 
 ## Surfaces entries
 
@@ -19,7 +19,8 @@ A doc with no `surfaces` does exactly one thing: appears in its directory's list
 - **workspace-open** — first-message context when cwd/profile mounts the doc's project store. Project stores only.
 - **read** — a `read` tool call returned a matching file: path globs vs the file's absolute path and basename, `./`-anchored globs vs its path relative to the store's owning repo dir, `match-frontmatter` predicates over the read file's own YAML frontmatter.
 - **memory-read** — a `crtr memory read` resolved a matching doc: name globs vs its canonical name, `./` anchored to this doc's canonical routing anchor (a collapsed directory document anchors at its own directory name).
-- **command** — a matching shell command ran: globs vs the whole command string, `*` crossing `/`. Delivery is post-execution — right for "you are now in this territory," never for "don't run this at all."
+- **command** — a matching shell command ran: globs vs the whole command string, `*` crossing `/`. Delivery is post-execution — right for "you are now in this territory"; when the point is "don't run this at all," use `pre-command` instead.
+- **pre-command** — a matching `bash` command is about to run. When the memory has not been read yet, the command does not execute — the memory comes back as the tool result instead, and the agent re-issues the command, which then runs. Use it to guarantee a memory is seen before a sensitive action is taken. Same globs as `command`, matched at command position; `match` is required. A guardrail against the faithful-but-uninformed action, not an enforcement boundary.
 
 Nothing positional fires from where a doc happens to sit on disk — only from its declared entries and its listing.
 
@@ -49,7 +50,7 @@ At boot/first-message assembly the runtime mounts: builtin docs, the user store
 
 Each project the selected profile has a relationship with carries a `memory` value — `none`, `name`, `preview`, or `content` — and that value is the maximum rung anything in that project's stores delivers at boot and workspace-open, whatever directory the node is working in. It only lowers: an entry authored below the maximum delivers at its authored rung. `none` contributes nothing to either automatic event, so a `none` project cannot shadow a same-named doc from a wider scope — that wider doc becomes the winner. A project store the selected profile has no relationship with delivers exactly what it authored.
 
-The maximum reaches those two events and nothing else. Read, memory-read, and command entries fire at their authored rungs; directory listings, `crtr memory read`, `crtr memory find`, config resolution, and plugin discovery all see the full corpus. An explicit `crtr memory read` is itself a content delivery, so reading a capped or document-gated doc returns its whole body and records content — the upgrade path for a doc the automatic events disclosed only by name or preview. Entry gates apply to companion docs routed by the `memory-read` event, not to the deliberate read or its listings.
+The maximum reaches those two events and nothing else. Read, memory-read, command, and pre-command entries fire at their authored rungs; directory listings, `crtr memory read`, `crtr memory find`, config resolution, and plugin discovery all see the full corpus. An explicit `crtr memory read` is itself a content delivery, so reading a capped or document-gated doc returns its whole body and records content — the upgrade path for a doc the automatic events disclosed only by name or preview. Entry gates apply to companion docs routed by the `memory-read` event, not to the deliberate read or its listings.
 
 A workspace's front door is an ordinary doc carrying the entry pair `{on: workspace-open, at: content}` + `{on: read, match: "./**", at: content}` — the operating guide loads when that workspace mounts or its files are read, not in every boot catalog. `crtr memory lint` requires exactly one workspace-open content doc per profile-managed project store. Multiple mounted roots render broad-to-specific.
 

package/dist/commands/memory/shared.d.ts

@@ -194,7 +194,7 @@ export declare function overlayParam(name: string, overrides?: Partial<FlagParam
  *  `--doc-rationale`, because `--rationale` there means why THIS REVISION is
  *  happening. Same field, same prose, two flag names that cannot be confused. */
 export declare const DOC_RATIONALE_CONSTRAINT = "Frontmatter rationale \u2014 the observed agent failure that made this doc necessary. Maintainer-facing only: never ships in any delivered surface (boot render, on-read injection, `memory read` content), visible only via `memory read --frontmatter`. Omitting the flag preserves an existing rationale unchanged.";
-export declare const GUIDE_SURFACES = "Every doc appears in its directory\u2019s listing by default (suppress with --unlisted); everything beyond the listing is explicit `surfaces` routing \u2014 entries declaring WHEN the doc delivers and how much. Events: `boot` delivers in the boot catalog every agent sees; `workspace-open` delivers in first-message context when cwd/profile mounts the doc\u2019s project store (project stores only); `read` fires when the agent reads a matching file (globs vs the file\u2019s absolute path and basename, `./`-anchored globs vs its path relative to the store\u2019s owning repo dir, `match-frontmatter` predicates over the read file\u2019s own YAML frontmatter); `memory-read` fires when another memory doc is read (globs vs that doc\u2019s canonical name, `./` anchored to this doc\u2019s routing anchor \u2014 its own canonical name when it is its directory\u2019s document, otherwise the canonical directory it sits in); `command` fires when a matching shell command runs (globs vs each shell segment of the command line \u2014 split on `&&`/`||`/`;`/`|`/newlines outside quotes, leading `VAR=value` assignments dropped \u2014 where `*` spans whole whitespace-separated tokens and never part of one, `?` is one character inside a token, and quoted argument text is opaque, so `*git commit*` fires for `cd x && git commit -m \"\u2026\"` but not for `git commit-tree` or an `echo` that merely mentions it). An entry may also carry `gate`, a node-config predicate using the same vocabulary as the document-level `gate`: event constraints and entry gate both must match, then all participating entries fold to the highest `at` (`content` > `preview` > `name`), with no cross-entry deny precedence. The document-level `gate` remains the hard eligibility check: when it fails, no automatic surface can deliver the document. `at` sets how much delivers: `name` the bare tag, `preview` the routing line, `content` the whole body. Explicit `memory read` and listings remain deliberate access and ignore gates/rungs; only companion docs routed by their `memory-read` entries use entry gates. Each entry is paid by every future agent it fires on, so default down: no surfaces at all is correct for reference depth reached through listings and [[links]], and when a doc fits in a single sentence, deliver `content` directly \u2014 a `preview` routing line would run longer than the doc itself. Sentence-length `content` docs are correct; never pad a memory to be more verbose than the rule or fact it carries.";
+export declare const GUIDE_SURFACES = "Every doc appears in its directory\u2019s listing by default (suppress with --unlisted); everything beyond the listing is explicit `surfaces` routing \u2014 entries declaring WHEN the doc delivers and how much. Events: `boot` delivers in the boot catalog every agent sees; `workspace-open` delivers in first-message context when cwd/profile mounts the doc\u2019s project store (project stores only); `read` fires when the agent reads a matching file (globs vs the file\u2019s absolute path and basename, `./`-anchored globs vs its path relative to the store\u2019s owning repo dir, `match-frontmatter` predicates over the read file\u2019s own YAML frontmatter); `memory-read` fires when another memory doc is read (globs vs that doc\u2019s canonical name, `./` anchored to this doc\u2019s routing anchor \u2014 its own canonical name when it is its directory\u2019s document, otherwise the canonical directory it sits in); `command` fires when a matching shell command runs (globs vs each shell segment of the command line \u2014 split on `&&`/`||`/`;`/`|`/newlines outside quotes, leading `VAR=value` assignments dropped \u2014 where `*` spans whole whitespace-separated tokens and never part of one, `?` is one character inside a token, and quoted argument text is opaque, so `*git commit*` fires for `cd x && git commit -m \"\u2026\"` but not for `git commit-tree` or an `echo` that merely mentions it); `pre-command` fires BEFORE a matching bash command runs (same matching): when the memory has not been read yet, the command does not execute \u2014 the memory comes back as the tool result instead, and the agent re-issues the command, which then runs. Use it to guarantee a memory is seen before a sensitive action is taken. Requires `match`. An entry may also carry `gate`, a node-config predicate using the same vocabulary as the document-level `gate`: event constraints and entry gate both must match, then all participating entries fold to the highest `at` (`content` > `preview` > `name`), with no cross-entry deny precedence. The document-level `gate` remains the hard eligibility check: when it fails, no automatic surface can deliver the document. `at` sets how much delivers: `name` the bare tag, `preview` the routing line, `content` the whole body. Explicit `memory read` and listings remain deliberate access and ignore gates/rungs; only companion docs routed by their `memory-read` entries use entry gates. Each entry is paid by every future agent it fires on, so default down: no surfaces at all is correct for reference depth reached through listings and [[links]], and when a doc fits in a single sentence, deliver `content` directly \u2014 a `preview` routing line would run longer than the doc itself. Sentence-length `content` docs are correct; never pad a memory to be more verbose than the rule or fact it carries.";
 export declare const GUIDE_ROUTING_LINE = "The routing line (--when-and-why-to-read) is the only text an agent reads before deciding to load the doc. The test for its when-clause: it names an observable circumstance in the reader\u2019s current work, not the doc\u2019s topic reworded as an activity. If the WHEN can be inferred from the title alone, it is not a real trigger. Bad on a todo list: \"When planning or prioritizing work across this profile.\" Good: \"When the user mentions something from their todos, or asks what is still outstanding across this profile.\" The test for its because-clause: if it can be derived by paraphrasing the doc\u2019s advice, it is a restatement, not a payoff \u2014 a real payoff names a consequence in the reader\u2019s world that the document itself never asserts. Bad: \"because only genuine first principles belong in taste memory.\" Bad: \"because keeping the test loop fast and free of speculative tests protects the development pace\" \u2014 the doc\u2019s rule as an outcome, derivable straight from its advice. Good: \"because identifying throughlines in user taste lets future decisions be made faster and with less re-litigation.\" Someone mid-task who has not read the doc must be able to decide from this line alone whether the read is worth it. If you cannot name the concrete situation that triggers it, you do not yet understand the memory \u2014 ask the user one sharp question instead of improvising.";
 export declare const GUIDE_PREDICATE_VOCABULARY = "Document gates, surface-entry gates, and match-frontmatter share the same predicate language: a field map is AND-ed across fields; dotted fields resolve nested values; field matchers may be scalar, array, or object. Scalar matchers do exact equality, with arrays matching any element. Array matchers do membership or intersection. Object matchers accept `eq`, `ne`, `in`, `nin`, `exists`, `contains`, `containsAll`, `containsAny`, `matches`, `imatches`, `gt`, `gte`, `lt`, and `lte`. Combinators are `all`, `any`, and `not`; sibling field matchers next to them are AND-ed in. An empty condition is inert. An unknown op never matches.";
 export declare const GUIDE_DOC_LINKS = "Link related docs with `[[canonical/name]]`. A doc link in any body is a first-class cross-reference to another memory document by its exact canonical name \u2014 the same identifier `crtr memory read` takes, namespace included for a project document. A bare directory name is a valid link too: following it returns that directory\u2019s own document when it has one, plus the directory listing. Links are pointers, never transclusion: the linked body is loaded only when a reader follows it, so a link costs nothing until needed. `crtr memory lint` fails on a link that resolves to no document or directory, and `crtr memory read` lists a doc\u2019s resolvable links alongside its body. There is no alias, label, or old-name form \u2014 a renamed target needs its links rewritten.";

package/dist/commands/memory/shared.js

@@ -436,7 +436,7 @@ export function coerceSurface(raw) {
             throw usage(`--surface: invalid \`match-frontmatter\`: ${JSON.stringify(matchFrontmatter)} (expected a field→matcher object)`);
         }
     }
-    if ((on === 'read' || on === 'memory-read' || on === 'command') && match === undefined && matchFrontmatter === undefined) {
+    if ((on === 'read' || on === 'memory-read' || on === 'command' || on === 'pre-command') && match === undefined && matchFrontmatter === undefined) {
         throw usage(`--surface: a \`${on}\` entry requires \`match\`${on === 'read' ? ' or `match-frontmatter`' : ''}`);
     }
     const gate = rec['gate'];
@@ -768,7 +768,7 @@ export const FRONTMATTER_OVERLAY_PARAMS = {
     'when-and-why-to-read': { kind: 'flag', name: 'when-and-why-to-read', type: 'string', required: false, constraint: 'ONE routing sentence: "When <circumstance>, this <kind> should be read because <broader downstream payoff>." WHY is the reader\u2019s payoff \u2014 the consequence they secure for their task by reading \u2014 NEVER the doc summary, its rule, or that rule reworded as an outcome (a benefit-shaped restatement still fails). Rendered verbatim as the preview.' },
     'short-form': { kind: 'flag', name: 'short-form', type: 'string', required: false, constraint: 'Frontmatter short-form \u2014 a very abbreviated version of the content, the hook shown in `crtr memory list`.' },
     'unlisted': { kind: 'flag', name: 'unlisted', type: 'bool', required: false, default: false, constraint: 'Suppress this doc from directory listings. Suppression only — explicit reads, [[links]], and surfaces entries still work.' },
-    'surface': { kind: 'flag', name: 'surface', type: 'string', required: false, repeatable: true, constraint: 'One routing entry per occurrence, as a YAML/JSON object `{on, at, match?, match-frontmatter?, gate?}`; the flag set replaces the document’s whole surfaces list. `on` is boot|workspace-open|read|memory-read|command; `at` is name|preview|content. `match` holds the event’s globs — required on read/memory-read/command (a read entry may carry `match-frontmatter`, a predicate over the read file’s own frontmatter, instead), meaningless on boot/workspace-open. Optional entry `gate` is a node-config predicate using the same vocabulary as the document gate; its event constraints and gate both match before it participates. A `./`-anchored glob is relative: for `read` to the store’s owning repo dir, for `memory-read` to this doc’s routing anchor — its own canonical name when the doc is its directory’s document (`<dir>/INDEX.md`), otherwise the canonical directory it sits in. Participating entries fold to their highest `at`; there is no cross-entry deny precedence.' },
+    'surface': { kind: 'flag', name: 'surface', type: 'string', required: false, repeatable: true, constraint: 'One routing entry per occurrence, as a YAML/JSON object `{on, at, match?, match-frontmatter?, gate?}`; the flag set replaces the document’s whole surfaces list. `on` is boot|workspace-open|read|memory-read|command|pre-command; `at` is name|preview|content. `match` holds the event’s globs — required on read/memory-read/command/pre-command (a read entry may carry `match-frontmatter`, a predicate over the read file’s own frontmatter, instead), meaningless on boot/workspace-open. Optional entry `gate` is a node-config predicate using the same vocabulary as the document gate; its event constraints and gate both match before it participates. A `./`-anchored glob is relative: for `read` to the store’s owning repo dir, for `memory-read` to this doc’s routing anchor — its own canonical name when the doc is its directory’s document (`<dir>/INDEX.md`), otherwise the canonical directory it sits in. Participating entries fold to their highest `at`; there is no cross-entry deny precedence.' },
     'gate': { kind: 'flag', name: 'gate', type: 'string', required: false, constraint: 'Frontmatter gate \u2014 YAML/JSON object predicate over node config using the same field/matcher vocabulary described in the guide.' },
     'slash': { kind: 'flag', name: 'slash', type: 'bool', required: false, default: false, constraint: 'Presence flags this doc invocable as a pi slash command (`/<name>`, `/` in a nested name rendered as `:`) \u2014 the doc body becomes the command\u2019s injected prompt. Default false: most docs are consulted, not invoked.' },
 };
@@ -786,7 +786,7 @@ export function overlayParam(name, overrides = {}, extraConstraint) {
  *  `--doc-rationale`, because `--rationale` there means why THIS REVISION is
  *  happening. Same field, same prose, two flag names that cannot be confused. */
 export const DOC_RATIONALE_CONSTRAINT = 'Frontmatter rationale \u2014 the observed agent failure that made this doc necessary. Maintainer-facing only: never ships in any delivered surface (boot render, on-read injection, `memory read` content), visible only via `memory read --frontmatter`. Omitting the flag preserves an existing rationale unchanged.';
-export const GUIDE_SURFACES = 'Every doc appears in its directory’s listing by default (suppress with --unlisted); everything beyond the listing is explicit `surfaces` routing — entries declaring WHEN the doc delivers and how much. Events: `boot` delivers in the boot catalog every agent sees; `workspace-open` delivers in first-message context when cwd/profile mounts the doc’s project store (project stores only); `read` fires when the agent reads a matching file (globs vs the file’s absolute path and basename, `./`-anchored globs vs its path relative to the store’s owning repo dir, `match-frontmatter` predicates over the read file’s own YAML frontmatter); `memory-read` fires when another memory doc is read (globs vs that doc’s canonical name, `./` anchored to this doc’s routing anchor — its own canonical name when it is its directory’s document, otherwise the canonical directory it sits in); `command` fires when a matching shell command runs (globs vs each shell segment of the command line — split on `&&`/`||`/`;`/`|`/newlines outside quotes, leading `VAR=value` assignments dropped — where `*` spans whole whitespace-separated tokens and never part of one, `?` is one character inside a token, and quoted argument text is opaque, so `*git commit*` fires for `cd x && git commit -m "…"` but not for `git commit-tree` or an `echo` that merely mentions it). An entry may also carry `gate`, a node-config predicate using the same vocabulary as the document-level `gate`: event constraints and entry gate both must match, then all participating entries fold to the highest `at` (`content` > `preview` > `name`), with no cross-entry deny precedence. The document-level `gate` remains the hard eligibility check: when it fails, no automatic surface can deliver the document. `at` sets how much delivers: `name` the bare tag, `preview` the routing line, `content` the whole body. Explicit `memory read` and listings remain deliberate access and ignore gates/rungs; only companion docs routed by their `memory-read` entries use entry gates. Each entry is paid by every future agent it fires on, so default down: no surfaces at all is correct for reference depth reached through listings and [[links]], and when a doc fits in a single sentence, deliver `content` directly — a `preview` routing line would run longer than the doc itself. Sentence-length `content` docs are correct; never pad a memory to be more verbose than the rule or fact it carries.';
+export const GUIDE_SURFACES = 'Every doc appears in its directory’s listing by default (suppress with --unlisted); everything beyond the listing is explicit `surfaces` routing — entries declaring WHEN the doc delivers and how much. Events: `boot` delivers in the boot catalog every agent sees; `workspace-open` delivers in first-message context when cwd/profile mounts the doc’s project store (project stores only); `read` fires when the agent reads a matching file (globs vs the file’s absolute path and basename, `./`-anchored globs vs its path relative to the store’s owning repo dir, `match-frontmatter` predicates over the read file’s own YAML frontmatter); `memory-read` fires when another memory doc is read (globs vs that doc’s canonical name, `./` anchored to this doc’s routing anchor — its own canonical name when it is its directory’s document, otherwise the canonical directory it sits in); `command` fires when a matching shell command runs (globs vs each shell segment of the command line — split on `&&`/`||`/`;`/`|`/newlines outside quotes, leading `VAR=value` assignments dropped — where `*` spans whole whitespace-separated tokens and never part of one, `?` is one character inside a token, and quoted argument text is opaque, so `*git commit*` fires for `cd x && git commit -m "…"` but not for `git commit-tree` or an `echo` that merely mentions it); `pre-command` fires BEFORE a matching bash command runs (same matching): when the memory has not been read yet, the command does not execute — the memory comes back as the tool result instead, and the agent re-issues the command, which then runs. Use it to guarantee a memory is seen before a sensitive action is taken. Requires `match`. An entry may also carry `gate`, a node-config predicate using the same vocabulary as the document-level `gate`: event constraints and entry gate both must match, then all participating entries fold to the highest `at` (`content` > `preview` > `name`), with no cross-entry deny precedence. The document-level `gate` remains the hard eligibility check: when it fails, no automatic surface can deliver the document. `at` sets how much delivers: `name` the bare tag, `preview` the routing line, `content` the whole body. Explicit `memory read` and listings remain deliberate access and ignore gates/rungs; only companion docs routed by their `memory-read` entries use entry gates. Each entry is paid by every future agent it fires on, so default down: no surfaces at all is correct for reference depth reached through listings and [[links]], and when a doc fits in a single sentence, deliver `content` directly — a `preview` routing line would run longer than the doc itself. Sentence-length `content` docs are correct; never pad a memory to be more verbose than the rule or fact it carries.';
 export const GUIDE_ROUTING_LINE = 'The routing line (--when-and-why-to-read) is the only text an agent reads before deciding to load the doc. The test for its when-clause: it names an observable circumstance in the reader\u2019s current work, not the doc\u2019s topic reworded as an activity. If the WHEN can be inferred from the title alone, it is not a real trigger. Bad on a todo list: "When planning or prioritizing work across this profile." Good: "When the user mentions something from their todos, or asks what is still outstanding across this profile." The test for its because-clause: if it can be derived by paraphrasing the doc\u2019s advice, it is a restatement, not a payoff \u2014 a real payoff names a consequence in the reader\u2019s world that the document itself never asserts. Bad: "because only genuine first principles belong in taste memory." Bad: "because keeping the test loop fast and free of speculative tests protects the development pace" \u2014 the doc\u2019s rule as an outcome, derivable straight from its advice. Good: "because identifying throughlines in user taste lets future decisions be made faster and with less re-litigation." Someone mid-task who has not read the doc must be able to decide from this line alone whether the read is worth it. If you cannot name the concrete situation that triggers it, you do not yet understand the memory \u2014 ask the user one sharp question instead of improvising.';
 export const GUIDE_PREDICATE_VOCABULARY = 'Document gates, surface-entry gates, and match-frontmatter share the same predicate language: a field map is AND-ed across fields; dotted fields resolve nested values; field matchers may be scalar, array, or object. Scalar matchers do exact equality, with arrays matching any element. Array matchers do membership or intersection. Object matchers accept `eq`, `ne`, `in`, `nin`, `exists`, `contains`, `containsAll`, `containsAny`, `matches`, `imatches`, `gt`, `gte`, `lt`, and `lte`. Combinators are `all`, `any`, and `not`; sibling field matchers next to them are AND-ed in. An empty condition is inert. An unknown op never matches.';
 export const GUIDE_DOC_LINKS = 'Link related docs with `[[canonical/name]]`. A doc link in any body is a first-class cross-reference to another memory document by its exact canonical name \u2014 the same identifier `crtr memory read` takes, namespace included for a project document. A bare directory name is a valid link too: following it returns that directory\u2019s own document when it has one, plus the directory listing. Links are pointers, never transclusion: the linked body is loaded only when a reader follows it, so a link costs nothing until needed. `crtr memory lint` fails on a link that resolves to no document or directory, and `crtr memory read` lists a doc\u2019s resolvable links alongside its body. There is no alias, label, or old-name form \u2014 a renamed target needs its links rewritten.';

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/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;

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

@@ -276,6 +276,53 @@ export function matchesCommandEntry(entry, subject, command) {
         return false;
     return entry.match.some((g) => commandGlobMatches(g, command));
 }
+const HEREDOC_OPEN = /<<(-?)\s*(["']?)([A-Za-z_][A-Za-z0-9_]*)\2/g;
+/** Remove heredoc BODIES (the stdin data between `<<DELIM` and its closing
+ *  `DELIM` line) from a command before it is 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 function stripHeredocs(command) {
+    const lines = command.split('\n');
+    const out = [];
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        out.push(line);
+        i += 1;
+        // Every heredoc opened on this line, left to right; their bodies stack and
+        // are consumed in that order.
+        const delims = [];
+        HEREDOC_OPEN.lastIndex = 0;
+        let m;
+        while ((m = HEREDOC_OPEN.exec(line)) !== null)
+            delims.push({ name: m[3], dash: m[1] === '-' });
+        for (const d of delims) {
+            while (i < lines.length) {
+                // `<<-` strips leading TABS from the body and the closing delimiter.
+                const probe = d.dash ? lines[i].replace(/^\t+/, '') : lines[i];
+                i += 1;
+                if (probe === d.name)
+                    break; // closing delimiter line — drop it, stop
+            }
+        }
+    }
+    return out.join('\n');
+}
+/** 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 function matchesPreCommandEntry(entry, subject, command) {
+    if (entry.on !== 'pre-command' || entry.match === undefined || !surfaceEntryGatePasses(entry, subject))
+        return false;
+    const stripped = stripHeredocs(command);
+    return entry.match.some((g) => commandGlobMatches(g, stripped));
+}
 // ---------------------------------------------------------------------------
 // Per-doc rung folds — a doc's delivery rung for one event occurrence is the
 // highest `at` over its matching entries of that event, `none` when none
@@ -331,3 +378,16 @@ export function commandDeliveryRung(doc, subject, command) {
     }
     return r;
 }
+/** 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 function preCommandDeliveryRung(doc, subject, command) {
+    let r = 'none';
+    for (const e of doc.surfaces) {
+        if (!matchesPreCommandEntry(e, subject, command))
+            continue;
+        if (rungRank(e.at) > rungRank(r))
+            r = e.at;
+    }
+    return r;
+}

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/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,7 +7,9 @@
 //
 // 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
@@ -16,7 +18,7 @@ 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';
@@ -28,6 +30,38 @@ import { autoLoadedContextInner, mergeAutoLoadedContext } from './envelope-merge
  *  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'];
     if (nodeId === undefined || nodeId.trim() === '')
@@ -57,6 +91,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.232",
+  "version": "0.3.233",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.232",
+  "version": "0.3.233",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.232",
+      "version": "0.3.233",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {