@bitkyc08/opencodex 2.43.0 → 2.44.0

package/src/claude/desktop-remote-store-io.ts

@@ -0,0 +1,91 @@
+import { chmodSync, lstatSync, mkdirSync, readFileSync, realpathSync, unlinkSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { atomicWriteFile, getConfigDir } from "../config";
+import { hardenSecretDir } from "../lib/windows-secret-acl";
+import { isRecord, resolveDesktop3pConfigLibraryPath, SAFE_DESKTOP_PROFILE_ID, type Desktop3pMetadata } from "./desktop-3p-library";
+import { DesktopStoreError, digest } from "./desktop-remote-store-state";
+
+export const MAX_DESKTOP_METADATA_ENTRIES = 256;
+
+export interface JsonFile { value: Record<string, unknown>; hash: string; identity: string }
+const identity = (s: NonNullable<ReturnType<typeof lstatSync>>): string => `${s.dev}:${s.ino}:${s.size}:${s.mtimeMs}`;
+function missing(error: unknown): boolean { return (error as NodeJS.ErrnoException)?.code === "ENOENT"; }
+export function canonicalDirectory(path: string): string {
+  const absolute = resolve(path);
+  try {
+    const stat = lstatSync(absolute);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) throw new DesktopStoreError("unsafe");
+    return realpathSync(absolute);
+  } catch (error) {
+    if (!missing(error)) throw error;
+    const parent = dirname(absolute);
+    return parent === absolute ? absolute : join(canonicalDirectory(parent), basename(absolute));
+  }
+}
+export function storePaths() {
+  const home = canonicalDirectory(getConfigDir());
+  const library = canonicalDirectory(resolveDesktop3pConfigLibraryPath());
+  const root = canonicalDirectory(join(home, "desktop-remote"));
+  return { home, library, root, state: join(root, "state.json"), baseline: join(root, "baseline.json"), disconnect: join(root, "disconnect.json") };
+}
+export class StoreIO {
+  changed = false;
+  private bytes = 0;
+  private readonly seenSizes = new Map<string, number>();
+  read(path: string, maxBytes = 1024 * 1024, privateFile = false): JsonFile | null {
+    let stat: ReturnType<typeof lstatSync>;
+    try { stat = lstatSync(path); }
+    catch (error) { if (missing(error)) return null; throw new DesktopStoreError("unsafe"); }
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > maxBytes
+      || (privateFile && process.platform !== "win32" && (stat.mode & 0o077) !== 0)) throw new DesktopStoreError("unsafe");
+    const counted = this.seenSizes.get(path) ?? 0;
+    this.bytes += Math.max(0, stat.size - counted);
+    this.seenSizes.set(path, Math.max(counted, stat.size));
+    if (this.bytes > 8 * 1024 * 1024) throw new DesktopStoreError("unsafe");
+    try {
+      const bytes = readFileSync(path);
+      if (bytes.byteLength > maxBytes || identity(lstatSync(path)) !== identity(stat)) throw new DesktopStoreError("conflict");
+      const value: unknown = JSON.parse(bytes.toString("utf8"));
+      if (!isRecord(value)) throw new DesktopStoreError("unsafe");
+      return { value, hash: digest(bytes.toString("utf8")), identity: identity(stat) };
+    } catch (error) { if (error instanceof DesktopStoreError) throw error; throw new DesktopStoreError("unsafe"); }
+  }
+  ensureDirectory(path: string): void {
+    canonicalDirectory(path);
+    mkdirSync(path, { recursive: true, mode: 0o700 });
+    canonicalDirectory(path);
+    chmodSync(path, 0o700);
+    if (process.platform === "win32") hardenSecretDir(path, { required: true });
+  }
+  compare(path: string, expected: JsonFile | null): void {
+    const fresh = this.read(path);
+    if (fresh?.hash !== expected?.hash || fresh?.identity !== expected?.identity) throw new DesktopStoreError("conflict");
+  }
+  write(path: string, value: unknown, expected: JsonFile | null, maxBytes = 1024 * 1024): void {
+    const bytes = JSON.stringify(value, null, 2) + "\n";
+    if (Buffer.byteLength(bytes) > maxBytes) throw new DesktopStoreError("unsafe");
+    this.compare(path, expected);
+    this.ensureDirectory(dirname(path));
+    atomicWriteFile(path, bytes, undefined, { validateBeforeRename: () => this.compare(path, expected) });
+    this.changed = true;
+  }
+  remove(path: string, expected: JsonFile): void {
+    this.compare(path, expected);
+    unlinkSync(path);
+    this.changed = true;
+  }
+}
+export function metadata(io: StoreIO, library: string): { file: JsonFile | null; value: Desktop3pMetadata } {
+  const file = io.read(join(library, "_meta.json"));
+  if (!file) return { file, value: { entries: [] } };
+  const value = file.value;
+  if (!Array.isArray(value.entries) || value.entries.length > MAX_DESKTOP_METADATA_ENTRIES) throw new DesktopStoreError("unsafe");
+  const seen = new Set<string>();
+  for (const entry of value.entries) {
+    if (!isRecord(entry) || typeof entry.id !== "string" || !SAFE_DESKTOP_PROFILE_ID.test(entry.id)
+      || seen.has(entry.id) || typeof entry.name !== "string") throw new DesktopStoreError("unsafe");
+    seen.add(entry.id);
+  }
+  if (value.appliedId !== undefined && (typeof value.appliedId !== "string" || !seen.has(value.appliedId))) throw new DesktopStoreError("unsafe");
+  return { file, value: value as unknown as Desktop3pMetadata };
+}

