@signalridge/pi-workflows 1.6.0 → 1.7.1

package/CHANGELOG.md

@@ -1,5 +1,154 @@
 # Changelog
 
+## 1.7.1
+### Patch Changes
+
+- 1f586f8: Preserve resumable cancellation when a workflow pauses during successful timeout cleanup, and retain finalized subagent output alongside observer failures. Avoid retaining descendant-owned mouse gestures in bordered components. Track successful writes using final rewritten paths, and distinguish uncertain changes observed during failed calls from confirmed agent modifications while keeping both discoverable in file browsing. Preserve exact filesystem paths and lazy-directory scan state when discovering session-observed changes, including changes injected during an active scan.
+- 1f586f8: - Bound workflow cancellation drains and durably fence unconfirmed cleanup, aborting sibling agents and releasing foreground callers.
+  - Await managed timeout cleanup before script continuation and terminal publication.
+  - Keep failed retry text and length responses discarded by overflow-compaction retry out of successful subagent fallbacks, while retaining valid pre-compaction and non-retried length output.
+  - Account for native prompts spanning reporter activation without dropping out-of-order wait debt.
+  - Reconcile settlement after observer-triggered manual compaction with run/session ownership.
+  - Preserve clipped overlay hit ranges and native container ancestry for editor autocomplete focus.
+  - Reconcile errored writes and edits against pre/post mutation evidence, retaining invocation cwd and releasing evidence when blocked or aborted preflight bypasses tool results.
+- d9219d4: Correct shipped documentation that contradicted the code or the manifest.
+  
+  - `pi-subagents`: the summary line still advertised protocol-v3 spawning while
+    the feature list and the managed-spawn section described v4.
+  - `pi-worktree`: the workspace-switching section named `/tree`; the registered
+    command is `/worktree`.
+  - `pi-workflows`: removed an orphaned sentence fragment left behind by an edit
+    to the saved-workflow paragraph.
+  - `pi-plan-mode`, `pi-goal`, `pi-usage-extension`: the stated Pi floor
+    (`0.80.6`, `0.42.4+`) contradicted the declared `^0.84.0` peer range, which
+    resolves to `0.84.x`. `pi-usage-extension` also carried a "Last updated"
+    stamp from a version that predates the workspace baseline.
+  - `pi-welcome`: the example card was a real session capture. It is now a
+    generic sample, and Install moved above the configuration sections instead of
+    sitting below them.
+- 1f586f8: Preserve Codex opaque checkpoints across Pi's retry-only assistant-tail removal using optional, fingerprint-verified version-1 proof plus explicit lifecycle provenance. Preserve that provenance across same-runtime reload without confusing a new identical assistant response with the persisted tail; persisted rebuilds reset it and unknown provenance fails closed. Bound BTW context and tool-argument construction, including suffix-key storage for wide JSON-shaped objects (enumeration remains linear). Balance out-of-order native UI waiting notifications without affecting manual blocked ownership. Foreground workflow cancellation waits for exact-owner quiescence even when stop is unavailable or rejects after reconciliation already stopped the child, including cancelled spawn allocation recovery; unconfirmed cleanup becomes durably non-resumable with a diagnostic retaining any stop error. Background execution remains detached.
+  
+  These are corrective changes: existing checkpoint fields, exports, and cross-extension protocols remain compatible, so no protocol or major-version bump is required.
+- 1f586f8: Expand Pi peer support to `^0.84.0 || ^0.85.0`, retaining 0.84 compatibility while admitting 0.85 releases. The previous zero-major caret range excluded Pi 0.85.1. Update existing Pi development dependency pins to 0.85.1.
+- 1f586f8: Keep goal iteration and continuation numbering correct when Pi compacts between tool results and the next response within one run. Preserve existing response limits and manual/post-run compaction handling.
+  
+  Capture subagent invocation results from finalized assistant events with bounded message retention so compaction cannot hide a final error or mix in historical output. Recognize explicitly selected PowerShell when the host provides it, without requiring its export on older Pi versions or expanding default wildcard tools.
+  
+  Use real session contexts for workflow replay and live TUI progress, release widget bindings on shutdown, and allow foreground checkpoint dialogs in RPC mode while retaining print-mode defaults. Cancel unanswered dialogs with their owning execution on tool abort, pause, stop, disposal, or fatal failure without journaling cancelled answers.
+
+## 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`,
@@ -185,7 +208,6 @@ sentence-ending dot is not a filename dot: "please run a workflow." arms, and
 turn it off entirely with `/workflows-trigger off`.
 
 Saved workflows use project scope first and a user scope fallback; writes are atomic and names are path-safe.
-written atomically with a backup.
 
 ## Model routing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalridge/pi-workflows",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "description": "Deterministic JavaScript orchestration workflows backed by pi-subagents managed spawning.",
   "type": "module",
   "license": "MIT",
@@ -15,12 +15,12 @@
     "lifecycle": "stable"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.84.0",
-    "@earendil-works/pi-tui": "^0.84.0",
+    "@earendil-works/pi-coding-agent": "^0.84.0 || ^0.85.0",
+    "@earendil-works/pi-tui": "^0.84.0 || ^0.85.0",
     "@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.1"
 ---
 
 # 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.1`
 
 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.1`
 
 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.1"
 ---
 
 # 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.1"
 ---
 
 # 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",