@north-light/crouter 0.3.233 → 0.3.234

package/dist/core/runtime/broker/frame-engine-control.d.ts

@@ -0,0 +1,20 @@
+import type { AgentSessionServices, ModelRegistry } from '@earendil-works/pi-coding-agent';
+import type { ClientToBroker } from '../broker-protocol.js';
+import type { BrokerClient, BrokerClientRegistry } from './client-registry.js';
+import type { FrameReplies } from './frame-replies.js';
+import type { BrokerSession } from './read-ops.js';
+/** The engine-command ops — every one of them a controller-gated mutation of
+ *  the live engine's model, thinking level, queue, or session settings. */
+export type EngineControlFrame = Extract<ClientToBroker, {
+    type: 'set_model' | 'deliver_custom_message' | 'cycle_model' | 'cycle_ladder' | 'cycle_thinking' | 'dequeue' | 'set_thinking_level' | 'set_auto_retry' | 'set_auto_compaction' | 'compact' | 'set_session_name';
+}>;
+export declare function createEngineControlHandler(deps: {
+    registry: BrokerClientRegistry;
+    replies: FrameReplies;
+    session: () => BrokerSession;
+    services: () => AgentSessionServices;
+    registryOf: (services: AgentSessionServices) => ModelRegistry;
+    persistModelChoice: (pinnedOverride?: boolean, userSelected?: boolean) => Promise<string | null>;
+    broadcastModelChanged: (persist?: boolean, pinnedOverride?: boolean, userSelected?: boolean) => Promise<void>;
+    formatModelSpec: (model: BrokerSession['model'], thinkingLevel?: string) => string | null;
+}): (client: BrokerClient, frame: EngineControlFrame) => void;

package/dist/core/runtime/broker/frame-engine-control.js

