@bastani/atomic 0.8.26-alpha.4 → 0.8.26-alpha.6

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

@@ -7,11 +7,24 @@
  */
 
 import type { Store } from "./store.js";
-import type { RunSnapshot, StageSnapshot, StageStatus, WorkflowChildReplaySnapshot } from "./store-types.js";
+import type {
+  RunSnapshot,
+  StageSnapshot,
+  StageStatus,
+  WorkflowChildReplaySnapshot,
+  WorkflowFailureCode,
+  WorkflowFailureDisposition,
+  WorkflowFailureKind,
+} from "./store-types.js";
 import type { WorkflowInputValues, WorkflowOutputValues } from "./types.js";
 import { workflowSerializableObjectSchema } from "./serializable.js";
 import { Value } from "typebox/value";
-import { isWorkflowFailureKind } from "./workflow-failures.js";
+import {
+  isWorkflowFailureCode,
+  isWorkflowFailureDisposition,
+  isWorkflowFailureKind,
+  isWorkflowFailureRecoverability,
+} from "./workflow-failures.js";
 
 // ---------------------------------------------------------------------------
 // Config option
@@ -49,6 +62,19 @@ export interface InFlightRun {
   readonly stageIds: readonly string[];
 }
 
+interface RestoredRunBlockedMetadata {
+  readonly failedStageId: string;
+  readonly error: string;
+  readonly failureKind: WorkflowFailureKind;
+  readonly failureCode?: WorkflowFailureCode;
+  readonly failureRecoverability: "recoverable";
+  readonly failureDisposition?: WorkflowFailureDisposition;
+  readonly failureMessage?: string;
+  readonly retryAfterMs?: number;
+  readonly resumable: true;
+  readonly ts: number;
+}
+
 // ---------------------------------------------------------------------------
 // Scan logic
 // ---------------------------------------------------------------------------
