@bastani/atomic 0.9.11-alpha.5 → 0.9.11-alpha.7

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

@@ -30,9 +30,11 @@ import { isReopenableSessionTranscript } from "../../shared/session-transcript.j
 import { createStageContext, type StageAdapters } from "./stage-runner.js";
 import {
   type AgentSessionEventListener,
+  type DetachedStageHandleLease,
   type StageControlHandle,
   type StageControlRegistry,
 } from "./stage-control-registry.js";
+import type { StageUserMessagePreparation } from "./stage-runner-types.js";
 
 /** Why a terminal stage could not be revived as an interactive post-mortem chat. */
 export type PostMortemUnavailableReason =
@@ -45,6 +47,10 @@ export type EnsurePostMortemStageHandleResult =
   | { readonly ok: true; readonly handle: StageControlHandle }
   | { readonly ok: false; readonly reason: PostMortemUnavailableReason };
 
+export type AcquirePostMortemStageHandleResult =
+  | { readonly ok: true; readonly lease: DetachedStageHandleLease }
+  | { readonly ok: false; readonly reason: PostMortemUnavailableReason };
+
 export interface PostMortemStageChatDeps {
   readonly registry: StageControlRegistry;
   readonly adapters?: StageAdapters;
@@ -82,7 +88,7 @@ export function ensurePostMortemStageHandle(
   deps: PostMortemStageChatDeps,
 ): EnsurePostMortemStageHandleResult {
   if (!TERMINAL_POSTMORTEM_STATUSES.has(stage.status)) return { ok: false, reason: "not_terminal" };
-  const existing = deps.registry.get(runId, stage.id);
+  const existing = deps.registry.claim(runId, stage.id);
   if (existing !== undefined && existing.isDisposed !== true) {
     return { ok: true, handle: existing };
   }
@@ -98,6 +104,31 @@ export function ensurePostMortemStageHandle(
   return { ok: true, handle };
 }
 
+/** Acquire a tentative detached handle for programmatic message admission. */
+export function acquirePostMortemStageHandle(
+  runId: string,
+  stage: StageSnapshot,
+  deps: PostMortemStageChatDeps,
+): AcquirePostMortemStageHandleResult {
+  if (!TERMINAL_POSTMORTEM_STATUSES.has(stage.status)) return { ok: false, reason: "not_terminal" };
+  const existing = deps.registry.peek(runId, stage.id);
+  if (existing !== undefined && existing.isDisposed !== true) {
+    return {
+      ok: true,
+      lease: deps.registry.acquireDetached(runId, stage.id, () => 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 lease = deps.registry.acquireDetached(runId, stage.id, () =>
+    createPostMortemStageHandle(runId, stage, sessionFile, adapters, deps.cwd, deps.defaultSessionDir)
+  );
+  return { ok: true, lease };
+}
+
 /**
  * Build a lazy session-only stage-control handle that reopens `sessionFile` on
  * first use and appends follow-up conversation without dispatching the
@@ -123,10 +154,18 @@ export function createPostMortemStageHandle(
     ...(defaultSessionDir !== undefined ? { defaultSessionDir } : {}),
   });
   let disposed = false;
-  const ensureAttached = async (): Promise<void> => {
+  const throwIfClosed = (): void => {
     if (disposed) throw new Error(`Post-mortem stage chat "${stage.name}" is closed.`);
-    if (context.__sessionMeta().sessionFile === undefined) {
-      await context.__ensureSessionFromFile(sessionFile);
+  };
+  const messagePreparation = (): StageUserMessagePreparation => ({
+    ...(context.__sessionMeta().sessionFile === undefined ? { sessionFile } : {}),
+    beforePreparation: throwIfClosed,
+  });
+  const ensureAttached = async (): Promise<void> => {
+    throwIfClosed();
+    const sessionFileToRestore = messagePreparation().sessionFile;
+    if (sessionFileToRestore !== undefined) {
+      await context.__ensureSessionFromFile(sessionFileToRestore);
     }
   };
   return {
@@ -141,6 +180,15 @@ export function createPostMortemStageHandle(
     get messages() { return context.messages; },
     get agentSession() { return context.__agentSession(); },
     async ensureAttached() { await ensureAttached(); },
+    async sendUserMessage(text, options, beforeDelivery) {
+      throwIfClosed();
+      const preparation = messagePreparation();
+      const admitDelivery = (): void => {
+        throwIfClosed();
+        beforeDelivery?.();
+      };
+      return context.__sendUserMessage(text, options, admitDelivery, preparation);
+    },
     async prompt(text: string) {
       await ensureAttached();
       await context.prompt(text);
@@ -160,6 +208,7 @@ export function createPostMortemStageHandle(
       throw new Error("Post-mortem stage chat cannot pause or resume workflow execution.");
     },
     subscribe(listener: AgentSessionEventListener) { return context.subscribe(listener); },
+    subscribeDeliveryActivity(listener) { return context.__subscribeDeliveryActivity(listener); },
     async dispose() {
       if (disposed) return;
       disposed = true;

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

@@ -26,6 +26,7 @@
  */
 
 import type { AgentSession, AgentSessionEvent } from "@bastani/atomic";
+import type { StageDeliveryActivityEvent } from "./stage-delivery-activity.js";
 import type { StageUserMessageDeliveryAction } from "./stage-runner-types.js";
 
 export type StageControlStatus =
@@ -64,10 +65,15 @@ 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. */
+  /**
+   * Deliver through the idle-aware session primitive and report the action.
+   * `beforeDelivery` must run synchronously after async setup and immediately
+   * before the underlying SDK admits or queues the message.
+   */
   sendUserMessage?(
     text: string,
     options?: { readonly deliverAs?: "steer" | "followUp" },
+    beforeDelivery?: () => void,
   ): Promise<StageUserMessageDeliveryAction>;
 
   /** Send a prompt. Use only when the stage is idle / not streaming. */
@@ -84,19 +90,37 @@ export interface StageControlHandle {
   pause(): Promise<void>;
   /**
    * Release a paused stage. If `message` is provided it is sent as the
-   * next user message before resuming.
+   * next user message before resuming. `beforeResume` guards final admission.
    */
-  resume(message?: string): Promise<void | StageUserMessageDeliveryAction>;
+  resume(message?: string, beforeResume?: () => void): Promise<void | StageUserMessageDeliveryAction>;
   /**
    * Subscribe to AgentSession events. The pending-listener semantics
    * from `InternalStageContext.subscribe` apply: listeners registered
    * before the session exists are buffered and bound on first attach.
    */
   subscribe(listener: AgentSessionEventListener): () => void;
+  /**
+   * Subscribe to workflow-owned delivery lifecycle facts. Present only for
+   * handles backed by a live stage runner. An accepted idle delivery reports
+   * `delivery_start` before the public `agent_start` is published, letting an
+   * attached chat show Working for the whole turn.
+   */
+  subscribeDeliveryActivity?(
+    listener: (event: StageDeliveryActivityEvent) => void,
+  ): () => void;
   /** Release the underlying SDK session and unregister this direct chat handle. */
   dispose?(): void | Promise<void>;
 }
 
+/** Tentative ownership used by workflow sends until final message admission. */
+export interface DetachedStageHandleLease {
+  readonly handle: StageControlHandle;
+  /** Keep the handle registered after admission; false when it was displaced. */
+  commit(): boolean;
+  /** Release tentative ownership and dispose an unclaimed provisional handle. */
+  release(): Promise<void>;
+}
+
 /**
  * Per-run aggregate. Fans pause/resume to currently-running stage
  * handles. Backed by the same `StageControlRegistry`.
@@ -142,12 +166,26 @@ export interface StageControlRegistry {
     stageId: string,
     create: () => StageControlHandle,
   ): StageControlHandle;
+  /**
+   * Acquire tentative ownership of a detached handle. A newly-created handle
+   * stays provisional until one lease commits or an ordinary consumer claims
+   * it through `claim()` / `getOrCreateDetached()`.
+   */
+  acquireDetached(
+    runId: string,
+    stageId: string,
+    create: () => StageControlHandle,
+  ): DetachedStageHandleLease;
+  /** Inspect without claiming a provisional detached handle. */
+  peek(runId: string, stageId: string): StageControlHandle | undefined;
+  /** Resolve and permanently claim a provisional detached handle. */
+  claim(runId: string, stageId: string): StageControlHandle | undefined;
   /**
    * Remove this stage from run-level pause/resume aggregates while keeping
    * `get()` chat attachment live until the registration disposer runs.
    */
   detachControl(runId: string, stageId: string, handle?: StageControlHandle): boolean;
-  /** Resolve a single stage handle by run + stage id, including detached chats. */
+  /** Resolve one stage handle by run + stage id, including detached chats. */
   get(runId: string, stageId: string): StageControlHandle | undefined;
   /** Resolve all currently-registered chat handles for a run. */
   forRun(runId: string): readonly StageControlHandle[];
@@ -169,6 +207,9 @@ export function createStageControlRegistry(): StageControlRegistry {
   type RegistryEntry = {
     handle: StageControlHandle;
     controlsDependencies: boolean;
+    permanent: boolean;
+    readonly leases: Set<symbol>;
+    disposal?: Promise<void>;
   };
 
   const _byRun = new Map<string, Map<string, RegistryEntry>>();
@@ -188,6 +229,20 @@ export function createStageControlRegistry(): StageControlRegistry {
     return [...runMap.values()].filter((entry) => entry.controlsDependencies);
   }
 
+  function disposeEntry(entry: RegistryEntry): Promise<void> {
+    if (entry.disposal !== undefined) return entry.disposal;
+    try {
+      entry.disposal = Promise.resolve(entry.handle.dispose?.());
+    } catch (error) {
+      entry.disposal = Promise.reject(error);
+    }
+    return entry.disposal;
+  }
+
+  function disposeEntryInBackground(entry: RegistryEntry, message: string): void {
+    void disposeEntry(entry).catch((err: unknown) => console.warn(message, err));
+  }
+
   function makeRunHandle(runId: string): WorkflowRunControlHandle {
     return {
       runId,
@@ -261,7 +316,19 @@ export function createStageControlRegistry(): StageControlRegistry {
   return {
     register(handle: StageControlHandle): () => void {
       const runMap = ensureRun(handle.runId);
-      runMap.set(handle.stageId, { handle, controlsDependencies: true });
+      const displaced = runMap.get(handle.stageId);
+      runMap.set(handle.stageId, {
+        handle,
+        controlsDependencies: true,
+        permanent: true,
+        leases: new Set(),
+      });
+      if (displaced !== undefined && displaced.handle !== handle && !displaced.permanent) {
+        disposeEntryInBackground(
+          displaced,
+          "atomic-workflows: displaced provisional stage handle dispose failed",
+        );
+      }
       return () => {
         const existing = _byRun.get(handle.runId);
         if (!existing) return;
@@ -278,17 +345,75 @@ export function createStageControlRegistry(): StageControlRegistry {
     ): StageControlHandle {
       const runMap = ensureRun(runId);
       const existing = runMap.get(stageId);
-      if (existing !== undefined && existing.handle.isDisposed !== true) return existing.handle;
+      if (existing !== undefined && existing.handle.isDisposed !== true) {
+        existing.permanent = 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);
-        });
+        disposeEntryInBackground(existing, "atomic-workflows: stale stage handle dispose failed");
       }
       const handle = create();
-      runMap.set(handle.stageId, { handle, controlsDependencies: false });
+      runMap.set(handle.stageId, {
+        handle,
+        controlsDependencies: false,
+        permanent: true,
+        leases: new Set(),
+      });
       return handle;
     },
+    acquireDetached(
+      runId: string,
+      stageId: string,
+      create: () => StageControlHandle,
+    ): DetachedStageHandleLease {
+      const runMap = ensureRun(runId);
+      let entry = runMap.get(stageId);
+      if (entry?.handle.isDisposed === true) {
+        runMap.delete(stageId);
+        disposeEntryInBackground(entry, "atomic-workflows: stale stage handle dispose failed");
+        entry = undefined;
+      }
+      if (entry === undefined) {
+        entry = {
+          handle: create(),
+          controlsDependencies: false,
+          permanent: false,
+          leases: new Set(),
+        };
+        runMap.set(stageId, entry);
+      }
+      const leasedEntry = entry;
+      const token = Symbol("detached-stage-handle-lease");
+      leasedEntry.leases.add(token);
+      let settled = false;
+      return {
+        handle: leasedEntry.handle,
+        commit() {
+          if (settled) return false;
+          if (runMap.get(stageId) !== leasedEntry || leasedEntry.disposal !== undefined) {
+            return false;
+          }
+          settled = true;
+          leasedEntry.leases.delete(token);
+          leasedEntry.permanent = true;
+          return true;
+        },
+        async release() {
+          if (settled) return;
+          settled = true;
+          leasedEntry.leases.delete(token);
+          if (runMap.get(stageId) !== leasedEntry) {
+            if (leasedEntry.disposal !== undefined) await leasedEntry.disposal;
+            return;
+          }
+          if (leasedEntry.permanent || leasedEntry.leases.size > 0) return;
+          runMap.delete(stageId);
+          if (runMap.size === 0) _byRun.delete(runId);
+          await disposeEntry(leasedEntry);
+        },
+      };
+    },
     detachControl(runId: string, stageId: string, handle?: StageControlHandle): boolean {
       const entry = _byRun.get(runId)?.get(stageId);
       if (!entry) return false;
@@ -297,6 +422,14 @@ export function createStageControlRegistry(): StageControlRegistry {
       entry.controlsDependencies = false;
       return true;
     },
+    peek(runId: string, stageId: string): StageControlHandle | undefined {
+      return _byRun.get(runId)?.get(stageId)?.handle;
+    },
+    claim(runId: string, stageId: string): StageControlHandle | undefined {
+      const entry = _byRun.get(runId)?.get(stageId);
+      if (entry !== undefined) entry.permanent = true;
+      return entry?.handle;
+    },
     get(runId: string, stageId: string): StageControlHandle | undefined {
       return _byRun.get(runId)?.get(stageId)?.handle;
     },
@@ -309,14 +442,10 @@ export function createStageControlRegistry(): StageControlRegistry {
       return makeRunHandle(runId);
     },
     clear(): void {
-      const handles = [..._byRun.values()].flatMap((runMap) =>
-        [...runMap.values()].map((entry) => entry.handle),
-      );
+      const entries = [..._byRun.values()].flatMap((runMap) => [...runMap.values()]);
       _byRun.clear();
-      for (const handle of handles) {
-        void Promise.resolve(handle.dispose?.()).catch((err: unknown) => {
-          console.warn("atomic-workflows: stage handle dispose failed", err);
-        });
+      for (const entry of entries) {
+        disposeEntryInBackground(entry, "atomic-workflows: stage handle dispose failed");
       }
     },
   };

package/dist/builtin/workflows/src/runs/foreground/stage-delivery-activity.ts

@@ -0,0 +1,86 @@
+/**
+ * Internal stage delivery-activity channel.
+ *
+ * An accepted *idle* stage delivery starts a real backend turn long before the
+ * public `agent_start` clears the session's ordered extension event queue. The
+ * attached stage chat therefore had no signal to paint `Working` with, and the
+ * pane looked idle while the model was already running.
+ *
+ * This channel carries only that fact — "an idle delivery was admitted and is
+ * now starting a turn" — as a workflow-internal event, so the chat can start
+ * its existing Working lifecycle without fabricating SDK lifecycle events or
+ * reordering the public event stream.
+ *
+ * Streaming deliveries (`steer` / `followUp`) never emit here: they join an
+ * in-flight turn that already owns the indicator.
+ *
+ * cross-ref:
+ *   - src/runs/foreground/stage-runner-send-user-message.ts (emitter)
+ *   - src/tui/stage-chat-view-delivery-activity.ts (consumer)
+ */
+
+export type StageDeliveryActivityEvent =
+  | { readonly type: "delivery_start"; readonly deliveryId: number }
+  | { readonly type: "delivery_settled"; readonly deliveryId: number };
+
+export type StageDeliveryActivityListener = (event: StageDeliveryActivityEvent) => void;
+
+export class StageDeliveryActivity {
+  private readonly listeners = new Set<StageDeliveryActivityListener>();
+  private readonly active = new Set<number>();
+  private nextDeliveryId = 0;
+
+  /**
+   * Register `listener`, then synchronously replay every currently-active
+   * delivery as `delivery_start`.
+   *
+   * A stage chat can attach after a delivery was admitted — a late `/workflow
+   * attach`, or a remount — and would otherwise see nothing until the public
+   * `agent_start` finally arrives. Registering before replaying matters:
+   * snapshotting first would drop a start or settlement that lands in between.
+   */
+  subscribe(listener: StageDeliveryActivityListener): () => void {
+    this.listeners.add(listener);
+    for (const deliveryId of [...this.active]) {
+      if (!this.listeners.has(listener)) break;
+      listener({ type: "delivery_start", deliveryId });
+    }
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  /** Report an admitted idle delivery that is about to start a turn. */
+  start(): number {
+    const deliveryId = ++this.nextDeliveryId;
+    this.active.add(deliveryId);
+    this.emit({ type: "delivery_start", deliveryId });
+    return deliveryId;
+  }
+
+  /** Keep one correlated delivery active for the full asynchronous operation. */
+  async runWithLease<T>(operation: () => Promise<T>): Promise<T> {
+    const deliveryId = this.start();
+    try {
+      return await operation();
+    } finally {
+      this.settle(deliveryId);
+    }
+  }
+
+  /** Report that a delivery finished, failed, or started no turn at all. */
+  settle(deliveryId: number | undefined): void {
+    if (deliveryId === undefined || !this.active.delete(deliveryId)) return;
+    this.emit({ type: "delivery_settled", deliveryId });
+  }
+
+  /** Settle every outstanding delivery, then drop listeners. */
+  dispose(): void {
+    for (const deliveryId of [...this.active]) this.settle(deliveryId);
+    this.listeners.clear();
+  }
+
+  private emit(event: StageDeliveryActivityEvent): void {
+    for (const listener of [...this.listeners]) listener(event);
+  }
+}

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

@@ -17,10 +17,18 @@ import {
 import type { InternalStageContext, StageRunnerOpts } from "./stage-runner-types.js";
 
 export function createStageContext(opts: StageRunnerOpts): InternalStageContext {
-  const { stageId, stageName, adapters, runId, signal, stageOptions, executionMode } = opts;
+  const { stageId, stageName, adapters, runId, workflowIntercomGroup, signal, stageOptions, executionMode } = opts;
   const structuredOutputCapture = stageOptions?.schema ? createStructuredOutputCapture<unknown>() : undefined;
   const effectiveStageOptions = stageOptionsWithStructuredOutput(stageOptions, structuredOutputCapture);
-  const meta: StageExecutionMeta = { runId, stageId, stageName, signal, stageOptions: effectiveStageOptions, executionMode };
+  const meta: StageExecutionMeta = {
+    runId,
+    stageId,
+    stageName,
+    ...(workflowIntercomGroup === undefined ? {} : { workflowIntercomGroup }),
+    signal,
+    stageOptions: effectiveStageOptions,
+    executionMode,
+  };
   const controller = new StageSessionController(opts, meta, effectiveStageOptions, structuredOutputCapture);
   let lastAssistantText: string | undefined;
   let adapterMessages = [] as InternalStageContext["messages"];
@@ -102,8 +110,8 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
       await controller.sendUserMessage(text, options);
     },
 
-    async __sendUserMessage(text, options, beforeDelivery) {
-      return controller.sendUserMessage(text, options, beforeDelivery);
+    async __sendUserMessage(text, options, beforeDelivery, preparation) {
+      return controller.sendUserMessage(text, options, beforeDelivery, preparation);
     },
 
     async steer(text) {
@@ -118,6 +126,10 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
       return controller.subscribe(listener);
     },
 
+    __subscribeDeliveryActivity(listener) {
+      return controller.subscribeDeliveryActivity(listener);
+    },
+
     get sessionFile() {
       return controller.currentSession?.sessionFile;
     },
@@ -226,8 +238,8 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
       await controller.requestPause();
     },
 
-    async __resume(message?: string) {
-      controller.resume(message);
+    async __resume(message, beforeResolve, beforeRelease) {
+      return controller.resume(message, beforeResolve, beforeRelease);
     },
 
     __isPaused() {

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

@@ -9,13 +9,12 @@ import { structuredOutputToolErrorFromEvent } from "./stage-runner-structured-ou
 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 { StageDeliveryActivity, type StageDeliveryActivityListener } from "./stage-delivery-activity.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 type { AgentSessionConsumer, StageModelFallbackMeta, StageRunnerOpts, StageSessionCreateOptions, StageSessionCreateResult, StageSessionEvent, StageSessionRuntime, StageUserMessagePreparation, WorkflowFastModeSettingsManager } from "./stage-runner-types.js";
 import { StageSessionReplacement } from "./stage-runner-replacement.js";
+import { StageSessionPause, type StageSessionPauseResumeResult } from "./stage-runner-pause.js";
 
-type PauseRequest = {
-  deferred: PromiseWithResolvers<{ message?: string }>;
-};
 
 export class StageSessionController {
   private session: StageSessionRuntime | undefined;
@@ -31,7 +30,7 @@ export class StageSessionController {
   private pendingThinkingLevel: Parameters<StageContext["setThinkingLevel"]>[0] | undefined;
   private readonly pendingListeners = new Set<(event: StageSessionEvent) => void>();
   private readonly listenerUnsubscribes = new Map<(event: StageSessionEvent) => void, () => void>();
-  private pauseRequest: PauseRequest | null = null;
+  private readonly pauseControl = new StageSessionPause(() => this.session);
   private readonly hasExplicitModelFallbackConfig: boolean;
   private candidatesPromise: Promise<WorkflowResolvedModelCandidate[]> | undefined;
   private activeCandidateIndex: number | undefined;
@@ -46,6 +45,7 @@ export class StageSessionController {
   private sessionSettingsManager: WorkflowFastModeSettingsManager | undefined;
   private readonly replacement = new StageSessionReplacement();
   private readonly messageAdmission = new StageMessageAdmission();
+  private readonly deliveryActivity = new StageDeliveryActivity();
 
   constructor(
     private readonly opts: StageRunnerOpts,
@@ -108,12 +108,25 @@ export class StageSessionController {
     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,
+    beforeDelivery?: () => void, preparation?: StageUserMessagePreparation): Promise<Awaited<ReturnType<typeof sendStageUserMessage>>> {
+    return this.messageAdmission.run(async (release) => {
+      const pausedDelivery = this.pauseControl.deferRunnerOwnedDelivery(() =>
+        this.sendUserMessage(content, options, beforeDelivery, preparation));
+      if (pausedDelivery !== undefined) { release(); return pausedDelivery; }
+      preparation?.beforePreparation?.();
+      const sessionFile = preparation?.sessionFile;
+      const deliver = async (activity?: StageDeliveryActivity) => sendStageUserMessage(
+        sessionFile === undefined ? await this.ensureSession("prompt")
+          : await this.ensureSessionFromFile(sessionFile, "prompt"),
+        content, options, beforeDelivery, release, this.messageAdmission, activity,
+      );
+      if (this.session === undefined || sessionFile !== undefined) return this.deliveryActivity.runWithLease(() => deliver());
+      return deliver(this.deliveryActivity);
+    });
   }
+  /** Internal pre-stream delivery lifecycle consumed by an attached stage chat. */
+  subscribeDeliveryActivity(listener: StageDeliveryActivityListener): () => void { return this.deliveryActivity.subscribe(listener); }
 
   sealGeneration(): void {
     this.generationSealed = true;
@@ -194,37 +207,23 @@ export class StageSessionController {
     this.pendingListeners.clear();
     this.unsubscribeTerminateWatcher?.();
     this.unsubscribeTerminateWatcher = undefined;
-    this.terminatingToolCallIds.clear(); this.messageAdmission.dispose();
+    this.terminatingToolCallIds.clear(); this.messageAdmission.dispose(); this.deliveryActivity.dispose();
     await this.replacement.dispose();
     await disposeStageSession(this.session);
   }
-
-  async requestPause(): Promise<void> {
-    if (this.pauseRequest) return;
-    const deferred = Promise.withResolvers<{ message?: string }>();
-    void deferred.promise.catch(() => {});
-    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 {
-    const req = this.pauseRequest;
-    if (!req) return;
-    this.pauseRequest = null;
-    req.deferred.resolve({ message });
+  requestPause(): Promise<void> { return this.pauseControl.requestPause(); }
+  resume(
+    message?: string,
+    beforeResolve?: (result: StageSessionPauseResumeResult) => void,
+    beforeRelease?: () => void,
+  ): Promise<StageSessionPauseResumeResult> {
+    return this.pauseControl.resume(message, beforeResolve, beforeRelease);
   }
-
-  isPaused(): boolean { return this.pauseRequest !== null; }
+  isPaused(): boolean { return this.pauseControl.isPaused(); }
   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; }
 
   private bindAbortSignal(): void {
@@ -237,10 +236,7 @@ export class StageSessionController {
     };
     const onAbort = (): void => {
       void this.session?.abort().catch(() => {});
-      if (!this.pauseRequest) return;
-      const req = this.pauseRequest;
-      this.pauseRequest = null;
-      req.deferred.reject(abortReason());
+      this.pauseControl.reject(abortReason());
     };
     if (signal.aborted) onAbort();
     else signal.addEventListener("abort", onAbort, { once: true });
@@ -370,10 +366,11 @@ export class StageSessionController {
   ): Promise<{ readonly terminalScanStartIndex: number }> {
     let nextText: string | undefined = initialText;
     while (nextText !== undefined) {
-      const pendingPauseBeforePrompt = this.pauseRequest;
+      const pendingPauseBeforePrompt = this.pauseControl.currentResume();
       if (pendingPauseBeforePrompt) {
-        const { message } = await pendingPauseBeforePrompt.deferred.promise;
-        nextText = message;
+        const resumed = await pendingPauseBeforePrompt;
+        await resumed.runnerOwnedDeliverySettlement;
+        nextText = resumed.message;
         if (nextText === undefined) return { terminalScanStartIndex: activeSession.messages.length };
         continue;
       }
@@ -381,22 +378,24 @@ export class StageSessionController {
       this.unresolvedContextOverflowMessage = undefined;
       try {
         await activeSession.prompt(nextText, sdkOptions);
-        const pendingPauseAfterPrompt = this.pauseRequest;
+        const pendingPauseAfterPrompt = this.pauseControl.currentResume();
         if (pendingPauseAfterPrompt) {
-          const { message } = await pendingPauseAfterPrompt.deferred.promise;
+          const resumed = await pendingPauseAfterPrompt;
+          await resumed.runnerOwnedDeliverySettlement;
           this.throwUnresolvedContextOverflowIfPresent();
-          nextText = message;
+          nextText = resumed.message;
           if (nextText === undefined) return { terminalScanStartIndex: activeSession.messages.length };
           continue;
         }
         this.throwUnresolvedContextOverflowIfPresent();
         return { terminalScanStartIndex: promptStartIndex };
       } catch (err) {
-        const pendingPauseAfterThrow = this.pauseRequest;
+        const pendingPauseAfterThrow = this.pauseControl.currentResume();
         if (pendingPauseAfterThrow) {
-          const { message } = await pendingPauseAfterThrow.deferred.promise;
+          const resumed = await pendingPauseAfterThrow;
+          await resumed.runnerOwnedDeliverySettlement;
           this.throwUnresolvedContextOverflowIfPresent();
-          nextText = message;
+          nextText = resumed.message;
           if (nextText === undefined) return { terminalScanStartIndex: activeSession.messages.length };
           continue;
         }