@north-light/crouter 0.3.262 → 0.3.263

package/dist/core/config.js

@@ -167,66 +167,140 @@ function mergeModelLadders(raw, base = defaultModelLaddersConfig()) {
 function validStrength(value) {
     return value === 'ultra' || value === 'strong' || value === 'medium' || value === 'light';
 }
-/** Validate and overlay route entries. Invalid declarations are loud but local:
- * a typo must not prevent unrelated launch configuration from resolving. */
-function mergeModelRoutes(raw, base = {}) {
-    const out = { ...base };
+const MODEL_STRENGTHS = ['ultra', 'strong', 'medium', 'light'];
+function routeRecord() {
+    return Object.create(null);
+}
+function setRouteRecord(record, routeId, value) {
+    Object.defineProperty(record, routeId, { value, writable: true, enumerable: true, configurable: true });
+}
+function copyRouteRecord(record) {
+    const copy = routeRecord();
+    for (const [routeId, value] of Object.entries(record ?? {}))
+        setRouteRecord(copy, routeId, value);
+    return copy;
+}
+function routeInvalid(routeId, rule) {
+    emitEvent({ level: 'warn', event: 'config.model_routes.invalid', fields: { route_id: routeId, rule } });
+}
+/** Overlay raw route patches first so a higher scope may replace one cell of a
+ * complete lower route. Completeness belongs to the resulting effective route,
+ * never an individual raw scope patch. */
+function mergeModelRoutePatches(raw, base = {}) {
+    const out = copyRouteRecord(base);
     if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
         return out;
     for (const [routeId, value] of Object.entries(raw)) {
-        const patch = value;
-        const invalid = (rule) => { emitEvent({ level: 'warn', event: 'config.model_routes.invalid', fields: { route_id: routeId, rule } }); };
-        if (!patch || typeof patch !== 'object' || Array.isArray(patch)) {
-            invalid('route must be an object');
+        if (routeId.trim() === '') {
+            routeInvalid(routeId, 'route id must be a non-empty string');
             continue;
         }
-        const route = { ...out[routeId], ...patch, models: { ...out[routeId]?.models, ...patch.models } };
-        if (typeof route.family !== 'string' || route.family.trim() === '') {
-            invalid('family must be a non-empty string');
-            continue;
-        }
-        if (typeof route.credentialSource !== 'string' || route.credentialSource.trim() === '') {
-            invalid('credentialSource must be a non-empty string');
-            continue;
-        }
-        if (typeof route.providerId !== 'string' || route.providerId.trim() === '') {
-            invalid('providerId must be a non-empty string');
-            continue;
-        }
-        if (!route.models || typeof route.models !== 'object' || Array.isArray(route.models)) {
-            invalid('models must be an object');
+        if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+            routeInvalid(routeId, 'route must be an object');
             continue;
         }
-        const models = {};
+        const patch = value;
+        const current = out[routeId];
+        const route = { ...current };
         let rule;
-        for (const [strength, spec] of Object.entries(route.models)) {
-            if (!validStrength(strength)) {
-                rule = `models.${strength} is not a model strength`;
-                break;
-            }
-            if (typeof spec !== 'string' || spec.trim() === '') {
-                rule = `models.${strength} must be a non-empty provider/id ref`;
+        for (const field of ['family', 'credentialSource', 'providerId']) {
+            const candidate = patch[field];
+            if (candidate === undefined)
+                continue;
+            if (typeof candidate !== 'string' || candidate.trim() === '') {
+                rule = `${field} must be a non-empty string`;
                 break;
             }
-            const slash = spec.indexOf('/');
-            if (slash <= 0 || slash === spec.length - 1) {
-                rule = `models.${strength} must be provider/id`;
-                break;
+            route[field] = candidate;
+        }
+        if (rule === undefined && patch.models !== undefined) {
+            if (patch.models === null || typeof patch.models !== 'object' || Array.isArray(patch.models))
+                rule = 'models must be an object';
+            else {
+                const models = { ...current?.models };
+                for (const [strength, spec] of Object.entries(patch.models)) {
+                    if (!validStrength(strength)) {
+                        rule = `models.${strength} is not a model strength`;
+                        break;
+                    }
+                    if (typeof spec !== 'string' || spec.trim() === '') {
+                        rule = `models.${strength} must be a non-empty provider/id ref`;
+                        break;
+                    }
+                    const slash = spec.indexOf('/');
+                    if (slash <= 0 || slash === spec.length - 1) {
+                        rule = `models.${strength} must be provider/id`;
+                        break;
+                    }
+                    models[strength] = spec;
+                }
+                route.models = models;
             }
-            if (spec.slice(0, slash) !== route.providerId) {
-                rule = `models.${strength} provider prefix must equal providerId`;
-                break;
+        }
+        if (rule === undefined && route.models !== undefined && route.providerId !== undefined) {
+            for (const [strength, spec] of Object.entries(route.models)) {
+                if (spec.slice(0, spec.indexOf('/')) !== route.providerId) {
+                    rule = `models.${strength} provider prefix must equal providerId`;
+                    break;
+                }
             }
-            models[strength] = spec;
         }
         if (rule !== undefined) {
-            invalid(rule);
+            routeInvalid(routeId, rule);
             continue;
         }
-        out[routeId] = { family: route.family, credentialSource: route.credentialSource, providerId: route.providerId, models };
+        setRouteRecord(out, routeId, route);
     }
     return out;
 }
+/** Resolve complete routes after every scope has overlaid its sparse raw patch.
+ * Sparse standalone routes are read for one compatibility release only: they
+ * retain their historical candidate behavior, emit a repair warning, and never
+ * gain invented cells. New writes cannot create them. */
+function resolveModelRoutes(routes) {
+    const complete = routeRecord();
+    const legacy = routeRecord();
+    for (const [routeId, route] of Object.entries(routes)) {
+        if (route.family === undefined || route.credentialSource === undefined || route.providerId === undefined || route.models === undefined) {
+            routeInvalid(routeId, 'route must include family, credentialSource, providerId, and models');
+            continue;
+        }
+        const missing = MODEL_STRENGTHS.filter((strength) => route.models[strength] === undefined);
+        if (missing.length > 0) {
+            routeInvalid(routeId, `incomplete route; missing strengths: ${missing.join(', ')}`);
+            setRouteRecord(legacy, routeId, { family: route.family, credentialSource: route.credentialSource, providerId: route.providerId, models: route.models });
+            continue;
+        }
+        setRouteRecord(complete, routeId, {
+            family: route.family,
+            credentialSource: route.credentialSource,
+            providerId: route.providerId,
+            models: route.models,
+        });
+    }
+    return { complete, legacy };
+}
+function assertCompleteModelRoute(routeId, route) {
+    if (routeId.trim() === '')
+        throw new Error('model route id must be a non-empty string');
+    for (const field of ['family', 'credentialSource', 'providerId']) {
+        if (typeof route[field] !== 'string' || route[field].trim() === '')
+            throw new Error(`model route "${routeId}" ${field} must be a non-empty string`);
+    }
+    const missing = MODEL_STRENGTHS.filter((strength) => route.models?.[strength] === undefined);
+    if (missing.length > 0)
+        throw new Error(`model route "${routeId}" is incomplete; missing strengths: ${missing.join(', ')}`);
+    for (const strength of MODEL_STRENGTHS) {
+        const spec = route.models[strength];
+        if (typeof spec !== 'string' || spec.trim() === '')
+            throw new Error(`model route "${routeId}" models.${strength} must be a non-empty provider/id ref`);
+        const slash = spec.indexOf('/');
+        if (slash <= 0 || slash === spec.length - 1)
+            throw new Error(`model route "${routeId}" models.${strength} must be provider/id`);
+        if (spec.slice(0, slash) !== route.providerId)
+            throw new Error(`model route "${routeId}" models.${strength} provider prefix must equal providerId`);
+    }
+}
 function mergeModelRouting(raw, base) {
     if (raw === undefined)
         return base;
@@ -679,14 +753,15 @@ function mergeConfig(partial) {
     const keybindings = normalizeKeybindings(partial.keybindings);
     const tmux_passthrough = normalizeTmuxPassthrough(partial.tmux_passthrough);
     const modelLadders = mergeModelLadders(partial.modelLadders);
-    const modelRoutes = mergeModelRoutes(partial.modelRoutes);
+    const routes = resolveModelRoutes(mergeModelRoutePatches(partial.modelRoutes));
+    const modelRoutes = routes.complete;
     const modelRouting = mergeModelRouting(partial.modelRouting, undefined);
     const kinds = mergeKinds(partial.kinds);
     const remoteCanvas = mergeRemoteCanvas(partial.remoteCanvas);
     const spawnEnv = mergeSpawnEnv(partial.spawnEnv, defaults.spawnEnv?.allow);
     const bin = normalizeBin(partial.bin);
     const humanActions = normalizeHumanActions(partial.humanActions);
-    return { bin, humanActions, schema_version, marketplaces, plugins, auto_update, max_panes_per_window, auto_open_child_viewers, brokerThresholds, completion_bell, working_gerunds, whip_mode, page_components, page_surface, whip_messages, whip_message_mode, mouse_mode_default, live_cycles, condensed_history, bash_tool_purpose, fold_finished_tools, summarize_tool_calls, detailed_tool_recaps, keybindings, tmux_passthrough, modelLadders, ...(Object.keys(modelRoutes).length > 0 ? { modelRoutes } : {}), ...(modelRouting !== undefined ? { modelRouting } : {}), kinds, remoteCanvas, spawnEnv };
+    return { bin, humanActions, schema_version, marketplaces, plugins, auto_update, max_panes_per_window, auto_open_child_viewers, brokerThresholds, completion_bell, working_gerunds, whip_mode, page_components, page_surface, whip_messages, whip_message_mode, mouse_mode_default, live_cycles, condensed_history, bash_tool_purpose, fold_finished_tools, summarize_tool_calls, detailed_tool_recaps, keybindings, tmux_passthrough, modelLadders, ...(Object.keys(modelRoutes).length > 0 ? { modelRoutes } : {}), ...(Object.keys(routes.legacy).length > 0 ? { legacyModelRoutes: routes.legacy } : {}), ...(modelRouting !== undefined ? { modelRouting } : {}), kinds, remoteCanvas, spawnEnv };
 }
 /** Raw (un-defaulted) partial config for one scope, or null if the scope has
  *  no root or no config.json. Used by `readMergedLaunchConfig` to layer
@@ -775,13 +850,13 @@ export function readMergedLaunchConfig(targetCwd = process.cwd(), targetProfileI
     // (ladders/routes/spawnEnv) have no plugin channel.
     let kinds = mergeKinds(userRaw?.kinds, layerPluginKinds('user', scopeRoot('user'), defaults.kinds));
     let modelLadders = mergeModelLadders(userRaw?.modelLadders, defaults.modelLadders);
-    let modelRoutes = mergeModelRoutes(userRaw?.modelRoutes);
+    let modelRoutePatches = mergeModelRoutePatches(userRaw?.modelRoutes);
     let modelRouting = mergeModelRouting(userRaw?.modelRouting, undefined);
     let spawnEnv = mergeSpawnEnv(userRaw?.spawnEnv, defaults.spawnEnv?.allow);
     if (profileRaw !== null) {
         kinds = mergeKinds(profileRaw.kinds, kinds);
         modelLadders = mergeModelLadders(profileRaw.modelLadders, modelLadders);
-        modelRoutes = mergeModelRoutes(profileRaw.modelRoutes, modelRoutes);
+        modelRoutePatches = mergeModelRoutePatches(profileRaw.modelRoutes, modelRoutePatches);
         modelRouting = mergeModelRouting(profileRaw.modelRouting, modelRouting);
         spawnEnv = mergeSpawnEnv(profileRaw.spawnEnv, spawnEnv.allow);
     }
@@ -790,11 +865,19 @@ export function readMergedLaunchConfig(targetCwd = process.cwd(), targetProfileI
         if (raw === null)
             continue;
         modelLadders = mergeModelLadders(raw.modelLadders, modelLadders);
-        modelRoutes = mergeModelRoutes(raw.modelRoutes, modelRoutes);
+        modelRoutePatches = mergeModelRoutePatches(raw.modelRoutes, modelRoutePatches);
         modelRouting = mergeModelRouting(raw.modelRouting, modelRouting);
         spawnEnv = mergeSpawnEnv(raw.spawnEnv, spawnEnv.allow);
     }
-    return { kinds, modelLadders, ...(Object.keys(modelRoutes).length > 0 ? { modelRoutes } : {}), ...(modelRouting !== undefined ? { modelRouting } : {}), spawnEnv };
+    const routes = resolveModelRoutes(modelRoutePatches);
+    return {
+        kinds,
+        modelLadders,
+        ...(Object.keys(routes.complete).length > 0 ? { modelRoutes: routes.complete } : {}),
+        ...(Object.keys(routes.legacy).length > 0 ? { legacyModelRoutes: routes.legacy } : {}),
+        ...(modelRouting !== undefined ? { modelRouting } : {}),
+        spawnEnv,
+    };
 }
 /** The effective `KindConfig` for one full kind string (top-level, e.g.
  *  `developer`, or sub-kind, e.g. `audit/security`), across
@@ -930,6 +1013,38 @@ export function persistModelLadders(root, patch) {
         atomicWriteJson(lockedPath, { ...raw, modelLadders: next });
     });
 }
+/** Persist one complete route at one exact config root. The route is the only
+ * raw route entry touched; unrelated routes and local ladder defaults remain
+ * absent. Pass `undefined` to remove this scope's entry, which resumes lower
+ * scope inheritance rather than introducing a tombstone. */
+export function persistModelRoute(root, routeId, route) {
+    if (route !== undefined)
+        assertCompleteModelRoute(routeId, route);
+    else if (routeId.trim() === '')
+        throw new Error('model route id must be a non-empty string');
+    const path = configPathFor(root);
+    ensureDir(root);
+    withConfigPathLock(path, (lockedPath) => {
+        const raw = readJsonIfExists(lockedPath) ?? {};
+        const routes = copyRouteRecord((raw.modelRoutes ?? {}));
+        if (route === undefined)
+            delete routes[routeId];
+        else {
+            const current = routes[routeId];
+            setRouteRecord(routes, routeId, {
+                ...(current !== null && typeof current === 'object' && !Array.isArray(current) ? current : {}),
+                ...route,
+                models: { ...route.models },
+            });
+        }
+        const next = { ...raw };
+        if (Object.keys(routes).length === 0)
+            delete next.modelRoutes;
+        else
+            next.modelRoutes = routes;
+        atomicWriteJson(lockedPath, next);
+    });
+}
 /** Mutate one exact config root. Setup uses this for profile and explicit
  * project targets that cannot be represented by the user/project Scope enum. */
 export function updateConfigAtRoot(root, mutate) {

package/dist/core/keybindings/catalog.js

@@ -72,7 +72,7 @@ export const BINDING_CATALOG = Object.freeze([
     b('crtr.tmux.node.previous', 'Global tmux', 'Previous node', 'Focus the previous canvas node.', ['alt+['], 'host-global', ['tmux.root']),
     b('crtr.tmux.inbox.toggle', 'Global tmux', 'Toggle inbox', 'Open or close the human inbox in the focused viewer.', ['alt+i'], 'host-global', ['tmux.root']),
     ...attachEntry('crtr.tmux.menu.attach.detach', 'crtr.attach.detach', 'Detach', 'Detach from the node.', ['d'], ['ctrl+d']),
-    ...attachEntry('crtr.tmux.menu.attach.clear-or-detach', 'crtr.attach.clear-or-detach', 'Clear input (detach if empty)', 'Clear input or detach when input is empty.', ['c'], ['ctrl+c']),
+    ...attachEntry('crtr.tmux.menu.attach.clear-or-detach', 'crtr.attach.clear-or-detach', 'Clear input (cancel agent on repeat)', 'Clear the input; press again within a second to cancel the running agent turn. Detach lives on its own binding.', ['c'], ['ctrl+c']),
     ...attachEntry('crtr.tmux.menu.attach.graph.toggle', 'crtr.attach.graph.toggle', 'Toggle graph', 'Open or close the graph overlay.', ['g'], ['alt+g']),
     ...attachEntry('crtr.tmux.menu.attach.help.toggle', 'crtr.attach.help.toggle', 'Help', 'Open the attach help overlay.', ['?'], ['alt+shift+k']),
     ...attachEntry('crtr.tmux.menu.attach.inbox.toggle', 'crtr.attach.inbox.toggle', 'Toggle inbox', 'Open or close the human inbox surface in this viewer.', ['i'], []),
@@ -190,13 +190,13 @@ function setupBindings() {
         b('crtr.setup.tab-next', 'Setup', 'Next tab', 'Select the next setup tab.', ['tab', 'right'], 'terminal', SETUP_TAB_CONTEXTS),
         b('crtr.setup.tab-previous', 'Setup', 'Previous tab', 'Select the previous setup tab.', ['shift+tab', 'left'], 'terminal', SETUP_TAB_CONTEXTS),
         b('crtr.setup.open', 'Setup', 'Open', 'Open the selected setup item.', ['enter'], 'terminal', ['setup.login']),
-        b('crtr.setup.list-down', 'Setup', 'Move down', 'Move to the next setup item.', ['j', 'down'], 'terminal', ['setup.list', 'setup.models', 'setup.models.dimension-picker']),
-        b('crtr.setup.list-up', 'Setup', 'Move up', 'Move to the previous setup item.', ['k', 'up'], 'terminal', ['setup.list', 'setup.models', 'setup.models.dimension-picker']),
+        b('crtr.setup.list-down', 'Setup', 'Move down', 'Move to the next setup item.', ['j', 'down'], 'terminal', ['setup.list', 'setup.models', 'setup.models.dimension-picker', 'setup.models.route-form']),
+        b('crtr.setup.list-up', 'Setup', 'Move up', 'Move to the previous setup item.', ['k', 'up'], 'terminal', ['setup.list', 'setup.models', 'setup.models.dimension-picker', 'setup.models.route-form']),
         b('crtr.setup.toggle', 'Setup', 'Toggle', 'Toggle the selected setup item.', ['space'], 'terminal', ['setup.list', 'setup.keybindings']),
         b('crtr.setup.details', 'Setup', 'Show details', 'Show details for the selected item.', ['?'], 'terminal', ['setup.list']),
         b('crtr.setup.advance', 'Setup', 'Advance', 'Advance the setup flow.', ['enter'], 'terminal', ['setup.list']),
-        b('crtr.setup.confirm.accept', 'Setup', 'Confirm', 'Accept the setup confirmation.', ['y', 'enter'], 'terminal', ['setup.confirm']),
-        b('crtr.setup.confirm.back', 'Setup', 'Go back', 'Cancel the setup confirmation.', ['n', 'escape', 'q'], 'terminal', ['setup.confirm'], 'dismiss-modal'),
+        b('crtr.setup.confirm.accept', 'Setup', 'Confirm', 'Accept the setup confirmation.', ['y', 'enter'], 'terminal', ['setup.confirm', 'setup.models.confirm']),
+        b('crtr.setup.confirm.back', 'Setup', 'Go back', 'Cancel the setup confirmation.', ['n', 'escape', 'q'], 'terminal', ['setup.confirm', 'setup.models.confirm'], 'dismiss-modal'),
         b('crtr.setup.keybindings.edit', 'Setup', 'Edit binding', 'Edit the selected binding.', ['enter'], 'terminal', ['setup.keybindings']),
         b('crtr.setup.keybindings.commit-edit', 'Setup', 'Commit edit', 'Commit the active binding edit.', ['enter'], 'terminal', ['setup.keybindings.edit']),
         b('crtr.setup.keybindings.cancel-edit', 'Setup', 'Cancel edit', 'Cancel the active binding edit.', ['escape'], 'terminal', ['setup.keybindings.edit'], 'dismiss-modal'),
@@ -212,10 +212,10 @@ function setupBindings() {
         b('crtr.setup.keybindings.filter-clear', 'Setup', 'Clear filter', 'Clear the keybinding filter.', ['escape'], 'terminal', ['setup.keybindings.filter'], 'dismiss-modal'),
         b('crtr.setup.cell-previous', 'Setup', 'Previous field', 'Select the previous field or setup table cell.', ['h'], 'terminal', ['setup.models', 'setup.keybindings']),
         b('crtr.setup.cell-next', 'Setup', 'Next field', 'Select the next field or setup table cell.', ['l'], 'terminal', ['setup.models', 'setup.keybindings']),
-        b('crtr.setup.models.open', 'Setup', 'Edit model', 'Edit the selected model cell.', ['enter'], 'terminal', ['setup.models']),
+        b('crtr.setup.models.open', 'Setup', 'Edit model', 'Edit the selected model cell or route field.', ['enter'], 'terminal', ['setup.models', 'setup.models.route-form']),
         b('crtr.setup.models.scope-next', 'Setup', 'Next model config scope', 'Edit the next applicable user, profile, or project config.', ['s'], 'terminal', ['setup.models']),
         b('crtr.setup.models.commit', 'Setup', 'Commit pick', 'Commit the provider, strength, model, or thinking-level pick.', ['enter'], 'terminal', ['setup.models.picker', 'setup.models.dimension-picker']),
-        b('crtr.setup.models.cancel', 'Setup', 'Cancel pick', 'Cancel the provider, strength, model, or thinking-level picker.', ['escape'], 'terminal', ['setup.models.picker', 'setup.models.dimension-picker'], 'dismiss-modal'),
+        b('crtr.setup.models.cancel', 'Setup', 'Cancel pick', 'Cancel the model picker or route form.', ['escape'], 'terminal', ['setup.models.picker', 'setup.models.dimension-picker', 'setup.models.route-form'], 'dismiss-modal'),
     ];
 }
 export const BINDING_IDS = new Set(BINDING_CATALOG.map((definition) => definition.id));
@@ -246,4 +246,6 @@ export const SAFETY_REQUIREMENTS = Object.freeze([
     { context: 'setup.models', capability: 'leave-screen' },
     { context: 'setup.models.picker', capability: 'dismiss-modal' },
     { context: 'setup.models.dimension-picker', capability: 'dismiss-modal' },
+    { context: 'setup.models.route-form', capability: 'dismiss-modal' },
+    { context: 'setup.models.confirm', capability: 'dismiss-modal' },
 ]);

package/dist/core/model-routes.js

@@ -19,6 +19,8 @@ function parseSpec(spec) {
 function synthesizeRoutes(ladders) {
     const route = (family) => {
         const providerId = ladders[family].strong.slice(0, ladders[family].strong.indexOf('/'));
+        // `credentialSource` orders routes. Auth and subscription-pool lookup are
+        // provider-wide, keyed by providerId, so this does not select credentials.
         return { family, credentialSource: 'default', providerId, models: ladders[family] };
     };
     return { anthropic: route('anthropic'), openai: route('openai') };
@@ -32,7 +34,10 @@ function strengths(requested, configured) {
 /** Expand config-derived route order only. Availability never affects rank. */
 export function expandModelCandidates(request, cwd, profileId) {
     const cfg = readMergedLaunchConfig(cwd, profileId ?? null);
-    const routes = cfg.modelRoutes && Object.keys(cfg.modelRoutes).length > 0 ? cfg.modelRoutes : synthesizeRoutes(cfg.modelLadders);
+    // Complete routes are the effective contract. Sparse entries written by an
+    // older crouter release remain readable for one cutover release only.
+    const declaredRoutes = { ...(cfg.modelRoutes ?? {}), ...(cfg.legacyModelRoutes ?? {}) };
+    const routes = Object.keys(declaredRoutes).length > 0 ? declaredRoutes : synthesizeRoutes(cfg.modelLadders);
     const routeEntries = Object.entries(routes);
     const fallback = cfg.modelRouting?.strengthFallback ?? [readRotationConfig().defaultFallbackStrength ?? 'strong'];
     const declarationFamilies = routeEntries.map(([, route]) => route.family).filter((value, index, all) => all.indexOf(value) === index);
@@ -79,7 +84,9 @@ export function expandModelCandidates(request, cwd, profileId) {
             return;
         if (concrete && parsed.modelId !== concrete.modelId)
             return;
-        const key = `${parsed.providerId}/${parsed.modelId}:${parsed.thinkingLevel ?? ''}`;
+        // Route identity is meaningful: two panel-managed routes can intentionally
+        // share a provider/model while carrying distinct credential-source order.
+        const key = JSON.stringify([routeId, parsed.providerId, parsed.modelId, parsed.thinkingLevel]);
         if (seen.has(key))
             return;
         seen.add(key);
@@ -91,7 +98,7 @@ export function expandModelCandidates(request, cwd, profileId) {
     if (concrete) {
         const [routeId, route] = concreteRoute ?? [
             'concrete',
-            { family: requestedFamily, credentialSource: 'default', providerId: concrete.providerId, models: { [requestedStrength]: request.spec } },
+            { family: requestedFamily, credentialSource: 'default' },
         ];
         append(routeId, route, requestedStrength, request.spec);
     }

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

@@ -25,4 +25,4 @@ export declare function docListingDirs(byName: ReadonlyMap<string, MemoryDoc>, n
  *  `filterDelivered` additionally drops members already exposed at preview rank
  *  or higher. A subdirectory always keeps its row — it advertises a subtree, so
  *  an omitted preview leaves the bare name. */
-export declare function renderDirListing(byName: ReadonlyMap<string, MemoryDoc>, dir: string, target: ExposureTarget | null, filterDelivered: boolean): string[];
+export declare function renderDirListing(byName: ReadonlyMap<string, MemoryDoc>, dir: string, target: ExposureTarget | null, filterDelivered: boolean, onPreview?: (doc: MemoryDoc) => void): string[];

package/dist/core/substrate/listings.js

@@ -93,7 +93,7 @@ function line(name, suffix) {
  *  `filterDelivered` additionally drops members already exposed at preview rank
  *  or higher. A subdirectory always keeps its row — it advertises a subtree, so
  *  an omitted preview leaves the bare name. */
-export function renderDirListing(byName, dir, target, filterDelivered) {
+export function renderDirListing(byName, dir, target, filterDelivered, onPreview) {
     const node = treeFor(byName).node(dir);
     if (node === null)
         return [];
@@ -102,10 +102,14 @@ export function renderDirListing(byName, dir, target, filterDelivered) {
         const suffix = previewSuffix(member.document, target, filterDelivered);
         if (suffix === null)
             continue;
+        onPreview?.(member.document);
         lines.push(line(member.name, suffix));
     }
     for (const sub of node.childDirectories) {
-        lines.push(line(sub.name, sub.document === null ? null : previewSuffix(sub.document, target, filterDelivered)));
+        const suffix = sub.document === null ? null : previewSuffix(sub.document, target, filterDelivered);
+        if (sub.document !== null && suffix !== null)
+            onPreview?.(sub.document);
+        lines.push(line(sub.name, suffix));
     }
     return lines;
 }

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

@@ -1,8 +1,62 @@
+import { type MemoryDoc, type MemoryTarget } from '../memory-resolver.js';
 import { type ContextExposureState, type ExposureTarget } from './injected-store.js';
+import { type Rung, type SubstrateDoc } from './schema.js';
 import type { NodeConfigSubject } from './subject-fields.js';
+export type DeliveryCause = 'directory listing attached to content delivery' | 'memory-read companion of content delivery';
+export interface AccountedDelivery {
+    rung: Rung;
+    cause?: DeliveryCause;
+    /** Resolver descriptor for accounting-only attachment rows. */
+    source?: MemoryDoc;
+}
+/** The renderer's structured delivery ledger. It records precisely the document
+ * envelopes and listing lines that rendered, so diagnostics can report the
+ * same attachment fixpoint without parsing its text or recreating it. */
+export interface DeliveryAccounting {
+    deliveries: Map<string, AccountedDelivery>;
+}
+export declare function deliveryAccounting(): DeliveryAccounting;
+export declare function accountDelivery(accounting: DeliveryAccounting | undefined, doc: Pick<SubstrateDoc, 'path'>, rung: Rung, cause?: DeliveryCause, source?: MemoryDoc): void;
+/** How one content delivery's attachments render, and the ledger + corpus the
+ *  whole fixpoint runs against. ONE options object flows through every nested
+ *  companion delivery, so `dirs` accumulates across the fixpoint and a
+ *  companion inherits its parent's listing mode and memory target. */
+export interface ContentAttachmentOptions {
+    /** Subject for companion `memory-read` gate evaluation. */
+    subject: NodeConfigSubject | null;
+    /** The one exposure ledger this fixpoint reads and registers against. */
+    target: ExposureTarget;
+    /** The corpus every directory question answers from — the caller's own
+     *  listing corpus, never an ambient re-resolution. */
+    byName: ReadonlyMap<string, MemoryDoc>;
+    /** What companion `memory-read` routes plan against. Absent = the ambient
+     *  cwd/profile target and this session's cached event corpus. */
+    memoryTarget?: MemoryTarget;
+    /** `blocks` attaches each disclosed listing as its own `<memory-listing>`.
+     *  `tree` attaches none and accumulates the disclosed directories into
+     *  `dirs` instead, for a caller that renders those members itself (the boot
+     *  catalog tree) and registers them as it renders. */
+    listings: 'blocks' | 'tree';
+    /** Accumulator for `tree` mode: every directory this fixpoint disclosed. */
+    dirs?: string[];
+    /** An explicit `crtr memory read`: the read doc's OWN directory renders
+     *  unfiltered and returns as `listing` rather than attaching as a block. */
+    explicit?: boolean;
+    /** Optional structured mirror of the actual emitted document deliveries. */
+    accounting?: DeliveryAccounting;
+    /** Why this winner was reached through the current content attachment walk. */
+    deliveryCause?: DeliveryCause;
+}
+/** The attachment semantics of a content delivery. Content is read-equivalent:
+ * it exposes its own/enclosing directory listings and fires memory-read routes.
+ * The exposure ledger makes this finite even when companion routes cycle. */
+export declare function contentReadAttachments(doc: Pick<SubstrateDoc, 'name' | 'path' | 'body'>, opts: ContentAttachmentOptions): {
+    blocks: string[];
+    listing?: string[];
+};
 /** Surface docs whose `read` entries match a successfully read file, using
  * the caller-supplied daemon snapshot subject. */
-export declare function renderOnReadDocsForSubject(subject: NodeConfigSubject, readFilePath: string, target?: ExposureTarget): string;
+export declare function renderOnReadDocsForSubject(subject: NodeConfigSubject, readFilePath: string, target?: ExposureTarget, accounting?: DeliveryAccounting): string;
 /** Workspace boot docs using the snapshot's cwd/profile instead of a canvas
  * lookup. The shared exposure target prevents a later read from repeating a
  * document already loaded here.
@@ -11,24 +65,26 @@ export declare function renderOnReadDocsForSubject(subject: NodeConfigSubject, r
  * relationship cap BEFORE filtering, ordering, rendering, and exposure
  * registration. A later explicit `crtr memory read` can still raise a document
  * that workspace-open disclosed at a lower rung. */
-export declare function renderWorkspaceOpenDocsForSubject(subject: NodeConfigSubject, cwd: string, profileId: string | null, target?: ExposureTarget): string;
+export declare function renderWorkspaceOpenDocsForSubject(subject: NodeConfigSubject, cwd: string, profileId: string | null, target?: ExposureTarget, accounting?: DeliveryAccounting): string;
 /** Inner `<memory>` blocks for the memory-read event: docs whose
  * `memory-read` entries match the doc a `crtr memory read` just resolved
  * (known by its exact canonical `name` — no mount-stripped or other alias;
  * `excludeRealpath` keeps the resolved doc from delivering itself). Returns
  * unwrapped blocks — the read leaf composes one `<auto-loaded-context>`
  * envelope from these plus the directory listings. */
-export declare function memoryReadDocBlocks(subject: NodeConfigSubject | null, excludeRealpath: string, name: string, target: ExposureTarget): string[];
+export declare function memoryReadDocBlocks(excludeRealpath: string, name: string, opts: Omit<ContentAttachmentOptions, 'byName'> & {
+    byName?: ReadonlyMap<string, MemoryDoc>;
+}): string[];
 /** Surface docs whose `command` entries match an executed bash command.
  * The corpus is the resolved cwd/profile set; a command has no file from which
  * to discover enclosing project stores. */
-export declare function renderOnCommandDocsForSubject(subject: NodeConfigSubject, command: string, target?: ExposureTarget): string;
+export declare function renderOnCommandDocsForSubject(subject: NodeConfigSubject, command: string, target?: ExposureTarget, accounting?: DeliveryAccounting): string;
 /** Surface docs whose `pre-command` entries match a bash command that has NOT
  * run yet. The exact twin of the post-execution renderer above, and its empty
  * string is load-bearing: `''` means every matching doc is already exposed at
  * its matching rung or above, which is the release — the caller lets the
  * command through. */
-export declare function renderPreCommandDocsForSubject(subject: NodeConfigSubject, command: string, target?: ExposureTarget): string;
+export declare function renderPreCommandDocsForSubject(subject: NodeConfigSubject, command: string, target?: ExposureTarget, accounting?: DeliveryAccounting): string;
 /** Does ANY doc in this session's corpus carry a `pre-command` entry? The
  * short-circuit a pre-execution caller checks first: with no such doc — the
  * common case — no command need ever pay for a subject lookup. */