@north-light/crouter 0.3.261 → 0.3.263

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

package/dist/commands/sys/context/admin/model.js

@@ -4,6 +4,7 @@
 import { resolve as resolvePath } from 'node:path';
 import { realpathOrSelf } from '../../../../core/fs-utils.js';
 import { planDelivery, } from '../../../../core/substrate/plan.js';
+import { assembleEventAccounting, effectivePlan, } from '../resolve.js';
 import { RUNGS, SURFACE_EVENTS, previewLine, rungRank, } from '../../../../core/substrate/schema.js';
 import { scopeForCwd, profileNameFor } from '../../../../core/substrate/subject-fields.js';
 import { resolveMemoryDocForTarget } from '../../../../core/memory-resolver.js';
@@ -71,7 +72,12 @@ export class PlanSet {
         const held = this.plans.get(event);
         if (held !== undefined)
             return held;
-        const computed = planDelivery(subjectOf(this.snapshot), targetOf(this.snapshot), event, this.payload(event));
+        const subject = subjectOf(this.snapshot);
+        const target = targetOf(this.snapshot);
+        const payload = this.payload(event);
+        const direct = planDelivery(subject, target, event, payload);
+        const rendered = assembleEventAccounting({ subject, target, nodeMissing: false }, event, payload);
+        const computed = effectivePlan(direct, rendered.accounting.deliveries, payload);
         this.plans.set(event, computed);
         return computed;
     }

package/dist/commands/sys/context/admin/read-view.d.ts

@@ -1,5 +1,5 @@
 import { type Rung, type SurfaceEvent } from '../../../../core/substrate/schema.js';
-import type { DeliveryRecord } from '../../../../core/substrate/plan.js';
+import type { EffectiveDeliveryRecord } from '../resolve.js';
 import type { NodeConfigSubject } from '../../../../core/substrate/subject-fields.js';
 /** The profile project entry whose `memory` rung ceilings this document's
  *  store, or null when no project governs it. */
