@bitkyc08/opencodex 2.7.40 → 2.7.41

package/src/claude/auth-detect.ts

@@ -0,0 +1,229 @@
+/**
+ * Claude auth presence detection.
+ *
+ * THREE values, not two. `unknown` means a source could not be READ (denied keychain,
+ * permission error, corrupt JSON) — treating that as `absent` would silently flip a
+ * subscriber into proxy mode, which is the failure this whole unit exists to prevent
+ * (devlog/_plan/260726_claude_auth_auto/001 F1). The resolver maps unknown to the
+ * historical default (subscription), never to proxy.
+ *
+ * IO is injectable so every source is testable without touching the real home
+ * directory, keychain, or environment.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+
+export type AuthPresence = "present" | "absent" | "unknown";
+
+export type AuthSourceId =
+  | "claude-json-oauth"        // S1: <config-dir>/../.claude.json oauthAccount
+  | "claude-credentials-file"  // S2: <config-dir>/.credentials.json
+  | "macos-keychain"           // S3: security find-generic-password (metadata only)
+  | "exported-env";            // S5: ANTHROPIC_API_KEY / a USER's ANTHROPIC_AUTH_TOKEN
+
+// NOTE: there is deliberately no "opencodex anthropic OAuth" source. That is a
+// PROVIDER credential in opencodex's own store which the Claude CLI never consumes,
+// so it is not evidence the client can authenticate natively (audit 002 §5).
+
+/**
+ * The one opencodex-owned dummy token. Exported so the CLI, the system-env writer and
+ * the tests all compare against the same literal — a second copy is how the marker
+ * feedback loop (002 §1) sneaks back in.
+ */
+export const PROXY_MARKER = "opencodex-proxy";
+
+const KEYCHAIN_SERVICE = "Claude Code-credentials";
+/** `security` exit code for "the item does not exist" — a real absent, not a failure. */
+const KEYCHAIN_ITEM_NOT_FOUND = 44;
+const KEYCHAIN_TIMEOUT_MS = 1_500;
+
+export interface AuthSourceResult {
+  source: AuthSourceId;
+  presence: AuthPresence;
+  /** One short, credential-free line. Never contains token material. */
+  detail?: string;
+}
+
+export interface AuthDetectDeps {
+  /** Parsed ~/.claude.json; undefined when missing; throws on corrupt/unreadable. */
+  readClaudeJson(): Record<string, unknown> | undefined;
+  /** Whether <config-dir>/.credentials.json exists; throws on read error. */
+  credentialsFileExists(): boolean;
+  /** present/absent/unknown for the macOS keychain probe; absent on non-Darwin. */
+  keychainProbe(): AuthPresence;
+  /**
+   * The environment to inspect for S5. Callers pass the SAME base env the launch will
+   * use, so detection and the spawned process can never disagree. Injection is typed
+   * to exclude this key (see `detectClaudeAuth` callers) so a test fake cannot
+   * silently replace the binding.
+   */
+  env(): NodeJS.ProcessEnv;
+  /**
+   * Token values opencodex itself put into the environment. `system-env.ts` exports the
+   * configured admission key as `ANTHROPIC_AUTH_TOKEN`, so without this the detector
+   * reads OUR OWN output back as proof the user can authenticate natively — the same
+   * feedback loop the `PROXY_MARKER` guard closes, one variable over.
+   */
+  ownTokens?: readonly string[];
+}
+
+export interface AuthDetectResult {
+  /** present if ANY source is present; unknown if none present but ANY unknown. */
+  presence: AuthPresence;
+  /** The source that proved presence, when any — feeds the GUI reason badge. */
+  foundBy?: AuthSourceId;
+  sources: AuthSourceResult[];
+  /**
+   * True when the inspected env carries OUR OWN dummy marker. It must never count as
+   * user auth, and a subscription resolution strips it before launch (002 §1).
+   */
+  staleProxyMarker: boolean;
+}
+
+/** Claude Code config dir: `CLAUDE_CONFIG_DIR` override, else `~/.claude`. */
+export function claudeConfigDir(env: NodeJS.ProcessEnv = process.env): string {
+  const explicit = env.CLAUDE_CONFIG_DIR?.trim();
+  return explicit ? explicit : join(homeDir(env), ".claude");
+}
+
+/**
+ * `os.homedir()` reads the OS user database and ignores a reassigned `HOME`, which
+ * makes an isolated-profile probe silently read the real user's files. Prefer the
+ * environment the caller handed us; fall back to the OS value.
+ */
+function homeDir(env: NodeJS.ProcessEnv): string {
+  const fromEnv = env.HOME?.trim() || env.USERPROFILE?.trim();
+  return fromEnv ? fromEnv : homedir();
+}
+
+function detectClaudeJson(deps: AuthDetectDeps): AuthSourceResult {
+  try {
+    const parsed = deps.readClaudeJson();
+    if (parsed === undefined) return { source: "claude-json-oauth", presence: "absent" };
+    const account = parsed.oauthAccount;
+    if (account && typeof account === "object" && !Array.isArray(account)) {
+      const email = (account as Record<string, unknown>).emailAddress;
+      if (typeof email === "string" && email.trim().length > 0) {
+        // Never echo the address itself — the detail line is UI copy, not a credential.
+        return { source: "claude-json-oauth", presence: "present", detail: "oauthAccount" };
+      }
+    }
+    return { source: "claude-json-oauth", presence: "absent" };
+  } catch {
+    // Corrupt or unreadable is NOT absent (F1).
+    return { source: "claude-json-oauth", presence: "unknown", detail: "unreadable" };
+  }
+}
+
+function detectCredentialsFile(deps: AuthDetectDeps): AuthSourceResult {
+  try {
+    return {
+      source: "claude-credentials-file",
+      presence: deps.credentialsFileExists() ? "present" : "absent",
+    };
+  } catch {
+    return { source: "claude-credentials-file", presence: "unknown", detail: "unreadable" };
+  }
+}
+
+function detectKeychain(deps: AuthDetectDeps): AuthSourceResult {
+  try {
+    return { source: "macos-keychain", presence: deps.keychainProbe() };
+  } catch {
+    return { source: "macos-keychain", presence: "unknown", detail: "probe failed" };
+  }
+}
+
+function detectExportedEnv(deps: AuthDetectDeps): AuthSourceResult {
+  try {
+    const env = deps.env();
+    const isOwn = (value: string): boolean =>
+      value === PROXY_MARKER || (deps.ownTokens ?? []).includes(value);
+    const apiKey = env.ANTHROPIC_API_KEY?.trim();
+    if (apiKey && !isOwn(apiKey)) {
+      return { source: "exported-env", presence: "present", detail: "ANTHROPIC_API_KEY" };
+    }
+    const token = env.ANTHROPIC_AUTH_TOKEN?.trim();
+    // Our own dummy is opencodex state, never user auth: counting it would make a
+    // proxy-mode launch look authenticated on the NEXT launch (002 §1). The configured
+    // admission key is opencodex state for exactly the same reason — the system-env
+    // writer exports it into this very variable.
+    if (token && !isOwn(token)) {
+      return { source: "exported-env", presence: "present", detail: "ANTHROPIC_AUTH_TOKEN" };
+    }
+    return { source: "exported-env", presence: "absent" };
+  } catch {
+    return { source: "exported-env", presence: "unknown" };
+  }
+}
+
+export function detectClaudeAuth(deps: AuthDetectDeps): AuthDetectResult {
+  const sources = [
+    detectClaudeJson(deps),
+    detectCredentialsFile(deps),
+    detectKeychain(deps),
+    detectExportedEnv(deps),
+  ];
+  let staleProxyMarker = false;
+  try {
+    staleProxyMarker = deps.env().ANTHROPIC_AUTH_TOKEN?.trim() === PROXY_MARKER;
+  } catch {
+    staleProxyMarker = false;
+  }
+
+  const present = sources.find(source => source.presence === "present");
+  if (present) return { presence: "present", foundBy: present.source, sources, staleProxyMarker };
+  if (sources.some(source => source.presence === "unknown")) {
+    return { presence: "unknown", sources, staleProxyMarker };
+  }
+  return { presence: "absent", sources, staleProxyMarker };
+}
+
+/**
+ * Real IO. The keychain probe is METADATA ONLY: no `-g` and no `-w`, because those
+ * flags print the password itself. We only need the exit code.
+ */
+export function defaultAuthDetectDeps(
+  env: NodeJS.ProcessEnv = process.env,
+  ownTokens: readonly string[] = [],
+): AuthDetectDeps {
+  const configDir = claudeConfigDir(env);
+  return {
+    readClaudeJson() {
+      // Sibling of the config dir when CLAUDE_CONFIG_DIR is set, else ~/.claude.json.
+      const path = env.CLAUDE_CONFIG_DIR?.trim()
+        ? join(configDir, "..", ".claude.json")
+        : join(homeDir(env), ".claude.json");
+      if (!existsSync(path)) return undefined;
+      // A parse failure propagates so the caller records `unknown`, not `absent`.
+      return JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
+    },
+    credentialsFileExists() {
+      return existsSync(join(configDir, ".credentials.json"));
+    },
+    keychainProbe() {
+      if (process.platform !== "darwin") return "absent";
+      const result = spawnSync("security", ["find-generic-password", "-s", KEYCHAIN_SERVICE], {
+        timeout: KEYCHAIN_TIMEOUT_MS,
+        stdio: ["ignore", "ignore", "ignore"],
+      });
+      if (result.error || result.signal !== null) return "unknown";
+      if (result.status === 0) return "present";
+      if (result.status === KEYCHAIN_ITEM_NOT_FOUND) return "absent";
+      return "unknown";
+    },
+    env: () => env,
+    ownTokens,
+  };
+}
+
+/**
+ * The token values opencodex itself exports. Configured admission keys land in
+ * `ANTHROPIC_AUTH_TOKEN` (see `system-env.ts`), so detection must not read them back
+ * as user auth.
+ */
+export function ownAdmissionTokens(config: { apiKeys?: Array<{ key: string }> }): string[] {
+  return (config.apiKeys ?? []).map(entry => entry.key).filter(key => key.length > 0);
+}