package/src/claude/desktop-remote-store-state.ts

@@ -0,0 +1,127 @@
+import { createHash } from "node:crypto";
+import { OPENCODEX_DESKTOP_PROFILE_KEYS, SAFE_DESKTOP_PROFILE_ID, isRecord } from "./desktop-3p-library";
+
+export type DesktopRemoteOwner = { serverUrl: string; apiKeyId: string; connectedAt: string };
+export type DesktopStoreResult =
+  | { ok: true; changed: boolean; status: "absent" | "applied" | "updated" | "restored";
+      baselineKind?: "known" | "standard_fallback";
+      restoration?: "owned_projection" | "standard_fallback" | "selection_preserved";
+      retainedForeignData?: boolean; restartRequired: boolean; path?: string; fingerprint?: string }
+  | { ok: false; changed: boolean; reason: "busy" | "conflict" | "unsafe" | "recovery_required" | "cleanup_pending" | "desired_disabled" };
+export type StoreReason = Extract<DesktopStoreResult, { ok: false }>["reason"];
+export class DesktopStoreError extends Error {
+  constructor(readonly reason: StoreReason) { super(`desktop_store_${reason}`); }
+}
+export type Projection = Record<string, unknown>;
+export interface Baseline {
+  version: 1; owner: DesktopRemoteOwner; home: string; library: string; targetId: string;
+  kind: "known" | "standard_fallback"; targetExisted: boolean; projection: Projection;
+  priorSelection: { id: string; hash: string } | null;
+}
+export interface ArtifactPending {
+  kind: "apply" | "rotate" | "restore"; before: string; after: string;
+  beforeSelection: string | null; afterSelection: string | null;
+  tokenFingerprint: string;
+}
+export interface StoreState {
+  version: 1; owner: DesktopRemoteOwner; home: string; library: string; targetId: string;
+  baselineRef: "baseline.json"; baselineHash: string; baselineKind: Baseline["kind"];
+  phase: "prepared" | "active" | "restored" | "cleaned";
+  lastProjectionHash: string; tokenFingerprint: string; pending?: ArtifactPending;
+}
+export interface DesktopDisconnectReceipt {
+  version: 1; owner: DesktopRemoteOwner; tokenFingerprint: string; keepCatalog: boolean;
+  phase: "prepared" | "desktop_restored" | "catalog_settled" | "removing_token" | "token_removed"
+    | "clearing_connection" | "connection_cleared" | "complete";
+  desktopAfterFingerprint?: string;
+  catalogAfter?: { kind: "absent" } | { kind: "file"; fingerprint: string };
+}
+export const DISCONNECT_PHASES = ["prepared", "desktop_restored", "catalog_settled", "removing_token", "token_removed", "clearing_connection", "connection_cleared", "complete"] as const;
+export function canonical(value: unknown): string {
+  const sort = (v: unknown): unknown => Array.isArray(v) ? v.map(sort) : isRecord(v)
+    ? Object.fromEntries(Object.keys(v).sort().map(k => [k, sort(v[k])])) : v;
+  const text = JSON.stringify(sort(value));
+  if (text === undefined) throw new DesktopStoreError("unsafe");
+  return text;
+}
+export function digest(value: string): string { return createHash("sha256").update(value).digest("hex"); }
+export function projection(value: Record<string, unknown>): Projection {
+  return Object.fromEntries(Object.entries(value).filter(([key]) => OPENCODEX_DESKTOP_PROFILE_KEYS.has(key)));
+}
+export function projectionHash(value: Record<string, unknown> | null): string {
+  return digest(canonical(value === null ? null : projection(value)));
+}
+export function mergeProjection(current: Record<string, unknown>, owned: Projection): Record<string, unknown> {
+  return { ...Object.fromEntries(Object.entries(current).filter(([k]) => !OPENCODEX_DESKTOP_PROFILE_KEYS.has(k))), ...owned };
+}
+export function sameOwner(a: DesktopRemoteOwner, b: DesktopRemoteOwner): boolean { return canonical(a) === canonical(b); }
+export function exact(value: Record<string, unknown>, keys: string[]): void {
+  if (Object.keys(value).some(k => !keys.includes(k))) throw new DesktopStoreError("unsafe");
+}
+export function origin(value: unknown): string {
+  if (typeof value !== "string") throw new DesktopStoreError("unsafe");
+  let url: URL;
+  try { url = new URL(value); } catch { throw new DesktopStoreError("unsafe"); }
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash
+    || !['/', '/v1', '/v1/'].includes(url.pathname)) throw new DesktopStoreError("unsafe");
+  return url.origin;
+}
+export function parseOwner(value: unknown): DesktopRemoteOwner {
+  if (!isRecord(value)) throw new DesktopStoreError("unsafe");
+  exact(value, ["serverUrl", "apiKeyId", "connectedAt"]);
+  if (typeof value.apiKeyId !== "string" || !value.apiKeyId || value.apiKeyId.length > 256
+    || typeof value.connectedAt !== "string" || !Number.isFinite(Date.parse(value.connectedAt))
+    || origin(value.serverUrl) !== value.serverUrl) throw new DesktopStoreError("unsafe");
+  return value as DesktopRemoteOwner;
+}
+export function isHash(value: unknown): value is string { return typeof value === "string" && /^[a-f0-9]{64}$/.test(value); }
+export function parseState(value: unknown): StoreState {
+  if (!isRecord(value)) throw new DesktopStoreError("unsafe");
+  exact(value, ["version", "owner", "home", "library", "targetId", "baselineRef", "baselineHash", "baselineKind", "phase", "lastProjectionHash", "tokenFingerprint", "pending"]);
+  parseOwner(value.owner);
+  if (value.version !== 1 || typeof value.home !== "string" || typeof value.library !== "string"
+    || typeof value.targetId !== "string" || !SAFE_DESKTOP_PROFILE_ID.test(value.targetId)
+    || value.baselineRef !== "baseline.json" || !isHash(value.baselineHash) || !isHash(value.lastProjectionHash)
+    || !isHash(value.tokenFingerprint) || !["known", "standard_fallback"].includes(String(value.baselineKind))
+    || !["prepared", "active", "restored", "cleaned"].includes(String(value.phase))) throw new DesktopStoreError("unsafe");
+  if (value.pending !== undefined) {
+    const p = value.pending;
+    if (!isRecord(p)) throw new DesktopStoreError("unsafe");
+    exact(p, ["kind", "before", "after", "beforeSelection", "afterSelection", "tokenFingerprint"]);
+    if (!['apply', 'rotate', 'restore'].includes(String(p.kind)) || !isHash(p.before) || !isHash(p.after) || !isHash(p.tokenFingerprint)
+      || [p.beforeSelection, p.afterSelection].some(id => id !== null && (typeof id !== "string" || !SAFE_DESKTOP_PROFILE_ID.test(id)))) throw new DesktopStoreError("unsafe");
+  }
+  return value as unknown as StoreState;
+}
+export function parseBaseline(value: unknown): Baseline {
+  if (!isRecord(value)) throw new DesktopStoreError("unsafe");
+  exact(value, ["version", "owner", "home", "library", "targetId", "kind", "targetExisted", "projection", "priorSelection"]);
+  parseOwner(value.owner);
+  if (value.version !== 1 || typeof value.home !== "string" || typeof value.library !== "string"
+    || typeof value.targetId !== "string" || !SAFE_DESKTOP_PROFILE_ID.test(value.targetId)
+    || !["known", "standard_fallback"].includes(String(value.kind)) || typeof value.targetExisted !== "boolean"
+    || !isRecord(value.projection) || Object.keys(value.projection).some(k => !OPENCODEX_DESKTOP_PROFILE_KEYS.has(k))) throw new DesktopStoreError("unsafe");
+  if (value.kind === "standard_fallback" && Object.keys(value.projection).length) throw new DesktopStoreError("unsafe");
+  if (value.priorSelection !== null) {
+    const p = value.priorSelection;
+    if (!isRecord(p)) throw new DesktopStoreError("unsafe");
+    exact(p, ["id", "hash"]);
+    if (typeof p.id !== "string" || !SAFE_DESKTOP_PROFILE_ID.test(p.id) || !isHash(p.hash)) throw new DesktopStoreError("unsafe");
+  }
+  return value as unknown as Baseline;
+}
+export function parseDisconnect(value: unknown): DesktopDisconnectReceipt {
+  if (!isRecord(value)) throw new DesktopStoreError("unsafe");
+  exact(value, ["version", "owner", "tokenFingerprint", "keepCatalog", "phase", "desktopAfterFingerprint", "catalogAfter"]);
+  parseOwner(value.owner);
+  if (value.version !== 1 || !isHash(value.tokenFingerprint) || typeof value.keepCatalog !== "boolean"
+    || !DISCONNECT_PHASES.includes(value.phase as DesktopDisconnectReceipt['phase'])
+    || (value.desktopAfterFingerprint !== undefined && !isHash(value.desktopAfterFingerprint))) throw new DesktopStoreError("unsafe");
+  if (value.catalogAfter !== undefined) {
+    const c = value.catalogAfter;
+    if (!isRecord(c)) throw new DesktopStoreError("unsafe");
+    exact(c, c.kind === "absent" ? ["kind"] : ["kind", "fingerprint"]);
+    if (c.kind !== "absent" && (c.kind !== "file" || !isHash(c.fingerprint))) throw new DesktopStoreError("unsafe");
+  }
+  return value as unknown as DesktopDisconnectReceipt;
+}

