@north-light/crouter 0.3.182 → 0.3.184

package/dist/commands/sys/setup-wizard.js

@@ -1,5 +1,5 @@
 // The `crtr sys setup` first-run installer: log in a provider, then install the
-// companion packages, system dependencies and API key a fresh machine needs.
+// companion packages and system dependencies a fresh machine needs.
 //
 // Ongoing configuration — models, keybindings, display preferences, panes,
 // broker limits, updates — lives in settings-shell.ts. Both hosts share the
@@ -7,14 +7,13 @@
 // confirmed install, that one is a persistent editor that saves as you go.
 import { matchesKey, truncateToWidth, visibleWidth, } from "@earendil-works/pi-tui";
 import { formatGesture, matchesPiTuiInput, } from "../../core/keybindings/index.js";
-import { buildSetupInitialState, executeSetupSubmission, formatSetupExecutionSummary, packagePlanAction, reconcileInboxFrontDoor, renderSetupStaticInstructions, resolveExaKeyPath, } from "./setup-core.js";
+import { buildSetupInitialState, executeSetupSubmission, formatSetupExecutionSummary, packagePlanAction, reconcileInboxFrontDoor, renderSetupStaticInstructions, } from "./setup-core.js";
 import { runSetupSettingsProcess } from "./setup-settings-runner.js";
 import { DependenciesPanel } from "./panels/dependencies-panel.js";
-import { KeysPanel } from "./panels/keys-panel.js";
 import { PAGE_CHROME_ROWS, pageFrame, theme, } from "./panels/panel.js";
 import { PluginsPanel } from "./panels/plugins-panel.js";
 import { ProviderPanel } from "./panels/provider-panel.js";
