@bitkyc08/opencodex 2.89.0 → 2.91.0

package/src/quota-pool/assemble.ts

@@ -0,0 +1,326 @@
+/**
+ * Assemble `ocx.quota-pool/1` (`GET /api/quota-pool`) from what this Home already holds.
+ *
+ * Strictly passive. Every source below is a cache another path filled; this module starts no
+ * probe, token refresh, quota refresh or upstream call and writes nothing. The whole assembly runs
+ * inside `runPassiveRead`, so even the shared readers it calls (the Codex account list, the OAuth
+ * store) take their passive branch: no WHAM probe, no native-main claim, no file hardening or
+ * malformed-store backup. Sources:
+ *
+ * - Codex pool accounts: the passive `listCodexAuthAccountsSnapshot` (stored `StoredAccountQuota`
+ *   per account plus the cached main-account reading);
+ * - provider-level reports: `heldProviderQuotaReports`, the reports the Home last published
+ *   (for the Codex pool provider this is OpenCodex's own pool aggregate, reported as `pooled`);
+ * - per-account OAuth quota (Anthropic instances, Kiro, Antigravity, xAI, Cursor, Kimi, Command
+ *   Code, Devin, DSH, Meta): the last-good per-account cache;
+ * - Claude CLI: the usage-admission snapshot (5-hour, weekly and family windows, plus a parsed
+ *   CLI limit refusal).
+ *
+ * An unknown window is omitted, never emitted as 0%. A window whose reset has passed is unknown
+ * again and is omitted too. Optional fields are left out instead of set to null.
+ */
+import type { OcxConfig, OcxProviderConfig } from "../types";
+import type { ProviderQuota, ProviderQuotaWindow } from "../providers/quota-types";
+import type { StoredAccountQuota } from "../codex/quota-types";
+import { isTerminalShortWindow, resetAtToMs } from "../codex/quota-types";
+import { runPassiveRead } from "../lib/passive-read";
+import { packageVersion } from "../lib/package-version";
+import { listCodexAuthAccountsSnapshot } from "../codex/auth-api";
+import { latestCodexQuotaObservationSource } from "../codex/quota";
+import { ACCOUNT_LOG_LABEL_RE, oauthAccountLogLabel } from "../codex/account-label";
+import { OPENAI_CODEX_PROVIDER_ID } from "../providers/openai-tiers-destination";
+import { hasCodexPoolProvider, heldProviderQuotaReports, type ProviderQuotaReport } from "../providers/quota/report-cache";
+import {
+  accountCacheKey,
+  accountQuotaCache,
+  getCachedProviderAccountQuota,
+  hasPassiveAccountQuota,
+  supportsPerAccountQuota,
+} from "../providers/quota/account-cache";
+import { parseQuotaFailureCode } from "../providers/quota-types";
+import { getAccountSet } from "../oauth/store";
+import { peekClaudeUsageObservation } from "../adapters/claude-cli/usage-admission";
+import {
+  QUOTA_POOL_SCHEMA,
+  type QuotaPool,
+  type QuotaPoolAccount,
+  type QuotaPoolAccountState,
+  type QuotaPoolProvider,
+  type QuotaPoolRole,
+  type QuotaPoolSource,
+  type QuotaPoolWindow,
+} from "./contract";
+import { quotaPoolAccountRef, readQuotaPoolIdentity, type QuotaPoolIdentity } from "./identity";
+
+const VERSION = packageVersion("0.0.0");
+const SHORT_BURST_MAX_SECONDS = 6 * 3600;
+const SHORT_DAILY_MAX_SECONDS = 36 * 3600;
+
+export interface QuotaPoolDeps {
+  now?: () => number;
+  /** Test seam for the Claude CLI admission file. */
+  claudeUsageStatePath?: string;
+}
+
+export type QuotaPoolResult = { ok: true; pool: QuotaPool } | { ok: false; error: "quota_pool_identity_unavailable" };
+
+const finite = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value);
+
+function iso(ms: number): string | undefined {
+  if (!finite(ms) || ms <= 0) return undefined;
+  const date = new Date(ms);
+  return Number.isFinite(date.getTime()) ? date.toISOString() : undefined;
+}
+
+/** A used percent inside the contract's 0..100, or undefined when there is no reading. */
+function percent(value: unknown): number | undefined {
+  if (!finite(value) || value < 0) return undefined;
+  return Math.min(100, value);
+}
+
+type WindowDraft = Omit<QuotaPoolWindow, "observedAt" | "source"> & { resetMs?: number };
+
+/**
+ * Finish a window, or drop it when it carries nothing (no percent, no counters) or its reset has
+ * already passed: an elapsed window is unknown now, not empty.
+ */
+function finish(draft: WindowDraft, source: QuotaPoolSource, observedMs: number, now: number): QuotaPoolWindow | null {
+  const observedAt = iso(observedMs);
+  if (!observedAt) return null;
+  const { resetMs, ...rest } = draft;
+  if (resetMs !== undefined && resetMs <= now) return null;
+  if (rest.usedPercent === undefined && rest.used === undefined && rest.limit === undefined && rest.exhausted === undefined) return null;
+  const resetsAt = resetMs !== undefined ? iso(resetMs) : undefined;
+  const exhausted = rest.exhausted ?? (rest.usedPercent !== undefined ? rest.usedPercent >= 100 : undefined);
+  const window: QuotaPoolWindow = { ...rest, source, observedAt };
+  if (resetsAt) window.resetsAt = resetsAt;
+  if (exhausted !== undefined) window.exhausted = exhausted;
+  return window;
+}
+
+function resetMs(value: unknown): number | undefined {
+  return finite(value) && value > 0 ? resetAtToMs(value) : undefined;
+}
+
+function shortKind(seconds: number | undefined): Pick<QuotaPoolWindow, "id" | "kind" | "label"> {
+  if (seconds === undefined || seconds <= SHORT_BURST_MAX_SECONDS) return { id: "5h", kind: "burst_5h", label: "5-hour" };
+  if (seconds <= SHORT_DAILY_MAX_SECONDS) return { id: "daily", kind: "daily", label: "Daily" };
+  return { id: "short", kind: "custom", label: "Short window" };
+}
+
+/** Codex `StoredAccountQuota`, mapped as the header and WHAM parsers stored it. */
+export function codexQuotaWindows(quota: StoredAccountQuota, source: QuotaPoolSource, now: number): QuotaPoolWindow[] {
+  const out: QuotaPoolWindow[] = [];
+  const push = (window: QuotaPoolWindow | null) => { if (window) out.push(window); };
+  const shortPercent = percent(quota.shortPercent);
+  const shortSeconds = finite(quota.shortWindowSeconds) && quota.shortWindowSeconds > 0 ? quota.shortWindowSeconds : undefined;
+  if (shortPercent !== undefined) {
+    push(finish({
+      ...shortKind(shortSeconds),
+      usedPercent: shortPercent,
+      ...(shortSeconds !== undefined ? { windowSeconds: shortSeconds } : {}),
+      resetMs: resetMs(quota.shortResetAt),
+      exhausted: isTerminalShortWindow(quota, now),
+    }, source, quota.shortObservedAt ?? quota.updatedAt, now));
+  }
+  const weekly = percent(quota.weeklyPercent);
+  if (weekly !== undefined) {
+    push(finish({ id: "weekly", kind: "weekly", label: "Weekly", usedPercent: weekly, resetMs: resetMs(quota.weeklyResetAt) }, source, quota.updatedAt, now));
+  }
+  const monthly = percent(quota.monthlyPercent);
+  if (monthly !== undefined) {
+    push(finish({ id: "monthly", kind: "monthly", label: "Monthly", usedPercent: monthly, resetMs: resetMs(quota.monthlyResetAt) }, source, quota.updatedAt, now));
+  }
+  for (const custom of quota.customWindows ?? []) {
+    const used = percent(custom?.percent);
+    if (typeof custom?.label !== "string" || !custom.label.trim() || used === undefined) continue;
+    push(finish({ id: `custom:${custom.label}`, kind: "custom", label: custom.label, usedPercent: used, resetMs: resetMs(custom.resetAt) }, source, quota.updatedAt, now));
+  }
+  return out;
+}
+
+function customWindow(window: ProviderQuotaWindow, source: QuotaPoolSource, updatedAt: number, now: number): QuotaPoolWindow | null {
+  if (typeof window?.label !== "string" || !window.label.trim()) return null;
+  // An exact-model row (Antigravity diagnostics, CCA fallback) restates the pool its family
+  // window already reports and carries no proven scope; reporting it unscoped would let it gate
+  // every model.
+  if (window.modelId !== undefined && window.scope !== "model") return null;
+  const scoped = window.scope === "model";
+  const passive = finite(window.passiveObservedAt);
+  return finish({
+    id: scoped ? `family:${window.label.toLowerCase()}` : `custom:${window.label}`,
+    kind: "custom",
+    label: window.label,
+    ...(percent(window.percent) !== undefined ? { usedPercent: percent(window.percent) } : {}),
+    ...(scoped ? { scopeModel: window.label } : {}),
+    ...(window.rejected === true ? { exhausted: true } : {}),
+    resetMs: resetMs(window.resetAt),
+  }, passive ? "header" : source, passive ? window.passiveObservedAt! : updatedAt, now);
+}
+
+/** A `ProviderQuota` (provider report or per-account cache row). */
+export function providerQuotaWindows(quota: ProviderQuota, source: QuotaPoolSource, now: number): QuotaPoolWindow[] {
+  const out: QuotaPoolWindow[] = [];
+  const push = (window: QuotaPoolWindow | null) => { if (window) out.push(window); };
+  const at = quota.updatedAt;
+  const fixed = [
+    ["5h", "burst_5h", "5-hour", quota.fiveHourPercent, quota.fiveHourResetAt],
+    ["weekly", "weekly", "Weekly", quota.weeklyPercent, quota.weeklyResetAt],
+    ["monthly", "monthly", "Monthly", quota.monthlyPercent, quota.monthlyResetAt],
+  ] as const;
+  for (const [id, kind, label, value, reset] of fixed) {
+    const used = percent(value);
+    if (used === undefined) continue;
+    push(finish({ id, kind, label, usedPercent: used, resetMs: resetMs(reset) }, source, at, now));
+  }
+  const kiroUsed = finite(quota.kiroCreditsUsed) && quota.kiroCreditsUsed >= 0 ? quota.kiroCreditsUsed : undefined;
+  const kiroLimit = finite(quota.kiroCreditsLimit) && quota.kiroCreditsLimit > 0 ? quota.kiroCreditsLimit : undefined;
+  if (kiroUsed !== undefined || kiroLimit !== undefined) {
+    push(finish({
+      id: "credits:kiro", kind: "credits", label: "Kiro credits", unit: "credits",
+      ...(kiroUsed !== undefined ? { used: kiroUsed } : {}),
+      ...(kiroLimit !== undefined ? { limit: kiroLimit } : {}),
+      ...(kiroUsed !== undefined && kiroLimit !== undefined ? { usedPercent: percent((kiroUsed / kiroLimit) * 100) } : {}),
+    }, source, at, now));
+  }
+  const usd = quota.creditsUsd;
+  if (usd && finite(usd.used) && usd.used >= 0) {
+    const unlimited = usd.unlimited === true;
+    push(finish({
+      id: "credits:usd", kind: "credits", label: "USD credits", unit: "usd", used: usd.used,
+      ...(!unlimited && finite(usd.limit) && usd.limit > 0 ? { limit: usd.limit } : {}),
+      ...(!unlimited && percent(usd.percent) !== undefined ? { usedPercent: percent(usd.percent) } : {}),
+      ...(unlimited ? { exhausted: false } : finite(usd.remaining) ? { exhausted: usd.remaining <= 0 } : {}),
+    }, source, at, now));
+  }
+  for (const custom of quota.customWindows ?? []) push(customWindow(custom, source, at, now));
+  return out;
+}
+
+function accountState(input: { reauth: boolean; paused: boolean; windows: readonly QuotaPoolWindow[] }): QuotaPoolAccountState {
+  if (input.reauth) return "reauth";
+  if (input.paused) return "paused";
+  // A model-scoped window never gates the account as a whole.
+  if (input.windows.some(window => window.exhausted === true && window.scopeModel === undefined)) return "exhausted";
+  return input.windows.length === 0 ? "unknown" : "available";
+}
+
+function nextResetAt(windows: readonly QuotaPoolWindow[]): string | undefined {
+  const resets = windows.filter(window => window.scopeModel === undefined && window.resetsAt).map(window => window.resetsAt!).sort();
+  return resets[0];
+}
+
+function reportSource(report: ProviderQuotaReport): QuotaPoolSource {
+  if (report.aggregation) return "estimated";
+  return report.observed === true ? "header" : "measured";
+}
+
+function codexAccounts(identity: QuotaPoolIdentity, accounts: Awaited<ReturnType<typeof listCodexAuthAccountsSnapshot>>["accounts"], now: number): QuotaPoolAccount[] {
+  const provider = OPENAI_CODEX_PROVIDER_ID;
+  return accounts.map(dto => {
+    const source: QuotaPoolSource = latestCodexQuotaObservationSource(dto.id) === "response-header" ? "header" : "measured";
+    const windows = dto.quota ? codexQuotaWindows(dto.quota as StoredAccountQuota, source, now) : [];
+    const account: QuotaPoolAccount = {
+      provider,
+      accountRef: quotaPoolAccountRef(identity, provider, dto.id),
+      // needsReauth only: a passive read leaves hasCredential false when it did not check, and an
+      // account without a credential already carries needsReauth.
+      state: accountState({ reauth: dto.needsReauth === true, paused: dto.paused, windows }),
+      windows,
+    };
+    if (typeof dto.logLabel === "string" && ACCOUNT_LOG_LABEL_RE.test(dto.logLabel)) account.label = dto.logLabel;
+    if (typeof dto.plan === "string" && dto.plan.trim()) account.plan = dto.plan.trim();
+    return account;
+  });
+}
+
+function oauthAccounts(identity: QuotaPoolIdentity, provider: string, now: number): QuotaPoolAccount[] {
+  const set = getAccountSet(provider);
+  if (!set) return [];
+  return set.accounts.map(row => {
+    const quota = getCachedProviderAccountQuota(provider, row.id);
+    const entry = accountQuotaCache.get(accountCacheKey(provider, row.id));
+    const windows = quota ? providerQuotaWindows(quota, "measured", now) : [];
+    const account: QuotaPoolAccount = {
+      provider,
+      accountRef: quotaPoolAccountRef(identity, provider, row.id),
+      label: oauthAccountLogLabel(row.id, provider),
+      state: accountState({ reauth: row.needsReauth === true, paused: row.paused === true, windows }),
+      windows,
+    };
+    const failure = entry?.quotaFailure && entry.quotaFailureIsCurrent?.() === true ? parseQuotaFailureCode(entry.quotaFailure) : undefined;
+    if (failure) account.failure = failure;
+    return account;
+  });
+}
+
+function claudeCliAccounts(identity: QuotaPoolIdentity, provider: string, deps: QuotaPoolDeps, now: number): QuotaPoolAccount[] {
+  const observation = peekClaudeUsageObservation(deps.claudeUsageStatePath ? { statePath: deps.claudeUsageStatePath } : {});
+  if (!observation) return [];
+  const windows = observation.quota ? providerQuotaWindows(observation.quota, "measured", now) : [];
+  if (finite(observation.refusalUntil) && observation.refusalUntil > now) {
+    const refusal = finish({ id: "refusal", kind: "custom", label: "Claude CLI limit", exhausted: true, resetMs: observation.refusalUntil },
+      "estimated", observation.checkedAt, now);
+    if (refusal) windows.push(refusal);
+  }
+  return [{
+    provider,
+    accountRef: quotaPoolAccountRef(identity, provider, `claude-cli:${observation.identity}`),
+    state: accountState({ reauth: false, paused: false, windows }),
+    windows,
+  }];
+}
+
+function role(config: OcxConfig): QuotaPoolRole {
+  return config.runtimeRole === "hub" || config.runtimeRole === "client" ? config.runtimeRole : "standalone";
+}
+
+function enabled(provider: OcxProviderConfig | undefined): provider is OcxProviderConfig {
+  return !!provider && provider.disabled !== true;
+}
+
+async function assemble(config: OcxConfig, identity: QuotaPoolIdentity, deps: QuotaPoolDeps): Promise<QuotaPool> {
+  const now = (deps.now ?? Date.now)();
+  const names = Object.keys(config.providers).filter(name => enabled(config.providers[name])).sort();
+  const reports = new Map(heldProviderQuotaReports(names).reports.map(report => [report.provider, report]));
+  const codexPool = hasCodexPoolProvider(config);
+  const codex = codexPool ? (await listCodexAuthAccountsSnapshot(config)).accounts : [];
+  const providers: QuotaPoolProvider[] = [];
+  for (const name of names) {
+    const provider = config.providers[name]!;
+    let accounts: QuotaPoolAccount[] = [];
+    let tracked = false;
+    if (codexPool && name === OPENAI_CODEX_PROVIDER_ID) {
+      tracked = true;
+      accounts = codexAccounts(identity, codex, now);
+    } else if (provider.adapter === "claude-cli") {
+      tracked = true;
+      accounts = claudeCliAccounts(identity, name, deps, now);
+    } else if (supportsPerAccountQuota(name) || hasPassiveAccountQuota(name)) {
+      tracked = true;
+      accounts = oauthAccounts(identity, name, now);
+    }
+    const report = reports.get(name);
+    const pooledWindows = report ? providerQuotaWindows(report.quota, reportSource(report), now) : [];
+    if (!tracked && !report) continue;
+    const pooled: QuotaPoolProvider["pooled"] = { windows: pooledWindows };
+    const next = nextResetAt(pooledWindows);
+    if (next) pooled.nextResetAt = next;
+    providers.push({ provider: name, accounts, pooled });
+  }
+  return {
+    schema: QUOTA_POOL_SCHEMA,
+    producer: { version: VERSION, role: role(config), homeId: identity.homeId },
+    generatedAt: iso(now) ?? new Date().toISOString(),
+    providers,
+  };
+}
+
+/** The quota pool, or an identity error. Always a passive read, whoever asks. */
+export function readQuotaPool(config: OcxConfig, deps: QuotaPoolDeps = {}): Promise<QuotaPoolResult> {
+  return runPassiveRead(async () => {
+    const identity = readQuotaPoolIdentity();
+    if (!identity) return { ok: false, error: "quota_pool_identity_unavailable" } as const;
+    return { ok: true, pool: await assemble(config, identity, deps) } as const;
+  });
+}