package/src/claude/desktop-remote-store.ts

@@ -0,0 +1,269 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { readConfigDiagnostics, withConfigMutationLockSync } from "../config";
+import { assertClientLifecycleHeld, type ClientLifecycleHeld } from "../client/lifecycle-lock";
+import { readServiceApiTokenState, serviceApiTokenFingerprint } from "../lib/service-secrets";
+import { assertDesktop3pModelsValid } from "./desktop-3p-guard";
+import { profilePath } from "./desktop-3p-library";
+import type { Desktop3pConfigMode, Desktop3pModelEntry } from "./desktop-3p";
+import { StoreIO, metadata, storePaths } from "./desktop-remote-store-io";
+import {
+  DesktopStoreError, DISCONNECT_PHASES, canonical, origin, parseDisconnect, parseOwner,
+  projection, projectionHash, sameOwner, type DesktopDisconnectReceipt, type DesktopRemoteOwner, type DesktopStoreResult,
+} from "./desktop-remote-store-state";
+import {
+  artifact, cleanBackup, currentConnection, establish, loadBundle, locateLegacy, profileCredential,
+  requireOwner, saveState, selectedFile, serviceGenerations, type Bundle,
+} from "./desktop-remote-store-artifact";
+export type { DesktopDisconnectReceipt, DesktopRemoteOwner, DesktopStoreResult } from "./desktop-remote-store-state";
+
+function mutation(held: ClientLifecycleHeld, operation: (io: StoreIO) => DesktopStoreResult): DesktopStoreResult {
+  assertClientLifecycleHeld(held);
+  const io = new StoreIO();
+  try { return withConfigMutationLockSync(() => operation(io)); }
+  catch (error) { return { ok: false, changed: io.changed, reason: error instanceof DesktopStoreError ? error.reason : io.changed ? "recovery_required" : "unsafe" }; }
+}
+function absent(io?: StoreIO): DesktopStoreResult { return { ok: true, changed: io?.changed ?? false, status: "absent", restartRequired: false }; }
+function success(io: StoreIO, bundle: Bundle, status: "applied" | "updated" | "restored", extra: Partial<Extract<DesktopStoreResult, { ok: true }>> = {}): DesktopStoreResult {
+  return { ok: true, changed: io.changed, status, baselineKind: bundle.state!.baselineKind,
+    restartRequired: io.changed, path: profilePath(bundle.paths.library, bundle.state!.targetId),
+    fingerprint: bundle.state!.lastProjectionHash, ...extra };
+}
+function receipt(io: StoreIO): DesktopDisconnectReceipt | null {
+  const file = io.read(storePaths().disconnect, 64 * 1024, true);
+  return file ? parseDisconnect(file.value) : null;
+}
+function noDisconnect(io: StoreIO): void {
+  const value = receipt(io);
+  if (value && value.phase !== "complete") throw new DesktopStoreError("conflict");
+}
+function knownGeneration(expected: string, candidates: readonly string[]): void {
+  if (!candidates.includes(expected)) throw new DesktopStoreError("conflict");
+}
+function recordedGenerations(io: StoreIO, owner: DesktopRemoteOwner): string[] {
+  const bundle = loadBundle(io);
+  const terminal = receipt(io);
+  if (bundle.state?.phase === "cleaned" && terminal?.phase === "complete"
+    && sameOwner(bundle.state.owner, terminal.owner) && !sameOwner(owner, terminal.owner)) return serviceGenerations();
+  requireOwner(bundle, owner);
+  return [...serviceGenerations(), ...(bundle.state ? [bundle.state.tokenFingerprint] : []),
+    ...(bundle.state?.pending ? [bundle.state.pending.tokenFingerprint] : [])];
+}
+
+export function inspectRemoteDesktopStore(owner: DesktopRemoteOwner): {
+  kind: "absent" | "active" | "pending" | "restored" | "legacy_current_connection" | "conflict" | "unsafe";
+} {
+  try {
+    parseOwner(owner);
+    const io = new StoreIO(), bundle = loadBundle(io);
+    if (bundle.state?.phase === "cleaned") {
+      const terminal = receipt(io);
+      if (terminal?.phase === "complete" && sameOwner(bundle.state.owner, terminal.owner) && !sameOwner(owner, terminal.owner)) return { kind: "absent" };
+    }
+    requireOwner(bundle, owner);
+    if (bundle.state) {
+      if (bundle.state.phase === "prepared" || bundle.state.pending) return { kind: "pending" };
+      if (bundle.state.phase === "cleaned") return { kind: "restored" };
+      const meta = metadata(io, bundle.paths.library);
+      selectedFile(io, bundle.paths.library, meta.value);
+      if (!meta.value.entries.some(e => e.id === bundle.state!.targetId && e.name === "opencodex")) return { kind: "conflict" };
+      const file = io.read(profilePath(bundle.paths.library, bundle.state.targetId));
+      if (projectionHash(file?.value ?? null) !== bundle.state.lastProjectionHash) return { kind: "conflict" };
+      return { kind: bundle.state.phase === "restored" ? "restored" : "active" };
+    }
+    if (existsSync(bundle.paths.root) && !receipt(io)) throw new DesktopStoreError("unsafe");
+    const legacy = locateLegacy(io, owner, serviceGenerations());
+    if (legacy) currentConnection(owner);
+    return { kind: legacy ? "legacy_current_connection" : "absent" };
+  } catch (error) { return { kind: error instanceof DesktopStoreError && error.reason === "conflict" ? "conflict" : "unsafe" }; }
+}
+
+export function applyRemoteDesktopStore(held: ClientLifecycleHeld, options: {
+  owner: DesktopRemoteOwner; expectedTokenFingerprint: string;
+  baseUrl: string; apiKey: string; mode: Desktop3pConfigMode; models: Desktop3pModelEntry[];
+}): DesktopStoreResult {
+  return mutation(held, io => {
+    const { config, client } = currentConnection(options.owner);
+    noDisconnect(io);
+    if (client.pendingOperation) throw new DesktopStoreError("conflict");
+    const token = readServiceApiTokenState();
+    if (token.kind !== "present" || token.fingerprint !== options.expectedTokenFingerprint || token.fingerprint !== client.tokenFingerprint
+      || serviceApiTokenFingerprint(options.apiKey) !== token.fingerprint || origin(options.baseUrl) !== options.owner.serverUrl) throw new DesktopStoreError("conflict");
+    if (config.clientIntegrations?.["claude-desktop"] === false) throw new DesktopStoreError("desired_disabled");
+    if (!options.models.length || !["static", "hybrid", "discovery"].includes(options.mode)) throw new DesktopStoreError("unsafe");
+    assertDesktop3pModelsValid(options.models);
+    const bundle = establish(io, options.owner, [token.fingerprint, ...serviceGenerations()], false)!;
+    const value = {
+      inferenceProvider: "gateway", inferenceCredentialKind: "static", inferenceGatewayBaseUrl: options.owner.serverUrl,
+      inferenceGatewayApiKey: options.apiKey, modelDiscoveryEnabled: options.mode !== "static",
+      ...(options.mode === "discovery" ? {} : { inferenceModels: options.models }),
+    };
+    artifact(io, bundle, value, "apply", token.fingerprint, bundle.state!.targetId);
+    cleanBackup(io, bundle, [token.fingerprint, ...serviceGenerations()]);
+    return success(io, bundle, "applied");
+  });
+}
+
+export function replaceRemoteDesktopCredential(held: ClientLifecycleHeld, options: {
+  owner: DesktopRemoteOwner; expectedTokenFingerprint: string; replacementKey: string;
+}): DesktopStoreResult {
+  return mutation(held, io => {
+    const { config, client } = currentConnection(options.owner);
+    noDisconnect(io);
+    const token = readServiceApiTokenState();
+    const generations = recordedGenerations(io, options.owner);
+    const replacement = serviceApiTokenFingerprint(options.replacementKey);
+    if (token.kind !== "present" || replacement !== token.fingerprint
+      || (token.fingerprint !== client.tokenFingerprint && !client.pendingOperation)) throw new DesktopStoreError("conflict");
+    knownGeneration(options.expectedTokenFingerprint, generations);
+    const bundle = establish(io, options.owner, [options.expectedTokenFingerprint, ...generations], true);
+    if (!bundle) return absent(io);
+    if (bundle.state!.phase === "restored") return restoreArtifact(io, bundle, generations);
+    if (config.clientIntegrations?.["claude-desktop"] === false) return restoreArtifact(io, bundle, generations);
+    const file = io.read(profilePath(bundle.paths.library, bundle.state!.targetId));
+    if (!file) throw new DesktopStoreError("unsafe");
+    const credential = profileCredential(file.value);
+    if (!credential || credential.origin !== options.owner.serverUrl
+      || ![options.expectedTokenFingerprint, replacement].includes(credential.fingerprint)) throw new DesktopStoreError("conflict");
+    artifact(io, bundle, { ...projection(file.value), inferenceGatewayApiKey: options.replacementKey }, "rotate", replacement);
+    cleanBackup(io, bundle, [options.expectedTokenFingerprint, ...generations]);
+    return success(io, bundle, "updated");
+  });
+}
+
+function restoreArtifact(io: StoreIO, bundle: Bundle, known: readonly string[]): DesktopStoreResult {
+  let state = bundle.state!;
+  const baseline = bundle.baseline;
+  if (!baseline) throw new DesktopStoreError("recovery_required");
+  const meta = metadata(io, bundle.paths.library);
+  selectedFile(io, bundle.paths.library, meta.value);
+  let selection = meta.value.appliedId ?? state.targetId;
+  let restoration: "owned_projection" | "standard_fallback" | "selection_preserved" = baseline.kind === "standard_fallback" ? "standard_fallback" : "owned_projection";
+  if (selection !== state.targetId) restoration = "selection_preserved";
+  else if (baseline.priorSelection && baseline.priorSelection.id !== state.targetId) {
+    const priorSelection = baseline.priorSelection;
+    const prior = io.read(profilePath(bundle.paths.library, priorSelection.id));
+    if (!prior || prior.hash !== priorSelection.hash || !meta.value.entries.some(e => e.id === priorSelection.id)) throw new DesktopStoreError("conflict");
+    const key = profileCredential(prior.value);
+    if (key && known.includes(key.fingerprint)) throw new DesktopStoreError("conflict");
+    selection = priorSelection.id;
+  }
+  const originalKey = profileCredential(baseline.projection);
+  if (originalKey && known.includes(originalKey.fingerprint)) throw new DesktopStoreError("conflict");
+  const current = io.read(profilePath(bundle.paths.library, state.targetId));
+  const retainedForeignData = current !== null && Object.keys(current.value).length > Object.keys(projection(current.value)).length;
+  if (state.pending && state.pending.kind !== "restore") {
+    const observed = projectionHash(current?.value ?? null);
+    if (observed !== state.pending.before && observed !== state.pending.after) throw new DesktopStoreError("conflict");
+    const targetEntry = meta.value.entries.find(e => e.id === state.targetId);
+    const uncommittedCreation = !baseline.targetExisted && state.lastProjectionHash === projectionHash(null);
+    if ((targetEntry && targetEntry.name !== "opencodex") || (!targetEntry && !uncommittedCreation)) throw new DesktopStoreError("conflict");
+    const tokenFingerprint = observed === state.pending.after ? state.pending.tokenFingerprint : state.tokenFingerprint;
+    // Transition the intent, not the last committed projection. A profile may
+    // already exist while its new metadata row has never been committed.
+    saveState(io, bundle, { ...state, tokenFingerprint, pending: {
+      kind: "restore", before: observed, after: projectionHash(baseline.projection),
+      beforeSelection: meta.value.appliedId ?? null, afterSelection: selection, tokenFingerprint,
+    } });
+    state = bundle.state!;
+  }
+  artifact(io, bundle, baseline.projection, "restore", state.tokenFingerprint, selection);
+  cleanBackup(io, bundle, [...known, state.tokenFingerprint]);
+  return success(io, bundle, "restored", { restoration, retainedForeignData: !baseline.targetExisted && retainedForeignData });
+}
+
+export function restoreRemoteDesktopStore(held: ClientLifecycleHeld, options: {
+  owner: DesktopRemoteOwner; knownTokenFingerprints: readonly string[];
+}): DesktopStoreResult {
+  return mutation(held, io => {
+    currentConnection(options.owner);
+    const generations = recordedGenerations(io, options.owner);
+    if (options.knownTokenFingerprints.some(hash => !generations.includes(hash))) throw new DesktopStoreError("conflict");
+    const bundle = establish(io, options.owner, generations, true);
+    if (!bundle) return absent(io);
+    return restoreArtifact(io, bundle, [...generations, ...options.knownTokenFingerprints]);
+  });
+}
+
+export function readDesktopDisconnectReceipt():
+  | { kind: "absent" } | { kind: "valid"; value: DesktopDisconnectReceipt } | { kind: "unsafe" } {
+  try { const value = receipt(new StoreIO()); return value ? { kind: "valid", value } : { kind: "absent" }; }
+  catch { return { kind: "unsafe" }; }
+}
+export function writeDesktopDisconnectReceipt(held: ClientLifecycleHeld, expected: DesktopDisconnectReceipt | null, next: DesktopDisconnectReceipt): void {
+  assertClientLifecycleHeld(held);
+  try {
+    withConfigMutationLockSync(() => {
+      parseDisconnect(next);
+      if (expected) parseDisconnect(expected);
+      const io = new StoreIO(), paths = storePaths();
+      const file = io.read(paths.disconnect, 64 * 1024, true);
+      const current = file ? parseDisconnect(file.value) : null;
+      if (canonical(current) !== canonical(expected)) throw new DesktopStoreError("conflict");
+      const rollover = current?.phase === "complete" && next.phase === "prepared" && !sameOwner(current.owner, next.owner);
+      if (!current || rollover) {
+        if (next.phase !== "prepared") throw new DesktopStoreError("conflict");
+        const { client } = currentConnection(next.owner);
+        const token = readServiceApiTokenState();
+        if (client.pendingOperation || token.kind !== "present" || token.fingerprint !== next.tokenFingerprint || client.tokenFingerprint !== token.fingerprint) throw new DesktopStoreError("conflict");
+        if (rollover) {
+          const bundle = loadBundle(io);
+          if (bundle.baselineFile || (bundle.state && (bundle.state.phase !== "cleaned" || !sameOwner(bundle.state.owner, current!.owner)))) throw new DesktopStoreError("conflict");
+          if (bundle.stateFile) io.remove(paths.state, bundle.stateFile);
+        }
+      } else {
+        if (!sameOwner(current.owner, next.owner) || current.tokenFingerprint !== next.tokenFingerprint || current.keepCatalog !== next.keepCatalog) throw new DesktopStoreError("conflict");
+        const delta = DISCONNECT_PHASES.indexOf(next.phase) - DISCONNECT_PHASES.indexOf(current.phase);
+        if (delta !== 0 && delta !== 1) throw new DesktopStoreError("conflict");
+        if ((current.desktopAfterFingerprint && current.desktopAfterFingerprint !== next.desktopAfterFingerprint)
+          || (current.catalogAfter && canonical(current.catalogAfter) !== canonical(next.catalogAfter))) throw new DesktopStoreError("conflict");
+      }
+      io.write(paths.disconnect, next, file, 64 * 1024);
+    });
+  } catch (error) {
+    throw new Error(error instanceof DesktopStoreError && error.reason === "conflict"
+      ? "desktop_disconnect_receipt_conflict" : error instanceof DesktopStoreError && error.reason === "unsafe"
+        ? "desktop_disconnect_receipt_unsafe" : "desktop_disconnect_receipt_write_failed");
+  }
+}
+
+export function inspectRemoteDesktopCleanup():
+  | { kind: "absent" } | { kind: "active" | "restored" | "pending"; owner: DesktopRemoteOwner } | { kind: "unsafe" } {
+  try {
+    const io = new StoreIO(), bundle = loadBundle(io), r = receipt(io);
+    if (r && bundle.state && !sameOwner(r.owner, bundle.state.owner)) throw new DesktopStoreError("unsafe");
+    if (bundle.state) {
+      const state = bundle.state;
+      if (state.phase === "cleaned" && r?.phase === "complete") {
+        return bundle.baselineFile ? { kind: "pending", owner: state.owner } : { kind: "absent" };
+      }
+      if (state.pending || state.phase === "prepared") return { kind: "pending", owner: state.owner };
+      if (r && r.phase !== "complete" && state.phase === "cleaned") return { kind: "pending", owner: state.owner };
+      return { kind: state.phase === "restored" || state.phase === "cleaned" ? "restored" : "active", owner: state.owner };
+    }
+    if (r && r.phase !== "complete") return { kind: "pending", owner: r.owner };
+    if (!r && existsSync(bundle.paths.root)) throw new DesktopStoreError("unsafe");
+    return { kind: "absent" };
+  } catch { return { kind: "unsafe" }; }
+}
+
+export function finishRemoteDesktopCleanup(held: ClientLifecycleHeld, owner: DesktopRemoteOwner): DesktopStoreResult {
+  return mutation(held, io => {
+    const r = receipt(io);
+    if (!r || !sameOwner(r.owner, owner) || !["connection_cleared", "complete"].includes(r.phase)) throw new DesktopStoreError("conflict");
+    const diagnostics = readConfigDiagnostics();
+    if (diagnostics.source === "fallback" || diagnostics.config.client || diagnostics.config.runtimeRole === "client"
+      || readServiceApiTokenState().kind !== "absent") throw new DesktopStoreError("conflict");
+    const bundle = loadBundle(io);
+    requireOwner(bundle, owner);
+    if (!bundle.state) return absent(io);
+    if (bundle.state.phase !== "restored" && bundle.state.phase !== "cleaned") throw new DesktopStoreError("conflict");
+    const target = io.read(profilePath(bundle.paths.library, bundle.state.targetId));
+    if (projectionHash(target?.value ?? null) !== bundle.state.lastProjectionHash) throw new DesktopStoreError("conflict");
+    cleanBackup(io, bundle, [r.tokenFingerprint, bundle.state.tokenFingerprint]);
+    // Mark cleanup before unlink so a crash between the two remains recoverable.
+    if (bundle.state.phase !== "cleaned") saveState(io, bundle, { ...bundle.state, phase: "cleaned" });
+    if (bundle.baselineFile) io.remove(bundle.paths.baseline, bundle.baselineFile);
+    return success(io, bundle, "restored", { restartRequired: false });
+  });
+}

