@bastani/atomic 0.9.5-alpha.7 → 0.9.5-alpha.9

package/dist/builtin/workflows/src/extension/workflow-command-surfaces.ts

@@ -45,6 +45,15 @@ export function emitTerminalRunDetailSurface(
   emitChatSurface(pi, { kind: "detail", detail }, { content: renderRunDetail(detail, { width: 100 }) });
 }
 
+
+export function formatWorkflowResourceLoadWarning(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error);
+  return [
+    "Workflow discovery diagnostics: workflow resources could not be fully refreshed.",
+    `- [error DISCOVERY_FAILED] workflow discovery: ${message}`,
+    "Using the currently loaded workflow registry; run `/workflow reload` after fixing the issue.",
+  ].join("\n");
+}
 export function formatStartupDiagnostics(
   configResult: ConfigLoadResult | null,
   discoveryResult: DiscoveryResult | null,

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

@@ -25,6 +25,8 @@ export const DEFAULT_PROMPT_GUIDANCE: string[] = [
   - For transcripts, avoid reading whole session transcripts at once. Use \`stages\` or \`stage\` to get \`sessionFile\`/\`transcriptPath\`, quote the exact path without rewriting separators (preserve Windows backslashes), search it with \`rg\`/\`grep\`, and read small relevant ranges; use \`transcript\` with explicit \`tail\` or \`limit\` only for quick recent-context checks.
   - If a user asks to create or edit a workflow, use the create-spec skill when available and ask detailed clarifying questions until you understand its purpose, inputs, stages, handoffs, validation, success criteria, and selected starter pattern. Then read the workflow docs/examples and implement the workflow from the created spec directly as a TypeScript definition. After you implement the workflow, reload it to access it and run it with test inputs to validate it works as intended before presenting it to the user.
     - Tip: when designing workflows, implement it in a way that you pass information from stage to stage by writing it to a file or artifact (either deterministic or model-driven), pass the path with \`reads\`, and explicitly prompt the downstream agent with wording like \`Read the file at <path>...\`; do not inject large \`previous\` payloads or session history into the next prompt unless explicitly requested to.
+    - When designing reviewer-gated workflows, distinguish implementation/review acceptance from post-approval final actions such as PR/MR/review creation, release tagging, deployment, or publication. Prompt reviewers/reducers to approve and stop the implementation loop when implementation and validation criteria are proven and only an explicitly authorized final action remains; carry that remainder as a next action or final-action field instead of another implementation turn.
+    - When authoring workflow, stage, reviewer, or reducer prompts, remember that a model stage sees its local prompt, artifacts, tools, and reads — not the workflow graph's name or surrounding implementation details unless you explicitly provide them. Describe the concrete action, available evidence, and success criteria directly (for example "review the current code delta" or "create/update the review request") instead of asking the model to reason from labels like "the create-PR workflow stage", "this Goal run", or "the Ralph reviewer". Use workflow or stage names only when the name itself is user-visible context or materially affects behavior.
   - Prefer the \`goal\` workflow for small-to-medium non-trivial one-off fixes, debugging, docs/code changes, scoped multi-file edits, or test/fix loops when you can name the work surface, outcome, and validation; prefer the \`ralph\` workflow for larger/riskier work, migrations, new features, broad refactors, multi-package changes, or tasks estimated over ~2K LoC.
     - Adjust \`goal.max_turns\` for Goal runs and \`ralph.max_loops\` for Ralph runs based on task complexity (estimated LoC, risk, validation effort, and number of unique files/areas touched).
     - Define an objective that includes tight scope, concrete and verifiable done criteria, and validation steps; then monitor progress as above instead of doing parallel implementation yourself.`,

package/dist/builtin/workflows/src/extension/workflow-run-control-command.ts

@@ -22,12 +22,14 @@ import {
   resolveRunIdPrefix,
   resolveStageTarget,
 } from "./workflow-targets.js";
+import { formatWorkflowResourceLoadWarning } from "./workflow-command-surfaces.js";
 
 export interface WorkflowRunControlDeps {
   pi: ExtensionAPI;
   overlay: GraphOverlayPort;
   getPersistence: () => WorkflowPersistencePort | undefined;
   runtimeForContext: (ctx?: PiCommandContext) => ExtensionRuntime;
+  ensureWorkflowResourcesLoaded: () => Promise<void> | void;
 }
 
 function resolveAttachStageId(runId: string, stageTarget: string | undefined): string | undefined | false {
@@ -61,6 +63,11 @@ async function handleDurableResume(
 ): Promise<boolean> {
   const print = (msg: string): void => reporter.info(msg);
   const fail = (msg: string): void => reporter.error(msg);
+  try {
+    await deps.ensureWorkflowResourcesLoaded();
+  } catch (error) {
+    ctx.ui?.notify(formatWorkflowResourceLoadWarning(error), "warning");
+  }
   const runtime = deps.runtimeForContext(ctx);
   const policy = workflowPolicyFromContext(ctx);
   // Hydrate the durable backend from DBOS (if configured) before listing so a
@@ -121,6 +128,13 @@ export async function handleRunControlCommand(
   const fail = (msg: string): void => reporter.error(msg);
   const canOpenPicker = (ui: PiCommandContext["ui"] | undefined): boolean =>
     policy.allowInputPicker && typeof ui?.custom === "function";
+  const ensureWorkflowResourcesVisible = async (): Promise<void> => {
+    try {
+      await deps.ensureWorkflowResourcesLoaded();
+    } catch (error) {
+      ctx.ui?.notify(formatWorkflowResourceLoadWarning(error), "warning");
+    }
+  };
   const confirmationPrompt = policy.allowHumanInput && typeof ctx.ui?.confirm === "function"
     ? ctx.ui.confirm.bind(ctx.ui)
     : undefined;
@@ -293,22 +307,23 @@ export async function handleRunControlCommand(
         const liveRuns = topLevelWorkflowRuns(store.runs()).filter((run) =>
           run.status === "paused" || (run.status === "failed" && run.resumable !== false),
         );
-        // Durable entries: a `running` durable handle may be a crashed process
-        // (cross-session crash recovery), so it stays selectable UNLESS it
-        // matches an actively-executing live run in this session.
-        const activeLiveIds = new Set(
-          topLevelWorkflowRuns(store.runs())
-            .filter((run) => run.endedAt === undefined && run.status === "running" && run.exitReason !== "quit")
-            .map((run) => run.id),
-        );
-        const runtime = deps.runtimeForContext(ctx);
         let durableEntries: readonly ResumableWorkflowEntry[] = [];
-        try {
-          const prepared = await runtime.prepareDurableResumable(undefined);
-          durableEntries = filterSelectorDurableEntries(runtime, prepared)
-            .filter((entry) => !activeLiveIds.has(entry.workflowId));
-        } catch (error) {
-          if (liveRuns.length === 0) {
+        if (liveRuns.length === 0) {
+          // Durable entries: a `running` durable handle may be a crashed process
+          // (cross-session crash recovery), so it stays selectable UNLESS it
+          // matches an actively-executing live run in this session.
+          const activeLiveIds = new Set(
+            topLevelWorkflowRuns(store.runs())
+              .filter((run) => run.endedAt === undefined && run.status === "running" && run.exitReason !== "quit")
+              .map((run) => run.id),
+          );
+          await ensureWorkflowResourcesVisible();
+          const runtime = deps.runtimeForContext(ctx);
+          try {
+            const prepared = await runtime.prepareDurableResumable(undefined);
+            durableEntries = filterSelectorDurableEntries(runtime, prepared)
+              .filter((entry) => !activeLiveIds.has(entry.workflowId));
+          } catch (error) {
             const message = error instanceof Error ? error.message : String(error);
             fail(`Failed to list resumable workflows: ${message}`);
             return true;
@@ -326,11 +341,12 @@ export async function handleRunControlCommand(
           const isPaused = run?.status === "paused" || (run?.stages.some((s) => s.status === "paused") ?? false);
           const isResumableContinuation = run !== undefined && !isPaused && ((run.status === "failed" && run.endedAt !== undefined && run.resumable !== false) || (run.endedAt === undefined && run.resumable === true && run.failureRecoverability === "recoverable"));
           if (isResumableContinuation) {
+            await ensureWorkflowResourcesVisible();
             const continuation = deps.runtimeForContext(ctx).resumeFailedRun(resolved.runId, undefined, { policy });
             continuation.ok ? print(continuation.message) : fail(continuation.message);
           } else {
             const result = resumeRun(resolved.runId, {});
-            if (result.ok && result.mode === "snapshot" && run?.exitReason === "quit") {
+            if (result.ok && !isPaused && result.mode === "snapshot" && run?.exitReason === "quit") {
               return await handleDurableResume(resolved.runId, ctx, reporter, deps);
             }
             if (result.ok && policy.allowInputPicker) deps.overlay.open(result.runId, overlaySurfaceFromContext(ctx));
@@ -389,7 +405,9 @@ export async function handleRunControlCommand(
       return true;
     }
     const run = store.runs().find((r) => r.id === stageRunId);
-    const isPaused = run?.status === "paused" || (run?.stages.some((s) => s.status === "paused") ?? false);
+    const hadPausedRunState = run?.status === "paused";
+    const hadPausedStageState = run?.stages.some((s) => s.status === "paused") ?? false;
+    const isPaused = hadPausedRunState || hadPausedStageState;
     const isResumableContinuation = run !== undefined && !isPaused && ((run.status === "failed" && run.endedAt !== undefined && run.resumable !== false) || (run.endedAt === undefined && run.resumable === true && run.failureRecoverability === "recoverable"));
     const isActivelyRunning = run !== undefined && run.endedAt === undefined && run.status === "running" && !isPaused && run.exitReason !== "quit";
     if (isActivelyRunning && action === "resume") {
@@ -397,27 +415,34 @@ export async function handleRunControlCommand(
       return true;
     }
     if (isResumableContinuation) {
+      await ensureWorkflowResourcesVisible();
       const continuation = deps.runtimeForContext(ctx).resumeFailedRun(stageRunId, stageId, { policy });
       continuation.ok ? print(continuation.message) : fail(continuation.message);
       return true;
     }
+    // A quit, non-paused durable run is a resume shadow rather than a live
+    // stage-control pause. Routing directly to durable resume preserves the
+    // previous snapshot-only diversion without reopening a stale local overlay.
+    if (!isPaused && run?.exitReason === "quit" && action === "resume") {
+      return await handleDurableResume(stageRunId, ctx, reporter, deps);
+    }
     const result = resumeRun(stageRunId, { stageId, message });
     if (!result.ok) {
       fail(`Run not found: ${stageRunId.slice(0, 8)}`);
       return true;
     }
-    if (result.mode === "snapshot" && run?.exitReason === "quit" && action === "resume") {
-      return await handleDurableResume(stageRunId, ctx, reporter, deps);
-    }
     if (!isPaused) {
       if (policy.allowInputPicker) deps.overlay.open(result.runId, overlaySurfaceFromContext(ctx));
       print(result.message ?? `Snapshot available: run ${result.runId} (${result.snapshot.name}) — status: ${result.snapshot.status}, stages: ${result.snapshot.stages.length}`);
       return true;
     }
     if (!message && stageId && policy.allowInputPicker) deps.overlay.open(runId, overlaySurfaceFromContext(ctx), stageId);
-    result.resumed.length === 0
-      ? fail(`No paused stages on run ${stageRunId.slice(0, 8)}.`)
-      : print(`Resumed ${result.resumed.length} stage(s) on run ${stageRunId.slice(0, 8)}${message ? ` with message: "${message}"` : ""}.`);
+    if (result.resumed.length === 0) {
+      const runLevelResumed = hadPausedRunState && !hadPausedStageState && stageId === undefined && result.snapshot.status === "running";
+      runLevelResumed ? print(`Resumed run ${stageRunId.slice(0, 8)}.`) : fail(`No paused stages on run ${stageRunId.slice(0, 8)}.`);
+    } else {
+      print(`Resumed ${result.resumed.length} stage(s) on run ${stageRunId.slice(0, 8)}${message ? ` with message: "${message}"` : ""}.`);
+    }
     return true;
   }
 

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

@@ -24,12 +24,14 @@ import {
   resolveToolStageTarget,
   stageFailureMessage,
 } from "./workflow-targets.js";
+import { formatWorkflowResourceLoadWarning } from "./workflow-command-surfaces.js";
 
 export interface WorkflowControlActionDeps {
   getPersistence: () => WorkflowPersistencePort | undefined;
   reloadWorkflowResources: () => Promise<void> | void;
-  runtime: ExtensionRuntime;
+  getRuntime: () => ExtensionRuntime;
   policy: WorkflowExecutionPolicy;
+  ensureWorkflowResourcesLoaded: () => Promise<void> | void;
 }
 
 export function workflowPauseAction(args: WorkflowToolArgs): WorkflowToolResult {
@@ -166,10 +168,10 @@ export function workflowInterruptAction(args: WorkflowToolArgs): WorkflowToolRes
   };
 }
 
-export function workflowResumeAction(
+export async function workflowResumeAction(
   args: WorkflowToolArgs,
-  deps: Pick<WorkflowControlActionDeps, "runtime" | "policy">,
-): WorkflowToolResult {
+  deps: Pick<WorkflowControlActionDeps, "getRuntime" | "policy" | "ensureWorkflowResourcesLoaded">,
+): Promise<WorkflowToolResult> {
   const target = resolveToolRunTarget(args, "No active run to resume.");
   if (target.kind === "all") return { action: "resume", runId: "--all", status: "noop", message: "Resume does not support --all." };
   if (target.kind === "ambiguous") return { action: "resume", runId: target.target, status: "noop", message: ambiguousRunMessage(target.target, target.matches) };
@@ -178,25 +180,35 @@ export function workflowResumeAction(
   if (!stage.ok) return { action: "resume", runId: target.runId, status: "noop", message: stage.message };
   const stageRunId = stage.runId ?? target.runId;
   const run = store.runs().find((r) => r.id === stageRunId);
-  const isPaused = run?.status === "paused" || (run?.stages.some((s) => s.status === "paused") ?? false);
+  const hadPausedRunState = run?.status === "paused";
+  const hadPausedStageState = run?.stages.some((s) => s.status === "paused") ?? false;
+  const isPaused = hadPausedRunState || hadPausedStageState;
   const isResumableContinuation = run !== undefined && !isPaused && (
     (run.status === "failed" && run.endedAt !== undefined && run.resumable !== false) ||
     (run.endedAt === undefined && run.resumable === true && run.failureRecoverability === "recoverable")
   );
   if (isResumableContinuation) {
-    const continuation = deps.runtime.resumeFailedRun(stageRunId, stage.stageId, { policy: deps.policy });
+    let warning: string | undefined;
+    try {
+      await deps.ensureWorkflowResourcesLoaded();
+    } catch (error) {
+      warning = formatWorkflowResourceLoadWarning(error);
+    }
+    const continuation = deps.getRuntime().resumeFailedRun(stageRunId, stage.stageId, { policy: deps.policy });
+    const message = warning === undefined ? continuation.message : `${warning}\n\n${continuation.message}`;
     return {
       action: "resume",
       runId: continuation.ok ? continuation.runId : stageRunId,
       status: continuation.ok ? "running" : "noop",
-      message: continuation.message,
+      message,
     };
   }
   const result = resumeRun(stageRunId, { stageId: stage.stageId, message: args.message });
   if (result.ok) {
+    const runLevelResumed = hadPausedRunState && !hadPausedStageState && stage.stageId === undefined && result.snapshot.status === "running";
     const message = result.message ?? (isPaused
       ? result.resumed.length === 0
-        ? `No paused stages on run ${result.runId.slice(0, 8)}.`
+        ? runLevelResumed ? `Resumed run ${result.runId.slice(0, 8)}.` : `No paused stages on run ${result.runId.slice(0, 8)}.`
         : `Resumed ${result.resumed.length} stage(s) on run ${result.runId.slice(0, 8)}${args.message ? ` with message: "${args.message}"` : ""}.`
       : `Snapshot available: run ${result.runId} (${result.snapshot.name}) — status: ${result.snapshot.status}, stages: ${result.snapshot.stages.length}`);
     return { action: "resume", runId: result.runId, status: "ok", message };

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

@@ -26,12 +26,14 @@ import {
 } from "./workflow-tool-inspection.js";
 import { workflowSendAction } from "./workflow-tool-send.js";
 import { isWorkflowStageToolContext, topLevelExpandedSnapshots } from "./workflow-targets.js";
+import { formatWorkflowResourceLoadWarning } from "./workflow-command-surfaces.js";
 
 export function makeExecuteWorkflowTool(
   runtime: ExtensionRuntime | ((ctx: PiExecuteContext) => ExtensionRuntime),
   getPersistence: () => WorkflowPersistencePort | undefined,
   reloadWorkflowResources: () => Promise<void> | void,
-) {
+  ensureWorkflowResourcesLoaded: () => Promise<void> | void = () => {},
+): (args: WorkflowToolArgs, ctx: PiExecuteContext) => Promise<WorkflowToolResult> {
   return async function executeWorkflowTool(
     args: WorkflowToolArgs,
     ctx: PiExecuteContext,
@@ -47,16 +49,28 @@ export function makeExecuteWorkflowTool(
         stages: [],
       };
     }
-    const activeRuntime = typeof runtime === "function" ? runtime(ctx) : runtime;
     const policy: WorkflowExecutionPolicy = workflowPolicyFromContext(ctx);
+    const getRuntime = (): ExtensionRuntime => typeof runtime === "function" ? runtime(ctx) : runtime;
+    const ensureWorkflowResourcesVisible = async (): Promise<void> => {
+      try {
+        await ensureWorkflowResourcesLoaded();
+      } catch (error) {
+        ctx.ui?.notify?.(formatWorkflowResourceLoadWarning(error), "warning");
+      }
+    };
 
     switch (action) {
       case "get":
-        return workflowGetResult(activeRuntime, args);
+        await ensureWorkflowResourcesVisible();
+        return workflowGetResult(getRuntime(), args);
       case "list":
-      case "inputs":
-      case "run":
-        if (action === "run" && hasDirectExecutionMode(args)) {
+      case "inputs": {
+        await ensureWorkflowResourcesVisible();
+        return getRuntime().dispatch(args, { policy });
+      }
+      case "run": {
+        if (hasDirectExecutionMode(args)) {
+          const activeRuntime = getRuntime();
           const normalModeCount = directModeCount(args) + (hasNamedExecutionMode(args) ? 1 : 0);
           if (normalModeCount !== 1) {
             throw new Error("Workflow extension: specify exactly one normal execution mode: workflow, task, tasks, or chain");
@@ -64,7 +78,9 @@ export function makeExecuteWorkflowTool(
           const details = await activeRuntime.runDirect(withForkParentSession(args, ctx), { policy });
           return workflowRunResultFromDetails(details);
         }
-        return activeRuntime.dispatch(args, { policy });
+        await ensureWorkflowResourcesVisible();
+        return getRuntime().dispatch(args, { policy });
+      }
       case "status": {
         const target = args.runId;
         if (target !== undefined) {
@@ -92,7 +108,7 @@ export function makeExecuteWorkflowTool(
       case "interrupt":
         return workflowInterruptAction(args);
       case "resume":
-        return workflowResumeAction(args, { runtime: activeRuntime, policy });
+        return workflowResumeAction(args, { getRuntime, policy, ensureWorkflowResourcesLoaded });
       default: {
         const _exhaustive: never = action;
         throw new Error(`Workflow extension: unknown action "${_exhaustive}"`);

package/dist/builtin/workflows/src/runs/background/status.ts

@@ -18,6 +18,7 @@ import { stageControlRegistry as defaultStageControlRegistry } from "../foregrou
 import { appendRunEnd } from "../../shared/persistence-session-entries.js";
 import { expandWorkflowGraph } from "../../shared/expanded-workflow-graph.js";
 import { topLevelWorkflowRuns } from "../../shared/run-visibility.js";
+import { actionableReturnedStatusText, effectiveRunStatus, structuredRecoverableWorkflowFailureText } from "../../shared/returned-run-status.js";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -115,7 +116,7 @@ export function statusRuns(opts?: { all?: boolean; store?: Store }): RunStatusEn
   return topLevelWorkflowRuns(snapshot.runs).map((run) => ({
     runId: run.id,
     name: run.name,
-    status: run.status,
+    status: effectiveRunStatus(run),
     startedAt: run.startedAt,
     durationMs: run.durationMs,
     stageCount: expandWorkflowGraph(snapshot, run.id).stages.length,
@@ -470,7 +471,7 @@ export function inspectRun(
   const detail: RunDetail = {
     runId: copy.id,
     name: copy.name,
-    status: copy.status,
+    status: effectiveRunStatus(copy),
     mode: expandedStages.length > 1 ? "chain" : "single",
     startedAt: copy.startedAt,
     endedAt: copy.endedAt,
@@ -481,7 +482,7 @@ export function inspectRun(
     inputs: copy.inputs,
     stages: expandedStages.map((stage) => structuredClone(stage)),
     result: copy.result,
-    error: copy.error,
+    error: copy.error ?? (effectiveRunStatus(copy) === copy.status ? undefined : (structuredRecoverableWorkflowFailureText(copy) ?? actionableReturnedStatusText(copy.result))),
     exited: copy.exited,
     exitReason: copy.exitReason,
     failureKind: copy.failureKind,

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

@@ -68,14 +68,23 @@ export function createContinuationReplayIndex(continuation: RunContinuationOpts
   }
 
   const stagesByReplayIdentity = new Map<string, StageSnapshot[]>();
+  const stagesByDisplayName = new Map<string, StageSnapshot[]>();
   const promptDuplicateCounts = new Map<string, number>();
   for (const stage of continuation.source.stages) {
     const identity = stage.replayKey ?? stage.name;
     const stages = stagesByReplayIdentity.get(identity);
     if (stages === undefined) stagesByReplayIdentity.set(identity, [stage]);
     else stages.push(stage);
-    const duplicateKey = `${identity}\u0001${sortedIdentity(stage.parentIds)}`;
-    promptDuplicateCounts.set(duplicateKey, (promptDuplicateCounts.get(duplicateKey) ?? 0) + 1);
+    const namedStages = stagesByDisplayName.get(stage.name);
+    if (namedStages === undefined) stagesByDisplayName.set(stage.name, [stage]);
+    else namedStages.push(stage);
+    const duplicateKeys = [
+      `${identity}\u0001${sortedIdentity(stage.parentIds)}`,
+      ...(identity === stage.name ? [] : [`${stage.name}\u0001${sortedIdentity(stage.parentIds)}`]),
+    ];
+    for (const duplicateKey of duplicateKeys) {
+      promptDuplicateCounts.set(duplicateKey, (promptDuplicateCounts.get(duplicateKey) ?? 0) + 1);
+    }
   }
 
   const consumedSourceStageIds = new Set<string>();
@@ -126,7 +135,8 @@ export function createContinuationReplayIndex(continuation: RunContinuationOpts
       let candidates = stagesByReplayIdentity.get(replayKey)?.filter((stage) => !consumedSourceStageIds.has(stage.id)) ?? [];
       if (candidates.length === 0) {
         identity = displayName;
-        candidates = stagesByReplayIdentity.get(displayName)?.filter((stage) => !consumedSourceStageIds.has(stage.id) && stage.replayKey === undefined) ?? [];
+        const namedCandidates = stagesByDisplayName.get(displayName)?.filter((stage) => !consumedSourceStageIds.has(stage.id)) ?? [];
+        candidates = kind === "prompt" ? namedCandidates.filter((stage) => stage.replayKey === undefined) : namedCandidates;
       }
       if (candidates.length === 0) return { kind: "execute", parentIds, answerReplay: "unavailable" };
 

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

@@ -23,14 +23,18 @@ import {
   createWorktrees,
   diffWorktrees,
   findWorktreeTaskCwdConflict,
-  setupGitWorktree,
+  setupGitWorktreeCached,
   formatWorktreeDiffSummary,
   formatWorktreeTaskCwdConflict,
+  type GitWorktreeSetupCache,
+  type GitWorktreeSetupResult,
   type WorktreeSetup,
 } from "../shared/worktree.js";
 import type { RunOpts, RunResult } from "./executor-types.js";
 import { isWorkflowExitStatus } from "./executor-abort.js";
 import { directTaskWithDefaults, resolveWorkflowPath, taskBaseDir, withoutUndefinedProperties } from "./executor-task-prompts.js";
+export { createGitWorktreeSetupCache } from "../shared/worktree.js";
+export type { GitWorktreeSetupCache } from "../shared/worktree.js";
 
 export function directModelRequestsFromChain(
   chain: readonly WorkflowChainStep[],
@@ -223,27 +227,44 @@ export function stageOptionsWithInputDefaults<T extends StageOptions>(options: T
   return { ...defaults, ...withoutUndefinedProperties(options ?? {}) } as T;
 }
 
-export function stageOptionsWithGitWorktree<T extends StageOptions>(options: T | undefined, workflowInvocationCwd: string): T | undefined {
+export function stageOptionsWithGitWorktree<T extends StageOptions>(options: T | undefined, workflowInvocationCwd: string, cache?: GitWorktreeSetupCache): T | undefined {
   if (options === undefined) return undefined;
   if (typeof options.gitWorktreeDir !== "string" || options.gitWorktreeDir.trim().length === 0) return options;
-  const setup = setupGitWorktree({
+  const setup = setupGitWorktreeCached({
     gitWorktreeDir: options.gitWorktreeDir,
     baseBranch: options.baseBranch,
     cwd: workflowInvocationCwd,
-  });
+  }, cache);
   const explicitCwd = resolveWorktreeCwdOverride(options.cwd, setup.cwd);
   return { ...options, gitWorktreeDir: undefined, baseBranch: undefined, cwd: explicitCwd ?? setup.cwd };
 }
 
-export function workflowCwdWithInputWorktree(inputDefaults: Partial<StageOptions>, workflowInvocationCwd: string): string {
+export function setupWorkflowInputGitWorktree(inputDefaults: Partial<StageOptions>, workflowInvocationCwd: string, cache?: GitWorktreeSetupCache): GitWorktreeSetupResult | undefined {
   if (typeof inputDefaults.gitWorktreeDir !== "string" || inputDefaults.gitWorktreeDir.trim().length === 0) {
-    return workflowInvocationCwd;
+    return undefined;
   }
-  return setupGitWorktree({
+  return setupGitWorktreeCached({
     gitWorktreeDir: inputDefaults.gitWorktreeDir,
     baseBranch: inputDefaults.baseBranch,
     cwd: workflowInvocationCwd,
-  }).cwd;
+  }, cache);
+}
+
+export function workflowCwdWithInputWorktree(inputDefaults: Partial<StageOptions>, workflowInvocationCwd: string, cache?: GitWorktreeSetupCache): string {
+  return setupWorkflowInputGitWorktree(inputDefaults, workflowInvocationCwd, cache)?.cwd ?? workflowInvocationCwd;
+}
+
+export function workflowInvocationMetadata(inputDefaults: Partial<StageOptions>, workflowInvocationCwd: string, cache?: GitWorktreeSetupCache): {
+  readonly invocationCwd: string;
+  readonly workflowCwd?: string;
+  readonly repositoryRoot?: string;
+  readonly gitWorktreeRoot?: string;
+} {
+  const setup = setupWorkflowInputGitWorktree(inputDefaults, workflowInvocationCwd, cache);
+  return {
+    invocationCwd: workflowInvocationCwd,
+    ...(setup !== undefined ? { workflowCwd: setup.cwd, repositoryRoot: setup.repositoryRoot, gitWorktreeRoot: setup.worktreeRoot } : {}),
+  };
 }
 
 function directWorktreeDiffsDir(options: WorkflowDirectOptions, setup: WorktreeSetup, runId: string, scope: string): string {

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

@@ -310,7 +310,8 @@ export function toolResultHasChatAnswer(result: unknown): boolean {
   );
 }
 
-export const RESUME_CONTINUATION_PROMPT = "Continue where you left off.";
+export const RESUME_CONTINUATION_PROMPT =
+  "Continue where you left off. If you believe you are finished with your original task (or a redefined task if the user told you), stop.";
 
 export function shouldInjectResumeContinuation(state: {
   readonly resumeOccurred: boolean;

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

@@ -24,7 +24,7 @@ import type { LiveStageMutableState, LiveStageRuntime, StageContextWithMeta, Sta
 import { createStageControlHandle } from "./executor-stage-control.js";
 import { createTrackedStageCaller } from "./executor-stage-call.js";
 import { createStageContext } from "./executor-stage-context.js";
-import { stageOptionsWithGitWorktree, stageOptionsWithInputDefaults } from "./executor-direct-helpers.js";
+import { stageOptionsWithGitWorktree, stageOptionsWithInputDefaults, type GitWorktreeSetupCache } from "./executor-direct-helpers.js";
 
 export function createWorkflowStageFactory(input: {
   readonly runId: string;
@@ -38,6 +38,7 @@ export function createWorkflowStageFactory(input: {
   readonly limiter: ConcurrencyLimiter;
   readonly inputRuntimeDefaults: Partial<StageOptions>;
   readonly workflowInvocationCwd: string;
+  readonly gitWorktreeSetupCache: GitWorktreeSetupCache;
   readonly stageRegistry: StageControlRegistry;
   readonly exit: WorkflowExitManager;
   readonly classifyExecutorFailure: (error: unknown) => WorkflowFailure;
@@ -45,7 +46,7 @@ export function createWorkflowStageFactory(input: {
 }): (name: string, options?: StageOptions, stageFailFastScope?: ParallelFailFastScope) => StageContextWithMeta {
   return (name: string, options?: StageOptions, stageFailFastScope?: ParallelFailFastScope): StageContextWithMeta => {
     input.exit.throwIfWorkflowExitSelected();
-    options = stageOptionsWithGitWorktree(stageOptionsWithInputDefaults(options, input.inputRuntimeDefaults), input.workflowInvocationCwd);
+    options = stageOptionsWithGitWorktree(stageOptionsWithInputDefaults(options, input.inputRuntimeDefaults), input.workflowInvocationCwd, input.gitWorktreeSetupCache);
     const stageId = crypto.randomUUID();
     const provisionalParentIds = input.tracker.onSpawn(stageId, name);
     const scopedParentIds = input.opts.continuation === undefined ? stageFailFastScope?.parentIds : undefined;
@@ -54,7 +55,7 @@ export function createWorkflowStageFactory(input: {
       input.tracker.replaceParents(stageId, scopedParentIds);
     }
 
-    const replayKey = `stage:${name}`;
+    const replayKey = options?.durableReplayKey ?? `stage:${name}`;
     const replayDecision = input.replayIndex.decide({
       displayName: name,
       replayKey,

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

@@ -6,6 +6,7 @@ import { missingAdapter, stripWorkflowOnlyOptions, unavailableSync } from "./sta
 import { asAgentSession, disposeStageSession, normalizeSessionCreateResult } from "./stage-runner-session.js";
 import { structuredOutputToolErrorFromEvent } from "./stage-runner-structured-output.js";
 import { sendStageUserMessage } from "./stage-runner-send-user-message.js";
+import { nextResumedContextOverflowFallbackIndex, terminatingToolCallId, unresolvedContextOverflowFailure, unresolvedContextOverflowMessage } from "./stage-runner-unresolved-overflow.js";
 import type { AgentSessionConsumer, StageModelFallbackMeta, StageRunnerOpts, StageSessionCreateOptions, StageSessionCreateResult, StageSessionEvent, StageSessionRuntime, WorkflowFastModeSettingsManager } from "./stage-runner-types.js";
 
 type PauseRequest = {
@@ -19,6 +20,7 @@ export class StageSessionController {
   private readonly terminatingToolCallIds = new Set<string>();
   private latestStructuredOutputToolErrorValue: string | undefined;
   private unsubscribeTerminateWatcher: (() => void) | undefined;
+  private unresolvedContextOverflowMessage: string | undefined;
   private disposed = false;
   private pendingThinkingLevel: Parameters<StageContext["setThinkingLevel"]>[0] | undefined;
   private readonly pendingListeners = new Set<(event: StageSessionEvent) => void>();
@@ -325,7 +327,9 @@ export class StageSessionController {
     }
     this.unsubscribeTerminateWatcher?.();
     this.unsubscribeTerminateWatcher = result.session.subscribe((event) => {
-      this.recordTerminatingToolCall(event);
+      const terminatingId = terminatingToolCallId(event);
+      if (terminatingId !== undefined) this.terminatingToolCallIds.add(terminatingId);
+      this.unresolvedContextOverflowMessage = unresolvedContextOverflowMessage(event) ?? this.unresolvedContextOverflowMessage;
       this.latestStructuredOutputToolErrorValue =
         structuredOutputToolErrorFromEvent(event) ?? this.latestStructuredOutputToolErrorValue;
     });
@@ -361,24 +365,29 @@ export class StageSessionController {
         continue;
       }
       const promptStartIndex = activeSession.messages.length;
+      this.unresolvedContextOverflowMessage = undefined;
       try {
         await activeSession.prompt(nextText, sdkOptions);
         const pendingPauseAfterPrompt = this.pauseRequest;
         if (pendingPauseAfterPrompt) {
           const { message } = await pendingPauseAfterPrompt.deferred.promise;
+          this.throwUnresolvedContextOverflowIfPresent();
           nextText = message;
           if (nextText === undefined) return { terminalScanStartIndex: activeSession.messages.length };
           continue;
         }
+        this.throwUnresolvedContextOverflowIfPresent();
         return { terminalScanStartIndex: promptStartIndex };
       } catch (err) {
         const pendingPauseAfterThrow = this.pauseRequest;
         if (pendingPauseAfterThrow) {
           const { message } = await pendingPauseAfterThrow.deferred.promise;
+          this.throwUnresolvedContextOverflowIfPresent();
           nextText = message;
           if (nextText === undefined) return { terminalScanStartIndex: activeSession.messages.length };
           continue;
         }
+        this.throwUnresolvedContextOverflowIfPresent();
         throw err;
       }
     }
@@ -420,10 +429,10 @@ export class StageSessionController {
         this.notifyModelFallbackMetaChange();
         throw err;
       }
-      this.pendingFallbackWarnings.push(`[fallback] resume on ${resumedLabel} failed: ${message}. Restarting fallback from ${this.candidateLabel(candidates[0]!)}.`);
-      await this.disposeCurrentSession();
-      this.activeCandidateIndex = undefined;
-      return false;
+      const resumedOverflowNextIndex = nextResumedContextOverflowFallbackIndex(err, this.activeCandidateIndex, candidates.length);
+      if (resumedOverflowNextIndex === "terminal") { this.modelWarnings.push(...this.pendingFallbackWarnings); this.pendingFallbackWarnings.length = 0; this.notifyModelFallbackMetaChange(); throw err; }
+      this.pendingFallbackWarnings.push(resumedOverflowNextIndex === undefined ? `[fallback] resume on ${resumedLabel} failed: ${message}. Restarting fallback from ${this.candidateLabel(candidates[0]!)}.` : `[fallback] resume on ${resumedLabel} failed: ${message}. Retrying with ${this.candidateLabel(candidates[resumedOverflowNextIndex]!)}.`);
+      await this.disposeCurrentSession(); this.activeCandidateIndex = resumedOverflowNextIndex; return false;
     }
   }
 
@@ -479,22 +488,12 @@ export class StageSessionController {
   private candidateLabel(candidate: WorkflowResolvedModelCandidate): string {
     return candidate.reasoningLevel !== undefined ? `${candidate.id}:${candidate.reasoningLevel}` : candidate.id;
   }
-
   private isWorkflowFastModeEnabled(): boolean | undefined {
     const model = this.session?.model;
     const settingsManager = this.sessionSettingsManager ?? this.effectiveStageOptions?.settingsManager;
-    if (model === undefined || settingsManager === undefined) return undefined;
-    return shouldApplyCodexFastModeForScope(model, settingsManager.getCodexFastModeSettings(), "workflow");
-  }
-
-  private recordTerminatingToolCall(event: unknown): void {
-    if (event === null || typeof event !== "object") return;
-    const record = event as Record<string, unknown>;
-    if (record["type"] !== "tool_execution_end") return;
-    const result = record["result"];
-    if (result === null || typeof result !== "object") return;
-    if ((result as Record<string, unknown>)["terminate"] !== true) return;
-    const callId = record["toolCallId"];
-    if (typeof callId === "string" && callId.length > 0) this.terminatingToolCallIds.add(callId);
+    return model === undefined || settingsManager === undefined
+      ? undefined
+      : shouldApplyCodexFastModeForScope(model, settingsManager.getCodexFastModeSettings(), "workflow");
   }
+  private throwUnresolvedContextOverflowIfPresent(): void { const message = this.unresolvedContextOverflowMessage; this.unresolvedContextOverflowMessage = undefined; if (message !== undefined) throw unresolvedContextOverflowFailure(message); }
 }