@bitkyc08/opencodex 2.67.0 → 2.68.0-preview.20260927

package/src/cli/index.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env bun
+import { serviceStayOutExitCode } from "../service/windows-wrapper-exit";
 import { spawn } from "node:child_process";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -83,10 +84,12 @@ import { requestBoundSystemRestart } from "./system-restart-client";
 import { installCrashGuards } from "../lib/crash-guard";
 import { SpendLedgerOwnerError } from "../lib/spend-ledger-owner";
 import { redactUrlForLog } from "../lib/redact";
-import { dispatchCommand, decideBusyPreferredPort, decideStartWithLiveOwner } from "./dispatch";
+import { dispatchCommand, decideBusyPreferredPort, decideStartExitTeardown, decideStartWithLiveOwner, startupLeftCodexNativeLine } from "./dispatch";
+import { probeOwnerPastRestartParent, takeRestartHandoffMarkers } from "./restart-handoff";
 import { AuxiliaryListenerBindError, findAvailablePort, isAddrInUse, PortUnavailableError, shouldPersistSelectedPort, waitForPortAvailable } from "../server/ports";
 import {
   findLiveProxy,
+  proveLiveProxyOwnedByHome,
   probeEndpointLiveness,
   probeHostname,
   probePortOwner,
@@ -127,13 +130,9 @@ import {
   StartOwnershipRollbackUncertainError,
 } from "./start-ownership-publication";
 import { syncModelsToCodex } from "../codex/sync";
-import {
-  HUB_GATED_SKIP_MESSAGE,
-  localClientSkipReason,
-  shouldSyncGrokOnStart,
-  syncCodexOnStartIfEnabled,
-  type LocalClientSkipReason,
-} from "../codex/desired-state";
+import { localClientSkipReason, shouldSyncGrokOnStart, syncCodexOnStartIfEnabled } from "../codex/desired-state";
+import { honorSiblingMarker, markSiblingStart, siblingOfLivePort, siblingRuntimeField, siblingStopFoundOwner, withoutSiblingMarker } from "../codex/sibling-start";
+import { consumeSiblingHandoff } from "../codex/sibling-handoff";
 import {
   reconcileClientStartupBeforeReady,
   syncClaudeAgentDefsAtProxyStartup,
@@ -232,19 +231,6 @@ async function waitForProxy(timeoutMs = 8_000): Promise<LiveProxy | null> {
   return null;
 }
 
-/**
- * The one startup line for "nothing was written to Codex".
- *
- * Two very different facts reached it: the user's own OFF switch, and a hub declining to
- * rewrite its own local clients. Printing the toggle's wording for the gate is what made
- * operators hunt for a switch they never set (#4236).
- */
-function startupLeftCodexNativeLine(reason: LocalClientSkipReason): string {
-  return reason === "hub-gated"
-    ? `   ${HUB_GATED_SKIP_MESSAGE} Startup left Codex native.`
-    : "   Codex integration OFF; startup left Codex native.";
-}
-
 /** Argv for detached `start`, optionally hard-pinning the listen port. */
 function startArgv(port?: number): string[] {
   const args = ["start"];
@@ -330,10 +316,9 @@ async function chooseListenPort(
         ocxService: process.env.OCX_SERVICE,
       });
       if (decision === "service-stay-out") {
-        // Same contract as the pre-bind owner check: the wrapper's retry loop terminates
-        // on a zero exit, and the port it was asked to serve is already served.
+        // Signal intentional stay-out to wrappers that support the exit protocol.
         console.log(`Proxy already running (PID ${holder?.pid ?? "unknown"}, port ${preferred}); service wrapper staying out of the way.`);
-        throw new StartCommandExit(0);
+        throw new StartCommandExit(serviceStayOutExitCode());
       }
       if (decision === "refuse-live-proxy") {
         console.error(`⚠️  Proxy already running (PID ${holder?.pid ?? "unknown"}, port ${preferred}). Use 'ocx stop' first.`);
@@ -381,7 +366,8 @@ async function findProxyOwnerBeforeJournalRecovery(
   // 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()) {
+  // A marked sibling's owner can be down mid-restart; its journal is still not ours to replay.
+  if (!currentExternalCodexModelProvider() && siblingOfLivePort() === null) {
     const clientState = readClientConnectionState();
     reconcileJournal(clientState.kind === "connected"
       ? { activeClientApiKeyId: clientState.value.apiKeyId }
@@ -427,42 +413,36 @@ async function handleStart(options: { block?: boolean } = {}) {
     }
   }
   const requestedPort = startOpts.port;
-  // Always probe the configured port, even when both state files are absent. A
-  // fallback-port sibling overwrites the pid/runtime records when it starts and
-  // removes them on its own shutdown, so their absence proves nothing about the
-  // configured port. Without the probe, `start` shadowed a healthy proxy with an
-  // ephemeral-port copy and re-pointed client config at the copy; the next sibling
-  // shutdown then left no runtime record for discovery at all. `handleEnsure`
-  // already passes this; `handleStart` is the path that did not.
-  const owner = await findProxyOwnerBeforeJournalRecovery({ probeConfiguredPort: true });
-  let siblingStart = false;
+  // Probe the configured port even without state files: a fallback sibling can remove them,
+  // and an unprobed start could shadow the owner and reroute Codex to a short-lived port.
+  // Consume a sibling replacement's handoff before probing, even if its owner is momentarily down.
+  let siblingStart = honorSiblingMarker(process.env, consumeSiblingHandoff) !== null;
+  // A restart replacement waits out its draining parent instead of refusing it, and bounds its handoff log (restart-handoff.ts).
+  const restartParent = { restartParentPid: takeRestartHandoffMarkers(process.env), requestedPort, ocxService: process.env.OCX_SERVICE };
+  const owner = await probeOwnerPastRestartParent(() => findProxyOwnerBeforeJournalRecovery({ probeConfiguredPort: true }), restartParent);
   if (owner.live) {
     // Rationale and the full decision table live on `decideStartWithLiveOwner`.
     const decision = decideStartWithLiveOwner({
       livePort: owner.live.port,
-      requestedPort,
-      ocxService: process.env.OCX_SERVICE,
+      livePid: owner.live.pid, ...restartParent,
     });
     if (decision === "service-stay-out") {
-      // Service-wrapper context (opencodex-service.cmd `:loop`): a healthy proxy from
-      // ANY source means the requested port is already served. Exit 0 so the wrapper's
-      // `if %ERRORLEVEL% NEQ 0` retry loop terminates instead of respawning every 5s
-      // against a listener it can never claim (observed as an endless
-      // "Proxy already running" service.log loop).
+      // A live owner is an intentional stay-out, not an unexpected child exit.
       console.log(`Proxy already running (PID ${owner.live.pid ?? owner.pidSnapshot ?? "unknown"}, port ${owner.live.port}); service wrapper staying out of the way.`);
-      process.exit(0);
+      process.exit(serviceStayOutExitCode());
     }
-    if (decision === "refuse") {
+    if (decision === "refuse" || decision === "await-parent") {
       console.error(`⚠️  Proxy already running (PID ${owner.live.pid ?? owner.pidSnapshot ?? "unknown"}, port ${owner.live.port}). Use 'ocx stop' first.`);
       process.exit(1);
     }
-    // Sibling path. Honest about the side effects it shares with any start in this home:
-    // the new instance takes over this home's ocx.pid / runtime-port.json while it runs,
-    // and re-points this home's Codex config at the new port when injection applies.
-    // What it must NOT do is persist its port into config.port: the configured-port
-    // proxy is still the owner of this home, and a later `ocx service` reads config.port
-    // to bake the service (observed: a probe on 10198 left the service pinned there).
+    // Sibling path. The new instance takes over this home's ocx.pid / runtime-port.json while
+    // it runs, and nothing else: Codex, Grok, Claude and the system env keep pointing at the
+    // live proxy for this process's whole lifetime, its exit and `ocx stop` included, so the
+    // mark goes down before any client write (`src/codex/sibling-start.ts`). Nor may it persist
+    // its port into config.port: the configured-port proxy still owns this home, and a later
+    // `ocx service` reads config.port to bake the service (a probe on 10198 pinned it there).
     siblingStart = true;
+    markSiblingStart(owner.live.port);
     console.warn(
       `Proxy already running on port ${owner.live.port}; requested a second instance on port ${requestedPort}. `
       + `Startup continues only for an independent OPENCODEX_HOME; one state directory has one spend-ledger writer.`,
@@ -485,8 +465,9 @@ async function handleStart(options: { block?: boolean } = {}) {
 
   // Interactive-only update prompt. Must run BEFORE we bind a port / write a
   // PID: choosing "Update now" installs globally and exits, so we never want a
-  // live daemon holding resources while it overwrites its own binary.
-  await maybeShowUpdatePrompt();
+  // live daemon holding resources while it overwrites its own binary. Never from a
+  // sibling: replacing the global package makes the live proxy drain and restart.
+  if (!siblingStart) await maybeShowUpdatePrompt();
 
   type StartServerModule = typeof import("../server");
   type BoundStart = {
@@ -508,18 +489,20 @@ async function handleStart(options: { block?: boolean } = {}) {
         if (fencedLive) {
           const decision = decideStartWithLiveOwner({
             livePort: fencedLive.port,
+            livePid: fencedLive.pid, restartParentPid: restartParent.restartParentPid,
             requestedPort,
             ocxService: process.env.OCX_SERVICE,
           });
           if (decision === "service-stay-out") {
             console.log(`Proxy already running (PID ${fencedLive.pid ?? "unknown"}, port ${fencedLive.port}); service wrapper staying out of the way.`);
-            throw new StartCommandExit(0);
+            throw new StartCommandExit(serviceStayOutExitCode());
           }
-          if (decision === "refuse") {
+          if (decision === "refuse" || decision === "await-parent") {
             console.error(`⚠️  Proxy appeared before bind (PID ${fencedLive.pid ?? "unknown"}, port ${fencedLive.port}). Use 'ocx stop' first.`);
             throw new StartCommandExit(1);
           }
           siblingStart = true;
+          markSiblingStart(fencedLive.port);
         }
 
         // Port selection is check-then-bind. The lease prevents every cooperating start or
@@ -529,6 +512,7 @@ async function handleStart(options: { block?: boolean } = {}) {
         const readinessGate = createReadinessGate();
         const localAttestationSecret = createLocalAttestationSecret();
         const config = loadConfig();
+        await (await import("../plugins/loader")).loadAndReportOcxPlugins();
         let server: ReturnType<typeof serverModule.startServer>;
         for (let attempt = 0; ; attempt++) {
           try {
@@ -566,6 +550,7 @@ async function handleStart(options: { block?: boolean } = {}) {
         port: bound.port,
         hostname: bound.config.hostname,
         attestationSecret: bound.localAttestationSecret,
+        ...siblingRuntimeField(),
       }),
       stopBound: bound => bound.server.stop(true),
       removeRuntime: () => removeRuntimePortIfPidIs(process.pid),
@@ -592,24 +577,25 @@ async function handleStart(options: { block?: boolean } = {}) {
   // background — the first `ocx start` after an update usually races the Codex app's DB lock.
   // Loopback-only (legacy mode still forward-tags) and respects syncResumeHistory opt-out.
   let historyGuardian: ReturnType<typeof startHistoryMigrationGuardian> | undefined;
+  let routingHealer: { stop(): void } | undefined; // routing-healer.ts; stopped first in syncCleanup
 
   let cleaned = false;
   let cleanupSucceeded = true;
   const syncCleanup = () => {
     if (cleaned) return cleanupSucceeded;
     cleaned = true;
+    try { routingHealer?.stop(); } catch { /* best-effort */ }
     try { guardian.stop(); } catch { /* best-effort */ }
     try { historyGuardian?.stop(); } catch { /* best-effort */ }
     // Dashboard drain-and-restart (#563) must not tear down injection: the replacement
-    // process expects Codex/Grok/env fences to still be in place.
-    const recycling = isRecyclingForExit();
-    if (!recycling) {
+    // process expects Codex/Grok/env fences to still be in place. A sibling owns none of them.
+    const teardown = decideStartExitTeardown({ sibling: siblingStart, recycling: isRecyclingForExit(), ocxService: process.env.OCX_SERVICE });
+    if (teardown.revertSystemEnv) {
       try { revertSystemEnv(); } catch { /* best-effort */ }
     }
     removePid(process.pid);
     removeRuntimePort(process.pid);
-    const preserveRouting = process.env.OCX_SERVICE === "1";
-    if (!recycling && !preserveRouting && !currentExternalCodexModelProvider()) {
+    if (teardown.restoreNativeCodex && !currentExternalCodexModelProvider()) {
       try {
         const restored = restoreNativeCodex();
         if (!restored.success) {
@@ -625,7 +611,7 @@ async function handleStart(options: { block?: boolean } = {}) {
     // Grok fence is shared state we must not remove — that service keeps running and would be
     // left pointing nowhere. This guard also covers signal-driven exits, which is the path that
     // would otherwise bypass handleStop's gate entirely.
-    if (!recycling && !preserveRouting && serviceEnvironmentOwnedHere()) {
+    if (teardown.stripGrokConfig && serviceEnvironmentOwnedHere()) {
       try { stripGrokConfig(); } catch { /* best-effort restore */ }
     }
     return cleanupSucceeded;
@@ -672,8 +658,9 @@ async function handleStart(options: { block?: boolean } = {}) {
   // syncCleanup reverts even if injection itself or subsequent startup steps fail).
   const systemEnv = await injectSystemEnv(port, config).catch(() => ({ injected: false }));
   // The hook is useful only for an installed Claude Code CLI. Reconcile instead of
-  // appending unconditionally so stale OpenCodex-owned hooks are removed as well.
-  reportShellHookFailure(reconcileShellHook(systemEnv.injected));
+  // appending unconditionally so stale OpenCodex-owned hooks are removed as well. A sibling
+  // skips it: reconciling to "not injected" would uninstall the live owner's ~/.zshrc hook.
+  if (!siblingStart) reportShellHookFailure(reconcileShellHook(systemEnv.injected));
   await maybeShowStarPrompt(); // once-only Yes/No GitHub-star prompt on first interactive start
   // Codex sync owns the ready/failed verdict, but its successful transition is
   // deferred until the best-effort Claude roster and Desktop registry settle. This
@@ -709,7 +696,7 @@ async function handleStart(options: { block?: boolean } = {}) {
       }
     },
   );
-  if (!startupSync.ran) console.log(startupLeftCodexNativeLine(localClientSkipReason(config)));
+  if (!startupSync.ran) console.log(startupLeftCodexNativeLine(localClientSkipReason(config), server.port ?? port));
   await refreshOwnedRaycastCatalog(config, port);
   // #1046: one warning per startup, after BOTH writes. The server's cache
   // invalidation happens first and the catalog sync second, so the mtime is only
@@ -720,9 +707,11 @@ async function handleStart(options: { block?: boolean } = {}) {
     const { warnIfStaleCodexAppServersAfterStartupWrite } = await import("../codex/app-server-processes");
     warnIfStaleCodexAppServersAfterStartupWrite({ log: console });
   }
-  if (!currentExternalCodexModelProvider() && !shouldInjectApiAuthHeader(config) && config.syncResumeHistory !== false) {
+  if (!siblingStart && !currentExternalCodexModelProvider() && !shouldInjectApiAuthHeader(config) && config.syncResumeHistory !== false) {
     historyGuardian = startHistoryMigrationGuardian();
   }
+  const routingHealerModule = siblingStart ? null : await import("../codex/routing-healer");
+  if (routingHealerModule && !cleaned) routingHealer = routingHealerModule.startCodexRoutingHealer({ port, config }); // `cleaned` read once the import settled
   // Grok Build auto-registration: additive fenced block in ~/.grok/config.toml so an installed
   // grok CLI can pick opencodex-routed models without manual config. No-op when ~/.grok is
   // absent or the bind is non-loopback; removed again by stop/eject/uninstall/shutdown.
@@ -751,9 +740,9 @@ async function handleStart(options: { block?: boolean } = {}) {
 }
 
 function detachedStartEnvironment(): NodeJS.ProcessEnv {
-  const env: NodeJS.ProcessEnv = { ...process.env };
-  // Only a real service wrapper may claim supervision. A detached ensure/tray child
-  // is an ordinary owner: while live it maintains routing, and on exit it restores it.
+  const env: NodeJS.ProcessEnv = withoutSiblingMarker(process.env);
+  // Only a real service wrapper may claim supervision. A detached ensure/tray child is an
+  // ordinary owner, never a sibling: while live it maintains routing, and on exit restores it.
   delete env.OCX_SERVICE;
   return withProcessRuntimeProvenance(env);
 }
@@ -1100,6 +1089,11 @@ async function handleStopUnlocked(snapshot?: GuardedStopSnapshot) {
   // service — the exact failure this flag prevents. A plain stop failure is different: we
   // tried, so local teardown still proceeds.
   let ownershipBlocked = false;
+  // A sibling instance's shared teardown is not this stop's to run: the client routing belongs
+  // to the live proxy it ran beside (`src/codex/sibling-start.ts`). Read before any stop removes
+  // the record; a record left behind by a hard-killed sibling still says so.
+  const siblingOfPort = readRuntimePort()?.siblingOfPort;
+  const stoppingSibling = siblingOfPort !== undefined;
   // Structured twin of the human lines below, for `ocx stop --json`: one document the
   // desktop shell can read across the process boundary (D4). Every field is assigned
   // where the corresponding boolean already flips — the summarizer never re-decides.
@@ -1137,7 +1131,7 @@ async function handleStopUnlocked(snapshot?: GuardedStopSnapshot) {
     .filter(read => isPendingTeardownAbandoned(read, teardownOwnerStillRunning));
   let teardownNonce: string | undefined;
   const claimTeardown = (endpoint: { hostname: string; port: number }, endpointSource: "exact" | "guessed") => {
-    if (teardownNonce) return;
+    if (teardownNonce || stoppingSibling) return;
     try {
       teardownNonce = claimPendingTeardown(endpoint, endpointSource).nonce;
     } catch (err) {
@@ -1155,8 +1149,8 @@ async function handleStopUnlocked(snapshot?: GuardedStopSnapshot) {
    * silently reopening the parent-crash window on the path where the stop is a hard kill
    * and no child teardown runs at all.
    *
-   * So the caller supplies whatever endpoint it already discovered: the orphan path knows
-   * one from `findLiveProxy` even when the runtime record is gone.
+   * So the caller supplies the endpoint it discovered after the orphan listener proves
+   * possession of this home's runtime record, even when the pid file is gone.
    *
    * When nothing resolves, the graceful request cannot be made at all — `stopProxy` goes
    * straight to the kill ladder, no child teardown runs, and there is no receipt to leave
@@ -1201,7 +1195,9 @@ async function handleStopUnlocked(snapshot?: GuardedStopSnapshot) {
           settle: () => settleApprovedTarget(snapshot.approval),
           managerState: () => observeGuardedManagerStopped(snapshot.manager),
         })).service
-      : stopServiceIfInstalledDetailed();
+      // A sibling never runs under a service manager: an installed one belongs to the live owner,
+      // and its ownership check would fail this stop and skip the stale-record purge below.
+      : stoppingSibling ? "absent" : stopServiceIfInstalledDetailed();
     record.service = serviceStop;
     stoppedService = serviceStop === "stopped" || serviceStop === "stopped-respawnable";
     schedulerCanRespawn = serviceStop === "stopped-respawnable";
@@ -1288,14 +1284,22 @@ async function handleStopUnlocked(snapshot?: GuardedStopSnapshot) {
       }
     }
   } else {
-    // Snapshot the stale on-disk state BEFORE the async probe: a concurrent `ocx start`
-    // can write fresh records mid-probe, and the purge below must never delete those.
+    // Snapshot stale state before probing; purge only exact values if another start races us.
     const stalePidValue = readPidFileValue();
     const staleRuntimePid = readRuntimePort()?.pid ?? null;
     // Orphan recovery: a live proxy can outlive its pid file (crash, manual delete,
     // corrupt file). Identity-checked liveness still finds it via the runtime record.
     const live = await findLiveProxy({ acceptPackageTreeFenced: true });
-    if (live?.pid) {
+    if (siblingStopFoundOwner(siblingOfPort, live)) {
+      record.proxy = "not-running";
+      console.log(`The sibling instance is already gone; the proxy on port ${siblingOfPort} was left running.`);
+    } else if (live?.pid && !(await proveLiveProxyOwnedByHome(live))) {
+      stopFailed = true;
+      ownershipBlocked = true;
+      record.proxy = "ownership-refused";
+      console.error(`❌ A proxy answers on port ${live.port}, but it has not proved it belongs to this home; refusing to stop it.`);
+      console.error("   Skipping shared teardown (native Codex restore, Grok config) while that proxy is running.");
+    } else if (live?.pid) {
       try {
         // The probe already found where it answers, and on this path the runtime record is
         // typically what went missing in the first place.
@@ -1343,9 +1347,9 @@ async function handleStopUnlocked(snapshot?: GuardedStopSnapshot) {
     }
   }
   }
-  // Environment ownership is independent from service ownership. Always roll back
-  // current-home variables; the helper refuses foreign markers on its own.
-  try { revertSystemEnv(); } catch { /* best-effort */ }
+  // Environment ownership is independent from service ownership. Roll back current-home
+  // variables (the helper refuses foreign markers on its own) unless a sibling never set them.
+  if (!stoppingSibling) { try { revertSystemEnv(); } catch { /* best-effort */ } }
   // A stopped Windows scheduler is not a proven-down proxy. `killWindowsSchedulerWrappers`
   // is explicitly best-effort and the `:loop` wrapper respawns its child after ~5s, so an
   // immediate probe can see a dead interval and an update can start replacing files right
@@ -1432,8 +1436,9 @@ async function handleStopUnlocked(snapshot?: GuardedStopSnapshot) {
       console.error("   The obligation is preserved; retry once the proxy is confirmed stopped.");
     }
   }
-  if (nativeRestoreHandledByProxy) record.sharedTeardown = "performed-by-proxy";
-  const restoreBlocked = ownershipBlocked || inheritedBlocks || nativeRestoreHandledByProxy;
+  if (nativeRestoreHandledByProxy && !stoppingSibling) record.sharedTeardown = "performed-by-proxy";
+  if (stoppingSibling) console.log(`↩️  Client routing stays on the proxy at port ${siblingOfPort}; this sibling had no shared teardown to run.`);
+  const restoreBlocked = ownershipBlocked || inheritedBlocks || nativeRestoreHandledByProxy || stoppingSibling;
   if (!restoreBlocked) {
     if (recoveredNonces.length > 0) {
       // A previous deferred stop died before restoring, and the probe says its endpoint is
@@ -1974,7 +1979,7 @@ process.exit(await dispatchCommand(head, {
       detached: true,
       stdio: "ignore",
       windowsHide: true,
-      env: withProcessRuntimeProvenance(process.env),
+      env: withProcessRuntimeProvenance(withoutSiblingMarker(process.env)),
     });
     child.unref();
   },

package/src/cli/minimax.ts

@@ -21,6 +21,7 @@ import { isLoopbackHostname } from "../server/auth-cors";
 import { findLiveProxy, probeHostname, type LiveProxy } from "../server/proxy-liveness";
 import type { OcxConfig } from "../types";
 import { opencodeProxyStartEnv } from "./opencode";
+import { withoutSiblingMarker } from "../codex/sibling-start";
 
 export interface MinimaxLaunchEnv {
   [key: string]: string | undefined;
@@ -270,8 +271,9 @@ async function ensureProxy(config: OcxConfig): Promise<LiveProxy | null> {
     stdio: "ignore",
     windowsHide: true,
     // Reuse the established service-token lookup so a detached start works
-    // when admission lives in the hardened token file rather than this shell.
-    env: withProcessRuntimeProvenance(opencodeProxyStartEnv(process.env) as NodeJS.ProcessEnv),
+    // when admission lives in the hardened token file rather than this shell. An ordinary
+    // owner, so a stray sibling marker is dropped.
+    env: withProcessRuntimeProvenance(opencodeProxyStartEnv(withoutSiblingMarker(process.env)) as NodeJS.ProcessEnv),
   });
   child.on("error", () => { /* the bounded health poll reports failure */ });
   child.unref();

package/src/cli/opencode.ts

@@ -50,6 +50,7 @@ import { findLiveProxy, probeHostname, type LiveProxy } from "../server/proxy-li
 import type { OcxConfig } from "../types";
 import { withProcessRuntimeProvenance } from "../lib/bun-runtime";
 import { selfLaunchArgv } from "../lib/self-launch-argv";
+import { withoutSiblingMarker } from "../codex/sibling-start";
 
 /**
  * The provider-block serializer, its constants, and the config-path helpers now live in
@@ -101,6 +102,8 @@ export interface OpencodeProxyModelRow {
   displayName?: string;
   displayNameSource?: "operator" | "provider" | "fallback";
   contextWindow?: number;
+  /** Authoritative output limit (CatalogModel.maxOutputTokens); optional. */
+  maxOutputTokens?: number;
   /** Declared input modalities from `/api/models`; carried into opencode model capabilities. */
   inputModalities?: string[];
   /** Declared effort ladder from `/api/models`; carried into opencode model variants. */
@@ -427,6 +430,7 @@ export function opencodeCatalogFromProxyRows(
       provider: row.provider,
       id: row.id,
       contextWindow: row.contextWindow,
+      ...(typeof row.maxOutputTokens === "number" ? { maxTokens: row.maxOutputTokens } : {}),
       displayName: row.displayNameSource === "fallback" ? undefined : row.displayName,
       ...(Array.isArray(row.inputModalities) && row.inputModalities.length > 0
         ? { inputModalities: [...row.inputModalities] }
@@ -641,7 +645,8 @@ async function ensureProxyForOpencode(config: OcxConfig): Promise<LiveProxy | nu
     detached: true,
     stdio: "ignore",
     windowsHide: true,
-    env: withProcessRuntimeProvenance(opencodeProxyStartEnv(process.env) as NodeJS.ProcessEnv),
+    // An ordinary owner: a stray sibling marker would otherwise mark it before any probe.
+    env: withProcessRuntimeProvenance(opencodeProxyStartEnv(withoutSiblingMarker(process.env)) as NodeJS.ProcessEnv),
   });
   // Without a listener an 'error' (bad argv[1], EMFILE, AV denial) throws synchronously
   // and kills this process; the health poll below already reports the failure properly.

package/src/cli/restart-handoff.ts

@@ -0,0 +1,110 @@
+/**
+ * The replacement side of a restart handoff: a start that finds its own draining parent.
+ *
+ * A dashboard drain-and-restart, a join into a Child and the standalone recycle all spawn a
+ * detached `ocx start` and hand it `OCX_RESTART_PARENT_PID` (`src/server/restart-replacement.ts`).
+ * The deadline and listener-stop-fallback handoffs spawn before the old listener is certainly
+ * gone, so the replacement's owner probe can still reach the parent. Refusing that "proxy already
+ * running" left no proxy at all a moment later, when the parent exited.
+ *
+ * So the owner probe runs through {@link probeOwnerPastRestartParent}: while the live owner is
+ * exactly the restart parent (`decideStartWithLiveOwner` answers `"await-parent"`), it waits for
+ * that process to exit, re-probing once a second in case the parent stops answering first, and
+ * then hands back a fresh probe. The wait is bounded; a parent that outlives it is refused like
+ * any other live proxy. Nothing here signals the parent, and the wait costs nothing on an ordinary
+ * start, which carries no marker.
+ *
+ * {@link takeRestartHandoffMarkers} also consumes the handoff-log flag: a replacement whose output
+ * its parent sent to `restart-handoff.log` bounds that file itself from then on
+ * (`armRestartHandoffLogCap` in `src/server/restart-replacement.ts`). It consumes the desktop app's
+ * supervision marker too, so a later restart exits to the app instead of spawning past it.
+ */
+import { isProcessAlive } from "../lib/process-control";
+import { takeDesktopSupervisedMarker, takeRestartParentMarker } from "../lib/system-restart-contract";
+import { armRestartHandoffLogCap, type RestartHandoffLogCapIo } from "../server/restart-replacement";
+import { decideStartWithLiveOwner } from "./dispatch";
+
+export { takeRestartParentMarker };
+
+/**
+ * Consume everything a parent handed this start, before its first probe: arm the handoff log's cap
+ * when the flag is set, record the desktop app's supervision, and return the restart-parent pid,
+ * honored only for this process's real parent. Every marker is removed from `env`, so no later child
+ * inherits one.
+ */
+export function takeRestartHandoffMarkers(
+  env: Record<string, string | undefined>,
+  logCap: RestartHandoffLogCapIo = {},
+): number | null {
+  armRestartHandoffLogCap(env, logCap);
+  takeDesktopSupervisedMarker(env);
+  return takeRestartParentMarker(env);
+}
+
+/** How long a replacement waits for its own draining parent before refusing it. */
+export const RESTART_PARENT_EXIT_TIMEOUT_MS = 30_000;
+const PARENT_EXIT_POLL_MS = 100;
+const OWNER_REPROBE_MS = 1_000;
+
+export interface OwnerProbeResult {
+  live: { pid: number | null; port: number } | null;
+}
+
+export interface RestartParentOwnerInput {
+  restartParentPid: number | null;
+  requestedPort: number | undefined;
+  ocxService: string | undefined;
+}
+
+export interface RestartParentWaitIo {
+  isAlive?: (pid: number) => boolean;
+  now?: () => number;
+  sleep?: (ms: number) => Promise<void>;
+  timeoutMs?: number;
+  log?: (line: string) => void;
+}
+
+function isRestartParent(owner: OwnerProbeResult, input: RestartParentOwnerInput): boolean {
+  if (owner.live === null) return false;
+  return decideStartWithLiveOwner({
+    livePort: owner.live.port,
+    livePid: owner.live.pid,
+    ...input,
+  }) === "await-parent";
+}
+
+/**
+ * Run the start's owner probe, waiting out this process's own restart parent when that is the
+ * owner it found. Returns the last probe result: after the parent exited or stopped answering,
+ * a fresh one; after the timeout, the one that still names the parent, which the caller refuses.
+ */
+export async function probeOwnerPastRestartParent<T extends OwnerProbeResult>(
+  probe: () => Promise<T>,
+  input: RestartParentOwnerInput,
+  io: RestartParentWaitIo = {},
+): Promise<T> {
+  let owner = await probe();
+  if (input.restartParentPid === null || !isRestartParent(owner, input)) return owner;
+  const parentPid = input.restartParentPid;
+  const isAlive = io.isAlive ?? isProcessAlive;
+  const now = io.now ?? Date.now;
+  const sleep = io.sleep ?? Bun.sleep;
+  const log = io.log ?? ((line: string) => console.log(line));
+  const timeoutMs = io.timeoutMs ?? RESTART_PARENT_EXIT_TIMEOUT_MS;
+  log(`Waiting for the restarting OpenCodex process (PID ${parentPid}) to hand over its port...`);
+  const deadline = now() + timeoutMs;
+  let reprobeAt = now() + OWNER_REPROBE_MS;
+  while (now() < deadline) {
+    if (!isAlive(parentPid)) return probe();
+    if (now() >= reprobeAt) {
+      owner = await probe();
+      if (!isRestartParent(owner, input)) return owner;
+      reprobeAt = now() + OWNER_REPROBE_MS;
+    }
+    const remainingMs = deadline - now();
+    if (remainingMs <= 0) break;
+    await sleep(Math.min(PARENT_EXIT_POLL_MS, remainingMs));
+  }
+  log(`The restarting OpenCodex process (PID ${parentPid}) did not exit within ${Math.round(timeoutMs / 1000)}s.`);
+  return owner;
+}

package/src/cli/status.ts

@@ -18,6 +18,8 @@ import { redactSecretString, redactUserPath } from "../lib/redact";
 import { collectOrcaCodexHomeDiagnostic, type OrcaCodexHomeDiagnostic } from "../codex/home";
 import { grokFenceEndpointDrift, readGrokStatus } from "../grok/status";
 import { effectiveLoopbackListenerPort } from "../codex/loopback-target";
+import { journaledInjectedOpenaiBaseUrl, journaledInjectedRealtimeWsBaseUrl } from "../codex/journal";
+import { detectCodexRoutingDrift, type JournaledCodexRouting } from "../codex/routing-drift";
 import { claudeDesktopIntegrationEnabled } from "../codex/desired-state";
 import { claudeDesktopPolicyHealth, probeClaudeDesktopPolicy, type ClaudeDesktopPolicyHealth } from "../claude/desktop-policy";
 import { collectClientConnectionStatus, type ClientConnectionStatus } from "./connect";
@@ -547,6 +549,36 @@ export function detectMissingCodexCatalogPath(): string | null {
   }
 }
 
+/**
+ * Owned Codex routing that names a local port the live proxy does not serve.
+ *
+ * `classifyCodexRouting` calls that "opencodex-local" whatever the port, so without this line the
+ * state behind a killed second instance was invisible here. Detection is `routing-drift.ts`, the
+ * same rule the owner's healer uses; this only reports and reads the journal without side effects.
+ * A sibling's report says nothing: its routing correctly names the owner it runs beside. Whether a
+ * healer runs, or is gated or paused, is not visible from here, so the line promises only `ocx sync`.
+ */
+export function codexRoutingDriftWarning(input: {
+  content: string | null;
+  livePort: number | undefined;
+  loopbackPort: number | null;
+  /** `siblingOfPort` from this home's runtime record. */
+  siblingOfPort: number | undefined;
+  journaled: () => JournaledCodexRouting;
+}): string | null {
+  const { content, livePort, loopbackPort } = input;
+  if (content === null || livePort === undefined || input.siblingOfPort !== undefined) return null;
+  const drift = detectCodexRoutingDrift(content, {
+    ownPorts: loopbackPort === null ? [livePort] : [livePort, loopbackPort],
+    journaled: input.journaled,
+  });
+  if (drift.kind !== "foreign") return null;
+  const ports = [...new Set(drift.targets.map(target => target.port))].join(", ");
+  return `Codex routing points at port ${ports}, but the proxy is on ${livePort}; if nothing serves that port, `
+    + "new Codex threads fail with \"Connection refused\". Run 'ocx sync' to re-point it now; a running "
+    + "owner proxy may also do that on its own once the port stays dead.";
+}
+
 /**
  * The one state in this report where Codex is broken independently of the proxy (#5261).
  *
@@ -702,6 +734,25 @@ export async function collectStatus(): Promise<CliStatusView> {
       + `${grokDrift.livePort}; grok turns will retry against a closed port. Run 'ocx ensure' to repoint it.`,
     );
   }
+  const codexDrift = (() => {
+    if (!health.ok) return null;
+    try {
+      const siblingOfPort = readRuntimePort()?.siblingOfPort;
+      return codexRoutingDriftWarning({
+        content: siblingOfPort === undefined ? readFileSync(CODEX_CONFIG_PATH, "utf8") : null,
+        livePort: listen.port,
+        loopbackPort: effectiveLoopbackListenerPort(config, listen.port),
+        siblingOfPort,
+        journaled: () => ({
+          openaiBaseUrl: journaledInjectedOpenaiBaseUrl({ readOnly: true }),
+          realtimeWsBaseUrl: journaledInjectedRealtimeWsBaseUrl({ readOnly: true }),
+        }),
+      });
+    } catch {
+      return null; // an absent or unreadable config.toml must never break `ocx status`
+    }
+  })();
+  if (codexDrift) warningParts.push(codexDrift);
   const codexRuntime = {
     path: displayCodexRuntimePath(resolvedRuntime.runtime.command),
     version: resolvedRuntime.runtime.version,