@bitkyc08/opencodex 2.11.1 → 2.12.0

package/src/adapters/openai-responses.ts

@@ -538,6 +538,65 @@ function repairOrphanedInputItems(body: unknown, dropReasoning: boolean): unknow
   return changed ? { ...body, input: repaired } : body;
 }
 
+/**
+ * Make unambiguous Responses tool pairs adjacent for upstream parsers that require it.
+ *
+ * [Decision Log]
+ * - 목적과 의도: Keep Codex hook-injected developer context without letting it make a strict upstream reject the matching tool result.
+ * - 기존 구현 및 제약 조건: The orphan repair verifies only pair presence; globally reordering valid history would change tolerant providers unnecessarily.
+ * - 검토한 주요 대안: Reorder every Responses request, drop the intervening message, or gate a lossless reorder behind provider capability metadata.
+ * - 선택한 방식: Reorder only unique call/result pairs for providers that explicitly require adjacency, preserving every intervening item immediately after the result.
+ * - 다른 대안 대신 이 방식을 선택한 이유: The provider gate limits semantic blast radius, while refusing ambiguous duplicate ids avoids guessing which result belongs to which call.
+ * - 장점, 단점 및 영향: DeepSeek receives the adjacency its parser requires; tolerant providers stay byte/order equivalent. Ambiguous duplicate ids still fail upstream rather than being silently rewritten.
+ */
+function normalizeResponsesToolResultAdjacency(body: unknown): unknown {
+  if (!isPlainObject(body) || !Array.isArray(body.input)) return body;
+  const input = body.input;
+  const calls = new Map<string, number[]>();
+  const outputs = new Map<string, number[]>();
+
+  const appendIndex = (map: Map<string, number[]>, key: string, index: number): void => {
+    const existing = map.get(key);
+    if (existing) existing.push(index);
+    else map.set(key, [index]);
+  };
+
+  for (let index = 0; index < input.length; index += 1) {
+    const item = input[index];
+    if (!isPlainObject(item) || typeof item.call_id !== "string" || item.call_id.length === 0) continue;
+    if (item.type === "function_call" || item.type === "local_shell_call") {
+      appendIndex(calls, `function:${item.call_id}`, index);
+    } else if (item.type === "custom_tool_call") {
+      appendIndex(calls, `custom:${item.call_id}`, index);
+    } else if (item.type === "function_call_output") {
+      appendIndex(outputs, `function:${item.call_id}`, index);
+    } else if (item.type === "custom_tool_call_output") {
+      appendIndex(outputs, `custom:${item.call_id}`, index);
+    }
+  }
+
+  const movedOutputIndices = new Set<number>();
+  const outputAfterCall = new Map<number, unknown>();
+  for (const [key, callIndices] of calls) {
+    const outputIndices = outputs.get(key);
+    if (callIndices.length !== 1 || outputIndices?.length !== 1) continue;
+    const callIndex = callIndices[0]!;
+    const outputIndex = outputIndices[0]!;
+    if (outputIndex === callIndex + 1) continue;
+    movedOutputIndices.add(outputIndex);
+    outputAfterCall.set(callIndex, input[outputIndex]);
+  }
+  if (movedOutputIndices.size === 0) return body;
+
+  const normalized: unknown[] = [];
+  for (let index = 0; index < input.length; index += 1) {
+    if (movedOutputIndices.has(index)) continue;
+    normalized.push(input[index]);
+    if (outputAfterCall.has(index)) normalized.push(outputAfterCall.get(index));
+  }
+  return { ...body, input: normalized };
+}
+
 /**
  * Remove `previous_response_id` before forwarding. Two triggers:
  * - the proxy expanded the request into a full input replay (the id is now redundant), or
@@ -1158,6 +1217,9 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
       if (forward || stateless) {
         outBody = repairOrphanedInputItems(outBody, unexpandedMiss);
       }
+      if (provider.requiresAdjacentResponsesToolResults === true) {
+        outBody = normalizeResponsesToolResultAdjacency(outBody);
+      }
       if (forward) {
         outBody = stripUnsupportedForwardParams(outBody);
       } else {

package/src/adapters/tool-catalog-nudge.ts

@@ -1,8 +1,6 @@
 import {
-  isAllowedToolChoice,
   namespacedToolName,
-  toolAllowedByChoice,
-  toolChoiceAliases,
+  toolChoiceToolPredicate,
   type OcxRequestOptions,
   type OcxTool,
   type OcxProviderConfig,
@@ -18,13 +16,6 @@ function uniqueNames(names: readonly string[]): string[] {
   return [...new Set(names.filter(name => name.trim().length > 0))];
 }
 
-function toolChoiceAllows(tool: Pick<OcxTool, "namespace" | "name">, toolChoice: OcxRequestOptions["toolChoice"] | undefined): boolean {
-  if (!toolChoice || toolChoice === "auto" || toolChoice === "required") return true;
-  if (toolChoice === "none") return false;
-  if (isAllowedToolChoice(toolChoice)) return toolAllowedByChoice(tool, new Set(toolChoice.allowedTools));
-  return toolChoiceAliases(tool).includes(toolChoice.name);
-}
-
 function isOpenAIOrChatGPTHost(hostname: string): boolean {
   return hostname === "openai.com"
     || hostname.endsWith(".openai.com")
@@ -65,7 +56,7 @@ export function buildNonOpenAIToolCatalogNudgeForTools(
   toWireName: (tool: Pick<OcxTool, "namespace" | "name">) => string = tool => namespacedToolName(tool.namespace, tool.name),
 ): string | undefined {
   const visibleNames = tools
-    ?.filter(tool => toolChoiceAllows(tool, toolChoice))
+    ?.filter(toolChoiceToolPredicate(toolChoice))
     .map(toWireName);
   return buildNonOpenAIToolCatalogNudgeFromNames(visibleNames);
 }

package/src/claude/outbound.ts

@@ -9,6 +9,7 @@
  *  - message_delta.usage is cumulative; message_start embeds a full message snapshot.
  *  - errors: {type:"error", error:{type,message}}; may arrive mid-stream after HTTP 200.
  */
