@north-light/crouter 0.3.233 → 0.3.234

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/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

package/dist/core/runtime/broker.js

@@ -16,6 +16,7 @@
 // + model registry are real SDK construction helpers (NOT part of the swappable
 // engine seam — the fake engine receives the real, extension-loaded loader so
 // the real canvas-stophook fires session_start).
+import { envModelIntent, envNodeCwd, envProfileId } from '../../shared/env.js';
 import { createServer } from 'node:net';
 import { existsSync, readFileSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
@@ -54,7 +55,7 @@ import { FrameOverflowError, normalizeSnapshotTail, } from './broker-protocol.js
 /** 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';
 /**
  * pi 0.82 made `ModelRuntime` the canonical model/auth surface and demoted
  * `ModelRegistry` to the synchronous facade over it (`find`/`getAll`/
@@ -83,9 +84,7 @@ function formatExactModelSpec(model, thinkingLevel) {
     const base = formatModelSpec(model, undefined);
     return base === null ? null : `${base}:${thinkingLevel === undefined || thinkingLevel === '' ? 'off' : thinkingLevel}`;
 }
-// ---------------------------------------------------------------------------
 // Tunables (backpressure / dialog anti-deadlock)
-// ---------------------------------------------------------------------------
 /** Broker-side default dialog timeout (anti-deadlock). When an extension
  *  dialog is forwarded to every writable client, the broker ALWAYS arms a timeout
  *  (this default, or a shorter per-dialog `opts.timeout` if the extension passed
@@ -93,14 +92,12 @@ function formatExactModelSpec(model, thinkingLevel) {
  *  — can never hang the agent turn forever. On fire it resolves to the SAFE default
  *  (deny for confirm; cancel/undefined for select/input/editor). */
 const DEFAULT_DIALOG_TIMEOUT_MS = 120_000; // 120 s
-// ---------------------------------------------------------------------------
 // M3 (scout mq5thyli): the active engine session, exposed so broker-cli's FATAL
 // handlers (uncaughtException / unhandledRejection / the runBroker reject) can
 // dispose it before process.exit. The bash tool spawns children `detached` (own
 // pgid); only session.dispose() (→ abortBash / agent.abort → killProcessTree)
 // reaps them. The graceful exit path already disposes; without this the crash
 // path would `process.exit(1)` and ORPHAN every in-flight bash subprocess.
-// ---------------------------------------------------------------------------
 let activeSession = null;
 /** Dispose the live engine session if one exists (idempotent). Called by
  *  broker-cli's fatal handlers before exit so a crash never orphans detached
@@ -117,9 +114,7 @@ export function disposeActiveSession() {
         }
     }
 }
-// ---------------------------------------------------------------------------
 // runBroker — the broker process body (plan T4 steps 1–6)
-// ---------------------------------------------------------------------------
 export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), startupTs = new Date().toISOString()) {
     // A clean-abort certificate belongs only to the dead broker that wrote it.
     // Fleet classification consumes it as proof that the dead broker had a turn
@@ -275,9 +270,7 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
     // N3: the node's display name is re-applied by the rebind lane below so it
     // survives a session replacement (new_session/switch_session/fork), not only at
     // boot.
-    // -------------------------------------------------------------------------
     // Socket fan-out, dialogs, and transcript tool groups
-    // -------------------------------------------------------------------------
     const sockPath = viewSocketPath(nodeId);
     const registry = new BrokerClientRegistry(nodeId);
     const pendingDialogs = new Map();
@@ -445,10 +438,8 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
     const reWelcomeAll = () => {
         registry.forEachHelloed(sendWelcome);
     };
-    // -------------------------------------------------------------------------
     // The single exit helper: dispose the engine, close + unlink the
     // socket, exit 0. Idempotent — every trigger converges here.
-    // -------------------------------------------------------------------------
     const completeExit = (status) => {
         if (disposed)
             return;
@@ -509,7 +500,6 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
         }
         completeExit(status);
     };
-    // -------------------------------------------------------------------------
     // Extension-dialog routing (C2). makeBrokerUiContext owns the dialogPromise;
     // here we just give it the three broker-side hooks it needs: the live set of
     // writable clients (empty = nobody can answer → noOp fallback), how to forward a
@@ -517,7 +507,6 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
     // first settles through. The zero-writable path NEVER hangs and NEVER waits on a
     // per-dialog timeout (design §5.4's timeout premise is false — see
     // makeBrokerUiContext).
-    // -------------------------------------------------------------------------
     uiContext = makeBrokerUiContext({
         writable: () => registry.writableClients(),
         forward: (client, request) => registry.sendFrame(client, request),
@@ -542,9 +531,7 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
     });
     notifyTurnAccepted = frameDispatch.notifyTurnAccepted;
     resetFrameState = frameDispatch.resetForSession;
-    // -------------------------------------------------------------------------
     // 4 (plan): the socket listener — unlink any stale socket first.
-    // -------------------------------------------------------------------------
     try {
         if (existsSync(sockPath))
             unlinkSync(sockPath);
@@ -671,7 +658,6 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
     process.on('SIGTERM', () => { void abortAndExit('SIGTERM'); });
     process.on('SIGINT', () => { void abortAndExit('SIGINT'); });
 }
-// ---------------------------------------------------------------------------
 // snapshotMessages — the catch-up snapshot's ordered message history.
 //
 // The broker is the SOLE writer of the node's session `.jsonl`, so the session
@@ -722,7 +708,6 @@ export function snapshotMessages(session, boundaryReviewId) {
     }
     return messages === undefined ? undefined : visibleMessages(messages, { boundaryReviewId });
 }
-// ---------------------------------------------------------------------------
 // resolveLaunchModel — the SOLE launch model-selection policy, module-scoped
 // so both buildForManager (initial boot, inside buildBrokerSession below) and
 // the reload_auth re-drive (inside runBroker, a DIFFERENT function scope) can
@@ -731,15 +716,14 @@ export function snapshotMessages(session, boundaryReviewId) {
 // viable at all (tier 3) — this is NOT a fault; the caller decides what to do
 // with it (construct a model-less session at boot, or leave a running session
 // alone on a failed re-drive attempt).
-// ---------------------------------------------------------------------------
 async function resolveLaunchModel(services, cfg) {
-    const routeRequest = modelRequestFromConfig(cfg.model, process.env['CRTR_MODEL_INTENT'], cfg.modelExact === true);
+    const routeRequest = modelRequestFromConfig(cfg.model, envModelIntent(), cfg.modelExact === true);
     if (routeRequest === undefined)
         return undefined;
     const registry = registryOf(services);
     const routeOptions = {
-        cwd: process.env['CRTR_NODE_CWD'] ?? cfg.cwd,
-        profileId: process.env['CRTR_PROFILE_ID'],
+        cwd: envNodeCwd() ?? cfg.cwd,
+        profileId: envProfileId(),
     };
     const unknown = unregisteredConcreteModel(routeRequest, registry, routeOptions);
     if (unknown !== undefined) {
@@ -812,11 +796,9 @@ function modelLessRegistry(real) {
     });
     return { runtime, reveal: () => { masked = false; } };
 }
-// ---------------------------------------------------------------------------
 // buildBrokerSession (plan T4 steps 2–4) — turn the launch recipe into a live
 // engine session via the pi SDK SERVICES path. Exported so the C3/C4 real-SDK
 // regression tests can drive the EXACT production wiring (not the mock).
-// ---------------------------------------------------------------------------
 export async function buildBrokerSession(engine, cfg) {
     // 2. Build cwd-bound runtime services via the SERVICES path (C3) — NOT plain
     //    createAgentSession. createAgentSessionServices builds + reloads the