@tt-a1i/openpi 0.3.1 → 0.5.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,43 +33,90 @@ 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 { formatActivityStatus } from "../shared/activity-status.ts";
+import {
+  Container,
+  Markdown,
+  Spacer,
+  Text,
+  truncateToWidth,
+} from "@earendil-works/pi-tui";
+import { type Static, Type } from "typebox";
+import {
+  createStatusWriter,
+  formatActivityStatus,
+} from "../shared/activity-status.ts";
+import { fitNavigationSides } from "../shared/below-editor-navigation.ts";
 import { waitBounded } from "../shared/child-session.ts";
+import { contextPercent } from "../shared/context-utilization.ts";
 import {
   registerEditorLayer,
   removeEditorLayer,
 } from "../shared/editor-layers.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 {
-  loadAgentTypes,
-  resolveAgentModel,
-  roleModelForAgentType,
-  selectSubagentModel,
-} from "../subagents/src/agent-types.ts";
+  notifyWebCapabilities,
+  projectWorkflowCapability,
+  registerWebCapability,
+  type WebCapabilityScope,
+} from "../shared/web-observer-registry.ts";
 import {
   createWorktree,
   reclaimWorktree,
   type Worktree,
   type WorktreeCleanup,
 } from "../shared/worktree.ts";
+import {
+  loadAgentTypes,
+  resolveAgentModel,
+  roleModelForAgentType,
+  selectSubagentModel,
+} from "../subagents/src/agent-types.ts";
+import {
+  acceptanceInstruction,
+  acceptanceSchema,
+  applyAcceptance,
+  parseAcceptanceContract,
+} from "./acceptance.ts";
 import {
   createWorkflowPersistence,
   loadJournal,
+  persistWorkflowAgentResult,
+  persistWorkflowDeliveryState,
   persistWorkflowJson,
+  persistWorkflowTerminalState,
 } from "./artifacts.ts";
+import {
+  buildExpandedWorkflowCompletion,
+  buildWorkflowCompletionDisplay,
+  isWorkflowCompletionDisplay,
+  workflowCompletionAlerts,
+  workflowCompletionResultPreview,
+  workflowCompletionSummary,
+} from "./completion-projection.ts";
+import { RunController } from "./controller.ts";
+import {
+  resolveWorkflowLaunchMode,
+  waitForWorkflowCompletion,
+} from "./coordinator.ts";
+import {
+  listPersistedRunIds,
+  readPersistedWorkflowDetails,
+  recoverStaleWorkflowDetails,
+  sessionWorkflowRunIds,
+  showWorkflowDashboard,
+} from "./dashboard.ts";
 import { createWorkflowHandoffRegistry } from "./handoff.ts";
 import {
   classifyInterruptedInvocation,
@@ -77,57 +124,60 @@ import {
   requestInvocation,
   transitionInvocation,
 } from "./invocation-ledger.ts";
-import {
-  normalizeWorkflowOperatorKey,
-  WorkflowOperatorRegistry,
-} from "./operator.ts";
 import {
   agentCallKey,
+  createJournalAccumulator,
   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,
+  compactWorkflowToolDetails,
   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 {
-  buildBackgroundWorkflowFollowUp,
+  WorkflowNavigationEditor,
+  type WorkflowStripEntry,
+  WorkflowStripState,
+  WorkflowStripWidget,
+  workflowStripEntryKey,
+} from "./navigation.ts";
+import {
+  normalizeWorkflowOperatorKey,
+  WorkflowOperatorRegistry,
+} from "./operator.ts";
+import {
   buildBackgroundWorkflowLaunchResult,
+  buildProjectedWorkflowCompletionBatches,
+  buildProjectedWorkflowResultMessage,
   buildWorkflowAgentPrompt,
   buildWorkflowResultMessage,
+  buildWorkflowStatusSummary,
   WORKFLOW_LIFECYCLE_PROMPT_SNIPPET,
   WORKFLOW_PARAMETER_DESCRIPTIONS,
   WORKFLOW_PROMPT_GUIDELINES,
@@ -139,39 +189,336 @@ import {
   WORKFLOW_TOOL_DESCRIPTION,
 } from "./prompt.ts";
 import {
-  WorkflowNavigationEditor,
-  WorkflowStripState,
-  WorkflowStripWidget,
-  type WorkflowStripEntry,
-} from "./navigation.ts";
+  beginProcessReplayWorkspaceLease,
+  createReplayIdentity,
+  isReplaySafeAgentCall,
+} from "./replay-safety.ts";
+import {
+  createWorkflowResultDelivery,
+  type WorkflowCompletionEnvelope,
+} from "./result-delivery.ts";
+import {
+  createWorkflowSettledRunRetention,
+  projectWorkflowDetails,
+  type WorkflowSettledRunRetentionOptions,
+} from "./retention.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 { 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, now);
+  // 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, now);
+    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, now)]
+          .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",
@@ -209,26 +556,35 @@ interface AgentCallOptions {
   inputs?: unknown;
 }
 
