@bitkyc08/opencodex 2.59.0 → 2.61.0-preview.20260922

package/src/cli/stop-report.ts

@@ -0,0 +1,143 @@
+/**
+ * Structured summary for `ocx stop --json` (D4 of the app runtime ownership unit).
+ *
+ * The desktop shell drives the real `ocx stop` as a child process so the receipt-backed
+ * teardown, the drain, the Windows respawn verification and the client-config restore run
+ * exactly as they do from a terminal. This module makes that run's RESULT readable from
+ * outside: a StopRunRecord is threaded through the existing stop path in
+ * src/cli/index.ts (the same booleans that already decide the exit code), and
+ * summarizeStopRun turns it into one versioned JSON document.
+ *
+ * Nothing here re-decides anything. If a field of the record is wrong, the fix belongs
+ * in the stop path, not in the summarizer.
+ */
+import { STOP_HISTORY_DEFERRED_EXIT_CODE } from "../update/stop-contract.mjs";
+
+/** Wire version of the stop summary document. */
+export const STOP_SUMMARY_SCHEMA = "ocx-stop/1";
+
+export type StopServiceOutcome =
+  | "absent"
+  | "stopped"
+  | "stopped-respawnable"
+  | "failed"
+  | "state-unknown"
+  | "error";
+
+export type StopProxyOutcome =
+  | "stopped"
+  | "stopped-orphan"
+  | "not-running"
+  | "stop-failed"
+  | "ownership-refused"
+  | "unresolvable-pid"
+  | "respawned"
+  | "unknown";
+
+export type StopSharedTeardownOutcome =
+  | "restored"
+  | "performed-by-proxy"
+  | "refused"
+  | "failed"
+  | "skipped";
+
+/** Facts recorded where the stop path already decides them. */
+export interface StopRunRecord {
+  /** What stopServiceIfInstalledDetailed returned, or "error" when it threw. */
+  service: StopServiceOutcome;
+  /** Which proxy path ran and how it ended. */
+  proxy: StopProxyOutcome;
+  /** Who ended up restoring shared client config (native Codex + Grok). */
+  sharedTeardown: StopSharedTeardownOutcome;
+  /** An inherited pending-teardown receipt blocked the restore. */
+  inheritedTeardownBlocks: boolean;
+  /** A discharged receipt could not be removed from disk. */
+  receiptClearFailed: boolean;
+}
+
+/** The internal booleans that already pick the process exit code. */
+export interface StopRunSignals {
+  failed: boolean;
+  historyOnly: boolean;
+  historyDeferred: boolean;
+  exitCode: number;
+}
+
+export interface StopSummaryJson {
+  schema: typeof STOP_SUMMARY_SCHEMA;
+  /** Strict exit-code view: true only for exit 0. */
+  ok: boolean;
+  outcome: "stopped" | "not-running" | "history-incomplete" | "history-deferred" | "failed";
+  exitCode: number;
+  /** True when this stop left no proxy of this home running by its own paths. */
+  runtimeDown: boolean;
+  service: StopServiceOutcome;
+  proxy: StopProxyOutcome;
+  sharedTeardown: StopSharedTeardownOutcome;
+  /** One stable human-readable line for a caller's UI. */
+  message: string;
+}
+
+/** What handleStop returns: the pre-existing boolean plus the structured twin. */
+export interface StopOutcome {
+  /**
+   * The exact boolean the stop path returned before summaries existed (!stopFailed).
+   * It is NOT the same as summary.ok: 79/80 stops return true here, because the
+   * downtime warning that keys on it applies whenever the runtime went down.
+   */
+  ok: boolean;
+  summary: StopSummaryJson;
+}
+
+function stopOutcome(record: StopRunRecord, signals: StopRunSignals): StopSummaryJson["outcome"] {
+  if (signals.failed) return "failed";
+  if (signals.historyOnly) return "history-incomplete";
+  if (signals.historyDeferred) {
+    // The deferred exit code is a proven claim; anything else means another obligation
+    // was sitting in the home, which the exit-code logic already reports as failure.
+    return signals.exitCode === STOP_HISTORY_DEFERRED_EXIT_CODE ? "history-deferred" : "failed";
+  }
+  if (record.proxy === "not-running") return "not-running";
+  if (record.proxy === "stopped" || record.proxy === "stopped-orphan") return "stopped";
+  return "failed";
+}
+
+function stopMessage(record: StopRunRecord, signals: StopRunSignals, outcome: StopSummaryJson["outcome"]): string {
+  if (record.proxy === "respawned") return "The proxy was respawned after the stop; it is still running.";
+  if (record.proxy === "ownership-refused") return "The proxy refused the stop; it belongs to a different opencodex home.";
+  if (record.proxy === "unresolvable-pid") return "A proxy is answering, but its process id could not be resolved, so it was not stopped.";
+  if (record.proxy === "stop-failed") return "The proxy process could not be stopped.";
+  if (record.service === "failed") return "The installed service manager did not stop and may respawn the proxy.";
+  if (record.service === "state-unknown") return "The service manager state could not be read.";
+  if (record.service === "error") return "Stopping the installed service failed.";
+  if (record.inheritedTeardownBlocks) return "An earlier stop left an outstanding shared teardown that could not be confirmed.";
+  if (record.sharedTeardown === "failed") return "The shared teardown failed; client configuration may still point at the stopped proxy.";
+  if (record.receiptClearFailed) return "The shared teardown finished, but its receipt could not be removed.";
+  if (record.sharedTeardown === "refused") return "The shared teardown was refused before it changed anything; it is still owed.";
+  if (signals.historyOnly) return "The proxy stopped; Codex history cleanup did not complete.";
+  if (outcome === "history-deferred") return "The proxy stopped; the shared teardown was deferred and is still owed.";
+  if (outcome === "not-running") return "No proxy was running.";
+  if (outcome === "stopped") return "The proxy stopped.";
+  return "The stop failed.";
+}
+
+/** Pure mapper from the recorded run to the wire document. */
+export function summarizeStopRun(record: StopRunRecord, signals: StopRunSignals): StopSummaryJson {
+  const outcome = stopOutcome(record, signals);
+  return {
+    schema: STOP_SUMMARY_SCHEMA,
+    ok: signals.exitCode === 0,
+    outcome,
+    exitCode: signals.exitCode,
+    runtimeDown: record.proxy === "stopped" || record.proxy === "stopped-orphan" || record.proxy === "not-running",
+    service: record.service,
+    proxy: record.proxy,
+    sharedTeardown: record.sharedTeardown,
+    message: stopMessage(record, signals, outcome),
+  };
+}
+
+/** Emit the summary as exactly one JSON document on stdout. */
+export function printStopSummary(summary: StopSummaryJson, stdout: { log: (s: string) => void } = console): void {
+  stdout.log(JSON.stringify(summary));
+}

