@bastani/atomic 0.9.5-alpha.6 → 0.9.5-alpha.8

package/dist/builtin/workflows/src/durable/stage-primitive.ts

@@ -1,6 +1,6 @@
 /** Durable `ctx.stage` / `ctx.task` replay and checkpoint helpers. */
 
-import type { StageContext, StageOptions, WorkflowTaskOptions, WorkflowTaskResult } from "../shared/types.js";
+import type { StageContext, StageOptions, WorkflowChildResult, WorkflowOutputValues, WorkflowTaskOptions, WorkflowTaskResult } from "../shared/types.js";
 import type { StageSnapshot } from "../shared/store-types.js";
 import type { WorkflowSerializableValue } from "../shared/types.js";
 import type { DurableWorkflowBackend } from "./backend.js";
@@ -8,6 +8,7 @@ import type { ParallelFailFastScope } from "../runs/foreground/executor-types.js
 import { durableHash } from "./backend.js";
 import { recordCheckpointDurably } from "./tool-primitive.js";
 import type { DurableStageCheckpoint } from "./types.js";
+export type DurableCompletedStageCheckpoint = DurableStageCheckpoint & { readonly output: WorkflowSerializableValue };
 
 export interface DurableStageDeps {
   readonly workflowId: string;
@@ -20,16 +21,28 @@ export interface DurableStageDeps {
 export async function recordStageCheckpoint(deps: DurableStageDeps, stage: StageSnapshot): Promise<boolean> {
   if (stage.status !== "completed") return false;
   const replayKey = deps.replayKeyForCompletedStage?.(stage) ?? stage.replayKey ?? deps.nextReplayKey(stage.name);
-  if (deps.backend.getStageOutput(deps.workflowId, replayKey) !== undefined) return false;
-  const checkpoint: DurableStageCheckpoint = {
-    kind: "stage",
-    workflowId: deps.workflowId,
-    checkpointId: stableCheckpointId("stage", replayKey),
-    name: stage.name,
-    replayKey,
-    output: stageOutput(stage),
-    completedAt: stage.endedAt ?? Date.now(),
-  };
+  const metadata = checkpointMetadata(stage);
+  const hasExistingOutput = deps.backend.getStageOutput(deps.workflowId, replayKey) !== undefined;
+  const checkpoint: DurableStageCheckpoint = hasExistingOutput
+    ? {
+        kind: "stage",
+        workflowId: deps.workflowId,
+        checkpointId: stageMetadataCheckpointId(replayKey, stage),
+        name: stage.name,
+        replayKey,
+        completedAt: stage.endedAt ?? Date.now(),
+        ...metadata,
+      }
+    : {
+        kind: "stage",
+        workflowId: deps.workflowId,
+        checkpointId: stableCheckpointId("stage", replayKey),
+        name: stage.name,
+        replayKey,
+        output: stageOutput(stage),
+        completedAt: stage.endedAt ?? Date.now(),
+        ...metadata,
+      };
   await recordCheckpointDurably(deps.backend, checkpoint);
   return true;
 }
@@ -79,14 +92,14 @@ export function createDurableStagePrimitive(input: {
   readonly backend: DurableWorkflowBackend;
   readonly nextReplayKey: (stageName: string) => string;
   readonly stage: (name: string, options: StageOptions | undefined, replayKey: string) => StageContext;
-  readonly recordCachedStage?: (name: string, replayKey: string, output: WorkflowSerializableValue) => void;
+  readonly recordCachedStage?: (name: string, replayKey: string, checkpoint: DurableCompletedStageCheckpoint) => void;
 }): (name: string, options?: StageOptions) => StageContext {
   return (name: string, options?: StageOptions): StageContext => {
     const replayKey = input.nextReplayKey(name);
-    const cached = input.backend.getStageOutput(input.workflowId, replayKey);
+    const cached = stageCheckpointWithOutput(input.backend, input.workflowId, replayKey);
     if (cached !== undefined) {
       input.recordCachedStage?.(name, replayKey, cached);
-      return createCachedStageContext(name, cached);
+      return createCachedStageContext(name, cached.output, cached.result);
     }
     const session = input.backend.getStageSession(input.workflowId, replayKey);
     const isMidSessionResume = session?.sessionFile !== undefined;
@@ -112,14 +125,14 @@ export function createDurableTaskPrimitive(input: {
   readonly backend: DurableWorkflowBackend;
   readonly nextReplayKey: (stageName: string) => string;
   readonly task: (name: string, options: WorkflowTaskOptions, stageFailFastScope?: ParallelFailFastScope) => Promise<WorkflowTaskResult>;
-  readonly recordCachedTask?: (name: string, replayKey: string, output: WorkflowTaskResult) => void;
+  readonly recordCachedTask?: (name: string, replayKey: string, checkpoint: DurableCompletedStageCheckpoint, stageFailFastScope?: ParallelFailFastScope) => void;
 }): (name: string, options: WorkflowTaskOptions) => Promise<WorkflowTaskResult> {
   return async (name: string, options: WorkflowTaskOptions, stageFailFastScope?: ParallelFailFastScope): Promise<WorkflowTaskResult> => {
     const replayKey = input.nextReplayKey(`task:${name}`);
-    const cached = input.backend.getStageOutput(input.workflowId, replayKey);
-    if (cached !== undefined && isWorkflowTaskResult(cached)) {
-      input.recordCachedTask?.(name, replayKey, cached);
-      return cached;
+    const cached = stageCheckpointWithOutput(input.backend, input.workflowId, replayKey, isWorkflowTaskResult);
+    if (cached !== undefined && isWorkflowTaskResult(cached.output)) {
+      input.recordCachedTask?.(name, replayKey, cached, stageFailFastScope);
+      return cached.output;
     }
     const session = input.backend.getStageSession(input.workflowId, replayKey);
     const taskOptions: WorkflowTaskOptions = {
@@ -136,6 +149,7 @@ export function createDurableTaskPrimitive(input: {
       replayKey,
       output: result,
       completedAt: Date.now(),
+      ...taskCheckpointMetadata(result),
     });
     return result;
   };
@@ -174,8 +188,8 @@ function wrapSchemaStageForDurability(input: {
   return wrapped;
 }
 
-function createCachedStageContext(name: string, output: WorkflowSerializableValue): StageContext {
-  const text = typeof output === "string" ? output : JSON.stringify(output);
+function createCachedStageContext(name: string, output: WorkflowSerializableValue, result?: string): StageContext {
+  const text = result ?? (typeof output === "string" ? output : JSON.stringify(output));
   const unsupported = async (): Promise<never> => { throw new Error(`Stage "${name}" was replayed from a durable checkpoint; live session operations are unavailable.`); };
   const cached = {
     name,
@@ -213,6 +227,82 @@ function stageOutput(stage: StageSnapshot): WorkflowSerializableValue {
   return { status: stage.status, stageId: stage.id };
 }
 
+function checkpointMetadata(stage: StageSnapshot): Partial<DurableStageCheckpoint> {
+  return {
+    ...(stage.startedAt !== undefined ? { startedAt: stage.startedAt } : {}),
+    ...(stage.endedAt !== undefined ? { endedAt: stage.endedAt } : {}),
+    ...(stage.durationMs !== undefined ? { durationMs: stage.durationMs } : {}),
+    ...(stage.result !== undefined ? { result: stage.result } : {}),
+    ...(stage.sessionId !== undefined ? { sessionId: stage.sessionId } : {}),
+    ...(stage.sessionFile !== undefined ? { sessionFile: stage.sessionFile } : {}),
+    ...(stage.model !== undefined ? { model: stage.model } : {}),
+    ...(stage.fastMode !== undefined ? { fastMode: stage.fastMode } : {}),
+    ...(stage.attemptedModels !== undefined ? { attemptedModels: [...stage.attemptedModels] } : {}),
+    ...(stage.modelAttempts !== undefined ? { modelAttempts: [...stage.modelAttempts] } : {}),
+  };
+}
+
+function taskCheckpointMetadata(result: WorkflowTaskResult): Partial<DurableStageCheckpoint> {
+  return {
+    result: result.text,
+    ...(result.sessionId !== undefined ? { sessionId: result.sessionId } : {}),
+    ...(result.sessionFile !== undefined ? { sessionFile: result.sessionFile } : {}),
+    ...(result.model !== undefined ? { model: result.model } : {}),
+    ...(result.fastMode !== undefined ? { fastMode: result.fastMode } : {}),
+    ...(result.attemptedModels !== undefined ? { attemptedModels: [...result.attemptedModels] } : {}),
+    ...(result.modelAttempts !== undefined ? { modelAttempts: [...result.modelAttempts] } : {}),
+  };
+}
+
+export function stageCheckpointWithOutput(
+  backend: DurableWorkflowBackend,
+  workflowId: string,
+  replayKey: string,
+  matchesOutput?: (value: WorkflowSerializableValue) => boolean,
+): DurableCompletedStageCheckpoint | undefined {
+  const checkpoints = backend.listCheckpoints(workflowId)
+    .filter((checkpoint): checkpoint is DurableStageCheckpoint =>
+      checkpoint.kind === "stage" && checkpoint.replayKey === replayKey,
+    );
+  const outputCheckpoints = checkpoints.filter((checkpoint): checkpoint is DurableCompletedStageCheckpoint =>
+    checkpoint.output !== undefined,
+  );
+  const replayValueCheckpoint = matchesOutput === undefined
+    ? outputCheckpoints[0]
+    : outputCheckpoints.find((checkpoint) => matchesOutput(checkpoint.output));
+  if (replayValueCheckpoint === undefined) return undefined;
+  return mergeCheckpointHydrationMetadata(replayValueCheckpoint, checkpoints);
+}
+
+function mergeCheckpointHydrationMetadata(
+  replayValueCheckpoint: DurableCompletedStageCheckpoint,
+  checkpoints: readonly DurableStageCheckpoint[],
+): DurableCompletedStageCheckpoint {
+  if (checkpoints.length === 0) return replayValueCheckpoint;
+  return {
+    ...replayValueCheckpoint,
+    ...(replayValueCheckpoint.startedAt === undefined ? metadataValue(checkpoints, "startedAt") : {}),
+    ...(replayValueCheckpoint.endedAt === undefined ? metadataValue(checkpoints, "endedAt") : {}),
+    ...(replayValueCheckpoint.durationMs === undefined ? metadataValue(checkpoints, "durationMs") : {}),
+    ...(replayValueCheckpoint.result === undefined ? metadataValue(checkpoints, "result") : {}),
+    ...(replayValueCheckpoint.sessionId === undefined ? metadataValue(checkpoints, "sessionId") : {}),
+    ...(replayValueCheckpoint.sessionFile === undefined ? metadataValue(checkpoints, "sessionFile") : {}),
+    ...(replayValueCheckpoint.model === undefined ? metadataValue(checkpoints, "model") : {}),
+    ...(replayValueCheckpoint.fastMode === undefined ? metadataValue(checkpoints, "fastMode") : {}),
+    ...(replayValueCheckpoint.attemptedModels === undefined ? metadataValue(checkpoints, "attemptedModels") : {}),
+    ...(replayValueCheckpoint.modelAttempts === undefined ? metadataValue(checkpoints, "modelAttempts") : {}),
+  };
+}
+
+function metadataValue<K extends keyof DurableStageCheckpoint>(
+  checkpoints: readonly DurableStageCheckpoint[],
+  key: K,
+): Pick<DurableStageCheckpoint, K> | Record<string, never> {
+  const value = checkpoints.find((checkpoint) => checkpoint[key] !== undefined)?.[key];
+  return value === undefined ? {} : { [key]: value } as Pick<DurableStageCheckpoint, K>;
+}
+
+
 export function createStageReplayKeyGenerator(_workflowId: string): (stageName: string, stageId?: string) => string {
   const counts = new Map<string, number>();
   return (stageName: string, _stageId?: string): string => {
@@ -236,6 +326,15 @@ function stageSessionCheckpointId(replayKey: string, stage: StageSnapshot): stri
 export function cachedStageId(runId: string, replayKey: string): string {
   return `durable-${durableHash({ runId, replayKey })}`;
 }
+function stageMetadataCheckpointId(replayKey: string, stage: StageSnapshot): string {
+  return `${stableCheckpointId("stage-meta", replayKey)}:${durableHash({
+    stageId: stage.id,
+    endedAt: stage.endedAt ?? 0,
+    durationMs: stage.durationMs ?? 0,
+    result: stage.result ?? "",
+  })}`;
+}
+
 
 export function recordCachedStageIntoStore(
   store: import("../shared/store.js").Store,
@@ -245,13 +344,24 @@ export function recordCachedStageIntoStore(
   output: WorkflowSerializableValue,
   completedStageReplayKeys: Map<string, string>,
   parentIds?: readonly string[],
+  checkpoint?: DurableCompletedStageCheckpoint,
 ): void {
   const now = Date.now();
   const stageId = cachedStageId(runId, replayKey);
-  const result = typeof output === "string" ? output : JSON.stringify(output);
+  const result = checkpoint?.result ?? (typeof output === "string" ? output : JSON.stringify(output));
+  const endedAt = checkpoint?.endedAt ?? checkpoint?.completedAt ?? now;
+  const workflowChild = isWorkflowChildResult(output) ? workflowChildSnapshotFromResult(output) : undefined;
   const snapshot: StageSnapshot = {
-    id: stageId, name, status: "completed", parentIds: parentIds !== undefined ? Object.freeze([...parentIds]) : [], startedAt: now, endedAt: now, durationMs: 0, result,
+    id: stageId, name, status: "completed", parentIds: parentIds !== undefined ? Object.freeze([...parentIds]) : [],
+    startedAt: checkpoint?.startedAt ?? endedAt, endedAt, durationMs: checkpoint?.durationMs ?? 0, result,
     replayKey, replayed: true, skippedReason: "durable checkpoint replay", toolEvents: [], attachable: false,
+    ...(workflowChild !== undefined ? { workflowChild } : {}),
+    ...(checkpoint?.sessionId !== undefined ? { sessionId: checkpoint.sessionId } : {}),
+    ...(checkpoint?.sessionFile !== undefined ? { sessionFile: checkpoint.sessionFile } : {}),
+    ...(checkpoint?.model !== undefined ? { model: checkpoint.model } : {}),
+    ...(checkpoint?.fastMode !== undefined ? { fastMode: checkpoint.fastMode } : {}),
+    ...(checkpoint?.attemptedModels !== undefined ? { attemptedModels: checkpoint.attemptedModels } : {}),
+    ...(checkpoint?.modelAttempts !== undefined ? { modelAttempts: checkpoint.modelAttempts } : {}),
   };
   store.recordStageStart(runId, snapshot);
   store.recordStageEnd(runId, snapshot);
@@ -269,16 +379,44 @@ export function recordCachedStageWithTracker(
   runId: string,
   name: string,
   replayKey: string,
-  output: WorkflowSerializableValue,
+  checkpoint: DurableCompletedStageCheckpoint,
   completedStageReplayKeys: Map<string, string>,
+  stageFailFastScope?: ParallelFailFastScope,
 ): void {
   const stageId = cachedStageId(runId, replayKey);
-  const parentIds = tracker.onSpawn(stageId, name);
-  recordCachedStageIntoStore(store, runId, name, replayKey, output, completedStageReplayKeys, parentIds);
+  let parentIds = tracker.onSpawn(stageId, name);
+  const scopeParentIds = stageFailFastScope?.parentIds ?? [];
+  if (stageFailFastScope !== undefined) {
+    tracker.replaceParents(stageId, scopeParentIds);
+    parentIds = [...scopeParentIds];
+  }
+  recordCachedStageIntoStore(store, runId, name, replayKey, checkpoint.output, completedStageReplayKeys, parentIds, checkpoint);
   tracker.onSettle(stageId);
 }
-
 function isWorkflowTaskResult(value: WorkflowSerializableValue): value is WorkflowTaskResult {
   if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
   return typeof (value as Record<string, WorkflowSerializableValue>)["text"] === "string";
 }
+
+function isWorkflowChildResult(value: WorkflowSerializableValue): value is WorkflowChildResult<WorkflowOutputValues> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const objectValue = value as Record<string, WorkflowSerializableValue | undefined>;
+  return typeof objectValue["workflow"] === "string"
+    && typeof objectValue["runId"] === "string"
+    && typeof objectValue["status"] === "string"
+    && typeof objectValue["outputs"] === "object"
+    && objectValue["outputs"] !== null
+    && !Array.isArray(objectValue["outputs"]);
+}
+
+function workflowChildSnapshotFromResult(result: WorkflowChildResult<WorkflowOutputValues>): StageSnapshot["workflowChild"] {
+  return {
+    alias: result.workflow,
+    workflow: result.workflow,
+    runId: result.runId,
+    status: result.status,
+    ...(result.exited !== undefined ? { exited: result.exited } : {}),
+    outputs: result.outputs,
+    ...(typeof result.exitReason === "string" ? { exitReason: result.exitReason } : {}),
+  };
+}

package/dist/builtin/workflows/src/durable/types.ts

@@ -9,7 +9,7 @@
  * cross-ref: issue #1498
  */
 
-import type { WorkflowSerializableValue } from "../shared/types.js";
+import type { WorkflowModelAttempt, WorkflowSerializableValue } from "../shared/types.js";
 
 // ---------------------------------------------------------------------------
 // Top-level workflow identity
@@ -113,6 +113,19 @@ export interface DurableStageCheckpoint {
   readonly sessionId?: string;
   readonly sessionFile?: string;
   readonly completedAt: number;
+  /** Original stage start timestamp, when available. */
+  readonly startedAt?: number;
+  /** Original stage end timestamp, when available. */
+  readonly endedAt?: number;
+  /** Original stage duration, when available. */
+  readonly durationMs?: number;
+  /** Display/result text recorded for the completed stage. */
+  readonly result?: string;
+  /** Completed stage/task model metadata used to hydrate replayed snapshots. */
+  readonly model?: string;
+  readonly fastMode?: boolean;
+  readonly attemptedModels?: readonly string[];
+  readonly modelAttempts?: readonly WorkflowModelAttempt[];
 }
 
 export type UiPromptKind = "input" | "confirm" | "select" | "editor" | "custom";

package/dist/builtin/workflows/src/engine/run.ts

@@ -1,11 +1,5 @@
-import type { RunSnapshot } from "../shared/store-types.js";
-import type {
-  WorkflowDefinition,
-  WorkflowInputValues,
-  WorkflowOutputValues,
-  WorkflowRunContext,
-  WorkflowSerializableValue,
-} from "../shared/types.js";
+import type { RunSnapshot, StageSnapshot } from "../shared/store-types.js";
+import type { WorkflowDefinition, WorkflowInputValues, WorkflowOutputValues, WorkflowRunContext } from "../shared/types.js";
 import type { WorkflowFailure } from "../shared/workflow-failures.js";
 import { classifyWorkflowFailure } from "../shared/workflow-failures.js";
 import { store as defaultStore } from "../shared/store.js";
@@ -45,12 +39,12 @@ import { classifyReturnedRunStatus } from "./run-returned-status.js";
 import { createToolPrimitive, createCheckpointIdGenerator } from "../durable/tool-primitive.js";
 import { persistDurableCacheEntry } from "../durable/resume-catalog.js";
 import { createDurableStagePrimitive, createDurableTaskPrimitive, recordStageCheckpoint, createStageReplayKeyGenerator, recordCachedStageWithTracker } from "../durable/stage-primitive.js";
+import type { DurableCompletedStageCheckpoint } from "../durable/stage-primitive.js";
 import { createDurableChildWorkflowPrimitive } from "../durable/child-primitive.js";
 import { ScopedDurableBackend, type DurableScope } from "../durable/scoped-backend.js";
 import { finalizeDurableTerminalStatus } from "./run-durable-finalize.js";
 import { createDurableStageSessionRecorder } from "./run-durable-stage-session.js";
 import type { DurableWorkflowBackend } from "../durable/backend.js";
-import type { StageSnapshot } from "../shared/store-types.js";
 
 function nextEventLoopTurn(): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, 0));
@@ -283,6 +277,8 @@ export async function run<
   });
   const workflowBoundaryReplayCounts = new Map<string, number>();
   const nextWorkflowBoundaryReplayKey = (name: string): string => {
+    const durableScopePrefix = pendingChildDurableScope?.scopePrefix;
+    if (durableScopePrefix !== undefined && durableScopePrefix.startsWith(`workflow:${name}:`)) return durableScopePrefix;
     const next = (workflowBoundaryReplayCounts.get(name) ?? 0) + 1;
     workflowBoundaryReplayCounts.set(name, next);
     return `workflow:${name}:${next}`;
@@ -346,12 +342,13 @@ export async function run<
 
   // Durable ctx.ui wrapper — caches completed user responses so a resumed workflow does not re-ask answered prompts.
   const durableUiDeps = { workflowId: runId, backend: durableBackend, nextCheckpointId: checkpointIdGenerator };
-  const recordCachedStage = (name: string, replayKey: string, output: WorkflowSerializableValue): void =>
-    recordCachedStageWithTracker(activeStore, tracker, runId, name, replayKey, output, completedStageReplayKeys);
+  const recordCachedStage = (name: string, replayKey: string, checkpoint: DurableCompletedStageCheckpoint): void =>
+    recordCachedStageWithTracker(activeStore, tracker, runId, name, replayKey, checkpoint, completedStageReplayKeys);
   const durableTask = createDurableTaskPrimitive({
     workflowId: runId, backend: durableBackend,
     nextReplayKey: (stageName) => stageReplayKeyGenerator(stageName), task: taskRunners.task,
-    recordCachedTask: (name, replayKey, output) => recordCachedStage(name, replayKey, output),
+    recordCachedTask: (name, replayKey, checkpoint, scope) =>
+      recordCachedStageWithTracker(activeStore, tracker, runId, name, replayKey, checkpoint, completedStageReplayKeys, scope),
   });
   const durableWorkflow = createDurableChildWorkflowPrimitive({
     workflowId: runId, rootWorkflowId: opts.parentRun?.rootRunId ?? runId, backend: durableBackend,
@@ -426,7 +423,7 @@ export async function run<
     await durableBackend.flush?.();
     const returned = classifyReturnedRunStatus(result);
     const recorded = activeStore.recordRunEnd(runId, returned.status, result, returned.error, returned.metadata);
-    appendRunEndWhenRecorded(opts.persistence, recorded, { runId, status: returned.status, result, ...(returned.error !== undefined ? { error: returned.error } : {}), ...(returned.metadata ?? {}), ts: Date.now() });
+    appendRunEndWhenRecorded(opts.persistence, recorded, { runId, status: returned.status, result, ...(returned.error !== undefined ? { error: returned.error } : {}), ...(returned.metadata ?? {}), ...(runSnapshot.endedAt !== undefined ? { endedAt: runSnapshot.endedAt } : {}), ...(runSnapshot.durationMs !== undefined ? { durationMs: runSnapshot.durationMs } : {}), ts: Date.now() });
     durableBackend.setWorkflowStatus(runId, returned.status, undefined, returned.metadata?.resumable);
     await durableBackend.flush?.();
     if (opts.persistence && durableBackend.persistent) {
@@ -480,6 +477,8 @@ export async function run<
       ...(metadata.failedStageId !== undefined ? { failedStageId: metadata.failedStageId } : {}),
       resumable: metadata.resumable,
       ...(metadata.retryAfterMs !== undefined ? { retryAfterMs: metadata.retryAfterMs } : {}),
+      ...(runSnapshot.endedAt !== undefined ? { endedAt: runSnapshot.endedAt } : {}),
+      ...(runSnapshot.durationMs !== undefined ? { durationMs: runSnapshot.durationMs } : {}),
       ts: Date.now(),
     });
     return reconcileTerminalRunResult(runId, runSnapshot, activeStore, { status: "failed", error: metadata.errorMessage }, opts.onRunEnd);

package/dist/builtin/workflows/src/extension/workflow-prompts.ts

@@ -25,6 +25,8 @@ export const DEFAULT_PROMPT_GUIDANCE: string[] = [
   - For transcripts, avoid reading whole session transcripts at once. Use \`stages\` or \`stage\` to get \`sessionFile\`/\`transcriptPath\`, quote the exact path without rewriting separators (preserve Windows backslashes), search it with \`rg\`/\`grep\`, and read small relevant ranges; use \`transcript\` with explicit \`tail\` or \`limit\` only for quick recent-context checks.
   - If a user asks to create or edit a workflow, use the create-spec skill when available and ask detailed clarifying questions until you understand its purpose, inputs, stages, handoffs, validation, success criteria, and selected starter pattern. Then read the workflow docs/examples and implement the workflow from the created spec directly as a TypeScript definition. After you implement the workflow, reload it to access it and run it with test inputs to validate it works as intended before presenting it to the user.
     - Tip: when designing workflows, implement it in a way that you pass information from stage to stage by writing it to a file or artifact (either deterministic or model-driven), pass the path with \`reads\`, and explicitly prompt the downstream agent with wording like \`Read the file at <path>...\`; do not inject large \`previous\` payloads or session history into the next prompt unless explicitly requested to.
+    - When designing reviewer-gated workflows, distinguish implementation/review acceptance from post-approval final actions such as PR/MR/review creation, release tagging, deployment, or publication. Prompt reviewers/reducers to approve and stop the implementation loop when implementation and validation criteria are proven and only an explicitly authorized final action remains; carry that remainder as a next action or final-action field instead of another implementation turn.
+    - When authoring workflow, stage, reviewer, or reducer prompts, remember that a model stage sees its local prompt, artifacts, tools, and reads — not the workflow graph's name or surrounding implementation details unless you explicitly provide them. Describe the concrete action, available evidence, and success criteria directly (for example "review the current code delta" or "create/update the review request") instead of asking the model to reason from labels like "the create-PR workflow stage", "this Goal run", or "the Ralph reviewer". Use workflow or stage names only when the name itself is user-visible context or materially affects behavior.
   - Prefer the \`goal\` workflow for small-to-medium non-trivial one-off fixes, debugging, docs/code changes, scoped multi-file edits, or test/fix loops when you can name the work surface, outcome, and validation; prefer the \`ralph\` workflow for larger/riskier work, migrations, new features, broad refactors, multi-package changes, or tasks estimated over ~2K LoC.
     - Adjust \`goal.max_turns\` for Goal runs and \`ralph.max_loops\` for Ralph runs based on task complexity (estimated LoC, risk, validation effort, and number of unique files/areas touched).
     - Define an objective that includes tight scope, concrete and verifiable done criteria, and validation steps; then monitor progress as above instead of doing parallel implementation yourself.`,

package/dist/builtin/workflows/src/runs/foreground/executor-continuation.ts

@@ -68,14 +68,23 @@ export function createContinuationReplayIndex(continuation: RunContinuationOpts
   }
 
   const stagesByReplayIdentity = new Map<string, StageSnapshot[]>();
+  const stagesByDisplayName = new Map<string, StageSnapshot[]>();
   const promptDuplicateCounts = new Map<string, number>();
   for (const stage of continuation.source.stages) {
     const identity = stage.replayKey ?? stage.name;
     const stages = stagesByReplayIdentity.get(identity);
     if (stages === undefined) stagesByReplayIdentity.set(identity, [stage]);
     else stages.push(stage);
-    const duplicateKey = `${identity}\u0001${sortedIdentity(stage.parentIds)}`;
-    promptDuplicateCounts.set(duplicateKey, (promptDuplicateCounts.get(duplicateKey) ?? 0) + 1);
+    const namedStages = stagesByDisplayName.get(stage.name);
+    if (namedStages === undefined) stagesByDisplayName.set(stage.name, [stage]);
+    else namedStages.push(stage);
+    const duplicateKeys = [
+      `${identity}\u0001${sortedIdentity(stage.parentIds)}`,
+      ...(identity === stage.name ? [] : [`${stage.name}\u0001${sortedIdentity(stage.parentIds)}`]),
+    ];
+    for (const duplicateKey of duplicateKeys) {
+      promptDuplicateCounts.set(duplicateKey, (promptDuplicateCounts.get(duplicateKey) ?? 0) + 1);
+    }
   }
 
   const consumedSourceStageIds = new Set<string>();
@@ -126,7 +135,8 @@ export function createContinuationReplayIndex(continuation: RunContinuationOpts
       let candidates = stagesByReplayIdentity.get(replayKey)?.filter((stage) => !consumedSourceStageIds.has(stage.id)) ?? [];
       if (candidates.length === 0) {
         identity = displayName;
-        candidates = stagesByReplayIdentity.get(displayName)?.filter((stage) => !consumedSourceStageIds.has(stage.id) && stage.replayKey === undefined) ?? [];
+        const namedCandidates = stagesByDisplayName.get(displayName)?.filter((stage) => !consumedSourceStageIds.has(stage.id)) ?? [];
+        candidates = kind === "prompt" ? namedCandidates.filter((stage) => stage.replayKey === undefined) : namedCandidates;
       }
       if (candidates.length === 0) return { kind: "execute", parentIds, answerReplay: "unavailable" };
 

package/dist/builtin/workflows/src/runs/foreground/executor-stage-factory.ts

@@ -54,7 +54,7 @@ export function createWorkflowStageFactory(input: {
       input.tracker.replaceParents(stageId, scopedParentIds);
     }
 
-    const replayKey = `stage:${name}`;
+    const replayKey = options?.durableReplayKey ?? `stage:${name}`;
     const replayDecision = input.replayIndex.decide({
       displayName: name,
       replayKey,

package/dist/builtin/workflows/src/runs/foreground/stage-runner-controller.ts

@@ -6,6 +6,7 @@ import { missingAdapter, stripWorkflowOnlyOptions, unavailableSync } from "./sta
 import { asAgentSession, disposeStageSession, normalizeSessionCreateResult } from "./stage-runner-session.js";
 import { structuredOutputToolErrorFromEvent } from "./stage-runner-structured-output.js";
 import { sendStageUserMessage } from "./stage-runner-send-user-message.js";
+import { nextResumedContextOverflowFallbackIndex, terminatingToolCallId, unresolvedContextOverflowFailure, unresolvedContextOverflowMessage } from "./stage-runner-unresolved-overflow.js";
 import type { AgentSessionConsumer, StageModelFallbackMeta, StageRunnerOpts, StageSessionCreateOptions, StageSessionCreateResult, StageSessionEvent, StageSessionRuntime, WorkflowFastModeSettingsManager } from "./stage-runner-types.js";
 
 type PauseRequest = {
@@ -19,6 +20,7 @@ export class StageSessionController {
   private readonly terminatingToolCallIds = new Set<string>();
   private latestStructuredOutputToolErrorValue: string | undefined;
   private unsubscribeTerminateWatcher: (() => void) | undefined;
+  private unresolvedContextOverflowMessage: string | undefined;
   private disposed = false;
   private pendingThinkingLevel: Parameters<StageContext["setThinkingLevel"]>[0] | undefined;
   private readonly pendingListeners = new Set<(event: StageSessionEvent) => void>();
@@ -325,7 +327,9 @@ export class StageSessionController {
     }
     this.unsubscribeTerminateWatcher?.();
     this.unsubscribeTerminateWatcher = result.session.subscribe((event) => {
-      this.recordTerminatingToolCall(event);
+      const terminatingId = terminatingToolCallId(event);
+      if (terminatingId !== undefined) this.terminatingToolCallIds.add(terminatingId);
+      this.unresolvedContextOverflowMessage = unresolvedContextOverflowMessage(event) ?? this.unresolvedContextOverflowMessage;
       this.latestStructuredOutputToolErrorValue =
         structuredOutputToolErrorFromEvent(event) ?? this.latestStructuredOutputToolErrorValue;
     });
@@ -361,24 +365,29 @@ export class StageSessionController {
         continue;
       }
       const promptStartIndex = activeSession.messages.length;
+      this.unresolvedContextOverflowMessage = undefined;
       try {
         await activeSession.prompt(nextText, sdkOptions);
         const pendingPauseAfterPrompt = this.pauseRequest;
         if (pendingPauseAfterPrompt) {
           const { message } = await pendingPauseAfterPrompt.deferred.promise;
+          this.throwUnresolvedContextOverflowIfPresent();
           nextText = message;
           if (nextText === undefined) return { terminalScanStartIndex: activeSession.messages.length };
           continue;
         }
+        this.throwUnresolvedContextOverflowIfPresent();
         return { terminalScanStartIndex: promptStartIndex };
       } catch (err) {
         const pendingPauseAfterThrow = this.pauseRequest;
         if (pendingPauseAfterThrow) {
           const { message } = await pendingPauseAfterThrow.deferred.promise;
+          this.throwUnresolvedContextOverflowIfPresent();
           nextText = message;
           if (nextText === undefined) return { terminalScanStartIndex: activeSession.messages.length };
           continue;
         }
+        this.throwUnresolvedContextOverflowIfPresent();
         throw err;
       }
     }
@@ -420,10 +429,10 @@ export class StageSessionController {
         this.notifyModelFallbackMetaChange();
         throw err;
       }
-      this.pendingFallbackWarnings.push(`[fallback] resume on ${resumedLabel} failed: ${message}. Restarting fallback from ${this.candidateLabel(candidates[0]!)}.`);
-      await this.disposeCurrentSession();
-      this.activeCandidateIndex = undefined;
-      return false;
+      const resumedOverflowNextIndex = nextResumedContextOverflowFallbackIndex(err, this.activeCandidateIndex, candidates.length);
+      if (resumedOverflowNextIndex === "terminal") { this.modelWarnings.push(...this.pendingFallbackWarnings); this.pendingFallbackWarnings.length = 0; this.notifyModelFallbackMetaChange(); throw err; }
+      this.pendingFallbackWarnings.push(resumedOverflowNextIndex === undefined ? `[fallback] resume on ${resumedLabel} failed: ${message}. Restarting fallback from ${this.candidateLabel(candidates[0]!)}.` : `[fallback] resume on ${resumedLabel} failed: ${message}. Retrying with ${this.candidateLabel(candidates[resumedOverflowNextIndex]!)}.`);
+      await this.disposeCurrentSession(); this.activeCandidateIndex = resumedOverflowNextIndex; return false;
     }
   }
 
@@ -479,22 +488,12 @@ export class StageSessionController {
   private candidateLabel(candidate: WorkflowResolvedModelCandidate): string {
     return candidate.reasoningLevel !== undefined ? `${candidate.id}:${candidate.reasoningLevel}` : candidate.id;
   }
-
   private isWorkflowFastModeEnabled(): boolean | undefined {
     const model = this.session?.model;
     const settingsManager = this.sessionSettingsManager ?? this.effectiveStageOptions?.settingsManager;
-    if (model === undefined || settingsManager === undefined) return undefined;
-    return shouldApplyCodexFastModeForScope(model, settingsManager.getCodexFastModeSettings(), "workflow");
-  }
-
-  private recordTerminatingToolCall(event: unknown): void {
-    if (event === null || typeof event !== "object") return;
-    const record = event as Record<string, unknown>;
-    if (record["type"] !== "tool_execution_end") return;
-    const result = record["result"];
-    if (result === null || typeof result !== "object") return;
-    if ((result as Record<string, unknown>)["terminate"] !== true) return;
-    const callId = record["toolCallId"];
-    if (typeof callId === "string" && callId.length > 0) this.terminatingToolCallIds.add(callId);
+    return model === undefined || settingsManager === undefined
+      ? undefined
+      : shouldApplyCodexFastModeForScope(model, settingsManager.getCodexFastModeSettings(), "workflow");
   }
+  private throwUnresolvedContextOverflowIfPresent(): void { const message = this.unresolvedContextOverflowMessage; this.unresolvedContextOverflowMessage = undefined; if (message !== undefined) throw unresolvedContextOverflowFailure(message); }
 }

package/dist/builtin/workflows/src/runs/foreground/stage-runner-unresolved-overflow.ts

@@ -0,0 +1,38 @@
+import { WorkflowPromptModelFailure } from "./stage-runner-messages.js";
+
+export function unresolvedContextOverflowMessage(event: unknown): string | undefined {
+  if (event === null || typeof event !== "object") return undefined;
+  const record = event as Record<string, unknown>;
+  if (record["type"] !== "compaction_end" || record["unresolvedOverflow"] !== true) return undefined;
+  const message = record["errorMessage"];
+  return typeof message === "string" && message.trim().length > 0
+    ? message
+    : "Context overflow recovery was exhausted for the current model.";
+}
+
+export function unresolvedContextOverflowFailure(message: string): WorkflowPromptModelFailure {
+  return new WorkflowPromptModelFailure({ message, code: "context_length_exceeded", stopReason: "error" });
+}
+
+export function isUnresolvedContextOverflowFailure(error: unknown): boolean {
+  if (!(error instanceof WorkflowPromptModelFailure)) return false;
+  const cause = error.cause;
+  if (cause === null || typeof cause !== "object") return false;
+  return (cause as { readonly code?: unknown }).code === "context_length_exceeded";
+}
+
+export function nextResumedContextOverflowFallbackIndex(error: unknown, currentIndex: number | undefined, candidateCount: number): number | "terminal" | undefined {
+  if (!isUnresolvedContextOverflowFailure(error) || currentIndex === undefined) return undefined;
+  const nextIndex = currentIndex + 1;
+  return nextIndex >= candidateCount ? "terminal" : nextIndex;
+}
+
+export function terminatingToolCallId(event: unknown): string | undefined {
+  if (event === null || typeof event !== "object") return undefined;
+  const record = event as Record<string, unknown>;
+  const result = record["result"];
+  if (record["type"] !== "tool_execution_end" || result === null || typeof result !== "object") return undefined;
+  if ((result as Record<string, unknown>)["terminate"] !== true) return undefined;
+  const callId = record["toolCallId"];
+  return typeof callId === "string" && callId.length > 0 ? callId : undefined;
+}

package/dist/builtin/workflows/src/shared/persistence-restore-helpers.ts

@@ -1,7 +1,7 @@
 import { Value } from "typebox/value";
 import { workflowSerializableObjectSchema } from "./serializable.js";
 import type { Store } from "./store.js";
-import type { SessionEntry } from "./persistence-restore.js";
+import type { NormalizedSessionEntry as SessionEntry } from "./persistence-restore.js";
 import type {
   RunStatus,
   StageSnapshot,
@@ -255,6 +255,14 @@ function numericRetryAfterMs(value: unknown): number | undefined {
   return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
 }
 
+function numericTimestamp(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+
+function numericDuration(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+
 export function findRunBlockedMetadata(
   entries: readonly SessionEntry[],
   runId: string,
@@ -360,6 +368,8 @@ export function restoreTerminalRuns(entries: readonly SessionEntry[], store: Sto
     const retryAfterMs = numericRetryAfterMs(end["retryAfterMs"]);
     const failureMessage = end["failureMessage"];
     const failedStageId = end["failedStageId"];
+    const restoredEndedAt = numericTimestamp(end["endedAt"]);
+    const restoredDurationMs = numericDuration(end["durationMs"]);
     store.recordRunEnd(
       runId,
       status,
@@ -378,6 +388,13 @@ export function restoreTerminalRuns(entries: readonly SessionEntry[], store: Sto
         ...(typeof exitReason === "string" ? { exitReason } : {}),
       },
     );
+    const restoredRun = store.runs().find((run) => run.id === runId);
+    if (restoredRun !== undefined && (restoredEndedAt !== undefined || restoredDurationMs !== undefined)) {
+      Object.assign(restoredRun, {
+        ...(restoredEndedAt !== undefined ? { endedAt: restoredEndedAt } : {}),
+        ...(restoredDurationMs !== undefined ? { durationMs: restoredDurationMs } : {}),
+      });
+    }
   }
 }