-const STEPS = ["Providers", "Plugins", "Dependencies", "Exa key"];
+const STEPS = ["Providers", "Plugins", "Dependencies"];
 /** The host owns step navigation, focus, submission and composition. Each step
  *  owns its own mutable UI state. */
 export class SetupWizard {
@@ -23,7 +22,6 @@ export class SetupWizard {
     providers;
     plugins;
     dependencies;
-    keys;
     step = 0;
     confirming = false;
     cachedWidth;
@@ -42,13 +40,9 @@ export class SetupWizard {
         this.providers.onChange = invalidate;
         this.plugins = new PluginsPanel(manifest, installedPackageIds, invalidate);
         this.dependencies = new DependenciesPanel(systemPlans, invalidate);
-        this.keys = new KeysPanel();
-        this.keys.onSubmit = () => this.finalize();
-        this.keys.onCancel = () => this.cancel();
     }
     set focused(value) {
         this._focused = value;
-        this.syncFocus();
     }
     get focused() {
         return this._focused;
@@ -58,9 +52,6 @@ export class SetupWizard {
         this.cachedHeight = undefined;
         this.cachedLines = undefined;
     }
-    syncFocus() {
-        this.keys.focused = this._focused && this.step === 3 && !this.confirming;
-    }
     matches(id, data) {
         return matchesPiTuiInput(this.bindings, id, data, (input, gesture) => matchesKey(input, gesture));
     }
@@ -85,7 +76,6 @@ export class SetupWizard {
     }
     setStep(next) {
         this.step = next;
-        this.syncFocus();
         this.invalidate();
     }
     moveStep(delta) {
@@ -93,7 +83,7 @@ export class SetupWizard {
     }
     /** Enter on a non-final step walks forward; on the last one it finishes. */
     advance() {
-        if (this.step === 3)
+        if (this.step === 2)
             this.finalize();
         else
             this.moveStep(1);
@@ -101,7 +91,6 @@ export class SetupWizard {
     cancel() {
         if (this.confirming) {
             this.confirming = false;
-            this.syncFocus();
             this.invalidate();
             return;
         }
@@ -109,7 +98,6 @@ export class SetupWizard {
     }
     dispose() {
         this.providers.dispose();
-        this.keys.focused = false;
     }
     hasPendingInstalls() {
         return (this.plugins.selected.some((entry) => !this.installedPackageIds.has(entry.id)) || this.dependencies.selected.length > 0);
@@ -119,8 +107,6 @@ export class SetupWizard {
             packages: [...this.plugins.selected],
             installedPackageIds: new Set(this.installedPackageIds),
             systemDeps: [...this.dependencies.selected],
-            exaKey: this.keys.value,
-            exaKeyPath: resolveExaKeyPath(),
         };
     }
     finalize() {
@@ -129,7 +115,6 @@ export class SetupWizard {
             return;
         }
         this.confirming = true;
-        this.syncFocus();
         this.invalidate();
     }
     currentPanel() {
@@ -137,20 +122,12 @@ export class SetupWizard {
             ? this.providers
             : this.step === 1
                 ? this.plugins
-                : this.step === 2
-                    ? this.dependencies
-                    : this.keys;
+                : this.dependencies;
     }
     handleInput(data) {
         const panel = this.currentPanel();
         const match = (id, input) => this.matches(id, input);
-        const nestedInput = (this.step === 0 && this.providers.isNestedFlowActive()) ||
-            (this.step === 3 &&
-                ((data.length === 1 && data.charCodeAt(0) >= 32) ||
-                    matchesKey(data, "left") ||
-                    matchesKey(data, "right") ||
-                    matchesKey(data, "up") ||
-                    matchesKey(data, "down")));
+        const nestedInput = this.step === 0 && this.providers.isNestedFlowActive();
         if (nestedInput) {
             if (panel.handleInput(data, match))
                 this.invalidate();
@@ -161,7 +138,6 @@ export class SetupWizard {
                 this.onSubmit?.(this.buildSubmission());
             else if (this.matches("crtr.setup.confirm.back", data)) {
                 this.confirming = false;
-                this.syncFocus();
                 this.invalidate();
             }
             return;
@@ -185,7 +161,7 @@ export class SetupWizard {
         if (this.matches("crtr.setup.advance", data))
             this.advance();
     }
-    /** `Providers › Plugins › Dependencies › Exa key`, active step lit, done
+    /** `Providers › Plugins › Dependencies`, active step lit, done
      *  steps checked — a first run should always show how much is left. */
     renderTrail(width) {
         const parts = STEPS.map((label, index) => {
@@ -214,10 +190,8 @@ export class SetupWizard {
                 : `${move} select \u00b7 a add \u00b7 p prefer \u00b7 r rename \u00b7 l re-login \u00b7 x remove \u00b7 ${this.label("crtr.setup.advance")} next`;
         else if (this.step === 1)
             left = `${move} move \u00b7 ${this.label("crtr.setup.toggle")} toggle \u00b7 ${this.label("crtr.setup.details")} details \u00b7 ${this.label("crtr.setup.advance")} next`;
-        else if (this.step === 2)
-            left = `${move} move \u00b7 ${this.label("crtr.setup.toggle")} toggle \u00b7 ${this.label("crtr.setup.advance")} next`;
         else
-            left = `paste EXA_API_KEY \u00b7 ${this.label("crtr.setup.advance")} finish`;
+            left = `${move} move \u00b7 ${this.label("crtr.setup.toggle")} toggle \u00b7 ${this.label("crtr.setup.advance")} finish`;
         const gap = width - visibleWidth(left) - visibleWidth(steps);
         return gap >= 2
             ? `${theme.fg("dim", left)}${" ".repeat(gap)}${theme.fg("dim", steps)}`
@@ -229,9 +203,7 @@ export class SetupWizard {
             truncateToWidth(theme.fg("warning", theme.bold("Confirm installs")), width),
             "",
         ];
-        if (submission.packages.length === 0 &&
-            submission.systemDeps.length === 0 &&
-            submission.exaKey === "")
+        if (submission.packages.length === 0 && submission.systemDeps.length === 0)
             return [
                 ...out,
                 truncateToWidth(theme.fg("success", `Nothing to install; ${this.label("crtr.setup.confirm.accept")} finish.`), width),
@@ -246,8 +218,6 @@ export class SetupWizard {
             for (const plan of submission.systemDeps)
                 out.push(truncateToWidth(`  \u2022 ${plan.tool} ${theme.fg("dim", "\u2192")} ${theme.fg("muted", plan.command ?? plan.hint)}`, width));
         }
-        if (submission.exaKey)
-            out.push(truncateToWidth(`${theme.fg("accent", "Exa key")} ${theme.fg("dim", "\u2192")} ${theme.fg("warning", `write ${submission.exaKeyPath}`)}`, width));
         return out;
     }
     render(width) {

package/dist/commands/sys/setup.js

@@ -11,19 +11,19 @@ import { defineLeaf } from '../../core/command.js';
 export const BROKER_LIMIT_OVERRIDE_PRECEDENCE = 'Valid CRTR_WARN_LIVE_BROKERS and CRTR_MAX_LIVE_BROKERS environment overrides take precedence over their corresponding configured limits.';
 export const sysSetupLeaf = defineLeaf({
     name: 'setup',
-    description: 'bootstrap a fresh machine — provider login, companion packages, system dependencies, Exa key',
+    description: 'bootstrap a fresh machine — provider login, companion packages, system dependencies',
     whenToUse: 'you are setting up crouter on a machine for the first time and need credentials and installs in place. Use sys settings to change configuration on an installed machine, and sys config set for scriptable edits.',
     help: {
         name: 'sys setup',
-        summary: 'run the first-run installer: provider login, companion packages, system dependencies, Exa key',
+        summary: 'run the first-run installer: provider login, companion packages, system dependencies',
         inputNote: 'No input parameters.',
         output: [],
         outputKind: 'object',
         effects: [
-            'Opens a four-step pi-tui installer. Step one logs in to a model provider (pi\'s real OAuth/API-key flow, same as in-app /login) so a fresh install has credentials before running any node.',
-            'The remaining steps collect companion package installs, system dependency installs, and an Exa API key, then confirm them all at once.',
-            'Runs the bundled pi CLI to install the selected companion packages, writes EXA_API_KEY to ~/.crouter/exa.key when provided, and prints a summary.',
-            'The companion-package list includes the official crtr marketplace and the plugins installed from it (currently `capture`), all checked by default and registered or installed into the user scope when left checked. Nothing else registers a marketplace, so an install that never runs setup fetches no catalog. An unreachable marketplace is reported as skipped rather than failing setup.',
+            'Opens a three-step pi-tui installer. Step one logs in to a model provider (pi\'s real OAuth/API-key flow, same as in-app /login) so a fresh install has credentials before running any node.',
+            'The remaining steps collect companion package installs and system dependency installs, then confirm them all at once.',
+            'Runs the bundled pi CLI to install the selected companion packages and prints a summary.',
+            'The companion-package list includes the official crtr marketplace and the plugins installed from it (currently `capture` and `search`), all checked by default and registered or installed into the user scope when left checked. Nothing else registers a marketplace, so an install that never runs setup fetches no catalog. An unreachable marketplace is reported as skipped rather than failing setup. Vendor credentials belong to the plugin that needs them, never to setup.',
             'On every invocation (best-effort, idempotent), refreshes crouter-owned tmux bindings and registers known nodes\' interaction roots so resolved tickets can call back into the asking node. The inbox popup toggle is a crouter-owned keybinding, editable on the keybindings tab.',
         ],
     },

package/dist/commands/sys/sync-project-guidance.js

@@ -1,8 +1,8 @@
 // `crtr sys sync project-guidance` — one-way migration of a project's own
 // CLAUDE.md/AGENTS.md/.claude/rules into that SAME directory's OWN
 // `.crouter/memory/`. Each project guide becomes the root INDEX front door;
-// rules retain their explicit path routes, or use the workspace-open `.` route
-// when they are pathless.
+// rules retain their explicit path routes, or use the `.` route (workspace
+// mount + any file read beneath the store's owning dir) when they are pathless.
 import { existsSync, readdirSync, statSync } from 'node:fs';
 import { basename, dirname, join, relative, resolve, sep } from 'node:path';
 import { defineLeaf } from '../../core/command.js';
@@ -97,11 +97,37 @@ function synthesizeShortForm(body) {
 }
 /** `.claude/rules` frontmatter `paths:` normalizes to a glob list — a single
  *  string, an array, or absent for a workspace-wide rule. */
+/** Split a rule's comma-separated `paths` string into globs, honoring brace
+ *  groups — `"lib/**\/*.{ts,tsx}, proxy.ts"` is two globs, and the comma inside
+ *  `{ts,tsx}` never splits. Authored rules use both the comma-joined string and
+ *  the YAML-list shape. */
+function splitTopLevelCommas(s) {
+    const out = [];
+    let depth = 0;
+    let cur = '';
+    for (const ch of s) {
+        if (ch === '{')
+            depth += 1;
+        else if (ch === '}')
+            depth = Math.max(0, depth - 1);
+        if (ch === ',' && depth === 0) {
+            out.push(cur);
+            cur = '';
+            continue;
+        }
+        cur += ch;
+    }
+    out.push(cur);
+    return out.map((g) => g.trim()).filter((g) => g !== '');
+}
 function normalizeRulePaths(v) {
     if (typeof v === 'string')
-        return v.trim() === '' ? [] : [v.trim()];
-    if (Array.isArray(v))
-        return v.filter((g) => typeof g === 'string' && g.trim() !== '');
+        return splitTopLevelCommas(v);
+    if (Array.isArray(v)) {
+        return v
+            .filter((g) => typeof g === 'string')
+            .flatMap(splitTopLevelCommas);
+    }
     return [];
 }
 /** The main repo root's directory name, found via `git rev-parse
@@ -195,7 +221,8 @@ function projectDocLabel(candidate) {
 /** AGENTS.md/CLAUDE.md → `<sourceDir>/.crouter/memory/INDEX.md`, the
  *  workspace front door. Its explicit project identity keeps sibling roots
  *  distinct; system none/file content plus `applies-to: "."` puts the wholly
- *  important guide in first-message context when cwd/profile mounts the store. */
+ *  important guide in first-message context when cwd/profile mounts the store,
+ *  and surfaces it on any file read beneath the store's owning dir. */
 function prepareAgentsCandidate(candidate) {
     const body = parseFrontmatterGeneric(readText(candidate.path)).body;
     const docLabel = projectDocLabel(candidate);
@@ -218,16 +245,23 @@ function prepareAgentsCandidate(candidate) {
 }
 /** `.claude/rules/<name>.md` → `<sourceDir>/.crouter/memory/<name>.md`. A
  *  `paths:` rule keeps its `applies-to` file globs at none/content; a pathless
- *  rule receives `applies-to: "."` and surfaces when the workspace opens. */
+ *  rule receives `applies-to: "."` and surfaces when the workspace opens or a
+ *  file beneath the store's owning dir is read. Like the INDEX docs, each rule
+ *  carries an explicit namespaced substrate name (`<root>/<subdir>/<leaf>`):
+ *  without it the resolver falls back to the store-relative leaf, and two
+ *  nested stores sharing a rule filename (e.g. apps/core and apps/gateway both
+ *  carrying `unit-tests.md`) collapse onto one bare name, shadowing one doc. */
 function prepareRuleCandidate(candidate) {
     const raw = readText(candidate.path);
     const parsed = parseFrontmatterGeneric(raw);
     const fm = parsed.data ?? {};
-    const name = normalizedName(basename(candidate.path));
+    const leaf = normalizedName(basename(candidate.path));
     const description = scalarString(fm['description']) ?? '';
     const dirLabel = projectDocLabel(candidate);
+    const name = normalizedName(`${dirLabel}/${leaf}`);
     const frontmatter = {
         kind: 'knowledge',
+        name,
         'when-and-why-to-read': description !== ''
             ? routeFromDescription(description, 'knowledge')
             : `When working under ${dirLabel}, this knowledge should be read because it is migrated project rule guidance.`,
@@ -240,7 +274,7 @@ function prepareRuleCandidate(candidate) {
     return {
         candidate,
         name,
-        target: memoryFilePath(join(candidate.sourceDir, CRTR_DIR_NAME, 'memory'), name),
+        target: memoryFilePath(join(candidate.sourceDir, CRTR_DIR_NAME, 'memory'), leaf),
         frontmatter,
         body: parsed.body,
     };
@@ -304,7 +338,7 @@ export const sysSyncProjectGuidanceLeaf = defineLeaf({
         ],
         outputKind: 'object',
         effects: [
-            "Copies each discovered CLAUDE.md/AGENTS.md into <dir>/.crouter/memory/INDEX.md with an explicit project name at system-prompt-visibility none, file-read-visibility content, and applies-to `.`. Copies each .claude/rules/*.md into <dir>/.crouter/memory/<name>.md at none/content, using the source paths as applies-to globs or `.` when no paths are declared. Originals are left untouched.",
+            "Copies each discovered CLAUDE.md/AGENTS.md into <dir>/.crouter/memory/INDEX.md with an explicit project name at system-prompt-visibility none, file-read-visibility content, and applies-to `.`. Copies each .claude/rules/*.md into <dir>/.crouter/memory/<name>.md at none/content, using the source paths as applies-to globs or `.` (workspace mount + reads beneath the owning dir) when no paths are declared. Originals are left untouched.",
             'Skips existing memory docs unless --overwrite is present.',
             'With --dry-run: read-only; writes nothing.',
         ],
@@ -320,8 +354,24 @@ export const sysSyncProjectGuidanceLeaf = defineLeaf({
                 if (docSeen.has(c.path))
                     continue;
                 docSeen.add(c.path);
-                const prepared = c.kind === 'agents' ? prepareAgentsCandidate(c) : prepareRuleCandidate(c);
-                results.push(convertProjectDoc(prepared, { dryRun, overwrite }));
+                // Isolate one malformed source file (e.g. invalid YAML in a rule's
+                // frontmatter) as its own skipped row — it must never abort the whole
+                // migration.
+                try {
+                    const prepared = c.kind === 'agents' ? prepareAgentsCandidate(c) : prepareRuleCandidate(c);
+                    results.push(convertProjectDoc(prepared, { dryRun, overwrite }));
+                }
+                catch (e) {
+                    const msg = (e instanceof Error ? e.message : String(e)).split('\n')[0];
+                    results.push({
+                        source: c.path,
+                        target: '',
+                        name: '',
+                        scope: 'project',
+                        status: 'skipped',
+                        reason: `unparseable source frontmatter: ${msg} — fix the source file and re-run`,
+                    });
+                }
             }
         }
         const imported = results.filter((r) => r.status === 'imported').length;

package/dist/core/__tests__/fault-classifier.test.js

@@ -43,6 +43,26 @@ test('flattened provider 5xx and API-error text classify as overloaded/auto (#15
         assert.equal(c.disposition, 'auto', `"${msg}" must be auto-retried`);
     }
 });
+// A gateway that refuses the request for SIZE cannot be retried: the daemon
+// re-posts the same conversation and fails identically. One oversized image in
+// a tool result wedged a live applet conversation this way — the rejection
+// arrived as 5xx prose, classified 'overloaded', and looped on injected
+// recovery messages until the chat surfaced CROUTER_PROVIDER_UNAVAILABLE.
+test('a request-size rejection is fatal, even wrapped in 5xx prose', () => {
+    for (const msg of [
+        '413 Payload Too Large',
+        'PayloadTooLargeError: request entity too large',
+        'Request body exceeds the 5 MB limit',
+        '500 Internal Server Error: request entity too large',
+    ]) {
+        const c = classify('pi→provider', msg);
+        assert.equal(c.kind, 'protocol', `"${msg}" must classify as protocol, not overloaded`);
+        assert.equal(c.disposition, 'fatal', `"${msg}" must never arm an automatic retry`);
+    }
+    const http = classify('pi→provider', { status: 413, statusText: 'Payload Too Large' });
+    assert.equal(http.kind, 'protocol');
+    assert.equal(http.disposition, 'fatal');
+});
 test('interrupted WebSocket text, including close 1000 and flattened error/interrupt (#302, #258), classifies as connection/auto', () => {
     for (const msg of ['WebSocket closed 1000', 'WebSocket stream closed before response.completed', 'WebSocket error', 'WebSocket connection interrupted']) {
         const c = classify('pi→provider', msg);

package/dist/core/__tests__/nested-store-discovery.test.d.ts

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

package/dist/core/__tests__/nested-store-discovery.test.js

@@ -0,0 +1,89 @@
+// Bounded descendant-store discovery (nested-stores.ts) and its resolver
+// opt-in: git owners enumerate via ls-files (tracked + untracked, .gitignore
+// respected, the input root excluded), non-git owners walk with a depth cap,
+// and `resolveMemoryDocForTarget` sees a nested doc only when the caller opts
+// into descendants.
+//
+// Run: node --import tsx/esm --test src/core/__tests__/nested-store-discovery.test.ts
+import { test, before, beforeEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { CrtrError } from '../errors.js';
+import { realpathOrSelf } from '../fs-utils.js';
+import { gitSync } from '../git.js';
+import { closeDb } from '../canvas/db.js';
+import { resetScopeCache } from '../scope.js';
+import { descendantStoreRoots } from '../nested-stores.js';
+import { resolveMemoryDocForTarget } from '../memory-resolver.js';
+let fakeHome;
+let prevHomeEnv;
+const cleanups = [];
+before(() => {
+    prevHomeEnv = process.env['HOME'];
+});
+beforeEach(() => {
+    closeDb();
+    resetScopeCache();
+    fakeHome = mkdtempSync(join(tmpdir(), 'crtr-descend-home-'));
+    process.env['HOME'] = fakeHome;
+    cleanups.push(fakeHome);
+});
+after(() => {
+    closeDb();
+    resetScopeCache();
+    for (const dir of cleanups)
+        rmSync(dir, { recursive: true, force: true });
+    if (prevHomeEnv === undefined)
+        delete process.env['HOME'];
+    else
+        process.env['HOME'] = prevHomeEnv;
+});
+function makeStore(dir) {
+    const memoryDir = join(dir, '.crouter', 'memory');
+    mkdirSync(memoryDir, { recursive: true });
+    writeFileSync(join(memoryDir, 'INDEX.md'), '# store\n');
+}
+test('git owner: tracked and untracked stores found, gitignored and input-root stores excluded', () => {
+    // Distinct tmp root per case: descendantStoreRoots caches by root list.
+    const owner = realpathOrSelf(mkdtempSync(join(tmpdir(), 'crtr-descend-git-')));
+    cleanups.push(owner);
+    assert.equal(gitSync(['-C', owner, 'init'], undefined).status, 0, 'git init succeeds');
+    makeStore(owner); // the input root itself — must be excluded
+    makeStore(join(owner, 'pkg-tracked'));
+    makeStore(join(owner, 'pkg-untracked'));
+    makeStore(join(owner, 'ignored'));
+    writeFileSync(join(owner, '.gitignore'), 'ignored/\n');
+    assert.equal(gitSync(['-C', owner, 'add', 'pkg-tracked'], undefined).status, 0, 'git add succeeds (ls-files needs no commit or identity)');
+    const found = descendantStoreRoots([join(owner, '.crouter')]).map(realpathOrSelf);
+    assert.deepEqual([...found].sort(), [join(owner, 'pkg-tracked', '.crouter'), join(owner, 'pkg-untracked', '.crouter')].sort(), 'tracked + untracked stores, nothing gitignored, never the input root');
+});
+test('non-git owner: the walk finds a store at the depth cap and stops below it', () => {
+    const owner = realpathOrSelf(mkdtempSync(join(tmpdir(), 'crtr-descend-walk-')));
+    cleanups.push(owner);
+    const atCap = join(owner, 'd1', 'd2', 'd3', 'd4', 'd5', 'd6'); // depth 6
+    makeStore(atCap);
+    const belowCap = join(atCap, 'd7'); // depth 7
+    makeStore(belowCap);
+    const found = descendantStoreRoots([join(owner, '.crouter')]).map(realpathOrSelf);
+    assert.deepEqual(found, [join(atCap, '.crouter')], 'depth 6 found; depth 7 is past the cap');
+});
+test('resolveMemoryDocForTarget resolves a nested doc only with includeDescendants', () => {
+    const proj = join(fakeHome, 'proj');
+    mkdirSync(join(proj, '.crouter', 'memory'), { recursive: true }); // project scope engages
+    const nestedMemory = join(proj, 'sub', '.crouter', 'memory');
+    mkdirSync(nestedMemory, { recursive: true });
+    writeFileSync(join(nestedMemory, 'guide.md'), '---\nkind: knowledge\n' +
+        'name: nested-guide\n' +
+        'when-and-why-to-read: When working in sub, this knowledge should be read because it carries the subsystem constraints.\n' +
+        'system-prompt-visibility: none\n' +
+        'file-read-visibility: none\n---\n' +
+        'NESTED GUIDE BODY\n');
+    const target = { cwd: proj, profileId: null, nodeId: null };
+    assert.throws(() => resolveMemoryDocForTarget('nested-guide', target, {}), (e) => e instanceof CrtrError && e.code === 'not_found', 'without the opt-in the flat ancestor stack does not see the nested store');
+    const doc = resolveMemoryDocForTarget('nested-guide', target, { includeDescendants: true });
+    assert.equal(doc.name, 'nested-guide', 'resolves by explicit frontmatter name');
+    assert.equal(doc.scope, 'project');
+    assert.ok(doc.body.includes('NESTED GUIDE BODY'));
+});

package/dist/core/__tests__/on-read-nested-store.test.d.ts

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

package/dist/core/__tests__/on-read-nested-store.test.js

@@ -0,0 +1,117 @@
+// A `.crouter/memory` store nested BELOW a mounted project root is delivered
+// by the read path, not by boot: its `.`-routed docs surface on the first read
+// beneath the store's owning dir, deduplicated against the workspace-open
+// render through the shared transcript dedup set. The `.` route stays fenced
+// to project-store docs — a hand-authored `.` in a user-scope doc must never
+// match a read.
+//
+// Run: node --import tsx/esm --test src/core/__tests__/on-read-nested-store.test.ts
+import { test, before, beforeEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { closeDb } from '../canvas/db.js';
+import { resetScopeCache } from '../scope.js';
+import { spawnNode } from '../runtime/nodes.js';
+import { renderOnReadDocs, renderWorkspaceOpenDocs } from '../substrate/on-read-node.js';
+import { clearSessionCache } from '../substrate/session-cache.js';
+const ROOT_BODY = 'ROOT WORKSPACE FRONT DOOR BODY';
+const NESTED_BODY = 'NESTED PKG FRONT DOOR BODY';
+let canvasHome;
+let fakeHome;
+let prevHomeEnv;
+before(() => {
+    prevHomeEnv = process.env['HOME'];
+});
+beforeEach(() => {
+    closeDb();
+    resetScopeCache();
+    clearSessionCache();
+    fakeHome = mkdtempSync(join(tmpdir(), 'crtr-nested-home-'));
+    process.env['HOME'] = fakeHome;
+    canvasHome = mkdtempSync(join(tmpdir(), 'crtr-nested-canvas-'));
+    process.env['CRTR_HOME'] = canvasHome;
+});
+after(() => {
+    closeDb();
+    resetScopeCache();
+    rmSync(canvasHome, { recursive: true, force: true });
+    rmSync(fakeHome, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+    if (prevHomeEnv === undefined)
+        delete process.env['HOME'];
+    else
+        process.env['HOME'] = prevHomeEnv;
+});
+/** A work tree with a root front door and a nested store front door, both
+ *  routed `.`. Returns the work dir. */
+function makeWorkTree() {
+    const work = join(fakeHome, 'work');
+    const rootStore = join(work, '.crouter', 'memory');
+    mkdirSync(rootStore, { recursive: true });
+    writeFileSync(join(rootStore, 'INDEX.md'), '---\nkind: knowledge\n' +
+        'when-and-why-to-read: When working in this workspace, this knowledge should be read because it is the operating guide.\n' +
+        'file-read-visibility: content\n' +
+        'applies-to: "."\n---\n' +
+        `${ROOT_BODY}\n`);
+    const nestedStore = join(work, 'pkg', '.crouter', 'memory');
+    mkdirSync(nestedStore, { recursive: true });
+    writeFileSync(join(nestedStore, 'INDEX.md'), '---\nkind: knowledge\n' +
+        'when-and-why-to-read: When working in pkg, this knowledge should be read because it carries the package constraints.\n' +
+        'file-read-visibility: content\n' +
+        'applies-to: "."\n---\n' +
+        `${NESTED_BODY}\n`);
+    return work;
+}
+test('a nested store front door surfaces on a read beneath its owning dir, not outside it', () => {
+    const work = makeWorkTree();
+    const node = spawnNode({ kind: 'general', cwd: work, parent: null }).node_id;
+    const inside = join(work, 'pkg', 'lib', 'file.ts');
+    mkdirSync(join(work, 'pkg', 'lib'), { recursive: true });
+    writeFileSync(inside, 'export const x = 1;\n');
+    const rendered = renderOnReadDocs(node, inside, new Set());
+    assert.ok(rendered.includes(NESTED_BODY), `read beneath pkg surfaces the nested front door; got: ${rendered}`);
+    const outside = join(work, 'docs', 'notes.ts');
+    mkdirSync(join(work, 'docs'), { recursive: true });
+    writeFileSync(outside, 'export const y = 2;\n');
+    const renderedOutside = renderOnReadDocs(node, outside, new Set());
+    assert.ok(!renderedOutside.includes(NESTED_BODY), `read outside pkg must not surface the nested front door; got: ${renderedOutside}`);
+});
+test('workspace-open and on-read share one dedup set: root front door once, nested store on first read beneath it', () => {
+    const work = makeWorkTree();
+    const node = spawnNode({ kind: 'general', cwd: work, parent: null }).node_id;
+    const seen = new Set();
+    const opened = renderWorkspaceOpenDocs(node, seen);
+    assert.ok(opened.includes(ROOT_BODY), 'workspace open delivers the mounted root front door');
+    assert.ok(!opened.includes(NESTED_BODY), 'boot stays flat: the nested store is not in the mounted stack');
+    const readFile = join(work, 'pkg', 'lib', 'file.ts');
+    mkdirSync(join(work, 'pkg', 'lib'), { recursive: true });
+    writeFileSync(readFile, 'export const x = 1;\n');
+    const onRead = renderOnReadDocs(node, readFile, seen);
+    assert.ok(onRead.includes(NESTED_BODY), 'the nested front door delivers on the first read beneath it');
+    assert.ok(!onRead.includes(ROOT_BODY), 'the root front door already delivered at workspace open — never twice');
+});
+test('a hand-authored `.` route in a user-scope doc never matches a read', () => {
+    const userStore = join(fakeHome, '.crouter', 'memory');
+    mkdirSync(userStore, { recursive: true });
+    writeFileSync(join(userStore, 'control.md'), '---\nkind: knowledge\n' +
+        'when-and-why-to-read: When reading markdown, this knowledge should be read because it is the corpus-loaded control fixture.\n' +
+        'file-read-visibility: content\n' +
+        'applies-to: "**/*.md"\n---\n' +
+        'USER CONTROL BODY\n');
+    writeFileSync(join(userStore, 'dot-routed.md'), '---\nkind: knowledge\n' +
+        'when-and-why-to-read: When anything, this knowledge should be read because it must never fire.\n' +
+        'file-read-visibility: content\n' +
+        'applies-to: "."\n---\n' +
+        'USER DOT BODY MUST NOT FIRE\n');
+    const work = join(fakeHome, 'work');
+    mkdirSync(work, { recursive: true });
+    const node = spawnNode({ kind: 'general', cwd: work, parent: null }).node_id;
+    const readFile = join(fakeHome, 'notes', 'thing.md');
+    mkdirSync(join(fakeHome, 'notes'), { recursive: true });
+    writeFileSync(readFile, '# a note\n');
+    const rendered = renderOnReadDocs(node, readFile, new Set());
+    assert.ok(rendered.includes('USER CONTROL BODY'), 'the glob-routed user doc proves the user store is in the corpus');
+    assert.ok(!rendered.includes('USER DOT BODY MUST NOT FIRE'), `the \`.\` route is project-store only — a user doc's owning root is ~; got: ${rendered}`);
+});

package/dist/core/__tests__/plugin-link-symlinked-scope-root.test.d.ts

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

package/dist/core/__tests__/plugin-link-symlinked-scope-root.test.js

@@ -0,0 +1,38 @@
+// Run with: node --conditions=crtr-src --import tsx/esm --test src/core/__tests__/plugin-link-symlinked-scope-root.test.ts
+//
+// Regression for the silent half of a local/marketplace plugin install: the
+// scope root is reached through a symlinked ancestor (the macOS /tmp →
+// /private/tmp case), so a relative link target computed from the lexical
+// directory counts `..` hops up the wrong chain. symlinkSync accepts a
+// dangling target, so `pkg plugin install` reported success and registered
+// enabled=true while the next invocation resolved zero plugins.
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { linkOrCopy } from '../fs-utils.js';
+import { listInstalledPluginsInRoot } from '../resolver.js';
+describe('plugin link through a symlinked scope-root ancestor', () => {
+    test('the installed plugin resolves on the next invocation', () => {
+        const base = mkdtempSync(join(tmpdir(), 'crtr-plugin-link-'));
+        try {
+            // Source plugin package, outside the scope root.
+            const source = join(base, 'source', 'search');
+            mkdirSync(join(source, '.crouter-plugin'), { recursive: true });
+            writeFileSync(join(source, '.crouter-plugin', 'plugin.json'), JSON.stringify({ name: 'search', version: '0.1.0' }));
+            // Scope root addressed through a symlinked ancestor: `home` is a link,
+            // so the plugins directory's physical parent chain differs from its
+            // lexical one.
+            mkdirSync(join(base, 'physical', 'home'), { recursive: true });
+            symlinkSync(join('physical', 'home'), join(base, 'home'), 'dir');
+            const scopeRootPath = join(base, 'home', '.crouter');
+            mkdirSync(join(scopeRootPath, 'plugins'), { recursive: true });
+            linkOrCopy(source, join(scopeRootPath, 'plugins', 'search'));
+            assert.deepEqual(listInstalledPluginsInRoot('user', scopeRootPath).map((p) => p.name), ['search']);
+        }
+        finally {
+            rmSync(base, { recursive: true, force: true });
+        }
+    });
+});

package/dist/core/__tests__/serial/tmux-surface.test.js

@@ -196,11 +196,14 @@ test('tmux installer remaps owned pairs and preserves occupied user bindings', (
         assert.equal(remapped.ok, true, JSON.stringify(remapped.diagnostics));
         assert.equal(tmuxBinding(socket, 'root', 'M-c'), null);
         assert.equal(tmuxBinding(socket, 'root', 'M-]'), null);
-        assert.equal(tmuxBinding(socket, 'root', 'M-F'), null);
-        assert.equal(tmuxBinding(socket, 'root', 'M-S-f'), null);
-        const foldTools = tmuxBinding(socket, 'root', 'M-S-F') ?? '';
-        assert.match(foldTools, /fold-tools/);
-        assert.doesNotMatch(foldTools, /#\{pane_id\}/);
+        // One chord, every name tmux can derive for it: the terminal's byte encoding
+        // changes with the focused pane's extended-key mode, and tmux does not
+        // normalize across them, so all three must carry the action.
+        for (const key of ['M-S-F', 'M-F', 'M-S-f']) {
+            const foldTools = tmuxBinding(socket, 'root', key) ?? '';
+            assert.match(foldTools, /fold-tools/, `${key} should run fold-tools`);
+            assert.doesNotMatch(foldTools, /#\{pane_id\}/);
+        }
         const menu = tmuxBinding(socket, 'root', 'M-S-Z') ?? '';
         assert.match(menu, /canvas graph/);
         assert.match(menu, /Z/);