@remodex/rmx 1.0.2

package/src/codex/journal.ts

@@ -0,0 +1,172 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteFile } from "../config";
+import { hasInjectedCodexRouting } from "./injected-marker";
+import { CODEX_HOME, CODEX_CONFIG_PATH, CODEX_PROFILE_PATH } from "./paths";
+
+/**
+ * Exported so that anything reasoning ABOUT the journal points at the journal.
+ *
+ * The Codex admission snapshot re-derived this path by hand and got it wrong in
+ * both halves — wrong directory and wrong filename — so its "journal identity"
+ * watched a file nothing writes. The fixture re-derived it the same wrong way,
+ * agreed with the producer, and the pair stayed green. One exported constant
+ * removes the opportunity.
+ */
+export const JOURNAL_PATH = join(CODEX_HOME, "opencodex-journal.json");
+
+interface Journal {
+  version: 1;
+  originalConfig: string;
+  originalProfile: string | null;
+  injectedConfigHash?: string;
+  injectedProfileHash?: string | null;
+  pid: number;
+  timestamp: string;
+}
+
+interface RestoreJournalResult {
+  configRestored: boolean;
+  profileRestored: boolean;
+  configChanged: boolean;
+  profileChanged: boolean;
+  complete: boolean;
+}
+
+function sha256(content: string | null): string | null {
+  return content === null ? null : createHash("sha256").update(content).digest("hex");
+}
+
+export interface WriteJournalOptions {
+  /**
+   * The caller's verdict on the config it is about to transform: false when
+   * `hasInjectedCodexRouting` matched. This does NOT decide whether the content
+   * may be journaled — that is checked below, from the bytes themselves. It only
+   * authorizes REPLACING an existing snapshot, which is why omitting it still
+   * allows a first snapshot but never an overwrite.
+   */
+  currentStateIsNative?: boolean;
+  /**
+   * The exact bytes the caller classified. Journaling these rather than re-reading
+   * the file keeps the snapshot and the verdict describing the same content when
+   * another process rewrites config.toml mid-flight.
+   */
+  configContent?: string;
+}
+
+/**
+ * Snapshot the pre-injection Codex state.
+ *
+ * Only native (non-Remodex-owned) config may be journaled, and native config
+ * always supersedes an older snapshot. The first half stops a re-inject from
+ * recording Remodex's own routing as the user's original — which would survive
+ * `rmx stop` and make the injection unremovable. The second half is the #477 fix:
+ * without it the first snapshot a machine ever takes is the only one it ever has,
+ * so an unclean shutdown days later replays a day-one config over the user's
+ * plugins, model choice, and trusted projects.
+ */
+export function writeJournal(options: WriteJournalOptions = {}): void {
+  if (!existsSync(CODEX_CONFIG_PATH)) return;
+  const config = options.configContent ?? readFileSync(CODEX_CONFIG_PATH, "utf-8");
+  // Ownership is decided HERE, from the bytes about to be journaled — never taken
+  // on the caller's word. A caller that says "native" about injected content would
+  // otherwise make Remodex's own routing the user's permanent "original".
+  if (hasInjectedCodexRouting(config)) return;
+  // The caller's verdict only authorizes REPLACEMENT. It is weaker evidence than
+  // the check above (it may describe bytes read a moment earlier), so an
+  // unclassified call creates a first snapshot but never overwrites one.
+  if (existsSync(JOURNAL_PATH) && readJournal() && options.currentStateIsNative !== true) return;
+  const profile = existsSync(CODEX_PROFILE_PATH)
+    ? readFileSync(CODEX_PROFILE_PATH, "utf-8")
+    : null;
+  const journal: Journal = {
+    version: 1,
+    originalConfig: Buffer.from(config).toString("base64"),
+    originalProfile: profile ? Buffer.from(profile).toString("base64") : null,
+    pid: process.pid,
+    timestamp: new Date().toISOString(),
+  };
+  atomicWriteFile(JOURNAL_PATH, JSON.stringify(journal));
+}
+
+export function markJournalInjectedState(config: string, profile: string | null): void {
+  const journal = readJournal();
+  if (!journal) return;
+  if (journal.injectedConfigHash) return;
+  journal.injectedConfigHash = sha256(config) ?? undefined;
+  journal.injectedProfileHash = sha256(profile);
+  atomicWriteFile(JOURNAL_PATH, JSON.stringify(journal));
+}
+
+export function removeJournal(): void {
+  try { unlinkSync(JOURNAL_PATH); } catch { /* ignore */ }
+}
+
+function readJournal(): Journal | null {
+  if (!existsSync(JOURNAL_PATH)) return null;
+  try {
+    const journal = JSON.parse(readFileSync(JOURNAL_PATH, "utf-8")) as Journal;
+    if (journal.version !== 1) throw new Error("unknown version");
+    return journal;
+  } catch {
+    removeJournal();
+    return null;
+  }
+}
+
+export function restoreJournalState(): RestoreJournalResult {
+  const journal = readJournal();
+  if (!journal) {
+    return { configRestored: false, profileRestored: false, configChanged: false, profileChanged: false, complete: false };
+  }
+  const currentConfig = existsSync(CODEX_CONFIG_PATH) ? readFileSync(CODEX_CONFIG_PATH, "utf-8") : "";
+  const currentProfile = existsSync(CODEX_PROFILE_PATH) ? readFileSync(CODEX_PROFILE_PATH, "utf-8") : null;
+  const configUnchanged = !journal.injectedConfigHash || sha256(currentConfig) === journal.injectedConfigHash;
+  const profileUnchanged = journal.injectedProfileHash === undefined || sha256(currentProfile) === (journal.injectedProfileHash ?? null);
+
+  let configRestored = false;
+  let profileRestored = false;
+  if (configUnchanged) {
+    atomicWriteFile(CODEX_CONFIG_PATH, Buffer.from(journal.originalConfig, "base64").toString("utf-8"));
+    configRestored = true;
+  }
+  if (profileUnchanged) {
+    if (journal.originalProfile !== null) {
+      atomicWriteFile(CODEX_PROFILE_PATH, Buffer.from(journal.originalProfile, "base64").toString("utf-8"));
+    } else if (existsSync(CODEX_PROFILE_PATH)) {
+      try { unlinkSync(CODEX_PROFILE_PATH); } catch { /* ignore */ }
+    }
+    profileRestored = true;
+  }
+  const complete = configRestored && profileRestored;
+  if (complete) removeJournal();
+  return {
+    configRestored,
+    profileRestored,
+    configChanged: !configUnchanged,
+    profileChanged: !profileUnchanged,
+    complete,
+  };
+}
+
+export function restoreJournal(): boolean {
+  return restoreJournalState().complete;
+}
+
+export function reconcileJournal(): boolean {
+  const journal = readJournal();
+  if (!journal) return false;
+  try {
+    process.kill(journal.pid, 0);
+    return false;
+  } catch (e: unknown) {
+    if ((e as NodeJS.ErrnoException).code === "EPERM") {
+      return false;
+    }
+  }
+  const restored = restoreJournalState();
+  if (!restored.configRestored && !restored.profileRestored) return false;
+  console.error(`⚠️  Previous session (PID ${journal.pid}) did not shut down cleanly. Codex state restored from journal.`);
+  return true;
+}

