@bastani/atomic 0.9.9 → 0.9.10-alpha.1

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

@@ -66,13 +66,22 @@ export function createTrackedStageCaller(input: {
     return false;
   };
 
-  const drainResumeContinuations = async <T>(currentResult: T): Promise<T> => {
+  const drainResumeContinuations = async <T>(currentResult: T): Promise<{
+    readonly result: T;
+    readonly chatAnswerObserved: boolean;
+  }> => {
     let result = currentResult;
-    while (runtime.state.resumeContinuationPending) {
+    let chatAnswerObserved = runtime.state.chatAnswerObservedThisTurn;
+    const captureChatAnswer = (): void => {
+      chatAnswerObserved ||= runtime.state.chatAnswerObservedThisTurn;
+    };
+    while (runtime.state.resumeContinuationPending !== false) {
+      const reason = runtime.state.resumeContinuationPending;
       runtime.state.resumeContinuationPending = false;
+      captureChatAnswer();
       suppressReadinessForCurrentTurn();
       if (!shouldInjectResumeContinuation({
-        resumeOccurred: true,
+        reason,
         gateEnabled: readinessGateEnabled,
         aborted: runtime.signal.aborted,
       })) {
@@ -80,8 +89,10 @@ export function createTrackedStageCaller(input: {
       }
       if (skipResumeContinuationInjection()) continue;
       result = await raceAbort(runtime.innerCtx.prompt(RESUME_CONTINUATION_PROMPT), runtime.signal) as T;
+      captureChatAnswer();
     }
-    return result;
+    captureChatAnswer();
+    return { result, chatAnswerObserved };
   };
 
   return async <T>(call: () => Promise<T>, eagerSessionOrOptions?: boolean | TrackedStageCallOptions): Promise<T> => {
@@ -148,9 +159,16 @@ export function createTrackedStageCaller(input: {
         runtime.state.askUserQuestionObservedThisTurn = false;
         runtime.state.chatAnswerObservedThisTurn = false;
         result = await raceAbort(call(), runtime.signal);
-        result = await drainResumeContinuations(result);
+        const initialDrain = await drainResumeContinuations(result);
+        result = initialDrain.result;
+        let repeatReadinessAfterChatTurn = initialDrain.chatAnswerObserved;
 
-        if (!runtime.signal.aborted && readinessGateEnabled) {
+        if (
+          !runtime.signal.aborted &&
+          readinessGateEnabled &&
+          (runtime.state.askUserQuestionObservedThisTurn || repeatReadinessAfterChatTurn) &&
+          !runtime.innerCtx.__structuredOutputFinalized()
+        ) {
           let resolveNextTurnEnd: (() => void) | null = null;
           const unsubscribeTurnWatcher = runtime.innerCtx.subscribe((event) => {
             if ((event as { type?: unknown }).type === "agent_end" && resolveNextTurnEnd) {
@@ -160,16 +178,24 @@ export function createTrackedStageCaller(input: {
             }
           });
           try {
-            while (runtime.state.askUserQuestionObservedThisTurn) {
-              const decision = runtime.state.chatAnswerObservedThisTurn ? "stay" : await confirmReadiness();
+            while (runtime.state.askUserQuestionObservedThisTurn || repeatReadinessAfterChatTurn) {
+              const decision = await confirmReadiness();
               if (decision === "advance") break;
               if (runtime.signal.aborted) break;
               runtime.state.askUserQuestionObservedThisTurn = false;
               runtime.state.chatAnswerObservedThisTurn = false;
-              await raceAbort(new Promise<void>((resolve) => { resolveNextTurnEnd = resolve; }), runtime.signal);
+              runtime.state.waitingForStageChatTurn = true;
+              try {
+                await raceAbort(new Promise<void>((resolve) => { resolveNextTurnEnd = resolve; }), runtime.signal);
+              } finally {
+                runtime.state.waitingForStageChatTurn = false;
+              }
               if (runtime.signal.aborted) break;
               result = (runtime.innerCtx.__getLastAssistantText() ?? result) as T;
-              result = await drainResumeContinuations(result);
+              const continuationDrain = await drainResumeContinuations(result);
+              result = continuationDrain.result;
+              repeatReadinessAfterChatTurn ||= continuationDrain.chatAnswerObserved;
+              if (runtime.innerCtx.__structuredOutputFinalized()) break;
             }
           } finally {
             resolveNextTurnEnd = null;
@@ -179,6 +205,7 @@ export function createTrackedStageCaller(input: {
       } finally {
         runtime.signal.removeEventListener("abort", abortSession);
       }
+      await runtime.innerCtx.__closeGeneration();
       runtime.captureStageSessionMeta();
       runtime.applyModelFallbackMeta(runtime.innerCtx.__modelFallbackMeta());
       if (trackStageLifecycle && runtime.stageFailFastScope?.failed === true && runtime.stageFailFastScope.activeStages.has(runtime.stageId)) {
@@ -210,13 +237,18 @@ export function createTrackedStageCaller(input: {
       // so the concurrency semaphore is not leaked.
       // cross-ref: issue #1498 — durable finalization failures must not leak the stage limiter.
       runtime.mcpScope.clear();
-      runtime.captureStageSessionMeta();
       let finalizationError: { readonly thrown: true; readonly error: unknown } | undefined;
+      try {
+        await runtime.innerCtx.__closeGeneration();
+        runtime.captureStageSessionMeta();
+      } catch (err) {
+        finalizationError = { thrown: true, error: err };
+      }
       if (trackStageLifecycle) {
         try {
           await runtime.finalizeStageSnapshot();
         } catch (err) {
-          finalizationError = { thrown: true, error: err };
+          finalizationError ??= { thrown: true, error: err };
         }
         try {
           if (runtime.state.stageClosedByWorkflowExit || runtime.exit.currentWorkflowExitAbortReason() !== undefined) {

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

@@ -1,5 +1,6 @@
 import type { StageControlHandle, AgentSessionEventListener } from "./stage-control-registry.js";
 import type { LiveStageRuntime } from "./executor-stage-types.js";
+import type { StageUserMessageDeliveryAction } from "./stage-runner-types.js";
 import { isTerminalStage } from "./executor-scheduler.js";
 import { StageToolExecutionBuffer } from "./stage-tool-execution-buffer.js";
 
@@ -54,21 +55,52 @@ export function createStageControlHandle(runtime: LiveStageRuntime): StageContro
       runtime.throwIfStageMutationBlocked();
       runtime.captureStageSessionMeta();
     },
-    async prompt(text: string) {
+    async sendUserMessage(text, options) {
       runtime.throwIfStageMutationBlocked();
       await ensureMessagingSession();
+      runtime.throwIfStageMutationBlocked();
       try {
-        await runtime.innerCtx.prompt(text);
+        const action = await runtime.innerCtx.__sendUserMessage(
+          text,
+          options,
+          runtime.throwIfStageMutationBlocked,
+        );
+        if (action === "steer" || action === "followUp") {
+          runtime.state.resumeContinuationPending = "queued-user-message";
+        }
+        return action;
       } finally {
         runtime.captureStageSessionMeta();
       }
+    },
+    async prompt(text: string) {
       runtime.throwIfStageMutationBlocked();
+      await ensureMessagingSession();
+      let action: StageUserMessageDeliveryAction | undefined;
+      try {
+        action = await runtime.innerCtx.__sendUserMessage(
+          text,
+          undefined,
+          runtime.throwIfStageMutationBlocked,
+        );
+      } finally {
+        runtime.captureStageSessionMeta();
+      }
+      if (action !== "handled") runtime.throwIfStageMutationBlocked();
     },
     async steer(text: string) {
       runtime.throwIfStageMutationBlocked();
       await ensureMessagingSession();
+      runtime.throwIfStageMutationBlocked();
+      // A user message queued into an in-flight turn should nudge the stage
+      // back to its objective once that turn ends: arm the pending flag so
+      // drainResumeContinuations injects RESUME_CONTINUATION_PROMPT after the
+      // tracked call resolves. Idle deliveries start a fresh user turn and
+      // need no continuation nudge, so only arm while streaming.
+      const queuedIntoInFlightTurn = runtime.innerCtx.isStreaming;
       try {
         await runtime.innerCtx.steer(text);
+        if (queuedIntoInFlightTurn) runtime.state.resumeContinuationPending = "queued-user-message";
       } finally {
         runtime.captureStageSessionMeta();
       }
@@ -76,8 +108,12 @@ export function createStageControlHandle(runtime: LiveStageRuntime): StageContro
     async followUp(text: string) {
       runtime.throwIfStageMutationBlocked();
       await ensureMessagingSession();
+      runtime.throwIfStageMutationBlocked();
+      // Same in-flight continuation arming as steer(): see comment above.
+      const queuedIntoInFlightTurn = runtime.innerCtx.isStreaming;
       try {
         await runtime.innerCtx.followUp(text);
+        if (queuedIntoInFlightTurn) runtime.state.resumeContinuationPending = "queued-user-message";
       } finally {
         runtime.captureStageSessionMeta();
       }
@@ -85,38 +121,53 @@ export function createStageControlHandle(runtime: LiveStageRuntime): StageContro
     async pause() {
       runtime.throwIfStageMutationBlocked();
       const statusBeforePause = runtime.stageSnapshot.status;
+      if (statusBeforePause === "pending" || statusBeforePause === "running" || runtime.innerCtx.isStreaming) {
+        await runtime.innerCtx.__requestPause();
+      }
       const changed = runtime.activeStore.recordStagePaused(runtime.runId, runtime.stageId);
       if (changed) {
         runtime.scheduler.ensureReleaseBarrier(runtime.stageId);
         await runtime.scheduler.cascadePauseFrom(runtime.stageId);
         const run = runtime.activeStore.runs().find((candidate) => candidate.id === runtime.runId);
         const stillActive = run?.stages.some(
-          (s) => s.status === "running" && s.id !== runtime.stageId,
+          (stage) => stage.status === "running" && stage.id !== runtime.stageId,
         ) ?? false;
         if (!stillActive) runtime.activeStore.recordRunPaused(runtime.runId);
       }
-      if (statusBeforePause === "pending" || statusBeforePause === "running" || runtime.innerCtx.isStreaming) {
-        await runtime.innerCtx.__requestPause();
-      }
     },
     async resume(message?: string) {
       runtime.throwIfStageMutationBlocked();
       await ensureMessagingSession();
+      runtime.throwIfStageMutationBlocked();
       const wasPausedBeforeResume = runtime.innerCtx.__isPaused();
-      const hasResumeContinuationMessage = typeof message === "string" && message.trim().length > 0;
-      const previousResumeContinuationPending = runtime.state.resumeContinuationPending;
-      const queuedResumeContinuation = wasPausedBeforeResume && hasResumeContinuationMessage;
-      if (queuedResumeContinuation) runtime.state.resumeContinuationPending = true;
+      const resumesIdleStageChat = wasPausedBeforeResume && runtime.state.waitingForStageChatTurn;
+      const hasMessage = typeof message === "string" && message.trim().length > 0;
+      const resumeMessage = hasMessage ? message : undefined;
+      const queuedResumeContinuation = wasPausedBeforeResume && !resumesIdleStageChat;
+      const addedResumeContinuation = queuedResumeContinuation && runtime.state.resumeContinuationPending === false;
+      if (addedResumeContinuation) runtime.state.resumeContinuationPending = "resume";
       try {
+        await runtime.innerCtx.__resume(resumesIdleStageChat ? undefined : resumeMessage);
         const changed = runtime.activeStore.recordStageResumed(runtime.runId, runtime.stageId);
         if (changed) {
           runtime.scheduler.releaseStageBarrier(runtime.stageId);
           await runtime.scheduler.cascadeResumeFrom(runtime.stageId);
+          // Preserve manual per-stage semantics: once this acknowledged
+          // resume succeeds, the run is active even if sibling stages remain paused.
           runtime.activeStore.recordRunResumed(runtime.runId);
         }
-        await runtime.innerCtx.__resume(message);
+        if (resumesIdleStageChat && hasMessage) {
+          runtime.throwIfStageMutationBlocked();
+          return await runtime.innerCtx.__sendUserMessage(
+            message,
+            undefined,
+            runtime.throwIfStageMutationBlocked,
+          );
+        }
       } catch (err) {
-        if (queuedResumeContinuation) runtime.state.resumeContinuationPending = previousResumeContinuationPending;
+        if (addedResumeContinuation && runtime.state.resumeContinuationPending === "resume") {
+          runtime.state.resumeContinuationPending = false;
+        }
         throw err;
       } finally {
         runtime.captureStageSessionMeta();

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

@@ -1,3 +1,4 @@
+import { runCallback, runSynchronousCallback } from "@bastani/atomic";
 import type { Store } from "../../shared/store.js";
 import type { StageSnapshot } from "../../shared/store-types.js";
 import type { StageOptions } from "../../shared/types.js";
@@ -25,6 +26,7 @@ import { createStageControlHandle } from "./executor-stage-control.js";
 import { createTrackedStageCaller } from "./executor-stage-call.js";
 import { createStageContext } from "./executor-stage-context.js";
 import { stageOptionsWithGitWorktree, stageOptionsWithInputDefaults, type GitWorktreeSetupCache } from "./executor-direct-helpers.js";
+import { createQueuedUserMessageConsumptionWatcher } from "./executor-queued-user-message.js";
 
 export function createWorkflowStageFactory(input: {
   readonly runId: string;
@@ -145,6 +147,7 @@ export function createWorkflowStageFactory(input: {
       askUserQuestionObservedThisTurn: false,
       chatAnswerObservedThisTurn: false,
       resumeContinuationPending: false,
+      waitingForStageChatTurn: false,
       liveHandleReleased: false,
       stageClosedByWorkflowExit: false,
       stageFinalized: false,
@@ -178,9 +181,15 @@ export function createWorkflowStageFactory(input: {
         stageUiBroker.clearStagePrompt(input.runId, stageId);
       }
     });
+    const unsubscribeQueuedUserMessageWatcher = innerCtx.subscribe(
+      createQueuedUserMessageConsumptionWatcher(() => {
+        state.resumeContinuationPending = "queued-user-message";
+      }),
+    );
 
     const disposeInnerContext = async (): Promise<void> => {
       unsubscribeAskUserQuestionWatcher();
+      unsubscribeQueuedUserMessageWatcher();
       activeAskUserQuestionCalls.clear();
       state.activeAskUserQuestionAnonymousCalls = 0;
       input.activeStore.recordStageAwaitingInput(input.runId, stageId, false);
@@ -212,6 +221,9 @@ export function createWorkflowStageFactory(input: {
         throw new Error(`atomic-workflows: stage "${name}" skipped by workflow exit`);
       }
       input.exit.throwIfWorkflowExitSelected();
+      if (input.signal.aborted) {
+        throw input.signal.reason ?? new DOMException("workflow killed", "AbortError");
+      }
     };
 
     let stageStartEntryAppended = false;
@@ -244,7 +256,12 @@ export function createWorkflowStageFactory(input: {
       applyModelFallbackMeta(innerCtx.__modelFallbackMeta());
       input.activeStore.recordStageEnd(input.runId, stageSnapshot);
       stageUiBroker.cancelStagePrompt(input.runId, stageId, new Error(`atomic-workflows: stage ${stageId} completed with pending custom UI`));
-      await input.opts.onStageEnd?.(input.runId, stageSnapshot);
+      if (input.opts.onStageEnd) {
+        await runCallback(
+          { kind: "workflow.stage_adapter", name: `onStageEnd:${name}`, runId: input.runId, stageId },
+          () => input.opts.onStageEnd!(input.runId, stageSnapshot),
+        );
+      }
       if (input.opts.persistence) {
         appendStageStartOnce();
         appendStageEnd(input.opts.persistence, {
@@ -318,7 +335,12 @@ export function createWorkflowStageFactory(input: {
     runtime.unregisterStageHandle = input.stageRegistry.register(handle);
 
     input.activeStore.recordStageStart(input.runId, stageSnapshot);
-    input.opts.onStageStart?.(input.runId, stageSnapshot);
+    if (input.opts.onStageStart) {
+      runSynchronousCallback(
+        { kind: "workflow.stage_adapter", name: `onStageStart:${name}`, runId: input.runId, stageId },
+        () => input.opts.onStageStart!(input.runId, stageSnapshot),
+      );
+    }
     const blockedBy = input.scheduler.blockingAncestorFor(stageSnapshot);
     if (blockedBy !== undefined) input.scheduler.blockStageUntilCascadeRelease(stageSnapshot, blockedBy);
 
@@ -330,20 +352,24 @@ export function createWorkflowStageFactory(input: {
     const skipForParallelFailFast = async (): Promise<void> => {
       if (isTerminalStage(stageSnapshot)) return;
       markSkippedForParallelFailFast();
-      await finalizeStageSnapshot();
+      innerCtx.__sealGeneration();
       await innerCtx.abort().catch(() => {});
+      await innerCtx.__closeGeneration();
+      await finalizeStageSnapshot();
       await dropStageControlForCompletion().catch(() => {});
     };
     stageFailFastScope?.activeStages.set(stageId, { skip: skipForParallelFailFast });
     runtime.unregisterWorkflowExitCleanup = input.exit.registerWorkflowExitCleanup(stageId, {
       async skipForWorkflowExit(reason?: string): Promise<void> {
         state.stageClosedByWorkflowExit = true;
+        innerCtx.__sealGeneration();
+        await innerCtx.abort().catch(() => {});
+        await innerCtx.__closeGeneration();
         if (!isTerminalStage(stageSnapshot)) {
           stageSnapshot.status = "skipped";
           stageSnapshot.skippedReason = input.exit.workflowExitSkippedReason(reason);
           await finalizeStageSnapshot();
         }
-        await innerCtx.abort().catch(() => {});
         await releaseLiveHandle().catch(() => {});
       },
     });

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

@@ -96,6 +96,7 @@ export function createReplayStageContext(input: {
     prompt: replayText,
     complete: replayText,
     sendUserMessage: async () => rejectReplayMutation("send a user message"),
+    __sendUserMessage: async () => rejectReplayMutation("send a user message"),
     steer: async () => rejectReplayMutation("steer"),
     followUp: async () => rejectReplayMutation("follow up"),
     subscribe: () => () => {},
@@ -119,6 +120,8 @@ export function createReplayStageContext(input: {
     getLastAssistantText: () => replayResult,
     __ensureSession: async () => {},
     __ensureSessionFromFile: async () => {},
+    __sealGeneration: () => {},
+    __closeGeneration: async () => {},
     __sessionMeta: () => ({ sessionId: replaySource.sessionId, sessionFile: replaySource.sessionFile }),
     __agentSession: () => undefined,
     __pendingMessageCount: () => 0,

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

@@ -14,11 +14,14 @@ export interface StageMcpScope {
   clear(): void;
 }
 
+export type ResumeContinuationReason = "resume" | "queued-user-message";
+
 export interface LiveStageMutableState {
   activeAskUserQuestionAnonymousCalls: number;
   askUserQuestionObservedThisTurn: boolean;
   chatAnswerObservedThisTurn: boolean;
-  resumeContinuationPending: boolean;
+  resumeContinuationPending: false | ResumeContinuationReason;
+  waitingForStageChatTurn: boolean;
   liveHandleReleased: boolean;
   stageClosedByWorkflowExit: boolean;
   stageFinalized: boolean;

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

@@ -7,8 +7,6 @@ import type {
   WorkflowTaskStep,
   WorkflowChainOptions,
   WorkflowParallelOptions,
-  WorkflowDirectOptions,
-  WorkflowDirectTaskItem,
   WorkflowMaxOutput,
 } from "../../shared/types.js";
 
@@ -147,9 +145,6 @@ export function parallelFallbackTask(steps: readonly WorkflowTaskStep[], options
   return "";
 }
 
-export function directTaskPrompt(item: WorkflowDirectTaskItem): string | undefined {
-  return item.prompt ?? item.task;
-}
 
 export function normalizeMaxOutput(maxOutput: WorkflowMaxOutput | undefined): Required<WorkflowMaxOutput> {
   return {
@@ -229,65 +224,3 @@ export function taskWithSharedDefaults(
     ...withoutUndefinedProperties(taskOptions),
   } as WorkflowTaskExecutionOptions;
 }
-
-export function directTaskWithDefaults(
-  item: WorkflowDirectTaskItem,
-  options: WorkflowDirectOptions,
-): WorkflowDirectTaskItem {
-  const {
-    task: _task,
-    chainName: _chainName,
-    concurrency: _concurrency,
-    failFast: _failFast,
-    chainDir: _chainDir,
-    reads,
-    output,
-    outputMode,
-    worktree,
-    gitWorktreeDir,
-    baseBranch,
-    maxOutput,
-    artifacts,
-    ...stageDefaults
-  } = options;
-
-  const taskWithStageDefaults = {
-    ...withoutUndefinedProperties(stageDefaults),
-    ...withoutUndefinedProperties(item),
-    name: item.name,
-  } as WorkflowDirectTaskItem;
-
-  return {
-    ...taskWithStageDefaults,
-    ...(item.reads === undefined && reads !== undefined ? { reads } : {}),
-    ...(item.output === undefined && output !== undefined ? { output } : {}),
-    ...(item.outputMode === undefined && outputMode !== undefined ? { outputMode } : {}),
-    ...(item.worktree === undefined && worktree !== undefined ? { worktree } : {}),
-    ...(item.gitWorktreeDir === undefined && gitWorktreeDir !== undefined ? { gitWorktreeDir } : {}),
-    ...(item.baseBranch === undefined && baseBranch !== undefined ? { baseBranch } : {}),
-    ...(item.maxOutput === undefined && maxOutput !== undefined ? { maxOutput } : {}),
-    ...(item.artifacts === undefined && artifacts !== undefined ? { artifacts } : {}),
-  };
-}
-
-export function directTaskToStep(
-  item: WorkflowDirectTaskItem,
-  fallbackPrompt?: string,
-  previous?: WorkflowTaskOptions["previous"],
-): WorkflowTaskStep {
-  const {
-    count: _count,
-    output: _output,
-    outputMode: _outputMode,
-    worktree: _worktree,
-    prompt,
-    task,
-    previous: itemPrevious,
-    ...stageOptions
-  } = item;
-  return {
-    ...stageOptions,
-    prompt: prompt ?? task ?? fallbackPrompt,
-    previous: previous ?? itemPrevious,
-  };
-}

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

@@ -57,6 +57,12 @@ export interface RunOpts extends Omit<AuthoringContract.RunOpts, "adapters" | "s
   signal?: AbortSignal;
   /** Yield to the next event-loop turn before invoking user workflow code. */
   deferWorkflowStart?: boolean;
+  /**
+   * Invoked once the run has persisted `run.start`, registered its durable
+   * invocation metadata, and is about to execute the workflow body. Callers
+   * can finalize a source claim only after this startup-admission signal.
+   */
+  onWorkflowStartReady?: () => void;
   /** Resolved runtime configuration. */
   config?: WorkflowRuntimeConfig;
   /** Optional model catalog used for fallback validation/resolution. */

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

@@ -8,7 +8,6 @@
 
 export type { ResolvedInputs, RunContinuationOpts, RunOpts, RunResult } from "./executor-types.js";
 export { run } from "./executor-run.js";
-export { runTask, runParallel, runChain } from "./executor-direct.js";
 export { resolveInputs, resolveAndValidateInputs } from "./executor-inputs.js";
 export { raceAbort } from "./executor-abort.js";
 export {

package/dist/builtin/workflows/src/runs/foreground/postmortem-stage-chat.ts

@@ -0,0 +1,169 @@
+/**
+ * Post-mortem stage-chat resolver.
+ *
+ * Generalizes the safe detached-handle pattern introduced by completed
+ * durable-workflow inspection (#1758) so any eligible terminal agent stage
+ * with a valid retained Atomic session can be reopened as an interactive
+ * post-mortem chat — from generic `/workflow attach` / `/workflow connect`,
+ * restored/replayed durable snapshots, and `workflow send` — not only the
+ * dedicated completed-inspection path.
+ *
+ * A post-mortem chat appends follow-up conversation to the stage's retained
+ * session (append-in-place, matching same-process handles and #1758). It never
+ * resumes, retries, rewinds, or otherwise mutates workflow execution: the
+ * handle is detached from run-level pause/resume control from birth and cannot
+ * pause/resume the workflow DAG. Tool side effects from follow-up turns are
+ * possible (the agent keeps its ordinary tools); only the workflow execution
+ * state is immutable.
+ *
+ * The resolver deliberately does NOT fabricate a `LiveStageRuntime`: that
+ * carries scheduler, store-mutation, exit, failure, and finalization
+ * dependencies a post-mortem conversation must never receive.
+ *
+ * cross-ref:
+ *   - src/durable/completed-inspection.ts (authoritative completed catalog/open)
+ *   - src/runs/foreground/stage-control-registry.ts (get-or-create ownership)
+ *   - src/shared/session-transcript.ts (retained-session validation)
+ */
+import type { StageSnapshot } from "../../shared/store-types.js";
+import { isReopenableSessionTranscript } from "../../shared/session-transcript.js";
+import { createStageContext, type StageAdapters } from "./stage-runner.js";
+import {
+  type AgentSessionEventListener,
+  type StageControlHandle,
+  type StageControlRegistry,
+} from "./stage-control-registry.js";
+
+/** Why a terminal stage could not be revived as an interactive post-mortem chat. */
+export type PostMortemUnavailableReason =
+  | "no_adapter"
+  | "not_terminal"
+  | "no_session"
+  | "invalid_session";
+
+export type EnsurePostMortemStageHandleResult =
+  | { readonly ok: true; readonly handle: StageControlHandle }
+  | { readonly ok: false; readonly reason: PostMortemUnavailableReason };
+
+export interface PostMortemStageChatDeps {
+  readonly registry: StageControlRegistry;
+  readonly adapters?: StageAdapters;
+  /** Working directory used when reopening the retained session. */
+  readonly cwd?: string;
+  /** Default stage session directory to restore after a host restart. */
+  readonly defaultSessionDir?: string;
+}
+
+/** Terminal statuses whose retained agent session may be reopened for follow-up. */
+const TERMINAL_POSTMORTEM_STATUSES = new Set<StageSnapshot["status"]>(["completed"]);
+
+/**
+ * True when the snapshot is an eligible terminal agent stage: a completed stage
+ * that retains a `sessionFile`. Prompt/boundary/summary/skipped nodes without
+ * their own agent session are excluded because they have no `sessionFile`.
+ */
+export function isPostMortemEligibleStage(stage: StageSnapshot): boolean {
+  return TERMINAL_POSTMORTEM_STATUSES.has(stage.status)
+    && typeof stage.sessionFile === "string"
+    && stage.sessionFile.length > 0;
+}
+
+/**
+ * Resolve an interactive post-mortem chat handle for a terminal agent stage.
+ *
+ * Reuses an existing non-disposed registry handle when present; otherwise
+ * validates the retained session and lazily creates a detached, single-flight
+ * handle keyed by the real `{ runId, stageId }`. Returns an explicit
+ * unavailable reason so callers can preserve the read-only transcript.
+ */
+export function ensurePostMortemStageHandle(
+  runId: string,
+  stage: StageSnapshot,
+  deps: PostMortemStageChatDeps,
+): EnsurePostMortemStageHandleResult {
+  if (!TERMINAL_POSTMORTEM_STATUSES.has(stage.status)) return { ok: false, reason: "not_terminal" };
+  const existing = deps.registry.get(runId, stage.id);
+  if (existing !== undefined && existing.isDisposed !== true) {
+    return { ok: true, handle: existing };
+  }
+  if (deps.adapters?.agentSession === undefined) return { ok: false, reason: "no_adapter" };
+  const sessionFile = stage.sessionFile;
+  if (typeof sessionFile !== "string" || sessionFile.length === 0) return { ok: false, reason: "no_session" };
+  if (!isReopenableSessionTranscript(sessionFile)) return { ok: false, reason: "invalid_session" };
+
+  const adapters = deps.adapters;
+  const handle = deps.registry.getOrCreateDetached(runId, stage.id, () =>
+    createPostMortemStageHandle(runId, stage, sessionFile, adapters, deps.cwd, deps.defaultSessionDir),
+  );
+  return { ok: true, handle };
+}
+
+/**
+ * Build a lazy session-only stage-control handle that reopens `sessionFile` on
+ * first use and appends follow-up conversation without dispatching the
+ * workflow. Pause/resume of workflow execution is rejected.
+ */
+export function createPostMortemStageHandle(
+  runId: string,
+  stage: Pick<StageSnapshot, "id" | "name" | "sessionId">,
+  sessionFile: string,
+  adapters: StageAdapters,
+  cwd: string | undefined,
+  defaultSessionDir: string | undefined,
+): StageControlHandle {
+  const context = createStageContext({
+    runId,
+    stageId: stage.id,
+    stageName: stage.name,
+    adapters,
+    stageOptions: {
+      resumeFromSessionFile: sessionFile,
+      ...(cwd !== undefined ? { cwd } : {}),
+    },
+    ...(defaultSessionDir !== undefined ? { defaultSessionDir } : {}),
+  });
+  let disposed = false;
+  const ensureAttached = async (): Promise<void> => {
+    if (disposed) throw new Error(`Post-mortem stage chat "${stage.name}" is closed.`);
+    if (context.__sessionMeta().sessionFile === undefined) {
+      await context.__ensureSessionFromFile(sessionFile);
+    }
+  };
+  return {
+    runId,
+    stageId: stage.id,
+    stageName: stage.name,
+    status: "completed",
+    get sessionId() { return context.__sessionMeta().sessionId ?? stage.sessionId; },
+    get sessionFile() { return context.__sessionMeta().sessionFile ?? sessionFile; },
+    get isStreaming() { return context.isStreaming; },
+    get isDisposed() { return disposed; },
+    get messages() { return context.messages; },
+    get agentSession() { return context.__agentSession(); },
+    async ensureAttached() { await ensureAttached(); },
+    async prompt(text: string) {
+      await ensureAttached();
+      await context.prompt(text);
+    },
+    async steer(text: string) {
+      await ensureAttached();
+      await context.steer(text);
+    },
+    async followUp(text: string) {
+      await ensureAttached();
+      await context.followUp(text);
+    },
+    async pause() {
+      throw new Error("Post-mortem stage chat cannot pause or resume workflow execution.");
+    },
+    async resume() {
+      throw new Error("Post-mortem stage chat cannot pause or resume workflow execution.");
+    },
+    subscribe(listener: AgentSessionEventListener) { return context.subscribe(listener); },
+    async dispose() {
+      if (disposed) return;
+      disposed = true;
+      await context.__dispose();
+    },
+  };
+}