pi-workflow-engine 0.11.0 → 0.12.0

package/USAGE.md

@@ -2,6 +2,10 @@
 
 `pi-workflow-engine` adds zero-dependency Dynamax workflows to pi: opt into live, parallel subagents for the tasks that need a custom investigation instead of one long prompt. Most users only need these surfaces:
 
+This release requires **pi 0.80.10 or newer**. pi remains host-provided rather
+than bundled by this package, and the extension rejects older runtimes at load
+time with an update message.
+
 - `/workflow <name> [args]` to run a saved workflow directly.
 - `/workflow:*` commands for related actions such as inspector reopening and Dynamax control.
 - `dynamax` as a literal one-shot opt-in token when you want the host agent to author a one-off inline workflow for investigation/review.
@@ -16,6 +20,7 @@ From inside a repo:
 /workflow refactor-scout src/
 /workflow diagnose "typecheck fails after the schema change"
 /workflow perf-review "workflow startup latency"
+/workflow research "Compare the current Node.js and Bun test-runner watch modes; prefer official docs"
 ```
 
 The built-in workflows are advisory by default. They inspect, verify, and report; they do **not** edit files. Saved or inline workflows can opt individual agents into disposable git worktrees when they need reviewable patches.
@@ -29,11 +34,63 @@ Useful flags:
 /workflow code-review --review-viewer    # alias for --result-viewer
 /workflow:results                        # reopen the latest code-review findings without rerunning
 /workflow code-review --concurrency=4    # cap concurrent subagents
+/workflow code-review --max-agents=20    # cap total live agent calls in the run
+/workflow code-review --agent-timeout-ms=600000 # abort one live agent after 10 minutes
+/workflow code-review --agent-retries=2  # retry classified transient provider failures
 /workflow code-review --budget=50000     # output-token ceiling for subagents
 /workflow code-review --resume <run-id>  # replay matching completed agent calls
+/workflow code-review --resume <run-id> --resume-edited # reuse unchanged calls after a workflow edit
 /workflow code-review --refresh          # rediscover newly added workflow files
+/workflow:runs                           # browse recent durable project runs
+/workflow:inspector <run-id>             # inspect one retained run directly
+/workflow:models                         # inspect small/medium/big model routes
+```
+
+## Workflow model profiles
+
+Workflow authors can route a stage through `profile: "small"`, `"medium"`, or
+`"big"` without hard-coding a provider. Inspect the effective routes with:
+
+```text
+/workflow:models
+/workflow:models set small openai/gpt-5-mini low
+/workflow:models set medium anthropic/claude-sonnet-4-5 medium --project
+/workflow:models clear medium --project
 ```
 
+`set` and `clear` use the user scope unless `--project` is present. User profiles
+live at `~/.pi/agent/workflow-models.json`; project profiles live at
+`<project>/.pi/workflow-models.json` and override the user file one profile at a
+time. A minimal file is:
+
+```json
+{
+  "profiles": {
+    "small": {
+      "model": "openai/gpt-5-mini",
+      "thinkingLevel": "low"
+    },
+    "big": {
+      "model": "anthropic/claude-opus-4-5"
+    }
+  }
+}
+```
+
+Models must be exact `provider/model` identities already available to pi. The
+file accepts only `model` and optional `thinkingLevel`; provider credentials and
+secrets stay in pi's provider configuration. The engine never ranks models by
+price, model-name substrings, or assumed capability.
+
+Routing is resolved per field: an agent's explicit `model` or `thinkingLevel`
+wins, then its requested profile, then host inheritance. A configured profile
+without `thinkingLevel` inherits the host effort. An entirely unconfigured tier
+uses the host model and the built-in bounded effort for that tier (`low`,
+`medium`, or `high` respectively); `/workflow:models` labels that route as a host
+fallback. Invalid JSON, unknown fields, malformed identities, and configured
+models missing from pi's registry fail with the config path and a corrective
+command instead of selecting another model.
+
 ## Built-in workflows
 
 | Name | Purpose |
@@ -42,9 +99,27 @@ Useful flags:
 | `refactor-scout` | Finds small, safe refactor opportunities. |
 | `diagnose` | Investigates a bug, failing command, or regression. |
 | `perf-review` | Reviews a slow path or performance concern. |
