@bitkyc08/opencodex 2.43.0 → 2.44.0

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

@@ -1,13 +1,24 @@
+import { readClientConnectionState } from "../client/state";
+import { readServiceApiTokenState, readTokenBackupState } from "../lib/service-secrets";
+import { withClientLifecycleSync, type ClientLifecycleLockDeps } from "../client/lifecycle-lock";
+import { applyRemoteDesktopStore, inspectRemoteDesktopCleanup, restoreRemoteDesktopStore } from "./desktop-remote-store";
+import { canonicalDirectory } from "./desktop-remote-store-io";
+import {
+  resolveDesktop3pConfigLibraryPath, parseMetadata, SAFE_DESKTOP_PROFILE_ID, isRecord,
+  isOwnedDesktopEntry, isOwnedDesktopGatewayEntry, profilePath, readDesktopProfileForeignKeys,
+  type Desktop3pConfigLibraryOptions, type Desktop3pMetadata, type Desktop3pMetadataEntry,
+} from "./desktop-3p-library";
+export { resolveDesktop3pConfigLibraryPath, type Desktop3pConfigLibraryOptions } from "./desktop-3p-library";
 import { createHash, randomUUID } from "node:crypto";
 import { copyFileSync, existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
-import { atomicWriteFile } from "../config";
+import { atomicWriteFile, readConfigDiagnostics, withConfigMutationLockSync } from "../config";
+import { claudeDesktopIntegrationEnabled } from "../codex/desired-state";
 import type { OcxClaudeDesktopProfile } from "../types";
-import { claudeDesktopConfigLibraryDir, resolveConfigLibraryDir } from "./desktop-3p-paths";
 import {
   reconcileDesktopProfile,
   renderDesktopProfile,
+  validDateAlias,
   type DesktopProfileModel,
 } from "./desktop-profile";
 import { nativeOpenAiContextWindow, type NativeContextLimitsInput } from "../codex/catalog";
@@ -50,33 +61,6 @@ export interface Desktop3pRoutedModel {
  */
 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>([
@@ -91,18 +75,6 @@ export function parseDesktop3pModeArgs(flags: string[]): { mode: Desktop3pConfig
   return { mode: picked[0] ?? "static" };
 }
 
-interface Desktop3pMetadataEntry {
-  id: string;
-  name: string;
-  [key: string]: unknown;
-}
-
-interface Desktop3pMetadata {
-  appliedId?: string;
-  entries: Desktop3pMetadataEntry[];
-  [key: string]: unknown;
-}
-
 export type Desktop3pLibraryKind =
   | "not_installed"
   | "standard"
@@ -144,6 +116,7 @@ export interface Desktop3pRemovalResult {
 
 let desktop3pRegistry = new Map<string, string>();
 let desktop3pAliasesByRoute = new Map<string, string>();
+let desktop3pRealAnthropicIds = new Set<string>();
 
 /** Derive a stable letter-first, three-character base36 code from a route key. */
 export function deriveDesktop3pCode(route: string): string {
@@ -192,7 +165,7 @@ function collectDesktop3pModels(
   routedModels: Array<Desktop3pRoutedModel>,
   profile?: OcxClaudeDesktopProfile,
   nativeContextCap?: NativeContextLimitsInput,
-): { models: Desktop3pModelEntry[]; registry: Map<string, string> } {
+): { models: Desktop3pModelEntry[]; registry: Map<string, string>; realAnthropicIds: Set<string> } {
   const registry = new Map<string, string>();
   const models: Desktop3pModelEntry[] = [];
   const candidates: Desktop3pRoutedModel[] = [
@@ -205,6 +178,9 @@ function collectDesktop3pModels(
     }),
     ...routedModels,
   ];
+  const realAnthropicIds = new Set(candidates
+    .filter(model => model.provider === "anthropic" && model.id.startsWith("claude-"))
+    .map(model => model.id));
 
   if (profile) {
     const profileModels = candidates.map(({ provider, id, contextWindow }) => ({
@@ -242,7 +218,7 @@ function collectDesktop3pModels(
       registry.set(legacy, model.route);
     }
     desktop3pAliasesByRoute = aliasesByRoute;
-    return { models, registry };
+    return { models, registry, realAnthropicIds };
   }
 
   for (const { provider, id, contextWindow } of candidates) {
@@ -285,7 +261,7 @@ function collectDesktop3pModels(
 
   if (models[0]) models[0].isFamilyDefault = true;
   desktop3pAliasesByRoute = new Map(candidates.map(({ provider, id }) => [`${provider}/${id}`, desktop3pAlias(provider, id)]));
-  return { models, registry };
+  return { models, registry, realAnthropicIds };
 }
 
 /** Build and install the registry used to decode Desktop aliases. */
@@ -295,8 +271,9 @@ export function buildDesktop3pRegistry(
   profile?: OcxClaudeDesktopProfile,
   nativeContextCap?: NativeContextLimitsInput,
 ): Map<string, string> {
-  const { registry } = collectDesktop3pModels(nativeSlugs, routedModels, profile, nativeContextCap);
+  const { registry, realAnthropicIds } = collectDesktop3pModels(nativeSlugs, routedModels, profile, nativeContextCap);
   desktop3pRegistry = registry;
+  desktop3pRealAnthropicIds = realAnthropicIds;
   return registry;
 }
 
@@ -307,8 +284,9 @@ export function generateDesktop3pModels(
   profile?: OcxClaudeDesktopProfile,
   nativeContextCap?: NativeContextLimitsInput,
 ): Desktop3pModelEntry[] {
-  const { models, registry } = collectDesktop3pModels(nativeSlugs, routedModels, profile, nativeContextCap);
+  const { models, registry, realAnthropicIds } = collectDesktop3pModels(nativeSlugs, routedModels, profile, nativeContextCap);
   desktop3pRegistry = registry;
+  desktop3pRealAnthropicIds = realAnthropicIds;
   return models;
 }
 
@@ -317,6 +295,21 @@ export function resolveDesktop3pAlias(alias: string): string | null {
   return desktop3pRegistry.get(alias) ?? null;
 }
 
+/** Exact registered and identity-preserving catalog IDs precede synthetic syntax. */
+export function isKnownDesktop3pModelId(id: string): boolean {
+  return desktop3pRegistry.has(id) || desktop3pRealAnthropicIds.has(id);
+}
+
+/** Only missing IDs in the emitted Desktop namespaces are managed-alias errors. */
+export function isUnresolvedDesktop3pAlias(id: string): boolean {
+  if (isKnownDesktop3pModelId(id)) return false;
+  // Validate the managed base even when Fast routing is disabled. This checks
+  // identity only; it neither enables a tier nor strips an exact full catalog ID.
+  const base = id.endsWith("--fast") ? id.slice(0, -"--fast".length) : id;
+  if (isKnownDesktop3pModelId(base)) return false;
+  return validDateAlias(base) || /^claude-opus-4-(?:8-)?[a-z][a-z0-9]{2}$/.test(base);
+}
+
 /** 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);
@@ -363,32 +356,6 @@ export function generateDesktop3pConfig(
   };
 }
 
-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 };
-}
-
-const SAFE_DESKTOP_PROFILE_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function isOwnedDesktopEntry(entry: Desktop3pMetadataEntry | undefined): boolean {
-  return entry?.name === "opencodex" || entry?.name === "opencodex-standard";
-}
-
-/** A gateway row is removable; the selected standard row must always remain. */
-function isOwnedDesktopGatewayEntry(entry: Desktop3pMetadataEntry | undefined): boolean {
-  return entry?.name === "opencodex";
-}
-
-function profilePath(libraryPath: string, id: string): string {
-  return join(libraryPath, `${id}.json`);
-}
-
 /**
  * Read Desktop's selected config without changing its library.
  *
@@ -481,7 +448,76 @@ export function inspectDesktop3pConfigLibrary(
  * (or any other benign mismatch), while the Integrations card still showed the
  * leftover profile as applied/stale.
  */
+/** Keep failures diagnosable without reflecting paths, config bytes or arbitrary errors. */
+function desktopMutationFailureReason(error: unknown): string {
+  const code = error !== null && typeof error === "object" && "code" in error ? error.code : undefined;
+  switch (code) {
+    case "client_lifecycle_busy": return "client_lifecycle_busy";
+    case "client_lifecycle_lock_failed": return "client_lifecycle_lock_failed";
+    case "CONFIG_MUTATION_LOCK_UNAVAILABLE": return "config_mutation_lock_unavailable";
+    case "EACCES":
+    case "EPERM": return "desktop_filesystem_denied";
+    case "ENOENT": return "desktop_path_missing";
+    case "EBUSY": return "desktop_filesystem_busy";
+    default: return "desktop_mutation_failed";
+  }
+}
+
 export function removeDesktop3pStandardPivot(
+  options: Desktop3pConfigLibraryOptions & {
+    appliedFingerprint?: string | null; unlink?: (path: string) => void;
+    lifecycleLockDeps?: ClientLifecycleLockDeps;
+  } = {},
+): Desktop3pRemovalResult {
+  const libraryPath = resolveDesktop3pConfigLibraryPath(options);
+  try {
+    return withClientLifecycleSync<Desktop3pRemovalResult>(held => withConfigMutationLockSync(() => {
+      const connection = readClientConnectionState();
+      if (connection.kind === "invalid" || connection.kind === "mismatched") {
+        return { ok: false, changed: false, kind: "unsafe", libraryPath, reason: `desktop_client_state_${connection.kind}` };
+      }
+      if (connection.kind === "connected"
+        && canonicalDirectory(libraryPath) !== canonicalDirectory(resolveDesktop3pConfigLibraryPath())) {
+        return { ok: false, changed: false, kind: "unsafe", libraryPath, reason: "desktop_library_identity_changed" };
+      }
+      const latest = readConfigDiagnostics();
+      if (latest.source === "fallback") return { ok: false, changed: false, kind: "unsafe", libraryPath, reason: "desktop_config_invalid" };
+      if (claudeDesktopIntegrationEnabled(latest.config)) {
+        const observed = inspectDesktop3pConfigLibrary(options);
+        if (observed.kind === "not_installed" || observed.kind === "no_owned_state") {
+          return { ok: true, changed: false, kind: "noop", libraryPath };
+        }
+        return { ok: false, changed: false, kind: "unsafe", libraryPath, reason: "desired_state_changed" };
+      }
+      const cleanup = inspectRemoteDesktopCleanup();
+      if (cleanup.kind === "absent") {
+        if (connection.kind === "disconnected") return removeDesktop3pStandardPivotLocal(options);
+        const client = connection.value;
+        const known = [readServiceApiTokenState(), readTokenBackupState()].flatMap(token => token.kind === "present" ? [token.fingerprint] : []);
+        const result = restoreRemoteDesktopStore(held, {
+          owner: { serverUrl: new URL(client.serverUrl).origin, apiKeyId: client.apiKeyId, connectedAt: client.connectedAt },
+          knownTokenFingerprints: known,
+        });
+        return result.ok
+          ? { ok: true, changed: result.changed, kind: result.changed ? "removed" : "noop", libraryPath }
+          : { ok: false, changed: result.changed, kind: "unsafe", reason: result.reason, libraryPath };
+      }
+      if (cleanup.kind === "unsafe" || canonicalDirectory(libraryPath) !== canonicalDirectory(resolveDesktop3pConfigLibraryPath())) {
+        return { ok: false, changed: false, kind: "unsafe", libraryPath };
+      }
+      const known = [readServiceApiTokenState(), readTokenBackupState()]
+        .flatMap(token => token.kind === "present" ? [token.fingerprint] : []);
+      const result = restoreRemoteDesktopStore(held, { owner: cleanup.owner, knownTokenFingerprints: known });
+      return result.ok
+        ? { ok: true, changed: result.changed, kind: result.changed ? "removed" : "noop", libraryPath }
+        : { ok: false, changed: result.changed, kind: result.reason === "cleanup_pending" ? "cleanup_incomplete" : "unsafe", reason: result.reason, libraryPath };
+    }), options.lifecycleLockDeps);
+  } catch (error) {
+    return { ok: false, changed: false, kind: "write_failed", libraryPath, reason: desktopMutationFailureReason(error) };
+  }
+}
+
+function removeDesktop3pStandardPivotLocal(
   options: Desktop3pConfigLibraryOptions & {
     appliedFingerprint?: string | null;
     unlink?: (path: string) => void;
@@ -554,8 +590,8 @@ export function removeDesktop3pStandardPivot(
       JSON.stringify({ ...metadataAfterPivot, entries: metadataAfterPivot.entries.filter(entry => !targetIds.includes(entry.id)) }, null, 2) + "\n",
     );
     return { ok: true, changed: true, kind: "removed", libraryPath: inspected.libraryPath };
-  } catch {
-    return { ok: false, changed: false, kind: "write_failed", libraryPath: inspected.libraryPath };
+  } catch (error) {
+    return { ok: false, changed: false, kind: "write_failed", libraryPath: inspected.libraryPath, reason: desktopMutationFailureReason(error) };
   }
 }
 
@@ -568,6 +604,59 @@ export function writeDesktop3pConfig(
   mode: Desktop3pConfigMode = "static",
   profile?: OcxClaudeDesktopProfile,
   nativeContextCap?: NativeContextLimitsInput,
+  lifecycleLockDeps?: ClientLifecycleLockDeps,
+): { written: boolean; path: string; reason?: string; fingerprint?: string } {
+  try {
+    return withClientLifecycleSync(() => withConfigMutationLockSync(() => {
+      const connection = readClientConnectionState();
+      if (connection.kind === "invalid" || connection.kind === "mismatched") {
+        return { written: false, path: resolveDesktop3pConfigLibraryPath(), reason: `desktop_client_state_${connection.kind}` };
+      }
+      const latest = readConfigDiagnostics();
+      if (latest.source === "fallback") return { written: false, path: resolveDesktop3pConfigLibraryPath(), reason: "desktop_config_invalid" };
+      if (!claudeDesktopIntegrationEnabled(latest.config)) {
+        return { written: false, path: resolveDesktop3pConfigLibraryPath(), reason: "desired_state_changed" };
+      }
+      if (connection.kind === "connected" || inspectRemoteDesktopCleanup().kind !== "absent") {
+        return { written: false, path: resolveDesktop3pConfigLibraryPath(), reason: "desktop_remote_store_active" };
+      }
+      return writeDesktop3pConfigWithGenerator(() => (
+        generateDesktop3pConfig(port, nativeSlugs, routedModels, apiKey, mode, profile, nativeContextCap)
+      ));
+    }), lifecycleLockDeps);
+  } catch { return { written: false, path: resolveDesktop3pConfigLibraryPath(), reason: "desktop_lifecycle_busy_or_unsafe" }; }
+}
+
+/** Write the hub's exact entries without constructing a client-local alias registry. */
+export function writeRemoteDesktop3pConfig(options: {
+  baseUrl: string;
+  apiKey: string;
+  mode: Desktop3pConfigMode;
+  models: Desktop3pModelEntry[];
+  lifecycleLockDeps?: ClientLifecycleLockDeps;
+}): { written: boolean; path: string; reason?: string; fingerprint?: string } {
+  try {
+    return withClientLifecycleSync(held => {
+      const connection = readClientConnectionState();
+      const token = readServiceApiTokenState();
+      if (connection.kind !== "connected" || token.kind !== "present") {
+        return { written: false, path: "", reason: "desktop_remote_connection_required" };
+      }
+      const client = connection.value;
+      const result = applyRemoteDesktopStore(held, {
+        baseUrl: options.baseUrl, apiKey: options.apiKey, mode: options.mode, models: options.models,
+        owner: { serverUrl: new URL(client.serverUrl).origin, apiKeyId: client.apiKeyId, connectedAt: client.connectedAt },
+        expectedTokenFingerprint: token.fingerprint,
+      });
+      return result.ok
+        ? { written: result.status === "applied", path: result.path ?? "", fingerprint: result.fingerprint }
+        : { written: false, path: "", reason: result.reason };
+    }, options.lifecycleLockDeps);
+  } catch { return { written: false, path: "", reason: "desktop_lifecycle_busy_or_unsafe" }; }
+}
+
+function writeDesktop3pConfigWithGenerator(
+  generate: () => object,
 ): { written: boolean; path: string; reason?: string; fingerprint?: string } {
   const libraryPath = resolveDesktop3pConfigLibraryPath();
   const metadataPath = join(libraryPath, "_meta.json");
@@ -579,13 +668,13 @@ export function writeDesktop3pConfig(
     const selected = metadata.entries.find(entry => entry?.id === metadata.appliedId && isOwnedDesktopGatewayEntry(entry));
     const existing = selected ?? metadata.entries.find(entry => isOwnedDesktopGatewayEntry(entry) && typeof entry.id === "string");
     const id = existing?.id ?? randomUUID();
-    configPath = join(libraryPath, `${id}.json`);
+    configPath = profilePath(libraryPath, id);
     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 generated = generateDesktop3pConfig(port, nativeSlugs, routedModels, apiKey, mode, profile, nativeContextCap);
+    const generated = generate();
     const preserved = readDesktopProfileForeignKeys(configPath);
     const configJson = JSON.stringify({ ...preserved, ...generated }, null, 2) + "\n";
     const fingerprint = createHash("sha256").update(configJson).digest("hex").slice(0, 16);
@@ -604,24 +693,6 @@ export function writeDesktop3pConfig(
   }
 }
 
-const OPENCODEX_DESKTOP_PROFILE_KEYS = new Set([
-  "inferenceProvider",
-  "inferenceCredentialKind",
-  "inferenceGatewayBaseUrl",
-  "inferenceGatewayApiKey",
-  "modelDiscoveryEnabled",
-  "inferenceModels",
-]);
-
-function readDesktopProfileForeignKeys(path: string): Record<string, unknown> {
-  if (!existsSync(path)) return {};
-  const parsed = JSON.parse(readFileSync(path, "utf8")) as unknown;
-  if (!isRecord(parsed)) throw new Error("Claude Desktop 3P profile is not a JSON object");
-  return Object.fromEntries(
-    Object.entries(parsed).filter(([key]) => !OPENCODEX_DESKTOP_PROFILE_KEYS.has(key)),
-  );
-}
-
 /** Backup an existing owned config then atomically replace it. Exported for failure-path tests. */
 export function atomicReplaceDesktopConfig(
   path: string,

package/src/claude/desktop-discovery-inputs.ts

@@ -0,0 +1,44 @@
+import type { OcxConfig } from "../types";
+import {
+  filterCatalogVisibleModels,
+  nativeContextLimits,
+  orderForSubagents,
+  type CatalogModel,
+  type NativeContextLimits,
+} from "../codex/catalog";
+import { ACCOUNT_GATED_NATIVE_OPENAI_MODELS } from "../codex/catalog/native-models";
+import {
+  availableAccountGatedNativeModels,
+  type CodexModelEntitlementSnapshot,
+} from "../codex/model-entitlements";
+import { MAIN_CODEX_ACCOUNT_ID } from "../codex/main-account";
+import { providerCodexAccountMode } from "../providers/registry";
+import { OPENAI_CODEX_PROVIDER_ID } from "../providers/openai-tiers";
+
+export interface DesktopDiscoveryInputs {
+  nativeSlugs: string[];
+  routedModels: CatalogModel[];
+  nativeContextCap: NativeContextLimits;
+}
+
+/** Project captured discovery state without reading caches or installing aliases. */
+export function buildDesktopDiscoveryInputs(options: {
+  config: OcxConfig;
+  models: readonly CatalogModel[];
+  modelEntitlements: CodexModelEntitlementSnapshot;
+  desktopNativeCandidates: readonly string[];
+}): DesktopDiscoveryInputs {
+  const { config, models, modelEntitlements, desktopNativeCandidates } = options;
+  const eligibleAccountIds = providerCodexAccountMode(
+    OPENAI_CODEX_PROVIDER_ID,
+    config.providers[OPENAI_CODEX_PROVIDER_ID],
+  ) === "direct" ? new Set([MAIN_CODEX_ACCOUNT_ID]) : undefined;
+  const available = availableAccountGatedNativeModels(modelEntitlements, eligibleAccountIds);
+  return {
+    nativeSlugs: desktopNativeCandidates.filter(slug => (
+      !ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(slug) || available.has(slug)
+    )),
+    routedModels: orderForSubagents(filterCatalogVisibleModels([...models], config), config.subagentModels),
+    nativeContextCap: nativeContextLimits(config),
+  };
+}

package/src/claude/desktop-profile.ts

@@ -83,7 +83,7 @@ function isRealAnthropicRoute(route: string): boolean {
   return route.startsWith("anthropic/claude-");
 }
 
-function validDateAlias(alias: string): boolean {
+export function validDateAlias(alias: string): boolean {
   const match = DATE_ALIAS.exec(alias);
   if (!match) return false;
   const year = Number(match[1]!.slice(0, 4));

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

@@ -0,0 +1,185 @@
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { readConfigDiagnostics } from "../config";
+import { readServiceApiTokenState, readTokenBackupState, serviceApiTokenFingerprint } from "../lib/service-secrets";
+import { profilePath, type Desktop3pMetadata } from "./desktop-3p-library";
+import { StoreIO, metadata, storePaths, MAX_DESKTOP_METADATA_ENTRIES, type JsonFile } from "./desktop-remote-store-io";
+import {
+  DesktopStoreError, digest, origin, parseBaseline, parseDisconnect, parseOwner, parseState, projection, projectionHash, mergeProjection,
+  sameOwner, type ArtifactPending, type Baseline, type DesktopRemoteOwner, type Projection, type StoreState,
+} from "./desktop-remote-store-state";
+
+export function currentConnection(owner: DesktopRemoteOwner) {
+  parseOwner(owner);
+  const { config, source } = readConfigDiagnostics();
+  const client = config.client;
+  if (source !== "file" || config.runtimeRole !== "client" || !client
+    || origin(client.serverUrl) !== owner.serverUrl || client.apiKeyId !== owner.apiKeyId || client.connectedAt !== owner.connectedAt) throw new DesktopStoreError("conflict");
+  return { config, client };
+}
+export function serviceGenerations(): string[] {
+  const token = readServiceApiTokenState();
+  const backup = readTokenBackupState();
+  if (token.kind === "unsafe" || backup.kind === "unsafe") throw new DesktopStoreError("unsafe");
+  return [token, backup].flatMap(t => t.kind === "present" ? [t.fingerprint] : []);
+}
+export function profileCredential(value: Record<string, unknown> | null): { origin: string; fingerprint: string } | null {
+  if (!value || value.inferenceProvider !== "gateway" || value.inferenceCredentialKind !== "static") return null;
+  if (typeof value.inferenceGatewayApiKey !== "string") throw new DesktopStoreError("unsafe");
+  return { origin: origin(value.inferenceGatewayBaseUrl), fingerprint: serviceApiTokenFingerprint(value.inferenceGatewayApiKey) };
+}
+export function loadBundle(io: StoreIO) {
+  const paths = storePaths();
+  const stateFile = io.read(paths.state, 64 * 1024, true);
+  const baselineFile = io.read(paths.baseline, 1024 * 1024, true);
+  const state = stateFile ? parseState(stateFile.value) : null;
+  const baseline = baselineFile ? parseBaseline(baselineFile.value) : null;
+  if (!state && baseline) throw new DesktopStoreError("unsafe");
+  if (state) {
+    if (state.home !== paths.home || state.library !== paths.library) throw new DesktopStoreError("unsafe");
+    if (!baseline && state.phase !== "prepared" && state.phase !== "cleaned") throw new DesktopStoreError("unsafe");
+    if (baseline && (baselineFile!.hash !== state.baselineHash || baseline.home !== paths.home
+      || baseline.library !== paths.library || baseline.targetId !== state.targetId || baseline.kind !== state.baselineKind
+      || !sameOwner(baseline.owner, state.owner))) throw new DesktopStoreError("unsafe");
+  }
+  return { paths, stateFile, baselineFile, state, baseline };
+}
+export type Bundle = ReturnType<typeof loadBundle>;
+export function requireOwner(bundle: Bundle, owner: DesktopRemoteOwner): void {
+  if (bundle.state && !sameOwner(bundle.state.owner, owner)) throw new DesktopStoreError("conflict");
+}
+export function selectedFile(io: StoreIO, library: string, meta: Desktop3pMetadata): JsonFile | null {
+  if (!meta.appliedId) return null;
+  const file = io.read(profilePath(library, meta.appliedId));
+  if (!file) throw new DesktopStoreError("unsafe");
+  return file;
+}
+export function locateLegacy(io: StoreIO, owner: DesktopRemoteOwner, known: readonly string[]) {
+  const paths = storePaths();
+  const meta = metadata(io, paths.library);
+  selectedFile(io, paths.library, meta.value);
+  let found: { id: string; file: JsonFile } | null = null;
+  for (const entry of meta.value.entries) {
+    const file = io.read(profilePath(paths.library, entry.id));
+    if (!file) { if (entry.id === meta.value.appliedId) throw new DesktopStoreError("unsafe"); continue; }
+    const credential = profileCredential(file.value);
+    if (!credential || credential.origin !== owner.serverUrl) continue;
+    if (entry.name !== "opencodex" || !known.includes(credential.fingerprint) || found) throw new DesktopStoreError("conflict");
+    found = { id: entry.id, file };
+  }
+  return found;
+}
+export function saveState(io: StoreIO, bundle: Bundle, state: StoreState): void {
+  parseState(state);
+  io.write(bundle.paths.state, state, bundle.stateFile, 64 * 1024);
+  bundle.state = state;
+  bundle.stateFile = io.read(bundle.paths.state, 64 * 1024, true);
+}
+export function establish(io: StoreIO, owner: DesktopRemoteOwner, known: readonly string[], onlyLegacy: boolean): Bundle | null {
+  let bundle = loadBundle(io);
+  const terminalFile = io.read(bundle.paths.disconnect, 64 * 1024, true);
+  const terminal = terminalFile ? parseDisconnect(terminalFile.value) : null;
+  if (terminal?.phase === "complete" && !sameOwner(terminal.owner, owner)) {
+    currentConnection(owner);
+    if (bundle.baselineFile || (bundle.state && (bundle.state.phase !== "cleaned" || !sameOwner(bundle.state.owner, terminal.owner)))) throw new DesktopStoreError("conflict");
+    if (bundle.stateFile) io.remove(bundle.paths.state, bundle.stateFile);
+    io.remove(bundle.paths.disconnect, terminalFile!);
+    bundle = loadBundle(io);
+  }
+  requireOwner(bundle, owner);
+  if (bundle.state && bundle.baseline) return bundle;
+  if (bundle.state?.phase === "cleaned") throw new DesktopStoreError("conflict");
+  const meta = metadata(io, bundle.paths.library);
+  const selected = selectedFile(io, bundle.paths.library, meta.value);
+  const legacy = locateLegacy(io, owner, known);
+  if (onlyLegacy && !legacy && !bundle.state) return null;
+  const entry = meta.value.entries.find(e => e.id === meta.value.appliedId && e.name === "opencodex")
+    ?? meta.value.entries.find(e => e.name === "opencodex");
+  const targetId = bundle.state?.targetId ?? legacy?.id ?? entry?.id ?? randomUUID();
+  if (!meta.value.entries.some(e => e.id === targetId) && meta.value.entries.length >= MAX_DESKTOP_METADATA_ENTRIES) {
+    throw new DesktopStoreError("conflict");
+  }
+  const target = io.read(profilePath(bundle.paths.library, targetId));
+  const credential = profileCredential(target?.value ?? null);
+  if (credential && known.includes(credential.fingerprint) && credential.origin !== owner.serverUrl) throw new DesktopStoreError("conflict");
+  const fallback = credential?.origin === owner.serverUrl;
+  if (fallback && (!known.includes(credential.fingerprint) || (entry?.name !== "opencodex" && legacy?.id !== targetId))) throw new DesktopStoreError("conflict");
+  const priorSelection = meta.value.appliedId && selected && !(fallback && meta.value.appliedId === targetId)
+    ? { id: meta.value.appliedId, hash: selected.hash } : null;
+  const baseline: Baseline = {
+    version: 1, owner, home: bundle.paths.home, library: bundle.paths.library, targetId,
+    kind: fallback ? "standard_fallback" : "known", targetExisted: target !== null,
+    projection: fallback ? {} : projection(target?.value ?? {}), priorSelection,
+  };
+  const baselineHash = digest(JSON.stringify(baseline, null, 2) + "\n");
+  if (bundle.state && (bundle.state.phase !== "prepared" || bundle.state.baselineHash !== baselineHash
+    || bundle.state.lastProjectionHash !== projectionHash(target?.value ?? null))) throw new DesktopStoreError("conflict");
+  if (!bundle.state) saveState(io, bundle, {
+    version: 1, owner, home: bundle.paths.home, library: bundle.paths.library, targetId,
+    baselineRef: "baseline.json", baselineHash, baselineKind: baseline.kind, phase: "prepared",
+    lastProjectionHash: projectionHash(target?.value ?? null), tokenFingerprint: known[0]!,
+  });
+  io.write(bundle.paths.baseline, baseline, null);
+  bundle = loadBundle(io);
+  saveState(io, bundle, { ...bundle.state!, phase: "active" });
+  return bundle;
+}
+
+export function artifact(io: StoreIO, bundle: Bundle, next: Projection, kind: ArtifactPending["kind"], tokenFingerprint: string, desiredSelection?: string | null): void {
+  const state = bundle.state!;
+  const targetPath = profilePath(bundle.paths.library, state.targetId);
+  let current = io.read(targetPath);
+  const meta = metadata(io, bundle.paths.library);
+  const existing = meta.value.entries.find(e => e.id === state.targetId);
+  // An absent row is valid only while a recorded first creation is unfinished.
+  // Keeping the original null projection receipt across apply -> restore proves it.
+  const uncommittedCreation = bundle.baseline?.targetExisted === false && state.lastProjectionHash === projectionHash(null);
+  if ((existing && existing.name !== "opencodex") || (!existing && !uncommittedCreation)) throw new DesktopStoreError("conflict");
+  if (!existing && meta.value.entries.length >= MAX_DESKTOP_METADATA_ENTRIES) throw new DesktopStoreError("conflict");
+  const before = projectionHash(current?.value ?? null), after = projectionHash(next);
+  const selection = meta.value.appliedId ?? null;
+  const pending = state.pending;
+  if (pending) {
+    if (pending.kind !== kind || pending.after !== after || pending.tokenFingerprint !== tokenFingerprint
+      || (before !== pending.before && before !== pending.after)) throw new DesktopStoreError("conflict");
+    if (kind === "apply" && selection !== pending.beforeSelection && selection !== pending.afterSelection) throw new DesktopStoreError("conflict");
+  } else if (before !== state.lastProjectionHash) throw new DesktopStoreError("conflict");
+  const afterSelection = desiredSelection === undefined ? selection : desiredSelection;
+  const settledPhase = kind === "restore" ? "restored" : "active";
+  if (!pending && existing && before === after && afterSelection === selection
+    && state.phase === settledPhase && state.tokenFingerprint === tokenFingerprint) return;
+  if (!pending) saveState(io, bundle, { ...state, pending: { kind, before, after, beforeSelection: selection, afterSelection, tokenFingerprint } });
+  if (before !== after) {
+    io.write(targetPath, mergeProjection(current?.value ?? {}, next), current);
+    current = io.read(targetPath);
+  }
+  // Build from fresh metadata, so unrelated rows/fields are never restored from baseline bytes.
+  const fresh = metadata(io, bundle.paths.library);
+  const freshEntry = fresh.value.entries.find(e => e.id === state.targetId);
+  if ((fresh.value.appliedId ?? null) !== selection || freshEntry?.name !== existing?.name) throw new DesktopStoreError("conflict");
+  if (!existing || afterSelection !== selection) {
+    if (!existing && fresh.value.entries.length >= MAX_DESKTOP_METADATA_ENTRIES) throw new DesktopStoreError("conflict");
+    if (afterSelection && !io.read(profilePath(bundle.paths.library, afterSelection))) throw new DesktopStoreError("unsafe");
+    const entries = existing ? fresh.value.entries : [...fresh.value.entries, { id: state.targetId, name: "opencodex" }];
+    const value = { ...fresh.value, entries, ...(afterSelection ? { appliedId: afterSelection } : {}) };
+    io.write(join(bundle.paths.library, "_meta.json"), value, fresh.file);
+  }
+  const { pending: _pending, ...settled } = bundle.state!;
+  saveState(io, bundle, { ...settled, phase: kind === "restore" ? "restored" : "active", lastProjectionHash: after, tokenFingerprint });
+}
+export function cleanBackup(io: StoreIO, bundle: Bundle, known: readonly string[]): void {
+  const path = `${profilePath(bundle.paths.library, bundle.state!.targetId)}.bak`;
+  const file = io.read(path);
+  if (!file) return;
+  const credential = profileCredential(file.value);
+  if (!credential || credential.origin !== bundle.state!.owner.serverUrl) return;
+  if (!known.includes(credential.fingerprint)) throw new DesktopStoreError("conflict");
+  const foreign = mergeProjection(file.value, {});
+  try {
+    if (Object.keys(foreign).length) io.write(path, foreign, file);
+    else io.remove(path, file);
+  } catch (error) {
+    if (error instanceof DesktopStoreError) throw error;
+    throw new DesktopStoreError("cleanup_pending");
+  }
+}