@bastani/atomic 0.9.4 → 0.9.5-alpha.10

package/dist/builtin/workflows/src/engine/run-returned-status.ts

@@ -1,5 +1,13 @@
 import type { RunEndMetadata } from "../shared/store-public-types.js";
 import type { WorkflowOutputValues } from "../shared/types.js";
+import type { RunSnapshot } from "../shared/store-types.js";
+import {
+  actionableReturnedStatusText,
+  isReturnedBlockedWorkflowStatus,
+  isReturnedResumableBlockedWorkflowStatus,
+  normalizeReturnedWorkflowStatus,
+  structuredRecoverableWorkflowFailure,
+} from "../shared/returned-run-status.js";
 
 export interface ReturnedRunStatus {
   readonly status: "completed" | "failed" | "blocked";
@@ -7,23 +15,44 @@ export interface ReturnedRunStatus {
   readonly metadata?: RunEndMetadata;
 }
 
-export function classifyReturnedRunStatus(result: WorkflowOutputValues | undefined): ReturnedRunStatus {
-  const returnedStatus = result?.["status"];
-  if (returnedStatus !== "failed" && returnedStatus !== "blocked") {
+export function classifyReturnedRunStatus(result: WorkflowOutputValues | undefined, runSnapshot?: RunSnapshot): ReturnedRunStatus {
+  const structuredFailure = runSnapshot !== undefined ? structuredRecoverableWorkflowFailure(runSnapshot) : undefined;
+  if (structuredFailure !== undefined) {
+    return {
+      status: "blocked",
+      error: structuredFailure.error,
+      metadata: structuredFailure.metadata,
+    };
+  }
+  const returnedStatus = normalizeReturnedWorkflowStatus(result?.["status"]);
+  if (returnedStatus === undefined || returnedStatus === "completed" || returnedStatus === "complete") {
     return { status: "completed" };
   }
 
-  const summary = result?.["summary"];
-  const error = typeof summary === "string" && summary.trim().length > 0
-    ? summary.trim()
-    : `Workflow returned status ${JSON.stringify(returnedStatus)}.`;
-  return {
-    status: returnedStatus,
-    error,
-    metadata: returnedStatus === "failed"
-      ? returnedFailureMetadata(error)
-      : returnedBlockedMetadata(),
-  };
+  const error = returnedStatusError(result, returnedStatus);
+  if (returnedStatus === "failed") {
+    return {
+      status: "failed",
+      error,
+      metadata: returnedFailureMetadata(error),
+    };
+  }
+  if (isReturnedBlockedWorkflowStatus(returnedStatus)) {
+    const metadata = isReturnedResumableBlockedWorkflowStatus(returnedStatus)
+      ? returnedRecoverableBlockedMetadata(error)
+      : { resumable: false };
+    return {
+      status: "blocked",
+      error,
+      metadata,
+    };
+  }
+
+  return { status: "completed" };
+}
+
+function returnedStatusError(result: WorkflowOutputValues | undefined, returnedStatus: string): string {
+  return actionableReturnedStatusText(result) ?? `Workflow returned status ${JSON.stringify(returnedStatus)}.`;
 }
 
 function returnedFailureMetadata(error: string): RunEndMetadata {
@@ -36,6 +65,11 @@ function returnedFailureMetadata(error: string): RunEndMetadata {
   };
 }
 
-function returnedBlockedMetadata(): RunEndMetadata {
-  return { resumable: false };
+function returnedRecoverableBlockedMetadata(error: string): RunEndMetadata {
+  return {
+    failureRecoverability: "recoverable",
+    failureDisposition: "active_blocked",
+    failureMessage: error,
+    resumable: true,
+  };
 }

package/dist/builtin/workflows/src/engine/run.ts

@@ -1,11 +1,5 @@
-import type { RunSnapshot } from "../shared/store-types.js";
-import type {
-  WorkflowDefinition,
-  WorkflowInputValues,
-  WorkflowOutputValues,
-  WorkflowRunContext,
-  WorkflowSerializableValue,
-} from "../shared/types.js";
+import type { RunSnapshot, StageSnapshot } from "../shared/store-types.js";
+import type { WorkflowDefinition, WorkflowInputValues, WorkflowOutputValues, WorkflowRunContext } from "../shared/types.js";
 import type { WorkflowFailure } from "../shared/workflow-failures.js";
 import { classifyWorkflowFailure } from "../shared/workflow-failures.js";
 import { store as defaultStore } from "../shared/store.js";
@@ -25,7 +19,7 @@ import { stageControlRegistry as defaultStageControlRegistry } from "../runs/for
 import type { RunOpts, RunResult } from "../runs/foreground/executor-types.js";
 import { unknownErrorMessage, findWorkflowExitSignal, parentWorkflowExitAbortReason } from "../runs/foreground/executor-abort.js";
 import { resolveAndValidateInputs, resolveInputConcurrency, resolveInputRuntimeDefaults } from "../runs/foreground/executor-inputs.js";
-import { workflowCwdWithInputWorktree } from "../runs/foreground/executor-direct-helpers.js";
+import { createGitWorktreeSetupCache, workflowCwdWithInputWorktree, workflowInvocationMetadata } from "../runs/foreground/executor-direct-helpers.js";
 import { createStageScheduler } from "../runs/foreground/executor-scheduler.js";
 import { createRunFinalizers } from "../runs/foreground/executor-run-finalizers.js";
 import { buildPromptNodeUiAdapter } from "../runs/foreground/executor-prompt-nodes.js";
@@ -45,12 +39,12 @@ import { classifyReturnedRunStatus } from "./run-returned-status.js";
 import { createToolPrimitive, createCheckpointIdGenerator } from "../durable/tool-primitive.js";
 import { persistDurableCacheEntry } from "../durable/resume-catalog.js";
 import { createDurableStagePrimitive, createDurableTaskPrimitive, recordStageCheckpoint, createStageReplayKeyGenerator, recordCachedStageWithTracker } from "../durable/stage-primitive.js";
+import type { DurableCompletedStageCheckpoint } from "../durable/stage-primitive.js";
 import { createDurableChildWorkflowPrimitive } from "../durable/child-primitive.js";
 import { ScopedDurableBackend, type DurableScope } from "../durable/scoped-backend.js";
 import { finalizeDurableTerminalStatus } from "./run-durable-finalize.js";
 import { createDurableStageSessionRecorder } from "./run-durable-stage-session.js";
 import type { DurableWorkflowBackend } from "../durable/backend.js";
-import type { StageSnapshot } from "../shared/store-types.js";
 
 function nextEventLoopTurn(): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, 0));
@@ -158,11 +152,11 @@ export async function run<
 
   const tracker = new GraphFrontierTracker();
   const inputConcurrency = resolveInputConcurrency(def.inputs, resolvedInputs);
-  const inputRuntimeDefaults = resolveInputRuntimeDefaults(def, resolvedInputs);
+  const inputRuntimeDefaults = resolveInputRuntimeDefaults(def, resolvedInputs), gitWorktreeSetupCache = createGitWorktreeSetupCache();
   const workflowInvocationCwd = opts.cwd ?? process.cwd();
   let workflowCwd: string | undefined;
   const resolveWorkflowCwd = (): string => {
-    workflowCwd ??= workflowCwdWithInputWorktree(inputRuntimeDefaults, workflowInvocationCwd);
+    workflowCwd ??= workflowCwdWithInputWorktree(inputRuntimeDefaults, workflowInvocationCwd, gitWorktreeSetupCache);
     return workflowCwd;
   };
   const limiter = createRunLimiter(inputConcurrency ?? opts.config?.defaultConcurrency);
@@ -277,12 +271,14 @@ export async function run<
     limiter,
     inputRuntimeDefaults,
     workflowInvocationCwd,
-    stageRegistry,
+    stageRegistry, gitWorktreeSetupCache,
     exit,
     classifyExecutorFailure,
   });
   const workflowBoundaryReplayCounts = new Map<string, number>();
   const nextWorkflowBoundaryReplayKey = (name: string): string => {
+    const durableScopePrefix = pendingChildDurableScope?.scopePrefix;
+    if (durableScopePrefix !== undefined && durableScopePrefix.startsWith(`workflow:${name}:`)) return durableScopePrefix;
     const next = (workflowBoundaryReplayCounts.get(name) ?? 0) + 1;
     workflowBoundaryReplayCounts.set(name, next);
     return `workflow:${name}:${next}`;
@@ -314,22 +310,19 @@ export async function run<
     },
     runWorkflow: run,
   });