@@ -11,7 +11,7 @@ export interface CapOwner {
  *  the sibling events' records, and the two facts the shell resolves. */
 export interface DossierContext {
     event: SurfaceEvent;
-    records: Map<SurfaceEvent, DeliveryRecord>;
+    records: Map<SurfaceEvent, EffectiveDeliveryRecord>;
     capOwner: CapOwner | null;
     readOnly: boolean;
     /** The configuration every record here was planned against — what a failed
@@ -20,12 +20,12 @@ export interface DossierContext {
 }
 /** The resting card, and — when `bodyOpen` — the document's own text beneath
  *  it in place of the affordance line that names it. */
-export declare function renderDossierRead(record: DeliveryRecord, context: DossierContext, width: number, bodyOpen: boolean): string[];
+export declare function renderDossierRead(record: EffectiveDeliveryRecord, context: DossierContext, width: number, bodyOpen: boolean): string[];
 /** Identity and routing — what the edit face keeps overhead of its field list,
  *  because they are the context a field is being edited against. */
-export declare function renderDossierHeader(record: DeliveryRecord, context: DossierContext, width: number): string[];
+export declare function renderDossierHeader(record: EffectiveDeliveryRecord, context: DossierContext, width: number): string[];
 /** Does it load here, what does it cost, and — only when there is one — what
  *  interfered. The three questions the old verdict, cost table and event grid
  *  each answered a piece of. */
-export declare function renderDossierDelivery(record: DeliveryRecord, context: DossierContext, width: number): string[];
+export declare function renderDossierDelivery(record: EffectiveDeliveryRecord, context: DossierContext, width: number): string[];
 export declare function bodyLineCount(body: string): number;

package/dist/commands/sys/context/admin/read-view.js

@@ -25,11 +25,13 @@ const INDENT = ' ';
 export function renderDossierRead(record, context, width, bodyOpen) {
     const inner = Math.max(1, width - INDENT.length);
     const out = renderDossierHeader(record, context, width);
-    if (record.doc.shortForm.trim() !== '') {
-        out.push('');
-        out.push(...indent(wrapped(record.doc.shortForm, inner)));
-    }
     out.push(...renderDossierDelivery(record, context, width));
+    // The gist sits against the body it summarizes: last of the card, directly
+    // above the affordance that opens the text it stands in for.
+    const gist = record.doc.shortForm.trim();
+    if (gist !== '') {
+        out.push('', theme.fg('dim', `${INDENT}SHORT FORM`), ...indent(wrapped(gist, inner)));
+    }
     const lines = bodyLineCount(record.doc.body);
     if (bodyOpen) {
         out.push('');
@@ -139,6 +141,9 @@ export function renderDossierDelivery(record, context, width) {
             ? `capped to ${record.cappedRung} by a profile ceiling on this store`
             : `capped to ${record.cappedRung} by the ${context.capOwner.memory} ceiling on ${context.capOwner.path}`);
     }
+    if (record.deliveryCause !== undefined) {
+        out.push(...dim(record.deliveryCause, width));
+    }
     if (record.shadowedBy !== null) {
         out.push(...indent(wrapped(`shadowed by the ${record.shadowedBy.scope} copy at ${record.shadowedBy.path}`, inner)).map((line) => theme.fg('muted', line)));
     }

package/dist/commands/sys/context/resolve.d.ts

@@ -1,6 +1,7 @@
-import { type MemoryTarget } from '../../../core/memory-resolver.js';
-import { type DeliveryPayload, type DeliveryRecord, type GateOutcome } from '../../../core/substrate/plan.js';
+import { type MemoryDoc, type MemoryTarget } from '../../../core/memory-resolver.js';
+import { type DeliveryPayload, type DeliveryPlan, type DeliveryRecord, type GateOutcome } from '../../../core/substrate/plan.js';
 import { type GateClause } from '../../../core/substrate/gate-explain.js';
+import { deliveryAccounting } from '../../../core/substrate/on-read.js';
 import { type Rung, type SurfaceEntry, type SurfaceEvent } from '../../../core/substrate/schema.js';
 import { type NodeConfigSubject } from '../../../core/substrate/subject-fields.js';
 export declare const resolveLeaf: import("../../../core/command.js").LeafDef;
@@ -26,6 +27,10 @@ export interface PayloadFlags {
 export declare function payloadFor(event: SurfaceEvent, flags: PayloadFlags, target: MemoryTarget): DeliveryPayload;
 export declare function subjectSummary(subject: NodeConfigSubject): Record<string, unknown>;
 export declare function optionalString(value: unknown): string | null;
+export interface EffectiveDeliveryRecord extends DeliveryRecord {
+    /** Present when the renderer raised this doc beyond its direct event plan. */
+    deliveryCause?: string;
+}
 export interface DocRow {
     name: string;
     kind: string;
@@ -40,13 +45,24 @@ export interface DocRow {
     doc_gate: string;
     entry_gate: string | null;
     matched_entry: string | null;
+    delivery_cause?: string;
     excluded?: string;
 }
+/** Overlay the production renderer's actual document deliveries onto direct
+ * planner records. The plan still supplies gates, caps, and exclusion detail;
+ * only an attachment that genuinely rendered may raise its final rung. */
+export declare function effectivePlan(plan: DeliveryPlan, deliveries: ReadonlyMap<string, {
+    rung: Rung;
+    cause?: string;
+    source?: MemoryDoc;
+}>, payload?: DeliveryPayload): DeliveryPlan & {
+    docs: EffectiveDeliveryRecord[];
+};
 /** A document delivers when it won its canonical name AND resolved to a rung
  *  above the no-delivery floor — boot keeps rung-`none` winners in the plan so
  *  the catalog can still count them. */
 export declare function delivers(record: DeliveryRecord): boolean;
-export declare function docRow(record: DeliveryRecord, includeAll: boolean, subject: NodeConfigSubject | null): DocRow;
+export declare function docRow(record: EffectiveDeliveryRecord, includeAll: boolean, subject: NodeConfigSubject | null): DocRow;
 /** A gate verdict as one cell: `pass`, or `fail:` plus the clauses that failed
  *  — the planner's generic sentence only when the explainer cannot decompose
  *  the predicate. */
@@ -55,5 +71,18 @@ export declare function entryText(entry: SurfaceEntry | null): string | null;
 /** Why a considered document delivers nothing, in the order the planner applies
  *  its checks — the first failing one is the answer an engineer acts on. */
 export declare function exclusionReason(record: DeliveryRecord, subject: NodeConfigSubject | null): string;
+/** Every renderer resolves its corpus from the AMBIENT process (cwd plus the
+ *  two env seams), not from a target argument, so a snapshot dialed away from
+ *  this process is only honored by standing in its place for the call. The
+ *  session parse cache is cleared on both sides so neither the emulated corpus
+ *  nor the real one is served from the other's scan. */
+export interface AccountedEventRender {
+    assembled: string;
+    accounting: ReturnType<typeof deliveryAccounting>;
+}
+/** Run the production renderer once and retain the structured document
+ * deliveries it recorded. Context diagnostics and the admin viewer consume
+ * this result rather than reconstructing attachment/companion fixpoints. */
+export declare function assembleEventAccounting(snapshot: ContextSnapshot, event: SurfaceEvent, payload: DeliveryPayload): AccountedEventRender;
 export declare function describeSubject(subject: Record<string, unknown>): string;
 export declare function cell(v: unknown): string;

package/dist/commands/sys/context/resolve.js

@@ -19,9 +19,9 @@ import { planDelivery, } from '../../../core/substrate/plan.js';
 import { explainRecordGate, formatClause } from '../../../core/substrate/gate-explain.js';
 import { emptyContextExposureState, exposureTarget } from '../../../core/substrate/injected-store.js';
 import { renderPreferencesForSubject, renderKnowledgeForSubject } from '../../../core/substrate/render.js';
-import { memoryReadDocBlocks, renderOnCommandDocsForSubject, renderOnReadDocsForSubject, renderPreCommandDocsForSubject, renderWorkspaceOpenDocsForSubject, } from '../../../core/substrate/on-read.js';
+import { deliveryAccounting, memoryReadDocBlocks, renderOnCommandDocsForSubject, renderOnReadDocsForSubject, renderPreCommandDocsForSubject, renderWorkspaceOpenDocsForSubject, } from '../../../core/substrate/on-read.js';
 import { clearSessionCache } from '../../../core/substrate/session-cache.js';
-import { rungAtLeast, SURFACE_EVENTS, } from '../../../core/substrate/schema.js';
+import { parseSubstrateDoc, rungAtLeast, SURFACE_EVENTS, } from '../../../core/substrate/schema.js';
 import { scopeForCwd, profileNameFor } from '../../../core/substrate/subject-fields.js';
 import { resetScopeCache } from '../../../core/scope.js';
 import { getDefaultProfileId } from '../../../core/profiles/default-binding.js';
@@ -52,7 +52,7 @@ export const resolveLeaf = defineLeaf({
             { name: 'event', type: 'string', required: false, constraint: 'The resolved event. Absent with --all-events, where every entry in `plans` carries its own.' },
             { name: 'subject', type: 'object', required: true, constraint: 'The configuration snapshot used: kind, mode, lifecycle, hasManager, profile, scope.' },
             { name: 'target', type: 'object', required: true, constraint: 'Store resolution inputs: cwd, profileId, nodeId.' },
-            { name: 'docs', type: 'array', required: false, constraint: 'One entry per document, at `docs`/`all` granularity: name, kind, scope, store_path, authored_rung, project_memory_cap, capped_rung, final_rung, winner, shadowed_by, doc_gate, entry_gate, matched_entry, and excluded when --all includes a non-delivering document.' },
+            { name: 'docs', type: 'array', required: false, constraint: 'One entry per document, at `docs`/`all` granularity: name, kind, scope, store_path, authored_rung, project_memory_cap, capped_rung, final_rung, winner, shadowed_by, doc_gate, entry_gate, matched_entry, delivery_cause when the renderer raised it through a content attachment, and excluded when --all includes a non-delivering document.' },
             { name: 'counts', type: 'object', required: false, constraint: 'At `summary` granularity: {considered, delivered: {content, preview, name}, delivered_total, excluded: {<reason>: count}}.' },
             { name: 'all_ignored', type: 'boolean', required: false, constraint: 'Present only when --all is supplied with --granularity assembled; true means assembled text is unchanged because --all applies only to docs granularity.' },
             { name: 'assembled', type: 'string', required: false, constraint: 'At `assembled` granularity: the exact text the node would receive for this event.' },
@@ -188,15 +188,59 @@ async function fetchSubjectOrNull(nodeId) {
     }
 }
 function planSection(snapshot, event, payload, granularity, includeAll) {
-    if (granularity === 'assembled') {
-        return { event, assembled: assembleEvent(snapshot, event, payload) };
-    }
-    const plan = planDelivery(snapshot.subject, snapshot.target, event, payload);
+    const rendered = assembleEventAccounting(snapshot, event, payload);
+    if (granularity === 'assembled')
+        return { event, assembled: rendered.assembled };
+    const plan = effectivePlan(planDelivery(snapshot.subject, snapshot.target, event, payload), rendered.accounting.deliveries, payload);
     if (granularity === 'summary')
         return { event, counts: countsOf(plan) };
     const docs = plan.docs.filter((r) => includeAll || delivers(r)).map((r) => docRow(r, includeAll, plan.subject));
     return { event, docs };
 }
+/** Overlay the production renderer's actual document deliveries onto direct
+ * planner records. The plan still supplies gates, caps, and exclusion detail;
+ * only an attachment that genuinely rendered may raise its final rung. */
+export function effectivePlan(plan, deliveries, payload = {}) {
+    const seen = new Set();
+    const docs = plan.docs.map((record) => {
+        seen.add(realpathOrSelf(record.doc.path));
+        const delivered = deliveries.get(realpathOrSelf(record.doc.path));
+        if (delivered === undefined || !rungAtLeast(delivered.rung, record.finalRung))
+            return record;
+        const raised = delivered.rung !== record.finalRung;
+        return {
+            ...record,
+            // A companion has its own memory-read winner set. If it is shadowed or
+            // silent in the outer event plan but genuinely rendered through that
+            // attachment, the rendered delivery is the truth this view reports.
+            ...(raised ? { winner: true, shadowedBy: null } : {}),
+            finalRung: delivered.rung,
+            ...(raised && delivered.cause !== undefined ? { deliveryCause: delivered.cause } : {}),
+        };
+    });
+    for (const delivered of deliveries.values()) {
+        if (delivered.source === undefined || seen.has(realpathOrSelf(delivered.source.path)))
+            continue;
+        const doc = parseSubstrateDoc(delivered.source);
+        if (doc === null)
+            continue;
+        // Workspace-open deliberately plans only project stores, while its real
+        // listing/companion attachments answer from the full target view. Plan this
+        // one rendered source solely to retain normal dossier metadata, then make
+        // its renderer-recorded rung and cause authoritative.
+        const record = planDelivery(plan.subject, plan.target, plan.event, payload, [{ doc, source: delivered.source }]).docs[0];
+        if (record === undefined)
+            continue;
+        docs.push({
+            ...record,
+            winner: true,
+            shadowedBy: null,
+            finalRung: delivered.rung,
+            ...(delivered.cause === undefined ? {} : { deliveryCause: delivered.cause }),
+        });
+    }
+    return { ...plan, docs };
+}
 /** A document delivers when it won its canonical name AND resolved to a rung
  *  above the no-delivery floor — boot keeps rung-`none` winners in the plan so
  *  the catalog can still count them. */
@@ -218,6 +262,7 @@ export function docRow(record, includeAll, subject) {
         doc_gate: gateText(record.docGate, explainRecordGate(record, 'doc', subject)),
         entry_gate: record.entryGate === null ? null : gateText(record.entryGate, explainRecordGate(record, 'entry', subject)),
         matched_entry: entryText(record.matchedEntry),
+        ...(record.deliveryCause === undefined ? {} : { delivery_cause: record.deliveryCause }),
     };
     if (includeAll && !delivers(record))
         row.excluded = exclusionReason(record, subject);
@@ -294,26 +339,23 @@ function exclusionBucket(record) {
     }
     return record.cappedRung === 'none' ? 'capped' : 'rung_none';
 }
-// Assembled granularity — the real renderers, so the highest-fidelity view is
-// byte-identical to what the node receives.
-/** Every renderer resolves its corpus from the AMBIENT process (cwd plus the
- *  two env seams), not from a target argument, so a snapshot dialed away from
- *  this process is only honored by standing in its place for the call. The
- *  session parse cache is cleared on both sides so neither the emulated corpus
- *  nor the real one is served from the other's scan. */
-function assembleEvent(snapshot, event, payload) {
+/** Run the production renderer once and retain the structured document
+ * deliveries it recorded. Context diagnostics and the admin viewer consume
+ * this result rather than reconstructing attachment/companion fixpoints. */
+export function assembleEventAccounting(snapshot, event, payload) {
     const restore = {
         cwd: process.cwd(),
         profileId: envProfileId(),
         nodeId: envNodeId(),
     };
+    const accounting = deliveryAccounting();
     clearSessionCache();
     resetScopeCache();
     try {
         process.chdir(snapshot.target.cwd);
         setEnv('CRTR_PROFILE_ID', snapshot.target.profileId ?? undefined);
         setEnv('CRTR_NODE_ID', snapshot.target.nodeId ?? undefined);
-        return renderEvent(snapshot, event, payload);
+        return { assembled: renderEvent(snapshot, event, payload, accounting), accounting };
     }
     finally {
         process.chdir(restore.cwd);
@@ -329,29 +371,34 @@ function setEnv(name, value) {
     else
         process.env[name] = value;
 }
-function renderEvent(snapshot, event, payload) {
+function renderEvent(snapshot, event, payload, accounting) {
     const { subject, target } = snapshot;
     switch (event) {
         case 'boot': {
-            const { block } = renderPreferencesForSubject(subject);
-            const knowledge = target.nodeId === null ? '' : renderKnowledgeForSubject(subject, target.nodeId);
+            const { block } = renderPreferencesForSubject(subject, undefined, accounting);
+            const knowledge = target.nodeId === null ? '' : renderKnowledgeForSubject(subject, target.nodeId, undefined, accounting);
             return knowledge === '' ? block : `${block}\n\n${knowledge}`;
         }
         case 'workspace-open':
-            return renderWorkspaceOpenDocsForSubject(subject, target.cwd, target.profileId);
+            return renderWorkspaceOpenDocsForSubject(subject, target.cwd, target.profileId, undefined, accounting);
         case 'read':
-            return payload.absoluteFile === undefined ? '' : renderOnReadDocsForSubject(subject, payload.absoluteFile);
+            return payload.absoluteFile === undefined ? '' : renderOnReadDocsForSubject(subject, payload.absoluteFile, undefined, accounting);
         case 'memory-read': {
             const name = payload.resolvedCanonicalName;
             if (name === undefined)
                 return '';
-            const blocks = memoryReadDocBlocks(subject, payload.resolvedDocPath ?? '', name, exposureTarget(emptyContextExposureState(), 'transcript'));
+            const blocks = memoryReadDocBlocks(payload.resolvedDocPath ?? '', name, {
+                subject,
+                target: exposureTarget(emptyContextExposureState(), 'transcript'),
+                listings: 'blocks',
+                accounting,
+            });
             return blocks.length === 0 ? '' : `<auto-loaded-context>\n${blocks.join('\n')}\n</auto-loaded-context>`;
         }
         case 'command':
-            return payload.command === undefined ? '' : renderOnCommandDocsForSubject(subject, payload.command);
+            return payload.command === undefined ? '' : renderOnCommandDocsForSubject(subject, payload.command, undefined, accounting);
         case 'pre-command':
-            return payload.command === undefined ? '' : renderPreCommandDocsForSubject(subject, payload.command);
+            return payload.command === undefined ? '' : renderPreCommandDocsForSubject(subject, payload.command, undefined, accounting);
     }
 }
 /** The read document never delivers to itself, so the plan needs its physical
@@ -403,7 +450,8 @@ function renderSection(section) {
     if (docs.length === 0)
         return 'No document delivers for this event.';
     const showExcluded = docs.some((d) => d.excluded !== undefined);
-    const cols = ['document', 'scope', 'kind', 'authored', 'cap', 'final', 'matched', 'gate', ...(showExcluded ? ['excluded'] : [])];
+    const showCause = docs.some((d) => d.delivery_cause !== undefined);
+    const cols = ['document', 'scope', 'kind', 'authored', 'cap', 'final', 'matched', 'gate', ...(showCause ? ['cause'] : []), ...(showExcluded ? ['excluded'] : [])];
     const rows = docs.map((d) => [
         d.name,
         d.scope,
@@ -413,6 +461,7 @@ function renderSection(section) {
         d.final_rung,
         d.matched_entry ?? '—',
         d.doc_gate,
+        ...(showCause ? [d.delivery_cause ?? ''] : []),
         ...(showExcluded ? [d.excluded ?? ''] : []),
     ]);
     return [

package/dist/commands/sys/panels/models-panel.d.ts

@@ -10,6 +10,8 @@ export declare class ModelsPanel implements SetupPanel {
     private readonly label;
     private mode;
     private ladders;
+    private modelRoutes;
+    private legacyModelRoutes;
     private kinds;
     /** The ladder providers this panel offers — only columns whose runtime
      *  provider is signed in (all of them when nobody is, so config stays
@@ -27,8 +29,11 @@ export declare class ModelsPanel implements SetupPanel {
     private modelSelector;
     private thinkingSelector;
     private pending;
-    private pendingDim;
-    private dimPickIndex;
+    private choice;
+    private choiceIndex;
+    private routeForm;
+    private readonly routeInput;
+    private pendingRouteCell;
     onChange?: () => void;
     constructor(tui: TUI, runtime: ModelRuntime, registry: ModelRegistry, matches: (id: BindingId, data: string) => boolean, label: (id: BindingId) => string);
     /** Same signed-in rule as the broker's Alt+M cycle: pool occupancy for a
@@ -38,6 +43,8 @@ export declare class ModelsPanel implements SetupPanel {
     private cycleTarget;
     private shadowingPath;
     private savedButShadowed;
+    private routeIds;
+    private routeFamilies;
     private buildRows;
     private reload;
     /** Re-read config and auth state — called when the Models tab is entered so
@@ -50,12 +57,26 @@ export declare class ModelsPanel implements SetupPanel {
     private clampColumn;
     handleInput(data: string): boolean;
     private activateCell;
-    /** Snapshot of the mode's current provider+strength. For orchestrator this
+    private portableSelection;
+    private familyLabel;
+    private familyOptions;
+    /** Snapshot of the mode's current family+strength. For orchestrator this
      *  falls back to the base `model` when no explicit override exists, so the
      *  inherited pair is what an edit preserves. */
     private kindSelection;
     private openDimensionPicker;
-    private commitDimensionPick;
+    private writeKindSelection;
+    private commitChoice;
+    private openRouteForm;
+    private closeRouteForm;
+    private activateRouteField;
+    private setRouteProvider;
+    private openRouteCell;
+    private onRouteModelPicked;
+    private saveRoute;
+    private declaringPath;
+    private deleteRoute;
+    private showModelSelector;
     private openModelPicker;
     private onModelPicked;
     private onThinkingPicked;
@@ -66,7 +87,9 @@ export declare class ModelsPanel implements SetupPanel {
     private targetKindOverride;
     footerHint(): string;
     /** Body lines only — the caller frames and windows them. */
-    private renderDimensionPicker;
+    private renderChoicePicker;
+    private renderRouteForm;
+    private renderRouteDelete;
     /** Fits the panel body into `budget` rows. The wizard draws header/tabs above
      *  and a footer below, so a body taller than its budget pushes the tab strip
      *  off the top of the terminal — the panel must window itself instead. Chrome