package/src/claude/auth-mode-migration.ts

@@ -0,0 +1,32 @@
+/**
+ * One-time authMode migration (devlog/_plan/260726_claude_auth_auto/015).
+ *
+ * Before auto existed, choosing "Subscription" in the GUI DELETED the key. So on disk
+ * an explicit subscription choice and "never chose anything" are byte-identical, and
+ * reading both as auto would flip a deliberate subscriber into proxy mode the moment
+ * their credentials are undetectable. This migration preserves the old EFFECTIVE
+ * behaviour for configs that already had a claudeCode block, and leaves genuinely
+ * untouched configs on auto.
+ */
+import type { OcxConfig } from "../types";
+
+/**
+ * @returns true when the config changed and the caller should persist it.
+ */
+export function runClaudeAuthModeMigration(config: OcxConfig, now = new Date()): boolean {
+  const claudeCode = config.claudeCode;
+  // No block at all = a fresh or Claude-untouched install: auto is the right default,
+  // and writing a sentinel here would create the block for no reason.
+  if (!claudeCode) return false;
+  // Idempotent: the sentinel's presence is the "already migrated" fact. A user who
+  // later picks Auto deletes authMode but KEEPS the sentinel, so the next start must
+  // not resurrect subscription.
+  if (typeof claudeCode.authModeMigratedAt === "string" && claudeCode.authModeMigratedAt.length > 0) {
+    return false;
+  }
+  if (claudeCode.authMode === undefined) {
+    claudeCode.authMode = "subscription";
+  }
+  claudeCode.authModeMigratedAt = now.toISOString();
+  return true;
+}