package/src/codex/main-account-cache.ts

@@ -0,0 +1,56 @@
+import type { StoredAccountQuota } from "./quota";
+import { truncateRetainedUtf8 } from "../lib/admission";
+
+const MAX_DIAGNOSTIC_VALUE_BYTES = 8 * 1024;
+
+export interface MainAccountInfo {
+  email: string | null;
+  plan: string | null;
+  quota: Omit<StoredAccountQuota, "updatedAt"> | null;
+}
+
+export interface CachedMainAccountInfo extends MainAccountInfo {
+  ts: number;
+}
+
+let cachedMainAccountInfo: CachedMainAccountInfo | null = null;
+let cachedMainCredentialPresence: boolean | null = null;
+let mainAccountIdentityGeneration = 0;
+
+export function captureMainAccountIdentityGeneration(): number {
+  return mainAccountIdentityGeneration;
+}
+
+export function isMainAccountIdentityGenerationLive(generation: number): boolean {
+  return generation === mainAccountIdentityGeneration;
+}
+
+export function getMainAccountInfoCache(): CachedMainAccountInfo | null {
+  return cachedMainAccountInfo;
+}
+
+export function setMainAccountInfoCache(value: CachedMainAccountInfo): void {
+  cachedMainAccountInfo = {
+    ...value,
+    email: value.email === null ? null : truncateRetainedUtf8(value.email, MAX_DIAGNOSTIC_VALUE_BYTES),
+    plan: value.plan === null ? null : truncateRetainedUtf8(value.plan, MAX_DIAGNOSTIC_VALUE_BYTES),
+  };
+}
+
+export function clearMainAccountInfoCache(): void {
+  cachedMainAccountInfo = null;
+  mainAccountIdentityGeneration += 1;
+}
+
+/** Last physical credential presence observed while native-main ownership was held. */
+export function getMainAccountCredentialPresence(): boolean | null {
+  return cachedMainCredentialPresence;
+}
+
+export function setMainAccountCredentialPresence(present: boolean): void {
+  cachedMainCredentialPresence = present;
+}
+
+export function clearMainAccountCredentialPresence(): void {
+  cachedMainCredentialPresence = null;
+}

