@iislee/opencodex 2.11.0 → 2.35.0

package/src/cli/claude-agent-startup-sync.ts

@@ -0,0 +1,73 @@
+import type { OcxConfig } from "../types";
+import { injectClaudeAgentDefs } from "../claude/agents-inject";
+import { fetchClaudeContextWindows } from "./claude";
+import type { ReadinessGate } from "../server/readiness";
+
+export interface ClaudeAgentStartupSyncDeps {
+  fetchContextWindows?: typeof fetchClaudeContextWindows;
+  injectAgentDefs?: typeof injectClaudeAgentDefs;
+  warn?: (message: string) => void;
+}
+
+/**
+ * Keep the public readiness gate pending until both startup reconciliations have settled.
+ *
+ * The Codex sync remains the authority for ready versus failed. Claude roster repair is
+ * deliberately best-effort (#2200), but readiness must not become observable between the
+ * Codex write and that repair: a service manager could otherwise launch Claude Code against
+ * stale `ocx-*.md` files. A small forwarding gate delays only the successful transition;
+ * terminal Codex failure is still published immediately.
+ */
+export async function reconcileClientStartupBeforeReady<T>(
+  readinessGate: ReadinessGate,
+  syncCodex: (deferredGate: ReadinessGate) => Promise<T>,
+  syncClaudeRoster: () => Promise<unknown>,
+): Promise<T> {
+  let codexReady = false;
+  const deferredGate: ReadinessGate = {
+    getStatus: () => readinessGate.getStatus(),
+    markReady: () => { codexReady = true; },
+    markFailed: () => readinessGate.markFailed(),
+  };
+
+  const result = await syncCodex(deferredGate);
+  await syncClaudeRoster();
+  if (codexReady) readinessGate.markReady();
+  return result;
+}
+
+/**
+ * Reconcile the generated Claude Code roster after the proxy listener is live.
+ *
+ * This belongs to the owning CLI lifecycle rather than `startServer`: the latter is also a
+ * library/test primitive and must not mutate a developer's real `~/.claude` directory merely
+ * because an in-process test server was created. The live Management API supplies the same bounded
+ * context-window map used by `ocx claude`; failure keeps startup available and falls back to an
+ * unmarked roster. Disabled integrations skip discovery and prune verified-owned definitions.
+ */
+export async function syncClaudeAgentDefsAtProxyStartup(
+  config: OcxConfig,
+  port: number,
+  deps: ClaudeAgentStartupSyncDeps = {},
+): Promise<string[] | null> {
+  const inject = deps.injectAgentDefs ?? injectClaudeAgentDefs;
+  const warn = deps.warn ?? (message => console.warn(message));
+
+  try {
+    if (config.claudeCode?.enabled === false || config.claudeCode?.injectAgents === false) {
+      return inject(config, {});
+    }
+
+    let windows: Record<string, number> = {};
+    try {
+      windows = await (deps.fetchContextWindows ?? fetchClaudeContextWindows)(config, port);
+    } catch {
+      // Startup remains best-effort. The next management mutation or `ocx claude` launch can
+      // restore context markers after a transient catalog/Management API failure.
+    }
+    return inject(config, windows);
+  } catch (error) {
+    warn(`⚠ Claude agent definitions could not be synced at proxy startup: ${error instanceof Error ? error.message : String(error)}`);
+    return null;
+  }
+}

package/src/cli/claude-desktop.ts

