npm - @bitkyc08/opencodex - Versions diffs - 2.6.18 → 2.6.19 - Mend

@bitkyc08/opencodex 2.6.18 → 2.6.19

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (19) hide show

package/gui/dist/assets/index-Barime1y.js +9 -0
package/gui/dist/index.html +1 -1
package/package.json +1 -1
package/src/adapters/cursor/transport-retry.ts +5 -26
package/src/adapters/google-http.ts +1 -16
package/src/adapters/kiro-retry.ts +1 -25
package/src/cli.ts +6 -0
package/src/codex-catalog.ts +25 -2
package/src/doctor.ts +153 -7
package/src/oauth/index.ts +26 -1
package/src/oauth/token-guardian.ts +200 -0
package/src/providers/registry.ts +27 -1
package/src/server.ts +113 -12
package/src/types.ts +41 -0
package/src/upstream-retry.ts +96 -0
package/src/vision/describe.ts +10 -6
package/src/web-search/executor.ts +10 -6
package/src/web-search/loop.ts +10 -6
package/gui/dist/assets/index-DbTEyo46.js +0 -9

package/gui/dist/index.html CHANGED Viewed

@@ -16,7 +16,7 @@
         } catch (e) {}
       })();
     </script>
-    <script type="module" crossorigin src="/assets/index-DbTEyo46.js"></script>
+    <script type="module" crossorigin src="/assets/index-Barime1y.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-DDcEW0Cm.css">
   </head>
   <body>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@bitkyc08/opencodex",
-  "version": "2.6.18",
+  "version": "2.6.19",
   "description": "Universal provider proxy for OpenAI Codex — use any LLM with Codex CLI/App/SDK",
   "type": "module",
   "main": "./bin/package-main.mjs",

package/src/adapters/cursor/transport-retry.ts CHANGED Viewed

@@ -1,5 +1,9 @@
 import type { CursorRunRequest, CursorServerMessage } from "./types";
 import type { CursorTransport, CursorTransportFactory, CursorTransportFactoryInput } from "./transport";
+import { abortError, sleepWithAbort } from "../../upstream-retry";
+// Compat: historical name for the shared abortable sleep, kept for external callers.
+export { sleepWithAbort as abortAwareSleep } from "../../upstream-retry";
 export const CURSOR_RETRY_ATTEMPTS = 3;
 export const CURSOR_RETRY_BASE_MS = 250;
@@ -36,31 +40,6 @@ export function cursorRetryDelayMs(attempt: number): number {
   return Math.floor(exp * (0.8 + Math.random() * 0.4));
 }
