@f5-sales-demo/xcsh 21.49.3 → 21.50.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "21.49.3",
+	"version": "21.50.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5-sales-demo/xcsh",
 	"author": "Can Boluk",
@@ -67,13 +67,13 @@
 	},
 	"dependencies": {
 		"@agentclientprotocol/sdk": "1.4.0",
-		"@f5-sales-demo/pi-agent-core": "21.49.3",
-		"@f5-sales-demo/pi-ai": "21.49.3",
-		"@f5-sales-demo/pi-natives": "21.49.3",
-		"@f5-sales-demo/pi-resource-management": "21.49.3",
-		"@f5-sales-demo/pi-tui": "21.49.3",
-		"@f5-sales-demo/pi-utils": "21.49.3",
-		"@f5-sales-demo/xcsh-stats": "21.49.3",
+		"@f5-sales-demo/pi-agent-core": "21.50.0",
+		"@f5-sales-demo/pi-ai": "21.50.0",
+		"@f5-sales-demo/pi-natives": "21.50.0",
+		"@f5-sales-demo/pi-resource-management": "21.50.0",
+		"@f5-sales-demo/pi-tui": "21.50.0",
+		"@f5-sales-demo/pi-utils": "21.50.0",
+		"@f5-sales-demo/xcsh-stats": "21.50.0",
 		"@mozilla/readability": "^0.6",
 		"@resvg/resvg-wasm": "2.6.2",
 		"@sinclair/typebox": "0.34.52",

package/src/commit/agentic/index.ts

@@ -31,8 +31,8 @@ export async function runAgenticCommit(args: CommitCommandArgs): Promise<void> {
 	process.stdout.write("● Resolving model...\n");
 	const modelRegistry = new ModelRegistry(authStorage, undefined, {
 		getProviderOrder: () => settings.get("modelProviderOrder"),
-		getOpenAICodexMaxContext: () => settings.get("providers.openaiCodexMaxContext"),
-		getLiteLLMMaxContext: () => settings.get("providers.litellmMaxContext"),
+		getOpenAIContextTier: () => settings.get("providers.openaiContextTier"),
+		getLiteLLMContextTier: () => settings.get("providers.litellmContextTier"),
 	});
 	await modelRegistry.refresh();
 	const stagedFilesPromise = (async () => {

package/src/commit/pipeline.ts

@@ -44,8 +44,8 @@ async function runLegacyCommitCommand(args: CommitCommandArgs): Promise<void> {
 	const authStorage = await discoverAuthStorage();
 	const modelRegistry = new ModelRegistry(authStorage, undefined, {
 		getProviderOrder: () => settings.get("modelProviderOrder"),
-		getOpenAICodexMaxContext: () => settings.get("providers.openaiCodexMaxContext"),
-		getLiteLLMMaxContext: () => settings.get("providers.litellmMaxContext"),
+		getOpenAIContextTier: () => settings.get("providers.openaiContextTier"),
+		getLiteLLMContextTier: () => settings.get("providers.litellmContextTier"),
 	});
 	await modelRegistry.refresh();
 

package/src/config/auto-config.ts

@@ -20,7 +20,7 @@ import { hardenAgentConfigFileSync, writeAgentConfigFileSync } from "./agent-con
 import { DEFAULT_MODEL_ROLE } from "./settings-schema";
 
 /** Current config schema version. Bump when the generated format changes. */
-export const CURRENT_CONFIG_VERSION = 9;
+export const CURRENT_CONFIG_VERSION = 11;
 const LITELLM_CONFIG_DIR_MODE = 0o700;
 const LITELLM_MODELS_FILE_MODE = 0o600;
 const GENERATED_LITELLM_MARKER = "# Auto-generated by xcsh for LiteLLM proxy";
@@ -123,6 +123,7 @@ export function generateModelsYml(baseUrl: string, options?: GenerateModelsYmlOp
 		"      - gpt-6-astra",
 		"      - gpt-5.6-luna",
 		"      - gpt-5.6-sol",
+		"      - gpt-5.5",
 		"    models:",
 		"      - id: gpt-6-luna",
 		"        name: GPT-6 Luna",
@@ -130,7 +131,8 @@ export function generateModelsYml(baseUrl: string, options?: GenerateModelsYmlOp
 		`        baseUrl: "${responsesBaseUrl}"`,
 		"      - id: gpt-5.6-terra",
 		"        name: GPT-5.6 Terra",
-		"        api: openai-completions",
+		"        api: openai-responses",
+		`        baseUrl: "${responsesBaseUrl}"`,
 		"      - id: gpt-6-sol",
 		"        name: GPT-6 Sol",
 		"        api: openai-responses",
@@ -141,10 +143,16 @@ export function generateModelsYml(baseUrl: string, options?: GenerateModelsYmlOp
 		`        baseUrl: "${responsesBaseUrl}"`,
 		"      - id: gpt-5.6-luna",
 		"        name: GPT-5.6 Luna",
-		"        api: openai-completions",
+		"        api: openai-responses",
+		`        baseUrl: "${responsesBaseUrl}"`,
 		"      - id: gpt-5.6-sol",
 		"        name: GPT-5.6 Sol",
-		"        api: openai-completions",
+		"        api: openai-responses",
+		`        baseUrl: "${responsesBaseUrl}"`,
+		"      - id: gpt-5.5",
+		"        name: GPT-5.5",
+		"        api: openai-responses",
+		`        baseUrl: "${responsesBaseUrl}"`,
 		"    picker:",
 		"      groupId: litellm",
 		"      groupLabel: LiteLLM",
@@ -251,6 +259,23 @@ export function generateModelsYml(baseUrl: string, options?: GenerateModelsYmlOp
 		"          supportsTemperature: false",
 		"      gpt-5.6-luna:",
 		"        reasoning: true",
+		"        input:",
+		"          - text",
+		"          - image",
+		"        contextWindow: 1050000",
+		"        maxTokens: 128000",
+		"        compat:",
+		"          supportsTemperature: false",
+		"        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }",
+		"      gpt-5.5:",
+		"        reasoning: true",
+		"        input:",
+		"          - text",
+		"          - image",
+		"        contextWindow: 1050000",
+		"        maxTokens: 128000",
+		"        compat:",
+		"          supportsTemperature: false",
 		"        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }",
 	];
 

package/src/config/model-catalog.ts

@@ -10,9 +10,16 @@ function compareVersions(left: string, right: string): number {
 	return 0;
 }
 
-/** Keep historical catalogs available while presenting only current user-facing families. */
-const DEFAULT_OPENAI_CODEX_MODEL_IDS = new Set(["gpt-5.6-terra", "gpt-6-astra", "gpt-6-luna", "gpt-6-sol"]);
-const CURRENT_LITELLM_OPENAI_MODEL_IDS = new Set(["gpt-6-luna", "gpt-5.6-terra", "gpt-6-sol", "gpt-6-astra"]);
+/** Present the exact model-interaction contract when each provider advertises the model. */
+const CODEX_INTERACTION_MODEL_IDS = new Set([
+	"gpt-6-astra",
+	"gpt-6-sol",
+	"gpt-6-luna",
+	"gpt-5.6-sol",
+	"gpt-5.6-terra",
+	"gpt-5.6-luna",
+	"gpt-5.5",
+]);
 
 /** Shared catalog boundary for the TUI and attached human interfaces. */
 export function filterCurrentBrowserModels(models: readonly Model[]): Model[] {
@@ -39,9 +46,10 @@ export function filterCurrentBrowserModels(models: readonly Model[]): Model[] {
 	return models.filter(model => {
 		const gpt = model.id.match(/^gpt-(\d+(?:\.\d+)?)(?:-|$)/i);
 		if (gpt?.[1]) {
+			if (model.provider === "openai-codex" || model.provider === "litellm") {
+				return CODEX_INTERACTION_MODEL_IDS.has(model.id.toLowerCase());
+			}
 			if (compareVersions(gpt[1], "5.6") < 0) return false;
-			if (model.provider === "openai-codex") return DEFAULT_OPENAI_CODEX_MODEL_IDS.has(model.id.toLowerCase());
-			if (model.provider === "litellm") return CURRENT_LITELLM_OPENAI_MODEL_IDS.has(model.id.toLowerCase());
 		}
 		const claude = model.id.match(/^claude-(opus|sonnet|haiku)-(\d+)(?:[.-](\d+))?(?:-|$)/i);
 		if (claude?.[1] && claude[2]) {

package/src/config/model-registry.ts

@@ -2,7 +2,9 @@ import * as path from "node:path";
 import {
 	type Api,
 	type AssistantMessageEventStream,
+	applyCodexInteractionMetadata,
 	applyGeneratedModelPolicies,
+	type CodexContextTier,
 	type Context,
 	createModelManager,
 	DEFAULT_LOCAL_TOKEN,
@@ -23,6 +25,7 @@ import {
 	readModelCache,
 	registerCustomApi,
 	registerOAuthProvider,
+	resolveCodexContextBudget,
 	type SimpleStreamOptions,
 	type ThinkingConfig,
 	unregisterCustomApis,
@@ -50,17 +53,14 @@ export type { CanonicalModelIndex, CanonicalModelRecord, CanonicalModelVariant,
 
 export const kNoAuth = NO_AUTH_API_KEY;
 
-const OPENAI_CODEX_STANDARD_CONTEXT_WINDOW = 272_000;
-const OPENAI_CODEX_MAX_CONTEXT_WINDOW = 1_050_000;
-const OPENAI_CODEX_MAX_CONTEXT_MODEL_IDS = new Set(["gpt-6-luna", "gpt-6-sol"]);
-const LITELLM_STANDARD_CONTEXT_WINDOW = 272_000;
-const LITELLM_MAX_CONTEXT_WINDOW = 1_050_000;
-const LITELLM_MAX_CONTEXT_MODEL_IDS = new Set(["gpt-6-luna", "gpt-5.6-terra", "gpt-6-sol", "gpt-6-astra"]);
-
 export function isAuthenticated(apiKey: string | undefined | null): apiKey is string {
 	return Boolean(apiKey) && apiKey !== kNoAuth;
 }
 
+function positiveInteger(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : undefined;
+}
+
 export type ModelRole = "default" | "smol" | "slow" | "vision" | "plan" | "designer" | "commit" | "task";
 
 export interface ModelRoleInfo {
@@ -878,8 +878,8 @@ export class ModelRegistry {
 	#lastDiscoveryWarnings: Map<string, string> = new Map();
 	#hasProbed = false;
 	#refreshQueue: Promise<void> = Promise.resolve();
-	#openAICodexMaxContext = false;
-	#litellmMaxContext = false;
+	#openAIContextTier: CodexContextTier = "standard";
+	#litellmContextTier: CodexContextTier = "standard";
 
 	#enqueueRefresh(operation: () => Promise<void>): Promise<void> {
 		const pending = this.#refreshQueue.then(operation);
@@ -901,8 +901,8 @@ export class ModelRegistry {
 		modelsPath?: string,
 		private readonly options: {
 			getProviderOrder?: () => readonly string[];
-			getOpenAICodexMaxContext?: () => boolean;
-			getLiteLLMMaxContext?: () => boolean;
+			getOpenAIContextTier?: () => CodexContextTier;
+			getLiteLLMContextTier?: () => CodexContextTier;
 		} = {},
 	) {
 		this.#modelsConfigFile = ModelsConfigFile.relocate(modelsPath);
@@ -1055,8 +1055,8 @@ export class ModelRegistry {
 	}
 
 	#loadModels() {
-		this.#openAICodexMaxContext = this.options.getOpenAICodexMaxContext?.() ?? this.#openAICodexMaxContext;
-		this.#litellmMaxContext = this.options.getLiteLLMMaxContext?.() ?? this.#litellmMaxContext;
+		this.#openAIContextTier = this.options.getOpenAIContextTier?.() ?? this.#openAIContextTier;
+		this.#litellmContextTier = this.options.getLiteLLMContextTier?.() ?? this.#litellmContextTier;
 		// Load custom models from models.json first (to know which providers to override)
 		const {
 			models: customModels = [],
@@ -1090,42 +1090,39 @@ export class ModelRegistry {
 		const combined = this.#mergeCustomModels(withConfigModels, this.#runtimeModelOverlays);
 
 		this.#models = this.#applyProviderModelAllowlists(this.#applyModelOverrides(combined, this.#modelOverrides));
-		this.#applyOpenAICodexContextWindow();
-		this.#applyLiteLLMContextWindow();
+		this.#applyOpenAIContextTier();
+		this.#applyLiteLLMContextTier();
 		this.#rebuildCanonicalIndex();
 	}
 
-	#applyOpenAICodexContextWindow(): void {
-		const contextWindow = this.#openAICodexMaxContext
-			? OPENAI_CODEX_MAX_CONTEXT_WINDOW
-			: OPENAI_CODEX_STANDARD_CONTEXT_WINDOW;
+	#applyContextTier(provider: "openai-codex" | "litellm", tier: CodexContextTier): void {
 		for (const model of this.#models) {
-			if (model.provider === "openai-codex" && OPENAI_CODEX_MAX_CONTEXT_MODEL_IDS.has(model.id)) {
-				model.contextWindow = contextWindow;
-			}
+			if (model.provider !== provider) continue;
+			Object.assign(model, applyCodexInteractionMetadata(model));
+			const budget = resolveCodexContextBudget(model.id, tier, model.providerContextWindow);
+			if (budget) Object.assign(model, budget);
 		}
 	}
 
-	/** Update GPT-6 subscription context limits without rebuilding the registry. */
-	setOpenAICodexMaxContext(enabled: boolean): void {
-		this.#openAICodexMaxContext = enabled;
-		this.#applyOpenAICodexContextWindow();
+	#applyOpenAIContextTier(): void {
+		this.#applyContextTier("openai-codex", this.#openAIContextTier);
+	}
+
+	/** Update subscription context limits without rebuilding the registry. */
+	setOpenAIContextTier(tier: CodexContextTier): void {
+		this.#openAIContextTier = tier;
+		this.#applyOpenAIContextTier();
 		this.#rebuildCanonicalIndex();
 	}
 
-	#applyLiteLLMContextWindow(): void {
-		const contextWindow = this.#litellmMaxContext ? LITELLM_MAX_CONTEXT_WINDOW : LITELLM_STANDARD_CONTEXT_WINDOW;
-		for (const model of this.#models) {
-			if (model.provider === "litellm" && LITELLM_MAX_CONTEXT_MODEL_IDS.has(model.id)) {
-				model.contextWindow = contextWindow;
-			}
-		}
+	#applyLiteLLMContextTier(): void {
+		this.#applyContextTier("litellm", this.#litellmContextTier);
 	}
 
 	/** Update current internal OpenAI context limits without changing subscription models. */
-	setLiteLLMMaxContext(enabled: boolean): void {
-		this.#litellmMaxContext = enabled;
-		this.#applyLiteLLMContextWindow();
+	setLiteLLMContextTier(tier: CodexContextTier): void {
+		this.#litellmContextTier = tier;
+		this.#applyLiteLLMContextTier();
 		this.#rebuildCanonicalIndex();
 	}
 
@@ -1198,6 +1195,13 @@ export class ModelRegistry {
 		return merged;
 	}
 
+	#filterOverlaysBySuccessfulDiscovery(models: CustomModelOverlay[]): CustomModelOverlay[] {
+		return models.filter(model => {
+			const discovery = this.#providerDiscoveryStates.get(model.provider);
+			return discovery?.status !== "ok" || discovery.models.includes(model.id);
+		});
+	}
+
 	#applyProviderModelAllowlists(models: Model<Api>[]): Model<Api>[] {
 		return models.filter(model => {
 			const allowlist = this.#modelAllowlists.get(model.provider);
@@ -1420,9 +1424,15 @@ export class ModelRegistry {
 		]);
 		const discovered = [...configuredDiscovered, ...builtInDiscovered];
 		// Replace only catalogs which completed successfully, including an empty response.
+		const successfulDiscoveryProviders = providerFilter
+			? [...providerFilter].filter(provider => this.#providerDiscoveryStates.get(provider)?.status === "ok")
+			: [...this.#providerDiscoveryStates.values()]
+					.filter(state => state.status === "ok")
+					.map(state => state.provider);
 		const refreshed = new Set([
 			...selectedDiscoverableProviders.map(provider => provider.provider),
 			...discovered.map(model => model.provider),
+			...successfulDiscoveryProviders,
 		]);
 		const discoveredModels = this.#applyHardcodedModelPolicies(
 			discovered.map(model => {
@@ -1452,12 +1462,18 @@ export class ModelRegistry {
 			model => !refreshed.has(model.provider) || this.#providerDiscoveryStates.get(model.provider)?.status !== "ok",
 		);
 		const resolved = this.#mergeResolvedModels(this.#models, discoveredModels);
-		const withConfigModels = this.#mergeCustomModels(resolved, this.#customModelOverlays);
+		const withConfigModels = this.#mergeCustomModels(
+			resolved,
+			this.#filterOverlaysBySuccessfulDiscovery(this.#customModelOverlays),
+		);
 		// Merge runtime extension models so they survive online discovery completion
-		const combined = this.#mergeCustomModels(withConfigModels, this.#runtimeModelOverlays);
+		const combined = this.#mergeCustomModels(
+			withConfigModels,
+			this.#filterOverlaysBySuccessfulDiscovery(this.#runtimeModelOverlays),
+		);
 		this.#models = this.#applyProviderModelAllowlists(this.#applyModelOverrides(combined, this.#modelOverrides));
-		this.#applyOpenAICodexContextWindow();
-		this.#applyLiteLLMContextWindow();
+		this.#applyOpenAIContextTier();
+		this.#applyLiteLLMContextTier();
 		this.#rebuildCanonicalIndex();
 	}
 
@@ -2047,7 +2063,13 @@ export class ModelRegistry {
 			throw new Error(`HTTP ${response.status} from ${modelsUrl}`);
 		}
 		const payload = await response.json();
-		const items: Array<{ id: string; contextWindow?: number }> =
+		const items: Array<{
+			id: string;
+			contextWindow?: number;
+			context_window?: unknown;
+			max_input_tokens?: unknown;
+			max_output_tokens?: unknown;
+		}> =
 			providerConfig.provider === "vllm"
 				? parseVllmModelsPayload(payload)
 				: ((payload as { data?: Array<{ id: string }> }).data ?? []);
@@ -2055,6 +2077,10 @@ export class ModelRegistry {
 		for (const item of items) {
 			const id = item.id;
 			if (!id) continue;
+			const advertisedContextWindow =
+				positiveInteger(item.context_window) ?? positiveInteger(item.max_input_tokens) ?? item.contextWindow;
+			const advertisedOutputLimit = positiveInteger(item.max_output_tokens);
+			const contextWindow = advertisedContextWindow ?? 128000;
 			discovered.push(
 				enrichModelThinking({
 					id,
@@ -2065,11 +2091,13 @@ export class ModelRegistry {
 					reasoning: false,
 					input: ["text"],
 					cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-					contextWindow: item.contextWindow ?? 128000,
+					contextWindow,
 					maxTokens:
-						item.contextWindow === undefined
+						advertisedOutputLimit ??
+						(advertisedContextWindow === undefined
 							? 8192
-							: Math.max(1, Math.min(8192, Math.floor(item.contextWindow / 4))),
+							: Math.max(1, Math.min(8192, Math.floor(advertisedContextWindow / 4)))),
+					providerContextWindow: advertisedContextWindow,
 					headers,
 				}),
 			);
@@ -2150,7 +2178,8 @@ export class ModelRegistry {
 		// bundled corrections. Reapply generated-model policy before a cached entry
 		// replaces its bundled peer; explicit user overrides still run afterward.
 		applyGeneratedModelPolicies(models, { preserveDiscoveredThinking });
-		return models.map(model => {
+		return models.map(rawModel => {
+			const model = applyCodexInteractionMetadata(rawModel);
 			if (model.id !== "gpt-5.4" || model.provider === "github-copilot") {
 				return model;
 			}

package/src/config/model-resolver.ts

@@ -1116,6 +1116,20 @@ export function resolveCliModel(options: {
 				error: undefined,
 			};
 		}
+		const thinkingSeparator = pattern.lastIndexOf(":");
+		const exactModelId =
+			thinkingSeparator !== -1 && parseThinkingLevel(pattern.slice(thinkingSeparator + 1))
+				? pattern.slice(0, thinkingSeparator)
+				: pattern;
+		if (resolveProviderModelReference(provider, exactModelId, allModels)) {
+			return {
+				model: undefined,
+				selector: undefined,
+				thinkingLevel: undefined,
+				warning: undefined,
+				error: `Model "${provider}/${exactModelId}" is unavailable. Configure or sign in to provider "${provider}".`,
+			};
+		}
 	}
 
 	const candidates = provider ? availableModels.filter(model => model.provider === provider) : availableModels;

package/src/config/settings-schema.ts

@@ -2123,24 +2123,27 @@ export const SETTINGS_SCHEMA = {
 		},
 	},
 
-	"providers.openaiCodexMaxContext": {
-		type: "boolean",
-		default: false,
+	"providers.openaiContextTier": {
+		type: "enum",
+		values: ["standard", "codex-max", "provider-max"] as const,
+		default: "standard",
 		ui: {
 			tab: "providers",
-			label: "OpenAI Codex Maximum Context",
-			description:
-				"Use the 1.05M-token context window for GPT-6 Luna and Sol (long-context pricing applies above 272K)",
+			label: "OpenAI Context Tier",
+			description: "Choose the standard, Codex maximum, or provider-advertised context window",
+			submenu: true,
 		},
 	},
 
-	"providers.litellmMaxContext": {
-		type: "boolean",
-		default: false,
+	"providers.litellmContextTier": {
+		type: "enum",
+		values: ["standard", "codex-max", "provider-max"] as const,
+		default: "standard",
 		ui: {
 			tab: "providers",
-			label: "LiteLLM Maximum Context",
-			description: "Use the verified 1.05M-token context window for current internal OpenAI models",
+			label: "LiteLLM Context Tier",
+			description: "Choose the standard, Codex maximum, or live provider-advertised context window",
+			submenu: true,
 		},
 	},
 

package/src/context/profile.ts

@@ -1,4 +1,4 @@
-import type { Model, Usage } from "@f5-sales-demo/pi-ai";
+import { getModelEffectiveContextWindow, type Model, type Usage } from "@f5-sales-demo/pi-ai";
 
 export type ContextLoadingMode = "eager" | "progressive";
 
@@ -182,7 +182,7 @@ export function profileProviderPayload(payload: unknown, model: Model, call: num
 			const bytes = jsonBytes(message);
 			return { role: safeRole(message), bytes, estimatedTokens: estimateContextTokens(bytes) };
 		}),
-		contextWindow: model.contextWindow,
+		contextWindow: getModelEffectiveContextWindow(model),
 	};
 }
 

package/src/internal-urls/api-catalog-discovery.ts

@@ -1,5 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
-import { mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { rmSync } from "node:fs";
+import { mkdir, mkdtemp, rename, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
 import { gunzipSync } from "node:zlib";
 import { createStore } from "@tobilu/qmd";
@@ -38,6 +40,17 @@ type QmdStore = Awaited<ReturnType<typeof createStore>>;
 const qmdStores = new Map<string, Promise<QmdStore>>();
 const verifiedIndexPaths = new Map<string, string>();
 const indexExtractions = new Map<string, Promise<string>>();
+const runtimeRoots = new Set<string>();
+let runtimeCleanupRegistered = false;
+
+function registerRuntimeRoot(root: string): void {
+	runtimeRoots.add(root);
+	if (runtimeCleanupRegistered) return;
+	runtimeCleanupRegistered = true;
+	process.once("exit", () => {
+		for (const runtimeRoot of runtimeRoots) rmSync(runtimeRoot, { recursive: true, force: true });
+	});
+}
 
 function indexCacheKey(options: QmdBm25CatalogDiscoveryOptions): string {
 	return `${options.cacheRoot}\u0000${options.prebuiltIndex.fingerprint}\u0000${options.prebuiltIndex.sqliteSha256}`;
@@ -46,7 +59,21 @@ function indexCacheKey(options: QmdBm25CatalogDiscoveryOptions): string {
 async function getQmdStore(databasePath: string): Promise<QmdStore> {
 	let store = qmdStores.get(databasePath);
 	if (!store) {
-		store = createStore({ dbPath: databasePath });
+		store = (async () => {
+			// QMD's FTS query path still needs a writable SQLite runtime. Search a
+			// disposable copy so the checksum-pinned cache stays immutable.
+			const runtimeRoot = await mkdtemp(path.join(os.tmpdir(), "xcsh-api-catalog-runtime-"));
+			const runtimeDatabasePath = path.join(runtimeRoot, "index.sqlite");
+			try {
+				await Bun.write(runtimeDatabasePath, Bun.file(databasePath));
+				const runtimeStore = await createStore({ dbPath: runtimeDatabasePath });
+				registerRuntimeRoot(runtimeRoot);
+				return runtimeStore;
+			} catch (error) {
+				await rm(runtimeRoot, { recursive: true, force: true });
+				throw error;
+			}
+		})();
 		qmdStores.set(databasePath, store);
 	}
 	try {