@north-light/crouter 0.3.226 → 0.3.228

package/dist/core/__tests__/repository-root-identity.test.js

@@ -0,0 +1,219 @@
+// Repository-root project-memory identity: real Git and non-Git fixtures prove
+// that declarations live at a repository root while every nested store derives
+// its effective prefix from its physical owner path.
+//
+// Run: node --conditions=crtr-src --import tsx/esm --test src/core/__tests__/repository-root-identity.test.ts
+import { after, before, beforeEach, test } 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 { gitSync } from '../git.js';
+import { createProfile } from '../profiles/manifest.js';
+import { loadMemoryStoreView, memoryStoresInPrecedence, openProjectMemoryStore, resolveMemoryDocForTarget, } from '../memory-resolver.js';
+import { resetScopeCache } from '../scope.js';
+const cleanups = [];
+let previousHome;
+before(() => {
+    previousHome = process.env.HOME;
+});
+beforeEach(() => {
+    process.env.HOME = fixtureDir('crtr-repository-root-identity-home-');
+    resetScopeCache();
+});
+after(() => {
+    resetScopeCache();
+    for (const path of cleanups)
+        rmSync(path, { recursive: true, force: true });
+    if (previousHome === undefined)
+        delete process.env.HOME;
+    else
+        process.env.HOME = previousHome;
+});
+function fixtureDir(prefix) {
+    const path = realpathSync(mkdtempSync(join(tmpdir(), prefix)));
+    cleanups.push(path);
+    return path;
+}
+function writeDoc(path, body, frontmatter) {
+    mkdirSync(join(path, '..'), { recursive: true });
+    const yaml = frontmatter === undefined ? '' : `---\n${frontmatter}\n---\n`;
+    writeFileSync(path, `${yaml}${body}\n`, 'utf8');
+}
+function writeStore(owner, namespace) {
+    const frontmatter = namespace === undefined ? undefined : `namespace: ${namespace}`;
+    writeDoc(join(owner, '.crouter', 'memory', 'INDEX.md'), 'STORE INDEX', frontmatter);
+}
+function initGit(repository) {
+    mkdirSync(repository, { recursive: true });
+    assert.equal(gitSync(['-C', repository, 'init', '-q'], undefined).status, 0, 'git init succeeds');
+}
+function commitInitial(repository) {
+    writeFileSync(join(repository, 'README.md'), 'fixture\n', 'utf8');
+    assert.equal(gitSync(['-C', repository, 'add', 'README.md'], undefined).status, 0);
+    assert.equal(gitSync(['-C', repository, '-c', 'user.name=Fixture', '-c', 'user.email=fixture@example.com', 'commit', '-qm', 'initial'], undefined).status, 0);
+}
+function target(cwd, profileId = null) {
+    return { cwd, profileId, nodeId: null };
+}
+test('a Git root declaration gives a metadata-free nested store its repository-relative prefix', () => {
+    const repository = join(process.env.HOME, 'repository');
+    const nested = join(repository, 'packages', 'agent');
+    initGit(repository);
+    writeStore(repository, 'acme');
+    mkdirSync(join(nested, '.crouter', 'memory'), { recursive: true });
+    writeDoc(join(nested, '.crouter', 'memory', 'guide.md'), 'NESTED GUIDE');
+    const doc = resolveMemoryDocForTarget('acme/packages/agent/guide', target(nested), { scope: 'project' });
+    assert.equal(doc.path, join(nested, '.crouter', 'memory', 'guide.md'));
+    assert.equal(doc.name, 'acme/packages/agent/guide');
+    const store = openProjectMemoryStore(nested);
+    assert.equal(store.mountStatus, 'ready');
+    assert.equal(store.repositoryRoot, repository);
+    assert.equal(store.ownerRelativePath, 'packages/agent');
+    assert.equal(store.namespacePath, join(repository, '.crouter', 'memory', 'INDEX.md'));
+});
+test('repository-relative ordering prefixes are stripped before nested identity composition', () => {
+    const repository = join(process.env.HOME, 'repository');
+    const nested = join(repository, '01-api');
+    initGit(repository);
+    writeStore(repository, 'acme');
+    writeStore(nested);
+    writeDoc(join(nested, '.crouter', 'memory', 'guide.md'), 'ORDERED GUIDE');
+    const store = openProjectMemoryStore(nested);
+    assert.equal(store.mountStatus, 'ready');
+    assert.equal(store.ownerRelativePath, 'api');
+    assert.equal(store.namespace, 'acme/api');
+    const doc = resolveMemoryDocForTarget('acme/api/guide', target(nested), { scope: 'project' });
+    assert.equal(doc.path, join(nested, '.crouter', 'memory', 'guide.md'));
+    assert.equal(doc.name, 'acme/api/guide');
+});
+test('a metadata-free nested INDEX answers exactly at the nested effective prefix', () => {
+    const repository = join(process.env.HOME, 'repository');
+    const nested = join(repository, 'packages', 'agent');
+    initGit(repository);
+    writeStore(repository, 'acme');
+    writeStore(nested);
+    writeDoc(join(nested, '.crouter', 'memory', 'guide.md'), 'NESTED GUIDE');
+    const store = openProjectMemoryStore(nested);
+    assert.equal(store.mountStatus, 'ready');
+    assert.equal(store.namespace, 'acme/packages/agent');
+    const view = loadMemoryStoreView(store, true);
+    assert.deepEqual(view.docs.map((doc) => doc.name), ['acme/packages/agent', 'acme/packages/agent/guide']);
+    assert.equal(resolveMemoryDocForTarget('acme/packages/agent', target(nested), { scope: 'project' }).path, join(nested, '.crouter', 'memory', 'INDEX.md'));
+});
+test('linked worktree owners have identical canonical names from different physical paths', () => {
+    const main = join(process.env.HOME, 'main');
+    const linked = join(process.env.HOME, 'linked');
+    initGit(main);
+    commitInitial(main);
+    assert.equal(gitSync(['-C', main, 'worktree', 'add', '-q', '-b', 'linked', linked], undefined).status, 0);
+    const mainOwner = join(main, 'packages', 'agent');
+    const linkedOwner = join(linked, 'packages', 'agent');
+    writeStore(main, 'acme');
+    writeStore(linked, 'acme');
+    writeStore(mainOwner);
+    writeStore(linkedOwner);
+    writeDoc(join(mainOwner, '.crouter', 'memory', 'guide.md'), 'MAIN GUIDE');
+    writeDoc(join(linkedOwner, '.crouter', 'memory', 'guide.md'), 'LINKED GUIDE');
+    const mainDoc = resolveMemoryDocForTarget('acme/packages/agent/guide', target(mainOwner), { scope: 'project' });
+    const linkedDoc = resolveMemoryDocForTarget('acme/packages/agent/guide', target(linkedOwner), { scope: 'project' });
+    assert.equal(mainDoc.name, linkedDoc.name);
+    assert.equal(mainDoc.path, join(mainOwner, '.crouter', 'memory', 'guide.md'));
+    assert.equal(linkedDoc.path, join(linkedOwner, '.crouter', 'memory', 'guide.md'));
+    const mainStore = openProjectMemoryStore(mainOwner);
+    const linkedStore = openProjectMemoryStore(linkedOwner);
+    assert.equal(mainStore.repositoryKey, linkedStore.repositoryKey);
+    assert.notEqual(mainStore.repositoryRoot, linkedStore.repositoryRoot);
+});
+test('an embedded Git repository uses its own declaration from cwd and explicit store opening', () => {
+    const outer = join(process.env.HOME, 'outer');
+    const embedded = join(outer, 'vendor');
+    const nested = join(embedded, 'pkg');
+    initGit(outer);
+    writeStore(outer, 'outer');
+    initGit(embedded);
+    writeStore(embedded, 'inner');
+    writeStore(nested);
+    writeDoc(join(nested, '.crouter', 'memory', 'guide.md'), 'EMBEDDED GUIDE');
+    const fromCwd = resolveMemoryDocForTarget('inner/pkg/guide', target(nested), { scope: 'project' });
+    assert.equal(fromCwd.path, join(nested, '.crouter', 'memory', 'guide.md'));
+    const explicit = openProjectMemoryStore(nested);
+    assert.equal(explicit.repositoryRoot, embedded);
+    assert.equal(explicit.namespace, 'inner/pkg');
+    assert.equal(loadMemoryStoreView(explicit, true).resolve('inner/pkg/guide').path, fromCwd.path);
+});
+test('a non-Git nested store derives from the outermost ancestor project store', () => {
+    const root = join(process.env.HOME, 'non-git');
+    const nested = join(root, 'packages', 'agent');
+    writeStore(root, 'workspace');
+    writeStore(nested);
+    writeDoc(join(nested, '.crouter', 'memory', 'guide.md'), 'NON-GIT GUIDE');
+    const store = openProjectMemoryStore(nested);
+    assert.equal(store.mountStatus, 'ready');
+    assert.equal(store.repositoryRoot, root);
+    assert.equal(store.repositoryKey, `path:${root}`);
+    assert.equal(store.ownerRelativePath, 'packages/agent');
+    assert.equal(store.namespace, 'workspace/packages/agent');
+    assert.equal(resolveMemoryDocForTarget('workspace/packages/agent/guide', target(nested), { scope: 'project' }).path, join(nested, '.crouter', 'memory', 'guide.md'));
+});
+test('a Git descendant without a root store is undeclared until the root declaration is created', () => {
+    const repository = join(process.env.HOME, 'repository');
+    const nested = join(repository, 'packages', 'agent');
+    initGit(repository);
+    writeStore(nested);
+    writeDoc(join(nested, '.crouter', 'memory', 'guide.md'), 'NESTED GUIDE');
+    const before = openProjectMemoryStore(nested);
+    assert.equal(before.mountStatus, 'undeclared');
+    assert.equal(before.mountFailure, 'undeclared-root');
+    assert.match(before.diagnostic ?? '', new RegExp(repository.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
+    writeStore(repository, 'acme');
+    const after = openProjectMemoryStore(nested);
+    assert.equal(after.mountStatus, 'ready');
+    assert.equal(after.namespace, 'acme/packages/agent');
+});
+test('sibling owner paths that normalize to one prefix, including ordering prefixes, leave both stores invalid', () => {
+    const repository = join(process.env.HOME, 'repository');
+    const first = join(repository, '01-My Notes');
+    const second = join(repository, 'my-notes');
+    initGit(repository);
+    writeStore(repository, 'acme');
+    writeStore(first);
+    writeStore(second);
+    const profileId = createProfile('collision', [{ path: second, memory: 'content' }]).profileId;
+    const stores = memoryStoresInPrecedence(target(first, profileId), 'project');
+    const colliding = stores.filter((store) => store.ownerDir === first || store.ownerDir === second);
+    assert.equal(colliding.length, 2);
+    for (const store of colliding) {
+        assert.equal(store.mountStatus, 'invalid');
+        assert.equal(store.mountFailure, 'collision');
+        assert.equal(store.namespace, 'acme/my-notes');
+        assert.match(store.diagnostic ?? '', /My Notes/);
+        assert.match(store.diagnostic ?? '', /my-notes/);
+    }
+});
+test('profile presence and order do not change a nested store canonical name', () => {
+    const repository = join(process.env.HOME, 'repository');
+    const nested = join(repository, 'packages', 'agent');
+    const unrelated = join(process.env.HOME, 'unrelated');
+    initGit(repository);
+    writeStore(repository, 'acme');
+    writeStore(nested);
+    writeDoc(join(nested, '.crouter', 'memory', 'guide.md'), 'NESTED GUIDE');
+    mkdirSync(unrelated, { recursive: true });
+    const absent = resolveMemoryDocForTarget('acme/packages/agent/guide', target(nested), { scope: 'project' });
+    const rootSecond = createProfile('root-second', [
+        { path: unrelated, memory: 'content' },
+        { path: repository, memory: 'content' },
+    ]).profileId;
+    const rootFirst = createProfile('root-first', [
+        { path: repository, memory: 'content' },
+        { path: unrelated, memory: 'content' },
+    ]).profileId;
+    const withRootSecond = resolveMemoryDocForTarget('acme/packages/agent/guide', target(nested, rootSecond), { scope: 'project' });
+    const withRootFirst = resolveMemoryDocForTarget('acme/packages/agent/guide', target(nested, rootFirst), { scope: 'project' });
+    assert.equal(absent.name, 'acme/packages/agent/guide');
+    assert.equal(withRootSecond.name, absent.name);
+    assert.equal(withRootFirst.name, absent.name);
+    assert.equal(withRootSecond.path, absent.path);
+    assert.equal(withRootFirst.path, absent.path);
+});

package/dist/core/__tests__/seam/memory-slash-node-relative-inventory.test.js

@@ -1,5 +1,5 @@
 import assert from 'node:assert/strict';
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -9,7 +9,9 @@ import { loadedCommandPreview } from '../../../clients/attach/slash/prompt-previ
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), '../../../..');
 const EXTENSION = join(ROOT, 'dist/builtin-pi-packages/pi-crtr-extensions/extensions/memory-slash-commands.ts');
 const LIVE_PROBE = join(ROOT, 'dist/core/__tests__/fixtures/memory-slash-live-probe.js');
