@north-light/crouter 0.3.262 → 0.3.269

package/dist/commands/canvas-history/grep.js

@@ -1,14 +1,14 @@
 import { defineLeaf } from '../../core/command.js';
 import { usage } from '../../core/errors.js';
 import { cliClient, rethrowAsCliError } from '../api-client.js';
-import { filterParams, parseFilters } from './shared.js';
+import { applyFilters, filterParams, parseFilters } from './shared.js';
 export const grepLeaf = defineLeaf({
     name: 'grep',
     description: 'exact regex line search across the cwd\'s node history',
     whenToUse: 'you know the exact string or pattern you\'re looking for — an error message, a literal identifier, a code fragment — and want every matching body LINE across every node that ran in this cwd, not a relevance ranking. The pattern is required (an ECMAScript regex, case-insensitive). Narrow with --type/--kind/--status/--since, scope elsewhere with --cwd/--all-cwds/--under/--node. Want ranked/browse search instead? Use `canvas history search` — a distinct leaf, not a flag here. Use `canvas history read <ref>` to read a hit\'s full body, `node inspect artifacts <node-id>` to list one node\'s artifacts, and `node lifecycle revive <id>` to reopen a node you found.',
     help: {
         name: 'canvas history grep',
-        summary: 'required-pattern regex line search over the per-cwd episodic record (reports + context docs + meta)',
+        summary: 'required-pattern regex line search over the per-cwd episodic record (reports + context docs + meta; transcripts and inbox opt-in)',
         params: [
             { kind: 'positional', name: 'pattern', required: true, constraint: 'An ECMAScript regex, matched case-insensitively against each body line. One hit per matching line.' },
             ...filterParams,
@@ -43,26 +43,7 @@ export const grepLeaf = defineLeaf({
         // closures cannot cross the wire.
         const f = parseFilters(input);
         const q = { pattern, limit };
-        if (f.cwd !== undefined)
-            q.cwd = f.cwd;
-        if (f.allCwds)
-            q.all_cwds = true;
-        if (f.under !== undefined)
-            q.under = f.under;
-        if (f.nodes !== undefined)
-            q.nodes = f.nodes;
-        if (f.types !== undefined)
-            q.types = f.types;
-        if (f.reportKind !== undefined)
-            q.report_kind = f.reportKind;
-        if (f.kinds !== undefined)
-            q.kinds = f.kinds;
-        if (f.statuses !== undefined)
-            q.statuses = f.statuses;
-        if (f.sinceMs !== undefined)
-            q.since_ms = f.sinceMs;
-        if (f.untilMs !== undefined)
-            q.until_ms = f.untilMs;
+        applyFilters(q, f);
         if (cursor !== undefined)
             q.cursor = cursor;
         try {

package/dist/commands/canvas-history/read.js

@@ -9,13 +9,14 @@ export const readLeaf = defineLeaf({
         name: 'canvas history read',
         summary: 'resolve a <node-id>:<relpath> ref to its full artifact body',
         params: [
-            { kind: 'positional', name: 'ref', required: true, constraint: 'The <node-id>:<relpath> handle from `canvas history search` (e.g. mq186ky0-c754531c:reports/20260607T075536-final.md, or <node-id>:meta for a node\'s identity).' },
+            { kind: 'positional', name: 'ref', required: true, constraint: 'The <node-id>:<relpath> handle from `canvas history search` (e.g. mq186ky0-c754531c:reports/20260607T075536-final.md, or <node-id>:meta for a node\'s identity). <node-id>:session addresses a node\'s whole conversation; <node-id>:session/<index> one message in it.' },
             { kind: 'flag', name: 'frontmatter', type: 'bool', required: false, constraint: 'Include the artifact\'s YAML frontmatter. Stripped by default.' },
+            { kind: 'flag', name: 'format', type: 'enum', choices: ['rendered', 'raw'], required: false, default: 'rendered', constraint: 'raw returns the verbatim bytes behind the ref — the session .jsonl for a bare session ref, the single persisted jsonl entry for one message, the unparsed file for a report or doc. Use it when the rendered view may be hiding what you are chasing.' },
         ],
         output: [
             { name: 'ref', type: 'string', required: true, constraint: 'Echo of the resolved ref.' },
             { name: 'node', type: 'string', required: true, constraint: 'Node name + id.' },
-            { name: 'source', type: 'string', required: true, constraint: 'report | doc | roadmap | meta (+ report-kind for reports).' },
+            { name: 'source', type: 'string', required: true, constraint: 'report | doc | roadmap | meta | inbox | transcript (+ report-kind for reports).' },
             { name: 'ts', type: 'string', required: true, constraint: 'Artifact timestamp.' },
             { name: 'content', type: 'string', required: true, constraint: 'Full body. Frontmatter stripped unless --frontmatter.' },
         ],
@@ -25,6 +26,7 @@ export const readLeaf = defineLeaf({
     run: async (input) => {
         const ref = input['ref'].trim();
         const includeFrontmatter = input['frontmatter'] === true;
+        const format = input['format'] ?? 'rendered';
         // Fast local shape check; ref resolution (+ its usage/not-found errors) runs
         // server-side in crtrd (`GET /v1/canvas/history/read`).
         if (!ref.includes(':')) {
@@ -34,7 +36,7 @@ export const readLeaf = defineLeaf({
             });
         }
         try {
-            const res = await cliClient().historyRead({ ref, frontmatter: includeFrontmatter });
+            const res = await cliClient().historyRead({ ref, frontmatter: includeFrontmatter, format });
             return { ref: res.ref, node: res.node, source: res.source, ts: res.ts, content: res.content };
         }
         catch (err) {

package/dist/commands/canvas-history/search.js

@@ -1,6 +1,6 @@
 import { defineLeaf } from '../../core/command.js';
 import { cliClient, rethrowAsCliError } from '../api-client.js';
-import { filterParams, parseFilters } from './shared.js';
+import { applyFilters, filterParams, parseFilters } from './shared.js';
 const SORTS = ['relevance', 'recency', 'oldest'];
 export const searchLeaf = defineLeaf({
     name: 'search',
@@ -8,7 +8,7 @@ export const searchLeaf = defineLeaf({
     whenToUse: 'you want to find past work by what it SAYS — a design, a final report, a roadmap, a finding — across every node that ran in this cwd, ranked by relevance. Omit the query to browse the record by recency ("what happened here lately"). Narrow with --type/--kind/--status/--since, scope elsewhere with --cwd/--all-cwds/--under/--node. Need an exact regex over bodies instead of ranking? Use `canvas history grep` — a distinct leaf, not a flag here. Use `canvas history read <ref>` to read a hit in full, `node inspect artifacts <node-id>` to list one node\'s artifacts, and `node lifecycle revive <id>` to reopen a node you found.',
     help: {
         name: 'canvas history search',
-        summary: 'ranked/filtered/sorted content search over the per-cwd episodic record (reports + context docs + meta)',
+        summary: 'ranked/filtered/sorted content search over the per-cwd episodic record (reports + context docs + meta; transcripts and inbox opt-in)',
         params: [
             { kind: 'positional', name: 'query', required: false, constraint: 'Whitespace-separated terms, matched case-insensitively and weighted across node name/description, report titles, and doc headings (and full bodies with --body); artifacts matching more/stronger fields rank higher. Omit to browse by recency (no relevance ranking; --sort still applies).' },
             ...filterParams,
@@ -45,26 +45,7 @@ export const searchLeaf = defineLeaf({
         const q = { snippet_lines: snippetLines, limit, sort: sortMode };
         if (query !== '')
             q.query = query;
-        if (f.cwd !== undefined)
-            q.cwd = f.cwd;
-        if (f.allCwds)
-            q.all_cwds = true;
-        if (f.under !== undefined)
-            q.under = f.under;
-        if (f.nodes !== undefined)
-            q.nodes = f.nodes;
-        if (f.types !== undefined)
-            q.types = f.types;
-        if (f.reportKind !== undefined)
-            q.report_kind = f.reportKind;
-        if (f.kinds !== undefined)
-            q.kinds = f.kinds;
-        if (f.statuses !== undefined)
-            q.statuses = f.statuses;
-        if (f.sinceMs !== undefined)
-            q.since_ms = f.sinceMs;
-        if (f.untilMs !== undefined)
-            q.until_ms = f.untilMs;
+        applyFilters(q, f);
         if (weighBody)
             q.weigh_body = true;
         if (full)

package/dist/commands/canvas-history/shared.d.ts

@@ -1,5 +1,7 @@
 import type { InputParam } from '../../core/help.js';
 export declare const TYPES: string[];
+export declare const ORIGINS: string[];
+export declare const ROLES: string[];
 export declare const NODE_KINDS: string[];
 export declare const STATUSES: string[];
 /** ISO 8601 (`2026-06-01`) \u2192 epoch ms (absolute); relative (`7d`, `2w`, `1mo`)
@@ -21,7 +23,13 @@ export interface ParsedFilters {
     statuses: string[] | undefined;
     sinceMs: number | undefined;
     untilMs: number | undefined;
+    origins: string[] | undefined;
+    roles: string[] | undefined;
+    from: string | undefined;
 }
 /** Parse + validate the shared scope/filter flags from a leaf's raw input.
  *  Pure and client-side; the corpus scan itself runs server-side in crtrd. */
 export declare function parseFilters(input: Record<string, unknown>): ParsedFilters;
+/** Copy every parsed filter onto a wire query. search, grep, and stats share
+ *  the whole filter vocabulary, so the mapping lives once. */
+export declare function applyFilters(q: Record<string, unknown>, f: ParsedFilters): void;

package/dist/commands/canvas-history/shared.js

@@ -5,7 +5,12 @@
 // seam. This is internal reuse only: neither leaf's public flag set or output
 // shape is shared, and nothing here is re-exported as a command alias.
 import { usage } from '../../core/errors.js';
-export const TYPES = ['report', 'doc', 'roadmap', 'meta', 'inbox'];
+export const TYPES = ['report', 'doc', 'roadmap', 'meta', 'inbox', 'transcript'];
+export const ORIGINS = [
+    'human', 'inbox', 'wake', 'revive', 'restart-continuation',
+    'stop-guard', 'park', 'recovery', 'context-nudge', 'kickoff', 'unknown',
+];
+export const ROLES = ['user', 'assistant', 'toolResult'];
 export const NODE_KINDS = ['advisor', 'developer', 'spec', 'design', 'review', 'explore', 'plan', 'general'];
 export const STATUSES = ['active', 'idle', 'done', 'dead', 'canceled'];
 const REL_UNITS = {
@@ -47,6 +52,9 @@ export const filterParams = [
     { kind: 'flag', name: 'status', type: 'string', required: false, constraint: `Node lifecycle status; comma-separated for several. One of: ${STATUSES.join(', ')} (e.g. done = completed work only).` },
     { kind: 'flag', name: 'since', type: 'string', required: false, constraint: 'Lower bound on artifact timestamp. ISO 8601 (2026-06-01) or relative (7d, 2w, 1mo).' },
     { kind: 'flag', name: 'until', type: 'string', required: false, constraint: 'Upper bound on artifact timestamp. ISO 8601 or relative.' },
+    { kind: 'flag', name: 'origin', type: 'string', required: false, constraint: `What drove a message to arrive; comma-separated for several. One of: ${ORIGINS.join(', ')}. Applies to transcript + inbox artifacts, which are the only ones that arrive — passing it therefore excludes every generated turn on its own. \`unknown\` is a message carrying no stamp, and is its own bucket rather than a fallback.` },
+    { kind: 'flag', name: 'role', type: 'string', required: false, constraint: `Transcript message role; comma-separated for several. One of: ${ROLES.join(', ')}.` },
+    { kind: 'flag', name: 'from', type: 'string', required: false, constraint: 'Case-insensitive substring against sender attribution — the node that sent a delivery. Applies to transcript + inbox artifacts.' },
 ];
 /** Parse + validate the shared scope/filter flags from a leaf's raw input.
  *  Pure and client-side; the corpus scan itself runs server-side in crtrd. */
@@ -61,6 +69,28 @@ export function parseFilters(input) {
         if (bad !== undefined)
             throw usage(`--type must be one of: ${TYPES.join(', ')}; received: ${bad}`);
     }
+    const origins = splitCsv(input['origin']);
+    if (origins !== undefined) {
+        const bad = origins.find((o) => !ORIGINS.includes(o));
+        if (bad !== undefined)
+            throw usage(`--origin must be one of: ${ORIGINS.join(', ')}; received: ${bad}`);
+    }
+    const roles = splitCsv(input['role']);
+    if (roles !== undefined) {
+        const bad = roles.find((r) => !ROLES.includes(r));
+        if (bad !== undefined)
+            throw usage(`--role must be one of: ${ROLES.join(', ')}; received: ${bad}`);
+    }
+    // Session files are large and there is no persistent index, so the whole
+    // conversation corpus is reachable only through a narrowed scan. The guard
+    // lives in the failure rather than in a permanently visible constraint:
+    // agents who never search transcripts never pay to understand it.
+    if (types !== undefined && types.includes('transcript')) {
+        const narrowed = input['node'] !== undefined || input['under'] !== undefined || input['since'] !== undefined;
+        if (!narrowed) {
+            throw usage('--type transcript needs a narrowing flag: pass --node, --under, or --since.', { next: 'Transcripts are the full conversation corpus — scanning every node in a cwd reads every session file. Narrow first.' });
+        }
+    }
     return {
         cwd,
         allCwds,
@@ -72,5 +102,38 @@ export function parseFilters(input) {
         statuses: splitCsv(input['status']),
         sinceMs: input['since'] !== undefined ? parseWhen('since', input['since']) : undefined,
         untilMs: input['until'] !== undefined ? parseWhen('until', input['until']) : undefined,
+        origins,
+        roles,
+        from: input['from'],
     };
 }
+/** Copy every parsed filter onto a wire query. search, grep, and stats share
+ *  the whole filter vocabulary, so the mapping lives once. */
+export function applyFilters(q, f) {
+    if (f.cwd !== undefined)
+        q['cwd'] = f.cwd;
+    if (f.allCwds)
+        q['all_cwds'] = true;
+    if (f.under !== undefined)
+        q['under'] = f.under;
+    if (f.nodes !== undefined)
+        q['nodes'] = f.nodes;
+    if (f.types !== undefined)
+        q['types'] = f.types;
+    if (f.reportKind !== undefined)
+        q['report_kind'] = f.reportKind;
+    if (f.kinds !== undefined)
+        q['kinds'] = f.kinds;
+    if (f.statuses !== undefined)
+        q['statuses'] = f.statuses;
+    if (f.sinceMs !== undefined)
+        q['since_ms'] = f.sinceMs;
+    if (f.untilMs !== undefined)
+        q['until_ms'] = f.untilMs;
+    if (f.origins !== undefined)
+        q['origins'] = f.origins;
+    if (f.roles !== undefined)
+        q['roles'] = f.roles;
+    if (f.from !== undefined)
+        q['from'] = f.from;
+}

package/dist/commands/canvas-history/stats.d.ts

@@ -0,0 +1 @@
+export declare const statsLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/canvas-history/stats.js

@@ -0,0 +1,68 @@
+// `canvas history stats` — the grouped-count projection over the same corpus
+// search and grep scan. A distinct leaf rather than a flag on search because
+// the output shape differs: counts by one dimension, not a hit list. Grouping
+// by origin is what turns the per-message stamps into a census — "what actually
+// drove work here" — without a second command family.
+import { defineLeaf } from '../../core/command.js';
+import { usage } from '../../core/errors.js';
+import { cliClient, rethrowAsCliError } from '../api-client.js';
+import { applyFilters, filterParams, parseFilters } from './shared.js';
+const GROUP_KEYS = ['origin', 'node', 'kind', 'day', 'type', 'role'];
+export const statsLeaf = defineLeaf({
+    name: 'stats',
+    description: 'grouped counts over the cwd\'s node history — the projection view',
+    whenToUse: 'you want the SHAPE of the record rather than individual hits — how much of it came from where, who produced it, or when it happened. Group by origin to census what drove agents to run (cron wakes, inbox deliveries, recovery re-drives, people), by node/kind to see who produced the work, by day for volume over time, by type for corpus composition. Takes every scope and filter `canvas history search` takes, so any query you can search you can also count. Want the matching artifacts themselves? Use `canvas history search` or `canvas history grep`.',
+    help: {
+        name: 'canvas history stats',
+        summary: 'counts by one dimension over the per-cwd episodic record — origin census, per-node volume, activity by day',
+        params: [
+            { kind: 'flag', name: 'group-by', type: 'enum', choices: GROUP_KEYS, required: false, default: 'type', constraint: 'The dimension to count by. origin = what drove an inbound message (transcript + inbox only); role = transcript message role; node / kind = who produced it; day = artifact date; type = corpus composition.' },
+            ...filterParams,
+        ],
+        output: [
+            { name: 'group_by', type: 'string', required: true, constraint: 'The dimension counted.' },
+            { name: 'groups', type: 'object[]', required: true, constraint: '{key, count}, descending by count then key.' },
+            { name: 'total', type: 'int', required: true, constraint: 'Artifacts that carried the grouped dimension. Lower than `scanned` when grouping by one not every artifact has (origin, role).' },
+            { name: 'scanned', type: 'int', required: true, constraint: 'Artifacts matched by the filters before grouping.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const by = input['groupBy'] ?? 'type';
+        if (!GROUP_KEYS.includes(by)) {
+            throw usage(`--group-by must be one of: ${GROUP_KEYS.join(', ')}; received: ${by}`);
+        }
+        // Filter validation stays client-side (pure); the corpus scan + grouping
+        // run server-side in crtrd, where canvas.db and the session files live.
+        const f = parseFilters(input);
+        const q = { group_by: by };
+        applyFilters(q, f);
+        try {
+            const res = await cliClient().historyStats(q);
+            return { group_by: res.group_by, groups: res.groups, total: res.total, scanned: res.scanned };
+        }
+        catch (err) {
+            rethrowAsCliError(err);
+        }
+    },
+    render: (r) => {
+        const groups = r['groups'];
+        const by = String(r['group_by']);
+        const total = r['total'];
+        const scanned = r['scanned'];
+        if (groups.length === 0) {
+            return `0 artifacts carried \`${by}\` (${scanned} scanned).`;
+        }
+        const width = Math.max(...groups.map((g) => g.key.length));
+        const max = groups[0].count;
+        const rows = groups
+            .map((g) => {
+            const bar = '█'.repeat(Math.max(1, Math.round((g.count / max) * 24)));
+            return `  ${g.key.padEnd(width)}  ${String(g.count).padStart(6)}  ${bar}`;
+        })
+            .join('\n');
+        const tail = total === scanned ? `${total} artifacts` : `${total} of ${scanned} scanned carried \`${by}\``;
+        return `by ${by}:\n\n${rows}\n\n- ${tail}`;
+    },
+});

package/dist/commands/canvas-history.js

@@ -10,6 +10,7 @@ import { defineBranch } from '../core/command.js';
 import { searchLeaf } from './canvas-history/search.js';
 import { grepLeaf } from './canvas-history/grep.js';
 import { readLeaf } from './canvas-history/read.js';
+import { statsLeaf } from './canvas-history/stats.js';
 /** A tiny per-cwd `<corpus>` marker for branch -h — just enough context to
  *  anchor the help text without scanning nodes or files. Uses only the injected
  *  node cwd env (or the process cwd outside a node), so help stays cheap. */
@@ -19,13 +20,13 @@ function corpusBlock() {
 }
 export const historyBranch = defineBranch({
     name: 'history',
-    description: 'search and recall the cwd-wide content corpus — every node\'s reports and context docs',
+    description: 'search and recall the cwd-wide content corpus — every node\'s reports, context docs, and conversations',
     whenToUse: 'you want to find or re-read what was DONE in a cwd — a past design, a final report, a roadmap, a finding — across every node that ran there, WITHOUT already knowing which node. Use it when picking up prior work ("that caching work from last week"), recovering an artifact, or surveying a project\'s history. Already have the node id and just want everything IT left behind? Use `node inspect artifacts <id>` instead — this branch is the cwd-wide search corpus, not a per-node listing. Distinct from `crtr memory` (curated semantic knowledge, not episodes) and from `canvas dashboard`/`node inspect` (graph topology, not content).',
     help: {
         name: 'canvas history',
         summary: 'search and recall the cwd-wide content corpus — every node\'s reports and context docs in this cwd',
-        model: 'The accumulated record of every node that ran in a cwd and the artifacts it left — its reports (final/update outcome summaries) and context docs (specs, designs, roadmaps, findings). `search` finds by content (ranked, filtered, sorted; omit the query to browse by recency); `grep` finds by an exact ECMAScript regex over body lines (pattern required, one hit per matching line — use this over `search` when you know the literal string/pattern, not just the topic); `read` pulls one hit\'s full body by its <node-id>:<relpath> ref. This is the episodic record of what was DONE — distinct from `crtr memory`, which is curated semantic knowledge. Already have a node id and want everything IT left behind (not a cwd-wide search)? Use `node inspect artifacts <node-id>` instead — that single-node listing moved out of this branch. A node\'s raw inbox history (`--type inbox`) is a separate, opt-in diagnostic corpus — the full cursor-independent inbox.jsonl for one node, including un-clipped direct-message bodies; reach for it only when the curated reports/docs above don\'t already answer the question. To reopen a node you found, use `node lifecycle revive`; for its place in the graph, `node inspect show`.',
+        model: 'The accumulated record of every node that ran in a cwd and the artifacts it left — its reports (final/update outcome summaries), context docs (specs, designs, roadmaps, findings), and the conversations themselves. `search` finds by content (ranked, filtered, sorted; omit the query to browse by recency); `grep` finds by an exact ECMAScript regex over body lines (pattern required, one hit per matching line — use this over `search` when you know the literal string/pattern, not just the topic); `read` pulls one hit\'s full body by its <node-id>:<relpath> ref, `--format raw` for the verbatim bytes; `stats` counts the same filtered corpus by one dimension instead of listing hits. Corpus is a DIMENSION here, not a location: `--type` selects which record you search, and every leaf takes the same scope and filters. This is the episodic record of what was DONE — distinct from `crtr memory`, which is curated semantic knowledge. Already have a node id and want everything IT left behind (not a cwd-wide search)? Use `node inspect artifacts <node-id>` instead. Two corpora are opt-in diagnostics rather than curated work: `--type inbox` is one node\'s full cursor-independent inbox.jsonl including un-clipped message bodies, and `--type transcript` is the conversation itself, message by message, each inbound turn carrying the origin that drove it (`--origin`, `--role`, `--from`, and `stats --group-by origin` for the census). Transcripts require a narrowing flag because there is no index. To reopen a node you found, use `node lifecycle revive`; for its place in the graph, `node inspect show`.',
         dynamicState: corpusBlock,
     },
-    children: [searchLeaf, grepLeaf, readLeaf],
+    children: [searchLeaf, grepLeaf, readLeaf, statsLeaf],
 });

package/dist/commands/memory/read.js

@@ -3,13 +3,12 @@ import { CrtrClient } from '../../api/index.js';
 import { defineLeaf } from '../../core/command.js';
 import { CrtrError } from '../../core/errors.js';
 import { memoryExtensionEffectiveCatalog, projectEffectiveMemoryExtensions } from '../../core/memory/extensions.js';
-import { realpathOrSelf } from '../../core/fs-utils.js';
 import { docLinkNames } from '../../core/memory/doc-link-grammar.js';
 import { createMemoryDocSnapshot, listAllMemoryDocs, loadMemoryStoreView, readMemoryDocContent, resolveMemoryCandidates, resolveMemoryDocs, } from '../../core/memory-resolver.js';
 import { expandShellBlocks, hasShellBlocks, makeNodeShellRunner } from '../../core/runtime/shell-expansion.js';
-import { emptyContextExposureState, exposedAtOrAbove, exposureTarget, loadContextExposureState, registerDocumentExposure, registerExposure, saveContextExposureState, } from '../../core/substrate/injected-store.js';
-import { dirDedupKey, docListingDirs, docsByName, isDirName, renderDirListing } from '../../core/substrate/listings.js';
-import { memoryReadDocBlocks } from '../../core/substrate/on-read.js';
+import { emptyContextExposureState, exposureTarget, loadContextExposureState, registerDocumentExposure, registerExposure, saveContextExposureState, } from '../../core/substrate/injected-store.js';
+import { dirDedupKey, docsByName, isDirName, renderDirListing } from '../../core/substrate/listings.js';
+import { contentReadAttachments } from '../../core/substrate/on-read.js';
 import { renderResult } from '../../core/render.js';
 import { effectiveDocKind } from '../../core/substrate/schema.js';
 import { canonicalSegments } from '../../core/memory/identity.js';
@@ -49,13 +48,6 @@ export function candidateRow(doc, winner) {
         path: doc.path,
     };
 }
-function attr(s) {
-    return s
-        .replace(/&/g, '&')
-        .replace(/"/g, '"')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;');
-}
 export const readLeaf = defineLeaf({
     name: 'read',
     description: 'load a memory document body by name',
@@ -190,36 +182,21 @@ export const readLeaf = defineLeaf({
             : emptyContextExposureState();
         const target = exposureTarget(contextExposure, 'transcript');
         const subject = await fetchSubject(nodeId);
-        const excludeReal = realpathOrSelf(doc.path);
-        // The explicit read IS a content delivery: record it first so unsolicited
-        // channels (including this doc's own line in its directory listing) stay
-        // quiet about a doc whose full body is already in the transcript.
+        // An explicit read is itself content delivery. Register it before shared
+        // attachments, so the directory tree and companion routes dedupe against
+        // the body just returned exactly as every automatic content delivery does.
         registerDocumentExposure(target, doc.path, doc.body, 'content');
-        const blocks = [];
-        // A doc that fronts a directory carries its members with its body: that
-        // listing is part of the deliberate read (every line renders) and returns
-        // as `listing`, while the ancestors above it stay unsolicited neighborhood
-        // context. The node's own document is never among its children, so nothing
-        // repeats.
-        const dirs = docListingDirs(listingByName, doc.name);
-        const ownDir = dirs[0] === doc.name;
-        let listing;
-        if (ownDir) {
-            listing = renderDirListing(listingByName, doc.name, target, false);
-            registerExposure(target, dirDedupKey(doc.name), 'preview');
-        }
-        for (const dir of ownDir ? dirs.slice(1) : dirs) {
-            if (exposedAtOrAbove(contextExposure, dirDedupKey(dir), 'preview'))
-                continue;
-            const lines = renderDirListing(listingByName, dir, target, true);
-            registerExposure(target, dirDedupKey(dir), 'preview');
-            if (lines.length > 0)
-                blocks.push(`<memory-listing dir="${attr(dir)}">\n${lines.join('\n')}\n</memory-listing>`);
-        }
-        blocks.push(...memoryReadDocBlocks(subject, excludeReal, doc.name, target));
+        const attachments = contentReadAttachments(doc, {
+            subject,
+            target,
+            byName: listingByName,
+            listings: 'blocks',
+            explicit: true,
+        });
         if (nodeId !== undefined)
             saveContextExposureState(nodeId, contextExposure);
-        const finalContent = blocks.length === 0 ? content : `<auto-loaded-context>\n${blocks.join('\n')}\n</auto-loaded-context>\n\n${content}`;
+        const finalContent = attachments.blocks.length === 0 ? content : `<auto-loaded-context>\n${attachments.blocks.join('\n')}\n</auto-loaded-context>\n\n${content}`;
+        const listing = attachments.listing;
         const hasListing = listing !== undefined && listing.length > 0;
         const followUp = hasListing
             ? links.length > 0

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

@@ -195,7 +195,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); `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_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\u2019s full body is delivered, including an explicit 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

@@ -795,7 +795,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); `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_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’s full body is delivered, including an explicit 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/commands/node/create.js

@@ -94,8 +94,8 @@ function nodeNewParams() {
                 whenToUse: 'Use only when the user, task, or governing agent guidance already requires a specific provider, model, capability tier, or family. Omit it for routine delegation: the selected persona kind and profile own normal model selection, and review personas may enforce a quality floor.',
                 value: `Accepted forms: ${MODEL_SPEC_FORMS}. Concrete provider/id requests must be registered. Portable provider/tier, bare-tier, and family-alias requests resolve through the configured model ladders.`,
                 effects: [
-                    'The resolved override is stored on the node and in its launch recipe, so future revives preserve it.',
-                    'A concrete provider/id pins that provider. Portable tiers and aliases preserve logical intent for runtime routing; a persona quality floor may raise a weaker request.',
+                    'The resolved concrete override is stored on the node and in its launch recipe, so every launch and revive uses that exact provider/model.',
+                    'Portable tiers and aliases resolve through the configured ladders; a persona quality floor may raise a weaker request before its resolved model is stored.',
                 ],
             },
         },

package/dist/commands/sys/config.js

@@ -39,6 +39,11 @@ function assertUserScopeBrokerThresholds(key, scope) {
         throw usage('brokerThresholds are available only in user scope');
     }
 }
+function assertUserScopeLifecycle(key, scope) {
+    if (key.split('.', 1)[0] === 'lifecycle' && scope !== 'user') {
+        throw usage('lifecycle settings are available only in user scope');
+    }
+}
 function assertWorkingGerundsScope(key, scope) {
     if (key === 'working_gerunds' && scope !== 'user') {
         throw usage('working_gerunds is available only in user scope');
@@ -132,6 +137,16 @@ function setNestedValue(cfg, key, rawValue, value) {
         cfg.brokerThresholds[parts[1]] = threshold;
         return;
     }
+    if (topKey === 'lifecycle') {
+        if (parts.length !== 2 || parts[1] !== 'unattendedParkMs') {
+            throw usage(`lifecycle key must be unattendedParkMs`);
+        }
+        if (typeof value !== 'number' || !Number.isFinite(value) || value < 1) {
+            throw usage(`lifecycle.unattendedParkMs must be an integer >= 1`);
+        }
+        cfg.lifecycle.unattendedParkMs = Math.floor(value);
+        return;
+    }
     throw usage(`unsupported key path for set: ${key}`);
 }
 // Leaf definitions
@@ -143,7 +158,7 @@ const configGet = defineLeaf({
         name: 'sys config get',
         summary: 'read a config value by dotted key',
         params: [
-            { kind: 'positional', name: 'key', type: 'string', required: true, constraint: `Dotted key path. Top-level keys: ${CONFIG_TOP_LEVEL_HELP}. brokerThresholds is user-only; keybindings is readable only as the whole user-scope object and editable only through sys settings.` },
+            { kind: 'positional', name: 'key', type: 'string', required: true, constraint: `Dotted key path. Top-level keys: ${CONFIG_TOP_LEVEL_HELP}. brokerThresholds and lifecycle are user-only; keybindings is readable only as the whole user-scope object and editable only through sys settings.` },
             { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Scope to read from. Default: user.' },
         ],
         output: [
@@ -158,6 +173,7 @@ const configGet = defineLeaf({
         const key = input['key'];
         const scope = resolveScope(input['scope']);
         assertUserScopeBrokerThresholds(key, scope);
+        assertUserScopeLifecycle(key, scope);
         if (key.startsWith('keybindings.') || (key === 'keybindings' && scope !== 'user')) {
             throw notFound('keybindings are available only as the whole user-scope object');
         }
@@ -177,7 +193,7 @@ const configSet = defineLeaf({
         name: 'sys config set',
         summary: 'write a config value by dotted key',
         params: [
-            { kind: 'positional', name: 'key', type: 'string', required: true, constraint: `Dotted key path. User-scope scalar settings: ${SCALAR_SETTING_HELP}. Also supported: working_gerunds and whip_messages (non-empty JSON string arrays), brokerThresholds.warning and brokerThresholds.automaticReviveCap (user scope; integer >= 1), modelLadders.defaultProvider, and modelLadders.<anthropic|openai>.<ultra|strong|medium|light>. Keybindings are edited only through sys settings. humanActions is an object map edited directly in ~/.crouter/config.json or <repo>/.crouter/config.json.` },
+            { kind: 'positional', name: 'key', type: 'string', required: true, constraint: `Dotted key path. User-scope scalar settings: ${SCALAR_SETTING_HELP}. Also supported: working_gerunds and whip_messages (non-empty JSON string arrays), brokerThresholds.warning and brokerThresholds.automaticReviveCap (user scope; integer >= 1), lifecycle.unattendedParkMs (user scope; integer ms >= 1), modelLadders.defaultProvider, and modelLadders.<anthropic|openai>.<ultra|strong|medium|light>. Keybindings are edited only through sys settings. humanActions is an object map edited directly in ~/.crouter/config.json or <repo>/.crouter/config.json.` },
             { kind: 'flag', name: 'value', type: 'string', required: true, constraint: 'value VALUE — string, required. working_gerunds and whip_messages accept JSON arrays; other values are stored as-is if quoted and coerced to number or boolean when unambiguous.' },
             { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Scope to write to. Default: user. Project scope is supported only for modelLadders.' },
         ],
@@ -193,6 +209,7 @@ const configSet = defineLeaf({
         const rawValue = input['value'];
         const scope = resolveScope(input['scope']);
         assertUserScopeBrokerThresholds(key, scope);
+        assertUserScopeLifecycle(key, scope);
         assertWorkingGerundsScope(key, scope);
         assertWhipMessagesScope(key, scope);
         assertUserSettingScope(key, scope);

package/dist/commands/sys/context/admin/docs-panel.d.ts

@@ -1,5 +1,5 @@
 import { type SurfaceEvent } from '../../../../core/substrate/schema.js';
-import type { DeliveryRecord } from '../../../../core/substrate/plan.js';
+import type { EffectiveDeliveryRecord } from '../resolve.js';
 import { PlanSet } from './model.js';
 import { type Filters } from './list-view.js';
 /** One physical document across every event. `records` is sparse: an event
@@ -11,8 +11,8 @@ export interface DocRow {
     /** The record for the focused event, or the first one any event carries —
      *  every panel needs a document to describe even when the focused event's
      *  corpus excludes it. */
-    anchor: DeliveryRecord;
-    records: Map<SurfaceEvent, DeliveryRecord>;
+    anchor: EffectiveDeliveryRecord;
+    records: Map<SurfaceEvent, EffectiveDeliveryRecord>;
     /** Present only in an event other than the focused one. */
     offEvent: boolean;
 }

package/dist/commands/sys/context/admin/model.d.ts

@@ -1,4 +1,5 @@
 import { type DeliveryPlan, type DeliveryRecord } from '../../../../core/substrate/plan.js';
+import { type EffectiveDeliveryRecord } from '../resolve.js';
 import { type Rung, type SurfaceEntry, type SurfaceEvent } from '../../../../core/substrate/schema.js';
 import { type NodeConfigSubject } from '../../../../core/substrate/subject-fields.js';
 import { type MemoryTarget } from '../../../../core/memory-resolver.js';
@@ -45,11 +46,15 @@ export declare class PlanSet {
     invalidate(): void;
     dispose(): void;
     /** The plan for one event, computing it now. */
-    plan(event: SurfaceEvent): DeliveryPlan;
+    plan(event: SurfaceEvent): DeliveryPlan & {
+        docs: EffectiveDeliveryRecord[];
+    };
     /** The plan for one event only if it is already computed — what the rail's
      *  EVENTS counts read, so an unwarmed event draws `…` instead of stalling the
      *  frame on five extra corpus loads. */
-    peek(event: SurfaceEvent): DeliveryPlan | undefined;
+    peek(event: SurfaceEvent): (DeliveryPlan & {
+        docs: EffectiveDeliveryRecord[];
+    }) | undefined;
     /** Compute one pending event per macrotask, calling back after each so the
      *  rail's counts fill in row by row. */
     warm(onProgress: () => void): void;