feat(memory): enforce an app-owned retained-state byte budget

One process-wide budget now sits over every evictable retained store —
diagnostic rings, caches, Cursor blobs, and continuation state — demoting
oldest entries in a fixed category order and reporting the whole picture
as a privacy-safe appOwnedBytes block on the system memory endpoint. The
budget is a user-visible setting on /api/settings (256 MiB default),
documented across all five locales as a cap on app-owned state, not RSS.
Three defects found by external review land as pre-work: the snapshot
writer's unbounded retry is capped with stable-only spill unlinking, the
RAM-cap loop demotes residents before touching older spill stubs, and the
GCP ADC expiry sweep finally joins the periodic registration table. The
usage-log entry-cap test also gains the store budget windows-latest
measured it needing.

Author: lidge-jun

devlog/_plan/260801_zero_leak_state_stores/040_app_bytes_observability.md

@@ -59,6 +59,7 @@ namespaced selected id を bare id に変えます。
 | `accountPoolStickyLimit?` | `number` | `1` | 1 回の round-robin 選択で次へ進む前に保持する成功的新セッション bind 数。範囲 1–100。`accountPoolStrategy` が `round-robin` のときのみ。 |
 | `upstreamFailoverThreshold?` | `number` | `3` | 一時的な上流失敗が連続して起きたのち、以降の新しいセッションを別の適合 pool アカウントに failover する回数。`0` なら失敗ベースの failover をオフにします。 |
 | `modelCacheTtlMs?` | `number` | `300000` | プロバイダー別 `/models` キャッシュの有効期間（5 分）。 |
+| `appOwnedMemoryBudgetMb?` | `number` | `256` | 退避可能なアプリ所有の保持状態（ログ、キャッシュ、Blob、継続応答ペイロード）に対するプロセス全体の上限（MiB）です。有効範囲は 64〜4096 で、RSS やネイティブランタイムメモリの上限ではありません。 |
 | `cacheRetention?` | `"none" \| "short" \| "long"` | `"short"` | Anthropic prompt cache ポリシー。オフ、5 分 ephemeral、1 時間 extended のいずれか。 |
 | `webSearchSidecar?` | `OcxWebSearchSidecarConfig` | on | ウェブ検索サイドカーオプション（下記参照）。 |
 | `visionSidecar?` | `OcxVisionSidecarConfig` | on | ビジョンサイドカーオプション（下記参照）。 |

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

@@ -60,6 +60,7 @@ namespaced selected id를 bare id로 바꿉니다.
 | `accountPoolStickyLimit?` | `number` | `1` | 한 round-robin 선택이 다음으로 넘어가기 전에 유지하는 성공적 새 세션 bind 수. 범위 1–100. `accountPoolStrategy`가 `round-robin`일 때만 적용. |
 | `upstreamFailoverThreshold?` | `number` | `3` | 일시적인 업스트림 실패가 연속으로 발생한 뒤, 이후 새 세션을 다른 적합한 pool 계정으로 failover할 횟수. `0`이면 실패 기반 failover를 끕니다. |
 | `modelCacheTtlMs?` | `number` | `300000` | 프로바이더별 `/models` 캐시의 유효 기간(5분). |
+| `appOwnedMemoryBudgetMb?` | `number` | `256` | 제거 가능한 앱 소유 유지 상태(로그, 캐시, Blob, 연속 응답 페이로드)의 프로세스 전체 상한(MiB)입니다. 유효 범위는 64~4096이며 RSS나 네이티브 런타임 메모리 상한이 아닙니다. |
 | `cacheRetention?` | `"none" \| "short" \| "long"` | `"short"` | Anthropic prompt cache 정책. 끔, 5분 ephemeral, 1시간 extended 중 하나입니다. |
 | `webSearchSidecar?` | `OcxWebSearchSidecarConfig` | on | 웹 검색 사이드카 옵션(아래 참조). |
 | `visionSidecar?` | `OcxVisionSidecarConfig` | on | 비전 사이드카 옵션(아래 참조). |

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

@@ -65,6 +65,7 @@ differing backup and rewrites known legacy namespaced selected ids to bare ids.
 | `accountPoolStickyLimit?` | `number` | `1` | Successful new-session binds retained on one round-robin selection before advancing. Range 1–100; only applies when `accountPoolStrategy` is `round-robin`. |
 | `upstreamFailoverThreshold?` | `number` | `3` | Consecutive transient upstream failures before future new sessions fail over to another eligible pool account. Set `0` to disable failure failover. |
 | `modelCacheTtlMs?` | `number` | `300000` | Freshness window for the per-provider `/models` cache (5 min). |
