@bitkyc08/opencodex 2.57.0 → 2.59.0

package/src/cli/runtime-api.ts

@@ -42,10 +42,39 @@ export class RuntimeApiError extends Error {
   }
 }
 
+/**
+ * Refusal for a management request that resolved to a connected-client machine listener.
+ *
+ * A connected client runs `src/client/machine-listener.ts`, which binds the SAME address the
+ * standalone proxy would (`port ?? config.port ?? 10100`) and answers `/healthz` as opencodex.
+ * Liveness therefore finds it — correctly, it is our process — but it serves only
+ * `/api/machine/*` and returns a JSON 404 for every other `/api/*` path. Before this refusal
+ * every management-backed subcommand on such a machine died on that opaque 404:
+ * `{"error":"not_found","method":"PUT","path":"/api/custom-models/<id>"}`, one character away
+ * from the real handler's unknown-id `{"error":"not found"}` and indistinguishable from it
+ * (#4662). The role was already on the wire; only the parser was throwing it away.
+ *
+ * 503 rather than 404: the management plane is unavailable here, the resource is not missing,
+ * and `runCliAction` maps 404 to exit 4 ("no such thing") — the wrong answer to give a script.
+ */
+function clientRoleManagementRefusal(port: number): string {
+  return [
+    `The opencodex listener on port ${port} is running in the client role. It serves only the machine routes (/api/machine/*), so this machine has no management API to call.`,
+    "Custom-model edits and other management changes are made on the hub this machine is connected to: run the command there, or use the hub dashboard (the dashboard on this machine relays to it when the connection uses the relay transport).",
+    "To change this machine's own configuration instead: edit customModels in config.json, then run: ocx sync",
+  ].join("\n");
+}
+
 export async function runtimeBaseUrl(deps: RuntimeApiDeps = {}): Promise<string> {
   if (deps.baseUrl) return deps.baseUrl.replace(/\/$/, "");
   const live = await (deps.findLiveProxy ?? findLiveProxy)();
   if (!live) throw new RuntimeApiError("Proxy is not running. Start it with: ocx start", 503, null);
+  // The role comes from the same identity-checked /healthz body liveness already parsed, so
+  // this costs no extra request. Only the client role is refused: an absent role is a
+  // standalone or hub proxy (or a legacy body that predates the field), and both serve /api/*.
+  if (live.role === "client") {
+    throw new RuntimeApiError(clientRoleManagementRefusal(live.port), 503, null);
+  }
   return `http://${probeHostname(live.hostname)}:${live.port}`;
 }
 
