@bitkyc08/opencodex 2.67.0 → 2.68.0

package/src/lib/process-control.ts

@@ -261,11 +261,14 @@ async function stopProxyGracefullyDetailed(
     if (!res.ok) return done(false);
     const body: unknown = await res.json().catch(() => null);
     const expectedTeardown = io.deferSharedTeardownNonce ? "deferred" : "performed";
+    // A sibling instance answers `not-owned`: it has no shared teardown to perform, so there is
+    // nothing left over for this caller either. A deferral it was sent is still not confirmed.
     sharedTeardownConfirmed = body !== null
       && typeof body === "object"
       && !Array.isArray(body)
       && "success" in body && body.success === true
-      && "sharedTeardown" in body && body.sharedTeardown === expectedTeardown;
+      && "sharedTeardown" in body && (body.sharedTeardown === expectedTeardown
+        || (!io.deferSharedTeardownNonce && body.sharedTeardown === "not-owned"));
   } catch {
     return done(false);
   }

package/src/lib/system-restart-contract.ts

@@ -12,6 +12,112 @@ export const SYSTEM_RESTART_CAPABILITY_HEADER = "x-opencodex-restart-capability"
 export const MEMORY_DRAIN_RESTART_MS = 60_000;
 export const REPLACEMENT_READY_TIMEOUT_MS = 70_000;
 