@@ -0,0 +1,231 @@
+import { configuredLadderProviders, isProviderPinnedModelToken, nextLadderModel, normalizeModel, } from '../launch.js';
+import { isManagedProvider, readSubscriptionPool, } from '../../subscription-state.js';
+import { parseModelSpec } from '../model-selection.js';
+import { resolveModelQuery } from './frame-model-query.js';
+export function createEngineControlHandler(deps) {
+    const { registry, replies, session, services, registryOf, persistModelChoice, broadcastModelChanged, formatModelSpec, } = deps;
+    const { notWritable, ackTo, engineErrorTo } = replies;
+    const modelRegistry = () => registryOf(services());
+    const noSuchModel = (client, message) => registry.sendFrame(client, { type: 'error', code: 'engine_error', message });
+    const setModel = (client, frame) => {
+        if (notWritable(client, 'set the model'))
+            return;
+        const requested = parseModelSpec(frame.model);
+        let model;
+        let normalized;
+        try {
+            // Tier/alias specs (`opus`, `strong`, `anthropic/strong`, …) MUST resolve
+            // through the config ladder before touching the registry: the fuzzy
+            // registry search rank-ties `opus` between claude-3-opus-20240229 and
+            // claude-opus-4-8, and the deprecated 2024 model wins on catalog order.
+            // Concrete `provider/id` specs and genuine substrings (`fable`) pass
+            // through normalizeModel unchanged and take the exact/search path below.
+            normalized = parseModelSpec(normalizeModel(requested.modelSpec));
+            model = resolveModelQuery(modelRegistry(), normalized.modelSpec);
+        }
+        catch (err) {
+            // N2: registry.find should never throw on the real SDK, but a degenerate
+            // engine must still get a reply rather than a silently-dropped frame.
+            engineErrorTo(client)(err);
+            return;
+        }
+        if (model === undefined) {
+            noSuchModel(client, `no model matching '${frame.model}' in the registry`);
+            return;
+        }
+        void session()
+            .setModel(model)
+            .then(async () => {
+            // The caller's explicit `:thinking` wins; else the ladder cell's.
+            const thinking = requested.thinkingLevel ?? normalized.thinkingLevel;
+            if (thinking !== undefined)
+                session().setThinkingLevel(thinking);
+            // frame.pinned, when the sender pre-normalized `frame.model` (e.g.
+            // setModelLive), carries the RAW-token pin decision explicitly.
+            // Otherwise frame.model itself IS the raw/explicit token (a
+            // slash-command arg, or a concrete picker pick) and derives it.
+            await broadcastModelChanged(true, frame.pinned !== undefined
+                ? frame.pinned
+                : isProviderPinnedModelToken(frame.model), true);
+            ackTo(client, 'set_model');
+        })
+            .catch(engineErrorTo(client));
+    };
+    const deliverCustomMessage = (client, frame) => {
+        if (notWritable(client, 'deliver a custom message'))
+            return;
+        // Never triggers a turn either way. `nextTurn` folds the message into
+        // whatever turn comes next (situational context); omitting it pushes
+        // straight onto the message list so it lands FIRST in a still-empty
+        // session (a freshly-claimed spare's bearings). The inbox watcher's own
+        // situational send uses `followUp` + triggerTurn because there its job
+        // IS to wake the node.
+        void session()
+            .sendCustomMessage({
+            customType: frame.customType,
+            content: frame.content,
+            display: true,
+            ...(frame.details !== undefined ? { details: frame.details } : {}),
+        }, ...(frame.deliverAs !== undefined ? [{ deliverAs: frame.deliverAs }] : []))
+            .then(() => ackTo(client, 'deliver_custom_message'))
+            .catch(engineErrorTo(client));
+    };
+    const cycleModel = (client, frame) => {
+        if (notWritable(client, 'cycle the model'))
+            return;
+        void session()
+            .cycleModel(frame.direction)
+            .then(async () => {
+            await broadcastModelChanged(true, undefined, true);
+            ackTo(client, 'cycle_model');
+        })
+            .catch(engineErrorTo(client));
+    };
+    const cycleLadder = (client, frame) => {
+        if (notWritable(client, 'cycle the model ladder'))
+            return;
+        // Resolve the next interleaved-ladder rung from the current model+thinking
+        // spec, then reuse the set_model path (registry resolve + thinking apply).
+        // The cycle only offers signed-in provider columns — same rule as the
+        // setup wizard's Models panel: pool occupancy for a managed provider
+        // (read live, so a login that landed mid-session counts immediately),
+        // else the registry's auth status. When nobody is signed in the helper
+        // returns every provider, so the cycle stays walkable pre-login.
+        const offeredProviders = (() => {
+            try {
+                const models = modelRegistry();
+                return configuredLadderProviders((providerId) => (isManagedProvider(providerId) &&
+                    readSubscriptionPool(providerId).length > 0) ||
+                    models.getProviderAuthStatus(providerId).configured);
+            }
+            catch {
+                return undefined; // auth state unreadable — cycle the full ladder
+            }
+        })();
+        const currentSpec = formatModelSpec(session().model, session().thinkingLevel) ?? '';
+        const nextSpec = parseModelSpec(nextLadderModel(currentSpec, frame.direction === 'backward' ? -1 : 1, offeredProviders));
+        let ladderModel;
+        try {
+            ladderModel = resolveModelQuery(modelRegistry(), nextSpec.modelSpec);
+        }
+        catch (err) {
+            engineErrorTo(client)(err);
+            return;
+        }
+        if (ladderModel === undefined) {
+            noSuchModel(client, `ladder model '${nextSpec.modelSpec}' not in the registry`);
+            return;
+        }
+        void session()
+            .setModel(ladderModel)
+            .then(async () => {
+            if (nextSpec.thinkingLevel !== undefined)
+                session().setThinkingLevel(nextSpec.thinkingLevel);
+            await broadcastModelChanged(true, undefined, true);
+            ackTo(client, 'cycle_ladder');
+        })
+            .catch(engineErrorTo(client));
+    };
+    const cycleThinking = (client) => {
+        if (notWritable(client, 'cycle the thinking level'))
+            return;
+        void (async () => {
+            session().cycleThinkingLevel();
+            await persistModelChoice(undefined, true);
+            ackTo(client, 'cycle_thinking');
+        })().catch(engineErrorTo(client));
+    };
+    const dequeue = (client, frame) => {
+        if (notWritable(client, 'dequeue messages', frame.id))
+            return;
+        try {
+            const { steering, followUp } = session().clearQueue();
+            registry.sendFrame(client, {
+                type: 'data',
+                id: frame.id,
+                kind: 'dequeue',
+                steering,
+                followUp,
+            });
+        }
+        catch (err) {
+            engineErrorTo(client, frame.id)(err);
+        }
+    };
+    const setThinkingLevel = (client, frame) => {
+        if (notWritable(client, 'set the thinking level'))
+            return;
+        void (async () => {
+            session().setThinkingLevel(frame.level);
+            await persistModelChoice(undefined, true);
+            ackTo(client, 'set_thinking_level');
+        })().catch(engineErrorTo(client));
+    };
+    const setAutoRetry = (client, frame) => {
+        if (notWritable(client, 'set auto-retry'))
+            return;
+        try {
+            session().setAutoRetryEnabled(frame.enabled);
+            ackTo(client, 'set_auto_retry');
+        }
+        catch (err) {
+            engineErrorTo(client)(err);
+        }
+    };
+    const setAutoCompaction = (client, frame) => {
+        if (notWritable(client, 'set auto-compaction'))
+            return;
+        try {
+            session().setAutoCompactionEnabled(frame.enabled);
+            ackTo(client, 'set_auto_compaction');
+        }
+        catch (err) {
+            engineErrorTo(client)(err);
+        }
+    };
+    const compact = (client, frame) => {
+        if (notWritable(client, 'compact the session'))
+            return;
+        void session()
+            .compact(frame.instructions)
+            .then(() => ackTo(client, 'compact'))
+            .catch(engineErrorTo(client));
+    };
+    const setSessionName = (client, frame) => {
+        if (notWritable(client, 'rename the session'))
+            return;
+        try {
+            session().setSessionName(frame.name);
+            ackTo(client, 'set_session_name');
+        }
+        catch (err) {
+            engineErrorTo(client)(err);
+        }
+    };
+    return (client, frame) => {
+        switch (frame.type) {
+            case 'set_model':
+                return setModel(client, frame);
+            case 'deliver_custom_message':
+                return deliverCustomMessage(client, frame);
+            case 'cycle_model':
+                return cycleModel(client, frame);
+            case 'cycle_ladder':
+                return cycleLadder(client, frame);
+            case 'cycle_thinking':
+                return cycleThinking(client);
+            case 'dequeue':
+                return dequeue(client, frame);
+            case 'set_thinking_level':
+                return setThinkingLevel(client, frame);
+            case 'set_auto_retry':
+                return setAutoRetry(client, frame);
+            case 'set_auto_compaction':
+                return setAutoCompaction(client, frame);
+            case 'compact':
+                return compact(client, frame);
+            case 'set_session_name':
+                return setSessionName(client, frame);
+        }
+    };
+}

