@north-light/crouter 0.3.207 → 0.3.209

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

@@ -1,32 +1,63 @@
-// injected-store.ts — durable per-node dedup set for on-read doc injection.
+// injected-store.ts — durable per-node dedup map for substrate doc delivery.
 //
-// The on-read substrate hook (canvas-doc-substrate.ts → renderOnReadDocs) dedups
-// so a given doc surfaces at most once per conversation. That set USED to live
-// only in the pi process heap, cleared on session_start. But a node's logical
-// session — the .jsonl transcript — spans MULTIPLE pi processes: a dormancy →
-// revive(resume) cycle exits the old process and launches a fresh `pi --session`
-// that REUSES the same transcript. The fresh process started with an empty set,
-// so any doc already injected before dormancy got injected AGAIN on the next
-// read — the "fires a second time per session" bug.
+// Delivery channels (boot render seeding, workspace-open, on-read, memory-read
+// listings and events, command events) dedup so a given doc surfaces at most
+// once per conversation AT A GIVEN DISCLOSURE. The map keys on realpath and
+// carries the highest rung rank delivered so far; higher rungs pierce lower —
+// a listing line (preview rank) must not block a later explicit content
+// delivery, while a content delivery silences everything after it. Directory
+// listings participate under the directory's own realpath (a directory never
+// collides with a file's realpath).
 //
-// This module persists the set to `nodes/<id>/injected-docs.json` so the resumed
-// process rehydrates it and skips docs already present in the transcript. The
-// one launch path that begins a FRESH transcript (reviveNode with resume=false,
-// in runtime/revive.ts) calls clearInjectedDocs(), so a new conversation starts
-// with an empty set.
+// The map USED to live only in the pi process heap, cleared on session_start.
+// But a node's logical session — the .jsonl transcript — spans MULTIPLE pi
+// processes: a dormancy → revive(resume) cycle exits the old process and
+// launches a fresh `pi --session` that REUSES the same transcript. This module
+// persists the map to `nodes/<id>/injected-docs.json` so the resumed process
+// rehydrates it and skips docs already present in the transcript. The one
+// launch path that begins a FRESH transcript (reviveNode with resume=false, in
+// runtime/revive.ts) calls clearInjectedDocs(), so a new conversation starts
+// empty. CLI processes (the `memory read` leaf) load/save the same file.
 //
-// All ops are best-effort: a failed read/write degrades to a possible re-inject,
-// never a crash — a dedup miss must never break a read or a revive.
+// Disk format: `{"v":2,"docs":{"<realpath>":<rank 1|2|3>}}` (rank =
+// rungRank of the delivered rung). A legacy v1 string-array rehydrates at
+// content rank — its entries were recorded under never-re-deliver semantics.
+//
+// All ops are best-effort: a failed read/write degrades to a possible
+// re-inject, never a crash — a dedup miss must never break a read or a revive.
 import { readFileSync, writeFileSync, rmSync } from 'node:fs';
 import { injectedDocsPath } from '../canvas/paths.js';
-/** Per-process cache behind `sharedInjectedDocs`: one Set instance per node,
+import { rungRank } from './schema.js';
+/** Already delivered at `rung` or above? — the skip test every channel runs
+ *  before rendering a doc (or a listing line, at preview) again. */
+export function deliveredAtOrAbove(seen, realpath, rung) {
+    const have = seen.get(realpath);
+    return have !== undefined && have >= rungRank(rung);
+}
+/** Record a delivery at `rung`, keeping the highest rank seen. */
+export function recordDelivery(seen, realpath, rung) {
+    const rank = rungRank(rung);
+    const have = seen.get(realpath);
+    if (have === undefined || have < rank)
+        seen.set(realpath, rank);
+}
+/** Max-merge `source` into `target` — used to fold an out-of-process delivery
+ *  (the daemon's warm-spare bearings push) into a live process's shared map. */
+export function mergeInjectedDocs(target, source) {
+    for (const [real, rank] of source) {
+        const have = target.get(real);
+        if (have === undefined || have < rank)
+            target.set(real, rank);
+    }
+}
+/** Per-process cache behind `sharedInjectedDocs`: one Map instance per node,
  *  shared by every extension in the pi process (context-intro's workspace-open
  *  render and doc-substrate's on-read hook), so a doc delivered by one hook is
- *  already in the set the other dedups against. */
+ *  already in the map the other dedups against. */
 const cache = new Map();
