@bitkyc08/opencodex 2.64.0-preview.20260923 → 2.65.0-preview.20260925

package/src/claude/intercept/picker-runtime.ts

@@ -0,0 +1,330 @@
+/**
+ * Claude Desktop picker mode: when to terminate claude.ai, and the pieces that do it.
+ *
+ * Picker mode lists opencodex models by name in Desktop's Code-tab picker while Desktop stays
+ * first-party. Desktop's own egress profile (wp4) points the app at the intercept CONNECT proxy;
+ * for every tunnel the proxy asks `selectTunnel`, and only `claude.ai:443` can ever come back as
+ * `intercept`. Everything else, and claude.ai whenever any condition fails, is a blind tunnel.
+ *
+ * The decision is cached by `refresh()` and only read by `selectTunnel`, so a CONNECT never
+ * waits on the keychain or the catalog. Arming needs all of: macOS, the persisted resolved mode is
+ * first-party (observation-aware, so a pre-field first-party install counts), Desktop intent on,
+ * `claudeCode.intercept.picker !== false`, the disarm latch clear, the picker listener up and the
+ * current picker CA trusted in the login keychain. `disarm()` stops terminating immediately and
+ * latches; only the picker controller's owner-only `rearm()` clears the latch.
+ */
+import { join } from "node:path";
+import type { OcxConfig } from "../../types";
+import type { ClaudeDesktopMode } from "../desktop-first-party";
+import type { TunnelDecision } from "./connect-proxy";
+import type { PemKeyPair } from "./local-ca";
+import { PICKER_HOST, ensurePickerCa, issuePickerLeaf, pickerCaFingerprints, pickerLeafCertPath, pickerStateDir, type PickerCa } from "./picker-ca";
+import { startPickerListener, type PickerListenerHandle } from "./picker-listener";
+import { createPickerModelSnapshot, type PickerModelSnapshot, type PickerRouteInput } from "./picker-models";
+import { inspectPickerTrust, type PickerTrustState, type SecurityRunner } from "./picker-trust";
+
+export type TunnelChoice = TunnelDecision;
+
+/** A claude.ai CONNECT that arrives before the first refresh waits at most this long. */
+export const PICKER_STARTUP_WAIT_MS = 3_000;
+export const PICKER_REFRESH_INTERVAL_MS = 60_000;
+export const PICKER_TRUST_TTL_MS = 30_000;
+/** Discovery for the picker list is refreshed in the background once the snapshot is this old. */
+export const PICKER_MODELS_MAX_AGE_MS = 5 * 60_000;
+export const PICKER_MODELS_FILE = "models.json";
+
+export type PickerRuntimeReason =
+  | "active"
+  | "starting"
+  | "unsupported_platform"
+  | "not_desired"
+  | "disarmed"
+  | "busy"
+  | "trust_untrusted"
+  | "trust_unknown"
+  | "listener_failed"
+  | "refresh_failed"
+  | "stopped";
+
+export interface PickerRuntimeStatus {
+  desired: boolean;
+  supported: boolean;
+  trust: PickerTrustState;
+  listenerReady: boolean;
+  effective: boolean;
+  latched: boolean;
+  reason: PickerRuntimeReason;
+  models: number;
+  snapshotAt: number | null;
+  /** Last time Desktop fetched a bootstrap through the picker listener (null = not since start). */
+  lastBootstrapAt: number | null;
+}
+
+export interface PickerRuntime {
+  selectTunnel(host: string, port: number): TunnelChoice | null | Promise<TunnelChoice | null>;
+  refreshTrust(): Promise<PickerTrustState>;
+  refresh(): Promise<void>;
+  disarm(): void;
+  rearm(): Promise<void>;
+  ensureStarted(): Promise<void>;
+  start(): Promise<void>;
+  readonly ready: Promise<void>;
+  status(): PickerRuntimeStatus;
+  stop(): Promise<void>;
+}
+
+export interface CreatePickerRuntimeOptions {
+  config: OcxConfig;
+  /** Persisted config for every decision; defaults to `loadConfig`. */
+  readConfig?: () => OcxConfig;
+  /** True while the picker controller holds its lock; refresh() then never arms. */
+  isBusy?: () => boolean;
+  configDir: string;
+  loadRoutes: () => Promise<PickerRouteInput>;
+  security?: SecurityRunner;
+  platform?: NodeJS.Platform;
+  now?: () => number;
+  trustTtlMs?: number;
+  startupWaitMs?: number;
+  refreshIntervalMs?: number;
+  /** Test seam: the observation-aware resolved Desktop mode for a config. */
+  resolveMode?: (config: OcxConfig) => ClaudeDesktopMode | Promise<ClaudeDesktopMode>;
+  /** Test seam: the claude.ai terminator. */
+  startListener?: typeof startPickerListener;
+  log?: (line: string) => void;
+}
+
+/**
+ * Whether picker mode should run for this persisted config and resolved mode. Desktop intent uses
+ * the durable-intent rule of `claudeDesktopIntegrationEnabled` (src/codex/desired-state.ts): only an
+ * explicit `false` turns it off. The picker preference is the same: on unless explicitly false.
+ */
+export function pickerDesired(
+  config: Pick<OcxConfig, "claudeCode" | "clientIntegrations">,
+  mode: ClaudeDesktopMode,
+  platform: NodeJS.Platform = process.platform,
+): boolean {
+  return platform === "darwin"
+    && config.clientIntegrations?.["claude-desktop"] !== false
+    && mode === "first-party"
+    && config.claudeCode?.intercept?.picker !== false;
+}
+
+async function defaultResolveMode(config: OcxConfig): Promise<ClaudeDesktopMode> {
+  // Dynamic: desktop-first-party imports intercept/runtime, which imports this module.
+  const { observeClaudeDesktopMode, resolveClaudeDesktopMode } = await import("../desktop-first-party");
+  return resolveClaudeDesktopMode(config, observeClaudeDesktopMode(config));
+}
+
+async function defaultReadConfig(): Promise<() => OcxConfig> {
+  const { loadConfig } = await import("../../config");
+  return loadConfig;
+}
+
+export function createPickerRuntime(options: CreatePickerRuntimeOptions): PickerRuntime {
+  const platform = options.platform ?? process.platform;
+  const now = options.now ?? Date.now;
+  const trustTtlMs = options.trustTtlMs ?? PICKER_TRUST_TTL_MS;
+  const startupWaitMs = options.startupWaitMs ?? PICKER_STARTUP_WAIT_MS;
+  const refreshIntervalMs = options.refreshIntervalMs ?? PICKER_REFRESH_INTERVAL_MS;
+  const resolveMode = options.resolveMode ?? defaultResolveMode;
+  const startListener = options.startListener ?? startPickerListener;
+  const log = options.log ?? (() => {});
+
+  let desired = false;
+  let armed = false;
+  let latched = false;
+  let stopped = false;
+  let started = false;
+  let firstRefreshDone = false;
+  let generation = 0;
+  let reason: PickerRuntimeReason = "starting";
+  let trust: PickerTrustState = "unknown";
+  let trustCheckedAt = -Infinity;
+  let trustFor: string | null = null;
+  let ca: PickerCa | null = null;
+  let caSha1: string | null = null;
+  let leaf: PemKeyPair | null = null;
+  let snapshot: PickerModelSnapshot | null = null;
+  let listener: PickerListenerHandle | null = null;
+  let listenerPromise: Promise<PickerListenerHandle> | null = null;
+  let lastBootstrapAt: number | null = null;
+  let interval: ReturnType<typeof setInterval> | null = null;
+  let readConfig: (() => OcxConfig) | null = options.readConfig ?? null;
+  let resolveReady!: () => void;
+  const ready = new Promise<void>(resolve => { resolveReady = resolve; });
+
+  function closeListener(): void {
+    const pending = listenerPromise;
+    listenerPromise = null;
+    listener = null;
+    if (pending) void pending.then(handle => handle.close()).catch(() => {});
+  }
+
+  function ensureMaterial(): { ca: PickerCa; leaf: PemKeyPair; sha1: string } {
+    if (!ca || !leaf || !caSha1) {
+      ca = ensurePickerCa(options.configDir);
+      leaf = issuePickerLeaf(ca, options.configDir);
+      caSha1 = pickerCaFingerprints(ca.certPem).sha1;
+    }
+    return { ca, leaf, sha1: caSha1 };
+  }
+
+  function ensureSnapshot(): PickerModelSnapshot {
+    snapshot ??= createPickerModelSnapshot(options.loadRoutes, join(pickerStateDir(options.configDir), PICKER_MODELS_FILE));
+    return snapshot;
+  }
+
+  async function inspectTrust(force: boolean): Promise<PickerTrustState> {
+    const { sha1 } = ensureMaterial();
+    if (!force && trustFor === sha1 && now() - trustCheckedAt < trustTtlMs) return trust;
+    trust = await inspectPickerTrust(pickerLeafCertPath(options.configDir), sha1, options.security, platform);
+    trustFor = sha1;
+    trustCheckedAt = now();
+    return trust;
+  }
+
+  /** CA, leaf, snapshot and listener. Resolves false when a disarm overtook it. */
+  async function startPieces(gen: number): Promise<boolean> {
+    const material = ensureMaterial();
+    ensureSnapshot().refreshIfStale(PICKER_MODELS_MAX_AGE_MS);
+    if (!listenerPromise) {
+      const current = startListener({
+        leaf: material.leaf,
+        models: () => {
+          lastBootstrapAt = now();
+          return ensureSnapshot().current()?.models ?? [];
+        },
+        log,
+      });
+      listenerPromise = current;
+      current.catch(() => { if (listenerPromise === current) listenerPromise = null; });
+    }
+    const pending = listenerPromise;
+    const handle = await pending;
+    if (gen !== generation || latched || stopped || listenerPromise !== pending) return false;
+    listener = handle;
+    return true;
+  }
+
+  async function evaluate(bypassBusy: boolean, forceTrust: boolean): Promise<void> {
+    const gen = generation;
+    if (stopped) return;
+    try {
+      readConfig ??= await defaultReadConfig();
+      const fresh = readConfig();
+      const mode = await resolveMode(fresh);
+      if (gen !== generation || stopped) return;
+      desired = pickerDesired(fresh, mode, platform);
+      if (!desired || latched) {
+        armed = false;
+        reason = platform !== "darwin" ? "unsupported_platform" : latched ? "disarmed" : "not_desired";
+        closeListener();
+        return;
+      }
+      if (!bypassBusy && options.isBusy?.()) {
+        reason = armed ? reason : "busy";
+        return;
+      }
+      let up: boolean;
+      try {
+        up = await startPieces(gen);
+      } catch {
+        armed = false;
+        reason = "listener_failed";
+        return;
+      }
+      if (!up) return;
+      const state = await inspectTrust(forceTrust);
+      if (gen !== generation || latched || stopped) return;
+      armed = state === "trusted" && listener !== null;
+      reason = armed ? "active" : state === "unknown" ? "trust_unknown" : state === "unsupported" ? "unsupported_platform" : "trust_untrusted";
+    } catch (error) {
+      if (gen !== generation) return;
+      armed = false;
+      reason = "refresh_failed";
+      log(`picker refresh failed (${error instanceof Error ? error.name : "error"})`);
+    }
+  }
+
+  function currentChoice(): TunnelChoice {
+    return armed && listener && !latched && !stopped
+      ? { kind: "intercept", port: listener.port }
+      : { kind: "blind" };
+  }
+
+  return {
+    ready,
+    selectTunnel(host, port) {
+      if (host.toLowerCase() !== PICKER_HOST || port !== 443) return null;
+      if (!started || firstRefreshDone || stopped) return currentChoice();
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const timeout = new Promise<"timeout">(resolve => { timer = setTimeout(() => resolve("timeout"), startupWaitMs); });
+      return Promise.race([ready.then(() => "ready" as const), timeout]).then(outcome => {
+        clearTimeout(timer);
+        return outcome === "ready" ? currentChoice() : { kind: "blind" as const };
+      });
+    },
+    async refreshTrust() {
+      return inspectTrust(true);
+    },
+    async refresh() {
+      await evaluate(false, false);
+    },
+    disarm() {
+      latched = true;
+      armed = false;
+      generation += 1;
+      reason = "disarmed";
+      closeListener();
+    },
+    async rearm() {
+      if (stopped) return;
+      latched = false;
+      await evaluate(true, true);
+    },
+    async ensureStarted() {
+      if (latched || stopped) return;
+      await startPieces(generation);
+    },
+    start() {
+      if (started) return ready;
+      started = true;
+      void evaluate(false, false).finally(() => {
+        firstRefreshDone = true;
+        resolveReady();
+      });
+      interval = setInterval(() => { void evaluate(false, false); }, refreshIntervalMs);
+      (interval as { unref?: () => void }).unref?.();
+      return ready;
+    },
+    status() {
+      const current = snapshot?.current() ?? null;
+      return {
+        desired,
+        supported: platform === "darwin",
+        trust,
+        listenerReady: listener !== null,
+        effective: armed && listener !== null && !latched && !stopped,
+        latched,
+        reason: stopped ? "stopped" : reason,
+        models: current?.models.length ?? 0,
+        snapshotAt: current?.builtAt ?? null,
+        lastBootstrapAt,
+      };
+    },
+    async stop() {
+      stopped = true;
+      armed = false;
+      generation += 1;
+      if (interval) clearInterval(interval);
+      interval = null;
+      firstRefreshDone = true;
+      resolveReady();
+      const pending = listenerPromise;
+      listenerPromise = null;
+      listener = null;
+      if (pending) await pending.then(handle => handle.close(), () => {});
+    },
+  };
+}