package/dist/core/runtime/broker/frame-memory-refs.d.ts

@@ -0,0 +1,19 @@
+import type { RefMeta } from '../broker-protocol.js';
+import type { BrokerSession } from './read-ops.js';
+/**
+ * Inline memory-reference inventory (design: inline memory references) — a
+ * single broker-level memo shared by BOTH the `list_memory_refs` read-op reply
+ * and per-submission guidance resolution, so a burst of reads + submissions
+ * between reloads never re-walks the corpus per call. Invalidated only when the
+ * corpus is KNOWN to have changed (a successful `session.reload()`); a failed
+ * reload leaves the memo intact.
+ */
+export type MemoryRefGuidance = {
+    /** The memoized inventory rows the `list_memory_refs` read-op replies with. */
+    refs(): RefMeta[];
+    /** The hidden guidance text for a human frame's verbatim text, or `null`. */
+    guidanceFor(text: string): string | null;
+    /** Drop the memo AND the shared substrate parse cache it reads through. */
+    invalidate(): void;
+};
+export declare function createMemoryRefGuidance(session: () => BrokerSession): MemoryRefGuidance;

package/dist/core/runtime/broker/frame-memory-refs.js

@@ -0,0 +1,41 @@
+import { emitEvent } from '../../events/emit.js';
+import { buildRefInventory } from '../../memory/inline-ref-inventory.js';
+import { buildGuidance } from '../../memory/inline-ref-guidance.js';
+import { clearSessionCache } from '../../substrate/session-cache.js';
+import { isLeadingEngineCommand } from './engine-routing.js';
+export function createMemoryRefGuidance(session) {
+    let memoized = null;
+    const inventory = () => {
+        if (memoized === null)
+            memoized = buildRefInventory();
+        return memoized;
+    };
+    return {
+        refs: () => inventory().refs,
+        /** `null` when no guidance should be sent (a leading engine command/skill/
+         *  template, no resolvable refs, or a degraded inventory/guidance build —
+         *  work item 6: any failure here degrades to "no guidance", logged once as a
+         *  structured warning, and NEVER blocks/alters the human delivery). */
+        guidanceFor(text) {
+            try {
+                if (isLeadingEngineCommand(text, session()))
+                    return null;
+                return buildGuidance(text, inventory().names);
+            }
+            catch (err) {
+                emitEvent({
+                    level: 'warn',
+                    event: 'broker.memory_refs.guidance_resolve_failed',
+                    error: err,
+                });
+                return null;
+            }
+        },
+        invalidate() {
+            memoized = null;
+            // Without this, a fresh buildRefInventory() would still read the stale
+            // cached docs out of the shared substrate parse cache.
+            clearSessionCache();
+        },
+    };
+}

