@north-light/crouter 0.3.182 → 0.3.184

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

package/dist/core/runtime/deliver-live.js

@@ -21,6 +21,7 @@ import { getNode } from '../canvas/index.js';
 import { oneShotControllerRequest } from './broker-request.js';
 import { isBrokerLive } from './model-swap.js';
 import { buildContextBearings, CONTEXT_INTRO_CUSTOM_TYPE } from './bearings.js';
+import { loadInjectedDocs, saveInjectedDocs } from '../substrate/injected-store.js';
 /** Deliver `message` into `nodeId`'s live session. Resolves without doing
  *  anything when the node has no live broker. Rejects when a live broker cannot
  *  be reached or refuses the frame — the caller decides what that means (for a
@@ -55,9 +56,18 @@ export async function deliverCustomMessageLive(nodeId, message) {
  *  guard matches on, so a LATER revive of this node sees its own bearings
  *  already on the branch and does not inject a second copy. */
 export async function deliverBearingsLive(nodeId) {
+    // This runs in the DAEMON while the spare's pi process is already alive, so
+    // the disk file — not any in-memory set — is the dedup medium: load the
+    // node's persisted set, grow it through the workspace-open render, and
+    // persist it after successful delivery. The pi process's on-read hook merges
+    // the on-disk set before each render, so docs delivered here never
+    // re-deliver on a later read. Plain load/save (not the process-shared
+    // cache): the daemon is long-lived and serves many nodes.
+    const seen = loadInjectedDocs(nodeId);
     await deliverCustomMessageLive(nodeId, {
         customType: CONTEXT_INTRO_CUSTOM_TYPE,
-        content: buildContextBearings(nodeId),
+        content: buildContextBearings(nodeId, seen),
         details: { nodeId },
     });
+    saveInjectedDocs(nodeId, seen);
 }

package/dist/core/runtime/fault.js

@@ -19,7 +19,7 @@ function faultPriority(fault) {
         return 2;
     return 1;
 }
