@bastani/atomic 0.8.31-alpha.4 → 0.8.31-alpha.5

package/CHANGELOG.md

@@ -23,6 +23,7 @@
 
 ### Fixed
 
+- Exposed `SessionManager.usesDefaultSessionDir()` through the read-only extension session-manager surface so bundled extensions can distinguish default global session storage from non-default `--session-dir`, `ATOMIC_CODING_AGENT_SESSION_DIR`, or settings-backed session directories without path guessing ([#1444](https://github.com/bastani-inc/atomic/issues/1444)).
 - Fixed `github-copilot/*` Gemini models (for example `github-copilot/gemini-3.1-pro-preview` and `github-copilot/gemini-3.5-flash`) failing **every** chat turn with `Error: 400 invalid request body`. These models are served through GitHub's Copilot API (CAPI), which translates the OpenAI chat-completions request into a Google GenAI `GenerateContent` request and forwards tool/function JSON Schema `anyOf`/`oneOf` verbatim into Gemini's `FunctionDeclaration` schema. Gemini rejects a union whose branch is a complex **object** schema, so Google returned HTTP 400 and CAPI relabelled it `{"error":{"code":"invalid_request_body"}}`. Because Atomic's bundled `workflow` tool — and any tool using the TypeBox `Type.Union([Type.Object(...), Type.String()])` pattern for fields such as `task`, `chain`, and `parallel` — is present in normal chat turns, the request failed before the model ever ran (it was previously masked only when a fallback model existed). Atomic now sanitizes outbound tool JSON Schemas for GitHub Copilot Gemini models into the subset CAPI/Gemini honors: it resolves object/array-bearing `anyOf`/`oneOf` to their most expressive branch, converts `const`/literal unions to `enum`, collapses nullable unions to `nullable`, prunes `required` to existing properties, and drops non-portable keywords (`additionalProperties`, `patternProperties`, `$schema`, `format`, `pattern`, numeric/length bounds, `default`, `title`, etc.). The transform is gated to `github-copilot` Gemini `openai-completions` models and runs last in the provider-payload pipeline (so it also covers extension/SDK-injected tools), leaving every other provider/model payload unchanged.
 - Fixed `github-copilot/*` Gemini models getting stuck in an infinite tool-call retry loop (most visibly on the workflow `structured_output` tool). Capturing the raw CAPI stream confirmed that Gemini serializes array/object function-call arguments as **flattened indexed keys** on the wire — for example `{ keywords: ["a", "b"] }` arrives as `{ "keywords[0]": "a", "keywords[1]": "b" }` — so schema validation failed (`keywords: must have required properties keywords` and `root: must not have additional properties`) and the model re-emitted the same shape forever. Atomic now reconstructs flattened tool-call arguments (`name[i]`, `name[i].sub`, `parent.child`) back into proper arrays/objects in each tool's `prepareArguments` step, before validation runs. Gated to GitHub Copilot Gemini models at call time and a no-op for well-formed arguments, so it covers built-in, extension, SDK, and MCP tools without affecting any other provider/model.
 - Fixed `github-copilot/*` Gemini models (for example `github-copilot/gemini-3.1-pro-preview`) silently dying mid-task instead of continuing the turn. Inspecting the affected sessions and confirming against GitHub's Copilot API (CAPI) source showed two distinct degenerate stream endings that Atomic was not recovering from: (1) CAPI's `getAzureFinishReason` maps several Gemini finish reasons — `MALFORMED_FUNCTION_CALL`, `OTHER`, `LANGUAGE`, and `UNEXPECTED_TOOL_CALL` — to a bare OpenAI `finish_reason: "error"`, which `pi-ai` surfaces as `"Provider finish_reason: error"`; the auto-retry classifier's regex did not match it, so the turn ended with an empty assistant message and no retry; and (2) Gemini intermittently ends the stream with `finish_reason: "stop"`, an **empty content array**, and **0 output tokens**, which Atomic treated as a successful (if empty) turn and stopped. Atomic now treats bare `finish_reason: error`/`content_filter` as retryable and detects degenerate empty completions (no text/tool-call/thinking content **and** zero output tokens on a `stop`/`toolUse` turn) as retryable, re-issuing the request with the existing exponential-backoff path. Empty `stop` completions also no longer reset the auto-retry counter, so repeated empties stay bounded by `maxRetries` instead of retrying forever.

package/dist/builtin/cursor/CHANGELOG.md

@@ -4,7 +4,7 @@
 
 ### Changed
 
-- Published a synchronized Atomic 0.8.31-alpha.3 prerelease; no functional Cursor provider changes were made after 0.8.30.
+- Published a synchronized Atomic 0.8.31-alpha.5 prerelease; no functional Cursor provider changes were made after 0.8.30.
 
 ## [0.8.30] - 2026-06-17
 

package/dist/builtin/cursor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/cursor",
-  "version": "0.8.31-alpha.4",
+  "version": "0.8.31-alpha.5",
   "private": true,
   "description": "Experimental first-party Atomic extension for Cursor OAuth, model discovery, and streaming provider registration.",
   "contributors": [
@@ -40,7 +40,7 @@
     }
   },
   "dependencies": {
-    "@bastani/atomic-natives": "0.8.31-alpha.4",
+    "@bastani/atomic-natives": "0.8.31-alpha.5",
     "@bufbuild/protobuf": "^2.0.0"
   }
 }