-function abortError(signal?: AbortSignal): unknown {
-  return signal?.reason ?? new DOMException("The operation was aborted", "AbortError");
-}
-export async function abortAwareSleep(ms: number, signal?: AbortSignal): Promise<void> {
-  if (ms <= 0) return;
-  if (signal?.aborted) throw abortError(signal);
-  await new Promise<void>((resolve, reject) => {
-    let timer: ReturnType<typeof setTimeout>;
-    const cleanup = () => {
-      clearTimeout(timer);
-      signal?.removeEventListener("abort", onAbort);
-    };
-    const onAbort = () => {
-      cleanup();
-      reject(abortError(signal));
-    };
-    timer = setTimeout(() => {
-      cleanup();
-      resolve();
-    }, ms);
-    signal?.addEventListener("abort", onAbort, { once: true });
-  });
-}
 /**
  * A transport is safe to retry only if it explicitly reports the run request was never committed.
  * A transport without `requestCommitted` is treated as committed (not retryable) — fail safe.
@@ -105,7 +84,7 @@ export async function runCursorTurnWithRetry(
         requestUncommitted(transport) &&
         isRetryableCursorError(err);
       if (!canRetry) throw err;
-      await abortAwareSleep(cursorRetryDelayMs(attempt), signal);
+      await sleepWithAbort(cursorRetryDelayMs(attempt), signal);
     } finally {
       await transport.close?.();
     }

package/src/adapters/google-http.ts CHANGED Viewed

@@ -1,5 +1,6 @@
 import type { AdapterFetchContext, AdapterRequest } from "./base";
 import { isQuotaExhaustedBody, retryableGoogleStatus, safeGoogleHttpErrorMessage } from "./google-errors";
+import { abortError, sleepWithAbort } from "../upstream-retry";
 const GOOGLE_RETRY_ATTEMPTS = 3;
 const GOOGLE_RETRY_BASE_MS = 250;
@@ -22,22 +23,6 @@ function retryDelayMs(attempt: number, headers?: Headers): number {
   return Math.floor(exp * (0.8 + Math.random() * 0.4));
 }
-function abortError(signal?: AbortSignal): unknown {
-  return signal?.reason ?? new DOMException("The operation was aborted", "AbortError");
-}
-async function sleepWithAbort(ms: number, signal?: AbortSignal): Promise<void> {
-  if (ms <= 0) return;
-  if (signal?.aborted) throw abortError(signal);
-  await new Promise<void>((resolve, reject) => {
-    let timer: ReturnType<typeof setTimeout>;
-    const cleanup = () => { clearTimeout(timer); signal?.removeEventListener("abort", onAbort); };
-    const onAbort = () => { cleanup(); reject(abortError(signal)); };
-    timer = setTimeout(() => { cleanup(); resolve(); }, ms);
-    signal?.addEventListener("abort", onAbort, { once: true });
-  });
-}
 function signalWithAttemptTimeout(parent: AbortSignal | undefined, timeoutMs: number): AbortSignal {
   const timeout = AbortSignal.timeout(timeoutMs);
   return parent ? AbortSignal.any([parent, timeout]) : timeout;

package/src/adapters/kiro-retry.ts CHANGED Viewed

@@ -1,5 +1,6 @@
 import type { AdapterFetchContext, AdapterRequest } from "./base";
 import { safeKiroHttpErrorMessage } from "./kiro-errors";
+import { abortError, sleepWithAbort } from "../upstream-retry";
 const KIRO_RETRY_ATTEMPTS = 3;
 const KIRO_RETRY_BASE_MS = 250;
@@ -26,31 +27,6 @@ function retryDelayMs(attempt: number, headers?: Headers): number {
   return Math.floor(exp * (0.8 + Math.random() * 0.4));
 }
-function abortError(signal?: AbortSignal): unknown {
-  return signal?.reason ?? new DOMException("The operation was aborted", "AbortError");
-}
-async function sleepWithAbort(ms: number, signal?: AbortSignal): Promise<void> {
-  if (ms <= 0) return;
-  if (signal?.aborted) throw abortError(signal);
-  await new Promise<void>((resolve, reject) => {
-    let timer: ReturnType<typeof setTimeout>;
-    const cleanup = () => {
-      clearTimeout(timer);
-      signal?.removeEventListener("abort", onAbort);
-    };
-    const onAbort = () => {
-      cleanup();
-      reject(abortError(signal));
-    };
-    timer = setTimeout(() => {
-      cleanup();
-      resolve();
-    }, ms);
-    signal?.addEventListener("abort", onAbort, { once: true });
-  });
-}
 function signalWithAttemptTimeout(parent: AbortSignal | undefined, timeoutMs: number): AbortSignal {
   const timeout = AbortSignal.timeout(timeoutMs);
   return parent ? AbortSignal.any([parent, timeout]) : timeout;

package/src/cli.ts CHANGED Viewed

@@ -27,6 +27,7 @@ import { findLiveProxy, probeHostname, type LiveProxy } from "./proxy-liveness";
 import { stopProxy } from "./process-control";
 import { serviceCommand, serviceStatusSummary, stopServiceIfInstalled, uninstallServiceIfInstalled } from "./service";
 import { drainAndShutdown, startServer } from "./server";
+import { startTokenGuardian } from "./oauth/token-guardian";
 import { maybeShowStarPrompt } from "./star-prompt";
 import { maybeShowUpdatePrompt } from "./update-notify";
 import { syncModelsToCodex } from "./codex-sync";
@@ -134,10 +135,15 @@ async function handleStart(options: { block?: boolean } = {}) {
   writeRuntimePort({ pid: process.pid, port, hostname: config.hostname });
   writeJournal();
+  // Background proactive token refresh. No-op unless config.tokenGuardian.enabled; timer is unref'd
+  // so it never keeps the process alive on its own. Stopped in syncCleanup so no refresh fires mid-drain.
+  const guardian = startTokenGuardian();
   let cleaned = false;
   const syncCleanup = () => {
     if (cleaned) return;
     cleaned = true;
+    try { guardian.stop(); } catch { /* best-effort */ }
     removePid(process.pid);
     removeRuntimePort(process.pid);
     if (!process.env.OCX_SERVICE) { try { restoreNativeCodex(); } catch { /* best-effort restore */ } }

