ytdb-slate 0.2.1 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # ytdb-slate
 
-Slate is a thread-weaving orchestration extension for the [pi coding agent](https://github.com/earendil-works/pi-coding-agent).
+Slate is a thread-weaving orchestration extension for the [pi coding agent](https://pi.dev).
 
 The orchestrator (your main pi session) dispatches **bounded actions** to persistent **worker threads**. Each completed action is compressed by an LLM into an **episode** — a durable, structured record (intent, actions, findings, artifacts, open issues, handoff notes) that the orchestrator composes into further dispatches instead of re-reading raw transcripts. On top of that, Slate injects a mandatory workflow doctrine: research before design, design review, adversarial review, and track review — with optional umbrella **draft-PR publishing** for tracks. An opt-in **model-failover** map adds high availability: when a model API fails, the orchestrator, worker threads, and episode compression each retry once on a configured equal-quality alternative.
 
@@ -47,6 +47,10 @@ The workflow scales with change size: multi-track changes get the full flow, sin
 
 This summary is orientation only; the shipped docs listed below are normative.
 
+## Model failover
+
+Slate can ride through model API outages. The opt-in `modelFailover` map in `.pi/slate.json` (trusted projects only) maps a model (`provider/id`) to an equal-quality alternative; on an eligible model API failure — not an abort or a context overflow, and for the orchestrator and worker sites only after pi's own retries are exhausted — the affected site (orchestrator, worker thread, or episode compression) retries once on the mapped model (single hop, never chained). An orchestrator failover — like the handoff adoption that re-applies a parent session's model — would otherwise leave pi's global model defaults changed, so Slate restores them on a best-effort basis unless `preserveGlobalModelDefault` is `false`. The map is empty by default (feature off) and read once at session start. Full semantics: the `modelFailover` row in [Configuration](#configuration) and the shipped [`docs/model-failover.md`](docs/model-failover.md) — if they disagree, that document wins.
+
 ## Install
 
 Install into a project (pinned, project-scoped — recorded in `.pi/settings.json`):
@@ -66,6 +70,7 @@ Optional config file: `slate.json` in the project's pi config dir (`.pi/slate.js
 | `orchestratorModeDefault` | boolean | `false` | Start fresh interactive sessions with orchestrator mode ON. |
 | `episodeModel` | string | newest available Anthropic Sonnet, else the worker's own model | Model (`provider/id`) used to compress a finished action into an episode. |
 | `workerTools` | string[] | `["read", "bash", "edit", "write", "grep", "find", "ls"]` | Tools available to worker threads (an empty list also falls back to the default). |
+| `workerExtensions` | string[] | `[]` | Regex patterns (matched **unanchored**) selecting which of the host session's already-loaded extensions also load into every worker thread; each matched extension's tools are added **on top of** `workerTools`. Empty (default) means workers load no extensions. The orchestrator keeps its restricted tool set but its doctrine is told what was whitelisted. Invalid patterns are dropped with a warning at session start. |
 | `maxConcurrent` | number | `4` | Maximum number of worker actions running concurrently (must be ≥ 1 — unenforced: a value of 0 or less silently hangs all dispatches). Excess dispatches wait in a queue; actions on the same thread always run in dispatch order. Default rationale: shipped `docs/design-principles.md` §5 (repo-local note). |
 | `contextBudget` | number \| object | `256000` (Anthropic models: `400000`) | Absolute orchestrator context budget (tokens) at which Slate auto-pauses and prepares a fresh-session handoff — semantics, defaults, per-model overrides, and rationale in [`docs/context-budget.md`](docs/context-budget.md). |
 | `orchestratorPromptDocs` | string[] | `[]` | Project markdown files (paths relative to the project root) whose **contents** are appended to the orchestrator system prompt. |
@@ -74,6 +79,7 @@ Optional config file: `slate.json` in the project's pi config dir (`.pi/slate.js
 | `doctrineExtraPath` | string | — | Project markdown whose **content** is appended to the orchestrator doctrine (project-specific workflow additions). |
 | `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). |
 
 Example `.pi/slate.json` (the `docs/agents/...` paths are placeholders — point them at markdown files that actually exist in **your** project):
 
@@ -93,6 +99,27 @@ Example `.pi/slate.json` (the `docs/agents/...` paths are placeholders — point
 
 > **Silent skip:** the project-file keys fail silently — no error is shown. For the content-injected keys (`orchestratorPromptDocs`, `workerPromptDocs`, `doctrineExtraPath`) a missing, unreadable, or empty file is skipped and nothing is injected. For `reviewPerspectivesPath` the pointer is omitted only when the file is missing — the file is not read at injection time, so an unreadable or empty file is still cited. Verify your paths after copying the example.
 
+**Worker extensions (`workerExtensions`).** By default worker threads load no extensions. This key is a list of regex patterns that select extensions the **host session has already loaded** and load them into every worker too. Each pattern is matched **unanchored** (unlike `contextBudget.overrides`, which is anchored) against a load unit's recorded source spec (e.g. `npm:pi-web-search@1.3.1`), its load-unit path, or the entry path of any tool that unit contributes, so a bare package name matches:
+
+```json
+{
+  "workerExtensions": ["pi-smart-fetch", "pi-web-search"]
+}
+```
+
+Every worker then gets the fetch and web-search tools **on top of** `workerTools` (and on top of the per-dispatch `tools` argument of the `thread` tool — those two govern the built-in tools only). The orchestrator itself does **not** gain these tools — orchestrator mode keeps its restricted set — but its doctrine gains a rule naming each whitelisted extension and its tools, so it knows what it can delegate. pi's discovery, project-trust gating, and dedup remain the only ingress: a worker can never load an extension the host is not running, an extension that registers no tools cannot be whitelisted, and a host started with extensions disabled offers nothing to whitelist.
+
+**What to know before whitelisting** — it reaches past Slate's isolation, so it is an operator decision:
+
+- **Delegation is unbounded.** Slate guarantees only that no worker obtains Slate's own `thread`/`threads`/`episode` tools. A whitelisted extension that ships its own sub-agent or delegation tool under any other name gives workers delegation Slate can neither detect, bound, nor account for.
+- **Credential and filesystem reach.** Inside a worker the extension has the same filesystem and credential access it has in the host; Slate's read-only settings snapshot blocks pi-settings writes and nothing else.
+- **Unsynced model-scoped tools.** Worker sessions never fire the session-start event, so an extension whose tool set is model-scoped stays unsynced and may offer a tool the worker's model cannot serve (e.g. pi-web-search's `url_context` on a non-Google worker model) — the call simply fails and the episode records it.
+- **Abort.** A third-party extension may ignore the abort signal, so its network activity can outlive an abort or a context-budget pause.
+- **Cost.** Provider-native tool billing can escape Slate's worker cost accounting.
+- **Pathological patterns.** The patterns are regexes from your own trusted config — the same file that already steers models, prompts, and tool lists — matched with no time bound while the extension set is resolved once per session. A pattern with catastrophic backtracking can stall that resolution; treat it as a footgun to avoid, not a privilege boundary.
+
+The load-time recursion guard behind this — and the risks it does and does not cover — is in [`docs/design-principles.md`](docs/design-principles.md).
+
 ## Trust
 
 Slate reads project configuration (`.pi/slate.json`) and injects project files (`orchestratorPromptDocs`, `workerPromptDocs`, `doctrineExtraPath`, `reviewPerspectivesPath`) **only in trusted projects**. In untrusted projects Slate runs with built-in defaults and injects nothing from the working tree.

package/docs/design-principles.md

@@ -125,8 +125,11 @@ or two problems for the others:
   not blind retry.
 - **P6 — Make desired behavior the natural behavior.** In orchestrator
   mode, tactical tools are removed, so delegation is the only way to act.
-- **P7 — Guard against over-decomposition.** Workers cannot spawn threads
-  (depth-1); recursion is structurally impossible.
+- **P7 — Guard against over-decomposition.** Workers never receive
+  Slate's dispatch tools (`thread`/`threads`/`episode`), so no worker can
+  spawn a Slate thread — Slate's own recursion stays depth-1. That is a
+  narrow load-time invariant, not a general delegation bound (see the
+  recursion-guard note in §5).
 - **P8 — Per-episode feedback beats blind N-step execution.** Bounded
   actions return before the next decision, so course correction is always
   possible.
@@ -146,7 +149,7 @@ or two problems for the others:
 | P4 context by reference | `tools.ts` `context` parameter injects prior episodes by id |
 | P5 adaptive decomposition | doctrine rule 6 in `mode.ts`; no plan structure imposed anywhere |
 | P6 natural behavior | `mode.ts` `ORCHESTRATOR_TOOLS` restriction (read-only + slate tools) |
-| P7 over-decomposition guard | `worker.ts` recursion guard — workers load no extensions, so the `thread` tool never exists for them |
+| P7 over-decomposition guard | `worker.ts` recursion guard — load-scoped barriers keep Slate's `thread`/`threads`/`episode` tools out of every worker (recursion-guard note below) |
 | P8 per-episode feedback | `threads.ts` synchronous dispatch; episode returned to orchestrator |
 | P9 parallelism | `threads.ts` `maxConcurrent` queueing; doctrine rule 2 in `mode.ts` |
 | P10 context as RAM | `handoff.ts` context-budget auto-pause + fresh-session handoff |
@@ -164,6 +167,97 @@ while staying safe on common consumer API tiers; wider fan-outs only
 pay tail latency, and projects with higher-tier keys raise the cap in
 `slate.json`.
 
+Repo-local note (not from the report): the P7 guard was originally
+absolute — workers loaded no extensions, so Slate's `thread` tool simply
+never existed for them. The optional `workerExtensions` key (`slate.json`,
+trusted projects only — see the README config reference) relaxes that: it
+whitelists extensions the host session has ALREADY loaded and loads them
+into every worker. The guard therefore no longer rests on "workers load
+nothing" but on a narrower, more precise invariant: no worker can ever
+obtain SLATE's dispatch tools (`thread`/`threads`/`episode`).
+
+Three load-scoped barriers buy that invariant, all applied per LOAD UNIT
+— the owning package directory when the extension is package-originated
+and the package's declared entries provably match what the host loaded
+(BG20, below), otherwise the extension's own entry file:
+
+1. Only whitelisted units load, through pi's resource loader in allowlist
+   mode; a worker's extension set is exactly the allowlist and no
+   non-whitelisted module is ever imported (load errors surface as
+   warnings). Candidates are only what the host session already loaded,
+   enumerated from its tool registry — so an extension registering no
+   tools is invisible, and a host started with extensions disabled yields
+   an empty candidate set.
+2. Any unit that contains Slate's own package root is dropped whatever the
+   patterns say.
+3. Any unit whose tools collide with Slate's `thread`/`threads`/`episode`
+   or with pi's built-ins (`read`/`bash`/`edit`/`write`/`grep`/`find`/`ls`)
+   is dropped WHOLE — pi's registry lets an extension tool overwrite a
+   same-named built-in, so a partial load could shadow the very tools the
+   guard protects.
+
+Exclusion has to happen at load time, at unit granularity, rather than by
+loading everything and filtering the tool list afterwards: a
+worker-loaded extension is not tools-only. Its event handlers, tools, and
+flags all go live on load, so once a unit has loaded its side effects have
+already run and dropping its tools afterwards would leave its handlers and
+flags active. Dropping the whole unit before it loads is the only clean
+cut — which is also why barrier 3 rejects a colliding unit entirely
+instead of suppressing just the offending tool. (A package directory is
+handed to pi whole — letting pi's own manifest resolution expand it, so
+no-tool companion entries load alongside the tool-bearing ones — only when
+the manifest's declared entries are ALL literal relative paths AND the
+host loaded every one of them. A glob or override-form entry, or a host
+running only a filtered subset, fails that equivalence check and drops the
+unit to exactly the entry files the host loaded; that fallback loses the
+package's no-tool companion entries, since an entry that registered no
+tool cannot be shown to be running.)
+
+That collision barrier is best-effort and load-time only: it runs before a
+unit loads, against its tools as the HOST registry reports them, and once
+more after the load, against the tools the units actually registered — a
+post-load collision fails the dispatch CLOSED rather than opening the
+worker. Neither pass can see a tool an extension registers only LATER, on
+the worker's first turn (a `before_agent_start` handler, say). Slate's own
+dispatch tools do not depend on that scan: `createAgentSession` is given
+an `excludeTools` denylist of `thread`/`threads`/`episode` that pi applies
+AFTER the tool allowlist and re-applies on every tool-registry refresh, so
+they can never be active in a worker no matter when or by whom they are
+registered — a deferred registration included. A deferred registration
+that shadows a pi BUILT-IN (`read`, `bash`, …) has no such gap-closer —
+the worker needs the real built-in — so it stays outside Slate's control,
+exactly as available to any extension the host session runs. The guard
+bounds Slate's dispatch tools, not every tool an extension might register
+at runtime.
+
+The orchestrator does NOT get the whitelisted tools; orchestrator mode
+keeps its restricted set. Instead its doctrine gains a rule listing each
+whitelisted extension with its tool names and descriptions, so it knows
+what it can delegate. That doctrine rule and the worker allowlists come
+from a single memoized resolution per session, so the two cannot drift.
+
+The invariant bought is exactly that: no worker gets Slate's dispatch
+tools. It is NOT a general recursion or delegation bound, and the accepted
+risks that follow are the operator's to weigh:
+
+- A whitelisted extension that registers its OWN sub-agent or delegation
+  tool under any other name gives workers unbounded delegation that Slate
+  can neither detect nor bound, outside Slate's episode and cost
+  accounting. Whitelisting such an extension is a deliberate operator
+  decision.
+- Inside a worker a whitelisted extension has the same filesystem and
+  credential reach it has in the host; Slate's read-only settings snapshot
+  blocks pi-settings writes and nothing else.
+- Worker sessions never fire the session-start event, so an extension
+  whose model-scoped tool manager depends on it stays unsynced and may
+  offer a tool the worker's model cannot serve — the call simply fails and
+  the episode records it.
+- Third-party extensions may ignore the abort signal, so their network
+  activity can outlive an abort or a context-budget pause.
+- Host and worker copies of the same extension share module-level state
+  through pi's process-global module cache.
+- Provider-native tool billing may escape Slate's worker cost accounting.
+
 ## 6. Runtime knowledge: what the orchestrator knows, and when
 
 The orchestrator's knowledge of these principles is two-tier, following

package/docs/model-failover.md

@@ -38,13 +38,16 @@ rule below.
 
 The map is read ONCE, at session start. Editing `slate.json`
 mid-session — e.g. adding a mapping in the middle of an outage —
-takes effect only in a NEW pi session.
+takes effect only in a NEW pi session. The same holds for
+`preserveGlobalModelDefault` (see the caveats), which lives in the
+same file under the same trust rule.
 
 Configuring the map is the whole opt-in: in a trusted project with a
 `modelFailover` entry, ORCHESTRATOR failover is active in every pi
 session regardless of whether Slate's orchestrator mode is on — a
-matching model failure switches the session's model (and pi's global
-default, see the caveats) even if you never use threads.
+matching model failure switches the session's model (and, as a side
+effect, pi's global model defaults, which Slate restores by default —
+see the caveats) even if you never use threads.
 
 ## When failover fires
 
@@ -120,14 +123,100 @@ Failover applies at three sites:
 - **Episode compression:** no live signal — the episode header's
   `compressor:` line names whichever model actually produced the
   episode.
+- **The global-default restore:** silent when it succeeds, which is
+  the normal case. Otherwise a warning naming the reason — e.g.
+  `slate: not restoring the global model defaults — …` when Slate
+  stood down without writing anything, or `slate: could not restore
+  the global model defaults within …` when it wrote but could not
+  confirm the result in time — printed on the console and, when a UI
+  is attached, also raised as a notification. Both states are
+  explained in the caveats.
 
 ## Caveats & accepted limitations
 
-- Orchestrator failover persists the mapped model as the user's
-  **global default model** — that is pi's `setModel` semantics. Switch
-  back with `/model` once the outage is over.
+- Slate switches the live model at two sites: orchestrator failover,
+  and the handoff adoption that re-applies a parent session's model
+  and thinking level when a fresh session picks up a Slate handoff.
+  Adoption does NOT depend on the `modelFailover` map, so everything
+  in this part of the caveats applies even with the map empty and
+  failover off. Both switches persist into the user's **global**
+  settings — that is pi's `setModel` / `setThinkingLevel` semantics —
+  affecting `defaultProvider`, `defaultModel`, and, through pi's
+  thinking-level cascade, `defaultThinkingLevel`. (Global settings
+  live in `settings.json` inside pi's agent directory:
+  `~/.pi/agent/` by default, elsewhere when `PI_CODING_AGENT_DIR`
+  relocates it.) Slate puts them back, judging each switch by two
+  fresh reads of the global scope taken immediately before and
+  immediately after it. `defaultProvider` and `defaultModel` are
+  decided and written as ONE UNIT, because pi only ever writes that
+  pair together: the pair is restored only if every half the switch
+  changed also holds exactly what that switch should have produced,
+  and if either changed half holds something else the whole pair is
+  left alone. When the pair is restored, the pre-switch values are
+  written back exactly — including a half that had no value before,
+  which is restored to absence. `defaultThinkingLevel` is decided and
+  written on its own, by the same test. A key the switch did not
+  change keeps its value; the live session still runs the switched
+  model; and resume is unaffected — the restore rewrites the settings
+  file, not the running session.
+- `preserveGlobalModelDefault` (boolean, default `true`) disables that
+  restore when set to `false`, at BOTH sites; with it off, the
+  switched values stay in the global settings as they did before the
+  mechanism existed.
+- **Slate can decline to restore anything.** When it cannot trust what
+  it read — the settings file held under another process's lock,
+  unreadable, corrupt or empty, or an extension context gone stale —
+  it warns, writes nothing and deletes nothing: acting on a read it
+  cannot trust is the one way this mechanism could destroy settings
+  rather than merely fail to tidy up. The switch itself still
+  happened, so you are left where you were before the restore
+  existed: the session runs the switched model, and the global
+  defaults may hold Slate's pick. The warning names the file and the
+  reason; clear that condition (release the other process, repair or
+  remove the file) and put the defaults back by hand as below. A narrower
+  variant: if only the session's live thinking level cannot be read,
+  that one key is skipped and the provider/model pair is still
+  evaluated.
+- **A restore can also be abandoned.** Slate verifies that its
+  restoring write landed and retries within a wall-clock budget; if
+  the restore is still unconfirmed when the budget runs out, Slate
+  gives up and does NOT retry later. The switched provider, model, or
+  thinking level then persists in the global settings for that session
+  and every session afterwards, exactly as it did before this
+  mechanism existed. You are told by a console warning plus, when a UI
+  is attached, a notification — though console output can be lost if
+  the process exits on a signal immediately afterwards. Putting it
+  back is manual, and only partly possible from inside pi: `/model`
+  rewrites the provider/model pair, the thinking level has no slash
+  command (cycle it with its keybinding — `/hotkeys` lists it), and
+  neither can restore a key to ABSENT. If a key had no value before
+  the switch, remove it from the settings file by hand.
+- The restore takes pi's settings lock, and that lock is acquired
+  SYNCHRONOUSLY. Under contention — another pi process writing
+  settings at the same moment — a switch can stall the session for a
+  noticeable interval before Slate gives up: the wall-clock budget
+  gates whether a new attempt starts, it cannot interrupt one already
+  waiting.
+- The test is "does this key now hold exactly what Slate's switch
+  should have produced?", and it cannot ask who wrote that value.
+  Both directions follow from that one rule. A write by anything else
+  is reverted when it happens to leave exactly that value — which
+  covers a third-party write that pi's own switch then lands on top
+  of, and one arriving after Slate's last read but before its
+  restoring write, which is overwritten outright. A write that leaves
+  anything else fails the test, so Slate stands off and leaves the key
+  alone (for the pair, both keys) — and its own residue then survives
+  in the global settings, which is what a second, concurrent pi
+  session typically causes. The trade is deliberate: a missed cleanup
+  over a reverted user change.
+- Slate writes only those three keys, and only in the GLOBAL scope —
+  but any settings write re-serialises the whole file through pi's own
+  migration, which can rename or drop legacy keys. pi does that on its
+  own writes too; Slate's restore can only make it happen earlier.
 - Worker sessions use a read-only settings view, so worker failover
-  persists nothing.
+  persists nothing; episode compression invokes the mapped model
+  directly for the one request instead of switching the session's
+  model, so it persists nothing either.
 - Orchestrator **preflight** auth failures (e.g. an OAuth token that
   expired before any run starts) bypass failover — pi surfaces the
   error itself; recover manually with `/model`.

package/extension/failover.ts

@@ -26,16 +26,38 @@ import {
 	type ExtensionAPI,
 	type ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
+import { withGlobalModelDefaultRestored } from "./model-default.ts";
+import { sanitizeForNotify } from "./notify.ts";
 import type { SlateConfig } from "./state.ts";
 
 type RegistryModel = NonNullable<ReturnType<ExtensionContext["modelRegistry"]["find"]>>;
 
-// Error messages reach ctx.ui.notify, and pi-tui renders control/ANSI codes
-// verbatim — strip control characters and cap length before display (same
-// pattern as handoff.ts's sanitizeForNotify).
-function sanitizeForNotify(s: string, max = 120): string {
-	const clean = s.replace(/[\u0000-\u001f\u007f\u009b]/g, "");
-	return clean.length > max ? `${clean.slice(0, max)}…` : clean;
+// Console-first reporting, for FAILURES ONLY: the console line is
+// unconditional, so a failover that could not happen still surfaces in
+// headless runs and at teardown — the has-UI branch is exactly the one that
+// vanishes there — and the UI notification is the extra. Success notices keep
+// their has-UI gate: an unconditional stderr write during an interactive turn
+// scribbles pi-tui's differentially rendered frame, and a failover that worked
+// is not news worth that cost. ctx.hasUI is a getter that THROWS on a stale
+// context, so it is guarded: an unguarded check would be a crash, not a test.
+function reportFailure(ctx: ExtensionContext, message: string): void {
+	console.warn(message);
+	try {
+		if (ctx.hasUI) ctx.ui.notify(message, "warning");
+	} catch {
+		/* stale ctx — the console line above stands */
+	}
+}
+
+// UI-only notice, as before this module gained a restore mechanism: shown when
+// a UI exists, silent otherwise — only the guard is new, since ctx.hasUI throws
+// on a stale context.
+function notifyUi(ctx: ExtensionContext, message: string): void {
+	try {
+		if (ctx.hasUI) ctx.ui.notify(message, "warning");
+	} catch {
+		/* stale ctx — a cosmetic notice is not worth unwinding the handler */
+	}
 }
 
 /** "provider/id": slash at index > 0 with a non-empty id after it. */
@@ -228,7 +250,10 @@ export function registerOrchestratorFailover(pi: ExtensionAPI, getConfig: () =>
 		// cancelled run must NEVER fail over. Non-retryable errors (quota,
 		// billing, auth…) fail fast with no backoff to cancel, so they pass.
 		// SettingsManager.create is a synchronous, lock-protected read of the
-		// same merged settings pi uses.
+		// same merged settings pi uses. READ-ONLY, and it must stay that way: a
+		// setter call on this throwaway instance would write straight into the
+		// user's GLOBAL settings unmediated — every write goes through
+		// model-default.ts instead.
 		if (isRetryableAssistantError(msg as AssistantMessage)) {
 			try {
 				const retry = SettingsManager.create(ctx.cwd, getAgentDir(), {
@@ -248,31 +273,54 @@ export function registerOrchestratorFailover(pi: ExtensionAPI, getConfig: () =>
 		if (!mapped) return; // no mapping / unknown / unauthed → the original failure stands
 		const from = `${current.provider}/${current.id}`;
 		const to = `${mapped.provider}/${mapped.id}`;
-		try {
-			// pi.setModel returns false when no API key is available, but can ALSO
-			// throw on a failed live auth check despite the Promise<boolean>
-			// contract — handle both. NOTE: on success it persists the mapped model
-			// as the user's GLOBAL default (pi semantics; documented caveat).
-			if (!(await pi.setModel(mapped))) {
-				if (ctx.hasUI) {
-					ctx.ui.notify(`slate: model failover to ${to} skipped — no API key. Keeping ${from}.`, "warning");
+		// pi.setModel persists the switch into the user's GLOBAL settings
+		// (defaultProvider, defaultModel and, through its thinking cascade,
+		// defaultThinkingLevel) — a session-scoped failover must not leave that
+		// behind, so the switch runs inside the shared restore wrapper, which
+		// puts back exactly what THIS switch changed (model-default.ts).
+		// Sequencing matters: the wrapper completes the restore BEFORE the
+		// steer below, so settings are already clean even if the steer then
+		// fails on a stale context.
+		// Set when pi.setModel THREW: the throw can land after pi already wrote the
+		// pair (it persists before the thinking cascade and the model-select
+		// emission), so that case must still be treated as "may have persisted"
+		// even though the switch failed. Read by the predicate below, which runs
+		// after the callback has resolved.
+		let mayHaveWritten = false;
+		const switched = await withGlobalModelDefaultRestored(
+			pi,
+			ctx,
+			getConfig(),
+			mapped,
+			async () => {
+				try {
+					// pi.setModel returns false when no API key is available, but can ALSO
+					// throw on a failed live auth check despite the Promise<boolean>
+					// contract — handle both.
+					if (!(await pi.setModel(mapped))) {
+						reportFailure(ctx, `slate: model failover to ${to} skipped — no API key. Keeping ${from}.`);
+						return false;
+					}
+				} catch (error) {
+					mayHaveWritten = true;
+					reportFailure(
+						ctx,
+						`slate: model failover to ${to} failed — ${sanitizeForNotify(
+							error instanceof Error ? error.message : String(error),
+						)}. Keeping ${from}.`,
+					);
+					return false;
 				}
-				return;
-			}
-		} catch (error) {
-			if (ctx.hasUI) {
-				ctx.ui.notify(
-					`slate: model failover to ${to} failed — ${sanitizeForNotify(
-						error instanceof Error ? error.message : String(error),
-					)}. Keeping ${from}.`,
-					"warning",
-				);
-			}
-			return;
-		}
-		if (ctx.hasUI) {
-			ctx.ui.notify(`slate: model failover ${from} ⇒ ${to} — retrying the failed turn`, "warning");
-		}
+				return true;
+			},
+			// A plain false return means pi.setModel bailed on its own auth check
+			// BEFORE touching settings (the extension-facing setModel returns false
+			// ahead of the session setter), so nothing can have been persisted and
+			// the whole post-switch phase is skipped — unless it failed by THROWING.
+			(ok) => ok || mayHaveWritten,
+		);
+		if (!switched) return;
+		notifyUi(ctx, `slate: model failover ${from} ⇒ ${to} — retrying the failed turn`);
 		pi.sendMessage(
 			{
 				customType: "slate-failover",

package/extension/handoff.ts

@@ -41,6 +41,8 @@ import {
 	type ExtensionCommandContext,
 	type ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
+import { withGlobalModelDefaultRestored } from "./model-default.ts";
+import { sanitizeForNotify } from "./notify.ts";
 import {
 	orchestratorCostUsd,
 	type ContextBudgetObject,
@@ -93,13 +95,21 @@ function pendingFile(cwd: string): string {
 	return join(cwd, CONFIG_DIR_NAME, "slate", "pending-handoff.json");
 }
 
-// Strings from the pending file (and error messages derived from them) reach
-// ctx.ui.notify, and pi-tui renders control/ANSI codes verbatim — a seeded
-// pending file could inject terminal escapes. Strip control characters and
-// cap the length before display.
-function sanitizeForNotify(s: string, max = 120): string {
-	const clean = s.replace(/[\u0000-\u001f\u007f\u009b]/g, "");
-	return clean.length > max ? `${clean.slice(0, max)}…` : clean;
+// Console-first reporting for the model-adoption block below, and for FAILURES
+// ONLY: the console line is unconditional, so the failure surfaces in headless
+// runs and at teardown too — the has-UI branch is exactly the one that vanishes
+// there — and the UI notification is the extra. Informational notices (the
+// "handoff state restored" line, the pause notices) keep their plain has-UI
+// gate, since an unconditional stderr write scribbles pi-tui's differentially
+// rendered frame. ctx.hasUI is a getter that THROWS on a stale context, so it
+// is guarded: an unguarded check would be a crash, not a test.
+function reportFailure(ctx: ExtensionContext, message: string): void {
+	console.warn(message);
+	try {
+		if (ctx.hasUI) ctx.ui.notify(message, "warning");
+	} catch {
+		/* stale ctx — the console line above stands */
+	}
 }
 
 /**
@@ -283,7 +293,10 @@ export function registerSlateHandoff(
 	// pi's compaction reserve — read ONCE, lazily, then cached: it feeds a
 	// per-turn check and SettingsManager.create is a lock-protected disk read.
 	// A mid-session settings edit is not picked up (acceptable: the clamp is a
-	// safety margin, not an exact contract).
+	// safety margin, not an exact contract). READ-ONLY, and it must stay that
+	// way: a setter call on this throwaway instance would write straight into
+	// the user's GLOBAL settings unmediated — every write goes through
+	// model-default.ts instead.
 	let cachedReserveTokens: number | undefined;
 	const reserveTokens = (ctx: ExtensionContext): number => {
 		if (cachedReserveTokens === undefined) {
@@ -489,40 +502,70 @@ export function registerSlateHandoff(
 			) {
 				const { provider, id } = spec;
 				const label = sanitizeForNotify(`${provider}/${id}`);
-				try {
-					// Equality guard: setModel persists the model as the user's GLOBAL
-					// default as a side effect, so only call it when the fresh session
-					// actually resolved to something else.
-					let restored = ctx.model?.provider === provider && ctx.model?.id === id;
-					if (!restored) {
-						const model = ctx.modelRegistry.find(provider, id);
-						restored = !!model && (await pi.setModel(model));
-					}
-					if (restored) {
-						// Thinking level rides only on a matching/restored model, and only
-						// AFTER setModel (which re-derives thinking internally). Like
-						// setModel, setThinkingLevel persists to the user's ONE GLOBAL
-						// default thinking level (not a per-model value), so clamping the
-						// old level against an unrelated fallback model would persist
-						// garbage there. Non-strings are never passed on; pi clamps
-						// unknown string levels itself.
-						if (typeof pending.thinkingLevel === "string") pi.setThinkingLevel(pending.thinkingLevel);
-					} else if (ctx.hasUI) {
-						ctx.ui.notify(
-							`slate: could not restore model ${label} (unknown or no auth) — keeping the session default.`,
-							"warning",
-						);
-					}
-				} catch (error) {
-					if (ctx.hasUI) {
-						ctx.ui.notify(
-							`slate: could not restore model ${label} — ${sanitizeForNotify(
-								error instanceof Error ? error.message : String(error),
-							)}. Keeping the session default.`,
-							"warning",
-						);
-					}
-				}
+				// The WHOLE adoption block runs inside the shared restore wrapper, not
+				// just the setModel call: both setters persist into the user's GLOBAL
+				// settings, and this path can persist the thinking-level key ALONE when
+				// the equality guard below short-circuits the model setter — so the
+				// wrapper's yield and post-switch read must follow the LAST write here
+				// (model-default.ts).
+				await withGlobalModelDefaultRestored(
+					pi,
+					ctx,
+					getConfig(),
+					{ provider, id },
+					async () => {
+						// True once a pi setter has actually been CALLED — only then can pi
+						// have persisted anything, and only then does the wrapper need to do
+						// its post-switch work.
+						let calledSetter = false;
+						try {
+							// Equality guard: setModel persists the model as the user's GLOBAL
+							// default as a side effect, so only call it when the fresh session
+							// actually resolved to something else.
+							let restored = ctx.model?.provider === provider && ctx.model?.id === id;
+							if (!restored) {
+								const model = ctx.modelRegistry.find(provider, id);
+								if (model) {
+									calledSetter = true;
+									restored = await pi.setModel(model);
+								}
+							}
+							if (restored) {
+								// Thinking level rides only on a matching/restored model, and only
+								// AFTER setModel (which re-derives thinking internally). Like
+								// setModel, setThinkingLevel persists to the user's ONE GLOBAL
+								// default thinking level (not a per-model value), so clamping the
+								// old level against an unrelated fallback model would persist
+								// garbage there. Non-strings are never passed on; pi clamps
+								// unknown string levels itself.
+								if (typeof pending.thinkingLevel === "string") {
+									calledSetter = true;
+									pi.setThinkingLevel(pending.thinkingLevel);
+								}
+							} else {
+								reportFailure(
+									ctx,
+									`slate: could not restore model ${label} (unknown or no auth) — keeping the session default.`,
+								);
+							}
+						} catch (error) {
+							// A throw can land AFTER a completed write (pi persists the pair
+							// before the cascade that can throw), so this counts as "a setter
+							// ran" — the safe direction.
+							calledSetter = true;
+							reportFailure(
+								ctx,
+								`slate: could not restore model ${label} — ${sanitizeForNotify(
+									error instanceof Error ? error.message : String(error),
+								)}. Keeping the session default.`,
+							);
+						}
+						return calledSetter;
+					},
+					// No setter was called ⇒ pi cannot have written anything ⇒ skip the
+					// wrapper's post-switch reads, retries and reporting entirely.
+					(calledSetter) => calledSetter,
+				);
 			}
 		} catch {
 			/* a broken pending file must never break session start */