package/dist/builtin/intercom/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/intercom",
-  "version": "0.8.31-alpha.4",
+  "version": "0.8.31-alpha.5",
   "private": true,
   "description": "Atomic extension providing a private coordination channel between parent and child agent sessions. Fork of: https://github.com/nicobailon/pi-intercom",
   "contributors": [

package/dist/builtin/mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/mcp",
-  "version": "0.8.31-alpha.4",
+  "version": "0.8.31-alpha.5",
   "private": true,
   "description": "Atomic extension that adapts MCP (Model Context Protocol) servers into the coding agent. Fork of: https://github.com/nicobailon/pi-mcp-adapter",
   "contributors": [

package/dist/builtin/subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/subagents",
-  "version": "0.8.31-alpha.4",
+  "version": "0.8.31-alpha.5",
   "private": true,
   "description": "Atomic extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification. Fork of: https://github.com/nicobailon/pi-subagents",
   "contributors": [

package/dist/builtin/web-access/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/web-access",
-  "version": "0.8.31-alpha.4",
+  "version": "0.8.31-alpha.5",
   "private": true,
   "description": "Atomic extension for web search, URL fetching, GitHub repo cloning, PDF/video extraction. Fork of: https://github.com/nicobailon/pi-web-access",
   "contributors": [

package/dist/builtin/workflows/CHANGELOG.md

@@ -12,6 +12,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ### Added
 
+- Added a deterministic workflow-stage resume stop hook: after an interactive interrupt/pause is resumed with a message, the executor suppresses the #1099/#1264 readiness prompt for that resume-answer turn (including `ask_user_question` turns) and, when the stage remains promptable, sends `Continue where you left off.` in the same stage session once per resume; schema-backed stages that already finalized with `structured_output` consume the token without a second prompt ([#1407](https://github.com/bastani-inc/atomic/issues/1407)).
 - Added a QA end-to-end proof video to the builtin `ralph` workflow. For UI-applicable or full-stack changes, the orchestrator now runs a `playwright-cli` end-to-end QA pass that drives the running app like a user, records a reviewable video (`playwright-cli video-start`/`video-stop`) to a stable run path, references it in the implementation notes (`## QA E2E Video`), and exposes it as the new optional `qa_video_path` output so the proof is available when the orchestrator finishes. When `create_pr=true`, the final `pull-request` stage attaches or links that video to the created PR/MR/review (embedding/linking where the provider supports media uploads, otherwise surfacing the absolute path). When no user-visible UI scenario applies, no video is produced and the notes record why.
 - Added a per-model context-window authoring token to workflow model strings: a parenthesized size token placed in the model-name portion, *before* the optional `:reasoning` suffix, e.g. `github-copilot/claude-opus-4.8 (1m):xhigh`. Adopting GitHub Copilot's `Claude Opus 4.8 (1M context)` naming convention keeps the window separate from the reasoning level so the two never collide. The token is resolved against the candidate model's advertised windows — an exact match wins, otherwise the largest supported window not exceeding the request (so `(1m)` selects a model's ~936K long-context tier), and it falls back to the model's default (short) window when no larger tier is available. It applies only to the candidate that carries the token, leaving primary and other fallback models untouched. Also surfaced `contextWindow`/`contextWindowStrict` on `StageOptions` and the workflow tool's direct-task schema for stage-level selection.
 
@@ -24,6 +25,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ### Fixed
 
+- Fixed workflow stage transcripts ignoring the host's resolved non-default session directory in headless runs. Stages without an explicit `sessionDir` now inherit the active main-session directory when it comes from `--session-dir`, `ATOMIC_CODING_AGENT_SESSION_DIR`, or settings; explicit per-stage `sessionDir` still wins, default host sessions keep writing stages to the global store, and forked stages inherit the non-default directory too ([#1444](https://github.com/bastani-inc/atomic/issues/1444)).
+- Fixed a manual workflow pause/resume not updating the main-chat run status the way the `workflow` tool and `/workflow pause`/`/workflow resume` do. Pausing a stage from the attached stage chat (Escape) or any direct live-handle path recorded only the **stage** as paused (`recordStagePaused`) and never the **run** (`recordRunPaused`), so the below-editor status widget and `/workflow status` kept showing the run as `running` (`●`) even though work was paused; resume had the symmetric gap. The executor stage-control handle now records run-level pause/resume itself — marking the run paused once no stage is still actively running (mirroring `pauseRun`'s all-active-stages-paused rule) and restoring it on resume — so manual and tool-driven pause/resume update the main chat identically. Both run-level transitions are idempotent, so the tool/slash path and cascade re-entry stay safe.
+- Fixed the builtin `ralph` workflow review loop iterating until `max_loops` even when reviewers judged the patch correct. The unanimous-approval gate required a literally empty `findings` array, so a single low-priority **P3** nit — or a placeholder/dummy finding a reviewer appended because it wrongly believed an empty array would fail schema validation — kept the loop spinning despite every reviewer reporting `overall_correctness: "patch is correct"`. Approval is now **severity-aware and deterministic**: a reviewer approves when it judged the patch correct, reported no `reviewer_error`, and filed no *blocking* finding, where blocking = **P0/P1/P2** (priority 0/1/2) and **P3** (priority 3) is a non-blocking nice-to-have; a finding without a determinable priority (`null`/`undefined`) is treated as blocking so ambiguity never silently approves. The decision is computed from finding priorities rather than the reviewer's self-reported `stop_review_loop` flag. Extracted the gate into `builtin/ralph-review-gate.ts` (`reviewDecisionApproved`, `isBlockingFinding`) with unit coverage, and updated the reviewer prompt so an empty `findings` array is explicitly valid and placeholder findings are never fabricated ([#1407](https://github.com/bastani-inc/atomic/issues/1407)).
 - Fixed workflow stage **model fallback misreporting configured providers as `No API key found`**. Each fallback candidate session was created with a fresh `AuthStorage`/`ModelRegistry`, so after a primary model failed (for example the Ralph `reviewer-a` chain hitting an unavailable `anthropic/claude-fable-5` and getting a real provider 404), every fallback candidate re-read `auth.json` from scratch. Under concurrent reviewer stages and OAuth token refreshes holding the `auth.json` lock, that fresh synchronous reload could fail and silently fall back to an empty credential set, reporting `No API key found` for `anthropic`/`openai-codex`/`github-copilot` even while sibling reviewer stages used those exact providers successfully. A stage now captures the `ModelRegistry` (and its already-loaded `AuthStorage`) from its first session and threads it into every subsequent fallback candidate, so a successfully-loaded credential store is reused across the whole fallback chain instead of being discarded and re-loaded per candidate. Combined with the coding-agent change that surfaces a real credential-store load failure instead of `No API key found`, a transient store-read failure remains a recoverable/retryable auth failure ([#1431](https://github.com/bastani-inc/atomic/issues/1431)).
 - Fixed post-completion workflow follow-ups replaying the entire model-fallback chain from an unavailable primary instead of resuming on the model the stage settled on. After model fallback succeeded, the stage kept its working `session` but left `sessionPromise` undefined, and `ensureSession()` only checked `sessionPromise` — so a follow-up (`ctx.followUp`/`ctx.steer`/`ensureAttached`, and post-completion `workflow send`/TUI prompts) created a brand-new session from `candidates[0]` (the primary), discarding the working fallback session. For a chain whose primary 404s (e.g. `anthropic/claude-fable-5`), every follow-up re-ran `primary -> 404 -> ... -> working model` and could leave the stage stuck on the unavailable primary. `ensureSession()` now reuses an already-attached session, and `promptWithFallback()` retries the last-settled model first (for both live retained sessions and disk-reattached sessions), restarting the full chain from the primary only if that model fails again retryably ([#1431](https://github.com/bastani-inc/atomic/issues/1431)).
 

package/dist/builtin/workflows/builtin/ralph-review-gate.ts

@@ -0,0 +1,89 @@
+/**
+ * Review-gate severity logic for the builtin `ralph` workflow.
+ *
+ * The bounded review loop must stop as soon as the patch is judged correct, even
+ * when a reviewer leaves a low-priority nit (or, occasionally, appends a
+ * placeholder finding because it wrongly believed an empty `findings` array would
+ * fail schema validation). Requiring a literally empty `findings` array made the
+ * loop iterate forever in those cases despite unanimous "patch is correct"
+ * verdicts.
+ *
+ * Approval is therefore severity-aware and deterministic. A single reviewer
+ * approves when it judged the patch correct, reported no `reviewer_error`, and
+ * filed no *blocking* finding:
+ *
+ * - Blocking  = P0/P1/P2 (numeric priority 0, 1, or 2).
+ * - Non-blocking = P3 (numeric priority 3) — a nice-to-have that should not keep
+ *   the loop spinning.
+ * - A finding whose priority cannot be determined (`null`/`undefined`) is treated
+ *   as blocking, so genuine ambiguity never silently approves.
+ *
+ * The decision is computed from the structured findings rather than the
+ * reviewer's self-reported `stop_review_loop` boolean, so the gate does not
+ * depend on the model correctly deriving that flag.
+ */
+
+export type ReviewFinding = {
+  readonly title: string;
+  readonly body: string;
+  readonly confidence_score: number;
+  readonly priority?: number | null;
+  readonly code_location: {
+    readonly absolute_file_path: string;
+    readonly line_range: {
+      readonly start: number;
+      readonly end: number;
+    };
+  };
+};
+
+export type ReviewerError = {
+  readonly kind:
+    | "validation_unavailable"
+    | "dependency_unavailable"
+    | "tool_failure"
+    | "reviewer_failure";
+  readonly message: string;
+  readonly attempted_recovery: string;
+};
+
+export type ReviewDecision = {
+  readonly findings: readonly ReviewFinding[];
+  readonly overall_correctness: "patch is correct" | "patch is incorrect";
+  readonly overall_explanation: string;
+  readonly overall_confidence_score: number;
+  readonly stop_review_loop: boolean;
+  readonly reviewer_error?: ReviewerError | null;
+};
+
+/**
+ * Highest finding priority that still blocks approval. P0=0, P1=1, P2=2 block;
+ * P3=3 does not.
+ */
+export const MAX_BLOCKING_PRIORITY = 2;
+
+/**
+ * True when a finding must keep the review loop iterating. P0/P1/P2 block; P3 is
+ * a non-blocking nice-to-have. A finding without a determinable priority
+ * (`null`/`undefined`) is treated as blocking so ambiguity never silently
+ * approves.
+ */
+export function isBlockingFinding(finding: ReviewFinding): boolean {
+  const priority = finding.priority;
+  if (priority === undefined || priority === null) return true;
+  return priority <= MAX_BLOCKING_PRIORITY;
+}
+
+/**
+ * A single reviewer approves (would stop the loop) when it judged the patch
+ * correct, surfaced no reviewer execution error, and filed no blocking
+ * (P0/P1/P2) finding. P3 nice-to-haves and placeholder/dummy findings do not
+ * block approval.
+ */
+export function reviewDecisionApproved(decision: ReviewDecision): boolean {
+  return (
+    decision.overall_correctness === "patch is correct" &&
+    decision.reviewer_error == null &&
+    !decision.findings.some(isBlockingFinding)
+  );
+}

package/dist/builtin/workflows/builtin/ralph.ts

@@ -18,6 +18,7 @@ import type {
   WorkflowTaskResult,
 } from "../src/shared/types.js";
 import { E2E_VERIFICATION_GUIDANCE, WORKER_PREFLIGHT_CONTRACT } from "./shared-prompts.js";
+import { reviewDecisionApproved, type ReviewDecision } from "./ralph-review-gate.js";
 
 const DEFAULT_MAX_LOOPS = 10;
 const DEFAULT_RESEARCH_DIR = "research";
@@ -25,44 +26,15 @@ const IMPLEMENTATION_NOTES_FILENAME = "implementation-notes.md";
 const QA_E2E_VIDEO_FILENAME = "qa-e2e-evidence.webm";
 const MAX_RESEARCH_SLUG_LENGTH = 80;
 // Reviewer fan-out launches three independent reviewers; the loop stops only when
-// all three reviewers independently approve (find no issues). Requiring unanimous
-// approval means a P0–P3 finding from any single reviewer keeps the loop iterating
-// instead of being out-voted by a majority, so lower-severity issues stay surfaced.
+// all three reviewers independently approve. Approval is severity-aware: a
+// reviewer approves when it judged the patch correct, reported no reviewer_error,
+// and filed no *blocking* (P0/P1/P2) finding. P3 nice-to-haves no longer keep the
+// loop iterating, so a single low-priority nit (or a placeholder finding) can no
+// longer strand an otherwise-approved patch. Requiring unanimous approval still
+// means a blocking finding from any one reviewer keeps the loop going. See
+// ./ralph-review-gate.ts for the gate types and decision logic.
 const REVIEWER_COUNT = 3;
 
-type ReviewFinding = {
-  readonly title: string;
-  readonly body: string;
-  readonly confidence_score: number;
-  readonly priority?: number | null;
-  readonly code_location: {
-    readonly absolute_file_path: string;
-    readonly line_range: {
-      readonly start: number;
-      readonly end: number;
-    };
-  };
-};
-
-type ReviewerError = {
-  readonly kind:
-    | "validation_unavailable"
-    | "dependency_unavailable"
-    | "tool_failure"
-    | "reviewer_failure";
-  readonly message: string;
-  readonly attempted_recovery: string;
-};
-
-type ReviewDecision = {
-  readonly findings: readonly ReviewFinding[];
-  readonly overall_correctness: "patch is correct" | "patch is incorrect";
-  readonly overall_explanation: string;
-  readonly overall_confidence_score: number;
-  readonly stop_review_loop: boolean;
-  readonly reviewer_error?: ReviewerError | null;
-};
-
 const reviewFindingSchema = Type.Object(
   {
     title: Type.String(),
@@ -220,15 +192,6 @@ function reviewDecisionFromResult(result: WorkflowTaskResult): ReviewDecision |
   return result.structured as ReviewDecision | undefined;
 }
 
-function reviewDecisionApproved(decision: ReviewDecision): boolean {
-  return (
-    decision.stop_review_loop === true &&
-    decision.overall_correctness === "patch is correct" &&
-    decision.findings.length === 0 &&
-    decision.reviewer_error == null
-  );
-}
-
 function reviewerErrorDecision(error: string): ReviewDecision {
   return {
     findings: [],
@@ -785,14 +748,14 @@ async function runRalphWorkflow(
           "Speculation is insufficient: identify the code path, scenario, environment, or input that is provably affected.",
           "Do not flag intentional behavior changes as bugs unless they clearly violate the task or documented contract.",
           "Ignore trivial style unless it obscures meaning or violates documented standards in a way that affects correctness/security/maintainability.",
-          "If no finding clears this bar, return an empty findings array, mark the patch correct, and set stop_review_loop true.",
+          "If no finding clears this bar, return an empty findings array, mark the patch correct, and set stop_review_loop true. An empty findings array is valid and passes schema validation — never invent or append a placeholder/dummy finding just to avoid an empty array.",
         ].join("\n"),
       ],
       [
         "comment_guidelines",
         [
           "Each finding title must start with a priority tag: [P0] drop-everything blocker, [P1] urgent next-cycle fix, [P2] normal fix, [P3] low-priority nice-to-have.",
-          "Also include numeric priority: 0 for P0, 1 for P1, 2 for P2, 3 for P3; use null only if priority genuinely cannot be determined.",
+          "Also include numeric priority: 0 for P0, 1 for P1, 2 for P2, 3 for P3; use null only if priority genuinely cannot be determined. Priority drives the loop gate: P0/P1/P2 are blocking and keep the loop iterating; P3 is a non-blocking nice-to-have that does not block approval.",
           "The body must be one concise paragraph explaining why this is a bug and the exact scenario, environment, or inputs required for it to arise.",
           "Use a matter-of-fact, non-accusatory tone. Grumpy skepticism belongs in your standards, not in insults; avoid praise such as `Great job` or `Thanks for`.",
           "Keep code_location ranges as short as possible, ideally one line and never longer than 5-10 lines unless unavoidable.",
@@ -805,7 +768,7 @@ async function runRalphWorkflow(
         "how_many_findings",
         [
           "Return all findings the original author would definitely want to fix.",
-          "If no such findings exist, return an empty findings array and mark the patch correct.",
+          "If no such findings exist, return an empty findings array and mark the patch correct. Do not pad the array with placeholder or speculative findings.",
           "Do not stop after the first qualifying finding; continue until every qualifying finding is listed.",
         ].join("\n"),
       ],
@@ -836,7 +799,7 @@ async function runRalphWorkflow(
       [
         "decision_rules",
         [
-          "Set stop_review_loop=true only when findings is empty, overall_correctness is patch is correct, and reviewer_error is null/omitted.",
+          "Set stop_review_loop=true when the patch is correct, reviewer_error is null/omitted, and there are no blocking (P0/P1/P2) findings; remaining P3 nice-to-haves do not block approval. The loop gate is computed from finding priorities, so an unresolved P0/P1/P2 keeps the loop going regardless of this flag.",
           "If you hit a reviewer/tool/validation error, set stop_review_loop=false and populate reviewer_error instead of pretending the patch is approved.",
         ].join("\n"),
       ],
@@ -908,8 +871,9 @@ async function runRalphWorkflow(
     ).length;
     // Require unanimous approval: every reviewer must have run and independently
     // approved. A fan-out error that collapses to a single error entry (fewer than
-    // REVIEWER_COUNT reviews) or any reviewer surfacing a finding keeps the loop
-    // iterating rather than letting a majority paper over outstanding issues.
+    // REVIEWER_COUNT reviews) or any reviewer surfacing a blocking (P0/P1/P2)
+    // finding keeps the loop iterating rather than letting a majority paper over
+    // outstanding issues. P3 nice-to-haves do not block approval.
     approved =
       reviewEntries.length === REVIEWER_COUNT &&
       approvalCount === REVIEWER_COUNT;

package/dist/builtin/workflows/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/workflows",
-  "version": "0.8.31-alpha.4",
+  "version": "0.8.31-alpha.5",
   "private": true,
   "description": "Atomic extension for multi-stage workflow authoring and execution.",
   "contributors": [

package/dist/builtin/workflows/src/extension/dispatcher.ts

@@ -69,6 +69,8 @@ export interface DispatcherOpts {
   policy?: WorkflowExecutionPolicy;
   /** Invocation cwd used for workflow execution. */
   cwd?: string;
+  /** Host-resolved non-default session directory inherited by stages without explicit sessionDir. */
+  defaultSessionDir?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -173,6 +175,7 @@ export async function dispatch(
         models: opts.models,
         executionMode: policy.mode,
         cwd: opts.cwd,
+        defaultSessionDir: opts.defaultSessionDir,
       });
       if (policy.awaitTerminalRun === true) {
         const tracker = opts.jobs ?? defaultJobTracker;

package/dist/builtin/workflows/src/extension/index.ts

@@ -2562,6 +2562,17 @@ function factory(pi: ExtensionAPI): void {
         : undefined,
     parentSession: () => intercomParentSession ?? undefined,
   };
+  const hostStageSessionDir: { current: string | undefined } = { current: undefined };
+  const resolveDefaultStageSessionDir = (): string | undefined => hostStageSessionDir.current;
+  const updateHostStageSessionDir = (sessionManager: SessionManager | undefined): void => {
+    try {
+      hostStageSessionDir.current = sessionManager?.usesDefaultSessionDir?.() === false
+        ? sessionManager.getSessionDir?.()
+        : undefined;
+    } catch {
+      hostStageSessionDir.current = undefined;
+    }
+  };
 
   const startupDiscovery = discoverStartupWorkflowsSync();
   const runtimeRef: { current: ExtensionRuntime } = {
@@ -2574,6 +2585,7 @@ function factory(pi: ExtensionAPI): void {
       mcp: mcpPort,
       intercom: intercomPort,
       config: runtimeConfigRef.current,
+      resolveDefaultStageSessionDir,
     }),
   };
   const discoveryRef: { current: DiscoveryResult | null } = { current: null };
@@ -2641,6 +2653,7 @@ function factory(pi: ExtensionAPI): void {
       intercom: intercomPort,
       config: runtimeConfigRef.current,
       models,
+      resolveDefaultStageSessionDir,
     });
   }
 
@@ -2735,6 +2748,7 @@ function factory(pi: ExtensionAPI): void {
       mcp: mcpPort,
       intercom: intercomPort,
       config: runtimeConfigRef.current,
+      resolveDefaultStageSessionDir,
     });
   }
 
@@ -4025,6 +4039,7 @@ function factory(pi: ExtensionAPI): void {
       }
 
       const sessionManager = ctx?.sessionManager ?? pi.sessionManager;
+      updateHostStageSessionDir(sessionManager);
       if (sessionManager) {
         const cfg = configLoadRef.current?.config;
         withWorkflowLifecycleNotificationsSuppressed(

package/dist/builtin/workflows/src/extension/runtime.ts

@@ -86,6 +86,8 @@ export interface ExtensionRuntimeOpts {
   jobs?: JobTracker;
   /** Invocation cwd used for workflow execution. Defaults to process.cwd(). */
   cwd?: string;
+  /** Resolve the host's non-default session directory for workflow stage transcripts. */
+  resolveDefaultStageSessionDir?: () => string | undefined;
 }
 
 // ---------------------------------------------------------------------------
@@ -149,6 +151,7 @@ export function createExtensionRuntime(opts: ExtensionRuntimeOpts = {}): Extensi
   const models = opts.models;
   const jobs = opts.jobs;
   const runtimeCwd = opts.cwd ?? process.cwd();
+  const resolveDefaultStageSessionDir = opts.resolveDefaultStageSessionDir;
 
   function runOptions(args: WorkflowToolArgs, policy?: WorkflowExecutionPolicy): RunOpts {
     const argConcurrency =
@@ -166,6 +169,7 @@ export function createExtensionRuntime(opts: ExtensionRuntimeOpts = {}): Extensi
             ...(config?.statusFilePath !== undefined ? { statusFilePath: config.statusFilePath } : {}),
             resumeInFlight: config?.resumeInFlight ?? "ask",
           };
+    const defaultSessionDir = resolveDefaultStageSessionDir?.();
     return {
       adapters,
       store: activeStore,
@@ -174,6 +178,7 @@ export function createExtensionRuntime(opts: ExtensionRuntimeOpts = {}): Extensi
       mcp,
       config: effectiveConfig,
       models,
+      ...(defaultSessionDir !== undefined ? { defaultSessionDir } : {}),
       ...(policy !== undefined ? { executionMode: policy.mode } : {}),
       registry,
       cwd: runtimeCwd,
@@ -510,6 +515,7 @@ export function createExtensionRuntime(opts: ExtensionRuntimeOpts = {}): Extensi
     },
 
     dispatch(args: WorkflowToolArgs, options?: RuntimeDispatchOptions): Promise<WorkflowToolResult> {
+      const defaultSessionDir = resolveDefaultStageSessionDir?.();
       return dispatch(args, {
         registry,
         adapters,
@@ -522,6 +528,7 @@ export function createExtensionRuntime(opts: ExtensionRuntimeOpts = {}): Extensi
         models,
         policy: options?.policy,
         cwd: runtimeCwd,
+        ...(defaultSessionDir !== undefined ? { defaultSessionDir } : {}),
       });
     },
 

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

@@ -121,6 +121,8 @@ export interface RunOpts extends Omit<AuthoringContract.RunOpts, "adapters" | "s
   ui?: WorkflowUIAdapter;
   /** Runtime execution mode. Controls child session policy metadata. */
   executionMode?: WorkflowExecutionMode;
+  /** Host-resolved non-default session directory inherited by stages without explicit sessionDir. */
+  defaultSessionDir?: string;
   /** Internal detached-run mode: surface ctx.ui.* as node-local workflow prompt stages. */
   usePromptNodesForUi?: boolean;
   /**
@@ -1003,6 +1005,24 @@ export function toolResultHasChatAnswer(result: unknown): boolean {
   );
 }
 
+// ---------------------------------------------------------------------------
+// Resume continuation hook (#1407)
+// ---------------------------------------------------------------------------
+// When an interactive paused stage is resumed with a user message, the resumed
+// answer turn should be followed by one deterministic same-session nudge so the
+// model returns to the interrupted work without showing the readiness gate for
+// the resume-answer turn itself.
+
+export const RESUME_CONTINUATION_PROMPT = "Continue where you left off.";
+
+export function shouldInjectResumeContinuation(state: {
+  readonly resumeOccurred: boolean;
+  readonly gateEnabled: boolean;
+  readonly aborted: boolean;
+}): boolean {
+  return state.resumeOccurred && state.gateEnabled && !state.aborted;
+}
+
 let cachedReadinessGateTool: ReturnType<typeof createAskUserQuestionToolDefinition> | undefined;
 function readinessGateTool(): ReturnType<typeof createAskUserQuestionToolDefinition> {
   return (cachedReadinessGateTool ??= createAskUserQuestionToolDefinition());
@@ -4199,6 +4219,7 @@ export async function run<TInputs extends WorkflowInputValues>(
           __requestPause: async () => rejectReplayMutation("pause"),
           __resume: async () => rejectReplayMutation("resume"),
           __isPaused: () => false,
+          __structuredOutputFinalized: () => false,
         };
         return replayContext;
       }
@@ -4233,6 +4254,7 @@ export async function run<TInputs extends WorkflowInputValues>(
         stageOptions: stageOptionsForContext,
         models: opts.models,
         executionMode: opts.executionMode,
+        defaultSessionDir: opts.defaultSessionDir,
         onModelFallbackMetaChange(meta) {
           applyModelFallbackMeta(meta);
           if (stageSnapshot.status === "running") {
@@ -4251,6 +4273,12 @@ export async function run<TInputs extends WorkflowInputValues>(
       // When true the readiness gate is bypassed — the stage stays in the
       // composer without showing an extra confirmation UI (#1264).
       let chatAnswerObservedThisTurn = false;
+      // Saturated one-slot marker for the latest real pause->resume(message)
+      // transition that still needs the deterministic same-session continuation
+      // prompt (#1407). Later paused resumes before the same post-turn drain
+      // supersede earlier unfinished resumes; the slot is consumed before
+      // prompting so a pause/resume of the continuation turn can set it again.
+      let resumeContinuationPending = false;
       const hasActiveAskUserQuestion = (): boolean =>
         activeAskUserQuestionCalls.size > 0 || activeAskUserQuestionAnonymousCalls > 0;
       const unsubscribeAskUserQuestionWatcher = innerCtx.subscribe((event) => {
@@ -4421,6 +4449,18 @@ export async function run<TInputs extends WorkflowInputValues>(
           if (changed) {
             ensureReleaseBarrier(stageId);
             await cascadePauseFrom(stageId);
+            // Mark the run paused once no stage is still actively running,
+            // mirroring pauseRun() (runs/background/status.ts). This keeps a
+            // manual TUI/Escape pause updating run-level status — and therefore
+            // the main-chat status widget and `/workflow status` — identically
+            // to the `workflow` tool and `/workflow pause`. recordRunPaused is
+            // idempotent, so double-recording from the tool/slash path or from
+            // cascade re-entry is safe.
+            const run = activeStore.runs().find((candidate) => candidate.id === runId);
+            const stillActive = run?.stages.some(
+              (s) => s.status === "running" && s.id !== stageId,
+            ) ?? false;
+            if (!stillActive) activeStore.recordRunPaused(runId);
           }
           if (statusBeforePause === "pending" || statusBeforePause === "running" || innerCtx.isStreaming) {
             await innerCtx.__requestPause();
@@ -4429,13 +4469,30 @@ export async function run<TInputs extends WorkflowInputValues>(
         async resume(message?: string) {
           throwIfStageMutationBlocked();
           await ensureMessagingSession();
-          const changed = activeStore.recordStageResumed(runId, stageId);
-          if (changed) {
-            releaseStageBarrier(stageId);
-            await cascadeResumeFrom(stageId);
+          const wasPausedBeforeResume = innerCtx.__isPaused();
+          const hasResumeContinuationMessage = typeof message === "string" && message.trim().length > 0;
+          const previousResumeContinuationPending = resumeContinuationPending;
+          const queuedResumeContinuation = wasPausedBeforeResume && hasResumeContinuationMessage;
+          if (queuedResumeContinuation) {
+            resumeContinuationPending = true;
           }
           try {
+            const changed = activeStore.recordStageResumed(runId, stageId);
+            if (changed) {
+              releaseStageBarrier(stageId);
+              await cascadeResumeFrom(stageId);
+              // Restore run-level status so a manual resume updates the main chat
+              // like the `workflow` tool / `/workflow resume`. recordRunResumed is
+              // a no-op when the run is not paused, so this is safe under cascade
+              // and the tool/slash path.
+              activeStore.recordRunResumed(runId);
+            }
             await innerCtx.__resume(message);
+          } catch (err) {
+            if (queuedResumeContinuation) {
+              resumeContinuationPending = previousResumeContinuationPending;
+            }
+            throw err;
           } finally {
             captureStageSessionMeta();
           }
@@ -4584,7 +4641,44 @@ export async function run<TInputs extends WorkflowInputValues>(
         }
       };
 
-      const runTrackedStageCall = async (call: () => Promise<string>, eagerSession = false): Promise<string> => {
+      const suppressReadinessForCurrentTurn = (): void => {
+        askUserQuestionObservedThisTurn = false;
+        chatAnswerObservedThisTurn = false;
+      };
+
+      const skipResumeContinuationInjection = (): boolean => {
+        if (stageFinalized) return true;
+        if (skippedForParallelFailFast) return true;
+        if (stageSnapshot.status === "skipped" && stageSnapshot.skippedReason === "fail-fast") return true;
+        if (isTerminalStage(stageSnapshot)) return true;
+        if (stageFailFastScope?.failed === true && stageFailFastScope.activeStages.has(stageId)) return true;
+        // A schema-backed stage can finalize during the resumed answer turn by
+        // calling structured_output. That consumes the resume slot and
+        // suppresses readiness for the resume-answer turn, but a second prompt
+        // would violate the one-prompt schema contract.
+        if (innerCtx.__structuredOutputFinalized()) return true;
+        return false;
+      };
+
+      const drainResumeContinuations = async <T>(currentResult: T): Promise<T> => {
+        let result = currentResult;
+        while (resumeContinuationPending) {
+          resumeContinuationPending = false;
+          suppressReadinessForCurrentTurn();
+          if (!shouldInjectResumeContinuation({
+            resumeOccurred: true,
+            gateEnabled: readinessGateEnabled,
+            aborted: ownController.signal.aborted,
+          })) {
+            continue;
+          }
+          if (skipResumeContinuationInjection()) continue;
+          result = await raceAbort(innerCtx.prompt(RESUME_CONTINUATION_PROMPT), ownController.signal) as T;
+        }
+        return result;
+      };
+
+      const runTrackedStageCall = async <T>(call: () => Promise<T>, eagerSession = false): Promise<T> => {
         throwIfWorkflowExitSelected();
         await waitForStageRelease();
         if (stageFinalized) {
@@ -4661,12 +4755,13 @@ export async function run<TInputs extends WorkflowInputValues>(
           };
           if (ownController.signal.aborted) abortSession();
           else ownController.signal.addEventListener("abort", abortSession, { once: true });
-          let result = "";
+          let result: T;
           try {
             // Run the stage's initial agent turn.
             askUserQuestionObservedThisTurn = false;
             chatAnswerObservedThisTurn = false;
             result = await raceAbort(call(), ownController.signal);
+            result = await drainResumeContinuations(result);
 
             // Per-turn readiness gate (#1099). When an agent turn ENDS (control
             // returns to the user): if the turn issued no ask_user_question
@@ -4706,7 +4801,8 @@ export async function run<TInputs extends WorkflowInputValues>(
                     ownController.signal,
                   );
                   if (ownController.signal.aborted) break;
-                  result = innerCtx.__getLastAssistantText() ?? result;
+                  result = (innerCtx.__getLastAssistantText() ?? result) as T;
+                  result = await drainResumeContinuations(result);
                 }
               } finally {
                 resolveNextTurnEnd = null;