@signalridge/pi-workflows 1.5.0 → 1.7.0

package/CHANGELOG.md

@@ -1,5 +1,232 @@
 # 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
+
+- fabe89a: A workflow now speaks one routing word of its own: **strength**.
+  
+  `agent({ tier })` is gone. A script names `strength: "low" | "medium" | "high"` —
+  this package's own word for how much effort a step deserves — and the new
+  `strengths` setting is the only thing that binds one to an Agent tier. A strength
+  no table defines dispatches with **no tier at all** and takes the agent's ordinary
+  default, so nothing is inferred from spelling at dispatch: the binding is always a
+  table entry.
+  
+  That inference was the bug. The built-ins ask for `low`, and so does the `Explore`
+  agent and everything that names no tier of its own, so pointing `low` at a cheaper
+  model to make a 26-agent fan-out affordable dragged every ordinary search spawn
+  with it. Pointing a *strength* elsewhere does not.
+  
+  A host that has configured nothing gets a shipped default table rather than no
+  mappings: each strength on the catalogue tier of the same name, wherever the host
+  defines one — identity on a stock install, empty on a host whose tiers are called
+  `cheap`/`deep`. It is computed against the live catalogue, so it is never an
+  assertion about someone else's tier names and never complains at run start about
+  configuration nobody wrote. Without it every shipped script's `low`/`medium`
+  distinction would collapse onto pi-subagents' managed `medium` fallback — the
+  *more* expensive rung — and an unconfigured machine would run its fan-outs dearer
+  than before this change.
+  
+  The distinction that makes that safe is that it is a **table, not a fallback
+  rule**. A rule would be unremovable, and re-pricing a fan-out would again mean
+  editing the shared tier. A table is replaced by writing one, a written table that
+  omits `low` leaves it unmapped even where a tier called `low` exists, and `{}` is
+  a real table meaning "map nothing".
+  
+  This is not the retired `workflow.tiers` key. That one carried its own `model` and
+  `thinking`, making it a second model policy behind a second resolver. A value here
+  is a key in the host's one catalogue: pi-subagents still owns every model, every
+  thinking level, and the only `resolveAgentTier()`, and cannot tell a mapped call
+  apart from a spawn that named the key itself. No protocol change.
+  
+  The vocabulary is closed, which buys back what the passthrough used to provide.
+  A word outside the three is a typo, not a strength nobody configured, so it fails
+  before dispatch. With no way for a script name to reach the catalogue, the
+  shipped-vs-user tier rule (`shippedScript`) had nothing left to decide and is
+  removed, along with its `run_created` journal field.
+  
+  The same argument applies one level up, so `agent()` and `checkpoint()` now
+  reject any option name they do not read instead of ignoring it. `tier`, `model`,
+  and `thinking` answer by naming their replacement; anything else lists the legal
+  keys, and a non-object options value is refused rather than reaching a bare
+  `TypeError`. An unknown key is dropped before the call hash is built, so it moves
+  neither the dispatch nor the resume identity: `agent({ strenght: "low" })` would
+  have run every step untiered and replayed that way, and
+  `checkpoint({ headles: "abort" })` would have auto-approved in headless mode
+  instead of aborting. Neither leaves a log line. A script is plain JavaScript
+  authored against this contract, so nothing else was going to catch it. Both key
+  lists are pinned to their interfaces by a `satisfies Record<keyof …>` clause, in
+  both directions.
+  
+  There is deliberately no default strength: a call that names none dispatches with
+  no tier, exactly as an unmapped one does, and the host resolves it the way it
+  resolves every other spawn. A default was tried and is wrong — a tier a call
+  requests outranks the agent type's own, so on a stock install (`medium → medium`)
+  every unlabelled dispatch would have pinned `medium` over whatever the agent
+  declared, overruling `Explore`'s shipped `tier: low` and re-pricing in the wrong
+  direction the one agent this indirection exists to leave alone. Nothing is lost:
+  a script that named no strength stated no opinion, and pi-subagents' ordinary
+  precedence is still user-owned policy.
+  
+  What the table must reach is every call a script did label, and the shipped
+  scripts label all of theirs. The three helpers that dispatch on the script's
+  behalf — `verify`, `judgePanel`, `completenessCheck` — took no strength at all
+  and so could never be re-routed; they now accept one, defaulting to `low`, `low`,
+  and `medium`.
+  
+  Those defaults are an opinion where there was none, and an opinion outranks the
+  host's: a tier a call requests beats `agentTiers.defaultTier`, so on a machine
+  whose default is `high` a `completenessCheck` now runs at whatever `medium` maps
+  to rather than at `high`. That is the price of making the helpers steerable at
+  all — a helper that names no tier can never be pointed anywhere — and the new
+  option is how a script takes it back.
+  
+  Fixes a re-spend bug: `strengths` is deliberately never frozen onto a run, but the
+  resumes the engine starts itself (`/workflows resume`, the provider-limit retry)
+  passed no table, and since a call's identity keys on the tier it requested, every
+  finished call missed its journal entry and re-ran untabled. The engine now reads
+  the current table for those.
+  
+  `/workflows-models` is gone; the table is edited with `/workflows strength`
+  (`[<low|medium|high> <tier>|off]`), which also prints the effective table and the
+  tiers this host defines — the one place both halves are visible. It validates the
+  strength and the target before writing and reports the resolved result rather than
+  echoing the write, so it can no longer claim a change the settings layer dropped.
+  `off` yields to a real host tier of that name, and says so when it does, since a
+  user who typed the documented keyword and got a mapping has to be told which
+  reading won. The view also names where a machine-wide table lives, and — while
+  the shipped default is in force — that the default is identity, so workflow work
+  is still sharing the tiers ordinary spawns use until a tier is defined for it.
+  
+  Settings commands now write project scope instead of the merged view. Previously
+  the first `/effort` or `/workflows-progress` in a project copied every global value
+  and default into the project file, after which that project stopped tracking the
+  global one.
+  
+  `strengths` needs the opposite treatment, because it replaces rather than merges at
+  each level, so `/workflows strength` seeds its write from the table a run would
+  actually use — project, else global, else the shipped default. Built on project
+  scope alone, setting one entry would have discarded an inherited global table, and
+  `off` against an entry the project never wrote would have written nothing and left
+  the mapping standing.
+  
+  One caution the docs now carry: the provider-limit retry resumes on a timer with
+  nobody watching, so a table edited while a run is rate-limit-paused is charged the
+  re-spend above without being asked. Stop the run first if that is not worth it.
+
 ## 1.5.0
 ### Minor Changes
 