package/src/codex-catalog.ts CHANGED Viewed

@@ -815,6 +815,30 @@ async function fetchProviderModels(name: string, prov: OcxProviderConfig, ttlMs:
   }
 }
+/**
+ * Narrow a raw routed-model list to what Codex's catalog / clients should see: drop the
+ * `disabledModels` blocklist AND, for any provider with a non-empty `selectedModels` allowlist, keep
+ * only those ids. This is the single choke point applied at every CATALOG emission point (on-disk
+ * sync + /v1/models); the admin `/api/models` list stays unfiltered so the picker can show the full
+ * set. Live discovery is unaffected — this only decides what ships. See issue_052.
+ */
+export function filterCatalogVisibleModels(
+  models: CatalogModel[],
+  config: Pick<OcxConfig, "disabledModels" | "providers">,
+): CatalogModel[] {
+  const disabled = new Set(config.disabledModels ?? []);
+  const allowByProvider = new Map<string, Set<string>>();
+  for (const [name, prov] of Object.entries(config.providers)) {
+    const sel = prov.selectedModels;
+    if (Array.isArray(sel) && sel.length > 0) allowByProvider.set(name, new Set(sel));
+  }
+  return models.filter(m => {
+    if (disabled.has(`${m.provider}/${m.id}`)) return false;
+    const allow = allowByProvider.get(m.provider);
+    return !allow || allow.has(m.id);
+  });
+}
 /**
  * Gather routed (non-forward) provider models across the config — the single source of truth for
  * the live model list, used by both the on-disk catalog sync and the proxy's /api/* + /v1/models
@@ -983,8 +1007,7 @@ export async function syncCatalogModels(config: OcxConfig): Promise<{ added: num
   // Hide disabled models from Codex, then feature the chosen subagent models (native OR routed)
   // by giving them the lowest priority — see buildCatalogEntries for why priority, not array order.
-  const disabled = new Set(config.disabledModels ?? []);
-  const enabledGo = goModels.filter(m => !disabled.has(`${m.provider}/${m.id}`));
+  const enabledGo = filterCatalogVisibleModels(goModels, config);
   const featured = config.subagentModels ?? [];
   const orderedGoModels = orderForSubagents(enabledGo, featured); // stable tie-break among equal priorities
   const goEntries = buildCatalogEntries(template ? JSON.parse(JSON.stringify(template)) : null, [], orderedGoModels, featured, websocketsEnabled(config));

package/src/doctor.ts CHANGED Viewed

@@ -10,7 +10,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
-import { expandUserPath, getConfigDir, getConfigPath } from "./config";
+import { expandUserPath, getConfigDir, getConfigPath, readConfigDiagnostics, readPid, resolveEnvValue } from "./config";
 import { readCodexTokens } from "./codex-auth-collision";
 const WHAM_USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
@@ -78,16 +78,143 @@ function readMounts(): string | null {
 const PROXY_KEYS = ["HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY", "NO_PROXY"] as const;
 export type ProxyEnvRow = { key: string; present: boolean };
+export type EnvMap = Record<string, string | undefined>;
 /** Report only presence/absence of proxy env vars - never the value (it may
  * embed credentials). Checks both upper- and lower-case forms. */