+/**
+ * The env var a restarting process hands its replacement `ocx start`: the restarting (parent) pid.
+ *
+ * The replacement can probe while its parent still answers on the port it is about to take over
+ * (a deadline or listener-stop-fallback handoff spawns before the old listener is gone). Without
+ * the marker that answer reads as "a proxy is already running" and the replacement refuses, which
+ * leaves no proxy at all once the parent exits. `handleStart` consumes the marker before any probe
+ * (`src/cli/restart-handoff.ts`), so no later child of the replacement inherits it.
+ */
+export const RESTART_PARENT_PID_ENV = "OCX_RESTART_PARENT_PID";
+
+type RestartEnv = Record<string, string | undefined>;
+
+/** A copy of `env` for this process's own replacement, naming `parentPid` as its restart parent. */
+export function withRestartParentMarker<T extends RestartEnv>(env: T, parentPid: number): T {
+  const next: RestartEnv = { ...env };
+  next[RESTART_PARENT_PID_ENV] = String(parentPid);
+  return next as T;
+}
+
+/**
+ * Consume an inherited restart-parent marker. The marker is removed from `env` either way, and the
+ * pid is honored only when it is this process's actual parent: a stale or hand-set value names a
+ * process that did not spawn this start and never earns the wait.
+ */
+export function takeRestartParentMarker(
+  env: RestartEnv,
+  actualParentPid: number = process.ppid,
+  ownPid: number = process.pid,
+): number | null {
+  const raw = env[RESTART_PARENT_PID_ENV]?.trim() ?? "";
+  delete env[RESTART_PARENT_PID_ENV];
+  if (!/^[1-9]\d{0,9}$/.test(raw)) return null;
+  const pid = Number(raw);
+  if (!Number.isSafeInteger(pid) || pid === ownPid || pid !== actualParentPid) return null;
+  return pid;
+}
+
+/**
+ * The env var the desktop app sets on the `ocx start` it spawns and waits on
+ * (`desktop/src-tauri/src/sidecar.rs`). Under it a restart spawns no detached replacement: it marks
+ * recycling and exits {@link DESKTOP_RESTART_EXIT_CODE}, and the app starts the replacement itself.
+ * A detached grandchild is a process the app can neither see nor stop, and one that failed to start
+ * left no proxy until somebody relaunched the app. `handleStart` consumes the marker before its
+ * first probe, so no child of the runtime inherits it.
+ */
+export const DESKTOP_SUPERVISED_ENV = "OCX_DESKTOP_SUPERVISED";
+/** EX_TEMPFAIL, "run me again": the desktop's supervisor restarts promptly on exactly this code. */
+export const DESKTOP_RESTART_EXIT_CODE = 75;
+/**
+ * The link-mode port-reclaim budget under the desktop app. With the pinned port's prefer-retry after
+ * it (`PINNED_PREFER_RETRY_MS` in `src/client/runtime.ts`) a start that cannot bind gives up within
+ * 25 seconds, inside the app's 30-second startup deadline, so the app sees it exit instead of giving
+ * up on it while it still waits.
+ */
+export const DESKTOP_SUPERVISED_PORT_WAIT_MS = 20_000;
+
+/** The desktop app's pid, recorded when the marker was taken; null when nothing supervises this process. */
+let desktopParentPid: number | null = null;
+
+/**
+ * Consume an inherited desktop-supervision marker, removing it from `env` either way. It is recorded
+ * only against a real parent process, so {@link isDesktopSupervised} can later check that the same
+ * app is still there.
+ */
+export function takeDesktopSupervisedMarker(env: RestartEnv, actualParentPid: number = process.ppid): boolean {
+  const raw = env[DESKTOP_SUPERVISED_ENV]?.trim();
+  delete env[DESKTOP_SUPERVISED_ENV];
+  desktopParentPid = raw === "1" && Number.isSafeInteger(actualParentPid) && actualParentPid > 1
+    ? actualParentPid
+    : null;
+  return desktopParentPid !== null;
+}
+
+export interface DesktopSupervisionIo {
+  parentPid?: () => number;
+  isAlive?: (pid: number) => boolean;
+}
+
+function processExists(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException | null)?.code === "EPERM";
+  }
+}
+
+/**
+ * Whether the desktop app that started this process is still there to start its replacement: the
+ * marker was taken, the parent recorded then is still this process's parent, and it is alive. An app
+ * that crashed leaves the runtime re-parented (POSIX) or its parent dead (Windows), and a restart then
+ * falls back to the detached replacement instead of exiting into nothing. Read only when a restart
+ * or a link-mode start needs it, never on the request path.
+ */
+export function isDesktopSupervised(io: DesktopSupervisionIo = {}): boolean {
+  if (desktopParentPid === null) return false;
+  if ((io.parentPid ?? (() => process.ppid))() !== desktopParentPid) return false;
+  return (io.isAlive ?? processExists)(desktopParentPid);
+}
+
+/** Test seam: forget a marker a test took. */
+export function resetDesktopSupervisionForTests(): void {
+  desktopParentPid = null;
+}
+
 const BASE64URL_256 = /^[A-Za-z0-9_-]{43}$/;
 
 export type ExpectedSystemRestartPid =

package/src/lib/upstream-retry.ts

@@ -847,6 +847,62 @@ export async function refetchAfterProtocolSafeReset(
     console.warn("[upstream-retry] protocol-safe refetch rejected" + label + "; preserving original stream error");
     return null;
   }
-  console.warn("[upstream-retry] pre-output Responses reset" + label + "; using one replacement stream");
+  console.warn("[upstream-retry] pre-output stream reset" + label + "; using one replacement stream");
   return replacement;
 }