-
-  // Durable workflow registration — register this run for cross-session discovery.
+  const durableRootWorkflowRegistration = {
+    workflowId: runId,
+    name: def.name,
+    inputs: resolvedInputs as Record<string, import("../shared/types.js").WorkflowSerializableValue>,
+    createdAt: runSnapshot.startedAt,
+    status: "running" as const,
+    rootWorkflowId: runId,
+    resumable: true,
+    ...(opts.persistence !== undefined ? { sessionFile: undefined } : {}),
+  };
   if (opts.continuation === undefined && opts.parentRun === undefined) {
-    // New root run: register it durably so a future session can discover it.
-    durableBackend.registerWorkflow({
-      workflowId: runId,
-      name: def.name,
-      inputs: resolvedInputs as Record<string, import("../shared/types.js").WorkflowSerializableValue>,
-      createdAt: runSnapshot.startedAt,
-      status: "running",
-      rootWorkflowId: runId,
-      resumable: true,
-      ...(opts.persistence !== undefined ? { sessionFile: undefined } : {}),
-    });
+    durableBackend.registerWorkflow({ ...durableRootWorkflowRegistration, invocationCwd: workflowInvocationCwd });
   } else if (opts.parentRun === undefined) {
-    // Resuming a root workflow: mark it as running again in the backend.
     durableBackend.setWorkflowStatus(runId, "running");
   }
   const tool = createToolPrimitive({
@@ -346,12 +339,13 @@ export async function run<
 
   // Durable ctx.ui wrapper — caches completed user responses so a resumed workflow does not re-ask answered prompts.
   const durableUiDeps = { workflowId: runId, backend: durableBackend, nextCheckpointId: checkpointIdGenerator };
-  const recordCachedStage = (name: string, replayKey: string, output: WorkflowSerializableValue): void =>
-    recordCachedStageWithTracker(activeStore, tracker, runId, name, replayKey, output, completedStageReplayKeys);
+  const recordCachedStage = (name: string, replayKey: string, checkpoint: DurableCompletedStageCheckpoint): void =>
+    recordCachedStageWithTracker(activeStore, tracker, runId, name, replayKey, checkpoint, completedStageReplayKeys);
   const durableTask = createDurableTaskPrimitive({
     workflowId: runId, backend: durableBackend,
     nextReplayKey: (stageName) => stageReplayKeyGenerator(stageName), task: taskRunners.task,
-    recordCachedTask: (name, replayKey, output) => recordCachedStage(name, replayKey, output),
+    recordCachedTask: (name, replayKey, checkpoint, scope) =>
+      recordCachedStageWithTracker(activeStore, tracker, runId, name, replayKey, checkpoint, completedStageReplayKeys, scope),
   });
   const durableWorkflow = createDurableChildWorkflowPrimitive({
     workflowId: runId, rootWorkflowId: opts.parentRun?.rootRunId ?? runId, backend: durableBackend,
@@ -411,6 +405,10 @@ export async function run<
       }
     }
 
+    if (opts.continuation === undefined && opts.parentRun === undefined) {
+      durableBackend.registerWorkflow({ ...durableRootWorkflowRegistration, ...workflowInvocationMetadata(inputRuntimeDefaults, workflowInvocationCwd, gitWorktreeSetupCache) });
+    }
+
     const rawResult = await def.run(ctx);
     if (ownController.signal.aborted) {
       const selectedExit = findWorkflowExitSignal(ownController.signal.reason, exitScope);
@@ -424,9 +422,9 @@ export async function run<
     assertWorkflowRunOutputs(def.name, result, def.outputs);
     assertWorkflowCreatedStage(runSnapshot);
     await durableBackend.flush?.();
-    const returned = classifyReturnedRunStatus(result);
+    const returned = classifyReturnedRunStatus(result, runSnapshot);
     const recorded = activeStore.recordRunEnd(runId, returned.status, result, returned.error, returned.metadata);
-    appendRunEndWhenRecorded(opts.persistence, recorded, { runId, status: returned.status, result, ...(returned.error !== undefined ? { error: returned.error } : {}), ...(returned.metadata ?? {}), ts: Date.now() });
+    appendRunEndWhenRecorded(opts.persistence, recorded, { runId, status: returned.status, result, ...(returned.error !== undefined ? { error: returned.error } : {}), ...(returned.metadata ?? {}), ...(runSnapshot.endedAt !== undefined ? { endedAt: runSnapshot.endedAt } : {}), ...(runSnapshot.durationMs !== undefined ? { durationMs: runSnapshot.durationMs } : {}), ts: Date.now() });
     durableBackend.setWorkflowStatus(runId, returned.status, undefined, returned.metadata?.resumable);
     await durableBackend.flush?.();
     if (opts.persistence && durableBackend.persistent) {
@@ -480,6 +478,8 @@ export async function run<
       ...(metadata.failedStageId !== undefined ? { failedStageId: metadata.failedStageId } : {}),
       resumable: metadata.resumable,
       ...(metadata.retryAfterMs !== undefined ? { retryAfterMs: metadata.retryAfterMs } : {}),
+      ...(runSnapshot.endedAt !== undefined ? { endedAt: runSnapshot.endedAt } : {}),
+      ...(runSnapshot.durationMs !== undefined ? { durationMs: runSnapshot.durationMs } : {}),
       ts: Date.now(),
     });
     return reconcileTerminalRunResult(runId, runSnapshot, activeStore, { status: "failed", error: metadata.errorMessage }, opts.onRunEnd);

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

@@ -13,6 +13,7 @@ import { createWorkflowStageFactory } from "../runs/foreground/executor-stage-fa
 import { createWorkflowBoundaryFactory, type WorkflowBoundaryStage } from "../runs/foreground/executor-child-boundary.js";
 import type { GraphFrontierTracker } from "./graph-inference.js";
 import type { EngineChildRunOptions, EngineStageRuntimeOptions, EngineWorkflowBoundaryOptions } from "./options.js";
+import type { GitWorktreeSetupCache } from "../runs/foreground/executor-direct-helpers.js";
 
 export interface EngineRuntimeInput {
   readonly runId: string;
@@ -31,6 +32,7 @@ export interface EngineRuntimeInput {
   readonly limiter: ConcurrencyLimiter;
   readonly inputRuntimeDefaults: Partial<StageOptions>;
   readonly workflowInvocationCwd: string;
+  readonly gitWorktreeSetupCache: GitWorktreeSetupCache;
   readonly stageRegistry: StageControlRegistry;
   readonly exit: WorkflowExitManager;
   readonly classifyExecutorFailure: LiveStageRuntime["classifyExecutorFailure"];
@@ -73,6 +75,7 @@ export class EngineRuntime {
   readonly exit: WorkflowExitManager;
   readonly inputRuntimeDefaults: Partial<StageOptions>;
   readonly workflowInvocationCwd: string;
+  readonly gitWorktreeSetupCache: GitWorktreeSetupCache;
 
   private readonly spawnAgentStage: (
     name: string,
@@ -93,6 +96,7 @@ export class EngineRuntime {
     this.exit = input.exit;
     this.inputRuntimeDefaults = input.inputRuntimeDefaults;
     this.workflowInvocationCwd = input.workflowInvocationCwd;
+    this.gitWorktreeSetupCache = input.gitWorktreeSetupCache;
 
     // The runtime only wires host-injected ports; stage sessions are still
     // created lazily by the stage runner through input.adapters.agentSession.
@@ -108,6 +112,7 @@ export class EngineRuntime {
       limiter: input.limiter,
       inputRuntimeDefaults: input.inputRuntimeDefaults,
       workflowInvocationCwd: input.workflowInvocationCwd,
+      gitWorktreeSetupCache: input.gitWorktreeSetupCache,
       stageRegistry: input.stageRegistry,
       exit: input.exit,
       classifyExecutorFailure: input.classifyExecutorFailure,

package/dist/builtin/workflows/src/extension/extension-factory.ts

@@ -85,6 +85,7 @@ function factory(pi: ExtensionAPI): void {
     (ctx) => runtimeState.runtimeForContext(ctx),
     () => runtimeState.persistenceRef.current,
     runtimeState.reloadWorkflowResources,
+    runtimeState.ensureWorkflowResourcesLoaded,
   );
 
   registerWorkflowTool(pi, executeWorkflowTool, runtimeState.runWithLifecycleSuppressedForPolicy);
@@ -93,12 +94,14 @@ function factory(pi: ExtensionAPI): void {
     runtimeForContext: runtimeState.runtimeForContext,
     overlay,
     reloadWorkflowResources: runtimeState.reloadWorkflowResources,
+    ensureWorkflowResourcesLoaded: runtimeState.ensureWorkflowResourcesLoaded,
     runWithLifecycleSuppressedForPolicy: runtimeState.runWithLifecycleSuppressedForPolicy,
     runControl: {
       pi,
       overlay,
       getPersistence: () => runtimeState.persistenceRef.current,
       runtimeForContext: runtimeState.runtimeForContext,
+      ensureWorkflowResourcesLoaded: runtimeState.ensureWorkflowResourcesLoaded,
     },
   });
   registerWorkflowMessageRenderers(pi);

package/dist/builtin/workflows/src/extension/extension-lifecycle.ts

@@ -58,7 +58,9 @@ export function registerWorkflowLifecycleHandlers(
   });
 
   pi.on("session_start", async (_event, ctx) => {
+    runtimeState.resetWorkflowDiscoveryForSession();
     deAdvertiseAskUserQuestionWhenHeadless(pi, ctx?.hasUI);
+    await runtimeState.ensureWorkflowConfigLoaded();
     killAllRuns({ store, cancellation: cancellationRegistry, persistence: runtimeState.persistenceRef.current });
     store.clear();
     clearForms();
@@ -66,10 +68,14 @@ export function registerWorkflowLifecycleHandlers(
     resetWorkflowHilAnswerNotificationState(runtimeState.hilAnswerNotificationState);
     stageControlRegistry.clear();
     runtimeState.setIntercomParentSession(registerIntercomParentSession(pi));
-    await runtimeState.discoveryPromise;
     runtimeState.setNotificationsActive(true);
+    runtimeState.startWorkflowDiscoveryWarmup(() => {
+      if (!ctx?.ui) return;
+      const diagnostics = formatStartupDiagnostics(null, runtimeState.discoveryRef.current);
+      if (diagnostics !== null) ctx.ui.notify?.(diagnostics, "warning");
+    });
     if (ctx?.ui) {
-      const diagnostics = formatStartupDiagnostics(runtimeState.configLoadRef.current, runtimeState.discoveryRef.current);
+      const diagnostics = formatStartupDiagnostics(runtimeState.configLoadRef.current, null);
       if (diagnostics !== null) ctx.ui.notify?.(diagnostics, "warning");
       deps.storeWidgetRef.current?.();
       deps.storeWidgetRef.current = installStoreWidget({ ui: ctx.ui }, store);
@@ -108,6 +114,7 @@ export function registerWorkflowLifecycleHandlers(
     }
     deps.storeWidgetRef.current?.();
     deps.storeWidgetRef.current = null;
+    runtimeState.resetWorkflowDiscoveryForSession();
     runtimeState.setNotificationsActive(false);
   });
 }

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

@@ -44,11 +44,14 @@ export interface WorkflowExtensionRuntimeState {
   runtimeProxy: ExtensionRuntime;
   configLoadRef: { current: ConfigLoadResult | null };
   discoveryRef: { current: DiscoveryResult | null };
-  discoveryPromise: Promise<void>;
   lifecycleNotificationState: ReturnType<typeof createWorkflowLifecycleNotificationState>;
   hilAnswerNotificationState: ReturnType<typeof createWorkflowHilAnswerNotificationState>;
   runtimeForContext(ctx?: PiModelContext): ExtensionRuntime;
+  resetWorkflowDiscoveryForSession(): void;
+  ensureWorkflowConfigLoaded(): Promise<void>;
+  ensureWorkflowResourcesLoaded(options?: { allowInFlight?: boolean }): Promise<void>;
   reloadWorkflowResources(options?: { allowInFlight?: boolean }): Promise<void>;
+  startWorkflowDiscoveryWarmup(onSettled?: () => void): void;
   runWithLifecycleSuppressedForPolicy<T>(policy: WorkflowExecutionPolicy, fn: () => Promise<T>): Promise<T>;
   setNotificationsActive(active: boolean): void;
   setIntercomParentSession(session: string | null): void;
@@ -74,6 +77,7 @@ export function createWorkflowExtensionRuntimeState(
   let lifecycleNotificationsUnsubscribe: (() => void) | null = null;
   let hilAnswerNotificationsUnsubscribe: (() => void) | null = null;
   let notificationsActive = false;
+  let notificationGeneration = 0;
   const lifecycleNotificationState = createWorkflowLifecycleNotificationState();
   const hilAnswerNotificationState = createWorkflowHilAnswerNotificationState();
   const lifecycleNotificationConfigRef: { current: WorkflowLifecycleNotificationConfig } = {
@@ -185,32 +189,15 @@ export function createWorkflowExtensionRuntimeState(
   }
 
   let workflowReloadQueue: Promise<void> = Promise.resolve();
-  async function reloadWorkflowResources(options?: { allowInFlight?: boolean }): Promise<void> {
-    const reload = workflowReloadQueue.then(() => reloadWorkflowResourcesNow(options));
-    workflowReloadQueue = reload.catch(() => {});
-    await reload;
-  }
-  async function loadPackageWorkflowPaths(): Promise<string[]> {
-    const packageResources = (await pi.refreshWorkflowResources?.()) ?? pi.getWorkflowResources?.() ?? [];
-    return packageResources.filter((resource) => resource.enabled !== false).map((resource) => resource.path);
+
+  let lazyDiscoveryPromise: Promise<void> | null = null;
+  let workflowDiscoveryGeneration = 0;
+  function deferToMacrotask(): Promise<void> {
+    return new Promise((resolve) => setImmediate(resolve));
   }
-  async function reloadWorkflowResourcesNow(options?: { allowInFlight?: boolean }): Promise<void> {
-    const activeRuns = inFlightRunCount();
-    if (options?.allowInFlight !== true && activeRuns > 0) {
-      throw new WorkflowReloadBlockedError(reloadBlockedMessage(activeRuns));
-    }
-    if (options?.allowInFlight === true && activeRuns > 0 && process.env.ATOMIC_WORKFLOW_DEBUG === "1") {
-      console.warn(`Workflow reload bypassed in-flight guard with ${activeRuns} active run(s).`);
-    }
-    const configResult = await loadWorkflowConfig();
+
+  function applyWorkflowConfig(configResult: ConfigLoadResult): void {
     configLoadRef.current = configResult;
-    const hasGlobal = configResult.globalConfig != null;
-    const hasProject = configResult.projectConfig != null;
-    const discoveryConfig = hasGlobal || hasProject
-      ? toScopedDiscoveryConfig(configResult.globalConfig ?? null, configResult.projectConfig ?? null, { projectRoot: process.cwd() })
-      : undefined;
-    const result = await discoverWorkflows({ config: discoveryConfig, packageWorkflowPaths: await loadPackageWorkflowPaths() });
-    discoveryRef.current = result;
     const effectiveConfig = withWorkflowDefaults(configResult.config ?? {});
     runtimeConfigRef.current = {
       maxDepth: effectiveConfig.maxDepth,
@@ -224,8 +211,11 @@ export function createWorkflowExtensionRuntimeState(
     statusWriterRef.unsubscribe();
     statusWriterRef = createStatusWriter(store, runtimeConfigRef.current);
     persistenceRef.current = makePersistencePort(pi, effectiveConfig.persistRuns);
+  }
+
+  function rebuildRuntime(registry = runtimeRef.current.registry): void {
     runtimeRef.current = createExtensionRuntime({
-      registry: result.registry,
+      registry,
       cwd: process.cwd(),
       adapters,
       cancellation: cancellationRegistry,
@@ -237,23 +227,143 @@ export function createWorkflowExtensionRuntimeState(
     });
   }
 
+  function isWorkflowDiscoveryCurrent(generation: number): boolean {
+    return generation === workflowDiscoveryGeneration;
+  }
+
+  function resetWorkflowDiscoveryForSession(): void {
+    workflowDiscoveryGeneration += 1;
+    discoveryRef.current = null;
+    lazyDiscoveryPromise = null;
+    workflowReloadQueue = Promise.resolve();
+    rebuildRuntime(startupDiscovery.registry);
+  }
+
+  async function ensureWorkflowConfigLoaded(): Promise<void> {
+    const generation = workflowDiscoveryGeneration;
+    const configResult = await loadWorkflowConfig();
+    if (!isWorkflowDiscoveryCurrent(generation)) return;
+    applyWorkflowConfig(configResult);
+    rebuildRuntime();
+  }
+
+  function queueWorkflowResourceReload(options: { allowInFlight?: boolean } | undefined, generation: number): Promise<void> {
+    const reload = workflowReloadQueue.then(() => reloadWorkflowResourcesNow(options, generation));
+    workflowReloadQueue = reload.catch(() => {});
+    return reload;
+  }
+
+  function trackLazyDiscovery(pending: Promise<void>): Promise<void> {
+    lazyDiscoveryPromise = pending;
+    void pending.finally(() => {
+      if (lazyDiscoveryPromise === pending) lazyDiscoveryPromise = null;
+    }).catch(() => {});
+    return pending;
+  }
+
+  function reloadWorkflowResources(options?: { allowInFlight?: boolean }): Promise<void> {
+    const generation = workflowDiscoveryGeneration;
+    return trackLazyDiscovery(queueWorkflowResourceReload(options, generation));
+  }
+  async function loadPackageWorkflowPaths(): Promise<string[]> {
+    const packageResources = (await pi.refreshWorkflowResources?.()) ?? pi.getWorkflowResources?.() ?? [];
+    return packageResources.filter((resource) => resource.enabled !== false).map((resource) => resource.path);
+  }
+  async function reloadWorkflowResourcesNow(options: { allowInFlight?: boolean } | undefined, generation: number): Promise<void> {
+    const activeRuns = inFlightRunCount();
+    if (options?.allowInFlight !== true && activeRuns > 0) {
+      throw new WorkflowReloadBlockedError(reloadBlockedMessage(activeRuns));
+    }
+    if (options?.allowInFlight === true && activeRuns > 0 && process.env.ATOMIC_WORKFLOW_DEBUG === "1") {
+      console.warn(`Workflow reload bypassed in-flight guard with ${activeRuns} active run(s).`);
+    }
+    const configResult = await loadWorkflowConfig();
+    if (!isWorkflowDiscoveryCurrent(generation)) return;
+    applyWorkflowConfig(configResult);
+    const hasGlobal = configResult.globalConfig != null;
+    const hasProject = configResult.projectConfig != null;
+    const discoveryConfig = hasGlobal || hasProject
+      ? toScopedDiscoveryConfig(configResult.globalConfig ?? null, configResult.projectConfig ?? null, { projectRoot: process.cwd() })
+      : undefined;
+    const packageWorkflowPaths = await loadPackageWorkflowPaths();
+    if (!isWorkflowDiscoveryCurrent(generation)) return;
+    const result = await discoverWorkflows({ config: discoveryConfig, packageWorkflowPaths });
+    if (!isWorkflowDiscoveryCurrent(generation)) return;
+    discoveryRef.current = result;
+    rebuildRuntime(result.registry);
+  }
+
+  async function ensureWorkflowResourcesLoaded(options?: { allowInFlight?: boolean }): Promise<void> {
+    while (!pi.disableAsyncDiscovery && discoveryRef.current === null) {
+      const generation = workflowDiscoveryGeneration;
+      const pending = lazyDiscoveryPromise ?? trackLazyDiscovery(
+        queueWorkflowResourceReload({ allowInFlight: options?.allowInFlight ?? true }, generation),
+      );
+      await pending;
+      if (!isWorkflowDiscoveryCurrent(generation)) continue;
+      if (discoveryRef.current === null) {
+        lazyDiscoveryPromise = null;
+      }
+    }
+  }
+
+  function startWorkflowDiscoveryWarmup(onSettled?: () => void): void {
+    if (pi.disableAsyncDiscovery || discoveryRef.current !== null || lazyDiscoveryPromise !== null) return;
+    const notificationStart = notificationGeneration;
+    const discoveryStart = workflowDiscoveryGeneration;
+    const pending = (async () => {
+      await deferToMacrotask();
+      if (!isWorkflowDiscoveryCurrent(discoveryStart)) return;
+      await queueWorkflowResourceReload({ allowInFlight: true }, discoveryStart);
+    })();
+    lazyDiscoveryPromise = pending;
+    const isCurrentWarmup = (): boolean => lazyDiscoveryPromise === pending
+      && notificationGeneration === notificationStart
+      && isWorkflowDiscoveryCurrent(discoveryStart);
+    void pending
+      .catch((error) => {
+        if (isCurrentWarmup() && process.env.ATOMIC_WORKFLOW_DEBUG === "1") {
+          const message = error instanceof Error ? error.message : String(error);
+          console.warn(`Workflow background discovery failed: ${message}`);
+        }
+      })
+      .finally(() => {
+        const current = isCurrentWarmup();
+        if (lazyDiscoveryPromise === pending) lazyDiscoveryPromise = null;
+        if (!current || !notificationsActive) return;
+        try {
+          onSettled?.();
+        } catch (error) {
+          if (process.env.ATOMIC_WORKFLOW_DEBUG === "1") {
+            const message = error instanceof Error ? error.message : String(error);
+            console.warn(`Workflow background discovery callback failed: ${message}`);
+          }
+        }
+      })
+      .catch(() => {});
+  }
+
   return {
     persistenceRef,
     mcpPort,
     runtimeProxy,
     configLoadRef,
     discoveryRef,
-    discoveryPromise: pi.disableAsyncDiscovery ? Promise.resolve() : reloadWorkflowResources({ allowInFlight: true }),
     lifecycleNotificationState,
     hilAnswerNotificationState,
     runtimeForContext,
+    resetWorkflowDiscoveryForSession,
+    ensureWorkflowConfigLoaded,
+    ensureWorkflowResourcesLoaded,
     reloadWorkflowResources,
+    startWorkflowDiscoveryWarmup,
     runWithLifecycleSuppressedForPolicy(policy, fn) {
       return policy.mode !== "non_interactive" || policy.awaitTerminalRun !== true
         ? fn()
         : withWorkflowLifecycleNotificationsSuppressedAsync(lifecycleNotificationState, fn);
     },
     setNotificationsActive(active) {
+      notificationGeneration += 1;
       notificationsActive = active;
       reinstallLifecycleNotifications();
       reinstallHilAnswerNotifications();

package/dist/builtin/workflows/src/extension/lifecycle-notifications.ts

@@ -15,6 +15,13 @@ import type {
   StoreSnapshot,
 } from "../shared/store-types.js";
 import { isTopLevelWorkflowRun } from "../shared/run-visibility.js";
+import {
+  actionableReturnedStatusText,
+  effectiveRunStatus,
+  isReturnedBlockedWorkflowStatus,
+  normalizeReturnedWorkflowStatus,
+  structuredRecoverableWorkflowFailureText,
+} from "../shared/returned-run-status.js";
 import { deriveGraphThemeFromPiTheme, type GraphTheme } from "../tui/graph-theme.js";
 import { renderWorkflowNoticeCard, type WorkflowNoticeTone } from "../tui/workflow-notice-card.js";
 
@@ -299,13 +306,13 @@ function makeTerminalNotice(
   const failedStage = run.failedStageId
     ? run.stages.find((stage) => stage.id === run.failedStageId)
     : undefined;
-  const error = run.error ?? (kind === "blocked" ? run.exitReason : undefined);
+  const error = run.error ?? returnedNoticeError(run, kind) ?? (kind === "blocked" ? run.exitReason : undefined);
   return {
     kind,
     scope: "run",
     runId: run.id,
     workflowName: run.name,
-    status: run.status,
+    status: effectiveRunStatus(run),
     ...(error ? { error: truncateSnippet(error) } : {}),
     ...(run.failedStageId ? { failedStageId: run.failedStageId } : {}),
     ...(failedStage ? { stageId: failedStage.id, stageName: failedStage.name } : {}),
@@ -330,13 +337,22 @@ function jsonString(value: string): string {
 }
 
 function terminalNoticeKind(run: RunSnapshot): "completed" | "failed" | "blocked" | undefined {
-  if (run.status === "failed" || run.status === "blocked") return run.status;
-  if (run.status !== "completed") return undefined;
-  const returnedStatus = run.result?.["status"];
-  if (returnedStatus === "failed" || returnedStatus === "blocked") return returnedStatus;
+  const status = effectiveRunStatus(run);
+  if (status === "failed" || status === "blocked") return status;
+  if (status !== "completed") return undefined;
   return "completed";
 }
 
+function returnedNoticeError(run: RunSnapshot, kind: "completed" | "failed" | "blocked"): string | undefined {
+  const structuredFailureText = structuredRecoverableWorkflowFailureText(run);
+  if (kind === "blocked" && structuredFailureText !== undefined) return structuredFailureText;
+  const returnedStatus = normalizeReturnedWorkflowStatus(run.result?.["status"]);
+  if (returnedStatus === undefined) return undefined;
+  if (kind === "failed" && returnedStatus === "failed") return actionableReturnedStatusText(run.result);
+  if (kind === "blocked" && isReturnedBlockedWorkflowStatus(returnedStatus)) return actionableReturnedStatusText(run.result);
+  return undefined;
+}
+
 function terminalRunKey(kind: "completed" | "failed" | "blocked", runId: string): string {
   return `${kind}:${runId}`;
 }

package/dist/builtin/workflows/src/extension/public-types.ts

@@ -61,7 +61,7 @@ export type PiArgumentCompletionResult = PiArgumentCompletion[] | null;
 export interface PiCommandOptions {
   description: string;
   handler: (args: string, ctx: PiCommandContext) => Promise<void> | void;
-  getArgumentCompletions?: (partial: string) => PiArgumentCompletionResult;
+  getArgumentCompletions?: (partial: string) => PiArgumentCompletionResult | Promise<PiArgumentCompletionResult>;
 }
 
 export interface PiRuntimeModel {

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

@@ -13,8 +13,9 @@ function completeToken(
     : Math.max(argumentText.lastIndexOf(" "), argumentText.lastIndexOf("\t")) + 1;
   const head = argumentText.slice(0, tokenStart);
   const token = argumentText.slice(tokenStart);
+  const normalizedToken = token.trimEnd();
   const filtered = candidates
-    .filter((candidate) => candidate.value.startsWith(token))
+    .filter((candidate) => candidate.value.startsWith(token) && candidate.value.trimEnd() !== normalizedToken)
     .map((candidate) => ({ ...candidate, value: `${head}${candidate.value}` }));
   return filtered.length > 0 ? filtered : null;
 }
@@ -50,6 +51,17 @@ function runIdItems(): PiArgumentCompletion[] {
   }));
 }
 
+export function workflowArgumentCompletionsNeedWorkflowResources(partial: string): boolean {
+  const parts = partial.trim().split(/\s+/).filter(Boolean);
+  const subcommand = parts[0] ?? "";
+  if (!partial.includes(" ")) return true;
+  if (!subcommand || subcommand === "inputs") return true;
+  if (["status", "connect", "resume", "attach", "pause", "interrupt", "kill", "reload"].includes(subcommand)) {
+    return false;
+  }
+  return true;
+}
+
 export function workflowArgumentCompletions(
   partial: string,
   runtime: ExtensionRuntime,