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

package/dist/builtin/workflows/skills/impeccable/scripts/surface-brief.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { resolveProjectRoot } from './context.mjs';
+import {
+  listSurfaceBriefs,
+  resolveSurfaceBrief,
+  surfaceBriefPathForTarget,
+  writeSurfaceBrief,
+} from './lib/surface-briefs.mjs';
+
+function summary(brief, projectRoot) {
+  return {
+    slug: brief.slug,
+    path: path.relative(projectRoot, brief.path).split(path.sep).join('/'),
+    primaryTarget: brief.primaryTarget,
+    relatedTargets: brief.relatedTargets,
+  };
+}
+
+function main(argv) {
+  const [command, target, bodyFile, ...relatedTargets] = argv;
+  const projectRoot = resolveProjectRoot(process.cwd(), target ? { targetPath: target } : {});
+  if (command === 'path') {
+    const filePath = surfaceBriefPathForTarget(target, { projectRoot });
+    if (!filePath) throw new Error('surface brief path requires a concrete target');
+    process.stdout.write(`${path.relative(process.cwd(), filePath) || filePath}\n`);
+    return;
+  }
+  if (command === 'list') {
+    process.stdout.write(`${JSON.stringify(listSurfaceBriefs(projectRoot).map((brief) => summary(brief, projectRoot)), null, 2)}\n`);
+    return;
+  }
+  if (command === 'read') {
+    const result = resolveSurfaceBrief(projectRoot, target || null);
+    if (result.brief) {
+      process.stdout.write(result.brief.text);
+      return;
+    }
+    if (result.candidates.length) process.stderr.write(`${JSON.stringify(result.candidates.map((brief) => summary(brief, projectRoot)), null, 2)}\n`);
+    process.exit(2);
+  }
+  if (command === 'write') {
+    if (!target || !bodyFile) throw new Error('usage: surface-brief.mjs write <primary-target> <body-file>');
+    const filePath = writeSurfaceBrief({
+      projectRoot,
+      primaryTarget: target,
+      relatedTargets,
+      body: fs.readFileSync(bodyFile, 'utf-8'),
+    });
+    process.stdout.write(`${path.relative(process.cwd(), filePath) || filePath}\n`);
+    return;
+  }
+  throw new Error('usage: surface-brief.mjs <path|list|read|write> [target] [body-file] [related-target ...]');
+}
+
+function isMainModule() {
+  if (!process.argv[1]) return false;
+  try {
+    return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(process.argv[1]);
+  } catch {
+    return import.meta.url === pathToFileURL(process.argv[1]).href;
+  }
+}
+
+if (isMainModule()) {
+  try {
+    main(process.argv.slice(2));
+  } catch (error) {
+    process.stderr.write(`${error?.message || error}\n`);
+    process.exit(1);
+  }
+}

package/dist/builtin/workflows/src/extension/index.bundle.mjs

@@ -41452,16 +41452,95 @@ function isTerminalStageChatState(status) {
   return isTerminalOrNonStreamingStageChatStatus(status);
 }
 
