@osolmaz/pi-workflows 0.1.0 → 0.3.0

package/dist/extension/index.js

@@ -1,15 +1,25 @@
-import { Type } from "typebox";
+import { randomUUID } from "node:crypto";
+import { projectControllerStorePath, SqliteControllerStore, } from "../controllers/index.js";
 import { WorkflowEngine } from "../workflows/engine.js";
-import { errorMessage } from "../workflows/errors.js";
-import { discoverWorkflows, loadWorkflowFile, resolveWorkflowRef } from "../workflows/loader.js";
-import { createDefinitionSnapshot } from "../workflows/store.js";
+import { ClaimLostError, errorMessage, isClaimLostError } from "../workflows/errors.js";
+import { discoverWorkflows, hashWorkflowSource, loadWorkflowFile, resolveWorkflowRef, } from "../workflows/loader.js";
+import { createRunId, listRunBundles, readLastTraceEvent, readRunBundle, WorkflowRunStore, createDefinitionSnapshot, } from "../workflows/store.js";
+import { PiControllerHost, parseControllerArgs, } from "./controller-host.js";
 import { ConversationStepExecutor } from "./executor.js";
+import { SessionRecorder } from "./recorder.js";
 import { buildWidgetView } from "./widget.js";
+import { WorkflowToolParameters } from "./workflow-tool.js";
+const RUN_CLAIM_LEASE_MS = 30_000;
+const RUN_CLAIM_RENEW_MS = 10_000;
+const RUN_SYNC_POLL_MS = 3_000;
 const WIDGET_KEY = "pi-workflows";
 const PRESENTATION_MESSAGE_TYPE = "pi-workflows-presentation";
 const FINAL_WIDGET_TTL_MS = 60_000;
 const WIDGET_SCROLL_STEP = 3;
 const MAX_PRESENTATION_RESULT_CHARS = 50_000;
+const MAX_STATUS_ERROR_CHARS = 4_000;
+const MAX_WORKFLOW_LIST_ITEMS = 50;
+const MAX_WORKFLOW_LIST_NAME_CHARS = 3_500;
 const PRESENTATION_TIMEOUT_MS = 30_000;
 class PresentationSupersededError extends Error {
 }
@@ -24,6 +34,49 @@ export function parseWorkflowArgs(args) {
     if (trimmed === "cancel" || trimmed === "pause" || trimmed === "resume") {
         return { kind: trimmed };
     }
+    if (trimmed === "status") {
+        return { kind: "status" };
+    }
+    if (trimmed.startsWith("status ")) {
+        const runId = trimmed.slice("status".length).trim();
+        if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/.test(runId)) {
+            throw new Error("status requires one valid run id");
+        }
+        return { kind: "status", runId };
+    }
+    if (trimmed === "answer" || trimmed.startsWith("answer ")) {
+        let rest = trimmed === "answer" ? "" : trimmed.slice("answer".length).trim();
+        if (rest.length === 0) {
+            throw new Error('answer requires a JSON value or text, e.g. /workflow answer {"approved":true}');
+        }
+        // `/workflow answer <run-id> <json>` targets a specific waiting run,
+        // for example after a restart or for host-driven runs.
+        let runId;
+        const firstSpace = rest.search(/\s/);
+        if (firstSpace > 0) {
+            const candidate = rest.slice(0, firstSpace);
+            const remainder = rest.slice(firstSpace).trim();
+            if (/^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/.test(candidate) &&
+                remainder.length > 0 &&
+                (remainder.startsWith("{") || remainder.startsWith("["))) {
+                runId = candidate;
+                rest = remainder;
+            }
+        }
+        try {
+            return {
+                kind: "answer",
+                input: JSON.parse(rest),
+                ...(runId !== undefined ? { runId } : {}),
+            };
+        }
+        catch {
+            if (runId !== undefined) {
+                throw new Error("answer with a run id requires a JSON value");
+            }
+            return { kind: "answer", input: { answer: rest } };
+        }
+    }
     const spaceIndex = trimmed.search(/\s/);
     const ref = spaceIndex === -1 ? trimmed : trimmed.slice(0, spaceIndex);
     const rest = spaceIndex === -1 ? "" : trimmed.slice(spaceIndex).trim();
@@ -39,8 +92,146 @@ export function parseWorkflowArgs(args) {
     }
     return { kind: "run", ref, input: rest.length > 0 ? { task: rest } : {} };
 }
