@gajae-code/coding-agent 0.16.0 → 0.16.1

package/src/config/model-registry.ts

@@ -39,7 +39,11 @@ import {
 	UNK_MAX_TOKENS,
 	unregisterCustomApis,
 } from "@gajae-code/ai/core";
-import { resolveLoopbackOpenAIBaseUrl } from "@gajae-code/ai/utils/discovery/openai-compatible";
+import { fetchModelsDevPayload } from "@gajae-code/ai/provider-models/openai-compat";
+import {
+	detectDiscoveredApiFamily,
+	resolveLoopbackOpenAIBaseUrl,
+} from "@gajae-code/ai/utils/discovery/openai-compatible";
 
 // Sentinels for local-only OAuth tokens — declared inline to avoid loading provider
 // modules at startup. Must match the provider OAuth modules.
@@ -66,6 +70,7 @@ import {
 } from "../sdk/providers";
 import type { AuthStorage, OAuthCredential } from "../session/auth-storage";
 import type { ActiveSearchModelContext, WebSearchMode } from "../web/search/types";
+import { type BillingPath, deriveBillingPath } from "./billing-path";
 import { ConfigError, ConfigFile } from "./config-file";
 import { isAuthenticated, kNoAuth } from "./model-auth";
 import { type ConfiguredModelBindings, ModelBindingsApplier } from "./model-bindings-applier";
@@ -112,6 +117,7 @@ import {
 } from "./provider-selection-policy";
 import { type Settings, settings } from "./settings";
 
+export type { BillingPath, BillingPathKind } from "./billing-path";
 export type { EffectiveProviderAuth, ProviderSelectionPolicy } from "./provider-selection-policy";
 export type { CanonicalModelIndex, CanonicalModelRecord, CanonicalModelVariant, ModelEquivalenceConfig };
 
@@ -135,6 +141,69 @@ function redactDiscoveryUrl(value: string | URL): string {
 		return "(invalid URL)";
 	}
 }
