@tt-a1i/openpi 0.3.0 → 0.4.0

package/extensions/workflows/index.ts

@@ -17,9 +17,9 @@
  * `agent()` always resolves to `{ ok, output, structured?, error? }` — it
  * never throws into the script. Scripts branch on `ok` explicitly.
  *
- * Runs are blocking by default (live progress in the tool block). Pass
- * `background: true` to return immediately and get a follow-up message when
- * the run finishes. Run artifacts (script, args, statuses, result) are saved
+ * Interactive runs detach by default and deliver a completion turn later.
+ * Pass `wait: true` when the current tool call must return the final result.
+ * Run artifacts (script, args, statuses, result) are saved
  * under `~/.pi/agent/workflows/<runId>/` for inspection; result and bounded
  * transcripts use separate artifacts.
  *
@@ -33,26 +33,41 @@ import { randomBytes } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import {
+  type ExtensionAPI,
+  type ExtensionContext,
   getAgentDir,
   getMarkdownTheme,
   keyHint,
-  type ExtensionAPI,
   type SessionManager,
-  type ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
-import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
-import { Type, type Static } from "typebox";
+import {
+  Container,
+  Markdown,
+  Spacer,
+  Text,
+  truncateToWidth,
+} from "@earendil-works/pi-tui";
+import { type Static, Type } from "typebox";
 import { formatActivityStatus } from "../shared/activity-status.ts";
 import { waitBounded } from "../shared/child-session.ts";
+import { contextPercent } from "../shared/context-utilization.ts";
 import {
   registerEditorLayer,
   removeEditorLayer,
 } from "../shared/editor-layers.ts";
+import { fitNavigationSides } from "../shared/below-editor-navigation.ts";
 import { loadSetupConfig } from "../shared/setup-config.ts";
+import { SPINNER_INTERVAL_MS } from "../shared/spinner.ts";
 import {
   OPENPI_TOOL_SURFACE,
   patchOwnedTools,
 } from "../shared/tool-surface.ts";
+import {
+  createWorktree,
+  reclaimWorktree,
+  type Worktree,
+  type WorktreeCleanup,
+} from "../shared/worktree.ts";
 import {
   loadAgentTypes,
   resolveAgentModel,
@@ -60,16 +75,30 @@ import {
   selectSubagentModel,
 } from "../subagents/src/agent-types.ts";
 import {
-  createWorktree,
-  reclaimWorktree,
-  type Worktree,
-  type WorktreeCleanup,
-} from "../shared/worktree.ts";
+  acceptanceInstruction,
+  acceptanceSchema,
+  applyAcceptance,
+  evaluateAcceptance,
+  parseAcceptanceContract,
+} from "./acceptance.ts";
 import {
   createWorkflowPersistence,
   loadJournal,
+  persistWorkflowAgentResult,
   persistWorkflowJson,
 } from "./artifacts.ts";
+import { RunController } from "./controller.ts";
+import {
+  resolveWorkflowLaunchPolicy,
+  waitForWorkflowCompletion,
+} from "./coordinator.ts";
+import {
+  listPersistedRunIds,
+  readPersistedWorkflowDetails,
+  recoverStaleWorkflowDetails,
+  sessionWorkflowRunIds,
+  showWorkflowDashboard,
+} from "./dashboard.ts";
 import { createWorkflowHandoffRegistry } from "./handoff.ts";
 import {
   classifyInterruptedInvocation,
@@ -77,57 +106,59 @@ import {
   requestInvocation,
   transitionInvocation,
 } from "./invocation-ledger.ts";
-import {
-  normalizeWorkflowOperatorKey,
-  WorkflowOperatorRegistry,
-} from "./operator.ts";
 import {
   agentCallKey,
   createReplayCache,
   type JournalEntry,
   type ReplayCache,
 } from "./journal.ts";
-import { RunController } from "./controller.ts";
-import {
-  normalizePersistedWorkflowDetails,
-  recoverStaleWorkflowDetails,
-  sessionWorkflowRunIds,
-  showWorkflowDashboard,
-} from "./dashboard.ts";
 import {
   extractMeta,
   prepareWorkflowScript,
   type WorkflowMeta,
 } from "./meta.ts";
 import {
+  type AgentRecord,
   agentContext,
   aggregateUsage,
   appendLog,
   countStates,
+  createUsageReader,
   emptyUsage,
   formatElapsed,
   formatUsage,
   isWorkflowRunId,
   phaseGroups,
+  refreshWorkflowGraph,
   resolveWorkflowRunTarget,
   resultJson,
   sanitizeLine,
   sanitizeWorkflowDisplayLine,
   sanitizeWorkflowDisplayText,
-  stateSquare,
+  stateGlyph,
   statusColor,
+  statusGlyph,
   statusWord,
-  createUsageReader,
-  refreshWorkflowGraph,
-  SQUARE,
-  type AgentRecord,
   type WorkflowDetails,
 } from "./model.ts";
+import {
+  WorkflowNavigationEditor,
+  type WorkflowStripEntry,
+  WorkflowStripState,
+  WorkflowStripWidget,
+} from "./navigation.ts";
+import {
+  normalizeWorkflowOperatorKey,
+  WorkflowOperatorRegistry,
+} from "./operator.ts";
 import {
   buildBackgroundWorkflowFollowUp,
   buildBackgroundWorkflowLaunchResult,
+  buildProjectedWorkflowCompletionBatch,
+  buildProjectedWorkflowResultMessage,
   buildWorkflowAgentPrompt,
   buildWorkflowResultMessage,
+  buildWorkflowStatusSummary,
   WORKFLOW_LIFECYCLE_PROMPT_SNIPPET,
   WORKFLOW_PARAMETER_DESCRIPTIONS,
   WORKFLOW_PROMPT_GUIDELINES,
@@ -139,39 +170,331 @@ import {
   WORKFLOW_TOOL_DESCRIPTION,
 } from "./prompt.ts";
 import {
-  WorkflowNavigationEditor,
-  WorkflowStripState,
-  WorkflowStripWidget,
-  type WorkflowStripEntry,
-} from "./navigation.ts";
+  createWorkflowResultDelivery,
+  type WorkflowCompletionEnvelope,
+} from "./result-delivery.ts";
+import {
+  beginProcessReplayWorkspaceLease,
+  createReplayIdentity,
+  isReplaySafeAgentCall,
+} from "./replay-safety.ts";
 import {
   createWorkflowResources,
   runAgent,
   type ThinkingLevel,
+  type WorkflowAgentSessionFactory,
   type WorkflowModel,
 } from "./runner.ts";
-import {
-  beginProcessReplayWorkspaceLease,
-  createReplayIdentity,
-  isReplaySafeAgentCall,
-} from "./replay-safety.ts";
 import { runWorkflowSandbox } from "./sandbox.ts";
-import {
-  acceptanceInstruction,
-  acceptanceSchema,
-  applyAcceptance,
-  evaluateAcceptance,
-  parseAcceptanceContract,
-} from "./acceptance.ts";
+import { safeStringify, writeFileAtomic } from "./serialization.ts";
 import {
   finalizeWorktreeHandoff,
   prepareWorktreeHandoff,
 } from "./worktree-handoff.ts";
-import { safeStringify, writeFileAtomic } from "./serialization.ts";
 
 const PREVIEW_LENGTH = 200;
 const EMIT_INTERVAL_MS = 120;
 
+/** Header of a workflow card: identity and phase on the left, metrics right. */
+function runHeader(
+  details: WorkflowDetails,
+  theme: Parameters<typeof statusGlyph>[1],
+  now: number,
+) {
+  const { done, failed, uncertain } = countStates(details);
+  const settled = done + failed;
+  const elapsed = formatElapsed(details.startedAt, details.finishedAt);
+  // A just-launched run has no agents and a 0s clock; the metrics join in
+  // once there is something real to report.
+  const counts =
+    details.agents.length > 0
+      ? `${settled}/${details.agents.length} agents${uncertain ? ` · ${uncertain} uncertain` : ""}`
+      : undefined;
+  const metrics = [counts, counts || elapsed !== "0s" ? elapsed : undefined]
+    .filter(Boolean)
+    .join(" · ");
+  let left =
+    `${statusGlyph(details.status, theme, now)} ${theme.fg("toolTitle", theme.bold("workflow "))}` +
+    theme.fg(
+      "accent",
+      sanitizeWorkflowDisplayLine(details.name ?? details.runId),
+    );
+  if (details.status === "running" && details.currentPhase) {
+    left += theme.fg(
+      "muted",
+      ` · ${sanitizeWorkflowDisplayLine(details.currentPhase)}`,
+    );
+  }
+  // The glyph already carries the run state, so the status word only stays
+  // for terminal states.
+  let right = theme.fg("dim", metrics);
+  if (details.status !== "running") {
+    right +=
+      theme.fg("dim", `${metrics ? " · " : ""}`) +
+      theme.fg(statusColor(details.status), statusWord(details.status));
+  }
+  if (failed) right += theme.fg("error", ` · ${failed} failed`);
+  return { left, right };
+}
+
+/**
+ * Collapsed workflow card, rebuilt per repaint. Metrics right-align like the
+ * below-editor strip, and each agent row carries one number only: context
+ * occupancy says a running agent is alive, elapsed says what a settled one
+ * cost. A swarm shows the first few agents and summarizes the rest instead
+ * of flooding the chat.
+ */
+function buildCollapsedRows(
+  details: WorkflowDetails,
+  theme: Parameters<typeof statusGlyph>[1],
+  width: number,
+  now: number,
+  totals: string,
+) {
+  const header = runHeader(details, theme, now);
+  const rows = [fitNavigationSides(header.left, header.right, width)];
+  const collapsedAgents = details.agents.slice(0, 8);
+  for (const agent of collapsedAgents) {
+    const percent = contextPercent({
+      tokens: agent.usage.contextTokens,
+      contextWindow: agent.contextWindow,
+    });
+    const stat =
+      agent.state === "running"
+        ? percent === undefined
+          ? undefined
+          : `${percent}%`
+        : formatElapsed(agent.startedAt, agent.finishedAt);
+    const left = `  ${stateGlyph(agent.state, theme, now)} ${theme.fg(
+      "accent",
+      sanitizeWorkflowDisplayLine(agent.label),
+    )}`;
+    rows.push(
+      stat
+        ? fitNavigationSides(left, theme.fg("dim", stat), width)
+        : truncateToWidth(left, width, "…"),
+    );
+  }
+  const hiddenAgents = details.agents.length - collapsedAgents.length;
+  if (hiddenAgents > 0) {
+    rows.push(`  ${theme.fg("dim", `… ${hiddenAgents} more`)}`);
+  }
+  // Only the tail collapsed: the newest lines are the ones that say where
+  // the run is now.
+  for (const entry of (details.logs ?? []).slice(-3)) {
+    rows.push(
+      truncateToWidth(
+        `  ${theme.fg("muted", "›")} ${theme.fg(
+          "dim",
+          sanitizeWorkflowDisplayLine(entry.text),
+        )}`,
+        width,
+        "…",
+      ),
+    );
+  }
+  if (totals) rows.push(`  ${theme.fg("dim", `Total: ${totals}`)}`);
+  if (details.error) {
+    rows.push(
+      truncateToWidth(
+        `  ${theme.fg(
+          "error",
+          `Error: ${sanitizeWorkflowDisplayLine(details.error)}`,
+        )}`,
+        width,
+        "…",
+      ),
+    );
+  }
+  // Expanding only earns its hint when there is more to see.
+  if (
+    details.agents.length > 0 ||
+    (details.logs ?? []).length > 0 ||
+    details.description ||
+    details.result !== undefined ||
+    details.error
+  ) {
+    rows.push(
+      theme.fg("muted", `(${keyHint("app.tools.expand", "to expand")})`),
+    );
+  }
+  return rows;
+}
+
+function buildExpandedWorkflow(
+  details: WorkflowDetails,
+  theme: Parameters<typeof statusGlyph>[1],
+  now: number,
+  totals: string,
+) {
+  const header = runHeader(details, theme, now);
+  const container = new Container();
+  container.addChild(
+    new Text(
+      header.right ? `${header.left} ${header.right}` : header.left,
+      0,
+      0,
+    ),
+  );
+  if (details.description) {
+    container.addChild(
+      new Text(
+        theme.fg("dim", sanitizeWorkflowDisplayLine(details.description)),
+        0,
+        0,
+      ),
+    );
+  }
+
+  for (const group of phaseGroups(details)) {
+    container.addChild(new Spacer(1));
+    container.addChild(
+      new Text(
+        theme.fg(
+          "muted",
+          `─── ${sanitizeWorkflowDisplayLine(group.title)} ───`,
+        ),
+        0,
+        0,
+      ),
+    );
+    for (const agent of group.agents) {
+      const usage = formatUsage(agent.usage, agent.model);
+      const context = agentContext(agent);
+      let line = `${stateGlyph(agent.state, theme, now)} ${theme.fg(
+        "accent",
+        sanitizeWorkflowDisplayLine(agent.label),
+      )} ${theme.fg(
+        "dim",
+        [context, formatElapsed(agent.startedAt, agent.finishedAt)]
+          .filter(Boolean)
+          .join(" · "),
+      )}`;
+      if (usage)
+        line += ` ${theme.fg("dim", sanitizeWorkflowDisplayLine(usage))}`;
+      container.addChild(new Text(line, 0, 0));
+      if (agent.error) {
+        container.addChild(
+          new Text(
+            `  ${theme.fg("error", sanitizeWorkflowDisplayLine(agent.error))}`,
+            0,
+            0,
+          ),
+        );
+      } else if (agent.preview) {
+        const preview = sanitizeWorkflowDisplayText(
+          agent.preview,
+          PREVIEW_LENGTH,
+        )
+          .split("\n")
+          .slice(0, 2)
+          .join(" ");
+        container.addChild(new Text(`  ${theme.fg("dim", preview)}`, 0, 0));
+      }
+    }
+  }
+
+  if (details.logs && details.logs.length > 0) {
+    container.addChild(new Spacer(1));
+    container.addChild(new Text(theme.fg("muted", "─── log ───"), 0, 0));
+    if (details.logsDropped) {
+      container.addChild(
+        new Text(
+          theme.fg("dim", `(${details.logsDropped} earlier line(s) dropped)`),
+          0,
+          0,
+        ),
+      );
+    }
+    for (const entry of details.logs) {
+      container.addChild(
+        new Text(
+          `${theme.fg("muted", "›")} ${theme.fg(
+            "dim",
+            sanitizeWorkflowDisplayLine(entry.text),
+          )}`,
+          0,
+          0,
+        ),
+      );
+    }
+  }
+
+  if (details.error) {
+    container.addChild(new Spacer(1));
+    container.addChild(
+      new Text(
+        theme.fg(
+          "error",
+          `Error: ${sanitizeWorkflowDisplayLine(details.error)}`,
+        ),
+        0,
+        0,
+      ),
+    );
+  }
+
+  if (details.result !== undefined) {
+    container.addChild(new Spacer(1));
+    container.addChild(new Text(theme.fg("muted", "─── result ───"), 0, 0));
+    container.addChild(
+      new Markdown(
+        `\`\`\`json\n${resultJson(details.result)}\n\`\`\``,
+        0,
+        0,
+        getMarkdownTheme(),
+      ),
+    );
+  }
+
+  if (totals) {
+    container.addChild(new Spacer(1));
+    container.addChild(new Text(theme.fg("dim", `Total: ${totals}`), 0, 0));
+  }
+  return container;
+}
+
+interface WorkflowRenderState {
+  spinnerTimer?: ReturnType<typeof setInterval>;
+}
+
+function syncWorkflowSpinner(
+  state: WorkflowRenderState,
+  isRunning: () => boolean,
+  invalidate: () => void,
+) {
+  if (!isRunning()) {
+    if (state.spinnerTimer) clearInterval(state.spinnerTimer);
+    state.spinnerTimer = undefined;
+    return;
+  }
+  if (state.spinnerTimer) return;
+  const spinnerTimer = setInterval(() => {
+    if (state.spinnerTimer !== spinnerTimer) return;
+    if (!isRunning()) {
+      clearInterval(spinnerTimer);
+      state.spinnerTimer = undefined;
+    }
+    invalidate();
+  }, SPINNER_INTERVAL_MS);
+  state.spinnerTimer = spinnerTimer;
+  spinnerTimer.unref?.();
+}
+
+/**
+ * Test-only injection seam for execute-level tests: production never sets it.
+ * The underscore-prefixed setter name makes any accidental production use
+ * self-evidently wrong.
+ */
+let testAgentSessionFactory: WorkflowAgentSessionFactory | undefined;
+
+/** Test-only: override how workflow children create their agent sessions. */
+export function __setWorkflowTestAgentSessionFactory(
+  factory: WorkflowAgentSessionFactory | undefined,
+) {
+  testAgentSessionFactory = factory;
+}
+
 const THINKING_LEVELS = [
   "off",
   "minimal",
@@ -223,6 +546,11 @@ const WorkflowParams = Type.Object({
       description: WORKFLOW_PARAMETER_DESCRIPTIONS.background,
     }),
   ),
+  wait: Type.Optional(
+    Type.Boolean({
+      description: WORKFLOW_PARAMETER_DESCRIPTIONS.wait,
+    }),
+  ),
   resume_from_run_id: Type.Optional(
     Type.String({
       description: WORKFLOW_PARAMETER_DESCRIPTIONS.resumeFromRunId,
@@ -267,12 +595,12 @@ function errorText(error: unknown): string {
 }
 
 function summaryLine(details: WorkflowDetails): string {
-  const { done, failed } = countStates(details);
+  const { done, failed, uncertain } = countStates(details);
   const settled = done + failed;
   // The newest narrator line beats the phase title when there is one: the
   // script wrote it precisely because it says more than the phase does.
   const latest = details.logs?.[details.logs.length - 1]?.text;
-  return `workflow ${details.name ?? details.runId}: ${settled}/${details.agents.length} agents${
+  return `workflow ${details.name ?? details.runId}: ${settled}/${details.agents.length} agents${uncertain ? ` · ${uncertain} uncertain` : ""}${
     latest
       ? ` · ${latest}`
       : details.currentPhase
@@ -348,15 +676,8 @@ function listRuns(
   referencedRunIds: ReadonlySet<string>,
   startedSince = 0,
 ): RunSummary[] {
-  const base = path.join(getAgentDir(), "workflows");
-  let names: string[] = [];
-  try {
-    names = fs.readdirSync(base).filter(isWorkflowRunId);
-  } catch {
-    // No runs yet.
-  }
   const summaries: RunSummary[] = [];
-  for (const runId of names) {
+  for (const runId of listPersistedRunIds()) {
     const live = activeRuns.get(runId);
     if (live) {
       const { done, failed } = countStates(live);
@@ -371,34 +692,30 @@ function listRuns(
       });
       continue;
     }
-    try {
-      const parsed = JSON.parse(
-        fs.readFileSync(path.join(base, runId, "workflow.json"), "utf8"),
-      ) as Partial<WorkflowDetails>;
-      const startedAt = parsed.startedAt ?? 0;
-      const touchedAt = Math.max(startedAt, parsed.finishedAt ?? 0);
-      if (
-        touchedAt < startedSince ||
-        (parsed.sessionId !== sessionId && !referencedRunIds.has(runId))
-      ) {
-        continue;
-      }
-      const agents = parsed.agents ?? [];
-      summaries.push({
-        runId,
-        name: parsed.name,
-        status:
-          parsed.status === "running"
-            ? "aborted"
-            : (parsed.status ?? "unknown"),
-        done: agents.filter((agent) => agent.state !== "running").length,
-        total: agents.length,
-        startedAt: parsed.startedAt ?? 0,
-        active: false,
-      });
-    } catch {
-      // Ignore unreadable artifacts because their session cannot be verified.
+    // Same reader as the dashboard and workflow_status: old-format runs are
+    // normalized here too, so every surface reports one status per run.
+    const details = readPersistedWorkflowDetails(runId, {
+      hydrateArtifacts: false,
+    });
+    if (!details) continue;
+    const touchedAt = Math.max(details.startedAt, details.finishedAt ?? 0);
+    if (
+      touchedAt < startedSince ||
+      (details.sessionId !== sessionId && !referencedRunIds.has(runId))
+    ) {
+      continue;
     }
+    recoverStaleWorkflowDetails(details);
+    const { done, failed } = countStates(details);
+    summaries.push({
+      runId,
+      name: details.name,
+      status: details.status,
+      done: done + failed,
+      total: details.agents.length,
+      startedAt: details.startedAt,
+      active: false,
+    });
   }
   return summaries.sort((a, b) => b.startedAt - a.startedAt);
 }
@@ -410,14 +727,15 @@ function runDetailText(
   const runDir = path.join(getAgentDir(), "workflows", run.runId);
   const live = activeRuns.get(run.runId);
   if (live) return buildWorkflowResultMessage(live, runDir);
-  try {
-    const parsed = JSON.parse(
-      fs.readFileSync(path.join(runDir, "workflow.json"), "utf8"),
-    ) as WorkflowDetails;
-    return buildWorkflowResultMessage(parsed, runDir);
-  } catch {
-    return `Run ${run.runId} — ${run.status}`;
-  }
+  const details = readPersistedWorkflowDetails(run.runId, {
+    hydrateArtifacts: true,
+  });
+  if (details)
+    return buildWorkflowResultMessage(
+      recoverStaleWorkflowDetails(details),
+      runDir,
+    );
+  return `Run ${run.runId} — ${run.status}`;
 }
 
 export default function workflows(pi: ExtensionAPI) {
@@ -428,13 +746,9 @@ export default function workflows(pi: ExtensionAPI) {
       [...activeRuns].map(([runId, run]) => [runId, run.details] as const),
     );
   const settledRuns = new Map<string, WorkflowDetails>();
-  const hideLifecycleTools = () =>
-    patchOwnedTools(pi, "workflows", {
-      disable: OPENPI_TOOL_SURFACE.workflows.deferred,
-    });
-  const showLifecycleTools = () =>
+  const registerStableToolFamily = () =>
     patchOwnedTools(pi, "workflows", {
-      enable: OPENPI_TOOL_SURFACE.workflows.deferred,
+      enable: OPENPI_TOOL_SURFACE.workflows.entry,
     });
   const stripState = new WorkflowStripState();
   const widgetKey = "workflow-navigation";
@@ -444,6 +758,52 @@ export default function workflows(pi: ExtensionAPI) {
    * next explicit request acknowledges them.
    */
   let lastContext: ExtensionContext | undefined;
+  const completionEnvelope = (
+    details: WorkflowDetails,
+  ): WorkflowCompletionEnvelope => {
+    const deliveryId = details.delivery?.id;
+    if (!deliveryId) throw new Error("Workflow delivery identity is missing");
+    return {
+      deliveryId,
+      runId: details.runId,
+      details,
+    };
+  };
+  const resultDelivery = createWorkflowResultDelivery({
+    isIdle: () => lastContext?.isIdle() ?? false,
+    persist: (details) =>
+      persistWorkflowJson(
+        path.join(getAgentDir(), "workflows", details.runId),
+        details,
+      ),
+    deliver: async (envelopes, wake) => {
+      const content = buildProjectedWorkflowCompletionBatch(
+        envelopes.map((envelope) => ({
+          deliveryId: envelope.deliveryId,
+          details: envelope.details,
+          runDir: path.join(getAgentDir(), "workflows", envelope.runId),
+        })),
+        lastContext?.getContextUsage?.(),
+      );
+      pi.sendMessage(
+        {
+          customType: "workflow-result",
+          content,
+          display: true,
+          ...(envelopes.length === 1
+            ? { details: compactToolDetails(envelopes[0]!.details) }
+            : {}),
+        },
+        wake
+          ? { deliverAs: "followUp", triggerTurn: true }
+          : { deliverAs: "nextTurn" },
+      );
+      return envelopes.map((envelope) => ({
+        deliveryId: envelope.deliveryId,
+        delivered: true,
+      }));
+    },
+  });
   let completedRuns = 0;
   let failedRuns = 0;
   let widgetVisible = false;
@@ -593,7 +953,7 @@ export default function workflows(pi: ExtensionAPI) {
   };
 
   pi.on("session_start", (_event, ctx) => {
-    hideLifecycleTools();
+    registerStableToolFamily();
     if (ctx.hasUI) lastContext = ctx;
     agentTypes = loadAgentTypes({
       agentDir: getAgentDir(),
@@ -606,6 +966,35 @@ export default function workflows(pi: ExtensionAPI) {
     settledRuns.clear();
     installWorkflowNavigation(ctx);
     updateIndicator();
+
+    const sessionId = ctx.sessionManager.getSessionId();
+    for (const runId of listPersistedRunIds()) {
+      const details = readPersistedWorkflowDetails(runId, {
+        hydrateArtifacts: true,
+      });
+      if (!details || details.sessionId !== sessionId) {
+        continue;
+      }
+      const wasRunning = details.status === "running";
+      if (wasRunning) {
+        recoverStaleWorkflowDetails(details);
+        persistWorkflowJson(
+          path.join(getAgentDir(), "workflows", details.runId),
+          details,
+        );
+      }
+      // Pre-V2 terminal runs have no delivery receipt. They may already have
+      // been shown, so replaying them on upgrade would be a surprising
+      // duplicate. Only migrate owner-lost runs, whose uncertainty matters.
+      if (details.delivery) {
+        resultDelivery.restore(completionEnvelope(details));
+      }
+    }
+    void resultDelivery.flushIfIdle();
+  });
+
+  pi.on("agent_settled", () => {
+    void resultDelivery.parentSettled();
   });
 
   pi.on("input", (event) => {
@@ -631,6 +1020,7 @@ export default function workflows(pi: ExtensionAPI) {
     widgetVisible = false;
     requestWidgetRender = undefined;
     stripState.focused = false;
+    resultDelivery.clear();
   });
 
   pi.registerCommand("workflows", {
@@ -736,7 +1126,13 @@ export default function workflows(pi: ExtensionAPI) {
       const meta = prepared.meta;
       const runId = `wf_${randomBytes(6).toString("hex")}`;
       const runDir = path.join(getAgentDir(), "workflows", runId);
-      const background = (params.background ?? false) && ctx.hasUI;
+      const canDeliverLater = ctx.hasUI && ctx.mode === "tui";
+      const launchPolicy = resolveWorkflowLaunchPolicy(
+        { wait: params.wait, background: params.background },
+        canDeliverLater,
+      );
+      const background = launchPolicy.detached;
+      const now = Date.now();
 
       const details: WorkflowDetails = {
         runId,
@@ -745,9 +1141,15 @@ export default function workflows(pi: ExtensionAPI) {
         description: meta.description,
         background,
         status: "running",
-        startedAt: Date.now(),
+        startedAt: now,
         phases: [...meta.phases],
         agents: [],
+        delivery: {
+          id: `workflow:${runId}:terminal`,
+          state: launchPolicy.wait ? "held-for-inline" : "none",
+          attempts: 0,
+          updatedAt: now,
+        },
       };
 
       // Resume: replay cached results for calls whose content is unchanged.
@@ -776,13 +1178,13 @@ export default function workflows(pi: ExtensionAPI) {
         journal: () => journalEntries,
       });
 
-      // Background runs survive Esc on the parent turn, but all runs are
-      // aborted and settled during session shutdown.
+      // A caller wait never owns the run. All runs survive an interrupted
+      // launch turn and are aborted only by workflow_stop/session shutdown.
       const workflowConfig = loadSetupConfig().workflows;
       const projectTrusted = ctx.isProjectTrusted();
       const runAgentTypes = agentTypes;
       const controller = new RunController(
-        background ? undefined : signal,
+        undefined,
         workflowConfig.concurrency,
         workflowConfig.maxAgentCalls,
       );
@@ -870,6 +1272,13 @@ export default function workflows(pi: ExtensionAPI) {
         }
         details.status = status;
         details.finishedAt = Date.now();
+        if (details.delivery && background) {
+          details.delivery = {
+            ...details.delivery,
+            state: "pending",
+            updatedAt: details.finishedAt,
+          };
+        }
         refreshWorkflowGraph(details);
         if (error) details.error = sanitizeWorkflowDisplayLine(error);
         return true;
@@ -905,7 +1314,11 @@ export default function workflows(pi: ExtensionAPI) {
 
       // One reader per run: it carries a high-water mark, because per-agent
       // usage is recomputed from a message list that compaction shrinks.
-      const readUsage = createUsageReader(details.agents);
+      const readBaseUsage = createUsageReader(details.agents);
+      const readUsage = () => ({
+        ...readBaseUsage(),
+        limits: controller.capacity(),
+      });
 
       let agentCounter = 0;
       const agentFn = async (
@@ -1239,11 +1652,18 @@ export default function workflows(pi: ExtensionAPI) {
               cached.structured,
             );
           }
+          record.resultArtifact = persistWorkflowAgentResult(runDir, index, {
+            output: cached.output,
+            ...(cached.structured !== undefined
+              ? { structured: cached.structured }
+              : {}),
+          });
           const ref = handoffs.register({
             callId,
             settled: true,
             ok: true,
             output: cached.output,
+            resultArtifact: record.resultArtifact,
             ...(cached.structured !== undefined
               ? { structured: cached.structured }
               : {}),
@@ -1365,6 +1785,9 @@ export default function workflows(pi: ExtensionAPI) {
                   ...(sessionManager ? { sessionManager } : {}),
                   modelRegistry: ctx.modelRegistry,
                   ...(agentType?.tools ? { tools: agentType.tools } : {}),
+                  ...(testAgentSessionFactory
+                    ? { sessionFactory: testAgentSessionFactory }
+                    : {}),
                   ...(replayIdentity
                     ? {
                         replayFilesystemBoundary: {
@@ -1441,11 +1864,26 @@ export default function workflows(pi: ExtensionAPI) {
                 record.error = judged.error
                   ? sanitizeWorkflowDisplayLine(judged.error)
                   : undefined;
+              if (outcomeOk) {
+                record.resultArtifact = persistWorkflowAgentResult(
+                  runDir,
+                  index,
+                  {
+                    output: outcome.output,
+                    ...(outcome.structured !== undefined
+                      ? { structured: outcome.structured }
+                      : {}),
+                  },
+                );
+              }
               const ref = handoffs.register({
                 callId,
                 settled: true,
                 ok: outcomeOk,
                 output: outcome.output,
+                ...(record.resultArtifact
+                  ? { resultArtifact: record.resultArtifact }
+                  : {}),
                 ...(outcome.structured !== undefined
                   ? { structured: outcome.structured }
                   : {}),
@@ -1624,48 +2062,29 @@ export default function workflows(pi: ExtensionAPI) {
       if (ctx.hasUI) lastContext = ctx;
       updateIndicator();
 
+      const recordTerminalRun = () => {
+        activeRuns.delete(runId);
+        recordSettledRun(details);
+        updateIndicator();
+      };
+
+      const settleForLaterDelivery = async (inlineReleased: boolean) => {
+        try {
+          await completion;
+        } catch (error) {
+          details.status = "failed";
+          details.finishedAt = Date.now();
+          details.error = details.error ?? errorText(error);
+        } finally {
+          recordTerminalRun();
+          const envelope = completionEnvelope(details);
+          if (inlineReleased) resultDelivery.releaseInline(envelope);
+          else resultDelivery.defer(envelope);
+        }
+      };
+
       if (background) {
-        void completion
-          .catch((error) => {
-            details.status = "failed";
-            details.finishedAt = Date.now();
-            details.error = details.error ?? errorText(error);
-          })
-          .finally(() => {
-            activeRuns.delete(runId);
-            recordSettledRun(details);
-            updateIndicator();
-            try {
-              // Deliver like the subagent/terminal families: a custom-typed
-              // session message with a dedicated renderer, not a plain
-              // user-provenance turn.
-              //
-              // Wake the model only if it is idle and therefore plausibly
-              // waiting on this run. If it is busy with something else, the
-              // result still enters context with the user's next message
-              // (nextTurn) instead of forcing a turn it can only acknowledge.
-              const wake = ctx.isIdle();
-              pi.sendMessage(
-                {
-                  customType: "workflow-result",
-                  content: buildBackgroundWorkflowFollowUp({
-                    runId,
-                    name: details.name,
-                    status: details.status,
-                    result: buildWorkflowResultMessage(details, runDir),
-                  }),
-                  display: true,
-                  details: compactToolDetails(details),
-                },
-                wake
-                  ? { deliverAs: "followUp", triggerTurn: true }
-                  : { deliverAs: "nextTurn" },
-              );
-            } catch {
-              // Session may be shutting down.
-            }
-          });
-        showLifecycleTools();
+        void settleForLaterDelivery(false);
         return {
           content: [
             {
@@ -1681,13 +2100,15 @@ export default function workflows(pi: ExtensionAPI) {
         };
       }
 
-      try {
-        await completion;
-      } finally {
-        activeRuns.delete(runId);
-        recordSettledRun(details);
-        updateIndicator();
+      const waitOutcome = await waitForWorkflowCompletion(completion, signal);
+      if (waitOutcome === "aborted") {
+        void settleForLaterDelivery(true);
+        throw new Error(
+          `Workflow wait interrupted; run ${runId} continues in the background.`,
+        );
       }
+      recordTerminalRun();
+      resultDelivery.consumeInline(details);
       if (details.status !== "completed") {
         // Pi marks tool failures only when execute throws; returning isError is
         // ignored by the extension API.
@@ -1697,7 +2118,11 @@ export default function workflows(pi: ExtensionAPI) {
         content: [
           {
             type: "text",
-            text: buildWorkflowResultMessage(details, runDir),
+            text: buildProjectedWorkflowResultMessage(
+              details,
+              runDir,
+              ctx.getContextUsage?.(),
+            ),
           },
         ],
         details: compactToolDetails(details),
@@ -1716,14 +2141,14 @@ export default function workflows(pi: ExtensionAPI) {
       const description = (meta as WorkflowMeta).description;
       if (description) text += `\n  ${theme.fg("dim", description)}`;
       for (const phase of meta.phases.slice(0, 8)) {
-        text += `\n  ${theme.fg("dim", SQUARE)} ${theme.fg("accent", phase.title)}${
+        text += `\n  ${theme.fg("dim", "○")} ${theme.fg("accent", phase.title)}${
           phase.detail ? theme.fg("dim", ` — ${phase.detail}`) : ""
         }`;
       }
       return new Text(text, 0, 0);
     },
 
-    renderResult(result, { expanded }, theme) {
+    renderResult(result, { expanded, isPartial }, theme, context) {
       const details = result.details as WorkflowDetails | undefined;
       if (!details) {
         const first = result.content[0];
@@ -1733,205 +2158,49 @@ export default function workflows(pi: ExtensionAPI) {
           0,
         );
       }
+      const currentDetails = () =>
+        activeRuns.get(details.runId)?.details ??
+        settledRuns.get(details.runId) ??
+        details;
+      syncWorkflowSpinner(
+        context.state as WorkflowRenderState,
+        () =>
+          currentDetails().status === "running" &&
+          (isPartial || activeRuns.has(details.runId)),
+        context.invalidate,
+      );
 
-      const { done, failed } = countStates(details);
-      const settled = done + failed;
-      const elapsed = formatElapsed(details.startedAt, details.finishedAt);
-      let header =
-        `${theme.fg(statusColor(details.status), SQUARE)} ${theme.fg("toolTitle", theme.bold("workflow "))}` +
-        `${theme.fg(
-          "accent",
-          sanitizeWorkflowDisplayLine(details.name ?? details.runId),
-        )} ` +
-        theme.fg(
-          "dim",
-          `${settled}/${details.agents.length} agents · ${elapsed} · `,
-        ) +
-        theme.fg(statusColor(details.status), statusWord(details.status));
-      if (failed) header += theme.fg("error", ` · ${failed} failed`);
-      if (details.background) header += theme.fg("dim", " (background)");
-      if (details.status === "running" && details.currentPhase) {
-        header += theme.fg(
-          "muted",
-          ` · ${sanitizeWorkflowDisplayLine(details.currentPhase)}`,
-        );
-      }
-      const totals = formatUsage(aggregateUsage(details.agents));
-
-      if (!expanded) {
-        let text = header;
-        for (const agent of details.agents) {
-          const context = agentContext(agent);
-          text += `\n  ${stateSquare(agent.state, theme)} ${theme.fg(
-            "accent",
-            sanitizeWorkflowDisplayLine(agent.label),
-          )}${
-            agent.phase
-              ? theme.fg(
-                  "dim",
-                  ` (${sanitizeWorkflowDisplayLine(agent.phase)})`,
-                )
-              : ""
-          }${theme.fg(
-            "dim",
-            `${context ? ` · ${context}` : ""} · ${formatElapsed(agent.startedAt, agent.finishedAt)}`,
-          )}`;
-        }
-        // Only the tail collapsed: the newest lines are the ones that say
-        // where the run is now.
-        for (const entry of (details.logs ?? []).slice(-3)) {
-          text += `\n  ${theme.fg("muted", "›")} ${theme.fg(
-            "dim",
-            sanitizeWorkflowDisplayLine(entry.text),
-          )}`;
-        }
-        if (totals) text += `\n  ${theme.fg("dim", `Total: ${totals}`)}`;
-        if (details.error)
-          text += `\n  ${theme.fg(
-            "error",
-            `Error: ${sanitizeWorkflowDisplayLine(details.error)}`,
-          )}`;
-        text += `\n${theme.fg("muted", `(${keyHint("app.tools.expand", "to expand")})`)}`;
-        return new Text(text, 0, 0);
-      }
-
-      const container = new Container();
-      container.addChild(new Text(header, 0, 0));
-      if (details.description) {
-        container.addChild(
-          new Text(
-            theme.fg("dim", sanitizeWorkflowDisplayLine(details.description)),
-            0,
-            0,
-          ),
-        );
-      }
-
-      for (const group of phaseGroups(details)) {
-        container.addChild(new Spacer(1));
-        container.addChild(
-          new Text(
-            theme.fg(
-              "muted",
-              `─── ${sanitizeWorkflowDisplayLine(group.title)} ───`,
-            ),
-            0,
-            0,
-          ),
-        );
-        for (const agent of group.agents) {
-          const usage = formatUsage(agent.usage, agent.model);
-          const context = agentContext(agent);
-          let line = `${stateSquare(agent.state, theme)} ${theme.fg(
-            "accent",
-            sanitizeWorkflowDisplayLine(agent.label),
-          )} ${theme.fg(
-            "dim",
-            [context, formatElapsed(agent.startedAt, agent.finishedAt)]
-              .filter(Boolean)
-              .join(" · "),
-          )}`;
-          if (usage)
-            line += ` ${theme.fg("dim", sanitizeWorkflowDisplayLine(usage))}`;
-          container.addChild(new Text(line, 0, 0));
-          if (agent.error) {
-            container.addChild(
-              new Text(
-                `  ${theme.fg("error", sanitizeWorkflowDisplayLine(agent.error))}`,
-                0,
-                0,
-              ),
+      return {
+        render(width: number) {
+          const current = currentDetails();
+          const totals = formatUsage(aggregateUsage(current.agents));
+          if (!expanded) {
+            return buildCollapsedRows(
+              current,
+              theme,
+              width,
+              Date.now(),
+              totals,
             );
-          } else if (agent.preview) {
-            const preview = sanitizeWorkflowDisplayText(
-              agent.preview,
-              PREVIEW_LENGTH,
-            )
-              .split("\n")
-              .slice(0, 2)
-              .join(" ");
-            container.addChild(new Text(`  ${theme.fg("dim", preview)}`, 0, 0));
           }
-        }
-      }
-
-      if (details.logs && details.logs.length > 0) {
-        container.addChild(new Spacer(1));
-        container.addChild(new Text(theme.fg("muted", "─── log ───"), 0, 0));
-        if (details.logsDropped) {
-          container.addChild(
-            new Text(
-              theme.fg(
-                "dim",
-                `(${details.logsDropped} earlier line(s) dropped)`,
-              ),
-              0,
-              0,
-            ),
-          );
-        }
-        for (const entry of details.logs) {
-          container.addChild(
-            new Text(
-              `${theme.fg("muted", "›")} ${theme.fg(
-                "dim",
-                sanitizeWorkflowDisplayLine(entry.text),
-              )}`,
-              0,
-              0,
-            ),
-          );
-        }
-      }
-
-      if (details.error) {
-        container.addChild(new Spacer(1));
-        container.addChild(
-          new Text(
-            theme.fg(
-              "error",
-              `Error: ${sanitizeWorkflowDisplayLine(details.error)}`,
-            ),
-            0,
-            0,
-          ),
-        );
-      }
-
-      if (details.result !== undefined) {
-        container.addChild(new Spacer(1));
-        container.addChild(new Text(theme.fg("muted", "─── result ───"), 0, 0));
-        container.addChild(
-          new Markdown(
-            `\`\`\`json\n${resultJson(details.result)}\n\`\`\``,
-            0,
-            0,
-            getMarkdownTheme(),
-          ),
-        );
-      }
-
-      if (totals) {
-        container.addChild(new Spacer(1));
-        container.addChild(new Text(theme.fg("dim", `Total: ${totals}`), 0, 0));
-      }
-      return container;
+          return buildExpandedWorkflow(
+            current,
+            theme,
+            Date.now(),
+            totals,
+          ).render(width);
+        },
+        invalidate() {},
+      };
     },
   });
 
   /** Resolve one run from live, settled, or persisted state. */
   const resolveRunDetails = (target: string) => {
-    const base = path.join(getAgentDir(), "workflows");
-    let persistedIds: string[] = [];
-    try {
-      persistedIds = fs.readdirSync(base).filter(isWorkflowRunId);
-    } catch {
-      // In-memory runs remain inspectable without the artifact directory.
-    }
     const resolution = resolveWorkflowRunTarget(target, [
       ...activeRuns.keys(),
       ...settledRuns.keys(),
-      ...persistedIds,
+      ...listPersistedRunIds(),
     ]);
     if (!resolution.ok) return resolution;
 
@@ -1940,31 +2209,22 @@ export default function workflows(pi: ExtensionAPI) {
     const settled = settledRuns.get(resolution.runId);
     if (settled) return { ok: true, details: settled } as const;
 
-    try {
-      const parsed: unknown = JSON.parse(
-        fs.readFileSync(
-          path.join(base, resolution.runId, "workflow.json"),
-          "utf8",
-        ),
-      );
-      const details = normalizePersistedWorkflowDetails(
-        resolution.runId,
-        parsed,
-      );
-      if (!details) throw new Error("invalid workflow details");
-      // A run absent from activeRuns cannot still be running this session; a
-      // persisted "running" is a run that was hard-killed or missed the
-      // shutdown settle deadline.
-      return {
-        ok: true,
-        details: recoverStaleWorkflowDetails(details),
-      } as const;
-    } catch {
+    const details = readPersistedWorkflowDetails(resolution.runId, {
+      hydrateArtifacts: true,
+    });
+    if (!details) {
       return {
         ok: false,
         error: `Workflow run ${resolution.runId} could not be read.`,
       } as const;
     }
+    // A run absent from activeRuns cannot still be running this session; a
+    // persisted "running" is a run that was hard-killed or missed the
+    // shutdown settle deadline.
+    return {
+      ok: true,
+      details: recoverStaleWorkflowDetails(details),
+    } as const;
   };
 
   pi.registerTool({
@@ -1978,23 +2238,29 @@ export default function workflows(pi: ExtensionAPI) {
       }),
     }),
     execute(_toolCallId, params) {
-      const running = [...activeRuns].filter(
-        ([, run]) => run.details.status === "running",
-      );
-      const resolution = resolveWorkflowRunTarget(
-        params.runId,
-        running.map(([runId]) => runId),
-      );
+      const resolution = resolveRunDetails(params.runId);
       if (!resolution.ok) throw new Error(resolution.error);
-      stopRun(resolution.runId);
+      const details = resolution.details;
+      if (details.status !== "running") {
+        return Promise.resolve({
+          content: [
+            {
+              type: "text",
+              text: `Workflow ${details.runId} is already ${details.status}.`,
+            },
+          ],
+          details: { runId: details.runId, status: details.status },
+        });
+      }
+      stopRun(details.runId);
       return Promise.resolve({
         content: [
           {
             type: "text",
-            text: `Stopping workflow ${resolution.runId}.`,
+            text: `Stopping workflow ${details.runId}.`,
           },
         ],
-        details: { runId: resolution.runId, status: "aborting" },
+        details: { runId: details.runId, status: "aborting" },
       });
     },
   });
@@ -2014,13 +2280,14 @@ export default function workflows(pi: ExtensionAPI) {
       // Details are a uniform run-summary array (one entry for a single-id peek)
       // so the tool has a single result shape; the text carries the detail.
       const summarize = (d: WorkflowDetails) => {
-        const { done, failed } = countStates(d);
+        const { done, failed, uncertain } = countStates(d);
         return {
           runId: d.runId,
           name: d.name,
           status: d.status,
           done,
           failed,
+          uncertain,
           total: d.agents.length,
         };
       };
@@ -2031,7 +2298,7 @@ export default function workflows(pi: ExtensionAPI) {
         const runDir = path.join(getAgentDir(), "workflows", details.runId);
         return Promise.resolve({
           content: [
-            { type: "text", text: buildWorkflowResultMessage(details, runDir) },
+            { type: "text", text: buildWorkflowStatusSummary(details, runDir) },
           ],
           details: { runs: [summarize(details)] },
         });
@@ -2049,8 +2316,8 @@ export default function workflows(pi: ExtensionAPI) {
         });
       }
       const lines = runs.map((d) => {
-        const { done, failed } = countStates(d);
-        return `${d.runId}${d.name ? ` "${d.name}"` : ""} — ${statusWord(d.status)} · ${done + failed}/${d.agents.length} agents${failed ? `, ${failed} failed` : ""}`;
+        const { done, failed, uncertain } = countStates(d);
+        return `${d.runId}${d.name ? ` "${d.name}"` : ""} — ${statusWord(d.status)} · ${done + failed}/${d.agents.length} agents${failed ? `, ${failed} failed` : ""}${uncertain ? `, ${uncertain} uncertain` : ""}`;
       });
       return Promise.resolve({
         content: [{ type: "text", text: lines.join("\n") }],
@@ -2071,17 +2338,10 @@ export default function workflows(pi: ExtensionAPI) {
               .join("") ?? "");
       const safeBody = sanitizeWorkflowDisplayText(body);
       if (!details) return new Text(safeBody, 0, 0);
-      const { done, failed } = countStates(details);
-      const settled = done + failed;
-      let header =
-        `${theme.fg(statusColor(details.status), SQUARE)} ${theme.fg("toolTitle", theme.bold("workflow "))}` +
-        `${theme.fg(
-          "accent",
-          sanitizeWorkflowDisplayLine(details.name ?? details.runId),
-        )} ` +
-        theme.fg("dim", `${settled}/${details.agents.length} agents · `) +
-        theme.fg(statusColor(details.status), statusWord(details.status));
-      if (failed) header += theme.fg("error", ` · ${failed} failed`);
+      const headerParts = runHeader(details, theme, Date.now());
+      const header = headerParts.right
+        ? `${headerParts.left} ${headerParts.right}`
+        : headerParts.left;
       if (expanded) return new Text(`${header}\n\n${safeBody}`, 0, 0);
       const preview = safeBody.split("\n").slice(0, 8).join("\n");
       return new Text(