@north-light/crouter 0.3.207 → 0.3.209

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 `.` route (workspace
-// mount + any file read beneath the store's owning dir) when they are pathless.
+// `.crouter/memory/`. Each project guide becomes the workspace front door
+// (workspace-open + ./** read entries); rules keep their explicit path routes
+// as read entries, or take the front-door pair 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';
@@ -218,9 +218,30 @@ function projectDocLabel(candidate) {
         .replace(/^\.$/, '');
     return relDir === '' ? rootLabel : normalizedName(`${rootLabel}/${relDir}`);
 }
+/** The surfaces pair every workspace front door carries: whole-doc delivery
+ *  when cwd/profile mounts the store, plus on any file read beneath the
+ *  store's owning dir. */
+function frontDoorSurfaces() {
+    return [
+        { on: 'workspace-open', at: 'content' },
+        { on: 'read', match: './**', at: 'content' },
+    ];
+}
+/** `./`-anchor a rule glob that could only match repo-relatively: any glob
+ *  containing `/` that starts with neither `/`, `**`, nor `./`. Mirrors the
+ *  surfaces migration's anchoring rule — this leaf MINTS new read globs, so it
+ *  must anchor them the same way or the routes it writes silently never fire. */
+function anchorReadGlob(g) {
+    const t = g.trim();
+    if (!t.includes('/'))
+        return t;
+    if (t.startsWith('/') || t.startsWith('**') || t.startsWith('./'))
+        return t;
+    return `./${t}`;
+}
 /** 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
+ *  distinct; the workspace-open + ./** read entry pair puts the wholly
  *  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) {
@@ -231,9 +252,7 @@ function prepareAgentsCandidate(candidate) {
         name: docLabel,
         'when-and-why-to-read': `When working in ${docLabel}, this knowledge should be read because it is the project's operating guide.`,
         'short-form': synthesizeShortForm(body),
-        'system-prompt-visibility': 'none',
-        'file-read-visibility': 'content',
-        'applies-to': ['.'],
+        surfaces: frontDoorSurfaces(),
     };
     return {
         candidate,
@@ -244,9 +263,10 @@ 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 or a
- *  file beneath the store's owning dir is read. Like the INDEX docs, each rule
+ *  `paths:` rule keeps its file globs as a `content` read entry (`./`-anchored
+ *  when repo-relative); a pathless rule takes the front-door pair 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
@@ -266,11 +286,11 @@ function prepareRuleCandidate(candidate) {
             ? routeFromDescription(description, 'knowledge')
             : `When working under ${dirLabel}, this knowledge should be read because it is migrated project rule guidance.`,
         'short-form': description !== '' ? description.replace(/\s+/g, ' ').trim() : synthesizeShortForm(parsed.body),
-        'system-prompt-visibility': 'none',
-        'file-read-visibility': 'content',
     };
-    const globs = normalizeRulePaths(fm['paths']);
-    frontmatter['applies-to'] = globs.length > 0 ? globs : ['.'];
+    const globs = normalizeRulePaths(fm['paths']).map(anchorReadGlob);
+    frontmatter['surfaces'] = globs.length > 0
+        ? [{ on: 'read', match: globs.length === 1 ? globs[0] : globs, at: 'content' }]
+        : frontDoorSurfaces();
     return {
         candidate,
         name,
@@ -321,7 +341,7 @@ function renderSummary(results) {
 export const sysSyncProjectGuidanceLeaf = defineLeaf({
     name: 'project-guidance',
     description: "migrate CLAUDE.md/AGENTS.md/.claude/rules into that directory's own crouter memory docs",
-    whenToUse: "migrating per-project CLAUDE.md/AGENTS.md/.claude/rules into the crouter memory-doc model: one-way copy into that same directory's OWN .crouter/memory/. The project guide becomes its root INDEX front door; path-scoped rules keep their globs and pathless rules open with the workspace. Never exports memory docs back to these source files.",
+    whenToUse: "migrating per-project CLAUDE.md/AGENTS.md/.claude/rules into the crouter memory-doc model: one-way copy into that same directory's OWN .crouter/memory/. The project guide becomes its workspace front door; path-scoped rules keep their globs as read entries and pathless rules open with the workspace. Never exports memory docs back to these source files.",
     help: {
         name: 'sys sync project-guidance',
         summary: "one-way migration: CLAUDE.md/AGENTS.md/.claude/rules → that dir's own crouter memory docs",
@@ -338,7 +358,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 `.` (workspace mount + reads beneath the owning dir) 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 and the workspace front-door surfaces pair ({on: workspace-open, at: content} + {on: read, match: './**', at: content}). Copies each .claude/rules/*.md into <dir>/.crouter/memory/<name>.md with a content read entry over the source paths (‘./’-anchored when repo-relative), or the same front-door pair when no paths are declared. Originals are left untouched.",
             'Skips existing memory docs unless --overwrite is present.',
             'With --dry-run: read-only; writes nothing.',
         ],

package/dist/commands/sys/sync-skills.js

@@ -167,6 +167,12 @@ function convertPrepared(prepared, opts) {
     delete frontmatter.description;
     delete frontmatter.type;
     delete frontmatter.keywords;
+    // Retired visibility-axis fields a stale source may still carry — they must
+    // never pass through into a substrate doc.
+    delete frontmatter['system-prompt-visibility'];
+    delete frontmatter['file-read-visibility'];
+    delete frontmatter['applies-to'];
+    delete frontmatter['read-when'];
     frontmatter.kind = prepared.kind;
     if (typeof frontmatter['when-and-why-to-read'] !== 'string' || frontmatter['when-and-why-to-read'].trim() === '') {
         frontmatter['when-and-why-to-read'] = routeFromDescription(description, prepared.kind);
@@ -174,10 +180,8 @@ function convertPrepared(prepared, opts) {
     if (typeof frontmatter['short-form'] !== 'string' || frontmatter['short-form'].trim() === '') {
         frontmatter['short-form'] = description.replace(/\s+/g, ' ').trim();
     }
-    if (typeof frontmatter['system-prompt-visibility'] !== 'string')
-        frontmatter['system-prompt-visibility'] = 'preview';
-    if (typeof frontmatter['file-read-visibility'] !== 'string')
-        frontmatter['file-read-visibility'] = 'none';
+    if (!Array.isArray(frontmatter['surfaces']))
+        frontmatter['surfaces'] = [{ on: 'boot', at: 'preview' }];
     if (!opts.dryRun)
         writeText(prepared.target, serializeMemoryDoc(frontmatter, prepared.parsed.body));
     return {

package/dist/commands/sys.js

@@ -11,19 +11,20 @@ import { supportBranch } from './sys/support.js';
 import { sysSyspromptLeaf } from './sys/sysprompt.js';
 import { promptReviewLeaf } from './sys/prompt-review.js';
 import { sysSyncBranch } from './sys/sync.js';
+import { sysMigrateLeaf } from './sys/migrate.js';
 import { sysUpdateLeaf, sysVersionLeaf } from './sys/update.js';
 export function registerSys() {
     return defineBranch({
         name: 'sys',
         rootEntry: {
             concept: 'crtr configuration, diagnostics, and self-management',
-            desc: 'settings, config, setup, doctor, sysprompt, prompt-review, sync, update, version, feedback, logs, support, daemon',
+            desc: 'settings, config, setup, doctor, sysprompt, prompt-review, sync, migrate, update, version, feedback, logs, support, daemon',
             useWhen: 'managing the crtr installation, inspecting diagnostics, or operating the crtrd supervisor process',
         },
         help: {
             name: 'sys',
             summary: 'crtr system configuration, settings, diagnostics, and self-management',
         },
-        children: [sysSettingsLeaf, configBranch, sysSetupLeaf, sysDoctorLeaf, sysSyspromptLeaf, promptReviewLeaf, sysFeedbackLeaf, sysLogsLeaf, supportBranch, sysUpdateLeaf, sysVersionLeaf, sysSyncBranch, daemonBranch],
+        children: [sysSettingsLeaf, configBranch, sysSetupLeaf, sysDoctorLeaf, sysSyspromptLeaf, promptReviewLeaf, sysFeedbackLeaf, sysLogsLeaf, supportBranch, sysUpdateLeaf, sysVersionLeaf, sysMigrateLeaf, sysSyncBranch, daemonBranch],
     });
 }

package/dist/core/__tests__/canvas-inbox-watcher.test.js

@@ -106,7 +106,7 @@ test('coalesce renders one inbox card whose entries inline short report bodies a
     const card = parseCard({ role: 'user', content: digest });
     assert.notEqual(card, null);
     assert.equal(card.kind, 'inbox');
-    assert.deepEqual({ ...card.facts }, { senders: '1', updates: '1' });
+    assert.deepEqual({ ...card.facts }, {});
     assert.equal(card.senders.length, 1);
     assert.equal(card.senders[0].id, 'child');
     // The label is NOT reprinted above the body it duplicates.

package/dist/core/__tests__/helpers/broker-clients.d.ts

@@ -25,7 +25,9 @@ export interface RawClient {
 }
 export interface AttachKit {
     /** Connect a BrokerClient to a node's running broker, hello, await welcome. */
-    attach(id: string, role: ClientRole, clientId: string): Promise<Attached>;
+    attach(id: string, role: ClientRole, clientId: string, opts?: {
+        snapshotTail?: number;
+    }): Promise<Attached>;
     /** Attach (as `role`) and retry until the welcome satisfies `pred`. */
     attachUntil(id: string, role: ClientRole, clientId: string, pred: (a: Attached) => boolean, label: string): Promise<Attached>;
     /** A raw node:net peer. read:false leaves the socket PAUSED (G8 stalled viewer). */

package/dist/core/__tests__/helpers/broker-clients.js

@@ -37,7 +37,7 @@ export function createAttachKit(getH) {
     // awaitBoot returns once the boot proof is written — which is BEFORE the broker's
     // server.listen() binds view.sock — so a fresh attach can momentarily race the
     // bind; retry the connect on BrokerUnavailable until it is listening.
-    async function attach(id, role, clientId) {
+    async function attach(id, role, clientId, opts = {}) {
         const h = getH();
         await h.waitFor(() => existsSync(h.brokerSock(id)), { label: `view.sock for ${id}`, timeoutMs: 20_000 });
         const frames = [];
@@ -65,7 +65,12 @@ export function createAttachKit(getH) {
         // round-trip — so a welcome timeout cannot leak a connected socket past the test.
         liveClients.push({ close: () => client.close() });
         const waitFrame = (pred, label, timeoutMs = 15_000) => h.waitFor(() => frames.find(pred) ?? null, { label, timeoutMs });
-        client.send({ type: 'hello', role, client_id: clientId });
+        client.send({
+            type: 'hello',
+            role,
+            client_id: clientId,
+            ...(opts.snapshotTail === undefined ? {} : { snapshot_tail: opts.snapshotTail }),
+        });
         let welcome;
         try {
             welcome = (await waitFrame((f) => f.type === 'welcome', `welcome for ${clientId}`));

package/dist/core/__tests__/inline-memory-refs.test.js

@@ -3,7 +3,7 @@
 // Load-bearing corpus regression for `buildRefInventory` — the authoritative
 // inventory the broker and terminal attach viewer both resolve inline memory
 // references against. Covers scope precedence dedup, referenceability
-// (both kinds, gated and slash docs), INDEX folding, malformed-doc omission,
+// (both kinds, gated and slash docs), directory browse names, malformed-doc omission,
 // metadata-only rows, and stable ordering, all over real on-disk fixtures.
 import { test, describe, before, beforeEach, after } from 'node:test';
 import assert from 'node:assert/strict';
@@ -17,7 +17,7 @@ import { buildRefInventory } from '../memory/inline-ref-inventory.js';
 // ---------------------------------------------------------------------------
 // Wave C4 — buildRefInventory: the authoritative corpus builder. Fixture-
 // backed (node/project/user scope docs on disk), since precedence dedup,
-// referenceability-ignores-gate/slash, and INDEX folding are all corpus-shape
+// referenceability-ignores-gate/slash, and directory browse names are all corpus-shape
 // facts that a pure in-memory test can't exercise. Fixture names are prefixed
 // to avoid any collision with the real shipped builtin/user corpus that
 // listAllMemoryDocs() also picks up in this environment.
@@ -128,12 +128,15 @@ describe('buildRefInventory (fixture-backed corpus)', () => {
         assert.equal(refs.find((r) => r.name === 'crtr-inline-ref-fixture-knowledge')?.kind, 'knowledge');
         assert.equal(refs.find((r) => r.name === 'crtr-inline-ref-fixture-preference')?.kind, 'preference');
     });
-    test('an INDEX doc folds to its bare directory name, not "<dir>/INDEX"', () => {
+    test('an INDEX doc keeps its canonical name; the bare dir name is a browse link, not a ref row', () => {
         writeDoc(join(projectMemoryDir(), 'crtr-inline-ref-fixture-taste'), 'INDEX.md', "kind: knowledge\nshort-form: 'taste index'");
         const { refs, names } = buildRefInventory();
+        assert.ok(names.has('crtr-inline-ref-fixture-taste/INDEX'));
+        // The directory name resolves as a listing link — in `names` for linkify,
+        // never a RefMeta row (no doc answers for a directory).
         assert.ok(names.has('crtr-inline-ref-fixture-taste'));
-        assert.ok(!names.has('crtr-inline-ref-fixture-taste/INDEX'));
-        const winner = refs.find((r) => r.name === 'crtr-inline-ref-fixture-taste');
+        assert.ok(!refs.some((r) => r.name === 'crtr-inline-ref-fixture-taste'));
+        const winner = refs.find((r) => r.name === 'crtr-inline-ref-fixture-taste/INDEX');
         assert.equal(winner?.shortForm, 'taste index');
     });
     test('a root INDEX doc is omitted, never exposed as an empty ref name', () => {

package/dist/core/__tests__/memory-resolver-precedence.test.js

@@ -128,13 +128,14 @@ test('a plain path-named doc with no explicit name resolves to the nearest copy'
         process.chdir(prevCwd);
     }
 });
-test('a bare-directory query resolves to that dir\'s INDEX.md, nearest copy first', () => {
+test('a bare-directory query does not resolve to a doc — directories answer with listings, not INDEX.md', () => {
     process.chdir(child);
     resetScopeCache();
     try {
-        const doc = resolveMemoryDoc('taste');
-        assert.equal(doc.path, join(child, '.crouter', 'memory', 'taste', 'INDEX.md'));
-        assert.match(doc.body, /CHILD TASTE INDEX/);
+        assert.throws(() => resolveMemoryDoc('taste'), (err) => {
+            assert.equal(err.code, 'not_found');
+            return true;
+        });
     }
     finally {
         process.chdir(prevCwd);

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

@@ -76,9 +76,7 @@ test('resolveMemoryDocForTarget resolves a nested doc only with includeDescendan
     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' +
+        'when-and-why-to-read: When working in sub, this knowledge should be read because it carries the subsystem constraints.\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');

package/dist/core/__tests__/on-read-crouter-home-fence.test.js

@@ -50,15 +50,15 @@ test('a store nested in the crouter home does not leak into a canvas-artifact re
     mkdirSync(leakedStore, { recursive: true });
     writeFileSync(join(leakedStore, 'private-thing.md'), '---\nkind: knowledge\n' +
         "when-and-why-to-read: When X, read this because Y.\n" +
-        'file-read-visibility: content\n' +
-        'applies-to: "**/*.md"\n---\n' +
+        'surfaces:\n' +
+        '  - {on: read, match: "**/*.md", at: content}\n---\n' +
         'PRIVATE ASSISTANT MEMORY MUST NOT LEAK\n');
     // A canvas runtime artifact under the crouter home — the shape of every node
     // report/context file the harness auto-reads.
     const reportFile = join(fakeHome, '.crouter', 'canvas', 'nodes', 'somenode', 'reports', 'r.md');
     mkdirSync(join(fakeHome, '.crouter', 'canvas', 'nodes', 'somenode', 'reports'), { recursive: true });
     writeFileSync(reportFile, '# a node report\n');
-    const rendered = renderOnReadDocs(node, reportFile, new Set());
+    const rendered = renderOnReadDocs(node, reportFile, new Map());
     assert.ok(!rendered.includes('PRIVATE ASSISTANT MEMORY MUST NOT LEAK'), `crouter-home-nested store must not surface on a canvas read; got: ${rendered}`);
     assert.ok(!rendered.includes('private-thing'), `crouter-home-nested store name must not surface on a canvas read; got: ${rendered}`);
 });

package/dist/core/__tests__/on-read-dedup-resume.test.js

@@ -45,7 +45,7 @@ after(() => {
     else
         process.env['HOME'] = prevHomeEnv;
 });
-test('project and user memory docs without applies-to do not fire on file reads', () => {
+test('project and user memory docs without read surfaces do not fire on file reads', () => {
     const fakeHome = mkdtempSync(join(tmpdir(), 'crtr-onread-user-home-'));
     process.env['HOME'] = fakeHome;
     resetScopeCache();
@@ -53,18 +53,16 @@ test('project and user memory docs without applies-to do not fire on file reads'
     const userMemDir = join(fakeHome, '.crouter', 'memory');
     mkdirSync(userMemDir, { recursive: true });
     writeFileSync(join(userMemDir, 'noisy-global.md'), '---\nkind: preference\n' +
-        'when-and-why-to-read: When reading any file, this preference should be read because this fixture must not fire without an explicit route\n' +
-        'file-read-visibility: content\n---\n' +
+        'when-and-why-to-read: When reading any file, this preference should be read because this fixture must not fire without an explicit route\n---\n' +
         'NOISY USER BODY\n');
     const projectMemDir = join(fakeHome, 'work', '.crouter', 'memory');
     mkdirSync(projectMemDir, { recursive: true });
     writeFileSync(join(projectMemDir, 'local.md'), '---\nkind: knowledge\n' +
-        'when-and-why-to-read: When reading project files, this reference should be read because this fixture proves explicit file routing\n' +
-        'file-read-visibility: content\n---\n' +
+        'when-and-why-to-read: When reading project files, this reference should be read because this fixture proves explicit file routing\n---\n' +
         'LOCAL PROJECT BODY\n');
     const readFile = join(fakeHome, 'work', 'ideas.md');
     writeFileSync(readFile, 'turn off xml closer\n');
-    const rendered = renderOnReadDocs(node, readFile, new Set());
+    const rendered = renderOnReadDocs(node, readFile, new Map());
     assert.ok(!rendered.includes('NOISY USER BODY'), 'user-global doc has no explicit file route');
     assert.ok(!rendered.includes('LOCAL PROJECT BODY'), 'project doc also has no implicit file route');
     assert.equal(rendered, '', 'no file context renders without an explicit trigger');
@@ -72,13 +70,15 @@ test('project and user memory docs without applies-to do not fire on file reads'
 });
 test('on-read doc surfaces once, stays deduped across a revive(resume), re-surfaces after a fresh launch', () => {
     const node = spawnNode({ kind: 'general', cwd: work, parent: null }).node_id;
-    // A file-routed substrate doc in a `.crouter/memory/` ancestor.
+    // A file-routed substrate doc in a `.crouter/memory/` ancestor. The
+    // `./`-anchored glob pins the repo-relative anchor: `src/file.ts` matches
+    // only relative to the doc's owning repo dir, never absolutely.
     const memDir = join(work, '.crouter', 'memory');
     mkdirSync(memDir, { recursive: true });
     writeFileSync(join(memDir, 'onread-fixture.md'), '---\nkind: knowledge\n' +
         'when-and-why-to-read: When reading work files, this reference should be read because it is the on-read regression fixture\n' +
-        'file-read-visibility: content\n' +
-        'applies-to: "src/**"\n---\n' +
+        'surfaces:\n' +
+        '  - {on: read, match: "./src/**", at: content}\n---\n' +
         `${FIXTURE_BODY}\n`);
     const readFile = join(work, 'src', 'file.ts');
     mkdirSync(join(work, 'src'), { recursive: true });
@@ -106,13 +106,13 @@ test('an explicitly routed doc injects on-read under its frontmatter name, not t
     writeFileSync(join(memDir, 'physical-guide.md'), '---\nkind: knowledge\n' +
         'name: acme-project\n' +
         'when-and-why-to-read: When reading acme source, this knowledge should be read because it carries the project-specific implementation constraints.\n' +
-        'file-read-visibility: content\n' +
-        'applies-to: "src/**"\n---\n' +
+        'surfaces:\n' +
+        '  - {on: read, match: "./src/**", at: content}\n---\n' +
         'ACME PROJECT OPERATING GUIDE\n');
     const readFile = join(work, 'src', 'file.ts');
     mkdirSync(join(work, 'src'), { recursive: true });
     writeFileSync(readFile, 'export const x = 1;\n');
-    const rendered = renderOnReadDocs(node, readFile, new Set());
+    const rendered = renderOnReadDocs(node, readFile, new Map());
     assert.ok(rendered.includes('ACME PROJECT OPERATING GUIDE'), 'the matching explicit route fires');
     assert.ok(rendered.includes('<memory kind="knowledge" name="acme-project"'), `expected explicit frontmatter name "acme-project" in the injected envelope, got: ${rendered}`);
     assert.ok(!rendered.includes('name="physical-guide"'), 'must not fall back to the path-derived name when frontmatter sets one');

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

@@ -1,9 +1,9 @@
 // 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.
+// 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 `./`
+// anchor stays fenced to project-store docs — a hand-authored `./` glob 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';
@@ -45,22 +45,25 @@ after(() => {
         process.env['HOME'] = prevHomeEnv;
 });
 /** A work tree with a root front door and a nested store front door, both
- *  routed `.`. Returns the work dir. */
+ *  carrying the explicit front-door pair (workspace-open + `./**` read).
+ *  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' +
+        'surfaces:\n' +
+        '  - {on: workspace-open, at: content}\n' +
+        '  - {on: read, match: "./**", at: content}\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' +
+        'surfaces:\n' +
+        '  - {on: workspace-open, at: content}\n' +
+        '  - {on: read, match: "./**", at: content}\n---\n' +
         `${NESTED_BODY}\n`);
     return work;
 }
@@ -70,18 +73,18 @@ test('a nested store front door surfaces on a read beneath its owning dir, not o
     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());
+    const rendered = renderOnReadDocs(node, inside, new Map());
     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());
+    const renderedOutside = renderOnReadDocs(node, outside, new Map());
     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 seen = new Map();
     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');
@@ -92,18 +95,18 @@ test('workspace-open and on-read share one dedup set: root front door once, nest
     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', () => {
+test('a hand-authored `./`-anchored read glob 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' +
+        'surfaces:\n' +
+        '  - {on: read, match: "**/*.md", at: content}\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' +
+        'surfaces:\n' +
+        '  - {on: read, match: "./**", at: content}\n---\n' +
         'USER DOT BODY MUST NOT FIRE\n');
     const work = join(fakeHome, 'work');
     mkdirSync(work, { recursive: true });
@@ -111,7 +114,7 @@ test('a hand-authored `.` route in a user-scope doc never matches a read', () =>
     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());
+    const rendered = renderOnReadDocs(node, readFile, new Map());
     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}`);
+    assert.ok(!rendered.includes('USER DOT BODY MUST NOT FIRE'), `the \`./\` anchor is project-store only — a user doc's owning root is ~; got: ${rendered}`);
 });

package/dist/core/__tests__/seam/broker-attach-multiclient.test.js

@@ -253,3 +253,12 @@ test('G10 — retained extension display state rides IN welcome.snapshot.display
     assert.equal(live.method, 'setStatus');
     assert.equal(live.statusText, 'painted while attached');
 });
+test('snapshot_tail is ignored when the session has no stable message ids', async () => {
+    const token = tok('snapshot-tail-no-ids');
+    h.fakeCmd(id, { cmd: 'stream', text: token });
+    const full = await attachUntil(id, 'observer', 'snapshot-tail-full', (a) => JSON.stringify(a.welcome.snapshot.messages).includes(token), 'full snapshot after a tail-less attach');
+    assert.equal(full.welcome.snapshot.messageIds, undefined, 'the fake session has no stable ids');
+    const tailed = await attach(id, 'observer', 'snapshot-tail-request', { snapshotTail: 1 });
+    assert.equal(tailed.welcome.snapshot.messageIds, undefined, 'the tail request cannot invent stable ids');
+    assert.deepEqual(tailed.welcome.snapshot.messages, full.welcome.snapshot.messages, 'a welcome without stable ids keeps the full history instead of stranding an unpageable tail');
+});

package/dist/core/__tests__/serial/broker-snapshot-history.test.js

@@ -34,7 +34,7 @@ import { CANVAS_EXTENSIONS } from '../../runtime/launch.js';
 import { buildBrokerSession, snapshotMessages } from '../../runtime/broker.js';
 import { createNode } from '../../canvas/canvas.js';
 import { closeDb } from '../../canvas/db.js';
-import { transcriptMarkdown } from '../../runtime/node-read.js';
+import { readNodeMessagesPage, transcriptMarkdown } from '../../runtime/node-read.js';
 // M-9 (broker.ts fault-and-die model gate): a boot with no cfg.model now calls
 // the REAL SDK's modelRegistry.getAvailable() and faults if it's empty, which it
 // always is on a host/CI runner with no authenticated provider. This test only
@@ -128,6 +128,57 @@ test('broker welcome snapshot serves the persisted history, not pi\u2019s sliced
         rmSync(cwd, { recursive: true, force: true });
     }
 });
+test('readNodeMessagesPage keeps a tool call with all following tool results across cursor pages', async () => {
+    const home = mkdtempSync(join(tmpdir(), 'crtr-page-tools-home-'));
+    const sessionCwd = mkdtempSync(join(tmpdir(), 'crtr-page-tools-session-'));
+    const prevHome = process.env['CRTR_HOME'];
+    process.env['CRTR_HOME'] = home;
+    closeDb();
+    try {
+        const seed = SessionManager.create(sessionCwd);
+        seed.appendMessage(userMsg('before the tool run'));
+        seed.appendMessage({
+            ...assistantMsg('calling tools'),
+            content: [
+                { type: 'toolCall', id: 'tool-1', name: 'read', arguments: { path: 'one.txt' } },
+                { type: 'toolCall', id: 'tool-2', name: 'read', arguments: { path: 'two.txt' } },
+            ],
+        });
+        seed.appendMessage({ role: 'toolResult', toolCallId: 'tool-1', toolName: 'read', content: [{ type: 'text', text: 'one' }], isError: false, timestamp: Date.now() });
+        seed.appendMessage({ role: 'toolResult', toolCallId: 'tool-2', toolName: 'read', content: [{ type: 'text', text: 'two' }], isError: false, timestamp: Date.now() });
+        seed.appendMessage(userMsg('after the tool run'));
+        seed.appendMessage(assistantMsg('finished'));
+        const sessionFile = seed.getSessionFile();
+        const nodeId = 'tool-page-boundary';
+        createNode({
+            node_id: nodeId,
+            name: nodeId,
+            created: new Date().toISOString(),
+            cwd: sessionCwd,
+            kind: 'general',
+            mode: 'base',
+            lifecycle: 'terminal',
+            status: 'active',
+            pi_session_file: sessionFile,
+        });
+        const newest = await readNodeMessagesPage(nodeId, { limit: 3 });
+        assert.equal(newest.messages[0].role, 'assistant', 'the page walks back from the tool-result cut to its call');
+        assert.deepEqual(newest.messages.slice(1, 3).map((message) => message.role), ['toolResult', 'toolResult'], 'all tool results share the page with their call');
+        assert.ok(newest.nextCursor, 'the widened page still has an older cursor');
+        const older = await readNodeMessagesPage(nodeId, { cursor: newest.nextCursor, limit: 3 });
+        const persisted = SessionManager.open(sessionFile).buildSessionContext().messages;
+        assert.deepEqual([...older.messages, ...newest.messages], persisted, 'cursor pages remain gap-free and non-overlapping after widening');
+        assert.deepEqual([...(older.messageIds ?? []), ...(newest.messageIds ?? [])], SessionManager.open(sessionFile).getEntries().map(({ id }) => id), 'stable ids remain aligned across the widened page boundary');
+    }
+    finally {
+        closeDb();
+        process.env['CRTR_HOME'] = prevHome;
+        if (prevHome === undefined)
+            delete process.env['CRTR_HOME'];
+        rmSync(home, { recursive: true, force: true });
+        rmSync(sessionCwd, { recursive: true, force: true });
+    }
+});
 // C3 (inline memory references, Wave 1A): transcriptMarkdown is the human-
 // facing render of a dormant node's persisted session. It must generically
 // skip any custom message whose `display === false` (the same hidden-guidance

package/dist/core/__tests__/serial/flagship-lifecycle.test.js

@@ -229,7 +229,7 @@ test('flagship: full node lifecycle — spawn, dormancy, one-hop wake, promote,
             const stop = evaluateStop(B, { pushedFinal: false, requestedHumanReply: false });
             assert.equal(stop.action, 'reprompt', 'orchestrator B with no live sub, no final → reprompt');
             assert.equal(stop.reason, 'stalled', 'classified stalled');
-            assert.equal(stop.action === 'reprompt' ? stop.message : '', formatCard('stop-guard', { reason: 'stalled' }, STALL_REPROMPT), 'the stall reprompt nudge, delivered as a whole-message stop-guard envelope');
+            assert.equal(stop.action === 'reprompt' ? stop.message : '', formatCard('stop-guard', {}, STALL_REPROMPT), 'the stall reprompt nudge, delivered as a whole-message stop-guard envelope');
         }
         // ===================================================================
         // S10 — B YIELDS. The real plain `node yield` verb sets intent=refresh

package/dist/core/canvas/db.d.ts

@@ -1,6 +1,8 @@
 import { DatabaseSync } from 'node:sqlite';
 /** The ordered migration list. Index `i` is migration version `i + 1`; the db's
- *  `user_version` tracks how many have been applied. Append only. */
+ *  `user_version` tracks how many have been applied. Append only. Journaled
+ *  entries from `src/migrations/registry.ts` follow the local steps, so a new
+ *  registry migration lands as the next version. */
 export declare const MIGRATIONS: ReadonlyArray<(db: DatabaseSync) => void>;
 /** Bring `db` up to the latest schema version. Reads `user_version`, runs each
  *  pending migration in order, and bumps `user_version` after each so the work

package/dist/core/canvas/db.js

@@ -7,7 +7,8 @@
 import { DatabaseSync } from 'node:sqlite';
 import { existsSync, readFileSync, readdirSync, appendFileSync } from 'node:fs';
 import { basename, join, resolve } from 'node:path';
-import { canvasDbPath, ensureHome, isSafeNodeId, nodesRoot, nodeMetaPath } from './paths.js';
+import { canvasDbPath, crtrHome, ensureHome, isSafeNodeId, nodesRoot, nodeMetaPath } from './paths.js';
+import { STATE_MIGRATIONS } from '../../migrations/registry.js';
 import { customExtensionPaths } from './extensions.js';
 import { updateJsonFileDurably } from './meta-file.js';
 // --- Schema as a forward-only migration list ------------------------------
@@ -1152,8 +1153,16 @@ ALTER TABLE crons ADD COLUMN held INTEGER NOT NULL DEFAULT 0;
 ALTER TABLE crons ADD COLUMN last_poke_at TEXT;
 `);
 }
+/** The journaled lane of the state-migration registry, adapted to this chain's
+ *  step shape. Registry order is preserved, so these versions stay stable as
+ *  long as the registry is append-only (same contract as the local list). */
+const JOURNALED_STATE_MIGRATIONS = STATE_MIGRATIONS
+    .filter((m) => m.lane === 'journaled')
+    .map((m) => (db) => m.apply(db, crtrHome()));
 /** The ordered migration list. Index `i` is migration version `i + 1`; the db's
- *  `user_version` tracks how many have been applied. Append only. */
+ *  `user_version` tracks how many have been applied. Append only. Journaled
+ *  entries from `src/migrations/registry.ts` follow the local steps, so a new
+ *  registry migration lands as the next version. */
 export const MIGRATIONS = [
     /* v1 */ baselineSchema,
     /* v2 */ addRuntimeColumns,
@@ -1189,6 +1198,7 @@ export const MIGRATIONS = [
     /* v30 */ dropConsultOutbox,
     /* v31 */ addReviewSubmitRequested,
     /* v32 */ addCronHeldColumns,
+    ...JOURNALED_STATE_MIGRATIONS,
 ];
 /** Migration indexes that manage their OWN transaction and therefore must not
  *  be wrapped by `migrate()` — `node:sqlite` rejects a nested BEGIN. Index 3