@bitkyc08/opencodex 2.64.0 → 2.65.0

package/src/claude/desktop-picker-profile.ts

@@ -0,0 +1,302 @@
+/**
+ * Claude Desktop picker mode: the owned egress profile in Desktop's config library.
+ *
+ * The profile is an owned standard row named `opencodex-picker` whose file holds only
+ * `egressProxyUrl`, pointing Desktop at the dedicated picker CONNECT proxy
+ * (`ClaudeInterceptState.pickerProxyPort`). The previous selection is kept in opencodex state
+ * (`<configDir>/claude-picker/profile-state.json`), never in Desktop's `_meta.json`.
+ */
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { withClientLifecycleSync } from "../client/lifecycle-lock";
+import { atomicWriteFile, getConfigDir, withConfigMutationLockSync } from "../config";
+import {
+  DESKTOP_PICKER_ENTRY_NAME,
+  isOwnedDesktopGatewayEntry,
+  parseMetadata,
+  profilePath,
+  resolveDesktop3pConfigLibraryPath,
+  SAFE_DESKTOP_PROFILE_ID,
+  type Desktop3pConfigLibraryOptions,
+  type Desktop3pMetadata,
+  type Desktop3pMetadataEntry,
+} from "./desktop-3p-library";
+
+// Keep a module-local rollback writer. Tests and callers may replace the public config writer to
+// inject a forward-write failure; rollback must still be able to restore the prior bytes.
+const rollbackAtomicWriteFile = atomicWriteFile;
+
+export interface DesktopPickerProfileState { entryId: string; previousAppliedId: string | null }
+export type DesktopPickerProfileInspection =
+  | { kind: "absent" }
+  | { kind: "applied"; entryId: string; proxyUrl: string }
+  | { kind: "not_selected"; entryId: string }
+  | { kind: "unsafe"; reason: string };
+
+export type DesktopPickerProfileOptions = Desktop3pConfigLibraryOptions & { configDir?: string };
+
+const PICKER_DIRECTORY = "claude-picker";
+
+function pickerStatePath(configDir: string): string {
+  return join(configDir, PICKER_DIRECTORY, "profile-state.json");
+}
+
+function metadataPath(libraryPath: string): string {
+  return join(libraryPath, "_meta.json");
+}
+
+function metadataJson(metadata: Desktop3pMetadata): string {
+  return JSON.stringify(metadata, null, 2) + "\n";
+}
+
+function isValidMetadata(metadata: Desktop3pMetadata): boolean {
+  return metadata.entries.every(entry =>
+    entry !== null && typeof entry === "object" && typeof entry.id === "string" && typeof entry.name === "string");
+}
+
+function readPickerState(path: string): DesktopPickerProfileState | null {
+  if (!existsSync(path)) return null;
+  const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<DesktopPickerProfileState>;
+  if (typeof parsed.entryId !== "string" || !SAFE_DESKTOP_PROFILE_ID.test(parsed.entryId)) {
+    throw new Error("picker_profile_state_unreadable");
+  }
+  if (parsed.previousAppliedId !== null
+    && parsed.previousAppliedId !== undefined
+    && (typeof parsed.previousAppliedId !== "string" || !SAFE_DESKTOP_PROFILE_ID.test(parsed.previousAppliedId))) {
+    throw new Error("picker_profile_state_unreadable");
+  }
+  return { entryId: parsed.entryId, previousAppliedId: parsed.previousAppliedId ?? null };
+}
+
+function readFileSnapshot(path: string): { exists: boolean; content?: string } {
+  return existsSync(path) ? { exists: true, content: readFileSync(path, "utf8") } : { exists: false };
+}
+
+function restoreFile(path: string, snapshot: { exists: boolean; content?: string }): void {
+  if (snapshot.exists) {
+    rollbackAtomicWriteFile(path, snapshot.content ?? "");
+  } else if (existsSync(path)) {
+    unlinkSync(path);
+  }
+}
+
+function unlinkIfPresent(path: string): void {
+  if (existsSync(path)) unlinkSync(path);
+}
+
+function pickerEntries(metadata: Desktop3pMetadata): Desktop3pMetadataEntry[] {
+  return metadata.entries.filter(entry => entry.name === DESKTOP_PICKER_ENTRY_NAME);
+}
+
+function pickerEntry(metadata: Desktop3pMetadata): Desktop3pMetadataEntry | undefined {
+  const entries = pickerEntries(metadata);
+  if (entries.length > 1) throw new Error("duplicate_picker_entries");
+  const entry = entries[0];
+  if (entry && !SAFE_DESKTOP_PROFILE_ID.test(entry.id)) throw new Error("unsafe_picker_id");
+  return entry;
+}
+
+function profileObject(path: string): Record<string, unknown> {
+  const parsed = JSON.parse(readFileSync(path, "utf8")) as unknown;
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("picker_profile_unreadable");
+  }
+  return parsed as Record<string, unknown>;
+}
+
+function validPickerProfile(profile: Record<string, unknown>): profile is { egressProxyUrl: string } {
+  const keys = Object.keys(profile);
+  const proxyUrl = profile.egressProxyUrl;
+  const port = typeof proxyUrl === "string" ? /^http:\/\/127\.0\.0\.1:([1-9][0-9]{0,4})$/.exec(proxyUrl)?.[1] : undefined;
+  return keys.length === 1
+    && keys[0] === "egressProxyUrl"
+    && typeof proxyUrl === "string"
+    && port !== undefined
+    && Number(port) <= 65535;
+}
+
+export function pickerEgressUrl(proxyPort: number): string {
+  return `http://127.0.0.1:${proxyPort}`;
+}
+
+type ApplyPickerProfileResult =
+  | { ok: true; changed: boolean; path: string }
+  | { ok: false; reason: "gateway_selected" | "foreign_unreadable" | "write_failed" };
+type RemovePickerProfileResult = { ok: true; changed: boolean } | { ok: false; reason: string; residualPaths?: string[] };
+
+/**
+ * Select the picker profile. Runs under the client lifecycle lock and the config mutation lock,
+ * the same boundary as the gateway writer (src/claude/desktop-3p.ts), so another process cannot
+ * interleave a gateway or catalog write with the selection.
+ */
+export function applyDesktopPickerProfile(options: { proxyPort: number } & DesktopPickerProfileOptions): ApplyPickerProfileResult {
+  try {
+    return withClientLifecycleSync(() => withConfigMutationLockSync(() => applyDesktopPickerProfileLocked(options)));
+  } catch {
+    return { ok: false, reason: "write_failed" };
+  }
+}
+
+/** Remove the picker profile under the same locks as `applyDesktopPickerProfile`. */
+export function removeDesktopPickerProfile(options: DesktopPickerProfileOptions = {}): RemovePickerProfileResult {
+  try {
+    return withClientLifecycleSync(() => withConfigMutationLockSync(() => removeDesktopPickerProfileLocked(options)));
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message : "lock_unavailable" };
+  }
+}
+
+function applyDesktopPickerProfileLocked(options: { proxyPort: number } & DesktopPickerProfileOptions): ApplyPickerProfileResult {
+  const libraryPath = resolveDesktop3pConfigLibraryPath(options);
+  const configDir = options.configDir ?? getConfigDir();
+  const metaPath = metadataPath(libraryPath);
+  let profile = join(libraryPath, "picker.json");
+  try {
+    if (!Number.isInteger(options.proxyPort) || options.proxyPort < 1 || options.proxyPort > 65535) {
+      return { ok: false, reason: "write_failed" };
+    }
+    mkdirSync(libraryPath, { recursive: true, mode: 0o700 });
+    const metadata = parseMetadata(metaPath);
+    if (!isValidMetadata(metadata)) return { ok: false, reason: "foreign_unreadable" };
+    if (metadata.appliedId !== undefined
+      && (typeof metadata.appliedId !== "string" || !SAFE_DESKTOP_PROFILE_ID.test(metadata.appliedId))) {
+      return { ok: false, reason: "foreign_unreadable" };
+    }
+    const selectedId = typeof metadata.appliedId === "string" ? metadata.appliedId : null;
+    const selected = selectedId === null ? undefined : metadata.entries.find(entry => entry.id === selectedId);
+    if (selected && isOwnedDesktopGatewayEntry(selected)) return { ok: false, reason: "gateway_selected" };
+
+    const existing = pickerEntry(metadata);
+    const entryId = existing?.id ?? randomUUID();
+    profile = profilePath(libraryPath, entryId);
+    const target = JSON.stringify({ egressProxyUrl: pickerEgressUrl(options.proxyPort) }) + "\n";
+    const previousStatePath = pickerStatePath(configDir);
+    const alreadySelected = selectedId === entryId;
+    const priorState = readPickerState(previousStatePath);
+    const previousAppliedId = alreadySelected ? priorState?.previousAppliedId ?? null : selectedId;
+    const oldMeta = readFileSnapshot(metaPath);
+    const oldProfile = readFileSnapshot(profile);
+    const backupPath = `${profile}.bak`;
+    const oldBackup = readFileSnapshot(backupPath);
+    const oldState = readFileSnapshot(previousStatePath);
+    const changed = !alreadySelected || !oldProfile.exists || oldProfile.content !== target;
+    if (!changed) return { ok: true, changed: false, path: profile };
+
+    mkdirSync(join(configDir, PICKER_DIRECTORY), { recursive: true, mode: 0o700 });
+    try {
+      // Keep the same backup convention as the existing Desktop writer. It is removed with the
+      // picker row and also gives this transaction a private rollback source.
+      if (oldProfile.exists) atomicWriteFile(backupPath, oldProfile.content ?? "");
+      atomicWriteFile(profile, target);
+      if (!alreadySelected) {
+        atomicWriteFile(previousStatePath, JSON.stringify({ entryId, previousAppliedId }) + "\n");
+      }
+      const entries = existing
+        ? metadata.entries.map(entry => entry.id === entryId ? { ...entry, name: DESKTOP_PICKER_ENTRY_NAME } : entry)
+        : [...metadata.entries, { id: entryId, name: DESKTOP_PICKER_ENTRY_NAME }];
+      atomicWriteFile(metaPath, metadataJson({ ...metadata, appliedId: entryId, entries }));
+    } catch {
+      try {
+        restoreFile(metaPath, oldMeta);
+        restoreFile(profile, oldProfile);
+        restoreFile(backupPath, oldBackup);
+        restoreFile(previousStatePath, oldState);
+      } catch {
+        // The public result remains deliberately opaque; callers can inspect the library.
+      }
+      return { ok: false, reason: "write_failed" };
+    }
+    return { ok: true, changed: true, path: profile };
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return { ok: false, reason: reason === "picker_profile_state_unreadable" || reason === "duplicate_picker_entries" || reason === "unsafe_picker_id" || reason === "picker_profile_unreadable"
+      ? "foreign_unreadable" : "write_failed" };
+  }
+}
+
+function removeDesktopPickerProfileLocked(options: DesktopPickerProfileOptions): RemovePickerProfileResult {
+  const libraryPath = resolveDesktop3pConfigLibraryPath(options);
+  const configDir = options.configDir ?? getConfigDir();
+  const statePath = pickerStatePath(configDir);
+  const metaPath = metadataPath(libraryPath);
+  try {
+    if (!existsSync(metaPath)) {
+      const hadState = existsSync(statePath);
+      unlinkIfPresent(statePath);
+      return { ok: true, changed: hadState };
+    }
+    const metadata = parseMetadata(metaPath);
+    if (!isValidMetadata(metadata)) return { ok: false, reason: "metadata_unreadable" };
+    const picker = pickerEntry(metadata);
+    if (!picker) {
+      const hadState = existsSync(statePath);
+      unlinkIfPresent(statePath);
+      return { ok: true, changed: hadState };
+    }
+    const selected = metadata.appliedId === picker.id;
+    let state: DesktopPickerProfileState | null = null;
+    try { state = readPickerState(statePath); } catch { return { ok: false, reason: "profile_state_unreadable" }; }
+
+    let metadataAfterPivot = metadata;
+    if (selected) {
+      const previous = state?.entryId === picker.id ? state.previousAppliedId : null;
+      const previousExists = previous !== null && previous !== picker.id && metadata.entries.some(entry => entry.id === previous);
+      if (previousExists) {
+        metadataAfterPivot = { ...metadata, appliedId: previous };
+      } else {
+        const standardId = randomUUID();
+        atomicWriteFile(profilePath(libraryPath, standardId), "{}\n");
+        metadataAfterPivot = {
+          ...metadata,
+          appliedId: standardId,
+          entries: [...metadata.entries, { id: standardId, name: "opencodex-standard" }],
+        };
+      }
+      atomicWriteFile(metaPath, metadataJson(metadataAfterPivot));
+    }
+
+    const residualPaths: string[] = [];
+    for (const path of [profilePath(libraryPath, picker.id), `${profilePath(libraryPath, picker.id)}.bak`]) {
+      try { unlinkIfPresent(path); } catch { /* report the path without exposing file contents */ }
+      if (existsSync(path)) residualPaths.push(path);
+    }
+    if (residualPaths.length > 0) {
+      return { ok: false, reason: "cleanup_incomplete", residualPaths };
+    }
+
+    const entries = metadataAfterPivot.entries.filter(entry => entry.id !== picker.id);
+    try {
+      atomicWriteFile(metaPath, metadataJson({ ...metadataAfterPivot, entries }));
+      try { unlinkIfPresent(statePath); } catch { /* residual is reported below */ }
+      if (existsSync(statePath)) return { ok: false, reason: "cleanup_incomplete", residualPaths: [statePath] };
+    } catch {
+      return { ok: false, reason: "write_failed", residualPaths: [metaPath] };
+    }
+    return { ok: true, changed: true };
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message : "cleanup_failed" };
+  }
+}
+
+export function inspectDesktopPickerProfile(options: DesktopPickerProfileOptions = {}): DesktopPickerProfileInspection {
+  const libraryPath = resolveDesktop3pConfigLibraryPath(options);
+  const metaPath = metadataPath(libraryPath);
+  if (!existsSync(metaPath)) return { kind: "absent" };
+  try {
+    const metadata = parseMetadata(metaPath);
+    if (!isValidMetadata(metadata)) return { kind: "unsafe", reason: "metadata_unreadable" };
+    const picker = pickerEntry(metadata);
+    if (!picker) return { kind: "absent" };
+    const path = profilePath(libraryPath, picker.id);
+    if (!existsSync(path)) return { kind: "unsafe", reason: "profile_missing" };
+    const profile = profileObject(path);
+    if (!validPickerProfile(profile)) return { kind: "unsafe", reason: "invalid_profile" };
+    return metadata.appliedId === picker.id
+      ? { kind: "applied", entryId: picker.id, proxyUrl: profile.egressProxyUrl }
+      : { kind: "not_selected", entryId: picker.id };
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : "metadata_unreadable";
+    return { kind: "unsafe", reason };
+  }
+}

