@bitkyc08/opencodex 2.64.0 → 2.65.0-preview.20260925

package/src/codex/inject/config-toml.ts

@@ -8,6 +8,7 @@ import {
   REALTIME_WS_BASE_URL_KEY,
   isRootOpenaiBaseUrlLine,
   isRootRealtimeWsBaseUrlLine,
+  rootTomlString,
   tomlStringPattern,
 } from "../injected-marker";
 import {
@@ -303,6 +304,142 @@ export function setRootRealtimeWsBaseUrl(
   return { content, keptUserRealtimeWsBaseUrl: false };
 }
 
+/**
+ * Root key codex-rs reads for its web-search mode. The value opencodex writes is the only one that
+ * takes the native hosted tool away; the other modes keep it, so they are never written here.
+ */
+export const ROOT_WEB_SEARCH_KEY = "web_search";
+
+/** The one value opencodex writes for {@link ROOT_WEB_SEARCH_KEY}. */
+export const ROOT_WEB_SEARCH_DISABLED_LINE = 'web_search = "disabled"';
+
+/** The value {@link ROOT_WEB_SEARCH_DISABLED_LINE} carries, as the journal records it. */
+export const ROOT_WEB_SEARCH_DISABLED_VALUE = "disabled";
+
+export function isRootWebSearchLine(line: string): boolean {
+  // The quoted spellings are the same key to TOML, and `tomlStringPattern` -- which the value
+  // evidence below goes through -- already reads them. A predicate that matched only the bare
+  // spelling would leave `"web_search" = "live"` in place while inserting our own line, and two
+  // root keys of the same name stop Codex from loading the file at all.
+  return /^\s*(?:"web_search"|'web_search'|web_search)\s*=/.test(line);
+}
+
+/** What an earlier injection recorded about this key, read back from the journal. */
+export interface RootWebSearchJournal {
+  /** The value that injection wrote, or null when it wrote none. */
+  injectedValue?: string | null;
+  /** The user-owned line that injection had to remove, or null when there was none. */
+  replacedUserLine?: string | null;
+}
+
+/** What one pass of {@link ensureRootWebSearchDisabled} did, for the journal to record. */
+export interface RootWebSearchOutcome {
+  content: string;
+  /** The user-owned root line this pass removed, or null when there was none. */
+  replacedUserLine: string | null;
+  /** The value this pass wrote, or null when it wrote none. */
+  wroteValue: string | null;
+}
+
+/** Insert root-level lines ahead of the first table; TOML root keys may not follow one. */
+function insertRootLines(lines: string[], text: string): string {
+  const firstTable = lines.findIndex((line) => /^\s*\[/.test(line));
+  if (firstTable === -1) return `${lines.join("\n").replace(/\n+$/, "")}\n${text}\n`;
+  let at = firstTable;
+  while (at > 0 && lines[at - 1].trim() === "") at -= 1;
+  lines.splice(at, 0, ...text.split("\n"));
+  return lines.join("\n");
+}
+
+/**
+ * Ensure the root `web_search` key follows the web-search sidecar's master switch.
+ *
+ * Codex reads this key (modes `disabled`/`cached`/`indexed`/`live`) to decide whether its native
+ * Responses `web_search` tool is offered at all; `disabled` is the only mode that removes the tool
+ * from the model's tool list. An operator who runs an MCP search server instead needs exactly that,
+ * because a native tool the client still advertises wins the model's attention away from the MCP
+ * one. So the switch is not advisory: while `webSearchSidecar.enabled` is false we own the value.
+ *
+ * Ownership, both directions:
+ * - `disabled` removes EVERY root `web_search` line (ours or the user's) and writes the marker-owned
+ *   pair. Two root keys of the same name are invalid TOML, so keeping a user line alongside ours
+ *   would stop Codex from loading the file at all — and the operator has just asked for this exact
+ *   value. A value the user owned is reported back as `replacedUserLine` so the journal can carry
+ *   it, and `ocx restore` additionally replays the snapshot, like every other line this injection
+ *   rewrites.
+ * - enabled (or unset) removes only the marker-owned pair, so re-enabling the sidecar cannot leave
+ *   the native tool switched off — which would silently leave the sidecar with nothing to intercept.
+ *   Two further sources of ownership come from the journal: the exact value a recorded injection
+ *   wrote, so a line whose marker comment a Codex app reserialize dropped is still ours (#1798), and
+ *   the user line that injection removed, which goes back now that nothing owns the key.
+ */
+export function ensureRootWebSearchDisabled(
+  content: string,
+  disabled: boolean,
+  journal: RootWebSearchJournal = {},
+): RootWebSearchOutcome {
+  const lines = stripInjectedRootWebSearch(content, journal.injectedValue).split("\n");
+  const firstTable = lines.findIndex((line) => /^\s*\[/.test(line));
+  const rootEnd = firstTable === -1 ? lines.length : firstTable;
+  if (!disabled) {
+    const restore = journal.replacedUserLine?.trim();
+    const owned = lines.slice(0, rootEnd).some(isRootWebSearchLine);
+    return {
+      content: restore && !owned ? insertRootLines(lines, restore) : lines.join("\n"),
+      replacedUserLine: null,
+      wroteValue: null,
+    };
+  }
+  // Whatever root line is left here is not marker-owned and not the value we recorded writing, so
+  // it is the operator's own mode: keep its exact text for the pass that switches the sidecar back
+  // on. Only one can be valid TOML, and the first is the one Codex reads. A pass that finds no such
+  // line keeps the one an earlier off pass recorded — the ordinary way to reach that state is a
+  // second injection while the switch is still off (a model change), and the operator's mode must
+  // not evaporate because the line it came from is already gone.
+  const replacedUserLine = lines
+    .slice(0, rootEnd)
+    .find((line) => isRootWebSearchLine(line))
+    ?.replace(/\r$/, "") ?? journal.replacedUserLine?.trim() ?? null;
+  return {
+    content: insertRootLines(
+      lines.filter((line, index) => index >= rootEnd || !isRootWebSearchLine(line)),
+      `${OCX_ROUTING_MARKER_LINE}\n${ROOT_WEB_SEARCH_DISABLED_LINE}`,
+    ),
+    replacedUserLine,
+    wroteValue: ROOT_WEB_SEARCH_DISABLED_VALUE,
+  };
+}
+
+/**
+ * Remove the marker-owned root `web_search` pair (marker line + the key line right after it).
+ * Same ownership rule as `stripInjectedOpenaiBaseUrl`: a user's own line has no marker above it and
+ * survives, so a hand-set mode is never reinterpreted as ours after an injection cycle. `injectedValue`
+ * adds the #1798 value evidence — the exact value a recorded injection wrote — so a line whose marker
+ * comment a Codex app reserialize dropped is still recognized as ours.
+ */
+export function stripInjectedRootWebSearch(content: string, injectedValue?: string | null): string {
+  const lines = content.split("\n");
+  const firstTable = lines.findIndex((line) => /^\s*\[/.test(line));
+  const rootEnd = firstTable === -1 ? lines.length : firstTable;
+  const drop = new Set<number>();
+  for (let i = 0; i + 1 < rootEnd; i += 1) {
+    if (lines[i].includes(OCX_SECTION_MARKER) && isRootWebSearchLine(lines[i + 1])) {
+      drop.add(i);
+      drop.add(i + 1);
+    }
+  }
+  if (injectedValue) {
+    for (let i = 0; i < rootEnd; i += 1) {
+      if (!isRootWebSearchLine(lines[i])) continue;
+      if (rootTomlString(lines[i], ROOT_WEB_SEARCH_KEY) !== injectedValue) continue;
+      drop.add(i);
+      if (i > 0 && lines[i - 1].includes(OCX_SECTION_MARKER)) drop.add(i - 1);
+    }
+  }
+  if (drop.size === 0) return content;
+  return lines.filter((_, index) => !drop.has(index)).join("\n");
+}
+
 /**
  * Remove the marker-owned root `openai_base_url` (marker line + the key line right after it).
  * A user's own root override (no marker) survives; an orphaned marker with no key line after

package/src/codex/inject/plan.ts

@@ -17,6 +17,8 @@ import {
 import {
   journaledInjectedOpenaiBaseUrl,
   journaledInjectedRealtimeWsBaseUrl,
+  journaledInjectedRootWebSearch,
+  journaledReplacedRootWebSearch,
 } from "../journal";
 import { stripJournaledOpenaiBaseUrl } from "../injected-marker";
 import { CODEX_CONFIG_PATH, resolveCodexStateDbPath } from "../paths";
@@ -30,6 +32,7 @@ import {
   chooseCatalogPathForInjection,
   dominantEol,
   ensureFastModeFeature,
+  ensureRootWebSearchDisabled,
   normalizeServiceTier,
   removeProfileSection,
   setRootModelCatalogPath,
@@ -74,6 +77,10 @@ export interface CodexInjectionPlanOk {
   keepRootOverrideAlongsideTable: boolean;
   keptUserBaseUrl: boolean;
   keptUserRealtimeWsBaseUrl: boolean;
+  /** The root `web_search` value this plan writes, or null when it writes none. */
+  injectedRootWebSearch: string | null;
+  /** The user-owned root `web_search` line this plan removed, for the journal to carry. */
+  replacedRootWebSearch: string | null;
   nativeSubagentDefaultsWarning: string | undefined;
   managedDefaultsMessage: string;
   /**
@@ -169,6 +176,20 @@ export function deriveCodexInjectionPlan(
   content = stripRootContextWindowOverrides(content);
   content = normalizeServiceTier(content);
   content = ensureFastModeFeature(content, config?.fastMode);
+  // Codex's own web-search switch follows the sidecar's master switch. While the sidecar is off,
+  // the client must not keep offering a native `web_search` tool that an MCP search server is
+  // meant to replace. The journal carries both halves of an earlier pass — the value we wrote,
+  // because the marker comment does not survive a Codex app reserialize, and the operator line we
+  // had to remove, because the sidecar coming back on is what returns it.
+  const webSearch = ensureRootWebSearchDisabled(
+    content,
+    config?.webSearchSidecar?.enabled === false,
+    {
+      injectedValue: journaledInjectedRootWebSearch({ readOnly: ctx.journalReadOnly }),
+      replacedUserLine: journaledReplacedRootWebSearch({ readOnly: ctx.journalReadOnly }),
+    },
+  );
+  content = webSearch.content;
 
   const catalogPath = chooseCatalogPathForInjection(
     content,
@@ -352,6 +373,8 @@ export function deriveCodexInjectionPlan(
     keepRootOverrideAlongsideTable,
     keptUserBaseUrl,
     keptUserRealtimeWsBaseUrl,
+    injectedRootWebSearch: webSearch.wroteValue,
+    replacedRootWebSearch: webSearch.replacedUserLine,
     nativeSubagentDefaultsWarning,
     managedDefaultsMessage,
     historyRelabelRefusal: observedHistoryRefusal,

package/src/codex/inject/remove.ts

@@ -10,12 +10,15 @@ import { HISTORY_RELABEL_STANDS_DOWN, preflightCodexHistoryInjection } from "../
 import {
   journaledInjectedOpenaiBaseUrl,
   journaledInjectedRealtimeWsBaseUrl,
+  journaledInjectedRootWebSearch,
+  journaledReplacedRootWebSearch,
 } from "../journal";
 import { CODEX_CONFIG_PATH, CODEX_PROFILE_PATH, readRootTomlString } from "../paths";
 import { transformManagedSubagentDefaults } from "../subagent-defaults";
 import {
   applyEol,
   dominantEol,
+  ensureRootWebSearchDisabled,
   removeProfileSection,
   stripInjectedOpenaiBaseUrl,
   stripOpencodexCatalogPath,
@@ -65,6 +68,8 @@ function stripOpencodexConfigResult(
   content: string,
   journaledBaseUrl: string | null = null,
   journaledRealtimeWsBaseUrl: string | null = null,
+  journaledRootWebSearch: string | null = null,
+  journaledReplacedWebSearch: string | null = null,
 ): StripOpencodexConfigResult {
   let out = content;
   const hadRootOcxProvider =
@@ -75,6 +80,13 @@ function stripOpencodexConfigResult(
   const hadInjectedBaseUrl = hasInjectedOpenaiBaseUrl(out)
     || (journaledBaseUrl !== null && rootTomlString(out, "openai_base_url") === journaledBaseUrl);
   out = stripInjectedOpenaiBaseUrl(out); // before removeOcxSection — it keys on the marker line too
+  // The enabled direction of the web-search transform is also the purge: it drops our pair, drops a
+  // marker-less `disabled` the journal proves we wrote, and puts back the operator line we had to
+  // remove for as long as the switch was off. Nothing of ours is written here.
+  out = ensureRootWebSearchDisabled(out, false, {
+    injectedValue: journaledRootWebSearch,
+    replacedUserLine: journaledReplacedWebSearch,
+  }).content;
   out = stripJournaledOpenaiBaseUrl(out, journaledBaseUrl, journaledRealtimeWsBaseUrl);
   if (hasOcxProviderTable(out)) {
     out = removeOcxSection(out);
@@ -174,11 +186,19 @@ export function removeCodexConfig(
   // ownership verdict, which must agree with what was actually removed.
   const journaledBaseUrl = journaledInjectedOpenaiBaseUrl();
   const journaledRealtimeWsBaseUrl = journaledInjectedRealtimeWsBaseUrl();
+  const journaledRootWebSearch = journaledInjectedRootWebSearch();
+  const journaledReplaced = journaledReplacedRootWebSearch();
   const had = hasOpencodexRouting(content)
     || (journaledBaseUrl !== null && rootTomlString(content, "openai_base_url") === journaledBaseUrl)
     || (journaledRealtimeWsBaseUrl !== null
       && rootTomlString(content, REALTIME_WS_BASE_URL_KEY) === journaledRealtimeWsBaseUrl);
-  const stripped = stripOpencodexConfigResult(content, journaledBaseUrl, journaledRealtimeWsBaseUrl);
+  const stripped = stripOpencodexConfigResult(
+    content,
+    journaledBaseUrl,
+    journaledRealtimeWsBaseUrl,
+    journaledRootWebSearch,
+    journaledReplaced,
+  );
   // Captured from the pre-strip bytes: the strip is what removes the table, so reading it
   // afterwards would find nothing.
   const retainedBlock = historyDisposition === "stand-down-retain"

package/src/codex/inject.ts

@@ -1,4 +1,5 @@
-import { existsSync, readFileSync } from "node:fs";
+import { closeSync, existsSync, openSync, readFileSync, statSync } from "node:fs";
+import { dirname } from "node:path";
 import {
   atomicWriteFile,
   loadConfig,
@@ -211,14 +212,15 @@ async function injectCodexConfigImpl(
   } catch (error) {
     return { success: false, message: error instanceof Error ? error.message : "Invalid Codex routing target" };
   }
-  if (!existsSync(CODEX_CONFIG_PATH)) {
-    return {
-      success: false,
-      message: `Codex config not found at ${CODEX_CONFIG_PATH}. Is Codex installed?`,
-    };
-  }
+  const missingConfig = !existsSync(CODEX_CONFIG_PATH)
+    ? missingCodexConfigAdmission()
+    : null;
+  if (missingConfig && !missingConfig.ok) return { success: false, message: missingConfig.message };
 
-  const rawContent = readFileSync(CODEX_CONFIG_PATH, "utf-8");
+  // An absent config.toml in an existing home is planned as an empty file. The file itself
+  // is created only inside the write boundary, after the pre-images are captured, so any
+  // later refusal or failure rolls it back to absent (issue 5422).
+  const rawContent = missingConfig ? "" : readFileSync(CODEX_CONFIG_PATH, "utf-8");
   const activeProvider = externalCodexModelProvider(rawContent);
   if (activeProvider) {
     // A launcher may have journaled before the provider manager took ownership. Never let shutdown
@@ -402,6 +404,7 @@ async function injectCodexConfigImpl(
    * flip included — before the result is reported.
    */
   const reconcileAndDerivePlan = (): { plan: CodexInjectionPlanOk; nativeInput: string } => {
+    if (missingConfig) createEmptyCodexConfigInBoundary();
     let nativeInput = rawContent;
     let plan = admittedPlan;
     if (v1Reconcile) {
@@ -465,6 +468,12 @@ async function injectCodexConfigImpl(
       injectedRealtimeWsBaseUrl: plan.providerTableMode || plan.keptUserBaseUrl || plan.keptUserRealtimeWsBaseUrl
         ? null
         : rootTomlString(plan.content, REALTIME_WS_BASE_URL_KEY),
+      // The web-search pair follows the sidecar's master switch, and it is the one root value we
+      // REPLACE rather than only add: the operator's own mode has to leave the file while the
+      // switch is off. Both halves are recorded here — the value we wrote (the marker comment is
+      // not durable) and the line we removed (so re-enabling the sidecar can return it).
+      injectedRootWebSearch: plan.injectedRootWebSearch,
+      replacedRootWebSearch: plan.replacedRootWebSearch,
       // This is the catalog artifact selected for this injection, even when config.toml
       // already points at that path and therefore needs no textual rewrite.
       injectedCatalogPath: plan.catalogPath,
@@ -860,3 +869,49 @@ export {
   setBeforeRestoreConfigForTests,
   skippedRestoreEnvelope,
 } from "./inject/restore";
+
+type MissingCodexConfig = { ok: true } | { ok: false; message: string };
+
+/**
+ * A fresh Codex install can have its home directory but no config.toml yet: Codex writes
+ * that file lazily, and a user who never signed in to OpenAI (authless Desktop with a
+ * third-party provider, issue 5422) may never get one. A missing optional file is not
+ * evidence that Codex is absent, so injection plans against an empty config.toml and
+ * creates it inside the write boundary. A missing home DIRECTORY is different: that is
+ * either an uninitialized install or the wrong home, and guessing would write provider
+ * state where Codex is not looking.
+ */
+function missingCodexConfigAdmission(): MissingCodexConfig {
+  const home = dirname(CODEX_CONFIG_PATH);
+  let homeIsDirectory = false;
+  try {
+    homeIsDirectory = statSync(home).isDirectory();
+  } catch {
+    homeIsDirectory = false;
+  }
+  if (homeIsDirectory) return { ok: true };
+  return {
+    ok: false,
+    message: `Codex home ${home} does not exist yet, so there is no config.toml to route. Start Codex once so it creates its home, then rerun 'ocx sync'. If Codex uses a different home, set CODEX_HOME to it.`,
+  };
+}
+
+/**
+ * Create the planned empty config.toml under the write boundary. It runs after the
+ * pre-images were captured (config absent), so compensation removes it again. The create is
+ * exclusive: a file that appeared since admission belongs to another writer, and this plan,
+ * derived from an absent file, must not replace it.
+ */
+function createEmptyCodexConfigInBoundary(): void {
+  try {
+    closeSync(openSync(CODEX_CONFIG_PATH, "wx", 0o600));
+  } catch (error) {
+    const appeared = (error as NodeJS.ErrnoException | null)?.code === "EEXIST";
+    throw new CodexInjectRefusal({
+      success: false,
+      message: appeared
+        ? `Codex config ${CODEX_CONFIG_PATH} appeared while injection was planned against its absence; nothing was changed. Rerun 'ocx sync'.`
+        : `Codex config not found at ${CODEX_CONFIG_PATH}, and creating it failed: ${error instanceof Error ? error.message : String(error)}`,
+    });
+  }
+}

package/src/codex/journal.ts

@@ -42,6 +42,26 @@ interface Journal {
    * that as ours. Null when the key was preserved or not injected.
    */
   injectedRealtimeWsBaseUrl?: string | null;
+  /**
+   * The root `web_search` value this injection wrote, when it wrote one.
+   *
+   * Same reasoning as {@link injectedOpenaiBaseUrl}, for the one other root key whose value is a
+   * mode Codex reads: the marker comment above `web_search = "disabled"` does not survive a Codex
+   * app reserialize, and without value evidence the next injection cannot tell our line from the
+   * operator's. The failure that buys is quiet: a re-enabled sidecar whose client still has the
+   * native tool switched off has nothing to intercept, which is the empty state the switch exists
+   * to avoid.
+   */
+  injectedRootWebSearch?: string | null;
+  /**
+   * The user-owned root `web_search` line this injection REMOVED while the sidecar was off.
+   *
+   * Two root keys of the same name are invalid TOML, so the operator's mode has to leave the file
+   * for as long as the switch is off. Recording the exact line is what puts it back when the
+   * sidecar is switched on again — including for a line the snapshot predates, which is the case
+   * `ocx restore` alone cannot cover.
+   */
+  replacedRootWebSearch?: string | null;
   /**
    * The catalog path this injection actually wrote to.
    *
@@ -156,6 +176,10 @@ export interface InjectedJournalOwnership {
   injectedOpenaiBaseUrl: string | null;
   injectedRealtimeWsBaseUrl: string | null;
   injectedCatalogPath: string | null;
+  /** Omitted by callers that inject no `web_search` line, which is the value it then records. */
+  injectedRootWebSearch?: string | null;
+  /** Omitted by callers that removed no user `web_search` line. */
+  replacedRootWebSearch?: string | null;
 }
 
 export function markJournalInjectedState(
@@ -177,6 +201,8 @@ export function markJournalInjectedState(
   // would mistake a preserved user override for injected routing.
   journal.injectedOpenaiBaseUrl = ownership.injectedOpenaiBaseUrl;
   journal.injectedRealtimeWsBaseUrl = ownership.injectedRealtimeWsBaseUrl;
+  journal.injectedRootWebSearch = ownership.injectedRootWebSearch ?? null;
+  journal.replacedRootWebSearch = ownership.replacedRootWebSearch ?? null;
   journal.injectedCatalogPath = ownership.injectedCatalogPath;
   atomicWriteFile(JOURNAL_PATH, JSON.stringify(journal));
 }
@@ -198,6 +224,16 @@ export function journaledInjectedRealtimeWsBaseUrl(options: { readOnly?: boolean
   return readJournal(options.readOnly !== true)?.injectedRealtimeWsBaseUrl ?? null;
 }
 
+/** The root `web_search` value the last injection wrote, or null when it wrote none. */
+export function journaledInjectedRootWebSearch(options: { readOnly?: boolean } = {}): string | null {
+  return readJournal(options.readOnly !== true)?.injectedRootWebSearch ?? null;
+}
+
+/** The user-owned root `web_search` line the last injection removed, or null when there was none. */
+export function journaledReplacedRootWebSearch(options: { readOnly?: boolean } = {}): string | null {
+  return readJournal(options.readOnly !== true)?.replacedRootWebSearch ?? null;
+}
+
 /** The catalog path the last injection wrote to, or null when none was recorded. */
 export function journaledInjectedCatalogPath(): string | null {
   return readJournal()?.injectedCatalogPath ?? null;

package/src/codex/main-account-hard-lock.ts

@@ -13,6 +13,19 @@ export interface MainAccountHardLockStatus {
 
 type PolicyConfig = Pick<OcxConfig, "codexMainAccountHardLock">;
 
+/**
+ * Whether the main-account hard lock applies to this config (#5694).
+ *
+ * Absent key or `true` means on; only the persisted `false` opt-out turns it off. The
+ * `undefined` branch is the trap this resolver cannot close on its own: no config object is
+ * "the caller supplied no policy", not "the operator opted out", so a call site holding an
+ * optional config must test for one before asking. Sites that hold a config always (a loaded
+ * config, a resolved policy) call this directly.
+ */
+export function isMainAccountHardLockEnabled(config: PolicyConfig | undefined): boolean {
+  return config?.codexMainAccountHardLock !== false;
+}
+
 function resetTimestamp(value: number | undefined): number | undefined {
   if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) return undefined;
   return value < 10_000_000_000 ? value * 1000 : value;
@@ -23,7 +36,7 @@ export function getMainAccountHardLockStatus(
   config: PolicyConfig,
   now = Date.now(),
 ): MainAccountHardLockStatus {
-  if (config.codexMainAccountHardLock !== true) return { enabled: false, state: "off" };
+  if (!isMainAccountHardLockEnabled(config)) return { enabled: false, state: "off" };
   const quota = getMainPolicyQuota();
   if (!quota) return { enabled: true, state: "unknown" };
   // Account window priority is deliberate: a 5h account uses that window, even if

package/src/codex/main-account-policy-wait.ts

@@ -0,0 +1,109 @@
+import {
+  isMainAccountPolicyBindingPending,
+  waitForNativeMainStartupGate,
+} from "./native-profile-startup";
+
+/**
+ * How long a request waits for an owned startup to finish binding the main-account policy
+ * before it is refused as draining.
+ *
+ * `codexMainAccountHardLock` is on by default (#5694), so the admission fence beside this
+ * constant is no longer an opt-in rarity: every request that arrives while a process-owned
+ * startup is still recovering, sweeping stages, and binding the pinned home lands on it. That
+ * window is milliseconds on a warm Linux host and seconds on Windows, which is why the fence
+ * waits for the gate instead of failing the request the moment it arrives.
+ *
+ * 15 s is deliberately just above one startup claim wait: both exclusive claims
+ * (`withNativeMainExclusiveClaim` in `convergeOwnedStartup`) allow 10 s before they give up, so a
+ * request that arrived during the last claim is not refused in the instant before the gate would
+ * have opened. Anything longer stops being a courtesy to the client and starts being a hung
+ * request, and a gate still blocked after this leaves a real answer -- retained recovery or a
+ * manual-recovery requirement -- where waiting cannot help, which is what the draining error says.
+ */
+export const MAIN_ACCOUNT_POLICY_BINDING_WAIT_MS = 15_000;
+
+/**
+ * Repoll interval for the one window where the settle promise is already resolved and the gate
+ * still reads pending: a manual-recovery fence publishes a resolved promise while an in-flight
+ * convergence is still marked pending, and re-awaiting that same resolved promise would spin the
+ * microtask queue -- which never lets the deadline timer fire.
+ */
+const MAIN_ACCOUNT_POLICY_BINDING_REPOLL_MS = 25;
+
+export interface MainAccountPolicyBindingWait {
+  /** Ends the wait with the signal's reason, as an aborted request must. */
+  signal?: AbortSignal;
+  /** Overrides {@link MAIN_ACCOUNT_POLICY_BINDING_WAIT_MS} for a bounded focused test. */
+  timeoutMs?: number;
+}
+
+/**
+ * Wait, bounded, for an owned startup's main-account policy binding to settle.
+ *
+ * Returns `true` once the binding is no longer pending, `false` when the deadline passed with it
+ * still in flight. Callers fail closed on `false`; the gate itself is re-read every iteration
+ * because a rearm replaces the settle promise rather than resolving the one already held.
+ */
+export async function waitForMainAccountPolicyBinding(
+  wait: MainAccountPolicyBindingWait = {},
+): Promise<boolean> {
+  const signal = wait.signal;
+  const timeoutMs = Math.max(0, wait.timeoutMs ?? MAIN_ACCOUNT_POLICY_BINDING_WAIT_MS);
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    if (!isMainAccountPolicyBindingPending()) return true;
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) return false;
+    const settledNow = await raceSettle(waitForNativeMainStartupGate(), remaining, signal);
+    // Settling does not always clear the flag: the gate may have been rearmed, or the resolved
+    // promise above may belong to a fence that never released the entry. Yield to the event loop
+    // before asking again so this stays a poll rather than a busy-wait.
+    if (settledNow && isMainAccountPolicyBindingPending()) {
+      await pause(Math.min(remaining, MAIN_ACCOUNT_POLICY_BINDING_REPOLL_MS), signal);
+    }
+  }
+}
+
+/** `true` when the settle promise resolved first, `false` on the deadline. */
+async function raceSettle(
+  settle: Promise<unknown>,
+  timeoutMs: number,
+  signal?: AbortSignal,
+): Promise<boolean> {
+  if (signal?.aborted) throw signal.reason;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let onAbort: (() => void) | undefined;
+  const deadline = new Promise<boolean>(resolve => {
+    timer = setTimeout(() => resolve(false), timeoutMs);
+    // A request waiting on a startup gate must never be the reason the process stays alive.
+    timer.unref?.();
+  });
+  const aborted = new Promise<never>((_resolve, reject) => {
+    if (!signal) return;
+    onAbort = () => reject(signal.reason);
+    signal.addEventListener("abort", onAbort);
+  });
+  try {
+    // A rejected settle is not an error here: the loop re-reads the gate and decides.
+    return await Promise.race([settle.then(() => true, () => true), deadline, aborted]);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+    if (signal && onAbort) signal.removeEventListener("abort", onAbort);
+  }
+}
+
+/** One short, abortable, unref'd yield so the loop cannot monopolize the microtask queue. */
+function pause(ms: number, signal?: AbortSignal): Promise<void> {
+  if (signal?.aborted) return Promise.reject(signal.reason);
+  return new Promise<void>((resolve, reject) => {
+    const finish = (settle: () => void) => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      settle();
+    };
+    const timer = setTimeout(() => finish(resolve), ms);
+    timer.unref?.();
+    const onAbort = () => finish(() => reject(signal?.reason));
+    signal?.addEventListener("abort", onAbort);
+  });
+}

package/src/codex/native-profile-startup.ts

@@ -1,6 +1,7 @@
 import { NativeProfileManager } from "./native-profile-manager";
 import { loadConfig } from "../config";
 import { initializeMainAccountPolicyBinding } from "./account-lifecycle";
+import { isMainAccountHardLockEnabled } from "./main-account-hard-lock";
 import { clearAccountNeedsReauth } from "./account-runtime-state";
 import { MAIN_CODEX_ACCOUNT_ID } from "./main-account";
 import {
@@ -188,7 +189,7 @@ function scheduleStageSweep(entry: StartupEntry): void {
         || entry.epoch !== sweepEpoch || entry.policyBindingPending) return;
       if (!safe) snapshot = { status: "blocked", homeId: entry.homeId, reason: "stage-cleanup-required" };
       else if (snapshot.homeId === entry.homeId && snapshot.status === "blocked" && snapshot.reason === "stage-cleanup-required") {
-        if (loadConfig().codexMainAccountHardLock === true) rearmOwnedMainPolicyBinding(entry);
+        if (isMainAccountHardLockEnabled(loadConfig())) rearmOwnedMainPolicyBinding(entry);
         else snapshot = ready(entry.homeId);
       }
     })().finally(() => {
@@ -200,7 +201,9 @@ function scheduleStageSweep(entry: StartupEntry): void {
 }
 
 function convergeOwnedStartup(entry: StartupEntry): void {
-  if (entry.recoveryStarted) return;
+  // The map entry is the gate's owner of record. A released one has been deleted, and every
+  // write below belongs to a generation nothing is waiting for any more.
+  if (entry.recoveryStarted || startupEntries.get(entry.homeId) !== entry) return;
   entry.recoveryStarted = true;
   const currentEpoch = entry.epoch;
   snapshot = { status: "blocked", homeId: entry.homeId, reason: "recovery-pending" };
@@ -225,7 +228,7 @@ function convergeOwnedStartup(entry: StartupEntry): void {
       ));
       const stageSweepSafe = recoveryState === "none" ? await runOwnedStageSweep(entry) : false;
       if (startupEntries.get(entry.homeId) === entry && entry.epoch === currentEpoch && recoveryState === "none" && stageSweepSafe) {
-        if (loadConfig().codexMainAccountHardLock === true) {
+        if (isMainAccountHardLockEnabled(loadConfig())) {
           await withNativeMainOwnerOperation(entry.manager.context, () => withNativeMainExclusiveClaim(
             entry.manager.context,
             async () => {
@@ -236,7 +239,7 @@ function convergeOwnedStartup(entry: StartupEntry): void {
               }
               // The HMAC is deliberately not persisted. Bind only the pinned owned home,
               // after recovery/cleanup, and before caller-owned admission can observe ready.
-              if (loadConfig().codexMainAccountHardLock === true) {
+              if (isMainAccountHardLockEnabled(loadConfig())) {
                 initializeMainAccountPolicyBinding(entry.manager.context.authPath);
               }
               clearAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
@@ -386,7 +389,7 @@ export function startNativeMainStartupLifecycle(
     entry.unsubscribe = owner.subscribe(ownerState => observeOwner(entry!, ownerState));
   } else if (!entry.policyBindingPending
     && snapshot.status === "ready" && snapshot.homeId === homeId
-    && loadConfig().codexMainAccountHardLock === true) {
+    && isMainAccountHardLockEnabled(loadConfig())) {
     // A new same-process listener can enable protection or follow a credential replacement.
     // Re-read its pinned home through the held owner before admitting caller-owned main.
     rearmOwnedMainPolicyBinding(entry);
@@ -404,6 +407,21 @@ export function startNativeMainStartupLifecycle(
     entry!.sweepTimer = undefined;
     entry!.unsubscribe();
     startupEntries.delete(homeId);
+    // A released owner cannot leave the process fenced. Convergence runs in the background, and
+    // its only guard is this entry, so a server that stops mid-convergence used to keep the
+    // "recovery-pending" snapshot the entry armed: every later native request answered 503 until
+    // the process exited, because a server whose config does not sync Codex installs a no-op
+    // lifecycle that never touches the gate.
+    //
+    // The gate state belonged only to this entry, so reset it to the process-initial state here,
+    // synchronously and before the first await: a NEW entry created for the same home afterwards
+    // re-arms its own gate and cannot be clobbered by this release. The epoch bump retires any
+    // in-flight `initializeNativeMainStartupGate`/convergence write from the released generation.
+    if (snapshot.homeId === homeId && !startupEntries.has(homeId)) {
+      epoch += 1;
+      snapshot = ready(null);
+      settled = Promise.resolve(snapshot);
+    }
     entry!.resolveAcquisition?.(snapshot);
     entry!.resolveAcquisition = undefined;
     // Startup convergence can transition from the exclusive recovery claim
@@ -705,7 +723,7 @@ export function blockNativeMainRecovery(
 export function completeNativeMainRecovery(homeId: string): boolean {
   if (snapshot.status !== "blocked" || snapshot.homeId !== homeId) return false;
   const entry = startupEntries.get(homeId);
-  if (entry && loadConfig().codexMainAccountHardLock === true) return rearmOwnedMainPolicyBinding(entry);
+  if (entry && isMainAccountHardLockEnabled(loadConfig())) return rearmOwnedMainPolicyBinding(entry);
   epoch += 1;
   clearAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
   snapshot = ready(homeId);