@selesai/code 0.9.11 → 0.9.12

package/dist/extensions/pi-subagents/src/runs/shared/external-job-runner.ts

@@ -0,0 +1,389 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ExternalJobProviderError, type ExternalJobHandle, type ExternalJobResult, type ExternalJobState } from "../../api/external-job-provider.ts";
+import type { ExternalJobStatus } from "../../shared/types.ts";
+import { requestExternalJobOperation } from "./external-job-bridge.ts";
+
+const STATUS_POLL_INTERVAL_MS = 1_000;
+
+export interface ExternalJobRunResult {
+	output: string;
+	exitCode: number;
+	error?: string;
+	timedOut?: boolean;
+	stopped?: boolean;
+	externalJob: ExternalJobStatus;
+}
+
+export function externalJobPromptDigest(prompt: string): string {
+	return createHash("sha256").update(prompt).digest("hex");
+}
+
+export function externalJobStableJson(value: unknown): string {
+	if (value === null || typeof value !== "object") return JSON.stringify(value);
+	if (Array.isArray(value)) return `[${value.map(externalJobStableJson).join(",")}]`;
+	const record = value as Record<string, unknown>;
+	return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${externalJobStableJson(record[key])}`).join(",")}}`;
+}
+
+export function externalJobFollowUpRequestDigest(input: { provider: string; parentProviderJobId: string; promptDigest: string; options: Record<string, unknown> }): string {
+	return createHash("sha256")
+		.update(externalJobStableJson({ provider: input.provider, parentProviderJobId: input.parentProviderJobId, promptDigest: input.promptDigest, options: input.options }))
+		.digest("hex");
+}
+
+export function externalJobFollowUpRequestId(requestDigest: string): string {
+	return `follow-up-${requestDigest.slice(0, 48)}`;
+}
+
+export function externalJobFollowUpRunId(requestDigest: string): string {
+	const hex = requestDigest.padEnd(32, "0").slice(0, 32).split("");
+	hex[12] = "4";
+	hex[16] = ((Number.parseInt(hex[16]!, 16) & 0x3) | 0x8).toString(16);
+	const value = hex.join("");
+	return `${value.slice(0, 8)}-${value.slice(8, 12)}-${value.slice(12, 16)}-${value.slice(16, 20)}-${value.slice(20, 32)}`;
+}
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function terminal(state: ExternalJobState): boolean {
+	return state === "completed" || state === "failed" || state === "stopped" || state === "blocked";
+}
+
+function formatError(error: ExternalJobProviderError, provider: string): string {
+	const blocking = error.blockingJobId ? ` Blocking provider job: ${error.blockingJobId}.` : "";
+	return `External-job provider '${provider}' failed closed (${error.code}): ${error.message}.${blocking}`;
+}
+
+function isNotFound(error: unknown): boolean {
+	return typeof error === "object" && error !== null && "code" in error && (error as NodeJS.ErrnoException).code === "ENOENT";
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function malformedStatus(statusPath: string): ExternalJobProviderError {
+	return new ExternalJobProviderError(`Malformed external-job status '${statusPath}'. Refusing to redispatch the prompt.`, { code: "status-unreadable" });
+}
+
+function parseExternalJobStatus(value: unknown, statusPath: string): ExternalJobStatus {
+	if (!isRecord(value)) throw malformedStatus(statusPath);
+	const provider = value.provider;
+	const promptDigest = value.promptDigest;
+	const state = value.state;
+	if (typeof provider !== "string" || provider.length === 0) throw malformedStatus(statusPath);
+	if (typeof promptDigest !== "string" || promptDigest.length === 0) throw malformedStatus(statusPath);
+	if (state !== "queued" && state !== "running" && state !== "completed" && state !== "failed" && state !== "stopped" && state !== "blocked") throw malformedStatus(statusPath);
+	if (value.options !== undefined && !isRecord(value.options)) throw malformedStatus(statusPath);
+	const providerJobId = value.providerJobId;
+	const handleUrl = value.handleUrl;
+	const conversationUrl = value.conversationUrl;
+	const resultArtifactPath = value.resultArtifactPath;
+	const failureCode = value.failureCode;
+	const failureMessage = value.failureMessage;
+	const blockingJobId = value.blockingJobId;
+	const startedAt = value.startedAt;
+	const updatedAt = value.updatedAt;
+	if (providerJobId !== undefined && (typeof providerJobId !== "string" || providerJobId.length === 0)) throw malformedStatus(statusPath);
+	if (handleUrl !== undefined && typeof handleUrl !== "string") throw malformedStatus(statusPath);
+	if (conversationUrl !== undefined && typeof conversationUrl !== "string") throw malformedStatus(statusPath);
+	if (resultArtifactPath !== undefined && typeof resultArtifactPath !== "string") throw malformedStatus(statusPath);
+	if (failureCode !== undefined && typeof failureCode !== "string") throw malformedStatus(statusPath);
+	if (failureMessage !== undefined && typeof failureMessage !== "string") throw malformedStatus(statusPath);
+	if (blockingJobId !== undefined && typeof blockingJobId !== "string") throw malformedStatus(statusPath);
+	const operation = value.operation;
+	const sourceRunId = value.sourceRunId;
+	const sourceStepIndex = value.sourceStepIndex;
+	const parentProviderJobId = value.parentProviderJobId;
+	const requestId = value.requestId;
+	const requestDigest = value.requestDigest;
+	if (operation !== undefined && operation !== "start" && operation !== "follow-up") throw malformedStatus(statusPath);
+	if (sourceRunId !== undefined && (typeof sourceRunId !== "string" || sourceRunId.length === 0)) throw malformedStatus(statusPath);
+	if (sourceStepIndex !== undefined && (typeof sourceStepIndex !== "number" || !Number.isInteger(sourceStepIndex) || sourceStepIndex < 0)) throw malformedStatus(statusPath);
+	if (parentProviderJobId !== undefined && (typeof parentProviderJobId !== "string" || parentProviderJobId.length === 0)) throw malformedStatus(statusPath);
+	if (requestId !== undefined && (typeof requestId !== "string" || requestId.length === 0)) throw malformedStatus(statusPath);
+	if (requestDigest !== undefined && (typeof requestDigest !== "string" || requestDigest.length === 0)) throw malformedStatus(statusPath);
+	if (startedAt !== undefined && typeof startedAt !== "number") throw malformedStatus(statusPath);
+	if (updatedAt !== undefined && typeof updatedAt !== "number") throw malformedStatus(statusPath);
+	return {
+		provider,
+		promptDigest,
+		...(operation ? { operation } : {}),
+		...(sourceRunId ? { sourceRunId } : {}),
+		...(sourceStepIndex !== undefined ? { sourceStepIndex } : {}),
+		...(parentProviderJobId ? { parentProviderJobId } : {}),
+		...(requestId ? { requestId } : {}),
+		...(requestDigest ? { requestDigest } : {}),
+		options: value.options ?? {},
+		state,
+		...(providerJobId ? { providerJobId } : {}),
+		...(handleUrl ? { handleUrl } : {}),
+		...(conversationUrl ? { conversationUrl } : {}),
+		...(resultArtifactPath ? { resultArtifactPath } : {}),
+		...(failureCode ? { failureCode } : {}),
+		...(failureMessage ? { failureMessage } : {}),
+		...(blockingJobId ? { blockingJobId } : {}),
+		...(startedAt !== undefined ? { startedAt } : {}),
+		...(updatedAt !== undefined ? { updatedAt } : {}),
+	};
+}
+
+function readExistingExternalJob(asyncDir: string, stepIndex: number): ExternalJobStatus | undefined {
+	const statusPath = path.join(asyncDir, "status.json");
+	let raw: string;
+	try {
+		raw = fs.readFileSync(statusPath, "utf-8");
+	} catch (error) {
+		if (isNotFound(error)) return undefined;
+		throw new ExternalJobProviderError(`Unreadable external-job status '${statusPath}'. Refusing to redispatch the prompt.`, { code: "status-unreadable", cause: error });
+	}
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (error) {
+		throw new ExternalJobProviderError(`Malformed external-job status '${statusPath}'. Refusing to redispatch the prompt.`, { code: "status-unreadable", cause: error });
+	}
+	if (!isRecord(parsed) || !Array.isArray(parsed.steps)) throw malformedStatus(statusPath);
+	const step = parsed.steps[stepIndex];
+	if (step === undefined || !isRecord(step)) throw malformedStatus(statusPath);
+	if (step.externalJob === undefined) return undefined;
+	return parseExternalJobStatus(step.externalJob, statusPath);
+}
+
+function externalJobLineage(followUp: ExternalJobFollowUpDescriptor | undefined, previous: ExternalJobStatus | undefined) {
+	return {
+		operation: followUp ? "follow-up" as const : previous?.operation,
+		...(followUp ? {
+			sourceRunId: followUp.sourceRunId,
+			sourceStepIndex: followUp.sourceStepIndex,
+			parentProviderJobId: followUp.parentProviderJobId,
+			requestId: followUp.requestId,
+			requestDigest: followUp.requestDigest,
+		} : {
+			...(previous?.sourceRunId ? { sourceRunId: previous.sourceRunId } : {}),
+			...(previous?.sourceStepIndex !== undefined ? { sourceStepIndex: previous.sourceStepIndex } : {}),
+			...(previous?.parentProviderJobId ? { parentProviderJobId: previous.parentProviderJobId } : {}),
+			...(previous?.requestId ? { requestId: previous.requestId } : {}),
+			...(previous?.requestDigest ? { requestDigest: previous.requestDigest } : {}),
+		}),
+	};
+}
+
+function statusFromHandle(input: {
+	provider: string;
+	promptDigest: string;
+	options: Record<string, unknown>;
+	followUp?: ExternalJobFollowUpDescriptor;
+	startedAt?: number;
+	previous?: ExternalJobStatus;
+	handle: ExternalJobHandle;
+	resultArtifactPath?: string;
+}): ExternalJobStatus {
+	return {
+		provider: input.provider,
+		providerJobId: input.handle.providerJobId,
+		promptDigest: input.promptDigest,
+		...externalJobLineage(input.followUp, input.previous),
+		options: input.options,
+		handleUrl: input.handle.handleUrl ?? input.previous?.handleUrl,
+		conversationUrl: input.handle.conversationUrl ?? input.previous?.conversationUrl,
+		resultArtifactPath: input.resultArtifactPath ?? input.previous?.resultArtifactPath,
+		state: input.handle.state,
+		failureCode: input.handle.failureCode,
+		failureMessage: input.handle.failureMessage,
+		blockingJobId: input.handle.blockingJobId,
+		startedAt: input.previous?.startedAt ?? input.startedAt,
+		updatedAt: Date.now(),
+	};
+}
+
+function failureStatus(input: {
+	provider: string;
+	promptDigest: string;
+	options: Record<string, unknown>;
+	followUp?: ExternalJobFollowUpDescriptor;
+	previous?: ExternalJobStatus;
+	code: string;
+	message: string;
+	blockingJobId?: string;
+}): ExternalJobStatus {
+	return {
+		provider: input.provider,
+		providerJobId: input.previous?.providerJobId,
+		promptDigest: input.promptDigest,
+		...externalJobLineage(input.followUp, input.previous),
+		options: input.options,
+		handleUrl: input.previous?.handleUrl,
+		conversationUrl: input.previous?.conversationUrl,
+		resultArtifactPath: input.previous?.resultArtifactPath,
+		state: input.blockingJobId ? "blocked" : "failed",
+		failureCode: input.code,
+		failureMessage: input.message,
+		blockingJobId: input.blockingJobId,
+		startedAt: input.previous?.startedAt,
+		updatedAt: Date.now(),
+	};
+}
+
+function resultOutput(result: ExternalJobResult, artifactPath: string | undefined): string {
+	if (result.output?.trim()) return result.output.trim();
+	if (artifactPath) return `External job finished. Result artifact: ${artifactPath}`;
+	return "External job finished without text output.";
+}
+
+function blocksStartRedispatch(status: ExternalJobStatus, provider: string, promptDigest: string): boolean {
+	return status.provider === provider
+		&& status.promptDigest === promptDigest
+		&& !status.providerJobId
+		&& status.failureCode !== "provider-unavailable";
+}
+
+interface ExternalJobFollowUpDescriptor {
+	sourceRunId: string;
+	sourceStepIndex: number;
+	parentProviderJobId: string;
+	requestId: string;
+	requestDigest: string;
+}
+
+function sameFollowUpLineage(status: ExternalJobStatus, followUp: ExternalJobFollowUpDescriptor | undefined): boolean {
+	if (!followUp) return status.operation !== "follow-up";
+	return status.operation === "follow-up"
+		&& status.sourceRunId === followUp.sourceRunId
+		&& status.sourceStepIndex === followUp.sourceStepIndex
+		&& status.parentProviderJobId === followUp.parentProviderJobId
+		&& status.requestId === followUp.requestId
+		&& status.requestDigest === followUp.requestDigest;
+}
+
+export async function runExternalJob(input: {
+	provider: string;
+	options?: Record<string, unknown>;
+	cwd: string;
+	prompt: string;
+	asyncDir: string;
+	stepIndex: number;
+	runId: string;
+	agent: string;
+	sessionId?: string;
+	registerTimeout?: (stop: (() => void) | undefined) => void;
+	registerStop?: (stop: (() => void) | undefined) => void;
+	timeoutMessage?: string;
+	stopMessage?: string;
+	onExternalJob?: (status: ExternalJobStatus) => void;
+	followUp?: ExternalJobFollowUpDescriptor;
+}): Promise<ExternalJobRunResult> {
+	const provider = input.provider;
+	const options = input.options ?? {};
+	const promptDigest = externalJobPromptDigest(input.prompt);
+	const startedAt = Date.now();
+	let timedOut = false;
+	let stopped = false;
+	let current: ExternalJobStatus | undefined;
+	const timeout = () => { timedOut = true; };
+	const stop = () => { stopped = true; };
+	input.registerTimeout?.(timeout);
+	input.registerStop?.(stop);
+	const publish = (status: ExternalJobStatus) => {
+		current = status;
+		input.onExternalJob?.(status);
+	};
+	const localCancellation = () => {
+		if (!timedOut && !stopped) return undefined;
+		const message = stopped
+			? input.stopMessage ?? `Subagent stopped locally before external provider '${provider}' returned a job id. The provider start may still be running.`
+			: input.timeoutMessage ?? `Subagent timed out locally before external provider '${provider}' returned a job id. The provider start may still be running.`;
+		return new ExternalJobProviderError(message, { code: stopped ? "local-stop" : "local-timeout" });
+	};
+	try {
+		current = readExistingExternalJob(input.asyncDir, input.stepIndex);
+		let handle: ExternalJobHandle;
+		if (current?.providerJobId) {
+			if (current.provider !== provider || current.promptDigest !== promptDigest || !sameFollowUpLineage(current, input.followUp)) {
+				const message = `Existing external job '${current.providerJobId}' does not match provider, prompt digest, or follow-up lineage. Refusing to redispatch prompt.`;
+				const status = failureStatus({ provider, promptDigest, options, followUp: input.followUp, previous: current, code: "recovery-mismatch", message });
+				publish(status);
+				return { output: message, exitCode: 1, error: message, externalJob: status };
+			}
+			handle = await requestExternalJobOperation<ExternalJobHandle>(input.asyncDir, { operation: "reattach", provider, providerJobId: current.providerJobId });
+		} else {
+			if (current && blocksStartRedispatch(current, provider, promptDigest)) {
+				const message = `External-job ${input.followUp ? "follow-up" : "start"} for provider '${provider}' previously ended without a durable provider job id. Refusing to redispatch the prompt automatically.`;
+				const status = failureStatus({ provider, promptDigest, options, followUp: input.followUp, previous: current, code: input.followUp ? "dispatch-redispatch-blocked" : "start-redispatch-blocked", message });
+				publish(status);
+				return { output: message, exitCode: 1, error: message, externalJob: status };
+			}
+			publish({ provider, promptDigest, ...(input.followUp ? { operation: "follow-up" as const, ...input.followUp } : {}), options, state: "queued", startedAt, updatedAt: Date.now() });
+			if (input.followUp) {
+				handle = await requestExternalJobOperation<ExternalJobHandle>(input.asyncDir, {
+					operation: "follow-up",
+					provider,
+					followUp: {
+						prompt: input.prompt,
+						promptDigest,
+						cwd: input.cwd,
+						runId: input.runId,
+						stepIndex: input.stepIndex,
+						agent: input.agent,
+						options,
+						...(input.sessionId ? { sessionId: input.sessionId } : {}),
+						...input.followUp,
+					},
+				}, undefined, localCancellation);
+			} else {
+				handle = await requestExternalJobOperation<ExternalJobHandle>(input.asyncDir, {
+					operation: "start",
+					provider,
+					start: {
+						prompt: input.prompt,
+						promptDigest,
+						cwd: input.cwd,
+						runId: input.runId,
+						stepIndex: input.stepIndex,
+						agent: input.agent,
+						options,
+						...(input.sessionId ? { sessionId: input.sessionId } : {}),
+					},
+				}, undefined, localCancellation);
+			}
+		}
+		publish(statusFromHandle({ provider, promptDigest, options, followUp: input.followUp, startedAt, previous: current, handle }));
+		while (!terminal(handle.state)) {
+			if (timedOut || stopped) {
+				const message = stopped
+					? input.stopMessage ?? `Subagent stopped locally; external provider job '${handle.providerJobId}' may still be running.`
+					: input.timeoutMessage ?? `Subagent timed out locally; external provider job '${handle.providerJobId}' may still be running.`;
+				return { output: message, exitCode: 1, error: message, ...(timedOut ? { timedOut: true } : {}), ...(stopped ? { stopped: true } : {}), externalJob: current! };
+			}
+			await sleep(STATUS_POLL_INTERVAL_MS);
+			handle = await requestExternalJobOperation<ExternalJobHandle>(input.asyncDir, { operation: "status", provider, providerJobId: handle.providerJobId });
+			publish(statusFromHandle({ provider, promptDigest, options, followUp: input.followUp, previous: current, handle }));
+		}
+		const result = await requestExternalJobOperation<ExternalJobResult>(input.asyncDir, { operation: "result", provider, providerJobId: handle.providerJobId });
+		let artifactPath = result.artifactPath;
+		if (!artifactPath && result.output !== undefined) {
+			artifactPath = path.join(input.asyncDir, `external-job-${input.stepIndex}.result.md`);
+			fs.writeFileSync(artifactPath, result.output, "utf-8");
+		}
+		const finalStatus = statusFromHandle({ provider, promptDigest, options, followUp: input.followUp, previous: current, handle: result, resultArtifactPath: artifactPath });
+		publish(finalStatus);
+		const output = resultOutput(result, artifactPath);
+		const error = result.state === "completed" ? undefined : result.failureMessage ?? `External job ${result.state}.`;
+		return { output, exitCode: result.state === "completed" ? 0 : 1, ...(error ? { error } : {}), externalJob: finalStatus };
+	} catch (error) {
+		const providerError = error instanceof ExternalJobProviderError
+			? error
+			: new ExternalJobProviderError(error instanceof Error ? error.message : String(error), { code: "provider-error", cause: error });
+		const message = formatError(providerError, provider);
+		const status = failureStatus({ provider, promptDigest, options, followUp: input.followUp, previous: current, code: providerError.code, message, ...(providerError.blockingJobId ? { blockingJobId: providerError.blockingJobId } : {}) });
+		publish(status);
+		return { output: message, exitCode: 1, error: message, ...(timedOut ? { timedOut: true } : {}), ...(stopped ? { stopped: true } : {}), externalJob: status };
+	} finally {
+		input.registerTimeout?.(undefined);
+		input.registerStop?.(undefined);
+	}
+}

package/dist/extensions/pi-subagents/src/runs/shared/fast-mode-extension.ts

@@ -0,0 +1,10 @@
+import type { ExtensionAPI } from "@selesai/code";
+
+function withPriorityServiceTier(payload: unknown): unknown {
+	if (!payload || typeof payload !== "object" || Array.isArray(payload)) return payload;
+	return { ...payload, service_tier: "priority" };
+}
+
+export default function registerSubagentFastModeExtension(pi: ExtensionAPI): void {
+	pi.on("before_provider_request", (event) => ({ payload: withPriorityServiceTier(event.payload) }));
+}

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

@@ -32,6 +32,12 @@ interface ServerEntry {
 	cwd?: string;
 	url?: string;
 	headers?: Record<string, string>;
+	requestHeadersCommand?: {
+		command: string;
+		args?: string[];
+		env?: Record<string, string>;
+		timeoutMs?: number;
+	};
 	auth?: "oauth" | "bearer" | false;
 	bearerToken?: string;
 	bearerTokenEnv?: string;
@@ -279,6 +285,14 @@ export function computeMcpServerHash(definition: ServerEntry): string {
 		cwd: resolveConfigPath(definition.cwd),
 		url: resolveServerUrl(definition),
 		headers: interpolateEnvRecord(definition.headers),
+		requestHeadersCommand: definition.requestHeadersCommand
+			? {
+				command: interpolateEnvVars(definition.requestHeadersCommand.command),
+				args: definition.requestHeadersCommand.args?.map(interpolateEnvVars),
+				env: interpolateEnvRecord(definition.requestHeadersCommand.env),
+				timeoutMs: definition.requestHeadersCommand.timeoutMs,
+			}
+			: undefined,
 		auth: definition.auth,
 		bearerToken: resolveBearerToken(definition),
 		bearerTokenEnv: definition.bearerTokenEnv,

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

@@ -0,0 +1,243 @@
+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";
+
+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 = splitKnownThinkingSuffix(fullId).baseModel;
+	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;
+}