@signalridge/pi-workflows 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,254 @@
 # Changelog
 
+## 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
+
+- c1b1741: Protocol v4: workflows use the Agent-tier catalogue directly.
+  
+  The wire contract changes, so the three packages move together: `pi-workflows`
+  now declares `"@signalridge/pi-subagents": ">=1.9.0"`, and a peer outside that
+  range fails the startup handshake with a diagnostic naming both packages rather
+  than failing mid-run.
+  
+  The `small | medium | large` workflow-tier vocabulary and its mapping layer are
+  gone. A managed request names an Agent tier — a key in the host's own
+  `agentTiers` catalogue — and `resolveAgentTier()` is the single resolver for
+  every spawn path. Removed with it: the wire's mapped `agentTier` field, the
+  `workflow` settings key (retired with a warning naming it; `agentTiers.defaultTier`
+  replaces `workflow.defaultTier`), and the per-call `model`/`thinking` selectors,
+  which the validator now rejects rather than accepting and ignoring.
+  
+  Every v4 capability is required and every ping carries the host's tier catalogue,
+  so an incomplete peer fails one check instead of five optional ones. Fresh
+  installs ship `low`/`medium`/`high` profiles, all inheriting their model, and a
+  managed call that names no tier falls back to `medium`, so a workflow runs on an
+  unconfigured machine without this package choosing a vendor. Because `medium`
+  inherits, that fallback lands on the parent session's model — it commits to an
+  effort level, not to a vendor, so it does change the thinking level a managed
+  call runs at when the parent session is set higher, and it does not move the
+  work anywhere cheaper. What it buys is a named policy with a durable snapshot
+  and a scope check; a workspace that wants cheaper managed work names a
+  `defaultTier` whose profile pins a model. The fallback is scoped to calls that
+  cannot inherit a parent model rather than being installed as
+  `agentTiers.defaultTier`: a shipped catalogue default would have applied to
+  every ordinary `Agent` spawn as well, silencing `defaultModel` and pinning a
+  thinking level on machines that configured neither. The catalogue no longer
+  ships a `fast` profile; it was the same (model, thinking) pair as `low`, and the
+  one agent that named it (Explore) now names `low`. A user agent file that still
+  says `agentTier: fast` is reported by the existing unknown-reference check when
+  settings and agents load, rather than failing at its first spawn.
+  
+  `agentTiers.defaultTier` therefore has three states, and `/agents → Settings`
+  offers all three rather than rendering two of them as one word: a named tier,
+  `unset` (managed calls reach the shipped fallback), and `none` (recorded as
+  `noDefaultTier`, which withdraws the fallback so managed calls fail closed).
+  `setDefaultAgentTier` takes that choice as a tagged value, so a caller cannot
+  express "no default" without saying which of the two it means.
+  
+  `resolveAgentTier` gained `requireTier` for that fallback, and the two things
+  pre-resolution callers need are both answered by the resolver rather than
+  restated beside it: `agentTierApplies()` for "will a tier own this spawn's
+  model?", and `selectAgentTier()` for the tier key itself, which the managed
+  path needs to label a tombstone and the lifecycle events before the runner has
+  resolved anything.
+  
+  Because a tier now owns model resolution outright, the spawn paths stop
+  pre-resolving one — and with it they stopped producing the model name the agent
+  UI shows. The resolution callback carries that label back instead, so a tier
+  that pins a model still names it in the viewer and the agent list, and a profile
+  that inherits correctly shows none. The label rides beside the snapshot rather
+  than inside it: the snapshot is a durable policy record a managed tombstone
+  persists and revalidates, and a cosmetic string does not belong in it.
+  
+  Workflow resume now keys each cached call on the policy for that call's own tier
+  rather than on a whole-catalogue fingerprint, so defining or editing an unrelated
+  tier no longer forces a full re-execution — but only for a call that names its
+  tier. A call that names none keeps the whole-catalogue key, because the host
+  resolves those as `call > agent frontmatter > defaultTier` and frontmatter is
+  not on this wire: an agent reaches a managed caller as a name. Keyed on
+  `defaultTier`, such a call would be wrong twice over — replaying stale work
+  after an edit to the tier its agent actually declares, and re-executing after an
+  edit to a default it never reached. `agentTierPolicyIdentity()` therefore
+  requires a tier rather than accepting `undefined` and folding the default in, so
+  the wrong call cannot be written. Journal schema v4 and managed tombstone schema
+  v2 are quarantined from older facts rather than migrated.
+  
+  The tier catalogue belongs to the user, names included. The built-in workflows
+  and the ad-hoc script ship with this package, so a tier name they use that the
+  host does not define is dropped in favour of the host's default rather than
+  failing the run — they cannot assert which names exist on someone else's
+  machine. A script the user wrote still fails closed on an undefined tier, since
+  that is a typo in a catalogue they own. Shipped-ness travels with the script
+  rather than with the frame that called it, so a user script that reaches a
+  built-in through `workflow(name)` applies the built-in's rule to the built-in;
+  the authoring skill now says outright that `low`/`medium`/`high` are the shipped
+  profiles rather than names an authored script may assume.
+  
+  The managed routing policy published on the wire reports the default a managed
+  call will actually get, fallback included, so a peer's replay identity cannot
+  disagree with the host's selection; its sorts are code-unit rather than
+  locale-dependent, so the same catalogue fingerprints identically everywhere. The
+  workflow peer re-pings per start and resume instead of pinning the catalogue it
+  saw at session start, and reports the host-selected tier back through an
+  `onTierResolved` callback rather than by mutating the dispatch options.
+  
+  Fixes: a nested spawn no longer relabels an agent's frontmatter tier as
+  caller-requested, which had turned a `scopeModels` warning into a refusal and
+  misattributed the choice; the scheduler no longer freezes a frontmatter tier into
+  a job, so editing the agent file takes effect at fire time; retired managed spawn
+  keys are now bounded instead of growing for the life of a session; a
+  scope refusal for a tier whose profile inherits its model now names the model
+  that would have run instead of the literal `undefined`; and the retired
+  `workflow` key warns once per process rather than on every settings read and
+  every project write.
+  
+  The tier-key predicate and its length bound now have a single definition, in
+  `pi-subagents-protocol`, which `pi-subagents` re-exports. The wire is the
+  narrower of the two gates — a key one accepted and the other rejected could
+  never reach a peer — so a second copy could only ever be a way for them to
+  disagree. That one definition now also governs `blockedProfiles`, which was
+  being validated by a helper that trims first: `" low"` became `"low"` there
+  while the same value in `profiles` or `defaultTier` was refused outright. All
+  three reject.
+  
+  `/agents → Settings` no longer names the fallback tier in the `unset` row's
+  label. Which tier `unset` reaches depends on the catalogue, and a workspace that
+  edits or deletes the shipped `medium` profile leaves it reaching nothing — at
+  which point `unset` and `none` behave identically. The row's description asks
+  the resolver what `unset` would currently resolve to and says that, including
+  when the answer is "nothing".
+  
+  `pi-workflows` also gained the session-lifecycle handling this routing work
+  needed to sit on. The engine has an explicit dispose lifecycle, so a protocol
+  probe or a start that is in flight when a session ends rejects with a disposed
+  error instead of resolving against an engine nobody owns. The tool, command and
+  widget surfaces register exactly once and resolve the *current* engine on each
+  use, rather than closing over the one that existed when they were registered —
+  a session replacement previously left them pointing at a disposed engine. Tool
+  and command handlers report failures as results rather than throwing out of the
+  host's dispatch, and the lifecycle handler accepts `subagents:created` and
+  `subagents:started` so a spawn's identity is recorded from the first event that
+  carries it rather than only at completion.
+
+### Patch Changes
+
+- Updated dependencies [c1b1741]
+  - @signalridge/pi-subagents-protocol@1.4.0
+
 ## 1.4.0
 ### Minor Changes
 

