@signalridge/pi-workflows 1.3.2 → 1.5.0

package/src/engine.ts

@@ -19,10 +19,12 @@
 
 import { createHash, randomUUID } from "node:crypto";
 import type { ManagedSpawnResponse } from "@signalridge/pi-subagents-protocol";
+import { isManagedAgentTier } from "@signalridge/pi-subagents-protocol";
 import { WorkflowError, WorkflowErrorCode, wrapError } from "./errors.js";
 import {
   buildResumeJournal,
   type CallResult,
+  type CallTierIdentity,
   deriveRecoveryId,
   JOURNAL_ENTRY_TYPE,
   JOURNAL_SCHEMA_VERSION,
@@ -39,6 +41,7 @@ import {
 import {
   createManagedSpawnClient,
   type DispatchTask,
+  type ManagedProtocolCheck,
   type ManagedSpawnClient,
   type WorkflowEventBus,
 } from "./rpc-client.js";
@@ -46,10 +49,17 @@ import {
   type AgentRunOptions,
   type AgentUsage,
   type JournalEntry,
+  MAX_AGENTS_PER_RUN,
+  normalizeAgentRetries,
+  normalizeAgentTimeout,
+  normalizeConcurrency,
+  normalizeMaxAgents,
+  normalizeTokenBudget,
   parseWorkflowScript,
   runWorkflow,
   type WorkflowAgentRunner,
   type WorkflowRunResult,
+  type WorkflowRuntimeEvent,
 } from "./runtime.js";
 
 export const MAX_ATTEMPTS_PER_NODE = 3;
@@ -78,6 +88,8 @@ export interface ScriptStartOptions {
   concurrency?: number;
   agentRetries?: number;
   tokenBudget?: number | null;
+  /** True for a script this package ships; see WorkflowRunOptions.shippedScript. */
+  shippedScript?: boolean;
   agentTimeoutMs?: number | null;
   toolset?: string;
   excludeTools?: string[];
@@ -93,7 +105,13 @@ export interface ScriptStartOptions {
       timeoutMs?: number;
     },
   ) => Promise<unknown>;
-  loadSavedWorkflow?: (name: string) => string | undefined;
+  /**
+   * Resolve a nested `workflow(name)` reference. The result reports whether the
+   * script it returned ships with this package, because that decides how the
+   * child frame treats a tier name the host does not define — see
+   * `WorkflowRunOptions.shippedScript`.
+   */
+  loadSavedWorkflow?: (name: string) => { script: string; shippedScript?: boolean } | undefined;
   mainModel?: string;
 }
 
@@ -106,12 +124,41 @@ export interface ScriptStartResult {
   waitAborted?: boolean;
 }
 
+interface AgentLifecycleWaiter {
+  callIndex: string;
+  generation: number;
+  onUsage?: (usage: AgentUsage) => void;
+  onHistory?: (history: unknown[]) => void;
+  executionGeneration: number;
+  resolve: (response: ManagedSpawnResponse) => void;
+  reject: (error: unknown) => void;
+  settled: boolean;
+}
+
+interface AgentTerminalDelivery {
+  response: ManagedSpawnResponse;
+  usage?: AgentUsage;
+  history?: unknown[];
+}
+
+interface BufferedAgentTerminal extends AgentTerminalDelivery {
+  owner: WorkflowOwner;
+  executionGeneration: number;
+}
+
 export interface ScriptRunState {
   run: ScriptRun;
   /** Frozen run parameters — resume reuses the original values, ignoring new budget/toolset overrides. */
   frozenOptions: Pick<
     ScriptStartOptions,
-    "tokenBudget" | "maxAgents" | "concurrency" | "agentRetries" | "agentTimeoutMs" | "toolset" | "excludeTools"
+    | "tokenBudget"
+    | "maxAgents"
+    | "concurrency"
+    | "agentRetries"
+    | "agentTimeoutMs"
+    | "toolset"
+    | "shippedScript"
+    | "excludeTools"
   >;
   /** Abort controller for this run's script execution. */
   controller: AbortController;
@@ -123,22 +170,14 @@ export interface ScriptRunState {
   result?: unknown;
   /** Per-call-index generation base for A4 spawnKey rotation (seeded from journal). */
   generations: Map<string, number>;
+  /** Resolved tier identity for live calls, including stopped terminal results. */
+  callTiers: Map<string, CallTierIdentity>;
   /** Live dispatch waiters keyed by agent id. */
-  agentWaiters: Map<
-    string,
-    {
-      callIndex: string;
-      generation: number;
-      onUsage?: (usage: AgentUsage) => void;
-      onHistory?: (history: unknown[]) => void;
-      executionGeneration: number;
-      resolve: (r: ManagedSpawnResponse) => void;
-      reject: (e: unknown) => void;
-      settled: boolean;
-    }
-  >;
+  agentWaiters: Map<string, AgentLifecycleWaiter>;
+  /** Owner-validated terminal events emitted before their spawn reply/waiter. */
+  bufferedTerminals: Map<string, BufferedAgentTerminal>;
   /** Allocations whose managed-spawn reply has not arrived yet. */
-  pendingSpawns: Map<string, { spawnKey: string; owner: WorkflowOwner }>;
+  pendingSpawns: Map<string, { spawnKey: string; owner: WorkflowOwner; executionGeneration: number }>;
   /** Journal retry bookkeeping. */
   pendingJournal: Set<string>;
   /** Whether a lifecycle suspension is in effect (branch change). */
@@ -153,6 +192,60 @@ function managedTerminalStatus(snapshot: { status: string }): "completed" | "fai
   return snapshot.status === "completed" ? "completed" : snapshot.status === "failed" ? "failed" : "stopped";
 }
 
+function updateCallTierIdentity(state: ScriptRunState, nodeId: string, tier: unknown): boolean {
+  if (!isManagedAgentTier(tier)) return false;
+  if (state.callTiers.get(nodeId)?.tier === tier) return false;
+  const identity: CallTierIdentity = { tier };
+  state.callTiers.set(nodeId, identity);
+  state.run.callTiers[nodeId] = identity;
+  return true;
+}
+
+function callIndexFromOwnerNode(nodeId: string): string | undefined {
+  return nodeId.startsWith("call-") ? nodeId.slice("call-".length) : undefined;
+}
+
+function renderWorkflowValue(value: unknown): string {
+  if (typeof value === "string") return value;
+  try {
+    const serialized = JSON.stringify(value, null, 2);
+    return serialized === undefined ? String(value) : serialized;
+  } catch {
+    return String(value);
+  }
+}
+
+function cloneWorkflowValue(value: unknown, label: string): unknown {
+  if (value === undefined) return undefined;
+  try {
+    const cloned = structuredClone(value);
+    const serialized = JSON.stringify(cloned);
+    if (serialized === undefined) throw new Error("value is not JSON-serializable");
+    if (serialized.length > 200_000) {
+      throw new Error("value exceeds the 200000-character workflow persistence limit");
+    }
+    return cloned;
+  } catch (error: unknown) {
+    throw new WorkflowError(
+      `${label} must be structured-cloneable and JSON-serializable: ${error instanceof Error ? error.message : String(error)}`,
+      WorkflowErrorCode.SCRIPT_VALIDATION_ERROR,
+      { recoverable: false, details: error },
+    );
+  }
+}
+
+function cloneWorkflowArgs(value: unknown): unknown {
+  return cloneWorkflowValue(value, "Workflow args");
+}
+
+function cloneWorkflowResult(value: unknown): unknown {
+  return cloneWorkflowValue(value, "Workflow result");
+}
+
+function cloneRuntimeEvent(event: WorkflowRuntimeEvent): WorkflowRuntimeEvent {
+  return structuredClone(event);
+}
+
 function resultFromLifecycle(
   status: "completed" | "failed" | "stopped",
   agentId: string | undefined,
@@ -160,10 +253,12 @@ function resultFromLifecycle(
   error: string | undefined,
   compactionCount: number,
   tokenCount?: number,
+  tier?: string,
 ): CallResult {
   return {
     status,
     ...(agentId ? { agentId } : {}),
+    ...(tier === undefined ? {} : { tier }),
     ...(result !== undefined && result.length > 0 ? { result } : {}),
     ...(error !== undefined && error.length > 0 ? { error } : {}),
     ...(tokenCount !== undefined ? { tokenCount } : {}),
@@ -179,15 +274,29 @@ function generationFromAttemptId(attemptId: string | undefined): number {
   return match ? Number(match[1]) : 0;
 }
 
+function sameWorkflowOwner(left: WorkflowOwner, right: WorkflowOwner): boolean {
+  return (
+    left.extension === right.extension &&
+    left.runId === right.runId &&
+    left.nodeId === right.nodeId &&
+    left.attemptId === right.attemptId
+  );
+}
+
 export class WorkflowEngine {
   private readonly runs = new Map<string, ScriptRunState>();
   /** Fired when a run settles terminal; wired by the UI surface for widget refresh. */
   onRunSettled: (() => void) | undefined;
+  /** Optional in-process observer for phase/task/quality runtime events. */
+  onRuntimeEvent: ((runId: string, event: WorkflowRuntimeEvent) => void) | undefined;
   private readonly waiters = new Map<
     string,
     Set<{ resolve: (run: ScriptRun) => void; reject: (e: unknown) => void; settled: boolean; cleanup: () => void }>
   >();
   private unsubscribeLifecycle: () => void;
+  private readonly protocolGate: () => Promise<ManagedProtocolCheck>;
+  private readonly disposeController = new AbortController();
+  private disposed = false;
   private lifecyclePaused = false;
   private branchQuiescePromise: Promise<WorkflowQuiesceResult> | undefined;
   private recoveryBranchGeneration = 0;
@@ -202,10 +311,37 @@ export class WorkflowEngine {
     private readonly client: ManagedSpawnClient,
     private readonly journal: JournalWriter,
     private readonly readEntries: () => readonly SessionEntryLike[] = () => [],
+    protocolGate?: () => Promise<ManagedProtocolCheck>,
   ) {
+    this.protocolGate =
+      protocolGate ??
+      (() => this.client.checkProtocol?.() ?? Promise.reject(new Error("managed protocol check is unavailable")));
     this.unsubscribeLifecycle = this.attachLifecycle();
   }
 
+  private async awaitProtocol(): Promise<ManagedProtocolCheck> {
+    if (this.disposed) throw new WorkflowEngineDisposedError();
+    let rejectDisposed: ((reason?: unknown) => void) | undefined;
+    const disposed = new Promise<never>((_, reject) => {
+      rejectDisposed = reject;
+    });
+    const onDisposed = () => rejectDisposed?.(new WorkflowEngineDisposedError());
+    this.disposeController.signal.addEventListener("abort", onDisposed, { once: true });
+    let result: ManagedProtocolCheck;
+    try {
+      result = await Promise.race([this.protocolGate(), disposed]);
+    } finally {
+      this.disposeController.signal.removeEventListener("abort", onDisposed);
+    }
+    if (this.disposed) throw new WorkflowEngineDisposedError();
+    return result;
+  }
+
+  /** Whether this engine can still accept new workflow executions. */
+  isDisposed(): boolean {
+    return this.disposed;
+  }
+
   private attachLifecycle(): () => void {
     const unsubs = [
       "subagents:created",
@@ -224,63 +360,157 @@ export class WorkflowEngine {
   }
 
   private onLifecycle(eventName: string, raw: unknown): void {
+    if (
+      eventName !== "subagents:created" &&
+      eventName !== "subagents:started" &&
+      eventName !== "subagents:completed" &&
+      eventName !== "subagents:failed"
+    )
+      return;
     if (!raw || typeof raw !== "object") return;
     const data = raw as Record<string, unknown>;
     const agentId = typeof data.id === "string" ? data.id : typeof data.agentId === "string" ? data.agentId : undefined;
     if (!agentId) return;
 
-    // Resolve a live dispatch waiter on terminal lifecycle events.
-    if (eventName === "subagents:completed" || eventName === "subagents:failed") {
-      const lifecycleStatus =
-        eventName === "subagents:completed"
-          ? "completed"
-          : data.status === "stopped" || data.status === "interrupted"
-            ? "stopped"
-            : "failed";
-      for (const state of this.runs.values()) {
-        const waiter = state.agentWaiters.get(agentId);
-        if (!waiter || waiter.settled || waiter.executionGeneration !== state.executionGeneration) continue;
-        const owner = data.owner;
-        if (!owner || typeof owner !== "object" || Array.isArray(owner)) continue;
-        const ownerRecord = owner as Record<string, unknown>;
-        if (
-          ownerRecord.extension !== "pi-workflows" ||
-          ownerRecord.runId !== state.run.runId ||
-          ownerRecord.nodeId !== `call-${waiter.callIndex}` ||
-          ownerRecord.attemptId !== `attempt-${waiter.generation}`
-        )
-          continue;
-        const tokenCount =
-          typeof data.tokenCount === "number"
-            ? data.tokenCount
-            : data.tokens &&
-                typeof data.tokens === "object" &&
-                typeof (data.tokens as Record<string, unknown>).total === "number"
-              ? ((data.tokens as Record<string, unknown>).total as number)
-              : undefined;
-        waiter.settled = true;
-        const terminal: ManagedSpawnResponse = {
-          id: agentId,
-          terminal: {
-            status: lifecycleStatus,
-            ...(typeof data.result === "string" ? { result: data.result } : {}),
-            ...(typeof data.error === "string" ? { error: data.error } : {}),
-            ...(typeof data.outputFile === "string" ? { outputFile: data.outputFile } : {}),
-            ...(tokenCount === undefined ? {} : { tokenCount }),
-            compactionCount: typeof data.compactionCount === "number" ? data.compactionCount : 0,
-            completedAt: typeof data.completedAt === "number" ? data.completedAt : Date.now(),
-          },
-        };
-        state.agentWaiters.delete(agentId);
-        if (tokenCount !== undefined)
-          waiter.onUsage?.({ input: 0, output: tokenCount, total: tokenCount, cost: 0, cacheRead: 0, cacheWrite: 0 });
-        if (Array.isArray(data.history)) waiter.onHistory?.(data.history);
-        waiter.resolve(terminal);
-      }
+    const rawOwner = data.owner;
+    if (!rawOwner || typeof rawOwner !== "object" || Array.isArray(rawOwner)) return;
+    const ownerRecord = rawOwner as Record<string, unknown>;
+    if (
+      ownerRecord.extension !== "pi-workflows" ||
+      typeof ownerRecord.runId !== "string" ||
+      typeof ownerRecord.nodeId !== "string" ||
+      typeof ownerRecord.attemptId !== "string"
+    )
+      return;
+    const owner: WorkflowOwner = {
+      extension: "pi-workflows",
+      runId: ownerRecord.runId,
+      nodeId: ownerRecord.nodeId,
+      attemptId: ownerRecord.attemptId,
+    };
+    const state = this.runs.get(owner.runId);
+    if (state?.run.status !== "running" || state.lifecycleSuspended || state.controller.signal.aborted) return;
+    const callNodeId = callIndexFromOwnerNode(owner.nodeId);
+    if (callNodeId === undefined) return;
+
+    // Validate ownership and the current attempt before accepting any identity
+    // from the host. A delayed lifecycle fact from an older attempt must not
+    // overwrite the tier identity of the current attempt.
+    const spawnKey = `${owner.runId}/${owner.nodeId}/${owner.attemptId}`;
+    const pending = state.pendingSpawns.get(spawnKey);
+    const waiter = state.agentWaiters.get(agentId);
+    const waiterMatches = Boolean(
+      waiter &&
+        !waiter.settled &&
+        waiter.executionGeneration === state.executionGeneration &&
+        owner.nodeId === `call-${waiter.callIndex}` &&
+        owner.attemptId === `attempt-${waiter.generation}`,
+    );
+    const pendingMatches = Boolean(
+      pending && pending.executionGeneration === state.executionGeneration && sameWorkflowOwner(pending.owner, owner),
+    );
+    if (!waiterMatches && !pendingMatches) return;
+    // Top-level journal attempts carry the full run/node/attempt identity while
+    // lifecycle owners carry the short attempt token. Nested calls have no
+    // top-level attempt fact and are fenced by their pending/waiter owner.
+    const currentAttemptId = state.run.attemptIds[callNodeId];
+    if (currentAttemptId !== undefined && currentAttemptId !== `${owner.runId}/${callNodeId}/${owner.attemptId}`)
+      return;
+
+    if (updateCallTierIdentity(state, callNodeId, data.tier)) {
+      this.persistCallTierIdentity(state, callNodeId);
     }
+    // Created/started lifecycle facts carry managed identity before the RPC
+    // reply is necessarily available. They are observation-only here; terminal
+    // ownership is handled below once a completion/failure fact arrives.
+    if (eventName !== "subagents:completed" && eventName !== "subagents:failed") return;
+
+    const lifecycleStatus =
+      eventName === "subagents:completed"
+        ? "completed"
+        : data.status === "stopped" || data.status === "interrupted"
+          ? "stopped"
+          : "failed";
+    const tokenCount =
+      typeof data.tokenCount === "number"
+        ? data.tokenCount
+        : data.tokens &&
+            typeof data.tokens === "object" &&
+            typeof (data.tokens as Record<string, unknown>).total === "number"
+          ? ((data.tokens as Record<string, unknown>).total as number)
+          : undefined;
+    const delivery: AgentTerminalDelivery = {
+      response: {
+        id: agentId,
+        terminal: {
+          status: lifecycleStatus,
+          ...(typeof data.result === "string" ? { result: data.result } : {}),
+          ...(typeof data.error === "string" ? { error: data.error } : {}),
+          ...(typeof data.outputFile === "string" ? { outputFile: data.outputFile } : {}),
+          ...(tokenCount === undefined ? {} : { tokenCount }),
+          compactionCount: typeof data.compactionCount === "number" ? data.compactionCount : 0,
+          completedAt: typeof data.completedAt === "number" ? data.completedAt : Date.now(),
+        },
+      },
+      ...(tokenCount === undefined
+        ? {}
+        : { usage: { input: 0, output: tokenCount, total: tokenCount, cost: 0, cacheRead: 0, cacheWrite: 0 } }),
+      ...(Array.isArray(data.history) ? { history: [...data.history] } : {}),
+    };
+
+    if (waiterMatches && waiter) {
+      this.resolveAgentWaiter(state, agentId, waiter, delivery);
+      return;
+    }
+
+    // spawn-managed can emit a terminal lifecycle event synchronously before its
+    // reply continuation registers the agent-id waiter. Buffer only an owner
+    // that is currently awaiting that exact reply in this execution generation.
+    if (!pendingMatches || state.bufferedTerminals.has(spawnKey) || state.bufferedTerminals.size >= MAX_AGENTS_PER_RUN)
+      return;
+    state.bufferedTerminals.set(spawnKey, { ...delivery, owner, executionGeneration: state.executionGeneration });
+  }
+
+  /** Persist a host-normalized tier learned before the managed reply arrives. */
+  private persistCallTierIdentity(state: ScriptRunState, nodeId: string): void {
+    const attemptId = state.run.attemptIds[nodeId];
+    const identity = state.callTiers.get(nodeId);
+    // Nested workflow frames are in-memory only; only a top-level call has a
+    // durable attempt owner and can safely receive a journal transition.
+    if (!attemptId || identity?.tier === undefined) return;
+    this.persist(state.run.runId, `call-tier:${nodeId}`, () =>
+      this.write({
+        kind: "call_transition",
+        schemaVersion: JOURNAL_SCHEMA_VERSION,
+        runId: state.run.runId,
+        nodeId,
+        status: "running",
+        tier: identity.tier,
+        attemptId,
+        owner: { extension: "pi-workflows", runId: state.run.runId, nodeId, attemptId },
+        timestamp: Date.now(),
+      }),
+    );
+  }
+
+  private resolveAgentWaiter(
+    state: ScriptRunState,
+    agentId: string,
+    waiter: AgentLifecycleWaiter,
+    delivery: AgentTerminalDelivery,
+  ): void {
+    if (waiter.settled) return;
+    waiter.settled = true;
+    state.agentWaiters.delete(agentId);
+    if (delivery.usage) waiter.onUsage?.(delivery.usage);
+    if (delivery.history) waiter.onHistory?.(delivery.history);
+    waiter.resolve(delivery.response);
   }
 
   dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.disposeController.abort();
     this.unsubscribeLifecycle();
     this.quarantinedRunIds.clear();
     for (const state of this.runs.values()) {
@@ -289,25 +519,25 @@ export class WorkflowEngine {
     }
     this.rejectWaiters(new WorkflowWaitAbortedError());
     this.runs.clear();
-    for (const timer of this.providerResumeTimers.values()) clearTimeout(timer);
-    this.providerResumeTimers.clear();
+    this.clearJournalRetries();
     this.branchQuiescePromise = undefined;
   }
 
   suspendLifecycle(): void {
-    if (this.lifecyclePaused) return;
+    if (this.disposed || this.lifecyclePaused) return;
     this.lifecyclePaused = true;
     this.unsubscribeLifecycle();
   }
 
   resumeLifecycle(): void {
-    if (!this.lifecyclePaused) return;
+    if (this.disposed || !this.lifecyclePaused) return;
     this.lifecyclePaused = false;
     this.unsubscribeLifecycle = this.attachLifecycle();
   }
 
   /** Stop owned agents while Pi replaces the active session-tree branch. */
   async quiesceForBranchChange(): Promise<WorkflowQuiesceResult> {
+    if (this.disposed) return { settled: true, pending: [] };
     if (this.branchQuiescePromise) return this.branchQuiescePromise;
     this.clearJournalRetries();
 
@@ -329,6 +559,7 @@ export class WorkflowEngine {
       });
       targets.set(state.run.runId, { agentIds, owners });
       state.lifecycleSuspended = true;
+      state.bufferedTerminals.clear();
       state.controller.abort(new DOMException("Workflow branch change", "AbortError"));
     }
 
@@ -389,23 +620,50 @@ export class WorkflowEngine {
    * the body it executes).
    */
   async start(script: string, options: ScriptStartOptions = {}): Promise<ScriptStartResult> {
+    if (this.disposed) throw new WorkflowEngineDisposedError();
+    const protocol = await this.awaitProtocol();
+    if (this.disposed) throw new WorkflowEngineDisposedError();
     const { meta } = parseWorkflowScript(script);
     const now = Date.now();
     const runId = randomUUID();
     const scriptHash = hashScript(script);
     const toolset = options.toolset;
+    const shippedScript = options.shippedScript === true ? true : undefined;
+    const durableArgs = cloneWorkflowArgs(options.args);
+    const runtimeArgs = cloneWorkflowArgs(durableArgs);
+    const journalArgs = cloneWorkflowArgs(durableArgs);
+    const frozenArgsPresent = durableArgs !== undefined;
+    const frozenMaxAgents = options.maxAgents === undefined ? undefined : normalizeMaxAgents(options.maxAgents);
+    const frozenConcurrency = options.concurrency === undefined ? undefined : normalizeConcurrency(options.concurrency);
+    const frozenAgentRetries =
+      options.agentRetries === undefined ? undefined : normalizeAgentRetries(options.agentRetries);
+    const frozenTokenBudget = options.tokenBudget === undefined ? undefined : normalizeTokenBudget(options.tokenBudget);
+    const frozenAgentTimeoutMs =
+      options.agentTimeoutMs === undefined ? undefined : normalizeAgentTimeout(options.agentTimeoutMs);
+    const startOptions: ScriptStartOptions = {
+      ...options,
+      ...(runtimeArgs === undefined ? {} : { args: runtimeArgs }),
+      ...(frozenMaxAgents === undefined ? {} : { maxAgents: frozenMaxAgents }),
+      ...(frozenConcurrency === undefined ? {} : { concurrency: frozenConcurrency }),
+      ...(frozenAgentRetries === undefined ? {} : { agentRetries: frozenAgentRetries }),
+      ...(frozenTokenBudget === undefined ? {} : { tokenBudget: frozenTokenBudget }),
+      ...(frozenAgentTimeoutMs === undefined ? {} : { agentTimeoutMs: frozenAgentTimeoutMs }),
+    };
     const run: ScriptRun = {
       runId,
       schemaVersion: JOURNAL_SCHEMA_VERSION,
       script,
       scriptHash,
       meta,
+      ...(durableArgs === undefined ? {} : { args: durableArgs }),
+      frozenArgsPresent,
+      ...(shippedScript === undefined ? {} : { shippedScript }),
       ...(toolset ? { toolset } : {}),
-      ...(options.maxAgents !== undefined ? { frozenMaxAgents: options.maxAgents } : {}),
-      ...(options.concurrency !== undefined ? { frozenConcurrency: options.concurrency } : {}),
-      ...(options.agentRetries !== undefined ? { frozenAgentRetries: options.agentRetries } : {}),
-      ...(options.tokenBudget !== undefined ? { frozenTokenBudget: options.tokenBudget } : {}),
-      ...(options.agentTimeoutMs !== undefined ? { frozenAgentTimeoutMs: options.agentTimeoutMs } : {}),
+      ...(frozenMaxAgents !== undefined ? { frozenMaxAgents } : {}),
+      ...(frozenConcurrency !== undefined ? { frozenConcurrency } : {}),
+      ...(frozenAgentRetries !== undefined ? { frozenAgentRetries } : {}),
+      ...(frozenTokenBudget !== undefined ? { frozenTokenBudget } : {}),
+      ...(frozenAgentTimeoutMs !== undefined ? { frozenAgentTimeoutMs } : {}),
       ...(options.excludeTools ? { frozenExcludeTools: [...options.excludeTools] } : {}),
       status: "pending",
       callStatus: {},
@@ -413,6 +671,8 @@ export class WorkflowEngine {
       attempts: {},
       attemptIds: {},
       callResults: {},
+      callTiers: {},
+      workflowResultGenerations: {},
       compactions: {},
       startedAt: now,
       updatedAt: now,
@@ -424,29 +684,35 @@ export class WorkflowEngine {
       script,
       scriptHash,
       meta,
+      ...(journalArgs === undefined ? {} : { args: journalArgs }),
+      frozenArgsPresent,
+      ...(shippedScript === undefined ? {} : { shippedScript }),
       ...(toolset ? { toolset } : {}),
-      ...(options.maxAgents !== undefined ? { frozenMaxAgents: options.maxAgents } : {}),
-      ...(options.concurrency !== undefined ? { frozenConcurrency: options.concurrency } : {}),
-      ...(options.agentRetries !== undefined ? { frozenAgentRetries: options.agentRetries } : {}),
-      ...(options.tokenBudget !== undefined ? { frozenTokenBudget: options.tokenBudget } : {}),
-      ...(options.agentTimeoutMs !== undefined ? { frozenAgentTimeoutMs: options.agentTimeoutMs } : {}),
+      ...(frozenMaxAgents !== undefined ? { frozenMaxAgents } : {}),
+      ...(frozenConcurrency !== undefined ? { frozenConcurrency } : {}),
+      ...(frozenAgentRetries !== undefined ? { frozenAgentRetries } : {}),
+      ...(frozenTokenBudget !== undefined ? { frozenTokenBudget } : {}),
+      ...(frozenAgentTimeoutMs !== undefined ? { frozenAgentTimeoutMs } : {}),
       ...(options.excludeTools ? { frozenExcludeTools: [...options.excludeTools] } : {}),
       timestamp: now,
     });
     const state: ScriptRunState = {
       run,
       frozenOptions: {
-        ...(options.tokenBudget !== undefined ? { tokenBudget: options.tokenBudget } : {}),
-        ...(options.maxAgents !== undefined ? { maxAgents: options.maxAgents } : {}),
-        ...(options.concurrency !== undefined ? { concurrency: options.concurrency } : {}),
-        ...(options.agentRetries !== undefined ? { agentRetries: options.agentRetries } : {}),
-        ...(options.agentTimeoutMs !== undefined ? { agentTimeoutMs: options.agentTimeoutMs } : {}),
+        ...(frozenTokenBudget !== undefined ? { tokenBudget: frozenTokenBudget } : {}),
+        ...(frozenMaxAgents !== undefined ? { maxAgents: frozenMaxAgents } : {}),
+        ...(frozenConcurrency !== undefined ? { concurrency: frozenConcurrency } : {}),
+        ...(frozenAgentRetries !== undefined ? { agentRetries: frozenAgentRetries } : {}),
+        ...(frozenAgentTimeoutMs !== undefined ? { agentTimeoutMs: frozenAgentTimeoutMs } : {}),
         ...(options.toolset ? { toolset: options.toolset } : {}),
+        ...(shippedScript === undefined ? {} : { shippedScript }),
         ...(options.excludeTools ? { excludeTools: [...options.excludeTools] } : {}),
       },
       controller: new AbortController(),
       generations: new Map(),
+      callTiers: new Map(Object.entries(run.callTiers ?? {})),
       agentWaiters: new Map(),
+      bufferedTerminals: new Map(),
       pendingSpawns: new Map(),
       pendingJournal: new Set(),
       lifecycleSuspended: false,
@@ -455,7 +721,7 @@ export class WorkflowEngine {
     this.runs.set(runId, state);
     this.setWorkflowStatus(run, "running");
     state.executionGeneration += 1;
-    state.execution = this.execute(runId, script, options, undefined, state.executionGeneration);
+    state.execution = this.execute(runId, script, startOptions, undefined, state.executionGeneration, protocol);
     // A run-fatal abort/stop already journals its terminal state; never let a
     // leftover rejection become an unhandled promise rejection.
     void state.execution.catch(() => {});
@@ -468,7 +734,7 @@ export class WorkflowEngine {
         runId,
         status: settled.status,
         background: false,
-        ...(scriptResult !== undefined ? { result: String(scriptResult) } : {}),
+        ...(scriptResult !== undefined ? { result: renderWorkflowValue(scriptResult) } : {}),
         ...(settled.error ? { error: settled.error } : {}),
       };
     } catch (error: unknown) {
@@ -490,6 +756,9 @@ export class WorkflowEngine {
     options: ScriptStartOptions = {},
     replacementScript?: string,
   ): Promise<ScriptStartResult | undefined> {
+    if (this.disposed) throw new WorkflowEngineDisposedError();
+    const protocol = await this.awaitProtocol();
+    if (this.disposed) throw new WorkflowEngineDisposedError();
     const state = this.runs.get(runId);
     if (!state) return undefined;
     if (state.lifecycleSuspended) return undefined;
@@ -521,6 +790,9 @@ export class WorkflowEngine {
         }),
       );
     }
+    // Arguments are frozen in every schema-v4 run_created fact. Resume never accepts
+    // replacement args and never backfills the pre-schema-v4 run_args contract.
+    const resumeArgs = cloneWorkflowArgs(run.args);
     const resumeJournal = buildResumeJournal(entries);
     // Seed generation bases from journaled attemptIds so a live re-dispatch of a
     // previously-journaled call never reuses a spawnKey (A4).
@@ -529,22 +801,32 @@ export class WorkflowEngine {
     }
     this.setWorkflowStatus(run, "running");
     state.controller = new AbortController();
-    // Freeze semantics: original run parameters win over new options.
-    // Only signal/confirm/args/background/loadSavedWorkflow/mainModel are per-resume context;
-    // budget/scale/toolset are frozen from the original start.
+    // Freeze semantics: original run parameters and args win over new options.
+    // Only signal/confirm/background/loadSavedWorkflow/mainModel are per-resume context;
+    // input/budget/scale/toolset are frozen from the original start.
     const frozen = state.frozenOptions;
     const resumeOptions: ScriptStartOptions = {
       ...options,
+      args: resumeArgs,
       tokenBudget: frozen.tokenBudget,
       maxAgents: frozen.maxAgents,
       concurrency: frozen.concurrency,
       agentRetries: frozen.agentRetries,
       agentTimeoutMs: frozen.agentTimeoutMs,
       toolset: frozen.toolset,
+      shippedScript: frozen.shippedScript,
       excludeTools: frozen.excludeTools ? [...frozen.excludeTools] : undefined,
     };
+    state.bufferedTerminals.clear();
     state.executionGeneration += 1;
-    state.execution = this.execute(runId, run.script, resumeOptions, resumeJournal, state.executionGeneration);
+    state.execution = this.execute(
+      runId,
+      run.script,
+      resumeOptions,
+      resumeJournal,
+      state.executionGeneration,
+      protocol,
+    );
     void state.execution.catch(() => {});
     if (options.background) return { runId, status: run.status, background: true };
     try {
@@ -561,6 +843,10 @@ export class WorkflowEngine {
     runId?: string,
     entries?: readonly SessionEntryLike[],
   ): Promise<{ action: string; runs?: unknown[]; run?: unknown }> {
+    if (this.disposed) {
+      if (action === "list") return { action, runs: [] };
+      throw new WorkflowEngineDisposedError();
+    }
     if (action === "list") return { action, runs: this.list() };
     if (!runId) throw new Error(`${action} requires runId`);
     const state = this.runs.get(runId);
@@ -624,6 +910,7 @@ export class WorkflowEngine {
     if (!state) throw new Error(`workflow run not found: ${runId}`);
     if (isTerminalWorkflow(state.run.status) || state.run.status === "paused" || state.run.status === "interrupted")
       return state.run;
+    if (signal?.aborted) throw new WorkflowWaitAbortedError();
     const all =
       this.waiters.get(runId) ??
       new Set<{
@@ -689,7 +976,9 @@ export class WorkflowEngine {
     options: ScriptStartOptions,
     resumeJournal?: Map<string, JournalEntry>,
     executionGeneration?: number,
+    protocol?: ManagedProtocolCheck,
   ): Promise<WorkflowRunResult<unknown>> {
+    if (this.disposed) throw new WorkflowEngineDisposedError();
     const state = this.runs.get(runId);
     if (!state) throw new Error(`workflow run not found: ${runId}`);
     const generation = executionGeneration ?? state.executionGeneration;
@@ -705,6 +994,12 @@ export class WorkflowEngine {
         args: options.args,
         agent: runner,
         mainModel: options.mainModel,
+        ...(protocol === undefined
+          ? {}
+          : {
+              routingPolicy: protocol.routingPolicy,
+              routingPolicyFingerprint: protocol.routingPolicyFingerprint,
+            }),
         concurrency: options.concurrency,
         agentRetries: options.agentRetries,
         tokenBudget: options.tokenBudget,
@@ -712,24 +1007,43 @@ export class WorkflowEngine {
         signal: state.controller.signal,
         maxAgents: options.maxAgents,
         runId,
+        executionNonce: `${generation}-${randomUUID()}`,
         resumeJournal,
         toolset: options.toolset,
+        shippedScript: options.shippedScript,
         excludeTools: options.excludeTools,
         confirm: options.confirm,
         loadSavedWorkflow: options.loadSavedWorkflow,
         onAgentJournal: (entry) => {
-          // Nested workflow frames use their own run ids. They are intentionally
-          // not persisted as top-level call facts until a namespaced journal exists;
-          // mixing them into the parent would quarantine the run on replay.
+          if (state.executionGeneration !== generation) return;
+          // Nested workflow frames keep their own lifecycle visibility, but their
+          // individual call facts are not top-level replay keys. The parent
+          // workflow_result fact below owns the nested replay boundary.
           if (entry.runId === undefined || entry.runId === runId) this.journalCallResult(runId, entry);
         },
-        onRuntimeEvent: () => {},
+        onWorkflowJournal: (entry) => {
+          if (state.executionGeneration !== generation) return;
+          this.journalWorkflowResult(runId, entry);
+        },
+        onRuntimeEvent: (event) => {
+          if (state.executionGeneration !== generation) return;
+          try {
+            this.events.emit("pi-workflows:runtime", { runId, event: cloneRuntimeEvent(event) });
+          } catch {
+            // Cross-extension observers cannot change workflow execution.
+          }
+          try {
+            this.onRuntimeEvent?.(runId, cloneRuntimeEvent(event));
+          } catch {
+            // UI observers are diagnostic surfaces and are independently contained.
+          }
+        },
       });
       const live = this.runs.get(runId);
-      if (live && state.executionGeneration === generation) live.result = result.result;
       const run = live?.run;
       if (run && state.executionGeneration === generation && !isTerminalWorkflow(run.status)) {
-        this.setWorkflowStatus(run, "completed");
+        this.setWorkflowStatus(run, "completed", undefined, undefined, result.result);
+        live.result = result.result;
       }
       return result;
     } catch (error: unknown) {
@@ -758,11 +1072,12 @@ export class WorkflowEngine {
 
   /**
    * Dispatch one live agent() call through spawn-managed with an A4-rotated
-   * spawnKey: `${runId}/call-${callIndex}/attempt-${generation}`. The generation
-   * combines the journaled base (so a resume of an edited call lands on a fresh
-   * key) with the runtime's per-attempt counter.
+   * spawnKey: `${runId}/call-${callIndex}/attempt-${generation}`. Top-level calls
+   * use numeric call indexes; nested workflow frames use a generation/nonce
+   * namespace so a changed child cannot reuse a stale managed identity.
    */
   private async dispatchAgent(runId: string, prompt: string, runOptions: AgentRunOptions): Promise<unknown> {
+    if (this.disposed) throw new WorkflowEngineDisposedError();
     const state = this.runs.get(runId);
     if (!state) throw new Error(`workflow run not found: ${runId}`);
     if (state.lifecycleSuspended || state.controller.signal.aborted) {
@@ -773,13 +1088,19 @@ export class WorkflowEngine {
     const run = state.run;
     const executionGeneration = state.executionGeneration;
     const callIndex = runOptions.callIndex ?? state.generations.size;
+    const frameRunId = runOptions.runId ?? runId;
+    const nested = frameRunId !== runId;
+    // Top-level calls use their numeric lexical index. Nested frames use a
+    // run-local namespace so child call 0 can never collide with the parent's
+    // call 0 or with a sibling nested workflow. The managed owner remains the
+    // top-level run: nested workflow results are journaled as one parent fact.
+    const nodeId = nested ? `${frameRunId}:${callIndex}` : String(callIndex);
     // The spawnKey identity carries the `call-` prefix (A4):
-    //   spawnKey = `${runId}/call-${callIndex}/attempt-${generation}`
-    // The journal node identity is the bare call index, and the journal
-    // attemptId is the full `${runId}/${nodeId}/attempt-${generation}` path the
-    // journal replay validates.
-    const spawnNodeId = `call-${callIndex}`;
-    const nodeId = String(callIndex);
+    //   spawnKey = `${runId}/call-${nodeId}/attempt-${generation}`
+    // The journal node identity is the bare call index for top-level calls;
+    // nested identities are in-memory only and are never persisted as agent
+    // facts.
+    const spawnNodeId = `call-${nodeId}`;
     const base = state.generations.get(nodeId) ?? 0;
     const generation = base + (runOptions.attempt ?? 1);
     state.generations.set(nodeId, generation);
@@ -787,39 +1108,53 @@ export class WorkflowEngine {
     const attemptId = `${runId}/${nodeId}/attempt-${generation}`;
 
     const type = runOptions.agentType ?? "general-purpose";
-    const tier =
-      runOptions.tier === "small" || runOptions.tier === "medium" || runOptions.tier === "large"
-        ? runOptions.tier
-        : undefined;
+    const tier = runOptions.tier;
+    if (tier !== undefined && !isManagedAgentTier(tier)) {
+      throw new WorkflowError(
+        `agent tier must be a non-empty, whitespace-free key (received ${String(tier)})`,
+        WorkflowErrorCode.SCRIPT_VALIDATION_ERROR,
+        { recoverable: false },
+      );
+    }
+    // This dispatch is authoritative for the current script revision. Do not
+    // carry an identity from the previous script: deleting `tier` must clear
+    // the recorded one instead of silently preserving the old route.
+    const tierIdentity: CallTierIdentity = tier === undefined ? {} : { tier };
+    state.callTiers.set(nodeId, tierIdentity);
+    run.callTiers[nodeId] = tierIdentity;
     const task: DispatchTask = {
       subagent_type: type,
       prompt,
       description: runOptions.label ?? `workflow call ${callIndex}`,
       ...(tier === undefined ? {} : { tier }),
-      ...(runOptions.model === undefined ? {} : { model: runOptions.model }),
       ...(runOptions.thread === undefined ? {} : { thread: runOptions.thread }),
       ...(runOptions.toolset === undefined ? {} : { toolset: runOptions.toolset }),
       ...(runOptions.excludeTools === undefined ? {} : { excludeTools: runOptions.excludeTools }),
       ...(runOptions.isolation === undefined ? {} : { isolation: runOptions.isolation }),
     };
 
-    // Journal the attempt rotation so a later resume knows the generation base.
-    this.persist(runId, `call-attempt:${nodeId}`, () =>
-      this.write({
-        kind: "call_attempt",
-        schemaVersion: JOURNAL_SCHEMA_VERSION,
-        runId,
-        nodeId,
-        attemptId,
-        generation,
-        owner: { extension: "pi-workflows", runId, nodeId, attemptId },
-        timestamp: Date.now(),
-      }),
-    );
-    run.callStatus[nodeId] = "running";
-    run.attempts[nodeId] = generation;
-    run.attemptIds[nodeId] = attemptId;
-    run.updatedAt = Date.now();
+    // Journal the attempt rotation only for top-level calls. A nested frame is
+    // represented by its parent workflow_result replay boundary instead of
+    // leaking child call facts into the parent's numeric call namespace.
+    if (!nested) {
+      this.persist(runId, `call-attempt:${nodeId}`, () =>
+        this.write({
+          kind: "call_attempt",
+          schemaVersion: JOURNAL_SCHEMA_VERSION,
+          runId,
+          nodeId,
+          attemptId,
+          generation,
+          ...(tierIdentity.tier === undefined ? {} : { tier: tierIdentity.tier }),
+          owner: { extension: "pi-workflows", runId, nodeId, attemptId },
+          timestamp: Date.now(),
+        }),
+      );
+      run.callStatus[nodeId] = "running";
+      run.attempts[nodeId] = generation;
+      run.attemptIds[nodeId] = attemptId;
+      run.updatedAt = Date.now();
+    }
 
     // Abort linkage: an external signal (pause/stop/Esc) cancels the wait and
     // stops the owned agent. Track the spawn key before the RPC reply arrives so
@@ -832,9 +1167,9 @@ export class WorkflowEngine {
       nodeId: spawnNodeId,
       attemptId: spawnAttemptId,
     };
-    const pendingKey = `${nodeId}\u0000${generation}`;
-    state.pendingSpawns.set(pendingKey, { spawnKey, owner });
+    state.pendingSpawns.set(spawnKey, { spawnKey, owner, executionGeneration });
     const reconcilePending = () => {
+      state.bufferedTerminals.delete(spawnKey);
       const reconciliation = this.client.reconcileManaged?.(spawnKey, owner);
       void reconciliation?.catch(() => {});
     };
@@ -845,10 +1180,10 @@ export class WorkflowEngine {
     let pendingId = "";
     let response: ManagedSpawnResponse | string;
     try {
-      response = await this.client.spawn(task, runId, spawnNodeId, spawnAttemptId, undefined, externalSignal);
+      response = await this.client.spawn(task, runId, spawnNodeId, spawnAttemptId, externalSignal);
     } finally {
       externalSignal.removeEventListener("abort", onPendingAbort);
-      state.pendingSpawns.delete(pendingKey);
+      state.pendingSpawns.delete(spawnKey);
     }
     const responseId = typeof response === "string" ? response : response.id;
     if (
@@ -856,6 +1191,7 @@ export class WorkflowEngine {
       state.controller.signal.aborted ||
       externalSignal.aborted
     ) {
+      state.bufferedTerminals.delete(spawnKey);
       await this.client
         .stopOwned?.(responseId, { extension: "pi-workflows", runId, nodeId: spawnNodeId, attemptId: spawnAttemptId })
         .catch(() => {});
@@ -865,9 +1201,18 @@ export class WorkflowEngine {
         { recoverable: true },
       );
     }
+    if (typeof response !== "string" && updateCallTierIdentity(state, nodeId, response.tier)) {
+      this.persistCallTierIdentity(state, nodeId);
+    }
+    // Report the tier the host actually selected back to the runtime, which
+    // journals it: a call that named none still resolved to something, and the
+    // run's own record of what ran should say what.
+    const resolvedTierIdentity = state.callTiers.get(nodeId);
+    if (resolvedTierIdentity?.tier !== undefined) runOptions.onTierResolved?.(resolvedTierIdentity.tier);
     if (typeof response === "string") {
       pendingId = response;
     } else if (response.terminal) {
+      state.bufferedTerminals.delete(spawnKey);
       // The spawn response already carries a terminal snapshot (fast completion
       // or interrupted replay). The runtime journals successful calls itself
       // (onAgentJournal); a terminal snapshot that is NOT a success is
@@ -891,9 +1236,10 @@ export class WorkflowEngine {
           terminal.error,
           terminal.compactionCount,
           terminal.tokenCount,
+          resolvedTierIdentity?.tier ?? tier,
         );
         result.attemptId = attemptId;
-        this.commitCallTerminal(runId, nodeId, result);
+        if (!nested) this.commitCallTerminal(runId, nodeId, result);
         if (status === "failed" && terminal.error) {
           throw wrapError(new Error(terminal.error), { agentLabel: runOptions.label });
         }
@@ -908,6 +1254,7 @@ export class WorkflowEngine {
       if (waiter && !waiter.settled) {
         waiter.settled = true;
         state.agentWaiters.delete(pendingId);
+        state.bufferedTerminals.delete(spawnKey);
         void this.client
           .stopOwned?.(pendingId, {
             extension: "pi-workflows",
@@ -920,10 +1267,11 @@ export class WorkflowEngine {
       }
     };
 
-    // Wait for the terminal lifecycle event.
+    // Wait for the terminal lifecycle event, consuming a matching terminal that
+    // arrived while the managed-spawn reply was still pending.
     const terminal = await new Promise<ManagedSpawnResponse>((resolve, reject) => {
-      const waiter = {
-        callIndex: String(callIndex),
+      const waiter: AgentLifecycleWaiter = {
+        callIndex: nodeId,
         generation,
         executionGeneration,
         onUsage: runOptions.onUsage,
@@ -934,7 +1282,24 @@ export class WorkflowEngine {
       };
       state.agentWaiters.set(pendingId, waiter);
       externalSignal.addEventListener("abort", waitAbort, { once: true });
-      if (externalSignal.aborted) waitAbort();
+      if (externalSignal.aborted) {
+        waitAbort();
+        return;
+      }
+
+      const buffered = state.bufferedTerminals.get(spawnKey);
+      if (!buffered) return;
+      state.bufferedTerminals.delete(spawnKey);
+      if (
+        buffered.executionGeneration !== executionGeneration ||
+        state.executionGeneration !== executionGeneration ||
+        state.lifecycleSuspended ||
+        state.controller.signal.aborted ||
+        buffered.response.id !== pendingId ||
+        !sameWorkflowOwner(buffered.owner, owner)
+      )
+        return;
+      this.resolveAgentWaiter(state, pendingId, waiter, buffered);
     }).finally(() => {
       externalSignal.removeEventListener("abort", waitAbort);
     });
@@ -956,13 +1321,16 @@ export class WorkflowEngine {
         snapshot.error,
         snapshot.compactionCount,
         snapshot.tokenCount,
+        state.callTiers.get(nodeId)?.tier ?? tier,
       );
       result.attemptId = attemptId;
-      this.commitCallTerminal(runId, nodeId, result);
+      if (!nested) this.commitCallTerminal(runId, nodeId, result);
       if (status === "failed" && snapshot.error) {
         throw wrapError(new Error(snapshot.error), { agentLabel: runOptions.label });
       }
     }
+    const completedTierIdentity = state.callTiers.get(nodeId);
+    if (completedTierIdentity?.tier !== undefined) runOptions.onTierResolved?.(completedTierIdentity.tier);
     return snapshot.result ?? "";
   }
 
@@ -972,9 +1340,12 @@ export class WorkflowEngine {
     const run = state.run;
     const nodeId = String(entry.index);
     const result = entry.result;
+    const callTierIdentity: CallTierIdentity =
+      entry.tier === undefined ? (run.callTiers[nodeId] ?? {}) : { tier: entry.tier };
     const callResult: CallResult = {
       status: "completed",
       ...(typeof result === "string" && result.length === 0 ? {} : { result }),
+      ...callTierIdentity,
       compactionCount: 0,
       updatedAt: Date.now(),
     };
@@ -996,10 +1367,47 @@ export class WorkflowEngine {
     };
     this.persist(runId, `call-result:${nodeId}`, () => this.write(event));
     run.callResults[nodeId] = callResult;
+    run.callTiers[nodeId] = callResult.tier === undefined ? {} : { tier: callResult.tier };
     run.callStatus[nodeId] = "completed";
     run.updatedAt = Date.now();
   }
 
+  private journalWorkflowResult(runId: string, entry: JournalEntry): void {
+    const state = this.runs.get(runId);
+    if (!state) return;
+    const nodeId = String(entry.index);
+    const result: CallResult = {
+      status: "completed",
+      ...(entry.result === undefined ? {} : { result: entry.result }),
+      ...(entry.tier === undefined ? {} : { tier: entry.tier }),
+      compactionCount: 0,
+      updatedAt: Date.now(),
+    };
+    const event: JournalEvent = {
+      kind: "workflow_result",
+      schemaVersion: JOURNAL_SCHEMA_VERSION,
+      runId,
+      nodeId,
+      result,
+      generation: entry.generation ?? 1,
+      ...(entry.agentCount === undefined ? {} : { agentCount: entry.agentCount }),
+      callHash: entry.hash,
+      ...(entry.storeDelta !== undefined && Object.keys(entry.storeDelta).length > 0
+        ? { storeDelta: entry.storeDelta }
+        : {}),
+      timestamp: Date.now(),
+    };
+    // The parent cannot become completed until this replay boundary is durable;
+    // otherwise a transient append retry would arrive after the terminal
+    // transition and be discarded as stale during restore.
+    this.appendRequired(event);
+    state.run.workflowResultGenerations[nodeId] = event.generation;
+    state.run.callResults[nodeId] = result;
+    state.run.callTiers[nodeId] = result.tier === undefined ? {} : { tier: result.tier };
+    state.run.callStatus[nodeId] = "completed";
+    state.run.updatedAt = Date.now();
+  }
+
   private commitCallTerminal(runId: string, nodeId: string, result: CallResult): void {
     const state = this.runs.get(runId);
     if (!state) return;
@@ -1017,6 +1425,7 @@ export class WorkflowEngine {
     };
     this.persist(runId, `call-terminal:${nodeId}`, () => this.write(event));
     run.callResults[nodeId] = result;
+    run.callTiers[nodeId] = result.tier === undefined ? {} : { tier: result.tier };
     run.callStatus[nodeId] = result.status;
     if (result.agentId) run.agentIds[nodeId] = result.agentId;
     run.compactions[nodeId] = Math.max(run.compactions[nodeId] ?? 0, result.compactionCount);
@@ -1031,6 +1440,7 @@ export class WorkflowEngine {
       void reconciliation?.catch(() => {});
     }
     state.pendingSpawns.clear();
+    state.bufferedTerminals.clear();
   }
 
   private async quiescePendingSpawns(state: ScriptRunState): Promise<WorkflowQuiesceResult> {
@@ -1093,6 +1503,8 @@ export class WorkflowEngine {
           undefined,
           "workflow stopped",
           run.compactions[nodeId] ?? 0,
+          undefined,
+          state.callTiers.get(nodeId)?.tier,
         );
         result.attemptId = run.attemptIds[nodeId];
         terminalResults.push({
@@ -1183,7 +1595,7 @@ export class WorkflowEngine {
       this.journal.append(event);
     } catch (error: unknown) {
       throw new WorkflowError(
-        `Could not persist workflow start: ${error instanceof Error ? error.message : String(error)}`,
+        `Could not persist workflow ${event.kind}: ${error instanceof Error ? error.message : String(error)}`,
         WorkflowErrorCode.PERSISTENCE_ERROR,
         { recoverable: true, details: error },
       );
@@ -1247,11 +1659,19 @@ export class WorkflowEngine {
       this.providerResumeTimers.delete(runId);
       const state = this.runs.get(runId);
       if (state?.run.status !== "paused") return;
-      void this.resume(runId, this.readEntries(), { background: true }).catch((error: unknown) => {
-        console.warn(
-          `[pi-workflows] automatic provider-limit resume failed: ${error instanceof Error ? error.message : String(error)}`,
-        );
-      });
+      void Promise.resolve()
+        .then(() => {
+          const current = this.runs.get(runId);
+          if (current?.run.status !== "paused") return;
+          // resume() is the single authorization gate and captures the fresh
+          // routing-policy fingerprint for this execution.
+          return this.resume(runId, this.readEntries(), { background: true });
+        })
+        .catch((error: unknown) => {
+          console.warn(
+            `[pi-workflows] automatic provider-limit resume failed: ${error instanceof Error ? error.message : String(error)}`,
+          );
+        });
     }, delay);
     timer.unref?.();
     this.providerResumeTimers.set(runId, timer);
@@ -1271,8 +1691,13 @@ export class WorkflowEngine {
     status: ScriptRun["status"],
     error?: string,
     terminalIntent?: "stop" | "failure",
+    finalResult?: unknown,
   ): void {
     if (isTerminalWorkflow(run.status) && !isTerminalWorkflow(status)) return;
+    // Validate and isolate terminal values before best-effort persistence or any
+    // status mutation. A bad result must still be able to transition the run to failed.
+    const durableFinalResult = finalResult === undefined ? undefined : cloneWorkflowResult(finalResult);
+    const runFinalResult = finalResult === undefined ? undefined : cloneWorkflowResult(finalResult);
     const timestamp = Date.now();
     this.persist(run.runId, `transition:${status}`, () =>
       this.write({
@@ -1281,15 +1706,18 @@ export class WorkflowEngine {
         runId: run.runId,
         status,
         ...(error !== undefined ? { error } : {}),
+        ...(durableFinalResult !== undefined ? { finalResult: durableFinalResult } : {}),
         ...(terminalIntent !== undefined ? { terminalIntent } : {}),
         timestamp,
       }),
     );
     run.status = status;
     if (error !== undefined) run.error = error;
+    if (runFinalResult !== undefined) run.finalResult = runFinalResult;
     if (terminalIntent !== undefined) run.terminalIntent = terminalIntent;
     run.updatedAt = timestamp;
     if (isTerminalWorkflow(status)) {
+      this.runs.get(run.runId)?.bufferedTerminals.clear();
       this.settleWaiters(run.runId, run);
       this.onRunSettled?.();
     }
@@ -1298,6 +1726,7 @@ export class WorkflowEngine {
   // ── restore / summary ──────────────────────────────────────────────────────
 
   restore(entries: readonly SessionEntryLike[], branchGeneration = 0): void {
+    if (this.disposed) return;
     // A branch replay is a replacement, not a merge. Runs absent from the new
     // branch must not remain controllable or append facts into it.
     this.clearJournalRetries();
@@ -1321,11 +1750,14 @@ export class WorkflowEngine {
           ...(run.frozenAgentRetries !== undefined ? { agentRetries: run.frozenAgentRetries } : {}),
           ...(run.frozenAgentTimeoutMs !== undefined ? { agentTimeoutMs: run.frozenAgentTimeoutMs } : {}),
           ...(run.toolset ? { toolset: run.toolset } : {}),
+          ...(run.shippedScript === undefined ? {} : { shippedScript: run.shippedScript }),
           ...(run.frozenExcludeTools ? { excludeTools: [...run.frozenExcludeTools] } : {}),
         },
         controller: new AbortController(),
         generations: new Map(),
+        callTiers: new Map(Object.entries(run.callTiers ?? {})),
         agentWaiters: new Map(),
+        bufferedTerminals: new Map(),
         pendingSpawns: new Map(),
         pendingJournal: new Set(),
         lifecycleSuspended: false,
@@ -1374,6 +1806,7 @@ export class WorkflowEngine {
       startedAt: run.startedAt,
       updatedAt: run.updatedAt,
       ...(run.error ? { error: run.error.slice(0, 2_000) } : {}),
+      ...(run.finalResult !== undefined ? { resultPreview: renderWorkflowValue(run.finalResult).slice(0, 8_000) } : {}),
     };
     if (!detailed) return base;
     const calls = Object.entries(run.callStatus)
@@ -1398,6 +1831,13 @@ function hashScript(script: string): string {
   return createHash("sha256").update(script).digest("hex");
 }
 
+export class WorkflowEngineDisposedError extends Error {
+  constructor() {
+    super("Workflow engine is disposed");
+    this.name = "WorkflowEngineDisposedError";
+  }
+}
+
 export class WorkflowWaitAbortedError extends Error {
   constructor() {
     super("workflow wait aborted");