package/dist/core/runtime/broker/frame-model-query.d.ts

@@ -0,0 +1,13 @@
+import type { ModelRegistry } from '@earendil-works/pi-coding-agent';
+/** A model resolved out of the registry, or undefined when nothing matches. */
+export type ResolvedModel = ReturnType<ModelRegistry['find']>;
+/** Resolve a `provider/id` model spec against the LIVE services registry (which
+ *  carries any extension-registered providers). Pure: returns undefined on a
+ *  malformed spec or an unknown model. */
+export declare function findModelSpec(registry: ModelRegistry, spec: string): ResolvedModel;
+/** Resolve a model from a free-text query — `/model opus`, `/model fable`. Tries
+ *  the exact `provider/id` spec first; failing that, searches the registry the
+ *  way the picker's search box does (case-insensitive substring on the model id
+ *  and the `provider/id` key) and returns the BEST match, preferring authed/
+ *  available models. Returns undefined only when nothing matches. */
+export declare function resolveModelQuery(registry: ModelRegistry, query: string): ResolvedModel;

package/dist/core/runtime/broker/frame-model-query.js

@@ -0,0 +1,69 @@
+import { parseModelSpec } from '../model-selection.js';
+import { modelKey } from './read-ops.js';
+/** Resolve a `provider/id` model spec against the LIVE services registry (which
+ *  carries any extension-registered providers). Pure: returns undefined on a
+ *  malformed spec or an unknown model. */
+export function findModelSpec(registry, spec) {
+    const { modelSpec } = parseModelSpec(spec);
+    const slash = modelSpec.indexOf('/');
+    if (slash <= 0)
+        return undefined;
+    return registry.find(modelSpec.slice(0, slash), modelSpec.slice(slash + 1));
+}
+/** Resolve a model from a free-text query — `/model opus`, `/model fable`. Tries
+ *  the exact `provider/id` spec first; failing that, searches the registry the
+ *  way the picker's search box does (case-insensitive substring on the model id
+ *  and the `provider/id` key) and returns the BEST match, preferring authed/
+ *  available models. Returns undefined only when nothing matches. */
+export function resolveModelQuery(registry, query) {
+    const exact = findModelSpec(registry, query);
+    if (exact)
+        return exact;
+    const q = query.trim().toLowerCase();
+    if (q === '')
+        return undefined;
+    let all;
+    try {
+        all = registry.getAll();
+    }
+    catch {
+        return undefined;
+    }
+    let availableKeys;
+    try {
+        availableKeys = new Set(registry.getAvailable().map(modelKey));
+    }
+    catch {
+        availableKeys = new Set();
+    }
+    // Rank: exact id (100) > exact provider/id (90) > id prefix (80) > id
+    // substring (60) > provider/id substring (40); +5 if the model is available.
+    const rank = (m) => {
+        const id = m.id.toLowerCase();
+        const key = modelKey(m).toLowerCase();
+        let base = -1;
+        if (id === q)
+            base = 100;
+        else if (key === q)
+            base = 90;
+        else if (id.startsWith(q))
+            base = 80;
+        else if (id.includes(q))
+            base = 60;
+        else if (key.includes(q))
+            base = 40;
+        else
+            return -1;
+        return base + (availableKeys.has(modelKey(m)) ? 5 : 0);
+    };
+    let best;
+    let bestRank = 0;
+    for (const m of all) {
+        const r = rank(m);
+        if (r > bestRank) {
+            bestRank = r;
+            best = m;
+        }
+    }
+    return best;
+}

