@north-light/crouter 0.3.233 → 0.3.235

package/dist/core/runtime/broker/frame-session.js

@@ -0,0 +1,203 @@
+import { execFile } from 'node:child_process';
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { captureSessionChatCapabilities } from '../command-surface.js';
+import { isPreBoundaryReviewEntry } from './frame-replies.js';
+/** True iff a parsed JSONL branch-entry line is a hidden (`display:false`)
+ *  custom message — the general display boundary crossed if left in an
+ *  exported branch (not just `crtr-memory-refs` guidance; any hidden custom
+ *  content). Covers both persisted shapes a branch entry can take: a
+ *  `type:'custom_message'` entry (display at the entry's own top level) and a
+ *  `type:'message'` entry wrapping a `role:'custom'` message (display nested
+ *  under `.message`). */
+export function isHiddenJsonlBranchEntry(entry) {
+    if (entry === null || typeof entry !== 'object')
+        return false;
+    const e = entry;
+    if (e.type === 'custom_message' && e.display === false)
+        return true;
+    if (e.type === 'message' && e.message?.role === 'custom' && e.message.display === false)
+        return true;
+    return false;
+}
+/** Rewrite an already-exported JSONL file in place, dropping every hidden
+ *  (`display:false`) branch entry while re-chaining `parentId` so the
+ *  remaining entries stay a single valid linear branch — applying the general
+ *  display:false boundary to `session.exportToJsonl`'s own output, which
+ *  serializes every entry verbatim regardless of display. The header line
+ *  (line 1) is copied through untouched. */
+export function stripHiddenEntriesFromJsonlExport(filePath) {
+    const raw = readFileSync(filePath, 'utf8');
+    const lines = raw.split('\n').filter((l) => l !== '');
+    if (lines.length === 0)
+        return;
+    const [headerLine, ...entryLines] = lines;
+    let prevId = null;
+    const kept = [];
+    for (const line of entryLines) {
+        const entry = JSON.parse(line);
+        if (isHiddenJsonlBranchEntry(entry))
+            continue;
+        kept.push(JSON.stringify({ ...entry, parentId: prevId }));
+        if (typeof entry.id === 'string')
+            prevId = entry.id;
+    }
+    writeFileSync(filePath, `${[headerLine, ...kept].join('\n')}\n`);
+}
+export function createSessionHandler(deps) {
+    const { registry, replies, rebind, session, boundaryReviewId, memoryRefs, reWelcomeAll } = deps;
+    return (client, frame) => {
+        switch (frame.type) {
+            case 'navigate_tree': {
+                if (replies.notWritable(client, 'navigate the session tree'))
+                    break;
+                if (isPreBoundaryReviewEntry(session(), boundaryReviewId, frame.targetId)) {
+                    replies.reviewBoundaryRefusalTo(client, frame.targetId);
+                    break;
+                }
+                // navigateTree rewinds IN-PLACE (same session file, new leaf) and emits no
+                // relayed event, so every viewer must be re-snapshotted onto the rewound
+                // transcript — same reWelcomeAll the session-replacing ops use. The ack's
+                // detail carries the navigated-to user message's text (pi parity: the
+                // interactive tree navigator restores it to the editor for re-editing).
+                void session()
+                    .navigateTree(frame.targetId, frame.options)
+                    .then((r) => {
+                    if (!r.cancelled)
+                        reWelcomeAll();
+                    replies.ackTo(client, 'navigate_tree', !r.cancelled, r.editorText);
+                })
+                    .catch(replies.engineErrorTo(client));
+                break;
+            }
+            case 'reload': {
+                if (replies.notWritable(client, 'reload'))
+                    break;
+                // A SUCCESSFUL reload invalidates the memoized ref inventory (work item
+                // 3) so the next read-op/submission re-walks the corpus. A FAILED
+                // reload (`.catch`) leaves it untouched: nothing about the corpus is
+                // known to have changed.
+                void session()
+                    .reload({ beforeSessionStart: () => captureSessionChatCapabilities(session()) })
+                    .then(() => {
+                    // pi's reload() re-syncs queue modes from the shared settings.json
+                    // (its ONE post-bind syncQueueModesFromSettings call site) —
+                    // re-apply the broker's 'all' modes so a reload cannot silently
+                    // restore one-at-a-time draining (see rebind.enqueueRebind).
+                    const agent = session().agent;
+                    if (agent) {
+                        agent.steeringMode = 'all';
+                        agent.followUpMode = 'all';
+                    }
+                    memoryRefs.invalidate();
+                    registry.forEachHelloed((observer) => {
+                        if (observer.role === 'observer')
+                            registry.sendFrame(observer, { type: 'resources_reloaded' });
+                    });
+                    replies.ackTo(client, 'reload');
+                })
+                    .catch(replies.engineErrorTo(client));
+                break;
+            }
+            case 'export': {
+                if (replies.notWritable(client, 'export the session'))
+                    break;
+                if (frame.format === 'jsonl') {
+                    try {
+                        const outPath = session().exportToJsonl(frame.path);
+                        stripHiddenEntriesFromJsonlExport(outPath);
+                        replies.ackTo(client, 'export');
+                    }
+                    catch (err) {
+                        replies.engineErrorTo(client)(err);
+                    }
+                }
+                else {
+                    void session()
+                        .exportToHtml(frame.path)
+                        .then(() => replies.ackTo(client, 'export'))
+                        .catch(replies.engineErrorTo(client));
+                }
+                break;
+            }
+            case 'new_session': {
+                if (replies.notWritable(client, 'start a new session'))
+                    break;
+                rebind.runReplacement(client, 'new_session', (rt) => rt.newSession());
+                break;
+            }
+            case 'switch_session': {
+                if (replies.notWritable(client, 'switch sessions'))
+                    break;
+                rebind.runReplacement(client, 'switch_session', (rt) => rt.switchSession(frame.path));
+                break;
+            }
+            case 'fork': {
+                if (replies.notWritable(client, 'fork the session'))
+                    break;
+                if (isPreBoundaryReviewEntry(session(), boundaryReviewId, frame.entryId)) {
+                    replies.reviewBoundaryRefusalTo(client, frame.entryId);
+                    break;
+                }
+                rebind.runReplacement(client, 'fork', (rt) => rt.fork(frame.entryId));
+                break;
+            }
+            case 'clone': {
+                if (replies.notWritable(client, 'clone the session'))
+                    break;
+                rebind.runReplacement(client, 'clone', async (rt) => {
+                    const sm = session().sessionManager;
+                    const leafId = sm.getLeafId();
+                    if (leafId === null) {
+                        return { cancelled: true, detail: 'no current leaf to clone from' };
+                    }
+                    const newPath = sm.createBranchedSession(leafId);
+                    if (newPath === undefined) {
+                        return {
+                            cancelled: true,
+                            detail: 'createBranchedSession returned no path',
+                        };
+                    }
+                    return rt.switchSession(newPath);
+                });
+                break;
+            }
+            case 'share': {
+                if (replies.notWritable(client, 'share the session'))
+                    break;
+                const tmpPath = join(tmpdir(), `pi-share-${Date.now()}.html`);
+                void session()
+                    .exportToHtml(tmpPath)
+                    .then(() => new Promise((resolve, reject) => {
+                    execFile('gh', ['gist', 'create', '--secret', tmpPath], { timeout: 30_000, maxBuffer: 1024 * 1024 }, (err, stdout) => {
+                        try {
+                            if (existsSync(tmpPath))
+                                unlinkSync(tmpPath);
+                        }
+                        catch {
+                            /* cleanup */
+                        }
+                        if (err) {
+                            reject(err);
+                            return;
+                        }
+                        resolve(stdout.trim());
+                    });
+                }))
+                    .then((url) => {
+                    replies.ackTo(client, 'share', true, url);
+                })
+                    .catch((err) => {
+                    const msg = String(err?.message ?? err);
+                    replies.ackTo(client, 'share', false, msg.includes('not found') ||
+                        msg.includes('gh: command not found') ||
+                        msg.includes('ENOENT')
+                        ? '`gh` CLI not found — install GitHub CLI and authenticate with `gh auth login`'
+                        : `share failed: ${msg}`);
+                });
+                break;
+            }
+        }
+    };
+}