+
+/** Whether a structured transport code proves that no listener accepted the connection. */
+function isConnectionRefusedDiscoveryCode(value: unknown): boolean {
+	if (typeof value === "string") {
+		const normalized = value.replace(/[^A-Za-z0-9]/gu, "").toUpperCase();
+		return (
+			normalized === "ECONNREFUSED" || normalized === "CONNECTIONREFUSED" || normalized === "ERRCONNECTIONREFUSED"
+		);
+	}
+	if (typeof value !== "number" || !Number.isInteger(value)) return false;
+	// ECONNREFUSED errno values used by the supported runtimes/OSes.
+	return value === 61 || value === -61 || value === 111 || value === -111 || value === 10061 || value === -10061;
+}
+
+function isConnectionRefusedDiscoveryEvidence(error: unknown): boolean {
+	const seen = new Set<unknown>();
+	const queue: unknown[] = [error];
+	while (queue.length > 0) {
+		const current = queue.shift();
+		if (current === null || typeof current !== "object" || seen.has(current)) continue;
+		seen.add(current);
+		for (const field of ["code", "errno", "errorCode", "transportCode"]) {
+			let value: unknown;
+			try {
+				value = Reflect.get(current, field);
+			} catch {
+				value = undefined;
+			}
+			if (isConnectionRefusedDiscoveryCode(value)) return true;
+		}
+		for (const field of ["cause", "error", "transport"]) {
+			let nested: unknown;
+			try {
+				nested = Reflect.get(current, field);
+			} catch {
+				nested = undefined;
+			}
+			if (nested !== undefined) queue.push(nested);
+		}
+	}
+	return false;
+}
+
+/** Whether `hostname` (as `URL.hostname` reports it) names this machine's loopback. */
+function isLoopbackDiscoveryHost(hostname: string): boolean {
+	if (hostname === "localhost" || hostname === "[::1]" || hostname === "::1") return true;
+	return /^127(?:\.\d{1,3}){3}$/u.test(hostname);
+}
+
+/**
+ * A loopback discovery endpoint that is proven to have no listener is the normal state of
+ * a machine without a local model server. Structured transport evidence is required when
+ * available; DNS, routing, proxy, TLS, and HTTP failures remain warnings.
+ */
+export function isQuietLocalDiscoveryFailure(baseUrl: string, _warning: string, evidence?: unknown): boolean {
+	let host: string;
+	try {
+		host = new URL(baseUrl).hostname;
+	} catch {
+		return false;
+	}
+	return isLoopbackDiscoveryHost(host) && evidence !== undefined && isConnectionRefusedDiscoveryEvidence(evidence);
+}
 function stripUrlQuery(value: string): string {
 	const queryStart = value.indexOf("?");
 	if (queryStart < 0) return value;
@@ -272,6 +341,44 @@ type ProviderValidationMode = "models-config" | "runtime-register";
 
 const OPENAI_REQUEST_TRANSFORM_APIS = new Set<Api>(["openai-completions", "openai-responses"]);
 
+const OPENAI_FAMILY_APIS = new Set<Api>([
+	"openai-completions",
+	"openai-responses",
+	"openai-codex-responses",
+	"azure-openai-responses",
+]);
+
+/** Whether an api uses an OpenAI-shaped request/response transport. */
+function isOpenAIFamilyApi(api: Api): boolean {
+	return OPENAI_FAMILY_APIS.has(api);
+}
+
+/**
+ * The most frequent OpenAI-family api among statically-configured models, used
+ * as the default api for auto-enabled `/v1/models` discovery on a custom
+ * provider that sets `api` only per model. Returns `undefined` when no
+ * configured model uses an OpenAI-family api (e.g. an Anthropic-only base),
+ * which suppresses auto-discovery for that provider.
+ */
+function dominantOpenAIFamilyModelApi(models: readonly { api?: string }[] | undefined): Api | undefined {
+	if (!models || models.length === 0) return undefined;
+	const counts = new Map<Api, number>();
+	for (const model of models) {
+		const api = model.api as Api | undefined;
+		if (api === undefined || !isOpenAIFamilyApi(api)) continue;
+		counts.set(api, (counts.get(api) ?? 0) + 1);
+	}
+	let best: Api | undefined;
+	let bestCount = 0;
+	for (const [api, count] of counts) {
+		if (count > bestCount) {
+			best = api;
+			bestCount = count;
+		}
+	}
+	return best;
+}
+
 function getKnownProviderApis(providerName: string): Set<Api> {
 	const apis = new Set<Api>();
 	for (const model of getBundledModels(providerName as Parameters<typeof getBundledModels>[0])) {
@@ -2674,17 +2781,48 @@ export class ModelRegistry {
 				keylessProviders.add(providerName);
 			}
 
-			if (providerConfig.discovery && providerConfig.api) {
+			// Explicit discovery config is authoritative. Otherwise auto-enable
+			// OpenAI-compatible `/v1/models` discovery for any custom provider that
+			// declares an OpenAI-family `api` and a `baseUrl`: a subscription-style
+			// gateway (e.g. CLIProxyAPI) then auto-populates `/model` with its live
+			// catalog and auto-routes each model's wire family, with no manual
+			// `discovery:` block. It stays optional so an endpoint without
+			// `/v1/models` degrades to the configured static models instead of
+			// failing. Providers that route through the local `openaiCompat` proxy
+			// already register their own discovery above, so skip them here.
+			const effectiveDiscoveryBaseUrl = providerConfig.baseUrl ?? resolveProviderBaseUrlFromEnv(providerName);
+			// The default api for discovered models: the provider-level `api` when
+			// set, otherwise the most common OpenAI-family `api` among the
+			// statically-configured models. For withfox-style configs that only set
+			// `api` per model (`openai-responses` for gpt, `anthropic-messages` for
+			// claude), this preserves the intended OpenAI transport for discovered
+			// OpenAI models while `detectDiscoveredApiFamily` still flips claude ids
+			// to Anthropic.
+			const providerApi =
+				(providerConfig.api as Api | undefined) ??
+				dominantOpenAIFamilyModelApi(providerConfig.models as { api?: string }[] | undefined);
+			const autoDiscovery: ProviderDiscovery | undefined =
+				!providerConfig.discovery &&
+				!localOpenAICompat &&
+				providerName !== "vllm" &&
+				providerName !== "sglang" &&
+				providerApi !== undefined &&
+				isOpenAIFamilyApi(providerApi) &&
+				effectiveDiscoveryBaseUrl !== undefined
+					? { type: "openai-models-list" }
+					: undefined;
+			const effectiveDiscovery = providerConfig.discovery ?? autoDiscovery;
+			if (effectiveDiscovery && providerApi) {
 				discoverableProviders.push({
 					provider: providerName,
-					api: providerConfig.api as Api,
-					baseUrl: providerConfig.baseUrl ?? resolveProviderBaseUrlFromEnv(providerName),
+					api: providerApi,
+					baseUrl: effectiveDiscoveryBaseUrl,
 					headers: providerConfig.headers,
 					compat: providerConfig.compat,
 					requestTransform: providerConfig.requestTransform,
 					cacheRetention: providerConfig.cacheRetention,
-					discovery: providerConfig.discovery,
-					optional: false,
+					discovery: effectiveDiscovery,
+					optional: !providerConfig.discovery,
 				});
 			}
 
@@ -2962,27 +3100,71 @@ export class ModelRegistry {
 				? { ...result, invalidatesPublishedState }
 				: { ...result, current: false, models: [], fetched: false, invalidatesPublishedState };
 		});
+		// Every field below except `model.baseUrl` and `model.id` depends only on
+		// `model.provider`. The built-in catalog carries thousands of models across
+		// only a few dozen providers, and `#getProviderEvidenceGeneration` reaches
+		// into AuthStorage while `#getProviderBaseUrlForDiscovery` parses URLs, so
+		// recomputing per model turned this filter into a per-refresh UI-thread
+		// stall. Memoize the provider-keyed work once per provider.
+		interface BuiltInProviderEvidenceState {
+			evidence:
+				| {
+						fresh: boolean;
+						modelIds: ReadonlySet<string>;
+						profileModelIds?: ReadonlySet<string>;
+						profileFresh?: boolean;
+						profileEndpoint?: string;
+						authGeneration: string;
+						endpoint: string;
+				  }
+				| undefined;
+			expectedAuthGeneration: string | undefined;
+			authGenerationThrew: boolean;
+			providerBaseEndpoint: string | undefined;
+			canUseCredentialDerivedXiaomiEndpoint: boolean;
+		}
+		const builtInProviderStates = new Map<string, BuiltInProviderEvidenceState>();
+		const builtInProviderStateFor = (provider: string): BuiltInProviderEvidenceState => {
+			const cached = builtInProviderStates.get(provider);
+			if (cached) return cached;
+			let expectedAuthGeneration: string | undefined;
+			let authGenerationThrew = false;
+			try {
+				expectedAuthGeneration = this.#getProviderEvidenceGeneration(
+					provider,
+					this.#providerEvidenceApiKeys.get(provider),
+				);
+			} catch {
+				authGenerationThrew = true;
+			}
+			const providerBaseUrl = this.#getProviderBaseUrlForDiscovery(provider);
+			const state: BuiltInProviderEvidenceState = {
+				evidence: this.#descriptorDiscoveryEvidence.get(provider),
+				expectedAuthGeneration,
+				authGenerationThrew,
+				providerBaseEndpoint:
+					providerBaseUrl !== undefined ? this.#normalizeDiscoveryEvidenceEndpoint(providerBaseUrl) : undefined,
+				canUseCredentialDerivedXiaomiEndpoint:
+					provider === "xiaomi" &&
+					this.#providerEvidenceApiKeys.get("xiaomi")?.startsWith("tp-") === true &&
+					this.#runtimeProviderOverrides.get("xiaomi")?.baseUrl === undefined &&
+					this.#providerOverrides.get("xiaomi")?.baseUrl === undefined &&
+					resolveProviderBaseUrlFromEnv("xiaomi") === undefined,
+			};
+			builtInProviderStates.set(provider, state);
+			return state;
+		};
 		const currentBuiltInDiscovered = builtInDiscovered.filter(model => {
-			const evidence = this.#descriptorDiscoveryEvidence.get(model.provider);
-			const currentEndpoint = this.#normalizeDiscoveryEvidenceEndpoint(
-				this.#getProviderBaseUrlForDiscovery(model.provider) ?? model.baseUrl ?? "",
-			);
-			const canUseCredentialDerivedXiaomiEndpoint =
-				model.provider === "xiaomi" &&
-				this.#providerEvidenceApiKeys.get("xiaomi")?.startsWith("tp-") === true &&
-				this.#runtimeProviderOverrides.get("xiaomi")?.baseUrl === undefined &&
-				this.#providerOverrides.get("xiaomi")?.baseUrl === undefined &&
-				resolveProviderBaseUrlFromEnv("xiaomi") === undefined;
+			const state = builtInProviderStateFor(model.provider);
+			const { evidence } = state;
+			if (evidence === undefined || state.authGenerationThrew) return false;
+			if (evidence.authGeneration !== state.expectedAuthGeneration) return false;
 			try {
+				const currentEndpoint =
+					state.providerBaseEndpoint ?? this.#normalizeDiscoveryEvidenceEndpoint(model.baseUrl ?? "");
 				return (
-					evidence !== undefined &&
-					evidence.authGeneration ===
-						this.#getProviderEvidenceGeneration(
-							model.provider,
-							this.#providerEvidenceApiKeys.get(model.provider),
-						) &&
 					(evidence.endpoint === currentEndpoint ||
-						(canUseCredentialDerivedXiaomiEndpoint &&
+						(state.canUseCredentialDerivedXiaomiEndpoint &&
 							evidence.endpoint === this.#normalizeDiscoveryEvidenceEndpoint(model.baseUrl ?? ""))) &&
 					evidence.modelIds.has(model.id)
 				);
@@ -3227,6 +3409,8 @@ export class ModelRegistry {
 					(evidence.authGeneration !== authGenerationBeforeDiscovery || evidence.endpoint !== endpoint)))
 				? "online"
 				: strategy;
+		let discoveryFailureEvidence: unknown;
+
 		const mergeInput = await this.#discoveryManager.discover(effectiveProviderConfig, refreshStrategy, {
 			cacheDbPath: this.#cacheDbPath,
 			requiresAuth: provider =>
@@ -3239,11 +3423,17 @@ export class ModelRegistry {
 							baseUrl: provider.baseUrl,
 						}),
 			isAuthenticated,
-			fetchModels: async (provider, apiKey) =>
-				this.#sanitizeDiscoverableModelsForCache(
-					provider,
-					await this.#discoverModelsByProviderType(provider, apiKey),
-				),
+			fetchModels: async (provider, apiKey) => {
+				try {
+					return this.#sanitizeDiscoverableModelsForCache(
+						provider,
+						await this.#discoverModelsByProviderType(provider, apiKey),
+					);
+				} catch (error) {
+					discoveryFailureEvidence = error;
+					throw error;
+				}
+			},
 			getEvidenceGeneration: provider => this.#getProviderEvidenceGeneration(provider.provider, preflightApiKey),
 			cacheDynamicModelProvenance: cacheLookupProvenance,
 			canPublishCache: () => isCurrentEndpoint() && isCurrentProviderRefresh(),
@@ -3267,11 +3457,15 @@ export class ModelRegistry {
 			};
 		}
 		if (mergeInput.warning) {
-			logger.warn("model discovery failed for provider", {
+			const baseUrl = effectiveProviderConfig.baseUrl ?? "";
+			const fields = {
 				provider: effectiveProviderConfig.provider,
-				url: redactDiscoveryUrl(effectiveProviderConfig.baseUrl ?? ""),
+				url: redactDiscoveryUrl(baseUrl),
 				error: mergeInput.warning,
-			});
+			};
+			if (isQuietLocalDiscoveryFailure(baseUrl, mergeInput.warning, discoveryFailureEvidence))
+				logger.debug("model discovery failed for provider", fields);
+			else logger.warn("model discovery failed for provider", fields);
 		}
 		this.#providerEvidenceApiKeys.set(effectiveProviderConfig.provider, preflightApiKey);
 		return {
@@ -3831,27 +4025,47 @@ export class ModelRegistry {
 		return this.#applyProviderModelOverrides(providerConfig.provider, discovered);
 	}
 
-	#resolveDiscoveredModelApi(providerConfig: DiscoveryProviderConfig, modelId: string): Api {
-		let api = providerConfig.api;
+	#resolveDiscoveredModelApi(
+		providerConfig: DiscoveryProviderConfig,
+		modelId: string,
+		entry?: { id?: unknown; owned_by?: unknown },
+	): Api {
+		// 1. Explicit per-prefix routing from models.yml always wins — the user
+		//    stated the transport for these ids, so never second-guess it.
 		let matchedPrefixLength = -1;
+		let prefixApi: Api | undefined;
 		for (const [prefix, routedApi] of Object.entries(providerConfig.discovery.apiByModelPrefix ?? {})) {
 			if (modelId.startsWith(prefix) && prefix.length > matchedPrefixLength) {
-				api = routedApi;
+				prefixApi = routedApi;
 				matchedPrefixLength = prefix.length;
 			}
 		}
-		return api;
+		if (prefixApi !== undefined) return prefixApi;
+		// 2. For OpenAI-compatible gateways that can front both OpenAI and
+		//    Anthropic upstreams (e.g. CLIProxyAPI), auto-detect the wire family
+		//    per model from the `/v1/models` `owned_by` owner and the model id.
+		//    A mixed gateway then routes `claude-*` through Anthropic Messages
+		//    with zero manual config. OpenAI-family models keep the provider's
+		//    configured OpenAI transport (e.g. `openai-responses` vs
+		//    `openai-completions`) rather than being forced to chat-completions,
+		//    because a `/v1/models` list cannot reveal which OpenAI API the
+		//    gateway expects. Only override to `openai-completions` when the
+		//    provider default is not itself an OpenAI-family api.
+		if (providerConfig.discovery.type === "openai-models-list") {
+			const detected = detectDiscoveredApiFamily(entry ?? { id: modelId });
+			if (detected === "anthropic-messages") return "anthropic-messages";
+			if (detected === "openai-completions") {
+				return isOpenAIFamilyApi(providerConfig.api) ? providerConfig.api : "openai-completions";
+			}
+		}
+		// 3. Fall back to the provider-level default api.
+		return providerConfig.api;
 	}
 
 	async #discoverModelsDevProvider(providerConfig: DiscoveryProviderConfig): Promise<Model<Api>[]> {
 		const baseUrl = providerConfig.baseUrl;
 		if (!baseUrl) throw new Error(`Provider "${providerConfig.provider}" requires baseUrl for models.dev discovery.`);
-		const response = await fetch("https://models.dev/api.json", {
-			headers: { Accept: "application/json" },
-			signal: AbortSignal.timeout(5_000),
-		});
-		if (!response.ok) throw new Error(`HTTP ${response.status} from https://models.dev/api.json`);
-		const payload: unknown = await response.json();
+		const payload: unknown = await fetchModelsDevPayload();
 		if (!isRecord(payload)) return [];
 		const catalogProvider = payload[providerConfig.discovery.modelsDevProvider ?? providerConfig.provider];
 		if (!isRecord(catalogProvider) || !isRecord(catalogProvider.models)) return [];
@@ -3957,7 +4171,7 @@ export class ModelRegistry {
 				item.max_tokens,
 				item.max_output_tokens,
 			);
-			const api = this.#resolveDiscoveredModelApi(providerConfig, id);
+			const api = this.#resolveDiscoveredModelApi(providerConfig, id, item);
 			discovered.push(
 				enrichModelThinking({
 					id,
@@ -4842,6 +5056,18 @@ export class ModelRegistry {
 		return this.#effectiveProviderAuth(provider, sessionId);
 	}
 
+	/**
+	 * Billing path for a resolved binding — derived at the point the binding
+	 * resolves credentials (model.api + credential provenance). Not a
+	 * provider-name allowlist: a custom OpenAI-compatible provider bound
+	 * to a metered gateway is "metered-api" exactly like a first-party
+	 * key. Only the billing category is ever disclosed.
+	 */
+	getBillingPath(model: Model<Api>, sessionId?: string): BillingPath | undefined {
+		const effectiveAuth = this.#effectiveProviderAuth(model.provider, sessionId);
+		return deriveBillingPath(model.provider, model.api as Api, effectiveAuth);
+	}
+
 	/**
 	 * Forget a session's remembered canonical variant so the next resolution
 	 * for that session re-ranks from scratch (explicit reselection

package/src/config/settings-schema.ts

@@ -1579,14 +1579,15 @@ export const SETTINGS_SCHEMA = {
 		},
 	},
 
-	interruptMode: {
+	toolInterruptPolicy: {
 		type: "enum",
-		values: ["immediate", "wait"] as const,
-		default: "immediate",
+		values: ["abort_tools", "finish_tools"] as const,
+		default: "abort_tools",
 		ui: {
 			tab: "interaction",
-			label: "Interrupt Mode",
-			description: "When steering messages interrupt tool execution",
+			label: "Tool Interrupt Policy",
+			description:
+				"Whether a steering message aborts the tools still running in the current batch (abort_tools) or lets them finish first (finish_tools). Never changes when a steer is consumed: it is always picked up at the next tool/turn boundary either way.",
 		},
 	},
 
@@ -3043,6 +3044,17 @@ export const SETTINGS_SCHEMA = {
 			description: "Enable the browser tool (Ulixee Hero)",
 		},
 	},
+	"browser.backend": {
+		type: "enum",
+		values: ["native", "aside"] as const,
+		default: "native",
+		ui: {
+			tab: "tools",
+			label: "Browser Backend",
+			description:
+				"Browser surface offered to the model. 'native' exposes the built-in Puppeteer browser tool. 'aside' hides it and requires every browser task to run through the Aside CLI in your live logged-in browser (requires the Aside CLI).",
+		},
+	},
 
 	"browser.headless": {
 		type: "boolean",
@@ -3072,7 +3084,7 @@ export const SETTINGS_SCHEMA = {
 			tab: "tools",
 			label: "Profile reuse posture",
 			description:
-				"'auto' (default): when a usable real Chrome profile is available, the browser tool uses an isolated copy of it (cookies/session/cache) for stronger stealth, warns, and falls back to synthetic. 'opt-in': stay synthetic unless a real profile is explicitly requested.",
+				"'auto' (default): when a usable real Chrome profile is available, the browser tool uses an isolated copy of it (cookies/session/cache) for stronger stealth, warns, and falls back to synthetic. 'opt-in': stay synthetic unless a real profile is explicitly requested. On macOS, cookie decryption is brand-specific (Chrome Safe Storage vs Chromium Safe Storage Keychain); a Chrome profile copied into bundled Chromium decrypts to garbage, so auto reuses the profile only when the headless executable can decrypt it — detected system Chrome/Chromium or PUPPETEER_EXECUTABLE_PATH — otherwise it falls back to synthetic with a warning.",
 		},
 	},
 
@@ -4124,7 +4136,7 @@ export function getEnumValues(path: SettingPath): readonly string[] | undefined
 	return "values" in def ? (def.values as readonly string[]) : undefined;
 }
 
-export { CONFIG_SCHEMA_VERSION } from "./config-schema-version";
+export { CONFIG_SCHEMA_VERSION, normalizeConfigSchemaVersion } from "./config-schema-version";
 
 export type SettingsSchemaIssue = {
 	path: string;

package/src/config/settings.ts

@@ -70,6 +70,7 @@ import {
 	type GroupPrefix,
 	type GroupTypeMap,
 	getDefault,
+	normalizeConfigSchemaVersion,
 	reconcileSettingsSchema,
 	SETTINGS_SCHEMA,
 	type SettingPath,
@@ -1525,15 +1526,19 @@ export class Settings implements NotificationSettingsReader {
 				this.#hasInvalidNotificationGlobal = true;
 			}
 		}
+		// ONE normalized marker feeds every version decision (future-schema,
+		// migration-pending, and the ordered registry in #migrateRawSettings): a
+		// malformed value must never be read as a future schema here — which would
+		// skip legacy migration entirely — and as unmigrated by the registry.
+		const configSchemaVersion = normalizeConfigSchemaVersion(parsedRaw.configSchemaVersion);
 		this.#futureSchemaVersion =
 			filePath === this.#configPath &&
-			typeof parsedRaw.configSchemaVersion === "number" &&
-			parsedRaw.configSchemaVersion > CONFIG_SCHEMA_VERSION;
+			configSchemaVersion !== undefined &&
+			configSchemaVersion > CONFIG_SCHEMA_VERSION;
 
-		const configSchemaVersion = parsedRaw.configSchemaVersion;
 		if (
 			filePath === this.#configPath &&
-			(typeof configSchemaVersion !== "number" || configSchemaVersion < CONFIG_SCHEMA_VERSION)
+			(configSchemaVersion === undefined || configSchemaVersion < CONFIG_SCHEMA_VERSION)
 		) {
 			this.#schemaMigrationPending = true;
 		}
@@ -2087,7 +2092,7 @@ export class Settings implements NotificationSettingsReader {
 						return false;
 					}
 					const schemaVersion = (root as Record<string, unknown> | null | undefined)?.configSchemaVersion;
-					if (typeof schemaVersion === "number" && schemaVersion > CONFIG_SCHEMA_VERSION) {
+					if ((normalizeConfigSchemaVersion(schemaVersion) ?? 0) > CONFIG_SCHEMA_VERSION) {
 						this.#warnLegacyFallbackMigration(
 							`Settings: database workflow migration skipped: ${this.#configPath} is a future config schema (configSchemaVersion ${schemaVersion} > ${CONFIG_SCHEMA_VERSION}); leaving legacy rows for the next load`,
 						);
@@ -2338,7 +2343,7 @@ export class Settings implements NotificationSettingsReader {
 				// sets #futureSchemaVersion, so it must check the target schema
 				// itself and never patch it or consume the legacy source.
 				const targetSchemaVersion = (tx.root as Record<string, unknown> | null | undefined)?.configSchemaVersion;
-				if (typeof targetSchemaVersion === "number" && targetSchemaVersion > CONFIG_SCHEMA_VERSION) {
+				if ((normalizeConfigSchemaVersion(targetSchemaVersion) ?? 0) > CONFIG_SCHEMA_VERSION) {
 					this.#warnLegacyFallbackMigration(
 						`Settings: config-root workflow migration skipped: ${target} is a future config schema (configSchemaVersion ${targetSchemaVersion} > ${CONFIG_SCHEMA_VERSION})`,
 					);
@@ -3580,7 +3585,7 @@ export class Settings implements NotificationSettingsReader {
 				// read-only across Settings; never patch it (mirrors the config-root
 				// migration guard) so a future schema cannot inherit stale keys.
 				const targetSchemaVersion = (tx.root as Record<string, unknown> | null | undefined)?.configSchemaVersion;
-				if (typeof targetSchemaVersion === "number" && targetSchemaVersion > CONFIG_SCHEMA_VERSION) {
+				if ((normalizeConfigSchemaVersion(targetSchemaVersion) ?? 0) > CONFIG_SCHEMA_VERSION) {
 					this.#warnLegacyFallbackMigration(
 						`Settings: project workflow migration skipped: ${target} is a future config schema (configSchemaVersion ${targetSchemaVersion} > ${CONFIG_SCHEMA_VERSION})`,
 					);
@@ -4097,7 +4102,7 @@ export class Settings implements NotificationSettingsReader {
 		markerPath = `${source}.fallback-invalid`,
 	): Promise<void> {
 		const targetSchemaVersion = (tx.root as Record<string, unknown> | null | undefined)?.configSchemaVersion;
-		if (typeof targetSchemaVersion === "number" && targetSchemaVersion > CONFIG_SCHEMA_VERSION) return;
+		if ((normalizeConfigSchemaVersion(targetSchemaVersion) ?? 0) > CONFIG_SCHEMA_VERSION) return;
 		if (tx.root !== undefined && (tx.root === null || typeof tx.root !== "object" || Array.isArray(tx.root))) {
 			return;
 		}
@@ -4826,7 +4831,7 @@ export class Settings implements NotificationSettingsReader {
 				// guard) would rewrite configuration an older binary treats as
 				// read-only.
 				const targetSchemaVersion = (tx.root as Record<string, unknown> | null | undefined)?.configSchemaVersion;
-				if (typeof targetSchemaVersion === "number" && targetSchemaVersion > CONFIG_SCHEMA_VERSION) {
+				if ((normalizeConfigSchemaVersion(targetSchemaVersion) ?? 0) > CONFIG_SCHEMA_VERSION) {
 					return;
 				}
 				// Unset only while the target still matches the migration's fallback
@@ -5404,11 +5409,41 @@ export class Settings implements NotificationSettingsReader {
 
 	/** Apply registered schema migrations once, using configSchemaVersion as the durable marker. */
 	#migrateRawSettings(raw: RawSettings): RawSettings {
-		const configuredVersion = raw.configSchemaVersion;
+		const rawVersion = raw.configSchemaVersion;
+		const configuredVersion = normalizeConfigSchemaVersion(rawVersion);
+		if (rawVersion !== undefined && rawVersion !== configuredVersion) {
+			logger.warn("Settings: config has a malformed configSchemaVersion; migrating from the normalized version", {
+				configSchemaVersion: String(rawVersion),
+				normalized: String(configuredVersion),
+			});
+		}
 		if (configuredVersion === CONFIG_SCHEMA_VERSION) return raw;
 		if (typeof configuredVersion === "number" && configuredVersion > CONFIG_SCHEMA_VERSION) return raw;
 
-		// Migration registry v0 -> v1.
+		// Ordered migration registry. Each step runs ONLY for files below its
+		// target version: the v0 steps are not all idempotent (ask.timeout's
+		// milliseconds-to-seconds conversion would re-divide a valid v1 value),
+		// so a v1 file must skip straight to the v2 step.
+		const fromVersion = typeof configuredVersion === "number" ? configuredVersion : 0;
+		if (fromVersion < 1) this.#migrateRawSettingsV0ToV1(raw);
+		// v1 -> v2: interruptMode -> toolInterruptPolicy.
+		if (fromVersion < 2 && "interruptMode" in raw) {
+			if (!("toolInterruptPolicy" in raw)) {
+				const legacy = raw.interruptMode;
+				if (legacy === "wait") raw.toolInterruptPolicy = "finish_tools";
+				else if (legacy === "immediate") raw.toolInterruptPolicy = "abort_tools";
+				// Any other value is malformed: drop it and let the schema default apply.
+			}
+			delete raw.interruptMode;
+		}
+
+		raw.configSchemaVersion = CONFIG_SCHEMA_VERSION;
+
+		return raw;
+	}
+
+	/** v0 -> v1 transforms. Runs only for files that predate schema version 1. */
+	#migrateRawSettingsV0ToV1(raw: RawSettings): void {
 		// queueMode -> steeringMode
 		normalizeSessionDirectoryMigration(raw);
 		if ("queueMode" in raw && !("steeringMode" in raw)) {
@@ -5573,10 +5608,6 @@ export class Settings implements NotificationSettingsReader {
 				delete providersObj.imageCustomKeyEnv;
 			}
 		}
-
-		raw.configSchemaVersion = CONFIG_SCHEMA_VERSION;
-
-		return raw;
 	}
 
 	// ─────────────────────────────────────────────────────────────────────────

package/src/coordinator-mcp/projection-scan.ts

@@ -195,10 +195,10 @@ function trimProjectionRootPath(dir: string): string {
 }
 
 /**
- * Windows has no descriptor-relative `openat` binding in Node. Keep the root pathname
- * authoritative by checking its identity before and after every mutable-path operation.
+ * Node exposes no descriptor-relative `openat` binding on Windows or macOS. Keep the
+ * root pathname authoritative by checking its identity around every path operation.
  */
-async function openProjectionDirectoryWindowsSafe(dir: string): Promise<ProjectionScanDirectory> {
+async function openProjectionDirectoryPathBracketed(dir: string): Promise<ProjectionScanDirectory> {
 	const rootPath = trimProjectionRootPath(dir);
 	let opened: import("node:fs").BigIntStats;
 	try {
@@ -226,8 +226,8 @@ async function openProjectionDirectoryWindowsSafe(dir: string): Promise<Projecti
 	};
 
 	const entryPath = (entry: string): string => {
-		// Directory entries come from readdir and are therefore single components on
-		// Windows. Keep the invariant explicit so an injected or corrupted entry can
+		// Directory entries come from readdir and are therefore single components.
+		// Keep the invariant explicit so an injected or corrupted entry can
 		// never turn a child operation into mutable pathname traversal.
 		if (
 			entry.length === 0 ||
@@ -290,7 +290,7 @@ async function openProjectionDirectoryWindowsSafe(dir: string): Promise<Projecti
  */
 async function openProjectionDirectorySafe(dir: string): Promise<ProjectionScanDirectory> {
 	const platform = projectionPlatform();
-	if (platform === "win32") return openProjectionDirectoryWindowsSafe(dir);
+	if (platform === "win32" || platform === "darwin") return openProjectionDirectoryPathBracketed(dir);
 	if (platform !== "linux") throw new ProjectionScanUnsupportedError();
 	const noFollow = fs.constants.O_NOFOLLOW;
 	const nonBlock = fs.constants.O_NONBLOCK;