@@ -1,6 +1,7 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { loadConfig, saveConfigPreservingClaudeCode } from "../config";
+import { setIntegrationEnabled } from "../codex/desired-state";
 import {
   DESKTOP_FAMILIES,
   moveDesktopRoute,
@@ -10,10 +11,11 @@ import {
   type DesktopProfile,
 } from "../claude/desktop-profile";
 import { writeDesktop3pConfig, type Desktop3pConfigMode, parseDesktop3pModeArgs } from "../claude/desktop-3p";
-import { filterCatalogVisibleModels, desktopVisibleNativeSlugs } from "../codex/catalog";
+import { filterCatalogVisibleModels, desktopVisibleNativeSlugs, nativeContextLimits } from "../codex/catalog";
 import { buildClaudeDesktopState, fetchAllModels } from "../server/management-api";
 import { findLiveProxy } from "../server/proxy-liveness";
-import { runtimeRequest } from "./runtime-api";
+import { CliUsageError, runtimeRequest, takeJsonFlag } from "./runtime-api";
+import { OPENAI_CODEX_PROVIDER_ID } from "../providers/openai-tiers";
 
 function isFamily(value: string | undefined): value is DesktopFamily {
   return !!value && (DESKTOP_FAMILIES as readonly string[]).includes(value);
@@ -23,6 +25,7 @@ function printDesktopHelp(): void {
   console.log(`Usage:
   ocx claude desktop [apply] [--static|--hybrid|--discovery-only]
   ocx claude desktop show [--json]
+  ocx claude desktop status [--json]
   ocx claude desktop move <provider/model> <opus|fable|sonnet|haiku> [--default]
   ocx claude desktop default <family> <provider/model|none>
   ocx claude desktop export <path|->
@@ -41,7 +44,11 @@ export async function applyProfile(
   profile: DesktopProfile,
   mode: Desktop3pConfigMode,
   deps: ApplyProfileDeps = {},
-): Promise<{ ok: boolean; path: string; reason?: string }> {
+): Promise<{ ok: boolean; path: string; reason?: string; warning?: string }> {
+  // Explicit apply is an enable action. Persist intent before any Desktop write
+  // so a process crash cannot leave a gateway profile that startup immediately removes.
+  const desired = setIntegrationEnabled("claude-desktop", true);
+  if (!desired.ok) return { ok: false, path: "", reason: desired.message };
   const config = loadConfig();
   const state = await buildClaudeDesktopState(config, profile);
   config.claudeCode = { ...(config.claudeCode ?? {}), desktopProfile: state.profile };
@@ -52,7 +59,7 @@ export async function applyProfile(
     // serving process installs the map there; a local-only write leaves the
     // daemon unable to decode aliases, and the provider rejects them (400).
     const post = deps.postApplyImpl ?? (async (m: Desktop3pConfigMode, p: DesktopProfile) =>
-      runtimeRequest<{ ok?: boolean; path?: string; error?: string }>(
+      runtimeRequest<{ ok?: boolean; path?: string; error?: string; saved?: boolean; warning?: string }>(
         "/api/claude-desktop/apply",
         // The daemon's config may be older than what we just saved, so the
         // profile travels with the request instead of being re-read there.
@@ -61,12 +68,26 @@ export async function applyProfile(
     try {
       const applied = await post(mode, state.profile);
       if (applied.ok === false) return { ok: false, path: applied.path ?? "", reason: applied.error ?? "daemon apply failed" };
-      return { ok: true, path: applied.path ?? "" };
+      // Partial success: Desktop was written but the applied marker was not
+      // persisted. Pass the degradation up instead of reporting a clean apply.
+      const partial = (applied as { saved?: boolean; warning?: string }).saved === false;
+      return {
+        ok: true,
+        path: applied.path ?? "",
+        ...(partial ? { warning: (applied as { warning?: string }).warning ?? "applied marker was not saved" } : {}),
+      };
     } catch (error) {
       return { ok: false, path: "", reason: error instanceof Error ? error.message : String(error) };
     }
   }
   const allModels = await fetchAllModels(config);
+  // The toggle can persist OFF while fetchAllModels was awaiting (same race the
+  // management writers fence). Re-read persisted intent immediately before the
+  // writer; a lost race is a discriminated skip, not a write.
+  const { claudeDesktopIntegrationEnabledNow } = await import("../codex/desired-state");
+  if (!claudeDesktopIntegrationEnabledNow()) {
+    return { ok: false, path: "", reason: "desired_state_changed" };
+  }
   const routed = filterCatalogVisibleModels(allModels, config).map(model => ({
     provider: model.provider,
     id: model.id,
@@ -79,6 +100,7 @@ export async function applyProfile(
     config.apiKeys?.[0]?.key,
     mode,
     state.profile,
+    nativeContextLimits(config),
   );
   return { ok: result.written, path: result.path, reason: result.reason };
 }
@@ -97,10 +119,10 @@ export async function handleClaudeDesktopCommand(argv: string[], deps: ApplyProf
     const nonMode = argv.filter(arg => !["apply", "--static", "--hybrid", "--discovery-only"].includes(arg));
     if (nonMode.length > 0) {
       console.error(`알 수 없는 인자: ${nonMode.join(" ")}`);
-      return 1;
+      return 2;
     }
     const parsedMode = parseDesktop3pModeArgs(legacyFlags);
-    if ("error" in parsedMode) { console.error(parsedMode.error); return 1; }
+    if ("error" in parsedMode) { console.error(parsedMode.error); return 2; }
     try {
       const config = loadConfig();
       const state = await buildClaudeDesktopState(config);
@@ -111,6 +133,9 @@ export async function handleClaudeDesktopCommand(argv: string[], deps: ApplyProf
         return 1;
       }
       console.log(`Claude Desktop 설정을 적용했습니다: ${result.path}`);
+      // The write landed; only the bookkeeping marker did not. Saying nothing
+      // would leave the saved-vs-applied display wrong with no explanation.
+      if (result.warning) console.warn(`⚠️  ${result.warning}`);
       console.log("Claude Desktop을 완전히 종료한 뒤 다시 열어 주세요.");
       return 0;
     } catch (error) {
@@ -121,10 +146,29 @@ export async function handleClaudeDesktopCommand(argv: string[], deps: ApplyProf
 
   try {
     const config = loadConfig();
+    // `status` is API-backed and must NOT build local state first: the whole point of the
+    // route the GUI polls (/api/claude-desktop/status) is the applied-vs-desired comparison,
+    // including staleness, drift and health, which only the running proxy knows. `show`
+    // reports what this machine would write; `status` reports what is actually in effect.
+    if (command === "status") {
+      const rest = argv.slice(1);
+      const wantsJson = takeJsonFlag(rest);
+      if (rest.length > 0) throw new CliUsageError("Usage: ocx claude desktop status [--json]");
+      const live = await runtimeRequest<Record<string, unknown>>("/api/claude-desktop/status", {});
+      if (wantsJson) console.log(JSON.stringify(live, null, 2));
+      else {
+        for (const [key, value] of Object.entries(live)) {
+          console.log(`${key}: ${typeof value === "object" ? JSON.stringify(value) : String(value)}`);
+        }
+      }
+      return 0;
+    }
     const state = await buildClaudeDesktopState(config);
     if (command === "show") {
-      if (argv.length > 2 || (argv[1] && argv[1] !== "--json")) throw new Error("Usage: ocx claude desktop show [--json]");
-      if (argv[1] === "--json") console.log(JSON.stringify(state));
+      const rest = argv.slice(1);
+      const wantsJson = takeJsonFlag(rest);
+      if (rest.length > 0) throw new CliUsageError("Usage: ocx claude desktop show [--json]");
+      if (wantsJson) console.log(JSON.stringify(state));
       else {
         for (const family of DESKTOP_FAMILIES) {
           console.log(`${family.toUpperCase()}${state.profile.defaults[family] ? ` (default: ${state.profile.defaults[family]})` : ""}`);
@@ -137,7 +181,7 @@ export async function handleClaudeDesktopCommand(argv: string[], deps: ApplyProf
     }
     if (command === "move") {
       const [, route, familyRaw, ...flags] = argv;
-      if (!route || !isFamily(familyRaw) || flags.some(flag => flag !== "--default")) throw new Error("Usage: ocx claude desktop move <route> <family> [--default]");
+      if (!route || !isFamily(familyRaw) || flags.some(flag => flag !== "--default")) throw new CliUsageError("Usage: ocx claude desktop move <route> <family> [--default]");
       if (!state.models.some(model => model.route === route && model.available)) throw new Error(`현재 사용할 수 없는 모델입니다: ${route}`);
       const profile = moveDesktopRoute(state.profile, route, familyRaw, flags.includes("--default"));
       config.claudeCode = { ...(config.claudeCode ?? {}), desktopProfile: profile };
@@ -147,7 +191,7 @@ export async function handleClaudeDesktopCommand(argv: string[], deps: ApplyProf
     }
     if (command === "default") {
       const [, familyRaw, routeRaw] = argv;
-      if (!isFamily(familyRaw) || !routeRaw || argv.length !== 3) throw new Error("Usage: ocx claude desktop default <family> <route|none>");
+      if (!isFamily(familyRaw) || !routeRaw || argv.length !== 3) throw new CliUsageError("Usage: ocx claude desktop default <family> <route|none>");
       const route = routeRaw === "none" ? null : routeRaw;
       if (route && !state.models.some(model => model.route === route && model.available)) throw new Error(`현재 사용할 수 없는 모델입니다: ${route}`);
       const profile = setDesktopFamilyDefault(state.profile, familyRaw, route);
@@ -158,7 +202,7 @@ export async function handleClaudeDesktopCommand(argv: string[], deps: ApplyProf
     }
     if (command === "export") {
       const target = argv[1];
-      if (!target || argv.length !== 2) throw new Error("Usage: ocx claude desktop export <path|->");
+      if (!target || argv.length !== 2) throw new CliUsageError("Usage: ocx claude desktop export <path|->");
       const json = JSON.stringify(state.profile, null, 2) + "\n";
       if (target === "-") process.stdout.write(json);
       else writeFileSync(resolve(target), json, { encoding: "utf8", mode: 0o600 });
@@ -167,7 +211,7 @@ export async function handleClaudeDesktopCommand(argv: string[], deps: ApplyProf
     if (command === "import") {
       const source = argv[1];
       const flags = argv.slice(2);
-      if (!source || flags.some(flag => flag !== "--apply")) throw new Error("Usage: ocx claude desktop import <path> [--apply]");
+      if (!source || flags.some(flag => flag !== "--apply")) throw new CliUsageError("Usage: ocx claude desktop import <path> [--apply]");
       const profile = parseDesktopProfile(JSON.parse(readFileSync(resolve(source), "utf8")));
       const reconciled = (await buildClaudeDesktopState(config, profile)).profile;
       config.claudeCode = { ...(config.claudeCode ?? {}), desktopProfile: reconciled };
@@ -175,14 +219,15 @@ export async function handleClaudeDesktopCommand(argv: string[], deps: ApplyProf
       if (flags.includes("--apply")) {
         const result = await applyProfile(reconciled, "static", deps);
         if (!result.ok) { console.error(`프로필은 저장했지만 Desktop 적용에 실패했습니다: ${result.reason ?? "unknown error"}`); return 1; }
+        if (result.warning) console.warn(`⚠️  ${result.warning}`);
       }
       console.log("Claude Desktop 프로필을 가져왔습니다.");
       return 0;
     }
     printDesktopHelp();
-    return 1;
+    return 2;
   } catch (error) {
     console.error(error instanceof Error ? error.message : String(error));
-    return 1;
+    return error instanceof CliUsageError ? 2 : 1;
   }
 }

package/src/cli/claude.ts

@@ -12,11 +12,15 @@ import { injectClaudeAgentDefs } from "../claude/agents-inject";
 import { effectiveModelEnv, resolveAutoContext } from "../claude/context-windows";
 import { refreshGatewayModelCacheFromProxy } from "../claude/gateway-cache";
 import { commandInvocation } from "../lib/win-exec";
+import { isProxyAdmissionSecret } from "../server/auth-cors";
 import { findLiveProxy } from "../server/proxy-liveness";
 import type { OcxConfig } from "../types";
 import { configuredAdminToken } from "../lib/admin-secrets";
 import { PROXY_MARKER, ownAdmissionTokens, defaultAuthDetectDeps, detectClaudeAuth, type AuthDetectDeps } from "../claude/auth-detect";
 import { resolveClaudeAuthMode } from "../claude/auth-mode";
+import { withProcessRuntimeProvenance } from "../lib/bun-runtime";
+import { selfLaunchArgv } from "../lib/self-launch-argv";
+import { ANTHROPIC_PARENT_ENV_SLOTS, trustedNodeLauncherContext, type AnthropicParentEnvSlot } from "./launcher-context";
 
 export interface ClaudeLaunchEnv {
   [key: string]: string | undefined;
@@ -26,13 +30,43 @@ export interface ClaudeLaunchEnv {
  * Injectable IO for tests. `env` is deliberately NOT injectable: it is bound to the
  * launch base so detection and the spawned process can never disagree (audit R3-3).
  */
-export type ClaudeEnvDeps = { authDetect?: Omit<Partial<AuthDetectDeps>, "env" | "ownTokens"> };
+export type ClaudeEnvDeps = {
+  authDetect?: Omit<Partial<AuthDetectDeps>, "env" | "ownTokens">;
+  /** Test seam; production uses the authenticated Node-launcher context. */
+  preBunAnthropicSlots?: readonly AnthropicParentEnvSlot[] | null;
+  /** Explicit unsafe opt-in from a root `--dangerously-skip-permissions` launch. */
+  allowRootSkipPermissions?: boolean;
+};
+
+function isClaudeLoopbackHostname(hostname: string): boolean {
+  const normalized = hostname.toLowerCase().replace(/\.$/, "");
+  return normalized === "localhost"
+    || normalized === "127.0.0.1"
+    || normalized === "::1"
+    || normalized === "[::1]";
+}
+
+function targetsLocalClaudeProxy(value: string | undefined, port: number): boolean {
+  if (!value) return false;
+  try {
+    const parsed = new URL(value);
+    const effectivePort = parsed.port === "" ? 80 : Number(parsed.port);
+    return parsed.protocol === "http:"
+      && isClaudeLoopbackHostname(parsed.hostname)
+      && effectivePort === port
+      && parsed.username === ""
+      && parsed.password === "";
+  } catch {
+    return false;
+  }
+}
 
 /**
  * Pure env assembly (unit-tested): never sets ANTHROPIC_API_KEY (setting both
  * token vars triggers Claude Code's auth-conflict warning, 003 E1), and never
- * overrides variables the user already exported, apart from stale loopback
- * ANTHROPIC_BASE_URL values owned by a previous opencodex launch.
+ * preserves Anthropic variables proven to exist in the parent Node launcher,
+ * apart from stale loopback ANTHROPIC_BASE_URL values owned by a previous
+ * opencodex launch. Unproven ambient values fail closed as project dotenv.
  */
 export function buildClaudeEnv(
   config: OcxConfig,
@@ -47,42 +81,56 @@ export function buildClaudeEnv(
   // stale marker left in place would suppress the admission key and then be removed,
   // leaving the child with no token at all (audit R2-1). It is opencodex state, never
   // user auth, so dropping it unconditionally is safe.
-  if (env.ANTHROPIC_AUTH_TOKEN === PROXY_MARKER) delete env.ANTHROPIC_AUTH_TOKEN;
-  // Step 1b — drop Anthropic credentials that the bundled Bun runtime synthesized from a
-  // project `.env`/`.env.local` (issue #701). Claude Code disables claude.ai connectors the
-  // moment either token slot is populated, so an ambient project file silently moved a
-  // subscriber onto API billing while their OAuth login stayed healthy. The npm launcher
-  // runs under Node, which does NOT auto-load dotenv, so it records the slots that existed
-  // before Bun started; anything populated now but absent then came from the working
-  // directory, not from the user. A genuine shell export is still honored, which keeps
-  // auto-mode API-key auth working. An ABSENT marker means provenance is unknowable
-  // (a direct `bun src/cli/index.ts` run, a test, or an older launcher), and then we
-  // change nothing rather than guess — an EMPTY marker is different: the launcher ran
-  // and saw no pre-existing slots.
-  const preBunSlots = base.OCX_PRE_BUN_ANTHROPIC_ENV;
-  if (preBunSlots !== undefined) {
-    const exported = new Set(preBunSlots.split(",").filter(name => name.length > 0));
-    for (const name of ["ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"] as const) {
-      const value = env[name];
-      if (value !== undefined && value !== "" && !exported.has(name)) delete env[name];
-    }
+  if (env.ANTHROPIC_AUTH_TOKEN?.trim() === PROXY_MARKER) delete env.ANTHROPIC_AUTH_TOKEN;
+  // Step 1b — drop Anthropic credentials AND destinations that Bun may have synthesized
+  // from a project `.env`/`.env.local`. The plain-Node launcher records genuine parent
+  // exports before Bun starts and pairs that context with an argv proof, so with a
+  // trusted context we know exactly which slots the user really exported.
+  //
+  // Without a trusted context all three slots are treated as project-controlled. An
+  // earlier revision of this branch preserved credentials here, reasoning that the
+  // destination is pinned below so a dotenv key would only ever reach the local proxy.
+  // That reasoning is wrong, and review caught it: `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`
+  // is only set when we own an auth token (see below, and #253 for why asserting it
+  // otherwise logs a subscriber out), so on a subscription launch Claude Code's
+  // settings.env merge can still replace `ANTHROPIC_BASE_URL` after we return. A
+  // preserved key then travels to that host. The repository documents that residual for
+  // subscription mode; it must not be widened into a credential leak.
+  //
+  // Direct `bun src/cli/index.ts` therefore loses ambient Anthropic values. That is a
+  // real cost to a documented entry point, and the escape hatch is the launcher: run
+  // through `ocx` (the published bin) and genuine shell exports are preserved by proof.
+  const explicitSlots = deps.preBunAnthropicSlots;
+  const trustedSlots = explicitSlots === undefined
+    ? trustedNodeLauncherContext()?.anthropicEnvSlots ?? []
+    : explicitSlots ?? [];
+  const exported = new Set<AnthropicParentEnvSlot>(trustedSlots);
+  for (const name of ANTHROPIC_PARENT_ENV_SLOTS) {
+    const value = env[name];
+    if (value !== undefined && value !== "" && !exported.has(name)) delete env[name];
   }
-  // Never forward the seam itself to Claude Code.
+  // Never forward old or current provenance seams to Claude Code.
   delete env.OCX_PRE_BUN_ANTHROPIC_ENV;
+  delete env.OCX_NODE_LAUNCH_CONTEXT;
   const setDefault = (name: string, value: string | undefined) => {
     if (value === undefined || value.length === 0) return;
     if (env[name] !== undefined && env[name] !== "") return; // user wins
     env[name] = value;
   };
+  if (deps.allowRootSkipPermissions === true) {
+    setDefault("IS_SANDBOX", "1");
+  }
   setDefault("ANTHROPIC_BASE_URL", `http://127.0.0.1:${port}`);
   const existingBaseUrl = env.ANTHROPIC_BASE_URL;
   if (existingBaseUrl) {
     try {
       const parsed = new URL(existingBaseUrl);
-      const isLoopback = parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1";
-      if (isLoopback && parsed.port !== "" && Number(parsed.port) !== port) {
+      const effectivePort = parsed.port === "" ? 80 : Number(parsed.port);
+      if (parsed.protocol === "http:"
+        && isClaudeLoopbackHostname(parsed.hostname)
+        && effectivePort !== port) {
         const replacement = `http://127.0.0.1:${port}`;
-        console.error(`⚠ Replacing stale opencodex ANTHROPIC_BASE_URL ${existingBaseUrl} with ${replacement}.`);
+        console.error(`⚠ Replacing stale opencodex ANTHROPIC_BASE_URL ${parsed.origin} with ${replacement}.`);
         env.ANTHROPIC_BASE_URL = replacement;
       }
     } catch {
@@ -94,8 +142,26 @@ export function buildClaudeEnv(
   // the user's Claude login. Only inject a token when the proxy actually requires an
   // admission key; otherwise Claude Code keeps its own OAuth and sends it to us —
   // native claude models then pass through verbatim (see server/claude-messages.ts).
-  if ((config.apiKeys?.length ?? 0) > 0) {
-    setDefault("ANTHROPIC_AUTH_TOKEN", config.apiKeys![0].key);
+  const ownTokens = ownAdmissionTokens(config);
+  const targetsLocalProxy = targetsLocalClaudeProxy(env.ANTHROPIC_BASE_URL, port);
+  const inheritedApiKey = env.ANTHROPIC_API_KEY;
+  if (typeof inheritedApiKey === "string" && isProxyAdmissionSecret(inheritedApiKey, config)) {
+    delete env.ANTHROPIC_API_KEY;
+  }
+  const hasUserApiKey = Boolean(env.ANTHROPIC_API_KEY?.trim());
+  const inheritedAuthToken = env.ANTHROPIC_AUTH_TOKEN;
+  const inheritedTokenIsOurs = typeof inheritedAuthToken === "string"
+    && isProxyAdmissionSecret(inheritedAuthToken, config);
+  // system-env may have injected the proxy's admission key into the parent. A
+  // proof-bound external BASE_URL is still user-owned, so never let our inherited
+  // key follow it. A user API key also wins on a local launch; remove only the token
+  // values recognized by the shared proxy-admission contract and preserve every
+  // other token.
+  if (inheritedTokenIsOurs && (!targetsLocalProxy || hasUserApiKey)) {
+    delete env.ANTHROPIC_AUTH_TOKEN;
+  }
+  if (targetsLocalProxy && !hasUserApiKey && ownTokens.length > 0) {
+    setDefault("ANTHROPIC_AUTH_TOKEN", ownTokens[0]);
   }
   // Detection reads the SANITIZED launch env — the exact object spawned below — so the
   // resolver and the spawned process cannot disagree. It deliberately does NOT read the
@@ -110,11 +176,19 @@ export function buildClaudeEnv(
     ...defaultAuthDetectDeps(env as NodeJS.ProcessEnv),
     ...(deps.authDetect ?? {}),
     env: () => env as NodeJS.ProcessEnv,
-    ownTokens: ownAdmissionTokens(config),
+    ownTokens,
   }));
-  if (!env.ANTHROPIC_AUTH_TOKEN && resolved.markerMode === "proxy") {
+  if (!env.ANTHROPIC_AUTH_TOKEN && !hasUserApiKey && targetsLocalProxy && resolved.markerMode === "proxy") {
     env.ANTHROPIC_AUTH_TOKEN = PROXY_MARKER;
   }
+  const finalAuthToken = env.ANTHROPIC_AUTH_TOKEN;
+  const hostOwnsAuthentication = targetsLocalProxy
+    && !hasUserApiKey
+    && typeof finalAuthToken === "string"
+    && (
+      finalAuthToken.trim() === PROXY_MARKER
+      || isProxyAdmissionSecret(finalAuthToken, config)
+    );
   if (resolved.origin === "auto-unknown") {
     console.error("⚠ Claude 인증을 확인하지 못했습니다 — 구독 방식으로 진행합니다. GUI에서 인증 모드를 직접 지정하면 이 판단을 덮어쓸 수 있습니다.");
   }
@@ -136,7 +210,7 @@ export function buildClaudeEnv(
   // Claude Code 2.1.206+ also treats this as a host-auth assertion. Injecting it
   // without a host token makes a valid claude.ai subscription look logged out,
   // so the guard is only safe when opencodex actually owns authentication.
-  if (env.ANTHROPIC_AUTH_TOKEN) {
+  if (hostOwnsAuthentication) {
     setDefault("CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST", "1");
   }
   // Opt-in effort forcing (devlog 136 B6): opus-shaped aliases already carry
@@ -201,11 +275,11 @@ async function ensureProxyForClaude(): Promise<number | null> {
   if (live) return live.port;
   const cfgPort = loadConfig().port;
   const pinPort = typeof cfgPort === "number" && cfgPort > 0 ? cfgPort : 10100;
-  const child = spawn(process.execPath, [process.argv[1], "start", "--port", String(pinPort)], {
+  const child = spawn(process.execPath, selfLaunchArgv(["start", "--port", String(pinPort)]), {
     detached: true,
     stdio: "ignore",
     windowsHide: true,
-    env: { ...process.env, OCX_SERVICE: "1" },
+    env: withProcessRuntimeProvenance({ ...process.env, OCX_SERVICE: "1" }),
   });
   child.unref();
   const deadline = Date.now() + 8_000;
@@ -232,6 +306,22 @@ export function claudeNotFoundHint(
   return platform === "win32" && code === 9009 && !signal ? CLAUDE_INSTALL_HINT : null;
 }
 
+export function shouldAllowRootSkipPermissions(
+  args: readonly string[],
+  getuid: (() => number) | null | undefined = process.getuid,
+): boolean {
+  return args.includes("--dangerously-skip-permissions")
+    && typeof getuid === "function"
+    && getuid() === 0;
+}
+
+export function rootSkipPermissionsNotice(env: ClaudeLaunchEnv): string {
+  if (env.IS_SANDBOX === "1") {
+    return "⚠ Root --dangerously-skip-permissions requested: OpenCodex set IS_SANDBOX=1 to bypass Claude Code's root guard. OpenCodex did not create an OS sandbox; prefer running as a non-root user.";
+  }
+  return `⚠ Root --dangerously-skip-permissions requested: preserving user IS_SANDBOX=${env.IS_SANDBOX}; Claude Code's root guard remains in control.`;
+}
+
 export async function cmdClaude(args: string[]): Promise<number> {
   const config = loadConfig();
   if (config.claudeCode?.enabled === false) {
@@ -244,11 +334,15 @@ export async function cmdClaude(args: string[]): Promise<number> {
     return 1;
   }
   const contextWindows = await fetchClaudeContextWindows(config, port);
-  const env = buildClaudeEnv(config, port, process.env, contextWindows);
+  const allowRootSkipPermissions = shouldAllowRootSkipPermissions(args);
+  const env = buildClaudeEnv(config, port, process.env, contextWindows, { allowRootSkipPermissions });
+  if (allowRootSkipPermissions) {
+    console.error(rootSkipPermissionsNotice(env));
+  }
   // Pre-write the CLI's gateway-model cache (devlog 030): without a token the CLI
   // never refreshes it, so the picker would keep showing yesterday's aliases.
   try {
-    const cachePath = await refreshGatewayModelCacheFromProxy(port);
+    const cachePath = await refreshGatewayModelCacheFromProxy(port, { admissionConfig: config });
     if (cachePath === null) {
       console.error("⚠ Gateway model cache could not be refreshed; the model picker may be stale.");
     }

package/src/cli/codex-log-guard-doctor.ts

@@ -0,0 +1,103 @@
+import { inspectCodexLogs, type CodexLogGuardInspection } from "../codex/log-guard/inspect";
+import {
+  getCodexLogGuardProtectionStatus,
+  type CodexLogGuardStatus,
+} from "../codex/log-guard/protection";
+
+function kib(bytes: number): string {
+  return `${(bytes / 1024).toFixed(1)} KiB`;
+}
+
+function fileMetadataLines(report: CodexLogGuardInspection): string[] {
+  if (report.externalSqliteHome === null) return [];
+  const location = report.externalSqliteHome ? "external sqlite_home" : "CODEX_HOME sqlite_home";
+  return [
+    `         ${location}; DB ${kib(report.files.databaseBytes)}, WAL ${kib(report.files.walBytes)}, SHM ${kib(report.files.shmBytes)}`,
+  ];
+}
+
+type DoctorReport = CodexLogGuardInspection | CodexLogGuardStatus;
+
+function protectionLines(report: DoctorReport): string[] {
+  if (!("protection" in report)) return [];
+  const protection = report.protection;
+  switch (protection.state) {
+    case "active":
+      return [`  ok     protection active (${protection.desiredMode})`];
+    case "off":
+      return ["  --     protection off"];
+    case "drifted":
+      return [
+        `  WARN   protection drifted (desired ${protection.desiredMode}; observed ${protection.observedMode})`,
+        "         Action: ocx storage codex-logs repair",
+      ];
+    case "unsupported":
+      return ["  --     protection unavailable for this schema"];
+    case "unknown":
+      return ["  WARN   protection state unknown; inspect reserved Log Guard triggers before changing mode"];
+  }
+}
+
+export function formatCodexLogGuardDoctor(report: DoctorReport): string[] {
+  const lines = ["Codex diagnostic logs"];
+  lines.push(...protectionLines(report));
+
+  if (report.schema.state === "unavailable") {
+    lines.push("  --     inspection unavailable");
+    return lines;
+  }
+  if (report.schema.state === "missing") {
+    lines.push("  --     logs_2.sqlite is not present");
+    return lines;
+  }
+  if (report.schema.state === "unreadable") {
+    lines.push("  --     logs_2.sqlite is unreadable; inspection metadata only");
+    lines.push(...fileMetadataLines(report));
+    lines.push("         checkpointed read-only snapshot; activity rate not measured");
+    return lines;
+  }
+  if (report.schema.state === "unsupported") {
+    lines.push("  --     unknown schema; inspection only");
+  } else {
+    lines.push("  ok     schema compatible");
+  }
+
+  lines.push(...fileMetadataLines(report));
+
+  if (report.metrics) {
+    lines.push(
+      `         ${report.metrics.totalRows} rows; TRACE ${(report.metrics.traceShare * 100).toFixed(1)}%; reclaimable ${kib(report.metrics.reclaimableBytes)}`,
+    );
+    const top = report.metrics.topTargets[0];
+    if (top) lines.push(`         top target ${top.target} (${top.rows} rows)`);
+  }
+
+  lines.push("         checkpointed read-only snapshot; activity rate not measured");
+  return lines;
+}
+
+export interface CodexLogGuardDoctorDeps {
+  inspect?: () => DoctorReport;
+  log?: (line: string) => void;
+}
+
+/** Observe-only doctor section. Inspection failures are reported without mutating or failing doctor. */
+export function printCodexLogGuardDoctor(deps: CodexLogGuardDoctorDeps = {}): void {
+  const inspect = deps.inspect ?? getCodexLogGuardProtectionStatus;
+  const log = deps.log ?? console.log;
+  try {
+    for (const line of formatCodexLogGuardDoctor(inspect())) log(line);
+  } catch (error) {
+    // Production can still fall back to PR 1's simpler inspector if the enriched
+    // protection lookup fails. An injected inspector is a test/caller boundary:
+    // never escape that boundary and touch the real Codex home behind its back.
+    if (!deps.inspect) {
+      try {
+        for (const line of formatCodexLogGuardDoctor(inspectCodexLogs())) log(line);
+        return;
+      } catch { /* report the original failure below */ }
+    }
+    log("Codex diagnostic logs");
+    log("  --     inspection unavailable");
+  }
+}

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

@@ -17,6 +17,8 @@ const DEFAULT_DEPS: CodexShimAutoRestoreCliDeps = {
 
 export function skipsCodexShimAutoRestore(command: string | undefined, args: string[]): boolean {
   if (command === "uninstall" || command === "remove") return true;
+  // `lab` is read-only inspection; it must not trigger shim side effects.
+  if (command === "lab") return true;
   return command === "codex-shim" && ["install", "uninstall", "remove"].includes(args[1] ?? "");
 }