pi-workflow-engine 0.13.0 → 1.1.0

package/.pi/extensions/pi-workflow-engine/src/workflow-run-controller.ts

@@ -18,19 +18,21 @@ import {
   isWorkflowRunLifecycleAction,
   parseWorkflowRunsCommand,
   retainedWorkflowRunOutcome,
+  supersedingRuns,
   WORKFLOW_RUN_ACTIONS,
   WORKFLOW_RUN_HISTORY_LIMIT,
+  type WorkflowRunActionContext,
   type WorkflowRunLifecycleAction,
 } from "./workflow-run-history.ts";
-import { transitionWorkflowRun, type WorkflowRunRecord } from "./workflow-run-record.ts";
+import { stopWorkflowRunRecord, type WorkflowRunRecord } from "./workflow-run-record.ts";
 import { ProjectWorkflowRunStore, type WorkflowRunStore } from "./workflow-run-store.ts";
 import { unknownErrorMessage } from "./unknown-error.ts";
-import { emptyWorkflowUsageTotals } from "./usage.ts";
 import {
   WorkflowUsageLimitScheduler,
   type WorkflowUsageLimitSchedulerClock,
 } from "./workflow-usage-limit-scheduler.ts";
-import { WorkflowInspector } from "./ui/workflow-inspector.ts";
+import { showWorkflowInspector } from "./ui/workflow-inspector.ts";
+import { WorkflowRunsBrowser, type WorkflowRunsBrowserChoice } from "./ui/workflow-runs-browser.ts";
 import { WORKFLOW_VIEWER_OVERLAY_OPTIONS } from "./ui/workflow-viewer-layout.ts";
 import { completeCurrentArgument, splitArgumentPrefix } from "./command-completions.ts";
 
