opencode-ufr 0.2.0

package/src/daemon/catalog.ts

@@ -0,0 +1,127 @@
+import type { ModelsFile, Price } from "../shared/models-file"
+import { deriveChains, deriveContextChains } from "./fallbacks"
+import type { Model, ModelPrice } from "./model"
+
+export type UfrModel = { id: string; name: string; tier: "free" | "paid"; vision: boolean }
+
+export type Catalog = {
+  models: Map<string, Model>
+  aliases: Map<string, string>
+  chains: Map<string, string[]>
+  contextChains: Map<string, string[]>
+  warnings: string[]
+}
+
+export const EMPTY_CATALOG: Catalog = {
+  models: new Map(),
+  aliases: new Map(),
+  chains: new Map(),
+  contextChains: new Map(),
+  warnings: [],
+}
+
+type RawUfrModel = {
+  id?: unknown
+  name?: unknown
+  connection_type?: unknown
+  info?: { meta?: { capabilities?: { vision?: unknown } } }
+}
+
+/** UFR's /api/models: `external` = UFR pays a vendor per token (OpenAI, Mistral). */
+export function parseUfrModels(raw: unknown): UfrModel[] {
+  const list = Array.isArray(raw) ? raw : (raw as { data?: unknown } | null)?.data
+  if (!Array.isArray(list)) throw new Error("UFR /api/models: unexpected response shape")
+  return (list as RawUfrModel[])
+    .filter((m) => m && typeof m.id === "string")
+    .map((m) => ({
+      id: m.id as string,
+      name: typeof m.name === "string" && m.name.trim() ? m.name.trim() : (m.id as string),
+      tier: m.connection_type === "external" ? "paid" : "free",
+      vision: Boolean(m.info?.meta?.capabilities?.vision),
+    }))
+}
+
+function toPrice(p: Price | undefined): ModelPrice | null {
+  if (!p) return null
+  return { input: p.input, output: p.output, cacheRead: p.cache_read ?? p.input, cacheWrite: p.cache_write ?? p.input }
+}
+
+export function buildCatalog(ufr: UfrModel[], file: ModelsFile, opts: { allowPaid: boolean }): Catalog {
+  const warnings: string[] = []
+  const exclude = new Set(file.exclude)
+  const models = new Map<string, Model>()
+  for (const u of ufr) {
+    const e = file.models[u.id]
+    models.set(u.id, {
+      id: u.id,
+      name: u.name,
+      tier: u.tier,
+      vision: e?.vision ?? u.vision,
+      tools: e?.tools ?? true,
+      context: e?.context ?? file.defaults.context,
+      maxOutput: e?.max_output ?? file.defaults.max_output,
+      price: toPrice(e?.price),
+      hasEntry: e !== undefined,
+      hidden: exclude.has(u.id),
+    })
+  }
+  const aliases = new Map<string, string>()
+  for (const [alias, target] of Object.entries(file.aliases)) {
+    if (!models.has(target)) continue
+    aliases.set(alias, target)
+    models.delete(alias) // UFR may list the alias spelling too; one entry per model
+  }
+  for (const m of models.values()) {
+    if (!m.hasEntry) {
+      warnings.push(`${m.id}: new at UFR, no models.json entry — using defaults (context ${m.context}, output ${m.maxOutput}), no fallbacks`)
+    } else if (!m.price && !m.hidden) {
+      warnings.push(`${m.id}: no price in models.json — cost shown as unknown`)
+    }
+  }
+  const hub = file.fallbacks.context_hub
+  if (hub && !models.has(hub)) warnings.push(`context hub ${hub} is not served by UFR — context fallback disabled`)
+  return {
+    models,
+    aliases,
+    chains: deriveChains(models, file.fallbacks, opts),
+    contextChains: deriveContextChains(models, hub, opts),
+    warnings,
+  }
+}
+
+export function resolveModel(cat: Catalog, name: string): string {
+  return cat.aliases.get(name) ?? name
+}
+
+export type OpencodeStamp = {
+  name: string
+  limit: { context: number; output: number }
+  cost?: { input: number; output: number; cache_read: number; cache_write: number }
+  tool_call: boolean
+  attachment: boolean
+  reasoning: boolean
+  temperature: boolean
+}
+
+/**
+ * What the plugin needs per model. reasoning=false for every UFR route
+ * (measured reasoning_effort inert upstream); temperature is accepted everywhere.
+ */
+export function opencodeStamp(m: Model): OpencodeStamp {
+  const s: OpencodeStamp = {
+    name: m.name,
+    limit: { context: m.context, output: m.maxOutput },
+    tool_call: m.tools,
+    attachment: m.vision,
+    reasoning: false,
+    temperature: true,
+  }
+  if (m.price) s.cost = { input: m.price.input, output: m.price.output, cache_read: m.price.cacheRead, cache_write: m.price.cacheWrite }
+  return s
+}
+
+export function listModels(cat: Catalog) {
+  return [...cat.models.values()]
+    .filter((m) => !m.hidden)
+    .map((m) => ({ id: m.id, object: "model" as const, owned_by: "ufr" as const, opencode: opencodeStamp(m) }))
+}

