@bitkyc08/opencodex 2.8.0 → 2.9.0

package/src/server/lifecycle.ts

@@ -1,26 +1,111 @@
 import { flushResponseState } from "../responses/state";
 import { setStorageCleanupPolicyLiveSink } from "../storage/policy";
 import {
-  abortStorageCleanupPolicyJob,
+  abortStorageCleanupPolicyJobAsync,
   setStorageCleanupPolicyJobLiveApply,
 } from "../storage/policy-job";
+import { abortRestoreTrashJobAsync } from "../storage/restore-job";
 import { stopStorageCleanupScheduler } from "../storage/policy-scheduler";
+import { stopStateStoreSweeper } from "../lib/state-store-sweeper";
+import {
+  cancelQueuedStorageWorkerSpawns,
+  drainStorageWorkers,
+} from "../storage/worker-lifecycle";
+import { createAdmissionGate, type AdmissionLease, type AdmissionMetrics } from "../lib/admission";
+import { codexWebSocketAdmissionMetrics } from "../codex/websocket-registry";
+import { storageMutationAdmissionMetrics } from "../storage/storage-mutation-coordinator";
+import { storageWorkerAdmissionMetrics } from "../storage/worker-lifecycle";
+import {
+  backgroundShellAdmissionMetrics,
+  beginBackgroundShellShutdown,
+  terminateAllBackgroundShells,
+} from "../adapters/cursor/native-exec-shell";
 
 // ---------------------------------------------------------------------------
 // Active turn tracking + graceful shutdown drain
 // ---------------------------------------------------------------------------
 
-const activeTurns = new Set<AbortController>();
+export const MAX_ACTIVE_TURNS = 256;
+const turnGate = createAdmissionGate("active_turns", MAX_ACTIVE_TURNS);
+export interface ActiveTurnLease extends AdmissionLease {
+  bindAbortController(ac: AbortController): void;
+  isTransferred(): boolean;
+}
+const activeTurns = new Map<AbortController, ActiveTurnLease>();
+const admittedTurns = new Set<ActiveTurnLease>();
+const knownTurnControllers = new WeakSet<AbortController>();
+let turnReleaseMisses = 0;
 let draining = false;
 let recyclingForExit = false;
 let _serverRef: ReturnType<typeof Bun.serve> | undefined;
 
 export function setServerRef(server: ReturnType<typeof Bun.serve> | undefined): void { _serverRef = server; }
 export function setDraining(value: boolean): void { draining = value; }
-export function registerTurn(ac: AbortController): void { activeTurns.add(ac); }
-export function unregisterTurn(ac: AbortController): void { activeTurns.delete(ac); }
+export function tryAdmitTurn(): ActiveTurnLease | null {
+  const gateLease = turnGate.tryAcquire();
+  if (!gateLease) return null;
+  const controllers = new Set<AbortController>();
+  let active = true;
+  let transferred = false;
+  const lease: ActiveTurnLease = {
+    bindAbortController(ac) {
+      knownTurnControllers.add(ac);
+      if (!active) {
+        ac.abort(new Error("turn already settled"));
+        return;
+      }
+      transferred = true;
+      controllers.add(ac);
+      activeTurns.set(ac, lease);
+    },
+    isTransferred() { return transferred; },
+    release() {
+      if (!active) return;
+      active = false;
+      admittedTurns.delete(lease);
+      for (const controller of controllers) {
+        if (activeTurns.get(controller) === lease) activeTurns.delete(controller);
+      }
+      controllers.clear();
+      gateLease.release();
+    },
+  };
+  admittedTurns.add(lease);
+  return lease;
+}
+export function registerTurn(ac: AbortController, lease?: AdmissionLease): void {
+  if (lease && "bindAbortController" in lease) (lease as ActiveTurnLease).bindAbortController(ac);
+}
+export function unregisterTurn(ac: AbortController): void {
+  const lease = activeTurns.get(ac);
+  if (!lease) {
+    if (knownTurnControllers.has(ac)) return;
+    turnReleaseMisses += 1;
+    return;
+  }
+  lease.release();
+}
 export function isDraining(): boolean { return draining; }