@@ -62,11 +91,26 @@ function stringField(record: Record<string, unknown>, key: string): string | und
  * is unavailable). Both were dropped here, so a fenced management plane was
  * indistinguishable from a generic failure and an operator had no way to tell a port
  * collision from an ACL refusal from a stopped proxy (#2698).
+ *
+ * A 404 body that carries both `method` and `path` is a different statement again: some
+ * opencodex listener answered, and it does not route that request at all. Only the
+ * connected-client machine listener emits that shape today (`json404` in
+ * src/client/machine-listener.ts), and printing its bare `not_found` token read as though the
+ * resource were missing — a real handler's unknown-id 404 says `not found`, one space apart
+ * (#4662). Name the route instead, so any listener that does not serve a path stays legible
+ * even if another one starts answering this way.
  */
 function responseMessage(body: unknown, status: number): string {
   if (typeof body === "string" && body.trim()) return body.trim().slice(0, 400);
   if (!body || typeof body !== "object") return `Management request failed (${status})`;
   const record = body as Record<string, unknown>;
+  if (status === 404) {
+    const method = stringField(record, "method");
+    const path = stringField(record, "path");
+    if (method && path) {
+      return `This opencodex listener does not serve ${method.slice(0, 16)} ${path.slice(0, 200)}, so the request was refused before any handler ran (it is not a missing record). Check that the command is pointed at a proxy that serves the management API.`;
+    }
+  }
   let primary: string | undefined;
   for (const key of ["error", "message", "detail"]) {
     primary = stringField(record, key);

package/src/cli/start-args.ts

@@ -0,0 +1,94 @@
+export const START_USAGE = "Usage: ocx start [--port <port>] [--socks5 [host:port] | --socks5-off]";
+export const START_USAGE_LINE = "ocx start [--port <port>] [--socks5 [host:port] | --socks5-off]";
+export const DEFAULT_SOCKS5_PROXY = "socks5://127.0.0.1:10808";
+
+export class StartArgsError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "StartArgsError";
+  }
+}
+
+export type StartOptions = {
+  port?: number;
+  /** SOCKS5 URL to persist. */
+  socks5?: string;
+  socks5Off?: boolean;
+};
+
+export function isSocksProxyUrl(proxy: string): boolean {
+  return /^socks5h?:\/\//i.test(proxy.trim());
+}
+
+export function normalizeSocks5(raw: string): string {
+  const trimmed = raw.trim();
+  if (!trimmed) return DEFAULT_SOCKS5_PROXY;
+  if (isSocksProxyUrl(trimmed)) {
+    try {
+      const parsed = new URL(trimmed);
+      const port = Number(parsed.port);
+      if (!parsed.hostname || !parsed.port || !Number.isInteger(port) || port <= 0 || port > 65535) {
+        throw new Error("invalid host or port");
+      }
+      return trimmed;
+    } catch {
+      throw new StartArgsError("Invalid SOCKS5 address; expected socks5://host:port");
+    }
+  }
+  if (/^socks4a?:\/\//i.test(trimmed)) {
+    throw new StartArgsError("Only SOCKS5 proxy URLs are supported");
+  }
+  if (/^https?:\/\//i.test(trimmed)) {
+    throw new StartArgsError("SOCKS5 proxy must be socks5://host:port, not an HTTP URL");
+  }
+  if (/^\d+$/.test(trimmed)) {
+    const port = Number(trimmed);
+    if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+      throw new StartArgsError("Invalid SOCKS5 port number");
+    }
+    return `socks5://127.0.0.1:${port}`;
+  }
+  const hostPort = /^(\[[^\]]+\]|[^:]+):(\d+)$/.exec(trimmed);
+  if (hostPort) {
+    const port = Number(hostPort[2]);
+    if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+      throw new StartArgsError("Invalid SOCKS5 port number");
+    }
+    return `socks5://${trimmed}`;
+  }
+  throw new StartArgsError("Invalid SOCKS5 address; expected socks5://host:port");
+}
+
+export function parseStartOptions(argv: string[]): StartOptions {
+  const options: StartOptions = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]!;
+    if (arg === "--port") {
+      const value = argv[++i];
+      const port = value && /^\d+$/.test(value) ? Number(value) : NaN;
+      if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+        throw new StartArgsError("Invalid port number");
+      }
+      options.port = port;
+      continue;
+    }
+    if (arg === "--socks5") {
+      if (options.socks5Off) throw new StartArgsError("--socks5 and --socks5-off cannot be used together");
+      const next = argv[i + 1];
+      if (next && !next.startsWith("-")) {
+        options.socks5 = normalizeSocks5(next);
+        i += 1;
+      } else {
+        options.socks5 = DEFAULT_SOCKS5_PROXY;
+      }
+      continue;
+    }
+    if (arg === "--socks5-off") {
+      if (options.socks5 !== undefined) throw new StartArgsError("--socks5 and --socks5-off cannot be used together");
+      options.socks5Off = true;
+      continue;
+    }
+    throw new StartArgsError(START_USAGE);
+  }
+  return options;
+}

package/src/cli/system-command.ts

