opencode-auth-load-balancer 0.2.1

package/dist/usage-refresh.d.ts

@@ -0,0 +1,30 @@
+import type { ProviderAdapter } from './providers/types';
+import type { PoolFile } from './types';
+/**
+ * Test-only window into the module-private `lastPoll` throttle map. Never
+ * imported by production code — only by usage-refresh tests that need to
+ * assert on the prune's exact membership (a net-neutral delete+re-add cycle
+ * cannot be distinguished by fetchUsage call counts alone, since a freshly
+ * added account never collides with a stale id).
+ */
+export declare function _lastPollIdsForTests(): Set<string>;
+/**
+ * Best-effort: seed/refresh usage for accounts whose WEEKLY snapshot is missing or
+ * stale (`capturedAt` is stamped only when a weekly window arrives — see
+ * `applyUsagePartial` in fetch.ts), via the provider's dedicated usage endpoint.
+ * Throttled per account (at most one poll per account per SEED_TTL_MS). Callers
+ * invoke it fire-and-forget, so it adds no latency to the request path; failures
+ * are swallowed — response headers remain the primary, always-fresh usage signal
+ * and this fixes cold-start blindness AND out-of-band server-side resets (e.g. a
+ * promotional weekly-quota reset) that response headers alone don't converge.
+ *
+ * Returns a promise (for tests / explicit awaiting); request-path callers ignore it.
+ *
+ * `poolSnapshot` lets the request hot path reuse the pool it JUST read for
+ * account selection instead of paying a second serialized file read +
+ * JSON.parse per request. The snapshot is only consulted for the staleness
+ * gates below; the actual usage write still goes through `mutatePool` (which
+ * re-reads under the lock), so a slightly stale snapshot is harmless. Callers
+ * without a pool in hand (e.g. the startup seed in index.ts) omit it.
+ */
+export declare function refreshUsageInBackground(adapter: ProviderAdapter, now: number, poolSnapshot?: PoolFile): Promise<void>;

package/dist/util.d.ts