package/dist/core/runtime/broker/rebind.js

@@ -8,6 +8,55 @@ import { abortSessionFromExtension } from './extension-abort.js';
 const MAX_ADMITTED_REPLACEMENTS = 2;
 const REPLACEMENT_DEADLINE_MS = 30_000;
 const REPLACEMENT_DEADLINE_EXCEEDED = Symbol('replacement-deadline-exceeded');
+const TRAILING_THINKING_PLACEHOLDER = '(interrupted)';
+const TRAILING_THINKING_GUARD = Symbol.for('crtr.trailing-thinking-guard');
+/** The last block an Anthropic request will actually carry: the serializer
+ *  drops whitespace-only text and signature-less empty thinking. */
+function lastSerializedBlock(content) {
+    for (let i = content.length - 1; i >= 0; i--) {
+        const block = content[i];
+        if (block === undefined)
+            continue;
+        if (block.type === 'text') {
+            if (block.text.trim().length === 0)
+                continue;
+            return block;
+        }
+        if (block.type === 'thinking') {
+            const signature = block.thinkingSignature;
+            const hasSignature = typeof signature === 'string' && signature.trim().length > 0;
+            if (block.redacted !== true && block.thinking.trim().length === 0 && !hasSignature)
+                continue;
+            return block;
+        }
+        return block;
+    }
+    return undefined;
+}
+function guardTrailingThinking(messages) {
+    return messages.map((message) => {
+        if (message.role !== 'assistant')
+            return message;
+        if (lastSerializedBlock(message.content)?.type !== 'thinking')
+            return message;
+        return { ...message, content: [...message.content, { type: 'text', text: TRAILING_THINKING_PLACEHOLDER }] };
+    });
+}
+/** Crouter aborts live streams (watchdog, extension abort, viewer esc), which
+ *  persists assistant turns that end on a thinking block. Anthropic rejects a
+ *  request whose final assistant block is `thinking`, and pi-ai's serializer
+ *  has no guard for it, so every later turn re-fails on embedded history. */
+function installTrailingThinkingGuard(agent) {
+    const inner = agent.convertToLlm;
+    if (inner[TRAILING_THINKING_GUARD] === true)
+        return;
+    const wrapped = (messages) => {
+        const converted = inner(messages);
+        return converted instanceof Promise ? converted.then(guardTrailingThinking) : guardTrailingThinking(converted);
+    };
+    wrapped[TRAILING_THINKING_GUARD] = true;
+    agent.convertToLlm = wrapped;
+}
 /** Owns session subscription replacement, its serialization lane, and replacement admission policy. */
 export class RebindDriver {
     deps;
@@ -86,6 +135,7 @@ export class RebindDriver {
                 });
                 agent.steeringMode = 'all';
                 agent.followUpMode = 'all';
