@iislee/opencodex 2.11.0 → 2.35.0

package/src/cli/doctor.ts

@@ -10,18 +10,41 @@
 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, resolveEnvValue } from "../config";
+import { readPid } from "../config/process-state";
+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 { tokenCollidesWithAdmin } from "../lib/admin-secrets";
+import { readInstalledServiceToken } from "../lib/service-secrets";
 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";
+import { NativeProfileError } from "../codex/native-profile-types";
 import { collectOrcaCodexHomeDiagnostic, resolveCodexHomeDir as resolveCodexHomeDirImpl, isWslRuntime, listWslWindowsCodexHomes, wslAutomountRoot, type CodexHomeDeps } from "../codex/home";
+import { scanCodexAgentRolesWithTomlModelFallback } from "../codex/subagent-model-fallback";
 import { findCodexOnPath, isWindowsInteropDir } from "../codex/shim";
 import { countPendingOpencodexHistory } from "../codex/history-provider";
+import {
+  inspectCodexCoordinator,
+  recoverZeroByteCodexCoordinator,
+  type CodexCoordinatorDiagnostic,
+} from "../codex/coordinator-doctor";
+import {
+  inspectAbandonedResponseStateTemps,
+  reclaimAbandonedResponseStateTemps,
+  type ResponseStateTempRecoveryResult,
+} from "../responses/state";
+import {
+  CodexUserIdentityRefusal,
+  probeCodexCoordinatorNamespace,
+  resolveEffectiveUserIdentity,
+} from "../codex/user-identity";
 import { collectProjectCodexConfigWarnings, formatProjectCodexConfigWarningsForDoctor } from "../codex/project-config-warnings";