-/** The process-shared dedup set for a node: loaded from disk once, then the
- *  SAME Set instance on every call, so all hooks in this pi process grow and
- *  consult one set. Daemon-side deliveries (a warm-spare claim) write the disk
+/** The process-shared dedup map for a node: loaded from disk once, then the
+ *  SAME Map instance on every call, so all hooks in this pi process grow and
+ *  consult one map. Daemon-side deliveries (a warm-spare claim) write the disk
  *  file from another process; consumers that must see those merge the plain
  *  `loadInjectedDocs` result in before rendering. */
 export function sharedInjectedDocs(nodeId) {
@@ -37,31 +68,47 @@ export function sharedInjectedDocs(nodeId) {
     }
     return seen;
 }
-/** Rehydrate a node's on-read dedup set from disk. Returns an empty set when the
- *  file is absent, unreadable, or malformed (a fresh transcript, or a node that
- *  has not yet surfaced any on-read doc). */
+const CONTENT_RANK = rungRank('content');
+/** Rehydrate a node's dedup map from disk. Returns an empty map when the file
+ *  is absent, unreadable, or malformed (a fresh transcript, or a node that has
+ *  not yet surfaced any doc). */
 export function loadInjectedDocs(nodeId) {
     try {
-        const arr = JSON.parse(readFileSync(injectedDocsPath(nodeId), 'utf8'));
-        if (!Array.isArray(arr))
-            return new Set();
-        return new Set(arr.filter((x) => typeof x === 'string'));
+        const raw = JSON.parse(readFileSync(injectedDocsPath(nodeId), 'utf8'));
+        const out = new Map();
+        if (Array.isArray(raw)) {
+            // legacy v1: bare realpath array, never-re-deliver semantics
+            for (const x of raw)
+                if (typeof x === 'string')
+                    out.set(x, CONTENT_RANK);
+            return out;
+        }
+        if (raw !== null && typeof raw === 'object') {
+            const docs = raw.docs;
+            if (docs !== null && typeof docs === 'object' && !Array.isArray(docs)) {
+                for (const [real, rank] of Object.entries(docs)) {
+                    if (typeof rank === 'number' && rank >= 1 && rank <= CONTENT_RANK)
+                        out.set(real, rank);
+                }
+            }
+        }
+        return out;
     }
     catch {
-        return new Set();
+        return new Map();
     }
 }
-/** Persist a node's on-read dedup set. Called after each read that surfaced a
- *  new doc, so the grown set survives a later dormancy. */
+/** Persist a node's dedup map. Called after each delivery that grew it, so
+ *  the grown map survives a later dormancy. */
 export function saveInjectedDocs(nodeId, seen) {
     try {
-        writeFileSync(injectedDocsPath(nodeId), JSON.stringify([...seen]));
+        writeFileSync(injectedDocsPath(nodeId), JSON.stringify({ v: 2, docs: Object.fromEntries(seen) }));
     }
     catch {
         // best-effort — a failed persist only risks a re-inject, never a crash
     }
 }