+function workflowStateSummary(state) {
+    const error = state.error === undefined
+        ? undefined
+        : state.error.length <= MAX_STATUS_ERROR_CHARS
+            ? state.error
+            : `${state.error.slice(0, MAX_STATUS_ERROR_CHARS)}\n… [error truncated]`;
+    return {
+        active: state.status === "running",
+        runId: state.runId,
+        workflowName: state.workflowName,
+        status: state.status,
+        steps: state.steps.length,
+        ...(state.currentNode !== undefined ? { currentNode: state.currentNode } : {}),
+        ...(state.waitingOn !== undefined ? { waitingOn: state.waitingOn } : {}),
+        ...(state.startedAt !== undefined ? { startedAt: state.startedAt } : {}),
+        ...(state.finishedAt !== undefined ? { finishedAt: state.finishedAt } : {}),
+        ...(error !== undefined ? { error } : {}),
+    };
+}
 export default function piWorkflows(pi) {
+    // One runner identity per session; it names this session in run claims.
+    const runnerId = randomUUID();
+    let runQueueStore = null;
+    const ensureRunQueueStore = (cwd) => {
+        runQueueStore ??= new SqliteControllerStore(projectControllerStorePath(cwd));
+        return runQueueStore;
+    };
+    // Session sync: a per-session watermark over the run event feed keeps this
+    // session's context current with runs other runners drove.
+    // The sync watermark is project-scoped: a reopened session catches up
+    // where the last one stopped, and two open sessions share one pointer.
+    const SYNC_WATERMARK_KEY = "project";
+    let syncArmed = false;
+    let runSyncTimer = null;
+    const recordRunEvent = (event) => {
+        try {
+            runQueueStore?.recordRunEvent({ ...event, runnerId });
+        }
+        catch {
+            // The event feed is best-effort; never fail a run for it.
+        }
+    };
+    const describeRunEvent = (event) => {
+        const label = `${event.workflowRef} run ${event.runId}`;
+        switch (event.type) {
+            case "waiting": {
+                const waitingOn = typeof event.payload.waitingOn === "string" ? event.payload.waitingOn : "a checkpoint";
+                return `${label} waits at checkpoint ${waitingOn} — answer with /workflow answer`;
+            }
+            case "parked":
+                return `${label} was parked and will resume when a runner is available`;
+            case "failed": {
+                const detail = typeof event.payload.error === "string" ? `: ${event.payload.error}` : "";
+                return `${label} failed${detail}`;
+            }
+            default:
+                return `${label} ${event.type}`;
+        }
+    };
+    const runSyncPass = async (ctx) => {
+        if (runQueueStore === null || !syncArmed) {
+            return;
+        }
+        try {
+            const watermark = runQueueStore.getSessionWatermark(SYNC_WATERMARK_KEY);
+            if (watermark === 0) {
+                // First sync ever for this project: never replay the feed (stale
+                // "waits at checkpoint" lines included). Fast-forward, then catch
+                // up from current state instead — what is parked, resuming, or
+                // waiting for an answer right now.
+                const latest = runQueueStore.latestRunEventSeq();
+                if (latest > 0) {
+                    runQueueStore.setSessionWatermark(SYNC_WATERMARK_KEY, latest);
+                }
+                await sendStateSnapshot(ctx);
+                return;
+            }
+            const events = runQueueStore.listRunEventsAfter(watermark, { limit: 20 });
+            if (events.length === 0) {
+                return;
+            }
+            // Persist the watermark first. A crash after this point skips the
+            // message, but snapshots recompute from the store, so no information
+            // stays lost; a duplicated state line is the worst outcome.
+            runQueueStore.setSessionWatermark(SYNC_WATERMARK_KEY, events[events.length - 1]?.seq ?? 0);
+            const noteworthy = events.filter((event) => event.runnerId !== runnerId &&
+                ["completed", "failed", "timed_out", "cancelled", "waiting", "parked"].includes(event.type));
+            if (noteworthy.length === 0) {
+                return;
+            }
+            const content = `Workflow run update:\n${noteworthy.map(describeRunEvent).join("\n")}`;
+            pi.sendMessage({ customType: "pi-workflows-run-sync", content, display: false }, { deliverAs: "steer", triggerTurn: false });
+            notify(ctx, noteworthy.map(describeRunEvent).join("; "));
+        }
+        catch {
+            // Sync is observational.
+        }
+    };
+    // The first-use catch-up: a snapshot of runs that need attention now.
+    const sendStateSnapshot = async (ctx) => {
+        if (runQueueStore === null) {
+            return;
+        }
+        const lines = [];
+        const rows = runQueueStore.listWorkflowRuns();
+        for (const row of rows) {
+            if (row.status === "parked") {
+                lines.push(`${row.workflowRef} run ${row.runId} is parked and will resume`);
+            }
+        }
+        const known = new Set(rows.map((row) => row.runId));
+        const continued = new Set(rows.map((row) => row.parentRunId).filter((parent) => parent !== null));
+        const bundles = await listRunBundles(new WorkflowRunStore().outputRoot);
+        for (const bundle of bundles) {
+            if (bundle.state.status === "waiting" &&
+                known.has(bundle.state.runId) &&
+                !continued.has(bundle.state.runId)) {
+                lines.push(`${bundle.state.workflowName} run ${bundle.state.runId} waits at checkpoint ${bundle.state.waitingOn ?? "?"} — answer with /workflow answer`);
+            }
+        }
+        if (lines.length === 0) {
+            return;
+        }
+        const content = `Workflow runs needing attention:\n${lines.join("\n")}`;
+        pi.sendMessage({ customType: "pi-workflows-run-sync", content, display: false }, { deliverAs: "steer", triggerTurn: false });
+        notify(ctx, lines.join("; "));
+    };
+    const startRunSync = (ctx) => {
+        if (runSyncTimer !== null) {
+            return;
+        }
+        ensureRunQueueStore(ctx.cwd);
+        void runSyncPass(ctx);
+        runSyncTimer = setInterval(() => void runSyncPass(ctx), RUN_SYNC_POLL_MS);
+        runSyncTimer.unref?.();
+    };
     let activeRun = null;
+    let pendingToolLaunch = null;
+    // The interactive run currently parked at a checkpoint, if any.
+    let lastWaitingRunId = null;
     let widgetTimer = null;
     let widgetTicker = null;
     // Manual widget scroll: null follows the active node; a number is the
@@ -54,6 +245,8 @@ export default function piWorkflows(pi) {
     let runGeneration = 0;
     let presentationAbort = null;
     let presentationPending = null;
+    let controllerHost;
+    let controllerContext = null;
     // UI updates are best-effort: a captured ctx becomes stale after session
     // replacement or shutdown, and pi throws on any access (even `ctx.hasUI`).
     // A workflow finishing right as the session goes away must not crash pi.
@@ -210,10 +403,61 @@ export default function piWorkflows(pi) {
             }
         }
     };
