@north-light/crouter 0.3.182 → 0.3.184

package/dist/core/__tests__/watchdog-abort-arms-retry.test.js

@@ -4,7 +4,7 @@ import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { FaultRetry } from '../runtime/broker/fault-retry.js';
-import { readFault } from '../runtime/fault.js';
+import { readFault, recordFault } from '../runtime/fault.js';
 let home;
 before(() => {
     home = mkdtempSync(join(tmpdir(), 'crtr-watchdog-abort-retry-'));
@@ -48,3 +48,36 @@ test('only a watchdog-stamped aborted settlement records an automatic connection
     settleAbort('human-node', false);
     assert.equal(readFault('human-node'), null, 'an otherwise-identical human abort must not arm recovery');
 });
+test('a failed retry settlement carries the episode forward instead of restarting it', () => {
+    // The episode marker a daemon retry records before re-prompting: original
+    // anchor, start time, and the attempt just consumed.
+    recordFault('retry-episode-node', {
+        link: 'pi→provider', op: 'generation turn', kind: 'connection',
+        retry: { disposition: 'auto', by: 'daemon', attempt: 2, max: 8 },
+        message: 'connection reset', since: '2026-01-01T00:00:00.000Z', anchorEntryId: 'original-anchor',
+    });
+    const session = {
+        sessionManager: { getLeafId: () => 'leaf-after-failed-retry' },
+        model: undefined,
+    };
+    const generation = {
+        id: 1,
+        session,
+        fallback: { blocked: false },
+        stagedProviderAgentEnd: {
+            messages: [{ role: 'assistant', stopReason: 'error', errorMessage: 'fetch failed' }],
+        },
+        stagedWatchdogAbort: false,
+        stagedOverflowFailure: null,
+        executingTools: new Set(),
+    };
+    new FaultRetry({
+        nodeId: 'retry-episode-node',
+        currentSession: () => session,
+        installedGeneration: () => generation,
+    }).publishSettledProviderFault(generation);
+    const fault = readFault('retry-episode-node');
+    assert.equal(fault?.anchorEntryId, 'original-anchor', 'each retry must rewind to the original fork point, not stack prompts');
+    assert.equal(fault?.since, '2026-01-01T00:00:00.000Z', 'the episode start survives a failed retry');
+    assert.equal(fault?.retry.attempt, 2, 'the attempt count accumulates toward exhaustion');
+});

package/dist/core/canvas/nav-model.d.ts

@@ -1,13 +1,6 @@
 import { type FlatRow, type FoldState, type SubtreeActivity } from './nav-render.js';
-import type { NodeMeta, SubscriptionRef } from './index.js';
+import type { NodeMeta } from './index.js';
 export { PI_MAX_WIDGET_LINES, VIEWPORT_FALLBACK_ROWS, ESC, RESET, BOLD, DIM, REVERSE, BG_ATTACHED, GREEN, RED, YELLOW, CYAN, GRAY, nodeGlyph, visibleWidth, truncate, fillWidth, fillBar, readTelemetry, fmtTokens, tokensCell, activityCell, cycleBadge, navLabel, shortId, askBadge, liveBelowBadge, isAttached, hasBrokerViewers, fetchAsksMap, graphWidgetBudget, GRAPH_HINT, type Telemetry, type FlatRow, type FoldState, type SubtreeActivity, } from './nav-render.js';
-export declare function beginFrame(): void;
-/** getNode memoized for the current frame (meta.json read + sqlite row). */
-export declare function cNode(id: string): NodeMeta | null;
-/** subscriptionsOf (a node's reports) memoized for the current frame. */
-export declare function cSubscriptions(id: string): SubscriptionRef[];
-/** subscribersOf (a node's managers) memoized for the current frame. */
-export declare function cSubscribers(id: string): SubscriptionRef[];
 /** First manager (by created) — the UP step for the ancestry spine. */
 export declare function managerOf(id: string): string | undefined;
 /** A kind:'human' node is a control-plane ASK (a deck on the human's

package/dist/core/canvas/nav-model.js

@@ -15,74 +15,45 @@ import { activeFaultForDisplay } from './render.js';
 import { readFault } from '../runtime/fault.js';
 import { faultSummary } from './status-glyph.js';
 import { statusRank } from './node-order.js';
-import { beginFrameTelem, nodeGlyph, navLabel, shortId, tokensCell, activityCell, cycleBadge, askBadge, liveBelowBadge, truncate, fillBar, fillWidth, isAttached, BOLD, DIM, RESET, REVERSE, BG_ATTACHED, } from './nav-render.js';
+import { nodeGlyph, navLabel, shortId, tokensCell, activityCell, cycleBadge, askBadge, liveBelowBadge, truncate, fillBar, fillWidth, isAttached, BOLD, DIM, RESET, REVERSE, BG_ATTACHED, } from './nav-render.js';
 // Re-export the pure render/telemetry half so existing nav-model importers
 // (chrome/canvas-panels, overlays/graph, resume) keep resolving these here.
 export { PI_MAX_WIDGET_LINES, VIEWPORT_FALLBACK_ROWS, ESC, RESET, BOLD, DIM, REVERSE, BG_ATTACHED, GREEN, RED, YELLOW, CYAN, GRAY, nodeGlyph, visibleWidth, truncate, fillWidth, fillBar, readTelemetry, fmtTokens, tokensCell, activityCell, cycleBadge, navLabel, shortId, askBadge, liveBelowBadge, isAttached, hasBrokerViewers, fetchAsksMap, graphWidgetBudget, GRAPH_HINT, } from './nav-render.js';
 // ---------------------------------------------------------------------------
-// Per-frame read cache
+// Read primitives — UNCACHED, deliberately
 //
-// One render fans the SAME handful of nodes out 5-10× each: computeSubtreeActivity
-// walks the whole tree (getNode + subscriptions per node), buildGraphModel walks it
-// again (climbRoot, sortedChildIds), then every visible row re-reads getNode +
-// telemetry + subscriptions for its badges. getNode alone is an fs.readFileSync of
-// meta.json plus a sqlite row read, and readTelemetry another readFileSync — so on a
-// modest graph a single 'j' keystroke fanned out to DOZENS of redundant disk reads.
-// That redundancy is the GRAPH view's open/scroll lag.
+// These once memoized into module-global Maps that a `beginFrame()` cleared at
+// the top of each TUI render. That cache is gone. Nothing in this module is
+// frame-scoped any more: the GRAPH overlay reads the canvas through crtrd's
+// remote CanvasSource (clients/attach/overlays/graph.ts) and never imports this
+// file, while the one live consumer left — crtrd's `GET /v1/nodes?under=` via
+// `subtreeIds` — is a daemon that runs for HOURS between restarts.
 //
-// Each render is a synchronous snapshot, so we memoize the read primitives for the
-// duration of one frame and clear at the top of render(): the next keystroke (or the
-// ask-poll / inbox render) re-reads fresh, so a killed node, a new spawn, or a status
-// flip all surface on the very next frame. Nothing here writes, so a stale entry can
-// at worst be one frame old — and render() always reruns immediately after any action.
-// The telemetry cache lives in nav-render (readTelemetry); beginFrame clears it too.
+// A process-lifetime memo there is not "at worst one frame stale", it is
+// permanent: the first `?under=X` request that lands before X has spawned any
+// children pinned `[]` under X and every later request returned it. Correctness
+// on the daemon outranks a render amortization no caller asks for, so each read
+// goes straight to the canvas db. The only frame cache still in play is
+// nav-render's telemetry memo, whose TUI callers clear it themselves via
+// `beginFrameTelem()`.
 // ---------------------------------------------------------------------------
-const frameNodes = new Map();
-const frameSubs = new Map();
-const frameMgrs = new Map();
-export function beginFrame() {
-    frameNodes.clear();
-    frameSubs.clear();
-    frameMgrs.clear();
-    beginFrameTelem();
-}
-/** getNode memoized for the current frame (meta.json read + sqlite row). */
-export function cNode(id) {
-    if (frameNodes.has(id))
-        return frameNodes.get(id) ?? null;
-    const v = getNode(id);
-    frameNodes.set(id, v);
-    return v;
-}
-/** subscriptionsOf (a node's reports) memoized for the current frame. */
-export function cSubscriptions(id) {
-    const hit = frameSubs.get(id);
-    if (hit !== undefined)
-        return hit;
-    let v;
+/** subscriptionsOf (a node's reports); an unreadable row reads as no edges. */
+function subsOf(id) {
     try {
-        v = subscriptionsOf(id);
+        return subscriptionsOf(id);
     }
     catch {
-        v = [];
+        return [];
     }
-    frameSubs.set(id, v);
-    return v;
 }
-/** subscribersOf (a node's managers) memoized for the current frame. */
-export function cSubscribers(id) {
-    const hit = frameMgrs.get(id);
-    if (hit !== undefined)
-        return hit;
-    let v;
+/** subscribersOf (a node's managers); an unreadable row reads as no edges. */
+function mgrsOf(id) {
     try {
-        v = subscribersOf(id);
+        return subscribersOf(id);
     }
     catch {
-        v = [];
+        return [];
     }
-    frameMgrs.set(id, v);
-    return v;
 }
 // ---------------------------------------------------------------------------
 // Attachment — is a human currently WATCHING a node? A separate axis from
@@ -100,7 +71,7 @@ export function cSubscribers(id) {
 // ---------------------------------------------------------------------------
 /** First manager (by created) — the UP step for the ancestry spine. */
 export function managerOf(id) {
-    return cSubscribers(id)[0]?.node_id;
+    return mgrsOf(id)[0]?.node_id;
 }
 /** A kind:'human' node is a control-plane ASK (a deck on the human's
  *  screen), NOT a pi conversation — it has no session, so focusing/reviving it
@@ -110,17 +81,17 @@ export function managerOf(id) {
  *  own. Drop it from every navigable list (the tree, BASE reports, child counts,
  *  subtree expansion) so it can never be selected. */
 export function isHumanAsk(id) {
-    return cNode(id)?.kind === 'human';
+    return getNode(id)?.kind === 'human';
 }
 /** A node's direct children that are navigable conversations — human-ask nodes
  *  dropped. The one place the nav chrome enumerates children. */
 export function convoChildIds(id) {
-    return cSubscriptions(id).map((s) => s.node_id).filter((cid) => !isHumanAsk(cid));
+    return subsOf(id).map((s) => s.node_id).filter((cid) => !isHumanAsk(cid));
 }
 /** Live reports (active|idle) of a node — the DOWN set in BASE. */
 export function liveReports(id) {
     return convoChildIds(id).filter((cid) => {
-        const st = cNode(cid)?.status;
+        const st = getNode(cid)?.status;
         return st === 'active' || st === 'idle';
     });
 }
@@ -175,7 +146,7 @@ export function childBadge(node) {
  *  the tree and when stepping into a subtree (`l`). Array.sort is stable, so
  *  equal-status siblings keep their creation order. */
 export function sortedChildIds(id) {
-    return convoChildIds(id).sort((a, b) => statusRank(cNode(a)?.status) - statusRank(cNode(b)?.status));
+    return convoChildIds(id).sort((a, b) => statusRank(getNode(a)?.status) - statusRank(getNode(b)?.status));
 }
 // ---------------------------------------------------------------------------
 // GRAPH model — flatten the local graph fold-aware. Rebuilt every render (cheap
@@ -189,7 +160,7 @@ export function computeSubtreeActivity(root, self) {
     // Returns the count of active nodes in subtree(id) INCLUDING id, and whether
     // that subtree is worth revealing (holds an active node or self).
     const visit = (id) => {
-        const selfActive = cNode(id)?.status === 'active';
+        const selfActive = getNode(id)?.status === 'active';
         if (seen.has(id))
             return { active: selfActive ? 1 : 0, reveal: selfActive || id === self };
         seen.add(id);
@@ -254,7 +225,7 @@ export function renderGraphRow(r, isCursor, focused, activeBelow, asks) {
         const line = `${r.branch}  ${DIM}↺ ${shortId(r.id)}${RESET}`;
         return wrap(line, false);
     }
-    const node = cNode(r.id);
+    const node = getNode(r.id);
     const dot = nodeGlyph(node);
     const rawName = navLabel(node, r.id);
     const name = r.isSelf ? `${BOLD}${rawName}${RESET}` : rawName;

package/dist/core/canvas/nav-render.d.ts

@@ -50,8 +50,8 @@ export declare function fillWidth(): number;
  *  bar; the visible width is padded out to `width`; the line closes with a real
  *  RESET so the style never bleeds into the editor below. */
 export declare function fillBar(content: string, width: number, open: string): string;
-/** Clear the per-frame telemetry cache. Called from nav-model's beginFrame so
- *  the graph half and the render half share one frame boundary. */
+/** Clear the per-frame telemetry cache. Every render pass calls this first, so
+ *  one keystroke re-reads each node's telemetry exactly once. */
 export declare function beginFrameTelem(): void;
 export interface Telemetry {
     /** Live context-window size (pi's getContextUsage) — the figure pi's own footer

package/dist/core/canvas/nav-render.js

@@ -130,14 +130,16 @@ export function fillBar(content, width, open) {
     return `${open}${reasserted}${' '.repeat(pad)}${RESET}`;
 }
 // ---------------------------------------------------------------------------
-// Per-frame telemetry cache. Cleared at the top of each render pass (nav-model's
-// beginFrame calls beginFrameTelem) so token/activity cells read fresh once per
-// frame instead of once per row. Nothing here writes, so a stale entry can at
-// worst be one frame old.
+// Per-frame telemetry cache. Its callers are TUI render passes ONLY (the GRAPH
+// overlay and the canvas panels), each of which calls beginFrameTelem() at the
+// top of the pass, so token/activity cells read fresh once per frame instead of
+// once per row and a stale entry can at worst be one frame old. Never memoize a
+// canvas read for a caller that is not a render pass: crtrd lives for hours, and
+// a memo it never clears is permanent, not per-frame.
 // ---------------------------------------------------------------------------
 const frameTelem = new Map();
-/** Clear the per-frame telemetry cache. Called from nav-model's beginFrame so
- *  the graph half and the render half share one frame boundary. */
+/** Clear the per-frame telemetry cache. Every render pass calls this first, so
+ *  one keystroke re-reads each node's telemetry exactly once. */
 export function beginFrameTelem() {
     frameTelem.clear();
 }

package/dist/core/command.js

@@ -580,9 +580,11 @@ export async function parseArgv(params, tokens, options) {
 export async function runCli(root, argv) {
     // argv is process.argv — strip node binary + script path. `--json` is a
     // global: pull it out anywhere it appears so the rest of argv parses against
-    // the leaf schema unchanged, and switch stdout from rendered prose to raw
-    // JSON. It is intentionally undocumented — the default prose output is the
-    // agent contract; --json exists only for programmatic/tooling consumers.
+    // the leaf schema unchanged, and switch stdout from rendered prose to the
+    // leaf's declared `outputs` object as raw JSON. Prose stays the contract for
+    // an agent READING output; --json is the documented channel (root -h globals)
+    // for scripts — a cron's bash, external tooling — that must branch on canvas
+    // state and would otherwise scrape markdown.
     // `--no-autostart` is likewise a global: it suppresses cold-socket daemon
     // autostart (read from `process.argv` in `cliClient`, spec §7.1) and applies
     // to every API-backed verb, so strip it here rather than declaring it on each

package/dist/core/fault-classifier.d.ts

@@ -1,5 +1,5 @@
 import type { ErrorClass, OperationId } from './events/types.js';
-export type FaultLink = 'pi→provider' | 'viewer↔broker' | 'relay↔broker' | 'viewer↔crtrd' | 'cli→exa' | 'daemon→node' | 'crtr→pi';
+export type FaultLink = 'pi→provider' | 'viewer↔broker' | 'relay↔broker' | 'viewer↔crtrd' | 'daemon→node' | 'crtr→pi';
 export type FaultKind = 'rate-limit' | 'overloaded' | 'connection' | 'auth' | 'protocol' | 'context-overflow' | 'other' | 'wedged' | 'model-not-found';
 export type FaultRetryDisposition = 'auto' | 'manual' | 'fatal';
 export type FaultRetryOwner = 'sdk' | 'daemon' | 'client';

package/dist/core/fault-classifier.js

@@ -27,6 +27,13 @@ function classifyProviderText(message) {
     // must not become a retryable transport interruption.
     if (/rate.?limit|\b429\b|too many requests|quota/i.test(m))
         return 'rate-limit';
+    // A body the other side refuses for SIZE is the request itself being
+    // unacceptable, never a transient server condition: the retry re-posts the
+    // same conversation and fails identically, forever. This must precede the
+    // overloaded rule, which otherwise claims a size rejection wrapped in 5xx
+    // prose ("500 ... request entity too large") and arms an unwinnable retry.
+    if (/\b413\b|payload too large|entity too large|request too large|entity\.too\.large|body exceeds/i.test(m))
+        return 'protocol';
     if (/invalid_grant|refresh token|unauthori[sz]ed|invalid.?api.?key|authentication failed|\b401\b|\b403\b/i.test(m))
         return 'auth';
     // pi compacts and retries a raw provider overflow. Its failed-recovery result

package/dist/core/fs-utils.js

@@ -124,7 +124,12 @@ export function linkOrCopy(target, linkPath, opts = {}) {
     removePath(linkPath);
     const isWindows = platform() === 'win32';
     if (!opts.noSymlink && !isWindows) {
-        const rel = relative(dirname(linkPath), target);
+        // The kernel resolves a relative link against the link's *physical*
+        // directory, so both ends must be realpaths: computing `..` hops from a
+        // lexical path whose ancestor is itself a symlink (macOS /tmp →
+        // /private/tmp) walks up the wrong chain and silently creates a dangling
+        // link, since symlinkSync never checks the target.
+        const rel = relative(realpathOrSelf(dirname(linkPath)), realpathOrSelf(target));
         try {
             symlinkSync(rel, linkPath, isDir(target) ? 'dir' : 'file');
             return 'symlink';

package/dist/core/keybindings/index.d.ts

@@ -1,6 +1,6 @@
 export { BINDING_CATALOG, BINDING_IDS, SAFETY_REQUIREMENTS, isAttachPaneBinding, type BindingId, } from './catalog.js';
 export { GestureSyntaxError, KeybindingValidationError, normalizeGesture, normalizeSparseOverrides, normalizeStroke, resolveKeybindings, resolveUserKeybindingSettings, resolveUserKeybindings, splitGestureExpression, type UserKeybindingSettings, } from './resolve.js';
-export { canonicalTerminalStroke, formatBinding, formatGesture, formatStroke, matchesPiTuiInput, matchesTerminalInput, type PiTuiMatcher, type RawTerminalInput, } from './match.js';
+export { canonicalTerminalStroke, formatBinding, formatGesture, formatStroke, matchesPiTuiInput, matchesTerminalInput, normalizeShiftedMeta, type PiTuiMatcher, type RawTerminalInput, } from './match.js';
 export { inboxOpenHint, inboxShortcut, } from './inbox.js';
 export { backgroundBashHint, backgroundBashShortcut, } from './background-bash.js';
 export { ATTACH_CONTROL_BINDINGS, decodeAttachControlInput, encodeAttachControlInput, extractAttachControlInput, type AttachBindingId, type AttachMenuBindingId, type ExtractedAttachControlInput, } from './attach-control.js';

package/dist/core/keybindings/index.js

@@ -1,6 +1,6 @@
 export { BINDING_CATALOG, BINDING_IDS, SAFETY_REQUIREMENTS, isAttachPaneBinding, } from './catalog.js';
 export { GestureSyntaxError, KeybindingValidationError, normalizeGesture, normalizeSparseOverrides, normalizeStroke, resolveKeybindings, resolveUserKeybindingSettings, resolveUserKeybindings, splitGestureExpression, } from './resolve.js';
-export { canonicalTerminalStroke, formatBinding, formatGesture, formatStroke, matchesPiTuiInput, matchesTerminalInput, } from './match.js';
+export { canonicalTerminalStroke, formatBinding, formatGesture, formatStroke, matchesPiTuiInput, matchesTerminalInput, normalizeShiftedMeta, } from './match.js';
 export { inboxOpenHint, inboxShortcut, } from './inbox.js';
 export { backgroundBashHint, backgroundBashShortcut, } from './background-bash.js';
 export { ATTACH_CONTROL_BINDINGS, decodeAttachControlInput, encodeAttachControlInput, extractAttachControlInput, } from './attach-control.js';

package/dist/core/keybindings/match.d.ts

@@ -26,4 +26,15 @@ export interface RawTerminalInput {
 export declare function canonicalTerminalStroke(raw: RawTerminalInput): string | null;
 export declare function matchesTerminalInput(bindingSet: BindingResolution<BindingId>, id: BindingId, raw: RawTerminalInput): boolean;
 export type PiTuiMatcher<Input> = (input: Input, gesture: string) => boolean;
+/** Rewrite the two Alt+Shift+<letter> encodings pi-tui does not recognize into
+ * the canonical shift+alt CSI-u sequence it does.
+ *
+ * A terminal that sends Option as a meta prefix emits Alt+Shift+M as the legacy
+ * two-byte `ESC M`, and tmux re-encodes that as CSI-u carrying the UPPERCASE
+ * codepoint with only the alt bit set (`ESC [ 77 ; 3 u`). pi-tui matches
+ * `alt+shift+m` against `ESC [ 109 ; 4 u` / `ESC [ 77 ; 4 u` and rejects both
+ * unshifted forms, so every Alt+Shift chord would be dead on those terminals.
+ * An uppercase letter cannot be typed without Shift, so restoring the bit adds
+ * nothing the keyboard did not already carry. Anything else passes through. */
+export declare function normalizeShiftedMeta(data: string): string;
 export declare function matchesPiTuiInput<Input>(bindingSet: BindingResolution<BindingId>, id: BindingId, input: Input, matchesKey: PiTuiMatcher<Input>): boolean;

package/dist/core/keybindings/match.js

@@ -100,6 +100,28 @@ export function matchesTerminalInput(bindingSet, id, raw) {
     const stroke = canonicalTerminalStroke(raw);
     return stroke !== null && bindingSet.gestures(id).includes(stroke);
 }
+/** Rewrite the two Alt+Shift+<letter> encodings pi-tui does not recognize into
+ * the canonical shift+alt CSI-u sequence it does.
+ *
+ * A terminal that sends Option as a meta prefix emits Alt+Shift+M as the legacy
+ * two-byte `ESC M`, and tmux re-encodes that as CSI-u carrying the UPPERCASE
+ * codepoint with only the alt bit set (`ESC [ 77 ; 3 u`). pi-tui matches
+ * `alt+shift+m` against `ESC [ 109 ; 4 u` / `ESC [ 77 ; 4 u` and rejects both
+ * unshifted forms, so every Alt+Shift chord would be dead on those terminals.
+ * An uppercase letter cannot be typed without Shift, so restoring the bit adds
+ * nothing the keyboard did not already carry. Anything else passes through. */
+export function normalizeShiftedMeta(data) {
+    if (data.length === 2 && data[0] === '\x1b' && /[A-Z]/.test(data[1])) {
+        return `\x1b[${data.charCodeAt(1)};4u`;
+    }
+    const altOnlyCsiU = /^\x1b\[(\d+);3u$/.exec(data);
+    if (altOnlyCsiU !== null) {
+        const codepoint = Number(altOnlyCsiU[1]);
+        if (codepoint >= 0x41 && codepoint <= 0x5a)
+            return `\x1b[${codepoint};4u`;
+    }
+    return data;
+}
 export function matchesPiTuiInput(bindingSet, id, input, matchesKey) {
     return bindingSet.gestures(id).some((gesture) => !gesture.includes(' > ') && matchesKey(input, gesture));
 }

package/dist/core/memory/doc-link-grammar.js

@@ -1,10 +1,6 @@
-// doc-link-grammar.ts — the single source of truth for the `[[canonical/name]]`
-// memory-document link grammar. Zero imports, pure string ops, browser-safe —
-// any surface that highlights, resolves, or lints doc links imports THIS module
-// rather than re-implementing the bracket scan or the name shape. It ships to
-// external consumers as `@north-light/crouter-api/doc-link-grammar`, so a
-// browser UI rendering a node's transcript scans with the same grammar crtrd
-// validates `/v1/memory/resolve` names with.
+// doc-link-grammar.ts — crouter's parser for `[[canonical/name]]` memory links.
+// Memory commands and the daemon's resolve endpoint share this module for the
+// bracket scan and canonical-name shape.
 //
 // A doc link is a durable cross-reference written INSIDE a memory document's
 // body, pointing at another memory document by its exact canonical name (the

package/dist/core/memory/inline-ref-guidance.js

@@ -9,7 +9,7 @@
 // returned string in a `{ role: 'custom', customType: 'crtr-memory-refs',
 // display: false, ... }` message and delivers it alongside the human turn.
 import { findRefTokens } from './inline-ref-grammar.js';
-const GUIDANCE_HEADER = 'The human explicitly referenced these memory documents. Before acting on the portion of their message that references each document, run the corresponding command and treat its returned content as authoritative context:';
+const GUIDANCE_HEADER = 'The user explicitly called out specific memories. Read the relevant mentioned memory files:';
 /**
  * Resolve every slash token in `text` against `names` (a
  * `buildRefInventory().names` set), collapse duplicates, and return one

package/dist/core/memory-resolver.d.ts

@@ -57,6 +57,12 @@ export interface MemoryResolutionOpts {
      *  matching-kind doc into a false not_found — resolution simply continues
      *  to the next source. See `effectiveDocKind` for the kind coercion. */
     kind?: string;
+    /** Also consult `.crouter/memory` stores discovered BELOW the mounted
+     *  project roots (bounded discovery — see nested-stores.ts). Opt-in for the
+     *  addressing surfaces (`memory read/list/find/lint/delete/origin`); OFF for
+     *  boot render, on-read resolvedDocs, the slash-command snapshot, and
+     *  persona resolution, which stay on the flat ancestor+profile stack. */
+    includeDescendants?: boolean;
 }
 /** Canonical, unambiguous identifier for a memory document: `<scope>/<name>`. */
 export declare function memoryDocId(doc: MemoryDoc): string;
@@ -98,7 +104,7 @@ export declare function listProjectMemoryDocs(startDir?: string, profileId?: str
  *  profile's memory (if any), then user, then builtin. Within each source,
  *  native docs are emitted before enabled-plugin docs, so native wins on the
  *  caller's first-wins dedup. */
-export declare function listAllMemoryDocs(scope?: MemoryScope, quiet?: boolean): MemoryDoc[];
+export declare function listAllMemoryDocs(scope?: MemoryScope, quiet?: boolean, includeDescendants?: boolean): MemoryDoc[];
 export interface MemoryDocSnapshot {
     /** Every document in default scope precedence order, loaded once. */
     docs: readonly MemoryDoc[];

package/dist/core/memory-resolver.js

@@ -10,6 +10,7 @@ import { pluginMemoryDir, projectScopeRoots, scopeMemoryDir } from './scope.js';
 import { effectiveDocKind, normalizeDocName, normalizeNameSegment, resolveDocName } from './substrate/schema.js';
 import { loadProfileManifest, profileMemoryDir } from './profiles/manifest.js';
 import { memoryDir as nodeMemoryDir } from './runtime/memory.js';
+import { descendantStoreRoots } from './nested-stores.js';
 /** Canonical, unambiguous identifier for a memory document: `<scope>/<name>`. */
 export function memoryDocId(doc) {
     return `${doc.scope}/${doc.name}`;
@@ -55,17 +56,29 @@ function scopesInPrecedence(target, scope) {
  *  join — and drops out silently (never throws the resolver) when the
  *  selected profile id no longer resolves to a manifest. User and builtin
  *  remain singleton scopes after that. */
-function memorySourcesInPrecedence(target, scope) {
+function memorySourcesInPrecedence(target, scope, includeDescendants = false) {
     const out = [];
     for (const s of scopesInPrecedence(target, scope)) {
         if (s === 'project') {
-            for (const root of projectScopeRoots(target.cwd, target.profileId)) {
+            const roots = projectScopeRoots(target.cwd, target.profileId);
+            for (const root of roots) {
                 out.push({
                     scope: 'project',
                     memoryDir: join(root, 'memory'),
                     plugins: listInstalledPluginsInRoot('project', root).filter((p) => p.enabled),
                 });
             }
+            // Descendant stores rank after every ancestor source (and before
+            // profile): an ancestor doc always beats a nested doc on a name tie.
+            if (includeDescendants) {
+                for (const root of descendantStoreRoots(roots)) {
+                    out.push({
+                        scope: 'project',
+                        memoryDir: join(root, 'memory'),
+                        plugins: listInstalledPluginsInRoot('project', root).filter((p) => p.enabled),
+                    });
+                }
+            }
         }
         else if (s === 'profile') {
             const profileId = target.profileId ?? '';
@@ -234,8 +247,8 @@ export function listProjectMemoryDocs(startDir = process.cwd(), profileId = sele
  *  profile's memory (if any), then user, then builtin. Within each source,
  *  native docs are emitted before enabled-plugin docs, so native wins on the
  *  caller's first-wins dedup. */
-export function listAllMemoryDocs(scope, quiet = false) {
-    return memorySourcesInPrecedence(ambientTarget(), scope).flatMap((source) => sourceMemoryDocs(source, quiet));
+export function listAllMemoryDocs(scope, quiet = false, includeDescendants = false) {
+    return memorySourcesInPrecedence(ambientTarget(), scope, includeDescendants).flatMap((source) => sourceMemoryDocs(source, quiet));
 }
 /** Find the direct child of `dir` — a `.md` file (matched on name minus
  *  extension) or a directory — whose NORMALIZED display name equals
@@ -359,10 +372,10 @@ function formatLeafAmbiguous(leaf, matches) {
     const ids = matches.map(memoryDocId).join(', ');
     return `ambiguous memory document: ${leaf} matches multiple documents: ${ids}`;
 }
-function loadMemorySources(target, scope) {
+function loadMemorySources(target, scope, includeDescendants = false) {
     // Quiet: a targeted read must not spew other docs' frontmatter warnings
     // before its own result (esp. a not_found) — corpus health is `lint`'s job.
-    return memorySourcesInPrecedence(target, scope).map((source) => ({
+    return memorySourcesInPrecedence(target, scope, includeDescendants).map((source) => ({
         source,
         docs: sourceMemoryDocs(source, true),
     }));
@@ -465,5 +478,5 @@ export function resolveMemoryDocForTarget(rawName, target, opts = {}) {
         throw usage(`scope conflict: identifier "${rawName}" uses scope "${parsed.scope}" but --scope is "${opts.scope}"`);
     }
     const effectiveScope = opts.scope ?? parsed.scope;
-    return resolveMemoryDocFromSources(rawName, opts, loadMemorySources(target, effectiveScope));
+    return resolveMemoryDocFromSources(rawName, opts, loadMemorySources(target, effectiveScope, opts.includeDescendants ?? false));
 }

package/dist/core/nested-stores.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Every `.crouter` store root strictly BELOW the given ancestor roots' owning
+ * dirs, in owner order then discovery order. Takes the `projectScopeRoots()`
+ * entries themselves (`.crouter` dir paths) and derives owner dirs internally.
+ *
+ * Any discovered root whose realpath matches an INPUT root is excluded here,
+ * inside the function: a profile can manage both `/a` and `/a/b`, making
+ * `/a/b/.crouter` simultaneously an ancestor root and a descendant of `/a` —
+ * excluding centrally gives the resolver and lint the identical call with no
+ * duplicated dedupe logic.
+ */
+export declare function descendantStoreRoots(ancestorRoots: string[]): string[];