-const WorkflowParams = Type.Object({
-  script: Type.String({
-    description: WORKFLOW_PARAMETER_DESCRIPTIONS.script,
-  }),
-  args: Type.Optional(
-    Type.String({
-      description: WORKFLOW_PARAMETER_DESCRIPTIONS.args,
-    }),
-  ),
-  background: Type.Optional(
-    Type.Boolean({
-      description: WORKFLOW_PARAMETER_DESCRIPTIONS.background,
+const WorkflowParams = Type.Object(
+  {
+    script: Type.String({
+      description: WORKFLOW_PARAMETER_DESCRIPTIONS.script,
     }),
-  ),
-  resume_from_run_id: Type.Optional(
-    Type.String({
-      description: WORKFLOW_PARAMETER_DESCRIPTIONS.resumeFromRunId,
-    }),
-  ),
-});
+    args: Type.Optional(
+      Type.String({
+        description: WORKFLOW_PARAMETER_DESCRIPTIONS.args,
+      }),
+    ),
+    background: Type.Optional(
+      Type.Boolean({
+        deprecated: true,
+        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,
+      }),
+    ),
+  },
+  { additionalProperties: false },
+);
 
 type WorkflowInput = Static<typeof WorkflowParams>;
 
@@ -266,13 +622,32 @@ function errorText(error: unknown): string {
   );
 }
 
+function isWorkflowRenderDetails(value: unknown): value is WorkflowDetails {
+  if (!value || typeof value !== "object") return false;
+  const details = value as Partial<WorkflowDetails>;
+  return (
+    typeof details.runId === "string" &&
+    details.runId.length > 0 &&
+    typeof details.background === "boolean" &&
+    (details.status === "running" ||
+      details.status === "completed" ||
+      details.status === "failed" ||
+      details.status === "aborted" ||
+      details.status === "uncertain") &&
+    typeof details.startedAt === "number" &&
+    Number.isFinite(details.startedAt) &&
+    Array.isArray(details.phases) &&
+    Array.isArray(details.agents)
+  );
+}
+
 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
@@ -285,20 +660,16 @@ function writeRunFile(runDir: string, name: string, content: string) {
   writeFileAtomic(path.join(runDir, name), content);
 }
 
-function compactToolDetails(details: WorkflowDetails): WorkflowDetails {
-  return {
-    ...details,
-    ...(details.result !== undefined
-      ? {
-          result: JSON.parse(
-            safeStringify(details.result, { maxBytes: 64 * 1024 }),
-          ),
-        }
-      : {}),
-    agents: details.agents.map((agent) => ({ ...agent, transcript: [] })),
-  };
+function appendArtifactPersistenceFailure(
+  details: WorkflowDetails,
+  error: unknown,
+) {
+  const persistenceFailure = `Artifact persistence failed: ${errorText(error)}`;
+  if (details.status !== "aborted") details.status = "failed";
+  details.error = details.error
+    ? `${details.error}; ${persistenceFailure}`
+    : persistenceFailure;
 }
-
 export interface ActiveWorkflowRunLifecycle {
   details: WorkflowDetails;
   controller: Pick<RunController, "abort" | "settle">;
@@ -306,6 +677,21 @@ export interface ActiveWorkflowRunLifecycle {
   forceSettle(error: string): void;
 }
 
+interface WorkflowLifecycleTestHooks {
+  readonly persistWorkflow?: typeof persistWorkflowJson;
+  readonly reclaimWorktree?: typeof reclaimWorktree;
+  readonly onRunStarted?: (run: ActiveWorkflowRunLifecycle) => void;
+}
+
+let workflowLifecycleTestHooks: WorkflowLifecycleTestHooks | undefined;
+
+/** Test-only control for deterministic lifecycle race coverage. */
+export function __setWorkflowTestLifecycleHooks(
+  hooks: WorkflowLifecycleTestHooks | undefined,
+) {
+  workflowLifecycleTestHooks = hooks;
+}
+
 /** Abort every live child and bound the whole session-shutdown barrier once. */
 export async function shutdownActiveWorkflowRuns(
   runs: readonly ActiveWorkflowRunLifecycle[],
@@ -348,15 +734,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 +750,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,33 +785,49 @@ 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) {
+export interface WorkflowExtensionOptions {
+  /** Test/configuration seam for the settled session-memory projection. */
+  readonly settledRetention?: WorkflowSettledRunRetentionOptions;
+}
+
+const WORKFLOW_DELIVERY_DETAILS_MAX_BYTES = 128 * 1024;
+
+export default function workflows(
+  pi: ExtensionAPI,
+  options: WorkflowExtensionOptions = {},
+) {
   /** Live background runs, for /workflows and shutdown cleanup. */
   const activeRuns = new Map<string, ActiveWorkflowRunLifecycle>();
+  let unregisterWebCapability: (() => void) | undefined;
+  let webCapabilityScope: WebCapabilityScope | undefined;
   const activeDetails = () =>
     new Map(
       [...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 settledRuns = createWorkflowSettledRunRetention(
+    options.settledRetention,
+  );
+  /** Disk remains canonical; retained projections cover transient read failures. */
+  const dashboardDetails = () => activeDetails();
+  const dashboardRetainedDetails = () =>
+    new Map<string, WorkflowDetails>(settledRuns.entriesArray());
+  const registerStableToolFamily = () =>
     patchOwnedTools(pi, "workflows", {
-      enable: OPENPI_TOOL_SURFACE.workflows.deferred,
+      enable: OPENPI_TOOL_SURFACE.workflows.entry,
     });
   const stripState = new WorkflowStripState();
+  const statusWriter = createStatusWriter("workflows");
   const widgetKey = "workflow-navigation";
 
   /**
@@ -444,9 +835,76 @@ 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");
+    const projection = projectWorkflowDetails(
+      details,
+      WORKFLOW_DELIVERY_DETAILS_MAX_BYTES,
+    );
+    if (!projection) {
+      throw new Error(
+        `Workflow ${details.runId} cannot create a bounded completion projection`,
+      );
+    }
+    return {
+      deliveryId,
+      runId: details.runId,
+      details: projection,
+    };
+  };
+  const resultDelivery = createWorkflowResultDelivery({
+    isIdle: () => lastContext?.isIdle() ?? false,
+    persist: (details) => {
+      if (!details.delivery)
+        throw new Error("Workflow delivery identity is missing");
+      persistWorkflowDeliveryState(
+        path.join(getAgentDir(), "workflows", details.runId),
+        details.delivery,
+      );
+    },
+    deliver: async (envelopes, wake) => {
+      const hydrated = envelopes.map((envelope) => ({
+        ...envelope,
+        details:
+          readPersistedWorkflowDetails(envelope.runId, {
+            hydrateArtifacts: true,
+          }) ?? envelope.details,
+      }));
+      const sourceEntries = hydrated.map((envelope) => ({
+        deliveryId: envelope.deliveryId,
+        details: envelope.details,
+        runDir: path.join(getAgentDir(), "workflows", envelope.runId),
+      }));
+      const batches = buildProjectedWorkflowCompletionBatches(
+        sourceEntries,
+        lastContext?.getContextUsage?.(),
+      );
+      for (const batch of batches) {
+        pi.sendMessage(
+          {
+            customType: "workflow-result",
+            content: batch.content,
+            display: true,
+            details: buildWorkflowCompletionDisplay(batch.entries),
+          },
+          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;
+  let widgetEntryKey: string | undefined;
   let requestWidgetRender: (() => void) | undefined;
   let navigationLayerRegistered = false;
   let dashboardOpen = false;
@@ -477,16 +935,25 @@ export default function workflows(pi: ExtensionAPI) {
     const running = newestEntry(
       [...activeRuns].map(([runId, run]) => [runId, run.details] as const),
     );
-    return running ?? newestEntry(settledRuns);
+    return running ?? newestEntry(settledRuns.entriesArray());
   };
 
   const updateWorkflowWidget = () => {
     const ctx = lastContext;
     if (!ctx || ctx.mode !== "tui") return;
-    const visible = Boolean(stripEntry());
-    if (visible === widgetVisible) return;
+    const entry = stripEntry();
+    const visible = Boolean(entry);
+    const entryKey = workflowStripEntryKey(entry);
+    if (visible === widgetVisible) {
+      if (visible && entryKey !== widgetEntryKey) {
+        widgetEntryKey = entryKey;
+        requestWidgetRender?.();
+      }
+      return;
+    }
     if (!visible) {
       stripState.focused = false;
+      widgetEntryKey = undefined;
       requestWidgetRender = undefined;
       ctx.ui.setWidget(widgetKey, undefined);
       widgetVisible = false;
@@ -501,25 +968,25 @@ export default function workflows(pi: ExtensionAPI) {
       { placement: "belowEditor" },
     );
     widgetVisible = true;
+    widgetEntryKey = entryKey;
   };
 
   const updateIndicator = () => {
+    if (webCapabilityScope) notifyWebCapabilities(webCapabilityScope);
     const ctx = lastContext;
     if (!ctx) return;
     try {
       const running = activeRuns.size;
-      if (running === 0 && completedRuns === 0 && failedRuns === 0) {
-        ctx.ui.setStatus("workflows", undefined);
-      } else {
-        ctx.ui.setStatus(
-          "workflows",
-          formatActivityStatus(ctx.ui.theme, "workflows", {
-            running,
-            done: completedRuns,
-            failed: failedRuns,
-          }),
-        );
-      }
+      statusWriter.write(
+        ctx.ui,
+        running === 0 && completedRuns === 0 && failedRuns === 0
+          ? undefined
+          : formatActivityStatus(ctx.ui.theme, "workflows", {
+              running,
+              done: completedRuns,
+              failed: failedRuns,
+            }),
+      );
       updateWorkflowWidget();
     } catch {
       // UI may be unavailable.
@@ -533,7 +1000,7 @@ export default function workflows(pi: ExtensionAPI) {
   };
 
   const recordSettledRun = (details: WorkflowDetails) => {
-    settledRuns.set(details.runId, details);
+    settledRuns.set(details);
     if (details.status === "completed") completedRuns += 1;
     else failedRuns += 1;
   };
@@ -556,10 +1023,11 @@ export default function workflows(pi: ExtensionAPI) {
     try {
       await showWorkflowDashboard(
         ctx,
-        activeDetails,
+        dashboardDetails,
         initialRunId,
         startedSince,
         stopRun,
+        dashboardRetainedDetails,
       );
       acknowledgeSettledRuns();
     } finally {
@@ -593,7 +1061,21 @@ export default function workflows(pi: ExtensionAPI) {
   };
 
   pi.on("session_start", (_event, ctx) => {
-    hideLifecycleTools();
+    unregisterWebCapability?.();
+    const scope = ctx.sessionManager;
+    webCapabilityScope = scope;
+    unregisterWebCapability = registerWebCapability(scope, {
+      kind: "workflows",
+      snapshot: () =>
+        projectWorkflowCapability([
+          ...activeDetails().values(),
+          ...settledRuns
+            .entriesArray()
+            .filter(([runId]) => !activeRuns.has(runId))
+            .map(([, details]) => details),
+        ]),
+    });
+    registerStableToolFamily();
     if (ctx.hasUI) lastContext = ctx;
     agentTypes = loadAgentTypes({
       agentDir: getAgentDir(),
@@ -603,9 +1085,38 @@ export default function workflows(pi: ExtensionAPI) {
     turnStartedAt = 0;
     completedRuns = 0;
     failedRuns = 0;
-    settledRuns.clear();
+    settledRuns.resetSession();
     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) => {
@@ -621,14 +1132,23 @@ export default function workflows(pi: ExtensionAPI) {
       navigationLayerRegistered = false;
     }
     await shutdownActiveWorkflowRuns([...activeRuns.values()]);
+    // Give deferred completions one final delivery attempt. Failed sends stay
+    // durably pending; clearing first would discard an envelope whose initial
+    // persistence may have failed.
+    await resultDelivery.parentSettled();
     try {
       lastContext?.ui.setStatus("workflows", undefined);
       lastContext?.ui.setWidget(widgetKey, undefined);
     } catch {
       // UI may already be disposed.
     }
+    statusWriter.reset();
+    unregisterWebCapability?.();
+    unregisterWebCapability = undefined;
+    webCapabilityScope = undefined;
     lastContext = undefined;
     widgetVisible = false;
+    widgetEntryKey = undefined;
     requestWidgetRender = undefined;
     stripState.focused = false;
   });
@@ -736,7 +1256,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 launchMode = resolveWorkflowLaunchMode(
+        { wait: params.wait, background: params.background },
+        canDeliverLater,
+      );
+      const background = launchMode === "detached";
+      const now = Date.now();
 
       const details: WorkflowDetails = {
         runId,
@@ -745,15 +1271,21 @@ 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: launchMode === "inline" ? "held-for-inline" : "none",
+          attempts: 0,
+          updatedAt: now,
+        },
       };
 
       // Resume: replay cached results for calls whose content is unchanged.
       // A missing or unreadable source degrades to a normal full run — resume
       // is an optimization and must not become a new way to fail.
-      const journalEntries: JournalEntry[] = [];
+      const journal = createJournalAccumulator();
       let replay: ReplayCache | undefined;
       if (params.resume_from_run_id) {
         const source = resolveRunDir(params.resume_from_run_id);
@@ -773,16 +1305,19 @@ export default function workflows(pi: ExtensionAPI) {
         writeRunFile(runDir, "args.json", params.args);
       persistWorkflowJson(runDir, details);
       const persistence = createWorkflowPersistence(runDir, details, {
-        journal: () => journalEntries,
+        journal: () => journal,
+        ...(workflowLifecycleTestHooks?.persistWorkflow
+          ? { persist: workflowLifecycleTestHooks.persistWorkflow }
+          : {}),
       });
 
-      // 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,
       );
@@ -817,7 +1352,7 @@ export default function workflows(pi: ExtensionAPI) {
         if (background) return;
         onUpdate?.({
           content: [{ type: "text", text: summaryLine(details) }],
-          details: compactToolDetails(details),
+          details: compactWorkflowToolDetails(details),
         });
       };
       const emit = (checkpoint = true) => {
@@ -835,6 +1370,15 @@ export default function workflows(pi: ExtensionAPI) {
         flush(terminal);
       };
 
+      const persistTerminalRecovery = () => {
+        try {
+          persistWorkflowTerminalState(runDir, details);
+        } catch {
+          // The original persistence error remains authoritative; restart
+          // reconciliation handles the remaining uncertainty.
+        }
+      };
+
       const terminalize = (
         status: WorkflowDetails["status"],
         error?: string,
@@ -870,6 +1414,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;
@@ -880,7 +1431,8 @@ export default function workflows(pi: ExtensionAPI) {
         try {
           persistence.flush();
         } catch (persistenceError) {
-          details.error = `${error}; artifact persistence failed: ${errorText(persistenceError)}`;
+          appendArtifactPersistenceFailure(details, persistenceError);
+          persistTerminalRecovery();
         }
         flushNow(true);
       };
@@ -897,15 +1449,19 @@ export default function workflows(pi: ExtensionAPI) {
 
       // The script's narrator. Unlike phase(), this is append-only progress
       // text, so it never mutates the phase list a run is judged against.
-      const logFn = (text: string) => {
+      const logFn = (text: string, kind?: "pipeline-drop") => {
         if (runSettled) return;
-        appendLog(details, text, Date.now());
+        appendLog(details, text, Date.now(), kind);
         emit();
       };
 
       // 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 (
@@ -1216,34 +1772,96 @@ export default function workflows(pi: ExtensionAPI) {
           });
         const callKey = replayIdentity ? replayKey(replayIdentity) : undefined;
         let replayBoundaryViolated = false;
+        const persistAgentResult = (result: {
+          output: string;
+          structured?: unknown;
+        }) => {
+          try {
+            return {
+              ok: true as const,
+              artifact: persistWorkflowAgentResult(runDir, index, result),
+            };
+          } catch (error) {
+            return { ok: false as const, error: errorText(error) };
+          }
+        };
         // Checked before controller.schedule on purpose: schedule() charges the
         // run's agent-call budget on entry, and a replayed call runs no agent.
         const cached =
           callKey && replayLease.canReplay ? replay?.take(callKey) : undefined;
         if (cached) {
           const finishedAt = Date.now();
-          record.invocation = transitionInvocation(record.invocation!, {
-            status: "replayed",
-            at: finishedAt,
-          });
-          record.state = "done";
-          record.replayed = true;
           record.finishedAt = finishedAt;
           record.preview = sanitizeWorkflowDisplayText(
             cached.output,
             PREVIEW_LENGTH,
           );
-          if (acceptanceContract) {
-            record.acceptance = evaluateAcceptance(
-              acceptanceContract,
-              cached.structured,
+          const judged = applyAcceptance({
+            contract: acceptanceContract,
+            structured: cached.structured,
+            agentOk: true,
+          });
+          if (judged.ledger) record.acceptance = judged.ledger;
+          if (!judged.ok) {
+            const error = sanitizeWorkflowDisplayLine(
+              judged.error ?? "Agent failed",
             );
+            record.invocation = transitionInvocation(record.invocation!, {
+              status: "rejected",
+              at: finishedAt,
+            });
+            record.state = "error";
+            record.error = error;
+            emit();
+            replayLease.end();
+            return {
+              ok: false,
+              output: cached.output,
+              ...(cached.structured !== undefined
+                ? { structured: cached.structured }
+                : {}),
+              ...(record.acceptance ? { acceptance: record.acceptance } : {}),
+              error,
+            };
           }
+          const persisted = persistAgentResult({
+            output: cached.output,
+            ...(cached.structured !== undefined
+              ? { structured: cached.structured }
+              : {}),
+          });
+          if (!persisted.ok) {
+            record.invocation = transitionInvocation(record.invocation!, {
+              status: "rejected",
+              at: finishedAt,
+            });
+            record.state = "error";
+            record.error = sanitizeWorkflowDisplayLine(persisted.error);
+            emit();
+            replayLease.end();
+            return {
+              ok: false,
+              output: cached.output,
+              ...(cached.structured !== undefined
+                ? { structured: cached.structured }
+                : {}),
+              ...(record.acceptance ? { acceptance: record.acceptance } : {}),
+              error: persisted.error,
+            };
+          }
+          record.invocation = transitionInvocation(record.invocation!, {
+            status: "replayed",
+            at: finishedAt,
+          });
+          record.state = "done";
+          record.replayed = true;
+          record.resultArtifact = persisted.artifact;
           const ref = handoffs.register({
             callId,
             settled: true,
             ok: true,
             output: cached.output,
+            resultArtifact: record.resultArtifact,
             ...(cached.structured !== undefined
               ? { structured: cached.structured }
               : {}),
@@ -1252,7 +1870,7 @@ export default function workflows(pi: ExtensionAPI) {
           emit();
           // Re-journal so a chain of resumes keeps working: run C resuming from
           // B still finds what B replayed from A.
-          journalEntries.push(cached);
+          journal.append(cached);
           replayLease.end();
           return {
             ok: true,
@@ -1365,6 +1983,9 @@ export default function workflows(pi: ExtensionAPI) {
                   ...(sessionManager ? { sessionManager } : {}),
                   modelRegistry: ctx.modelRegistry,
                   ...(agentType?.tools ? { tools: agentType.tools } : {}),
+                  ...(testAgentSessionFactory
+                    ? { sessionFactory: testAgentSessionFactory }
+                    : {}),
                   ...(replayIdentity
                     ? {
                         replayFilesystemBoundary: {
@@ -1429,7 +2050,18 @@ export default function workflows(pi: ExtensionAPI) {
               });
               const acceptance = judged.ledger;
               if (acceptance) record.acceptance = acceptance;
-              const outcomeOk = judged.ok;
+              let artifactError: string | undefined;
+              if (judged.ok) {
+                const persisted = persistAgentResult({
+                  output: outcome.output,
+                  ...(outcome.structured !== undefined
+                    ? { structured: outcome.structured }
+                    : {}),
+                });
+                if (persisted.ok) record.resultArtifact = persisted.artifact;
+                else artifactError = persisted.error;
+              }
+              const outcomeOk = judged.ok && artifactError === undefined;
               record.invocation = transitionInvocation(record.invocation!, {
                 status: "settled",
                 outcome: outcomeOk ? "success" : "error",
@@ -1437,15 +2069,20 @@ export default function workflows(pi: ExtensionAPI) {
               });
               record.state = outcomeOk ? "done" : "error";
               if (outcomeOk) delete record.error;
-              else
-                record.error = judged.error
-                  ? sanitizeWorkflowDisplayLine(judged.error)
+              else {
+                const failureError = artifactError ?? judged.error;
+                record.error = failureError
+                  ? sanitizeWorkflowDisplayLine(failureError)
                   : undefined;
+              }
               const ref = handoffs.register({
                 callId,
                 settled: true,
                 ok: outcomeOk,
                 output: outcome.output,
+                ...(record.resultArtifact
+                  ? { resultArtifact: record.resultArtifact }
+                  : {}),
                 ...(outcome.structured !== undefined
                   ? { structured: outcome.structured }
                   : {}),
@@ -1477,7 +2114,7 @@ export default function workflows(pi: ExtensionAPI) {
                 !replayBoundaryViolated &&
                 replayLease.canJournal()
               ) {
-                journalEntries.push({
+                journal.append({
                   key: completedKey,
                   output: outcome.output,
                   ...(outcome.structured !== undefined
@@ -1521,7 +2158,10 @@ export default function workflows(pi: ExtensionAPI) {
                     detached: false,
                   };
                 } else {
-                  cleanup = await reclaimWorktree(ctx.cwd, worktree).catch(
+                  const reclaimer =
+                    workflowLifecycleTestHooks?.reclaimWorktree ??
+                    reclaimWorktree;
+                  cleanup = await reclaimer(ctx.cwd, worktree).catch(
                     (error): WorktreeCleanup => ({
                       removed: false,
                       branchDeleted: false,
@@ -1543,13 +2183,21 @@ export default function workflows(pi: ExtensionAPI) {
                     };
                   }
                 }
-                if (!runSettled) {
-                  record.worktreeCleanup = cleanup;
-                  if (cleanup.branchDeleted) delete record.worktreeBranch;
-                  else record.worktreeBranch = cleanup.branch;
-                  if (!cleanup.removed) record.worktreePath = worktree.path;
-                  emit();
-                }
+                record.worktreeCleanup = cleanup;
+                if (cleanup.branchDeleted) delete record.worktreeBranch;
+                else record.worktreeBranch = cleanup.branch;
+                if (!cleanup.removed) record.worktreePath = worktree.path;
+                // Forced settlement fixes the execution verdict, but cleanup
+                // provenance discovered afterward still belongs in the run.
+                // No later final flush remains, so failures must be observable.
+                if (runSettled) {
+                  try {
+                    persistence.flush();
+                  } catch (error) {
+                    appendArtifactPersistenceFailure(details, error);
+                    persistTerminalRecovery();
+                  }
+                } else emit();
               }
             }
           }, invocationSignal)
@@ -1603,8 +2251,8 @@ export default function workflows(pi: ExtensionAPI) {
         try {
           persistence.flush();
         } catch (error) {
-          details.status = "failed";
-          details.error = `Artifact persistence failed: ${errorText(error)}`;
+          appendArtifactPersistenceFailure(details, error);
+          persistTerminalRecovery();
           throw new Error(details.error);
         } finally {
           flushNow(true);
@@ -1621,51 +2269,33 @@ export default function workflows(pi: ExtensionAPI) {
       activeRuns.set(runId, activeRun);
       const completion = runScript();
       activeRun.completion = completion;
+      workflowLifecycleTestHooks?.onRunStarted?.(activeRun);
       if (ctx.hasUI) lastContext = ctx;
       updateIndicator();
 
+      const recordTerminalRun = () => {
+        activeRuns.delete(runId);
+        recordSettledRun(details);
+        updateIndicator();
+      };
+
+      const settleForLaterDelivery = async (inlineReleased: boolean) => {
+        try {
+          await completion;
+        } catch (error) {
+          if (details.status === "running") 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: [
             {
@@ -1677,17 +2307,19 @@ export default function workflows(pi: ExtensionAPI) {
               }),
             },
           ],
-          details: compactToolDetails(details),
+          details: compactWorkflowToolDetails(details),
         };
       }
 
-      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,10 +2329,14 @@ export default function workflows(pi: ExtensionAPI) {
         content: [
           {
             type: "text",
-            text: buildWorkflowResultMessage(details, runDir),
+            text: buildProjectedWorkflowResultMessage(
+              details,
+              runDir,
+              ctx.getContextUsage?.(),
+            ),
           },
         ],
-        details: compactToolDetails(details),
+        details: compactWorkflowToolDetails(details),
       };
     },
 
@@ -1712,20 +2348,24 @@ export default function workflows(pi: ExtensionAPI) {
       let text =
         theme.fg("toolTitle", theme.bold("workflow ")) +
         theme.fg("accent", (meta as WorkflowMeta).name ?? "(script)");
-      if (args.background) text += theme.fg("dim", " (background)");
+      if (args.background !== undefined) {
+        text += theme.fg("dim", ` (deprecated: use wait: ${!args.background})`);
+      } else if (args.wait === true) {
+        text += theme.fg("dim", " (wait)");
+      }
       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) {
-      const details = result.details as WorkflowDetails | undefined;
-      if (!details) {
+    renderResult(result, { expanded, isPartial }, theme, context) {
+      const details = result.details;
+      if (!isWorkflowRenderDetails(details)) {
         const first = result.content[0];
         return new Text(
           first?.type === "text" ? first.text : "(no output)",
@@ -1733,225 +2373,53 @@ export default function workflows(pi: ExtensionAPI) {
           0,
         );
       }
+      // A settled Pi tool result is committed transcript history. Keep its
+      // launch snapshot stable; live run state belongs to the strip/dashboard.
+      const settledAt = Date.now();
+      const currentDetails = () =>
+        isPartial
+          ? (activeRuns.get(details.runId)?.details ??
+            settledRuns.get(details.runId) ??
+            details)
+          : details;
+      syncWorkflowSpinner(
+        context.state as WorkflowRenderState,
+        () => isPartial && currentDetails().status === "running",
+        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,
-              ),
-            );
-          } 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));
+      return {
+        render(width: number) {
+          const current = currentDetails();
+          const totals = formatUsage(aggregateUsage(current.agents));
+          const now = isPartial ? Date.now() : settledAt;
+          if (!expanded) {
+            return buildCollapsedRows(current, theme, width, now, totals);
           }
-        }
-      }
-
-      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,
-            ),
+          return buildExpandedWorkflow(current, theme, now, totals).render(
+            width,
           );
-        }
-        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;
+        },
+        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;
 
     const active = activeRuns.get(resolution.runId);
     if (active) return { ok: true, details: active.details } as const;
-    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");
+    const details = readPersistedWorkflowDetails(resolution.runId, {
+      hydrateArtifacts: true,
+    });
+    if (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.
@@ -1959,12 +2427,15 @@ export default function workflows(pi: ExtensionAPI) {
         ok: true,
         details: recoverStaleWorkflowDetails(details),
       } as const;
-    } catch {
-      return {
-        ok: false,
-        error: `Workflow run ${resolution.runId} could not be read.`,
-      } as const;
     }
+    // Keep the bounded projection as a diagnostic fallback when an artifact is
+    // temporarily unreadable. An explicit id still resolves to a known run.
+    const settled = settledRuns.get(resolution.runId);
+    if (settled) return { ok: true, details: settled } as const;
+    return {
+      ok: false,
+      error: `Workflow run ${resolution.runId} could not be read.`,
+    } as const;
   };
 
   pi.registerTool({
@@ -1978,23 +2449,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 +2491,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,
         };
       };
@@ -2029,32 +2507,57 @@ export default function workflows(pi: ExtensionAPI) {
         if (!resolution.ok) throw new Error(resolution.error);
         const details = resolution.details;
         const runDir = path.join(getAgentDir(), "workflows", details.runId);
+        const retention = settledRuns.stats;
         return Promise.resolve({
           content: [
-            { type: "text", text: buildWorkflowResultMessage(details, runDir) },
+            { type: "text", text: buildWorkflowStatusSummary(details, runDir) },
           ],
-          details: { runs: [summarize(details)] },
+          details: {
+            runs: [summarize(details)],
+            retention,
+            settledRunsEvicted: retention.settledRunsEvicted,
+          },
         });
       }
       const runs = [
         ...[...activeRuns.values()].map((run) => run.details),
         ...settledRuns.values(),
       ];
+      const retention = settledRuns.stats;
       if (runs.length === 0) {
         return Promise.resolve({
           content: [
-            { type: "text", text: "No active or recently finished workflows." },
+            {
+              type: "text",
+              text:
+                retention.evictedRuns > 0
+                  ? `No active or retained workflows. ${retention.evictedRuns} settled run(s) omitted from memory in the current session; canonical artifacts remain available on disk.`
+                  : "No active or recently finished workflows.",
+            },
           ],
-          details: { runs: [] },
+          details: {
+            runs: [],
+            retention,
+            settledRunsEvicted: retention.settledRunsEvicted,
+          },
         });
       }
       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` : ""}`;
       });
+      if (retention.evictedRuns > 0) {
+        lines.push(
+          `Retention (current session): ${retention.retainedRuns} settled projection(s) retained; ${retention.evictedRuns} evicted/omitted (${retention.evictedBytes} UTF-8 bytes). Canonical artifacts remain available on disk.`,
+        );
+      }
       return Promise.resolve({
         content: [{ type: "text", text: lines.join("\n") }],
-        details: { runs: runs.map(summarize) },
+        details: {
+          runs: runs.map(summarize),
+          retention,
+          settledRunsEvicted: retention.settledRunsEvicted,
+        },
       });
     },
   });
@@ -2062,7 +2565,6 @@ export default function workflows(pi: ExtensionAPI) {
   pi.registerMessageRenderer(
     "workflow-result",
     (message, { expanded }, theme) => {
-      const details = message.details as WorkflowDetails | undefined;
       const body =
         typeof message.content === "string"
           ? message.content
@@ -2070,25 +2572,73 @@ export default function workflows(pi: ExtensionAPI) {
               ?.map((part) => (part.type === "text" ? part.text : ""))
               .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`);
-      if (expanded) return new Text(`${header}\n\n${safeBody}`, 0, 0);
-      const preview = safeBody.split("\n").slice(0, 8).join("\n");
-      return new Text(
-        `${header}\n${preview}\n${theme.fg("muted", `(${keyHint("app.tools.expand", "to expand")})`)}`,
-        0,
-        0,
-      );
+      const display = isWorkflowCompletionDisplay(message.details)
+        ? message.details
+        : undefined;
+      const legacyDetails = isWorkflowRenderDetails(message.details)
+        ? message.details
+        : undefined;
+      if (!display && !legacyDetails) {
+        return new Text(safeBody, 0, 0);
+      }
+      if (legacyDetails) {
+        const headerParts = runHeader(legacyDetails, 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(
+          `${header}\n${preview}\n${theme.fg("muted", `(${keyHint("app.tools.expand", "to expand")})`)}`,
+          0,
+          0,
+        );
+      }
+      if (!display) return new Text(safeBody, 0, 0);
+      if (expanded) {
+        return new Text(buildExpandedWorkflowCompletion(display), 0, 0);
+      }
+      return {
+        render(width: number) {
+          const rows: string[] = [];
+          for (const entry of display.entries) {
+            rows.push(
+              truncateToWidth(
+                `${statusGlyph(entry.status, theme, Date.now())} ${workflowCompletionSummary(entry)}`,
+                width,
+                "…",
+              ),
+            );
+            for (const alert of workflowCompletionAlerts(entry)) {
+              rows.push(
+                truncateToWidth(`  ${theme.fg("error", alert)}`, width, "…"),
+              );
+            }
+            const result = workflowCompletionResultPreview(entry);
+            if (result) {
+              rows.push(
+                truncateToWidth(
+                  `  ${theme.fg("accent", "Result:")} ${result}`,
+                  width,
+                  "…",
+                ),
+              );
+            }
+          }
+          rows.push(
+            truncateToWidth(
+              theme.fg(
+                "muted",
+                `(${keyHint("app.tools.expand", "to expand")})`,
+              ),
+              width,
+              "…",
+            ),
+          );
+          return rows;
+        },
+        invalidate() {},
+      };
     },
   );
 }