@iislee/opencodex 2.11.0

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

@@ -0,0 +1,381 @@
+import { createHash, randomUUID } from "node:crypto";
+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 { claudeDesktopConfigLibraryDir, resolveConfigLibraryDir } from "./desktop-3p-paths";
+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" | "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;
+}
+
+/**
+ * static (default, Pro-verified devlog 138): pinned inferenceModels with
+ * modelDiscoveryEnabled:false — a static list OVERRIDES discovery (no merge), so
+ * this is the deterministic shape. hybrid keeps discovery:true alongside the list
+ * (claude-code-router's version-defensive pattern). discovery: /v1/models only.
+ */
+export type Desktop3pConfigMode = "hybrid" | "discovery" | "static";
+
+export interface Desktop3pRoutedModel {
+  provider: string;
+  id: string;
+  /** Authoritative context window (CatalogModel.contextWindow); optional. */
+  contextWindow?: number;
+}
+
+/**
+ * 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;
+
+export interface Desktop3pConfigLibraryOptions {
+  env?: NodeJS.ProcessEnv;
+  platform?: NodeJS.Platform;
+  homeDir?: string;
+}
+
+/**
+ * Resolve the config library from the same user-data root Claude Desktop uses. Keeping this in one
+ * helper prevents the writer and dashboard status probe from agreeing on a path Desktop never reads.
+ *
+ * The resolution itself lives in `./desktop-3p-paths`, which ports Claude Desktop's own `GE()`
+ * branch for branch — including the `-3p` suffix the app appends to its userData root. Dropping
+ * that suffix points us at a directory Desktop never reads (GitHub #539).
+ */
+export function resolveDesktop3pConfigLibraryPath(
+  options: Desktop3pConfigLibraryOptions = {},
+): string {
+  if (options.env === undefined && options.platform === undefined && options.homeDir === undefined) {
+    return claudeDesktopConfigLibraryDir();
+  }
+  return resolveConfigLibraryDir({
+    env: options.env ?? process.env,
+    platform: options.platform ?? process.platform,
+    home: options.homeDir ?? homedir(),
+  });
+}
+
+/** CLI arg parsing for `ocx claude desktop` mode flags (mutually exclusive). */
+export function parseDesktop3pModeArgs(flags: string[]): { mode: Desktop3pConfigMode } | { error: string } {
+  const known = new Map<string, Desktop3pConfigMode>([
+    ["--static", "static"],
+    ["--hybrid", "hybrid"],
+    ["--discovery-only", "discovery"],
+  ]);
+  const unknown = flags.filter(a => !known.has(a));
+  if (unknown.length > 0) return { error: `알 수 없는 옵션: ${unknown.join(" ")} (지원: --static, --hybrid, --discovery-only)` };
+  const picked = [...new Set(flags.map(a => known.get(a)!))];
+  if (picked.length > 1) return { error: "모드 옵션은 하나만 쓸 수 있습니다 (--static | --hybrid | --discovery-only)." };
+  return { mode: picked[0] ?? "static" };
+}
+
+interface Desktop3pMetadataEntry {
+  id: string;
+  name: string;
+  [key: string]: unknown;
+}
+
+interface Desktop3pMetadata {
+  appliedId?: string;
+  entries: Desktop3pMetadataEntry[];
+  [key: string]: unknown;
+}
+
+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 {
+  const hash = createHash("sha256").update(route).digest();
+  const n = hash.readUInt32BE(0) % 33696;
+  const first = String.fromCharCode(97 + Math.floor(n / 1296));
+  const rest = (n % 1296).toString(36).padStart(2, "0");
+  return first + rest;
+}
+
+/**
+ * Alias for one proxy model. Real Anthropic models pass through unchanged (they must
+ * keep hitting the sk-ant native passthrough); everything else gets a Claude-shaped
+ * `claude-opus-4-8-{code}` id. Opus 4.8 is chosen deliberately: Desktop's effort
+ * selector is an allowlist keyed on exact supported model ids (Opus 4.8/4.7/4.6,
+ * Sonnet 4.6 — devlog 131), and 4.6+ canonical ids are dateless, so the letter-first
+ * 3-char suffix can never collide with a real id or a legacy date suffix.
+ */
+export function desktop3pAlias(provider: string, modelId: string): string {
+  if (provider === "anthropic" && modelId.startsWith("claude-")) return modelId;
+  return `claude-opus-4-8-${deriveDesktop3pCode(`${provider}/${modelId}`)}`;
+}
+
+/** Pre-rename alias shape (claude-opus-4-{code}) — still decoded for stale Desktop configs. */
+export function legacyDesktop3pAlias(provider: string, modelId: string): string {
+  return `claude-opus-4-${deriveDesktop3pCode(`${provider}/${modelId}`)}`;
+}
+
+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" || lower === "1m") return lower.toUpperCase();
+      return part.charAt(0).toUpperCase() + part.slice(1);
+    })
+    .join(" ");
+}
+
+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[] = [
+    // 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 >= DESKTOP_SUPPORTS_1M_THRESHOLD
+      ? { supports1m: true as const }
+      : {};
+    if (alias === id) {
+      // Real Anthropic model: keep it OUT of the decode registry — registering it would
+      // make resolveInboundModel() non-identity and kill the sk-ant native passthrough
+      // (audit 133 #1). It still appears in the static Desktop model list below.
+      models.push({
+        name: alias,
+        labelOverride: `${displayModelId(id)} (${provider})`,
+        anthropicFamilyTier: "opus",
+        ...supports1m,
+      ...(supports1m.supports1m ? { prefer1m: true as const } : {}),
+      });
+      continue;
+    }
+    const existingRoute = registry.get(alias);
+    if (existingRoute !== undefined) {
+      console.warn(`[opencodex] Claude Desktop 3P alias collision: ${alias} maps to both ${existingRoute} and ${route}; skipping ${route}`);
+      continue;
+    }
+
+    registry.set(alias, route);
+    // Back-compat decode for Desktop configs written before the opus-4-8 rename.
+    const legacy = legacyDesktop3pAlias(provider, id);
+    if (!registry.has(legacy)) registry.set(legacy, route);
+    models.push({
+      name: alias,
+      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 };
+}
+
+/** Build and install the registry used to decode Desktop aliases. */
+export function buildDesktop3pRegistry(
+  nativeSlugs: string[],
+  routedModels: Array<Desktop3pRoutedModel>,
+  profile?: OcxClaudeDesktopProfile,
+): Map<string, string> {
+  const { registry } = collectDesktop3pModels(nativeSlugs, routedModels, profile);
+  desktop3pRegistry = registry;
+  return registry;
+}
+
+/** Generate Claude Desktop 3P model entries from the proxy's available models. */
+export function generateDesktop3pModels(
+  nativeSlugs: string[],
+  routedModels: Array<Desktop3pRoutedModel>,
+  profile?: OcxClaudeDesktopProfile,
+): Desktop3pModelEntry[] {
+  const { models, registry } = collectDesktop3pModels(nativeSlugs, routedModels, profile);
+  desktop3pRegistry = registry;
+  return models;
+}
+
+/** Resolve an alias using the most recently generated Desktop model registry. */
+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.
+ *
+ * Default mode is "static" (Pro-verified, devlog 138): the static list is the ONLY
+ * channel for supports1m/tier pins and it overrides discovery anyway (no merge), so
+ * discovery stays off for determinism. supports1m makes Desktop offer a separate 1M
+ * row; selecting it sends the bare id + `anthropic-beta: context-1m-2025-08-07`.
+ */
+export function generateDesktop3pConfig(
+  port: number,
+  nativeSlugs: string[],
+  routedModels: Array<Desktop3pRoutedModel>,
+  apiKey = "ocx",
+  mode: Desktop3pConfigMode = "static",
+  profile?: OcxClaudeDesktopProfile,
+): object {
+  const base = {
+    inferenceProvider: "gateway",
+    inferenceCredentialKind: "static",
+    inferenceGatewayBaseUrl: `http://127.0.0.1:${port}`,
+    inferenceGatewayApiKey: apiKey,
+  };
+  if (mode === "discovery") {
+    // Build/refresh the decode registry even though no static list is emitted.
+    buildDesktop3pRegistry(nativeSlugs, routedModels, profile);
+    return { ...base, modelDiscoveryEnabled: true };
+  }
+  return {
+    ...base,
+    modelDiscoveryEnabled: mode === "hybrid",
+    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;
+    })(),
+  };
+}
+
+function parseMetadata(path: string): Desktop3pMetadata {
+  if (!existsSync(path)) return { entries: [] };
+  const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<Desktop3pMetadata>;
+  if (!Array.isArray(parsed.entries)) throw new Error("Claude Desktop 3P _meta.json has no entries array");
+  return { ...parsed, entries: parsed.entries };
+}
+
+/** Write and apply the opencodex config in Claude Desktop 3P's config library. */
+export function writeDesktop3pConfig(
+  port: number,
+  nativeSlugs: string[],
+  routedModels: Array<Desktop3pRoutedModel>,
+  apiKey?: string,
+  mode: Desktop3pConfigMode = "static",
+  profile?: OcxClaudeDesktopProfile,
+): { written: boolean; path: string; reason?: string; fingerprint?: string } {
+  const libraryPath = resolveDesktop3pConfigLibraryPath();
+  const metadataPath = join(libraryPath, "_meta.json");
+  let configPath = libraryPath;
+
+  try {
+    mkdirSync(libraryPath, { recursive: true, mode: 0o700 });
+    const metadata = parseMetadata(metadataPath);
+    const existing = metadata.entries.find(entry => entry?.name === "opencodex" && typeof entry.id === "string");
+    const id = existing?.id ?? randomUUID();
+    configPath = join(libraryPath, `${id}.json`);
+    const entry: Desktop3pMetadataEntry = existing ? { ...existing, id, name: "opencodex" } : { id, name: "opencodex" };
+    const entries = existing
+      ? metadata.entries.map(current => current === existing ? entry : current)
+      : [...metadata.entries, entry];
+
+    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,
+  };
+}

