@bitkyc08/opencodex 2.12.0 → 2.13.0

package/src/cli/dispatch.ts

@@ -0,0 +1,532 @@
+/**
+ * Registry-driven command dispatch (Phase 3 of the CLI deepening).
+ *
+ * The command switch moved out of src/cli/index.ts into a runner table keyed
+ * by command name. Aliases resolve through the registry's alias pairs
+ * (init/setup, restore/eject, uninstall/remove, models/model); the registry
+ * remains the single source of command metadata. index.ts passes its local
+ * helpers (start/stop/ensure/status/...) through CliDispatchDeps so dispatch
+ * never needs to import the entry module back (no cycle).
+ */
+import { CLI_COMMANDS } from "./registry";
+import type { CliHead } from "./root";
+import type { ReadyArgs } from "./ready";
+import type { LiveProxy } from "../server/proxy-liveness";
+import type { OcxConfig } from "../types";
+import { hasHelpFlag, printSubcommandUsage, printUsage } from "./help";
+import { setIntegrationEnabled, shouldSyncCodexOnStart } from "../codex/desired-state";
+import { syncModelsToCodex } from "../codex/sync";
+import { collectOrcaCodexHomeDiagnostic } from "../codex/home";
+import { restoreNativeCodexAsync } from "../codex/inject";
+import { stripGrokConfig } from "../grok/inject";
+import { afterCatalogWriteHandleAppServers } from "../codex/app-server-processes";
+import { normalizeUpdateChannel, runGuiUpdateWorker } from "../update/job";
+import { serviceCommand } from "../service";
+
+export interface CliDispatchDeps {
+  args: string[];
+  command: string | undefined;
+  head: CliHead;
+  loadConfig: () => OcxConfig;
+  findLiveProxy: () => Promise<LiveProxy | null>;
+  probeHostname: (hostname: string | undefined) => string;
+  waitForProxy: (timeoutMs?: number) => Promise<LiveProxy | null>;
+  startArgv: (port?: number) => string[];
+  /** Spawn a detached proxy child (stdio ignore, unref'd, provenance env). */
+  spawnDetached: (argv: readonly string[]) => void;
+  handleStart: () => Promise<void>;
+  handleStop: () => Promise<boolean>;
+  handleEnsure: (options?: { existingIsSuccess?: boolean }) => Promise<boolean>;
+  handleTrayProxyStart: (existingIsSuccess?: boolean) => Promise<boolean>;
+  handleTrayProxyRestart: () => Promise<void>;
+  handleRestartStartWhenStopped: () => Promise<boolean | "skipped">;
+  handleProxyRestart: (startWhenStopped: () => Promise<boolean | "skipped">) => Promise<boolean>;
+  handleUninstall: () => Promise<void>;
+  handleStatus: () => Promise<void>;
+  handleRecoverHistory: () => Promise<void>;
+  handleReady: (args: ReadyArgs) => Promise<number>;
+}
+
+type CommandRunner = (deps: CliDispatchDeps) => Promise<number>;
+
+const commandRunners: Record<string, CommandRunner> = {
+  init: async () => {
+    const { runInit } = await import("./init");
+    await runInit();
+    // runInit sets process.exitCode = 1 on stdin EOF/closed; preserve it.
+    return Number(process.exitCode ?? 0);
+  },
+  start: async deps => {
+    await deps.handleStart();
+    return Number(process.exitCode ?? 0);
+  },
+  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').");
+    }
+    return Number(process.exitCode ?? 0);
+  },
+  restore: async deps => {
+    const restoreJson = deps.args[1] === "--json";
+    if (deps.args[1] === "back") {
+      // Reverse switch: re-point plain `codex` at the RUNNING proxy without touching its
+      // lifecycle — the counterpart of `ocx restore`. Start/stop triggers are unchanged;
+      // this only re-runs the same inject (config + catalog + history) `ocx start` does.
+      const live = await deps.findLiveProxy();
+      if (!live) {
+        console.error("No running proxy found. Run 'ocx start' — it injects opencodex automatically.");
+        return 1;
+      }
+      const desired = setIntegrationEnabled("codex", true);
+      if (!desired.ok) {
+        console.error(`Codex desired state was not saved (${desired.reason}).`);
+        return desired.reason === "conflict" ? 2 : 1;
+      }
+      const synced = await syncModelsToCodex(live.port);
+      if (synced.status === "skipped") {
+        console.error("Codex integration is OFF; restore back did not change Codex. Retry after the competing integration change finishes.");
+        return 2;
+      }
+      if (!synced.ok) {
+        console.error("Plain `codex` was not switched back to opencodex. Fix the reported Codex config issue and retry.");
+        return 1;
+      }
+      const target = collectOrcaCodexHomeDiagnostic();
+      console.log(`Plain \`codex\` now routes through opencodex in ${target.effectiveCodexHome} (undo with: ocx restore).`);
+      return 0;
+    }
+    const desired = setIntegrationEnabled("codex", false);
+    if (!desired.ok) {
+      if (restoreJson) {
+        // Machine-readable contract: every restore --json outcome emits one
+        // schema-complete envelope on stdout, including pre-machinery failures.
+        const { skippedRestoreEnvelope } = await import("../codex/inject");
+        console.log(JSON.stringify(skippedRestoreEnvelope(false, `Codex desired state was not saved (${desired.reason}).`)));
+      } else {
+        console.error(`Codex desired state was not saved (${desired.reason}).`);
+      }
+      return desired.reason === "conflict" ? 2 : 1;
+    }
+    // A repeated OFF on an already-clean home is a policy no-op. Do not enter
+    // restore's native-profile machinery merely to prove there is nothing to
+    // restore: those locks live in CODEX_HOME and a skip must create nothing.
+    if (desired.status === "unchanged") {
+      const { classifyNativeRoutedResidue } = await import("../codex/native-residue");
+      if (classifyNativeRoutedResidue().kind === "clean") {
+        const alreadyOff = "Codex integration is already OFF and native; no Codex files changed.";
+        if (restoreJson) {
+          const { skippedRestoreEnvelope } = await import("../codex/inject");
+          console.log(JSON.stringify(skippedRestoreEnvelope(true, alreadyOff)));
+        } else {
+          console.log(alreadyOff);
+        }
+        return 0;
+      }
+    }
+    let r: { success: boolean; message: string };
+    try {
+      r = await restoreNativeCodexAsync({ revalidateDesiredState: true });
+    } catch (err) {
+      r = { success: false, message: err instanceof Error ? err.message : String(err) };
+    }
+    if (restoreJson) {
+      // Spawned callers need the artifact-level result to distinguish a busy
+      // history worker from a successful native restore. Keep stdout machine
+      // readable; human framing remains the default command contract.
+      console.log(JSON.stringify(r));
+      return r.success ? 0 : 1;
+    }
+    if (r.success) console.log(`✅ ${r.message}`);
+    else {
+      console.error(`⚠️  ${r.message}`);
+    }
+    let code = r.success ? 0 : 1;
+    try {
+      const g = stripGrokConfig();
+      if (g.changed) console.log(`✅ ${g.message}`);
+      else if (!g.ok) {
+        console.error(`⚠️  ${g.message}`);
+        code = 1;
+      }
+    } catch { /* best-effort */ }
+    if (r.success) {
+      console.log("Codex integration is OFF and plain `codex` now runs natively. Switch back with: ocx restore back");
+    } else {
+      console.error("Plain `codex` was not fully restored. Inspect $CODEX_HOME/config.toml before using native Codex.");
+    }
+    return code;
+  },
+  "recover-history": async deps => {
+    await deps.handleRecoverHistory();
+    return Number(process.exitCode ?? 0);
+  },
+  uninstall: async deps => {
+    await deps.handleUninstall();
+    return Number(process.exitCode ?? 0);
+  },
+  status: async deps => {
+    await deps.handleStatus();
+    return Number(process.exitCode ?? 0);
+  },
+  doctor: async deps => {
+    const { runDoctor } = await import("./doctor");
+    await runDoctor(deps.args.slice(1));
+    return 0;
+  },
+  debug: async deps => {
+    const { handleDebugCommand } = await import("./debug");
+    await handleDebugCommand(deps.args.slice(1));
+    return 0;
+  },
+  ensure: async deps => {
+    await deps.handleEnsure();
+    return Number(process.exitCode ?? 0);
+  },
+  login: async deps => {
+    const { handleLogin } = await import("../oauth/login-cli");
+    await handleLogin(deps.args[1]);
+    return 0;
+  },
+  logout: async deps => {
+    const { removeCredential } = await import("../oauth/store");
+    const name = (deps.args[1] ?? "").trim().toLowerCase();
+    await removeCredential(name);
+    console.log(`Logged out of ${name || "(none)"}.`);
+    return 0;
+  },
+  sync: async deps => {
+    const restartCodex = deps.args.slice(1).includes("--restart-codex");
+    const synced = await syncModelsToCodex((await deps.findLiveProxy())?.port);
+    let code = 0;
+    if (synced.status === "skipped") {
+      console.log("Codex integration is OFF; sync skipped and no Codex files changed.");
+    } else if (!synced.ok) {
+      code = 1;
+      console.error("Codex sync did not complete. Fix the reported Codex config issue and retry.");
+    }
+    // Only warn/restart when a catalog or models_cache write actually happened. This is
+    // deliberately not an `else`: refreshCodexModelCatalog runs before injectCodexConfig,
+    // so a sync can fail (`ok: false`) after the catalog was already rewritten — which is
+    // exactly when a long-lived app-server is holding the stale list.
+    if (synced.catalogWritten || synced.cacheSynced) {
+      afterCatalogWriteHandleAppServers({ restart: restartCodex, log: console });
+    }
+    return code;
+  },
+  v2: async deps => {
+    const { cmdV2 } = await import("./v2");
+    return await cmdV2(deps.args.slice(1), {}, async () => (await deps.findLiveProxy())?.port);
+  },
+  "sync-cache": async deps => {
+    const restartCodex = deps.args.slice(1).includes("--restart-codex");
+    if (!shouldSyncCodexOnStart(deps.loadConfig())) {
+      console.log("Codex integration is OFF; cache sync skipped and no Codex files changed.");
+      return 0;
+    }
+    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 (invalidated.kind === "completed" && invalidated.value) {
+      afterCatalogWriteHandleAppServers({ restart: restartCodex, log: console });
+    }
+    return 0;
+  },
+  gui: async deps => {
+    const config = deps.loadConfig();
+    // Identity-checked liveness (not the pid file + a fixed sleep): finds a fallback-port
+    // proxy and waits until the spawned one actually answers before opening the browser.
+    let live = await deps.findLiveProxy();
+    if (!live) {
+      console.log("Proxy not running. Starting...");
+      deps.spawnDetached(deps.startArgv((config.port ?? 10100) > 0 ? (config.port ?? 10100) : undefined));
+      live = await deps.waitForProxy();
+      if (!live) {
+        console.error("❌ Proxy did not become healthy after starting. Not opening the GUI.");
+        return 1;
+      }
+    }
+    // Open the host the proxy actually binds — `localhost` only answers for
+    // loopback/wildcard binds, not a concrete LAN/IPv6 hostname.
+    const guiHost = deps.probeHostname(live?.hostname ?? config.hostname);
+    const guiUrl = `http://${guiHost === "127.0.0.1" ? "localhost" : guiHost}:${live?.port ?? config.port}`;
+    console.log(`Opening ${guiUrl}`);
+    const { openUrl } = await import("../lib/open-url");
+    openUrl(guiUrl);
+    return 0;
+  },
+  service: async deps => {
+    await serviceCommand(...deps.args.slice(1));
+    return 0;
+  },
+  tray: async deps => {
+    const { windowsTrayCommand } = await import("../tray/windows");
+    await windowsTrayCommand(deps.args.slice(1));
+    return 0;
+  },
+  "codex-shim": async deps => {
+    const { codexShimStatus, diagnoseCodexShim, installCodexShim, uninstallCodexShim } = await import("../codex/shim");
+    switch (deps.args[1]) {
+      case "install": {
+        const r = installCodexShim();
+        const { collectCodexShimReadinessWarnings } = await import("./codex-shim-readiness");
+        const warnings = diagnoseCodexShim().healthy
+          ? collectCodexShimReadinessWarnings()
+          : [];
+        console.log(`${r.installed && warnings.length === 0 ? "✅ " : "⚠️  "}${r.message}`);
+        for (const warning of warnings) console.warn(`   ${warning}`);
+        break;
+      }
+      case "status":
+        console.log(codexShimStatus());
+        break;
+      case "uninstall":
+      case "remove": {
+        const r = uninstallCodexShim();
+        console.log(r.removed ? `✅ ${r.message}` : `⚠️  ${r.message}`);
+        break;
+      }
+      default:
+        console.error("Usage: ocx codex-shim <install|status|uninstall|remove>");
+        return 1;
+    }
+    return 0;
+  },
+  update: async deps => {
+    // `ocx update --help` must print usage and exit WITHOUT side effects — running the
+    // real self-update stops the proxy and drops in-flight routed streams (issue #168).
+    if (hasHelpFlag(deps.args.slice(1))) {
+      printSubcommandUsage("update");
+      return 0;
+    }
+    const { runUpdate } = await import("../update");
+    await runUpdate();
+    return 0;
+  },
+  "__refresh-version": async deps => {
+    // Hidden, detached helper spawned by the update prompt to refresh the
+    // cached latest version without blocking the foreground start. Not in help.
+    const { refreshVersionCache } = await import("../update/notify");
+    const channel = deps.args[1] === "preview" ? "preview" : "latest";
+    await refreshVersionCache(channel);
+    return 0;
+  },
+  "__tray-start": async deps => {
+    return (await deps.handleTrayProxyStart()) ? 0 : 1;
+  },
+  "__tray-restart": async deps => {
+    await deps.handleTrayProxyRestart();
+    return Number(process.exitCode ?? 0);
+  },
+  "__startup-health": async deps => {
+    const { collectStartupHealth } = await import("../codex/autostart-health");
+    console.log(JSON.stringify(collectStartupHealth(deps.loadConfig())));
+    return 0;
+  },
+  "__tray-host": async () => {
+    const { runWindowsTrayHost } = await import("../tray/windows");
+    await runWindowsTrayHost();
+    return 0;
+  },
+  "__gui-update-worker": async deps => {
+    const jobId = deps.args[1];
+    if (!jobId) return 1;
+    const channel = normalizeUpdateChannel(deps.args[2]);
+    await runGuiUpdateWorker(jobId, channel, deps.args[3] === "restart");
+    return 0;
+  },
+  restart: async deps => {
+    // The running proxy owns its drain and replacement through /api/system/restart.
+    // If nothing is live, restart degrades to the documented `ensure` start behavior.
+    await deps.handleProxyRestart(deps.handleRestartStartWhenStopped);
+    return Number(process.exitCode ?? 0);
+  },
+  health: async deps => {
+    const healthArgs = deps.args.slice(1);
+    const wantsHealthJson = healthArgs.includes("--json");
+    const live = await deps.findLiveProxy();
+    if (wantsHealthJson) {
+      console.log(JSON.stringify({ ok: !!live, pid: live?.pid ?? null, port: live?.port ?? null }));
+    } else {
+      console.log(live ? `Proxy healthy (PID ${live.pid}, port ${live.port})` : "Proxy not healthy");
+    }
+    return live ? 0 : 1;
+  },
+  ready: async deps => {
+    // Fail-closed impossible-state guard: readyArgs is populated by the
+    // preparse block in src/cli/root.ts before maybeAutoRestoreCodexShim, so
+    // reaching here without it means dispatch diverged. Refuse with code 64
+    // and perform NO I/O (no discovery/probe). process.exit is `never`,
+    // narrowing below.
+    const readyArgs = deps.head.readyArgs;
+    if (!readyArgs) return 64;
+    return await deps.handleReady(readyArgs);
+  },
+  provider: async deps => {
+    const { handleProviderCommand } = await import("./provider");
+    await handleProviderCommand(deps.args.slice(1));
+    return 0;
+  },
+  account: async deps => {
+    const { cmdAccount } = await import("./account");
+    return await cmdAccount(deps.args.slice(1));
+  },
+  models: async deps => {
+    const { handleModels } = await import("./models");
+    await handleModels(deps.args.slice(1));
+    return 0;
+  },
+  combo: async deps => {
+    const { handleComboCommand } = await import("./combo");
+    return await handleComboCommand(deps.args.slice(1));
+  },
+  route: async deps => {
+    if (deps.args[1] !== "combo" && deps.args[1] !== "policy") {
+      console.error("Usage: ocx route <combo|policy> <subcommand>");
+      return 2;
+    }
+    if (deps.args[1] === "combo") {
+      const { handleComboCommand } = await import("./combo");
+      return await handleComboCommand(deps.args.slice(2));
+    } else {
+      const { handleRoutePolicyCommand } = await import("./route-policy");
+      return await handleRoutePolicyCommand(deps.args.slice(2));
+    }
+  },
+  agent: async deps => {
+    const { handleAgentCommand } = await import("./agent");
+    return await handleAgentCommand(deps.args.slice(1));
+  },
+  observe: async deps => {
+    const { handleObserveCommand } = await import("./observe");
+    return await handleObserveCommand(deps.args.slice(1));
+  },
+  logs: async deps => {
+    const { handleObserveCommand } = await import("./observe");
+    return await handleObserveCommand([deps.command!, ...deps.args.slice(1)]);
+  },
+  usage: async deps => {
+    const { handleObserveCommand } = await import("./observe");
+    return await handleObserveCommand([deps.command!, ...deps.args.slice(1)]);
+  },
+  storage: async deps => {
+    const { handleObserveCommand } = await import("./observe");
+    return await handleObserveCommand([deps.command!, ...deps.args.slice(1)]);
+  },
+  memory: async deps => {
+    const { handleObserveCommand } = await import("./observe");
+    return await handleObserveCommand([deps.command!, ...deps.args.slice(1)]);
+  },
+  access: async deps => {
+    const { handleAccessCommand } = await import("./access");
+    return await handleAccessCommand(deps.args.slice(1));
+  },
+  "api-key": async deps => {
+    const { handleAccessCommand } = await import("./access");
+    return await handleAccessCommand(["key", ...deps.args.slice(1)]);
+  },
+  export: async deps => {
+    const { handleExportCommand } = await import("./export-command");
+    return await handleExportCommand(deps.args.slice(1));
+  },
+  grok: async deps => {
+    const { handleGrokCommand } = await import("./integrations");
+    return await handleGrokCommand(deps.args.slice(1));
+  },
+  integration: async deps => {
+    const integration = deps.args[1];
+    if (integration === "grok") {
+      const { handleGrokCommand } = await import("./integrations");
+      return await handleGrokCommand(deps.args.slice(2));
+    } else if (integration === "claude") {
+      const { handleClaudeConfigCommand } = await import("./integrations");
+      return await handleClaudeConfigCommand(deps.args.slice(2));
+    } else if (integration === "client") {
+      const { handleClientIntegrationCommand } = await import("./integrations");
+      return await handleClientIntegrationCommand(deps.args.slice(2));
+    } else {
+      console.error("Usage: ocx integration <claude|grok|client> <subcommand>");
+      return 2;
+    }
+  },
+  system: async deps => {
+    const { handleSystemCommand } = await import("./system-command");
+    return await handleSystemCommand(deps.args.slice(1));
+  },
+  config: async deps => {
+    const { handleConfigCommand } = await import("./config-command");
+    return await handleConfigCommand(deps.args.slice(1));
+  },
+  lab: async deps => {
+    const { handleLabCommand } = await import("./lab");
+    return await handleLabCommand(deps.args.slice(1));
+  },
+  claude: async deps => {
+    const { cmdClaude } = await import("./claude");
+    // "ocx claude desktop" → write Desktop 3P config
+    if (deps.args[1] === "desktop") {
+      const { handleClaudeDesktopCommand } = await import("./claude-desktop");
+      const exitCode = await handleClaudeDesktopCommand(deps.args.slice(2));
+      if (exitCode !== 0) return exitCode;
+      return 0;
+    }
+    if (deps.args[1] === "config") {
+      const { handleClaudeConfigCommand } = await import("./integrations");
+      return await handleClaudeConfigCommand(deps.args.slice(2));
+    }
+    return await cmdClaude(deps.args.slice(1));
+  },
+  opencode: async deps => {
+    const { cmdOpencode } = await import("./opencode");
+    return await cmdOpencode(deps.args.slice(1));
+  },
+  help: async () => {
+    printUsage();
+    return 0;
+  },
+  "--help": async () => {
+    printUsage();
+    return 0;
+  },
+  "-h": async () => {
+    printUsage();
+    return 0;
+  },
+};
+
+/** Registry alias pairs → canonical dispatch name (init/setup, restore/eject, …). */
+const aliasTargets = new Map<string, string>();
+for (const entry of CLI_COMMANDS) {
+  for (const alias of entry.aliases ?? []) aliasTargets.set(alias, entry.name);
+}
+
+export const DISPATCH_COMMANDS: ReadonlySet<string> = new Set(Object.keys(commandRunners));
+export const DISPATCH_ALIASES: ReadonlyMap<string, string> = aliasTargets;
+
+/** Resolve the runner key for a command, following registry aliases to the
+ * canonical runner. Returns undefined when the command is unknown. */
+export function resolveDispatchCommand(command: string | undefined): string | undefined {
+  if (command === undefined) return undefined;
+  if (Object.prototype.hasOwnProperty.call(commandRunners, command)) return command;
+  return aliasTargets.get(command);
+}
+
+export async function dispatchCommand(head: CliHead, deps: CliDispatchDeps): Promise<number> {
+  const command = head.command;
+  if (command === undefined || command === "help" || command === "--help" || command === "-h") {
+    printUsage();
+    return 0;
+  }
+  const runner = commandRunners[resolveDispatchCommand(command) ?? ""];
+  if (!runner) {
+    console.error(`Unknown command: ${command}`);
+    printUsage();
+    return 1;
+  }
+  return await runner(deps);
+}

