@north-light/crouter 0.3.170 → 0.3.172

package/dist/core/runtime/__tests__/session-visibility.test.js

@@ -0,0 +1,119 @@
+// Run with: node --import tsx/esm --test src/core/runtime/__tests__/session-visibility.test.ts
+//
+// This table keeps the review companion transcript boundary a pure, cheap
+// regression surface: ordinary snapshots are untouched, a persisted marker
+// wins from its first occurrence, and markerless companions expose nothing.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { boundaryRootedTree, REVIEW_BOUNDARY_CUSTOM_TYPE, visibleMessages } from '../session-visibility.js';
+function message(fields) {
+    return fields;
+}
+function contentOf(item) {
+    return item.content;
+}
+const boundary = message({
+    role: 'custom',
+    customType: REVIEW_BOUNDARY_CUSTOM_TYPE,
+    content: 'review boundary',
+    display: true,
+    timestamp: 2,
+});
+const cycleDivider = message({
+    role: 'custom',
+    customType: 'crtr-cycle-divider',
+    content: 'cycle 2 begins',
+    display: true,
+    timestamp: 3,
+});
+const cases = [
+    {
+        name: 'first marker wins even when it is not first, and preserves later cycle dividers',
+        messages: [
+            message({ role: 'user', content: 'inherited origin context', timestamp: 0 }),
+            message({ role: 'assistant', content: 'inherited answer', timestamp: 1 }),
+            boundary,
+            message({ role: 'user', content: 'review message', timestamp: 2 }),
+            cycleDivider,
+            message({ role: 'assistant', content: 'later cycle message', timestamp: 4 }),
+        ],
+        reviewCompanion: true,
+        assertResult: (_input, result) => {
+            assert.deepEqual(result, [boundary, message({ role: 'user', content: 'review message', timestamp: 2 }), cycleDivider, message({ role: 'assistant', content: 'later cycle message', timestamp: 4 })]);
+            assert.equal(result[0], boundary);
+            assert.ok(!result.some((item) => contentOf(item) === 'inherited origin context'));
+            assert.ok(!result.some((item) => contentOf(item) === 'inherited answer'));
+        },
+    },
+    {
+        name: 'ordinary nodes return the exact input reference without a marker',
+        messages: [
+            message({ role: 'user', content: 'ordinary message', timestamp: 0 }),
+            cycleDivider,
+        ],
+        reviewCompanion: false,
+        assertResult: (input, result) => {
+            assert.strictEqual(result, input);
+        },
+    },
+    {
+        name: 'a markerless companion replaces only a compaction summary with a synthetic boundary',
+        messages: [
+            message({
+                role: 'compactionSummary',
+                content: 'summary may include inherited origin context',
+                timestamp: 7,
+            }),
+            message({ role: 'user', content: 'post-compaction review message', timestamp: 8 }),
+        ],
+        reviewCompanion: true,
+        assertResult: (_input, result) => {
+            assert.deepEqual(result, [
+                message({
+                    role: 'custom',
+                    customType: REVIEW_BOUNDARY_CUSTOM_TYPE,
+                    content: 'Earlier conversation with the origin is not shown.',
+                    display: true,
+                    timestamp: 7,
+                }),
+                message({ role: 'user', content: 'post-compaction review message', timestamp: 8 }),
+            ]);
+            assert.ok(!result.some((item) => contentOf(item) === 'summary may include inherited origin context'));
+        },
+    },
+];
+for (const testCase of cases) {
+    test(`visibleMessages: ${testCase.name}`, () => {
+        const input = testCase.messages;
+        const result = visibleMessages(input, { reviewCompanion: testCase.reviewCompanion });
+        testCase.assertResult(input, result);
+    });
+}
+function treeNode(id, entry, children = []) {
+    return { entry: { id, ...entry }, children };
+}
+test('visibleMessages: every markerless non-compaction shape remains synthetic-only', () => {
+    const result = visibleMessages([message({ role: 'user', content: 'inherited context', timestamp: 5 })], { reviewCompanion: true });
+    assert.equal(result.length, 1);
+    assert.equal(result[0]?.customType, REVIEW_BOUNDARY_CUSTOM_TYPE);
+});
+test('boundaryRootedTree drops inherited ancestors and preserves only boundary descendants', () => {
+    const tree = [
+        treeNode('origin', { type: 'message', message: { role: 'user', content: 'PREBOUNDARY_CANARY' } }, [
+            treeNode('inherited-reply', { type: 'message', message: { role: 'assistant', content: 'inherited reply' } }, [
+                treeNode('boundary', { type: 'custom_message', customType: REVIEW_BOUNDARY_CUSTOM_TYPE, content: 'review boundary', display: true }, [
+                    treeNode('review-user', { type: 'message', message: { role: 'user', content: 'review finding' } }),
+                    treeNode('review-assistant', { type: 'message', message: { role: 'assistant', content: 'review resolution' } }),
+                ]),
+            ]),
+        ]),
+    ];
+    const result = boundaryRootedTree(tree);
+    assert.deepEqual(result.map((node) => node.entry.id), ['boundary']);
+    assert.deepEqual(result[0]?.children.map((node) => node.entry.id), ['review-user', 'review-assistant']);
+    assert.equal(JSON.stringify(result).includes('PREBOUNDARY_CANARY'), false);
+});
+test('boundaryRootedTree returns no picker tree for a markerless companion', () => {
+    const tree = [treeNode('origin', { type: 'message', message: { role: 'user', content: 'PREBOUNDARY_CANARY' } })];
+    assert.deepEqual(boundaryRootedTree(tree), []);
+});

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