package/src/codex/main-account.ts

@@ -0,0 +1,40 @@
+import { readCodexTokens } from "./auth-collision";
+import { decodeJwtPayload } from "../oauth/chatgpt";
+import { MAIN_CODEX_ACCOUNT_ID } from "./account-id";
+
+export { MAIN_CODEX_ACCOUNT_ID } from "./account-id";
+
+/**
+ * Main account plan (e.g. "plus", "go", "free", "team"), populated from the WHAM usage
+ * fetch. Used by the rotation usage-score so go/free main accounts score on monthly
+ * percent, matching pool-account behavior.
+ */
+let mainAccountPlan: string | null = null;
+
+export function setMainAccountPlan(plan: string | null): void {
+  mainAccountPlan = plan;
+}
+
+export function getMainAccountPlan(): string | undefined {
+  return mainAccountPlan ?? undefined;
+}
+
+/** Read-only main account token from ~/.codex/auth.json, or null when not logged in. */
+export function getMainAccountToken(): { accessToken: string; chatgptAccountId: string } | null {
+  const tokens = readCodexTokens();
+  if (!tokens?.access_token) return null;
+  return { accessToken: tokens.access_token, chatgptAccountId: tokens.account_id };
+}
+
+/**
+ * The main token is usable when it exists and — if its JWT carries a decodable `exp` — is
+ * not expired. When `exp` cannot be decoded we treat the token as live (best-effort); an
+ * actually-invalid token then surfaces via the upstream 401 → cooldown path.
+ */
+export function isMainAccountTokenLive(now = Date.now()): boolean {
+  const tokens = readCodexTokens();
+  if (!tokens?.access_token) return false;
+  const payload = decodeJwtPayload(tokens.access_token);
+  const exp = typeof payload?.exp === "number" ? payload.exp * 1000 : undefined;
+  return exp === undefined || exp > now;
+}

package/src/codex/management-convergence.ts

