@bitkyc08/opencodex 2.10.0 → 2.10.1

package/src/cli/doctor.ts

@@ -13,10 +13,15 @@ import { dirname, join } from "node:path";
 import { getConfigDir, getConfigPath, readConfigDiagnostics, readPid, readRuntimePort, resolveEnvValue } from "../config";
 import { findLiveProxy } from "../server/proxy-liveness";
 import { gracefulStopHost } from "../lib/process-control";
+import { BUN_RUNTIME_SOURCES } from "../lib/bun-runtime";
+import type { BunRuntimeSource } from "../lib/bun-runtime";
 import { maskAccountId } from "../lib/privacy";
 import { PROXY_ENV_KEYS, proxyEnvPresent } from "../lib/proxy-env";
 import { configuredAdminToken } from "../lib/admin-secrets";
 import { readCodexTokens } from "../codex/auth-collision";
+import { withNativeMainSharedClaim } from "../codex/native-main-claim";
+import { probeNativeProfileRecoveryState, resolveNativeProfileContext } from "../codex/native-profile-store";
+import { NativeProfileError } from "../codex/native-profile-types";
 import { collectOrcaCodexHomeDiagnostic, resolveCodexHomeDir as resolveCodexHomeDirImpl, isWslRuntime, listWslWindowsCodexHomes, wslAutomountRoot, type CodexHomeDeps } from "../codex/home";
 import { findCodexOnPath, isWindowsInteropDir } from "../codex/shim";
 import { countPendingOpencodexHistory } from "../codex/history-provider";
@@ -479,36 +484,75 @@ export type WhamProbeResult = {
   authenticated: boolean;
 };
 
+type NativeMainDoctorClaim = <T>(operation: () => Promise<T>) => Promise<T>;
+
+export interface WhamProbeDeps {
+  withNativeMainClaim?: NativeMainDoctorClaim;
+  probeNativeMainRecoveryState?: typeof probeNativeProfileRecoveryState;
+}
+
 /**
  * Replicate the runtime WHAM fetch shape (same URL, 8s timeout, main-token
  * headers when present) so the probe fails exactly where the real path fails.
  * `fetchImpl` is injectable for testing.
  */