-export function getActiveTurnCount(): number { return activeTurns.size; }
+export function getActiveTurnCount(): number { return turnGate.metrics().active; }
+export function activeRegistryMetrics(): Record<string, AdmissionMetrics> {
+  const turns = turnGate.metrics();
+  return {
+    activeTurns: { ...turns, releaseMisses: turns.releaseMisses + turnReleaseMisses },
+    codexWebSockets: codexWebSocketAdmissionMetrics(),
+    cursorBackgroundShells: backgroundShellAdmissionMetrics(),
+    storageHomeSlots: storageMutationAdmissionMetrics(),
+    storageWorkerReservations: storageWorkerAdmissionMetrics(),
+  };
+}
+
+export function abortAndReleaseAllTurns(reason: unknown = new Error("server shutdown")): void {
+  const owners = [...admittedTurns];
+  for (const owner of owners) {
+    const controllers = [...activeTurns].filter(([, lease]) => lease === owner).map(([controller]) => controller);
+    for (const controller of controllers) controller.abort(reason);
+    owner.release();
+  }
+}
 /** Live listen port of the Bun server, when started. */
 export function getServerListenPort(): number | undefined {
   const port = _serverRef?.port;
@@ -38,8 +123,9 @@ export function trackStreamLifetime(
   body: ReadableStream<Uint8Array>,
   ac: AbortController,
   onDone?: () => void,
+  lease?: AdmissionLease,
 ): ReadableStream<Uint8Array> {
-  registerTurn(ac);
+  registerTurn(ac, lease);
   const reader = body.getReader();
   let closed = false;
   const finish = () => {
@@ -73,25 +159,69 @@ export async function drainAndShutdown(
 ): Promise<void> {
   const s = server ?? _serverRef;
   draining = true;
-  const deadline = Date.now() + timeoutMs;
-  while (activeTurns.size > 0 && Date.now() < deadline) {
-    await Bun.sleep(100);
-  }
-  if (activeTurns.size > 0) {
-    console.warn(`⚠️  Aborting ${activeTurns.size} in-flight turn(s) after ${timeoutMs}ms deadline`);
-    for (const ac of activeTurns) {
-      ac.abort(new Error("server shutdown"));
+  beginBackgroundShellShutdown();
+  try {
+    const deadline = Date.now() + timeoutMs;
+    while (admittedTurns.size > 0 && Date.now() < deadline) {
+      await Bun.sleep(100);
+    }
+    if (admittedTurns.size > 0) {
+      console.warn(`⚠️  Aborting ${admittedTurns.size} in-flight turn(s) after ${timeoutMs}ms deadline`);
+      abortAndReleaseAllTurns(new Error("server shutdown"));
+    }
+
+    const shellDrain = await Promise.allSettled([terminateAllBackgroundShells()]);
+    const shellResult = shellDrain[0]!;
+    if (shellResult.status === "rejected") {
+      console.warn("[cursor] background shell drain failed", { rejected: 1 });
+    } else if (shellResult.value.unresolved > 0 || shellResult.value.killFailures > 0) {
+      console.warn("[cursor] background shell drain incomplete", shellResult.value);
+    }
+
+    // Debounced replay-state snapshot may still be pending; flush so the last completed turn's
+    // previous_response_id chain survives the restart this shutdown is usually part of.
+    const responseStateFlush = await Promise.allSettled([flushResponseState()]);
+    if (responseStateFlush[0]?.status === "rejected") {
+      console.warn("[responses] state flush during shutdown failed");
+    }
+
+    // Tear down opt-in storage policy timers / worker / live-config sink so they cannot fire after stop.
+    // Await worker thread exit: on Windows, a still-exiting Bun Worker under
+    // `bun test --isolate` panics the whole process at the next realm reclaim.
+    // Abort each job independently so one wedged join cannot skip the other,
+    // then drain leftovers; failures must not prevent `server.stop`.
+    stopStorageCleanupScheduler();
+    stopStateStoreSweeper();
+    cancelQueuedStorageWorkerSpawns();
+    const shutdownJoins = await Promise.allSettled([
+      abortStorageCleanupPolicyJobAsync(),
+      abortRestoreTrashJobAsync(),
+    ]);
+    for (const result of shutdownJoins) {
+      if (result.status === "rejected") {
+        console.warn(
+          "[storage] worker abort during shutdown failed:",
+          result.reason instanceof Error ? result.reason.message : result.reason,
+        );
+      }
+    }
+    try {
+      await drainStorageWorkers();
+    } catch (err) {
+      console.warn(
+        "[storage] worker drain during shutdown failed:",
+        err instanceof Error ? err.message : err,
+      );
+    }
+    setStorageCleanupPolicyLiveSink(null);
+    setStorageCleanupPolicyJobLiveApply(null);
+  } finally {
+    try {
+      // Bun's Server.stop returns Promise<void>; fire-and-forget races the next
+      // isolate reclaim / follow-on listen the same way unterminated Workers did.
+      if (s) await s.stop(true);
+    } finally {
+      draining = false;
     }
-    activeTurns.clear();
   }
-  // Debounced replay-state snapshot may still be pending; flush so the last completed turn's
-  // previous_response_id chain survives the restart this shutdown is usually part of.
-  await flushResponseState();
-  // Tear down opt-in storage policy timers / worker / live-config sink so they cannot fire after stop.
-  stopStorageCleanupScheduler();
-  abortStorageCleanupPolicyJob();
-  setStorageCleanupPolicyLiveSink(null);
-  setStorageCleanupPolicyJobLiveApply(null);
-  s?.stop(true);
-  draining = false;
 }

package/src/server/management/agent-settings-routes.ts

@@ -7,6 +7,7 @@ import {
   codexAutoStartEnabled,
   hasOwnProvider,
   isValidProviderName,
+  loadConfig,
   multiAgentGuidanceEnabled,
   providerBaseUrlConfigError,
   providerHeadersConfigError,
@@ -58,16 +59,68 @@ import { applySystemEnvToggle } from "../system-env";
 
 import { isPlainRecord, parseDebugLogQuery, tokPerSecondResult, unavailableCostReason, costResult, requestLogDto, stripRegistryOnlyStaticHeaders, fetchAllModels, fetchGrokCandidateModels, buildClaudeDesktopState } from "./shared";
 import type { MetricUnavailableReason, TokPerSecondResult, CostEstimateReason, CostResult, MetricSource } from "./shared";
+import { readManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
 
-let grokApplyChain: Promise<unknown> = Promise.resolve();
-/**
- * Serializes Grok applies: injectGrokConfig is read-modify-write over a single file,
- * so two concurrent clicks must not interleave two cycles.
- */
-function queueGrokApply<T>(run: () => Promise<T>): Promise<T> {
-  const next = grokApplyChain.then(run, run);
-  grokApplyChain = next.catch(() => {});
-  return next;
+const GROK_APPLY_JOIN_MS = 120_000;
+export const GROK_APPLY_TERMINAL_MS = 10 * 60_000;
+const grokApplyEncoder = new TextEncoder();
+let grokApplyFlight: { startedAt: number; promise: Promise<unknown>; bytes: number } | null = null;
+let grokApplyHighWaterBytes = 0;
+let grokApplyTestHooks: { now?: () => number; run?: () => Promise<unknown> } | null = null;
+
+class GrokApplyBusyError extends Error {}
+
+export function grokApplyFlightSnapshot(): { currentBytes: number; highWaterBytes: number; active: number } {
+  return {
+    currentBytes: grokApplyFlight?.bytes ?? 0,
+    highWaterBytes: grokApplyHighWaterBytes,
+    active: grokApplyFlight ? 1 : 0,
+  };
+}
+
+function runGrokApplyFlight(): Promise<unknown> {
+  const at = grokApplyTestHooks?.now?.() ?? Date.now();
+  const current = grokApplyFlight;
+  if (current) {
+    const age = at - current.startedAt;
+    if (age < GROK_APPLY_JOIN_MS) return current.promise;
+    if (age <= GROK_APPLY_TERMINAL_MS) return Promise.reject(new GrokApplyBusyError("grok_apply_busy"));
+    // A permanently hung operation must not monopolize the singleton forever. Its
+    // eventual finally is identity-checked, so it cannot clear a replacement flight.
+    if (grokApplyFlight === current) grokApplyFlight = null;
+  }
+
+  const flight = { startedAt: at, promise: Promise.resolve() as Promise<unknown>, bytes: 0 };
+  flight.promise = (grokApplyTestHooks?.run ?? (async () => {
+    const [{ syncGrokConfig }, { readRuntimePort }] = await Promise.all([
+      import("../../grok/sync"),
+      import("../../config"),
+    ]);
+    const currentConfig = loadConfig();
+    const runtime = readRuntimePort(process.pid);
+    const port = runtime?.port ?? currentConfig.port;
+    const hostname = runtime?.hostname ?? currentConfig.hostname;
+    flight.bytes = grokApplyEncoder.encode(JSON.stringify(currentConfig)).byteLength
+      + grokApplyEncoder.encode(hostname ?? "").byteLength;
+    grokApplyHighWaterBytes = Math.max(grokApplyHighWaterBytes, flight.bytes);
+    return syncGrokConfig(port, currentConfig, hostname !== undefined ? { hostname } : {});
+  }))().finally(() => {
+    if (grokApplyFlight === flight) grokApplyFlight = null;
+  });
+  grokApplyFlight = flight;
+  return flight.promise;
+}
+
+export function runGrokApplyFlightForTests(): Promise<unknown> {
+  return runGrokApplyFlight();
+}
+
+export function setGrokApplyFlightTestHooks(
+  hooks: { now?: () => number; run?: () => Promise<unknown> } | null,
+): void {
+  grokApplyTestHooks = hooks;
+  grokApplyFlight = null;
+  grokApplyHighWaterBytes = 0;
 }
 import type { ManagementContext } from "./context";
 
@@ -80,12 +133,12 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       if (config.claudeCode?.desktopAutoApply === false) return;
       if (!config.claudeCode?.desktopProfile) return;
       const { writeDesktop3pConfig } = await import("../../claude/desktop-3p");
-      const { visibleNativeSlugs, filterCatalogVisibleModels } = await import("../../codex/catalog");
+      const { filterCatalogVisibleModels, desktopVisibleNativeSlugs } = await import("../../codex/catalog");
       const allModels = await fetchAllModels(config);
       const routed = filterCatalogVisibleModels(allModels, config).map(m => ({ provider: m.provider, id: m.id, contextWindow: m.contextWindow }));
       const result = writeDesktop3pConfig(
         config.port ?? 10100,
-        [...visibleNativeSlugs(config)],
+        [...desktopVisibleNativeSlugs(config)],
         routed,
         config.apiKeys?.[0]?.key,
         "static",
@@ -131,7 +184,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       agentsMaxDepth?: unknown;
       subagentDeveloperInstructions?: unknown;
     };
-    try { body = await req.json(); } catch { return jsonResponse({ error: "invalid JSON body" }, 400); }
+    try { body = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
     const wantsFlag = body.enabled !== undefined;
     const wantsThreads = body.maxConcurrentThreadsPerSession !== undefined;
     const wantsMode = body.multiAgentMode !== undefined;
@@ -275,7 +328,8 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
   }
   if (url.pathname === "/api/injection-model" && req.method === "PUT") {
     let parsedBody: unknown;
-    try { parsedBody = await req.json(); } catch {
+    try { parsedBody = await readManagementJsonBody(req); } catch (error) {
+      rethrowManagementBodyTooLarge(error);
       return jsonResponse({ error: "invalid JSON body" }, 400);
     }
     if (!parsedBody || typeof parsedBody !== "object" || Array.isArray(parsedBody)) {
@@ -374,7 +428,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
   }
   if (url.pathname === "/api/effort-caps" && req.method === "PUT") {
     let body: { effortCap?: unknown; subagentEffortCap?: unknown };
-    try { body = await req.json(); } catch { return jsonResponse({ error: "invalid JSON body" }, 400); }
+    try { body = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
     const { isCodexReasoningEffort } = await import("../../reasoning-effort");
     for (const key of ["effortCap", "subagentEffortCap"] as const) {
       if (!(key in body)) continue;
@@ -410,7 +464,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
   }
   if (url.pathname === "/api/subagent-models" && req.method === "PUT") {
     let body: { models?: unknown };
-    try { body = await req.json(); } catch { return jsonResponse({ error: "invalid JSON body" }, 400); }
+    try { body = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
     const chosen = Array.isArray(body.models) ? body.models.filter((m): m is string => typeof m === "string").slice(0, 5) : [];
     config.subagentModels = chosen;
     const { saveConfigPreservingClaudeCode: save } = await import("../../config");
@@ -444,8 +498,9 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
   if (url.pathname === "/api/subagent-model-fallback" && req.method === "PUT") {
     let body: { models?: unknown; pollMs?: unknown };
     try {
-      body = await req.json();
-    } catch {
+      body = await readManagementJsonBody(req);
+    } catch (error) {
+      rethrowManagementBodyTooLarge(error);
       return jsonResponse({ error: "invalid JSON body" }, 400);
     }
     if (!body || typeof body !== "object" || Array.isArray(body)) {
@@ -513,7 +568,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
   // injectGrokConfig, through the apply route below — this route cannot touch that file.
   if (url.pathname === "/api/grok/selection" && req.method === "PUT") {
     let body: { excluded?: unknown };
-    try { body = await req.json(); } catch { return jsonResponse({ error: "invalid JSON body" }, 400); }
+    try { body = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
     const raw = body.excluded;
     if (!Array.isArray(raw) || raw.some(entry => typeof entry !== "string" || entry.length === 0)) {
       return jsonResponse({ error: "excluded must be an array of model ids" }, 400);
@@ -533,20 +588,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
   // duplicated here. Accepts no body: every input comes from persisted state.
   if (url.pathname === "/api/grok/apply" && req.method === "POST") {
     try {
-      const { syncGrokConfig } = await import("../../grok/sync");
-      const { readRuntimePort } = await import("../../config");
-      // The host/port the proxy ACTUALLY bound — not the request authority (caller-
-      // influenced) and not config.hostname, which sync.ts warns may have drifted.
-      // `ocx ensure` passes live.hostname for the same reason; the runtime-port record
-      // is the in-process equivalent, written at startup.
-      const runtime = readRuntimePort(process.pid);
-      const port = runtime?.port ?? config.port;
-      const hostname = runtime?.hostname ?? config.hostname;
-      const result = await queueGrokApply(() => syncGrokConfig(
-        port,
-        config,
-        hostname !== undefined ? { hostname } : {},
-      ));
+      const result = await runGrokApplyFlight() as Awaited<ReturnType<typeof import("../../grok/sync")["syncGrokConfig"]>>;
       // A policy skip (non-loopback, no ~/.grok) is not a server error: report it as a
       // result the page can explain rather than a 500 the user cannot act on.
       return jsonResponse({
@@ -556,6 +598,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
         ...(result.skippedReason ? { skippedReason: result.skippedReason } : {}),
       }, result.ok ? 200 : 500);
     } catch (error) {
+      if (error instanceof GrokApplyBusyError) return jsonResponse({ error: "grok_apply_busy" }, 409);
       return jsonResponse({ error: error instanceof Error ? error.message : String(error) }, 400);
     }
   }
@@ -572,7 +615,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
   }
   if (url.pathname === "/api/claude-desktop" && req.method === "PUT") {
     let body: { profile?: unknown };
-    try { body = await req.json(); } catch { return jsonResponse({ error: "invalid JSON body" }, 400); }
+    try { body = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
     try {
       const { parseDesktopProfile, reconcileDesktopProfile } = await import("../../claude/desktop-profile");
       const parsed = parseDesktopProfile(body.profile);
@@ -607,7 +650,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       config.claudeCode = { ...(config.claudeCode ?? {}), desktopProfile: state.profile };
       saveConfigPreservingClaudeCode(config);
       const { writeDesktop3pConfig } = await import("../../claude/desktop-3p");
-      const { visibleNativeSlugs } = await import("../../codex/catalog");
+      const { desktopVisibleNativeSlugs } = await import("../../codex/catalog");
       const routed = state.models
         .filter(model => model.available && !model.route.startsWith("native/"))
         .map(model => {
@@ -616,7 +659,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
         });
       const result = writeDesktop3pConfig(
         Number(url.port) || config.port,
-        [...visibleNativeSlugs(config)],
+        [...desktopVisibleNativeSlugs(config)],
         routed,
         config.apiKeys?.[0]?.key,
         "static",
@@ -770,7 +813,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
     // regardless on 2.1.207). PUT keeps validating them so hand-written configs
     // and older GUIs stay safe; GUI saves omit them and the spread preserves them.
     let parsedBody: unknown;
-    try { parsedBody = await req.json(); } catch { return jsonResponse({ error: "invalid JSON body" }, 400); }
+    try { parsedBody = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
     const isPlainObject = (value: unknown): value is Record<string, unknown> => {
       if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
       const prototype = Object.getPrototypeOf(value);

package/src/server/management/api-key-usage.ts

@@ -0,0 +1,167 @@
+import {
+  currentUsageLogRevision,
+  readUsageSnapshotForManagement,
+  usageLogRevisionKey,
+  type PersistedUsageEntry,
+} from "../../usage/log";
+
+/**
+ * Per-key usage as the API tab renders it.
+ *
+ * A discriminated union rather than numbers with a flag beside them: when two
+ * config entries share an id there IS no per-key total, and an optional marker
+ * next to `requests7d: 7` invites a consumer to render the 7 anyway.
+ */
+export type ApiKeyUsage =
+  | { ambiguous: true }
+  | { ambiguous?: false; requests7d: number; totalRequests: number; lastUsedAt?: string };
+
+export interface ApiKeyUsageSnapshot {
+  rollup: Map<string, ApiKeyUsage>;
+  historyTruncated?: true;
+  /**
+   * Earliest row carrying a recognized `admissionKind`. A property of the DATA
+   * SET, not of a key, so it is singular and lives beside the map: it is what
+   * lets the GUI tell "this key was used zero times" from "nothing is
+   * attributable yet". Keyed on the kind rather than on `apiKeyId`, because an
+   * environment or loopback row is attributed traffic with no configured key.
+   */
+  attributionSince?: string;
+}
+
+const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
+
+/**
+ * A timestamp we can actually do date arithmetic with.
+ *
+ * `usage.jsonl` is hand-editable and JSON permits numbers outside the Date
+ * range: `1e309` survives normalization and then throws `RangeError` from
+ * `toISOString()`. Since the caller catches to protect key management, one bad
+ * row would have zeroed the rollup for EVERY key — active keys reported as
+ * unused is exactly the wrong answer to hand someone deciding what to delete.
+ */
+function usableTimestamp(value: unknown): number | null {
+  if (typeof value !== "number" || !Number.isFinite(value)) return null;
+  return Number.isNaN(new Date(value).getTime()) ? null : value;
+}
+
+/**
+ * Pure: one pass over an already-read snapshot, so it is unit-testable without
+ * touching the filesystem.
+ *
+ * Rows are bucketed only when `admissionKind === "configured"`. Keying on
+ * `apiKeyId` alone would let a hand-edited entry whose id is `loopback` absorb
+ * traffic it never admitted.
+ */
+export function rollupApiKeyUsage(
+  entries: PersistedUsageEntry[],
+  configuredIds: string[],
+  now: number = Date.now(),
+): ApiKeyUsageSnapshot {
+  const duplicated = new Set<string>();
+  const seen = new Set<string>();
+  for (const id of configuredIds) {
+    if (seen.has(id)) duplicated.add(id);
+    seen.add(id);
+  }
+
+  const totals = new Map<string, { requests7d: number; totalRequests: number; lastUsedAt?: string }>();
+  let attributionSince: number | undefined;
+  const cutoff = now - SEVEN_DAYS_MS;
+
+  for (const entry of entries) {
+    if (!entry.admissionKind) continue;
+    const timestamp = usableTimestamp(entry.timestamp);
+    if (timestamp !== null && (attributionSince === undefined || timestamp < attributionSince)) {
+      attributionSince = timestamp;
+    }
+    if (entry.admissionKind !== "configured" || !entry.apiKeyId) continue;
+
+    const bucket = totals.get(entry.apiKeyId) ?? { requests7d: 0, totalRequests: 0 };
+    // The request happened even if its clock reading is unusable, so it still
+    // counts toward the total; only the time-based fields are skipped.
+    bucket.totalRequests += 1;
+    if (timestamp !== null) {
+      if (timestamp >= cutoff) bucket.requests7d += 1;
+      const iso = new Date(timestamp).toISOString();
+      if (!bucket.lastUsedAt || iso > bucket.lastUsedAt) bucket.lastUsedAt = iso;
+    }
+    totals.set(entry.apiKeyId, bucket);
+  }
+
+  const rollup = new Map<string, ApiKeyUsage>();
+  for (const id of configuredIds) {
+    if (duplicated.has(id)) {
+      rollup.set(id, { ambiguous: true });
+      continue;
+    }
+    rollup.set(id, totals.get(id) ?? { requests7d: 0, totalRequests: 0 });
+  }
+  return {
+    rollup,
+    ...(attributionSince !== undefined ? { attributionSince: new Date(attributionSince).toISOString() } : {}),
+  };
+}
+
+/**
+ * Rollup cache keyed by the exact usage-log revision, mirroring the /api/usage
+ * summary cache. Without it, every key-list read reparses an append-only log
+ * that only ever grows — and the GUI fetches this route on mount and after every
+ * create/rename/delete. The compact rollup is a handful of counters per key, so
+ * caching it costs nothing; a new row changes the revision and invalidates it.
+ */
+let rollupCache: { revisionKey: string; expiresAt: number; snapshot: ApiKeyUsageSnapshot } | null = null;
+
+/**
+ * The rollup is a function of the log AND of the clock: a request ages out of
+ * the seven-day window with no write to bump the file revision, so a purely
+ * revision-keyed entry would report a stale `requests7d` indefinitely.
+ *
+ * A minute is the whole rule. Deriving the exact next-transition instant would
+ * mean tracking the OLDEST counted request per key, which the compact rollup
+ * deliberately does not keep — and a count that can be at most 60s stale is
+ * already far tighter than the window it describes.
+ */
+const ROLLUP_CACHE_TTL_MS = 60_000;
+
+/** Test seam: the cache is module state and would otherwise leak between cases. */
+export function clearApiKeyUsageCacheForTests(): void {
+  rollupCache = null;
+}
+
+/**
+ * Reads the durable usage snapshot the way /api/usage does, then rolls it up.
+ *
+ * Never throws: an unreadable snapshot yields empty rollups and no
+ * `attributionSince`. Key management working matters more than usage numbers
+ * being present, and the GUI already treats an absent field as "no data".
+ */
+export async function readApiKeyUsageRollup(configuredIds: string[], maxReadBytes?: number): Promise<ApiKeyUsageSnapshot> {
+  // JSON rather than a joined string: ids are only validated as non-empty
+  // strings, so `["a\0b","c"]` and `["a","b\0c"]` join to the same value and one
+  // config could be served the other's cached rollup.
+  const idsKey = JSON.stringify([configuredIds, maxReadBytes]);
+  const now = Date.now();
+  try {
+    const observedKey = `${usageLogRevisionKey(currentUsageLogRevision())}|${idsKey}`;
+    if (rollupCache?.revisionKey === observedKey && now < rollupCache.expiresAt) {
+      return rollupCache.snapshot;
+    }
+
+    const snapshot = await readUsageSnapshotForManagement(maxReadBytes);
+    const rolled = {
+      ...rollupApiKeyUsage(snapshot.entries, configuredIds, now),
+      ...(snapshot.truncatedPrefixBytes > 0 || snapshot.entriesTruncated ? { historyTruncated: true as const } : {}),
+    };
+    rollupCache = {
+      revisionKey: `${usageLogRevisionKey(snapshot.revision)}|${idsKey}`,
+      expiresAt: now + ROLLUP_CACHE_TTL_MS,
+      snapshot: rolled,
+    };
+    return rolled;
+  } catch {
+    const rollup = new Map<string, ApiKeyUsage>();
+    for (const id of configuredIds) rollup.set(id, { requests7d: 0, totalRequests: 0 });
+    return { rollup };
+  }
+}

package/src/server/management/body.ts

@@ -0,0 +1,35 @@
+import type { OcxConfig } from "../../types";
+import { jsonResponse } from "../auth-cors";
+import {
+  DecompressedBodyTooLargeError,
+  readBoundedJsonRequestBody,
+} from "../request-decompress";
+
+export const MANAGEMENT_JSON_BODY_MAX_BYTES = 4 * 1024 * 1024;
+
+export function readManagementJsonBody<T = unknown>(req: Request): Promise<T> {
+  return readBoundedJsonRequestBody(req, MANAGEMENT_JSON_BODY_MAX_BYTES) as Promise<T>;
+}
+
+export function managementBodyTooLargeResponse(
+  error: unknown,
+  req: Request,
+  config: OcxConfig,
+): Response | null {
+  return error instanceof DecompressedBodyTooLargeError
+    ? jsonResponse({ error: "request body too large" }, 413, req, config)
+    : null;
+}
+
+export function rethrowManagementBodyTooLarge(error: unknown): void {
+  if (error instanceof DecompressedBodyTooLargeError) throw error;
+}
+
+export async function readManagementJsonBodyOr<T>(req: Request, fallback: T): Promise<unknown | T> {
+  try {
+    return await readManagementJsonBody(req);
+  } catch (error) {
+    rethrowManagementBodyTooLarge(error);
+    return fallback;
+  }
+}