@@ -32,22 +32,6 @@ export declare function orchestratorContextNote(nodeId: string): string;
  *  `● you`, then its immediate children. Returns '' for a lone root with no
  *  children (nothing to map). Exported for testing. */
 export declare function buildGraphMap(nodeId: string): string;
-/** Minimal identity needed to render the assertion before a node is persisted.
- *  Private human-work birth uses this to freeze the exact kickoff in the same
- *  metadata write that creates the node, before any broker can exist. */
-export interface IdentityAssertionInput {
-    node_id: string;
-    kind: string;
-    mode: string;
-    fork_from?: string | null;
-}
-/** Render the identity assertion for a known or not-yet-persisted node. A fork
- *  copies the source's first-person conversation, so its kickoff names the new
- *  identity and treats the inherited narrative as reference material. */
-export declare function buildIdentityAssertionFor(meta: IdentityAssertionInput): string;
-/** The identity assertion injected at session start for an already-persisted
- *  node. Exported for tests and spawn-time fork kickoff construction. */
-export declare function buildIdentityAssertion(nodeId: string): string;
 /** Why a node was born or woken, as carried from the fired cron to the
  *  injection seam. `ownerName` is the armer's resolved display name when it
  *  still exists (a reaped cron's armer renders as a bare id, never crashes). */
@@ -77,7 +61,11 @@ export declare function cronWakeOrigin(c: Cron, kind: WakeOrigin['kind']): WakeO
  *  carry the signal, and a raw ISO instant is noise an agent cannot cheaply turn
  *  into an elapsed delta. */
 export declare function buildWakeBearings(origin: WakeOrigin): string;