-const COMMAND_NAMES = ['acceptance-context-token', 'acceptance-node-token', 'acceptance-independent'];
+const COMMAND_LOCALS = ['acceptance-context-token', 'acceptance-node-token', 'acceptance-independent'];
+const PROJECT_NAMESPACE = 'workspace';
+const COMMAND_NAMES = COMMAND_LOCALS.map((name) => `${PROJECT_NAMESPACE}:workspace:${name}`);
 function writeSlashDoc(memoryDir, name, description, body) {
     writeFileSync(join(memoryDir, `${name}.md`), `---\nkind: knowledge\nwhen-and-why-to-read: Acceptance fixture.\nshort-form: ${description}\nslash: true\n---\n${body}`);
 }
@@ -60,15 +62,19 @@ function fixtureRows(rows) {
         return row;
     });
 }
-test('node-relative memory slash commands omit preview metadata without changing live sends', async () => {
-    const cwd = mkdtempSync(join(tmpdir(), 'crtr-memory-slash-inventory-'));
-    const home = join(cwd, 'canvas');
+test('node-relative memory slash commands omit preview metadata and register invoked bodies at content', async () => {
+    const repositoryRoot = mkdtempSync(join(tmpdir(), 'crtr-memory-slash-inventory-'));
+    const cwd = join(repositoryRoot, 'workspace');
+    const home = join(repositoryRoot, 'canvas');
     const memoryDir = join(cwd, '.crouter', 'memory');
+    const repositoryMemory = join(repositoryRoot, '.crouter', 'memory');
     const nodeId = 'acceptance-live-node';
     mkdirSync(memoryDir, { recursive: true });
-    writeSlashDoc(memoryDir, COMMAND_NAMES[0], 'Context-relative fixture.', 'Store $ARGUMENTS in $CRTR_CONTEXT_DIR/result.md.\n');
-    writeSlashDoc(memoryDir, COMMAND_NAMES[1], 'Node-relative fixture.', 'Node $CRTR_NODE_ID received $ARGUMENTS.\n');
-    writeSlashDoc(memoryDir, COMMAND_NAMES[2], 'Node-independent fixture.', 'Independent payload: $ARGUMENTS.\n');
+    mkdirSync(repositoryMemory, { recursive: true });
+    writeFileSync(join(repositoryMemory, 'INDEX.md'), `---\nnamespace: ${PROJECT_NAMESPACE}\n---\nWorkspace front door.\n`);
+    writeSlashDoc(memoryDir, COMMAND_LOCALS[0], 'Context-relative fixture.', 'Store $ARGUMENTS in $CRTR_CONTEXT_DIR/result.md.\n');
+    writeSlashDoc(memoryDir, COMMAND_LOCALS[1], 'Node-relative fixture.', 'Node $CRTR_NODE_ID received $ARGUMENTS.\n');
+    writeSlashDoc(memoryDir, COMMAND_LOCALS[2], 'Node-independent fixture.', 'Independent payload: $ARGUMENTS.\n');
     try {
         const live = await liveProbe({
             cwd,
@@ -83,6 +89,9 @@ test('node-relative memory slash commands omit preview metadata without changing
         const prospectiveRows = fixtureRows(live.prospective.commands);
         const liveRows = fixtureRows(live.commands);
         assert.deepEqual(liveRows, prospectiveRows);
+        for (const local of COMMAND_LOCALS) {
+            assert.equal(live.commands.some((row) => row.name === local), false, `/${local} is not retained as an old command`);
+        }
         assert.deepEqual(prospectiveRows, [
             { name: COMMAND_NAMES[0], description: 'Context-relative fixture.', source: 'command' },
             { name: COMMAND_NAMES[1], description: 'Node-relative fixture.', source: 'command' },
@@ -101,8 +110,9 @@ test('node-relative memory slash commands omit preview metadata without changing
         assert.ok(insightsInit, 'Gateway completion includes /insights:init');
         assert.equal(insightsInit.expansion, undefined);
         assert.equal(loadedCommandPreview('/insights:init agent-facing CLI', live.commands), undefined);
-        assert.equal(loadedCommandPreview('/acceptance-independent first evidence', live.commands)?.content, 'Independent payload: first evidence.\n');
-        assert.equal(loadedCommandPreview('/acceptance-independent changed evidence', live.commands)?.content, 'Independent payload: changed evidence.\n');
+        assert.equal(loadedCommandPreview(`/${COMMAND_NAMES[2]} first evidence`, live.commands)?.content, 'Independent payload: first evidence.\n');
+        assert.equal(loadedCommandPreview(`/${COMMAND_NAMES[2]} changed evidence`, live.commands)?.content, 'Independent payload: changed evidence.\n');
+        assert.equal(loadedCommandPreview('/acceptance-independent first evidence', live.commands), undefined);
         assert.deepEqual(live.notifications, []);
         const sentContent = Object.fromEntries(live.sent.map((send) => [send.name, send.message.content]));
         assert.deepEqual(sentContent, {
@@ -120,8 +130,14 @@ test('node-relative memory slash commands omit preview metadata without changing
         }
         assert.doesNotMatch(sentContent[COMMAND_NAMES[0]], /\$CRTR_CONTEXT_DIR|\$CRTR_NODE_ID/);
         assert.doesNotMatch(sentContent[COMMAND_NAMES[1]], /\$CRTR_CONTEXT_DIR|\$CRTR_NODE_ID/);
+        const persisted = JSON.parse(readFileSync(join(home, 'nodes', nodeId, 'injected-docs.json'), 'utf8'));
+        assert.equal(persisted.v, 3);
+        for (const name of COMMAND_LOCALS) {
+            const path = realpathSync(join(memoryDir, `${name}.md`));
+            assert.deepEqual(persisted.exposures[path], { transcript: 3 }, `/${name} registers the invoked document body as transcript content`);
+        }
     }
     finally {
-        rmSync(cwd, { recursive: true, force: true });
+        rmSync(repositoryRoot, { recursive: true, force: true });
     }
 });

package/dist/core/__tests__/warm-claim-preference-snapshot.test.d.ts

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

package/dist/core/__tests__/warm-claim-preference-snapshot.test.js

@@ -0,0 +1,40 @@
+// The warm-pool claim must leave a FROZEN preference snapshot behind.
+//
+// A spare boots with no claimant, so canvas-context-intro skips it and
+// canvas-doc-substrate's before_agent_start is the only other freezer — and Pi
+// emits that event on the typed-prompt path only. A claimed spare whose first
+// turn is a slash command (`sendMessage({ triggerTurn: true })`) therefore
+// reached the persona gate with no snapshot and died with "context preference
+// snapshot is missing". Claim time is where the snapshot is frozen.
+//
+// Run: node --import tsx/esm --test src/core/__tests__/warm-claim-preference-snapshot.test.ts
+import { test, before, beforeEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { closeDb } from '../canvas/db.js';
+import { spawnNode } from '../runtime/nodes.js';
+import { deliverBearingsLive } from '../runtime/deliver-live.js';
+import { loadContextExposureState } from '../substrate/injected-store.js';
+let home;
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-warm-snapshot-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    mkdirSync(home, { recursive: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+test('the claim path persists a frozen preference snapshot', async () => {
+    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
+    assert.equal(loadContextExposureState(meta.node_id).preferenceSnapshot, null, 'a spare mints with nothing frozen');
+    await deliverBearingsLive(meta.node_id);
+    assert.notEqual(loadContextExposureState(meta.node_id).preferenceSnapshot, null, 'claim freezes the snapshot the persona gate requires');
+});

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

@@ -5,6 +5,9 @@ export declare function createNode(meta: NodeMeta): NodeMeta;
 /** The canonical node record: durable identity (meta.json) ∪ authoritative
  *  runtime (the row). Null if unknown. */
 export declare function getNode(nodeId: string): NodeMeta | null;
+export declare function canonicalSessionFile(sessionFile: string): string;
+/** Resolve the crouter node that owns one exact Pi session file. */
+export declare function findNodeBySessionFile(sessionFile: string): NodeMeta | null;
 /** The indexed row (from the db) — cheap for queries that don't need full meta. */
 export declare function getRow(nodeId: string): NodeRow | null;
 /** The node row whose durable LOCATION pane is `pane`, or null. Lets placement

package/dist/core/canvas/canvas.js

@@ -4,8 +4,8 @@
 // Source-of-truth split: a node's meta.json is canonical for its own fields;
 // the db row is a queryable index re-derivable from it. The subscribes_to edges
 // are db-authoritative (mutable, many-writers — what WAL is for).
-import { existsSync, readFileSync, readdirSync, rmSync, statSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, readFileSync, readdirSync, realpathSync, rmSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
 import { openDb, withCanvasWrite } from './db.js';
 import { withMetaLock, readMetaObject, writeMetaObjectLocked, writeJsonFileDurably } from './meta-file.js';
 import { isPidAlive, recordedPidLiveness, capturePidIdentities, identitiesMatch, isLegacyTicksIdentity, isBootScopedIdentity, } from './pid.js';
@@ -22,7 +22,7 @@ import { ensureHome, ensureNodeDirs, nodeMetaPath, nodeDir, nodesRoot, jobDir, }
  *  can ever leak onto disk even when a fully-hydrated NodeMeta is handed in. */
 const IDENTITY_KEYS = [
     'node_id', 'name', 'description', 'icon', 'cycles', 'created', 'cwd', 'host_kind', 'profile_id', 'kind', 'mode',
-    'lifecycle', 'persona_ack', 'parent', 'spawned_by', 'fork_from', 'review_binding', 'passive_default', 'pi_session_id',
+    'lifecycle', 'persona_ack', 'parent', 'spawned_by', 'fork_from', 'fork_source_file', 'review_binding', 'passive_default', 'pi_session_id',
     'pi_session_file', 'cycle_pending', 'model_override',
     'launch', 'managed_worktree',
 ];
@@ -33,6 +33,10 @@ function toIdentity(m) {
         if (m[k] !== undefined)
             out[k] = m[k];
     }
+    for (const key of ['pi_session_file', 'fork_source_file']) {
+        if (typeof out[key] === 'string')
+            out[key] = canonicalSessionFile(out[key]);
+    }
     return out;
 }
 function readMeta(nodeId) {
@@ -83,13 +87,14 @@ function writeMeta(meta) {
  *  state. A fresh insert takes the schema defaults for runtime. */
 function upsertRow(meta) {
     openDb()
-        .prepare(`INSERT INTO nodes (node_id, name, kind, mode, lifecycle, cwd, host_kind, profile_id, parent, created)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        .prepare(`INSERT INTO nodes (node_id, name, kind, mode, lifecycle, cwd, host_kind, profile_id, parent, created, pi_session_file)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
        ON CONFLICT(node_id) DO UPDATE SET
          name=excluded.name, kind=excluded.kind, mode=excluded.mode,
          lifecycle=excluded.lifecycle, cwd=excluded.cwd, host_kind=excluded.host_kind,
-         profile_id=excluded.profile_id, parent=excluded.parent`)
-        .run(meta.node_id, meta.name, meta.kind, meta.mode, meta.lifecycle, meta.cwd, meta.host_kind ?? null, meta.profile_id ?? null, meta.parent ?? null, meta.created);
+         profile_id=excluded.profile_id, parent=excluded.parent,
+         pi_session_file=excluded.pi_session_file`)
+        .run(meta.node_id, meta.name, meta.kind, meta.mode, meta.lifecycle, meta.cwd, meta.host_kind ?? null, meta.profile_id ?? null, meta.parent ?? null, meta.created, typeof meta.pi_session_file === 'string' ? canonicalSessionFile(meta.pi_session_file) : null);
 }
 /** Seed a node's row at BIRTH: identity columns + runtime columns taken from the
  *  incoming meta (defaults: status='active', the rest null). The only writer
@@ -98,18 +103,19 @@ function upsertRow(meta) {
 function seedRow(meta) {
     openDb()
         .prepare(`INSERT INTO nodes
-         (node_id, name, kind, mode, lifecycle, cwd, host_kind, profile_id, parent, created,
+         (node_id, name, kind, mode, lifecycle, cwd, host_kind, profile_id, parent, created, pi_session_file,
           status, intent, waiting_for, final_report, finalized_at, pi_pid, "window", tmux_session, pane)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
        ON CONFLICT(node_id) DO UPDATE SET
          name=excluded.name, kind=excluded.kind, mode=excluded.mode,
          lifecycle=excluded.lifecycle, cwd=excluded.cwd, host_kind=excluded.host_kind,
          profile_id=excluded.profile_id, parent=excluded.parent,
+         pi_session_file=excluded.pi_session_file,
          status=excluded.status, intent=excluded.intent, waiting_for=excluded.waiting_for,
          final_report=excluded.final_report, finalized_at=excluded.finalized_at,
          pi_pid=excluded.pi_pid, "window"=excluded."window", tmux_session=excluded.tmux_session,
          pane=excluded.pane`)
-        .run(meta.node_id, meta.name, meta.kind, meta.mode, meta.lifecycle, meta.cwd, meta.host_kind ?? null, meta.profile_id ?? null, meta.parent ?? null, meta.created, meta.status ?? 'active', meta.intent ?? null, meta.waiting_for ?? null, meta.final_report ?? null, meta.finalized_at ?? null, meta.pi_pid ?? null, meta.window ?? null, meta.tmux_session ?? null, meta.pane ?? null);
+        .run(meta.node_id, meta.name, meta.kind, meta.mode, meta.lifecycle, meta.cwd, meta.host_kind ?? null, meta.profile_id ?? null, meta.parent ?? null, meta.created, typeof meta.pi_session_file === 'string' ? canonicalSessionFile(meta.pi_session_file) : null, meta.status ?? 'active', meta.intent ?? null, meta.waiting_for ?? null, meta.final_report ?? null, meta.finalized_at ?? null, meta.pi_pid ?? null, meta.window ?? null, meta.tmux_session ?? null, meta.pane ?? null);
 }
 function rowFrom(r) {
     return {
@@ -179,6 +185,20 @@ export function getNode(nodeId) {
     // exists yet (rare — pre-rebuild), keep whatever the meta carried.
     return { ...ident, ...(rt ?? {}) };
 }
+export function canonicalSessionFile(sessionFile) {
+    const absolute = resolve(sessionFile);
+    return existsSync(absolute) ? realpathSync(absolute) : absolute;
+}
+/** Resolve the crouter node that owns one exact Pi session file. */
+export function findNodeBySessionFile(sessionFile) {
+    const canonical = canonicalSessionFile(sessionFile);
+    const matches = openDb()
+        .prepare('SELECT node_id FROM nodes WHERE pi_session_file = ? ORDER BY created')
+        .all(canonical);
+    if (matches.length > 1)
+        throw new Error(`multiple nodes own pi session file: ${canonical}`);
+    return matches[0] === undefined ? null : getNode(matches[0].node_id);
+}
 /** The indexed row (from the db) — cheap for queries that don't need full meta. */
 export function getRow(nodeId) {
     const r = openDb()

package/dist/core/canvas/db.js

@@ -1175,6 +1175,27 @@ CREATE TABLE human_action_deliveries (
 CREATE INDEX idx_human_action_deliveries_due ON human_action_deliveries(state, next_attempt_at);
 `);
 }
+/** v34 — index the exact Pi session file coordinate used to recover fork
+ * exposure provenance without hydrating every node meta. Meta remains authoritative;
+ * normal identity upserts keep this projection current after the one-time backfill. */
+function addNodeSessionFileIndex(db) {
+    const columns = nodeColumns(db);
+    addNodeColumnIfMissing(db, columns, 'pi_session_file', 'ALTER TABLE nodes ADD COLUMN pi_session_file TEXT;');
+    for (const entry of readdirSync(nodesRoot(), { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        try {
+            const meta = JSON.parse(readFileSync(nodeMetaPath(entry.name), 'utf8'));
+            if (typeof meta.pi_session_file === 'string') {
+                db.prepare('UPDATE nodes SET pi_session_file = ? WHERE node_id = ?').run(meta.pi_session_file, entry.name);
+            }
+        }
+        catch {
+            // Corrupt node metadata is ignored by the ordinary canvas rebuild too.
+        }
+    }
+    db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_pi_session_file ON nodes(pi_session_file);');
+}
 /** 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). */
@@ -1221,6 +1242,7 @@ export const MIGRATIONS = [
     /* v31 */ addReviewSubmitRequested,
     /* v32 */ addCronHeldColumns,
     /* v33 */ addHumanActionDeliveries,
+    /* v34 */ addNodeSessionFileIndex,
     ...JOURNALED_STATE_MIGRATIONS,
 ];
 /** Migration indexes that manage their OWN transaction and therefore must not
@@ -1348,11 +1370,16 @@ export function openDb() {
     ensureHome();
     recordOpenLedger();
     const db = new DatabaseSync(path);
+    // FIRST, before any pragma that can contend. `journal_mode = WAL` takes a
+    // brief exclusive lock, so on the default zero busy_timeout a cold open that
+    // races a concurrent writer throws `database is locked` outright — crtrd, a
+    // CLI child and a broker all open this same file, and every one of them opens
+    // it cold. Setting the wait window first makes that open wait its turn.
+    db.exec('PRAGMA busy_timeout = 5000;');
     db.exec('PRAGMA journal_mode = WAL;');
     // Load-bearing as of migration v4: the edges→nodes FK (ON DELETE CASCADE)
     // needs this ON at the deleting connection so a node delete reaps its edges.
     db.exec('PRAGMA foreign_keys = ON;');
-    db.exec('PRAGMA busy_timeout = 5000;');
     migrate(db);
     handles.set(path, db);
     return db;

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

@@ -10,6 +10,8 @@ export declare function crtrHome(): string;
  *  local disk — so the db shares the node data's location and survives a
  *  sandbox recreate together with `nodes/`. */
 export declare function canvasDbPath(): string;
+export declare function onDiskMigrationLockPath(): string;
+export declare function onDiskMigrationMarkerPath(): string;
 /** Absolute path to a node's broker `view.sock` — always `view.sock` under the
  *  node dir. Stale socket files (a host reboot, a sandbox recreate on a
  *  durable volume) are harmless: the broker unlinks any existing socket before
@@ -73,12 +75,8 @@ export declare function situationalContextPath(nodeId: string): string;
 export declare function passivePath(nodeId: string): string;
 export declare function transcriptPath(nodeId: string): string;
 export declare function sessionPtrPath(nodeId: string): string;
-/** On-read injection dedup set — the doc realpaths already surfaced on-read in
- *  this node's CURRENT conversation transcript. Persisted so the once-per-
- *  transcript dedup survives a dormancy → revive(resume) cycle: a resume reuses
- *  the same .jsonl transcript in a NEW pi process, so the in-memory set would
- *  otherwise start empty and re-inject docs already present in the transcript.
- *  Deleted by the launch paths that start a FRESH transcript. */
+/** Frozen preference snapshot and rank-aware exposure state for the node's
+ * currently loaded LLM context. The filename remains stable across schema versions. */
 export declare function injectedDocsPath(nodeId: string): string;
 /** Create the full directory skeleton for a node. Idempotent. */
 export declare function ensureNodeDirs(nodeId: string): void;

package/dist/core/canvas/paths.js

@@ -36,6 +36,12 @@ export function crtrHome() {
 export function canvasDbPath() {
     return join(crtrHome(), 'canvas.db');
 }
+export function onDiskMigrationLockPath() {
+    return join(crtrHome(), 'on-disk-migration.lock');
+}
+export function onDiskMigrationMarkerPath() {
+    return join(crtrHome(), 'on-disk-migrations.json');
+}
 /** Absolute path to a node's broker `view.sock` — always `view.sock` under the
  *  node dir. Stale socket files (a host reboot, a sandbox recreate on a
  *  durable volume) are harmless: the broker unlinks any existing socket before
@@ -159,12 +165,8 @@ export function transcriptPath(nodeId) {
 export function sessionPtrPath(nodeId) {
     return join(nodeDir(nodeId), 'session.ptr');
 }
-/** On-read injection dedup set — the doc realpaths already surfaced on-read in
- *  this node's CURRENT conversation transcript. Persisted so the once-per-
- *  transcript dedup survives a dormancy → revive(resume) cycle: a resume reuses
- *  the same .jsonl transcript in a NEW pi process, so the in-memory set would
- *  otherwise start empty and re-inject docs already present in the transcript.
- *  Deleted by the launch paths that start a FRESH transcript. */
+/** Frozen preference snapshot and rank-aware exposure state for the node's
+ * currently loaded LLM context. The filename remains stable across schema versions. */
 export function injectedDocsPath(nodeId) {
     return join(nodeDir(nodeId), 'injected-docs.json');
 }

package/dist/core/canvas/render-source.js

@@ -20,7 +20,7 @@ import { jobDir, contextDir } from './paths.js';
 import { isPidAlive } from './pid.js';
 import { resolveNodeVisual, faultSummary } from './status-glyph.js';
 import { readFault } from '../runtime/fault.js';
-import { isLegacyRuntimeText, parseCard } from '../../shared/generated-context.js';
+import { parseCard } from '../../shared/generated-context.js';
 // ---------------------------------------------------------------------------
 // Active-fault overlay: stale daemon-owned provider faults are hidden once the
 // broker pid is gone; manual/client faults stay visible until cleared.
@@ -192,7 +192,7 @@ export function readSessionParts(sessionFile) {
         const text = extractUserText(rec.message.content);
         if (text === '')
             continue;
-        if (parseCard({ role: 'user', content: text }) !== null || isLegacyRuntimeText(text))
+        if (parseCard({ role: 'user', content: text }) !== null)
             continue;
         const capped = text.length > CONVO_MSG_CAP ? text.slice(0, CONVO_MSG_CAP) : text;
         parts.push(capped);

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

@@ -113,13 +113,13 @@ export interface NodeIdentity {
     kind: string;
     mode: Mode;
     lifecycle: Lifecycle;
-    /** The last persona state {mode,lifecycle} the node was GIVEN transition
-     *  guidance for. Meta-only (not a db column). Born equal to the node's initial
-     *  {mode,lifecycle} at spawn so a fresh node never gets spurious guidance. The
-     *  persona injector (runtime/persona.ts) compares the live {mode,lifecycle}
-     *  against this and, on drift, injects guidance for the new state then commits
-     *  it here. */
+    /** The last {kind,mode,lifecycle} whose context delivery was acknowledged.
+     *  Meta-only (not a db column). Born equal to the initial persona; later
+     *  changes advance only after a baseline or provider-gated transition is
+     *  durably registered. Historical rows may omit `kind`; reads resolve it to
+     *  the current kind so they do not fabricate a transition. */
     persona_ack?: {
+        kind?: string;
         mode: Mode;
         lifecycle: Lifecycle;
     };
@@ -130,14 +130,10 @@ export interface NodeIdentity {
      *  `parent` so an INDEPENDENT root (parent=null) still records its lineage.
      *  Audit only; null for a user-opened root. Defaults to `parent` for a child. */
     spawned_by?: string | null;
-    /** Fork provenance — the `--fork-from` source this node was forked from at
-     *  spawn (the node id / session path / pi session uuid the caller passed). pi
-     *  COPIED that conversation into this node's first session, so the node boots
-     *  carrying the SOURCE's first-person history. Persisted here so the boot
-     *  intro can assert this node's OWN identity over that inherited narrative
-     *  (without it a fork impersonates its source). Undefined for a fresh node;
-     *  identity/audit only. */
+    /** Raw `--fork-from` operand retained for identity framing and audit. */
     fork_from?: string | null;
+    /** Resolved absolute source session file used for every pre-bind fork retry. */
+    fork_source_file?: string | null;
     /** Immutable review-companion binding. Undefined for ordinary nodes. */
     review_binding?: ReviewBinding | null;
     /** New subscriptions this node opens default to passive when true. */

package/dist/core/exclusive-lock.d.ts

@@ -12,3 +12,5 @@ export interface ExclusiveLockOptions {
  * however long its operation runs.
  */
 export declare function withExclusiveDirectoryLock<T>(path: string, operation: () => T, options?: ExclusiveLockOptions): T;
+/** Run an awaited operation under the same token-checked directory lock. */
+export declare function withExclusiveDirectoryLockAsync<T>(path: string, operation: () => Promise<T>, options?: ExclusiveLockOptions): Promise<T>;