@@ -0,0 +1,118 @@
+/** Shared no-op for swallowing rejected promises / throwaway callbacks. */
+export declare const ignore: () => undefined;
+/** Shared async sleep — used by the pool's lock-retry and atomic-rename loops. */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Abortable sleep. Resolves after `ms`, or rejects with the signal's abort reason the
+ * moment `signal` aborts — so a request waiting out a rate-limit cooldown (see fetch.ts)
+ * wakes IMMEDIATELY when opencode cancels the turn instead of blocking the full delay.
+ * Falls back to the plain `sleep` when no signal is given. The abort reason is propagated
+ * untouched (a DOMException named `AbortError` by default), which fetch.ts recognizes as
+ * a client abort and re-throws rather than treating as the account's fault.
+ */
+export declare function sleepAbortable(ms: number, signal?: AbortSignal): Promise<void>;
+/**
+ * Clamp a number into [0, 1], treating NaN/Infinity as 0. Used by both provider
+ * usage parsers to normalize header/endpoint utilization into the contract the
+ * scheduler expects (a finite fraction). NOTE: `src/scheduler/score-core.ts` ships
+ * its OWN identical clamp01 by design — that file is byte-copied into
+ * `tui/auth-load-balancer-scoring.ts` and MUST stay dependency-free (enforced by
+ * `tui-scoring-sync.test.ts`), so this helper covers the providers only.
+ */
+export declare function clamp01(n: number): number;
+/**
+ * Type guard: a real, finite number (rejects NaN/±Infinity AND non-numbers).
+ * Shared by both providers' `endpointWindow` malformed-window checks, where
+ * the `v is number` narrowing also handles optional fields. NOTE:
+ * `tui/auth-load-balancer-tui.logic.ts` ships its OWN `isFiniteNumber` copy
+ * by design — the TUI runtime cannot import `src/`.
+ */
+export declare function isFiniteNumber(v: unknown): v is number;
+/**
+ * True for a plain JSON object (non-null `object`, not an array). Shared
+ * trust-boundary predicate for the two consumers that accept arbitrary JSON
+ * shapes: the user-editable pool file's `lastSelected` / `sessions`
+ * containers and session rows (`pool/store.ts`), and the incoming `system`
+ * prompt blocks in the Anthropic request transform
+ * (`providers/anthropic/transform.ts`). NOTE:
+ * `tui/auth-load-balancer-tui.logic.ts` ships its OWN `isPlainRecordValue`
+ * copy by design — the TUI runtime cannot import `src/`.
+ */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Collect the `text` of every content block into one string. A message's
+ * `content` arrives as either a plain string (passed through) or an array of
+ * blocks (anything else → ''); each block contributes its `text` when it is a
+ * string, and non-empty texts are joined with `separator`. Shared by the
+ * session-key hasher (`session.ts`, `''` join) and the Codex instructions
+ * lifter (`providers/openai/transform.ts`, `'\n'` join) — previously two
+ * copy-pasted 15-line walkers. NOTE: `providers/anthropic/cch.ts`'s
+ * `messageText` is deliberately different (FIRST text block only) — not this.
+ */
+export declare function joinBlockTexts(content: unknown, separator: string): string;
+/**
+ * Set `key`→`value` on a bounded `Map`, clearing it first once it is already
+ * at `max` — a "clear-on-full" cache eviction with no LRU bookkeeping,
+ * appropriate for the three call sites that only need a rough memory cap, not
+ * exact recency: `sanitizeCache` in `providers/anthropic/transform.ts`,
+ * `cachedHeader` in `providers/anthropic/cch.ts`, and `lastFallbackToasted`
+ * in `notify.ts`. The first two were previously the same 2-line
+ * `if (map.size >= max) map.clear(); map.set(key, value)` block, each
+ * commented as duplicating the other — this is that logic unified. Each call
+ * site keeps its own cap constant and key/value semantics; only the eviction
+ * mechanics are shared.
+ */
+export declare function setBounded<K, V>(map: Map<K, V>, key: K, value: V, max: number): void;
+/**
+ * A single-slot memo keyed by a raw value compared with `===`. Returns a
+ * closure that recomputes only when the key changes since the last call —
+ * the "cache the value derived from a raw env/token string, keyed by that
+ * string" pattern previously hand-rolled four separate times across the
+ * Anthropic provider module (`mergeBetaHeaders`/`resolveBaseUrl` in
+ * `providers/anthropic/transform.ts`, `resolveFamilyOrder`/
+ * `resolveFallbackSetting` in `providers/anthropic/fallback.ts`). Each
+ * caller keeps any fast-path early return (e.g. "no raw value at all")
+ * BEFORE calling into this memo — the memo only covers the "check cache,
+ * else compute and reseat" part. NOTE: `providers/openai/jwt.ts`'s
+ * `resolveAccountId` needed a MULTI-slot `Map` variant instead of this
+ * (a one-slot memo thrashes there because the plugin decodes MULTIPLE
+ * OpenAI accounts' access tokens concurrently — see that file's own
+ * `decodedAccountIdCache` doc comment). `src/scheduler/score-core.ts`
+ * deliberately does NOT use this either — that file is byte-copied into
+ * `tui/auth-load-balancer-scoring.ts` and must stay dependency-free.
+ */
+export declare function memoOne<K, V>(compute: (key: K) => V): (key: K) => V;
+/**
+ * True when `candidateMs` (an absolute epoch-ms reset timestamp) sits further
+ * in the future than `MAX_QUOTA_RESET_BOUND_MS` past the real wall clock — used to
+ * reject a FINITE-but-absurd reset (e.g. a corrupted proxy emitting
+ * `99999999999` seconds ≈ year 5138) that would otherwise silently become the
+ * account's `resetAt`, permanently near-zero-ranking it in `weeklyUrgency`
+ * (days² in the denominator) and printing a nonsensical "115200d" countdown.
+ * Shared by `secondsToMs` (below) and Anthropic's `parseResetAt`
+ * (providers/anthropic/usage.ts), which cannot delegate to `secondsToMs`
+ * itself (different seconds-vs-ms-vs-ISO-string semantics) but needs the
+ * exact same "how far in the future is too far" guard. Reads the REAL wall
+ * clock (not an injected `now`) because every caller parses a response/
+ * endpoint payload at essentially the moment it arrives — there is no
+ * meaningful test-injectable `now` to thread through the provider
+ * `parseUsageHeaders`/endpoint-parsing call chain the way `cooldownUntilFrom`
+ * (fetch.ts) threads an already-captured `now`. A value in the PAST always
+ * passes (returns false) — an elapsed reset is simply "expired", handled
+ * elsewhere (`isWindowExpired`), not a broken-clock symptom.
+ */
+export declare function isImplausiblyFarFuture(candidateMs: number): boolean;
+/**
+ * Convert epoch-seconds → epoch-ms while rejecting non-finite/zero/negative inputs,
+ * the `Number.MAX_VALUE`-overflow case (`1e308` is finite but `1e308 * 1000`
+ * collapses to +Infinity), AND a finite-but-implausibly-far-future reset (see
+ * `isImplausiblyFarFuture`) — any of which would silently commit a corrupt value to
+ * `pool.usage.{hourly,weekly}.resetAt`, breaking `isWindowExpired`, `weeklyUrgency`,
+ * and `relTime` rendering. Returns 0 to signal "no usable reset". Mirrors
+ * `cooldownUntilFrom`'s retry-after guard in `fetch.ts` (cooldown's
+ * `until = now + delta` shape differs, so it is NOT folded in here). Used by both
+ * provider header parsers and the OpenAI endpoint helper. Anthropic's `parseResetAt`
+ * ms-vs-seconds heuristic (`value > 1e12`) intentionally stays separate — different
+ * semantics.
+ */
+export declare function secondsToMs(resetSec: number): number;

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "opencode-auth-load-balancer",
+  "version": "0.2.1",
+  "description": "Load-balance opencode requests across multiple Anthropic (Claude) and OpenAI (Codex) OAuth accounts, weighted primarily by weekly usage with drain-before-reset scheduling.",
+  "type": "module",
+  "license": "MIT",
+  "author": "owjs3901",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/owjs3901/opencode-auth-load-balancer.git"
+  },
+  "homepage": "https://github.com/owjs3901/opencode-auth-load-balancer#readme",
+  "bugs": {
+    "url": "https://github.com/owjs3901/opencode-auth-load-balancer/issues"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "tui"
+  ],
+  "scripts": {
+    "sync:tui": "bun -e \"await Bun.write('tui/auth-load-balancer-scoring.ts', Bun.file('src/scheduler/score-core.ts'))\"",
+    "build": "bun run sync:tui && bun build ./src/index.ts --outdir dist --target node --format esm && tsc -p tsconfig.build.json",
+    "dev": "bun build ./src/index.ts --outdir dist --target node --format esm --watch",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.tui.json --noEmit",
+    "typecheck:tui": "tsc -p tsconfig.tui.json --noEmit",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "status": "bun run src/cli/status.ts",
+    "changepacks": "bunx @changepacks/cli",
+    "prepare": "husky"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.17.13"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.17.13",
+    "@opentui/core": "0.4.2",
+    "@opentui/solid": "0.4.2",
+    "@types/bun": "^1.3.14",
+    "@types/node": "^26.1.0",
+    "eslint-plugin-devup": "^2.0.19",
+    "husky": "^9.1",
+    "oxlint": "1.72",
+    "solid-js": "1.9.14",
+    "typescript": "^6.0.3"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "anthropic",
+    "claude",
+    "openai",
+    "codex",
+    "oauth",
+    "load-balancer"
+  ],
+  "engines": {
+    "node": ">=18",
+    "bun": ">=1.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/tui/auth-load-balancer-scoring.ts

@@ -0,0 +1,344 @@
+/**
+ * Pure account-scoring core — the SINGLE SOURCE OF TRUTH for how the load balancer
+ * ranks accounts. Imported by the server scheduler AND the standalone TUI view, which
+ * loads a byte-identical copy installed alongside it
+ * (`tui/auth-load-balancer-scoring.ts`, kept in sync by a build step + a test). Keeping
+ * the formula in one place means the dashboard's ranking can never silently drift from
+ * what the scheduler actually picks (which it once did, as duplicated copies).
+ *
+ * This module MUST stay dependency-free (only `process.env`) so the TUI view can load a
+ * single copied file without resolving the rest of `src/`.
+ */
+
+/** Tunable scoring knobs (the subset of the scheduler config that affects ranking). */
+export interface ScoreConfig {
+  /**
+   * How much the 5h-window headroom modulates the weekly-urgency score, in [0,1].
+   * 0 = ignore the 5h window; 1 = an account with no 5h headroom scores 0. Applied
+   * multiplicatively so it de-rates within the weekly ordering but never flips it.
+   */
+  hourlyInfluence: number
+  /** Floor for time-until-reset (ms). Caps how large urgency can grow near a reset. */
+  minResetMs: number
+  /** Baseline horizon (ms) used when an account's weekly reset time is unknown/stale. */
+  weekWindowMs: number
+  /**
+   * Hard exhaustion: utilization >= this excludes the account entirely while others
+   * have headroom, and forces a pinned session off it regardless of switch cost.
+   */
+  exhaustedAt: number
+  /**
+   * Soft threshold for the SHORT 5h window: proactively migrate a pinned session once
+   * its 5h utilization crosses this — before it hard-exhausts at `exhaustedAt`. Must be
+   * < exhaustedAt. (The WEEKLY window migrates at the higher `weeklyDrainTarget`.)
+   */
+  migrateAt: number
+  /**
+   * Weekly drain target (default 0.98): scoring treats weekly quota as "fully drained"
+   * at this utilization (the account stops being favored past it), and a pinned session
+   * proactively migrates once its WEEKLY util crosses it — so perishable weekly quota is
+   * drained close to full before the window resets. In (migrateAt, exhaustedAt].
+   */
+  weeklyDrainTarget: number
+}
+
+/** A single rate-limit window slice the scoring reads. */
+export interface ScoreWindow {
+  utilization: number
+  resetAt: number
+}
+
+/**
+ * The slice of an account the scoring reads. The server's full `PoolAccount` and the
+ * TUI's parsed-pool account both satisfy this (the TUI normalizes its looser JSON into
+ * this shape before scoring).
+ */
+export interface ScoreAccount {
+  usage: {
+    hourly: ScoreWindow | null
+    weekly: ScoreWindow | null
+  }
+  cooldownUntil: number
+  disabledReason: string | null
+}
+
+const DAY_MS = 24 * 60 * 60 * 1000
+/**
+ * Weekly windows repeat on FIXED per-account anchors every 7 days (see
+ * usage-merge.ts). Exported so `usage-merge.ts` (an ordinary `src/` file with
+ * no dependency-free constraint) can import this single source instead of
+ * computing the same 604800000ms constant independently — `score-core.ts`
+ * itself still imports nothing, so the TUI's byte-identical copy stays
+ * dependency-free.
+ */
+export const WEEK_MS = 7 * DAY_MS
+const HOUR_MS = 60 * 60 * 1000
+/** The ~5h short rolling window (Anthropic 5h ≈ Codex primary). */
+const HOURLY_WINDOW_MS = 5 * HOUR_MS
+/**
+ * ~6h cushion added to time-to-reset so an imminent reset stays urgent without the score
+ * exploding toward infinity at the reset instant (and so tiny crumbs near a reset don't
+ * dominate). In days.
+ */
+const RESET_CUSHION_DAYS = 0.25
+
+/** Scoring-config defaults (the scoring subset of the scheduler's DEFAULT_CONFIG). */
+export const SCORE_DEFAULTS: ScoreConfig = {
+  hourlyInfluence: 0.5,
+  minResetMs: 5 * 60 * 1000, // 5 minutes
+  weekWindowMs: WEEK_MS, // 7 days
+  exhaustedAt: 0.999,
+  migrateAt: 0.95,
+  weeklyDrainTarget: 0.98,
+}
+
+/**
+ * Parse one numeric env override: missing/empty → default, non-finite → default.
+ * The SINGLE parsing contract for every numeric `OPENCODE_AUTH_LB_*` knob — shared
+ * by `loadScoreConfig` below and the server-only `loadConfig` in
+ * `src/scheduler/config.ts`, so the two loaders can never silently diverge.
+ */
+export function readEnvNumber(
+  env: Record<string, string | undefined>,
+  key: string,
+  dflt: number,
+): number {
+  const raw = env[key]
+  // trim(): a whitespace-only value must fall back too — `Number('  ') === 0`
+  // (finite), so it would otherwise silently zero the knob instead of using
+  // the default. The bool parser in config.ts trims the same way.
+  if (raw === undefined || raw.trim() === '') return dflt
+  const n = Number(raw)
+  return Number.isFinite(n) ? n : dflt
+}
+
+/** Read scoring overrides from env (OPENCODE_AUTH_LB_*), falling back to SCORE_DEFAULTS. */
+export function loadScoreConfig(
+  env: Record<string, string | undefined> = process.env,
+): ScoreConfig {
+  const num = (key: string, dflt: number): number =>
+    readEnvNumber(env, key, dflt)
+  return {
+    hourlyInfluence: num(
+      'OPENCODE_AUTH_LB_HOURLY_INFLUENCE',
+      SCORE_DEFAULTS.hourlyInfluence,
+    ),
+    minResetMs: num('OPENCODE_AUTH_LB_MIN_RESET_MS', SCORE_DEFAULTS.minResetMs),
+    weekWindowMs: num(
+      'OPENCODE_AUTH_LB_WEEK_WINDOW_MS',
+      SCORE_DEFAULTS.weekWindowMs,
+    ),
+    exhaustedAt: num(
+      'OPENCODE_AUTH_LB_EXHAUSTED_AT',
+      SCORE_DEFAULTS.exhaustedAt,
+    ),
+    migrateAt: num('OPENCODE_AUTH_LB_MIGRATE_AT', SCORE_DEFAULTS.migrateAt),
+    weeklyDrainTarget: num(
+      'OPENCODE_AUTH_LB_WEEKLY_DRAIN_TARGET',
+      SCORE_DEFAULTS.weeklyDrainTarget,
+    ),
+  }
+}
+
+function clamp01(n: number): number {
+  if (!Number.isFinite(n)) return 0
+  return Math.min(1, Math.max(0, n))
+}
+
+/**
+ * A window is EXPIRED once `now` has passed its `resetAt`: the rate-limit window it
+ * described has rolled over, so its stored utilization is STALE and no longer applies (a
+ * 5h window that read 100% an hour ago has full headroom again, even before we re-poll).
+ * `resetAt === 0` means the reset time is UNKNOWN — NOT expired — so an account with no
+ * reset metadata keeps its reported utilization until real numbers arrive (see
+ * `weeklyUrgency` / `scoreAccount` for how an unknown reset is then ranked).
+ */
+function isWindowExpired(window: ScoreWindow, now: number): boolean {
+  return window.resetAt > 0 && window.resetAt <= now
+}
+
+/**
+ * Effective utilization of a window RIGHT NOW (0..1). A missing window — or one that has
+ * already reset (see `isWindowExpired`) — contributes 0, so a stale 100% left over from
+ * an elapsed window never makes an account look busy or exhausted (which would exclude it
+ * from selection, so it would never be picked, never re-polled, and stay "full" forever).
+ */
+export function utilOf(window: ScoreWindow | null, now: number): number {
+  if (!window || isWindowExpired(window, now)) return 0
+  return clamp01(window.utilization)
+}
+
+/**
+ * Effective utilization for DISPLAY: `null` when there is no window (dashboards render
+ * "-"), `0` once the window has reset (the stale stored value is discarded → "0%"),
+ * otherwise the stored utilization. Mirrors `utilOf`'s expiry rule but keeps the
+ * unknown-vs-zero distinction the dashboards need ("-" for no data, "0%" for a freshly
+ * reset window with full headroom).
+ */
+export function displayUtil(
+  window: ScoreWindow | null,
+  now: number,
+): number | null {
+  if (!window) return null
+  return isWindowExpired(window, now) ? 0 : clamp01(window.utilization)
+}
+
+/** The busiest window's utilization right now (whichever of 5h / weekly is higher). */
+export function maxUtil(account: ScoreAccount, now: number): number {
+  return Math.max(
+    utilOf(account.usage.hourly, now),
+    utilOf(account.usage.weekly, now),
+  )
+}
+
+/** An account is exhausted when ANY still-live window is at/over the exhaustion threshold. */
+export function isExhausted(
+  account: ScoreAccount,
+  cfg: ScoreConfig,
+  now: number,
+): boolean {
+  return maxUtil(account, now) >= cfg.exhaustedAt
+}
+
+/** Available = not disabled, not in cooldown, and not exhausted. */
+export function isAvailable(
+  account: ScoreAccount,
+  cfg: ScoreConfig,
+  now: number,
+): boolean {
+  if (account.disabledReason) return false
+  if (account.cooldownUntil > now) return false
+  if (isExhausted(account, cfg, now)) return false
+  return true
+}
+
+/**
+ * Weekly "urgency" — how perishable an account's remaining weekly quota is. It favors
+ * draining the SOONEST-resetting account first (earliest-deadline-first), because unused
+ * weekly quota is LOST at the reset:
+ *
+ *   drainable = max(0, weeklyDrainTarget - weeklyUtil)   // quota left to safely burn
+ *   urgency   = drainable / (daysToReset + cushion)^2
+ *
+ * The SQUARED time term is the key: it approximates the cost of DELAYING — as a reset
+ * nears, the drain rate needed to avoid waste worsens nonlinearly, so a near-reset
+ * account outranks one that merely has more quota left but resets far away (which is what
+ * `remaining / time` failed to do). `drainable` caps the chase at `weeklyDrainTarget`
+ * (stop favoring an account near the top of its window) and the cushion prevents a blow-up
+ * at the reset instant.
+ *
+ * Imperfect reset metadata splits in three:
+ *  - Window PRESENT but `resetAt === 0` (utilization known, anchor unknown — the
+ *    post-quota-reset shape): weekly resets are FIXED per-account anchors, so
+ *    "unknown" does NOT imply "a full window away" — it may be hours away, wasting a
+ *    refillable budget every idle hour. Assume the reset is IMMINENT (`minResetMs`)
+ *    so the account is ranked FIRST and serves one request ASAP; that response's
+ *    headers reveal the real anchor and the score self-corrects immediately.
+ *    (`drainable` still gates this: an unknown-anchor account with no headroom
+ *    scores 0, so probing never routes to an exhausted account.)
+ *  - Window PRESENT with an ELAPSED anchor (`resetAt` in the past — e.g. an idle
+ *    account behind a failing usage endpoint): because the anchor is FIXED and
+ *    repeats every 7 days, the TRUE next reset is `WEEK_MS - (elapsed % WEEK_MS)`
+ *    away — roll it forward (same model as `rollWeeklyAnchorForward` in
+ *    usage-merge.ts, inlined here to keep score-core dependency-free). An anchor
+ *    that lapsed 6 days ago really resets in ~1 day and must rank accordingly,
+ *    not as "a full window away".
+ *  - Window MISSING entirely (never polled — utilization unknown too): keep the
+ *    conservative full-window baseline. The free usage-endpoint poll resolves this
+ *    case within seconds without routing any traffic to it.
+ */
+export function weeklyUrgency(
+  account: ScoreAccount,
+  cfg: ScoreConfig,
+  now: number,
+): number {
+  // Hoist `account.usage.weekly` to a local so the body skips one chained
+  // property indirection per access on the per-candidate hot path (reached
+  // transitively via `scoreAccount` for every account in the pool — on every
+  // request through `selectAccount` and on every dashboard render through
+  // `status.ts`'s `buildStatus` — and directly from `selectForSession`'s
+  // drain branch).
+  const weekly = account.usage.weekly
+  const drainable = Math.max(0, cfg.weeklyDrainTarget - utilOf(weekly, now))
+  // At/over the weekly drain target `drainable === 0`, so `urgency = 0 / (days*days) = 0`
+  // regardless of the divisor — skip the resetAt/ms/days/divide chain (exact identity).
+  if (drainable === 0) return 0
+  const resetAt = weekly?.resetAt ?? 0
+  // See the jsdoc: a PRESENT window with an unknown anchor assumes an IMMINENT
+  // reset (probe-first — one request reveals the fixed anchor); an ELAPSED
+  // anchor rolls forward to its next 7-day occurrence; only a MISSING window
+  // keeps the full-window baseline.
+  const ms =
+    resetAt > now
+      ? resetAt - now
+      : weekly
+        ? resetAt === 0
+          ? cfg.minResetMs
+          : WEEK_MS - ((now - resetAt) % WEEK_MS)
+        : cfg.weekWindowMs
+  const days = Math.max(ms, cfg.minResetMs) / DAY_MS + RESET_CUSHION_DAYS
+  return drainable / (days * days)
+}
+
+/**
+ * Score one candidate account (higher is better):
+ *   score = weeklyUrgency * (1 - hourlyInfluence * hourlyPressure)
+ *
+ * The 5h window is only a SAFETY de-rate (avoid a short-window hard limit), NOT a quota
+ * objective — and it is RESET-AWARE: `hourlyPressure = hourlyUtil * (msToReset / 5h)`, so
+ * an account whose 5h window is busy but resets in minutes is barely penalized (its
+ * short-term pressure is about to clear), letting the perishable weekly urgency drive the
+ * choice. An unknown 5h reset is treated as a full window (full penalty).
+ */
+export function scoreAccount(
+  account: ScoreAccount,
+  cfg: ScoreConfig,
+  now: number,
+): number {
+  const urgency = weeklyUrgency(account, cfg, now)
+  // With zero weekly urgency the score is 0 no matter the 5h pressure:
+  // `hourlyInfluence` is finite (readEnvNumber rejects non-finite) and
+  // `pressure` is a product of clamp01 values, so the multiplier is always
+  // finite and `0 * finite === 0` — skip the whole hourly chain (exact identity).
+  if (urgency === 0) return 0
+  // Hoist `account.usage.hourly` to a local — same rationale as `weekly`
+  // in `weeklyUrgency` above (per-candidate, per-request hot path). Checked
+  // for null BEFORE `utilOf` (rather than after, via `hourly?.resetAt ?? 0`):
+  // `utilOf` returns 0 for a null window anyway, so this narrows `hourly` to
+  // non-null for the `resetAt` read below instead of leaving a provably-dead
+  // `?.`/`?? 0` — unlike `weeklyUrgency`'s sibling `weekly?.resetAt ?? 0`,
+  // where `weekly` CAN legitimately be null with a non-zero `drainable`.
+  const hourly = account.usage.hourly
+  if (!hourly) return urgency
+  const hourlyUtil = utilOf(hourly, now)
+  // With no 5h pressure `pressure === 0`, so `score = urgency * (1 - influence*0) = urgency`
+  // — skip the resetAt/msToReset/resetFactor/multiply chain (exact identity).
+  if (hourlyUtil === 0) return urgency
+  const resetAt = hourly.resetAt
+  const msToReset = resetAt > now ? resetAt - now : HOURLY_WINDOW_MS
+  const resetFactor = clamp01(msToReset / HOURLY_WINDOW_MS)
+  const pressure = hourlyUtil * resetFactor
+  return urgency * (1 - cfg.hourlyInfluence * pressure)
+}
+
+/**
+ * Sort comparator shared by `src/status.ts` and the TUI sidebar ranking pipeline, so the
+ * dashboard's *ordering* rule can never silently drift from what the server displays —
+ * the same single-source guarantee `scoreAccount` provides for the *formula*. Both
+ * pipelines map each account into `{ available, score, weeklyUtil }` (the per-pipeline
+ * `weeklyUtil` field is computed locally — `src/status.ts` uses the raw stored value to
+ * keep tie-breaking deterministic for cooling-down accounts, the TUI uses `utilOf` to
+ * discard a window that already reset) and pass that shape here:
+ *
+ *   - available accounts come first (they're the only ones the scheduler will pick);
+ *   - among available accounts, higher `score` wins (matches `selectAccount`'s pick);
+ *   - among unavailable accounts, lower `weeklyUtil` wins — the "least bad cooling-down
+ *     account" surfaces first so a forced fall-through stays predictable.
+ */
+export function compareRanked<
+  T extends { available: boolean; score: number; weeklyUtil: number },
+>(x: T, y: T): number {
+  if (x.available !== y.available) return x.available ? -1 : 1
+  if (x.available) return y.score - x.score
+  return x.weeklyUtil - y.weeklyUtil
+}