@@ -21,6 +21,8 @@ const USAGE = `Usage:
   ocx system codex-app-server [--json]
   ocx system codex-restart --yes [--json]
   ocx system codex-cli-update check [--json]
+  ocx system codex-cli-update attest [--json]
+  ocx system codex-cli-update attest --candidate <absolute-path> --npm-prefix <absolute-path> --npm-cli <absolute-path> --node <absolute-path> [--json]
   ocx system update check [--channel <latest|preview>] [--json]
   ocx system update run [--channel <latest|preview>] [--restart <on|off>] --yes [--json]
   ocx system update status <job-id> [--json]
@@ -42,6 +44,72 @@ async function status(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   printData(result, wantsJson, summaryLines(result));
 }
 
+function recordValue(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" ? value as Record<string, unknown> : undefined;
+}
+
+function desktopSwitchInertReason(reason: unknown): string {
+  if (reason === "client_role") return "this proxy is running in the client role";
+  if (reason === "non_loopback_bind_requires_admission_token") {
+    return "a non-loopback bind requires an admission token, so this flag is inert";
+  }
+  return "the stored setting is not effective in the current runtime configuration";
+}
+
+function desktopSwitchApplyReason(reason: unknown): string {
+  if (reason === "not_requested") return "no desktop switch rewrite was requested";
+  if (reason === "proxy_not_running") return "the proxy is not running";
+  if (reason === "integration_disabled") return "Codex integration is disabled";
+  if (reason === "write_lock_busy") return "the Codex config write lock is busy";
+  if (reason === "injection_refused") return "Codex config injection was refused";
+  return "the rewrite could not be completed";
+}
+
+function settingsUpdateLines(
+  result: unknown,
+  changed: { desktopAuthless: boolean; clientCompaction: boolean },
+): string[] {
+  if (!changed.desktopAuthless && !changed.clientCompaction) return ["System settings updated."];
+  const switches = recordValue(recordValue(result)?.codexDesktopSwitches);
+  if (!switches) return ["System settings updated."];
+
+  const lines: string[] = [];
+  const appendSwitch = (key: string, label: string): boolean => {
+    const state = recordValue(switches[key]);
+    if (!state || typeof state.stored !== "boolean" || typeof state.effective !== "boolean") return false;
+    lines.push(`${label}: stored ${state.stored ? "on" : "off"}.`);
+    // The effective value is always stated, even when it matches. Printing it only on a
+    // mismatch would make silence ambiguous — the reader could not tell "the stored value is
+    // in force" from "this build does not report effective state", and that ambiguity is a
+    // smaller version of the defect being fixed.
+    lines.push(state.effective === state.stored
+      ? `${label}: effective ${state.effective ? "on" : "off"}.`
+      : `${label}: effective ${state.effective ? "on" : "off"} because ${desktopSwitchInertReason(state.inertReason)}.`);
+    return true;
+  };
+
+  if (changed.desktopAuthless && !appendSwitch("codexDesktopAuthless", "Codex desktop authless")) {
+    return ["System settings updated."];
+  }
+  if (changed.clientCompaction && !appendSwitch("codexClientCompaction", "Codex client compaction")) {
+    return ["System settings updated."];
+  }
+
+  const apply = recordValue(switches.apply);
+  const authSource = recordValue(switches.authSource);
+  if (!apply || typeof apply.applied !== "boolean" || !authSource || typeof authSource.summary !== "string") {
+    return ["System settings updated."];
+  }
+  if (apply.applied) {
+    lines.push("Codex config: ~/.codex/config.toml was rewritten.");
+  } else {
+    const detail = typeof apply.detail === "string" && apply.detail.length > 0 ? ` Details: ${apply.detail}` : "";
+    lines.push(`Codex config: ~/.codex/config.toml was not rewritten because ${desktopSwitchApplyReason(apply.reason)}.${detail} Run 'ocx sync' to apply the stored settings.`);
+  }
+  lines.push(`Auth source: ${authSource.summary}`);
+  return lines;
+}
+
 async function settings(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   const args = [...argv];
   const wantsJson = takeFlag(args, "--json");
@@ -63,7 +131,10 @@ async function settings(argv: string[], deps: RuntimeApiDeps): Promise<void> {
     ...(clientCompaction !== undefined ? { codexClientCompaction: clientCompaction } : {}),
   };
   const result = await runtimeRequest("/api/settings", { method: "PUT", body: JSON.stringify(body) }, deps);
-  printData(result, wantsJson, ["System settings updated."]);
+  printData(result, wantsJson, settingsUpdateLines(result, {
+    desktopAuthless: desktopAuthless !== undefined,
+    clientCompaction: clientCompaction !== undefined,
+  }));
 }
 
 async function startup(argv: string[], deps: RuntimeApiDeps): Promise<void> {

package/src/cli/uninstall-client-state.ts

@@ -4,6 +4,7 @@ import { readClientConnectionState, sameClientConnectionOwner } from "../client/
 import { assertClientLifecycleHeld, withClientLifecycle } from "../client/lifecycle-lock";
 import { inspectRemoteDesktopCleanup, readDesktopDisconnectReceipt } from "../claude/desktop-remote-store";
 import { removeOwnedConfigState, type ConfigRemovalResult } from "../lib/config-ownership";
+import { windowsSecretAclReapPendingAtOrBelow } from "../lib/windows-secret-acl";
 import { sharedTeardownAuthorized, type UninstallObservation } from "./uninstall-plan";
 
 export interface UninstallClientStateDeps {
@@ -13,6 +14,8 @@ export interface UninstallClientStateDeps {
   disconnect: (options?: Parameters<typeof disconnectClient>[0]) => Promise<unknown>;
   withLifecycle: typeof withClientLifecycle;
   remove: () => ConfigRemovalResult;
+  /** True while a timed-out icacls child still owns a path at or below the config directory. */
+  aclReapPending: (rootPath: string) => boolean;
 }
 
 const defaults: UninstallClientStateDeps = {
@@ -22,6 +25,7 @@ const defaults: UninstallClientStateDeps = {
   disconnect: options => disconnectClient(options),
   withLifecycle: withClientLifecycle,
   remove: () => removeOwnedConfigState(getConfigDir()),
+  aclReapPending: rootPath => windowsSecretAclReapPendingAtOrBelow(rootPath),
 };
 
 /** Restore connection-owned client artifacts before removing their ownership/recovery records. */
@@ -73,6 +77,14 @@ export async function removeOwnedConfigAfterDesktopCleanup(
       || (latestReceipt.kind === "valid" && latestReceipt.value.phase !== "complete")) {
       throw new Error("Client cleanup refused: connection or Desktop state changed before removal.");
     }
+    // The async ACL belt releases its caller on a stalled `icacls.exe`, which is what keeps
+    // startup and shutdown bounded. It is not evidence that the child released the directory,
+    // and on Windows a live handle makes this removal fail partway instead of cleanly. Refuse
+    // promptly and let the operator retry: waiting here would hand a stuck child the power to
+    // hang `ocx uninstall`, which is the bound the belt exists to preserve.
+    if (deps.aclReapPending(getConfigDir())) {
+      throw new Error("Client cleanup refused: ACL hardening still owns a path under the config directory.");
+    }
     return deps.remove();
   });
 }

package/src/client/machine-api.ts

@@ -74,10 +74,11 @@ export async function handleMachineApi(
   injected: MachineApiDeps = defaultDeps,
 ): Promise<Response | null> {
   const deps = { ...defaultDeps, ...injected };
-  if (url.pathname === "/api/machine/status" && req.method === "GET") {
+  const readMethod = req.method === "GET" || req.method === "HEAD";
+  if (url.pathname === "/api/machine/status" && readMethod) {
     return Response.json(statusPayload(req, state, deps), { headers: { "Cache-Control": "no-store" } });
   }
-  if (url.pathname === "/api/machine/clients" && req.method === "GET") {
+  if (url.pathname === "/api/machine/clients" && readMethod) {
     return Response.json({
       selectedClients: [...state.selectedClients],
       journalOwner: journalOwner(),
@@ -103,7 +104,7 @@ export async function handleMachineApi(
       return Response.json({ success: false, error: message }, { status: 502 });
     }
   }
-  if (url.pathname === "/api/machine/shim" && req.method === "GET") {
+  if (url.pathname === "/api/machine/shim" && readMethod) {
     return Response.json(diagnoseCodexShim(), { headers: { "Cache-Control": "no-store" } });
   }
   if (url.pathname === "/api/machine/shim" && req.method === "POST") {

package/src/client/machine-listener.ts

@@ -46,9 +46,14 @@ export function machineRouteAllowed(url: URL, req: Request, relayEnabled: boolea
   if (req.headers.get("upgrade")) return false;
   const path = url.pathname;
   if (req.method === "GET" && (path === "/healthz" || path === "/readyz" || path === "/" || path === "/opencodex-session")) return true;
-  if (req.method === "GET" && (path === "/api/machine/status" || path === "/api/machine/clients" || path === "/api/machine/shim")) return true;
+  if ((req.method === "GET" || req.method === "HEAD") && (path === "/api/machine/status" || path === "/api/machine/clients" || path === "/api/machine/shim")) return true;
   if (req.method === "POST" && (path === "/api/machine/sync" || path === "/api/machine/shim" || path === "/api/machine/disconnect")) return true;
   if (relayEnabled && path.startsWith("/api/machine/hub-relay/")) return true;
+  // Known machine endpoints are admitted for every method so an unsupported
+  // method reaches the authenticated method restriction (403) instead of a
+  // bare 404 that hides the endpoint entirely.
+  if (path === "/api/machine/status" || path === "/api/machine/clients" || path === "/api/machine/shim"
+    || path === "/api/machine/sync" || path === "/api/machine/disconnect") return true;
   if (req.method !== "GET" || path.startsWith("/api/") || path.startsWith("/v1/")) return false;
   return GUI_SPA_PATHS.has(path)
     || path.startsWith("/integrations/")
@@ -111,6 +116,14 @@ export function startMachineListener(
         if (managementPrincipal(req, managementAuth, config) !== "gui-session") {
           return Response.json({ error: "opencodex machine GUI session required" }, { status: 401 });
         }
+        // A loopback dashboard session proves possession, not user presence: any local
+        // process can fetch the dashboard bootstrap and replay its token and CSRF value.
+        // Keep the connected listener useful for status/diagnostics, but never let that
+        // credentialless bootstrap authorize durable machine changes. Those operations
+        // remain available through the explicit CLI commands.
+        if (req.method !== "GET" && req.method !== "HEAD") {
+          return Response.json({ error: "opencodex machine changes require the local CLI" }, { status: 403 });
+        }
         return await handleMachineApi(req, url, connection, machineApiDeps) ?? json404(req);
       }
 

package/src/clients/config-export/constants.ts

@@ -37,9 +37,8 @@ export const OPENCLAW_API_KEY_ENV_REF = `\${${OPENCLAW_API_KEY_ENV}}`;
 export const LOOPBACK_API_KEY_PLACEHOLDER = "opencodex-loopback";
 
 /**
- * Gajae's `apiKeyEnv` is env-name-only and fail-closed. Its sibling `apiKey`
- * falls back to treating the literal text as the token when the variable is
- * unset, which would silently ship a bogus credential — so we never emit it.
+ * Legacy name retained for existing consumers. Gajae exports now use the
+ * non-secret loopback placeholder and do not emit an environment reference.
  */
 export const GAJAE_API_KEY_ENV = "OPENCODEX_GAJAE_API_KEY";
 

package/src/clients/config-export.ts

@@ -41,7 +41,7 @@ export type { RaycastAbility, RaycastAbilityName, RaycastModelEntry, RaycastProv
 export { buildRaycastClientConfig, summarizeRaycast, buildRaycastContribution } from "./config-export/raycast";
 
 import type { OpencodeLaunchEnv, OpencodeCatalogModel, ExportContext, PiModelEntry, ManagedContribution, ManagedFragment, ExportClientId, ExportClientSpec } from "./config-export/contracts";
-import { OPENCODE_API_KEY_ENV_REF, OPENCODE_PROVIDER_BLOCK_DEFAULT_CONFIG, OPENCODE_CONFIG_SCHEMA, OPENCODE_PROVIDER_ID, PI_API_DIALECT, LOOPBACK_API_KEY_PLACEHOLDER, HERMES_API_KEY_ENV_REF, OPENCLAW_API_KEY_ENV_REF, GAJAE_API_KEY_ENV, OPENCODE_API_KEY_ENV, HERMES_API_KEY_ENV, OPENCLAW_API_KEY_ENV } from "./config-export/constants";
+import { OPENCODE_API_KEY_ENV_REF, OPENCODE_PROVIDER_BLOCK_DEFAULT_CONFIG, OPENCODE_CONFIG_SCHEMA, OPENCODE_PROVIDER_ID, PI_API_DIALECT, LOOPBACK_API_KEY_PLACEHOLDER, HERMES_API_KEY_ENV_REF, OPENCLAW_API_KEY_ENV_REF, OPENCODE_API_KEY_ENV, HERMES_API_KEY_ENV, OPENCLAW_API_KEY_ENV } from "./config-export/constants";
 import { exportModelLabel, authoritativeContextWindow, outputBudgetFor, normalizeExportModels, inputModalitiesForClient, opencodeModelCapabilities, proxyAdmissionHeaders, singleFragment } from "./config-export/model-metadata";
 import { buildOmpClientConfig, summarizeOmp, buildOmpContribution } from "./config-export/omp";
 import { buildDshClientConfig, summarizeDsh, buildDshContribution } from "./config-export/dsh";
@@ -867,7 +867,7 @@ export interface GajaeModelEntry {
 /** Gajae validates strictly: an unknown field fails the whole config. */
 export interface GajaeProviderBlock {
   baseUrl: string;
-  apiKeyEnv: string;
+  apiKey: string;
   api: "openai-completions";
   models: GajaeModelEntry[];
 }
@@ -1056,7 +1056,7 @@ function buildGajaeClientConfig(ctx: ExportContext): GajaeGeneratedConfig {
     providers: {
       [OPENCODE_PROVIDER_ID]: {
         baseUrl: ctx.baseUrl,
-        apiKeyEnv: GAJAE_API_KEY_ENV,
+        apiKey: LOOPBACK_API_KEY_PLACEHOLDER,
         api: "openai-completions",
         models,
       },
@@ -1320,8 +1320,8 @@ export const EXPORT_CLIENTS: Record<ExportClientId, ExportClientSpec> = {
     id: "gajae",
     filename: "gajae-models.yaml",
     destination: env => gajaeConfigPath(env),
-    apiKeyEnv: GAJAE_API_KEY_ENV,
-    exportHint: `export ${GAJAE_API_KEY_ENV}=<your key>`,
+    apiKeyEnv: "",
+    exportHint: "No environment variable is needed for the loopback provider.",
     build: buildGajaeClientConfig,
     format: "yaml",
     summarize: summarizeGajae,

package/src/codex/account-store.ts

@@ -1,3 +1,4 @@
+import { readOrcaAuthSource } from "./orca-auth-source";
 import { createHash } from "node:crypto";
 import { closeSync, existsSync, fstatSync, readFileSync, mkdirSync, openSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
@@ -52,11 +53,20 @@ function isObject(value: unknown): value is Record<string, unknown> {
 }
 
 function isCredential(value: unknown): value is CodexAccountCredentials {
+  const hasNoSource = isObject(value)
+    && value.sourceAuthPath === undefined
+    && value.sourceSubject === undefined;
+  const hasCompleteSource = isObject(value)
+    && typeof value.sourceAuthPath === "string"
+    && value.sourceAuthPath.length > 0
+    && typeof value.sourceSubject === "string"
+    && value.sourceSubject.length > 0;
   return isObject(value)
     && typeof value.accessToken === "string"
     && typeof value.refreshToken === "string"
     && typeof value.expiresAt === "number"
-    && typeof value.chatgptAccountId === "string";
+    && typeof value.chatgptAccountId === "string"
+    && (hasNoSource || hasCompleteSource);
 }
 
 function isCredentialRecord(value: unknown): value is CodexAccountCredentialRecord {
@@ -78,6 +88,7 @@ export function refreshGrantFingerprintForToken(refreshToken: string): string {
 }
 
 function recordGrantFingerprint(record: CodexAccountCredentialRecord): string | undefined {
+  if (record.credential?.sourceAuthPath) return undefined;
   return record.refreshGrantFingerprint ?? (
     record.credential ? refreshGrantFingerprintForToken(record.credential.refreshToken) : undefined
   );
@@ -426,7 +437,7 @@ export function commitRefreshedCodexCredentialWithAliases(
   return withCredentialMutationLockSync(() => {
     const store = loadCodexAccountRecordStore();
     const current = store[id];
-    if (!current || current.generation !== generation || current.deletedAt != null || !current.credential) {
+    if (!current || current.generation !== generation || current.deletedAt != null || !current.credential || current.credential.sourceAuthPath) {
       return { committed: false, propagatedAliases: [] };
     }
     const priorCredential = current.credential;
@@ -458,7 +469,7 @@ export function commitRefreshedCodexCredentialWithAliases(
       && priorCredential.chatgptAccountId === cred.chatgptAccountId
     ) {
       for (const [aliasId, alias] of Object.entries(store)) {
-        if (aliasId === id || alias.deletedAt != null || !alias.credential) continue;
+        if (aliasId === id || alias.deletedAt != null || !alias.credential || alias.credential.sourceAuthPath) continue;
         if (recordGrantFingerprint(alias) !== priorFingerprint) continue;
         if (alias.credential.accessToken !== priorCredential.accessToken) continue;
         if (alias.credential.expiresAt !== priorCredential.expiresAt) continue;
@@ -630,7 +641,14 @@ export type CodexRefreshProvenance = "self-refresh" | "joined-lineage" | "extern
 
 /** Terminal outcome of one forced refresh, as seen by the caller that requested it. */
 export type ForcedRefreshOutcome =
-  | { kind: "resolved"; provenance: CodexRefreshProvenance; generation: number; rotated: boolean }
+  | {
+      kind: "resolved";
+      provenance: CodexRefreshProvenance;
+      generation: number;
+      rotated: boolean;
+      /** Same-grant records advanced by this refresh, at their committed generations. */
+      propagatedAliases?: { id: string; generation: number }[];
+    }
   | { kind: "failed"; error: unknown };
 const MAX_CODEX_REFRESH_FLIGHTS = 32;
 const CODEX_REFRESH_FLIGHT_STALE_MS = 120_000;
@@ -776,7 +794,7 @@ function findFreshCredentialForGrant(
   // require both ids to be present and exactly equal rather than inferring identity from the grant.
   if (!expectedChatgptAccountId) return null;
   for (const [candidateId, candidate] of Object.entries(records)) {
-    if (candidateId === excludeId || candidate.deletedAt != null || !candidate.credential) continue;
+    if (candidateId === excludeId || candidate.deletedAt != null || !candidate.credential || candidate.credential.sourceAuthPath) continue;
     if (recordGrantFingerprint(candidate) !== refreshGrantFingerprint) continue;
     if (!candidate.credential.chatgptAccountId) continue;
     if (candidate.credential.chatgptAccountId !== expectedChatgptAccountId) continue;
@@ -926,6 +944,9 @@ export async function forceRefreshCodexPoolToken(
         provenance: classify(resolved),
         generation: resolved.generation,
         rotated: resolved.accessToken !== options.rejectedAccessToken,
+        ...(resolved.propagatedAliases?.length
+          ? { propagatedAliases: resolved.propagatedAliases }
+          : {}),
       });
     },
     error => {
@@ -967,6 +988,57 @@ export async function getValidCodexToken(
   };
 }
 
+/** Source credentials never join refresh flights or spend a refresh grant, including after 401. */
+function resolveOrcaSourceToken(id: string, forced?: ForcedRefreshFence): CodexRefreshResult {
+  const initial = readCodexAccountRecord(id);
+  const initialCredential = initial?.credential;
+  if (!initial || initial.deletedAt != null || !initialCredential?.sourceAuthPath || !initialCredential.sourceSubject) {
+    throw new CodexCredentialGenerationConflictError();
+  }
+  const sourceCredential = readOrcaAuthSource(initialCredential.sourceAuthPath);
+  if (sourceCredential.chatgptAccountId !== initialCredential.chatgptAccountId
+    || sourceCredential.sourceSubject !== initialCredential.sourceSubject) {
+    throw new Error("Orca credential identity changed; reimport the account explicitly.");
+  }
+  if (sourceCredential.accessToken === initialCredential.accessToken
+    && sourceCredential.expiresAt === initialCredential.expiresAt) {
+    if (forced?.rejectedAccessToken === sourceCredential.accessToken) {
+      throw new Error("Orca bearer was rejected; update the account in Orca and retry.");
+    }
+    return { accessToken: sourceCredential.accessToken, chatgptAccountId: sourceCredential.chatgptAccountId,
+      generation: initial.generation, provenance: "external-replacement" };
+  }
+
+  return withCredentialMutationLockSync(() => {
+    const store = loadCodexAccountRecordStore();
+    const record = store[id];
+    const prior = record?.credential;
+    if (!record || record.deletedAt != null || !prior?.sourceAuthPath || !prior.sourceSubject) {
+      throw new CodexCredentialGenerationConflictError();
+    }
+    if (record.generation !== initial.generation) throw new CodexCredentialGenerationConflictError();
+    const credential = readOrcaAuthSource(prior.sourceAuthPath);
+    if (credential.chatgptAccountId !== prior.chatgptAccountId || credential.sourceSubject !== prior.sourceSubject) {
+      throw new Error("Orca credential identity changed; reimport the account explicitly.");
+    }
+    if (credential.accessToken !== prior.accessToken || credential.expiresAt !== prior.expiresAt) {
+      store[id] = {
+        credential, generation: record.generation + 1, replacedAt: Date.now(),
+        // The source identity was checked above. Retire old-generation writers without
+        // splitting this same account's retained quota history on every source rotation.
+        quotaHistoryIdentity: record.quotaHistoryIdentity,
+        ...preservedValidationMetadata(record),
+      };
+      persistCredentialMutation(store);
+    }
+    if (forced?.rejectedAccessToken === credential.accessToken) {
+      throw new Error("Orca bearer was rejected; update the account in Orca and retry.");
+    }
+    return { accessToken: credential.accessToken, chatgptAccountId: credential.chatgptAccountId,
+      generation: store[id]!.generation, provenance: "external-replacement" };
+  });
+}
+
 async function resolveCodexToken(
   id: string,
   forced?: ForcedRefreshFence,
@@ -976,6 +1048,7 @@ async function resolveCodexToken(
   const record = readCodexAccountRecord(id);
   const cred = record?.deletedAt == null ? record?.credential : undefined;
   if (!record || !cred) throw new CodexCredentialUnavailableError();
+  if (cred.sourceAuthPath) return resolveOrcaSourceToken(id, forced);
   const refreshGrantFingerprint = recordGrantFingerprint(record);
   if (!refreshGrantFingerprint) throw new CodexCredentialUnavailableError();
 
@@ -1005,6 +1078,7 @@ async function resolveCodexToken(
       const refreshed = await awaitOwnCancellation(existing.promise, callerSignal);
       const current = readCodexAccountRecord(id);
       const currentCred = current?.deletedAt == null ? current?.credential : undefined;
+      if (currentCred?.sourceAuthPath) return resolveOrcaSourceToken(id, forced);
       // The flight owner already committed this credential, and it is the one stored
       // for this account: adopt the stored state instead of CAS-writing the identical
       // bytes, which would bump the generation a second time and invalidate the
@@ -1126,6 +1200,7 @@ async function resolveCodexToken(
     const lockedRecord = readCodexAccountRecord(id);
     const lockedCred = lockedRecord?.deletedAt == null ? lockedRecord?.credential : undefined;
     if (!lockedRecord || !lockedCred) throw new CodexCredentialGenerationConflictError();
+    if (lockedCred.sourceAuthPath) return resolveOrcaSourceToken(id, forced);
     const startGeneration = lockedRecord.generation;
     const lockedRefreshGrantFingerprint = recordGrantFingerprint(lockedRecord);
     if (lockedRefreshGrantFingerprint !== refreshGrantFingerprint) {
@@ -1331,6 +1406,7 @@ async function resolveCodexToken(
     // Provenance rides out with the rest: a joiner that adopts this result needs the
     // flight's own classification, not a guess made at the adoption site (#3019).
     ...(result.provenance !== undefined ? { provenance: result.provenance } : {}),
+    ...(result.propagatedAliases?.length ? { propagatedAliases: result.propagatedAliases } : {}),
     ...(result.resolvedGrantFingerprint !== undefined
       ? { resolvedGrantFingerprint: result.resolvedGrantFingerprint }
       : {}),

package/src/codex/auth-api/pool-quota-probe.ts

@@ -9,7 +9,7 @@ import { codexWarmupFailureReason, warmCodexAccount } from "../warmup";
 import { readBoundedResponseBody } from "../../lib/bounded-body";
 import { ResourceAdmissionError } from "../../lib/admission";
 import { WHAM_REQUEST_TIMEOUT_MS } from "../quota-recovery-timing";
-import { claimQuotaRecovery, quotaRecoveryTerminalFor, releaseQuotaRecovery, settleQuotaRecovery, settleQuotaRecoveryTerminal } from "../quota-401-recovery";
+import { claimQuotaRecovery, fencePropagatedQuotaRecovery, quotaRecoveryTerminalFor, releaseQuotaRecovery, settleQuotaRecovery, settleQuotaRecoveryTerminal } from "../quota-401-recovery";
 import { seedLoginRowsForTests } from "./login-state";
 import { nonEmptyPlan } from "./runtime-config";
 
@@ -205,6 +205,12 @@ export async function recoverPoolQuotaFrom401(ctx: {
       onSettled: outcome => {
         if (outcome.kind === "resolved") {
           settleQuotaRecovery(accountId, claim.claimId, outcome);
+          // A propagated alias adopted the rotated grant without spending its own claim. Fence
+          // each committed alias generation so a later 401 on it cannot claim a second refresh
+          // of the same underlying grant.
+          for (const alias of outcome.propagatedAliases ?? []) {
+            fencePropagatedQuotaRecovery(alias.id, alias.generation);
+          }
         } else if (outcome.error instanceof TokenRefreshError && isTerminalRefreshError(outcome.error)) {
           // A revoked or expired grant does not become valid on the next poll. Releasing it
           // into backoff would let the following bare 401 find a non-terminal record and
@@ -476,9 +482,14 @@ export async function fetchPoolAccountQuota(
       && generation !== undefined && record.generation === generation
       && isCompleteCodexQuotaRecoverySnapshot(result.freshQuota ?? null, result.freshPlan ?? configuredPlan)) {
       try {
+        // Quota I/O may outlive the source capture. Never validate a rotated or revoked link
+        // using an older generation's observation. Explicit validation consent still applies.
+        const sourceToken = record.credential.sourceAuthPath ? await getValidToken(accountId) : null;
+        if (sourceToken && (sourceToken.generation !== generation
+          || !isCodexAccountGenerationLive(accountId, generation))) return result;
         await warmCodexAccount({
-          accessToken: record.credential.accessToken,
-          chatgptAccountId: record.credential.chatgptAccountId,
+          accessToken: sourceToken?.accessToken ?? record.credential.accessToken,
+          chatgptAccountId: sourceToken?.chatgptAccountId ?? record.credential.chatgptAccountId,
         });
         markCodexAccountValidated(accountId, Date.now(), generation);
         clearAccountNeedsReauth(accountId, generation);

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

@@ -7,7 +7,7 @@ import { getAccountQuotaHistory, listAccountQuotas } from "../quota";
 import { deleteCodexAccount } from "../account-lifecycle";
 import { isCodexAccountPaused, setCodexAccountPaused } from "../account-pause";
 import { clearCodexAccountPin, isCodexAccountPriorityKey, pinnedCodexAccountId, setCodexAccountPin, setCodexAccountPriority } from "../account-priority";
-import { codexQuotaScopeForModel, clearCodexAccountCooldown, clearThreadAccountMapForAccount, getEffectiveActiveCodexAccountId, isEffectiveCodexAccountPinned, resetCodexRoutingForManualSelection } from "../routing";
+import { codexAccountPinDrainReason, codexQuotaScopeForModel, clearCodexAccountCooldown, clearThreadAccountMapForAccount, getEffectiveActiveCodexAccountId, isEffectiveCodexAccountPinned, resetCodexRoutingForManualSelection } from "../routing";
 import { DEFAULT_ACCOUNT_PRIORITY, MAX_ACCOUNT_PRIORITY, MIN_ACCOUNT_PRIORITY, normalizeAccountPoolStickyLimit, normalizeCodexAccountPoolStrategy, parseAccountPoolStickyLimit, parseCodexAccountPoolStrategy, parseAccountPriority } from "../pool-rotation";
 import { MAIN_CODEX_ACCOUNT_ID } from "../main-account";
 import { reconcileLiveStateStores } from "../../lib/state-store-registrations";
@@ -235,7 +235,22 @@ export async function handleCodexAuthAPI(
     else setCodexAccountPin(runtimeConfig, targetAccountId);
     resetCodexRoutingForManualSelection(targetAccountId);
     saveRuntimeConfig(config, runtimeConfig);
-    return jsonResponse({ ok: true, activeCodexAccountId: body.accountId, appliesImmediately: true });
+    // A pin this route accepts can still be dropped by the very next resolve, and saying
+    // nothing about that is what made the setting look ignored (#4521). The checks above
+    // refuse an account that cannot be selected at all; this reports the one remaining
+    // outcome they do not cover, from the same predicate routing releases on, so the two
+    // cannot drift. Absent means the pin survives — additive for existing clients.
+    // `appliesImmediately` is unchanged: it answers whether thread affinity was cleared,
+    // not whether the pin is durable.
+    const pinDrainReason = body.accountId == null
+      ? undefined
+      : codexAccountPinDrainReason(runtimeConfig, targetAccountId);
+    return jsonResponse({
+      ok: true,
+      activeCodexAccountId: body.accountId,
+      appliesImmediately: true,
+      ...(pinDrainReason !== undefined ? { pinDrained: true, pinDrainReason } : {}),
+    });
   }
 
   if (url.pathname === "/api/codex-auth/active" && req.method === "GET") {