@nicknisi/pi-workflows 0.2.2 → 0.3.0

package/README.md

@@ -8,8 +8,11 @@ Four pieces compose the workflow platform: `@nicknisi/pi-shared`'s **subagent ru
 
 ## What it adds
 
-- **`workflow` tool** (model-facing) — actions: `run` (inline JS `script` OR `name` of a saved workflow file), `list`, `status <runId>`, `stop <runId>`.
-- **`/wf` command** (human-facing) — `/wf list | /wf run <name> [argsJson] | /wf status <runId> | /wf stop <runId>`.
+- **`workflow` tool** (model-facing) — actions: `run` (inline JS `script` OR `name` of a saved workflow file), `list`, `status <runId>`, `stop <runId>`, `pause`, `resume`.
+- **`/wf` command** (human-facing) — `/wf list | /wf run <name> [argsJson] | /wf status <runId> | /wf stop <runId> | /wf pause | /wf resume`.
+- **Human gates inside scripts** — `checkpoint(label?)` pauses the run on a confirm dialog (reject/dismiss stops the run); `ask(question, options?)` asks mid-run (select with options, yes/no without, `undefined` when dismissed).
+- **Footer status** — while a run is active the footer shows `wf <name> [running|paused] <last phase>`.
+- **`autoplan` skill** — teaches the model the "autoplan this" trigger: run the saved `autoplan` workflow with args derived from the conversation, then respect the run's decision outcome. Disable with `"skills": ["-skills/autoplan"]` on the package entry.
 
 ## The script contract
 
@@ -30,14 +33,18 @@ return { answered: results.length, results };
 | `agent(prompt, opts)`        | Spawns a hermetic in-process child via the subagent runtime (namespace `workflows`). Throws `${kind}: ${error}` on failure — wrap with a `safeAgent` that returns `{ ok, value, error }` so a failure inside `parallel()` reports which stage died instead of collapsing the wave to `null`. Returns `res.data ?? res.text ?? null`. |
 | `parallel(thunks)`           | `Promise.all` over zero-arg thunks — pass `() => agent(...)`, not `agent(...)`.                                                                                                                                                                                                                                                      |
 | `pipeline(items, ...stages)` | Folds items through stages: each stage maps over the previous stage's outputs in parallel, producing the next array.                                                                                                                                                                                                                 |
-| `phase(name)`                | Logging marker only — NOT a budget boundary. Appends `── name` to the result logs.                                                                                                                                                                                                                                                   |
+| `phase(name)`                | Logging marker that also drives the footer status (`wf <name> [state] <phase>`). NOT a budget boundary.                                                                                                                                                                                                                              |
 | `log(...args)`               | Captured into the result logs.                                                                                                                                                                                                                                                                                                       |
+| `checkpoint(label?)`         | Human gate: suspends the run on a confirm dialog; rejecting throws and stops the run. Without a UI host it is a logged no-op. Put it before destructive or expensive steps.                                                                                                                                                          |
+| `ask(question, options?)`    | Human answer mid-run: a select when `options` are given, a yes/no confirm otherwise; `undefined` when dismissed. Without a UI host it throws — never invent an answer.                                                                                                                                                               |
 | `args`                       | The `args` JSON value passed to `run`.                                                                                                                                                                                                                                                                                               |
 | `budget`                     | `{ total, spent, remaining }` over the run's token usage. `total` defaults to `Infinity`; `spent` accumulates across `agent()` calls. Read-only.                                                                                                                                                                                     |
 | `cwd`                        | The session working directory.                                                                                                                                                                                                                                                                                                       |
 
 `agent()` opts: `model` (`'provider/id'`), `tools` (allowlist — default read-only `['read','grep','find','ls']`; pass `['read','bash','edit','write']` for builders), `label` (child agent label), `systemPrompt`, `schema` (validated; parsed JSON lands in `result.data`), `effort` (thinking level), `timeoutMs`, `maxTurns`, `worktree` (run the child in an isolated git worktree; on settle the change set is captured to a `.patch` and `agent()` returns `{ value, patchPath, runId }` instead of the bare value — opt-in, so non-worktree calls are unchanged), `agentType` (accepted but ignored — no agent-type registry; resolve `systemPrompt` in the script itself).
 
