@sema-agent/core 3.0.0 → 4.0.0

package/dist/orchestration/run-workflow-tool.js

@@ -456,7 +456,7 @@ export async function createRunWorkflowTool(d) {
                     },
                 });
             }
-            if (d.notifier) {
+            {
                 let notified = false;
                 const fire = (notification) => {
                     if (notified)
@@ -467,6 +467,8 @@ export async function createRunWorkflowTool(d) {
                     }
                     catch {
                     }
+                    if (!d.notifier)
+                        return;
                     void Promise.resolve()
                         .then(() => d.notifier.notify({
                         runId,
@@ -507,40 +509,6 @@ export async function createRunWorkflowTool(d) {
                 }))
                     .catch(() => { });
             }
-            else {
-                let notified = false;
-                const fire = (notification) => {
-                    if (notified)
-                        return;
-                    notified = true;
-                    try {
-                        d.taskNotification?.(notification);
-                    }
-                    catch {
-                    }
-                };
-                handle.done
-                    .then((res) => fire({
-                    task_id: runId,
-                    task_type: "workflow",
-                    ...(ctx.toolCallId !== undefined ? { toolUseId: ctx.toolCallId } : {}),
-                    status: "completed",
-                    summary: completionSummary(meta.name, res.run),
-                    result: boundedRedactedSummary(res.result, 4000),
-                    usage: workflowUsageBlock(res.run),
-                    diagnostics: workflowDiagnostics(runId, d.journalStore?.locator?.(runId, res.run.scope), res.run.resume?.journalEntries === 0),
-                    completionId: res.run.completionId,
-                }), (err) => fire({
-                    task_id: runId,
-                    task_type: "workflow",
-                    ...(ctx.toolCallId !== undefined ? { toolUseId: ctx.toolCallId } : {}),
-                    status: "failed",
-                    summary: failureSummary(err, runId),
-                    diagnostics: workflowDiagnostics(runId, undefined),
-                    ...(completionIdFromRejection(err) !== undefined ? { completionId: completionIdFromRejection(err) } : {}),
-                }))
-                    .catch(() => { });
-            }
             return {
                 details: { type: "workflow-run", status: "backgrounded", workflowRunId: runId },
                 content: JSON.stringify({

package/dist/orchestration/workflow.d.ts

@@ -2,7 +2,7 @@ import type { TSchema } from "typebox";
 import type { Runner } from "../core/runner/runtask.js";
 import type { AgentDefinition, TaskEvent, TaskResult, TaskSpec } from "../core/types.js";
 import type { WorkflowRunStore } from "../core/workflow-run-store.js";
-import type { WorkflowJournalStore } from "../core/workflow-journal-store.js";
+import type { WorkflowJournalStore, ResumeClaimArgs } from "../core/workflow-journal-store.js";
 import type { WorkflowRun, WorkflowEvent } from "./workflow-types.js";
 export * from "./workflow-types.js";
 export declare const WORKFLOW_SUBAGENT_PROMPT = "You are a subagent spawned by a workflow orchestration script. Use the tools available to complete the task.\n\nCRITICAL: Your final text response is returned **verbatim** as a string to the calling script \u2014 it is your return value, not a message to a human.\n- Output the literal result (data, JSON, text). Do NOT output confirmations like \"Done.\" or \"Sent.\"\n- If asked for JSON, return ONLY the raw JSON \u2014 no code fences, no prose, no markdown.\n- Do NOT address a human user \u2014 there is no user on the other end. Put your answer in your final text response.\n- Do NOT delegate to further sub-agents or start nested workflows; complete the task yourself.\n- Be concise. The script will parse your output.";
@@ -131,19 +131,11 @@ export interface WorkflowTimers {
     clearTimeout(handle: unknown): void;
 }
 export declare const workflowResumeClaimFallback: {
-    acquire(store: WorkflowJournalStore, input: {
-        sourceRunId: string;
-        newRunId: string;
-        scope: string;
-    }): {
+    acquire(store: WorkflowJournalStore, input: ResumeClaimArgs): {
         granted: boolean;
         holder?: string;
     };
-    release(store: WorkflowJournalStore, input: {
-        sourceRunId: string;
-        newRunId: string;
-        scope: string;
-    }): void;
+    release(store: WorkflowJournalStore, input: ResumeClaimArgs): void;
 };
 export declare function startWorkflow<T>(runner: Runner, fn: (ctx: WorkflowRunContext) => Promise<T>, opts?: RunWorkflowOptions, internals?: WorkflowInternals): WorkflowHandle<T>;
 export declare function runWorkflow<T>(runner: Runner, fn: (ctx: WorkflowRunContext) => Promise<T>, opts?: RunWorkflowOptions, internals?: WorkflowInternals): Promise<RunWorkflowResult<T>>;

package/dist/orchestration/workflow.js

@@ -6,6 +6,7 @@ import { uuidv7 } from "../internal/harness.js";
 import { builtinAgentDefinitions } from "../agents/builtin-agents.js";
 import { GENERAL_PURPOSE_SUBAGENT_TYPE } from "../agents/subagent.js";
 import { combinePolicies, createAllowDenyPolicy } from "../core/tool-policy.js";
+import { createSafeNotifier } from "../core/safe-notify.js";
 import { callKeyOrdinal, oversizeJournalResult, journalOversizeTombstone, JOURNAL_OVERSIZE_ERROR_CODE, MAX_JOURNAL_RESULT_BYTES } from "../core/workflow-journal-store.js";
 import { isWorkflowRunActive, closeWorkflowChannel, markWorkflowActive, publishWorkflowEvent } from "./workflow-observe.js";
 import { isDurablePause, mapNestedSuspend } from "../agents/suspend-guard.js";
@@ -66,8 +67,9 @@ export function applyWorkflowAgentType(spec, agentType, registry) {
         out.model = def.model;
     if (out.thinking === undefined && def.thinking !== undefined)
         out.thinking = def.thinking;
-    if (out.limits?.maxTurns === undefined && def.maxTurns !== undefined)
+    if (out.limits?.maxTurns === undefined && typeof def.maxTurns === "number" && Number.isFinite(def.maxTurns) && def.maxTurns > 0) {
         out.limits = { ...out.limits, maxTurns: def.maxTurns };
+    }
     if (out.skills === undefined && def.skills !== undefined)
         out.skills = def.skills;
     if (out.memory === undefined && def.memory !== undefined)
@@ -124,6 +126,27 @@ function rethrowIfMaxAgents(e) {
         throw e;
     return null;
 }
+function foldFanOutSettled(settled, lane, errorsOut, emitRunLog) {
+    let dropped = 0;
+    const droppedSlots = [];
+    const results = settled.map((s) => {
+        if (s.ok)
+            return s.v;
+        if (s.e instanceof WorkflowBudgetExceededError) {
+            dropped++;
+            droppedSlots.push(s.i);
+            errorsOut?.push(workflowFanOutSlotError(s.i, s.e));
+            return null;
+        }
+        rethrowIfMaxAgents(s.e);
+        errorsOut?.push(workflowFanOutSlotError(s.i, s.e));
+        emitRunLog(`${lane}[${s.i}] failed: ${boundedRedactedSummary(s.e instanceof Error ? s.e.message : String(s.e), 300)}`);
+        return null;
+    });
+    if (dropped > 0)
+        emitRunLog(`${lane}: ${dropped} ${dropped === 1 ? "slot" : "slots"} dropped — token budget exceeded (${dropped === 1 ? "slot" : "slots"} ${droppedSlots.join(", ")})`);
+    return results;
+}
 function workflowFanOutSlotError(index, e) {
     const code = e?.code;
     const kind = typeof code === "string" && code.length > 0 ? code : e instanceof Error ? e.name : "Error";
@@ -191,6 +214,14 @@ function normalizeConcurrency(c) {
     }
     return Math.floor(c);
 }
+function normalizeWorkflowHardCap(name, v) {
+    if (v === undefined)
+        return undefined;
+    if (!Number.isFinite(v) || v < 0) {
+        throw new Error(`runWorkflow: ${name} must be a finite number ≥ 0 (got ${v})`);
+    }
+    return v;
+}
 function createSemaphore(max) {
     let active = 0;
     const waiters = [];
@@ -273,8 +304,9 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
     const concurrency = normalizeConcurrency(opts.concurrency);
     const agentRegistry = workflowAgentRegistry(opts);
     const store = opts.store;
-    const maxAgents = opts.maxAgents;
-    const maxLogChars = opts.maxLogChars;
+    const maxAgents = normalizeWorkflowHardCap("maxAgents", opts.maxAgents);
+    const maxLogChars = normalizeWorkflowHardCap("maxLogChars", opts.maxLogChars);
+    const maxResultChars = normalizeWorkflowHardCap("maxResultChars", opts.maxResultChars);
     const stallMs = opts.stallMs ?? WORKFLOW_AGENT_STALL_MS;
     const agentMaxRetries = opts.agentMaxRetries ?? WORKFLOW_AGENT_MAX_RETRIES;
     const throttleBackoffMs = opts.throttleBackoffMs ?? WORKFLOW_AGENT_THROTTLE_BACKOFF_MS;
@@ -289,13 +321,10 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
     const workflowSignal = signalSources.length === 1 ? signalSources[0] : AbortSignal.any(signalSources);
     let timeoutTimer;
     let storeRev = 0;
+    const notifier = createSafeNotifier();
     const emit = (e) => {
         publishWorkflowEvent(runId, e);
-        try {
-            opts.onEvent?.(e);
-        }
-        catch {
-        }
+        notifier.notify(() => opts.onEvent?.(e), "workflow.onEvent");
     };
     let persistTail = Promise.resolve();
     const persist = (mode) => {
@@ -445,12 +474,9 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
     };
     const bceSink = opts.onBackgroundChildEvent;
     const bceEmit = (e) => {
-        try {
-            bceSink?.(e);
-        }
-        catch {
-        }
+        notifier.notify(() => bceSink?.(e), "workflow.onBackgroundChildEvent");
     };
+    const bceParentToolCall = opts.parentToolCallId !== undefined ? { parentToolCallId: opts.parentToolCallId } : {};
     const waIdOf = (callKey) => `wa${createHash("sha256").update(`${runId}:${callKey}`).digest("hex").slice(0, 16)}`;
     const bceLive = new Map();
     const bceSpawn = (callKey, label, agentType, replayed, sessionId) => {
@@ -463,6 +489,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             taskId: id,
             sessionScoped: false,
             owner: runId,
+            ...bceParentToolCall,
             ...(sessionId !== undefined ? { sessionId, transcriptId: sessionId } : {}),
             ...(scope !== undefined ? { scope } : {}),
             description: replayed ? `${label} (replayed)` : label,
@@ -494,6 +521,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             taskId: id,
             sessionScoped: false,
             owner: runId,
+            ...bceParentToolCall,
             workflowRunId: runId,
             ...(scope !== undefined ? { scope } : {}),
             ...(row.agentType !== undefined ? { agentType: row.agentType } : { agentType: "workflow-agent" }),
@@ -518,6 +546,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             taskId: id,
             sessionScoped: false,
             owner: runId,
+            ...bceParentToolCall,
             workflowRunId: runId,
             ...(scope !== undefined ? { scope } : {}),
             ...(coord !== undefined ? { sessionId: coord, transcriptId: coord } : {}),
@@ -574,6 +603,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
         });
     };
     let journalTail = Promise.resolve();
+    const JOURNAL_DRAIN_MAX_MS = 5_000;
     const journalAppend = async (callKey, result, label) => {
         const dbg = typeof process !== "undefined" && process.env?.SEMA_DEBUG_WORKFLOW_JOURNAL === "1";
         if (!journalStore) {
@@ -712,6 +742,94 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
         rec.output = output;
         return output;
     };
+    const assertAgentSpawnAllowed = (lane, spec, agentOpts) => {
+        if (finalized) {
+            throw new Error(`workflow run already finalized — ${lane} cannot be called after the script returned`);
+        }
+        const effectiveSignal = spec.signal ?? agentOpts.signal ?? workflowSignal;
+        if (effectiveSignal?.aborted)
+            throw new Error("workflow aborted");
+        if (maxAgents !== undefined && run.agents.length >= maxAgents) {
+            throw new WorkflowMaxAgentsError(maxAgents);
+        }
+        return effectiveSignal;
+    };
+    const prepareAgentCall = (spec, agentOpts) => {
+        if (agentOpts.schema) {
+            const compiled = compileOutputSchema(agentOpts.schema);
+            if ("error" in compiled)
+                throw new TypeError(`agent({schema}) received an invalid JSON Schema: ${compiled.error}`);
+        }
+        assertSupportedAgentIsolation(agentOpts.isolation);
+        const label = agentOpts.label ?? `agent-${run.agents.length + 1}`;
+        const phase = agentOpts.phase ?? currentPhase?.title;
+        const phaseInstance = resolveAgentPhase(agentOpts.phase);
+        const groupId = currentGroup;
+        const typeDefModel = agentOpts.agentType !== undefined ? agentRegistry.find((d) => d.name === agentOpts.agentType)?.model : undefined;
+        const inheritedModelSnap = spec.model === undefined && typeDefModel === undefined ? opts.defaultModel?.() : undefined;
+        const specForIdentity = inheritedModelSnap !== undefined ? { ...spec, model: inheritedModelSnap } : spec;
+        const callKey = workflowAgentCallKey(run.agents.length, specForIdentity, agentOpts);
+        const prompt = boundedRedactedSummary(spec.systemPrompt ? `${spec.systemPrompt}\n\n${spec.objective}` : spec.objective, MAX_TRANSCRIPT_CHARS);
+        const model = workflowModelLabel(specForIdentity);
+        return { label, phase, phaseInstance, groupId, inheritedModelSnap, callKey, prompt, model };
+    };
+    const createUsageBeat = (rec) => {
+        let beatTokens = 0;
+        let beatTurns = 0;
+        let beatCostMicroUsd = 0;
+        const rollbackUsageBeat = () => {
+            if (beatTurns === 0 && beatTokens === 0 && beatCostMicroUsd === 0)
+                return false;
+            run.stats.tokens -= beatTokens;
+            run.stats.turns -= beatTurns;
+            run.stats.costMicroUsd -= beatCostMicroUsd;
+            beatTokens = 0;
+            beatTurns = 0;
+            beatCostMicroUsd = 0;
+            return true;
+        };
+        const onTurnEndUsage = (usage) => {
+            if (finalized)
+                return;
+            const turnTokens = usage ? usage.totalInputTokens + usage.outputTokens : 0;
+            const turnCost = usage?.costMicroUsd ?? 0;
+            beatTokens += turnTokens;
+            beatTurns += 1;
+            beatCostMicroUsd += turnCost;
+            run.stats.tokens += turnTokens;
+            run.stats.turns += 1;
+            run.stats.costMicroUsd += turnCost;
+            rec.stats = { tokens: beatTokens, turns: beatTurns, costMicroUsd: beatCostMicroUsd };
+            void persist("update");
+        };
+        return { onTurnEndUsage, rollbackUsageBeat };
+    };
+    const settleAgentResult = async (rec, result, activityTail, agentOpts, journal) => {
+        const s = result.stats;
+        accumulateStats(result, true);
+        rec.status = result.status === "completed" ? "completed" : "failed";
+        rec.taskStatus = result.status;
+        if (result.sessionId)
+            rec.sessionId = result.sessionId;
+        rec.endedAt = now();
+        rec.stats = { tokens: s.tokens ?? 0, turns: s.turns ?? 0, costMicroUsd: s.costMicroUsd };
+        const output = settleAgentError(rec, result, rec.label, boundedRedactedSummary(result.structuredOutput ?? result.result, MAX_TRANSCRIPT_CHARS));
+        if (result.stats.toolCalls !== undefined)
+            rec.toolCalls = result.stats.toolCalls;
+        if (activityTail.length > 0)
+            rec.activity = activityTail.slice();
+        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 } : {}), 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);
+        }
+        if (agentOpts.schema && result.status === "completed" && result.structuredOutput === undefined) {
+            throw new WorkflowAgentSchemaError(rec.label, result);
+        }
+    };
     const ctx = {
         runId,
         budget,
@@ -720,31 +838,8 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             emitRunLog(message);
         },
         async agent(spec, agentOpts = {}) {
-            if (finalized) {
-                throw new Error("workflow run already finalized — ctx.agent cannot be called after the script returned");
-            }
-            const effectiveSignal = spec.signal ?? agentOpts.signal ?? workflowSignal;
-            if (effectiveSignal?.aborted)
-                throw new Error("workflow aborted");
-            if (maxAgents !== undefined && run.agents.length >= maxAgents) {
-                throw new WorkflowMaxAgentsError(maxAgents);
-            }
-            if (agentOpts.schema) {
-                const compiled = compileOutputSchema(agentOpts.schema);
-                if ("error" in compiled)
-                    throw new TypeError(`agent({schema}) received an invalid JSON Schema: ${compiled.error}`);
-            }
-            assertSupportedAgentIsolation(agentOpts.isolation);
-            const label = agentOpts.label ?? `agent-${run.agents.length + 1}`;
-            const phase = agentOpts.phase ?? currentPhase?.title;
-            const phaseInstance = resolveAgentPhase(agentOpts.phase);
-            const groupId = currentGroup;
-            const typeDefModel = agentOpts.agentType !== undefined ? agentRegistry.find((d) => d.name === agentOpts.agentType)?.model : undefined;
-            const inheritedModelSnap = spec.model === undefined && typeDefModel === undefined ? opts.defaultModel?.() : undefined;
-            const specForIdentity = inheritedModelSnap !== undefined ? { ...spec, model: inheritedModelSnap } : spec;
-            const callKey = workflowAgentCallKey(run.agents.length, specForIdentity, agentOpts);
-            const prompt = boundedRedactedSummary(spec.systemPrompt ? `${spec.systemPrompt}\n\n${spec.objective}` : spec.objective, MAX_TRANSCRIPT_CHARS);
-            const model = workflowModelLabel(specForIdentity);
+            const effectiveSignal = assertAgentSpawnAllowed("ctx.agent", spec, agentOpts);
+            const { label, phase, phaseInstance, groupId, inheritedModelSnap, callKey, prompt, model } = prepareAgentCall(spec, agentOpts);
             if (opts.resumeFromRunId !== undefined && !diverged) {
                 const cached = replayByOrdinal[run.agents.length];
                 if (cached && cached.callKey === callKey && cached.result.status === "completed") {
@@ -913,35 +1008,8 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                         lastProgressRearm = t;
                         armWatchdog();
                     };
-                    let beatTokens = 0;
-                    let beatTurns = 0;
-                    let beatCostMicroUsd = 0;
-                    const rollbackUsageBeat = () => {
-                        if (beatTurns === 0 && beatTokens === 0 && beatCostMicroUsd === 0)
-                            return false;
-                        run.stats.tokens -= beatTokens;
-                        run.stats.turns -= beatTurns;
-                        run.stats.costMicroUsd -= beatCostMicroUsd;
-                        beatTokens = 0;
-                        beatTurns = 0;
-                        beatCostMicroUsd = 0;
-                        return true;
-                    };
+                    const { onTurnEndUsage, rollbackUsageBeat } = createUsageBeat(rec);
                     activeUsageBeats.add(rollbackUsageBeat);
-                    const onTurnEndUsage = (usage) => {
-                        if (finalized)
-                            return;
-                        const turnTokens = usage ? usage.totalInputTokens + usage.outputTokens : 0;
-                        const turnCost = usage?.costMicroUsd ?? 0;
-                        beatTokens += turnTokens;
-                        beatTurns += 1;
-                        beatCostMicroUsd += turnCost;
-                        run.stats.tokens += turnTokens;
-                        run.stats.turns += 1;
-                        run.stats.costMicroUsd += turnCost;
-                        rec.stats = { tokens: beatTokens, turns: beatTurns, costMicroUsd: beatCostMicroUsd };
-                        void persist("update");
-                    };
                     try {
                         attemptResult = await workflowDepthStore.run({ depth: depth + 1 }, async () => {
                             if (typeof runner.runTaskStream !== "function") {
@@ -963,8 +1031,11 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                         attemptError = err;
                     }
                     finally {
-                        rollbackUsageBeat();
+                        const attemptHadSpend = rollbackUsageBeat();
                         activeUsageBeats.delete(rollbackUsageBeat);
+                        if (attemptError !== undefined && attemptHadSpend && !finalized && rec.stats !== undefined) {
+                            accumulateStats({ stats: rec.stats }, true);
+                        }
                         disarmWatchdog();
                         effectiveSignal?.removeEventListener("abort", onCallerAbort);
                     }
@@ -1073,57 +1144,15 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             if (isDurablePause(result.status)) {
                 result = mapNestedSuspend(result);
             }
-            const s = result.stats;
-            accumulateStats(result, true);
-            rec.status = result.status === "completed" ? "completed" : "failed";
-            rec.taskStatus = result.status;
-            if (result.sessionId)
-                rec.sessionId = result.sessionId;
-            rec.endedAt = now();
-            rec.stats = { tokens: s.tokens ?? 0, turns: s.turns ?? 0, costMicroUsd: s.costMicroUsd };
-            const output = settleAgentError(rec, result, label, boundedRedactedSummary(result.structuredOutput ?? result.result, MAX_TRANSCRIPT_CHARS));
-            if (result.stats.toolCalls !== undefined)
-                rec.toolCalls = result.stats.toolCalls;
-            if (activityTail.length > 0)
-                rec.activity = activityTail.slice();
-            emit({ type: "agent_end", runId, label, phase, ...(groupId !== undefined ? { groupId } : {}), status: rec.status, output, ...(rec.errorCode !== undefined ? { errorCode: rec.errorCode } : {}), ...(result.stats.toolCalls !== undefined ? { toolCalls: result.stats.toolCalls } : {}), ts: rec.endedAt });
-            void persist("update");
-            bceTerminal(callKey, rec.status === "completed" ? "completed" : "failed", output, result.sessionId || undefined, rec.stats);
-            await journalAppend(callKey, result, label);
-            if (agentOpts.schema && result.status === "completed" && result.structuredOutput === undefined) {
-                throw new WorkflowAgentSchemaError(label, result);
-            }
+            await settleAgentResult(rec, result, activityTail, agentOpts, "awaited");
             return result;
         },
         async agentStream(spec, agentOpts = {}) {
-            if (finalized) {
-                throw new Error("workflow run already finalized — ctx.agentStream cannot be called after the script returned");
-            }
-            const effectiveSignal = spec.signal ?? agentOpts.signal ?? workflowSignal;
-            if (effectiveSignal?.aborted)
-                throw new Error("workflow aborted");
-            if (maxAgents !== undefined && run.agents.length >= maxAgents) {
-                throw new WorkflowMaxAgentsError(maxAgents);
-            }
+            const effectiveSignal = assertAgentSpawnAllowed("ctx.agentStream", spec, agentOpts);
             if (budgetTotal !== null && spent() >= budgetTotal) {
                 throw new WorkflowBudgetExceededError(spent(), budgetTotal);
             }
-            if (agentOpts.schema) {
-                const compiled = compileOutputSchema(agentOpts.schema);
-                if ("error" in compiled)
-                    throw new TypeError(`agent({schema}) received an invalid JSON Schema: ${compiled.error}`);
-            }
-            assertSupportedAgentIsolation(agentOpts.isolation);
-            const label = agentOpts.label ?? `agent-${run.agents.length + 1}`;
-            const phase = agentOpts.phase ?? currentPhase?.title;
-            const phaseInstance = resolveAgentPhase(agentOpts.phase);
-            const groupId = currentGroup;
-            const typeDefModel = agentOpts.agentType !== undefined ? agentRegistry.find((d) => d.name === agentOpts.agentType)?.model : undefined;
-            const inheritedModelSnap = spec.model === undefined && typeDefModel === undefined ? opts.defaultModel?.() : undefined;
-            const specForIdentity = inheritedModelSnap !== undefined ? { ...spec, model: inheritedModelSnap } : spec;
-            const callKey = workflowAgentCallKey(run.agents.length, specForIdentity, agentOpts);
-            const prompt = boundedRedactedSummary(spec.systemPrompt ? `${spec.systemPrompt}\n\n${spec.objective}` : spec.objective, MAX_TRANSCRIPT_CHARS);
-            const model = workflowModelLabel(specForIdentity);
+            const { label, phase, phaseInstance, groupId, inheritedModelSnap, callKey, prompt, model } = prepareAgentCall(spec, agentOpts);
             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() };
@@ -1215,35 +1244,8 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 await stream.steer(framed, { trusted: true });
                 return marker;
             };
-            let beatTokens = 0;
-            let beatTurns = 0;
-            let beatCostMicroUsd = 0;
-            const rollbackUsageBeat = () => {
-                if (beatTurns === 0 && beatTokens === 0 && beatCostMicroUsd === 0)
-                    return false;
-                run.stats.tokens -= beatTokens;
-                run.stats.turns -= beatTurns;
-                run.stats.costMicroUsd -= beatCostMicroUsd;
-                beatTokens = 0;
-                beatTurns = 0;
-                beatCostMicroUsd = 0;
-                return true;
-            };
+            const { onTurnEndUsage, rollbackUsageBeat } = createUsageBeat(rec);
             activeUsageBeats.add(rollbackUsageBeat);
-            const onTurnEndUsage = (usage) => {
-                if (finalized)
-                    return;
-                const turnTokens = usage ? usage.totalInputTokens + usage.outputTokens : 0;
-                const turnCost = usage?.costMicroUsd ?? 0;
-                beatTokens += turnTokens;
-                beatTurns += 1;
-                beatCostMicroUsd += turnCost;
-                run.stats.tokens += turnTokens;
-                run.stats.turns += 1;
-                run.stats.costMicroUsd += turnCost;
-                rec.stats = { tokens: beatTokens, turns: beatTurns, costMicroUsd: beatCostMicroUsd };
-                void persist("update");
-            };
             const completion = (async () => {
                 let result;
                 try {
@@ -1259,14 +1261,18 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 catch (err) {
                     rollbackUsageBeat();
                     activeUsageBeats.delete(rollbackUsageBeat);
+                    const partialSpend = rec.stats;
+                    if (!finalized && partialSpend !== undefined && (partialSpend.tokens > 0 || partialSpend.turns > 0 || (partialSpend.costMicroUsd ?? 0) > 0)) {
+                        accumulateStats({ stats: partialSpend }, true);
+                    }
                     recordFailed();
                     releaseOnce();
-                    await journalAppend(callKey, {
+                    void journalAppend(callKey, {
                         taskId: callKey,
                         sessionId: "",
                         status: "failed",
                         result: boundedRedactedSummary(err instanceof Error ? err.message : String(err), 500),
-                        stats: { turns: 0, tokens: 0, costMicroUsd: 0 },
+                        stats: { turns: partialSpend?.turns ?? 0, tokens: partialSpend?.tokens ?? 0, costMicroUsd: partialSpend?.costMicroUsd ?? 0 },
                     }).catch(() => undefined);
                     bceTerminal(callKey, "failed", err instanceof Error ? err.message : String(err), undefined, rec.stats);
                     throw err;
@@ -1279,26 +1285,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 if (isDurablePause(result.status)) {
                     result = mapNestedSuspend(result);
                 }
-                const s = result.stats;
-                accumulateStats(result, true);
-                rec.status = result.status === "completed" ? "completed" : "failed";
-                rec.taskStatus = result.status;
-                if (result.sessionId)
-                    rec.sessionId = result.sessionId;
-                rec.endedAt = now();
-                rec.stats = { tokens: s.tokens ?? 0, turns: s.turns ?? 0, costMicroUsd: s.costMicroUsd };
-                const output = settleAgentError(rec, result, label, boundedRedactedSummary(result.structuredOutput ?? result.result, MAX_TRANSCRIPT_CHARS));
-                if (result.stats.toolCalls !== undefined)
-                    rec.toolCalls = result.stats.toolCalls;
-                if (activityTail.length > 0)
-                    rec.activity = activityTail.slice();
-                emit({ type: "agent_end", runId, label, phase, ...(groupId !== undefined ? { groupId } : {}), status: rec.status, output, ...(rec.errorCode !== undefined ? { errorCode: rec.errorCode } : {}), ...(result.stats.toolCalls !== undefined ? { toolCalls: result.stats.toolCalls } : {}), ts: rec.endedAt });
-                void persist("update");
-                bceTerminal(callKey, rec.status === "completed" ? "completed" : "failed", output, result.sessionId || undefined, rec.stats);
-                await journalAppend(callKey, result, label).catch(() => undefined);
-                if (agentOpts.schema && result.status === "completed" && result.structuredOutput === undefined) {
-                    throw new WorkflowAgentSchemaError(label, result);
-                }
+                await settleAgentResult(rec, result, activityTail, agentOpts, "best-effort");
                 return result;
             })();
             completion.catch(() => undefined);
@@ -1312,25 +1299,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             const settled = await Promise.all(thunks.map((t, i) => Promise.resolve()
                 .then(t)
                 .then((v) => ({ ok: true, v }), (e) => ({ ok: false, e, i }))));
-            let dropped = 0;
-            const droppedSlots = [];
-            const results = settled.map((s) => {
-                if (s.ok)
-                    return s.v;
-                if (s.e instanceof WorkflowBudgetExceededError) {
-                    dropped++;
-                    droppedSlots.push(s.i);
-                    errorsOut?.push(workflowFanOutSlotError(s.i, s.e));
-                    return null;
-                }
-                rethrowIfMaxAgents(s.e);
-                errorsOut?.push(workflowFanOutSlotError(s.i, s.e));
-                emitRunLog(`parallel[${s.i}] failed: ${boundedRedactedSummary(s.e instanceof Error ? s.e.message : String(s.e), 300)}`);
-                return null;
-            });
-            if (dropped > 0)
-                emitRunLog(`parallel: ${dropped} ${dropped === 1 ? "slot" : "slots"} dropped — token budget exceeded (${dropped === 1 ? "slot" : "slots"} ${droppedSlots.join(", ")})`);
-            return results;
+            return foldFanOutSettled(settled, "parallel", errorsOut, emitRunLog);
         },
         async pipeline(items, ...stagesAndOpts) {
             if (items.length > MAX_WORKFLOW_ITEMS) {
@@ -1350,25 +1319,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             const settled = await Promise.all(items.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 }))));
-            let dropped = 0;
-            const droppedSlots = [];
-            const results = settled.map((s) => {
-                if (s.ok)
-                    return s.v;
-                if (s.e instanceof WorkflowBudgetExceededError) {
-                    dropped++;
-                    droppedSlots.push(s.i);
-                    errorsOut?.push(workflowFanOutSlotError(s.i, s.e));
-                    return null;
-                }
-                rethrowIfMaxAgents(s.e);
-                errorsOut?.push(workflowFanOutSlotError(s.i, s.e));
-                emitRunLog(`pipeline[${s.i}] failed: ${boundedRedactedSummary(s.e instanceof Error ? s.e.message : String(s.e), 300)}`);
-                return null;
-            });
-            if (dropped > 0)
-                emitRunLog(`pipeline: ${dropped} ${dropped === 1 ? "slot" : "slots"} dropped — token budget exceeded (${dropped === 1 ? "slot" : "slots"} ${droppedSlots.join(", ")})`);
-            return results;
+            return foldFanOutSettled(settled, "pipeline", errorsOut, emitRunLog);
         },
         async phase(title, body) {
             if (finalized)
@@ -1531,7 +1482,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             else {
                 result = await bodyPromise;
             }
-            if (opts.maxResultChars !== undefined) {
+            if (maxResultChars !== undefined) {
                 let size = 0;
                 try {
                     size = JSON.stringify(result)?.length ?? 0;
@@ -1539,8 +1490,8 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 catch {
                     size = 0;
                 }
-                if (size > opts.maxResultChars)
-                    throw new WorkflowResultTooLargeError(size, opts.maxResultChars);
+                if (size > maxResultChars)
+                    throw new WorkflowResultTooLargeError(size, maxResultChars);
             }
             finalized = true;
             settleActiveUsageBeats();
@@ -1587,7 +1538,16 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
         }
         finally {
             finalized = true;
-            await journalTail.catch(() => undefined);
+            await new Promise((resolve) => {
+                const t = setTimeout(() => {
+                    emitRunLog(`resume-journal: terminal drain did not settle within ${JOURNAL_DRAIN_MAX_MS}ms — tail entries may be missing; a resume from this run re-runs those agents live.`);
+                    resolve();
+                }, JOURNAL_DRAIN_MAX_MS);
+                void journalTail.catch(() => undefined).then(() => {
+                    clearTimeout(t);
+                    resolve();
+                });
+            });
             if (resumeClaim !== undefined) {
                 const granted = await finalizeWithin(timers, resumeClaim.verdict.then((v) => v.granted, () => false), false);
                 if (granted) {