@north-light/crouter 0.3.181 → 0.3.183

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

package/dist/core/nested-stores.js

@@ -0,0 +1,146 @@
+// nested-stores.ts — bounded discovery of `.crouter/memory` stores BELOW the
+// mounted ancestor roots, so `crtr memory list/read/find/lint/delete/origin`
+// can address a nested store's docs by name. Deliberately opt-in and never on
+// the boot/render path: the boot catalog, workspace-open render, on-read
+// resolvedDocs, slash-command snapshot, and persona resolution all stay on the
+// flat ancestor+profile stack (on-read delivery finds nested stores through
+// its own read-file walk instead).
+//
+// Two discovery modes per owner dir, both under one shared 500 ms budget:
+//   • Git root — `git ls-files` over tracked+untracked (respecting .gitignore),
+//     so junk dirs and ignored trees cost nothing and embedded repos are
+//     auto-excluded (ls-files does not descend into submodules).
+//   • Non-git root — a DFS with junk-dir skips, a depth cap, and an
+//     embedded-repo stop.
+import { readdirSync } from 'node:fs';
+import { dirname, join, sep } from 'node:path';
+import { CRTR_DIR_NAME } from '../types.js';
+import { pathExists, realpathOrSelf } from './fs-utils.js';
+import { gitSync } from './git.js';
+import { warn } from './output.js';
+/** Mirrors on-read.ts's junk set, plus `.venv`. */
+const JUNK_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', '.cache', '.yalc', '.venv']);
+const MAX_DEPTH = 6;
+const TIME_BUDGET_MS = 500;
+/** Cache keyed by the sorted joined root list. A `memory read` of an INDEX
+ *  resolves every `[[link]]` through the resolver, each of which rebuilds its
+ *  sources — without this cache that is one git spawn + walk per link. CLI
+ *  processes are short-lived, so staleness is a non-issue; the daemon never
+ *  opts in. */
+const cache = new Map();
+/**
+ * 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 function descendantStoreRoots(ancestorRoots) {
+    const key = [...ancestorRoots].sort().join('\n');
+    const cached = cache.get(key);
+    if (cached !== undefined)
+        return cached;
+    const ancestorReal = new Set(ancestorRoots.map((root) => realpathOrSelf(root)));
+    const owners = [];
+    const ownerSeen = new Set();
+    for (const root of ancestorRoots) {
+        const owner = dirname(root);
+        const real = realpathOrSelf(owner);
+        if (ownerSeen.has(real))
+            continue;
+        ownerSeen.add(real);
+        owners.push(owner);
+    }
+    const deadline = Date.now() + TIME_BUDGET_MS;
+    let warned = false;
+    const tripBudget = (owner) => {
+        if (warned)
+            return;
+        warned = true;
+        warn(`memory: nested-store discovery under ${owner} exceeded its ${TIME_BUDGET_MS}ms budget — nested stores may be missing from this listing; register deep stores explicitly (add their dirs to the selected profile's projects)`);
+    };
+    const found = [];
+    const foundSeen = new Set();
+    const add = (storeRoot) => {
+        const real = realpathOrSelf(storeRoot);
+        if (foundSeen.has(real) || ancestorReal.has(real))
+            return;
+        foundSeen.add(real);
+        found.push(storeRoot);
+    };
+    for (const owner of owners) {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0) {
+            tripBudget(owner);
+            break;
+        }
+        if (pathExists(join(owner, '.git'))) {
+            collectGitStores(owner, add, remaining, () => tripBudget(owner));
+        }
+        else {
+            collectWalkStores(owner, add, deadline, () => tripBudget(owner));
+        }
+    }
+    cache.set(key, found);
+    return found;
+}
+// Git owner: enumerate via `git ls-files -co --exclude-standard` so
+// .gitignore is respected for free. Git's default pathspec fnmatch lets `*`
+// cross slashes, and the leading `*/` excludes the owner's own root store
+// (nothing precedes its `.crouter`).
+function collectGitStores(owner, add, timeoutMs, trip) {
+    const marker = `/${CRTR_DIR_NAME}/memory/`;
+    const res = gitSync(['-C', owner, 'ls-files', '-z', '-co', '--exclude-standard', '--', `*/${CRTR_DIR_NAME}/memory/*`], undefined, undefined, { timeoutMs });
+    if (res.timedOut === true) {
+        trip();
+        return;
+    }
+    if (res.status !== 0)
+        return;
+    for (const rel of res.stdout.split('\0')) {
+        if (rel === '')
+            continue;
+        const idx = rel.indexOf(marker);
+        if (idx <= 0)
+            continue;
+        add(join(owner, rel.slice(0, idx).split('/').join(sep), CRTR_DIR_NAME));
+    }
+}
+/** Non-git owner: DFS with junk skips, a depth cap, and a stop at any embedded
+ *  `.git` dir (an embedded repo is its own world — register it explicitly). */
+function collectWalkStores(owner, add, deadline, trip) {
+    const stack = [{ dir: owner, depth: 0 }];
+    while (stack.length > 0) {
+        if (Date.now() > deadline) {
+            trip();
+            return;
+        }
+        const { dir, depth } = stack.pop();
+        if (dir !== owner) {
+            if (pathExists(join(dir, '.git')))
+                continue;
+            if (pathExists(join(dir, CRTR_DIR_NAME, 'memory')))
+                add(join(dir, CRTR_DIR_NAME));
+        }
+        if (depth >= MAX_DEPTH)
+            continue;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            if (JUNK_DIRS.has(entry.name) || entry.name === CRTR_DIR_NAME)
+                continue;
+            stack.push({ dir: join(dir, entry.name), depth: depth + 1 });
+        }
+    }
+}

