@signalridge/pi-workflows 1.6.0 → 1.7.0

package/CHANGELOG.md

@@ -1,5 +1,118 @@
 # Changelog
 
+## 1.7.0
+### Minor Changes
+
+- f05185e: A workflow now runs at the width of the host's subagent pool rather than a
+  number it picked blind, and stops charging queue time against the agent waiting
+  in it.
+  
+  Two facts were missing on the pi-workflows side, and they compounded. It had no
+  way to learn `maxConcurrent`, so its own width was a constant guess. And a
+  dispatched agent was treated as a running one, though a managed spawn takes a
+  background slot like any other and waits when the pool is full, so a batch
+  dispatched behind a busy pool could fail as timeouts with none of it having run.
+  
+  - The ping reply can now carry the peer's live `maxConcurrent`, and pi-workflows
+    makes it both the default width and the ceiling: an unnamed `concurrency` takes
+    the pool size, and a named one is clamped to it, with the clamp recorded in the
+    run log so a caller who asked for a number learns why it got another. It is
+    read at each start and resume rather than frozen onto the run, because the pool
+    is a setting the user can change in between. One setting therefore governs the
+    whole fleet, which is what the ownership boundary already said and what the
+    code can now honour.
+  - **This narrows the common case, and that is the point.** The pool defaults to
+    4 background slots, so a default pair now runs a fan-out four at a time where
+    it used to dispatch `hardwareConcurrency - 2`. Nothing runs slower for it —
+    dispatching twelve into four slots only ever queued eight, ahead of the host's
+    own spawns — but the width a run reports is now the width it actually has, and
+    `maxConcurrent` is the single place to raise it for workflows and every other
+    background agent at once. A host that had already raised it gets the wide
+    fan-outs its setting always implied.
+  - The field is **requested by name** (`include: ["maxConcurrent"]`) rather than
+    volunteered. A ping envelope is parsed with `rejectUnknownKeys`, so a peer that
+    simply added a field would make every already-published caller reject the
+    handshake and lose workflows entirely. Asking keeps both directions working: an
+    older peer answers without it and the caller falls back to 16, and a caller that
+    never asks gets the v4 envelope unchanged. No version bump, no capability, no
+    lockstep release. Both READMEs document the mechanism, since `include` is now
+    part of the public cross-extension contract.
+  - `agentTimeoutMs` now counts from the moment the host reports the agent left its
+    queue. The clock is still armed at dispatch and restarted on that report, not
+    armed only by it, so a report that never arrives degrades to the old behaviour
+    rather than to an agent that can hang forever. A report that arrives *after* the
+    agent settled is ignored, so a late or duplicate one cannot leave a live timer
+    behind to abort a finished agent.
+  
+  The engine already subscribed to `subagents:started` and already filtered it by
+  workflow owner, so the start signal is the event it was discarding.
+  
+  `getMaxConcurrent` is required on the RPC bridge rather than optional. The other
+  bridge members are capabilities, advertised in the ping and rejected outright
+  when missing, so forgetting one fails loudly; a missing pool size has no
+  capability bit and no failure — the caller would silently fall back to its own
+  guess and run at the wrong width. Required is what makes that omission a compile
+  error instead of a quiet wrong answer.
+- f05185e: Stop the run's own limits from being the thing that keeps a fan-out small.
+  
+  Every execution limit a caller can pass — `maxAgents`, `concurrency`,
+  `agentRetries`, `tokenBudget`, `agentTimeoutMs` — reached the model as a bare
+  number with no stated default, while the authoring skill asked it to "set finite
+  bounds that match the work" for three of them. The result was a caller that
+  priced the run before writing it: fan-outs of one to eight, `concurrency: 1`,
+  and per-agent wall clocks of two to five minutes. Each of those values ends a run
+  rather than shaping it — `AGENT_LIMIT_EXCEEDED` partway through, or a whole
+  batch failing as timeouts — so the precaution removed coverage and not cost.
+  
+  Four changes, and the first two matter most:
+  
+  - Every numeric tool input now states its default and says to omit it, and the
+    guidelines ask for a fan-out sized to the evidence the task has: one agent per
+    independent question, ten to thirty for an ordinary review or audit. The gain
+    named is coverage, not speed — one agent asked one question reads further into
+    it than one agent asked four — because how many of them run at once is the
+    host's pool and not the script's to decide. The authoring and review skills no
+    longer treat the invocation limits as the place to express a bound — that
+    belongs to the script's own task counts, loop rounds, and fan-out widths, which
+    is where the topology is decided. `lifecycle.md` also stops citing two settings
+    keys that never existed (`defaultAgentTimeoutMs`, `defaultTokenBudget`).
+  - `agentTimeoutMs` defaults to 30 minutes rather than 5. It exists to bound a
+    hang; an agent's real budget is the turn, tool and token ceiling pi-subagents
+    applies to it, which a deep call legitimately spends over many minutes. A
+    default an order of magnitude under that budget turned every wide fan-out of
+    real work into a batch of timeouts. `null` still removes the wall clock.
+  - Concurrency defaults to 16 and clamps at 64, up from a default of
+    `hardwareConcurrency - 2` clamped at 16. Core count was the wrong quantity: a
+    dispatched agent is a remote call this process waits on, so the old default
+    fanned a 14-core host out 12 ways and a 4-core host 2 ways for identical work.
+    pi-subagents' `maxConcurrent` remains the authoritative throttle — this is the
+    guard against a runaway script, and a host that wants a narrower fleet still
+    narrows it in one place for every agent it runs.
+  - `strength` gains a criterion instead of three bare words. `high` now means a
+    step whose error is expensive to reverse — an architecture decision, a
+    destructive migration, a security boundary — normally absent from a fan-out and
+    at most one closing step, and the authoring skill and review checklist both say
+    so. The ULTRA effort directive stops asking for it outright: it used to end
+    `give the deepest steps strength: "high"`, which priced every branch of a wide
+    run at the cost of the one that mattered, and now points the exhaustiveness at
+    width and reserves `high` for a step that has that property, if the run has one.
+    Nothing about the mechanism changed — there is still no default strength, and a
+    call naming none still dispatches with no tier.
+  - `/workflows run` plans up to 24 tasks instead of 8. The planner's JSON schema
+    was the only bound on the one path where the model decides the width itself,
+    and 8 was below what an ordinary audit decomposes into. The synthesis step
+    absorbs the extra tasks by shrinking its per-worker excerpt: measured against
+    the 78,000-character context budget, 8 tasks contribute about 6,000 characters
+    each and 24 contribute about 2,500 — three times the coverage at roughly 40%
+    of the depth per worker, and about a quarter more total evidence reaching the
+    synthesizer. Widening past that would need a larger budget, which the wire's
+    100,000-character prompt cap does not leave room for.
+
+### Patch Changes
+
+- Updated dependencies [f05185e]
+  - @signalridge/pi-subagents-protocol@1.5.0
+
 ## 1.6.0
 ### Minor Changes
 