package/src/cli/uninstall-plan.ts

@@ -84,3 +84,12 @@ export function everyEndpointProvenDown(
   if (endpoints.length === 0) return false;
   return endpoints.every(e => probe(e) === "dead");
 }
+
+export async function everyEndpointProvenDownAsync(
+  endpoints: readonly ProbeEndpoint[],
+  probe: (e: ProbeEndpoint) => Promise<"live" | "dead" | "unknown"> | "live" | "dead" | "unknown",
+): Promise<boolean> {
+  if (endpoints.length === 0) return false;
+  const results = await Promise.all(endpoints.map(e => probe(e)));
+  return results.every(result => result === "dead");
+}

package/src/client/machine-api.ts

@@ -23,7 +23,7 @@ export interface MachineStatusV1 {
 export interface MachineApiDeps {
   sync: typeof syncConnectedClient;
   disconnect: typeof disconnectClient;
-  scheduleStandaloneRecycle: () => void;
+  scheduleStandaloneRecycle: (disconnectedTokenFingerprint: string) => void;
   hubReachability?: () => HubReachability;
   setHubReachability?: (value: HubReachability) => void;
 }
@@ -130,7 +130,7 @@ export async function handleMachineApi(
     }
     try {
       const result = await deps.disconnect(input.keepCatalog === undefined ? {} : { keepCatalog: input.keepCatalog });
-      deps.scheduleStandaloneRecycle();
+      deps.scheduleStandaloneRecycle(state.tokenFingerprint);
       return Response.json({ success: true, ...result }, { status: 202 });
     } catch (error) {
       return Response.json({ success: false, error: error instanceof Error ? error.message : "disconnect failed" }, { status: 409 });

package/src/client/machine-listener.ts

@@ -1,4 +1,3 @@
-import { readFileSync } from "node:fs";
 import type { Server } from "bun";
 import { loadConfig } from "../config";
 import { browserSecurityHeaders } from "../server/auth-cors";
@@ -16,11 +15,9 @@ import { readClientConnectionState } from "./state";
 import { handleMachineApi, type HubReachability, type MachineApiDeps } from "./machine-api";
 import { MACHINE_GUI_ORIGIN_HEADER, requireMachineAuth } from "./machine-auth";
 import { relayHubManagementRequest } from "./hub-relay";
+import { packageVersion } from "../lib/package-version";
 
-const VERSION = (() => {
-  try { return JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version as string; }
-  catch { return "0.0.0"; }
-})();
+const VERSION = packageVersion("0.0.0");
 const GUI_SPA_PATHS = new Set([
   "/dashboard", "/startup", "/providers", "/models", "/subagents",
   "/logs", "/usage", "/storage", "/codex-set", "/integrations",
@@ -75,8 +72,8 @@ export function startMachineListener(
   const machineApiDeps: MachineApiDeps = {
     sync: deps.machineApi?.sync ?? syncConnectedClient,
     disconnect: deps.machineApi?.disconnect ?? disconnectClient,
-    scheduleStandaloneRecycle: deps.machineApi?.scheduleStandaloneRecycle ?? (() => {
-      void import("./runtime").then(module => module.scheduleStandaloneRecycle());
+    scheduleStandaloneRecycle: deps.machineApi?.scheduleStandaloneRecycle ?? (tokenFingerprint => {
+      void import("./runtime").then(module => module.scheduleStandaloneRecycle(tokenFingerprint));
     }),
     hubReachability: deps.machineApi?.hubReachability ?? (() => hubReachability),
     setHubReachability: deps.machineApi?.setHubReachability ?? (value => { hubReachability = value; }),

package/src/client/runtime.ts

@@ -4,6 +4,7 @@ import { loadConfig } from "../config";
 import { removePid, removeRuntimePort, writePid, writeRuntimePort } from "../config/process-state";
 import { installCrashGuards } from "../lib/crash-guard";
 import { selfLaunchArgv } from "../lib/self-launch-argv";
+import { loadServiceTokenFromFile, serviceApiTokenFingerprint } from "../lib/service-secrets";
 import { findAvailablePort } from "../server/ports";
 import { startMachineListener } from "./machine-listener";
 import { readClientConnectionState } from "./state";
@@ -17,7 +18,30 @@ function cleanup(): void {
   removeRuntimePort(process.pid);
 }
 
-export function scheduleStandaloneRecycle(): void {
+export function standaloneRecycleEnv(
+  env: NodeJS.ProcessEnv,
+  disconnectedTokenFingerprint: string,
+): NodeJS.ProcessEnv {
+  const childEnv = { ...env };
+  const admissionToken = childEnv.OPENCODEX_API_AUTH_TOKEN?.trim();
+  if (admissionToken && serviceApiTokenFingerprint(admissionToken) !== disconnectedTokenFingerprint) {
+    // A surviving env token shadows OCX_API_TOKEN_FILE entirely, so nothing below can
+    // reintroduce the disconnected token.
+    return childEnv;
+  }
+  if (admissionToken) delete childEnv.OPENCODEX_API_AUTH_TOKEN;
+  // The respawned `ocx start` loads OCX_API_TOKEN_FILE into OPENCODEX_API_AUTH_TOKEN when the
+  // env token is absent, so vet the file by content: drop the pointer when it is unreadable or
+  // holds the disconnected token, keep it when it holds a different operator credential.
+  if (!childEnv.OCX_API_TOKEN_FILE?.trim()) return childEnv;
+  const fileToken = loadServiceTokenFromFile(childEnv);
+  if (fileToken === null || serviceApiTokenFingerprint(fileToken) === disconnectedTokenFingerprint) {
+    delete childEnv.OCX_API_TOKEN_FILE;
+  }
+  return childEnv;
+}
+
+export function scheduleStandaloneRecycle(disconnectedTokenFingerprint: string): void {
   if (recycleScheduled) return;
   recycleScheduled = true;
   const timer = setTimeout(() => {
@@ -46,7 +70,7 @@ export function scheduleStandaloneRecycle(): void {
         detached: true,
         stdio: "ignore",
         windowsHide: true,
-        env: { ...process.env },
+        env: standaloneRecycleEnv(process.env, disconnectedTokenFingerprint),
       });
       child.unref();
     }

package/src/clients/aside-profiles.ts

@@ -201,6 +201,7 @@ export function guardAsideProfileIO(profile: AsideProfile, io: IntegrationIO, pr
   const selected = { ...profile };
   const registered = registeredProfiles(selected, profiles).map(peer => ({ ...peer }));
   const captured = boundary(selected, registered, false);
+  const lstatProbe = io.lstatKind;
   function check(path: string, directory: boolean, mutation: boolean): void {
     if (path !== (directory ? selected.detectDir : selected.configPath)) {
       refuse("IO attempted to access a different account path.");
@@ -214,6 +215,9 @@ export function guardAsideProfileIO(profile: AsideProfile, io: IntegrationIO, pr
   return {
     readText: path => { check(path, false, false); return io.readText(path); },
     statKind: path => { check(path, path === selected.detectDir, false); return io.statKind(path); },
+    ...(lstatProbe
+      ? { lstatKind: (path: string) => { check(path, path === selected.detectDir, false); return lstatProbe(path); } }
+      : {}),
     writeText: (path, text) => { check(path, false, true); io.writeText(path, text); },
     removeFile: path => { check(path, false, true); io.removeFile(path); },
     mkdirp: path => { check(path, true, true); io.mkdirp(path); },

package/src/clients/config-export/zcode-store.ts

@@ -0,0 +1,157 @@
+// ZCode personal provider store export.
+import type { ExportContext, ManagedContribution, ManagedFragment } from "./contracts";
+import { authoritativeContextWindow, inputModalitiesForClient, normalizeExportModels } from "./model-metadata";
+import { OPENCODE_PROVIDER_ID, LOOPBACK_API_KEY_PLACEHOLDER } from "./constants";
+import { formatSelectorConjunction } from "../../integrations/merge";
+
+/**
+ * The file ZCode 3.14 and later actually read their custom providers from.
+ *
+ * `v2/config.json` — the file {@link buildZcodeContribution} writes — is still
+ * parsed by this client, but only by a one-shot `importLegacy` hook that runs
+ * when this store is missing. The client creates the store on first launch, so
+ * on any install that has ever run the import is already spent and a later
+ * write to the old file is read by nobody (#5348).
+ *
+ * The shape below is the client's own, quoted from the report that opened
+ * #5348: it is what the client's `importLegacyPersonalProviderConfig` produced
+ * when it migrated this project's block, so it is observed output rather than a
+ * schema this project invented. Everything the client persists that we have not
+ * seen it derive from our block is deliberately absent — an omitted field is a
+ * field the client still owns.
+ */
+export const ZCODE_STORE_SCHEMA_VERSION = 1;
+
+/**
+ * `group` places the provider among the user's own personal providers rather
+ * than the builtin list the client ships and rewrites. `api.type` is the same
+ * choice `kind: "openai"` makes in the legacy block: the OpenAI Responses
+ * protocol, which is the only surface this proxy speaks natively.
+ */
+export const ZCODE_STORE_PROVIDER_GROUP = "standard-personal";
+export const ZCODE_STORE_API_TYPE = "openai-responses";
+export const ZCODE_STORE_PROVIDER_NAME = "OpenCodex";
+
+/** Where the store keeps one rule per provider, and one per (provider, model). */
+export const ZCODE_STORE_PROVIDER_RULES_PATH = ["config", "providerConfigRules", "providerRules"] as const;
+export const ZCODE_STORE_MODEL_RULES_PATH = ["config", "modelConfigRules", "providerModelRules"] as const;
+
+export interface ZcodeStoreProviderRule {
+  providerId: string;
+  enabled: true;
+  providerName: string;
+  config: {
+    group: string;
+    access: { apiKey: string };
+    api: { type: string; baseUrl: string };
+    personalModelIds: string[];
+    modelOrder: string[];
+  };
+}
+
+export interface ZcodeStoreModelRule {
+  providerId: string;
+  modelId: string;
+  config: { properties: { contextWindow: number } };
+}
+
+/**
+ * Is this document a store whose schema we can write?
+ *
+ * Only the one version whose shape has been observed. A store carrying any
+ * other `schemaVersion` — or none, or a document that is not an object — is a
+ * file we cannot merge into without asserting a nesting we have never seen,
+ * and a wrong assertion there does not fail loudly: it replaces the provider
+ * list the user keeps in the same file. The integration reports the write as
+ * ineffective in that case instead of guessing.
+ */
+export function zcodeStoreSchemaEstablished(parsed: unknown): boolean {
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return false;
+  return (parsed as Record<string, unknown>).schemaVersion === ZCODE_STORE_SCHEMA_VERSION;
+}
+
+/**
+ * The selector addressing one model rule, or null when the id cannot be spelled.
+ *
+ * A rule is identified by the PAIR, so both fields are named: a selector
+ * carrying only the model would match another provider's rule for the same
+ * model. The conjunction grammar reserves `,` and `]`, and a model id holding
+ * either cannot be addressed unambiguously — that row ships without its
+ * context window rather than with a selector that points somewhere else.
+ */
+function modelRuleSelector(modelId: string): string | null {
+  return formatSelectorConjunction([
+    { field: "providerId", value: OPENCODE_PROVIDER_ID },
+    { field: "modelId", value: modelId },
+  ]);
+}
+
+/** The rows this export publishes, filtered exactly as the legacy block filters them. */
+function storeModels(ctx: ExportContext): string[] {
+  const ids: string[] = [];
+  for (const model of normalizeExportModels(ctx.models)) {
+    if (inputModalitiesForClient("pi", model.inputModalities) === null) continue;
+    ids.push(model.namespaced);
+  }
+  return ids;
+}
+
+/**
+ * The provider rule the client reads, built from the same context the legacy
+ * block is built from.
+ *
+ * `baseUrl` carries the `/v1` root for the same reason the legacy block does:
+ * this client appends `/responses` for the Responses protocol, so requests land
+ * on `/v1/responses`. The serialized credential is always the non-secret
+ * loopback placeholder.
+ */
+export function buildZcodeStoreProviderRule(ctx: ExportContext): ZcodeStoreProviderRule {
+  const ids = storeModels(ctx);
+  return {
+    providerId: OPENCODE_PROVIDER_ID,
+    enabled: true,
+    providerName: ZCODE_STORE_PROVIDER_NAME,
+    config: {
+      group: ZCODE_STORE_PROVIDER_GROUP,
+      access: { apiKey: LOOPBACK_API_KEY_PLACEHOLDER },
+      api: { type: ZCODE_STORE_API_TYPE, baseUrl: `${ctx.baseUrl.replace(/\/v1\/?$/, "")}/v1` },
+      personalModelIds: ids,
+      /*
+       * The client persists the picker order separately from membership. Ours is
+       * the catalog order the rest of this export already sorts by, so a refresh
+       * that adds a model puts it where every other surface puts it.
+       */
+      modelOrder: [...ids],
+    },
+  };
+}
+
+/**
+ * Everything this project owns inside the store: one provider rule, plus one
+ * model rule per row that has an authoritative context window.
+ *
+ * A row without one ships no model rule at all, which is the same
+ * authoritative-window rule the legacy block follows — an emitted stand-in
+ * would be a guessed capability. Reasoning ladders have no counterpart here
+ * that this project has observed the client produce, so none is written.
+ */
+export function buildZcodeStoreContribution(ctx: ExportContext): ManagedContribution {
+  const fragments: ManagedFragment[] = [{
+    path: [...ZCODE_STORE_PROVIDER_RULES_PATH, `[providerId=${OPENCODE_PROVIDER_ID}]`],
+    value: buildZcodeStoreProviderRule(ctx),
+  }];
+  for (const model of normalizeExportModels(ctx.models)) {
+    if (inputModalitiesForClient("pi", model.inputModalities) === null) continue;
+    const contextWindow = authoritativeContextWindow(model.contextWindow);
+    if (contextWindow === undefined) continue;
+    const selector = modelRuleSelector(model.namespaced);
+    if (selector === null) continue;
+    const rule: ZcodeStoreModelRule = {
+      providerId: OPENCODE_PROVIDER_ID,
+      modelId: model.namespaced,
+      config: { properties: { contextWindow } },
+    };
+    fragments.push({ path: [...ZCODE_STORE_MODEL_RULES_PATH, selector], value: rule });
+  }
+  return { clientId: "zcode", fragments };
+}

package/src/clients/config-export.ts

@@ -35,6 +35,18 @@ export { OPENCODE_PROVIDER_ID, OPENCODE_CONFIG_SCHEMA, OPENCODE_API_KEY_ENV, OPE
 export { normalizeExportModels } from "./config-export/model-metadata";
 export type { OmpModelEntry, OmpProviderBlock, OmpGeneratedConfig } from "./config-export/omp";
 export type { ZcodeModelEntry, ZcodeProviderBlock, ZcodeGeneratedConfig } from "./config-export/zcode";
+export type { ZcodeStoreProviderRule, ZcodeStoreModelRule } from "./config-export/zcode-store";
+export {
+  ZCODE_STORE_SCHEMA_VERSION,
+  ZCODE_STORE_PROVIDER_GROUP,
+  ZCODE_STORE_API_TYPE,
+  ZCODE_STORE_PROVIDER_NAME,
+  ZCODE_STORE_PROVIDER_RULES_PATH,
+  ZCODE_STORE_MODEL_RULES_PATH,
+  buildZcodeStoreProviderRule,
+  buildZcodeStoreContribution,
+  zcodeStoreSchemaEstablished,
+} from "./config-export/zcode-store";
 export type { DshReasoningEffort, DshWireReasoningEffort, DshModelEntry, DshProviderBlock, DshGeneratedConfig } from "./config-export/dsh";
 export type { McodeProviderBlock, McodeModelEntry, McodeGeneratedConfig } from "./config-export/mcode";
 export type { RaycastAbility, RaycastAbilityName, RaycastModelEntry, RaycastProviderEntry, RaycastGeneratedConfig } from "./config-export/raycast";
@@ -447,6 +459,30 @@ export function zcodeConfigPath(env: OpencodeLaunchEnv = process.env, home: stri
   return join(zcodeHomeDir(env, home), "v2", "config.json");
 }
 
+/**
+ * The provider store a current ZCode reads, which is NOT the file above.
+ *
+ * ZCode 3.14 moved custom providers to `v2/provider_config.json` and left
+ * `v2/config.json` reachable only through a one-shot import that runs when the
+ * new file is missing. The client creates the new file on first launch, so on
+ * 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
+ * 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
+ * reason `ZCODE_DATA_DIR` refuses one: we and the client would disagree about
+ * 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 {
+  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");
+}
+
 /**
  * Prime Agent resolves its agent directory from `PRIME_AGENT_CODING_AGENT_DIR`
  * — the brand-derived spelling of the `PI_CODING_AGENT_DIR` that `ompAgentDir`

package/src/codex/account-store.ts

@@ -370,6 +370,23 @@ export function isCodexAccountGenerationLive(id: string, generation: number): bo
   return !!record?.credential && record.deletedAt == null && record.generation === generation;
 }
 
+/**
+ * The same verdict as {@link isCodexAccountGenerationLive}, over ONE store load.
+ *
+ * `readCodexAccountRecord` is `loadCodexAccountRecordStore()[id]`, so asking it per row
+ * reloads, reparses and renormalizes the whole file per row — the exact shape
+ * {@link loadCodexAccountRecordSnapshot} was added to avoid. The denial reader resolves
+ * several accounts in one synchronous pass on the request path, so it opens one checker and
+ * closes over the snapshot instead.
+ */
+export function beginCodexAccountGenerationLiveCheck(): (id: string, generation: number) => boolean {
+  const snapshot = loadCodexAccountRecordSnapshot();
+  return (id, generation) => {
+    const record = snapshot[id];
+    return !!record?.credential && record.deletedAt == null && record.generation === generation;
+  };
+}
+
 export function saveCodexAccountCredentialIfGeneration(
   id: string,
   generation: number,
@@ -596,6 +613,41 @@ function withCredentialMutationLockSync<T>(fn: () => T): T {
 }
 
 type CodexTokenResult = { accessToken: string; chatgptAccountId: string; generation: number };
+type CodexRefreshGenerationHandoff = (accountId: string, fromGeneration: number, toGeneration: number) => void;
+// var (hoisted, initialized to undefined) rather than const: a registrar reached
+// through an import cycle can register while this module body is still evaluating,
+// and the lazily created Set must be reachable rather than in the temporal dead zone.
+var refreshGenerationHandoffs: Set<CodexRefreshGenerationHandoff> | undefined;
+function refreshHandoffs(): Set<CodexRefreshGenerationHandoff> {
+  return refreshGenerationHandoffs ??= new Set();
+}
+
+/** Register process-local state that must follow a credential refresh generation. */
+export function registerCodexRefreshGenerationHandoff(handoff: CodexRefreshGenerationHandoff): () => void {
+  const set = refreshHandoffs();
+  set.add(handoff);
+  return () => set.delete(handoff);
+}
+
+/**
+ * Invoke every registered handoff for one committed `fromGeneration` to `toGeneration` move.
+ *
+ * Each listener runs independently and a throw is contained: by the time handoffs run the
+ * rotated credential is already persisted, so a failing listener must not reject the shared
+ * refresh promise (surviving waiters would see a refresh failure that never happened), must
+ * not starve the remaining listeners, and must not block plan reconciliation. The warning
+ * carries no account id or token material — the same scrub refresh error messages get.
+ */
+function dispatchRefreshGenerationHandoffs(accountId: string, fromGeneration: number, toGeneration: number): void {
+  for (const handoff of refreshHandoffs()) {
+    try {
+      handoff(accountId, fromGeneration, toGeneration);
+    } catch (error) {
+      console.warn("[codex-auth] a refresh generation handoff listener failed", error);
+    }
+  }
+}
+
 type CodexRefreshResult = CodexTokenResult & {
   credential?: CodexAccountCredentials;
   /**
@@ -1377,6 +1429,19 @@ async function resolveCodexToken(
    * committed result, for every waiter, including none.
    */
   const refreshPromise = fetchPromise.then(async (result): Promise<CodexRefreshResult> => {
+    // Generation-dependent completion belongs to the flight, not to its initiating
+    // request. The owner may stop waiting after a disconnect while this detached work
+    // still commits G+1; advance process-local affinities before any waiter observes
+    // the result (and even when there are no surviving waiters).
+    if (result.selfRefreshed) {
+      dispatchRefreshGenerationHandoffs(id, result.generation - 1, result.generation);
+      // A propagated alias committed at its OWN generation, so its affinities sit at
+      // alias.generation - 1: without this handoff they fail the exact-generation
+      // liveness check on the very next request that reads them.
+      for (const alias of result.propagatedAliases ?? []) {
+        dispatchRefreshGenerationHandoffs(alias.id, alias.generation - 1, alias.generation);
+      }
+    }
     await notePlanFromRefreshedAccessToken(id, result.accessToken, result.generation);
     // One settlement path for the whole flight: the refreshing account, then any dormant alias that
     // adopted the same rotated JWT. An alias holds the identical access token, so a changed