package/dist/core/preview-registry.js

@@ -62,9 +62,11 @@ export const TOOL_ICON = {
     write: String.fromCodePoint(0xf0c7),
     edit: String.fromCodePoint(0xf044),
 };
-/** One glyph per root subtree (`crtr <family> ...`) — the fallback for any
+/** One glyph per root family (`crtr <family> ...`) — the fallback for any
  *  leaf not listed in LEAF_ICON_CP below. Codepoints are Nerd Font
- *  private-use-area icons chosen per family concept (see command-icons.md). */
+ *  private-use-area icons chosen per family concept (see command-icons.md).
+ *  Families a plugin mounts (capture, device, search) are listed here too: this
+ *  registry is keyed by command path, not by who owns the command. */
 const FAMILY_ICON_CP = {
     canvas: 0xf0e8,
     capture: 0xf03d,

package/dist/core/runtime/bearings.d.ts

@@ -81,4 +81,4 @@ export declare function buildForkBearings(nodeId: string): string;
  *      AGENTS.md/CLAUDE.md injection stays suppressed (`noContextFiles` in
  *      broker.ts); `crtr sys sync project-guidance` imports that guidance into
  *      the directory's `.crouter/memory/INDEX.md` front door. */
-export declare function buildContextBearings(nodeId: string): string;
+export declare function buildContextBearings(nodeId: string, seen?: Set<string>): string;

package/dist/core/runtime/bearings.js

@@ -404,7 +404,7 @@ export function buildForkBearings(nodeId) {
  *      AGENTS.md/CLAUDE.md injection stays suppressed (`noContextFiles` in
  *      broker.ts); `crtr sys sync project-guidance` imports that guidance into
  *      the directory's `.crouter/memory/INDEX.md` front door. */
-export function buildContextBearings(nodeId) {
+export function buildContextBearings(nodeId, seen) {
     const node = getNode(nodeId);
     const bearings = ['<crtr-bearings>', buildIdentityAssertion(nodeId)];
     const map = buildGraphMap(nodeId);
@@ -425,7 +425,7 @@ export function buildContextBearings(nodeId) {
     // The consultable catalog rides BESIDE the bearings, not inside them.
     const knowledge = renderKnowledgeBlock(nodeId);
     // A workspace mount is the initial read of its root (`applies-to: "."`).
-    const workspaceContext = renderWorkspaceOpenDocs(nodeId);
+    const workspaceContext = renderWorkspaceOpenDocs(nodeId, seen);
     // Hidden applet/situation-origin ambient context (see situational-context.ts)
     // — a SIBLING block, never nested under <crtr-bearings>, and never routed
     // through the visible chat/digest path. '' when nothing was ever set.

package/dist/core/runtime/broker/fault-retry.js

@@ -53,6 +53,15 @@ export class FaultRetry {
         generation.stagedWatchdogAbort = false;
         generation.stagedOverflowFailure = null;
         const settledSession = generation.session;
+        // A failed daemon retry settles here with the episode's fault marker still
+        // present (a successful provider round-trip would have cleared it). Carry
+        // the episode forward — original anchor, start time, and attempt count — so
+        // each retry rewinds to the same fork point instead of stacking recovery
+        // prompts, and so backoff/exhaustion actually accumulate.
+        const prior = readFault(this.deps.nodeId);
+        const episode = this.isActiveAutoFault(prior) && prior.link === 'pi→provider'
+            ? { since: prior.since, anchorEntryId: prior.anchorEntryId, attempt: prior.retry.attempt }
+            : null;
         const messages = Array.isArray(agentEnd?.messages) ? agentEnd.messages : [];
         const last = [...messages].reverse().find((message) => typeof message === 'object' && message !== null && message.role === 'assistant');
         if (overflowFailure !== null) {
@@ -65,9 +74,11 @@ export class FaultRetry {
         }
         if (watchdogAbort && last?.stopReason === 'aborted') {
             recordFault(this.deps.nodeId, {
-                link: 'pi→provider', op: 'generation turn', kind: 'connection', retry: { disposition: 'auto', by: 'daemon' },
+                link: 'pi→provider', op: 'generation turn', kind: 'connection',
+                retry: { disposition: 'auto', by: 'daemon', ...(episode?.attempt !== undefined ? { attempt: episode.attempt } : {}) },
                 message: typeof last.errorMessage === 'string' ? last.errorMessage : 'engine error (no errorMessage recorded)',
-                anchorEntryId: settledSession.sessionManager.getLeafId?.() ?? undefined,
+                ...(episode !== null ? { since: episode.since } : {}),
+                anchorEntryId: episode?.anchorEntryId ?? settledSession.sessionManager.getLeafId?.() ?? undefined,
             });
             return;
         }
@@ -84,9 +95,17 @@ export class FaultRetry {
             retry: uncompactedOverflow
                 ? { disposition: 'fatal' }
                 : classified.disposition === 'auto'
-                    ? { disposition: 'auto', by: 'daemon', ...(coolingDeadline !== undefined ? { nextAt: new Date(coolingDeadline).toISOString() } : {}) }
+                    ? {
+                        disposition: 'auto', by: 'daemon',
+                        ...(coolingDeadline !== undefined ? { nextAt: new Date(coolingDeadline).toISOString() } : {}),
+                        ...(episode?.attempt !== undefined ? { attempt: episode.attempt } : {}),
+                    }
                     : { disposition: classified.disposition },
-            message: raw, anchorEntryId: settledSession.sessionManager.getLeafId?.() ?? undefined,
+            message: raw,
+            ...(!uncompactedOverflow && classified.disposition === 'auto' && episode !== null ? { since: episode.since } : {}),
+            anchorEntryId: !uncompactedOverflow && classified.disposition === 'auto' && episode?.anchorEntryId !== undefined
+                ? episode.anchorEntryId
+                : settledSession.sessionManager.getLeafId?.() ?? undefined,
         });
     }
     schedule() {

package/dist/core/runtime/broker/inbox.d.ts

@@ -18,5 +18,9 @@ export declare function readBrokerCursor(nodeId: string): BrokerInboxEntryId | u
 export declare function readBrokerInboxSince(nodeId: string, cursor?: string): BrokerInboxEntry[];
 export declare function readBrokerInboxRange(nodeId: string, after: string | undefined, through: string): BrokerInboxEntry[];
 export declare function readBrokerCanceledEntryIds(nodeId: string): Set<BrokerInboxEntryId>;
+/** The node id a canonical report ref points at, or undefined when the ref is
+ *  absent, absolute, or not a report path. Callers use it to tell whether the
+ *  report-node projection they hold can still resolve the ref. */
+export declare function reportRefNodeId(ref: string | undefined): string | undefined;
 /** Render the existing inbox digest wording with daemon-projected report existence. */
 export declare function coalesceBrokerInbox(entries: readonly BrokerInboxEntry[], reportNodes: ReadonlyMap<string, BrokerReportNodeDTO>): string;

package/dist/core/runtime/broker/inbox.js

@@ -101,16 +101,25 @@ function clipBody(body) {
     }
     return { text: text.trimEnd(), clipped };
 }
-function inlineReport(entry, reportNodes) {
-    if (entry.ref === undefined || entry.ref.startsWith('/'))
-        return null;
-    const separator = entry.ref.indexOf(':');
+/** The node id a canonical report ref points at, or undefined when the ref is
+ *  absent, absolute, or not a report path. Callers use it to tell whether the
+ *  report-node projection they hold can still resolve the ref. */
+export function reportRefNodeId(ref) {
+    if (ref === undefined || ref.startsWith('/'))
+        return undefined;
+    const separator = ref.indexOf(':');
     if (separator <= 0)
+        return undefined;
+    const relpath = ref.slice(separator + 1);
+    if (!relpath.startsWith('reports/') || relpath.includes('..') || relpath.startsWith('/'))
+        return undefined;
+    return ref.slice(0, separator);
+}
+function inlineReport(entry, reportNodes) {
+    const nodeId = reportRefNodeId(entry.ref);
+    if (nodeId === undefined || !reportNodes.has(nodeId))
         return null;
-    const nodeId = entry.ref.slice(0, separator);
-    const relpath = entry.ref.slice(separator + 1);
-    if (!reportNodes.has(nodeId) || !relpath.startsWith('reports/') || relpath.includes('..') || relpath.startsWith('/'))
-        return null;
+    const relpath = entry.ref.slice(entry.ref.indexOf(':') + 1);
     const path = `${nodeDir(nodeId)}/${relpath}`;
     try {
         const body = readFileSync(path, 'utf8');

package/dist/core/runtime/broker-extension-render.d.ts

@@ -3,7 +3,7 @@ export declare function editorLabelForBrokerNode(node: BrokerExtensionNodeDTO):
 /** Same environment-only project context rendered at normal boot, without a
  * canvas import. */
 export declare function buildProjectContextBlockForBroker(cwd: string): string;
-export declare function buildContextBearingsFromState(state: BrokerExtensionStateDTO, projectContext: string, situational?: string): string;
+export declare function buildContextBearingsFromState(state: BrokerExtensionStateDTO, projectContext: string, situational?: string, seen?: Set<string>): string;
 export declare function buildForkBearingsFromState(state: BrokerExtensionStateDTO, situational?: string): string;
 export declare function renderPreferencesFromState(state: BrokerExtensionStateDTO): string;
 /** A canonical report ref has already been validated by crtrd in state. The

package/dist/core/runtime/broker-extension-render.js

@@ -120,7 +120,7 @@ function reviewNote(node) {
         return '';
     return `You exist for one human review of \`${review.target_file}\`. The inherited conversation belongs to the origin node, not you — carry only the context needed for this review. The person's visible transcript begins at the boundary marker above; everything earlier is context they cannot see.`;
 }
-export function buildContextBearingsFromState(state, projectContext, situational = '') {
+export function buildContextBearingsFromState(state, projectContext, situational = '', seen) {
     const { node } = state;
     const bearings = ['<crtr-bearings>', identity(state)];
     const map = graphMap(state);
@@ -137,7 +137,7 @@ export function buildContextBearingsFromState(state, projectContext, situational
         bearings.push('', `Because you persist across refresh cycles, your context directory (${contextDir(node.node_id)}) is also where a future cycle of you resumes the work — keep the working notes and decisions a refreshed you would need there, alongside the docs you share with the nodes you spawn.`);
     bearings.push('</crtr-bearings>');
     const knowledge = renderKnowledgeForSubject(state.subject, node.node_id);
-    const workspace = renderWorkspaceOpenDocsForSubject(state.subject, node.cwd, node.profile_id);
+    const workspace = renderWorkspaceOpenDocsForSubject(state.subject, node.cwd, node.profile_id, seen);
     return [bearings.join('\n'), knowledge, workspace, situational, projectContext].filter((part) => part !== '').join('\n');
 }
 export function buildForkBearingsFromState(state, situational = '') {

package/dist/core/runtime/broker-protocol.d.ts

@@ -47,7 +47,7 @@ export interface BrokerSnapshot {
         title: string | undefined;
     };
     /** Broker-owned summaries keyed by the first tool-call id in each group.
-     * Structured objects with bullets, nodesSpawned, and filesDeleted.
+     * Structured objects with bullets and filesDeleted.
      * Optional so snapshots from an older live runtime remain readable. */
     toolGroupSummaries?: Record<string, ToolGroupSummary>;
     /** The broker-selected normal activity label for the current turn. Optional so