package/src/quota-pool/contract.ts

@@ -0,0 +1,58 @@
+/**
+ * Wire shape of `GET /api/quota-pool`: the GOAT contract `ocx.quota-pool/1`.
+ *
+ * GOAT owns the decoder (`packages/contracts/src/quotaPool.ts` in goat-si/goat); OpenCodex is
+ * the producer. Every optional field is OMITTED when OpenCodex does not know it. A missing
+ * window means unknown, never 0%, and no field is ever `null`.
+ */
+
+export const QUOTA_POOL_SCHEMA = "ocx.quota-pool/1" as const;
+
+export type QuotaPoolWindowKind = "burst_5h" | "daily" | "weekly" | "monthly" | "credits" | "custom";
+/** measured: a usage probe body; header: response rate-limit headers; estimated: derived by OpenCodex. */
+export type QuotaPoolSource = "measured" | "header" | "estimated";
+export type QuotaPoolUnit = "requests" | "tokens" | "credits" | "usd";
+export type QuotaPoolAccountState = "available" | "exhausted" | "paused" | "reauth" | "unknown";
+export type QuotaPoolRole = "standalone" | "hub" | "client";
+
+export interface QuotaPoolWindow {
+  id: string;
+  kind: QuotaPoolWindowKind;
+  label: string;
+  usedPercent?: number;
+  used?: number;
+  limit?: number;
+  unit?: QuotaPoolUnit;
+  resetsAt?: string;
+  windowSeconds?: number;
+  scopeModel?: string;
+  source: QuotaPoolSource;
+  observedAt: string;
+  exhausted?: boolean;
+}
+
+export interface QuotaPoolAccount {
+  provider: string;
+  driver?: string;
+  /** Opaque, stable for this install, never an email or a raw account id (see identity.ts). */
+  accountRef: string;
+  label?: string;
+  plan?: string;
+  state: QuotaPoolAccountState;
+  windows: QuotaPoolWindow[];
+  /** A closed `QuotaFailureCode`; never upstream text. */
+  failure?: string;
+}
+
+export interface QuotaPoolProvider {
+  provider: string;
+  accounts: QuotaPoolAccount[];
+  pooled: { windows: QuotaPoolWindow[]; headroom?: number; nextResetAt?: string };
+}
+
+export interface QuotaPool {
+  schema: typeof QUOTA_POOL_SCHEMA;
+  producer: { version: string; role: QuotaPoolRole; homeId: string };
+  generatedAt: string;
+  providers: QuotaPoolProvider[];
+}

