feat(usage): add configurable usage history size limit

docs-site/src/content/docs/guides/web-dashboard.md

@@ -92,7 +92,7 @@ badge or the version value to read the full value.
 | **Subagents** | Feature up to five bare native or namespaced routed models in the `spawn_agent` override list. |
 | **Models** | Toggle native GPT and routed models, set provider allowlists and context caps, choose v1/base/v2, and configure the v2 thread limit. Configured providers stay visible as zero-model groups when discovery is off or returns no rows. |
 | **Logs** | Auto-refresh recent requests with tokens, requested effort and (when available) effective outbound effort, resolved model, provider, status, request id, duration, and error details. The detail view includes the exact reasoning wire field when the adapter emits one. Filter by opaque conversation/session id (when the client sends one) to total tokens and estimated list-price cost for the currently loaded Logs ring. |
-| **Usage / Debug** | Inspect token-usage coverage and trends, or enable opt-in provider transport and usage-extraction diagnostics. |
+| **Usage / Debug** | Inspect token-usage coverage and trends. The **Usage** page also exposes the opt-in size ceiling for `usage.jsonl` (`usageLedgerRetention.enabled` / `maxBytes`); the background scheduler compacts older complete rows when the ceiling is exceeded. Enable provider transport and usage-extraction diagnostics here as needed. |
 | **Storage** | Read-only CODEX_HOME disk breakdown (sessions, archives, DBs, attachments). Optional archived cleanup: preview the oldest N%, then quarantine to `CODEX_HOME/.trash` (default) or permanently delete behind an explicit checkbox. **Auto-cleanup policy** is opt-in and **default OFF** (`storageCleanupPolicy.enabled`); configure threshold/target/schedule/mode on the Storage page, or trigger **Run now**. Quarantined entries can be restored from the Storage page (JSONL + threads). Active sessions stay read-only. Cleanup and restore are refused while Codex holds the newest/active `state_*.sqlite` locked. |
 | **Stop** | Gracefully stop the proxy and installed background service, restore native Codex, and exit (`POST /api/stop`). On Windows with the Task Scheduler backend the dashboard refuses and asks you to run `ocx stop` instead: that wrapper can respawn the proxy after the task ends, and only a stop running outside this process can verify the restart window before restoring your client config. Nothing is changed when it refuses. |
 

docs-site/src/content/docs/reference/cli/agents.md

@@ -162,6 +162,21 @@ separately, and requests with no matching price row are counted as
 ocx usage --range today --provider xai
 ```
 
+### `ocx storage usage-limit`
+
+Inspect or change the opt-in `usage.jsonl` size ceiling. The setting is also available in the
+dashboard on the **Usage** page.
+
+```bash
+ocx storage usage-limit show --json
+ocx storage usage-limit set --enabled true --mib 512 --json
+```
+
+`set` sends only the fields supplied, so changing `--mib` preserves the saved enabled state.
+The minimum ceiling is 1 MiB. A bare `usage-limit` invocation is read-only. The background
+scheduler compacts complete JSONL rows after the ledger exceeds the configured ceiling. The
+command drives `GET`/`PUT /api/storage/usage-ledger-retention` on the running proxy.
+
 ### `ocx debug <provider|usage|injection|claude> <on|off|status|reset|logs [-f]>`
 
 Read or change runtime debug overrides through the running proxy's management API.

docs-site/src/content/docs/reference/configuration/server.md

@@ -23,6 +23,7 @@ runs helper features around provider requests.
 | `corsAllowOrigins?` | `string[]` | `[]` | Additional exact origins allowed by CORS. Loopback origins are always allowed. Authority-based browser extension origins such as `chrome-extension://<extension-id>` are supported; `*` is not a wildcard. Firefox and Safari regenerate the extension UUID (per install / per browser launch), so update the entry when the origin changes. |
 | `apiKeys?` | `OcxApiKey[]` | `[]` | Generated `ocx_…` credentials accepted by management and data-plane auth on non-loopback binds. Dashboard-managed. |
 | `storageCleanupPolicy?` | `StorageCleanupPolicy` | disabled | Opt-in archived-session cleanup policy. Never enabled implicitly. |
+| `usageLedgerRetention?` | `UsageLedgerRetentionConfig` | disabled | Opt-in cap for the append-only `usage.jsonl` usage ledger. When enabled, the background scheduler compacts complete rows after the ledger exceeds `maxBytes`. |
 | `appOwnedMemoryBudgetMb?` | `number` | `256` | Cap in MiB for evictable app-owned logs, caches, blobs, and continuation payloads. Range 64–4096; not an RSS cap. |
 | `codexAutoStart?` | `boolean` | `true` | Let the Codex shim run `ocx ensure` before launching Codex. False makes ensure a no-op. |
 | `codexShimAutoRestore?` | `boolean` | `true` | Restore an installed shim after a completed external Codex update replaces it. Environment opt-out: `OPENCODEX_CODEX_SHIM_AUTO_RESTORE=0`. |
