@quintinshaw/pi-dynamic-workflows 1.2.0 → 1.4.0

package/README.md

@@ -46,6 +46,18 @@ The model writes a workflow script and calls the `workflow` tool. Live progress
 
 Press `Esc` to cancel a running run; active subagents are aborted and surfaced as skipped.
 
+### Background runs & `/workflows`
+
+Ask for a background workflow (the model passes `background: true`) and it runs without blocking your session. Manage it with the `/workflows` command:
+
+```text
+/workflows                 # list runs (default)
+/workflows status <id>     # show a run's progress
+/workflows stop <id>       # abort a running run
+/workflows pause <id>      # pause a running run
+/workflows rm <id>         # remove a run from the list
+```
+
 ## Workflow script shape
 
 A workflow is plain JavaScript. The first statement must export literal metadata:
@@ -121,6 +133,8 @@ Scripts run inside a Node `vm` sandbox. Intentionally unavailable: `Date.now()`,
 - **Structured output** — JSON-Schema-validated subagent results
 - **Real token & cost accounting** — read from each subagent's SDK session (input / output / total / cost), with a character estimate only as fallback when a provider reports no usage; `budget` gates on the real total
 - **Real per-agent / per-phase model routing** — `opts.model` and `meta.phases[].model` actually select the model (resolved against your authed model registry), with graceful fallback
+- **`/workflows` command** — list, inspect, stop, pause, **resume**, and remove background runs; runs started with `background: true` are reachable from the command
+- **Resume** — each agent result is journaled by a deterministic call index; resuming replays the unchanged prefix from cache (no re-run, no tokens) and runs only new or edited calls live
 - **Safety limits** — 1000-agent cap (`maxAgents`), per-agent timeout (`agentTimeoutMs`), recoverable-vs-fatal error classification
 - **Live progress + token/cost display**, `Esc` to abort
 - **Log persistence** to `.pi/workflows/runs/`
@@ -129,8 +143,6 @@ Scripts run inside a Node `vm` sandbox. Intentionally unavailable: `Date.now()`,
 
 Tracked toward closer parity with Claude Code dynamic workflows:
 
-- **Command surface** — `/workflows` (list / status / stop) and reachable background runs
-- **Resume** — journaled results, replay the unchanged prefix, run the rest live
 - **Worktree isolation** for parallel edits, and **bundled `/deep-research`**
 - **Saved workflows** as `/<name>` slash commands
 

package/dist/index.d.ts

@@ -20,6 +20,7 @@ export type { StructuredOutputCapture, StructuredOutputToolOptions } from "./str
 export { createStructuredOutputTool } from "./structured-output.js";
 export type { AgentOptions, WorkflowMeta, WorkflowMetaPhase, WorkflowRunOptions, WorkflowRunResult, } from "./workflow.js";
 export { parseWorkflowScript, runWorkflow } from "./workflow.js";
+export { registerWorkflowCommands } from "./workflow-commands.js";
 export type { ManagedRun, WorkflowManagerOptions } from "./workflow-manager.js";
 export { WorkflowManager } from "./workflow-manager.js";
 export type { SavedWorkflow, WorkflowStorage } from "./workflow-saved.js";

package/dist/index.js

