@bastani/atomic 0.9.9 → 0.9.10

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

@@ -26,6 +26,7 @@
  */
 
 import type { AgentSession, AgentSessionEvent } from "@bastani/atomic";
+import type { StageUserMessageDeliveryAction } from "./stage-runner-types.js";
 
 export type StageControlStatus =
   | "pending"
@@ -63,6 +64,12 @@ export interface StageControlHandle {
   pendingToolExecutionEvents?(): readonly AgentSessionEvent[];
   /** Ensure the SDK session exists. Cheap when already attached. */
   ensureAttached(): Promise<void>;
+  /** Deliver through the idle-aware session primitive and report the actual action. */
+  sendUserMessage?(
+    text: string,
+    options?: { readonly deliverAs?: "steer" | "followUp" },
+  ): Promise<StageUserMessageDeliveryAction>;
+
   /** Send a prompt. Use only when the stage is idle / not streaming. */
   prompt(text: string): Promise<void>;
   /** Steer the current streaming operation (interrupt mid-turn). */
@@ -79,7 +86,7 @@ export interface StageControlHandle {
    * Release a paused stage. If `message` is provided it is sent as the
    * next user message before resuming.
    */
-  resume(message?: string): Promise<void>;
+  resume(message?: string): Promise<void | StageUserMessageDeliveryAction>;
   /**
    * Subscribe to AgentSession events. The pending-listener semantics
    * from `InternalStageContext.subscribe` apply: listeners registered
@@ -123,6 +130,18 @@ export interface StageControlRegistry {
    * keep using its direct handle reference.
    */
   register(handle: StageControlHandle): () => void;
+  /**
+   * Atomically resolve an existing non-disposed handle for `runId + stageId`
+   * or create one via `create`, register it, and immediately detach it from
+   * run-level pause/resume control. Used by the post-mortem stage-chat
+   * resolver so repeated attach/send calls single-flight onto one detached
+   * writer per real stage instead of racing competing sessions.
+   */
+  getOrCreateDetached(
+    runId: string,
+    stageId: string,
+    create: () => StageControlHandle,
+  ): StageControlHandle;
   /**
    * Remove this stage from run-level pause/resume aggregates while keeping
    * `get()` chat attachment live until the registration disposer runs.
@@ -252,6 +271,24 @@ export function createStageControlRegistry(): StageControlRegistry {
         if (existing.size === 0) _byRun.delete(handle.runId);
       };
     },
+    getOrCreateDetached(
+      runId: string,
+      stageId: string,
+      create: () => StageControlHandle,
+    ): StageControlHandle {
+      const runMap = ensureRun(runId);
+      const existing = runMap.get(stageId);
+      if (existing !== undefined && existing.handle.isDisposed !== true) return existing.handle;
+      if (existing !== undefined) {
+        runMap.delete(stageId);
+        void Promise.resolve(existing.handle.dispose?.()).catch((err: unknown) => {
+          console.warn("atomic-workflows: stale stage handle dispose failed", err);
+        });
+      }
+      const handle = create();
+      runMap.set(handle.stageId, { handle, controlsDependencies: false });
+      return handle;
+    },
     detachControl(runId: string, stageId: string, handle?: StageControlHandle): boolean {
       const entry = _byRun.get(runId)?.get(stageId);
       if (!entry) return false;

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

@@ -0,0 +1,21 @@
+import type { StageOptions, WorkflowModelAttempt } from "../../shared/types.js";
+import type { WorkflowResolvedModelCandidate } from "../shared/model-fallback.js";
+
+export function effectiveCandidateReasoning(
+  candidate: WorkflowResolvedModelCandidate,
+  fallback: StageOptions["thinkingLevel"] | undefined,
+): StageOptions["thinkingLevel"] | undefined {
+  return candidate.reasoningLevel ?? fallback;
+}
+
+export function modelAttemptReasoning(
+  candidate: WorkflowResolvedModelCandidate,
+  fallback: StageOptions["thinkingLevel"] | undefined,
+): Pick<WorkflowModelAttempt, "reasoningLevel"> {
+  const reasoningLevel = effectiveCandidateReasoning(candidate, fallback);
+  return reasoningLevel !== undefined ? { reasoningLevel } : {};
+}
+
+export function candidateLabel(candidate: WorkflowResolvedModelCandidate): string {
+  return candidate.reasoningLevel !== undefined ? `${candidate.id}:${candidate.reasoningLevel}` : candidate.id;
+}

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

@@ -1,4 +1,4 @@
-import { createStructuredOutputCapture } from "@bastani/atomic";
+import { createStructuredOutputCapture, runCallback } from "@bastani/atomic";
 import type { StageExecutionMeta } from "../../shared/types.js";
 import { StageSessionController } from "./stage-runner-controller.js";
 import { assistantMessage } from "./stage-runner-messages.js";
@@ -42,7 +42,10 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
         if (structuredOutputCapture) {
           throw new Error("atomic-workflows: stage schema requires an AgentSessionAdapter so the structured_output tool can be registered.");
         }
-        const rawText = await adapters.prompt.prompt(text, meta);
+        const rawText = await runCallback(
+          { kind: "workflow.stage_adapter", name: `prompt:${stageName}`, runId, stageId },
+          () => adapters.prompt!.prompt(text, meta),
+        );
         lastAssistantText = await finalizePromptOutput(rawText, outputOptions, runtimeCwd());
         adapterMessages = assistantMessage(lastAssistantText);
         return lastAssistantText;
@@ -74,7 +77,10 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
 
     async complete(text, completeOpts) {
       if (adapters.complete) {
-        lastAssistantText = await adapters.complete.complete(text, completeOpts, meta);
+        lastAssistantText = await runCallback(
+          { kind: "workflow.stage_adapter", name: `complete:${stageName}`, runId, stageId },
+          () => adapters.complete!.complete(text, completeOpts, meta),
+        );
         adapterMessages = assistantMessage(lastAssistantText);
         return lastAssistantText;
       }
@@ -96,6 +102,10 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
       await controller.sendUserMessage(text, options);
     },
 
+    async __sendUserMessage(text, options, beforeDelivery) {
+      return controller.sendUserMessage(text, options, beforeDelivery);
+    },
+
     async steer(text) {
       await (await controller.ensureSession()).steer(text);
     },
@@ -188,6 +198,14 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
       await controller.ensureSessionFromFile(sessionFile);
     },
 
+    __sealGeneration() {
+      controller.sealGeneration();
+    },
+
+    async __closeGeneration() {
+      await controller.closeGeneration();
+    },
+
     __sessionMeta() {
       return controller.sessionMeta();
     },

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

@@ -1,13 +1,17 @@
-import { getModelDefaultContextWindow, getSupportedContextWindows, SessionManager, shouldApplyCodexFastModeForScope, type AgentSession, type CreateAgentSessionOptions, type PromptOptions, type StructuredOutputCapture } from "@bastani/atomic";
+import { shouldApplyCodexFastModeForScope, type AgentSession, type CreateAgentSessionOptions, type PromptOptions, type StructuredOutputCapture } from "@bastani/atomic";
 import type { StageContext, StageExecutionMeta, StageOptions, StageSendUserMessageOptions, StageUserMessageContent, WorkflowModelAttempt, WorkflowModelCatalogPort } from "../../shared/types.js";
 import { buildModelCandidatesFromCatalog, errorMessage, isRetryableModelFailure, workflowModelId, type WorkflowResolvedModelCandidate } from "../shared/model-fallback.js";
+import { candidateLabel, effectiveCandidateReasoning, modelAttemptReasoning } from "./stage-runner-candidate.js";
 import { WorkflowPromptModelFailure, lastAssistantTextFromSession, latestTerminalAssistantFailureSince } from "./stage-runner-messages.js";
 import { missingAdapter, stripWorkflowOnlyOptions, unavailableSync } from "./stage-runner-options.js";
-import { asAgentSession, disposeStageSession, normalizeSessionCreateResult } from "./stage-runner-session.js";
+import { asAgentSession, attachCreatedStageSession, disposeStageSession, normalizeSessionCreateResult } from "./stage-runner-session.js";
 import { structuredOutputToolErrorFromEvent } from "./stage-runner-structured-output.js";
+import { buildStageSessionOptions } from "./stage-runner-session-options.js";
 import { sendStageUserMessage } from "./stage-runner-send-user-message.js";
+import { StageMessageAdmission } from "./stage-runner-message-admission.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";
+import { StageSessionReplacement } from "./stage-runner-replacement.js";
 
 type PauseRequest = {
   deferred: PromiseWithResolvers<{ message?: string }>;
@@ -15,12 +19,14 @@ type PauseRequest = {
 
 export class StageSessionController {
   private session: StageSessionRuntime | undefined;
+  private activeCreation: Promise<StageSessionRuntime> | undefined;
   private sessionPromise: Promise<StageSessionRuntime> | undefined;
   private reattachSessionFile: string | undefined;
   private readonly terminatingToolCallIds = new Set<string>();
   private latestStructuredOutputToolErrorValue: string | undefined;
   private unsubscribeTerminateWatcher: (() => void) | undefined;
   private unresolvedContextOverflowMessage: string | undefined;
+  private generationSealed = false;
   private disposed = false;
   private pendingThinkingLevel: Parameters<StageContext["setThinkingLevel"]>[0] | undefined;
   private readonly pendingListeners = new Set<(event: StageSessionEvent) => void>();
@@ -31,12 +37,15 @@ export class StageSessionController {
   private activeCandidateIndex: number | undefined;
   private selectedModel: string | undefined;
   private sharedModelRegistry: CreateAgentSessionOptions["modelRegistry"];
+  private sharedOrchestrationContext: CreateAgentSessionOptions["orchestrationContext"];
   private resumeCurrentSession = false;
   private readonly modelAttempts: WorkflowModelAttempt[] = [];
   private readonly modelWarnings: string[] = [];
   private readonly pendingFallbackWarnings: string[] = [];
   private readonly modelCatalog: WorkflowModelCatalogPort | undefined;
   private sessionSettingsManager: WorkflowFastModeSettingsManager | undefined;
+  private readonly replacement = new StageSessionReplacement();
+  private readonly messageAdmission = new StageMessageAdmission();
 
   constructor(
     private readonly opts: StageRunnerOpts,
@@ -83,9 +92,7 @@ export class StageSessionController {
     };
   }
 
-  setThinkingLevel(level: Parameters<StageContext["setThinkingLevel"]>[0]): void {
-    this.pendingThinkingLevel = level; this.session?.setThinkingLevel(level);
-  }
+  setThinkingLevel(level: Parameters<StageContext["setThinkingLevel"]>[0]): void { this.pendingThinkingLevel = level; this.session?.setThinkingLevel(level); }
 
   async ensureSession(consumer: AgentSessionConsumer = "prompt"): Promise<StageSessionRuntime> {
     if (this.disposed) throw new Error(`atomic-workflows: stage "${this.opts.stageName}" session has been disposed`);
@@ -95,13 +102,29 @@ export class StageSessionController {
   }
 
   async ensureSessionFromFile(sessionFile: string, consumer: AgentSessionConsumer = "prompt"): Promise<StageSessionRuntime> {
-    if (this.sessionPromise || this.session) return this.ensureSession(consumer);
-    this.reattachSessionFile = sessionFile;
-    return this.ensureSession(consumer);
+    if (!this.sessionPromise && !this.session) this.reattachSessionFile = sessionFile;
+    const session = await this.ensureSession(consumer);
+    await session.closeWorkflowStageGeneration?.();
+    return session;
+  }
+
+  async sendUserMessage(content: StageUserMessageContent, options?: StageSendUserMessageOptions, beforeDelivery?: () => void):
+    Promise<Awaited<ReturnType<typeof sendStageUserMessage>>> {
+    return this.messageAdmission.run(async (release) => sendStageUserMessage(
+      await this.ensureSession("prompt"), content, options, beforeDelivery, release, this.messageAdmission,
+    ));
   }
 
-  async sendUserMessage(content: StageUserMessageContent, options?: StageSendUserMessageOptions): Promise<void> {
-    await sendStageUserMessage(await this.ensureSession("prompt"), content, options);
+  sealGeneration(): void {
+    this.generationSealed = true;
+    this.sharedOrchestrationContext?.messageAdmission?.boundary.seal();
+    this.session?.sealWorkflowStageGeneration?.();
+  }
+  async closeGeneration(): Promise<void> {
+    this.sealGeneration();
+    const pending = this.activeCreation ?? this.sessionPromise;
+    const session = pending ? await pending : this.session;
+    await session?.closeWorkflowStageGeneration?.();
   }
 
   async promptWithFallback(
@@ -171,7 +194,8 @@ export class StageSessionController {
     this.pendingListeners.clear();
     this.unsubscribeTerminateWatcher?.();
     this.unsubscribeTerminateWatcher = undefined;
-    this.terminatingToolCallIds.clear();
+    this.terminatingToolCallIds.clear(); this.messageAdmission.dispose();
+    await this.replacement.dispose();
     await disposeStageSession(this.session);
   }
 
@@ -179,8 +203,12 @@ export class StageSessionController {
     if (this.pauseRequest) return;
     const deferred = Promise.withResolvers<{ message?: string }>();
     void deferred.promise.catch(() => {});
-    this.pauseRequest = { deferred };
-    await this.session?.abort();
+    const request = { deferred };
+    this.pauseRequest = request;
+    try { await this.session?.abort(); } catch (error) {
+      if (this.pauseRequest === request) { this.pauseRequest = null; deferred.reject(error); }
+      throw error;
+    }
   }
 
   resume(message?: string): void {
@@ -191,16 +219,13 @@ export class StageSessionController {
   }
 
   isPaused(): boolean { return this.pauseRequest !== null; }
-
   sessionMeta(): { sessionId: string | undefined; sessionFile: string | undefined } {
     return { sessionId: this.session?.sessionId, sessionFile: this.session?.sessionFile };
   }
 
   agentSession(): AgentSession | undefined { return asAgentSession(this.session); }
 
-  pendingMessageCount(): number {
-    return typeof this.session?.pendingMessageCount === "number" ? this.session.pendingMessageCount : 0;
-  }
+  pendingMessageCount(): number { return typeof this.session?.pendingMessageCount === "number" ? this.session.pendingMessageCount : 0; }
 
   private bindAbortSignal(): void {
     const { signal } = this.opts;
@@ -233,50 +258,6 @@ export class StageSessionController {
     return this.candidatesPromise;
   }
 
-  private stageOptionsForCandidate(
-    candidate: WorkflowResolvedModelCandidate | undefined,
-    resumeOptions?: { restoreSavedModel?: boolean },
-  ): StageOptions | undefined {
-    const optionsForCandidate: StageOptions = candidate === undefined
-      ? { ...(this.effectiveStageOptions ?? {}) }
-      : {
-          ...(this.effectiveStageOptions ?? {}),
-          model: candidate.value,
-          ...(candidate.reasoningLevel !== undefined ? { thinkingLevel: candidate.reasoningLevel } : {}),
-          ...(candidate.contextWindow !== undefined ? { contextWindow: candidate.contextWindow } : {}),
-          fallbackModels: undefined,
-          fallbackThinkingLevels: undefined,
-        };
-    if (resumeOptions?.restoreSavedModel) delete optionsForCandidate.model;
-    // Pin a tiered model's short default context window for fresh, non-resumed
-    // stage sessions unless the author selected a long tier via `(1m)` or
-    // contextWindow. This prevents persisted interactive long-tier preferences
-    // from leaking into workflow stages; single-window models are left alone.
-    if (
-      resumeOptions?.restoreSavedModel !== true &&
-      this.reattachSessionFile === undefined &&
-      optionsForCandidate.contextWindow === undefined &&
-      candidate !== undefined &&
-      typeof candidate.value !== "string" &&
-      getSupportedContextWindows(candidate.value).length > 1
-    ) {
-      optionsForCandidate.contextWindow = getModelDefaultContextWindow(candidate.value);
-    }
-    if (this.reattachSessionFile !== undefined && optionsForCandidate.sessionManager === undefined) {
-      const cwd = optionsForCandidate.cwd ?? process.cwd();
-      optionsForCandidate.sessionManager = SessionManager.open(
-        this.reattachSessionFile,
-        optionsForCandidate.sessionDir,
-        cwd,
-      );
-      optionsForCandidate.context = undefined;
-      optionsForCandidate.forkFromSessionFile = undefined;
-    }
-    if (this.sharedModelRegistry !== undefined && optionsForCandidate.modelRegistry === undefined) {
-      optionsForCandidate.modelRegistry = this.sharedModelRegistry;
-    }
-    return Object.keys(optionsForCandidate).length === 0 ? undefined : optionsForCandidate;
-  }
 
   private async createInitialSession(consumer: AgentSessionConsumer): Promise<StageSessionRuntime> {
     if (!this.hasExplicitModelFallbackConfig) return this.createSession(undefined, consumer);
@@ -297,24 +278,56 @@ export class StageSessionController {
     return this.createSession(first, consumer);
   }
 
-  private async createSession(
+
+  private createSession(
+    candidate: WorkflowResolvedModelCandidate | undefined,
+    consumer: AgentSessionConsumer,
+    resumeOptions?: { restoreSavedModel?: boolean },
+  ): Promise<StageSessionRuntime> {
+    const creation = this.createSessionAttempt(candidate, consumer, resumeOptions);
+    this.activeCreation = creation;
+    void creation.finally(() => {
+      if (this.activeCreation === creation) this.activeCreation = undefined;
+    }).catch(() => {});
+    return creation;
+  }
+
+  private async createSessionAttempt(
     candidate: WorkflowResolvedModelCandidate | undefined,
     consumer: AgentSessionConsumer,
     resumeOptions?: { restoreSavedModel?: boolean },
   ): Promise<StageSessionRuntime> {
     this.applyCandidateThinking(candidate);
-    const stageOptions = this.stageOptionsForCandidate(candidate, resumeOptions);
+    const stageOptions = buildStageSessionOptions({
+      effectiveStageOptions: this.effectiveStageOptions,
+      candidate,
+      restoreSavedModel: resumeOptions?.restoreSavedModel,
+      reattachSessionFile: this.reattachSessionFile,
+      sharedModelRegistry: this.sharedModelRegistry,
+    });
     const created = this.opts.adapters.agentSession
       ? await this.opts.adapters.agentSession.create(
           stripWorkflowOnlyOptions(stageOptions, this.opts.defaultSessionDir, this.meta) as StageSessionCreateOptions,
-          { ...this.meta, stageOptions },
+          {
+            ...this.meta,
+            stageOptions,
+            ...(this.sharedOrchestrationContext !== undefined
+              ? { orchestrationContext: this.sharedOrchestrationContext }
+              : {}),
+          },
         )
       : missingAdapter(consumer);
-    return this.attachSession(created);
+    return attachCreatedStageSession(created, this.disposed, this.opts.stageName, (result) => this.attachSession(result));
   }
 
   private attachSession(created: StageSessionRuntime | StageSessionCreateResult): StageSessionRuntime {
     const result = normalizeSessionCreateResult(created);
+    const orchestrationContext = asAgentSession(result.session)?.orchestrationContext;
+    if (this.sharedOrchestrationContext === undefined && orchestrationContext !== undefined) {
+      this.sharedOrchestrationContext = orchestrationContext;
+    }
+    if (this.generationSealed) result.session.sealWorkflowStageGeneration?.();
+    this.replacement.adopt(result.session);
     this.session = result.session;
     if (this.sharedModelRegistry === undefined) {
       const withRegistry = result.session as Partial<Pick<AgentSession, "modelRegistry">>;
@@ -337,7 +350,8 @@ export class StageSessionController {
   }
 
   private async disposeCurrentSession(): Promise<void> {
-    const current = this.session;
+    const current = this.session; this.messageAdmission.reset();
+    this.replacement.retire(current);
     this.session = undefined;
     this.sessionPromise = undefined;
     this.sessionSettingsManager = undefined;
@@ -347,7 +361,6 @@ export class StageSessionController {
     this.unsubscribeTerminateWatcher?.();
     this.unsubscribeTerminateWatcher = undefined;
     this.terminatingToolCallIds.clear();
-    await disposeStageSession(current);
   }
 
   private async promptWithPauseResume(
@@ -431,7 +444,7 @@ export class StageSessionController {
       }
       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]!)}.`);
+      this.pendingFallbackWarnings.push(resumedOverflowNextIndex === undefined ? `[fallback] resume on ${resumedLabel} failed: ${message}. Restarting fallback from ${candidateLabel(candidates[0]!)}.` : `[fallback] resume on ${resumedLabel} failed: ${message}. Retrying with ${candidateLabel(candidates[resumedOverflowNextIndex]!)}.`);
       await this.disposeCurrentSession(); this.activeCandidateIndex = resumedOverflowNextIndex; return false;
     }
   }
@@ -447,7 +460,7 @@ export class StageSessionController {
       this.recordSuccessfulAttempt(candidate);
       return "handled";
     }
-    this.modelAttempts.push({ model: candidate.id, success: false, ...this.modelAttemptReasoning(candidate), error: message });
+    this.modelAttempts.push({ model: candidate.id, success: false, ...modelAttemptReasoning(candidate, this.effectiveStageOptions?.thinkingLevel), error: message });
     if (this.opts.signal?.aborted || !isRetryableModelFailure(err) || index === candidates.length - 1) {
       this.modelWarnings.push(...this.pendingFallbackWarnings);
       this.pendingFallbackWarnings.length = 0;
@@ -455,7 +468,7 @@ export class StageSessionController {
       return "throw";
     }
     const nextCandidate = candidates[index + 1]!;
-    this.pendingFallbackWarnings.push(`[fallback] ${this.candidateLabel(candidate)} failed: ${message}. Retrying with ${this.candidateLabel(nextCandidate)}.`);
+    this.pendingFallbackWarnings.push(`[fallback] ${candidateLabel(candidate)} failed: ${message}. Retrying with ${candidateLabel(nextCandidate)}.`);
     await this.disposeCurrentSession();
     return "retry";
   }
@@ -465,28 +478,16 @@ export class StageSessionController {
   }
 
   private recordSuccessfulAttempt(candidate: WorkflowResolvedModelCandidate): void {
-    this.modelAttempts.push({ model: candidate.id, success: true, ...this.modelAttemptReasoning(candidate) });
+    this.modelAttempts.push({ model: candidate.id, success: true, ...modelAttemptReasoning(candidate, this.effectiveStageOptions?.thinkingLevel) });
     this.pendingFallbackWarnings.length = 0; this.resumeCurrentSession = true;
   }
 
   private notifyModelFallbackMetaChange(): void { this.opts.onModelFallbackMetaChange?.(this.currentModelFallbackMeta()); }
 
-  private effectiveCandidateReasoning(candidate: WorkflowResolvedModelCandidate): StageOptions["thinkingLevel"] | undefined {
-    return candidate.reasoningLevel ?? this.effectiveStageOptions?.thinkingLevel;
-  }
-
-  private modelAttemptReasoning(candidate: WorkflowResolvedModelCandidate): Pick<WorkflowModelAttempt, "reasoningLevel"> {
-    const reasoningLevel = this.effectiveCandidateReasoning(candidate); return reasoningLevel !== undefined ? { reasoningLevel } : {};
-  }
-
   private applyCandidateThinking(candidate: WorkflowResolvedModelCandidate | undefined): void {
     this.pendingThinkingLevel = candidate === undefined
       ? this.effectiveStageOptions?.thinkingLevel
-      : this.effectiveCandidateReasoning(candidate);
-  }
-
-  private candidateLabel(candidate: WorkflowResolvedModelCandidate): string {
-    return candidate.reasoningLevel !== undefined ? `${candidate.id}:${candidate.reasoningLevel}` : candidate.id;
+      : effectiveCandidateReasoning(candidate, this.effectiveStageOptions?.thinkingLevel);
   }
   private isWorkflowFastModeEnabled(): boolean | undefined {
     const model = this.session?.model;

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

@@ -0,0 +1,195 @@
+import type { StageSessionRuntime, StageUserMessageDeliveryAction } from "./stage-runner-types.js";
+
+type TurnState = "starting" | "owned" | "terminal";
+
+type PublicTurnId = string | number;
+
+interface TurnGeneration {
+  readonly id: number;
+  state: TurnState;
+  publicStarted: boolean;
+  publicTurnId?: PublicTurnId;
+}
+
+export interface StageMessageTurn {
+  arm(): void;
+  observe(): void;
+  observeStreaming(): void;
+  settle(action?: StageUserMessageDeliveryAction): void;
+}
+
+export class StageMessageAdmission {
+  private tail: Promise<void> | undefined;
+  private session: StageSessionRuntime | undefined;
+  private observeStarting: (() => void) | undefined;
+  private unsubscribe: (() => void) | undefined;
+  private nextGeneration = 0;
+  private starting: TurnGeneration | undefined;
+  private owned: TurnGeneration | undefined;
+  private readonly startedGenerations: TurnGeneration[] = [];
+  private readonly replayedTurnIds = new Set<PublicTurnId>();
+
+  run<T>(operation: (release: () => void) => Promise<T>): Promise<T> {
+    const admission = this.acquire();
+    if (typeof admission === "function") return this.runAdmitted(operation, admission);
+    return admission.then((release) => this.runAdmitted(operation, release));
+  }
+
+  isOwned(session: StageSessionRuntime): boolean {
+    return this.session === session && this.owned?.state === "owned";
+  }
+
+  startTurn(session: StageSessionRuntime, release: () => void): StageMessageTurn {
+    this.bind(session);
+    const generation: TurnGeneration = {
+      id: ++this.nextGeneration,
+      state: "starting",
+      publicStarted: false,
+    };
+    let armed = false;
+    let settled = false;
+    const observe = (): void => {
+      if (!armed || settled || generation.state !== "starting" || this.starting !== generation) return;
+      generation.state = "owned";
+      this.starting = undefined;
+      this.observeStarting = undefined;
+      this.owned = generation;
+      release();
+    };
+    return {
+      arm: () => {
+        if (settled || armed) return;
+        armed = true;
+        this.starting = generation;
+        this.observeStarting = observe;
+      },
+      observe,
+      observeStreaming: () => {
+        if (session.isStreaming) observe();
+      },
+      settle: (action) => {
+        if (settled) return;
+        settled = true;
+        if (this.starting === generation) {
+          this.starting = undefined;
+          this.observeStarting = undefined;
+        }
+        if (generation.state === "starting") {
+          generation.state = "terminal";
+          this.releaseBindingIfIdle();
+          return;
+        }
+        if (generation.state !== "owned") {
+          this.releaseBindingIfIdle();
+          return;
+        }
+        generation.state = "terminal";
+        if (action === "handled") {
+          const queuedIndex = this.startedGenerations.findIndex((entry) => entry.id === generation.id);
+          if (queuedIndex >= 0) this.startedGenerations.splice(queuedIndex, 1);
+        }
+        if (this.owned === generation) this.owned = undefined;
+        this.releaseBindingIfIdle();
+      },
+    };
+  }
+
+  reset(): void {
+    this.unsubscribe?.();
+    this.unsubscribe = undefined;
+    this.session = undefined;
+    this.observeStarting = undefined;
+    this.starting = undefined;
+    this.owned = undefined;
+    this.startedGenerations.length = 0;
+    this.replayedTurnIds.clear();
+  }
+
+  dispose(): void {
+    this.reset();
+  }
+
+  private bind(session: StageSessionRuntime): void {
+    if (this.session === session) return;
+    this.reset();
+    this.session = session;
+    let subscribing = true;
+    this.unsubscribe = session.subscribe((event) => {
+      if (event.type === "agent_start") {
+        if (subscribing) this.recordReplayedStart(event.turnId);
+        else this.observePublicStart(event.turnId);
+        return;
+      }
+      if (event.type === "agent_end") this.endStartedTurn(event.turnId, !subscribing);
+    });
+    subscribing = false;
+  }
+
+  private recordReplayedStart(turnId: PublicTurnId | undefined): void {
+    // Untagged synchronous callbacks are snapshots only. Recording them would
+    // make a future current-turn end indistinguishable from an old replay end.
+    if (turnId !== undefined) this.replayedTurnIds.add(turnId);
+  }
+
+  private observePublicStart(turnId: PublicTurnId | undefined): void {
+    const generation = this.starting ?? this.owned;
+    if (generation === undefined || generation.state === "terminal") return;
+    this.observeStarting?.();
+    if (generation.publicStarted) return;
+    generation.publicStarted = true;
+    if (turnId !== undefined) {
+      this.replayedTurnIds.delete(turnId);
+      generation.publicTurnId = turnId;
+    }
+    this.startedGenerations.push(generation);
+  }
+
+  private endStartedTurn(turnId: PublicTurnId | undefined, releaseIfIdle = true): void {
+    if (turnId !== undefined && this.replayedTurnIds.delete(turnId)) {
+      if (releaseIfIdle) this.releaseBindingIfIdle();
+      return;
+    }
+    const generationIndex = turnId === undefined
+      ? this.startedGenerations.findIndex((entry) => entry.publicTurnId === undefined)
+      : this.startedGenerations.findIndex((entry) => entry.publicTurnId === turnId);
+    if (generationIndex < 0) return;
+    const [generation] = this.startedGenerations.splice(generationIndex, 1);
+    if (generation === undefined) return;
+    generation.state = "terminal";
+    if (this.owned === generation) this.owned = undefined;
+    if (releaseIfIdle) this.releaseBindingIfIdle();
+  }
+
+  private releaseBindingIfIdle(): void {
+    if (this.starting !== undefined || this.owned !== undefined || this.startedGenerations.length > 0) return;
+    this.unsubscribe?.();
+    this.unsubscribe = undefined;
+    this.session = undefined;
+    this.replayedTurnIds.clear();
+  }
+
+  private acquire(): (() => void) | Promise<() => void> {
+    const previous = this.tail;
+    const next = Promise.withResolvers<void>();
+    this.tail = next.promise;
+    const release = (): void => {
+      next.resolve();
+      if (this.tail === next.promise) this.tail = undefined;
+    };
+    return previous === undefined ? release : previous.then(() => release);
+  }
+
+  private async runAdmitted<T>(operation: (release: () => void) => Promise<T>, release: () => void): Promise<T> {
+    let released = false;
+    const releaseOnce = (): void => {
+      if (released) return;
+      released = true;
+      release();
+    };
+    try {
+      return await operation(releaseOnce);
+    } finally {
+      releaseOnce();
+    }
+  }
+}