-import { collectStartupHealth, startupHealthSummary } from "../codex/autostart-health";
+import { collectStartupHealth, formatStartupRoutingDetail, startupHealthSummary } from "../codex/autostart-health";
 import {
   displayCodexRuntimePath,
   loadLastEffortClamp,
@@ -31,9 +54,41 @@ 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 };
+/**
+ * `FAIL` exists for a condition that makes the surface unusable rather than degraded.
+ * A review of the #2696 work pointed out that reporting a fully fenced management plane
+ * — every `/api/*` returning 503 — at the same level as a directory-permission note
+ * misleads the reader about severity.
+ *
+ * Doctor's own exit code still belongs to the uniform contract in wp3b (devlog 025);
+ * this type only fixes what the operator is told.
+ */
+export type OAuthDoctorCheck = { level: "OK" | "WARN" | "FAIL"; message: string };
+
+/**
+ * Whether any FAIL-level condition was seen during this `runDoctor` pass.
+ *
+ * Module-scoped and reset at the top of `runDoctor` rather than threaded through, because
+ * `runDoctor` reports by direct `console.log` across a dozen sections and has no checks
+ * collection to inspect. Reset matters for the test suite, which calls `runDoctor` several
+ * times in one process; a sticky flag would make the second call fail because the first did.
+ */
+let doctorSawFailure = false;
+
+function recordDoctorFailure(): void {
+  doctorSawFailure = true;
+}
+
+/** True when the last `runDoctor` pass saw a FAIL-level condition. */
+export function doctorFailed(): boolean {
+  return doctorSawFailure;
+}
 
 function pathIsWritable(path: string): boolean {
   try {
@@ -112,6 +167,50 @@ function describeDoctorHealth(entry: OAuthHealthEntry): string {
   }
 }
 
+/**
+ * Detect the management/data-plane credential collision behind #2696.
+ *
+ * The service exports the service token file as `OPENCODEX_API_AUTH_TOKEN` before
+ * starting the proxy. When that value is the admin token, the server treats the
+ * management credential as a data-plane admission secret and fences the ENTIRE
+ * management plane closed at boot: every `/api/*` returns 503, including on a loopback
+ * install that never needed a data-plane secret.
+ *
+ * `assertNotAdminToken` in src/service.ts now refuses to create this state, but an
+ * install made before that guard existed is already broken on disk, and the symptom
+ * (every management command failing) points nowhere. This is the check that names it.
+ *
+ * Observe-only, like the rest of doctor: it compares shapes and never prints, logs, or
+ * returns a credential value.
+ */
+export function dataPlaneCredentialCollisionCheck(
+  env: NodeJS.ProcessEnv = process.env,
+  installedServiceToken: string | null = readInstalledServiceToken(),
+): OAuthDoctorCheck {
+  const dataPlane = env.OPENCODEX_API_AUTH_TOKEN?.trim() || installedServiceToken?.trim() || "";
+  if (!dataPlane) {
+    return { level: "OK", message: "No data-plane token is set, so it cannot collide with the management token." };
+  }
+  // Same comparison as assertNotAdminToken: minted prefix or configuredAdminToken
+  // (env or admin-api-token file). The file token is the one the service wrapper
+  // actually exports; inspecting only the doctor process env reported OK on every
+  // already-broken install (#2696).
+  if (!tokenCollidesWithAdmin(dataPlane, env)) {
+    return { level: "OK", message: "Data-plane and management credentials are distinct." };
+  }
+  return {
+    // Not a degradation: while this holds, every /api/* returns 503 and no ocx
+    // management command can work at all.
+    level: "FAIL",
+    message:
+      "The data-plane secret (OPENCODEX_API_AUTH_TOKEN or the service token file) holds the "
+      + "management (admin) token, so the proxy fences the whole management API closed and "
+      + "every ocx management command fails with 503. "
+      + "Action: unset OPENCODEX_API_AUTH_TOKEN, replace the service token file with a distinct "
+      + "data-plane key, then re-run `ocx service install` and restart the proxy",
+  };
+}
+
 /**
  * OAuth reliability checks for `ocx doctor`. Observe-only: never mutates
  * credentials, locks, or networking. Every WARN includes a recovery Action.
@@ -122,6 +221,8 @@ export async function collectOAuthDoctorChecks(
 ): Promise<OAuthDoctorCheck[]> {
   const checks: OAuthDoctorCheck[] = [];
 
+  checks.push(dataPlaneCredentialCollisionCheck());
+
   if (isOAuthCredentialStorageWritable()) {
     checks.push({ level: "OK", message: "OAuth credential storage directory is writable for atomic auth.json updates." });
   } else {
@@ -479,36 +580,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 +663,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;
@@ -558,20 +700,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 {
@@ -579,6 +729,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,
@@ -612,12 +765,118 @@ export async function fetchServiceMemory(
 
 const mb = (bytes: number): string => `${Math.round(bytes / (1024 * 1024))}MB`;
 
+export const RECLAIM_RESPONSE_TEMPS_FLAG = "--reclaim-response-temps";
+export const RECOVER_ZERO_BYTE_COORDINATOR_FLAG = "--recover-zero-byte-coordinator";
+/** Matches the dry run's entry bound so report and reclaim agree on a large backlog. */
+const RESPONSE_TEMP_RECLAIM_MAX_CLEANUPS = 4_096;
+/** Names the subsystem: other components mint temps with the same shape and are not covered. */
+const CLEAN_RESPONSE_TEMP_LINE = "  ok  No abandoned response-state temp files.";
+
+/**
+ * Render the abandoned-temp section (testable without console capture).
+ *
+ * Report is the DEFAULT and reclaim is opt-in: `doctor` is a diagnostic an operator runs
+ * to understand a machine, so deleting files as a side effect of asking a question is the
+ * wrong default even for cache files.
+ *
+ * Counts come from `eligible`/`eligibleBytes`, never `matched`: `matched` is incremented
+ * before the file-type, age, boot-floor, and liveness gates, so reporting it would tell an
+ * operator that live-pid temps and young temps are "abandoned".
+ */
+export function formatResponseTempLines(
+  result: ResponseStateTempRecoveryResult,
+  reclaimed: boolean,
+): string[] {
+  if (reclaimed) {
+    if (result.removed === 0 && result.failed === 0) return [CLEAN_RESPONSE_TEMP_LINE];
+    const lines = [`  ok  Reclaimed ${result.removed} abandoned response-state temp file(s), ${mb(result.bytesRemoved)} freed.`];
+    if (result.failed > 0) {
+      // Never "retried automatically": this command exists for the operator whose proxy will
+      // NOT start, and in that state nothing retries anything.
+      lines.push(`  !!  ${result.failed} file(s) could not be removed (in use or locked). Retried on the next reclaim — automatically while the proxy runs, otherwise re-run this command.`);
+    }
+    // `truncated`, not `eligible > removed + failed`: outside a dry run every eligible entry
+    // is unlinked or failed on the same iteration it is counted, so those two are always
+    // equal and the comparison never fired. An operator with a backlog past the budget was
+    // told the reclaim had finished.
+    if (result.truncated) {
+      lines.push("  !!  Cleanup budget reached; files remain. Run the command again to continue.");
+    }
+    return lines;
+  }
+  if (result.eligible === 0) return [CLEAN_RESPONSE_TEMP_LINE];
+  const lines = [
+    `  !!  ${result.eligible} abandoned response-state temp file(s), ${mb(result.eligibleBytes)} reclaimable.`,
+    "      These are interrupted snapshot writes (continuation cache only) and are safe to remove.",
+    "      Reclaim them with: ocx doctor --reclaim-response-temps",
+  ];
+  // The dry run skips the cleanup budget but is still bounded by the entry cap, so a large
+  // enough backlog makes this a floor rather than a total. Say so instead of letting an
+  // operator size the problem from a truncated count.
+  if (result.truncated) lines.push("      Scan stopped at its entry budget; the real total is higher.");
+  return lines;
+}
+
+export function formatCoordinatorDoctorLines(diagnostic: CodexCoordinatorDiagnostic): string[] {
+  const pathLine = diagnostic.path ? [`       path: ${diagnostic.path}`] : [];
+  const evidenceLines = "evidence" in diagnostic && diagnostic.evidence
+    ? [
+      `       size: ${diagnostic.evidence.sizeBytes} bytes; user_version: ${diagnostic.evidence.schemaVersion}`,
+      `       tables: ${diagnostic.evidence.tables.length === 0 ? "none" : diagnostic.evidence.tables.join(", ")}`,
+      `       transition rows: ${diagnostic.evidence.transitionRows ?? "not inspected"}; singleton=1 rows: ${diagnostic.evidence.singletonRows ?? "not inspected"}`,
+    ]
+    : [];
+  switch (diagnostic.kind) {
+    case "absent":
+      return ["  ok     native-write coordinator not created yet", ...pathLine];
+    case "ready":
+      return ["  ok     native-write coordinator has an authoritative transition row", ...pathLine, ...evidenceLines];
+    case "zero-byte":
+      return [
+        "  !!     native-write coordinator is a zero-byte remnant and has no authority",
+        ...pathLine,
+        ...evidenceLines,
+        `       Action: stop the OpenCodex proxy/service, then run ocx doctor ${RECOVER_ZERO_BYTE_COORDINATOR_FLAG} --yes`,
+      ];
+    case "unversioned-empty":
+      return [
+        "  !!     native-write coordinator is a non-empty unversioned database; automatic recovery is refused",
+        ...pathLine,
+        ...evidenceLines,
+      ];
+    case "rowless":
+      return [
+        "  !!     native-write coordinator has schema version 1 but no authoritative row; automatic recovery is refused",
+        ...pathLine,
+        ...evidenceLines,
+      ];
+    case "unversioned-nonempty":
+      return [
+        "  !!     native-write coordinator is unversioned and contains unknown tables; automatic recovery is refused",
+        ...pathLine,
+        ...evidenceLines,
+      ];
+    case "unsupported":
+      return [
+        `  !!     native-write coordinator schema version ${diagnostic.version} is unsupported; automatic recovery is refused`,
+        ...pathLine,
+        ...evidenceLines,
+      ];
+    case "changed":
+      return ["  --     native-write coordinator changed during diagnosis; re-run ocx doctor", ...pathLine];
+    case "unsafe":
+      return [`  !!     native-write coordinator path is unsafe: ${diagnostic.reason}`, ...pathLine];
+    case "unreadable":
+      return [`  !!     native-write coordinator is unreadable: ${diagnostic.reason}`, ...pathLine, ...evidenceLines];
+  }
+}
+
 /** Render the doctor "Memory / runtime" section lines (testable without console capture). */
 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") {
@@ -652,12 +911,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 +940,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}`;
 }
 
@@ -704,7 +983,37 @@ export async function runDoctor(args: string[] = []): Promise<void> {
     return;
   }
 
+  if (args.includes(RECOVER_ZERO_BYTE_COORDINATOR_FLAG)) {
+    if (!args.includes("--yes")) {
+      console.log(`Recovery is explicit and creates a same-directory backup. Re-run: ocx doctor ${RECOVER_ZERO_BYTE_COORDINATOR_FLAG} --yes`);
+      process.exitCode = 1;
+      return;
+    }
+    const diagnostics = readConfigDiagnostics().config;
+    const live = await findLiveProxy({
+      configFn: () => ({ port: diagnostics.port, hostname: diagnostics.hostname }),
+    });
+    if (live) {
+      console.log(`Recovery refused: OpenCodex proxy pid ${live.pid} is still running. Stop the proxy/service and retry.`);
+      process.exitCode = 1;
+      return;
+    }
+    const recovered = recoverZeroByteCodexCoordinator();
+    if (!recovered.ok) {
+      console.log(`Recovery refused: ${recovered.reason}.`);
+      process.exitCode = 1;
+      return;
+    }
+    console.log(`Moved the non-authoritative coordinator to ${recovered.backupPath}`);
+    console.log("Run `ocx sync` to retry Codex config injection. The backup was preserved and no Codex config/catalog file was changed by recovery.");
+    process.exitCode = 0;
+    return;
+  }
+
   console.log("opencodex doctor\n");
+  // Reset per pass: the suite drives runDoctor several times in one process, and a sticky
+  // flag would fail the second call because the first saw a problem.
+  doctorSawFailure = false;
 
   // Ordering note: the memory/runtime section renders after "Running proxy
   // process proxy env" below; helpers live above runDoctor for testability.
@@ -719,6 +1028,26 @@ export async function runDoctor(args: string[] = []): Promise<void> {
     console.log(`  ${row.exists ? "ok " : "-- "} ${row.label}: ${row.path}${flags ? `  (${flags})` : ""}`);
   }
 
+  // Runs without the proxy on purpose: the worst accumulation happens when the proxy will
+  // not start, which is exactly when the in-process periodic reclaim never ticks.
+  const reclaimTemps = args.includes(RECLAIM_RESPONSE_TEMPS_FLAG);
+  console.log("\nResponse-state temp files");
+  // A typo must not silently degrade into "nothing to reclaim" — the operator would read the
+  // report as an answer to a question they never actually asked.
+  for (const arg of args) {
+    if (arg !== RECLAIM_RESPONSE_TEMPS_FLAG && /^--reclaim/.test(arg)) {
+      console.log(`  !!  Unrecognized flag ${arg}; did you mean ${RECLAIM_RESPONSE_TEMPS_FLAG}? Reporting only.`);
+    }
+  }
+  for (const line of formatResponseTempLines(
+    // The reclaim budget matches the report budget: a report bounded by entries and a removal
+    // bounded by a smaller cleanup cap would tell an operator 816 and then silently free 512.
+    reclaimTemps
+      ? reclaimAbandonedResponseStateTemps({ maxCleanups: RESPONSE_TEMP_RECLAIM_MAX_CLEANUPS })
+      : inspectAbandonedResponseStateTemps(),
+    reclaimTemps,
+  )) console.log(line);
+
   const orcaHome = collectOrcaCodexHomeDiagnostic();
   console.log("\nCodex app home targeting");
   console.log(`  ${orcaHome.mismatch ? "!! " : "ok "} Effective Codex home: ${orcaHome.effectiveCodexHome}`);
@@ -733,7 +1062,7 @@ export async function runDoctor(args: string[] = []): Promise<void> {
   const startup = collectStartupHealth(doctorConfig);
   console.log("\nCodex restart safety");
   console.log(`  ${startup.rebootSafe ? "ok " : "!! "} ${startupHealthSummary(startup)}`);
-  console.log(`       routing=${startup.routingKind}, service=${startup.serviceViable ? "viable" : startup.serviceInstalled ? "installed-but-unhealthy" : "absent"}, shim=${startup.shimHealthy ? "healthy" : startup.shimInstalled ? "stale" : "absent"}`);
+  console.log(`       ${formatStartupRoutingDetail(startup)}`);
 
   console.log("\nCodex runtime selection");
   {
@@ -769,10 +1098,20 @@ 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);
+
+  // Mirrors `ocx status` through the same comparison rather than a second implementation:
+  // two diagnostics disagreeing about whether an install is stale is worse than one (#2701).
+  // No extra probe -- findLiveProxy already carried the version back.
+  {
+    const { packageVersion } = await import("./help");
+    const { computeVersionSkew } = await import("./version-skew");
+    const skew = computeVersionSkew(packageVersion(), live?.version);
+    if (skew.skewed && skew.warning) {
+      console.log(`!! ${skew.warning}`);
+    } else if (skew.proxyVersion !== null) {
+      console.log(`ok ocx ${skew.cliVersion} matches the running proxy`);
+    }
+  }
 
   const currentProxyEnv = collectProxyEnv();
   const configuredProxy = collectConfiguredProxy();
@@ -812,13 +1151,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);
     }
   }
@@ -829,17 +1166,41 @@ export async function runDoctor(args: string[] = []): Promise<void> {
   console.log(`  ${probe.ok ? "ok " : "-- "} ${WHAM_USAGE_URL}`);
   console.log(`       ${detail}, ${probe.durationMs}ms, ${probe.authenticated ? "authenticated" : "unauthenticated"}`);
 
-  // Design B upgrade visibility: threads still tagged opencodex are invisible to the native
-  // Codex app until the one-time migration lands. Read-only probe (readonly sqlite, 100ms
-  // busy timeout) — reports state, never mutates.
-  console.log("\nCodex history migration");
+  // Design B upgrade visibility: only the backup manifest authorizes restoring provider
+  // metadata. Bare routed rows have unknown provenance and remain unchanged. This read-only
+  // probe reports manifest work and database readability; it never mutates.
+  console.log("\nCodex history metadata restore");
+  // The history failure messages point here; make the visit worthwhile by
+  // probing the coordinator namespace the locks live in. The probe exercises
+  // identity, runtime-root, and permission checks without taking any lock or
+  // creating anything (a doctor run must observe, not initialize).
+  try {
+    const identity = resolveEffectiveUserIdentity();
+    const probe = probeCodexCoordinatorNamespace(identity);
+    if (probe.status === "missing") {
+      console.log("  ok     history coordinator namespace not created yet (no history operation has run)");
+    } else {
+      console.log("  ok     history coordinator namespace resolves");
+    }
+  } catch (cause) {
+    const reason = cause instanceof CodexUserIdentityRefusal ? cause.message : String(cause);
+    console.log(`  --     history coordinator namespace refused: ${reason}`);
+  }
+  console.log("\nCodex native-write coordinator");
+  for (const line of formatCoordinatorDoctorLines(inspectCodexCoordinator())) console.log(line);
   const pending = countPendingOpencodexHistory();
   if (pending.failed) {
-    console.log("  --     state DB locked or unreadable (Codex app open?) — migration state unknown");
+    if (pending.failureReason === "busy") {
+      console.log("  --     history database, backup manifest, or rollout file is busy — exact metadata restore is pending");
+    } else if (pending.failureReason === "permission") {
+      console.log("  --     state DB or backup manifest access was denied — restore state unknown");
+    } else {
+      console.log("  --     backup manifest or restore target failed integrity checks — manual review required");
+    }
   } else if (pending.pendingRows === 0 && pending.backupEntries === 0) {
-    console.log("  ok     no legacy opencodex-tagged threads pending");
+    console.log("  ok     no manifest-backed provider metadata pending; untracked routed history is unchanged");
   } else {
-    console.log(`  --     ${pending.pendingRows} thread(s) still tagged opencodex, ${pending.backupEntries} backup manifest entr${pending.backupEntries === 1 ? "y" : "ies"}`);
+    console.log(`  --     ${pending.backupEntries} backup manifest entr${pending.backupEntries === 1 ? "y" : "ies"} pending exact metadata restore`);
   }
 
   console.log("\nProject Codex configs");
@@ -852,6 +1213,15 @@ export async function runDoctor(args: string[] = []): Promise<void> {
     }
   }
 
+  console.log("\nCodex agent role files");
+  const tomlFallbackRoles = scanCodexAgentRolesWithTomlModelFallback(resolveCodexHomeDirImpl());
+  if (tomlFallbackRoles.length === 0) {
+    console.log("  ok     no per-role model_fallback fields in $CODEX_HOME/agents/*.toml");
+  } else {
+    console.log(`  [WARN] ${tomlFallbackRoles.length} agent role file${tomlFallbackRoles.length === 1 ? "" : "s"} contain${tomlFallbackRoles.length === 1 ? "s" : ""} \`model_fallback\`: ${tomlFallbackRoles.join(", ")}`);
+    console.log("        Codex >= 0.146 rejects that field as unknown and skips the whole role. Move the chains to opencodex config `subagentModelFallbackByModel` (keyed by primary model) and remove the field from the TOML files.");
+  }
+
   const dual = collectWslDualInstall();
   if (dual.wsl) {
     console.log("\nWSL Codex installs");
@@ -871,6 +1241,12 @@ export async function runDoctor(args: string[] = []): Promise<void> {
   console.log("\nOAuth reliability");
   for (const check of await collectOAuthDoctorChecks()) {
     console.log(`  [${check.level}] ${check.message}`);
+    // A diagnostic that always exits 0 cannot gate anything, which defeats the point of
+    // running it from a script (#2697's sibling defect). FAIL is the level reserved for a
+    // surface that is unusable rather than degraded, so it -- and only it -- fails the
+    // command. WARN stays exit 0 on purpose: warning on a degraded-but-working install
+    // must not break a pipeline that is legitimately green.
+    if (check.level === "FAIL") recordDoctorFailure();
   }
 
   // #857: a running Codex app-server can keep an older in-memory catalog than
@@ -878,7 +1254,7 @@ export async function runDoctor(args: string[] = []): Promise<void> {
   const { collectCodexAppServerCatalogState } = await import("../codex/app-server-processes");
   const catalogState = collectCodexAppServerCatalogState();
   if (catalogState.state === "stale") {
-    console.log(`  [WARN] Codex app-server (PID(s): ${catalogState.processes.map(p => p.pid).join(", ")}) started before the on-disk catalog changed; its in-memory model list disagrees with ocx. Action: restart Codex (or run \`ocx sync --restart-codex\`)`);
+    console.log(`  [WARN] Codex app-server (PID(s): ${catalogState.processes.map(p => p.pid).join(", ")}) started before the on-disk catalog changed; its in-memory model list disagrees with ocx. Action: restart Codex (or run \`ocx sync --restart-codex\`; on Windows the desktop app may need \`ocx sync --restart-desktop-app\`)`);
   } else if (catalogState.state === "unknown") {
     console.log("  [WARN] Could not verify whether the running Codex app-server's model catalog is current (start time or catalog unreadable). Action: if the model list looks stale, restart Codex");
   } else if (catalogState.state === "fresh") {
@@ -891,6 +1267,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) {
@@ -913,8 +1291,14 @@ export async function runDoctor(args: string[] = []): Promise<void> {
       }
     }
   }
-  if (pending.failed || pending.pendingRows > 0 || pending.backupEntries > 0) {
-    hints.push("Legacy chat threads are still tagged opencodex (or the DB was locked). The running proxy retries the migration automatically; to force it now, close the Codex app and run 'ocx sync'.");
+  if (pending.failed && pending.failureReason === "busy") {
+    hints.push("Backed-up history metadata is pending or its state is unreadable. The running proxy retries exact restoration automatically; to force it now, close the Codex app and run 'ocx sync'. Untracked routed history is not relabeled.");
+  } else if (pending.failed && pending.failureReason === "permission") {
+    hints.push("Backed-up history metadata could not be inspected because access was denied. Fix access to the reported Codex history paths, then run 'ocx sync'; repeated retries do not repair permissions.");
+  } else if (pending.failed) {
+    hints.push("The history manifest or its target is invalid or changed. Preserve both, inspect the manifest/database/rollout identity, and do not repeatedly run 'ocx sync' until the mismatch is understood. Untracked routed history is not relabeled.");
+  } else if (pending.backupEntries > 0) {
+    hints.push("Backed-up history metadata is pending. The running proxy retries exact restoration automatically; to force it now, close the Codex app and run 'ocx sync'. Untracked routed history is not relabeled.");
   }
   if (dual.dualInstall && !dual.effectiveIsWindowsMount) {
     hints.push(`Codex is installed on BOTH WSL and Windows. Each side keeps its own ~/.codex (logins, config, catalog are separate); ocx here manages the Linux one. To share a single home, set CODEX_HOME=${dual.windowsCodexHomes[0] ?? `${dual.automountRoot}/c/Users/<you>/.codex`} in WSL (drvfs file locking is less reliable).`);