codex-copilot-dx 0.6.14 → 0.6.18

package/src/pm-studio-setup.mjs

@@ -12,7 +12,10 @@ import {
   PM_STUDIO_2_9_10_RECIPE,
   PM_STUDIO_RECIPES,
   createCompatiblePmStudioRecipe,
+  createCompatiblePmStudioRecipeFromFile,
+  inspectAsarFile,
   inspectElectronAsarIntegritySlots,
+  inspectElectronAsarIntegrityFile,
   inspectAsarBuffer,
   patchAsarBuffer,
   sha256Hex,
@@ -57,10 +60,10 @@ function runChecked(processRunner, command, args, label) {
   return result;
 }
 
-function hashRegularFile(filePath, expected) {
+function hashRegularFile(filePath, expected, readBuffer) {
   const hash = createHash("sha256");
   const file = fs.openSync(filePath, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
-  const buffer = Buffer.allocUnsafe(1024 * 1024);
+  const buffer = readBuffer || Buffer.allocUnsafe(1024 * 1024);
   try {
     const before = fs.fstatSync(file, { bigint: true });
     if (before.dev !== BigInt(expected.dev)
@@ -136,6 +139,7 @@ function parseXattrHex(output, root, ignoredXattrs) {
 export function inspectBundleContent(appPath, {
   xattrOutput = "",
   ignoredXattrs = [],
+  readBuffer,
 } = {}) {
   const root = path.resolve(appPath);
   const rootStat = fs.lstatSync(root);
@@ -186,7 +190,7 @@ export function inspectBundleContent(appPath, {
         }
         regularFileCount += 1;
         regularBytes += stat.size;
-        records.push(["file", relative, mode, stat.size, hashRegularFile(fullPath, stat)]);
+        records.push(["file", relative, mode, stat.size, hashRegularFile(fullPath, stat, readBuffer)]);
       } else {
         throw setupError("PM_STUDIO_BUNDLE_ENTRY_INVALID", `PM Studio contains an unsupported entry: ${relative}`);
       }
@@ -208,12 +212,13 @@ export function inspectBundleContent(appPath, {
   };
 }
 
-function defaultInspectBundleContent({ appPath, recipe, processRunner }) {
+function defaultInspectBundleContent({ appPath, recipe, processRunner, readBuffer }) {
   const xattrs = runChecked(processRunner, "/usr/bin/xattr", ["-r", "-s", "-x", "-l", appPath],
     "Reading PM Studio extended attributes");
   return inspectBundleContent(appPath, {
     xattrOutput: xattrs.stdout,
     ignoredXattrs: recipe.sourceBundleContent?.ignoredXattrs || [],
+    readBuffer,
   });
 }
 
@@ -316,6 +321,55 @@ function defaultInspectExecutableIntegrity({ appPath, infoPlistPath, recipe, pro
   };
 }
 
+function statusInspectExecutableIntegrity({ appPath, infoPlistPath, recipe, processRunner, evidenceCache }) {
+  const executableName = plistRead(processRunner, infoPlistPath, "CFBundleExecutable");
+  if (!executableName || path.basename(executableName) !== executableName) {
+    throw setupError("PM_STUDIO_EXECUTABLE_INVALID", "PM Studio CFBundleExecutable is invalid");
+  }
+  const executablePath = path.join(appPath, "Contents", "MacOS", executableName);
+  const frameworkPath = path.join(appPath, recipe.electronFrameworkPath);
+  const executable = inspectElectronAsarIntegrityFile(executablePath, { cache: evidenceCache });
+  const framework = inspectElectronAsarIntegrityFile(frameworkPath, { cache: evidenceCache });
+  return {
+    executableName,
+    executablePath,
+    executableSha256: executable.sha256,
+    frameworkPath,
+    frameworkSha256: framework.sha256,
+    embeddedIntegrity: {
+      state: executable.integrity.slots.length === 0 && framework.integrity.slots.length === 0 ? "absent" : "present",
+      supported: executable.integrity.slots.length === 0 && framework.integrity.slots.length === 0,
+      executable: executable.integrity,
+      framework: framework.integrity,
+    },
+    matchesRecipeName: executableName === recipe.executable,
+  };
+}
+
+export function createPmStudioStatusOperationOverrides() {
+  const evidenceCache = new Map();
+  const bundleReadBuffer = Buffer.allocUnsafe(1024 * 1024);
+  return {
+    inspectExecutableIntegrity: (args) => statusInspectExecutableIntegrity({
+      ...args,
+      evidenceCache,
+    }),
+    inspectAsarFile: ({ asarPath, recipe }) => inspectAsarFile(asarPath, recipe, {
+      cache: evidenceCache,
+      releaseTargets: true,
+    }),
+    createCompatibleRecipeFromFile: ({ asarPath, options }) => createCompatiblePmStudioRecipeFromFile(
+      asarPath,
+      options,
+      { cache: evidenceCache, releaseTargets: true },
+    ),
+    inspectBundleContent: (args) => defaultInspectBundleContent({
+      ...args,
+      readBuffer: bundleReadBuffer,
+    }),
+  };
+}
+
 function defaultSignApp({ appPath, source, processRunner }) {
   const preserve = [];
   if (source?.codeSign?.displayValid === true) {
@@ -411,6 +465,17 @@ function defaultAssertPermissions({ appPath, backupRoot }) {
   }
 }
 
+function defaultAssertRestorePermissions({ appPath, backupAppPath }) {
+  try {
+    fs.accessSync(appPath, fs.constants.R_OK | fs.constants.X_OK);
+    fs.accessSync(path.dirname(appPath), fs.constants.W_OK | fs.constants.X_OK);
+    fs.accessSync(backupAppPath, fs.constants.R_OK | fs.constants.X_OK);
+  } catch {
+    throw setupError("PM_STUDIO_PERMISSION_DENIED",
+      "PM Studio or its verified backup is not accessible to the current user; restore will not use sudo");
+  }
+}
+
 export function createPmStudioSetupOperations(overrides = {}) {
   const processRunner = overrides.processRunner || defaultProcessRunner;
   return {
@@ -432,6 +497,7 @@ export function createPmStudioSetupOperations(overrides = {}) {
     availableBytes: defaultAvailableBytes,
     volumeId: defaultVolumeId,
     assertPermissions: defaultAssertPermissions,
+    assertRestorePermissions: defaultAssertRestorePermissions,
     readClaudeCredentials: ({ home }) => readAuthProfileCredentials(AUTH_PROFILE_CLAUDE, { home }),
     now: () => new Date(),
     uuid: () => randomUUID(),
@@ -470,7 +536,9 @@ export function inspectPmStudioApp({
   const paths = appPaths(appPath, recipe);
   const issues = [];
   const metadata = operations.readBundleMetadata({ ...paths, recipe, processRunner: operations.processRunner });
-  const asar = inspectAsarBuffer(fs.readFileSync(paths.asarPath), recipe);
+  const asar = operations.inspectAsarFile
+    ? operations.inspectAsarFile({ ...paths, recipe, processRunner: operations.processRunner })
+    : inspectAsarBuffer(fs.readFileSync(paths.asarPath), recipe);
   const plistIntegrity = operations.readAsarIntegrity({ ...paths, recipe, processRunner: operations.processRunner });
   const executableIntegrity = operations.inspectExecutableIntegrity({
     ...paths, recipe, processRunner: operations.processRunner,
@@ -679,11 +747,14 @@ function compatibleSourceStructure({ appPath, metadata, operations }) {
     throw setupError("PM_STUDIO_ASAR_INCOMPATIBLE",
       "PM Studio compatible-version discovery found an unsupported executable or embedded ASAR integrity policy");
   }
-  const compatibleRecipe = createCompatiblePmStudioRecipe(fs.readFileSync(paths.asarPath), {
+  const recipeOptions = {
     ...compatibleStaticOptions(metadata, executableIntegrity.executableName),
     sourceExecutableSha256: executableIntegrity.executableSha256,
     sourceElectronFrameworkSha256: executableIntegrity.frameworkSha256,
-  });
+  };
+  const compatibleRecipe = operations.createCompatibleRecipeFromFile
+    ? operations.createCompatibleRecipeFromFile({ asarPath: paths.asarPath, options: recipeOptions })
+    : createCompatiblePmStudioRecipe(fs.readFileSync(paths.asarPath), recipeOptions);
   const plistIntegrity = operations.readAsarIntegrity({
     ...paths,
     recipe: compatibleRecipe,
@@ -737,11 +808,14 @@ function compatibleRecipeFromManifest({ backupDir, manifest, metadata, operation
     recipe: PM_STUDIO_2_9_10_RECIPE,
     processRunner: operations.processRunner,
   });
-  const compatibleRecipe = createCompatiblePmStudioRecipe(fs.readFileSync(sourceAsarPath), {
+  const recipeOptions = {
     ...compatibleStaticOptions(metadata, executableIntegrity.executableName),
     sourceExecutableSha256: manifest?.source?.binaries?.main_executable_sha256,
     sourceElectronFrameworkSha256: manifest?.source?.binaries?.electron_framework_sha256,
-  });
+  };
+  const compatibleRecipe = operations.createCompatibleRecipeFromFile
+    ? operations.createCompatibleRecipeFromFile({ asarPath: sourceAsarPath, options: recipeOptions })
+    : createCompatiblePmStudioRecipe(fs.readFileSync(sourceAsarPath), recipeOptions);
   const recipe = Object.freeze({
     ...compatibleRecipe,
     sourceBundleContent: frozenBundleContent(manifest.source.bundle_content),
@@ -766,7 +840,8 @@ function compatibleRecipeFromManifest({ backupDir, manifest, metadata, operation
 
 function compatibleRecipeFromBackup({ appPath, backupRoot, metadata, operations }) {
   if (!fs.existsSync(backupRoot)) return null;
-  const installedAsar = fs.readFileSync(path.join(appPath, PM_STUDIO_2_9_10_RECIPE.asarPath));
+  const installedAsarPath = path.join(appPath, PM_STUDIO_2_9_10_RECIPE.asarPath);
+  const installedAsar = operations.inspectAsarFile ? null : fs.readFileSync(installedAsarPath);
   let candidates = [];
   const invalidCandidates = [];
   for (const entry of fs.readdirSync(backupRoot, { withFileTypes: true })) {
@@ -788,7 +863,9 @@ function compatibleRecipeFromBackup({ appPath, backupRoot, metadata, operations
       continue;
     }
     if (!recipe) continue;
-    const asarState = inspectAsarBuffer(installedAsar, recipe).state;
+    const asarState = operations.inspectAsarFile
+      ? operations.inspectAsarFile({ asarPath: installedAsarPath, recipe }).state
+      : inspectAsarBuffer(installedAsar, recipe).state;
     if (asarState === "drift") continue;
     candidates.push({ recipe, manifest, asarState });
   }
@@ -1188,6 +1265,74 @@ function assertSpace({ appPath, backupRoot, backupExists, operations }) {
   }
 }
 
+function assertRestoreSpace({ appPath, backupAppPath, operations }) {
+  const bundleBytes = operations.bundleSize(backupAppPath);
+  if (!Number.isFinite(bundleBytes) || bundleBytes <= 0) {
+    throw setupError("PM_STUDIO_SIZE_INVALID", "Could not determine verified PM Studio backup size");
+  }
+  if (operations.availableBytes(path.dirname(appPath)) < bundleBytes + MIN_FREE_MARGIN_BYTES) {
+    throw setupError("PM_STUDIO_SPACE_INSUFFICIENT", "Not enough free space for PM Studio restore staging");
+  }
+}
+
+function codeSignFingerprint(codeSign) {
+  return {
+    valid: codeSign?.valid === true,
+    verifyValid: codeSign?.verifyValid === true,
+    displayValid: codeSign?.displayValid === true,
+    entitlementsState: codeSign?.entitlementsState || "",
+    adHoc: codeSign?.adHoc === true,
+    identifier: codeSign?.identifier || "",
+    teamIdentifier: codeSign?.teamIdentifier || "",
+    flags: codeSign?.flags || "",
+    runtimeVersion: codeSign?.runtimeVersion || "",
+    cdHashFull: codeSign?.cdHashFull || "",
+    notarizationTicket: codeSign?.notarizationTicket || "",
+    entitlementsSha256: codeSign?.entitlementsSha256 || "",
+  };
+}
+
+function restoreStateFingerprint(inspection, bundleContent) {
+  return JSON.stringify({
+    state: inspection.state,
+    metadata: inspection.metadata,
+    asar: {
+      state: inspection.asar?.state,
+      asarSha256: inspection.asar?.asarSha256,
+      headerSha256: inspection.asar?.headerSha256,
+    },
+    plistIntegrity: inspection.plistIntegrity,
+    executableIntegrity: {
+      executableName: inspection.executableIntegrity?.executableName,
+      executableSha256: inspection.executableIntegrity?.executableSha256,
+      frameworkSha256: inspection.executableIntegrity?.frameworkSha256,
+      embeddedIntegrity: inspection.executableIntegrity?.embeddedIntegrity,
+      matchesRecipeName: inspection.executableIntegrity?.matchesRecipeName,
+    },
+    codeSign: codeSignFingerprint(inspection.codeSign),
+    bundleContent,
+  });
+}
+
+function inspectRestoreState({ appPath, recipe, operations }) {
+  const inspection = inspectPmStudioApp({ appPath, recipe, operations });
+  const bundleContent = inspection.bundleContent || operations.inspectBundleContent({
+    ...appPaths(appPath, recipe),
+    recipe,
+    processRunner: operations.processRunner,
+  });
+  return {
+    inspection,
+    fingerprint: restoreStateFingerprint(inspection, bundleContent),
+  };
+}
+
+function assertRestoreStateMatches(actual, expected, code, message) {
+  if (actual.fingerprint !== expected.fingerprint) {
+    throw setupError(code, message, actual.inspection.issues);
+  }
+}
+
 function replaceVerifiedStage({ appPath, stagePath, operations }) {
   try {
     operations.replaceApp({ appPath, stagePath, processRunner: operations.processRunner });
@@ -1376,9 +1521,8 @@ export async function runPmStudioSetup({
     emit(`[OK] Verified backup: ${backup.backupAppPath}${backup.reused ? " (reused)" : ""}`);
     emit(`[OK] Backup manifest: ${backup.manifestPath}`);
     emit("[INFO] The verified staging bundle was installed with Foundation's atomic item replacement.");
-    emit(`[INFO] Restore step 1/3: quit PM Studio and its updater.`);
-    emit(`[INFO] Restore step 2/3: confirm the installed Info.plist still reports version/build ${recipe.version}/${recipe.build}; never restore this backup over another version.`);
-    emit(`[INFO] Restore step 3/3: move ${appPath} aside, copy ${backup.backupAppPath} to that exact path, and verify its signature before launch.`);
+    emit(`[INFO] To restore, quit PM Studio and its updater, then run ${commandName} pms restore.`);
+    emit("[INFO] Restore uses exact source-content verification; the original source signature is inspected and reported but is not an admission gate.");
     emit(`[INFO] Start ${commandName} before using Claude in PM Studio; GPT remains on PM Studio's native GitHub Copilot path.`);
     return {
       status: migratingExistingPatch ? "migrated" : "patched",
@@ -1394,3 +1538,164 @@ export async function runPmStudioSetup({
   }
   });
 }
+
+export async function runPmStudioRestore({
+  commandName = "ccdx",
+  appPath = DEFAULT_PM_STUDIO_APP_PATH,
+  home = os.homedir(),
+  backupRoot = pmStudioBackupRoot(home),
+  recipes = PM_STUDIO_RECIPES,
+  operations: operationOverrides = {},
+  logger = (line) => console.log(line),
+} = {}) {
+  const operations = createPmStudioSetupOperations(operationOverrides);
+  return operations.withSetupLock({ appPath }, async () => {
+    const messages = [];
+    const emit = (message) => {
+      messages.push(message);
+      logger(message);
+    };
+
+    assertInstalledAppPath(appPath);
+    assertNoBlockingProcesses(operations, appPath);
+    const metadata = operations.readBundleMetadata({
+      appPath,
+      infoPlistPath: path.join(appPath, "Contents/Info.plist"),
+      processRunner: operations.processRunner,
+    });
+    const recipe = resolvePmStudioCompatibleRecipe({
+      appPath,
+      home,
+      backupRoot,
+      metadata,
+      recipes,
+      operations,
+    });
+    const source = inspectRestoreState({ appPath, recipe, operations });
+    if (source.inspection.state === "clean") {
+      emit(`[OK] PM Studio ${recipe.version} build ${recipe.build} is already the exact clean local bundle; no files were changed.`);
+      return {
+        status: "already_clean",
+        changed: false,
+        recipe: recipe.id,
+        inspection: source.inspection,
+        messages,
+      };
+    }
+    if (!["patched", "predecessor", "legacy"].includes(source.inspection.state)) {
+      throw setupError("PM_STUDIO_BUNDLE_DRIFT",
+        `PM Studio ${recipe.version} build ${recipe.build} does not match a recorded patch state; no files were changed`,
+        source.inspection.issues);
+    }
+
+    const manifestPath = pmStudioPatchManifestPath({ home, backupRoot, recipe });
+    const backupDir = path.dirname(manifestPath);
+    const backup = validateBackup({ backupDir, recipe, operations });
+    assertPatchedBinaryRecord({
+      inspection: source.inspection,
+      manifestPath: backup.manifestPath,
+      recipe,
+      recordState: source.inspection.state,
+    });
+    operations.assertRestorePermissions({
+      appPath,
+      backupAppPath: backup.backupAppPath,
+      processRunner: operations.processRunner,
+    });
+    assertRestoreSpace({ appPath, backupAppPath: backup.backupAppPath, operations });
+    const manifestSnapshot = fs.readFileSync(backup.manifestPath);
+    const backupSource = inspectRestoreState({ appPath: backup.backupAppPath, recipe, operations });
+    if (backupSource.inspection.state !== "clean") {
+      throw setupError("PM_STUDIO_BACKUP_INVALID", "Verified PM Studio backup is not an exact clean bundle",
+        backupSource.inspection.issues);
+    }
+
+    const stagePath = path.join(path.dirname(appPath),
+      `.${path.basename(appPath)}.ccdx-restore-stage-${operations.uuid()}`);
+    let preserveStage = false;
+    try {
+      operations.copyBundle({
+        source: backup.backupAppPath,
+        destination: stagePath,
+        processRunner: operations.processRunner,
+      });
+      if (!fs.readFileSync(backup.manifestPath).equals(manifestSnapshot)) {
+        throw setupError("PM_STUDIO_BACKUP_CHANGED",
+          "PM Studio backup manifest changed during restore; the verified staging bundle was not installed");
+      }
+      const currentBackup = validateBackup({ backupDir, recipe, operations });
+      const unchangedBackup = inspectRestoreState({
+        appPath: currentBackup.backupAppPath,
+        recipe,
+        operations,
+      });
+      assertRestoreStateMatches(unchangedBackup, backupSource, "PM_STUDIO_BACKUP_CHANGED",
+        "PM Studio backup changed during restore; the verified staging bundle was not installed");
+      const unchangedSource = inspectRestoreState({ appPath, recipe, operations });
+      assertRestoreStateMatches(unchangedSource, source, "PM_STUDIO_SOURCE_CHANGED",
+        "PM Studio changed during restore; the verified staging bundle was not installed");
+      assertPatchedBinaryRecord({
+        inspection: unchangedSource.inspection,
+        manifestPath: backup.manifestPath,
+        recipe,
+        recordState: source.inspection.state,
+      });
+
+      const staged = inspectRestoreState({ appPath: stagePath, recipe, operations });
+      if (staged.inspection.state !== "clean") {
+        throw setupError("PM_STUDIO_RESTORE_STAGE_INVALID",
+          "PM Studio restore staging copy is not an exact clean bundle", staged.inspection.issues);
+      }
+      assertRestoreStateMatches(staged, backupSource, "PM_STUDIO_RESTORE_STAGE_INVALID",
+        "PM Studio restore staging copy differs from the verified clean backup");
+      assertNoBlockingProcesses(operations, appPath);
+
+      const replacementError = replaceVerifiedStage({ appPath, stagePath, operations });
+      let installed;
+      try {
+        installed = inspectRestoreState({ appPath, recipe, operations });
+      } catch {
+        preserveStage = fs.existsSync(stagePath);
+        throw setupError("PM_STUDIO_RESTORE_STATE_UNKNOWN",
+          `PM Studio restore final state could not be verified. Do not launch it. ${recoveryMessage(backup)}${preserveStage ? ` Verified staging retained: ${stagePath}.` : ""}`);
+      }
+      if (installed.inspection.state !== "clean" || installed.fingerprint !== staged.fingerprint) {
+        const originalRetained = installed.fingerprint === source.fingerprint;
+        preserveStage = !originalRetained && fs.existsSync(stagePath);
+        const code = originalRetained
+          ? "PM_STUDIO_RESTORE_REPLACE_FAILED"
+          : "PM_STUDIO_RESTORE_INSTALL_VERIFY_FAILED";
+        const stateMessage = originalRetained
+          ? `The installed PM Studio remains the verified ${source.inspection.state} bundle`
+          : "The installed PM Studio does not match the verified clean backup; do not launch it";
+        throw setupError(code,
+          `${stateMessage}. ${recoveryMessage(backup)}${preserveStage ? ` Verified staging retained: ${stagePath}.` : ""}`,
+          installed.inspection.issues);
+      }
+      if (replacementError) {
+        emit("[WARN] Atomic replacement reported an error after the exact clean bundle became installed; the final bundle was independently verified.");
+      }
+      emit(`[OK] Restored PM Studio ${recipe.version} build ${recipe.build} from the exact verified clean backup.`);
+      emit(`[OK] Verified backup retained: ${backup.backupAppPath}`);
+      emit(`[OK] Backup manifest retained: ${backup.manifestPath}`);
+      emit("[INFO] The verified clean staging bundle was installed with Foundation's atomic item replacement.");
+      if (installed.inspection.codeSign?.valid === true) {
+        emit("[OK] The restored source bundle's original signature verifies successfully.");
+      } else {
+        emit("[WARN] The restored bundle exactly matches its recorded local source, whose original signature does not currently verify; reinstall PM Studio if a vendor-valid signature is required.");
+      }
+      emit(`[INFO] Run ${commandName} pms setup to apply the split-origin patch again.`);
+      return {
+        status: "restored",
+        changed: true,
+        recipe: recipe.id,
+        backup,
+        inspection: installed.inspection,
+        replacementMode: "foundation-atomic-replace",
+        messages,
+      };
+    } finally {
+      if (!preserveStage && fs.existsSync(stagePath)) operations.removePath({ target: stagePath });
+    }
+  });
+}

package/src/pm-studio-status.mjs

@@ -8,6 +8,7 @@ import {
 import { PM_STUDIO_RECIPES } from "./pm-studio-asar.mjs";
 import {
   assertPatchedBinaryRecord,
+  createPmStudioStatusOperationOverrides,
   createPmStudioSetupOperations,
   DEFAULT_PM_STUDIO_APP_PATH,
   inspectPmStudioApp,
@@ -147,7 +148,10 @@ export async function inspectPmStudioStatus({
   readAdapterStatusFn = readAdapterStatus,
   probePmStudioRelayFn = probePmStudioRelay,
 } = {}) {
-  const operations = createPmStudioSetupOperations(operationOverrides);
+  const operations = createPmStudioSetupOperations({
+    ...createPmStudioStatusOperationOverrides(),
+    ...operationOverrides,
+  });
   let app;
   if (!existsSync(appPath)) {
     app = { state: "not_installed", metadata: null, issues: [] };

package/src/profile-model-runtime.mjs

@@ -1,6 +1,6 @@
 import {
   isValidModelList,
-  loadModelCache,
+  loadModelCacheEntry,
   saveModelCache,
 } from "./model-cache.mjs";
 import {
@@ -22,13 +22,48 @@ function parsedCatalog(result) {
   if (result?.status < 200 || result?.status >= 300) {
     throw new Error(`Copilot models returned HTTP ${result?.status}`);
   }
-  const models = JSON.parse(result.body);
+  let models;
+  try {
+    models = JSON.parse(result.body);
+  } catch {
+    throw new Error("Copilot models response was not valid JSON");
+  }
   if (!isValidModelList(models)) {
     throw new Error("Copilot models response contained no valid models");
   }
   return models;
 }
 
+function createModelRegistry() {
+  return {
+    modelDefs: undefined,
+    models: undefined,
+    source: "built-in",
+    cacheState: "none",
+    cacheSavedAtMs: null,
+    lastError: null,
+    lastErrorAtMs: null,
+    refreshInFlight: false,
+    generation: 0,
+  };
+}
+
+function sameModelDefs(left, right) {
+  if (left === right) return true;
+  if (!Array.isArray(left) || !Array.isArray(right)) return false;
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function safeRefreshError(error, { timedOut = false, timeoutMs } = {}) {
+  if (timedOut) return `Model refresh timed out after ${timeoutMs}ms`;
+  const raw = String(error?.message || error?.name || "Model refresh failed")
+    .replace(/[\u0000-\u001f\u007f]+/g, " ")
+    .replace(/\b(?:github_pat_|gh[pousr]_|copilot_)[A-Za-z0-9._-]+\b/gi, "<redacted>")
+    .replace(/\bBearer\s+\S+/gi, "Bearer <redacted>")
+    .trim();
+  return (raw || "Model refresh failed").slice(0, 240);
+}
+
 export function createProfileModelRuntime({
   codexClient,
   claudeClient = codexClient,
@@ -51,11 +86,13 @@ export function createProfileModelRuntime({
     throw new Error("Isolated Claude models require an isolated Claude client");
   }
 
-  const codexRegistry = { modelDefs: undefined, models: undefined, source: "built-in" };
+  const codexRegistry = createModelRegistry();
   const claudeRegistry = claudeMode === "inherited"
     ? codexRegistry
-    : { modelDefs: undefined, models: undefined, source: "built-in" };
+    : createModelRegistry();
   const customClaudeDefs = parseModelAliasEnv(env.CCDX_CLAUDE_MODEL_ALIASES);
+  const refreshFlights = new Map();
+  const refreshGenerations = new Map();
   const refreshTimeoutMs = Number.isFinite(timeoutMs) && timeoutMs > 0
     ? timeoutMs
     : DEFAULT_TIMEOUT_MS;
@@ -85,8 +122,9 @@ export function createProfileModelRuntime({
       ? customClaudeDefs.map((model) => ({ ...model }))
       : claudeDesktopModelDefsFromCopilotModels(models);
     if (discovered.length) {
+      const changed = !sameModelDefs(registry.modelDefs, discovered);
       registry.modelDefs = discovered;
-      notifyClaudeModels(discovered);
+      if (changed) notifyClaudeModels(discovered);
     }
     return registry.modelDefs;
   }
@@ -96,11 +134,13 @@ export function createProfileModelRuntime({
       ? String(claudeCredentialFingerprint || "").trim()
       : String(codexCredentialFingerprint || "").trim();
     if (profile === "claude" && !credentialFingerprint) return false;
-    const cached = loadModelCache({ home, profile, credentialFingerprint });
+    const cached = loadModelCacheEntry({ home, profile, credentialFingerprint });
     if (!cached) return false;
     try {
-      applyCatalog({ client, models: cached, registry, source: "cache", ownsClaudeModels });
-      return true;
+      applyCatalog({ client, models: cached.models, registry, source: "cache", ownsClaudeModels });
+      registry.cacheState = cached.state;
+      registry.cacheSavedAtMs = cached.savedAtMs;
+      return { loaded: true, stale: cached.state === "stale" };
     } catch {
       return false;
     }
@@ -131,13 +171,22 @@ export function createProfileModelRuntime({
     }
   }
 
-  function persist(models, profile) {
+  function persist(models, profile, registry, generation) {
     const credentialFingerprint = profile === "claude"
       ? String(claudeCredentialFingerprint || "").trim()
       : String(codexCredentialFingerprint || "").trim();
     if (profile === "claude" && !credentialFingerprint) return;
     try {
-      saveModelCache(models, { home, profile, credentialFingerprint });
+      const saved = saveModelCache(models, {
+        home,
+        profile,
+        credentialFingerprint,
+        isCurrent: () => refreshGenerations.get(profile) === generation,
+      });
+      if (saved) {
+        registry.cacheState = "fresh";
+        registry.cacheSavedAtMs = Date.now();
+      }
     } catch (error) {
       const label = profile === "codex" ? "Copilot" : "Claude Copilot";
       emit("warn", `Could not persist the ${label} model cache (${error.message})`);
@@ -162,12 +211,13 @@ export function createProfileModelRuntime({
     return profile === "claude" ? "built-in model list" : "no cached model list";
   }
 
-  async function refreshProfile({ client, profile, registry, ownsClaudeModels, checksCodex }) {
+  async function performRefresh({ client, profile, registry, ownsClaudeModels, checksCodex }, generation) {
     const controllerLabel = claudeMode === "inherited"
       ? ""
       : `${profile === "codex" ? "Codex" : "Claude"} `;
     try {
       const models = await requestCatalog(client);
+      if (refreshGenerations.get(profile) !== generation) return registry.modelDefs;
       if (checksCodex) checkCodexCatalog(models);
       const modelDefs = applyCatalog({
         client,
@@ -176,20 +226,44 @@ export function createProfileModelRuntime({
         source: "live",
         ownsClaudeModels,
       });
-      persist(models, profile);
+      persist(models, profile, registry, generation);
+      registry.lastError = null;
+      registry.lastErrorAtMs = null;
       if (ownsClaudeModels) logClaudeCatalog(modelDefs);
       return modelDefs;
     } catch (error) {
+      if (refreshGenerations.get(profile) !== generation) return registry.modelDefs;
       const fallback = fallbackLabel(registry, profile);
       const timedOut = error?.name === "AbortError" || error?.code === "ABORT_ERR";
+      const diagnostic = safeRefreshError(error, { timedOut, timeoutMs: refreshTimeoutMs });
+      registry.lastError = diagnostic;
+      registry.lastErrorAtMs = Date.now();
       const message = timedOut
         ? `${controllerLabel}model refresh timed out after ${refreshTimeoutMs}ms; using ${fallback}`
-        : `Could not refresh ${controllerLabel.toLowerCase()}model list; using ${fallback} (${error.message})`;
+        : `Could not refresh ${controllerLabel.toLowerCase()}model list; using ${fallback} (${diagnostic})`;
       emit("warn", message[0].toUpperCase() + message.slice(1));
       return registry.modelDefs;
     }
   }
 
+  function refreshProfile(options) {
+    const { profile, registry } = options;
+    const existing = refreshFlights.get(profile);
+    if (existing) return existing.promise;
+
+    const generation = (refreshGenerations.get(profile) || 0) + 1;
+    refreshGenerations.set(profile, generation);
+    registry.generation = generation;
+    registry.refreshInFlight = true;
+    const flight = { generation, promise: null };
+    refreshFlights.set(profile, flight);
+    flight.promise = performRefresh(options, generation).finally(() => {
+      if (refreshFlights.get(profile) === flight) refreshFlights.delete(profile);
+      if (refreshGenerations.get(profile) === generation) registry.refreshInFlight = false;
+    });
+    return flight.promise;
+  }
+
   function refreshCodex() {
     return refreshProfile({
       client: codexClient,