@@ -259,6 +260,38 @@ either `target.reduceToBytes` or `target.removeOldestPercent`. `mode` defaults t
 Configure it on the Storage page or with `GET`/`PUT /api/storage/cleanup-policy`; trigger a manual run
 with `POST /api/storage/cleanup-policy/run`.
 
+## Usage-ledger retention
+
+`usageLedgerRetention` is disabled by default. It is an opt-in size ceiling for
+`$OPENCODEX_HOME/usage.jsonl`, the append-only usage ledger used by the Usage page and
+`GET /api/usage`. Enabling it lets the proxy compact older rows in a background Worker once
+the file exceeds the configured limit; normal request handling is not blocked by the scan.
+
+```json
+{
+  "usageLedgerRetention": {
+    "enabled": false
+  }
+}
+```
+
+The effective default is **Unlimited** (`enabled: false`). An unconfigured installation remembers
+**1 GiB** (`1073741824`) as `maxBytes`; that saved value becomes effective on first enable. Set
+`maxBytes` explicitly only when selecting a different ceiling. Any explicit value must be a safe
+integer of at least 1 MiB (`1048576`). A saved ceiling is retained when `enabled` is set to `false`,
+so an operator can pause retention without losing the selected limit. Unknown keys and malformed
+values fail closed and leave retention disabled.
+
+Compaction publishes a complete JSONL-row candidate only after the source revision and active-turn
+checks still match. An unterminated crash tail is discarded; a single row larger than the ceiling
+is dropped so the published ledger remains bounded. The derived request-history projection is
+recreated after a successful publish. A policy change invalidates an in-flight candidate, and a
+source append during scanning defers the commit for a later run.
+
+The dashboard exposes this control on the **Usage** page. For headless operation, use
+`ocx storage usage-limit` or the `GET`/`PUT` management routes below. Setting the policy is
+non-destructive; the background scheduler compacts older rows when the ceiling is exceeded.
+
 ## Quota-reset notifications (`quotaResetNotify`)
 
 Off by default. When the section is absent, no detection runs, no timer starts, and no state

docs-site/src/content/docs/reference/management-api.md

@@ -184,6 +184,8 @@ by the current window size.
 | `GET /api/claude/inbound-debug` | Read Claude inbound debug state and entries | — |
 | `GET /api/usage` | Stream the complete usage ledger into compact aggregates, then incrementally fold verified appends; summarize by preset or inclusive custom window and client surface, with a Codex `accounts` breakdown keyed by stable non-PII log labels | 400 invalid custom bounds; returns an `error: "read_failed"` summary if storage cannot be read |
 | `GET /api/storage` | Scan Codex storage usage by bucket | Returns an `error: "scan_failed"` payload on scan failure |
+| `GET /api/storage/usage-ledger-retention` | Read the usage-ledger retention policy, current `usage.jsonl` size, over-limit state, and the last background job state | — |
+| `PUT /api/storage/usage-ledger-retention` | Replace the retention fields supplied in `{ "enabled"?: boolean, "maxBytes"?: integer }`; omitted fields keep their saved values | 400 malformed body, unknown field, or `maxBytes` below 1 MiB; 500 `config_write_failed` |
 | `POST /api/storage/cleanup/preview` | Preview archived-session cleanup and return a binding digest | 400 `invalid_json` or `invalid_percent` |
 | `POST /api/storage/cleanup` | Quarantine or permanently remove the previewed archived set | 400 invalid input; 409 stale/busy/referenced state; 500 filesystem/database failure |
 | `GET /api/storage/trash` | List quarantined cleanup entries | 500 `trash_list_failed` |
@@ -193,6 +195,13 @@ by the current window size.
 | `POST /api/storage/cleanup-policy/run` | Start a manual cleanup-policy run | 409 `already_running`; 500 `cleanup_failed` |
 | `GET /api/storage/cleanup-policy/test-stream` | Test-only policy stream hook | 404 `not_found` when unavailable |
 
+The retention status response is shaped as `{ enabled, maxBytes, currentBytes, overLimit, job }`;
+`job` reports the process-local background state (`idle` or `running`) and the last outcome when
+one exists. `PUT` accepts only `enabled` and `maxBytes`, and merges the supplied fields with the
+saved policy. It never starts a compaction by itself. The background scheduler queues a Worker
+when the ledger exceeds the ceiling; the canonical ledger is replaced only after complete-row,
+active-turn, and source-revision checks pass.
+
 New xAI attempts in `usage.jsonl` include a request-time `credentialSource`: `grok-oauth`
 for the resolved Grok CLI OAuth transport, or `xai-api-key` for the public xAI API key
 transport. This fixed label contains no credential or account identifier. It belongs to

