@bitkyc08/opencodex 2.83.0 → 2.86.0

package/src/clients/config-export.ts

@@ -24,6 +24,7 @@ import { existsSync, lstatSync, readFileSync, realpathSync, statSync } from "nod
 import { basename, dirname, isAbsolute, join, resolve, win32 } from "node:path";
 import { shouldInjectApiAuthHeader, standaloneCodexRoutingTarget } from "../codex/inject";
 import { FORMAT_MEDIA_TYPE, serializeDocument, type ConfigFormat } from "../integrations/serialize";
+import { fileIO } from "../integrations/config-io";
 import { canonicalizeReasoningEfforts } from "../reasoning-effort";
 import { expandFastExportModels } from "./config-export/fast-models";
 import { probeHostname } from "../server/proxy-liveness";
@@ -81,6 +82,8 @@ import {
 
 export type { CommandCodeGeneratedConfig, CommandCodeModelEntry, CommandCodeProviderBlock };
 export { buildCommandCodeClientConfig, summarizeCommandCode, buildCommandCodeContribution, commandCodeProviderRoot };
+import { buildQoderClientConfig, summarizeQoder, buildQoderContribution, qoderConfigPath } from "./config-export/qoder";
+export { buildQoderClientConfig, qoderConfigPath, qoderHomeDir, type QoderGeneratedConfig } from "./config-export/qoder";
 
 
 
@@ -470,20 +473,49 @@ export function mcodeConfigPath(env: OpencodeLaunchEnv = process.env, home: stri
   return join(mcodeHomeDir(env, home), "config.yaml");
 }
 
-/**
- * ZCode (Z.ai's desktop client) keeps everything under `~/.zcode`; custom
- * providers live in `v2/config.json`. `ZCODE_DATA_DIR` mirrors the other
- * clients' override convention; relative overrides are refused for the same
- * reason as MCode's.
- */
-export function zcodeHomeDir(env: OpencodeLaunchEnv = process.env, home: string = homedir()): string {
-  const override = env.ZCODE_DATA_DIR?.trim();
-  if (override) return absoluteClientPath(override, home, "ZCODE_DATA_DIR");
-  return join(home, ".zcode");
+/** Bootstrap settings always stay at the default home, even after relocation. */
+export type ZcodePathIO = {
+  readText: (path: string) => { kind: "text"; text: string } | { kind: "missing" } | { kind: "failed"; code?: string };
+};
+const zcodePathIO: ZcodePathIO = {
+  /** Shares the integration reader's four-MiB limit and regular-file-only bootstrap contract. */
+  readText: path => fileIO().readText(path),
+};
+export class ZcodeSettingsPathError extends ClientPathError {}
+
+export function zcodeBootstrapSettingsPath(home: string = homedir()): string {
+  return join(home, ".zcode", "v2", "setting.json");
 }
 
-export function zcodeConfigPath(env: OpencodeLaunchEnv = process.env, home: string = homedir()): string {
-  return join(zcodeHomeDir(env, home), "v2", "config.json");
+/** The pre-relocation path is retained solely to recognize historical ownership. */
+export function zcodeLegacyHomeDir(env: OpencodeLaunchEnv = process.env, home: string = homedir()): string {
+  const override = env.ZCODE_DATA_DIR?.trim();
+  return override ? absoluteClientPath(override, home, "ZCODE_DATA_DIR") : join(home, ".zcode");
+}
+
+/** ZCODE_DATA_DIR names the .zcode root; dataBaseDir names its parent. */
+export function zcodeHomeDir(env: OpencodeLaunchEnv = process.env, home: string = homedir(), io: ZcodePathIO = zcodePathIO): string {
+  if (env.ZCODE_DATA_DIR?.trim()) return zcodeLegacyHomeDir(env, home);
+  const bootstrap = zcodeBootstrapSettingsPath(home);
+  const read = io.readText(bootstrap);
+  if (read.kind === "missing") return join(home, ".zcode");
+  const unknown = () => new ZcodeSettingsPathError(
+    `ZCode's active data root is unknown: ${bootstrap} must be readable JSON with an absolute dataBaseDir (or no dataBaseDir). Repair the bootstrap setting before enabling or refreshing; no legacy provider will be applied.`,
+  );
+  if (read.kind !== "text") throw unknown();
+  let settings: unknown;
+  try { settings = JSON.parse(read.text); } catch { throw unknown(); }
+  if (settings === null || typeof settings !== "object" || Array.isArray(settings)) throw unknown();
+  const base = (settings as Record<string, unknown>).dataBaseDir;
+  if (base === undefined) return join(home, ".zcode");
+  // Match the native path's value, without cwd or tilde expansion. The native
+  // ZCODE_DATA_BASE_DIR selector is not an alias for our ZCODE_DATA_DIR.
+  if (typeof base !== "string" || !isAbsolute(base) || base.includes("\0")) throw unknown();
+  return join(base, ".zcode");
+}
+
+export function zcodeConfigPath(env: OpencodeLaunchEnv = process.env, home: string = homedir(), io?: ZcodePathIO): string {
+  return join(zcodeHomeDir(env, home, io), "v2", "config.json");
 }
 
 /**
@@ -532,8 +564,7 @@ export function commandCodeConfigPath(env: OpencodeLaunchEnv = process.env, home
  * an install that has ever run, the import has already happened and never runs
  * again — every later write to `v2/config.json` is read by nobody (#5348).
  *
- * This project does not write this file; it names it so the integration can
- * tell whether its own write can still reach the client. The env override is
+ * The integration writes this store through its existing schema-aware writer. The env override is
  * ZCode's own (`ZCODE_PERSONAL_PROVIDER_CONFIG_FILE`), so an operator who
  * relocated the store is measured against the file their client actually opens
  * rather than the default location. A relative override is refused for the same
@@ -541,10 +572,10 @@ export function commandCodeConfigPath(env: OpencodeLaunchEnv = process.env, home
  * which file it names, and here that disagreement decides whether an apply is
  * reported as effective.
  */
-export function zcodeProviderStorePath(env: OpencodeLaunchEnv = process.env, home: string = homedir()): string {
+export function zcodeProviderStorePath(env: OpencodeLaunchEnv = process.env, home: string = homedir(), io?: ZcodePathIO): string {
   const override = env.ZCODE_PERSONAL_PROVIDER_CONFIG_FILE?.trim();
   if (override) return absoluteClientPath(override, home, "ZCODE_PERSONAL_PROVIDER_CONFIG_FILE");
-  return join(zcodeHomeDir(env, home), "v2", "provider_config.json");
+  return join(zcodeHomeDir(env, home, io), "v2", "provider_config.json");
 }
 
 /**
@@ -1399,6 +1430,18 @@ export function clineSettingsDir(env: OpencodeLaunchEnv = process.env, home: str
 }
 
 export const EXPORT_CLIENTS: Record<ExportClientId, ExportClientSpec> = {
+  qoder: {
+    id: "qoder",
+    filename: "qoder-settings.json",
+    destination: env => qoderConfigPath(env),
+    apiKeyEnv: "",
+    exportHint: "Qoder reads a non-secret placeholder from settings.json; loopback needs no key.",
+    build: buildQoderClientConfig,
+    format: "json",
+    summarize: summarizeQoder,
+    buildContribution: buildQoderContribution,
+    loopbackOnly: true,
+  },
   opencode: {
     id: "opencode",
     filename: "opencode.json",

package/src/clients/omo-role-models.ts

@@ -120,10 +120,13 @@ function serialize(text: string, doc: JsonObject): string {
 /**
  * `reasoning` left undefined keeps the entry's level; null removes it, so a level LazyCodex cannot
  * express does not leave a stale one behind for its next install to apply.
+ * `model` left undefined keeps the entry's model, so an effort-only save of a role that inherits
+ * its model never adds a pin here. LazyCodex declares both keys optional, so an entry may carry
+ * `reasoning` alone; an absent entry is created only when there is a value to put in it.
  */
 export function writeOmoRoleModel(
   role: string,
-  model: string,
+  model: string | undefined,
   path: string = omoJsoncPath(),
   reasoning?: string | null,
 ): OmoRoleModelWriteStatus {
@@ -137,10 +140,10 @@ export function writeOmoRoleModel(
   if (!isObject(agents)) return "invalid";
   const entry = agents[role] === undefined ? {} : agents[role];
   if (!isObject(entry)) return "invalid";
-  const next: JsonObject = { ...entry, model };
+  const next: JsonObject = model === undefined ? { ...entry } : { ...entry, model };
   if (reasoning === null) delete next.reasoning;
   else if (reasoning !== undefined) next.reasoning = reasoning;
-  if (entry.model === model && entry.reasoning === next.reasoning) return "unchanged";
+  if (entry.model === next.model && entry.reasoning === next.reasoning) return "unchanged";
   agents[role] = next;
   codex.agents = agents;
   doc[CODEX_SECTION] = codex;

package/src/codex/agent-role-models.ts

@@ -1,11 +1,12 @@
 /**
- * The dashboard's write of one Codex agent role's model, and optionally its reasoning effort.
+ * The dashboard's write of one Codex agent role's model, its reasoning effort, or both.
  *
  * Codex overrides the spawn-time model with the root `model` pin in
  * `$CODEX_HOME/agents/<role>.toml`, so that pin is what decides a child's model. This module
- * edits exactly that value, plus the root `model_reasoning_effort` when a caller passes one, and
- * nothing else: every other byte of the file, including the instructions multiline string that
- * usually mentions `model =` in prose, is left as it was.
+ * edits exactly that value when a caller passes a model, plus the root `model_reasoning_effort`
+ * when a caller passes an effort, and nothing else: every other byte of the file, including the
+ * instructions multiline string that usually mentions `model =` in prose, is left as it was. An
+ * omitted model leaves the pin as it is, so a role that inherits its model keeps inheriting it.
  * It runs only on an explicit user action; no sync or startup path calls it.
  */
 import { lstatSync, readFileSync } from "node:fs";
@@ -97,6 +98,21 @@ export function setTomlRootReasoningEffort(content: string, effort: string): str
   return setTomlRootString(content, locateTomlReasoningEffortKey(content), "model_reasoning_effort", effort);
 }
 
+export function removeTomlRootReasoningEffort(content: string): string {
+  const location = locateTomlReasoningEffortKey(content);
+  if (!location?.inRootTable) return content;
+  if (!location.span) {
+    throw new AgentRoleModelError("unsupported_model_value", "the existing model_reasoning_effort value is not a one-line string");
+  }
+  const lines = content.split("\n");
+  // A terminated line goes with its own newline. An unterminated last line is emptied instead,
+  // so the previous line keeps its terminator (and its \r in a CRLF file).
+  if (location.line < lines.length - 1) lines.splice(location.line, 1);
+  else lines[location.line] = "";
+  const bom = location.line === 0 && content.startsWith("\ufeff") ? "\ufeff" : "";
+  return bom + lines.join("\n");
+}
+
 export function readCodexAgentRoleEffort(role: string, codexHome: string): string | null {
   try {
     const location = locateTomlReasoningEffortKey(readFileSync(roleFile(role, codexHome), "utf8"));
@@ -148,9 +164,9 @@ function assertValidRoleToml(role: string, text: string, stage: "before" | "afte
 
 export function writeCodexAgentRoleModel(
   role: string,
-  model: string,
+  model: string | undefined,
   codexHome: string,
-  effort?: string,
+  effort?: string | null,
 ): { status: "written" | "unchanged" } {
   requireKnownRole(role, codexHome);
   const path = roleFile(role, codexHome);
@@ -159,10 +175,12 @@ export function writeCodexAgentRoleModel(
   }
   const before = readFileSync(path, "utf8");
   assertValidRoleToml(role, before, "before");
-  const withModel = setTomlRootModel(before, validateAgentRoleModel(model));
+  const withModel = model === undefined ? before : setTomlRootModel(before, validateAgentRoleModel(model));
   const after = effort === undefined
     ? withModel
-    : setTomlRootReasoningEffort(withModel, validateAgentRoleEffort(effort));
+    : effort === null
+      ? removeTomlRootReasoningEffort(withModel)
+      : setTomlRootReasoningEffort(withModel, validateAgentRoleEffort(effort));
   if (after === before) return { status: "unchanged" };
   assertValidRoleToml(role, after, "after");
   assertIntegrationWriteOwnership(path);

package/src/codex/auth-api/account-list.ts

@@ -33,6 +33,7 @@ import { fetchMainAccountInfoAttempt, EMPTY_MAIN_ACCOUNT_INFO, mainResetCreditsF
 import { fetchPoolAccountQuota, PoolQuotaProbeBusyError, POOL_QUOTA_REFRESH_CONCURRENCY } from "./pool-quota-probe";
 import type { PoolQuotaResult } from "./pool-quota-probe";
 import { getRuntimeConfig, configuredPoolAccount, mapWithConcurrency } from "./runtime-config";
+import { isPassiveRead } from "../../lib/passive-read";
 
 export function quotaForPlan<T extends Omit<StoredAccountQuota, "updatedAt"> | StoredAccountQuota | null>(
   quota: T,
@@ -274,13 +275,25 @@ export async function listCodexAuthAccountsSnapshot(
   pruneCodexCredits([MAIN_CODEX_ACCOUNT_ID, ...poolAccounts.map(account => account.id)]);
   // One redaction decision for the whole snapshot, read once from the operator's config (#3859).
   const maskEmails = emailMaskingEnabled(runtimeConfig);
-  const mainResult = await fetchMainAccountInfoAttempt(forceRefresh, 1, undefined, false,
-    forceRefresh, false, runtimeConfig);
+  // A passive read (a Remote Link Child's, #6959) reports what this machine already observed: no
+  // token refresh, no WHAM probe, and so none of the plan or credential writes they make.
+  const passive = isPassiveRead();
+  const mainResult: Awaited<ReturnType<typeof fetchMainAccountInfoAttempt>> = passive
+    ? { info: getMainAccountInfoCache() ?? EMPTY_MAIN_ACCOUNT_INFO, credentialChecked: false, hasCredential: false,
+      identityGeneration: captureMainAccountIdentityGeneration() }
+    : await fetchMainAccountInfoAttempt(forceRefresh, 1, undefined, false, forceRefresh, false, runtimeConfig);
   const refreshedPool = await mapWithConcurrency(poolAccounts, POOL_QUOTA_REFRESH_CONCURRENCY, async account => {
     const cred = getCodexAccountCredential(account.id);
     let quotaResult: PoolQuotaResult;
     if (!cred) {
       quotaResult = { quota: null, needsReauth: true };
+    } else if (passive) {
+      quotaResult = {
+        quota: getAccountQuota(account.id),
+        needsReauth: false,
+        credentialGeneration: readCodexAccountRecord(account.id)?.generation,
+        quotaProbeSkipped: true,
+      };
     } else {
       try {
         // Credits are process-local while pool quota is hydrated from disk, so right after a
@@ -410,6 +423,8 @@ export async function listCodexAuthAccountsSnapshot(
   };
   // Project the refusal and DTO in the same owned synchronous observation. A same-account grant
   // replacement during earlier pool probes must not inherit the previous grant's refusal.
+  // A passive read opens no claim database (its lock file is hardened on open).
+  if (passive) return projectSnapshot();
   const projectionLease = tryAcquireNativeMainProfileClaim();
   if (!projectionLease) return projectSnapshot();
   try {

package/src/codex/auth-api/account-selection.ts

@@ -6,11 +6,11 @@ import { deleteConfigTopLevelKey, fileBackedConfigPath, recordFileBackedConfig }
 import { MAIN_CODEX_ACCOUNT_ID, hasLegacyMainCodexPoolAccount, isSelectableCodexPoolAccount, isValidCodexAccountId } from "../account-id";
 import { isCodexAccountPaused } from "../account-pause";
 import { readCodexAccountRecord } from "../account-store";
-import { codexAccountPinDrainReason, resetCodexRoutingForManualSelection } from "../routing";
+import { codexAccountPinDrainReason, resetCodexRoutingForClearedSelection, resetCodexRoutingForManualSelection } from "../routing";
 import { jsonResponse } from "./http";
 
 class SelectionRejected extends Error {
-  constructor(message: string, readonly status: number) { super(message); }
+  constructor(message: string, readonly status: number, readonly code?: string) { super(message); }
 }
 
 function validateSelection(config: OcxConfig, accountId: string | null): void {
@@ -42,8 +42,14 @@ function applySelection(config: OcxConfig, accountId: string | null): boolean {
   return changed;
 }
 
+function validateExpectedPin(config: OcxConfig, expectedPinnedAccountId: string | undefined): void {
+  if (expectedPinnedAccountId !== undefined && config.activeCodexAccountPinned !== expectedPinnedAccountId) {
+    throw new SelectionRejected("The pin changed; reload accounts before releasing it", 409, "account_pin_changed");
+  }
+}
+
 /** A manual selection is an explicit command, even when equal to the live merge baseline. */
-export function persistCodexAccountSelection(config: OcxConfig, accountId: string | null): Response {
+export function persistCodexAccountSelection(config: OcxConfig, accountId: string | null, expectedPinnedAccountId?: string): Response {
   const unknown = () => jsonResponse({
     error: "Account selection could not be confirmed; reload settings before retrying",
     code: "account_selection_unavailable",
@@ -63,7 +69,9 @@ export function persistCodexAccountSelection(config: OcxConfig, accountId: strin
       const normalized = validateConfigCandidate(mergeConfigDefaults(config));
       if (!normalized.ok) return unknown();
       const initial = normalized.config;
-      applySelection(initial, accountId);
+      validateExpectedPin(initial, expectedPinnedAccountId);
+      // Conditional release must keep the baseline pin until the locked mutation checks it.
+      if (expectedPinnedAccountId === undefined) applySelection(initial, accountId);
       initializePersistedConfigIfMissing(initial);
     }
     const result = mutatePersistedConfig(persisted => {
@@ -71,12 +79,13 @@ export function persistCodexAccountSelection(config: OcxConfig, accountId: strin
       // A removed or paused account must not be resurrected by a stale UI snapshot.
       validateSelection(config, accountId);
       validateSelection(persisted, accountId);
+      validateExpectedPin(persisted, expectedPinnedAccountId);
       return { changed: applySelection(persisted, accountId), value: persisted };
     });
     if (result.status === "unavailable") return unknown();
     committed = result.value;
   } catch (error) {
-    if (error instanceof SelectionRejected) return jsonResponse({ error: error.message }, error.status);
+    if (error instanceof SelectionRejected) return jsonResponse({ error: error.message, ...(error.code ? { code: error.code } : {}) }, error.status);
     // Atomic publication may succeed before generation/bookkeeping fails. Confirm the exact
     // durable selection instead of rolling live state back behind an already published write.
     const snapshot = readConfigFileSnapshot();
@@ -95,12 +104,13 @@ export function persistCodexAccountSelection(config: OcxConfig, accountId: strin
   adoptPersistedCodexAccountSelection(config, committed);
   recordFileBackedConfig(config, configPath);
   // No failed save may clear affinity, spend the manual preference, or move the RR cursor.
-  resetCodexRoutingForManualSelection(accountId ?? MAIN_CODEX_ACCOUNT_ID);
+  if (accountId === null) resetCodexRoutingForClearedSelection();
+  else resetCodexRoutingForManualSelection(accountId);
   const pinDrainReason = accountId === null ? undefined : codexAccountPinDrainReason(config, accountId);
   return jsonResponse({
     ok: true,
     activeCodexAccountId: config.activeCodexAccountId ?? null,
-    appliesImmediately: true,
+    appliesImmediately: accountId !== null,
     ...(pinDrainReason !== undefined ? { pinDrained: true, pinDrainReason } : {}),
     ...(warning ? { warning: "config_bookkeeping_failed" } : {}),
   });

package/src/codex/auth-api/pool-mode-gate.ts

@@ -25,6 +25,7 @@ import type { PoolQuotaResult } from "./pool-quota-probe";
 import { fetchMainAccountInfoAttempt, fetchMainAccountInfo, MAIN_CACHE_TTL } from "./main-account-probe";
 import { fetchPoolAccountQuota, PoolQuotaProbeBusyError, POOL_CACHE_TTL, POOL_QUOTA_REFRESH_CONCURRENCY } from "./pool-quota-probe";
 import { getRuntimeConfig, configuredPoolAccount, mapWithConcurrency } from "./runtime-config";
+import { trackBackgroundWork } from "../../lib/background-work";
 
 let primeInFlight: Promise<void> | null = null;
 let lastPriorityFailbackPrimeAt: number | undefined;
@@ -259,7 +260,9 @@ export async function primeCodexPoolQuotas(
       && now - lastPriorityFailbackPrimeAt < CODEX_PRIORITY_FAILBACK_REFRESH_MS) return;
     lastPriorityFailbackPrimeAt = now;
   }
-  primeInFlight = (async () => {
+  // Tracked because most callers do not await it, yet it holds the native-main claim
+  // database open; whoever removes that directory settles it first (see background-work).
+  primeInFlight = trackBackgroundWork(`codex-pool-quota-prime:${reason}`, (async () => {
     const pool = (runtimeConfig.codexAccounts ?? []).filter(isSelectableCodexPoolAccount);
     const stale = pool.filter(a => {
       const q = getAccountQuota(a.id);
@@ -344,7 +347,7 @@ export async function primeCodexPoolQuotas(
     if (process.env.OPENCODEX_DEBUG_QUOTA === "1") {
       console.warn(`[codex-quota] prime done (reason=${reason}, pool=${pool.length}, refreshed=${stale.length})`);
     }
-  })().finally(() => { primeInFlight = null; });
+  })().finally(() => { primeInFlight = null; }));
   return primeInFlight;
 }
 

package/src/codex/auth-api/routes.ts

@@ -254,7 +254,11 @@ export async function handleCodexAuthAPI(
       || !("accountId" in body) || (body.accountId !== null && typeof body.accountId !== "string")) {
       return jsonResponse({ error: "accountId must be an account id or null" }, 400);
     }
-    return persistCodexAccountSelection(getRuntimeConfig(config), body.accountId);
+    const expectedPin = "expectedPinnedAccountId" in body ? body.expectedPinnedAccountId : undefined;
+    if (expectedPin !== undefined && (body.accountId !== null || !isCodexAccountPriorityKey(expectedPin))) {
+      return jsonResponse({ error: "expectedPinnedAccountId must be a valid account id for a release" }, 400);
+    }
+    return persistCodexAccountSelection(getRuntimeConfig(config), body.accountId, expectedPin as string | undefined);
   }
 
   if (url.pathname === "/api/codex-auth/active" && req.method === "GET") {

package/src/codex/auth-context.ts

@@ -51,6 +51,7 @@ import {
 // The half-open TRANSIENT-HOLD lease (#4701). Not the quota-cooldown probe lease imported from
 // ./routing above -- different module, different domain, and a request never holds both.
 import { releaseTransientProbe } from "../routing/probe-lease";
+import { trackBackgroundWork } from "../lib/background-work";
 import {
   codexConversationIdentity,
   recordCodexThreadLineage,
@@ -66,7 +67,8 @@ import {
 import { ACCOUNT_GATED_NATIVE_OPENAI_MODELS, NATIVE_RESERVE_MODEL } from "./catalog/native-models";
 import type { CodexCooldownSource, CodexQuotaScope } from "./routing";
 import { maskAccountId } from "../lib/privacy";
-import { formatErrorResponse } from "../bridge";
+import { formatErrorResponse, formatUsageLimitReachedResponse } from "../bridge";
+import { nextCodexPoolRecoveryAt } from "./routing/pool-recovery";
 import { CODEX_UNKNOWN_USAGE_SCORE, getAccountQuota, getMainPolicyQuota, parseUsageQuota, parseMainPolicyUsageQuota, setAccountQuotaFromParsed } from "./quota";
 import { codexAccountUsesCreditsAfterLimit, codexUsageLimitResetAt } from "./account-credit-use";
 import type { CodexAccountMode, OcxConfig, OcxProviderConfig } from "../types";
@@ -523,6 +525,11 @@ export class CodexAccountCooldownError extends Error {
 
 export class CodexMainAccountHardLockError extends CodexAccountCooldownError {
   readonly resetAt?: number;
+  /**
+   * Earliest known recovery of another stored pool account, set only when an unpinned pool
+   * selection reached main (#7046). A hint for the client's retry time; never routing input.
+   */
+  poolRecoveryAt?: number;
 
   constructor(resetAt?: number, thresholds = resolveMainAccountHardLockThresholds(undefined)) {
     super(MAIN_CODEX_ACCOUNT_ID, resetAt ?? 0);
@@ -935,16 +942,40 @@ export function cooldownErrorMessage(err: CodexAccountCooldownError, accountSele
     + ` (source: ${err.cooldownSource ?? "default"}).${recovery}`;
 }
 
+/**
+ * The soonest a main hard-lock refusal is worth retrying: a sibling pool account's known
+ * recovery when it comes first, otherwise main's own reset (#7046). A pool hint is held to at
+ * least {@link MAIN_HARD_LOCK_MIN_POOL_RETRY_MS} so a hold about to lapse cannot turn the refusal
+ * into a tight retry loop. Null when neither time is known and still in the future.
+ */
+export const MAIN_HARD_LOCK_MIN_POOL_RETRY_MS = 60_000;
+export function mainHardLockRetryAt(err: CodexMainAccountHardLockError, now: number): number | null {
+  const future = (value: number | undefined): number | null =>
+    typeof value === "number" && Number.isFinite(value) && value > now ? value : null;
+  const main = future(err.resetAt);
+  const pool = future(err.poolRecoveryAt);
+  const poolRetryAt = pool === null ? null : Math.max(pool, now + MAIN_HARD_LOCK_MIN_POOL_RETRY_MS);
+  if (poolRetryAt !== null && (main === null || poolRetryAt < main)) return poolRetryAt;
+  return main;
+}
+
 /** HTTP form of {@link cooldownErrorMessage}, carrying Retry-After for well-behaved clients. */
 export function cooldownErrorResponse(
   err: CodexAccountCooldownError,
   now = Date.now(),
   accountSelector?: string,
 ): Response {
+  if (err instanceof CodexMainAccountHardLockError) {
+    // A local policy refusal with a known horizon, not a transient throttle (#7046): Codex keeps
+    // a Goal active and sleeps through `rate_limit_exceeded` for the whole Retry-After, but
+    // stops on `usage_limit_reached` and shows the reset. The guard itself is unchanged.
+    const retryAt = mainHardLockRetryAt(err, now);
+    return formatUsageLimitReachedResponse(cooldownErrorMessage(err, accountSelector), retryAt,
+      retryAt === null ? null : Math.max(1, Math.ceil((retryAt - now) / 1000)));
+  }
   const res = formatErrorResponse(429, "rate_limit_error", cooldownErrorMessage(err, accountSelector));
   const headers = new Headers(res.headers);
-  if (!(err instanceof CodexReserveUnavailableError)
-    && (!(err instanceof CodexMainAccountHardLockError) || err.resetAt !== undefined)) {
+  if (!(err instanceof CodexReserveUnavailableError)) {
     headers.set("Retry-After", String(Math.max(1, Math.ceil((err.cooldownUntil - now) / 1000))));
   }
   return new Response(res.body, { status: res.status, headers });
@@ -1044,11 +1075,51 @@ async function awaitMainAccountPolicyBindingSettled(
   if (!settled) throw new CodexMainProfileDrainingError();
 }
 
+/**
+ * Resolve the credential for one Codex turn. A main hard-lock reached through unpinned pool
+ * selection is annotated with the earliest known pool recovery, so the refusal can name a retry
+ * time that a sibling account may meet (#7046).
+ */
 export async function resolveCodexAuthContext(
   headers: Headers,
   config: OcxConfig,
   mode: CodexAccountMode,
   options: ResolveCodexAuthContextOptions = {},
+): Promise<CodexAuthContext> {
+  // Filled by the inner resolver with the request's own fenced model evidence, so the hint obeys it.
+  const eligibility: RecoveryHintEligibility = {};
+  try {
+    return await resolveCodexAuthContextUnannotated(headers, config, mode, options, eligibility);
+  } catch (error) {
+    if (error instanceof CodexMainAccountHardLockError && mode === "pool" && options.accountId === undefined
+      && options.excludeAccountId !== MAIN_CODEX_ACCOUNT_ID
+      && !requiresReserveAuthorization(options.codexAuthPolicy ?? config, options.modelId, options.admission)
+      // An account-gated model with no resolved roster has no known eligible sibling.
+      && (!options.modelId || !ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(options.modelId)
+        || eligibility.modelEligibleAccountIds !== undefined)) {
+      try {
+        const now = Date.now();
+        error.poolRecoveryAt = nextCodexPoolRecoveryAt(config, now, codexQuotaScopeForModel(options.modelId), {
+          deniedAccountIds: eligibility.deniedModelAccountIds,
+          eligibleAccountIds: eligibility.modelEligibleAccountIds,
+        });
+      } catch { /* the hint is optional; the refusal stands without it */ }
+    }
+    throw error;
+  }
+}
+
+interface RecoveryHintEligibility {
+  modelEligibleAccountIds?: ReadonlySet<string>;
+  deniedModelAccountIds?: ReadonlySet<string>;
+}
+
+async function resolveCodexAuthContextUnannotated(
+  headers: Headers,
+  config: OcxConfig,
+  mode: CodexAccountMode,
+  options: ResolveCodexAuthContextOptions = {},
+  eligibility: RecoveryHintEligibility = {},
 ): Promise<CodexAuthContext> {
   const writerGeneration = captureConfigGeneration();
   const policy = options.codexAuthPolicy ?? config;
@@ -1256,6 +1327,7 @@ export async function resolveCodexAuthContext(
     const modelEligibleAccountIds = entitledAccountIds
       ? new Set([...entitledAccountIds].filter(candidate => !excludeAccountIds?.has(candidate)))
       : undefined;
+    eligibility.modelEligibleAccountIds = modelEligibleAccountIds;
     // #4768: the flagships stay visible and never fail closed, so this is evidence routing may
     // ORDER by, not evidence it may refuse on. Read synchronously from rosters discovery has
     // already gathered -- no upstream fetch joins the request path for the most commonly
@@ -1273,6 +1345,7 @@ export async function resolveCodexAuthContext(
       undefined,
       { excludeAccountIds },
     );
+    eligibility.deniedModelAccountIds = deniedModelAccountIds;
     const selectionOptions = {
       // Temporary switch drain keeps the candidate until the atomic claim rejects
       // it. Retained recovery makes main wholly ineligible so pool routing continues.
@@ -1475,9 +1548,10 @@ export async function resolveCodexAuthContext(
     if (options.primeCodexPoolQuotas) {
       void options.primeCodexPoolQuotas(config, reason).catch(() => {});
     } else {
-      import("./auth-api")
+      // Tracked from the import on: the prime registers itself only once the module resolves.
+      void trackBackgroundWork(`codex-pool-quota-prime-import:${reason}`, import("./auth-api")
         .then(({ primeCodexPoolQuotas }) => primeCodexPoolQuotas(config, reason))
-        .catch(() => {});
+        .catch(() => {}));
     }
   }
   // Snapshot (not just the deadline) so a refused request can report WHY it is cooled:

package/src/codex/autostart-health.ts

@@ -35,6 +35,7 @@ export interface StartupHealthInputs {
   shimHealthy: boolean;
   platform: NodeJS.Platform;
   diagnosticStale?: boolean;
+  shimActivationPending?: boolean;
   routingAdoption?: RoutingAdoptionEvidence;
 }
 
@@ -55,6 +56,8 @@ export interface StartupHealth {
   serviceConflict: boolean;
   shimInstalled: boolean;
   shimHealthy: boolean;
+  /** Intact PATH-overlay shim this process could not see active; activate it rather than repair it. */
+  shimActivationPending?: boolean;
   shimCoverage: ShimCoverage;
   serviceSupported: boolean;
   platform: NodeJS.Platform;
@@ -171,6 +174,7 @@ export function collectStartupHealth(
     serviceSupported: service.supported,
     shimInstalled: shim.installed,
     shimHealthy: shim.healthy,
+    ...(shim.activationPending ? { shimActivationPending: true } : {}),
     platform: process.platform,
     ...(routingAdoption ? { routingAdoption } : {}),
   });
@@ -215,7 +219,9 @@ function classifyStartupHealthSummary(health: StartupHealth): string {
     ? "custom remote Codex routing (no local restart dependency)"
     : "native Codex routing (no opencodex restart dependency)";
   if (health.protection === "service") return "protected by background service";
-  if (health.protection === "desktop") return "protected by desktop app at login and its proxy supervisor";
+  if (health.protection === "desktop") return health.desktop?.loginRegistration === "registered-not-loaded"
+    ? "protected by desktop app at next login and its proxy supervisor (Start at Login registered; not loaded in this session)"
+    : "protected by desktop app at login and its proxy supervisor";
   const command = health.recommendedCommand ?? health.commands.restoreNative;
   if (health.routingKind === "unknown") return `AT RISK after restart (Codex routing could not be verified; run '${command}')`;
   if (health.routingKind === "custom-local") return `AT RISK after restart (custom local gateway lifecycle is not managed by opencodex; run '${command}')`;

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

@@ -48,7 +48,8 @@ import { NATIVE_RESERVE_MODEL } from "./native-models";
 import { isReserveCatalogProjection, type ReserveCatalogProjection } from "./reserve";
 import { deriveEntry, finishUpstreamNativeEntry, isExactComboCatalogEntry } from "./derive-entry";
 import { PICKER_ORDER_PRIORITY_BASE, SPAWN_PRIORITY_FIELD } from "./subagent-roster";
-import { preserveOperatorUltraFastTiers } from "./operator-tiers";
+import { applyConfiguredUltraFast } from "./configured-tiers";
+import { applyNativeUltraFastTier } from "./native-ultrafast";
 
 export interface ObservedCatalogEntryBuildInput {
   readonly template: RawEntry | null;
@@ -473,6 +474,8 @@ export function applyFullModelPickerOrder(entries: RawEntry[], order: readonly s
 export interface ObservedCatalogMergeInput {
   /** Preserve operator-supplied Ultra Fast only from the exact persisted routed row. */
   readonly ultraFastTier?: boolean;
+  /** Current captured wire declarations; disk rows and templates never populate this set. */
+  readonly configuredUltraFastSlugs?: ReadonlySet<string>;
   readonly catalogModels: readonly RawEntry[];
   readonly baselineCatalogModels: readonly RawEntry[];
   readonly routedEntries: readonly RawEntry[];
@@ -514,6 +517,7 @@ export interface ObservedCatalogMergeInput {
  */
 export function mergeCatalogEntriesFromObservedState({
   ultraFastTier = false,
+  configuredUltraFastSlugs = new Set(),
   catalogModels,
   baselineCatalogModels,
   routedEntries,
@@ -865,7 +869,7 @@ export function mergeCatalogEntriesFromObservedState({
     if (typeof entry.slug !== "string" || !entry.slug.includes("/")
       || isNativeAliasCatalogEntry(entry) || isExactComboCatalogEntry(entry, exactComboSlugs)
       || trustedAccountBoundNativeCatalogSlug(entry) !== undefined) continue;
-    preserveOperatorUltraFastTiers(entry, operatorRows.get(entry.slug), ultraFastTier);
+    applyConfiguredUltraFast(entry, operatorRows.get(entry.slug), configuredUltraFastSlugs.has(entry.slug), ultraFastTier);
   }
   const finalRoutedEntrySet = new Set(finalRoutedEntries);
   const degradedPreservedCount = preservedRoutedEntries.filter(entry => {
@@ -932,6 +936,11 @@ export function mergeCatalogEntriesFromObservedState({
         );
       }
     }
+    // Native Astra/Sol rows (bare and account-bound) gain or lose the documented Ultrafast
+    // choice with the switch; aliases, combos and reserve projections keep their own tiers.
+    if (!reserveProjection && !exactCombo && m.owned_by !== COMBO_NAMESPACE && !isNativeAliasCatalogEntry(e)) {
+      applyNativeUltraFastTier(e, ultraFastTier);
+    }
     if (wsEnabled) e.supports_websockets = true;
     else {
       delete e.supports_websockets;

package/src/codex/catalog/bundled.ts

@@ -28,6 +28,7 @@ import {
 import type { NormalizedComboConfig } from "../../combos/types";
 import { providerDestinationResolvedError } from "../../lib/destination-policy";
 import { redactSecretString } from "../../lib/redact";
+import { isPassiveRead } from "../../lib/passive-read";
 import upstreamModelsSnapshot from "../data/upstream-models.json";
 import { decodeOverlayState } from "../shim-state-file";
 
@@ -313,7 +314,8 @@ function* bundledCatalogSteps(
       const output = yield command;
       if (!current()) return null;
       const catalog = output === null ? null : parseCatalogJson(output);
-      if (catalog && findNativeTemplate(catalog)) {
+      if (catalog && catalog.models?.every(row => row !== null && typeof row === "object" && !Array.isArray(row))
+        && findNativeTemplate(catalog)) {
         if (cacheKey) {
           publishBundledCatalogCache(
             cacheKey,
@@ -377,6 +379,8 @@ export function loadBundledCodexCatalogAsync(
   if (useCache && bundledCatalogFlight?.inputs === inputs && bundledCatalogFlight.epoch === epoch) {
     return view(bundledCatalogFlight.promise);
   }
+  // A passive read (a Remote Link Child's, #6959) runs no Codex binary and persists no runtime.
+  if (isPassiveRead()) return Promise.resolve(null);
   const controller = new AbortController();
   const flight = { inputs, epoch, controller, promise: Promise.resolve<ReadonlyRawCatalog | null>(null) };
   if (useCache && !signal && isCurrent === catalogAlwaysCurrent) {