package/README.md

@@ -54,9 +54,9 @@ export const meta = {
 
 phase("scan");
 const findings = await parallel([
-  () => agent("Check for cross-package imports", { label: "imports", tier: "low" }),
-  () => agent("Check for secrets", { label: "secrets", tier: "low" }),
-  () => agent("Check for dead code", { label: "dead-code", tier: "low" }),
+  () => agent("Check for cross-package imports", { label: "imports", strength: "low" }),
+  () => agent("Check for secrets", { label: "secrets", strength: "low" }),
+  () => agent("Check for dead code", { label: "dead-code", strength: "low" }),
 ]);
 
 phase("synthesize");
@@ -77,13 +77,13 @@ user's own LLM and run on the user's own machine.
 
 ### Runtime globals
 
-- `agent(prompt, { label, phase, schema, tier, isolation, thread, agentType, toolset, excludeTools, timeoutMs, retries })`
+- `agent(prompt, { label, phase, schema, strength, 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. 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`.
-  `tier` is the provider-neutral workflow route; `thread` chains sequential turns
+  `strength` is the provider-neutral workflow route; `thread` chains sequential turns
   within a named conversation thread. A legacy programmatic `model` option may
   still be accepted by non-managed callers, but workflow meta/phase model or
   thinking fields are rejected and are never a workflow policy source. Pre-schema-v4
@@ -145,14 +145,40 @@ 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`,
-  `resume`, `rm`, and `save <name> [runId]` subcommands.
-- `/workflows-models`: points at pi-subagents' `/agents → Model tiers` — there
-  is deliberately no second tier configuration file.
+  `resume`, `rm`, `save <name> [runId]`, and `strength` subcommands.
+- `/workflows strength`: `[<low|medium|high> <tier>|off]` — which Agent tier each
+  workflow strength runs on, and the tiers this host defines. Unconfigured hosts
+  start on a shipped default table (identity, where the host defines the name).
+  The tiers themselves are still configured only in pi-subagents'
+  `/agents → Model tiers`; there is deliberately no second tier configuration file.
 - `/effort` and `/ultracode`: standing `off|high|ultra` effort guidance that auto-arms substantive messages.
 - `/workflows-progress`: `compact|detailed|status|max <N>` controls the persisted live panel.
 - `/deep-research`, `/adversarial-review`, `/code-review`,
@@ -186,52 +212,185 @@ written atomically with a backup.
 
 ## Model routing
 
-`tier` names a key in the host's own `agentTiers` catalogue — the same catalogue an
-ordinary `Agent` call uses. There is no separate workflow-tier vocabulary and no
-mapping layer: a workflow that wants cheap work asks for the tier the user defined
-for cheap work.
+A workflow speaks one word about cost: **strength**, this package's own name for
+how much effort a step deserves. `low`, `medium`, `high` — that is the whole
+vocabulary, and a script may name nothing else.
 
 ```js
-await agent("summarize this diff", { tier: "low" })
-await agent("design the migration", { tier: "high" })
+await agent("summarize this diff", { strength: "low" })
+await agent("design the migration", { strength: "high" })
+await agent("the ordinary case")                          // no strength: see below
 ```
 
-The host's catalogue arrives with the protocol handshake, so a tier this host does
-not define is rejected before any dispatch, naming the ones it does. Resolution
-itself is entirely pi-subagents' `resolveAgentTier()`: it owns the final model,
-thinking level, clamping, availability checks, and the immutable resolution
-snapshot.
-
-The catalogue belongs to whoever runs the workflow — the names included. The
-built-in workflows and the ad-hoc script ship with this package, so they cannot
-assert that `low` exists on a machine whose tiers are called `cheap` and `deep`:
-a name they use that the host does not define is dropped, with a log line, and
-the host's own default applies. A script you wrote names tiers from your own
-catalogue, so an undefined one there is a typo and fails closed instead.
-
-There is no per-call `model` or `thinking`, and `meta`/phase metadata may not carry
-them either — both are rejected explicitly rather than accepted and ignored. A tier
-is the only model policy a workflow can express, which is what keeps a script from
-pinning a vendor the host did not choose.
-
-Omitting `tier` uses the agent's own tier, then `agentTiers.defaultTier`. Fresh
-installs ship `low`/`medium`/`high` profiles, all inheriting their model, and a
-managed call that still names no tier falls back to `medium` — so the built-ins run
-on a new machine without any configuration. That fallback is scoped to managed
-calls: it is not the catalogue's `defaultTier`, so an ordinary `Agent` spawn on the
-same machine keeps falling through to `defaultModel` and the parent session. A host
-whose default has been cleared (`noDefaultTier`) rejects an untiered managed call
-rather than quietly inheriting the parent session's model.
-
-The managed wire, invocation record, journal, tombstone, and resume state all carry
-the one resolved tier — including one the host defaulted to, so a run's record says
-what actually ran. Resume keys each cached call on the policy for *that call's*
-tier: editing an unrelated tier does not invalidate work that never used it.
+There is no default strength. A call that names none dispatches with **no tier**,
+exactly as an unmapped strength does, and pi-subagents resolves it the way it
+resolves any other spawn: the agent type's own frontmatter tier, then
+`agentTiers.defaultTier`. That matters because a tier a call requests outranks
+the agent type's own — so a default strength would have pinned every unlabelled
+call to whatever it mapped to, overruling `Explore`'s shipped `tier: low` and
+re-pricing the one agent this indirection exists to leave alone. Label the calls
+whose cost you mean to steer; leave the rest to the host.
+
+A strength is not an Agent tier. A `strengths` table is the only thing that
+binds one to a tier:
+
+```jsonc
+// <agent dir>/workflows/settings.json, or the per-project settings file
+{ "strengths": { "low": "cheap-search", "high": "deep" } }
+```
+
+**An unmapped strength dispatches with no tier at all** and takes the agent's
+ordinary default — the agent's own frontmatter tier, then the host's configured
+default. `{}` is a real table meaning exactly that for every strength.
+
+### The default table
+
+A host that has configured nothing does not get "no mappings". It gets a table
+this package ships: each strength on the catalogue tier of the same name,
+**wherever the host defines one**. On a stock install that is
+`low → low, medium → medium, high → high`; on a host whose tiers are called
+`cheap` and `deep` it is empty, and every strength is unmapped. It is computed
+against the live catalogue rather than hardcoded, so it is never an assertion
+about someone else's tier names and never produces a start-up complaint about
+configuration you did not write.
+
+Without it, every shipped script's `low`/`medium` distinction would collapse
+onto pi-subagents' managed default — which is the *more* expensive rung, so an
+unconfigured machine would run its fan-outs dearer, not cheaper.
+
+That it is a **table and not a fallback rule** is the whole design. A rule
+saying "an unmapped strength runs on the tier of the same name" would be
+unremovable, so making a 26-agent fan-out cheaper would still mean editing tier
+`low` itself — dragging the `Explore` agent and everything else that names it. A
+table is replaced by writing one, and a written table that omits `low` leaves it
+unmapped even on a host that defines a tier called `low`. Nothing is ever
+inferred from spelling at dispatch: the binding is always a table entry.
+
+So `low → low` in a written table is a real entry and not a no-op — a table you
+write replaces the default outright, so the entries you leave out are unmapped,
+not inherited.
+
+### Editing it
+
+`/workflows strength` edits the table and also prints the tiers this host
+defines — the one place both halves are visible, since the strengths come from
+this package and the tiers from pi-subagents:
+
+```
+/workflows strength              # show the effective table and the host's tiers
+/workflows strength low cheap    # run workflow strength `low` on Agent tier `cheap`
+/workflows strength low off      # unmapped; back to the agent's own default
+```
+
+Edits land in **this project's** settings, like every other setting this package
+owns. Because the table replaces rather than merges at each level, the command
+seeds the write from the table a run would actually use — the project file, else
+global, else the shipped default — so setting one entry cannot silently discard
+the rest, and `off` clears a mapping this project never wrote. The write is
+therefore a full copy of the current table into the project; edit
+`<agent dir>/workflows/settings.json` by hand for a machine-wide table.
+
+Any key the host's catalogue defines is a legal target — an existing tier, or a
+profile added for exactly this purpose. There is no shortlist and no naming
+convention: the target is checked against the live catalogue at run start, so a
+profile added to `subagents.json` is usable the moment it exists. One hop, never
+chained. An entry whose tier the host does not define is reported once at run
+start and ignored, leaving that strength unmapped — a stale entry costs the
+redirect, not every workflow on the machine.
+
+This is not the retired `workflow.tiers` key and must not become it. That one
+carried its own `model` and `thinking` values, which made it a second model
+policy resolved by a second resolver. A value here is a **key in the host's one
+catalogue**: pi-subagents still owns every model, every thinking level, and the
+only `resolveAgentTier()`, and cannot tell a mapped call apart from a spawn that
+named the key itself.
+
+There is no per-call `model`, `thinking`, or `tier`, and `meta`/phase metadata
+may not carry them either. A strength is the only model policy a workflow can
+express, which is what keeps a script from pinning a vendor the host did not
+choose.
+
+The vocabulary is closed so that a word outside it is a *typo* rather than a
+strength nobody configured: `agent({ strength: "lowe" })` fails before any
+dispatch instead of silently running at the default.
+
+The same argument applies one level up, to the option *name*. `agent()` and
+`checkpoint()` reject any key they do not read, rather than ignoring it:
+
+```js
+await agent("x", { tier: "low" })      // → name a strength instead: one of low, medium, high
+await agent("x", { model: "…" })       // → a strength is the only model policy a workflow can express
+await agent("x", { strenght: "low" })  // → valid options are: label, phase, schema, strength, …
+```
+
+An unknown key is dropped before the call hash is built, so it changes neither
+the dispatch nor the resume identity — the run would simply spend at a policy
+nobody chose, and a resume would replay it without noticing. A script is plain
+JavaScript authored against this contract, so there is no other gate: a
+misspelled option would run every step untiered, and a misspelled
+`checkpoint({ headles: "abort" })` would auto-approve in headless mode instead
+of aborting.
+
+### Helpers that dispatch for you
+
+`verify()`, `judgePanel()`, and `completenessCheck()` spawn agents on the
+script's behalf, so the script cannot label those calls. Each carries a
+documented default and takes an override, which keeps every dispatch inside the
+vocabulary:
+
+```js
+await verify(finding)                              // reviewers run at "low"
+await verify(finding, { strength: "high" })        // unless you say otherwise
+await completenessCheck(args, results)             // one open-ended read: "medium"
+```
+
+These defaults are an opinion, and an opinion outranks the host's: a tier a call
+requests beats `agentTiers.defaultTier`, so on a machine whose default is `high`
+a `completenessCheck` now runs at whatever `medium` maps to rather than at
+`high`. That is the trade for making the helpers re-routable at all — they
+previously named no tier and could never be steered — and the override above is
+how a script takes it back.
+
+### Resume
+
+The table is read fresh at each start and resume — including the resumes the
+engine starts itself, `/workflows resume` and the provider-limit retry — never
+frozen onto a run.
+
+Resume identity keys a call on the tier it will actually request, so editing the
+table and resuming re-routes the calls that have not run — and **also re-runs
+the finished calls whose strength moved**, plus everything after the first such
+miss, because their cached answers came from a different tier. Re-routing
+mid-run is therefore a re-spend; if the point of the edit was to spend less,
+start a new run instead of resuming one that is mostly done. The provider-limit
+retry resumes on a timer with no one watching, so a table edited while a run is
+rate-limit-paused is charged the same way without being asked — stop that run
+before editing if the re-spend is not worth it. A nested
+`workflow()` boundary folds the table into its own key for the same reason: the
+value it caches for the whole child frame would otherwise survive a change that
+re-routes the child.
+
+Fresh installs of pi-subagents ship `low`/`medium`/`high` tier profiles, all
+inheriting their model — which is what the default table above resolves against,
+so the built-ins run on a new machine, at their own strengths, with no
+configuration. A managed call that still names no tier falls back to `medium`;
+that is where an unmapped strength lands. The fallback is scoped to managed
+calls: it is not the catalogue's `defaultTier`, so an ordinary `Agent` spawn on
+the same machine keeps falling through to `defaultModel` and the parent session.
+A host whose default has been cleared (`noDefaultTier`) rejects an untiered
+managed call rather than quietly inheriting the parent session's model — which
+an unmapped strength can reach.
+
+The managed wire, invocation record, journal, tombstone, and resume state all
+carry the one resolved tier — including one the host defaulted to, so a run's
+record says what actually ran. Resume keys each cached call on the policy for
+*that call's* tier: editing an unrelated tier does not invalidate work that never
+used it.
 
 ## Intentional adaptations from upstream
 
 - **No host-side web tools.** Agents reach the web through configured pi-web-access/MCP tools or an agent type's tool policy.
-- **Agent registry and tier catalogue ownership.** `agentType` and the tier catalogue resolve in pi-subagents; the workflow package supplies only a tier key, avoiding a second model/thinking policy.
+- **Agent registry and tier catalogue ownership.** `agentType` and the tier catalogue resolve in pi-subagents; the workflow package supplies only a tier key its own `strengths` table chose, avoiding a second model/thinking policy.
 - **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 v4), including frozen invocation args, resolved tier identity, terminal result previews, script revisions, named nested-workflow result boundaries, and durable removals. Interrupted/provider-limited runs replay from the journal; pre-schema-v4 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.5.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.5.0"
+  version: "1.7.0"
 ---
 
 # Workflow authoring
@@ -25,16 +25,44 @@ 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.
-- Route an agent call with `tier: "<key>"`, naming a tier the destination host
-  defines. Omitting `tier` uses the agent's own tier, then the host's configured
-  default; a host whose default has been cleared rejects the call rather than
-  inheriting the parent model. There is no per-call `model`/`thinking`, and
-  neither may appear in workflow meta or phase profiles. Never guess a tier or
-  agent-type name—use names supplied by the current environment and follow
+- 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
+  alone binds a strength to a tier — the user's, or the shipped default on a
+  host that configured none — and a strength no table defines dispatches with no
+  tier and takes the agent's own default. So name the effort the step deserves
+  and never reach for a catalogue name; a word outside the three is rejected
+  before dispatch, as is `tier:` itself. There is no default: omitting
+  `strength` dispatches with no tier and lets the agent type's own tier stand,
+  so label the calls whose cost you mean to steer and leave the rest alone.
+  There is no per-call `model`/`thinking`/`tier`, and none may
+  appear in workflow meta or phase profiles. `agent()` and `checkpoint()` reject
+  any option name they do not read rather than ignoring it, so pass only the
+  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`.
 
@@ -56,7 +84,9 @@ JavaScript.
    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.
+   `completenessCheck` with explicit bounds. These dispatch on your behalf, so
+   pass `strength` when the default (`low`, or `medium` for
+   `completenessCheck`) is not the effort that gate deserves.
 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.
@@ -176,8 +206,8 @@ Before shipping a workflow change:
 - 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; remember that a tier
-  names a key in the host catalogue while model/thinking resolution stays in
-  pi-subagents;
+  signature, default, or support boundary is disputed; remember that a strength
+  is this package's own vocabulary, bound to a host tier only by the user's
+  `strengths` table, while model/thinking resolution stays in pi-subagents;
 - ensure every package-relative example/reference link remains inside the
   publishable package.