package/src/claude/desktop-profile.ts

@@ -0,0 +1,263 @@
+import { createHash } from "node:crypto";
+import type {
+  OcxClaudeDesktopAssignment,
+  OcxClaudeDesktopFamily,
+  OcxClaudeDesktopProfile,
+} from "../types";
+
+export const DESKTOP_FAMILIES = ["opus", "fable", "sonnet", "haiku"] as const;
+export type DesktopFamily = OcxClaudeDesktopFamily;
+export type DesktopProfile = OcxClaudeDesktopProfile;
+
+export interface DesktopProfileModel {
+  route: string;
+  label: string;
+  contextWindow?: number;
+}
+
+export interface RenderedDesktopModel extends DesktopProfileModel {
+  name: string;
+  family: DesktopFamily;
+  isFamilyDefault: boolean;
+  supports1m: boolean;
+}
+
+const DATE_ALIAS = /^claude-opus-4-8-(2026\d{4})$/;
+const DAY_COUNT_2026 = 365;
+
+export class DesktopProfileError extends Error {
+  constructor(message: string, readonly path = "profile") {
+    super(`${path}: ${message}`);
+    this.name = "DesktopProfileError";
+  }
+}
+
+export function emptyDesktopProfile(): DesktopProfile {
+  return {
+    version: 1,
+    assignments: {},
+    defaults: { opus: null, fable: null, sonnet: null, haiku: null },
+  };
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function assertExactKeys(value: Record<string, unknown>, keys: readonly string[], path: string): void {
+  const allowed = new Set(keys);
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) throw new DesktopProfileError(`unknown field "${key}"`, path);
+  }
+}
+
+/**
+ * Applied-state markers survive every profile rebuild.
+ *
+ * `parseDesktopProfile`, `reconcileDesktopProfile` and `moveDesktopRoute` each construct a
+ * fresh `{ version, assignments, defaults }`, and the management routes persist whatever they
+ * return. Without this carry-through, saving an assignment — or merely dragging a model to
+ * another family — would erase the fingerprint the apply route wrote, and the GUI would report
+ * "not applied" for a config that is applied on disk.
+ */
+function appliedMarkers(source: { appliedFingerprint?: unknown; appliedAt?: unknown }): {
+  appliedFingerprint?: string;
+  appliedAt?: string;
+} {
+  return {
+    ...(typeof source.appliedFingerprint === "string" ? { appliedFingerprint: source.appliedFingerprint } : {}),
+    ...(typeof source.appliedAt === "string" ? { appliedAt: source.appliedAt } : {}),
+  };
+}
+
+function isFamily(value: unknown): value is DesktopFamily {
+  return typeof value === "string" && (DESKTOP_FAMILIES as readonly string[]).includes(value);
+}
+
+function routeModelId(route: string): string {
+  const slash = route.indexOf("/");
+  return slash >= 0 ? route.slice(slash + 1) : route;
+}
+
+function isRealAnthropicRoute(route: string): boolean {
+  return route.startsWith("anthropic/claude-");
+}
+
+function validDateAlias(alias: string): boolean {
+  const match = DATE_ALIAS.exec(alias);
+  if (!match) return false;
+  const year = Number(match[1]!.slice(0, 4));
+  const month = Number(match[1]!.slice(4, 6));
+  const day = Number(match[1]!.slice(6, 8));
+  const date = new Date(Date.UTC(year, month - 1, day));
+  return date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day;
+}
+
+export function parseDesktopProfile(value: unknown): DesktopProfile {
+  if (!isPlainObject(value)) throw new DesktopProfileError("must be an object");
+  // `appliedFingerprint`/`appliedAt` are written back by the apply route once a profile
+  // reaches Claude Desktop (see server/management/agent-settings-routes.ts). Rejecting them
+  // here made every reload after the first apply fail with `unknown field`.
+  assertExactKeys(value, ["version", "assignments", "defaults", "appliedFingerprint", "appliedAt"], "profile");
+  if (value.version !== 1) throw new DesktopProfileError("version must be 1", "profile.version");
+  if (!isPlainObject(value.assignments)) throw new DesktopProfileError("must be an object", "profile.assignments");
+  if (!isPlainObject(value.defaults)) throw new DesktopProfileError("must be an object", "profile.defaults");
+  assertExactKeys(value.defaults, DESKTOP_FAMILIES, "profile.defaults");
+  if (value.appliedFingerprint !== undefined && typeof value.appliedFingerprint !== "string") {
+    throw new DesktopProfileError("must be a string", "profile.appliedFingerprint");
+  }
+  if (value.appliedAt !== undefined && typeof value.appliedAt !== "string") {
+    throw new DesktopProfileError("must be a string", "profile.appliedAt");
+  }
+
+  const assignments: Record<string, OcxClaudeDesktopAssignment> = {};
+  const aliases = new Set<string>();
+  for (const [route, raw] of Object.entries(value.assignments)) {
+    if (!route.trim() || !route.includes("/")) throw new DesktopProfileError("route must be provider/model", `profile.assignments.${route || "<empty>"}`);
+    if (!isPlainObject(raw)) throw new DesktopProfileError("must be an object", `profile.assignments.${route}`);
+    assertExactKeys(raw, ["family", "alias"], `profile.assignments.${route}`);
+    if (!isFamily(raw.family)) throw new DesktopProfileError("unknown family", `profile.assignments.${route}.family`);
+    if (typeof raw.alias !== "string" || !raw.alias) throw new DesktopProfileError("must be a non-empty string", `profile.assignments.${route}.alias`);
+    if (isRealAnthropicRoute(route)) {
+      if (raw.alias !== routeModelId(route)) throw new DesktopProfileError("real Anthropic routes must keep their exact model id", `profile.assignments.${route}.alias`);
+    } else if (!validDateAlias(raw.alias)) {
+      throw new DesktopProfileError("must be a valid claude-opus-4-8-2026MMDD alias", `profile.assignments.${route}.alias`);
+    }
+    if (aliases.has(raw.alias)) throw new DesktopProfileError(`duplicate alias "${raw.alias}"`, `profile.assignments.${route}.alias`);
+    aliases.add(raw.alias);
+    assignments[route] = { family: raw.family, alias: raw.alias };
+  }
+
+  const defaults = {} as DesktopProfile["defaults"];
+  for (const family of DESKTOP_FAMILIES) {
+    const route = value.defaults[family];
+    if (route !== null && typeof route !== "string") throw new DesktopProfileError("must be a route or null", `profile.defaults.${family}`);
+    const members = Object.keys(assignments).filter(key => assignments[key]!.family === family).sort();
+    if (members.length === 0) {
+      if (route !== null) throw new DesktopProfileError("must be null for an empty family", `profile.defaults.${family}`);
+      defaults[family] = null;
+      continue;
+    }
+    if (typeof route !== "string" || !assignments[route] || assignments[route]!.family !== family) {
+      throw new DesktopProfileError("must reference a member of this family", `profile.defaults.${family}`);
+    }
+    defaults[family] = route;
+  }
+  return { version: 1, assignments, defaults, ...appliedMarkers(value) };
+}
+
+function dayOfYearAlias(dayIndex: number): string {
+  const date = new Date(Date.UTC(2026, 0, dayIndex + 1));
+  const y = date.getUTCFullYear();
+  const m = String(date.getUTCMonth() + 1).padStart(2, "0");
+  const d = String(date.getUTCDate()).padStart(2, "0");
+  return `claude-opus-4-8-${y}${m}${d}`;
+}
+
+function routeStartDay(route: string): number {
+  return createHash("sha256").update(route).digest().readUInt32BE(0) % DAY_COUNT_2026;
+}
+
+function allocateAlias(route: string, used: Set<string>): string {
+  if (isRealAnthropicRoute(route)) return routeModelId(route);
+  const start = routeStartDay(route);
+  for (let offset = 0; offset < DAY_COUNT_2026; offset += 1) {
+    const alias = dayOfYearAlias((start + offset) % DAY_COUNT_2026);
+    if (!used.has(alias)) return alias;
+  }
+  throw new DesktopProfileError("all 365 encoded date slots are occupied", `profile.assignments.${route}.alias`);
+}
+
+export function reconcileDesktopProfile(
+  stored: unknown,
+  models: readonly DesktopProfileModel[],
+): DesktopProfile {
+  const profile = stored === undefined || stored === null ? emptyDesktopProfile() : parseDesktopProfile(stored);
+  const assignments: DesktopProfile["assignments"] = Object.fromEntries(
+    Object.entries(profile.assignments).map(([route, assignment]) => [route, { ...assignment }]),
+  );
+  const used = new Set(Object.values(assignments).map(value => value.alias));
+  for (const model of [...models].sort((a, b) => a.route.localeCompare(b.route))) {
+    if (assignments[model.route]) continue;
+    const alias = allocateAlias(model.route, used);
+    used.add(alias);
+    assignments[model.route] = { family: "opus", alias };
+  }
+  const defaults = { ...profile.defaults };
+  for (const family of DESKTOP_FAMILIES) {
+    const members = Object.keys(assignments).filter(route => assignments[route]!.family === family).sort();
+    const current = defaults[family];
+    defaults[family] = current && assignments[current]?.family === family ? current : (members[0] ?? null);
+  }
+  return parseDesktopProfile({ version: 1, assignments, defaults, ...appliedMarkers(profile) });
+}
+
+export function moveDesktopRoute(
+  profile: DesktopProfile,
+  route: string,
+  family: DesktopFamily,
+  makeDefault = false,
+): DesktopProfile {
+  const parsed = parseDesktopProfile(profile);
+  const current = parsed.assignments[route];
+  if (!current) throw new DesktopProfileError("route is not assigned", `profile.assignments.${route}`);
+  const oldFamily = current.family;
+  if (oldFamily === family) {
+    return makeDefault ? setDesktopFamilyDefault(parsed, family, route) : parsed;
+  }
+  const assignments = { ...parsed.assignments, [route]: { ...current, family } };
+  const defaults = { ...parsed.defaults };
+  if (defaults[oldFamily] === route) {
+    defaults[oldFamily] = Object.keys(assignments).filter(key => key !== route && assignments[key]!.family === oldFamily).sort()[0] ?? null;
+  }
+  const destinationMembers = Object.keys(assignments).filter(key => assignments[key]!.family === family).sort();
+  if (makeDefault || !defaults[family] || assignments[defaults[family]!]?.family !== family) defaults[family] = route;
+  if (!defaults[family] && destinationMembers.length > 0) defaults[family] = destinationMembers[0]!;
+  return parseDesktopProfile({ version: 1, assignments, defaults, ...appliedMarkers(parsed) });
+}
+
+export function setDesktopFamilyDefault(
+  profile: DesktopProfile,
+  family: DesktopFamily,
+  route: string | null,
+): DesktopProfile {
+  const parsed = parseDesktopProfile(profile);
+  const members = Object.keys(parsed.assignments).filter(key => parsed.assignments[key]!.family === family);
+  if (route === null && members.length > 0) throw new DesktopProfileError("cannot clear a non-empty family default", `profile.defaults.${family}`);
+  if (route !== null && parsed.assignments[route]?.family !== family) throw new DesktopProfileError("route is not a member of this family", `profile.defaults.${family}`);
+  return parseDesktopProfile({ ...parsed, defaults: { ...parsed.defaults, [family]: route } });
+}
+
+export function renderDesktopProfile(
+  profile: DesktopProfile,
+  models: readonly DesktopProfileModel[],
+): RenderedDesktopModel[] {
+  const parsed = parseDesktopProfile(profile);
+  const modelByRoute = new Map(models.map(model => [model.route, model]));
+  const activeByFamily = new Map<DesktopFamily, string[]>();
+  for (const family of DESKTOP_FAMILIES) activeByFamily.set(family, []);
+  for (const [route, assignment] of Object.entries(parsed.assignments)) {
+    if (modelByRoute.has(route)) activeByFamily.get(assignment.family)!.push(route);
+  }
+  for (const routes of activeByFamily.values()) routes.sort();
+  const effectiveDefaults = {} as Record<DesktopFamily, string | null>;
+  for (const family of DESKTOP_FAMILIES) {
+    const active = activeByFamily.get(family)!;
+    const stored = parsed.defaults[family];
+    effectiveDefaults[family] = stored && active.includes(stored) ? stored : (active[0] ?? null);
+  }
+  const defaultOrder = DESKTOP_FAMILIES.map(family => effectiveDefaults[family]).filter((route): route is string => !!route);
+  const defaultSet = new Set(defaultOrder);
+  const rest = Object.keys(parsed.assignments).filter(route => modelByRoute.has(route) && !defaultSet.has(route)).sort();
+  return [...defaultOrder, ...rest].map(route => {
+    const model = modelByRoute.get(route)!;
+    const assignment = parsed.assignments[route]!;
+    return {
+      ...model,
+      name: assignment.alias,
+      family: assignment.family,
+      isFamilyDefault: effectiveDefaults[assignment.family] === route,
+      supports1m: typeof model.contextWindow === "number" && model.contextWindow >= 1_000_000,
+    };
+  });
+}