package/dist/core/runtime/broker/frame-read.d.ts

@@ -0,0 +1,19 @@
+import type { ClientToBroker } from '../broker-protocol.js';
+import type { BrokerClient, BrokerClientRegistry } from './client-registry.js';
+import type { FrameReplies } from './frame-replies.js';
+import type { MemoryRefGuidance } from './frame-memory-refs.js';
+import { type BrokerSession } from './read-ops.js';
+/** The read ops — none of them controller-gated: they are pure reads that
+ *  drive nothing in the engine, so terminal observer connections populate their
+ *  palettes and pickers through these too. */
+export type ReadFrame = Extract<ClientToBroker, {
+    type: 'get_commands' | 'list_models' | 'list_scoped_models' | 'list_memory_refs' | 'get_tree' | 'get_settings' | 'list_sessions' | 'get_human_fork_coordinates';
+}>;
+export declare function createReadHandler(deps: {
+    registry: BrokerClientRegistry;
+    replies: FrameReplies;
+    session: () => BrokerSession;
+    boundaryReviewId: string | undefined;
+    memoryRefs: MemoryRefGuidance;
+    formatExactModelSpec: (model: BrokerSession['model'], thinkingLevel?: string) => string | null;
+}): (client: BrokerClient, frame: ReadFrame) => void;

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

