ytdb-slate 0.1.2 → 0.2.0

package/extension/handoff.ts

@@ -1,42 +1,87 @@
 /**
  * Auto-pause + handoff: context-budget discipline for the orchestrator.
  *
- * Monitoring: after every turn, when orchestrator mode is on and context usage
- * crosses pauseThresholdPercent (default 40), the store is paused — the thread
- * tool then rejects NEW dispatches (in-flight ones finish) — and the
- * orchestrator is steered to produce a handoff brief for the user.
+ * Monitoring: after every turn, when orchestrator mode is on and context
+ * usage crosses the absolute token budget (contextBudget; built-in defaults
+ * 256k tokens, 400k for anthropic/* models, clamped so the pause always
+ * lands with brief-writing room below pi's own compaction point), the store
+ * is paused — the thread tool then rejects NEW dispatches (in-flight ones
+ * finish) — and the orchestrator is steered to produce a handoff brief for
+ * the user. Threshold auto-compactions are intercepted the same way
+ * (session_before_compact → pause + cancel); once paused they pass through
+ * as the escape valve. The DEPRECATED pauseThresholdPercent keeps its exact
+ * legacy percent behavior (compaction untouched) when set WITHOUT
+ * contextBudget.
  *
  * /slate handoff [focus] → startHandoff(): captures the orchestrator's last
  * assistant message as the brief, writes <config dir>/slate/pending-handoff.json
- * (state snapshot + brief + parent session), and opens a fresh session.
+ * (state snapshot + brief + parent session + live model/thinking level), and
+ * opens a fresh session.
  *
  * Adoption: session replacement tears down this extension instance, so
  * in-memory state cannot cross over; and the fresh session's own file has no
  * slate-state entries for restore() to find (they live in the parent's file).
  * The pending file bridges the gap: the NEW instance's session_start handler
  * adopts the snapshot when the fresh session's parentSession header matches
- * (trusted projects only; stale files are reaped regardless of trust).
+ * (trusted projects only; stale files are reaped regardless of trust), and
+ * then restores the captured model/thinking level — the fresh session does
+ * not inherit them: startup CLI flags (-m/--thinking) are re-applied to the
+ * replacement runtime, enabledModels scoping picks its first entry, and a
+ * parent resumed with a non-default session-file model falls back to the
+ * settings default.
  */
 
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import {
 	CONFIG_DIR_NAME,
+	getAgentDir,
+	SettingsManager,
 	type ExtensionAPI,
 	type ExtensionCommandContext,
 	type ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
-import { orchestratorCostUsd, type SlateConfig, type SlateSnapshot, type SlateStore } from "./state.ts";
+import {
+	orchestratorCostUsd,
+	type ContextBudgetObject,
+	type ContextBudgetOverride,
+	type SlateConfig,
+	type SlateSnapshot,
+	type SlateStore,
+} from "./state.ts";
 
+/** Legacy percent mode only (DEPRECATED pauseThresholdPercent without contextBudget). */
 const DEFAULT_PAUSE_THRESHOLD_PERCENT = 40;
+/** Budget-mode default for models without a configured or built-in override. */
+const DEFAULT_CONTEXT_BUDGET_TOKENS = 256_000;
+/** Built-in override: anthropic/* models get a larger default budget. */
+const ANTHROPIC_DEFAULT_BUDGET_TOKENS = 400_000;
+const ANTHROPIC_MODEL_RE = /^anthropic\/.*/;
+/**
+ * Head-room subtracted (together with pi's compaction reserveTokens) from the
+ * context window when clamping the budget: the pause must land with enough
+ * room left for the orchestrator to WRITE the handoff brief before pi's own
+ * compaction point (contextWindow − reserveTokens).
+ */
+const BRIEF_HEADROOM_TOKENS = 32_768;
+/** Used when the merged settings cannot be read (mirrors pi's own default). */
+const FALLBACK_RESERVE_TOKENS = 16_384;
 /** A pending-handoff file older than this cannot belong to an in-flight handoff. */
 const PENDING_MAX_AGE_MS = 15 * 60 * 1000;
 const BRIEF_MAX_CHARS = 6000;
 
+// pi-coding-agent does not re-export ThinkingLevel (it lives in the transitive
+// pi-agent-core package, which is not one of our peer deps) — derive it.
+type ThinkingLevel = ReturnType<ExtensionAPI["getThinkingLevel"]>;
+
 interface PendingHandoff {
 	parentSession: string | undefined; // undefined = in-memory session; adoption then never matches
 	createdAt: number;
 	brief: string;
+	// Live model + thinking level at handoff time. Absent in old pending files
+	// and when the parent session had no model.
+	model?: { provider: string; id: string };
+	thinkingLevel?: ThinkingLevel;
 	snapshot: SlateSnapshot;
 }
 
@@ -48,6 +93,124 @@ 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;
+}
+
+/**
+ * Validate the raw `contextBudget` config value — eagerly, at session_start,
+ * for the same reason modelFailover is (failover.ts): a malformed budget
+ * would otherwise fail silently exactly when the auto-pause was supposed to
+ * save the orchestrator's context. Normalizes a bare number to { tokens }.
+ * Returns undefined for anything unusable — an INVALID contextBudget never
+ * disables a configured pauseThresholdPercent. `{}` is valid: an explicit
+ * opt-in to the built-in budget defaults.
+ */
+export function sanitizeContextBudget(raw: unknown, warn: (msg: string) => void): ContextBudgetObject | undefined {
+	if (raw === undefined) return undefined;
+	const isBudgetTokens = (v: unknown): v is number => typeof v === "number" && Number.isInteger(v) && v > 0;
+	if (typeof raw === "number") {
+		if (isBudgetTokens(raw)) return { tokens: raw };
+		warn(`slate: ignoring contextBudget — expected a positive integer token count, got ${raw}`);
+		return undefined;
+	}
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+		warn('slate: ignoring contextBudget — expected a token count or { "tokens": N, "overrides": [...] }');
+		return undefined;
+	}
+	const obj = raw as { tokens?: unknown; overrides?: unknown };
+	const result: ContextBudgetObject = {};
+	// CQ1: a typo like {"token": 50000} would otherwise silently fall back to
+	// the built-in defaults — surface unknown keys (they are user-edited
+	// slate.json content headed for ctx.ui.notify, so sanitize for display).
+	const unknownKeys = Object.keys(obj).filter((k) => k !== "tokens" && k !== "overrides");
+	if (unknownKeys.length > 0) {
+		warn(
+			`slate: ignoring unknown contextBudget key(s): ${sanitizeForNotify(unknownKeys.join(", "))} (known: "tokens", "overrides")`,
+		);
+	}
+	if (obj.tokens !== undefined) {
+		if (isBudgetTokens(obj.tokens)) result.tokens = obj.tokens;
+		// Dropping just the scalar keeps the object valid — the user still opted
+		// into budget mode, so built-in defaults apply rather than legacy percent.
+		// BG1: the value reaches ctx.ui.notify — sanitize like the sibling
+		// overrides path (a crafted string could inject ANSI/CSI codes).
+		else {
+			warn(
+				`slate: dropping contextBudget.tokens — expected a positive integer, got ${sanitizeForNotify(
+					JSON.stringify(obj.tokens),
+				)}`,
+			);
+		}
+	}
+	if (obj.overrides !== undefined) {
+		if (!Array.isArray(obj.overrides)) {
+			warn("slate: dropping contextBudget.overrides — expected an array");
+		} else {
+			const kept: ContextBudgetOverride[] = [];
+			const dropped: string[] = [];
+			for (const entry of obj.overrides as unknown[]) {
+				const o = entry as { match?: unknown; tokens?: unknown } | null;
+				let ok = typeof o?.match === "string" && o.match !== "" && isBudgetTokens(o.tokens);
+				if (ok) {
+					// Compile the exact ANCHORED form resolution uses at match time —
+					// validating the bare pattern would not prove the wrapped one compiles.
+					try {
+						new RegExp(`^(?:${o?.match as string})$`);
+					} catch {
+						ok = false;
+					}
+				}
+				if (ok) kept.push({ match: o?.match as string, tokens: o?.tokens as number });
+				// Entries come from user-edited slate.json and reach ctx.ui.notify —
+				// strip control/ANSI codes before display (same rationale as
+				// failover.ts's CQ1 comment; this round's BG1 fixed the sibling
+				// tokens path above to match).
+				else dropped.push(sanitizeForNotify(JSON.stringify(entry)));
+			}
+			if (dropped.length > 0) {
+				warn(
+					`slate: dropped invalid contextBudget.overrides entries (need a regex string "match" + positive integer "tokens"):\n` +
+						dropped.join("\n"),
+				);
+			}
+			if (kept.length > 0) result.overrides = kept;
+		}
+	}
+	return result;
+}
+
+/**
+ * BUDGET mode is active unless the config is percent-only: LEGACY iff
+ * pauseThresholdPercent is set AND no valid contextBudget survived
+ * sanitization (both fields pass through session_start's eager sanitize
+ * before any config reaches this module via getConfig()).
+ */
+function budgetModeActive(config: SlateConfig): boolean {
+	return config.contextBudget !== undefined || config.pauseThresholdPercent === undefined;
+}
+
+/**
+ * Resolve the budget for one "provider/id" spec. Lattice: first matching
+ * user override → user scalar → built-in anthropic rule → global default.
+ * Runs against the LIVE model on EVERY check — failover, /model, and handoff
+ * restore can all swap models mid-session, so the result is never cached.
+ */
+function resolveBudgetTokens(budget: ContextBudgetObject | undefined, modelSpec: string): number {
+	for (const o of budget?.overrides ?? []) {
+		// The sanitizer verified this exact anchored form compiles.
+		if (new RegExp(`^(?:${o.match})$`).test(modelSpec)) return o.tokens;
+	}
+	if (budget?.tokens !== undefined) return budget.tokens;
+	if (ANTHROPIC_MODEL_RE.test(modelSpec)) return ANTHROPIC_DEFAULT_BUDGET_TOKENS;
+	return DEFAULT_CONTEXT_BUDGET_TOKENS;
+}
+
 /** Last assistant message text on the current branch (the handoff brief). */
 function lastAssistantText(ctx: ExtensionCommandContext): string {
 	let text = "";
@@ -117,45 +280,151 @@ export function registerSlateHandoff(
 	store: SlateStore,
 	getConfig: () => SlateConfig,
 ): SlateHandoffHooks {
+	// 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).
+	let cachedReserveTokens: number | undefined;
+	const reserveTokens = (ctx: ExtensionContext): number => {
+		if (cachedReserveTokens === undefined) {
+			try {
+				cachedReserveTokens = SettingsManager.create(ctx.cwd, getAgentDir(), {
+					projectTrusted: ctx.isProjectTrusted(),
+				}).getCompactionReserveTokens();
+			} catch {
+				cachedReserveTokens = FALLBACK_RESERVE_TOKENS;
+			}
+		}
+		return cachedReserveTokens;
+	};
+
+	/** Handoff instructions shared by both pause sites (turn check + compaction intercept). */
+	const pauseInstructions = (headline: string) =>
+		[
+			headline,
+			"Finish nothing new. Reply to the user with:",
+			"(1) a concise HANDOFF BRIEF — overall goal, per-thread state with episode ids, immediate next actions;",
+			"(2) instructions: run /slate handoff [optional focus] to continue in a fresh session where all threads and episodes are restored automatically;",
+			`alternatively, start a new pi session manually, run /slate on, and have the new orchestrator read the episode files under ${CONFIG_DIR_NAME}/slate/episodes/.`,
+		].join("\n");
+
 	const checkBudget = (ctx: ExtensionContext) => {
 		if (!store.orchestratorMode || store.paused) return;
-		const percent = ctx.getContextUsage()?.percent;
-		if (percent == null) return;
-		// slate.json is user-edited: accept only finite (0, 100] thresholds.
-		const configured = getConfig().pauseThresholdPercent;
-		const threshold =
-			typeof configured === "number" && Number.isFinite(configured) && configured > 0 && configured <= 100
-				? configured
-				: DEFAULT_PAUSE_THRESHOLD_PERCENT;
-		if (percent < threshold) return;
+		const config = getConfig();
+		let notifyText: string;
+		let headline: string;
+		if (!budgetModeActive(config)) {
+			// LEGACY percent mode (DEPRECATED pauseThresholdPercent, no contextBudget).
+			const percent = ctx.getContextUsage()?.percent;
+			if (percent == null) return;
+			// slate.json is user-edited: accept only finite (0, 100] thresholds.
+			const configured = config.pauseThresholdPercent;
+			const threshold =
+				typeof configured === "number" && Number.isFinite(configured) && configured > 0 && configured <= 100
+					? configured
+					: DEFAULT_PAUSE_THRESHOLD_PERCENT;
+			if (percent < threshold) return;
+			const pct = Math.round(percent);
+			notifyText = `slate: context at ${pct}% (budget ${threshold}%) — paused. Run /slate handoff [focus] to continue in a fresh session.`;
+			headline = `[slate] Context is at ${pct}% — over the ${threshold}% budget. Slate auto-paused: the thread tool now REJECTS new dispatches.`;
+		} else {
+			// BUDGET mode: absolute token budget resolved against the LIVE model.
+			const usage = ctx.getContextUsage();
+			// tokens is null right after compaction, before the next LLM response.
+			if (usage?.tokens == null) return;
+			if (!ctx.model) return;
+			// sanitizeContextBudget (session_start) normalized any bare number to
+			// { tokens }; the inline conversion is belt-and-braces for the type.
+			const budget = config.contextBudget;
+			const configured = resolveBudgetTokens(
+				typeof budget === "number" ? { tokens: budget } : budget,
+				`${ctx.model.provider}/${ctx.model.id}`,
+			);
+			// Clamp to the window: the pause must fire BEFORE pi's compaction point
+			// (contextWindow − reserveTokens) with room to write the brief — but
+			// never below half the window, so a small-window model still gets a
+			// usable orchestrator instead of a near-zero effective budget.
+			// (usage.contextWindow > 0 is guaranteed: getContextUsage returns
+			// undefined when no window is known.)
+			const effective = Math.min(
+				configured,
+				Math.max(usage.contextWindow - reserveTokens(ctx) - BRIEF_HEADROOM_TOKENS, Math.ceil(usage.contextWindow / 2)),
+			);
+			if (usage.tokens < effective) return;
+			const used = usage.tokens.toLocaleString("en-US");
+			const cap = effective.toLocaleString("en-US");
+			// CQ2: when the clamp engaged, the effective number alone is
+			// untraceable to the configured budget — name both, so "budget
+			// 150,848" against a configured 500,000 explains itself. Phrasing is
+			// unchanged when no clamping occurred.
+			const clampNote =
+				effective < configured
+					? ` (configured ${configured.toLocaleString("en-US")}, clamped for this model's context window)`
+					: "";
+			notifyText = `slate: context at ${used} tokens (budget ${cap}${clampNote}) — paused. Run /slate handoff [focus] to continue in a fresh session.`;
+			headline = `[slate] Context is at ${used} tokens — over the ${cap}-token budget${clampNote}. Slate auto-paused: the thread tool now REJECTS new dispatches.`;
+		}
+
+		store.paused = true;
+		store.save();
+		if (ctx.hasUI) ctx.ui.notify(notifyText, "warning");
+		pi.sendMessage(
+			{ customType: "slate-pause", content: pauseInstructions(headline), display: true },
+			{ deliverAs: "steer", triggerTurn: true },
+		);
+	};
+
+	pi.on("turn_end", async (_event, ctx) => checkBudget(ctx));
+	pi.on("agent_end", async (_event, ctx) => checkBudget(ctx));
 
+	// Threshold auto-compaction intercept: compaction pressure on an unpaused
+	// orchestrator means the budget failed to fire first (mis-sized override,
+	// low compaction threshold, …) — the right response is still pause +
+	// handoff, not a silent compaction that would shred the weave the episodes
+	// encode. BUDGET mode only: percent-only configs keep today's behavior
+	// end-to-end, compaction included. Manual /compact and overflow recovery
+	// always pass through (the user asked / pi is un-wedging a stuck turn).
+	pi.on("session_before_compact", async (event, ctx) => {
+		// !paused is the escape valve: once paused, later threshold compactions
+		// run normally — context that keeps growing must not wedge the session.
+		if (!store.orchestratorMode || store.paused) return;
+		if (!budgetModeActive(getConfig())) return;
+		if (event.reason !== "threshold") return;
 		store.paused = true;
 		store.save();
-		const pct = Math.round(percent);
 		if (ctx.hasUI) {
 			ctx.ui.notify(
-				`slate: context at ${pct}% (budget ${threshold}%) — paused. Run /slate handoff [focus] to continue in a fresh session.`,
+				"slate: auto-compaction intercepted — paused instead. Run /slate handoff [focus] to continue in a fresh session.",
 				"warning",
 			);
 		}
+		// deliverAs "steer" WITHOUT triggerTurn (CN1/CN2/CN3) — traced against
+		// BOTH pi call sites of session_before_compact (agent-session.js):
+		//  - post-run site (_handlePostAgentRun → _checkCompaction), streaming:
+		//    the steer queues on the agent; _handlePostAgentRun then sees
+		//    hasQueuedMessages() and continues the run, so the model writes the
+		//    handoff brief THIS settle — before the escape-valve compaction can
+		//    fire (CN2) and before a user steer slips in uninstructed (CN3).
+		//  - idle pre-prompt site (prompt() preflight), not streaming: the
+		//    message is appended directly to state/session and rides into the
+		//    imminent turn — no turn starts. triggerTurn stays OFF: a
+		//    triggering send at this site is what would start a nested agent
+		//    run (the original hazard was triggerTurn specifically).
+		// Unlike "nextTurn" (an unretractable _pendingNextTurnMessages queue
+		// that survives /slate resume — CN1), a steer lands in the transcript
+		// at pause time; the disregard clause below is defense in depth.
 		pi.sendMessage(
 			{
 				customType: "slate-pause",
-				content: [
-					`[slate] Context is at ${pct}% — over the ${threshold}% budget. Slate auto-paused: the thread tool now REJECTS new dispatches.`,
-					"Finish nothing new. Reply to the user with:",
-					"(1) a concise HANDOFF BRIEF — overall goal, per-thread state with episode ids, immediate next actions;",
-					"(2) instructions: run /slate handoff [optional focus] to continue in a fresh session where all threads and episodes are restored automatically;",
-					`alternatively, start a new pi session manually, run /slate on, and have the new orchestrator read the episode files under ${CONFIG_DIR_NAME}/slate/episodes/.`,
-				].join("\n"),
+				content: `${pauseInstructions(
+					"[slate] pi hit its auto-compaction threshold; slate cancelled the compaction and auto-paused instead: the thread tool now REJECTS new dispatches. (While paused, a repeat compaction passes through as the escape valve.)",
+				)}\n(If slate has since been resumed or unpaused, disregard this message.)`,
 				display: true,
 			},
-			{ deliverAs: "steer", triggerTurn: true },
+			{ deliverAs: "steer" },
 		);
-	};
-
-	pi.on("turn_end", async (_event, ctx) => checkBudget(ctx));
-	pi.on("agent_end", async (_event, ctx) => checkBudget(ctx));
+		return { cancel: true };
+	});
 
 	// Adopt a pending handoff into a fresh session. Registered AFTER index.ts's
 	// restore handler (so a branch that already carries slate state wins) and
@@ -170,7 +439,10 @@ export function registerSlateHandoff(
 			// STALE reap runs regardless of trust: it deletes an abandoned runtime
 			// file without injecting any content into prompts or state, and keeps
 			// the file from lingering forever in a never-trusted project.
-			if (age >= PENDING_MAX_AGE_MS) {
+			// Out-of-range timestamps are stale too: a future createdAt (negative
+			// age) or a non-numeric one (NaN age) would otherwise dodge the reap
+			// forever — a real in-flight handoff is at most minutes old.
+			if (!(age >= 0 && age < PENDING_MAX_AGE_MS)) {
 				rmSync(file, { force: true });
 				return;
 			}
@@ -194,6 +466,64 @@ export function registerSlateHandoff(
 					"info",
 				);
 			}
+			// Restore the parent's live model + thinking level. The fresh session
+			// does not inherit them: startup CLI flags (-m/--thinking) are
+			// re-applied to the replacement runtime, enabledModels scoping picks
+			// its first entry, and a parent resumed with a non-default
+			// session-file model falls back to the settings default. This sits
+			// AFTER the adoption commit above, in its own try/catch, because
+			// pi.setModel can THROW on a failed live auth check despite its
+			// Promise<boolean> contract — a restore failure must never unwind a
+			// committed adoption.
+			// The pending file is disk JSON: honor the captured model only as an
+			// object with non-empty string provider/id — a malformed {"model":{}}
+			// must not count as "already live" via undefined === undefined.
+			const spec = pending.model;
+			if (
+				typeof spec === "object" &&
+				spec !== null &&
+				typeof spec.provider === "string" &&
+				spec.provider !== "" &&
+				typeof spec.id === "string" &&
+				spec.id !== ""
+			) {
+				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",
+						);
+					}
+				}
+			}
 		} catch {
 			/* a broken pending file must never break session start */
 		}