@@ -0,0 +1,114 @@
+import type { OcxConfig } from "../types";
+import { captureCatalogAdmissionSnapshot } from "./catalog-admission";
+import { convergeCodexCatalog } from "./convergence";
+import type {
+  CatalogDisposition,
+  CatalogOnlyOutcome,
+  CodexHistoryState,
+  CodexObservedState,
+  ConvergeCodex,
+  ProjectCatalogOnlyOutcomeInput,
+} from "./convergence-types";
+
+function notEvaluatedHistory(): CodexHistoryState {
+  return {
+    status: "not-evaluated",
+    attempts: 0,
+    nextRetryAt: null,
+    txId: null,
+    pendingRows: null,
+    backupEntries: null,
+  };
+}
+
+function notEvaluatedObserved(history: CodexHistoryState): CodexObservedState {
+  return {
+    aggregate: "not-evaluated",
+    isApplied: null,
+    desired: "unknown",
+    converged: null,
+    authority: { service: "unknown", externalProvider: null },
+    surfaces: {
+      config: "not-evaluated",
+      profile: "not-evaluated",
+      catalog: "not-evaluated",
+      cache: "not-evaluated",
+      journal: "not-evaluated",
+      history: {
+        state: history,
+        database: "not-evaluated",
+        manifest: "not-evaluated",
+        rollouts: "not-evaluated",
+      },
+      provenance: {
+        state: "not-evaluated",
+        nativeGeneration: null,
+        currentTxId: null,
+      },
+    },
+  };
+}
+
+function unexpectedCatalogFailure(commitBegan: boolean): CatalogDisposition {
+  return {
+    status: "failed",
+    reason: "disk",
+    phase: commitBegan ? "commit" : "gather",
+    retryable: false,
+    partialWrite: commitBegan,
+  };
+}
+
+function admissionFailure(error: unknown): CatalogDisposition {
+  const message = error instanceof Error ? error.message : "";
+  if (message.includes("config generation is busy") || message.includes("config generation is database")) {
+    return { status: "skipped", reason: "busy", retryable: true };
+  }
+  return unexpectedCatalogFailure(false);
+}
+
+/** Project catalog work into the shared no-change/not-evaluated outcome shape. */
+export function projectCatalogOnlyOutcome({
+  changed,
+  catalogRefresh,
+}: ProjectCatalogOnlyOutcomeInput): CatalogOnlyOutcome {
+  const history = notEvaluatedHistory();
+  return {
+    kind: "catalog-only",
+    changed,
+    observed: notEvaluatedObserved(history),
+    catalogRefresh,
+    history,
+  };
+}
+
+/**
+ * Bind the management callback's exact config authority to a catalog-only
+ * funnel. This module is intentionally not re-exported by a public Codex facade.
+ */
+export function createManagementConvergeCodex(
+  config: Readonly<OcxConfig>,
+): ConvergeCodex {
+  const retainedConfig = config;
+  return async request => {
+    let commitBegan = false;
+    try {
+      if (request.scope !== "catalog" || request.action !== "converge") {
+        return projectCatalogOnlyOutcome({
+          changed: false,
+          catalogRefresh: unexpectedCatalogFailure(false),
+        });
+      }
+      const snapshot = captureCatalogAdmissionSnapshot(retainedConfig);
+      const result = await convergeCodexCatalog(snapshot, request, {
+        onCommitBegin: () => { commitBegan = true; },
+      });
+      return projectCatalogOnlyOutcome(result);
+    } catch (error) {
+      return projectCatalogOnlyOutcome({
+        changed: false,
+        catalogRefresh: commitBegan ? unexpectedCatalogFailure(true) : admissionFailure(error),
+      });
+    }
+  };
+}

package/src/codex/model-cache.ts