@@ -10,6 +10,7 @@ export { buildModelRoutingInstructions, parseModelRoutingFromMeta, resolveModelF
 export { createRunPersistence, generateRunId } from "./run-persistence.js";
 export { createStructuredOutputTool } from "./structured-output.js";
 export { parseWorkflowScript, runWorkflow } from "./workflow.js";
+export { registerWorkflowCommands } from "./workflow-commands.js";
 export { WorkflowManager } from "./workflow-manager.js";
 export { createWorkflowStorage } from "./workflow-saved.js";
 export { createWorkflowTool } from "./workflow-tool.js";

package/dist/run-persistence.d.ts

@@ -33,6 +33,12 @@ export interface PersistedRunState {
         output: number;
         total: number;
     };
+    /** Cached agent results for resume, keyed by deterministic call index. */
+    journal?: Array<{
+        index: number;
+        hash: string;
+        result: unknown;
+    }>;
 }
 export interface RunPersistence {
     /** Save current run state. */

package/dist/workflow-commands.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `/workflows` slash command: list, inspect, and control background workflow runs.
+ * Shares the extension's single WorkflowManager so background runs are reachable.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { WorkflowManager } from "./workflow-manager.js";
+/** Register the `/workflows` command against the shared manager. Idempotent. */
+export declare function registerWorkflowCommands(pi: ExtensionAPI, manager: WorkflowManager): void;

package/dist/workflow-commands.js

@@ -0,0 +1,111 @@
+/**
+ * `/workflows` slash command: list, inspect, and control background workflow runs.
+ * Shares the extension's single WorkflowManager so background runs are reachable.
+ */
+import { renderWorkflowText } from "./display.js";
+const STATUS_ICON = {
+    pending: "·",
+    running: "◆",
+    paused: "⏸",
+    completed: "✓",
+    failed: "✗",
+    aborted: "⊘",
+};
+const USAGE = "Usage: /workflows [list] | status <id> | stop <id> | pause <id> | resume <id> | rm <id>";
+function summarizeRun(run) {
+    const icon = STATUS_ICON[run.status] ?? "?";
+    const done = run.agents.filter((a) => a.status === "done").length;
+    const total = run.agents.length;
+    const tokens = run.tokenUsage ? ` · ${run.tokenUsage.total.toLocaleString()} tok` : "";
+    return `${icon} ${run.runId}  ${run.workflowName} [${run.status}] ${done}/${total} agents${tokens}`;
+}
+function renderPersistedStatus(run) {
+    const lines = [`${STATUS_ICON[run.status] ?? "?"} ${run.workflowName} (${run.runId}) — ${run.status}`];
+    if (run.currentPhase)
+        lines.push(`  phase: ${run.currentPhase}`);
+    for (const agent of run.agents) {
+        const icon = agent.status === "done" ? "✓" : agent.status === "error" ? "✗" : agent.status === "running" ? "◆" : "·";
+        lines.push(`  ${icon} ${agent.label}`);
+    }
+    if (run.tokenUsage)
+        lines.push(`  tokens: ${run.tokenUsage.total.toLocaleString()}`);
+    if (run.durationMs)
+        lines.push(`  duration: ${(run.durationMs / 1000).toFixed(1)}s`);
+    return lines.join("\n");
+}
+/** Register the `/workflows` command against the shared manager. Idempotent. */
+export function registerWorkflowCommands(pi, manager) {
+    try {
+        const taken = (pi.getCommands?.() ?? []).some((c) => c.name === "workflows");
+        if (taken)
+            return;
+    }
+    catch {
+        // getCommands may be unavailable in some hosts; fall through and try to register.
+    }
+    pi.registerCommand("workflows", {
+        description: "List and control background workflow runs",
+        async handler(args, ctx) {
+            const parts = args.trim().split(/\s+/).filter(Boolean);
+            const sub = (parts[0] ?? "list").toLowerCase();
+            const id = parts[1];
+            const print = (text) => pi.sendMessage({ customType: "workflows", content: text, display: true });
+            switch (sub) {
+                case "list": {
+                    const runs = manager.listRuns();
+                    if (!runs.length) {
+                        await print("No workflow runs yet. Start one with a background workflow (background: true).");
+                        return;
+                    }
+                    await print(["Workflow runs:", ...runs.map(summarizeRun), "", USAGE].join("\n"));
+                    return;
+                }
+                case "status": {
+                    if (!id) {
+                        ctx.ui.notify(USAGE, "warning");
+                        return;
+                    }
+                    const live = manager.getSnapshot(id);
+                    if (live) {
+                        await print(renderWorkflowText(live, false));
+                        return;
+                    }
+                    const run = manager.listRuns().find((r) => r.runId === id);
+                    if (!run) {
+                        ctx.ui.notify(`No workflow run "${id}"`, "error");
+                        return;
+                    }
+                    await print(renderPersistedStatus(run));
+                    return;
+                }
+                case "stop": {
+                    if (!id)
+                        return ctx.ui.notify(USAGE, "warning");
+                    ctx.ui.notify(manager.stop(id) ? `Stopped ${id}` : `Cannot stop ${id} (not running)`, manager.getRun(id) ? "info" : "warning");
+                    return;
+                }
+                case "pause": {
+                    if (!id)
+                        return ctx.ui.notify(USAGE, "warning");
+                    ctx.ui.notify(manager.pause(id) ? `Paused ${id}` : `Cannot pause ${id} (not running)`, "info");
+                    return;
+                }
+                case "resume": {
+                    if (!id)
+                        return ctx.ui.notify(USAGE, "warning");
+                    const ok = await manager.resume(id);
+                    ctx.ui.notify(ok ? `Resumed ${id}` : `Resume not available for ${id} yet`, ok ? "info" : "warning");
+                    return;
+                }
+                case "rm": {
+                    if (!id)
+                        return ctx.ui.notify(USAGE, "warning");
+                    ctx.ui.notify(manager.deleteRun(id) ? `Removed ${id}` : `No run ${id}`, "info");
+                    return;
+                }
+                default:
+                    ctx.ui.notify(`Unknown subcommand "${sub}". ${USAGE}`, "warning");
+            }
+        },
+    });
+}

package/dist/workflow-manager.d.ts

@@ -5,7 +5,7 @@ import { EventEmitter } from "node:events";
 import type { WorkflowSnapshot } from "./display.js";
 import { WorkflowError } from "./errors.js";
 import { type PersistedRunState, type RunPersistence, type RunStatus } from "./run-persistence.js";
-import { type WorkflowRunResult } from "./workflow.js";
+import { type JournalEntry, type WorkflowRunResult } from "./workflow.js";
 export interface ManagedRun {
     runId: string;
     status: RunStatus;
@@ -14,6 +14,11 @@ export interface ManagedRun {
     error?: WorkflowError;
     controller: AbortController;
     startedAt: Date;
+    /** The real script, kept so the run can be resumed. */
+    script: string;
+    args?: unknown;
+    /** Accumulated agent results for resume (deterministic call index -> result). */
+    journal: JournalEntry[];
 }
 export interface WorkflowManagerOptions {
     cwd?: string;
@@ -44,7 +49,8 @@ export declare class WorkflowManager extends EventEmitter {
      */
     pause(runId: string): boolean;
     /**
-     * Resume a paused workflow.
+     * Resume an interrupted run: replay journaled results for the unchanged prefix
+     * and run the rest live. Returns false if there is nothing resumable.
      */
     resume(runId: string): Promise<boolean>;
     /**

package/dist/workflow-manager.js

@@ -40,6 +40,9 @@ export class WorkflowManager extends EventEmitter {
             },
             controller,
             startedAt: new Date(),
+            script,
+            args,
+            journal: [],
         };
         this.runs.set(runId, managed);
         // Persist initial state
@@ -82,17 +85,28 @@ export class WorkflowManager extends EventEmitter {
             },
             controller,
             startedAt: new Date(),
+            script,
+            args,
+            journal: [],
         };
         this.runs.set(runId, managed);
         return this.executeRun(managed, script, args);
     }
-    async executeRun(managed, script, args) {
+    async executeRun(managed, script, args, resumeJournal) {
         try {
             const result = await runWorkflow(script, {
                 cwd: this.cwd,
                 args,
                 signal: managed.controller.signal,
                 concurrency: this.concurrency,
+                resumeJournal,
+                resumeFromRunId: resumeJournal ? managed.runId : undefined,
+                onAgentJournal: (entry) => {
+                    // Append (crash-safe-ish): keep the latest entry per index, then persist.
+                    managed.journal = managed.journal.filter((e) => e.index !== entry.index);
+                    managed.journal.push(entry);
+                    this.persistRun(managed);
+                },
                 onLog: (message) => {
                     managed.snapshot.logs.push(message);
                     this.emit("log", { runId: managed.runId, message });
@@ -152,7 +166,11 @@ export class WorkflowManager extends EventEmitter {
         this.persistence.save({
             runId: managed.runId,
             workflowName: managed.snapshot.name,
-            script: "", // Don't persist script for security
+            // Persist the real script + journal so the run can be resumed. Runs live
+            // under .pi/workflows/runs/ — protect via directory permissions, not blanking.
+            script: managed.script,
+            args: managed.args,
+            journal: managed.journal,
             status: managed.status,
             phases: managed.snapshot.phases,
             currentPhase: managed.snapshot.currentPhase,
@@ -183,15 +201,41 @@ export class WorkflowManager extends EventEmitter {
         return true;
     }
     /**
-     * Resume a paused workflow.
+     * Resume an interrupted run: replay journaled results for the unchanged prefix
+     * and run the rest live. Returns false if there is nothing resumable.
      */
     async resume(runId) {
+        const active = this.runs.get(runId);
+        if (active?.status === "running")
+            return false; // already running
         const persisted = this.persistence.load(runId);
-        if (persisted?.status !== "paused")
+        if (!persisted?.script || persisted.status === "completed")
             return false;
-        // For now, resume creates a fresh run with completed agents' results cached
-        // Full resume would require re-executing the script with cached results
+        const controller = new AbortController();
+        const managed = {
+            runId,
+            status: "running",
+            snapshot: {
+                name: persisted.workflowName,
+                phases: persisted.phases ?? [],
+                logs: persisted.logs ?? [],
+                agents: [],
+                agentCount: 0,
+                runningCount: 0,
+                doneCount: 0,
+                errorCount: 0,
+            },
+            controller,
+            startedAt: new Date(),
+            script: persisted.script,
+            args: persisted.args,
+            journal: persisted.journal ?? [],
+        };
+        this.runs.set(runId, managed);
+        const resumeJournal = new Map((persisted.journal ?? []).map((e) => [e.index, e]));
         this.emit("resumed", { runId });
+        // Run in the background; executeRun records status/errors on the managed run.
+        void this.executeRun(managed, persisted.script, persisted.args, resumeJournal).catch(() => { });
         return true;
     }
     /**

package/dist/workflow-tool.d.ts

@@ -1,5 +1,7 @@
 import { type ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import { WorkflowManager } from "./workflow-manager.js";
+import { type WorkflowStorage } from "./workflow-saved.js";
 declare const workflowToolSchema: Type.TObject<{
     script: Type.TString;
     args: Type.TOptional<Type.TAny>;
@@ -17,6 +19,10 @@ export type WorkflowToolInput = {
 export interface WorkflowToolOptions {
     cwd?: string;
     concurrency?: number;
+    /** Shared manager so background runs are reachable from the `/workflows` command. */
+    manager?: WorkflowManager;
+    /** Shared saved-workflow storage. */
+    storage?: WorkflowStorage;
 }
 export declare function createWorkflowTool(options?: WorkflowToolOptions): ToolDefinition<typeof workflowToolSchema, any>;
 export {};

package/dist/workflow-tool.js

@@ -27,8 +27,8 @@ const workflowToolSchema = Type.Object({
     })),
 });
 export function createWorkflowTool(options = {}) {
-    const manager = new WorkflowManager({ cwd: options.cwd, concurrency: options.concurrency });
-    const _storage = createWorkflowStorage(options.cwd ?? process.cwd());
+    const manager = options.manager ?? new WorkflowManager({ cwd: options.cwd, concurrency: options.concurrency });
+    const _storage = options.storage ?? createWorkflowStorage(options.cwd ?? process.cwd());
     return defineTool({
         name: "workflow",
         label: "Workflow",
@@ -70,8 +70,8 @@ export function createWorkflowTool(options = {}) {
                             text: [
                                 `Workflow "${parsed.meta.name}" started in background.`,
                                 `Run ID: ${runId}`,
-                                `Use /workflow status ${runId} to check progress.`,
-                                `Use /workflow stop ${runId} to cancel.`,
+                                `Use /workflows status ${runId} to check progress.`,
+                                `Use /workflows stop ${runId} to cancel.`,
                             ].join("\n"),
                         },
                     ],

package/dist/workflow.d.ts

@@ -11,6 +11,13 @@ export interface WorkflowMeta {
     whenToUse?: string;
     phases?: WorkflowMetaPhase[];
 }
+/** One cached agent() result, keyed by its deterministic call index. */
+export interface JournalEntry {
+    index: number;
+    /** sha256 of the call's identity (prompt + model + phase + agentType + schema). */
+    hash: string;
+    result: unknown;
+}
 export interface WorkflowRunOptions extends WorkflowAgentOptions {
     args?: unknown;
     agent?: Pick<WorkflowAgent, "run">;
@@ -25,6 +32,12 @@ export interface WorkflowRunOptions extends WorkflowAgentOptions {
     persistLogs?: boolean;
     /** Run ID for persistence. Auto-generated if not provided. */
     runId?: string;
+    /** Resume: cached agent results keyed by deterministic call index. */
+    resumeJournal?: Map<number, JournalEntry>;
+    /** Resume: the run being resumed (informational; enables resume mode). */
+    resumeFromRunId?: string;
+    /** Called after each live agent completes so the caller can persist the journal. */
+    onAgentJournal?: (entry: JournalEntry) => void;
     onLog?: (message: string) => void;
     onPhase?: (title: string) => void;
     onAgentStart?: (event: {

package/dist/workflow.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import vm from "node:vm";
 import { parse } from "acorn";
 import { WorkflowAgent } from "./agent.js";
@@ -25,6 +26,7 @@ export async function runWorkflow(script, options = {}) {
         logs: [],
         phases: [],
         agentCount: 0,
+        callSeq: 0,
         spent: 0,
         tokenUsage: { input: 0, output: 0, total: 0, cost: 0 },
     };
@@ -67,6 +69,20 @@ export async function runWorkflow(script, options = {}) {
         const requestedLabel = agentOptions.label?.trim();
         // Precedence: explicit agentOptions.model > phase model (meta.phases[].model).
         const modelSpec = agentOptions.model ?? resolveModelForPhase(assignedPhase, routingConfig);
+        // Deterministic resume key: assigned at lexical call time, before the limiter,
+        // so parallel()/pipeline() fan-out is reproducible for a fixed script.
+        const callIndex = state.callSeq++;
+        const callHash = hashAgentCall(prompt, modelSpec, assignedPhase, agentOptions);
+        // Resume: replay a cached result for an unchanged call (matching hash), without
+        // consuming a concurrency slot, tokens, or a real subagent run.
+        const cached = options.resumeJournal?.get(callIndex);
+        if (cached && cached.hash === callHash) {
+            state.agentCount++;
+            const label = requestedLabel || defaultAgentLabel(assignedPhase, state.agentCount);
+            options.onAgentStart?.({ label, phase: assignedPhase, prompt, model: modelSpec });
+            options.onAgentEnd?.({ label, phase: assignedPhase, result: cached.result, tokens: 0 });
+            return cached.result;
+        }
         return limiter(async () => {
             state.agentCount++;
             const label = requestedLabel || defaultAgentLabel(assignedPhase, state.agentCount);
@@ -101,6 +117,7 @@ export async function runWorkflow(script, options = {}) {
                 }), timeout, `Agent "${label}" timed out after ${timeout}ms`);
                 throwIfAborted();
                 const tokens = recordTokens(result);
+                options.onAgentJournal?.({ index: callIndex, hash: callHash, result });
                 options.onAgentEnd?.({ label, phase: assignedPhase, result, tokens });
                 return result;
             }
@@ -348,6 +365,17 @@ function createLimiter(limit) {
 function defaultAgentLabel(phase, index) {
     return phase ? `${phase} agent ${index}` : `agent ${index}`;
 }
+/** Stable identity hash for an agent() call — a cache miss on resume when anything changes. */
+function hashAgentCall(prompt, model, phase, options) {
+    const identity = JSON.stringify({
+        prompt,
+        model: model ?? null,
+        phase: phase ?? null,
+        agentType: options.agentType ?? null,
+        schema: options.schema ?? null,
+    });
+    return createHash("sha256").update(identity).digest("hex");
+}
 function buildAgentInstructions(phase, options) {
     const lines = [];
     if (phase)

package/extensions/workflow.ts

@@ -1,9 +1,16 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { createWorkflowTool } from "../src/index.js";
+import { createWorkflowStorage, createWorkflowTool, registerWorkflowCommands, WorkflowManager } from "../src/index.js";
 
 export default function extension(pi: ExtensionAPI) {
-  const workflowTool = createWorkflowTool();
+  // Single manager/storage shared by the workflow tool and the /workflows command,
+  // so background runs started by the tool are reachable from the command.
+  const cwd = process.cwd();
+  const manager = new WorkflowManager({ cwd });
+  const storage = createWorkflowStorage(cwd);
+
+  const workflowTool = createWorkflowTool({ cwd, manager, storage });
   pi.registerTool(workflowTool);
+  registerWorkflowCommands(pi, manager);
 
   pi.on("session_start", () => {
     const active = pi.getActiveTools();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quintinshaw/pi-dynamic-workflows",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Claude-Code-style dynamic workflow orchestration for Pi.",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts

@@ -47,6 +47,7 @@ export type {
   WorkflowRunResult,
 } from "./workflow.js";
 export { parseWorkflowScript, runWorkflow } from "./workflow.js";
+export { registerWorkflowCommands } from "./workflow-commands.js";
 export type { ManagedRun, WorkflowManagerOptions } from "./workflow-manager.js";
 export { WorkflowManager } from "./workflow-manager.js";
 export type { SavedWorkflow, WorkflowStorage } from "./workflow-saved.js";

package/src/run-persistence.ts

@@ -40,6 +40,8 @@ export interface PersistedRunState {
     output: number;
     total: number;
   };
+  /** Cached agent results for resume, keyed by deterministic call index. */
+  journal?: Array<{ index: number; hash: string; result: unknown }>;
 }
 
 export interface RunPersistence {

package/src/workflow-commands.ts

@@ -0,0 +1,117 @@
+/**
+ * `/workflows` slash command: list, inspect, and control background workflow runs.
+ * Shares the extension's single WorkflowManager so background runs are reachable.
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { renderWorkflowText } from "./display.js";
+import type { PersistedRunState } from "./run-persistence.js";
+import type { WorkflowManager } from "./workflow-manager.js";
+
+const STATUS_ICON: Record<string, string> = {
+  pending: "·",
+  running: "◆",
+  paused: "⏸",
+  completed: "✓",
+  failed: "✗",
+  aborted: "⊘",
+};
+
+const USAGE = "Usage: /workflows [list] | status <id> | stop <id> | pause <id> | resume <id> | rm <id>";
+
+function summarizeRun(run: PersistedRunState): string {
+  const icon = STATUS_ICON[run.status] ?? "?";
+  const done = run.agents.filter((a) => a.status === "done").length;
+  const total = run.agents.length;
+  const tokens = run.tokenUsage ? ` · ${run.tokenUsage.total.toLocaleString()} tok` : "";
+  return `${icon} ${run.runId}  ${run.workflowName} [${run.status}] ${done}/${total} agents${tokens}`;
+}
+
+function renderPersistedStatus(run: PersistedRunState): string {
+  const lines = [`${STATUS_ICON[run.status] ?? "?"} ${run.workflowName} (${run.runId}) — ${run.status}`];
+  if (run.currentPhase) lines.push(`  phase: ${run.currentPhase}`);
+  for (const agent of run.agents) {
+    const icon =
+      agent.status === "done" ? "✓" : agent.status === "error" ? "✗" : agent.status === "running" ? "◆" : "·";
+    lines.push(`  ${icon} ${agent.label}`);
+  }
+  if (run.tokenUsage) lines.push(`  tokens: ${run.tokenUsage.total.toLocaleString()}`);
+  if (run.durationMs) lines.push(`  duration: ${(run.durationMs / 1000).toFixed(1)}s`);
+  return lines.join("\n");
+}
+
+/** Register the `/workflows` command against the shared manager. Idempotent. */
+export function registerWorkflowCommands(pi: ExtensionAPI, manager: WorkflowManager): void {
+  try {
+    const taken = (pi.getCommands?.() ?? []).some((c: { name: string }) => c.name === "workflows");
+    if (taken) return;
+  } catch {
+    // getCommands may be unavailable in some hosts; fall through and try to register.
+  }
+
+  pi.registerCommand("workflows", {
+    description: "List and control background workflow runs",
+    async handler(args: string, ctx: ExtensionCommandContext) {
+      const parts = args.trim().split(/\s+/).filter(Boolean);
+      const sub = (parts[0] ?? "list").toLowerCase();
+      const id = parts[1];
+      const print = (text: string) => pi.sendMessage({ customType: "workflows", content: text, display: true });
+
+      switch (sub) {
+        case "list": {
+          const runs = manager.listRuns();
+          if (!runs.length) {
+            await print("No workflow runs yet. Start one with a background workflow (background: true).");
+            return;
+          }
+          await print(["Workflow runs:", ...runs.map(summarizeRun), "", USAGE].join("\n"));
+          return;
+        }
+        case "status": {
+          if (!id) {
+            ctx.ui.notify(USAGE, "warning");
+            return;
+          }
+          const live = manager.getSnapshot(id);
+          if (live) {
+            await print(renderWorkflowText(live, false));
+            return;
+          }
+          const run = manager.listRuns().find((r) => r.runId === id);
+          if (!run) {
+            ctx.ui.notify(`No workflow run "${id}"`, "error");
+            return;
+          }
+          await print(renderPersistedStatus(run));
+          return;
+        }
+        case "stop": {
+          if (!id) return ctx.ui.notify(USAGE, "warning");
+          ctx.ui.notify(
+            manager.stop(id) ? `Stopped ${id}` : `Cannot stop ${id} (not running)`,
+            manager.getRun(id) ? "info" : "warning",
+          );
+          return;
+        }
+        case "pause": {
+          if (!id) return ctx.ui.notify(USAGE, "warning");
+          ctx.ui.notify(manager.pause(id) ? `Paused ${id}` : `Cannot pause ${id} (not running)`, "info");
+          return;
+        }
+        case "resume": {
+          if (!id) return ctx.ui.notify(USAGE, "warning");
+          const ok = await manager.resume(id);
+          ctx.ui.notify(ok ? `Resumed ${id}` : `Resume not available for ${id} yet`, ok ? "info" : "warning");
+          return;
+        }
+        case "rm": {
+          if (!id) return ctx.ui.notify(USAGE, "warning");
+          ctx.ui.notify(manager.deleteRun(id) ? `Removed ${id}` : `No run ${id}`, "info");
+          return;
+        }
+        default:
+          ctx.ui.notify(`Unknown subcommand "${sub}". ${USAGE}`, "warning");
+      }
+    },
+  });
+}

package/src/workflow-manager.ts

@@ -12,7 +12,7 @@ import {
   type RunPersistence,
   type RunStatus,
 } from "./run-persistence.js";
-import { parseWorkflowScript, runWorkflow, type WorkflowRunResult } from "./workflow.js";
+import { type JournalEntry, parseWorkflowScript, runWorkflow, type WorkflowRunResult } from "./workflow.js";
 
 export interface ManagedRun {
   runId: string;
@@ -22,6 +22,11 @@ export interface ManagedRun {
   error?: WorkflowError;
   controller: AbortController;
   startedAt: Date;
+  /** The real script, kept so the run can be resumed. */
+  script: string;
+  args?: unknown;
+  /** Accumulated agent results for resume (deterministic call index -> result). */
+  journal: JournalEntry[];
 }
 
 export interface WorkflowManagerOptions {
@@ -67,6 +72,9 @@ export class WorkflowManager extends EventEmitter {
       },
       controller,
       startedAt: new Date(),
+      script,
+      args,
+      journal: [],
     };
 
     this.runs.set(runId, managed);
@@ -115,19 +123,35 @@ export class WorkflowManager extends EventEmitter {
       },
       controller,
       startedAt: new Date(),
+      script,
+      args,
+      journal: [],
     };
 
     this.runs.set(runId, managed);
     return this.executeRun(managed, script, args);
   }
 
-  private async executeRun(managed: ManagedRun, script: string, args?: unknown): Promise<WorkflowRunResult> {
+  private async executeRun(
+    managed: ManagedRun,
+    script: string,
+    args?: unknown,
+    resumeJournal?: Map<number, JournalEntry>,
+  ): Promise<WorkflowRunResult> {
     try {
       const result = await runWorkflow(script, {
         cwd: this.cwd,
         args,
         signal: managed.controller.signal,
         concurrency: this.concurrency,
+        resumeJournal,
+        resumeFromRunId: resumeJournal ? managed.runId : undefined,
+        onAgentJournal: (entry) => {
+          // Append (crash-safe-ish): keep the latest entry per index, then persist.
+          managed.journal = managed.journal.filter((e) => e.index !== entry.index);
+          managed.journal.push(entry);
+          this.persistRun(managed);
+        },
         onLog: (message) => {
           managed.snapshot.logs.push(message);
           this.emit("log", { runId: managed.runId, message });
@@ -197,7 +221,11 @@ export class WorkflowManager extends EventEmitter {
     this.persistence.save({
       runId: managed.runId,
       workflowName: managed.snapshot.name,
-      script: "", // Don't persist script for security
+      // Persist the real script + journal so the run can be resumed. Runs live
+      // under .pi/workflows/runs/ — protect via directory permissions, not blanking.
+      script: managed.script,
+      args: managed.args,
+      journal: managed.journal,
       status: managed.status,
       phases: managed.snapshot.phases,
       currentPhase: managed.snapshot.currentPhase,
@@ -230,15 +258,42 @@ export class WorkflowManager extends EventEmitter {
   }
 
   /**
-   * Resume a paused workflow.
+   * Resume an interrupted run: replay journaled results for the unchanged prefix
+   * and run the rest live. Returns false if there is nothing resumable.
    */
   async resume(runId: string): Promise<boolean> {
+    const active = this.runs.get(runId);
+    if (active?.status === "running") return false; // already running
+
     const persisted = this.persistence.load(runId);
-    if (persisted?.status !== "paused") return false;
+    if (!persisted?.script || persisted.status === "completed") return false;
+
+    const controller = new AbortController();
+    const managed: ManagedRun = {
+      runId,
+      status: "running",
+      snapshot: {
+        name: persisted.workflowName,
+        phases: persisted.phases ?? [],
+        logs: persisted.logs ?? [],
+        agents: [],
+        agentCount: 0,
+        runningCount: 0,
+        doneCount: 0,
+        errorCount: 0,
+      },
+      controller,
+      startedAt: new Date(),
+      script: persisted.script,
+      args: persisted.args,
+      journal: persisted.journal ?? [],
+    };
+    this.runs.set(runId, managed);
 
-    // For now, resume creates a fresh run with completed agents' results cached
-    // Full resume would require re-executing the script with cached results
+    const resumeJournal = new Map((persisted.journal ?? []).map((e) => [e.index, e] as const));
     this.emit("resumed", { runId });
+    // Run in the background; executeRun records status/errors on the managed run.
+    void this.executeRun(managed, persisted.script, persisted.args, resumeJournal).catch(() => {});
     return true;
   }
 

package/src/workflow-tool.ts

@@ -12,7 +12,7 @@ import {
 import { WorkflowError, WorkflowErrorCode } from "./errors.js";
 import { parseWorkflowScript, runWorkflow, type WorkflowRunResult } from "./workflow.js";
 import { WorkflowManager } from "./workflow-manager.js";
-import { createWorkflowStorage } from "./workflow-saved.js";
+import { createWorkflowStorage, type WorkflowStorage } from "./workflow-saved.js";
 
 const workflowToolSchema = Type.Object({
   script: Type.String({
@@ -54,11 +54,15 @@ export type WorkflowToolInput = {
 export interface WorkflowToolOptions {
   cwd?: string;
   concurrency?: number;
+  /** Shared manager so background runs are reachable from the `/workflows` command. */
+  manager?: WorkflowManager;
+  /** Shared saved-workflow storage. */
+  storage?: WorkflowStorage;
 }
 
 export function createWorkflowTool(options: WorkflowToolOptions = {}): ToolDefinition<typeof workflowToolSchema, any> {
-  const manager = new WorkflowManager({ cwd: options.cwd, concurrency: options.concurrency });
-  const _storage = createWorkflowStorage(options.cwd ?? process.cwd());
+  const manager = options.manager ?? new WorkflowManager({ cwd: options.cwd, concurrency: options.concurrency });
+  const _storage = options.storage ?? createWorkflowStorage(options.cwd ?? process.cwd());
 
   return defineTool({
     name: "workflow",
@@ -103,8 +107,8 @@ export function createWorkflowTool(options: WorkflowToolOptions = {}): ToolDefin
               text: [
                 `Workflow "${parsed.meta.name}" started in background.`,
                 `Run ID: ${runId}`,
-                `Use /workflow status ${runId} to check progress.`,
-                `Use /workflow stop ${runId} to cancel.`,
+                `Use /workflows status ${runId} to check progress.`,
+                `Use /workflows stop ${runId} to cancel.`,
               ].join("\n"),
             },
           ],

package/src/workflow.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import vm from "node:vm";
 import type { Node } from "acorn";
 import { parse } from "acorn";
@@ -22,6 +23,14 @@ export interface WorkflowMeta {
   phases?: WorkflowMetaPhase[];
 }
 
+/** One cached agent() result, keyed by its deterministic call index. */
+export interface JournalEntry {
+  index: number;
+  /** sha256 of the call's identity (prompt + model + phase + agentType + schema). */
+  hash: string;
+  result: unknown;
+}
+
 export interface WorkflowRunOptions extends WorkflowAgentOptions {
   args?: unknown;
   agent?: Pick<WorkflowAgent, "run">;
@@ -36,6 +45,12 @@ export interface WorkflowRunOptions extends WorkflowAgentOptions {
   persistLogs?: boolean;
   /** Run ID for persistence. Auto-generated if not provided. */
   runId?: string;
+  /** Resume: cached agent results keyed by deterministic call index. */
+  resumeJournal?: Map<number, JournalEntry>;
+  /** Resume: the run being resumed (informational; enables resume mode). */
+  resumeFromRunId?: string;
+  /** Called after each live agent completes so the caller can persist the journal. */
+  onAgentJournal?: (entry: JournalEntry) => void;
   onLog?: (message: string) => void;
   onPhase?: (title: string) => void;
   onAgentStart?: (event: { label: string; phase?: string; prompt: string; model?: string }) => void;
@@ -75,6 +90,8 @@ interface RuntimeState {
   logs: string[];
   phases: string[];
   agentCount: number;
+  /** Monotonic, assigned at lexical agent() call time — the stable resume key. */
+  callSeq: number;
   spent: number;
   tokenUsage: {
     input: number;
@@ -112,6 +129,7 @@ export async function runWorkflow<T = unknown>(
     logs: [],
     phases: [],
     agentCount: 0,
+    callSeq: 0,
     spent: 0,
     tokenUsage: { input: 0, output: 0, total: 0, cost: 0 },
   };
@@ -170,6 +188,22 @@ export async function runWorkflow<T = unknown>(
     // Precedence: explicit agentOptions.model > phase model (meta.phases[].model).
     const modelSpec = agentOptions.model ?? resolveModelForPhase(assignedPhase, routingConfig);
 
+    // Deterministic resume key: assigned at lexical call time, before the limiter,
+    // so parallel()/pipeline() fan-out is reproducible for a fixed script.
+    const callIndex = state.callSeq++;
+    const callHash = hashAgentCall(prompt, modelSpec, assignedPhase, agentOptions);
+
+    // Resume: replay a cached result for an unchanged call (matching hash), without
+    // consuming a concurrency slot, tokens, or a real subagent run.
+    const cached = options.resumeJournal?.get(callIndex);
+    if (cached && cached.hash === callHash) {
+      state.agentCount++;
+      const label = requestedLabel || defaultAgentLabel(assignedPhase, state.agentCount);
+      options.onAgentStart?.({ label, phase: assignedPhase, prompt, model: modelSpec });
+      options.onAgentEnd?.({ label, phase: assignedPhase, result: cached.result, tokens: 0 });
+      return cached.result;
+    }
+
     return limiter(async () => {
       state.agentCount++;
       const label = requestedLabel || defaultAgentLabel(assignedPhase, state.agentCount);
@@ -214,6 +248,7 @@ export async function runWorkflow<T = unknown>(
         throwIfAborted();
 
         const tokens = recordTokens(result);
+        options.onAgentJournal?.({ index: callIndex, hash: callHash, result });
         options.onAgentEnd?.({ label, phase: assignedPhase, result, tokens });
         return result;
       } catch (error) {
@@ -481,6 +516,23 @@ function defaultAgentLabel(phase: string | undefined, index: number): string {
   return phase ? `${phase} agent ${index}` : `agent ${index}`;
 }
 
+/** Stable identity hash for an agent() call — a cache miss on resume when anything changes. */
+function hashAgentCall(
+  prompt: string,
+  model: string | undefined,
+  phase: string | undefined,
+  options: AgentOptions,
+): string {
+  const identity = JSON.stringify({
+    prompt,
+    model: model ?? null,
+    phase: phase ?? null,
+    agentType: options.agentType ?? null,
+    schema: options.schema ?? null,
+  });
+  return createHash("sha256").update(identity).digest("hex");
+}
+
 function buildAgentInstructions(phase: string | undefined, options: AgentOptions): string | undefined {
   const lines = [];
   if (phase) lines.push(`Workflow phase: ${phase}`);