@@ -204,10 +534,16 @@ export function registerSlateHandoff(
 
 		const brief = lastAssistantText(ctx);
 		const parentSession = ctx.sessionManager.getSessionFile();
+		// ctx.model can be undefined (no-model session): capture neither field
+		// then — a thinking level is meaningless without a model to clamp it
+		// against, and adoption skips the whole restore when model is absent.
+		const model = ctx.model ? { provider: ctx.model.provider, id: ctx.model.id } : undefined;
 		const pending: PendingHandoff = {
 			parentSession,
 			createdAt: Date.now(),
 			brief,
+			model,
+			thinkingLevel: model ? pi.getThinkingLevel() : undefined,
 			// The successor starts unpaused and in orchestrator mode regardless of
 			// the current (paused) state.
 			snapshot: {

package/extension/index.ts

@@ -14,24 +14,33 @@
  *   episodes.ts — episode compression (Sonnet-default, D5)
  *   threads.ts  — ThreadManager: queueing, dispatch lifecycle
  *   tools.ts    — thread / threads / episode tools
- *   handoff.ts  — context-budget auto-pause + fresh-session handoff
+ *   handoff.ts  — absolute-token context-budget auto-pause (with threshold-
+ *                 compaction intercept) + fresh-session handoff
  *
  * Optional config at <config dir>/slate.json (config dir = CONFIG_DIR_NAME,
  * ".pi" by default), honored ONLY when the project is trusted — untrusted
  * projects run on built-in defaults with no project file injection:
  *   { "episodeModel": "provider/id", "workerTools": [...], "maxConcurrent": 4,
- *     "pauseThresholdPercent": 40, "orchestratorModeDefault": true,
+ *     "contextBudget": 256000, "orchestratorModeDefault": true,
  *     "orchestratorPromptDocs": ["docs/orchestrator-guidelines.md"],
  *     "workerPromptDocs": ["docs/thread-guidelines.md"],
  *     "workflow": { "draftPRs": false },
+ *     "modelFailover": { "provider/id": "provider/id" },
  *     "doctrineExtraPath": "docs/project-doctrine.md",
  *     "reviewPerspectivesPath": "docs/review-perspectives.md" }
+ * 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
+ * pauseThresholdPercent keeps its legacy percent behavior only when it is set
+ * AND contextBudget is absent or entirely invalid (invalid sanitizes to
+ * absent — a partially invalid object stays budget mode).
  */
 
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { CONFIG_DIR_NAME, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { registerSlateHandoff } from "./handoff.ts";
+import { registerOrchestratorFailover, sanitizeModelFailover } from "./failover.ts";
+import { registerSlateHandoff, sanitizeContextBudget } from "./handoff.ts";
 import { registerSlateMode } from "./mode.ts";
 import { SlateStore, type SlateConfig } from "./state.ts";
 import { ThreadManager } from "./threads.ts";
@@ -66,7 +75,17 @@ export default function (pi: ExtensionAPI) {
 		manager.disposeAll();
 		// Trust gate: project config steers prompts, models, and tool lists, so
 		// it is honored only for trusted projects; untrusted → built-in defaults.
-		manager = new ThreadManager(store, ctx.isProjectTrusted() ? loadConfig(ctx.cwd) : {});
+		const config = ctx.isProjectTrusted() ? loadConfig(ctx.cwd) : {};
+		const warn = (msg: string) => (ctx.hasUI ? ctx.ui.notify(msg, "warning") : console.warn(msg));
+		// modelFailover and contextBudget are validated eagerly: a malformed
+		// value would otherwise fail silently mid-dispatch / exactly when the
+		// auto-pause was supposed to save the orchestrator's context.
+		config.modelFailover = sanitizeModelFailover(config.modelFailover, warn);
+		config.contextBudget = sanitizeContextBudget(config.contextBudget, warn);
+		if (config.contextBudget !== undefined && config.pauseThresholdPercent !== undefined) {
+			warn("slate: contextBudget is set — the deprecated pauseThresholdPercent is ignored");
+		}
+		manager = new ThreadManager(store, config);
 		store.restore(ctx);
 	});
 
@@ -80,5 +99,9 @@ export default function (pi: ExtensionAPI) {
 	// getConfig reads the CURRENT `manager` (reassigned on session_start).
 	const handoff = registerSlateHandoff(pi, store, () => manager.getConfig());
 
+	// Orchestrator model failover (turn_end/agent_settled/input) — not
+	// order-critical relative to the handlers above (different trigger events).
+	registerOrchestratorFailover(pi, () => manager.getConfig());
+
 	registerSlateMode(pi, store, handoff, () => manager.getConfig());
 }

package/extension/state.ts

@@ -42,15 +42,28 @@ export interface SlateSnapshot {
 	carriedCostUsd: number; // orchestrator spend banked from ancestor sessions at handoff
 }
 
+/** One contextBudget override. `match` is a regex tested ANCHORED (^(?:match)$) against "provider/id". */
+export interface ContextBudgetOverride {
+	match: string;
+	tokens: number;
+}
+
+export interface ContextBudgetObject {
+	tokens?: number; // absolute token budget for models not caught by an override
+	overrides?: ContextBudgetOverride[]; // first matching entry wins
+}
+
 export interface SlateConfig {
 	episodeModel?: string; // "provider/id" for the episode compressor (D5)
 	workerTools?: string[];
 	maxConcurrent?: number; // global cap on concurrently running worker actions (default 4; must be ≥ 1 — unenforced, ≤ 0 silently hangs all dispatches; rationale: docs/design-principles.md §5 repo-local note)
-	pauseThresholdPercent?: number; // orchestrator context budget for auto-pause (default 40)
+	pauseThresholdPercent?: number; // DEPRECATED: legacy percent-based auto-pause (default 40); applies only when set AND contextBudget is absent or entirely invalid (invalid sanitizes to absent — a partially invalid object stays budget mode)
+	contextBudget?: number | ContextBudgetObject; // absolute orchestrator token budget; bare number = { tokens: N }; {} opts into built-in defaults (256k, 400k for anthropic/*) — see handoff.ts
 	orchestratorModeDefault?: boolean; // seed orchestrator mode ON for fresh interactive sessions (unsaved until first real mutation)
 	orchestratorPromptDocs?: string[]; // role-guideline docs appended to the orchestrator prompt (cwd-relative paths, default none)
 	workerPromptDocs?: string[]; // role-guideline docs appended to worker system prompts (cwd-relative paths, default none)
 	workflow?: { draftPRs?: boolean }; // draftPRs: umbrella draft PRs are part of the pre-implementation gates (default false)
+	modelFailover?: Record<string, string>; // model→model failover map ("provider/id" → "provider/id"); empty/absent = feature off
 	doctrineExtraPath?: string; // cwd-relative markdown appended to the orchestrator doctrine (project-doctrine section)
 	reviewPerspectivesPath?: string; // cwd-relative markdown with additional project-specific review perspectives
 }