@@ -170,7 +196,37 @@ export function restoreOnSessionStart(
 
   for (const run of inFlight) {
     const runMeta = findRunStartMetadata(sessionEntries, run.runId);
-    const stages = _buildStageSnapshots(sessionEntries, run.runId);
+    const blockedMeta = findRunBlockedMetadata(sessionEntries, run.runId);
+    const stages = _buildStageSnapshots(sessionEntries, run.runId, blockedMeta);
+
+    if (blockedMeta !== undefined) {
+      const runSnapshot: RunSnapshot = {
+        id: run.runId,
+        name: run.name,
+        inputs: run.inputs,
+        status: "running",
+        stages,
+        startedAt: run.startTs,
+        ...(runMeta.parentRunId !== undefined ? { parentRunId: runMeta.parentRunId } : {}),
+        ...(runMeta.parentStageId !== undefined ? { parentStageId: runMeta.parentStageId } : {}),
+        ...(runMeta.rootRunId !== undefined ? { rootRunId: runMeta.rootRunId } : {}),
+        ...(runMeta.resumedFromRunId !== undefined ? { resumedFromRunId: runMeta.resumedFromRunId } : {}),
+        ...(runMeta.resumeFromStageId !== undefined ? { resumeFromStageId: runMeta.resumeFromStageId } : {}),
+      };
+      store.recordRunStart(runSnapshot);
+      store.recordRunBlocked(run.runId, blockedMeta.error, {
+        failureKind: blockedMeta.failureKind,
+        ...(blockedMeta.failureCode !== undefined ? { failureCode: blockedMeta.failureCode } : {}),
+        failureRecoverability: "recoverable",
+        ...(blockedMeta.failureDisposition !== undefined ? { failureDisposition: blockedMeta.failureDisposition } : {}),
+        ...(blockedMeta.failureMessage !== undefined ? { failureMessage: blockedMeta.failureMessage } : {}),
+        failedStageId: blockedMeta.failedStageId,
+        resumable: true,
+        ...(blockedMeta.retryAfterMs !== undefined ? { retryAfterMs: blockedMeta.retryAfterMs } : {}),
+        blockedAt: blockedMeta.ts,
+      });
+      continue;
+    }
 
     if (config.resumeInFlight === "auto") {
       // Re-hydrate the run into the store as "running"
@@ -223,6 +279,7 @@ export function restoreOnSessionStart(
 function _buildStageSnapshots(
   entries: readonly SessionEntry[],
   runId: string,
+  blockedMeta?: RestoredRunBlockedMetadata,
 ): StageSnapshot[] {
   const stageMap = new Map<string, StageSnapshot>();
   const endedStages = new Set<string>();
@@ -256,6 +313,10 @@ function _buildStageSnapshots(
       const summary = entry.payload["summary"];
       const error = entry.payload["error"];
       const failureKind = entry.payload["failureKind"];
+      const failureCode = entry.payload["failureCode"];
+      const failureRecoverability = entry.payload["failureRecoverability"];
+      const failureDisposition = entry.payload["failureDisposition"];
+      const retryAfterMs = entry.payload["retryAfterMs"];
       const failureMessage = entry.payload["failureMessage"];
       const skippedReason = entry.payload["skippedReason"];
       if (typeof stageId !== "string") continue;
@@ -267,6 +328,10 @@ function _buildStageSnapshots(
         if (typeof summary === "string") snap.result = summary;
         if (typeof error === "string") snap.error = error;
         if (typeof failureKind === "string" && isWorkflowFailureKind(failureKind)) snap.failureKind = failureKind;
+        if (typeof failureCode === "string" && isWorkflowFailureCode(failureCode)) snap.failureCode = failureCode;
+        if (typeof failureRecoverability === "string" && isWorkflowFailureRecoverability(failureRecoverability)) snap.failureRecoverability = failureRecoverability;
+        if (typeof failureDisposition === "string" && isWorkflowFailureDisposition(failureDisposition)) snap.failureDisposition = failureDisposition;
+        if (typeof retryAfterMs === "number") snap.retryAfterMs = retryAfterMs;
         if (typeof failureMessage === "string") snap.failureMessage = failureMessage;
         if (typeof skippedReason === "string") snap.skippedReason = skippedReason;
         Object.assign(snap, replayMetadata(entry.payload), workflowChildMetadata(entry.payload));
@@ -274,9 +339,12 @@ function _buildStageSnapshots(
     }
   }
 
-  // Mark any stage that didn't get an end entry as "failed" (crashed)
-  for (const [stageId, snap] of stageMap) {
-    if (!endedStages.has(stageId)) {
+  if (blockedMeta !== undefined) {
+    restoreBlockedStageState(stageMap, endedStages, blockedMeta);
+  } else {
+    // Mark any stage that didn't get an end entry as crashed.
+    for (const [stageId, snap] of stageMap) {
+      if (endedStages.has(stageId)) continue;
       snap.status = "failed";
       snap.error = "Stage did not complete — process was interrupted.";
     }
@@ -285,6 +353,57 @@ function _buildStageSnapshots(
   return [...stageMap.values()];
 }
 
+function hasRestoredAncestor(
+  stageMap: ReadonlyMap<string, StageSnapshot>,
+  stage: StageSnapshot,
+  ancestorId: string,
+): boolean {
+  const queue = [...stage.parentIds];
+  const seen = new Set<string>();
+
+  while (queue.length > 0) {
+    const next = queue.shift();
+    if (next === undefined || seen.has(next)) continue;
+    if (next === ancestorId) return true;
+    seen.add(next);
+    queue.push(...(stageMap.get(next)?.parentIds ?? []));
+  }
+
+  return false;
+}
+
+function markRestoredBlockedFailureStage(
+  snap: StageSnapshot,
+  blockedMeta: RestoredRunBlockedMetadata,
+): void {
+  snap.status = "failed";
+  snap.error = blockedMeta.error;
+  snap.failureKind = blockedMeta.failureKind;
+  snap.failureCode = blockedMeta.failureCode;
+  snap.failureRecoverability = blockedMeta.failureRecoverability;
+  snap.failureDisposition = blockedMeta.failureDisposition;
+  snap.failureMessage = blockedMeta.failureMessage;
+  snap.retryAfterMs = blockedMeta.retryAfterMs;
+}
+
+function restoreBlockedStageState(
+  stageMap: Map<string, StageSnapshot>,
+  endedStages: ReadonlySet<string>,
+  blockedMeta: RestoredRunBlockedMetadata,
+): void {
+  for (const [stageId, snap] of stageMap) {
+    if (endedStages.has(stageId)) continue;
+    if (stageId === blockedMeta.failedStageId) {
+      markRestoredBlockedFailureStage(snap, blockedMeta);
+      continue;
+    }
+    if (hasRestoredAncestor(stageMap, snap, blockedMeta.failedStageId)) {
+      snap.status = "blocked";
+      snap.blockedByStageId = blockedMeta.failedStageId;
+    }
+  }
+}
+
 function replayMetadata(payload: Record<string, unknown>): Pick<StageSnapshot, "replayKey" | "replayedFromStageId" | "replayed"> {
   const replayKey = payload["replayKey"];
   const replayedFromStageId = payload["replayedFromStageId"];
@@ -361,12 +480,61 @@ function restoreStageStatus(status: unknown): StageStatus {
     case "completed":
     case "failed":
     case "skipped":
+    case "blocked":
       return status;
     default:
       return "failed";
   }
 }
 
+function numericRetryAfterMs(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+
+function findRunBlockedMetadata(
+  entries: readonly SessionEntry[],
+  runId: string,
+): RestoredRunBlockedMetadata | undefined {
+  let latest: RestoredRunBlockedMetadata | undefined;
+  for (const entry of entries) {
+    if (entry.type !== "workflow.run.blocked" || entry.payload["runId"] !== runId) continue;
+    const failedStageId = entry.payload["failedStageId"];
+    const error = entry.payload["error"];
+    const failureKind = entry.payload["failureKind"];
+    const failureCode = entry.payload["failureCode"];
+    const failureRecoverability = entry.payload["failureRecoverability"];
+    const failureDisposition = entry.payload["failureDisposition"];
+    const failureMessage = entry.payload["failureMessage"];
+    const retryAfterMs = numericRetryAfterMs(entry.payload["retryAfterMs"]);
+    const resumable = entry.payload["resumable"];
+    const ts = entry.payload["ts"];
+    if (
+      typeof failedStageId !== "string" ||
+      typeof error !== "string" ||
+      typeof failureKind !== "string" ||
+      !isWorkflowFailureKind(failureKind) ||
+      failureRecoverability !== "recoverable" ||
+      resumable !== true ||
+      typeof ts !== "number"
+    ) {
+      continue;
+    }
+    latest = {
+      failedStageId,
+      error,
+      failureKind,
+      ...(typeof failureCode === "string" && isWorkflowFailureCode(failureCode) ? { failureCode } : {}),
+      failureRecoverability: "recoverable",
+      ...(typeof failureDisposition === "string" && isWorkflowFailureDisposition(failureDisposition) ? { failureDisposition } : {}),
+      ...(typeof failureMessage === "string" ? { failureMessage } : {}),
+      ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+      resumable: true,
+      ts,
+    };
+  }
+  return latest;
+}
+
 function restoreTerminalRuns(entries: readonly SessionEntry[], store: Store): void {
   const started = new Map<string, { readonly name: string; readonly inputs: Readonly<WorkflowInputValues>; readonly startTs: number }>();
   const ended = new Map<string, Record<string, unknown>>();
@@ -416,6 +584,10 @@ function restoreTerminalRuns(entries: readonly SessionEntry[], store: Store): vo
 
     const error = end["error"];
     const failureKind = end["failureKind"];
+    const failureCode = end["failureCode"];
+    const failureRecoverability = end["failureRecoverability"];
+    const failureDisposition = end["failureDisposition"];
+    const retryAfterMs = numericRetryAfterMs(end["retryAfterMs"]);
     const failureMessage = end["failureMessage"];
     const failedStageId = end["failedStageId"];
     const resumable = end["resumable"];
@@ -426,6 +598,10 @@ function restoreTerminalRuns(entries: readonly SessionEntry[], store: Store): vo
       typeof error === "string" ? error : undefined,
       {
         ...(typeof failureKind === "string" && isWorkflowFailureKind(failureKind) ? { failureKind } : {}),
+        ...(typeof failureCode === "string" && isWorkflowFailureCode(failureCode) ? { failureCode } : {}),
+        ...(typeof failureRecoverability === "string" && isWorkflowFailureRecoverability(failureRecoverability) ? { failureRecoverability } : {}),
+        ...(typeof failureDisposition === "string" && isWorkflowFailureDisposition(failureDisposition) ? { failureDisposition } : {}),
+        ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
         ...(typeof failureMessage === "string" ? { failureMessage } : {}),
         ...(typeof failedStageId === "string" ? { failedStageId } : {}),
         ...(typeof resumable === "boolean" ? { resumable } : {}),

package/dist/builtin/workflows/src/shared/persistence-session-entries.ts

@@ -7,6 +7,11 @@
  */
 
 import type { WorkflowInputValues, WorkflowOutputValues } from "./types.js";
+import type {
+  WorkflowFailureCode,
+  WorkflowFailureDisposition,
+  WorkflowFailureKind,
+} from "./store-types.js";
 
 // ---------------------------------------------------------------------------
 // Structural API type (subset of ExtensionAPI needed here)
@@ -76,7 +81,11 @@ export interface StageEndPayload {
   readonly summary?: string;
   readonly error?: string;
   readonly failureKind?: string;
+  readonly failureCode?: string;
+  readonly failureRecoverability?: string;
+  readonly failureDisposition?: string;
   readonly failureMessage?: string;
+  readonly retryAfterMs?: number;
   readonly skippedReason?: string;
   readonly replayKey?: string;
   readonly replayedFromStageId?: string;
@@ -90,9 +99,27 @@ export interface RunEndPayload {
   readonly result?: WorkflowOutputValues;
   readonly error?: string;
   readonly failureKind?: string;
+  readonly failureCode?: string;
+  readonly failureRecoverability?: string;
+  readonly failureDisposition?: string;
   readonly failureMessage?: string;
   readonly failedStageId?: string;
   readonly resumable?: boolean;
+  readonly retryAfterMs?: number;
+  readonly ts: number;
+}
+
+export interface RunBlockedPayload {
+  readonly runId: string;
+  readonly failedStageId: string;
+  readonly error: string;
+  readonly failureKind: WorkflowFailureKind;
+  readonly failureCode?: WorkflowFailureCode;
+  readonly failureMessage?: string;
+  readonly failureRecoverability: "recoverable";
+  readonly failureDisposition?: WorkflowFailureDisposition;
+  readonly retryAfterMs?: number;
+  readonly resumable: true;
   readonly ts: number;
 }
 
@@ -165,7 +192,11 @@ export function appendStageEnd(
     ...(payload.summary !== undefined ? { summary: payload.summary } : {}),
     ...(payload.error !== undefined ? { error: payload.error } : {}),
     ...(payload.failureKind !== undefined ? { failureKind: payload.failureKind } : {}),
+    ...(payload.failureCode !== undefined ? { failureCode: payload.failureCode } : {}),
+    ...(payload.failureRecoverability !== undefined ? { failureRecoverability: payload.failureRecoverability } : {}),
+    ...(payload.failureDisposition !== undefined ? { failureDisposition: payload.failureDisposition } : {}),
     ...(payload.failureMessage !== undefined ? { failureMessage: payload.failureMessage } : {}),
+    ...(payload.retryAfterMs !== undefined ? { retryAfterMs: payload.retryAfterMs } : {}),
     ...(payload.skippedReason !== undefined ? { skippedReason: payload.skippedReason } : {}),
     ...(payload.replayKey !== undefined ? { replayKey: payload.replayKey } : {}),
     ...(payload.replayedFromStageId !== undefined ? { replayedFromStageId: payload.replayedFromStageId } : {}),
@@ -180,18 +211,57 @@ export function appendStageEnd(
   }
 }
 
+function sanitizeTerminalRunEndPayload(payload: RunEndPayload): RunEndPayload {
+  if (payload.status === "killed") {
+    return {
+      ...payload,
+      failureRecoverability: "non_recoverable",
+      failureDisposition: "terminal_killed",
+      resumable: false,
+    };
+  }
+
+  if (payload.failureDisposition !== "active_blocked") return payload;
+  const sanitized = { ...payload };
+  delete (sanitized as { failureDisposition?: string }).failureDisposition;
+  return sanitized;
+}
+
 /** Appends a `workflow.run.end` entry. */
 export function appendRunEnd(api: PersistenceAPI, payload: RunEndPayload): void {
   if (typeof api.appendEntry !== "function") return;
+  const terminalPayload = sanitizeTerminalRunEndPayload(payload);
   api.appendEntry("workflow.run.end", {
+    runId: terminalPayload.runId,
+    status: terminalPayload.status,
+    ...(terminalPayload.result !== undefined ? { result: terminalPayload.result } : {}),
+    ...(terminalPayload.error !== undefined ? { error: terminalPayload.error } : {}),
+    ...(terminalPayload.failureKind !== undefined ? { failureKind: terminalPayload.failureKind } : {}),
+    ...(terminalPayload.failureCode !== undefined ? { failureCode: terminalPayload.failureCode } : {}),
+    ...(terminalPayload.failureRecoverability !== undefined ? { failureRecoverability: terminalPayload.failureRecoverability } : {}),
+    ...(terminalPayload.failureDisposition !== undefined ? { failureDisposition: terminalPayload.failureDisposition } : {}),
+    ...(terminalPayload.failureMessage !== undefined ? { failureMessage: terminalPayload.failureMessage } : {}),
+    ...(terminalPayload.failedStageId !== undefined ? { failedStageId: terminalPayload.failedStageId } : {}),
+    ...(terminalPayload.resumable !== undefined ? { resumable: terminalPayload.resumable } : {}),
+    ...(terminalPayload.retryAfterMs !== undefined ? { retryAfterMs: terminalPayload.retryAfterMs } : {}),
+    ts: terminalPayload.ts,
+  });
+}
+
+/** Appends a `workflow.run.blocked` entry for active recoverable failures. */
+export function appendRunBlocked(api: PersistenceAPI, payload: RunBlockedPayload): void {
+  if (typeof api.appendEntry !== "function") return;
+  api.appendEntry("workflow.run.blocked", {
     runId: payload.runId,
-    status: payload.status,
-    ...(payload.result !== undefined ? { result: payload.result } : {}),
-    ...(payload.error !== undefined ? { error: payload.error } : {}),
-    ...(payload.failureKind !== undefined ? { failureKind: payload.failureKind } : {}),
+    failedStageId: payload.failedStageId,
+    error: payload.error,
+    failureKind: payload.failureKind,
+    ...(payload.failureCode !== undefined ? { failureCode: payload.failureCode } : {}),
     ...(payload.failureMessage !== undefined ? { failureMessage: payload.failureMessage } : {}),
-    ...(payload.failedStageId !== undefined ? { failedStageId: payload.failedStageId } : {}),
-    ...(payload.resumable !== undefined ? { resumable: payload.resumable } : {}),
+    failureRecoverability: payload.failureRecoverability,
+    ...(payload.failureDisposition !== undefined ? { failureDisposition: payload.failureDisposition } : {}),
+    ...(payload.retryAfterMs !== undefined ? { retryAfterMs: payload.retryAfterMs } : {}),
+    resumable: payload.resumable,
     ts: payload.ts,
   });
 }

package/dist/builtin/workflows/src/shared/stage-prompt.ts

@@ -239,13 +239,41 @@ export function parseAskUserQuestionArgs(
   return questions.length > 0 ? questions : undefined;
 }
 
+/**
+ * Sentinel label for the chat escape hatch. Matches the `ROW_INTENT_META.chat.label`
+ * in the coding-agent package. Duplicated here as a literal to avoid a cross-package
+ * import; the reserved-label guard in validate-questionnaire already prevents an
+ * authored option from using this label.
+ */
+const CHAT_ABOUT_THIS_LABEL = "Chat about this";
+const CHAT_ABOUT_THIS_NORMALIZED = normalizeLabel(CHAT_ABOUT_THIS_LABEL);
+
+function isChatSentinel(value: string): boolean {
+  return normalizeLabel(value) === CHAT_ABOUT_THIS_NORMALIZED;
+}
+
+function answerChat(question: StageInputQuestion): BuiltAnswer {
+  return {
+    questionIndex: 0,
+    question: question.question,
+    kind: "chat",
+    answer: CHAT_ABOUT_THIS_LABEL,
+  };
+}
+
 /**
  * Resolve a desired answer string against a single-select question's options.
- * Matches a case-insensitive option label, then a 1-based option index, then
- * falls back to a typed ("custom") answer.
+ * Checks the chat sentinel first (case/whitespace insensitive), then matches a
+ * case-insensitive option label, then a 1-based option index, then falls back to
+ * a typed ("custom") answer.
  */
 function answerSingle(question: StageInputQuestion, desired: string): BuiltAnswer {
   const normalized = normalizeLabel(desired);
+  // Chat sentinel takes priority over authored options — the label is reserved so
+  // no option can legitimately match it.
+  if (isChatSentinel(desired)) {
+    return answerChat(question);
+  }
   const byLabel = question.options.find((option) => normalizeLabel(option.label) === normalized);
   if (byLabel) {
     return { questionIndex: 0, question: question.question, kind: "option", answer: byLabel.label };
@@ -295,6 +323,9 @@ function buildResult(
       answer.optionLabels !== undefined
         ? answer.optionLabels
         : (answer.text ?? "").split(",").map((part) => part.trim()).filter((part) => part.length > 0);
+    if (candidates.some(isChatSentinel)) {
+      return { answers: [answerChat(question)], cancelled: false } satisfies BuiltResult;
+    }
     return { answers: [answerMulti(question, candidates)], cancelled: false } satisfies BuiltResult;
   }
 

package/dist/builtin/workflows/src/shared/store-types.ts

@@ -17,6 +17,19 @@ export type StageStatus =
   | "skipped";
 
 export type WorkflowFailureKind = "auth" | "rate_limit" | "provider" | "cancelled" | "unknown";
+export type WorkflowFailureRecoverability = "recoverable" | "non_recoverable" | "unknown";
+export type WorkflowFailureDisposition = "active_blocked" | "terminal_killed" | "terminal_failed";
+export type WorkflowFailureCode =
+  | "login_required"
+  | "missing_api_key"
+  | "invalid_api_key"
+  | "forbidden_config"
+  | "unknown_model"
+  | "rate_limited"
+  | "quota_limited"
+  | "provider_unavailable"
+  | "cancelled"
+  | "unknown";
 
 /**
  * Human-in-the-loop prompt kind. Mirrors the four `WorkflowUIContext` methods.
@@ -127,6 +140,14 @@ export interface StageSnapshot {
   error?: string;
   /** Structured workflow failure category for failed stages. */
   failureKind?: WorkflowFailureKind;
+  /** Specific additive workflow failure code within `failureKind`. */
+  failureCode?: WorkflowFailureCode;
+  /** Whether retry/resume can recover this failed stage without a workflow rerun. */
+  failureRecoverability?: WorkflowFailureRecoverability;
+  /** Executor lifecycle disposition chosen for the failed stage. */
+  failureDisposition?: WorkflowFailureDisposition;
+  /** Optional provider retry hint in milliseconds. Informational; blocked stages resume only via explicit user action. */
+  retryAfterMs?: number;
   /** Original unsanitized error text when different from `error`. */
   failureMessage?: string;
   /** Reason for stages skipped by fail-fast/cascade handling. */
@@ -218,6 +239,16 @@ export interface RunSnapshot {
   error?: string;
   /** Structured workflow failure category for failed runs. */
   failureKind?: WorkflowFailureKind;
+  /** Specific additive workflow failure code within `failureKind`. */
+  failureCode?: WorkflowFailureCode;
+  /** Whether retry/resume can recover this run without a workflow rerun. */
+  failureRecoverability?: WorkflowFailureRecoverability;
+  /** Executor lifecycle disposition chosen for this failure. */
+  failureDisposition?: WorkflowFailureDisposition;
+  /** Optional provider retry hint in milliseconds. Informational; blocked runs resume only via explicit user action. */
+  retryAfterMs?: number;
+  /** Timestamp when an active run was blocked by a recoverable workflow failure. */
+  blockedAt?: number;
   /** Original unsanitized error text when different from `error`. */
   failureMessage?: string;
   failedStageId?: string;

package/dist/builtin/workflows/src/shared/store.ts

@@ -16,6 +16,9 @@ import type {
   RunStatus,
   StageStatus,
   WorkflowFailureKind,
+  WorkflowFailureCode,
+  WorkflowFailureRecoverability,
+  WorkflowFailureDisposition,
   WorkflowNotice,
   WorkflowChildRunRef,
 } from "./store-types.js";
@@ -43,9 +46,55 @@ function cannotPause(status: StageStatus): boolean {
 
 export interface RunEndMetadata {
   readonly failureKind?: WorkflowFailureKind;
+  readonly failureCode?: WorkflowFailureCode;
+  readonly failureRecoverability?: WorkflowFailureRecoverability;
+  readonly failureDisposition?: WorkflowFailureDisposition;
   readonly failureMessage?: string;
   readonly failedStageId?: string;
   readonly resumable?: boolean;
+  readonly retryAfterMs?: number;
+}
+
+export interface RunBlockedMetadata extends RunEndMetadata {
+  readonly failureRecoverability: "recoverable";
+  readonly failedStageId: string;
+  readonly resumable: true;
+  readonly blockedAt?: number;
+}
+
+function clearRunFailureMetadata(run: RunSnapshot): void {
+  delete run.error;
+  delete run.failureKind;
+  delete run.failureCode;
+  delete run.failureRecoverability;
+  delete run.failureDisposition;
+  delete run.failureMessage;
+  delete run.failedStageId;
+  delete run.resumable;
+  delete run.retryAfterMs;
+  delete run.blockedAt;
+}
+
+function clearStaleBlockedRunMetadata(run: RunSnapshot, metadata: RunEndMetadata | undefined): void {
+  if (metadata?.failureKind === undefined) delete run.failureKind;
+  if (metadata?.failureCode === undefined) delete run.failureCode;
+  if (metadata?.failureRecoverability === undefined) delete run.failureRecoverability;
+  if (metadata?.failureDisposition === undefined) delete run.failureDisposition;
+  if (metadata?.failureMessage === undefined) delete run.failureMessage;
+  if (metadata?.failedStageId === undefined) delete run.failedStageId;
+  if (metadata?.resumable === undefined) delete run.resumable;
+  if (metadata?.retryAfterMs === undefined) delete run.retryAfterMs;
+}
+
+function applyRunEndMetadata(run: RunSnapshot, metadata: RunEndMetadata): void {
+  if (metadata.failureKind !== undefined) run.failureKind = metadata.failureKind;
+  if (metadata.failureCode !== undefined) run.failureCode = metadata.failureCode;
+  if (metadata.failureRecoverability !== undefined) run.failureRecoverability = metadata.failureRecoverability;
+  if (metadata.failureDisposition !== undefined) run.failureDisposition = metadata.failureDisposition;
+  if (metadata.retryAfterMs !== undefined) run.retryAfterMs = metadata.retryAfterMs;
+  if (metadata.failureMessage !== undefined) run.failureMessage = metadata.failureMessage;
+  if (metadata.failedStageId !== undefined) run.failedStageId = metadata.failedStageId;
+  if (metadata.resumable !== undefined) run.resumable = metadata.resumable;
 }
 
 export type StagePromptAnswerSource = "workflow_ui" | "workflow_tool";
@@ -95,6 +144,12 @@ export interface Store {
     error?: string,
     metadata?: RunEndMetadata,
   ): boolean;
+  /**
+   * Record an active, recoverable workflow failure without ending the run.
+   * The run remains resumable/running and carries failure metadata for status,
+   * persistence restore, and continuation decisions.
+   */
+  recordRunBlocked(runId: string, error: string, metadata: RunBlockedMetadata): boolean;
   /**
    * Remove a run from live workflow history/status. Any pending HIL prompt
    * waiter is rejected because the workflow will not resume through that path.
@@ -448,6 +503,10 @@ export function createStore(): Store {
       existing.result = stage.result;
       existing.error = stage.error;
       existing.failureKind = stage.failureKind;
+      existing.failureCode = stage.failureCode;
+      existing.failureRecoverability = stage.failureRecoverability;
+      existing.failureDisposition = stage.failureDisposition;
+      existing.retryAfterMs = stage.retryAfterMs;
       existing.failureMessage = stage.failureMessage;
       existing.skippedReason = stage.skippedReason;
       if (stage.replayKey !== undefined) existing.replayKey = stage.replayKey;
@@ -485,17 +544,26 @@ export function createStore(): Store {
         run.pausedAt = undefined;
       }
       run.durationMs = elapsedRunMs(run, run.endedAt);
-      if (status === "completed" && result !== undefined) {
-        run.result = result;
-      }
-      if ((status === "failed" || status === "killed") && error !== undefined) {
-        run.error = error;
-      }
-      if (metadata !== undefined) {
-        if (metadata.failureKind !== undefined) run.failureKind = metadata.failureKind;
-        if (metadata.failureMessage !== undefined) run.failureMessage = metadata.failureMessage;
-        if (metadata.failedStageId !== undefined) run.failedStageId = metadata.failedStageId;
-        if (metadata.resumable !== undefined) run.resumable = metadata.resumable;
+      const wasBlocked = run.blockedAt !== undefined || run.failureDisposition === "active_blocked";
+      delete run.blockedAt;
+      if (status === "completed") {
+        if (result !== undefined) {
+          run.result = result;
+        }
+        clearRunFailureMetadata(run);
+      } else {
+        if (wasBlocked && error === undefined) delete run.error;
+        if ((status === "failed" || status === "killed") && error !== undefined) {
+          run.error = error;
+        }
+        if (wasBlocked) clearStaleBlockedRunMetadata(run, metadata);
+        if (metadata !== undefined) applyRunEndMetadata(run, metadata);
+        if (run.failureDisposition === "active_blocked") delete run.failureDisposition;
+        if (status === "killed") {
+          run.failureRecoverability = "non_recoverable";
+          run.failureDisposition = "terminal_killed";
+          run.resumable = false;
+        }
       }
       // Abandon any waiting HIL prompt — workflow body never resumed past
       // it, but the awaiter promise must reject so the executor's catch
@@ -511,6 +579,26 @@ export function createStore(): Store {
       return true;
     },
 
+    recordRunBlocked(runId: string, error: string, metadata: RunBlockedMetadata): boolean {
+      const run = findRun(runId);
+      if (!run) return false;
+      if (TERMINAL_STATUSES.has(run.status)) return false;
+      run.status = "running";
+      run.error = error;
+      run.failureKind = metadata.failureKind;
+      run.failureCode = metadata.failureCode;
+      run.failureRecoverability = metadata.failureRecoverability;
+      run.failureDisposition = metadata.failureDisposition;
+      run.failureMessage = metadata.failureMessage;
+      run.failedStageId = metadata.failedStageId;
+      run.resumable = metadata.resumable;
+      run.blockedAt = metadata.blockedAt ?? Date.now();
+      if (metadata.retryAfterMs !== undefined) run.retryAfterMs = metadata.retryAfterMs;
+      _version++;
+      notify();
+      return true;
+    },
+
     removeRun(runId: string): boolean {
       const index = _runs.findIndex((r) => r.id === runId);
       if (index < 0) return false;