package/src/daemon/daemon.ts

@@ -0,0 +1,397 @@
+import { randomBytes } from "node:crypto"
+import { mkdir, open, rm, stat } from "node:fs/promises"
+import { dirname } from "node:path"
+import { loadConfig, saveConfig } from "../shared/config"
+import { readJson, readText, writeFileAtomic } from "../shared/fs"
+import type { Paths } from "../shared/paths"
+import type { SecretStore } from "../shared/secrets"
+import { VPN_PASS, VPN_USER } from "../shared/secrets"
+import { sleep } from "../shared/sleep"
+import { startOfLocalDay } from "../shared/time"
+import { VERSION } from "../shared/version"
+import { type BreakerState, BreakerRegistry } from "./breaker"
+import { type Catalog, EMPTY_CATALOG, buildCatalog, listModels } from "./catalog"
+import { type FetchLike, type ModelsSource, loadModelsFile, loadUfrModels } from "./catalog-source"
+import { type KeyInfo, KeyPool, type KeySnapshot } from "./keypool"
+import { Router } from "./router"
+import { startServer } from "./server"
+import { Stats } from "./stats"
+import { createTransport } from "./transport"
+import { VpnManager } from "./vpn/manager"
+import { SlidingWindow } from "./window"
+
+export class AlreadyRunningError extends Error {
+  constructor() {
+    super("another opencode-ufr daemon is already running")
+  }
+}
+
+export type StatusJson = {
+  version: string
+  pid: number
+  port: number
+  uptimeMs: number
+  inFlight: number
+  now: number
+  upstream: { ok: boolean | null; message: string; at: number }
+  keys: KeySnapshot[]
+  pool: ReturnType<SlidingWindow["snapshot"]>
+  breakers: Record<string, { state: BreakerState; level: number; retryAfterMs: number }>
+  catalog: { source: ModelsSource | "none"; ufrSource: "remote" | "cache" | "none"; loadedAt: number; models: number; warnings: string[] }
+  vpn: { mode: string; detail: string } | null
+  spendToday: Record<string, number>
+  dailyBudgetUsd: number
+}
+
+export type DaemonOptions = {
+  paths: Paths
+  secrets: SecretStore
+  fetch?: FetchLike
+  bundledModelsPath?: string
+  now?: () => number
+  log?: (m: string) => void
+  /** Fixed port (0 = ephemeral, tests). Default: config.port, else the first free port from preferredPort. */
+  port?: number
+  preferredPort?: number
+  exitOnIdle?: boolean
+  idleMs?: number
+  idleCheckMs?: number
+  /** Backoff after UFR's model list failed to load (VPN down, UFR unreachable); the last delay repeats. */
+  catalogRetryMs?: number[]
+  onStopped?: () => void
+}
+
+export type RunningDaemon = {
+  port: number
+  token: string
+  router: Router
+  status: () => StatusJson
+  refreshCatalog: () => Promise<void>
+  stop: () => Promise<void>
+}
+
+export function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (e) {
+    return (e as NodeJS.ErrnoException).code === "EPERM"
+  }
+}
+
+/** Nonces this process has minted for locks it currently holds, keyed by lock file
+ *  path so releaseLockNonce can forget the right one. Reserved before the lock
+ *  file is even created, so a concurrent reader in this same process never sees
+ *  committed lock content before its nonce is already known here. */
+const heldNonces = new Set<string>()
+const nonceByLock = new Map<string, string>()
+
+export type AcquireLockOptions = {
+  isAlive?: (pid: number) => boolean
+  /** Asked only once a foreign live pid's lock is older than graceMs. */
+  confirmDaemon?: (pid: number) => Promise<boolean>
+  /** How long a foreign live pid's lock is trusted without confirmation (default 60 s). */
+  graceMs?: number
+}
+
+/**
+ * Exclusive-create lock. A lock is stale — and taken over — when: its content
+ * is empty/unparseable and past the just-created window; it names our own pid
+ * but a nonce we never issued (the pid was reused since we last held it); its
+ * pid is dead; or its pid is foreign, live, past the grace period, and
+ * confirmDaemon (when given) says no daemon answers there. A foreign live pid
+ * we cannot confirm (no confirmDaemon given) is left alone, as before.
+ */
+export async function acquireLock(lockFile: string, o: AcquireLockOptions = {}): Promise<boolean> {
+  const isAlive = o.isAlive ?? pidAlive
+  const graceMs = o.graceMs ?? 60_000
+  await mkdir(dirname(lockFile), { recursive: true })
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const nonce = randomBytes(8).toString("hex")
+    heldNonces.add(nonce)
+    try {
+      const fh = await open(lockFile, "wx")
+      await fh.writeFile(`${process.pid} ${nonce}`)
+      await fh.close()
+      nonceByLock.set(lockFile, nonce)
+      return true
+    } catch (e) {
+      heldNonces.delete(nonce)
+      if ((e as NodeJS.ErrnoException).code !== "EEXIST") throw e
+      const content = (await readText(lockFile))?.trim() ?? ""
+      const [pidStr, existingNonce] = content.split(/\s+/)
+      const pid = Number(pidStr)
+      const st = await stat(lockFile).catch(() => null)
+      const ageMs = st ? Date.now() - st.mtimeMs : Number.POSITIVE_INFINITY
+      if (!Number.isInteger(pid) || pid <= 0) {
+        if (ageMs < 10_000) return false // being created right now
+      } else if (pid === process.pid) {
+        if (existingNonce && heldNonces.has(existingNonce)) return false // held by this process
+        // else: our own pid, but a nonce we never issued — the pid was reused
+      } else if (!isAlive(pid)) {
+        // dead pid — stale
+      } else if (ageMs < graceMs) {
+        return false // a daemon looks to be starting; give it the grace period
+      } else if (o.confirmDaemon) {
+        if (await o.confirmDaemon(pid)) return false
+        // confirmDaemon found no daemon there — stale, take over
+      } else {
+        return false // no way to verify a foreign live pid — the old, conservative default
+      }
+      await rm(lockFile, { force: true })
+    }
+  }
+  return false
+}
+
+/** Forgets the nonce for a lock this process released, so a later reuse of our
+ *  own pid (containers, Windows) is never mistaken for a lock we still hold. */
+export function releaseLockNonce(lockFile: string): void {
+  const nonce = nonceByLock.get(lockFile)
+  if (nonce) heldNonces.delete(nonce)
+  nonceByLock.delete(lockFile)
+}
+
+/** The local token survives restarts so the provider opencode registered keeps working. */
+export async function loadOrCreateToken(file: string): Promise<string> {
+  const t = (await readText(file))?.trim()
+  if (t && /^[0-9a-f]{64}$/.test(t)) return t
+  const token = randomBytes(32).toString("hex")
+  await writeFileAtomic(file, token + "\n", 0o600)
+  return token
+}
+
+export async function startDaemon(o: DaemonOptions): Promise<RunningDaemon> {
+  const now = o.now ?? Date.now
+  const log = o.log ?? ((m: string) => console.error(`[opencode-ufr] ${m}`))
+  const f: FetchLike = o.fetch ?? ((u, i) => fetch(u, i))
+  const p = o.paths
+  const config = await loadConfig(p.configFile)
+  const confirmDaemon = async (pid: number): Promise<boolean> => {
+    const saved = (await readJson(p.daemonFile)) as { pid?: number; port?: number } | null
+    if (!saved || saved.pid !== pid || typeof saved.port !== "number") return false
+    try {
+      const res = await fetch(`http://127.0.0.1:${saved.port}/health`, { signal: AbortSignal.timeout(2_000) })
+      if (!res.ok) return false
+      const body = (await res.json()) as { pid?: number }
+      return body.pid === pid
+    } catch {
+      return false
+    }
+  }
+  if (!(await acquireLock(p.lockFile, { confirmDaemon }))) throw new AlreadyRunningError()
+
+  let stats: Stats | null = null
+  let abortStartup = () => {}
+  try {
+    const token = await loadOrCreateToken(p.tokenFile)
+
+    const keyInfos: KeyInfo[] = []
+    for (const alias of config.keys) {
+      const secret = await o.secrets.get(alias)
+      if (secret) keyInfos.push({ alias, secret })
+      else log(`key "${alias}" is in config.json but not in the keyring — skipped`)
+    }
+
+    // Built-in VPN ("auto" transport): logs in to the uni Fortinet gateway and
+    // tunnels UFR calls through a userspace TCP stack when direct fails.
+    let vpn: VpnManager | null = null
+    if (config.transport.type === "auto") {
+      const [user, pass] = await Promise.all([o.secrets.get(VPN_USER), o.secrets.get(VPN_PASS)])
+      vpn = new VpnManager({
+        gateway: config.vpn.gateway,
+        upstreamHost: new URL(config.upstream.baseUrl).hostname,
+        baseUrl: config.upstream.baseUrl,
+        credentials: user && pass ? { user, pass } : null,
+        mode: config.vpn.mode,
+        log,
+        fetch: f,
+      })
+    }
+    const transport = createTransport(config.transport, { vpn })
+    const keys = new KeyPool(keyInfos, {
+      cap: config.limits.keyRpm,
+      windowMs: config.limits.keyWindowS * 1000,
+      maxWaitMs: config.limits.keyMaxWaitS * 1000,
+      now,
+    })
+    const pool = new SlidingWindow({
+      cap: config.limits.poolPerHour,
+      windowMs: config.limits.poolWindowS * 1000,
+      maxWaitMs: config.limits.poolMaxWaitS * 1000,
+      now,
+    })
+    const breakers = new BreakerRegistry({
+      tripThreshold: config.breaker.tripThreshold,
+      ladderMs: config.breaker.ladderS.map((s) => s * 1000),
+      probeTimeoutMs: config.breaker.probeTimeoutS * 1000,
+      now,
+    })
+    const db = new Stats(p.statsDb)
+    stats = db
+    db.prune(now() - 90 * 86_400_000)
+    pool.seed(db.poolAdmissionsSince(now() - config.limits.poolWindowS * 1000))
+    const saved = db.getKv("breakers")
+    if (saved) {
+      try {
+        breakers.restore(JSON.parse(saved))
+      } catch {
+        log("stored breaker state unreadable — starting closed")
+      }
+    }
+
+    const timers: ReturnType<typeof setInterval>[] = []
+    let stopping = false
+    // UFR's model list failed (VPN not up yet, UFR unreachable): retry with backoff
+    // (60 s → 120 s → 300 s → 900 s, then every 900 s; no step longer than refreshHours)
+    // so connecting the VPN later needs no daemon restart.
+    const retryMs = o.catalogRetryMs ?? [60_000, 120_000, 300_000, 900_000]
+    let retryTimer: ReturnType<typeof setTimeout> | null = null
+    let retries = 0
+    const clearCatalogRetry = () => {
+      if (retryTimer) clearTimeout(retryTimer)
+      retryTimer = null
+      retries = 0
+    }
+    abortStartup = () => {
+      stopping = true // a failed start must not leave a retry timer behind
+      clearCatalogRetry()
+    }
+    const scheduleCatalogRetry = () => {
+      if (stopping || retryTimer) return
+      const delay = Math.min(retryMs[Math.min(retries, retryMs.length - 1)]!, config.catalog.refreshHours * 3_600_000)
+      retries++
+      retryTimer = setTimeout(() => {
+        retryTimer = null
+        refreshCatalog().catch((e) => {
+          log(`catalog refresh failed: ${(e as Error).message}`)
+          scheduleCatalogRetry()
+        })
+      }, delay)
+    }
+
+    const reach: StatusJson["upstream"] = { ok: null, message: "", at: 0 }
+    let catalog: Catalog = EMPTY_CATALOG
+    let catalogInfo: Omit<StatusJson["catalog"], "models" | "warnings"> = { source: "none", ufrSource: "none", loadedAt: 0 }
+    const refreshCatalog = async () => {
+      const mf = await loadModelsFile({ url: config.catalog.url, cachePath: p.modelsCache, etagPath: p.modelsEtag,
+        bundledPath: o.bundledModelsPath, fetch: f, log })
+      const ufr = await loadUfrModels({ baseUrl: config.upstream.baseUrl, key: keyInfos[0]?.secret ?? null,
+        cachePath: p.ufrModelsCache, fetch: (u, i) => transport.fetch(u, i), log })
+      catalog = buildCatalog(ufr.models, mf.file, { allowPaid: config.allowPaid })
+      catalogInfo = { source: mf.source, ufrSource: ufr.source, loadedAt: now() }
+      if (ufr.error) Object.assign(reach, { ok: false, message: ufr.error, at: now() })
+      else if (reach.ok !== true) Object.assign(reach, { ok: true, message: "", at: now() })
+      for (const w of catalog.warnings) log(w)
+      // Keys are read once at start: without one a retry can never succeed.
+      if (ufr.error && keyInfos.length > 0) scheduleCatalogRetry()
+      else clearCatalogRetry()
+    }
+    await refreshCatalog()
+
+    const router = new Router({
+      config,
+      catalog: () => catalog,
+      keys,
+      pool,
+      breakers,
+      stats: db,
+      transport,
+      now,
+      sleep,
+      onUpstream: (ok, message) => Object.assign(reach, { ok, message, at: now() }),
+    })
+
+    const startedAt = now()
+    let lastActivity = now()
+    let port = 0
+    const status = (): StatusJson => ({
+      version: VERSION,
+      pid: process.pid,
+      port,
+      uptimeMs: now() - startedAt,
+      inFlight: router.inFlight,
+      now: now(),
+      upstream: { ...reach },
+      keys: keys.snapshot(),
+      pool: pool.snapshot(),
+      breakers: breakers.states(),
+      catalog: { ...catalogInfo, models: catalog.models.size, warnings: catalog.warnings },
+      vpn: vpn ? { mode: vpn.status.mode, detail: vpn.status.detail } : null,
+      spendToday: db.spendByKeySince(startOfLocalDay(now())),
+      dailyBudgetUsd: config.dailyBudgetUsd,
+    })
+
+    let server: ReturnType<typeof startServer> | null = null
+    const stop = async () => {
+      if (stopping) return
+      stopping = true
+      for (const t of timers) clearInterval(t)
+      clearCatalogRetry()
+      try {
+        db.setKv("breakers", JSON.stringify(breakers.snapshot()))
+      } catch {
+        // db already closed
+      }
+      server?.stop()
+      db.close()
+      await vpn?.stop()
+      await rm(p.daemonFile, { force: true })
+      await rm(p.lockFile, { force: true })
+      releaseLockNonce(p.lockFile)
+      log("stopped")
+      o.onStopped?.()
+    }
+
+    const fixed = o.port !== undefined || config.port !== null
+    const first = o.port ?? config.port ?? o.preferredPort ?? 47300
+    for (let candidate = first, i = 0; i < (fixed ? 1 : 20); i++, candidate++) {
+      try {
+        server = startServer({
+          port: candidate,
+          token,
+          version: VERSION,
+          router,
+          models: () => listModels(catalog),
+          status,
+          onActivity: () => {
+            lastActivity = now()
+          },
+          onShutdown: () => void stop(),
+        })
+        break
+      } catch (e) {
+        const inUse = /EADDRINUSE|in use/i.test(`${(e as { code?: string }).code ?? ""} ${(e as Error).message}`)
+        if (!inUse) throw e
+        if (fixed) throw new Error(`port ${candidate} is in use by another program — change "port" in ${p.configFile}`)
+      }
+    }
+    if (!server) throw new Error(`no free port between ${first} and ${first + 19}`)
+    port = server.port
+    if (!fixed) {
+      config.port = port
+      await saveConfig(p.configFile, config)
+    }
+    await writeFileAtomic(p.daemonFile, JSON.stringify({ port, pid: process.pid, version: VERSION, startedAt }) + "\n", 0o600)
+
+    timers.push(setInterval(() => {
+      refreshCatalog().catch((e) => log(`catalog refresh failed: ${(e as Error).message}`))
+    }, config.catalog.refreshHours * 3_600_000))
+    timers.push(setInterval(() => db.setKv("breakers", JSON.stringify(breakers.snapshot())), 30_000))
+    timers.push(setInterval(() => db.prune(now() - 90 * 86_400_000), 86_400_000))
+    if (o.exitOnIdle !== false) {
+      const idleMs = o.idleMs ?? config.idleShutdownMin * 60_000
+      timers.push(setInterval(() => {
+        if (now() - lastActivity > idleMs && router.inFlight === 0) void stop()
+      }, o.idleCheckMs ?? 30_000))
+    }
+    log(`listening on 127.0.0.1:${port} with ${keyInfos.length} key(s), ${catalog.models.size} models`)
+    return { port, token, router, status, refreshCatalog, stop }
+  } catch (e) {
+    abortStartup()
+    stats?.close()
+    await rm(p.lockFile, { force: true })
+    releaseLockNonce(p.lockFile)
+    throw e
+  }
+}