@@ -77,8 +79,10 @@ export class WorkflowRunController {
     this.completionContext = { cwd: ctx.cwd, sessionManager: ctx.sessionManager };
     this.usageLimitScheduler.activateSession(ctx);
     try {
-      for (const record of await this.storeForCwd(ctx.cwd).list()) {
-        if (canRelaunchWorkflowRun(record)) this.usageLimitScheduler.arm(ctx, record);
+      const records = await this.storeForCwd(ctx.cwd).list();
+      const resumed = resumedRunIds(records);
+      for (const record of records) {
+        if (!resumed.has(record.runId) && canRelaunchWorkflowRun(record)) this.usageLimitScheduler.arm(ctx, record);
       }
     } catch (error) {
       this.log(`[workflow] provider-limit recovery could not load run history: ${unknownErrorMessage(error)}`);
@@ -101,11 +105,12 @@ export class WorkflowRunController {
       return;
     }
     if (!ctx.hasUI) {
-      const records = await this.listRecent(ctx.cwd);
-      ctx.ui.notify(formatWorkflowRunHistory(records, this.background.activeRunIds(ctx)), "info");
+      const { records, runs } = await this.history(ctx);
+      ctx.ui.notify(formatWorkflowRunHistory(records, runs), "info");
       return;
     }
-    await this.openRunSelector(ctx);
+    if (ctx.mode === "tui") await this.openRunsBrowser(ctx);
+    else await this.openRunSelector(ctx);
   }
 
   async inspectStoredRun(ctx: ExtensionContext, runId: string): Promise<boolean> {
@@ -115,17 +120,35 @@ export class WorkflowRunController {
     return true;
   }
 
-  private async openRunSelector(ctx: ExtensionCommandContext): Promise<void> {
+  /** The TUI runs overlay; it reopens on the same run after each action until closed. */
+  private async openRunsBrowser(ctx: ExtensionCommandContext): Promise<void> {
+    let initialRunId: string | undefined;
     while (true) {
-      const records = await this.listRecent(ctx.cwd);
-      const active = this.background.activeRunIds(ctx);
+      const { records, runs } = await this.history(ctx);
       if (records.length === 0) {
-        ctx.ui.notify(formatWorkflowRunHistory(records, active), "info");
+        ctx.ui.notify(formatWorkflowRunHistory(records, runs), "info");
         return;
       }
-      const options = records.map((record) =>
-        formatWorkflowRunSummary(record, active.has(record.runId))
+      const choice = await ctx.ui.custom<WorkflowRunsBrowserChoice | undefined>(
+        (...[tui, theme, , done]) =>
+          new WorkflowRunsBrowser({ records, runs }, tui, theme, done, { initialRunId, refresh: () => this.history(ctx) }),
+        WORKFLOW_VIEWER_OVERLAY_OPTIONS,
       );
+      if (!choice) return;
+      initialRunId = choice.runId;
+      await this.perform(choice.action, choice.runId, ctx);
+    }
+  }
+
+  /** Two native selects (run, then action) for UI hosts that cannot show custom components, such as RPC. */
+  private async openRunSelector(ctx: ExtensionCommandContext): Promise<void> {
+    while (true) {
+      const { records, runs } = await this.history(ctx);
+      if (records.length === 0) {
+        ctx.ui.notify(formatWorkflowRunHistory(records, runs), "info");
+        return;
+      }
+      const options = records.map((record) => formatWorkflowRunSummary(record, runs));
       const selected = await ctx.ui.select("Workflow Runs", options);
       if (!selected) return;
       const selectedIndex = options.indexOf(selected);
@@ -135,7 +158,7 @@ export class WorkflowRunController {
         ctx.ui.notify("The selected workflow run is no longer available.", "warning");
         continue;
       }
-      const actions = availableWorkflowRunActions(record, active.has(record.runId));
+      const actions = availableWorkflowRunActions(record, runs);
       const selectedAction = await ctx.ui.select(
         `${record.workflow.name} · ${record.runId}`,
         [...actions],
@@ -149,22 +172,10 @@ export class WorkflowRunController {
 
   private async inspect(record: WorkflowRunRecord, ctx: ExtensionContext): Promise<void> {
     if (!ctx.hasUI || ctx.mode !== "tui") {
-      ctx.ui.notify(
-        formatWorkflowRunDetails(record, this.background.activeRunIds(ctx).has(record.runId)),
-        "info",
-      );
+      ctx.ui.notify(formatWorkflowRunDetails(record, (await this.history(ctx)).runs), "info");
       return;
     }
-    await ctx.ui.custom<void>(
-      (tui, theme, _keybindings, done) => new WorkflowInspector(
-        () => record.progress,
-        tui,
-        theme,
-        () => done(undefined),
-        { label: `${record.state.toUpperCase()} outcome`, text: retainedWorkflowRunOutcome(record) },
-      ),
-      WORKFLOW_VIEWER_OVERLAY_OPTIONS,
-    );
+    await showWorkflowInspector(ctx.ui, () => record.progress, { text: retainedWorkflowRunOutcome(record), state: record.state });
   }
 
   private async perform(
@@ -181,12 +192,15 @@ export class WorkflowRunController {
       await this.inspect(record, ctx);
       return;
     }
-    const available = availableWorkflowRunActions(
-      record,
-      this.background.activeRunIds(ctx).has(record.runId),
-    );
-    if (!available.includes(action)) {
-      ctx.ui.notify(`Action ${action} is not available for ${record.state} run ${runId}.`, "warning");
+    const { runs } = await this.history(ctx);
+    if (!availableWorkflowRunActions(record, runs).includes(action)) {
+      const resumedAs = record.state === "paused" && action === "resume" ? runs.resumedAs.get(runId) : undefined;
+      ctx.ui.notify(
+        resumedAs
+          ? `Workflow run ${runId} was already resumed as ${resumedAs}.`
+          : `Action ${action} is not available for ${record.state} run ${runId}.`,
+        "warning",
+      );
       return;
     }
 
@@ -194,17 +208,7 @@ export class WorkflowRunController {
       if (action === "stop") {
         if (record.state === "paused") {
           this.usageLimitScheduler.cancel(runId);
-          const stopped = transitionWorkflowRun(record, {
-            state: "stopped",
-            progress: record.progress,
-            usage: record.usage ?? record.progress.usage ?? {
-              agents: [],
-              totals: emptyWorkflowUsageTotals(),
-              assistantMessages: 0,
-            },
-            error: new Error("Workflow stopped by user."),
-          });
-          await this.storeForCwd(ctx.cwd).save(stopped);
+          await this.storeForCwd(ctx.cwd).save(stopWorkflowRunRecord(record));
           await this.background.durableRunSettled(ctx, runId);
           ctx.ui.notify(`Workflow run ${runId} is now stopped.`, "info");
           return;
@@ -227,10 +231,7 @@ export class WorkflowRunController {
     action: "resume" | "restart",
   ): Promise<string> {
     const unavailable = backgroundUnavailableResult(ctx.mode);
-    if (unavailable) {
-      const first = unavailable.content[0];
-      throw new Error(first?.type === "text" ? first.text : "background workflows are unavailable");
-    }
+    if (unavailable) throw new Error(unavailable.content[0].text);
     const workflow = await this.dependencies.resolveWorkflow(record.workflow.name);
     if (!workflow) throw new Error(`registered workflow ${record.workflow.name} is unavailable`);
     if (workflow.source.kind !== "file") {
@@ -243,7 +244,6 @@ export class WorkflowRunController {
       throw new Error("workflow source changed, so journal replay cannot resume safely");
     }
     const options = resolveWorkflowRunOptions({
-      inspect: false,
       perf: record.options.perf,
       concurrency: record.options.concurrency,
       parallelSubmissionLimit: record.options.parallelSubmissionLimit ?? undefined,
@@ -257,7 +257,6 @@ export class WorkflowRunController {
         ? (record.state === "paused" ? record.pause?.attempt : undefined) ?? record.options.usageLimitAttempt
         : 0,
       budget: record.options.budget ?? undefined,
-      resultViewer: "skip",
       resumeFromRunId: action === "resume" ? record.runId : undefined,
     });
     const result = await startBackgroundWorkflowTool({
@@ -268,8 +267,7 @@ export class WorkflowRunController {
       execute: (backgroundCtx, backgroundOptions) =>
         this.dependencies.execute(backgroundCtx, workflow.meta.name, workflow, backgroundOptions),
     });
-    const first = result.content[0];
-    const message = first?.type === "text" ? first.text : `Workflow ${action} started.`;
+    const message = result.content[0].text;
     if (typeof result.details.error === "string") throw new Error(message);
     return message;
   }
@@ -282,6 +280,7 @@ export class WorkflowRunController {
       || !record.pause.autoResume
       || record.pause.attempt !== attempt
       || !canRelaunchWorkflowRun(record)
+      || resumedRunIds(await this.storeForCwd(ctx.cwd).list()).has(runId)
     ) {
       return;
     }
@@ -298,11 +297,17 @@ export class WorkflowRunController {
     return await this.storeForCwd(cwd).load(runId);
   }
 
-  private async listRecent(cwd: string): Promise<WorkflowRunRecord[]> {
-    const records = await this.storeForCwd(cwd).list();
-    return records
-      .sort((left, right) => right.createdAt - left.createdAt)
-      .slice(0, WORKFLOW_RUN_HISTORY_LIMIT);
+  /** The most recent runs and what their actions depend on, from one store listing. */
+  private async history(
+    ctx: WorkflowRunCompletionContext,
+  ): Promise<{ readonly records: WorkflowRunRecord[]; readonly runs: WorkflowRunActionContext }> {
+    const records = await this.storeForCwd(ctx.cwd).list();
+    return {
+      records: [...records]
+        .sort((left, right) => right.createdAt - left.createdAt)
+        .slice(0, WORKFLOW_RUN_HISTORY_LIMIT),
+      runs: { activeRunIds: this.background.activeRunIds(ctx), resumedAs: supersedingRuns(records) },
+    };
   }
 
   async argumentCompletions(argumentPrefix: string): Promise<AutocompleteItem[] | null> {
@@ -314,12 +319,11 @@ export class WorkflowRunController {
     if (parts.completed.length !== 1 || !ctx) return null;
     const action = parts.completed[0];
     if (!action || !isWorkflowRunLifecycleAction(action)) return null;
-    const records = await this.listRecent(ctx.cwd);
-    const active = this.background.activeRunIds(ctx);
+    const { records, runs } = await this.history(ctx);
     return completeCurrentArgument(
       argumentPrefix,
       records
-        .filter((record) => availableWorkflowRunActions(record, active.has(record.runId)).includes(action))
+        .filter((record) => availableWorkflowRunActions(record, runs).includes(action))
         .map((record) => ({
           value: record.runId,
           description: `${record.state} · ${record.workflow.name}`,
@@ -331,7 +335,7 @@ export class WorkflowRunController {
     const ctx = this.completionContext;
     const parts = splitArgumentPrefix(argumentPrefix);
     if (parts.completed.length > 0) return null;
-    const records = ctx ? await this.listRecent(ctx.cwd) : [];
+    const records = ctx ? (await this.history(ctx)).records : [];
     return completeCurrentArgument(argumentPrefix, [
       { value: "last", description: "Inspect the current or most recent in-session workflow" },
       ...records.map((record) => ({
@@ -342,6 +346,16 @@ export class WorkflowRunController {
   }
 }
 
+/**
+ * Runs that any stored run resumed, whatever that resume's outcome. A resumed run keeps its paused
+ * record and pause attempt, so automatic resume treats the pause as spent: re-arming it after a
+ * failed or stopped resume would relaunch it on every session start. Manual resume instead uses
+ * `supersedingRuns`, which frees a run whose every resume failed or was stopped.
+ */
+function resumedRunIds(records: readonly WorkflowRunRecord[]): ReadonlySet<string> {
+  return new Set(records.flatMap((record) => record.options.resumeFromRunId ?? []));
+}
+
 export function registerWorkflowRunCommand(
   pi: Pick<ExtensionAPI, "registerCommand">,
   controller: WorkflowRunController,

package/.pi/extensions/pi-workflow-engine/src/workflow-run-history.ts

@@ -1,5 +1,6 @@
+import { truncateText } from "./text.ts";
 import { formatWorkflowUsageLine } from "./usage.ts";
-import type { WorkflowRunRecord, WorkflowRunState } from "./workflow-run-record.ts";
+import type { WorkflowRunRecord } from "./workflow-run-record.ts";
 import { formatDuration } from "./ui/workflow-format.ts";
 
 export const WORKFLOW_RUN_HISTORY_LIMIT = 50;
@@ -43,15 +44,37 @@ export function workflowRunsUsage(): string {
   return `Usage: /workflow:runs [${WORKFLOW_RUN_ACTIONS.map((action) => action.value).join("|")} <run-id>]`;
 }
 
+/** What a run's lifecycle actions depend on beyond its own record. */
+export interface WorkflowRunActionContext {
+  /** Runs this session is executing in the background. */
+  readonly activeRunIds: ReadonlySet<string>;
+  /** Resumed runs, keyed to the run that resumed them; see {@link supersedingRuns}. */
+  readonly resumedAs: ReadonlyMap<string, string>;
+}
+
+/**
+ * Maps each run to a stored run that resumed it and is queued, running, paused or completed, so
+ * resuming it again would replay its journal a second time. A run whose every resume failed or
+ * was stopped is absent, which leaves manual resume as the way back to its journal.
+ */
+export function supersedingRuns(records: readonly WorkflowRunRecord[]): ReadonlyMap<string, string> {
+  const resumedAs = new Map<string, string>();
+  for (const record of records) {
+    const source = record.options.resumeFromRunId;
+    if (source !== undefined && record.state !== "failed" && record.state !== "stopped") resumedAs.set(source, record.runId);
+  }
+  return resumedAs;
+}
+
 export function availableWorkflowRunActions(
   record: WorkflowRunRecord,
-  active: boolean,
+  runs: WorkflowRunActionContext,
 ): readonly WorkflowRunLifecycleAction[] {
   const actions: WorkflowRunLifecycleAction[] = ["inspect"];
-  if ((record.state === "queued" || record.state === "running") && active) actions.push("stop");
+  if ((record.state === "queued" || record.state === "running") && runs.activeRunIds.has(record.runId)) actions.push("stop");
   if (record.state === "paused") {
     actions.push("stop");
-    if (canRelaunchWorkflowRun(record)) actions.push("resume");
+    if (!runs.resumedAs.has(record.runId) && canRelaunchWorkflowRun(record)) actions.push("resume");
   }
   if (
     (record.state === "completed" || record.state === "failed" || record.state === "stopped")
@@ -70,33 +93,31 @@ export function canRelaunchWorkflowRun(record: WorkflowRunRecord): boolean {
 
 export function formatWorkflowRunHistory(
   records: readonly WorkflowRunRecord[],
-  activeRunIds: ReadonlySet<string> = new Set(),
+  runs: WorkflowRunActionContext,
   now = Date.now(),
 ): string {
   if (records.length === 0) return "No durable workflow runs are available for this project.";
   const lines = ["Recent workflow runs:"];
-  for (const record of records.slice(0, WORKFLOW_RUN_HISTORY_LIMIT)) {
-    lines.push(`- ${formatWorkflowRunSummary(record, activeRunIds.has(record.runId), now)}`);
-  }
-  if (records.length > WORKFLOW_RUN_HISTORY_LIMIT) {
-    lines.push(`… ${records.length - WORKFLOW_RUN_HISTORY_LIMIT} older runs hidden`);
+  for (const record of records) {
+    lines.push(`- ${formatWorkflowRunSummary(record, runs, now)}`);
   }
   return lines.join("\n");
 }
 
 export function formatWorkflowRunSummary(
   record: WorkflowRunRecord,
-  active: boolean,
+  runs: WorkflowRunActionContext,
   now = Date.now(),
 ): string {
   const usage = formatWorkflowUsageLine(record.usage);
-  const actions = availableWorkflowRunActions(record, active).filter((action) => action !== "inspect");
-  return `${workflowRunStateLabel(record.state)} ${record.workflow.name} · age ${formatDuration(Math.max(0, now - record.createdAt))} · duration ${formatWorkflowRunDuration(record, now)}${usage ? ` · ${usage}` : ""} · ${record.runId}${actions.length > 0 ? ` · actions ${actions.join(", ")}` : ""}`;
+  const resumedAs = runs.resumedAs.get(record.runId);
+  const actions = availableWorkflowRunActions(record, runs).filter((action) => action !== "inspect");
+  return `${record.state.toUpperCase()} ${record.workflow.name} · age ${formatDuration(Math.max(0, now - record.createdAt))} · duration ${formatWorkflowRunDuration(record, now)}${usage ? ` · ${usage}` : ""} · ${record.runId}${resumedAs ? ` · resumed as ${resumedAs}` : ""}${actions.length > 0 ? ` · actions ${actions.join(", ")}` : ""}`;
 }
 
 export function formatWorkflowRunDetails(
   record: WorkflowRunRecord,
-  active: boolean,
+  runs: WorkflowRunActionContext,
   now = Date.now(),
 ): string {
   const agents = record.progress.phases.flatMap((phase) =>
@@ -107,12 +128,14 @@ export function formatWorkflowRunDetails(
   const lines = [
     `Workflow run ${record.runId}`,
     `Workflow: ${record.workflow.name}`,
-    `State: ${workflowRunStateLabel(record.state)}`,
+    `State: ${record.state.toUpperCase()}`,
     `Age: ${formatDuration(Math.max(0, now - record.createdAt))}`,
     `Duration: ${formatWorkflowRunDuration(record, now)}`,
     `Phase: ${record.progress.currentPhase}`,
-    `Actions: ${availableWorkflowRunActions(record, active).join(", ")}`,
+    `Actions: ${availableWorkflowRunActions(record, runs).join(", ")}`,
   ];
+  const resumedAs = runs.resumedAs.get(record.runId);
+  if (resumedAs) lines.push(`Resumed as: ${resumedAs}`);
   if (usage) lines.push(usage);
   if (record.options.resumeEditedWorkflow) lines.push("Edited-workflow resume: enabled");
   const cachedAgents = record.progress.counters.find((counter) => counter.key === "resume.cached")?.value ?? 0;
@@ -136,11 +159,11 @@ export function formatWorkflowRunDetails(
 
 export function retainedWorkflowRunOutcome(record: WorkflowRunRecord): string {
   if (record.state === "completed") {
-    if (record.result.kind === "unavailable") return boundedOutcome(`Result unavailable: ${record.result.reason}`);
-    return boundedOutcome(JSON.stringify(record.result.value, null, 2));
+    if (record.result.kind === "unavailable") return truncateText(`Result unavailable: ${record.result.reason}`, WORKFLOW_RUN_OUTCOME_TEXT_LIMIT);
+    return truncateText(JSON.stringify(record.result.value, null, 2), WORKFLOW_RUN_OUTCOME_TEXT_LIMIT);
   }
   if (record.state === "failed" || record.state === "stopped" || record.state === "paused") {
-    return boundedOutcome(record.message);
+    return truncateText(record.message, WORKFLOW_RUN_OUTCOME_TEXT_LIMIT);
   }
   return "Run is still in progress.";
 }
@@ -150,13 +173,3 @@ export function formatWorkflowRunDuration(record: WorkflowRunRecord, now = Date.
   const end = record.endedAt ?? (record.state === "paused" ? record.updatedAt : now);
   return formatDuration(Math.max(0, end - start));
 }
-
-export function workflowRunStateLabel(state: WorkflowRunState): string {
-  return state.toUpperCase();
-}
-
-function boundedOutcome(value: string): string {
-  return value.length <= WORKFLOW_RUN_OUTCOME_TEXT_LIMIT
-    ? value
-    : `${value.slice(0, WORKFLOW_RUN_OUTCOME_TEXT_LIMIT - 1)}…`;
-}

package/.pi/extensions/pi-workflow-engine/src/workflow-run-record.ts

@@ -1,4 +1,5 @@
 import { validateWorkflowRunId } from "./journal.ts";
+import { isFiniteNumber, isRecord } from "./guards.ts";
 import {
   type ResolvedWorkflowRunOptions,
   WORKFLOW_USAGE_LIMIT_ATTEMPTS_MAX,
@@ -8,7 +9,8 @@ import {
 } from "./options.ts";
 import type { WorkflowProgressSnapshot } from "./progress-types.ts";
 import type { LoadedWorkflow, WorkflowSourceIdentity } from "./types.ts";
-import { isWorkflowUsageSnapshot, type WorkflowUsageSnapshot } from "./usage.ts";
+import { truncateText } from "./text.ts";
+import { emptyWorkflowUsageTotals, isWorkflowUsageSnapshot, type WorkflowUsageSnapshot } from "./usage.ts";
 import { unknownErrorMessage } from "./unknown-error.ts";
 import {
   createPersistedWorkflowBackground,
@@ -112,7 +114,6 @@ export type WorkflowRunRecord = WorkflowRunRecordBase & (
 );
 
 export type WorkflowRunTransition =
-  | { readonly state: "queued"; readonly progress: WorkflowProgressSnapshot; readonly at?: number }
   | { readonly state: "running"; readonly progress: WorkflowProgressSnapshot; readonly at?: number }
   | { readonly state: "paused"; readonly progress: WorkflowProgressSnapshot; readonly message: string; readonly pause?: WorkflowRunPause; readonly at?: number }
   | { readonly state: "completed"; readonly progress: WorkflowProgressSnapshot; readonly usage: WorkflowUsageSnapshot; readonly result: unknown; readonly at?: number }
@@ -177,8 +178,6 @@ export function transitionWorkflowRun(record: WorkflowRunRecord, transition: Wor
   };
 
   switch (transition.state) {
-    case "queued":
-      return { ...base, state: "queued", startedAt: record.startedAt };
     case "running":
       return { ...base, state: "running", startedAt: record.startedAt ?? at };
     case "paused":
@@ -211,6 +210,16 @@ export function transitionWorkflowRun(record: WorkflowRunRecord, transition: Wor
   }
 }
 
+/** Records a user stop from the retained state, for runs whose engine cannot record it itself. */
+export function stopWorkflowRunRecord(record: WorkflowRunRecord): WorkflowRunRecord {
+  return transitionWorkflowRun(record, {
+    state: "stopped",
+    progress: record.progress,
+    usage: record.usage ?? record.progress.usage ?? { agents: [], totals: emptyWorkflowUsageTotals(), assistantMessages: 0 },
+    error: "Workflow stopped by user.",
+  });
+}
+
 export function captureWorkflowRunResult(value: unknown): WorkflowRunStoredResult {
   try {
     const state = { nodes: 0, bytes: 0, active: new WeakSet<object>() };
@@ -334,7 +343,7 @@ function isAllowedTransition(from: WorkflowRunState, to: WorkflowRunState): bool
     case "running":
       return to === "completed" || to === "failed" || to === "stopped" || to === "paused";
     case "paused":
-      return to === "queued" || to === "running" || to === "failed" || to === "stopped";
+      return to === "running" || to === "failed" || to === "stopped";
     case "completed":
     case "failed":
     case "stopped":
@@ -458,7 +467,7 @@ function compactWorkflowRunPause(pause: WorkflowRunPause): WorkflowRunPause {
 }
 
 function boundedText(value: string): string {
-  return value.length <= MAX_PERSISTED_TEXT ? value : `${value.slice(0, MAX_PERSISTED_TEXT - 1)}…`;
+  return truncateText(value, MAX_PERSISTED_TEXT);
 }
 
 export function isWorkflowRunRecord(value: unknown): value is WorkflowRunRecord {
@@ -617,16 +626,8 @@ function isValidRunId(value: unknown): value is string {
   }
 }
 
-function isFiniteNumber(value: unknown): value is number {
-  return typeof value === "number" && Number.isFinite(value);
-}
-
 function isIntegerInRange(value: unknown, min: number, max: number): value is number {
   return typeof value === "number" && Number.isSafeInteger(value) && value >= min && value <= max;
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 class WorkflowRunValueError extends Error {}

package/.pi/extensions/pi-workflow-engine/src/workflow-run-store.ts

@@ -8,6 +8,7 @@ import {
   transitionWorkflowRun,
   updateWorkflowRunProgress,
   type WorkflowRunRecord,
+  type WorkflowRunState,
   type WorkflowRunTransition,
 } from "./workflow-run-record.ts";
 
@@ -37,8 +38,9 @@ export class ProjectWorkflowRunStore implements WorkflowRunStore {
     try {
       await writeFile(temporaryPath, content, { encoding: "utf8", mode: 0o600 });
       await rename(temporaryPath, path);
-    } finally {
+    } catch (error) {
       await rm(temporaryPath, { force: true }).catch(() => undefined);
+      throw error;
     }
   }
 
@@ -47,43 +49,22 @@ export class ProjectWorkflowRunStore implements WorkflowRunStore {
   }
 
   async list(): Promise<WorkflowRunRecord[]> {
-    const dir = join(this.cwd, WORKFLOW_RUNS_DIR);
-    let files: string[];
-    try {
-      files = await readdir(dir);
-    } catch {
-      return [];
-    }
-    const records = await Promise.all(
-      files
-        .filter((file) => file.endsWith(WORKFLOW_RUN_RECORD_SUFFIX))
-        .map((file) => loadWorkflowRunRecord(join(dir, file))),
-    );
+    const records = await Promise.all((await this.recordPaths()).map(loadWorkflowRunRecord));
     return records
       .filter((record): record is WorkflowRunRecord => record !== undefined)
       .sort((left, right) => right.updatedAt - left.updatedAt);
   }
 
   async prune(keep = WORKFLOW_RUN_RECORD_KEEP): Promise<void> {
-    const dir = join(this.cwd, WORKFLOW_RUNS_DIR);
-    let files: string[];
-    try {
-      files = await readdir(dir);
-    } catch {
-      return;
-    }
     const candidates = await Promise.all(
-      files
-        .filter((file) => file.endsWith(WORKFLOW_RUN_RECORD_SUFFIX))
-        .map(async (file) => {
-          const path = join(dir, file);
-          try {
-            const info = await stat(path);
-            return { path, mtimeMs: info.mtimeMs };
-          } catch {
-            return undefined;
-          }
-        }),
+      (await this.recordPaths()).map(async (path) => {
+        try {
+          const info = await stat(path);
+          return { path, mtimeMs: info.mtimeMs };
+        } catch {
+          return undefined;
+        }
+      }),
     );
     const stale = candidates
       .filter((entry): entry is { readonly path: string; readonly mtimeMs: number } => entry !== undefined)
@@ -91,6 +72,17 @@ export class ProjectWorkflowRunStore implements WorkflowRunStore {
       .slice(Math.max(0, keep));
     await Promise.all(stale.map((entry) => rm(entry.path, { force: true }).catch(() => undefined)));
   }
+
+  /** Record file paths in the runs directory; empty when the directory cannot be read. */
+  private async recordPaths(): Promise<string[]> {
+    const dir = join(this.cwd, WORKFLOW_RUNS_DIR);
+    try {
+      const files = await readdir(dir);
+      return files.filter((file) => file.endsWith(WORKFLOW_RUN_RECORD_SUFFIX)).map((file) => join(dir, file));
+    } catch {
+      return [];
+    }
+  }
 }
 
 /** Owns one run record and coalesces progress writes while a prior atomic save is in flight. */
@@ -110,6 +102,10 @@ export class DurableWorkflowRun {
     this.queue(initial);
   }
 
+  get state(): WorkflowRunState {
+    return this.record.state;
+  }
+
   updateProgress(progress: WorkflowProgressSnapshot, at = Date.now()): void {
     this.record = updateWorkflowRunProgress(this.record, progress, at);
     this.queue(this.record);

package/.pi/extensions/pi-workflow-engine/src/workflow-usage-limit-scheduler.ts

@@ -13,7 +13,7 @@ interface ScheduledUsageLimitResume {
   readonly handle: unknown;
 }
 
-export const defaultWorkflowUsageLimitSchedulerClock: WorkflowUsageLimitSchedulerClock = {
+const defaultWorkflowUsageLimitSchedulerClock: WorkflowUsageLimitSchedulerClock = {
   now: () => Date.now(),
   setTimeout: (callback, delayMs) => setTimeout(callback, delayMs),
   clearTimeout: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
@@ -73,8 +73,4 @@ export class WorkflowUsageLimitScheduler {
   activateSession(ctx: Pick<ExtensionContext, "sessionManager">): void {
     this.inactiveSessions.delete(ctx.sessionManager.getSessionId());
   }
-
-  has(runId: string): boolean {
-    return this.scheduled.has(runId);
-  }
 }

package/.pi/extensions/pi-workflow-engine/src/workflows.ts

@@ -12,8 +12,9 @@ import type { WorkflowModule } from "./types.ts";
  * pi's bundled `typebox` / SDK — guaranteeing schema validation works.
  *
  * To add a guaranteed workflow: drop a `.ts` in `workflows/`, import it here, and add
- * it to this array. (Drop-in workflows discovered at runtime are also supported — see
- * discovery.ts — but the static registry is the always-correct path.)
+ * a `defineBuiltinWorkflow(mod, "<name>.ts")` entry to `BUILTIN_WORKFLOW_DEFINITIONS`.
+ * (Drop-in workflows discovered at runtime are also supported — see discovery.ts — but
+ * the static registry is the always-correct path.)
  *
  * Do not replace these built-in imports with dynamic imports unless a dedicated test
  * proves pi's jiti virtual modules preserve the same bundled `typebox` identity for
@@ -26,7 +27,6 @@ export interface BuiltinWorkflowDefinition {
   readonly module: WorkflowModule;
   readonly filename: string;
   readonly path: string;
-  readonly root: string;
 }
 
 export const BUILTIN_WORKFLOW_DEFINITIONS: readonly BuiltinWorkflowDefinition[] = [
@@ -36,15 +36,12 @@ export const BUILTIN_WORKFLOW_DEFINITIONS: readonly BuiltinWorkflowDefinition[]
   defineBuiltinWorkflow(perfReview, "perf-review.ts"),
   defineBuiltinWorkflow(research, "research.ts"),
 ];
-export const BUILTIN_WORKFLOWS = BUILTIN_WORKFLOW_DEFINITIONS.map(({ module }) => module);
 export const BUILTIN_WORKFLOW_FILES = new Set(BUILTIN_WORKFLOW_DEFINITIONS.map(({ filename }) => filename));
-export const BUILTIN_WORKFLOW_NAMES = BUILTIN_WORKFLOWS.map((mod) => mod.meta.name);
 
 function defineBuiltinWorkflow(module: WorkflowModule, filename: string): BuiltinWorkflowDefinition {
   return {
     module: { meta: module.meta, default: module.default },
     filename,
     path: fileURLToPath(new URL(`../workflows/${filename}`, import.meta.url)),
-    root: BUILTIN_SOURCE_ROOT,
   };
 }