+| `appOwnedMemoryBudgetMb?` | `number` | `256` | Process-wide cap in MiB for evictable app-owned retained state (logs, caches, blobs, and continuation payloads), valid from 64 to 4096. This does not cap RSS or native runtime memory. |
 | `cacheRetention?` | `"none" \| "short" \| "long"` | `"short"` | Anthropic prompt-cache policy: disabled, 5-minute ephemeral, or 1-hour extended. |
 | `webSearchSidecar?` | `OcxWebSearchSidecarConfig` | on | Web-search sidecar options (see below). |
 | `visionSidecar?` | `OcxVisionSidecarConfig` | on | Vision sidecar options (see below). |

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

@@ -64,6 +64,7 @@ opencodex настраивается файлом `~/.opencodex/config.json`. Е
 | `accountPoolStickyLimit?` | `number` | `1` | Число успешных привязок новых сессий, удерживаемых на одном выборе round-robin перед переходом дальше. Диапазон 1–100; только при `accountPoolStrategy` = `round-robin`. |
 | `upstreamFailoverThreshold?` | `number` | `3` | Число подряд идущих временных сбоев вышестоящей стороны, после которого будущие новые сессии переключаются (failover) на другой подходящий аккаунт пула. Установите `0`, чтобы отключить переключение по сбоям. |
 | `modelCacheTtlMs?` | `number` | `300000` | Окно свежести кэша `/models` каждого провайдера (5 минут). |
+| `appOwnedMemoryBudgetMb?` | `number` | `256` | Общий для процесса лимит в МиБ для вытесняемого удерживаемого состояния приложения (журналы, кэши, BLOB-данные и данные продолжения), допустимый диапазон — 64–4096. Это не лимит RSS или нативной памяти среды выполнения. |
 | `cacheRetention?` | `"none" \| "short" \| "long"` | `"short"` | Политика кэша промптов Anthropic: отключён, эфемерный на 5 минут или расширенный на 1 час. |
 | `webSearchSidecar?` | `OcxWebSearchSidecarConfig` | вкл. | Параметры сайдкара веб-поиска (см. ниже). |
 | `visionSidecar?` | `OcxVisionSidecarConfig` | вкл. | Параметры vision-сайдкара (см. ниже). |

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

@@ -58,6 +58,7 @@ no-replace 方式创建 `config.json.pre-openai-tiers-v2.bak`，并把已知旧
 | `accountPoolStickyLimit?` | `number` | `1` | 一次 round-robin 选择在推进前保留的成功新 session 绑定数。范围 1–100；仅当 `accountPoolStrategy` 为 `round-robin` 时生效。 |
 | `upstreamFailoverThreshold?` | `number` | `3` | 连续发生多少次临时上游失败后，让后续新 session failover 到其他合格 pool account。设为 `0` 可禁用失败切换。 |
 | `modelCacheTtlMs?` | `number` | `300000` | 每个 provider 的 `/models` 缓存新鲜度窗口（5 分钟）。 |
+| `appOwnedMemoryBudgetMb?` | `number` | `256` | 进程级可驱逐应用保留状态（日志、缓存、Blob 和续接响应负载）上限，单位为 MiB，有效范围为 64–4096。它不是 RSS 或原生运行时内存上限。 |
 | `cacheRetention?` | `"none" \| "short" \| "long"` | `"short"` | Anthropic prompt-cache 策略：禁用、5 分钟 ephemeral 或 1 小时 extended。 |
 | `webSearchSidecar?` | `OcxWebSearchSidecarConfig` | 开启 | 网络搜索 sidecar 选项（见下文）。 |
 | `visionSidecar?` | `OcxVisionSidecarConfig` | 开启 | 视觉 sidecar 选项（见下文）。 |

docs-site/src/content/docs/zh-cn/reference/configuration.md

@@ -20,6 +20,7 @@ import {
   TOTAL_IMAGE_BASE64_BUDGET,
   type ImageBlockRef,
 } from "./anthropic-image-guard";