+`agent()` awaits the run's pause gate before every spawn: `pause` lets the in-flight step finish, then holds the run before the next one; `resume` releases it. Pause/resume are session-scoped (`/wf pause`, `/wf resume`, or the tool actions) — they apply to every active run, in practice one. Stopping or timing out a run aborts the gate, so a parked run rejects instead of hanging.
+
 The script executes **in the host process with full Node access** — `process`, `require`, and `fs` are all reachable, the same trust boundary as the `bash` tool. Keep the returned value small: summaries, counts, key findings — never raw file dumps.
 
 ## Saved workflows
@@ -71,6 +78,9 @@ The `examples/` directory ships standalone, copy-and-adapt workflow scripts —
 - **`lanes.js`** — N parallel agents editing FILE-DISJOINT lanes of one repo under a hard-rules preamble (each lane owns a fixed file set; no git, no installs; the parent integrates centrally). Use it when a task splits into independent edits that don't overlap on files. Adapt by setting `VERIFY` to your typecheck command and filling the `LANES` array with `{ name, files, brief }` per lane.
 - **`gates.js`** — three judge/verify prompt builders returning prompt strings: adversarial refutation (defeats confirmation bias), deep-research coverage (defeats silent source omission), and a 3-way code-review verdict (defeats verdict collapse). Use it when you need a reliable gate inside your own workflow. Adapt by copying the builder whose failure mode you need and calling it from an `agent()` with a JSON schema. Prompt patterns distilled from `@quintinshaw/pi-dynamic-workflows`.
 - **`bake-off.js`** — race N models on the SAME task in isolated worktrees (`worktree: true`), then an advisory judge reads each contender's `.patch` and picks a winner. Use it on hard build tasks where a single GLM-5.2-class builder produces decent-but-flawed code; the 2x token cost buys a measurably better hit rate. Adapt by setting `CONTENDERS` to the models to race and passing `task` in `args`; the workflow returns the winner's `patchPath` to apply via `/patches`.
+- **`autoplan.js`** — 3 solution candidates in parallel + a Holy Grail pass, an advisor that ranks with a recommendation (curbing Grail ideas that need upstream changes), then the HUMAN decides via `ask()` — recommendation on top, reject-all always offered — and the chosen option gets the full plan write. Ported from osolmaz/pi-workflows' decision-gate demo. Pass `{ problem, scope, constraints }` in `args`, or say "autoplan this" and the bundled `autoplan` skill derives the args from the conversation.
+- **`sanity-check.js`** — read-only contribution review: evidence collection, four parallel area reviewers (necessity, duplication, contracts, scope/tests), then a verifier that tries to REFUTE every finding before the keep/simplify/refactor/drop/needs-evidence verdict. Ported from osolmaz/pi-workflows. Pass `{ baseRef }` in `args`.
+- **`autoimplement.js`** — implement a supplied plan (never devises one) behind an `ask` plan gate, then a bounded build → verify → review/fix loop where P0/P1 block and the round cap prevents an unbounded fix spiral. Ported from osolmaz/pi-workflows. Pass `{ task, plan, verify }` in `args`.
 
 ## Dependencies
 
@@ -81,6 +91,8 @@ The `examples/` directory ships standalone, copy-and-adapt workflow scripts —
 ## Caveats
 
 - The script runs in the host process with full Node access — the same trust boundary as the `bash` and `codemode` tools. Your model, your session.
+- `checkpoint`/`ask` need an interactive UI host. In a headless/RPC host `checkpoint` degrades to a logged no-op and `ask` throws — scripts that require an answer fail loudly instead of inventing one.
+- Pause/resume are session-scoped and best-effort for tool-initiated runs: slash commands may queue behind an in-flight turn, so a `pause` issued mid-turn engages at the next `agent()` boundary after it's processed. For a guaranteed human gate, put `checkpoint`/`ask` in the script itself.
 - Project-local workflows (`.pi/workflows/`) load only in trusted projects; untrusted projects are limited to global workflows so a cloned repo cannot silently inject orchestration scripts.
 - `agent()` cannot spawn children of its own (the ecosystem recursion guard refuses nested orchestration). For dependent multi-stage work where stages spawn, use `@nicknisi/pi-codemode`'s `runWorkflow` instead.
 - `stop` cancels only runs spawned by this host process; persisted runs from other hosts show in `status` but are not cancellable here.

package/dist/engine.d.ts

@@ -2,7 +2,7 @@
  * The workflow script engine — pi-free and testable.
  *
  * A workflow script is a JavaScript statement body with injected globals
