@gotcos/glasses-server 6.79.2 → 6.80.0

package/server/lib/key-lanes-wiring.ts

@@ -0,0 +1,346 @@
+// Key lanes K1, package P11 (plan v4 14.2 row P11, 17): the wiring between the packages.
+//
+// P2 owns the relay, P3 and P4 the Lane B bridges, P5 the direct lane, P6 the profile router.
+// Each left a seam for this file to fill:
+//
+//   registerLaneBRelay / registerCodexKeyRelay   the shared loopback relay (P2) for keyed CLI turns
+//   registerCodexKeyedThreadRecorder             a keyed Codex thread is recorded like a Claude one (P3)
+//   registerKeyProfileEngine claude|codex|direct the runner P6's router hands a `profile:<id>` turn to
+//   registerDirectRelay                          the in-process door the direct lane posts through
+//   installKeyRelaySeams                         the relay's answers on GET /api/key-lanes/status
+//
+// HARD RULE: wireKeyLanes() does map writes, plus the one read keyLanesEnabled() makes of
+// data/key-lanes.json (an existsSync when it is absent; QA N1: this comment said "no file is read").
+// Nothing is written, no socket or timer is opened, and the direct lane module is not even loaded
+// until a direct profile turn runs. The status seams are installed at boot only when
+// keyLanesEnabled(); every registered runner and relay resolver refuses (or is never reached)
+// while keyLanesActive() is false, so a server with no key takes the 6.79.1 path byte for byte.
+import { randomUUID } from 'node:crypto'
+import { callClaudeStreaming } from './claude-bridge.js'
+import { runCodexKeyProfileTurn } from './codex-bridge.js'
+import { registerCodexKeyRelay, registerCodexKeyedThreadRecorder } from './codex-profile-home.js'
+import { keyCatalogPeekPrice } from './key-lanes-pricing.js'
+import { keyLanesActive, keyLanesEnabled, registerKeyLanesStatusProvider } from './key-lanes.js'
+import { registerKeyProfileEngine, type KeyProfileEngineRunner, type KeyProfileTurn } from './key-profile-routing.js'
+import { __setKeyCatalogForTests, getKeyCatalog, KeyCatalog } from './key-catalog.js'
+import type { KeyProfile, KeyRef, KeyRelay, RelayNonceBinding } from './key-relay-contract.js'
+import { KEY_NOTICE_ERROR_IDS, keyModelLabel, keyNoticeError, type KeyNoticeErrorId } from './key-notices.js'
+import { getPublicKey } from './key-store.js'
+import type { StreamCallbacks } from './claude-bridge.js'
+import { breakerScopeFor, classifyUpstreamStatus, countsTowardBreaker, redactSecrets } from './key-relay-errors.js'
+import { estimateReserveUsd, getSharedKeyMeter, tokensToUsd, type KeyRelayMeter } from './key-relay-meter.js'
+import { getKeyRelay, installKeyRelaySeams, KeyRelayRefusal, type KeyRelayServer, type RelayTurnFailure } from './key-relay.js'
+import { readKeySecretForRelay } from './key-store.js'
+import { keyedSessionIds, recordKeyedSession } from './keyed-sessions.js'
+import { registerLaneBRelay } from './lane-b-env.js'
+import type { DirectRefusalKind, DirectRelay, DirectRelayPost, DirectRelayTurn, DirectTurnBinding, DirectUsage } from './direct-bridge.js'
+
+/**
+ * QA C2 journeys: `COS_KEY_RELAY_TEST_UPSTREAM=http://127.0.0.1:<port>` points the relay's
+ * upstreams, OpenRouter's key API and the public catalog at a LOOPBACK mock, so the journey
+ * harness can boot index.ts and run a keyed turn end to end. Anything that is not
+ * http://127.0.0.1 is ignored with a warning. Not in managed-runtime-contract.json: a managed
+ * install never forwards it.
+ */
+export function keyRelayTestUpstream(env: NodeJS.ProcessEnv = process.env): string | null {
+  const raw = env.COS_KEY_RELAY_TEST_UPSTREAM
+  if (!raw) return null
+  try {
+    const u = new URL(raw)
+    if (u.protocol === 'http:' && u.hostname === '127.0.0.1' && u.port) return u.origin
+  } catch { /* fall through */ }
+  console.warn('[key-lanes] COS_KEY_RELAY_TEST_UPSTREAM ignored: only http://127.0.0.1:<port> is accepted')
+  return null
+}
+
+/** The one relay, created on first keyed use with live catalog prices (P5) for the meter. */
+export function sharedKeyRelay(): KeyRelayServer {
+  const test = keyRelayTestUpstream()
+  return getKeyRelay({
+    priceFor: keyCatalogPeekPrice,
+    onTurnFailure: recordKeyTurnFailure,
+    ...(test ? {
+      upstreams: { openrouterMessages: `${test}/api/v1/messages`, openrouterResponses: `${test}/api/v1/responses`, anthropicMessages: `${test}/anthropic/v1/messages`, openaiResponses: `${test}/openai/v1/responses` },
+      openrouterApiBase: `${test}/api/v1`,
+    } : {}),
+  })
+}
+
+// ── Turn failures: the key-notices line, never the CLI's raw error ───────────
+// The relay reports the plan 4.6 "ends the turn" rows (cap, 401, 402, model gone) for a turn id,
+// and issueTurn refuses a turn before spawn (breaker open, cap used, key gone). The CLI then
+// fails with its own wording ("API Error: 402 ..."). The Lane B runners below wrap onError so
+// the lens, the durable job and COS Control read the P8 line for that failure instead.
+
+interface KeyTurnFailure { kind: KeyNoticeErrorId; keyRef: KeyRef; scope?: 'key' | 'profile'; id?: string; ends?: boolean }
+const KEY_TURN_FAILURES_MAX = 256
+const turnFailures = new Map<string, KeyTurnFailure>()
+
+function rememberFailure(turnId: string, failure: KeyTurnFailure): void {
+  if (!turnId) return
+  // A failure that ended the turn is the reason; a later retry note (429, an ended token) never hides it.
+  if (turnFailures.get(turnId)?.ends && !failure.ends) return
+  turnFailures.delete(turnId)
+  turnFailures.set(turnId, failure)
+  while (turnFailures.size > KEY_TURN_FAILURES_MAX) {
+    const oldest = turnFailures.keys().next().value
+    if (oldest === undefined) break
+    turnFailures.delete(oldest)
+  }
+}
+
+/** The relay's onTurnFailure. */
+export function recordKeyTurnFailure(f: RelayTurnFailure): void {
+  // QA G4: one line per failure kind (names and kinds only, never a body or a token).
+  console.info(`[key-lanes] turn failure kind=${f.kind} status=${f.status} profile=${f.profileId}`)
+  const counted = f.kind === 'key_rejected' || f.kind === 'out_of_credit' || f.kind === 'model_gone'
+  const scope = f.kind === 'model_gone' ? 'profile' : 'key'
+  const ends = f.endsTurn ?? (f.kind === 'cap_refused' || counted)
+  rememberFailure(f.turnId, { kind: f.kind, keyRef: f.keyRef, ends, ...(counted ? { scope, id: scope === 'key' ? f.keyRef : f.profileId } : {}) })
+}
+
+function refusalId(err: KeyRelayRefusal): KeyNoticeErrorId | null {
+  if (err.code === 'breaker_open') return 'breaker_open'
+  if (err.kind === 'lanes_inactive') return 'profile_off'
+  if (err.code === 'key_missing') return 'profile_removed'
+  return (KEY_NOTICE_ERROR_IDS as readonly string[]).includes(err.kind) ? err.kind as KeyNoticeErrorId : null
+}
+
+/** The P8 line for a turn the relay failed or refused, once (it is consumed), or null. */
+export function keyTurnFailureLine(turnId: string, profile: Pick<KeyProfile, 'label' | 'model'>, now: Date = new Date()): string | null {
+  const f = turnFailures.get(turnId)
+  if (!f) return null
+  turnFailures.delete(turnId)
+  // A counted failure that opened its breaker reads as the pause, not as one more rejection.
+  const paused = f.scope && f.id && f.kind !== 'breaker_open' && sharedKeyRelay().breakers.isOpen(f.scope, f.id)
+  const key = getPublicKey(f.keyRef)
+  return keyNoticeError(paused ? 'breaker_open' : f.kind, {
+    ...(key ? { keyKind: key.kind, capUsd: key.capUsd } : {}),
+    modelLabel: keyModelLabel(profile.model),
+    profileLabel: profile.label,
+    now,
+  })
+}
+
+/** The Lane B relay as the bridges see it: the shared relay, with pre-spawn refusals remembered. */
+function laneBRelayView(): KeyRelay {
+  const relay = sharedKeyRelay()
+  return {
+    issueTurn: async (binding: RelayNonceBinding, options) => {
+      try {
+        return await relay.issueTurn(binding, options)
+      } catch (err) {
+        const id = err instanceof KeyRelayRefusal ? refusalId(err) : null
+        if (id) rememberFailure(binding.turnId, { kind: id, keyRef: binding.keyRef, ends: true })
+        throw err
+      }
+    },
+    revokeTurn: (turnId, reason) => relay.revokeTurn(turnId, reason),
+    revokeAll: reason => relay.revokeAll(reason),
+    port: () => relay.port(),
+    close: () => relay.close(),
+  }
+}
+
+/** onError reads the turn's key-notices line when the relay has one; onDone forgets it. */
+function withKeyFailureLines(callbacks: StreamCallbacks, turnId: string, profile: KeyProfile): StreamCallbacks {
+  turnFailures.delete(turnId)
+  return {
+    ...callbacks,
+    onError: error => callbacks.onError(keyTurnFailureLine(turnId, profile) ?? error),
+    onDone: (...args) => { turnFailures.delete(turnId); return callbacks.onDone(...args) },
+  }
+}
+
+// ── Runners (P6's engine seam) ───────────────────────────────────────────────
+
+/**
+ * QA C11: an OpenRouter profile whose slug left the (cached) catalog is refused before anything
+ * spawns, with the model-gone line. No cached catalog: the turn goes ahead and a refresh starts.
+ */
+export function keyProfileSlugGoneLine(turn: Pick<KeyProfileTurn, 'profile' | 'keyKind'>, catalog = getKeyCatalog()): string | null {
+  if (turn.keyKind !== 'openrouter') return null
+  const models = catalog.peek()
+  if (!models) { catalog.refreshInBackground(); return null }
+  if (models.some(m => m.id === turn.profile.model)) return null
+  console.info(`[key-lanes] refused kind=model_gone profile=${turn.profile.id} (slug not in the catalog)`)
+  return keyNoticeError('model_gone', { keyKind: turn.keyKind, modelLabel: keyModelLabel(turn.profile.model), profileLabel: turn.profile.label })
+}
+
+async function refuseGoneSlug(sessionId: string, callbacks: StreamCallbacks, turn: KeyProfileTurn): Promise<string | null> {
+  const line = keyProfileSlugGoneLine(turn)
+  if (!line) return null
+  await callbacks.onError(line)
+  return sessionId
+}
+
+/** Lane B Claude (P3): the profile's timeout tier for the clock, its model on `--model`. */
+export const runClaudeKeyProfileTurn: KeyProfileEngineRunner = async (query, sessionId, callbacks, turn, images, reference, globalMsgNum, options) => {
+  const gone = await refuseGoneSlug(sessionId, callbacks, turn)
+  if (gone !== null) return gone
+  // The relay keys failures by turn id, so the turn gets one here when the caller has none.
+  const turnId = options?.turnId ?? randomUUID()
+  return callClaudeStreaming(query, sessionId, withKeyFailureLines(callbacks, turnId, turn.profile), turn.profile.timeoutTier, images, reference, globalMsgNum, { ...options, turnId, keyProfile: turn.profile })
+}
+
+/** Lane B Codex (P4). */
+export const runCodexKeyTurn: KeyProfileEngineRunner = async (query, sessionId, callbacks, turn, images, reference, globalMsgNum, options) => {
+  const gone = await refuseGoneSlug(sessionId, callbacks, turn)
+  if (gone !== null) return gone
+  const turnId = options?.turnId ?? randomUUID()
+  return runCodexKeyProfileTurn(query, sessionId, withKeyFailureLines(callbacks, turnId, turn.profile), turn, images, reference, globalMsgNum, { ...options, turnId })
+}
+
+/** Lane C1 (P5). The module loads on the first direct turn, never at boot. */
+export const runDirectKeyTurn: KeyProfileEngineRunner = async (query, sessionId, callbacks, turn, images, reference, globalMsgNum, options) => {
+  const gone = await refuseGoneSlug(sessionId, callbacks, turn)
+  if (gone !== null) return gone
+  const direct = await import('./direct-bridge.js')
+  if (!direct.directRelayRegistered()) direct.registerDirectRelay(() => sharedDirectRelay())
+  return direct.callDirectStreaming(query, sessionId, callbacks, turn.profile, images, reference, globalMsgNum, options)
+}
+
+// ── The direct relay (P5's in-process door over P2's meter, breakers and secret read) ──
+
+export interface DirectRelayAdapterDeps {
+  isActive?: () => boolean
+  secretFor?: (ref: KeyRef) => string | null
+  meter?: KeyRelayMeter
+  breakers?: () => KeyRelayServer['breakers']
+  priceFor?: (model: string) => { inUsdPerM: number; outUsdPerM: number }
+  fetch?: typeof fetch
+}
+
+function authHeaders(secret: string): Record<string, string> {
+  // OpenRouter, OpenAI, Anthropic's OpenAI-compatible endpoint and custom endpoints all take Bearer.
+  return { authorization: `Bearer ${secret}`, 'content-type': 'application/json', accept: 'text/event-stream, application/json' }
+}
+
+/**
+ * A DirectRelay that reserves against the key's daily cap on the shared meter (the same counter
+ * Lane B uses), forwards to the binding's endpoint with the real key, and settles what the direct
+ * lane measured. It never retries (the lane's own loop does). The key is read at request time and
+ * put only in the request headers; an upstream error body is scrubbed of it before the lane sees it.
+ */
+export function createDirectRelay(deps: DirectRelayAdapterDeps = {}): DirectRelay {
+  const isActive = deps.isActive ?? (() => keyLanesActive())
+  const secretFor = deps.secretFor ?? readKeySecretForRelay
+  const meter = () => deps.meter ?? getSharedKeyMeter()
+  const breakers = deps.breakers ?? (() => sharedKeyRelay().breakers)
+  const priceFor = deps.priceFor ?? keyCatalogPeekPrice
+  const fetchImpl = deps.fetch ?? ((input: RequestInfo | URL, init?: RequestInit) => fetch(input, init))
+
+  const preflight = (b: DirectTurnBinding): DirectRefusalKind | null => {
+    if (!isActive()) return 'lanes_inactive'
+    if (!secretFor(b.keyRef)) return 'key_missing'
+    const br = breakers()
+    if (br.isOpen('key', b.keyRef) || br.isOpen('profile', b.profileId)) return 'breaker_open'
+    if (meter().atCap(b.keyRef)) return 'cap_refused'
+    return null
+  }
+
+  return {
+    async openTurn(binding) {
+      const refused = preflight(binding)
+      if (refused) {
+        console.info(`[key-lanes] direct refused kind=${refused} profile=${binding.profileId}`)
+        return { ok: false, refused }
+      }
+      const price = priceFor(binding.model)
+      const turn: DirectRelayTurn = {
+        async post(body, signal) {
+          const refusedNow = preflight(binding)
+          if (refusedNow) return { refused: refusedNow }
+          const secret = secretFor(binding.keyRef)
+          if (!secret) return { refused: 'key_missing' }
+          // Only the profile's model goes upstream, whatever the body says.
+          const payload = JSON.stringify({ ...body, model: binding.model })
+          const maxTokens = typeof body.max_tokens === 'number' ? body.max_tokens : null
+          // QA W2: the direct lane caps each reply at its own max_tokens, so the whole of it is
+          // reserved; the meter refuses a reservation that does not fit under today's cap.
+          const fullUsd = estimateReserveUsd({ bodyBytes: Buffer.byteLength(payload), maxTokens, price })
+          const reserved = meter().reserve({
+            keyRef: binding.keyRef,
+            turnId: binding.turnId,
+            estimateUsd: fullUsd,
+            profile: binding.profileId,
+            lane: 'direct',
+          })
+          if (!reserved.ok) return { refused: 'cap_refused' }
+          let response: Response
+          try {
+            response = await fetchImpl(binding.endpoint, { method: 'POST', headers: authHeaders(secret), body: payload, signal, redirect: 'error' })
+          } catch (err) {
+            meter().settle({ reservationId: reserved.reservationId, usd: 0, tokens: { input: 0, output: 0 } })
+            throw err instanceof Error ? new Error(redactSecrets(err.message, [secret])) : err
+          }
+          const br = breakers()
+          if (!response.ok) {
+            const text = redactSecrets(await response.text().catch(() => ''), [secret])
+            const kind = classifyUpstreamStatus(response.status, text)
+            if (countsTowardBreaker(kind)) br.record(breakerScopeFor(kind), breakerScopeFor(kind) === 'key' ? binding.keyRef : binding.profileId, kind, false)
+            response = new Response(text, { status: response.status, statusText: response.statusText, headers: response.headers })
+          } else {
+            br.record('key', binding.keyRef, null, true)
+            br.record('profile', binding.profileId, null, true)
+          }
+          let settled = false
+          const post: DirectRelayPost = {
+            response,
+            settle(usage: DirectUsage | null) {
+              if (settled) return
+              settled = true
+              if (usage === null) { meter().settleReserved(reserved.reservationId); return }
+              const tokens = { input: Math.max(0, usage.input || 0), output: Math.max(0, usage.output || 0) }
+              const usd = typeof usage.costUsd === 'number' && Number.isFinite(usage.costUsd) && usage.costUsd >= 0
+                ? usage.costUsd
+                : tokensToUsd(tokens, price)
+              meter().settle({ reservationId: reserved.reservationId, usd, tokens, ...(usage.generationId ? { generationId: usage.generationId } : {}) })
+            },
+          }
+          return post
+        },
+        spentTodayUsd: () => meter().spentTodayUsd(binding.keyRef),
+        close() { /* nothing held: each post settles its own reservation */ },
+      }
+      return { ok: true, turn }
+    },
+  }
+}
+
+let directRelay: DirectRelay | null = null
+function sharedDirectRelay(): DirectRelay {
+  if (!directRelay) directRelay = createDirectRelay()
+  return directRelay
+}
+
+// ── Boot ─────────────────────────────────────────────────────────────────────
+
+let wired = false
+
+/** Called once from index.ts. Map writes only; see the HARD RULE above. */
+export function wireKeyLanes(): void {
+  if (wired) return
+  wired = true
+  registerLaneBRelay(() => laneBRelayView())
+  registerCodexKeyRelay(() => laneBRelayView())
+  registerCodexKeyedThreadRecorder(thread => recordKeyedSession({ id: thread.id, engine: 'codex', profileId: thread.profileId, cosSessionId: thread.cosSessionId }))
+  registerKeyProfileEngine('claude', runClaudeKeyProfileTurn)
+  registerKeyProfileEngine('codex', runCodexKeyTurn)
+  registerKeyProfileEngine('direct', runDirectKeyTurn)
+  // Read only by GET /api/key-lanes/status, which answers only while lanes are enabled.
+  registerKeyLanesStatusProvider({ keyedSessionIds })
+  const test = keyRelayTestUpstream()
+  if (test) {
+    console.warn(`[key-lanes] test upstream ${test}: keyed requests and the catalog go to this loopback mock`)
+    __setKeyCatalogForTests(new KeyCatalog({ url: `${test}/api/v1/models` }))
+  }
+  if (keyLanesEnabled()) installKeyRelaySeams()
+}
+
+/** Tests only. */
+export function __resetKeyLanesWiringForTests(): void {
+  wired = false
+  directRelay = null
+  turnFailures.clear()
+}

