@tt-a1i/openpi 0.4.0 → 0.5.0

package/extensions/workflows/index.ts

@@ -48,20 +48,29 @@ import {
   truncateToWidth,
 } from "@earendil-works/pi-tui";
 import { type Static, Type } from "typebox";
-import { formatActivityStatus } from "../shared/activity-status.ts";
+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 { 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 {
+  notifyWebCapabilities,
+  projectWorkflowCapability,
+  registerWebCapability,
+  type WebCapabilityScope,
+} from "../shared/web-observer-registry.ts";
 import {
   createWorktree,
   reclaimWorktree,
@@ -78,18 +87,27 @@ import {
   acceptanceInstruction,
   acceptanceSchema,
   applyAcceptance,
-  evaluateAcceptance,
   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 {
-  resolveWorkflowLaunchPolicy,
+  resolveWorkflowLaunchMode,
   waitForWorkflowCompletion,
 } from "./coordinator.ts";
 import {
@@ -108,8 +126,8 @@ import {
 } from "./invocation-ledger.ts";
 import {
   agentCallKey,
+  createJournalAccumulator,
   createReplayCache,
-  type JournalEntry,
   type ReplayCache,
 } from "./journal.ts";
 import {
@@ -122,6 +140,7 @@ import {
   agentContext,
   aggregateUsage,
   appendLog,
+  compactWorkflowToolDetails,
   countStates,
   createUsageReader,
   emptyUsage,
@@ -146,15 +165,15 @@ import {
   type WorkflowStripEntry,
   WorkflowStripState,
   WorkflowStripWidget,
+  workflowStripEntryKey,
 } from "./navigation.ts";
 import {
   normalizeWorkflowOperatorKey,
   WorkflowOperatorRegistry,
 } from "./operator.ts";
 import {
-  buildBackgroundWorkflowFollowUp,
   buildBackgroundWorkflowLaunchResult,
-  buildProjectedWorkflowCompletionBatch,
+  buildProjectedWorkflowCompletionBatches,
   buildProjectedWorkflowResultMessage,
   buildWorkflowAgentPrompt,
   buildWorkflowResultMessage,
@@ -169,15 +188,20 @@ import {
   WORKFLOW_STOP_TOOL_DESCRIPTION,
   WORKFLOW_TOOL_DESCRIPTION,
 } from "./prompt.ts";
-import {
-  createWorkflowResultDelivery,
-  type WorkflowCompletionEnvelope,
-} from "./result-delivery.ts";
 import {
   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,
@@ -186,7 +210,7 @@ import {
   type WorkflowModel,
 } from "./runner.ts";
 import { runWorkflowSandbox } from "./sandbox.ts";
-import { safeStringify, writeFileAtomic } from "./serialization.ts";
+import { writeFileAtomic } from "./serialization.ts";
 import {
   finalizeWorktreeHandoff,
   prepareWorktreeHandoff,
@@ -203,7 +227,7 @@ function runHeader(
 ) {
   const { done, failed, uncertain } = countStates(details);
   const settled = done + failed;
-  const elapsed = formatElapsed(details.startedAt, details.finishedAt);
+  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 =
@@ -264,7 +288,7 @@ function buildCollapsedRows(
         ? percent === undefined
           ? undefined
           : `${percent}%`
-        : formatElapsed(agent.startedAt, agent.finishedAt);
+        : formatElapsed(agent.startedAt, agent.finishedAt, now);
     const left = `  ${stateGlyph(agent.state, theme, now)} ${theme.fg(
       "accent",
       sanitizeWorkflowDisplayLine(agent.label),
@@ -366,7 +390,7 @@ function buildExpandedWorkflow(
         sanitizeWorkflowDisplayLine(agent.label),
       )} ${theme.fg(
         "dim",
-        [context, formatElapsed(agent.startedAt, agent.finishedAt)]
+        [context, formatElapsed(agent.startedAt, agent.finishedAt, now)]
           .filter(Boolean)
           .join(" · "),
       )}`;
@@ -532,31 +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,
     }),
-  ),
-  wait: Type.Optional(
-    Type.Boolean({
-      description: WORKFLOW_PARAMETER_DESCRIPTIONS.wait,
-    }),
-  ),
-  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>;
 
@@ -594,6 +622,25 @@ 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, uncertain } = countStates(details);
   const settled = done + failed;
@@ -613,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">;
@@ -634,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[],
@@ -738,19 +796,38 @@ function runDetailText(
   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 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.entry,
     });
   const stripState = new WorkflowStripState();
+  const statusWriter = createStatusWriter("workflows");
   const widgetKey = "workflow-navigation";
 
   /**
@@ -763,41 +840,61 @@ export default function workflows(pi: ExtensionAPI) {
   ): 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,
+      details: projection,
     };
   };
   const resultDelivery = createWorkflowResultDelivery({
     isIdle: () => lastContext?.isIdle() ?? false,
-    persist: (details) =>
-      persistWorkflowJson(
+    persist: (details) => {
+      if (!details.delivery)
+        throw new Error("Workflow delivery identity is missing");
+      persistWorkflowDeliveryState(
         path.join(getAgentDir(), "workflows", details.runId),
-        details,
-      ),
+        details.delivery,
+      );
+    },
     deliver: async (envelopes, wake) => {
-      const content = buildProjectedWorkflowCompletionBatch(
-        envelopes.map((envelope) => ({
-          deliveryId: envelope.deliveryId,
-          details: envelope.details,
-          runDir: path.join(getAgentDir(), "workflows", envelope.runId),
-        })),
+      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?.(),
       );
-      pi.sendMessage(
-        {
-          customType: "workflow-result",
-          content,
-          display: true,
-          ...(envelopes.length === 1
-            ? { details: compactToolDetails(envelopes[0]!.details) }
-            : {}),
-        },
-        wake
-          ? { deliverAs: "followUp", triggerTurn: true }
-          : { deliverAs: "nextTurn" },
-      );
+      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,
@@ -807,6 +904,7 @@ export default function workflows(pi: ExtensionAPI) {
   let completedRuns = 0;
   let failedRuns = 0;
   let widgetVisible = false;
+  let widgetEntryKey: string | undefined;
   let requestWidgetRender: (() => void) | undefined;
   let navigationLayerRegistered = false;
   let dashboardOpen = false;
@@ -837,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;
@@ -861,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.
@@ -893,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;
   };
@@ -916,10 +1023,11 @@ export default function workflows(pi: ExtensionAPI) {
     try {
       await showWorkflowDashboard(
         ctx,
-        activeDetails,
+        dashboardDetails,
         initialRunId,
         startedSince,
         stopRun,
+        dashboardRetainedDetails,
       );
       acknowledgeSettledRuns();
     } finally {
@@ -953,6 +1061,20 @@ export default function workflows(pi: ExtensionAPI) {
   };
 
   pi.on("session_start", (_event, ctx) => {
+    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({
@@ -963,7 +1085,7 @@ export default function workflows(pi: ExtensionAPI) {
     turnStartedAt = 0;
     completedRuns = 0;
     failedRuns = 0;
-    settledRuns.clear();
+    settledRuns.resetSession();
     installWorkflowNavigation(ctx);
     updateIndicator();
 
@@ -1010,17 +1132,25 @@ 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;
-    resultDelivery.clear();
   });
 
   pi.registerCommand("workflows", {
@@ -1127,11 +1257,11 @@ export default function workflows(pi: ExtensionAPI) {
       const runId = `wf_${randomBytes(6).toString("hex")}`;
       const runDir = path.join(getAgentDir(), "workflows", runId);
       const canDeliverLater = ctx.hasUI && ctx.mode === "tui";
-      const launchPolicy = resolveWorkflowLaunchPolicy(
+      const launchMode = resolveWorkflowLaunchMode(
         { wait: params.wait, background: params.background },
         canDeliverLater,
       );
-      const background = launchPolicy.detached;
+      const background = launchMode === "detached";
       const now = Date.now();
 
       const details: WorkflowDetails = {
@@ -1146,7 +1276,7 @@ export default function workflows(pi: ExtensionAPI) {
         agents: [],
         delivery: {
           id: `workflow:${runId}:terminal`,
-          state: launchPolicy.wait ? "held-for-inline" : "none",
+          state: launchMode === "inline" ? "held-for-inline" : "none",
           attempts: 0,
           updatedAt: now,
         },
@@ -1155,7 +1285,7 @@ export default function workflows(pi: ExtensionAPI) {
       // 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);
@@ -1175,7 +1305,10 @@ 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 }
+          : {}),
       });
 
       // A caller wait never owns the run. All runs survive an interrupted
@@ -1219,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) => {
@@ -1237,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,
@@ -1289,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);
       };
@@ -1306,9 +1449,9 @@ 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();
       };
 
@@ -1629,35 +1772,90 @@ 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,
+            };
           }
-          record.resultArtifact = persistWorkflowAgentResult(runDir, index, {
+          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,
@@ -1672,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,
@@ -1852,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",
@@ -1860,21 +2069,11 @@ 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;
-              if (outcomeOk) {
-                record.resultArtifact = persistWorkflowAgentResult(
-                  runDir,
-                  index,
-                  {
-                    output: outcome.output,
-                    ...(outcome.structured !== undefined
-                      ? { structured: outcome.structured }
-                      : {}),
-                  },
-                );
               }
               const ref = handoffs.register({
                 callId,
@@ -1915,7 +2114,7 @@ export default function workflows(pi: ExtensionAPI) {
                 !replayBoundaryViolated &&
                 replayLease.canJournal()
               ) {
-                journalEntries.push({
+                journal.append({
                   key: completedKey,
                   output: outcome.output,
                   ...(outcome.structured !== undefined
@@ -1959,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,
@@ -1981,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)
@@ -2041,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);
@@ -2059,6 +2269,7 @@ 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();
 
@@ -2072,8 +2283,8 @@ export default function workflows(pi: ExtensionAPI) {
         try {
           await completion;
         } catch (error) {
-          details.status = "failed";
-          details.finishedAt = Date.now();
+          if (details.status === "running") details.status = "failed";
+          details.finishedAt ??= Date.now();
           details.error = details.error ?? errorText(error);
         } finally {
           recordTerminalRun();
@@ -2096,7 +2307,7 @@ export default function workflows(pi: ExtensionAPI) {
               }),
             },
           ],
-          details: compactToolDetails(details),
+          details: compactWorkflowToolDetails(details),
         };
       }
 
@@ -2125,7 +2336,7 @@ export default function workflows(pi: ExtensionAPI) {
             ),
           },
         ],
-        details: compactToolDetails(details),
+        details: compactWorkflowToolDetails(details),
       };
     },
 
@@ -2137,7 +2348,11 @@ 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)) {
@@ -2149,8 +2364,8 @@ export default function workflows(pi: ExtensionAPI) {
     },
 
     renderResult(result, { expanded, isPartial }, theme, context) {
-      const details = result.details as WorkflowDetails | undefined;
-      if (!details) {
+      const details = result.details;
+      if (!isWorkflowRenderDetails(details)) {
         const first = result.content[0];
         return new Text(
           first?.type === "text" ? first.text : "(no output)",
@@ -2158,15 +2373,18 @@ 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 = () =>
-        activeRuns.get(details.runId)?.details ??
-        settledRuns.get(details.runId) ??
-        details;
+        isPartial
+          ? (activeRuns.get(details.runId)?.details ??
+            settledRuns.get(details.runId) ??
+            details)
+          : details;
       syncWorkflowSpinner(
         context.state as WorkflowRenderState,
-        () =>
-          currentDetails().status === "running" &&
-          (isPartial || activeRuns.has(details.runId)),
+        () => isPartial && currentDetails().status === "running",
         context.invalidate,
       );
 
@@ -2174,21 +2392,13 @@ export default function workflows(pi: ExtensionAPI) {
         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,
-              Date.now(),
-              totals,
-            );
+            return buildCollapsedRows(current, theme, width, now, totals);
           }
-          return buildExpandedWorkflow(
-            current,
-            theme,
-            Date.now(),
-            totals,
-          ).render(width);
+          return buildExpandedWorkflow(current, theme, now, totals).render(
+            width,
+          );
         },
         invalidate() {},
       };
@@ -2206,24 +2416,25 @@ export default function workflows(pi: ExtensionAPI) {
 
     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;
-
     const details = readPersistedWorkflowDetails(resolution.runId, {
       hydrateArtifacts: true,
     });
-    if (!details) {
+    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.
       return {
-        ok: false,
-        error: `Workflow run ${resolution.runId} could not be read.`,
+        ok: true,
+        details: recoverStaleWorkflowDetails(details),
       } 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.
+    // 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: true,
-      details: recoverStaleWorkflowDetails(details),
+      ok: false,
+      error: `Workflow run ${resolution.runId} could not be read.`,
     } as const;
   };
 
@@ -2296,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: 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, 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,
+        },
       });
     },
   });
@@ -2329,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
@@ -2337,18 +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 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(
-        `${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() {},
+      };
     },
   );
 }