package/src/cli/doctor.ts

@@ -10,14 +10,13 @@
 import { accessSync, constants, existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 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 { getConfigDir, getConfigPath, readConfigDiagnostics, readPid, resolveEnvValue } from "../config";
+import { findLiveProxy, type LiveProxy } from "../server/proxy-liveness";
 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 { LOCAL_MANAGEMENT_READ_PATHS } from "../lib/local-management-capability";
 import { readCodexTokens } from "../codex/auth-collision";
 import { withNativeMainSharedClaim } from "../codex/native-main-claim";
 import { probeNativeProfileRecoveryState, resolveNativeProfileContext } from "../codex/native-profile-store";
@@ -42,6 +41,10 @@ import {
 } from "../codex/runtime";
 import { CODEX_REAUTH_ACTION, collectOAuthHealthEntriesForCli, MASKED_ACCOUNT_FALLBACK, type OAuthHealthEntry } from "../oauth/health";
 import { getAuthRefreshIntentLockPath, getAuthStorePath } from "../oauth/store";
+import {
+  fetchBoundLocalManagementRead,
+  type LocalManagementReadDeps,
+} from "../server/local-management-read-client";
 export { resolveCodexHomeDir } from "../codex/home";
 
 export type OAuthDoctorCheck = { level: "OK" | "WARN"; message: string };
@@ -610,20 +613,28 @@ function observedMemory(data: { rss: number; external?: number; arrayBuffers?: n
 }
 
 export async function fetchServiceMemory(
-  host: string,
-  port: number,
-  token: string | null,
-  fetchImpl: typeof fetch = fetch,
+  target: LiveProxy,
+  deps: LocalManagementReadDeps = {},
 ): Promise<ServiceMemoryReport> {
   try {
-    const res = await fetchImpl(`http://${host}:${port}/api/system/memory`, {
-      headers: token ? { "x-opencodex-api-key": token } : {},
-      signal: AbortSignal.timeout(SERVICE_MEMORY_TIMEOUT_MS),
+    const read = await fetchBoundLocalManagementRead(target, LOCAL_MANAGEMENT_READ_PATHS.systemMemory, {
+      ...deps,
+      timeoutMs: SERVICE_MEMORY_TIMEOUT_MS,
     });
+    if (read.kind === "unavailable") {
+      return read.reason === "transport"
+        ? { status: "unreachable", error: "fetch failed" }
+        : { status: "unauthorized" };
+    }
+    const { response: res, targetPid } = read;
     if (res.status === 401 || res.status === 403) return { status: "unauthorized" };
     if (!res.ok) return { status: "unreachable", error: `http ${res.status}` };
     const body = await res.json() as Partial<ServiceMemoryData>;
-    if (typeof body.pid !== "number" || typeof body.bunVersion !== "string" || typeof body.rss !== "number") {
+    if (
+      body.pid !== targetPid
+      || typeof body.bunVersion !== "string"
+      || typeof body.rss !== "number"
+    ) {
       return { status: "unreachable", error: "malformed response" };
     }
     return {
@@ -672,7 +683,7 @@ export function formatServiceMemoryLines(report: ServiceMemoryReport): string[]
   const lines: string[] = [];
   lines.push(`  --     doctor process Bun ${Bun.version} (this is NOT the service process)`);
   if (report.status === "unauthorized") {
-    lines.push("  --     proxy reachable but rejected the request — set OPENCODEX_ADMIN_AUTH_TOKEN to match the service");
+    lines.push("  --     local diagnostic capability unavailable — restart the running proxy with this OpenCodex version");
     return lines;
   }
   if (report.status === "unreachable") {
@@ -844,10 +855,6 @@ export async function runDoctor(args: string[] = []): Promise<void> {
   const live = await findLiveProxy({
     configFn: () => ({ port: doctorConfig.port, hostname: doctorConfig.hostname }),
   });
-  const livePid = live ? live.pid : readPid();
-  const liveRuntime = live
-    ? { pid: live.pid ?? 0, port: live.port, hostname: live.hostname }
-    : (livePid ? readRuntimePort(livePid) : null);
 
   const currentProxyEnv = collectProxyEnv();
   const configuredProxy = collectConfiguredProxy();
@@ -887,13 +894,11 @@ export async function runDoctor(args: string[] = []): Promise<void> {
 
   console.log("\nMemory / runtime");
   {
-    const runtime = liveRuntime;
-    if (!runtime || !live) {
+    if (!live) {
       console.log(`  --     doctor process Bun ${Bun.version} (this is NOT the service process)`);
       console.log("  --     no running ocx proxy found (no live pid/runtime record)");
     } else {
-      const token = configuredAdminToken();
-      const report = await fetchServiceMemory(gracefulStopHost(runtime.hostname), runtime.port, token);
+      const report = await fetchServiceMemory(live);
       for (const line of formatServiceMemoryLines(report)) console.log(line);
     }
   }