package/server/lib/key-lanes.ts

@@ -0,0 +1,145 @@
+// Key lanes (K1, plan v4 section 3): the two predicates every key-lane branch starts with.
+//
+//   keyLanesEnabled()  COS_KEY_LANES=1, or data/key-lanes.json says enabled:true.
+//                      COS_KEY_LANES=0 forces off and wins over the file.
+//   keyLanesActive()   enabled AND provider-profiles.json holds at least one enabled profile.
+//
+// HARD RULE (zero impact without a key): with the switch off nothing here creates a file, opens a
+// socket, starts a timer or adds a response field. Reading never creates. Every new branch in the
+// server starts `if (!keyLanesActive()) return <old path>` (or keyLanesEnabled() for the exposure
+// list rows), before any other new work.
+import { existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { durableAtomicWriteFileSync } from './atomic-fs.js'
+import { DATA_DIR, dataPath } from './data-dir.js'
+import { enabledProfileCount, listProfiles } from './key-profiles.js'
+import { listPublicKeys } from './key-store.js'
+import type {
+  KeyLanesHealthDetail,
+  KeyLanesInactiveHook,
+  KeyLanesInactiveReason,
+  KeyLanesStatusProvider,
+  PublicKeyProfileOption,
+} from './key-relay-contract.js'
+
+export const KEY_LANES_ENV = 'COS_KEY_LANES'
+export const KEY_LANES_STATE_FILE = 'key-lanes.json'
+
+export type KeyLanesEnvSwitch = 'on' | 'off' | 'unset'
+
+/** Exactly `1` is on and exactly `0` is off; anything else (absent, empty, `true`) is unset. */
+export function keyLanesEnvSwitch(env: NodeJS.ProcessEnv = process.env): KeyLanesEnvSwitch {
+  const raw = env[KEY_LANES_ENV]?.trim()
+  if (raw === '1') return 'on'
+  if (raw === '0') return 'off'
+  return 'unset'
+}
+
+export function keyLanesStatePath(): string {
+  return dataPath(KEY_LANES_STATE_FILE)
+}
+
+interface KeyLanesStateFile {
+  v: 1
+  enabled: boolean
+  updatedAt: string
+}
+
+/** The file's `enabled`, or null when it is missing or unreadable. Never writes. */
+function readStateFileEnabled(): boolean | null {
+  const file = keyLanesStatePath()
+  if (!existsSync(file)) return null
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8')) as Partial<KeyLanesStateFile>
+    return parsed && typeof parsed === 'object' && parsed.enabled === true
+  } catch {
+    // A torn or foreign file reads as off. It is never repaired or rewritten from a read.
+    return false
+  }
+}
+
+// The file is read once (the first call, at boot in practice) and again on enable/disable.
+let fileEnabled: boolean | null | undefined
+
+export function keyLanesEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  const sw = keyLanesEnvSwitch(env)
+  if (sw === 'off') return false
+  if (sw === 'on') return true
+  if (fileEnabled === undefined) fileEnabled = readStateFileEnabled()
+  return fileEnabled === true
+}
+
+export function keyLanesActive(env: NodeJS.ProcessEnv = process.env): boolean {
+  if (!keyLanesEnabled(env)) return false
+  return enabledProfileCount() > 0
+}
+
+/**
+ * Write the state file (the enable and disable routes, and Remove all keys). This is the ONLY
+ * writer of key-lanes.json. 0600, atomic, in a 0700 data dir.
+ */
+export function setKeyLanesEnabled(enabled: boolean, now: () => Date = () => new Date()): void {
+  mkdirSync(DATA_DIR, { recursive: true, mode: 0o700 })
+  const body: KeyLanesStateFile = { v: 1, enabled, updatedAt: now().toISOString() }
+  durableAtomicWriteFileSync(keyLanesStatePath(), JSON.stringify(body, null, 2) + '\n', { mode: 0o600 })
+  fileEnabled = enabled
+}
+
+/** Re-read the state file on the next predicate call. */
+export function refreshKeyLanesEnabled(): void {
+  fileEnabled = undefined
+}
+
+// ── Response fields (plan 3.1 exposure list). Omitted, never null, when off. ──
+
+/** `/api/health`: `details.keyLanes` while enabled, nothing at all otherwise. */
+export function keyLanesHealthFields(env: NodeJS.ProcessEnv = process.env): { details?: { keyLanes: KeyLanesHealthDetail } } {
+  if (!keyLanesEnabled(env)) return {}
+  return { details: { keyLanes: { enabled: true, active: keyLanesActive(env) } } }
+}
+
+/** `/api/models`: `keyProfiles` while active (enabled profiles whose key still exists), nothing otherwise. */
+export function keyProfilesModelsField(env: NodeJS.ProcessEnv = process.env): { keyProfiles?: PublicKeyProfileOption[] } {
+  if (!keyLanesActive(env)) return {}
+  const kinds = new Map(listPublicKeys().map(k => [k.ref, k.kind]))
+  const keyProfiles: PublicKeyProfileOption[] = []
+  for (const p of listProfiles()) {
+    const keyKind = kinds.get(p.keyRef)
+    if (!p.enabled || !keyKind) continue
+    keyProfiles.push({ id: p.id, label: p.label, engine: p.engine, model: p.model, keyKind, timeoutTier: p.timeoutTier })
+  }
+  return { keyProfiles }
+}
+
+// ── Seams other packages register into (P2 relay, P3 keyed sessions, P6 bindings). ──
+
+let statusProvider: KeyLanesStatusProvider = {}
+const inactiveHooks = new Map<string, KeyLanesInactiveHook>()
+
+export function registerKeyLanesStatusProvider(provider: KeyLanesStatusProvider): void {
+  statusProvider = { ...statusProvider, ...provider }
+}
+
+export function keyLanesStatusProvider(): KeyLanesStatusProvider {
+  return statusProvider
+}
+
+/** Named so a re-registration replaces rather than stacks. */
+export function onKeyLanesInactive(name: string, hook: KeyLanesInactiveHook): void {
+  inactiveHooks.set(name, hook)
+}
+
+/** Run every hook; one failing hook never stops the others. Returns the names that threw. */
+export async function runKeyLanesInactiveHooks(reason: KeyLanesInactiveReason): Promise<string[]> {
+  const failed: string[] = []
+  for (const [name, hook] of inactiveHooks) {
+    try { await hook(reason) } catch { failed.push(name) }
+  }
+  return failed
+}
+
+/** Tests only: forget the cached file read and every registration. */
+export function __resetKeyLanesForTests(): void {
+  fileEnabled = undefined
+  statusProvider = {}
+  inactiveHooks.clear()
+}