package/README.md

@@ -12,8 +12,8 @@ isolation, retry, and session policy.
 
 ## Install
 
-`@signalridge/pi-workflows` requires `@signalridge/pi-subagents` `>=1.5.0`
-with protocol v3 managed-spawn, workflow-tier, and managed-policy support. They are separate Pi packages: the peer
+`@signalridge/pi-workflows` requires `@signalridge/pi-subagents` `>=1.9.0`
+with protocol v4 managed-spawn, Agent-tier, and managed-policy support. They are separate Pi packages: the peer
 dependency documents the requirement but intentionally does not auto-load or
 duplicate the subagent extension.
 
@@ -54,9 +54,9 @@ export const meta = {
 
 phase("scan");
 const findings = await parallel([
-  () => agent("Check for cross-package imports", { label: "imports", tier: "small" }),
-  () => agent("Check for secrets", { label: "secrets", tier: "small" }),
-  () => agent("Check for dead code", { label: "dead-code", tier: "small" }),
+  () => 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,15 +77,17 @@ user's own LLM and run on the user's own machine.
 
 ### Runtime globals
 
-- `agent(prompt, { label, phase, schema, model, 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`.
-  Explicit `model` and `isolation: "worktree"` are resolved and enforced by pi-subagents; `tier` remains the provider-neutral route.
-  `tier`; see "Model routing"). `thread` chains sequential turns within a named
-  conversation thread.
+  `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
+  journal runs are quarantined and cannot be resumed.
 - `parallel(thunks)` — run thunks concurrently, preserve input order. Recoverable
   thunk failures become `null`; non-recoverable failures (token budget, agent
   limit) halt the run after the batch barrier settles. Fan-out that breaches
@@ -148,9 +150,12 @@ workflow, and the review skill before accepting a topology or recovery change.
 - `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`,
@@ -184,12 +189,185 @@ written atomically with a backup.
 
 ## Model routing
 
-The managed protocol carries semantic tiers plus optional exact model/thinking, toolset, denylist, thread, and worktree requests. pi-subagents resolves model references, validates scope, creates/cleans worktrees, and owns tool/session policy. Workflows fail closed with a diagnostic when the peer does not advertise managed-policy support; explicit selectors otherwise fail closed when unavailable, and workflows never bypass the companion's policy.
+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", { strength: "low" })
+await agent("design the migration", { strength: "high" })
+await agent("the ordinary case")                          // no strength: see below
+```
+
+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 `small|medium|large` profiles resolve in pi-subagents, avoiding a second registry/config schema.
+- **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 v3), including frozen invocation args, terminal result previews, script revisions, named nested-workflow result boundaries, and durable removals. Interrupted/provider-limited runs replay from the journal; schema-v2 declarative journals are quarantined rather than replayed. Foreground `AbortSignal`s stop owned children through explicit owner-scoped stop/quiescence, and dispose/branch replacement reject stale waiters.
+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.4.0",
+  "version": "1.6.0",
   "description": "Deterministic JavaScript orchestration workflows backed by pi-subagents managed spawning.",
   "type": "module",
   "license": "MIT",
@@ -17,10 +17,10 @@
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.0",
     "@earendil-works/pi-tui": "^0.84.0",
-    "@signalridge/pi-subagents": ">=1.5.0"
+    "@signalridge/pi-subagents": ">=1.9.0"
   },
   "dependencies": {
-    "@signalridge/pi-subagents-protocol": "^1.3.0",
+    "@signalridge/pi-subagents-protocol": "^1.4.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.4.0"
+  version: "1.6.0"
 ---
 
 # Workflow authoring
@@ -28,10 +28,22 @@ JavaScript.
 - Bound graph tasks, fan-out items, loops, retries, agents, concurrency, and
   evidence size. Invocation-level token and time caps are user constraints, not
   substitutes for algorithmic bounds.
-- Route an agent call with `tier: "small"`, `"medium"`, or `"large"`; omit
-  `tier` to use the pi-subagents workflow default. Never guess nonstandard model
-  routes, tiers, or agent types—use a name supplied by the current environment
-  and follow [registry ownership](references/registry-ownership.md).
+- 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).
 - Workflows have no imports, filesystem/network APIs, timers, or unrestricted
   Node APIs. Pass timestamps, randomness, and external decisions through `args`.
 
