pi-subagents 0.67.0 → 0.68.0

package/src/watchdog/types.ts

@@ -15,8 +15,8 @@ export const WATCHDOG_WARNING_CATEGORIES = [
 ] as const;
 export type WatchdogCategory = typeof WATCHDOG_WARNING_CATEGORIES[number];
 
-export const WATCHDOG_WARNING_CONFIDENCES = ["medium", "high"] as const;
-export type WatchdogConfidence = typeof WATCHDOG_WARNING_CONFIDENCES[number];
+export const WATCHDOG_WARNING_IMPORTANCES = ["low", "medium", "high"] as const;
+export type WatchdogImportance = typeof WATCHDOG_WARNING_IMPORTANCES[number];
 
 export const WATCHDOG_WARNING_SOURCES = ["main", "child", "lsp"] as const;
 export type WatchdogWarningSource = typeof WATCHDOG_WARNING_SOURCES[number];
@@ -44,11 +44,11 @@ export type WatchdogWarningState = typeof WATCHDOG_WARNING_STATES[number];
 
 export interface WatchdogWarning {
 	severity: WatchdogSeverity;
+	importance: WatchdogImportance;
 	summary: string;
 	evidence: string;
 	recommendedAction: string;
 	category?: WatchdogCategory;
-	confidence?: WatchdogConfidence;
 	source?: WatchdogWarningSource;
 	agent?: string;
 	runId?: string;
@@ -87,14 +87,12 @@ export interface WatchdogCadenceConfig {
 export interface WatchdogEndpointConfig {
 	enabled: boolean;
 	model?: string;
-	fallbackModels?: string[];
 	thinking?: string | false;
 }
 
 export interface WatchdogChildOverrideConfig {
 	enabled?: boolean;
 	model?: string;
-	fallbackModels?: string[];
 	thinking?: string | false;
 	cadence?: Partial<WatchdogCadenceConfig>;
 }

package/src/watchdog/warning-format.ts

@@ -34,12 +34,12 @@ export function formatWatchdogWarningContent(warning: WatchdogWarning): string {
 	const details = normalizeWatchdogWarningDetails(warning);
 	const attrs = [
 		`severity="${escapeXmlAttribute(details.severity)}"`,
+		`importance="${escapeXmlAttribute(details.importance)}"`,
 		`category="${escapeXmlAttribute(details.category)}"`,
 		`source="${escapeXmlAttribute(details.source)}"`,
 		`guidance="weigh, don't blindly obey"`,
 	];
 	const optionalTags = [
-		tag("confidence", details.confidence),
 		tag("agent", details.agent),
 		tag("run_id", details.runId),
 		tag("state", details.state),

package/src/workflows/scripted-workflow.ts

@@ -1,4 +1,4 @@
-import { readFileSync } from "node:fs";
+import { accessSync, constants, readFileSync, realpathSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, resolve as resolvePath } from "node:path";
 import { Worker } from "node:worker_threads";
@@ -550,7 +550,7 @@ function runLanes(laneSpecs) {
       generatedKey: stage.generatedKey,
       ...workflowPlanStringMetadata(stage.params),
       ...(typeof stage.params.as === "string" && stage.params.as.trim() ? { outputName: stage.params.as.trim() } : {}),
-      ...(stage.params.outputSchema !== undefined ? { structured: true } : {}),
+      ...(stage.params.outputSchema ? { structured: true } : {}),
     })),
   })) });
   const firstItems = lanes.map((lane) => {
@@ -952,6 +952,12 @@ function omitUndefinedWorkflowValues(value, seen = new Set()) {
   return normalized;
 }
 
+function deepFreezeWorkflowArgs(value) {
+  if (value === null || typeof value !== "object" || Object.isFrozen(value)) return value;
+  for (const entry of Object.values(value)) deepFreezeWorkflowArgs(entry);
+  return Object.freeze(value);
+}
+
 parentPort.on("message", async (message) => {
   if (message.type === "response") {
     const entry = pending.get(message.callId);
@@ -971,6 +977,9 @@ parentPort.on("message", async (message) => {
     if (message.stateEnabled) sandbox.state = state;
     const context = vm.createContext(sandbox, { codeGeneration: { strings: false, wasm: false } });
     contextObjectPrototype = vm.runInContext("Object.prototype", context);
+    // Rebuild args inside the VM realm: a worker-realm object would expose the worker's unrestricted
+    // Function through args.constructor.constructor, bypassing codeGeneration.strings: false.
+    sandbox.args = deepFreezeWorkflowArgs(vm.runInContext("JSON.parse", context)(JSON.stringify(message.args ?? {})));
     let compiled;
     try {
       assertPortableWorkflowScript(message.script);
@@ -1169,6 +1178,10 @@ export interface WorkflowChildSettledNotification {
 
 export interface RunWorkflowScriptOptions {
 	script: string;
+	/** Normalized raw-script input exposed as the deeply frozen sandbox global `args`. */
+	args?: Readonly<Record<string, unknown>>;
+	/** Parent-session cwd used to recover a stale process cwd. */
+	processCwd?: string;
 	/** Workflow run ID for notifications. Required when onChildSettled is provided. */
 	workflowRunId?: string;
 	/** Host-only first-slice admission context. It is never sent to the workflow worker. */
@@ -1922,6 +1935,32 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 	}
 	const launchSemaphore = new Semaphore(options.globalConcurrencyLimit ?? DEFAULT_GLOBAL_CONCURRENCY_LIMIT);
 
+	if (options.processCwd !== undefined) {
+		let staleCwd = false;
+		try {
+			realpathSync(process.cwd());
+		} catch (error) {
+			const code = typeof error === "object" && error !== null && "code" in error ? (error as NodeJS.ErrnoException).code : undefined;
+			if (code !== "ENOENT") throw new Error("Workflow current cwd could not be validated.", { cause: error });
+			staleCwd = true;
+		}
+		try {
+			if (staleCwd) process.chdir(options.processCwd);
+			else {
+				const target = realpathSync(options.processCwd);
+				if (!statSync(target).isDirectory()) {
+					const error = new Error(`ENOTDIR: not a directory, access '${target}'`) as NodeJS.ErrnoException;
+					error.code = "ENOTDIR";
+					throw error;
+				}
+				accessSync(target, constants.X_OK);
+			}
+		} catch (error) {
+			const detail = error instanceof Error ? error.message : String(error);
+			throw new Error(`Workflow process cwd is unavailable: ${options.processCwd}: ${detail}`, { cause: error });
+		}
+	}
+
 	let acornPath: string;
 	try {
 		acornPath = resolveWorkflowParserEntry();
@@ -2509,6 +2548,6 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 			respond(deliver(promise), `runs.run('${key}') result`, (error) => children.set(key, responseBoundaryFailure(key, error)));
 		});
 
-		worker.postMessage({ type: "start", script: options.script, stateEnabled: options.state !== undefined });
+		worker.postMessage({ type: "start", script: options.script, ...(options.args ? { args: options.args } : {}), stateEnabled: options.state !== undefined });
 	});
 }

package/src/workflows/workflow-receipt.ts

@@ -37,6 +37,7 @@ export function buildWorkflowReceipt(input: {
 	workflowRunId: string;
 	state: WorkflowReceiptState;
 	children: WorkflowScriptChildResult[];
+	argsDigest?: string;
 	hostSteps?: WorkflowReceipt["hostSteps"];
 	workflowChildren?: WorkflowReceipt["workflowChildren"];
 	resource?: WorkflowResourceProvenance;
@@ -44,6 +45,7 @@ export function buildWorkflowReceipt(input: {
 	createdAt?: number;
 }): WorkflowReceipt {
 	const workflowRunId = assertSafeRunId(input.workflowRunId, "workflowRunId");
+	if (input.argsDigest !== undefined && !/^[a-f0-9]{64}$/u.test(input.argsDigest)) throw new Error("workflow receipt argsDigest must be a lowercase SHA-256 digest.");
 	if (input.workflowChildren?.workflowRunId !== undefined && input.workflowChildren.workflowRunId !== workflowRunId) throw new Error("workflowChildren workflowRunId does not match its receipt.");
 	const entries: Record<string, WorkflowReceiptEntry> = Object.create(null) as Record<string, WorkflowReceiptEntry>;
 	for (const child of input.children) {
@@ -75,7 +77,7 @@ export function buildWorkflowReceipt(input: {
 	const hostSteps = input.hostSteps?.map((hostStep, index) => parseHostStepNode(hostStep, `workflow receipt hostSteps[${index}]`));
 	if (hostSteps) assertUniqueHostStepIds(hostSteps, "workflow receipt");
 	const resource = parseWorkflowResource(input.resource, "workflow receipt");
-	return { version: WORKFLOW_RECEIPT_VERSION, workflowRunId, state: input.state, createdAt: input.createdAt ?? Date.now(), entries, ...(resource ? { resource } : {}), ...(hostSteps?.length ? { hostSteps } : {}), ...(input.workflowChildren ? { workflowChildren: input.workflowChildren } : {}), ...(input.terminalOutcome ? { terminalOutcome: input.terminalOutcome } : {}) };
+	return { version: WORKFLOW_RECEIPT_VERSION, workflowRunId, state: input.state, createdAt: input.createdAt ?? Date.now(), entries, ...(input.argsDigest ? { argsDigest: input.argsDigest } : {}), ...(resource ? { resource } : {}), ...(hostSteps?.length ? { hostSteps } : {}), ...(input.workflowChildren ? { workflowChildren: input.workflowChildren } : {}), ...(input.terminalOutcome ? { terminalOutcome: input.terminalOutcome } : {}) };
 }
 
 export function writeWorkflowReceipt(asyncDir: string, receipt: WorkflowReceipt): string {
@@ -115,12 +117,26 @@ const EXTERNAL_CLI_CAPABILITIES = {
 	extensionBindings: false,
 } as const;
 
+function parseExternalCliMachine(value: unknown, label: string): void {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label}.machine must be an object.`);
+	const machine = value as Record<string, unknown>;
+	const unknownMachine = Object.keys(machine).filter((field) => !["provider", "id", "label", "target", "session", "cwd", "remoteGit"].includes(field));
+	if (unknownMachine.length > 0) throw new Error(`${label}.machine has unsupported fields: ${unknownMachine.join(", ")}.`);
+	if (machine.provider !== "herdr" || typeof machine.id !== "string" || !machine.id.trim() || typeof machine.target !== "string" || !machine.target.trim() || typeof machine.cwd !== "string" || !machine.cwd.trim()) throw new Error(`${label}.machine is invalid.`);
+	for (const field of ["label", "session"] as const) if (machine[field] !== undefined && (typeof machine[field] !== "string" || !machine[field].trim())) throw new Error(`${label}.machine.${field} is invalid.`);
+	if (machine.remoteGit === undefined) return;
+	if (!machine.remoteGit || typeof machine.remoteGit !== "object" || Array.isArray(machine.remoteGit)) throw new Error(`${label}.machine.remoteGit must be an object.`);
+	const remoteGit = machine.remoteGit as Record<string, unknown>;
+	const unknownRemoteGit = Object.keys(remoteGit).filter((field) => !["head", "branch", "dirty"].includes(field));
+	if (unknownRemoteGit.length > 0 || (remoteGit.head !== undefined && (typeof remoteGit.head !== "string" || !remoteGit.head.trim())) || (remoteGit.branch !== undefined && (typeof remoteGit.branch !== "string" || !remoteGit.branch.trim())) || (remoteGit.dirty !== undefined && typeof remoteGit.dirty !== "boolean")) throw new Error(`${label}.machine.remoteGit is invalid.`);
+}
+
 function parseExternalCliReceiptMetadata(value: unknown, key: string, source: string): ExternalCliReceiptMetadata | undefined {
 	if (value === undefined) return undefined;
 	const label = `Invalid workflow receipt '${source}': entry '${key}' externalAdapter`;
 	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object.`);
 	const metadata = value as Record<string, unknown>;
-	const unknownMetadata = Object.keys(metadata).filter((field) => !["adapter", "capabilities", "safety", "outputArtifacts", "handoff", "supervisor", "nonResumableReason"].includes(field));
+	const unknownMetadata = Object.keys(metadata).filter((field) => !["adapter", "capabilities", "machine", "safety", "outputArtifacts", "handoff", "supervisor", "nonResumableReason"].includes(field));
 	if (unknownMetadata.length > 0) throw new Error(`${label} has unsupported fields: ${unknownMetadata.join(", ")}.`);
 	const adapter = metadata.adapter;
 	if (!adapter || typeof adapter !== "object" || Array.isArray(adapter)) throw new Error(`${label}.adapter must be an object.`);
@@ -136,6 +152,7 @@ function parseExternalCliReceiptMetadata(value: unknown, key: string, source: st
 	for (const [capability, expected] of Object.entries(EXTERNAL_CLI_CAPABILITIES)) {
 		if (capabilityRecord[capability] !== expected) throw new Error(`${label}.capabilities.${capability} is invalid.`);
 	}
+	if (metadata.machine !== undefined) parseExternalCliMachine(metadata.machine, label);
 	const safety = metadata.safety;
 	if (adapterRecord.id === "codex-exec") {
 		if (!safety || typeof safety !== "object" || Array.isArray(safety)) throw new Error(`${label}.safety is missing.`);
@@ -330,10 +347,11 @@ export function readWorkflowReceipt(asyncDirRoot: string, workflowRunId: string)
 		assertUniqueHostStepIds(hostSteps, receiptPath);
 	}
 	const workflowResolution = parseWorkflowResolution(receipt.workflowResolution, receiptPath);
+	if (receipt.argsDigest !== undefined && (typeof receipt.argsDigest !== "string" || !/^[a-f0-9]{64}$/u.test(receipt.argsDigest))) throw new Error(`Invalid workflow receipt '${receiptPath}': argsDigest is invalid.`);
 	const resource = parseWorkflowResource(receipt.resource, receiptPath);
 	const terminalOutcome = parseTerminalOutcome(receipt.terminalOutcome, `Invalid workflow receipt '${receiptPath}': terminalOutcome`);
 	const recovery = parseRecovery(receipt.recovery, workflowRunId, entries, receiptPath);
-	return { version: 1, workflowRunId, state: receipt.state, createdAt: receipt.createdAt, entries, ...(resource ? { resource } : {}), ...(hostSteps?.length ? { hostSteps } : {}), ...(workflowChildren ? { workflowChildren } : {}), ...(workflowResolution ? { workflowResolution } : {}), ...(terminalOutcome ? { terminalOutcome } : {}), ...(recovery ? { recovery } : {}) };
+	return { version: 1, workflowRunId, state: receipt.state, createdAt: receipt.createdAt, entries, ...(receipt.argsDigest ? { argsDigest: receipt.argsDigest } : {}), ...(resource ? { resource } : {}), ...(hostSteps?.length ? { hostSteps } : {}), ...(workflowChildren ? { workflowChildren } : {}), ...(workflowResolution ? { workflowResolution } : {}), ...(terminalOutcome ? { terminalOutcome } : {}), ...(recovery ? { recovery } : {}) };
 }
 
 export function resolveWorkflowReceiptResumeEntry(input: {

package/src/workflows/workflow-resources.ts

@@ -125,7 +125,7 @@ function validatePlainJson(value: unknown, path: string, depth = 0): void {
 	}
 }
 
-function normalizeArgs(value: unknown): { args: Record<string, unknown> } | { error: string } {
+export function normalizeWorkflowArgs(value: unknown): { args: Record<string, unknown> } | { error: string } {
 	if (value === undefined) return { args: {} };
 	if (!isPlainRecord(value)) return { error: "workflow args must be a plain JSON object." };
 	try {
@@ -137,6 +137,17 @@ function normalizeArgs(value: unknown): { args: Record<string, unknown> } | { er
 	}
 }
 
+export function deepFreezeWorkflowArgs<T extends Record<string, unknown>>(args: T): Readonly<T> {
+	deepFreezeWorkflowValue(args);
+	return args;
+}
+
+function deepFreezeWorkflowValue(value: unknown): void {
+	if (!Array.isArray(value) && !isPlainRecord(value)) return;
+	for (const entry of Object.values(value)) deepFreezeWorkflowValue(entry);
+	Object.freeze(value);
+}
+
 function resolveRunCi(args: Readonly<Record<string, unknown>>): ReturnType<WorkflowResourceDefinition["resolve"]> {
 	const allowed = new Set(["command", "timeoutMs"]);
 	const unsupported = Object.keys(args).filter((key) => !allowed.has(key));
@@ -191,7 +202,7 @@ function resolveResource(nameValue: unknown, argsValue?: unknown, sessionId?: st
 	if (!RESOURCE_NAME_PATTERN.test(name)) return { ok: false, error: "workflow must use a safe resource name." };
 	const resource = findWorkflowResource(name) ?? (sessionId ? registry().bySession.get(sessionId)?.get(name) : undefined);
 	if (!resource) return { ok: false, error: `Unknown workflow resource '${name}'. Available resources: ${listWorkflowResourceNames().join(", ")}.` };
-	const normalizedArgs = normalizeArgs(argsValue);
+	const normalizedArgs = normalizeWorkflowArgs(argsValue);
 	if ("error" in normalizedArgs) return { ok: false, error: normalizedArgs.error };
 	const resolved = resource.resolve(normalizedArgs.args);
 	if (resolved && typeof (resolved as unknown as { then?: unknown }).then === "function") {

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

@@ -1,374 +0,0 @@
-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";
-
-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;
-/** Default duration for a new model exclusion when no per-record TTL is supplied. */
-export const DEFAULT_MODEL_EXCLUSION_TTL_MS = 24 * 60 * 60_000;
-/** Keeps a new expiry safely below JavaScript's maximum Date timestamp. */
-export const MAX_MODEL_EXCLUSION_TTL_MS = 8_000_000_000_000_000;
-const MAX_DATE_TIMESTAMP_MS = 8_640_000_000_000_000;
-let defaultTTLMs = DEFAULT_MODEL_EXCLUSION_TTL_MS;
-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.
- *
- * @param ms Duration in milliseconds. Must be finite and positive.
- * @returns Nothing.
- */
-// TEST:test/unit/model-exclusions.test.ts[model exclusions — TTL expiry]
-export function setDefaultTTL(ms: number, options?: { shortenExisting?: boolean }): void {
-	if (!Number.isFinite(ms) || ms <= 0 || ms > MAX_MODEL_EXCLUSION_TTL_MS) {
-		throw new Error(`Default model exclusion TTL must be a finite positive number no greater than ${MAX_MODEL_EXCLUSION_TTL_MS}.`);
-	}
-	defaultTTLMs = ms;
-	loadedTTLCeilingMs = options?.shortenExisting ? ms : undefined;
-	if (loaded && loadedTTLCeilingMs !== undefined && shortenExclusionsToTTL(exclusions, loadedTTLCeilingMs, Date.now())) schedulePersist();
-}
-
-/**
- * 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) {
-			if (!Array.isArray(data.exclusions)) throw new Error("Model exclusion store version 1 must contain an exclusions array.");
-			const now = Date.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 (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);
-		}
-	}
-}
-
-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 ?? ""}`;
-}
-
-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();
-	invalidateAuthExclusions();
-	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 !== undefined) {
-		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();
-	invalidateAuthExclusions();
-	return exclusions.some((entry) => entryMatches(entry, modelId, provider, Date.now()));
-}
-
-/**
- * Return the active exclusion matching a full model id, if any.
- *
- * The caller uses this for hard-fail diagnostics; fallback filtering should
- * continue to use {@link filterFallbackCandidates}.
- */
-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));
-}
-
-/**
- * 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;
-	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) && opts?.ignoreExclusion?.(raw, entry) !== true);
-		if (exclusion) {
-			opts?.onExcluded?.(raw, exclusion);
-			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;
-}
-
-function shortenExclusionsToTTL(items: ModelExclusion[], ttlMs: number, now: number): boolean {
-	let changed = false;
-	for (const entry of items) {
-		const configuredExpiry = entry.recordedAt + ttlMs;
-		if (entry.expiresAt > configuredExpiry) {
-			entry.expiresAt = configuredExpiry;
-			changed = true;
-		}
-	}
-	const previousLength = items.length;
-	prune(items, now);
-	return changed || items.length !== previousLength;
-}