package/src/claude/inbound-model-options.ts

@@ -2,8 +2,9 @@ import type { OcxClaudeCodeConfig } from "../types";
 import { isAnthropicOutputSchema } from "../adapters/anthropic-output-schema";
 import { resolveAlias } from "./alias";
 import { stripOneMillionMarker } from "./context-windows";
-import { resolveDesktop3pAlias } from "./desktop-3p";
-import { isRec, type Rec } from "./inbound-records";
+import { isUnresolvedDesktop3pAlias, resolveDesktop3pAlias } from "./desktop-3p";
+import { validDateAlias } from "./desktop-profile";
+import { AnthropicRequestError, DesktopModelMappingUnavailableError, isRec, type Rec } from "./inbound-records";
 
 function isClaudeClassifierModel(model: string): boolean {
   const stripped = model.replace(/-\d{8}$/, "");
@@ -54,6 +55,13 @@ export function resolveInboundModel(model: string, cc?: OcxClaudeCodeConfig): st
   const map = cc?.modelMap ?? {};
   const exact = map[model];
   if (typeof exact === "string" && exact.length > 0) return exact;
+  if (isUnresolvedDesktop3pAlias(model)) {
+    const base = model.endsWith("--fast") ? model.slice(0, -"--fast".length) : model;
+    // A missing date-shaped ID is ambiguous even after a successful but partial
+    // discovery. Never infer that a genuine native model is invalid or reroute it.
+    if (validDateAlias(base)) throw new DesktopModelMappingUnavailableError();
+    throw new AnthropicRequestError("Unknown Claude Desktop alias; reapply the Desktop profile from the connected hub");
+  }
   const stripped = model.replace(/-\d{8}$/, "");
   const dateless = map[stripped];
   if (typeof dateless === "string" && dateless.length > 0) return dateless;

package/src/claude/inbound-records.ts

@@ -1,5 +1,12 @@
 export class AnthropicRequestError extends Error {}
 
+/** A date-shaped Desktop ID can also name a genuine native model absent from discovery. */
+export class DesktopModelMappingUnavailableError extends AnthropicRequestError {
+  constructor() {
+    super("Claude Desktop model mapping is unavailable; refresh model discovery or reapply the connected hub profile");
+  }
+}
+
 export type Rec = Record<string, unknown>;
 
 export function isRec(v: unknown): v is Rec {

package/src/claude/inbound.ts

@@ -12,7 +12,7 @@
 import type { OcxClaudeCodeConfig } from "../types";
 import { createHash } from "node:crypto";
 
-export { AnthropicRequestError } from "./inbound-records";
+export { AnthropicRequestError, DesktopModelMappingUnavailableError } from "./inbound-records";
 export { resolveInboundModel, effortForThinkingBudget, effortFromOutputConfig, extractOcxRouteDirective, extractOcxEffortDirective } from "./inbound-model-options";
 import { AnthropicRequestError, isRec, type Rec } from "./inbound-records";
 import { resolveInboundModel, effortForThinkingBudget, effortFromOutputConfig, formatFromOutputConfig } from "./inbound-model-options";

package/src/claude/model-info.ts

@@ -143,14 +143,19 @@ export function buildAnthropicModelInfos(
   // the auto-context widening that let a 372K route carry the marker (and be
   // over-filled) is the #854 defect and does not come back. Guards (audit R1#11):
   // same dedupe set, never double-suffix.
-  const push1mVariant = (base: AnthropicModelInfo, contextWindow: number | undefined, maxInputTokens?: number) => {
+  const push1mVariant = (
+    base: AnthropicModelInfo,
+    contextWindow: number | undefined,
+    maxInputTokens?: number,
+    selectorId?: string,
+  ) => {
     // The [1m] marker makes Claude Code account 1e6 tokens for the row, so it
     // may only name models whose AUTHORITATIVE effective window is >= 1M —
     // never the auto-context widening, which would mark a 372K route and have
     // Claude Code over-fill it (the #854 defect).
     if (contextWindow === undefined || contextWindow < ONE_MILLION) return;
     if (base.id.includes("[1m]")) return;
-    const id = `${base.id}[1m]`;
+    const id = selectorId ?? `${base.id}[1m]`;
     if (seen.has(id)) return;
     seen.add(id);
     // The marker fixes Claude Code's accounting at 1e6, but a model may accept less input
@@ -220,7 +225,15 @@ export function buildAnthropicModelInfos(
     out.push(info);
     // Anthropic passthrough guard (audit 021 #3): never auto-widen canonical claude
     // routes — only a genuine >=1M window earns the variant row there.
-    push1mVariant(info, m.contextWindow, routedMaxInput);
+    // Claude Code groups canonical Fable ids before it compares the [1m] marker. This
+    // reversible alias only separates picker families; it is not an OpenAI-native route.
+    // The Messages ingress restores the canonical Anthropic id before passthrough.
+    const oneMillionSelector = idStyle === "readable"
+      && m.provider === "anthropic"
+      && listedModelId.startsWith("claude-fable-")
+      ? `${claudeCodeNativeAlias(listedModelId)}[1m]`
+      : undefined;
+    push1mVariant(info, m.contextWindow, routedMaxInput, oneMillionSelector);
     // The whole model is passed, not a (provider, id) pair: a combo row lives in its own
     // namespace with no config.providers entry, so the caller classifies it from the
     // aggregated supportsServiceTier the row already carries.

package/src/cli/account-api.ts

@@ -8,6 +8,7 @@ import { runningProxyUpdateHeaders } from "../oauth/login-cli";
 import { isPublicOAuthProvider } from "../oauth/index";
 import { getProviderRegistryEntry, providerCodexAccountMode } from "../providers/registry";
 import type { OcxConfig } from "../types";
+import { projectCodexQuotaRefreshOutcome, type CodexQuotaRefreshOutcome } from "../codex/quota-refresh-outcome";
 
 export type AccountType = "codex" | "oauth" | "api-key";
 
@@ -24,6 +25,7 @@ export interface AccountRow {
   /** Codex pool selection order, higher used earlier. Absent where ordering does not apply. */
   priority?: number;
   quota?: CodexQuotaDto | null;
+  quotaRefresh?: CodexQuotaRefreshOutcome;
   /**
    * Whether the pool is holding this account out of rotation.
    *
@@ -237,6 +239,7 @@ interface CodexAccountDto {
   needsReauth?: boolean;
   priority?: number;
   quota?: CodexQuotaDto | null;
+  quotaRefresh?: unknown;
   paused?: boolean;
 }
 
@@ -299,7 +302,10 @@ export async function fetchCodexRows(
     needsReauth: a.needsReauth,
     priority: typeof a.priority === "number" ? a.priority : 0,
     paused: a.paused === true,
-    ...(includeQuota ? { quota: projectQuota(a.quota) } : {}),
+    ...(includeQuota ? {
+      quota: projectQuota(a.quota),
+      quotaRefresh: projectCodexQuotaRefreshOutcome(a.quotaRefresh),
+    } : {}),
   }));
   return { rows, activeId, autoSwitchThreshold, status: 200 };
 }

package/src/cli/aside-profiles.ts

@@ -0,0 +1,17 @@
+import type { OwnedIntegrationRefreshOutcome } from "../integrations/owned-refresh";
+import { runtimeRequest, RuntimeApiError, type RuntimeApiDeps } from "./runtime-api";
+
+/** Aside policy and file writes share the running server's mutation owner. Never fall back locally. */
+export async function refreshAsideProfilesThroughServer(
+  deps: RuntimeApiDeps = {},
+): Promise<OwnedIntegrationRefreshOutcome[]> {
+  const result = await runtimeRequest<{ results?: OwnedIntegrationRefreshOutcome[] }>(
+    "/api/client-integrations/aside/sync",
+    { method: "POST", body: "{}" },
+    deps,
+  );
+  if (!Array.isArray(result.results)) {
+    throw new RuntimeApiError("The running proxy does not support Aside profile synchronization", 502, result);
+  }
+  return result.results;
+}