@sema-agent/core 7.48.0 → 7.49.1

package/dist/orchestration/workflow.d.ts

@@ -126,6 +126,22 @@ export declare class WorkflowJournalIncompatibleError extends Error {
     readonly code = "workflow.journal_incompatible";
     constructor(fromRunId: string, ordinal: number);
 }
+/**
+ * Thrown by `ctx.agent` / `ctx.agentStream().result()` when the journal store did not answer the append of the
+ * call's result within {@link RunWorkflowOptions.journalAppendTimeoutMs}. A STORE fault, not a run timeout: the
+ * run's `totalTimeoutMs` is independent of it, and whichever comes first speaks (the earlier deadline's error
+ * is the one the caller sees). The script does not run past the agent whose result may be unrecorded; it is the
+ * same exit a rejecting store already has. The timeout does not cancel the write: the store may still land it
+ * late (appends are idempotent per ordinal), so a resume of this run replays the agent if the write landed and
+ * re-runs it live if not.
+ */
+export declare class WorkflowJournalAppendTimeoutError extends Error {
+    readonly runId: string;
+    readonly ordinal: number;
+    readonly timeoutMs: number;
+    readonly code = "workflow.journal_append_timeout";
+    constructor(runId: string, ordinal: number, timeoutMs: number);
+}
 /**
  * A TRUSTED, run-scoped internal channel carrying the workflow **nesting depth** across a process boundary
  * (design/98 §0.1 BLOCKER3). It is NOT a `TaskSpec` field and NOT a `run_workflow` tool param — a worker or
@@ -215,7 +231,8 @@ export interface WorkflowAgentHandle {
      * (the worker can't address the leader except by the marker). A steer issued BEFORE the worker's loop goes
      * live is parked and delivered into the NEXT turn's context (birth-window delivery, bounded — ledger item 36); steers are
      * delivered in call order, the birth window included. Rejects with `steering.not_running` once the task has
-     * finished (teardown included).
+     * finished (teardown included) — from the start on a handle a resume settled without running it (replayed from
+     * the journal, or settled at its parked ordinal).
      *
      * `opts.inputId` is a PASS-THROUGH of the underlying `TaskStream.steer` correlation/idempotency key
      * (design/171 §6.3 — its whole contract, value domain and typed refusals are that verb's; absent ⇒ byte-identical
@@ -230,7 +247,8 @@ export interface WorkflowAgentHandle {
     steer(content: string, opts?: {
         inputId?: string;
     }): Promise<string>;
-    /** Await the agent's {@link TaskResult} (the same value the eager recording used; idempotent). */
+    /** Await the agent's {@link TaskResult} (the same value the eager recording used; idempotent). On a resume that
+     *  replayed this call it is the journaled result, settled at once. */
     result(): Promise<TaskResult>;
 }
 export interface WorkflowRunContext {
@@ -384,17 +402,32 @@ export interface RunWorkflowOptions {
     /** Injected clock (design/87 §4.3 — testable without the wall clock). Default `Date.now`. */
     now?: () => number;
     /**
-     * design/97 CORE-7 — the LOAD-BEARING resume journal. With a `journalStore`, every `ctx.agent` result (NOT
-     * `ctx.agentStream` — see below) is recorded keyed by its deterministic callKey. Supplying `resumeFromRunId`
-     * (a PRIOR run id, requires `journalStore`) replays the longest UNCHANGED PREFIX of those results instantly and
-     * runs only the first changed/new call + everything after it live (same script + args → 100% cache hit). A
-     * `journalStore` WITHOUT `resumeFromRunId` just records (so a future run can resume from THIS run). Replayed
-     * agents accumulate into `run.stats` (total work) but NOT into `ctx.budget.spent()` (live spend only — a resume
-     * is not re-charged for cached work). NOT-REPLAYED (they force divergence so the suffix runs live): `ctx.agentStream`
-     * (a finished result can't be steered — RECORDED for the journal read-face, never replayed) and `ctx.pipeline` (latency-dependent ordinals aren't deterministic —
-     * a CORE-7.1 follow-on adds stage-scoped deterministic keys). Sequential + `parallel(direct thunks)` replay.
+     * design/97 CORE-7 — the LOAD-BEARING resume journal. With a `journalStore`, every agent result — `ctx.agent` and
+     * `ctx.agentStream` alike — is recorded keyed by its deterministic callKey. Supplying `resumeFromRunId` (a PRIOR run
+     * id, requires `journalStore`) replays the longest UNCHANGED PREFIX of those results instantly and runs only the
+     * first changed/new call + everything after it live (same script + args → 100% cache hit). A replayed
+     * `ctx.agentStream` call hands back an already-settled handle: `result()` is the journaled result, `steer()` is
+     * refused `steering.not_running` (nothing is running). A `journalStore` WITHOUT `resumeFromRunId` just records (so
+     * a future run can resume from THIS run). Replayed agents accumulate into `run.stats` (total work) but NOT into
+     * `ctx.budget.spent()` (live spend only — a resume is not re-charged for cached work). NOT-REPLAYED (it forces
+     * divergence so the suffix runs live): `ctx.pipeline` (latency-dependent ordinals aren't deterministic — a
+     * CORE-7.1 follow-on adds stage-scoped deterministic keys). Sequential + `parallel(direct thunks)` replay.
      */
     journalStore?: WorkflowJournalStore;
+    /**
+     * How long (ms) a call waits for the journal store to answer ONE append before it is refused with
+     * {@link WorkflowJournalAppendTimeoutError} (`workflow.journal_append_timeout`). Default
+     * {@link WORKFLOW_JOURNAL_APPEND_TIMEOUT_MS}. One bound for both spawn lanes (`ctx.agent` and
+     * `ctx.agentStream().result()`) and every awaited append (a settled result, a refused call's failed
+     * entry, an oversize tombstone, a park record). Must be a finite number > 0 (a bad value is refused before the
+     * run starts, never replaced by the default).
+     *
+     * Independent of `totalTimeoutMs`: this one names a dead STORE, that one ends the RUN. Whichever deadline is
+     * earlier speaks — a run with no `totalTimeoutMs` is bounded by this alone, one whose `totalTimeoutMs` is
+     * shorter finalizes with the run timeout first (the late append fault is then silent). The timeout does not
+     * cancel the write; see {@link WorkflowJournalAppendTimeoutError}.
+     */
+    journalAppendTimeoutMs?: number;
     /** design/97 CORE-7 — resume by replaying a prior run's journal (requires `journalStore`). See `journalStore`. */
     resumeFromRunId?: string;
     /** The HOST task's effective working root — threaded into every spawned agent's trusted internals
@@ -533,6 +566,10 @@ export interface RunWorkflowOptions {
      *  `run_workflow` tool wiring; a directly-started workflow may pass its own. Absent ⇒ children run
      *  under only their own gates (pre-seam behavior). TRUSTED: never a script/model argument. */
     inheritedGate?: import("../core/runner/contracts.js").InheritedGate;
+    /** The HOST task's tool selector layers (`ToolExecuteContext.toolSelector.layers`), threaded into EVERY spawned agent's trusted
+     *  internals as its ceiling (`RunInternals.toolCeiling`) on both spawn legs: nothing a workflow agent's spec names can widen what
+     *  the host may use. Set by the `run_workflow` tool wiring; absent ⇒ the agents are bounded only by their own lists. TRUSTED. */
+    toolCeiling?: readonly import("../core/tool-face.js").ToolSelectorLayer[];
     /** RB-201 FO-3 (workflow lane) — the session's auto-mode classifier, consulted BEFORE each script-spawned
      *  child starts (objective + toolset + output schema, finalized). The delegation-tool lane reviews its
      *  children at one shared point; a workflow's children reach `runner.runTask` through this module instead,
@@ -639,6 +676,19 @@ export declare const WORKFLOW_AGENT_THROTTLE_BACKOFF_MS = 45000;
  * so the timer is unref'd by default and tests can drive it without waiting.
  */
 export declare const WORKFLOW_RESUME_CLAIM_FINALIZE_TIMEOUT_MS = 10000;
+/**
+ * The default for {@link RunWorkflowOptions.journalAppendTimeoutMs}: how long a call waits for the journal store
+ * to answer ONE append before it is refused with {@link WorkflowJournalAppendTimeoutError}.
+ *
+ * The wait is load-bearing (the script must not run past an unrecorded agent), so the figure has to clear a
+ * healthy write by a wide margin: one row of at most `MAX_JOURNAL_RESULT_BYTES` to a remote, loaded database
+ * is seconds, never tens of seconds — a bound near that would misread a busy store as a dead one. It also has
+ * to be well inside the Workflow tool's 10-minute deadline, or the bound would add nothing there: a dead store
+ * is named after 30 s instead of silently eating the run's whole deadline. The two terminal-boundary waits
+ * (5 s drain, 10 s claim release) are shorter on purpose — they run after the outcome is fixed and lose
+ * nothing by giving up; this one decides whether the script may continue.
+ */
+export declare const WORKFLOW_JOURNAL_APPEND_TIMEOUT_MS = 30000;
 /** F5/B4 + design/87 §4.3 — the INJECTABLE timer seam the per-agent resilience layer schedules on (the
  *  stall watchdog + the throttle backoff sleep). Tests drive VIRTUAL time instead of really waiting
  *  180s/45s. Default: the real `setTimeout`/`clearTimeout`, unref'd (a pending watchdog must never hold

package/dist/orchestration/workflow.js

@@ -6,6 +6,7 @@ import { uuidv7 } from "../internal/harness.js";
 import { applyParentSpecSeat } from "../core/parent-spec-seat.js";
 import { TERMINAL_CAUSE_IS_REPLAYABLE, isTerminalCauseKind } from "../core/terminal-cause.js";
 import { terminalProjection } from "../core/runner/terminal-projection.js";
+import { steeringError } from "../core/runner/steer-admission.js";
 import { builtinAgentDefinitions } from "../agents/builtin-agents.js";
 import { GENERAL_PURPOSE_SUBAGENT_TYPE, markerFragment } from "../agents/subagent.js";
 import { deploymentSubagentSystemPrompt, runnerRoleMap } from "../agents/child-model-seat.js";
@@ -240,6 +241,21 @@ export class WorkflowJournalIncompatibleError extends Error {
         this.name = "WorkflowJournalIncompatibleError";
     }
 }
+export class WorkflowJournalAppendTimeoutError extends Error {
+    runId;
+    ordinal;
+    timeoutMs;
+    code = "workflow.journal_append_timeout";
+    constructor(runId, ordinal, timeoutMs) {
+        super(`the workflow journal store did not answer the append for agent #${ordinal} of run ${runId} within ${timeoutMs}ms (journalAppendTimeoutMs) — ` +
+            "a journal-store fault, not a run timeout. The result is not confirmed recorded: a resume of this run replays the agent only if the write " +
+            "landed late, otherwise it re-runs the agent live.");
+        this.runId = runId;
+        this.ordinal = ordinal;
+        this.timeoutMs = timeoutMs;
+        this.name = "WorkflowJournalAppendTimeoutError";
+    }
+}
 class WorkflowParkRefusal extends Error {
     code;
     detail;
@@ -353,6 +369,7 @@ function readLegApprovalWaitedMs(result, announce) {
     return raw;
 }
 export const WORKFLOW_RESUME_CLAIM_FINALIZE_TIMEOUT_MS = 10_000;
+export const WORKFLOW_JOURNAL_APPEND_TIMEOUT_MS = 30_000;
 const REAL_WORKFLOW_TIMERS = {
     setTimeout(fn, ms) {
         const t = setTimeout(fn, ms);
@@ -411,6 +428,14 @@ function normalizeWorkflowTimerCap(name, v) {
     }
     return normalized;
 }
+function normalizeWorkflowJournalAppendTimeoutMs(v) {
+    if (v === undefined)
+        return WORKFLOW_JOURNAL_APPEND_TIMEOUT_MS;
+    if (!Number.isFinite(v) || v <= 0) {
+        throw new Error(`runWorkflow: journalAppendTimeoutMs must be a finite number > 0 (got ${v}) — a bound of zero would time out every append before the store could answer. Omit it for the default.`);
+    }
+    return normalizeWorkflowTimerCap("journalAppendTimeoutMs", v);
+}
 function normalizeWorkflowStallMs(v) {
     if (v === undefined)
         return WORKFLOW_AGENT_STALL_MS;
@@ -525,6 +550,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
     const stallMs = normalizeWorkflowStallMs(opts.stallMs);
     const agentMaxRetries = normalizeWorkflowHardCap("agentMaxRetries", opts.agentMaxRetries) ?? WORKFLOW_AGENT_MAX_RETRIES;
     const throttleBackoffMs = normalizeWorkflowTimerCap("throttleBackoffMs", opts.throttleBackoffMs) ?? WORKFLOW_AGENT_THROTTLE_BACKOFF_MS;
+    const journalAppendTimeoutMs = normalizeWorkflowJournalAppendTimeoutMs(opts.journalAppendTimeoutMs);
     const timers = opts.timers ?? REAL_WORKFLOW_TIMERS;
     const cancelController = new AbortController();
     const timeoutController = totalTimeoutMs !== undefined ? new AbortController() : undefined;
@@ -689,6 +715,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
         ...(opts.parentCenterSourceRevision !== undefined ? { parentCenterSourceRevision: opts.parentCenterSourceRevision } : {}),
         ...(opts.onForwardEvent ? { onForwardEvent: opts.onForwardEvent } : {}),
         ...(opts.inheritedGate !== undefined ? { inheritedGate: opts.inheritedGate } : {}),
+        ...(opts.toolCeiling !== undefined ? { toolCeiling: opts.toolCeiling } : {}),
         ...((opts.rootSessionId ?? opts.originatingSessionId) !== undefined ? { rootSessionId: opts.rootSessionId ?? opts.originatingSessionId } : {}),
         ...(opts.placementRoot !== undefined ? { placementRoot: opts.placementRoot } : {}),
         ...(opts.originatingSessionId !== undefined ? { parentSessionId: opts.originatingSessionId } : {}),
@@ -835,15 +862,18 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
     const journalStore = opts.journalStore;
     let resumeClaim;
     const replayByOrdinal = [];
-    let diverged = false;
+    let divergence;
     let parkedLeg;
     const parkedError = () => {
         const p = parkedLeg;
         return new WorkflowAgentParkedError(p.label, p.paused.terminal.gate.kind, p.paused.terminal.checkpointId);
     };
     const parkedResumeFor = (token) => opts.parkedResume?.find((d) => d.token === token);
-    const parkedCallChangedError = (ordinal) => Object.assign(new Error(`workflow resume: ordinal ${ordinal} is PARKED on an approval checkpoint, but the call at that ordinal changed (its call key differs from the journaled one) — ` +
-        "the script or its args were edited at a parked call, and a fresh spawn there would run beside the pinned child. Restore the call and resume again, or decide the checkpoint " +
+    const parkedCallChangedError = (ordinal) => Object.assign(new Error(`workflow resume: ordinal ${ordinal} is PARKED on an approval checkpoint, but the call at that ordinal changed (its call key differs from the journaled one) ` +
+        (divergence === undefined
+            ? "while no earlier call diverged from the record — the difference is in this call's own inputs (the script, its args, or a host input folded into the call identity). "
+            : `after replay stopped at agent #${divergence.ordinal} (${divergence.reason}) — the calls from there on ran live, so this call may have been built from a live result rather than the recorded one. `) +
+        "A fresh spawn there would run beside the pinned child. Resume with the calls up to it unchanged, or decide the checkpoint " +
         "through the deployment's approval channel and start a fresh run."), { code: "workflow.parked_call_changed" });
     let inFlightLegs = 0;
     let legsIdleResolve;
@@ -971,6 +1001,34 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
     };
     let journalTail = Promise.resolve();
     const JOURNAL_DRAIN_MAX_MS = 5_000;
+    const awaitedAppendTimers = new Set();
+    const trackJournalWrite = (write, callKey) => {
+        if (finalized)
+            return Promise.resolve(write);
+        const written = new Promise((resolve, reject) => {
+            const handle = timers.setTimeout(() => {
+                awaitedAppendTimers.delete(handle);
+                const fault = new WorkflowJournalAppendTimeoutError(runId, callKeyOrdinal(callKey), journalAppendTimeoutMs);
+                emitRunLog(`resume-journal: ${fault.message}`);
+                reject(fault);
+            }, journalAppendTimeoutMs);
+            handle?.ref?.();
+            awaitedAppendTimers.add(handle);
+            const settled = () => {
+                timers.clearTimeout(handle);
+                awaitedAppendTimers.delete(handle);
+            };
+            Promise.resolve(write).then(() => {
+                settled();
+                resolve();
+            }, (err) => {
+                settled();
+                reject(err);
+            });
+        });
+        journalTail = journalTail.then(() => written).catch(() => undefined);
+        return written;
+    };
     const durableApprovalInherit = (s) => s.durableApproval === undefined && opts.defaultDurableApproval !== undefined ? { durableApproval: { ...opts.defaultDurableApproval } } : {};
     const journalDurableResult = (result) => {
         const t = result.terminal;
@@ -999,8 +1057,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 run.journalSkips = (run.journalSkips ?? 0) + 1;
             emitRunLog(`resume-journal: agent #${callKeyOrdinal(callKey)}${label !== undefined ? ` "${label.slice(0, 80)}"` : ""} result is ${bytes} bytes, ` +
                 `over the ${MAX_JOURNAL_RESULT_BYTES}-byte per-entry cap — NOT cached. A resume from this run re-runs this agent and everything after it live.`);
-            const tombstone = journalStore.append(runId, scope, { callKey, result: journalOversizeTombstone(stored, bytes) });
-            journalTail = journalTail.then(() => tombstone).catch(() => undefined);
+            const tombstone = trackJournalWrite(journalStore.append(runId, scope, { callKey, result: journalOversizeTombstone(stored, bytes) }), callKey);
             try {
                 await tombstone;
                 if (dbg)
@@ -1012,8 +1069,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             }
             return;
         }
-        const p = journalStore.append(runId, scope, { callKey, result: stored });
-        journalTail = journalTail.then(() => p).catch(() => undefined);
+        const p = trackJournalWrite(journalStore.append(runId, scope, { callKey, result: stored }), callKey);
         try {
             await p;
             if (dbg)
@@ -1028,9 +1084,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
     const journalAppendParked = async (callKey, paused) => {
         if (!journalStore)
             return false;
-        const p = journalStore.append(runId, scope, { callKey, parked: paused });
-        journalTail = journalTail.then(() => p).catch(() => undefined);
-        await p;
+        await trackJournalWrite(journalStore.append(runId, scope, { callKey, parked: paused }), callKey);
         return true;
     };
     const parkAgentLeg = async (rec, paused, activityTail, chargeLive) => {
@@ -1097,7 +1151,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
         bceSpawn(callKey, label, agentOpts.agentType, d.kind === "repark", (d.kind === "repark" ? d.paused.sessionId : d.result.sessionId) || undefined, model);
         if (d.kind === "repark")
             return await parkAgentLeg(rec, d.paused, [], false);
-        await settleAgentResult(rec, d.result, [], agentOpts, "awaited");
+        await settleAgentResult(rec, d.result, [], agentOpts);
         return d.result;
     };
     const createActivityCapture = (callKey, label, groupId, rec) => {
@@ -1243,11 +1297,10 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
         }
         run.timeoutInterruption = { timeoutMs: totalTimeoutMs, agentsCompleted, agentsFailed, agentsInFlight, ...(approvalWaitedMs !== undefined ? { approvalWaitedMs } : {}) };
     };
-    let divergenceNoted = false;
     const noteDivergence = (ordinal, reason) => {
-        if (opts.resumeFromRunId === undefined || divergenceNoted)
+        if (opts.resumeFromRunId === undefined || divergence !== undefined)
             return;
-        divergenceNoted = true;
+        divergence = { ordinal, reason };
         if (run.resume) {
             run.resume.divergedAtOrdinal = ordinal;
             run.resume.divergedReason = reason;
@@ -1426,7 +1479,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
         };
         return { onTurnEndUsage, rollbackUsageBeat, observedTokens: () => beatTokens };
     };
-    const settleAgentResult = async (rec, result, activityTail, agentOpts, journal) => {
+    const settleAgentResult = async (rec, result, activityTail, agentOpts) => {
         const s = result.stats;
         accumulateStats(result, true);
         rec.status = result.terminal.kind === "completed" ? "completed" : "failed";
@@ -1445,15 +1498,98 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
         emit({ type: "agent_end", runId, label: rec.label, phase: rec.phase, ...(rec.groupId !== undefined ? { groupId: rec.groupId } : {}), status: rec.status, output, ...(rec.errorCode !== undefined ? { errorCode: rec.errorCode } : {}), ...(result.stats.toolCalls !== undefined ? { toolCalls: result.stats.toolCalls } : {}), ...(result.model !== undefined ? { modelResolved: result.model } : {}), ts: rec.endedAt });
         void persist("update");
         bceTerminal(rec.callKey, rec.status === "completed" ? "completed" : "failed", output, result.sessionId || undefined, rec.stats);
-        if (journal === "awaited")
-            await journalAppend(rec.callKey, result, rec.label);
-        else {
-            void journalAppend(rec.callKey, result, rec.label).catch(() => undefined);
-        }
+        await journalAppend(rec.callKey, result, rec.label);
         if (agentOpts.schema && result.terminal.kind === "completed" && result.structuredOutput === undefined) {
             throw new WorkflowAgentSchemaError(rec.label, result);
         }
     };
+    const resumeArmOf = (callKey) => {
+        const ordinal = run.agents.length;
+        let drive;
+        const truth = opts.resumeFromRunId !== undefined ? parkedByOrdinal[ordinal] : undefined;
+        if (truth !== undefined) {
+            const d = disposeParkedOrdinal(truth, ordinal, callKey);
+            if (d.kind !== "drive")
+                return { kind: "dispose", d };
+            drive = d.drive;
+        }
+        if (parkedLeg !== undefined && drive === undefined)
+            throw parkedError();
+        if (drive !== undefined || opts.resumeFromRunId === undefined || divergence !== undefined)
+            return { kind: "live", drive };
+        const cached = replayByOrdinal[ordinal];
+        if (cached && cached.callKey === callKey && cached.result !== undefined && TERMINAL_CAUSE_IS_REPLAYABLE[cached.result.terminal.kind]) {
+            return { kind: "replay", result: cached.result };
+        }
+        noteDivergence(ordinal, cached === undefined
+            ? run.resume?.journalEntries === 0
+                ? "the journal loaded no entries"
+                : ordinal >= replayByOrdinal.length
+                    ? "a new call past the journaled prefix — the prior run ended before this point (the intended extend-the-script resume shape)"
+                    : "no journal entry at this ordinal (never recorded, e.g. an oversize result under a pre-tombstone engine, or dropped)"
+            : cached.callKey !== callKey
+                ? "the call changed — its call key changed from the journaled call's while no earlier call diverged from the record, so the difference is in this call's own inputs (the script, its args, or a host input folded into the call identity)"
+                : cached.result?.terminal?.kind === "failed" && cached.result.terminal.code === JOURNAL_OVERSIZE_ERROR_CODE
+                    ? "the prior result exceeded the journal size cap and was never cached"
+                    : `the journaled result was ${cached.result?.terminal?.kind ?? "(no terminal record)"}, not completed`);
+        return { kind: "live", drive: undefined };
+    };
+    const replayAgent = async (call, r, agentOpts) => {
+        const { label, callKey, groupId, phase, phaseInstance, prompt } = call;
+        if (finalized)
+            return r;
+        const rs = r.stats;
+        const cachedOutput = boundedRedactedSummary(r.structuredOutput ?? r.result, MAX_TRANSCRIPT_CHARS);
+        const at = now();
+        const replayModel = r.model;
+        const replayRec = {
+            label,
+            callKey,
+            ...(groupId !== undefined ? { groupId } : {}),
+            phase,
+            prompt,
+            ...(replayModel !== undefined ? { model: replayModel } : {}),
+            replayed: true,
+            status: r.terminal.kind === "completed" ? "completed" : "failed",
+            taskStatus: terminalProjection(r.terminal).status,
+            ...(r.sessionId ? { sessionId: r.sessionId } : {}),
+            ...(r.runId ? { taskRunId: r.runId } : {}),
+            queuedAt: at,
+            startedAt: at,
+            endedAt: at,
+            stats: { tokens: rs.tokens ?? 0, turns: rs.turns ?? 0, costMicroUsd: rs.costMicroUsd },
+            ...(rs.toolCalls !== undefined ? { toolCalls: rs.toolCalls } : {}),
+            output: cachedOutput,
+        };
+        if (run.resume)
+            run.resume.replayed += 1;
+        run.agents.push(replayRec);
+        if (phaseInstance)
+            agentPhaseOf.set(replayRec, phaseInstance);
+        emit({ type: "agent_start", runId, label, phase, ...(groupId !== undefined ? { groupId } : {}), callKey, prompt, ...(replayModel !== undefined ? { model: replayModel } : {}), replayed: true, ts: at });
+        emit({ type: "agent_end", runId, label, phase, ...(groupId !== undefined ? { groupId } : {}), status: replayRec.status, output: cachedOutput, ...(rs.toolCalls !== undefined ? { toolCalls: rs.toolCalls } : {}), replayed: true, ts: at });
+        bceSpawn(callKey, label, agentOpts.agentType, true, r.sessionId || undefined, replayModel);
+        bceTerminal(callKey, replayRec.status === "completed" ? "completed" : "failed", cachedOutput, r.sessionId || undefined, replayRec.stats);
+        accumulateStats(r, false);
+        void persist("update");
+        await journalAppend(callKey, r);
+        if (agentOpts.schema && r.terminal.kind === "completed" && r.structuredOutput === undefined) {
+            throw new WorkflowAgentSchemaError(label, r);
+        }
+        return r;
+    };
+    const settledHandle = (label, callKey, settled) => {
+        settled.catch(() => undefined);
+        return {
+            runId,
+            label,
+            callKey,
+            steer: async () => {
+                throw steeringError(`the task has already finished — workflow agent "${label}" was settled on this resume without running`);
+            },
+            result: () => settled,
+        };
+    };
     const ctx = {
         runId,
         budget,
@@ -1464,77 +1600,13 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
         async agent(spec, agentOpts = {}) {
             const effectiveSignal = assertAgentSpawnAllowed("ctx.agent", spec, agentOpts);
             const { label, phase, phaseInstance, groupId, inheritedModelSnap, inheritedModelRef, inheritedModelError, inheritedThinkingSnap, callKey, prompt, model } = prepareAgentCall(spec, agentOpts);
-            let drive;
-            const cached = opts.resumeFromRunId !== undefined ? replayByOrdinal[run.agents.length] : undefined;
-            const truth = opts.resumeFromRunId !== undefined ? parkedByOrdinal[run.agents.length] : undefined;
-            if (truth !== undefined) {
-                const d = disposeParkedOrdinal(truth, run.agents.length, callKey);
-                if (d.kind !== "drive")
-                    return await recordParkDisposition(d, { label, callKey, groupId, phase, phaseInstance, prompt }, agentOpts);
-                drive = d.drive;
-            }
-            if (parkedLeg !== undefined && drive === undefined)
-                throw parkedError();
-            if (opts.resumeFromRunId !== undefined && !diverged) {
-                if (drive === undefined && cached && cached.callKey === callKey && cached.result !== undefined && TERMINAL_CAUSE_IS_REPLAYABLE[cached.result.terminal.kind]) {
-                    if (finalized)
-                        return cached.result;
-                    const r = cached.result;
-                    const rs = r.stats;
-                    const cachedOutput = boundedRedactedSummary(r.structuredOutput ?? r.result, MAX_TRANSCRIPT_CHARS);
-                    const at = now();
-                    const replayModel = r.model;
-                    const replayRec = {
-                        label,
-                        callKey,
-                        ...(groupId !== undefined ? { groupId } : {}),
-                        phase,
-                        prompt,
-                        ...(replayModel !== undefined ? { model: replayModel } : {}),
-                        replayed: true,
-                        status: r.terminal.kind === "completed" ? "completed" : "failed",
-                        taskStatus: terminalProjection(r.terminal).status,
-                        ...(r.sessionId ? { sessionId: r.sessionId } : {}),
-                        ...(r.runId ? { taskRunId: r.runId } : {}),
-                        queuedAt: at,
-                        startedAt: at,
-                        endedAt: at,
-                        stats: { tokens: rs.tokens ?? 0, turns: rs.turns ?? 0, costMicroUsd: rs.costMicroUsd },
-                        ...(rs.toolCalls !== undefined ? { toolCalls: rs.toolCalls } : {}),
-                        output: cachedOutput,
-                    };
-                    if (run.resume)
-                        run.resume.replayed += 1;
-                    run.agents.push(replayRec);
-                    if (phaseInstance)
-                        agentPhaseOf.set(replayRec, phaseInstance);
-                    emit({ type: "agent_start", runId, label, phase, ...(groupId !== undefined ? { groupId } : {}), callKey, prompt, ...(replayModel !== undefined ? { model: replayModel } : {}), replayed: true, ts: at });
-                    emit({ type: "agent_end", runId, label, phase, ...(groupId !== undefined ? { groupId } : {}), status: replayRec.status, output: cachedOutput, ...(rs.toolCalls !== undefined ? { toolCalls: rs.toolCalls } : {}), replayed: true, ts: at });
-                    bceSpawn(callKey, label, agentOpts.agentType, true, r.sessionId || undefined, replayModel);
-                    bceTerminal(callKey, replayRec.status === "completed" ? "completed" : "failed", cachedOutput, r.sessionId || undefined, replayRec.stats);
-                    accumulateStats(r, false);
-                    void persist("update");
-                    await journalAppend(callKey, r);
-                    if (agentOpts.schema && r.terminal.kind === "completed" && r.structuredOutput === undefined) {
-                        throw new WorkflowAgentSchemaError(label, r);
-                    }
-                    return r;
-                }
-                if (drive === undefined) {
-                    noteDivergence(run.agents.length, cached === undefined
-                        ? run.resume?.journalEntries === 0
-                            ? "the journal loaded no entries"
-                            : run.agents.length >= replayByOrdinal.length
-                                ? "a new call past the journaled prefix — the prior run ended before this point (the intended extend-the-script resume shape)"
-                                : "no journal entry at this ordinal (never recorded, e.g. an oversize result under a pre-tombstone engine, or dropped)"
-                        : cached.callKey !== callKey
-                            ? "the call key changed — the script or its args differ here"
-                            : cached.result?.terminal?.kind === "failed" && cached.result.terminal.code === JOURNAL_OVERSIZE_ERROR_CODE
-                                ? "the prior result exceeded the journal size cap and was never cached"
-                                : `the journaled result was ${cached.result?.terminal?.kind ?? "(no terminal record)"}, not completed`);
-                    diverged = true;
-                }
-            }
+            const call = { label, callKey, groupId, phase, phaseInstance, prompt };
+            const arm = resumeArmOf(callKey);
+            if (arm.kind === "dispose")
+                return await recordParkDisposition(arm.d, call, agentOpts);
+            if (arm.kind === "replay")
+                return await replayAgent(call, arm.result, agentOpts);
+            const drive = arm.drive;
             if (budgetTotal !== null && spent() >= budgetTotal) {
                 throw new WorkflowBudgetExceededError(spent(), budgetTotal);
             }
@@ -1773,6 +1845,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             catch (err) {
                 if (drive !== undefined && !finalized && !thrownIs(err, WorkflowAgentParkedError)) {
                     emitRunLog(`[park] the parked leg "${label}" could not be driven — the resume was refused before the checkpoint was consumed (${withoutToken(errText(err), drive.token)}); the park stands.`);
+                    release();
                     return await parkAgentLeg(rec, drive.paused, activityTail, false);
                 }
                 if (!finalized) {
@@ -1811,6 +1884,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                     }
                     emit({ type: "agent_end", runId, label, phase, ...(groupId !== undefined ? { groupId } : {}), status: "failed", ...(rec.output !== undefined ? { output: rec.output } : {}), ...(rec.errorCode !== undefined ? { errorCode: rec.errorCode } : {}), ts: rec.endedAt });
                     void persist("update");
+                    release();
                     const journaled = journalAppend(callKey, salvaged ?? {
                         taskId: callKey,
                         sessionId: "",
@@ -1841,29 +1915,22 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 emitRunLog(`[park] the parked leg "${label}" was driven but the approved action never started (${result.terminal.kind === "failed" ? result.terminal.code : ""}); the park stands.`);
                 return await parkAgentLeg(rec, drive.paused, activityTail, false);
             }
-            await settleAgentResult(rec, result, activityTail, agentOpts, "awaited");
+            await settleAgentResult(rec, result, activityTail, agentOpts);
             return result;
         },
         async agentStream(spec, agentOpts = {}) {
             const effectiveSignal = assertAgentSpawnAllowed("ctx.agentStream", spec, agentOpts);
+            const { label, phase, phaseInstance, groupId, inheritedModelSnap, inheritedModelRef, inheritedModelError, inheritedThinkingSnap, callKey, prompt, model } = prepareAgentCall(spec, agentOpts);
+            const call = { label, callKey, groupId, phase, phaseInstance, prompt };
+            const arm = resumeArmOf(callKey);
+            if (arm.kind === "dispose")
+                return settledHandle(label, callKey, Promise.resolve(await recordParkDisposition(arm.d, call, agentOpts)));
+            if (arm.kind === "replay")
+                return settledHandle(label, callKey, replayAgent(call, arm.result, agentOpts));
+            const drive = arm.drive;
             if (budgetTotal !== null && spent() >= budgetTotal) {
                 throw new WorkflowBudgetExceededError(spent(), budgetTotal);
             }
-            const { label, phase, phaseInstance, groupId, inheritedModelSnap, inheritedModelRef, inheritedModelError, inheritedThinkingSnap, callKey, prompt, model } = prepareAgentCall(spec, agentOpts);
-            let drive;
-            const truth = opts.resumeFromRunId !== undefined ? parkedByOrdinal[run.agents.length] : undefined;
-            if (truth !== undefined) {
-                const d = disposeParkedOrdinal(truth, run.agents.length, callKey);
-                if (d.kind !== "drive") {
-                    const settled = await recordParkDisposition(d, { label, callKey, groupId, phase, phaseInstance, prompt }, agentOpts);
-                    return { runId, label, callKey, steer: async () => Promise.reject(new Error(`workflow agent "${label}" settled at its parked ordinal — nothing to steer`)), result: async () => settled };
-                }
-                drive = d.drive;
-            }
-            if (drive === undefined) {
-                noteDivergence(run.agents.length, "ctx.agentStream results are never replayed");
-                diverged = true;
-            }
             const rec = { label, callKey, ...(groupId !== undefined ? { groupId } : {}), phase, prompt, ...(model !== undefined ? { model } : {}), status: "running", queuedAt: now() };
             const { tail: activityTail, onActivity } = createActivityCapture(callKey, label, groupId, rec);
             run.agents.push(rec);
@@ -1991,19 +2058,22 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 const spawnMessage = thrownMessageOf(err);
                 if (!finalized && rec.errorMessage === undefined && spawnMessage !== undefined)
                     rec.errorMessage = boundedRedactedSummary(spawnMessage, MAX_TRANSCRIPT_CHARS);
-                if (!finalized && thrownIs(err, WorkflowAgentBlockedError)) {
+                const refusal = !finalized && thrownIs(err, WorkflowAgentBlockedError) ? err : undefined;
+                if (refusal !== undefined) {
                     rec.errorCode = WORKFLOW_SPAWN_BLOCKED_ERROR_CODE;
-                    rec.errorMessage = boundedRedactedSummary(err.message, MAX_TRANSCRIPT_CHARS);
-                    void journalAppend(callKey, {
+                    rec.errorMessage = boundedRedactedSummary(refusal.message, MAX_TRANSCRIPT_CHARS);
+                }
+                recordFailed();
+                releaseLeg();
+                if (refusal !== undefined) {
+                    await journalAppend(callKey, {
                         taskId: callKey,
                         sessionId: "",
-                        terminal: { kind: "failed", code: WORKFLOW_SPAWN_BLOCKED_ERROR_CODE, message: boundedRedactedSummary(err.message, 500) },
-                        result: boundedRedactedSummary(err.message, 500),
+                        terminal: { kind: "failed", code: WORKFLOW_SPAWN_BLOCKED_ERROR_CODE, message: boundedRedactedSummary(refusal.message, 500) },
+                        result: boundedRedactedSummary(refusal.message, 500),
                         stats: { turns: 0, tokens: 0, costMicroUsd: 0, usageMissing: true },
                     }).catch(() => undefined);
                 }
-                recordFailed();
-                releaseLeg();
                 bceTerminal(callKey, "failed", thrownText(err), undefined, undefined);
                 throw err;
             }
@@ -2044,7 +2114,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                     }
                     recordFailed();
                     releaseLeg();
-                    void journalAppend(callKey, {
+                    await journalAppend(callKey, {
                         taskId: callKey,
                         sessionId: "",
                         terminal: { kind: "failed", message: boundedRedactedSummary(thrownText(err), 500) },
@@ -2066,7 +2136,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                     emitRunLog(`[park] the parked leg "${label}" was driven but the approved action never started (${result.terminal.kind === "failed" ? result.terminal.code : ""}); the park stands.`);
                     return await parkAgentLeg(rec, drive.paused, activityTail, false);
                 }
-                await settleAgentResult(rec, result, activityTail, agentOpts, "best-effort");
+                await settleAgentResult(rec, result, activityTail, agentOpts);
                 return result;
             })();
             completion.catch(() => undefined);
@@ -2096,7 +2166,6 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             assertFanOutCallables("pipeline", "stage", stages);
             const errorsOut = fanOutOpts?.errors;
             noteDivergence(run.agents.length, "ctx.pipeline ordinals are latency-dependent, so its calls always run live on a resume");
-            diverged = true;
             const settled = await Promise.all(itemList.map((item, index) => stages
                 .reduce((acc, stage) => acc.then((prev) => stage(prev, item, index)), Promise.resolve(item))
                 .then((v) => ({ ok: true, v }), (e) => ({ ok: false, e, i: index }))));
@@ -2464,6 +2533,9 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                     resolve();
                 });
             });
+            for (const pending of awaitedAppendTimers)
+                timers.clearTimeout(pending);
+            awaitedAppendTimers.clear();
             if (resumeClaim !== undefined) {
                 const granted = await finalizeWithin(timers, resumeClaim.verdict.then((v) => v.granted, () => false), false);
                 if (granted) {

package/dist/scenarios/full-body.d.ts

@@ -56,7 +56,7 @@ export interface CodeToolsConfig {
 }
 /**
  * Single-source bundle of the `code` scenario's `spec.tools`-class tools, so each deployment doesn't re-wire it
- * (the single-source discipline; mirrors the blessed `SCENARIO_REGISTRY` "data (named bundles)" precedent).
+ * (the single-source discipline: a scenario is data — a named bundle).
  * Profile-as-data — the engine iterates `spec.tools` branch-free; nothing keys off the scenario name. A trusted
  * assembler (service) calls this, sets `systemPrompt = CODE_SYSTEM_PROMPT` (or `role = CODE_ROLE`) +
  * `enablePlanMode:true`, and wires the deps seams (executionEnv/onQuestion/lspManager/skillSpecs/memoryStore/