@bastani/atomic 0.9.5-alpha.8 → 0.9.5

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

@@ -12,7 +12,7 @@ import type { GraphOverlayPort } from "../tui/overlay-adapter.js";
 import type { ExtensionRuntime } from "./runtime.js";
 import type { WorkflowInputEntry, WorkflowToolResult } from "./render-result.js";
 import type { ExtensionAPI, PiCommandContext, PiArgumentCompletionResult } from "./public-types.js";
-import { workflowArgumentCompletions } from "./workflow-command-completions.js";
+import { workflowArgumentCompletions, workflowArgumentCompletionsNeedWorkflowResources } from "./workflow-command-completions.js";
 import {
   createWorkflowCommandReporter,
   emitWorkflowCommandOutput,
@@ -23,7 +23,7 @@ import {
   type WorkflowCommandHandler,
   type WorkflowCommandOutputDetails,
 } from "./workflow-command-utils.js";
-import { emitTerminalRunDetailSurface } from "./workflow-command-surfaces.js";
+import { emitTerminalRunDetailSurface, formatWorkflowResourceLoadWarning } from "./workflow-command-surfaces.js";
 import { handleRunControlCommand, type WorkflowRunControlDeps } from "./workflow-run-control-command.js";
 import { workflowPolicyFromContext } from "./workflow-policy.js";
 import {
@@ -39,6 +39,7 @@ export interface WorkflowSlashCommandDeps {
   runtimeForContext: (ctx?: PiCommandContext) => ExtensionRuntime;
   overlay: GraphOverlayPort;
   reloadWorkflowResources: () => Promise<void> | void;
+  ensureWorkflowResourcesLoaded: () => Promise<void> | void;
   runWithLifecycleSuppressedForPolicy: <T>(
     policy: WorkflowExecutionPolicy,
     fn: () => Promise<T>,
@@ -57,8 +58,11 @@ export function registerWorkflowSlashCommand(
     {
       description: "Run or inspect Atomic workflows. Usage: /workflow <name> [key=value…] | /workflow [list|status|connect|attach|interrupt|kill|pause|resume|inputs|reload] [args]",
       handler: (args, ctx) => workflowSlashHandler(args, ctx, pi, deps),
-      getArgumentCompletions: (partial: string): PiArgumentCompletionResult =>
-        workflowArgumentCompletions(partial, deps.runtimeProxy),
+      getArgumentCompletions: (partial: string): PiArgumentCompletionResult | Promise<PiArgumentCompletionResult> => {
+        const buildCompletions = (): PiArgumentCompletionResult => workflowArgumentCompletions(partial, deps.runtimeProxy);
+        if (!workflowArgumentCompletionsNeedWorkflowResources(partial)) return buildCompletions();
+        return Promise.resolve(deps.ensureWorkflowResourcesLoaded()).then(buildCompletions).catch(buildCompletions);
+      },
     },
     workflowCommands,
   );
@@ -76,10 +80,18 @@ async function workflowSlashHandler(
   const fail = (msg: string): void => reporter.error(msg);
   const withImplicitYesFlag = (tokens: string[]): string[] =>
     tokens.some((t) => t === "--yes" || t === "-y") ? tokens : [...tokens, "-y"];
+  const ensureWorkflowResourcesVisible = async (): Promise<void> => {
+    try {
+      await deps.ensureWorkflowResourcesLoaded();
+    } catch (error) {
+      ctx.ui?.notify(formatWorkflowResourceLoadWarning(error), "warning");
+    }
+  };
   const showWorkflowInputs = async (
     workflowName: string,
     command: WorkflowCommandOutputDetails["command"] = "inputs",
   ): Promise<void> => {
+    await ensureWorkflowResourcesVisible();
     const result = await deps.runtimeForContext(ctx).dispatch({ workflow: workflowName, inputs: {}, action: "inputs" }, { policy });
     if (result.action !== "inputs" || !("inputs" in result)) return;
     const inputResult = result as Extract<WorkflowToolResult, { action: "inputs" }>;
@@ -99,6 +111,7 @@ async function workflowSlashHandler(
     return;
   }
   if (!subcommand || subcommand === "list") {
+    await ensureWorkflowResourcesVisible();
     const items = deps.runtimeProxy.registry.all().map((def) => ({
       name: def.normalizedName,
       description: def.description,
@@ -163,6 +176,7 @@ async function workflowSlashHandler(
     typeof ctx.ui?.setEditorComponent === "function" || typeof ctx.ui?.custom === "function"
   );
   if (canOpenPicker) {
+    await ensureWorkflowResourcesVisible();
     const schemaResult = await deps.runtimeForContext(ctx).dispatch({ workflow: workflowName, inputs: {}, action: "inputs" }, { policy });
     const schema = schemaResult.action === "inputs" && "inputs" in schemaResult
       ? (schemaResult as Extract<WorkflowToolResult, { action: "inputs" }>)
@@ -185,6 +199,7 @@ async function workflowSlashHandler(
     }
   }
 
+  await ensureWorkflowResourcesVisible();
   const result = await deps.runWithLifecycleSuppressedForPolicy(policy, () =>
     deps.runtimeForContext(ctx).dispatch({ workflow: workflowName, inputs: mergedInputs, action: "run" }, { policy }),
   );

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

@@ -1,5 +1,6 @@
 export const WORKFLOW_TOOL_DESCRIPTION =
-  "Run named workflows or direct one-off task/tasks/chain workflows; " +
+  "Run named builtin, project, user, or package workflows, or direct one-off task/tasks/chain workflows; " +
+  "when workflow execution fits but another shape would better achieve the task, author a custom TypeScript workflow({...}) inline with normal coding tools, reload it, and run it; " +
   "discover with list/get/inputs, inspect status/stages/stage details, " +
   "send prompt answers or steering, pause/resume/interrupt/kill runs, and reload workflow resources. " +
   "For large stage handoffs, write context to files/artifacts, pass paths via reads, and prompt downstream agents to 'Read the file at <path>...' instead of injecting large previous text. " +
@@ -8,26 +9,20 @@ export const WORKFLOW_TOOL_DESCRIPTION =
   "then search it with rg/grep and read small ranges; transcript is path-only by default when sessionFile/transcriptPath exists, explicit tail/limit returns bounded previews, and missing transcript paths fall back to a small preview.";
 
 export const DEFAULT_PROMPT_GUIDANCE: string[] = [
-  `**Workflows**: Treat workflows as the default execution path for any non-trivial task and for any request that has inherent structure plus an objective you can make verifiable. Use the \`workflow\` tool for existing named workflows and for repeatable, inspectable, resumable, multi-stage, or reviewer-gated processes; use direct \`task\`, \`tasks\`, or \`chain\` workflow calls for one-off tracked work when no named workflow fits.
-  - Decide the execution mode before your first tool call on a new request and state it in one short line: inline (tiny, deterministic, low-risk) or a workflow run. Reconnaissance counts as inline execution — reading code, searching, and running probe scripts is already doing the task, so an unstated "explore first" default silently commits you to an unbounded inline session.
-  - Workflow fit check: ask whether the task is an implementation, build, debug/diagnosis, bug-fix, migration, new-feature, scoped multi-file edit, or docs/code change with validation; or whether it has multiple steps, dependencies, handoffs, uncertainty, validation/review needs, a long-running surface, or measurable done criteria. If yes, launch or design a workflow instead of doing parallel implementation yourself.
-  - Treat loop/structural wording as a strong workflow signal, especially requests like "do X until Y", "repeat until", "iterate until", "review/fix until passing", "run checks and fix until green", "keep going until done", or any prompt that names a stop condition, approval gate, or evidence requirement.
-  - Budget reconnaissance: when a task passes the fit check, keep pre-workflow exploration to a few quick scoping reads whose only purpose is writing a sharper objective and validation criteria; deep research, upstream/design comparison, and behavior probing belong inside the workflow run — any workflow with a research or analysis stage, whether user-defined or builtin (e.g. \`ralph\`'s research stage) — not before it.
-  - Course-correct instead of drifting: if you are roughly ten or more tool calls into inline exploration with no artifact, edit, or commit to show — or you keep telling yourself "let me verify one more thing" — stop, write your findings so far to a context file, launch the best-fit workflow with that file passed via \`reads\` and a prompt like "Read the file at <path>...", and let the workflow own the implementation. Check \`action: "list"\` for named or user-defined workflows that match the task first, falling back to the builtin \`goal\`/\`ralph\` when nothing more specific fits. Sunk inline research is never a reason to stay inline; it transfers via files.
-  - Only skip workflows for tiny, deterministic, low-risk answers or direct edits that are faster and safer to complete inline without stage tracking, typically a clearly single-file/no-test/no-review change.
+  `**Execution routing**: Use the least orchestration that reliably fits the user's intent.
+  - Keep interactive, exploratory, conceptual, and conversation-led work inline so the user can steer it turn by turn.
+  - Use a single subagent or a bounded subagent chain/parallel fan-out for specialist work while the parent remains in control. Multiple steps, files, tests, validation commands, or parallelism alone do not require a workflow.
+  - Use a workflow when the user clearly delegates a well-defined autonomous job that is likely long-running or background-oriented, or when the job materially needs durable stage tracking, artifacts/checkpoints, resumability, human-in-the-loop prompts, gates, retries, or bounded loops. When the user clearly delegates such a long-running job, choose and run an appropriate workflow rather than keeping it inline.
+  - Treat loop or stop-condition phrasing as a key workflow signal, especially requests such as "do X until Y", "repeat until", "iterate until", "review/fix until passing", "run checks and fix until green", or "keep going until done". When the user asks Atomic to execute such a loop, prefer a workflow so the stop condition, retries, evidence, and convergence are tracked. Do not let this override a clearly exploratory or conceptual conversation.
+  - Named workflows may be builtin, project, user, or package supplied. Direct \`task\`, \`tasks\`, and \`chain\` modes provide one-off tracked shapes. When workflow execution is warranted, you may always author a custom TypeScript \`workflow({...})\` inline with normal coding tools if that shape best achieves the user's task; it need not reuse an installed workflow or fit a direct mode. For richer branches, loops, gates, child workflows, or human-in-the-loop behavior, write the definition, reload workflow resources, then run it. The workflow tool does not have a create action; do not force-fit a builtin such as \`goal\` or \`ralph\` when a custom workflow better matches the job.`,
+  `**Workflow discovery and lifecycle**:
   - For unfamiliar named workflows, discover with \`action: "list"\`, inspect with \`action: "get"\` or \`action: "inputs"\`, and run with \`action: "run"\`, \`workflow\`, and validated \`inputs\`; do not invent workflow names or input keys.
-  - When designing or editing workflows, read docs/workflows.md and reference its Workflow Starter Patterns: Classify-and-act, Fan-out-and-synthesize, Adversarial verification, Generate-and-filter, Tournament, and Loop until done. Choose or combine these patterns before inventing a custom stage graph, and reflect the selected pattern in the spec and Mermaid diagram when using the create-spec skill.
-  - Once you run a workflow with the workflow tool, end your current turn and wait for the next user input or lifecycle notice.
-    - You will automatically be alerted of key lifecycle events like start, finish, failure; do not micro-manage the run with sleep/status polling loops or read its logs/stages unless the user asks you to or you need information for the next step.
-    - If the user needs information from the workflow run, use targeted \`status\`/\`stages\`/\`stage\` checks instead of trying to read everything.
-    - Offer to help the user on another task instead of anxiously polling or help the user run another workflow if they need.
-    - Use run-control and messaging actions (\`send\`, \`pause\`, \`resume\`, \`interrupt\`, \`kill\`) only when needed to answer prompts, steer a stage, resume or interrupt paused work, or respond to user requests/control signals.
-  - 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.`,
+  - Once you run a workflow, end the current turn and wait for user input or a lifecycle notice. Do not use sleep/status polling loops: key start, finish, and failure events arrive automatically. Use targeted \`status\`/\`stages\`/\`stage\` checks only when the user asks or the next step needs them, and use \`send\`/\`pause\`/\`resume\`/\`interrupt\`/\`kill\` only to answer, steer, or honor control requests.
+  - For transcripts, avoid whole-file reads. Get \`sessionFile\`/\`transcriptPath\` from \`stages\` or \`stage\`, preserve the exact path and platform separators, search with \`rg\`/\`grep\`, and read small relevant ranges; use explicit \`tail\` or \`limit\` only for a bounded preview.`,
+  `**Workflow authoring and handoffs**:
+  - When a user asks to create or edit a workflow, clarify only unresolved requirements that materially affect its purpose, inputs, stages, handoffs, validation, success criteria, or starter pattern. Read the workflow docs/examples, implement the TypeScript definition with normal coding tools, reload it, and run representative test inputs before presenting it. Use the create-spec skill when it adds value; it is not mandatory when context is already sufficient.
+  - Consult docs/workflows.md and its starter patterns (Classify-and-act, Fan-out-and-synthesize, Adversarial verification, Generate-and-filter, Tournament, and Loop until done) when designing a stage graph.
+  - Pass large stage context through files/artifacts and \`reads\` with an explicit \`Read the file at <path>...\` prompt rather than large \`previous\` payloads or injected session history.
+  - Separate implementation/review acceptance from explicitly authorized final actions such as PR/MR/review creation, release tagging, deployment, or publication. Stop implementation loops once acceptance is proven and carry a remaining final action separately.
+  - A model stage sees its local prompt, artifacts, tools, and reads, not the graph name or surrounding implementation. State the concrete action, evidence, and success criteria directly.`,
 ];

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-schema.ts

@@ -49,7 +49,7 @@ const StageSessionOptionProperties = {
   agentDir: Type.Optional(Type.String()),
   authStorage: Type.Optional(SdkSessionOptionSchema("authStorage")),
   modelRegistry: Type.Optional(SdkSessionOptionSchema("modelRegistry")),
-  model: Type.Optional(Type.Unsafe<WorkflowModelValue>({ description: "Primary model id or SDK model object. String ids may include a reasoning suffix, e.g. openai/gpt-5:high; valid levels: off|minimal|low|medium|high|xhigh. A parenthesized context-window token may precede or follow the suffix, e.g. github-copilot/claude-opus-4.8 (1m):xhigh or github-copilot/claude-opus-4.8:xhigh (1m). Use (long) for a generic long-context marker, or a rounded size matching the model's long tier (e.g. (1m) or (1.1m)); both select the model's advertised long tier." })),
+  model: Type.Optional(Type.Unsafe<WorkflowModelValue>({ description: "Primary model id or SDK model object. String ids may include a reasoning suffix, e.g. openai/gpt-5:high; valid levels: off|minimal|low|medium|high|xhigh|max. A parenthesized context-window token may precede or follow the suffix, e.g. github-copilot/claude-opus-4.8 (1m):xhigh or github-copilot/claude-opus-4.8:xhigh (1m). Use (long) for a generic long-context marker, or a rounded size matching the model's long tier (e.g. (1m) or (1.1m)); both select the model's advertised long tier." })),
   contextWindow: Type.Optional(Type.Number({ description: "Context-window token budget for the stage session (e.g. 1000000). Non-strict by default: an unsupported value keeps the model's default window. Prefer the per-model `(1m)` token in a model/fallbackModels entry when only specific models should use a larger window." })),
   contextWindowStrict: Type.Optional(Type.Boolean({ description: "Treat an unsupported contextWindow as an error instead of falling back to the model's default window." })),
   thinkingLevel: Type.Optional(SdkSessionOptionSchema("thinkingLevel")),
@@ -71,8 +71,21 @@ const StageSessionOptionProperties = {
   forkFromSessionFile: Type.Optional(Type.String()),
 };
 
+// Keep this union opaque to Value.Convert: branch ordering otherwise coerces
+// boolean false to "false", or the legitimate string path "false" to false.
+const WorkflowOutputSchema = Type.Unsafe<string | false>({
+  not: {
+    not: {
+      anyOf: [
+        { type: "string" },
+        { const: false },
+      ],
+    },
+  },
+});
+
 const WorkflowTaskOptionProperties = {
-  output: Type.Optional(Type.Union([Type.String(), Type.Literal(false)])),
+  output: Type.Optional(WorkflowOutputSchema),
   outputMode: Type.Optional(Type.Union([Type.Literal("inline"), Type.Literal("file-only")])),
   reads: Type.Optional(Type.Union([Type.Array(Type.String()), Type.Literal(false)])),
   worktree: Type.Optional(Type.Boolean()),

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-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,7 @@ export function toolResultHasChatAnswer(result: unknown): boolean {
   );
 }
 
-export const RESUME_CONTINUATION_PROMPT = "Continue where you left off.";
+export { RESUME_CONTINUATION_PROMPT } from "../../shared/resume-continuation.js";
 
 export function shouldInjectResumeContinuation(state: {
   readonly resumeOccurred: boolean;