ytdb-slate 0.6.1 → 0.7.0

package/README.md

@@ -1,6 +1,6 @@
 # ytdb-slate
 
-[![CI status](https://github.com/JetBrains/ytdb-slate/actions/workflows/tier-1.yml/badge.svg?branch=main)](https://github.com/JetBrains/ytdb-slate/actions/workflows/tier-1.yml)
+[![CI status](https://github.com/JetBrains/ytdb-slate/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/JetBrains/ytdb-slate/actions/workflows/ci.yml)
 
 Slate is a thread-weaving orchestration extension for the [pi coding agent](https://pi.dev).
 
@@ -57,6 +57,14 @@ Slate can ride through model API outages. The opt-in `modelFailover` map in `.pi
 
 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.
 
+Router startup warnings have two classes. One class is a configuration fault. It reports project configuration that Slate ignored or dropped. A configuration fault also covers problems the user can stop by adding a model, credential, or failover entry.
+
+The addition must go into their project configuration or pi credentials. Removing the model named by a warning does not meet this second test. Slate always shows configuration faults.
+
+The other class is a model data note. It reports shipped research data that project configuration cannot correct. Slate hides those notes by default.
+
+With this repository's six-model list and pi's stock registry, Slate hides eleven notes. Slate shows one discoverability line instead. A local registry override can change that count. The line names the hidden warning count and the `router.showWarnings` setting. A hidden note can still affect which model runs an action.
+
 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.
 
 ## Optional writing guidance
@@ -105,6 +113,7 @@ Optional config file: `slate.json` in the project's pi config dir (`.pi/slate.js
 | `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 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. |
+| `router.showWarnings` | boolean | `false` | Reveal model data notes about Slate's shipped routing research. Configuration faults are never hidden. See [`docs/model-routing.md`](docs/model-routing.md). |
 
 Example `.pi/slate.json` (the `docs/agents/...` paths are placeholders — point them at markdown files that actually exist in **your** project):
 
@@ -168,7 +177,7 @@ In orchestrator mode, Slate appends a short **doctrine** (a block of numbered ru
 - `docs/model-failover.md` — the opt-in `modelFailover` map (**reference documentation** — unlike the entries above it is not workflow doctrine and is not cited by the doctrine)
 - `docs/context-budget.md` — the orchestrator `contextBudget`: defaults, per-model overrides, the window clamp, and the pricing rationale (also **reference documentation**, not cited by the doctrine)
 - `docs/writing-guidance.md` — the optional writing convention, `writing.check` behavior, status line, and checker CLI
-- `docs/model-routing.md` — action-level model routing: the two `router` keys, how a model becomes routable, how an omitted effort level resolves, the dispatch guards, and the warnings a first routed session emits. Unlike the two entries above it **is** cited by the doctrine, by absolute path, but only while the routing rule renders — it is the extra embedded path that appears with the rule, the fourth normally and the fifth when `workflow.draftPRs` is also on, which the size arithmetic in `docs/context-budget.md` accounts for. The routable model list itself is never read from this file: the rule renders it live from the session's own resolution, because that set depends on your registry and credentials.
+- `docs/model-routing.md` — the action-level model routing reference. It covers the three `router` keys, model eligibility, omitted effort, and dispatch guards. It also covers first-session warnings. The doctrine cites this absolute path only while the routing rule renders. This path is fourth normally and fifth when `workflow.draftPRs` is on. The rule renders the live list because it depends on the session registry and credentials.
 
 Project-specific additions layer on top — they extend, not replace, the shipped doctrine — via two distinct mechanisms:
 

package/docs/model-routing.md

@@ -199,7 +199,7 @@ opened on. M7 and E6 are known cases in which it does not.
 
 `router` lives in `.pi/slate.json` and, like the rest of that file,
 is honored **only in trusted projects** — an untrusted project loads
-no project config, so the router stays off. There are exactly two
+no project config, so the router stays off. There are exactly three
 keys:
 
 ```json
@@ -213,7 +213,8 @@ keys:
       "anthropic/claude-opus-5",
       "anthropic/claude-fable-5"
     ],
-    "allowUnmeasuredEffort": true
+    "allowUnmeasuredEffort": true,
+    "showWarnings": false
   }
 }
 ```
@@ -222,6 +223,7 @@ keys:
 | --- | --- | --- | --- |
 | `models` | array of `"provider/id"` strings | `[]` | the closed candidate list; empty or absent = router OFF |
 | `allowUnmeasuredEffort` | boolean | `true` | `false` turns an evidence gap from a warning into a refusal |
+| `showWarnings` | boolean | `false` | `true` shows model data notes in addition to the always-visible configuration faults |
 
 Validation, all of it at session start so a broken list surfaces
 before a dispatch is refused by it:
@@ -237,6 +239,9 @@ before a dispatch is refused by it:
   entries in the same list still apply.
 - A non-boolean `allowUnmeasuredEffort` is warned about and treated
   as `true`.
+- A non-boolean `showWarnings` is warned about as a configuration
+  fault and treated as `false`. The fault remains visible despite
+  that fallback.
 
 The config is read once, at session start. Editing `slate.json`
 mid-session takes effect only in a new pi session.
@@ -249,24 +254,54 @@ the credentials pi actually has configured. Resolution happens once
 per session, lazily at the first consultation, and the answer is
 then frozen for that session.
 
-| what happens | outcome | warning |
-| --- | --- | --- |
-| entry is not a canonical `provider/id` | dropped | names the entry and the defect |
-| no profile in Slate's model profiles | dropped | "has no benchmark data … excluding it from routing" |
-| two entries resolve to the same profile (an alias or a case variant) | first kept, second dropped | names both spellings and the profile |
-| the same spec listed twice | first kept | none (silent) |
-| pi's model registry does not know it | dropped | "routing there could only produce billed failures" |
-| pi has no usable credentials configured for it | dropped | same wording, credentials variant |
-| every entry dropped | router turns OFF | one summary line naming the count |
-| no usable input price for today's date | kept, ordered last | "its cost cannot be compared" |
-| no usable effort ladder in the profile | kept | "every explicit effort level for it will read as off-ladder" |
-| profile's context window differs from the registry's | kept (registry value used) | see [Expected first-session warnings](#expected-first-session-warnings) |
-| profile names unknown routing-critical fields | kept | "routing decisions for it are provisional", naming the fields |
-| no `modelFailover` entry for a candidate | kept | one aggregate line naming every uncovered candidate |
-
-Every warning is emitted at most once per session and reaches the
-same channel as the other config warnings: a UI notification when a
-UI is attached, the console otherwise.
+The class test has two independent conditions. A warning is a
+**configuration fault** when EITHER condition holds:
+
+1. Slate ignored or dropped part of the user's configuration.
+2. The user can stop the warning by ADDING something to their own
+   project config or pi credentials, such as a model, credential or
+   failover entry. This differs from only removing the model named
+   by the warning.
+
+Every other warning is a **model data note**. The single-part test
+that asks only whether a user can stop a warning does not partition
+the classes: removing a dropped `router.models` entry can silence its
+warning, but removal is not the ADD remedy in condition 2. Condition
+1 catches every silently ignored or dropped config value first.
+
+| what happens | outcome | warning fragment | class |
+| --- | --- | --- | --- |
+| entry is not a canonical `provider/id` | dropped | "It is not a canonical \"provider/id\" model spec. Reason:" | configuration fault |
+| no profile in Slate's model profile table | dropped | "has no entry in slate's model profile table" | configuration fault |
+| two entries resolve to the same profile (an alias or a case variant) | first kept, second dropped | "name the same profiled model" | configuration fault |
+| the same spec is listed twice | first kept | none (silent) | — |
+| pi's model registry does not know it | dropped | "is not in pi's model registry. Slate drops it from routing." | configuration fault |
+| pi has no usable credentials configured for it | dropped | "has no usable credentials configured in pi. Slate drops it from routing." | configuration fault |
+| every entry is dropped | router turns OFF | "survived validation. The warnings above name each dropped entry" | configuration fault |
+| no usable input price exists for today's date | kept, ordered last | "Slate cannot compare its cost with the other models." | model data note |
+| no usable effort ladder exists in the profile | kept | "Such a level passes through to pi, which clamps it" | model data note |
+| profile context window differs from the registry window | kept, registry value used | "differs between two sources" | model data note |
+| the first profile names unknown routing-critical fields | kept | "picks models from a research table shipped inside slate" | model data note |
+| a profile names unknown routing-critical fields | kept | "model fact that slate could not trace to a source" or "model facts that slate could not trace to a source" | model data note |
+| a reportable profile/registry context-window divergence exists, the registry figure is not the profile's recorded known-divergence figure, and the registry figure equals the model's own long-context billing threshold | kept | "context window equal to the model's own long-context billing threshold" | model data note |
+| no `modelFailover` entry exists for a candidate | kept | "routable models have no modelFailover entry" | configuration fault |
+| every configured candidate is marked non-preferred | cheapest candidate becomes the base | "profiles mark every configured model as one it must never pick by itself" | configuration fault |
+| resolution throws | router turns OFF | "routing is disabled. The router could not resolve its model list" | configuration fault |
+
+Every warning is emitted at most once per session. The complete
+resolution retains every warning regardless of display filtering.
+With `router.showWarnings: true`, every warning reaches the same
+channel as the other config warnings: a UI notification when a UI is
+attached, the console otherwise. With the default `false`, every
+configuration fault still reaches that channel and model data notes
+do not.
+
+When at least one note is hidden, Slate emits one discoverability
+line after resolution. It gives the hidden warning count, names
+`router.showWarnings`, and says that a hidden warning can affect
+which model runs an action. The count is warnings, not physical
+display lines: one warning can wrap across several lines. No
+discoverability line appears when nothing was hidden.
 
 Half a list is still a routing policy, so partial drops leave the
 router ON. Nothing surviving is not a policy: the router turns OFF
@@ -463,60 +498,78 @@ model's ladder is unreadable.
 
 ## Expected first-session warnings
 
-**A batch of warnings on the first routed session is expected UX,
-not a bug.** With a six-model list on a stock pi install, resolution
-emits eleven lines, broken down below. They are not repeated: every
-warning fires at most once per session, and the resolution is frozen
-after the first consultation.
-
-In orchestrator mode that first consultation is the DOCTRINE BUILD,
+The stock count below is a render over this repository's
+`.pi/slate.json`, the shipped profile table, and the provider data
+inside the pinned pi 0.83.0 package. It does not read the live model
+registry. The packaged OpenAI data at
+`@earendil-works/pi-coding-agent/node_modules/@earendil-works/pi-ai/dist/providers/data/openai.json`
+reports a **272,000-token** context window for
+`openai/gpt-5.6-luna`, `openai/gpt-5.6-terra` and
+`openai/gpt-5.6-sol`. The packaged Anthropic data reports 1,000,000
+for each configured Anthropic model. The render treated all six as
+authenticated, matching this repository's configured-auth state.
+
+The shipped profiles record 1,050,000 tokens for those three OpenAI
+models. Each stock registry value therefore produces a context-window
+divergence note. The same 272,000-token value equals each model's
+long-context billing threshold, so one aggregate billing-pattern note
+also fires.
+
+Resolution emits **11 warnings: 0 configuration faults and 11 model
+data notes**. The default `router.showWarnings: false` therefore
+shows **0 of those warnings** and one discoverability line. That line
+begins `slate: there are 11 hidden warnings in the model router.`
+Enabling the option shows all 11 warnings and no discoverability
+line. Each warning fires at most once per session, and the resolution
+is frozen after the first consultation.
+
+| warnings | class | condition keys | why | shown by default |
+| --- | --- | --- | --- | --- |
+| 1 | model data note | `w3-explainer` | explains the shipped research table before the first unknown-data warning | 0 |
+| 6 | model data note | one `w3:string:<JSON spec>` for each configured model | each profile names model facts with no traced source, or conflicting figures with no adjudication | 0 |
+| 3 | model data note | one `w1:string:<JSON spec>` for each configured OpenAI model | each stock registry window differs from its profile window | 0 |
+| 1 | model data note | `w1-billing-pattern` | aggregates the three registry windows that equal their models' billing thresholds | 0 |
+| **11** | **all model data notes** | — | stock measured total | **0 warnings; 1 discoverability line** |
+
+The stock emission order is:
+
+1. `w1:string:"openai/gpt-5.6-luna"`
+2. `w3-explainer`
+3. `w3:string:"openai/gpt-5.6-luna"`
+4. `w1:string:"openai/gpt-5.6-terra"`
+5. `w3:string:"openai/gpt-5.6-terra"`
+6. `w1:string:"openai/gpt-5.6-sol"`
+7. `w3:string:"openai/gpt-5.6-sol"`
+8. `w3:string:"anthropic/claude-sonnet-5"`
+9. `w3:string:"anthropic/claude-opus-5"`
+10. `w3:string:"anthropic/claude-fable-5"`
+11. `w1-billing-pattern`
+
+This count depends on pi's registry data and any local registry
+override. This machine's `~/.pi/agent/models.json` overrides the
+three OpenAI windows to 1,050,000 tokens. A live render here therefore
+suppresses the three divergence notes and the billing-pattern note,
+leaving **7 model data notes**. That seven-note result describes this
+machine, not a stock install.
+
+The configured failover map covers all six candidates, so the
+failover-coverage condition does not fire in either render. Preferred
+candidates remain in the list, so the non-preferred-base condition
+does not fire either.
+
+In orchestrator mode the first consultation is the DOCTRINE BUILD,
 not a dispatch: the orchestrator's system prompt carries the
-routable model table, and it is assembled when your first message
-starts a turn. So the whole batch can arrive in a session where you
-typed nothing but "hi" and dispatched nothing at all — that is the
-router reading its inputs for the session, not a dispatch
-misfiring. (Outside orchestrator mode no doctrine is built, so the
-first dispatch triggers it instead. The config-shape warnings above
-land earlier still, at session start.)
-
-The breakdown:
-
-| lines | class | why |
-| --- | --- | --- |
-| 6 | unknown routing data | each of the six profiles names routing-critical fields with no traced value, or with two published values and no adjudication, so routing decisions for them are provisional |
-| 3 | context-window divergence | the three `openai/gpt-5.6-*` models — see below |
-| 1 | billing-pattern note | one aggregate line naming those three models |
-| 1 | failover coverage | one aggregate line, when `modelFailover` covers none of them |
-
-The window divergence is real, and both sides are stated without
-adjudication. On a stock install pi's registry reports **272,000**
-tokens for `openai/gpt-5.6-luna`, `-terra` and `-sol`, while their
-profiles record **1,050,000** (with the profile's asOf date in the
-same line). Routing uses the REGISTRY figure — that is a fact about
-this code, and it is stated as such — but which figure is factually
-correct is not established by the router: it sees two numbers and no
-provenance for either.
-
-The registry's 272,000 is also exactly those models' long-context
-BILLING threshold, so one further line says so once, naming all
-three: a window equal to its own threshold would leave the
-long-context price tier unreachable, which is the
-billing-row-restated-as-a-capacity pattern. That is suggestive, not
-proof, which is why it is a pointer and not a verdict.
-
-**Why Slate does not "fix" this by changing its own number.** The
-research pass that produced this table explicitly withdrew 272,000
-as a capacity figure: in the source it appears only inside a pricing
-row, as a boundary on input tokens. Restating it as a window is the
-fabrication that pass caught and corrected. Editing the profile to
-match the registry would silence the warning by asserting something
-the evidence does not support, and would suppress a divergence that
-is currently true. The honest options are the two you already have:
-leave it (routing uses the registry number, which is the
-conservative one) or raise the registry window deliberately in pi's
-custom-models file, after which the warning stops on its own —
-`context-budget.md` documents that opt-in and the billing
-consequences of running above the threshold.
+routable model table, and it is assembled when the first message
+starts a turn. Outside orchestrator mode the first dispatch triggers
+resolution instead. Config-shape warnings land earlier, at session
+start.
+
+A hidden warning can still alter which model runs an action. Context-
+window divergence is the concrete case, and the stock registry emits
+three such hidden notes for this list. Routing uses the registry
+window, and that value drives the context-window substitution guard.
+`router.showWarnings` changes display only; it does not change the
+resolution or the guard input.
 
 ## What the router does NOT enforce
 

package/extension/index.ts

@@ -38,11 +38,14 @@
  *     "preserveGlobalModelDefault": true,
  *     "doctrineExtraPath": "docs/project-doctrine.md",
  *     "reviewPerspectivesPath": "docs/review-perspectives.md",
- *     "router": { "models": ["provider/id", ...], "allowUnmeasuredEffort": true },
+ *     "router": { "models": ["provider/id", ...], "allowUnmeasuredEffort": true,
+ *                 "showWarnings": false },
  *     "writing": { "check": false } }
  * router.models is the closed list of models an action may be routed to (empty
  * or absent = router off, the default); allowUnmeasuredEffort (default true)
- * governs effort levels with no capability evidence — see model-router.ts.
+ * governs effort levels with no capability evidence; showWarnings (default
+ * false) also shows the router's model data notes, the warnings about shipped
+ * research data that no project config can fix — see model-router.ts.
  * contextBudget also takes { "tokens": N, "overrides": [{ "match": "regex",
  * "tokens": N }] } (match is anchored against "provider/id"); absent, the
  * built-in defaults apply (256k tokens; 400k for anthropic/*). The DEPRECATED
@@ -58,7 +61,13 @@ import { createBaseModelTracker, readLiveEffort, type BaseModelTracker } from ".
 import { registerOrchestratorFailover, sanitizeModelFailover } from "./failover.ts";
 import { registerSlateHandoff, sanitizeContextBudget } from "./handoff.ts";
 import { registerSlateMode } from "./mode.ts";
-import { createModelRouterResolver, ROUTER_OFF, sanitizeRouterConfig, type ModelRouterResolution } from "./model-router.ts";
+import {
+	createModelRouterResolver,
+	ROUTER_OFF,
+	sanitizeRouterConfig,
+	type ModelRouterResolution,
+	type RouterWarningClass,
+} from "./model-router.ts";
 import { sanitizeEpisodeModel, SlateStore, type SlateConfig } from "./state.ts";
 import { ThreadManager } from "./threads.ts";
 import { registerSlateTools } from "./tools.ts";
@@ -146,7 +155,26 @@ export default function (pi: ExtensionAPI) {
 		config.workerExtensions = sanitizeWorkerExtensions(config.workerExtensions, warn);
 		// router likewise: a malformed model list must surface at session start, not
 		// when a dispatch is refused for naming a model the list silently dropped.
-		config.router = sanitizeRouterConfig(config.router, warn);
+		// The router's own warn sink. It reads the CLASS the router tags each warning
+		// with (model-router.ts) and hides a MODEL DATA NOTE — a fact about slate's
+		// shipped research table that no project config and no credential can change —
+		// unless the project asked for those with router.showWarnings. A CONFIGURATION
+		// FAULT always reaches the user, and so does a warning from a sink that omits
+		// the class argument. Nothing is dropped from the resolution itself: the router
+		// still emits every warning and still collects every one on its result.
+		let showRouterWarnings = false;
+		let hiddenRouterWarnings = 0;
+		const routerWarn = (msg: string, warningClass?: RouterWarningClass) => {
+			if (warningClass === "model-data-note" && !showRouterWarnings) {
+				hiddenRouterWarnings += 1;
+				return;
+			}
+			warn(msg);
+		};
+		config.router = sanitizeRouterConfig(config.router, routerWarn);
+		// Read AFTER sanitization, so an invalid value has already fallen back to false
+		// and reported itself as a configuration fault.
+		showRouterWarnings = config.router.showWarnings === true;
 		config.writing = sanitizeWritingConfig(config.writing, warn);
 		// episodeModel too (RG20): an unusable value falls back to the built-in
 		// compressor, and until this ran it did so without saying anything at all.
@@ -169,14 +197,42 @@ export default function (pi: ExtensionAPI) {
 		// visible — and every later consultation gets that same frozen answer (CQ7).
 		// `failover` is passed so the resolver can report candidates with no failover
 		// coverage; both keys are read through the closure, not captured by value.
-		resolveModelRouterResolution = createModelRouterResolver(
+		const memoizedRouterResolution = createModelRouterResolver(
 			() => ({
 				registry: ctx.modelRegistry,
 				models: config.router?.models ?? [],
 				failover: config.modelFailover ?? {},
 			}),
-			warn,
+			routerWarn,
 		);
+		// The discoverability line, at most once per session. It is flushed AFTER the
+		// memoized resolution returns on every return path. The current resolver emits
+		// no model-data note on its all-dropped path, but the flush stays there because
+		// this wrapper must cover that return path if the resolver gains one later. The
+		// memo means a later consultation re-emits nothing and cannot count a warning
+		// twice, and `noticeFlushed` covers the FIRST consultation
+		// producing no hidden note at all. It counts WARNINGS, not rendered lines: one
+		// warning can wrap across several of those.
+		let noticeFlushed = false;
+		resolveModelRouterResolution = () => {
+			const resolution = memoizedRouterResolution();
+			if (!noticeFlushed) {
+				noticeFlushed = true;
+				if (hiddenRouterWarnings > 0) {
+					const count = hiddenRouterWarnings;
+					const plural = count === 1 ? "is 1 hidden warning" : `are ${count} hidden warnings`;
+					try {
+						warn(
+							`slate: there ${plural} in the model router. Set "router.showWarnings" to true in ` +
+								`${CONFIG_DIR_NAME}/slate.json to read them. A hidden warning can affect which model runs an action.`,
+						);
+					} catch {
+						/* BG3: a throwing sink costs the notice, never the resolution */
+					}
+				}
+			}
+			return resolution;
+		};
 		// Fresh tracker per session, seeded from the session's OWN resolved model —
 		// undefined is legitimate (no model, or no auth for one) and stays silent.
 		// Same warn channel as the sanitizers above. A handoff adoption re-seeds it

package/extension/model-router.ts

@@ -80,9 +80,18 @@
  *    path, Track 02, gated by `router.allowUnmeasuredEffort`, default true) that
  *    decides what to do with that. This module never refuses anything.
  *
+ *  - EVERY WARNING CARRIES A CLASS (see RouterWarningClass): a CONFIGURATION
+ *    FAULT the user can act on, or a MODEL DATA NOTE about shipped research the
+ *    user cannot change. This module never hides anything: it tags each warning
+ *    and sends every one of them to the sink it was handed. The extension entry
+ *    point (index.ts) is what filters notes when `router.showWarnings` is off,
+ *    and what reports how many it hid.
+ *
  *  - EVERY WARNING AT MOST ONCE PER SESSION (D58), sanitized through the shared
  *    sanitizeForNotify before display, exactly like the other sanitizers: config
  *    values and profile fields are user-editable text that reaches ctx.ui.notify.
+ *    Each assembled message is capped as a WHOLE (ROUTER_MESSAGE_MAX), so the
+ *    control-byte guard covers the finished string and not only its parts.
  *    Warnings are BOTH pushed to the sink and collected on the result, and the
  *    sink is called defensively — a throwing UI must not cost a resolution
  *    (BG3). Per-candidate notices that would otherwise scale with the list
@@ -138,6 +147,109 @@ export const SHIPPED_PROFILE_SOURCE: RouterProfileSource = {
 	ladderFor: shippedLadderFor,
 };
 
+/**
+ * What KIND of problem a router warning reports. There are exactly two.
+ *
+ * THE TEST, and it has two parts. A warning is a `configuration-fault` when
+ * EITHER part holds:
+ *   (a) slate ignored or dropped part of the user's configuration, or
+ *   (b) the user can stop the warning by ADDING something to their own project
+ *       config or pi credentials, such as a model, credential or failover entry.
+ *       This differs from only removing the model named by the warning.
+ * Otherwise it is a `model-data-note`.
+ *
+ * BOTH parts are load-bearing. The single-part "can the user stop it" question
+ * does not partition the classes: removing a dropped `router.models` entry can
+ * silence its warning, but removal is not the ADD remedy in part (b). Part (a)
+ * catches every silently ignored or dropped config value first.
+ *
+ * A `model-data-note` reports the shipped research table itself: a figure that
+ * has no traced source, two sources that disagree, a price row that does not
+ * cover today. No project config and no credential closes that gap, so these are
+ * hidden unless `router.showWarnings` is true.
+ */
+export type RouterWarningClass = "configuration-fault" | "model-data-note";
+
+/**
+ * The warn sink, widened to carry the class alongside the message.
+ *
+ * A one-parameter `(message: string) => void` stays assignable to this type, so
+ * every existing caller keeps compiling AND keeps receiving every warning. Only
+ * a sink that WANTS to filter reads the second argument.
+ */
+export type RouterWarnSink = (message: string, warningClass: RouterWarningClass) => void;
+
+/**
+ * Per-field cap for PROFILE-SOURCED text (the unknown-field entries and the
+ * non-preferred reason). BOTH bounds matter:
+ *  - the longest entry in the shipped table measures 177 characters today (the
+ *    design text quoted 167, measured before the last profile refresh), so 180
+ *    keeps every real entry whole instead of cutting it mid-word;
+ *  - the hostile fixture in verification/resolver-checks.mjs asserts that no
+ *    warning carries a 200-character run, so the cap must stay BELOW 200.
+ * That leaves a narrow band, and 180 sits in it. The 80-character cap this
+ * replaces truncated most real entries.
+ */
+const PROFILE_FIELD_MAX = 180;
+
+/**
+ * Cap for one WHOLE assembled warning. A profile may carry any number of
+ * fields, so a per-field cap alone does not bound the message. 799 is chosen
+ * against the same hostile check: sanitizeForNotify appends an ellipsis, so the
+ * displayed string stays at or below the 800 characters that check allows, and
+ * the longest real message stays whole.
+ */
+const ROUTER_MESSAGE_MAX = 799;
+
+/**
+ * Separator between field entries: U+00B7 MIDDLE DOT.
+ *
+ * A newline is a control byte, and the hostile check bans one in any warning.
+ * U+00B7 was verified to survive sanitizeForNotify unchanged, and the
+ * confusable annotation (describeConfusables) never sees it, because that note
+ * is applied to a model SPEC and never to an assembled message.
+ */
+const FIELD_SEPARATOR = " · ";
+
+/**
+ * Display form of PROFILE-SOURCED text.
+ *
+ * The shipped table carries bracketed source tags ([G1e], [RI36], [arb]) that
+ * name unpublished research artifacts. They mean nothing to a reader of a
+ * warning, so they are removed here, the whitespace the removal leaves behind is
+ * collapsed, and a separator left dangling at the end is trimmed.
+ *
+ * USE THIS ONLY FOR PROFILE TEXT. An echoed USER value must keep its brackets:
+ * a user who wrote a nested array into `router.models` has to see those brackets
+ * to recognise the value the warning is talking about.
+ */
+function profileText(text: string, max = PROFILE_FIELD_MAX): string {
+	// Bound BEFORE scanning for tags. This keeps an unclosed bracket run from
+	// consuming session-start time, and the cap remains below the hostile 200-char
+	// fixture while clearing every real shipped entry.
+	const wasTruncated = text.length > max;
+	const bounded = text.slice(0, max);
+	const collapsed = bounded
+		// A citation can act as the subject after punctuation. Restore a neutral
+		// subject before removing it: "; [G3] gives" becomes "; the source gives".
+		.replace(/([;:,.])\s*\[[^\]]*\]\s+(?=[A-Za-z])/g, "$1 the source ")
+		.replace(/\[[^\]]*\]/g, "") // the source tags themselves
+		.replace(/\u00b7/g, " ") // profile text cannot forge the field-list separator
+		.replace(/\s+/g, " ") // the hole each removal leaves
+		.replace(/,\s*\)/g, ")") // "(vendor, [G3])" would otherwise read "(vendor, )"
+		.replace(/\(\s*\)/g, "") // a parenthesis that held nothing but a tag
+		.replace(/\s+([,;:.)])/g, "$1") // "1736 , unadjudicated" would otherwise keep the gap
+		.replace(/\s+/g, " ")
+		.replace(/[\s,;:—–-]+$/, "") // a separator the last removal left dangling
+		.trim();
+	if (!wasTruncated) return sanitizeForNotify(collapsed, max);
+	// Preserve an explicit truncation mark even when slicing made the cleaned text
+	// exactly max characters. Remove the sanitizer's own mark before adding one,
+	// so the visible result has one mark and remains within the same cap.
+	const cleaned = sanitizeForNotify(collapsed, max - 1);
+	return `${cleaned.endsWith("…") ? cleaned.slice(0, -1) : cleaned}…`;
+}
+
 /** One routable model: what survived validation, plus everything a caller needs to explain it. */
 export interface RouterCandidate {
 	spec: string; // canonical "provider/id"
@@ -356,7 +468,7 @@ export function effectivePriceRow(profile: ModelProfile, today: string): PriceRo
 }
 
 /** The known `router` keys — anything else is a typo worth surfacing (CQ1). */
-const ROUTER_KEYS = ["models", "allowUnmeasuredEffort"];
+const ROUTER_KEYS = ["models", "allowUnmeasuredEffort", "showWarnings"];
 
 /**
  * Validate the raw `router` config value (D4/D53). undefined → the defaults
@@ -366,33 +478,56 @@ const ROUTER_KEYS = ["models", "allowUnmeasuredEffort"];
  * and an unknown key is reported the way sanitizeContextBudget reports one
  * (CQ1 — a typo'd `"model"` must not look like an empty list).
  * `allowUnmeasuredEffort` defaults to TRUE — an evidence gap is advisory.
+ * `showWarnings` defaults to FALSE — model data notes are hidden until asked for.
+ *
+ * EVERY warning here is a configuration fault by the class test: each one names
+ * a value slate read from the project config and then ignored.
  */
-export function sanitizeRouterConfig(raw: unknown, warn: (msg: string) => void): Required<RouterConfig> {
-	const defaults: Required<RouterConfig> = { models: [], allowUnmeasuredEffort: true };
+export function sanitizeRouterConfig(raw: unknown, warn: RouterWarnSink): Required<RouterConfig> {
+	const defaults: Required<RouterConfig> = { models: [], allowUnmeasuredEffort: true, showWarnings: false };
+	const fault = (message: string) => warn(sanitizeForNotify(message, ROUTER_MESSAGE_MAX), "configuration-fault");
 	if (raw === undefined) return defaults;
 	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
-		warn('slate: ignoring router — expected an object like { "models": ["provider/id"], "allowUnmeasuredEffort": true }');
+		fault('slate: ignoring the router config. It must be an object like { "models": ["provider/id"], "allowUnmeasuredEffort": true }.');
 		return defaults;
 	}
-	const value = raw as { models?: unknown; allowUnmeasuredEffort?: unknown };
+	const value = raw as { models?: unknown; allowUnmeasuredEffort?: unknown; showWarnings?: unknown };
 
-	const unknownKeys = Object.keys(value).filter((k) => !ROUTER_KEYS.includes(k));
+	let unknownKeys: string[];
+	try {
+		unknownKeys = Object.keys(value).filter((k) => !ROUTER_KEYS.includes(k));
+	} catch {
+		fault("slate: ignoring the router config because its keys could not be read. Slate uses the router defaults.");
+		return defaults;
+	}
 	if (unknownKeys.length > 0) {
-		warn(
-			`slate: ignoring unknown router key(s): ${sanitizeForNotify(unknownKeys.join(", "))} (known: ${ROUTER_KEYS.map(
+		fault(
+			`slate: ignoring unknown router key(s): ${sanitizeForNotify(unknownKeys.join(", "))}. The known router keys are ${ROUTER_KEYS.map(
 				(k) => `"${k}"`,
-			).join(", ")})`,
+			).join(", ")}.`,
 		);
 	}
 
+	const read = (key: keyof typeof value): { readable: boolean; value: unknown } => {
+		try {
+			return { readable: true, value: value[key] };
+		} catch {
+			fault(`slate: ignoring router.${key} because its value could not be read. Slate uses the default.`);
+			return { readable: false, value: undefined };
+		}
+	};
+
+	const rawModels = read("models");
 	const models: string[] = [];
-	if (value.models !== undefined) {
-		if (!Array.isArray(value.models)) {
-			warn('slate: router.models must be an array of "provider/id" strings — ignoring it (the router stays off)');
+	if (rawModels.readable && rawModels.value !== undefined) {
+		if (!Array.isArray(rawModels.value)) {
+			fault('slate: router.models must be an array of "provider/id" strings. Slate ignores the value, so the router stays off.');
 		} else {
-			for (const entry of value.models) {
+			for (const entry of rawModels.value) {
 				if (!isModelSpec(entry)) {
-					warn(`slate: ignoring router.models entry ${quoted(entry)} — ${describeSpecDefect(entry)}`);
+					// quoted() echoes a USER value, so its brackets stay: a nested array has
+					// to be recognisable in the warning that rejects it.
+					fault(`slate: ignoring the router.models entry ${quoted(entry)}. Reason: ${describeSpecDefect(entry)}.`);
 					continue;
 				}
 				models.push(entry);
@@ -401,17 +536,31 @@ export function sanitizeRouterConfig(raw: unknown, warn: (msg: string) => void):
 	}
 
 	let allowUnmeasuredEffort = true;
-	if (value.allowUnmeasuredEffort !== undefined) {
-		if (typeof value.allowUnmeasuredEffort !== "boolean") {
-			warn(
-				`slate: ignoring router.allowUnmeasuredEffort ${quoted(value.allowUnmeasuredEffort)} — expected true or false (defaulting to true)`,
+	const rawAllowUnmeasuredEffort = read("allowUnmeasuredEffort");
+	if (rawAllowUnmeasuredEffort.readable && rawAllowUnmeasuredEffort.value !== undefined) {
+		if (typeof rawAllowUnmeasuredEffort.value !== "boolean") {
+			fault(
+				`slate: ignoring router.allowUnmeasuredEffort ${quoted(rawAllowUnmeasuredEffort.value)}. Expected true or false. Slate uses true.`,
 			);
 		} else {
-			allowUnmeasuredEffort = value.allowUnmeasuredEffort;
+			allowUnmeasuredEffort = rawAllowUnmeasuredEffort.value;
+		}
+	}
+
+	// Same shape as allowUnmeasuredEffort above: a non-boolean value is reported
+	// and the default stands. Reporting it is itself a configuration fault, so a
+	// typo here can never hide behind the very option it fails to set.
+	let showWarnings = false;
+	const rawShowWarnings = read("showWarnings");
+	if (rawShowWarnings.readable && rawShowWarnings.value !== undefined) {
+		if (typeof rawShowWarnings.value !== "boolean") {
+			fault(`slate: ignoring router.showWarnings ${quoted(rawShowWarnings.value)}. Expected true or false. Slate uses false.`);
+		} else {
+			showWarnings = rawShowWarnings.value;
 		}
 	}
 
-	return { models, allowUnmeasuredEffort };
+	return { models, allowUnmeasuredEffort, showWarnings };
 }
 
 /** Sort key for a tier: a malformed/absent tier sorts LAST instead of poisoning the comparator with NaN (CQ5). */
@@ -434,7 +583,7 @@ function tierOf(profile: ModelProfile): number {
  * normally runs first, but this function is also called directly — by the
  * checks, and by any future caller that builds a list itself (BG4).
  */
-export function resolveModelRouter(input: ModelRouterInput, warn: (msg: string) => void = () => {}): ModelRouterResolution {
+export function resolveModelRouter(input: ModelRouterInput, warn: RouterWarnSink = () => {}): ModelRouterResolution {
 	const models = Array.isArray(input.models) ? input.models : [];
 	if (models.length === 0) return ROUTER_OFF;
 
@@ -446,14 +595,21 @@ export function resolveModelRouter(input: ModelRouterInput, warn: (msg: string)
 	// what identifies a condition, so a reworded message cannot start repeating.
 	// BG3: the sink is called inside a try/catch — a throwing UI must not abort a
 	// resolution (and, through the memo below, must not un-cache it either).
+	//
+	// The CLASS is the third parameter, and it DEFAULTS to "configuration-fault".
+	// A future warning added here without a class is therefore visible rather than
+	// silently hidden: forgetting the class costs noise, never a lost report.
 	const emitted = new Set<string>();
 	const warnings: string[] = [];
-	const once = (key: string, message: string) => {
+	const once = (key: string, message: string, warningClass: RouterWarningClass = "configuration-fault") => {
 		if (emitted.has(key)) return;
 		emitted.add(key);
-		warnings.push(message);
+		// The whole assembled message is capped here, so the control-byte strip and the
+		// length bound apply to the finished string and not only to its interpolations.
+		const text = sanitizeForNotify(message, ROUTER_MESSAGE_MAX);
+		warnings.push(text);
 		try {
-			warn(message);
+			warn(text, warningClass);
 		} catch {
 			/* a broken warn sink costs the notice, never the resolution (BG3) */
 		}
@@ -468,7 +624,9 @@ export function resolveModelRouter(input: ModelRouterInput, warn: (msg: string)
 		if (!isModelSpec(raw)) {
 			once(
 				conditionKey("malformed", raw),
-				`slate: model router: ignoring ${quoted(raw)} — ${describeSpecDefect(raw)}, so it is not a canonical "provider/id" model spec`,
+				// quoted() echoes a USER value: brackets and all, so the entry stays recognisable.
+				`slate: model router: ignoring the router.models entry ${quoted(raw)}. It is not a canonical "provider/id" ` +
+					`model spec. Reason: ${describeSpecDefect(raw)}.`,
 			);
 			continue;
 		}
@@ -485,7 +643,8 @@ export function resolveModelRouter(input: ModelRouterInput, warn: (msg: string)
 		if (!profile || typeof profile !== "object") {
 			once(
 				conditionKey("unprofiled", raw),
-				`slate: model router: ${label} has no benchmark data in slate's model profiles — excluding it from routing`,
+				`slate: model router: ${label} has no entry in slate's model profile table. Slate has no benchmark data for it, ` +
+					"so slate drops it from routing. Remove it from router.models, or list a profiled model instead.",
 			);
 			continue;
 		}
@@ -499,8 +658,8 @@ export function resolveModelRouter(input: ModelRouterInput, warn: (msg: string)
 		if (claimedBy !== undefined) {
 			once(
 				conditionKey("alias-duplicate", raw),
-				`slate: model router: ${label} is the same profiled model as ${sanitizeForNotify(claimedBy)} ` +
-					`(both resolve to ${sanitizeForNotify(profileId)}) — keeping the first and dropping this one`,
+				`slate: model router: ${label} and ${sanitizeForNotify(claimedBy)} name the same profiled model. ` +
+					`Both resolve to the model profile ${sanitizeForNotify(profileId)}. Slate keeps the first entry and drops ${label}.`,
 			);
 			continue;
 		}
@@ -517,7 +676,9 @@ export function resolveModelRouter(input: ModelRouterInput, warn: (msg: string)
 		if (!model || typeof model !== "object") {
 			once(
 				conditionKey("unknown", raw),
-				`slate: model router: ${label} is not in pi's model registry — dropping it (routing there could only produce billed failures)`,
+				`slate: model router: ${label} is not in pi's model registry. Slate drops it from routing. ` +
+					"A dispatch to a model pi does not know could only produce a billed failure. " +
+					"Add the model to pi's model registry, or remove it from router.models.",
 			);
 			continue;
 		}
@@ -530,7 +691,8 @@ export function resolveModelRouter(input: ModelRouterInput, warn: (msg: string)
 		if (!authed) {
 			once(
 				conditionKey("noauth", raw),
-				`slate: model router: ${label} has no usable credentials configured in pi — dropping it (routing there could only produce billed failures)`,
+				`slate: model router: ${label} has no usable credentials configured in pi. Slate drops it from routing. ` +
+					"A dispatch to a model without credentials could only produce a billed failure. Add credentials in pi to route to it.",
 			);
 			continue;
 		}
@@ -541,8 +703,9 @@ export function resolveModelRouter(input: ModelRouterInput, warn: (msg: string)
 		if (inUsdPerMTok === undefined) {
 			once(
 				conditionKey("price", raw),
-				`slate: model router: ${label} has no usable input price for ${today} in its profile — ` +
-					"keeping it, ordered last; its cost cannot be compared",
+				`slate: model router: ${label} has no usable input price for ${today} in its model profile. ` +
+					"Slate keeps the model and orders it last. Slate cannot compare its cost with the other models.",
+				"model-data-note",
 			);
 		}
 
@@ -596,10 +759,12 @@ export function resolveModelRouter(input: ModelRouterInput, warn: (msg: string)
 				// from the user, this line must name WHICH source it read — the sentence
 				// contrasts two sources, and mislabelling one of them is the whole defect
 				// this wording was rewritten to avoid.
-				`slate: model router: context window for ${label} differs between sources — the model profile records ` +
-					`${profileWindow} tokens (profile asOf ${quoted(profile.asOf ?? "unknown")}), pi's model registry reports ` +
-					`${registryWindow} tokens. Routing uses the registry figure; which source is correct is not established here.` +
-					`${matchesBillingThreshold ? " That registry figure is also this model's long-context BILLING threshold — see the note below." : ""}`,
+				`slate: model router: the context window for ${label} differs between two sources. The model profile records ` +
+					`${profileWindow} tokens, and that profile was recorded as of ${profileText(quoted(profile.asOf ?? "unknown"))}. ` +
+					`The pi model registry reports ${registryWindow} tokens. Routing uses the registry figure. ` +
+					"Slate does not establish here which source is correct." +
+					`${matchesBillingThreshold ? " That registry figure is also this model's long-context billing threshold. A separate note below names that pattern." : ""}`,
+				"model-data-note",
 			);
 		}
 
@@ -607,11 +772,25 @@ export function resolveModelRouter(input: ModelRouterInput, warn: (msg: string)
 		const unknownFields = Array.isArray(profile.unknownRoutingCriticalFields)
 			? profile.unknownRoutingCriticalFields.filter((f) => typeof f === "string" && f !== "")
 			: [];
-		if (unknownFields.length > 0) {
+		const renderedUnknownFields = unknownFields.map((field) => profileText(field)).filter((field) => field !== "");
+		if (renderedUnknownFields.length > 0) {
+			// The CLASS explanation, once per session and only when a W3 warning fires at
+			// all. It is emitted BEFORE the first per-model line, so a reader meets the
+			// meaning of the class before the first instance of it (BG27's aggregation
+			// argument, applied to an explanation rather than to a set of models).
+			once(
+				"w3-explainer",
+				"slate: model router: slate picks models from a research table shipped inside slate. Some figures in that " +
+					"table have no traced source. Slate records the absence instead of a guess. Routing still works. " +
+					"The ranking of such a model rests on less evidence. You cannot close this gap from your configuration.",
+				"model-data-note",
+			);
+			const factNoun = renderedUnknownFields.length === 1 ? "fact" : "facts";
 			once(
 				conditionKey("w3", raw),
-				`slate: model router: ${label} has unknown routing-critical data — ` +
-					`${unknownFields.map((f) => sanitizeForNotify(f, 80)).join("; ")} — routing decisions for it are provisional`,
+				`slate: model router: ${label} has ${renderedUnknownFields.length} model ${factNoun} that slate could not trace to a ` +
+					`source: ${renderedUnknownFields.join(FIELD_SEPARATOR)}. Routing to this model still works.`,
+				"model-data-note",
 			);
 		}
 
@@ -631,10 +810,17 @@ export function resolveModelRouter(input: ModelRouterInput, warn: (msg: string)
 			? [...new Set(ladderRaw.filter((l): l is ThinkingLevel => THINKING_LEVELS.includes(l as string)))]
 			: [];
 		if (ladder.length === 0) {
+			// The earlier text claimed that every explicit effort level would read as
+			// off-ladder. That was wrong: guard 2 in route.ts fires only on a KNOWN ladder
+			// (`ladderKnown`), so an unreadable ladder makes it stand down and the level goes
+			// to pi, which clamps it. Guard 4 keeps its carve-out either way.
 			once(
 				conditionKey("ladder", raw),
-				`slate: model router: ${label} has no usable effort ladder in its profile — ` +
-					"keeping it, but every explicit effort level for it will read as off-ladder",
+				`slate: model router: ${label} has no usable effort ladder in its model profile. Slate keeps the model. ` +
+					"Slate cannot check an explicit effort level against a ladder it could not read. Such a level passes " +
+					"through to pi, which clamps it to a level the model supports. A level the provider rejects outright " +
+					"is still refused.",
+				"model-data-note",
 			);
 		}
 
@@ -663,8 +849,8 @@ export function resolveModelRouter(input: ModelRouterInput, warn: (msg: string)
 	if (!isNonEmpty(candidates)) {
 		once(
 			"all-dropped",
-			`slate: model router: routing is disabled — none of the ${models.length} configured router.models ` +
-				"entries survived validation (see the warnings above)",
+			`slate: model router: routing is disabled. None of the ${models.length} configured router.models entries ` +
+				"survived validation. The warnings above name each dropped entry and the reason for it.",
 		);
 		return frozenResolution(false, [], undefined, false, warnings);
 	}
@@ -677,9 +863,11 @@ export function resolveModelRouter(input: ModelRouterInput, warn: (msg: string)
 	if (billingPatternSpecs.length > 0) {
 		once(
 			"w1-billing-pattern",
-			`slate: model router: the registry's context window equals the model's own long-context BILLING threshold for ` +
-				`${billingPatternSpecs.join(", ")} — a window equal to its own threshold would leave the long-context price ` +
-				"tier unreachable, which is the billing-row-restated-as-a-capacity pattern finding RI32 warns about.",
+			"slate: model router: for these models the pi model registry reports a context window equal to the model's own " +
+				`long-context billing threshold: ${billingPatternSpecs.join(", ")}. A window equal to its own threshold would ` +
+				"leave the long-context price tier unreachable. That shape suggests a billing figure restated as a capacity " +
+				"figure. Slate reports the pattern and does not decide which figure is right.",
+			"model-data-note",
 		);
 	}
 
@@ -690,8 +878,9 @@ export function resolveModelRouter(input: ModelRouterInput, warn: (msg: string)
 	if (uncovered.length > 0) {
 		once(
 			"failover-coverage",
-			`slate: model router: no modelFailover entry for ${uncovered.join(", ")} — ` +
-				"a model failure while routed there has no failover coverage",
+			`slate: model router: these routable models have no modelFailover entry: ${uncovered.join(", ")}. ` +
+				"A model failure during an action routed to one of them has no failover coverage. " +
+				"Add a modelFailover entry for each of them to cover that case.",
 		);
 	}
 
@@ -735,10 +924,15 @@ export function resolveModelRouter(input: ModelRouterInput, warn: (msg: string)
 	for (const c of pool) if (price(c) < price(cheapest)) cheapest = c;
 	const cheapestNonPreferred = cheapest.nonPreferred !== null;
 	if (cheapestNonPreferred) {
+		// Always visible (a configuration fault by part (b) of the class test: adding
+		// one preferred model to router.models stops it), so the text is
+		// project-authored and the interpolated reason is stripped of its source tags.
 		once(
 			"nonpreferred-base",
-			`slate: model router: every configured model is marked non-preferred, so ${sanitizeForNotify(cheapest.spec, 60)} ` +
-				`is the default base model anyway — ${sanitizeForNotify(cheapest.nonPreferred ?? "", 120)}`,
+			"slate: model router: slate's model profiles mark every configured model as one it must never pick by " +
+				`itself. Slate still needs a default base model, so ${sanitizeForNotify(cheapest.spec, 60)} is the base ` +
+				`model for new threads. The recorded reason for that mark is: ${profileText(cheapest.nonPreferred ?? "")}. ` +
+				"Add a model without that mark to router.models to change the base model.",
 		);
 	}
 
@@ -837,7 +1031,7 @@ export function checkEffort(resolution: ModelRouterResolution, spec: string, eff
  */
 export function createModelRouterResolver(
 	getInput: () => ModelRouterInput,
-	warn: (msg: string) => void = () => {},
+	warn: RouterWarnSink = () => {},
 ): () => ModelRouterResolution {
 	let cached: ModelRouterResolution | undefined;
 	return () => {
@@ -845,11 +1039,17 @@ export function createModelRouterResolver(
 			try {
 				cached = resolveModelRouter(getInput(), warn);
 			} catch (error) {
-				const message = `slate: model router: routing is disabled — resolution failed: ${sanitizeForNotify(
-					error instanceof Error ? error.message : String(error),
-				)}`;
+				// A configuration fault by the class test: the user's own model list, config or
+				// credentials are the most likely input to a failed resolution, and a silent
+				// router that routes nothing is the worst outcome to hide.
+				const message = sanitizeForNotify(
+					`slate: model router: routing is disabled. The router could not resolve its model list. The error was: ${sanitizeForNotify(
+						error instanceof Error ? error.message : String(error),
+					)}`,
+					ROUTER_MESSAGE_MAX,
+				);
 				try {
-					warn(message);
+					warn(message, "configuration-fault");
 				} catch {
 					/* see BG3 above */
 				}

package/extension/notify.ts

@@ -7,14 +7,18 @@
  * control/ANSI codes verbatim, so a raw value could inject terminal escapes —
  * strip control characters and cap the length before display.
  *
- * Imported by failover.ts, handoff.ts, worker.ts and worker-extensions.ts, which
- * previously each carried a verbatim copy. model-default.ts deliberately does
- * NOT import this: it also needs the bare control-char strip as a standalone
- * primitive (for its word-boundary report truncation, which this helper does
- * not do), so it keeps that primitive and its own fragment cap together locally
- * — see the note there.
+ * Imported across failover.ts, handoff.ts, worker.ts, worker-extensions.ts,
+ * writing.ts, state.ts, episodes.ts, threads.ts, route.ts, base-model.ts and
+ * model-router.ts. This shared change therefore affects every notify or console
+ * warning those modules emit. model-default.ts deliberately does NOT import this:
+ * it also needs the bare control-char strip as a standalone primitive (for its
+ * word-boundary report truncation, which this helper does not do), so it keeps
+ * that primitive and its own fragment cap together locally — see the note there.
  */
 export function sanitizeForNotify(s: string, max = 120): string {
-	const clean = s.replace(/[\u0000-\u001f\u007f\u009b]/g, "");
+	// Remove all C0 and C1 controls, DEL, and Unicode bidirectional formatting
+	// controls. A directional override can reorder visible warning text even when
+	// it is not a terminal escape, and truncation can otherwise separate its pair.
+	const clean = s.replace(/[\u0000-\u001f\u007f\u0080-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g, "");
 	return clean.length > max ? `${clean.slice(0, max)}…` : clean;
 }

package/extension/state.ts

@@ -474,12 +474,16 @@ export interface ContextBudgetObject {
  * 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.
+ * an evidence gap is advisory, not a prohibition. `showWarnings` (default
+ * FALSE) reveals the router's MODEL DATA NOTES — the warnings a user cannot stop
+ * by changing this file or their pi credentials. A configuration fault is always
+ * shown, whatever this key says. Validated by sanitizeRouterConfig in
+ * model-router.ts.
  */
 export interface RouterConfig {
 	models?: string[];
 	allowUnmeasuredEffort?: boolean;
+	showWarnings?: boolean;
 }
 
 /** Optional writing checks and context-cadenced reminders. */
@@ -527,7 +531,11 @@ export class SlateStore {
 	/** Invoked after every save/restore; used by mode.ts to refresh the widget. */
 	onDidChange?: () => void;
 
-	constructor(private pi: ExtensionAPI) {}
+	private pi: ExtensionAPI;
+
+	constructor(pi: ExtensionAPI) {
+		this.pi = pi;
+	}
 
 	nextThreadId(): string {
 		let max = 0;

package/extension/threads.ts

@@ -202,7 +202,10 @@ const FAILOVER_NUDGE =
 class Semaphore {
 	private waiters: Array<() => void> = [];
 	private active = 0;
-	constructor(private limit: number) {}
+	private limit: number;
+	constructor(limit: number) {
+		this.limit = limit;
+	}
 	async acquire(): Promise<void> {
 		if (this.active < this.limit) {
 			this.active++;
@@ -253,27 +256,42 @@ export class ThreadManager {
 	private liveBaselines = new Map<string, SessionBaseline>();
 	/** pi's compaction settings, read once (a lock-protected disk read) — see compactionSettings(). */
 	private cachedCompaction?: { enabled: boolean; reserveTokens: number; keepRecentTokens: number };
+	/** Session-owned persisted thread and episode state. */
+	private store: SlateStore;
+	/** This manager's immutable session configuration. */
+	private config: SlateConfig;
+	/** Frozen worker-extension resolver, bound by value to this session (AD41/CN20). */
+	private resolveExtensions: () => WorkerExtensionSet;
+	/** Memoized router resolver, bound by value to this session. */
+	private resolveRouter: () => ModelRouterResolution;
+	/** Orchestrator base model used only by the episode compressor's last-resort rung. */
+	private baseModelTracker?: BaseModelTracker;
 
 	constructor(
-		private store: SlateStore,
-		private config: SlateConfig,
+		store: SlateStore,
+		config: SlateConfig,
 		// This session's frozen worker-extension resolver (AD41), bound BY VALUE at
 		// construction (CN20) so a manager orphaned by a session swap keeps its own
 		// session's set instead of resolving against a later one's. Read lazily per
 		// new worker. Defaults to the empty-set function so existing construction
 		// sites and test harnesses keep working with the feature off.
-		private resolveExtensions: () => WorkerExtensionSet = () => EMPTY_WORKER_EXTENSION_SET,
+		resolveExtensions: () => WorkerExtensionSet = () => EMPTY_WORKER_EXTENSION_SET,
 		// 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 shared OFF
 		// resolution, which supplies no candidates or router-owned base.
-		private resolveRouter: () => ModelRouterResolution = () => ROUTER_OFF,
+		resolveRouter: () => ModelRouterResolution = () => ROUTER_OFF,
 		// The orchestrator's base model, EXCLUDING failover fallbacks (base-model.ts).
 		// 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,
+		baseModelTracker?: BaseModelTracker,
 	) {
+		this.store = store;
+		this.config = config;
+		this.resolveExtensions = resolveExtensions;
+		this.resolveRouter = resolveRouter;
+		this.baseModelTracker = baseModelTracker;
 		this.semaphore = new Semaphore(config.maxConcurrent ?? 4); // default rationale: docs/design-principles.md §5 repo-local note
 	}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ytdb-slate",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "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": {
@@ -23,7 +23,11 @@
     ]
   },
   "scripts": {
-    "typecheck": "tsc --noEmit -p tsconfig.json"
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bash verification/run-tests.sh",
+    "test:coverage": "bash verification/run-tests.sh",
+    "coverage:gate": "node verification/coverage-gate.mjs",
+    "link:peers": "bash verification/link-peers.sh"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",