@@ -0,0 +1,116 @@
+import { SessionListCache } from '../session-list-cache.js';
+import { sessionListCachePath } from '../../canvas/paths.js';
+import { engineLeadingCommandTokens } from './engine-routing.js';
+import { buildCommandList, buildGetTreeData, buildListMemoryRefsData, buildListModelsData, buildScopedModelsData, buildSessionsData, buildSettingsData, } from './read-ops.js';
+export function createReadHandler(deps) {
+    const { registry, replies, session, boundaryReviewId, memoryRefs, formatExactModelSpec } = deps;
+    // Cache per-session wire info keyed by (path, mtime, size) so reopening the
+    // picker does not re-read the whole corpus (see session-list-cache.ts).
+    const sessionListCache = new SessionListCache(sessionListCachePath());
+    sessionListCache.prewarm(session().sessionManager.getSessionDir());
+    return (client, frame) => {
+        switch (frame.type) {
+            case 'get_commands': {
+                // OBSERVERS may call this: the merged command inventory is static
+                // (extensions + templates + skills + builtins) and drives nothing in the
+                // engine, so it is not a controller-gated op. Terminal observer
+                // connections use it to populate the command palette.
+                // The merged command list rides in ack.detail as JSON (the foundation's
+                // AckFrame.detail field) — the viewer JSON.parses it when for ===
+                // 'get_commands'. Keeps every command op a uniform ack reply.
+                try {
+                    replies.ackTo(client, 'get_commands', true, JSON.stringify(buildCommandList(session())));
+                }
+                catch (err) {
+                    replies.engineErrorTo(client)(err);
+                }
+                break;
+            }
+            // read-op picker data (§5 Unit A)
+            // NOT controller-gated: read-only, like get_commands. Terminal observer
+            // connections populate pickers through these too.
+            case 'list_models': {
+                try {
+                    registry.sendFrame(client, buildListModelsData(frame.id, session()));
+                }
+                catch (err) {
+                    replies.engineErrorTo(client, frame.id)(err);
+                }
+                break;
+            }
+            case 'list_scoped_models': {
+                try {
+                    registry.sendFrame(client, buildScopedModelsData(frame.id, session()));
+                }
+                catch (err) {
+                    replies.engineErrorTo(client, frame.id)(err);
+                }
+                break;
+            }
+            case 'list_memory_refs': {
+                try {
+                    registry.sendFrame(client, buildListMemoryRefsData(frame.id, memoryRefs.refs(), engineLeadingCommandTokens(session())));
+                }
+                catch (err) {
+                    replies.engineErrorTo(client, frame.id)(err);
+                }
+                break;
+            }
+            case 'get_tree': {
+                try {
+                    registry.sendFrame(client, buildGetTreeData(frame.id, session(), boundaryReviewId));
+                }
+                catch (err) {
+                    replies.engineErrorTo(client, frame.id)(err);
+                }
+                break;
+            }
+            case 'get_settings': {
+                try {
+                    registry.sendFrame(client, buildSettingsData(frame.id, session()));
+                }
+                catch (err) {
+                    replies.engineErrorTo(client, frame.id)(err);
+                }
+                break;
+            }
+            case 'list_sessions': {
+                // Session listing reads the session dir off disk — async; reply when it
+                // resolves (or relay the error, correlated by id so the viewer doesn't hang).
+                void buildSessionsData(frame.id, frame.scope ?? 'cwd', session(), sessionListCache)
+                    .then((d) => registry.sendFrame(client, d))
+                    .catch(replies.engineErrorTo(client, frame.id));
+                break;
+            }
+            case 'get_human_fork_coordinates': {
+                // NOT controller-gated: this is a pure observer read. Branch creation is
+                // intentionally delegated to a detached SDK manager in the ask publisher;
+                // calling createBranchedSession here corrupts this live manager's identity.
+                try {
+                    const sm = session().sessionManager;
+                    const sourceFile = sm.getSessionFile();
+                    const leafId = sm.getLeafId();
+                    if (sourceFile === undefined ||
+                        sourceFile === '' ||
+                        leafId === null) {
+                        replies.engineErrorTo(client, frame.id)(new Error('no persisted source session leaf'));
+                        break;
+                    }
+                    registry.sendFrame(client, {
+                        type: 'data',
+                        id: frame.id,
+                        kind: 'human_fork_coordinates',
+                        sourceFile,
+                        sourceSessionId: sm.getSessionId(),
+                        leafId,
+                        modelSpec: formatExactModelSpec(session().model, session().thinkingLevel),
+                    });
+                }
+                catch (err) {
+                    replies.engineErrorTo(client, frame.id)(err);
+                }
+                break;
+            }
+        }
+    };
+}

package/dist/core/runtime/broker/frame-replies.d.ts

@@ -0,0 +1,24 @@
+import type { BrokerClient, BrokerClientRegistry } from './client-registry.js';
+import type { BrokerSession } from './read-ops.js';
+export declare const REVIEW_BOUNDARY_NAVIGATION_CODE = "review_boundary_navigation";
+export declare class ReviewBoundaryNavigationError extends Error {
+    readonly targetId: string;
+    readonly code = "review_boundary_navigation";
+    constructor(targetId: string);
+}
+/** The reply vocabulary every frame handler answers a client with, bound once
+ *  to the client registry that owns the sockets. */
+export type FrameReplies = {
+    /** Reject a read-only client for a mutating op. The decision reads this
+     *  client's OWN fixed role — there is no shared writer slot, so any number of
+     *  writable clients pass concurrently. Returns true when rejected (the caller
+     *  should `break`). */
+    notWritable(client: BrokerClient, what: string, id?: string): boolean;
+    ackTo(client: BrokerClient, op: string, ok?: boolean, detail?: string, id?: string): void;
+    engineErrorTo(client: BrokerClient, id?: string): (err: unknown) => void;
+    reviewBoundaryRefusalTo(client: BrokerClient, targetId: string): void;
+};
+export declare function createFrameReplies(registry: BrokerClientRegistry): FrameReplies;
+/** True iff `entryId` sits BEFORE this review companion's visible transcript
+ *  boundary — the navigation an ordinary node has no boundary for. */
+export declare function isPreBoundaryReviewEntry(session: BrokerSession, boundaryReviewId: string | undefined, entryId: string): boolean;

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

