@signalridge/pi-workflows 1.2.0 → 1.3.1

package/src/index.ts

@@ -1,67 +1,61 @@
+import { execFileSync } from "node:child_process";
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "@sinclair/typebox";
-import { WorkflowEngine, type WorkflowQuiesceResult } from "./engine.js";
+import { DEFAULT_TRIGGER_WORD, hasTriggerWord, WORKFLOW_ARMED_DIRECTIVE } from "./arming.js";
+import { BUILTIN_WORKFLOWS, validateBuiltinArgs } from "./builtins.js";
+import { type CommandResult, resolveCodeReviewScope } from "./code-review-scope.js";
+import { type ScriptStartOptions, type ScriptStartResult, WorkflowEngine, WorkflowWaitAbortedError } from "./engine.js";
 import { JOURNAL_ENTRY_TYPE, type SessionEntryLike } from "./journal.js";
 import { createManagedSpawnClient, PROTOCOL_DIAGNOSTIC, queryChildSessionContextImmediate } from "./rpc-client.js";
-import { validateWorkflow } from "./schema.js";
-import { showWorkflowNavigator } from "./ui.js";
+import { listSavedWorkflows, loadSavedWorkflow, saveWorkflow } from "./saved-workflows.js";
+import { liveWidgetLines, showWorkflowNavigator } from "./ui.js";
+import { loadWorkflowSettings, saveWorkflowSettings } from "./workflow-settings.js";
 