-    const finishRun = (ctx, run, result) => {
+    // Release the queue claim exactly once. "done" marks the queue row
+    // terminal, "park" leaves it claimable for another runner, and "lost"
+    // leaves it for the new claim holder.
+    const releaseClaim = (run, outcome) => {
+        if (run.renewTimer !== undefined) {
+            clearInterval(run.renewTimer);
+            run.renewTimer = undefined;
+        }
+        if (run.claimToken === undefined || runQueueStore === null || outcome === "lost") {
+            return;
+        }
+        try {
+            if (outcome === "park") {
+                runQueueStore.parkWorkflowRun({ runId: run.runId, claimToken: run.claimToken });
+            }
+            else {
+                runQueueStore.completeWorkflowRun({ runId: run.runId, claimToken: run.claimToken });
+            }
+        }
+        catch {
+            // Queue bookkeeping is best-effort next to the durable bundle.
+        }
+        finally {
+            run.claimToken = undefined;
+        }
+    };
+    const finishRun = async (ctx, run, result) => {
         if (activeRun === run) {
             activeRun = null;
         }
+        if (result.state.status === "running") {
+            // The run was parked for another runner; its bundle stays resumable
+            // and its queue row becomes claimable. The recorder drains first: its
+            // finalization writes share the fenced store, so the claim must stay
+            // valid until capture is complete. Nothing else to present.
+            await run.recorder?.stop().catch(() => undefined);
+            releaseClaim(run, "park");
+            recordRunEvent({ runId: run.runId, workflowRef: run.workflowName, type: "parked" });
+            stopWidgetTicker();
+            clearWidget(ctx);
+            return;
+        }
+        releaseClaim(run, "done");
+        recordRunEvent({
+            runId: run.runId,
+            workflowRef: run.workflowName,
+            type: result.state.status,
+            payload: {
+                ...(result.state.error !== undefined ? { error: result.state.error } : {}),
+                ...(result.state.waitingOn !== undefined ? { waitingOn: result.state.waitingOn } : {}),
+            },
+        });
+        // Normally already stopped via onRunFinishing; this covers observers of
+        // runs that ended without reaching that hook.
+        void run.recorder?.stop();
         stopWidgetTicker();
         const { state } = result;
         updateWidget(ctx, state, run.snapshot);
@@ -224,85 +468,669 @@ export default function piWorkflows(pi) {
             widgetTimer = setTimeout(() => clearWidget(ctx), FINAL_WIDGET_TTL_MS);
             widgetTimer.unref?.();
         }
+        if (state.status === "waiting" && run.childKey === undefined) {
+            lastWaitingRunId = run.runId;
+        }
         const summary = state.status === "waiting" && state.waitingOn
-            ? `Workflow ${state.workflowName} parked at checkpoint ${state.waitingOn} — run ended, awaiting your decision (run ${state.runId})`
+            ? `Workflow ${state.workflowName} parked at checkpoint ${state.waitingOn} — answer with /workflow answer <json> (run ${state.runId})`
             : `Workflow ${state.workflowName} ${state.status} (run ${state.runId})`;
         notify(ctx, summary, state.status === "completed" ? "info" : "warning");
+        try {
+            const childResult = run.childKey !== undefined &&
+                (sessionClosed || run.interruptionRequested === true) &&
+                state.status === "cancelled"
+                ? {
+                    state: "interrupted",
+                    runId: state.runId,
+                    ...(state.error !== undefined ? { error: state.error } : {}),
+                }
+                : workflowSchedulerResult(state);
+            run.onFinish?.(childResult);
+        }
+        catch (error) {
+            notify(ctx, `Could not record child workflow completion: ${errorMessage(error)}`, "warning");
+        }
         void presentRun(ctx, run, state);
     };
-    const startRun = async (ctx, ref, input) => {
+    const startRun = async (ctx, ref, input, options = {}) => {
+        if (options.signal?.aborted) {
+            throw options.signal.reason ?? new Error("Workflow startup aborted");
+        }
         if (activeRun) {
-            notify(ctx, `A workflow is already running: ${activeRun.workflowName}. Use /workflow cancel first.`, "error");
-            return;
+            if (!options.quiet) {
+                notify(ctx, `A workflow is already running: ${activeRun.workflowName}. Use /workflow cancel first.`, "error");
+            }
+            return undefined;
         }
         if (presentationPending !== null) {
-            notify(ctx, "The previous workflow result is still being presented. Wait for it to finish.");
-            return;
+            if (!options.quiet) {
+                notify(ctx, "The previous workflow result is still being presented. Wait for it to finish.");
+            }
+            return undefined;
         }
         supersedePresentation();
         const generation = runGeneration;
         const resolved = await resolveWorkflowRef(ref, { cwd: ctx.cwd });
         const workflow = await loadWorkflowFile(resolved.path);
+        if (options.signal?.aborted) {
+            throw options.signal.reason ?? new Error("Workflow startup aborted");
+        }
         const snapshot = createDefinitionSnapshot(workflow);
+        const workflowHash = await hashWorkflowSource(resolved.path);
+        const runId = options.runId ?? createRunId(workflow.name);
+        // Continuations validate the parent before touching the queue: a
+        // refused continuation (edited source, missing parent) must not consume
+        // the parent's one-continuation slot.
+        if (options.parentRunId !== undefined) {
+            const parent = await readRunBundle(new WorkflowRunStore().runDirFor(options.parentRunId));
+            if (parent === null || parent.state.status !== "waiting") {
+                throw new Error(`Workflow run ${options.parentRunId} is not waiting at a checkpoint`);
+            }
+            if (parent.state.workflowHash !== undefined && parent.state.workflowHash !== workflowHash) {
+                throw new Error(`Workflow source changed since run ${options.parentRunId} started; revert the edit to answer its checkpoint`);
+            }
+        }
+        // Interactive runs are queued and claimed atomically, so this session
+        // owns the run from birth (origin affinity). Controller child runs keep
+        // their own scheduling and stay out of the run queue. A resume caller
+        // arrives with its claim already taken.
+        let claimToken = options.claimToken;
+        let queueStore = null;
+        if (options.childKey === undefined) {
+            queueStore = ensureRunQueueStore(ctx.cwd);
+            if (claimToken === undefined) {
+                const token = randomUUID();
+                queueStore.enqueueWorkflowRun({
+                    runId,
+                    workflowRef: ref,
+                    workflowPath: resolved.path,
+                    input,
+                    runnerId,
+                    claimToken: token,
+                    leaseMs: RUN_CLAIM_LEASE_MS,
+                    ...(options.parentRunId !== undefined ? { parentRunId: options.parentRunId } : {}),
+                });
+                claimToken = token;
+                recordRunEvent({
+                    runId,
+                    workflowRef: ref,
+                    type: "queued",
+                    payload: options.parentRunId !== undefined ? { parentRunId: options.parentRunId } : {},
+                });
+            }
+        }
+        let fence;
+        if (queueStore !== null && claimToken !== undefined) {
+            const claimedStore = queueStore;
+            const token = claimToken;
+            fence = () => {
+                if (!claimedStore.verifyWorkflowRunClaim({ runId, claimToken: token })) {
+                    throw new ClaimLostError(runId);
+                }
+            };
+        }
         const executor = new ConversationStepExecutor({
             sendPrompt: ({ prompt, streaming }) => {
                 pi.sendUserMessage(prompt, streaming ? { deliverAs: "steer" } : undefined);
             },
+            conversation: {
+                beginAttempt: (contract) => run.recorder?.beginAttempt(contract),
+                mark: () => run.recorder?.mark() ?? 0,
+                rangeSince: (mark) => run.recorder?.rangeSince(mark),
+            },
         });
+        // The store is shared between the engine and the session recorder so the
+        // trace sequence stays single-writer (see docs/run-bundles.md). Queued
+        // runs are fenced: every write proves the claim is still ours first.
+        const store = new WorkflowRunStore(undefined, fence === undefined ? {} : { fenceProvider: () => fence });
         const engine = new WorkflowEngine({
             executor,
-            onEvent: (_event, state) => {
-                if (run.runId === null) {
-                    run.runId = state.runId;
+            store,
+            // Awaited by the engine after run_started is persisted, so the session
+            // binding and its trace event always precede node and terminal events.
+            onRunStarted: async (runDir, state) => {
+                const recorder = new SessionRecorder(store, runDir, state.runId);
+                try {
+                    await recorder.bind(ctx);
+                    run.recorder = recorder;
+                }
+                catch {
+                    // Binding is best-effort: a session without UI access or an
+                    // ephemeral context must not fail the run.
                 }
+            },
+            // Awaited by the engine before the terminal snapshot. If completion was
+            // submitted from the workflow tool, capture stays open through Pi's
+            // final tool, message, and turn hooks before it drains.
+            onRunFinishing: async () => {
+                await run.recorder?.finish();
+            },
+            onEvent: (_event, state) => {
                 run.lastState = state;
                 updateWidget(ctx, state, snapshot);
             },
         });
         const run = {
-            runId: null,
+            runId,
             workflowName: workflow.name,
             engine,
             executor,
+            recorder: null,
             snapshot,
-            presentationPrompt: workflow.presentationPrompt,
+            presentationPrompt: options.presentation === false ? undefined : workflow.presentationPrompt,
             generation,
             lastState: null,
+            ...(options.childKey !== undefined ? { childKey: options.childKey } : {}),
+            ...(options.onFinish !== undefined ? { onFinish: options.onFinish } : {}),
+            ...(claimToken !== undefined ? { claimToken } : {}),
+            ...(options.resume === true ? { resume: true } : {}),
+            ...(options.parentRunId !== undefined ? { parentRunId: options.parentRunId } : {}),
         };
         activeRun = run;
+        if (queueStore !== null && claimToken !== undefined) {
+            const store = queueStore;
+            const token = claimToken;
+            // Renew the claim while the run executes. If renewal says the claim is
+            // gone, cancel so the fence trips on the next write instead of letting
+            // this runner interleave with the new claim holder.
+            run.renewTimer = setInterval(() => {
+                try {
+                    if (!store.renewWorkflowRunClaim({ runId, claimToken: token, leaseMs: RUN_CLAIM_LEASE_MS })) {
+                        run.engine.cancel();
+                    }
+                }
+                catch {
+                    // Transient store errors leave fencing to decide ownership.
+                }
+            }, RUN_CLAIM_RENEW_MS);
+            run.renewTimer.unref?.();
+        }
         clearWidgetTimer();
         startWidgetTicker(ctx, run);
-        notify(ctx, `Workflow ${workflow.name} started. Follow it live with: pi-workflows view`);
-        engine
-            .run(workflow, input, { workflowPath: resolved.path })
+        if (!options.quiet) {
+            notify(ctx, `Workflow ${workflow.name} started. Follow it live with: pi-workflows view`);
+        }
+        run.completion = (options.resume === true
+            ? engine.resumeRun(workflow, runId, { workflowHash })
+            : options.parentRunId === undefined
+                ? engine.run(workflow, input, { workflowPath: resolved.path, workflowHash, runId })
+                : engine.continueRun(workflow, options.parentRunId, input, {
+                    workflowPath: resolved.path,
+                    workflowHash,
+                    runId,
+                }))
             .then((result) => finishRun(ctx, run, result))
-            .catch((error) => {
+            .catch(async (error) => {
             if (activeRun === run) {
                 activeRun = null;
             }
+            const message = errorMessage(error);
+            // A resume that fails before executing (for example edited workflow
+            // source) must not strand the run: park it so it stays claimable
+            // once the cause is fixed, and say so in the feed.
+            let resumeFailed = run.resume === true && !isClaimLostError(error);
+            let terminalStatus;
+            // Re-parking only makes sense while the bundle is still resumable.
+            // A terminal or waiting bundle closes the queue row instead, or
+            // every session start would retry it forever — and the feed reports
+            // the bundle's real state, not a bogus failure.
+            if (resumeFailed) {
+                try {
+                    const bundle = await readRunBundle(new WorkflowRunStore().runDirFor(runId));
+                    if (bundle === null || bundle.state.status !== "running") {
+                        resumeFailed = false;
+                        terminalStatus = bundle?.state.status;
+                    }
+                }
+                catch {
+                    // Unreadable bundles close the row too.
+                    resumeFailed = false;
+                }
+            }
+            // A continuation that failed before its bundle exists frees the
+            // parent's continuation slot instead of consuming it forever.
+            let continuationSlotFreed = false;
+            if (run.parentRunId !== undefined &&
+                run.claimToken !== undefined &&
+                !isClaimLostError(error)) {
+                try {
+                    const bundle = await readRunBundle(new WorkflowRunStore().runDirFor(runId));
+                    if (bundle === null) {
+                        continuationSlotFreed =
+                            runQueueStore?.deleteWorkflowRun({ runId, claimToken: run.claimToken }) === true;
+                        if (continuationSlotFreed) {
+                            run.claimToken = undefined;
+                        }
+                    }
+                }
+                catch {
+                    // The row may remain; a later cleanup pass can remove it.
+                }
+            }
+            releaseClaim(run, isClaimLostError(error) || continuationSlotFreed
+                ? "lost"
+                : resumeFailed
+                    ? "park"
+                    : "done");
+            void run.recorder?.stop();
             stopWidgetTicker();
             clearWidget(ctx);
-            notify(ctx, `Workflow ${workflow.name} crashed: ${errorMessage(error)}`, "error");
+            if (isClaimLostError(error)) {
+                notify(ctx, `Workflow ${workflow.name} continues under another runner (run ${runId}).`);
+                return;
+            }
+            if (resumeFailed) {
+                recordRunEvent({ runId, workflowRef: workflow.name, type: "parked", payload: {} });
+                notify(ctx, `Could not resume workflow ${workflow.name}: ${message}. The run is parked again.`, "warning");
+                return;
+            }
+            if (terminalStatus !== undefined) {
+                recordRunEvent({ runId, workflowRef: workflow.name, type: terminalStatus, payload: {} });
+                notify(ctx, `Workflow ${workflow.name} ${terminalStatus} (run ${runId}).`);
+                return;
+            }
+            recordRunEvent({
+                runId,
+                workflowRef: workflow.name,
+                type: "failed",
+                payload: { error: message },
+            });
+            try {
+                run.onFinish?.({ state: "failed", runId, error: message });
+            }
+            catch {
+                // The original workflow failure remains the primary error.
+            }
+            notify(ctx, `Workflow ${workflow.name} crashed: ${message}`, "error");
         });
+        return runId;
     };
-    const listWorkflows = async (ctx) => {
+    // Reclaim and resume a parked run when this session opens without an
+    // active run. The claim comes first; the engine resumes at the stopped
+    // node only after the queue proves ownership.
+    const resumeParkedRun = async (ctx) => {
+        if (activeRun !== null) {
+            return;
+        }
+        const queueStore = ensureRunQueueStore(ctx.cwd);
+        const claimToken = randomUUID();
+        const claimed = queueStore.claimNextWorkflowRun({
+            runnerId,
+            claimToken,
+            leaseMs: RUN_CLAIM_LEASE_MS,
+        });
+        if (claimed === undefined) {
+            return;
+        }
+        let started;
+        try {
+            started = await startRun(ctx, claimed.workflowPath, claimed.input, {
+                resume: true,
+                runId: claimed.runId,
+                claimToken,
+            });
+        }
+        catch (error) {
+            queueStore.parkWorkflowRun({ runId: claimed.runId, claimToken });
+            throw error;
+        }
+        if (started !== undefined) {
+            notify(ctx, `Resumed workflow run ${claimed.runId} (${claimed.workflowRef}).`);
+        }
+        else {
+            queueStore.parkWorkflowRun({ runId: claimed.runId, claimToken });
+        }
+    };
+    const startChild = async (request, signal, onComplete) => {
+        if (signal.aborted) {
+            throw signal.reason ?? new Error("Child workflow scheduling aborted");
+        }
+        const childKey = `${request.requestId}:${request.attempt}`;
+        if (activeRun !== null) {
+            if (activeRun.childKey !== childKey) {
+                return { state: "pending" };
+            }
+            return activeRun.lastState === null
+                ? { state: "running", runId: activeRun.runId }
+                : workflowSchedulerResult(activeRun.lastState);
+        }
+        const store = new WorkflowRunStore();
+        const bundle = await readRunBundle(store.runDirFor(request.runId));
+        if (bundle !== null) {
+            const recovered = bundle.state.status === "running" ? await store.markRunInterrupted(request.runId) : bundle;
+            if (recovered !== null) {
+                const lastTraceEvent = await readLastTraceEvent(recovered.runDir, recovered.manifest.paths.trace);
+                return workflowSchedulerResult(recovered.state, lastTraceEvent?.type === "run_interrupted");
+            }
+            return { state: "pending" };
+        }
+        if (controllerContext === null) {
+            return { state: "pending" };
+        }
+        await store.quarantineIncompleteRun(request.runId);
+        const runId = await startRun(controllerContext, request.workflow, request.input, {
+            runId: request.runId,
+            childKey,
+            onFinish: onComplete,
+            presentation: false,
+            quiet: true,
+            signal,
+        });
+        return runId === undefined ? { state: "pending" } : { state: "running", runId };
+    };
+    const updateControllerStatus = (ctx) => {
+        if (controllerHost === undefined) {
+            ctx.ui.setStatus("pi-controllers", undefined);
+            return;
+        }
+        const count = controllerHost.store.listResources().length;
+        ctx.ui.setStatus("pi-controllers", `${count} controller resource${count === 1 ? "" : "s"}`);
+    };
+    const ensureControllerHost = async (ctx) => {
+        controllerContext = ctx;
+        if (controllerHost !== undefined) {
+            return controllerHost;
+        }
+        controllerHost = await PiControllerHost.create({ cwd: ctx.cwd, startChild });
+        controllerHost?.start();
+        updateControllerStatus(ctx);
+        return controllerHost;
+    };
+    const listWorkflowControl = async (ctx, offset = 0) => {
         const discovered = await discoverWorkflows({ cwd: ctx.cwd });
         if (discovered.length === 0) {
-            notify(ctx, "No workflows found. Put *.workflow.ts files in .pi/workflows/ or ~/.pi/agent/workflows/, or pass a path.", "warning");
-            return;
+            return {
+                message: "No workflows found. Put *.workflow.ts files in .pi/workflows/ or ~/.pi/agent/workflows/, or pass a path.",
+                details: { workflows: [], total: 0, offset: 0 },
+                level: "warning",
+            };
+        }
+        if (!Number.isInteger(offset) || offset < 0 || offset > discovered.length) {
+            throw new Error(`Workflow list offset must be an integer from 0 through ${discovered.length}.`);
+        }
+        const page = [];
+        let nameChars = 0;
+        for (const workflow of discovered.slice(offset)) {
+            const renderedName = `${workflow.name} (${workflow.source})`;
+            if (page.length >= MAX_WORKFLOW_LIST_ITEMS ||
+                nameChars + renderedName.length > MAX_WORKFLOW_LIST_NAME_CHARS) {
+                break;
+            }
+            page.push(workflow);
+            nameChars += renderedName.length;
+        }
+        const names = page.map((workflow) => `${workflow.name} (${workflow.source})`).join(", ");
+        const nextOffset = offset + page.length;
+        const omitted = discovered.length - nextOffset;
+        return {
+            message: [
+                `Workflows: ${names}.`,
+                omitted > 0 ? `${omitted} more omitted; list again with offset ${nextOffset}.` : "",
+                "Run one with /workflow <name> [task].",
+            ]
+                .filter(Boolean)
+                .join(" "),
+            details: {
+                workflows: page.map((workflow) => ({
+                    name: workflow.name,
+                    source: workflow.source,
+                    ...(workflow.name === "monitor"
+                        ? {
+                            description: "Repeatedly check a target, report requested changes, and stop on a condition.",
+                        }
+                        : {}),
+                })),
+                total: discovered.length,
+                offset,
+                omitted,
+                ...(omitted > 0 ? { nextOffset } : {}),
+            },
+        };
+    };
+    const listWorkflows = async (ctx) => {
+        const result = await listWorkflowControl(ctx);
+        notify(ctx, result.message, result.level);
+    };
+    const cancelWorkflowControl = (ctx) => {
+        if (activeRun) {
+            const workflowName = activeRun.workflowName;
+            const runId = activeRun.runId;
+            activeRun.engine.cancel();
+            return {
+                message: `Cancelling workflow ${workflowName}…`,
+                details: { action: "cancel", workflowName, runId },
+            };
+        }
+        if (pendingToolLaunch !== null) {
+            const ref = pendingToolLaunch.ref;
+            pendingToolLaunch = null;
+            return {
+                message: `Cancelled the queued workflow launch for ${ref}.`,
+                details: { action: "cancel", workflow: ref, queued: false },
+            };
+        }
+        if (widgetSource) {
+            const { state } = widgetSource;
+            clearWidgetTimer();
+            clearWidget(ctx);
+            const detail = state.status === "waiting" && state.waitingOn
+                ? `already ended at checkpoint ${state.waitingOn}`
+                : `already ${state.status}`;
+            return {
+                message: `Workflow ${state.workflowName} ${detail}; cleared its widget.`,
+                details: { action: "clear", workflowName: state.workflowName, runId: state.runId },
+            };
+        }
+        return {
+            message: "No workflow is running.",
+            details: { action: "cancel", active: false },
+            level: "warning",
+        };
+    };
+    const pauseWorkflowControl = (ctx) => {
+        if (!activeRun) {
+            return {
+                message: "No workflow is running.",
+                details: { action: "pause", active: false },
+                level: "warning",
+            };
+        }
+        if (runHeld()) {
+            return {
+                message: `Workflow ${activeRun.workflowName} is already pausing or paused.`,
+                details: {
+                    action: "pause",
+                    workflowName: activeRun.workflowName,
+                    runId: activeRun.runId,
+                    paused: true,
+                },
+            };
+        }
+        activeRun.engine.pause();
+        renderWidget(ctx);
+        return {
+            message: `Pausing workflow ${activeRun.workflowName}; the current step will finish before the run holds.`,
+            details: {
+                action: "pause",
+                workflowName: activeRun.workflowName,
+                runId: activeRun.runId,
+                paused: true,
+            },
+        };
+    };
+    const resumeWorkflowControl = (ctx) => {
+        if (!activeRun) {
+            return {
+                message: "No workflow is running.",
+                details: { action: "resume", active: false },
+                level: "warning",
+            };
+        }
+        if (!runHeld()) {
+            return {
+                message: `Workflow ${activeRun.workflowName} is not paused.`,
+                details: {
+                    action: "resume",
+                    workflowName: activeRun.workflowName,
+                    runId: activeRun.runId,
+                    paused: false,
+                },
+                level: "warning",
+            };
+        }
+        activeRun.engine.resume();
+        activeRun.executor.release();
+        renderWidget(ctx);
+        return {
+            message: `Workflow ${activeRun.workflowName} resumed.`,
+            details: {
+                action: "resume",
+                workflowName: activeRun.workflowName,
+                runId: activeRun.runId,
+                paused: false,
+            },
+        };
+    };
+    const statusWorkflowControl = async (ctx, runId) => {
+        if (runId !== undefined) {
+            const bundle = await readRunBundle(new WorkflowRunStore().runDirFor(runId));
+            if (bundle === null) {
+                throw new Error(`Workflow run not found: ${runId}`);
+            }
+            const { state } = bundle;
+            return {
+                message: `Workflow ${state.workflowName} is ${state.status} (run ${state.runId}).`,
+                details: workflowStateSummary(state),
+            };
+        }
+        const state = activeRun?.lastState ?? widgetSource?.state;
+        if ((state === undefined || state === null) && pendingToolLaunch !== null) {
+            return {
+                message: `Workflow ${pendingToolLaunch.ref} is queued until the current turn finishes.`,
+                details: { active: false, queued: true, workflow: pendingToolLaunch.ref },
+            };
+        }
+        if (state === undefined || state === null) {
+            return {
+                message: "No workflow run is active or displayed.",
+                details: { active: false },
+                level: "warning",
+            };
+        }
+        return {
+            message: `Workflow ${state.workflowName} is ${state.status} (run ${state.runId}).`,
+            details: workflowStateSummary(state),
+        };
+    };
+    const resolveWaitingWorkflow = async (ctx, requestedRunId) => {
+        let parentRunId = requestedRunId ?? lastWaitingRunId;
+        if (parentRunId === null) {
+            const rows = ensureRunQueueStore(ctx.cwd).listWorkflowRuns();
+            const known = new Set(rows.map((row) => row.runId));
+            const continued = new Set(rows.map((row) => row.parentRunId).filter((parent) => parent !== null));
+            const bundles = await listRunBundles(new WorkflowRunStore().outputRoot);
+            parentRunId =
+                bundles.find((bundle) => bundle.state.status === "waiting" &&
+                    known.has(bundle.state.runId) &&
+                    !continued.has(bundle.state.runId))?.state.runId ?? null;
+        }
+        if (parentRunId === null) {
+            throw new Error("No workflow is waiting for an answer.");
+        }
+        const parent = await readRunBundle(new WorkflowRunStore().runDirFor(parentRunId));
+        if (parent === null ||
+            parent.state.status !== "waiting" ||
+            parent.state.workflowPath === undefined) {
+            if (parentRunId === lastWaitingRunId) {
+                lastWaitingRunId = null;
+            }
+            throw new Error(`Workflow run ${parentRunId} is no longer waiting.`);
+        }
+        return { parentRunId, workflowPath: parent.state.workflowPath };
+    };
+    const answerWorkflowControl = async (ctx, input, requestedRunId) => {
+        const waiting = await resolveWaitingWorkflow(ctx, requestedRunId);
+        const continued = await startRun(ctx, waiting.workflowPath, input, {
+            parentRunId: waiting.parentRunId,
+        });
+        if (continued === undefined) {
+            throw new Error("Could not start the checkpoint continuation.");
+        }
+        lastWaitingRunId = null;
+        return {
+            message: `Answered checkpoint ${waiting.parentRunId}; continuation ${continued} started.`,
+            details: {
+                action: "answer",
+                parentRunId: waiting.parentRunId,
+                runId: continued,
+            },
+        };
+    };
+    const startWorkflowControl = async (ctx, ref, input) => {
+        if (activeRun !== null) {
+            throw new Error(`A workflow is already running: ${activeRun.workflowName}.`);
+        }
+        if (pendingToolLaunch !== null) {
+            throw new Error("A workflow launch is already waiting for the current turn to finish.");
+        }
+        if (presentationPending !== null) {
+            throw new Error("The previous workflow result is still being presented.");
+        }
+        const runId = await startRun(ctx, ref, input);
+        if (runId === undefined) {
+            throw new Error("The workflow could not start.");
+        }
+        return {
+            message: `Workflow ${ref} started (run ${runId}).`,
+            details: { action: "start", workflow: ref, runId },
+        };
+    };
+    const queueToolLaunch = async (ctx, ref, input, options = {}) => {
+        if (activeRun !== null) {
+            throw new Error(`A workflow is already running: ${activeRun.workflowName}. Cancel it before starting another.`);
+        }
+        if (pendingToolLaunch !== null) {
+            throw new Error("A workflow launch is already waiting for the current turn to finish.");
+        }
+        if (presentationPending !== null) {
+            throw new Error("The previous workflow result is still being presented.");
+        }
+        const reservation = { ctx, ref, input, options };
+        pendingToolLaunch = reservation;
+        try {
+            const resolved = await resolveWorkflowRef(ref, { cwd: ctx.cwd });
+            const workflow = await loadWorkflowFile(resolved.path);
+            if (pendingToolLaunch !== reservation) {
+                throw new Error("The queued workflow launch was cancelled before validation finished.");
+            }
+            return {
+                message: `Workflow ${workflow.name} will start after this turn finishes.`,
+                details: {
+                    action: "start",
+                    workflow: workflow.name,
+                    source: resolved.source,
+                    queued: true,
+                },
+            };
+        }
+        catch (error) {
+            if (pendingToolLaunch === reservation) {
+                pendingToolLaunch = null;
+            }
+            throw error;
         }
-        const names = discovered.map((workflow) => `${workflow.name} (${workflow.source})`).join(", ");
-        notify(ctx, `Workflows: ${names}. Run one with /workflow <name> [task].`);
     };
     pi.registerCommand("workflow", {
-        description: "Run a workflow: /workflow <name-or-path> [task | --input-json {…}]; also: pause, resume, cancel",
+        description: "Run or manage a workflow: /workflow <name-or-path> [task | --input-json {…}]; also: status, pause, resume, cancel, answer",
         getArgumentCompletions: async (prefix) => {
             const discovered = await discoverWorkflows({ cwd: process.cwd() });
             const items = [
                 ...discovered.map((workflow) => ({ value: workflow.name, label: workflow.name })),
+                { value: "status", label: "status" },
                 { value: "pause", label: "pause" },
                 { value: "resume", label: "resume" },
                 { value: "cancel", label: "cancel" },
+                { value: "answer", label: "answer" },
             ].filter((item) => item.value.startsWith(prefix));
             return items.length > 0 ? items : null;
         },
@@ -320,87 +1148,174 @@ export default function piWorkflows(pi) {
                 return;
             }
             if (parsed.kind === "cancel") {
-                if (activeRun) {
-                    activeRun.engine.cancel();
-                    notify(ctx, `Cancelling workflow ${activeRun.workflowName}…`);
-                    return;
-                }
-                // No live run, but a parked (waiting) or recently finished run may
-                // still occupy the widget; cancel clears it.
-                if (widgetSource) {
-                    const { state } = widgetSource;
-                    clearWidgetTimer();
-                    clearWidget(ctx);
-                    const detail = state.status === "waiting" && state.waitingOn
-                        ? `already ended at checkpoint ${state.waitingOn}`
-                        : `already ${state.status}`;
-                    notify(ctx, `Workflow ${state.workflowName} ${detail}; cleared its widget.`);
-                    return;
-                }
-                notify(ctx, "No workflow is running.", "warning");
+                const result = cancelWorkflowControl(ctx);
+                notify(ctx, result.message, result.level);
                 return;
             }
             if (parsed.kind === "pause") {
-                if (!activeRun) {
-                    notify(ctx, "No workflow is running.", "warning");
-                    return;
+                const result = pauseWorkflowControl(ctx);
+                notify(ctx, result.message, result.level);
+                return;
+            }
+            if (parsed.kind === "resume") {
+                const result = resumeWorkflowControl(ctx);
+                notify(ctx, result.message, result.level);
+                return;
+            }
+            if (parsed.kind === "status") {
+                try {
+                    const result = await statusWorkflowControl(ctx, parsed.runId);
+                    notify(ctx, result.message, result.level);
                 }
-                if (runHeld()) {
-                    notify(ctx, `Workflow ${activeRun.workflowName} is already pausing or paused.`);
-                    return;
+                catch (error) {
+                    notify(ctx, errorMessage(error), "error");
                 }
-                activeRun.engine.pause();
-                renderWidget(ctx);
-                notify(ctx, `Pausing workflow ${activeRun.workflowName} — the current step finishes, then the run holds. /workflow resume to continue.`);
                 return;
             }
-            if (parsed.kind === "resume") {
-                if (!activeRun) {
-                    notify(ctx, "No workflow is running.", "warning");
-                    return;
+            if (parsed.kind === "answer") {
+                try {
+                    const result = await answerWorkflowControl(ctx, parsed.input, parsed.runId);
+                    notify(ctx, result.message, result.level);
                 }
-                if (!runHeld()) {
-                    notify(ctx, `Workflow ${activeRun.workflowName} is not paused.`);
-                    return;
+                catch (error) {
+                    const message = errorMessage(error);
+                    notify(ctx, /workflow_run_queue_parent/.test(message)
+                        ? "That checkpoint was already answered; see its continuation run."
+                        : `Could not continue workflow: ${message}`, "error");
                 }
-                activeRun.engine.resume();
-                activeRun.executor.release();
-                renderWidget(ctx);
-                notify(ctx, `Workflow ${activeRun.workflowName} resumed.`);
                 return;
             }
             try {
-                await startRun(ctx, parsed.ref, parsed.input);
+                const result = await startWorkflowControl(ctx, parsed.ref, parsed.input);
+                notify(ctx, result.message, result.level);
             }
             catch (error) {
                 notify(ctx, `Could not start workflow: ${errorMessage(error)}`, "error");
             }
         },
     });
+    pi.registerCommand("controller", {
+        description: "Manage durable controllers: list, get, apply, reconcile, delete, start, or stop",
+        getArgumentCompletions: async (prefix) => {
+            const items = ["list", "get", "apply", "reconcile", "delete", "start", "stop"]
+                .filter((value) => value.startsWith(prefix))
+                .map((value) => ({ value, label: value }));
+            return items.length > 0 ? items : null;
+        },
+        handler: async (args, ctx) => {
+            let parsed;
+            try {
+                parsed = parseControllerArgs(args);
+            }
+            catch (error) {
+                notify(ctx, errorMessage(error), "error");
+                return;
+            }
+            const host = await ensureControllerHost(ctx);
+            if (host === undefined) {
+                notify(ctx, "No controllers found. Put *.controller.ts files in .pi/controllers/ or ~/.pi/agent/controllers/.", "warning");
+                return;
+            }
+            try {
+                switch (parsed.kind) {
+                    case "list":
+                        notify(ctx, host.list());
+                        break;
+                    case "get":
+                        notify(ctx, host.get(parsed.controller, parsed.key));
+                        break;
+                    case "apply": {
+                        const resource = host.apply(parsed.controller, parsed.key, parsed.spec);
+                        updateControllerStatus(ctx);
+                        notify(ctx, `Applied ${resource.metadata.controller}/${resource.metadata.key} generation ${resource.metadata.generation}.`);
+                        break;
+                    }
+                    case "reconcile":
+                        host.reconcile(parsed.controller, parsed.key);
+                        notify(ctx, `Queued ${parsed.controller}/${parsed.key}.`);
+                        break;
+                    case "delete":
+                        host.delete(parsed.controller, parsed.key);
+                        notify(ctx, `Requested deletion of ${parsed.controller}/${parsed.key}.`);
+                        break;
+                    case "start":
+                        host.start();
+                        notify(ctx, "Controller workers started.");
+                        break;
+                    case "stop":
+                        if (activeRun?.childKey !== undefined) {
+                            activeRun.interruptionRequested = true;
+                            activeRun.engine.cancel();
+                        }
+                        await host.stop();
+                        notify(ctx, "Controller workers stopped.");
+                        break;
+                }
+            }
+            catch (error) {
+                notify(ctx, `Controller command failed: ${errorMessage(error)}`, "error");
+            }
+        },
+    });
     pi.registerTool({
         name: "workflow",
         label: "Workflow",
         description: [
-            "Submit the output for the pending workflow step.",
-            "Only call this tool when a workflow step contract in the conversation asks you to.",
-            "Pass the exact step id from the contract and your result as the output.",
+            "List, start, inspect, pause, resume, cancel, answer, or complete Pi Workflows runs.",
+            "When the user asks to monitor, watch, poll, or check something repeatedly, start the built-in monitor workflow with input keys task, everyMinutes, reportWhen, stopWhen, and optional maxChecks.",
+            "Use submit only when a workflow step contract asks for it, and pass the exact step and attempt ids.",
+            "Do not start repeated work without the user's request, and keep monitoring observation-only unless the user authorizes mutations.",
         ].join(" "),
-        parameters: Type.Object({
-            step: Type.String({ description: "The step id from the workflow step contract" }),
-            attempt: Type.String({ description: "The attempt id from the workflow step contract" }),
-            output: Type.Unknown({ description: "The step output, matching the expected output shape" }),
-        }),
-        async execute(_toolCallId, params) {
-            if (!activeRun) {
-                throw new Error("No workflow is running. Do not call the workflow tool outside a workflow.");
-            }
-            const result = await activeRun.executor.submit(params.step, params.attempt, params.output);
-            if (!result.accepted) {
-                throw new Error(result.message);
+        parameters: WorkflowToolParameters,
+        async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+            let control;
+            switch (params.action) {
+                case "list":
+                    control = await listWorkflowControl(ctx, params.offset);
+                    break;
+                case "start":
+                    control = await queueToolLaunch(ctx, params.workflow, params.input ?? {});
+                    break;
+                case "status":
+                    control = await statusWorkflowControl(ctx, params.runId);
+                    break;
+                case "pause":
+                    control = pauseWorkflowControl(ctx);
+                    break;
+                case "resume":
+                    control = resumeWorkflowControl(ctx);
+                    break;
+                case "cancel":
+                    control = cancelWorkflowControl(ctx);
+                    break;
+                case "answer": {
+                    const waiting = await resolveWaitingWorkflow(ctx, params.runId);
+                    control = await queueToolLaunch(ctx, waiting.workflowPath, params.input, {
+                        parentRunId: waiting.parentRunId,
+                    });
+                    break;
+                }
+                case "submit": {
+                    if (!activeRun) {
+                        throw new Error("No workflow step is waiting for output.");
+                    }
+                    // Flush the conversation into the bundle before accepting, so the
+                    // attempt range includes the assistant message carrying this call.
+                    await activeRun.recorder?.record(ctx).catch(() => undefined);
+                    await activeRun.recorder?.synchronize(ctx).catch(() => undefined);
+                    const result = await activeRun.executor.submit(params.step, params.attempt, params.output);
+                    if (!result.accepted) {
+                        throw new Error(result.message);
+                    }
+                    return {
+                        content: [{ type: "text", text: result.message }],
+                        details: { action: "submit", step: params.step, accepted: true },
+                    };
+                }
             }
             return {
-                content: [{ type: "text", text: result.message }],
-                details: { step: params.step, accepted: true },
+                content: [{ type: "text", text: control.message }],
+                details: control.details,
             };
         },
     });
@@ -412,6 +1327,29 @@ export default function piWorkflows(pi) {
         description: "Scroll the workflow widget down",
         handler: (ctx) => scrollWidget(ctx, WIDGET_SCROLL_STEP),
     });
+    pi.on("session_start", async (_event, ctx) => {
+        sessionClosed = false;
+        controllerContext = ctx;
+        try {
+            syncArmed = true;
+            startRunSync(ctx);
+        }
+        catch {
+            // Session sync is best-effort; runs themselves never depend on it.
+        }
+        try {
+            await resumeParkedRun(ctx);
+        }
+        catch (error) {
+            notify(ctx, `Could not resume a parked workflow: ${errorMessage(error)}`, "warning");
+        }
+        try {
+            await ensureControllerHost(ctx);
+        }
+        catch (error) {
+            notify(ctx, `Could not start controller workers: ${errorMessage(error)}`, "warning");
+        }
+    });
     pi.on("agent_start", () => {
         if (!activeRun && presentationPending === null && presentationAbort) {
             // A normal user turn started while an async presentation prompt was
@@ -441,19 +1379,85 @@ export default function piWorkflows(pi) {
         renderWidget(ctx);
         notify(ctx, `Workflow ${run.workflowName} paused (turn interrupted). /workflow resume to continue, /workflow cancel to stop.`);
     });
-    pi.on("agent_settled", () => {
-        if (!activeRun) {
+    pi.on("turn_start", (event) => {
+        activeRun?.recorder?.handleTurnStart(event);
+    });
+    pi.on("turn_end", async (event, ctx) => {
+        await activeRun?.recorder?.handleTurnEnd(event, ctx).catch(() => undefined);
+    });
+    pi.on("message_start", async (event, ctx) => {
+        await activeRun?.recorder?.handleMessageStart(event, ctx).catch(() => undefined);
+    });
+    pi.on("message_update", (event) => {
+        activeRun?.recorder?.handleMessageUpdate(event);
+    });
+    pi.on("message_end", (event) => {
+        activeRun?.recorder?.handleMessageEnd(event);
+    });
+    pi.on("tool_execution_start", (event) => {
+        activeRun?.recorder?.handleToolStart(event);
+    });
+    pi.on("tool_execution_update", (event) => {
+        activeRun?.recorder?.handleToolUpdate(event);
+    });
+    pi.on("tool_execution_end", (event) => {
+        activeRun?.recorder?.handleToolEnd(event);
+    });
+    pi.on("agent_settled", async (_event, ctx) => {
+        if (activeRun === null && pendingToolLaunch !== null) {
+            const launch = pendingToolLaunch;
+            pendingToolLaunch = null;
+            try {
+                const runId = await startRun(launch.ctx, launch.ref, launch.input, launch.options);
+                if (runId === undefined) {
+                    notify(launch.ctx, "The queued workflow could not start.", "error");
+                }
+                else if (launch.options?.parentRunId !== undefined) {
+                    lastWaitingRunId = null;
+                }
+            }
+            catch (error) {
+                notify(launch.ctx, `Could not start queued workflow: ${errorMessage(error)}`, "error");
+            }
+            return;
+        }
+        const run = activeRun;
+        if (!run) {
             presentationPending = null;
             return;
         }
-        activeRun.executor.setStreaming(false);
-        activeRun.executor.handleAgentSettled();
+        await run.recorder?.synchronize(ctx).catch(() => undefined);
+        run.recorder?.settleAttempt();
+        run.executor.setStreaming(false);
+        run.executor.handleAgentSettled();
     });
-    pi.on("session_shutdown", () => {
+    pi.on("session_shutdown", async () => {
         sessionClosed = true;
         supersedePresentation();
-        activeRun?.engine.cancel();
+        const run = activeRun;
+        if (run !== null && run.claimToken !== undefined) {
+            // Queued interactive runs park: no terminal event, no recorded partial
+            // attempt, and the claim releases so another runner can resume.
+            run.engine.park();
+        }
+        else {
+            run?.engine.cancel();
+        }
+        await run?.recorder?.stop().catch(() => undefined);
+        await run?.completion?.catch(() => undefined);
         activeRun = null;
+        pendingToolLaunch = null;
+        lastWaitingRunId = null;
+        if (runSyncTimer !== null) {
+            clearInterval(runSyncTimer);
+            runSyncTimer = null;
+        }
+        syncArmed = false;
+        await controllerHost?.close().catch(() => undefined);
+        controllerHost = undefined;
+        controllerContext = null;
+        runQueueStore?.close();
+        runQueueStore = null;
         presentationPending = null;
         clearWidgetTimer();
         stopWidgetTicker();
@@ -461,6 +1465,31 @@ export default function piWorkflows(pi) {
         widgetScroll = null;
     });
 }
+function workflowSchedulerResult(state, interrupted = false) {
+    if (interrupted) {
+        return {
+            state: "interrupted",
+            runId: state.runId,
+            ...(state.error !== undefined ? { error: state.error } : {}),
+        };
+    }
+    switch (state.status) {
+        case "running":
+            return { state: "running", runId: state.runId };
+        case "waiting":
+            return { state: "waiting", runId: state.runId };
+        case "completed":
+            return { state: "succeeded", runId: state.runId };
+        case "failed":
+        case "timed_out":
+        case "cancelled":
+            return {
+                state: "failed",
+                runId: state.runId,
+                ...(state.error !== undefined ? { error: state.error } : {}),
+            };
+    }
+}
 async function resolvePresentationPrompt(buildPrompt, state, signal) {
     const snapshot = structuredClone(state);
     return await Promise.race([