- * (args, agent, parallel, pipeline, phase, log, budget, cwd) and a leading
+ * (args, agent, parallel, pipeline, phase, log, budget, cwd, checkpoint, ask) and a leading
  * `export const meta = { name, description }` declaration. It returns a value
  * by evaluating a trailing expression or a top-level `return` (the body is
  * wrapped in an async function so a bare `return` compiles).
@@ -59,6 +59,17 @@ export interface EngineBudget {
     spent: number;
     remaining: number;
 }
+export interface RunGate {
+    readonly paused: boolean;
+    pause(): void;
+    resume(): void;
+    /** Reject all current and future waiters (run stopped/timed out). */
+    abort(): void;
+    wait(): Promise<void>;
+}
+export declare function createRunGate(): RunGate;
+/** Script-global human question: select when options given, confirm otherwise. undefined = dismissed. */
+export type EngineAskFn = (question: string, options?: string[]) => Promise<string | boolean | undefined>;
 export interface ScriptMeta {
     name?: string;
     description?: string;
@@ -71,6 +82,19 @@ export interface RunScriptOptions {
     cwd: string;
     budgetTotal?: number;
     onLog?: (line: string) => void;
+    /** Pause gate; agent() awaits it before every spawn. */
+    gate?: RunGate;
+    /**
+     * Host-side human gate for the `checkpoint(label?)` global. When omitted,
+     * checkpoint is a no-op that logs a skip note (pi-free hosts, tests).
+     */
+    checkpoint?: (label?: string) => Promise<void>;
+    /**
+     * Host-side human question for the `ask(question, options?)` global. When
+     * omitted, ask throws — a script that needs an answer should fail loudly
+     * rather than invent one.
+     */
+    ask?: EngineAskFn;
 }
 export interface RunScriptResult {
     value: unknown;
@@ -81,7 +105,7 @@ export interface RunScriptResult {
 }
 export declare function runScript(opts: RunScriptOptions): Promise<RunScriptResult>;
 /** The compiled async body; invoking it runs the script with injected globals. */
-export type CompiledFn = (args: unknown, agent: unknown, parallel: unknown, pipeline: unknown, phase: unknown, log: unknown, budget: unknown, cwd: string) => Promise<unknown>;
+export type CompiledFn = (args: unknown, agent: unknown, parallel: unknown, pipeline: unknown, phase: unknown, log: unknown, budget: unknown, cwd: string, checkpoint: unknown, ask: unknown) => Promise<unknown>;
 export interface CompiledScript {
     /** The script's `meta` export, read via a stub dry-run (no real spawn). */
     meta: ScriptMeta | undefined;

package/dist/engine.js

@@ -2,7 +2,7 @@
  * The workflow script engine — pi-free and testable.
  *
  * A workflow script is a JavaScript statement body with injected globals
- * (args, agent, parallel, pipeline, phase, log, budget, cwd) and a leading
+ * (args, agent, parallel, pipeline, phase, log, budget, cwd, checkpoint, ask) and a leading
  * `export const meta = { name, description }` declaration. It returns a value
  * by evaluating a trailing expression or a top-level `return` (the body is
  * wrapped in an async function so a bare `return` compiles).
@@ -17,6 +17,42 @@
  * meta.name/description.
  */
 import vm from 'node:vm';
+export function createRunGate() {
+    let paused = false;
+    let aborted = false;
+    let waiters = [];
+    return {
+        get paused() {
+            return paused;
+        },
+        pause() {
+            paused = true;
+        },
+        resume() {
+            paused = false;
+            const w = waiters;
+            waiters = [];
+            for (const { resolve } of w)
+                resolve();
+        },
+        abort() {
+            aborted = true;
+            const w = waiters;
+            waiters = [];
+            for (const { reject } of w)
+                reject(new Error('run aborted while paused'));
+        },
+        wait() {
+            if (aborted)
+                return Promise.reject(new Error('run aborted while paused'));
+            if (!paused)
+                return Promise.resolve();
+            return new Promise((resolve, reject) => {
+                waiters.push({ resolve, reject });
+            });
+        },
+    };
+}
 // ── Internals ──────────────────────────────────────────────────────────────
 const STRIP_META = /export\s+const\s+meta\s*=/;
 const DEFAULT_TOOLS = ['read', 'grep', 'find', 'ls'];
@@ -84,6 +120,8 @@ export async function runScript(opts) {
         if (typeof agentOpts.agentType === 'string') {
             log(`(agentType '${agentOpts.agentType}' accepted but ignored — no agent-type registry)`);
         }
+        // Pause gate: hold here (between steps) until resumed. Rejects on abort.
+        await opts.gate?.wait();
         const spawnOpts = {
             prompt,
             ...(typeof agentOpts.label === 'string' ? { agent: agentOpts.label } : {}),
@@ -108,6 +146,24 @@ export async function runScript(opts) {
             return { value: res.data ?? res.text ?? null, patchPath: res.patchPath, runId: res.runId };
         return res.data ?? res.text ?? null;
     };
+    // checkpoint(label?): script-internal human gate. The host decides what
+    // "continue?" means (a confirm dialog in pi); default is a logged no-op.
+    const checkpoint = async (label) => {
+        if (!opts.checkpoint) {
+            log(`(checkpoint${label ? ` '${label}'` : ''} skipped — no host gate)`);
+            return;
+        }
+        log(`⏸ checkpoint${label ? `: ${label}` : ''}`);
+        await opts.checkpoint(label);
+    };
+    // ask(question, options?) — human answer inside a run. select with options,
+    // confirm without. Default throws: never invent an answer.
+    const ask = async (question, options) => {
+        if (!opts.ask)
+            throw new Error('ask() unavailable in this host');
+        log(`? ${question}`);
+        return opts.ask(question, options);
+    };
     const parallel = (thunks) => Promise.all(thunks.map((t) => t()));
     // pipeline(items, ...stages): each stage maps over the previous stage's
     // outputs in parallel, producing the next array. A fold over Promise.all.
@@ -121,7 +177,7 @@ export async function runScript(opts) {
     // Compile + run. compileScript is extracted so callers (tests, future
     // tooling) can compile + read `meta` without a real spawn.
     const compiled = compileScript(script);
-    const value = await compiled.fn(args, agent, parallel, pipeline, phase, log, budget, cwd);
+    const value = await compiled.fn(args, agent, parallel, pipeline, phase, log, budget, cwd, checkpoint, ask);
     return { value, meta: compiled.meta, logs, usage, durationMs: Date.now() - startedAt };
 }
 /**
@@ -138,11 +194,11 @@ export async function runScript(opts) {
 export function compileScript(script) {
     const metaHolder = { value: undefined };
     const stripped = script.replace(STRIP_META, 'const meta = metaHolder.value =');
-    const wrapped = `(async function(args, agent, parallel, pipeline, phase, log, budget, cwd, metaHolder){\n${stripped}\n})`;
+    const wrapped = `(async function(args, agent, parallel, pipeline, phase, log, budget, cwd, checkpoint, ask, metaHolder){\n${stripped}\n})`;
     const raw = new vm.Script(wrapped, { filename: 'workflow.js' }).runInThisContext();
-    // Bind metaHolder so callers invoke an 8-arg fn; the holder rides the call
+    // Bind metaHolder so callers invoke a 10-arg fn; the holder rides the call
     // (runInThisContext cannot see a closure variable, so it must be a parameter).
-    const fn = (args, agent, parallel, pipeline, phase, log, budget, cwd) => raw(args, agent, parallel, pipeline, phase, log, budget, cwd, metaHolder);
+    const fn = (args, agent, parallel, pipeline, phase, log, budget, cwd, checkpoint, ask) => raw(args, agent, parallel, pipeline, phase, log, budget, cwd, checkpoint, ask, metaHolder);
     // Stub dry-run to read `meta`. Well-formed scripts declare `meta` first, so
     // it is assigned synchronously before the first `await`; we await the whole
     // stubbed body anyway so a script that computes meta from `args` works too.
@@ -156,7 +212,9 @@ export function compileScript(script) {
         return values;
     };
     const stubBudget = { total: Infinity, spent: 0, remaining: Infinity };
-    void fn(undefined, stubAgent, stubParallel, stubPipeline, () => { }, () => { }, stubBudget, '/tmp').catch(() => { });
+    const stubCheckpoint = async () => { };
+    const stubAsk = async () => undefined;
+    void fn(undefined, stubAgent, stubParallel, stubPipeline, () => { }, () => { }, stubBudget, '/tmp', stubCheckpoint, stubAsk).catch(() => { });
     // `meta` is a getter so a caller that re-runs `fn` with real globals sees
     // the post-run meta (the stub dry-run may have thrown on args-derived meta;
     // the real run sets it). For static meta the stub already populated it.

package/dist/examples.test.js

@@ -18,8 +18,15 @@ const examples = fs
     .filter((f) => f.endsWith('.js'))
     .map((f) => path.join(examplesDir, f));
 describe('examples smoke: compile + meta', () => {
-    it('discovers exactly the three example files', () => {
-        expect(examples.map((e) => path.basename(e)).sort()).toEqual(['bake-off.js', 'gates.js', 'lanes.js']);
+    it('discovers exactly the six example files', () => {
+        expect(examples.map((e) => path.basename(e)).sort()).toEqual([
+            'autoimplement.js',
+            'autoplan.js',
+            'bake-off.js',
+            'gates.js',
+            'lanes.js',
+            'sanity-check.js',
+        ]);
     });
     for (const file of examples) {
         const name = path.basename(file);

package/dist/index.js

@@ -29,13 +29,72 @@ import * as path from 'node:path';
 import { CONFIG_DIR_NAME, getAgentDir } from '@earendil-works/pi-coding-agent';
 import { createSubagentRuntime, readRunArtifacts, sweepRunArtifactsOnce, } from '@nicknisi/pi-shared';
 import { Type } from 'typebox';
-import { runScript, } from './engine.js';
+import { createRunGate, runScript, } from './engine.js';
 const ARTIFACTS_ROOT = path.join(getAgentDir(), 'subagent-runs');
 const NAMESPACE = 'workflows';
 const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
 const MAX_TIMEOUT_MS = 30 * 60 * 1000;
 const MAX_RESULT_CHARS = 16 * 1024;
 const MAX_LOG_CHARS = 2000;
+function pauseAll(activeRuns) {
+    for (const run of activeRuns) {
+        run.gate.pause();
+        run.refresh();
+    }
+    return activeRuns.size;
+}
+function resumeAll(activeRuns) {
+    for (const run of activeRuns) {
+        run.gate.resume();
+        run.refresh();
+    }
+    return activeRuns.size;
+}
+/**
+ * Per-run scaffolding: gate (pause/resume/abort), footer status that tracks
+ * phase() markers, and the checkpoint/ask host functions backed by pi's UI.
+ * checkpoint is a confirm dialog — aborting it rejects so a dismissed gate
+ * stops the run instead of silently continuing.
+ */
+function makeRunControls(label, ui, activeRuns) {
+    const gate = createRunGate();
+    let lastPhase = '';
+    const run = {
+        label,
+        gate,
+        refresh: () => {
+            const state = gate.paused ? 'paused' : 'running';
+            ui.setStatus('workflows', `wf ${label} [${state}]${lastPhase ? ` ${lastPhase}` : ''}`);
+        },
+    };
+    const checkpoint = async (checkpointLabel) => {
+        const ok = await ui.confirm('Workflow checkpoint', checkpointLabel ? `${checkpointLabel} — continue?` : 'Continue?');
+        if (!ok)
+            throw new Error(`checkpoint${checkpointLabel ? ` '${checkpointLabel}'` : ''} rejected`);
+    };
+    const ask = async (question, options) => {
+        if (options && options.length > 0)
+            return ui.select(question, options);
+        return ui.confirm('Workflow', question);
+    };
+    activeRuns.add(run);
+    run.refresh();
+    return {
+        gate,
+        checkpoint,
+        ask,
+        onLog: (line) => {
+            if (line.startsWith('── ')) {
+                lastPhase = line.slice(3);
+                run.refresh();
+            }
+        },
+        dispose: () => {
+            activeRuns.delete(run);
+            ui.setStatus('workflows', undefined);
+        },
+    };
+}
 function spawnCancellable(cancellables, runtime, opts, externalSignal) {
     const controller = new AbortController();
     const onExternalAbort = () => controller.abort();
@@ -195,6 +254,7 @@ function formatRunResult(result, label) {
 // ── Extension ─────────────────────────────────────────────────────────────
 export default function workflows(pi) {
     const cancellables = new Map();
+    const activeRuns = new Set();
     const runtime = createSubagentRuntime({ namespace: NAMESPACE, artifactsDir: ARTIFACTS_ROOT });
     sweepRunArtifactsOnce(ARTIFACTS_ROOT);
     pi.registerTool({
@@ -204,14 +264,21 @@ export default function workflows(pi) {
             'Run a JavaScript workflow script that orchestrates subagents over the first-party runtime,',
             "or manage runs. Actions: 'run' (compile a script in a vm and execute it with injected",
             'globals), "list" (saved workflow files), "status" (a run record by runId), "stop" (cancel a',
-            "run by runId). For 'run', pass EITHER `script` (inline JS) OR `name` (a saved workflow file",
+            'run by runId), "pause"/"resume" (hold active runs before their next agent step, then',
+            "continue them). For 'run', pass EITHER `script` (inline JS) OR `name` (a saved workflow file",
             'stem from ~/.pi/agent/workflows/*.js or .pi/workflows/*.js). Optional `args` (any JSON value)',
             "is passed in as the script's `args` global.",
             '',
             'Script contract — injected globals: agent(prompt, opts), parallel(thunks),',
             'pipeline(items, ...stages), phase(name), log(...args), args, budget ({total, spent,',
-            "remaining}), cwd. The script's FIRST statement SHOULD be `export const meta = { name,",
-            'description }` (rewritten so the vm compiles; meta.name/description surface in the result).',
+            "remaining}), cwd, checkpoint(label?), ask(question, options?). The script's FIRST statement",
+            'SHOULD be `export const meta = { name, description }` (rewritten so the vm compiles;',
+            'meta.name/description surface in the result).',
+            '',
+            'checkpoint(label?) gates the run on a human confirm (dismiss/reject throws and stops the',
+            'run); ask(question, options?) asks the human mid-run — select when options are given,',
+            'yes/no confirm otherwise, undefined when dismissed. Use them before destructive or',
+            'expensive steps.',
             'The script returns a value via a trailing expression or a top-level `return` (the body is',
             'wrapped in an async function).',
             '',
@@ -237,9 +304,14 @@ export default function workflows(pi) {
             'Keep the returned value small — summaries, counts, key findings — never raw file contents.',
         ],
         parameters: Type.Object({
-            action: Type.Union([Type.Literal('run'), Type.Literal('list'), Type.Literal('status'), Type.Literal('stop')], {
-                description: 'Action: run | list | status | stop',
-            }),
+            action: Type.Union([
+                Type.Literal('run'),
+                Type.Literal('list'),
+                Type.Literal('status'),
+                Type.Literal('stop'),
+                Type.Literal('pause'),
+                Type.Literal('resume'),
+            ], { description: 'Action: run | list | status | stop | pause | resume' }),
             script: Type.Optional(Type.String({ description: 'Inline JS workflow script (action: run).' })),
             name: Type.Optional(Type.String({ description: 'Saved workflow file stem (action: run).' })),
             args: Type.Optional(Type.Any({ description: "Any JSON value passed as the script's `args` global (action: run)." })),
@@ -287,6 +359,13 @@ export default function workflows(pi) {
                     details: { runId: record.runId, status: record.status },
                 };
             }
+            if (action === 'pause' || action === 'resume') {
+                const n = action === 'pause' ? pauseAll(activeRuns) : resumeAll(activeRuns);
+                const text = n === 0
+                    ? 'No active workflow run in this session.'
+                    : `${action === 'pause' ? 'Paused' : 'Resumed'} ${n} active run${n === 1 ? '' : 's'}.`;
+                return { content: [{ type: 'text', text }], details: { affected: n } };
+            }
             if (action === 'stop') {
                 const runId = params.runId;
                 if (!runId) {
@@ -369,6 +448,10 @@ export default function workflows(pi) {
                 controller.abort();
             }, timeoutMs);
             const spawnFn = makeSpawnFn(cancellables, runtime, ctx.cwd, ctx.sessionManager.getSessionFile(), controller.signal);
+            const controls = makeRunControls(label, ctx.ui, activeRuns);
+            // A parked run (gate.wait / checkpoint) must not leak when the tool is
+            // aborted or times out — aborting the gate rejects its waiters.
+            controller.signal.addEventListener('abort', () => controls.gate.abort(), { once: true });
             const timeoutPromise = new Promise((_, reject) => {
                 controller.signal.addEventListener('abort', () => reject(new Error(timedOut
                     ? `Timed out after ${timeoutMs}ms (in-flight subagents were aborted)`
@@ -381,7 +464,10 @@ export default function workflows(pi) {
                         args: params.args,
                         spawn: spawnFn,
                         cwd: ctx.cwd,
-                        onLog: () => { },
+                        onLog: controls.onLog,
+                        gate: controls.gate,
+                        checkpoint: controls.checkpoint,
+                        ask: controls.ask,
                     }),
                     timeoutPromise,
                 ]);
@@ -407,28 +493,29 @@ export default function workflows(pi) {
             finally {
                 clearTimeout(timer);
                 signal?.removeEventListener('abort', onToolAbort);
+                controls.dispose();
             }
         },
     });
     // ── /wf — thin human-facing wrapper ───────────────────────────────────
     pi.registerCommand('wf', {
-        description: 'Workflows: /wf list | /wf run <name> [argsJson] | /wf status <runId> | /wf stop <runId>. Saved workflows live in ~/.pi/agent/workflows/*.js (global) and .pi/workflows/*.js (project, trusted only).',
+        description: 'Workflows: /wf list | /wf run <name> [argsJson] | /wf status <runId> | /wf stop <runId> | /wf pause | /wf resume. Saved workflows live in ~/.pi/agent/workflows/*.js (global) and .pi/workflows/*.js (project, trusted only).',
         getArgumentCompletions: (argumentPrefix) => {
             if (argumentPrefix.includes(' '))
                 return null;
             const prefix = argumentPrefix.trim();
-            const subs = ['list', 'run', 'status', 'stop'].filter((s) => s.startsWith(prefix));
+            const subs = ['list', 'run', 'status', 'stop', 'pause', 'resume'].filter((s) => s.startsWith(prefix));
             if (subs.length === 0)
                 return null;
             return subs.map((s) => ({ value: s + ' ', label: s }));
         },
         handler: async (args, ctx) => {
-            await cmdWf(args, ctx, runtime, cancellables);
+            await cmdWf(args, ctx, runtime, cancellables, activeRuns);
         },
     });
 }
 // ── /wf handler (shared, typed against the runtime) ───────────────────────
-async function cmdWf(args, ctx, runtime, cancellables) {
+async function cmdWf(args, ctx, runtime, cancellables, activeRuns) {
     const parts = args.trim().split(/\s+/).filter(Boolean);
     const sub = parts[0];
     if (!sub || sub === 'list') {
@@ -471,20 +558,42 @@ async function cmdWf(args, ctx, runtime, cancellables) {
                 parsedArgs = argsJson;
             }
         }
-        ctx.ui.setStatus('workflows', `running ${name}…`);
+        const controls = makeRunControls(name, ctx.ui, activeRuns);
+        if (ctx.signal) {
+            if (ctx.signal.aborted)
+                controls.gate.abort();
+            else
+                ctx.signal.addEventListener('abort', () => controls.gate.abort(), { once: true });
+        }
         try {
             const spawnFn = makeSpawnFn(cancellables, runtime, ctx.cwd, ctx.sessionManager.getSessionFile(), ctx.signal ?? undefined);
-            const result = await runScript({ script: src, args: parsedArgs, spawn: spawnFn, cwd: ctx.cwd });
+            const result = await runScript({
+                script: src,
+                args: parsedArgs,
+                spawn: spawnFn,
+                cwd: ctx.cwd,
+                onLog: controls.onLog,
+                gate: controls.gate,
+                checkpoint: controls.checkpoint,
+                ask: controls.ask,
+            });
             ctx.ui.notify(formatRunResult(result, name), 'info');
         }
         catch (err) {
             ctx.ui.notify(`${name} failed: ${err instanceof Error ? err.message : String(err)}`, 'error');
         }
         finally {
-            ctx.ui.setStatus('workflows', undefined);
+            controls.dispose();
         }
         return;
     }
+    if (sub === 'pause' || sub === 'resume') {
+        const n = sub === 'pause' ? pauseAll(activeRuns) : resumeAll(activeRuns);
+        ctx.ui.notify(n === 0
+            ? 'No active workflow run in this session.'
+            : `${sub === 'pause' ? 'Paused' : 'Resumed'} ${n} run${n === 1 ? '' : 's'}.`, n === 0 ? 'warning' : 'info');
+        return;
+    }
     if (sub === 'status') {
         const runId = parts[1];
         if (!runId) {
@@ -517,7 +626,7 @@ async function cmdWf(args, ctx, runtime, cancellables) {
         ctx.ui.notify(`Cancelled run ${runId.slice(0, 8)}`, 'info');
         return;
     }
-    ctx.ui.notify('Usage: /wf list | /wf run <name> [argsJson] | /wf status <runId> | /wf stop <runId>', 'warning');
+    ctx.ui.notify('Usage: /wf list | /wf run <name> [argsJson] | /wf status <runId> | /wf stop <runId> | /wf pause | /wf resume', 'warning');
 }
 // ── Run lookup / cancellation resolution ──────────────────────────────────
 /** Find a run by full id or unique 8-char prefix across live + persisted records. */

package/dist/workflow.test.js

@@ -11,7 +11,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { runScript } from './engine.js';
+import { createRunGate, runScript } from './engine.js';
 const tmpdirs = [];
 function tmpRoot() {
     const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'pi-workflows-test-'));
@@ -221,6 +221,94 @@ describe('engine: agent opts + failures', () => {
         expect(r.value).toBe('PASS');
     });
 });
+describe('engine: gate (pause/resume)', () => {
+    const tick = () => new Promise((r) => setTimeout(r, 10));
+    it('a paused gate holds agent() before the spawn until resumed', async () => {
+        const gate = createRunGate();
+        let spawns = 0;
+        const spawn = async () => {
+            spawns++;
+            return { ok: true, text: 'ok', usage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 } };
+        };
+        gate.pause();
+        const run = runScript({ script: 'await agent("x"); return "done";', spawn, cwd: '/tmp', gate });
+        await tick();
+        expect(spawns).toBe(0); // held at the gate, spawn never fired
+        gate.resume();
+        const r = await run;
+        expect(spawns).toBe(1);
+        expect(r.value).toBe('done');
+    });
+    it('abort() rejects a parked run instead of hanging it', async () => {
+        const gate = createRunGate();
+        gate.pause();
+        const run = runScript({ script: 'await agent("x"); return "done";', spawn: fakeSpawn(), cwd: '/tmp', gate });
+        gate.abort();
+        await expect(run).rejects.toThrow('aborted');
+    });
+    it('abort() rejects future waits too (no re-arm after stop)', async () => {
+        const gate = createRunGate();
+        gate.abort();
+        await expect(gate.wait()).rejects.toThrow('aborted');
+    });
+});
+describe('engine: checkpoint + ask', () => {
+    it('checkpoint without a host is a logged no-op', async () => {
+        const r = await runScript({
+            script: 'await checkpoint("review"); return "ok";',
+            spawn: fakeSpawn(),
+            cwd: '/tmp',
+        });
+        expect(r.value).toBe('ok');
+        expect(r.logs.some((l) => l.includes("checkpoint 'review' skipped"))).toBe(true);
+    });
+    it('checkpoint with a host is invoked with its label and gates the run', async () => {
+        const calls = [];
+        const r = await runScript({
+            script: 'await checkpoint(); await checkpoint("ship?"); return "ok";',
+            spawn: fakeSpawn(),
+            cwd: '/tmp',
+            checkpoint: async (label) => {
+                calls.push(label);
+            },
+        });
+        expect(r.value).toBe('ok');
+        expect(calls).toEqual([undefined, 'ship?']);
+    });
+    it('a throwing checkpoint host stops the run (rejected gate = stop)', async () => {
+        await expect(runScript({
+            script: 'await checkpoint("review"); return "unreachable";',
+            spawn: fakeSpawn(),
+            cwd: '/tmp',
+            checkpoint: async () => {
+                throw new Error('rejected');
+            },
+        })).rejects.toThrow('rejected');
+    });
+    it('ask without a host throws (never invent an answer)', async () => {
+        const r = await runScript({
+            script: 'try { await ask("continue?"); } catch (e) { return e.message; }',
+            spawn: fakeSpawn(),
+            cwd: '/tmp',
+        });
+        expect(r.value).toBe('ask() unavailable in this host');
+    });
+    it('ask passes question + options to the host and returns the answer', async () => {
+        const seen = [];
+        const r = await runScript({
+            script: 'const a = await ask("pick", ["a", "b"]); const b = await ask("ok?"); return { a, b };',
+            spawn: fakeSpawn(),
+            cwd: '/tmp',
+            ask: async (q, opts) => {
+                seen.push({ q, ...(opts ? { opts } : {}) });
+                return opts ? 'b' : true;
+            },
+        });
+        expect(r.value).toEqual({ a: 'b', b: true });
+        expect(seen).toEqual([{ q: 'pick', opts: ['a', 'b'] }, { q: 'ok?' }]);
+        expect(r.logs.some((l) => l === '? pick')).toBe(true);
+    });
+});
 // ── Saved-workflow discovery ───────────────────────────────────────────────
 describe('saved-workflow discovery', () => {
     let prevAgentDir;