package/src/daemon/fallbacks.ts

@@ -0,0 +1,41 @@
+import type { ModelsFile } from "../shared/models-file"
+import type { Model } from "./model"
+
+/**
+ * Rate-limit fallbacks from one total order: a model may only fall back to
+ * models strictly later in `free_escape_order`. That gives, for free: no
+ * cycles, bounded length, and only maintainer-chosen targets. Hand-written
+ * lists caused the author's former proxy's 2026-08-20 crash-loop and 2026-08-21 cascade.
+ */
+export function deriveChains(
+  models: Map<string, Model>,
+  fb: ModelsFile["fallbacks"],
+  opts: { allowPaid: boolean },
+): Map<string, string[]> {
+  const order = fb.free_escape_order.filter((id) => {
+    const t = models.get(id)
+    return t !== undefined && (opts.allowPaid || t.tier === "free")
+  })
+  const chains = new Map<string, string[]>()
+  for (const [id, m] of models) {
+    if (id === fb.context_hub || !m.tools || !m.hasEntry) continue
+    let targets = order.includes(id) ? order.slice(order.indexOf(id) + 1) : order.filter((t) => t !== id)
+    targets = targets.filter((t) => !m.vision || models.get(t)!.vision).slice(0, fb.max_targets)
+    if (targets.length > 0) chains.set(id, targets)
+  }
+  return chains
+}
+
+/** Context-overflow escapes: anything smaller than the hub may retry on it (one hop). */
+export function deriveContextChains(
+  models: Map<string, Model>,
+  hub: string | null,
+  opts: { allowPaid: boolean },
+): Map<string, string[]> {
+  const out = new Map<string, string[]>()
+  if (!hub) return out
+  const h = models.get(hub)
+  if (!h || (h.tier === "paid" && !opts.allowPaid)) return out
+  for (const [id, m] of models) if (id !== hub && m.tools && m.context < h.context) out.set(id, [hub])
+  return out
+}