-/** The full boot intro, three top-level sections:
+/** The node-scoped update for a fork whose copied branch already contains a
+ *  full crouter baseline. Shared project and operating context stays in the
+ *  inherited branch; this block replaces only source-owned facts. */
+export declare function buildForkBearings(nodeId: string): string;
+/** The full boot intro, four top-level sections:
  *
  *   1. `<crtr-bearings>` — the orienting facts about THIS node: the identity
  *      assertion (always first, so it overrides any copied-in persona), then a

package/dist/core/runtime/bearings.js

@@ -1,44 +1,14 @@
-// bearings.ts — the boot-intro prose (the <crtr-bearings> orientation block +
-// the <memory kind="knowledge"> catalog that rides beside it), shared by the
-// paths that deliver it so they can never drift:
+// bearings.ts — session orientation shared by every delivery path.
 //
-//   • the context-intro pi-extension injects buildContextBearings() as the
-//     node's first session message in every brand-new chat. The <crtr-bearings>
-//     block opens with the identity assertion (buildIdentityAssertion) that
-//     names the node (id, kind, mode), then a `## Your place in the canvas`
-//     mini-map (ancestry trunk up + immediate children with statuses, via
-//     buildGraphMap) and a `## Your context directory` note; identity leads,
-//     ONLY for a fork, disowns the source's copied first-person narrative as
-//     inherited context — the fix for the `--fork-from` bug where a fork copies
-//     the source's whole conversation and then impersonates it. A non-fork
-//     node's bearings are its FIRST entry, so there is nothing earlier to
-//     disown; it gets only the declarative identity line. The message also
-//     carries the <project_context> block (buildProjectContextBlock), which is
-//     now only the <environment> snapshot: a host/runtime line (platform,
-//     hostname, node, tmux-or-not), the cwd dir listing, and git status.
-//     Project guidance rides the document substrate instead: a workspace's
-//     `.crouter/memory/INDEX.md` declares `applies-to: "."` and surfaces through
-//     an <auto-loaded-context> block when cwd/profile mounts that workspace;
-//     ordinary boot-routed knowledge remains in the <memory kind="knowledge">
-//     block below. No parallel project-context loader lives here (see
-//     `crtr memory read taste/document-substrate`);
-//   • promote.ts folds orchestratorContextNote() into the promotion guidance
-//     dump, so a node that becomes an orchestrator MID-LIFE gets the
-//     orchestrator framing it never received at spawn — it spawned as a base
-//     worker, and the bearings already in its history carry only the base note.
+// A conversation with no inherited crouter bearings receives the full baseline:
+// node identity and graph position, context-directory guidance, routed knowledge,
+// auto-loaded project docs, situational context, and the current environment.
+// A fork whose copied branch already carries that baseline receives only
+// buildForkBearings(): the new node-scoped facts that supersede its source's
+// identity. The copied baseline remains useful reference without being repeated.
 //
-// Base framing (every node): the context dir is durable, shared scratch — the
-// one place other nodes on the canvas can read from, so it is for documents
-// worth a shared reference, NOT a task tracker, and NOT a "future memory-wiped
-// you" stash (a terminal worker has no future cycle — that framing only makes
-// sense once a node is a resident orchestrator). The `<memory kind="knowledge">`
-// block (substrate knowledge docs + node-local docs) rides as a SIBLING of
-// <crtr-bearings> — never nested under the context dir, which would imply the
-// catalog belongs to that one directory rather than spanning all memory scopes.
-//
-// Orchestrator addendum (gated on orchestrator MODE): the dir ALSO survives
-// refresh cycles, so it is where a future cycle of the orchestrator resumes.
-// This across-cycles note is the ONE thing a terminal worker's bearings drop.
+// promote.ts separately delivers orchestratorContextNote() when a base node
+// becomes an orchestrator after birth.
 import { contextDir, getNode, fullName, isSafeNodeId, subscriptionsOf, } from '../canvas/index.js';
 import { execSync } from 'node:child_process';
 import { readdirSync } from 'node:fs';
@@ -292,39 +262,22 @@ export function buildGraphMap(nodeId) {
     }
     return lines.join('\n');
 }
-/** Render the identity assertion for a known or not-yet-persisted node. A fork
- *  copies the source's first-person conversation, so its kickoff names the new
- *  identity and treats the inherited narrative as reference material. */
-export function buildIdentityAssertionFor(meta) {
-    const lines = [`You are node ${meta.node_id} — kind ${meta.kind}, mode ${meta.mode}.`];
-    const forkFrom = meta.fork_from;
+/** The identity assertion injected at session start. A fork names its source
+ *  while treating the copied first-person narrative as reference. */
+function buildIdentityAssertion(nodeId) {
+    const meta = getNode(nodeId);
+    const lines = [`You are node ${nodeId} — kind ${meta?.kind ?? 'general'}, mode ${meta?.mode ?? 'base'}.`];
+    const forkFrom = meta?.fork_from;
     if (forkFrom !== undefined && forkFrom !== null && forkFrom !== '') {
-        // Name the source: a known node id gets its human label; a raw path/uuid
-        // (e.g. a human-work provenance file) passes through as-is — getNode()
-        // requires a safe node-id segment and throws on an arbitrary path, so only
-        // call it when forkFrom actually looks like a node id.
+        // A known node id carries its human label. Paths and session ids remain
+        // opaque provenance rather than being passed to the node-id lookup.
         const src = isSafeNodeId(forkFrom) ? getNode(forkFrom) : null;
         const sourceLabel = src !== null ? `${forkFrom} ("${fullName(src)}")` : forkFrom;
-        lines.push('', `You are a FORK of ${sourceLabel}: at spawn pi COPIED that node's conversation into your ` +
-            `session as a starting point. You are NOT ${sourceLabel}. Everything earlier in this ` +
-            'conversation is THEIR first-person history — inherited reference material, not your own ' +
-            'past. Do not speak or act as them, do not continue their task as if it were yours, and do ' +
-            'not "monitor yourself" as though you were a child they spawned. You inherit none of the ' +
-            'source node’s graph edges and are not responsible for monitoring or managing its children.');
+        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');
 }
-/** The identity assertion injected at session start for an already-persisted
- *  node. Exported for tests and spawn-time fork kickoff construction. */
-export function buildIdentityAssertion(nodeId) {
-    const meta = getNode(nodeId);
-    return buildIdentityAssertionFor({
-        node_id: nodeId,
-        kind: meta?.kind ?? 'general',
-        mode: meta?.mode ?? 'base',
-        fork_from: meta?.fork_from,
-    });
-}
 /** The armer rendered for prose, ROLE-explicit so a newborn never mistakes the
  *  id for its own: `node <id> ("<name>")` when the name resolved, `node <id>
  *  (now gone)` when the armer was reaped, `an unknown node` only if the owner id
@@ -380,7 +333,72 @@ export function buildWakeBearings(origin) {
             `${armer} to fire now. You are its only run, not a recurring job. Your task follows.`;
     return `<crtr-wake>\n${body}\n</crtr-wake>`;
 }
-/** The full boot intro, three top-level sections:
+function managedWorktreeNote(node) {
+    const wt = node?.managed_worktree;
+    if (wt?.state !== 'open')
+        return '';
+    return `Branch: \`${wt.branch}\`\nWorktree: \`${wt.path}\`\nBase: \`${wt.base_ref}\` @ \`${wt.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.`;
+}
+/** The review-companion block — rendered ONLY when a node carries its immutable
+ *  review binding. Names the target file (the document under review), clarifies
+ *  that inherited context belongs to the origin node and is not visible to the
+ *  person, and notes that the visible transcript begins at the boundary marker
+ *  above. */
+function reviewCompanionBlock(meta) {
+    if (meta?.review_binding === undefined || meta?.review_binding === null)
+        return '';
+    const targetFile = meta.review_binding.target_file;
+    return (`You exist for one human review of \`${targetFile}\`. The inherited conversation belongs to ` +
+        `the origin node, not you — carry only the context needed for this review. The person's visible ` +
+        `transcript begins at the boundary marker above; everything earlier is context they cannot see.`);
+}
+/** The node-scoped update for a fork whose copied branch already contains a
+ *  full crouter baseline. Shared project and operating context stays in the
+ *  inherited branch; this block replaces only source-owned facts. */
+export function buildForkBearings(nodeId) {
+    const node = getNode(nodeId);
+    const bearings = [
+        '<crtr-bearings>',
+        buildIdentityAssertion(nodeId),
+        '',
+        'The source node’s earlier task, graph position, lifecycle, children, schedules, worktree, situational context, and context-directory path do not carry over. Shared conversation, project, and operating context remain reference material.',
+        '',
+        '## Your node now',
+        `Lifecycle: ${node?.lifecycle ?? 'terminal'}.`,
+    ];
+    const map = buildGraphMap(nodeId);
+    if (map === '') {
+        bearings.push('Canvas: independent root with no parent or inherited graph edges.');
+    }
+    else {
+        bearings.push('', map);
+    }
+    bearings.push(`Context directory: \`${contextDir(nodeId)}\` (\`$CRTR_CONTEXT_DIR\`). Use this path in place of every source-node context path above.`);
+    const forkFrom = node?.fork_from;
+    const source = forkFrom !== undefined && forkFrom !== null && isSafeNodeId(forkFrom)
+        ? getNode(forkFrom)
+        : null;
+    if (node !== null && (source === null || source.cwd !== node.cwd)) {
+        bearings.push(`Working directory: \`${node.cwd}\`.`);
+    }
+    if (node !== null && (source === null || source.profile_id !== node.profile_id)) {
+        const profileSection = profileNote(nodeId);
+        if (profileSection !== '')
+            bearings.push(profileSection);
+    }
+    const worktree = managedWorktreeNote(node);
+    if (worktree !== '')
+        bearings.push('', '## Your managed worktree', worktree);
+    if (node?.mode === 'orchestrator')
+        bearings.push('', orchestratorContextNote(nodeId));
+    const review = reviewCompanionBlock(node);
+    if (review !== '')
+        bearings.push('', review);
+    bearings.push('', 'The first real user message after these bearings is your mandate.', '</crtr-bearings>');
+    const situational = situationalContextBlock(nodeId);
+    return [bearings.join('\n'), situational].filter((s) => s !== '').join('\n');
+}
+/** The full boot intro, four top-level sections:
  *
  *   1. `<crtr-bearings>` — the orienting facts about THIS node: the identity
  *      assertion (always first, so it overrides any copied-in persona), then a
@@ -407,10 +425,9 @@ export function buildContextBearings(nodeId) {
     const profileSection = profileNote(nodeId);
     if (profileSection !== '')
         bearings.push('', profileSection);
-    const wt = node?.managed_worktree;
-    if (wt?.state === 'open') {
-        bearings.push('', '## Your managed worktree', `Branch: \`${wt.branch}\`\nWorktree: \`${wt.path}\`\nBase: \`${wt.base_ref}\` @ \`${wt.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.`);
-    }
+    const worktree = managedWorktreeNote(node);
+    if (worktree !== '')
+        bearings.push('', '## Your managed worktree', worktree);
     // Orchestrator-only: the across-cycles framing (a terminal has no future cycle).
     if (node?.mode === 'orchestrator')
         bearings.push('', orchestratorContextNote(nodeId));

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

@@ -1,6 +1,7 @@
 import type { AgentSession, AgentSessionEvent, RpcExtensionUIRequest, RpcExtensionUIResponse, RpcSessionState, SessionEntry, SessionInfo, SettingsConfig, SessionStats } from '@earendil-works/pi-coding-agent';
 import type { Api, ImageContent, Model } from '@earendil-works/pi-ai';
 import type { BrokerErrorFrame } from '../../api/dto/broker.js';
+import type { ToolGroupSummary } from '../../shared/tool-groups.js';
 /** pi's own RPC types, re-exported unchanged. `broker-protocol` stays the one
  *  import site for the wire union; the shapes themselves are pi's, versioned by
  *  pi, so a pi change is a compile error here instead of silent drift. */
@@ -45,6 +46,14 @@ export interface BrokerSnapshot {
         }>;
         title: string | undefined;
     };
+    /** Broker-owned summaries keyed by the first tool-call id in each group.
+     * Structured objects with bullets, nodesSpawned, and filesEdited.
+     * Optional so snapshots from an older live runtime remain readable. */
+    toolGroupSummaries?: Record<string, ToolGroupSummary>;
+    /** The broker-selected normal activity label for the current turn. Optional so
+     *  viewers can still attach to an older live runtime; they fall back to
+     *  `Working...` when it is absent. */
+    workingActivity?: string;
 }
 /** Opens the connection and FIXES this client's role for its lifetime. A repeated
  *  `hello` on an already-helloed socket never changes the established role. */
