@bastani/atomic 0.9.9 → 0.9.10-alpha.1

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

@@ -27,13 +27,14 @@ import type {
 } from "@bastani/atomic";
 import type { StageAdapters, StageSessionCreateResult, StageSessionRuntime } from "../runs/foreground/stage-runner.js";
 import type { StageExecutionMeta, StageOptions } from "../shared/types.js";
+import { resolveStageGroup, stageHasIntercomAccess } from "../shared/intercom-group.js";
 import { stageUiBroker, type StageUiBroker } from "../shared/stage-ui-broker.js";
 import { prepareAtomicStageSessionOptions } from "./atomic-stage-session.js";
 import type { PiCodingAgentSdk, PrepareAtomicStageSessionOptions } from "./atomic-stage-session.js";
 export { prepareAtomicStageSessionOptions } from "./atomic-stage-session.js";
 export type { AtomicCreateAgentSessionOptions, PiCodingAgentSdk, PiSdkResourceLoader, PiSdkSettingsManager, PrepareAtomicStageSessionOptions } from "./atomic-stage-session.js";
 import type { PiCustomOverlayFactory, PiCustomOverlayOptions, PiUISurface } from "./ui-surface.js";
-export type { PiCustomComponent, PiCustomOverlayFactory, PiCustomOverlayFactoryTui, PiCustomOverlayFunction, PiCustomOverlayOptions, PiEditorComponent, PiEditorFactory, PiHostCustomUiState, PiHostCustomUiStateListener, PiKeybindings, PiOverlayHandle, PiOverlayOptions, PiTheme, PiUIDialogOptions, PiUISurface, UIWiringSurface } from "./ui-surface.js";
+export type { PiCustomComponent, PiCustomOverlayFactory, PiCustomOverlayFactoryTui, PiCustomOverlayFunction, PiCustomOverlayOptions, PiEditorComponent, PiEditorFactory, PiHostCustomUiState, PiHostCustomUiStateListener, PiHostSessionPickerFunction, PiHostSessionPickerHandle, PiHostSessionPickerRequest, PiHostSessionPickerRow, PiKeybindings, PiOverlayHandle, PiOverlayOptions, PiRemoteTerminalControl, PiTheme, PiUIDialogOptions, PiUISurface, UIWiringSurface } from "./ui-surface.js";
 
 // ---------------------------------------------------------------------------
 // Minimal pi surface
@@ -60,6 +61,23 @@ export interface PiExecOpts {
   timeout?: number;
 }
 
