@selesai/code 0.13.16 → 0.13.18

package/dist/extensions/pi-subagents/src/runs/shared/host-step-status.ts

@@ -1,6 +1,6 @@
 import type {
 	AsyncStatus,
-	HostStepNodeV1,
+	HostStepNode,
 	HostStepState,
 	HostStepVerdict,
 	WorkflowGraphNode,
@@ -57,7 +57,7 @@ function assertTimestamp(value: unknown, field: string, source: string, required
 	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw new Error(`Invalid host step '${source}': ${field} must be a non-negative safe integer.`);
 }
 
-function assertFreshness(value: unknown, source: string): asserts value is HostStepNodeV1["freshness"] {
+function assertFreshness(value: unknown, source: string): asserts value is HostStepNode["freshness"] {
 	if (!isRecord(value)) throw new Error(`Invalid host step '${source}': freshness must be an object.`);
 	const unknownFields = Object.keys(value).filter((field) => !FRESHNESS_FIELDS.has(field));
 	if (unknownFields.length > 0) throw new Error(`Invalid host step '${source}': freshness has unsupported fields: ${unknownFields.join(", ")}.`);
@@ -70,7 +70,7 @@ function assertFreshness(value: unknown, source: string): asserts value is HostS
  * Validate the persisted host-step contract. This deliberately rejects unknown
  * fields and unbounded values so status and receipt loaders fail closed.
  */
-export function assertHostStepNode(value: unknown, source = "status"): asserts value is HostStepNodeV1 {
+export function assertHostStepNode(value: unknown, source = "status"): asserts value is HostStepNode {
 	if (!isRecord(value)) throw new Error(`Invalid host step '${source}': expected an object.`);
 	const unknownFields = Object.keys(value).filter((field) => !HOST_STEP_FIELDS.has(field));
 	if (unknownFields.length > 0) throw new Error(`Invalid host step '${source}': unsupported fields: ${unknownFields.join(", ")}.`);
@@ -105,7 +105,7 @@ export function assertHostStepNode(value: unknown, source = "status"): asserts v
 	assertTimestamp(value.deadlineAt, "deadlineAt", source);
 }
 
-export function parseHostStepNode(value: unknown, source = "status"): HostStepNodeV1 {
+export function parseHostStepNode(value: unknown, source = "status"): HostStepNode {
 	assertHostStepNode(value, source);
 	return {
 		...value,
@@ -113,7 +113,7 @@ export function parseHostStepNode(value: unknown, source = "status"): HostStepNo
 	};
 }
 
-export function assertUniqueHostStepIds(hostSteps: readonly HostStepNodeV1[], source = "status"): void {
+export function assertUniqueHostStepIds(hostSteps: readonly HostStepNode[], source = "status"): void {
 	const ids = new Set<string>();
 	for (const hostStep of hostSteps) {
 		if (ids.has(hostStep.id)) throw new Error(`Invalid host step '${source}': duplicate host step id '${hostStep.id}'.`);
@@ -122,11 +122,11 @@ export function assertUniqueHostStepIds(hostSteps: readonly HostStepNodeV1[], so
 }
 
 /** Return only valid host nodes so an untrusted in-memory projection fails closed. */
-export function validHostStepNodes(graph: WorkflowGraphSnapshot | undefined): HostStepNodeV1[] {
+export function validHostStepNodes(graph: WorkflowGraphSnapshot | undefined): HostStepNode[] {
 	const nodes = graph?.nodes ?? [];
 	const nodeIdCounts = new Map<string, number>();
 	for (const node of nodes) nodeIdCounts.set(node.id, (nodeIdCounts.get(node.id) ?? 0) + 1);
-	const hostSteps: HostStepNodeV1[] = [];
+	const hostSteps: HostStepNode[] = [];
 	for (const [index, node] of nodes.entries()) {
 		if (node.kind !== "host-step") continue;
 		try {
@@ -147,7 +147,7 @@ export function assertWorkflowGraphHostSteps(graph: WorkflowGraphSnapshot | unde
 	if (!Array.isArray(graph.nodes)) throw new Error(`Invalid host step '${source}.workflowGraph': nodes must be an array.`);
 	const hostStepCount = graph.nodes.filter((node) => node.kind === "host-step").length;
 	if (hostStepCount > HOST_STEP_MAX_COUNT) throw new Error(`Invalid host step '${source}': workflowGraph contains more than ${HOST_STEP_MAX_COUNT} host steps.`);
-	const hostSteps: HostStepNodeV1[] = [];
+	const hostSteps: HostStepNode[] = [];
 	for (const [index, node] of graph.nodes.entries()) {
 		if (node.kind !== "host-step") continue;
 		const hostStep = parseHostStepNode(node.hostStep, `${source}.workflowGraph.nodes[${index}].hostStep`);
@@ -161,7 +161,7 @@ export function assertWorkflowGraphHostSteps(graph: WorkflowGraphSnapshot | unde
 	}
 }
 
-export function hostStepWorkflowNode(hostStep: HostStepNodeV1): WorkflowGraphNode {
+export function hostStepWorkflowNode(hostStep: HostStepNode): WorkflowGraphNode {
 	assertHostStepNode(hostStep, hostStep.id);
 	return {
 		id: hostStep.id,
@@ -172,7 +172,7 @@ export function hostStepWorkflowNode(hostStep: HostStepNodeV1): WorkflowGraphNod
 	};
 }
 
-function workflowNodeStatus(hostStep: HostStepNodeV1): WorkflowNodeStatus {
+function workflowNodeStatus(hostStep: HostStepNode): WorkflowNodeStatus {
 	if (hostStep.state === "pending") return "pending";
 	if (hostStep.state === "running") return "running";
 	if (hostStep.state === "cancelled") return "stopped";
@@ -187,7 +187,7 @@ function workflowNodeStatus(hostStep: HostStepNodeV1): WorkflowNodeStatus {
  */
 export function upsertHostStep(input: {
 	status: AsyncStatus;
-	hostStep: HostStepNodeV1;
+	hostStep: HostStepNode;
 	persist: (status: AsyncStatus) => void;
 }): AsyncStatus {
 	const hostStep = parseHostStepNode(input.hostStep, input.hostStep.id);

package/dist/extensions/pi-subagents/src/runs/shared/llm-intent-arbiter.ts

@@ -1,7 +1,6 @@
 import { createHash } from "node:crypto";
-import { Agent, type AgentTool, type StreamFn } from "@earendil-works/pi-agent-core";
-import { convertToLlm, type ExtensionContext } from "@selesai/code";
-import { streamSimple } from "@earendil-works/pi-ai/compat";
+import type { Agent, AgentTool, StreamFn } from "@earendil-works/pi-agent-core";
+import type { ExtensionContext } from "@selesai/code";
 import type { ProviderHeaders } from "@earendil-works/pi-ai";
 import { Type, type Static } from "typebox";
 import { agentStreamOptions } from "../../shared/agent-stream-options.ts";
@@ -52,7 +51,11 @@ export function mapArbiterDecision(
 
 interface ArbiterRuntime {
 	model: NonNullable<RegistryModel>;
-	baseStreamFn: StreamFn;
+	/** Explicit override; it always wins over a registered provider stream. */
+	explicitStreamFn?: StreamFn;
+	/** Registered provider stream, usable only when its api matches the model. */
+	registeredStreamFn?: StreamFn;
+	registeredApi?: string;
 	timeoutMs: number;
 }
 
@@ -73,9 +76,10 @@ export interface TaskMutationArbiterOptions {
 const DEFAULT_ARBITER_TIMEOUT_MS = 10_000;
 
 type RegistryModel = ReturnType<NonNullable<ExtensionContext["modelRegistry"]["find"]>>;
+type ArbiterModelContext = Pick<ExtensionContext, "model" | "modelRegistry">;
 
 function resolveArbiterModel(
-	ctx: ExtensionContext,
+	ctx: ArbiterModelContext,
 	options?: TaskMutationArbiterOptions,
 ): NonNullable<RegistryModel> | null {
 	const registry = ctx.modelRegistry as {
@@ -95,7 +99,7 @@ function resolveArbiterModel(
 }
 
 function resolveArbiterRuntime(
-	ctx: ExtensionContext,
+	ctx: ArbiterModelContext,
 	options?: TaskMutationArbiterOptions,
 ): ArbiterRuntime | null {
 	const model = resolveArbiterModel(ctx, options);
@@ -103,23 +107,20 @@ function resolveArbiterRuntime(
 	const registry = ctx.modelRegistry as {
 		getRegisteredProviderConfig?: (provider: string) => { api?: string; streamSimple?: StreamFn } | undefined;
 	};
-	const modelApi = (model as { api?: string }).api;
 	const registered = registry.getRegisteredProviderConfig?.(model.provider);
-	const baseStreamFn = options?.streamFn
-		?? (registered?.streamSimple && registered.api === modelApi
-			? registered.streamSimple
-			: streamSimple);
 	return {
 		model,
-		baseStreamFn,
+		explicitStreamFn: options?.streamFn,
+		registeredStreamFn: registered?.streamSimple,
+		registeredApi: registered?.api,
 		timeoutMs: options?.timeoutMs ?? DEFAULT_ARBITER_TIMEOUT_MS,
 	};
 }
 
 async function resolveArbiterAuth(
-	ctx: ExtensionContext,
+	ctx: ArbiterModelContext,
 	model: RegistryModel,
-): Promise<ArbiterAuth> {
+): Promise<ArbiterAuth | undefined> {
 	const registry = ctx.modelRegistry as {
 		getApiKeyAndHeaders?: (m: RegistryModel) => Promise<{
 			ok: boolean;
@@ -135,14 +136,14 @@ async function resolveArbiterAuth(
 	if (!registry.getApiKeyAndHeaders) return {};
 	try {
 		const auth = await registry.getApiKeyAndHeaders(model);
-		if (auth.ok === false) return {};
+		if (auth.ok === false) return undefined;
 		return {
 			...(auth.apiKey ? { apiKey: auth.apiKey } : {}),
 			...(auth.headers ? { headers: auth.headers } : {}),
 			...(auth.env ? { env: auth.env } : {}),
 		};
 	} catch {
-		return {};
+		return undefined;
 	}
 }
 
@@ -164,6 +165,15 @@ async function runArbitration(
 	auth: ArbiterAuth,
 	task: string,
 ): Promise<TaskMutationVerdict> {
+	// Keep optional Pi peers out of the detached runner's static import graph.
+	const [{ Agent }, { convertToLlm }, { streamSimple }] = await Promise.all([
+		import("@earendil-works/pi-agent-core"),
+		import("@selesai/code"),
+		import("@earendil-works/pi-ai/compat"),
+	]);
+	const streamFn: StreamFn = runtime.explicitStreamFn
+		?? (runtime.registeredApi !== undefined && runtime.registeredApi === runtime.model.api ? runtime.registeredStreamFn : undefined)
+		?? streamSimple;
 	let decision: DecisionParams | undefined;
 	const tool: AgentTool<typeof DecisionParams, { recorded: boolean }> = {
 		name: "task_mutation_decision",
@@ -190,7 +200,7 @@ async function runArbitration(
 			tools: [tool],
 		},
 		convertToLlm,
-		...agentStreamOptions(authWrappedStreamFn(runtime.baseStreamFn, auth)),
+		...agentStreamOptions(authWrappedStreamFn(streamFn, auth)),
 		getApiKey: (providerName) =>
 			providerName === runtime.model.provider ? auth.apiKey : undefined,
 		beforeToolCall: async ({ toolCall }) =>
@@ -221,9 +231,9 @@ async function runArbitration(
 	}
 }
 
-/** Create a memoized arbiter bound to the parent session's model, or undefined when disabled/unavailable. */
+/** Create a memoized arbiter bound to the supplied model services, or undefined when disabled/unavailable. */
 export function createTaskMutationArbiter(
-	ctx: ExtensionContext,
+	ctx: ArbiterModelContext,
 	options?: TaskMutationArbiterOptions,
 ): TaskMutationArbiter | undefined {
 	if (process.env.SELESAI_SUBAGENTS_LLM_INTENT_ARBITER === "0") return undefined;
@@ -235,7 +245,7 @@ export function createTaskMutationArbiter(
 		const cached = cache.get(key);
 		if (cached) return cached;
 		const auth = await resolveArbiterAuth(ctx, runtime.model);
-		const verdict = await runArbitration(runtime, auth, task);
+		const verdict = auth ? await runArbitration(runtime, auth, task) : "unavailable";
 		if (cache.size > 200) cache.clear();
 		cache.set(key, verdict);
 		return verdict;

package/dist/extensions/pi-subagents/src/runs/shared/mcp-direct-tool-allowlist.ts

@@ -115,8 +115,11 @@ export function resolveMcpDirectToolResolution(
 		? mergeConfigs(config, { mcpServers: runtimeServers })
 		: config;
 	validateSelectedServerDefinitions(resolvedConfig, selectors);
+	const runtime = Object.keys(runtimeServers).length > 0
+		? { mcpConfig: resolvedConfig, runtimeServerNames: Object.keys(runtimeServers) }
+		: {};
 	const cache = loadMetadataCache();
-	if (!cache) return { selections: [], unresolvedSelectors: selectors };
+	if (!cache) return { selections: [], unresolvedSelectors: selectors, ...runtime };
 	const validMetadata: Record<string, ServerCacheEntry> = {};
 	for (const [serverName, definition] of Object.entries(resolvedConfig.mcpServers)) {
 		const serverCache = cache.servers[serverName];
@@ -131,9 +134,7 @@ export function resolveMcpDirectToolResolution(
 	return {
 		selections: grant.selections,
 		unresolvedSelectors: grant.unresolvedSelectors,
-		...(Object.keys(runtimeServers).length > 0
-			? { mcpConfig: resolvedConfig, runtimeServerNames: Object.keys(runtimeServers) }
-			: {}),
+		...runtime,
 	};
 }
 

package/dist/extensions/pi-subagents/src/runs/shared/model-exclusions.ts

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { splitKnownThinkingSuffix } from "../../shared/model-info.ts";
 import { TEMP_ROOT_DIR } from "../../shared/types.ts";
+import { getAgentDir } from "../../shared/utils.ts";
 
 export const EXCLUSIONS_PATH_ENV = "PI_MODEL_EXCLUSIONS_PATH";
 
@@ -30,6 +31,43 @@ let loadedTTLCeilingMs: number | undefined;
 let persistTimer: ReturnType<typeof setTimeout> | null = null;
 let persistSeq = 0;
 
+const AUTH_FAILURE_PATTERNS = [
+	/auth(?:entication)?/i,
+	/unauthori[sz]ed/i,
+	/forbidden/i,
+	/api key/i,
+	/token expired/i,
+	/invalid key/i,
+];
+
+function isAuthModelExclusion(entry: ModelExclusion): boolean {
+	const reason = entry.reason;
+	return typeof reason === "string" && AUTH_FAILURE_PATTERNS.some((pattern) => pattern.test(reason));
+}
+
+function getAuthStoreMtimeMs(): number | undefined {
+	const authStorePath = path.join(getAgentDir(), "auth.json");
+	try {
+		const stats = fs.statSync(authStorePath);
+		return stats.isFile() && Number.isFinite(stats.mtimeMs) ? stats.mtimeMs : undefined;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+			console.error(`[model-exclusions] Failed to stat Pi auth store at ${authStorePath}; preserving auth-related exclusions:`, error);
+		}
+		return undefined;
+	}
+}
+
+function invalidateAuthExclusions(): void {
+	if (!exclusions.some(isAuthModelExclusion)) return;
+	const authStoreMtimeMs = getAuthStoreMtimeMs();
+	if (authStoreMtimeMs === undefined) return;
+	const retained = exclusions.filter((entry) => !isAuthModelExclusion(entry) || authStoreMtimeMs <= entry.recordedAt);
+	if (retained.length === exclusions.length) return;
+	exclusions = retained;
+	schedulePersist();
+}
+
 /**
  * Override the default TTL applied to newly recorded model exclusions.
  *
@@ -95,23 +133,23 @@ function ensureLoaded(): void {
 		const data = JSON.parse(raw);
 		if (data.version === 1) {
 			if (!Array.isArray(data.exclusions)) throw new Error("Model exclusion store version 1 must contain an exclusions array.");
-			for (let index = 0; index < data.exclusions.length; index++) {
-				const entry = data.exclusions[index];
-				if (!entry || typeof entry !== "object" || Array.isArray(entry)) throw new Error(`Model exclusion store entry ${index} must be an object.`);
-				if (entry.reason !== undefined && typeof entry.reason !== "string") throw new Error(`Model exclusion store entry ${index} has an invalid reason.`);
-				for (const field of ["recordedAt", "expiresAt"] as const) {
-					const timestamp = entry[field];
-					if (typeof timestamp !== "number" || !Number.isFinite(timestamp) || timestamp <= 0 || timestamp > MAX_DATE_TIMESTAMP_MS) {
-						throw new Error(`Model exclusion store entry ${index} has an invalid ${field}.`);
-					}
-				}
-			}
 			const now = Date.now();
-			exclusions = (data.exclusions ?? []).filter((e: ModelExclusion) => e.expiresAt > now);
+			let droppedInvalid = false;
+			exclusions = data.exclusions.flatMap((entry: unknown, index: number) => {
+				const result = readPersistedExclusion(entry, index);
+				if (!result.ok) {
+					droppedInvalid = true;
+					console.warn(`[model-exclusions] Ignoring invalid exclusion: ${result.message}`);
+					return [];
+				}
+				return [result.exclusion];
+			}).filter((e: ModelExclusion) => e.expiresAt > now);
 			const shortened = loadedTTLCeilingMs !== undefined && shortenExclusionsToTTL(exclusions, loadedTTLCeilingMs, now);
 			exclusions = deduplicate(exclusions);
-			if (shortened) schedulePersist();
+			if (droppedInvalid) flushPersist();
+			else if (shortened) schedulePersist();
 		}
+		invalidateAuthExclusions();
 	} catch (error) {
 		if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
 			console.error(`[model-exclusions] Failed to load exclusions from ${getExclusionsFilePath()}:`, error);
@@ -119,6 +157,32 @@ function ensureLoaded(): void {
 	}
 }
 
+type PersistedExclusionRead =
+	| { ok: true; exclusion: ModelExclusion }
+	| { ok: false; message: string };
+
+function invalidPersistedExclusion(index: number, message: string): PersistedExclusionRead {
+	return { ok: false, message: `Model exclusion store entry ${index} ${message}.` };
+}
+
+function readPersistedExclusion(entry: unknown, index: number): PersistedExclusionRead {
+	if (!entry || typeof entry !== "object" || Array.isArray(entry)) return invalidPersistedExclusion(index, "must be an object");
+	const candidate = entry as { modelId?: unknown; provider?: unknown; reason?: unknown; recordedAt?: unknown; expiresAt?: unknown };
+	const { modelId, provider, reason } = candidate;
+	if (modelId !== undefined && (typeof modelId !== "string" || modelId.length === 0)) return invalidPersistedExclusion(index, "has an invalid modelId");
+	if (provider !== undefined && (typeof provider !== "string" || provider.length === 0)) return invalidPersistedExclusion(index, "has an invalid provider");
+	if (reason !== undefined && typeof reason !== "string") return invalidPersistedExclusion(index, "has an invalid reason");
+	const { recordedAt, expiresAt } = candidate;
+	if (typeof recordedAt !== "number" || !Number.isFinite(recordedAt) || recordedAt <= 0 || recordedAt > MAX_DATE_TIMESTAMP_MS) return invalidPersistedExclusion(index, "has an invalid recordedAt");
+	if (typeof expiresAt !== "number" || !Number.isFinite(expiresAt) || expiresAt <= 0 || expiresAt > MAX_DATE_TIMESTAMP_MS) return invalidPersistedExclusion(index, "has an invalid expiresAt");
+	const metadata = { ...(reason === undefined ? {} : { reason }), recordedAt, expiresAt };
+	if (modelId === undefined) {
+		if (provider === undefined) return invalidPersistedExclusion(index, "must include modelId or provider");
+		return { ok: true, exclusion: { provider, ...metadata } };
+	}
+	return { ok: true, exclusion: { modelId, ...(provider === undefined ? {} : { provider }), ...metadata } };
+}
+
 function dedupKey(entry: ModelExclusion): string {
 	return `${entry.provider ?? ""}|${entry.modelId ?? ""}`;
 }
@@ -165,6 +229,7 @@ export function recordModelFailure(options: RecordModelFailureOptions): void {
  */
 export function clearExpiredExclusions(): void {
 	ensureLoaded();
+	invalidateAuthExclusions();
 	prune(exclusions, Date.now());
 	schedulePersist();
 }
@@ -190,7 +255,7 @@ export function clearExclusions(): void {
  */
 function entryMatches(entry: ModelExclusion, candidateModelId: string, candidateProvider: string | undefined, now: number): boolean {
 	if (entry.expiresAt <= now) return false;
-	if (entry.modelId) {
+	if (entry.modelId !== undefined) {
 		if (entry.modelId !== candidateModelId) return false;
 		return !entry.provider || !candidateProvider || entry.provider === candidateProvider;
 	}
@@ -202,6 +267,7 @@ function entryMatches(entry: ModelExclusion, candidateModelId: string, candidate
  */
 export function isExcluded(modelId: string, provider: string): boolean {
 	ensureLoaded();
+	invalidateAuthExclusions();
 	return exclusions.some((entry) => entryMatches(entry, modelId, provider, Date.now()));
 }
 
@@ -213,6 +279,7 @@ export function isExcluded(modelId: string, provider: string): boolean {
  */
 export function findModelExclusion(fullId: string, now = Date.now()): Readonly<ModelExclusion> | undefined {
 	ensureLoaded();
+	invalidateAuthExclusions();
 	const { provider, modelId } = parseModelKey(fullId);
 	return exclusions.find((entry) => entryMatches(entry, modelId, provider, now));
 }
@@ -250,15 +317,17 @@ export function parseModelKey(fullId: string): { provider?: string; modelId: str
 export function filterFallbackCandidates(candidates: string[], opts?: {
 	now?: number;
 	onExcluded?: (candidate: string, exclusion: Readonly<ModelExclusion>) => void;
+	ignoreExclusion?: (candidate: string, exclusion: Readonly<ModelExclusion>) => boolean;
 }): string[] {
 	ensureLoaded();
+	invalidateAuthExclusions();
 	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 exclusion = exclusions.find((entry) => entryMatches(entry, candidateModelId, candidateProvider, timestamp));
+		const exclusion = exclusions.find((entry) => entryMatches(entry, candidateModelId, candidateProvider, timestamp) && opts?.ignoreExclusion?.(raw, entry) !== true);
 		if (exclusion) {
 			opts?.onExcluded?.(raw, exclusion);
 			continue;

package/dist/extensions/pi-subagents/src/runs/shared/model-fallback.ts

@@ -1,4 +1,4 @@
-import { splitKnownThinkingSuffix, type ModelInfo as AvailableModelInfo } from "../../shared/model-info.ts";
+import { splitKnownThinkingSuffix as splitThinkingSuffix, type ModelInfo as AvailableModelInfo } from "../../shared/model-info.ts";
 import type { Usage } from "../../shared/types.ts";
 import { filterFallbackCandidates, findModelExclusion, parseModelKey, recordModelFailure } from "./model-exclusions.ts";
 import { checkModelScope, type ModelScopeCheckRule, type ModelScopeViolation, type ModelSource } from "./model-scope.ts";
@@ -14,13 +14,19 @@ interface ModelAttemptSummary {
 	usage?: Usage;
 }
 
-export function splitThinkingSuffix(model: string): { baseModel: string; thinkingSuffix: string } {
-	return splitKnownThinkingSuffix(model);
-}
+export { splitThinkingSuffix };
 
-export function formatSubagentModelVerificationError(expectedModel: string, observedModel: string, availableModels: AvailableModelInfo[] | undefined): string | undefined {
+/** Aliases apply only to the resolved launch candidate (without its thinking suffix) and the exact raw response ID. */
+export function formatSubagentModelVerificationError(
+	expectedModel: string,
+	observedModel: string,
+	availableModels: AvailableModelInfo[] | undefined,
+	modelResponseAliases?: Record<string, string[]>,
+): string | undefined {
 	if (!availableModels || availableModels.length === 0) return undefined;
 	const expectedBase = splitThinkingSuffix(expectedModel).baseModel;
+	if (modelResponseAliases && Object.hasOwn(modelResponseAliases, expectedBase)
+		&& modelResponseAliases[expectedBase]?.includes(observedModel)) return undefined;
 	const observedBase = splitThinkingSuffix(observedModel).baseModel;
 	if (expectedBase === observedBase) return undefined;
 	const expectedEntry = availableModels.find((entry) => entry.fullId === expectedBase);
@@ -30,7 +36,7 @@ export function formatSubagentModelVerificationError(expectedModel: string, obse
 		const expectedFullIdLeaf = expectedEntry.fullId.slice(expectedEntry.fullId.lastIndexOf("/") + 1);
 		if (expectedIdLeaf === observedBase || expectedFullIdLeaf === observedBase) return undefined;
 	}
-	return `model_verification_failed: child reported a different model than the launch candidate. Expected '${expectedModel}' but observed '${observedModel}'.`;
+	return `model_verification_failed: native Pi child reported a different model than the launch candidate. Expected '${expectedModel}' but observed '${observedModel}'. If you have independently verified this response ID identifies the requested model, declare the exact mapping in modelResponseAliases in ~/.selesai/agent/extensions/subagent/config.json (see docs/configuration.md#modelresponsealiases). Use the resolved provider/model ID without its thinking suffix as the key. This leaves the outgoing request unchanged. Configuration changes affect new independent native runs; resumed native runs retain their launch-time declaration. External CLI adapters do not use this setting.`;
 }
 
 /** Sentinel model value requesting that a subagent inherit the parent session's model. */
@@ -284,6 +290,49 @@ function enforceModelScopes(
 	for (const violation of violations) (onWarn ?? defaultScopeWarn)(violation);
 }
 
+const MODEL_EXCLUSION_DIAGNOSTIC_MAX_LENGTH = 240;
+const MODEL_EXCLUSION_DIAGNOSTIC_MAX_ENTRIES = 20;
+
+function sanitizeModelExclusionDiagnostic(value: string | undefined, fallback: string): string {
+	const normalized = typeof value === "string"
+		? value.replace(/[\u0000-\u001f\u007f\u2028\u2029]+/g, " ").trim()
+		: "";
+	return redactSecretValues(normalized || fallback).slice(0, MODEL_EXCLUSION_DIAGNOSTIC_MAX_LENGTH);
+}
+
+function formatModelExclusionExpiry(expiresAt: number): string {
+	if (!Number.isFinite(expiresAt)) return "unknown";
+	const date = new Date(expiresAt);
+	return Number.isNaN(date.getTime()) ? "unknown" : date.toISOString();
+}
+
+function formatExcludedCandidateEvidence(candidate: string, exclusion: NonNullable<ReturnType<typeof findModelExclusion>>): string {
+	const { provider, modelId } = parseModelKey(candidate);
+	const displayCandidate = sanitizeModelExclusionDiagnostic(candidate, "unknown");
+	const displayModel = sanitizeModelExclusionDiagnostic(modelId, "unknown");
+	const displayProvider = sanitizeModelExclusionDiagnostic(provider ?? exclusion.provider, "unspecified");
+	const reason = sanitizeModelExclusionDiagnostic(exclusion.reason, "runtime-failure");
+	return `${displayCandidate} — model: ${displayModel}; provider: ${displayProvider}; reason: ${reason}; expires: ${formatModelExclusionExpiry(exclusion.expiresAt)}`;
+}
+
+const MODEL_UNAVAILABLE_EXCLUSION_PATTERNS = [
+	/model.*not found/i,
+	/unknown model/i,
+	/model.*unavailable/i,
+	/model.*disabled/i,
+];
+
+function isCurrentRegistryModel(candidate: string, availableModels: AvailableModelInfo[] | undefined): boolean {
+	if (!availableModels || availableModels.length === 0) return false;
+	const { baseModel } = splitThinkingSuffix(candidate);
+	return availableModels.some((entry) => entry.fullId === baseModel);
+}
+
+function ignoreStaleModelUnavailableExclusion(candidate: string, exclusion: NonNullable<ReturnType<typeof findModelExclusion>>, availableModels: AvailableModelInfo[] | undefined): boolean {
+	const reason = exclusion.reason ?? "";
+	return MODEL_UNAVAILABLE_EXCLUSION_PATTERNS.some((pattern) => pattern.test(reason)) && isCurrentRegistryModel(candidate, availableModels);
+}
+
 function throwForExplicitModelExclusion(model: string): void {
 	const exclusion = findModelExclusion(model);
 	if (!exclusion) return;
@@ -419,9 +468,15 @@ export function buildModelCandidates(
 	if (!primaryModel) throwForUnresolvedEnforcedInheritScope(options?.scope, true);
 	const origin = options?.origin ?? (options?.primaryModelFromParent ? "inherited" : "configured");
 	const scopes = configuredScopes(options?.scope);
+	type ExcludedCandidate = { candidate: string; exclusion: NonNullable<ReturnType<typeof findModelExclusion>> };
+	const excludedCandidates: ExcludedCandidate[] = [];
+	let excludedCandidateCount = 0;
 	const warnCachedExclusion = (candidate: string, exclusion: NonNullable<ReturnType<typeof findModelExclusion>>) => {
-		const reason = redactSecretValues((exclusion.reason ?? "runtime-failure").replace(/[\u0000-\u001f\u007f]+/g, " ")).slice(0, 240);
-		console.warn(`[pi-subagents] Skipping model '${candidate}' due to a cached exclusion (reason: ${reason}; expires: ${new Date(exclusion.expiresAt).toISOString()}).`);
+		excludedCandidateCount++;
+		if (excludedCandidates.length < MODEL_EXCLUSION_DIAGNOSTIC_MAX_ENTRIES) excludedCandidates.push({ candidate, exclusion });
+		const displayCandidate = sanitizeModelExclusionDiagnostic(candidate, "unknown");
+		const reason = sanitizeModelExclusionDiagnostic(exclusion.reason, "runtime-failure");
+		console.warn(`[pi-subagents] Skipping model '${displayCandidate}' due to a cached exclusion (reason: ${reason}; expires: ${formatModelExclusionExpiry(exclusion.expiresAt)}).`);
 	};
 	if (origin === "explicit" && primaryModel) {
 		const normalized = resolveRequiredSubagentModelCandidate(primaryModel.trim(), availableModels, preferredProvider);
@@ -433,6 +488,7 @@ export function buildModelCandidates(
 	const candidates: string[] = [];
 	const rawCandidates = [primaryModel, ...(fallbackModels ?? [])];
 	let skippedPrimary: string | undefined;
+	let skippedFallback: string | undefined;
 	for (let index = 0; index < rawCandidates.length; index++) {
 		const raw = rawCandidates[index];
 		if (!raw) continue;
@@ -442,7 +498,10 @@ export function buildModelCandidates(
 			: resolveSubagentModelCandidate(model, availableModels, preferredProvider);
 		if (!normalized) {
 			if (index === 0) skippedPrimary = model;
-			else console.warn(`[pi-subagents] Skipping fallback model '${model}' because it is unavailable in this environment.`);
+			else {
+				skippedFallback ??= model;
+				console.warn(`[pi-subagents] Skipping fallback model '${model}' because it is unavailable in this environment.`);
+			}
 			continue;
 		}
 		if (seen.has(normalized)) continue;
@@ -452,10 +511,21 @@ export function buildModelCandidates(
 		seen.add(normalized);
 		candidates.push(normalized);
 	}
-	const resolved = filterFallbackCandidates(candidates, { onExcluded: warnCachedExclusion });
+	const resolved = filterFallbackCandidates(candidates, {
+		onExcluded: warnCachedExclusion,
+		ignoreExclusion: (candidate, exclusion) => ignoreStaleModelUnavailableExclusion(candidate, exclusion, availableModels),
+	});
 	if (resolved.length === 0) {
 		if (skippedPrimary) resolveRequiredSubagentModelCandidate(skippedPrimary, availableModels, preferredProvider);
-		if (candidates.length > 0) throw new Error(ZERO_USABLE_MODEL_CANDIDATES_ERROR);
+		if (candidates.length === 0 && skippedFallback) resolveRequiredSubagentModelCandidate(skippedFallback, availableModels, preferredProvider);
+		if (candidates.length > 0) {
+			const shownExclusions = excludedCandidates;
+			const omittedExclusions = excludedCandidateCount - shownExclusions.length;
+			const evidence = shownExclusions.length > 0
+				? ` (excluded: ${shownExclusions.map(({ candidate, exclusion }) => formatExcludedCandidateEvidence(candidate, exclusion)).join("; ")}${omittedExclusions > 0 ? `; ... and ${omittedExclusions} more` : ""})`
+				: "";
+			throw new Error(`${ZERO_USABLE_MODEL_CANDIDATES_ERROR}${evidence}`);
+		}
 		return resolved;
 	}
 	if (skippedPrimary) {
@@ -465,6 +535,7 @@ export function buildModelCandidates(
 }
 
 const RETRYABLE_MODEL_FAILURE_PATTERNS = [
+	/^REQUEST_LIMIT_EXCEEDED$/,
 	/rate\s*limit/i,
 	/usage\s*limit/i,
 	/too many requests/i,
@@ -536,8 +607,13 @@ export function isRetryableModelFailureAttempt(input: { error: string | undefine
 	return Boolean(error && input.messages?.some((message) => messageError(message)?.trim() === error));
 }
 
+// Request-shape failures can match broad fallback signals such as "upstream",
+// but do not establish that the model is unhealthy for subsequent requests.
+const REQUEST_SHAPE_FAILURE_PATTERN = /\b(?:bad[ _]request|invalid[ _]argument|invalid_request_error)\b/i;
+
 export function recordRetryableModelFailure(model: string | undefined, error: string | undefined): void {
-	if (!model || !isRetryableModelFailure(error)) return;
+	if (!model || !error || !isRetryableModelFailure(error) || isContextOverflow(error)) return;
+	if (REQUEST_SHAPE_FAILURE_PATTERN.test(error)) return;
 	const { provider, modelId } = parseModelKey(model);
 	recordModelFailure({ modelId, reason: error, ...(provider ? { provider } : {}) });
 }