@bastani/atomic 0.9.14-alpha.1 → 0.9.14-alpha.3

package/dist/builtin/workflows/src/extension/workflow-prompts.ts

@@ -3,6 +3,7 @@ export const WORKFLOW_TOOL_DESCRIPTION =
 	"when workflow execution fits but another shape would better achieve the task, author a custom TypeScript workflow({...}) inline with normal coding tools, reload it, and run it; after successfully creating and reloading a newly authored custom workflow, report the folder containing its generated code as 'Custom workflow created. You can inspect its code at: <workflow-folder-path>'; do this only for newly created custom workflows, never builtin or pre-existing workflows; " +
 	"discover with list/get/inputs/models, list session runs with status (no runId; statusFilter narrows the list), inspect status/stages/stage details, " +
 	"send prompt answers or steering only while the root workflow is nonterminal, pause/resume/interrupt/quit runs, and reload workflow resources. " +
+	"For primitive prompt answers, use booleans or the documented confirm labels, exact case-insensitive select labels or 1-based indexes, and text strings for input/editor; an invalid answer remains pending and returns guidance instead of choosing a default. " +
 	"For large stage handoffs, write context to files/artifacts, pass paths via reads, and prompt downstream agents to 'Read the file at <path>...' instead of injecting large previous text. " +
 	"Wrap critical parts of run inputs and steering messages in <keepContext>...</keepContext> so compaction preserves them verbatim in the stages that inherit them; tag role constraints, prohibitions, must-hold criteria, and identifiers, not background or bulk reference material. " +
 	"For transcripts, prefer status/stages/stage to get sessionFile/transcriptPath, " +