package/src/claude/desktop-picker.ts

@@ -0,0 +1,365 @@
+/**
+ * Claude Desktop picker mode: the one server-side controller for every picker mutation.
+ *
+ * While a server runs, enable, disable and Desktop mode transitions run here, serialized by one
+ * lock (devlog/_plan/260924_claude_desktop_picker_mode/030_wp4_picker_activation.md, D11).
+ */
+import type { OcxConfig } from "../types";
+import { claudeDesktopIntegrationEnabled } from "../codex/desired-state";
+import { getConfigDir } from "../config/paths";
+import { readFileSync, existsSync } from "node:fs";
+import { pickerCaCertPath, pickerCaFingerprints, ensurePickerCa, issuePickerLeaf, pickerLeafCertPath } from "./intercept/picker-ca";
+import { inspectPickerTrust, trustPickerCa, untrustPickerCa } from "./intercept/picker-trust";
+import type { PickerRuntime } from "./intercept/picker-runtime";
+import type { PickerTrustState, SecurityRunner } from "./intercept/picker-trust";
+import {
+  applyDesktopPickerProfile,
+  inspectDesktopPickerProfile,
+  removeDesktopPickerProfile,
+  pickerEgressUrl,
+  type DesktopPickerProfileInspection,
+  type DesktopPickerProfileOptions,
+} from "./desktop-picker-profile";
+import { resolveClaudeDesktopMode, observeClaudeDesktopMode } from "./desktop-first-party";
+
+/** Desktop no longer selects the picker profile, so removing the CA's trust cannot strand it. */
+function profileReleased(profile: DesktopPickerProfileInspection): boolean {
+  return profile.kind === "absent" || profile.kind === "not_selected";
+}
+
+export type DesktopPickerReason = "active" | "restart_required" | "unsupported_platform" | "not_first_party"
+  | "integration_off" | "disabled" | "proxy_unavailable" | "mode_not_committed" | "trust_pending"
+  | "trust_declined" | "profile_failed";
+
+export interface DesktopPickerStatus {
+  desired: boolean;
+  supported: boolean;
+  trust: PickerTrustState;
+  profile: DesktopPickerProfileInspection["kind"];
+  listenerReady: boolean;
+  effective: boolean;
+  reason: DesktopPickerReason;
+  models: number;
+  snapshotAt: number | null;
+  lastBootstrapAt: number | null;
+  hint?: string;
+  residual?: string[];
+}
+
+export interface DesktopPickerEnableOptions {
+  persist: boolean;
+  context: "cli-trusted" | "server";
+  callerAddedTrust?: boolean;
+}
+
+export interface DesktopPickerOps {
+  disableLocked(options: { persist: boolean }): Promise<DesktopPickerStatus>;
+  enableLocked(options: DesktopPickerEnableOptions): Promise<DesktopPickerStatus>;
+}
+
+export interface DesktopPickerController {
+  enable(options: DesktopPickerEnableOptions): Promise<DesktopPickerStatus>;
+  disable(options: { persist: boolean }): Promise<DesktopPickerStatus>;
+  transition<T>(fn: (ops: DesktopPickerOps) => Promise<T>): Promise<T>;
+  status(): Promise<DesktopPickerStatus>;
+  busy(): boolean;
+}
+
+export interface DesktopPickerControllerDeps {
+  runtime: PickerRuntime;
+  readConfig: () => OcxConfig;
+  persistPreference: (value: boolean) => boolean;
+  /** Bound picker CONNECT proxy port (Desktop's egress), or null when it is not running. */
+  proxyPort: () => number | null;
+  configDir: string;
+  security?: SecurityRunner;
+  platform?: NodeJS.Platform;
+  applyProfile?: typeof applyDesktopPickerProfile;
+  removeProfile?: typeof removeDesktopPickerProfile;
+  inspectProfile?: typeof inspectDesktopPickerProfile;
+}
+
+function profileOptions(deps: DesktopPickerControllerDeps): DesktopPickerProfileOptions {
+  return { configDir: deps.configDir, ...(deps.platform ? { platform: deps.platform } : {}) };
+}
+
+function statusReasonForConfig(config: OcxConfig, platform: NodeJS.Platform, proxyBound: boolean): DesktopPickerReason {
+  if (platform !== "darwin") return "unsupported_platform";
+  if (resolveClaudeDesktopMode(config, observeClaudeDesktopMode(config)) !== "first-party") return "not_first_party";
+  if (!claudeDesktopIntegrationEnabled(config)) return "integration_off";
+  if (config.claudeCode?.intercept?.picker === false) return "disabled";
+  if (!proxyBound) return "proxy_unavailable";
+  return "restart_required";
+}
+
+function emptyStatus(config: OcxConfig, platform: NodeJS.Platform, reason: DesktopPickerReason): DesktopPickerStatus {
+  return {
+    desired: platform === "darwin"
+      && claudeDesktopIntegrationEnabled(config)
+      && resolveClaudeDesktopMode(config, observeClaudeDesktopMode(config)) === "first-party"
+      && config.claudeCode?.intercept?.picker !== false,
+    supported: platform === "darwin",
+    trust: "unknown",
+    profile: "absent",
+    listenerReady: false,
+    effective: false,
+    reason,
+    models: 0,
+    snapshotAt: null,
+    lastBootstrapAt: null,
+  };
+}
+
+export function createDesktopPickerController(deps: DesktopPickerControllerDeps): DesktopPickerController {
+  const platform = deps.platform ?? process.platform;
+  const applyProfile = deps.applyProfile ?? applyDesktopPickerProfile;
+  const removeProfile = deps.removeProfile ?? removeDesktopPickerProfile;
+  const inspectProfile = deps.inspectProfile ?? inspectDesktopPickerProfile;
+  let pending = 0;
+  // When this process last changed Desktop's egress profile. Desktop reads that profile only at
+  // launch, so a restart is needed only until it has fetched a bootstrap since that change; a plain
+  // opencodex restart changes nothing Desktop reads and never asks for one.
+  let profileChangedAt: number | null = null;
+  let tail = Promise.resolve();
+
+  function inspect(): DesktopPickerProfileInspection {
+    try { return inspectProfile(profileOptions(deps)); }
+    catch { return { kind: "unsafe", reason: "inspection_failed" }; }
+  }
+
+  function runtimeStatus(trustOverride?: PickerTrustState): DesktopPickerStatus {
+    const runtime = deps.runtime.status();
+    const profile = inspect();
+    const profileCurrent = profile.kind === "applied" && profile.proxyUrl === pickerEgressUrl(deps.proxyPort() ?? 0);
+    const trust = trustOverride ?? runtime.trust;
+    const effective = runtime.effective && profileCurrent && trust === "trusted";
+    let reason: DesktopPickerReason;
+    if (platform !== "darwin") reason = "unsupported_platform";
+    else if (!runtime.desired) reason = statusReasonForConfig(deps.readConfig(), platform, deps.proxyPort() !== null);
+    else if (deps.proxyPort() === null) reason = "proxy_unavailable";
+    else if (trust !== "trusted") reason = "trust_pending";
+    else if (!profileCurrent) reason = "profile_failed";
+    else if (!runtime.listenerReady || !runtime.effective) reason = "restart_required";
+    else reason = profileChangedAt !== null && (runtime.lastBootstrapAt === null || runtime.lastBootstrapAt < profileChangedAt)
+      ? "restart_required"
+      : "active";
+    return {
+      desired: runtime.desired,
+      supported: runtime.supported,
+      trust,
+      profile: profile.kind,
+      listenerReady: runtime.listenerReady,
+      effective,
+      reason,
+      models: runtime.models,
+      snapshotAt: runtime.snapshotAt,
+      lastBootstrapAt: runtime.lastBootstrapAt,
+    };
+  }
+
+  async function withLock<T>(fn: () => Promise<T>): Promise<T> {
+    pending += 1;
+    let release!: () => void;
+    const previous = tail;
+    tail = new Promise<void>(resolve => { release = resolve; });
+    await previous;
+    try { return await fn(); }
+    finally { pending -= 1; release(); }
+  }
+
+  async function untrustCurrentCa(): Promise<boolean> {
+    const caPath = pickerCaCertPath(deps.configDir);
+    if (platform !== "darwin" || !existsSync(caPath)) return true;
+    try {
+      const sha1 = pickerCaFingerprints(readFileSync(caPath, "utf8")).sha1;
+      return (await untrustPickerCa(caPath, sha1, deps.security, platform)).ok;
+    } catch { return false; }
+  }
+
+  async function compensateTrust(shouldCompensate: boolean): Promise<boolean> {
+    if (!shouldCompensate) return true;
+    // An already selected owned profile proves that another successful enable still relies on
+    // this CA. Keep its trust even when the current request is refused.
+    if (inspect().kind === "applied") return true;
+    try {
+      const ca = ensurePickerCa(deps.configDir);
+      const result = await untrustPickerCa(
+        pickerCaCertPath(deps.configDir), pickerCaFingerprints(ca.certPem).sha1, deps.security, platform,
+      );
+      return result.ok;
+    } catch { return false; }
+  }
+
+  function withTrustFailure(status: DesktopPickerStatus, trustFailed: boolean): DesktopPickerStatus {
+    if (!trustFailed) return status;
+    return { ...status, effective: false, hint: "ocx claude desktop picker off", residual: [...new Set([...(status.residual ?? []), "trust"])] };
+  }
+
+  async function enableLocked(options: DesktopPickerEnableOptions): Promise<DesktopPickerStatus> {
+    let trustedByAttempt = false;
+    let observedTrust: PickerTrustState | undefined;
+    const refuse = async (reason: DesktopPickerReason): Promise<DesktopPickerStatus> => {
+      const trustFailed = options.callerAddedTrust === true && !(await compensateTrust(true));
+      return withTrustFailure({ ...runtimeStatus(observedTrust), reason }, trustFailed);
+    };
+    const check = (config: OcxConfig, includePreference: boolean): DesktopPickerReason | null => {
+      if (platform !== "darwin") return "unsupported_platform";
+      if (resolveClaudeDesktopMode(config, observeClaudeDesktopMode(config)) !== "first-party") return "mode_not_committed";
+      if (!claudeDesktopIntegrationEnabled(config)) return "integration_off";
+      if (includePreference && config.claudeCode?.intercept?.picker === false) return "disabled";
+      if (deps.proxyPort() === null) return "proxy_unavailable";
+      return null;
+    };
+
+    const first = check(deps.readConfig(), false);
+    if (first) return refuse(first);
+    if (options.persist) {
+      try {
+        if (!deps.persistPreference(true)) return refuse("mode_not_committed");
+      } catch { return refuse("mode_not_committed"); }
+    }
+    const second = check(deps.readConfig(), true);
+    if (second) return refuse(second);
+
+    let caPath: string;
+    let caSha1: string;
+    try {
+      const ca = ensurePickerCa(deps.configDir);
+      issuePickerLeaf(ca, deps.configDir);
+      caPath = pickerCaCertPath(deps.configDir);
+      caSha1 = pickerCaFingerprints(ca.certPem).sha1;
+      let trust = await inspectPickerTrust(pickerLeafCertPath(deps.configDir), caSha1, deps.security, platform);
+      observedTrust = trust;
+      if (trust !== "trusted" && options.context === "server") {
+        const added = await trustPickerCa(caPath, deps.security, platform);
+        trustedByAttempt = added.ok;
+        trust = await inspectPickerTrust(pickerLeafCertPath(deps.configDir), caSha1, deps.security, platform);
+        observedTrust = trust;
+      }
+      if (trust !== "trusted") {
+        const compensationFailed = (trustedByAttempt || options.callerAddedTrust === true) && !(await compensateTrust(true));
+        const result = withTrustFailure({ ...runtimeStatus(trust), reason: options.context === "cli-trusted" ? "trust_declined" : "trust_pending", hint: options.context === "cli-trusted" ? undefined : "ocx claude desktop picker trust" }, compensationFailed);
+        return result;
+      }
+      const afterTrust = check(deps.readConfig(), true);
+      if (afterTrust) {
+        const compensationFailed = (trustedByAttempt || options.callerAddedTrust === true) && !(await compensateTrust(true));
+        return withTrustFailure({ ...runtimeStatus(trust), reason: afterTrust }, compensationFailed);
+      }
+      const proxyPort = deps.proxyPort();
+      if (proxyPort === null) {
+        const compensationFailed = (trustedByAttempt || options.callerAddedTrust === true) && !(await compensateTrust(true));
+        return withTrustFailure({ ...runtimeStatus(trust), reason: "proxy_unavailable" }, compensationFailed);
+      }
+      const applied = applyProfile({ ...profileOptions(deps), proxyPort });
+      if (!applied.ok) {
+        const compensationFailed = (trustedByAttempt || options.callerAddedTrust === true) && !(await compensateTrust(true));
+        return withTrustFailure({ ...runtimeStatus(trust), reason: "profile_failed", residual: ["profile"] }, compensationFailed);
+      }
+      if (applied.changed) profileChangedAt = Date.now();
+      await deps.runtime.rearm();
+      const result = runtimeStatus();
+      if (result.reason === "active") return result;
+      return { ...result, reason: "restart_required" };
+    } catch {
+      const compensationFailed = (trustedByAttempt || options.callerAddedTrust === true) && !(await compensateTrust(true));
+      return withTrustFailure({ ...runtimeStatus(observedTrust), reason: "profile_failed" }, compensationFailed);
+    }
+  }
+
+  async function disableLocked(options: { persist: boolean }): Promise<DesktopPickerStatus> {
+    const residual: string[] = [];
+    try { deps.runtime.disarm(); } catch { residual.push("runtime"); }
+    if (options.persist) {
+      try { if (!deps.persistPreference(false)) residual.push("preference"); }
+      catch { residual.push("preference"); }
+    }
+    try {
+      const removed = removeProfile(profileOptions(deps));
+      if (!removed.ok) residual.push("profile");
+    } catch { residual.push("profile"); }
+    // Trust goes only once Desktop no longer selects the picker profile: a selected profile without
+    // trust pins Desktop to a proxy whose certificate it rejects. Disarmed, the proxy only tunnels.
+    let trustRemoved = false;
+    if (profileReleased(inspect())) {
+      trustRemoved = await untrustCurrentCa();
+      if (!trustRemoved) residual.push("trust");
+    } else if (!residual.includes("profile")) {
+      residual.push("profile");
+    }
+    let trustAfter = deps.runtime.status().trust;
+    try { trustAfter = await deps.runtime.refreshTrust(); } catch { /* status below retains the runtime's cached trust */ }
+    const result = runtimeStatus(trustRemoved ? trustAfter === "trusted" ? "trusted" : "untrusted" : trustAfter);
+    const profile = inspect();
+    const trust = result.trust;
+    const effective = result.effective && profile.kind === "applied" && trust === "trusted";
+    const reason = residual.length > 0
+      ? (residual.includes("trust") ? "trust_pending" : "profile_failed")
+      : configPickerDisabled(deps.readConfig()) ? "disabled" : profile.kind === "applied" ? "profile_failed" : "restart_required";
+    return { ...result, effective, reason, ...(residual.length > 0 ? { residual } : {}) };
+  }
+
+  function configPickerDisabled(config: OcxConfig): boolean { return config.claudeCode?.intercept?.picker === false; }
+  const ops: DesktopPickerOps = { disableLocked, enableLocked };
+  return {
+    enable: options => withLock(() => enableLocked(options)),
+    disable: options => withLock(() => disableLocked(options)),
+    transition: fn => withLock(() => fn(ops)),
+    status: async () => runtimeStatus(),
+    busy: () => pending > 0,
+  };
+}
+
+export async function removeDesktopPickerArtifacts(options: { configDir?: string; security?: SecurityRunner; platform?: NodeJS.Platform } = {}): Promise<{ ok: boolean; residual?: string[] }> {
+  const configDir = options.configDir ?? getConfigDir();
+  const platform = options.platform ?? process.platform;
+  const residual: string[] = [];
+  try {
+    const removed = removeDesktopPickerProfile({ configDir, ...(platform ? { platform } : {}) });
+    if (!removed.ok) residual.push("profile");
+  } catch { residual.push("profile"); }
+  let released = false;
+  try { released = profileReleased(inspectDesktopPickerProfile({ configDir, ...(platform ? { platform } : {}) })); } catch { /* unknown: keep trust */ }
+  if (!released) {
+    // Still selected (or unknown): keep trust so Desktop is not pinned to a CA it rejects.
+    if (!residual.includes("profile")) residual.push("profile");
+    return { ok: false, residual };
+  }
+  const caPath = pickerCaCertPath(configDir);
+  if (platform === "darwin" && existsSync(caPath)) {
+    try {
+      const sha1 = pickerCaFingerprints(readFileSync(caPath, "utf8")).sha1;
+      if (!(await untrustPickerCa(caPath, sha1, options.security, platform)).ok) residual.push("trust");
+    } catch { residual.push("trust"); }
+  }
+  return residual.length ? { ok: false, residual } : { ok: true };
+}
+
+/** Static status when no controller runs in this process (intercept disabled, client role, bind failure). */
+export function offlinePickerStatus(config: OcxConfig, platform: NodeJS.Platform = process.platform): DesktopPickerStatus {
+  const reason = statusReasonForConfig(config, platform, false);
+  return emptyStatus(config, platform, reason);
+}
+
+/**
+ * Run a Desktop mode transition under the controller lock, or, with no controller, with offline
+ * ops: disableLocked removes leftover picker artifacts; enableLocked reports proxy_unavailable.
+ */
+export function runDesktopTransition<T>(
+  controller: DesktopPickerController | null,
+  fn: (ops: DesktopPickerOps) => Promise<T>,
+  offline?: { configDir?: string; config: OcxConfig; security?: SecurityRunner; platform?: NodeJS.Platform },
+): Promise<T> {
+  if (controller) return controller.transition(fn);
+  const fallback = offline ?? { config: {} as OcxConfig };
+  const platform = fallback.platform ?? process.platform;
+  const ops: DesktopPickerOps = {
+    disableLocked: async () => {
+      const cleanup = await removeDesktopPickerArtifacts({ configDir: fallback.configDir, security: fallback.security, platform });
+      const status = offlinePickerStatus(fallback.config, platform);
+      return cleanup.ok ? status : { ...status, effective: false, reason: "profile_failed", residual: cleanup.residual };
+    },
+    enableLocked: async () => ({ ...offlinePickerStatus(fallback.config, platform), reason: "proxy_unavailable" }),
+  };
+  return fn(ops);
+}