+| `research` | Gathers current external evidence, independently verifies claims, and returns a cited synthesis. |
 
 `code-review` auto-detects a diff when you do not pass args. If there is an open GitHub PR for the current branch, it uses the cumulative PR diff; otherwise it falls back to branch-vs-main/master or `HEAD~1`. Per-commit `gh pr diff --patch` input is rejected because it can surface superseded code. If diff capture fails, the review fails instead of returning an empty report or "no findings."
 
+### External research capabilities
+
+`research` requires at least one installed pi tool whose metadata identifies it
+as external web search, browsing, or HTTP(S) page extraction. Local grep/find
+tools do not satisfy this check. The workflow does not bundle a scraper or a
+paid API; install or enable the web capability you prefer, then restart or
+reload pi so subagent sessions can see it.
+
+The workflow bounds decomposition to four lanes and verification to twelve
+claims, while the engine's concurrency, total-agent, timeout, cancellation, and
+token-budget limits still apply. Gatherers retain direct page titles and URLs;
+search-results URLs are rejected, sources are canonicalized and deduplicated,
+and separate verifier agents classify claims as supported, conflicting,
+uncertain, inferred, or rejected before synthesis. External research calls use
+`resume: "off"` because live web evidence, time, and service state are outside
+the journal's deterministic replay surface.
+
 ## Use Dynamax for custom workflows
 
 Use `dynamax` when the built-in workflows are not specific enough and you want the main pi agent to author a temporary workflow for the current question. It is the fastest path from "this needs multiple angles" to a live fan-out, verifier pass, and synthesized result.
@@ -73,6 +148,30 @@ The workflow inspector and code-review results viewer are also registered as fir
 
 When only the literal `dynamax` token is used, the opt-in is one-shot: the next agent run receives the workflow permission reminder, stays visibly active for that run, then clears after the run ends. When `/workflow:dynamax on` is used, the opt-in is sticky for the current pi session until `/workflow:dynamax off`. Sticky mode, one-shot pending mode, and active Dynamax workflow runs show compact TUI status with `/workflow:dynamax on|off` and the inspector shortcut; off mode clears that status line.
 