package/src/daemon/keypool.ts

@@ -0,0 +1,109 @@
+import { SlidingWindow } from "./window"
+
+export type KeyInfo = { alias: string; secret: string }
+export type Acquired = { kind: "ok"; alias: string; secret: string; waitMs: number; at: number }
+export type NotAcquired = { kind: "none"; reason: "no_keys" | "all_tried" | "exhausted"; retryAfterMs: number }
+export type KeySnapshot = { alias: string; used: number; cap: number; blockedForMs: number; invalid: boolean }
+
+type Slot = KeyInfo & {
+  window: SlidingWindow
+  blockedUntil: number
+  invalid: boolean
+  recent429: { at: number; model: string }[]
+}
+
+export class KeyPool {
+  private readonly slots: Slot[]
+  private rr = 0
+
+  constructor(
+    keys: KeyInfo[],
+    private readonly o: { cap: number; windowMs: number; maxWaitMs: number; now: () => number },
+  ) {
+    this.slots = keys.map((k) => ({
+      ...k,
+      window: new SlidingWindow({ cap: o.cap, windowMs: o.windowMs, maxWaitMs: o.maxWaitMs, now: o.now }),
+      blockedUntil: 0,
+      invalid: false,
+      recent429: [],
+    }))
+  }
+
+  /** Number of keys not marked invalid. */
+  get size(): number {
+    return this.slots.filter((s) => !s.invalid).length
+  }
+
+  private find(alias: string): Slot | undefined {
+    return this.slots.find((s) => s.alias === alias)
+  }
+
+  private availableAt(s: Slot): number {
+    return Math.max(s.blockedUntil, this.o.now() + s.window.nextFreeInMs())
+  }
+
+  acquire(exclude: ReadonlySet<string> = new Set()): Acquired | NotAcquired {
+    const now = this.o.now()
+    const valid = this.slots.filter((s) => !s.invalid)
+    if (valid.length === 0) return { kind: "none", reason: "no_keys", retryAfterMs: 0 }
+    const usable = valid.filter((s) => !exclude.has(s.alias))
+    if (usable.length === 0) return { kind: "none", reason: "all_tried", retryAfterMs: 0 }
+
+    const ready = usable.filter((s) => this.availableAt(s) <= now)
+    if (ready.length > 0) {
+      const best = Math.max(...ready.map((s) => s.window.headroom()))
+      const tied = ready.filter((s) => s.window.headroom() === best)
+      const pick = tied[this.rr++ % tied.length]!
+      const r = pick.window.reserve()
+      return { kind: "ok", alias: pick.alias, secret: pick.secret, waitMs: 0, at: r.at }
+    }
+
+    let soonest = usable[0]!
+    for (const s of usable) if (this.availableAt(s) < this.availableAt(soonest)) soonest = s
+    const at = this.availableAt(soonest)
+    const waitMs = at - now
+    if (waitMs <= this.o.maxWaitMs) {
+      soonest.window.reserveAt(at)
+      return { kind: "ok", alias: soonest.alias, secret: soonest.secret, waitMs, at }
+    }
+    return { kind: "none", reason: "exhausted", retryAfterMs: waitMs }
+  }
+
+  release(alias: string, at: number): void {
+    this.find(alias)?.window.release(at)
+  }
+
+  /**
+   * UFR said 429 on this key. Bucket, model wall and daily $ cap look identical,
+   * so only cool the key down when the bucket is the plausible cause.
+   */
+  onRateLimited(alias: string, model: string): void {
+    const s = this.find(alias)
+    if (!s) return
+    const now = this.o.now()
+    s.recent429 = s.recent429.filter((e) => e.at > now - this.o.windowMs)
+    s.recent429.push({ at: now, model })
+    const usedHalf = s.window.inWindow() >= Math.max(1, Math.floor(this.o.cap / 2))
+    const acrossModels = new Set(s.recent429.map((e) => e.model)).size >= 2
+    if (usedHalf || acrossModels) {
+      // UFR frees a slot at first admission + window; rejected calls do not count.
+      s.blockedUntil = Math.max(s.blockedUntil, (s.window.oldest() ?? now) + this.o.windowMs, now + 1_000)
+    }
+  }
+
+  onInvalid(alias: string): void {
+    const s = this.find(alias)
+    if (s) s.invalid = true
+  }
+
+  snapshot(): KeySnapshot[] {
+    const now = this.o.now()
+    return this.slots.map((s) => ({
+      alias: s.alias,
+      used: s.window.inWindow(),
+      cap: this.o.cap,
+      blockedForMs: Math.max(0, s.blockedUntil - now),
+      invalid: s.invalid,
+    }))
+  }
+}

package/src/daemon/log.ts

@@ -0,0 +1,15 @@
+import { appendFileSync, mkdirSync, renameSync, statSync } from "node:fs"
+import { dirname } from "node:path"
+
+/** Append-only log, rotated to <file>.1 past maxBytes. Callers never pass key values. */
+export function createLogger(file: string, maxBytes = 1_000_000): (msg: string) => void {
+  mkdirSync(dirname(file), { recursive: true })
+  return (msg) => {
+    try {
+      if (statSync(file).size > maxBytes) renameSync(file, `${file}.1`)
+    } catch {
+      // no log file yet
+    }
+    appendFileSync(file, `${new Date().toISOString()} ${msg}\n`)
+  }
+}