+import { enforceAppOwnedMemoryBudget } from "../lib/app-owned-memory";
 
 /** One ladder position: dimension cap, JPEG quality attempts, per-image base64 cap. */
 export interface TierSpec {
@@ -168,6 +169,7 @@ function cachePut(key: string, value: CacheValue): boolean {
   cacheBytes += next.sizeBytes;
   cacheMetadataBytes += next.metadataBytes;
   if (typeof value === "string") cacheSentinelEntries++;
+  enforceAppOwnedMemoryBudget();
   return true;
 }
 

src/adapters/anthropic-image-normalize.ts

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { enforceAppOwnedMemoryBudget } from "../../lib/app-owned-memory";
 import { create } from "@bufbuild/protobuf";
 import {
   DiagnosticsErrorSchema,
@@ -166,6 +167,11 @@ function recomputeBlobClassAccounting(): void {
   scheduleBlobExpiryAccounting(now);
 }
 
+function reconcileBlobClassAccountingAndEnforce(): void {
+  recomputeBlobClassAccounting();
+  enforceAppOwnedMemoryBudget();
+}
+
 function scheduleBlobExpiryAccounting(now: number): void {
   if (blobExpiryAccountingTimer) clearTimeout(blobExpiryAccountingTimer);
   blobExpiryAccountingTimer = undefined;
@@ -178,7 +184,7 @@ function scheduleBlobExpiryAccounting(now: number): void {
   if (!Number.isFinite(nextExpiry)) return;
   blobExpiryAccountingTimer = setTimeout(() => {
     blobExpiryAccountingTimer = undefined;
-    recomputeBlobClassAccounting();
+    reconcileBlobClassAccountingAndEnforce();
   }, Math.max(0, nextExpiry - now));
   blobExpiryAccountingTimer.unref?.();
 }
@@ -205,7 +211,7 @@ function releaseHydratedBlob(k: string, requestScope?: CursorBlobRequestScopeTok
     state?.keys.delete(k);
     if (state?.sealed && state.keys.size === 0) blobRequestScopes.delete(scope);
   }
-  if (changed) recomputeBlobClassAccounting();
+  if (changed) reconcileBlobClassAccountingAndEnforce();
 }
 
 function setBlob(
@@ -306,7 +312,7 @@ function setBlob(
   blobs.set(k, entry);
   blobBytes += entry.sizeBytes;
   for (const scope of entry.requestPins) blobRequestScopes.get(scope)?.keys.add(k);
-  recomputeBlobClassAccounting();
+  reconcileBlobClassAccountingAndEnforce();
   return { admitted: true, replaced: existing !== undefined };
 }
 
@@ -361,7 +367,7 @@ export function releaseCursorBlobRequestScope(scope: CursorBlobRequestScopeToken
   if (!state) return;
   for (const k of state.keys) blobs.get(k)?.requestPins.delete(scope);
   blobRequestScopes.delete(scope);
-  recomputeBlobClassAccounting();
+  reconcileBlobClassAccountingAndEnforce();
 }
 
 export function storeCursorBlob(data: Uint8Array, requestScope?: CursorBlobRequestScopeToken): Uint8Array {

src/adapters/cursor/native-exec.ts

@@ -1,3 +1,5 @@
+import { enforceAppOwnedMemoryBudget } from "../lib/app-owned-memory";
+
 /**
  * Antigravity (Cloud Code Assist) thoughtSignature reasoning-replay cache.
  *
@@ -21,6 +23,7 @@ interface ReplayEntry {
   byCall: Map<string, ReplayCall>;
   bytes: number;
   expiresAtMs: number;
+  oldestAtMs: number | null;
 }
 
 const MIN_SIGNATURE_LEN = 16;
@@ -47,6 +50,8 @@ const replayCache = new Map<string, ReplayEntry>();
 const utf8 = new TextEncoder();
 let replayLimits = { ...DEFAULT_REPLAY_LIMITS };
 let replayBytes = 0;
+let replayOldestSessionKey: string | undefined;
+let replayOldestAt: number | null = null;
 
 function replayKey(model: string, sessionId: string): string {
   return `${model}::session:${sessionId}`;
@@ -87,9 +92,32 @@ function deleteReplaySession(key: string): number {
   if (!entry) return 0;
   replayCache.delete(key);
   replayBytes -= entry.bytes;
+  if (replayOldestSessionKey === key) recomputeReplayOldestCandidate();
   return entry.bytes;
 }
 
+function recomputeReplayOldestCandidate(): void {
+  replayOldestSessionKey = undefined;
+  replayOldestAt = null;
+  for (const [key, entry] of replayCache) {
+    if (entry.oldestAtMs === null || (replayOldestAt !== null && entry.oldestAtMs >= replayOldestAt)) continue;
+    replayOldestSessionKey = key;
+    replayOldestAt = entry.oldestAtMs;
+  }
+}
+
+function refreshReplaySessionCandidate(key: string, entry: ReplayEntry): void {
+  entry.oldestAtMs = entry.byCall.values().next().value?.touchedAtMs ?? null;
+  if (replayOldestSessionKey === key) {
+    recomputeReplayOldestCandidate();
+    return;
+  }
+  if (entry.oldestAtMs !== null && (replayOldestAt === null || entry.oldestAtMs < replayOldestAt)) {
+    replayOldestSessionKey = key;
+    replayOldestAt = entry.oldestAtMs;
+  }
+}
+
 function deleteExpiredReplaySessions(now: number): void {
   for (const [key, entry] of replayCache) if (entry.expiresAtMs <= now) deleteReplaySession(key);
 }
@@ -138,7 +166,12 @@ export function observeAntigravityReplay(model: string, sessionId: string, parts
   const now = Date.now();
   deleteExpiredReplaySessions(now);
   const key = replayKey(model, sessionId);
-  const entry = replayCache.get(key) ?? { byCall: new Map<string, ReplayCall>(), bytes: 0, expiresAtMs: 0 };
+  const entry = replayCache.get(key) ?? {
+    byCall: new Map<string, ReplayCall>(),
+    bytes: 0,
+    expiresAtMs: 0,
+    oldestAtMs: null,
+  };
   let inserted = false;
   for (const raw of parts) {
     if (!raw || typeof raw !== "object") continue;
@@ -161,7 +194,9 @@ export function observeAntigravityReplay(model: string, sessionId: string, parts
   evictInnerCalls(entry);
   entry.expiresAtMs = now + REPLAY_TTL_MS;
   replayCache.set(key, entry);
+  refreshReplaySessionCandidate(key, entry);
   evictIfNeeded();
+  enforceAppOwnedMemoryBudget();
 }
 
 /**
@@ -177,6 +212,7 @@ export function applyAntigravityReplay(model: string, sessionId: string, content
   if (!entry) {
     return contents;
   }
+  let touched = false;
   for (const c of contents as { role?: string; parts?: unknown[] }[]) {
     if (!c || typeof c !== "object" || c.role !== "model" || !Array.isArray(c.parts)) continue;
     for (const raw of c.parts) {
@@ -191,9 +227,11 @@ export function applyAntigravityReplay(model: string, sessionId: string, content
         part.thoughtSignature = call.signature;
         entry.byCall.delete(ck);
         entry.byCall.set(ck, { ...call, touchedAtMs: now });
+        touched = true;
       }
     }
   }
+  if (touched) refreshReplaySessionCandidate(replayKey(model, sessionId), entry);
   return contents;
 }
 
@@ -224,27 +262,17 @@ export function antigravityReplayRetainedStoreSnapshot(): {
   pinnedBytes: number;
   oldestAt: number | null;
 } {
-  let oldestAt: number | null = null;
-  for (const entry of replayCache.values()) {
-    for (const call of entry.byCall.values()) {
-      oldestAt = oldestAt === null ? call.touchedAtMs : Math.min(oldestAt, call.touchedAtMs);
-    }
-  }
-  return { count: replayCache.size, bytes: replayBytes, evictableBytes: replayBytes, pinnedBytes: 0, oldestAt };
+  return {
+    count: replayCache.size,
+    bytes: replayBytes,
+    evictableBytes: replayBytes,
+    pinnedBytes: 0,
+    oldestAt: replayOldestAt,
+  };
 }
 
 export function evictOldestAntigravityReplayForBudget(): number {
-  let oldestKey: string | undefined;
-  let oldestAt = Number.POSITIVE_INFINITY;
-  for (const [key, entry] of replayCache) {
-    let sessionOldest = entry.expiresAtMs;
-    for (const call of entry.byCall.values()) sessionOldest = Math.min(sessionOldest, call.touchedAtMs);
-    if (sessionOldest < oldestAt) {
-      oldestAt = sessionOldest;
-      oldestKey = key;
-    }
-  }
-  return oldestKey === undefined ? 0 : deleteReplaySession(oldestKey);
+  return replayOldestSessionKey === undefined ? 0 : deleteReplaySession(replayOldestSessionKey);
 }
 
 export function setAntigravityReplayLimitsForTests(limits?: Partial<ReplayLimits>): void {
@@ -256,4 +284,6 @@ export function setAntigravityReplayLimitsForTests(limits?: Partial<ReplayLimits
 export function __resetAntigravityReplayCache(): void {
   replayCache.clear();
   replayBytes = 0;
+  replayOldestSessionKey = undefined;
+  replayOldestAt = null;
 }

src/adapters/google-antigravity-replay.ts

@@ -15,6 +15,7 @@
 import { createHmac, randomBytes } from "node:crypto";
 import { isClaudeDebugEnabled } from "../lib/debug-settings";
 import { retainedUtf8Bytes, truncateRetainedUtf8 } from "../lib/admission";
+import { enforceAppOwnedMemoryBudget } from "../lib/app-owned-memory";
 
 export interface ClaudeInboundDebugEntry {
   /** Monotonic capture id — unique even when several entries share Date.now(). */
@@ -138,6 +139,7 @@ export function captureClaudeInbound(
   ring.push(entry);
   ringBytes += entryBytes(entry);
   if (ring.length > RING_LIMIT) removeOldest();
+  enforceAppOwnedMemoryBudget();
 }
 
 /** Newest-first snapshot for /api/claude/inbound-debug. */