@signalridge/pi-workflows 1.3.2 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 1.4.0
+### Minor Changes
+
+- 28c8aa1: Strengthen script orchestration with deterministic named dependency graphs, bounded task retries and failure policies, safer fan-out barriers, durable nested-workflow replay, and reliable pause/resume accounting. The natural-language `/workflows run` path now plans, executes, and synthesizes a bounded task graph, while expanded authoring/pattern guidance and the new `workflow-review` skill make routing, recovery, and publication constraints explicit.
+
 ## 1.3.2
 ### Patch Changes
 

package/README.md

@@ -2,7 +2,7 @@
 
 JavaScript orchestration for Pi. A workflow is a raw JavaScript module executed
 in a determinism-guarded `node:vm` realm; the runtime supplies `agent()`,
-`parallel()`, `pipeline()`, `workflow()`, quality helpers (`verify`,
+`parallel()`, `pipeline()`, `orchestrate()`, `workflow()`, quality helpers (`verify`,
 `judgePanel`, `loopUntilDry`, `completenessCheck`, `retry`, `gate`), human
 `checkpoint()`, `phase()`, `log()`, `args`, `cwd`, restricted `process`, and
 `budget`. Every live `agent()` call is dispatched through the additive
@@ -69,8 +69,9 @@ return report;
 The meta statement must be the first statement and use only literals — spread,
 computed keys, methods, template interpolation, and the reserved keys
 `__proto__`/`constructor`/`prototype` are rejected. `Date.now()`,
-`Math.random()`, and no-argument `new Date()` are unavailable (a regex precheck
-plus in-realm stubs); pass timestamps and randomness through `args`. The vm is
+`Math.random()`, and no-argument `new Date()` are unavailable (an AST precheck
+plus in-realm stubs); prompt text containing those words remains valid. Pass
+timestamps and randomness through `args`. The vm is
 a determinism guardrail, not a security boundary — scripts are generated by the
 user's own LLM and run on the user's own machine.
 
@@ -78,7 +79,8 @@ user's own LLM and run on the user's own machine.
 
 - `agent(prompt, { label, phase, schema, model, tier, isolation, thread, agentType, toolset, excludeTools, timeoutMs, retries })`
   — dispatch one subagent through the managed spawn protocol. Returns text, a
-  schema-validated value, or recoverable `null` after retries. `schema` is a
+  schema-validated value, or recoverable `null` after retries. Replayed journal
+  calls consume no real-dispatch cap or token/phase budget. `schema` is a
   plain JSON Schema; the reply is parsed and validated client-side with bounded
   repair across attempts, and exhaustion throws `SCHEMA_NONCOMPLIANCE`.
   Explicit `model` and `isolation: "worktree"` are resolved and enforced by pi-subagents; `tier` remains the provider-neutral route.
@@ -86,12 +88,21 @@ user's own LLM and run on the user's own machine.
   conversation thread.
 - `parallel(thunks)` — run thunks concurrently, preserve input order. Recoverable
   thunk failures become `null`; non-recoverable failures (token budget, agent
-  limit) halt the run. Fan-out that breaches `maxAgents` cancels only its own
-  batch.
+  limit) halt the run after the batch barrier settles. Fan-out that breaches
+  `maxAgents` cancels only its own batch; each call accepts at most 4096 thunks.
 - `pipeline(items, ...stages)` — items run concurrently, stages per item run
-  sequentially with `(previousValue, originalItem, index)`.
+  sequentially with `(previousValue, originalItem, index)`; each call accepts at
+  most 4096 items and waits for the batch before surfacing fatal failures.
+- `orchestrate(tasks, { onError })` — execute a named dependency graph in
+  deterministic declaration-order layers. Each task is `{ id, dependsOn?, phase?,
+  retries?, run }`; its callback receives `{ id, attempt, results, statuses }`.
+  `onError` is `skip-dependents` (default), `continue`, or `fail-fast`. Results
+  are keyed by task id, and task lifecycle events are observable through
+  `onRuntimeEvent`.
 - `workflow(savedName, childArgs?)` — run a saved workflow inline; one nested