package/server/lib/key-ledger.ts

@@ -0,0 +1,123 @@
+// Key lanes K1 P2 (plan v4 4.5): the spend ledger, `data/key-ledger.jsonl`.
+//
+// One JSON row per reserve, settle or reconcile. 0600, append-only (one write(2) per row under
+// O_APPEND, so rows from parallel turns never interleave), never written through a symlink. A row
+// carries a key REF, never a secret, never a nonce. Reading never creates: a missing file is an
+// empty ledger, an unreadable line is skipped and left in place.
+//
+// Spend for a UTC day is the sum of `settle` rows plus `reconcile` deltas. `reserve` rows are an
+// audit trail only: open reservations live in the meter's memory, so a crash between reserve and
+// settle forgets the reservation (OpenRouter's own usage_daily and the key's credit limit are the
+// backstop, plan 4.5).
+import { closeSync, constants as fsConstants, existsSync, fchmodSync, lstatSync, mkdirSync, openSync, readFileSync, writeSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { dataPath } from './data-dir.js'
+import type { KeyLane, KeyLedgerKind, KeyLedgerRow, KeyRef } from './key-relay-contract.js'
+import { KEY_REF_RE } from './key-relay-contract.js'
+
+export const KEY_LEDGER_FILE = 'key-ledger.jsonl'
+const ID_MAX = 128
+const KINDS: readonly KeyLedgerKind[] = ['reserve', 'settle', 'reconcile']
+const LANES: readonly KeyLane[] = ['key', 'direct']
+
+export function keyLedgerPath(): string {
+  return dataPath(KEY_LEDGER_FILE)
+}
+
+/** The UTC day (plan 4.5: OpenRouter usage_daily resets at UTC midnight). */
+export function utcDay(ms: number): string {
+  return new Date(ms).toISOString().slice(0, 10)
+}
+
+function clipId(v: unknown): string {
+  return typeof v === 'string' ? v.slice(0, ID_MAX) : ''
+}
+
+function finiteNonNeg(v: unknown): number {
+  return typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : 0
+}
+
+/** Build a row from known fields only, so nothing else (a secret, a nonce) can ride along. */
+export function toLedgerRow(input: KeyLedgerRow): KeyLedgerRow {
+  if (!KEY_REF_RE.test(input.keyRef)) throw new Error('key ledger: bad key ref')
+  if (!KINDS.includes(input.kind)) throw new Error('key ledger: bad kind')
+  if (!LANES.includes(input.lane)) throw new Error('key ledger: bad lane')
+  const usd = typeof input.usd === 'number' && Number.isFinite(input.usd) ? Math.round(input.usd * 1e8) / 1e8 : 0
+  return {
+    ts: clipId(input.ts),
+    keyRef: input.keyRef,
+    profile: clipId(input.profile),
+    lane: input.lane,
+    turnId: clipId(input.turnId),
+    ...(input.generationId ? { generationId: clipId(input.generationId) } : {}),
+    tokens: { input: Math.round(finiteNonNeg(input.tokens?.input)), output: Math.round(finiteNonNeg(input.tokens?.output)) },
+    usd,
+    kind: input.kind,
+  }
+}
+
+/**
+ * Append one row. QA W6: opened with O_NOFOLLOW, so a symlink planted between any check and the
+ * write is refused by the kernel (ELOOP), never followed; the mode is set on the open descriptor.
+ */
+export function appendKeyLedgerRow(row: KeyLedgerRow, file: string = keyLedgerPath()): void {
+  const line = JSON.stringify(toLedgerRow(row)) + '\n'
+  mkdirSync(dirname(file), { recursive: true, mode: 0o700 })
+  let fd: number
+  try {
+    // O_NONBLOCK too: a FIFO planted at the path fails at once (ENXIO) instead of hanging the server.
+    fd = openSync(file, fsConstants.O_WRONLY | fsConstants.O_APPEND | fsConstants.O_CREAT | fsConstants.O_NOFOLLOW | fsConstants.O_NONBLOCK, 0o600)
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException)?.code === 'ELOOP') throw new Error('refusing to write the key ledger through a symlink')
+    throw err
+  }
+  try {
+    fchmodSync(fd, 0o600)
+    writeSync(fd, line)
+  } finally {
+    closeSync(fd)
+  }
+}
+
+/** Every parseable row. Never creates the file. */
+export function readKeyLedger(file: string = keyLedgerPath()): KeyLedgerRow[] {
+  if (!existsSync(file)) return []
+  const st = lstatSync(file)
+  if (st.isSymbolicLink() || !st.isFile()) return []
+  const rows: KeyLedgerRow[] = []
+  for (const line of readFileSync(file, 'utf8').split('\n')) {
+    if (!line.trim()) continue
+    try {
+      const r = JSON.parse(line) as Partial<KeyLedgerRow>
+      if (r && typeof r.keyRef === 'string' && typeof r.kind === 'string' && typeof r.usd === 'number' && typeof r.ts === 'string') rows.push(r as KeyLedgerRow)
+    } catch { /* a torn line is skipped, never rewritten */ }
+  }
+  return rows
+}
+
+/**
+ * Spend for one key on one UTC day, from the file: settle plus reconcile deltas, PLUS every
+ * reservation no settle row answered (QA W3: a crash mid-stream left it open, and the provider
+ * may have billed it; an Anthropic or OpenAI key has no usage API to say otherwise). Settles
+ * answer a turn's reservations in order. Read at a process's first use of the day, before it
+ * opens any reservation of its own.
+ */
+export function ledgerSpentUsd(keyRef: KeyRef, day: string, file: string = keyLedgerPath()): number {
+  let sum = 0
+  const open = new Map<string, number[]>()
+  for (const r of readKeyLedger(file)) {
+    if (r.keyRef !== keyRef || r.ts.slice(0, 10) !== day) continue
+    const usd = Number.isFinite(r.usd) ? r.usd : 0
+    const turn = typeof r.turnId === 'string' ? r.turnId : ''
+    if (r.kind === 'reserve') {
+      open.set(turn, [...(open.get(turn) ?? []), Math.max(0, usd)])
+    } else if (r.kind === 'settle') {
+      sum += usd
+      open.get(turn)?.shift()
+    } else if (r.kind === 'reconcile') {
+      sum += usd
+    }
+  }
+  for (const left of open.values()) for (const usd of left) sum += usd
+  return Math.max(0, sum)
+}