@@ -0,0 +1,267 @@
+/**
+ * In-memory, per-provider TTL cache for live `/models` results.
+ *
+ * Ported in spirit from jawcode's packages/ai/src/model-manager.ts (the "always load the latest
+ * model list" resolver): live fetch when the cache is stale, serve the cache while it is fresh,
+ * and fall back to the last-known-good list when a live fetch fails. The Remodex proxy is a single
+ * long-running process and the on-disk Codex catalog already persists the last sync across
+ * restarts, so an in-memory cache is sufficient here (no SQLite layer needed).
+ */
+import type { CatalogModel } from "./catalog";
+import type { GenerationContext } from "../lib/state-store-sweeper";
+import { enforceAppOwnedMemoryBudget, type RetainedStoreSnapshot } from "../lib/app-owned-memory";
+
+/** Default freshness window. Matches Codex's own 5-min models cache so the two stay in step. */
+export const DEFAULT_MODEL_CACHE_TTL_MS = 5 * 60 * 1000;
+
+interface CacheEntry {
+  models: CatalogModel[];
+  fetchedAt: number;
+  sizeBytes: number;
+}
+
+export type ProviderModelDiscoveryFailureReason =
+  | "http"
+  | "blocked"
+  | "invalid_response"
+  | "network"
+  | "provider";
+
+export type ProviderModelDiscoveryStatus =
+  | { status: "ok" }
+  | { status: "failed"; reason: "http"; httpStatus: number }
+  | {
+      status: "failed";
+      reason: Exclude<ProviderModelDiscoveryFailureReason, "http">;
+      httpStatus?: never;
+    };
+
+export type ProviderModelDiscoveryFailure = ProviderModelDiscoveryStatus extends infer Status
+  ? Status extends { status: "failed" }
+    ? Omit<Status, "status">
+    : never
+  : never;
+
+/** Whether clearing cache rows also revokes in-flight discovery authority. */
+export type ModelCacheClearReason = "authority" | "eviction";
+
+const cache = new Map<string, CacheEntry>();
+let globalCacheGeneration = 0;
+const providerCacheGenerations = new Map<string, number>();
+let cacheBytes = 0;
+let oldestCachedProvider: string | undefined;
+let oldestCachedAt: number | null = null;
+const modelCacheEncoder = new TextEncoder();
+
+function recomputeOldestCachedProvider(): void {
+  oldestCachedProvider = undefined;
+  oldestCachedAt = null;
+  for (const [provider, entry] of cache) {
+    if (oldestCachedAt !== null && entry.fetchedAt >= oldestCachedAt) continue;
+    oldestCachedProvider = provider;
+    oldestCachedAt = entry.fetchedAt;
+  }
+}
+
+function deleteCachedProvider(provider: string): number {
+  const entry = cache.get(provider);
+  if (!entry) return 0;
+  cache.delete(provider);
+  cacheBytes = Math.max(0, cacheBytes - entry.sizeBytes);
+  if (oldestCachedProvider === provider) recomputeOldestCachedProvider();
+  return entry.sizeBytes;
+}
+
+/** Cooldown after a failed live `/models` fetch, so a dead/unreachable provider doesn't re-pay
+ * the full fetch timeout on every catalog poll (issue #54: UI stalls behind corporate proxies). */
+export const MODELS_FETCH_FAILURE_COOLDOWN_MS = 30_000;
+
+const failureAt = new Map<string, number>();
+const discoveryStatus = new Map<string, ProviderModelDiscoveryStatus>();
+/**
+ * How many models the last successful discovery actually returned, before any configured-alias
+ * augmentation or custom-model merge. Consumers cannot recover this by subtracting known custom
+ * ids: a custom id that later also appears upstream would make a real live catalog look
+ * custom-only, and the provider's configured fallback would wrongly stay authoritative.
+ */
+const liveModelCounts = new Map<string, number>();
+let lastReconciledGeneration = 0;
+
+export function markModelsFetchFailure(provider: string, now = Date.now()): void {
+  failureAt.set(provider, now);
+}
+
+/** `liveModelCount` is required so a caller that forgets to pass it fails typecheck instead of
+ * silently recording zero and misclassifying the provider as having no live catalog. */
+export function markProviderDiscoveryOk(provider: string, liveModelCount: number): void {
+  discoveryStatus.set(provider, { status: "ok" });
+  liveModelCounts.set(provider, Math.max(0, Math.floor(liveModelCount)));
+}
+
+export function markProviderDiscoveryFailed(
+  provider: string,
+  failure: ProviderModelDiscoveryFailure,
+): void {
+  discoveryStatus.set(provider, { status: "failed", ...failure });
+}
+
+/**
+ * Decide whether a discovery FAILURE should be logged, to avoid flooding the log with an identical
+ * warning on every poll (#395: an anthropic-adapter baseUrl without `/v1/models`, e.g. Azure AI
+ * Foundry, returns HTTP 404 forever; the 30s cooldown re-probes and previously re-logged each time).
+ *
+ * Returns true only when the failure SIGNATURE changed since the last observed status — i.e. the
+ * previous state was ok/undefined, or a different reason/httpStatus. Repeated identical failures
+ * stay observable through `getProviderDiscoveryStatus()` / the providers API without log spam.
+ * Call this BEFORE `markProviderDiscoveryFailed` so it can see the prior state.
+ */
+export function shouldLogDiscoveryFailure(
+  provider: string,
+  failure: ProviderModelDiscoveryFailure,
+): boolean {
+  const prev = discoveryStatus.get(provider);
+  if (!prev || prev.status !== "failed") return true;
+  if (prev.reason !== failure.reason) return true;
+  if (prev.reason === "http" && failure.reason === "http") {
+    return prev.httpStatus !== failure.httpStatus;
+  }
+  return false;
+}
+
+export function clearProviderDiscoveryStatus(provider: string): void {
+  discoveryStatus.delete(provider);
+  liveModelCounts.delete(provider);
+}
+
+export function getProviderDiscoveryStatus(provider: string): ProviderModelDiscoveryStatus | undefined {
+  return discoveryStatus.get(provider);
+}
+
+/** Undefined when discovery has never succeeded for this provider. A failed refresh keeps the
+ * last successful count so a stale catalog is still recognised as live-origin. */
+export function getProviderLiveModelCount(provider: string): number | undefined {
+  return liveModelCounts.get(provider);
+}
+
+export function isModelsFetchCoolingDown(provider: string, cooldownMs = MODELS_FETCH_FAILURE_COOLDOWN_MS, now = Date.now()): boolean {
+  const at = failureAt.get(provider);
+  return at !== undefined && now - at < cooldownMs;
+}
+
+/** Fresh cached models for a provider, or null when absent/stale (caller should re-fetch). */
+export function getFreshCached(provider: string, ttlMs: number, now = Date.now()): CatalogModel[] | null {
+  const entry = cache.get(provider);
+  if (!entry) return null;
+  return now - entry.fetchedAt < ttlMs ? entry.models : null;
+}
+
+/** Last-known-good models regardless of age — the fallback when a live fetch fails. */
+export function getStaleCached(provider: string): CatalogModel[] | null {
+  return cache.get(provider)?.models ?? null;
+}
+
+/** Capture the cache generation before an asynchronous provider discovery starts. */
+export function captureModelCacheGeneration(provider: string): string {
+  if (!providerCacheGenerations.has(provider)) providerCacheGenerations.set(provider, 0);
+  return `${globalCacheGeneration}:${providerCacheGenerations.get(provider)!}`;
+}
+
+/** Whether a discovery started under {@link captureModelCacheGeneration} may still write. */
+export function isModelCacheGenerationCurrent(provider: string, generation: string): boolean {
+  return generation === captureModelCacheGeneration(provider);
+}
+
+/**
+ * Store a live result unless the cache was cleared while that asynchronous discovery was running.
+ * The optional generation keeps existing direct cache writers unchanged while discovery callers can
+ * prevent a previous OAuth account from repopulating the current account's cache.
+ */
+export function setCached(
+  provider: string,
+  models: CatalogModel[],
+  now = Date.now(),
+  generation?: string,
+): boolean {
+  if (generation !== undefined && !isModelCacheGenerationCurrent(provider, generation)) return false;
+  deleteCachedProvider(provider);
+  const sizeBytes = modelCacheEncoder.encode(provider).byteLength
+    + modelCacheEncoder.encode(JSON.stringify(models)).byteLength;
+  cache.set(provider, { models, fetchedAt: now, sizeBytes });
+  cacheBytes += sizeBytes;
+  if (oldestCachedAt === null || now < oldestCachedAt) {
+    oldestCachedProvider = provider;
+    oldestCachedAt = now;
+  }
+  enforceAppOwnedMemoryBudget();
+  return true;
+}
+
+/** Drop one provider's cache (or all) so the next resolve forces a live re-fetch. */
+export function clearModelCache(
+  provider?: string,
+  reason: ModelCacheClearReason = "authority",
+): void {
+  const revokesInFlightDiscovery = reason === "authority";
+  if (provider) {
+    if (revokesInFlightDiscovery) {
+      providerCacheGenerations.set(provider, (providerCacheGenerations.get(provider) ?? 0) + 1);
+    }
+    deleteCachedProvider(provider);
+    failureAt.delete(provider);
+    discoveryStatus.delete(provider);
+    liveModelCounts.delete(provider);
+  } else {
+    if (revokesInFlightDiscovery) globalCacheGeneration += 1;
+    cache.clear();
+    cacheBytes = 0;
+    oldestCachedProvider = undefined;
+    oldestCachedAt = null;
+    failureAt.clear();
+    discoveryStatus.clear();
+    liveModelCounts.clear();
+  }
+}
+
+export function reconcileModelCacheProviders(
+  validProviders: ReadonlySet<string>,
+  generation = lastReconciledGeneration + 1,
+): number {
+  if (generation <= lastReconciledGeneration) return 0;
+  const removedProviders = new Set<string>();
+  const trackedProviders = new Set([
+    ...providerCacheGenerations.keys(),
+    ...failureAt.keys(),
+    ...discoveryStatus.keys(),
+    ...liveModelCounts.keys(),
+    ...cache.keys(),
+  ]);
+  for (const provider of trackedProviders) {
+    if (validProviders.has(provider)) continue;
+    providerCacheGenerations.set(provider, (providerCacheGenerations.get(provider) ?? 0) + 1);
+    deleteCachedProvider(provider);
+    failureAt.delete(provider);
+    discoveryStatus.delete(provider);
+    liveModelCounts.delete(provider);
+    removedProviders.add(provider);
+  }
+  lastReconciledGeneration = generation;
+  return removedProviders.size;
+}
+
+export function reconcileModelCacheGeneration(context: GenerationContext): number {
+  return reconcileModelCacheProviders(context.providerNames, context.generation);
+}
+
+export function modelCacheRetainedStoreSnapshot(): RetainedStoreSnapshot {
+  return {
+    count: cache.size,
+    bytes: cacheBytes,
+    evictableBytes: cacheBytes,
+    pinnedBytes: 0,
+    oldestAt: oldestCachedAt,
+  };
+}
+
+export function evictOldestModelCacheForBudget(): number {
+  return oldestCachedProvider === undefined ? 0 : deleteCachedProvider(oldestCachedProvider);
+}