@@ -0,0 +1,64 @@
+import { isReviewBoundary } from '../session-visibility.js';
+export const REVIEW_BOUNDARY_NAVIGATION_CODE = 'review_boundary_navigation';
+export class ReviewBoundaryNavigationError extends Error {
+    targetId;
+    code = REVIEW_BOUNDARY_NAVIGATION_CODE;
+    constructor(targetId) {
+        super(`review companion cannot navigate before the visible transcript boundary (target: ${targetId})`);
+        this.targetId = targetId;
+        this.name = 'ReviewBoundaryNavigationError';
+    }
+}
+export function createFrameReplies(registry) {
+    return {
+        notWritable(client, what, id) {
+            if (client.role === 'controller')
+                return false;
+            registry.sendFrame(client, {
+                type: 'error',
+                code: 'read_only',
+                message: `a read-only client may not ${what}`,
+                // M1: echo a correlated request's id so its pending-by-id promise rejects
+                // rather than hanging (e.g. a read-only `dequeue`).
+                ...(id !== undefined ? { id } : {}),
+            });
+            return true;
+        },
+        ackTo(client, op, ok = true, detail, id) {
+            registry.sendFrame(client, {
+                type: 'ack',
+                for: op,
+                ok,
+                ...(detail !== undefined ? { detail } : {}),
+                ...(id !== undefined ? { id } : {}),
+            });
+        },
+        engineErrorTo(client, id) {
+            return (err) => registry.sendFrame(client, {
+                type: 'error',
+                code: 'engine_error',
+                message: String(err),
+                // M1: a correlated read-op / dequeue failure echoes its id so the viewer's
+                // pending-by-id promise rejects instead of hanging; uncorrelated callers
+                // pass no id (unchanged behavior).
+                ...(id !== undefined ? { id } : {}),
+            });
+        },
+        reviewBoundaryRefusalTo(client, targetId) {
+            const refusal = new ReviewBoundaryNavigationError(targetId);
+            registry.sendFrame(client, {
+                type: 'error',
+                code: refusal.code,
+                message: refusal.message,
+            });
+        },
+    };
+}
+/** True iff `entryId` sits BEFORE this review companion's visible transcript
+ *  boundary — the navigation an ordinary node has no boundary for. */
+export function isPreBoundaryReviewEntry(session, boundaryReviewId, entryId) {
+    return (boundaryReviewId !== undefined &&
+        !session.sessionManager
+            .getBranch(entryId)
+            .some((entry) => isReviewBoundary(entry, boundaryReviewId)));
+}

package/dist/core/runtime/broker/frame-session.d.ts

@@ -0,0 +1,34 @@
+import type { ClientToBroker } from '../broker-protocol.js';
+import type { BrokerClient, BrokerClientRegistry } from './client-registry.js';
+import type { FrameReplies } from './frame-replies.js';
+import type { MemoryRefGuidance } from './frame-memory-refs.js';
+import type { RebindDriver } from './rebind.js';
+import type { BrokerSession } from './read-ops.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 declare function isHiddenJsonlBranchEntry(entry: unknown): boolean;
+/** 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 declare function stripHiddenEntriesFromJsonlExport(filePath: string): void;
+/** The ops that navigate, replace, or publish this node's session. */
+export type SessionFrame = Extract<ClientToBroker, {
+    type: 'navigate_tree' | 'reload' | 'export' | 'new_session' | 'switch_session' | 'fork' | 'clone' | 'share';
+}>;
+export declare function createSessionHandler(deps: {
+    registry: BrokerClientRegistry;
+    replies: FrameReplies;
+    rebind: RebindDriver;
+    session: () => BrokerSession;
+    boundaryReviewId: string | undefined;
+    memoryRefs: MemoryRefGuidance;
+    reWelcomeAll: () => void;
+}): (client: BrokerClient, frame: SessionFrame) => void;