pi-cache-optimizer 2.8.16 → 2.8.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cache-optimizer",
-  "version": "2.8.16",
+  "version": "2.8.17",
   "description": "Improve Pi prompt/KV cache hit rates with stable prompts, OpenAI-compatible cache keys, proxy compat warnings, and footer cache stats.",
   "keywords": [
     "pi-package",
@@ -16,7 +16,8 @@
   "author": "freescheme",
   "license": "MIT",
   "files": [
-    "index.ts"
+    "index.ts",
+    "src"
   ],
   "pi": {
     "extensions": [
@@ -31,12 +32,13 @@
     "test": "node --import jiti/register --test tests/*.test.ts",
     "typecheck": "tsc --noEmit --pretty false",
     "check:diff": "git diff --check",
-    "check:pack": "npm pack --dry-run --cache node_modules/.cache/npm",
-    "check": "npm run typecheck && npm test && npm run check:diff && npm run check:pack"
+    "check:pack": "node scripts/check-pack.mjs",
+    "check": "npm run typecheck && npm test && npm run check:diff && npm run check:modules && npm run check:pack",
+    "check:modules": "node scripts/check-module-graph.mjs"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.99.2",
-    "@earendil-works/pi-server": "0.99.2",
+    "@earendil-works/pi-coding-agent": "^1.0.0",
+    "@earendil-works/pi-server": "1.0.0",
     "@types/node": "^22.0.0",
     "jiti": "^2.7.0",
     "typescript": "^5.8.3"

package/src/adapters.ts

@@ -0,0 +1,250 @@
+import { type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type PiModel, isNonEmptyString } from "./common.ts";
+import { buildDeepSeekCompatWarningText, buildOpenAIProxyCompatWarningText, describeMissingCacheCompatForModel, describeMissingOpenAICompatibleProxyCompat, isDeepSeekWireCompatApplicable } from "./compat-advice.ts";
+import { getAssistantMessageModelTokenValues, getModelIdNameTokenValues, hasAnyTokenContaining } from "./model-detect.ts";
+import { ALEPH_MODEL_PATTERN, ARCTIC_MODEL_PATTERN, AYA_MODEL_PATTERN, DOUBAO_SEED_PATTERN, MIMO_MODEL_PATTERN, MPT_MODEL_PATTERN, NOVA_MODEL_PATTERN, ORION_MODEL_PATTERN, PHI_MODEL_PATTERN, PPLX_MODEL_PATTERN, XAI_MODEL_PATTERN, YI_MODEL_PATTERN, getAssistantRecord, getCompat, isAssistantMessage, isClaudeLikeAssistantMessage, isClaudeLikeModel, isDeepSeekLikeAssistantMessage, isDeepSeekLikeModel, isGeminiLikeAssistantMessage, isGeminiLikeModel, isNativeVirtualModel, isOpenAICompatibleApi, isOpenAIFamilyAssistantMessage, isOpenAIFamilyModel, isPiBuiltInLlamaCppModel, modelKey } from "./model-identity.ts";
+import { firstNonEmptyString, getRoutingRegistry, isRouterModel, resolveActiveRouteSnapshot } from "./routing.ts";
+import { type CacheProviderId, type UsageSnapshot } from "./stats-store.ts";
+import { getAnthropicRawUsage, getDeepSeekRawUsage, getGeminiRawUsage, getOpenAIRawUsage, normalizeWithFallback } from "./usage.ts";
+
+export type CacheProviderAdapter = {
+  id: CacheProviderId;
+  label: string;
+  showCacheWrite?: boolean;
+  matchesModel(model: PiModel | undefined): boolean;
+  matchesAssistantMessage(message: unknown, model: PiModel | undefined): boolean;
+  normalizeUsage(message: unknown): UsageSnapshot | undefined;
+  warningText?(model: PiModel): string | undefined;
+};
+
+export function isVirtualRoutingModel(model: PiModel | undefined, ctx?: Pick<ExtensionContext, "sessionManager">): boolean {
+  if (!model) return false;
+  return isNativeVirtualModel(model) || isRouterModel(model) || !!getRoutingRegistry()?.getRouter(model.provider) || !!resolveActiveRouteSnapshot(model, ctx);
+}
+
+export function modelFromAssistantMessage(message: unknown, fallback: PiModel | undefined, preferCatalogId = false): PiModel | undefined {
+  const record = getAssistantRecord(message);
+  if (!record) return fallback;
+
+  // Pi's model field is the dispatched catalog id. Legacy routing adapters
+  // can still use responseModel as their only physical identity, so callers
+  // that need catalog attribution opt in rather than changing that protocol.
+  const id = preferCatalogId
+    ? firstNonEmptyString(record.model, record.responseModel, fallback?.id)
+    : firstNonEmptyString(record.responseModel, record.model, fallback?.id);
+  const provider = firstNonEmptyString(record.provider, fallback?.provider);
+  const api = firstNonEmptyString(record.api, fallback?.api) ?? "";
+  if (!id || !provider) return fallback;
+
+  const fallbackName = isNonEmptyString(fallback?.name) ? fallback.name : undefined;
+  const preservesFallbackIdentity =
+    !isVirtualRoutingModel(fallback) &&
+    provider === fallback?.provider &&
+    id === fallback?.id &&
+    fallbackName !== undefined;
+
+  return {
+    ...(fallback ?? {}),
+    id,
+    // Direct providers such as kimi-coding may echo only a short model id
+    // (`k3`) while the active model name (`Kimi K3`) carries the adapter token.
+    // Preserve that display name only when response and fallback identities are
+    // exactly the same; routed/different identities keep message-local naming.
+    name: preservesFallbackIdentity ? fallbackName : id,
+    provider,
+    api,
+    baseUrl: fallback?.baseUrl ?? "",
+    reasoning: fallback?.reasoning ?? false,
+    input: fallback?.input ?? ["text"],
+    cost: fallback?.cost ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: fallback?.contextWindow ?? 0,
+    maxTokens: fallback?.maxTokens ?? 0,
+  } as PiModel;
+}
+
+/**
+ * Model families that share one adapter shape: usage is read from OpenAI-shaped
+ * fields and the OpenAI-compatible proxy compat warning applies. A family
+ * matches when any of the model's (or the assistant message's) lowercase id /
+ * name tokens contains one of `needles`, or satisfies `pattern`. Order matters:
+ * the first matching adapter wins, so it follows the specific adapters above.
+ * Supporting a new family is one row here.
+ */
+export type OpenAIShapedFamily = { label: string; needles: string[]; pattern?: RegExp };
+
+export const OPENAI_SHAPED_FAMILIES: OpenAIShapedFamily[] = [
+  { label: "Kimi cache", needles: ["kimi"] },
+  { label: "Qwen cache", needles: ["qwen"] },
+  { label: "GLM cache", needles: ["glm"] },
+  { label: "MiniMax cache", needles: ["minimax"] },
+  { label: "Mimo cache", needles: ["xiaomimimo"], pattern: MIMO_MODEL_PATTERN },
+  { label: "Hunyuan cache", needles: ["hunyuan"] },
+  { label: "Mistral cache", needles: ["mistral", "mixtral", "codestral"] },
+  { label: "Grok cache", needles: ["grok"], pattern: XAI_MODEL_PATTERN },
+  { label: "Llama cache", needles: ["llama"] },
+  { label: "Nemotron cache", needles: ["nemotron"] },
+  { label: "Cohere cache", needles: ["cohere", "command-r"] },
+  { label: "Yi cache", needles: ["yi-", "01-ai", "zero-one"], pattern: YI_MODEL_PATTERN },
+  { label: "Doubao cache", needles: ["doubao", "豆包", "volcengine", "bytedance", "byte-dance"], pattern: DOUBAO_SEED_PATTERN },
+  { label: "ERNIE cache", needles: ["ernie", "wenxin", "文心", "yiyan", "一言", "baidu"] },
+  { label: "Baichuan cache", needles: ["baichuan", "百川"] },
+  { label: "StepFun cache", needles: ["stepfun", "step-"] },
+  { label: "Spark cache", needles: ["spark", "xinghuo", "星火", "iflytek", "讯飞"] },
+  { label: "InternLM cache", needles: ["internlm", "intern-lm", "书生"] },
+  { label: "Gemma cache", needles: ["gemma"] },
+  { label: "Phi cache", needles: ["phi-"], pattern: PHI_MODEL_PATTERN },
+  { label: "Jamba cache", needles: ["jamba", "ai21"] },
+  { label: "Solar cache", needles: ["solar", "upstage"] },
+  { label: "Sonar cache", needles: ["sonar", "perplexity"], pattern: PPLX_MODEL_PATTERN },  // Perplexity / Sonar
+  { label: "Nova cache", needles: ["amazon-nova"], pattern: NOVA_MODEL_PATTERN },  // Amazon Nova
+  { label: "Reka cache", needles: ["reka"] },  // Reka
+  { label: "Falcon cache", needles: ["falcon", "tiiuae"] },  // Falcon / TII
+  { label: "DBRX cache", needles: ["dbrx", "databricks"] },  // Databricks DBRX
+  { label: "MPT cache", needles: ["mosaicml", "mpt-"], pattern: MPT_MODEL_PATTERN },  // MosaicML MPT
+  { label: "StableLM cache", needles: ["stablelm", "stable-lm", "stability-ai"] },  // StableLM / Stability AI
+  { label: "Aquila cache", needles: ["aquila", "baai"] },  // BAAI / Aquila
+  { label: "EXAONE cache", needles: ["exaone"] },  // LG EXAONE
+  { label: "HyperCLOVA cache", needles: ["hyperclova", "clova-x"] },  // Naver HyperCLOVA X (conservative: hyperclova, clova-x only)
+  { label: "Luminous cache", needles: ["luminous", "aleph-alpha"], pattern: ALEPH_MODEL_PATTERN },  // Aleph Alpha Luminous
+  { label: "Hermes cache", needles: ["nous", "hermes", "openhermes"] },  // Nous / Hermes / OpenHermes
+  { label: "Granite cache", needles: ["granite", "ibm-granite"] },  // IBM Granite
+  { label: "Arctic cache", needles: ["snowflake-arctic"], pattern: ARCTIC_MODEL_PATTERN },  // Snowflake Arctic
+  { label: "Pangu cache", needles: ["pangu", "pan-gu", "盘古", "huawei-pangu"] },  // Huawei Pangu / 盘古
+  { label: "SenseNova cache", needles: ["sensenova", "sense-nova", "sensechat", "商汤"] },  // SenseTime SenseNova / 商汤
+  { label: "Zhinao cache", needles: ["360gpt", "360-gpt", "zhinao", "智脑"] },  // 360 Zhinao / 智脑
+  { label: "MiniCPM cache", needles: ["minicpm", "mini-cpm", "openbmb"] },  // OpenBMB MiniCPM
+  { label: "XVERSE cache", needles: ["xverse"] },  // XVERSE
+  { label: "Orion cache", needles: ["orionstar", "orion-star"], pattern: ORION_MODEL_PATTERN },  // OrionStar Orion
+  { label: "OpenChat cache", needles: ["openchat"] },  // OpenChat
+  { label: "Vicuna cache", needles: ["vicuna"] },  // Vicuna
+  { label: "Wizard cache", needles: ["wizardlm", "wizard-lm", "wizardcoder", "wizard-coder"] },  // WizardLM / WizardCoder
+  { label: "Zephyr cache", needles: ["zephyr"] },  // Zephyr
+  { label: "Dolphin cache", needles: ["dolphin"] },  // Dolphin
+  { label: "OpenOrca cache", needles: ["openorca", "open-orca"] },  // OpenOrca
+  { label: "Starling cache", needles: ["starling"] },  // Starling
+  { label: "BLOOM cache", needles: ["bloom", "bigscience"] },  // BLOOM / BigScience
+  { label: "RWKV cache", needles: ["rwkv"] },  // RWKV
+  { label: "Aya cache", needles: ["aya-expanse"], pattern: AYA_MODEL_PATTERN },  // Cohere Aya
+];
+
+export function familyMatchesTokens(family: OpenAIShapedFamily, tokens: string[]): boolean {
+  return hasAnyTokenContaining(tokens, family.needles) || (family.pattern !== undefined && tokens.some((token) => family.pattern!.test(token)));
+}
+
+export function createOpenAIShapedAdapter(family: OpenAIShapedFamily): CacheProviderAdapter {
+  return {
+    id: "openai" as CacheProviderId,
+    label: family.label,
+    matchesModel: (model) => familyMatchesTokens(family, getModelIdNameTokenValues(model)),
+    matchesAssistantMessage(message, model) {
+      if (!isAssistantMessage(message)) return false;
+      return familyMatchesTokens(family, [...getModelIdNameTokenValues(model), ...getAssistantMessageModelTokenValues(message)]);
+    },
+    normalizeUsage(message) {
+      return normalizeWithFallback(message, getOpenAIRawUsage);
+    },
+    warningText(model) {
+      const missing = describeMissingOpenAICompatibleProxyCompat(model);
+      if (missing.length === 0) return undefined;
+      return buildOpenAIProxyCompatWarningText(modelKey(model), missing);
+    },
+  };
+}
+
+export const OPENAI_SHAPED_FAMILY_ADAPTERS: CacheProviderAdapter[] = OPENAI_SHAPED_FAMILIES.map(createOpenAIShapedAdapter);
+
+export const CACHE_PROVIDER_ADAPTERS: CacheProviderAdapter[] = [
+  {
+    id: "deepseek",
+    label: "DS cache",
+    matchesModel: isDeepSeekLikeModel,
+    matchesAssistantMessage(message, model) {
+      if (!isAssistantMessage(message)) return false;
+      return isDeepSeekLikeAssistantMessage(message, model);
+    },
+    normalizeUsage(message) {
+      return normalizeWithFallback(message, getDeepSeekRawUsage, { allowInputOnlyPiUsage: true });
+    },
+    warningText(model) {
+      const missing = describeMissingCacheCompatForModel(model);
+      if (missing.length === 0) return undefined;
+
+      const key = modelKey(model);
+      return isDeepSeekWireCompatApplicable(model)
+        ? buildDeepSeekCompatWarningText(key, missing)
+        : buildOpenAIProxyCompatWarningText(key, missing);
+    },
+  },
+  {
+    id: "claude",
+    label: "Claude cache",
+    showCacheWrite: true,
+    matchesModel: isClaudeLikeModel,
+    matchesAssistantMessage(message, model) {
+      if (!isAssistantMessage(message)) return false;
+      return isClaudeLikeAssistantMessage(message, model);
+    },
+    normalizeUsage(message) {
+      return normalizeWithFallback(message, getAnthropicRawUsage);
+    },
+    warningText(model) {
+      if (!isClaudeLikeModel(model) || !isOpenAICompatibleApi(model.api) || isPiBuiltInLlamaCppModel(model)) return undefined;
+      if (getCompat(model).cacheControlFormat === "anthropic") return undefined;
+
+      return (
+        `💡 Cache optimizer: ${modelKey(model)} looks Claude/Anthropic-like but OpenAI-compatible compat lacks cacheControlFormat: "anthropic". ` +
+        "Pi may not place Anthropic cache_control breakpoints unless this endpoint supports and enables that compat flag."
+      );
+    },
+  },
+  {
+    id: "openai",
+    label: "OpenAI cache",
+    matchesModel: isOpenAIFamilyModel,
+    matchesAssistantMessage(message, model) {
+      if (!isAssistantMessage(message)) return false;
+      return isOpenAIFamilyAssistantMessage(message, model);
+    },
+    normalizeUsage(message) {
+      return normalizeWithFallback(message, getOpenAIRawUsage);
+    },
+    warningText(model) {
+      const missing = describeMissingOpenAICompatibleProxyCompat(model);
+      if (missing.length === 0) return undefined;
+      return buildOpenAIProxyCompatWarningText(modelKey(model), missing);
+    },
+  },
+  {
+    id: "gemini",
+    label: "Gemini cache",
+    matchesModel: isGeminiLikeModel,
+    matchesAssistantMessage(message, model) {
+      if (!isAssistantMessage(message)) return false;
+      return isGeminiLikeAssistantMessage(message, model);
+    },
+    normalizeUsage(message) {
+      return normalizeWithFallback(message, getGeminiRawUsage);
+    },
+  },
+  // ── Non-GPT OpenAI-compatible adapters ──────────────────────
+  // ── More OpenAI-compatible adapters ──────────────────────────
+  // ── More OpenAI-compatible adapters (batch 2) ───────────────────
+  // ── New OpenAI-compatible adapters (batch 3, 12 families) ────────
+  // ── More OpenAI-compatible adapters (batch 4, 18 families) ────────
+  ...OPENAI_SHAPED_FAMILY_ADAPTERS,
+];
+
+export function selectAdapterForModel(model: PiModel | undefined): CacheProviderAdapter | undefined {
+  // A native virtual selection has no cache identity of its own; stats always
+  // belong to the physical model it routed to.
+  if (isNativeVirtualModel(model)) return undefined;
+  return CACHE_PROVIDER_ADAPTERS.find((adapter) => adapter.matchesModel(model));
+}
+
+export function selectAdapterForAssistantMessage(message: unknown, model: PiModel | undefined): CacheProviderAdapter | undefined {
+  // Assistant message metadata is request-local and authoritative for virtual
+  // routing providers. Use it first for every model; direct providers normally
+  // echo the same provider/model and therefore remain unchanged.
+  const responseModel = modelFromAssistantMessage(message, model);
+  return CACHE_PROVIDER_ADAPTERS.find((adapter) => adapter.matchesAssistantMessage(message, responseModel));
+}

package/src/atomic-fs.ts

@@ -0,0 +1,300 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import { chmod, copyFile, link, lstat, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { LOG_PREFIX, asRecord, getErrorCode, isProcessAlive } from "./common.ts";
+import { MODELS_TRANSACTION_LOCK_PATH, MODELS_TRANSACTION_LOCK_STALE_MS, MODELS_TRANSACTION_LOCK_WAIT_MS, STATE_DIR } from "./paths.ts";
+
+/**
+ * Generate a unique UTC timestamp component for backup filenames.
+ * Milliseconds, process id, and an in-process sequence prevent collisions.
+ */
+export let backupSequence = 0;
+
+export function backupTimestamp(now: Date = new Date()): string {
+  const y = now.getUTCFullYear();
+  const m = String(now.getUTCMonth() + 1).padStart(2, "0");
+  const d = String(now.getUTCDate()).padStart(2, "0");
+  const h = String(now.getUTCHours()).padStart(2, "0");
+  const min = String(now.getUTCMinutes()).padStart(2, "0");
+  const s = String(now.getUTCSeconds()).padStart(2, "0");
+  const ms = String(now.getUTCMilliseconds()).padStart(3, "0");
+  return `${y}${m}${d}T${h}${min}${s}${ms}Z-${process.pid}-${backupSequence++}`;
+}
+
+export function uniqueTempPath(targetPath: string, purpose: string): string {
+  return `${targetPath}.${process.pid}.${Date.now()}.${backupSequence++}.${purpose}.tmp`;
+}
+
+export type FileIdentity = { dev: number | bigint; ino: number | bigint };
+
+export function sameFileIdentity(left: FileIdentity, right: FileIdentity): boolean {
+  // Some platforms do not expose a meaningful inode. On those platforms the
+  // hash checks around the transaction remain authoritative.
+  const leftDev = Number(left.dev);
+  const rightDev = Number(right.dev);
+  const leftIno = Number(left.ino);
+  const rightIno = Number(right.ino);
+  return leftIno === 0 || rightIno === 0 || (leftDev === rightDev && leftIno === rightIno);
+}
+
+export type AtomicTargetGuard = {
+  identity?: FileIdentity;
+  hash?: string;
+  mode?: number;
+};
+
+export async function validateAtomicTarget(
+  targetPath: string,
+  guard?: AtomicTargetGuard,
+): Promise<Awaited<ReturnType<typeof lstat>>> {
+  const info = await lstat(targetPath);
+  if (info.isSymbolicLink() || !info.isFile()) {
+    throw new Error("target is not a regular file; refusing atomic replacement");
+  }
+  if (guard?.identity && !sameFileIdentity(guard.identity, info)) {
+    throw new Error("target changed during atomic replacement");
+  }
+  if (guard?.mode !== undefined && (info.mode & 0o7777) !== guard.mode) {
+    throw new Error("target access mode changed during atomic replacement");
+  }
+  if (guard?.hash !== undefined) {
+    const text = await readFile(targetPath, "utf8");
+    if (hashText(text) !== guard.hash) {
+      throw new Error("target content changed during atomic replacement");
+    }
+  }
+  return info;
+}
+
+export async function atomicReplaceTextFilePreservingMode(
+  targetPath: string,
+  content: string,
+  mode: number,
+  purpose: string,
+  guard?: AtomicTargetGuard,
+  /** Test-only race injector; production callers leave this undefined. */
+  beforeRename?: () => Promise<void>,
+): Promise<void> {
+  const initialTargetInfo = await validateAtomicTarget(targetPath, guard);
+  const tempPath = uniqueTempPath(targetPath, purpose);
+  try {
+    // `wx` makes the unique temporary path non-overwriting even if a hostile
+    // or stale file appears between name generation and the write.
+    await writeFile(tempPath, content, { encoding: "utf8", mode, flag: "wx" });
+    const tempInfo = await lstat(tempPath);
+    if (tempInfo.isSymbolicLink() || !tempInfo.isFile()) {
+      throw new Error("temporary replacement is not a regular file");
+    }
+    await chmod(tempPath, mode);
+    await validateAtomicTarget(targetPath, {
+      ...guard,
+      identity: initialTargetInfo,
+      mode,
+    });
+    if (beforeRename) await beforeRename();
+    await validateAtomicTarget(targetPath, {
+      ...guard,
+      identity: initialTargetInfo,
+      mode,
+    });
+    await rename(tempPath, targetPath);
+  } catch (error) {
+    try {
+      await unlink(tempPath);
+    } catch (cleanupError) {
+      if (getErrorCode(cleanupError) !== "ENOENT") {
+        console.warn(`${LOG_PREFIX}: failed to remove temporary models.json file`, cleanupError);
+      }
+    }
+    throw error;
+  }
+}
+
+export async function atomicCreateTextFileNoReplace(
+  targetPath: string,
+  content: string,
+  mode: number,
+  purpose: string,
+  /** Test-only race injector; production callers leave this undefined. */
+  beforeLink?: () => Promise<void>,
+): Promise<void> {
+  const tempPath = uniqueTempPath(targetPath, purpose);
+  try {
+    await writeFile(tempPath, content, { encoding: "utf8", mode, flag: "wx" });
+    const tempInfo = await lstat(tempPath);
+    if (tempInfo.isSymbolicLink() || !tempInfo.isFile()) {
+      throw new Error("temporary creation is not a regular file");
+    }
+    await chmod(tempPath, mode);
+    // A hard link gives us an atomic no-replace create. Unlike rename(), it
+    // cannot overwrite a file that appeared after the absence check.
+    if (beforeLink) await beforeLink();
+    await link(tempPath, targetPath);
+    await unlink(tempPath).catch((cleanupError) => {
+      console.warn(`${LOG_PREFIX}: committed config file but failed to remove its temporary hard link`, cleanupError);
+    });
+  } catch (error) {
+    try {
+      await unlink(tempPath);
+    } catch (cleanupError) {
+      if (getErrorCode(cleanupError) !== "ENOENT") {
+        console.warn(`${LOG_PREFIX}: failed to remove temporary config file`, cleanupError);
+      }
+    }
+    throw error;
+  }
+}
+
+export async function atomicRestoreFileFromBackup(
+  backupPath: string,
+  targetPath: string,
+  mode: number,
+  guard?: AtomicTargetGuard & { backupHash?: string },
+  /** Test-only race injector; production callers leave this undefined. */
+  beforeRename?: () => Promise<void>,
+): Promise<void> {
+  const backupInfo = await lstat(backupPath);
+  if (backupInfo.isSymbolicLink() || !backupInfo.isFile()) {
+    throw new Error("backup is not a regular file; refusing atomic restore");
+  }
+  if (guard?.backupHash !== undefined) {
+    const backupText = await readFile(backupPath, "utf8");
+    if (hashText(backupText) !== guard.backupHash) {
+      throw new Error("backup content changed during atomic restore");
+    }
+  }
+  const targetInfo = await validateAtomicTarget(targetPath, guard);
+  const tempPath = uniqueTempPath(targetPath, "restore");
+  try {
+    await copyFile(backupPath, tempPath, fsConstants.COPYFILE_EXCL);
+    const tempInfo = await lstat(tempPath);
+    if (tempInfo.isSymbolicLink() || !tempInfo.isFile()) {
+      throw new Error("temporary restore is not a regular file");
+    }
+    await chmod(tempPath, mode);
+    const tempText = await readFile(tempPath, "utf8");
+    if (guard?.backupHash !== undefined && hashText(tempText) !== guard.backupHash) {
+      throw new Error("backup content changed during atomic restore");
+    }
+    await validateAtomicTarget(targetPath, {
+      ...guard,
+      identity: targetInfo,
+    });
+    if (beforeRename) await beforeRename();
+    await validateAtomicTarget(targetPath, {
+      ...guard,
+      identity: targetInfo,
+    });
+    await rename(tempPath, targetPath);
+  } catch (error) {
+    try {
+      await unlink(tempPath);
+    } catch (cleanupError) {
+      if (getErrorCode(cleanupError) !== "ENOENT") {
+        console.warn(`${LOG_PREFIX}: failed to remove temporary restore file`, cleanupError);
+      }
+    }
+    throw error;
+  }
+}
+
+export function hashText(text: string): string {
+  return createHash("sha256").update(text, "utf8").digest("hex");
+}
+
+export async function withModelsJsonTransactionLock<T>(operation: () => Promise<T>): Promise<T> {
+  await mkdir(STATE_DIR, { recursive: true });
+  const deadline = Date.now() + MODELS_TRANSACTION_LOCK_WAIT_MS;
+  const ownerToken = randomUUID();
+  const ownerText = JSON.stringify({ pid: process.pid, token: ownerToken });
+  let ownedLockIdentity: FileIdentity | undefined;
+  while (true) {
+    try {
+      // A single O_EXCL file is the lease: unlike mkdir-then-owner-file, there
+      // is no ownerless crash window between creating the lock and identifying
+      // its owner.
+      await writeFile(MODELS_TRANSACTION_LOCK_PATH, ownerText, {
+        encoding: "utf8",
+        mode: 0o600,
+        flag: "wx",
+      });
+      const lockInfo = await lstat(MODELS_TRANSACTION_LOCK_PATH);
+      if (lockInfo.isSymbolicLink() || !lockInfo.isFile()) {
+        throw new Error("models.json transaction lock path is unsafe");
+      }
+      ownedLockIdentity = lockInfo;
+      break;
+    } catch (error) {
+      if (getErrorCode(error) !== "EEXIST") throw error;
+      const lockInfo = await lstat(MODELS_TRANSACTION_LOCK_PATH).catch(() => undefined);
+      if (!lockInfo) continue;
+      if (lockInfo.isSymbolicLink() || !lockInfo.isFile()) {
+        throw new Error("models.json transaction lock path is unsafe");
+      }
+      let staleOwnerPid: number | undefined;
+      try {
+        const owner = asRecord(JSON.parse(await readFile(MODELS_TRANSACTION_LOCK_PATH, "utf8")));
+        if (typeof owner?.pid === "number") staleOwnerPid = owner.pid;
+      } catch {}
+      const stale = Date.now() - lockInfo.mtimeMs > MODELS_TRANSACTION_LOCK_STALE_MS;
+      if (stale && (staleOwnerPid === undefined || !isProcessAlive(staleOwnerPid))) {
+        // Recheck identity immediately before unlinking so a recovered owner
+        // cannot delete a replacement lease created at the same path.
+        const currentLock = await lstat(MODELS_TRANSACTION_LOCK_PATH).catch(() => undefined);
+        if (currentLock && sameFileIdentity(lockInfo, currentLock)) {
+          await unlink(MODELS_TRANSACTION_LOCK_PATH).catch((unlinkError) => {
+            if (getErrorCode(unlinkError) !== "ENOENT") throw unlinkError;
+          });
+        }
+        continue;
+      }
+      if (Date.now() >= deadline) {
+        throw new Error("another cache-optimizer models.json transaction is still running");
+      }
+      await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+  }
+
+  try {
+    return await operation();
+  } finally {
+    // Only the matching inode and owner token may remove the lease. A
+    // recovered/replaced lock belongs to another transaction.
+    try {
+      const currentLock = await lstat(MODELS_TRANSACTION_LOCK_PATH);
+      if (
+        ownedLockIdentity &&
+        !currentLock.isSymbolicLink() &&
+        currentLock.isFile() &&
+        sameFileIdentity(ownedLockIdentity, currentLock) &&
+        await readFile(MODELS_TRANSACTION_LOCK_PATH, "utf8") === ownerText
+      ) {
+        await unlink(MODELS_TRANSACTION_LOCK_PATH);
+      }
+    } catch (error) {
+      if (getErrorCode(error) !== "ENOENT") {
+        console.warn(`${LOG_PREFIX}: failed to remove models.json transaction lock`, error);
+      }
+    }
+  }
+}
+
+export async function readRegularTextFile(path: string): Promise<{ text: string; mode: number }> {
+  const info = await lstat(path);
+  if (info.isSymbolicLink() || !info.isFile()) {
+    throw new Error("file is not a regular file");
+  }
+  const text = await readFile(path, "utf8");
+  const afterRead = await lstat(path);
+  if (
+    afterRead.isSymbolicLink() ||
+    !afterRead.isFile() ||
+    !sameFileIdentity(info, afterRead)
+  ) {
+    throw new Error("file changed while it was being read");
+  }
+  return {
+    text,
+    mode: afterRead.mode & 0o7777,
+  };
+}