+// dist/builtin/workflows/src/tui/stage-chat-view-delivery-activity.ts
+function subscribeStageChatDeliveryActivity(ctx) {
+  const handle = ctx.handle;
+  if (!handle?.subscribeDeliveryActivity)
+    return null;
+  return handle.subscribeDeliveryActivity((event) => {
+    applyStageChatDeliveryActivityEvent(ctx, event);
+  });
+}
+function applyStageChatDeliveryActivityEvent(ctx, event) {
+  if (event.type === "delivery_start") {
+    ctx.terminalLifecycleFenced = false;
+    ctx.deliveryLifecycles.set(event.deliveryId, ctx.chatHost.beginExternalPromptLifecycle());
+    return;
+  }
+  if (!ctx.deliveryLifecycles.has(event.deliveryId))
+    return;
+  const generation = ctx.deliveryLifecycles.get(event.deliveryId);
+  ctx.deliveryLifecycles.delete(event.deliveryId);
+  if (!ownsStageChatLifecycleGeneration(ctx, generation)) {
+    ctx.chatHost.settleExternalPromptLifecycle(generation);
+  }
+  if (!hasActiveStageChatDelivery(ctx) && isStageChatContextTerminal(ctx)) {
+    ctx.terminalLifecycleFenced = true;
+  }
+}
+function ownsStageChatLifecycleGeneration(ctx, generation) {
+  for (const active of ctx.deliveryLifecycles.values()) {
+    if (active === generation)
+      return true;
+  }
+  return false;
+}
+function hasActiveStageChatDelivery(ctx) {
+  return ctx.deliveryLifecycles.size > 0;
+}
+function isStageChatContextTerminal(ctx) {
+  return isTerminalStageChatState(ctx.lastObservedRunStatus) || isTerminalStageChatState(ctx.lastObservedStageStatus);
+}
+function reconcileStageChatDeliveryLifecycle(ctx) {
+  if (!hasActiveStageChatDelivery(ctx))
+    return;
+  if (ctx.chatHost.isStreaming() && ctx.chatHost.hasAnimationTick())
+    return;
+  const generation = ctx.chatHost.reassertExternalPromptLifecycle();
+  for (const deliveryId of [...ctx.deliveryLifecycles.keys()]) {
+    ctx.deliveryLifecycles.set(deliveryId, generation);
+  }
+}
+function invalidateStageChatDeliveryLifecycles(ctx) {
+  ctx.deliveryLifecycles.clear();
+  ctx.terminalLifecycleFenced = true;
+}
+
 // dist/builtin/workflows/src/tui/stage-chat-view-live-events.ts
 function applyStageChatLiveHandleEvent(ctx, event) {
+  const staleTerminalStart = isStaleTerminalLifecycleStart(ctx, event);
   ctx.chatHost.applyAgentEvent(event);
+  if (staleTerminalStart) {
+    retainTerminalCleanup(ctx);
+    return;
+  }
+  if (isCompactionEndEvent(event))
+    reconcileStageChatDeliveryLifecycle(ctx);
   if (!shouldCleanupAfterLiveEvent(ctx, event))
     return;
+  retainTerminalCleanup(ctx);
+}
+function retainTerminalCleanup(ctx) {
   const hadAnimationTick = ctx.chatHost.hasAnimationTick();
   ctx.chatHost.clearBusyForTerminalWorkflowStage();
   if (hadAnimationTick !== ctx.chatHost.hasAnimationTick())
     ctx.requestRender?.();
 }