-  level, sharing the limiter, counters, token accounting, and store.
+  level, sharing the limiter, counters, token accounting, and store. The child
+  result is journaled as one parent call with a generation-scoped namespace, so
+  unchanged nested work replays without spawning again after resume.
 - `verify(item, { reviewers, threshold, lens })`, `judgePanel(attempts,
   { judges, rubric })`, `loopUntilDry({ round, key, consecutiveEmpty,
   maxRounds })`, `completenessCheck(taskArgs, results)`, `retry(thunk,
@@ -107,17 +118,35 @@ user's own LLM and run on the user's own machine.
 ### Resume
 
 A script edit replays the longest unchanged prefix from the journal and runs
-live from the first changed or inserted `agent()`/`checkpoint()` call. Pass
-`resumeFromRunId` with the edited script; unchanged calls report zero tokens,
+live from the first changed or inserted `agent()`/`checkpoint()` call. The
+original invocation `args` and execution limits are frozen and reused on manual
+or automatic resume. Pass `resumeFromRunId` with the edited script; unchanged
+calls report zero tokens,
 and edited calls rotate their managed spawn key generation so pi-subagents
 never raises a fingerprint conflict.
 
+## Skills
+
+The package ships three model-routable skills:
+
+- `workflow-authoring` — design, review, and debug custom JavaScript workflows;
+  it teaches topology selection, stable work IDs, bounded failure handling, and
+  resume-safe authoring.
+- `workflow-patterns` — choose and invoke a reviewed built-in for research,
+  adversarial review, code review, multi-perspective analysis, or codebase audit.
+- `workflow-review` — audit an existing workflow for topology, data flow,
+  recovery, resume safety, and publication readiness without editing it.
+
+Use the pattern skill for a standard task, the authoring skill for a custom
+workflow, and the review skill before accepting a topology or recovery change.
+
 ## Tools and commands
 
 - `workflow`: run a script (`script`) or a saved/built-in workflow (`name`),
   with `args`, `background` (default true), `maxAgents`, `concurrency`,
   `agentRetries`, `tokenBudget`, `agentTimeoutMs`, and `resumeFromRunId`.
 - `workflow_control`: `list`, `get`, `pause`, `resume`, `stop`, or `rm` a run; `rm` writes a durable removal tombstone.
+- `pi.events` emits `pi-workflows:runtime` snapshots (`{ runId, event }`) for phase, task, quality, retry, and nested-workflow progress; observer failures are contained.
 - `/workflows`: TUI navigator plus `run`, `status`, `watch`, `stop`, `pause`,
   `resume`, `rm`, and `save <name> [runId]` subcommands.
 - `/workflows-models`: points at pi-subagents' `/agents → Model tiers` — there
@@ -163,4 +192,4 @@ The managed protocol carries semantic tiers plus optional exact model/thinking,
 - **Agent registry and tier catalogue ownership.** `agentType` and `small|medium|large` profiles resolve in pi-subagents, avoiding a second registry/config schema.
 - **Schema validation is client-side.** The managed request does not assume a structured-output tool; the runtime asks for JSON, parses, validates (including `additionalProperties`), and repairs across bounded attempts.
 
-State is persisted as `pi.appendEntry("pi-workflows:journal", ...)` custom entries (schema v3), including script revisions and durable removals. Interrupted/provider-limited runs replay from the journal; schema-v2 declarative journals are quarantined rather than replayed. Foreground `AbortSignal`s stop owned children through explicit owner-scoped stop/quiescence, and dispose/branch replacement reject stale waiters.
+State is persisted as `pi.appendEntry("pi-workflows:journal", ...)` custom entries (schema v3), including frozen invocation args, terminal result previews, script revisions, named nested-workflow result boundaries, and durable removals. Interrupted/provider-limited runs replay from the journal; schema-v2 declarative journals are quarantined rather than replayed. Foreground `AbortSignal`s stop owned children through explicit owner-scoped stop/quiescence, and dispose/branch replacement reject stale waiters.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalridge/pi-workflows",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "description": "Deterministic JavaScript orchestration workflows backed by pi-subagents managed spawning.",
   "type": "module",
   "license": "MIT",
@@ -30,7 +30,8 @@
     ],
     "skills": [
       "skills/workflow-authoring",
-      "skills/workflow-patterns"
+      "skills/workflow-patterns",
+      "skills/workflow-review"
     ]
   },
   "repository": {

package/skills/workflow-authoring/SKILL.md

@@ -1,30 +1,178 @@
 ---
 name: workflow-authoring
-description: Guidance for writing, editing, reviewing, and debugging JavaScript workflow code for @signalridge/pi-workflows. Use when authoring or changing workflow scripts; not for merely running an existing workflow.
+description: Design, write, review, and debug Pi JavaScript workflows that coordinate multiple subagents. Use when a request needs named dependencies, bounded fan-out, per-item pipelines, quality gates, saved or nested workflows, pause/resume, or workflow progress; do not use it merely to run an existing named workflow.
 metadata:
-  version: "1.2.1"
+  version: "1.4.0"
 ---
 
 # Workflow authoring
 
-Load this skill when workflow JavaScript changes. Running an existing workflow needs no authoring reference.
+A workflow is a small program that coordinates subagents; it is not a long prompt
+that asks one agent to do every step. Keep semantic work in agents and keep
+identity, ordering, bounds, failure handling, and aggregation deterministic in
+JavaScript.
 
-## Choose a branch
+## Operating contract
 
-Read only what the task needs:
+- Use a workflow only when the task benefits from multiple agents, explicit
+  stages, independent coverage, or a quality/recovery loop. One or two simple
+  delegations should use the ordinary agent surface.
+- Start every script with literal `export const meta = { name, description,
+  phases? }`. Return plain JSON data explicitly.
+- Use `orchestrate()` for named dependencies, `parallel()` for a small
+  independent barrier, and `pipeline()` for independent items that each need a
+  sequential stage chain. Do not encode a dependency graph only in comments.
+- Give every work unit a stable ID and every agent call a short unique label.
+  Keep IDs beside results before filtering; `null` is missing coverage, not a
+  successful finding.
+- Bound graph tasks, fan-out items, loops, retries, agents, concurrency, and
+  evidence size. Invocation-level token and time caps are user constraints, not
+  substitutes for algorithmic bounds.
+- Route an agent call with `tier: "small"`, `"medium"`, or `"large"`; omit
+  `tier` to use the pi-subagents workflow default. Never guess nonstandard model
+  routes, tiers, or agent types—use a name supplied by the current environment
+  and follow [registry ownership](references/registry-ownership.md).
+- Workflows have no imports, filesystem/network APIs, timers, or unrestricted
+  Node APIs. Pass timestamps, randomness, and external decisions through `args`.
 
-- **Write or edit:** start with [runtime](references/runtime.md). Add [pattern selection](references/pattern-selection.md) for topology, [lifecycle](references/lifecycle.md) for limits or resume, and [focused recipes](references/focused-recipes.md) for the matching concern.
-- **Helper task:** read [quality helpers](references/quality-helpers.md) only for `verify` or `judgePanel`, the [retry helper](references/retry-helper.md) only for `retry`, and [specialized helpers](references/specialized-helpers.md) only for `completenessCheck`, `loopUntilDry`, `gate`, or `checkpoint`.
-- **Review:** use the [review checklist](references/review.md), plus only the matching [quality](references/quality-helpers.md) or [specialized](references/specialized-helpers.md) helper contracts.
-- **Debug:** use the [debugging map](references/debugging.md).
-- **Routing:** read [registry ownership](references/registry-ownership.md) before using `model`, `tier`, phase models, or `agentType`; use environment-specific names only when context supplies them.
-- **Exact lookup or portability:** start with the generated [capability index](references/capabilities.md). Follow its exhaustive-facts pointer only for constraints or support boundaries. Use [versions](references/versions.md) when moving scripts between installations.
+## The authoring pass
 
-## Invariants
+1. **Classify the topology.** Decide whether the work is direct, a named DAG,
+   homogeneous fan-out, a per-item pipeline, iterative discovery, or a quality
+   gate. Read [pattern selection](references/pattern-selection.md) only for the
+   chosen shape.
+2. **Declare inputs and bounds.** Read `args` once, normalize the input, reject
+   or cap untrusted cardinality, and decide what incomplete coverage means.
+3. **Write the envelope.** Declare only phases that are actually entered. Use
+   `phase(title, { budget })` for a soft token sub-budget, not as a scheduler.
+4. **Build the smallest work ledger.** Store `{ id, status, result, error }`
+   (or an equivalent object) for each intended unit. Do not lose identity when
+   applying `.filter(Boolean)`.
+5. **Dispatch with the right primitive.** Await every batch. For a dependent
+   prompt, include both the dependency ID and its actual result; do not assume
+   the child can see the parent conversation.
+6. **Add quality only where it changes a decision.** Use a schema before reading
+   structured fields, then use `verify`, `judgePanel`, `gate`, or
+   `completenessCheck` with explicit bounds.
+7. **Aggregate and report.** Return a bounded JSON result containing the answer,
+   coverage, and important failures. If the workflow runs in the background,
+   the run ID is the handle for later control/resume.
+8. **Review the script.** Use [the review checklist](references/review.md), then
+   test with deterministic fake agents when changing topology or recovery.
 
-- Start with literal `export const meta = { name, description }`; declare phases as an array of used `{ title }` objects and enter each named phase.
-- Call `agent()` at least once, give every call a short unique `label`, and return plain JSON data explicitly.
-- Pair ordered results with stable work IDs before filtering. When one agent consumes another's selected result, include both its stable ID and actual data in the downstream prompt. Treat recoverable `null` as missing coverage and report it.
-- Bound fan-out, loops, retries, agents, and concurrency to the task. Treat invocation-level token and time caps as opt-in user constraints, not defaults.
-- Use `log()` for new code; `console` is compatibility-only.
-- Write plain JavaScript without imports or filesystem modules. Pass nondeterminism through `args`; `Date.now()`, `Math.random()`, and no-argument `new Date()` are unavailable.
+## Topology rules
+
+### Named dependencies: `orchestrate`
+
+Use a task graph when a later step consumes a named earlier step:
+
+```js
+const graph = await orchestrate([
+  { id: "scan", run: () => agent("Inspect the target", { label: "scan" }) },
+  { id: "security", run: () => agent("Check security risks", { label: "security" }) },
+  {
+    id: "report",
+    dependsOn: ["scan", "security"],
+    run: ({ results, statuses }) =>
+      agent(
+        "Synthesize the named findings; mention unavailable coverage.\n\n" +
+          JSON.stringify({ results, statuses }),
+        { label: "report" },
+      ),
+  },
+]);
+return graph;
+```
+
+`orchestrate()` validates IDs, missing dependencies, duplicate edges, and
+cycles before callbacks run. It executes ready tasks in declaration-order
+layers with a barrier between layers and returns `{ results, tasks }`. Each task
+callback receives detached `{ id, attempt, results, statuses }` snapshots.
+`retries` retries ordinary task-callback failures up to three times. The default
+`onError: "skip-dependents"` prevents a failed dependency from feeding a stale
+prompt; use `onError: "continue"` only when the dependent explicitly handles
+failed statuses. `fail-fast` stops discovery of later layers after the current
+layer settles.
+
+### Independent fan-out: `parallel`
+
+Pass thunks, not already-started promises. Results preserve input order and a
+recoverable item failure becomes `null`; fatal errors surface after the whole
+batch barrier settles. Keep a ledger with IDs before filtering:
+
+```js
+const work = items.map((item) => ({ id: item.id, item }));
+const outputs = await parallel(work.map(({ item }) => () =>
+  agent("Handle item " + item.id, { label: "item-" + item.id }),
+));
+const ledger = work.map(({ id }, index) => ({ id, result: outputs[index] }));
+```
+
+Each `parallel()` call accepts at most 4096 thunks. It is a barrier: do not
+start synthesis until the returned array is complete.
+
+### Per-item stages: `pipeline`
+
+Use `pipeline(items, ...stages)` when every item follows the same chain. Items
+run concurrently, but stages for one item are sequential and receive
+`(previousValue, originalItem, index)`. A stage failure drops that item to
+`null`; guard missing values before the next stage. There is no cross-item
+barrier between stages, and each call accepts at most 4096 items.
+
+### Saved or nested workflows
+
+`workflow(name, childArgs)` resolves a context-supplied saved workflow and runs
+it inline with the parent's limiter, agent accounting, token accounting, and
+store. One nested level is allowed; concurrent siblings are allowed. An
+unchanged child is replayed as one parent journal call, while a changed or
+interrupted child receives a generation-scoped managed identity. Do not use
+nesting as an unbounded recursion mechanism.
+
+## Prompt and result discipline
+
+Every child prompt must be self-contained: state the role, exact task, relevant
+inputs, expected output shape, and what the child must not do. Prefer a small
+`schema` for values JavaScript will inspect. When a child consumes another
+child's output, include the stable ID and actual bounded data, for example:
+
+```js
+const prompt = "Review result " + JSON.stringify({ id: "scan", result: scan });
+```
+
+Do not pass whole transcripts when a summary or structured fields are enough.
+Use `log()` for progress and return a result that distinguishes completed work,
+missing coverage, and failed/skipped work.
+
+## Failure, limits, and recovery
+
+- Recoverable child failures return `null` after agent retries. Fatal workflow
+  errors (invalid hooks, exhausted hard limits, unsupported selectors, and
+  schema exhaustion) throw and must not be dissolved into a normal result.
+- Runtime `agent({ retries })` retries execution failures. `orchestrate` task
+  `retries` retries the callback. Semantic `retry()`/`gate()` attempts are a
+  third, intentional layer. Bound and ledger every layer separately.
+- `agent()` schema repair includes concrete validation feedback in the next
+  attempt. Do not read fields from an unvalidated text response.
+- `checkpoint()` is headless by default for background runs. Use
+  `background: false` only when a human decision must be shown.
+- `budget` and phase budgets are soft pre-call gates; concurrent work may
+  overshoot. Do not promise an exact token ceiling unless the caller supplied
+  and accepted that policy.
+
+## Resume and publication gate
+
+Resume replays the longest unchanged prefix of journaled calls. Keep call order,
+labels, prompts, routing options, and inputs stable. `orchestrate` layer order
+and named dependency results make dynamic plans easier to replay, but arbitrary
+branch/loop call counts can still invalidate the positional prefix. Never use
+`Date.now()`, `Math.random()`, or no-argument `new Date()` in a script.
+
+Before shipping a workflow change:
+
+- read [lifecycle](references/lifecycle.md) for pause, stop, budget, and resume;
+- read [debugging](references/debugging.md) when reproducing a failure;
+- read [the review checklist](references/review.md) before accepting topology;
+- read [the generated capability index](references/capabilities.md) when a
+  signature, default, or support boundary is disputed;
+- ensure every package-relative example/reference link remains inside the
+  publishable package.

package/skills/workflow-authoring/examples/named-task-graph.js

@@ -0,0 +1,34 @@
+export const meta = {
+  name: "named-task-graph",
+  description: "Run independent research and synthesize it through named dependencies",
+  phases: [{ title: "research" }, { title: "synthesis" }],
+};
+
+const graph = await orchestrate([
+  {
+    id: "architecture",
+    phase: "research",
+    description: "Inspect the architecture",
+    run: () => agent("Inspect the architecture and report concrete design constraints", { label: "architecture" }),
+  },
+  {
+    id: "risk",
+    phase: "research",
+    description: "Find operational risks",
+    run: () => agent("Find operational and recovery risks", { label: "risk" }),
+  },
+  {
+    id: "synthesis",
+    phase: "synthesis",
+    dependsOn: ["architecture", "risk"],
+    description: "Combine the named findings",
+    run: ({ results, statuses }) =>
+      agent(
+        "Combine these findings. Mention any unavailable dependency explicitly.\n\n" +
+          JSON.stringify({ results, statuses }),
+        { label: "synthesis" },
+      ),
+  },
+]);
+
+return graph;

package/skills/workflow-authoring/references/capabilities.md

@@ -2,7 +2,7 @@
 # Workflow capability index
 
 Contract format: `1.0.0`<br>
-Contract content / skill / extension: `1.3.2`
+Contract content / skill / extension: `1.4.0`
 
 This compact generated index covers supported runtime globals and workflow-tool inputs. For constraints, compatibility behavior, internal boundaries, and dynamic-reference ownership, follow the [exhaustive generated facts](capability-details.md).
 
@@ -14,6 +14,7 @@ This compact generated index covers supported runtime globals and workflow-tool
 | agent | runtime-global | `agent(prompt, options?) => Promise<string \| structured value \| null>` | `label`: string (optional); default: derived from phase and call count<br>`phase`: string (optional); default: current phase<br>`schema`: plain JSON Schema (optional)<br>`model`: string (optional); default: pi-subagents model resolver<br>`tier`: small\|medium\|large (optional); default: pi-subagents workflow tier<br>`isolation`: "worktree" (optional); default: pi-subagents worktree policy<br>`thread`: string (optional); default: fresh session per call<br>`toolset`: string (optional); default: configured host/agent toolset hint<br>`excludeTools`: string[] (optional)<br>`agentType`: string (optional); default: general-purpose<br>`timeoutMs`: number \| null (optional); default: 300000 (5min); null disables<br>`retries`: number (optional); default: run retry count |
 | parallel | runtime-global | `parallel(thunks) => Promise<Array<unknown \| null>>` | — |
 | pipeline | runtime-global | `pipeline(items, ...stages) => Promise<Array<unknown \| null>>` | — |
+| orchestrate | runtime-global | `orchestrate(tasks, options?) => Promise<{ results, tasks }>` | `onError`: "skip-dependents"\|"continue"\|"fail-fast" (optional); default: "skip-dependents" |
 | workflow | runtime-global | `workflow(savedName, childArgs?) => Promise<unknown>` | — |
 | verify | runtime-global | `verify(item, options?) => Promise<{ real, realCount, total, votes }>` | `reviewers`: number (optional); default: 2<br>`threshold`: number (optional); default: 0.5<br>`lens`: string \| string[] (optional) |
 | judgePanel | runtime-global | `judgePanel(attempts, options?) => Promise<{ index, attempt, score, judgments } \| undefined>` | `judges`: number (optional); default: 3<br>`rubric`: string (optional); default: overall quality and correctness |

package/skills/workflow-authoring/references/capability-details.md

@@ -2,7 +2,7 @@
 # Exhaustive workflow capability facts
 
 Contract format: `1.0.0`<br>
-Contract content / skill / extension: `1.3.2`
+Contract content / skill / extension: `1.4.0`
 
 Every exact fact below is projected from the installed extension's capability contract. Explanatory judgment belongs in the hand-written references next to this file.
 
@@ -28,6 +28,7 @@ Every exact fact below is projected from the installed extension's capability co
 - Constraint: recoverable failures return null after retries; nonrecoverable failures throw
 - Constraint: schema noncompliance after bounded repair attempts is nonrecoverable
 - Constraint: resume replays only the longest unchanged prefix; the first miss and every later call execute live
+- Constraint: replayed calls do not consume the real-dispatch maxAgents or token/phase budgets
 - Constraint: spawnKeys rotate by generation on resume so pi-subagents never raises a fingerprint conflict
 - Constraint: explicit model is resolved and scope-checked by pi-subagents; unavailable selectors fail closed
 - Constraint: same-thread calls must be sequential and preserve a stable workflow thread name
@@ -41,8 +42,9 @@ Every exact fact below is projected from the installed extension's capability co
 - Signature: `parallel(thunks) => Promise<Array<unknown \| null>>`
 - Constraint: requires functions rather than promises
 - Constraint: result order matches input order
-- Constraint: recoverable thunk failures become null; nonrecoverable failures throw
+- Constraint: recoverable thunk failures become null; nonrecoverable failures throw after the batch barrier settles
 - Constraint: a breached agent cap cancels only its own batch
+- Constraint: accepts at most 4096 thunks per call
 
 <a id="runtime-global-pipeline"></a>
 ## pipeline
@@ -53,6 +55,21 @@ Every exact fact below is projected from the installed extension's capability co
 - Constraint: items run concurrently while stages per item run sequentially
 - Constraint: each stage receives previousValue, originalItem, and zero-based index
 - Constraint: a null stage result is passed to the next stage
+- Constraint: accepts at most 4096 items per call and awaits the whole batch before surfacing fatal errors
+
+<a id="runtime-global-orchestrate"></a>
+## orchestrate
+
+- Classification: `runtime-global`
+- Support: `supported`
+- Signature: `orchestrate(tasks, options?) => Promise<{ results, tasks }>`
+- `onError`: "skip-dependents"\|"continue"\|"fail-fast" (optional); default: "skip-dependents"
+- Constraint: task ids and dependencies are validated before any callback runs
+- Constraint: ready tasks run in declaration-order layers with a barrier between layers
+- Constraint: task context carries detached named results and statuses
+- Constraint: ordinary task failures can retry up to three times; fatal workflow errors propagate
+- Constraint: failed or skipped dependencies skip descendants by default; continue runs them with null values
+- Constraint: the graph accepts at most 128 tasks and emits task start/retry/end/skip runtime events
 
 <a id="runtime-global-workflow"></a>
 ## workflow
@@ -60,9 +77,9 @@ Every exact fact below is projected from the installed extension's capability co
 - Classification: `runtime-global`
 - Support: `supported`
 - Signature: `workflow(savedName, childArgs?) => Promise<unknown>`
-- Constraint: one nested level
+- Constraint: one nested level; concurrent sibling nested calls are allowed
 - Constraint: shares limiter, counters, token accounting, and store
-- Constraint: nested runs get unique runIds via nestedCallSeq
+- Constraint: nested calls use call-index/generation namespaces and replay as one parent result
 
 <a id="runtime-global-verify"></a>
 ## verify
@@ -270,6 +287,7 @@ Every exact fact below is projected from the installed extension's capability co
 - Support: `supported`
 - Signature: `resumeFromRunId?: string`
 - Constraint: resumes a prior incomplete run with an edited script
+- Constraint: original args and execution limits are reused on resume
 - Constraint: unchanged positional calls replay from cache until the first changed call
 - Constraint: always runs in the background
 

package/skills/workflow-authoring/references/focused-recipes.md

@@ -4,6 +4,7 @@ Read only the recipe matching the concern. Change task prompts, schemas, bounds,
 
 | Concern | Preserve when adapting | Tested recipe |
 | --- | --- | --- |
+| Named dependencies | Validate stable task IDs before dispatch; use the default skip policy unless dependents can consume `statuses` and null results. | [Named task graph](../examples/named-task-graph.js) |
 | Phased budgets | Phase and run budgets are soft pre-call gates; active work can overshoot. Report shared spend and bound calls independently. | [Phased budgets](../examples/phased-budgets.js) |
 | Saved workflows | Use a context-supplied name, await jobs sequentially, nest one level, and treat shared limits, counters, tokens, limiter, and store as parent capacity. | [Saved nested workflows](../examples/saved-nested-workflows.js) |
 | Semantic retry | Separate it from recoverable runtime retries. Use a new unique label per bounded attempt and return the attempt ledger plus exhausted outcome. | [Bounded semantic retry](../examples/bounded-semantic-retry.js) |

package/skills/workflow-authoring/references/lifecycle.md

@@ -2,7 +2,7 @@
 
 ## Bounds and budget
 
-Set finite bounds that match the work for `maxAgents`, `concurrency`, and `agentRetries`; bound loops and semantic retries inside the script. Treat invocation-level `agentTimeoutMs` and `tokenBudget` as opt-in user constraints, not precautionary defaults. Omit `tokenBudget` unless the user supplies a cap or explicitly asks you to choose one. If asked to choose, allow for every planned agent call, retry, synthesis, and verification pass, with headroom. A tight gate can terminate coverage; it does not reduce work already in flight. An omitted `agentTimeoutMs` uses the configured `defaultAgentTimeoutMs` and is otherwise unbounded. An omitted `tokenBudget` uses the configured `defaultTokenBudget` and is otherwise unlimited.
+Set finite bounds that match the work for `maxAgents`, `concurrency`, and `agentRetries`; bound graph tasks, fan-out items, loops, and semantic retries inside the script. A journal replay is logical work and does not consume the real-dispatch `maxAgents` cap, but it still counts toward reported call totals. Treat invocation-level `agentTimeoutMs` and `tokenBudget` as opt-in user constraints, not precautionary defaults. Omit `tokenBudget` unless the user supplies a cap or explicitly asks you to choose one. If asked to choose, allow for every planned agent call, retry, synthesis, and verification pass, with headroom. A tight gate can terminate coverage; it does not reduce work already in flight. An omitted `agentTimeoutMs` uses the configured `defaultAgentTimeoutMs` and is otherwise unbounded. An omitted `tokenBudget` uses the configured `defaultTokenBudget` and is otherwise unlimited.
 
 Enter a phase budget with `phase("Name", { budget: N })`; phase metadata does not carry budgets. `N` is a token allowance, not a call or round count: size it for the intended agent work instead of copying a small iteration limit. Token and phase budgets are soft pre-call gates. Spend lands after agents finish, so concurrent work can overshoot. A phase budget gates later calls in that phase; it neither reserves tokens nor cancels active calls. `budget.spent()` and `budget.remaining()` include nested work.
 
@@ -22,9 +22,9 @@ Always retain `{ id, status, result }` or an equivalent ledger for each intended
 
 ## Resume
 
-Resume replays only the longest unchanged prefix of journaled calls. Once one call is new, changed, or unusable, that call and all later calls execute live. Stable lexical call ordering, prompts, labels, routing options, and inputs therefore matter. Retry chains can cascade after an upstream miss. Nested workflows do not reuse the parent's resume journal.
+Resume replays only the longest unchanged prefix of journaled calls. Once one call is new, changed, or unusable, that call and all later calls execute live. Stable lexical call ordering, prompts, labels, routing options, and inputs therefore matter. Retry chains can cascade after an upstream miss. A nested workflow is cached as one parent call; an unchanged child replays its complete result, while a changed or interrupted child runs live in a generation-scoped namespace.
 
-Only a call that finishes with a real result is journaled. A call whose every attempt was recoverable (including one that only ever produced `AGENT_EMPTY_OUTPUT`) contributes no journal entry, so resuming that run reruns exactly that call and everything lexically after it live; the earlier, already-succeeded prefix still replays from cache.
+Only a call that finishes with a real result is journaled. A call whose every attempt was recoverable (including one that only ever produced `AGENT_EMPTY_OUTPUT`) contributes no journal entry, so resuming that run reruns exactly that call and everything lexically after it live; the earlier, already-succeeded prefix still replays from cache. Schema repair retries include the concrete validation errors in the next prompt.
 
 The runtime blocks common accidental nondeterminism, but this is not a security boundary. Pass timestamps, randomness, and external decisions through `args`.
 

package/skills/workflow-authoring/references/pattern-selection.md

@@ -5,6 +5,7 @@ Choose from data dependencies, then read only the matching example. JavaScript o
 <a id="fan-out-and-synthesize"></a>
 | Dependency shape | Pattern | Preserve when adapting | Example |
 | --- | --- | --- | --- |
+| Named steps have explicit dependencies | Named task graph | Give every task a stable ID; let `orchestrate()` validate cycles, run declaration-order layers, and pass named results/statuses to dependents | [Adapt](../examples/named-task-graph.js) |
 | Heterogeneous items need different handling | Classify and act | Finish all classification before routed action; ledger classification and action failures by item ID | [Adapt](../examples/classify-and-act.js) |
 | Independent work needs whole-set judgment | Fan out and synthesize | Pass thunks; await the full set; give synthesis every intended ID, including `null` | [Adapt](../examples/fan-out-and-synthesize.js) |
 | Claims need skeptical checks | Adversarial verification | Use separate producer and skeptic calls; start skepticism after production; ledger both failures | [Adapt](../examples/adversarial-verification.js) |

package/skills/workflow-authoring/references/registry-ownership.md

@@ -12,6 +12,6 @@ The agent registry owns agent-type names and their bound instructions, tools, mo
 
 ## Priority
 
-Routing priority is explicit `model` > named `tier` > phase/run model > pi-subagents agent configuration > parent session. Higher priority means selection, not "try this then fall back to the next selector." Avoid specifying competing selectors unless deliberately overriding a lower-priority default.
+An explicit per-call `model` wins. A named `agentType` model overrides a tier; an explicit `tier` suppresses the phase/run model so pi-subagents can apply the agent definition and then the selected workflow tier. Without a per-call model or tier, the phase/run model is used when present, followed by pi-subagents defaults and the parent session. Model and thinking fields are resolved independently. Avoid specifying competing selectors unless the override is deliberate.
 
 Unavailability is fail-closed for explicit `model` and named tiers: pi-subagents reports the selector and does not silently run a different model. An omitted selector may inherit the parent session according to the companion's current settings.

package/skills/workflow-authoring/references/review.md

@@ -11,10 +11,10 @@ Review author-visible behavior, not formatting preferences. When behavior depend
 
 ## Topology and identity
 
-- Does topology match dependencies: thunks for independent parallel work, stages for per-item pipelines, barriers before whole-set synthesis?
-- Is cardinality bounded before fan-out?
+- Does topology match dependencies: `orchestrate` for named graphs, thunks for independent parallel work, stages for per-item pipelines, barriers before whole-set synthesis?
+- Is cardinality bounded before graph construction and fan-out?
 - Is every agent label short and unique?
-- Are stable work-unit IDs retained beside ordered results?
+- Are stable graph/work-unit IDs retained beside ordered results?
 - Are failed/null identities recorded before any filtering?
 
 ## Data and routing
@@ -30,12 +30,14 @@ Review author-visible behavior, not formatting preferences. When behavior depend
 - Are loops, agents, concurrency, timeout, and token spend bounded appropriately?
 - Are budget claims honest about soft gates and in-flight overshoot?
 - Are checkpoints limited to implemented confirmation/headless behavior?
-- Does nesting stay one level and account for shared limits/store?
-- Would lexical call order remain stable under resume?
+- Does nesting stay one level, allow only safe sibling concurrency, and account for shared limits/store?
+- Are helper attempts and graph retries finite and separately visible?
+- Would lexical call order and generated graph order remain stable under resume?
 
 ## Compatibility and publication
 
 - Does new code use `log()` rather than compatibility-only `console`?
+- Are runtime progress events and background result delivery described without promising durability the engine does not provide?
 - Is compatibility behavior clearly distinguished from supported authoring behavior and VM substrate?
 - Do package, skill, and generated contract versions match?
 - Do all relative links resolve within the publishable package?

package/skills/workflow-authoring/references/runtime.md

@@ -6,13 +6,14 @@ Use this page for routine scripts. Open the generated capability index only when
 
 Start with the only legal export: `export const meta = { name, description, phases?: [{ title, detail?, model? }] }`. Values are nonblank literals; declare only used phases and call `phase()` before each phase's work. The remaining body already runs inside an async function: write helpers as ordinary declarations; `export default` and other exports are invalid. Return the result explicitly.
 
-The runtime supplies `agent`, `parallel`, `pipeline`, `workflow`, quality/control helpers, `phase`, `log`, `args`, `cwd`, restricted `process.cwd()`, and `budget`. Imports, `require()`, filesystem modules, `Date.now()`, `Math.random()`, and no-argument `new Date()` are unavailable. The Node VM realm is implementation substrate, not a security boundary or public API.
+The runtime supplies `agent`, `parallel`, `pipeline`, `orchestrate`, `workflow`, quality/control helpers, `phase`, `log`, `args`, `cwd`, restricted `process.cwd()`, and `budget`. Imports, `require()`, filesystem modules, `Date.now()`, `Math.random()`, and no-argument `new Date()` are unavailable. The Node VM realm is implementation substrate, not a security boundary or public API.
 
 ## Topology
 
 - `parallel()` takes thunks, runs independent work, and preserves input order. Await the whole array before whole-set synthesis.
 - `pipeline()` runs stages sequentially per item while items proceed concurrently. Each stage receives `(previousValue, originalItem, index)` and forwards `null` to the next stage, so guard missing coverage first.
-- `workflow(name, childArgs?)` runs a context-supplied saved workflow. Nesting is one level and shares limits, counters, tokens, and store.
+- `orchestrate()` is the preferred topology for named dependencies. Give each task a unique `id`, optional `dependsOn`, and a `run({ id, attempt, results, statuses })` callback. The runtime validates the graph, executes declaration-order ready layers behind barriers, and returns `{ results, tasks }`; use `onError: "continue"` only when a downstream task can handle failed dependencies.
+- `workflow(name, childArgs?)` runs a context-supplied saved workflow. Nesting is one level, shares limits/counters/tokens/store, and journals the complete child result as one parent replay boundary.
 
 ## Data and failure
 
@@ -24,6 +25,6 @@ When JavaScript reads fields, pass a small plain JSON Schema. Schema noncomplian
 
 ## Routing and support
 
-Selector priority is explicit `model` > named `tier` > phase/run model > pi-subagents agent configuration > parent session. An unavailable explicit selector fails closed rather than silently choosing another model. Worktree isolation is also fail-closed and remains owned by pi-subagents. See [registry ownership](registry-ownership.md).
+An explicit per-call `model` wins. A named `agentType` model overrides `tier`; specifying `tier` suppresses the phase/run model and delegates model/thinking resolution to pi-subagents. Without a per-call selector, the phase/run model is used when present, followed by pi-subagents defaults and the parent session. Explicit unavailable models and tiers fail closed. Worktree isolation is also fail-closed and remains owned by pi-subagents. See [registry ownership](registry-ownership.md).
 
 Generated entries marked `supported` are authoring API. `console` and whole-script Markdown fences are compatibility-only. VM realm facilities are internal. Active model routes and agent types are dynamic. Use `log()` in new scripts.