-/** Drop a node's persisted dedup set. Called by the launch paths that start a
+/** Drop a node's persisted dedup map. Called by the launch paths that start a
  *  FRESH transcript, so the new conversation surfaces docs from scratch. */
 export function clearInjectedDocs(nodeId) {
     cache.delete(nodeId);

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

@@ -0,0 +1,21 @@
+import type { MemoryDoc } from '../memory-resolver.js';
+import { type InjectedDocs } from './injected-store.js';
+/** Dedup key for a whole directory's listing. Realpath keys start with `/`,
+ *  so the scheme prefix never collides with a doc entry. */
+export declare function dirDedupKey(dir: string): string;
+/** First-occurrence-wins name map over a precedence-ordered corpus: the doc
+ *  that renders a name's line is the doc a read of that name would return. */
+export declare function docsByName(corpus: readonly MemoryDoc[]): Map<string, MemoryDoc>;
+/** Is `name` a directory in the merged name tree — i.e. does any doc live
+ *  beneath it? The corpus root ('') is never a directory here: store roots
+ *  merge into the whole catalog, which `memory list` owns. */
+export declare function isDirName(byName: ReadonlyMap<string, MemoryDoc>, name: string): boolean;
+/** The dirs a doc read discloses: the doc's own directory, then each ancestor
+ *  walking up, the root excluded. `a/b/c` → `['a/b', 'a']`. */
+export declare function ancestorDirsOf(name: string): string[];
+/** Render one directory's listing lines: `[[name]]: <when-and-why>` per
+ *  member doc (bare `[[name]]` when the doc carries no routing line), a bare
+ *  `[[name]]` per subdirectory. `unlisted` members are omitted always;
+ *  `filterDelivered` additionally drops members already delivered at preview
+ *  rank or higher. Rendered members record at preview rank into `seen`. */
+export declare function renderDirListing(byName: ReadonlyMap<string, MemoryDoc>, dir: string, seen: InjectedDocs | null, filterDelivered: boolean): string[];

package/dist/core/substrate/listings.js

@@ -0,0 +1,88 @@
+// listings.ts — system-owned directory listings over the merged name tree.
+//
+// Reading a doc discloses where it sits: `ls` semantics over the corpus
+// namespace (directories merge across stores), consulting no frontmatter
+// except `unlisted`. A listing renders one when-and-why line per member doc
+// and one bare name per subdirectory — never recursive contents, never gates.
+//
+// Two render modes share one function. An EXPLICIT directory read (`crtr
+// memory read <dir>`) is a deliberate act, so every line renders (unlisted
+// excluded) — mirroring how an explicit doc read always returns content. The
+// AUTOMATIC neighborhood listings a doc read prepends are unsolicited, so
+// each member line dedup-filters against the transcript set and whole
+// directories dedup under a synthetic `dir://<name>` key (a name-tree
+// directory spans stores, so no single physical realpath identifies it).
+// Either mode records rendered member docs at preview rank — a listing line
+// IS a preview-rank render — when a dedup map is supplied.
+import { realpathOrSelf } from '../fs-utils.js';
+import { parseSubstrateDoc, previewLine } from './schema.js';
+import { deliveredAtOrAbove, recordDelivery } from './injected-store.js';
+/** Dedup key for a whole directory's listing. Realpath keys start with `/`,
+ *  so the scheme prefix never collides with a doc entry. */
+export function dirDedupKey(dir) {
+    return `dir://${dir}`;
+}
+/** First-occurrence-wins name map over a precedence-ordered corpus: the doc
+ *  that renders a name's line is the doc a read of that name would return. */
+export function docsByName(corpus) {
+    const byName = new Map();
+    for (const d of corpus)
+        if (!byName.has(d.name))
+            byName.set(d.name, d);
+    return byName;
+}
+/** Is `name` a directory in the merged name tree — i.e. does any doc live
+ *  beneath it? The corpus root ('') is never a directory here: store roots
+ *  merge into the whole catalog, which `memory list` owns. */
+export function isDirName(byName, name) {
+    if (name === '')
+        return false;
+    const prefix = name + '/';
+    for (const n of byName.keys())
+        if (n.startsWith(prefix))
+            return true;
+    return false;
+}
+/** The dirs a doc read discloses: the doc's own directory, then each ancestor
+ *  walking up, the root excluded. `a/b/c` → `['a/b', 'a']`. */
+export function ancestorDirsOf(name) {
+    const dirs = [];
+    const segs = name.split('/');
+    for (let i = segs.length - 1; i >= 1; i--)
+        dirs.push(segs.slice(0, i).join('/'));
+    return dirs;
+}
+/** Render one directory's listing lines: `[[name]]: <when-and-why>` per
+ *  member doc (bare `[[name]]` when the doc carries no routing line), a bare
+ *  `[[name]]` per subdirectory. `unlisted` members are omitted always;
+ *  `filterDelivered` additionally drops members already delivered at preview
+ *  rank or higher. Rendered members record at preview rank into `seen`. */
+export function renderDirListing(byName, dir, seen, filterDelivered) {
+    const prefix = dir + '/';
+    const memberLines = new Map();
+    const subdirs = new Set();
+    for (const [name, doc] of byName) {
+        if (!name.startsWith(prefix))
+            continue;
+        const rest = name.slice(prefix.length);
+        const slash = rest.indexOf('/');
+        if (slash >= 0) {
+            subdirs.add(rest.slice(0, slash));
+            continue;
+        }
+        const sub = parseSubstrateDoc(doc);
+        if (sub?.unlisted)
+            continue;
+        const real = realpathOrSelf(doc.path);
+        if (filterDelivered && seen !== null && deliveredAtOrAbove(seen, real, 'preview'))
+            continue;
+        const line = sub === null ? '' : previewLine(sub);
+        memberLines.set(rest, line === '' ? `[[${name}]]` : `[[${name}]]: ${line}`);
+        if (seen !== null)
+            recordDelivery(seen, real, 'preview');
+    }
+    return [
+        ...[...memberLines.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([, l]) => l),
+        ...[...subdirs].sort((a, b) => a.localeCompare(b)).map((s) => `[[${prefix}${s}]]`),
+    ];
+}

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

@@ -1,9 +1,9 @@
+import type { InjectedDocs } from './injected-store.js';
 /** Surface docs matched by a successful read tool call. An unknown node id or
  *  an unreadable canvas renders nothing. */
-export declare function renderOnReadDocs(nodeId: string, readFilePath: string, seen?: Set<string>): string;
+export declare function renderOnReadDocs(nodeId: string, readFilePath: string, seen?: InjectedDocs): string;
 /** Surface workspace-wide docs during first-message assembly, using the node's
- *  recorded cwd and selected profile. `.` is a reserved applies-to target
- *  meaning “when this project store is mounted by cwd/profile” (and, on the
- *  read event, “a file under the store's owning dir was read”). `seen` is the
+ *  recorded cwd and selected profile: docs in mounted project stores carrying
+ *  a `workspace-open` surfaces entry deliver here. `seen` is the
  *  transcript-scoped dedup set shared with the on-read hook. */
-export declare function renderWorkspaceOpenDocs(nodeId: string, seen?: Set<string>): string;
+export declare function renderWorkspaceOpenDocs(nodeId: string, seen?: InjectedDocs): string;

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

@@ -8,7 +8,7 @@ import { assembleNodeSubject } from './subject.js';
 import { renderOnReadDocsForSubject, renderWorkspaceOpenDocsForSubject } from './on-read.js';
 /** Surface docs matched by a successful read tool call. An unknown node id or
  *  an unreadable canvas renders nothing. */
-export function renderOnReadDocs(nodeId, readFilePath, seen = new Set()) {
+export function renderOnReadDocs(nodeId, readFilePath, seen = new Map()) {
     let subject;
     try {
         subject = assembleNodeSubject(nodeId);
@@ -21,11 +21,10 @@ export function renderOnReadDocs(nodeId, readFilePath, seen = new Set()) {
     return renderOnReadDocsForSubject(subject, readFilePath, seen);
 }
 /** Surface workspace-wide docs during first-message assembly, using the node's
- *  recorded cwd and selected profile. `.` is a reserved applies-to target
- *  meaning “when this project store is mounted by cwd/profile” (and, on the
- *  read event, “a file under the store's owning dir was read”). `seen` is the
+ *  recorded cwd and selected profile: docs in mounted project stores carrying
+ *  a `workspace-open` surfaces entry deliver here. `seen` is the
  *  transcript-scoped dedup set shared with the on-read hook. */
-export function renderWorkspaceOpenDocs(nodeId, seen = new Set()) {
+export function renderWorkspaceOpenDocs(nodeId, seen = new Map()) {
     try {
         const subject = assembleNodeSubject(nodeId);
         const node = getNode(nodeId);

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

@@ -1,9 +1,30 @@
+import { type InjectedDocs } from './injected-store.js';
+import { type Rung, type SubstrateDoc } from './schema.js';
 import type { NodeConfigSubject } from './subject-fields.js';
-/** Surface docs matched by a successful read tool call using the caller-supplied
- * daemon snapshot subject. */
-export declare function renderOnReadDocsForSubject(subject: NodeConfigSubject, readFilePath: string, seen?: Set<string>): string;
+/** Render candidates at their matched rungs, gate-checked and deduped against
+ *  the transcript set (higher rungs pierce lower; a delivery records at its
+ *  rendered rung). A `null` subject means no node identity is available for
+ *  gate evaluation: gated docs are skipped, ungated docs still deliver. */
+export declare function renderCandidateBlocks(subject: NodeConfigSubject | null, candidates: Array<{
+    doc: SubstrateDoc;
+    rung: Rung;
+}>, seen: InjectedDocs): string[];
+/** Surface docs whose `read` entries match a successfully read file, using
+ * the caller-supplied daemon snapshot subject. */
+export declare function renderOnReadDocsForSubject(subject: NodeConfigSubject, readFilePath: string, seen?: InjectedDocs): string;
 /** Workspace boot docs using the snapshot's cwd/profile instead of a canvas
  * lookup. `seen` is the transcript-scoped dedup set shared with the on-read
  * hook, so a front door delivered here never re-delivers on a later read
  * beneath its store. */
-export declare function renderWorkspaceOpenDocsForSubject(subject: NodeConfigSubject, cwd: string, profileId: string | null, seen?: Set<string>): string;
+export declare function renderWorkspaceOpenDocsForSubject(subject: NodeConfigSubject, cwd: string, profileId: string | null, seen?: InjectedDocs): string;
+/** Inner `<memory>` blocks for the memory-read event: docs whose
+ * `memory-read` entries match the doc a `crtr memory read` just resolved
+ * (known by `targetNames`; `excludeRealpath` keeps the resolved doc from
+ * delivering itself). Returns unwrapped blocks — the read leaf composes one
+ * `<auto-loaded-context>` envelope from these plus the directory listings. */
+export declare function memoryReadDocBlocks(subject: NodeConfigSubject | null, excludeRealpath: string, targetNames: string[], seen: InjectedDocs): string[];
+/** Surface docs whose `command` entries match an executed bash command
+ * string. The corpus is the resolved cwd/profile set only — a command has no
+ * file to walk enclosing stores from. `seen` is the same transcript-scoped
+ * dedup set as the other channels. */
+export declare function renderOnCommandDocsForSubject(subject: NodeConfigSubject, command: string, seen?: InjectedDocs): string;

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

@@ -1,45 +1,41 @@
-// on-read.ts — the pure file-context delivery functions for the document
-// substrate. Both take a caller-supplied subject; the canvas-db wrappers that
-// resolve one from a node id live in on-read-node.ts, so a consumer that
-// already holds a subject imports this module WITHOUT pulling subject.js's
-// canvas-db reach (the same split as render.ts / render-node.ts).
+// on-read.ts — the pure event-delivery renderers for the document substrate.
+// Each takes a caller-supplied subject; the canvas-db wrappers that resolve
+// one from a node id live in on-read-node.ts, so a consumer that already
+// holds a subject imports this module WITHOUT pulling subject.js's canvas-db
+// reach (the same split as render.ts / render-node.ts).
 //
-// A memory with file-read visibility participates only through an explicit
-// `applies-to` path glob (authoring lint requires one). Two events use that one
-// routing mechanism:
+// A doc participates through its `surfaces` entries (surface-match.ts owns
+// the per-entry matchers; this module folds them per doc and renders):
 //
-//   • A successful `read` tool call evaluates the read file against every
-//     visible substrate doc. Project stores encountered between that file and
-//     the filesystem root join the resolved cwd/profile corpus, so a nested
-//     workspace can contribute guidance exactly when a file beneath it is read.
-//     On this event the reserved `applies-to: "."` target means "the read file
-//     is under the doc's store's owning directory" — a nested store's front
-//     door surfaces on the first read beneath it, delivery driven purely by
-//     filesystem truth.
-//   • Opening a workspace evaluates the reserved `applies-to: "."` target for
-//     every project store mounted by the cwd and selected profile. This happens
-//     while the first-message bearings are assembled, so workspace-wide context
-//     arrives before the task rather than waiting for an arbitrary first file.
-//     Both hooks share one transcript-scoped dedup set, so a doc delivered at
-//     workspace open never re-delivers on a later matching read.
+//   • `read` — a successful read tool call evaluates the read file against
+//     every doc's `read` entries: path globs vs the absolute path and
+//     basename, `./`-anchored globs vs the path relative to the doc's store's
+//     owning repo dir (project stores only), `match-frontmatter` vs the read
+//     file's own YAML. Project stores encountered between the file and the
+//     filesystem root join the resolved cwd/profile corpus, so a nested
+//     workspace contributes guidance exactly when a file beneath it is read.
+//   • `workspace-open` — opening a workspace delivers docs carrying a
+//     `workspace-open` entry from every project store mounted by the cwd and
+//     selected profile, while the first-message bearings are assembled — so
+//     workspace-wide context arrives before the task rather than waiting for
+//     an arbitrary first file.
+//   • `command` — a `bash` tool call evaluates the executed command string
+//     against every doc's `command` entries (string globs, `*` crossing `/`).
 //
-// `read-when` remains an additional OR trigger over a read markdown file's own
-// frontmatter. It does not replace `applies-to`: every non-none file-read rung
-// still declares its path boundary explicitly.
-//
-// Every candidate renders at its own fileReadVisibility rung. Explicit routing
-// is the whole on-read model, so directory INDEX ceilings remain a boot-catalog
-// concern and do not cap a deliberately matched document.
+// All channels share one transcript-scoped (realpath → rung rank) dedup set,
+// so a doc delivered by one never re-delivers at the same or lower rung
+// through another. Each candidate renders at its matched rung — the highest
+// `at` over its matching entries for the event.
 import { homedir } from 'node:os';
-import { basename, dirname, isAbsolute, matchesGlob, parse, relative, sep } from 'node:path';
+import { dirname, parse, relative, sep } from 'node:path';
 import { CRTR_DIR_NAME } from '../../types.js';
 import { pathExists, readText, walkFiles } from '../fs-utils.js';
 import { parseFrontmatterGeneric } from '../frontmatter.js';
-import { evalCondition } from '../predicate.js';
 import { listAllMemoryDocs, listProjectMemoryDocs } from '../memory-resolver.js';
 import { userScopeRoot } from '../scope.js';
-import { displayName } from './ceiling.js';
 import { gatePasses } from './gate.js';
+import { commandDeliveryRung, memoryReadDeliveryRung, owningRootOf, readDeliveryRung, workspaceOpenRung } from './surface-match.js';
+import { deliveredAtOrAbove, recordDelivery } from './injected-store.js';
 import { normalizeDocName, parseSubstrateDoc, parseSubstrateFrontmatter, previewLine, resolveDocName } from './schema.js';
 import { cachedSubstrateDocs } from './session-cache.js';
 import { realpathOrSelf } from '../fs-utils.js';
@@ -75,13 +71,6 @@ function disp(p) {
 function isJunkAncestor(dir) {
     return dir.split(sep).some((segment) => JUNK_DIRS.has(segment));
 }
-function owningRootOf(doc) {
-    const parts = doc.path.split(sep);
-    const idx = parts.lastIndexOf(CRTR_DIR_NAME);
-    if (idx <= 0)
-        return null;
-    return parts.slice(0, idx).join(sep) || sep;
-}
 function loadProjectDoc(file, memoryDir) {
     try {
         const raw = relative(memoryDir, file)
@@ -168,31 +157,6 @@ function dedupeByPhysicalPath(docs) {
     }
     return out;
 }
-function globMatches(glob, absReadFile, owningRoot) {
-    const targets = [absReadFile, basename(absReadFile)];
-    if (owningRoot !== null)
-        targets.push(relative(owningRoot, absReadFile));
-    return targets.some((target) => {
-        try {
-            return matchesGlob(target, glob);
-        }
-        catch {
-            return false;
-        }
-    });
-}
-/** True when the read file sits beneath the doc's store's owning directory —
- *  the read-event meaning of the reserved `applies-to: "."` target. Callers
- *  additionally guard on `doc.scope === 'project'`: a profile store's path
- *  computes an owning root of `~`, and user/builtin/node docs likewise have no
- *  project-owning dir, so `.` outside a project store must never match. */
-function underOwningRoot(doc, absReadFile) {
-    const root = owningRootOf(doc);
-    if (root === null)
-        return false;
-    const rel = relative(realpathOrSelf(root), absReadFile);
-    return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
-}
 function readFileFrontmatter(absReadFile) {
     if (!/\.(md|mdx|markdown)$/i.test(absReadFile))
         return {};
@@ -203,24 +167,7 @@ function readFileFrontmatter(absReadFile) {
         return {};
     }
 }
-function matchesReadEvent(doc, absReadFile, readFrontmatter) {
-    const pathMatch = doc.appliesTo?.some((glob) => glob.trim() === '.'
-        ? doc.scope === 'project' && underOwningRoot(doc, absReadFile)
-        : globMatches(glob, absReadFile, owningRootOf(doc))) === true;
-    const frontmatterMatch = doc.readWhen !== undefined &&
-        Object.keys(readFrontmatter).length > 0 &&
-        evalCondition(doc.readWhen, readFrontmatter);
-    return pathMatch || frontmatterMatch;
-}
-function envelopeName(doc) {
-    const displayed = displayName(doc.name);
-    if (displayed !== '')
-        return displayed;
-    const root = owningRootOf(doc);
-    return root === null ? doc.name : basename(root);
-}
-function renderDocEnvelope(doc) {
-    const rung = doc.fileReadVisibility;
+function renderDocEnvelope(doc, rung) {
     if (rung === 'none')
         return null;
     let body = '';
@@ -228,47 +175,56 @@ function renderDocEnvelope(doc) {
         body = doc.body.trim();
     else if (rung === 'preview')
         body = previewLine(doc);
-    const attrs = `kind="${attr(doc.kind)}" name="${attr(envelopeName(doc))}" src="${attr(disp(doc.path))}"`;
+    const attrs = `kind="${attr(doc.kind)}" name="${attr(doc.name)}" src="${attr(disp(doc.path))}"`;
     return body === '' ? `<memory ${attrs} />` : `<memory ${attrs}>\n${body}\n</memory>`;
 }
-function renderCandidates(subject, docs, seen) {
+/** Render candidates at their matched rungs, gate-checked and deduped against
+ *  the transcript set (higher rungs pierce lower; a delivery records at its
+ *  rendered rung). A `null` subject means no node identity is available for
+ *  gate evaluation: gated docs are skipped, ungated docs still deliver. */
+export function renderCandidateBlocks(subject, candidates, seen) {
     const rendered = [];
-    for (const doc of docs) {
+    for (const { doc, rung } of candidates) {
         const real = realpathOrSelf(doc.path);
-        if (seen.has(real))
+        if (deliveredAtOrAbove(seen, real, rung))
             continue;
         try {
-            if (!gatePasses(doc, subject))
+            if (subject === null ? doc.gate !== undefined : !gatePasses(doc, subject))
                 continue;
-            const block = renderDocEnvelope(doc);
+            const block = renderDocEnvelope(doc, rung);
             if (block === null)
                 continue;
-            seen.add(real);
+            recordDelivery(seen, real, rung);
             rendered.push(block);
         }
         catch {
             continue;
         }
     }
+    return rendered;
+}
+function renderCandidates(subject, candidates, seen) {
+    const rendered = renderCandidateBlocks(subject, candidates, seen);
     return rendered.length === 0
         ? ''
         : `<auto-loaded-context>\n${rendered.join('\n')}\n</auto-loaded-context>`;
 }
-/** Surface docs matched by a successful read tool call using the caller-supplied
- * daemon snapshot subject. */
-export function renderOnReadDocsForSubject(subject, readFilePath, seen = new Set()) {
+/** Surface docs whose `read` entries match a successfully read file, using
+ * the caller-supplied daemon snapshot subject. */
+export function renderOnReadDocsForSubject(subject, readFilePath, seen = new Map()) {
     const absReadFile = realpathOrSelf(readFilePath);
     const readFrontmatter = readFileFrontmatter(absReadFile);
-    const docs = dedupeByPhysicalPath([...enclosingProjectDocs(absReadFile), ...resolvedDocs()])
+    const candidates = dedupeByPhysicalPath([...enclosingProjectDocs(absReadFile), ...resolvedDocs()])
         .filter((doc) => realpathOrSelf(doc.path) !== absReadFile)
-        .filter((doc) => matchesReadEvent(doc, absReadFile, readFrontmatter));
-    return renderCandidates(subject, docs, seen);
+        .map((doc) => ({ doc, rung: readDeliveryRung(doc, absReadFile, readFrontmatter) }))
+        .filter(({ rung }) => rung !== 'none');
+    return renderCandidates(subject, candidates, seen);
 }
 /** Workspace boot docs using the snapshot's cwd/profile instead of a canvas
  * lookup. `seen` is the transcript-scoped dedup set shared with the on-read
  * hook, so a front door delivered here never re-delivers on a later read
  * beneath its store. */
-export function renderWorkspaceOpenDocsForSubject(subject, cwd, profileId, seen = new Set()) {
+export function renderWorkspaceOpenDocsForSubject(subject, cwd, profileId, seen = new Map()) {
     let docs;
     try {
         docs = listProjectMemoryDocs(cwd, profileId)
@@ -278,13 +234,36 @@ export function renderWorkspaceOpenDocsForSubject(subject, cwd, profileId, seen
     catch {
         return '';
     }
-    docs = dedupeByPhysicalPath(docs)
-        .filter((doc) => doc.appliesTo?.some((glob) => glob.trim() === '.') === true)
+    const candidates = dedupeByPhysicalPath(docs)
+        .map((doc) => ({ doc, rung: workspaceOpenRung(doc) }))
+        .filter(({ rung }) => rung !== 'none')
         .sort((a, b) => {
-        const aRoot = owningRootOf(a) ?? '';
-        const bRoot = owningRootOf(b) ?? '';
+        const aRoot = owningRootOf(a.doc) ?? '';
+        const bRoot = owningRootOf(b.doc) ?? '';
         const depth = aRoot.split(sep).filter(Boolean).length - bRoot.split(sep).filter(Boolean).length;
-        return depth || aRoot.localeCompare(bRoot) || a.path.localeCompare(b.path);
+        return depth || aRoot.localeCompare(bRoot) || a.doc.path.localeCompare(b.doc.path);
     });
-    return renderCandidates(subject, docs, seen);
+    return renderCandidates(subject, candidates, seen);
+}
+/** Inner `<memory>` blocks for the memory-read event: docs whose
+ * `memory-read` entries match the doc a `crtr memory read` just resolved
+ * (known by `targetNames`; `excludeRealpath` keeps the resolved doc from
+ * delivering itself). Returns unwrapped blocks — the read leaf composes one
+ * `<auto-loaded-context>` envelope from these plus the directory listings. */
+export function memoryReadDocBlocks(subject, excludeRealpath, targetNames, seen) {
+    const candidates = dedupeByPhysicalPath(resolvedDocs())
+        .filter((doc) => realpathOrSelf(doc.path) !== excludeRealpath)
+        .map((doc) => ({ doc, rung: memoryReadDeliveryRung(doc, targetNames) }))
+        .filter(({ rung }) => rung !== 'none');
+    return renderCandidateBlocks(subject, candidates, seen);
+}
+/** Surface docs whose `command` entries match an executed bash command
+ * string. The corpus is the resolved cwd/profile set only — a command has no
+ * file to walk enclosing stores from. `seen` is the same transcript-scoped
+ * dedup set as the other channels. */
+export function renderOnCommandDocsForSubject(subject, command, seen = new Map()) {
+    const candidates = dedupeByPhysicalPath(resolvedDocs())
+        .map((doc) => ({ doc, rung: commandDeliveryRung(doc, command) }))
+        .filter(({ rung }) => rung !== 'none');
+    return renderCandidates(subject, candidates, seen);
 }

package/dist/core/substrate/render-node.d.ts

@@ -1,3 +1,4 @@
+import type { InjectedDocs } from './injected-store.js';
 /** The system-prompt `<memory kind="preference">` block for `nodeId`: assemble
  *  the node's subject from the canvas-db, render the pure block, then swap the
  *  literal `$CRTR_CONTEXT_DIR` env-var token for the node's real absolute path
@@ -7,5 +8,7 @@
 export declare function renderPreferencesSection(nodeId: string): string;
 /** The first-message `<memory kind="knowledge">` block for `nodeId`: assemble
  *  the node's subject from the canvas-db and render the consultable catalog.
- *  Returns '' for an unknown id or when nothing is eligible. */
-export declare function renderKnowledgeBlock(nodeId: string): string;
+ *  Returns '' for an unknown id or when nothing is eligible. `seen` (optional,
+ *  write-only) receives each rendered doc at its displayed rung — boot
+ *  delivery seeding for the transcript dedup map. */
+export declare function renderKnowledgeBlock(nodeId: string, seen?: InjectedDocs): string;