package/src/claude/auth-mode.ts

@@ -0,0 +1,62 @@
+/**
+ * Claude auth-mode resolution.
+ *
+ * The resolver answers exactly ONE question: does the opencodex-owned dummy token
+ * (`ANTHROPIC_AUTH_TOKEN=opencodex-proxy`) get injected? That is narrower than "how
+ * will Claude authenticate" — native passthrough additionally needs an `sk-ant-`
+ * credential on the incoming request — so the field is `markerMode`, not
+ * `effectiveAuthMode` (devlog/_plan/260726_claude_auth_auto/002 R2-1).
+ *
+ * The admission-key axis is separate and untouched: when the proxy requires an
+ * admission key, `buildClaudeEnv` injects it regardless of mode.
+ */
+import type { OcxConfig } from "../types";
+import type { AuthDetectResult, AuthSourceId } from "./auth-detect";
+
+export type MarkerMode = "proxy" | "subscription";
+
+export type AuthModeOrigin = "manual" | "auto-present" | "auto-absent" | "auto-unknown";
+
+export interface ResolvedAuthMode {
+  /** Does the owned dummy marker get injected. NOT a claim about native auth. */
+  markerMode: MarkerMode;
+  origin: AuthModeOrigin;
+  /** The detector source that proved presence (origin auto-present only). */
+  foundBy?: AuthSourceId;
+  detection: AuthDetectResult;
+}
+
+/**
+ * Reads `authMode`; never writes it. An explicit "proxy"/"subscription" bypasses the
+ * detector forever, which is what makes a manual choice stick across auth changes.
+ *
+ * `unknown` resolves to subscription — the historical default — because flipping a
+ * subscriber into proxy mode on a failed read (denied keychain, unreadable file) is
+ * the worst outcome this feature can produce.
+ */
+export function resolveClaudeAuthMode(config: OcxConfig, detection: AuthDetectResult): ResolvedAuthMode {
+  const authMode = config.claudeCode?.authMode;
+  if (authMode === "proxy") return { markerMode: "proxy", origin: "manual", detection };
+  if (authMode === "subscription") return { markerMode: "subscription", origin: "manual", detection };
+
+  switch (detection.presence) {
+    case "present":
+      return {
+        markerMode: "subscription",
+        origin: "auto-present",
+        ...(detection.foundBy ? { foundBy: detection.foundBy } : {}),
+        detection,
+      };
+    case "absent":
+      return { markerMode: "proxy", origin: "auto-absent", detection };
+    default:
+      return { markerMode: "subscription", origin: "auto-unknown", detection };
+  }
+}
+
+/** The three-state intent as the API and GUI express it. */
+export type AuthModeIntent = "auto" | "proxy" | "subscription";
+
+export function authModeIntent(config: OcxConfig): AuthModeIntent {
+  return config.claudeCode?.authMode ?? "auto";
+}