gui/src/components/usage/UsageLedgerRetentionControl.tsx

@@ -0,0 +1,243 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { clampNumberDraft } from "../../clamp-draft";
+import { formatBytes } from "../../format-bytes";
+import { useI18n } from "../../i18n/shared";
+import { Switch } from "../../ui";
+import { NumberStepper } from "../NumberStepper";
+
+const MIB = 1024 ** 2;
+const MAX_MIB = Math.floor(Number.MAX_SAFE_INTEGER / MIB);
+
+interface RetentionStatus {
+  enabled: boolean;
+  maxBytes: number;
+  currentBytes?: number;
+}
+
+function parseStatus(value: unknown): RetentionStatus {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("invalid_status");
+  const candidate = value as Record<string, unknown>;
+  if (typeof candidate.enabled !== "boolean" || typeof candidate.maxBytes !== "number"
+    || !Number.isFinite(candidate.maxBytes) || candidate.maxBytes <= 0) {
+    throw new Error("invalid_status");
+  }
+  return {
+    enabled: candidate.enabled,
+    maxBytes: candidate.maxBytes,
+    currentBytes: typeof candidate.currentBytes === "number" && Number.isFinite(candidate.currentBytes)
+      ? candidate.currentBytes
+      : undefined,
+  };
+}
+
+function formatMaxMiBDraft(maxBytes: number): string {
+  return Number.isFinite(maxBytes) && maxBytes > 0 ? String(maxBytes / MIB) : "";
+}
+
+function parseMaxMiBDraft(raw: string): number | null {
+  const mib = Number(raw.trim());
+  if (!Number.isSafeInteger(mib) || mib < 1 || mib > MAX_MIB) return null;
+  const bytes = mib * MIB;
+  return Number.isSafeInteger(bytes) ? bytes : null;
+}
+
+/**
+ * Usage-page control for the opt-in usage-ledger byte ceiling.
+ *
+ * The dashboard keeps the switch as the primary action and exposes a MiB-aligned
+ * custom editor only while the policy is enabled. Toggling the switch always
+ * sends the exact server-reported byte value, so existing non-MiB-aligned values
+ * can never be rounded or silently rewritten.
+ */
+export default function UsageLedgerRetentionControl({ apiBase }: { apiBase: string }) {
+  const { locale, t } = useI18n();
+  const mibLabel = formatBytes(MIB, locale).replace(/^[\d.,]+\s*/, "");
+  const [status, setStatus] = useState<RetentionStatus | null>(null);
+  const [customDraft, setCustomDraft] = useState("");
+  const [editing, setEditing] = useState(false);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const loadGeneration = useRef(0);
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  const load = useCallback(async (signal?: AbortSignal) => {
+    const generation = ++loadGeneration.current;
+    try {
+      const response = await fetch(`${apiBase}/api/storage/usage-ledger-retention`, { signal });
+      if (!response.ok) throw new Error("load_failed");
+      const next = parseStatus(await response.json());
+      if (signal?.aborted || generation !== loadGeneration.current) return;
+      setError(null);
+      setStatus(next);
+      setCustomDraft(formatMaxMiBDraft(next.maxBytes));
+    } catch (errorValue) {
+      // A successful PUT invalidates reads that started under the old policy. Stale reads
+      // must be silent whether they eventually succeed, fail HTTP, reject, or parse badly.
+      if (signal?.aborted || generation !== loadGeneration.current
+        || (errorValue as { name?: string })?.name === "AbortError") return;
+      throw errorValue;
+    }
+  }, [apiBase]);
+
+  useEffect(() => {
+    const controller = new AbortController();
+    const timeout = window.setTimeout(() => {
+      void load(controller.signal).catch(errorValue => {
+        if (!controller.signal.aborted && (errorValue as { name?: string })?.name !== "AbortError") {
+          setError(t("usage.retention.error"));
+        }
+      });
+    }, 0);
+    return () => {
+      window.clearTimeout(timeout);
+      controller.abort();
+    };
+  }, [load, t]);
+
+  const persist = useCallback(async (nextEnabled: boolean, maxBytes: number) => {
+    setBusy(true);
+    setError(null);
+    try {
+      const response = await fetch(`${apiBase}/api/storage/usage-ledger-retention`, {
+        method: "PUT",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ enabled: nextEnabled, maxBytes }),
+      });
+      if (!response.ok) throw new Error("save_failed");
+      const next = parseStatus(await response.json());
+      // A GET may have started before this authoritative mutation completed (for example,
+      // after a locale change). Do not let that older snapshot repaint the saved state.
+      loadGeneration.current += 1;
+      setStatus(next);
+      setCustomDraft(formatMaxMiBDraft(next.maxBytes));
+      setEditing(false);
+    } catch {
+      setError(t("usage.retention.error"));
+    } finally {
+      setBusy(false);
+    }
+  }, [apiBase, t]);
+
+  const toggle = () => {
+    if (!status || busy) return;
+    void persist(!status.enabled, status.maxBytes);
+  };
+
+  const saveCustom = () => {
+    if (!status || busy) return;
+    // If the saved value is not MiB-aligned, leaving the field untouched must
+    // not force an unrelated rounding write; the switch path remains exact.
+    if (customDraft === formatMaxMiBDraft(status.maxBytes)) {
+      setEditing(false);
+      return;
+    }
+    const nextMaxBytes = parseMaxMiBDraft(customDraft);
+    if (nextMaxBytes === null) {
+      setError(t("usage.retention.error"));
+      return;
+    }
+    void persist(true, nextMaxBytes);
+  };
+
+  const resetCustom = () => {
+    if (!status) return;
+    setCustomDraft(formatMaxMiBDraft(status.maxBytes));
+    setEditing(false);
+    setError(null);
+  };
+
+  return (
+    <section className="usage-retention-control" data-testid="usage-ledger-retention" aria-labelledby="usage-retention-title">
+      <div className="usage-retention-heading">
+        <div>
+          <h3 id="usage-retention-title" className="h-section">{t("usage.retention.title")}</h3>
+          <p className="muted text-control">{t("usage.retention.help")}</p>
+        </div>
+        <Switch
+          on={status?.enabled === true}
+          onClick={toggle}
+          disabled={busy || status === null}
+          label={t("usage.retention.enabled")}
+        />
+      </div>
+
+      {status?.enabled && (
+        <div className="usage-retention-editor" aria-busy={busy}>
+          <label className="usage-retention-limit">
+            <span className="field-label">{t("usage.retention.limit")}</span>
+            <span
+              className="codex-auto-switch-input-wrap"
+              onBlur={event => {
+                if (event.currentTarget.contains(event.relatedTarget as Node | null)) return;
+                if ((event.relatedTarget as HTMLElement | null)?.closest("button.switch")) {
+                  setEditing(false);
+                  return;
+                }
+                if (editing) saveCustom();
+              }}
+            >
+              <input
+                ref={inputRef}
+                className="input mono codex-auto-switch-input"
+                type="number"
+                min={1}
+                max={MAX_MIB}
+                step={1}
+                inputMode="numeric"
+                value={customDraft}
+                placeholder={mibLabel}
+                disabled={busy}
+                aria-label={t("usage.retention.limit")}
+                onFocus={() => setEditing(true)}
+                onChange={event => {
+                  setError(null);
+                  setCustomDraft(event.target.value);
+                }}
+                onKeyDown={event => {
+                  if (event.nativeEvent.isComposing || busy) return;
+                  if (event.key === "Enter") {
+                    event.preventDefault();
+                    saveCustom();
+                  } else if (event.key === "Escape") {
+                    event.preventDefault();
+                    resetCustom();
+                  }
+                }}
+              />
+              <span className="codex-auto-switch-unit" aria-hidden="true">{mibLabel}</span>
+              <NumberStepper
+                disabled={busy}
+                incrementLabel={t("usage.retention.increase")}
+                decrementLabel={t("usage.retention.decrease")}
+                onIncrement={() => {
+                  inputRef.current?.focus();
+                  setEditing(true);
+                  setCustomDraft(clampNumberDraft(customDraft, 1, 1, MAX_MIB));
+                }}
+                onDecrement={() => {
+                  inputRef.current?.focus();
+                  setEditing(true);
+                  setCustomDraft(clampNumberDraft(customDraft, -1, 1, MAX_MIB));
+                }}
+              />
+            </span>
+          </label>
+        </div>
+      )}
+
+      <p className="muted text-caption usage-retention-current">
+        {t("usage.retention.current")}: {status?.currentBytes === undefined ? "—" : formatBytes(status.currentBytes, locale)}
+        {status && (
+          <>
+            {" · "}
+            {!status.enabled && <><span className="usage-retention-state">{t("usage.retention.unlimited")}</span>{" · "}</>}
+            <span className={`usage-retention-limit${status.enabled ? "" : " is-disabled"}`}>
+              {t("usage.retention.limit")}: {formatBytes(status.maxBytes, locale)}
+            </span>
+          </>
+        )}
+      </p>
+      {error && <p className="err" role="alert">{error}</p>}
+    </section>
+  );
+}