ytdb-slate 0.5.0 → 0.5.1

package/README.md

@@ -53,7 +53,7 @@ Slate can ride through model API outages. The opt-in `modelFailover` map in `.pi
 
 ## Action-level model routing
 
-Slate can pick the model and the effort level per dispatched action rather than running every action on whatever model the orchestrator happens to be on. `router.models` in `.pi/slate.json` (trusted projects only) is a closed list of `provider/id` specs; a dispatch then runs on the `model` and `effort` arguments of that action, else on the thread's own base model and a level DERIVED for the model that actually runs — the lowest level that model has a capability measurement at, never a fixed default. The list is empty by default, and empty means off: no list is enforced, nothing is seeded, and model selection is exactly what it was before the router existed. Only models Slate ships a benchmark profile for can be routed to; entries pi cannot serve, or has no profile for, are dropped with a warning naming them.
+Slate can pick the model and the effort level per dispatched action rather than running every action on whatever model the orchestrator happens to be on. `router.models` in `.pi/slate.json` (trusted projects only) is a closed list of `provider/id` specs. Each action uses its `model` and `effort` arguments when present. Otherwise, it uses the thread's base model and a level DERIVED for the model it routes to. That level is the lowest one with a capability measurement, never a fixed default. The list is empty by default. An empty list disables candidate-list enforcement, base seeding, effort derivation, and the router's window, billing, and substitution paths. Per-action `model` and `effort` arguments stay active on both router states. Slate always checks an explicit effort against pi's vocabulary, and against the ladder of the model it routes to whenever it has that model's profile data. An action that omits `model` plans for the thread's pre-router pin, and a thread with no pin gives it no plan target. An action that omits `effort` resolves no level. In both cases the worker session returns to what it opened on. [`docs/model-routing.md`](docs/model-routing.md) holds the full contract, including the known cases where the model or level that runs differs. Only models Slate ships a benchmark profile for can be routed to; entries pi cannot serve, or has no profile for, are dropped with a warning naming them.
 
 What the code enforces is deliberately narrower than what the routing data advises. The dispatch guards refuse an unlisted model, a level off the target model's ladder and a level the provider rejects outright; they warn about — and mark — an unmeasured level, refusing it only when `router.allowUnmeasuredEffort` is `false`; and the context-window guard substitutes a wider listed model instead of ever blocking an action. The obligations that come from the profile data itself — keeping review and gate actions on measured levels, and honoring a REFUSE such as `anthropic/claude-fable-5`'s for zero-data-retention work — are stated in the doctrine for the orchestrator to honor; they are **not** code-enforced guards. Full semantics: the `router.*` rows in [Configuration](#configuration) and the shipped [`docs/model-routing.md`](docs/model-routing.md) — if they disagree, that document wins.
 
@@ -86,7 +86,7 @@ Optional config file: `slate.json` in the project's pi config dir (`.pi/slate.js
 | `reviewPerspectivesPath` | string | — | Project review charters, each declaring its own finding-ID prefix. The doctrine references this **path**; the orchestrator reads the file alongside the shipped review rules. |
 | `modelFailover` | object (string → string) | — (empty, failover off) | Map of `provider/id` → equal-quality alternative model; on a model API failure the affected site retries once on the mapped model (worker/orchestrator sites only after pi's own retries are exhausted; episode compression has no pi retry loop). Read once at session start — see [`docs/model-failover.md`](docs/model-failover.md). |
 | `preserveGlobalModelDefault` | boolean | `true` | Put pi's global model defaults (`defaultProvider`, `defaultModel`, `defaultThinkingLevel`) back after a Slate-initiated model switch — orchestrator failover and handoff adoption — so the switch stays session-scoped. `false` turns that restore off at both sites (the switches themselves are unaffected), leaving each one persisted in pi's global settings. Best-effort: Slate reverts only a value its own switch produced, and can stand down or give up — limits in [`docs/model-failover.md`](docs/model-failover.md). |
-| `router.models` | string[] | `[]` (empty — routing off) | Closed list of models (`provider/id`) an action may be routed to. **Empty or absent means the router is OFF and dispatch behaves exactly as it did before the router existed** — no model list is enforced and no thread gets a seeded base model. A listed model becomes routable only where four things intersect: your list, a benchmark profile Slate ships for that model, pi's model registry, and credentials pi actually has configured; anything that fails one of those is dropped with a warning naming it (if every entry drops, routing turns off with one summary warning). Read once at session start and resolved once per session — see [`docs/model-routing.md`](docs/model-routing.md). |
+| `router.models` | string[] | `[]` (empty — routing off) | Closed list of models (`provider/id`) an action may use. Empty or absent means the router is OFF. Slate enforces no candidate list, seeds no thread base, derives no effort level, and runs no router-only window, billing, or substitution path. Per-action `model` and `effort` arguments stay active on both router states. Slate still checks explicit effort against pi's vocabulary and the routed model's ladder when it has that model's profile data. An action that omits `model` plans for the thread's pre-router pin, and a thread with no pin gives it no plan target. An action that omits `effort` resolves no level. In both cases the worker session returns to what it opened on. The known cases where the model or level that runs differs are listed in [`docs/model-routing.md`](docs/model-routing.md). A listed model becomes routable only if Slate has its benchmark profile, pi registers it, and credentials are configured. Slate drops other entries with a warning. If all entries drop, routing turns off with one summary warning. Slate reads and resolves the list once per session. See [`docs/model-routing.md`](docs/model-routing.md). |
 | `router.allowUnmeasuredEffort` | boolean | `true` | What happens when an explicitly requested effort level is on the target model's ladder but has no capability measurement in Slate's profiles: `true` dispatches it with a ⚠ notice and marks the episode `(unmeasured level)`; `false` refuses the dispatch. Either way a level that is off the model's ladder, or one the provider rejects outright, is refused, and a level Slate DERIVES for an action is always a measured one. |
 
 Example `.pi/slate.json` (the `docs/agents/...` paths are placeholders — point them at markdown files that actually exist in **your** project):

package/docs/design-principles.md

@@ -194,7 +194,9 @@ context budget, also decide per dispatch whether a worker thread still
 fits the model it is routed to, in which case the action moves to the
 widest listed model rather than being blocked.
 
-The feature is OFF until `router.models` lists something, and it is
+Candidate routing is OFF until `router.models` lists something — the
+per-action `model` and `effort` arguments, and a fallback a failover
+is holding, stay active either way. The feature is
 built on a deliberate split that is worth holding onto when reasoning
 about the architecture: the code ENFORCES less than the routing data
 ADVISES. Dispatch guards refuse what is mechanically wrong — a model

package/docs/model-failover.md

@@ -89,11 +89,11 @@ Failover applies at three sites:
   model and the failed action is re-prompted once with a continuation
   nudge. The transcript is preserved; usage and cost accumulate across
   both attempts. The thread stays on the mapped model while its
-  session is live and returns to its configured model when the session
-  is reopened (e.g. after a pi restart). The `threads` listing marks a
-  switched live session as `model=A ⇒B (live)` — the marker means a
-  live failover switch happened (it is not a value comparison) and
-  disappears when the session is reopened.
+  session is live, including across later model-less actions, and the
+  `threads` listing marks it `live=<model> (failover)`. The hold, the
+  marker and the retry inside the failing dispatch are cases M1, M6
+  and M2 of [Known cases where the model or level
+  differs](model-routing.md#known-cases-where-the-model-or-level-differs).
 - **Episode compression.** The compression call is retried once with
   the mapped compressor model — only if it is distinct from the
   original, resolvable, and authed. If the retry also fails, the

package/docs/model-routing.md

@@ -6,14 +6,19 @@ list of models an action may run on; every dispatch then resolves to
 one model from that list and one effort level from that model's own
 ladder — chosen to be up to the task and no more, so the bill is
 bounded by the action rather than by the session's current model.
-The list is empty by default: with no entries the router is OFF, no
-model list is enforced, no thread gets a seeded base, and a
-dispatch that names no model resolves exactly as it did before the
-router existed — the thread's pre-router pin, else the host
-session's model. (The per-action `model` and `effort` arguments
-themselves are honoured on both router states; see the accepted
-limitations.) This document is reference documentation, not
-workflow doctrine.
+The list is empty by default. With no entries the router is OFF: no
+model list is enforced, no thread gets a seeded base, no effort level
+is derived, and the router's window, billing and substitution paths
+are inert. A dispatch that names no model then plans for the thread's
+pre-router pin, and for no model at all when the thread has none: a
+new worker opens on the host session's model, and a reused one stays
+on the model it opened on. The per-action `model` and `effort`
+arguments are honoured on both router states. What a dispatch plans
+is not always what it runs; the cases known to bite are collected
+under [Known cases where the model or level
+differs](#known-cases-where-the-model-or-level-differs).
+
+This document is reference documentation, not workflow doctrine.
 
 A model can only be routed to if Slate ships a benchmark profile for
 it. An entry with no profile is named in a warning and excluded —
@@ -26,36 +31,44 @@ from](#where-the-numbers-come-from-and-how-stale-they-can-be).
 
 ## What routing decides, per action
 
-Two levers, both per dispatch — on a new thread and on a
+Two route inputs are per dispatch — on a new thread and on a
 continuation alike:
 
 - **the model** — the `model` argument (`"provider/id"`), else the
-  thread's base model (router ON), else the thread's pre-router pin
-  or the host session's model (router OFF);
+  thread's base model (router ON), else the thread's pre-router pin,
+  else no plan target at all, in which case the session returns to
+  the model it opened on (router OFF; M1, M3, M7);
 - **the effort level** — the `effort` argument (one of pi's thinking
-  levels), else a level Slate resolves for the model that actually
-  runs (router ON) or the level the worker session opened on (router
+  levels), else a level Slate resolves for the model it routes to
+  (router ON) or the level the worker session opened on (router
   OFF). See [Effort levels](#effort-levels).
 
-Neither is sticky, and that is the guarantee to hold on to: an
-explicit `model` or `effort` governs its own action and no later
-one. An omitted `model` resolves to the thread's base. An omitted
-`effort` resolves differently on the two router states, and neither
-of them is "whatever the last action asked for":
+The arguments themselves do not become thread defaults. An explicit
+`effort` never governs a later action. An explicit `model` governs
+only its own action too, outside M1, M3, M6 and M7. An omitted `effort`
+is never "whatever the last action asked for":
 
 - **router on** — the thread's base effort, re-validated, or a level
-  derived for the model that runs (see [Effort
+  derived for the model it routes to (see [Effort
   levels](#effort-levels)). A thread based on `luna@medium` whose
   previous action ran at `max` runs the next one at `medium`.
-- **router off** — nothing is resolved, so the worker session is put
-  back to the level it opened on, which is pi's own settings default
+- **router off** — the worker session is put back to the level it
+  opened on, which is pi's own settings default
   (`defaultThinkingLevel`, else pi's built-in default). Slate passes
   that level explicitly at every open, so it is re-clamped against
   the session's current model rather than inherited from the session
   file.
 
-A thread's base model and base effort are separate state, visible in
-the `threads` listing, and are never set from an action's own route.
+The model axis carries live-session cases the effort axis does not,
+M1 and M3 among them, and they predate action-level routing. The
+effort axis shares only M7. All of them, with the code that
+implements each, are under [Known cases where the model or level
+differs](#known-cases-where-the-model-or-level-differs).
+
+A thread's base model and base effort are separate planning state,
+visible in the `threads` listing, and are never set from an action's
+own route. A live failover marker, when present, identifies the
+model that currently overrides that nominal base.
 
 Two things can come back instead of a normal episode:
 
@@ -68,6 +81,120 @@ Two things can come back instead of a normal episode:
   result — advisory: an evidence gap, a window substitution, a
   long-context billing cliff, a re-seeded base. The action ran.
 
+## Known cases where the model or level differs
+
+The model and the level an action runs on are not always the ones it
+asked for, or the ones its thread implies. The cases below are the
+ones known to bite, each with the code that implements it. **This
+list is not exhaustive.** `planRoute`, `decideModelSwitch` and
+`decideEffortSwitch` in `extension/route.ts`, applied by `applyRoute`
+in `extension/threads.ts`, are the authority: read them when you need
+certainty rather than a map. This section is the reference for these
+cases. Other sites may name or summarise them; if a summary disagrees,
+this section governs, with the source functions above the ultimate
+authority.
+
+Why the MODEL can differ:
+
+- **M1 — a live failover holds the thread.** After a successful
+  `modelFailover` the worker stays on its fallback, and a dispatch
+  that omits `model` keeps it: the revert to the session's opening
+  model stands down (BG16). The hold ends when the session is
+  disposed, and when a later non-`openOnly` route moves it — an
+  explicit `model` on either router state, or the thread's routed
+  base while the router is ON. An OFF pre-router pin is `openOnly`
+  and does not release it. A reopen ends it too, except in M6.
+  *Code:* the `failover-held` keep in `decideModelSwitch`
+  (`route.ts`); `applyRoute` clears the marker after a plan-driven
+  `setModel`, and `liveFailoverModel` reports it (`threads.ts`).
+- **M2 — a failover fires inside the dispatch.** When the attempt
+  fails with a model-API error, Slate switches the live session to
+  the mapped model and re-prompts once. One episode covers both
+  attempts, and its `ran:` line names the model the action ended on
+  rather than the planned one. *Code:* the `isFailoverCandidate`
+  block in `runDispatchInner` (`threads.ts`) and `planFailoverSwitch`,
+  guard 7 (`route.ts`).
+- **M3 — the revert was attempted and failed.** A dispatch that names
+  no model switches the session back to the model it opened on. When
+  that spec no longer resolves, or `setModel` throws, Slate warns and
+  leaves the session on the model the previous action left it on
+  (BG24). A PLAN-driven switch that fails is the opposite case: the
+  dispatch aborts, nothing runs and no episode is written. M7 is the
+  case where no revert is attempted at all. *Code:* `giveUp` inside
+  `applyRoute` (`threads.ts`).
+- **M4 — the window guard substitutes** (router ON). A model that
+  cannot hold the thread's context is replaced by the widest listed
+  candidate, and only when one is STRICTLY wider than the model it
+  would replace. When nothing listed is wider, the action runs on the
+  original model and a warning says pi will compact. It never blocks
+  the action, and `substitutedFrom` records a replacement. *Code:*
+  `strictlyWider` in `planRoute`'s guard 5 (`route.ts`).
+- **M5 — the thread's base was not routable** (router ON). A base
+  that is absent or has fallen off the list is re-seeded to a listed
+  candidate with a warning, so a model-less dispatch runs on the
+  seeded base and not on the value the record carried. *Code:* the
+  re-seed branch of `planRoute` with `defaultBase` (`route.ts`),
+  written back by `persistReseededBase` (`threads.ts`).
+- **M6 — a reopened session restores a model from its file** (CQ3).
+  Slate passes the reopening model explicitly whenever the dispatch
+  resolves one, and that overrides the session file. When the
+  dispatch resolves no model at all and the host session has none
+  either, pi restores the file's last model change instead, which can
+  be a fallback M1 was holding. The `live=` marker is cleared on every
+  reopen, so in this one shape the fallback outlives its marker.
+  *Code:* `opts.model ? resolveModel(ctx, opts.model) : ctx.model` in
+  `openWorkerSession` (`worker.ts`); the marker delete in
+  `openWorkerFor` and the CQ3 note on `liveFailoverModel`
+  (`threads.ts`).
+- **M7 — nothing was captured to return to.** When the worker session
+  reported no model as it opened, there is no revert target, and a
+  dispatch that names no model leaves the session where it is with no
+  switch attempted. The effort axis has the same keep when no opening
+  level was captured. *Code:* `NO_SESSION_BASELINE` and the
+  `no-baseline` keeps in `decideModelSwitch` and `decideEffortSwitch`,
+  fed by `captureSessionBaseline` (`route.ts`).
+
+Why the LEVEL can differ. There is no counterpart to M1 here: a
+dispatch that names no `effort` returns the session to the level it
+opened on. M7 and E6 are known cases in which it does not.
+
+- **E1 — pi clamps a level Slate cannot judge.** When the ladder for
+  the judged model is unreadable — no profile, a throwing lookup, a
+  non-array ladder — the guards stand down and the level goes to pi,
+  which clamps it to something the model offers. Slate reports
+  nothing, because it has no evidence to report. *Code:*
+  `checkEffortFor` and `guardEffort`'s `ladderKnown` (`route.ts`).
+- **E2 — M4 moved the model under an explicit level.** A level that
+  is not valid on the substituted model is DROPPED with a warning
+  rather than refusing the action — a context size must never
+  hard-block a dispatch — and the session's opening level applies.
+  *Code:* the `soft` branch of `guardEffort` (`route.ts`).
+- **E3 — a stored base level no longer holds.** A base effort is a
+  cached derivation over a table that ships with Slate. When today's
+  table no longer reads it as `ok`, it is silently re-derived for
+  that model: nobody asked for that level, so a stale cache is
+  Slate's to correct rather than news to report. *Code:* the stored
+  base-effort branch of `planRoute`, with `lowestMeasuredEffort`
+  (`route.ts`).
+- **E4 — the action's model is not the base model.** An explicit
+  `model`, or M4, drops the inherited base level and derives the new
+  model's own lowest measured level instead. A level derived for one
+  model is never carried onto another. *Code:* the effort resolution
+  in `planRoute`, keyed on `judgedModel` (`route.ts`).
+- **E5 — M2 re-clamps the level.** The failover route requests no
+  level, and pi re-clamps the session's current level for the
+  fallback model. *Code:* `session.setModel(mapped)` in the failover
+  block (`threads.ts`); `openWorkerSession` passes the settings
+  default explicitly at every open for the same reason (`worker.ts`).
+- **E6 — the level was judged for one model and another model runs.**
+  When M1, M3 or M7 leaves the session on a model other than the plan
+  target, the level the plan resolved is still applied, and pi clamps
+  it to that model's own ladder with nothing reported.
+  `effortJudgedFor` names the model the judgement was about, which is
+  then not the model that ran. *Code:* the effort switch in
+  `applyRoute`, which runs after a model `keep` (`threads.ts`), and
+  `decideEffortSwitch` (`route.ts`).
+
 ## Configuration
 
 `router` lives in `.pi/slate.json` and, like the rest of that file,
@@ -196,7 +323,8 @@ The vocabulary is pi's ladder and nothing else: `off`, `minimal`,
 actually offers is per model — the shipped table records a ladder
 per model id, not a family rule.
 
-**An omitted `effort` never resolves to a fixed default.** In order:
+**An omitted `effort` never resolves to a fixed default.** With the
+router ON, in order:
 
 1. the thread's stored base effort — but only when the action runs
    on the thread's base model, and only while that stored level
@@ -205,8 +333,8 @@ per model id, not a family rule.
    the ladder, or onto the provider's rejection list) is silently
    re-derived; nobody asked for it, so a stale cache is Slate's
    problem to correct rather than news to report;
-2. otherwise the **lowest measured level of the model that actually
-   runs** — the lowest level on its ladder that carries a traced
+2. otherwise the **lowest measured level of the model it routes to**
+   — the lowest level on that model's ladder that carries a traced
    capability measurement. A level derived for one model is never
    carried onto another, so an explicit `model`, or a window
    substitution, re-derives it;
@@ -214,14 +342,19 @@ per model id, not a family rule.
    the level the worker session opened on applies, which is pi's own
    settings default — never a level another action left behind.
 
+With the router OFF Slate resolves no level at all, so that same
+opening level applies to every action that omits `effort`.
+
 So a higher level is only ever reached by naming it: pass `effort`
 explicitly on the dispatch. A derived level is measured by
 construction and therefore cannot trip the effort guards; only an
 explicit one can.
 
-An explicit level is judged against the model the action will
-actually run on, and the difference between a warning and a refusal
-is:
+An explicit level is judged against the model the action routes to,
+which `effortJudgedFor` names. [Known cases where the model or level
+differs](#known-cases-where-the-model-or-level-differs) collects what
+can move either afterwards. The difference between a warning and a
+refusal is:
 
 - **evidence gap** (the level is on that model's ladder but no
   traced source reports a capability result there) — advisory. The
@@ -230,8 +363,8 @@ is:
   `router.allowUnmeasuredEffort: false` turns this one case into a
   hard refusal for the whole project;
 - **off the model's ladder** — refused, whenever the ladder is
-  known. pi would otherwise clamp the level silently and the
-  orchestrator would believe the action ran at a level the model
+  known, outside E2. pi would otherwise clamp the level silently and
+  the orchestrator would believe the action ran at a level the model
   never offered;
 - **rejected outright by the provider** — refused, always. Such a
   level is still on pi's ladder for the model (the table records the
@@ -300,13 +433,15 @@ model's ladder is unreadable.
   its decision to make), the same lines in the live progress output,
   and `details.ranModel` / `details.ranEffort` /
   `details.ranEffortUnmeasured` / `details.warnings` for a renderer.
-- **In the `threads` listing:** `base=<model>@<level>?` — what a
-  dispatch that omits `model` will run on. The trailing `?` marks
+- **In the `threads` listing:** `base=<model>@<level>?` — the nominal
+  plan target when a dispatch omits `model`. The trailing `?` marks
   the level, not the model, as provisional: it is a stored default,
-  re-checked on every dispatch. Then `last=<model>@<level>` — what the thread's
-  last action actually ran on, with `(unmeasured)` where that
-  applies — and `live=<model> (failover)` while a failover holds the
-  live session.
+  re-validated against the model's current capability data on every
+  dispatch and silently re-derived if it no longer holds. `last=` is
+  the model and level that the last action actually ran on, with
+  `(unmeasured)` where that applies. `live=<model> (failover)` means
+  a held fallback currently overrides the nominal base for the live
+  session.
 - **At the session level:** the resolution's own warnings, as UI
   notifications (console when no UI is attached).
 - **In the orchestrator's own system prompt, every turn:** the
@@ -519,13 +654,16 @@ concern; a green suite says nothing about it.
   dispatch guard and anything else that consults the router agree.
   A key or provider added mid-session, and an edit to
   `slate.json`, both need a new pi session.
-- **Router OFF is not "no effort checking".** With an empty list
-  there is no model list, no window guard, no billing notice, no
-  seeded base and no substitution — but an explicit `effort` is
-  still judged against the shipped profile for the model that runs,
-  when pi's registry can serve that model. The `model` argument
-  itself is passed through byte-for-byte, so a malformed spec still
-  produces pi's own error.
+- **Router OFF disables candidate routing, not action arguments or
+  failover.** With an empty list there is no model list, window
+  guard, billing notice, seeded base or candidate substitution, and
+  Slate derives no effort level. A model-less plan targets the
+  thread's pre-router pin, else nothing, so the session returns to the
+  model it opened on outside M1, M3 and M7, and to the level it opened
+  on outside M7 and E6. An explicit `effort` is still judged against
+  the shipped profile for the plan target when pi's registry can serve
+  that model. The `model` argument itself is passed through
+  byte-for-byte, so a malformed spec still produces pi's own error.
 - **A mid-thread model switch costs the prompt cache.** A long
   thread runs overwhelmingly on cache reads; routing a small action
   to a cheaper model on a cold cache can cost more than staying on

package/docs/pr-publishing.md

@@ -59,6 +59,31 @@ The description becomes the squash-commit body on the default
 development branch — it is the permanent git-archaeology record for
 the change. Write it accordingly.
 
+Aim to keep the final delivery commit body at or below 16,384 UTF-8
+bytes, excluding the subject. This is a target, not a gate. Measure
+the exact body text as UTF-8 without adding a newline: for a PR, count
+the GitHub API `body` string; for a delivered commit, count the byte
+sequence after the subject separator in `git cat-file commit <sha>`.
+Do not use a formatted `git log` value such as `%b`, which adds an
+output newline.
+
+If the body is larger, first remove repetition and merge overlapping
+material. Then record a size exception in Risks & accepted trade-offs
+carrying measurements, not assurances: the overrun, by the canonical
+method above; every top-level section's byte count by that same
+method, largest first; and, for each section that was condensed, its
+byte count before condensing. A section with no before-count is
+visibly untouched, so the user weighs any claim that nothing could be
+removed against the counts beside it, and can refuse the exception. Do
+not remove decisions, risks, verdicts, or evidence needed to
+understand or review the change only to meet the target.
+
+By the canonical measurement above, the most recent accepted delivery
+body, from the publishing-enabled path, was 20,957 bytes: 27.9% above
+the target. That precedent establishes that a justified overrun can
+pass; it does not establish the typical size of either delivery path
+or a content-equivalent exception in the publishing-disabled path.
+
 ## Tracks table
 
 The description's Tracks section holds the track table; its
@@ -102,6 +127,14 @@ executed in order:
   description, including the Planned changes section, describes the
   change as implemented, folding in everything added, dropped, or
   reshaped since the draft PR was opened.
+- Resolve every remaining Open Question, or record its user-approved
+  deferral or accepted uncertainty in Risks & accepted trade-offs. A
+  mention without the user's disposition is not enough.
+- Measure the final PR description by the canonical method in §
+  Description rules. If it exceeds the target, verify that Risks &
+  accepted trade-offs carries the size exception's measurements: the
+  overrun, the per-section counts, and the before-counts of whatever
+  was condensed.
 - Last, re-read the whole PR description end-to-end to confirm the
   as-flipped text tells one consistent story.
 
@@ -110,10 +143,13 @@ executed in order:
 The user may wait for CI green and/or peer-review completion and ask
 the agent to fix test failures or review observations. The agent lands
 fixes as normal commits, keeps the description in sync, and presents
-agent-landed commits to the user as they land. Commits pushed directly
-by reviewers are visible in the PR UI; the agent reconciles the
-description with them on its next task. The user's merge act is the
-final approval.
+agent-landed commits to the user as they land. After every post-flip
+description change, and again at the final handoff for merge, repeat
+the byte measurement and any over-target size exception required by §
+Description rules. Commits pushed directly by reviewers are visible in
+the PR UI; the agent reconciles the description with them on its next
+task. The user's merge act is the final approval, including acceptance
+of any recorded size exception.
 
 ## After the merge
 

package/docs/track-workflow.md

@@ -108,6 +108,35 @@ explicitly hands any remaining Open Questions to the user, then
 deletes the log file. On abandonment the agent deletes the log file
 after offering its content to the user for archiving.
 
+Aim to keep the final delivery commit body at or below 16,384 UTF-8
+bytes, excluding the subject. This is a target, not a gate. Measure
+the exact body text as UTF-8 without adding a newline: count the byte
+sequence after the subject separator in `git cat-file commit <sha>`.
+Do not use a formatted `git log` value such as `%b`, which adds an
+output newline. For a proposed commit, apply the same rule to the
+exact body text before committing.
+
+If the body is larger, first remove repetition and merge overlapping
+material. Then add a `Size exception` paragraph to the delivery commit
+body carrying measurements, not assurances: the overrun, by the
+canonical method above; every top-level section's byte count by that
+same method, largest first; and, for each section that was condensed,
+its byte count before condensing. A section with no before-count is
+visibly untouched, so the user weighs any claim that nothing could be
+removed against the counts beside it, and can refuse the exception. Do
+not remove decisions, risks, verdicts, or evidence needed to
+understand or review the change only to meet the target. Immediately
+before presenting the final delivery commit to the user, measure it by
+that method and obtain the user's approval of the body and of any size
+exception; repeat both steps if the body changes before it lands.
+
+By this canonical measurement, the most recent accepted delivery body
+from the publishing-enabled path was 20,957 bytes, 27.9% above the
+target. That precedent establishes only that a justified overrun can
+pass in that path. Publishing-enabled descriptions can carry material
+that this path does not, so the figure is neither a direct measurement
+nor an exercised exception for publishing-disabled delivery.
+
 ### Under-trigger guardrail
 
 When shaping the planned-changes statement without a log, state this

package/extension/index.ts

@@ -101,9 +101,9 @@ export default function (pi: ExtensionAPI) {
 	// One MEMOIZED model-router resolution per session (model-router.ts), reassigned
 	// every session_start below for the same reason as the resolver above: the
 	// candidate list is frozen at first use, and a dispatch guard built from a
-	// different resolution than the doctrine describes would be a bug. Starts as the
-	// off resolution — dispatch then behaves exactly as it did before the router
-	// existed — until session_start has sanitized `router.models`.
+	// different resolution than the doctrine describes would be a bug. Starts at the
+	// shared OFF resolution — no candidate list is available — until session_start
+	// has sanitized `router.models`.
 	let resolveModelRouterResolution: () => ModelRouterResolution = () => ROUTER_OFF;
 
 	// One base-model tracker per session (base-model.ts), reassigned every

package/extension/mode.ts

@@ -339,7 +339,7 @@ ${n}. Route every action to the cheapest model and effort that clears it. Routab
 ${rows.join("\n")}${legend === "" ? "" : `\n   ${legend}.`}
    \`model\` and \`effort\` route THAT action only. Omit \`model\` for the thread's
    base${newThreadBase}; omit \`effort\` for its base
-   level, else the FIRST measured level of the model that runs — never a higher
+   level, else the FIRST measured level of the model it routes to — never a higher
    one, so name the level harder work needs. Off-ladder and provider-rejected
    levels are tool errors; an unmeasured one ${gap}.
    Prices are base rates: some models bill a long-context multiplier above a

package/extension/model-router.ts

@@ -2,9 +2,9 @@
  * Model router: resolving WHICH models an action may be dispatched to, and at
  * which effort levels.
  *
- * The router is OFF by default and OFF-behaviour is the pre-router behaviour:
- * with no `router.models` configured nothing here changes a dispatch. When a
- * project DOES list models, this module maps that list plus pi's model registry
+ * The router is OFF by default: with no `router.models` configured this resolver
+ * returns no candidates and emits no router warning. When a project DOES list
+ * models, this module maps that list plus pi's model registry
  * plus the benchmark profiles in model-profiles.ts onto a small, ordered set of
  * routable candidates — and the warnings that make the gaps in that data
  * visible instead of silent.
@@ -423,9 +423,9 @@ function tierOf(profile: ModelProfile): number {
  * Resolve the routable candidate set.
  *
  * An empty model list returns ROUTER_OFF WITHOUT touching the registry or the
- * profile table — the fast path, since the router is off by default and that
- * path must stay behaviourally identical to the pre-router extension. Every
- * warning is emitted at most once per condition (D58), sanitized, through
+ * profile table — the fast path, since the router is off by default and there
+ * are no candidates to resolve. Every warning is emitted at most once per
+ * condition (D58), sanitized, through
  * `warn` (default no-op) and collected on the result.
  *
  * Hostile/raw input is handled here rather than assumed away: `models` may be
@@ -770,8 +770,11 @@ function frozenResolution(
  * decides anything — `router.allowUnmeasuredEffort` and the refusal wording
  * live in the dispatch path.
  *
- * With the router OFF every pair is `ok`: the list guard is inert exactly as it
- * was before the router existed. An omitted/empty effort is also `ok` — the
+ * With the router OFF this predicate reports `ok` for every pair, having no
+ * candidate list to judge against — a statement about THIS function only, since
+ * route.ts feeds it a SYNTHESISED one-candidate resolution built from its
+ * injected profile source, so a router-OFF explicit level can still be refused.
+ * An omitted/empty effort is also `ok` — the
  * ladder question only arises for a level the caller actually asked for.
  * `listedGap` distinguishes an authored evidence gap from one the table never
  * mentioned (see EffortVerdict/BG9); both are advisory.
@@ -823,9 +826,9 @@ export function checkEffort(resolution: ModelRouterResolution, spec: string, eff
  * The memo holds unconditionally (BG3). Warnings already go through a
  * try/catch, and a throw from `getInput` or from anything else in resolution is
  * caught here and cached as an OFF resolution carrying one warning: the router
- * failing is not a reason to keep re-running it every turn, and OFF is the
- * pre-router behaviour, so dispatch keeps working. There is deliberately NO
- * second message-level dedup layer — it made the real dedup untestable (CQ4)
+ * failing is not a reason to keep re-running it every turn, and an empty
+ * candidate result is safe for candidate-dependent guards. There is deliberately
+ * NO second message-level dedup layer — it made the real dedup untestable (CQ4)
  * while adding nothing the memo does not already guarantee.
  *
  * CQ7: what is frozen includes the registry and auth SNAPSHOT. A key added to

package/extension/route.ts

@@ -29,10 +29,10 @@
  *   refused: the fall-through path must always have a valid destination, or
  *   configuring a list would strand every thread that predates it.
  *
- *   EFFORT — the level an action runs at is ALWAYS one that belongs to the model it
- *   actually runs on: either the caller named it, in which case it is judged against
- *   THAT model's own ladder, or it is derived from that model (its lowest MEASURED
- *   level). A level derived for one model is never carried onto another, and a level
+ *   EFFORT — the level the planner resolves is ALWAYS one that belongs to the model
+ *   it routes to: either the caller named it, in which case it is judged against THAT
+ *   model's own ladder, or it is derived from that model (its lowest MEASURED level).
+ *   A level derived for one model is never carried onto another, and a level
  *   STORED for this one is only replayed while today's table still reads it as `ok` —
  *   a cached derivation must not outlive the evidence it was derived from. `effort`
  *   therefore reports one and only one thing, and `effortJudgedFor` names the model
@@ -43,13 +43,14 @@
  * DIFFERENT model, and applying it produced evidence-gap warnings — or, with
  * allowUnmeasuredEffort:false, outright rejections — for a level nobody requested.
  *
- * WITH THE ROUTER OFF THIS MODULE IS INVISIBLE. No list, no window guard, no
- * billing notice, no seeded or persisted base, no tracker: the model a dispatch
- * runs on is the `model` ARGUMENT (honoured per action, which is the one addition)
- * or else the thread's PRE-ROUTER PIN — and the pin is only ever the model a NEW
- * worker session opens with, never a reason to switch a live one (`openOnly`).
- * The argument itself is passed through byte-for-byte, so a malformed spec still
- * produces pi's own error rather than a router opinion.
+ * WITH THE ROUTER OFF ITS PLANNER-OWNED MECHANISMS ARE INERT. There is no list,
+ * window guard, billing notice, seeded or persisted base, or tracker input. The
+ * plan target is the `model` ARGUMENT (honoured per action) or else the thread's
+ * PRE-ROUTER PIN; the pin only opens a NEW worker session and never instructs a
+ * live one to switch (`openOnly`). A later switch decision KEEPS a held failover
+ * fallback rather than applying an open-only target (decideModelSwitch). The raw
+ * argument still passes through byte-for-byte, so a malformed spec produces pi's
+ * own error rather than a router opinion.
  *
  * A FAILURE TO READ EVIDENCE IS NOT EVIDENCE OF A PROBLEM. Every injected data
  * source may be missing, throwing or malformed — a profile lookup, a ladder
@@ -68,13 +69,13 @@
  *      is one that is not a STRING at all, since reading a malformed argument as
  *      absent would quietly run the action at the thread's base level instead.
  *   1. LIST MEMBERSHIP (router ON only): a resolved model outside the effective
- *      candidate list is rejected, naming the list. With the router OFF the model
- *      argument behaves exactly as it did before the router existed.
+ *      candidate list is rejected, naming the list. With the router OFF this guard
+ *      does not enforce a list; the raw model argument continues to pi unchanged.
  *      A THREAD'S BASE is exempt by REPAIR, not by exception — see THE ONE RULE
  *      above: absent or off-list, it is re-seeded, so only an EXPLICIT off-list
  *      model is ever refused.
  *   5. CONTEXT WINDOW: never a hard block, and it runs BEFORE the effort guards so
- *      that every effort judgement is about the model that will actually run. The
+ *      that every effort judgement is about the model the planner routes to. The
  *      REGISTRY window (which is what a RouterCandidate carries; a profile's own
  *      figure is documentation only) reduced by pi's compaction reserve, judged by
  *      pi's OWN predicate. A model that cannot hold the thread's context is
@@ -153,7 +154,7 @@ export interface RoutePlanInput {
 	requestedModel?: string;
 	/** The dispatch's `effort` argument, raw and unvalidated. */
 	requestedEffort?: string;
-	/** The session's FROZEN router resolution. An off resolution = the pre-router dispatch path. */
+	/** The session's FROZEN router resolution. An off resolution supplies no router candidates. */
 	resolution: ModelRouterResolution;
 	/** router.allowUnmeasuredEffort. Default TRUE: only an explicit false refuses an evidence gap. */
 	allowUnmeasuredEffort?: boolean;
@@ -429,7 +430,7 @@ export type EffortSwitchDecision =
  * whole rule, in one pure function, mirroring decideModelSwitch:
  *
  *   1. the level the PLAN resolved (an explicit `effort`, the thread's stored default
- *      once re-validated, or one derived for the model that runs);
+ *      once re-validated, or one derived for the model the planner routes to);
  *   2. failing that, the level the session was OPENED on — pi's clamped settings
  *      default. This is the RESTORE, and it is what makes `effort` per-ACTION: without
  *      it a level set by one action silently governs the next (BG18).
@@ -515,11 +516,10 @@ export type RoutePlanVerdict = RoutePlanProceed | RoutePlanReject;
 /**
  * Normalise whatever the session's router resolver handed back.
  *
- * A malformed or half-built resolution must leave the dispatch path exactly as it
- * is with the router OFF — that is the pre-router behaviour, so it is always a
- * safe answer — because the guards below walk `candidates` directly. (checkEffort
- * tolerates a junk resolution on its own, CQ5; this is about the list guard and
- * the window guard.) Shared with threads.ts so the shape check has ONE definition.
+ * A malformed or half-built resolution falls back to the shared ROUTER_OFF value
+ * because candidate-dependent planner paths below walk `candidates` directly.
+ * (checkEffort tolerates a junk resolution on its own, CQ5.) Shared with threads.ts
+ * so the shape check has ONE definition.
  */
 export function usableResolution(value: unknown): ModelRouterResolution {
 	const resolution = value as ModelRouterResolution | undefined;
@@ -719,8 +719,9 @@ function count(tokens: number): string {
  * failover. What remains is the one rule failover itself must obey (never the
  * model that just failed) and a NON-SUBSTITUTING window check that warns and
  * proceeds — substituting here would be the router vetoing failover by another
- * name. Gated on the router being ON so a router-off session keeps exactly its
- * pre-router failover behaviour.
+ * name. Gated on the router being ON, so a router-OFF failover gets no window
+ * warning at all: that is the pre-router behaviour of THIS branch, not of the
+ * dispatch path, where a router-OFF action's own `model` still moves a session.
  */
 function planFailoverSwitch(input: RoutePlanInput, resolution: ModelRouterResolution, target: string | undefined): RoutePlanVerdict {
 	const warnings: string[] = [];
@@ -810,10 +811,10 @@ export function planRoute(input: RoutePlanInput): RoutePlanVerdict {
 	/** Router OFF only: the thread's pre-router `model` pin, which OPENS a session and never switches one. */
 	let pin: string | undefined;
 	if (!resolution.on) {
-		// ROUTER OFF — this module is INVISIBLE (module header). The pre-router code
-		// passed ONE thing to the worker opener — the thread's `model` pin, undefined for
-		// most threads — and never touched a live session's model again. So that is all
-		// that happens here, for existing and new threads alike:
+		// ROUTER OFF — this planner seeds no base and applies no candidate-dependent
+		// guard. The pre-router code passed ONE thing to the worker opener — the thread's
+		// `model` pin, undefined for most threads — and never used that pin to move a
+		// live session. This branch preserves that open-only planning rule:
 		//
 		//  · nothing is SEEDED and nothing is PERSISTED: `baseModel`/`baseEffort` stay
 		//    undefined, so the caller writes no base onto the record. An earlier version
@@ -924,9 +925,9 @@ export function planRoute(input: RoutePlanInput): RoutePlanVerdict {
 	let model = explicit ?? baseModel ?? pin;
 	const openOnly = model !== undefined && model === pin && explicit === undefined;
 
-	// GUARD 1 — list membership. Router ON only; with the router off the `model`
-	// argument behaves exactly as it did before the router existed. Validated on the
-	// RESOLVED model, but only an EXPLICIT one can trip it: a new thread's base is a
+	// GUARD 1 — list membership. Router ON only; with the router off this guard does
+	// not inspect or reject the raw `model` argument. Validated on the RESOLVED model,
+	// but only an EXPLICIT one can trip it: a new thread's base is a
 	// listed candidate by construction (D48), and an existing thread's was re-seeded
 	// above if it was not — which is what keeps a dispatch that omitted `model` from
 	// ever landing here.
@@ -942,8 +943,8 @@ export function planRoute(input: RoutePlanInput): RoutePlanVerdict {
 	}
 
 	// GUARD 5 — CONTEXT WINDOW, and it runs BEFORE the effort guards on purpose: the
-	// model this action runs on must be settled before any level is judged against
-	// it, or the judgement is about a model that will be substituted away. Never a
+	// model the planner routes this action to must be settled before any level is judged
+	// against it, or the judgement is about a model that will be substituted away. Never a
 	// hard block, and router ON only: with the router off there is no candidate list
 	// to fall back to, and the pre-router behaviour is no check at all.
 	let substitutedFrom: string | undefined;
@@ -994,17 +995,17 @@ export function planRoute(input: RoutePlanInput): RoutePlanVerdict {
 		}
 	}
 
-	// ---- the EFFORT, for the model that will ACTUALLY run (THE ONE RULE, effort half)
+	// ---- the EFFORT, for the model the planner routes to (THE ONE RULE, effort half)
 	//
-	// The model is final now (guard 1 accepted it, guard 5 may have moved it), so the
-	// level can be settled against THAT model and nothing else:
+	// The routed model is final inside planRoute (guard 1 accepted it, guard 5 may have
+	// moved it), so the level can be settled against THAT model and nothing else:
 	//
 	//  · an EXPLICIT `effort` is judged against it, hard — the caller named a level and
 	//    is entitled to be told it does not exist there rather than silently clamped;
 	//  · a level INHERITED from the thread's base applies only while the base model is
-	//    the model that runs. The moment they differ — an explicit `model`, or a window
-	//    substitution — the inherited level is DROPPED and re-derived for the model that
-	//    runs (its lowest MEASURED level, or nothing when it has none). Carrying it over
+	//    the routed model. The moment they differ — an explicit `model`, or a window
+	//    substitution — the inherited level is DROPPED and re-derived for the routed
+	//    model (its lowest MEASURED level, or nothing when it has none). Carrying it over
 	//    was BG14: an action explicitly routed to another model inherited a budget
 	//    derived for the base, and was warned about — or, with allowUnmeasuredEffort
 	//    false, REJECTED — for a level nobody had asked for.

package/extension/state.ts

@@ -36,26 +36,25 @@ export interface ThreadRecord {
 	status: "idle" | "running";
 	/**
 	 * PRE-ROUTER pin: "provider/id" passed as `model` when the thread was created
-	 * WITH THE ROUTER OFF. It keeps exactly its pre-router meaning — the model a NEW
-	 * worker session for this thread OPENS on, never a reason to switch a live one —
-	 * so with the router off this feature stays invisible. With the router ON a
-	 * `model` argument routes ONE action and is deliberately NOT recorded here; see
-	 * `baseModel`.
+	 * WITH THE ROUTER OFF. It names what a NEW worker session opens on and never
+	 * instructs a live one to switch. With the router ON a `model` argument routes
+	 * ONE action and is deliberately NOT recorded here; see `baseModel`.
 	 */
 	model?: string;
 	/**
-	 * The thread's DEFAULT model, canonical "provider/id" — what a dispatch that
-	 * omits `model` runs on. Written ONLY while the router is on (with the router off
+	 * The thread's DEFAULT plan model, canonical "provider/id" — the target when a
+	 * dispatch omits `model`. Written ONLY while the router is on (with the router off
 	 * nothing is seeded or persisted), and always one of the effective candidates:
 	 * a base that is absent or has fallen off the list is re-seeded on the next
 	 * dispatch (route.ts's THE ONE RULE). DISTINCT from whatever a single action was
-	 * routed to: a routed action never becomes the thread's base. Absent = unknown.
+	 * routed to: a routed action never becomes the thread's base. A live failover may
+	 * temporarily override it without changing this record. Absent = unknown.
 	 */
 	baseModel?: string;
 	/**
 	 * The thread's DEFAULT effort level, derived for `baseModel` and valid only for
-	 * it: a dispatch whose model differs re-derives the level for the model that
-	 * actually runs. Absent = unknown ⇒ the worker session's own opening level.
+	 * it: a dispatch whose model differs re-derives the level for the model it
+	 * routes to. Absent = unknown ⇒ the worker session's own opening level.
 	 *
 	 * The type is a claim about what slate WROTE, not a guarantee about what it reads
 	 * back: this record is restored from an unversioned, hand-editable snapshot, so the
@@ -469,11 +468,13 @@ export interface ContextBudgetObject {
 /**
  * Action-level model router (D4/D53). `models` is the CLOSED list of models the
  * router may route an action to, in canonical "provider/id" form; empty or
- * absent means the router is OFF and dispatch behaves exactly as it did before
- * the router existed. `allowUnmeasuredEffort` (default TRUE) decides what the
- * dispatch path does with an effort level that is ladder-valid but has no
- * capability evidence — an evidence gap is advisory, not a prohibition.
- * Validated by sanitizeRouterConfig in model-router.ts.
+ * absent means the router is OFF, so no candidate list or router-owned base,
+ * window, billing or substitution mechanism applies. Per-action arguments and
+ * pre-existing failover remain outside that feature-off statement.
+ * `allowUnmeasuredEffort` (default TRUE) decides what the dispatch path does
+ * with an effort level that is ladder-valid but has no capability evidence —
+ * an evidence gap is advisory, not a prohibition. Validated by
+ * sanitizeRouterConfig in model-router.ts.
  */
 export interface RouterConfig {
 	models?: string[];

package/extension/threads.ts

@@ -15,11 +15,11 @@
  * this, `model` was accepted only when a thread was created and silently ignored
  * on every later dispatch. The rules the dispatch path implements:
  *
- *  - RESOLUTION: the effective model is the explicit argument, else the thread's
- *    base model. The effective effort is the explicit argument, else the thread's
- *    base effort WHEN THE BASE MODEL IS THE ONE THAT RUNS, else a level derived
- *    for the model that does — a level never travels between models (route.ts's
- *    THE ONE RULE, effort half). The GUARDS ALWAYS VALIDATE THE RESOLVED PAIR,
+ *  - RESOLUTION: the planner's model is the explicit argument, else the thread's
+ *    base model. Its effort is the explicit argument, else the thread's base effort
+ *    WHEN THE BASE MODEL IS THE ROUTE TARGET, else a level derived for that target —
+ *    a level never travels between planner targets (route.ts's THE ONE RULE, effort
+ *    half). The GUARDS ALWAYS VALIDATE THE RESOLVED PAIR,
  *    never only the explicit arguments — an omitted argument must not escape
  *    validation.
  *
@@ -36,27 +36,27 @@
  *    once, in route.ts's header: with the router ON a thread's base is ALWAYS a
  *    listed candidate.
  *
- *  - ROUTER OFF = PRE-ROUTER BEHAVIOUR, exactly, and INVISIBLY. No list guard, no
- *    window guard, no billing notice, no seeded or persisted base, and no
- *    consultation of the orchestrator's tracked model: a dispatch runs on the
- *    `model` ARGUMENT, else on the thread's creation-time PIN — which, exactly as
- *    before, is only the model a NEW worker session opens with and never a reason
- *    to switch a live one (`openOnly`) — else on the host's current model, which
- *    is what worker.ts did before. Two additions: an explicitly passed `effort` is
- *    validated against the target model's ladder (that argument did not exist
- *    before, and pi would otherwise silently CLAMP a level the model does not
- *    offer), and a level set by one action is put back to the session's opening
- *    level by the next, so it cannot leak between actions. The MODEL an explicit
- *    argument routes to is reverted the same way (BG22): both axes are per-ACTION,
- *    and the revert target is what the session opened on — except while a failover
- *    holds the session, which slate must not undo (BG16).
+ *  - ROUTER OFF MAKES ROUTER-OWNED MECHANISMS INERT. No list guard, window guard,
+ *    billing notice, seeded or persisted base, or consultation of the
+ *    orchestrator's tracked model: a model-less plan targets the thread's
+ *    creation-time PIN — which only opens a NEW worker session (`openOnly`) — and
+ *    nothing at all when there is no pin, so a NEW session opens on the host's
+ *    current model (worker.ts) and a reused one is reverted to the model it opened
+ *    on — outside cases M1, M3 and M7 of the doc named below (BG16, BG24).
+ *    The `model` and `effort` arguments still apply per action: an explicit
+ *    `effort` is validated against the plan target's ladder whenever that ladder is
+ *    readable, and a level set by one action is put back to the session's opening
+ *    level by the next. The MODEL an explicit argument routes to is reverted the same
+ *    way (BG22), outside those same cases; the failover hold predates the router, and
+ *    an OFF plan does not undo it. docs/model-routing.md's "Known cases where the
+ *    model or level differs" collects the ones known to bite, this file's included.
+ *    It does not claim to be exhaustive, and this code is the authority.
  *
- *    An earlier iteration seeded the base from the tracker here and persisted it,
- *    which was strictly worse than the pre-router code in the same file: it undid
- *    failovers on reused sessions, could strand a thread for good once its tracked
- *    model lost credentials, and stopped a restarted thread following the host's
- *    model. Equivalence is the requirement; the tracker survives only as the
- *    episode compressor's last-resort rung.
+ *    An earlier iteration seeded the base from the tracker here and persisted it.
+ *    That undid failovers on reused sessions, could strand a thread once its
+ *    tracked model lost credentials, and stopped a restarted thread following the
+ *    host's model. The tracker survives only as the episode compressor's
+ *    last-resort rung.
  *
  *  - VALIDATION HAPPENS TWICE. Early, in dispatch(), before any state mutation
  *    or session work, so a bad pick is a TOOL ERROR rather than a billed failed
@@ -266,13 +266,12 @@ export class ThreadManager {
 		// This session's MEMOIZED model-router resolution (model-router.ts's
 		// createModelRouterResolver), bound by value for the same reason as the
 		// resolver above: a manager orphaned by a session swap must keep answering
-		// with its own session's frozen candidate list. Defaults to the OFF
-		// resolution, which is byte-for-byte the pre-router dispatch path.
+		// with its own session's frozen candidate list. Defaults to the shared OFF
+		// resolution, which supplies no candidates or router-owned base.
 		private resolveRouter: () => ModelRouterResolution = () => ROUTER_OFF,
 		// The orchestrator's base model, EXCLUDING failover fallbacks (base-model.ts).
-		// Consulted only when the router is off, to seed a new thread's base model.
-		// undefined (the default) = no tracker ⇒ fall back to the pre-router
-		// behaviour, where the worker opens on the host session's current model.
+		// Consulted only for the episode compressor's last-resort model rung; route
+		// planning never seeds a worker-thread base from this tracker.
 		private baseModelTracker?: BaseModelTracker,
 	) {
 		this.semaphore = new Semaphore(config.maxConcurrent ?? 4); // default rationale: docs/design-principles.md §5 repo-local note
@@ -412,11 +411,11 @@ export class ThreadManager {
 	/**
 	 * This session's frozen router resolution, defensively.
 	 *
-	 * A THROWING resolver, or one that hands back a malformed object, must leave the
-	 * dispatch path exactly as it is with the router off: OFF is the pre-router
-	 * behaviour, so it is always a safe answer. The SHAPE check itself is route.ts's
-	 * usableResolution, so the planner and this module cannot disagree about what a
-	 * usable resolution is.
+	 * A THROWING resolver, or one that hands back a malformed object, falls back to
+	 * the shared OFF resolution. That answer supplies no candidates, so list, window,
+	 * billing and substitution paths cannot walk an unreadable shape. The SHAPE check
+	 * itself is route.ts's usableResolution, so the planner and this module cannot
+	 * disagree about what a usable resolution is.
 	 */
 	private routerResolution(): ModelRouterResolution {
 		try {
@@ -525,11 +524,12 @@ export class ThreadManager {
 	): RoutePlanInput {
 		const resolution = this.routerResolution();
 		// CQ17: the window guard is router-ON only, so with the router OFF pi's compaction
-		// settings are NOT READ and no predicate is built. "Router off = invisible" is
-		// about what this feature DOES, not only about what it decides: the read is a
+		// settings are NOT READ and no predicate is built. The router-OFF path must add no
+		// router-owned SIDE EFFECT, not merely no router-owned decision: the read is a
 		// lock-protected disk read, and performing it for a guard that cannot fire is the
-		// kind of side effect the invariant exists to forbid. (Memoized per manager, so
-		// this was never a cost question.) The router-ON path is untouched, including the
+		// kind of side effect that rule exists to forbid. (Memoized per manager, so this
+		// was never a cost question.) Per-action argument and effort paths are unaffected
+		// by it. The router-ON path is untouched, including the
 		// `enabled: true` forcing below, which is load-bearing.
 		const settings = resolution.on ? this.compactionSettings(ctx) : undefined;
 		return {
@@ -650,7 +650,7 @@ export class ThreadManager {
 			);
 		};
 		abortIfBlocked();
-		// WHICH MODEL this action runs on is decided by route.ts's pure `decideModelSwitch`
+		// WHICH MODEL this action starts on is decided by route.ts's pure `decideModelSwitch`
 		// (the plan's model, else the session's opening model as a REVERT, standing down
 		// while a failover holds it). Everything it needs is passed explicitly, so the
 		// decision — the part with the interesting cases — is checkable without a
@@ -1169,11 +1169,11 @@ export class ThreadManager {
 			workerEffortUnmeasured: effortIsAsPlanned,
 			workerEffortJudgedFor: plan?.effortJudgedFor,
 			configuredModel: this.config.episodeModel,
-			// The compressor's LAST-RESORT rung: the ORCHESTRATOR's base model, from the
-			// same tracker the router-off base resolution uses (failover fallbacks
-			// excluded, spec-validated). Without this the pin's bottom rung could never
-			// fire, and a project with no episodeModel and no usable Sonnet would drop
-			// straight to the uncompressed fallback.
+			// The compressor's LAST-RESORT rung: the ORCHESTRATOR's base model from the
+			// tracker (failover fallbacks excluded, spec-validated). Route planning no
+			// longer consumes this tracker. Without it the compressor pin's bottom rung
+			// could never fire, and a project with no episodeModel and no usable Sonnet
+			// would drop straight to the uncompressed fallback.
 			orchestratorBaseModel: this.trackedBaseModel(),
 			modelFailover: this.config.modelFailover,
 			signal: signal?.aborted ? undefined : signal,

package/extension/tools.ts

@@ -14,21 +14,21 @@ export function registerSlateTools(pi: ExtensionAPI, store: SlateStore, getManag
 		name: "thread",
 		label: "Thread",
 		description: [
-			"Dispatch ONE bounded action to a persistent worker thread and receive back an episode",
-			"(a compressed, structured record of what the thread did).",
-			"Omit `thread` to create a new thread (give it a short `name`); pass an existing thread id",
-			"to continue that thread — it retains the context of all its previous actions.",
-			"Use `context` to inject prior episodes (by id, from any thread) into the action.",
-			"Threads are serial; to parallelize, dispatch to DIFFERENT threads in one message.",
-			"`model` (\"provider/id\") and `effort` (pi thinking level) route THIS ACTION ONLY — new thread",
-			"or continuation alike; the next action reverts to the thread's defaults, which is also what",
-			"an omitted argument runs on.",
-			"`tools` applies only when creating a new thread.",
-			"Guarded: a level the model does not offer is a tool error, as is a model outside the routable",
-			"list where a project configures one; advisory notices (evidence gaps, cost cliffs, window",
-			"substitution) are prefixed to the episode as ⚠ lines.",
-			"An episode header of STATUS: FAILED means the action failed — read it and adapt.",
-			"Tasks that modify repository files require the track workflow's pre-implementation gates to have run first.",
+			"Dispatch ONE bounded action to a persistent worker thread; receive an episode",
+			"(a compressed, structured record of its work).",
+			"Omit `thread` and give a short `name` to create one; pass its id to continue with all prior-action context.",
+			"Use `context` to inject episodes by id from any thread.",
+			"Each thread is serial; use DIFFERENT threads in one message for parallel work.",
+			"`model` (\"provider/id\") and `effort` (pi thinking level) route THIS ACTION ONLY on new or continued threads.",
+			"With routing on, omission plans for the thread's base pair. With routing off, an omitted model",
+			"plans for its pre-router pin; no pin gives no target. Omitted effort resolves no level. The session",
+			"then returns to what it opened on. See docs/model-routing.md § Known cases where the model or level",
+			"differs for what can run instead.",
+			"`tools` applies only when creating a thread.",
+			"Slate rejects a level the model does not offer and, when configured, a model outside the routable list.",
+			"⚠ advisory notices before the episode report evidence gaps, cost cliffs, or window substitution.",
+			"STATUS: FAILED means the action failed — read the episode and adapt.",
+			"File-changing tasks require the track workflow's pre-implementation gates first.",
 		].join(" "),
 		promptSnippet: "Dispatch one bounded action to a persistent worker thread; returns a compressed episode",
 		promptGuidelines: [
@@ -43,14 +43,21 @@ export function registerSlateTools(pi: ExtensionAPI, store: SlateStore, getManag
 				Type.Array(Type.String(), { description: "Episode ids to inject as context (e.g. [\"t1.e2\"])" }),
 			),
 			model: Type.Optional(
-				Type.String({ description: "Worker model \"provider/id\" for THIS action; omit to use the thread's base model" }),
+				Type.String({
+					description:
+						"Worker model \"provider/id\" for THIS action. Omit it to plan for the thread's base model with " +
+						"routing on, or for its pre-router pin with routing off. With no pin the worker session returns to " +
+						"the model it opened on. Cases M1, M3 and M7 in docs/model-routing.md § Known cases where the model " +
+						"or level differs are when it does not.",
+				}),
 			),
 			effort: Type.Optional(
 				Type.String({
 					description:
-						"Thinking level for THIS action: off, minimal, low, medium, high, xhigh or max " +
-						"(only levels the target model offers); omit to let slate choose — the thread's " +
-						"default level, or one measured for the model that runs",
+						"Thinking level for THIS action: off, minimal, low, medium, high, xhigh or max. " +
+						"Slate refuses a level the routed model's known ladder lacks, outside case E2 in " +
+						"docs/model-routing.md. Omit it to plan for the thread's default or a measured level with routing " +
+						"on, or for the level the worker session opened on with routing off.",
 				}),
 			),
 			tools: Type.Optional(Type.Array(Type.String(), { description: "Worker tool allowlist (new threads only)" })),
@@ -131,12 +138,11 @@ export function registerSlateTools(pi: ExtensionAPI, store: SlateStore, getManag
 		name: "threads",
 		label: "Threads",
 		description:
-			"List all worker threads: id, name, status, episodes so far, last activity, and models — " +
-			"base=<the thread's default model>@<effort>? (what a dispatch that omits `model` runs on; " +
-			"the trailing ? marks the LEVEL as provisional — it is the stored default, re-checked against " +
-			"the model's current capability data on every dispatch and silently re-derived if it no longer " +
-			"holds) and last=<the model its last action actually ran on>@<effort>, which is fact. " +
-			"Use this to decide whether to continue an existing thread or create a new one.",
+			"List worker threads, their status, episodes, activity, and models. " +
+			"base=<model>@<effort>? is the nominal plan target when `model` is omitted. " +
+			"The ? marks effort as provisional because Slate re-checks and may re-derive it. " +
+			"last=<model>@<effort> records the last action. live=<model> (failover) shows a held fallback " +
+			"that currently overrides the nominal base.",
 		promptSnippet: "List worker threads and their episodes",
 		parameters: Type.Object({}),
 		async execute() {
@@ -147,15 +153,16 @@ export function registerSlateTools(pi: ExtensionAPI, store: SlateStore, getManag
 			const lines = threads.map((t) => {
 				const episodes = t.episodeIds.length > 0 ? t.episodeIds.join(", ") : "(none)";
 				const marks: string[] = [];
-				// The thread's DEFAULT model — what a dispatch that omits `model` runs on
-				// (?? t.model: a thread created before per-action routing existed carries
-				// only the pre-router pin). Absent for a thread whose base could not be
-				// resolved: it then runs on the host's current model, as it always did.
+				// The thread's NOMINAL model — the planner target for a dispatch that omits
+				// `model` (?? t.model: an older thread carries only the pre-router pin).
+				// Absent means the plan has no model: a NEW session then opens on the host
+				// model and a reused one is reverted to the model it opened on. A separate
+				// `live=` marker below overrides this display while failover holds the session.
 				const base = t.baseModel ?? t.model;
-				// CQ19: the MODEL half is authoritative (an unroutable base is re-seeded, so this
-				// is what a dispatch that omits `model` will use), but the LEVEL half is only a
-				// STORED default: every dispatch re-checks it against the model's current
-				// capability data and silently derives a fresh one if the profile table has moved
+				// CQ19: the MODEL half is authoritative as nominal planning state (an unroutable
+				// base is re-seeded, so this is what an omitted `model` resolves to), but the
+				// LEVEL half is only a STORED default: every dispatch re-checks it against the
+				// model's current capability data and silently derives a fresh one if the table has moved
 				// under it (BG23). Reporting it bare would present a value that may not survive
 				// contact with the next action as fact — the `?` says so, and the tool description
 				// says what it means. `last=` below carries no such caveat: that one is what ran.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ytdb-slate",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Slate: thread-weaving orchestration for the pi coding agent — bounded worker actions, compressed episodes, mandatory research/design/adversarial/track review workflow, configurable model failover, and orchestrator context-budget handoff.",
   "license": "Apache-2.0",
   "repository": {