package/src/codex/native-main-admission.ts

@@ -0,0 +1,47 @@
+import type { AdmissionLease } from "../lib/admission";
+import {
+  tryAcquireNativeMainProfileClaim as tryAcquireLifecycleNativeMainProfileClaim,
+  tryClaimNativeMainProfileForTurn as tryClaimLifecycleNativeMainProfileForTurn,
+} from "../server/lifecycle";
+import { isNativeMainTrafficBlocked } from "./native-profile-startup";
+
+export interface NativeMainTurnClaimDeps {
+  /** Test seams for the synchronous precheck/claim/postcheck transition. */
+  isTrafficBlocked?: typeof isNativeMainTrafficBlocked;
+  claimTurn?: typeof tryClaimLifecycleNativeMainProfileForTurn;
+}
+
+/**
+ * Admit a physical native-main credential read on an existing turn.
+ *
+ * Lifecycle admission owns the scoped switch/shutdown fence while the startup
+ * gate owns retained journal/manual recovery. Keep their composition here so
+ * low-level server lifecycle code does not import NativeProfileManager through
+ * native-profile-startup and create a fragile dependency cycle.
+ */
+export function tryClaimNativeMainProfileForTurn(
+  lease?: AdmissionLease,
+  deps: NativeMainTurnClaimDeps = {},
+): boolean {
+  const isBlocked = deps.isTrafficBlocked ?? isNativeMainTrafficBlocked;
+  const claimTurn = deps.claimTurn ?? tryClaimLifecycleNativeMainProfileForTurn;
+  if (isBlocked()) return false;
+  if (!claimTurn(lease)) return false;
+  if (!isBlocked()) return true;
+
+  // Recovery became visible between the precheck and lifecycle claim. This
+  // request must not read auth.json. Keep the caller-owned turn claimed until
+  // normal request cleanup: optional routed work may continue, and releasing
+  // the whole turn here would let shutdown/profile switching overlap it.
+  return false;
+}
+
+/** Acquire standalone ownership only when both native-main gates admit work. */
+export function tryAcquireNativeMainProfileClaim(): AdmissionLease | null {
+  if (isNativeMainTrafficBlocked()) return null;
+  const claim = tryAcquireLifecycleNativeMainProfileClaim();
+  if (!claim) return null;
+  if (!isNativeMainTrafficBlocked()) return claim;
+  claim.release();
+  return null;
+}