@north-light/crouter 0.3.226 → 0.3.228

package/dist/pi-extensions/__tests__/canvas-context-intro.test.js

@@ -1,21 +1,28 @@
 // Run with: node --import tsx/esm --test src/pi-extensions/__tests__/canvas-context-intro.test.ts
 //
-// A forked crouter branch receives a compact node-scoped update after its
-// inherited baseline, and a resume re-injects nothing — idempotency keyed on
-// the exact node-id stamp, independent of the bearings text.
+// A forked crouter branch receives compact node bearings only with persisted
+// transcript provenance. Persona drift is delivered at the provider gate.
 import { test, before, after, beforeEach, afterEach } from 'node:test';
 import assert from 'node:assert/strict';
-import { existsSync, mkdtempSync, mkdirSync, rmSync } from 'node:fs';
+import { existsSync, mkdtempSync, mkdirSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { registerCanvasContextIntro, CONTEXT_INTRO_CUSTOM_TYPE, } from '../canvas-context-intro.js';
+import { registerCanvasDocSubstrate } from '../canvas-doc-substrate.js';
 import { buildContextBearings as buildContextIntro } from '../../core/runtime/bearings.js';
-import { createNode } from '../../core/canvas/canvas.js';
+import { installPersonaTransitionGate } from '../../core/runtime/broker-persona-guidance.js';
+import { createNode, deleteNode, getNode, updateNode } from '../../core/canvas/canvas.js';
 import { apiSocketPath } from '../../core/canvas/paths.js';
 import { createApiServer } from '../../daemon/api/server.js';
 import { closeDb } from '../../core/canvas/db.js';
+import { resetScopeCache } from '../../core/scope.js';
+import { clearSessionCache } from '../../core/substrate/session-cache.js';
+import { emptyContextExposureState, exposureTarget, initializeForkContextExposure, loadContextExposureState, registerExposure, saveContextExposureState, } from '../../core/substrate/injected-store.js';
 let home;
+let origCwd;
+let origHome;
 let origNode;
+let origProfile;
 let server;
 async function waitForSocket(path) {
     for (let i = 0; i < 200; i++) {
@@ -45,6 +52,7 @@ function introEntry(content) {
 }
 function makeFakePi() {
     let handler;
+    let branch = [];
     return {
         sent: [],
         on(event, h) {
@@ -53,41 +61,74 @@ function makeFakePi() {
         },
         sendMessage(m) {
             this.sent.push(m);
+            branch.push({ type: 'custom_message', ...m });
         },
         registerMessageRenderer() {
             /* display-only; irrelevant here */
         },
-        async fireSessionStart(entries) {
-            await handler?.(undefined, { sessionManager: { getEntries: () => entries } });
+        async fireSessionStart(entries, reason) {
+            branch = entries;
+            await handler?.({ reason }, {
+                sessionManager: {
+                    getEntries: () => branch,
+                    getBranch: () => branch,
+                },
+            });
         },
     };
 }
 before(() => {
+    origCwd = process.cwd();
+    origHome = process.env['HOME'];
     origNode = process.env['CRTR_NODE_ID'];
+    origProfile = process.env['CRTR_PROFILE_ID'];
 });
 beforeEach(async () => {
     closeDb();
     if (home)
         rmSync(home, { recursive: true, force: true });
     home = mkdtempSync(join(tmpdir(), 'crtr-context-intro-'));
+    const userHome = join(home, 'user');
+    const cwd = join(userHome, 'work');
+    mkdirSync(cwd, { recursive: true });
+    process.chdir(cwd);
+    process.env['HOME'] = userHome;
     process.env['CRTR_HOME'] = home;
     delete process.env['CRTR_NODE_ID'];
-    mkdirSync(home, { recursive: true });
+    delete process.env['CRTR_PROFILE_ID'];
+    resetScopeCache();
+    clearSessionCache();
     server = createApiServer();
     await waitForSocket(apiSocketPath());
 });
 afterEach(async () => {
-    await server.close();
+    try {
+        await server.close();
+    }
+    finally {
+        process.chdir(origCwd);
+    }
 });
 after(() => {
+    process.chdir(origCwd);
     closeDb();
     if (home)
         rmSync(home, { recursive: true, force: true });
+    if (origHome === undefined)
+        delete process.env['HOME'];
+    else
+        process.env['HOME'] = origHome;
+    resetScopeCache();
+    clearSessionCache();
     delete process.env['CRTR_HOME'];
     if (origNode === undefined)
         delete process.env['CRTR_NODE_ID'];
     else
         process.env['CRTR_NODE_ID'] = origNode;
+    if (origProfile === undefined)
+        delete process.env['CRTR_PROFILE_ID'];
+    else
+        process.env['CRTR_PROFILE_ID'] = origProfile;
 });
 test('session_start appends compact fork bearings after an inherited source baseline', async () => {
     createNode(node('srcA'));
@@ -95,6 +136,16 @@ test('session_start appends compact fork bearings after an inherited source base
     // A fork boots with the SOURCE's whole conversation copied in — including the
     // source's bearings intro entry (which names srcA, not forkB).
     const inheritedSourceBlock = introEntry(buildContextIntro('srcA'));
+    const sourceExposure = emptyContextExposureState();
+    registerExposure(exposureTarget(sourceExposure, 'system'), 'source-system-only', 'content');
+    registerExposure(exposureTarget(sourceExposure, 'transcript'), 'inherited-source-document', 'content');
+    saveContextExposureState('srcA', sourceExposure);
+    initializeForkContextExposure('forkB', 'srcA');
+    deleteNode('srcA');
+    initializeForkContextExposure('forkB', null);
+    const forkExposure = loadContextExposureState('forkB');
+    assert.deepEqual(forkExposure.exposures.get('inherited-source-document'), { transcript: 3 }, 'a pre-bind retry preserves the transcript exposure seed after its source disappears');
+    assert.equal(forkExposure.exposures.has('source-system-only'), false, 'a fork never inherits source system exposure');
     process.env['CRTR_NODE_ID'] = 'forkB';
     const pi = makeFakePi();
     registerCanvasContextIntro(pi);
@@ -104,15 +155,172 @@ test('session_start appends compact fork bearings after an inherited source base
     assert.equal(pi.sent[0].customType, CONTEXT_INTRO_CUSTOM_TYPE);
     assert.match(pi.sent[0].content, /You are node forkB/, 'injected bearings name the fork, not the source');
     assert.match(pi.sent[0].content, /new FORK of srcA/, 'injected bearings carry the fork callout');
-    assert.doesNotMatch(pi.sent[0].content, /<project_context>/, 'the full source baseline is not repeated');
+    assert.doesNotMatch(pi.sent[0].content, /<project_context>/, 'inherited crouter bearings stay compact even after the source row is gone');
     assert.equal(pi.sent[0].details?.nodeId, 'forkB', 'the compact update carries the fork node stamp');
-    // A non-crouter source has no inherited baseline, so its fork receives one.
-    createNode(node('externalF', { fork_from: '/tmp/external-session.jsonl' }));
-    process.env['CRTR_NODE_ID'] = 'externalF';
-    const externalPi = makeFakePi();
-    registerCanvasContextIntro(externalPi);
-    await externalPi.fireSessionStart([]);
-    assert.match(externalPi.sent[0].content, /<project_context>/, 'an external-session fork receives the full baseline');
+    // An inherited crouter block without a recoverable transcript seed cannot
+    // prove what that branch contains, so the destination starts from scratch.
+    createNode(node('unknownF', { fork_from: '/tmp/unknown-session.jsonl' }));
+    const unknownPreState = loadContextExposureState('unknownF');
+    assert.equal(unknownPreState.exposures.size, 0);
+    assert.equal(unknownPreState.preferenceSnapshot, null);
+    process.env['CRTR_NODE_ID'] = 'unknownF';
+    const unknownPi = makeFakePi();
+    registerCanvasContextIntro(unknownPi);
+    await unknownPi.fireSessionStart([inheritedSourceBlock]);
+    assert.match(unknownPi.sent[0].content, /<project_context>/, 'unknown inherited provenance receives the full baseline');
+});
+test('root /new leaves baseline assembly to the replacement broker', async () => {
+    const oldPersona = { kind: 'general', mode: 'base', lifecycle: 'resident' };
+    createNode(node('root-new', {
+        parent: null,
+        kind: 'developer',
+        lifecycle: 'resident',
+        persona_ack: oldPersona,
+    }));
+    const exposure = emptyContextExposureState();
+    exposure.preferenceSnapshot = 'ORIGINAL-SNAPSHOT';
+    registerExposure(exposureTarget(exposure, 'transcript'), 'original-transcript', 'content');
+    saveContextExposureState('root-new', exposure);
+    process.env['CRTR_NODE_ID'] = 'root-new';
+    const pi = makeFakePi();
+    registerCanvasContextIntro(pi);
+    await pi.fireSessionStart([], 'new');
+    assert.equal(pi.sent.length, 0, 'the provisional in-process branch receives no baseline');
+    assert.equal(loadContextExposureState('root-new').preferenceSnapshot, 'ORIGINAL-SNAPSHOT');
+    assert.deepEqual(getNode('root-new')?.persona_ack, oldPersona, 'the replacement launch still owns the pending transition');
+});
+test('child /new commits its baseline before ack and the provider gate delivers strict-resume drift', async () => {
+    const previousProfile = process.env['CRTR_PROFILE_ID'];
+    const userHome = join(home, 'user');
+    const cwd = join(userHome, 'work');
+    const userMemory = join(userHome, '.crouter', 'memory');
+    const projectMemory = join(cwd, '.crouter', 'memory');
+    mkdirSync(userMemory, { recursive: true });
+    mkdirSync(projectMemory, { recursive: true });
+    const preferencePath = join(userMemory, 'new-context-preference.md');
+    const knowledgePath = join(userMemory, 'new-context-knowledge.md');
+    const workspacePath = join(projectMemory, 'INDEX.md');
+    const transitionPath = join(userMemory, 'developer-transition.md');
+    writeFileSync(preferencePath, '---\nkind: preference\nwhen-and-why-to-read: New context preference.\nsurfaces:\n  - {on: boot, at: content}\n---\nSYSTEM-PREFERENCE-NEW-CONTEXT\n');
+    writeFileSync(knowledgePath, '---\nkind: knowledge\nwhen-and-why-to-read: New context knowledge.\nsurfaces:\n  - {on: boot, at: content}\n---\nBEARINGS-KNOWLEDGE-NEW-CONTEXT\n');
+    writeFileSync(workspacePath, '---\nnamespace: new-context-workspace\nkind: knowledge\nwhen-and-why-to-read: New context workspace.\nsurfaces:\n  - {on: workspace-open, at: content}\n---\nBEARINGS-WORKSPACE-NEW-CONTEXT\n');
+    writeFileSync(transitionPath, '---\nkind: knowledge\nwhen-and-why-to-read: Developer transition knowledge.\ngate: {kind: developer}\nsurfaces:\n  - {on: boot, at: content}\n---\nSTRICT-RESUME-DEVELOPER-DELTA\n');
+    delete process.env['CRTR_PROFILE_ID'];
+    resetScopeCache();
+    clearSessionCache();
+    try {
+        createNode(node('new-parent', { cwd, lifecycle: 'resident' }));
+        const oldPersona = { kind: 'general', mode: 'base', lifecycle: 'terminal' };
+        const currentPersona = { kind: 'review', mode: 'base', lifecycle: 'terminal' };
+        createNode(node('new-child', {
+            cwd,
+            parent: 'new-parent',
+            kind: currentPersona.kind,
+            persona_ack: oldPersona,
+        }));
+        mkdirSync(join(home, 'nodes', 'new-child'), { recursive: true });
+        process.env['CRTR_NODE_ID'] = 'new-child';
+        const sessionStartHandlers = [];
+        const sent = [];
+        const branch = [];
+        let ackWhenBearingsWereSent;
+        const pi = {
+            on(event, handler) {
+                if (event === 'session_start')
+                    sessionStartHandlers.push(handler);
+            },
+            sendMessage(message) {
+                sent.push(message);
+                branch.push({ type: 'custom_message', ...message });
+                if (message.customType === CONTEXT_INTRO_CUSTOM_TYPE) {
+                    ackWhenBearingsWereSent = getNode('new-child')?.persona_ack;
+                }
+            },
+            registerMessageRenderer() { },
+        };
+        registerCanvasContextIntro(pi);
+        registerCanvasDocSubstrate(pi);
+        const ctx = { sessionManager: { getEntries: () => branch, getBranch: () => branch } };
+        for (const handler of sessionStartHandlers)
+            await handler({ reason: 'new' }, ctx);
+        assert.equal(sent.length, 1, 'the fresh child branch receives one bearings message and no transition delta');
+        assert.match(sent[0].content, /BEARINGS-KNOWLEDGE-NEW-CONTEXT/);
+        assert.match(sent[0].content, /BEARINGS-WORKSPACE-NEW-CONTEXT/);
+        assert.deepEqual(ackWhenBearingsWereSent, oldPersona, 'the old persona remains acknowledged until the baseline is complete');
+        assert.deepEqual(getNode('new-child')?.persona_ack, currentPersona);
+        const state = loadContextExposureState('new-child');
+        assert.match(state.preferenceSnapshot ?? '', /SYSTEM-PREFERENCE-NEW-CONTEXT/);
+        assert.deepEqual(state.exposures.get(realpathSync(preferencePath)), { system: 3 });
+        assert.deepEqual(state.exposures.get(realpathSync(knowledgePath)), { transcript: 3 });
+        assert.deepEqual(state.exposures.get(realpathSync(workspacePath)), { transcript: 3 });
+        assert.equal(state.exposures.has(realpathSync(transitionPath)), false);
+        const frozenSnapshot = state.preferenceSnapshot;
+        updateNode('new-child', { kind: 'developer' });
+        for (const handler of sessionStartHandlers)
+            await handler({ reason: 'startup' }, ctx);
+        assert.equal(sent.length, 1, 'session_start preserves the branch and leaves pending drift to the provider gate');
+        assert.deepEqual(getNode('new-child')?.persona_ack, currentPersona);
+        const order = [];
+        const activeMessages = [];
+        let latestTransformed = [];
+        let mutateDuringAppend = false;
+        const providerSession = {
+            agent: {
+                state: { messages: activeMessages },
+                transformContext: async (messages) => {
+                    order.push('previous-transform');
+                    latestTransformed = [...messages];
+                    return latestTransformed;
+                },
+            },
+            sessionManager: {
+                appendCustomMessageEntry(customType, content, display, details) {
+                    order.push('append-transition');
+                    branch.push({ type: 'custom_message', customType, content, display, details });
+                    if (mutateDuringAppend)
+                        updateNode('new-child', { kind: 'review' });
+                },
+            },
+        };
+        installPersonaTransitionGate('new-child', providerSession);
+        const transformed = await providerSession.agent.transformContext([{ role: 'user', content: 'continue' }]);
+        assert.deepEqual(order, ['previous-transform', 'append-transition'], 'Pi transforms context before crouter appends the transition');
+        assert.equal(branch.at(-1)?.customType, 'crtr-persona-transition');
+        assert.match(branch.at(-1)?.content ?? '', /STRICT-RESUME-DEVELOPER-DELTA/);
+        assert.equal(activeMessages.at(-1)?.['customType'], 'crtr-persona-transition');
+        assert.equal(transformed.at(-1)?.['customType'], 'crtr-persona-transition');
+        assert.deepEqual(getNode('new-child')?.persona_ack, {
+            kind: 'developer',
+            mode: 'base',
+            lifecycle: 'terminal',
+        });
+        const resumedState = loadContextExposureState('new-child');
+        assert.equal(resumedState.preferenceSnapshot, frozenSnapshot, 'strict resume preserves the frozen system snapshot byte-for-byte');
+        assert.deepEqual(resumedState.exposures.get(realpathSync(transitionPath)), { transcript: 3 });
+        updateNode('new-child', { mode: 'orchestrator' });
+        mutateDuringAppend = true;
+        order.length = 0;
+        const branchBeforeRace = branch.length;
+        const activeBeforeRace = activeMessages.length;
+        await providerSession.agent.transformContext([{ role: 'user', content: 'race' }]);
+        assert.deepEqual(order, ['previous-transform', 'append-transition', 'append-transition']);
+        assert.equal(branch.length, branchBeforeRace + 2, 'the stale transition is followed by current guidance');
+        assert.equal(activeMessages.length, activeBeforeRace + 2, 'the active agent transcript keeps both materialized cards');
+        assert.equal(latestTransformed.at(-1)?.['customType'], 'crtr-persona-transition', 'the provider context ends at the current persona');
+        assert.deepEqual(getNode('new-child')?.persona_ack, {
+            kind: 'review',
+            mode: 'orchestrator',
+            lifecycle: 'terminal',
+        }, 'the corrective transition acknowledges the current persona');
+    }
+    finally {
+        resetScopeCache();
+        clearSessionCache();
+        if (previousProfile === undefined)
+            delete process.env['CRTR_PROFILE_ID'];
+        else
+            process.env['CRTR_PROFILE_ID'] = previousProfile;
+    }
 });
 test('resume idempotency uses the exact details stamp independent of block text', async () => {
     createNode(node('stampD'));

package/dist/pi-extensions/__tests__/canvas-goal-capture-envelope.test.js

@@ -62,12 +62,20 @@ async function waitForRequestMentioning(id) {
 before(async () => {
     home = mkdtempSync(join(tmpdir(), 'crtr-goal-capture-'));
     process.env['CRTR_HOME'] = home;
-    // A stub daemon: it records the request and hangs up, so the naming path fails
-    // fast (and silently, as it must) without any model call.
+    // A stub daemon: it records the request and answers a typed error, so the
+    // naming path fails fast (and silently, as it must) without any model call.
+    // It must ANSWER rather than hang up — the api client reads a mid-request
+    // hangup as a daemon handover and rides it out with a 10s /healthz poll,
+    // which kept this process alive for ten seconds after the test had passed.
     socket = createServer((connection) => {
         connection.on('data', (chunk) => {
             requests.push(chunk.toString('utf8'));
-            connection.destroy();
+            const body = JSON.stringify({ error: { code: 'internal', message: 'stub daemon' } });
+            connection.end('HTTP/1.1 500 Internal Server Error\r\n'
+                + 'Content-Type: application/json\r\n'
+                + `Content-Length: ${Buffer.byteLength(body)}\r\n`
+                + 'Connection: close\r\n\r\n'
+                + body);
         });
     });
     await new Promise((resolve) => socket.listen(apiSocketPath(), resolve));

package/dist/pi-extensions/canvas-context-intro.d.ts

@@ -1,5 +1,5 @@
 import { CONTEXT_INTRO_CUSTOM_TYPE } from '../shared/generated-context.js';
-import { type InjectedDocs } from '../core/substrate/injected-store.js';
+import { type ExposureTarget } from '../core/substrate/injected-store.js';
 /** The `customType` stamped on the injected session message. Used both to write
  *  the entry and to detect it on resume (the idempotency guard). Defined beside
  *  the block builder in `core/runtime/bearings.ts` because the warm-pool claim's
@@ -69,7 +69,7 @@ interface PiLike {
 }
 /** Build the full bearings baseline for a conversation without inherited
  *  crouter context. Exported for testing. */
-export declare function buildContextIntro(nodeId: string, seen?: InjectedDocs): Promise<string>;
+export declare function buildContextIntro(nodeId: string, target?: ExposureTarget): Promise<string>;
 /** Build the compact node-scoped update for a fork whose copied branch already
  *  carries a full crouter baseline. Exported for testing. */
 export declare function buildForkContextIntro(nodeId: string): Promise<string>;
@@ -82,8 +82,6 @@ export declare function buildForkContextIntro(nodeId: string): Promise<string>;
 export declare function renderContextMessage(message: RenderedMessageLike, options: {
     expanded?: boolean;
 }, theme: ThemeLike): ComponentLike;
-/** Register the context-intro preamble. Fresh branches receive one full
- *  baseline, forked crouter branches receive one compact update, and resumes
- *  whose active branch already carries this node's stamp receive nothing. */
+/** Register new-context baseline assembly; a strict resume changes nothing. */
 export declare function registerCanvasContextIntro(pi: PiLike): void;
 export default registerCanvasContextIntro;

package/dist/pi-extensions/canvas-context-intro.js

@@ -3,17 +3,13 @@
 // Loaded into every canvas node's pi process via the node's launch.extensions
 // list. INERT when CRTR_NODE_ID is absent (plain pi session or legacy job agent).
 //
-// On `session_start` — before the node's first real user message — this injects
-// one persisted <crtr-context> custom message. A fresh conversation receives the
-// full baseline as its first entry. A fork receives a compact update after the
-// copied history and immediately before its new mandate. The prose lives in
-// core/runtime/bearings.ts.
+// At session_start, before the first response, this assembles the context-owned
+// memory state. A fresh branch receives full bearings, while a copied crouter
+// branch with known transcript provenance receives compact node bearings.
 //
-// BRANCH-AWARE and IDEMPOTENT: the active branch receives one bearings message
-// stamped for this node. A resume finds that stamp and injects nothing. A new
-// cycle has no current-branch stamp and receives a fresh full baseline. A fork
-// whose active branch carries another node's bearings receives only a compact
-// node-scoped update; a fork of a non-crouter session receives the full baseline.
+// The active branch owns the idempotency stamp. A new cycle has no current-node
+// stamp and receives a new baseline. The preference snapshot and persona
+// acknowledgment persist only after Pi materializes that baseline.
 //
 // COLLAPSED BY DEFAULT: a `registerMessageRenderer` keyed to our customType
 // renders the block as a single one-line stub; the full body only appears when
@@ -28,9 +24,11 @@
 // crouter's own tsc build without a dep on the pi packages.
 import { CONTEXT_INTRO_CUSTOM_TYPE, formatCard, parseCard } from '../shared/generated-context.js';
 import { brokerExtensionState } from '../core/runtime/broker/daemon-ops.js';
-import { buildContextBearingsFromState, buildForkBearingsFromState, buildProjectContextBlockForBroker } from '../core/runtime/broker-extension-render.js';
+import { buildContextBearingsFromState, buildForkBearingsFromState, buildProjectContextBlockForBroker, renderPreferencesFromState, } from '../core/runtime/broker-extension-render.js';
+import { acknowledgePersonaBaseline } from '../core/runtime/broker-persona-guidance.js';
 import { situationalContextEnvelope } from '../core/runtime/situational-context.js';
-import { saveInjectedDocs, sharedInjectedDocs } from '../core/substrate/injected-store.js';
+import { clearContextExposureState, cloneTranscriptExposureState, emptyContextExposureState, exposureTarget, freezePreferenceSnapshot, hasTranscriptExposure, loadContextExposureState, replaceContextExposureState, saveContextExposureState, sharedContextExposureState, } from '../core/substrate/injected-store.js';
+import { clearSessionCache } from '../core/substrate/session-cache.js';
 import { truncateToWidth } from './truncate.js';
 /** The `customType` stamped on the injected session message. Used both to write
  *  the entry and to detect it on resume (the idempotency guard). Defined beside
@@ -42,9 +40,9 @@ export { CONTEXT_INTRO_CUSTOM_TYPE };
 // ---------------------------------------------------------------------------
 /** Build the full bearings baseline for a conversation without inherited
  *  crouter context. Exported for testing. */
-export async function buildContextIntro(nodeId, seen) {
+export async function buildContextIntro(nodeId, target) {
     const state = await brokerExtensionState(nodeId);
-    return buildContextBearingsFromState(state, buildProjectContextBlockForBroker(state.node.cwd), situationalContextEnvelope(nodeId) ?? '', seen);
+    return buildContextBearingsFromState(state, buildProjectContextBlockForBroker(state.node.cwd), situationalContextEnvelope(nodeId) ?? '', target);
 }
 /** Build the compact node-scoped update for a fork whose copied branch already
  *  carries a full crouter baseline. Exported for testing. */
@@ -79,6 +77,11 @@ function entryText(e) {
     }
     return '';
 }
+function activeBranch(ctx) {
+    return typeof ctx.sessionManager.getBranch === 'function'
+        ? ctx.sessionManager.getBranch()
+        : ctx.sessionManager.getEntries();
+}
 /** Hard-wrap a single logical line to `width` columns (content carries no ANSI).
  *  Code-point aware so wide-string slicing never splits a surrogate pair; the
  *  bearings prose is plain text, so code-point count == visible columns. */
@@ -127,60 +130,61 @@ export function renderContextMessage(message, options, theme) {
 // ---------------------------------------------------------------------------
 // Extension
 // ---------------------------------------------------------------------------
-/** Register the context-intro preamble. Fresh branches receive one full
- *  baseline, forked crouter branches receive one compact update, and resumes
- *  whose active branch already carries this node's stamp receive nothing. */
+/** Register new-context baseline assembly; a strict resume changes nothing. */
 export function registerCanvasContextIntro(pi) {
     // Collapse the block to a one-liner until the user expands tool output (Ctrl+O).
     // Harmless to register outside TUI mode (it's only consulted while rendering).
     pi.registerMessageRenderer(CONTEXT_INTRO_CUSTOM_TYPE, renderContextMessage);
-    pi.on('session_start', async (_event, ctx) => {
+    pi.on('session_start', async (event, ctx) => {
         const nodeId = process.env['CRTR_NODE_ID'];
         if (nodeId === undefined || nodeId.trim() === '')
             return;
+        const reason = event?.reason;
         // Warm spares have no claimant yet. Their claim path delivers the full
         // baseline after assigning the real persona, profile, and working directory.
-        let state;
-        try {
-            state = await brokerExtensionState(nodeId);
-        }
-        catch {
-            return;
-        }
+        const state = await brokerExtensionState(nodeId);
         if (state.warm_spare)
             return;
+        // A root's in-process /new branch is provisional: stophook has already asked
+        // crtrd to relaunch it. The replacement broker owns the new baseline.
+        if (reason === 'new' && state.node.parent === null)
+            return;
+        if (reason === 'new') {
+            clearContextExposureState(nodeId);
+            clearSessionCache();
+        }
         // The active branch, rather than the whole session file, is the context the
         // next turn sees. A new cycle therefore receives its own current baseline.
-        const scan = typeof ctx.sessionManager.getBranch === 'function'
-            ? ctx.sessionManager.getBranch()
-            : ctx.sessionManager.getEntries();
-        const contextEntries = scan.filter((e) => e.type === 'custom_message' && e.customType === CONTEXT_INTRO_CUSTOM_TYPE);
+        const contextEntries = activeBranch(ctx).filter((e) => e.type === 'custom_message' && e.customType === CONTEXT_INTRO_CUSTOM_TYPE);
         const ours = contextEntries.some((e) => e.details?.nodeId === nodeId || entryText(e).includes(nodeId));
         if (ours)
             return;
-        // A copied crouter branch already carries the shared baseline. Append only
-        // this fork's new node-scoped facts. A non-crouter branch has no such entry.
-        const inherited = contextEntries.length > 0;
-        const forked = state.node.fork_from !== null;
-        // The baseline branch renders workspace-open docs, so it threads the
-        // PROCESS-SHARED dedup set: the on-read hook (canvas-doc-substrate) holds
-        // the same Set instance, so a front door delivered here never re-delivers
-        // on a later read beneath its store. The fork branch renders no workspace
-        // docs and needs no set.
-        const seen = inherited && forked ? undefined : sharedInjectedDocs(nodeId);
-        const content = inherited && forked
+        const persisted = loadContextExposureState(nodeId);
+        const compact = contextEntries.length > 0 && hasTranscriptExposure(persisted);
+        const next = compact
+            ? cloneTranscriptExposureState(persisted)
+            : emptyContextExposureState();
+        const content = compact
             ? buildForkBearingsFromState(state, situationalContextEnvelope(nodeId) ?? '')
-            : buildContextBearingsFromState(state, buildProjectContextBlockForBroker(state.node.cwd), situationalContextEnvelope(nodeId) ?? '', seen);
+            : buildContextBearingsFromState(state, buildProjectContextBlockForBroker(state.node.cwd), situationalContextEnvelope(nodeId) ?? '', exposureTarget(next, 'transcript'));
+        freezePreferenceSnapshot(next, renderPreferencesFromState(state, exposureTarget(next, 'system')));
+        const messageContent = formatCard('bearings', {}, content);
         pi.sendMessage({
             customType: CONTEXT_INTRO_CUSTOM_TYPE,
-            content: formatCard('bearings', {}, content),
+            content: messageContent,
             display: true,
             details: { nodeId },
         });
-        // Persist what the baseline delivered so the dedup survives a later
-        // dormancy → revive(resume) into a fresh process.
-        if (seen !== undefined)
-            saveInjectedDocs(nodeId, seen);
+        const delivered = activeBranch(ctx).some((entry) => entry.type === 'custom_message'
+            && entry.customType === CONTEXT_INTRO_CUSTOM_TYPE
+            && entry.details?.nodeId === nodeId
+            && entryText(entry) === messageContent);
+        if (!delivered)
+            throw new Error(`Pi did not materialize the context baseline for ${nodeId}`);
+        const live = sharedContextExposureState(nodeId);
+        replaceContextExposureState(live, next);
+        saveContextExposureState(nodeId, live);
+        await acknowledgePersonaBaseline(state);
     });
 }
 export default registerCanvasContextIntro;

package/dist/pi-extensions/canvas-doc-substrate.d.ts

@@ -31,15 +31,8 @@ type ToolResultResultLike = {
 } | void;
 interface PiLike {
     on(event: 'before_agent_start', handler: (event: BeforeAgentStartEventLike) => BeforeAgentStartResultLike | void | Promise<BeforeAgentStartResultLike | void>): void;
-    on(event: 'session_start', handler: (event: unknown, ctx: unknown) => void): void;
+    on(event: 'session_start', handler: (event: unknown, ctx: unknown) => void | Promise<void>): void;
     on(event: 'tool_result', handler: (event: ToolResultEventLike, ctx: ToolResultCtxLike) => ToolResultResultLike | Promise<ToolResultResultLike>): void;
 }
-/**
- * Register the document substrate's pi hooks on `pi`.
- *
- * Returns immediately (inert) when CRTR_NODE_ID is absent — a non-canvas pi
- * session gets no hooks. Each handler is independently wrapped so a failure
- * degrades to a no-op (boot proceeds, the read returns) rather than bricking.
- */
 export declare function registerCanvasDocSubstrate(pi: PiLike): void;
 export default registerCanvasDocSubstrate;