package/src/claude/desktop-3p-guard.ts

@@ -0,0 +1,35 @@
+/**
+ * Write-path validation for the Desktop 3P model list.
+ *
+ * The request path has its own guards (anthropic-image-guard.ts); this is the
+ * config-output counterpart. A bad entry here ships inside a user-visible config file,
+ * so it fails LOUD at the write boundary rather than silently producing a config
+ * Desktop rejects or mislabels.
+ */
+import type { Desktop3pModelEntry } from "./desktop-3p";
+
+const NAME_PATTERN = /^claude-[a-z0-9-]+$/;
+const MAX_LABEL_CHARS = 80;
+/** Bracket capability markers must already have been normalized away by displayModelId. */
+const FORBIDDEN_LABEL_CHARS = /[[\]]/;
+
+export function assertDesktop3pModelsValid(models: readonly Desktop3pModelEntry[]): void {
+  const seen = new Set<string>();
+  for (const model of models) {
+    if (!NAME_PATTERN.test(model.name)) {
+      throw new Error(`Desktop 3P model name is not a valid Claude-shaped id: ${model.name}`);
+    }
+    // Alias collisions are skipped upstream; if that skip ever regresses, a duplicate
+    // must fail here instead of writing a config Desktop cannot decode.
+    if (seen.has(model.name)) {
+      throw new Error(`Desktop 3P model name duplicated: ${model.name}`);
+    }
+    seen.add(model.name);
+    if (FORBIDDEN_LABEL_CHARS.test(model.labelOverride)) {
+      throw new Error(`Desktop 3P label carries a raw capability marker: ${model.labelOverride}`);
+    }
+    if (model.labelOverride.length > MAX_LABEL_CHARS) {
+      throw new Error(`Desktop 3P label exceeds ${MAX_LABEL_CHARS} chars: ${model.labelOverride}`);
+    }
+  }
+}

package/src/claude/desktop-3p.ts