@@ -50,6 +51,8 @@ export const DEFAULT_PROMPT_GUIDANCE: string[] = [
 	`**Workflow authoring and handoffs**:
   - When a user asks to create or edit a workflow, clarify only unresolved requirements that materially affect its purpose, inputs, stages, handoffs, validation, success criteria, or starter pattern. Read the workflow docs/examples, implement the TypeScript definition with normal coding tools, reload it, and run representative test inputs before presenting it. Use the create-spec skill when it adds value; it is not mandatory when context is already sufficient.
   - After creating and reloading a newly authored custom workflow, close the loop by stating the folder containing the workflow file just written, for example \`.atomic/workflows/\`, in this shape: \`Custom workflow created. You can inspect its code at: <workflow-folder-path>\`. Do this only for newly created custom workflows, never builtin or pre-existing workflows.
+  - Keep a small, readable workflow in one entry file. Do not split short one-use prompts, create one file per stage, add wrapper-only modules, hide the graph across files, or use line counts alone as a module boundary.
+  - When a meaningful source boundary improves clarity, reuse, ownership, or testability, keep the graph and control flow in the top-level workflow entry file and extract cohesive concerns such as long or reused prompt builders, shared TypeBox schemas and workflow-specific types, model-policy constants shared by several stages, deterministic helpers with their own testable behavior, or reusable child workflow definitions into a subdirectory below the top-level discovery directory — either one owned by a single workflow or a shared support directory. Project and user discovery scans only top-level \`.ts\`/\`.js\`/\`.mjs\`/\`.cjs\` files in the workflow directory, so those support modules are not scanned as extra top-level workflow candidates; use \`.js\` import extensions from TypeScript source.
   - When creating or editing a workflow that pins an explicit stage \`model\` or \`fallbackModels\`, consult \`packages/coding-agent/docs/models/model-selection.md\` for role-based recommendations, treating benchmark thinking levels as measurement configurations rather than universal workflow defaults, then call \`workflow({ action: "models" })\` to see the models actually present in the user's configured catalog. Use only the catalog's returned \`fullId\` values as model strings, and append a thinking suffix only when that exact level appears in the entry's \`availableThinkingLevels\`; apply the stage role and failure-cost policy independently to the primary and every fallback; treat an absent or empty \`availableThinkingLevels\` as no suffix support rather than inferring one. If a guide-recommended model for the role is unavailable, try another guide-recommended model that is present in the catalog. If the selected model does not support the role's level, choose another catalog model that does or leave the stage unpinned rather than inventing or silently promoting a level. An explicit user request for a level overrides the role default, but never fabricate an unsupported catalog level. If no recommendation intersects with the catalog, leave the stage unpinned rather than inventing a substitute, and mention the limitation, asking the user only if the workflow requires an explicit model choice. If the catalog is empty, continue with unpinned stages, state that no configured models were returned, and do not fabricate model IDs. Do not inspect or infer credentials, environment variables, auth files, token validity, entitlements, or the reason a model is absent; \`isCurrent\` marks the active selection, not a quality recommendation.
   - Consult docs/workflows.md and its starter patterns (Classify-and-act, Fan-out-and-synthesize, Adversarial verification, Generate-and-filter, Tournament, Loop until done, and Stacked implementation slices) when designing a stage graph.
   - Treat workflow composition as a first-class authoring option. Before duplicating stages, inspect reusable workflow modules and builtin exports; import their definitions and invoke them with \`ctx.workflow(...)\`, mapping typed inputs and consuming only declared outputs. Nested workflows can themselves import children, so combine small reusable graphs into a richer parent while respecting \`maxDepth\`.
@@ -61,7 +64,7 @@ export const DEFAULT_PROMPT_GUIDANCE: string[] = [
   - Bounded loops must create distinct tracked work for every iteration; never reopen an ancestor below its downstream work. Stacked implementation slices are unrolled, not looped: each slice gets a fresh child boundary and distinct tracked nodes, and no slice may add an edge back to the current frontier, itself, or an ancestor. If a retained session receives follow-up without new dependency work, keep it as non-topological activity metadata rather than adding a back-edge. Before launch, sketch nodes and dependencies for every branch and loop and reject any proposed parent edge to the node itself or an ancestor.
   - Treat dynamic graph validation during execution, replay, and DBOS hydration as the authoritative cycle boundary. If runtime topology code changes, require incremental edge checks and DBOS hydration validation; prompt guidance and TypeScript types cannot replace those runtime checks.
   - Every workflow invocation automatically receives one stable, non-default Intercom group. Intercom-capable stages inherit it, nested workflows keep the top-level invocation group, and subagents inherit their launching stage's group. Do not mint or thread group names through ordinary workflow definitions. Use an explicit \`group\` only for an intentional override: a named group or \`group: true\` creates a subgroup, while \`group: "default"\` opts into the shared default group. Stages without Intercom access receive no group, and \`contact_supervisor\` still crosses group boundaries for authorized escalation.
-  - Prefer \`ctx.tool(name, args, fn)\` for workflow-owned TypeScript operations with side effects, such as filesystem writes, network mutations, and external API actions. It creates a tracked, non-attachable durable graph node before invoking \`fn\`; it may be used before, between, after, or without model stages. A completed \`ctx.tool\` call is durably checkpointed with its serializable result, so resume replays that result without rerunning \`fn\`. For checks that may fail during a bounded repair loop, opt into \`failureMode: "return"\`, branch on the typed outcome, and pass only the needed error fields to the repair stage or artifact yourself; Atomic does not inject failure evidence into later prompts. Cancellation and storage faults still throw. Keep pure computation and side-effect-free transformations as ordinary TypeScript. Do not wrap agent-stage internals or every function call indiscriminately; this rule applies to side effects orchestrated directly by the workflow definition.
+  - Prefer \`ctx.tool(name, args, fn)\` for workflow-owned TypeScript operations with side effects, such as filesystem writes, network mutations, and external API actions. It creates a tracked, non-attachable durable graph node before invoking \`fn\`; it may be used before, between, after, or without model stages. A completed \`ctx.tool\` call is durably checkpointed with its serializable result, so resume replays that result without rerunning \`fn\`. For checks that may fail during a bounded repair loop, opt into \`failureMode: "return"\`, branch on the typed outcome, and pass only the needed error fields to the repair stage or artifact yourself; Atomic does not inject failure evidence into later prompts. Retries do not bound a hung callback, so every \`ctx.tool\` callback that starts a child process or performs network I/O MUST set an explicit positive finite \`timeoutMs\` and forward the supplied \`signal\` to cancellable work. A timeout applies per attempt, aborts that attempt's signal, and gives retries a fresh deadline and signal. Cancellation and storage faults still throw. Keep pure computation and side-effect-free transformations as ordinary TypeScript. Do not wrap agent-stage internals or every function call indiscriminately; this rule applies to side effects orchestrated directly by the workflow definition.
   - Pass large stage context through files/artifacts and \`reads\` with an explicit \`Read the file at <path>...\` prompt rather than large \`previous\` payloads or injected session history.
   - Wrap critical stage-prompt content in \`<keepContext>\` / \`</keepContext>\`. Tagged content survives compression verbatim regardless of the compression ratio, and every line of the span including the tag lines is protected. A long-running stage will be compacted, and compaction ranks lines individually: an objective is verbose and restated while the constraint that narrows it is usually one line, so the constraint is the cheaper deletion and what survives reads as broader permission than intended. Tag role constraints that bound a stage to part of the work, acceptance criteria and immutable contracts, explicit prohibitions, and identifiers a stage must not lose such as a target branch, worktree path, or run ID. Do not tag bulk context: protected lines count against the keep target rather than raising it, so a large protected span makes the surrounding transcript compress harder — tag the constraint, not the material it applies to.
   - Separate implementation/review acceptance from explicitly authorized final actions such as PR/MR/review creation, release tagging, deployment, or publication. Stop implementation loops once acceptance is proven and carry a remaining final action separately.

package/dist/builtin/workflows/src/extension/workflow-schema.ts

@@ -1,5 +1,33 @@
 import { type Static, Type } from "typebox";
 
+/**
+ * Advertise the JSON value types accepted by workflow-send responses.
+ *
+ * `Type.Unknown()` emits `{}`, which tells a provider nothing about this
+ * property. A retained session shows an assistant tool call that answered a
+ * `ctx.ui.confirm` prompt with the string `"true"` rather than a boolean, so
+ * naming the accepted types is worth doing. It is not the runtime fix: no
+ * inspected host or pi-ai layer converts a boolean to a string, and prompt-kind
+ * normalization happens at the pending-prompt boundary, not in provider
+ * argument validation.
+ *
+ * String comes first so validation does not convert text answers to booleans.
+ */
+const WorkflowResponseSchema = Type.Union(
+	[
+		Type.String(),
+		Type.Boolean(),
+		Type.Number(),
+		Type.Null(),
+		Type.Array(Type.Unknown()),
+		Type.Record(Type.String(), Type.Unknown()),
+	],
+	{
+		description:
+			"Answer payload for a pending stage prompt. Primitive prompts accept text strings, booleans, or numeric select indexes according to the prompt kind; structured prompts may accept JSON arrays or objects.",
+	},
+);
+
 export const WorkflowParametersSchema = Type.Object(
 	{
 		workflow: Type.Optional(
@@ -114,11 +142,7 @@ export const WorkflowParametersSchema = Type.Object(
 				description: "Text to send to a stage for prompt answers, steering, follow-ups, or resume messages.",
 			}),
 		),
-		response: Type.Optional(
-			Type.Unknown({
-				description: "Structured response payload for answering a pending stage prompt.",
-			}),
-		),
+		response: Type.Optional(WorkflowResponseSchema),
 		delivery: Type.Optional(
 			Type.Union(
 				[

package/dist/builtin/workflows/src/extension/workflow-tool-send.ts

@@ -10,6 +10,11 @@ import {
 	expandedStageLabel,
 	expandWorkflowGraph,
 } from "../shared/expanded-workflow-graph.js";
+import {
+	coercePrimitivePromptAnswer,
+	isPrimitivePrompt,
+	primitivePromptAnswerRejection,
+} from "../shared/prompt-answer.js";
 import { coerceStageInputAnswer, hasStageInputAnswerContent, type StageInputAnswer } from "../shared/stage-prompt.js";
 import { stageUiBroker } from "../shared/stage-ui-broker.js";
 import { store } from "../shared/store.js";
@@ -287,7 +292,33 @@ export async function workflowSendAction(
 				`Input request ${promptId} was already answered.`,
 			);
 		}
-		const ok = store.resolveStagePendingPrompt(stageRunId, stage.stageId, promptId, promptPayloadFromArgs(args), {
+		const rawPayload = promptPayloadFromArgs(args);
+		const pendingPrompt = snapshot?.pendingPrompt;
+		const primitivePrompt =
+			pendingPrompt?.id === promptId && isPrimitivePrompt(pendingPrompt) ? pendingPrompt : undefined;
+		if (primitivePrompt !== undefined) {
+			const coercedPayload = coercePrimitivePromptAnswer(primitivePrompt, rawPayload);
+			if (!coercedPayload.ok) {
+				return workflowSendResult(
+					stageRunId,
+					stage.stageId,
+					"answer",
+					"noop",
+					primitivePromptAnswerRejection(promptId, primitivePrompt),
+				);
+			}
+			const ok = store.resolveStagePendingPrompt(stageRunId, stage.stageId, promptId, coercedPayload.value, {
+				answerSource: "workflow_tool",
+			});
+			return workflowSendResult(
+				stageRunId,
+				stage.stageId,
+				"answer",
+				ok ? "ok" : "noop",
+				ok ? `Answered prompt ${promptId}.` : `No matching pending prompt ${promptId}.`,
+			);
+		}
+		const ok = store.resolveStagePendingPrompt(stageRunId, stage.stageId, promptId, rawPayload, {
 			answerSource: "workflow_tool",
 		});
 		return workflowSendResult(

package/dist/builtin/workflows/src/runs/background/cancellation-registry.ts

@@ -13,6 +13,8 @@
  * cross-ref: spec §8.1 Phase D (kill-runtime-wiring downstream)
  */
 
+import { createSessionScopedSingleton } from "../../shared/session-scoped-singleton.js";
+
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
@@ -123,4 +125,11 @@ export function createCancellationRegistry(): CancellationRegistry {
  * Singleton registry for the default runtime. Consumers needing isolation
  * should call createCancellationRegistry() instead.
  */
-export const cancellationRegistry: CancellationRegistry = createCancellationRegistry();
+const SESSION_KEY = "workflows:cancellation:v1";
+const singleton = createSessionScopedSingleton(SESSION_KEY, createCancellationRegistry);
+
+export const cancellationRegistry: CancellationRegistry = singleton.facade;
+
+export function adoptCancellationRegistry(scope: object): CancellationRegistry {
+	return singleton.adopt(scope);
+}

package/dist/builtin/workflows/src/runs/background/job-tracker.ts

@@ -9,6 +9,8 @@
  * cross-ref: spec detached-runner §job-tracker
  */
 
+import { createSessionScopedSingleton } from "../../shared/session-scoped-singleton.js";
+
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
@@ -113,4 +115,11 @@ export function createJobTracker(): JobTracker {
 /**
  * Singleton tracker for the default runtime.
  */
-export const jobTracker: JobTracker = createJobTracker();
+const SESSION_KEY = "workflows:job-tracker:v1";
+const singleton = createSessionScopedSingleton(SESSION_KEY, createJobTracker);
+
+export const jobTracker: JobTracker = singleton.facade;
+
+export function adoptJobTracker(scope: object): JobTracker {
+	return singleton.adopt(scope);
+}

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

@@ -262,6 +262,8 @@ export function askUserQuestionToolEvent(event: unknown): AskUserQuestionToolEve
 
 export const READINESS_GATE_ADVANCE_LABEL = "I'm ready to move on to the next workflow stage.";
 
+export const READINESS_GATE_CHAT_MESSAGE = "The user would like to chat more about this";
+
 const READINESS_GATE_ADVANCE_NORMALIZED = READINESS_GATE_ADVANCE_LABEL.trim().toLowerCase();
 
 export const READINESS_GATE_QUESTION_PARAMS = {
@@ -313,6 +315,32 @@ export function toolResultHasChatAnswer(result: unknown): boolean {
 	return answers.some((a) => a !== null && typeof a === "object" && (a as Record<string, unknown>).kind === "chat");
 }
 
+export type ReadinessDecision = { readonly action: "advance" } | { readonly action: "stay"; readonly message?: string };
+
+function firstReadinessAnswer(result: unknown): Record<string, unknown> | undefined {
+	if (result === null || typeof result !== "object") return undefined;
+	const details = (result as Record<string, unknown>).details;
+	if (details === null || typeof details !== "object") return undefined;
+	const answers = (details as Record<string, unknown>).answers;
+	if (!Array.isArray(answers)) return undefined;
+	const first = answers[0];
+	return first !== null && typeof first === "object" ? (first as Record<string, unknown>) : undefined;
+}
+
+export function readinessStayMessage(result: unknown): string | undefined {
+	const first = firstReadinessAnswer(result);
+	if (first === undefined) return undefined;
+	if (first.kind === "chat") return READINESS_GATE_CHAT_MESSAGE;
+	if (first.kind !== "custom" || typeof first.answer !== "string") return undefined;
+	return first.answer.trim().length > 0 ? first.answer : undefined;
+}
+
+export function interpretReadinessResult(result: unknown): ReadinessDecision {
+	if (readinessResultMeansAdvance(result)) return { action: "advance" };
+	const message = readinessStayMessage(result);
+	return message !== undefined ? { action: "stay", message } : { action: "stay" };
+}
+
 export { RESUME_CONTINUATION_PROMPT } from "../../shared/resume-continuation.js";
 
 export function shouldInjectResumeContinuation(state: {
@@ -327,7 +355,7 @@ export function shouldInjectResumeContinuation(state: {
 let cachedReadinessGateTool: ReturnType<typeof createAskUserQuestionToolDefinition> | undefined;
 function readinessGateTool(): ReturnType<typeof createAskUserQuestionToolDefinition> {
 	if (cachedReadinessGateTool === undefined) {
-		cachedReadinessGateTool = createAskUserQuestionToolDefinition();
+		cachedReadinessGateTool = createAskUserQuestionToolDefinition({ chatAsOption: true });
 	}
 	return cachedReadinessGateTool;
 }
@@ -336,9 +364,9 @@ export async function askReadinessViaStageBroker(
 	runId: string,
 	stageId: string,
 	signal: AbortSignal,
-): Promise<"advance" | "stay"> {
+): Promise<ReadinessDecision> {
 	const execute = readinessGateTool().execute;
-	if (execute === undefined) return "advance";
+	if (execute === undefined) return { action: "advance" };
 	const gateContext = {
 		hasUI: true,
 		ui: {
@@ -368,7 +396,7 @@ export async function askReadinessViaStageBroker(
 			undefined,
 			gateContext as unknown as Parameters<typeof execute>[4],
 		);
-		return readinessResultMeansAdvance(result) ? "advance" : "stay";
+		return interpretReadinessResult(result);
 	} finally {
 		stageUiBroker.clearStagePrompt(runId, stageId);
 	}

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

@@ -2,6 +2,7 @@ import type { DurableStageTopology } from "../../durable/types.js";
 import type { DurableUiReplayRequest } from "../../durable/ui-primitive.js";
 import type { GraphFrontierTracker } from "../../engine/graph-inference.js";
 import { appendStageEnd, appendStageStart } from "../../shared/persistence-session-entries.js";
+import { requirePrimitivePromptAnswer } from "../../shared/prompt-answer.js";
 import { withPromptCallerStack } from "../../shared/prompt-callsite-context.js";
 import { stageUiBroker } from "../../shared/stage-ui-broker.js";
 import type { Store } from "../../shared/store.js";
@@ -221,8 +222,16 @@ export function buildPromptNodeUiAdapter(input: {
 		if (shouldReplay) {
 			await Promise.resolve();
 			input.throwIfWorkflowExitSelected();
+			let response = replayAnswer.value;
+			try {
+				if (!isCustom) response = requirePrimitivePromptAnswer(descriptor, response);
+			} catch (err) {
+				applyFailureToStage(stageSnapshot, input.classifyExecutorFailure(err));
+				await finalizePromptStage("failed");
+				throw err;
+			}
 			await finalizePromptStage("completed");
-			return replayAnswer.value;
+			return response;
 		}
 
 		try {
@@ -234,15 +243,9 @@ export function buildPromptNodeUiAdapter(input: {
 		}
 
 		if (isCustom) {
-			if (descriptor.options?.overlay === true) {
-				const error = new Error(
-					"atomic-workflows: ctx.ui.custom overlay mode is unavailable in the workflow graph viewer",
-				);
-				applyFailureToStage(stageSnapshot, input.classifyExecutorFailure(error));
-				await finalizePromptStage("failed");
-				throw error;
-			}
-
+			// `overlay: true` is a placement hint the attached stage-chat host
+			// honours by mounting on its ordinary custom-UI slot, so a workflow
+			// asking for an overlay is served rather than failed here.
 			const mergedSignal = mergeHilSignals(input.signal, descriptor.options?.signal);
 			try {
 				if (mergedSignal.signal.aborted) throw hilAbortError(mergedSignal.signal);
@@ -323,9 +326,10 @@ export function buildPromptNodeUiAdapter(input: {
 					},
 				);
 			});
+			const normalizedResponse = requirePrimitivePromptAnswer(descriptor, response);
 			await waitForExplicitResume();
 			await finalizePromptStage("completed");
-			return response;
+			return normalizedResponse;
 		} catch (err) {
 			if (input.signal.aborted) {
 				input.preserveWorkflowExitSkippedReason(stageSnapshot, "run-aborted");
@@ -355,22 +359,17 @@ export function buildPromptNodeUiAdapter(input: {
 			});
 		},
 		async input(promptText: string): Promise<string> {
-			const response = await ask({ kind: "input", message: promptText });
-			return typeof response === "string" ? response : String(response ?? "");
+			return (await ask({ kind: "input", message: promptText })) as string;
 		},
 		async confirm(message: string): Promise<boolean> {
-			const response = await ask({ kind: "confirm", message });
-			return response === true;
+			return (await ask({ kind: "confirm", message })) as boolean;
 		},
 		async select<T extends string>(message: string, options: readonly T[]): Promise<T> {
 			if (options.length === 0) throw new Error("atomic-workflows: ctx.ui.select requires at least one option");
-			const response = await ask({ kind: "select", message, choices: options });
-			if (typeof response === "string" && (options as readonly string[]).includes(response)) return response as T;
-			return options[0]!;
+			return (await ask({ kind: "select", message, choices: options })) as T;
 		},
 		async editor(initial?: string): Promise<string> {
-			const response = await ask({ kind: "editor", message: "Edit and save to continue.", initial });
-			return typeof response === "string" ? response : (initial ?? "");
+			return (await ask({ kind: "editor", message: "Edit and save to continue.", initial })) as string;
 		},
 		async custom<T>(factory: WorkflowCustomUiFactory<T>, options?: WorkflowCustomUiOptions): Promise<T> {
 			const response = await ask(customPromptDescriptor(factory, options));

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

@@ -6,6 +6,7 @@ import { hasExplicitFastModeCandidate } from "./executor-direct-helpers.js";
 import {
 	askReadinessViaStageBroker,
 	RESUME_CONTINUATION_PROMPT,
+	type ReadinessDecision,
 	shouldInjectResumeContinuation,
 } from "./executor-hil.js";
 import { applyFailureToStage } from "./executor-lifecycle.js";
@@ -45,7 +46,7 @@ export function createTrackedStageCaller(input: {
 	const { runtime } = input;
 	const readinessGateEnabled =
 		runtime.opts.confirmStageReadiness !== undefined || runtime.opts.usePromptNodesForUi === true;
-	const confirmReadiness = async (): Promise<"advance" | "stay"> => {
+	const confirmReadiness = async (): Promise<ReadinessDecision> => {
 		try {
 			if (runtime.opts.confirmStageReadiness !== undefined) {
 				const ready = await runtime.opts.confirmStageReadiness({
@@ -54,11 +55,11 @@ export function createTrackedStageCaller(input: {
 					stageName: runtime.name,
 					signal: runtime.signal,
 				});
-				return ready ? "advance" : "stay";
+				return ready ? { action: "advance" } : { action: "stay" };
 			}
 			return await askReadinessViaStageBroker(runtime.runId, runtime.stageId, runtime.signal);
 		} catch {
-			return "advance";
+			return { action: "advance" };
 		}
 	};
 
@@ -230,27 +231,33 @@ export function createTrackedStageCaller(input: {
 					try {
 						while (runtime.state.askUserQuestionObservedThisTurn || repeatReadinessAfterChatTurn) {
 							const decision = await confirmReadiness();
-							if (decision === "advance") break;
+							if (decision.action === "advance") break;
 							if (runtime.signal.aborted) break;
 							runtime.state.askUserQuestionObservedThisTurn = false;
 							runtime.state.chatAnswerObservedThisTurn = false;
-							runtime.state.waitingForStageChatTurn = true;
-							try {
-								await runtime.raceStageSessionHeartbeat(
-									raceAbort(
-										new Promise<void>((resolve) => {
-											resolveNextTurnEnd = resolve;
-											runtime.state.wakeWaitingForStageChatTurn = resolve;
-										}),
-										runtime.signal,
-									),
-								);
-							} finally {
-								runtime.state.wakeWaitingForStageChatTurn = undefined;
-								runtime.state.waitingForStageChatTurn = false;
+							if (decision.message !== undefined) {
+								result = (await runtime.raceStageSessionHeartbeat(
+									raceAbort(runtime.innerCtx.prompt(decision.message), runtime.signal),
+								)) as T;
+							} else {
+								runtime.state.waitingForStageChatTurn = true;
+								try {
+									await runtime.raceStageSessionHeartbeat(
+										raceAbort(
+											new Promise<void>((resolve) => {
+												resolveNextTurnEnd = resolve;
+												runtime.state.wakeWaitingForStageChatTurn = resolve;
+											}),
+											runtime.signal,
+										),
+									);
+								} finally {
+									runtime.state.wakeWaitingForStageChatTurn = undefined;
+									runtime.state.waitingForStageChatTurn = false;
+								}
+								if (runtime.signal.aborted) break;
+								result = (runtime.innerCtx.__getLastAssistantText() ?? result) as T;
 							}
-							if (runtime.signal.aborted) break;
-							result = (runtime.innerCtx.__getLastAssistantText() ?? result) as T;
 							const continuationDrain = await drainResumeContinuations(result);
 							result = continuationDrain.result;
 							repeatReadinessAfterChatTurn ||= continuationDrain.chatAnswerObserved;

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

@@ -7,12 +7,16 @@
  */
 
 export { raceAbort } from "./executor-abort.js";
+export type { ReadinessDecision } from "./executor-hil.js";
 export {
 	askReadinessViaStageBroker,
+	interpretReadinessResult,
 	READINESS_GATE_ADVANCE_LABEL,
+	READINESS_GATE_CHAT_MESSAGE,
 	READINESS_GATE_QUESTION_PARAMS,
 	RESUME_CONTINUATION_PROMPT,
 	readinessResultMeansAdvance,
+	readinessStayMessage,
 	shouldInjectResumeContinuation,
 	toolResultHasChatAnswer,
 } from "./executor-hil.js";

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

@@ -26,6 +26,7 @@
  */
 
 import type { AgentSession, AgentSessionEvent } from "@bastani/atomic";
+import { createSessionScopedSingleton } from "../../shared/session-scoped-singleton.js";
 import type { StageDeliveryActivityEvent } from "./stage-delivery-activity.js";
 import type { StageQueuedUserMessages } from "./stage-queued-user-messages.js";
 import type { StageUserMessageDeliveryAction } from "./stage-runner-types.js";
@@ -188,6 +189,8 @@ export interface StageControlRegistry {
 	get(runId: string, stageId: string): StageControlHandle | undefined;
 	/** Resolve all currently-registered chat handles for a run. */
 	forRun(runId: string): readonly StageControlHandle[];
+	/** True when this run currently has a registration map. */
+	has(runId: string): boolean;
 	/** Build a run-level control aggregate. Cheap; not memoised. */
 	run(runId: string): WorkflowRunControlHandle;
 	/**
@@ -196,6 +199,13 @@ export interface StageControlRegistry {
 	 * their subscriptions when the host store is cleared.
 	 */
 	clear(): void;
+	/**
+	 * Drop only handles detached from run-level control (`controlsDependencies`
+	 * false), disposing them through the background-dispose path. Live executor
+	 * handles that still own workflow execution stay registered. Emptied run
+	 * maps are pruned.
+	 */
+	clearDetached(): void;
 }
 
 /**
@@ -415,6 +425,9 @@ export function createStageControlRegistry(): StageControlRegistry {
 			if (!runMap) return [];
 			return [...runMap.values()].map((entry) => entry.handle);
 		},
+		has(runId: string): boolean {
+			return _byRun.has(runId);
+		},
 		run(runId: string): WorkflowRunControlHandle {
 			return makeRunHandle(runId);
 		},
@@ -425,6 +438,16 @@ export function createStageControlRegistry(): StageControlRegistry {
 				disposeEntryInBackground(entry, "atomic-workflows: stage handle dispose failed");
 			}
 		},
+		clearDetached(): void {
+			for (const [runId, runMap] of [..._byRun]) {
+				for (const [stageId, entry] of [...runMap]) {
+					if (entry.controlsDependencies) continue;
+					runMap.delete(stageId);
+					disposeEntryInBackground(entry, "atomic-workflows: detached stage handle dispose failed");
+				}
+				if (runMap.size === 0) _byRun.delete(runId);
+			}
+		},
 	};
 }
 
@@ -433,4 +456,11 @@ export function createStageControlRegistry(): StageControlRegistry {
  * explicit instance via `RunOpts.stageControlRegistry`; the singleton
  * is the default consumer surface used by the extension factory.
  */
-export const stageControlRegistry: StageControlRegistry = createStageControlRegistry();
+const SESSION_KEY = "workflows:stage-control:v1";
+const singleton = createSessionScopedSingleton(SESSION_KEY, createStageControlRegistry);
+
+export const stageControlRegistry: StageControlRegistry = singleton.facade;
+
+export function adoptStageControlRegistry(scope: object): StageControlRegistry {
+	return singleton.adopt(scope);
+}

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

@@ -1,7 +1,8 @@
 import { createStructuredOutputCapture, runCallback } from "@bastani/atomic";
+import type { Static, TSchema } from "typebox";
 import type { StageExecutionMeta } from "../../shared/types.js";
 import { StageSessionController } from "./stage-runner-controller.js";
-import { assistantMessage } from "./stage-runner-messages.js";
+import { assistantArtifactTextForToolCall, assistantMessage } from "./stage-runner-messages.js";
 import {
 	finalizePromptOutput,
 	splitPromptOptions,
@@ -12,6 +13,7 @@ import {
 	formatStructuredOutputCorrectionPrompt,
 	STRUCTURED_OUTPUT_MAX_CORRECTIVE_PROMPTS,
 	STRUCTURED_OUTPUT_MISSING_ERROR,
+	type StructuredOutputExecutionCapture,
 	stageOptionsWithStructuredOutput,
 	stringifyStructuredOutputValue,
 } from "./stage-runner-structured-output.js";
@@ -19,8 +21,14 @@ import type { InternalStageContext, StageRunnerOpts } from "./stage-runner-types
 
 export function createStageContext(opts: StageRunnerOpts): InternalStageContext {
 	const { stageId, stageName, adapters, runId, workflowIntercomGroup, signal, stageOptions, executionMode } = opts;
-	const structuredOutputCapture = stageOptions?.schema ? createStructuredOutputCapture<unknown>() : undefined;
-	const effectiveStageOptions = stageOptionsWithStructuredOutput(stageOptions, structuredOutputCapture);
+	const structuredOutputCapture = stageOptions?.schema ? createStructuredOutputCapture<Static<TSchema>>() : undefined;
+	const structuredOutputExecutionCapture: StructuredOutputExecutionCapture<Static<TSchema>> | undefined =
+		stageOptions?.schema ? {} : undefined;
+	const effectiveStageOptions = stageOptionsWithStructuredOutput(
+		stageOptions,
+		structuredOutputCapture,
+		structuredOutputExecutionCapture,
+	);
 	const meta: StageExecutionMeta = {
 		runId,
 		stageId,
@@ -34,6 +42,7 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
 	let lastAssistantText: string | undefined;
 	let lastFinalizedOutput: string | undefined;
 	let lastFinalizedMessageCount: number | undefined;
+	let structuredArtifactFinalized = false;
 	let adapterMessages = [] as InternalStageContext["messages"];
 
 	function runtimeCwd(): string {
@@ -43,7 +52,8 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
 	function finalizedOutputIsCurrent(): boolean {
 		return (
 			lastFinalizedOutput !== undefined &&
-			(lastFinalizedMessageCount === undefined ||
+			(structuredArtifactFinalized ||
+				lastFinalizedMessageCount === undefined ||
 				controller.currentSession?.messages.length === lastFinalizedMessageCount)
 		);
 	}
@@ -54,9 +64,10 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
 		async prompt(text, options) {
 			const { sdkOptions, outputOptions } = splitPromptOptions(options);
 			validatePromptOutputOptions(outputOptions);
+			const hasOutputArtifact = typeof outputOptions.output === "string" && outputOptions.output.length > 0;
 			// The runtime owns the artifact write, so it states that contract itself
 			// rather than relying on every workflow definition to describe it.
-			const promptText = `${text}${stageOutputInstruction(outputOptions)}`;
+			const promptText = `${text}${stageOutputInstruction(outputOptions, structuredOutputCapture !== undefined)}`;
 			if (structuredOutputCapture?.called) {
 				throw new Error(
 					"atomic-workflows: stage schema supports one prompt() call per stage context because structured_output may be called exactly once. Create a new ctx.stage(...) for each additional schema-backed prompt.",
@@ -97,19 +108,39 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
 						throw new Error(structuredOutputError);
 					}
 					correctiveAttempts += 1;
-					nextPrompt = formatStructuredOutputCorrectionPrompt(structuredOutputError, correctiveAttempts);
+					nextPrompt = formatStructuredOutputCorrectionPrompt(
+						structuredOutputError,
+						correctiveAttempts,
+						hasOutputArtifact,
+					);
+				}
+				const sessionMessages = controller.currentSession?.messages;
+				const executionSnapshot = structuredOutputExecutionCapture?.snapshot;
+				if (executionSnapshot === undefined) {
+					throw new Error(
+						"atomic-workflows: structured_output completed without an execution snapshot; the successful tool call could not be paired with its result.",
+					);
 				}
-				const rawStructuredText = stringifyStructuredOutputValue(structuredOutputCapture.value);
+				// The exact successful tool-call message owns the artifact. When it
+				// carries no ordinary text — or the session no longer holds it after
+				// model-fallback recreation — fall back to the last non-structured
+				// assistant text so an earlier-turn deliverable is not discarded
+				// (issue #2198); only when no prose exists anywhere is the artifact
+				// empty, and its receipt then carries the empty-artifact warning.
+				const rawOutputText = hasOutputArtifact
+					? (assistantArtifactTextForToolCall(sessionMessages ?? [], executionSnapshot.toolCallId) ?? "")
+					: stringifyStructuredOutputValue(executionSnapshot.value);
 				lastAssistantText = await finalizePromptOutput(
-					rawStructuredText,
+					rawOutputText,
 					outputOptions,
 					runtimeCwd(),
 					runId,
-					controller.currentSession?.messages,
+					sessionMessages,
 				);
 				lastFinalizedOutput = lastAssistantText;
 				lastFinalizedMessageCount = controller.currentSession?.messages.length;
-				return structuredOutputCapture.value as never;
+				if (hasOutputArtifact) structuredArtifactFinalized = true;
+				return executionSnapshot.value as never;
 			}
 			await controller.promptWithFallback(promptText, sdkOptions);
 			const rawText = controller.lastAssistantText(lastAssistantText) ?? "";