+
+/**
+ * Wrap a streamed body so a reset that arrives before the downstream reader has consumed a single
+ * byte swaps in ONE replacement body.
+ *
+ * The zero-byte gate is the whole reason this wrapper exists: the caller observed nothing, which is
+ * the stage where a replacement may even be considered. Every other question -- whether the operator
+ * granted one, whether the request is replayable, whether the replacement is a fresh unlocked body
+ * that matches the contract already promised to the client -- belongs to
+ * {@link refetchAfterProtocolSafeReset}. Delegating rather than re-deciding is what keeps the chat
+ * lane from drifting away from the one the Responses stream already uses.
+ *
+ * Partial output is never masked: once a byte has reached the caller, the original failure stands.
+ */
+export function wrapWithZeroOutputRefetch(
+  body: ReadableStream<Uint8Array>,
+  doFetch: ProtocolSafeRefetch,
+  // `authorize` is optional on the shared options but required here: a zero-output replacement
+  // is always a post-header resend, so every caller must name the gate that weighs it.
+  opts: ProtocolSafeRefetchOptions & { authorize: () => boolean },
+): ReadableStream<Uint8Array> {
+  let reader = body.getReader();
+  let bytesRead = 0;
+  let retried = false;
+  return new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      for (;;) {
+        try {
+          const { done, value } = await reader.read();
+          if (done) {
+            controller.close();
+            return;
+          }
+          bytesRead += value.byteLength;
+          controller.enqueue(value);
+          return;
+        } catch (err) {
+          if (!retried && bytesRead === 0 && !opts.abortSignal?.aborted) {
+            retried = true;
+            const replacement = await refetchAfterProtocolSafeReset(doFetch, err, { ...opts, authorize: opts.authorize });
+            if (replacement?.body) {
+              try { void reader.cancel().catch(() => {}); } catch { /* broken reader; the replacement won */ }
+              reader = replacement.body.getReader();
+              continue;
+            }
+          }
+          try { controller.error(err); } catch { /* already torn down */ }
+          return;
+        }
+      }
+    },
+    cancel(reason) {
+      try { void reader.cancel(reason).catch(() => {}); } catch { /* already torn down */ }
+    },
+  });
+}

package/src/link/ports.ts

@@ -7,6 +7,15 @@
 export const MIN_LINK_PORT = 1024;
 export const MAX_LINK_PORT = 65535;
 
+/**
+ * A Child joining from its dashboard picks its tunnel port from this range. It sits below the
+ * common OS ephemeral ranges (macOS and Windows 49152-65535, Linux 32768-60999), so an outgoing
+ * connection that happens to hold the port rarely blocks the tunnel when it comes back after a
+ * reboot. The persisted port of an existing link is never rewritten.
+ */
+export const JOIN_TUNNEL_PORT_MIN = 20_000;
+export const JOIN_TUNNEL_PORT_MAX = 29_999;
+
 export function isLinkPort(value: unknown): value is number {
   return typeof value === "number" && Number.isInteger(value) && value >= MIN_LINK_PORT && value <= MAX_LINK_PORT;
 }

package/src/link/ssh-argv.ts

@@ -12,6 +12,8 @@
  * - Tunnel and exec commands use StrictHostKeyChecking=yes. Only the probe uses accept-new,
  *   against an empty temporary file, so the key it records can be shown to the user first.
  * - Forwards always bind 127.0.0.1 on both ends.
+ * - Remote ocx runs through `remoteOcxArgv`: a non-interactive ssh session reads no interactive
+ *   profile, so ~/.bun/bin and Homebrew are usually missing from the remote PATH.
  */
 
 import { isAbsolute } from "node:path";
@@ -129,6 +131,20 @@ export function buildExecArgv(options: ExecArgvOptions): string[] {
   ];
 }
 
