docs: distill sidecar memory trimming

Author: linhay

.agents/skills/gettokens-domain-engineering/SKILL.md

@@ -145,6 +145,9 @@ This skill unifies the technical rules for building, styling, and debugging GetT
   - Account resource surfaces inside live-session details should reuse accounts-domain components such as `QuotaBars` and `BillingBalance`. Add a small adapter from live request `quota` / `billing` DTOs into account display shapes instead of copying quota or balance JSX into live sessions.
   - Never display raw request/response payloads, credentials, bearer tokens, cookies, or unredacted error bodies. Diagnostic copy must be redacted and bounded.
   - When correlating WebSocket and HTTP usage, preserve request ids through context. Usage hooks should update an existing WebSocket request when the request id is known, not create a duplicate HTTP-only session.
+  - When trimming live-session memory, distinguish realtime snapshot retention from historical retention. The in-memory tracker may cap session/request maps for RSS control, but historical request data must be written to a disk-backed ledger before it can be trimmed from memory.
+  - Snapshot cleanup endpoints such as `DELETE /v0/management/gettokens/live-sessions` clear only realtime memory state by default. Disk history cleanup requires a separately scoped API with explicit filters/retention semantics; do not reuse memory prune to delete history.
+  - Live-session history endpoints should be paginated from disk (`limit / offset / window / session_id`) and must not rebuild the old unbounded in-memory details list.
   - Treat Codex upstream HTTP fallback as an observable sticky state. GetTokens may infer and explain the fallback, but must not promise transparent recovery to WebSocket after Codex has already downgraded.
   - The frontend must support browser preview with mock snapshots, while desktop mode polls the real Wails snapshot. Show source state such as `live`, `cache`, or `preview` so stale sidecar state is not mistaken for no sessions.
   - Request timing trend charts must be driven by request records, not decorative UI state. Put trend derivation in a pure model under `features/codex-live-sessions/model/`, merge the active request by `requestID`, sort points by `startedAt`, and accept an explicit `nowMs` option so live requests can be projected in tests.

docs-linhay/dev/20260519-cliproxyapi-upstream-sync-session-distillation.md

@@ -106,3 +106,45 @@ git check-ignore -v <path>
 4. `git -C docs-linhay/references/CLIProxyAPI diff --check`
 
 本地 sidecar 已通过 `./scripts/ensure-sidecar.sh darwin arm64` 重建，`build/bin/cli-proxy-api.meta.json` 记录 `commit=1c5db246`、`dirty=clean`、`goos=darwin`、`goarch=arm64`。
+
+## 2026-05-26 同步记录
+
+本轮将 `docs-linhay/references/CLIProxyAPI#gettokens/sidecar` 从 `upstream/main@50d19e20` 之后的最新上游合并到维护分支，生成 merge commit `b72ac277` 并推送到 `AxApp/CLIProxyAPI#gettokens/sidecar`。
+
+上游新增内容包括 Codex model fetch 命令、request logging 文件落盘、home request logging request id、auth file websocket 字段解析与 patch。合并前本地维护分支已有未推送补丁 `b8754677`，本轮保留该补丁并一并推送。
+
+冲突处理：
+
+1. `sdk/api/handlers/openai/openai_responses_websocket.go` 与上游 file-backed websocket timeline 变更冲突；合并时保留上游 `websocketTimelineLog` / `FileBodySource` 结构。
+2. 同一文件保留 GetTokens live-session hook、`RecordDownstreamWebsocketConnected/Disconnected/Request`、request id 注入、pinned auth retry/failover 与 wrapped status code 提取。
+3. websocket capability 继续走 fork 侧 `coreauth.AuthAllowsWebsockets(auth)`，避免上游仅检查显式 `metadata/attributes.websockets` 后收窄 Codex API key 默认 websocket 路由能力。
+
+验证：
+
+1. `go test ./sdk/api/handlers/openai`
+2. `go test ./internal/api/handlers/management ./internal/api/middleware ./internal/logging ./internal/runtime/executor ./sdk/api/handlers/openai`
+3. `go test ./...`
+4. `git diff --check`
+
+本地 sidecar 已通过 `./scripts/ensure-sidecar.sh darwin arm64` 重建，`build/bin/cli-proxy-api.meta.json` 记录 `commit=b72ac277`、`dirty=clean`、`goos=darwin`、`goarch=arm64`。该 meta 文件和二进制当前未被父仓库 git 跟踪，父仓库可见变更为 CLIProxyAPI gitlink 前进到 `b72ac277`。
+
+## 2026-05-26 内存剪裁记录
+
+本轮针对 sidecar RSS 偏高做了三类剪裁：
+
+1. live sessions tracker 仍然保留最近 30 分钟窗口，但每个 session 只保留最近 50 条 request，并新增 `DELETE /v0/management/gettokens/live-sessions` 清理接口；`requestMap` 也跟着回收，避免单个长会话和索引一起无限增长。被内存裁掉的 request 会以完整 `LiveRequest` JSON 落到 `live-sessions-v1.sqlite`，并通过 `GET /v0/management/gettokens/live-sessions/history` 分页追溯；清理实时 snapshot 不删除磁盘历史。
+2. legacy `internal/usage/logger_plugin.go` 不再把 request details 长驻内存，`Snapshot()` 只保留聚合字段；细粒度数据继续通过磁盘分页接口追溯，避免 12.8 万条 detail 常驻堆上。
+3. legacy usage snapshot 文件切到 `usage-observed-v2.sqlite`，聚合快照继续落盘；首次启动若 v2 无数据但 `usage-observed-v1.sqlite` 存在，会读取 v1 聚合并回写 v2，避免升级后历史聚合归零。历史明细通过 `GET /v0/management/gettokens/usage-attribution/details` 继续追溯，不再依赖一次性回灌旧的巨大 payload JSON。
+
+新增的磁盘读取接口包括：
+
+1. `GET /v0/management/gettokens/live-sessions/history`：支持 `window / limit / offset / session_id`，用于追溯已被实时内存窗口裁掉的 live request。
+2. `GET /v0/management/gettokens/usage-attribution/details`：支持 `window / limit / offset / account_key / attribution_key`，用于后续前端按页拉取明细而不是一次性把整坨数据抬进内存。
+
+验证：
+
+1. `go test ./internal/gettokenshooks ./internal/usage ./internal/cmd`
+2. `go test ./...`
+3. `git diff --check`
+
+当前侧边车相关内存剪裁仍是可继续迭代的方向，后续若前端真要消费分页明细，再补对应 UI 和调用层。

