@bitkyc08/opencodex 2.67.0 → 2.68.0

package/src/codex/app-server-processes.ts

@@ -1095,6 +1095,38 @@ export async function collectCodexAppServerCatalogStateForRequest(
   return servableStale ?? flight.promise;
 }
 
+/**
+ * Dashboard read of the request-path catalog state, bounded by `deadlineMs`.
+ *
+ * The request collector keeps the event loop free, but a cold Windows probe still
+ * takes 4-7s (CIM walk plus GetOwner per candidate), and the Models and Subagents
+ * pages cannot render their rosters until these routes answer. The reading only
+ * drives an advisory banner, so a slow probe answers `unknown` (which renders no
+ * banner) and keeps running; its result is cached for the next poll.
+ *
+ * The deadline bounds the Windows path, where the request collector is asynchronous. On
+ * other platforms the request collector keeps its existing synchronous read (a /proc walk on
+ * Linux, `ps` on macOS, typically tens of milliseconds), which completes before the deadline
+ * timer can fire; making those reads asynchronous is outside this change.
+ */
+export async function collectCodexAppServerCatalogStateWithin(
+  deadlineMs: number,
+  io: CodexAppServerProcessIo = {},
+): Promise<CodexAppServerCatalogStatus> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const deadline = new Promise<CodexAppServerCatalogStatus>(resolve => {
+    timer = setTimeout(() => resolve({ state: "unknown", processes: [], catalogMtimeMs: null }), deadlineMs);
+  });
+  try {
+    return await Promise.race([collectCodexAppServerCatalogStateForRequest(io), deadline]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Deadline for dashboard catalog-state reads; a cached reading answers well within it. */
+export const DASHBOARD_CATALOG_STATE_DEADLINE_MS = 250;
+
 /**
  * Drop memoized catalog state after a relevant catalog/cache write and before
  * the post-write state read. Advancing the generation prevents an older

package/src/codex/app-server-restart-service.ts

@@ -20,6 +20,8 @@
  */
 import {
   collectCodexAppServerCatalogState,
+  collectCodexAppServerCatalogStateWithin,
+  DASHBOARD_CATALOG_STATE_DEADLINE_MS,
   listCodexAppServerProcesses,
   readProcessStartMsBatch,
   resetCodexAppServerCatalogStateCache,
@@ -59,6 +61,8 @@ export interface CodexRestartServiceIo {
    */
   listenPort?: () => number | undefined;
   collectState?: typeof collectCodexAppServerCatalogState;
+  /** Deadline for the default dashboard state read (ms). */
+  stateDeadlineMs?: number;
   listProcesses?: typeof listCodexAppServerProcesses;
   restart?: typeof restartCodexAppServers;
   resetStateCache?: () => void;
@@ -88,10 +92,23 @@ class CodexAppServerIdentityChanged extends Error {
  */
 let inFlight: Promise<CodexRestartResponse> | null = null;
 
-export function readCodexAppServerState(
+/**
+ * Read-only state for the dashboard route. The default classifier is the bounded
+ * request-path read: on Windows the synchronous one runs PowerShell CIM enumeration
+ * inline, which measured 4-7s per call and stalled every listener, proxy traffic
+ * included, each time the Models page opened. A probe slower than the deadline answers
+ * `unknown` and keeps refreshing the cache. The restart path below keeps the
+ * synchronous reading because it acts on it.
+ */
+export async function readCodexAppServerState(
   io: CodexRestartServiceIo = {},
-): CodexAppServerStateResponse {
-  const status = (io.collectState ?? collectCodexAppServerCatalogState)(io.processIo ?? {});
+): Promise<CodexAppServerStateResponse> {
+  const status = io.collectState
+    ? io.collectState(io.processIo ?? {})
+    : await collectCodexAppServerCatalogStateWithin(
+      io.stateDeadlineMs ?? DASHBOARD_CATALOG_STATE_DEADLINE_MS,
+      io.processIo ?? {},
+    );
   return { state: status.state, runningCount: status.processes.length };
 }
 

package/src/codex/catalog/access-programs.ts

@@ -0,0 +1,50 @@
+import { isMainCodexAccountTarget } from "../account-namespaces";
+import { COMBO_NAMESPACE } from "../../combos";
+import { MAIN_CODEX_ACCOUNT_ID } from "../main-account";
+import type { CodexModelEntitlementSnapshot } from "../model-entitlements";
+import { trustedAccountBoundNativeCatalogSlug } from "./account-models";
+import { isNativeAliasCatalogEntry, SUPPORTED_NATIVE_OPENAI_SLUGS } from "./metadata";
+import type { RawEntry } from "./parsing";
+
+/** Project authenticated account metadata onto native rows only. */
+export function applyNativeAccessPrograms(
+  entries: RawEntry[],
+  snapshot: CodexModelEntitlementSnapshot,
+  accountTargets: ReadonlyMap<string, string>,
+): void {
+  for (const entry of entries) {
+    // A combo may deliberately claim a bare native slug. It is still a routed combo row,
+    // so the matching native Codex roster must not project its access programs onto it.
+    if (isNativeAliasCatalogEntry(entry)) continue;
+    if (entry.owned_by === COMBO_NAMESPACE) {
+      delete entry.available_access_programs;
+      continue;
+    }
+    const accountBoundSlug = trustedAccountBoundNativeCatalogSlug(entry);
+    const bareSlug = typeof entry.slug === "string" && !entry.slug.includes("/")
+      && SUPPORTED_NATIVE_OPENAI_SLUGS.has(entry.slug) ? entry.slug : undefined;
+    const slug = accountBoundSlug ?? bareSlug;
+    if (!slug) continue;
+    const selector = accountBoundSlug && typeof entry.slug === "string"
+      ? entry.slug.slice(0, entry.slug.indexOf("/")) : undefined;
+    const target = selector === undefined ? MAIN_CODEX_ACCOUNT_ID : accountTargets.get(selector);
+    const accountId = target && isMainCodexAccountTarget(target) ? MAIN_CODEX_ACCOUNT_ID : target;
+    if (!accountId) {
+      delete entry.available_access_programs;
+      continue;
+    }
+    // An old on-disk catalog can contain metadata from a previous credential. Until this
+    // account has a confirmed roster, that value is no longer evidence of a grant.
+    if (!snapshot.confirmedAccountIds.has(accountId)
+      || !snapshot.modelsByAccount.get(accountId)?.has(slug)) {
+      delete entry.available_access_programs;
+      continue;
+    }
+    const accountPrograms = snapshot.accessProgramsByAccount?.get(accountId);
+    if (accountPrograms?.has(slug)) {
+      entry.available_access_programs = accountPrograms.get(slug) ?? null;
+    } else {
+      delete entry.available_access_programs;
+    }
+  }
+}

package/src/codex/catalog/build-entries.ts

@@ -865,9 +865,22 @@ export function mergeCatalogEntriesFromObservedState({
     const normalized = reserveProjection ? m : normalizeServiceTiers(m);
     if (!reserveProjection && !isNativeAliasCatalogEntry(normalized)) applyNativeOpenAiContextOverride(normalized, openaiContextCap);
     const exactCombo = isExactComboCatalogEntry(m, exactComboSlugs);
+    // The builder copied this metadata from the pinned first-party row only for an exact
+    // ChatGPT/Codex forward custom alias. Freshness plus source equality prevents an old or
+    // unrelated routed row from claiming the native account's access programs at this second
+    // normalization boundary.
+    const nativeSourceSlug = typeof m.slug === "string" && m.slug.startsWith("openai/")
+      ? m.slug.slice("openai/".length) : undefined;
+    const nativeSource = nativeSourceSlug ? upstreamNativeEntry(nativeSourceSlug) : undefined;
+    const preserveNativeAccessPrograms = freshCustomEntries.has(m)
+      && m.owned_by !== COMBO_NAMESPACE
+      && nativeSource != null
+      && Object.hasOwn(nativeSource, "available_access_programs")
+      && JSON.stringify(m.available_access_programs) === JSON.stringify(nativeSource.available_access_programs);
     const e = reserveProjection ? normalized : ensureStrictCatalogFields(normalized, {
       preserveExactInputModalities: exactCombo,
       isRouted: finalRoutedEntrySet.has(m),
+      preserveNativeAccessPrograms,
     });
     // Mock-max universality (260709): preserved routed entries from disk may predate
     // the max rung — ensure it here so subagent max spawns validate on every

package/src/codex/catalog/derive-entry.ts

@@ -195,6 +195,7 @@ export function deriveEntry(
     return ensureStrictCatalogFields(normalizeServiceTiers(e), {
       preserveExactInputModalities: preserveExact,
       isRouted,
+      preserveNativeAccessPrograms: codexForwardNativeCapabilityAlias !== null,
     });
   }
   // Fallback when no template is available (best-effort; strict parser may need more).

package/src/codex/catalog/model-hints.ts

@@ -426,6 +426,17 @@ export function suppressedSyntheticMaxCatalogSlugs(
 export const QUIET_AUTHORITATIVE_CATALOG_PROVIDERS = new Set(["kimi", "xai"]);
 
 export const CALLABLE_CONFIGURED_COMPATIBILITY_MODELS: Readonly<Record<string, ReadonlySet<string>>> = {
+  // CodeBuddy's vendor defaults are real callable selectors — both the bundled manifests
+  // (`product.json` / `product.internal.json`) and `--model` accept them — but the key-scoped
+  // configuration roster omits them. Without this entry, a successful live roster
+  // would drop the configured default ("default" for CN, "default-model" for Global) from
+  // the catalog even though the client can still call it (maintainer review, #5147).
+  codebuddy: new Set([
+    "default-model",
+  ]),
+  "codebuddy-cn": new Set([
+    "default",
+  ]),
   kimi: new Set([
     "k3[1m]",
     "kimi-k2.7-code",

package/src/codex/catalog/parsing.ts

@@ -582,9 +582,10 @@ export function applyNativeOpenAiContextOverride(entry: RawEntry, limits?: Nativ
   }
 }
 
+/** Normalize a row for Codex's catalog parser, stripping native eligibility from routed rows unless explicitly preserved. */
 export function ensureStrictCatalogFields(
   entry: RawEntry,
-  options: { preserveExactInputModalities?: boolean; isRouted?: boolean } = {},
+  options: { preserveExactInputModalities?: boolean; isRouted?: boolean; preserveNativeAccessPrograms?: boolean } = {},
 ): RawEntry {
   if (entry.shell_type === "default" || entry.shell_type === "local" || entry.shell_type === "shell_command") {
     entry.shell_type = "unified_exec";
@@ -634,7 +635,7 @@ export function ensureStrictCatalogFields(
   if (typeof entry.effective_context_window_percent !== "number") entry.effective_context_window_percent = 95;
   if (typeof entry.comp_hash !== "string") entry.comp_hash = "opencodex";
   // Routed rows must not carry NATIVE eligibility metadata. `deriveEntry` deep-clones a
-  // native template and deletes a fixed denylist, so these five survive onto rows backed
+  // native template and deletes a fixed denylist, so these eligibility fields survive onto rows backed
   // by unrelated provider credentials — advertising ChatGPT plan eligibility for a model
   // that never touches a ChatGPT account (#2813).
   //
@@ -644,6 +645,9 @@ export function ensureStrictCatalogFields(
   // leave already-contaminated rows contaminated forever.
   if (options.isRouted === true) {
     entry.supported_in_api = true;
+    // Exact Codex-forward aliases still use a ChatGPT credential and may retain their native
+    // source metadata. Other routed rows cannot claim that account's access programs.
+    if (!options.preserveNativeAccessPrograms) delete entry.available_access_programs;
     delete entry.available_in_plans;
     delete entry.minimal_client_version;
     delete entry.availability_nux;

package/src/codex/catalog/provider-models.ts

@@ -6,6 +6,8 @@ import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync } from
 import { delimiter, dirname, join, resolve } from "node:path";
 import { atomicWriteFile, expandUserPath, getConfigDir, websocketsEnabled } from "../../config";
 import { resolveProviderApiKey } from "../../providers/key-store";
+import { getAccountSet } from "../../oauth/store";
+import { readKiroAccountModels, kiroObservedContextWindow } from "../../providers/kiro-model-catalog";
 import { CODEX_CONFIG_PATH, CODEX_MODELS_CACHE_PATH, DEFAULT_CATALOG_PATH, readRootTomlString, resolveCodexConfigPath } from "../paths";
 import {
   clearModelCache,
@@ -55,6 +57,9 @@ import { fetchCursorUsableModels } from "../../adapters/cursor/live-models";
 import { cursorLiveRosterScope, recordLiveCursorClaudeModels, recordLiveCursorMaxModeModels } from "../../adapters/cursor/catalog";
 import { fetchQoderModels } from "../../adapters/qoder/live-models";
 import { resolveQoderProfile } from "../../adapters/qoder/profiles";
+import { CODEBUDDY_PROFILES, type CodeBuddyProfile } from "../../adapters/codebuddy/profiles";
+import { fetchCodeBuddyModels } from "../../adapters/codebuddy/live-models";
+import { resolveProfileByBaseUrl } from "../../adapters/coding-agent/profile";
 import { fetchDevinUsableModels } from "../../adapters/devin/live-models";
 import { resolveDevinApiBaseUrl } from "../../oauth/devin/api-base";
 import { isCanonicalOpenAiForwardProvider, OPENAI_API_PROVIDER_ID, OPENAI_CODEX_PROVIDER_ID } from "../../providers/openai-tiers";
@@ -107,6 +112,11 @@ import { QUIET_AUTHORITATIVE_CATALOG_PROVIDERS, applyConfigHintsToCachedModels,
 import { mergeConfiguredModelsIntoLiveCatalog, shouldExposeProviderModel, warnDroppedConfiguredIdsOnce } from "./model-visibility";
 import { captureModelsRequest, captureProviderGather, materializeCapturedHeaders } from "./gather-capture";
 
+
+/** Observed Kiro ids advertised in the public catalog: plain ids that need no router decoding. */
+const KIRO_PUBLISHABLE_MODEL_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+/** Upper bound on observed Kiro ids added to the catalog across the whole roster. */
+const KIRO_OBSERVED_CATALOG_MAX = 64;
 export interface ProviderModelsResult {
   readonly models: CatalogModel[];
   readonly outcome: CatalogGatherProviderModelOutcome;
@@ -214,6 +224,30 @@ export async function fetchProviderModelsWithAuth(
   // discovery failure left by an older live configuration even when the account is logged out.
   if (prov.liveModels === false) {
     clearProviderDiscoveryStatus(name);
+    if (name === "kiro") {
+      const ids = [...configuredIds];
+      // Observed ids are advertised only when they round-trip through catalog encoding (no "/"
+      // or other separators the router would have to decode), and the roster adds at most
+      // KIRO_OBSERVED_CATALOG_MAX of them. Every observed id still informs routing preference.
+      let observedAdded = 0;
+      for (const account of getAccountSet("kiro")?.accounts ?? []) {
+        if (account.needsReauth === true) continue;
+        for (const row of readKiroAccountModels(account) ?? []) {
+          if (observedAdded >= KIRO_OBSERVED_CATALOG_MAX) break;
+          if (!KIRO_PUBLISHABLE_MODEL_ID.test(row.modelId) || ids.includes(row.modelId)) continue;
+          ids.push(row.modelId);
+          observedAdded += 1;
+        }
+      }
+      return observed(ids.map(id => {
+        const hints = catalogHintsFromProviderConfig(name, prov, id, contextCap,
+          metadataModelIdCaseFold, captured.effectiveAlias);
+        const observedWindow = kiroObservedContextWindow(id);
+        return { id, provider: name, ...hints,
+          ...(observedWindow !== undefined
+            ? { contextWindow: applyProviderContextCap(observedWindow, contextCap) } : {}) };
+      }), "authoritative");
+    }
     return observed(configured, "authoritative");
   }
   const auth: ModelsAuthResolution = captured.observedAuth ?? (resolveAuth.kind === "refreshing"
@@ -245,6 +279,53 @@ export async function fetchProviderModelsWithAuth(
       ? [...models, vertexDefaultSeed]
       : models
   );
+  if (prov.adapter === "codebuddy") {
+    if (!apiKey) return observed(configured, "degraded");
+    const resolvedProfile = resolveProfileByBaseUrl(CODEBUDDY_PROFILES, prov.baseUrl);
+    if (!resolvedProfile) return observed(configured, "degraded");
+    const profile = resolvedProfile as CodeBuddyProfile;
+    // Cache reads/writes are provider/key-fingerprint-scoped: an irreversible fingerprint of
+    // the configured key means a key switch never reuses the roster cached for the previous
+    // key. The roster comes from the product configuration endpoint authenticated with that
+    // same key, so the fingerprint scope and the roster's authority are the same identity: the
+    // roster is the key's own account answer, never the CLI login's.
+    const authorityIdentity = createHash("sha256").update(apiKey).digest("hex");
+    const fresh = getFreshCached(name, ttlMs, Date.now(), authorityIdentity);
+    if (fresh) {
+      return observed(withConfiguredRetention(
+        applyConfigHintsToCachedModels(name, prov, fresh, contextCap, metadataModelIdCaseFold, captured.effectiveAlias),
+      ), "authoritative");
+    }
+    const scopedStale = getStaleCached(name, authorityIdentity);
+    if (isModelsFetchCoolingDown(name, undefined, undefined, authorityIdentity) && scopedStale) {
+      return observed(withConfiguredRetention(
+        applyConfigHintsToCachedModels(name, prov, scopedStale, contextCap, metadataModelIdCaseFold, captured.effectiveAlias),
+      ), "degraded");
+    }
+    const live = await fetchCodeBuddyModels(profile, apiKey);
+    if (live.ok) {
+      const discovered = live.models.map(id => ({
+        id,
+        provider: name,
+        ...catalogHintsFromProviderConfig(name, prov, id, contextCap, metadataModelIdCaseFold, captured.effectiveAlias),
+      }));
+      const forCache = withConfiguredRetention(discovered, { retainComboTargets: false });
+      if (!setCached(name, forCache, Date.now(), cacheGeneration, authorityIdentity)) {
+        return observed(withConfiguredRetention(configured), "degraded");
+      }
+      markProviderDiscoveryOk(name, live.models.length);
+      return observed(withConfiguredRetention(forCache, { warnDrops: true }), "authoritative");
+    }
+    if (isCurrentCacheGeneration()) {
+      markModelsFetchFailure(name, undefined, authorityIdentity);
+      markProviderDiscoveryFailed(name, { reason: "provider" });
+      console.warn(`[opencodex] CodeBuddy model discovery failed [${live.error}]${live.status === undefined ? "" : ` status=${live.status}`}; using stale/static catalog degradation.`);
+    }
+    const stale = getStaleCached(name, authorityIdentity);
+    return observed(withConfiguredRetention(
+      stale ? applyConfigHintsToCachedModels(name, prov, stale, contextCap, metadataModelIdCaseFold, captured.effectiveAlias) : configured,
+    ), "degraded");
+  }
   if (prov.adapter === "qoder") {
     if (!apiKey) return observed(configured, "degraded");
     const profile = resolveQoderProfile(prov.baseUrl);

package/src/codex/catalog/retained-sync.ts

@@ -12,6 +12,7 @@ import { providerCodexAccountMode } from "../../providers/registry";
 import { COMBO_NAMESPACE } from "../../combos";
 import { codexAccountNamespaceEntries, isMainCodexAccountTarget } from "../account-namespaces";
 import { MAIN_CODEX_ACCOUNT_ID } from "../main-account";
+import { applyNativeAccessPrograms } from "./access-programs";
 import {
   availableAccountGatedNativeModels,
   codexModelEntitlementStateForAccount,
@@ -266,6 +267,7 @@ function catalogModelsForMergeWithNativeRecovery(
   ]);
 }
 
+/** Merge retained rows, project confirmed account metadata, and publish only changed catalog bytes. */
 function writeRetainedCatalogSync({
   config,
   goModels,
@@ -526,6 +528,7 @@ function writeRetainedCatalogSync({
       warningPolicy: "emit",
     },
   });
+  applyNativeAccessPrograms(catalog.models, modelEntitlements, accountTargets);
   clampCatalogModelsToCodexSupport(catalog.models);
   finalizeAutoReviewModelOverride(catalog.models, catalogModelsForMerge, config);
   // Last mutation before serialization; see `enforceCatalogSlugUniqueness` for why the ordering

package/src/codex/codex-write-lock.ts

@@ -144,9 +144,9 @@ export interface CodexWriteCommitContext {
  *
  * `hub-gated` is not the user's switch: a hub declines to rewrite its own local clients, and
  * reporting that as "integration is OFF" sent operators hunting for a toggle they never set
- * (#4236).
+ * (#4236). `sibling` is a second instance beside a live proxy that owns the routing.
  */
-export type CodexWriteLockSkipReason = "desired_disabled" | "desired_enabled" | "hub-gated";
+export type CodexWriteLockSkipReason = "desired_disabled" | "desired_enabled" | "hub-gated" | "sibling";
 
 /** A synchronous under-lock policy re-read proved the requested apply stale. */
 export class CodexWriteLockSkipped extends Error {

package/src/codex/convergence.ts

@@ -74,6 +74,7 @@ import { suppressedSyntheticMaxCatalogSlugs } from "./catalog/model-hints";
 import { codexRuntimeStatePath, peekCodexRuntimeProcessCache } from "./runtime";
 import { codexAccountNamespaceEntries, isMainCodexAccountTarget } from "./account-namespaces";
 import { MAIN_CODEX_ACCOUNT_ID } from "./main-account";
+import { applyNativeAccessPrograms } from "./catalog/access-programs";
 import {
   availableAccountGatedNativeModels,
   codexModelEntitlementStateForAccount,
@@ -384,6 +385,7 @@ function prepareCatalog(
       warningPolicy: "suppress",
     },
   });
+  applyNativeAccessPrograms(mergedModels, modelEntitlements, accountTargets);
   clampCatalogModelsToObservedCodexSupport(
     mergedModels,
     source.runtimeSupport.kind === "available"

package/src/codex/desired-state.ts

@@ -23,6 +23,7 @@
 import { deleteConfigTopLevelKey, loadConfig, mutatePersistedConfig } from "../config";
 import type { OcxClientIntegrationsConfig, OcxConfig } from "../types";
 import { runStartupReadinessSync, type ReadinessGate, type SyncOutcomeLike } from "../server/readiness";
+import { siblingOfLivePort, siblingSkipMessage } from "./sibling-start";
 
 /** Clients whose durable intent this module owns. */
 export type DurableIntentClientId = keyof OcxClientIntegrationsConfig;
@@ -77,6 +78,8 @@ type LocalClientSyncConfig = Pick<
 >;
 
 export function localClientSyncAllowed(config: LocalClientSyncConfig): boolean {
+  // A sibling instance never writes the live owner's client routing (`sibling-start.ts`).
+  if (siblingOfLivePort() !== null) return false;
   return config.runtimeRole !== "hub"
     || config.unauthenticatedLoopbackListener?.enabled === true;
 }
@@ -93,8 +96,11 @@ export const HUB_GATED_SKIP_MESSAGE =
   "This machine is a hub; it does not rewrite its own Codex/Grok/Claude configs unless "
   + "unauthenticatedLoopbackListener is enabled.";
 
-/** Why a local-client write was skipped. The gate outranks the toggle: it is the surprising one. */
-export type LocalClientSkipReason = "desired_disabled" | "hub-gated";
+/**
+ * Why a local-client write was skipped. The gate outranks the toggle: it is the surprising one.
+ * `sibling` outranks both: this process is a second instance beside a live owner.
+ */
+export type LocalClientSkipReason = "desired_disabled" | "hub-gated" | "sibling";
 
 /**
  * "hub-gated" is claimed only when the toggle is ON and the gate is what stopped the write.
@@ -106,6 +112,7 @@ export function localClientSkipReason(
   config: LocalClientSyncConfig,
   client: DurableIntentClientId = "codex",
 ): LocalClientSkipReason {
+  if (siblingOfLivePort() !== null) return "sibling";
   return integrationEnabled(config, client) && !localClientSyncAllowed(config)
     ? "hub-gated"
     : "desired_disabled";
@@ -123,7 +130,9 @@ export function localClientSkipMessage(
   hubSuffix?: string,
   client: DurableIntentClientId = "codex",
 ): string {
-  if (localClientSkipReason(config, client) !== "hub-gated") return integrationOffMessage;
+  const reason = localClientSkipReason(config, client);
+  if (reason === "sibling") return siblingSkipMessage();
+  if (reason !== "hub-gated") return integrationOffMessage;
   return hubSuffix ? `${HUB_GATED_SKIP_MESSAGE} ${hubSuffix}` : HUB_GATED_SKIP_MESSAGE;
 }
 
@@ -134,7 +143,8 @@ export function shouldSyncCodexOnStart(config: LocalClientSyncConfig): boolean {
   // /readyz failed because it tried to run the full local client sync).
   // A hub can be a local client only through its explicitly enabled loopback
   // listener. The public hub bind remains outside this gate and still requires
-  // admission; an explicit client OFF continues to win.
+  // admission; an explicit client OFF continues to win. A sibling instance is closed by the
+  // same gate: the live owner keeps the routing it maintains.
   return localClientSyncAllowed(config) && codexIntegrationEnabled(config);
 }
 

package/src/codex/home.ts

@@ -132,17 +132,35 @@ export function findWslWindowsCodexHome(deps: CodexHomeDeps = {}): string | null
   return candidates.length === 1 ? candidates[0]! : null;
 }
 
+function canonicalExistingCodexHome(path: string, deps: CodexHomeDeps): string {
+  const stat = deps.statSync ?? statSync;
+  try {
+    if (!stat(path).isDirectory()) return path;
+    // Use the portable resolver here rather than realpathSync.native. The
+    // Windows Bun standalone runtime can reject a valid junction through the
+    // native resolver, while the effective home still needs to be physical
+    // before callers open auth.json or native-profile state.
+    return (deps.realpathSync ?? realpathSync)(path);
+  } catch {
+    // Preserve the existing lexical-path behavior for missing or unreadable
+    // homes; callers that require the directory still fail at their boundary.
+    return path;
+  }
+}
+
 export function defaultCodexHome(deps: CodexHomeDeps = {}): string {
   const home = (deps.homedir ?? homedir)();
   const defaultHome = join(home, ".codex");
+  const canonicalDefaultHome = canonicalExistingCodexHome(defaultHome, deps);
   // A local ~/.codex that Codex is already using is the user's Codex home even before
   // config.toml exists (a fresh install: login writes auth.json, first use writes
   // sessions/ and history.jsonl). A local directory with none of that state is not
   // evidence of a local Codex: before #5441 such a home let WSL discovery pick the
   // Windows home, and existing WSL users who run against that Windows home must not
-  // be moved to an empty local one on upgrade.
-  if (localCodexHomeIsDirectory(defaultHome, deps) && localCodexHomeInUse(defaultHome, deps)) return defaultHome;
-  return findWslWindowsCodexHome(deps) ?? defaultHome;
+  // be moved to an empty local one on upgrade. Return the canonical path so a
+  // Windows junction cannot leak into later credential and profile writes.
+  if (localCodexHomeIsDirectory(defaultHome, deps) && localCodexHomeInUse(defaultHome, deps)) return canonicalDefaultHome;
+  return findWslWindowsCodexHome(deps) ?? canonicalDefaultHome;
 }
 
 function localCodexHomeInUse(home: string, deps: CodexHomeDeps): boolean {

package/src/codex/inject/restore.ts

@@ -1,5 +1,6 @@
 import { loadConfig } from "../../config";
 import { shouldSyncCodexOnStart } from "../desired-state";
+import { siblingOfLivePort, siblingSkipMessage } from "../sibling-start";
 import { withCatalogWriteSerialization } from "../catalog-write-serialization";
 import { restoreCodexCatalogWithPermit } from "../catalog/sync";
 import { withCodexWriteLock, CodexWriteLockSkipped } from "../codex-write-lock";
@@ -253,6 +254,18 @@ function desiredEnabledRestoreSkip(): CodexNativeRestoreResult {
   return skippedRestoreEnvelope(true, message);
 }
 
+/**
+ * A sibling instance restores nothing: the journal, config and catalog are the live owner's.
+ *
+ * It has to be checked before anything else, not left to the desired-state re-reads below. Those
+ * skip a restore when `shouldSyncCodexOnStart` says ON, and the sibling mark makes that gate
+ * answer OFF, so without this the gate would read as "the user turned Codex off" and the restore
+ * would replay the owner's journal.
+ */
+function siblingRestoreSkip(): CodexNativeRestoreResult | null {
+  return siblingOfLivePort() === null ? null : skippedRestoreEnvelope(true, siblingSkipMessage());
+}
+
 /**
  * A schema-complete all-skipped envelope for outcomes decided before any
  * restore machinery runs. Every `restore --json` path must stay shape-stable
@@ -471,6 +484,8 @@ function restoreCodexCatalogArtifact(
 export async function restoreNativeCodexAsync(
   options: { revalidateDesiredState?: boolean; removeProviderTable?: boolean } = {},
 ): Promise<CodexNativeRestoreResult> {
+  const sibling = siblingRestoreSkip();
+  if (sibling) return sibling;
   try {
     return await restoreNativeCodexAsyncImpl(options);
   } catch (error) {
@@ -669,6 +684,8 @@ async function restoreNativeCodexAsyncImpl(
 export function restoreNativeCodex(
   options: { skipHistory?: boolean; revalidateDesiredState?: boolean; removeProviderTable?: boolean } = {},
 ): CodexNativeRestoreResult {
+  const sibling = siblingRestoreSkip();
+  if (sibling) return sibling;
   const activeProvider = currentExternalCodexModelProvider();
   if (activeProvider) {
     removeJournal();

package/src/codex/inject/routing-classify.ts

@@ -11,7 +11,7 @@ import { CODEX_CONFIG_PATH } from "../paths";
 export type CodexRoutingKind =
   "native" | "opencodex-local" | "custom-local" | "custom-remote" | "unknown";
 
-type RoutingEndpointKind = "local" | "remote" | "unknown";
+export type RoutingEndpointKind = "local" | "remote" | "unknown";
 
 function ipv4Octets(hostname: string): number[] | null {
   const dotted = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(hostname);
@@ -26,7 +26,8 @@ function ipv4Octets(hostname: string): number[] | null {
   return [high >>> 8, high & 0xff, low >>> 8, low & 0xff];
 }
 
-function classifyRoutingEndpoint(value: string): RoutingEndpointKind {
+/** The one loopback rule for routing URLs; the drift detector (`routing-drift.ts`) shares it. */
+export function classifyRoutingEndpoint(value: string): RoutingEndpointKind {
   try {
     const url = new URL(value);
     if (url.protocol !== "http:" && url.protocol !== "https:") return "unknown";

package/src/codex/inject-coordination.ts

@@ -10,6 +10,7 @@ import { existsSync, lstatSync, readFileSync } from "node:fs";
 import { atomicWriteFile } from "../config";
 import type { CodexWriteLockResult, CodexWriteLockSkipReason } from "./codex-write-lock";
 import { HUB_GATED_SKIP_MESSAGE } from "./desired-state";
+import { siblingSkipMessage } from "./sibling-start";
 import { inspectCodexCoordinatorPath } from "./coordinator-doctor";
 import { JOURNAL_PATH } from "./journal";
 import { updateIntegrationRecord } from "./integration-record";
@@ -452,10 +453,12 @@ export function codexInjectLockOutcome(
       success: true,
       status: "skipped",
       skippedReason: result.reason,
-      // Three distinct facts, three sentences. The hub gate in particular must not borrow the
+      // Four distinct facts, four sentences. The hub gate in particular must not borrow the
       // toggle's wording — that is the phantom "integration is OFF" report from #4236.
       message: result.reason === "hub-gated"
         ? `${HUB_GATED_SKIP_MESSAGE} No Codex config, catalog, cache, or history was changed.`
+        : result.reason === "sibling"
+        ? `${siblingSkipMessage()} No Codex config, catalog, cache, or history was changed.`
         : result.reason === "desired_disabled"
           ? "Codex integration is OFF; no Codex config, catalog, cache, or history was changed."
           : "Codex integration was re-enabled; native restore was skipped.",

package/src/codex/inject.ts

@@ -12,7 +12,9 @@ import {
   localClientSkipMessage,
   localClientSkipReason,
   shouldSyncCodexOnStart,
+  type LocalClientSkipReason,
 } from "./desired-state";
+import { siblingOfLivePort, siblingSkipMessage } from "./sibling-start";
 import { resolveCodexHistoryTransition } from "./history-transition";
 import {
   buildInjectWitness,
@@ -147,7 +149,7 @@ export interface CodexInjectResult {
   /** Busy write lock, emitted by `codexInjectLockOutcome` and undeclared here until #4809. */
   retryable?: boolean;
   /** `hub-gated` is the hub-role gate (#4236), distinct from the user's own OFF switch. */
-  skippedReason?: "desired_disabled" | "desired_enabled" | "hub-gated";
+  skippedReason?: LocalClientSkipReason | "desired_enabled";
   nativeSubagentDefaultsWarning?: string;
 }
 
@@ -184,6 +186,11 @@ export async function injectCodexConfig(
   config?: OcxConfig,
   options: InjectCodexOptions = {},
 ): Promise<CodexInjectResult> {
+  // First, before the external-provider branch below removes the SHARED journal: a sibling owns
+  // none of this home's routing, not even the courtesy cleanup.
+  if (siblingOfLivePort() !== null) {
+    return { success: true, status: "skipped", skippedReason: "sibling", message: siblingSkipMessage() };
+  }
   try { return await injectCodexConfigImpl(port, config, options); }
   catch (error) {
     if (error instanceof CodexHistoryPreflightRefusal) return { success: false, historyPreflightFailureReason: error.message, message: `Codex config injection refused: ${error.message}. Existing configuration and history were preserved.` };

package/src/codex/journal.ts

@@ -255,8 +255,12 @@ function readJournal(cleanInvalid = true): Journal | null {
   }
 }
 
-export function journalOwner(): JournalOwner | null {
-  const journal = readJournal();
+/**
+ * Who owns the journal. `readOnly` never deletes an unreadable journal: a background reader (the
+ * routing healer, `routing-healer.ts`) must not destroy recovery evidence it only looked at.
+ */
+export function journalOwner(options: { readOnly?: boolean } = {}): JournalOwner | null {
+  const journal = readJournal(options.readOnly !== true);
   if (!journal) return null;
   if (journal.owner?.kind === "client" && typeof journal.owner.apiKeyId === "string" && journal.owner.apiKeyId) {
     return { kind: "client", apiKeyId: journal.owner.apiKeyId };

package/src/codex/management-convergence.ts

@@ -2,6 +2,7 @@ import type { OcxConfig } from "../types";
 import { resolvePendingInitialModelSelection } from "../providers/initial-model-selection-runtime";
 import { captureCatalogAdmissionSnapshot } from "./catalog-admission";
 import { convergeCodexCatalog } from "./convergence";
+import { siblingOfLivePort } from "./sibling-start";
 import type {
   CatalogDisposition,
   CatalogFailureCause,
@@ -155,6 +156,14 @@ export function createManagementConvergeCodex(
       }
       // Registration choices are committed independently, before sealing catalog authority.
       await resolvePendingInitialModelSelection(retainedConfig as OcxConfig);
+      // The catalog and models cache live in the shared `CODEX_HOME`; a sibling instance leaves
+      // them to the live owner. This funnel serves every management caller and the auto-refresh tick.
+      if (siblingOfLivePort() !== null) {
+        return projectCatalogOnlyOutcome({
+          changed: false,
+          catalogRefresh: { status: "skipped", reason: "refused", retryable: false },
+        });
+      }
       const snapshot = captureCatalogAdmissionSnapshot(retainedConfig);
       const result = await convergeCodexCatalog(snapshot, request, {
         onCommitBegin: () => { commitBegan = true; },