+                installTrailingThinkingGuard(agent);
             }
             if (this.deps.cfg.editorName !== undefined && this.deps.cfg.editorName !== '') {
                 try {

package/dist/core/runtime/broker/turn-ignition.d.ts

@@ -0,0 +1,42 @@
+import type { BrokerSession } from './read-ops.js';
+/**
+ * Prompt dispatches whose promise has not yet settled. `session.prompt()` does
+ * async setup (input transforms, model/auth validation, compaction) BEFORE
+ * `_isAgentRunActive` flips, so for a short window after a routed deliver the
+ * engine reads idle and `session.abort()` is a silent no-op — an interrupt
+ * racing that window would miss the turn entirely (verified live). The counter
+ * lets a caller distinguish "genuinely idle" from "turn still igniting".
+ */
+export type PromptDispatchTracker = {
+    track(p: Promise<unknown>): Promise<unknown>;
+    pending(): number;
+    /** Wait (bounded) for a pending dispatch to reach an abortable turn — or for
+     *  every dispatch to settle without one (an early return). Returns
+     *  immediately when the engine is already streaming or nothing is pending. */
+    waitUntilAbortable(): Promise<void>;
+};
+export declare function createPromptDispatchTracker(session: () => BrokerSession): PromptDispatchTracker;
+/**
+ * The one-shot waiters a `deliver` frame parks until its prompt is ACCEPTED by
+ * the engine (the broker's `agent_start`). Every waiter fires once, on the
+ * first acceptance after it was added.
+ */
+export type TurnAcceptanceGate = {
+    waitFor(waiter: () => void): void;
+    cancel(waiter: () => void): void;
+    notifyAccepted(): void;
+};
+export declare function createTurnAcceptanceGate(): TurnAcceptanceGate;
+/**
+ * The launch prompt, held until the session actually has a model. A model-less
+ * tier-3 boot leaves it pending; `drivePending` is a no-op until the
+ * `reload_auth` re-drive resolves a model, at which point it fires.
+ */
+export type KickoffDriver = {
+    kickoff(prompt: string): void;
+    drivePending(): void;
+};
+export declare function createKickoffDriver(deps: {
+    session: () => BrokerSession;
+    dispatches: PromptDispatchTracker;
+}): KickoffDriver;

package/dist/core/runtime/broker/turn-ignition.js

@@ -0,0 +1,74 @@
+import { emitEvent } from '../../events/emit.js';
+import { operationIdContext } from '../../events/operation-id.js';
+import { isUnknownModel } from '../model-selection.js';
+/** How long a caller waits for a dispatched prompt to become abortable, and how
+ *  often it re-reads the engine while waiting. */
+const ABORTABLE_WAIT_MS = 5_000;
+const ABORTABLE_POLL_MS = 25;
+export function createPromptDispatchTracker(session) {
+    let pending = 0;
+    return {
+        track(p) {
+            pending++;
+            const tracked = Promise.resolve(p);
+            void tracked.finally(() => {
+                pending--;
+            });
+            return tracked;
+        },
+        pending: () => pending,
+        async waitUntilAbortable() {
+            if (session().isStreaming || pending === 0)
+                return;
+            const deadline = Date.now() + ABORTABLE_WAIT_MS;
+            while (Date.now() < deadline && !session().isStreaming && pending > 0) {
+                await new Promise((resolve) => setTimeout(resolve, ABORTABLE_POLL_MS));
+            }
+        },
+    };
+}
+export function createTurnAcceptanceGate() {
+    const waiters = new Set();
+    return {
+        waitFor: (waiter) => void waiters.add(waiter),
+        cancel: (waiter) => void waiters.delete(waiter),
+        notifyAccepted() {
+            const pending = [...waiters];
+            waiters.clear();
+            for (const waiter of pending)
+                waiter();
+        },
+    };
+}
+export function createKickoffDriver(deps) {
+    const { session, dispatches } = deps;
+    let pendingPrompt;
+    let inFlight = false;
+    const sessionHasNoModel = () => session().model === undefined || isUnknownModel(session().model);
+    const drivePending = () => {
+        if (pendingPrompt === undefined || inFlight || sessionHasNoModel())
+            return;
+        const prompt = pendingPrompt;
+        pendingPrompt = undefined;
+        inFlight = true;
+        dispatches.track(operationIdContext.fresh(() => session()
+            .prompt(prompt)
+            .catch((err) => {
+            emitEvent({
+                level: 'error',
+                event: 'broker.prompt.first_failed',
+                error: err,
+            });
+        })
+            .finally(() => {
+            inFlight = false;
+        })));
+    };
+    return {
+        kickoff(prompt) {
+            pendingPrompt = prompt;
+            drivePending();
+        },
+        drivePending,
+    };
+}

package/dist/core/runtime/broker-extension-render.js

@@ -1,118 +1,42 @@
 // Pure broker-side render adapters. crtrd supplies the fixed extension-state
 // DTO; these functions only combine it with node-local/filesystem information.
 import { contextDir, nodeDir } from '../canvas/paths.js';
-import { execSync, spawnSync } from 'node:child_process';
-import { readdirSync } from 'node:fs';
-import { hostname } from 'node:os';
 import { interpolateNodePaths } from '../canvas/paths.js';
 import { fullName } from '../canvas/labels.js';
 import { renderKnowledgeForSubject, renderPreferencesForSubject } from '../substrate/render.js';
 import { renderWorkspaceOpenDocsForSubject } from '../substrate/on-read.js';
-import { loadProfileManifest } from '../profiles/manifest.js';
+import { buildProjectContextBlock, contextDirNote as contextDirNoteShared, profileNote as profileNoteShared, relativeLabel as relativeLabelShared, renderGraphMap, buildIdentityAssertion, worktreeNote as worktreeNoteShared, } from './bearings-render.js';
 export function editorLabelForBrokerNode(node) {
     const icon = (node.icon ?? '').trim();
     const handle = node.name !== node.kind ? node.name.trim() : '';
     const name = handle !== '' ? handle : (node.description ?? '').trim() || node.name;
     return icon === '' ? name : `${icon} ${name}`;
 }
-function command(cwd, text) {
-    try {
-        return execSync(text, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
-    }
-    catch {
-        return '';
-    }
-}
 /** Same environment-only project context rendered at normal boot, without a
  * canvas import. */
 export function buildProjectContextBlockForBroker(cwd) {
-    let listing;
-    try {
-        const entries = readdirSync(cwd, { withFileTypes: true }).sort((a, b) => Number(b.isDirectory()) - Number(a.isDirectory()) || a.name.localeCompare(b.name));
-        const shown = entries.slice(0, 50).map((entry) => `${entry.name}${entry.isDirectory() ? '/' : ''}`);
-        listing = entries.length > shown.length ? [...shown, `[+${entries.length - shown.length} more]`] : shown;
-    }
-    catch {
-        listing = ['Directory listing: unavailable (cwd missing or unreadable).'];
-    }
-    const tmux = spawnSync('tmux', ['list-sessions'], { encoding: 'utf8', stdio: 'ignore' }).status === 0;
-    let git = 'Git: not a git repository.';
-    let worktrees = 'Worktrees: none.';
-    if (command(cwd, 'git rev-parse --is-inside-work-tree') !== '') {
-        const branch = command(cwd, 'git branch --show-current') || command(cwd, 'git rev-parse --abbrev-ref HEAD') || 'HEAD';
-        const sha = command(cwd, 'git rev-parse --short HEAD') || 'unknown';
-        const changes = command(cwd, 'git status --porcelain').split('\n').filter(Boolean).length;
-        const raw = command(cwd, 'git worktree list --porcelain').split('\n');
-        const found = [];
-        let path = '';
-        let wtBranch = 'detached HEAD';
-        for (const line of raw) {
-            if (line.startsWith('worktree ')) {
-                if (path !== '')
-                    found.push(`${path} (${wtBranch})`);
-                path = line.slice(9);
-                wtBranch = 'detached HEAD';
-            }
-            else if (line.startsWith('branch '))
-                wtBranch = line.slice(7).replace(/^refs\/heads\//, '');
-        }
-        if (path !== '')
-            found.push(`${path} (${wtBranch})`);
-        git = `Git: ${branch} @ ${sha}; ${changes === 0 ? 'clean' : `${changes} uncommitted change${changes === 1 ? '' : 's'}`}; ${found.length} worktree${found.length === 1 ? '' : 's'}.`;
-        worktrees = found.length === 0 ? 'Worktrees: none.' : `Worktrees: ${found.join(', ')}`;
-    }
-    return `<project_context>\n\n<environment cwd="${cwd.replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('<', '&lt;')}">\nHost: ${process.platform} ${process.arch} · ${hostname()} · node ${process.version} · tmux server: ${tmux ? 'reachable' : 'none'}\nDirectory:\n${listing.map((line) => `  ${line}`).join('\n')}\n${git}\n${worktrees}\n</environment>\n</project_context>`;
+    return buildProjectContextBlock(cwd);
 }
 function contextDirNote(nodeId) {
-    return `Your context directory is \`${contextDir(nodeId)}\` (also in the env as \`$CRTR_CONTEXT_DIR\`) — durable scratch space on disk, and the one place the other nodes on the canvas can read from. Put documents here that you want to share by reference instead of re-explaining them in a prompt: specs, designs, findings, notes worth pointing a sibling, child, or parent at. It is a shared document store, not a task tracker. **Address it by absolute path** — write artifacts as \`$CRTR_CONTEXT_DIR/<name>.md\` (or the full path above). Your working dir is the project, NOT this directory, so a bare relative \`context/...\` lands in the repo, not here — and other nodes can only read what is actually here. When you report a file, report its absolute path.`;
+    return contextDirNoteShared(nodeId);
 }
 function profileNote(node) {
-    if (node.profile_id === null || node.profile_id === '')
-        return '';
-    try {
-        const entry = loadProfileManifest(node.profile_id);
-        if (entry.manifest.projects.length === 0)
-            return '';
-        return `Your working dir is \`${node.cwd}\`. Your profile **${entry.manifest.name}** also has purview over: ${entry.manifest.projects.map((project) => project.path).join(', ')}.`;
-    }
-    catch {
-        return '';
-    }
+    return profileNoteShared(node.cwd, node.profile_id);
 }
 function relativeLabel(node) {
-    const desc = fullName(node);
-    const descPart = desc !== '' && desc !== node.kind && desc !== node.name ? ` — ${desc}` : '';
-    return `${node.node_id} (${node.kind} · ${node.status})${descPart}`;
+    return relativeLabelShared(node);
 }
 function graphMap(state) {
     const { ancestors, children, node } = state;
-    if (ancestors.length === 0 && children.length === 0)
-        return '';
-    const indent = (depth) => '  '.repeat(depth);
-    const lines = ['Your place in the canvas graph (ancestry above you, your direct children below):'];
-    ancestors.forEach((ancestor, index) => lines.push(`${indent(index)}${index === 0 ? '' : '└ '}${relativeLabel(ancestor)}`));
-    const depth = ancestors.length;
-    lines.push(`${indent(depth)}${depth === 0 ? '' : '└ '}● you: ${node.node_id} (${node.kind}, ${node.mode})`);
-    const shown = children.slice(0, 5);
-    shown.forEach((child, index) => lines.push(`${indent(depth + 1)}${index === shown.length - 1 && children.length === shown.length ? '└ ' : '├ '}${relativeLabel(child)}`));
-    if (children.length > shown.length)
-        lines.push(`${indent(depth + 1)}└ +${children.length - shown.length} more`);
-    return lines.join('\n');
+    return renderGraphMap(node.node_id, node.kind, node.mode, ancestors, children);
 }
 function identity(state) {
     const { node, fork_source: source } = state;
-    const lines = [`You are node ${node.node_id} — kind ${node.kind}, mode ${node.mode}.`];
-    if (node.fork_from !== null && node.fork_from !== '') {
-        const sourceLabel = source === null ? node.fork_from : `${node.fork_from} ("${fullName(source)}")`;
-        lines.push('', `You are a new FORK of ${sourceLabel}, not ${sourceLabel}. Pi copied the earlier conversation into this session. Treat that first-person history as reference material, not your own past.`);
-    }
-    return lines.join('\n');
+    const sourceLabel = source === null ? (node.fork_from ?? '') : `${node.fork_from} ("${fullName(source)}")`;
+    return buildIdentityAssertion(node.node_id, node.kind, node.mode, node.fork_from, sourceLabel);
 }
 function worktreeNote(node) {
-    const worktree = node.managed_worktree;
-    if (worktree === null || worktree === undefined || worktree.state !== 'open')
-        return '';
-    return `Branch: \`${worktree.branch}\`\nWorktree: \`${worktree.path}\`\nBase: \`${worktree.base_ref}\` @ \`${worktree.base_sha}\`\nCommit work here. Land it with \`crtr node worktree close\` before finishing. Auto-drop applies only when the worktree is clean (no uncommitted changes) and nothing remains to land (zero commits ahead of the base, or its commits are already contained in the base); unlanded commits (commits not already contained in the base) or uncommitted changes require an explicit close/landing decision.`;
+    return worktreeNoteShared(node.managed_worktree);
 }
 /** The companion note — rendered ONLY when a node carries its immutable
  *  companion binding. Names the target (the document under review, or the page

package/dist/core/runtime/broker-protocol.js

@@ -16,9 +16,7 @@
 // pi. pi names the correlation field `id` (design §5.2 wrote `request_id`); we
 // follow pi.
 import { StringDecoder } from 'node:string_decoder';
-// ---------------------------------------------------------------------------
 // Client → broker frames
-// ---------------------------------------------------------------------------
 /** Largest transcript window a client may request in its welcome snapshot. */
 export const SNAPSHOT_TAIL_MAX = 500;
 /** Invalid requests preserve the complete welcome; valid requests are capped. */
@@ -27,10 +25,8 @@ export function normalizeSnapshotTail(value) {
         return undefined;
     return Math.min(value, SNAPSHOT_TAIL_MAX);
 }
-// ---------------------------------------------------------------------------
 // Newline-delimited JSON codec (the framing pi solves with `jsonl`, reproduced
 // locally so the protocol module owns no transport dependency)
-// ---------------------------------------------------------------------------
 /** Encode one frame as a single newline-terminated JSON line. */
 export function encodeFrame(frame) {
     return JSON.stringify(frame) + '\n';

package/dist/core/runtime/broker-sdk.js

@@ -10,6 +10,7 @@
 import { execFileSync } from 'node:child_process';
 import { readFileSync, statSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { envBrokerEngine } from '../../shared/env.js';
 import { createAgentSessionServices, createAgentSessionFromServices, createAgentSessionRuntime, SessionManager, VERSION, } from '@earendil-works/pi-coding-agent';
 import { crtrHome } from '../canvas/paths.js';
 import { emitEvent } from '../events/emit.js';
@@ -24,7 +25,7 @@ export { createAgentSessionServices, createAgentSessionFromServices, createAgent
  * through here so the seam stays a single, auditable swap.
  */
 export async function loadBrokerEngine() {
-    const spec = process.env.CRTR_BROKER_ENGINE ?? '@earendil-works/pi-coding-agent';
+    const spec = envBrokerEngine();
     const mod = (await import(spec));
     if (typeof mod.createAgentSessionServices !== 'function' ||
         typeof mod.createAgentSessionFromServices !== 'function' ||

package/dist/core/runtime/broker.d.ts

@@ -7,7 +7,7 @@ import { type BrokerToClient, type RpcExtensionUIRequest, type RpcExtensionUIRes
 /** A review companion may only navigate or fork within a branch whose ancestry
  * has crossed its durable transcript boundary. The broker sends this typed local
  * failure as a dedicated error frame without invoking pi's tree mutation. */
-export { ReviewBoundaryNavigationError, REVIEW_BOUNDARY_NAVIGATION_CODE } from './broker/frame-dispatch.js';
+export { ReviewBoundaryNavigationError, REVIEW_BOUNDARY_NAVIGATION_CODE } from './broker/frame-replies.js';
 export type { SubscriptionGeneration } from './broker/rebind.js';
 /** A blocking dialog awaiting a response from ANY writable client, the
  *  broker-side default timeout, or the engine's abort. The dialog is fanned out