pi-crew 0.9.59 → 0.9.61

package/src/runtime/model/model-fallback.ts

@@ -2,8 +2,10 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { errors } from "../../errors.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
 import { fuzzyResolveModelId } from "./model-resolver.ts";
 import { checkModelScope } from "./model-scope.ts";
+import { providerRankFromQuota, deprioritizedProviders as quotaDeprioritizedProviders } from "./provider-quota.ts";
 
 export interface AvailableModelInfo {
 	provider: string;
@@ -43,6 +45,21 @@ interface PiProviderConfigLike {
 }
 
 function modelInfoFromUnknown(value: unknown): AvailableModelInfo | undefined {
+	// A plain `"provider/id"` (or bare `"id"`) string is a valid model reference.
+	// The child-process path receives pi's `Model` object, but the live-session
+	// path and the background path (manifest-persisted) carry strings; both must
+	// resolve identically or parent-model inheritance silently disappears.
+	if (typeof value === "string") {
+		const raw = value.trim();
+		if (!raw) return undefined;
+		const slashIdx = raw.indexOf("/");
+		if (slashIdx <= 0) return { provider: "", id: raw, fullId: raw };
+		return {
+			provider: raw.slice(0, slashIdx),
+			id: raw.slice(slashIdx + 1),
+			fullId: raw,
+		};
+	}
 	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
 	const record = value as ModelLike;
 	if (typeof record.provider !== "string" || typeof record.id !== "string") return undefined;
@@ -70,6 +87,21 @@ export function modelStringFromUnknown(model: unknown): string | undefined {
 	return modelInfoFromUnknown(model)?.fullId;
 }
 
+/**
+ * Normalize any model reference (pi `Model` object, `"provider/id"`, bare id)
+ * to its canonical string form. Returns undefined for unrecognized input.
+ */
+export function modelRefToString(model: unknown): string | undefined {
+	return modelInfoFromUnknown(model)?.fullId;
+}
+
+/** Provider segment of a `"provider/id"` reference, or undefined for bare ids. */
+export function providerOfModelRef(model: string | undefined): string | undefined {
+	if (!model) return undefined;
+	const slashIdx = model.indexOf("/");
+	return slashIdx > 0 ? model.slice(0, slashIdx) : undefined;
+}
+
 function uniqueModelInfos(models: AvailableModelInfo[]): AvailableModelInfo[] {
 	const seen = new Set<string>();
 	return models.filter((model) => {
@@ -130,19 +162,103 @@ function modelsJsonInfos(modelsJson: PiModelsJsonLike | undefined): AvailableMod
 	return infos;
 }
 
-export function configuredModelInfosFromPiConfig(cwd?: string): AvailableModelInfo[] {
+/**
+ * Providers that have a discoverable credential, so a model from them is
+ * plausibly runnable. Mirrors (loosely) pi's own `configuredProviders` set,
+ * which is what `ModelRegistry.getAvailable()` filters on — the raw-JSON
+ * fallback below has no registry, so without this check a background run would
+ * happily queue models the user has no key for and burn a child spawn per one.
+ *
+ * Detection channels (existence only — no credential value is ever read into
+ * a return value or a log):
+ *   • a top-level provider key in `~/.pi/agent/auth.json`
+ *   • `apiKey` / `baseUrl` set on the provider in `models.json` (local
+ *     providers such as ollama are keyless but carry a baseUrl)
+ *   • an `<PROVIDER>_API_KEY` environment variable
+ */
+export function providersWithCredentials(modelsJson: PiModelsJsonLike | undefined, env: NodeJS.ProcessEnv = process.env): Set<string> {
+	const providers = new Set<string>();
+	const auth = readJsonObject(path.join(piAgentDir(), "auth.json"));
+	for (const key of Object.keys(auth ?? {})) providers.add(key);
+	if (modelsJson?.providers && typeof modelsJson.providers === "object" && !Array.isArray(modelsJson.providers)) {
+		for (const [provider, rawConfig] of Object.entries(modelsJson.providers as Record<string, unknown>)) {
+			if (!rawConfig || typeof rawConfig !== "object" || Array.isArray(rawConfig)) continue;
+			const config = rawConfig as { apiKey?: unknown; baseUrl?: unknown };
+			if (typeof config.apiKey === "string" && config.apiKey.trim()) providers.add(provider);
+			if (typeof config.baseUrl === "string" && config.baseUrl.trim()) providers.add(provider);
+		}
+	}
+	for (const key of Object.keys(env)) {
+		const match = /^([A-Z0-9]+(?:_[A-Z0-9]+)*)_API_KEY$/.exec(key);
+		if (match && env[key]?.trim()) providers.add(match[1]!.toLowerCase().replace(/_/g, "-"));
+	}
+	return providers;
+}
+
+interface ConfiguredModelCacheEntry {
+	signature: string;
+	all: AvailableModelInfo[];
+	credentialed: AvailableModelInfo[];
+}
+
+/** US-012: avoid re-reading 3 JSON files on every routing build (and every retry). */
+const configuredModelCache = new Map<string, ConfiguredModelCacheEntry>();
+
+function fileSignature(filePath: string): string {
+	try {
+		const stat = fs.statSync(filePath);
+		return `${stat.mtimeMs}:${stat.size}`;
+	} catch {
+		return "-";
+	}
+}
+
+export interface ConfiguredModelOptions {
+	/** Drop models whose provider has no discoverable credential. */
+	requireCredentials?: boolean;
+}
+
+export function configuredModelInfosFromPiConfig(cwd?: string, options?: ConfiguredModelOptions): AvailableModelInfo[] {
 	const agentDir = piAgentDir();
-	const globalSettings = readJsonObject(path.join(agentDir, "settings.json")) as PiSettingsLike | undefined;
-	const projectSettings = cwd ? (readJsonObject(path.join(cwd, ".pi", "settings.json")) as PiSettingsLike | undefined) : undefined;
+	const globalSettingsPath = path.join(agentDir, "settings.json");
+	const modelsJsonPath = path.join(agentDir, "models.json");
+	const authPath = path.join(agentDir, "auth.json");
+	const projectSettingsPath = cwd ? path.join(cwd, ".pi", "settings.json") : undefined;
+	const cacheKey = `${agentDir}\u0000${cwd ?? ""}`;
+	const signature = [globalSettingsPath, modelsJsonPath, authPath, ...(projectSettingsPath ? [projectSettingsPath] : [])]
+		.map(fileSignature)
+		.join("|");
+	const cached = configuredModelCache.get(cacheKey);
+	if (cached?.signature === signature) return options?.requireCredentials ? cached.credentialed : cached.all;
+
+	const globalSettings = readJsonObject(globalSettingsPath) as PiSettingsLike | undefined;
+	const projectSettings = projectSettingsPath ? (readJsonObject(projectSettingsPath) as PiSettingsLike | undefined) : undefined;
 	const effectiveSettings = {
 		...(globalSettings ?? {}),
 		...(projectSettings ?? {}),
 	};
 	const defaultModel = settingsModelInfo(effectiveSettings);
-	return uniqueModelInfos([
-		...(defaultModel ? [defaultModel] : []),
-		...modelsJsonInfos(readJsonObject(path.join(agentDir, "models.json")) as PiModelsJsonLike | undefined),
-	]);
+	const modelsJson = readJsonObject(modelsJsonPath) as PiModelsJsonLike | undefined;
+	const all = uniqueModelInfos([...(defaultModel ? [defaultModel] : []), ...modelsJsonInfos(modelsJson)]);
+	const credentialedProviders = providersWithCredentials(modelsJson);
+	// The settings.json default model is kept regardless: it is the user's
+	// explicit choice and pi resolves its auth through channels we do not model
+	// here (OAuth, keychain, provider extensions).
+	const credentialed = all.filter(
+		(info) => info.fullId === defaultModel?.fullId || credentialedProviders.has(info.provider.toLowerCase()),
+	);
+	configuredModelCache.set(cacheKey, { signature, all, credentialed });
+	// LRU cap: prevent unbounded growth across many distinct agent-dir/cwd combos.
+	if (configuredModelCache.size > 32) {
+		const oldestKey = configuredModelCache.keys().next().value;
+		if (oldestKey !== undefined) configuredModelCache.delete(oldestKey);
+	}
+	return options?.requireCredentials ? credentialed : all;
+}
+
+/** @internal Test seam — clear the mtime-keyed configured-model cache. */
+export function __test_resetConfiguredModelCache(): void {
+	configuredModelCache.clear();
 }
 
 export function splitThinkingSuffix(model: string): {
@@ -304,17 +420,182 @@ function isAvailableModel(model: string, availableModels: AvailableModelInfo[] |
 	return fuzzy !== undefined;
 }
 
+/**
+ * Ordering + budget policy for the AUTO portion of the fallback chain (the
+ * models appended from the registry / pi config that nobody declared).
+ *
+ * Explicit declarations (tool override, step, team role, agent model and the
+ * declared `fallbackModels`) are never reordered and never truncated — only the
+ * auto tail is governed here.
+ */
+export interface ModelFallbackPolicy {
+	/**
+	 * How many auto-appended models to keep. `undefined` = keep all (legacy).
+	 * Each extra candidate multiplies the worst-case child-spawn budget by
+	 * `maxAttempts + 1`, so an unbounded tail on a large catalogue is the main
+	 * cost amplifier.
+	 */
+	maxAutoFallbacks?: number;
+	/**
+	 * `"parentFirst"` keeps the auto tail on the same provider as the model
+	 * actually in use before crossing to another provider when a policy is
+	 * configured or quota data enriches it — same auth, similar cost/latency
+	 * profile. `"asIs"` preserves raw catalogue order. Without explicit
+	 * configuration, auto tail stays catalogue order.
+	 */
+	order?: "parentFirst" | "asIs";
+	/** Lower rank = try earlier. Populated from provider quota when available. */
+	providerRank?: Record<string, number>;
+	/** Providers at/near their quota limit — pushed to the back of the tail. */
+	deprioritizedProviders?: string[];
+	/** Drop pi-config models whose provider has no discoverable credential. */
+	requireCredentials?: boolean;
+	/**
+	 * When true (default), populate `providerRank` and `deprioritizedProviders`
+	 * from the provider-quota cache before ordering the auto tail. Set to false
+	 * to disable quota-aware ordering entirely.
+	 */
+	quotaAwareOrdering?: boolean;
+}
+
+/**
+ * Order the auto tail. Stable: equal-priority entries keep catalogue order.
+ * Priority, most significant first:
+ *   1. not quota-exhausted
+ *   2. same provider as the anchor (the model we are actually going to run)
+ *   3. explicit provider rank (quota-derived), unknown providers last
+ */
+export function orderAutoFallbacks(candidates: string[], policy: ModelFallbackPolicy | undefined, anchorProvider?: string): string[] {
+	if (!policy || policy.order === "asIs") return candidates;
+	const deprioritized = new Set((policy.deprioritizedProviders ?? []).map((p) => p.toLowerCase()));
+	const rank = policy.providerRank ?? {};
+	const rankFor = (provider: string | undefined): number => {
+		if (!provider) return Number.MAX_SAFE_INTEGER;
+		const value = rank[provider] ?? rank[provider.toLowerCase()];
+		return typeof value === "number" ? value : Number.MAX_SAFE_INTEGER;
+	};
+	return candidates
+		.map((model, index) => {
+			const provider = providerOfModelRef(model);
+			return {
+				model,
+				index,
+				exhausted: provider && deprioritized.has(provider.toLowerCase()) ? 1 : 0,
+				anchored: anchorProvider && provider === anchorProvider ? 0 : 1,
+				rank: rankFor(provider),
+			};
+		})
+		.sort((a, b) => a.exhausted - b.exhausted || a.anchored - b.anchored || a.rank - b.rank || a.index - b.index)
+		.map((entry) => entry.model);
+}
+
+/**
+ * Build a {@link ModelFallbackPolicy} from crew config + environment. Env vars
+ * override config (lowest friction for a quick experiment without editing JSON):
+ *   PI_CREW_MAX_AUTO_FALLBACKS — cap the auto tail
+ *   PI_CREW_MODEL_FALLBACK_ORDER — "parentFirst" | "asIs"
+ *   PI_CREW_MODEL_REQUIRE_CREDENTIALS — "1" to drop uncredentialed providers
+ *
+ * `parentFirst` ordering applies only when a policy is explicitly configured or
+ * quota data enriches it; otherwise the auto tail stays catalogue order.
+ *
+ * Returns undefined when nothing is configured, so callers that pass it to
+ * `buildConfiguredModelRouting` get legacy (unbounded, unordered) behaviour.
+ */
+export function resolveModelFallbackPolicy(
+	config:
+		| {
+				maxAutoFallbacks?: number;
+				order?: "parentFirst" | "asIs";
+				requireCredentials?: boolean;
+				quotaAwareOrdering?: boolean;
+		  }
+		| undefined,
+	env: NodeJS.ProcessEnv = process.env,
+): ModelFallbackPolicy | undefined {
+	const envMaxAuto = env.PI_CREW_MAX_AUTO_FALLBACKS;
+	let maxAutoFallbacks: number | undefined;
+	if (envMaxAuto) {
+		const parsed = Number.parseInt(envMaxAuto, 10);
+		if (Number.isFinite(parsed) && parsed >= 0) {
+			maxAutoFallbacks = parsed;
+		} else if (Number.isFinite(parsed)) {
+			// Negative — clamp to 0 with warning.
+			logInternalError(
+				"model-fallback.max-auto-fallbacks-invalid",
+				undefined,
+				`PI_CREW_MAX_AUTO_FALLBACKS="${envMaxAuto}" is negative, clamped to 0`,
+				"warn",
+			);
+			maxAutoFallbacks = 0;
+		} else {
+			// NaN or non-finite — fall back to config.
+			logInternalError(
+				"model-fallback.max-auto-fallbacks-invalid",
+				undefined,
+				`PI_CREW_MAX_AUTO_FALLBACKS="${envMaxAuto}" is invalid, falling back to config`,
+				"warn",
+			);
+			maxAutoFallbacks = config?.maxAutoFallbacks;
+		}
+	} else {
+		maxAutoFallbacks = config?.maxAutoFallbacks;
+	}
+	const order = (env.PI_CREW_MODEL_FALLBACK_ORDER as "parentFirst" | "asIs" | undefined) ?? config?.order;
+	const requireCredentials =
+		env.PI_CREW_MODEL_REQUIRE_CREDENTIALS === "1"
+			? true
+			: env.PI_CREW_MODEL_REQUIRE_CREDENTIALS === "0"
+				? false
+				: config?.requireCredentials;
+	// quotaAwareOrdering defaults to true (user preference: default-on with cache).
+	// When explicitly disabled, no deprioritization/rank data is attached.
+	const quotaAware = config?.quotaAwareOrdering !== false;
+	if (maxAutoFallbacks === undefined && !order && requireCredentials === undefined && config?.quotaAwareOrdering === undefined)
+		return undefined;
+	return {
+		...(maxAutoFallbacks !== undefined && Number.isFinite(maxAutoFallbacks) ? { maxAutoFallbacks } : {}),
+		...(order ? { order } : {}),
+		...(requireCredentials !== undefined ? { requireCredentials } : {}),
+		quotaAwareOrdering: quotaAware,
+	};
+}
+
+/**
+ * Resolve the default subagent model from config or env. Precedence:
+ *   PI_CREW_MODEL env > config.runtime.modelFallback.defaultSubagentModel
+ * Returns undefined when neither is set.
+ */
+export function resolveDefaultSubagentModel(
+	config: { defaultSubagentModel?: string } | undefined,
+	env: NodeJS.ProcessEnv = process.env,
+): string | undefined {
+	return env.PI_CREW_MODEL?.trim() || config?.defaultSubagentModel?.trim() || undefined;
+}
+
 export interface ConfiguredModelRouting {
 	requested?: string;
 	candidates: string[];
 	reason?: string;
+	/**
+	 * Set when the caller asked for a model that is not resolvable against the
+	 * available catalogue, so the chain silently runs something else. Callers
+	 * surface this as a warning instead of dropping it on the floor.
+	 */
+	droppedRequested?: string;
+	/** How many candidates came from the auto tail (diagnostics). */
+	autoFallbackCount?: number;
 	/**
 	 * F7 scope gate verdict. Populated when the caller passed `scopeModelsPatterns`.
 	 * - `inScope: true` → the resolved model is inside the allowlist (or no allowlist).
-	 * - `inScope: false, source: "caller"` → caller override is out-of-scope; the
-	 *   function throws `errors.modelOutOfScope` (hard error before spawn) UNLESS
-	 *   the caller marked it as a frontmatter override (`isFrontmatterOverride: true`),
-	 *   in which case the verdict is returned for the caller to log as a warning.
+	 * - `inScope: false, source: "caller"` → caller override (override/step/team role)
+	 *   is out-of-scope; the function throws `errors.modelOutOfScope` (hard error
+	 *   before spawn) UNLESS the caller marked it as a frontmatter override
+	 *   (`isFrontmatterOverride: true`), in which case the verdict is returned for
+	 *   the caller to log as a warning.
+	 * - `inScope: false, source: "frontmatter" | "resolved"` → frontmatter-pinned,
+	 *   defaultSubagentModel, or parentModel-inherited model is out-of-scope;
+	 *   soft warn + run anyway (no throw).
 	 */
 	scopeVerdict?: import("./model-scope.ts").ModelScopeCheck;
 }
@@ -323,11 +604,22 @@ export function buildConfiguredModelRouting(input: {
 	overrideModel?: string;
 	stepModel?: string;
 	teamRoleModel?: string;
+	/** Team-role declared fallbacks (`fallbackModels=a,b` on the role line). */
+	teamRoleFallbackModels?: string[];
 	agentModel?: string;
+	/**
+	 * Config-level default model for subagents. Sits between the agent model
+	 * and the inherited parent model in precedence: when the agent has
+	 * `model: false` (all builtins), this takes over before falling back to
+	 * the session's model. Ignored when the agent or caller already set one.
+	 */
+	defaultSubagentModel?: string;
 	fallbackModels?: string[];
 	parentModel?: unknown;
 	modelRegistry?: unknown;
 	cwd?: string;
+	/** Ordering + budget policy for the auto tail. */
+	policy?: ModelFallbackPolicy;
 	/**
 	 * F7: when set, enforce the enabledModels allowlist. Caller-supplied out-of-
 	 * scope models throw `errors.modelOutOfScope`; frontmatter-pinned out-of-scope
@@ -343,14 +635,20 @@ export function buildConfiguredModelRouting(input: {
 	isFrontmatterOverride?: boolean;
 }): ConfiguredModelRouting {
 	const registryModels = availableModelInfosFromRegistry(input.modelRegistry);
-	const configModels = configuredModelInfosFromPiConfig(input.cwd);
+	const configModels = configuredModelInfosFromPiConfig(input.cwd, {
+		requireCredentials: input.policy?.requireCredentials,
+	});
 	const availableModels =
 		registryModels && registryModels.length > 0 ? registryModels : configModels.length > 0 ? configModels : registryModels;
 	const parentModel = modelStringFromUnknown(input.parentModel);
-	const preferredProvider = parentModel?.split("/")[0] ?? availableModels?.[0]?.provider;
+	const preferredProvider = providerOfModelRef(parentModel) ?? availableModels?.[0]?.provider;
 	// B3: Parent model inheritance — when agent has no model specified,
 	// inherit from parent session model before falling back to defaults.
-	const effectiveAgentModel = input.agentModel?.trim() ? input.agentModel : parentModel;
+	// defaultSubagentModel (config/env) sits between agent and parent: when
+	// the agent has `model: false` but a default is configured, the default
+	// takes over and the parent model becomes the first fallback.
+	const defaultSubagent = input.defaultSubagentModel?.trim() || undefined;
+	const effectiveAgentModel = input.agentModel?.trim() ? input.agentModel : (defaultSubagent ?? parentModel);
 	const requested = [input.overrideModel, input.stepModel, input.teamRoleModel, effectiveAgentModel].find((model): model is string =>
 		Boolean(model?.trim()),
 	);
@@ -360,52 +658,130 @@ export function buildConfiguredModelRouting(input: {
 			candidates: [],
 			reason: "no configured Pi models available",
 		};
-	const rawModels = availableModels
-		? [
-				input.overrideModel,
-				input.stepModel,
-				input.teamRoleModel,
-				effectiveAgentModel,
-				...(input.fallbackModels ?? []),
-				...availableModels.map((model) => model.fullId),
-			]
-		: [input.overrideModel, input.stepModel, input.teamRoleModel, effectiveAgentModel, ...(input.fallbackModels ?? []), parentModel];
+	// Explicit declarations, highest precedence first. These are authoritative:
+	// never reordered, never truncated by the auto-tail budget.
+	const declaredRaw = [
+		input.overrideModel,
+		input.stepModel,
+		input.teamRoleModel,
+		effectiveAgentModel,
+		// When defaultSubagentModel replaced parentModel as the effective agent
+		// model, keep parentModel as an explicit fallback before the auto tail.
+		...(defaultSubagent && !input.agentModel?.trim() ? [parentModel] : []),
+		...(input.teamRoleFallbackModels ?? []),
+		...(input.fallbackModels ?? []),
+	];
 	// Fix (Round 18): when an agent has `model: false` (frontmatter) the
 	// inherited `parentModel` (= session chính's model, e.g. minimax-M3) IS the
 	// desired primary. It must NOT be filtered out by isAvailableModel — which
 	// only knows about models from models.json / registry, NOT builtin Pi models.
 	// Pin the inherited parentModel at index 0 regardless of availability.
 	const parentModelRaw = effectiveAgentModel?.trim() || undefined;
-	const configuredModels = rawModels
+	// When defaultSubagentModel replaced parentModel as the effective agent
+	// model, the parent model is still a valid fallback (it IS the session's
+	// live model) — pin it too so isAvailableModel doesn't filter it out.
+	const parentModelFallback = defaultSubagent && !input.agentModel?.trim() ? parentModel : undefined;
+	const declaredModels = declaredRaw
 		.filter((model): model is string => Boolean(model?.trim()))
 		.filter((model, idx) => {
 			if (parentModelRaw && idx === 0 && model.trim() === parentModelRaw) return true;
+			if (parentModelFallback && model.trim() === parentModelFallback) return true;
 			return isAvailableModel(model.trim(), availableModels);
 		});
-	const candidates = buildModelCandidates(configuredModels[0], configuredModels.slice(1), availableModels, preferredProvider);
-	const reason =
-		requested && candidates[0] && resolveModelCandidate(requested, availableModels, preferredProvider) !== candidates[0]
-			? "requested model unavailable; selected configured Pi fallback"
-			: candidates.length > 1
-				? "configured Pi fallback chain"
-				: undefined;
+	const declaredCandidates = buildModelCandidates(declaredModels[0], declaredModels.slice(1), availableModels, preferredProvider);
+	// Auto tail: everything the user did NOT declare. Without a registry the
+	// only auto candidate is the inherited parent model.
+	const autoRaw = availableModels ? availableModels.map((model) => model.fullId) : parentModel ? [parentModel] : [];
+	const declaredSet = new Set(declaredCandidates);
+	const autoResolved = buildModelCandidates(undefined, autoRaw, availableModels, preferredProvider).filter(
+		(candidate) => !declaredSet.has(candidate),
+	);
+	const anchorProvider = providerOfModelRef(declaredCandidates[0]) ?? providerOfModelRef(parentModel);
+	// Quota-aware ordering: when the policy allows it, enrich with live quota
+	// data so exhausted providers sink to the back of the auto tail.
+	let effectivePolicy = input.policy;
+	if (effectivePolicy?.quotaAwareOrdering !== false && autoResolved.length > 0) {
+		const tailProviders = [...new Set(autoResolved.map((m) => providerOfModelRef(m)).filter((p): p is string => Boolean(p)))];
+		const deprioritized = quotaDeprioritizedProviders(tailProviders);
+		const rank = providerRankFromQuota(tailProviders);
+		if (deprioritized.length > 0 || Object.keys(rank).length > 0) {
+			effectivePolicy = {
+				...effectivePolicy,
+				deprioritizedProviders: [...(effectivePolicy?.deprioritizedProviders ?? []), ...deprioritized],
+				providerRank: { ...rank, ...(effectivePolicy?.providerRank ?? {}) },
+			};
+		}
+	}
+	const autoOrdered = orderAutoFallbacks(autoResolved, effectivePolicy, anchorProvider);
+	const autoCandidates =
+		effectivePolicy?.maxAutoFallbacks === undefined ? autoOrdered : autoOrdered.slice(0, Math.max(0, effectivePolicy.maxAutoFallbacks));
+	const candidates = [...declaredCandidates, ...autoCandidates];
+	const resolvedRequested = requested ? resolveModelCandidate(requested, availableModels, preferredProvider) : undefined;
+	const droppedRequested = requested && candidates[0] && resolvedRequested !== candidates[0] ? requested : undefined;
+	const reason = droppedRequested
+		? "requested model unavailable; selected configured Pi fallback"
+		: candidates.length > 1
+			? "configured Pi fallback chain"
+			: undefined;
 	// F7 scope gate: when `scopeModelsPatterns` is configured, check the
 	// resolved model. Caller-supplied (override/step/team role) out-of-scope
 	// is a HARD ERROR (we surface it via the verdict AND throw, so spawn aborts
-	// before any cost is incurred). Frontmatter-pinned out-of-scope is a
-	// WARNING returned on the verdict for the caller to log.
+	// before any cost is incurred). Frontmatter-pinned, defaultSubagentModel,
+	// and parentModel-inherited out-of-scope is a WARNING returned on the verdict
+	// for the caller to log.
 	let scopeVerdict: ConfiguredModelRouting["scopeVerdict"];
 	if (input.scopeModelsPatterns && input.scopeModelsPatterns.length > 0) {
 		const resolved = candidates[0] ?? requested;
-		const source = input.overrideModel ? "caller" : input.agentModel ? "frontmatter" : "resolved";
+		// Attribution by REAL precedence: override/step/team role are caller-level
+		// (hard-error when out-of-scope); agentModel is frontmatter (soft warn);
+		// defaultSubagentModel + parentModel are resolved (soft warn).
+		// F5: isFrontmatterOverride means the caller override equals the agent's
+		// frontmatter model (author authority) → treat as "frontmatter" so the
+		// soft warning surfaces instead of being silent (throw is also skipped).
+		const source = input.isFrontmatterOverride
+			? "frontmatter"
+			: input.overrideModel
+				? "caller"
+				: input.stepModel
+					? "caller"
+					: input.teamRoleModel
+						? "caller"
+						: input.agentModel?.trim()
+							? "frontmatter"
+							: "resolved";
 		scopeVerdict = checkModelScope(resolved, input.scopeModelsPatterns, source);
 		if (!scopeVerdict.inScope && source === "caller" && !input.isFrontmatterOverride) {
 			throw errors.modelOutOfScope(resolved ?? "", input.scopeModelsPatterns);
 		}
 	}
-	return { requested, candidates, reason, scopeVerdict };
+	return {
+		requested,
+		candidates,
+		reason,
+		droppedRequested,
+		autoFallbackCount: autoCandidates.length,
+		scopeVerdict,
+	};
 }
 
 export function buildConfiguredModelCandidates(input: Parameters<typeof buildConfiguredModelRouting>[0]): string[] {
 	return buildConfiguredModelRouting(input).candidates;
 }
+
+/**
+ * Surface a non-silent warning when a soft-sourced (non-caller) model is
+ * out-of-scope and runs anyway. Centralises the `"warn"` severity so call
+ * sites cannot accidentally omit it — Round-2 F1 found two sites forgot it,
+ * making the warning debug-gated/silent and defeating the entire Sec-M1 fix.
+ * Caller-sourced out-of-scope already throws inside `buildConfiguredModelRouting`,
+ * so this is a no-op for `source === "caller"`.
+ */
+export function warnOutOfScopeSoft(verdict: import("./model-scope.ts").ModelScopeCheck | undefined, scope: string, prefix = "Model"): void {
+	if (!verdict || verdict.inScope || verdict.source === "caller") return;
+	logInternalError(
+		scope,
+		undefined,
+		`${prefix} "${verdict.model}" from source "${verdict.source}" is outside enabledModels scope: ${verdict.reason ?? "unknown"}. Running anyway (soft warn).`,
+		"warn",
+	);
+}

package/src/runtime/model/model-scope.ts

@@ -8,6 +8,8 @@
  *   - Frontmatter-pinned (AgentConfig.model) out-of-scope
  *     → WARNING + runs anyway (frontmatter is authoritative; the agent
  *     author made a deliberate choice).
+ *   - defaultSubagentModel / parentModel-inherited out-of-scope
+ *     → WARNING + runs anyway (soft warn, same as frontmatter).
  *
  * Pattern semantics match pi's `--models` CLI / `enabledModels` allowlist:
  *   - `"anthropic/claude-opus-4-5"` — exact match (case-insensitive).

package/src/runtime/model/pi-args.ts

@@ -45,6 +45,8 @@ export interface BuildPiWorkerArgsInput {
 	env?: NodeJS.ProcessEnv;
 	/** Role for tool restrictions (uses role-tools.ts config) */
 	role?: string;
+	/** Per-role thinking override (teamRole.thinking). Takes precedence over agent.thinking. */
+	thinkingOverride?: string;
 }
 
 export interface BuildPiWorkerArgsResult {
@@ -265,13 +267,15 @@ export function buildPiWorkerArgs(input: BuildPiWorkerArgsInput): BuildPiWorkerA
 	if (input.sessionEnabled === false) args.push("--no-session");
 
 	const resolvedModel = input.model ?? input.agent.model;
+	// H1.a: teamRole.thinking (passed as thinkingOverride) takes precedence over agent.thinking.
+	const effectiveThinking = input.thinkingOverride ?? input.agent.thinking;
 	if (resolvedModel) {
-		const modelWithThinking = applyThinkingSuffix(resolvedModel, input.agent.thinking);
+		const modelWithThinking = applyThinkingSuffix(resolvedModel, effectiveThinking);
 		if (modelWithThinking) args.push("--model", modelWithThinking);
 	}
 	// When no model resolved, pass thinking separately so Pi can apply it to the inherited parent model.
-	if (!resolvedModel && input.agent.thinking && input.agent.thinking !== "off" && isValidThinkingLevel(input.agent.thinking)) {
-		args.push("--thinking", input.agent.thinking);
+	if (!resolvedModel && effectiveThinking && effectiveThinking !== "off" && isValidThinkingLevel(effectiveThinking)) {
+		args.push("--thinking", effectiveThinking);
 	}
 
 	// Apply role-based tool restrictions (from role-tools.ts)