pi-subagents 0.52.1 → 0.54.0

package/src/runs/foreground/workflow-detach-reconcile.ts

@@ -1,7 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { writeAtomicJson } from "../../shared/atomic-json.ts";
-import { isStorageCapacityError } from "../../shared/file-system-retry.ts";
 import { getSingleResultOutput, readStatus } from "../../shared/utils.ts";
 import {
 	DIRS,
@@ -13,6 +12,8 @@ import {
 } from "../../shared/types.ts";
 import { updateActiveRunIndex } from "../background/active-run-index.ts";
 import { resultFilePath, writeAsyncResultFile } from "../background/result-files.ts";
+import { resolveAsyncResumeTarget } from "../background/async-resume.ts";
+import { readWorkflowReceipt, workflowReceiptPath, writeWorkflowReceipt, type WorkflowReceipt } from "../../workflows/workflow-receipt.ts";
 
 function cloneWorkflowStatus(status: AsyncStatus): AsyncStatus {
 	return {
@@ -97,7 +98,7 @@ function workflowResultChildren(status: AsyncStatus, childRunId: string, result:
 	}));
 }
 
-function publishedWorkflowResult(status: AsyncStatus, childRunId: string, result: SingleResult, asyncDir: string, existing?: Record<string, unknown>): Record<string, unknown> {
+function publishedWorkflowResult(status: AsyncStatus, childRunId: string, result: SingleResult, asyncDir: string, existing?: Record<string, unknown>, receipt?: WorkflowReceipt): Record<string, unknown> {
 	const sessionId = status.sessionId ?? (typeof existing?.sessionId === "string" ? existing.sessionId : undefined);
 	const summary = status.state === "complete"
 		? `Workflow completed after detached child ${childRunId} finished.`
@@ -118,6 +119,7 @@ function publishedWorkflowResult(status: AsyncStatus, childRunId: string, result
 		timestamp: Date.now(),
 		results: workflowResultChildren(status, childRunId, result, existing?.results),
 		workflow: status.workflow,
+		...(receipt ? { workflowReceipt: { path: path.join(asyncDir, "workflow-receipt.json"), receipt } } : {}),
 		asyncDir,
 		cwd: status.cwd,
 		sessionId,
@@ -125,6 +127,60 @@ function publishedWorkflowResult(status: AsyncStatus, childRunId: string, result
 	};
 }
 
+function reconcileWorkflowReceipt(status: AsyncStatus, childRunId: string, result: SingleResult, asyncDir: string): WorkflowReceipt | undefined {
+	const receiptPath = workflowReceiptPath(DIRS.async, status.runId);
+	if (!fs.existsSync(receiptPath)) return undefined;
+	const receipt = readWorkflowReceipt(DIRS.async, status.runId);
+	const step = status.steps?.find((candidate) => candidate.runId === childRunId);
+	const key = step?.workflowKey;
+	if (!key) throw new Error(`Workflow receipt '${status.runId}' cannot identify detached child '${childRunId}' by stable key.`);
+	const entry = receipt.entries[key];
+	if (!entry) throw new Error(`Workflow receipt '${status.runId}' has no detached child key '${key}'.`);
+	let resumability: typeof entry.resumability;
+	try {
+		const target = resolveAsyncResumeTarget({ id: childRunId, dir: path.join(DIRS.async, childRunId) }, {}, { requireSessionFile: true, sessionId: status.sessionId });
+		resumability = target.kind === "revive" ? { state: "resumable" } : { state: "not-resumable", reason: "child is still running" };
+	} catch (error) {
+		resumability = { state: "not-resumable", reason: error instanceof Error ? error.message : String(error) };
+	}
+	const outputReference = result.savedOutputPath ?? result.outputReference?.path ?? entry.outputReference;
+	const updatedEntry: WorkflowReceipt["entries"][string] = resumability.state === "resumable"
+		? {
+			...entry,
+			...(step.agent ? { agent: step.agent } : {}),
+			...(step.context ? { resolvedContext: step.context } : {}),
+			latestRunId: entry.latestRunId ?? childRunId,
+			resumability,
+			...(outputReference ? { outputReference } : {}),
+		}
+		: {
+			...entry,
+			...(step.agent ? { agent: step.agent } : {}),
+			...(step.context ? { resolvedContext: step.context } : {}),
+			resumability,
+			...(outputReference ? { outputReference } : {}),
+		};
+	const next: WorkflowReceipt = {
+		...receipt,
+		state: status.state === "complete" ? "complete" : status.state === "stopped" ? "stopped" : status.state === "paused" ? "paused" : "failed",
+		entries: {
+			...receipt.entries,
+			[key]: updatedEntry,
+		},
+	};
+	writeWorkflowReceipt(asyncDir, next);
+	return next;
+}
+
+function appendDetachedWorkflowEvent(asyncDir: string, event: Record<string, unknown>): void {
+	const eventsPath = path.join(asyncDir, "events.jsonl");
+	try {
+		fs.appendFileSync(eventsPath, `${JSON.stringify(event)}\n`, "utf-8");
+	} catch (error) {
+		console.error(`Failed to append detached workflow event '${eventsPath}':`, error);
+	}
+}
+
 export function reconcileDetachedWorkflowChildCompletion(input: {
 	state: SubagentState;
 	workflowRunId: string;
@@ -160,21 +216,33 @@ export function reconcileDetachedWorkflowChildCompletion(input: {
 	} catch (error) {
 		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
 	}
-	const published = publishedWorkflowResult(next, input.childRunId, input.result, asyncDir, existing);
+	let receipt: WorkflowReceipt | undefined;
+	let receiptError: string | undefined;
+	try {
+		receipt = reconcileWorkflowReceipt(next, input.childRunId, input.result, asyncDir);
+	} catch (error) {
+		receiptError = `Failed to reconcile async workflow receipt: ${error instanceof Error ? error.message : String(error)}`;
+	}
+	const published = publishedWorkflowResult(next, input.childRunId, input.result, asyncDir, existing, receipt);
 	writeAsyncResultFile(resultPath, published);
+	if (receiptError) {
+		appendDetachedWorkflowEvent(asyncDir, {
+			ts: Date.now(),
+			runId: input.workflowRunId,
+			type: "subagent.workflow.receipt_write_failed",
+			error: receiptError,
+			reconciledFromDetachedChild: input.childRunId,
+		});
+	}
 	if (next.state === "complete" || next.state === "failed") {
-		try {
-			fs.appendFileSync(path.join(asyncDir, "events.jsonl"), `${JSON.stringify({
-				ts: Date.now(),
-				runId: input.workflowRunId,
-				type: "subagent.workflow.completed",
-				state: next.state,
-				...(next.error ? { error: next.error } : {}),
-				reconciledFromDetachedChild: input.childRunId,
-			})}\n`, "utf-8");
-		} catch (error) {
-			if (!isStorageCapacityError(error)) throw error;
-		}
+		appendDetachedWorkflowEvent(asyncDir, {
+			ts: Date.now(),
+			runId: input.workflowRunId,
+			type: "subagent.workflow.completed",
+			state: next.state,
+			...(next.error ? { error: next.error } : {}),
+			reconciledFromDetachedChild: input.childRunId,
+		});
 		input.events?.emit(SUBAGENT_ASYNC_COMPLETE_EVENT, {
 			id: input.workflowRunId,
 			runId: input.workflowRunId,

package/src/runs/shared/acceptance.ts

@@ -1140,6 +1140,49 @@ async function runMemoizedVerifyCommand(command: AcceptanceVerifyCommand, defaul
 	return evidenced;
 }
 
+/**
+ * On Windows with `shell: true`, cmd.exe parses the command line itself and an
+ * unquoted executable path containing spaces (e.g. `C:\Program Files\...\tool.exe`)
+ * is split at the first space, so cmd tries to run `C:\Program` and fails.
+ *
+ * The command line is ambiguous, so only an unquoted absolute drive path with
+ * a space in a directory component is safe to identify as an executable. That
+ * path is quoted; everything after it is preserved as arguments.
+ *
+ * Commands that already start with a quote, single-token commands, and commands
+ * whose first token already ends in an executable extension are returned
+ * unchanged. Non-Windows platforms pass the command through untouched.
+ */
+export function quoteExecutableForShell(command: string, platform: string = process.platform): string {
+	if (platform !== "win32") return command;
+	const trimmed = command.trimStart();
+	if (trimmed.startsWith("\"")) return command;
+	const firstToken = trimmed.match(/^\S+/)?.[0];
+	if (/\.(?:exe|bat|cmd|com|ps1)$/i.test(firstToken ?? "")) return command;
+	const match = trimmed.match(/^([A-Za-z]:\\[^"<>|&*?\r\n]*?\s[^"<>|&*?\r\n]*?\\[^"<>|&*?\r\n]*?\.(?:exe|bat|cmd|com|ps1))(?=\s|$)/i);
+	const executable = match?.[1];
+	if (executable && /\s/.test(executable) && !/[A-Za-z]:\\/.test(executable.slice(3))) {
+		const rest = trimmed.slice(executable.length);
+		const leading = command.slice(0, command.length - trimmed.length);
+		return `${leading}"${executable}"${rest}`;
+	}
+	const extensionlessSpacedFilenameMatch = trimmed.match(/^([A-Za-z]:\\[^"<>|&*?\r\n]*?\s[^"<>|&*?\r\n]*?)(?=\s+--|$)/i);
+	const extensionlessSpacedFilename = extensionlessSpacedFilenameMatch?.[1];
+	if (extensionlessSpacedFilename && /\s/.test(extensionlessSpacedFilename.slice(0, extensionlessSpacedFilename.lastIndexOf("\\"))) && !/[A-Za-z]:\\/.test(extensionlessSpacedFilename.slice(3))) {
+		const rest = trimmed.slice(extensionlessSpacedFilename.length);
+		const leading = command.slice(0, command.length - trimmed.length);
+		return `${leading}"${extensionlessSpacedFilename}"${rest}`;
+	}
+	const extensionlessMatch = trimmed.match(/^([A-Za-z]:\\[^"<>|&*?\r\n]*?\s[^"<>|&*?\r\n]*?\\[^"<>|&*?\s\r\n]+)(?=\s|$)/i);
+	const extensionlessExecutable = extensionlessMatch?.[1];
+	if (extensionlessExecutable && /\s/.test(extensionlessExecutable) && !/[A-Za-z]:\\/.test(extensionlessExecutable.slice(3)) && !/\s/.test(extensionlessExecutable.slice(extensionlessExecutable.lastIndexOf("\\") + 1))) {
+		const rest = trimmed.slice(extensionlessExecutable.length);
+		const leading = command.slice(0, command.length - trimmed.length);
+		return `${leading}"${extensionlessExecutable}"${rest}`;
+	}
+	return command;
+}
+
 function runVerifyCommand(command: AcceptanceVerifyCommand, defaultCwd: string, options: { signal?: AbortSignal; abortMessage?: string } = {}): Promise<AcceptanceVerifyResult> {
 	return new Promise((resolve) => {
 		const startedAt = Date.now();
@@ -1149,7 +1192,7 @@ function runVerifyCommand(command: AcceptanceVerifyCommand, defaultCwd: string,
 		let timedOut = false;
 		let settled = false;
 		let hardKill: NodeJS.Timeout | undefined;
-		const child = spawn(command.command, {
+		const child = spawn(quoteExecutableForShell(command.command), {
 			cwd,
 			env: effectiveVerifyEnv(command.env),
 			shell: true,

package/src/runs/shared/model-exclusions.ts

@@ -0,0 +1,242 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { TEMP_ROOT_DIR } from "../../shared/types.ts";
+
+export const EXCLUSIONS_PATH_ENV = "PI_MODEL_EXCLUSIONS_PATH";
+
+type ModelExclusionTarget = { modelId: string; provider?: string } | { provider: string; modelId?: never };
+
+export type ModelExclusion = ModelExclusionTarget & {
+	reason?: string;
+	recordedAt: number;
+	expiresAt: number;
+};
+
+type RecordModelFailureOptions = ModelExclusionTarget & {
+	reason?: string;
+	ttlMs?: number;
+};
+
+let exclusions: ModelExclusion[] = [];
+let loaded = false;
+let defaultTTLMs = 24 * 60 * 60_000; // 24 hours, overridable via setDefaultTTL
+let persistTimer: ReturnType<typeof setTimeout> | null = null;
+let persistSeq = 0;
+
+/** Override the default exclusion TTL. */
+export function setDefaultTTL(ms: number): void {
+	if (!Number.isFinite(ms) || ms <= 0) throw new Error("Default model exclusion TTL must be a finite positive number.");
+	defaultTTLMs = ms;
+}
+
+/**
+ * Resolve the persistence path. Honors PI_MODEL_EXCLUSIONS_PATH; defaults to
+ * <TEMP_ROOT_DIR>/model-exclusions.json. Resolved lazily so tests can point the
+ * store at an isolated location after module load.
+ */
+export function getExclusionsFilePath(): string {
+	const envPath = process.env[EXCLUSIONS_PATH_ENV];
+	if (typeof envPath === "string" && envPath.trim()) return envPath.trim();
+	return path.join(TEMP_ROOT_DIR, "model-exclusions.json");
+}
+
+/**
+ * Persist exclusions to disk immediately (atomic write via tmp + rename).
+ * The store otherwise debounces writes; call this when durability matters
+ * (and in tests).
+ */
+export function flushPersist(): void {
+	const file = getExclusionsFilePath();
+	try {
+		fs.mkdirSync(path.dirname(file), { recursive: true });
+		const tmpPath = `${file}.${process.pid}.${persistSeq++}.tmp`;
+		fs.writeFileSync(tmpPath, JSON.stringify({
+			version: 1,
+			exclusions: deduplicate(exclusions),
+		}, null, 2), "utf-8");
+		fs.renameSync(tmpPath, file);
+	} catch (error) {
+		console.error(`[model-exclusions] Failed to persist exclusions to ${file}:`, error);
+	}
+}
+
+function schedulePersist(): void {
+	if (persistTimer) clearTimeout(persistTimer);
+	persistTimer = setTimeout(() => {
+		persistTimer = null;
+		flushPersist();
+	}, 5000);
+	// Never hold the process open just to flush exclusions.
+	persistTimer.unref?.();
+}
+
+function ensureLoaded(): void {
+	if (loaded) return;
+	loaded = true;
+	try {
+		const raw = fs.readFileSync(getExclusionsFilePath(), "utf-8");
+		const data = JSON.parse(raw);
+		if (data.version === 1) {
+			const now = Date.now();
+			exclusions = (data.exclusions ?? []).filter((e: ModelExclusion) => e.expiresAt > now);
+			exclusions = deduplicate(exclusions);
+		}
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+			console.error(`[model-exclusions] Failed to load exclusions from ${getExclusionsFilePath()}:`, error);
+		}
+	}
+}
+
+function dedupKey(entry: ModelExclusion): string {
+	return `${entry.provider ?? ""}|${entry.modelId ?? ""}`;
+}
+
+function deduplicate(items: ModelExclusion[]): ModelExclusion[] {
+	const map = new Map<string, ModelExclusion>();
+	for (const entry of items) {
+		const key = dedupKey(entry);
+		const existing = map.get(key);
+		if (!existing || entry.recordedAt > existing.recordedAt) {
+			map.set(key, entry);
+		}
+	}
+	return Array.from(map.values());
+}
+
+/**
+ * Record a model failure as a temporary exclusion. While the exclusion is
+ * active, {@link isExcluded} returns true for the model (or for every model of
+ * the provider when modelId is omitted), and {@link filterFallbackCandidates}
+ * removes matching candidates from fallback lists.
+ */
+export function recordModelFailure(options: RecordModelFailureOptions): void {
+	ensureLoaded();
+	const ttl = options.ttlMs ?? defaultTTLMs;
+	const now = Date.now();
+	const target: ModelExclusionTarget = options.modelId !== undefined
+		? { modelId: options.modelId, ...(options.provider ? { provider: options.provider } : {}) }
+		: { provider: options.provider };
+	const exclusion: ModelExclusion = {
+		...target,
+		reason: options.reason ?? "runtime-failure",
+		recordedAt: now,
+		expiresAt: now + ttl,
+	};
+	exclusions.unshift(exclusion);
+	exclusions = deduplicate(exclusions);
+	if (exclusions.length > 200) exclusions.length = 200;
+	flushPersist();
+}
+
+/**
+ * Drop all expired exclusions from memory and schedule a persist.
+ */
+export function clearExpiredExclusions(): void {
+	ensureLoaded();
+	prune(exclusions, Date.now());
+	schedulePersist();
+}
+
+/**
+ * Remove every exclusion (e.g. after the operator fixes credentials).
+ */
+export function clearExclusions(): void {
+	ensureLoaded();
+	exclusions.length = 0;
+	schedulePersist();
+}
+
+/**
+ * Whether an exclusion entry matches a candidate.
+ *
+ * Semantics:
+ * - Entry with modelId: model-specific exclusion. Matches only that modelId;
+ *   when both the entry and the candidate carry a provider, the providers must
+ *   also agree so `openai/gpt-4` does not exclude `github-copilot/gpt-4`.
+ * - Entry without modelId: provider-wide exclusion (e.g. quota or auth failure).
+ *   Matches every model of that provider.
+ */
+function entryMatches(entry: ModelExclusion, candidateModelId: string, candidateProvider: string | undefined, now: number): boolean {
+	if (entry.expiresAt <= now) return false;
+	if (entry.modelId) {
+		if (entry.modelId !== candidateModelId) return false;
+		return !entry.provider || !candidateProvider || entry.provider === candidateProvider;
+	}
+	return Boolean(entry.provider) && entry.provider === candidateProvider;
+}
+
+/**
+ * Whether a model (or its provider) is currently excluded.
+ */
+export function isExcluded(modelId: string, provider: string): boolean {
+	ensureLoaded();
+	return exclusions.some((entry) => entryMatches(entry, modelId, provider, Date.now()));
+}
+
+/**
+ * Number of live (non-expired) exclusions.
+ */
+export function getExcludedCount(): number {
+	ensureLoaded();
+	clearExpiredExclusions();
+	return exclusions.length;
+}
+
+/**
+ * Split a candidate fullId into its provider + modelId components.
+ *
+ * A fullId may carry a thinking suffix (`provider/model:thinking`) which is
+ * stripped before parsing, and the modelId itself may contain slashes
+ * (e.g. `openrouter/google/gemini-flash`). The first `/`-segment is the
+ * provider; everything after is the modelId. This MUST stay in lock-step with
+ * the matching inside {@link isExcluded} so that a failure recorded via
+ * {@link recordModelFailure} is later recognised by the candidate filter.
+ */
+export function parseModelKey(fullId: string): { provider?: string; modelId: string } {
+	const base = fullId.includes(":") ? fullId.substring(0, fullId.lastIndexOf(":")) : fullId;
+	if (!base.includes("/")) return { modelId: base };
+	const slash = base.indexOf("/");
+	return { provider: base.slice(0, slash), modelId: base.slice(slash + 1) };
+}
+
+/**
+ * Filter a list of candidate fullIds, removing excluded models/providers and
+ * duplicates while preserving order.
+ */
+export function filterFallbackCandidates(candidates: string[], opts?: { now?: number }): string[] {
+	ensureLoaded();
+	const timestamp = opts?.now ?? Date.now();
+	const seen = new Set<string>();
+	const filtered: string[] = [];
+	for (const raw of candidates) {
+		if (!raw || seen.has(raw)) continue;
+		const { provider: candidateProvider, modelId: candidateModelId } = parseModelKey(raw);
+		const excluded = exclusions.some((entry) => entryMatches(entry, candidateModelId, candidateProvider, timestamp));
+		if (excluded) continue;
+		seen.add(raw);
+		filtered.push(raw);
+	}
+	return filtered;
+}
+
+/**
+ * Reload exclusions from disk (for tests and config hot-reload).
+ * Discards any in-memory-only exclusions that were not yet persisted.
+ */
+export function reloadFromDisk(): void {
+	loaded = false;
+	exclusions = [];
+	ensureLoaded();
+}
+
+function prune(items: ModelExclusion[], now: number): void {
+	let write = 0;
+	for (let i = 0; i < items.length; i++) {
+		const entry = items[i]!;
+		if (entry.expiresAt > now) {
+			items[write++] = entry;
+		}
+	}
+	items.length = write;
+}

package/src/runs/shared/model-fallback.ts

@@ -1,6 +1,7 @@
 import type { ModelInfo as AvailableModelInfo } from "../../shared/model-info.ts";
 import type { Usage } from "../../shared/types.ts";
-import { checkModelScope, type ModelScopeConfig, type ModelScopeViolation, type ModelSource } from "./model-scope.ts";
+import { filterFallbackCandidates, parseModelKey, recordModelFailure } from "./model-exclusions.ts";
+import { checkModelScope, type ModelScopeCheckRule, type ModelScopeViolation, type ModelSource } from "./model-scope.ts";
 
 export type { AvailableModelInfo };
 
@@ -235,7 +236,7 @@ function resolveRequiredSubagentModelCandidate(
 
 export interface ResolveSubagentModelOverrideOptions {
 	/** When set with `enforce: true`, out-of-scope models are rejected. */
-	scope?: ModelScopeConfig;
+	scope?: ModelScopeCheckRule | ModelScopeCheckRule[];
 	/** Origin of the requested model: explicit caller-supplied (hard error) vs inherited (warn). Defaults to `"inherited"`. */
 	source?: ModelSource;
 	/** Called for warn-severity violations instead of `console.warn`. */
@@ -246,6 +247,32 @@ function defaultScopeWarn(violation: ModelScopeViolation): void {
 	console.warn(`[pi-subagents] ${violation.message}`);
 }
 
+function configuredScopes(scope: ModelScopeCheckRule | ModelScopeCheckRule[] | undefined): ModelScopeCheckRule[] {
+	return scope ? (Array.isArray(scope) ? scope : [scope]) : [];
+}
+
+function throwForUnresolvedEnforcedInheritScope(scope: ModelScopeCheckRule | ModelScopeCheckRule[] | undefined, includeMixed = false): void {
+	const unresolvedInheritScope = configuredScopes(scope)
+		.find((entry) => entry.enforce === true && (includeMixed ? entry.allow?.includes(INHERIT_MODEL) : entry.allow?.length === 1 && entry.allow[0] === INHERIT_MODEL));
+	if (!unresolvedInheritScope) return;
+	const origin = unresolvedInheritScope.origin ?? "modelScope";
+	throw new Error(`Cannot enforce subagent model scope (${origin}): 'inherit' requires a current parent session model.`);
+}
+
+function enforceModelScopes(
+	model: string,
+	scope: ModelScopeCheckRule | ModelScopeCheckRule[] | undefined,
+	source: ModelSource,
+	onWarn: ((violation: ModelScopeViolation) => void) | undefined,
+): void {
+	const violations = configuredScopes(scope)
+		.map((entry) => checkModelScope(model, entry, source))
+		.filter((violation): violation is ModelScopeViolation => violation !== undefined);
+	const error = violations.find((violation) => violation.severity === "error");
+	if (error) throw new Error(error.message);
+	for (const violation of violations) (onWarn ?? defaultScopeWarn)(violation);
+}
+
 /**
  * Resolve the `--model` override passed to a spawned subagent.
  *
@@ -273,19 +300,16 @@ export function resolveSubagentModelOverride(
 ): string | undefined {
 	const trimmed = typeof requestedModel === "string" ? requestedModel.trim() : "";
 	const explicit = trimmed && trimmed !== INHERIT_MODEL ? trimmed : undefined;
+	if (!parentModel) throwForUnresolvedEnforcedInheritScope(options?.scope, explicit === undefined || options?.source === "inherited");
 	let resolved: string | undefined;
 	if (explicit === undefined) {
 		resolved = parentModel ? `${parentModel.provider}/${parentModel.id}` : undefined;
 	} else {
 		resolved = resolveRequiredSubagentModelCandidate(explicit, availableModels, preferredProvider);
 	}
-	if (resolved && options?.scope?.enforce) {
+	if (resolved && options?.scope) {
 		const source: ModelSource = explicit === undefined ? "inherited" : (options.source ?? "inherited");
-		const violation = checkModelScope(resolved, options.scope, source);
-		if (violation) {
-			if (violation.severity === "error") throw new Error(violation.message);
-			(options.onWarn ?? defaultScopeWarn)(violation);
-		}
+		enforceModelScopes(resolved, options.scope, source, options.onWarn);
 	}
 	return resolved;
 }
@@ -317,7 +341,7 @@ export function resolveEffectiveSubagentModel(
 
 export interface BuildModelCandidatesOptions {
 	/** Fallback models warn by default and throw when strict scope enforcement is enabled. */
-	scope?: ModelScopeConfig;
+	scope?: ModelScopeCheckRule | ModelScopeCheckRule[];
 	onWarn?: (violation: ModelScopeViolation) => void;
 	/** The primary model came from the running parent session, not configuration. */
 	primaryModelFromParent?: boolean;
@@ -340,6 +364,7 @@ export function buildModelCandidates(
 	preferredProvider?: string,
 	options?: BuildModelCandidatesOptions,
 ): string[] {
+	if (!primaryModel) throwForUnresolvedEnforcedInheritScope(options?.scope, true);
 	const seen = new Set<string>();
 	const candidates: string[] = [];
 	const rawCandidates = [primaryModel, ...(fallbackModels ?? [])];
@@ -357,17 +382,14 @@ export function buildModelCandidates(
 			continue;
 		}
 		if (seen.has(normalized)) continue;
-		if ((index > 0 || options?.scope?.strict === true) && options?.scope?.enforce) {
-			const violation = checkModelScope(normalized, options.scope, "inherited");
-			if (violation) {
-				if (violation.severity === "error") throw new Error(violation.message);
-				(options.onWarn ?? defaultScopeWarn)(violation);
-			}
+		const scopes = configuredScopes(options?.scope);
+		if (index > 0 || scopes.some((scope) => scope.enforce === true && scope.strict === true)) {
+			enforceModelScopes(normalized, scopes, "inherited", options?.onWarn);
 		}
 		seen.add(normalized);
 		candidates.push(normalized);
 	}
-	return candidates;
+	return filterFallbackCandidates(candidates);
 }
 
 const RETRYABLE_MODEL_FAILURE_PATTERNS = [
@@ -424,6 +446,40 @@ export function isRetryableModelFailure(error: string | undefined): boolean {
 	return RETRYABLE_MODEL_FAILURE_PATTERNS.some((pattern) => pattern.test(error));
 }
 
+export function recordRetryableModelFailure(model: string | undefined, error: string | undefined): void {
+	if (!model || !isRetryableModelFailure(error)) return;
+	const { provider, modelId } = parseModelKey(model);
+	recordModelFailure({ modelId, reason: error, ...(provider ? { provider } : {}) });
+}
+
+/**
+ * Context-overflow signals. These are deliberately NOT part of
+ * {@link RETRYABLE_MODEL_FAILURE_PATTERNS}: an overflow means the input was too
+ * large for the model's context window, so retrying the same input on another
+ * model (or the same model again) cannot succeed. Callers should treat overflow
+ * as a terminal, non-retryable failure and surface a clear "input too large"
+ * error instead of burning fallback attempts on a guaranteed failure.
+ */
+const CONTEXT_OVERFLOW_PATTERNS = [
+	/context(?: length| window| limit)? (?:exceed|overflow|too long)/i,
+	/maximum context length/i,
+	/too many tokens/i,
+	/token limit/i,
+	/context_length_exceeded/i,
+	/length_required/i,
+	/maximum.*tokens/i,
+	/prompt.*too long/i,
+	/input.*too long/i,
+	/exceeded.*context/i,
+	/context.*overflow/i,
+];
+
+export function isContextOverflow(error: string | undefined): boolean {
+	if (!error) return false;
+	if (TOOL_FAILURE_PREFIX.test(error.trim())) return false;
+	return CONTEXT_OVERFLOW_PATTERNS.some((pattern) => pattern.test(error));
+}
+
 export function formatModelAttemptNote(attempt: ModelAttemptSummary, nextModel?: string): string {
 	const failure = attempt.error?.trim() || `exit ${attempt.exitCode ?? 1}`;
 	return nextModel