docs-linhay/memory/2026-05-26.md

@@ -1,5 +1,10 @@
 # 2026-05-26
 
+## Codex Channel Routing 兼容遮罩收口
+- 决策：Codex 账号列表里的 `session-affinity`、`websocket-pin`、`route-order-header` 不再回写新 `ChannelRoutingConfig`；前端只展示为 `Legacy compatibility mask`，并在 explain 中记录 `legacy:compatibility-mask=blocked`，以便后续和上游合并时保持最小改动面。
+- 验证：`npm --prefix frontend run typecheck`、`npm --prefix frontend run test:unit -- src/features/channel-routing/tests/channelRouting.test.mjs`、`npm --prefix frontend run test:unit -- src/features/codex/codexAccountList.test.mjs` 通过；浏览器 dev 预览在 `http://127.0.0.1:5173/#frame=codex&workspace=account-list` 可见兼容遮罩区块与三条信号说明。
+- 边界：这次只收口 Codex Channel Routing 的前端语意和 preview/explain 文案，不改上游核心路由实现，也不扩大到 AGENTS 级别规则。
+
 ## Codex live sessions 时间线首 token 补齐
 - 决策：`#frame=codex&workspace=live-sessions` 的请求时间线行补出 `firstTokenLabel`，和 `总 / TTFT` 并排显示；次级的 `stream` 指标继续保留但会在更窄断点隐藏，避免紧凑行过满。
 - 补充：线上版也需要稳定显示 `总 / TTFT / 首` 三个指标，因此前三个指标不再受 `sm` 断点隐藏影响；只有第 4 个 `stream` 仍作为宽屏次级指标。
@@ -93,9 +98,12 @@
 
 ## CLIProxyAPI 内存剪裁
 - 决策：live sessions tracker 只保留最近 50 条 request，保留 30 分钟窗口但增加 `DELETE /v0/management/gettokens/live-sessions` 清理接口，避免单个长会话无限堆 request。
-- 决策：legacy `internal/usage/logger_plugin.go` 不再把 request detail 长驻内存，改为聚合常驻、明细落盘分页读取；`usage-observed` 迁移到 `usage-observed-v2.sqlite`，不再回灌旧的大 JSON payload。
+- 决策：live sessions 的历史 request 另外落到 `live-sessions-v1.sqlite`，通过 `GET /v0/management/gettokens/live-sessions/history` 分页追溯；清理实时 snapshot 不删除磁盘历史。
+- 决策：legacy `internal/usage/logger_plugin.go` 不再把 request detail 长驻内存，改为聚合常驻、明细落盘分页读取；`usage-observed` 迁移到 `usage-observed-v2.sqlite`，首次启动若只剩 v1 会自动回写 v2。
 - 新增：usage attribution 增加 `GET /v0/management/gettokens/usage-attribution/details`，支持 `window / limit / offset / account_key / attribution_key`，给后续前端或调试页按页取明细。
-- 验证：`go test ./internal/usage ./internal/gettokenshooks` 通过；这轮剪裁是为了降低 sidecar RSS，不是前端展示优化，因此没有改前端 dev server 的职责边界。
+- 纠正：这轮调整的边界只是在内存里裁剪 live sessions / requestMap 和 usage detail 常驻量，磁盘上的历史仍要保留完整可追溯数据，不能把落盘内容也裁短。
+- 沉淀：已更新 `.agents/skills/gettokens-domain-engineering/SKILL.md` 的 Codex Live Sessions 小节，新增“内存裁剪必须先定义磁盘历史归属、snapshot 清理不删除历史、历史接口从磁盘分页读取”的规则；该规则属于 CLIProxyAPI fork / Codex runtime observability 领域边界，不升级 `AGENTS.md`。
+- 验证：`go test ./internal/gettokenshooks ./internal/usage ./internal/cmd`、`go test ./...`、`git diff --check` 通过；这轮剪裁是为了降低 sidecar RSS，不是前端展示优化，因此没有改前端 dev server 的职责边界。
 
 ## Codex live sessions 请求趋势整理
 - 沉淀：请求耗时趋势图只允许当前 active request 使用 `nowMs - startedAt` 投影；历史请求保留记录值或完成时间差，避免 stale `streaming/reconnecting` 样本一起增长。

docs-linhay/references/CLIProxyAPI

@@ -1 +1 @@
-Subproject commit b8754677fd33b07586752283f0a268303ae4a431
+Subproject commit 8ea4d93c8b83979c19ed91beceaf65742419f233