-export async function probeWham(fetchImpl: typeof fetch = fetch): Promise<WhamProbeResult> {
-  const tokens = readCodexTokens();
-  const headers: Record<string, string> = {};
-  if (tokens) {
-    headers.Authorization = `Bearer ${tokens.access_token}`;
-    headers["ChatGPT-Account-Id"] = tokens.account_id;
-  }
+export async function probeWham(
+  fetchImpl: typeof fetch = fetch,
+  deps: WhamProbeDeps = {},
+): Promise<WhamProbeResult> {
   const start = performance.now();
+  let authenticated = false;
   try {
-    const resp = await fetchImpl(WHAM_USAGE_URL, { headers, signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
-    const durationMs = Math.round(performance.now() - start);
-    return {
-      ok: resp.ok,
-      status: resp.status,
-      durationMs,
-      classification: resp.ok ? "ok" : `http_${resp.status}`,
-      authenticated: !!tokens,
-    };
+    const context = resolveNativeProfileContext();
+    const withClaim = deps.withNativeMainClaim
+      ?? (<T>(operation: () => Promise<T>) => withNativeMainSharedClaim(context, operation));
+    return await withClaim(async () => {
+      const recoveryState = (deps.probeNativeMainRecoveryState ?? probeNativeProfileRecoveryState)(context);
+      if (recoveryState !== "none") {
+        return {
+          ok: false,
+          status: null,
+          durationMs: Math.round(performance.now() - start),
+          classification: `native_main_recovery_${recoveryState}`,
+          authenticated: false,
+        };
+      }
+      const tokens = readCodexTokens();
+      const headers: Record<string, string> = {};
+      if (tokens) {
+        headers.Authorization = `Bearer ${tokens.access_token}`;
+        headers["ChatGPT-Account-Id"] = tokens.account_id;
+      }
+      authenticated = !!tokens;
+      const resp = await fetchImpl(WHAM_USAGE_URL, { headers, signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
+      const durationMs = Math.round(performance.now() - start);
+      return {
+        ok: resp.ok,
+        status: resp.status,
+        durationMs,
+        classification: resp.ok ? "ok" : `http_${resp.status}`,
+        authenticated,
+      };
+    });
   } catch (err) {
     const durationMs = Math.round(performance.now() - start);
+    if (
+      err instanceof NativeProfileError
+      && (err.code === "NATIVE_MAIN_CLAIM_BUSY" || err.code === "NATIVE_MAIN_CLAIM_UNAVAILABLE")
+    ) {
+      return {
+        ok: false,
+        status: null,
+        durationMs,
+        classification: err.code.toLowerCase(),
+        authenticated: false,
+      };
+    }
     const name = err instanceof Error ? err.name : String(err);
     const classification = name === "TimeoutError" || name === "AbortError"
       ? "timeout"
       : "connect_error";
-    return { ok: false, status: null, durationMs, classification, authenticated: !!tokens };
+    return { ok: false, status: null, durationMs, classification, authenticated };
   }
 }
 
@@ -523,6 +567,8 @@ export async function probeWham(fetchImpl: typeof fetch = fetch): Promise<WhamPr
 export type ServiceMemoryData = {
   pid: number;
   bunVersion: string;
+  /** Launch-time provenance; absent for services installed before the marker existed. */
+  bunRuntimeSource?: BunRuntimeSource;
   platform: string;
   rss: number;
   heapUsed: number;
@@ -579,6 +625,9 @@ export async function fetchServiceMemory(
       data: {
         pid: body.pid,
         bunVersion: body.bunVersion,
+        // Allowlisted independently of the server: an unrecognized wire value is
+        // treated as absent rather than echoed into user-facing guidance.
+        bunRuntimeSource: BUN_RUNTIME_SOURCES.find(source => source === body.bunRuntimeSource),
         platform: typeof body.platform === "string" ? body.platform : "unknown",
         rss: body.rss,
         heapUsed: typeof body.heapUsed === "number" ? body.heapUsed : 0,
@@ -652,12 +701,22 @@ export function formatServiceMemoryLines(report: ServiceMemoryReport): string[]
   } else {
     lines.push("  !!     high RSS, indeterminate split — capture two doctor runs over time to see the trend");
   }
-  // Version-claiming (never binary-claiming): the endpoint cannot distinguish
-  // the bundled binary from an OPENCODEX_BUN_PATH override of the same version.
   if (d.platform === "win32" && d.eagerRelay?.reason === "auto-known-bad") {
     lines.push(`         service is running Bun ${d.bunVersion} on Windows — a version affected by the upstream Bun memory issue.`);
-    lines.push("         Options: wait for a bundled runtime update, or set OPENCODEX_BUN_PATH to a runtime you trust (unvalidated — own risk),");
-    lines.push("         or opt into streamMode \"eager-relay\" via PUT /api/settings (crash risk on this runtime; see docs).");
+    // The remediation depends on how the SERVICE was launched, which only the
+    // launch-time marker can answer. Telling someone to set OPENCODEX_BUN_PATH
+    // when it is already set is the bug this branch exists to avoid (#848).
+    if (d.bunRuntimeSource === "override") {
+      lines.push(`         OPENCODEX_BUN_PATH is already active for this service — the override runtime is itself an affected version (unvalidated — own risk).`);
+      lines.push("         Options: point the override at a different runtime, or opt into streamMode \"eager-relay\" via PUT /api/settings (crash risk on this runtime; see docs).");
+    } else if (d.bunRuntimeSource === undefined) {
+      lines.push("         this service records no runtime origin (installed before provenance tracking), so OpenCodex cannot tell whether an override is already active.");
+      lines.push("         Reinstall the service to record it, or opt into streamMode \"eager-relay\" via PUT /api/settings (crash risk on this runtime; see docs).");
+    } else {
+      const origin = d.bunRuntimeSource === "process" ? "the runtime that launched it" : "the bundled runtime";
+      lines.push(`         the service is using ${origin}. Options: wait for a bundled runtime update, or set OPENCODEX_BUN_PATH to a runtime you trust (unvalidated — own risk),`);
+      lines.push("         or opt into streamMode \"eager-relay\" via PUT /api/settings (crash risk on this runtime; see docs).");
+    }
   }
   return lines;
 }
@@ -671,11 +730,21 @@ export function proxyDownRestartHint(input: {
   proxyRunning: boolean;
   port: number;
   serviceViable: boolean;
+  /** Absent means "unknown"; the hint then keeps its pre-repair wording. */
+  serviceInstalled?: boolean;
+  serviceConflict?: boolean;
 }): string | null {
   if (input.proxyRunning) return null;
+  // `serviceViable` alone conflates "no service at all" with "registered but stale or
+  // stopped". Only the first wants `install`: re-registering an existing service costs a
+  // UAC prompt on Windows and can switch a WinSW backend to Task Scheduler. A conflict
+  // still needs uninstall-then-install, which repairService() refuses outright.
+  const installedButBroken = input.serviceInstalled === true && input.serviceConflict !== true;
   const restart = input.serviceViable
     ? "Restart it with 'ocx service start' (service installed) or 'ocx start'."
-    : "Restart it with 'ocx start', or install the persistent service: 'ocx service install'.";
+    : installedButBroken
+      ? "Restart it with 'ocx start', or refresh the installed service: 'ocx service repair'."
+      : "Restart it with 'ocx start', or install the persistent service: 'ocx service install'.";
   return `The ocx proxy is not running. Codex/Claude clients pinned to 127.0.0.1:${input.port} fail with errors like "error sending request for url (http://127.0.0.1:${input.port}/v1/responses)". ${restart}`;
 }
 
@@ -891,6 +960,8 @@ export async function runDoctor(args: string[] = []): Promise<void> {
     proxyRunning: Boolean(live),
     port: live?.port ?? doctorConfig.port ?? 10100,
     serviceViable: startup.serviceViable,
+    serviceInstalled: startup.serviceInstalled,
+    serviceConflict: startup.serviceConflict,
   });
   if (proxyDown) hints.push(proxyDown);
   for (const row of providerApiKeys) {

package/src/cli/export-command.ts

@@ -1,13 +1,19 @@
 /**
- * `ocx export --client <opencode|pi>` — print a client config for the live proxy.
+ * `ocx export --client <id>` — print a client config for the live proxy.
+ *
+ * Six clients, four formats: opencode and Pi are JSON, Hermes and Gajae YAML,
+ * OpenClaw JSON5, Kimi TOML.
  *
  * Two consumers, one payload (devlog 260731_client_config_export/020):
  *
- * - **Agent** (`--json`): stdout is exactly the client config JSON and nothing else, so
- *   `ocx export --client pi --json > models.json` is safe to pipe. Every diagnostic —
- *   including the `--out` write note — goes to stderr.
- * - **Human** (no flag): the JSON leads, then the destination path, the merge warning,
- *   the env export line, and the model/degraded counts.
+ * - **Agent** (`--json`): stdout is exactly the client config as JSON and nothing else,
+ *   so `ocx export --client pi --json > models.json` is safe to pipe. This is JSON for
+ *   every client, including the YAML/JSON5/TOML ones — the flag is about machine
+ *   readability, not the client's native format. Every diagnostic — including the
+ *   `--out` write note — goes to stderr.
+ * - **Human** (no flag) and `--out`: the client's NATIVE serialization leads, then the
+ *   destination path, the merge warning, the env export line, and the model/degraded
+ *   counts.
  *
  * The command never writes the user's real config path. `--out` is an explicit target and
  * refuses to clobber an existing file without `--force`, because the common mistake
@@ -15,14 +21,15 @@
  *
  * Serialization itself belongs to src/clients/config-export.ts; this module only resolves
  * the base URL, filters the catalog, and renders. No secret is ever serialized: the config
- * carries the client's documented env reference and the real key stays in the environment.
+ * carries the client's documented env reference — or, for Kimi, which cannot hold one, a
+ * loopback placeholder — and the real key stays in the environment.
  */
 import { writeFileSync } from "node:fs";
 import { loadConfig } from "../config";
 import {
   EXPORT_CLIENTS,
   EXPORT_CLIENT_IDS,
-  buildClientConfig,
+  buildClientConfigText,
   isExportClientId,
   opencodeProxyBaseUrl,
   type ExportClientId,
@@ -164,16 +171,23 @@ export async function handleExportCommand(argv: string[], deps: ExportCommandDep
       throw new RuntimeApiError("Management API returned an unexpected /api/models payload.", 502, rows);
     }
     const models = exportModelsFromProxyRows(rows, config);
-    const clientConfig = buildClientConfig(client, { baseUrl: proxyV1BaseUrl(root), models, config });
-    const text = JSON.stringify(clientConfig, null, 2);
+    // The text is the client's OWN format — YAML, TOML and JSON5 clients would
+    // otherwise receive a JSON rendering their parser reads differently.
+    const built = buildClientConfigText(client, { baseUrl: proxyV1BaseUrl(root), models, config });
+    const clientConfig = built.document;
+    const text = built.text;
 
-    if (out !== undefined) writeExport(out, `${text}\n`, force);
+    // Every serializer already ends with exactly one newline.
+    if (out !== undefined) writeExport(out, text, force);
     // stderr, so `--json` stdout stays byte-exact for a redirect.
     if (out !== undefined && wantsJson) console.error(`Wrote ${out}`);
 
     const degraded = models.filter(model => !hasContextLimit(model)).length;
+    // `--json` keeps emitting the DOCUMENT at the top level: a script that
+    // pipes it into a config file must not have to unwrap an envelope we added
+    // for our own convenience. Format metadata rides in the human lines below.
     printData(clientConfig, wantsJson, [
-      text,
+      text.trimEnd(),
       "",
       ...(out !== undefined ? [`Wrote ${out}`] : []),
       `Destination: ${spec.destination(process.env)}`,

package/src/cli/help.ts

@@ -110,7 +110,7 @@ const helpEntries: Record<string, HelpEntry> = {
     ],
   },
   account: {
-    usage: "ocx account <list|current|use|refresh|auto-switch|login|reauth|code|cancel|remove|add-key|reset-credits> ...",
+    usage: "ocx account <list|current|use|refresh|auto-switch|login|reauth|code|cancel|remove|add-key|reset-credits|main> ...",
     summary: "List and switch provider accounts and API-key pools (GUI parity).",
     details: [
       "list [provider]     Codex account pool, OAuth accounts and API keys (identifiers shown masked as the API returns them).",
@@ -122,6 +122,7 @@ const helpEntries: Record<string, HelpEntry> = {
       "add-key <provider> [--label <label>]  Add a key read only from piped stdin.",
       "login/reauth/code/cancel  Run browser or manual-code auth from a headless shell.",
       "reset-credits <id|main> [--consume --yes]  Inspect or consume Codex reset credits.",
+      "main <subcommand>     Manage the physical native Codex login separately from Pool routing.",
       "Codex pool selection applies to the next request after clearing existing affinity; in-flight requests keep their captured account.",
     ],
   },
@@ -170,17 +171,17 @@ const helpEntries: Record<string, HelpEntry> = {
   },
   "api-key": { usage: "ocx api-key <list|create|remove> ...", summary: "Alias of ocx access key." },
   export: {
-    usage: "ocx export --client <opencode|pi> [--json] [--out <path>] [--force]",
-    summary: "Print a client config (opencode, Pi) wired to the running proxy.",
+    usage: "ocx export --client <opencode|pi|hermes|openclaw|kimi|gajae> [--json] [--out <path>] [--force]",
+    summary: "Print a client config (opencode, Pi, Hermes, OpenClaw, Kimi Code, Gajae Code) wired to the running proxy.",
     details: [
       "--json prints only the config JSON on stdout, so it is safe to redirect to a file.",
       "--out <path> writes the config there and refuses to replace an existing file without --force.",
-      "The config never contains a key; it references the client's env var, which you export before launching.",
+      "The config never contains a key; it references the client's env var, which you export before launching. Kimi cannot hold an env reference, so it carries a loopback placeholder instead.",
       "The destination path is printed for merging by hand — ocx never writes your real client config.",
     ],
   },
   grok: { usage: "ocx grok <status|exclude|include|set|clear|apply> ...", summary: "Manage and apply the Grok Build model fence." },
-  integration: { usage: "ocx integration <claude|grok> ...", summary: "Manage supported client integrations." },
+  integration: { usage: "ocx integration <claude|grok|client> ...", summary: "Manage supported client integrations." },
   system: {
     usage: "ocx system <status|settings|startup|diagnostics|sync|update> ...",
     summary: "Manage headless runtime settings, startup, sync, diagnostics, and updates.",
@@ -296,7 +297,8 @@ Usage:
   ocx agent <sub>             Subagents, injection, effort caps, and sidecars
   ocx observe <sub>           Logs, usage, storage, memory, and debug data
   ocx access <sub>            External API keys and endpoint information
-  ocx export --client <id>    Print an opencode/Pi config wired to the running proxy
+  ocx export --client <id>    Print a client config wired to the running proxy (6 clients)
+  ocx integration client <sub> Enable, disable, inspect or roll back a client integration
   ocx grok <sub>              Grok Build model selection and apply
   ocx system <sub>            Runtime settings, startup, sync, and updates
   ocx config <sub>            Validated configuration show/get/set/import/export

package/src/cli/index.ts

@@ -1,8 +1,8 @@
 #!/usr/bin/env bun
 import { spawn } from "node:child_process";
-import { currentExternalCodexModelProvider, restoreNativeCodex, shouldInjectApiAuthHeader } from "../codex/inject";
+import { currentExternalCodexModelProvider, restoreNativeCodex, restoreNativeCodexAsync, shouldInjectApiAuthHeader } from "../codex/inject";
 import { stripGrokConfig } from "../grok/inject";
-import { restoreLegacyOpenaiHistory } from "../codex/history-provider";
+import { resolveCodexHistoryJobTarget, runCodexHistoryJob } from "../codex/history-job";
 import { reconcileJournal } from "../codex/journal";
 import {
   codexAutoStartEnabled,
@@ -41,9 +41,11 @@ import { maybeShowStarPrompt } from "./star-prompt";
 import { scheduleCatalogPrewarm } from "./catalog-prewarm";
 import { maybeShowUpdatePrompt } from "../update/notify";
 import { syncModelsToCodex } from "../codex/sync";
+import { shouldSyncGrokOnStart, syncCodexOnStartIfEnabled } from "../codex/desired-state";
 import { normalizeUpdateChannel, runGuiUpdateWorker } from "../update/job";
 import { collectOrcaCodexHomeDiagnostic } from "../codex/home";
 import { removeOwnedConfigState } from "../lib/config-ownership";
+import { withProcessRuntimeProvenance } from "../lib/bun-runtime";
 
 const args = process.argv.slice(2);
 const command = args[0];
@@ -315,7 +317,7 @@ async function handleStart(options: { block?: boolean } = {}) {
   installShellHook();
 
   await maybeShowStarPrompt(); // once-only Yes/No GitHub-star prompt on first interactive start
-  await syncModelsToCodex(port).catch(() => {});
+  await syncCodexOnStartIfEnabled(port, config);
   if (!currentExternalCodexModelProvider() && !shouldInjectApiAuthHeader(config) && config.syncResumeHistory !== false) {
     historyGuardian = startHistoryMigrationGuardian();
   }
@@ -335,7 +337,10 @@ async function handleStart(options: { block?: boolean } = {}) {
   // absent or the bind is non-loopback; removed again by stop/eject/uninstall/shutdown.
   // Deliberately a SIBLING of the Desktop-3P block above: nesting it there meant a catalog
   // failure skipped the fence entirely, even though syncGrokConfig handles that case itself.
-  try {
+  //
+  // Gated on the persisted switch: without this, turning Grok off lasted exactly
+  // one restart, because the toggle removed the fence and start wrote it back.
+  if (shouldSyncGrokOnStart(config)) try {
     const { syncGrokConfig } = await import("../grok/sync");
     const r = await syncGrokConfig(port, config, config.hostname ? { hostname: config.hostname } : {});
     if (r.changed) console.log("   + Grok Build config updated (~/.grok/config.toml)");
@@ -385,7 +390,7 @@ async function handleEnsure() {
     detached: true,
     stdio: "ignore",
     windowsHide: true,
-    env: { ...process.env, OCX_SERVICE: "1" },
+    env: withProcessRuntimeProvenance({ ...process.env, OCX_SERVICE: "1" }),
   });
   child.unref();
 
@@ -427,7 +432,7 @@ async function handleTrayProxyStart(): Promise<void> {
         detached: true,
         stdio: "ignore",
         windowsHide: true,
-        env: { ...process.env, OCX_SERVICE: "1" },
+        env: withProcessRuntimeProvenance({ ...process.env, OCX_SERVICE: "1" }),
       });
       child.unref();
     },
@@ -524,7 +529,7 @@ async function handleStop() {
     }
   }
   if (!ownershipBlocked) {
-    const r = restoreNativeCodex();
+    const r = await restoreNativeCodexAsync();
     if (r.success) console.log(`↩️  ${r.message}`);
     else {
       stopFailed = true;
@@ -586,8 +591,8 @@ async function handleUninstall() {
     });
   }
 
-  await runStep("native Codex restored", () => {
-    const r = restoreNativeCodex();
+  await runStep("native Codex restored", async () => {
+    const r = await restoreNativeCodexAsync();
     if (!r.success) throw new Error(r.message);
   });
 
@@ -659,7 +664,14 @@ async function handleStatus() {
   console.log(`   Health: ${status.healthLabel}`);
   if (!(status.json.proxy.pid || status.json.proxy.health.ok)) {
     console.log("   ↳ Not running — Codex/Claude requests will fail with connection errors.");
-    console.log("     Restart with 'ocx start', or install the persistent service: 'ocx service install'.");
+    // The service summary a few lines below already tells a registered-but-not-serving
+    // user to repair. Printing "install the persistent service" unconditionally
+    // contradicted it in the same report, and install re-registers: UAC on Windows and a
+    // possible WinSW-to-scheduler switch for someone who already has a service.
+    const installed = status.json.startup.serviceInstalled && !status.json.startup.serviceConflict;
+    console.log(installed
+      ? "     Restart with 'ocx start', or refresh the installed service: 'ocx service repair'."
+      : "     Restart with 'ocx start', or install the persistent service: 'ocx service install'.");
   }
   console.log(`   Dashboard: ${status.json.dashboard.url}`);
   console.log(`   Config: ${status.json.paths.config}`);
@@ -707,13 +719,22 @@ async function handleStatus() {
   }
 }
 
-function handleRecoverHistory() {
+async function handleRecoverHistory() {
   if (args[1] !== "--legacy-openai") {
     console.error("Usage: ocx recover-history --legacy-openai");
     console.error("Only use this if an older syncResumeHistory build already remapped OpenAI Codex App history to opencodex before backup support existed.");
     process.exit(1);
   }
-  const r = restoreLegacyOpenaiHistory();
+  // Manifest-independent legacy ejection, serialized like every other history
+  // mutation. It is a separate operation from generic restore precisely because
+  // it must not read, consume or replace the backup manifest.
+  const outcome = await runCodexHistoryJob({
+    ...resolveCodexHistoryJobTarget(),
+    operation: "recover-legacy-openai",
+  });
+  const r = outcome.kind === "converged"
+    ? { rows: outcome.rows, files: outcome.files, failed: undefined }
+    : { rows: 0, files: 0, failed: true as const };
   if (r.failed) {
     console.error(
       "⚠️  Recovery SKIPPED: the Codex history DB is locked (Codex app/IDE open?). Close it and rerun this command.",
@@ -764,7 +785,7 @@ switch (command) {
     }
     let r: { success: boolean; message: string };
     try {
-      r = restoreNativeCodex();
+      r = await restoreNativeCodexAsync();
     } catch (err) {
       r = { success: false, message: err instanceof Error ? err.message : String(err) };
     }
@@ -789,7 +810,7 @@ switch (command) {
     break;
   }
   case "recover-history":
-    handleRecoverHistory();
+    await handleRecoverHistory();
     break;
   case "uninstall":
   case "remove":
@@ -847,9 +868,14 @@ switch (command) {
   }
   case "sync-cache": {
     const restartCodex = args.slice(1).includes("--restart-codex");
-    const { invalidateCodexModelsCache } = await import("../codex/catalog");
+    const { withCatalogWriteSerialization } = await import("../codex/catalog-write-serialization");
+    const { invalidateCodexModelsCacheWithPermit } = await import("../codex/catalog/sync");
+    const { getCodexHome } = await import("../codex/paths");
+    const owningCodexHome = getCodexHome();
+    const invalidated = withCatalogWriteSerialization(owningCodexHome, permit =>
+      invalidateCodexModelsCacheWithPermit(permit, owningCodexHome));
     // Only warn/restart when models_cache was actually rewritten from a readable catalog.
-    if (invalidateCodexModelsCache()) {
+    if (invalidated.kind === "completed" && invalidated.value) {
       const { afterCatalogWriteHandleAppServers } = await import("../codex/app-server-processes");
       afterCatalogWriteHandleAppServers({ restart: restartCodex, log: console });
     }
@@ -867,7 +893,7 @@ switch (command) {
         detached: true,
         stdio: "ignore",
         windowsHide: true,
-        env: process.env,
+        env: withProcessRuntimeProvenance(process.env),
       });
       child.unref();
       live = await waitForProxy();
@@ -999,13 +1025,18 @@ switch (command) {
     break;
   }
   case "route": {
-    if (args[1] !== "combo") {
-      console.error("Usage: ocx route combo <subcommand>");
+    if (args[1] !== "combo" && args[1] !== "policy") {
+      console.error("Usage: ocx route <combo|policy> <subcommand>");
       process.exitCode = 2;
       break;
     }
-    const { handleComboCommand } = await import("./combo");
-    process.exitCode = await handleComboCommand(args.slice(2));
+    if (args[1] === "combo") {
+      const { handleComboCommand } = await import("./combo");
+      process.exitCode = await handleComboCommand(args.slice(2));
+    } else {
+      const { handleRoutePolicyCommand } = await import("./route-policy");
+      process.exitCode = await handleRoutePolicyCommand(args.slice(2));
+    }
     break;
   }
   case "agent": {
@@ -1054,8 +1085,11 @@ switch (command) {
     } else if (integration === "claude") {
       const { handleClaudeConfigCommand } = await import("./integrations");
       process.exitCode = await handleClaudeConfigCommand(args.slice(2));
+    } else if (integration === "client") {
+      const { handleClientIntegrationCommand } = await import("./integrations");
+      process.exitCode = await handleClientIntegrationCommand(args.slice(2));
     } else {
-      console.error("Usage: ocx integration <claude|grok> <subcommand>");
+      console.error("Usage: ocx integration <claude|grok|client> <subcommand>");
       process.exitCode = 2;
     }
     break;

package/src/cli/integrations.ts

@@ -27,6 +27,12 @@ const GROK_USAGE = `Usage:
   ocx grok clear [--json]
   ocx grok apply [--json]`;
 
+const CLIENT_USAGE = `Usage:
+  ocx integration client [status] [--client <id>] [--json]
+  ocx integration client <enable|disable> --client <id> [--json]
+  ocx integration client history [--client <id>] [--json]
+  ocx integration client restore --op <opId> [--confirm-drift] [--json]`;
+
 function parseMap(raw: string): Record<string, string> {
   if (raw === "-") return {};
   const map: Record<string, string> = {};
@@ -139,4 +145,81 @@ export async function handleGrokCommand(argv: string[], deps: RuntimeApiDeps = {
   });
 }
 
-export const INTEGRATION_USAGE = { claude: CLAUDE_USAGE, grok: GROK_USAGE };
+/**
+ * The headless half of the client-integration toggle.
+ *
+ * Every safety property lives behind the management API — ownership, the
+ * pre-write snapshot, the journal, the drift refusal — so this command is a
+ * thin caller and deliberately re-implements none of it. That is also why
+ * `restore` surfaces the drift refusal as an error telling the user to pass
+ * `--confirm-drift` rather than retrying on their behalf: replacing edits a
+ * user made after the snapshot is exactly the decision they have to make.
+ */
+export async function handleClientIntegrationCommand(
+  argv: string[],
+  deps: RuntimeApiDeps = {},
+): Promise<number> {
+  return runCliAction(async () => {
+    const args = [...argv];
+    const action = (args.shift() ?? "status").toLowerCase();
+    const wantsJson = takeFlag(args, "--json");
+
+    if (action === "status" || action === "show" || action === "list") {
+      const client = takeOption(args, "--client");
+      rejectArgs(args, CLIENT_USAGE);
+      const path = client
+        ? `/api/client-integrations/${encodeURIComponent(client)}`
+        : "/api/client-integrations";
+      const result = await runtimeRequest(path, {}, deps);
+      const rows = (result as { clients?: Array<Record<string, unknown>> }).clients;
+      printData(result, wantsJson, rows
+        ? rows.map(row => `${String(row.clientId)}: ${String(row.state)}${row.installed ? "" : " (not installed)"}`)
+        : summaryLines(result));
+      return;
+    }
+
+    if (action === "history" || action === "journal") {
+      const client = takeOption(args, "--client");
+      rejectArgs(args, CLIENT_USAGE);
+      const query = client ? `?client=${encodeURIComponent(client)}` : "";
+      const result = await runtimeRequest(`/api/client-integrations/journal${query}`, {}, deps);
+      const operations = (result as { operations?: Array<Record<string, unknown>> }).operations ?? [];
+      printData(result, wantsJson, operations.length === 0
+        ? ["No integration operations recorded yet."]
+        : operations.map(row => {
+          // `snapshot` is resolved against the disk by the route, so "expired"
+          // here means the bytes are genuinely gone, not merely old.
+          const backup = row.snapshot === "expired" ? "backup expired" : `op ${String(row.opId)}`;
+          return `${String(row.at)}  ${String(row.clientId)}  ${String(row.kind)}  (${backup})`;
+        }));
+      return;
+    }
+
+    if (action === "restore") {
+      const opId = takeOption(args, "--op") ?? takeOption(args, "--op-id");
+      const confirmDrift = takeFlag(args, "--confirm-drift");
+      rejectArgs(args, CLIENT_USAGE);
+      if (!opId) throw new CliUsageError("--op <opId> is required", CLIENT_USAGE);
+      const result = await runtimeRequest("/api/client-integrations/restore", {
+        method: "POST",
+        body: JSON.stringify({ opId, confirmDrift }),
+      }, deps);
+      printData(result, wantsJson, [String((result as Record<string, unknown>).message ?? "Restored.")]);
+      return;
+    }
+
+    if (action !== "enable" && action !== "disable") {
+      throw new CliUsageError(`unknown client integration command ${action}`, CLIENT_USAGE);
+    }
+    const client = takeOption(args, "--client");
+    rejectArgs(args, CLIENT_USAGE);
+    if (!client) throw new CliUsageError("--client <id> is required", CLIENT_USAGE);
+    const result = await runtimeRequest(`/api/client-integrations/${encodeURIComponent(client)}`, {
+      method: "PUT",
+      body: JSON.stringify({ enabled: action === "enable" }),
+    }, deps);
+    printData(result, wantsJson, [String((result as Record<string, unknown>).message ?? `${client} ${action}d.`)]);
+  });
+}
+
+export const INTEGRATION_USAGE = { claude: CLAUDE_USAGE, grok: GROK_USAGE, client: CLIENT_USAGE };