-export function collectProxyEnv(): ProxyEnvRow[] {
+export function collectProxyEnv(env: EnvMap = process.env): ProxyEnvRow[] {
   return PROXY_KEYS.map(key => ({
     key,
-    present: !!(process.env[key]?.trim() || process.env[key.toLowerCase()]?.trim()),
+    present: !!(env[key]?.trim() || env[key.toLowerCase()]?.trim()),
   }));
 }
+export type ConfiguredProxyDiagnostic = {
+  key: "config.proxy";
+  present: boolean;
+  configured: boolean;
+  source: "default" | "file" | "fallback";
+  detail: string;
+};
+function envReferenceName(value: string): string | null {
+  const braced = value.match(/^\$\{(\w+)\}$/);
+  if (braced) return braced[1]!;
+  const bare = value.match(/^\$(\w+)$/);
+  return bare ? bare[1]! : null;
+}
+export function collectConfiguredProxy(): ConfiguredProxyDiagnostic {
+  const diagnostics = readConfigDiagnostics();
+  const rawProxy = typeof diagnostics.config.proxy === "string" ? diagnostics.config.proxy.trim() : "";
+  if (diagnostics.error) {
+    return {
+      key: "config.proxy",
+      present: false,
+      configured: false,
+      source: diagnostics.source,
+      detail: `config unreadable (${diagnostics.error})`,
+    };
+  }
+  if (!rawProxy) {
+    return {
+      key: "config.proxy",
+      present: false,
+      configured: false,
+      source: diagnostics.source,
+      detail: "not configured",
+    };
+  }
+  const envName = envReferenceName(rawProxy);
+  const resolved = resolveEnvValue(rawProxy);
+  if (resolved?.trim()) {
+    return {
+      key: "config.proxy",
+      present: true,
+      configured: true,
+      source: diagnostics.source,
+      detail: envName ? `env reference ${envName} resolved` : "value hidden",
+    };
+  }
+  return {
+    key: "config.proxy",
+    present: false,
+    configured: true,
+    source: diagnostics.source,
+    detail: envName ? `env reference ${envName} is unset` : "empty after resolution",
+  };
+}
+export function parseProcessEnvBlock(content: string): EnvMap {
+  const env: EnvMap = {};
+  for (const entry of content.split("\0")) {
+    if (!entry) continue;
+    const separator = entry.indexOf("=");
+    if (separator <= 0) continue;
+    env[entry.slice(0, separator)] = entry.slice(separator + 1);
+  }
+  return env;
+}
+export type RunningProxyEnvDiagnostic =
+  | { status: "not_running"; rows: ProxyEnvRow[] }
+  | { status: "ok"; pid: number; rows: ProxyEnvRow[] }
+  | { status: "unavailable"; pid: number; reason: string; rows: ProxyEnvRow[] };
+type RunningProxyEnvDeps = {
+  readPidFn?: () => number | null;
+  readEnvironFn?: (pid: number) => string | null;
+  platform?: NodeJS.Platform | string;
+};
+function readProcessEnviron(pid: number): string | null {
+  try {
+    return readFileSync(`/proc/${pid}/environ`, "utf-8");
+  } catch {
+    return null;
+  }
+}
+/*
+ * [Decision Log]
+ * - Purpose: Make `ocx doctor` distinguish the current shell env from the already-running proxy process env.
+ * - Alternatives: Rename the old section only; parse service-manager env for each OS; read the recorded proxy PID's env presence.
+ * - Rationale: PID env presence is the narrowest useful diagnostic on Linux/WSL, avoids secret value output, and keeps unsupported platforms explicit.
+ */
+export function collectRunningProxyEnv(deps: RunningProxyEnvDeps = {}): RunningProxyEnvDiagnostic {
+  const rowsWhenEmpty = () => collectProxyEnv({});
+  const pid = (deps.readPidFn ?? readPid)();
+  if (!pid) return { status: "not_running", rows: rowsWhenEmpty() };
+  const platform = deps.platform ?? process.platform;
+  if (platform !== "linux" && !deps.readEnvironFn) {
+    return {
+      status: "unavailable",
+      pid,
+      reason: "process env inspection is only supported on Linux",
+      rows: rowsWhenEmpty(),
+    };
+  }
+  const content = (deps.readEnvironFn ?? readProcessEnviron)(pid);
+  if (content === null) {
+    return {
+      status: "unavailable",
+      pid,
+      reason: "could not read process environment",
+      rows: rowsWhenEmpty(),
+    };
+  }
+  return {
+    status: "ok",
+    pid,
+    rows: collectProxyEnv(parseProcessEnvBlock(content)),
+  };
+}
 export type WhamProbeResult = {
   ok: boolean;
   status: number | null;
@@ -142,11 +269,30 @@ export async function runDoctor(): Promise<void> {
     console.log(`  ${row.exists ? "ok " : "-- "} ${row.label}: ${row.path}${flags ? `  (${flags})` : ""}`);
   }
-  console.log("\nProxy env (presence only)");
-  for (const row of collectProxyEnv()) {
+  const currentProxyEnv = collectProxyEnv();
+  const configuredProxy = collectConfiguredProxy();
+  const runningProxyEnv = collectRunningProxyEnv();
+  console.log("\nCurrent doctor process proxy env (presence only)");
+  for (const row of currentProxyEnv) {
     console.log(`  ${row.present ? "set    " : "unset  "} ${row.key}`);
   }
+  console.log("\nConfigured proxy (value hidden)");
+  console.log(`  ${configuredProxy.present ? "set    " : "unset  "} ${configuredProxy.key} (${configuredProxy.source}; ${configuredProxy.detail})`);
+  console.log("\nRunning proxy process proxy env (presence only)");
+  if (runningProxyEnv.status === "not_running") {
+    console.log("  --     no running ocx proxy process found");
+  } else if (runningProxyEnv.status === "unavailable") {
+    console.log(`  --     pid ${runningProxyEnv.pid}: ${runningProxyEnv.reason}`);
+  } else {
+    console.log(`  ok     pid ${runningProxyEnv.pid}`);
+    for (const row of runningProxyEnv.rows) {
+      console.log(`  ${row.present ? "set    " : "unset  "} ${row.key}`);
+    }
+  }
   console.log("\nWHAM reachability");
   const probe = await probeWham();
   const detail = probe.status !== null ? `status=${probe.status}` : `error=${probe.classification}`;
@@ -156,7 +302,7 @@ export async function runDoctor(): Promise<void> {
   // Hints, not fixes.
   const hints: string[] = [];
   const anyDrvfs = paths.some(p => detectFsType(p.path, mounts).isDrvfs || detectFsType(p.path, mounts).isMntDrive);
-  const noProxy = collectProxyEnv().every(p => !p.present);
+  const noProxy = currentProxyEnv.every(p => !p.present) && !configuredProxy.present;
   if (anyDrvfs) {
     hints.push("State dir is on a Windows-mounted (/mnt) drive. Prefer the Linux home (~) under WSL for token/lock reliability.");
   }
@@ -164,7 +310,7 @@ export async function runDoctor(): Promise<void> {
     if (probe.classification === "timeout" || probe.classification === "connect_error") {
       hints.push("WHAM probe could not reach chatgpt.com. On WSL2 this is often NAT/DNS/VPN. Quota cannot prime, so auto-switch stays on unknown scores.");
       if (noProxy) {
-        hints.push("No *_PROXY env is set in this WSL process. If Windows uses a proxy/VPN, set HTTP(S)_PROXY here or enable WSL autoProxy so Bun fetch can reach the network.");
+        hints.push("No proxy is visible to this doctor process and config.proxy is unset or unresolved. If Windows uses a proxy/VPN, set config.proxy or start ocx from a shell with HTTP(S)_PROXY.");
       }
     }
   }

package/src/oauth/index.ts CHANGED Viewed

@@ -1,5 +1,5 @@
 import type { OAuthController, OAuthCredentials } from "./types";
-import type { OcxConfig, OcxProviderConfig } from "../types";
+import type { OcxConfig, OcxProviderConfig, RefreshPolicy } from "../types";
 import { loadConfig, resolveEnvValue, saveConfig } from "../config";
 import { maskEmail } from "../privacy";
 import { getCredential, saveCredential } from "./store";
@@ -24,6 +24,12 @@ interface OAuthProviderDef {
   /** provider entry written into config.json on first login. */
   providerConfig: OcxProviderConfig;
   defaultModel: string;
+  /**
+   * Built-in proactive-refresh policy, risk-tiered by the provider's ToS exposure (devlog
+   * 260703_oauth-multi-account-refresh-and-tos). A user's per-provider `config.providers[x].refreshPolicy`
+   * overrides this. Default when unset here: "lazy-only".
+   */
+  defaultRefreshPolicy?: RefreshPolicy;
 }
 function oauthConfig(id: string): OcxProviderConfig {
@@ -50,6 +56,9 @@ export const OAUTH_PROVIDERS: Record<string, OAuthProviderDef> = {
     refresh: refreshAnthropicToken,
     providerConfig: oauthConfig("anthropic"),
     defaultModel: oauthDefaultModel("anthropic"),
+    // Anthropic actively server-side-blocks subscription OAuth outside its own clients (Feb 2026).
+    // Never generate background refresh traffic for it — grade 20, highest ToS risk.
+    defaultRefreshPolicy: "disabled",
   },
   kimi: {
     login: (ctrl) => loginKimi(ctrl),
@@ -87,6 +96,22 @@ export function isOAuthProvider(name: string): boolean {
   return name in OAUTH_PROVIDERS;
 }
+function isRefreshPolicy(value: unknown): value is RefreshPolicy {
+  return value === "proactive" || value === "lazy-only" || value === "disabled";
+}
+/**
+ * The effective proactive-refresh policy for a provider: the user's per-provider
+ * `config.providers[provider].refreshPolicy` if set, else the provider def's risk-tiered default,
+ * else "lazy-only". The guardian acts only when this resolves to "proactive".
+ */
+export function resolveRefreshPolicy(provider: string, config: OcxConfig): RefreshPolicy {
+  const override = config.providers[provider]?.refreshPolicy;
+  if (isRefreshPolicy(override)) return override;
+  const def = OAUTH_PROVIDERS[provider];
+  return def?.defaultRefreshPolicy ?? "lazy-only";
+}
 /** The discovered project id stored on an OAuth credential (Antigravity CCA), if any. */
 export function getOAuthCredentialProjectId(provider: string): string | undefined {
   return getCredential(provider)?.projectId;

package/src/oauth/token-guardian.ts ADDED Viewed

@@ -0,0 +1,200 @@
+/**
+ * Token Guardian — background proactive OAuth refresh.
+ *
+ * Keeps idle tokens from aging out server-side (the reported multi-account Codex-pool bug) by
+ * refreshing them BEFORE a request needs them. It is a CALLER of the existing refresh machinery —
+ * it adds no new refresh/locking logic:
+ *   - single-account providers → getValidAccessToken() (in-memory dedup + persist)
+ *   - multi-account Codex pool  → getValidCodexToken()  (file lock + generation CAS + grant fingerprint)
+ *
+ * Safety by construction: the guardian only touches a provider whose EFFECTIVE refreshPolicy is
+ * "proactive", and the global switch (config.tokenGuardian.enabled) defaults OFF, so a default
+ * install adds zero ToS-detection surface. See devlog 260703_oauth-multi-account-refresh-and-tos.
+ */
+import { loadConfig } from "../config";
+import type { OcxConfig, OcxTokenGuardianConfig } from "../types";
+import { getCredential } from "./store";
+import { getValidAccessToken, listOAuthProviders, resolveRefreshPolicy } from "./index";
+import {
+  getValidCodexToken,
+  listCodexAccountIds,
+  readCodexAccountRecord,
+  TokenRefreshError,
+} from "../codex-account-store";
+export interface TokenGuardianHandle {
+  stop(): void;
+}
+export interface GuardianSweepResult {
+  enabled: boolean;
+  refreshed: string[];
+  failed: string[];
+  skippedBackoff: string[];
+}
+const DEFAULTS = {
+  tickSeconds: 21600, // 6h — matches codex-lb's guardian cadence
+  jitterSeconds: 300,
+  concurrency: 3,
+  leadSeconds: 900,
+  failureBackoffBaseSeconds: 300,
+  failureBackoffMaxSeconds: 3600,
+};
+interface BackoffEntry {
+  attempts: number;
+  retryAfterMs: number;
+}
+// Module-scoped so backoff survives across sweeps within one process (keyed "oauth:<p>" / "codex:<id>").
+const backoff = new Map<string, BackoffEntry>();
+/** Test hook: clear backoff state between cases. */
+export function __resetGuardianState(): void {
+  backoff.clear();
+}
+function num(value: number | undefined, fallback: number, min: number): number {
+  return typeof value === "number" && Number.isFinite(value) && value >= min ? value : fallback;
+}
+function resolved(g: OcxTokenGuardianConfig | undefined) {
+  return {
+    tickSeconds: num(g?.tickSeconds, DEFAULTS.tickSeconds, 60),
+    jitterSeconds: num(g?.jitterSeconds, DEFAULTS.jitterSeconds, 0),
+    concurrency: Math.max(1, Math.floor(num(g?.concurrency, DEFAULTS.concurrency, 1))),
+    leadSeconds: num(g?.leadSeconds, DEFAULTS.leadSeconds, 0),
+    backoffBaseSeconds: num(g?.failureBackoffBaseSeconds, DEFAULTS.failureBackoffBaseSeconds, 0),
+    backoffMaxSeconds: num(g?.failureBackoffMaxSeconds, DEFAULTS.failureBackoffMaxSeconds, 0),
+  };
+}
+function inBackoff(key: string, nowMs: number): boolean {
+  const entry = backoff.get(key);
+  return entry !== undefined && entry.retryAfterMs > nowMs;
+}
+function recordFailure(key: string, nowMs: number, baseSeconds: number, maxSeconds: number, permanent: boolean): void {
+  const prev = backoff.get(key);
+  const attempts = (prev?.attempts ?? 0) + 1;
+  // Permanent failures (revoked/expired refresh token) wait the full ceiling — nothing but a
+  // re-login fixes them, so there is no point retrying sooner.
+  const delaySeconds = permanent
+    ? maxSeconds
+    : Math.min(maxSeconds, baseSeconds * 2 ** (attempts - 1));
+  backoff.set(key, { attempts, retryAfterMs: nowMs + delaySeconds * 1000 });
+}
+async function runWithConcurrency(tasks: Array<() => Promise<void>>, limit: number): Promise<void> {
+  let cursor = 0;
+  const workers = Array.from({ length: Math.min(limit, tasks.length) }, async () => {
+    while (cursor < tasks.length) {
+      const task = tasks[cursor++];
+      if (task) await task();
+    }
+  });
+  await Promise.all(workers);
+}
+/**
+ * One refresh sweep. Reads live config + stores; refreshes every proactive-policy credential that
+ * will expire before the next sweep (tick + lead horizon). Never throws — per-credential failures
+ * are captured into backoff and the result. Returns a redacted summary (provider names / account
+ * ids only, never tokens).
+ */
+export async function guardianSweep(nowMs: number = Date.now()): Promise<GuardianSweepResult> {
+  const config: OcxConfig = loadConfig();
+  const g = config.tokenGuardian;
+  const result: GuardianSweepResult = { enabled: !!g?.enabled, refreshed: [], failed: [], skippedBackoff: [] };
+  if (!g?.enabled) return result;
+  const opts = resolved(g);
+  const horizonMs = (opts.tickSeconds + opts.leadSeconds) * 1000;
+  const tasks: Array<() => Promise<void>> = [];
+  // A) single-account OAuth providers
+  for (const provider of listOAuthProviders()) {
+    if (resolveRefreshPolicy(provider, config) !== "proactive") continue;
+    const cred = getCredential(provider);
+    if (!cred) continue;
+    if (cred.expires > nowMs + horizonMs) continue;
+    const key = `oauth:${provider}`;
+    if (inBackoff(key, nowMs)) { result.skippedBackoff.push(key); continue; }
+    tasks.push(async () => {
+      try {
+        await getValidAccessToken(provider);
+        backoff.delete(key);
+        result.refreshed.push(key);
+      } catch {
+        // Single-account refresh throws generic errors; treat as transient (exponential backoff).
+        recordFailure(key, nowMs, opts.backoffBaseSeconds, opts.backoffMaxSeconds, false);
+        result.failed.push(key);
+      }
+    });
+  }
+  // B) multi-account Codex pool (gated on the chatgpt provider's policy)
+  if (resolveRefreshPolicy("chatgpt", config) === "proactive") {
+    for (const id of listCodexAccountIds()) {
+      const record = readCodexAccountRecord(id);
+      const cred = record?.deletedAt == null ? record?.credential : undefined;
+      if (!cred) continue;
+      if (cred.expiresAt > nowMs + horizonMs) continue;
+      const key = `codex:${id}`;
+      if (inBackoff(key, nowMs)) { result.skippedBackoff.push(key); continue; }
+      tasks.push(async () => {
+        try {
+          await getValidCodexToken(id);
+          backoff.delete(key);
+          result.refreshed.push(key);
+        } catch (err) {
+          const permanent = err instanceof TokenRefreshError && (err.reason === "revoked" || err.reason === "expired");
+          recordFailure(key, nowMs, opts.backoffBaseSeconds, opts.backoffMaxSeconds, permanent);
+          result.failed.push(key);
+        }
+      });
+    }
+  }
+  await runWithConcurrency(tasks, opts.concurrency);
+  return result;
+}
+/**
+ * Start the background sweep loop. Returns a handle whose stop() clears the pending timer (in-flight
+ * refreshes settle on their own). Schedules recursively so each interval gets fresh jitter. The loop
+ * runs even when the guardian is disabled (each sweep is a cheap no-op) so toggling `enabled` in
+ * config takes effect on the next tick without a restart.
+ */
+export function startTokenGuardian(): TokenGuardianHandle {
+  let stopped = false;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const scheduleNext = () => {
+    if (stopped) return;
+    const opts = resolved(loadConfig().tokenGuardian);
+    const delayMs = (opts.tickSeconds + Math.random() * opts.jitterSeconds) * 1000;
+    timer = setTimeout(runSweep, delayMs);
+    if (typeof timer.unref === "function") timer.unref(); // never keep the process alive for a sweep
+  };
+  const runSweep = () => {
+    void guardianSweep()
+      .then(r => {
+        if (r.enabled && (r.refreshed.length || r.failed.length)) {
+          console.log(`🛡️  token-guardian: refreshed ${r.refreshed.length}, failed ${r.failed.length}`);
+        }
+      })
+      .catch(err => console.log(`token-guardian sweep error: ${err instanceof Error ? err.message : String(err)}`))
+      .finally(scheduleNext);
+  };
+  scheduleNext();
+  return {
+    stop() {
+      stopped = true;
+      if (timer) clearTimeout(timer);
+    },
+  };
+}