+import { createHash } from "node:crypto";
 import { isTransientUpstreamStatus } from "../lib/upstream-retry";
 import {
   isTranslatorBudgetExceededError,
@@ -24,6 +25,27 @@ function isRec(v: unknown): v is Rec {
   return !!v && typeof v === "object" && !Array.isArray(v);
 }
 
+function reasoningIdentityDigest(value: string): string {
+  return createHash("sha256").update(value).digest("base64url");
+}
+
+/** Fixed-size identity that preserves protocol boundaries without retaining upstream strings. */
+function boundedReasoningIdentity(value: unknown): string {
+  if (typeof value === "number") {
+    if (Number.isSafeInteger(value) && value >= 0) return `n${value}`;
+    if (Number.isFinite(value)) return `d${value}`;
+    return Number.isNaN(value) ? "dnan" : value > 0 ? "dinf" : "d-inf";
+  }
+  if (typeof value === "string") {
+    return `s${reasoningIdentityDigest(value)}`;
+  }
+  if (value === null) return "z";
+  if (typeof value === "boolean") return value ? "b1" : "b0";
+  if (Array.isArray(value)) return `a${reasoningIdentityDigest(JSON.stringify(value) ?? "[]")}`;
+  // Preserve the prior String(record) category semantics without serializing untrusted trees.
+  return typeof value === "object" ? "o" : "u";
+}
+
 function uuid(): string {
   return crypto.randomUUID().replace(/-/g, "");
 }
@@ -188,7 +210,7 @@ interface OpenBlock {
   argsBufBytes?: number;
   webSearchArgsEmitted?: boolean;
   callId?: string;
-  /** Last reasoning part identity (item + summary/content index) seen by this thinking block. */
+  /** Last fixed-size reasoning identity (item + summary/content index) seen by this block. */
   reasoningPartKey?: string;
 }
 
@@ -245,14 +267,13 @@ export function responsesSseToAnthropicSse(
         emit("message_start", { type: "message_start", message: messageSnapshot(model) });
         emit("ping", { type: "ping" });
       };
-      // Idle keepalive (devlog 100): real Anthropic streams may interleave pings anywhere;
-      // synthesizing one during upstream silence protects remote deployments behind
-      // LB/NAT idle timeouts and covers slow first tokens. Cheap and spec-legal.
+      // Once a semantic Anthropic message has started, keepalive pings protect remote
+      // deployments behind LB/NAT idle timeouts. Transport-only Responses prelude frames
+      // must not manufacture a message before a possible initial error.
       if (pingIntervalMs > 0) {
         pingTimer = setInterval(() => {
-          if (terminated) return;
+          if (terminated || !started) return;
           try {
-            ensureStarted();
             emit("ping", { type: "ping" });
           } catch { /* controller torn down; the read loop is ending anyway */ }
         }, pingIntervalMs);
@@ -328,20 +349,24 @@ export function responsesSseToAnthropicSse(
           ))));
           return;
         }