@@ -67,6 +76,8 @@ export interface PromptFrame {
     type: 'prompt';
     text: string;
     images?: ImageContent[];
+    /** Abort the active turn before starting this prompt. Used by the attach viewer's whip action so its command replaces, rather than joins, in-flight work. */
+    interrupt?: true;
 }
 export interface SteerFrame {
     type: 'steer';
@@ -309,16 +320,16 @@ export interface CloneFrame {
 export interface ShareFrame {
     type: 'share';
 }
-/** Reload credentials + refresh model registry after a viewer-side auth change.
- *  Open to any client — reload_auth is an idempotent local re-read that doesn't
- *  steer the conversation, so the daemon's canvas-wide fan (one /login → every
- *  live broker) can trigger it from an observer connection. Broker handler:
- *  services.authStorage.reload() +
- *  services.modelRegistry.refresh(). */
+/** Reload credentials + the local model-runtime availability snapshot after a
+ *  viewer-side auth change. Open to any client — reload_auth is an idempotent
+ *  local re-read that doesn't steer the conversation, so the daemon's
+ *  canvas-wide fan (one /login → every live broker) can trigger it from an
+ *  observer connection. The broker refreshes with network catalogs disabled,
+ *  then reconciles eligible logical routes before admitting the next idle prompt. */
 export interface ReloadAuthFrame {
     type: 'reload_auth';
 }
-/** Read live source coordinates for an ask-time Humanloop fork. This is an
+/** Read live source coordinates for an ask-time human fork. This is an
  * observer-safe getter only: it never creates a branch, switches a session, or
  * changes the source manager. */
 export interface GetHumanForkCoordinatesFrame {
@@ -349,6 +360,11 @@ export interface WelcomeFrame {
  *  the other four learn nothing); the PAYLOAD is pi's — `Model`, exactly what
  *  pi's own `set_model` response carries and what `snapshot.state.model` holds.
  *  Undefined when the engine has none. */
+export interface WorkingActivityFrame {
+    type: 'working_activity';
+    /** Full display label selected from the user's configured gerunds. */
+    activity: string;
+}
 export interface ModelChangedFrame {
     type: 'model_changed';
     model: Model<any> | undefined;
@@ -563,10 +579,17 @@ export interface ExtensionUIDismissFrame {
     type: 'extension_ui_dismiss';
     id: string;
 }
+/** A completed broker-side tool-group summary. The viewer owns presentation;
+ * this frame carries the durable group key and structured summary object. */
+export interface ToolGroupSummaryFrame {
+    type: 'tool_group_summary';
+    key: string;
+    summary: ToolGroupSummary;
+}
 /** Everything the broker can send. Live `AgentSessionEvent`s are relayed
  *  verbatim (the broker adds nothing); the broker's own control frames carry
  *  non-colliding `type` discriminants. */
-export type BrokerToClient = WelcomeFrame | ModelChangedFrame | ErrorFrame | AckFrame | BrokerDataFrame | BashStartFrame | BashOutputFrame | BashEndFrame | ExtensionUIRequestFrame | ExtensionUIDismissFrame | AgentSessionEvent;
+export type BrokerToClient = WelcomeFrame | WorkingActivityFrame | ModelChangedFrame | ErrorFrame | AckFrame | BrokerDataFrame | BashStartFrame | BashOutputFrame | BashEndFrame | ExtensionUIRequestFrame | ExtensionUIDismissFrame | ToolGroupSummaryFrame | AgentSessionEvent;
 /** Encode one frame as a single newline-terminated JSON line. */
 export declare function encodeFrame(frame: ClientToBroker | BrokerToClient): string;
 /** Byte bounds for a {@link FrameDecoder} (C5). */

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

@@ -5,6 +5,15 @@ import { type BrokerSdkConfig } from './launch.js';
 import { type BrokerEngine } from './broker-sdk.js';
 import { type KnownStreamWaitControl } from './stream-watchdog.js';
 import { FrameDecoder, type BrokerSnapshot, type BrokerToClient, type ClientRole, type RpcExtensionUIRequest, type RpcExtensionUIResponse } 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 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 pinned pi SDK never yields `session.model === undefined` for a model-less
  * boot: Agent.createMutableAgentState() falls back to a hardcoded
@@ -74,6 +83,11 @@ export declare function isLeadingEngineCommand(text: string, session: {
         name: string;
     }>;
 }): boolean;
+/** A `steer` frame normally maps directly to pi's steer queue. Engine commands,
+ * skills, and templates must instead pass through prompt()'s leading-command
+ * preflight; with streamingBehavior:'steer', ordinary expanded text still lands
+ * in the same queue. */
+export declare function resolveSteerCall(text: string, session: Parameters<typeof isLeadingEngineCommand>[1]): 'prompt' | 'steer';
 /**
  * Enumerate every leading-token STRING this session's engine would
  * independently consume as a leading command/skill/template dispatch BEFORE
@@ -205,7 +219,7 @@ interface PendingDialog {
  *  bash children. No-op before the session is built or after a clean dispose. */
 export declare function disposeActiveSession(): void;
 export declare function runBroker(nodeId: string, startupAt?: bigint, startupTs?: string): Promise<void>;
-export declare function snapshotMessages(session: CreateAgentSessionResult['session']): BrokerSnapshot['messages'];
+export declare function snapshotMessages(session: CreateAgentSessionResult['session'], reviewCompanion?: boolean): BrokerSnapshot['messages'];
 export declare function buildBrokerSession(engine: BrokerEngine, cfg: BrokerSdkConfig): Promise<{
     session: CreateAgentSessionResult['session'];
     services: AgentSessionServices;