@@ -1,18 +1,29 @@
 import { createHash, randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { atomicWriteFile } from "../config";
+import type { OcxClaudeDesktopProfile } from "../types";
+import {
+  reconcileDesktopProfile,
+  renderDesktopProfile,
+  type DesktopProfileModel,
+} from "./desktop-profile";
+import { nativeOpenAiContextWindow } from "../codex/catalog";
+import { assertDesktop3pModelsValid } from "./desktop-3p-guard";
 
 export interface Desktop3pModelEntry {
   name: string;
   labelOverride: string;
-  anthropicFamilyTier: "opus";
+  anthropicFamilyTier: "opus" | "fable" | "sonnet" | "haiku";
   isFamilyDefault?: boolean;
   /**
    * Desktop's documented 1M-context capability assertion. Set ONLY from an
    * authoritative routed contextWindow >= 1M — never guessed (devlog 136 B5).
    */
   supports1m?: true;
+  /** When true, Desktop selects the 1M variant by default (official schema, Luna research 260722). */
+  prefer1m?: true;
 }
 
 /**
@@ -30,7 +41,13 @@ export interface Desktop3pRoutedModel {
   contextWindow?: number;
 }
 
-const SUPPORTS_1M_THRESHOLD = 1_000_000;
+/**
+ * 1M-context eligibility, shared with the Desktop DTO so the dashboard's 1M chip can
+ * never disagree with what the writer emits. The DTO imports this from here — keeping
+ * the constant in this module avoids a cycle, since shared.ts already reads
+ * claude/desktop-profile.
+ */
+export const DESKTOP_SUPPORTS_1M_THRESHOLD = 1_000_000;
 
 /** CLI arg parsing for `ocx claude desktop` mode flags (mutually exclusive). */
 export function parseDesktop3pModeArgs(flags: string[]): { mode: Desktop3pConfigMode } | { error: string } {
@@ -59,6 +76,7 @@ interface Desktop3pMetadata {
 }
 
 let desktop3pRegistry = new Map<string, string>();
+let desktop3pAliasesByRoute = new Map<string, string>();
 
 /** Derive a stable letter-first, three-character base36 code from a route key. */
 export function deriveDesktop3pCode(route: string): string {
@@ -89,11 +107,14 @@ export function legacyDesktop3pAlias(provider: string, modelId: string): string
 
 function displayModelId(modelId: string): string {
   return modelId
+    // Capability markers like [1m] are not name text: strip the brackets so the label
+    // reads "K3 1M", never "K3[1m]".
+    .replace(/\[([^\]]+)\]/g, "-$1")
     .split(/[-_]+/)
     .filter(Boolean)
     .map(part => {
       const lower = part.toLowerCase();
-      if (lower === "gpt" || lower === "glm" || lower === "ai") return lower.toUpperCase();
+      if (lower === "gpt" || lower === "glm" || lower === "ai" || lower === "1m") return lower.toUpperCase();
       return part.charAt(0).toUpperCase() + part.slice(1);
     })
     .join(" ");
@@ -102,18 +123,64 @@ function displayModelId(modelId: string): string {
 function collectDesktop3pModels(
   nativeSlugs: string[],
   routedModels: Array<Desktop3pRoutedModel>,
+  profile?: OcxClaudeDesktopProfile,
 ): { models: Desktop3pModelEntry[]; registry: Map<string, string> } {
   const registry = new Map<string, string>();
   const models: Desktop3pModelEntry[] = [];
   const candidates: Desktop3pRoutedModel[] = [
-    ...nativeSlugs.map(id => ({ provider: "native", id })),
+    // Native candidates carry their real context window from the same accessor the
+    // Desktop DTO uses, so a native 1M/372k model resolves identically in the written
+    // config and on the dashboard.
+    ...nativeSlugs.map(id => {
+      const contextWindow = nativeOpenAiContextWindow(id);
+      return { provider: "native", id, ...(contextWindow !== undefined ? { contextWindow } : {}) };
+    }),
     ...routedModels,
   ];
 
+  if (profile) {
+    const profileModels = candidates.map(({ provider, id, contextWindow }) => ({
+      route: `${provider}/${id}`,
+      label: `${displayModelId(id)} (${provider})`,
+      ...(typeof contextWindow === "number" ? { contextWindow } : {}),
+    } satisfies DesktopProfileModel));
+    const reconciled = reconcileDesktopProfile(profile, profileModels);
+    const rendered = renderDesktopProfile(reconciled, profileModels);
+    const aliasesByRoute = new Map<string, string>();
+    for (const model of rendered) {
+      aliasesByRoute.set(model.route, model.name);
+      if (!model.route.startsWith("anthropic/claude-")) registry.set(model.name, model.route);
+      models.push({
+        name: model.name,
+        labelOverride: model.label,
+        anthropicFamilyTier: model.family,
+        ...(model.isFamilyDefault ? { isFamilyDefault: true } : {}),
+        ...(model.supports1m ? { supports1m: true, prefer1m: true } : {}),
+      });
+    }
+    // Legacy hashes are compatibility-only and can collide. Bind them in stable route order so
+    // changing a family default or rendered ordering can never silently rebind an old Desktop id.
+    for (const model of [...rendered].sort((a, b) => a.route.localeCompare(b.route))) {
+      if (model.route.startsWith("anthropic/claude-")) continue;
+      const providerEnd = model.route.indexOf("/");
+      const provider = model.route.slice(0, providerEnd);
+      const id = model.route.slice(providerEnd + 1);
+      const legacy = legacyDesktop3pAlias(provider, id);
+      const existing = registry.get(legacy);
+      if (existing && existing !== model.route) {
+        console.warn(`[opencodex] Claude Desktop legacy alias collision: ${legacy} stays bound to ${existing}; ignoring ${model.route}`);
+        continue;
+      }
+      registry.set(legacy, model.route);
+    }
+    desktop3pAliasesByRoute = aliasesByRoute;
+    return { models, registry };
+  }
+
   for (const { provider, id, contextWindow } of candidates) {
     const route = `${provider}/${id}`;
     const alias = desktop3pAlias(provider, id);
-    const supports1m = typeof contextWindow === "number" && contextWindow >= SUPPORTS_1M_THRESHOLD
+    const supports1m = typeof contextWindow === "number" && contextWindow >= DESKTOP_SUPPORTS_1M_THRESHOLD
       ? { supports1m: true as const }
       : {};
     if (alias === id) {
@@ -125,6 +192,7 @@ function collectDesktop3pModels(
         labelOverride: `${displayModelId(id)} (${provider})`,
         anthropicFamilyTier: "opus",
         ...supports1m,
+      ...(supports1m.supports1m ? { prefer1m: true as const } : {}),
       });
       continue;
     }
@@ -143,10 +211,12 @@ function collectDesktop3pModels(
       labelOverride: `${displayModelId(id)} (${provider})`,
       anthropicFamilyTier: "opus",
       ...supports1m,
+      ...(supports1m.supports1m ? { prefer1m: true as const } : {}),
     });
   }
 
   if (models[0]) models[0].isFamilyDefault = true;
+  desktop3pAliasesByRoute = new Map(candidates.map(({ provider, id }) => [`${provider}/${id}`, desktop3pAlias(provider, id)]));
   return { models, registry };
 }
 
@@ -154,8 +224,9 @@ function collectDesktop3pModels(
 export function buildDesktop3pRegistry(
   nativeSlugs: string[],
   routedModels: Array<Desktop3pRoutedModel>,
+  profile?: OcxClaudeDesktopProfile,
 ): Map<string, string> {
-  const { registry } = collectDesktop3pModels(nativeSlugs, routedModels);
+  const { registry } = collectDesktop3pModels(nativeSlugs, routedModels, profile);
   desktop3pRegistry = registry;
   return registry;
 }
@@ -164,8 +235,9 @@ export function buildDesktop3pRegistry(
 export function generateDesktop3pModels(
   nativeSlugs: string[],
   routedModels: Array<Desktop3pRoutedModel>,
+  profile?: OcxClaudeDesktopProfile,
 ): Desktop3pModelEntry[] {
-  const { models, registry } = collectDesktop3pModels(nativeSlugs, routedModels);
+  const { models, registry } = collectDesktop3pModels(nativeSlugs, routedModels, profile);
   desktop3pRegistry = registry;
   return models;
 }
@@ -175,6 +247,11 @@ export function resolveDesktop3pAlias(alias: string): string | null {
   return desktop3pRegistry.get(alias) ?? null;
 }
 
+/** Alias selected by the installed profile registry, falling back to the legacy hash shape. */
+export function activeDesktop3pAlias(provider: string, modelId: string): string {
+  return desktop3pAliasesByRoute.get(`${provider}/${modelId}`) ?? desktop3pAlias(provider, modelId);
+}
+
 /**
  * Generate the complete Claude Desktop 3P gateway config.
  *
@@ -189,6 +266,7 @@ export function generateDesktop3pConfig(
   routedModels: Array<Desktop3pRoutedModel>,
   apiKey = "ocx",
   mode: Desktop3pConfigMode = "static",
+  profile?: OcxClaudeDesktopProfile,
 ): object {
   const base = {
     inferenceProvider: "gateway",
@@ -198,13 +276,19 @@ export function generateDesktop3pConfig(
   };
   if (mode === "discovery") {
     // Build/refresh the decode registry even though no static list is emitted.
-    buildDesktop3pRegistry(nativeSlugs, routedModels);
+    buildDesktop3pRegistry(nativeSlugs, routedModels, profile);
     return { ...base, modelDiscoveryEnabled: true };
   }
   return {
     ...base,
     modelDiscoveryEnabled: mode === "hybrid",
-    inferenceModels: generateDesktop3pModels(nativeSlugs, routedModels),
+    inferenceModels: (() => {
+      const models = generateDesktop3pModels(nativeSlugs, routedModels, profile);
+      // Fail loud at the write boundary rather than ship a config Desktop rejects:
+      // the output counterpart of the request-path guards.
+      assertDesktop3pModelsValid(models);
+      return models;
+    })(),
   };
 }
 
@@ -222,8 +306,10 @@ export function writeDesktop3pConfig(
   routedModels: Array<Desktop3pRoutedModel>,
   apiKey?: string,
   mode: Desktop3pConfigMode = "static",
-): { written: boolean; path: string; reason?: string } {
-  const libraryPath = join(homedir(), "Library", "Application Support", "Claude-3p", "configLibrary");
+  profile?: OcxClaudeDesktopProfile,
+): { written: boolean; path: string; reason?: string; fingerprint?: string } {
+  const libraryPath = process.env.OPENCODEX_CLAUDE_DESKTOP_CONFIG_DIR?.trim()
+    || join(homedir(), "Library", "Application Support", "Claude-3p", "configLibrary");
   const metadataPath = join(libraryPath, "_meta.json");
   let configPath = libraryPath;
 
@@ -238,17 +324,31 @@ export function writeDesktop3pConfig(
       ? metadata.entries.map(current => current === existing ? entry : current)
       : [...metadata.entries, entry];
 
-    writeFileSync(configPath, JSON.stringify(generateDesktop3pConfig(port, nativeSlugs, routedModels, apiKey, mode), null, 2) + "\n", {
-      encoding: "utf8",
-      mode: 0o600,
-    });
-    writeFileSync(metadataPath, JSON.stringify({ ...metadata, appliedId: id, entries }, null, 2) + "\n", {
-      encoding: "utf8",
-      mode: 0o600,
-    });
-    return { written: true, path: configPath };
+    const configJson = JSON.stringify(generateDesktop3pConfig(port, nativeSlugs, routedModels, apiKey, mode, profile), null, 2) + "\n";
+    const fingerprint = createHash("sha256").update(configJson).digest("hex").slice(0, 16);
+    const { backupPath } = atomicReplaceDesktopConfig(configPath, configJson);
+    try {
+      atomicWriteFile(metadataPath, JSON.stringify({ ...metadata, appliedId: id, entries }, null, 2) + "\n");
+    } catch (metaError) {
+      // Rollback: restore the backed-up config if metadata write fails.
+      if (backupPath && existsSync(backupPath)) copyFileSync(backupPath, configPath);
+      throw metaError;
+    }
+    return { written: true, path: configPath, fingerprint };
   } catch (error) {
     const reason = error instanceof Error ? error.message : String(error);
     return { written: false, path: configPath, reason };
   }
 }
+
+/** Backup an existing owned config then atomically replace it. Exported for failure-path tests. */
+export function atomicReplaceDesktopConfig(
+  path: string,
+  content: string,
+  writer: (path: string, content: string) => void = atomicWriteFile,
+): { backupPath?: string } {
+  const backupPath = `${path}.bak`;
+  if (existsSync(path)) copyFileSync(path, backupPath);
+  writer(path, content);
+  return existsSync(backupPath) ? { backupPath } : {};
+}

package/src/claude/desktop-health.ts

@@ -0,0 +1,26 @@
+/** In-memory Desktop health tracker (resets on server restart). */
+
+interface DesktopHealthState {
+  lastRequestAt: number | null;
+  requestCount: number;
+  errorCount: number;
+}
+
+const state: DesktopHealthState = { lastRequestAt: null, requestCount: 0, errorCount: 0 };
+
+export function recordDesktopRequest(): void {
+  state.lastRequestAt = Date.now();
+  state.requestCount++;
+}
+
+export function recordDesktopError(): void {
+  state.errorCount++;
+}
+
+export function getDesktopHealth(): { lastRequestAt: string | null; requestCount: number; errorCount: number } {
+  return {
+    lastRequestAt: state.lastRequestAt !== null ? new Date(state.lastRequestAt).toISOString() : null,
+    requestCount: state.requestCount,
+    errorCount: state.errorCount,
+  };
+}