-        ensureStarted();
-        closeOpenBlock();
         const type = upstreamDerived && isTransientUpstreamStatus(status) ? "overloaded_error" : undefined;
+        if (!started) {
+          // An initial upstream failure is an Anthropic error stream, not a partial message.
+          // Do not manufacture message_start/ping before the terminal error.
+          emit("error", anthropicErrorBody(status, message, type, code));
+          return;
+        }
+        closeOpenBlock();
         emit("error", anthropicErrorBody(status, message, type, code));
       };
 
       const handleFrame = (eventName: string, data: Rec) => {
         switch (eventName) {
           case "response.created":
-            ensureStarted();
+            // Transport prelude only. Start Anthropic framing on semantic output or completion.
             break;
           case "response.heartbeat":
-            ensureStarted();
-            emit("ping", { type: "ping" });
+            if (started) emit("ping", { type: "ping" });
             break;
           case "response.output_text.delta": {
             if (typeof data.delta !== "string" || data.delta.length === 0) break;
@@ -361,9 +386,12 @@ export function responsesSseToAnthropicSse(
             // so multi-part summaries do not glue into one run-on paragraph. Frames
             // without part indices produce a constant key and never get a separator.
             const slot = eventName === "response.reasoning_summary_text.delta"
-              ? `s${String(data.summary_index)}`
-              : `c${String(data.content_index)}`;
-            const partKey = `${String(data.item_id)}:${slot}`;
+              ? `s${boundedReasoningIdentity(data.summary_index)}`
+              : `c${boundedReasoningIdentity(data.content_index)}`;
+            // Upstream string metadata can be arbitrarily large. Hash strings into fixed-size
+            // components while retaining item and part equality, rather than dropping item_id and
+            // accidentally joining distinct malformed reasoning items.
+            const partKey = `${boundedReasoningIdentity(data.item_id)}:${slot}`;
             if (open!.reasoningPartKey !== undefined && open!.reasoningPartKey !== partKey) {
               emit("content_block_delta", {
                 type: "content_block_delta", index: open!.index,

package/src/cli/claude.ts

@@ -12,6 +12,7 @@ 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";
@@ -34,6 +35,29 @@ export type ClaudeEnvDeps = {
   preBunAnthropicSlots?: readonly AnthropicParentEnvSlot[] | null;
 };
 
+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
@@ -54,7 +78,7 @@ 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;
+  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
@@ -95,10 +119,12 @@ export function buildClaudeEnv(
   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 {
@@ -110,8 +136,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
@@ -126,11 +170,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에서 인증 모드를 직접 지정하면 이 판단을 덮어쓸 수 있습니다.");
   }
@@ -152,7 +204,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

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] ?? "");
 }
 

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

@@ -60,9 +60,16 @@ export function codexShimReadinessWarnings(
 
 export function collectCodexShimReadinessWarnings(): string[] {
   const config = loadConfig();
+  let externalProvider: string | null = null;
+  try {
+    externalProvider = currentExternalCodexModelProvider();
+  } catch {
+    // Routing readiness is advisory; getCodexRoutingKind() already reports an
+    // unreadable config as unknown, so preserve that warning instead of failing.
+  }
   return codexShimReadinessWarnings({
     routingKind: getCodexRoutingKind(),
-    externalProvider: currentExternalCodexModelProvider(),
+    externalProvider,
     processProxyEnvPresent: PROXY_ENV_KEYS.some(key => Boolean(process.env[key]?.trim())),
     configuredProxyResolved: Boolean(resolveEnvValue(config.proxy)?.trim()),
   });

package/src/cli/config-command.ts

@@ -1,6 +1,6 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import { clearCodexAccountPin } from "../codex/account-priority";
-import { getConfigPath, readConfigDiagnostics, saveConfig, validateConfigCandidate } from "../config";
+import { getConfigPath, readConfigDiagnostics, sanitizeModelCostsForDisplay, saveConfig, validateConfigCandidate } from "../config";
 import { VISION_REASONING_EFFORTS, isVisionReasoningEffort } from "../reasoning-effort";
 import type { OcxConfig } from "../types";
 import { normalizeVisionReasoningForModel } from "../vision/reasoning";
@@ -20,6 +20,9 @@ const BLOCKED_SEGMENTS = new Set(["__proto__", "prototype", "constructor"]);
 
 function redact(value: unknown, key = ""): unknown {
   if (SECRET_KEYS.test(key) && typeof value === "string") return value ? "********" : value;
+  // modelCosts rows are keyed by model id; a pasted API key in a key position
+  // must not be echoed back by config show/get (values are already redacted).
+  if (key === "modelCosts") return sanitizeModelCostsForDisplay(value);
   if (Array.isArray(value)) return value.map(item => redact(item));
   if (value && typeof value === "object") {
     return Object.fromEntries(Object.entries(value as Record<string, unknown>).map(([childKey, child]) => [childKey, redact(child, childKey)]));

package/src/cli/doctor.ts

@@ -23,6 +23,7 @@ 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 {
@@ -942,6 +943,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");

package/src/cli/help.ts

@@ -264,6 +264,20 @@ const helpEntries: Record<string, HelpEntry> = {
       "Invalid or unknown arguments exit 64. Not-ready, pending, failed, timeout, and unreachable exit 1.",
     ],
   },
+  lab: {
+    usage: "ocx lab <status|verdicts|subjects|subject|observations|events|event|artifacts|artifact|catalog> [options] [--json]",
+    summary: "Read-only Compatibility Lab projection inspection (local SQLite; no daemon).",
+    details: [
+      "status                Projection availability, schema versions, and row counts.",
+      "verdicts              Paginated derived compatibility verdicts with filters.",
+      "subjects              List subjects; subject <id> returns one typed subject.",
+      "observations          Paginated observation rows from the projection.",
+      "events                Event history; event <id> returns one safe typed event.",
+      "artifacts             Artifact metadata only (no content download).",
+      "catalog               Packaged protocol/live scenario catalog metadata.",
+      "Reads never rebuild the projection, trigger probes, or require the proxy.",
+    ],
+  },
 };
 
 function packageVersion(): string {
@@ -318,6 +332,7 @@ Usage:
   ocx grok <sub>              Grok Build model selection and apply
   ocx system <sub>            Runtime settings, startup, sync, and updates
   ocx config <sub>            Validated configuration show/get/set/import/export
+  ocx lab <sub>               Read-only Compatibility Lab projection inspection
   ocx claude [args...]        Launch Claude Code wired to the proxy (model discovery on)
   ocx claude desktop [sub]    Manage and apply Claude Desktop's four-family profile
   ocx opencode [args...]      Launch opencode wired to the proxy (runtime provider config)

package/src/cli/index.ts

@@ -219,6 +219,22 @@ async function chooseListenPort(requestedPort?: number): Promise<number> {
   }
 }
 
+async function findProxyOwnerBeforeJournalRecovery(
+  options: { probeConfiguredPort?: boolean } = {},
+): Promise<{ live: LiveProxy | null; pidSnapshot: number | null }> {
+  const pidSnapshot = readPidFileValue();
+  const hasRuntimeOwner = readRuntimePort() !== null;
+  const shouldProbe = pidSnapshot !== null || hasRuntimeOwner || options.probeConfiguredPort === true;
+  const live = shouldProbe ? await findLiveProxy() : null;
+  if (live) return { live, pidSnapshot };
+
+  // The probe established that the snapshotted owner is stale. Compare before
+  // deleting so a concurrent start that rewrote the PID file keeps its state.
+  removePidIfValueIs(pidSnapshot);
+  if (!currentExternalCodexModelProvider()) reconcileJournal();
+  return { live: null, pidSnapshot };
+}
+
 async function handleStart(options: { block?: boolean } = {}) {
   // Native (WinSW) service mode has no batch wrapper to read the service token file
   // into the environment, so the app loads it here before the server binds. The server
@@ -226,15 +242,10 @@ async function handleStart(options: { block?: boolean } = {}) {
   const serviceToken = loadServiceTokenFromFile(process.env);
   if (serviceToken) process.env.OPENCODEX_API_AUTH_TOKEN = serviceToken;
   const requestedPort = parsePortOption();
-  if (!currentExternalCodexModelProvider()) reconcileJournal();
-  const existingPid = readPid();
-  if (existingPid) {
-    const live = await findLiveProxy();
-    if (live) {
-      console.error(`⚠️  Proxy already running (PID ${live.pid ?? existingPid}, port ${live.port}). Use 'ocx stop' first.`);
-      process.exit(1);
-    }
-    removePid(existingPid);
+  const owner = await findProxyOwnerBeforeJournalRecovery();
+  if (owner.live) {
+    console.error(`⚠️  Proxy already running (PID ${owner.live.pid ?? owner.pidSnapshot ?? "unknown"}, port ${owner.live.port}). Use 'ocx stop' first.`);
+    process.exit(1);
   }
 
   // Interactive-only update prompt. Must run BEFORE we bind a port / write a
@@ -442,13 +453,13 @@ function detachedStartEnvironment(): NodeJS.ProcessEnv {
 }
 
 async function handleEnsure(options: { existingIsSuccess?: boolean } = {}): Promise<boolean> {
-  if (!currentExternalCodexModelProvider()) reconcileJournal();
+  const owner = await findProxyOwnerBeforeJournalRecovery({ probeConfiguredPort: true });
   const config = loadConfig();
   if (!codexAutoStartEnabled(config)) {
     console.log("Codex autostart is disabled.");
     return false;
   }
-  const live = await findLiveProxy();
+  const live = owner.live;
   if (live) {
     if (options.existingIsSuccess === false) {
       console.error("Proxy appeared while restart was confirming absence; no start was attempted.");
@@ -1356,6 +1367,11 @@ switch (command) {
     process.exitCode = await handleConfigCommand(args.slice(1));
     break;
   }
+  case "lab": {
+    const { handleLabCommand } = await import("./lab");
+    process.exitCode = await handleLabCommand(args.slice(1));
+    break;
+  }
   case "claude": {
     const { cmdClaude } = await import("./claude");
     // "ocx claude desktop" → write Desktop 3P config