@north-light/crouter 0.3.269 → 0.3.271

package/dist/core/command-hooks/transport/exec-lifecycle.js

@@ -0,0 +1,152 @@
+import { randomBytes } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { PROCESS_GROUP_KILL_GRACE_MS, posixProcessGroupSpawnOptions, terminateProcessGroup } from '../../../hook-process.js';
+import { isRecord } from '../../../shared/predicates.js';
+import { diag } from '../../io.js';
+const MAX_STDOUT = 10 * 1024 * 1024;
+export const LIFECYCLE_HOOK_TIMEOUT_MS = 5_000;
+export const LIFECYCLE_EVENT_BUDGET_MS = 10_000;
+/** Runs one lifecycle hook. The node launch remains authoritative on every failure. */
+export async function invokeLifecycleHook(hook, invocation, timeoutMs) {
+    try {
+        const request = {
+            protocolVersion: 1,
+            op: hook.op,
+            event: hook.event,
+            phase: hook.phase,
+            operationId: randomBytes(16).toString('hex'),
+            node: invocation.node,
+            runtime: invocation.runtime,
+            context: { cwd: invocation.node.cwd },
+        };
+        const result = await runLifecycleProcess(hook, JSON.stringify(request), timeoutMs);
+        if (result.signal !== null)
+            throw new Error(`executable was killed by signal ${result.signal}`);
+        const envelope = parseEnvelope(result.stdout);
+        if (envelope.ok) {
+            if (result.status !== 0)
+                diag(`crtr: ${label(hook)} returned ok:true but exited ${result.status} (honoring the envelope)`);
+            return;
+        }
+        diag(`crtr: ${label(hook)} failed: ${envelope.error.code}: ${envelope.error.message}`);
+    }
+    catch (error) {
+        diag(`crtr: ${label(hook)} failed: ${describeError(error)}`);
+    }
+}
+/** Executes lifecycle hooks in discovery order, within one bounded start-event budget. */
+export async function invokeLifecycleHooks(hooks, invocation) {
+    const deadline = Date.now() + LIFECYCLE_EVENT_BUDGET_MS;
+    for (const hook of hooks) {
+        const remaining = deadline - Date.now();
+        // A timed-out hook must be reaped before launch can proceed. Reserve the
+        // process-group termination grace inside the event budget rather than
+        // letting the final cleanup extend the node-start critical path.
+        const timeoutMs = Math.min(LIFECYCLE_HOOK_TIMEOUT_MS, remaining - PROCESS_GROUP_KILL_GRACE_MS);
+        if (timeoutMs <= 0) {
+            diag(`crtr: lifecycle hook event ${hook.event} exceeded its ${LIFECYCLE_EVENT_BUDGET_MS}ms aggregate budget; skipped ${label(hook)}`);
+            return;
+        }
+        await invokeLifecycleHook(hook, invocation, timeoutMs);
+    }
+}
+async function runLifecycleProcess(hook, input, timeoutMs) {
+    let child;
+    try {
+        child = spawn(hook.executable, ['--crtr-hook-protocol', '1'], {
+            cwd: hook.plugin.root,
+            env: process.env,
+            stdio: ['pipe', 'pipe', 'inherit'],
+            ...posixProcessGroupSpawnOptions(),
+        });
+    }
+    catch (error) {
+        throw new Error(`executable could not be run (${describeError(error)})`);
+    }
+    return new Promise((resolve, reject) => {
+        let stdoutBytes = 0;
+        const stdout = [];
+        let failure;
+        let closed = false;
+        let cleaned = false;
+        let status = null;
+        let signal = null;
+        let timeout;
+        const finish = () => {
+            if (!closed || (failure !== undefined && !cleaned))
+                return;
+            if (timeout !== undefined)
+                clearTimeout(timeout);
+            if (failure?.kind === 'timeout')
+                return reject(new Error(`executable timed out after ${timeoutMs}ms`));
+            if (failure?.kind === 'output_limit')
+                return reject(new Error('stdout exceeded the 10 MiB cap'));
+            if (failure?.kind === 'spawn')
+                return reject(new Error(`executable could not be run (${describeError(failure.error)})`));
+            if (failure?.kind === 'cleanup')
+                return reject(new Error(`executable cleanup failed (${describeError(failure.error)})`));
+            resolve({ stdout: Buffer.concat(stdout).toString('utf8'), status, signal });
+        };
+        const terminate = (reason) => {
+            if (failure !== undefined)
+                return;
+            failure = reason;
+            if (timeout !== undefined)
+                clearTimeout(timeout);
+            void terminateProcessGroup(child).then(() => { cleaned = true; finish(); }, (error) => { failure = { kind: 'cleanup', error }; cleaned = true; finish(); });
+        };
+        child.stdout.on('data', (chunk) => {
+            stdoutBytes += chunk.byteLength;
+            if (stdoutBytes > MAX_STDOUT)
+                return terminate({ kind: 'output_limit' });
+            stdout.push(chunk);
+        });
+        child.once('error', (error) => {
+            if (child.pid === undefined) {
+                failure = { kind: 'spawn', error };
+                closed = true;
+                cleaned = true;
+                finish();
+                return;
+            }
+            terminate({ kind: 'spawn', error });
+        });
+        child.once('close', (nextStatus, nextSignal) => {
+            status = nextStatus;
+            signal = nextSignal;
+            closed = true;
+            finish();
+        });
+        timeout = setTimeout(() => terminate({ kind: 'timeout' }), timeoutMs);
+        child.stdin.end(input);
+    });
+}
+function parseEnvelope(stdout) {
+    let value;
+    try {
+        value = JSON.parse(stdout.trim());
+    }
+    catch {
+        throw new Error('stdout was not a single JSON envelope');
+    }
+    if (!isRecord(value) || value['protocolVersion'] !== 1)
+        throw new Error('stdout was not a protocolVersion: 1 envelope');
+    if (value['ok'] === true && exactKeys(value, ['protocolVersion', 'ok']))
+        return { protocolVersion: 1, ok: true };
+    if (value['ok'] !== false || !exactKeys(value, ['protocolVersion', 'ok', 'error']))
+        throw new Error('response envelope had missing or extra fields');
+    const error = value['error'];
+    if (!isRecord(error) || !exactKeys(error, ['code', 'message'], ['next']) || typeof error['code'] !== 'string' || error['code'] === '' || typeof error['message'] !== 'string' || error['message'] === '' || (error['next'] !== undefined && typeof error['next'] !== 'string')) {
+        throw new Error('failure envelope had invalid error fields');
+    }
+    return { protocolVersion: 1, ok: false, error: { code: error['code'], message: error['message'], ...(error['next'] === undefined ? {} : { next: error['next'] }) } };
+}
+function exactKeys(value, required, optional = []) {
+    return required.every((key) => Object.hasOwn(value, key)) && Object.keys(value).every((key) => required.includes(key) || optional.includes(key));
+}
+function label(hook) {
+    return `plugin "${hook.plugin.name}" lifecycle hook "${hook.op}" for ${hook.event}`;
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/core/human/feedback-companion.js

@@ -92,7 +92,7 @@ export async function realizeFeedbackCompanion(args) {
         // The bind deadline below only a live broker can meet, so a capacity
         // refusal must surface here and discard the companion — freezing would
         // burn the whole deadline waiting for a launch that is not coming.
-        reviveNode(node.node_id, { resume: false, capacity: 'refuse' });
+        await reviveNode(node.node_id, { resume: false, capacity: 'refuse' });
         if (!await awaitCompanionBind(node.node_id, COMPANION_BIND_DEADLINE_MS)) {
             throw new Error(`feedback companion did not bind within ${COMPANION_BIND_DEADLINE_MS}ms`);
         }

package/dist/core/review/realize.js

@@ -172,7 +172,7 @@ export async function realizeReview(reviewId) {
     // Realization is bounded by the bind deadline below, which only a live broker
     // can meet: refuse at the cap rather than freeze into a certain timeout.
     if (companion.pi_session_id === null)
-        reviveNode(companion.node_id, { resume: false, capacity: 'refuse' });
+        await reviveNode(companion.node_id, { resume: false, capacity: 'refuse' });
     // R4: session_start is the durable bind boundary.
     if (!await awaitCompanionBind(review.companion_node_id, COMPANION_BIND_DEADLINE_MS)) {
         throw companionUnbound(review.review_id, COMPANION_BIND_DEADLINE_MS);

package/dist/core/runtime/broker/engine-drive.d.ts

@@ -1,3 +1,4 @@
+import type { MessageOrigin } from '../stamp/protocol.js';
 import type { ClientToBroker } from '../broker-protocol.js';
 import type { BrokerClient, BrokerClientRegistry } from './client-registry.js';
 import type { EventProjection } from './event-projection.js';
@@ -9,9 +10,18 @@ import type { RebindDriver } from './rebind.js';
 import type { ToolGroupTracker } from './tool-groups.js';
 import type { PromptDispatchTracker } from './turn-ignition.js';
 import type { TurnAdmissionGate } from './turn-admission.js';
-/** The frames that drive the live engine — the viewer's input vocabulary. */
-export type DriveFrame = Extract<ClientToBroker, {
-    type: 'prompt' | 'steer' | 'follow_up' | 'abort' | 'bash';
+/** The frames that drive the live engine. A daemon delivery carries its
+ *  provenance through admission because only the resolved route can decide
+ *  whether the resulting run is internal. */
+type DeliveredInput = {
+    delivery?: {
+        origin?: MessageOrigin;
+    };
+};
+export type DriveFrame = (Extract<ClientToBroker, {
+    type: 'prompt' | 'follow_up';
+}> & DeliveredInput) | Extract<ClientToBroker, {
+    type: 'steer' | 'abort' | 'bash';
 }>;
 export type EngineDriver = (client: BrokerClient, frame: DriveFrame) => Promise<unknown> | undefined;
 export declare function createEngineDriver(deps: {
@@ -26,3 +36,4 @@ export declare function createEngineDriver(deps: {
     toolGroups: ToolGroupTracker;
     turnAdmission: TurnAdmissionGate;
 }): EngineDriver;
+export {};

package/dist/core/runtime/broker/engine-drive.js

@@ -2,6 +2,8 @@ import { emitEvent } from '../../events/emit.js';
 import { operationIdContext } from '../../events/operation-id.js';
 import { promptWithAdvertisedCommandInvocation } from '../advertised-command-invocation.js';
 import { heldDeferredInboxPromptJoin } from './held-deferred-inbox.js';
+import { announceMessageOrigin } from '../stamp/channel.js';
+import { clearTurnVisibility, currentTurnVisibility, setTurnVisibility, } from '../turn-visibility.js';
 import { chooseGuidanceDeliveryMode, promptWithNextTurnGuidance, resolveEngineRoute, resolveSteerCall, } from './engine-routing.js';
 export function createEngineDriver(deps) {
     const { registry, replies, session, dispatches, memoryRefs, authReloadGate, rebind, projection, toolGroups, turnAdmission, } = deps;
@@ -47,6 +49,20 @@ export function createEngineDriver(deps) {
             const route = resolveEngineRoute(frame, session().isStreaming);
             const promptOptions = route.call === 'prompt' ? route.options : undefined;
             const guidance = memoryRefs.guidanceFor(frame.text);
+            const deliveryIsInternal = frame.delivery?.origin?.type === 'runtime'
+                && frame.delivery.origin.kind === 'park'
+                && route.call === 'prompt'
+                && route.options.streamingBehavior === undefined;
+            const announceDelivery = () => {
+                if (frame.delivery === undefined)
+                    return;
+                const visibility = deliveryIsInternal ? 'internal' : undefined;
+                if (frame.delivery.origin === undefined) {
+                    setTurnVisibility('visible');
+                    return;
+                }
+                announceMessageOrigin(frame.text, frame.delivery.origin, visibility);
+            };
             const prompt = async () => {
                 // Both human surfaces converge at this admitted boundary. The watcher
                 // claims held deferred mail before the prompt body, but its cursor stays
@@ -60,7 +76,19 @@ export function createEngineDriver(deps) {
                         // replay. A person's live prompt is not replayable, so it must run.
                     }
                 }
-                await session().prompt(frame.text, { ...promptOptions, preflightResult: release });
+                announceDelivery();
+                registry.broadcast({
+                    type: 'turn_visibility',
+                    visibility: currentTurnVisibility(),
+                });
+                try {
+                    await session().prompt(frame.text, { ...promptOptions, preflightResult: release });
+                }
+                catch (error) {
+                    if (deliveryIsInternal)
+                        clearTurnVisibility();
+                    throw error;
+                }
             };
             if (guidance === null) {
                 if (route.call === 'prompt') {

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

@@ -1,7 +1,6 @@
 import { SITUATIONAL_CONTEXT_CUSTOM_TYPE } from '../../../shared/generated-context.js';
 import { emitEvent } from '../../events/emit.js';
 import { normalizeSnapshotTail } from '../broker-protocol.js';
-import { announceMessageOrigin } from '../stamp/channel.js';
 export function createClientHandlers(deps) {
     const { registry, replies, session, driveEngine, turnAcceptance, pendingDialogs, sendWelcome, replayExtraPendingDialogsTo, disposeAndExit, } = deps;
     const { notWritable, ackTo } = replies;
@@ -83,13 +82,13 @@ export function createClientHandlers(deps) {
             };
             if (via === 'prompt')
                 turnAcceptance.waitFor(ackAccepted);
-            // The daemon knows who authored this body; the stamp writer lives here.
-            if (frame.origin !== undefined)
-                announceMessageOrigin(frame.text, frame.origin);
             const outcome = driveEngine(client, {
                 type: 'prompt',
                 text: frame.text,
                 ...(frame.images !== undefined ? { images: frame.images } : {}),
+                delivery: {
+                    ...(frame.origin === undefined ? {} : { origin: frame.origin }),
+                },
             });
             if (via === 'steer' || outcome === undefined) {
                 turnAcceptance.cancel(ackAccepted);

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

@@ -6,6 +6,7 @@ import { operationIdContext } from '../../events/operation-id.js';
 import { installPersonaTransitionGate } from '../broker-persona-guidance.js';
 import { abortSessionFromExtension } from './extension-abort.js';
 import { clearFault, invalidateProviderRetryEpisode, readFault } from '../fault.js';
+import { clearTurnVisibility } from '../turn-visibility.js';
 const MAX_ADMITTED_REPLACEMENTS = 2;
 const REPLACEMENT_DEADLINE_MS = 30_000;
 const REPLACEMENT_DEADLINE_EXCEEDED = Symbol('replacement-deadline-exceeded');
@@ -302,6 +303,12 @@ export class RebindDriver {
         catch (err) {
             emitEvent({ level: 'debug', event: 'broker.runtime.diagnostic', fields: { message: `event relay threw: ${String(err)}` } });
         }
+        finally {
+            // Projection sees the settlement while the run is still internal; every
+            // later input and output fails open to visible after this boundary.
+            if (event.type === 'agent_settled')
+                clearTurnVisibility();
+        }
     }
     ackTo(client, op, ok = true, detail, id) {
         this.deps.registry.sendFrame(client, { type: 'ack', for: op, ok, ...(detail !== undefined ? { detail } : {}), ...(id !== undefined ? { id } : {}) });

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

@@ -2,7 +2,7 @@ import type { AgentSession, AgentSessionEvent, RpcExtensionUIRequest, RpcExtensi
 import type { Api, ImageContent, Model } from '@earendil-works/pi-ai';
 import type { BrokerErrorFrame, BrokerNodeNamedFrame } from '../../api/dto/broker.js';
 import type { ToolGroupSummary } from '../../shared/tool-groups.js';
-import type { MessageOrigin } from './stamp/protocol.js';
+import type { MessageOrigin, MessageVisibility } from './stamp/protocol.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. */
@@ -22,6 +22,10 @@ export interface BrokerSnapshot {
     /** Stable session-entry ids aligned 1:1 with `messages`. Absent when the
      * session manager cannot expose its entry tree. */
     messageIds?: string[];
+    /** Presentation visibility aligned 1:1 with `messages`. */
+    messageVisibility: MessageVisibility[];
+    /** Presentation visibility of the run currently owned by the engine. */
+    turnVisibility: MessageVisibility;
     stats: SessionStats;
     /** pi's OWN `get_state` payload, verbatim — not a mirror. `buildSnapshot`
      *  fills it exactly as pi's `rpc-mode.js` does, from the same getters, so a
@@ -398,6 +402,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 TurnVisibilityFrame {
+    type: 'turn_visibility';
+    /** Presentation visibility of the run whose native events follow. */
+    visibility: MessageVisibility;
+}
 export interface WorkingActivityFrame {
     type: 'working_activity';
     /** Full display label selected from the user's configured gerunds. */
@@ -643,7 +652,7 @@ export interface ToolGroupSummaryFrame {
 /** 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 | WorkingActivityFrame | ModelChangedFrame | ResourcesReloadedFrame | ErrorFrame | NodeNamedFrame | AckFrame | BrokerDataFrame | BashStartFrame | BashOutputFrame | BashEndFrame | ExtensionUIRequestFrame | ExtensionUIDismissFrame | ToolGroupSummaryFrame | AgentSessionEvent;
+export type BrokerToClient = WelcomeFrame | TurnVisibilityFrame | WorkingActivityFrame | ModelChangedFrame | ResourcesReloadedFrame | ErrorFrame | NodeNamedFrame | 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

@@ -29,7 +29,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'], boundaryReviewId?: string): import("./session-cycles.js").IdentifiedMessage[] | undefined;
+export declare function snapshotMessages(session: CreateAgentSessionResult['session'], boundaryReviewId?: string): import("./session-visibility.js").ProjectedMessage[] | undefined;
 export declare function buildBrokerSession(engine: BrokerEngine, cfg: BrokerSdkConfig): Promise<{
     session: CreateAgentSessionResult['session'];
     services: AgentSessionServices;

package/dist/core/runtime/broker.js

@@ -40,7 +40,8 @@ import { modelRequestFromConfig, selectInitialModelRoute, unregisteredConcreteMo
 import { KNOWN_STREAM_WAIT_UI } from './stream-watchdog.js';
 import { probeOnline as probeOnlineReal } from './connectivity.js';
 import { CRTR_CYCLE_CUSTOM_TYPE, cycleAwareMessages } from './session-cycles.js';
-import { visibleMessages } from './session-visibility.js';
+import { projectTranscript } from './session-visibility.js';
+import { currentTurnVisibility } from './turn-visibility.js';
 import { isUnknownModel } from './model-selection.js';
 import { BrokerClientRegistry } from './broker/client-registry.js';
 import { ToolGroupTracker } from './broker/tool-groups.js';
@@ -397,6 +398,9 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
         return ({
             messages,
             ...(retained === undefined ? {} : { messageIds: retained.map(({ id }) => id) }),
+            messageVisibility: retained?.map(({ visibility }) => visibility)
+                ?? messages.map(() => 'visible'),
+            turnVisibility: currentTurnVisibility(),
             stats: liveSession.getSessionStats(),
             // pi's `get_state` (rpc-mode.js), field for field, from the same getters.
             // The ONE divergence: a model-less session (undefined OR the SDK
@@ -754,11 +758,17 @@ export function snapshotMessages(session, boundaryReviewId) {
     // payload), narrower than `CycleSessionManagerLike`'s structural read of the
     // `crtr-cycle` marker's `{cycle, fromLeaf}` shape — the fields we read off it
     // are ones ONLY this module's own `appendCustomEntry` call (above) ever writes.
-    const messages = cycleAwareMessages(session.sessionManager);
+    const manager = session.sessionManager;
+    const messages = cycleAwareMessages(manager);
     if (messages !== undefined) {
         hydratePersistedAdvertisedCommandMessages(messages.map(({ message }) => message));
     }
-    return messages === undefined ? undefined : visibleMessages(messages, { boundaryReviewId });
+    return messages === undefined
+        ? undefined
+        : projectTranscript(messages, {
+            boundaryReviewId,
+            sessionEntries: manager.getEntries?.(),
+        });
 }
 // resolveLaunchModel — the SOLE launch model-selection policy, module-scoped
 // so both buildForManager (initial boot, inside buildBrokerSession below) and

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

@@ -47,9 +47,8 @@ export interface FleetRegistry {
     get(nodeId: string): FleetEntry | undefined;
     /** The capacity count: registered brokers only, excluding reservations. */
     size(): number;
-    /** Every slot the cap accounts for — registered brokers plus in-flight
-     *  reservations (a launch that has claimed a slot but not yet registered, and
-     *  an exited broker whose exit-policy job has not yet run). */
+    /** Every slot the cap accounts for — registered brokers plus launch
+     *  reservations that have not registered yet. */
     occupancy(): number;
     /** Claim a slot for `nodeId`. True means the caller may launch; false means
      *  the cap is reached and the caller must freeze or refuse. Idempotent — a
@@ -62,9 +61,9 @@ export interface FleetRegistry {
     /** Drop an entry without policy (terminal exits + close paths). */
     forget(nodeId: string): void;
     /** Wired by `headlessBrokerHost.launch` to the handle's `exited` promise.
-     *  Removes the entry (freeing the capacity slot), then enqueues an
-     *  exit-policy job on the daemon's serial work lane — policy never runs
-     *  inline on the Node event callback (design D-3). */
+     *  Removes the entry (freeing the capacity slot), then enqueues its
+     *  observation on the daemon's serial work lane — it never runs inline on
+     *  the Node event callback (design D-3). */
     onChildExit(nodeId: string, status: FleetExitStatus): void;
     /** Test seam — delivers a synthetic exit through the SAME path as
      *  onChildExit, so fabricated-row tests drive policy without a process. */

package/dist/core/runtime/node-read.d.ts

@@ -32,6 +32,8 @@ export interface NodeMessagesPageRead {
     messages: unknown[];
     /** Stable session-entry ids aligned 1:1 with `messages`. */
     messageIds?: string[];
+    /** Presentation visibility aligned 1:1 with `messages`. */
+    messageVisibility: Array<'visible' | 'internal'>;
     nextCursor: string | null;
 }
 export interface NodeMessagesPageOptions {

package/dist/core/runtime/node-read.js

@@ -18,7 +18,7 @@ import { SessionManager } from './broker-sdk.js';
 import { openModelRegistry } from './model-registry.js';
 import { BUILTIN_SLASH_COMMANDS } from './pi-vendored.js';
 import { cycleAwareMessages } from './session-cycles.js';
-import { visibleMessages } from './session-visibility.js';
+import { projectTranscript } from './session-visibility.js';
 import { normalizeToolGroupSummaryRecord } from '../../shared/tool-groups.js';
 /** A session `.jsonl` records only `{ provider, modelId }` — pi never persists a
  *  whole `Model`. Resolve it back through pi's own registry so a dormant
@@ -149,10 +149,10 @@ function readToolGroupSummaries(nodeId) {
         return {};
     }
 }
-/** Reconstruct the visible message history from a stable at-rest session copy.
+/** Reconstruct transcript messages from a stable at-rest session copy.
  * Both snapshot and paged reads use this one path so their histories cannot
  * diverge. */
-async function reconstructVisibleMessages(nodeId) {
+async function reconstructTranscript(nodeId) {
     const node = getNode(nodeId);
     if (node === null) {
         throw new InputError({ error: 'not_found', message: `no node: ${nodeId}`, field: 'id', next: 'List nodes with `crtr node inspect list`.' });
@@ -174,7 +174,10 @@ async function reconstructVisibleMessages(nodeId) {
         }
         const identified = reconstructed === undefined
             ? undefined
-            : visibleMessages(reconstructed, { boundaryReviewId: node.review_binding?.review_id });
+            : projectTranscript(reconstructed, {
+                boundaryReviewId: node.review_binding?.review_id,
+                sessionEntries: manager.getEntries(),
+            });
         const messages = identified?.map(({ message }) => message) ?? context.messages;
         return {
             sessionFile,
@@ -228,10 +231,13 @@ function encodeMessagesCursor(before) {
 /** Reconstruct a persisted session without launching its broker. Backs the
  * machine-readable snapshot endpoint and the human transcript render. */
 export async function readNodeSnapshot(nodeId) {
-    const read = await reconstructVisibleMessages(nodeId);
+    const read = await reconstructTranscript(nodeId);
     const snapshot = {
         messages: read.messages,
         ...(read.identified === undefined ? {} : { messageIds: read.identified.map(({ id }) => id) }),
+        messageVisibility: read.identified?.map(({ visibility }) => visibility)
+            ?? read.messages.map(() => 'visible'),
+        turnVisibility: 'visible',
         stats: statsFromMessages(read.messages, read.sessionId, read.sessionFile),
         // pi's `get_state` shape (RpcSessionState), reconstructed offline: the
         // live-only fields report their at-rest values (nothing is streaming or
@@ -284,15 +290,16 @@ export async function readNodeMessagesPage(nodeId, { cursor, limit = 200 }) {
     // transcript read is how a UI opens a new conversation. Only this paged read
     // can answer honestly — `/snapshot` would have to invent the engine state a
     // never-run node does not have, so it and the raw `/session` export still
-    // reject the same state through `reconstructVisibleMessages`.
+    // reject the same state through `reconstructTranscript`.
     // Same shape a session-file-backed empty read produces: `messageIds` stays
     // aligned 1:1 with `messages` (an absent `message_ids` would claim this read
     // cannot identify entries, which is a different statement than "there are
     // none"), and `nextCursor: null` is the same end-of-history marker an
     // exhausted backward walk returns.
-    if (readableSessionFile(nodeId) === null)
-        return { messages: [], messageIds: [], nextCursor: null };
-    const { messages, identified } = await reconstructVisibleMessages(nodeId);
+    if (readableSessionFile(nodeId) === null) {
+        return { messages: [], messageIds: [], messageVisibility: [], nextCursor: null };
+    }
+    const { messages, identified } = await reconstructTranscript(nodeId);
     const before = cursor === undefined ? messages.length : decodeMessagesCursor(cursor, messages.length);
     let start = Math.max(0, before - limit);
     while (start > 0
@@ -305,6 +312,8 @@ export async function readNodeMessagesPage(nodeId, { cursor, limit = 200 }) {
     return {
         messages: page?.map(({ message }) => message) ?? messages.slice(start, before),
         ...(page === undefined ? {} : { messageIds: page.map(({ id }) => id) }),
+        messageVisibility: page?.map(({ visibility }) => visibility)
+            ?? messages.slice(start, before).map(() => 'visible'),
         nextCursor: start === 0 ? null : encodeMessagesCursor(start),
     };
 }

package/dist/core/runtime/nodes.js

@@ -12,7 +12,7 @@
 //             learns when the work finishes — this seeds the subscription
 //             graph to mirror the spawn structure. A `spawned_by` audit edge
 //             is also recorded.
-import { envHomeOverride } from '../../shared/env.js';
+import { envHomeOverride, envRuntimeHomeOverride } from '../../shared/env.js';
 import { randomBytes } from 'node:crypto';
 import { mkdirSync } from 'node:fs';
 import { createNode, getNode, getRow, subscribe, recordSpawn, subscribersOf, contextDir, } from '../canvas/index.js';
@@ -206,6 +206,11 @@ export function nodeEnv(meta) {
     const home = envHomeOverride();
     if (home !== undefined && home !== '')
         env['CRTR_HOME'] = home;
+    // Propagate an explicit runtime home so broker-side `crtr` invocations use
+    // the same installed generation despite an isolated HOME.
+    const runtimeHome = envRuntimeHomeOverride();
+    if (runtimeHome !== undefined && runtimeHome !== '')
+        env['CRTR_RUNTIME_HOME'] = runtimeHome;
     // Propagate the subtree-root node id. The broker uses it to group a subtree;
     // each launch site also emits the authoritative rootOfSpine(nodeId) over this
     // passthrough.

package/dist/core/runtime/revive-all.d.ts

@@ -54,4 +54,4 @@ export interface ReviveAllResult {
  *  no-op), so this is a thin orchestrator over `listDisconnected`: revive each
  *  with resume:true. One failing node never aborts the sweep — its error is
  *  collected and the rest proceed. */
-export declare function reviveAll(): ReviveAllResult;
+export declare function reviveAll(): Promise<ReviveAllResult>;

package/dist/core/runtime/revive-all.js

@@ -84,7 +84,7 @@ export function listDisconnected() {
  *  no-op), so this is a thin orchestrator over `listDisconnected`: revive each
  *  with resume:true. One failing node never aborts the sweep — its error is
  *  collected and the rest proceed. */
-export function reviveAll() {
+export async function reviveAll() {
     const result = { revived: [], failed: [], frozen: [] };
     for (const meta of listDisconnected()) {
         try {
@@ -93,7 +93,7 @@ export function reviveAll() {
             // whole canvas is the likeliest way to meet the cap, and every node in it
             // is one the daemon wants back: freeze the overflow and let the tick
             // bring them up as slots free.
-            const outcome = reviveNode(meta.node_id, { resume: true, recovery: true, capacity: 'freeze' }).outcome;
+            const outcome = (await reviveNode(meta.node_id, { resume: true, recovery: true, capacity: 'freeze' })).outcome;
             if (outcome === 'frozen')
                 result.frozen.push(meta.node_id);
             else

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

@@ -87,10 +87,10 @@ export type ReviveCapacityPolicy = 'freeze' | 'refuse';
  *  Throws if the node does not exist. All other failures propagate as-is —
  *  callers (daemon, command) decide how to handle.
  */
-export declare function reviveNode(nodeId: string, opts: ReviveOptions): ReviveResult;
+export declare function reviveNode(nodeId: string, opts: ReviveOptions): Promise<ReviveResult>;
 /** The attach-specific entry to the revive boundary. A focus viewer may decline
  * to wake an exact parked resident while preserving the ordinary activating
  * attach default. The fleet check and parked decision are synchronous with the
  * launch below, so an already-running broker wins before dormancy is observed. */
-export declare function decideAttachRevive(nodeId: string, opts: ReviveOptions, wakeParked: boolean): AttachReviveDecision;
+export declare function decideAttachRevive(nodeId: string, opts: ReviveOptions, wakeParked: boolean): Promise<AttachReviveDecision>;
 export {};