package/src/quota-pool/identity.ts

@@ -0,0 +1,203 @@
+/**
+ * The install identity behind `ocx.quota-pool/1`: the Home's `homeId` and the secret that keys
+ * every `accountRef`.
+ *
+ * Both live in `<OPENCODEX_HOME>/quota-pool-identity.json` (owner-only). The server creates the
+ * file once, in the background after it starts listening (`ensureQuotaPoolIdentity`); the
+ * `/api/quota-pool` read only reads it, so the read path never writes. A read that finds no
+ * valid file reports the identity as unavailable instead of minting one.
+ *
+ * `accountRef` is `acct_` + base64url(HMAC-SHA256(secret, "ocx.quota-pool/1" NUL provider NUL
+ * accountId)) truncated to 128 bits. It is stable across restarts because the secret is
+ * persisted, distinct per provider, and not reversible: without the per-install secret a
+ * recipient cannot confirm a guessed email or account id against it, and it never contains
+ * either. Deleting the file rotates `homeId` and every `accountRef` together.
+ */
+import { createHmac, randomBytes, randomUUID } from "node:crypto";
+import { closeSync, constants as fsConstants, fsyncSync, linkSync, lstatSync, openSync, readFileSync, unlinkSync, writeSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getConfigDir } from "../config/paths";
+
+export const QUOTA_POOL_IDENTITY_FILE = "quota-pool-identity.json";
+
+export interface QuotaPoolIdentity {
+  homeId: string;
+  secret: string;
+}
+
+const HOME_ID = /^home_[0-9a-f]{32}$/;
+const SECRET = /^[0-9a-f]{64}$/;
+let memo: { path: string; identity: QuotaPoolIdentity } | null = null;
+
+export function quotaPoolIdentityPath(configDir = getConfigDir()): string {
+  return join(configDir, QUOTA_POOL_IDENTITY_FILE);
+}
+
+function parseIdentity(text: string): QuotaPoolIdentity | null {
+  try {
+    const raw = JSON.parse(text) as Record<string, unknown>;
+    if (raw?.version !== 1 || typeof raw.homeId !== "string" || typeof raw.secret !== "string") return null;
+    if (!HOME_ID.test(raw.homeId) || !SECRET.test(raw.secret)) return null;
+    return { homeId: raw.homeId, secret: raw.secret };
+  } catch {
+    return null;
+  }
+}
+
+/** Read-only: the persisted identity, or null when it is missing or malformed. Never writes. */
+export function readQuotaPoolIdentity(configDir = getConfigDir()): QuotaPoolIdentity | null {
+  const path = quotaPoolIdentityPath(configDir);
+  if (memo?.path === path) return memo.identity;
+  try {
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1024) return null;
+  } catch {
+    return null;
+  }
+  let identity: QuotaPoolIdentity | null;
+  try { identity = parseIdentity(readFileSync(path, "utf8")); } catch { return null; }
+  if (identity) memo = { path, identity };
+  return identity;
+}
+
+const NOFOLLOW = process.platform === "win32" ? 0 : fsConstants.O_NOFOLLOW;
+/** How long a loser waits for a concurrent winner's file to become readable before giving up. */
+const PUBLISHED_READ_ATTEMPTS = 50;
+const PUBLISHED_READ_INTERVAL_MS = 10;
+
+/** Test seams for the publication windows; production never sets them. */
+export interface QuotaPoolIdentityTestHooks {
+  /** After the first read found no identity, before the existence check. */
+  afterAbsentRead?: (path: string) => void;
+  /** After a file was exclusively created, before its bytes are written. */
+  afterCreate?: (path: string) => void;
+  /** Replace `linkSync` (to force the in-place fallback). */
+  link?: (existing: string, target: string) => void;
+  /** Override the bounded wait for a concurrent winner. */
+  publishedReadAttempts?: number;
+}
+let hooks: QuotaPoolIdentityTestHooks = {};
+
+export function setQuotaPoolIdentityHooksForTests(next: QuotaPoolIdentityTestHooks = {}): void {
+  hooks = next;
+}
+
+/** Write a whole new owner-only file, flushed to disk; fails if anything (a symlink included) already exists. */
+function createExclusive(path: string, content: string): void {
+  const fd = openSync(path, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | NOFOLLOW, 0o600);
+  try {
+    hooks.afterCreate?.(path);
+    writeSync(fd, content);
+    fsyncSync(fd);
+  } finally { closeSync(fd); }
+}
+
+function errorCode(error: unknown): string | undefined {
+  return (error as NodeJS.ErrnoException | null)?.code;
+}
+
+/**
+ * Make the new directory entry durable too: fsyncing the file alone can lose the entry on power
+ * loss, and a lost entry would mint a new identity and rotate every accountRef on the next start.
+ * Best effort; Windows cannot open a directory for fsync.
+ */
+function syncParentDirectory(path: string): void {
+  if (process.platform === "win32") return;
+  try {
+    const fd = openSync(dirname(path), fsConstants.O_RDONLY);
+    try { fsyncSync(fd); } finally { closeSync(fd); }
+  } catch { /* the file itself is flushed; a directory fsync is an extra guarantee */ }
+}
+
+function pause(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/**
+ * Something already sits at the path: adopt it once it reads as a valid identity.
+ *
+ * A concurrent winner's file is complete the moment it appears when it was hard-linked, but the
+ * in-place fallback creates the file before writing it, so a loser can briefly see it empty. The
+ * wait is bounded; an invalid result is never returned or memoized. A symlink, or a file that stays
+ * invalid past the bound, is refused and left alone.
+ */
+function adoptPublishedIdentity(configDir: string, path: string): QuotaPoolIdentity {
+  const attempts = hooks.publishedReadAttempts ?? PUBLISHED_READ_ATTEMPTS;
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    let stat;
+    try { stat = lstatSync(path); } catch (error) {
+      if (errorCode(error) !== "ENOENT") throw error;
+      stat = null;
+    }
+    if (stat && (stat.isSymbolicLink() || !stat.isFile())) break;
+    const identity = readQuotaPoolIdentity(configDir);
+    if (identity) return identity;
+    if (attempt + 1 < attempts) pause(PUBLISHED_READ_INTERVAL_MS);
+  }
+  throw new Error("quota-pool identity file is not a valid regular file; remove it to rotate the identity");
+}
+
+/**
+ * Create the identity once. Called off the request path (server startup); idempotent.
+ *
+ * Publication is exclusive and never follows a link: the secret is written and flushed to a
+ * private temp file, then hard-linked into place, which fails if anything already sits at the path.
+ * Where hard links are unavailable it is created in place exclusively. Two servers starting on one
+ * fresh home therefore cannot each keep a different identity: a loser, including one that finds
+ * the winner's file appear between its own checks, re-reads within a bound and adopts the winner's.
+ * A symlink or a persistently malformed file at the path is refused and left alone (the read keeps
+ * reporting the identity as unavailable until an operator removes it); it is never overwritten.
+ */
+export function ensureQuotaPoolIdentity(configDir = getConfigDir()): QuotaPoolIdentity {
+  const existing = readQuotaPoolIdentity(configDir);
+  if (existing) return existing;
+  const path = quotaPoolIdentityPath(configDir);
+  hooks.afterAbsentRead?.(path);
+  let present = true;
+  try { lstatSync(path); } catch (error) { if (errorCode(error) !== "ENOENT") throw error; present = false; }
+  if (present) return adoptPublishedIdentity(configDir, path);
+  const identity: QuotaPoolIdentity = {
+    homeId: `home_${randomUUID().replaceAll("-", "")}`,
+    secret: randomBytes(32).toString("hex"),
+  };
+  const content = `${JSON.stringify({ version: 1, ...identity })}\n`;
+  const temp = `${path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+  let published = false;
+  try {
+    createExclusive(temp, content);
+    try {
+      (hooks.link ?? linkSync)(temp, path);
+      published = true;
+    } catch (error) {
+      const code = errorCode(error);
+      if (code === "EEXIST") return adoptPublishedIdentity(configDir, path);
+      // No hard links on this filesystem: exclusive create in place is still never a replacement.
+      if (code !== "EPERM" && code !== "ENOTSUP" && code !== "EXDEV" && code !== "ENOSYS") throw error;
+    }
+  } finally {
+    try { unlinkSync(temp); } catch { /* best effort */ }
+  }
+  if (!published) {
+    try {
+      createExclusive(path, content);
+    } catch (error) {
+      if (errorCode(error) !== "EEXIST") throw error;
+      return adoptPublishedIdentity(configDir, path);
+    }
+  }
+  syncParentDirectory(path);
+  memo = { path, identity };
+  return identity;
+}
+
+/** The opaque account reference: keyed by the install secret, never the raw id or an email. */
+export function quotaPoolAccountRef(identity: QuotaPoolIdentity, provider: string, accountId: string): string {
+  const digest = createHmac("sha256", Buffer.from(identity.secret, "hex"))
+    .update(`ocx.quota-pool/1\0${provider}\0${accountId}`)
+    .digest();
+  return `acct_${digest.subarray(0, 16).toString("base64url")}`;
+}
+
+export function resetQuotaPoolIdentityMemoForTests(): void {
+  memo = null;
+}

package/src/remote/features.ts

@@ -0,0 +1,74 @@
+/**
+ * The one registry of peer-visible features this build serves, advertised in `GET /readyz`
+ * `features` so a Hub, a Child or GOAT decides compatibility by feature instead of parsing versions.
+ *
+ * Every entry reads the module that owns the capability; nothing here restates a fact by hand:
+ *
+ * - `quota-pool/1` when the management route registry declares `GET /api/quota-pool`. The registry
+ *   is reconciled against dispatch source (`tests/server/management-route-registry.test.ts`), so the
+ *   feature appears exactly when the route is reachable.
+ * - `fallback-policy/1` when the registry declares `GET /api/fallback` (OCX-11). GOAT reads a Home
+ *   without it as "fallback state unknown".
+ * - `link-management-relay` when the Remote Link management read table is non-empty.
+ * - `served-by-header` when the served-by emitter says responses carry the header.
+ * - `relay-auth/<n>` with the connection-bound link relay auth version.
+ * - `link-peer-report/<n>` with the version of the report a Child sends on the relay challenge and a
+ *   Home records for `ocx link status` (`src/link/peer-report.ts`).
+ *
+ * The ids are static strings. They carry no account, credential or configuration data, which is
+ * what keeps the unauthenticated `/readyz` body safe. `parseRemoteReadyMetadata` accepts at most
+ * 64 unique ids of at most 80 characters, and `tests/server/readyz-features.test.ts` holds the
+ * full registry to that.
+ */
+import { LINK_MANAGEMENT_READ_PATHS } from "../link/management-routes";
+import { LINK_PEER_REPORT_VERSION } from "../link/peer-report";
+import { LINK_RELAY_AUTH_VERSION } from "../link/relay-auth";
+import { MANAGEMENT_ROUTES, type ManagementRoute } from "../server/management/route-registry";
+import { SERVED_BY_HEADER_EMITTED } from "./served-by";
+
+export const QUOTA_POOL_PATH = "/api/quota-pool";
+export const FALLBACK_STATE_PATH = "/api/fallback";
+
+/** The owning sources the registry reads. Tests pass their own to drive presence and absence. */
+export interface PeerFeatureSources {
+  readonly managementRoutes: readonly Pick<ManagementRoute, "method" | "path">[];
+  readonly linkManagementReadPaths: readonly string[];
+  readonly servedByHeaderEmitted: boolean;
+  readonly relayAuthVersion: string;
+  readonly linkPeerReportVersion: string;
+}
+
+/** One feature: its id when the sources say it is served, otherwise null. */
+export type PeerFeature = (sources: PeerFeatureSources) => string | null;
+
+/** Ordered; `/readyz` lists the served ids in this order. */
+export const PEER_FEATURES: readonly PeerFeature[] = [
+  s => s.managementRoutes.some(route => route.method === "GET" && route.path === QUOTA_POOL_PATH) ? "quota-pool/1" : null,
+  s => s.managementRoutes.some(route => route.method === "GET" && route.path === FALLBACK_STATE_PATH) ? "fallback-policy/1" : null,
+  s => s.linkManagementReadPaths.length > 0 ? "link-management-relay" : null,
+  s => s.servedByHeaderEmitted ? "served-by-header" : null,
+  s => `relay-auth/${s.relayAuthVersion}`,
+  s => `link-peer-report/${s.linkPeerReportVersion}`,
+];
+
+export function currentPeerFeatureSources(): PeerFeatureSources {
+  return {
+    managementRoutes: MANAGEMENT_ROUTES,
+    linkManagementReadPaths: LINK_MANAGEMENT_READ_PATHS,
+    servedByHeaderEmitted: SERVED_BY_HEADER_EMITTED,
+    relayAuthVersion: LINK_RELAY_AUTH_VERSION,
+    linkPeerReportVersion: LINK_PEER_REPORT_VERSION,
+  };
+}
+
+export function servedPeerFeatures(sources: PeerFeatureSources = currentPeerFeatureSources()): string[] {
+  return PEER_FEATURES.map(feature => feature(sources)).filter((id): id is string => id !== null);
+}
+
+let buildFeatures: readonly string[] | undefined;
+
+/** This build's served features. The sources are build constants, so the list is computed once. */
+export function buildPeerFeatures(): string[] {
+  buildFeatures ??= Object.freeze(servedPeerFeatures());
+  return [...buildFeatures];
+}

package/src/remote/protocol.ts

@@ -1,4 +1,5 @@
 import type { OcxConfig } from "../types/config";
+import { buildPeerFeatures } from "./features";
 
 export const REMOTE_HUB_PROTOCOL = 1;
 export const MINIMUM_REMOTE_CLIENT_PROTOCOL = 1;
@@ -53,6 +54,7 @@ export function readyProtocolMetadata(config: OcxConfig, req: Request): RemoteRe
     protocol: REMOTE_HUB_PROTOCOL,
     minimumClientProtocol: MINIMUM_REMOTE_CLIENT_PROTOCOL,
     managementUrl,
+    features: buildPeerFeatures(),
   };
 }