@signalridge/pi-workflows 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,140 @@
 # Changelog
 
+## 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", tier: "low" }),
+  () => agent("Check for secrets", { label: "secrets", tier: "low" }),
+  () => agent("Check for dead code", { label: "dead-code", tier: "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, tier, isolation, thread, agentType, toolset, excludeTools, timeoutMs, retries })`
   — dispatch one subagent through the managed spawn protocol. Returns text, a
   schema-validated value, or recoverable `null` after retries. 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.
+  `tier` 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
@@ -184,12 +186,52 @@ 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.
+`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.
+
+```js
+await agent("summarize this diff", { tier: "low" })
+await agent("design the migration", { tier: "high" })
+```
+
+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.
 
 ## 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, 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.5.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.5.0"
 ---
 
 # Workflow authoring
@@ -28,10 +28,13 @@ 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 `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
+  [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`.
 
@@ -173,6 +176,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 tier
+  names a key in the host catalogue 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.5.0`
 
 This compact generated index covers supported runtime globals and workflow-tool inputs. For constraints, compatibility behavior, internal boundaries, and dynamic-reference ownership, follow the [exhaustive generated facts](capability-details.md).
 
@@ -11,7 +11,7 @@ This compact generated index covers supported runtime globals and workflow-tool
 <!-- BEGIN GENERATED SUPPORTED WORKFLOW CAPABILITIES -->
 | Name | Classification | Signature | Options and defaults |
 | --- | --- | --- | --- |
-| agent | runtime-global | `agent(prompt, options?) => Promise<string \| structured value \| null>` | `label`: string (optional); default: derived from phase and call count<br>`phase`: string (optional); default: current phase<br>`schema`: plain JSON Schema (optional)<br>`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>`tier`: agent tier key (optional); default: 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" |

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

@@ -1,8 +1,8 @@
 <!-- GENERATED from WORKFLOW_CAPABILITY_CONTRACT; do not edit by hand. -->
 # Exhaustive workflow capability facts
 
-Contract format: `1.0.0`<br>
-Contract content / skill / extension: `1.4.0`
+Contract format: `2.0.0`<br>
+Contract content / skill / extension: `1.5.0`
 
 Every exact fact below is projected from the installed extension's capability contract. Explanatory judgment belongs in the hand-written references next to this file.
 
@@ -16,8 +16,7 @@ Every exact fact below is projected from the installed extension's capability co
 - `label`: string (optional); default: derived from phase and call count
 - `phase`: string (optional); default: current phase
 - `schema`: plain JSON Schema (optional)
-- `model`: string (optional); default: pi-subagents model resolver
-- `tier`: small\|medium\|large (optional); default: pi-subagents workflow tier
+- `tier`: agent tier key (optional); default: the agent's own tier, else agentTiers.defaultTier
 - `isolation`: "worktree" (optional); default: pi-subagents worktree policy
 - `thread`: string (optional); default: fresh session per call
 - `toolset`: string (optional); default: configured host/agent toolset hint
@@ -30,7 +29,9 @@ Every exact fact below is projected from the installed extension's capability co
 - Constraint: resume replays only the longest unchanged prefix; the first miss and every later call execute live
 - Constraint: replayed calls do not consume the real-dispatch maxAgents or token/phase budgets
 - Constraint: spawnKeys rotate by generation on resume so pi-subagents never raises a fingerprint conflict
-- Constraint: explicit model is resolved and scope-checked by pi-subagents; unavailable selectors fail closed
+- Constraint: tier names a key in the host's agentTiers catalogue; a key it does not define is rejected before dispatch
+- Constraint: resolveAgentTier in pi-subagents owns model, thinking, clamping, availability, and the resolution snapshot
+- Constraint: there is no per-call model or thinking: a tier is the only model policy a workflow can express
 - Constraint: same-thread calls must be sequential and preserve a stable workflow thread name
 - Constraint: threads cannot be combined with worktree isolation
 
@@ -299,6 +300,7 @@ Every exact fact below is projected from the installed extension's capability co
 - Signature: `export const meta = { name, description, phases? }`
 - Constraint: must be the first statement
 - Constraint: name and description must be nonblank literals
+- Constraint: workflow meta and phase metadata cannot contain model or thinking fields
 - Constraint: spread, computed keys, methods, template interpolation, and __proto__/constructor/prototype are rejected
 
 <a id="script-contract-determinism"></a>

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

@@ -8,7 +8,7 @@ Start from the symptom, then reproduce through the real workflow runtime with de
 | `parallel()` rejects input | Promises were passed instead of thunks | [runtime](runtime.md#topology) |
 | Synthesis starts early | Fan-out was not awaited as one complete result set | [pattern selection](pattern-selection.md#fan-out-and-synthesize) |
 | Coverage silently disappears | `null` results were filtered before IDs were ledgered | [lifecycle](lifecycle.md#retry-and-recoverable-failure) |
-| Wrong model is used | A higher-priority selector overrides the expected route | [registry ownership](registry-ownership.md#priority) |
+| Wrong model or thinking is used | The call named no tier and fell to a default, or named one whose profile is not what you expected | [registry ownership](registry-ownership.md#priority) |
 | Unknown `agentType` log | A live registry name was guessed or is unavailable | [registry ownership](registry-ownership.md#agent-types) |
 | Budget exceeds the number shown | The budget is a soft pre-call gate and work was in flight | [lifecycle](lifecycle.md#bounds-and-budget) |
 | Later calls rerun on resume | An earlier call missed or changed, ending the replayable prefix | [lifecycle](lifecycle.md#resume) |
@@ -23,7 +23,7 @@ Start from the symptom, then reproduce through the real workflow runtime with de
 
 1. Reduce to the smallest script that preserves metadata, labels, work IDs, and the failing topology.
 2. Replace provider calls with deterministic, schema-aware fake agents.
-3. Record call order, labels, phases, prompts, results, and `null` entries.
+3. Record call order, labels, phases, prompts, resolved tiers, results, and `null` entries.
 4. When the failure turns on a disputed signature or default, compare it with the compact [capability index](capabilities.md); follow its exhaustive-facts pointer only when needed.
 5. Separate runtime defects from unsupported authoring assumptions and compatibility-only behavior.
 6. Fix only the demonstrated authoring issue; do not rely on known out-of-scope gaps in nested persistence, resume accounting, checkpoint forms/timeouts, metadata validation, or budget overshoot.

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

@@ -4,14 +4,16 @@ Model routes and agent types are dynamic references. Their shape and owner are d
 
 ## Model routes
 
-The `pi-subagents` workflow-tier settings own route names. Standard routes are `small`, `medium`, and `large`; use another route only when its name and purpose are supplied in context. A route is selected with `tier`. An exact user-requested model is selected with `model` and is resolved/scope-checked by pi-subagents.
+pi-subagents owns the agent-tier catalogue; a workflow names a key from it and nothing else. Available tier names depend on active configuration and are intentionally absent from static skill files — read them from the destination context.
+
+A name a script writes is not a claim that the name exists. Scripts that ship with this package name `low`/`medium`/`high` — the profiles a fresh install receives — and a host that does not define one of those drops it in favour of that host's default, with a log line. A script you write is held to the stricter rule: an undefined tier is a typo in a catalogue you own, so it is rejected before dispatch rather than rerouted. Write the tier you mean for the host you are targeting; do not copy `low`/`medium`/`high` in on the assumption that every machine has them.
 
 ## Agent types
 
-The agent registry owns agent-type names and their bound instructions, tools, model, and isolation policy. Use `agentType` only when context supplies both its name and purpose. Do not infer an agent type from a role-like label.
+The agent registry owns agent-type names and their bound instructions, tools, Agent-tier defaults, and isolation policy. Use `agentType` only when context supplies both its name and purpose. Do not infer an agent type from a role-like label.
 
 ## Priority
 
-An explicit per-call `model` wins. A named `agentType` model overrides a tier; an explicit `tier` suppresses the phase/run model so pi-subagents can apply the agent definition and then the selected workflow tier. Without a per-call model or tier, the phase/run model is used when present, followed by pi-subagents defaults and the parent session. Model and thinking fields are resolved independently. Avoid specifying competing selectors unless the override is deliberate.
+A call's `tier` takes precedence over an agent type's own tier default, which takes precedence over `agentTiers.defaultTier`. `resolveAgentTier()` in pi-subagents then resolves model, thinking, clamping, availability, and the immutable snapshot as one decision. Neither a call, nor workflow meta, nor a phase may carry model or thinking fields.
 
-Unavailability is fail-closed for explicit `model` and named tiers: pi-subagents reports the selector and does not silently run a different model. An omitted selector may inherit the parent session according to the companion's current settings.
+Unavailability is fail-closed: pi-subagents names the tier and does not silently run a different model. A managed call with no tier and no applicable default is rejected rather than inheriting the parent session.

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

@@ -6,6 +6,7 @@ Review author-visible behavior, not formatting preferences. When behavior depend
 
 - Is literal `export const meta` the first statement, with a short unique name and useful description?
 - Are only used phases declared, and does each named phase begin at the intended boundary?
+- Are workflow meta and phase objects free of retired `model`/`thinking` fields?
 - Does the script call at least one agent and explicitly return JSON-serializable data?
 - Are imports and nondeterministic APIs absent?
 
@@ -21,8 +22,9 @@ Review author-visible behavior, not formatting preferences. When behavior depend
 
 - Does JavaScript consume structured fields only after a small plain JSON Schema guarantees them?
 - Does synthesis receive complete coverage and failure ledgers?
-- Are `model`, `tier`, and `agentType` used according to selector priority?
-- Did every nonstandard route or agent type come from context with a name and purpose?
+- Does every `tier` name a key the destination host actually defines, rather than a guessed one?
+- Is the tier the only model/thinking policy source, via pi-subagents' `resolveAgentTier()`?
+- Did every tier or agent-type name come from context with a name and purpose?
 
 ## Lifecycle
 
@@ -33,6 +35,7 @@ Review author-visible behavior, not formatting preferences. When behavior depend
 - Does nesting stay one level, allow only safe sibling concurrency, and account for shared limits/store?
 - Are helper attempts and graph retries finite and separately visible?
 - Would lexical call order and generated graph order remain stable under resume?
+- Does the journal/tombstone retain the resolved `tier`, including one the host defaulted to?
 
 ## Compatibility and publication
 

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

@@ -4,7 +4,7 @@ Use this page for routine scripts. Open the generated capability index only when
 
 ## Script envelope
 
-Start with the only legal export: `export const meta = { name, description, phases?: [{ title, detail?, model? }] }`. Values are nonblank literals; declare only used phases and call `phase()` before each phase's work. The remaining body already runs inside an async function: write helpers as ordinary declarations; `export default` and other exports are invalid. Return the result explicitly.
+Start with the only legal export: `export const meta = { name, description, phases?: [{ title, detail? }] }`. Values are nonblank literals; declare only used phases and call `phase()` before each phase's work. Workflow meta and phase objects must not contain `model` or `thinking`; those retired fields are rejected. The remaining body already runs inside an async function: write helpers as ordinary declarations; `export default` and other exports are invalid. Return the result explicitly.
 
 The runtime supplies `agent`, `parallel`, `pipeline`, `orchestrate`, `workflow`, quality/control helpers, `phase`, `log`, `args`, `cwd`, restricted `process.cwd()`, and `budget`. Imports, `require()`, filesystem modules, `Date.now()`, `Math.random()`, and no-argument `new Date()` are unavailable. The Node VM realm is implementation substrate, not a security boundary or public API.
 
@@ -17,7 +17,7 @@ The runtime supplies `agent`, `parallel`, `pipeline`, `orchestrate`, `workflow`,
 
 ## Data and failure
 
-Call `agent(prompt, { label, schema? })`; it returns text, a schema-validated value, or recoverable `null`. Nonrecoverable limit, validation, and budget failures throw. Record each intended work ID before filtering. A `null` means missing coverage, never a negative finding.
+Call `agent(prompt, { label, schema?, tier? })`; it returns text, a schema-validated value, or recoverable `null`. `tier` names a key in the host's agent-tier catalogue. Nonrecoverable limit, validation, budget, unknown-tier, and unavailable-tier failures throw. Record each intended work ID before filtering. A `null` means missing coverage, never a negative finding.
 
 Use `agent(prompt, { thread: "implementer" })` when the same managed subagent must receive a later follow-up with its complete conversation intact. Reuse a thread name sequentially; never put same-thread calls in one `parallel()` batch. Threads are scoped to one workflow run/session and cannot use worktree isolation. A pause or process restart may require a fresh thread session.
 
@@ -25,6 +25,6 @@ When JavaScript reads fields, pass a small plain JSON Schema. Schema noncomplian
 
 ## Routing and support
 
-An explicit per-call `model` wins. A named `agentType` model overrides `tier`; specifying `tier` suppresses the phase/run model and delegates model/thinking resolution to pi-subagents. Without a per-call selector, the phase/run model is used when present, followed by pi-subagents defaults and the parent session. Explicit unavailable models and tiers fail closed. Worktree isolation is also fail-closed and remains owned by pi-subagents. See [registry ownership](registry-ownership.md).
+`tier` is a key in the host's agent-tier catalogue, not a model ID. The catalogue and its names belong to the user running the workflow; read the available keys from the destination context rather than assuming any particular name exists. A tier this host does not define is rejected before dispatch — only the scripts shipped with this package reroute to the host default instead, because they cannot know the catalogue they will land in. pi-subagents' `resolveAgentTier()` alone resolves the final model, thinking, clamping, availability, and snapshot. A tier the host does not define is rejected before dispatch. Omitting `tier` uses the agent's own tier, then `agentTiers.defaultTier`; a host whose default has been cleared rejects the call instead of inheriting the parent model. There is no per-call model or thinking, and workflow meta and phases may not carry them either. Worktree isolation remains owned by pi-subagents. See [registry ownership](registry-ownership.md).
 
 Generated entries marked `supported` are authoring API. `console` and whole-script Markdown fences are compatibility-only. VM realm facilities are internal. Active model routes and agent types are dynamic. Use `log()` in new scripts.

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

@@ -9,5 +9,5 @@ When copying a workflow between installations:
 1. Check the destination's generated version and exact capability facts.
 2. Re-check every supported global, option, and constraint used by the script.
 3. Treat compatibility entries as preservation aids, not portable recommendations.
-4. Re-resolve dynamic model routes and agent types from destination context; static docs intentionally contain no live entries.
+4. Re-resolve tier keys and agent types from destination context; both come from the destination host's configuration, and static docs intentionally contain no live catalogue entries.
 5. Prefer runtime behavior when prose and execution disagree, and report the documentation mismatch rather than changing behavior during an authoring fix.

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.4.0"
+  version: "1.5.0"
 ---
 
 # Built-in workflow patterns

package/skills/workflow-review/SKILL.md

@@ -2,7 +2,7 @@
 name: workflow-review
 description: Audit an existing Pi JavaScript workflow for topology, prompt/data flow, limits, failure handling, cancellation, resume safety, and publication compatibility. Use when reviewing or debugging a workflow script or saved run; do not use to run a standard named workflow.
 metadata:
-  version: "1.4.0"
+  version: "1.5.0"
 ---
 
 # Workflow review