-const faultLinks = ['pi→provider', 'viewer↔broker', 'relay↔broker', 'viewer↔crtrd', 'cli→exa', 'daemon→node', 'crtr→pi'];
+const faultLinks = ['pi→provider', 'viewer↔broker', 'relay↔broker', 'viewer↔crtrd', 'daemon→node', 'crtr→pi'];
 const faultKinds = ['rate-limit', 'overloaded', 'connection', 'auth', 'protocol', 'context-overflow', 'other', 'wedged', 'model-not-found'];
 function parseFault(raw) {
     try {

package/dist/core/runtime/tmux-bindings.js

@@ -161,23 +161,40 @@ function normalizedStrokeParts(stroke) {
     return { key: parts.pop(), modifiers: parts };
 }
 function tmuxKey(stroke) {
+    return tmuxKeyNames(stroke)[0];
+}
+/** Every tmux key name one physical chord can arrive as, most specific first.
+ *
+ *  tmux derives the name from the bytes the terminal sent, and a terminal sends
+ *  different bytes for the same chord depending on whether extended keys are
+ *  active — which changes per pane, since the pane's application turns them on.
+ *  tmux does not normalize across those encodings, so a chord bound under one
+ *  name is simply dead under the others. Verified against tmux 3.7b by writing
+ *  raw bytes to an attached client; for Alt+Shift+F:
+ *
+ *    ESC F           (legacy meta prefix)                -> `M-F`
+ *    ESC [70;4u  / ESC [27;4;70~   (shifted keysym)      -> `M-S-F`
+ *    ESC [102;4u / ESC [27;4;102~  (base keysym)         -> `M-S-f`
+ *
+ *  Shift alone never survives as a modifier — every encoding of Shift+G lands
+ *  on `G` — so only chords that pair Shift with Ctrl or Alt carry aliases. */
+function tmuxKeyNames(stroke) {
     let { key, modifiers: modifierParts } = normalizedStrokeParts(stroke);
     const modifiers = new Set(modifierParts);
-    if (modifiers.has('shift') && key.length === 1 && /[a-z]/.test(key)) {
-        // tmux names a shifted printable with its uppercase character even when an
-        // extended-key terminal also preserves Shift as a modifier: Alt+Shift+F is
-        // `M-S-F`. Shift by itself needs only the uppercase character (`F`).
-        key = key.toUpperCase();
-        if (!modifiers.has('ctrl') && !modifiers.has('alt'))
-            modifiers.delete('shift');
-    }
-    key = TMUX_NAMED_KEYS[key] ?? key;
-    const prefix = [
+    const name = (character, shift) => [
         modifiers.has('ctrl') ? 'C-' : '',
         modifiers.has('alt') ? 'M-' : '',
-        modifiers.has('shift') ? 'S-' : '',
+        shift ? 'S-' : '',
+        TMUX_NAMED_KEYS[character] ?? character,
     ].join('');
-    return `${prefix}${key}`;
+    if (modifiers.has('shift') && key.length === 1 && /[a-z]/.test(key)) {
+        const shifted = key.toUpperCase();
+        // Shift-only: tmux always collapses it into the uppercase character.
+        if (!modifiers.has('ctrl') && !modifiers.has('alt'))
+            return [name(shifted, false)];
+        return [name(shifted, true), name(shifted, false), name(key, true)];
+    }
+    return [name(key, modifiers.has('shift'))];
 }
 function menuSelector(stroke) {
     const { key, modifiers } = normalizedStrokeParts(stroke);
@@ -386,7 +403,7 @@ export function occupiedTmuxRootGestures(gestures) {
         const parsed = parseTmuxBinding(line);
         return parsed?.table === ROOT_TABLE ? [parsed.key] : [];
     }));
-    return gestures.filter((gesture) => !gesture.includes(' > ') && occupied.has(tmuxKey(gesture)));
+    return gestures.filter((gesture) => !gesture.includes(' > ') && tmuxKeyNames(gesture).some((key) => occupied.has(key)));
 }
 function isInstalledPair(value) {
     return typeof value === 'object' && value !== null
@@ -547,9 +564,10 @@ function reconcileTmuxBindings(bindingSnapshot, passthroughSnapshot = []) {
         for (const gesture of bindings.gestures(bindingId)) {
             if (gesture.includes(' > '))
                 continue;
-            const key = tmuxKey(gesture);
-            if (!desiredWrappers.has(key))
-                desiredWrappers.set(key, { bindingId, gesture });
+            for (const key of tmuxKeyNames(gesture)) {
+                if (!desiredWrappers.has(key))
+                    desiredWrappers.set(key, { bindingId, gesture });
+            }
         }
     }
     // Restore every wrapper crouter still owns before the ordinary binding sweep.
@@ -610,7 +628,8 @@ function reconcileTmuxBindings(bindingSnapshot, passthroughSnapshot = []) {
     const menuActions = resolvedMenuActions(bindings);
     const menuCommand = buildMenuArgs(' crtr ', menuItems(bindings, menuActions));
     for (const gesture of bindings.gestures('crtr.tmux.menu.open')) {
-        install(ROOT_TABLE, tmuxKey(gesture), menuCommand, 'crtr.tmux.menu.open', gesture);
+        for (const key of tmuxKeyNames(gesture))
+            install(ROOT_TABLE, key, menuCommand, 'crtr.tmux.menu.open', gesture);
     }
     for (const definition of BINDING_CATALOG) {
         if (definition.pair?.field !== 'menu')
@@ -625,12 +644,15 @@ function reconcileTmuxBindings(bindingSnapshot, passthroughSnapshot = []) {
         if (command === null)
             throw new Error(`no direct tmux action for paired menu binding ${menuId}`);
         for (const gesture of bindings.gestures(globalId)) {
-            install(ROOT_TABLE, tmuxKey(gesture), command.argv, globalId, gesture);
+            for (const key of tmuxKeyNames(gesture))
+                install(ROOT_TABLE, key, command.argv, globalId, gesture);
         }
     }
     for (const id of ['crtr.tmux.node.next', 'crtr.tmux.node.previous', 'crtr.tmux.inbox.toggle']) {
-        for (const gesture of bindings.gestures(id))
-            install(ROOT_TABLE, tmuxKey(gesture), actionCommand(id), id, gesture);
+        for (const gesture of bindings.gestures(id)) {
+            for (const key of tmuxKeyNames(gesture))
+                install(ROOT_TABLE, key, actionCommand(id), id, gesture);
+        }
     }
     // Wrap only occupied roots. Unoccupied gestures already reach the pane and do
     // not need crouter ownership. Re-read the installed line as the fingerprint;

package/dist/core/runtime/tool-group-summary.js

@@ -49,20 +49,16 @@ const SUMMARY_SYSTEM_PROMPT = 'Create a structured recap of this coding-agent to
     'Omit inbox receipt, delivery, and queueing; node-response and report bookkeeping; help lookups; status checks; and summary-generation activity. ' +
     'A node response may support a substantive outcome, but its arrival or resummarization is never itself an outcome. ' +
     'If no meaningful outcome remains after those omissions, submit the single bullet "No meaningful changes." ' +
-    'Count nodes created, and separately count distinct files removed from disk, only when the supplied tool arguments or results evidence them; otherwise use zero, even when the corresponding mechanics are omitted from bullets. ' +
+    'Count distinct files removed from disk only when the supplied tool arguments or results evidence them; otherwise use zero, even when the corresponding mechanics are omitted from bullets. ' +
     'A deleted file is one that no longer exists after the segment, never a file that was merely edited or overwritten, and a recursive or wildcard removal of an unknown number of files counts as one. ' +
     'Do not invent success when a result shows failure. ' +
-    'Call submit_summary exactly once with bullets, nodesSpawned, and filesDeleted, then stop.';
+    'Call submit_summary exactly once with bullets and filesDeleted, then stop.';
 const SUBMIT_SUMMARY_SCHEMA = Type.Object({
     bullets: Type.Array(Type.String({
         minLength: 1,
         maxLength: 120,
         description: 'A very short, plain-English outcome without bullet markers, identifiers, or operational bookkeeping.',
     }), { minItems: 1, maxItems: 5 }),
-    nodesSpawned: Type.Integer({
-        minimum: 0,
-        description: 'Count of nodes created during the supplied segment, or zero when none are evidenced.',
-    }),
     filesDeleted: Type.Integer({
         minimum: 0,
         description: 'Count of distinct files removed from disk during the supplied segment, or zero when none are evidenced.',

package/dist/core/substrate/injected-store.d.ts

@@ -1,3 +1,9 @@
+/** The process-shared dedup set for a node: loaded from disk once, then the
+ *  SAME Set instance on every call, so all hooks in this pi process grow and
+ *  consult one set. Daemon-side deliveries (a warm-spare claim) write the disk
+ *  file from another process; consumers that must see those merge the plain
+ *  `loadInjectedDocs` result in before rendering. */
+export declare function sharedInjectedDocs(nodeId: string): Set<string>;
 /** Rehydrate a node's on-read dedup set from disk. Returns an empty set when the
  *  file is absent, unreadable, or malformed (a fresh transcript, or a node that
  *  has not yet surfaced any on-read doc). */

package/dist/core/substrate/injected-store.js

@@ -19,6 +19,24 @@
 // never a crash — a dedup miss must never break a read or a revive.
 import { readFileSync, writeFileSync, rmSync } from 'node:fs';
 import { injectedDocsPath } from '../canvas/paths.js';
+/** Per-process cache behind `sharedInjectedDocs`: one Set instance per node,
+ *  shared by every extension in the pi process (context-intro's workspace-open
+ *  render and doc-substrate's on-read hook), so a doc delivered by one hook is
+ *  already in the set the other dedups against. */
+const cache = new Map();
+/** The process-shared dedup set for a node: loaded from disk once, then the
+ *  SAME Set instance on every call, so all hooks in this pi process grow and
+ *  consult one set. Daemon-side deliveries (a warm-spare claim) write the disk
+ *  file from another process; consumers that must see those merge the plain
+ *  `loadInjectedDocs` result in before rendering. */
+export function sharedInjectedDocs(nodeId) {
+    let seen = cache.get(nodeId);
+    if (seen === undefined) {
+        seen = loadInjectedDocs(nodeId);
+        cache.set(nodeId, seen);
+    }
+    return seen;
+}
 /** Rehydrate a node's on-read dedup set from disk. Returns an empty set when the
  *  file is absent, unreadable, or malformed (a fresh transcript, or a node that
  *  has not yet surfaced any on-read doc). */
@@ -46,6 +64,7 @@ export function saveInjectedDocs(nodeId, seen) {
 /** Drop a node's persisted dedup set. Called by the launch paths that start a
  *  FRESH transcript, so the new conversation surfaces docs from scratch. */
 export function clearInjectedDocs(nodeId) {
+    cache.delete(nodeId);
     try {
         rmSync(injectedDocsPath(nodeId), { force: true });
     }

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

@@ -3,5 +3,7 @@
 export declare function renderOnReadDocs(nodeId: string, readFilePath: string, seen?: Set<string>): string;
 /** Surface workspace-wide docs during first-message assembly, using the node's
  *  recorded cwd and selected profile. `.` is a reserved applies-to target
- *  meaning “when this project store is mounted by cwd/profile”. */
-export declare function renderWorkspaceOpenDocs(nodeId: string): string;
+ *  meaning “when this project store is mounted by cwd/profile” (and, on the
+ *  read event, “a file under the store's owning dir was read”). `seen` is the
+ *  transcript-scoped dedup set shared with the on-read hook. */
+export declare function renderWorkspaceOpenDocs(nodeId: string, seen?: Set<string>): string;

package/dist/core/substrate/on-read-node.js

@@ -22,14 +22,16 @@ export function renderOnReadDocs(nodeId, readFilePath, seen = new Set()) {
 }
 /** Surface workspace-wide docs during first-message assembly, using the node's
  *  recorded cwd and selected profile. `.` is a reserved applies-to target
- *  meaning “when this project store is mounted by cwd/profile”. */
-export function renderWorkspaceOpenDocs(nodeId) {
+ *  meaning “when this project store is mounted by cwd/profile” (and, on the
+ *  read event, “a file under the store's owning dir was read”). `seen` is the
+ *  transcript-scoped dedup set shared with the on-read hook. */
+export function renderWorkspaceOpenDocs(nodeId, seen = new Set()) {
     try {
         const subject = assembleNodeSubject(nodeId);
         const node = getNode(nodeId);
         if (subject === null || node === null)
             return '';
-        return renderWorkspaceOpenDocsForSubject(subject, node.cwd, node.profile_id ?? null);
+        return renderWorkspaceOpenDocsForSubject(subject, node.cwd, node.profile_id ?? null, seen);
     }
     catch {
         return '';

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

@@ -3,5 +3,7 @@ import type { NodeConfigSubject } from './subject-fields.js';
  * daemon snapshot subject. */
 export declare function renderOnReadDocsForSubject(subject: NodeConfigSubject, readFilePath: string, seen?: Set<string>): string;
 /** Workspace boot docs using the snapshot's cwd/profile instead of a canvas
- * lookup. */
-export declare function renderWorkspaceOpenDocsForSubject(subject: NodeConfigSubject, cwd: string, profileId: string | null): string;
+ * lookup. `seen` is the transcript-scoped dedup set shared with the on-read
+ * hook, so a front door delivered here never re-delivers on a later read
+ * beneath its store. */
+export declare function renderWorkspaceOpenDocsForSubject(subject: NodeConfigSubject, cwd: string, profileId: string | null, seen?: Set<string>): string;

package/dist/core/substrate/on-read.js

@@ -12,10 +12,16 @@
 //     visible substrate doc. Project stores encountered between that file and
 //     the filesystem root join the resolved cwd/profile corpus, so a nested
 //     workspace can contribute guidance exactly when a file beneath it is read.
+//     On this event the reserved `applies-to: "."` target means "the read file
+//     is under the doc's store's owning directory" — a nested store's front
+//     door surfaces on the first read beneath it, delivery driven purely by
+//     filesystem truth.
 //   • Opening a workspace evaluates the reserved `applies-to: "."` target for
 //     every project store mounted by the cwd and selected profile. This happens
 //     while the first-message bearings are assembled, so workspace-wide context
 //     arrives before the task rather than waiting for an arbitrary first file.
+//     Both hooks share one transcript-scoped dedup set, so a doc delivered at
+//     workspace open never re-delivers on a later matching read.
 //
 // `read-when` remains an additional OR trigger over a read markdown file's own
 // frontmatter. It does not replace `applies-to`: every non-none file-read rung
@@ -25,7 +31,7 @@
 // is the whole on-read model, so directory INDEX ceilings remain a boot-catalog
 // concern and do not cap a deliberately matched document.
 import { homedir } from 'node:os';
-import { basename, dirname, matchesGlob, parse, relative, sep } from 'node:path';
+import { basename, dirname, isAbsolute, matchesGlob, parse, relative, sep } from 'node:path';
 import { CRTR_DIR_NAME } from '../../types.js';
 import { pathExists, readText, walkFiles } from '../fs-utils.js';
 import { parseFrontmatterGeneric } from '../frontmatter.js';
@@ -175,6 +181,18 @@ function globMatches(glob, absReadFile, owningRoot) {
         }
     });
 }
+/** True when the read file sits beneath the doc's store's owning directory —
+ *  the read-event meaning of the reserved `applies-to: "."` target. Callers
+ *  additionally guard on `doc.scope === 'project'`: a profile store's path
+ *  computes an owning root of `~`, and user/builtin/node docs likewise have no
+ *  project-owning dir, so `.` outside a project store must never match. */
+function underOwningRoot(doc, absReadFile) {
+    const root = owningRootOf(doc);
+    if (root === null)
+        return false;
+    const rel = relative(realpathOrSelf(root), absReadFile);
+    return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
+}
 function readFileFrontmatter(absReadFile) {
     if (!/\.(md|mdx|markdown)$/i.test(absReadFile))
         return {};
@@ -186,7 +204,9 @@ function readFileFrontmatter(absReadFile) {
     }
 }
 function matchesReadEvent(doc, absReadFile, readFrontmatter) {
-    const pathMatch = doc.appliesTo?.some((glob) => globMatches(glob, absReadFile, owningRootOf(doc))) === true;
+    const pathMatch = doc.appliesTo?.some((glob) => glob.trim() === '.'
+        ? doc.scope === 'project' && underOwningRoot(doc, absReadFile)
+        : globMatches(glob, absReadFile, owningRootOf(doc))) === true;
     const frontmatterMatch = doc.readWhen !== undefined &&
         Object.keys(readFrontmatter).length > 0 &&
         evalCondition(doc.readWhen, readFrontmatter);
@@ -245,8 +265,10 @@ export function renderOnReadDocsForSubject(subject, readFilePath, seen = new Set
     return renderCandidates(subject, docs, seen);
 }
 /** Workspace boot docs using the snapshot's cwd/profile instead of a canvas
- * lookup. */
-export function renderWorkspaceOpenDocsForSubject(subject, cwd, profileId) {
+ * lookup. `seen` is the transcript-scoped dedup set shared with the on-read
+ * hook, so a front door delivered here never re-delivers on a later read
+ * beneath its store. */
+export function renderWorkspaceOpenDocsForSubject(subject, cwd, profileId, seen = new Set()) {
     let docs;
     try {
         docs = listProjectMemoryDocs(cwd, profileId)
@@ -264,5 +286,5 @@ export function renderWorkspaceOpenDocsForSubject(subject, cwd, profileId) {
         const depth = aRoot.split(sep).filter(Boolean).length - bRoot.split(sep).filter(Boolean).length;
         return depth || aRoot.localeCompare(bRoot) || a.path.localeCompare(b.path);
     });
-    return renderCandidates(subject, docs, new Set());
+    return renderCandidates(subject, docs, seen);
 }

package/dist/daemon/__tests__/subtree-filter-freshness.test.d.ts

@@ -0,0 +1 @@
+export {};