@osolmaz/pi-workflows 0.1.0 → 0.3.0

package/src/extension/index.ts

@@ -1,27 +1,55 @@
-import type {
-  ExtensionAPI,
-  ExtensionCommandContext,
-  ExtensionContext,
-} from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
+import { randomUUID } from "node:crypto";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  projectControllerStorePath,
+  type RunEventRecord,
+  SqliteControllerStore,
+} from "../controllers/index.js";
+import type { JsonObject } from "../controllers/types.js";
+import type { WorkflowSchedulerResult } from "../controllers/workflows.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 type {
   WorkflowDefinition,
   WorkflowDefinitionSnapshot,
   WorkflowRunResult,
   WorkflowRunState,
 } from "../workflows/types.js";
+import {
+  PiControllerHost,
+  parseControllerArgs,
+  type PiChildWorkflowStarter,
+} from "./controller-host.js";
 import { ConversationStepExecutor } from "./executor.js";
+import { SessionRecorder } from "./recorder.js";
 import { buildWidgetView } from "./widget.js";
+import { WorkflowToolParameters, type WorkflowToolInput } 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 {}
@@ -33,14 +61,40 @@ type PresentationPromptBuilder = Exclude<
 >;
 
 type ActiveRun = {
-  runId: string | null;
+  runId: string;
   workflowName: string;
   engine: WorkflowEngine;
   executor: ConversationStepExecutor;
+  recorder: SessionRecorder | null;
   snapshot: WorkflowDefinitionSnapshot;
   presentationPrompt: WorkflowDefinition["presentationPrompt"];
   generation: number;
   lastState: WorkflowRunState | null;
+  childKey?: string;
+  onFinish?: (result: WorkflowSchedulerResult) => void;
+  completion?: Promise<void>;
+  interruptionRequested?: boolean;
+  claimToken?: string | undefined;
+  renewTimer?: ReturnType<typeof setInterval> | undefined;
+  /** True for runs this session resumed from the queue. */
+  resume?: boolean | undefined;
+  /** Set on continuation runs: the checkpointed parent run id. */
+  parentRunId?: string | undefined;
+};
+
+type StartRunOptions = {
+  runId?: string;
+  childKey?: string;
+  onFinish?: (result: WorkflowSchedulerResult) => void;
+  presentation?: boolean;
+  quiet?: boolean;
+  signal?: AbortSignal;
+  /** Continue a checkpointed run: input becomes the answer payload. */
+  parentRunId?: string;
+  /** Resume a parked run at its stopped node instead of starting fresh. */
+  resume?: boolean;
+  /** An existing queue claim token, when the caller already claimed the run. */
+  claimToken?: string;
 };
 
 export type ParsedWorkflowArgs =
@@ -48,6 +102,8 @@ export type ParsedWorkflowArgs =
   | { kind: "cancel" }
   | { kind: "pause" }
   | { kind: "resume" }
+  | { kind: "status"; runId?: string }
+  | { kind: "answer"; input: unknown; runId?: string | undefined }
   | { kind: "run"; ref: string; input: unknown };
 
 /** Parse `/workflow` arguments. Exported for tests. */