+type StageLateMessageRouter = NonNullable<
+  NonNullable<CreateAgentSessionOptions["orchestrationContext"]>["lateMessageRouter"]
+>;
+
+const LATE_STAGE_MESSAGE_EVENT = "atomic:workflow-stage-late-message";
+type LateStageMessage = Parameters<StageLateMessageRouter["routeMessage"]>[0];
+type LateStageMessageEvent = {
+  handled: boolean;
+  completion?: Promise<void>;
+  batch: boolean;
+  messages: LateStageMessage[];
+  workflowRunId: string;
+  workflowStageId: string;
+  workflowStageName: string;
+  options?: Parameters<StageLateMessageRouter["routeMessage"]>[1];
+};
+
 export interface RuntimeWiringSurface {
   exec?: (command: string, args: string[], opts?: PiExecOpts) => Promise<PiExecResult>;
   ui?: PiUISurface;
@@ -67,6 +85,9 @@ export interface RuntimeWiringSurface {
   getResourceLoaderInheritanceSnapshot?: () => DefaultResourceLoaderInheritanceSnapshot | undefined;
   /** Test seam: inject a stub session factory instead of importing the SDK. */
   createAgentSession?: (options?: CreateAgentSessionOptions) => Promise<StageSessionCreateResult>;
+  sendMessage?: StageLateMessageRouter["routeMessage"];
+  sendMessages?: StageLateMessageRouter["routeMessages"];
+  events?: { emit?: (channel: string, data: Record<string, unknown>) => void };
 }
 
 export interface RuntimeAdapterBuildOptions {
@@ -170,19 +191,63 @@ async function createTestAgentSession(_options?: CreateAgentSessionOptions): Pro
 function stripWorkflowOnlyOptions(options: (StageOptions | CreateAgentSessionOptions) | undefined): CreateAgentSessionOptions | undefined {
   if (!options) return options;
   const maybeWorkflowOptions = options as StageOptions;
-  const { schema: _schema, mcp: _mcp, fallbackModels: _fallbackModels, ...sessionOptions } = maybeWorkflowOptions;
+  const { schema: _schema, mcp: _mcp, fallbackModels: _fallbackModels, group: _group, ...sessionOptions } = maybeWorkflowOptions;
   return sessionOptions as CreateAgentSessionOptions;
 }
 
-function makeWorkflowStageOrchestrationContext(meta: StageExecutionMeta): NonNullable<CreateAgentSessionOptions["orchestrationContext"]> {
+function emitLateIntercomRoute(
+  pi: RuntimeWiringSurface,
+  meta: StageExecutionMeta,
+  messages: LateStageMessage[],
+  options: LateStageMessageEvent["options"] | undefined,
+  batch: boolean,
+): Promise<void> | undefined {
+  if (!messages.some((message) => message.customType === "intercom_message") || !pi.events?.emit) return undefined;
+  const event: LateStageMessageEvent = {
+    handled: false,
+    messages,
+    options,
+    batch,
+    workflowRunId: meta.runId,
+    workflowStageId: meta.stageId,
+    workflowStageName: meta.stageName,
+  };
+  pi.events.emit(LATE_STAGE_MESSAGE_EVENT, event as unknown as Record<string, unknown>);
+  if (!event.handled) return undefined;
+  return event.completion ?? Promise.resolve();
+}
+
+function makeWorkflowStageOrchestrationContext(
+  meta: StageExecutionMeta,
+  pi: RuntimeWiringSurface,
+): NonNullable<CreateAgentSessionOptions["orchestrationContext"]> {
+  const intercomGroup = stageHasIntercomAccess(meta.stageOptions) ? resolveStageGroup(meta.stageOptions) : undefined;
   return {
     kind: "workflow-stage",
     workflowRunId: meta.runId,
     workflowStageId: meta.stageId,
     workflowStageName: meta.stageName,
-    constraints: {
-      disableWorkflowTool: true,
-      maxSubagentDepth: 5,
+    constraints: { disableWorkflowTool: true, maxSubagentDepth: 5 },
+    ...(intercomGroup ? { intercomGroup } : {}),
+    lateMessageRouter: {
+      routeMessage(message, options) {
+        const intercomRoute = emitLateIntercomRoute(pi, meta, [message], options, false);
+        if (intercomRoute) return intercomRoute;
+        if (!pi.sendMessage) throw new Error("atomic-workflows: main-chat late-message route is unavailable");
+        return pi.sendMessage(message, options);
+      },
+      routeMessages(messages, options) {
+        const intercomRoute = emitLateIntercomRoute(pi, meta, messages, options, true);
+        if (intercomRoute) return intercomRoute;
+        if (pi.sendMessages) return pi.sendMessages(messages, options);
+        const sendMessage = pi.sendMessage;
+        if (!sendMessage) throw new Error("atomic-workflows: main-chat late-message route is unavailable");
+        return (async () => {
+          for (const [index, message] of messages.entries()) {
+            await sendMessage(message, index === 0 ? options : { deliverAs: "followUp" });
+          }
+        })();
+      },
     },
   };
 }
@@ -190,6 +255,7 @@ function makeWorkflowStageOrchestrationContext(meta: StageExecutionMeta): NonNul
 function withWorkflowStageSessionOptions(
   options: CreateAgentSessionOptions,
   meta: StageExecutionMeta | undefined,
+  pi: RuntimeWiringSurface,
 ): CreateAgentSessionOptions {
   // Workflow stage sessions should never see the workflow tool, even when older
   // meta-less callers cannot receive the richer runtime orchestration context.
@@ -204,7 +270,9 @@ function withWorkflowStageSessionOptions(
   return {
     ...options,
     excludedTools,
-    ...(meta ? { orchestrationContext: makeWorkflowStageOrchestrationContext(meta) } : {}),
+    ...(meta
+      ? { orchestrationContext: meta.orchestrationContext ?? makeWorkflowStageOrchestrationContext(meta, pi) }
+      : {}),
   };
 }
 
@@ -309,6 +377,7 @@ export function buildRuntimeAdapters(
         const sessionOptions = withWorkflowStageSessionOptions(
           stripWorkflowOnlyOptions(stageOptions) ?? {},
           meta,
+          pi,
         );
         const result = await createSession(sessionOptions);
         const bindable = result.session as BindableStageSession;

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

@@ -27,7 +27,7 @@ function adminCompletions(): PiArgumentCompletion[] {
     { value: "list ", label: "list", description: "List registered workflows" },
     { value: "status ", label: "status", description: "List current-session active and retained terminal runs" },
     { value: "interrupt ", label: "interrupt", description: "Interrupt a run" },
-    { value: "kill ", label: "kill", description: "Kill and retain a run for inspection" },
+    { value: "quit ", label: "quit", description: "Quit a run and keep it resumable" },
     { value: "pause ", label: "pause", description: "Pause a run or stage" },
     { value: "resume ", label: "resume", description: "Re-open overlay for a run" },
     { value: "inputs ", label: "inputs", description: "Show a workflow's input schema" },
@@ -56,7 +56,7 @@ export function workflowArgumentCompletionsNeedWorkflowResources(partial: string
   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)) {
+  if (["status", "connect", "resume", "attach", "pause", "interrupt", "quit", "reload"].includes(subcommand)) {
     return false;
   }
   return true;
@@ -76,15 +76,20 @@ export function workflowArgumentCompletions(
   if (["status", "connect", "resume", "attach", "pause"].includes(subcommand)) {
     return completeToken(partial, runIdItems());
   }
-  if (subcommand === "interrupt" || subcommand === "kill") {
-    const verb = subcommand === "kill" ? "Kill and retain" : "Interrupt";
+  if (subcommand === "interrupt") {
     return completeToken(partial, [
-      { value: "--all ", label: "--all", description: `${verb} all in-flight runs` },
+      { value: "--all ", label: "--all", description: "Interrupt all in-flight runs" },
       { value: "--yes ", label: "--yes", description: "Skip confirmation" },
       { value: "-y ", label: "-y", description: "Skip confirmation" },
       ...runIdItems(),
     ]);
   }
+  if (subcommand === "quit") {
+    return completeToken(partial, [
+      { value: "--all ", label: "--all", description: "Quit and keep all in-flight runs resumable" },
+      ...runIdItems(),
+    ]);
+  }
   if (!subcommand) return completeToken(partial, [...adminCompletions(), ...workflows()]);
 
   const workflow = runtime.registry.get(subcommand);

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

@@ -5,6 +5,7 @@ import { store } from "../shared/store.js";
 import type { WorkflowExecutionPolicy } from "../shared/types.js";
 import { emitChatSurface } from "../tui/chat-surface-message.js";
 import { openInlineInputsForm } from "../tui/inline-form-overlay.js";
+import { openHostInputsForm } from "../tui/host-input-form.js";
 import { openInputsPicker } from "../tui/inputs-overlay.js";
 import { deriveGraphTheme } from "../tui/graph-theme.js";
 import { selectRunsForPicker } from "../tui/session-picker.js";
@@ -59,7 +60,7 @@ export function registerWorkflowSlashCommand(
     pi,
     "workflow",
     {
-      description: "Run or inspect Atomic workflows. Usage: /workflow <name> [key=value…] | /workflow [list|status|connect|attach|interrupt|kill|pause|resume|inputs|reload] [args]",
+      description: "Run or inspect Atomic workflows. Usage: /workflow <name> [key=value…] | /workflow [list|status|connect|attach|interrupt|quit|pause|resume|inputs|reload] [args]",
       handler: (args, ctx) => workflowSlashHandler(args, ctx, pi, deps),
       getArgumentCompletions: (partial: string): PiArgumentCompletionResult | Promise<PiArgumentCompletionResult> => {
         const buildCompletions = (): PiArgumentCompletionResult => workflowArgumentCompletions(partial, deps.runtimeProxy);
@@ -69,6 +70,18 @@ export function registerWorkflowSlashCommand(
     },
     workflowCommands,
   );
+  registerWorkflowCommand(
+    pi,
+    "workflows",
+    {
+      description: "List retained workflow runs or open one by id. Usage: /workflows [run-id]",
+      handler: (args, ctx) => {
+        const target = args.trim();
+        return workflowSlashHandler(target.length === 0 ? "resume" : `resume ${target}`, ctx, pi, deps);
+      },
+    },
+    workflowCommands,
+  );
 }
 
 async function workflowSlashHandler(
@@ -154,10 +167,14 @@ async function workflowSlashHandler(
     }
     return;
   }
-  if (subcommand === "interrupt" || subcommand === "kill") {
+  if (subcommand === "interrupt") {
     await handleRunControlCommand(subcommand, withImplicitYesFlag(parts.slice(1)), ctx, reporter, deps.runControl);
     return;
   }
+  if (subcommand === "quit") {
+    await handleRunControlCommand(subcommand, parts.slice(1), ctx, reporter, deps.runControl);
+    return;
+  }
   if (subcommand === "inputs") {
     const workflowName = parts[1] ?? "";
     if (!workflowName) return fail("Usage: /workflow inputs <name>");
@@ -176,7 +193,9 @@ async function workflowSlashHandler(
   let mergedInputs = inputs;
   let pickerWasShown = false;
   const canOpenPicker = policy.allowInputPicker && !wantsPickerSkip && (
-    typeof ctx.ui?.setEditorComponent === "function" || typeof ctx.ui?.custom === "function"
+    typeof ctx.ui?.hostInputForm === "function" ||
+    typeof ctx.ui?.setEditorComponent === "function" ||
+    typeof ctx.ui?.custom === "function"
   );
   if (canOpenPicker) {
     await ensureWorkflowResourcesVisible();
@@ -191,9 +210,12 @@ async function workflowSlashHandler(
     if (fields.length > 0 && (inputTokens.length === 0 || missingRequired)) {
       pickerWasShown = true;
       const pickerTheme = deriveGraphTheme({});
-      let pickerResult = typeof ctx.ui?.setEditorComponent === "function"
-        ? await openInlineInputsForm(pi, ctx, { workflowName, fields, prefilled: inputs, theme: pickerTheme })
+      let pickerResult = typeof ctx.ui?.hostInputForm === "function"
+        ? await openHostInputsForm(ctx.ui, { workflowName, fields, prefilled: inputs })
         : { kind: "unsupported" as const };
+      if (pickerResult.kind === "unsupported" && typeof ctx.ui?.setEditorComponent === "function") {
+        pickerResult = await openInlineInputsForm(pi, ctx, { workflowName, fields, prefilled: inputs, theme: pickerTheme });
+      }
       if (pickerResult.kind === "unsupported" && typeof ctx.ui?.custom === "function") {
         pickerResult = await openInputsPicker(ctx.ui, { workflowName, fields, prefilled: inputs, theme: pickerTheme });
       }

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

@@ -1,4 +1,3 @@
-import type { WorkflowPersistencePort } from "../shared/types.js";
 import { store } from "../shared/store.js";
 import type { RunSnapshot } from "../shared/store-types.js";
 import { openWorkflowResumeSelector } from "../tui/workflow-resume-selector.js";
@@ -7,6 +6,10 @@ import { formatResumableWorkflowList } from "../durable/resume-catalog.js";
 import { getDurableBackend } from "../durable/factory.js";
 import { listOpenableCompletedWorkflows } from "../durable/completed-catalog.js";
 import { openCompletedDurableWorkflow } from "../durable/completed-inspection.js";
+import {
+  deleteDurableWorkflowIfSafe,
+  type DurableWorkflowDeleteOutcome,
+} from "../durable/retention-policy.js";
 import type { ResumableWorkflowEntry } from "../durable/types.js";
 import type { ExtensionRuntime } from "./runtime.js";
 import type { ExtensionAPI, PiCommandContext } from "./public-types.js";
@@ -18,7 +21,6 @@ import { overlaySurfaceFromContext } from "./workflow-targets.js";
 export interface WorkflowRunControlDeps {
   pi: ExtensionAPI;
   overlay: GraphOverlayPort;
-  getPersistence: () => WorkflowPersistencePort | undefined;
   runtimeForContext: (ctx?: PiCommandContext) => ExtensionRuntime;
   ensureWorkflowResourcesLoaded: () => Promise<void> | void;
 }
@@ -43,24 +45,36 @@ export async function prepareWorkflowResumeCatalog(
   activeLiveIds: ReadonlySet<string>,
   target?: string,
 ): Promise<WorkflowResumeCatalog> {
-  const prepared = await runtime.prepareDurableResumable(target);
+  const shared = await runtime.prepareDurableCatalog?.();
+  const prepared = shared?.resumable ?? await runtime.prepareDurableResumable(target);
   const backend = getDurableBackend();
+  const isDisplayLoadable = (entry: ResumableWorkflowEntry): boolean =>
+    shared !== undefined || backend.isWorkflowLoadable(entry.workflowId);
   const resumable = filterSelectorDurableEntries(runtime, prepared)
-    .filter((entry) => !activeLiveIds.has(entry.workflowId) && backend.isWorkflowLoadable(entry.workflowId));
-  const completed = runtime.prepareCompletedDurable !== undefined
+    .filter((entry) => !activeLiveIds.has(entry.workflowId) && isDisplayLoadable(entry));
+  const completed = shared?.completed ?? (runtime.prepareCompletedDurable !== undefined
     ? await runtime.prepareCompletedDurable()
-    : listOpenableCompletedWorkflows(backend);
+    : listOpenableCompletedWorkflows(backend));
   return {
     resumable,
-    completed: completed.filter((entry) => !activeLiveIds.has(entry.workflowId) && backend.isWorkflowLoadable(entry.workflowId)),
+    completed: completed.filter((entry) => !activeLiveIds.has(entry.workflowId) && isDisplayLoadable(entry)),
   };
 }
 
+export function deleteWorkflowResumeEntry(workflowId: string): Promise<DurableWorkflowDeleteOutcome> {
+  return deleteDurableWorkflowIfSafe(getDurableBackend(), workflowId, (candidateId) => {
+    const run = store.runs().find((candidate) => candidate.id === candidateId);
+    return run !== undefined && run.status !== "completed"
+      && (run.endedAt === undefined || run.status === "paused");
+  });
+}
+
 export async function handleDurableResume(
   target: string | undefined,
   ctx: PiCommandContext,
   reporter: WorkflowCommandReporter,
   deps: WorkflowRunControlDeps,
+  preparedCatalog?: WorkflowResumeCatalog,
 ): Promise<boolean> {
   const print = (message: string): void => reporter.info(message);
   const fail = (message: string): void => reporter.error(message);
@@ -71,7 +85,7 @@ export async function handleDurableResume(
   }
   const runtime = deps.runtimeForContext(ctx);
   const policy = workflowPolicyFromContext(ctx);
-  const catalog = await prepareWorkflowResumeCatalog(runtime, new Set(), target);
+  const catalog = preparedCatalog ?? await prepareWorkflowResumeCatalog(runtime, new Set(), target);
   const allOpenable = [...catalog.resumable, ...catalog.completed];
 
   if (target !== undefined) {
@@ -79,7 +93,9 @@ export async function handleDurableResume(
       target,
       [],
       catalog.resumable,
-      getDurableBackend().listCompletedWorkflows(),
+      // Reuse the catalog prepared above instead of re-enumerating the durable
+      // directory a second time for the same command invocation.
+      catalog.completed,
     );
     if (resolved.kind === "ambiguous") {
       fail(`Ambiguous workflow prefix "${target}" matches: ${formatMatches(resolved.matches)}`);
@@ -89,7 +105,7 @@ export async function handleDurableResume(
       return openCompletedTarget(resolved.workflowId, catalog.completed, ctx, reporter, deps, runtime);
     }
     if (resolved.kind === "durable") {
-      return resumeDurableTarget(resolved.workflowId, ctx, reporter, deps, runtime);
+      return await resumeDurableTarget(resolved.workflowId, ctx, reporter, deps, runtime);
     }
 
     const completedAttempt = openCompleted(runtime, target, catalog.completed);
@@ -97,7 +113,7 @@ export async function handleDurableResume(
       fail(completedAttempt.message);
       return true;
     }
-    const result = runtime.resumeDurableWorkflow(target, { policy });
+    const result = await runtime.resumeDurableWorkflow(target, { policy });
     fail(allOpenable.length === 0
       ? result.message
       : `${result.message}\n\n${formatResumableWorkflowList(allOpenable)}`);
@@ -113,12 +129,26 @@ export async function handleDurableResume(
     print(`${formatResumableWorkflowList(allOpenable)}\n\n${instruction}: /workflow resume <id>`);
     return true;
   }
-  const picked = await openWorkflowResumeSelector(ctx.ui, [], catalog.resumable, catalog.completed);
-  if (picked.kind === "durable") {
-    return resumeDurableTarget(picked.workflowId, ctx, reporter, deps, runtime);
+  let picked: Awaited<ReturnType<typeof openWorkflowResumeSelector>>;
+  try {
+    picked = await openWorkflowResumeSelector(
+      ctx.ui,
+      [],
+      // Catalog already prepared above; resolve it immediately with no rescan.
+      () => Promise.resolve({ durable: catalog.resumable, completed: catalog.completed }),
+      { deleteWorkflow: deleteWorkflowResumeEntry },
+    );
+  } catch (error) {
+    // No fallback: a host without the session-picker capability fails the
+    // resume command with one actionable message.
+    fail(error instanceof Error ? error.message : String(error));
+    return true;
+  }
+  if (picked.result.kind === "durable") {
+    return resumeDurableTarget(picked.result.workflowId, ctx, reporter, deps, runtime);
   }
-  if (picked.kind === "completed") {
-    return openCompletedTarget(picked.workflowId, catalog.completed, ctx, reporter, deps, runtime);
+  if (picked.result.kind === "completed") {
+    return openCompletedTarget(picked.result.workflowId, catalog.completed, ctx, reporter, deps, runtime);
   }
   return true;
 }
@@ -172,14 +202,14 @@ function isExplicitResumeCandidate(run: RunSnapshot): boolean {
   return run.resumable === true && run.failureRecoverability === "recoverable";
 }
 
-function resumeDurableTarget(
+async function resumeDurableTarget(
   workflowId: string,
   ctx: PiCommandContext,
   reporter: WorkflowCommandReporter,
   deps: WorkflowRunControlDeps,
   runtime: ExtensionRuntime,
-): boolean {
-  const result = runtime.resumeDurableWorkflow(workflowId, { policy: workflowPolicyFromContext(ctx) });
+): Promise<boolean> {
+  const result = await runtime.resumeDurableWorkflow(workflowId, { policy: workflowPolicyFromContext(ctx) });
   if (!result.ok) reporter.error(result.message);
   else {
     reporter.info(result.message);

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

@@ -1,19 +1,19 @@
 export const WORKFLOW_TOOL_DESCRIPTION =
-  "Run named builtin, project, user, or package workflows, or direct one-off task/tasks/chain workflows; custom definitions may import reusable project/package workflows or builtin definitions from @bastani/workflows/builtin and nest them with ctx.workflow(...), including deeper composition within the configured maxDepth; " +
+  "Run named builtin, project, user, or package workflows; custom definitions may import reusable project/package workflows or builtin definitions from @bastani/workflows/builtin and nest them with ctx.workflow(...), including deeper composition within the configured maxDepth; " +
   "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. " +
+  "discover with list/get/inputs, list session runs with status (no runId; statusFilter narrows the list), inspect status/stages/stage details, " +
+  "send prompt answers or steering, pause/resume/interrupt/quit 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. " +
   "For transcripts, prefer status/stages/stage to get sessionFile/transcriptPath, " +
   "quote the exact path without rewriting separators (Windows backslashes are valid), " +
   "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 one-off tracked \`task\`, \`tasks\`, or \`chain\` shapes; when the task needs richer control flow, author a custom TypeScript \`workflow({...})\` inline with normal coding tools, reload workflow resources, and run it.
+  `**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; when the task needs a graph that is not installed, author a custom TypeScript \`workflow({...})\` inline with normal coding tools, reload workflow resources, and run it.
   - 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 workflow. Reconnaissance counts as inline execution, so an unstated "explore first" default must not silently commit you to an unbounded inline session.
   - Workflow fit check: prefer a workflow for implementation, build, debug/diagnosis, bug-fix, migration, new-feature, scoped multi-file, or docs/code changes with validation; and whenever there are multiple steps, dependencies, handoffs, uncertainty, review/validation needs, long-running work, measurable done criteria, or an outcome that needs evidence.
   - Treat loop or stop-condition wording as a strong workflow signal, especially "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 an approval gate or evidence requirement.
-  - Do not force-fit an installed workflow, direct one-off shape, or builtin such as \`goal\` or \`ralph\`. When another graph better matches the task, write a task-specific TypeScript workflow inline. Use and combine the documented starter patterns: Classify-and-act for runtime routing, Fan-out-and-synthesize for independent slices, Adversarial verification for worker/reviewer/reducer repair, Generate-and-filter or Tournament for competing candidates, and Loop until done for bounded convergence. Rich custom workflows may use deterministic branching, dynamic fan-out, child workflows, artifacts, structured outputs, human-in-the-loop prompts, gates, retries, and explicit stop conditions.
+  - Do not force-fit an installed workflow or builtin such as \`goal\` or \`ralph\`. When another graph better matches the task, write a task-specific TypeScript workflow inline. Use and combine the documented starter patterns: Classify-and-act for runtime routing, Fan-out-and-synthesize for independent slices, Adversarial verification for worker/reviewer/reducer repair, Generate-and-filter or Tournament for competing candidates, and Loop until done for bounded convergence. Rich custom workflows may use deterministic branching, dynamic fan-out, child workflows, artifacts, structured outputs, human-in-the-loop prompts, gates, retries, and explicit stop conditions.
   - Compose workflows instead of rebuilding every capability in one graph. Workflow definitions are normal TypeScript modules: import reusable project/package definitions or builtins from \`@bastani/workflows/builtin\`, then call \`ctx.workflow(childDefinition, { inputs, stageName })\`. Imported children may nest more workflows up to \`maxDepth\`; their stages, HIL prompts, control, durability, and declared outputs remain part of the expanded parent graph. Pass definitions, not registry-name strings or paths.
   - Composition examples: import \`deepResearchCodebase\`, then conditionally nest \`goal\` or \`ralph\` for implementation; wrap \`openClaudeDesign\` with project-specific approval/export stages; or build a reusable user-defined research child and import it into several parent workflows. Prefer composing a proven builtin or shared child over copying its prompt/graph.
   - Example custom shapes: classify a request and dispatch category-specific stages; fan out per package and synthesize artifact-backed results; implement, run fresh-context verifiers, reduce findings, and loop through repairs until approved; generate several plans and filter or tournament-rank them; or rerun checks and fixes until green with a progress ledger and max-iteration escape hatch.
@@ -22,9 +22,9 @@ export const DEFAULT_PROMPT_GUIDANCE: string[] = [
   - Only skip workflows for tiny, deterministic, low-risk answers or direct edits where stage tracking clearly costs more than it adds, typically a single-file/no-test/no-review change or a simple answer.`,
   `**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.
-  - In interactive chat, launch every workflow in the background. Named workflow launches are already detached; direct \`task\`, \`tasks\`, and \`chain\` launches must set top-level \`async: true\`. This applies only to launches, not inspection or control calls (\`status\`, \`stages\`, \`stage\`, \`transcript\`, \`send\`, \`pause\`, \`resume\`, \`interrupt\`, \`kill\`). Use foreground execution only when the user explicitly requests it or it is technically required, and tell the user before launching it.
-  - Natural-language instructions to create or use a worktree do not enable runner isolation. For write-capable direct tasks, set \`worktree: true\` or \`gitWorktreeDir\`; \`cwd\` only selects the starting directory and runs in that checkout. For independent queues, prefer one run per independent item with its own reusable worktree.
-  - 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.
+  - In interactive chat, named workflow launches run in the background. Run \`/workflow connect <run>\` to see agents working and chat with and steer each stage. Inspection and control calls (\`status\`, \`stages\`, \`stage\`, \`transcript\`, \`send\`, \`pause\`, \`resume\`, \`interrupt\`, \`quit\`) remain available while work runs.
+  - Natural-language instructions to create or use a worktree do not enable runner isolation. A named workflow must declare and implement any worktree inputs it supports; inspect its inputs before launching it.
+  - 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\`/\`quit\` 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.

package/dist/builtin/workflows/src/extension/workflow-resume-picker-rows.ts

@@ -0,0 +1,81 @@
+/**
+ * Row sources for the `/workflow resume` picker.
+ *
+ * Only inactive workflows belong in the resume selector. Live runs contribute
+ * paused (quit) or recoverably-failed rows; actively-running live runs are
+ * hidden because resuming an executing workflow would double-dispatch it.
+ * The same collection backs the picker's live refresh (store changes plus a
+ * bounded cross-session poll), so state transitions appear while it is open.
+ */
+
+import { getDurableBackend } from "../durable/factory.js";
+import type { ResumableWorkflowEntry } from "../durable/types.js";
+import type { Store } from "../shared/store.js";
+import type { RunSnapshot } from "../shared/store-types.js";
+import { topLevelWorkflowRuns } from "../shared/run-visibility.js";
+import type { WorkflowResumeRefresh } from "../tui/workflow-resume-selector.js";
+import { reconcileDurableResumeShadow } from "./workflow-resume-shadow.js";
+import type { ExtensionRuntime } from "./runtime.js";
+import { prepareWorkflowResumeCatalog } from "./workflow-durable-resume-command.js";
+
+export interface ResumePickerLiveSource {
+  readonly liveRuns: readonly RunSnapshot[];
+  readonly activeLiveIds: ReadonlySet<string>;
+}
+
+function isActiveRecoverableBlock(run: RunSnapshot): boolean {
+  return run.endedAt === undefined
+    && run.resumable === true
+    && run.failureRecoverability === "recoverable";
+}
+
+export function collectResumePickerLiveRuns(runStore: Store): ResumePickerLiveSource {
+  const durableResumeShadows = new Set(
+    topLevelWorkflowRuns(runStore.runs())
+      .filter((run) => reconcileDurableResumeShadow(run, runStore))
+      .map((run) => run.id),
+  );
+  const liveRuns = topLevelWorkflowRuns(runStore.runs()).filter((run) =>
+    !durableResumeShadows.has(run.id) &&
+    (run.status === "paused" || (run.status === "failed" && run.resumable !== false) || isActiveRecoverableBlock(run)) &&
+    getDurableBackend().isWorkflowLoadable(run.id),
+  );
+  const activeLiveIds = new Set(
+    topLevelWorkflowRuns(runStore.runs())
+      .filter((run) =>
+        !durableResumeShadows.has(run.id) &&
+        run.endedAt === undefined &&
+        run.status === "running" &&
+        !isActiveRecoverableBlock(run) &&
+        run.exitReason !== "quit")
+      .map((run) => run.id),
+  );
+  return { liveRuns, activeLiveIds };
+}
+
+export interface ResumePickerLiveUpdateOptions {
+  readonly watch: (onChange: () => void) => () => void;
+  readonly refresh: WorkflowResumeRefresh;
+}
+
+export function resumePickerLiveUpdateOptions(
+  runStore: Store,
+  runtime: ExtensionRuntime,
+): ResumePickerLiveUpdateOptions {
+  return {
+    watch: (onChange) => runStore.subscribe(() => onChange()),
+    refresh: async () => {
+      const current = collectResumePickerLiveRuns(runStore);
+      const catalog = await prepareWorkflowResumeCatalog(runtime, current.activeLiveIds);
+      return {
+        liveRuns: current.liveRuns,
+        catalog: { durable: catalog.resumable, completed: catalog.completed },
+      };
+    },
+  };
+}
+
+export interface ResumePickerCatalogRows {
+  readonly durable: readonly ResumableWorkflowEntry[];
+  readonly completed: readonly ResumableWorkflowEntry[];
+}

package/dist/builtin/workflows/src/extension/workflow-resume-shadow.ts

@@ -0,0 +1,55 @@
+import type { DurableWorkflowBackend } from "../durable/backend.js";
+import { getLoadableDurableWorkflow } from "../durable/workflow-status-transition.js";
+import { getDurableBackend } from "../durable/factory.js";
+import { isDurableWorkflowResumable } from "../durable/resume-eligibility.js";
+import { jobTracker, type JobTracker } from "../runs/background/job-tracker.js";
+import {
+  stageControlRegistry,
+  type StageControlRegistry,
+} from "../runs/foreground/stage-control-registry.js";
+import { expandWorkflowGraph } from "../shared/expanded-workflow-graph.js";
+import type { Store } from "../shared/store-public-types.js";
+import type { RunSnapshot } from "../shared/store-types.js";
+
+interface DurableResumeShadowDeps {
+  readonly backend?: DurableWorkflowBackend;
+  readonly jobs?: JobTracker;
+  readonly stageControls?: StageControlRegistry;
+}
+
+export type DurableResumeShadowClassification = "eligible" | "ineligible" | "not_shadow";
+
+/** Classify restored metadata without manufacturing progress the durable backend rejects. */
+export function classifyDurableResumeShadow(
+  run: RunSnapshot,
+  store: Store,
+  deps: DurableResumeShadowDeps = {},
+): DurableResumeShadowClassification {
+  const backend = deps.backend ?? getDurableBackend();
+  const handle = getLoadableDurableWorkflow(backend, run.id);
+  if (handle?.status !== "paused" && handle?.status !== "running") return "not_shadow";
+  const jobs = deps.jobs ?? jobTracker;
+  if (jobs.has(run.id)) return "not_shadow";
+  const controls = deps.stageControls ?? stageControlRegistry;
+  const graph = expandWorkflowGraph(store.snapshot(), run.id);
+  const controlRunIds = new Set<string>([run.id]);
+  for (const stage of graph.stages) controlRunIds.add(stage.workflowGraphTarget.runId);
+  if ([...controlRunIds].some((runId) => controls.run(runId).stages().length > 0)) return "not_shadow";
+  if (!isDurableWorkflowResumable(handle)) return "ineligible";
+  if (run.status !== "paused" || run.exitReason !== "quit" || run.resumable !== true) {
+    store.recordRunPaused(run.id, undefined, { exitReason: "quit", resumable: true });
+  }
+  return "eligible";
+}
+
+/**
+ * Reconcile a session-restored snapshot with an authoritative resumable
+ * durable handle. Live jobs/controls win; zero-progress orphans remain intact.
+ */
+export function reconcileDurableResumeShadow(
+  run: RunSnapshot,
+  store: Store,
+  deps: DurableResumeShadowDeps = {},
+): boolean {
+  return classifyDurableResumeShadow(run, store, deps) === "eligible";
+}