package/README.md

@@ -145,8 +145,31 @@ 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`.
+  with `args`, `background` (default true), `maxAgents` (default 1000),
+  `concurrency` (defaults to the host's pool size), `agentRetries` (default 0),
+  `tokenBudget` (default unlimited), `agentTimeoutMs` (default 1800000, `null`
+  disables), and `resumeFromRunId`. The execution limits are tuned defaults: a
+  caller that names one narrower than the script needs stops the run rather
+  than shaping it.
+
+  Concurrency is not configured here at all. A workflow agent occupies one of
+  pi-subagents' `maxConcurrent` background slots like any other background
+  agent, so that setting is both the width a run defaults to and the ceiling it
+  is clamped to — read live from the peer at each start and resume, so one
+  setting governs the whole fleet and a run neither guesses it nor exceeds it.
+  The peer publishes it only to a caller that requests it by name, so an older
+  pair still handshakes; a run that learns no pool size falls back to 16. A
+  request above the pool is clamped and the run log says so.
+
+  In practice that pool is usually the *narrower* number, not the wider one: it
+  defaults to 4 background slots, so a default pair runs a fan-out four at a
+  time. That is the honest width rather than a new restriction — dispatching
+  twelve into four slots only ever queued eight — but it does mean a wide
+  fan-out finishes in waves, and `maxConcurrent` is the one place to change
+  that, for workflows and for every other background agent at once.
+
+  `agentTimeoutMs` counts from the moment the host reports the agent left its
+  queue, so waiting for a slot is never charged against the work.
 - `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`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalridge/pi-workflows",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Deterministic JavaScript orchestration workflows backed by pi-subagents managed spawning.",
   "type": "module",
   "license": "MIT",
@@ -20,7 +20,7 @@
     "@signalridge/pi-subagents": ">=1.9.0"
   },
   "dependencies": {
-    "@signalridge/pi-subagents-protocol": "^1.4.0",
+    "@signalridge/pi-subagents-protocol": "^1.5.0",
     "@sinclair/typebox": "^0.34.50",
     "acorn": "^8.16.0"
   },

package/skills/workflow-authoring/SKILL.md

@@ -2,7 +2,7 @@
 name: workflow-authoring
 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.6.0"
+  version: "1.7.0"
 ---
 
 # Workflow authoring
@@ -25,9 +25,19 @@ JavaScript.
 - 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.
+- Bound the algorithm inside the script: graph tasks, fan-out items, loop
+  rounds, semantic retries, and evidence size. The invocation-level limits
+  (`maxAgents`, `concurrency`, `agentRetries`, `tokenBudget`, `agentTimeoutMs`)
+  are tuned defaults rather than the place to express a bound; each one stops or
+  fails a run that outgrows it, so a precautionary value cuts the coverage and
+  not the cost. Set one only when the user asked for that limit.
+- Size the fan-out to the evidence the task actually has: one agent per
+  independent question, ten to thirty for an ordinary review or audit. The gain
+  is coverage — one agent asked one question reads further into it than one
+  agent asked four. Speed is a separate matter and not yours to decide: how many
+  of those agents run at once is the host's `maxConcurrent` pool, so a wide
+  fan-out on a narrow pool still finishes in waves. Split for what gets looked
+  at, not for wall-clock.
 - Route an agent call with `strength: "low" | "medium" | "high"` — this
   package's own word for how much effort a step deserves, and the only routing
   word a workflow has. It is **not** an agent-tier key: a `strengths` table
@@ -44,6 +54,15 @@ JavaScript.
   documented keys. Never guess an agent-type name—use
   names supplied by the current environment and follow
   [registry ownership](references/registry-ownership.md).
+- Pick that word by what a wrong answer costs, not by how important the step
+  feels. `low` is retrieval, navigation, and read-heavy breadth. `medium` is the
+  ordinary working rung and where a labelled step belongs unless you can say why
+  not. `high` is for a step whose error is expensive to reverse — an architecture
+  decision, a destructive migration, a security boundary — and a fan-out normally
+  names it zero times, at most once on a closing step that actually decides
+  something. It is not a reward for the hardest-sounding task: routing a whole
+  fan-out to `high` prices every branch at the cost of the one that mattered, and
+  buys depth where the run needed coverage.
 - Workflows have no imports, filesystem/network APIs, timers, or unrestricted
   Node APIs. Pass timestamps, randomness, and external decisions through `args`.
 

package/skills/workflow-authoring/examples/defensive-json-parsing.js

@@ -31,7 +31,7 @@ function parseOrFlag(text, requiredKeys) {
 }
 
 // ADAPT: validate and bound work, then keep required fields as small as downstream JavaScript needs.
-const work = args && Array.isArray(args.work) ? args.work.slice(0, 8) : [{ id: "sample" }];
+const work = args && Array.isArray(args.work) ? args.work.slice(0, 24) : [{ id: "sample" }];
 const requiredKeys = ["verdict", "reason"];
 const outputs = [];
 const missing = [];

package/skills/workflow-authoring/examples/phased-budgets.js

@@ -5,7 +5,7 @@ export const meta = {
 };
 
 // ADAPT: validate the work and choose phase budgets, prompts, and schemas; add invocation-level tokenBudget only when the user explicitly requests a cap.
-const work = args && Array.isArray(args.work) ? args.work.slice(0, 8) : [{ id: "sample" }];
+const work = args && Array.isArray(args.work) ? args.work.slice(0, 24) : [{ id: "sample" }];
 const phaseBudget =
   args && Number.isFinite(args.phaseBudget) ? Math.max(1, Math.min(args.phaseBudget, 100000)) : 2000;
 const resultSchema = {

package/skills/workflow-authoring/examples/saved-nested-workflows.js

@@ -7,7 +7,7 @@ export const meta = {
 // ADAPT: accept only a saved workflow name supplied in context; never guess an installed name.
 const savedWorkflowName = args && typeof args.savedWorkflowName === "string" ? args.savedWorkflowName : null;
 if (!savedWorkflowName) throw new Error("args.savedWorkflowName must be supplied by context");
-const jobs = args && Array.isArray(args.jobs) ? args.jobs.slice(0, 8) : [{ id: "sample" }];
+const jobs = args && Array.isArray(args.jobs) ? args.jobs.slice(0, 24) : [{ id: "sample" }];
 const preparationSchema = {
   type: "object",
   properties: { ready: { type: "boolean" } },

package/skills/workflow-authoring/examples/structured-output.js

@@ -5,7 +5,7 @@ export const meta = {
 };
 
 // ADAPT: validate and bound work, then keep the schema as small as downstream JavaScript needs.
-const work = args && Array.isArray(args.work) ? args.work.slice(0, 8) : [{ id: "sample" }];
+const work = args && Array.isArray(args.work) ? args.work.slice(0, 24) : [{ id: "sample" }];
 const outputSchema = {
   type: "object",
   properties: {

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

@@ -2,7 +2,7 @@
 # Workflow capability index
 
 Contract format: `2.0.0`<br>
-Contract content / skill / extension: `1.6.0`
+Contract content / skill / extension: `1.7.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).
 
