@north-light/crouter 0.3.281 → 0.3.283

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

@@ -1,12 +1,14 @@
 import { emitEvent } from '../../events/emit.js';
 import { operationIdContext } from '../../events/operation-id.js';
+import { parkSummaryGraceMs } from '../../../shared/env.js';
+import { headlessTurn } from '../headless-pi.js';
+import { completeBrokerPark, recordBrokerParkActivity } from './daemon-ops.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;
+    const { nodeId, registry, replies, session, dispatches, memoryRefs, authReloadGate, rebind, projection, toolGroups, turnAdmission, } = deps;
     const { ackTo, engineErrorTo } = replies;
     const errorRelay = (client) => {
         let failure;
@@ -36,32 +38,62 @@ export function createEngineDriver(deps) {
             error: err,
         });
     });
+    let parkingSummaryInFlight = false;
+    const recordParkActivityBeforeInput = async () => {
+        if (!parkingSummaryInFlight)
+            return;
+        const result = await recordBrokerParkActivity(nodeId);
+        if (result.activity !== 'recorded') {
+            throw new Error('parking completion took priority before input admission');
+        }
+    };
+    const runParkTurn = (text) => {
+        parkingSummaryInFlight = true;
+        const liveSession = session();
+        const model = liveSession.model;
+        const source = liveSession.sessionManager;
+        const run = model === undefined || typeof model.provider !== 'string' || typeof model.id !== 'string'
+            ? Promise.resolve('failed')
+            : headlessTurn({
+                systemPrompt: liveSession.systemPrompt,
+                userPrompt: text,
+                modelSpec: `${model.provider}/${model.id}`,
+                timeoutMs: parkSummaryGraceMs(),
+                seedMessages: source.buildSessionContext().messages,
+                sessionId: source.getSessionId(),
+                toolPolicy: 'builtin',
+            });
+        void run
+            .catch(() => 'failed')
+            .then((outcome) => completeBrokerPark(nodeId, { outcome }))
+            .then((directive) => {
+            if (directive.action === 'shutdown')
+                rebind.requestShutdown();
+        })
+            .catch((error) => {
+            emitEvent({ level: 'error', event: 'broker.park.complete_failed', error });
+        })
+            .finally(() => {
+            parkingSummaryInFlight = false;
+        });
+    };
     const drivePromptOrFollowUp = (client, frame, errors) => {
         const relayError = errors.relay;
         // Settle on the engine call's outcome: the failure is set by relayError
         // before the caught promise resolves, so reading it after the chain is
         // the call's verdict.
         const settle = (p) => p.then(() => errors.failure());
-        const dispatch = () => turnAdmission.admit((release) => {
+        const drive = (release) => {
             // A prior prompt can be in asynchronous preflight while isStreaming is
             // false. Admission waits for that preflight, then routes against the
             // state it actually established instead of its stale snapshot.
             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)
+                if (frame.delivery?.origin === undefined)
                     return;
-                const visibility = deliveryIsInternal ? 'internal' : undefined;
-                if (frame.delivery.origin === undefined) {
-                    setTurnVisibility('visible');
-                    return;
-                }
-                announceMessageOrigin(frame.text, frame.delivery.origin, visibility);
+                announceMessageOrigin(frame.text, frame.delivery.origin);
             };
             const prompt = async () => {
                 // Both human surfaces converge at this admitted boundary. The watcher
@@ -77,18 +109,7 @@ export function createEngineDriver(deps) {
                     }
                 }
                 announceDelivery();
-                registry.broadcast({
-                    type: 'turn_visibility',
-                    visibility: currentTurnVisibility(),
-                });
-                try {
-                    await session().prompt(frame.text, { ...promptOptions, preflightResult: release });
-                }
-                catch (error) {
-                    if (deliveryIsInternal)
-                        clearTurnVisibility();
-                    throw error;
-                }
+                await session().prompt(frame.text, { ...promptOptions, preflightResult: release });
             };
             if (guidance === null) {
                 if (route.call === 'prompt') {
@@ -125,6 +146,19 @@ export function createEngineDriver(deps) {
                 .followUp(frame.text, frame.images)
                 .catch(relayError)
                 .then(() => sendGuidance(guidance, deliverAs)));
+        };
+        const dispatch = () => turnAdmission.admit((release) => {
+            // Do not make the normal path async: prompt admission and auth reload
+            // ordering depend on Pi seeing this call in the current stack.
+            if (!parkingSummaryInFlight)
+                return drive(release);
+            // This operation is the input-admission half of an in-flight parking
+            // summary: it completes before Pi receives the prompt, so completion
+            // cannot tear down a viewer or live delivery that won admission.
+            return recordParkActivityBeforeInput().then(() => drive(release), (error) => {
+                relayError(error);
+                return errors.failure();
+            });
         });
         // /login acknowledges before its asynchronous local refresh completes.
         // An idle turn must not overtake that refresh and launch on the stale
@@ -180,7 +214,7 @@ export function createEngineDriver(deps) {
      */
     const driveSteer = (frame, errors) => {
         const relayError = errors.relay;
-        void turnAdmission.admit((release) => {
+        const drive = (release) => {
             if (resolveSteerCall(frame.text, session()) === 'prompt') {
                 return promptWithAdvertisedCommandInvocation(session(), frame.text, () => session().prompt(frame.text, {
                     images: frame.images,
@@ -196,6 +230,13 @@ export function createEngineDriver(deps) {
             return session()
                 .steer(frame.text, frame.images)
                 .then(() => sendGuidance(guidance, 'steer'));
+        };
+        void turnAdmission.admit((release) => {
+            if (!parkingSummaryInFlight)
+                return drive(release);
+            return recordParkActivityBeforeInput().then(() => drive(release), (error) => {
+                relayError(error);
+            });
         }).catch(relayError);
     };
     /**
@@ -285,6 +326,12 @@ export function createEngineDriver(deps) {
      * and returns `undefined`.
      */
     return (client, frame) => {
+        if ((frame.type === 'prompt' || frame.type === 'follow_up')
+            && frame.delivery?.origin?.type === 'runtime'
+            && frame.delivery.origin.kind === 'park') {
+            runParkTurn(frame.text);
+            return undefined;
+        }
         const errors = errorRelay(client);
         switch (frame.type) {
             case 'prompt':

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

@@ -38,6 +38,7 @@ export function createFrameDispatchContext(deps) {
         turnAdmission,
     });
     const driveEngine = createEngineDriver({
+        nodeId,
         registry,
         replies,
         session: currentSession,

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

@@ -104,8 +104,19 @@ export function buildSettingsData(id, session) {
     catch {
         /* loader without themes — viewer falls back to its local theme registry */
     }
+    const defaultProvider = manager.getDefaultProvider();
+    const defaultModelId = manager.getDefaultModel();
+    let availableDefaultModels = [];
+    try {
+        availableDefaultModels = session.modelRuntime.getAvailableSnapshot();
+    }
+    catch {
+        /* the snapshot touches auth config; degrade to none known available */
+    }
     const settings = {
         autoCompact: session.autoCompactionEnabled,
+        defaultModel: defaultProvider && defaultModelId ? `${defaultProvider}/${defaultModelId}` : 'not set',
+        availableDefaultModels,
         showImages: manager.getShowImages(),
         imageWidthCells: manager.getImageWidthCells(),
         autoResizeImages: manager.getImageAutoResize(),
@@ -117,6 +128,7 @@ export function buildSettingsData(id, session) {
         httpIdleTimeoutMs: manager.getHttpIdleTimeoutMs(),
         thinkingLevel: session.thinkingLevel,
         availableThinkingLevels: session.getAvailableThinkingLevels(),
+        modelThinkingLevels: manager.getAllModelThinkingLevels(),
         currentTheme: manager.getTheme() ?? '',
         terminalTheme: 'dark',
         availableThemes,
@@ -133,7 +145,9 @@ export function buildSettingsData(id, session) {
         clearOnShrink: manager.getClearOnShrink(),
         showTerminalProgress: manager.getShowTerminalProgress(),
         tuiMode: manager.getTuiMode(),
+        fullscreenExitOutput: manager.getFullscreenExitOutput(),
         fullscreenScrollbar: manager.getFullscreenScrollbar(),
+        fullscreenCopyOnSelect: manager.getFullscreenCopyOnSelect(),
         warnings: manager.getWarnings(),
         defaultProjectTrust: manager.getDefaultProjectTrust(),
         showCacheMissNotices: manager.getShowCacheMissNotices(),

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

@@ -6,7 +6,6 @@ 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');
@@ -303,12 +302,6 @@ 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

@@ -402,11 +402,6 @@ 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. */
@@ -652,7 +647,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 | TurnVisibilityFrame | WorkingActivityFrame | ModelChangedFrame | ResourcesReloadedFrame | ErrorFrame | NodeNamedFrame | AckFrame | BrokerDataFrame | BashStartFrame | BashOutputFrame | BashEndFrame | ExtensionUIRequestFrame | ExtensionUIDismissFrame | ToolGroupSummaryFrame | AgentSessionEvent;
+export type BrokerToClient = WelcomeFrame | 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/fleet.d.ts

@@ -58,6 +58,13 @@ export interface FleetRegistry {
     /** Give back a slot claimed by `reserveSlot` and not consumed by a launch. */
     releaseReservation(nodeId: string): void;
     entries(): Iterable<[string, FleetEntry]>;
+    /** Mark this exact broker's pause interruption before directly sending it
+     * SIGTERM. An explicit pid is the identity-checked fallback when the daemon
+     * has not registered a handle yet. */
+    interruptForProfilePause(nodeId: string, pid?: number): void;
+    /** Whether the next dead-row policy pass must absorb this pause interruption
+     * before a later pass may recover the row normally. */
+    hasProfilePauseInterruption(nodeId: string): boolean;
     /** Drop an entry without policy (terminal exits + close paths). */
     forget(nodeId: string): void;
     /** Wired by `headlessBrokerHost.launch` to the handle's `exited` promise.

package/dist/core/runtime/headless-pi.d.ts

@@ -1,4 +1,5 @@
 import type { ConstrainedSamplingConfig } from '@earendil-works/pi-ai';
+import type { AgentMessage } from '@earendil-works/pi-agent-core';
 import type { TSchema } from 'typebox';
 export interface HeadlessTool {
     name: string;
@@ -15,6 +16,12 @@ export interface HeadlessRequest {
     modelIntent?: string;
     timeoutMs: number;
     tool?: HeadlessTool;
+    /** Exact context to seed into an isolated in-memory session. */
+    seedMessages?: readonly AgentMessage[];
+    /** Reuses a provider cache identity without binding or persisting a session. */
+    sessionId?: string;
+    /** Omit `noTools` to load Pi's builtin tool suite. */
+    toolPolicy?: 'builtin';
 }
 /** Run a one-shot call whose only output channel is one structured tool call. */
 export declare function headlessToolCall(request: HeadlessRequest & {
@@ -22,3 +29,9 @@ export declare function headlessToolCall(request: HeadlessRequest & {
 }): Promise<unknown>;
 /** Run a one-shot call and return the final assistant text. */
 export declare function headlessText(request: HeadlessRequest): Promise<string>;
+/** Run a tool-capable, extension-free in-memory turn against seeded context. */
+export declare function headlessTurn(request: HeadlessRequest & {
+    seedMessages: readonly AgentMessage[];
+    sessionId: string;
+    toolPolicy: 'builtin';
+}): Promise<'completed' | 'failed'>;

package/dist/core/runtime/headless-pi.js

@@ -112,13 +112,17 @@ async function runHeadless(request, fallback, collect) {
                     };
                 },
             });
+            const sessionManager = sdk.SessionManager.inMemory(nodeCwd, request.sessionId === undefined ? undefined : { id: request.sessionId });
+            for (const message of request.seedMessages ?? []) {
+                sessionManager.appendMessage(message);
+            }
             ({ session } = await sdk.createAgentSessionFromServices({
                 services,
-                sessionManager: sdk.SessionManager.inMemory(nodeCwd),
+                sessionManager,
                 model: selected.model,
                 thinkingLevel: 'off',
                 ...(tool === undefined
-                    ? { noTools: 'all' }
+                    ? request.toolPolicy === 'builtin' ? {} : { noTools: 'all' }
                     : { tools: [tool.name], customTools: [customTool] }),
             }));
             if (timedOut)
@@ -151,3 +155,7 @@ export function headlessToolCall(request) {
 export function headlessText(request) {
     return runHeadless(request, '', (session) => lastAssistantText(session.messages));
 }
+/** Run a tool-capable, extension-free in-memory turn against seeded context. */
+export function headlessTurn(request) {
+    return runHeadless(request, 'failed', () => 'completed');
+}

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

@@ -1,8 +1,12 @@
-import type { NodeMeta, NodeStatus, ExitIntent, TerminalReason } from '../canvas/types.js';
+import type { NodeMeta, NodeOutcomeDetailV1, NodeStatus, ExitIntent, TerminalReason } from '../canvas/types.js';
 /** The lifecycle events — the only vocabulary for moving a node's status/intent.
  *  Each maps (in the table below) to a target status and/or intent plus the set
  *  of from-statuses it is legal from. */
 export type LifecycleEvent = 'finish' | 'park' | 'cancel' | 'crash' | 'yield' | 'release' | 'refresh-launch' | 'revive';
+export interface TerminalOutcomeInput {
+    /** Omit to derive: a lifecycle terminal transition is always a failure. */
+    detail?: NodeOutcomeDetailV1;
+}
 /** Enact a lifecycle event on a node: validate the from-status against the
  *  table, then write status+intent in ONE atomic statement (so they can never
  *  disagree). Returns the hydrated node view after the write.
@@ -11,6 +15,7 @@ export type LifecycleEvent = 'finish' | 'park' | 'cancel' | 'crash' | 'yield' |
  *  legality authoritative at SQLite write time rather than at a stale read. */
 export declare function transition(nodeId: string, event: LifecycleEvent, opts?: {
     reason?: TerminalReason;
+    outcome?: TerminalOutcomeInput;
 }): NodeMeta;
 /** Whether this row is a PARKED node — terminalized by the unattended clock
  *  rather than by finishing its own work. The one read of the park marker:

package/dist/core/runtime/lifecycle.js

@@ -31,7 +31,7 @@
 // unknown-node/illegal-move/already-finalized-cancel branching — stays here;
 // only the raw conditional UPDATE lives in canvas.ts, keeping every `.prepare(`
 // inside `core/canvas/`).
-import { getNode, cancelCronsOnWake, transitionStatusIntent } from '../canvas/index.js';
+import { getNode, cancelCronsOnWake, composeOutcomeDeliveryDocument, readOutcomeDelivery, transitionStatusIntent } from '../canvas/index.js';
 const ANY = '*';
 const TERMINAL_REASONS = {
     finish: 'finished',
@@ -72,6 +72,29 @@ const TRANSITIONS = {
     // reviveNode ordinary launch · resetRoot · stophook boot confirmation.
     revive: { status: 'active', intent: null, from: ANY },
 };
+function firstLineAtMost(value, maxBytes) {
+    const line = value.split('\n')[0] ?? '';
+    let bytes = 0;
+    let result = '';
+    for (const character of line) {
+        const next = Buffer.byteLength(character, 'utf8');
+        if (bytes + next > maxBytes)
+            break;
+        bytes += next;
+        result += character;
+    }
+    return result;
+}
+function detailJson(detail) {
+    if (detail === undefined)
+        return null;
+    const message = detail.message === undefined ? undefined : firstLineAtMost(detail.message, 500);
+    const bounded = { ...detail, ...(message === undefined ? {} : { message }) };
+    const serialized = JSON.stringify(bounded);
+    if (Buffer.byteLength(serialized, 'utf8') <= 4 * 1024)
+        return serialized;
+    return JSON.stringify({ schema: 'crtr.node-outcome-detail/v1', truncated: true, ...(message === undefined ? {} : { message }) });
+}
 /** Enact a lifecycle event on a node: validate the from-status against the
  *  table, then write status+intent in ONE atomic statement (so they can never
  *  disagree). Returns the hydrated node view after the write.
@@ -90,10 +113,36 @@ export function transition(nodeId, event, opts) {
         fields.intent = spec.intent ?? null;
     if (reason !== undefined)
         fields.terminal_reason = reason;
+    const terminal = event === 'finish' || event === 'park' || event === 'cancel' || event === 'crash';
+    const current = terminal ? getNode(nodeId) : null;
+    const recordsOutcome = terminal && current?.kind !== 'human';
+    const outcomeReason = reason;
+    const outcomeAt = terminal ? new Date().toISOString() : null;
+    const outcomeDetailJson = detailJson(opts?.outcome?.detail);
+    let documentJson;
+    if (recordsOutcome && current !== null && current.outcome_at === null) {
+        const delivery = readOutcomeDelivery(nodeId);
+        if (delivery?.state === 'armed') {
+            documentJson = composeOutcomeDeliveryDocument({
+                nodeId,
+                outcome: { kind: 'failure', reason: outcomeReason, at: outcomeAt, revision: (current.outcome_revision ?? 0) + 1, detailJson: outcomeDetailJson },
+                action: { name: delivery.actionName, payload: delivery.payload },
+            });
+        }
+    }
     // A committed canonical result is protected from a concurrent close.
     const changes = transitionStatusIntent(nodeId, fields, {
         fromStatuses: spec.from === ANY ? undefined : spec.from,
         requireNoFinalReport: event === 'cancel',
+        ...(recordsOutcome ? {
+            outcome: {
+                kind: 'failure',
+                reason: outcomeReason,
+                detailJson: outcomeDetailJson,
+                at: outcomeAt,
+                ...(documentJson === undefined ? {} : { documentJson }),
+            },
+        } : {}),
     });
     if (changes === 0) {
         const cur = getNode(nodeId);

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

@@ -1,4 +1,4 @@
-import { type NodeMeta, type Mode, type Lifecycle, type LaunchSpec, type ManagedWorktree, type ReviewBinding } from '../canvas/index.js';
+import { type NodeMeta, type Mode, type Lifecycle, type LaunchSpec, type ManagedWorktree, type OutcomeDeliveryBinding, type ReviewBinding } from '../canvas/index.js';
 /** Explicitly set the resolved install id. crtrd calls this once at boot,
  *  immediately after `resolveInstallId()` — see crtrd.ts — so a provisioning
  *  mismatch fails the daemon loudly at STARTUP rather than lazily on first
@@ -97,6 +97,10 @@ export interface SpawnNodeOpts {
     profile_id?: string | null;
     /** Managed worktree already created for this node, if any. */
     managedWorktree?: ManagedWorktree;
+    /** Absolute wall-clock deadline persisted with the row at birth. */
+    deadlineAt?: string;
+    /** Delivery target persisted with the row before any broker can launch. */
+    outcomeDelivery?: OutcomeDeliveryBinding;
     /** Override the generated id — either an internally pre-allocated id
      *  (worktree naming; always valid+fresh) or an external caller's explicit id
      *  (`--node-id`), which is format-validated

package/dist/core/runtime/nodes.js

@@ -264,6 +264,7 @@ export function spawnNode(opts) {
         passive_default: opts.passiveDefault ?? false,
         ...(opts.managedWorktree !== undefined ? { managed_worktree: opts.managedWorktree } : {}),
         intent: null,
+        deadline_at: opts.deadlineAt ?? null,
         pi_session_id: null,
         pi_session_file: null,
         launch: opts.launch,
@@ -278,7 +279,7 @@ export function spawnNode(opts) {
         throw new Error(`cannot spawn from unknown creator node: ${creator}`);
     }
     assertProfileAvailableForBirth(meta.profile_id ?? null);
-    createNode(meta);
+    createNode(meta, opts.outcomeDelivery === undefined ? undefined : { outcomeDelivery: opts.outcomeDelivery });
     // Create the node-local memory directory so substrate docs can be written
     // directly into it without a separate mkdir. Skip for ephemeral human-bridge
     // rows (kind 'human') — they are not agent nodes.

package/dist/core/runtime/outcome-document.d.ts

@@ -0,0 +1,70 @@
+import type { DeclinedResult, NodeMeta, NodeOutcomeDetailV1, NodeOutcomeKind, TerminalReason } from '../canvas/types.js';
+export interface NodeOutcomeDocumentV1 {
+    schema: 'crtr.node-outcome/v1';
+    outcomeId: string;
+    nodeId: string;
+    revision: number;
+    kind: NodeOutcomeKind;
+    reason: TerminalReason;
+    settledAt: string;
+    node: {
+        name: string;
+        description?: string;
+        kind: string;
+        mode: 'base' | 'orchestrator';
+        lifecycle: 'terminal' | 'resident';
+        status: 'active' | 'idle' | 'done' | 'dead' | 'canceled';
+        terminalReason: TerminalReason | null;
+        cwd: string;
+        createdAt: string;
+        parent: string | null;
+        spawnedBy: string | null;
+    };
+    result?: {
+        finalReport: {
+            basename: string;
+            path: string;
+        };
+        structuredResult?: unknown;
+        structuredResultOmitted?: true;
+        structuredResultPath?: string;
+    };
+    failure?: {
+        message: string | null;
+        faultKind: NodeOutcomeDetailV1['fault_kind'] | null;
+        errorClass: NodeOutcomeDetailV1['error_class'] | null;
+        respawnFailures: number | null;
+        deadline: {
+            deadlineAt: string;
+            elapsedMs: number;
+        } | null;
+        /** Set only for reason `declined`: the reason, requester-classified code, and retryable claim. */
+        declined: DeclinedResult | null;
+    };
+    action: {
+        name: string;
+        payload: unknown;
+    };
+    delivery: {
+        attempt: number;
+    };
+}
+/** Compose a document at outcome time; delivery only replaces `delivery.attempt`. */
+export declare function composeNodeOutcomeDocument(args: {
+    node: NodeMeta;
+    outcome: {
+        kind: NodeOutcomeKind;
+        reason: TerminalReason;
+        at: string;
+        revision: number;
+        detailJson: string | null;
+    };
+    action: {
+        name: string;
+        payload: unknown;
+    };
+    /** Required for a result before the final-report pointer has committed. */
+    finalReport?: string | null;
+    /** Lets the outcome transaction supply a parsed result without a second read. */
+    structuredResult?: unknown;
+}): NodeOutcomeDocumentV1;

package/dist/core/runtime/outcome-document.js

@@ -0,0 +1,97 @@
+// The immutable outcome document handed to a registered delivery target.
+import { existsSync, readFileSync } from 'node:fs';
+import { contextDir, reportsDir } from '../canvas/paths.js';
+import { outputResultPath } from './structured-output.js';
+const MAX_DOCUMENT_BYTES = 256 * 1024;
+function structuredResult(nodeId) {
+    const path = outputResultPath(nodeId);
+    try {
+        return existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseDetail(detailJson) {
+    if (detailJson === null)
+        return null;
+    try {
+        return JSON.parse(detailJson);
+    }
+    catch {
+        return null;
+    }
+}
+/** Preserve valid Unicode while bounding a display-only field by UTF-8 bytes. */
+function truncateDescription(value) {
+    const maxBytes = 1024;
+    if (Buffer.byteLength(value, 'utf8') <= maxBytes)
+        return value;
+    const ellipsis = '…';
+    let bytes = Buffer.byteLength(ellipsis, 'utf8');
+    let result = '';
+    for (const character of value) {
+        const next = Buffer.byteLength(character, 'utf8');
+        if (bytes + next > maxBytes)
+            break;
+        bytes += next;
+        result += character;
+    }
+    return `${result}${ellipsis}`;
+}
+/** Compose a document at outcome time; delivery only replaces `delivery.attempt`. */
+export function composeNodeOutcomeDocument(args) {
+    const { node, outcome, action } = args;
+    const detail = parseDetail(outcome.detailJson);
+    const finalReport = args.finalReport ?? node.final_report ?? '';
+    const name = truncateDescription(node.name);
+    const description = node.description === undefined ? undefined : truncateDescription(node.description);
+    const result = outcome.kind === 'result'
+        ? args.structuredResult === undefined ? structuredResult(node.node_id) : args.structuredResult
+        : undefined;
+    const document = {
+        schema: 'crtr.node-outcome/v1',
+        outcomeId: `${node.node_id}:${outcome.revision}`,
+        nodeId: node.node_id,
+        revision: outcome.revision,
+        kind: outcome.kind,
+        reason: outcome.reason,
+        settledAt: outcome.at,
+        node: {
+            name,
+            ...(description === undefined ? {} : { description }),
+            kind: node.kind,
+            mode: node.mode,
+            lifecycle: node.lifecycle,
+            status: node.status,
+            terminalReason: node.terminal_reason ?? null,
+            cwd: node.cwd,
+            createdAt: node.created,
+            parent: node.parent ?? null,
+            spawnedBy: node.spawned_by ?? null,
+        },
+        ...(outcome.kind === 'result' ? {
+            result: {
+                finalReport: { basename: finalReport, path: `${reportsDir(node.node_id)}/${finalReport}` },
+                ...(result === undefined ? {} : { structuredResult: result }),
+            },
+        } : {
+            failure: {
+                message: detail?.message ?? null,
+                faultKind: detail?.fault_kind ?? null,
+                errorClass: detail?.error_class ?? null,
+                respawnFailures: detail?.respawn_failures ?? null,
+                deadline: detail?.deadline === undefined ? null : { deadlineAt: detail.deadline.deadline_at, elapsedMs: detail.deadline.elapsed_ms },
+                declined: detail?.declined ?? null,
+            },
+        }),
+        action,
+        delivery: { attempt: 0 },
+    };
+    if (Buffer.byteLength(JSON.stringify(document), 'utf8') > MAX_DOCUMENT_BYTES && document.result?.structuredResult !== undefined) {
+        delete document.result.structuredResult;
+        document.result.structuredResultOmitted = true;
+        document.result.structuredResultPath = `${contextDir(node.node_id)}/result.json`;
+    }
+    return document;
+}