@@ -53,7 +65,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.
@@ -173,6 +187,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;
+  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.

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

@@ -1,8 +1,8 @@
 <!-- GENERATED from WORKFLOW_CAPABILITY_CONTRACT; do not edit by hand. -->
 # Workflow capability index
 
-Contract format: `1.0.0`<br>
-Contract content / skill / extension: `1.4.0`
+Contract format: `2.0.0`<br>
+Contract content / skill / extension: `1.6.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,15 +11,15 @@ 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>`model`: string (optional); default: pi-subagents model resolver<br>`tier`: small\|medium\|large (optional); default: pi-subagents workflow tier<br>`isolation`: "worktree" (optional); default: pi-subagents worktree policy<br>`thread`: string (optional); default: fresh session per call<br>`toolset`: string (optional); default: configured host/agent toolset hint<br>`excludeTools`: string[] (optional)<br>`agentType`: string (optional); default: general-purpose<br>`timeoutMs`: number \| null (optional); default: 300000 (5min); null disables<br>`retries`: number (optional); default: run retry count |
+| 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 |
 | parallel | runtime-global | `parallel(thunks) => Promise<Array<unknown \| null>>` | — |
 | pipeline | runtime-global | `pipeline(items, ...stages) => Promise<Array<unknown \| null>>` | — |
 | orchestrate | runtime-global | `orchestrate(tasks, options?) => Promise<{ results, tasks }>` | `onError`: "skip-dependents"\|"continue"\|"fail-fast" (optional); default: "skip-dependents" |
 | workflow | runtime-global | `workflow(savedName, childArgs?) => Promise<unknown>` | — |
-| verify | runtime-global | `verify(item, options?) => Promise<{ real, realCount, total, votes }>` | `reviewers`: number (optional); default: 2<br>`threshold`: number (optional); default: 0.5<br>`lens`: string \| string[] (optional) |
-| judgePanel | runtime-global | `judgePanel(attempts, options?) => Promise<{ index, attempt, score, judgments } \| undefined>` | `judges`: number (optional); default: 3<br>`rubric`: string (optional); default: overall quality and correctness |
+| verify | runtime-global | `verify(item, options?) => Promise<{ real, realCount, total, votes }>` | `reviewers`: number (optional); default: 2<br>`threshold`: number (optional); default: 0.5<br>`lens`: string \| string[] (optional)<br>`strength`: "low" \| "medium" \| "high" (optional); default: "low" |
+| judgePanel | runtime-global | `judgePanel(attempts, options?) => Promise<{ index, attempt, score, judgments } \| undefined>` | `judges`: number (optional); default: 3<br>`rubric`: string (optional); default: overall quality and correctness<br>`strength`: "low" \| "medium" \| "high" (optional); default: "low" |
 | loopUntilDry | runtime-global | `loopUntilDry({ round, key?, consecutiveEmpty?, maxRounds? }) => Promise<unknown[]>` | `round`: (roundIndex) => unknown[]; default: required<br>`key`: (item) => string (optional); default: JSON.stringify<br>`consecutiveEmpty`: number (optional); default: 2<br>`maxRounds`: number (optional); default: 50 |
-| completenessCheck | runtime-global | `completenessCheck(taskArgs, results) => Promise<{ complete, missing? } \| null>` | — |
+| completenessCheck | runtime-global | `completenessCheck(taskArgs, results, options?) => Promise<{ complete, missing? } \| null>` | `strength`: "low" \| "medium" \| "high" (optional); default: "medium" |
 | retry | runtime-global | `retry(thunk, options?) => Promise<unknown>` | `attempts`: number (optional); default: 3<br>`until`: (result) => boolean (optional); default: accept first result |
 | gate | runtime-global | `gate(thunk, validator, options?) => Promise<{ ok, value, attempts }>` | `attempts`: number (optional); default: 3 |
 | checkpoint | runtime-global | `checkpoint(prompt, options?) => Promise<unknown>` | `default`: unknown (optional); default: true when no UI and omitted<br>`headless`: "default" \| "abort" (optional); default: "default"<br>`kind`: "confirm" \| "input" \| "select" (optional); default: "confirm"<br>`choices`: string[] (optional)<br>`timeoutMs`: number (optional) |