@@ -11,7 +11,7 @@ This compact generated index covers supported runtime globals and workflow-tool
 <!-- BEGIN GENERATED SUPPORTED WORKFLOW CAPABILITIES -->
 | Name | Classification | Signature | Options and defaults |
 | --- | --- | --- | --- |
-| 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>`strength`: "low" \| "medium" \| "high" (optional); default: no tier is sent; the agent's own tier, else agentTiers.defaultTier<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 |
+| 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>`strength`: "low" \| "medium" \| "high" (optional); default: no tier is sent; the agent's own tier, else agentTiers.defaultTier<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: 1800000 (30min); 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" |
@@ -35,9 +35,9 @@ This compact generated index covers supported runtime globals and workflow-tool
 | args | workflow-tool-input | `args?: unknown` | — |
 | background | workflow-tool-input | `background?: boolean = true` | — |
 | maxAgents | workflow-tool-input | `maxAgents?: number = 1000` | — |
-| concurrency | workflow-tool-input | `concurrency?: number` | — |
+| concurrency | workflow-tool-input | `concurrency?: number = the host's pi-subagents maxConcurrent` | — |
 | agentRetries | workflow-tool-input | `agentRetries?: number = 0` | — |
-| agentTimeoutMs | workflow-tool-input | `agentTimeoutMs?: number = 300000` | — |
+| agentTimeoutMs | workflow-tool-input | `agentTimeoutMs?: number = 1800000` | — |
 | tokenBudget | workflow-tool-input | `tokenBudget?: number` | — |
 | resumeFromRunId | workflow-tool-input | `resumeFromRunId?: string` | — |
 | export const meta | script-contract | `export const meta = { name, description, phases? }` | — |

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

@@ -2,7 +2,7 @@
 # Exhaustive workflow capability facts
 
 Contract format: `2.0.0`<br>
-Contract content / skill / extension: `1.6.0`
+Contract content / skill / extension: `1.7.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.
 
@@ -22,7 +22,7 @@ Every exact fact below is projected from the installed extension's capability co
 - `toolset`: string (optional); default: configured host/agent toolset hint
 - `excludeTools`: string[] (optional)
 - `agentType`: string (optional); default: general-purpose
-- `timeoutMs`: number \| null (optional); default: 300000 (5min); null disables
+- `timeoutMs`: number \| null (optional); default: 1800000 (30min); null disables
 - `retries`: number (optional); default: run retry count
 - Constraint: recoverable failures return null after retries; nonrecoverable failures throw
 - Constraint: schema noncompliance after bounded repair attempts is nonrecoverable
@@ -262,8 +262,12 @@ Every exact fact below is projected from the installed extension's capability co
 
 - Classification: `workflow-tool-input`
 - Support: `supported`
-- Signature: `concurrency?: number`
-- Constraint: runtime clamps to 1..16
+- Signature: `concurrency?: number = the host's pi-subagents maxConcurrent`
+- Constraint: runtime clamps to 1..64
+- Constraint: read live from the peer at each start and resume, and also the ceiling: a request above the pool is clamped to it, and the run log records the clamp
+- Constraint: 16 is only the fallback for a peer that publishes no pool size
+- Constraint: pi-subagents maxConcurrent stays the authoritative throttle; one setting governs the whole fleet
+- Constraint: that pool is typically small (4 slots by default), so a wide fan-out runs in waves rather than all at once
 
 <a id="workflow-tool-input-agentretries"></a>
 ## agentRetries
