@bitkyc08/opencodex 2.60.0 → 2.61.0-preview.20260922

package/src/cli/claude-desktop.ts

@@ -1,3 +1,4 @@
+import { recordCommittedDesktopGateway } from "../claude/desktop-gateway-state";
 import { readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { loadConfig, mutatePersistedConfig, withConfigMutationLockSync } from "../config";
@@ -15,13 +16,25 @@ import {
   type DesktopFamily,
   type DesktopProfile,
 } from "../claude/desktop-profile";
-import { writeDesktop3pConfig, type Desktop3pConfigMode, parseDesktop3pModeArgs } from "../claude/desktop-3p";
+import { inspectDesktop3pConfigLibrary, removeDesktop3pStandardPivot, writeDesktop3pConfig, type Desktop3pConfigMode, parseDesktop3pModeArgs } from "../claude/desktop-3p";
+import {
+  applyDesktopFirstParty,
+  captureDesktopFirstPartyRollback,
+  isClaudeDesktopMode,
+  recordClaudeDesktopMode,
+  removeDesktopFirstParty,
+  resolveClaudeDesktopApplyMode,
+  type ClaudeDesktopMode,
+} from "../claude/desktop-first-party";
 import { claudeDesktopPolicyWarning, probeClaudeDesktopPolicy } from "../claude/desktop-policy";
 import { filterCatalogVisibleModels, desktopVisibleNativeSlugs, nativeContextLimits } from "../codex/catalog";
 import { buildClaudeDesktopState, fetchAllModels } from "../server/management-api";
 import { findLiveProxy } from "../server/proxy-liveness";
 import { CliUsageError, runtimeRequest, takeJsonFlag } from "./runtime-api";
 import { OPENAI_CODEX_PROVIDER_ID } from "../providers/openai-tiers";
+import type { OcxConfig } from "../types";
+
+const APPLY_FLAGS = ["--first-party", "--gateway", "--static", "--hybrid", "--discovery-only"];
 
 function isFamily(value: string | undefined): value is DesktopFamily {
   return !!value && (DESKTOP_FAMILIES as readonly string[]).includes(value);
@@ -29,7 +42,10 @@ function isFamily(value: string | undefined): value is DesktopFamily {
 
 function printDesktopHelp(): void {
   console.log(`Usage:
-  ocx claude desktop [apply] [--static|--hybrid|--discovery-only]
+  ocx claude desktop [apply] [--first-party | --gateway [--static|--hybrid|--discovery-only]]
+      --first-party  (default) keep Desktop on claude.ai; route only the Code tab's Claude Code
+                     through the local intercept proxy via ~/.claude/settings.json env
+      --gateway      install the third-party gateway profile for the whole app
   ocx claude desktop show [--json]
   ocx claude desktop status [--json]
   ocx claude desktop move <provider/model> <opus|fable|sonnet|haiku> [--default]
@@ -56,6 +72,7 @@ function saveLocalDesktopProfile(
   expectedProfile: DesktopProfile | undefined,
   expectedConnection: ClientConnectionState,
   deps: ApplyProfileDeps,
+  gatewayWrite?: { fingerprint?: string },
 ): void {
   withClientLifecycleSync(() => {
     const outcome = mutatePersistedConfig(current => {
@@ -73,6 +90,10 @@ function saveLocalDesktopProfile(
       if (JSON.stringify(current.claudeCode?.desktopProfile) !== JSON.stringify(expectedProfile)) {
         throw new Error("desktop_profile_changed");
       }
+      if (gatewayWrite) {
+        recordCommittedDesktopGateway(current, profile, gatewayWrite.fingerprint, new Date().toISOString());
+        return { changed: true, value: undefined };
+      }
       const changed = JSON.stringify(current.claudeCode?.desktopProfile) !== JSON.stringify(profile);
       if (changed) current.claudeCode = { ...(current.claudeCode ?? {}), desktopProfile: structuredClone(profile) };
       return { changed, value: undefined };
@@ -135,6 +156,151 @@ async function applyConnectedDesktopProfile(
   }
 }
 
+/** Persist the operator's Desktop mode choice; a failed marker save never undoes the apply. */
+function saveDesktopMode(mode: ClaudeDesktopMode, deps: ApplyProfileDeps): boolean {
+  try {
+    return withClientLifecycleSync(() => {
+      const outcome = mutatePersistedConfig(current => recordClaudeDesktopMode(current, mode));
+      return outcome.status !== "unavailable";
+    }, deps.lifecycleLockDeps);
+  } catch {
+    return false;
+  }
+}
+
+export type DesktopApplyTarget =
+  | { kind: "first-party" }
+  | { kind: "gateway"; mode: Desktop3pConfigMode };
+
+/** Parse `ocx claude desktop apply` flags into a target; legacy gateway shape flags imply --gateway. */
+/**
+ * Default mode when no flag is given: first-party wherever the local intercept proxy can
+ * run; a connected client (proxy lives on the hub) or a disabled intercept falls back to
+ * the gateway profile rather than pointing Claude Code at a proxy that does not exist.
+ */
+export function defaultDesktopApplyMode(
+  config: Pick<OcxConfig, "claudeCode" | "runtimeRole">,
+  connection: ClientConnectionState = readClientConnectionState(),
+): ClaudeDesktopMode {
+  const resolved = resolveClaudeDesktopApplyMode(config);
+  if (resolved === "gateway") return resolved;
+  return connection.kind === "connected" ? "gateway" : "first-party";
+}
+
+export function parseDesktopApplyArgs(
+  flags: string[],
+  config: Pick<OcxConfig, "claudeCode" | "runtimeRole">,
+): { target: DesktopApplyTarget } | { error: string } {
+  const shapeFlags = flags.filter(arg => ["--static", "--hybrid", "--discovery-only"].includes(arg));
+  const wantsFirstParty = flags.includes("--first-party");
+  const wantsGateway = flags.includes("--gateway") || shapeFlags.length > 0;
+  if (wantsFirstParty && wantsGateway) return { error: "--first-party cannot be combined with --gateway or gateway shape flags." };
+  const unknown = flags.filter(arg => !["--first-party", "--gateway", "--static", "--hybrid", "--discovery-only"].includes(arg));
+  if (unknown.length > 0) return { error: `알 수 없는 인자: ${unknown.join(" ")}` };
+  const kind: ClaudeDesktopMode = wantsFirstParty ? "first-party" : wantsGateway ? "gateway" : defaultDesktopApplyMode(config);
+  if (kind === "first-party") return { target: { kind } };
+  const parsedMode = parseDesktop3pModeArgs(shapeFlags);
+  if ("error" in parsedMode) return parsedMode;
+  return { target: { kind, mode: parsedMode.mode } };
+}
+
+/**
+ * Why a gateway apply happened when the help text calls first-party the default.
+ *
+ * `resolveClaudeDesktopMode` keeps an existing install where it is: an explicit
+ * `claudeCode.desktopMode` wins, and a stored gateway apply marker keeps gateway. Both rules are
+ * right — a working Desktop install must not flip underneath its user because a default moved.
+ * Together they mean an existing gateway user never arrives at first-party without discovering
+ * `--first-party` unaided, while `ocx claude desktop --help` tells them first-party is "(default)".
+ *
+ * The fix is not to change the resolution. It is to say, at the moment of the apply, that the
+ * other mode exists and what selects it. Returns null when the user asked for gateway explicitly,
+ * because they already know, and when first-party is simply unavailable here — a connected client
+ * or a disabled intercept cannot run it, so offering it would be advice that fails.
+ */
+export function gatewayModeExplanation(input: {
+  requestedExplicitly: boolean;
+  config: Pick<OcxConfig, "claudeCode" | "runtimeRole">;
+  connection?: ClientConnectionState;
+}): string[] {
+  if (input.requestedExplicitly) return [];
+  const connection = input.connection ?? readClientConnectionState();
+  if (connection.kind === "connected") return [];
+  // Only a stored preference is worth explaining. Without one, gateway was chosen because
+  // first-party cannot run here, and naming an unavailable alternative is advice that fails.
+  const savedMode = input.config.claudeCode?.desktopMode;
+  const hasSavedGateway = isClaudeDesktopMode(savedMode) && savedMode === "gateway";
+  const hasApplyMarker = input.config.claudeCode?.desktopProfile?.appliedFingerprint !== undefined;
+  if (!hasSavedGateway && !hasApplyMarker) return [];
+  const reason = hasSavedGateway
+    ? "this machine has claudeCode.desktopMode saved as gateway"
+    : "this machine carries a previous gateway apply";
+  return [
+    `Applied the gateway profile because ${reason}; an existing install is never switched for you.`,
+    "First-party keeps Desktop on your claude.ai account and routes only the Code tab through the local proxy:",
+    "  ocx claude desktop apply --first-party",
+  ];
+}
+
+/**
+ * First-party apply: settings.json env only. The intercept pair the env points at runs inside
+ * the hub process, so this is a local-hub operation — a connected client machine cannot reach
+ * a loopback proxy on the hub and is refused rather than left with a dead `HTTPS_PROXY`.
+ */
+async function applyFirstPartyDesktop(
+  deps: ApplyProfileDeps,
+): Promise<{ ok: boolean; path: string; reason?: string; warning?: string }> {
+  try { assertNoClientDisconnectPending(); } catch { return { ok: false, path: "", reason: "client_disconnect_pending" }; }
+  const connection = readClientConnectionState();
+  if (connection.kind === "connected") return { ok: false, path: "", reason: "first_party_requires_local_hub" };
+  if (connection.kind !== "disconnected") return { ok: false, path: "", reason: "client_connection_invalid" };
+  const config = loadConfig();
+  const desired = setIntegrationEnabled("claude-desktop", true);
+  if (!desired.ok) return { ok: false, path: "", reason: desired.message };
+  // Establish the replacement before deleting the working gateway. A refused
+  // cleanup restores only our managed env keys, preserving unrelated settings.
+  const rollback = captureDesktopFirstPartyRollback(config);
+  const applied = applyDesktopFirstParty(config);
+  if (!applied.ok) return { ok: false, path: applied.path, reason: applied.reason };
+  const appliedFingerprint = config.claudeCode?.desktopProfile?.appliedFingerprint ?? null;
+  const library = inspectDesktop3pConfigLibrary({ appliedFingerprint });
+  if (library.kind === "gateway_ours" || library.kind === "gateway_drifted") {
+    const removed = removeDesktop3pStandardPivot({ appliedFingerprint, replaceWhileEnabled: true });
+    if (!removed.ok) {
+      const restored = removed.changed || !applied.changed || rollback();
+      const modeSaved = !removed.changed || saveDesktopMode("first-party", deps);
+      const warning = [restored ? "" : "first-party settings rollback did not complete",
+        modeSaved ? "" : "first-party is active but its mode marker was not saved"].filter(Boolean).join("; ");
+      return { ok: false, path: library.selectedProfilePath ?? "", reason: removed.kind === "cleanup_incomplete" ? "gateway_cleanup_incomplete" : `gateway_profile_active:${removed.reason ?? removed.kind}`,
+        ...(warning ? { warning } : {}) };
+    }
+  }
+  const saved = saveDesktopMode("first-party", deps);
+  return {
+    ok: true,
+    path: applied.path,
+    ...(saved ? {} : { warning: "desktop mode marker was not saved" }),
+  };
+}
+
+export async function applyDesktop(
+  profile: DesktopProfile | undefined,
+  target: DesktopApplyTarget,
+  deps: ApplyProfileDeps = {},
+): Promise<{ ok: boolean; path: string; reason?: string; warning?: string }> {
+  if (target.kind === "first-party") return applyFirstPartyDesktop(deps);
+  const result = await applyProfile(profile, target.mode, deps);
+  if (!result.ok) return result;
+  const modeSaved = saveDesktopMode("gateway", deps);
+  const warning = [result.warning, modeSaved ? "" : "desktop mode marker was not saved"].filter(Boolean).join(" ");
+  // The gateway mode is committed before retiring first-party settings.
+  const removed = removeDesktopFirstParty();
+  if (!removed.ok) return { ok: false, path: removed.path, reason: "first_party_settings_unreadable",
+    warning: ["gateway applied; first-party cleanup remains incomplete", warning].filter(Boolean).join(" ") };
+  if (warning) return { ...result, warning };
+  return result;
+}
+
 export async function applyProfile(
   profile: DesktopProfile | undefined,
   mode: Desktop3pConfigMode,
@@ -205,8 +371,13 @@ export async function applyProfile(
     nativeContextLimits(config),
     deps.lifecycleLockDeps,
   );
+  let stateWarning: string | undefined;
+  if (result.written) {
+    try { saveLocalDesktopProfile(state.profile, state.profile, connection, deps, { fingerprint: result.fingerprint }); }
+    catch { stateWarning = "gateway applied but its committed mode/profile state was not saved"; }
+  }
   const policyState = (deps.probeClaudeDesktopPolicy ?? probeClaudeDesktopPolicy)();
-  const warning = result.written ? claudeDesktopPolicyWarning(policyState) : undefined;
+  const warning = [result.written ? claudeDesktopPolicyWarning(policyState) : undefined, stateWarning].filter(Boolean).join(" ");
   return {
     ok: result.written,
     path: result.path,
@@ -222,24 +393,42 @@ export async function handleClaudeDesktopCommand(argv: string[], deps: ApplyProf
     return 0;
   }
 
-  // Legacy mode flags remain apply aliases and are parsed before subcommands.
-  const legacyFlags = argv.filter(arg => ["--static", "--hybrid", "--discovery-only"].includes(arg));
-  const applyInvocation = argv.length === 0 || command === "apply" || legacyFlags.length > 0;
+  // Mode flags remain apply aliases and are parsed before subcommands.
+  const applyFlags = argv.filter(arg => APPLY_FLAGS.includes(arg));
+  const applyInvocation = argv.length === 0 || command === "apply" || applyFlags.length > 0;
   if (applyInvocation) {
-    const nonMode = argv.filter(arg => !["apply", "--static", "--hybrid", "--discovery-only"].includes(arg));
-    if (nonMode.length > 0) {
-      console.error(`알 수 없는 인자: ${nonMode.join(" ")}`);
-      return 2;
-    }
-    const parsedMode = parseDesktop3pModeArgs(legacyFlags);
-    if ("error" in parsedMode) { console.error(parsedMode.error); return 2; }
+    const rest = argv.filter(arg => arg !== "apply");
+    const parsedTarget = parseDesktopApplyArgs(rest, loadConfig());
+    if ("error" in parsedTarget) { console.error(parsedTarget.error); return 2; }
+    const { target } = parsedTarget;
     try {
-      const result = await applyProfile(undefined, parsedMode.mode, deps);
+      const result = await applyDesktop(undefined, target, deps);
       if (!result.ok) {
         console.error(`설정 적용 실패: ${result.reason ?? "unknown error"}`);
+        if (result.warning) console.warn(result.warning);
+        if (result.reason?.startsWith("gateway_")) {
+          console.error("The gateway profile could not be removed safely, so first-party mode was not applied. Turn the integration off (dashboard toggle) and retry, or keep gateway with `ocx claude desktop apply --gateway`.");
+        } else if (result.reason === "foreign_env") {
+          console.error(`~/.claude/settings.json already sets HTTPS_PROXY or NODE_EXTRA_CA_CERTS to a value opencodex does not own (${result.path}). Remove them or use --gateway.`);
+        } else if (result.reason === "intercept_disabled") {
+          console.error("First-party mode needs the Claude intercept proxy (claudeCode.intercept.enabled on a hub). Use --gateway instead.");
+        } else if (result.reason === "first_party_requires_local_hub") {
+          console.error("First-party mode runs on the hub machine only; on a connected client use --gateway.");
+        }
         return 1;
       }
-      console.log(`Claude Desktop 설정을 적용했습니다: ${result.path}`);
+      if (target.kind === "first-party") {
+        console.log(`Claude Desktop first-party 설정을 적용했습니다: ${result.path}`);
+        console.log("Desktop 앱 설정은 그대로이며, Code 탭의 Claude Code만 로컬 프록시를 거칩니다.");
+      } else {
+        console.log(`Claude Desktop gateway 설정을 적용했습니다: ${result.path}`);
+        for (const line of gatewayModeExplanation({
+          requestedExplicitly: applyFlags.some(flag => flag !== "--first-party"),
+          config: loadConfig(),
+        })) {
+          console.log(line);
+        }
+      }
       // The write landed; only the bookkeeping marker did not. Saying nothing
       // would leave the saved-vs-applied display wrong with no explanation.
       if (result.warning) console.warn(`⚠️  ${result.warning}`);
@@ -336,7 +525,8 @@ export async function handleClaudeDesktopCommand(argv: string[], deps: ApplyProf
       }
       saveLocalDesktopProfile(reconciled, config.claudeCode?.desktopProfile, connection, deps);
       if (flags.includes("--apply")) {
-        const result = await applyProfile(reconciled, "static", deps);
+        // A routing profile is a gateway-mode artifact: importing with --apply installs it there.
+        const result = await applyDesktop(reconciled, { kind: "gateway", mode: "static" }, deps);
         if (!result.ok) { console.error(`프로필은 저장했지만 Desktop 적용에 실패했습니다: ${result.reason ?? "unknown error"}`); return 1; }
         if (result.warning) console.warn(`⚠️  ${result.warning}`);
       }

package/src/cli/codex-shim-autorestore.ts

@@ -19,6 +19,9 @@ export function skipsCodexShimAutoRestore(command: string | undefined, args: str
   if (command === "uninstall" || command === "remove") return true;
   // `lab` is read-only inspection; it must not trigger shim side effects.
   if (command === "lab") return true;
+  // `resolve` is read-only inspection for embedding shells: a lookup made to populate
+  // a consent surface must not trigger a shim repair side effect first.
+  if (command === "resolve") return true;
   // The entire updater-inspection namespace is zero-effect, including malformed
   // or future actions. A later `apply` implementation must own its preflight.
   if (command === "system" && args[1] === "codex-cli-update") return true;

package/src/cli/companion.ts

@@ -0,0 +1,56 @@
+import { CliUsageError, printData, rejectArgs, runCliAction, runtimeRequest, takeFlag, type RuntimeApiDeps } from "./runtime-api";
+
+const USAGE = `Usage:
+  ocx companion [show] [--json]
+  ocx companion set <key>=<value> [...] [--json]
+  ocx companion reset [--json]`;
+
+function parseValue(raw: string): unknown {
+  if (raw === "null") return null;
+  try { return JSON.parse(raw); } catch { return raw; }
+}
+
+async function show(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  rejectArgs(args, USAGE);
+  printData(await runtimeRequest("/api/companion/settings", {}, deps), wantsJson);
+}
+
+async function set(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  if (args.length === 0) throw new CliUsageError("companion set requires key=value assignments", USAGE);
+  const patch: Record<string, unknown> = {};
+  for (const assignment of args) {
+    const separator = assignment.indexOf("=");
+    if (separator <= 0) throw new CliUsageError(`invalid companion setting "${assignment}"; use key=value`, USAGE);
+    patch[assignment.slice(0, separator)] = parseValue(assignment.slice(separator + 1));
+  }
+  printData(await runtimeRequest("/api/companion/settings", {
+    method: "PUT",
+    body: JSON.stringify({ settings: patch }),
+  }, deps), wantsJson, ["Companion settings saved."]);
+}
+
+async function reset(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  rejectArgs(args, USAGE);
+  printData(await runtimeRequest("/api/companion/settings", {
+    method: "PUT",
+    body: JSON.stringify({ reset: true }),
+  }, deps), wantsJson, ["Companion settings reset."]);
+}
+
+export async function handleCompanionCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  return runCliAction(async () => {
+    const [sub = "show", ...rest] = argv;
+    if (sub === "show") await show(rest, deps);
+    else if (sub === "set") await set(rest, deps);
+    else if (sub === "reset") await reset(rest, deps);
+    else throw new CliUsageError(`unknown companion command ${sub}`, USAGE);
+  });
+}
+
+export const COMPANION_USAGE = USAGE;

package/src/cli/dispatch.ts

@@ -29,6 +29,8 @@ import { stripGrokConfig } from "../grok/inject";
 import { handleRestartScopeAfterWrite, readRestartScope, type RestartScope } from "./restart-scope";
 import { normalizeUpdateChannel, runGuiUpdateWorker } from "../update/job";
 import { isJsonOption, takeFlag, terminalSafeError } from "./runtime-api";
+import { printStopSummary, type StopOutcome } from "./stop-report";
+import type { ResolveArgs } from "./resolve";
 import type { ClientConnectionState } from "../client/state";
 import { OCX_NATIVE_REPLAY_RECOVERY_NOTE } from "../responses/compaction";
 
@@ -44,8 +46,9 @@ export interface CliDispatchDeps {
   /** Spawn a detached proxy child (stdio ignore, unref'd, provenance env). */
   spawnDetached: (argv: readonly string[]) => void;
   handleStart: () => Promise<void>;
-  handleStop: () => Promise<boolean>;
+  handleStop: () => Promise<StopOutcome>;
   handleEnsure: (options?: { existingIsSuccess?: boolean }) => Promise<boolean>;
+  handleResolve: (args: ResolveArgs) => Promise<number>;
   handleTrayProxyStart: (existingIsSuccess?: boolean) => Promise<boolean>;
   handleTrayProxyRestart: () => Promise<void>;
   handleRestartStartWhenStopped: () => Promise<boolean | "skipped">;
@@ -98,11 +101,39 @@ const commandRunners: Record<string, CommandRunner> = {
   stop: async deps => {
     // Downtime warning lives HERE, not in handleStop: `restart`/tray-restart callers
     // re-start the proxy immediately, so warning there would contradict the next line.
-    if (await deps.handleStop()) {
-      console.log("⚠️  Codex/Claude requests through the proxy will fail until it is restarted ('ocx start' or 'ocx service start').");
+    const warning = "⚠️  Codex/Claude requests through the proxy will fail until it is restarted ('ocx start' or 'ocx service start').";
+    if (!takeFlag(deps.args.slice(1), "--json")) {
+      // handleStop returns the structured outcome now; an object is always truthy, so
+      // the warning must key on .ok — otherwise a failed stop would still claim downtime.
+      if ((await deps.handleStop()).ok) console.log(warning);
+      return Number(process.exitCode ?? 0);
     }
+    // --json is a reporting layer over the SAME stop path: the receipt, the drain, the
+    // respawn verification and the client-config restore run unchanged. Human output
+    // still prints, but on stderr, so stdout carries exactly one JSON summary document.
+    // The exit code (0/1/79/80) crosses the process boundary untouched — the shell reads
+    // it from the child, and the stop-contract codes must survive the JSON mode.
+    const humanLog = console.log;
+    console.log = console.error;
+    let outcome: StopOutcome | undefined;
+    try {
+      outcome = await deps.handleStop();
+      if (outcome.ok) console.log(warning);
+    } finally {
+      console.log = humanLog;
+    }
+    // A throw above propagates after the finally restores the console, so reaching here
+    // with an undefined outcome cannot happen; the guard keeps the assignment provable.
+    if (outcome) printStopSummary(outcome.summary);
     return Number(process.exitCode ?? 0);
   },
+  resolve: async deps => {
+    // Same fail-closed shape as `ready`: parseCliHead pre-parsed the verb before any
+    // preflight side effect, so a missing resolveArgs means dispatch diverged. Refuse
+    // with code 64 and perform NO I/O.
+    if (!deps.head.resolveArgs) return 64;
+    return await deps.handleResolve(deps.head.resolveArgs);
+  },
   restore: async deps => {
     const restoreArgs = deps.args.slice(1);
     const restoreJson = takeFlag(restoreArgs, "--json");
@@ -615,7 +646,11 @@ const commandRunners: Record<string, CommandRunner> = {
         const guiUrl = selectDefaultGuiUrl(config, live, deps.probeHostname);
         console.log(`Opening ${guiUrl}`);
         const { openUrl } = await import("../lib/open-url");
-        openUrl(guiUrl);
+        // Awaited so a launcher that never opened anything is said out loud (#5261). Still exit
+        // 0: the proxy is serving and the URL above is reachable, only the launch did not happen.
+        if ((await openUrl(guiUrl)).status === "failed") {
+          console.error("⚠️  No browser could be opened here; open the URL above yourself.");
+        }
         return 0;
       },
     });
@@ -782,6 +817,10 @@ const commandRunners: Record<string, CommandRunner> = {
     const { handleComboCommand } = await import("./combo");
     return await handleComboCommand(deps.args.slice(1));
   },
+  companion: async deps => {
+    const { handleCompanionCommand } = await import("./companion");
+    return await handleCompanionCommand(deps.args.slice(1));
+  },
   route: async deps => {
     if (deps.args[1] !== "combo" && deps.args[1] !== "policy") {
       console.error("Usage: ocx route <combo|policy> <subcommand>");

package/src/cli/ensure-desired-integrations.ts

@@ -10,7 +10,13 @@
  */
 import { loadConfig } from "../config";
 import { stripGrokConfig, type GrokInjectResult } from "../grok/inject";
-import { removeDesktop3pStandardPivot } from "../claude/desktop-3p";
+import { inspectDesktop3pConfigLibrary, removeDesktop3pStandardPivot } from "../claude/desktop-3p";
+import {
+  applyDesktopFirstParty,
+  inspectDesktopFirstParty,
+  removeDesktopFirstParty,
+  resolveClaudeDesktopMode,
+} from "../claude/desktop-first-party";
 import {
   claudeDesktopIntegrationEnabled,
   grokIntegrationEnabled,
@@ -35,6 +41,10 @@ export interface EnsureDesiredIntegrationsDeps {
     opts?: { hostname?: string },
   ) => Promise<GrokInjectResult>;
   removeDesktop3pStandardPivot: typeof removeDesktop3pStandardPivot;
+  removeDesktopFirstParty?: typeof removeDesktopFirstParty;
+  applyDesktopFirstParty?: typeof applyDesktopFirstParty;
+  inspectDesktopFirstParty?: typeof inspectDesktopFirstParty;
+  inspectDesktop3pConfigLibrary?: typeof inspectDesktop3pConfigLibrary;
   log?: (message: string) => void;
   error?: (message: string) => void;
 }
@@ -113,16 +123,44 @@ export async function ensureGrokFenceMatchesDesired(
 }
 
 /**
- * When Claude Desktop is durably OFF, clear any leftover owned gateway profile.
- * ensure/update used to leave Claude-3p residue in place after a failed disable
- * (drifted fingerprint), so the Integrations card kept looking applied/stale.
+ * When Claude Desktop is durably OFF, clear any leftover owned gateway profile and the
+ * first-party settings env. ensure/update used to leave Claude-3p residue in place after a
+ * failed disable (drifted fingerprint), so the Integrations card kept looking applied/stale.
+ *
+ * When it is ON in first-party mode, refresh a stale env (the intercept port follows the
+ * public port, so a port change would otherwise leave Claude Code pointed at a dead proxy).
  */
 export function ensureClaudeDesktopMatchesDesired(
   deps: EnsureDesiredIntegrationsDeps = productionDeps,
 ): void {
   const config = deps.loadConfig();
   const { log, error } = io(deps);
-  if (claudeDesktopIntegrationEnabled(config)) return;
+  if (claudeDesktopIntegrationEnabled(config)) {
+    if (resolveClaudeDesktopMode(config) !== "first-party") return;
+    const library = (deps.inspectDesktop3pConfigLibrary ?? inspectDesktop3pConfigLibrary)({
+      appliedFingerprint: config.claudeCode?.desktopProfile?.appliedFingerprint ?? null,
+    });
+    if (library.kind === "gateway_ours" || library.kind === "gateway_drifted") {
+      // The mode marker and the disk disagree. Replacing a live Desktop profile is an operator
+      // action, not something an update hook should do silently.
+      error("⚠️  Claude Desktop mode is first-party but a gateway profile is still applied; run `ocx claude desktop apply --first-party` (or `--gateway`) to reconcile.");
+      return;
+    }
+    const seen = (deps.inspectDesktopFirstParty ?? inspectDesktopFirstParty)(config);
+    if (!seen.stale) return;
+    const applied = (deps.applyDesktopFirstParty ?? applyDesktopFirstParty)(config);
+    if (applied.ok && applied.changed) log(`   + Claude Desktop first-party env refreshed (${applied.path})`);
+    else if (!applied.ok) error(`⚠️  Claude Desktop first-party env refresh skipped: ${applied.reason}.`);
+    return;
+  }
+  try {
+    const env = (deps.removeDesktopFirstParty ?? removeDesktopFirstParty)();
+    if (env.ok && env.changed) log("   ↩️  Claude Desktop first-party env removed.");
+    else if (!env.ok) error(`⚠️  Claude Desktop first-party env cleanup skipped: ${env.reason} (${env.path}).`);
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    error(`⚠️  Claude Desktop first-party env cleanup failed: ${detail}.`);
+  }
   try {
     const removed = deps.removeDesktop3pStandardPivot({
       appliedFingerprint: config.claudeCode?.desktopProfile?.appliedFingerprint ?? null,

package/src/cli/help.ts

@@ -1,9 +1,5 @@
-import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
 import { findCommand } from "./registry";
-
-const repoRoot = dirname(fileURLToPath(new URL("../../package.json", import.meta.url)));
+import { packageVersion as readPackageVersion } from "../lib/package-version";
 
 /**
  * Version of the `ocx` bundle this process is running from.
@@ -13,9 +9,7 @@ const repoRoot = dirname(fileURLToPath(new URL("../../package.json", import.meta
  * rather than throwing; callers must treat that as "cannot compare", not as a mismatch.
  */
 export function packageVersion(): string {
-  const raw = readFileSync(join(repoRoot, "package.json"), "utf8");
-  const parsed = JSON.parse(raw) as { version?: unknown };
-  return typeof parsed.version === "string" ? parsed.version : "unknown";
+  return readPackageVersion();
 }
 
 export function printVersion(): void {
@@ -29,9 +23,11 @@ Usage:
   ocx setup                   Interactive setup (alias: init)
   ocx start [--port <port>] [--socks5 [host:port] | --socks5-off]
                               Start the proxy; SOCKS5 defaults to 127.0.0.1:10808
-  ocx stop                    Stop the proxy AND restore native Codex (plain codex works again)
+  ocx stop [--json]           Stop the proxy AND restore native Codex (plain codex works again)
   ocx restore                 Restore native Codex without stopping (alias: eject)
   ocx restore back            Re-point codex at the running proxy (undo restore)
+  ocx restore --remove-codex-provider-table
+                              Also drop [model_providers.opencodex] that a paginated restore kept
   ocx recover-history --legacy-openai --yes
                                Force all user-message opencodex rows to OpenAI (legacy recovery)
   ocx recover-history --ocx-compaction <thread-id> --yes
@@ -67,6 +63,7 @@ Usage:
   ocx health [--json]          Check proxy health (exit 0=healthy, 1=not)
   ocx capabilities [--json]    List declared capabilities and the API routes they drive
   ocx ready [--json] [--wait [--timeout <s>]]  Check post-sync readiness (exit 0 only when ready)
+  ocx resolve [--json]        Config home, effective port, and liveness (JSON for shells)
   ocx provider <sub>          Providers, connectivity, quota, and selected models
   ocx account <sub>           Accounts, login/reauth, key pools, and quota controls
   ocx models <sub>            Live/custom models, visibility, context, and shadow calls
@@ -89,6 +86,7 @@ Usage:
   ocx grok <sub>              Grok Build model selection and apply
   ocx system <sub>            Runtime settings, startup, sync, OpenCodex updates, and Codex CLI inspection
   ocx config <sub>            Validated configuration show/get/set/import/export
+  ocx companion <show|set|reset>  Menu-bar and widget companion usage settings
   ocx lab <sub>               Read-only Compatibility Lab projection inspection
   ocx claude [args...]        Launch Claude Code wired to the proxy (model discovery on)
   ocx claude desktop [sub]    Manage and apply Claude Desktop's four-family profile