@bastani/atomic 0.9.14-alpha.2 → 0.9.14-alpha.4

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

@@ -38912,7 +38912,8 @@ var MOCHA = {
   yellow: "#f9e2af",
   red: "#f38ba8",
   mauve: "#cba6f7",
-  sky: "#89dceb"
+  sky: "#89dceb",
+  lavender: "#b4befe"
 };
 function deriveGraphTheme(theme = {}) {
   return {
@@ -38929,6 +38930,8 @@ function deriveGraphTheme(theme = {}) {
     text: theme.text ?? MOCHA.text,
     textMuted: theme.textMuted ?? MOCHA.subtext0,
     dim: theme.dim ?? MOCHA.overlay1,
+    toolTitle: theme.toolTitle ?? MOCHA.lavender,
+    toolOutput: theme.toolOutput ?? MOCHA.text,
     accent: theme.accent ?? MOCHA.blue,
     mauve: theme.mauve ?? MOCHA.mauve,
     success: theme.success ?? MOCHA.green,
@@ -39002,6 +39005,8 @@ function deriveGraphThemeFromPiTheme(theme) {
     text: fgHex(t, "text") ?? fgHex(t, "customMessageText"),
     textMuted: fgHex(t, "muted"),
     dim: fgHex(t, "dim"),
+    toolTitle: fgHex(t, "toolTitle"),
+    toolOutput: fgHex(t, "toolOutput") ?? fgHex(t, "text") ?? fgHex(t, "customMessageText"),
     accent,
     success: fgHex(t, "success"),
     warning: fgHex(t, "warning"),
@@ -43801,7 +43806,12 @@ function renderSwitcher(stages, state, opts) {
 var TOOL_DETAIL_VALUE_LIMIT = TOOL_PAYLOAD_VALUE_LIMIT;
 var COLLAPSED_ARGS_LIMIT = 240;
 var COLLAPSED_RESULT_LINES = 10;
-var BODY_INDENT = "  ";
+var BOX_PAD = 1;
+function boxMetrics(width) {
+  const safeWidth = Math.max(1, Math.floor(width));
+  const inset = safeWidth >= BOX_PAD * 2 + 1 ? BOX_PAD : 0;
+  return { pad: " ".repeat(inset), inner: Math.max(1, safeWidth - inset * 2) };
+}
 function statusColor2(status, theme) {
   switch (status) {
     case "running":
@@ -43842,14 +43852,26 @@ function styledStatus(status, theme) {
   return theme === undefined ? glyph : `${hexToAnsi(statusColor2(status, theme))}${glyph}${RESET}`;
 }
 function styledTitle(text, theme) {
-  return theme === undefined ? text : `${hexToAnsi(theme.text)}${BOLD}${text}${RESET}`;
+  return theme === undefined ? text : `${hexToAnsi(theme.toolTitle)}${BOLD}${text}${RESET}`;
+}
+function styledOutput(text, theme) {
+  return theme === undefined ? text : `${hexToAnsi(theme.toolOutput)}${text}${RESET}`;
 }
 function styledMuted(text, theme) {
   return theme === undefined ? text : `${hexToAnsi(theme.textMuted)}${text}${RESET}`;
 }
+function styledDim(text, theme) {
+  return theme === undefined ? text : `${hexToAnsi(theme.dim)}${text}${RESET}`;
+}
 function styledError(text, theme) {
   return theme === undefined ? text : `${hexToAnsi(theme.error)}${text}${RESET}`;
 }
+function expandHintLine(earlier, expandKey, pad2, theme) {
+  const lead = `... (${earlier} earlier lines`;
+  if (expandKey.length === 0)
+    return `${pad2}${styledMuted(`${lead})`, theme)}`;
+  return `${pad2}${styledMuted(`${lead}, `, theme)}${styledDim(expandKey, theme)}${styledMuted(" Expand)", theme)}`;
+}
 function toolBackground(status, theme) {
   switch (status) {
     case "completed":
@@ -43993,70 +44015,70 @@ function paintRow(content, width, theme, status) {
   return `${background}${repainted}${background}${" ".repeat(padding)}${RESET}`;
 }
 function messageHeaderRows(tool, width, theme, expanded) {
-  const safeWidth = Math.max(1, Math.floor(width));
+  const { pad: pad2, inner } = boxMetrics(width);
   const name = sanitizeToolTitleText(tool.name);
   const glyph = headerGlyph(tool.status);
   const glyphSuffix = glyph === undefined ? "" : ` ${glyph}`;
   const args = tool.args === undefined ? "" : boundedSerializedValue(tool.args, expanded ? TOOL_DETAIL_VALUE_LIMIT : COLLAPSED_ARGS_LIMIT);
   const withArgs = `$ ${name}${args ? ` ${args}` : ""}${glyphSuffix}`;
-  const plain = !expanded && visibleWidth(withArgs) > safeWidth ? `$ ${name}${glyphSuffix}` : withArgs;
+  const plain = !expanded && visibleWidth(withArgs) > inner ? `$ ${name}${glyphSuffix}` : withArgs;
   const titleEnd = `$ ${name}`;
-  const continuationIndent = BODY_INDENT;
-  const continuationWidth = Math.max(1, safeWidth - visibleWidth(continuationIndent));
-  return wrapFieldValue(plain, safeWidth, continuationWidth).map((chunk, index, chunks) => {
-    const prefix = index === 0 ? "" : continuationIndent;
+  return wrapFieldValue(plain, inner, inner).map((chunk, index, chunks) => {
     if (index !== 0 || !chunk.startsWith(titleEnd))
-      return `${prefix}${styledMuted(chunk, theme)}`;
+      return `${pad2}${styledMuted(chunk, theme)}`;
     const remainder = chunk.slice(titleEnd.length);
     const hasStatus = glyphSuffix.length > 0 && index === chunks.length - 1 && remainder.endsWith(glyphSuffix);
     const summary = hasStatus ? remainder.slice(0, -glyphSuffix.length) : remainder;
     const suffix = hasStatus ? ` ${styledStatus(tool.status, theme)}` : "";
-    return `${styledTitle(titleEnd, theme)}${summary.trim().length > 0 ? styledMuted(summary, theme) : ""}${suffix}`;
+    const title = styledTitle(titleEnd, theme);
+    const rest = summary.trim().length > 0 ? styledMuted(summary, theme) : "";
+    return `${pad2}${title}${rest}${suffix}`;
   });
 }
 function bodyRows(text, error, width, theme) {
-  const contentWidth = Math.max(1, width - visibleWidth(BODY_INDENT));
-  return wrapFieldValue(text, contentWidth).map((line) => {
-    const styled = error ? styledError(line, theme) : styledMuted(line, theme);
-    return `${BODY_INDENT}${styled}`;
+  const { pad: pad2, inner } = boxMetrics(width);
+  return wrapFieldValue(text, inner).map((line) => {
+    const styled = error ? styledError(line, theme) : styledOutput(line, theme);
+    return `${pad2}${styled}`;
   });
 }
 function footerText(tool, elapsed) {
   if (elapsed === undefined)
     return;
   const label = tool.status === "running" ? "Elapsed" : "Took";
-  const duration = elapsed < 1000 ? `${Math.round(elapsed)}ms` : fmtDuration(elapsed);
   const markers = [
     tool.status === "cached" ? "cached" : undefined,
     tool.replayed === true ? "replayed" : undefined
   ].filter((marker) => marker !== undefined);
-  return `${label} ${duration}${markers.length > 0 ? ` · ${markers.join(" · ")}` : ""}`;
+  return `${label} ${fmtDuration(elapsed)}${markers.length > 0 ? ` · ${markers.join(" · ")}` : ""}`;
 }
 function renderMessageLines(tool, width, theme, expanded, expandKey, now) {
   const safeWidth = Math.max(1, Math.floor(width));
+  const { pad: pad2, inner } = boxMetrics(safeWidth);
   const result = resultText(tool, TOOL_DETAIL_VALUE_LIMIT);
   const rows = messageHeaderRows(tool, safeWidth, theme, expanded);
+  rows.push("");
   const wrappedBody = bodyRows(result.text, result.error, safeWidth, theme);
   if (expanded) {
     rows.push(...wrappedBody);
     if (tool.source !== undefined && tool.source.length > 0) {
-      const sourceWidth = Math.max(1, safeWidth - visibleWidth(BODY_INDENT));
-      rows.push(...wrapFieldValue(boundedToolText(sanitizeToolDisplayText(tool.source)), sourceWidth).map((line) => `${BODY_INDENT}${styledMuted(line, theme)}`));
+      rows.push(...wrapFieldValue(boundedToolText(sanitizeToolDisplayText(tool.source)), inner).map((line) => `${pad2}${styledMuted(line, theme)}`));
     }
   } else {
     const earlier = Math.max(0, wrappedBody.length - COLLAPSED_RESULT_LINES);
     if (earlier > 0) {
-      const hint = expandKey.length > 0 ? `... (${earlier} earlier lines, ${expandKey} Expand)` : `... (${earlier} earlier lines)`;
-      rows.push(`  ${styledMuted(hint, theme)}`);
+      rows.push(expandHintLine(earlier, expandKey, pad2, theme));
     }
     rows.push(...wrappedBody.slice(-COLLAPSED_RESULT_LINES));
   }
   const footer = footerText(tool, durationMs(tool, now));
   if (footer !== undefined) {
     rows.push("");
-    rows.push(styledMuted(footer, theme));
+    rows.push(`${pad2}${styledMuted(footer, theme)}`);
   }
-  return rows.map((row) => paintRow(row, safeWidth, theme, tool.status));
+  const painted = rows.map((row) => paintRow(row, safeWidth, theme, tool.status));
+  const padRow = paintRow("", safeWidth, theme, tool.status);
+  return [padRow, ...painted, padRow];
 }
 function renderToolDetail(tool, opts = {}) {
   const width = Math.max(1, Math.floor(opts.width ?? 80));
@@ -44078,6 +44100,10 @@ function stripLayoutWrapper(line) {
   const end = endsWithWrapper ? line.length - LAYOUT_OSC_RESET.length : line.length;
   return line.slice(start, Math.max(start, end));
 }
+var TOOL_DETAIL_VIEWPORT_PAD = 1;
+function toolDetailViewportPad(rows) {
+  return rows >= TOOL_DETAIL_VIEWPORT_PAD * 2 + 1 ? TOOL_DETAIL_VIEWPORT_PAD : 0;
+}
 
 class GraphViewRenderer extends GraphViewGraphRenderer {
   graphLayout;
@@ -44169,14 +44195,13 @@ class GraphViewRenderer extends GraphViewGraphRenderer {
     const cached = this.detailFrame;
     if (cached !== null && cached.width === safeWidth)
       return cached;
-    const blockWidth = Math.max(1, safeWidth - 1);
     const frame = {
       width: safeWidth,
-      blockWidth,
-      leftPad: safeWidth > 1 ? 1 : 0,
+      blockWidth: safeWidth,
+      leftPad: 0,
       lines: renderToolDetailLines(node, {
         theme: this.graphTheme,
-        width: blockWidth,
+        width: safeWidth,
         expanded: this.toolDetailExpanded,
         expandKey: toolExpandKey(isKeybindingsLike(this.piKeybindings) ? this.piKeybindings : undefined)
       })
@@ -44187,7 +44212,8 @@ class GraphViewRenderer extends GraphViewGraphRenderer {
   _graphBodyContentHeight(width, viewportRows) {
     const rows = Math.max(0, Math.floor(viewportRows));
     if (this.toolDetail !== null) {
-      return Math.max(rows, this._toolDetailFrame(this.toolDetail, width).lines.length);
+      const pad2 = toolDetailViewportPad(rows);
+      return Math.max(rows, this._toolDetailFrame(this.toolDetail, width).lines.length + pad2 * 2);
     }
     if (!this._currentRenderRun() || this.cachedRenderGeometry.totalRows <= 0)
       return rows;
@@ -44245,7 +44271,10 @@ class GraphViewRenderer extends GraphViewGraphRenderer {
   _renderBody(width, top, rows, _contentRows) {
     if (this.toolDetail !== null) {
       const detail = this._toolDetailFrame(this.toolDetail, width);
-      return detail.lines.slice(top, top + rows).map((line) => this._canvasRow(`${" ".repeat(detail.leftPad)}${line}`, width));
+      const pad2 = toolDetailViewportPad(rows);
+      const inner = Math.max(0, rows - pad2 * 2);
+      const painted = detail.lines.slice(top, top + inner).map((line) => this._canvasRow(`${" ".repeat(detail.leftPad)}${line}`, width));
+      return [...Array.from({ length: pad2 }, () => ""), ...painted, ...Array.from({ length: pad2 }, () => "")];
     }
     const run = this._currentRenderRun();
     const raw = run ? this._renderGraph(width, top, rows, run) : this._renderEmptyBody(width, rows);
@@ -45560,11 +45589,6 @@ async function showCustomUi(ctx, request) {
     ctx.stageUiBroker.reject(request, new Error("atomic-workflows: stage custom UI cannot mount without attached TUI host"));
     return;
   }
-  if (request.options?.overlay === true) {
-    ctx.mountingRequestId = null;
-    ctx.stageUiBroker.reject(request, new Error("atomic-workflows: ctx.ui.custom overlay mode is unavailable in the workflow graph viewer"));
-    return;
-  }
   try {
     const mounted = await mountStageCustomUi(request, ctx.piTui, ctx.piTheme, ctx.piKeybindings, ctx.stageUiBroker, () => {
       if (ctx.mountedCustomUi?.request.id !== request.id)
@@ -56020,7 +56044,8 @@ var orchestratorModelConfig = {
     "openai/gpt-5.5:xhigh",
     "anthropic/claude-opus-4-8:high",
     "github-copilot/claude-opus-4.8:high",
-    "xai/grok-4.6:high",
+    "xai/grok-4.6:xhigh",
+    "github-copilot/grok-4.6:xhigh",
     "zai/glm-5.3:high",
     "zai-coding-cn/glm-5.3:high",
     "openrouter/anthropic/claude-opus-5:high",
@@ -56051,7 +56076,8 @@ var reviewerModelConfig = {
     "openai/gpt-5.5:xhigh",
     "anthropic/claude-opus-4-8:high",
     "github-copilot/claude-opus-4.8:high",
-    "xai/grok-4.6:high",
+    "xai/grok-4.6:xhigh",
+    "github-copilot/grok-4.6:xhigh",
     "zai/glm-5.3:high",
     "zai-coding-cn/glm-5.3:high",
     "openrouter/anthropic/claude-opus-5:high",
@@ -58079,7 +58105,8 @@ async function runOpenClaudeDesignWorkflow(ctx) {
       "openai-codex/gpt-5.6-sol:xhigh",
       "github-copilot/gpt-5.6-sol:xhigh",
       "openai/gpt-5.6-sol:xhigh",
-      "xai/grok-4.6:high",
+      "xai/grok-4.6:xhigh",
+      "github-copilot/grok-4.6:xhigh",
       "zai/glm-5.3:high",
       "zai-coding-cn/glm-5.3:high",
       "openrouter/anthropic/claude-opus-5:high",
@@ -59016,7 +59043,8 @@ var promptEngineerModelConfig = {
     "openai/gpt-5.5:xhigh",
     "anthropic/claude-opus-4-8:high",
     "github-copilot/claude-opus-4.8:high",
-    "xai/grok-4.6:high",
+    "xai/grok-4.6:xhigh",
+    "github-copilot/grok-4.6:xhigh",
     "zai/glm-5.3:high",
     "zai-coding-cn/glm-5.3:high",
     "openrouter/anthropic/claude-opus-5:high",
@@ -59047,7 +59075,8 @@ var researchModelConfig = {
     "openai/gpt-5.5:xhigh",
     "anthropic/claude-opus-4-8:high",
     "github-copilot/claude-opus-4.8:high",
-    "xai/grok-4.6:high",
+    "xai/grok-4.6:xhigh",
+    "github-copilot/grok-4.6:xhigh",
     "zai/glm-5.3:high",
     "zai-coding-cn/glm-5.3:high",
     "openrouter/anthropic/claude-opus-5:high",
@@ -59078,7 +59107,8 @@ var orchestratorModelConfig2 = {
     "openai/gpt-5.5:xhigh",
     "anthropic/claude-opus-4-8:high",
     "github-copilot/claude-opus-4.8:high",
-    "xai/grok-4.6:high",
+    "xai/grok-4.6:xhigh",
+    "github-copilot/grok-4.6:xhigh",
     "zai/glm-5.3:high",
     "zai-coding-cn/glm-5.3:high",
     "openrouter/anthropic/claude-opus-5:high",
@@ -59109,7 +59139,8 @@ var reviewerAModelConfig = {
     "openai/gpt-5.5:xhigh",
     "anthropic/claude-opus-4-8:high",
     "github-copilot/claude-opus-4.8:high",
-    "xai/grok-4.6:high",
+    "xai/grok-4.6:xhigh",
+    "github-copilot/grok-4.6:xhigh",
     "zai/glm-5.3:high",
     "zai-coding-cn/glm-5.3:high",
     "openrouter/anthropic/claude-opus-5:high",
@@ -59141,7 +59172,8 @@ var reviewerBModelConfig = {
     "openai/gpt-5.5:xhigh",
     "anthropic/claude-opus-4-8:high",
     "github-copilot/claude-opus-4.8:high",
-    "xai/grok-4.6:high",
+    "xai/grok-4.6:xhigh",
+    "github-copilot/grok-4.6:xhigh",
     "zai/glm-5.3:high",
     "zai-coding-cn/glm-5.3:high",
     "openrouter/openai/gpt-5.6-sol:xhigh",
@@ -60826,6 +60858,7 @@ function askUserQuestionToolEvent(event) {
   return;
 }
 var READINESS_GATE_ADVANCE_LABEL = "I'm ready to move on to the next workflow stage.";
+var READINESS_GATE_CHAT_MESSAGE = "The user would like to chat more about this";
 var READINESS_GATE_ADVANCE_NORMALIZED = READINESS_GATE_ADVANCE_LABEL.trim().toLowerCase();
 var READINESS_GATE_QUESTION_PARAMS = {
   questions: [
@@ -60870,6 +60903,34 @@ function toolResultHasChatAnswer(result) {
     return false;
   return answers.some((a) => a !== null && typeof a === "object" && a.kind === "chat");
 }
+function firstReadinessAnswer(result) {
+  if (result === null || typeof result !== "object")
+    return;
+  const details = result.details;
+  if (details === null || typeof details !== "object")
+    return;
+  const answers = details.answers;
+  if (!Array.isArray(answers))
+    return;
+  const first = answers[0];
+  return first !== null && typeof first === "object" ? first : undefined;
+}
+function readinessStayMessage(result) {
+  const first = firstReadinessAnswer(result);
+  if (first === undefined)
+    return;
+  if (first.kind === "chat")
+    return READINESS_GATE_CHAT_MESSAGE;
+  if (first.kind !== "custom" || typeof first.answer !== "string")
+    return;
+  return first.answer.trim().length > 0 ? first.answer : undefined;
+}
+function interpretReadinessResult(result) {
+  if (readinessResultMeansAdvance(result))
+    return { action: "advance" };
+  const message = readinessStayMessage(result);
+  return message !== undefined ? { action: "stay", message } : { action: "stay" };
+}
 function shouldInjectResumeContinuation(state) {
   if (state.reason === false || state.aborted)
     return false;
@@ -60878,14 +60939,14 @@ function shouldInjectResumeContinuation(state) {
 var cachedReadinessGateTool;
 function readinessGateTool() {
   if (cachedReadinessGateTool === undefined) {
-    cachedReadinessGateTool = createAskUserQuestionToolDefinition();
+    cachedReadinessGateTool = createAskUserQuestionToolDefinition({ chatAsOption: true });
   }
   return cachedReadinessGateTool;
 }
 async function askReadinessViaStageBroker(runId, stageId, signal) {
   const execute = readinessGateTool().execute;
   if (execute === undefined)
-    return "advance";
+    return { action: "advance" };
   const gateContext = {
     hasUI: true,
     ui: {
@@ -60898,7 +60959,7 @@ async function askReadinessViaStageBroker(runId, stageId, signal) {
     stageUiBroker.provideStagePrompt(runId, stageId, gateAdapter);
   try {
     const result = await execute(gatePromptId, READINESS_GATE_QUESTION_PARAMS, signal, undefined, gateContext);
-    return readinessResultMeansAdvance(result) ? "advance" : "stay";
+    return interpretReadinessResult(result);
   } finally {
     stageUiBroker.clearStagePrompt(runId, stageId);
   }
@@ -64990,12 +65051,6 @@ function buildPromptNodeUiAdapter(input) {
       throw err;
     }
     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;
-      }
       const mergedSignal = mergeHilSignals(input.signal, descriptor.options?.signal);
       try {
         if (mergedSignal.signal.aborted)
@@ -68041,11 +68096,11 @@ 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" };
     }
   };
   const suppressReadinessForCurrentTurn = () => {
@@ -68187,25 +68242,29 @@ function createTrackedStageCaller(input) {
           try {
             while (runtime.state.askUserQuestionObservedThisTurn || repeatReadinessAfterChatTurn) {
               const decision = await confirmReadiness();
-              if (decision === "advance")
+              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((resolve11) => {
-                  resolveNextTurnEnd = resolve11;
-                  runtime.state.wakeWaitingForStageChatTurn = resolve11;
-                }), 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));
+              } else {
+                runtime.state.waitingForStageChatTurn = true;
+                try {
+                  await runtime.raceStageSessionHeartbeat(raceAbort(new Promise((resolve11) => {
+                    resolveNextTurnEnd = resolve11;
+                    runtime.state.wakeWaitingForStageChatTurn = resolve11;
+                  }), runtime.signal));
+                } finally {
+                  runtime.state.wakeWaitingForStageChatTurn = undefined;
+                  runtime.state.waitingForStageChatTurn = false;
+                }
+                if (runtime.signal.aborted)
+                  break;
+                result = runtime.innerCtx.__getLastAssistantText() ?? result;
               }
-              if (runtime.signal.aborted)
-                break;
-              result = runtime.innerCtx.__getLastAssistantText() ?? result;
               const continuationDrain = await drainResumeContinuations(result);
               result = continuationDrain.result;
               repeatReadinessAfterChatTurn ||= continuationDrain.chatAnswerObserved;

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

@@ -243,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);

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/shared/authoring-contract-ui.d.ts

@@ -13,7 +13,12 @@ export type WorkflowCustomUiOverlayOptions = OverlayOptions;
 export type WorkflowCustomUiOverlayHandle = OverlayHandle;
 export type WorkflowCustomUiFactory<T> = (tui: TUI, theme: Theme, keybindings: KeybindingsManager, done: (value: T) => void) => WorkflowCustomUiComponent | Promise<WorkflowCustomUiComponent>;
 export interface WorkflowCustomUiOptions {
-    /** Render as a nested overlay. Workflow graph hosts may reject this when unsupported. */
+    /**
+     * Ask the host to render as an overlay. Workflow graph hosts accept this: the
+     * attached stage chat mounts the widget on its ordinary custom-UI slot, which
+     * already keeps the stage transcript visible behind it, instead of opening a
+     * nested overlay above the graph chrome.
+     */
     readonly overlay?: boolean;
     /** AbortSignal to programmatically dismiss the custom UI. */
     readonly signal?: AbortSignal;

package/dist/builtin/workflows/src/shared/authoring-contract-ui.ts

@@ -49,7 +49,12 @@ export type WorkflowCustomUiFactory<T> = (
 ) => WorkflowCustomUiComponent | Promise<WorkflowCustomUiComponent>;
 
 export interface WorkflowCustomUiOptions {
-	/** Render as a nested overlay. Workflow graph hosts may reject this when unsupported. */
+	/**
+	 * Ask the host to render as an overlay. Workflow graph hosts accept this: the
+	 * attached stage chat mounts the widget on its ordinary custom-UI slot, which
+	 * already keeps the stage transcript visible behind it, instead of opening a
+	 * nested overlay above the graph chrome.
+	 */
 	readonly overlay?: boolean;
 	/** AbortSignal to programmatically dismiss the custom UI. */
 	readonly signal?: AbortSignal;