@north-light/crouter 0.3.227 → 0.3.229

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

@@ -42,11 +42,17 @@ function freshNode(nodeId) {
 }
 function makeFakePi() {
     const handlers = {};
+    let resolveFirstInjection;
+    const firstInjection = new Promise((resolve) => { resolveFirstInjection = resolve; });
     return {
         injected: [],
+        firstInjection,
         sentMessages: [],
         on(e, h) { handlers[e] = h; },
-        sendUserMessage(content, options) { this.injected.push({ content, deliverAs: options?.deliverAs }); },
+        sendUserMessage(content, options) {
+            this.injected.push({ content, deliverAs: options?.deliverAs });
+            resolveFirstInjection?.();
+        },
         sendMessage(message) { this.sentMessages.push(message); },
         async fire(e, ev, ctx) { await handlers[e]?.(ev, ctx); },
     };
@@ -77,6 +83,13 @@ async function shutdown(pi, opts = {}) {
     await pi.fire('session_shutdown', {}, undefined);
 }
 const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+async function waitForFirstInjection(pi, timeoutMs = 2_000) {
+    const timeout = new Promise((_, reject) => {
+        const timer = setTimeout(() => reject(new Error('watcher did not inject the inbox handoff')), timeoutMs);
+        timer.unref();
+    });
+    await Promise.race([pi.firstInjection, timeout]);
+}
 // Register the watcher, then fire session_start — the real lifecycle gate
 // that arms its poll interval and initial tick (see canvas-inbox-watcher.ts).
 // registerCanvasInboxWatcher() alone only wires up handlers; without this the
@@ -161,7 +174,7 @@ describe('canvas inbox watcher — hold + idle delivery', () => {
         pi.fire('agent_start', { type: 'agent_start' }, { isIdle: () => false });
         await wait(TICK_MS + 100);
         appendInbox('node-refresh', { from: 'child-x', tier: 'urgent', kind: 'final', label: 'done' });
-        await wait(SETTLE_MS);
+        await waitForFirstInjection(pi);
         assert.equal(pi.injected.length, 1, 'the live broker receives the handoff before its durable cursor boundary');
         // The cursor operation decides the refresh hold at its durable commit
         // boundary; clearing intent does not manufacture a second handoff.

package/dist/core/__tests__/config-change-delta.test.js

@@ -0,0 +1,106 @@
+// A node whose kind/mode/lifecycle changes mid-context gets only memory newly
+// visible or raised above the context's active exposure ranks. Removals stay
+// silent because already loaded context cannot be unseen.
+//
+// The load-bearing case is the gated orchestration kernel: a base → orchestrator
+// change must select its real builtin document through the ordinary renderer.
+//
+// Run: node --conditions=crtr-src --import tsx/esm --test src/core/__tests__/config-change-delta.test.ts
+import { test, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { resetScopeCache } from '../scope.js';
+import { clearSessionCache } from '../substrate/session-cache.js';
+import { renderConfigChangeDelta, renderKnowledgeForSubject, renderPreferencesForSubject, } from '../substrate/render.js';
+import { emptyContextExposureState, exposureTarget, } from '../substrate/injected-store.js';
+const NODE = 'n-delta-test';
+const DEV_PREFERENCE = 'BODY-DELTA-DEV-PREFERENCE';
+const DEV_KNOWLEDGE_WHEN = 'When the developer-only guide is routed';
+const KERNEL_MARKER = '## You are an orchestrator';
+let home;
+let work;
+let prevHome;
+let prevCanvasHome;
+let prevProfile;
+let prevCwd;
+function subject(over = {}) {
+    return {
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        hasManager: true,
+        cwd: work,
+        scope: 'user',
+        orchestration: { depth: 1 },
+        profile: null,
+        ...over,
+    };
+}
+/** Everything the node's boot channels render for `s` — the baseline every
+ *  later delta is diffed against. */
+function seedBoot(state, s) {
+    renderPreferencesForSubject(s, exposureTarget(state, 'system'));
+    renderKnowledgeForSubject(s, NODE, exposureTarget(state, 'transcript'));
+}
+before(() => {
+    prevHome = process.env['HOME'];
+    prevCanvasHome = process.env['CRTR_HOME'];
+    prevProfile = process.env['CRTR_PROFILE_ID'];
+    prevCwd = process.cwd();
+    home = realpathSync(mkdtempSync(join(tmpdir(), 'crtr-delta-home-')));
+    work = realpathSync(mkdtempSync(join(tmpdir(), 'crtr-delta-work-')));
+    process.env['HOME'] = home;
+    process.env['CRTR_HOME'] = realpathSync(mkdtempSync(join(tmpdir(), 'crtr-delta-canvas-')));
+    delete process.env['CRTR_PROFILE_ID'];
+    const user = join(home, '.crouter', 'memory');
+    mkdirSync(user, { recursive: true });
+    writeFileSync(join(user, 'delta-dev-preference.md'), ['---', 'kind: preference', 'gate: {kind: developer}', 'surfaces:', '  - {on: boot, at: content}', '---', '', DEV_PREFERENCE, ''].join('\n'));
+    writeFileSync(join(user, 'delta-dev-knowledge.md'), ['---', 'kind: knowledge', `when-and-why-to-read: "${DEV_KNOWLEDGE_WHEN}"`, 'gate: {kind: developer}', 'surfaces:', '  - {on: boot, at: preview}', '---', '', 'ignored body', ''].join('\n'));
+    process.chdir(work);
+    resetScopeCache();
+    clearSessionCache();
+});
+after(() => {
+    process.chdir(prevCwd);
+    resetScopeCache();
+    rmSync(home, { recursive: true, force: true });
+    rmSync(work, { recursive: true, force: true });
+    rmSync(process.env['CRTR_HOME'], { recursive: true, force: true });
+    if (prevHome === undefined)
+        delete process.env['HOME'];
+    else
+        process.env['HOME'] = prevHome;
+    if (prevCanvasHome === undefined)
+        delete process.env['CRTR_HOME'];
+    else
+        process.env['CRTR_HOME'] = prevCanvasHome;
+    if (prevProfile !== undefined)
+        process.env['CRTR_PROFILE_ID'] = prevProfile;
+});
+test('a config change delivers only what the new configuration newly exposes', () => {
+    const state = emptyContextExposureState();
+    const transcript = exposureTarget(state, 'transcript');
+    const base = subject();
+    seedBoot(state, base);
+    assert.equal(renderConfigChangeDelta(base, NODE, transcript), '', 'no change → nothing to deliver; boot already showed this configuration');
+    // base → orchestrator: the builtin orchestration kernel is gated
+    // `{mode: orchestrator}`, so this transition is what unlocks it.
+    const promoted = subject({ mode: 'orchestrator' });
+    const promoteDelta = renderConfigChangeDelta(promoted, NODE, transcript);
+    assert.ok(promoteDelta.includes(KERNEL_MARKER), 'the promote delta carries the builtin orchestration kernel');
+    assert.ok(!promoteDelta.includes('Waiting is a way to end a turn'), 'a doc boot already delivered is not repeated');
+    assert.equal(renderConfigChangeDelta(promoted, NODE, transcript), '', 'the same change twice delivers nothing the second time');
+    // kind flip: a content-rung preference and a preview-rung knowledge doc, each
+    // gated on the new kind, in their own blocks.
+    const developer = subject({ mode: 'orchestrator', kind: 'developer' });
+    const kindDelta = renderConfigChangeDelta(developer, NODE, transcript);
+    assert.ok(kindDelta.includes(DEV_PREFERENCE), 'the newly-eligible preference body is delivered');
+    assert.ok(kindDelta.includes('<memory kind="preference">'), 'agent-editable preferences ride a preference block');
+    assert.ok(kindDelta.includes(`delta-dev-knowledge  # read when: ${DEV_KNOWLEDGE_WHEN}`), 'the newly-eligible knowledge doc is routed at its preview rung');
+    assert.ok(kindDelta.includes('<memory kind="knowledge">'), 'knowledge rides its own block');
+    assert.ok(!kindDelta.includes(KERNEL_MARKER), 'the kernel is not re-delivered — the promote already showed it');
+    // Removals are silent, and nothing already shown comes back.
+    assert.equal(renderConfigChangeDelta(subject({ mode: 'orchestrator' }), NODE, transcript), '', 'dropping back to the old kind announces nothing — the new prose overrides');
+});

package/dist/core/__tests__/context-intro.test.js

@@ -57,18 +57,22 @@ test('the stored situational card rides the bearings body; absent when unset', (
     assert.match(block, /<runtime kind="situational">/, 'card present once situational context is set');
     assert.match(block, /user is looking at the billing applet/, 'card carries the ambient text');
 });
-function makeFakePi() {
+function makeFakePi(entries = []) {
     return {
         sent: [],
+        entries,
         renderers: {},
         on(e, h) { if (e === 'session_start')
             this.handler = h; },
-        sendMessage(m) { this.sent.push(m); },
+        sendMessage(m) {
+            this.sent.push(m);
+            this.entries.push({ type: 'custom_message', ...m });
+        },
         registerMessageRenderer(t, r) { this.renderers[t] = r; },
     };
 }
-function fakeCtx(entries = []) {
-    return { sessionManager: { getEntries: () => entries } };
+function fakeCtx(pi) {
+    return { sessionManager: { getEntries: () => pi.entries } };
 }
 test('session_start injects the block as the first message of an empty session', async () => {
     const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
@@ -78,7 +82,7 @@ test('session_start injects the block as the first message of an empty session',
     assert.ok(pi.handler, 'session_start handler registered');
     // Empty session → inject the block as its own custom message (no delivery
     // options → it precedes the first prompt).
-    await pi.handler({ reason: 'startup' }, fakeCtx());
+    await pi.handler({ reason: 'startup' }, fakeCtx(pi));
     assert.equal(pi.sent.length, 1, 'one message injected');
     assert.equal(pi.sent[0].customType, CONTEXT_INTRO_CUSTOM_TYPE);
     assert.equal(pi.sent[0].display, true);
@@ -92,19 +96,19 @@ test('session_start is idempotent across resume (skips if already in history)',
     // skips when the present bearings name THIS node (a fork inherits the
     // SOURCE's bearings, which name a different node — see canvas-context-intro
     // tests), so a realistic resume entry must carry the real block content.
-    const pi = makeFakePi();
-    registerCanvasContextIntro(pi);
     const entries = [
         { type: 'custom_message', customType: CONTEXT_INTRO_CUSTOM_TYPE, content: buildContextIntro(meta.node_id) },
     ];
-    await pi.handler({ reason: 'resume' }, fakeCtx(entries));
+    const pi = makeFakePi(entries);
+    registerCanvasContextIntro(pi);
+    await pi.handler({ reason: 'resume' }, fakeCtx(pi));
     assert.equal(pi.sent.length, 0, 'our own block already in history → skip');
 });
 test('session_start is inert when CRTR_NODE_ID is absent', async () => {
     delete process.env['CRTR_NODE_ID'];
     const pi = makeFakePi();
     registerCanvasContextIntro(pi);
-    await pi.handler({ reason: 'startup' }, fakeCtx());
+    await pi.handler({ reason: 'startup' }, fakeCtx(pi));
     assert.equal(pi.sent.length, 0);
 });
 test('renderer registered for the customType; collapsed hides body, ctrl+o expand reveals it', () => {

package/dist/core/__tests__/daemon-boot.test.js

@@ -1,8 +1,9 @@
 import { test, before, after, beforeEach } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { spawnSync, spawn } from 'node:child_process';
 import { createServer } from 'node:net';
 import { createNode, getNode, subscribe } from '../canvas/canvas.js';
@@ -177,6 +178,18 @@ test('verifyDaemonStartup waits for pidfile + live pid, then reports success for
     assert.equal(pidAliveReady, true, 'pid must have been alive before success');
     assert.equal(slept > 0, true, 'the guard must actually poll');
 });
+test('runDaemon awaits activation before ownership and readiness', () => {
+    const source = readFileSync(fileURLToPath(new URL('../../daemon/crtrd.ts', import.meta.url)), 'utf8');
+    const runDaemonAt = source.indexOf('export async function runDaemon');
+    const activationAt = source.indexOf('await ensureOnDiskMigrations();', runDaemonAt);
+    const ownershipAt = source.indexOf('claimDaemonOwnership(', runDaemonAt);
+    const readinessAt = source.indexOf('writePidfile();', runDaemonAt);
+    assert.ok(runDaemonAt >= 0, 'runDaemon exists');
+    assert.ok(activationAt > runDaemonAt, 'runDaemon awaits on-disk activation');
+    assert.equal(source.slice(runDaemonAt, activationAt).includes('await '), false, 'activation is the first awaited operation');
+    assert.ok(activationAt < ownershipAt, 'activation precedes the ownership claim that opens canvas.db');
+    assert.ok(ownershipAt < readinessAt, 'ownership follows activation before readiness is published');
+});
 // Regression for the cold-guest recreate blocker: the production startup window
 // must tolerate a slower cold start than the old 500ms bound.
 test('verifyDaemonStartup default window tolerates a slower cold start', async () => {
@@ -197,28 +210,21 @@ test('verifyDaemonStartup default window tolerates a slower cold start', async (
     });
     assert.equal(existingPid, null, 'the production startup window must allow a cold guest to settle');
 });
-// REGRESSION (#508): a fixed 5s startup window falsely failed a valid cold
-// boot right after `install-runtime`, where the daemon's first-ever module
-// load + possible db migration can push writePidfile() past 5s even though
-// the daemon is starting up fine. The production window must comfortably
-// tolerate a pidfile that only appears well past the old 5s bound.
-test('verifyDaemonStartup default window tolerates a cold start slower than the old 5s bound', async () => {
+test('startup verification waits for delayed activation inside the shared window', async () => {
     let now = 0;
-    let pidfileReady = false;
-    let pidAliveReady = false;
+    let activationComplete = false;
     const existingPid = await verifyDaemonStartup(42, undefined, {
         now: () => now,
-        readPidfile: () => (pidfileReady ? 42 : null),
-        isPidAlive: () => pidAliveReady,
+        readPidfile: () => (activationComplete ? 42 : null),
+        isPidAlive: () => activationComplete,
         sleepMs: (ms) => {
             now += ms;
-            if (now >= 12_000)
-                pidfileReady = true;
-            if (now >= 12_100)
-                pidAliveReady = true;
+            if (now >= 25_000)
+                activationComplete = true;
         },
     });
-    assert.equal(existingPid, null, 'the production startup window must survive a pidfile that appears well past the old 5s bound');
+    assert.equal(existingPid, null, 'activation beyond the old 20s bound still reaches readiness');
+    assert.equal(activationComplete, true, 'readiness follows activation completion');
 });
 // A concurrent start race is success when another live daemon already owns the
 // pidfile; the loser must return that existing pid instead of timing out.

package/dist/core/__tests__/fixtures/memory-slash-live-probe.js

@@ -1,4 +1,4 @@
-import { existsSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { DefaultResourceLoader, ExtensionRunner, } from '@earendil-works/pi-coding-agent';
 import { buildRefInventory } from '../../memory/inline-ref-inventory.js';
@@ -17,6 +17,10 @@ async function main() {
     const stateBeforeProspective = existsSync(home);
     const prospective = await runProspectiveInventory({ cwd, profileId: null, extensions: [extensionPath] });
     const stateAfterProspective = existsSync(home);
+    const nodeId = process.env['CRTR_NODE_ID'];
+    if (nodeId === undefined || nodeId === '')
+        throw new Error('CRTR_NODE_ID is required');
+    mkdirSync(join(home, 'nodes', nodeId), { recursive: true });
     const loader = new DefaultResourceLoader({
         cwd,
         agentDir: join(cwd, '.pi'),

package/dist/core/__tests__/human-deliver.test.js

@@ -6,6 +6,7 @@ import assert from 'node:assert/strict';
 import { mkdtempSync, rmSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { ApiError } from '../../api/index.js';
 import { createApiServer } from '../../daemon/api/server.js';
 import { cancelHumanTicket, deliverTerminalResult, resolvePageTicket, settleFeedbackCompanion } from '../../daemon/human/finish.js';
 import { humanSend } from '../../commands/human/prompts.js';
@@ -219,6 +220,24 @@ describe('terminal ticket delivery', () => {
         assert.equal(notes[0].tier, 'normal');
         assert.match(notes[0].label, /canceled/);
     });
+    test('cancellation reaches subscribers when the bridge is already done, and retries conflict rather than fail', async () => {
+        const actor = spawnNode({ kind: 'general', parent: null, cwd: home, name: 'actor' }).node_id;
+        const bridge = spawnNode({ kind: 'human', parent: actor, cwd: home, name: 'human-page', lifecycle: 'terminal' }).node_id;
+        const other = spawnNode({ kind: 'general', parent: null, cwd: home, name: 'other' }).node_id;
+        const { subscribe } = await import('../canvas/canvas.js');
+        subscribe(other, bridge, true);
+        submitBridgePage(bridge);
+        // The bridge is parked done with no canonical final while its page is still
+        // pending — done is where cancellation wants it, so cancelling must deliver.
+        transition(bridge, 'finish');
+        const result = await cancelHumanTicket(bridge, { reason: 'stale', actor });
+        assert.equal(result.kind, 'canceled');
+        assert.equal(getNode(bridge)?.status, 'done');
+        assert.equal(readInboxSince(other).length, 1, 'the other waiter is told no answer is coming');
+        // The recorded cancellation is final: a retry is an already-resolved
+        // conflict, never a delivery failure that keeps repeating.
+        await assert.rejects(() => cancelHumanTicket(bridge, { reason: 'stale', actor }), (error) => error instanceof ApiError && error.status === 409 && error.code === 'ticket_already_resolved');
+    });
 });
 test('a display-only page publishes passively and creates no canvas node', async () => {
     const page = join(home, 'build-done.tsx');

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

@@ -25,6 +25,8 @@ import { gatewayMemoryRows } from '../runtime/chat-inventory-rows.js';
 // ---------------------------------------------------------------------------
 describe('buildRefInventory (fixture-backed corpus)', () => {
     const NODE_ID = 'crtr-inline-ref-fixture-node';
+    const PROJECT_NAMESPACE = 'crtr-inline-ref-fixture-project';
+    const projectName = (local) => `${PROJECT_NAMESPACE}/root/${local}`;
     let canvasHome;
     let userHome;
     let projectBase;
@@ -75,6 +77,10 @@ describe('buildRefInventory (fixture-backed corpus)', () => {
         projectBase = mkdtempSync(join(tmpdir(), 'crtr-inline-ref-project-'));
         projectRoot = join(projectBase, 'root');
         mkdirSync(projectRoot, { recursive: true });
+        const repositoryMemory = join(projectBase, '.crouter', 'memory');
+        mkdirSync(repositoryMemory, { recursive: true });
+        mkdirSync(projectMemoryDir(), { recursive: true });
+        writeFileSync(join(repositoryMemory, 'INDEX.md'), `---\nnamespace: ${PROJECT_NAMESPACE}\n---\nProject front door.\n`, 'utf8');
         process.env['CRTR_HOME'] = canvasHome;
         process.env['HOME'] = userHome;
         process.env['CRTR_NODE_ID'] = NODE_ID;
@@ -102,28 +108,25 @@ describe('buildRefInventory (fixture-backed corpus)', () => {
         else
             process.env['CRTR_NODE_ID'] = prevNodeId;
     });
-    test('nearest scope wins by canonical name: node > project > user', () => {
-        const name = 'crtr-inline-ref-fixture-shared';
-        writeDoc(userMemoryDir(), `${name}.md`, "kind: knowledge\nshort-form: 'user copy'");
-        writeDoc(projectMemoryDir(), `${name}.md`, "kind: knowledge\nshort-form: 'project copy'");
-        writeDoc(nodeScopeMemoryDir(), `${name}.md`, "kind: knowledge\nshort-form: 'node copy'");
+    test('canonical qualification removes project shadowing while equal identities keep precedence', () => {
+        const local = 'crtr-inline-ref-fixture-shared';
+        const qualified = projectName(local);
+        writeDoc(userMemoryDir(), `${local}.md`, "kind: knowledge\nshort-form: 'user copy'");
+        writeDoc(projectMemoryDir(), `${local}.md`, "kind: knowledge\nshort-form: 'project copy'");
+        writeDoc(nodeScopeMemoryDir(), `${local}.md`, "kind: knowledge\nshort-form: 'node copy'");
         let { refs, names } = buildRefInventory();
-        assert.ok(names.has(name));
-        let winner = refs.find((r) => r.name === name);
+        assert.ok(names.has(local));
+        assert.ok(names.has(qualified));
+        let winner = refs.find((r) => r.name === local);
         assert.equal(winner?.scope, 'node');
         assert.equal(winner?.shortForm, 'node copy');
-        // Remove the node-scope copy: project now wins.
-        rmSync(join(nodeScopeMemoryDir(), `${name}.md`));
-        clearSessionCache();
-        ({ refs, names } = buildRefInventory());
-        winner = refs.find((r) => r.name === name);
+        winner = refs.find((r) => r.name === qualified);
         assert.equal(winner?.scope, 'project');
         assert.equal(winner?.shortForm, 'project copy');
-        // Remove the project-scope copy too: user is the last resort.
-        rmSync(join(projectMemoryDir(), `${name}.md`));
+        rmSync(join(nodeScopeMemoryDir(), `${local}.md`));
         clearSessionCache();
         ({ refs, names } = buildRefInventory());
-        winner = refs.find((r) => r.name === name);
+        winner = refs.find((r) => r.name === local);
         assert.equal(winner?.scope, 'user');
         assert.equal(winner?.shortForm, 'user copy');
     });
@@ -133,41 +136,41 @@ describe('buildRefInventory (fixture-backed corpus)', () => {
         writeDoc(projectMemoryDir(), 'crtr-inline-ref-fixture-gated.md', 'kind: knowledge\ngate:\n  never-matches: true');
         writeDoc(projectMemoryDir(), 'crtr-inline-ref-fixture-slash.md', 'kind: knowledge\nslash: true');
         const { refs, names } = buildRefInventory();
-        for (const name of [
+        for (const local of [
             'crtr-inline-ref-fixture-knowledge',
             'crtr-inline-ref-fixture-preference',
             'crtr-inline-ref-fixture-gated',
             'crtr-inline-ref-fixture-slash',
         ]) {
+            const name = projectName(local);
             assert.ok(names.has(name), `expected ${name} to be referenceable`);
         }
-        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');
+        assert.equal(refs.find((r) => r.name === projectName('crtr-inline-ref-fixture-knowledge'))?.kind, 'knowledge');
+        assert.equal(refs.find((r) => r.name === projectName('crtr-inline-ref-fixture-preference'))?.kind, 'preference');
     });
-    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'");
+    test('a collapsed directory document keeps one canonical name and registers its browse node', () => {
+        const local = 'crtr-inline-ref-fixture-taste';
+        const name = projectName(local);
+        writeDoc(join(projectMemoryDir(), local), '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(!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');
+        assert.ok(!names.has(`${name}/INDEX`));
+        assert.ok(names.has(name));
+        assert.ok(refs.some((r) => r.name === name));
+        assert.equal(refs.find((r) => r.name === name)?.shortForm, 'taste index');
     });
-    test('a root INDEX doc is omitted, never exposed as an empty ref name', () => {
-        writeDoc(projectMemoryDir(), 'INDEX.md', "kind: knowledge\nshort-form: 'project root index'");
-        writeDoc(projectMemoryDir(), 'crtr-inline-ref-fixture-sibling.md', 'kind: knowledge');
+    test('a project root INDEX document is omitted from refs but its namespace remains usable', () => {
+        writeDoc(join(projectBase, '.crouter', 'memory'), 'INDEX.md', `namespace: ${PROJECT_NAMESPACE}\nkind: knowledge\nshort-form: 'project root index'`);
+        const local = 'crtr-inline-ref-fixture-sibling';
+        writeDoc(projectMemoryDir(), `${local}.md`, 'kind: knowledge');
         const { refs, names } = buildRefInventory();
         assert.ok(!names.has(''));
         assert.ok(!refs.some((r) => r.name === ''));
-        // A sibling doc in the same corpus is unaffected.
-        assert.ok(names.has('crtr-inline-ref-fixture-sibling'));
+        assert.ok(names.has(projectName(local)));
     });
     test('refs are metadata-only: exactly {name, kind, scope, shortForm, gatewayVisible}, no body/path', () => {
         writeDoc(projectMemoryDir(), 'crtr-inline-ref-fixture-meta.md', "kind: knowledge\nshort-form: 'hook'");
         const { refs } = buildRefInventory();
-        const ref = refs.find((r) => r.name === 'crtr-inline-ref-fixture-meta');
+        const ref = refs.find((r) => r.name === projectName('crtr-inline-ref-fixture-meta'));
         assert.ok(ref);
         assert.deepEqual(Object.keys(ref).sort(), ['gatewayVisible', 'kind', 'name', 'scope', 'shortForm']);
     });
@@ -176,30 +179,31 @@ describe('buildRefInventory (fixture-backed corpus)', () => {
         writeDoc(projectMemoryDir(), 'crtr-inline-ref-fixture-hidden.md', 'kind: knowledge\nextensions:\n  northlight:\n    visibility: false');
         writeDoc(projectMemoryDir(), 'crtr-inline-ref-fixture-visible.md', 'kind: knowledge');
         const { refs, names } = buildRefInventory();
-        const hidden = refs.find((ref) => ref.name === 'crtr-inline-ref-fixture-hidden');
-        const visible = refs.find((ref) => ref.name === 'crtr-inline-ref-fixture-visible');
+        const hidden = refs.find((ref) => ref.name === projectName('crtr-inline-ref-fixture-hidden'));
+        const visible = refs.find((ref) => ref.name === projectName('crtr-inline-ref-fixture-visible'));
         assert.equal(hidden?.gatewayVisible, false);
         assert.equal(visible?.gatewayVisible, true);
-        assert.ok(names.has('crtr-inline-ref-fixture-hidden'));
-        assert.ok(names.has('crtr-inline-ref-fixture-visible'));
+        assert.ok(names.has(projectName('crtr-inline-ref-fixture-hidden')));
+        assert.ok(names.has(projectName('crtr-inline-ref-fixture-visible')));
         assert.ok(refs.some((ref) => ref.scope === 'builtin'));
         assert.ok(refs.filter((ref) => ref.scope === 'builtin').every((ref) => !ref.gatewayVisible));
         const chatRows = gatewayMemoryRows(refs);
-        assert.ok(!chatRows.some((ref) => ref.name === 'crtr-inline-ref-fixture-hidden'));
-        assert.ok(chatRows.some((ref) => ref.name === 'crtr-inline-ref-fixture-visible'));
+        assert.ok(!chatRows.some((ref) => ref.name === projectName('crtr-inline-ref-fixture-hidden')));
+        assert.ok(chatRows.some((ref) => ref.name === projectName('crtr-inline-ref-fixture-visible')));
         assert.ok(!chatRows.some((ref) => ref.scope === 'builtin'));
     });
     test('a malformed doc (no valid kind) is omitted from the inventory', () => {
         writeDoc(projectMemoryDir(), 'crtr-inline-ref-fixture-malformed.md', "short-form: 'no kind here'");
         const { names } = buildRefInventory();
-        assert.ok(!names.has('crtr-inline-ref-fixture-malformed'));
+        assert.ok(!names.has(projectName('crtr-inline-ref-fixture-malformed')));
     });
-    test('duplicate distinct-scope docs still produce ONE inventory row (not one per scope)', () => {
-        const name = 'crtr-inline-ref-fixture-dedup';
-        writeDoc(userMemoryDir(), `${name}.md`, 'kind: knowledge');
-        writeDoc(projectMemoryDir(), `${name}.md`, 'kind: knowledge');
+    test('project qualification keeps distinct scope identities separate', () => {
+        const local = 'crtr-inline-ref-fixture-dedup';
+        writeDoc(userMemoryDir(), `${local}.md`, 'kind: knowledge');
+        writeDoc(projectMemoryDir(), `${local}.md`, 'kind: knowledge');
         const { refs } = buildRefInventory();
-        assert.equal(refs.filter((r) => r.name === name).length, 1);
+        assert.equal(refs.filter((r) => r.name === local).length, 1);
+        assert.equal(refs.filter((r) => r.name === projectName(local)).length, 1);
     });
     test('refs are stably sorted by winning scope precedence then name', () => {
         writeDoc(nodeScopeMemoryDir(), 'crtr-inline-ref-fixture-b-node.md', 'kind: knowledge');
@@ -209,7 +213,7 @@ describe('buildRefInventory (fixture-backed corpus)', () => {
         const fixtureRefs = refs.filter((r) => r.name.startsWith('crtr-inline-ref-fixture-'));
         const idxA = fixtureRefs.findIndex((r) => r.name === 'crtr-inline-ref-fixture-a-node');
         const idxB = fixtureRefs.findIndex((r) => r.name === 'crtr-inline-ref-fixture-b-node');
-        const idxC = fixtureRefs.findIndex((r) => r.name === 'crtr-inline-ref-fixture-c-project');
+        const idxC = fixtureRefs.findIndex((r) => r.name === projectName('crtr-inline-ref-fixture-c-project'));
         // Node-scope docs (a, b) sort before the project-scope doc (c); within the
         // same scope, alphabetically by name.
         assert.ok(idxA < idxB, 'a-node before b-node (alphabetical within node scope)');

package/dist/core/__tests__/{serial → integration}/broker-fork-seam.test.js

@@ -1,4 +1,4 @@
-// Run with: npm run test:serial
+// Run with: npm run test:integration
 //
 // BUG-REGRESSION (broker-universal-host cut, design §B.broker; U1 report
 // mq8ftenr-5d55313d). Before the cut, the headless broker had NO fork path — its

package/dist/core/__tests__/{serial → integration}/broker-sdk-wiring.test.js

@@ -1,4 +1,4 @@
-// Run with: npm run test:serial
+// Run with: npm run test:integration
 //
 // REAL-SDK regression tests for the latent broker gaps the viewer-reuse scout
 // (node mq5thyli) found (findings-viewer-reuse.md §Q2). These deliberately drive

package/dist/core/__tests__/{serial → integration}/broker-snapshot-history.test.js

@@ -1,4 +1,4 @@
-// Run with: npm run test:serial
+// Run with: npm run test:integration
 //
 // BUG-REGRESSION (real, observed; surfaced during the crouter-web build, proven
 // broker-side). After a revive resumes a previously-CLOSED pi session, the