@@ -278,8 +282,10 @@ Every exact fact below is projected from the installed extension's capability co
 
 - Classification: `workflow-tool-input`
 - Support: `supported`
-- Signature: `agentTimeoutMs?: number = 300000`
-- Constraint: null disables the hard timeout; default 300000ms (5min)
+- Signature: `agentTimeoutMs?: number = 1800000`
+- Constraint: null disables the hard timeout; default 1800000ms (30min)
+- Constraint: it bounds a hang only; an agent's real budget is the host's turn, tool and token ceiling
+- Constraint: the clock restarts when the host reports the agent left its queue, so waiting for a slot is not charged as work
 
 <a id="workflow-tool-input-tokenbudget"></a>
 ## tokenBudget

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

@@ -2,7 +2,11 @@
 
 ## Bounds and budget
 
-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.
+Bound the work where the work is decided: graph tasks, fan-out items, loop rounds, semantic retries, and evidence size, all inside the script. The invocation-level limits are not that place. `maxAgents` (1000), `concurrency` (the host's pool, and 16 only when it publishes none, clamped either way to 64), `agentRetries` (0) and `agentTimeoutMs` (1800000ms, `null` to disable) are tuned defaults, and `tokenBudget` is unlimited unless set; each one stops or fails a run that outgrows it, so a precautionary value removes coverage rather than cost. Pass one only when the user asked for that limit — a `maxAgents` under the script's own dispatch count ends the run with `AGENT_LIMIT_EXCEEDED` partway, and an `agentTimeoutMs` shorter than the host's turn/tool/token budget fails a whole fan-out as timeouts. A journal replay is logical work and does not consume the real-dispatch `maxAgents` cap, but it still counts toward reported call totals. If the user does ask for a token cap, allow for every planned agent call, retry, synthesis, and verification pass, with headroom: a tight gate terminates coverage and does not reduce work already in flight.
+
+`concurrency` needs no value at all: it defaults to the host's pi-subagents `maxConcurrent`, read live at each start and resume, and a larger request is clamped to it (the run log records the clamp). Dispatching wider would not run wider — a workflow agent takes one of those background slots like any other, so the surplus would only wait in the host's queue, ahead of the host's own spawns. Name a number here only to run *narrower* than the host allows, and only when the user asked for that.
+
+That pool is typically small — 4 slots unless the host was configured otherwise — so assume a wide fan-out runs in waves, not all at once. This does not change how wide to make it: the agents all run either way, and the reason to split work is coverage rather than wall-clock. It does mean a script should not promise the user a fast answer because it fanned out, and should not add a checkpoint or a progress phase that only makes sense if everything starts together.
 
 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.
 

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

@@ -30,7 +30,10 @@ Review author-visible behavior, not formatting preferences. When behavior depend
 ## Lifecycle
 
 - Are runtime retries and semantic retries separately bounded?
-- Are loops, agents, concurrency, timeout, and token spend bounded appropriately?
+- Are loops, graph tasks, fan-out items, and semantic retries bounded inside the script, where the topology is decided?
+- Does the invocation leave `maxAgents`, `concurrency`, `agentRetries`, `tokenBudget` and `agentTimeoutMs` at their defaults unless the user asked for that limit? A precautionary value there removes coverage, not cost.
+- Is the fan-out as wide as the evidence the task has, rather than narrowed by habit?
+- Does `high` appear only on a step whose error is expensive to reverse — normally nowhere, at most once — rather than across a fan-out?
 - Are budget claims honest about soft gates and in-flight overshoot?
 - Are checkpoints limited to implemented confirmation/headless behavior?
 - Does nesting stay one level, allow only safe sibling concurrency, and account for shared limits/store?

package/skills/workflow-patterns/SKILL.md

@@ -2,7 +2,7 @@
 name: workflow-patterns
 description: Choose and run one of Pi's built-in multi-agent workflows for research, adversarial review, code review, multi-perspective analysis, or codebase auditing. Use when the request matches a named pattern; use workflow-authoring instead for a new script or custom topology.
 metadata:
-  version: "1.6.0"
+  version: "1.7.0"
 ---
 
 # Built-in workflow patterns

package/skills/workflow-review/SKILL.md

@@ -2,7 +2,7 @@
 name: workflow-review
 description: Audit an existing Pi JavaScript workflow for topology, prompt/data flow, limits, failure handling, cancellation, resume safety, and publication compatibility. Use when reviewing or debugging a workflow script or saved run; do not use to run a standard named workflow.
 metadata:
-  version: "1.6.0"
+  version: "1.7.0"
 ---
 
 # Workflow review
@@ -25,9 +25,11 @@ they are available.
    values and their bounds. Confirm that structured fields have a schema and
    that failed/null results remain visible in a ledger.
 4. **Check admission.** Verify finite bounds for task count, fan-out, loops,
-   retries, concurrency, token budget, timeout, and evidence size. Check that
-   a graph validates IDs, references, duplicate edges, and cycles before any
-   callback runs.
+   retries, and evidence size inside the script, and that the invocation leaves
+   `maxAgents`, `concurrency`, `tokenBudget` and `agentTimeoutMs` at their
+   defaults unless the user asked for that limit — a precautionary value there
+   removes coverage rather than cost. Check that a graph validates IDs,
+   references, duplicate edges, and cycles before any callback runs.
 5. **Check failure policy.** Distinguish recoverable child `null` from fatal
    workflow errors. For graphs, verify whether the default
    `skip-dependents`, explicit `continue`, or `fail-fast` policy matches the

package/src/capabilities.ts

@@ -63,7 +63,7 @@ export const WORKFLOW_CAPABILITIES: readonly CapabilityEntry[] = [
       { name: "toolset", kind: "string", optional: true, default: "configured host/agent toolset hint" },
       { name: "excludeTools", kind: "string[]", optional: true, default: "none" },
       { name: "agentType", kind: "string", optional: true, default: "general-purpose" },
-      { name: "timeoutMs", kind: "number | null", optional: true, default: "300000 (5min); null disables" },
+      { name: "timeoutMs", kind: "number | null", optional: true, default: "1800000 (30min); null disables" },
       { name: "retries", kind: "number", optional: true, default: "run retry count" },
     ],
     constraints: [
@@ -284,9 +284,15 @@ export const WORKFLOW_CAPABILITIES: readonly CapabilityEntry[] = [
   {
     name: "concurrency",
     classification: "workflow-tool-input",
-    signature: "concurrency?: number",
+    signature: "concurrency?: number = the host's pi-subagents maxConcurrent",
     options: [],
-    constraints: ["runtime clamps to 1..16"],
+    constraints: [
+      "runtime clamps to 1..64",
+      "read live from the peer at each start and resume, and also the ceiling: a request above the pool is clamped to it, and the run log records the clamp",
+      "16 is only the fallback for a peer that publishes no pool size",
+      "pi-subagents maxConcurrent stays the authoritative throttle; one setting governs the whole fleet",
+      "that pool is typically small (4 slots by default), so a wide fan-out runs in waves rather than all at once",
+    ],
   },
   {
     name: "agentRetries",
@@ -298,9 +304,13 @@ export const WORKFLOW_CAPABILITIES: readonly CapabilityEntry[] = [
   {
     name: "agentTimeoutMs",
     classification: "workflow-tool-input",
-    signature: "agentTimeoutMs?: number = 300000",
+    signature: "agentTimeoutMs?: number = 1800000",
     options: [],
-    constraints: ["null disables the hard timeout; default 300000ms (5min)"],
+    constraints: [
+      "null disables the hard timeout; default 1800000ms (30min)",
+      "it bounds a hang only; an agent's real budget is the host's turn, tool and token ceiling",
+      "the clock restarts when the host reports the agent left its queue, so waiting for a slot is not charged as work",
+    ],
   },
   {
     name: "tokenBudget",

package/src/engine.ts

@@ -136,12 +136,32 @@ interface AgentLifecycleWaiter {
   generation: number;
   onUsage?: (usage: AgentUsage) => void;
   onHistory?: (history: unknown[]) => void;
+  /** Told once when the host reports this agent left the queue and started. */
+  onRunning?: () => void;
+  startedNotified: boolean;
   executionGeneration: number;
   resolve: (response: ManagedSpawnResponse) => void;
   reject: (error: unknown) => void;
   settled: boolean;
 }
 
+/**
+ * Tell a waiter once that its agent started.
+ *
+ * Once, because the wall clock is restarted from this point: a repeated report
+ * — a duplicate event, or a reply that raced its own lifecycle event — would
+ * keep pushing the deadline out and quietly turn the timeout off.
+ */
+function notifyAgentRunning(waiter: AgentLifecycleWaiter): void {
+  if (waiter.startedNotified || waiter.settled) return;
+  waiter.startedNotified = true;
+  try {
+    waiter.onRunning?.();
+  } catch {
+    /* the clock is best effort; never fail a live agent over it */
+  }
+}
+
 interface AgentTerminalDelivery {
   response: ManagedSpawnResponse;
   usage?: AgentUsage;
@@ -432,6 +452,10 @@ export class WorkflowEngine {
     if (updateCallTierIdentity(state, callNodeId, data.tier)) {
       this.persistCallTierIdentity(state, callNodeId);
     }
+    // A start is the moment the host admitted this agent from its queue. It is
+    // the only signal that separates waiting for a slot from doing the work, so
+    // the call's wall clock is restarted here rather than at dispatch.
+    if (eventName === "subagents:started" && waiterMatches && waiter) notifyAgentRunning(waiter);
     // Created/started lifecycle facts carry managed identity before the RPC
     // reply is necessarily available. They are observation-only here; terminal
     // ownership is handled below once a completion/failure fact arrives.
@@ -1010,6 +1034,10 @@ export class WorkflowEngine {
           : {
               routingPolicy: protocol.routingPolicy,
               routingPolicyFingerprint: protocol.routingPolicyFingerprint,
+              // Read live at each start and resume, never frozen onto the run:
+              // the pool is a host setting the user can change between them, and
+              // a run that outlived a narrowing would dispatch into a queue.
+              ...(protocol.maxConcurrent === undefined ? {} : { hostMaxConcurrent: protocol.maxConcurrent }),
             }),
         concurrency: options.concurrency,
         agentRetries: options.agentRetries,
@@ -1287,11 +1315,17 @@ export class WorkflowEngine {
         executionGeneration,
         onUsage: runOptions.onUsage,
         onHistory: runOptions.onHistory,
+        onRunning: runOptions.onRunning,
+        startedNotified: false,
         settled: false,
         resolve,
         reject,
       };
       state.agentWaiters.set(pendingId, waiter);
+      // A spawn that was admitted straight away is already running, and its
+      // `subagents:started` event fired before this waiter existed. Only a
+      // reply that says "queued" still has a start to wait for.
+      if (typeof response !== "string" && response.state !== "queued") notifyAgentRunning(waiter);
       externalSignal.addEventListener("abort", waitAbort, { once: true });
       if (externalSignal.aborted) {
         waitAbort();

package/src/index.ts

@@ -36,11 +36,40 @@ const WorkflowToolSchema = Type.Object(
     name: Type.Optional(Type.String({ minLength: 1, maxLength: 128 })),
     args: Type.Optional(Type.Any()),
     background: Type.Optional(Type.Boolean()),
-    maxAgents: Type.Optional(Type.Number({ minimum: 1 })),
-    concurrency: Type.Optional(Type.Number({ minimum: 1 })),
-    agentRetries: Type.Optional(Type.Number({ minimum: 0, maximum: 3 })),
-    tokenBudget: Type.Optional(Type.Number({ minimum: 1 })),
-    agentTimeoutMs: Type.Optional(Type.Number({ minimum: 1 })),
+    maxAgents: Type.Optional(
+      Type.Number({
+        minimum: 1,
+        description:
+          "Cap on real agent dispatches for this run. Default 1000, which no ordinary script reaches. Omit it: a value below what the script dispatches stops the run partway with AGENT_LIMIT_EXCEEDED.",
+      }),
+    ),
+    concurrency: Type.Optional(
+      Type.Number({
+        minimum: 1,
+        description:
+          "Agents in flight at once. Defaults to the host's own subagent pool size, which is also the ceiling. Omit it: a lower number runs the same work more slowly and buys nothing, and a higher one is clamped.",
+      }),
+    ),
+    agentRetries: Type.Optional(
+      Type.Number({
+        minimum: 0,
+        maximum: 3,
+        description: "Retries for a recoverable agent failure. Default 0; a failed call returns null to the script.",
+      }),
+    ),
+    tokenBudget: Type.Optional(
+      Type.Number({
+        minimum: 1,
+        description: "Soft token ceiling for the whole run. Default unlimited; exhausting a set budget aborts the run.",
+      }),
+    ),
+    agentTimeoutMs: Type.Optional(
+      Type.Number({
+        minimum: 1,
+        description:
+          "Wall clock per agent, there to bound a hang. Default 1800000 (30min), and it counts from when the agent actually starts, not from dispatch. An agent's real budget is the host's turn, tool and token ceiling. Omit it: a short value fails an entire fan-out as timeouts.",
+      }),
+    ),
     resumeFromRunId: Type.Optional(Type.String({ minLength: 1, maxLength: 128 })),
   },
   { additionalProperties: false },
@@ -139,7 +168,7 @@ function formatStart(result: ScriptStartResult): string {
 export function buildAdHocWorkflowScript(prompt: string): string {
   return `export const meta = { name: "ad-hoc", description: "Plan, execute, and synthesize a bounded multi-agent task graph" };
 const originalPrompt = ${JSON.stringify(prompt)};
-const plan = await agent("Design a bounded execution plan for this user task. Return 1-8 independent or dependency-linked tasks. Use unique short ids, concise descriptions, exact worker prompts, and only dependencies that appear in the task list. Prefer independent tasks when possible. User task:\\n\\n" + originalPrompt, {
+const plan = await agent("Design a bounded execution plan for this user task. Return 1-24 independent or dependency-linked tasks. Use unique short ids, concise descriptions, exact worker prompts, and only dependencies that appear in the task list. Prefer independent tasks when possible, and prefer narrow tasks over few broad ones: a task asked one question is read further into than a task asked four. User task:\\n\\n" + originalPrompt, {
   label: "planner",
   strength: "medium",
   schema: {
@@ -148,14 +177,14 @@ const plan = await agent("Design a bounded execution plan for this user task. Re
       tasks: {
         type: "array",
         minItems: 1,
-        maxItems: 8,
+        maxItems: 24,
         items: {
           type: "object",
           properties: {
             id: { type: "string", minLength: 1, maxLength: 64 },
             description: { type: "string", minLength: 1, maxLength: 500 },
             prompt: { type: "string", minLength: 1, maxLength: 8000 },
-            dependsOn: { type: "array", maxItems: 8, items: { type: "string", minLength: 1, maxLength: 64 } },
+            dependsOn: { type: "array", maxItems: 24, items: { type: "string", minLength: 1, maxLength: 64 } },
           },
           required: ["id", "description", "prompt"],
           additionalProperties: false,
@@ -427,9 +456,11 @@ export default function piWorkflows(pi: ExtensionAPI): void {
         promptGuidelines: [
           "Provide either a full `script` (raw JavaScript with the meta contract first) or a `name` of a saved/built-in workflow.",
           "Use orchestrate([{ id, dependsOn, run }]) for named dependency graphs; use parallel(() => agent(...), ...) for a simple fan-out and pipeline(items, ...stages) for sequential per-item stages.",
+          "Size the fan-out to the work: one agent per independent piece of evidence the task actually has. Ten to thirty agents is an ordinary review or audit, and a script that splits a broad task four ways is usually four agents each doing one agent's job. The gain is coverage, not speed — how many run at once is the host's pool, not the script's choice.",
+          "Pass script/name/args/background and nothing else unless the user named a specific limit. maxAgents, concurrency, agentRetries, tokenBudget and agentTimeoutMs already default to tuned values, and each one stops or fails the run when it is set too low.",
           "Use background: true for long runs; retrieve results with workflow_control.",
           "Use resumeFromRunId with an edited script to replay the unchanged prefix from cache and re-run the rest live.",
-          "Do not include model, thinking, concurrency, retry, timeout, or turn-limit settings beyond the declared options.",
+          "Inside the script, never name a model, a thinking level, or a turn limit: `strength` is the only routing a call may express.",
         ],
         parameters: WorkflowToolSchema,
         renderCall(args, theme) {
@@ -929,7 +960,7 @@ export default function piWorkflows(pi: ExtensionAPI): void {
       if (event.text.includes(WORKFLOW_ARMED_DIRECTIVE)) return { action: "continue" as const };
       const effortDirective =
         effortLevel === "ultra"
-          ? 'Effort: ULTRA. Be exhaustive: use broad parallel review, verification, and completeness checks; give the deepest steps strength: "high".'
+          ? 'Effort: ULTRA. Be exhaustive: use broad parallel review, verification, and completeness checks. Width is where the exhaustiveness goes: keep steps at strength: "medium" and reserve "high" for a step whose error is expensive to reverse, if the run has one at all.'
           : effortLevel === "high"
             ? "Effort: HIGH. Be thorough: use several independent reviewers and an adversarial verification pass."
             : "";

package/src/rpc-client.ts

@@ -172,6 +172,16 @@ export interface ManagedProtocolCheck {
   routingPolicy: ManagedRoutingPolicy;
   /** Whole-catalogue identity; used only where a per-tier identity cannot be. */
   routingPolicyFingerprint: string;
+  /**
+   * The host's background-agent pool size, when the peer published one.
+   *
+   * A workflow agent occupies one of those slots like any other background
+   * agent, so this is the width the run can actually achieve; dispatching past
+   * it only fills the host's queue. Undefined means the peer predates the
+   * field or answered through the readiness broadcast, which carries no
+   * requested fields — the caller then falls back to its own default.
+   */
+  maxConcurrent?: number;
 }
 
 export async function checkManagedSpawnProtocol(
@@ -213,7 +223,9 @@ export async function checkManagedSpawnProtocol(
     });
     const sendPing = () => {
       try {
-        events.emit("subagents:rpc:ping", { requestId: id });
+        // Additive reply fields are requested by name: the reply envelope is
+        // strictly parsed, so a peer may not volunteer one.
+        events.emit("subagents:rpc:ping", { requestId: id, include: ["maxConcurrent"] });
       } catch (error: unknown) {
         finish(undefined, error instanceof Error ? error : new Error(String(error)));
       }
@@ -254,6 +266,7 @@ export async function checkManagedSpawnProtocol(
   return {
     routingPolicy: ping.routingPolicy.policy,
     routingPolicyFingerprint: ping.routingPolicy.fingerprint,
+    ...(ping.maxConcurrent === undefined ? {} : { maxConcurrent: ping.maxConcurrent }),
   };
 }
 

package/src/runtime.ts

@@ -155,6 +155,16 @@ export interface AgentRunOptions {
   onTierResolved?: (tier: string) => void;
   onUsage?: (usage: AgentUsage) => void;
   onHistory?: (history: unknown[]) => void;
+  /**
+   * The agent left the host's queue and is now running.
+   *
+   * A dispatched agent does not necessarily start: it takes a background slot
+   * from pi-subagents, and a fan-out wider than that pool waits. The wall clock
+   * is restarted from this point so queue time is not charged against the work,
+   * which is what let a batch dispatched behind a busy pool fail as timeouts
+   * without any of it having run.
+   */
+  onRunning?: () => void;
 }
 
 export interface AgentOptions {
@@ -260,6 +270,17 @@ export interface WorkflowRunOptions {
   workflowDepth?: number;
   cwd?: string;
   concurrency?: number;
+  /**
+   * The host's background-agent pool size, read live from the peer at each
+   * start and resume.
+   *
+   * It is both the default width and the ceiling: a workflow agent occupies one
+   * of those slots like any other background agent, so dispatching past the pool
+   * does not run wider — it fills the host's single queue ahead of the host's own
+   * spawns. One setting therefore governs the fleet, and a run neither has to
+   * guess it nor can exceed it.
+   */
+  hostMaxConcurrent?: number;
   agentRetries?: number;
   tokenBudget?: number | null;
   signal?: AbortSignal;
@@ -337,9 +358,36 @@ export const MAX_AGENTS_PER_RUN = 1000;
 export const MAX_CALLS_PER_WORKFLOW = 1_000;
 /** Per-call item cap, matching the bounded batch contract used by reference engines. */
 export const MAX_FANOUT_ITEMS = 4_096;
-export const MAX_CONCURRENCY = 16;
+/**
+ * Upper bound on agents in flight at once.
+ *
+ * A dispatched agent is a remote call this process waits on, not work it
+ * performs, so the ceiling guards against a runaway script rather than against
+ * machine capacity. The real throttle belongs to pi-subagents: every managed
+ * spawn takes one of its `maxConcurrent` background slots, so a host that wants
+ * a narrower fleet narrows it there, once, for every agent it runs.
+ */
+export const MAX_CONCURRENCY = 64;
+/**
+ * In-flight agents when neither the run nor the caller names a number.
+ *
+ * Deliberately a constant rather than a function of `hardwareConcurrency`. Core
+ * count measures what this process can compute, and dispatching an agent
+ * computes nothing here; deriving the default from it fanned a 14-core host out
+ * 12 ways and a 4-core host 2 ways for identical, entirely remote work.
+ */
+export const DEFAULT_CONCURRENCY = 16;
 export const MAX_AGENT_RETRIES = 3;
-export const DEFAULT_AGENT_TIMEOUT_MS: number | null = 300_000;
+/**
+ * Wall clock for one agent when neither the call nor the run names one.
+ *
+ * It bounds a hang and nothing else. An agent's real budget is the turn, tool
+ * and token ceiling pi-subagents applies to it, which a deep call legitimately
+ * spends over many minutes; a default an order of magnitude shorter than that
+ * budget turned every wide fan-out of real work into a batch of timeouts. Pass
+ * `null` to remove the wall clock and leave the host's budgets in sole charge.
+ */
+export const DEFAULT_AGENT_TIMEOUT_MS: number | null = 1_800_000;
 export const MAX_SCRIPT_SYNC_MS = 1_000;
 
 // ── Determinism guardrail ────────────────────────────────────────────────────
@@ -865,13 +913,30 @@ async function withTimeout<T>(
   ms: number | null,
   label: string,
   onTimeout?: () => void,
+  /**
+   * Receives a `restart()` that re-arms the clock from now.
+   *
+   * The clock is armed at dispatch and restarted when the agent reports that it
+   * started, rather than only armed on that report: a report that never arrives
+   * must degrade to the old behaviour, not to an agent that can hang forever.
+   */
+  onArm?: (restart: () => void) => void,
 ): Promise<T> {
-  if (ms === null) return promise;
+  if (ms === null) {
+    onArm?.(() => {});
+    return promise;
+  }
 
   let timeoutId: ReturnType<typeof setTimeout> | undefined;
+  // The `restart` handed out below outlives this call: the holder keeps it in a
+  // closure that the caller may still reach after the race settles. Re-arming
+  // then would leave a live timer nothing clears, firing `onTimeout` on a
+  // finished agent long after the fact, so settlement makes it inert here
+  // rather than relying on every holder to guard its own call.
+  let settled = false;
 
   const timeoutPromise = new Promise<never>((_, reject) => {
-    timeoutId = setTimeout(() => {
+    const fire = () => {
       try {
         onTimeout?.();
       } catch {
@@ -884,12 +949,19 @@ async function withTimeout<T>(
           { recoverable: true },
         ),
       );
-    }, ms);
+    };
+    timeoutId = setTimeout(fire, ms);
+    onArm?.(() => {
+      if (settled) return;
+      if (timeoutId) clearTimeout(timeoutId);
+      timeoutId = setTimeout(fire, ms);
+    });
   });
 
   try {
     return await Promise.race([promise, timeoutPromise]);
   } finally {
+    settled = true;
     if (timeoutId) clearTimeout(timeoutId);
   }
 }
@@ -1185,19 +1257,38 @@ export async function runWorkflow<T = unknown>(
   };
 
   const agentRunner = options.agent;
+  // The host's pool is the width that can actually be achieved, so it is the
+  // default when it is known and the ceiling when it is not the default.
+  // DEFAULT_CONCURRENCY only covers a peer that published no pool size.
+  const requestedConcurrency = options.concurrency ?? options.hostMaxConcurrent ?? DEFAULT_CONCURRENCY;
   const concurrency = normalizeConcurrency(
-    options.concurrency ??
-      Math.max(
-        1,
-        (globalThis as { navigator?: { hardwareConcurrency?: number } }).navigator?.hardwareConcurrency ?? 8,
-      ) - 2,
+    options.hostMaxConcurrent === undefined
+      ? requestedConcurrency
+      : Math.min(requestedConcurrency, options.hostMaxConcurrent),
   );
+  // Only a caller who asked for a specific width can be surprised by the clamp,
+  // and the guidance now tells everything else to omit the field — so the one
+  // caller that set it is exactly the one owed an explanation for the number it
+  // did not get.
+  // Floored, not raw: normalizeConcurrency floors, and reporting 12.5 -> 12 as a
+  // clamp would blame a bound that did not bite.
+  const askedConcurrency = options.concurrency === undefined ? undefined : Math.floor(options.concurrency);
+  const concurrencyClampNotice =
+    askedConcurrency !== undefined && askedConcurrency > concurrency
+      ? `concurrency ${askedConcurrency} clamped to ${concurrency}` +
+        // Name the bound that actually bit. A pool above MAX_CONCURRENCY is not
+        // the reason for the clamp even though it is below what was requested.
+        (concurrency === options.hostMaxConcurrent
+          ? `: the host's subagent pool is ${concurrency}, and dispatching past it only queues`
+          : `: the runtime ceiling is ${MAX_CONCURRENCY}`)
+      : undefined;
 
   const log = (message: unknown) => {
     const text = String(message);
     state.logs.push(text);
     options.onLog?.(text);
   };
+  if (concurrencyClampNotice !== undefined) log(concurrencyClampNotice);
 
   /**
    * The strength table this run will honor, target-checked once at start.
@@ -1584,6 +1675,10 @@ export async function runWorkflow<T = unknown>(
               );
             }
 
+            // Set by withTimeout below, and called by the dispatcher when the
+            // agent leaves the host queue. Undefined until then: a start that
+            // beats the arming simply leaves the full clock ahead of it.
+            let restartTimeout: (() => void) | undefined;
             const runPromise = agentRunner.run(promptText + schemaInstruction + repairFeedback, {
               label,
               sessionName: agentOptions.thread
@@ -1614,9 +1709,20 @@ export async function runWorkflow<T = unknown>(
               onHistory: (history: unknown[]) => {
                 options.onAgentHistory?.({ id: deltaKey, label, phase: assignedPhase, history });
               },
+              onRunning: () => {
+                restartTimeout?.();
+              },
             });
             runPromise.catch(() => {});
-            let result = await withTimeout(runPromise, timeout, label, () => agentController.abort());
+            let result = await withTimeout(
+              runPromise,
+              timeout,
+              label,
+              () => agentController.abort(),
+              (restart) => {
+                restartTimeout = restart;
+              },
+            );
 
             throwIfAborted();
             if (isEmptyTextAgentResult(result, schema)) {