@automatalabs/workflows 0.45.0 → 0.45.2

package/dist/mcp-server.js

@@ -32755,7 +32755,7 @@ function callKey(scope, callIndex) {
 }
 
 // ../mcp-server/src/generated/authoring-prompt-content.ts
-var AUTHORING_PROMPT_CONTENT = '# Writing AgentPrism workflow scripts\n\nA workflow script is a small piece of plain JavaScript (passed around as a **string**, not a module) that orchestrates real, shipped coding agents. The engine runs the script in a deterministic sandboxed realm; every `agent()` call inside it fans out to an [Agent Client Protocol](https://agentclientprotocol.com) (ACP) backend \u2014 Claude Code, OpenAI Codex, OpenCode, pi, or any custom ACP agent server \u2014 which runs its own tool loop to completion and hands back the final text or a schema-validated object.\n\nThis guide is **backend-agnostic**: everything here works the same regardless of which agent serves a given call, and one script can freely mix backends per call. The **Workflow script reference** section at the end of this document holds the exhaustive option tables, routing grammar, and error codes.\n\n## The guide, by task\n\nEvery section of the guide is inlined below, after the core: MCP Server Setup, the source contract, models and structured output, composition and failure design, gates and lenses, the execution environment, determinism and resume, long-running trains, and worked examples with validation.\n\n## The mental model\n\n- **The script is the orchestrator; agents are workers.** All control flow \u2014 loops, fan-out, dedup, aggregation, conditionals \u2014 lives in script code. Never ask an agent to "spawn subagents" or "coordinate the other agents"; agents cannot do that. Decompose in the script and give each agent one self-contained task.\n- **Treat agent calls as memoryless orchestration boundaries.** Ordinary calls open fresh sessions, so thread everything a later call needs into its prompt explicitly. The sole automatic exception is recovery of the *same* usage/auth-interrupted occurrence: an unchanged, eligible resume may reopen that recorded session to finish its unfinished turn; it never gives a different call ambient memory.\n- **Agents are real coding agents, not chat completions.** They have file access, shells, and tools, rooted at the run\'s working directory. "Read the failing test and fix it" is a valid prompt; the agent will actually edit files.\n- **The DSL primitives are realm globals, not imports.** There is nothing to `import` \u2014 `agent`, `parallel`, `pipeline`, `gate`, `checkpoint`, `args`, `budget`, \u2026 are injected. Top-level `await` and a top-level `return` are valid (the body runs inside an async wrapper). The script\'s return value becomes the run\'s `result`.\n- **Assume every agent is brilliant, amnesiac, overconfident, and racing a world that changed since its prompt was written.** Every load-bearing pattern in this guide \u2014 self-contained prompts, evidence-demanding schemas, pinned bases re-checked every round, refusal as a first-class outcome \u2014 follows from those four facts. The script, not the agents, is responsible for compensating for them.\n- **Scripts are plain JavaScript, not TypeScript.** Type annotations fail to parse. There are also no Node APIs in the realm (no `require`, `import`, `fs`, `fetch`, timers) \u2014 all side effects happen through agents.\n- **Live observability requires no script annotations.** Journaling ACP runs publish coarse,\n  redacted progress and execution-partitioned transcript upserts at\n  `workflow://runs/{runId}/events`; MCP clients subscribe for update hints and page the durable\n  cursor. Author labels for human correlation, not to enable this behavior.\n\n## Minimal script\n\n```js\nexport const meta = {\n  name: "repo-summary",\n  description: "Summarize what a repository does",\n};\n\nconst summary = await agent(\n  `Read the README and the package manifests under ${args.path}, then ` +\n  `summarize what this project does in five sentences.`,\n  { label: "summarize" },\n);\nreturn { summary };\n```\n\nRunning scripts happens through the MCP server\'s `workflow` tool \u2014 server setup, the run/inspect/await/stop actions, and the `args`/`cwd` globals a running script receives are covered in the **MCP Server Setup** section below.\n\n## Pre-flight checklist\n\n- [ ] `export const meta = { name, description }` is the first statement, a pure literal.\n- [ ] No `Date.now()` / `Math.random()` / no-arg `new Date()` / `Date()`; no imports, no Node APIs \u2014 timestamps and randomness come in through `args`.\n- [ ] Every `parallel` element is a **thunk**; results are `.filter(Boolean)`-ed or null-checked.\n- [ ] Every agent prompt is self-contained \u2014 prior results interpolated in, no "as discussed above" \u2014 and every file path a prompt references is traceable to a writer (an earlier call, an `args` input, or that prompt\'s own instructions).\n- [ ] Schemas: object root, `additionalProperties: false`, everything `required`, `description` on every field; load-bearing fields checked for placeholders in script code.\n- [ ] Model specs only where a specific backend earns its keep; use a registered prefix plus a live-catalog-verified id (or backend-only form), and expect harness rejection rather than client fallback.\n- [ ] Model ids and effort values were read from `npx @automatalabs/workflows config` (or a validator report), not recalled from memory \u2014 and every pinned model was confirmed against its own per-pair validator echo (options are model-specific; provider variants of the same model advertise different domains).\n- [ ] Every `configOptions` id/value comes from the selected model\'s advertised-options table; `"model"` stays in the dedicated field, and any ordered thought-level clamp warning is intentional.\n- [ ] `mode` only on calls with a pinned `model`; worktree-isolated agents return their work as data.\n- [ ] Replay behavior is intentional: completed calls with matching identity/input fingerprints replay whether they read or write; change a hashed field (normally the prompt) when a completed call must run again. Do not add the legacy `resume: { filesystem: "read-only" }` field to enable replay\u2014it has no effect.\n- [ ] The run cwd is never assumed disposable: a committing workflow verifies an args-supplied workroot in a preflight step or creates its own persistent workspace idempotently (refuse, never force).\n- [ ] `checkpoint()` before irreversible actions \u2014 including the first commit into a user-owned checkout \u2014 with a sane headless `default` or an intentional `headless: "pause"` durable hand-off.\n- [ ] New-run `checkpointReplies` use source `checkpointContext.callIndex` keys; changed checkpoint defaults/headless modes/timeouts are expected to run fresh.\n- [ ] Budget loops guard on `budget.total`; caps and drops are `log()`-ed, not silent.\n- [ ] `return` a compact, structured result \u2014 it is the run\'s `result`, not a transcript.\n- [ ] Boolean-controlled convergence branches are scripted with mock answers (including reject-then-approve), not left to the all-true default \u2014 and the fixtures ship beside the script as `<name>.mock.json`.\n- [ ] The user\'s verbatim request sentences travel with the run (`args.sourceRequest` / a focus file), your prompts were diffed against them, and every genuine ambiguity became a question to the user \u2014 not a silent scope decision; a mutable external spec is snapshotted verbatim by the first call, and open decisions carry the source\'s stated lean.\n- [ ] Producer reports have an explicit refusal shape (a STOP-and-report `status` enum, not an implicit empty-array convention) and the checker recognizes it; report-shape validation runs in script code before any reviewer is spawned, and producer/reviewer SHA fields are compared in script code (values, not attested booleans).\n- [ ] Every reviewer charge is one falsifiable question with an evidence field capped in size; full detail goes to design-dir files outside the worktree.\n- [ ] Gates are bounded, a terminal adjudicator is designed in, and its findings feed a panel-free fix round \u2014 no unaddressed final-round blockers, no unbounded convergence hopes.\n- [ ] `npx @automatalabs/workflows validate <file> --args \'<json>\'` exits 0 with no surprising warnings.\n\nFor the complete `agent()` option table, model-routing grammar, checkpoint options, error codes, `meta.backends` config fields, and how hosts run scripts, see the **Workflow script reference** section below.\n\n\n## MCP Server Setup \u2014 how workflows actually run\n\nAgents run workflows through the single `workflow` tool served by `@automatalabs/mcp-server`. Register it once in the host\'s MCP configuration (project-scoped is typical):\n\n```json\n{ "mcpServers": { "agentprism-workflows": { "command": "npx", "args": ["-y", "@automatalabs/mcp-server@latest"] } } }\n```\n\nThe stdio command the host spawns is a thin **shim** that proxies to a shared per-user **workflow daemon** (Streamable HTTP on loopback, auto-started on first use). Workflow execution lives in the daemon, so runs survive the host killing the stdio process \u2014 session end, restarts, and tool timeouts do not stop in-flight work, and any later session can await/inspect/stop it. Every `run` call names its project via the **required `projectDir` argument** (an absolute path \u2014 normally the workspace root), so one registration, even a global one, serves every project; `inspect`/`await`/`stop` take only a runId, which locates its project store automatically. Add `--in-process` to the args for the pre-daemon single-process behavior (there `projectDir` is optional and defaults to the server\'s own project), or register the daemon\'s HTTP endpoint directly in HTTP-capable hosts (`agentprism-workflow daemon url` prints Claude Code and Codex snippets). The command resolves at spawn time, so a reconnect (`/mcp` in Claude Code) picks up the latest published version. Runs, journals, and logs persist under `~/.agentprism/workflows/` per project namespace, which is what makes background execution, inspection, and resume durable across tool calls, sessions, and daemon restarts.\n\n### The `workflow` tool, by action\n\n- **Run** (default, no `action`): supply exactly one of `script` (the raw source string, no Markdown fences) or `scriptPath` (an absolute path on the server\'s filesystem), plus `projectDir` (the absolute project directory \u2014 required on the daemon; it selects the project-scoped run store and the run\'s default execution cwd). A path is read once at admission and its content snapshotted, so later edits affect only a new run. `args` arrives in the script as the `args` global; the run\'s base directory is the `cwd` global. Some hosts hand `args` through as a JSON **string** \u2014 a robust script tolerates both shapes (`typeof args === "string" ? JSON.parse(args) : args`) before reading knobs off it. Foreground streams progress but is bound to the request (and its timeout); pass `background: true` for anything that may outlive one request \u2014 it acknowledges after durable admission with a `runId` and, for a resume, the admission-time `replayEligibility` plan.\n- **Await** (`{ action: "await", runId, waitMs }`): bounded collection for background runs \u2014 a timeout is progress, not failure; call again. The top-level status includes current `replayEligibility`; at terminal status the response adds `outcome` (the authored result or pause context, with the same eligibility plus `resumeReport`, `fallbacks`, and `checkpointsTaken`).\n- **Inspect** (`{ action: "inspect", runId, lastN, labelGlob, logLines }`): a bounded snapshot \u2014 latest matching calls with compact result previews plus the newest log lines. It includes current `replayEligibility` for resumed runs. Use a narrow `labelGlob` to diagnose before deciding whether to resume, edit, or stop. Inspection never executes or resumes a script; its cold preflight may only reconcile dead-owner status to `paused` / `interrupted`.\n- **Stop**: `{ action: "stop", runId }` durably aborts the whole live run and returns its final snapshot; stopping an already-terminal run is a successful no-op. `{ action: "stop", runId, callIndex }` instead cancels exactly that in-flight agent, settles its slot to `null` with `AGENT_CANCELLED`, and leaves the run live. The selected form errors for a settled, unallocated, checkpoint, ambiguous scoped index, or terminal run and lists the currently in-flight call-index/label pairs. `labelGlob` remains only a filter for the returned snapshot; it never selects what to cancel.\n- **Resume**: a NEW run with `resumeFromRunId` plus the script re-sent (same `script` content or `scriptPath`) and the desired `args` (+ `checkpointReplies` when answering a durable checkpoint). Read the returned `replayEligibility` for the predicted/observed prefix and first miss, and the terminal `resumeReport` for every per-call decision; never assume a prefix hit. The exact semantics live in **Determinism and resume**.\n\n### Operational rules that save runs\n\n- **Always retain the returned `runId`.** Paused/failed/aborted responses carry a redacted final-20 `logTail` \u2014 read it before changing anything. Every admitted script is also an immutable resource at `workflow://runs/{runId}/script` (results link the full resume lineage), so a later session can recover a lost inline script verbatim.\n- **Replay identity is explicit**: the identity hash covers prompt, resolved model, authored mode/non-empty sorted config options/tier/phase/agent type, the resolved agent definition, and schema. The separate input fingerprint covers resolved label, per-call cwd and isolation, `keepSession`, images, MCP servers, session/prompt metadata, and the approved script-backend digest. `replayEligibility.firstNonReplay` uses the frozen admission or per-call reason vocabulary listed in **Determinism and resume**, with `detail` naming a differing fact when one is derivable.\n- **Operational bounds are not replay inputs**: host `concurrency`, `agentRetries`, and `agentTimeoutMs`, plus per-call `timeoutMs` and `retries`, enter neither hash and can change on a resume without invalidating completed work or interrupted-turn continuation. A resume admission does not inherit host bounds from its source, so pass the desired values on every new run. `agentTimeoutMs` is a total wall-clock ceiling per attempt, not an idle timer; per-call `timeoutMs` may tighten it but cannot escape it. Each retry starts a fresh clock, for at most `(resolved retries + 1) \xD7 resolved timeout` with retries clamped to 3. Run, inspect, and await structured content report the resolved `limits`; `replayEligibility.operationalChanges` diagnoses source/current differences without gating replay.\n- **Compatibility is explicit**: input formats below 2 use `positional-v1` with `fallbackReason: "inputs-format-legacy"`; a current-format crash snapshot uses identity matching even without terminal-environment capture. Carried ancestor-scoped rows from \u22640.23 resume chains replay only while that ancestor run remains persisted. Journals resume across filesystem/environment, workflow-engine, Node, and V8 changes: `replayEligibility` surfaces those differences as diagnostics, never gates. Unsupported call-path/input/checkpoint formats remain named runtime mismatches.\n- **Runs are detached from clients, not just from requests** \u2014 they execute in the daemon, so a client disconnect, shim kill, or host exit never stops in-flight work; only daemon exit (signals, `daemon stop`, crash, machine loss) \u2014 or, under `--in-process`, that single process exiting \u2014 can. When a run\'s owner process does die, construction and cold inspect/list/await/stop/resume preflights take its stale lease and change only persisted `pending`/`running` state to `paused` with `pauseReason: "interrupted"`; a live or permission-protected owner is left alone. Completed journal entries remain available to `resumeFromRunId`, and an unjournaled in-flight call runs live. Background starts have no live checkpoint channel, so authored `headless` checkpoint modes apply.\n- Embedding hosts can instead call `runDynamicWorkflow` / `WorkflowManager` from `@automatalabs/workflows` directly \u2014 see the reference section on how hosts run scripts; the script contract is identical either way.\n\n## Start from the user\'s outcome \u2014 the source contract\n\nThe most expensive workflow failures are not crashes; they are flawless executions of the wrong scope. They enter at one seam: the prose YOU write between the user\'s request and the agents\' prompts. Downstream reviewers verify against your framing, so an assumption or a silent narrowing made here is amplified by every later stage, not caught. Before composing anything:\n\n- **Carry the user\'s words verbatim, not your summary of them.** Put the exact request sentences (including scope-bearing follow-ups from conversation \u2014 a later "and it must be first class" belongs beside the original ask) into the workflow\'s inputs: an `args.sourceRequest` field, a focus file the prompts reference, or both. Hosts may verify this mechanically; even where they don\'t, the discipline stands. Over-include \u2014 selection bias, not verbosity, is the failure mode.\n- **Anchor every derived stage to hop zero.** Specs, briefs, review prompts, and gate lenses should quote or reference the original sentences, never only the previous derivation. A chain that verifies hop N against hop N\u22121 will defend a hop-1 error forever; a chain that verifies against hop 0 self-corrects.\n- **Diff your prompts against the source before launching.** Enumerate what your prompts add that the user never asked for, what they drop, and what they reframe. Fix the mechanical deltas silently; put the genuine ambiguities to the user as binary questions ("Your request was: \u27E8X\u27E9. The workflow does: \u27E8Y\u27E9. Correct?") while corrections are still free. Never resolve an ambiguity by narrowing scope on your own authority \u2014 stated scope is an instruction, not an opening bid.\n- **Serve the implicit outcome too.** A user asking for a review wants findings they can act on (file:line, severity, evidence), not prose. A user asking for an implementation wants it shipped \u2014 tests green, docs consistent, zero deferred work \u2014 not a diff plus a TODO list. Encode the implicit bar in schemas and verification steps so the workflow cannot return something the user would have to finish themselves.\n- **Snapshot mutable specs before anything derives from them.** When the governing contract lives in a mutable external system \u2014 an issue tracker, a wiki, a shared doc \u2014 the workflow\'s FIRST call captures it verbatim (body plus scope-bearing comments) into the run\'s artifacts, and every later prompt anchors to that snapshot, never to the live object. A spec that can be edited mid-run is not an anchor.\n- **Open decisions travel with the source\'s stated lean.** When the source explicitly leaves a decision open and states a preference ("arguably desirable\u2026", "prefer X unless\u2026"), forward that decision to the stage that resolves it with the stated lean as the default, overridable only by cited evidence. Orchestration prose never quietly picks a side \u2014 least of all the disfavored one. A silent override at the prompt layer is scope drift no reviewer will catch, because every reviewer verifies against your framing.\n\n## Choosing the agent for each call\n\nThe backend is selected **per `agent()` call** from its effective `model` string. This is the core capability: one script can plan on one vendor\'s agent, implement on another\'s, and review on a third\'s, handing structured results between them.\n\nThe current built-in names (`claude`, `codex`, `opencode`, `pi`) are derived from the runtime\nbackend registry, not an authoring-only allowlist. Registered custom names extend that set.\n\n- **Omit `model` entirely** for maximum portability \u2014 the call runs on whatever default backend the host configured (`AGENTPRISM_DEFAULT_BACKEND`, or the host\'s session model). A script with no model specs anywhere runs unchanged on any backend.\n- **Route by one registered first segment.** Split on the first `/`; ASCII-case-insensitive `claude`, `codex`, `opencode`, `pi`, or a registered custom backend name selects that harness and is stripped exactly once. A custom registration wins on a built-in-name collision.\n- **Use a backend name alone** (`claude`, `codex`, `opencode`, `pi`, or a custom name) to preserve the harness\'s configured default model. No model config call is made.\n- **Everything else goes intact to the default backend.** `anthropic/\u2026`, `openai/\u2026`, bare `opus`, and bare `gpt-\u2026` are not routing aliases. When an id remains after routing, it is sent byte-for-byte: no catalog matching, case folding, bracket parsing, effort/Fast option driving, retry, or fallback. Brackets, dots, and provider prefixes are ordinary id characters; harness rejection is an agent error.\n- **`tier`** (`"small" | "medium" | "big"`) is a coarse alternative resolved from the host\'s tier config \u2014 use it when you want "a cheap model" without naming a vendor.\n\nThe published examples use ids verified against live harness catalogs: `claude/opus[1m]`, `codex/gpt-5.6-sol`, and `opencode/zai/glm-5.2`. For Pi, `pi/openrouter/vendor/model-id` strips only `pi/`; Pi then splits provider `openrouter` from model id `vendor/model-id`. Prefer backend-only forms when the desired model is configured inside the harness.\n\nNever guess model ids, effort values, or option names from memory \u2014 read the live catalog first:\n\n```bash\nnpx @automatalabs/workflows config                # every routable harness (claude, codex, opencode, pi + registered customs)\nnpx @automatalabs/workflows config codex --json   # one harness, machine-readable\n```\n\nOne no-prompt session per harness, zero tokens: the table lists every negotiable session option \u2014 model ids (including bracket variants like `opus[1m]`), effort levels, modes \u2014 exactly as the installed harness advertises them. But the bare `config` probe reads each harness with its **default model** selected, and option domains are **model-specific**: an option can appear only once a particular model is selected (an `effort` select surfacing for one model and not another), ceilings differ per model, and provider-served variants of the *same* model can advertise different domains (one provider\'s build may expose a level another lacks). The authoritative per-model probe is the validator run on your real script \u2014 it selects each authored `{ backend, model }` pair first and echoes that pair\'s advertised table. Authoring-then-validating IS the per-model probe; confirm every pinned model against its own echoed table, and do not read package internals to discover options.\n\n```js\nconst plan   = await agent(PLAN_PROMPT,          { label: "plan",      model: "opencode/zai/glm-5.2", schema: PLAN });\nconst impl   = await agent(implPrompt(plan),     { label: "implement", model: "codex/gpt-5.6-sol" });\nconst review = await agent(reviewPrompt(impl),   { label: "review",    model: "claude/opus[1m]", schema: REVIEW });\n```\n\nUse `configOptions` only for exact ACP session options advertised by that routed harness. Read the\nper-harness advertised-options table first \u2014 `npx @automatalabs/workflows config <harness>`, or the\nsame table in every validator report \u2014 before choosing ids or select values; catalogs vary by\nharness version, login, and machine.\n\n```js\nconst impl = await agent(implPrompt(plan), {\n  label: "implement",\n  model: "codex",\n  configOptions: { "fast-mode": true, reasoning_effort: "high" },\n});\n```\n\nIds and string/boolean values pass through verbatim in ascending id order, after model selection\nand before the prompt. There are no aliases, coercion, client-side vocabulary, defaults, or cached\ncatalogs. Copy option ids character-for-character from the catalog, punctuation included \u2014\n`"fast-mode"`, not `fast_mode` \u2014 and quote ids that are not valid identifiers. Never put `"model"`\nin `configOptions`; use the dedicated `model` field. A harness rejection follows the ordinary\nagent-error path.\n\nPi\'s thought-level option is named `thinkingLevel`, and its choices depend on the exact model in\nthe same call:\n\n```js\nconst review = await agent(REVIEW_PROMPT, {\n  label: "pi-review",\n  model: "pi/openrouter/vendor/model-id",\n  configOptions: { thinkingLevel: "high" },\n});\n```\n\nValidation selects `openrouter/vendor/model-id` before reading Pi\'s choices. A listed value passes\nunchanged. A recognized value above an ordered backend model\'s ceiling or in a model-specific gap\npasses with a warning that names the effective clamp target. Pi advertises its SDK-derived domain\ndirectly. Claude and Codex are also ordered; when their options omit domain metadata, validation\nenumerates the advertised models and merges their per-model effort orders. Claude\'s missing\n`effort` option means that model does not support it, and `default` never becomes a ceiling target.\nOpenCode and custom/unknown backends use exact-set validation because their values have no declared\ntotal order. In every case, an unrecognized or exact-set-unadvertised value fails with exit code `2`.\nEnumeration is bounded at 32 advertised models; a larger or inconsistently ordered catalog warns\nand uses exact advertised-value validation.\n\nTwo things worth designing for:\n\n- **Cross-vendor independence.** Reviewing or verifying with a *different* vendor than the one that produced the work removes correlated blind spots \u2014 an agent family tends to approve its own idioms. When correctness matters, judge across vendors.\n- **The harness is authoritative.** The client never substitutes a nearby model or silently falls back. A rejected id follows the existing agent-error path; a harness that accepts or ignores it determines the outcome. The public `fallbacks`/`onModelFallback` fields remain for compatibility but model resolution does not emit them.\n\n## Structured output\n\nPass `schema` \u2014 a **plain JSON Schema object literal** (no schema builders exist inside the realm) \u2014 and the call resolves to a **validated object** instead of text:\n\n```js\nconst FINDINGS = {\n  type: "object",\n  additionalProperties: false,\n  required: ["findings"],\n  properties: {\n    findings: {\n      type: "array",\n      items: {\n        type: "object",\n        additionalProperties: false,\n        required: ["file", "line", "summary"],\n        properties: {\n          file:    { type: "string", description: "Repo-relative path \u2014 copy it exactly, never invent one" },\n          line:    { type: "number", description: "1-indexed line the finding anchors to" },\n          summary: { type: "string", description: "One sentence stating the defect, grounded in code you actually read" },\n        },\n      },\n    },\n  },\n};\n\nconst report = await agent("Review the diff on this branch for correctness bugs.", {\n  label: "review", schema: FINDINGS,\n});\nreport.findings.forEach((f) => log(`${f.file}:${f.line} ${f.summary}`));\n```\n\nThe same schema works on **every** backend; only the fulfillment channel differs, and the runner picks it for you: Claude uses its `outputFormat`, Codex its strict `outputSchema`, while Pi, OpenCode, and eligible custom ACP agents receive a client-hosted `StructuredOutput` MCP tool when they advertise HTTP MCP support. Pi accepts stdio, Streamable HTTP, and SSE MCP servers. If no valid tool capture exists, Pi retains the runner\'s common prompt-embedded schema and validated final-text JSON fallback. In every channel the runner validates the value client-side (with type coercion) and re-prompts a bounded number of times before failing the call with non-recoverable `SCHEMA_NONCOMPLIANCE`.\n\nSchema authoring rules that keep all channels healthy:\n\n- Root must be an object; set `additionalProperties: false` and list every property in `required`.\n- Put a `description` on every field \u2014 descriptions are the per-field prompt, and they are the difference between grounded values and guesses.\n- Keep schemas structurally simple. Exotic keywords (`oneOf`, `patternProperties`, unusual `format`s, backreference regexes) are normalized or stripped on the wire for some backends \u2014 validation still enforces them client-side, which shows up as re-prompt churn. Prefer `anyOf`, `enum`, and plain types.\n- **Guard load-bearing fields against placeholders.** Agents under schema pressure sometimes emit `"TODO"`, `"unknown"`, or an invented path. Say "populate every field from evidence; never emit placeholder values" in the prompt, and check critical fields in script code (e.g. reject findings whose `file` doesn\'t appear in a known file list) before spending more agents on them.\n\n## The `meta` header\n\nEvery script must **begin** with `export const meta = {...}` as a plain object literal (no computed values \u2014 it is parsed from the source text before anything runs):\n\n```js\nexport const meta = {\n  name: "fix-flaky-tests",                        // required\n  description: "Find flaky tests and fix them",   // required\n  phases: [                                        // optional; one entry per phase() call\n    { title: "Find", model: "opencode/zai/glm-5.2" },  // per-phase default model\n    { title: "Fix" },\n  ],\n  model: "claude/sonnet",                          // optional run-wide default model\n  backends: { /* optional custom ACP agents \u2014 see "Custom ACP backends" */ },\n};\n```\n\nPer-agent model resolution order: explicit `agent({ model })` > `agent({ tier })` > the current phase\'s `model` > `meta.model` > the host session\'s default. So `meta.phases[].model` is how you give a whole phase a backend without repeating it on every call.\n\n## Fan-out: `parallel` and `pipeline`\n\n```js\n// parallel: an array of THUNKS (not promises!) run concurrently \u2014 a barrier that\n// resolves in input order. A failed slot resolves to null; filter before use.\nconst sweeps = (await parallel([\n  () => agent("Audit error handling in src/server", { label: "sweep:errors", schema: FINDINGS }),\n  () => agent("Audit input validation in src/api",  { label: "sweep:input",  schema: FINDINGS }),\n])).filter(Boolean);\n\n// pipeline: each item flows through the stages independently \u2014 NO barrier between\n// stages, so item A can be in stage 2 while item B is still in stage 1.\n// Stages receive (previousResult, originalItem, index).\nconst verified = (await pipeline(\n  sweeps.flatMap((s) => s.findings),\n  (f) => agent(`Adversarially verify this finding \u2014 try to refute it:\\n${JSON.stringify(f)}`,\n               { label: `verify:${f.file}`, schema: VERDICT }),\n  (verdict, f) => ({ ...f, real: verdict.real }),\n)).filter(Boolean).filter((f) => f.real);\n```\n\n**Default to `pipeline`** for multi-stage work; use a `parallel` barrier only when the next stage genuinely needs *all* prior results at once (dedup across the full set, early-exit on a zero count, prompts that compare "the other findings"). The test is always the **information dependency**, never the org chart: "these stages are conceptually separate" or "this reads cleaner" are not reasons for a barrier, and a barrier\'s cost is real \u2014 the fastest worker idles for the slowest. Likewise, all coordination lives in script code: never ask an agent to "check with the other reviewers" or "spawn helpers" \u2014 agents cannot see each other, and the ones that try will hallucinate colleagues. Passing a promise instead of a thunk to `parallel` is a `TypeError` \u2014 wrap every call: `() => agent(...)`.\n\nFan-out also contends for the **working tree**, not just the concurrency limiter. Two agents running builds or test suites in the same checkout collide on build outputs, caches, and lockfiles, and concurrent `git fetch`es contend on the same `.git` \u2014 none of it visible in script code. Give run-things reviewers `isolation: "worktree"` when the commits they must inspect are reachable from the run cwd\'s repository, or serialize them; fan out freely only the agents that just read. In a shared tree, freshness checks use `git ls-remote` (no local mutation), never `git fetch`.\n\nThe host caps concurrent agents per run (default 8); hand `parallel`/`pipeline` as many items as the task needs and let the limiter schedule them. `workflow(nameOrScript, args)` nests another workflow inline (one level deep, sharing this run\'s budget and limiter) \u2014 inline script strings always work; saved names resolve when the host serves a workflows folder (`openWorkflowDir` / the `workflows` run option \u2014 see the reference section below).\n\n## Failure semantics \u2014 design for `null`\n\n- A **recoverable** failure (timeout, empty output, transient execution error) is retried per the call\'s `retries` (default 0), then the call **resolves to `null`** \u2014 inside `parallel`/`pipeline` *and* as a bare `await agent(...)`. Null-check anything load-bearing, and set `retries: 1\u20132` on steps you can\'t afford to lose.\n- A host can settle one runaway in-flight call with MCP `{ action: "stop", runId, callIndex }` or SDK `manager.cancelAgentCall(runId, callIndex)`. The call resolves to `null` with `AGENT_CANCELLED`, skips every configured retry, and does not abort the run or its siblings. Its failed call record is inspectable but is not cached as a journal result, so a later resume runs that occurrence live.\n- A **non-recoverable** failure (schema never validated, script bug) throws and fails the run. You *may* `try/catch` around an `agent()` call to degrade gracefully \u2014 rethrow anything you can\'t meaningfully handle. In particular, **always rethrow pause-class errors** (`err.code === "PROVIDER_USAGE_LIMIT"` or `"AUTH_REQUIRED"`): they must propagate out of the script so the engine can pause the run resumably \u2014 swallowing one converts that pause into a fake, lossy completion.\n- A **provider quota wall, missing backend authentication, or opted-in durable checkpoint pauses a managed run instead of failing it** \u2014 the journal checkpoints and the host can resume after the budget refills, authentication completes, or a checkpoint decision is supplied. Direct `runner.run()` calls still receive the `AUTH_REQUIRED` error because they have no manager lifecycle.\n- Per-call knobs: `timeoutMs` and `retries`. A finite `timeoutMs` may shorten the host\'s run-level\n  `agentTimeoutMs` ceiling; `null` or omission is uncapped only when the host supplied no ceiling.\n  The timeout is total wall-clock time per attempt, and every retry gets a fresh clock. The maximum\n  timeout envelope is `(resolved retries + 1) \xD7 resolved timeout`, with retries clamped to 3.\n- **Make refusal a first-class outcome (STOP-and-report).** For implementation and spec work, give the producer an explicit refusal shape \u2014 a `status: "implemented" | "stopped"` enum plus the discrepancy verbatim in a `deviations` field. Prefer the enum over an implicit convention like "empty `commitShas` means refusal": a round can legitimately have both commits and deviations, and the checker should never have to guess. Pair it with the instruction that a cited surface that does not exist as cited means STOP, never improvise. Then make your checker RECOGNIZE that shape: set a flag, exit the loop, skip adjudication, and surface it for the owner. A correct refusal routed into "round failed, try again" wastes every remaining round; the plausible-looking alternative \u2014 the agent quietly building around the discrepancy \u2014 is worse, because the mismatch is usually a stale base, not a wrong spec.\n- **Treat provider failure as an expected path, not an anomaly.** Rate limits, capacity collapse on newly launched models, and schema-repair exhaustion on oversized outputs all happen mid-run. Keep the recovery knobs at the host level where they are NOT identity-hashed \u2014 concurrency caps, engine retries, labels \u2014 so a resume can turn them without invalidating completed work. When one panel model\'s provider degrades, swapping that role to a stable model (an owner decision, disclosed) beats burning rounds on retries.\n\n## Budgets and phases\n\n```js\nphase("Explore", { budget: 100_000 });   // soft per-phase token sub-budget\n// budget.total (null = unbounded) \xB7 budget.spent() \xB7 budget.remaining() (Infinity when unbounded)\n\nconst found = [];\nwhile (budget.total && budget.remaining() > 50_000 && found.length < 20) {\n  const r = await agent("Find one more edge case not in: " + JSON.stringify(found.map((f) => f.name)),\n                        { label: `edge:${found.length}`, schema: EDGE });\n  if (!r) break;\n  found.push(r);\n}\n```\n\nGuard budget-driven loops on `budget.total` being set \u2014 with no budget, `remaining()` is `Infinity` and only your own counters stop the loop. The run-level token budget and agent-count cap are hard: once exhausted, further `agent()` calls throw. `phase()` also groups agents in progress UIs and run logs; `log(msg)` (and `console.log`) append to the run log \u2014 narrate what matters, especially anything you drop or cap.\n\nThe concurrency cap counts active agent attempts, not authored branches. If one `parallel()` branch\nis slow, queued branches begin as other attempts finish. A branch that exhausts its timeout settles\nto `null` after retries and immediately frees its slot; a host-cancelled branch does the same without\nretrying. Finite ceilings and targeted cancellation keep one stalled worker from holding a slot\nindefinitely.\n\n## Built-in quality loops\n\nThese helpers spawn their own subagents (on the default model \u2014 hand-roll with `parallel` + `agent` when you want panel members on specific backends). Full signatures in the reference section below.\n\n| helper | shape | use for |\n|---|---|---|\n| `gate(produce, validate, { attempts })` | produce \u2192 validate \u2192 feed `feedback` back; return `{ ok, value, verdict, attempts }` | produce-until-a-reviewer-approves loops that need the final review evidence |\n| `retry(thunk, { attempts, until })` | bounded retry until `until(result)` holds | flaky single steps |\n| `verify(item, { reviewers, threshold, lens })` | N adversarial reviewers vote `real`/not | killing plausible-but-wrong findings |\n| `judgePanel(attempts, { judges, rubric })` | score candidates 0\u20131 against a rubric, return the best | picking among independent solutions |\n| `loopUntilDry({ round, key, consecutiveEmpty, maxRounds })` | repeat a round, dedup by `key`, stop when dry | unknown-size discovery (bugs, edge cases) |\n| `completenessCheck(args, results)` | one critic lists what\'s still missing | a final "what did we not cover?" pass |\n\nThe `gate` pattern, spelled out \u2014 note how the producer thunk threads the validator\'s feedback into a *fresh* agent\'s prompt (sessions have no memory):\n\n```js\nconst outcome = await gate(\n  (feedback, attempt) => agent(\n    `Implement the fix described here:\\n${JSON.stringify(plan)}\\n` +\n    (feedback ? `\\nA reviewer rejected attempt ${attempt}: ${feedback}\\nAddress every point.` : ""),\n    { label: `fix:${attempt + 1}`, model: "codex/gpt-5.6-sol" },\n  ),\n  (result) => agent(\n    `Run the test suite and review this change summary:\\n${result}\\n` +\n    `Return ok=true only if tests pass and the fix is correct; include the reviewed commit SHA.`,\n    { label: "gate-review", model: "claude/opus[1m]", schema: { type: "object", additionalProperties: false,\n      required: ["ok"], properties: { ok: { type: "boolean" }, feedback: { type: "string" },\n        commitSha: { type: "string" } } } },\n  ),\n  { attempts: 3 },\n);\nif (!outcome.ok) log(`reviewer never approved after ${outcome.attempts} attempts`);\nelse log(`reviewer approved commit ${outcome.verdict?.commitSha ?? "(unspecified)"}`);\n```\n\n## Designing review gates and lenses\n\nThe quality helpers give you the machinery; these rules \u2014 each bought with a real failure \u2014 govern how to aim it:\n\n- **A lens is a falsifiable question, not a job title.** Charge each reviewer with ONE failure mode and an explicit pass condition: "ok=true only if you *failed* to find a real bug" reads differently to a model than "review for correctness", and the difference shows in output. Overlapping mandates produce duplicate findings and diffuse accountability.\n- **Force evidence generation, not opinion formation.** Require an `evidence` field of literal commands + exit codes; charge reviewers to *run* things \u2014 drive the e2e themselves, reproduce the bug on the wire, re-run the suite from the committed state. A lens that only reads produces plausible opinions; a lens that runs produces facts. Always include one lens whose entire job is independently re-verifying greenness while trusting nothing in the producer\'s report.\n- **Cap the structured fields; overflow to files.** Evidence and feedback fields must stay small (tens of lines) \u2014 an oversized structured output can fail schema repair and kill the round. Full transcripts and detailed findings go to per-round files in a design directory; the structured verdict carries conclusions and pointers. A worktree-isolated reviewer\'s checkout is destroyed when its call ends, so point its overflow files at an absolute design directory OUTSIDE the repository; at minimum, the terminal adjudication is always written somewhere durable.\n- **Demand values, not attestations.** A schema field that asserts a check passed (`headMatchesReport: true`) can be emitted without the check ever running. Require the underlying value instead: the producer reports its `headSha`, each reviewer reports the `reviewedHeadSha` it actually inspected, and SCRIPT CODE compares them. The comparison is free and unfakeable \u2014 it turns "the reviewer says it looked at the right commit" into "the reviewer provably did".\n- **Gate the plan before the expensive rounds.** For plan-and-implement work, the plan itself deserves one bounded cross-vendor review before any implementer runs \u2014 a plan defect costs every downstream round. Strongest form: make the plan schema carry its own source diff (`additions` / `omissions` / `reframings` against the verbatim source, with omissions and reframings required empty), so hop-zero fidelity is enforced by the schema at runtime instead of only by authoring discipline.\n- **Diversity of question beats count of reviewers \u2014 and watch for the question nobody owns.** Distinct failure-mode lenses (compliance, correctness, deferred work, green-verify) beat N generic reviewers. When every lens verifies against the same derived artifact, add one whose only input is the ORIGINAL source (the user\'s verbatim request) and whose only question is fidelity: enumerate every addition, omission, narrowing, or reframing. Scope drift is invisible to every other lens by construction.\n- **Constrain each lens\'s jurisdiction explicitly.** A minimalism lens will otherwise "improve" the design by descoping requested features: state that it judges HOW, never the owner\'s WHAT. Requested scope is not a design variable.\n- **Feedback must be self-contained.** The producer\'s next round sees ONLY the feedback string \u2014 sessions are memoryless. Never template in references to files that may not exist ("read review-X.md" when no reviewer ran); interpolate everything the producer needs. A phantom citation sends an honest producer into a correct-but-wasteful STOP. The rule generalizes beyond feedback: EVERY path any prompt references must be traceable to a writer \u2014 an earlier call instructed to create it, a host-supplied `args` input, or that same prompt\'s own instructions. Before launching, walk every interpolated path in the script and name its writer; a file that "should obviously exist" but has no writer is one of the commonest authoring defects.\n- **Adversarial gates do not self-converge \u2014 design the terminal state.** At high effort, each fix commit is fresh attack surface: rejections narrow but never reach zero on their own. Bound the rounds, then run a TERMINAL adjudicator whose verdict is final: it reads all rounds\' files, independently spot-checks surprising verdicts in both directions (lens verdicts are inputs, not votes), resolves what the repo actually answers, and emits findings as a CLOSED list plus any genuine owner decisions.\n- **The fix round after adjudication uses no panel.** One producer pass applying the closed list exactly \u2014 nothing more \u2014 judged directly by the SAME adjudicator re-verifying its own findings. Re-opening a multi-lens gate on a fix round generates novel findings forever. Match review breadth to the openness of the question: open question \u2192 panel; closed list \u2192 the author of the list.\n- **Reconcile contradictions above the producer.** When lenses (or rounds) issue conflicting directives, the workflow owner adjudicates before the next produce round \u2014 an implementer will otherwise obey whichever spoke last, and the conflict lands unresolved on the terminal verdict.\n- **Don\'t spend lenses where code suffices.** SHA-format checks, placeholder detection, "does the report name the mandated path" \u2014 script code, run in the checker BEFORE any reviewer burns tokens. Lenses are expensive instruments; point them only at questions requiring judgment.\n\n## Human gates: `checkpoint()`\n\n`checkpoint(promptText, options?)` is a zero-token, journaled human gate. With MCP elicitation (or a live SDK `confirm` callback) it waits for that reply; without a live channel, its default mode takes `default ?? true` immediately, so detached runs never hang.\n\n```js\nconst proceed = await checkpoint(`Apply this plan?\\n${JSON.stringify(plan, null, 2)}`, {\n  kind: "confirm",          // "confirm" | "input" | "select"\n  default: false,           // default headless mode takes this (or true)\n  // headless: "abort",     // abort when no live human is attached\n  // headless: "pause",     // or persist a resumable human-decision pause\n});\nif (!proceed) return { applied: false, plan };\n```\n\n`kind: "input"` resolves to free text, `kind: "select"` to one of `choices`. How the question reaches a human is the host\'s job (elicitation in the MCP server; `ExecOptions.confirm` in the SDK). With no live channel, `headless: "default"` (the default) takes `default ?? true`, `"abort"` aborts, and `"pause"` returns a managed run with `reason: "checkpoint_required"` plus non-secret `checkpointContext`. Resume the last mode with `checkpointReplies: { [context.callIndex]: decision }` or a live confirm. For `resumeFromRunId`, that key is the source context index; an unambiguous identity match may journal the injected answer at a shifted current index. Put a checkpoint before anything hard to reverse \u2014 applying diffs, pushing, publishing \u2014 and treat the FIRST commit into a user-owned checkout as exactly that: a workflow that mutates a working copy it did not create carries at least one checkpoint before its first mutation (`default: true` keeps detached runs moving).\n\n## Working directory, isolation, confinement\n\n- Every agent session runs in the run\'s base `cwd` unless the call narrows it: `agent({ cwd: "packages/api" })` (relative resolves against the base).\n- `isolation: "worktree"` runs the agent in a **throwaway git worktree** (`<repoRoot>/.agentprism/worktrees/\u2026`) so parallel agents can edit without colliding. The worktree and its branch are **always deleted when the call ends \u2014 an isolated agent\'s file edits are discarded**. Have isolated agents *return their work as data* (a unified diff, a file map, a report) and apply it in a later non-isolated step; use worktrees for experiments, builds, and verification, not for persistent edits. Outside a git repo, isolation degrades to the shared tree with a logged notice.\n- `resume: { filesystem: "read-only" }` is a deprecated compatibility annotation. It is not a runner mode and has no effect on replay; completed calls replay by journal correspondence whether they read or write. Use `mode`, tool policy, prompts, and worktrees when you actually need confinement.\n- `mode` requests an agent-advertised ACP session mode and is **strict** \u2014 an unsupported mode fails the call rather than running unconfined. Mode ids are backend-specific (Claude-family: `plan`, `acceptEdits`, `bypassPermissions`; Codex-family: `read-only`, `agent`, `agent-full-access`; OpenCode via its mode option; Pi advertises thinking-level config rather than modes), so only set `mode` on calls whose `model` you also pin. Use read-only/plan modes for reviewers and auditors that must not write.\n- `agentType: "<name>"` binds a reusable subagent definition \u2014 a Markdown file at `<cwd>/.agentprism/agents/<name>.md` (project) or `~/.agentprism/agents/<name>.md` (user; project wins) whose frontmatter sets tool allow/deny lists, a model, and isolation, and whose body is the role prompt. An unknown name logs a warning and degrades to defaults.\n\n## Where a mutating workflow runs\n\nThe run\'s base `cwd` is the USER\'S checkout \u2014 the working copy they launched the host from. Treat it as borrowed, never disposable: committing onto whatever branch happens to be checked out, switching its branches, or resetting it are defects unless the user explicitly asked for exactly that. The most expensive environment failures are silent assumptions ("cwd will be a prepared worktree", "the current branch is mine to commit on") that hold only in the author\'s head; scripts that commit must make their environment contract explicit, one of two ways:\n\n1. **Require a prepared workroot via `args` and verify it before any edit.** A preflight step confirms the expected branch, the recorded base, and a clean tree \u2014 and refuses (STOP-and-report) on any mismatch instead of adapting to it.\n2. **Create a persistent workspace in a setup call.** E.g. `git worktree add <sibling-path> -b <branch> origin/<default>`, idempotently: reuse the workspace when it already matches, refuse when the path or branch exists in any other state. Never force-delete or overwrite anything the workflow did not create.\n\n`isolation: "worktree"` is NOT this workspace: it is per-call and throwaway \u2014 the checkout and its branch are deleted when the call ends. Use it for experiments, builds, and verification; use a setup-created persistent worktree (or a verified args-supplied one) as the train\'s home. Note also that the throwaway worktree branches from the run cwd\'s repository: an isolated reviewer sees a producer\'s commits only when they are reachable there \u2014 in a shared object store (the workroot is a worktree of the same repo) it can `git checkout --detach <reported SHA>` to inspect them; when the commits live in an unrelated clone, isolation reviews the wrong tree.\n\n## Wiring tools and inputs into a call\n\n- `mcpServers: [{ name, command, args: [], env: [] }]` attaches MCP servers to that agent\'s session \u2014 the portable way to hand any backend a capability (image generation, a browser, a ticket system). The agent sees the server\'s tools natively. Note `env` is a list of `{ name, value }` pairs (ACP shape), not an object map; HTTP/SSE servers use `{ type: "http", name, url, headers: [] }`.\n- `images: [...]` appends base64 image blocks to the prompt (backends without image support receive a bracketed text note instead).\n- `meta` / `promptMeta` pass generic ACP `_meta` through to `session/new` / `session/prompt` \u2014 the escape hatch for driving a custom agent\'s extension surface.\n- `keepSession: true` keeps a successful agent\'s ACP session re-openable after the run: the re-attach record (sessionId, backend, effective pool identity, cwd, reopen capabilities) lands in `WorkflowRunResult.agentSessions`, and the HOST can continue that conversation later via `runner.loadSession()`. Usage/auth pause failures are kept open automatically so managed resume can continue the interrupted occurrence. Scripts themselves never request reattach.\n\n### Custom ACP backends\n\nAny process that speaks ACP over stdio can serve `agent()` calls \u2014 an in-house browser-QA agent, an image generator, a domain-specific executor. Two ways in:\n\n1. **Host-registered** (preferred): the embedder passes `createAcpRunner({ backends: { browser: { command: "/abs/browser-acp" } } })`; the script just routes with `model: "browser"`.\n2. **Script-declared**: the script itself declares the backend in `meta.backends` \u2014 but declarations are **inert until the host approves them** (an elicitation in the MCP server; `allowScriptBackends` in the SDK), because they spawn commands on the host machine. Don\'t rely on them silently working.\n\n```js\nexport const meta = {\n  name: "checkout-qa",\n  description: "Implement, then QA the checkout flow in a real browser",\n  backends: {\n    browser: { command: "browser-acp", args: ["--headless"] },  // requires host approval\n  },\n};\n\nconst change = await agent("Implement the coupon-code field per the spec in docs/coupon.md.",\n                           { label: "implement" });              // default backend\nconst verdict = await agent(\n  `Open the app, walk through checkout with coupon SAVE20, and verify the discount line. Change summary:\\n${change}`,\n  { label: "qa", model: "browser",                               // the custom agent\n    schema: { type: "object", additionalProperties: false, required: ["passed"],\n              properties: { passed: { type: "boolean" }, notes: { type: "string" } } } },\n);\nreturn { change, qa: verdict };\n```\n\nStructured output works on custom backends through the same injected-tool/fallback ladder as OpenCode \u2014 no special-casing in the script.\n\n## Determinism and resume\n\nRuns are journaled: every `agent()` and `checkpoint()` result is recorded under a deterministic call index. A new run may reuse eligible results from a terminal source, but uncertainty always means live execution.\n\n> **Resume rule:** replay is content-addressed and fail-to-live on correspondence: a completed call replays when its identity and input fingerprint match uniquely. Filesystem or world state never gates replay.\n\n- Direct `Date.now()`, `Math.random()`, and no-arg `new Date()` / `Date()` calls fail static validation. The realm also blocks aliased or computed forms at runtime (`new Date(isoString)` is fine). Need a timestamp or random seed? Pass it through `args`.\n- An `agent()` replay identity hashes the prompt, resolved `model`, `mode` when set, `configOptions` when non-empty (with sorted keys), `tier`, `phase`, `agentType`, the resolved agent definition, and `schema`. An omitted or empty config bag preserves existing hash bytes. The resolved definition covers its tool allowlist/denylist, model, isolation, and body prompt, so editing an agent definition invalidates calls that use it.\n- A separate execution-input fingerprint hashes the resolved label, per-call `cwd`, resolved isolation, `keepSession`, `images`, `mcpServers`, `meta`, `promptMeta`, and the approved script-backend digest. Host `agentTimeoutMs`, `agentRetries`, and `concurrency`, plus per-call `timeoutMs` and `retries`, are operational bounds: they enter neither identity nor the input fingerprint and may change freely on resume. A new run resolves them from its own request instead of inheriting the source values.\n- `args` is not hashed directly. If new args only raise a loop cap, earlier calls with the same identities and input fingerprints can replay. If new args change a prompt, model selection, phase, schema, call order, or runner-visible input, affected calls run live; unchanged independent calls may still replay.\n- Identity matching first tries a unique exact `(kind, call path, identity hash)` row (`"path-hash"`), then a unique `(kind, identity hash, input fingerprint)` row so unchanged calls can replay as `"unique-hash"` after insertions/deletions. Source and current input fingerprints must be equal. Duplicate exact identities, duplicate content, consumed candidates, missing facts, and empty schema-less results run live\u2014no source-order or occurrence guess.\n- Source admission requires exact `cwd`, compatible call-path/input/checkpoint fingerprint formats, complete call/journal/allocation metadata, and a valid manifest/seed. Git HEAD/dirty digest, `environmentKey`, captured start/terminal environment values, Node/V8, and producing engine version are diagnostics only. Provenance compares the recorded terminal environment (or start environment when no terminal capture exists) with the current environment; differences may appear in `replayEligibility.provenanceChanges` but never gate admission or matching.\n- A completed matching writer replays exactly like a reader. A live call, nested workflow, host checkpoint callback, or degraded worktree does not clear unrelated candidates. Nested child calls themselves run live because they are outside the parent\'s journal; matching root calls around them remain replayable. The engine does not reproduce file writes or decide whether the live world is safe\u2014that is deliberately left to the live agent\'s intelligence.\n- Identity replay preserves budget-driven control flow: cached agents add their source logical debit to `budget.spent()`/`remaining()`, but add zero current provider/token usage. Replayed session records keep their backend/session identity and are rebound to the current call index, label, and phase.\n- A root agent interrupted by `PROVIDER_USAGE_LIMIT` or `AUTH_REQUIRED` is continuation-eligible on both same-ID and `resumeFromRunId` recovery. The engine requires the exact call index, identity hash, complete input fingerprint, non-worktree isolation, identical existing cwd, coherent recorded session, and the runner\'s current backend/`poolKey`/reopen gates. A successful resume/load continues the unfinished turn and charges only its usage delta; every failed gate runs fresh. `fallbacks` records the reattached method or exact skip reason. No script option enables or disables this.\n- Completed checkpoint results replay when identity and the `default`/`headless`/`timeoutMs` fingerprint match, including headless results. `checkpointReplies` keys always name the checkpoint index in the source run. A moved reply can follow intact prior journal correspondence; after a prior live divergence it must reach the exact recorded call site, so a different same-text branch cannot consume it.\n- `resumePolicy: "positional"` is a migration escape hatch for index/prefix matching, not permission to bypass new-format format, metadata, manifest, cwd, or input checks. It does not require safety annotations. Marker-less/manual/same-ID legacy journals keep historical hash-only positional behavior. A current-format crash snapshot with a valid identity manifest uses identity matching even without a terminal environment; old input formats use the `inputs-format-legacy` hash-only positional bridge and are rewritten under the current format for the next hop. A carried prefix from a \u22640.23 resume hop is eligible when each row is unscoped, scoped to the immediate source, or scoped to an ancestor run still persisted beside it. Engine-minted nested scopes and deleted ancestor scopes are excluded.\n- `label`, `cwd`, `mcpServers`, `images`, `meta`, `promptMeta`, and `keepSession` are not identity-hashed. Changing one does not invalidate an ordinary cached replay, but these fields are in the separate input fingerprint: changing one rejects continuation of an interrupted turn and runs that occurrence fresh. Change a hashed field, normally the prompt, when an already-completed call must execute again.\n- Keep call order deterministic. Derive iteration from `args` and prior agent results, never from ambient state.\n\nEvery `resumeFromRunId` result has a bounded `replayEligibility` summary. MCP background admission, foreground completion, both await shapes, and inspect expose the same strategy, predicted replayable-prefix length, observed replayed prefix/counts, and first non-replay when one is known. Active correspondence reasons include `strategy-live`, `positional-miss`, `positional-suffix`, `not-recorded`, `path-missing`, `inputs-missing`, `inputs-changed`, `ambiguous-identity`, `ambiguous-content`, `candidate-consumed`, `empty-output`, `worktree-degraded`, `seed-persistence-error`, and `resume-fatal-latch`. Older safety/world reason literals remain exported only so historical journals and consumers parse. Engine/input-format versions and environment/Node/V8 provenance appear alongside the report as diagnostics.\n\nAn all-live outcome is expected when correspondence cannot be established, not when the world changed. Missing resume metadata, incompatible format literals, or an invalid manifest/seed can disable new-format replay. If any source result lacks a captured path/input fact\u2014possible when a call stack exceeds the raw-frame cap or `meta` is not strict JSON\u2014the whole source is `"manifest-invalid"`; dropping that row could make an ambiguous sibling look unique. Identity-v1 fingerprint bytes are never reinterpreted: format-1 sources enter the input-format bridge, and a format greater than the current format is `"runtime-mismatch"`.\n\n### Worked resume \u2014 raise a loop cap\n\nThe following workflow requires eight reviews but lets the caller cap how many are attempted in one run:\n\n```js\nexport const meta = {\n  name: "resume-loop-cap",\n  description: "Run expensive review rounds up to an args-controlled cap",\n  phases: [{ title: "Review" }],\n};\n\nconst input = args && typeof args === "object" && !Array.isArray(args) ? args : {};\nconst numericCap = Number(input.maxRounds);\nconst maxRounds = Number.isInteger(numericCap) && numericCap > 0 ? numericCap : 8;\n\nphase("Review");\nconst rounds = [];\nfor (let i = 0; i < maxRounds; i += 1) {\n  rounds.push(\n    await agent(\n      `Review round ${i + 1}: inspect the repository and report unresolved release blockers.`,\n      { label: `review:${i + 1}`, phase: "Review" },\n    ),\n  );\n}\n\nif (maxRounds < 8) throw new Error(`review cap ${maxRounds} reached before 8 rounds`);\nreturn { rounds };\n```\n\nWith the MCP `workflow` tool, run it first with `args: { "maxRounds": 6 }`. Then send the same\ncontent (again via `script`, or via the absolute `scriptPath` you are editing) with\n`args: { "maxRounds": 8 }` and the first result\'s `runId` as `resumeFromRunId`. Rounds 1\u20136 replay\nfor zero current provider tokens and only rounds 7\u20138 run live because the cap controls call count\nbut is not interpolated into the round prompt. If every round prompt included `maxRounds`, all\neight identities would change and all would run live. Resume always states its content; a bare\n`resumeFromRunId` never silently reuses the old script.\n\n- Narrate decisions and round summaries with `log()`, and give repeated calls stable, descriptive\n  labels. MCP hosts can safely retrieve the latest log lines and compact results by label after a\n  pause or failure; useful narration turns that inspection into a diagnosis instead of a guess.\n\nWhen you run through MCP, always retain the returned `runId`. A paused, failed, or aborted response\nalready includes a redacted final-20 `logTail`; read it before changing the script. If the cause is\nstill unclear, call the same single `workflow` tool with\n`{ action: "inspect", runId, lastN, labelGlob?, logLines }`. Inspection never executes the script or\nspends tokens; a cold dead-owner row may be lease-reconciled to `paused` / `interrupted`. Use a\nnarrow label glob and latest-N tail to identify the last relevant work before deciding whether to\nresume, edit, or stop. `resumeFromRunId` executes a new run; inspection does not.\n\nEvery admitted script is also an immutable MCP resource at\n`workflow://runs/{runId}/script`. Run results link the new script; inspect/await link the complete\nresume lineage oldest-to-newest. If a later session has lost an inline script, read that URI and\nexplicitly send the retrieved text as `script` with `resumeFromRunId` (and `checkpointReplies` when\nrecovering a durable checkpoint). Resource content is the admission snapshot, never a re-read path.\n\nTo kill, patch, and resume a live run, call\n`{ action: "stop", runId, lastN?, labelGlob?, logLines? }`. The returned `aborted` snapshot is the\nauthoritative durable acknowledgement: resume is safe immediately and an additional await adds\nnothing. Edit the file, then start a new run with its absolute `scriptPath` plus\n`resumeFromRunId: runId`. The manager replays every completed call whose recorded identity and\ninput fingerprint correspond, regardless of filesystem or environment drift. Read\n`replayEligibility` and the full `resumeReport` to see correspondence decisions.\nOnly backend session wind-down can remain after stop, so inspect per-agent states only if cleanup\nappears hung. The stopped run frees its background slot immediately. A repeated stop of a terminal\nrun is a successful no-op.\n\nChoose `background: true` for work that may outlive one MCP request. The start call returns\n`{ runId, status: "running", scriptSource, scriptUri }` plus a script resource link after durable\nadmission; retain that new ID and normally collect with\n20-second bounded calls: `{ action: "await", runId, waitMs: 20000 }`. A timeout is progress, not\nfailure: it returns the newest safe status and cumulative usage, so call await again. Use\n`action:"inspect"` (or `waitMs:0`) when you need an immediate filtered diagnostic instead of waiting.\nThe background start has no enduring request channel: it returns immediately and emits no progress\nafter returning, even if that initiating request supplied a progress token. A later bounded\n`action:"await"` is a separate request; when that await carries a progress token, it can stream\ncoarse phase and distinct started/ended-call progress while pending. A legacy/inconsistent-log\npolling fallback still returns bounded status without progress notifications.\nAt terminal status await adds `outcome`, the foreground-equivalent authored result/pause context.\nThat outcome carries optional `fallbacks` and `checkpointsTaken`; inspect and the top-level await\nstatus intentionally do not. It carries `scriptUri` but not the admission-only, unpersisted\n`scriptSource`. `checkpointsTaken` identifies resolved live, headless-default,\njournal-replay, and injected `checkpointReplies` decisions without repeating prompt text.\n\nBackground is detached from the client entirely: runs execute in the shared workflow daemon, so a\nclient disconnect or shim exit does not stop in-flight work \u2014 only daemon exit (or, under\n`--in-process`, that single process exiting) can. The start request has no live checkpoint\nelicitation, so authored headless checkpoint modes apply. Resume only a paused durable journal: submit a new run with the\nscript, `resumeFromRunId`, and any `checkpointReplies`. That execution gets a new run ID and\ndurably inherits the complete replay prefix. Await and inspect never execute or resume the script;\ntheir cold preflight may only reconcile dead-owner status.\n\n## Long-running implementation workflows\n\nHard-won rules for workflows whose implement/review rounds span hours against a repository that\nkeeps moving. Each of these prevented \u2014 or would have prevented \u2014 a real terminal-verdict blocker:\n\n- **Fix where the train lives before round one.** Verify an args-supplied workroot in a preflight\n  step (expected branch, recorded base, clean tree \u2014 refuse on mismatch) or have a setup call create\n  a persistent sibling worktree idempotently; never commit onto whatever the run cwd happens to have\n  checked out. The execution-environment section spells out both patterns.\n- **Pin a base and check it every round.** A brief that says "based on origin/main" names a moving\n  target. Have the implementer record the exact base SHA it built against (e.g. into a gitignored\n  `base-sha.txt`), and make every reviewer compare `git ls-remote origin refs/heads/<default>`\n  against it as a structured verdict field (`ls-remote` reads the remote without mutating the shared\n  checkout; reserve `git fetch` for throwaway worktrees). Reviewers grounded in a stale worktree will confidently\n  "verify" claims against the wrong tree \u2014 in one run, fourteen of fifteen agents (including the\n  final adjudicator\'s first pass) validated against a base nine commits behind, and the decisive\n  blocker was visible only to the single reviewer that fetched. At least one gate lens should\n  build/test against the LIVE default branch, where upstream drift surfaces as a compile failure\n  instead of an opinion.\n- **A missing cited mechanism means stop, never re-implement.** If the spec cites an engine field or\n  API that does not exist on the implementer\'s tree, the correct move is to halt and report the\n  discrepancy \u2014 the overwhelmingly likely cause is a stale base, not a wrong spec. The plausible\n  fallback ("build the equivalent at my own layer") produces a parallel implementation that collides\n  with the real mechanism on rebase. Put that instruction in the implementer\'s prompt verbatim.\n- **Reconcile contradictory reviewer directives before obeying either.** With multiple independent\n  lenses across rounds, one reviewer can demand a subsystem that another later demands removed. The\n  implementer will obey whichever spoke last; the conflict then lands unresolved on the terminal\n  adjudicator. When a round\'s feedback contradicts an earlier round\'s, the workflow owner (or an\n  explicit adjudication step) decides \u2014 not the implementer.\n- **Never hand the adjudicator unaddressed final-round blockers.** A gate capped at N rounds ends\n  with round N\'s findings unfixed by construction. Budget one bounded post-gate fix pass (judged by\n  the terminal adjudicator directly, no re-review) or run the adjudicator before the final round.\n- **The report and HEAD must be the same commit.** An implementer that keeps committing after filing\n  its structured report makes the review target a moving object \u2014 reviewers certify a branch state\n  that no longer exists. Require the report\'s SHAs to be the branch tip, and treat post-report\n  commits as a blocking process violation. Enforce it with values, not prose: the producer schema\n  carries a full 40-character `headSha` that script code checks equals the last reported commit,\n  each reviewer schema carries the `reviewedHeadSha` it actually inspected, and script code compares\n  the two \u2014 an attested boolean ("I reviewed the right commit") is worthless next to an SHA equality\n  check that costs nothing.\n- **Verify the brief\'s own premises against the live tree.** A brief assertion about engine behavior\n  ("seeds persist on every resumed run") that is false at HEAD forces the implementer into\n  ungrounded redesigns mid-flight. Cited behaviors deserve the same file:line grounding the spec\n  gets.\n- **Design artifacts live OUTSIDE the worktree and survive it.** Briefs, review files, base pins, and adjudication reports go in a design directory beside (never inside) the worktree \u2014 a mid-run reset or worktree removal must not destroy the record the adjudicator needs. The persisted run state, not your scratchpad copy, is the replay-identity ground truth for the script itself.\n- **Re-verify external pins with fresh clones, every round.** A dependency pinned at authoring time can be superseded mid-train (fast-moving upstreams release daily). Reviewers fetch a FRESH temp clone and confirm the pin still equals the upstream\'s current release; the spec carries an implementation-time re-verification clause obligating the implementer to repeat the check and STOP on drift. A pinned checkout that was fresh yesterday is a stale checkout today.\n- **No uninvited resource caps.** A structurally bounded workflow (fixed rounds \xD7 fixed fan-out +\n  one adjudication) cannot run away; a token budget adds no protection but adds a new failure mode \u2014\n  the mid-flight kill that wastes live work. Add caps only when the structure itself is unbounded,\n  sized from per-role estimates (one xhigh implement + one four-reviewer verify round with full test\n  suites \u2248 3M tokens).\n- **Bound every potentially stalled agent deliberately.** Use a run-level `agentTimeoutMs` as the\n  total wall-clock ceiling for each attempt, and use a smaller per-call `timeoutMs` only where a\n  step deserves a tighter deadline. Each retry re-arms the clock. At the concurrency cap, one slow\n  `parallel()` branch occupies one slot while other finished branches release theirs; an exhausted\n  timeout settles that branch to `null` and frees its slot for queued work. For a live outlier that\n  should stop without tearing down completed siblings, inspect its deterministic index and send\n  `{ action: "stop", runId, callIndex }`; host cancellation also settles `null`, frees the slot, and\n  deliberately skips retries.\n\n## Worked example \u2014 cross-vendor build with every major primitive\n\n```js\nexport const meta = {\n  name: "feature-build",\n  description: "Plan, gate on approval, implement, cross-vendor review, fix until green",\n  phases: [{ title: "Plan" }, { title: "Implement" }, { title: "Review" }],\n};\n\nconst PLAN = { type: "object", additionalProperties: false, required: ["steps", "risks"],\n  properties: {\n    steps: { type: "array", items: { type: "string", description: "One concrete implementation step" } },\n    risks: { type: "array", items: { type: "string" } } } };\nconst VERDICT = { type: "object", additionalProperties: false, required: ["ok"],\n  properties: { ok: { type: "boolean" },\n                feedback: { type: "string", description: "Required when ok=false: concretely what to change" } } };\n\nphase("Plan");\nconst plan = await agent(\n  `Study this repo, then write an implementation plan for: ${args.feature}. Keep steps concrete.`,\n  { label: "plan", model: "opencode/zai/glm-5.2", schema: PLAN },\n);\n\nconst approved = await checkpoint(\n  `Implement "${args.feature}" with this plan?\\n- ${plan.steps.join("\\n- ")}\\nRisks: ${plan.risks.join("; ")}`,\n  { kind: "confirm", default: true },\n);\nif (!approved) return { implemented: false, plan };\n\nphase("Implement");\nconst outcome = await gate(\n  (feedback, attempt) => agent(\n    `Implement: ${args.feature}\\nPlan:\\n- ${plan.steps.join("\\n- ")}\\n` +\n    `Run the project\'s tests before finishing and report results.` +\n    (feedback ? `\\n\\nReviewer feedback on attempt ${attempt}:\\n${feedback}\\nAddress every point.` : ""),\n    { label: `implement:${attempt + 1}`, model: "codex/gpt-5.6-sol", retries: 1 },\n  ),\n  async (report) => {\n    if (!report) return { ok: false, feedback: "implementation agent produced no result" };\n    phase("Review");\n    const reviews = (await parallel([   // two vendors, two lenses \u2014 independent eyes\n      () => agent(`Review the working-tree diff for correctness. Implementer\'s report:\\n${report}`,\n                  { label: "review:correctness", model: "claude/opus[1m]", schema: VERDICT }),\n      () => agent(`Review the working-tree diff for regressions and missing tests. Report:\\n${report}`,\n                  { label: "review:coverage", model: "opencode/zai/glm-5.2", schema: VERDICT }),\n    ])).filter(Boolean);\n    const rejections = reviews.filter((r) => !r.ok);\n    return rejections.length\n      ? { ok: false, feedback: rejections.map((r) => r.feedback).join("\\n"), reviews }\n      : { ok: true, reviews };\n  },\n  { attempts: 3 },\n);\n\nreturn { implemented: outcome.ok, attempts: outcome.attempts, reviewVerdict: outcome.verdict, plan };\n```\n\n(The planner would ideally run read-only, but mode ids are backend-specific \u2014 this call routes to OpenCode, so it leaves `mode` unset rather than guessing; a Claude-routed planner could safely say `mode: "plan"`.)\n\n## Worked example \u2014 fully backend-agnostic audit\n\nNo `model` anywhere: this script runs unchanged on whatever backend the host defaults to.\n\n```js\nexport const meta = {\n  name: "edge-case-audit",\n  description: "Exhaustively hunt edge-case bugs in a target dir, verify each, report gaps",\n  phases: [{ title: "Hunt" }, { title: "Verify" }],\n};\n\nconst BUGS = { type: "object", additionalProperties: false, required: ["bugs"],\n  properties: { bugs: { type: "array", items: { type: "object", additionalProperties: false,\n    required: ["file", "scenario"], properties: {\n      file: { type: "string", description: "Repo-relative path you actually opened" },\n      scenario: { type: "string", description: "Concrete input/state \u2192 wrong behavior" } } } } } };\n\nphase("Hunt");\nconst seen = [];   // what earlier rounds reported, threaded into each new prompt\nconst candidates = await loopUntilDry({\n  round: async (i) => {\n    const r = await agent(\n      `Round ${i + 1}: find edge-case bugs in ${args.target} not already in this list:\\n` +\n      JSON.stringify(seen) + `\\nOnly report what you can ground in code you read.`,\n      { label: `hunt:${i + 1}`, schema: BUGS },\n    );\n    const bugs = r ? r.bugs : [];\n    seen.push(...bugs);\n    return bugs;      // loopUntilDry dedups these by `key` across rounds\n  },\n  key: (b) => `${b.file}:${b.scenario}`,\n  consecutiveEmpty: 2,\n  maxRounds: 8,\n});\n\nphase("Verify");\nconst confirmed = (await pipeline(\n  candidates,\n  (bug) => verify(bug, { reviewers: 3, threshold: 0.66, lens: ["correctness", "reproducibility"] }),\n  (v, bug) => (v.real ? bug : null),\n)).filter(Boolean);\n\nconst gaps = await completenessCheck(args, confirmed);\nlog(`${confirmed.length}/${candidates.length} confirmed; complete=${gaps.complete}`);\nreturn { confirmed, missing: gaps.missing ?? [] };\n```\n\n## Full-scale example scripts\n\nWhen the inline examples above aren\'t enough, study the complete, validated scripts that ship with the published authoring skill:\n\n- [`repo-triage.workflow.js`](https://github.com/VikashLoomba/agentprism-workflows/blob/main/skills/agentprism-workflow-authoring/examples/repo-triage.workflow.js) \u2014 an autonomous, unattended cross-vendor repo triage and the broadest support-API tour: `pipeline` with no inter-stage barrier, a cross-vendor adversarial verification panel, `gate()` where writer and reviewer are always different vendors, nesting a saved workflow by name, `completenessCheck()`, budget headroom reservation, string-form `args` hardening, placeholder/path guards on schema outputs, and pause-class error rethrow.\n- [`implementation-train.workflow.js`](https://github.com/VikashLoomba/agentprism-workflows/blob/main/skills/agentprism-workflow-authoring/examples/implementation-train.workflow.js) \u2014 the battle pattern for shipping real work against a frozen contract: a lens-gated implement loop (produce \u2192 four falsifiable-question reviewers \u2192 self-contained combined feedback) with STOP-and-report recognized in the checker, script-side report validation before any reviewer spends tokens, base-freshness re-anchoring every round, and a terminal adjudicator whose closed finding list feeds a panel-free fix round.\n- `quick-wins.workflow.js` (included in full at the end of this document) \u2014 a small hunter that runs standalone *or* nested: `loopUntilDry()` with per-round vendor rotation, dedup threading via a `seen` list, and an in-round budget floor (nested runs share the parent\'s budget).\n\n[`examples/README.md`](https://github.com/VikashLoomba/agentprism-workflows/blob/main/skills/agentprism-workflow-authoring/examples/README.md) maps each script to what it teaches.\n\n## Validate before you run\n\nThe SDK ships a validator that costs **zero tokens** \u2014 always run it on a script you just wrote or edited:\n\n```bash\nnpx @automatalabs/workflows validate my-workflow.js --args \'{"target":"src/"}\'\n```\n\nIt does three passes: a **static parse** (the `meta` literal, syntax, and direct nondeterministic call expressions), a **dry run** \u2014 the script executes for real in the engine\'s realm, but every `agent()` call is served by a mock backend that fabricates schema-conforming results \u2014 then one no-prompt session for each distinct routed `{ backend, model }` pair. The last pass spends no tokens, selects each authored call model, and surfaces the echoed model-specific config-options table in the human and JSON reports every time. Read that table before picking `configOptions` values. Unknown ids, bad select values, non-boolean boolean values, and the reserved `"model"` key fail validation with the call label, authored value, and alternatives. Self-advertised recognized domains win; otherwise Claude and Codex enumerate at most 32 picker-visible models and merge consistent effort orders for ordered clamping. Pi already advertises its domain. OpenCode and custom/unknown backends are exact-set, and enumeration that is too large or inconsistent warns and exact-rejects unadvertised values. Claude effort absence remains model-specific and `default` is not an ordered ceiling. If a routed pair cannot spawn, authenticate, select its model, or open a session, validation emits one warning, marks it `probed:false`, skips only its checks, and stays valid; this is the offline degradation behavior. A mock live confirm answers checkpoints with `default ?? true`, so `headless: "pause"` dry-runs cleanly; `headless: "abort"` still warns because a truly unattended run would abort. Script-declared `meta.backends` are treated as approved, and the report lists every call with its backend attribution plus warnings (undeclared phases, `headless: "abort"` checkpoints, zero agent calls).\n\nThe default fabricator returns `true` for every boolean. Do not accept that all-true path as proof\nthat a convergence loop works: script its control labels with `--mock-answers` or a reusable\n`--mock-answers-file`. Use a finite `$sequence` such as reject-then-approve so validation executes\nthe revision branch and proves the loop stops; the report identifies every consumed and unused\nfixture without printing answer bodies.\n\nShip the fixtures with the script. Save the mock-answers JSON beside the workflow file\n(`<name>.mock.json`) and treat the pair as the deliverable: the deep paths it proves \u2014 fix rounds,\nSTOP branches, post-adjudication repairs \u2014 are exactly the paths a later edit (or a\nkill-patch-resume) breaks silently, and an unmocked dry run stops at the first guard. When a\ndefault-fabrication dry run leaves declared phases unexecuted, that usually means your guard\nbranches fired \u2014 script the mocks that reach past them instead of shrugging at the warnings.\n\nExit codes: `0` valid \xB7 `1` parse failure \xB7 `2` dry-run or config-option failure. Useful flags: `--parse-only`, `--token-budget <n>` (exercises `budget`-guarded paths; the mock reports 1000 tokens per call), `--args-file <path>`, `--json` (machine-readable report). Hosts can do the same programmatically via `validateWorkflowScript(script, opts)` from `@automatalabs/workflows`.\n\nThe third pass\'s table is also available standalone \u2014 before any script exists \u2014 as validate\'s sibling command: `npx @automatalabs/workflows config [harness ...]` (default: every routable harness; `--json`; exit `1` when a probe fails). Use `config` while authoring to pick values; validate\'s copy then confirms the script you wrote against the same live catalog.\n\nIf the script nests saved workflows by name (`workflow("review-pr")`), pass the folder so names resolve \u2014 and the positional itself may then be a name: `npx @automatalabs/workflows validate review-pr --workflows-dir ./workflows`. A green dry run proves structure, not judgment \u2014 prompts and schemas still deserve review.\n\n---\n\n# Workflow script reference\n\nExhaustive tables for the AgentPrism workflow script DSL. The guide above covers authoring; this section is the lookup companion. Everything here is verified against `@automatalabs/workflow-engine` / `@automatalabs/acp-agents` as shipped with `@automatalabs/workflows`.\n\n## The `meta` header\n\n`export const meta = {...}` must be the script\'s first statement and a pure object literal (it is parsed from source text before execution).\n\n| field | required | meaning |\n|---|---|---|\n| `name` | yes | Stable identifier for the workflow (journals, logs, traces). |\n| `description` | yes | One line: what the workflow does. |\n| `phases` | no | `[{ title, detail?, model? }]` \u2014 declare one entry per `phase()` call (matched by exact title). A phase `model` is the default for agents assigned to that phase. |\n| `model` | no | Run-wide default model for agents with no `model`/`tier` whose phase has no `model`. |\n| `backends` | no | Script-declared custom ACP backends, keyed by routing name \u2014 see [Custom backends](#custom-backends-metabackends). Inert until the host approves them. |\n\nPer-agent model precedence: `agent({ model })` > `agent({ tier })` > current phase `model` > `meta.model` > host session default.\n\n## `agent(prompt, options?)` \u2014 full option table\n\nReturns the agent\'s final assistant text, or the schema-validated object when `schema` is set. Resolves to `null` when a *recoverable* failure survives all retries.\n\n| option | type | meaning |\n|---|---|---|\n| `label` | `string` | Display/telemetry name; also stamped on every live ACP event for this call. Always set it. Not part of the resume hash. |\n| `phase` | `string` | Assign this call to a phase explicitly (needed inside concurrent stages where the global `phase()` state would race). |\n| `schema` | JSON Schema object | Structured output. Plain object literal only \u2014 no schema builders exist in the realm. Part of the resume hash. |\n| `model` | `string` | Model spec: optional registered harness prefix plus a verbatim id, or a backend-only name. See [Model specs & routing](#model-specs--routing). Part of the resume hash. |\n| `tier` | `"small" \\| "medium" \\| "big"` | Coarse tier resolved from host config; beats phase/meta model, loses to explicit `model`. Part of the resume hash. |\n| `mode` | `string` | ACP session mode id advertised by the selected backend. **Strict**: unsupported/unadvertised ids fail the call (never silently unconfined). Claude-family: `default`, `plan`, `acceptEdits`, `bypassPermissions`. Codex-family: `read-only`, `agent`, `agent-full-access`. OpenCode: its mode config option. Part of the resume hash when set. |\n| `configOptions` | `Record<string, string \\| boolean>` | Exact ACP session option ids and authored values. Applied in ascending id order after model and before the prompt, with no aliases or coercion. `"model"` is reserved for the dedicated `model` field. Part of the resume hash only when non-empty, with sorted keys. Read the advertised-options table first (`agentprism-workflows config <harness>`, or any validate report) before choosing values. |\n| `agentType` | `string` | Bind a named subagent definition (tools allow/deny, model, isolation, role prompt). See [agentType definitions](#agenttype-definitions). Part of the resume hash. |\n| `isolation` | `"worktree"` | Run in a throwaway git worktree branched from the run cwd. **Always removed (worktree + branch) when the call ends** \u2014 edits are discarded; return work as data. Degrades to the shared tree outside a git repo (logged). |\n| `resume` | `{ filesystem: "read-only" }` | Deprecated compatibility annotation. It is recorded as legacy diagnostic provenance, is not sent to the runner or hashed, and has no effect on replay. New scripts should omit it. |\n| `cwd` | `string` | Per-session working directory; relative resolves against the run\'s base cwd. Overridden by worktree isolation. Not hashed. |\n| `timeoutMs` | `number \\| null` | Total wall-clock cap for each attempt. A finite value may tighten a finite host `agentTimeoutMs` ceiling but cannot raise or disable it. With no host ceiling, a finite value applies and `null`/omitted is uncapped. |\n| `retries` | `number` | Retries after *recoverable* failures (default 0, host-overridable). Exhausted retries \u21D2 the call resolves `null`. |\n| `mcpServers` | `McpServerConfig[]` | MCP servers attached to this session. Stdio shape: `{ name, command, args: [], env: [{ name, value }] }` (`args`/`env` required, `env` is name/value pairs, not a map); `{ type: "http" \\| "sse", name, url, headers: [] }` also accepted. Not hashed. |\n| `images` | `PromptImage[]` | Base64 image blocks appended to the prompt; backends without image support get a bracketed text note. Not hashed. |\n| `meta` | `object` | ACP `_meta` merged into `session/new` \u2014 session-scoped extension passthrough (pairs with custom backends). Not hashed. |\n| `promptMeta` | `object` | ACP `_meta` merged into `session/prompt` \u2014 turn-scoped passthrough. Backend-computed keys win on conflict. Not hashed. |\n| `keepSession` | `boolean` | Skip release-time best-effort `session/close`; the non-secret re-attach record lands in `WorkflowRunResult.agentSessions` for host-side `loadSession()` / `resumeSession()`. Usage/auth pause failures are kept open automatically for managed continuation. Not identity-hashed; included in the input fingerprint. |\n\nThe timeout clock measures the whole attempt, including backend startup, model/config setup, tool\nwork, and streamed output; it is not an idle timer. Each retry starts a fresh clock, so the maximum\ntimeout envelope is `(retries + 1) \xD7 resolved timeoutMs` (retries are clamped to 3). An exhausted\ntimeout is recoverable `AGENT_TIMEOUT`: the call resolves to `null`, releases its concurrency slot,\nand asks the ACP session to cancel. A session that keeps running after the cancellation grace is\nclosed where supported and its pooled child is recycled.\n\nEvery new run, including one admitted with `resumeFromRunId`, resolves host limits from that run\'s\nrequest. It does not inherit `agentTimeoutMs`, retries, concurrency, agent-count, or token-budget\nvalues from its source, so pass every operational bound the resumed execution should use.\n\n## Model specs & routing\n\nA `model` string is resolved solely from its first segment, then delegated to the harness:\n\n| spec shape | routes to | notes |\n|---|---|---|\n| *(omitted)* | host default backend | `AGENTPRISM_DEFAULT_BACKEND` (`claude` \\| `codex` \\| `opencode` \\| `pi` \\| custom name; default `claude`), session default model. Most portable. |\n| `claude`, `codex`, `opencode`, `pi`, or `<custom-name>` | that registered harness | Backend-only: no model config call; the harness default remains active. |\n| `claude/<id>`, `codex/<id>`, `opencode/<id>`, `pi/<id>`, or `<custom-name>/<id>` | that registered harness | Match the first segment ASCII-case-insensitively and strip exactly one segment. Custom names take priority on collision. The remaining `<id>` is sent verbatim, including further `/` characters. For Pi, that remainder is its `<provider>/<model-id>` and Pi preserves any further slashes in the model id. |\n| any other string, including `anthropic/\u2026`, `openai/\u2026`, bare `opus`, or bare `gpt-\u2026` | host default backend | The **entire** authored string is sent verbatim; these are not routing aliases. |\n\nSelection is a single `session/set_config_option` with `configId: "model"` and the exact remaining string. There is no catalog matching, case folding, normalization, bracket parsing, nearest-neighbor selection, sibling effort/Fast option driving, retry, or echo verification. Brackets, dots, and provider-style prefixes are ordinary model-id characters. Live-catalog-verified examples are `claude/opus[1m]`, `codex/gpt-5.6-sol`, and `opencode/zai/glm-5.2`; prefer backend-only forms for harness-configured models.\n\nWhatever the harness returns is the outcome. A rejection follows the existing agent-error path with no resolution-specific code or model fallback event. `onModelFallback` and `WorkflowRunResult.fallbacks` remain public compatibility surfaces; model resolution does not emit entries, while pause recovery emits `kind: "continuation"` reattach/skip notices.\n\n### Session config options\n\n`configOptions` extends the model rule to any other ACP session knob the routed harness advertises:\n\n```js\nawait agent("Implement the approved change.", {\n  label: "implement",\n  model: "codex",\n  configOptions: { "fast-mode": true, reasoning_effort: "high" },\n});\n```\n\nIds and values are verbatim: strings stay strings, booleans stay booleans, and the client has no\naliases, vocabulary, defaults, coercion, or catalog fallback. Entries are sent in ascending\noption-id order after model selection and before the prompt. A harness rejection follows the\nordinary agent-error path. Never put `"model"` in this bag; the engine rejects it before opening a\nsession. The catalog varies by harness version, login, and machine, so read a live advertised\nconfig-options table \u2014 `agentprism-workflows config <harness>`, or any validate report \u2014 before\npicking an id or select value, and run the validator every time after authoring. Ids are copied\ncharacter-for-character, punctuation included (`"fast-mode"`, not `fast_mode`). The bare `config`\nprobe reads each harness with its default model selected; option ids, domains, and ceilings are\nmodel-specific, and provider-served variants of the same model can advertise different domains \u2014\nvalidate\'s per-pair echo, which selects your authored model first, is the authoritative per-model\nprobe.\n\nFor Pi, use `thinkingLevel` only with an explicit Pi model when the level matters. Validation\nselects that call\'s model before reading the option: listed values pass unchanged, recognized but\nunsupported ordered values warn with the effective clamp, and unrecognized values fail with exit\n`2`. Pi advertises its domain directly. Claude and Codex derive missing domains by enumerating up to\n32 advertised models and consistently merging their effort orders; Claude does not borrow `effort`\nfor a model that omits the option, and its `default` sentinel is outside clamp ordering. OpenCode and\ncustom/unknown backends are exact-set, so every unadvertised thought-level value fails instead of\nclamping. A too-large or inconsistent ordered catalog warns and takes that same exact path.\n\n## Structured output channels\n\nOne author API (`schema`), four fulfillment paths \u2014 chosen automatically per backend:\n\n| backend | channel |\n|---|---|\n| Claude | native `outputFormat`, schema normalized to Anthropic\'s structured-outputs subset (e.g. `oneOf` \u2192 `anyOf`; unsupported keywords/formats stripped on the wire) |\n| Codex | native strict `outputSchema` (OpenAI strict subset normalization) |\n| Pi | a client-hosted `StructuredOutput` MCP tool injected when the agent advertises HTTP MCP support; common prompt-embedded schema and validated final-text JSON fallback |\n| OpenCode / custom ACP | a client-hosted **`StructuredOutput` MCP tool** injected into the session when the agent advertises HTTP MCP support (an agent may show it as `structured_output_StructuredOutput`); otherwise prompt-embedded schema + JSON parse of the final message. Custom backends can opt out of tool injection with `structuredOutputTool: false`. |\n\nPi accepts stdio, Streamable HTTP, and SSE MCP servers; ACP-transport MCP hosting remains client-side.\n\nIn every channel the runner coerces + validates client-side and re-prompts a bounded number of times; the final miss fails the call with non-recoverable `SCHEMA_NONCOMPLIANCE`. Constraints stripped from the wire are still enforced client-side \u2014 an exotic schema keyword shows up as re-prompt churn, so keep schemas simple.\n\n## DSL globals \u2014 complete signatures\n\n```\nagent(prompt, options?)                    \u2192 Promise<string | object | null>\nparallel(thunks)                           \u2192 Promise<results[]>   // barrier; input order; failed slot = null\npipeline(items, ...stages)                 \u2192 Promise<results[]>   // no inter-stage barrier; stage(prev, original, index); failed item = null\nworkflow(nameOrScript, args?)              \u2192 Promise<unknown>     // one nesting level; names resolve from the host\'s workflows folder, inline scripts always work\ngate(thunk, validator, { attempts = 3 })   \u2192 { ok, value, verdict, attempts }\n    // thunk(feedback, attempt); validator(result) \u2192 { ok, feedback?, ... } | boolean | null (may be async / an agent call)\nretry(thunk, { attempts = 3, until? })     \u2192 last result           // thunk(attempt); stops early when until(result)\nverify(item, { reviewers = 2, threshold = 0.5, lens? })\n    \u2192 { real, realCount, total, votes: [{ real?, reason? }] }\n    // N adversarial reviewers prompted to REFUTE; lens (string | string[]) rotates focus per reviewer\njudgePanel(attempts, { judges = 3, rubric = "overall quality and correctness" })\n    \u2192 { index, attempt, score, judgments }  // mean 0\u20131 score per candidate; stable tie-break by index\nloopUntilDry({ round, key = JSON.stringify, consecutiveEmpty = 2, maxRounds = 50 })\n    \u2192 unique items[]   // round(i) returns items; stops after N dry rounds; budget exhaustion returns the partial result\ncompletenessCheck(taskArgs, results)       \u2192 { complete, missing?: string[] }\ncheckpoint(promptText, options?)           \u2192 Promise<reply>       // journaled human gate; zero tokens\nphase(title, { budget? })                  \u2192 void                 // soft per-phase token sub-budget\nlog(message)                               \u2192 void                 // console.log/info/warn/error route here too\nargs                                       // the host-provided input value, verbatim\ncwd                                        // the run\'s base working directory (string); process.cwd() returns it too\nbudget.total | budget.spent() | budget.remaining()\n```\n\nFor `gate()`, `value` is the final producer result and `verdict` is the exact last completed\nvalidator return, including any extra structured fields. `{ ok: true }` and bare `true` pass;\n`{ ok: false, feedback? }`, bare `false`, and `null` reject. Only object feedback is threaded into\nthe next producer attempt. A producer result of `null` is still passed to the validator. Producer\nor validator exceptions propagate immediately, so no partial gate result is returned and no later\nattempt runs. An explicit unsupported `undefined` validator return is a rejection represented as\n`verdict: null`. If the script returns the gate result, its complete verdict is persisted and may\nreach the host; keep evidence concise and never put credentials or other secrets in verdict data.\n\n`verify`, `judgePanel`, and `completenessCheck` spawn their subagents on the run\'s default model \u2014 hand-roll with `parallel` + `agent` to pin panel members to specific backends.\n\n## `checkpoint()` options\n\n| option | type | meaning |\n|---|---|---|\n| `kind` | `"confirm" \\| "input" \\| "select"` | Reply shape: boolean-ish / free text / one of `choices`. Affects the journal hash and the host UI widget. |\n| `choices` | `string[]` | For `kind: "select"`. |\n| `default` | `unknown` | Reply taken in the default headless mode \u2014 journaled like a real reply. Defaults to `true`. |\n| `headless` | `"default" \\| "abort" \\| "pause"` | No live channel: `"default"` takes `default ?? true`, `"abort"` aborts, and `"pause"` creates a persisted `checkpoint_required` pause. Default `"default"`. |\n| `timeoutMs` | `number` | Deadline for the interactive prompt. |\n\nThe host supplies the live human channel (elicitation in the MCP server; `ExecOptions.confirm` in the SDK), and that channel wins even when `headless: "pause"` is declared. A durable pause carries non-secret `checkpointContext`; resume with `ExecOptions.checkpointReplies: { [context.callIndex]: decision }` or attach a live channel. On a new `resumeFromRunId` execution, reply keys always name indexes in the **source** recording; identity matching may inject that decision at a shifted current index. Completed host and headless checkpoint results both replay when identity and the checkpoint-options fingerprint over `default`, `headless`, and `timeoutMs` match. A changed option or ambiguous match runs fresh. Detached runs never pause for a checkpoint unless the author opts into `"pause"`.\n\n## Error codes (`WorkflowError.code`)\n\n| code | recoverable | engine behavior |\n|---|---|---|\n| `AGENT_TIMEOUT` | yes | Total wall-clock attempt cap exhausted. Every retry gets a fresh clock; after the final attempt the call resolves `null`, and ACP cancel escalates to close/recycle when the turn does not stop. |\n| `AGENT_CANCELLED` | yes | The host selected this in-flight call for cancellation. It resolves `null` immediately through an engine race, skips retries, leaves the run live, and is recorded as a failed call rather than a replayable journal result. |\n| `AGENT_EMPTY_OUTPUT` | yes | No assistant text on a schema-less call; same retry-then-`null`. |\n| `AGENT_EXECUTION_ERROR` | yes* | Generic agent failure (*refusal/truncation variants are non-recoverable). |\n| `SCHEMA_NONCOMPLIANCE` | no | Structured output never validated after the re-prompt ladder. Halts the run (catchable in-script). |\n| `PROVIDER_USAGE_LIMIT` | no | Quota/rate wall \u2014 the run **pauses** (journaled, resumable), with the provider\'s reset hint. |\n| `TOKEN_BUDGET_EXHAUSTED` | no | Run (or phase) token cap hit; further `agent()` calls throw. |\n| `AGENT_LIMIT_EXCEEDED` | no | `maxAgents` cap hit. |\n| `AUTH_REQUIRED` | no | Backend needs authentication. `WorkflowManager` returns a resumable pause with `reason: "auth_required"` and redacted `authContext`; a direct runner throws. The host completes auth before resuming/retrying. |\n| `CHECKPOINT_REQUIRED` | no | `headless: "pause"` reached without a live channel. `WorkflowManager` returns `reason: "checkpoint_required"` plus non-secret `checkpointContext`; resume with `checkpointReplies` or live confirm. |\n| `SCRIPT_VALIDATION_ERROR` | no | Script failed parse/validation (bad meta, nondeterministic API, bad `meta.backends` shape). |\n| `SCRIPT_ERROR` | no | The script itself crashed (uncaught throw, floated rejection). |\n| `WORKFLOW_ABORTED` | \u2014 | Real cancellation (pause/stop/host signal) \u2014 never used for crashes. |\n\n`loopUntilDry` absorbs `TOKEN_BUDGET_EXHAUSTED` / `AGENT_LIMIT_EXCEEDED` from its rounds and returns the partial result; everywhere else those propagate.\n\n## Determinism & the resume journal\n\n> **Resume rule:** replay is content-addressed and fail-to-live on correspondence: a completed call replays when its identity and input fingerprint match uniquely. Filesystem or world state never gates replay.\n\n- Direct calls that break deterministic replay fail static validation: `Date.now()`, `Math.random()`, and no-arg `new Date()` / `Date()`. The realm also blocks aliased or computed forms at runtime. `new Date(value)` works. There is no `require`, `import`, Node API, or network API in the realm.\n- Each `agent()` result is journaled under a monotonic call index and a SHA-256 identity hash. The canonical identity fields, in order, are `prompt`, resolved `model`, `mode` only when set, `configOptions` only when non-empty, `tier`, `phase`, `agentType`, resolved `agentDef`, and `schema`. Config-option keys are sorted before serialization. Missing fields other than `mode` and `configOptions` serialize as `null`; an unset `mode` and an unset/empty `configOptions` key are omitted for compatibility with older journals.\n- `agentDef` is the resolved definition\'s tools, disallowed tools, model, isolation, and body prompt. Changing a named definition therefore invalidates its call even when the `agentType` name is unchanged.\n- The separate input fingerprint contains resolved label, per-call `cwd`, resolved isolation, `keepSession`, `images`, `mcpServers`, `meta`, `promptMeta`, and the approved script-backend digest. Host `agentTimeoutMs`, `agentRetries`, and `concurrency`, plus per-call `timeoutMs` and `retries`, are operational bounds in neither hash; a resume may change them without invalidating completed work or interrupted-turn continuation.\n- `args` is exposed to the script but is not directly included in the call hash. An args change misses only when evaluating the script produces a changed hashed field, changed call order, new call, or changed runner-visible input fingerprint.\n- The legacy `resume: { filesystem: "read-only" }` annotation has no effect on admission or matching. Writers, readers, worktree calls, and unannotated calls follow the same journal rule.\n- Automatic new-format matching first tries one exact `(kind, call path, identity hash)` candidate (`"path-hash"`), then one unique `(kind, identity hash, input fingerprint)` candidate so an unchanged call may replay as `"unique-hash"` across inserted/deleted siblings. The source and current input fingerprints must be equal. Duplicate exact identities, duplicate content, consumed candidates, missing facts, or an empty schema-less result run live; no occurrence or source-order guess is made.\n- A source is admitted only after exact cwd, compatible call-path/input/checkpoint formats, complete call/journal/allocation metadata, and valid manifest/seed checks. Git HEAD/dirty digest, `environmentKey`, captured start/terminal environment values, current Node/V8, and engine version are diagnostics only. Provenance compares the recorded terminal environment (or start environment when no terminal capture exists) with the current environment; reported differences never gate replay.\n- Live agents, nested workflows, host checkpoint callbacks, and worktree degradation do not close the identity cache. Nested child calls are not in the parent journal and therefore run live, while matching parent calls around them remain replayable. Replayed calls do not recreate file writes; a later live agent navigates the world it actually finds.\n- Identity hits add their preserved logical budget debit to `budget.spent()`/`remaining()` so budget-driven control flow stays stable, while current `tokenUsage` and provider cost remain zero. Replayed session records are rebound to the current call index/label/phase without opening a session.\n- A root call interrupted by `PROVIDER_USAGE_LIMIT` / `AUTH_REQUIRED` may continue its recorded session on either resume API. Continuation is index-local and independent of replay strategy. It requires matching identity and input fingerprints, a non-worktree call, equal existing cwd, a coherent reopenable session row, and matching runner backend/`poolKey`; current capabilities choose resume before load. Every rejection fails to a fresh call and appears in `fallbacks`, while successful continuation journals its reopen method and charges only continuation-turn usage.\n- Completed `checkpoint()` results require equal fingerprints of `default`, `headless`, and `timeoutMs` and replay whether they came from a host or headless default. `checkpointReplies` keys refer to source indexes; a moved reply follows intact prior correspondence, while a different same-text branch after a live divergence cannot consume it.\n- `resumePolicy: "positional"` is the migration escape hatch: it requests index/prefix correspondence but cannot bypass new-format format, metadata, manifest, cwd, or input checks. It requires no safety annotation. Marker-less journals and permanently marked manual/same-run legacy resumes retain historical hash-only positional behavior. Current-format reconciled `paused` / `interrupted` snapshots with valid manifests use identity matching even without terminal-environment capture; sources below input format 2 use `inputs-format-legacy`. Ancestor-scoped rows carried by a \u22640.23 resume hop replay only while that ancestor is still persisted, and nested/deleted scopes stay live.\n- The additive options `label`, `cwd`, `mcpServers`, `images`, `meta`, `promptMeta`, and `keepSession` are not identity-hashed. A changed value does not invalidate an ordinary replayed result, but it changes the input fingerprint and therefore rejects continuation of an interrupted turn.\n\nEvery new-run resume exposes `replayEligibility` on admission, polling, inspection, and the terminal result. It reports strategy, predicted/observed replayable prefix and counts, first non-replay/reason/detail, engine/input-format diagnostics, non-gating runtime/environment `provenanceChanges`, and non-gating operational changes; `resumeReport` retains the complete terminal per-call correspondence.\n\nAn all-live outcome is expected when correspondence cannot be established, not when the world changed. Missing resume metadata, incompatible format literals, or an invalid manifest/seed can disable reuse. A new-format source containing any result row without a captured call path/input fact\u2014possible with a call stack deeper than the raw-frame cap or a non-strict-JSON `meta` value\u2014is source-wide `"manifest-invalid"`; excluding the row could make an ambiguous sibling look unique. Format-1 bytes are never reinterpreted; they enter the positional bridge and replayed rows are recorded under format 2.\n\nAn args-controlled cap is the useful case. In this complete script, `maxRounds` changes how many calls are reachable but does not appear in an earlier call\'s prompt:\n\n```js\nexport const meta = {\n  name: "resume-loop-cap",\n  description: "Run expensive review rounds up to an args-controlled cap",\n  phases: [{ title: "Review" }],\n};\n\nconst input = args && typeof args === "object" && !Array.isArray(args) ? args : {};\nconst numericCap = Number(input.maxRounds);\nconst maxRounds = Number.isInteger(numericCap) && numericCap > 0 ? numericCap : 8;\n\nphase("Review");\nconst rounds = [];\nfor (let i = 0; i < maxRounds; i += 1) {\n  rounds.push(\n    await agent(\n      `Review round ${i + 1}: inspect the repository and report unresolved release blockers.`,\n      { label: `review:${i + 1}`, phase: "Review" },\n    ),\n  );\n}\n\nif (maxRounds < 8) throw new Error(`review cap ${maxRounds} reached before 8 rounds`);\nreturn { rounds };\n```\n\nThe first MCP request uses `{ "args": { "maxRounds": 6 } }` and returns a failed run with a\npersisted six-entry journal. The next request sends the same content via `script` (or the same\nabsolute `scriptPath`), `{ "args": { "maxRounds": 8 } }`, and the returned run ID as\n`resumeFromRunId`. Calls 0\u20135 match uniquely and replay for zero current provider tokens; calls 6\u20137\nare new and run live. This changed-args pattern is specific to new-run entry points that accept\ncurrent args with `resumeFromRunId`. The MCP `workflow` tool does, as does\n`WorkflowManager.runSync(script, newArgs, { resumeFromRunId })`. MCP resume always requires\nexplicit content; a bare `resumeFromRunId` is invalid. `WorkflowManager.resume(runId)` is a\ndifferent same-ID recovery API: it reloads the persisted original script/args and permanently uses\nlegacy positional replay semantics, while the independent default-on channel may still continue an\neligible usage/auth-interrupted live call.\n\n## <a name="custom-backends-metabackends"></a>Custom backends \u2014 `meta.backends`\n\n```js\nexport const meta = {\n  name: "\u2026", description: "\u2026",\n  backends: {\n    browser: {\n      command: "browser-acp",          // required: executable (absolute or on PATH)\n      args: ["--headless"],            // default []\n      env: { BROWSER_PROFILE: "qa" },  // merged OVER the child\'s inherited env \u2014 per-backend secrets go here\n      sessionMeta: { viewport: "desktop" },  // static ACP _meta on every session/new (per-call `meta` merges over it)\n      structuredOutputTool: true,      // default true; false = keep this backend on the prompt/_meta schema fallback\n    },\n  },\n};\n```\n\nScript-declared backends are **trust-gated**: they spawn commands on the host machine, so they stay inert until the composition root approves them \u2014 elicitation approval in the MCP server, `allowScriptBackends: true` (or a per-backend callback) on `runDynamicWorkflow`, `ExecOptions.scriptBackends` on a manager, or `AGENTPRISM_ALLOW_SCRIPT_BACKENDS=1`. A *declined* backend aborts the run rather than silently rerouting its calls to the default backend. Host-registered names always win over script declarations. Prefer host registration (`createAcpRunner({ backends })` / `AGENTPRISM_BACKENDS` env JSON) when you control the host.\n\n## <a name="agenttype-definitions"></a>`agentType` definitions\n\nMarkdown files at `<runCwd>/.agentprism/agents/<name>.md` (project) and `~/.agentprism/agents/<name>.md` (user); project wins on name collision. Frontmatter + body:\n\n```markdown\n---\ndescription: Read-only security auditor\ntools: [read, grep, glob]        # allowlist of tool names (omit = all)\ndisallowedTools: [bash]          # denylist, applied after the allowlist\nmodel: claude/opus[1m]           # verified id; agent({ model }) overrides it\nisolation: worktree              # optional\n---\nYou are a security auditor. Report findings; never modify files.\n```\n\nThe body is prepended to the agent\'s task as role guidance. An unknown `agentType` logs a warning and runs with default tools/model (the name degrades to a prose hint).\n\n## How hosts run scripts (what authors can assume)\n\nThe MCP route (`npx @automatalabs/mcp-server`, tool name `workflow`) \u2014 the canonical way an agent\nruns an authored script \u2014 accepts exactly one of raw\n`script` source or an absolute server-filesystem `scriptPath`, plus `args`. A path is read once and\nsnapshotted at admission. Foreground is the default and streams progress/resolves checkpoints live;\nlong work uses `background:true` plus bounded `action:"await"`. It supports explicit\n`resumeFromRunId` with content supplied again by either mechanism; non-elicitation clients resume\n`headless: "pause"` checkpoints with `checkpointReplies` from terminal\n`outcome.checkpointContext`. Unlike the SDK\'s `openWorkflowDir` path, this input does not resolve a\nsaved workflow name. The `workflow` tool is the server\'s whole tool surface \u2014\nrun/resume/inspect/await/stop are action branches, not separate tools. Stop without `callIndex`\naborts the whole run; stop with `callIndex` cancels only that in-flight agent and returns a live\ninspection snapshot. `labelGlob` filters that snapshot and never selects cancellation. A run that pauses with\n`reason: "auth_required"` resumes via a new run after the backend\'s own CLI is logged in out-of-band\n(see below). Prompt-capable MCP hosts (e.g. Claude Code, where it surfaces as a slash command) also\nget this entire guide from the server itself as the **`author-workflow`** prompt, with an optional\n`task` argument. Environment knobs shared by both routes (MCP server and the SDK below): `AGENTPRISM_DEFAULT_BACKEND`,\n`AGENTPRISM_ACP_POOL_SIZE` (schema-run parallelism on OpenCode/custom backends scales with the pool,\none injected-tool registry per process), `AGENTPRISM_BACKENDS`,\n`AGENTPRISM_ALLOW_SCRIPT_BACKENDS`, `AGENTPRISM_PERSISTENCE_ROOT`, plus per-backend spawn\noverrides. Pi uses `AGENTPRISM_PI_ACP_CMD` with optional `AGENTPRISM_PI_ACP_ARGS`; otherwise the\ninstalled exact-pinned package bin is used before the `npx -y @automatalabs/pi-acp` fallback.\n\nEmbedding hosts can instead drive the same contract directly through the SDK:\n\n```ts\nimport { runDynamicWorkflow } from "@automatalabs/workflows";\n\nconst run = await runDynamicWorkflow(script, {\n  cwd: "/abs/project",              // the script\'s `cwd` global; every session\'s base dir\n  args: { target: "src/" },         // the script\'s `args` global, verbatim\n  allowScriptBackends: true,        // approve meta.backends (or a per-backend callback)\n  exec: {\n    tokenBudget: 500_000,           // hard cap \u2192 budget.total in-script\n    maxAgents: 200,\n    concurrency: 8,                 // concurrent agents (default 8)\n    agentTimeoutMs: 600_000,         // total wall-clock ceiling for every attempt\n    agentRetries: 1,                // default retries for recoverable failures\n    confirm: async (text, opts) => true,   // live checkpoint channel; omit = authored headless mode\n    onProgress: (snapshot) => {},\n  },\n});\n// run.status: "completed" | "paused" | "failed" | "aborted"\n// run.result \xB7 run.runId (resume handle) \xB7 run.tokenUsage \xB7 run.logs \xB7 run.phases \xB7 run.effectiveLimits\n// run.replayEligibility? \xB7 run.resumeReport? \xB7 run.fallbacks? \xB7 run.checkpointsTaken? (absent when empty)\n```\n\nFor edited-script/current-args resume, call the same entry point with\n`exec: { resumeFromRunId: previous.runId, resumePolicy: "auto", checkpointReplies }`. Reply keys\nname source indexes. The manager prepares and durably persists correspondence before execution.\n\nExact detached host types:\n\n```ts\ninterface WorkflowExecuteToolInputBase {\n  action?: "run";\n  args?: unknown;\n  maxAgents?: number;\n  concurrency?: number;\n  agentRetries?: number;\n  agentTimeoutMs?: number | null;\n  tokenBudget?: number | null;\n  resumeFromRunId?: string;\n  resumePolicy?: "auto" | "positional";\n  checkpointReplies?: Record<number, unknown>;\n  background?: boolean; // default false\n}\n\ntype WorkflowExecuteToolInput = WorkflowExecuteToolInputBase & (\n  | { script: string; scriptPath?: never }\n  | { script?: never; scriptPath: string } // absolute path on the server\n);\n// WorkflowExecuteToolInputBase also carries projectDir?: string \u2014 the absolute project\n// directory selecting the project-scoped run store and default execution cwd. REQUIRED for\n// run on the shared workflow daemon (one registration serves every project); optional on a\n// single-project (--in-process) server. inspect/await/stop never take it: a runId locates\n// its project store automatically.\n\ninterface WorkflowAwaitToolInput {\n  action: "await";\n  runId: string;\n  waitMs?: number;      // default 20_000; integer 0..25_000\n  lastN?: number;       // default 20; integer 1..50\n  labelGlob?: string;   // same whole-label glob as inspect\n  logLines?: number;    // default 20; integer 0..50\n}\n\ninterface WorkflowBackgroundAccepted {\n  runId: string;\n  status: "running";\n  scriptSource: "inline" | "path";\n  scriptUri: string;\n  limits: WorkflowRunLimits;\n  replayEligibility?: WorkflowReplayEligibility;\n}\n\ninterface WorkflowAwaitMetadata {\n  requestedMs: number;\n  elapsedMs: number;\n  returnedBecause: "terminal" | "timeout" | "immediate";\n}\n\ninterface WorkflowRunAwaitResult<T = unknown> extends WorkflowRunStatus {\n  wait: WorkflowAwaitMetadata;\n  tokenUsage?: TokenUsage;\n  outcome?: Omit<WorkflowExecutionToolResult<T>, "scriptSource">; // exactly when terminal\n  scriptUri: string;\n  lineage: Array<{ runId: string; uri: string; available: boolean }>;\n}\n\ninterface WorkflowStopToolInput {\n  action: "stop";\n  runId: string;\n  callIndex?: number;  // omitted = whole-run abort; present = cancel one in-flight agent\n  lastN?: number;\n  labelGlob?: string;\n  logLines?: number;\n  script?: never;\n  scriptPath?: never;\n  waitMs?: never;\n}\n```\n\nThe selected stop form requires a live, uniquely addressable agent attempt. Settled/unallocated\nindexes, checkpoints, duplicate scoped indexes, and terminal runs are errors that enumerate the\ncurrently in-flight call-index/label pairs. A successful selected cancellation returns the ordinary\nlive `WorkflowRunStatus`; whole-run stop returns the terminal `WorkflowStopResult`.\n\n`WorkflowRunResult.fallbacks?: WorkflowRunFallback[]` retains the compatibility shape\n`{ callIndex, label, phase?, requestedSpec, resolvedModel?, backendId?, kind, message, continuation? }`.\n`kind` is `model | modifier | continuation`; continuation details report either a reattached\n`resume | load` method or an exact skip reason. The model-resolution pipeline itself produces no entries.\n`WorkflowRunResult.checkpointsTaken?: WorkflowCheckpointTaken[]` records resolved checkpoints as\n`{ callIndex, kind, decision, source }`, where source is `live`, `headless-default`,\n`journal-replay`, or `injected`. A paused checkpoint is not resolved. Both fields are persisted and\nappear in foreground results plus terminal await `outcome`; neither appears on `WorkflowRunStatus`.\n\nAt most four background runs may be active or starting per server instance. Foreground, inspect,\nawait, and stop consume no slot; a durably stopped background run frees its slot immediately even\nwhile backend session wind-down remains. A timeout returns the freshest status and partial cumulative usage; replay\nhits cost/add zero. Terminal results have no MCP TTL and are reconstructed after restart while the\nproject run record remains readable. The inherited status fields stay redacted/bounded at 24,576\nstructured bytes and 8,192 text bytes. The full script lineage is never truncated; when lineage\nalone exceeds the status budget, `truncation.maxStructuredBytes` reports the larger actual envelope\nlimit. Terminal `outcome` preserves the raw authored result/full logs and has no new total cap, but\nit is never copied into text. It includes `scriptUri` but not the unpersisted admission-only\n`scriptSource`.\n\nThe background start has no enduring request signal, progress channel, or live checkpoint channel.\nIt returns immediately and emits no progress after returning, even if the initiating request\nsupplied a progress token. A later bounded `action:"await"` is a separate request; when that await\ncarries a progress token, it can stream coarse phase and distinct started/ended-call progress while\npending. The legacy/inconsistent-log polling fallback emits no progress notifications. Headless\ncheckpoint default continues, abort fails with `WORKFLOW_ABORTED`, and pause returns\n`checkpoint_required` plus `outcome.checkpointContext`. Auth pauses return non-secret\n`outcome.authContext`; log the backend CLI in before resume. Background is process-lifetime, not\ndaemon execution: process death can interrupt an in-flight call, and stale durable\n`pending`/`running` state reconciles under its lease to `paused` / `interrupted`.\n\nBackground runs are nevertheless observable independently of the initiating tool request. Every\njournaling run has `workflow://runs/{runId}/events`: subscribe to the canonical URI for advisory\n`resources/updated` hints, then read/paginate with `after`, `limit`, and `streamId`. Progress is\ncoarse and content-bearing (not token fidelity); `agentTranscript` rows are redacted assistant/tool\nupserts partitioned by `(scope, callIndex, executionStartSeq)` and reduced by greatest revision per\nentry index. The durable cursor is authoritative when hints coalesce or a subscriber falls behind.\n\n`action:"await"` and `action:"inspect"` never replay the script or spend tokens. Their cold\npreflight may briefly acquire a dead owner\'s stale lease solely to reconcile `pending`/`running` to\n`paused` / `interrupted`. `resumeFromRunId` executes a new run with the caller\'s current script or\npath snapshot and args, and a new run ID. Every resumed background run durably seeds its inherited prefix (including a\nmanager-owned checkpoint injection) beneath that new ID before acknowledgement, so later resume\nhops remain self-contained. The MCP layer never rewrites that seed.\n\nEvery admitted script is an immutable persistence-backed MCP resource at\n`workflow://runs/{runId}/script`. Run results link the new script; inspect/await link the full resume\nlineage oldest-to-newest and expose structured `{ runId, uri, available }` entries. A fresh session\ncan read a lost inline script and explicitly send that text back with `resumeFromRunId`; a path is\nnever persisted or implicitly re-read. Listing/completion include only the 50 newest runs, but a\ndirect URI read works for any retained project run.\nThe MCP layer retains no scripts, args, or synthetic lineage metadata in process memory.\n\n`action:"stop"` durably aborts a `running` or `paused` run live in the serving process, cancels any\npending agent/checkpoint request, appends `stopped`, releases the lease, and returns the final\ninspection projection with `stopped:true`. Resume is safe immediately; await adds nothing. Only\nbackend session wind-down can remain, observable through inspect\'s agent states. A repeated stop on\na terminal run succeeds with `stopped:false, alreadyTerminal:true`. For the kill-patch-resume loop:\nstop, edit the file, then submit its `scriptPath` with `resumeFromRunId`. An in-flight stop may lack\na quiescent terminal-environment proof, so the manager can conservatively run that resume live;\ninspect `replayEligibility` and `resumeReport` rather than assuming a prefix replay.\n\nRetain the run ID and inspect halted runs before guessing. The exact inspection input is:\n\n```ts\ninterface WorkflowInspectToolInput {\n  action: "inspect";\n  runId: string;       // /^[a-z0-9]+-[a-z0-9]+$/, at most 128 characters\n  lastN?: number;      // default 20; integer 1..50\n  labelGlob?: string;  // non-empty; at most 128 Unicode code points\n  logLines?: number;   // default 20; integer 0..50\n  script?: never;\n  scriptPath?: never;\n}\n```\n\n`labelGlob` matches the whole raw agent label case-sensitively: `*` is zero or more Unicode code\npoints, `?` is exactly one, and backslash escapes the next character (a trailing backslash is\nliteral). Checkpoints and unknown legacy calls are excluded when a glob is present. Filtering\nhappens before `lastN`; selected calls return in ascending call-index order.\n\n```ts\ninterface WorkflowLogTail {\n  lines: string[];\n  totalLines: number;\n  omittedLines: number;\n  truncatedLines: number;\n  redactedLines: number;\n}\n\ninterface WorkflowRunCallStatus {\n  index: number;\n  kind: "agent" | "checkpoint" | "unknown";\n  label?: string;\n  phase?: string;\n  model?: string;\n  backendId?: string;\n  timeoutMs?: number | null;\n  errorCode?: string;\n  resultPreview: string;\n  resultRedacted: boolean;\n  resultTruncated: boolean;\n}\n\ninterface WorkflowRunStatus {\n  runId: string;\n  status: "pending" | "running" | "paused" | "completed" | "failed" | "aborted";\n  workflowName: string;\n  phases: string[];\n  currentPhase?: string;\n  reason?: string;\n  errorCode?: string;\n  limits?: WorkflowRunLimits; // absent only on legacy persisted records\n  replayEligibility?: WorkflowReplayEligibility;\n  logTail: WorkflowLogTail;\n  calls: WorkflowRunCallStatus[];\n  filter: { lastN: number; logLines: number; labelGlob?: string };\n  truncation: {\n    maxStructuredBytes: number;\n    byteCapApplied: boolean;\n    phases: { total: number; returned: number; shortened: number };\n    logs: { total: number; returned: number; shortened: number; redacted: number };\n    calls: {\n      total: number;\n      matched: number;\n      returned: number;\n      shortenedResults: number;\n      redactedResults: number;\n    };\n  };\n}\n\ninterface WorkflowRunLimits {\n  maxAgents: number;\n  tokenBudget: number | null;\n  concurrency: number;\n  agentRetries: number;\n  agentTimeoutMs: number | null;\n}\n```\n\nInspection returns only this allowlisted projection: never raw script, args, prompts, histories,\nhashes, session IDs, cwd, checkpoint/auth details, or raw results. Credential-shaped data is\nredacted, results are structurally compacted, every outward text scalar/preview is capped at 512\nUTF-8 bytes, inherited status JSON at 24,576 bytes, and inspection text at 8,192 bytes. Full lineage\ncan raise the structured envelope limit as reported by `truncation.maxStructuredBytes`. An unknown ID is\na tool error with no structured content; reading an existing failed run succeeds and reports\n`status:"failed"`. Every paused, failed, or aborted execution result also carries a redacted\nfinal-20 `logTail` (present when empty) and renders it in the immediate terminal text. Completed\nexecution results omit that extra field while retaining their full `logs` array.\n\nBackend auth comes from the machine the host runs on: Claude via a logged-in Claude Code install or `ANTHROPIC_API_KEY`; Codex via `~/.codex/auth.json`; OpenCode via `opencode auth login` (its CLI must be installed \u2014 it is not bundled); Pi via one of `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `XAI_API_KEY`, `OPENROUTER_API_KEY`, or ambient credentials in `~/.pi/agent/auth.json`. A script only needs auth for the backends it actually routes to.\n\n## The validator \u2014 `agentprism-workflows validate`\n\n```bash\nnpx @automatalabs/workflows validate <workflow-file> [options]\n```\n\nZero tokens: a static parse (meta literal, syntax, and direct nondeterministic call expressions) plus a dry run in the real engine realm against a mock `AgentRunner` that fabricates deterministic results (`enum[0]`, `true` booleans, `mock-<field>` strings, one to three array items). Afterward, validation opens each distinct routed `{ backend, model }` pair once without a prompt, selects the authored call model verbatim, and surfaces its echoed model-specific config-options table in both human and JSON reports, even when the script authors none. It checks exact authored ids, select values, boolean types, and the reserved `"model"` key; errors name the call label, authored value, and alternatives and exit `2`. Self-advertised recognized domains win. Otherwise, Claude/Codex enumerate up to 32 picker-visible models and merge consistent effort orders before using the same ordered clamp path. Pi already advertises its domain. OpenCode, custom/unknown backends, too-large catalogs, and inconsistent orders use exact advertised-value validation. Claude effort omission is model-specific and its `default` sentinel is excluded from ceiling ordering. A pair\'s spawn/auth/model-selection/session failure adds one warning, reports `probed:false`, and skips only that pair\'s checks\u2014it never fails validation by itself. Catalogs are read afresh on every validation. Script boolean-controlled branches explicitly instead of treating the all-true default as convergence coverage.\n\n| flag | meaning |\n|---|---|\n| `--args <json>` / `--args-file <path>` | the script\'s `args` global for the dry run |\n| `--mock-answers <json>` | label-glob answers for dry-run calls; mutually exclusive with the file form |\n| `--mock-answers-file <path>` | read the same JSON object from a UTF-8 file resolved against the process cwd |\n| `--workflows-dir <dir>` | repeatable; a folder of workflow scripts (name = filename stem). Lets the positional be a NAME and resolves nested `workflow("<name>")` calls |\n| `--parse-only` | static parse only |\n| `--cwd <dir>` | dry-run base cwd (default: throwaway temp dir, so `isolation: "worktree"` no-ops; a real repo cwd creates and cleans up real worktrees) |\n| `--token-budget <n>` | sets `budget.total`; the mock reports 1000 tokens per agent call |\n| `--max-agents <n>` | cap on dry-run agent calls |\n| `--timeout-ms <n>` | dry-run wall-clock limit (default 30000) |\n| `--json` | machine-readable `ValidateWorkflowReport` on stdout |\n\nInline false-branch fixture (exact shell form):\n\n```bash\nagentprism-workflows validate flow.workflow.js \\\n  --mock-answers \'{"refute:*":{"real":false}}\'\n```\n\nEquivalent reusable file with a reject-then-approve sequence:\n\n```json\n{\n  "refute:*": { "real": false },\n  "quality:review": {\n    "$sequence": [\n      { "ok": false, "feedback": "exercise the revision path" },\n      { "ok": true }\n    ]\n  }\n}\n```\n\n```bash\nagentprism-workflows validate flow.workflow.js --mock-answers-file mock-answers.json\n```\n\nRules match the final resolved label case-sensitively across the whole string. `*` matches zero or more characters (including `:` and `/`), `?` one character, and `\\` escapes the next character; empty globs and trailing escapes are invalid. Object order is captured once and the **last matching rule wins**, so put `"*"` before narrower exceptions. Raw canonical array-index keys (`"0"` or a non-zero, no-leading-zero decimal through `"4294967294"`) are reserved because ECMAScript reorders them. To match numeric label `10`, use JSON key `"\\\\10"`; `"01"` and `"4294967295"` are ordinary keys.\n\nA single answer is reusable. `{ "$sequence": [...] }` is finite and only the winning rule consumes it; a raw array is one array result, and a sequence element is ordinary answer data even when it contains `$sequence`. Exhaustion fails instead of repeating the last item or falling back. The machine report uses zero-based `sequenceIndex`; human lines render one-based `[position/length]`. Earlier matching rules count the match even when shadowed, and `dryRun.mockAnswers.unused` distinguishes `no-match`, `shadowed`, and partially consumed `not-reached` items. Unused fixtures warn but do not fail validation.\n\nFor schema calls, each answer deep-merges over a **fresh** fabricated base: JSON objects merge recursively; arrays, `null`, falsy primitives, and other scalars replace. The merged value is TypeBox-checked without coercion. Any answer-caused violation fails non-recoverably with `SCHEMA_NONCOMPLIANCE`; a failure already present at the identical untouched path/message in the simple fabricated base may be accepted with a grouped inherited-fabrication warning. A valid override can repair such a base limitation. Schema-less answers must be nonblank strings. Fixture failure messages, attribution, and warnings contain only labels, globs, positions, paths, and counts\u2014not answer values.\n\nLimits: 256 KiB raw UTF-8 for either CLI source and canonical JSON for programmatic input; 256 rules; 1\u2013256 UTF-16 code units per glob; 256 entries per sequence; answer depth 32. Inputs must be plain JSON data. Mock-enabled validation serves agent calls serially for deterministic FIFO sequence allocation; it is not a concurrency/load simulation, and the soft token gate may admit work differently than an unscripted concurrent dry run. Fixture values still flow into the script like real agent results, so author code can expose them via `log()` or its returned result\u2014never store credentials or production data in fixtures.\n\nExit codes: `0` valid \xB7 `1` parse/static failure \xB7 `2` dry-run failure \xB7 `3` usage error. The report also lists every checkpoint with the mock reply (`default ?? true`) and warnings for backend approval, phase mismatch, `headless: "abort"`, and agent-less scripts. `headless: "pause"` dry-runs cleanly. A saved nested workflow still needs `--workflows-dir`.\n\nProgrammatic: `validateWorkflowScript(script, { args, workflows, dryRun, cwd, tokenBudget, maxAgents, timeoutMs, mockAnswers })` from `@automatalabs/workflows` returns the same report. Invalid workflow scripts resolve to reports; invalid `mockAnswers` supplied from untyped JavaScript throws `TypeError` before parsing.\n\n## Harness config discovery \u2014 `agentprism-workflows config`\n\nValidate\'s sibling: the same no-prompt config probe, standalone \u2014 no script required. Run it BEFORE authoring to read each harness\'s advertised, negotiable session surface (model ids including bracket variants, effort levels, modes, boolean knobs) instead of guessing values or writing a throwaway probe workflow.\n\n```bash\nnpx @automatalabs/workflows config                  # every routable harness\nnpx @automatalabs/workflows config codex opencode   # only the named harnesses\nnpx @automatalabs/workflows config claude --json    # machine-readable report\n```\n\nHarness names are the routing names: built-in `claude` / `codex` / `opencode` / `pi` plus any custom backend registered via the `AGENTPRISM_BACKENDS` env var (registered customs also join the no-argument default set). Each harness opens one session without a prompt \u2014 zero tokens \u2014 and its catalog is read fresh; a harness that cannot spawn or authenticate reports `probed: false` with the reason and never blocks the others.\n\nThe no-argument built-in sequence comes from `BUILTIN_BACKEND_IDS`; authoring prose describes the\ncurrent registry rows and does not define a separate supported-backend list.\n\n| flag | meaning |\n|---|---|\n| `--cwd <dir>` | session cwd for the probes (default: the current directory \u2014 harnesses may resolve project-level config, and hence their catalog, from it) |\n| `--timeout-ms <n>` | per-harness probe bound (default 60000); a timed-out harness reports `probed:false` |\n| `--json` | machine-readable `HarnessConfigReport` on stdout (`harnessOptions` uses the same per-harness shape as validate\'s report) |\n\nExit codes: `0` all probed \xB7 `1` at least one probe failed \xB7 `3` usage error.\n\nProgrammatic: `probeHarnessConfig({ harnesses, backends, cwd, timeoutMs })` from `@automatalabs/workflows` returns the same report (`backends` merges over `AGENTPRISM_BACKENDS` exactly like `createAcpRunner`); `formatHarnessConfigReport(report)` renders the human table.\n\n## Workflow folders \u2014 `openWorkflowDir`\n\nHosts that keep versioned folders of workflow scripts serve them by name with:\n\n```ts\nimport { openWorkflowDir, runDynamicWorkflow } from "@automatalabs/workflows";\n\nconst flows = openWorkflowDir("./workflows");   // or [projectDir, teamDir] \u2014 first hit wins; no I/O here\nflows.list();                                    // [{ name, file, meta }] \u2014 fresh scan per call\nconst run = await runDynamicWorkflow("review-pr", { workflows: flows, args });\n```\n\nThe filename stem is the name (`review-pr.workflow.js` \u21D2 `review-pr`; `.workflow.js` beats `.js`). With the `workflows` option set, the first argument may be a name AND nested `workflow("<name>")` calls resolve from the same view (`flows.resolve` is a ready-made `loadSavedWorkflow` for hand-built `WorkflowManager`s). Every method reads the filesystem at call time \u2014 a git checkout/pull is picked up immediately \u2014 while each admitted run persists the exact script content used for journal correspondence. For script AUTHORS the takeaway is simply: `workflow("<name>")` works when the host serves a folder; keep names equal to filename stems.\n\n---\n\n# Complete example \u2014 quick-wins.workflow.js\n\nA complete, validated script (`loopUntilDry()` with per-round vendor rotation, dedup threading via a `seen` list, and an in-round budget floor; runs standalone or nested):\n\n```js\n// quick-wins \u2014 a small, self-contained hunter that repo-triage nests by name\n// (`workflow("quick-wins", {...})`) and that also runs standalone:\n//\n//   npm start -- --workflow quick-wins\n//   npx agentprism-workflows validate quick-wins --workflows-dir workflows\n//\n// Demonstrates loopUntilDry(): keep spawning hunt rounds \u2014 each on the next vendor\n// in the pool \u2014 until two consecutive rounds add nothing new (or the round cap /\n// token budget stops it first). Workflow scripts are self-contained strings with no\n// imports, so the vendor pool is repeated here rather than shared with repo-triage.\nexport const meta = {\n  name: "quick-wins",\n  description: "Hunt small, high-confidence quick wins across the repo until two consecutive rounds come up dry",\n  phases: [{ title: "Hunt" }],\n};\n\n// args \u2014 every knob optional; hosts may hand args through as a JSON string.\nconst raw = typeof args === "string" ? (() => { try { return JSON.parse(args); } catch { return {}; } })() : args;\nconst opt = raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};\nconst rounds = Number.isFinite(Number(opt.rounds)) && Number(opt.rounds) >= 1 ? Math.floor(Number(opt.rounds)) : 4;\nconst focus =\n  typeof opt.focus === "string" && opt.focus.trim().length > 0\n    ? opt.focus.trim()\n    : "small, safe, high-confidence improvements";\nconst avoid = Array.isArray(opt.avoid) ? opt.avoid.filter((x) => typeof x === "string") : [];\n\n// These registered-prefix specs use ids verified against each live harness catalog.\nconst POOL = [\n  { name: "claude", model: "claude/opus[1m]", mode: "plan" },\n  { name: "codex", model: "codex/gpt-5.6-sol", mode: "read-only" },\n  { name: "opencode", model: "opencode/zai/glm-5.2" },\n];\n\nconst WINS = {\n  type: "object",\n  additionalProperties: false,\n  required: ["wins"],\n  properties: {\n    wins: {\n      type: "array",\n      items: {\n        type: "object",\n        additionalProperties: false,\n        required: ["file", "summary", "action"],\n        properties: {\n          file: {\n            type: "string",\n            description: "Repo-relative path of a file you actually opened \u2014 copy it exactly, never invent one",\n          },\n          summary: { type: "string", description: "One sentence: the small problem or missed improvement" },\n          action: { type: "string", description: "The concrete, low-risk change that fixes it, in one clause" },\n        },\n      },\n    },\n  },\n};\n\nphase("Hunt");\nconst seen = [];\nconst wins = await loopUntilDry({\n  round: async (i) => {\n    // Budget floor: leave headroom for whatever runs after this hunt. When nested\n    // inside repo-triage, budget.* reads the PARENT run\'s shared budget.\n    if (budget.total && budget.remaining() < 30_000) {\n      log(`Hunt round ${i + 1}: stopping \u2014 only ${budget.remaining()} tokens left`);\n      return [];\n    }\n    const v = POOL[i % POOL.length];\n    const r = await agent(\n      `Hunt round ${i + 1}: find up to 3 quick wins in this repository \u2014 ${focus}. ` +\n        "A quick win is a small, safe, self-contained improvement (a missing guard, a stale doc line, an obvious dead branch), " +\n        "not a refactor. Open files and ground every entry in code you actually read; never emit a placeholder.\\n" +\n        `Already known \u2014 do NOT repeat anything on this list: ${JSON.stringify([...avoid, ...seen])}`,\n      { label: `hunt:${i + 1}:${v.name}`, phase: "Hunt", schema: WINS, model: v.model, mode: v.mode },\n    );\n    const found = (r?.wins ?? []).filter((w) => typeof w.file === "string" && w.file.length > 0 && !w.file.startsWith("/"));\n    seen.push(...found.map((w) => `${w.file}: ${w.summary}`));\n    return found.map((w) => ({ ...w, foundBy: v.name }));\n  },\n  key: (w) => `${w.file}::${w.summary}`,\n  consecutiveEmpty: 2,\n  maxRounds: rounds,\n});\n\nlog(`quick-wins: ${wins.length} unique wins across the hunt`);\nreturn { wins };\n```\n';
+var AUTHORING_PROMPT_CONTENT = '# Writing AgentPrism workflow scripts\n\nA workflow script is plain JavaScript, passed around as a **string**, not a module. The engine runs it in a deterministic sandboxed realm. Each `agent()` call opens a session on an [Agent Client Protocol](https://agentclientprotocol.com) (ACP) backend \u2014 Claude Code, OpenAI Codex, OpenCode, pi, or a custom ACP agent server. The backend runs its own tool loop to completion and returns final text or a schema-validated object. One script can mix backends per call.\n\nThe **Workflow script reference** section at the end of this document holds the exhaustive option tables, routing grammar, and error codes.\n\n## The guide, by task\n\nEvery section of the guide is inlined below, after the core: Running workflows (the MCP server and `workflow` tool), backends and structured output, composition and failure, quality helpers and checkpoints, the execution environment, determinism and resume, and worked examples with validation.\n\n## The mental model\n\n- **The script is the orchestrator; agents are workers.** All control flow \u2014 loops, fan-out, dedup, aggregation, conditionals \u2014 lives in script code. Agents cannot spawn agents and cannot see each other. Give each agent one self-contained task.\n- **Each `agent()` call opens a fresh session with no memory.** Interpolate everything a later call needs into its prompt. (Sole exception: resume can continue the same usage/auth-interrupted occurrence \u2014 see Determinism and resume.)\n- **Agents are real coding agents, not chat completions.** They have file access, shells, and tools, rooted at the run\'s working directory. "Read the failing test and fix it" is a valid prompt; the agent will edit files.\n- **The DSL primitives are realm globals, not imports.** There is nothing to `import` \u2014 `agent`, `parallel`, `pipeline`, `gate`, `checkpoint`, `args`, `budget`, \u2026 are injected. Top-level `await` and a top-level `return` are valid. The script\'s return value becomes the run\'s `result`.\n- **Scripts are plain JavaScript, not TypeScript.** Type annotations fail to parse. The realm has no Node APIs (no `require`, `import`, `fs`, `fetch`, timers). All side effects happen through agents.\n- **Live observability needs no script annotations.** Journaling runs publish redacted progress and transcript upserts at `workflow://runs/{runId}/events`. Author labels for human correlation, not to enable this behavior.\n\n## Minimal script\n\n```js\nexport const meta = {\n  name: "repo-summary",\n  description: "Summarize what a repository does",\n};\n\nconst summary = await agent(\n  `Read the README and the package manifests under ${args.path}, then ` +\n  `summarize what this project does in five sentences.`,\n  { label: "summarize" },\n);\nreturn { summary };\n```\n\nRun scripts through the MCP server\'s `workflow` tool \u2014 registration, the run/await/inspect/stop actions, and the `args`/`cwd` globals are covered in the **Running workflows** section below.\n\n## Pre-flight checklist\n\n- [ ] `export const meta = { name, description }` is the first statement, a pure literal.\n- [ ] No `Date.now()` / `Math.random()` / no-arg `new Date()` / `Date()`; no imports, no Node APIs. Timestamps and randomness come in through `args`.\n- [ ] Every `parallel` element is a **thunk**; results are `.filter(Boolean)`-ed or null-checked.\n- [ ] Every prompt is self-contained: prior results are interpolated in, and every file path a prompt references was written by an earlier call, supplied through `args`, or created by that prompt\'s own instructions.\n- [ ] Schemas: object root, `additionalProperties: false`, everything `required`, a `description` on every field.\n- [ ] Model ids, effort values, and `configOptions` come from `npx @automatalabs/workflows config` or a validator report, never from memory. `mode` only on calls with a pinned `model`.\n- [ ] Worktree-isolated agents return their work as data \u2014 their edits are discarded when the call ends.\n- [ ] Replay is intentional: completed calls with matching identity and input fingerprints replay. Change a hashed field (normally the prompt) when a completed call must run again.\n- [ ] Budget loops guard on `budget.total`; caps and drops are `log()`-ed, not silent.\n- [ ] `checkpoint()` guards irreversible actions, with a sane headless `default` or an intentional `headless: "pause"`.\n- [ ] `return` a compact, structured result \u2014 it is the run\'s `result`, not a transcript.\n- [ ] `npx @automatalabs/workflows validate <file> --args \'<json>\'` exits 0 with no surprising warnings.\n\nFor the complete `agent()` option table, model-routing grammar, checkpoint options, error codes, `meta.backends` config fields, and the MCP tool input shapes, see the **Workflow script reference** section below.\n\n\n## Running workflows \u2014 the MCP `workflow` tool\n\nAgents run workflows through the single `workflow` tool served by `@automatalabs/mcp-server`. Register it once in the host\'s MCP configuration (project-scoped is typical):\n\n```json\n{ "mcpServers": { "agentprism-workflows": { "command": "npx", "args": ["-y", "@automatalabs/mcp-server@latest"] } } }\n```\n\nThe stdio command the host spawns is a thin **shim**. It proxies to a shared per-user **workflow daemon** (Streamable HTTP on loopback, auto-started on first use). Runs execute in the daemon, so they survive session end, host restarts, and tool timeouts; only daemon exit can interrupt in-flight work. Any later session can await, inspect, or stop a run. Runs, journals, and logs persist under `~/.agentprism/workflows/` per project namespace.\n\nEvery `run` call names its project with the required `projectDir` argument \u2014 an absolute path, normally the workspace root. One registration serves every project. `inspect`/`await`/`stop` take only a `runId`; the runId locates its project store automatically. Add `--in-process` to the args for the pre-daemon single-process behavior (`projectDir` is then optional), or register the daemon\'s HTTP endpoint directly in HTTP-capable hosts (`agentprism-workflow daemon url` prints snippets). The command resolves at spawn time, so a reconnect (`/mcp` in Claude Code) picks up the latest published version.\n\n### The `workflow` tool, by action\n\n- **Run** (default, no `action`): supply exactly one of `script` (the raw source string, no Markdown fences) or `scriptPath` (an absolute path on the server\'s filesystem), plus `projectDir`. A path is read once at admission and its content snapshotted; later edits affect only a new run. `args` arrives in the script as the `args` global; the run\'s base directory is the `cwd` global. Some hosts hand `args` through as a JSON **string** \u2014 tolerate both shapes (`typeof args === "string" ? JSON.parse(args) : args`). Foreground streams progress but is bound to the request and its timeout. Pass `background: true` for anything that may outlive one request; it acknowledges after durable admission with a `runId`.\n- **Await** (`{ action: "await", runId, waitMs }`): bounded collection for background runs. A timeout is progress, not failure \u2014 call again (`waitMs: 20000` is typical). At terminal status the response adds `outcome`: the authored result or pause context, plus `replayEligibility`, `resumeReport`, `fallbacks`, and `checkpointsTaken`.\n- **Inspect** (`{ action: "inspect", runId, lastN, labelGlob, logLines }`): a bounded snapshot \u2014 the latest matching calls with compact result previews plus the newest log lines. Use a narrow `labelGlob` to diagnose before deciding whether to resume, edit, or stop. Inspection never executes or resumes a script.\n- **Stop**: `{ action: "stop", runId }` durably aborts the whole run and returns its final snapshot; stopping a terminal run is a successful no-op. `{ action: "stop", runId, callIndex }` cancels exactly that in-flight agent: its slot settles to `null` with `AGENT_CANCELLED` and the run stays live. `labelGlob` only filters the returned snapshot; it never selects what to cancel.\n- **Resume**: a NEW run with `resumeFromRunId` plus the script content re-sent (the same `script` or `scriptPath`) and the desired `args` (+ `checkpointReplies` when answering a durable checkpoint). Read the returned `replayEligibility` for the predicted and observed replay prefix; never assume a prefix hit. Full semantics: **Determinism and resume**.\n\n### Operating rules\n\n- **Always retain the returned `runId`.** A paused, failed, or aborted response carries a redacted final-20 `logTail`. Read it before you change anything. Every admitted script is also an immutable resource at `workflow://runs/{runId}/script`, so a later session can recover a lost inline script.\n- **Two fingerprints control replay.** The identity hash covers the prompt, the resolved model, `mode` when set, non-empty sorted `configOptions`, `tier`, `phase`, `agentType`, the resolved agent definition, and the schema. The input fingerprint covers the resolved label, per-call `cwd` and isolation, `keepSession`, images, MCP servers, session/prompt metadata, and the approved script-backend digest.\n- **Operational bounds are not replay inputs.** Host `concurrency`, `agentRetries`, and `agentTimeoutMs`, plus per-call `timeoutMs` and `retries`, enter neither fingerprint. A resume does not inherit them from its source run; pass the values you want on every run. `agentTimeoutMs` caps the wall-clock time of each attempt; it is not an idle timer. A per-call `timeoutMs` can tighten that ceiling but cannot escape it. Each retry gets a fresh clock, so the envelope is `(resolved retries + 1) \xD7 resolved timeout`, with retries clamped to 3.\n- **Old journals stay usable.** Input formats below 2 replay positionally with `fallbackReason: "inputs-format-legacy"`. A current-format crash snapshot uses identity matching even without terminal-environment capture. Ancestor-scoped rows carried from \u22640.23 resume chains replay only while that ancestor run is still persisted. Journals resume across filesystem, environment, engine, Node, and V8 changes; `replayEligibility` reports those differences as diagnostics, never as gates.\n- **A background start returns immediately.** It sends no progress after it returns; collect progress with later bounded awaits. Background runs have no live checkpoint channel, so authored `headless` checkpoint modes apply. When a run\'s owner process dies, cold preflights reconcile stale `pending`/`running` state to `paused` with `pauseReason: "interrupted"`; a live owner is left alone.\n- A run paused with `reason: "auth_required"` resumes as a new run after you log in the backend\'s own CLI out of band.\n\n### Execution logs \u2014 the events resource\n\nEvery journaling run publishes an MCP resource at `workflow://runs/{runId}/events`. Subscribe to the canonical URI for advisory `resources/updated` hints, then read and paginate with `after`, `limit`, and `streamId`. Progress is coarse and redacted: `agentTranscript` rows are assistant/tool upserts partitioned by `(scope, callIndex, executionStartSeq)` and reduced by greatest revision per entry index. The durable cursor is authoritative when hints coalesce or a subscriber falls behind.\n\nEmbedding hosts can drive the same contract with `runDynamicWorkflow` / `WorkflowManager` from `@automatalabs/workflows`; the script contract is identical either way.\n\n## Choosing the agent for each call\n\nThe backend is selected **per `agent()` call** from its effective `model` string. One script can plan on one vendor\'s agent, implement on another\'s, and review on a third\'s, handing structured results between them.\n\nThe built-in names (`claude`, `codex`, `opencode`, `pi`) come from the runtime backend registry. Registered custom names extend that set.\n\n- **Omit `model` entirely** for maximum portability \u2014 the call runs on whatever default backend the host configured (`AGENTPRISM_DEFAULT_BACKEND`, or the host\'s session model). A script with no model specs anywhere runs unchanged on any backend.\n- **Route by one registered first segment.** Split on the first `/`; ASCII-case-insensitive `claude`, `codex`, `opencode`, `pi`, or a registered custom backend name selects that harness and is stripped exactly once. A custom registration wins on a built-in-name collision.\n- **Use a backend name alone** (`claude`, `codex`, `opencode`, `pi`, or a custom name) to preserve the harness\'s configured default model. No model config call is made.\n- **Everything else goes intact to the default backend.** `anthropic/\u2026`, `openai/\u2026`, bare `opus`, and bare `gpt-\u2026` are not routing aliases. When an id remains after routing, it is sent byte-for-byte: no catalog matching, case folding, bracket parsing, effort/Fast option driving, retry, or fallback. Harness rejection is an agent error.\n- **`tier`** (`"small" | "medium" | "big"`) is a coarse alternative resolved from the host\'s tier config \u2014 use it for "a cheap model" without naming a vendor.\n\nThe published examples use ids verified against live harness catalogs: `claude/opus[1m]`, `codex/gpt-5.6-sol`, and `opencode/zai/glm-5.2`. For Pi, `pi/openrouter/vendor/model-id` strips only `pi/`; Pi then splits provider `openrouter` from model id `vendor/model-id`. Prefer backend-only forms when the desired model is configured inside the harness.\n\nNever guess model ids, effort values, or option names from memory \u2014 read the live catalog first:\n\n```bash\nnpx @automatalabs/workflows config                # every routable harness (claude, codex, opencode, pi + registered customs)\nnpx @automatalabs/workflows config codex --json   # one harness, machine-readable\n```\n\nOne no-prompt session per harness, zero tokens: the table lists every negotiable session option \u2014 model ids (including bracket variants like `opus[1m]`), effort levels, modes \u2014 exactly as the installed harness advertises them. One caveat: the bare `config` probe reads each harness with its **default model** selected, and option domains are **model-specific**. An option can appear only after a particular model is selected. Ceilings differ per model. Provider-served variants of the same model can advertise different domains. The authoritative per-model probe is the validator run on your real script: it selects each authored `{ backend, model }` pair first and echoes that pair\'s advertised table. Confirm every pinned model against its own echoed table; do not read package internals to discover options.\n\n```js\nconst plan   = await agent(PLAN_PROMPT,          { label: "plan",      model: "opencode/zai/glm-5.2", schema: PLAN });\nconst impl   = await agent(implPrompt(plan),     { label: "implement", model: "codex/gpt-5.6-sol" });\nconst review = await agent(reviewPrompt(impl),   { label: "review",    model: "claude/opus[1m]", schema: REVIEW });\n```\n\nUse `configOptions` only for exact ACP session options advertised by that routed harness. Read the per-harness advertised-options table first \u2014 `npx @automatalabs/workflows config <harness>`, or the same table in every validator report \u2014 before choosing ids or select values; catalogs vary by harness version, login, and machine.\n\n```js\nconst impl = await agent(implPrompt(plan), {\n  label: "implement",\n  model: "codex",\n  configOptions: { "fast-mode": true, reasoning_effort: "high" },\n});\n```\n\nIds and string/boolean values pass through verbatim in ascending id order, after model selection and before the prompt. There are no aliases, coercion, client-side vocabulary, defaults, or cached catalogs. Copy option ids character-for-character from the catalog, punctuation included \u2014 `"fast-mode"`, not `fast_mode` \u2014 and quote ids that are not valid identifiers. Never put `"model"` in `configOptions`; use the dedicated `model` field. A harness rejection follows the ordinary agent-error path.\n\nPi\'s thought-level option is named `thinkingLevel`, and its choices depend on the exact model in the same call:\n\n```js\nconst review = await agent(REVIEW_PROMPT, {\n  label: "pi-review",\n  model: "pi/openrouter/vendor/model-id",\n  configOptions: { thinkingLevel: "high" },\n});\n```\n\nValidation selects `openrouter/vendor/model-id` before reading Pi\'s choices. A listed value passes unchanged. A recognized value above an ordered model\'s ceiling, or in a model-specific gap, passes with a warning that names the effective clamp target. Pi advertises its SDK-derived domain directly. Claude and Codex are also ordered: when their options omit domain metadata, validation enumerates the advertised models and merges their per-model effort orders. A Claude model without an `effort` option does not support effort, and `default` never becomes a ceiling target. OpenCode and custom backends have no declared value order, so validation is exact-set. An unrecognized or unadvertised value fails with exit code `2`. Enumeration stops at 32 advertised models; a larger or inconsistently ordered catalog warns and falls back to exact advertised-value validation.\n\n**The harness is authoritative.** The client never substitutes a nearby model or silently falls back. A rejected id follows the existing agent-error path; a harness that accepts or ignores it determines the outcome. The public `fallbacks`/`onModelFallback` fields remain for compatibility but model resolution does not emit them.\n\n## Structured output\n\nPass `schema` \u2014 a **plain JSON Schema object literal** (no schema builders exist inside the realm) \u2014 and the call resolves to a **validated object** instead of text:\n\n```js\nconst FINDINGS = {\n  type: "object",\n  additionalProperties: false,\n  required: ["findings"],\n  properties: {\n    findings: {\n      type: "array",\n      items: {\n        type: "object",\n        additionalProperties: false,\n        required: ["file", "line", "summary"],\n        properties: {\n          file:    { type: "string", description: "Repo-relative path \u2014 copy it exactly, never invent one" },\n          line:    { type: "number", description: "1-indexed line the finding anchors to" },\n          summary: { type: "string", description: "One sentence stating the defect, grounded in code you actually read" },\n        },\n      },\n    },\n  },\n};\n\nconst report = await agent("Review the diff on this branch for correctness bugs.", {\n  label: "review", schema: FINDINGS,\n});\nreport.findings.forEach((f) => log(`${f.file}:${f.line} ${f.summary}`));\n```\n\nThe same schema works on **every** backend; only the fulfillment channel differs, and the runner picks it for you: Claude uses its `outputFormat`, Codex its strict `outputSchema`, while Pi, OpenCode, and eligible custom ACP agents receive a client-hosted `StructuredOutput` MCP tool when they advertise HTTP MCP support. Pi accepts stdio, Streamable HTTP, and SSE MCP servers. If no valid tool capture exists, Pi retains the runner\'s common prompt-embedded schema and validated final-text JSON fallback. In every channel the runner validates the value client-side (with type coercion) and re-prompts a bounded number of times before failing the call with non-recoverable `SCHEMA_NONCOMPLIANCE`.\n\nSchema authoring rules that keep all channels healthy:\n\n- Root must be an object; set `additionalProperties: false` and list every property in `required`.\n- Put a `description` on every field \u2014 descriptions are the per-field prompt.\n- Keep schemas structurally simple. Exotic keywords (`oneOf`, `patternProperties`, unusual `format`s, backreference regexes) are normalized or stripped on the wire for some backends \u2014 validation still enforces them client-side, which shows up as re-prompt churn. Prefer `anyOf`, `enum`, and plain types.\n- Keep free-text fields small (tens of lines). An oversized structured output can exhaust schema repair and fail the call.\n- Validation checks structure, not truth. Check load-bearing values in script code (for example, reject findings whose `file` is not in a known file list) before spending more agents on them.\n\n## The `meta` header\n\nEvery script must **begin** with `export const meta = {...}` as a plain object literal (no computed values \u2014 it is parsed from the source text before anything runs):\n\n```js\nexport const meta = {\n  name: "fix-flaky-tests",                        // required\n  description: "Find flaky tests and fix them",   // required\n  phases: [                                        // optional; one { title, detail?, model? } entry\n    { title: "Find", model: "opencode/zai/glm-5.2" },  // per phase() call, matched by exact title;\n    { title: "Fix" },                                  // a phase model is that phase\'s default\n  ],\n  model: "claude/sonnet",                          // optional run-wide default model\n  backends: { /* optional custom ACP agents \u2014 see "Custom ACP backends" */ },\n};\n```\n\nPer-agent model resolution order: explicit `agent({ model })` > `agent({ tier })` > the current phase\'s `model` > `meta.model` > the host session\'s default. So `meta.phases[].model` gives a whole phase a backend without repeating it on every call.\n\n## Fan-out: `parallel` and `pipeline`\n\n```js\n// parallel: an array of THUNKS (not promises!) run concurrently \u2014 a barrier that\n// resolves in input order. A failed slot resolves to null; filter before use.\nconst sweeps = (await parallel([\n  () => agent("Audit error handling in src/server", { label: "sweep:errors", schema: FINDINGS }),\n  () => agent("Audit input validation in src/api",  { label: "sweep:input",  schema: FINDINGS }),\n])).filter(Boolean);\n\n// pipeline: each item flows through the stages independently \u2014 NO barrier between\n// stages, so item A can be in stage 2 while item B is still in stage 1.\n// Stages receive (previousResult, originalItem, index).\nconst verified = (await pipeline(\n  sweeps.flatMap((s) => s.findings),\n  (f) => agent(`Adversarially verify this finding \u2014 try to refute it:\\n${JSON.stringify(f)}`,\n               { label: `verify:${f.file}`, schema: VERDICT }),\n  (verdict, f) => ({ ...f, real: verdict.real }),\n)).filter(Boolean).filter((f) => f.real);\n```\n\n**Default to `pipeline`** for multi-stage work. Add a `parallel` barrier only when the next stage needs *all* prior results at once: dedup across the full set, early-exit on a zero count, or prompts that compare "the other findings". The test is the **information dependency** \u2014 a barrier\'s cost is real, because the fastest worker idles for the slowest. All coordination lives in script code: agents cannot see each other, so never ask an agent to "check with the other reviewers" or "spawn helpers". Passing a promise instead of a thunk to `parallel` is a `TypeError` \u2014 wrap every call: `() => agent(...)`.\n\nFan-out also contends for the **working tree**, not just the concurrency limiter. Two agents running builds or test suites in the same checkout collide on build outputs, caches, and lockfiles, and concurrent `git fetch`es contend on the same `.git`. Give run-things agents `isolation: "worktree"` when the commits they must inspect are reachable from the run cwd\'s repository, or serialize them; fan out freely only the agents that just read.\n\nThe host caps concurrent agents per run (default 8); hand `parallel`/`pipeline` as many items as the task needs and let the limiter schedule them. The cap counts active agent attempts, not authored branches: queued branches begin as other attempts finish, and a branch that exhausts its timeout settles to `null` and frees its slot. `workflow(nameOrScript, args)` nests another workflow inline (one level deep, sharing this run\'s budget and limiter) \u2014 inline script strings always work; saved names resolve when the host serves a workflows folder (see the reference section below).\n\n## Failure semantics \u2014 design for `null`\n\n- A **recoverable** failure (timeout, empty output, transient execution error) is retried per the call\'s `retries` (default 0), then the call **resolves to `null`** \u2014 inside `parallel`/`pipeline` *and* as a bare `await agent(...)`. Null-check anything load-bearing, and set `retries: 1\u20132` on steps you can\'t afford to lose.\n- A host can settle one runaway in-flight call with MCP `{ action: "stop", runId, callIndex }` or SDK `manager.cancelAgentCall(runId, callIndex)`. The call resolves to `null` with `AGENT_CANCELLED`, skips every configured retry, and does not abort the run or its siblings. Its failed call record is not cached as a journal result, so a later resume runs that occurrence live.\n- A **non-recoverable** failure (schema never validated, script bug) throws and fails the run. You *may* `try/catch` around an `agent()` call to degrade gracefully \u2014 rethrow anything you can\'t meaningfully handle. In particular, **always rethrow pause-class errors** (`err.code === "PROVIDER_USAGE_LIMIT"` or `"AUTH_REQUIRED"`): they must propagate out of the script so the engine can pause the run resumably \u2014 swallowing one converts that pause into a fake, lossy completion.\n- A **provider quota wall, missing backend authentication, or opted-in durable checkpoint pauses a managed run instead of failing it** \u2014 the journal checkpoints and the host can resume after the budget refills, authentication completes, or a checkpoint decision is supplied. Direct `runner.run()` calls still receive the `AUTH_REQUIRED` error because they have no manager lifecycle.\n- Per-call knobs: `timeoutMs` and `retries`. A finite `timeoutMs` may shorten the host\'s run-level `agentTimeoutMs` ceiling; `null` or omission is uncapped only when the host supplied no ceiling. The timeout is total wall-clock time per attempt, and every retry gets a fresh clock.\n\n## Budgets and phases\n\n```js\nphase("Explore", { budget: 100_000 });   // soft per-phase token sub-budget\n// budget.total (null = unbounded) \xB7 budget.spent() \xB7 budget.remaining() (Infinity when unbounded)\n\nconst found = [];\nwhile (budget.total && budget.remaining() > 50_000 && found.length < 20) {\n  const r = await agent("Find one more edge case not in: " + JSON.stringify(found.map((f) => f.name)),\n                        { label: `edge:${found.length}`, schema: EDGE });\n  if (!r) break;\n  found.push(r);\n}\n```\n\nGuard budget-driven loops on `budget.total` being set \u2014 with no budget, `remaining()` is `Infinity` and only your own counters stop the loop. The run-level token budget and agent-count cap are hard: once exhausted, further `agent()` calls throw. `phase()` also groups agents in progress UIs and run logs; `log(msg)` (and `console.log`) append to the run log \u2014 narrate what matters, especially anything you drop or cap.\n\n## Built-in quality loops\n\nThese helpers spawn their own subagents (on the default model \u2014 hand-roll with `parallel` + `agent` when you want panel members on specific backends). Full signatures in the reference section below.\n\n| helper | shape | use for |\n|---|---|---|\n| `gate(produce, validate, { attempts })` | produce \u2192 validate \u2192 feed `feedback` back; return `{ ok, value, verdict, attempts }` | produce-until-a-reviewer-approves loops that need the final review evidence |\n| `retry(thunk, { attempts, until })` | bounded retry until `until(result)` holds | flaky single steps |\n| `verify(item, { reviewers, threshold, lens })` | N adversarial reviewers vote `real`/not | killing plausible-but-wrong findings |\n| `judgePanel(attempts, { judges, rubric })` | score candidates 0\u20131 against a rubric, return the best | picking among independent solutions |\n| `loopUntilDry({ round, key, consecutiveEmpty, maxRounds })` | repeat a round, dedup by `key`, stop when dry | unknown-size discovery (bugs, edge cases) |\n| `completenessCheck(args, results)` | one critic lists what\'s still missing | a final "what did we not cover?" pass |\n\nThe `gate` pattern, spelled out \u2014 note how the producer thunk threads the validator\'s feedback into a *fresh* agent\'s prompt (sessions have no memory):\n\n```js\nconst outcome = await gate(\n  (feedback, attempt) => agent(\n    `Implement the fix described here:\\n${JSON.stringify(plan)}\\n` +\n    (feedback ? `\\nA reviewer rejected attempt ${attempt}: ${feedback}\\nAddress every point.` : ""),\n    { label: `fix:${attempt + 1}`, model: "codex/gpt-5.6-sol" },\n  ),\n  (result) => agent(\n    `Run the test suite and review this change summary:\\n${result}\\n` +\n    `Return ok=true only if tests pass and the fix is correct; include the reviewed commit SHA.`,\n    { label: "gate-review", model: "claude/opus[1m]", schema: { type: "object", additionalProperties: false,\n      required: ["ok"], properties: { ok: { type: "boolean" }, feedback: { type: "string" },\n        commitSha: { type: "string" } } } },\n  ),\n  { attempts: 3 },\n);\nif (!outcome.ok) log(`reviewer never approved after ${outcome.attempts} attempts`);\nelse log(`reviewer approved commit ${outcome.verdict?.commitSha ?? "(unspecified)"}`);\n```\n\nFeedback is the producer\'s only context for the next attempt. Interpolate everything it needs, and name only files that provably exist.\n\n## Human gates: `checkpoint()`\n\n`checkpoint(promptText, options?)` is a zero-token, journaled human gate. With MCP elicitation (or a live SDK `confirm` callback) it waits for that reply; without a live channel, its default mode takes `default ?? true` immediately, so detached runs never hang.\n\n```js\nconst proceed = await checkpoint(`Apply this plan?\\n${JSON.stringify(plan, null, 2)}`, {\n  kind: "confirm",          // "confirm" | "input" | "select"\n  default: false,           // default headless mode takes this (or true)\n  // headless: "abort",     // abort when no live human is attached\n  // headless: "pause",     // or persist a resumable human-decision pause\n});\nif (!proceed) return { applied: false, plan };\n```\n\n`kind: "input"` resolves to free text, `kind: "select"` to one of `choices`. How the question reaches a human is the host\'s job (elicitation in the MCP server; `ExecOptions.confirm` in the SDK). With no live channel, `headless: "default"` (the default) takes `default ?? true`, `"abort"` aborts, and `"pause"` returns a managed run with `reason: "checkpoint_required"` plus non-secret `checkpointContext`. Resume the last mode with `checkpointReplies: { [context.callIndex]: decision }` or a live confirm. For `resumeFromRunId`, that key is the source context index; an unambiguous identity match may journal the injected answer at a shifted current index. Put a checkpoint before anything hard to reverse \u2014 applying diffs, pushing, publishing, or the first commit into a working copy the workflow did not create (`default: true` keeps detached runs moving).\n\n## Working directory, isolation, confinement\n\n- Every agent session runs in the run\'s base `cwd` unless the call narrows it: `agent({ cwd: "packages/api" })` (relative resolves against the base).\n- `isolation: "worktree"` runs the agent in a **throwaway git worktree** (`<repoRoot>/.agentprism/worktrees/\u2026`) so parallel agents can edit without colliding. The worktree and its branch are **always deleted when the call ends \u2014 an isolated agent\'s file edits are discarded**. Have isolated agents *return their work as data* (a unified diff, a file map, a report) and apply it in a later non-isolated step; use worktrees for experiments, builds, and verification, not for persistent edits. Outside a git repo, isolation degrades to the shared tree with a logged notice.\n- `resume: { filesystem: "read-only" }` is a deprecated compatibility annotation. It is not a runner mode and has no effect on replay; completed calls replay by journal correspondence whether they read or write. Use `mode`, tool policy, prompts, and worktrees when you actually need confinement.\n- `mode` requests an agent-advertised ACP session mode and is **strict** \u2014 an unsupported mode fails the call rather than running unconfined. Mode ids are backend-specific and drift with harness versions: read the advertised `mode` select from `npx @automatalabs/workflows config <harness>` or a validator report (Codex-family examples: `read-only`, `agent`; Claude-family advertises permission modes such as `plan` and `acceptEdits`; OpenCode via its mode option; Pi advertises thinking-level config rather than modes). Only set `mode` on calls whose `model` you also pin. Use read-only/plan modes for reviewers and auditors that must not write.\n- `agentType: "<name>"` binds a reusable subagent definition \u2014 a Markdown file at `<cwd>/.agentprism/agents/<name>.md` (project) or `~/.agentprism/agents/<name>.md` (user; project wins) whose frontmatter sets tool allow/deny lists, a model, and isolation, and whose body is the role prompt. An unknown name logs a warning and degrades to defaults.\n\n## Where a mutating workflow runs\n\nThe run\'s base `cwd` is the USER\'S checkout \u2014 the working copy they launched the host from. Treat it as borrowed: committing onto whatever branch is checked out, switching branches, or resetting it are defects unless the user asked for exactly that. A script that commits should verify its target workspace in a preflight step, or create its own workspace idempotently, and refuse on a mismatch rather than adapt. `isolation: "worktree"` is NOT such a workspace \u2014 it is per-call and throwaway. Note also that a throwaway worktree branches from the run cwd\'s repository: an isolated agent sees another agent\'s commits only when they are reachable there.\n\n## Wiring tools and inputs into a call\n\n- `mcpServers: [{ name, command, args: [], env: [] }]` attaches MCP servers to that agent\'s session \u2014 the portable way to hand any backend a capability (image generation, a browser, a ticket system). The agent sees the server\'s tools natively. Note `env` is a list of `{ name, value }` pairs (ACP shape), not an object map; HTTP/SSE servers use `{ type: "http", name, url, headers: [] }`.\n- `images: [...]` appends base64 image blocks to the prompt (backends without image support receive a bracketed text note instead).\n- `meta` / `promptMeta` pass generic ACP `_meta` through to `session/new` / `session/prompt` \u2014 the escape hatch for driving a custom agent\'s extension surface.\n- `keepSession: true` keeps a successful agent\'s ACP session re-openable after the run: the re-attach record (sessionId, backend, effective pool identity, cwd, reopen capabilities) lands in `WorkflowRunResult.agentSessions`, and the HOST can continue that conversation later via `runner.loadSession()`. Usage/auth pause failures are kept open automatically so managed resume can continue the interrupted occurrence. Scripts themselves never request reattach.\n\n### Custom ACP backends\n\nAny process that speaks ACP over stdio can serve `agent()` calls \u2014 an in-house browser-QA agent, an image generator, a domain-specific executor. Two ways in:\n\n1. **Host-registered** (preferred): the embedder passes `createAcpRunner({ backends: { browser: { command: "/abs/browser-acp" } } })`; the script just routes with `model: "browser"`.\n2. **Script-declared**: the script itself declares the backend in `meta.backends` \u2014 but declarations are **inert until the host approves them** (an elicitation in the MCP server; `allowScriptBackends` in the SDK), because they spawn commands on the host machine. Don\'t rely on them silently working.\n\n```js\nexport const meta = {\n  name: "checkout-qa",\n  description: "Implement, then QA the checkout flow in a real browser",\n  backends: {\n    browser: { command: "browser-acp", args: ["--headless"] },  // requires host approval\n  },\n};\n\nconst change = await agent("Implement the coupon-code field per the spec in docs/coupon.md.",\n                           { label: "implement" });              // default backend\nconst verdict = await agent(\n  `Open the app, walk through checkout with coupon SAVE20, and verify the discount line. Change summary:\\n${change}`,\n  { label: "qa", model: "browser",                               // the custom agent\n    schema: { type: "object", additionalProperties: false, required: ["passed"],\n              properties: { passed: { type: "boolean" }, notes: { type: "string" } } } },\n);\nreturn { change, qa: verdict };\n```\n\nStructured output works on custom backends through the same injected-tool/fallback ladder as OpenCode \u2014 no special-casing in the script.\n\n## Determinism and resume\n\nRuns are journaled: every `agent()` and `checkpoint()` result is recorded under a deterministic call index. A new run may reuse eligible results from a terminal source run. Uncertainty always means live execution.\n\n> **Resume rule:** replay is content-addressed and fail-to-live on correspondence: a completed call replays when its identity and input fingerprint match uniquely. Filesystem or world state never gates replay.\n\n- Direct `Date.now()`, `Math.random()`, and no-arg `new Date()` / `Date()` calls fail static validation. The realm also blocks aliased or computed forms at runtime; `new Date(isoString)` is fine. Pass timestamps and random seeds through `args`.\n- The replay identity of an `agent()` call hashes: the prompt, the resolved `model`, `mode` when set, `configOptions` when non-empty (sorted keys), `tier`, `phase`, `agentType`, the resolved agent definition, and `schema`. The resolved agent definition includes its tool allowlist and denylist, model, isolation, and body prompt \u2014 editing a definition invalidates the calls that use it.\n- A separate input fingerprint hashes: the resolved label, per-call `cwd`, resolved isolation, `keepSession`, `images`, `mcpServers`, `meta`, `promptMeta`, and the approved script-backend digest.\n- Host `agentTimeoutMs`, `agentRetries`, and `concurrency`, plus per-call `timeoutMs` and `retries`, are operational bounds. They enter neither hash and may change freely on resume. A new run resolves them from its own request; it does not inherit the source values.\n- `args` is not hashed directly. New args that only raise a loop cap leave earlier identities unchanged, so those calls can replay. New args that change a prompt, model selection, phase, schema, call order, or runner-visible input make the affected calls run live. Unchanged independent calls may still replay.\n- Matching tries a unique exact `(kind, call path, identity hash)` row first (`"path-hash"`), then a unique `(kind, identity hash, input fingerprint)` row, so an unchanged call can replay as `"unique-hash"` after insertions or deletions. Source and current input fingerprints must be equal. Duplicate identities, duplicate content, consumed candidates, missing facts, and empty schema-less results run live. The engine never guesses by source order or occurrence.\n- Source admission requires: exact `cwd`, compatible call-path/input/checkpoint fingerprint formats, complete call/journal/allocation metadata, and a valid manifest and seed. Git HEAD and dirty digest, `environmentKey`, captured environment values, Node/V8, and producing engine version are diagnostics only. Environment differences may appear in `replayEligibility.provenanceChanges`; they never gate admission or matching.\n- A completed writer replays exactly like a reader. A live call, nested workflow, host checkpoint callback, or degraded worktree does not clear unrelated candidates. Nested child calls run live \u2014 they are outside the parent\'s journal \u2014 while matching root calls around them still replay. The engine does not reproduce file writes; a later live agent navigates the world it finds.\n- Replay preserves budget-driven control flow: a cached call adds its source logical debit to `budget.spent()`/`remaining()`, and zero current provider usage. Replayed session records keep their backend and session identity, rebound to the current call index, label, and phase.\n- A root call interrupted by `PROVIDER_USAGE_LIMIT` or `AUTH_REQUIRED` can continue its recorded session on either resume API. Continuation requires: the exact call index, identity hash, complete input fingerprint, non-worktree isolation, identical existing cwd, a coherent recorded session, and the runner\'s current backend/`poolKey`/reopen gates. A successful continuation finishes the unfinished turn and charges only its usage delta. Every failed gate runs fresh, and `fallbacks` records the reopen method or the exact skip reason. No script option controls this.\n- Completed checkpoint results replay when the identity and the `default`/`headless`/`timeoutMs` fingerprint match \u2014 headless results included. `checkpointReplies` keys always name the checkpoint index in the source run. A moved reply can follow intact prior correspondence; after a live divergence it must reach the exact recorded call site, so a different same-text branch cannot consume it.\n- `resumePolicy: "positional"` is a migration escape hatch for index/prefix matching. It cannot bypass format, metadata, manifest, cwd, or input checks. Marker-less, manual, and same-ID legacy journals keep historical hash-only positional behavior. Input formats below 2 use the `inputs-format-legacy` positional bridge and are rewritten under the current format on the next hop. A current-format crash snapshot with a valid identity manifest uses identity matching even without terminal-environment capture.\n- `label`, `cwd`, `mcpServers`, `images`, `meta`, `promptMeta`, and `keepSession` are not identity-hashed: changing one does not invalidate an ordinary replay. They are in the input fingerprint: changing one rejects continuation of an interrupted turn, and that occurrence runs fresh. To force a completed call to run again, change a hashed field \u2014 normally the prompt.\n- Keep call order deterministic. Derive iteration from `args` and prior agent results, never from ambient state.\n\nEvery `resumeFromRunId` result has a bounded `replayEligibility` summary. Background admission, foreground completion, both await shapes, and inspect expose the same fields: strategy, predicted replayable-prefix length, observed replayed prefix and counts, and the first non-replay when known. Active correspondence reasons include `strategy-live`, `positional-miss`, `positional-suffix`, `not-recorded`, `path-missing`, `inputs-missing`, `inputs-changed`, `ambiguous-identity`, `ambiguous-content`, `candidate-consumed`, `empty-output`, `worktree-degraded`, `seed-persistence-error`, and `resume-fatal-latch`. Older reason literals stay exported only so historical journals parse. Engine and input-format versions and environment provenance ride along as diagnostics.\n\nAn all-live outcome means correspondence could not be established \u2014 not that the world changed. Missing resume metadata, incompatible format literals, or an invalid manifest or seed disable new-format replay. If any source row lacks a captured path or input fact (possible past the raw-frame cap, or with a non-strict-JSON `meta` value), the whole source is `"manifest-invalid"`: dropping the row could make an ambiguous sibling look unique.\n\n### Worked resume \u2014 raise a loop cap\n\nThe following workflow (shipped as `examples/resume-loop-cap.workflow.js`) requires eight reviews but lets the caller cap how many are attempted in one run:\n\n```js\nexport const meta = {\n  name: "resume-loop-cap",\n  description: "Run expensive review rounds up to an args-controlled cap",\n  phases: [{ title: "Review" }],\n};\n\nconst input = args && typeof args === "object" && !Array.isArray(args) ? args : {};\nconst numericCap = Number(input.maxRounds);\nconst maxRounds = Number.isInteger(numericCap) && numericCap > 0 ? numericCap : 8;\n\nphase("Review");\nconst rounds = [];\nfor (let i = 0; i < maxRounds; i += 1) {\n  rounds.push(\n    await agent(\n      `Review round ${i + 1}: inspect the repository and report unresolved release blockers.`,\n      { label: `review:${i + 1}`, phase: "Review" },\n    ),\n  );\n}\n\nif (maxRounds < 8) throw new Error(`review cap ${maxRounds} reached before 8 rounds`);\nreturn { rounds };\n```\n\nRun it with `args: { "maxRounds": 6 }`. Then send the same content (via `script`, or the absolute `scriptPath` you edit) with `args: { "maxRounds": 8 }` and the first result\'s `runId` as `resumeFromRunId`. Rounds 1\u20136 replay for zero current provider tokens; only rounds 7\u20138 run live, because the cap controls call count but is not interpolated into the round prompt. If every round prompt included `maxRounds`, all eight identities would change and all would run live. Resume always states its content; a bare `resumeFromRunId` never silently reuses the old script.\n\nGive repeated calls stable, descriptive labels and narrate decisions with `log()` \u2014 inspection by `labelGlob` then turns a pause or failure into a diagnosis instead of a guess.\n\n### Kill, patch, resume\n\nStop the live run with `{ action: "stop", runId }`. The returned `aborted` snapshot is the durable acknowledgement: resume is safe immediately, and a further await adds nothing. Edit the file. Start a new run with its absolute `scriptPath` and `resumeFromRunId`. Every completed call whose recorded identity and input fingerprint correspond replays, regardless of filesystem or environment drift. Read `replayEligibility` and the full `resumeReport` for the per-call decisions. A repeated stop of a terminal run is a successful no-op.\n\nRegistration, the per-action contracts, background collection, and the events resource are covered in the **Running workflows** section above. Resume a durable checkpoint pause by re-sending the script with `resumeFromRunId` and `checkpointReplies` keyed by the source run\'s `checkpointContext.callIndex`.\n\n## Worked example \u2014 cross-vendor build with every major primitive\n\n```js\nexport const meta = {\n  name: "feature-build",\n  description: "Plan, gate on approval, implement, cross-vendor review, fix until green",\n  phases: [{ title: "Plan" }, { title: "Implement" }, { title: "Review" }],\n};\n\nconst PLAN = { type: "object", additionalProperties: false, required: ["steps", "risks"],\n  properties: {\n    steps: { type: "array", items: { type: "string", description: "One concrete implementation step" } },\n    risks: { type: "array", items: { type: "string" } } } };\nconst VERDICT = { type: "object", additionalProperties: false, required: ["ok"],\n  properties: { ok: { type: "boolean" },\n                feedback: { type: "string", description: "Required when ok=false: concretely what to change" } } };\n\nphase("Plan");\nconst plan = await agent(\n  `Study this repo, then write an implementation plan for: ${args.feature}. Keep steps concrete.`,\n  { label: "plan", model: "opencode/zai/glm-5.2", schema: PLAN },\n);\n\nconst approved = await checkpoint(\n  `Implement "${args.feature}" with this plan?\\n- ${plan.steps.join("\\n- ")}\\nRisks: ${plan.risks.join("; ")}`,\n  { kind: "confirm", default: true },\n);\nif (!approved) return { implemented: false, plan };\n\nphase("Implement");\nconst outcome = await gate(\n  (feedback, attempt) => agent(\n    `Implement: ${args.feature}\\nPlan:\\n- ${plan.steps.join("\\n- ")}\\n` +\n    `Run the project\'s tests before finishing and report results.` +\n    (feedback ? `\\n\\nReviewer feedback on attempt ${attempt}:\\n${feedback}\\nAddress every point.` : ""),\n    { label: `implement:${attempt + 1}`, model: "codex/gpt-5.6-sol", retries: 1 },\n  ),\n  async (report) => {\n    if (!report) return { ok: false, feedback: "implementation agent produced no result" };\n    phase("Review");\n    const reviews = (await parallel([   // two reviewers on different vendors\n      () => agent(`Review the working-tree diff for correctness. Implementer\'s report:\\n${report}`,\n                  { label: "review:correctness", model: "claude/opus[1m]", schema: VERDICT }),\n      () => agent(`Review the working-tree diff for regressions and missing tests. Report:\\n${report}`,\n                  { label: "review:coverage", model: "opencode/zai/glm-5.2", schema: VERDICT }),\n    ])).filter(Boolean);\n    const rejections = reviews.filter((r) => !r.ok);\n    return rejections.length\n      ? { ok: false, feedback: rejections.map((r) => r.feedback).join("\\n"), reviews }\n      : { ok: true, reviews };\n  },\n  { attempts: 3 },\n);\n\nreturn { implemented: outcome.ok, attempts: outcome.attempts, reviewVerdict: outcome.verdict, plan };\n```\n\n(The planner would ideally run read-only, but mode ids are backend-specific \u2014 this call routes to OpenCode, so it leaves `mode` unset rather than guessing; a Claude-routed planner could safely say `mode: "plan"`.)\n\n## Worked example \u2014 fully backend-agnostic audit\n\nNo `model` anywhere: this script runs unchanged on whatever backend the host defaults to.\n\n```js\nexport const meta = {\n  name: "edge-case-audit",\n  description: "Exhaustively hunt edge-case bugs in a target dir, verify each, report gaps",\n  phases: [{ title: "Hunt" }, { title: "Verify" }],\n};\n\nconst BUGS = { type: "object", additionalProperties: false, required: ["bugs"],\n  properties: { bugs: { type: "array", items: { type: "object", additionalProperties: false,\n    required: ["file", "scenario"], properties: {\n      file: { type: "string", description: "Repo-relative path you actually opened" },\n      scenario: { type: "string", description: "Concrete input/state \u2192 wrong behavior" } } } } } };\n\nphase("Hunt");\nconst seen = [];   // what earlier rounds reported, threaded into each new prompt\nconst candidates = await loopUntilDry({\n  round: async (i) => {\n    const r = await agent(\n      `Round ${i + 1}: find edge-case bugs in ${args.target} not already in this list:\\n` +\n      JSON.stringify(seen) + `\\nOnly report what you can ground in code you read.`,\n      { label: `hunt:${i + 1}`, schema: BUGS },\n    );\n    const bugs = r ? r.bugs : [];\n    seen.push(...bugs);\n    return bugs;      // loopUntilDry dedups these by `key` across rounds\n  },\n  key: (b) => `${b.file}:${b.scenario}`,\n  consecutiveEmpty: 2,\n  maxRounds: 8,\n});\n\nphase("Verify");\nconst confirmed = (await pipeline(\n  candidates,\n  (bug) => verify(bug, { reviewers: 3, threshold: 0.66, lens: ["correctness", "reproducibility"] }),\n  (v, bug) => (v.real ? bug : null),\n)).filter(Boolean);\n\nconst gaps = await completenessCheck(args, confirmed);\nlog(`${confirmed.length}/${candidates.length} confirmed; complete=${gaps.complete}`);\nreturn { confirmed, missing: gaps.missing ?? [] };\n```\n\n## Full-scale example scripts\n\nWhen the inline examples above aren\'t enough, study the complete, validated scripts that ship with the published authoring skill:\n\n- [`repo-triage.workflow.js`](https://github.com/VikashLoomba/agentprism-workflows/blob/main/skills/agentprism-workflow-authoring/examples/repo-triage.workflow.js) \u2014 an autonomous cross-vendor repo triage and the broadest support-API tour: `pipeline` with no inter-stage barrier, a cross-vendor verification panel, `gate()` where writer and reviewer are different vendors, nesting a saved workflow by name, `completenessCheck()`, budget headroom reservation, string-form `args` hardening, path guards on schema outputs, and pause-class error rethrow.\n- `quick-wins.workflow.js` (included in full at the end of this document) \u2014 a small hunter that runs standalone *or* nested: `loopUntilDry()` with per-round vendor rotation, dedup threading via a `seen` list, and an in-round budget floor (nested runs share the parent\'s budget).\n- [`resume-loop-cap.workflow.js`](https://github.com/VikashLoomba/agentprism-workflows/blob/main/skills/agentprism-workflow-authoring/examples/resume-loop-cap.workflow.js) \u2014 content-addressed replay: run with a low `maxRounds`, resume with a higher one; unchanged rounds replay for zero tokens (worked through in Determinism and resume).\n\n[`examples/README.md`](https://github.com/VikashLoomba/agentprism-workflows/blob/main/skills/agentprism-workflow-authoring/examples/README.md) maps each script to what it teaches.\n\n## Validate before you run\n\nThe SDK ships a validator that costs **zero tokens** \u2014 always run it on a script you just wrote or edited:\n\n```bash\nnpx @automatalabs/workflows validate my-workflow.js --args \'{"target":"src/"}\'\n```\n\nIt does three passes. First, a **static parse**: the `meta` literal, syntax, and direct\nnondeterministic call expressions. Second, a **dry run**: the engine runs the script\'s control flow\nin its realm, with every `agent()` call served by a mock backend that fabricates\nschema-conforming results \u2014 no real agent runs, and validation is not an execution of the\nworkflow. Third, one no-prompt session for each distinct routed `{ backend, model\n}` pair. The third pass spends no tokens, selects each authored call model, and echoes that pair\'s\nmodel-specific config-options table in the report. Read that table before picking `configOptions`\nvalues; unknown ids, bad select values, wrong value types, and the reserved `"model"` key fail\nvalidation with the call label, authored value, and alternatives. If a routed pair cannot spawn,\nauthenticate, select its model, or open a session, validation emits one warning, marks it\n`probed:false`, skips only that pair\'s checks, and stays valid \u2014 the offline degradation behavior. A\nmock live confirm answers checkpoints with `default ?? true`, so `headless: "pause"` dry-runs\ncleanly; `headless: "abort"` warns because a truly unattended run would abort. Script-declared\n`meta.backends` are treated as approved. The report lists every call with its backend attribution,\nplus warnings for undeclared phases, `headless: "abort"` checkpoints, and zero agent calls.\n(Option-domain clamping rules are in Backends and structured output; the full flag table and\nmock-answer grammar are in `reference.md`.)\n\nThe default fabricator returns `true` for every boolean. Do not accept that all-true path as proof that a convergence loop works: script its control labels with `--mock-answers` or a reusable `--mock-answers-file`. Use a finite `$sequence` such as reject-then-approve so validation executes the revision branch and proves the loop stops; the report identifies every consumed and unused fixture without printing answer bodies.\n\nSave reusable mock answers beside the workflow file (`<name>.mock.json`). When a default-fabrication dry run leaves declared phases unexecuted, your guard branches fired \u2014 script the mocks that reach past them instead of shrugging at the warnings.\n\nExit codes: `0` valid \xB7 `1` parse failure \xB7 `2` dry-run or config-option failure. The full flag table, mock-answers grammar, and limits are in `reference.md`.\n\nThe third pass\'s table is also available standalone \u2014 before any script exists \u2014 as validate\'s sibling command: `npx @automatalabs/workflows config [harness ...]` (default: every routable harness; `--json`; exit `1` when a probe fails). Use `config` while authoring to pick values; validate\'s copy then confirms the script you wrote against the same live catalog.\n\nIf the script nests saved workflows by name (`workflow("review-pr")`), pass the folder so names resolve \u2014 and the positional itself may then be a name: `npx @automatalabs/workflows validate review-pr --workflows-dir ./workflows`. A green dry run proves structure, not judgment \u2014 prompts and schemas still deserve review.\n\n---\n\n# Workflow script reference\n\nExhaustive tables for the AgentPrism workflow script DSL. The guide above covers authoring; this section is the lookup companion. Everything here is verified against `@automatalabs/workflow-engine` / `@automatalabs/acp-agents` as shipped with `@automatalabs/workflows`.\n\n## `agent(prompt, options?)` \u2014 full option table\n\nReturns the agent\'s final assistant text, or the schema-validated object when `schema` is set. Resolves to `null` when a *recoverable* failure survives all retries.\n\n| option | type | meaning |\n|---|---|---|\n| `label` | `string` | Display/telemetry name; also stamped on every live ACP event for this call. Always set it. Not part of the resume hash. |\n| `phase` | `string` | Assign this call to a phase explicitly (needed inside concurrent stages where the global `phase()` state would race). |\n| `schema` | JSON Schema object | Structured output. Plain object literal only \u2014 no schema builders exist in the realm. Part of the resume hash. |\n| `model` | `string` | Model spec: optional registered harness prefix plus a verbatim id, or a backend-only name. See [Model specs & routing](#model-specs--routing). Part of the resume hash. |\n| `tier` | `"small" \\| "medium" \\| "big"` | Coarse tier resolved from host config; beats phase/meta model, loses to explicit `model`. Part of the resume hash. |\n| `mode` | `string` | ACP session mode id advertised by the selected backend. **Strict**: unsupported/unadvertised ids fail the call (never silently unconfined). Ids are backend-specific and drift with harness versions \u2014 read the advertised `mode` select from the config probe or a validator report (Codex-family examples: `read-only`, `agent`, `agent-full-access`; Claude-family advertises permission modes such as `plan`, `acceptEdits`, and `dontAsk`). Part of the resume hash when set. |\n| `configOptions` | `Record<string, string \\| boolean>` | Exact ACP session option ids and authored values. Applied in ascending id order after model and before the prompt, with no aliases or coercion. `"model"` is reserved for the dedicated `model` field. Part of the resume hash only when non-empty, with sorted keys. Read the advertised-options table first (`agentprism-workflows config <harness>`, or any validate report) before choosing values. |\n| `agentType` | `string` | Bind a named subagent definition (tools allow/deny, model, isolation, role prompt). See [agentType definitions](#agenttype-definitions). Part of the resume hash. |\n| `isolation` | `"worktree"` | Run in a throwaway git worktree branched from the run cwd. **Always removed (worktree + branch) when the call ends** \u2014 edits are discarded; return work as data. Degrades to the shared tree outside a git repo (logged). |\n| `resume` | `{ filesystem: "read-only" }` | Deprecated compatibility annotation. It is recorded as legacy diagnostic provenance, is not sent to the runner or hashed, and has no effect on replay. New scripts should omit it. |\n| `cwd` | `string` | Per-session working directory; relative resolves against the run\'s base cwd. Overridden by worktree isolation. Not hashed. |\n| `timeoutMs` | `number \\| null` | Total wall-clock cap for each attempt. A finite value may tighten a finite host `agentTimeoutMs` ceiling but cannot raise or disable it. With no host ceiling, a finite value applies and `null`/omitted is uncapped. |\n| `retries` | `number` | Retries after *recoverable* failures (default 0, host-overridable). Exhausted retries \u21D2 the call resolves `null`. |\n| `mcpServers` | `McpServerConfig[]` | MCP servers attached to this session. Stdio shape: `{ name, command, args: [], env: [{ name, value }] }` (`args`/`env` required, `env` is name/value pairs, not a map); `{ type: "http" \\| "sse", name, url, headers: [] }` also accepted. Not hashed. |\n| `images` | `PromptImage[]` | Base64 image blocks appended to the prompt; backends without image support get a bracketed text note. Not hashed. |\n| `meta` | `object` | ACP `_meta` merged into `session/new` \u2014 session-scoped extension passthrough (pairs with custom backends). Not hashed. |\n| `promptMeta` | `object` | ACP `_meta` merged into `session/prompt` \u2014 turn-scoped passthrough. Backend-computed keys win on conflict. Not hashed. |\n| `keepSession` | `boolean` | Skip release-time best-effort `session/close`; the non-secret re-attach record lands in `WorkflowRunResult.agentSessions` for host-side `loadSession()` / `resumeSession()`. Usage/auth pause failures are kept open automatically for managed continuation. Not identity-hashed; included in the input fingerprint. |\n\nThe timeout clock measures the whole attempt, including backend startup, model/config setup, tool\nwork, and streamed output; it is not an idle timer. Each retry starts a fresh clock, so the maximum\ntimeout envelope is `(retries + 1) \xD7 resolved timeoutMs` (retries are clamped to 3). An exhausted\ntimeout is recoverable `AGENT_TIMEOUT`: the call resolves to `null`, releases its concurrency slot,\nand asks the ACP session to cancel. A session that keeps running after the cancellation grace is\nclosed where supported and its pooled child is recycled.\n\nEvery new run, including one admitted with `resumeFromRunId`, resolves host limits from that run\'s\nrequest. It does not inherit `agentTimeoutMs`, retries, concurrency, agent-count, or token-budget\nvalues from its source, so pass every operational bound the resumed execution should use.\n\n## Model specs & routing\n\nA `model` string is resolved solely from its first segment, then delegated to the harness:\n\n| spec shape | routes to | notes |\n|---|---|---|\n| *(omitted)* | host default backend | `AGENTPRISM_DEFAULT_BACKEND` (`claude` \\| `codex` \\| `opencode` \\| `pi` \\| custom name; default `claude`), session default model. Most portable. |\n| `claude`, `codex`, `opencode`, `pi`, or `<custom-name>` | that registered harness | Backend-only: no model config call; the harness default remains active. |\n| `claude/<id>`, `codex/<id>`, `opencode/<id>`, `pi/<id>`, or `<custom-name>/<id>` | that registered harness | Match the first segment ASCII-case-insensitively and strip exactly one segment. Custom names take priority on collision. The remaining `<id>` is sent verbatim, including further `/` characters. For Pi, that remainder is its `<provider>/<model-id>` and Pi preserves any further slashes in the model id. |\n| any other string, including `anthropic/\u2026`, `openai/\u2026`, bare `opus`, or bare `gpt-\u2026` | host default backend | The **entire** authored string is sent verbatim; these are not routing aliases. |\n\nSelection is a single `session/set_config_option` with `configId: "model"` and the exact remaining string. There is no catalog matching, case folding, normalization, bracket parsing, nearest-neighbor selection, sibling effort/Fast option driving, retry, or echo verification. Brackets, dots, and provider-style prefixes are ordinary model-id characters.\n\nWhatever the harness returns is the outcome. A rejection follows the existing agent-error path with no resolution-specific code or model fallback event. `onModelFallback` and `WorkflowRunResult.fallbacks` remain public compatibility surfaces; model resolution does not emit entries, while pause recovery emits `kind: "continuation"` reattach/skip notices.\n\n## Structured output channels\n\nOne author API (`schema`), four fulfillment paths \u2014 chosen automatically per backend:\n\n| backend | channel |\n|---|---|\n| Claude | native `outputFormat`, schema normalized to Anthropic\'s structured-outputs subset (e.g. `oneOf` \u2192 `anyOf`; unsupported keywords/formats stripped on the wire) |\n| Codex | native strict `outputSchema` (OpenAI strict subset normalization) |\n| Pi | a client-hosted `StructuredOutput` MCP tool injected when the agent advertises HTTP MCP support; common prompt-embedded schema and validated final-text JSON fallback |\n| OpenCode / custom ACP | a client-hosted **`StructuredOutput` MCP tool** injected into the session when the agent advertises HTTP MCP support (an agent may show it as `structured_output_StructuredOutput`); otherwise prompt-embedded schema + JSON parse of the final message. Custom backends can opt out of tool injection with `structuredOutputTool: false`. |\n\nPi accepts stdio, Streamable HTTP, and SSE MCP servers; ACP-transport MCP hosting remains client-side.\n\nIn every channel the runner coerces + validates client-side and re-prompts a bounded number of times; the final miss fails the call with non-recoverable `SCHEMA_NONCOMPLIANCE`. Constraints stripped from the wire are still enforced client-side \u2014 an exotic schema keyword shows up as re-prompt churn, so keep schemas simple.\n\n## DSL globals \u2014 complete signatures\n\n```\nagent(prompt, options?)                    \u2192 Promise<string | object | null>\nparallel(thunks)                           \u2192 Promise<results[]>   // barrier; input order; failed slot = null\npipeline(items, ...stages)                 \u2192 Promise<results[]>   // no inter-stage barrier; stage(prev, original, index); failed item = null\nworkflow(nameOrScript, args?)              \u2192 Promise<unknown>     // one nesting level; names resolve from the host\'s workflows folder, inline scripts always work\ngate(thunk, validator, { attempts = 3 })   \u2192 { ok, value, verdict, attempts }\n    // thunk(feedback, attempt); validator(result) \u2192 { ok, feedback?, ... } | boolean | null (may be async / an agent call)\nretry(thunk, { attempts = 3, until? })     \u2192 last result           // thunk(attempt); stops early when until(result)\nverify(item, { reviewers = 2, threshold = 0.5, lens? })\n    \u2192 { real, realCount, total, votes: [{ real?, reason? }] }\n    // N adversarial reviewers prompted to REFUTE; lens (string | string[]) rotates focus per reviewer\njudgePanel(attempts, { judges = 3, rubric = "overall quality and correctness" })\n    \u2192 { index, attempt, score, judgments }  // mean 0\u20131 score per candidate; stable tie-break by index\nloopUntilDry({ round, key = JSON.stringify, consecutiveEmpty = 2, maxRounds = 50 })\n    \u2192 unique items[]   // round(i) returns items; stops after N dry rounds; budget exhaustion returns the partial result\ncompletenessCheck(taskArgs, results)       \u2192 { complete, missing?: string[] }\ncheckpoint(promptText, options?)           \u2192 Promise<reply>       // journaled human gate; zero tokens\nphase(title, { budget? })                  \u2192 void                 // soft per-phase token sub-budget\nlog(message)                               \u2192 void                 // console.log/info/warn/error route here too\nargs                                       // the host-provided input value, verbatim\ncwd                                        // the run\'s base working directory (string); process.cwd() returns it too\nbudget.total | budget.spent() | budget.remaining()\n```\n\nFor `gate()`, `value` is the final producer result and `verdict` is the exact last completed\nvalidator return, including any extra structured fields. `{ ok: true }` and bare `true` pass;\n`{ ok: false, feedback? }`, bare `false`, and `null` reject. Only object feedback is threaded into\nthe next producer attempt. A producer result of `null` is still passed to the validator. Producer\nor validator exceptions propagate immediately, so no partial gate result is returned and no later\nattempt runs. An explicit unsupported `undefined` validator return is a rejection represented as\n`verdict: null`. If the script returns the gate result, its complete verdict is persisted and may\nreach the host; keep evidence concise and never put credentials or other secrets in verdict data.\n\n`verify`, `judgePanel`, and `completenessCheck` spawn their subagents on the run\'s default model \u2014 hand-roll with `parallel` + `agent` to pin panel members to specific backends.\n\n## `checkpoint()` options\n\n| option | type | meaning |\n|---|---|---|\n| `kind` | `"confirm" \\| "input" \\| "select"` | Reply shape: boolean-ish / free text / one of `choices`. Affects the journal hash and the host UI widget. |\n| `choices` | `string[]` | For `kind: "select"`. |\n| `default` | `unknown` | Reply taken in the default headless mode \u2014 journaled like a real reply. Defaults to `true`. |\n| `headless` | `"default" \\| "abort" \\| "pause"` | No live channel: `"default"` takes `default ?? true`, `"abort"` aborts, and `"pause"` creates a persisted `checkpoint_required` pause. Default `"default"`. |\n| `timeoutMs` | `number` | Deadline for the interactive prompt. |\n\nThe host supplies the live human channel (elicitation in the MCP server; `ExecOptions.confirm` in the SDK), and that channel wins even when `headless: "pause"` is declared. A durable pause carries non-secret `checkpointContext`; resume with `ExecOptions.checkpointReplies: { [context.callIndex]: decision }` or attach a live channel. On a new `resumeFromRunId` execution, reply keys always name indexes in the **source** recording; identity matching may inject that decision at a shifted current index. Completed host and headless checkpoint results both replay when identity and the checkpoint-options fingerprint over `default`, `headless`, and `timeoutMs` match. A changed option or ambiguous match runs fresh. Detached runs never pause for a checkpoint unless the author opts into `"pause"`.\n\n## Error codes (`WorkflowError.code`)\n\n| code | recoverable | engine behavior |\n|---|---|---|\n| `AGENT_TIMEOUT` | yes | Total wall-clock attempt cap exhausted. Every retry gets a fresh clock; after the final attempt the call resolves `null`, and ACP cancel escalates to close/recycle when the turn does not stop. |\n| `AGENT_CANCELLED` | yes | The host selected this in-flight call for cancellation. It resolves `null` immediately through an engine race, skips retries, leaves the run live, and is recorded as a failed call rather than a replayable journal result. |\n| `AGENT_EMPTY_OUTPUT` | yes | No assistant text on a schema-less call; same retry-then-`null`. |\n| `AGENT_EXECUTION_ERROR` | yes* | Generic agent failure (*refusal/truncation variants are non-recoverable). |\n| `SCHEMA_NONCOMPLIANCE` | no | Structured output never validated after the re-prompt ladder. Halts the run (catchable in-script). |\n| `PROVIDER_USAGE_LIMIT` | no | Quota/rate wall \u2014 the run **pauses** (journaled, resumable), with the provider\'s reset hint. |\n| `TOKEN_BUDGET_EXHAUSTED` | no | Run (or phase) token cap hit; further `agent()` calls throw. |\n| `AGENT_LIMIT_EXCEEDED` | no | `maxAgents` cap hit. |\n| `AUTH_REQUIRED` | no | Backend needs authentication. `WorkflowManager` returns a resumable pause with `reason: "auth_required"` and redacted `authContext`; a direct runner throws. The host completes auth before resuming/retrying. |\n| `CHECKPOINT_REQUIRED` | no | `headless: "pause"` reached without a live channel. `WorkflowManager` returns `reason: "checkpoint_required"` plus non-secret `checkpointContext`; resume with `checkpointReplies` or live confirm. |\n| `SCRIPT_VALIDATION_ERROR` | no | Script failed parse/validation (bad meta, nondeterministic API, bad `meta.backends` shape). |\n| `SCRIPT_ERROR` | no | The script itself crashed (uncaught throw, floated rejection). |\n| `WORKFLOW_ABORTED` | \u2014 | Real cancellation (pause/stop/host signal) \u2014 never used for crashes. |\n\n`loopUntilDry` absorbs `TOKEN_BUDGET_EXHAUSTED` / `AGENT_LIMIT_EXCEEDED` from its rounds and returns the partial result; everywhere else those propagate.\n\n## Determinism & the resume journal\n\n> **Resume rule:** replay is content-addressed and fail-to-live on correspondence: a completed call replays when its identity and input fingerprint match uniquely. Filesystem or world state never gates replay.\n\nThe guide section **Determinism and resume** carries the full semantics: what each hash contains, matching, admission, continuation of interrupted calls, and checkpoint replay. Wire-level specifics for lookup:\n\n- Each `agent()` result is journaled under a monotonic call index and a SHA-256 identity hash. The canonical identity fields, in order, are `prompt`, resolved `model`, `mode` only when set, `configOptions` only when non-empty, `tier`, `phase`, `agentType`, resolved `agentDef`, and `schema`. Config-option keys are sorted before serialization. Missing fields other than `mode` and `configOptions` serialize as `null`; an unset `mode` and an unset/empty `configOptions` key are omitted for compatibility with older journals.\n- `agentDef` is the resolved definition\'s tools, disallowed tools, model, isolation, and body prompt. Changing a named definition therefore invalidates its call even when the `agentType` name is unchanged.\n- The legacy `resume: { filesystem: "read-only" }` annotation has no effect on admission or matching. Writers, readers, worktree calls, and unannotated calls follow the same journal rule.\n- `resumePolicy: "positional"` requests index/prefix correspondence but cannot bypass new-format format, metadata, manifest, cwd, or input checks. Marker-less journals and permanently marked manual/same-run legacy resumes retain historical hash-only positional behavior. Sources below input format 2 use `inputs-format-legacy`. Ancestor-scoped rows carried by a \u22640.23 resume hop replay only while that ancestor is still persisted; engine-minted nested scopes and deleted ancestor scopes stay live.\n- There is no `require`, `import`, Node API, or network API in the realm. `Date.now()`, `Math.random()`, and no-arg `new Date()` / `Date()` fail static validation; aliased or computed forms are blocked at runtime; `new Date(value)` works.\n\nEvery new-run resume exposes `replayEligibility` on admission, polling, inspection, and the terminal result. It reports strategy, predicted/observed replayable prefix and counts, first non-replay/reason/detail, engine/input-format diagnostics, non-gating runtime/environment `provenanceChanges`, and non-gating operational changes; `resumeReport` retains the complete terminal per-call correspondence.\n\nAn all-live outcome is expected when correspondence cannot be established, not when the world changed. Missing resume metadata, incompatible format literals, or an invalid manifest/seed can disable reuse. A new-format source containing any result row without a captured call path/input fact\u2014possible with a call stack deeper than the raw-frame cap or a non-strict-JSON `meta` value\u2014is source-wide `"manifest-invalid"`; excluding the row could make an ambiguous sibling look unique. Format-1 bytes are never reinterpreted; they enter the positional bridge and replayed rows are recorded under format 2.\n\nAn args-controlled cap is the useful case: a cap that changes how many calls are reachable, but\ndoes not appear in an earlier call\'s prompt, lets those calls replay on resume. The worked example\nlives in the determinism-and-resume guide document and ships as\n`examples/resume-loop-cap.workflow.js`. This changed-args pattern is specific to new-run entry\npoints that accept current args with `resumeFromRunId`. The MCP `workflow` tool does, as does\n`WorkflowManager.runSync(script, newArgs, { resumeFromRunId })`. MCP resume always requires\nexplicit content; a bare `resumeFromRunId` is invalid. `WorkflowManager.resume(runId)` is a\ndifferent same-ID recovery API: it reloads the persisted original script/args and permanently uses\nlegacy positional replay semantics, while the independent default-on channel may still continue an\neligible usage/auth-interrupted live call.\n\n## <a name="custom-backends-metabackends"></a>Custom backends \u2014 `meta.backends`\n\n```js\nexport const meta = {\n  name: "\u2026", description: "\u2026",\n  backends: {\n    browser: {\n      command: "browser-acp",          // required: executable (absolute or on PATH)\n      args: ["--headless"],            // default []\n      env: { BROWSER_PROFILE: "qa" },  // merged OVER the child\'s inherited env \u2014 per-backend secrets go here\n      sessionMeta: { viewport: "desktop" },  // static ACP _meta on every session/new (per-call `meta` merges over it)\n      structuredOutputTool: true,      // default true; false = keep this backend on the prompt/_meta schema fallback\n    },\n  },\n};\n```\n\nScript-declared backends are **trust-gated**: they spawn commands on the host machine, so they stay inert until the composition root approves them \u2014 elicitation approval in the MCP server, `allowScriptBackends: true` (or a per-backend callback) on `runDynamicWorkflow`, `ExecOptions.scriptBackends` on a manager, or `AGENTPRISM_ALLOW_SCRIPT_BACKENDS=1`. A *declined* backend aborts the run rather than silently rerouting its calls to the default backend. Host-registered names always win over script declarations. Prefer host registration (`createAcpRunner({ backends })` / `AGENTPRISM_BACKENDS` env JSON) when you control the host.\n\n## <a name="agenttype-definitions"></a>`agentType` definitions\n\nMarkdown files at `<runCwd>/.agentprism/agents/<name>.md` (project) and `~/.agentprism/agents/<name>.md` (user); project wins on name collision. Frontmatter + body:\n\n```markdown\n---\ndescription: Read-only security auditor\ntools: [read, grep, glob]        # allowlist of tool names (omit = all)\ndisallowedTools: [bash]          # denylist, applied after the allowlist\nmodel: claude/opus[1m]           # verified id; agent({ model }) overrides it\nisolation: worktree              # optional\n---\nYou are a security auditor. Report findings; never modify files.\n```\n\nThe body is prepended to the agent\'s task as role guidance. An unknown `agentType` logs a warning and runs with default tools/model (the name degrades to a prose hint).\n\n## How hosts run scripts (what authors can assume)\n\nThe MCP route (`npx @automatalabs/mcp-server`, tool name `workflow`) is the canonical way an agent\nruns an authored script; registration and the per-action contracts are in the Running workflows\nguide section. The `workflow` tool is the server\'s whole tool surface: run/resume/inspect/await/stop\nare action branches, not separate tools, and this input does not resolve a saved workflow name. A\nrun that pauses with `reason: "auth_required"` resumes via a new run after the backend\'s own CLI is\nlogged in out-of-band (see below). Prompt-capable MCP hosts (e.g. Claude Code, where it surfaces as\na slash command) also get this entire guide from the server itself as the **`author-workflow`**\nprompt, with an optional `task` argument.\n\nEnvironment knobs shared by the MCP server and the SDK: `AGENTPRISM_DEFAULT_BACKEND`,\n`AGENTPRISM_ACP_POOL_SIZE` (schema-run parallelism on OpenCode/custom backends scales with the\npool; one injected-tool registry per process), `AGENTPRISM_BACKENDS`,\n`AGENTPRISM_ALLOW_SCRIPT_BACKENDS`, `AGENTPRISM_PERSISTENCE_ROOT`, plus per-backend spawn\noverrides. Pi uses `AGENTPRISM_PI_ACP_CMD` with optional `AGENTPRISM_PI_ACP_ARGS`; otherwise the\ninstalled exact-pinned package bin is used before the `npx -y @automatalabs/pi-acp` fallback.\n\nEmbedding hosts drive the same contract directly through the SDK \u2014 `runDynamicWorkflow` /\n`WorkflowManager` from `@automatalabs/workflows`, with `exec` limits (`tokenBudget`, `maxAgents`,\n`concurrency`, `agentTimeoutMs`, `agentRetries`), a live `confirm` checkpoint channel, and\n`exec.resumeFromRunId` for edited-script resume. See `docs/api.md` in the repository. The shapes\nbelow are the MCP tool surface, which is what script authors interact with.\n\nExact MCP tool input/output types:\n\n```ts\ninterface WorkflowExecuteToolInputBase {\n  action?: "run";\n  args?: unknown;\n  maxAgents?: number;\n  concurrency?: number;\n  agentRetries?: number;\n  agentTimeoutMs?: number | null;\n  tokenBudget?: number | null;\n  resumeFromRunId?: string;\n  resumePolicy?: "auto" | "positional";\n  checkpointReplies?: Record<number, unknown>;\n  background?: boolean; // default false\n}\n\ntype WorkflowExecuteToolInput = WorkflowExecuteToolInputBase & (\n  | { script: string; scriptPath?: never }\n  | { script?: never; scriptPath: string } // absolute path on the server\n);\n// WorkflowExecuteToolInputBase also carries projectDir?: string \u2014 the absolute project\n// directory selecting the project-scoped run store and default execution cwd. REQUIRED for\n// run on the shared workflow daemon (one registration serves every project); optional on a\n// single-project (--in-process) server. inspect/await/stop never take it: a runId locates\n// its project store automatically.\n\ninterface WorkflowAwaitToolInput {\n  action: "await";\n  runId: string;\n  waitMs?: number;      // default 20_000; integer 0..25_000\n  lastN?: number;       // default 20; integer 1..50\n  labelGlob?: string;   // same whole-label glob as inspect\n  logLines?: number;    // default 20; integer 0..50\n}\n\ninterface WorkflowBackgroundAccepted {\n  runId: string;\n  status: "running";\n  scriptSource: "inline" | "path";\n  scriptUri: string;\n  limits: WorkflowRunLimits;\n  replayEligibility?: WorkflowReplayEligibility;\n}\n\ninterface WorkflowAwaitMetadata {\n  requestedMs: number;\n  elapsedMs: number;\n  returnedBecause: "terminal" | "timeout" | "immediate";\n}\n\ninterface WorkflowRunAwaitResult<T = unknown> extends WorkflowRunStatus {\n  wait: WorkflowAwaitMetadata;\n  tokenUsage?: TokenUsage;\n  outcome?: Omit<WorkflowExecutionToolResult<T>, "scriptSource">; // exactly when terminal\n  scriptUri: string;\n  lineage: Array<{ runId: string; uri: string; available: boolean }>;\n}\n\ninterface WorkflowStopToolInput {\n  action: "stop";\n  runId: string;\n  callIndex?: number;  // omitted = whole-run abort; present = cancel one in-flight agent\n  lastN?: number;\n  labelGlob?: string;\n  logLines?: number;\n  script?: never;\n  scriptPath?: never;\n  waitMs?: never;\n}\n```\n\nThe selected stop form requires a live, uniquely addressable agent attempt. Settled/unallocated\nindexes, checkpoints, duplicate scoped indexes, and terminal runs are errors that enumerate the\ncurrently in-flight call-index/label pairs. A successful selected cancellation returns the ordinary\nlive `WorkflowRunStatus`; whole-run stop returns the terminal `WorkflowStopResult`.\n\n`WorkflowRunResult.fallbacks?: WorkflowRunFallback[]` retains the compatibility shape\n`{ callIndex, label, phase?, requestedSpec, resolvedModel?, backendId?, kind, message, continuation? }`.\n`kind` is `model | modifier | continuation`; continuation details report either a reattached\n`resume | load` method or an exact skip reason. The model-resolution pipeline itself produces no entries.\n`WorkflowRunResult.checkpointsTaken?: WorkflowCheckpointTaken[]` records resolved checkpoints as\n`{ callIndex, kind, decision, source }`, where source is `live`, `headless-default`,\n`journal-replay`, or `injected`. A paused checkpoint is not resolved. Both fields are persisted and\nappear in foreground results plus terminal await `outcome`; neither appears on `WorkflowRunStatus`.\n\nAt most four background runs may be active or starting per server instance. Foreground, inspect,\nawait, and stop consume no slot; a durably stopped background run frees its slot immediately even\nwhile backend session wind-down remains. A timeout returns the freshest status and partial cumulative usage; replay\nhits cost/add zero. Terminal results have no MCP TTL and are reconstructed after restart while the\nproject run record remains readable. The inherited status fields stay redacted/bounded at 24,576\nstructured bytes and 8,192 text bytes. The full script lineage is never truncated; when lineage\nalone exceeds the status budget, `truncation.maxStructuredBytes` reports the larger actual envelope\nlimit. Terminal `outcome` preserves the raw authored result/full logs and has no new total cap, but\nit is never copied into text. It includes `scriptUri` but not the unpersisted admission-only\n`scriptSource`.\n\nThe background start has no enduring request signal, progress channel, or live checkpoint channel.\nIt returns immediately and emits no progress after returning, even if the initiating request\nsupplied a progress token. A later bounded `action:"await"` is a separate request; when that await\ncarries a progress token, it can stream coarse phase and distinct started/ended-call progress while\npending. The legacy/inconsistent-log polling fallback emits no progress notifications. A headless\ncheckpoint default continues; abort fails with `WORKFLOW_ABORTED`; pause returns\n`checkpoint_required` plus `outcome.checkpointContext`. Auth pauses return non-secret\n`outcome.authContext`; log the backend CLI in before resume. Background execution lives in the\nserving process (the daemon, or the single process under `--in-process`): that process\'s death can\ninterrupt an in-flight call, and stale durable `pending`/`running` state reconciles under its lease\nto `paused` / `interrupted`.\n\nEvery resumed background run durably seeds its inherited prefix (including a manager-owned\ncheckpoint injection) beneath its new run ID before acknowledgement, so later resume hops remain\nself-contained. The MCP layer never rewrites that seed. Await and inspect never execute or resume\nthe script; their cold preflight may only reconcile a dead owner\'s stale `pending`/`running` state\nto `paused` / `interrupted`.\n\nEvery admitted script is an immutable persistence-backed MCP resource at\n`workflow://runs/{runId}/script`. Run results link the new script; inspect/await link the full\nresume lineage oldest-to-newest as structured `{ runId, uri, available }` entries. Listing and\ncompletion include only the 50 newest runs, but a direct URI read works for any retained project\nrun. A path is never persisted or implicitly re-read, and the MCP layer retains no scripts, args,\nor synthetic lineage metadata in process memory.\n\n`action:"stop"` durably aborts a `running` or `paused` run live in the serving process: it cancels\nany pending agent/checkpoint request, appends `stopped`, releases the lease, and returns the final\ninspection projection with `stopped:true`. Only backend session wind-down can remain, observable\nthrough inspect\'s agent states. A repeated stop on a terminal run succeeds with `stopped:false,\nalreadyTerminal:true`. An in-flight stop may lack a quiescent terminal-environment proof, so the\nmanager can conservatively run the following resume live; inspect `replayEligibility` and\n`resumeReport` rather than assuming a prefix replay.\n\nRetain the run ID and inspect halted runs before guessing. The exact inspection input is:\n\n```ts\ninterface WorkflowInspectToolInput {\n  action: "inspect";\n  runId: string;       // /^[a-z0-9]+-[a-z0-9]+$/, at most 128 characters\n  lastN?: number;      // default 20; integer 1..50\n  labelGlob?: string;  // non-empty; at most 128 Unicode code points\n  logLines?: number;   // default 20; integer 0..50\n  script?: never;\n  scriptPath?: never;\n}\n```\n\n`labelGlob` matches the whole raw agent label case-sensitively: `*` is zero or more Unicode code\npoints, `?` is exactly one, and backslash escapes the next character (a trailing backslash is\nliteral). Checkpoints and unknown legacy calls are excluded when a glob is present. Filtering\nhappens before `lastN`; selected calls return in ascending call-index order.\n\n```ts\ninterface WorkflowLogTail {\n  lines: string[];\n  totalLines: number;\n  omittedLines: number;\n  truncatedLines: number;\n  redactedLines: number;\n}\n\ninterface WorkflowRunCallStatus {\n  index: number;\n  kind: "agent" | "checkpoint" | "unknown";\n  label?: string;\n  phase?: string;\n  model?: string;\n  backendId?: string;\n  timeoutMs?: number | null;\n  errorCode?: string;\n  resultPreview: string;\n  resultRedacted: boolean;\n  resultTruncated: boolean;\n}\n\ninterface WorkflowRunStatus {\n  runId: string;\n  status: "pending" | "running" | "paused" | "completed" | "failed" | "aborted";\n  workflowName: string;\n  phases: string[];\n  currentPhase?: string;\n  reason?: string;\n  errorCode?: string;\n  limits?: WorkflowRunLimits; // absent only on legacy persisted records\n  replayEligibility?: WorkflowReplayEligibility;\n  logTail: WorkflowLogTail;\n  calls: WorkflowRunCallStatus[];\n  filter: { lastN: number; logLines: number; labelGlob?: string };\n  truncation: {\n    maxStructuredBytes: number;\n    byteCapApplied: boolean;\n    phases: { total: number; returned: number; shortened: number };\n    logs: { total: number; returned: number; shortened: number; redacted: number };\n    calls: {\n      total: number;\n      matched: number;\n      returned: number;\n      shortenedResults: number;\n      redactedResults: number;\n    };\n  };\n}\n\ninterface WorkflowRunLimits {\n  maxAgents: number;\n  tokenBudget: number | null;\n  concurrency: number;\n  agentRetries: number;\n  agentTimeoutMs: number | null;\n}\n```\n\nInspection returns only this allowlisted projection: never raw script, args, prompts, histories,\nhashes, session IDs, cwd, checkpoint/auth details, or raw results. Credential-shaped data is\nredacted, results are structurally compacted, every outward text scalar/preview is capped at 512\nUTF-8 bytes, inherited status JSON at 24,576 bytes, and inspection text at 8,192 bytes. Full lineage\ncan raise the structured envelope limit as reported by `truncation.maxStructuredBytes`. An unknown ID is\na tool error with no structured content; reading an existing failed run succeeds and reports\n`status:"failed"`. Every paused, failed, or aborted execution result also carries a redacted\nfinal-20 `logTail` (present when empty) and renders it in the immediate terminal text. Completed\nexecution results omit that extra field while retaining their full `logs` array.\n\nBackend auth comes from the machine the host runs on: Claude via a logged-in Claude Code install or `ANTHROPIC_API_KEY`; Codex via `~/.codex/auth.json`; OpenCode via `opencode auth login` (its CLI must be installed \u2014 it is not bundled); Pi via one of `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `XAI_API_KEY`, `OPENROUTER_API_KEY`, or ambient credentials in `~/.pi/agent/auth.json`. A script only needs auth for the backends it actually routes to.\n\n## The validator \u2014 `agentprism-workflows validate`\n\n```bash\nnpx @automatalabs/workflows validate <workflow-file> [options]\n```\n\nZero tokens; three passes \u2014 static parse, mocked dry run, then one no-prompt config probe per\nrouted `{ backend, model }` pair \u2014 described in the guide\'s Validate before you run section. The\ntables and grammar below are the exhaustive contract.\n\n| flag | meaning |\n|---|---|\n| `--args <json>` / `--args-file <path>` | the script\'s `args` global for the dry run |\n| `--mock-answers <json>` | label-glob answers for dry-run calls; mutually exclusive with the file form |\n| `--mock-answers-file <path>` | read the same JSON object from a UTF-8 file resolved against the process cwd |\n| `--workflows-dir <dir>` | repeatable; a folder of workflow scripts (name = filename stem). Lets the positional be a NAME and resolves nested `workflow("<name>")` calls |\n| `--parse-only` | static parse only |\n| `--cwd <dir>` | dry-run base cwd (default: throwaway temp dir, so `isolation: "worktree"` no-ops; a real repo cwd creates and cleans up real worktrees) |\n| `--token-budget <n>` | sets `budget.total`; the mock reports 1000 tokens per agent call |\n| `--max-agents <n>` | cap on dry-run agent calls |\n| `--timeout-ms <n>` | dry-run wall-clock limit (default 30000) |\n| `--json` | machine-readable `ValidateWorkflowReport` on stdout |\n\nInline false-branch fixture (exact shell form):\n\n```bash\nagentprism-workflows validate flow.workflow.js \\\n  --mock-answers \'{"refute:*":{"real":false}}\'\n```\n\nEquivalent reusable file with a reject-then-approve sequence:\n\n```json\n{\n  "refute:*": { "real": false },\n  "quality:review": {\n    "$sequence": [\n      { "ok": false, "feedback": "exercise the revision path" },\n      { "ok": true }\n    ]\n  }\n}\n```\n\n```bash\nagentprism-workflows validate flow.workflow.js --mock-answers-file mock-answers.json\n```\n\nRules match the final resolved label case-sensitively across the whole string. `*` matches zero or more characters (including `:` and `/`), `?` one character, and `\\` escapes the next character; empty globs and trailing escapes are invalid. Object order is captured once and the **last matching rule wins**, so put `"*"` before narrower exceptions. Raw canonical array-index keys (`"0"` or a non-zero, no-leading-zero decimal through `"4294967294"`) are reserved because ECMAScript reorders them. To match numeric label `10`, use JSON key `"\\\\10"`; `"01"` and `"4294967295"` are ordinary keys.\n\nA single answer is reusable. `{ "$sequence": [...] }` is finite and only the winning rule consumes it; a raw array is one array result, and a sequence element is ordinary answer data even when it contains `$sequence`. Exhaustion fails instead of repeating the last item or falling back. The machine report uses zero-based `sequenceIndex`; human lines render one-based `[position/length]`. Earlier matching rules count the match even when shadowed, and `dryRun.mockAnswers.unused` distinguishes `no-match`, `shadowed`, and partially consumed `not-reached` items. Unused fixtures warn but do not fail validation.\n\nFor schema calls, each answer deep-merges over a **fresh** fabricated base: JSON objects merge recursively; arrays, `null`, falsy primitives, and other scalars replace. The merged value is TypeBox-checked without coercion. Any answer-caused violation fails non-recoverably with `SCHEMA_NONCOMPLIANCE`; a failure already present at the identical untouched path/message in the simple fabricated base may be accepted with a grouped inherited-fabrication warning. A valid override can repair such a base limitation. Schema-less answers must be nonblank strings. Fixture failure messages, attribution, and warnings contain only labels, globs, positions, paths, and counts\u2014not answer values.\n\nLimits: 256 KiB raw UTF-8 for either CLI source and canonical JSON for programmatic input; 256 rules; 1\u2013256 UTF-16 code units per glob; 256 entries per sequence; answer depth 32. Inputs must be plain JSON data. Mock-enabled validation serves agent calls serially for deterministic FIFO sequence allocation; it is not a concurrency/load simulation, and the soft token gate may admit work differently than an unscripted concurrent dry run. Fixture values still flow into the script like real agent results, so author code can expose them via `log()` or its returned result\u2014never store credentials or production data in fixtures.\n\nExit codes: `0` valid \xB7 `1` parse/static failure \xB7 `2` dry-run failure \xB7 `3` usage error. The report also lists every checkpoint with the mock reply (`default ?? true`) and warnings for backend approval, phase mismatch, `headless: "abort"`, and agent-less scripts. `headless: "pause"` dry-runs cleanly. A saved nested workflow still needs `--workflows-dir`.\n\nProgrammatic: `validateWorkflowScript(script, { args, workflows, dryRun, cwd, tokenBudget, maxAgents, timeoutMs, mockAnswers })` from `@automatalabs/workflows` returns the same report. Invalid workflow scripts resolve to reports; invalid `mockAnswers` supplied from untyped JavaScript throws `TypeError` before parsing.\n\n## Harness config discovery \u2014 `agentprism-workflows config`\n\nValidate\'s sibling: the same no-prompt config probe, standalone \u2014 no script required. Run it BEFORE authoring to read each harness\'s advertised, negotiable session surface (model ids including bracket variants, effort levels, modes, boolean knobs) instead of guessing values or writing a throwaway probe workflow.\n\n```bash\nnpx @automatalabs/workflows config                  # every routable harness\nnpx @automatalabs/workflows config codex opencode   # only the named harnesses\nnpx @automatalabs/workflows config claude --json    # machine-readable report\n```\n\nHarness names are the routing names: built-in `claude` / `codex` / `opencode` / `pi` plus any custom backend registered via the `AGENTPRISM_BACKENDS` env var (registered customs also join the no-argument default set). Each harness opens one session without a prompt \u2014 zero tokens \u2014 and its catalog is read fresh; a harness that cannot spawn or authenticate reports `probed: false` with the reason and never blocks the others.\n\nThe no-argument built-in sequence comes from `BUILTIN_BACKEND_IDS`; authoring prose describes the\ncurrent registry rows and does not define a separate supported-backend list.\n\n| flag | meaning |\n|---|---|\n| `--cwd <dir>` | session cwd for the probes (default: the current directory \u2014 harnesses may resolve project-level config, and hence their catalog, from it) |\n| `--timeout-ms <n>` | per-harness probe bound (default 60000); a timed-out harness reports `probed:false` |\n| `--json` | machine-readable `HarnessConfigReport` on stdout (`harnessOptions` uses the same per-harness shape as validate\'s report) |\n\nExit codes: `0` all probed \xB7 `1` at least one probe failed \xB7 `3` usage error.\n\nProgrammatic: `probeHarnessConfig({ harnesses, backends, cwd, timeoutMs })` from `@automatalabs/workflows` returns the same report (`backends` merges over `AGENTPRISM_BACKENDS` exactly like `createAcpRunner`); `formatHarnessConfigReport(report)` renders the human table.\n\n## Workflow folders\n\nHosts that keep versioned folders of workflow scripts serve them by name (the SDK\'s\n`openWorkflowDir` \u2014 see `docs/api.md`). The filename stem is the name (`review-pr.workflow.js` \u21D2\n`review-pr`; `.workflow.js` beats `.js`). For script AUTHORS the takeaway is simply:\n`workflow("<name>")` works when the host serves a folder; keep names equal to filename stems.\n\n---\n\n# Complete example \u2014 quick-wins.workflow.js\n\nA complete, validated script (`loopUntilDry()` with per-round vendor rotation, dedup threading via a `seen` list, and an in-round budget floor; runs standalone or nested):\n\n```js\n// quick-wins \u2014 a small, self-contained hunter that repo-triage nests by name\n// (`workflow("quick-wins", {...})`) and that also runs standalone:\n//\n//   npm start -- --workflow quick-wins\n//   npx agentprism-workflows validate quick-wins --workflows-dir workflows\n//\n// Demonstrates loopUntilDry(): keep spawning hunt rounds \u2014 each on the next vendor\n// in the pool \u2014 until two consecutive rounds add nothing new (or the round cap /\n// token budget stops it first). Workflow scripts are self-contained strings with no\n// imports, so the vendor pool is repeated here rather than shared with repo-triage.\nexport const meta = {\n  name: "quick-wins",\n  description: "Hunt small, high-confidence quick wins across the repo until two consecutive rounds come up dry",\n  phases: [{ title: "Hunt" }],\n};\n\n// args \u2014 every knob optional; hosts may hand args through as a JSON string.\nconst raw = typeof args === "string" ? (() => { try { return JSON.parse(args); } catch { return {}; } })() : args;\nconst opt = raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};\nconst rounds = Number.isFinite(Number(opt.rounds)) && Number(opt.rounds) >= 1 ? Math.floor(Number(opt.rounds)) : 4;\nconst focus =\n  typeof opt.focus === "string" && opt.focus.trim().length > 0\n    ? opt.focus.trim()\n    : "small, safe, high-confidence improvements";\nconst avoid = Array.isArray(opt.avoid) ? opt.avoid.filter((x) => typeof x === "string") : [];\n\n// These registered-prefix specs use ids verified against each live harness catalog.\nconst POOL = [\n  { name: "claude", model: "claude/opus[1m]", mode: "plan" },\n  { name: "codex", model: "codex/gpt-5.6-sol", mode: "read-only" },\n  { name: "opencode", model: "opencode/zai/glm-5.2" },\n];\n\nconst WINS = {\n  type: "object",\n  additionalProperties: false,\n  required: ["wins"],\n  properties: {\n    wins: {\n      type: "array",\n      items: {\n        type: "object",\n        additionalProperties: false,\n        required: ["file", "summary", "action"],\n        properties: {\n          file: {\n            type: "string",\n            description: "Repo-relative path of a file you actually opened \u2014 copy it exactly, never invent one",\n          },\n          summary: { type: "string", description: "One sentence: the small problem or missed improvement" },\n          action: { type: "string", description: "The concrete, low-risk change that fixes it, in one clause" },\n        },\n      },\n    },\n  },\n};\n\nphase("Hunt");\nconst seen = [];\nconst wins = await loopUntilDry({\n  round: async (i) => {\n    // Budget floor: leave headroom for whatever runs after this hunt. When nested\n    // inside repo-triage, budget.* reads the PARENT run\'s shared budget.\n    if (budget.total && budget.remaining() < 30_000) {\n      log(`Hunt round ${i + 1}: stopping \u2014 only ${budget.remaining()} tokens left`);\n      return [];\n    }\n    const v = POOL[i % POOL.length];\n    const r = await agent(\n      `Hunt round ${i + 1}: find up to 3 quick wins in this repository \u2014 ${focus}. ` +\n        "A quick win is a small, safe, self-contained improvement (a missing guard, a stale doc line, an obvious dead branch), " +\n        "not a refactor. Open files and ground every entry in code you actually read; never emit a placeholder.\\n" +\n        `Already known \u2014 do NOT repeat anything on this list: ${JSON.stringify([...avoid, ...seen])}`,\n      { label: `hunt:${i + 1}:${v.name}`, phase: "Hunt", schema: WINS, model: v.model, mode: v.mode },\n    );\n    const found = (r?.wins ?? []).filter((w) => typeof w.file === "string" && w.file.length > 0 && !w.file.startsWith("/"));\n    seen.push(...found.map((w) => `${w.file}: ${w.summary}`));\n    return found.map((w) => ({ ...w, foundBy: v.name }));\n  },\n  key: (w) => `${w.file}::${w.summary}`,\n  consecutiveEmpty: 2,\n  maxRounds: rounds,\n});\n\nlog(`quick-wins: ${wins.length} unique wins across the hunt`);\nreturn { wins };\n```\n';
 
 // ../mcp-server/src/authoring-prompt.ts
 var AUTHORING_PROMPT_NAME = "author-workflow";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automatalabs/workflows",
-  "version": "0.45.0",
+  "version": "0.45.2",
   "license": "Apache-2.0",
   "engines": {
     "node": ">=22"
@@ -32,7 +32,7 @@
   "dependencies": {
     "typebox": "1.3.2",
     "@automatalabs/shared-types": "0.28.0",
-    "@automatalabs/acp-agents": "0.34.10",
+    "@automatalabs/acp-agents": "0.34.12",
     "@automatalabs/workflow-engine": "0.34.0"
   },
   "devDependencies": {