package/src/claude/intercept/picker-trust.ts

@@ -0,0 +1,125 @@
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { PICKER_CA_COMMON_NAME, PICKER_HOST } from "./picker-ca";
+
+/** Trust is scoped to the current root fingerprint and a verified persisted leaf. */
+export type PickerTrustState = "trusted" | "untrusted" | "unsupported" | "unknown";
+export interface SecurityResult { code: number | null; stdout: string; stderr: string }
+export type SecurityRunner = (args: readonly string[]) => Promise<SecurityResult>;
+
+export const defaultSecurityRunner: SecurityRunner = async args => {
+  const child = Bun.spawn(["/usr/bin/security", ...args], { stdout: "pipe", stderr: "pipe" });
+  const [stdout, stderr, code] = await Promise.all([
+    new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited,
+  ]);
+  return { code, stdout, stderr };
+};
+
+export function loginKeychainPath(home = homedir()): string {
+  return join(home, "Library", "Keychains", "login.keychain-db");
+}
+
+function hasFingerprint(output: string, expected: string): boolean {
+  const normalized = expected.replace(/:/g, "").toUpperCase();
+  if (!/^[0-9A-F]{40}$/.test(normalized)) return false;
+  return output.split(/\r?\n/).some(line => {
+    const match = /^SHA-1 hash:\s*([0-9a-fA-F:]{40,59})\s*$/.exec(line.trim());
+    return !!match && match[1]!.replace(/:/g, "").toUpperCase() === normalized;
+  });
+}
+
+/**
+ * Whether the current CA's user trust settings carry a policy string (a host scope such as the
+ * `-s claude.ai` earlier builds used). verify-cert honours those, but Chromium skips them, so
+ * Desktop would reject the picker leaf; the CA then counts as untrusted and trust is added again,
+ * which replaces the setting. `null` when the settings cannot be read; the caller then reports
+ * `unknown`, because arming on a setting Chromium skips would cut Desktop off from claude.ai.
+ */
+async function hostScopedTrust(caSha1: string, run: SecurityRunner): Promise<boolean | null> {
+  let dir: string | undefined;
+  try {
+    dir = mkdtempSync(join(tmpdir(), "ocx-picker-trust-"));
+    const file = join(dir, "trust-settings.plist");
+    if ((await run(["trust-settings-export", file])).code !== 0) return null;
+    const xml = readFileSync(file, "utf8");
+    const at = xml.indexOf(`<key>${caSha1.replace(/:/g, "").toUpperCase()}</key>`);
+    if (at < 0) return false;
+    // The entry's trustSettings array holds flat dictionaries, so its first </array> ends it.
+    const end = xml.indexOf("</array>", at);
+    return xml.slice(at, end < 0 ? undefined : end).includes("<key>kSecTrustSettingsPolicyString</key>");
+  } catch { // no-excuse-ok: catch -- unreadable trust settings are no evidence of a host scope.
+    return null;
+  } finally {
+    if (dir) rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+export async function inspectPickerTrust(
+  leafPath: string,
+  caSha1: string,
+  run: SecurityRunner = defaultSecurityRunner,
+  platform: NodeJS.Platform = process.platform,
+): Promise<PickerTrustState> {
+  if (platform !== "darwin") return "unsupported";
+  const keychain = loginKeychainPath();
+  try {
+    const found = await run(["find-certificate", "-a", "-Z", "-c", PICKER_CA_COMMON_NAME, keychain]);
+    if (found.code === 1) return "untrusted";
+    if (found.code !== 0) return "unknown";
+    if (!hasFingerprint(found.stdout, caSha1)) return "untrusted";
+    const verified = await run(["verify-cert", "-q", "-L", "-c", leafPath,
+      "-p", "ssl", "-n", PICKER_HOST, "-k", keychain]);
+    if (verified.code === 0) {
+      const scoped = await hostScopedTrust(caSha1, run);
+      return scoped === null ? "unknown" : scoped ? "untrusted" : "trusted";
+    }
+    return verified.code === 1 ? "untrusted" : "unknown";
+  } catch { // no-excuse-ok: catch -- OS command unavailable or denied; never claim trust.
+    return "unknown";
+  }
+}
+
+export async function trustPickerCa(
+  caPath: string,
+  run: SecurityRunner = defaultSecurityRunner,
+  platform: NodeJS.Platform = process.platform,
+): Promise<{ ok: boolean; reason?: "unsupported" | "declined_or_failed" }> {
+  if (platform !== "darwin") return { ok: false, reason: "unsupported" };
+  try {
+    // No `-s <host>` policy string: Chromium (Claude Desktop) skips trust settings that carry one,
+    // so a host-scoped setting leaves Desktop rejecting the picker leaf. The CA's critical name
+    // constraints already limit it to claude.ai; macOS verify-cert rejects any other name.
+    const result = await run(["add-trusted-cert", "-r", "trustRoot", "-p", "ssl",
+      "-k", loginKeychainPath(), caPath]);
+    return result.code === 0 ? { ok: true } : { ok: false, reason: "declined_or_failed" };
+  } catch { // no-excuse-ok: catch -- user decline and command failure share a safe result.
+    return { ok: false, reason: "declined_or_failed" };
+  }
+}
+
+export async function untrustPickerCa(
+  caPath: string,
+  fingerprintSha1: string,
+  run: SecurityRunner = defaultSecurityRunner,
+  platform: NodeJS.Platform = process.platform,
+): Promise<{ ok: boolean }> {
+  if (platform !== "darwin") return { ok: false };
+  const keychain = loginKeychainPath();
+  // Listed means the current picker CA is in the login keychain; unlisted means nothing to remove,
+  // which is success, so a machine that never trusted it never sees a keychain prompt for it.
+  const listed = async (): Promise<boolean> => {
+    const found = await run(["find-certificate", "-a", "-Z", "-c", PICKER_CA_COMMON_NAME, keychain]);
+    if (found.code === 1) return false;
+    if (found.code !== 0) throw new Error("find-certificate failed");
+    return hasFingerprint(found.stdout, fingerprintSha1);
+  };
+  try {
+    if (!(await listed())) return { ok: true };
+    const removed = await run(["remove-trusted-cert", caPath]);
+    const deleted = await run(["delete-certificate", "-Z", fingerprintSha1, keychain]);
+    return { ok: removed.code === 0 && deleted.code === 0 && !(await listed()) };
+  } catch { // no-excuse-ok: catch -- failed removal must be visible to the caller.
+    return { ok: false };
+  }
+}

package/src/claude/intercept/runtime.ts

@@ -1,9 +1,13 @@
 import type { Server } from "bun";
 import type { OcxConfig } from "../../types";
 import { getConfigDir } from "../../config/paths";
-import { CLAUDE_INTERCEPT_HOSTS, startConnectProxy, type ConnectProxyHandle } from "./connect-proxy";
+import type { DesktopPickerController } from "../desktop-picker";
+import { CLAUDE_INTERCEPT_HOSTS, isBrowserConnect, startConnectProxy, type ConnectProxyHandle } from "./connect-proxy";
 import { startClaudeInterceptListener } from "./listener";
 import { claudeInterceptCaCertPath, ensureLocalInterceptCaForStartup, issueLocalInterceptLeaf } from "./local-ca";
+import type { PickerRouteInput } from "./picker-models";
+import { createPickerRuntime, type CreatePickerRuntimeOptions, type PickerRuntime } from "./picker-runtime";
+import type { SecurityRunner } from "./picker-trust";
 
 /**
  * Lifecycle for the Claude intercept pair (CONNECT proxy + TLS listener).
@@ -11,6 +15,13 @@ import { claudeInterceptCaCertPath, ensureLocalInterceptCaForStartup, issueLocal
  * Started next to the public listener, torn down with it. The proxy port is derived from the
  * public port unless configured, because Claude Code's `settings.json` must name a port that
  * survives restarts; the TLS listener is ephemeral and only ever reached through the proxy.
+ *
+ * Picker mode adds a second CONNECT proxy on the next port, used as Claude Desktop's pinned egress
+ * proxy. Desktop also hands that proxy to the Claude Code processes it spawns, so the choice is per
+ * client: Claude Code (no User-Agent on CONNECT) trusts only the intercept CA and gets the
+ * api.anthropic.com intercept and nothing else; the app itself (a browser User-Agent) trusts only
+ * the login keychain and never meets the api.anthropic.com intercept, and only its claude.ai
+ * tunnels may be terminated by the picker runtime (src/claude/intercept/picker-runtime.ts).
  */
 
 export const CLAUDE_INTERCEPT_PORT_OFFSET = 100;
@@ -27,9 +38,17 @@ export function claudeInterceptProxyPort(config: Pick<OcxConfig, "claudeCode">,
   return publicPort + CLAUDE_INTERCEPT_PORT_OFFSET;
 }
 
+/** Desktop's egress proxy for picker mode: the port after the intercept proxy (before it at 65535). */
+export function claudePickerProxyPort(config: Pick<OcxConfig, "claudeCode">, publicPort: number): number {
+  const interceptPort = claudeInterceptProxyPort(config, publicPort);
+  return interceptPort < 65535 ? interceptPort + 1 : interceptPort - 1;
+}
+
 export interface ClaudeInterceptState {
   proxyPort: number;
   caCertPath: string;
+  /** Desktop egress proxy for picker mode; null when the picker is not wired or could not bind. */
+  pickerProxyPort: number | null;
 }
 
 export interface ClaudeInterceptHandle<T = undefined> extends ClaudeInterceptState {
@@ -38,12 +57,44 @@ export interface ClaudeInterceptHandle<T = undefined> extends ClaudeInterceptSta
 }
 
 let activeState: ClaudeInterceptState | null = null;
+let activePicker: PickerRuntime | null = null;
+let activeController: DesktopPickerController | null = null;
 
 /** Live intercept endpoints, or `null` when the pair is not running in this process. */
 export function getClaudeInterceptState(): ClaudeInterceptState | null {
   return activeState;
 }
 
+/** The running picker runtime, or `null` when picker mode is not wired in this process. */
+export function getClaudePickerRuntime(): PickerRuntime | null {
+  return activePicker;
+}
+
+/** The picker controller that owns every picker mutation while this server runs, or `null`. */
+export function getClaudePickerController(): DesktopPickerController | null {
+  return activeController;
+}
+
+/**
+ * Persist `claudeCode.intercept.picker` through the field-scoped writer and adopt the committed
+ * subtree into the live config, so a later whole-config save neither reverts nor re-applies it.
+ */
+export async function createPickerPreferenceWriter(live: OcxConfig): Promise<(value: boolean) => boolean> {
+  const { adoptPersistedClaudeCode, mutatePersistedConfig } = await import("../../config");
+  return value => {
+    const outcome = mutatePersistedConfig(persisted => {
+      const claudeCode = persisted.claudeCode ?? {};
+      const intercept = claudeCode.intercept ?? {};
+      if (intercept.picker === value) return { changed: false, value: structuredClone(persisted.claudeCode) };
+      persisted.claudeCode = { ...claudeCode, intercept: { ...intercept, picker: value } };
+      return { changed: true, value: structuredClone(persisted.claudeCode) };
+    });
+    if (outcome.status === "unavailable") return false;
+    adoptPersistedClaudeCode(live, outcome.value);
+    return true;
+  };
+}
+
 export interface StartClaudeInterceptOptions<T> {
   config: OcxConfig;
   /** Bound public port; the derived proxy port is offset from it. */
@@ -56,6 +107,13 @@ export interface StartClaudeInterceptOptions<T> {
   dispatch: (req: Request, server: Server<T>) => Promise<Response>;
   maxRequestBodySize?: number;
   configDir?: string;
+  /** Routes for Desktop's Code-tab picker. Picker mode is wired only when this is given. */
+  loadPickerRoutes?: () => Promise<PickerRouteInput>;
+  /** Test seam: builds the picker runtime. */
+  createPicker?: (options: CreatePickerRuntimeOptions) => PickerRuntime;
+  /** Test seams: the macOS `security` runner and platform for the picker runtime and controller. */
+  pickerSecurity?: SecurityRunner;
+  pickerPlatform?: NodeJS.Platform;
 }
 
 /**
@@ -84,13 +142,102 @@ export async function startClaudeIntercept<T>(options: StartClaudeInterceptOptio
     await listener.stop(true);
     throw error;
   }
-  const state: ClaudeInterceptState = { proxyPort: proxy.port, caCertPath: claudeInterceptCaCertPath(configDir) };
+  // Widened on purpose: assignments happen in nested awaits the catch below must still see.
+  let picker = null as PickerRuntime | null;
+  let pickerProxy = null as ConnectProxyHandle | null;
+  let controller = null as DesktopPickerController | null;
+  let pickerProxyLive = false;
+  try {
+    if (options.loadPickerRoutes) {
+      picker = (options.createPicker ?? createPickerRuntime)({
+        config: options.config,
+        configDir,
+        loadRoutes: options.loadPickerRoutes,
+        // The controller's lock: while it is held, periodic refreshes never arm.
+        isBusy: () => controller?.busy() ?? false,
+        // Metadata only: method, bootstrap or other, status, and the rewrite outcome.
+        log: line => console.log(`[claude-picker] ${line}`),
+        ...(options.pickerSecurity ? { security: options.pickerSecurity } : {}),
+        ...(options.pickerPlatform ? { platform: options.pickerPlatform } : {}),
+      });
+      const runtime = picker;
+      const interceptPort = listener.port!;
+      try {
+        pickerProxy = await startConnectProxy(claudePickerProxyPort(options.config, options.publicPort), {
+          interceptPort,
+          // No host list here: the choice below depends on which client opened the tunnel.
+          interceptHosts: [],
+          selectTunnel: (host, port, request) => {
+            // Desktop hands its pinned egress proxy to the Claude Code processes it spawns, so their
+            // api.anthropic.com traffic arrives here too and gets the same intercept as on the Claude
+            // Code proxy. Those processes trust only the intercept CA, so the picker never terminates
+            // their claude.ai tunnels; only the app's own (browser) CONNECTs reach the picker.
+            if (!isBrowserConnect(request)) {
+              return port === 443 && (CLAUDE_INTERCEPT_HOSTS as readonly string[]).includes(host.toLowerCase())
+                ? { kind: "intercept", port: interceptPort }
+                : { kind: "blind" };
+            }
+            return runtime.selectTunnel(host, port);
+          },
+        });
+        pickerProxyLive = true;
+      } catch (error) {
+        // Picker mode is optional: a busy port leaves the intercept pair running without it.
+        console.warn(`⚠ Claude Desktop picker proxy could not start: ${error instanceof Error ? error.message : String(error)}`);
+        await runtime.stop();
+        picker = null;
+      }
+      if (picker) {
+        // Dynamic: the controller reaches desktop-first-party, which imports this module.
+        const [{ createDesktopPickerController }, { loadConfig }, persistPreference] = await Promise.all([
+          import("../desktop-picker"),
+          import("../../config"),
+          createPickerPreferenceWriter(options.config),
+        ]);
+        const boundProxy = pickerProxy;
+        controller = createDesktopPickerController({
+          runtime: picker,
+          readConfig: loadConfig,
+          persistPreference,
+          proxyPort: () => (pickerProxyLive && boundProxy ? boundProxy.port : null),
+          configDir,
+          ...(options.pickerSecurity ? { security: options.pickerSecurity } : {}),
+          ...(options.pickerPlatform ? { platform: options.pickerPlatform } : {}),
+        });
+        await picker.start();
+      }
+    }
+  } catch (error) {
+    // Construction or start failed after the CONNECT proxy bound: release every socket first,
+    // so the lifecycle's catch never leaves a bound port without a handle.
+    pickerProxyLive = false;
+    controller = null;
+    await picker?.stop();
+    await pickerProxy?.close();
+    await proxy.close();
+    await listener.stop(true);
+    throw error;
+  }
+  const state: ClaudeInterceptState = {
+    proxyPort: proxy.port,
+    caCertPath: claudeInterceptCaCertPath(configDir),
+    pickerProxyPort: picker && pickerProxy ? pickerProxy.port : null,
+  };
   activeState = state;
+  activePicker = picker;
+  activeController = controller;
+  const ownPicker = picker;
+  const ownController = controller;
   return {
     ...state,
     listener,
     stop: async () => {
       if (activeState === state) activeState = null;
+      if (activePicker === ownPicker) activePicker = null;
+      if (activeController === ownController) activeController = null;
+      pickerProxyLive = false;
+      await ownPicker?.stop();
+      await pickerProxy?.close();
       await proxy.close();
       await listener.stop(true);
     },