+function isStaleTerminalLifecycleStart(ctx, event) {
+  if (!ctx.terminalLifecycleFenced)
+    return false;
+  const type = String(event.type ?? "");
+  if (type !== "agent_start" && type !== "turn_start")
+    return false;
+  if (hasActiveStageChatDelivery(ctx))
+    return false;
+  if (ctx.chatHost.isStreaming())
+    return false;
+  return isCurrentRunOrStageTerminal(ctx);
+}
+function isCompactionEndEvent(event) {
+  return String(event.type ?? "") === "compaction_end";
+}
 function shouldCleanupAfterLiveEvent(ctx, event) {
   if (!isToolExecutionLiveEvent(event))
     return false;
@@ -41550,8 +41629,11 @@ function initializeStageChatView(ctx, opts) {
   ctx.lastObservedStageStatus = undefined;
   ctx.lastObservedRunStatus = undefined;
   ctx.seenNoticeIds = new Set;
+  ctx.deliveryLifecycles = new Map;
+  ctx.terminalLifecycleFenced = false;
   ctx._unsubscribeStore = null;
   ctx._unsubscribeHandle = null;
+  ctx._unsubscribeDeliveryActivity = null;
   ctx._unsubscribeFooterData = null;
   ctx._unregisterStageUiHost = null;
   installFocusHold(ctx);
@@ -41581,6 +41663,7 @@ function initializeStageChatView(ctx, opts) {
   ctx._unsubscribeStore = ctx.store.subscribe(() => handleStoreUpdate(ctx));
   ctx._unsubscribeFooterData = ctx.footerData?.onBranchChange(() => ctx.requestRender?.()) ?? null;
   if (ctx.handle) {
+    ctx._unsubscribeDeliveryActivity = subscribeStageChatDeliveryActivity(ctx);
     ctx._unsubscribeHandle = ctx.handle.subscribe((event) => applyStageChatLiveHandleEvent(ctx, event));
   }
   ctx.chatHost.syncAnimationTick();
@@ -41693,6 +41776,7 @@ function handleStoreUpdate(ctx) {
   }
   if (isTerminalStageChatTransition(ctx.lastObservedStageStatus, currentStageStatus) || isTerminalStageChatTransition(ctx.lastObservedRunStatus, currentRunStatus)) {
     ctx.chatHost.clearBusyForTerminalWorkflowStage();
+    invalidateStageChatDeliveryLifecycles(ctx);
     changed = true;
   }
   ctx.lastObservedRunStatus = currentRunStatus;
@@ -41918,6 +42002,9 @@ function disposeStageChatView(ctx) {
   ctx._unsubscribeStore = null;
   ctx._unsubscribeHandle?.();
   ctx._unsubscribeHandle = null;
+  ctx._unsubscribeDeliveryActivity?.();
+  ctx._unsubscribeDeliveryActivity = null;
+  ctx.deliveryLifecycles.clear();
   ctx._unsubscribeFooterData?.();
   ctx._unsubscribeFooterData = null;
   releaseMountedCustomUi(ctx);
@@ -48600,7 +48687,7 @@ function coordinatedPromptOwnershipObserver(turn) {
 function unsupportedContentError() {
   return new Error("atomic-workflows: this stage session adapter does not support non-string sendUserMessage content; provide a runtime sendUserMessage implementation for text/image blocks.");
 }
-async function sendStageUserMessage(activeSession, content, options, beforeDelivery, promptStarted, admission) {
+async function sendStageUserMessage(activeSession, content, options, beforeDelivery, promptStarted, admission, activity) {
   const streaming = activeSession.isStreaming || admission?.isOwned(activeSession) === true;
   const deliverAs = streaming ? options?.deliverAs ?? "followUp" : options?.deliverAs;
   if (activeSession.sendUserMessage !== undefined) {
@@ -48608,6 +48695,7 @@ async function sendStageUserMessage(activeSession, content, options, beforeDeliv
     let reportedAction;
     const ownership2 = streaming ? undefined : admission === undefined ? createLocalPromptOwnershipObserver(activeSession, promptStarted) : coordinatedPromptOwnershipObserver(admission.startTurn(activeSession, promptStarted ?? (() => {})));
     ownership2?.arm();
+    const deliveryId2 = streaming ? undefined : activity?.start();
     try {
       const delivery = activeSession.sendUserMessage(content, {
         ...deliverAs === undefined ? {} : { deliverAs },
@@ -48628,6 +48716,7 @@ async function sendStageUserMessage(activeSession, content, options, beforeDeliv
       throw error;
     } finally {
       ownership2?.dispose();
+      activity?.settle(deliveryId2);
     }
   }
   if (typeof content !== "string")
@@ -48642,6 +48731,7 @@ async function sendStageUserMessage(activeSession, content, options, beforeDeliv
   }
   const ownership = admission === undefined ? createLocalPromptOwnershipObserver(activeSession, promptStarted) : coordinatedPromptOwnershipObserver(admission.startTurn(activeSession, promptStarted ?? (() => {})));
   ownership.arm();
+  const deliveryId = activity?.start();
   try {
     const turn = activeSession.prompt(content);
     ownership.observeStreaming();
@@ -48653,6 +48743,7 @@ async function sendStageUserMessage(activeSession, content, options, beforeDeliv
     throw error;
   } finally {
     ownership.dispose();
+    activity?.settle(deliveryId);
   }
 }
 
@@ -48839,6 +48930,52 @@ class StageMessageAdmission {
   }
 }
 
+// dist/builtin/workflows/src/runs/foreground/stage-delivery-activity.ts
+class StageDeliveryActivity {
+  listeners = new Set;
+  active = new Set;
+  nextDeliveryId = 0;
+  subscribe(listener) {
+    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);
+    };
+  }
+  start() {
+    const deliveryId = ++this.nextDeliveryId;
+    this.active.add(deliveryId);
+    this.emit({ type: "delivery_start", deliveryId });
+    return deliveryId;
+  }
+  async runWithLease(operation) {
+    const deliveryId = this.start();
+    try {
+      return await operation();
+    } finally {
+      this.settle(deliveryId);
+    }
+  }
+  settle(deliveryId) {
+    if (deliveryId === undefined || !this.active.delete(deliveryId))
+      return;
+    this.emit({ type: "delivery_settled", deliveryId });
+  }
+  dispose() {
+    for (const deliveryId of [...this.active])
+      this.settle(deliveryId);
+    this.listeners.clear();
+  }
+  emit(event) {
+    for (const listener of [...this.listeners])
+      listener(event);
+  }
+}
+
 // dist/builtin/workflows/src/runs/foreground/stage-runner-unresolved-overflow.ts
 function unresolvedContextOverflowMessage(event) {
   if (event === null || typeof event !== "object")
@@ -49105,6 +49242,7 @@ class StageSessionController {
   sessionSettingsManager;
   replacement = new StageSessionReplacement;
   messageAdmission = new StageMessageAdmission;
+  deliveryActivity = new StageDeliveryActivity;
   constructor(opts, meta, effectiveStageOptions, structuredOutputCapture) {
     this.opts = opts;
     this.meta = meta;
@@ -49168,16 +49306,24 @@ class StageSessionController {
     await session.closeWorkflowStageGeneration?.();
     return session;
   }
-  async sendUserMessage(content, options, beforeDelivery) {
+  async sendUserMessage(content, options, beforeDelivery, preparation) {
     return this.messageAdmission.run(async (release) => {
-      const pausedDelivery = this.pauseControl.deferRunnerOwnedDelivery(() => this.sendUserMessage(content, options, beforeDelivery));
+      const pausedDelivery = this.pauseControl.deferRunnerOwnedDelivery(() => this.sendUserMessage(content, options, beforeDelivery, preparation));
       if (pausedDelivery !== undefined) {
         release();
         return pausedDelivery;
       }
-      return sendStageUserMessage(await this.ensureSession("prompt"), content, options, beforeDelivery, release, this.messageAdmission);
+      preparation?.beforePreparation?.();
+      const sessionFile = preparation?.sessionFile;
+      const deliver = async (activity) => 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);
     });
   }
+  subscribeDeliveryActivity(listener) {
+    return this.deliveryActivity.subscribe(listener);
+  }
   sealGeneration() {
     this.generationSealed = true;
     this.sharedOrchestrationContext?.messageAdmission?.boundary.seal();
@@ -49252,6 +49398,7 @@ class StageSessionController {
     this.unsubscribeTerminateWatcher = undefined;
     this.terminatingToolCallIds.clear();
     this.messageAdmission.dispose();
+    this.deliveryActivity.dispose();
     await this.replacement.dispose();
     await disposeStageSession(this.session);
   }
@@ -49739,8 +49886,8 @@ function createStageContext(opts) {
     async sendUserMessage(text, options) {
       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) {
       await (await controller.ensureSession()).steer(text);
@@ -49751,6 +49898,9 @@ function createStageContext(opts) {
     subscribe(listener) {
       return controller.subscribe(listener);
     },
+    __subscribeDeliveryActivity(listener) {
+      return controller.subscribeDeliveryActivity(listener);
+    },
     get sessionFile() {
       return controller.currentSession?.sessionFile;
     },
@@ -51274,6 +51424,7 @@ function createReplayStageContext(input) {
     steer: async () => rejectReplayMutation("steer"),
     followUp: async () => rejectReplayMutation("follow up"),
     subscribe: () => () => {},
+    __subscribeDeliveryActivity: () => () => {},
     get sessionFile() {
       return replaySource.sessionFile;
     },
@@ -51371,18 +51522,28 @@ class StageToolExecutionBuffer {
 
 // dist/builtin/workflows/src/runs/foreground/executor-stage-control.ts
 function createStageControlHandle(runtime) {
-  const ensureMessagingSession = async () => {
+  const messagePreparation = () => {
     const meta = runtime.innerCtx.__sessionMeta();
-    if (meta.sessionId !== undefined || meta.sessionFile !== undefined)
-      return;
+    if (meta.sessionId !== undefined || meta.sessionFile !== undefined) {
+      return { beforePreparation: runtime.throwIfStageMutationBlocked };
+    }
     if (runtime.stageSnapshot.sessionFile !== undefined) {
-      await runtime.innerCtx.__ensureSessionFromFile(runtime.stageSnapshot.sessionFile);
-      runtime.captureStageSessionMeta();
-      return;
+      return {
+        sessionFile: runtime.stageSnapshot.sessionFile,
+        beforePreparation: runtime.throwIfStageMutationBlocked
+      };
     }
     if (isTerminalStage(runtime.stageSnapshot)) {
       throw new Error(`atomic-workflows: cannot message stage "${runtime.name}" because no retained session metadata is available.`);
     }
+    return { beforePreparation: runtime.throwIfStageMutationBlocked };
+  };
+  const ensureMessagingSession = async () => {
+    const sessionFile = messagePreparation().sessionFile;
+    if (sessionFile === undefined)
+      return;
+    await runtime.innerCtx.__ensureSessionFromFile(sessionFile);
+    runtime.captureStageSessionMeta();
   };
   const toolExecutions = new StageToolExecutionBuffer;
   const unsubscribeToolExecutions = runtime.innerCtx.subscribe((event) => toolExecutions.record(event));
@@ -51423,14 +51584,13 @@ function createStageControlHandle(runtime) {
     },
     async sendUserMessage(text, options, beforeDelivery) {
       runtime.throwIfStageMutationBlocked();
-      await ensureMessagingSession();
-      runtime.throwIfStageMutationBlocked();
+      const preparation = messagePreparation();
       const admitDelivery = () => {
         runtime.throwIfStageMutationBlocked();
         beforeDelivery?.();
       };
       try {
-        const action = await runtime.innerCtx.__sendUserMessage(text, options, admitDelivery);
+        const action = await runtime.innerCtx.__sendUserMessage(text, options, admitDelivery, preparation);
         if (action === "steer" || action === "followUp") {
           runtime.state.resumeContinuationPending = "queued-user-message";
         }
@@ -51441,10 +51601,10 @@ function createStageControlHandle(runtime) {
     },
     async prompt(text) {
       runtime.throwIfStageMutationBlocked();
-      await ensureMessagingSession();
+      const preparation = messagePreparation();
       let action;
       try {
-        action = await runtime.innerCtx.__sendUserMessage(text, undefined, runtime.throwIfStageMutationBlocked);
+        action = await runtime.innerCtx.__sendUserMessage(text, undefined, runtime.throwIfStageMutationBlocked, preparation);
       } finally {
         runtime.captureStageSessionMeta();
       }
@@ -51540,6 +51700,9 @@ function createStageControlHandle(runtime) {
     subscribe(listener) {
       return runtime.innerCtx.subscribe(listener);
     },
+    subscribeDeliveryActivity(listener) {
+      return runtime.innerCtx.__subscribeDeliveryActivity(listener);
+    },
     async dispose() {
       unsubscribeToolExecutions();
       toolExecutions.clear();
@@ -61765,11 +61928,19 @@ function createPostMortemStageHandle(runId, stage, sessionFile, adapters, cwd, d
     ...defaultSessionDir !== undefined ? { defaultSessionDir } : {}
   });
   let disposed = false;
-  const ensureAttached = async () => {
+  const throwIfClosed = () => {
     if (disposed)
       throw new Error(`Post-mortem stage chat "${stage.name}" is closed.`);
-    if (context.__sessionMeta().sessionFile === undefined) {
-      await context.__ensureSessionFromFile(sessionFile);
+  };
+  const messagePreparation = () => ({
+    ...context.__sessionMeta().sessionFile === undefined ? { sessionFile } : {},
+    beforePreparation: throwIfClosed
+  });
+  const ensureAttached = async () => {
+    throwIfClosed();
+    const sessionFileToRestore = messagePreparation().sessionFile;
+    if (sessionFileToRestore !== undefined) {
+      await context.__ensureSessionFromFile(sessionFileToRestore);
     }
   };
   return {
@@ -61799,8 +61970,13 @@ function createPostMortemStageHandle(runId, stage, sessionFile, adapters, cwd, d
       await ensureAttached();
     },
     async sendUserMessage(text, options, beforeDelivery) {
-      await ensureAttached();
-      return context.__sendUserMessage(text, options, beforeDelivery);
+      throwIfClosed();
+      const preparation = messagePreparation();
+      const admitDelivery = () => {
+        throwIfClosed();
+        beforeDelivery?.();
+      };
+      return context.__sendUserMessage(text, options, admitDelivery, preparation);
     },
     async prompt(text) {
       await ensureAttached();
@@ -61823,6 +61999,9 @@ function createPostMortemStageHandle(runId, stage, sessionFile, adapters, cwd, d
     subscribe(listener) {
       return context.subscribe(listener);
     },
+    subscribeDeliveryActivity(listener) {
+      return context.__subscribeDeliveryActivity(listener);
+    },
     async dispose() {
       if (disposed)
         return;

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

@@ -1,21 +1,31 @@
 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 type { StageUserMessageDeliveryAction, StageUserMessagePreparation } from "./stage-runner-types.js";
 import { isTerminalStage } from "./executor-scheduler.js";
 import { StageToolExecutionBuffer } from "./stage-tool-execution-buffer.js";
 
 export function createStageControlHandle(runtime: LiveStageRuntime): StageControlHandle {
-  const ensureMessagingSession = async (): Promise<void> => {
+  const messagePreparation = (): StageUserMessagePreparation => {
     const meta = runtime.innerCtx.__sessionMeta();
-    if (meta.sessionId !== undefined || meta.sessionFile !== undefined) return;
+    if (meta.sessionId !== undefined || meta.sessionFile !== undefined) {
+      return { beforePreparation: runtime.throwIfStageMutationBlocked };
+    }
     if (runtime.stageSnapshot.sessionFile !== undefined) {
-      await runtime.innerCtx.__ensureSessionFromFile(runtime.stageSnapshot.sessionFile);
-      runtime.captureStageSessionMeta();
-      return;
+      return {
+        sessionFile: runtime.stageSnapshot.sessionFile,
+        beforePreparation: runtime.throwIfStageMutationBlocked,
+      };
     }
     if (isTerminalStage(runtime.stageSnapshot)) {
       throw new Error(`atomic-workflows: cannot message stage "${runtime.name}" because no retained session metadata is available.`);
     }
+    return { beforePreparation: runtime.throwIfStageMutationBlocked };
+  };
+  const ensureMessagingSession = async (): Promise<void> => {
+    const sessionFile = messagePreparation().sessionFile;
+    if (sessionFile === undefined) return;
+    await runtime.innerCtx.__ensureSessionFromFile(sessionFile);
+    runtime.captureStageSessionMeta();
   };
   const toolExecutions = new StageToolExecutionBuffer();
   const unsubscribeToolExecutions = runtime.innerCtx.subscribe((event) => toolExecutions.record(event));
@@ -57,8 +67,7 @@ export function createStageControlHandle(runtime: LiveStageRuntime): StageContro
     },
     async sendUserMessage(text, options, beforeDelivery) {
       runtime.throwIfStageMutationBlocked();
-      await ensureMessagingSession();
-      runtime.throwIfStageMutationBlocked();
+      const preparation = messagePreparation();
       const admitDelivery = (): void => {
         runtime.throwIfStageMutationBlocked();
         beforeDelivery?.();
@@ -68,6 +77,7 @@ export function createStageControlHandle(runtime: LiveStageRuntime): StageContro
           text,
           options,
           admitDelivery,
+          preparation,
         );
         if (action === "steer" || action === "followUp") {
           runtime.state.resumeContinuationPending = "queued-user-message";
@@ -79,13 +89,14 @@ export function createStageControlHandle(runtime: LiveStageRuntime): StageContro
     },
     async prompt(text: string) {
       runtime.throwIfStageMutationBlocked();
-      await ensureMessagingSession();
+      const preparation = messagePreparation();
       let action: StageUserMessageDeliveryAction | undefined;
       try {
         action = await runtime.innerCtx.__sendUserMessage(
           text,
           undefined,
           runtime.throwIfStageMutationBlocked,
+          preparation,
         );
       } finally {
         runtime.captureStageSessionMeta();
@@ -197,6 +208,9 @@ export function createStageControlHandle(runtime: LiveStageRuntime): StageContro
     subscribe(listener: AgentSessionEventListener) {
       return runtime.innerCtx.subscribe(listener);
     },
+    subscribeDeliveryActivity(listener) {
+      return runtime.innerCtx.__subscribeDeliveryActivity(listener);
+    },
     async dispose() {
       unsubscribeToolExecutions();
       toolExecutions.clear();

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

@@ -100,6 +100,7 @@ export function createReplayStageContext(input: {
     steer: async () => rejectReplayMutation("steer"),
     followUp: async () => rejectReplayMutation("follow up"),
     subscribe: () => () => {},
+    __subscribeDeliveryActivity: () => () => {},
     get sessionFile() { return replaySource.sessionFile; },
     get sessionId() { return replaySource.sessionId ?? ""; },
     setModel: async () => rejectReplayMutation("set model"),

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

@@ -34,6 +34,7 @@ import {
   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 =
@@ -153,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 {
@@ -172,8 +181,13 @@ export function createPostMortemStageHandle(
     get agentSession() { return context.__agentSession(); },
     async ensureAttached() { await ensureAttached(); },
     async sendUserMessage(text, options, beforeDelivery) {
-      await ensureAttached();
-      return context.__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();
@@ -194,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 =
@@ -98,6 +99,15 @@ export interface StageControlHandle {
    * 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>;
 }