-const WorkflowTierSchema = Type.Union([Type.Literal("small"), Type.Literal("medium"), Type.Literal("large")]);
-
-const PhaseSchema = Type.Object(
-  {
-    id: Type.String({ minLength: 1, maxLength: 128 }),
-    title: Type.String({ minLength: 1, maxLength: 512 }),
-  },
-  { additionalProperties: false },
-);
-
-const TaskSchema = Type.Object(
-  {
-    id: Type.String({ minLength: 1, maxLength: 128 }),
-    phase: Type.Optional(Type.String({ minLength: 1, maxLength: 128 })),
-    tier: Type.Optional(WorkflowTierSchema),
-    subagent_type: Type.String({ minLength: 1, maxLength: 128 }),
-    description: Type.String({ minLength: 1, maxLength: 512 }),
-    prompt: Type.String({ minLength: 1, maxLength: 100_000 }),
-    depends_on: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: 128 }), { maxItems: 128 })),
-    inputs: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: 128 }), { maxItems: 128 })),
-  },
-  { additionalProperties: false },
-);
-
-const SynthesisSchema = Type.Object(
+const WorkflowToolSchema = Type.Object(
   {
-    subagent_type: Type.String({ minLength: 1, maxLength: 128 }),
-    tier: Type.Optional(WorkflowTierSchema),
-    prompt: Type.String({ minLength: 1, maxLength: 100_000 }),
-  },
-  { additionalProperties: false },
-);
-
-const WorkflowSchema = Type.Object(
-  {
-    name: Type.String({ minLength: 1, maxLength: 512 }),
-    description: Type.Optional(Type.String({ maxLength: 100_000 })),
-    tier: Type.Optional(WorkflowTierSchema),
-    phases: Type.Optional(Type.Array(PhaseSchema, { maxItems: 32 })),
-    tasks: Type.Array(TaskSchema, { minItems: 1, maxItems: 128 }),
-    synthesis: Type.Optional(SynthesisSchema),
+    script: Type.Optional(Type.String({ maxLength: 200_000 })),
+    name: Type.Optional(Type.String({ minLength: 1, maxLength: 128 })),
+    args: Type.Optional(Type.Any()),
     background: Type.Optional(Type.Boolean()),
+    maxAgents: Type.Optional(Type.Number({ minimum: 1 })),
+    concurrency: Type.Optional(Type.Number({ minimum: 1 })),
+    agentRetries: Type.Optional(Type.Number({ minimum: 0, maximum: 3 })),
+    tokenBudget: Type.Optional(Type.Number({ minimum: 1 })),
+    agentTimeoutMs: Type.Optional(Type.Number({ minimum: 1 })),
+    resumeFromRunId: Type.Optional(Type.String({ minLength: 1, maxLength: 128 })),
   },
   { additionalProperties: false },
 );
 
 const ControlSchema = Type.Object(
   {
-    action: Type.String({ minLength: 1, maxLength: 32 }),
+    action: Type.Union(
+      [
+        Type.Literal("list", { description: "List all workflow runs" }),
+        Type.Literal("get", { description: "Get details for one run" }),
+        Type.Literal("status", { description: "Alias for get — inspect one run" }),
+        Type.Literal("pause", { description: "Pause a running workflow" }),
+        Type.Literal("resume", { description: "Resume a paused/interrupted workflow" }),
+        Type.Literal("stop", { description: "Stop a running workflow" }),
+        Type.Literal("rm", { description: "Remove a workflow run and its journal" }),
+      ],
+      { description: "Control action" },
+    ),
     run_id: Type.Optional(Type.String({ minLength: 1, maxLength: 128 })),
+    // Accept camelCase and legacy workflow_run_id for interop with pi-dynamic-workflows docs
+    runId: Type.Optional(Type.String({ minLength: 1, maxLength: 128 })),
+    workflow_run_id: Type.Optional(Type.String({ minLength: 1, maxLength: 128 })),
   },
   { additionalProperties: false },
 );
 
+function normalizeControlRunId(params: Record<string, unknown>): string | undefined {
+  const raw = params.run_id ?? params.runId ?? params.workflow_run_id ?? params.runID ?? params.workflowRunId;
+  return typeof raw === "string" && raw.trim().length > 0 ? raw.trim() : undefined;
+}
+
 function textResult(text: string, details: unknown = {}) {
   return {
     content: [{ type: "text" as const, text }],
@@ -69,14 +63,50 @@ function textResult(text: string, details: unknown = {}) {
   };
 }
 
-function formatStart(result: {
-  runId: string;
-  status: string;
-  background: boolean;
-  result?: string;
-  error?: string;
-  waitAborted?: boolean;
-}): string {
+/**
+ * Run one command for diff discovery. argv array, never a shell string — a
+ * branch name or path reaches this from user input.
+ */
+function runCommand(file: string, args: string[]): CommandResult {
+  try {
+    const stdout = execFileSync(file, args, {
+      encoding: "utf8",
+      maxBuffer: 32 * 1024 * 1024,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    return { ok: true, stdout };
+  } catch {
+    // Non-zero exit or a missing binary. Either way there is no usable diff;
+    // the caller decides whether to degrade or report.
+    return { ok: false, stdout: "" };
+  }
+}
+
+/** Control subcommands of `/workflows` that take a run id. */
+export type WorkflowControlSubcommand = "stop" | "pause" | "resume" | "rm";
+
+/**
+ * Resolve which run a `/workflows <subcommand>` invocation acts on.
+ *
+ * `stop` and `rm` are destructive — stopping kills the run's owned agents, and
+ * `rm` deletes the run and its journal — so they take no implicit target: a
+ * bare `/workflows rm` must never act on whatever `list()` happens to return
+ * first. `pause` and `resume` are reversible, so they keep the convenience
+ * default for the common single-run case.
+ *
+ * Returns the empty string when the caller must be asked for an explicit id.
+ */
+export function resolveControlTarget(
+  subcommand: WorkflowControlSubcommand,
+  explicitRunId: string,
+  firstListedRunId: string | undefined,
+): string {
+  if (explicitRunId) return explicitRunId;
+  if (subcommand === "stop" || subcommand === "rm") return "";
+  return firstListedRunId ?? "";
+}
+
+function formatStart(result: ScriptStartResult): string {
   const lines = [
     `Workflow ${result.background ? "started in background" : result.status}: ${result.runId}`,
     `status=${result.status}`,
@@ -94,16 +124,62 @@ export default function piWorkflows(pi: ExtensionAPI): void {
   let protocolCheck: Promise<void> = Promise.resolve();
   let active = false;
   let unsubscribeTreeSignal: (() => void) | undefined;
-  let branchQuiesce: Promise<WorkflowQuiesceResult> | undefined;
+  let branchQuiesce: Promise<{ settled: boolean; pending: string[]; diagnostic?: string }> | undefined;
   let lifecycleGeneration = 0;
-  let branchGeneration = 0;
   let protocolAbortController: AbortController | undefined;
+  let sessionCwd = process.cwd();
+  let workflowSettings = loadWorkflowSettings(sessionCwd);
+  let effortLevel: "off" | "high" | "ultra" = workflowSettings.effort;
+  /** Per-session delivery endpoint for background-run results (A10 fail-closed). */
+  let deliverResult: ((text: string, details?: unknown) => void) | undefined;
+  /** Pending deliveries for runs that settled before a session endpoint was bound (A10). */
+  const pendingDeliveryMarkers = new Map<string, { text: string; timestamp: number }>();
+  const PENDING_DELIVERY_TYPE = "pi-workflows:pending-delivery";
+  const PENDING_DELIVERY_ACK_TYPE = "pi-workflows:pending-delivery-ack";
+  const MAX_PENDING_DELIVERIES = 256;
+  const PENDING_DELIVERY_TTL_MS = 7 * 24 * 60 * 60 * 1_000;
+  let widgetTimer: ReturnType<typeof setInterval> | undefined;
 
   const currentEngine = (): WorkflowEngine => {
     if (!engine) throw new Error("pi-workflows is not active in this session context");
     return engine;
   };
 
+  const branchEntries = (): SessionEntryLike[] => {
+    const ctx = (pi as unknown as { currentSessionManager?: { getBranch?: () => unknown } }).currentSessionManager;
+    try {
+      return (ctx?.getBranch?.() as SessionEntryLike[] | undefined) ?? [];
+    } catch {
+      return [];
+    }
+  };
+
+  const DEFAULT_EXCLUDED_TOOLS = ["workflow", "workflow_control"] as const;
+
+  const resolveScript = (
+    script: string | undefined,
+    name: string | undefined,
+    args: unknown,
+  ): { script: string; source: string; toolset?: string } => {
+    if (script !== undefined && name !== undefined) {
+      throw new Error("Provide either `script` or `name`, not both.");
+    }
+    if (script !== undefined) return { script, source: "inline" };
+    if (name !== undefined) {
+      const saved = loadSavedWorkflow(name, sessionCwd);
+      if (saved) return { script: saved, source: `saved:${name}` };
+      const builtin = BUILTIN_WORKFLOWS[name];
+      if (builtin) {
+        // Validate named invocations before starting a potentially expensive fleet.
+        // Slash commands provide the same shape through their descriptor primaryArg.
+        validateBuiltinArgs(name, args);
+        return { script: builtin.script, source: `builtin:${name}`, toolset: builtin.toolset };
+      }
+      throw new Error(`Unknown workflow name "${name}". It is neither a saved workflow nor a built-in.`);
+    }
+    throw new Error("Provide either `script` or `name`.");
+  };
+
   const registerSurface = (): void => {
     if (active) return;
     active = true;
@@ -114,16 +190,19 @@ export default function piWorkflows(pi: ExtensionAPI): void {
         name: "workflow",
         label: "Workflow",
         description:
-          "Run a strict declarative task DAG through pi-subagents. Workflows submit subagent_type, prompt, description, and an optional semantic tier; execution policy belongs to pi-subagents.",
-        promptSnippet: "Run independent tasks as a dependency-aware workflow",
+          "Run a JavaScript workflow script through the pi-subagents managed spawning protocol. The script declares `export const meta = { name, description, phases }` first and uses the runtime globals agent(), parallel(), pipeline(), workflow(), verify(), judgePanel(), loopUntilDry(), completenessCheck(), retry(), gate(), checkpoint(), phase(), log(), args, cwd, process, and budget. Determinism is enforced: Date.now()/Math.random()/new Date() are unavailable.",
+        promptSnippet: "Run a JavaScript workflow script",
         promptGuidelines: [
-          "Use workflow for explicit multi-task DAG orchestration; an optional tier must be small, medium, or large. Do not include model, thinking, concurrency, retry, timeout, or turn-limit settings.",
-          "depends_on controls ordering only. To pass a dependency's result into a task, also list it in inputs, which must be a subset of that task's depends_on; those results are appended to the task prompt under a bounded budget.",
-          "Use workflow_control to inspect, pause, resume, or stop a background workflow.",
+          "Provide either a full `script` (raw JavaScript with the meta contract first) or a `name` of a saved/built-in workflow.",
+          "Use parallel(() => agent(...), ...) for concurrent agents; pipeline(items, ...stages) for sequential per-item stages.",
+          "Use background: true for long runs; retrieve results with workflow_control.",
+          "Use resumeFromRunId with an edited script to replay the unchanged prefix from cache and re-run the rest live.",
+          "Do not include model, thinking, concurrency, retry, timeout, or turn-limit settings beyond the declared options.",
         ],
-        parameters: WorkflowSchema,
+        parameters: WorkflowToolSchema,
         renderCall(args, theme) {
-          return new Text(theme.fg("toolTitle", theme.bold(`Workflow ${args.name ?? ""}`)), 0, 0);
+          const label = args.name ?? (args.script !== undefined ? "script" : "");
+          return new Text(theme.fg("toolTitle", theme.bold(`Workflow ${label}`)), 0, 0);
         },
         renderResult(result, { expanded, isPartial }, theme) {
           const text = result.content[0]?.type === "text" ? result.content[0].text : "";
@@ -138,7 +217,7 @@ export default function piWorkflows(pi: ExtensionAPI): void {
             0,
           );
         },
-        async execute(_toolCallId, params, signal, _onUpdate, _ctx) {
+        async execute(_toolCallId, params, signal, _onUpdate, ctx) {
           try {
             await protocolCheck;
           } catch (error: unknown) {
@@ -147,8 +226,54 @@ export default function piWorkflows(pi: ExtensionAPI): void {
                 `${PROTOCOL_DIAGNOSTIC} Diagnostic: ${error instanceof Error ? error.message : String(error)}`,
             );
           }
-          const definition = validateWorkflow(params);
-          const result = await workflowEngine.start(definition, signal);
+          const resolved =
+            params.resumeFromRunId && params.script === undefined && params.name === undefined
+              ? (() => {
+                  const prior = workflowEngine.getRun(params.resumeFromRunId);
+                  if (!prior) throw new Error(`Workflow run not found: ${params.resumeFromRunId}`);
+                  return { script: prior.script, source: "resume", toolset: prior.toolset };
+                })()
+              : resolveScript(params.script, params.name, params.args);
+          const { script, source, toolset } = resolved;
+          const options: ScriptStartOptions = {
+            args: params.args,
+            background: params.background ?? true,
+            maxAgents: params.maxAgents,
+            concurrency: params.concurrency,
+            agentRetries: params.agentRetries,
+            tokenBudget: params.tokenBudget,
+            agentTimeoutMs: params.agentTimeoutMs,
+            toolset,
+            excludeTools: [...DEFAULT_EXCLUDED_TOOLS],
+            signal,
+            mainModel: ctx?.model?.id,
+            // Foreground checkpoint confirmation only when the run is not
+            // background — background runs are headless by contract.
+            confirm:
+              params.background === false && ctx?.hasUI && ctx.mode === "tui"
+                ? async (promptText, checkpointOptions) => {
+                    if (checkpointOptions.kind === "input")
+                      return ctx.ui.input(promptText, String(checkpointOptions.default ?? ""));
+                    if (checkpointOptions.kind === "select")
+                      return ctx.ui.select(promptText, checkpointOptions.choices ?? []);
+                    return ctx.ui.confirm(promptText, promptText);
+                  }
+                : undefined,
+            loadSavedWorkflow: (name) => loadSavedWorkflow(name, sessionCwd) ?? BUILTIN_WORKFLOWS[name]?.script,
+          };
+          if (params.resumeFromRunId) {
+            const replacement = params.script !== undefined || params.name !== undefined ? script : undefined;
+            const resumed = await workflowEngine.resume(params.resumeFromRunId, branchEntries(), options, replacement);
+            if (!resumed) return textResult(`Workflow run not found: ${params.resumeFromRunId}`);
+            if (resumed.background) void deliverBackgroundResult(workflowEngine, resumed.runId);
+            return textResult(formatStart(resumed), resumed);
+          }
+          const result = await workflowEngine.start(script, options);
+          if (result.background) {
+            // The engine resolves the script's meta name for the delivery header.
+            void source;
+            void deliverBackgroundResult(workflowEngine, result.runId);
+          }
           return textResult(formatStart(result), result);
         },
       }),
@@ -158,7 +283,8 @@ export default function piWorkflows(pi: ExtensionAPI): void {
       defineTool({
         name: "workflow_control",
         label: "Workflow Control",
-        description: "List, inspect, pause, resume, or stop workflow runs with bounded machine-readable output.",
+        description:
+          "List, inspect, pause, resume, stop, or remove workflow runs with bounded machine-readable output.",
         parameters: ControlSchema,
         renderCall(args, theme) {
           return new Text(theme.fg("toolTitle", theme.bold(`Workflow control: ${args.action ?? ""}`)), 0, 0);
@@ -167,25 +293,385 @@ export default function piWorkflows(pi: ExtensionAPI): void {
           const text = result.content[0]?.type === "text" ? result.content[0].text : "";
           return new Text(theme.fg("dim", expanded ? text.slice(0, 8_000) : text.slice(0, 1_000)), 0, 0);
         },
-        async execute(_toolCallId, params) {
-          const action = params.action as "list" | "get" | "pause" | "resume" | "stop";
-          if (!["list", "get", "pause", "resume", "stop"].includes(action)) {
+        async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+          const rawAction = params.action as string;
+          const action = (rawAction === "status" ? "get" : rawAction) as
+            | "list"
+            | "get"
+            | "pause"
+            | "resume"
+            | "stop"
+            | "rm";
+          if (!["list", "get", "pause", "resume", "stop", "rm"].includes(action)) {
             throw new Error(`unknown workflow_control action: ${params.action}`);
           }
-          const result = await workflowEngine.control(action, params.run_id);
+          const runId = normalizeControlRunId(params as unknown as Record<string, unknown>);
+          const result = await workflowEngine.control(action, runId);
           return textResult(JSON.stringify(result), result);
         },
       }),
     );
 
+    // /workflows: navigator + run/status/watch/stop/pause/resume/rm/save subcommands
     pi.registerCommand("workflows", {
-      description: "Open the workflow run navigator",
+      description: "Workflow runs: open the navigator, or run/status/watch/stop/pause/resume/rm/save",
+      handler: async (args: string, ctx: ExtensionCommandContext) => {
+        const tokens = args.trim().split(/\s+/).filter(Boolean);
+        const [subcommand, ...rest] = tokens;
+        const restArgs = rest.join(" ").trim();
+        if (!subcommand) {
+          await showWorkflowNavigator(ctx, workflowEngine);
+          return;
+        }
+        if (subcommand === "run") {
+          if (!restArgs) {
+            ctx.ui.notify("/workflows run <prompt-or-script>", "warning");
+            return;
+          }
+          const runId = await runWorkflowFromPrompt(ctx, restArgs);
+          if (runId) ctx.ui.notify(`Workflow started in background: ${runId}`, "info");
+          return;
+        }
+        if (subcommand === "status") {
+          if (restArgs) {
+            const run = workflowEngine.getRun(restArgs);
+            if (!run) {
+              ctx.ui.notify(`Workflow run not found: ${restArgs}`, "warning");
+              return;
+            }
+            ctx.ui.notify(`${run.runId} · ${run.status} · ${String(run.meta?.name ?? run.runId)}`, "info");
+            return;
+          }
+          const runs = workflowEngine.list();
+          ctx.ui.notify(
+            runs.length === 0
+              ? "No workflow runs."
+              : runs.map((r) => `${r.runId} · ${r.status} · ${String(r.name)}`).join("\n"),
+            "info",
+          );
+          return;
+        }
+        if (subcommand === "watch") {
+          const runId = restArgs || String(workflowEngine.list()[0]?.runId ?? "");
+          if (!runId) {
+            ctx.ui.notify("No workflow runs to watch.", "warning");
+            return;
+          }
+          const run = await workflowEngine.waitFor(runId).catch(() => undefined);
+          if (run) ctx.ui.notify(`${run.runId} settled as ${run.status}`, "info");
+          return;
+        }
+        if (subcommand === "stop" || subcommand === "pause" || subcommand === "resume" || subcommand === "rm") {
+          const firstListed = workflowEngine.list()[0]?.runId;
+          const runId = resolveControlTarget(
+            subcommand,
+            restArgs,
+            firstListed === undefined ? undefined : String(firstListed),
+          );
+          if (!runId) {
+            const destructive = subcommand === "stop" || subcommand === "rm";
+            ctx.ui.notify(
+              destructive
+                ? `/workflows ${subcommand} <runId> — a run id is required; /workflows status lists them`
+                : `/workflows ${subcommand} <runId>`,
+              "warning",
+            );
+            return;
+          }
+          try {
+            await workflowEngine.control(subcommand, runId);
+            if (subcommand === "resume") void deliverBackgroundResult(workflowEngine, runId);
+            ctx.ui.notify(`Workflow ${subcommand} requested: ${runId}`, "info");
+          } catch (error: unknown) {
+            ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+          }
+          return;
+        }
+        if (subcommand === "save") {
+          const name = rest[0] ?? "";
+          if (!name) {
+            ctx.ui.notify("/workflows save <name> [runId]", "warning");
+            return;
+          }
+          // Fallback to most recent run when runId omitted — matches upstream runs.find(r=>r.script)
+          const runId = rest[1] ?? String(workflowEngine.list()[0]?.runId ?? "");
+          if (!runId) {
+            ctx.ui.notify("No workflow runs to save.", "warning");
+            return;
+          }
+          try {
+            await saveWorkflowFromRun(ctx, name, runId);
+          } catch (error: unknown) {
+            ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+          }
+          return;
+        }
+        ctx.ui.notify(`Unknown /workflows subcommand: ${subcommand}`, "warning");
+      },
+    });
+
+    // /workflows-models: tier configuration is owned by pi-subagents; this
+    // command documents the delegation (A8: no second tier config file).
+    pi.registerCommand("workflows-models", {
+      description: "Workflow tier routing: tiers are configured in pi-subagents /agents → Model tiers",
       handler: async (_args: string, ctx: ExtensionCommandContext) => {
-        await showWorkflowNavigator(ctx, workflowEngine);
+        ctx.ui.notify(
+          "Workflow tiers (small/medium/large) route through pi-subagents' workflow.tiers settings. " +
+            "Use /agents → Model tiers to configure them.",
+          "info",
+        );
+      },
+    });
+
+    // /workflows-progress: persistent compact/detailed live-panel settings.
+    pi.registerCommand("workflows-progress", {
+      description: "Workflow progress panel: compact|detailed|status|max <N>",
+      handler: async (args: string, ctx: ExtensionCommandContext) => {
+        const tokens = args.trim().split(/\s+/).filter(Boolean);
+        const action = tokens[0] ?? "status";
+        if (action === "status") {
+          ctx.ui.notify(
+            `Workflow progress: ${workflowSettings.progressMode}, max agents shown: ${workflowSettings.maxAgentsShown}`,
+            "info",
+          );
+          return;
+        }
+        if (action === "compact" || action === "detailed") {
+          workflowSettings = { ...workflowSettings, progressMode: action };
+        } else if (action === "max") {
+          const max = Number(tokens[1]);
+          if (!Number.isInteger(max) || max < 1 || max > 32) {
+            ctx.ui.notify("Usage: /workflows-progress max <1-32>", "warning");
+            return;
+          }
+          workflowSettings = { ...workflowSettings, maxAgentsShown: max };
+        } else {
+          ctx.ui.notify("Usage: /workflows-progress compact|detailed|status|max <N>", "warning");
+          return;
+        }
+        try {
+          saveWorkflowSettings(workflowSettings, sessionCwd);
+          refreshWidget();
+          ctx.ui.notify(
+            `Workflow progress set to ${workflowSettings.progressMode}, max ${workflowSettings.maxAgentsShown}.`,
+            "info",
+          );
+        } catch (error: unknown) {
+          ctx.ui.notify(
+            `Could not save workflow progress settings: ${error instanceof Error ? error.message : String(error)}`,
+            "warning",
+          );
+        }
+      },
+    });
+
+    // /workflows-trigger: keyword arming (A5). Typing the bounded word
+    // `workflow`/`workflows` — or a configured synonym — in an ordinary message
+    // counts as an explicit opt-in to multi-agent orchestration, and the message
+    // is annotated to say so. Arming AUTHORIZES the tool; it never forces a run,
+    // and it never opens UI. A user asking a question about workflows still gets
+    // an ordinary answer.
+    let triggerKeyword: string | undefined = workflowSettings.keywordTriggerWord;
+    let keywordTriggerEnabled = workflowSettings.keywordTriggerEnabled;
+    const TRIGGER_WORD_PATTERN = /^[A-Za-z][A-Za-z0-9_-]{0,31}$/u;
+    const persistTriggerSettings = (): void => {
+      workflowSettings = { ...workflowSettings, keywordTriggerWord: triggerKeyword, keywordTriggerEnabled };
+      try {
+        saveWorkflowSettings(workflowSettings, sessionCwd);
+      } catch {
+        /* setting changes remain active in memory */
+      }
+    };
+    pi.registerCommand("workflows-trigger", {
+      description: "Arm the workflow tool on a keyword: set <keyword> | off | on | reset | status",
+      handler: async (args: string, ctx: ExtensionCommandContext) => {
+        const token = args.trim().split(/\s+/)[0] ?? "";
+        if (token === "off") {
+          keywordTriggerEnabled = false;
+          persistTriggerSettings();
+          ctx.ui.notify("Workflow keyword trigger disabled.", "info");
+          return;
+        }
+        if (token === "on") {
+          keywordTriggerEnabled = true;
+          persistTriggerSettings();
+          ctx.ui.notify(`Workflow keyword trigger armed on "${triggerKeyword ?? DEFAULT_TRIGGER_WORD}".`, "info");
+          return;
+        }
+        if (token === "reset") {
+          triggerKeyword = undefined;
+          keywordTriggerEnabled = true;
+          persistTriggerSettings();
+          ctx.ui.notify(`Workflow keyword trigger reset to default "${DEFAULT_TRIGGER_WORD}".`, "info");
+          return;
+        }
+        if (token === "status") {
+          ctx.ui.notify(
+            `Workflow keyword trigger: ${keywordTriggerEnabled ? "armed" : "disabled"} on "${triggerKeyword ?? DEFAULT_TRIGGER_WORD}"`,
+            "info",
+          );
+          return;
+        }
+        const keyword = token === "set" ? (args.trim().split(/\s+/)[1] ?? "") : token;
+        if (!TRIGGER_WORD_PATTERN.test(keyword)) {
+          ctx.ui.notify("Usage: /workflows-trigger set <one-word-keyword> | off | on | reset | status", "warning");
+          return;
+        }
+        triggerKeyword = keyword.toLowerCase();
+        keywordTriggerEnabled = true;
+        persistTriggerSettings();
+        ctx.ui.notify(`Workflow keyword trigger armed on "${keyword}".`, "info");
+      },
+    });
+
+    // Keyword arming input hook (A5). The message is annotated rather than
+    // acted on: the model is told it may use the `workflow` tool and may still
+    // decline, which is what keeps "how do workflows work?" an ordinary
+    // question. Nothing is swallowed and no UI opens.
+    pi.on("input", (event) => {
+      if (event.source === "extension") return { action: "continue" as const };
+      const explicitTrigger = keywordTriggerEnabled && hasTriggerWord(event.text, triggerKeyword);
+      const substantive = effortLevel !== "off" && event.text.trim().length >= 16 && !event.text.trim().startsWith("/");
+      if (!explicitTrigger && !substantive) return { action: "continue" as const };
+      if (event.text.includes(WORKFLOW_ARMED_DIRECTIVE)) return { action: "continue" as const };
+      const effortDirective =
+        effortLevel === "ultra"
+          ? "Effort: ULTRA. Be exhaustive: use broad parallel review, verification, and completeness checks; choose the large tier where useful."
+          : effortLevel === "high"
+            ? "Effort: HIGH. Be thorough: use several independent reviewers and an adversarial verification pass."
+            : "";
+      return {
+        action: "transform" as const,
+        text: `${event.text}\n\n${WORKFLOW_ARMED_DIRECTIVE}${effortDirective ? `\n${effortDirective}` : ""}`,
+        ...(event.images ? { images: event.images } : {}),
+      };
+    });
+
+    // Standing effort mode mirrors the reference: it auto-arms substantive
+    // interactive messages but remains guidance, not an inferred spend ceiling.
+    pi.registerCommand("effort", {
+      description: "Standing workflow effort: off | high | ultra",
+      handler: async (args: string, ctx: ExtensionCommandContext) => {
+        const level = args.trim().toLowerCase();
+        if (level !== "off" && level !== "high" && level !== "ultra") {
+          ctx.ui.notify(`Effort is currently "${effortLevel}". Usage: /effort off|high|ultra`, "info");
+          return;
+        }
+        effortLevel = level;
+        workflowSettings = { ...workflowSettings, effort: effortLevel };
+        try {
+          saveWorkflowSettings(workflowSettings, sessionCwd);
+        } catch {
+          /* warning is non-fatal */
+        }
+        ctx.ui.notify(
+          level === "off"
+            ? "Effort off — messages are no longer auto-armed."
+            : `Effort ${level} enabled for substantive messages.`,
+          "info",
+        );
+      },
+    });
+    pi.registerCommand("ultracode", {
+      description: "Ultracode: toggle exhaustive workflow effort",
+      handler: async (args: string, ctx: ExtensionCommandContext) => {
+        effortLevel = args.trim().toLowerCase() === "off" ? "off" : "ultra";
+        workflowSettings = { ...workflowSettings, effort: effortLevel };
+        try {
+          saveWorkflowSettings(workflowSettings, sessionCwd);
+        } catch {
+          /* warning is non-fatal */
+        }
+        ctx.ui.notify(
+          effortLevel === "off"
+            ? "Ultracode off."
+            : "Ultracode on — substantive messages use exhaustive workflow guidance.",
+          "info",
+        );
       },
     });
 
-    const beginBranchQuiesce = (): Promise<WorkflowQuiesceResult> => {
+    // Builtin workflow commands (A6). Saved workflows with the same name take
+    // precedence at resolution; the commands themselves still dispatch by name.
+    // Names already claimed by another extension are left alone — Pi cannot
+    // unregister or replace a command, so clobbering one is permanent.
+    const claimedCommands = new Set((pi.getCommands?.() ?? []).map((command) => command.name));
+    for (const name of Object.keys(BUILTIN_WORKFLOWS)) {
+      if (claimedCommands.has(name)) continue;
+      const descriptor = BUILTIN_WORKFLOWS[name];
+      pi.registerCommand(name, {
+        description: `Run the ${name} workflow`,
+        handler: async (args: string, ctx: ExtensionCommandContext) => {
+          const text = args.trim();
+          // Each script reads its own named input; none reads a generic
+          // `prompt`, so the text goes in under `primaryArg`. `code-review`
+          // takes a diff rather than something typed, so it resolves one first.
+          let scriptArgs: Record<string, unknown> | undefined;
+          if (name === "code-review") {
+            const scope = resolveCodeReviewScope(text, runCommand);
+            for (const notice of scope.notices) ctx.ui.notify(notice, "warning");
+            if (!scope.diff.trim()) return;
+            scriptArgs = { diff: scope.diff, diffSource: scope.diffSource };
+          } else {
+            scriptArgs = text ? { [descriptor.primaryArg]: text } : undefined;
+          }
+          try {
+            validateBuiltinArgs(name, scriptArgs);
+          } catch (error: unknown) {
+            ctx.ui.notify(error instanceof Error ? error.message : String(error), "warning");
+            return;
+          }
+          const options: ScriptStartOptions = {
+            args: scriptArgs,
+            background: true,
+            toolset: descriptor.toolset,
+            excludeTools: [...DEFAULT_EXCLUDED_TOOLS],
+            loadSavedWorkflow: (savedName) =>
+              loadSavedWorkflow(savedName, sessionCwd) ?? BUILTIN_WORKFLOWS[savedName]?.script,
+          };
+          const result = await workflowEngine.start(descriptor.script, options);
+          void deliverBackgroundResult(workflowEngine, result.runId);
+          ctx.ui.notify(`Workflow ${name} started in background: ${result.runId}`, "info");
+        },
+      });
+    }
+
+    // Live progress widget (A10): renders only while runs are active, then
+    // clears itself. The widget is TUI-only; headless sessions skip it.
+    const refreshWidget = () => {
+      const tui = (pi as unknown as { ui?: { setWidget?: (key: string, content: string[] | undefined) => void } }).ui;
+      if (!tui?.setWidget) return;
+      const runs = workflowEngine
+        .list()
+        .map((summary) => workflowEngine.getRun(String(summary.runId)))
+        .filter((run): run is NonNullable<typeof run> => run !== undefined);
+      const lines = liveWidgetLines(runs, workflowSettings.progressMode, workflowSettings.maxAgentsShown);
+      tui.setWidget("pi-workflows", lines.length > 0 ? lines : undefined);
+      if (lines.length > 0 && !widgetTimer) {
+        widgetTimer = setInterval(() => {
+          if (!tui?.setWidget) return;
+          const current = workflowEngine
+            .list()
+            .map((summary) => workflowEngine.getRun(String(summary.runId)))
+            .filter((run): run is NonNullable<typeof run> => run !== undefined);
+          const next = liveWidgetLines(current, workflowSettings.progressMode, workflowSettings.maxAgentsShown);
+          tui.setWidget("pi-workflows", next.length > 0 ? next : undefined);
+          if (next.length === 0 && widgetTimer) {
+            clearInterval(widgetTimer);
+            widgetTimer = undefined;
+          }
+        }, 2_000);
+      } else if (lines.length === 0 && widgetTimer) {
+        clearInterval(widgetTimer);
+        widgetTimer = undefined;
+      }
+    };
+    // Refresh after any control action and on run settlement.
+    const notifyRunChanged = () => refreshWidget();
+    workflowEngine.onRunSettled = notifyRunChanged;
+    void notifyRunChanged;
+
+    const beginBranchQuiesce = (): Promise<{ settled: boolean; pending: string[]; diagnostic?: string }> => {
       if (!branchQuiesce) {
         branchQuiesce = workflowEngine.quiesceForBranchChange().then((result) => {
           if (!result.settled) {
@@ -211,18 +697,12 @@ export default function piWorkflows(pi: ExtensionAPI): void {
       try {
         entries = ctx.sessionManager.getBranch() as unknown as SessionEntryLike[];
       } catch {
-        // A reload may invalidate the old lifecycle context before the tree
-        // callback is delivered. Do not let stale-context access escape.
         return;
       }
       workflowEngine.suspendLifecycle();
-      branchGeneration += 1;
       try {
-        workflowEngine.restore(entries, branchGeneration);
+        workflowEngine.restore(entries);
       } catch (error: unknown) {
-        // Keep the lifecycle surface alive after a failed recovery append. The
-        // engine rolls its candidate state back transactionally; a later tree
-        // event can retry the same branch without leaving workflows inert.
         console.warn(
           `[pi-workflows] session tree recovery failed: ${error instanceof Error ? error.message : String(error)}`,
         );
@@ -233,20 +713,102 @@ export default function piWorkflows(pi: ExtensionAPI): void {
     });
   };
 
+  const rememberPendingDelivery = (runId: string, text: string, timestamp = Date.now()): void => {
+    if (!runId || timestamp + PENDING_DELIVERY_TTL_MS < Date.now()) return;
+    pendingDeliveryMarkers.set(runId, { text: text.slice(0, 8_000), timestamp });
+    for (const [id, marker] of pendingDeliveryMarkers) {
+      if (marker.timestamp + PENDING_DELIVERY_TTL_MS < Date.now()) pendingDeliveryMarkers.delete(id);
+    }
+    while (pendingDeliveryMarkers.size > MAX_PENDING_DELIVERIES) {
+      const oldest = [...pendingDeliveryMarkers.entries()].sort((a, b) => a[1].timestamp - b[1].timestamp)[0]?.[0];
+      if (!oldest) break;
+      pendingDeliveryMarkers.delete(oldest);
+    }
+  };
+
+  /** Background-run result delivery: fail-closed, session-bound (A10). */
+  const deliverBackgroundResult = async (engine: WorkflowEngine, runId: string): Promise<void> => {
+    const run = await engine.waitFor(runId).catch(() => undefined);
+    if (!run) return;
+    const header = `Workflow ${run.runId} ${run.status}`;
+    const body = run.error ?? `completed with ${Object.keys(run.callResults).length} agent call(s).`;
+    const text = `${header}: ${body}`;
+    if (deliverResult) {
+      try {
+        deliverResult(text);
+      } catch {
+        // Endpoint suspended or send failed — leave pending for next bind (fail-closed).
+        rememberPendingDelivery(runId, text);
+        try {
+          pi.appendEntry(PENDING_DELIVERY_TYPE, { runId, text, status: run.status, timestamp: Date.now() });
+        } catch {
+          // appendEntry is best-effort; in-memory marker still ensures flush on next bind
+        }
+      }
+    } else {
+      // No bound session endpoint — fail-closed: persist a pending marker and
+      // flush it when a session binds, never fall back to shared pi.sendMessage.
+      rememberPendingDelivery(runId, text);
+      try {
+        pi.appendEntry(PENDING_DELIVERY_TYPE, { runId, text, status: run.status, timestamp: Date.now() });
+      } catch {
+        // best-effort persistence; in-memory marker still ensures retry
+      }
+    }
+  };
+
+  const flushPendingDeliveries = (): void => {
+    if (!deliverResult || pendingDeliveryMarkers.size === 0) return;
+    for (const [runId, pending] of [...pendingDeliveryMarkers]) {
+      try {
+        deliverResult(pending.text);
+        pi.appendEntry(PENDING_DELIVERY_ACK_TYPE, { runId, timestamp: Date.now() });
+        pendingDeliveryMarkers.delete(runId);
+      } catch {
+        // Keep pending until both delivery and its durable acknowledgement succeed.
+      }
+    }
+  };
+
+  /** Build a script from a natural-language prompt and run it in background. */
+  const runWorkflowFromPrompt = async (ctx: ExtensionCommandContext, prompt: string): Promise<string | undefined> => {
+    // A bounded, deterministic script that dispatches the user's instruction
+    // through a general-purpose agent and returns its answer.
+    const script = `export const meta = { name: "ad-hoc", description: "Run a user-requested task with a general-purpose agent" };
+const answer = await agent(${JSON.stringify(prompt)});
+return answer;`;
+    try {
+      const result = await currentEngine().start(script, { background: true, mainModel: ctx.model?.id });
+      void deliverBackgroundResult(currentEngine(), result.runId);
+      return result.runId;
+    } catch (error: unknown) {
+      ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+      return undefined;
+    }
+  };
+
+  const saveWorkflowFromRun = async (ctx: ExtensionCommandContext, name: string, runId?: string): Promise<void> => {
+    const state = engine?.getState(runId ?? "");
+    if (!state) {
+      throw new Error(`Workflow run not found: ${runId ?? "(none)"}`);
+    }
+    saveWorkflow(name, state.run.script, sessionCwd);
+    ctx.ui.notify(`Saved workflow "${name}" (${state.run.script.length} chars).`, "info");
+  };
+
   pi.on("session_start", async (_event, ctx) => {
     if (active || engine) return;
     const generation = ++lifecycleGeneration;
+    sessionCwd = ctx.cwd ?? process.cwd();
+    workflowSettings = loadWorkflowSettings(sessionCwd);
+    effortLevel = workflowSettings.effort;
     let initialEntries: SessionEntryLike[];
     try {
       initialEntries = ctx.sessionManager.getBranch() as unknown as SessionEntryLike[];
     } catch {
-      // The lifecycle context may already be invalid during a reload race.
       return;
     }
 
-    // Dispatch the formal child-context query synchronously. The event bus
-    // delivers the reply synchronously, which lets us filter child sessions
-    // before registering any Pi tools while keeping startup nonblocking.
     let child: boolean | undefined;
     try {
       child = queryChildSessionContextImmediate(pi.events);
@@ -256,27 +818,31 @@ export default function piWorkflows(pi: ExtensionAPI): void {
     if (child === true) return;
 
     protocolAbortController = new AbortController();
-    // Tool-call signals only cancel the foreground wait. Managed RPCs use this
-    // session-lifetime controller so a host with no ctx.signal still cancels
-    // outstanding requests during session_shutdown.
     const client = createManagedSpawnClient(pi.events, protocolAbortController.signal, protocolAbortController.signal);
 
-    // Recovery appends can fail transiently (for example while Pi is flushing a
-    // branch). Build and restore a disposable candidate, retrying against the
-    // latest branch snapshot before exposing the workflow surface. Never leave
-    // `engine` assigned while restore is half-complete.
     let recoveredEngine: WorkflowEngine | undefined;
     let recoveryError: unknown;
     for (let attempt = 0; attempt < 3 && !recoveredEngine; attempt += 1) {
-      const candidate = new WorkflowEngine(pi.events, client, {
-        append(event) {
-          pi.appendEntry(JOURNAL_ENTRY_TYPE, event);
+      const candidate = new WorkflowEngine(
+        pi.events,
+        client,
+        {
+          append(event) {
+            pi.appendEntry(JOURNAL_ENTRY_TYPE, event);
+          },
         },
-      });
+        () => {
+          try {
+            return (ctx.sessionManager.getBranch() as unknown as SessionEntryLike[]) ?? [];
+          } catch {
+            return [];
+          }
+        },
+      );
       try {
         const entries =
           attempt === 0 ? initialEntries : (ctx.sessionManager.getBranch() as unknown as SessionEntryLike[]);
-        candidate.restore(entries, branchGeneration);
+        candidate.restore(entries);
         recoveredEngine = candidate;
       } catch (error: unknown) {
         recoveryError = error;
@@ -294,35 +860,116 @@ export default function piWorkflows(pi: ExtensionAPI): void {
     }
 
     engine = recoveredEngine;
-    branchGeneration = 0;
     registerSurface();
 
+    // Bind per-session delivery endpoint (A10): capture the session-bound send
+    // at this moment so completions deliver to the originating session, not
+    // whichever session happens to be current later. Never fall back to the
+    // shared pi.sendMessage — a missing or suspended endpoint leaves the
+    // result pending and flushes on the next successful bind (fail-closed).
+    try {
+      const capturedSend = pi.sendMessage;
+      if (typeof capturedSend === "function") {
+        deliverResult = (text: string) => {
+          // Use the captured function value for session affinity; if the
+          // captured function is itself a shared accessor, the flush is still
+          // fail-closed (delivery only when bound).
+          (capturedSend as unknown as (message: unknown, options: unknown) => unknown).call(
+            pi,
+            {
+              content: text,
+              display: true,
+              customType: "pi-workflows:delivery",
+            },
+            { deliverAs: "followUp", triggerTurn: true },
+          );
+        };
+      }
+    } catch {
+      // binding is best-effort; pending stays buffered
+    }
+    // Hydrate any pending markers persisted before this bind (e.g. runs that
+    // settled before the first session_start) — scan the branch for
+    // PENDING_DELIVERY_TYPE entries that have no in-memory counterpart.
+    try {
+      const acknowledged = new Set<string>();
+      for (const entry of initialEntries) {
+        const shaped = entry as { type?: unknown; customType?: unknown; data?: unknown };
+        if (shaped.type !== "custom" || typeof shaped.customType !== "string") continue;
+        const data = shaped.data as Record<string, unknown> | undefined;
+        const entryRunId = typeof data?.runId === "string" ? data.runId : undefined;
+        if (!entryRunId) continue;
+        if (shaped.customType === PENDING_DELIVERY_ACK_TYPE) {
+          acknowledged.add(entryRunId);
+        } else if (shaped.customType === PENDING_DELIVERY_TYPE) {
+          const pendingText = typeof data?.text === "string" ? data.text : undefined;
+          const timestamp = typeof data?.timestamp === "number" ? data.timestamp : Date.now();
+          if (pendingText && !acknowledged.has(entryRunId)) rememberPendingDelivery(entryRunId, pendingText, timestamp);
+        }
+      }
+      for (const runId of acknowledged) pendingDeliveryMarkers.delete(runId);
+    } catch {
+      // scan is best-effort
+    }
+    flushPendingDeliveries();
+
+    // Saved workflow commands register at session_start (Pi cannot unregister
+    // or replace command metadata, so factory-time registration would freeze the
+    // source project's description and survive cross-project resumes). Check for
+    // name clashes first — never overwrite another extension's command.
+    const existingCommands = new Set((pi.getCommands?.() ?? []).map((command) => command.name));
+    for (const savedName of listSavedWorkflows(sessionCwd)) {
+      if (existingCommands.has(savedName)) continue;
+      const script = loadSavedWorkflow(savedName, sessionCwd);
+      if (!script) continue;
+      pi.registerCommand(savedName, {
+        description: `Run the saved workflow ${savedName}`,
+        handler: async (args: string, commandCtx: ExtensionCommandContext) => {
+          const options: ScriptStartOptions = {
+            args: args.trim() ? { prompt: args.trim() } : undefined,
+            background: true,
+            mainModel: commandCtx?.model?.id,
+            loadSavedWorkflow: (name) => loadSavedWorkflow(name, sessionCwd) ?? BUILTIN_WORKFLOWS[name]?.script,
+          };
+          const result = await recoveredEngine.start(script, options);
+          void deliverBackgroundResult(recoveredEngine, result.runId);
+          commandCtx.ui.notify(`Workflow ${savedName} started in background: ${result.runId}`, "info");
+        },
+      });
+    }
+
     protocolError = undefined;
     protocolCheck = client.checkProtocol?.() ?? Promise.reject(new Error("managed protocol check is unavailable"));
     void protocolCheck.catch((error: unknown) => {
       if (generation !== lifecycleGeneration) return;
       const detail = error instanceof Error ? error.message : String(error);
-      // Missing pi-subagents is a valid independent-package activation state.
-      // Keep startup nonblocking and defer the bounded diagnostic to the next
-      // workflow tool call instead of logging a spurious startup error.
       protocolError = `${PROTOCOL_DIAGNOSTIC} Diagnostic: ${detail}`;
     });
   });
 
-  pi.on("session_shutdown", () => {
+  pi.on("session_shutdown", async () => {
     lifecycleGeneration += 1;
+    if (widgetTimer) {
+      clearInterval(widgetTimer);
+      widgetTimer = undefined;
+    }
+    const closingEngine = engine;
+    if (closingEngine) {
+      await closingEngine.quiesceForBranchChange().catch(() => undefined);
+    }
     protocolAbortController?.abort();
     protocolAbortController = undefined;
     unsubscribeTreeSignal?.();
     unsubscribeTreeSignal = undefined;
-    engine?.dispose();
+    closingEngine?.dispose();
     engine = undefined;
     active = false;
     branchQuiesce = undefined;
-    branchGeneration = 0;
     protocolCheck = Promise.resolve();
     protocolError = undefined;
+    deliverResult = undefined;
   });
 }
 
-export { validateWorkflow, WorkflowSchema };
+export type { ScriptStartResult };
+export { WorkflowWaitAbortedError };