+/**
+ * The remote sh script for every ocx call. `quoteRemote` single-quotes it, so the login shell
+ * passes it through untouched and `$HOME`/`$PATH` expand in the remote `sh`; the arguments reach
+ * ocx as `"$@"` without another round of parsing. The fallback directories are appended, so an
+ * ocx the remote PATH already resolves keeps winning. A missing ocx exits 127.
+ */
+export const REMOTE_OCX_SCRIPT = 'PATH="$PATH:$HOME/.bun/bin:$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin"; exec ocx "$@"';
+/** The POSIX shell's exit status for a command it could not find. */
+export const REMOTE_COMMAND_NOT_FOUND = 127;
+
+export function remoteOcxArgv(args: readonly string[]): string[] {
+  return ["sh", "-c", REMOTE_OCX_SCRIPT, "ocx", ...args];
+}
+
 export interface ProbeArgvOptions {
   alias: string;
   /** An empty, private, temporary file. The probe records the offered host key here. */

package/src/link/ssh-runner.ts

@@ -1,4 +1,66 @@
+import { homedir } from "node:os";
+
 const DEFAULT_OUTPUT_BYTES = 64 * 1024;
+const HINT_MAX_CHARS = 160;
+// Written as escapes on purpose: invisible and bidi controls must never sit literally in source.
+const ANSI_SEQUENCE = /\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)|\u001b\[[0-?]*[ -/]*[@-~]|\u001b[@-_]/g;
+const HINT_CONTROL = /[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u202a-\u202e\u2060-\u206f\ufeff]/g;
+const HINT_SECRET = /\bocx_(data|admin|session|pair)_[A-Za-z0-9_-]+/g;
+const HINT_URL_QUERY = /\b(https?:\/\/[^\s?#]*)[?#]\S*/g;
+
+type SpawnEnv = Record<string, string | undefined>;
+
+/**
+ * PATH for ssh and ssh-keygen children on POSIX. A desktop sidecar inherits launchd's minimal
+ * PATH, so a ProxyCommand helper installed by Homebrew or into ~/.bun/bin would not resolve.
+ * Inherited entries keep their order and precedence; the common helper directories are appended
+ * once. Windows keeps its inherited environment untouched and gets undefined.
+ */
+export function linkSshPath(env: SpawnEnv = process.env, platform: NodeJS.Platform = process.platform): string | undefined {
+  if (platform === "win32") return undefined;
+  const home = env.HOME || homedir();
+  const extra = ["/opt/homebrew/bin", "/usr/local/bin", ...(home ? [`${home}/.bun/bin`, `${home}/.local/bin`] : [])];
+  return [...new Set([...(env.PATH ?? "").split(":").filter(Boolean), ...extra])].join(":");
+}
+
+/** The environment ssh runs with: the inherited one with `linkSshPath`, or undefined on Windows. */
+export function linkSshSpawnEnv(env: SpawnEnv = process.env, platform: NodeJS.Platform = process.platform): SpawnEnv | undefined {
+  const path = linkSshPath(env, platform);
+  return path === undefined ? undefined : { ...env, PATH: path };
+}
+
+/**
+ * One hint line as the dashboard may see it: control and bidi characters removed, OpenCodex
+ * secrets and URL queries redacted, whitespace collapsed, capped at 160 code points. The cut is
+ * made between code points, so an astral character is never split into a lone surrogate.
+ */
+export function boundHint(line: string): string | undefined {
+  const clean = line.replace(HINT_CONTROL, " ").replace(HINT_SECRET, "ocx_$1_[redacted]")
+    .replace(HINT_URL_QUERY, "$1").replace(/\s+/g, " ").trim();
+  if (!clean) return undefined;
+  const points = Array.from(clean);
+  return points.length > HINT_MAX_CHARS ? `${points.slice(0, HINT_MAX_CHARS - 1).join("")}\u2026` : clean;
+}
+
+/**
+ * A short reason for a failed ssh command: the last non-empty stderr line, with terminal escapes,
+ * control and bidi characters removed, OpenCodex secrets and URL queries redacted, capped at 160
+ * code points. It reads stderr only; stdout and stdin can carry keys. Callers return it to the
+ * dashboard and never log it.
+ */
+export function sshFailureHint(stderr: string): string | undefined {
+  const lines = stderr.replace(ANSI_SEQUENCE, "").split(/\r\n|\r|\n/);
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    const hint = boundHint(lines[index]!);
+    if (hint) return hint;
+  }
+  return undefined;
+}
+
+/** The runner's own failure (spawn, timeout, output limit) as a hint; other errors give none. */
+export function sshRunnerErrorHint(error: unknown): string | undefined {
+  return error instanceof SshRunnerError ? boundHint(error.message) : undefined;
+}
 
 export interface SshRunResult {
   code: number;
@@ -71,14 +133,19 @@ function defaultKill(process: Bun.Subprocess, signal?: NodeJS.Signals): void {
   process.kill(signal);
 }
 
-export function createSshRunner(deps: { spawn?: typeof Bun.spawn; timeoutMs?: number } = {}): SshRunner {
+export function createSshRunner(deps: { spawn?: typeof Bun.spawn; timeoutMs?: number; env?: () => SpawnEnv | undefined } = {}): SshRunner {
   const spawn = deps.spawn ?? ((argv, options) => Bun.spawn(argv, options));
   const defaultTimeoutMs = deps.timeoutMs ?? 30_000;
+  // Read per spawn so a PATH change reaches the next command; Windows passes no env key at all.
+  const spawnEnv = (): { env?: SpawnEnv } => {
+    const env = (deps.env ?? (() => linkSshSpawnEnv()))();
+    return env ? { env } : {};
+  };
 
   const spawnChild = (argv: readonly string[]): SshChild => {
     let child: Bun.Subprocess;
     try {
-      child = spawn([...argv], { stdin: "ignore", stdout: "pipe", stderr: "pipe" });
+      child = spawn([...argv], { stdin: "ignore", stdout: "pipe", stderr: "pipe", ...spawnEnv() });
     } catch (error) {
       throw new SshRunnerError("spawn", `could not spawn ${argv[0] ?? "ssh"}`, { cause: error });
     }
@@ -108,6 +175,7 @@ export function createSshRunner(deps: { spawn?: typeof Bun.spawn; timeoutMs?: nu
           stdin: options.stdin === undefined ? "ignore" : "pipe",
           stdout: "pipe",
           stderr: "pipe",
+          ...spawnEnv(),
         });
       } catch (error) {
         throw new SshRunnerError("spawn", `could not spawn ${argv[0] ?? "ssh"}`, { cause: error });

package/src/link/tunnel-state.ts

@@ -5,8 +5,11 @@
  * - connected: the forward is up.
  * - reconnecting: a transient failure; requests through the link fail with 503 meanwhile, and a
  *   new attempt is due at `retryAt`.
- * - failed: needs the user. Auth, host key and forward failures are not retried, and neither is a
- *   link that stayed down for FAILED_AFTER_MS.
+ * - failed: auth, host key and forward failures, and a link that stayed down for FAILED_AFTER_MS.
+ *   Without a retry policy (the Home's `-R` supervisor) it needs the user. With one (the Child's
+ *   own `-L` tunnel) a reason that has a delay is tried again at `retryAt`, and the retry attempt
+ *   runs with `inFlight` while the state still reads failed; a reason without a delay stays
+ *   terminal.
  */
 
 export type TunnelFailure = "auth" | "hostkey" | "forward" | "timeout";
@@ -17,7 +20,7 @@ export type TunnelState =
   | { kind: "connecting"; since: number }
   | { kind: "connected"; since: number }
   | { kind: "reconnecting"; since: number; attempt: number; retryAt: number; inFlight: boolean }
-  | { kind: "failed"; since: number; reason: TunnelFailure };
+  | { kind: "failed"; since: number; reason: TunnelFailure; retryAt?: number; inFlight?: boolean };
 
 export type TunnelEvent =
   | { type: "spawn"; now: number }
@@ -26,10 +29,25 @@ export type TunnelEvent =
   | { type: "tick"; now: number }
   | { type: "stop" };
 
+/** Opt-in retry of a failed tunnel: the delay before each failure reason is tried again. */
+export interface TunnelRetryPolicy {
+  retryFailedAfterMs: Partial<Record<TunnelFailure, number>>;
+}
+
 export const FAILED_AFTER_MS = 5 * 60_000;
 export const BASE_DELAY_MS = 1_000;
 export const MAX_DELAY_MS = 30_000;
 
+/**
+ * The client-owned tunnel's policy. Timeout and forward failures retry about once a minute. Auth
+ * retries every five minutes, and because each auth failure schedules the next attempt five
+ * minutes out, no more than 12 attempts reach the Home's sshd in an hour. A changed host key is a
+ * security signal and is never retried.
+ */
+export const CLIENT_TUNNEL_RETRY_POLICY: TunnelRetryPolicy = {
+  retryFailedAfterMs: { timeout: 60_000, forward: 60_000, auth: 5 * 60_000 },
+};
+
 export const IDLE: TunnelState = { kind: "idle" };
 
 /** Capped exponential backoff with ±20% jitter. `random` is injectable for tests. */
@@ -40,22 +58,52 @@ export function nextDelayMs(attempt: number, random: () => number = Math.random)
   return Math.round(Math.min(MAX_DELAY_MS, base * jitter));
 }
 
-export function reduceTunnel(state: TunnelState, event: TunnelEvent, random?: () => number): TunnelState {
+/** A failed state; under a policy that retries `reason` it carries the next attempt's time. */
+export function failedTunnel(
+  reason: TunnelFailure,
+  now: number,
+  policy?: TunnelRetryPolicy,
+  since: number = now,
+): TunnelState {
+  const delay = policy?.retryFailedAfterMs[reason];
+  return delay === undefined
+    ? { kind: "failed", since, reason }
+    : { kind: "failed", since, reason, retryAt: now + delay, inFlight: false };
+}
+
+function failureOf(cls: StderrClass): TunnelFailure | null {
+  return cls === "auth" || cls === "hostkey" || cls === "forward" ? cls : null;
+}
+
+export function reduceTunnel(
+  state: TunnelState,
+  event: TunnelEvent,
+  random?: () => number,
+  policy?: TunnelRetryPolicy,
+): TunnelState {
   if (event.type === "stop") return IDLE;
   switch (event.type) {
     case "spawn":
+      if (state.kind === "failed" && state.retryAt !== undefined) return { ...state, inFlight: true };
       if (state.kind === "idle" || state.kind === "failed") return { kind: "connecting", since: event.now };
       if (state.kind === "reconnecting") return { ...state, inFlight: true };
       return state;
     case "ready":
       if (state.kind === "connecting" || state.kind === "reconnecting") return { kind: "connected", since: event.now };
+      if (state.kind === "failed" && state.inFlight) return { kind: "connected", since: event.now };
       return state;
     case "exit": {
-      if (state.kind === "idle" || state.kind === "failed") return state;
-      const cls = event.stderrClass;
-      if (cls === "auth" || cls === "hostkey" || cls === "forward") return { kind: "failed", since: event.now, reason: cls };
+      if (state.kind === "idle") return state;
+      if (state.kind === "failed") {
+        if (!state.inFlight) return state;
+        // A retry of a failed link failed again. It stays failed from the original moment; a
+        // transient exit keeps the slow cadence (timeout) instead of restarting fast backoff.
+        return failedTunnel(failureOf(event.stderrClass) ?? "timeout", event.now, policy, state.since);
+      }
+      const failure = failureOf(event.stderrClass);
+      if (failure) return failedTunnel(failure, event.now, policy);
       const since = state.kind === "reconnecting" || state.kind === "connecting" ? state.since : event.now;
-      if (event.now - since >= FAILED_AFTER_MS) return { kind: "failed", since: event.now, reason: "timeout" };
+      if (event.now - since >= FAILED_AFTER_MS) return failedTunnel("timeout", event.now, policy);
       const attempt = state.kind === "reconnecting" ? state.attempt + 1 : 1;
       return { kind: "reconnecting", since, attempt, retryAt: event.now + nextDelayMs(attempt, random), inFlight: false };
     }
@@ -63,7 +111,7 @@ export function reduceTunnel(state: TunnelState, event: TunnelEvent, random?: ()
       // An attempt in flight does not pause the clock: a first attempt or a retry that hangs past
       // the limit still fails the link, and the supervisor kills the child on seeing `failed`.
       if ((state.kind === "reconnecting" || state.kind === "connecting") && event.now - state.since >= FAILED_AFTER_MS) {
-        return { kind: "failed", since: event.now, reason: "timeout" };
+        return failedTunnel("timeout", event.now, policy);
       }
       return state;
   }
@@ -71,6 +119,7 @@ export function reduceTunnel(state: TunnelState, event: TunnelEvent, random?: ()
 
 /** Whether the supervisor should start a new ssh attempt now. */
 export function dueForSpawn(state: TunnelState, now: number): boolean {
+  if (state.kind === "failed") return state.retryAt !== undefined && !state.inFlight && now >= state.retryAt;
   return state.kind === "reconnecting" && !state.inFlight && now >= state.retryAt;
 }
 

package/src/oauth/account-quota-rank.ts

@@ -11,7 +11,8 @@
  * serve the retry" — and within the healthy group a simple headroom sort is enough.
  */
 import { getCachedProviderAccountQuota, hasPassiveAccountQuota } from "../providers/quota";
-import { getKiroAccountExhaustion } from "../providers/kiro-usage";
+import { kiroAccountEvidence } from "../providers/kiro-usage";
+import type { ProviderAccount } from "./types";
 
 /** Antigravity hosts Gemini and Claude windows on one account; ranking must not mix them. */
 export type QuotaModelFamily = "gem" | "cla";
@@ -83,8 +84,11 @@ const PASSIVE_HEADROOM_MAX_AGE_MS = 60 * 60_000;
 * The minimum wins: an account at 5% of its five-hour window is unusable right now even if
 * its monthly allowance is barely touched.
 */
-function headroomOf(provider: string, accountId: string, requestedModelId?: string | null): number | null {
-  const quota = getCachedProviderAccountQuota(provider, accountId);
+function headroomOf(provider: string, accountId: string, requestedModelId?: string | null, account?: ProviderAccount): number | null {
+  const evidence = provider === "kiro" && account ? kiroAccountEvidence(account) : null;
+  const quota = provider === "kiro"
+    ? evidence?.quotaPercent === undefined ? null : { monthlyPercent: evidence.quotaPercent, updatedAt: Date.now() }
+    : getCachedProviderAccountQuota(provider, accountId);
   if (!quota) return null;
   // Null, not a low rank: this must reproduce "no evidence" so a stale roster degrades to
   // the unranked ring rather than to a differently wrong answer.
@@ -119,8 +123,9 @@ export function accountHeadroomPercent(
   provider: string,
   accountId: string,
   requestedModelId?: string | null,
+  account?: ProviderAccount,
 ): number | null {
-  return headroomOf(provider, accountId, requestedModelId);
+  return headroomOf(provider, accountId, requestedModelId, account);
 }
 
 /** Unknown usage is not exhaustion; Kiro's explicit overage verdict is authoritative. */
@@ -128,10 +133,10 @@ export function isAccountQuotaExhausted(
   provider: string,
   accountId: string,
   requestedModelId?: string | null,
+  account?: ProviderAccount,
 ): boolean {
-  const exhaustion = provider === "kiro" ? getKiroAccountExhaustion(`${provider}\u0000${accountId}`) : null;
-  if (exhaustion !== null) return exhaustion.exhausted;
-  const headroom = headroomOf(provider, accountId, requestedModelId);
+  if (provider === "kiro") return account ? kiroAccountEvidence(account).exhausted === true : false;
+  const headroom = headroomOf(provider, accountId, requestedModelId, account);
   return headroom !== null && headroom <= 0;
 }
 
@@ -145,6 +150,7 @@ export function rankAccountsByHeadroom(
   provider: string,
   ring: readonly string[],
   requestedModelId?: string | null,
+  accounts?: ReadonlyMap<string, ProviderAccount>,
 ): string[] {
   if (ring.length < 2) return [...ring];
 
@@ -158,11 +164,14 @@ export function rankAccountsByHeadroom(
   const ranked: Ranked[] = ring.map((id, index) => {
     // A provider-declared exhaustion verdict outranks the percentage: an account may sit at
     // 100% and still be servable when overage is enabled, and the verdict knows that.
-    const exhaustion = provider === "kiro" ? getKiroAccountExhaustion(`${provider}\u0000${id}`) : null;
-    const headroom = headroomOf(provider, id, requestedModelId);
-    if (exhaustion !== null || headroom !== null) sawEvidence = true;
-
-    if (isAccountQuotaExhausted(provider, id, requestedModelId)) return { id, bucket: RANK_EXHAUSTED, headroom: 0, index };
+    const account = accounts?.get(id);
+    const exhaustion = provider === "kiro" && account ? kiroAccountEvidence(account).exhausted : undefined;
+    const headroom = headroomOf(provider, id, requestedModelId, account);
+    if (exhaustion !== undefined || headroom !== null) sawEvidence = true;
+
+    if (isAccountQuotaExhausted(provider, id, requestedModelId, account)
+      || (provider === "kiro" && exhaustion === undefined && headroom !== null && headroom <= 0))
+      return { id, bucket: RANK_EXHAUSTED, headroom: 0, index };
     if (headroom === null) return { id, bucket: RANK_UNKNOWN, headroom: 0, index };
     return { id, bucket: RANK_HEALTHY, headroom, index };
   });
@@ -186,6 +195,7 @@ export function hasHeadroomEvidence(
   provider: string,
   ids: readonly string[],
   requestedModelId?: string | null,
+  accounts?: ReadonlyMap<string, ProviderAccount>,
 ): boolean {
   // A PASSIVE provider needs evidence for EVERY candidate, not any one of them.
   //
@@ -200,8 +210,9 @@ export function hasHeadroomEvidence(
     return ids.length > 0 && ids.every(id => headroomOf(provider, id, requestedModelId) !== null);
   }
   return ids.some(id =>
-    headroomOf(provider, id, requestedModelId) !== null
-    || (provider === "kiro" && getKiroAccountExhaustion(`${provider}\u0000${id}`) !== null));
+    headroomOf(provider, id, requestedModelId, accounts?.get(id)) !== null
+    || (provider === "kiro" && accounts?.get(id) !== undefined
+      && kiroAccountEvidence(accounts.get(id)!).exhausted !== undefined));
 }
 /**
  * How long to cool an account that just 429'd, when we know its allowance is spent.
@@ -213,10 +224,10 @@ export function hasHeadroomEvidence(
 const MIN_EXHAUSTED_COOLDOWN_MS = 5 * 60_000;
 const MAX_EXHAUSTED_COOLDOWN_MS = 24 * 60 * 60_000;
 
-export function exhaustedCooldownMs(provider: string, accountId: string, now = Date.now()): number | null {
+export function exhaustedCooldownMs(provider: string, accountId: string, now = Date.now(), account?: ProviderAccount): number | null {
   if (provider !== "kiro") return null;
-  const exhaustion = getKiroAccountExhaustion(`${provider}\u0000${accountId}`, now);
-  if (!exhaustion?.exhausted) return null;
-  const untilReset = exhaustion.nextResetAt === undefined ? MIN_EXHAUSTED_COOLDOWN_MS : exhaustion.nextResetAt - now;
+  const evidence = account ? kiroAccountEvidence(account, now) : {};
+  if (!evidence.exhausted) return null;
+  const untilReset = evidence.resetAt === undefined ? MIN_EXHAUSTED_COOLDOWN_MS : evidence.resetAt - now;
   return Math.min(Math.max(untilReset, MIN_EXHAUSTED_COOLDOWN_MS), MAX_EXHAUSTED_COOLDOWN_MS);
 }