@@ -59,6 +115,52 @@ export function parseWorkflowArgs(args: string): ParsedWorkflowArgs {
   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: string | undefined;
+    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) as unknown,
+        ...(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();
@@ -75,13 +177,185 @@ export function parseWorkflowArgs(args: string): ParsedWorkflowArgs {
   return { kind: "run", ref, input: rest.length > 0 ? { task: rest } : {} };
 }
 
+function workflowStateSummary(state: WorkflowRunState): JsonObject {
+  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 } : {}),
+  };
+}
+
 type WidgetSource = {
   state: WorkflowRunState;
   snapshot: WorkflowDefinitionSnapshot;
 };
 
 export default function piWorkflows(pi: ExtensionAPI) {
+  // One runner identity per session; it names this session in run claims.
+  const runnerId = randomUUID();
+  let runQueueStore: SqliteControllerStore | null = null;
+  const ensureRunQueueStore = (cwd: string): SqliteControllerStore => {
+    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: ReturnType<typeof setInterval> | null = null;
+
+  const recordRunEvent = (event: {
+    runId: string;
+    workflowRef: string;
+    type: string;
+    payload?: JsonObject;
+  }) => {
+    try {
+      runQueueStore?.recordRunEvent({ ...event, runnerId });
+    } catch {
+      // The event feed is best-effort; never fail a run for it.
+    }
+  };
+
+  const describeRunEvent = (event: RunEventRecord): string => {
+    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: ExtensionContext): Promise<void> => {
+    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: ExtensionContext) => {
+    if (runQueueStore === null) {
+      return;
+    }
+    const lines: string[] = [];
+    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 is string => 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: ExtensionContext) => {
+    if (runSyncTimer !== null) {
+      return;
+    }
+    ensureRunQueueStore(ctx.cwd);
+    void runSyncPass(ctx);
+    runSyncTimer = setInterval(() => void runSyncPass(ctx), RUN_SYNC_POLL_MS);
+    runSyncTimer.unref?.();
+  };
   let activeRun: ActiveRun | null = null;
+  let pendingToolLaunch: {
+    ctx: ExtensionContext;
+    ref: string;
+    input: unknown;
+    options?: StartRunOptions;
+  } | null = null;
+  // The interactive run currently parked at a checkpoint, if any.
+  let lastWaitingRunId: string | null = null;
   let widgetTimer: NodeJS.Timeout | null = null;
   let widgetTicker: NodeJS.Timeout | null = null;
   // Manual widget scroll: null follows the active node; a number is the
@@ -95,6 +369,8 @@ export default function piWorkflows(pi: ExtensionAPI) {
   let runGeneration = 0;
   let presentationAbort: AbortController | null = null;
   let presentationPending: number | null = null;
+  let controllerHost: PiControllerHost | undefined;
+  let controllerContext: ExtensionContext | null = 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`).
@@ -290,10 +566,63 @@ export default function piWorkflows(pi: ExtensionAPI) {
     }
   };
 
-  const finishRun = (ctx: ExtensionContext, run: ActiveRun, result: WorkflowRunResult) => {
+  // 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: ActiveRun, outcome: "done" | "lost" | "park") => {
+    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: ExtensionContext,
+    run: ActiveRun,
+    result: WorkflowRunResult,
+  ): Promise<void> => {
     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);
@@ -304,100 +633,763 @@ export default function piWorkflows(pi: ExtensionAPI) {
       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" as const,
+              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: ExtensionCommandContext, ref: string, input: unknown) => {
+  const startRun = async (
+    ctx: ExtensionContext,
+    ref: string,
+    input: unknown,
+    options: StartRunOptions = {},
+  ): Promise<string | undefined> => {
+    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: SqliteControllerStore | null = 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: (() => void) | undefined;
+    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: WorkflowRunState) => {
-        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: WorkflowRunState) => {
         run.lastState = state;
         updateWidget(ctx, state, snapshot);
       },
     });
     const run: ActiveRun = {
-      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`);
+    if (!options.quiet) {
+      notify(ctx, `Workflow ${workflow.name} started. Follow it live with: pi-workflows view`);
+    }
 
-    engine
-      .run(workflow, input, { workflowPath: resolved.path })
+    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: unknown) => {
+      .catch(async (error: unknown) => {
         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: string | undefined;
+        // 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;
+  };
+
+  // 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: ExtensionContext): Promise<void> => {
+    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: string | undefined;
+    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: PiChildWorkflowStarter = 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: ExtensionContext) => {
+    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: ExtensionContext,
+  ): Promise<PiControllerHost | undefined> => {
+    controllerContext = ctx;
+    if (controllerHost !== undefined) {
+      return controllerHost;
+    }
+    controllerHost = await PiControllerHost.create({ cwd: ctx.cwd, startChild });
+    controllerHost?.start();
+    updateControllerStatus(ctx);
+    return controllerHost;
   };
 
-  const listWorkflows = async (ctx: ExtensionCommandContext) => {
+  type WorkflowControlResult = {
+    message: string;
+    details: JsonObject;
+    level?: "info" | "warning" | "error";
+  };
+
+  const listWorkflowControl = async (
+    ctx: ExtensionContext,
+    offset = 0,
+  ): Promise<WorkflowControlResult> => {
     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 {
+        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}.`,
       );
-      return;
     }
-    const names = discovered.map((workflow) => `${workflow.name} (${workflow.source})`).join(", ");
-    notify(ctx, `Workflows: ${names}. Run one with /workflow <name> [task].`);
+    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: ExtensionContext) => {
+    const result = await listWorkflowControl(ctx);
+    notify(ctx, result.message, result.level);
+  };
+
+  const cancelWorkflowControl = (ctx: ExtensionContext): WorkflowControlResult => {
+    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: ExtensionContext): WorkflowControlResult => {
+    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: ExtensionContext): WorkflowControlResult => {
+    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: ExtensionContext,
+    runId?: string,
+  ): Promise<WorkflowControlResult> => {
+    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: ExtensionContext,
+    requestedRunId?: string,
+  ): Promise<{ parentRunId: string; workflowPath: string }> => {
+    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 is string => 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: ExtensionContext,
+    input: unknown,
+    requestedRunId?: string,
+  ): Promise<WorkflowControlResult> => {
+    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: ExtensionContext,
+    ref: string,
+    input: unknown,
+  ): Promise<WorkflowControlResult> => {
+    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: ExtensionContext,
+    ref: string,
+    input: unknown,
+    options: StartRunOptions = {},
+  ): Promise<WorkflowControlResult> => {
+    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;
+    }
   };
 
   pi.registerCommand("workflow", {
     description:
-      "Run a workflow: /workflow <name-or-path> [task | --input-json {…}]; also: pause, resume, cancel",
+      "Run or manage a workflow: /workflow <name-or-path> [task | --input-json {…}]; also: status, pause, resume, cancel, answer",
     getArgumentCompletions: async (prefix: string) => {
       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;
     },
@@ -414,93 +1406,186 @@ export default function piWorkflows(pi: ExtensionAPI) {
         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;
-        }
-        if (runHeld()) {
-          notify(ctx, `Workflow ${activeRun.workflowName} is already pausing or paused.`);
-          return;
-        }
-        activeRun.engine.pause();
-        renderWidget(ctx);
-        notify(
-          ctx,
-          `Pausing workflow ${activeRun.workflowName} — the current step finishes, then the run holds. /workflow resume to continue.`,
-        );
+        const result = pauseWorkflowControl(ctx);
+        notify(ctx, result.message, result.level);
         return;
       }
       if (parsed.kind === "resume") {
-        if (!activeRun) {
-          notify(ctx, "No workflow is running.", "warning");
-          return;
+        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);
+        } catch (error) {
+          notify(ctx, errorMessage(error), "error");
         }
-        if (!runHeld()) {
-          notify(ctx, `Workflow ${activeRun.workflowName} is not paused.`);
-          return;
+        return;
+      }
+      if (parsed.kind === "answer") {
+        try {
+          const result = await answerWorkflowControl(ctx, parsed.input, parsed.runId);
+          notify(ctx, result.message, result.level);
+        } 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: string) => {
+      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: WorkflowToolInput, _signal, _onUpdate, ctx) {
+      let control: WorkflowControlResult;
+      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,
       };
     },
   });
@@ -515,6 +1600,27 @@ export default function piWorkflows(pi: ExtensionAPI) {
     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
@@ -552,20 +1658,91 @@ export default function piWorkflows(pi: ExtensionAPI) {
     );
   });
 
-  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();
@@ -574,6 +1751,35 @@ export default function piWorkflows(pi: ExtensionAPI) {
   });
 }
 
+function workflowSchedulerResult(
+  state: WorkflowRunState,
+  interrupted = false,
+): WorkflowSchedulerResult {
+  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: PresentationPromptBuilder,
   state: WorkflowRunState,