+### Prompt editor cue
+
+In TUI mode, every standalone `dynamax` token receives one bounded
+moving-shine sweep, then remains as a static multi-colour cue. Longer identifiers
+such as `notdynamax`, `dynamaxing`, and `dynamax_mode` are deliberately left
+alone. The cue affects rendering only; one-shot and sticky activation semantics
+are unchanged.
+
+The default effect is `shine`. Set `PI_DYNAMAX_EFFECT=static` for a motionless
+cue or `PI_DYNAMAX_EFFECT=off` to disable it. A non-empty `NO_COLOR` also
+disables the default cue; an explicit `PI_DYNAMAX_EFFECT` value takes precedence.
+
+The implementation follows pi 0.80.10's [official `CustomEditor`
+pattern](https://pi.dev/docs/latest/extensions#custom-editor): it decorates only
+the editor's rendered lines, retaining the wrapped editor's input, cursor,
+deletion, paste, multiline, undo, completion, IME, and app-keybinding behavior.
+
+If an editor extension is already registered, pi-workflow-engine composes its
+factory and adds only the Dynamax render hook. If that editor cannot be
+composed, an explicit warning is shown and pi's stock-compatible `CustomEditor`
+is used so highlighting is never silently disabled. Pi editor registration is
+still last-writer-wins; the previous editor is restored on shutdown only while
+the Dynamax decorator still owns the registration.
+
 When the host agent calls the `workflow` tool from a TUI session, pi opens the live workflow inspector for that run. The compact workflow widget still shows the latest moving status above the editor, but the inspector is the richer view for phases, agents, findings, and logs.
 
 Configure either shortcut by creating `~/.pi/agent/extensions/pi-workflow-engine.json`:
@@ -106,7 +205,7 @@ const GapAnalysis = Type.Object({
 });
 const gaps = await api.agent(
   `Identify only material gaps that require another agent:\n${JSON.stringify(firstPass)}`,
-  { schema: GapAnalysis, thinkingLevel: "low" },
+  { schema: GapAnalysis, profile: "small" },
 );
 
 const followUpItems = gaps?.items.slice(0, MAX_FOLLOW_UPS) ?? [];
@@ -114,7 +213,7 @@ const followUps = followUpItems.length
   ? (await api.parallel(
       followUpItems.map((item) => () =>
         api.agent(`Resolve this gap and cite evidence: ${JSON.stringify(item)}`, {
-          thinkingLevel: "low",
+          profile: "small",
         }),
       ),
     )).filter((result) => result !== null)
@@ -122,7 +221,7 @@ const followUps = followUpItems.length
 
 return api.agent(
   `Synthesize the first pass and any follow-ups:\n${JSON.stringify({ firstPass, followUps })}`,
-  { thinkingLevel: "medium" },
+  { profile: "medium" },
 );
 ```
 
@@ -138,12 +237,64 @@ Workflow results are rendered in pi with:
 - recommendations;
 - next steps;
 - run stats when available;
-- workflow-level token and cost totals gathered from subagent sessions when provider usage is available.
+- workflow-level fresh-input, cache-read, cache-write, output, and cost totals gathered from subagent sessions when provider usage is available.
 
 These workflow usage totals are separate from `--perf`, which is internal timing only. They are also separate from pi's built-in footer and `/session` totals, which may still show host-session usage only unless pi core adds a first-class extension usage API. If a model has no pricing configured, token totals can be non-zero while displayed cost remains `$0.000`.
 
+The result, inspector overview, compact widget, and status line all use the same usage summary. Providers with a complete breakdown show `fresh`, `cache read`, `cache write`, and `output` separately. Zero cache components are omitted. If a provider reports only some components, the summary labels mixed-run component totals with `≥` and preserves the provider's aggregate `total`; if it reports no components, the summary falls back to aggregate `tokens`. Costs are summed from provider session totals and are never inferred from local pricing.
+
 During a run, pi shows live phases and subagent status. Use `--inspect` if you want a larger live view while the workflow is active, then `/workflow:inspector` if you want to bring the last completed inspector back up afterward.
 
+### Durable run records
+
+Every workflow run writes a versioned project-local record to `.pi/.workflow-runs/<run-id>.run.json`; its agent replay journal remains `.pi/.workflow-runs/<run-id>.jsonl`. The same run ID appears in execution metadata, progress snapshots, result details, and both filenames. Records distinguish `queued`, `running`, `completed`, `failed`, `stopped`, and `paused` lifecycle states and retain resolved scalar options, timestamps, compact progress, summary usage, and the final result or error.
+
+Record replacement is atomic, corrupt or unsupported-version files are ignored independently, and the newest 50 run records are retained. Journal retention remains 50 files. Both record and journal files are excluded from repository resume fingerprints, so checkpoint writes do not invalidate replay.
+
+Persistence is intentionally bounded and private by default. Raw workflow args, prompts, subagent transcripts, progress logs, lane details, agent errors, environment data, credentials, and tool-output-shaped fields are not stored. Final results are limited to bounded plain JSON; credential- and transcript-shaped fields are redacted, and unsupported or cyclic results are marked unavailable instead of executing accessors or breaking the workflow. Loading history only parses these data files and never imports or executes workflow code.
+
+### Background workflows
+
+The host-facing `workflow` tool accepts `background: true`. It returns as soon as the run ID and origin metadata are durably recorded, while the normal workflow engine continues in-process with the same concurrency, budget, worktree, progress, usage, and resume rules. Synchronous execution remains the default, and the `/workflow` slash command remains synchronous.
+
+Background runs are detached from the initiating tool-call signal, so the host agent can finish that turn and continue the conversation. When the run completes or fails, the extension waits for the originating session to become idle and inserts one concise `workflow-result` message containing the run ID, terminal state, and summary. Delivery state is stored with the run record; on reload, the extension checks both that state and the session message history before retrying, which suppresses duplicates even if persistence failed immediately after message insertion.
+
+Provider usage-window continuation is a separate, explicit background option:
+
+```json
+{
+  "name": "code-review",
+  "background": true,
+  "autoResumeOnUsageLimit": true,
+  "usageLimitMaxAttempts": 3,
+  "usageLimitMaxDelayMs": 21600000
+}
+```
+
+It is off by default and schedules only registered file workflows whose invocation had no arguments; inline scripts and argument-bearing runs still pause safely but require an explicit manual decision because their executable input is not persisted. A recognized provider usage or quota failure aborts the current fan-out before queued agents can open new sessions, preserves the replay journal, and records a sanitized provider message, provider identity, reset hint, total attempt number, and next eligible time. Transport failures and ordinary provider errors keep the existing per-agent `agentRetries` behavior and do not create a provider-limit pause.
+
+Reset parsing accepts provider duration hints such as `retry-after: 60` and `x-ratelimit-reset-tokens: 6m0s`, plus future RFC3339 timestamps. Missing, past, or malformed hints use a 60-second fallback; delays are clamped to at least 5 seconds and at most `usageLimitMaxDelayMs`. The default maximum is three total run attempts, including the initial run. When the eligible time arrives, the extension starts a new background run with `resumeFromRunId`; after a process restart, it re-arms only the remaining delay. `/workflow:runs resume` and `/workflow:runs stop` cancel any pending timer, and the attempt cap prevents an infinite resume loop.
+
+The equivalent environment defaults are `PI_WORKFLOW_USAGE_LIMIT_AUTO_RESUME=1`, `PI_WORKFLOW_USAGE_LIMIT_MAX_ATTEMPTS`, and `PI_WORKFLOW_USAGE_LIMIT_MAX_DELAY_MS`. Per-tool-call values take precedence.
+
+A graceful pi session shutdown aborts active background work and records it as `paused` instead of successful. Reopening the same session after an ungraceful process exit also reconciles a retained `queued` or `running` background record to `paused`. Resuming the originating pi session delivers that interruption once. If the originating session no longer exists, the record remains in `.pi/.workflow-runs/`, delivery is marked unavailable, and a fallback is written to stderr. Background mode is supported in long-lived TUI and RPC sessions; `print` and `json` modes reject it because those processes exit after the prompt. This feature is in-process rather than a daemon: a hard process kill cannot keep model work running, but the last atomic run checkpoint remains available.
+
+### Recent runs and lifecycle actions
+
+`/workflow:runs` opens pi's native selection UI with a bounded list of recent project runs. Each option includes an accessible state label, workflow name, age, duration, usage summary, and full run ID. Choose a run, then choose one of the lifecycle actions currently valid for it: inspect, stop, resume, or restart. The background activity line is present only while this session owns active background work.
+
+The same operations are available without the selection UI:
+
+```text
+/workflow:runs inspect <run-id>
+/workflow:runs stop <run-id>
+/workflow:runs resume <run-id>
+/workflow:runs restart <run-id>
+/workflow:inspector <run-id>
+```
+
+Inspect is always safe. Stop is available for a background run active in the current session and for a retained paused run with a pending resume timer. Resume is limited to paused registered workflows whose source fingerprint is unchanged and whose invocation had no redacted arguments; it starts a new background run ID with `resumeFromRunId` journal replay. Restart is limited to completed, failed, or stopped registered workflows that had no arguments and also creates a new background run ID. Inline workflows and argument-bearing invocations are intentionally not relaunched because their executable input was not persisted. In `print` and `json` modes, list and inspect return formatted text without opening TUI components, while resume/restart report that background execution requires TUI or RPC mode.
+
 Code-review findings are rendered as a formatted result message by default. pi no longer asks whether to open the findings viewer. Use `--result-viewer` or `--review-viewer` when you want to inspect findings interactively, press `enter` to expand/collapse the nicely formatted finding text, and use `1`-`9` to jump directly to a visible finding. The viewer is centred, scales to the terminal, and shows the visible finding/detail ranges while scrolling. `/workflow:results` or `ctrl+shift+r` reopens the most recent validated code-review report in the current pi session without rerunning the workflow; selections reset when it reopens.
 
 The Fix action revalidates the exact reviewed PR/ref/index/working-tree snapshot, then runs each selected finding through its own worktree-isolated agent and returns the finding ID, validation summary, patch, and changed status. Failed attempts do not discard successful previews, no patch is applied to your active tree automatically, and a moved or unverifiable review target is rejected rather than patched against the wrong code. The original review and all Fix previews retained in that pi session share one output-token budget. Reopening the viewer does not reset it, finalized preview usage is always deducted, and only one preview can run at a time.
@@ -156,9 +307,16 @@ Every workflow result includes a run id. Resume with:
 
 ```text
 /workflow code-review --resume <run-id> HEAD~3
+/workflow code-review --resume <run-id> --resume-edited HEAD~3
 ```
 
-The `workflow` tool exposes the same feature as `resumeFromRunId`. Replay is explicit for agents that share the workflow directory and automatic for isolated patch-producing agents:
+The `workflow` tool exposes the same features as `resumeFromRunId` and the opt-in `resumeEditedWorkflow: true`. By default, any workflow source change invalidates every prior call. Edited-workflow resume waives only that source-fingerprint mismatch: repository state, runtime, model, system prompt, thinking level, prompt, schema, ordered skills, tools, isolation, and all other replay checks must still match.
+
+With edited-workflow resume enabled, unchanged calls are reused while changed or newly added calls run live. Matching uses a stable behavioral hash, not call or completion order. Repeated identical calls are deliberately ambiguous and run live unless each logical call has a stable, distinct `cacheKey`. The new run record retains the opt-in policy and reports cached and live agent totals. The engine only inspects the prior run's JSON journal; it never loads or executes the prior workflow source.
+
+This option can return a result produced before an orchestration edit when that call's explicit identity did not change. Use it only when the unchanged call is still semantically valid in the edited workflow, and prefer stable `cacheKey` values for repeated logical calls. Omit `--resume-edited` or `resumeEditedWorkflow` for the fail-closed default.
+
+Replay is explicit for agents that share the workflow directory and automatic for isolated patch-producing agents:
 
 | Agent call | Default during resume | Override |
 | --- | --- | --- |
@@ -205,14 +363,14 @@ export default async function run({ agent, parallel, phase, args }: WorkflowApi)
         schema: Finding,
         tools: SEARCH_TOOLS,
         toolHints: SEARCH_TOOL_HINTS,
-        thinkingLevel: "low",
+        profile: "small",
         resume: "read-only",
       }),
       () => agent(`Find edge cases: ${args}`, {
         schema: Finding,
         tools: SEARCH_TOOLS,
         toolHints: SEARCH_TOOL_HINTS,
-        thinkingLevel: "low",
+        profile: "small",
         resume: "read-only",
       }),
     ]),
@@ -220,7 +378,7 @@ export default async function run({ agent, parallel, phase, args }: WorkflowApi)
 
   phase("Synthesize");
   return agent(`Summarize: ${JSON.stringify(findings)}`, {
-    thinkingLevel: "medium",
+    profile: "medium",
     tools: [],
     resume: "read-only",
   });
@@ -239,15 +397,33 @@ Core primitives:
 | `progress(event)` | Emits counters, summaries, and lane items. |
 | `workflow(ref, args?)` | Runs another workflow inline as a sub-step and returns its result. |
 
-Use settled mode when the workflow must distinguish a successful `null` from a failed branch. It preserves input order and returns `{ ok: true, value }` or `{ ok: false, error: { name?, message } }` for every thunk. Genuine workflow cancellation still rejects the whole `parallel()` call and cancels siblings.
+Schema agents accept structured output only through the validated, terminating `final_answer` tool. If the first response omits it, the engine makes at most **two repair attempts** (three prompt attempts total). Repair prompts expose only `final_answer` when the active pi session supports tool restriction. Clean exhaustion throws `WorkflowStructuredOutputError` with code `WORKFLOW_STRUCTURED_OUTPUT_NONCOMPLIANCE`; provider failures and host cancellation still propagate unchanged.
+
+Use settled mode when the workflow must distinguish a successful `null` from a failed branch. It preserves input order and returns `{ ok: true, value }` or `{ ok: false, error: { name?, message, code?, details? } }` for every thunk. Default parallel mode still turns recoverable structured-output exhaustion into a `null` slot, while settled mode retains the typed code and attempt details. Genuine workflow cancellation still rejects the whole `parallel()` call and cancels siblings.
 
-Set `thinkingLevel` on fan-out agents. Otherwise many subagents can inherit an expensive global reasoning level.
+Direct schema calls can catch the typed failure instead of receiving an unexplained `null`:
 
-`tools` is a strict allowlist. If you set `tools: ["read", "bash"]`, extension tools such as `ast-grep`, `mgrep`, `fffind`, or `ffgrep` are hidden from that subagent. Add `toolHints: ["search"]` to dynamically expose installed grep/find/search-like tools while keeping the concrete base allowlist portable. The built-in advisory workflows use `tools: ["read", "bash", "grep", "find", "ls"]` plus `toolHints: ["search"]`.
+```ts
+try {
+  return await agent("Return the result.", { schema: ResultSchema });
+} catch (error) {
+  if (error instanceof Error && "code" in error && error.code === "WORKFLOW_STRUCTURED_OUTPUT_NONCOMPLIANCE") {
+    log("The agent did not produce compliant structured output.");
+    return undefined;
+  }
+  throw error;
+}
+```
+
+Set a model `profile` on each stage so users can tune workflow routing centrally.
+Use explicit `model` or `thinkingLevel` only when that one call intentionally
+overrides its profile.
+
+`tools` is a strict allowlist. If you set `tools: ["read", "bash"]`, extension tools such as `ast-grep`, `mgrep`, `fffind`, or `ffgrep` are hidden from that subagent. Add `toolHints: ["search"]` to dynamically expose installed grep/find/search-like tools while keeping the concrete base allowlist portable. Use `toolHints: ["external-search"]` for installed web search, browsing, and URL-extraction tools; `requireToolHints: true` fails before prompting unless each requested capability matched. The built-in advisory workflows use `tools: ["read", "bash", "grep", "find", "ls"]` plus `toolHints: ["search"]`.
 
 Subagents receive no skills by default. Opt in per agent with `skills: ["skill-name"]`; if `tools` is also restricted, the engine automatically keeps `read` available so the subagent can load the selected `SKILL.md`. When `skills` is omitted, clear prompt text such as `/skill:name`, `include skill name`, or `use the name skill` is also treated as an opt-in. Pass `skills: []` to suppress that inference.
 
-Set `model` only when a subagent should use a specific model. Bare ids keep the Anthropic shorthand; `provider/id` targets built-in, custom, or local providers. Omitted models inherit the host/session default; malformed or unknown explicit refs fail fast.
+Set `model` only when a subagent should use a specific model. Bare ids keep the Anthropic shorthand; `provider/id` targets built-in, custom, or local providers. Explicit models override a requested profile; calls with neither inherit the host/session default. Malformed or unknown explicit refs fail fast.
 
 ### Mutating agents in worktrees
 
@@ -257,7 +433,7 @@ Use `isolation: "worktree"` only for agents that should edit files. The agent ru
 const edit = await agent("Rename this helper and update its call sites.", {
   tools: ["read", "bash", "edit", "grep", "find", "ls"],
   isolation: "worktree",
-  thinkingLevel: "medium",
+  profile: "medium",
 });
 
 if (edit.changed) {
@@ -272,7 +448,7 @@ Cleanup is a required finalizer. The engine attempts every registered worktree r
 
 ### Compose workflows
 
-`workflow(ref, args?)` runs a registered workflow by name as a sub-step, returning its result. The child shares the parent run's concurrency cap, abort signal, and perf timing, and its phases nest under `<name> ▸ <phase>` in the live UI.
+`workflow(ref, args?)` runs a registered workflow by name as a sub-step, returning its result. The child shares the parent run's concurrency cap, total-agent limit, per-agent timeout, abort signal, and perf timing, and its phases nest under `<name> ▸ <phase>` in the live UI.
 
 ```ts
 export default async function run({ workflow }: WorkflowApi) {
@@ -312,8 +488,8 @@ export default async function run({ agent, parallel, phase, args }) {
   phase("Find");
   const Finding = Type.Object({ summary: Type.String() });
   const findings = await parallel([
-    () => agent(`Find correctness issues: ${args}`, { schema: Finding, thinkingLevel: "low" }),
-    () => agent(`Find edge cases: ${args}`, { schema: Finding, thinkingLevel: "low" }),
+    () => agent(`Find correctness issues: ${args}`, { schema: Finding, profile: "small" }),
+    () => agent(`Find edge cases: ${args}`, { schema: Finding, profile: "small" }),
   ]);
   return { summary: JSON.stringify(findings) };
 }
@@ -325,6 +501,7 @@ Inline rules:
 - default-export an async workflow function;
 - no imports or dynamic `import()`;
 - use the injected `Type` object for schemas;
+- request `profile: "small"`, `"medium"`, or `"big"` instead of hard-coding provider models when the stage is portable;
 - add `skills: ["skill-name"]` per `agent()` call when a subagent should use a pi skill; no skills are exposed by default;
 - no extra exports or code after the default export.
 
@@ -338,10 +515,27 @@ Only tune these when a workflow is too slow, too expensive, or too noisy:
 | --- | --- |
 | `--concurrency=N` / `PI_WORKFLOW_CONCURRENCY=N` | Cap concurrent subagents. Default is `min(8, max(2, CPU count))`. |
 | `--parallel-limit=N` / `PI_WORKFLOW_PARALLEL_SUBMISSION_LIMIT=N` | Limit eager `parallel()` submission. |
-| `--budget=N` / `PI_WORKFLOW_BUDGET=N` | Set an output-token ceiling for completed subagents. `agent()` throws `WorkflowBudgetExceededError` before starting another agent once the ceiling is reached; agents already running may overshoot because the engine does not reserve per-agent estimates. |
+| `--max-agents=N` / `PI_WORKFLOW_MAX_AGENTS=N` | Cap live model calls across the complete run, including sub-workflows. Default `64`; values are clamped to `1`–`10000`. Replay hits do not consume the cap. The `workflow` tool field is `maxAgents`. |
+| `--agent-timeout-ms=N` / `PI_WORKFLOW_AGENT_TIMEOUT_MS=N` | Abort one live agent after this duration. Default `1800000` (30 minutes); values are clamped to `1000`–`86400000`. The session is aborted and its isolated worktree is cleaned up. The `workflow` tool field is `agentTimeoutMs`. |
+| `--agent-retries=N` / `PI_WORKFLOW_AGENT_RETRIES=N` | Retry terminal assistant failures that pi classifies as transient provider or transport errors. Default `0`; values are clamped to `0`–`10`. Backoff starts at one second, doubles, and caps at 30 seconds. The `workflow` tool field is `agentRetries`. |
+| `--budget=N` / `PI_WORKFLOW_BUDGET=N` | Set an output-token ceiling across recorded subagent attempts, including failed provider attempts. `agent()` throws `WorkflowBudgetExceededError` before starting another model request once the ceiling is reached; agents already running may overshoot because the engine does not reserve per-agent estimates. |
 | `--perf` / `PI_WORKFLOW_PERF=1` | Include internal timing aggregates. Usage/cost totals are reported separately from perf. |
 | `PI_WORKFLOW_LANE_ITEM_LIMIT=N` | Cap retained progress lane items. |
 
+These controls bound different dimensions: concurrency limits how many agents
+are active together, `max-agents` limits how many live model calls the run may
+start in total, `agent-timeout-ms` bounds one active call (including retry
+backoff), and `budget` limits recorded output tokens. Every retry consumes
+another live-agent admission and remains inside the original timeout, budget,
+and abort scope. Usage from failed attempts is retained, so it can exhaust the
+budget before the next retry begins. Host cancellation takes precedence over
+limit and timeout failures.
+
+Workflow subagents disable pi's session-level automatic retry so this run-level
+policy is authoritative and visible in the existing agent progress row. Invalid
+models, schema-contract failures, exhausted budgets, agent limits, worktree
+failures, timeouts, and host aborts are never provider-retried.
+
 ## Common fixes
 
 - **Unknown workflow**: confirm the extension is loaded with `pi list`; use `--refresh` for new drop-ins.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-workflow-engine",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "type": "module",
   "description": "Zero-dependency Dynamax workflows for pi: live parallel subagents, typed handoffs, synthesized results.",
   "keywords": [