Skip to content

feat: session-file GC — sweep stale small state files (#1082) - #1084

Merged
ranxianglei merged 1 commit into
masterfrom
2026-09-21_session-file-gc
Sep 23, 2026
Merged

ranxianglei merged 1 commit into
masterfrom
2026-09-21_session-file-gc

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Closes #1082

What & why

Short-lived sessions leave small state files under the sessions dir that are never resumed. The kernel StateStore never deletes files, so they accumulate forever. This adds a conservative disk sweep plus a per-turn rebuild-cost signal.

Design (as settled in-thread with owner):

  • Every turn records metadata.rawInputTokens — token estimate of the raw wire payload as received (text-only; binary fields excluded by estimateRawBodyTokens). Latest wins: history grows monotonically and shrinks after native-compaction boundaries, which is exactly when re-sending gets cheaper. No acp-kernel bump needed (metadata is bili's free-form bag).
  • Sweep deletes a file only when both hold:
    1. age > BILI_SESSION_GC_MAX_AGE_DAYS (default 7d, judged on decoded savedAt);
    2. size gate ≤ BILI_SESSION_GC_MAX_TOKENS (default 1M, owner-set): rawInputTokens when recorded, else no active compression blocks AND contextTokens ≤ threshold (a file with live blocks can read small yet carry huge raw history — deleting it would overflow the window on resume).
  • Runs at boot + every BILI_SESSION_GC_INTERVAL_MS (default 1h); kill switch BILI_SESSION_GC=0; gated on persistence being enabled.

Safety rails:

  • mtime pre-filter — only age-eligible files are decoded;
  • corrupt/unreadable files are left in place (logged, never guessed at);
  • encrypted BILIENC1 files are decoded through the store's codec before judging (new SessionStore.readRawFile, codec-aware path-keyed twin of the id-keyed loaders);
  • resident guard: a file whose session is still in memory is skipped unless it has been idle since its last disk write (no in-flight request, no pending debounced save, lastSeen not newer than savedAt) — then it is dropped from the map via new dropSessionForGc() so the writer cannot resurrect the file;
  • walks the disk tree, not the in-memory map (LRU-evicted/capped sessions leave files only a walk sees);
  • emptied protocol subdirectories removed; one summary log line per non-empty sweep ([gc] removed N … freed X KB).

Files

  • src/session-gc.ts (new) — config, file-view parsing (v3 envelope + legacy flat, grouped-then-flat fallbacks mirroring persist.ts readers), eligibility predicate, sweep
  • src/persist.ts — SessionStore.readRawFile(file)
  • src/server.ts — per-turn rawInputTokens recording (after activePack), boot sweep + unref'd interval
  • src/session.ts — dropSessionForGc(id)
  • tests/session-gc.test.ts (new) — 10 tests: eligibility matrix, view parsing, env config, sweep keep/delete/corrupt/encrypted/resident/pending cases, and an end-to-end recording→persistence round-trip through a real proxy+upstream
  • docs: CONFIGURATION.md / .zh-CN.md env rows, README.md / .zh-CN.md sections

Pre-flight

  • npm run typecheck ✅ · full npm test: 2092 pass / 0 fail (2 pre-existing skips) ✅ · npm run build ✅
  • New tests: 10/10 ✅
  • E2E preflight (E2E_CHECK=1, codex binary + dist + upstream probe) ✅. Full 4-phase E2E could not be completed in this environment: warmup fails identically on clean master with changes stashed (warmup exit=1, empty output) — pre-existing sandbox/upstream issue, not this change. CI's manual-dispatch e2e workflow can cover it.
  • No version bump, no wire-protocol change, no acp-kernel pin change; both compression modes unaffected (recording is format-agnostic, GC touches only the persistence layer).

@github-actions

github-actions Bot commented Sep 21, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-09-21_session-file-gc (9e503f4)

Option A — Install from npm PR tag (recommended)

npm install -g billion-context@pr-1084

Each push to this PR publishes a new version under the pr-1084 npm tag.

Option B — Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr1084.tgz
npm install -g package

Install instructions are refreshed on each push.

@ranxianglei
ranxianglei force-pushed the 2026-09-21_session-file-gc branch from bd05c48 to d05c26e Compare September 21, 2026 10:13
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

Review of #1084 (session-file GC) — rebased onto current master, all gates green.

The PR base had gone stale (master moved to v0.1.133 / 7cec6d2). I rebased the branch onto live master — no conflicts — and re-ran the full gate on the rebased head d05c26e:

  • npm run typecheck ✅
  • npm run build ✅
  • full npm test: 2180 pass / 0 fail / 2 pre-existing skips ✅ (count is higher than the PR's 2092 because master gained tests since)
  • Branch force-pushed (lease-checked, old head bd05c48 unchanged before push); PR is now mergeable: true, CI running on the new head.

Diff cleanliness: single commit, 9 files, +614/−1, every line related to the feature. No lock-file churn, no version bump, no acp-kernel pin change, no wire-protocol change.

Design fidelity (verified against the settled thread in #1082):

  • Per-turn metadata.rawInputTokens stamped at src/server.ts:1467 (right beside the feat(compress): promptPack — kernel pack resolution wired through all three wire paths #730 activePack audit stamp), format-agnostic (raw parsed body, both wire shapes, both compression modes — recording happens before any mode-specific processing). It persists through the existing metadata-bag serialization (src/persist.ts:599) — proven by the e2e round-trip test.
  • Two-condition eligibility exactly as agreed: age > BILI_SESSION_GC_MAX_AGE_DAYS (7d, decoded savedAt) AND size ≤ BILI_SESSION_GC_MAX_TOKENS (1M); legacy fallback requires no active blocks AND contextTokens ≤ threshold. Conservative biases throughout: missing active counts as active (keep), missing savedAt = unreadable (keep), token estimate overcounts (keep).
  • All safety rails present: mtime pre-filter, corrupt files left in place, BILIENC1 decoded via the store codec (SessionStore.readRawFile), resident guard (inFlight / pending debounced save / lastSeen vs savedAt) + dropSessionForGc() so the writer can't resurrect, disk-tree walk (sees LRU-evicted sessions), emptied subdir removal, one summary log line per non-empty sweep, kill switch + persistence gate, unref'd timer.
  • Tests (10): eligibility matrix, view parsing, env config incl. invalid-value fallback, sweep keep/delete/corrupt/encrypted/resident/pending cases, and a real proxy+upstream integration proving record→persist round-trip.
  • Docs zh/en in sync (CONFIGURATION env rows + README sections both languages).

Minor findings (non-blocking, reporting per review discipline):

  1. intEnv treats ≤ 0 as invalid and falls back to default, so BILI_SESSION_GC_MAX_TOKENS=0 cannot express "keep everything" (it silently becomes 1M). The kill switch covers full disable, so this is cosmetic.
  2. Dual-instance residual (ACP_PASSTHROUGH 一键静默关死全部压缩:无日志/无横幅/面板不可见且不可清除,同族 env 旋钮全部生效于无声 #405 config, two proxies sharing BILI_SESSIONS_DIR): instance A could delete a file whose session is still resident in instance B. Worst case is one cold rebuild (B holds state in memory and rewrites the file on its next save); no corruption possible. Acceptable given the file must be ≥7 days stale by savedAt.
  3. Full 4-phase codex E2E not runnable in this sandbox (warmup fails identically on clean master — pre-existing); CI's zero-token codex job runs on this head and will cover the pipeline.

Verdict: implementation matches the agreed design, rails are conservative, evidence is green on the rebased head. This is a feat: (new capability surface), so per §7.4 it's outside auto-merge scope regardless — ready for you to merge: #1084

已将分支 rebase 到当前 master(v0.1.133)并全量复验(typecheck/build/2180 项测试全绿),实现与 #1082 讨论确定的设计一致、diff 干净,可以合并。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

CI caught one thing — fixed directly on the branch (commit 147fcab).

The test jobs (ubuntu+windows × node 22/24) failed with 6 errors, all in tests/session-gc.test.ts:

ENOENT: no such file or directory, mkdtemp '/home/runner/work/billion-context/billion-context/.tmp/bili-gc-sweep-XXXXXX'

Root cause: the new tmpDir() helper falls back to path.join(process.cwd(), ".tmp") when TMPDIR is unset — and GitHub runners have neither TMPDIR nor a .tmp/ dir in the checkout. mkdtempSync only creates the final component, not parent dirs → ENOENT. It passed in my sandbox only because this environment exports TMPDIR. Feature code was never implicated — the 4 pure unit tests (eligibility/view/config) passed on CI too.

Fix: tmpDir() now uses os.tmpdir(), the convention every other test file in this repo already uses (absorb, auto-restart, ca-combined, …). Test-only change, 2 lines, zero dist impact.

Re-verified on the fixed head: tests/session-gc.test.ts 10/10 ✅ · typecheck ✅ · full suite 2180 pass / 0 fail / 2 pre-existing skips ✅. CI re-running now.

Prior review verdict stands — once CI is green the PR is ready for you to merge: #1084

CI 暴露了测试临时目录助手在 runner 上(无 TMPDIR、无 .tmp/)的 ENOENT,已直接在分支上改用全仓库通行的 os.tmpdir() 并复验全绿,功能代码不受影响。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

CI is fully green on the fixed head 147fcab — all 8 check runs pass: test matrix (ubuntu+windows × node 22/24) ✅, build-artifact ✅, version-guard ✅, zero-token codex E2E ✅, codex CODEX_HOME/MCP job ✅.

Final state of #1084:

  • Branch rebased onto current master (v0.1.133), single feature commit + one 2-line test fix (os.tmpdir() helper).
  • Local gate on the same head: typecheck ✅ · build ✅ · 2180 pass / 0 fail / 2 pre-existing skips ✅.
  • Design matches what was settled in [Feature] Default state file cleanup strategy #1082; safety rails verified in code and tests; docs zh/en in sync; no wire/version/kernel-pin changes.

Ready for you to merge: #1084 (merge stays with you — I can't merge PRs).

修复了测试临时目录在 CI 上的 ENOENT(改用 os.tmpdir()),分支已 rebase 到最新 master,本地与 CI(含全平台测试矩阵和 codex E2E)全部通过,可以合并。

@ranxianglei ranxianglei left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

审查结论:FIX-FIRST(rebase + 两处修复后重审)

骨架是好的:kill switch(BILI_SESSION_GC=0)、resident/pending 守卫(dropSessionForGc 防抖写复活)、损坏/不可读文件一律不动只计数、测试全确定性(注入 now + utimesSync,吸收了 #360 教训)。以下按严重度:

🔴 HIGH(与 #1083 的跨 PR 语义冲突):readRawFile 让 GC 对默认格式文件整体失效

src/persist.ts:489-504(本 PR)的 head-peek 只解 BILIENC1:head.equals(ENCRYPT_MAGIC) ? codec.decode(raw) : raw.toString("utf8")。#1083 一合,默认输出是 BILIZSTD1 → 走 utf8 分支 → JSON.parse 抛 → unreadable → 永不删除。GC 对所有默认格式文件静默 no-op,整个功能失效且无任何报错。 修法一行:无条件 this.codec.decode(raw)(decode 本就按 magic 分发、明文直通)。本 PR base 早于 #1083,rebase 时必须带上这个适配——这正是热文件上两个并行 PR 的潜伏断裂(§7.2)。

[Medium] rawInputTokens 只数文本,图片重的会话被误判可删

estimateRawBodyTokens(src/preflight.ts:171-187)只走字符串键;记录在 src/server.ts:1468;isGcEligible(session-gc.ts:116)在值存在时独占信任。图片为主的闲置会话(如 400K 图 token + 50K 文本)记 50K → eligible → 删除 → resume 重新灌满窗口——恰好是设计注释里说要防的事故。建议把图片 token 估计并入记录值,或对含图轮次回退 blocks+context 启发。

[Medium] 7 天默认删除需要 owner 在合并时明确签字

session-gc.ts:44-47 注释自认 "Owner decision… aggressive by design"。代价要说清:删除后 bili export 再也无法渲染该会话(proxy 侧折叠视图/块摘要是唯一记录,raw 历史从不持久化);重建成本=全新 preflight 折叠+模型压缩 token+冷 prefix cache。现在只有一行聚合日志。建议:BILI_SESSION_GC_DRY_RUN=1 + 每文件 debug 行(符合 §7.3 日志纪律)。默认开启+无 dry-run 的数据删除,按本仓库的数据丢失保守度需要显式 re-confirm。

小项

  • [Low] 多实例:resident 守卫是进程内的;共存实例跑 BILI_PERSIST=0 对共享 BILI_SESSIONS_DIR 不刷 mtime,其活会话文件会老化被扫。7d 门实际兜底,但至少文档提一句。
  • [Low] TOCTOU(session-gc.ts:186-205):扫描中到来的请求会重建会话/文件——良性(最坏冷重建),无需动作。
  • [Process] mergeable_state: behind → rebase + 全量门禁;预期 HIGH#1 在 rebase 时暴露。

@ranxianglei

Copy link
Copy Markdown
Owner Author

Fix follow-up on the earlier review (#1084 (review)): both blockers are fixed on this branch in 4c90034 (rebased over 147fcab), gates green (typecheck / 2175 tests / build).

1. readRawFile is now format-agnostic (src/persist.ts) — the head-peek that only recognized BILIENC1 is replaced by: try JSON.parse(utf8) → on failure, codec.decode(raw) → null. Root-cause rationale: enumerating frame magics drifts every time a new frame format lands (it already would have no-op'd the GC against #1083's default BILIZSTD1 output); the codec's own magic dispatch + plaintext fallthrough is the stable contract. Regression tests cover plaintext / codec-framed / garbage (garbage → null → GC keeps the file).

2. rawInputTokens now includes images — src/server.ts:1468 records estimateRawBodyTokens(parsed) + imageTokensInParsedBody(protocol, parsed) (src/image-tokens.ts, default billing="bytes"). Image-heavy idle sessions are no longer misjudged deletable. e2e round asserts recorded tokens ≥ text+image estimate.

Remaining open item from the review (not code): the 7-day default still needs explicit owner sign-off at merge time — data deletion with no dry-run deserves a conscious yes. BILI_SESSION_GC_DRY_RUN was suggested in the review; leaving that decision to the owner.

@ework — please re-review the current head 4c90034 in full (fresh pass over the whole diff, not just these two hunks).

ranxianglei pushed a commit that referenced this pull request Sep 21, 2026
Low item from #1084 review: a co-resident instance that does not persist
(e.g. BILI_PERSIST=0) never refreshes mtimes, so its live session files can
age out under a shared BILI_SESSIONS_DIR. Worst case is the same bounded cold
rebuild, backstopped by the age gate — documented in both languages.
@ranxianglei
ranxianglei force-pushed the 2026-09-21_session-file-gc branch from 4c90034 to 1bd5152 Compare September 21, 2026 16:03
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

Full re-review done — both blockers verified fixed, base cleaned up, all gates green.

One process note first: the pushed head 4c90034 carried its own copies of master's revert + release v0.1.134 commits (952b0f9/8cd6234 vs master's 369f9d5/d81fb41) instead of sitting on the real master SHAs — net diff was clean, but merging would have planted duplicate release commits in master's history. Rebased onto live master (9c01dbe, v0.1.134); git dropped the two duplicates as previously-applied, leaving three linear feature commits. New head: 1bd5152.

Blocker 1 — readRawFile format-agnostic ✅ (src/persist.ts)
Verified against the codec contract itself (src/encrypt.ts:85): decode() dispatches on the magic and passes non-magic input through; a decode failure throws → outer catch → null → GC keeps the file. The load-bearing invariant: readRawFile delegates to the same codec object the store's id-keyed loaders use, so "GC can decode X" ⟺ "the store can load X". Any future frame (#1083's BILIZSTD1) must extend codec.decode for normal loads to work at all, so the sweep picks it up with zero changes here — no magic enumeration left in GC code. Note #1083 isn't on master yet, so this is forward-compat by design; today's behavior is pinned by the new regression test (plain JSON / codec-framed / unknown-frame garbage → null → kept, asserted both at readRawFile level and GC level).

Blocker 2 — image tokens in rawInputTokens ✅ (src/server.ts:1468)
Now records estimateRawBodyTokens(parsed) + imageTokensInParsedBody(protocol, parsed). Checked the helper (src/image-tokens.ts:211): covers openai image_url, anthropic image source, responses input_image (+ tool images), google inlineData/fileData; default billing bytes; returns 0 when no images. No double-counting — estimateRawBodyTokens skips exactly the binary payload keys (data/url/b64_json/file_data) that the image helper prices. The e2e round-trip now sends an image turn and asserts recorded ≥ text+image estimate, plus persistence survival.

Small item fixed directly on the branch (commit 1bd5152): the review's [Low] multi-instance ask — added one sentence each to CONFIGURATION.md / .zh-CN.md noting the resident guard is per-process (a co-resident BILI_PERSIST=0 instance never refreshes mtimes; worst case = same bounded cold rebuild, age gate backstops).

Gates on final head 1bd5152: local typecheck ✅ · build ✅ · full suite 2173 pass / 0 fail / 2 pre-existing skips ✅ (matches your 2175 count) · CI 8/8 check runs success (test matrix ubuntu+windows × node 22/24, build-artifact, version-guard, zero-token codex E2E, codex overlay job) ✅. Net diff vs master: exactly the 9 feature files, +666/−1.

Remaining open item (yours, not code): the 7-day default + no dry-run still needs your explicit sign-off at merge time — deleting data without a rehearsal deserves a conscious yes. If you want BILI_SESSION_GC_DRY_RUN first, it's a small follow-up PR; otherwise merge with the decision noted in the merge commit. Otherwise ready: #1084 (merge stays with you).

两个 blocker(readRawFile 格式无关化、rawInputTokens 计入图片 token)均已按根因修复并验证,分支已 rebase 到最新 master 剔除重复的 release/revert 提交、补上多实例文档说明,本地与 CI 全绿;剩 7 天默认值/dry-run 一项等你合并时拍板。

@ranxianglei

Copy link
Copy Markdown
Owner Author

独立审查结论:approve(需 rebase 后合并)。 我把 PR head bcd7183 rebase 到当前 master b2f28c6 做了完整验证,设计与实现都过关,但 rebase 有一个文本层看不见的语义断裂必须处理,详见下文。

语义审查(通过)

  • 四条 owner 要求全部落实且相互咬合:opt-in(BILI_SESSION_GC 仅 1/true/on 启用)、双条件收紧为「age>7d AND 从未压缩(零 active/inactive 块 + 零 blockContents)AND rawInputTokens≤1M(旧文件回退 contextTokens)」、阈值机理(m00001 重分配错配风险)写入代码注释与文档、逐条审计日志 + 扫描汇总。
  • readRawFile format-agnostic 的取舍正确:先试 plain JSON、失败走 codec.decode——枚举 magic 前缀会在未来帧格式(feat: zstd-compress session files by default, decoupled from encryption (#1080) #1083 zstd)落地时静默失效 sweep,这个设计规避了 cross-PR 漂移。
  • resident 守卫三条件齐:inFlight>0 || hasPending || lastSeen>savedAt+1s → keep,先 dropSessionForGc 再 rm,防 debounced writer 复活已删文件。
  • rmdir 带 parent !== dir 守卫;boot sweep + unref'd interval;GC 需 store.enabled AND opt-in 双门(与 chain-detection 的 getStore().enabled 前置同构)。
  • rawInputTokens 记录含 image tokens(image-heavy 会话不会被判便宜),native compaction 边界后 latest-wins 与真实 re-send 成本一致。

⚠️ rebase 到当前 master 的实操报告(必须处理)

  1. 语义断裂(文本 rebase 看不见):tests/session-gc.test.ts:15 引 createSessionCodec,该导出在 master 已改名 createStorageCodec(签名从 (key) 变为 ({ key, compress }),返回 StateStoreCodec | undefined)。修法:import 改名,两处调用改 createStorageCodec({ key: parseEncryptionKey(keyHex) }) 并补非空断言。修复后 11/11 通过。
  2. 文本冲突三处:src/session.ts(hasProcessedState(fix: chain-detection content fallback exempts this instance's own sessions (#1086) #1090)与 dropSessionForGc 相邻插入,union 两侧,注意共享尾括号);CONFIGURATION.md/CONFIGURATION.zh-CN.md 各一处(表格行,union 时警惕保留双方全部行——我机械并集时曾多留了一行旧版 BILI_SESSION_GC 文案和一行旧版 BILI_ENCRYPTION_KEY,en/zh 都要查重)。

修复后验证(rebased head 上)

typecheck ✅;GC 测试 11/11 ✅;全量 2268 pass / 0 fail / 2 skip(既有门控)✅。

已知挂起项(ework 已自行标注,不阻塞):与 #1099 的双 GC 归并、store/ 目录总 footprint 计量——等 #1097 落地后另开。

…le audit log (#1082)

Rebased onto master v0.1.139 (b2f28c6): adopt createStorageCodec({key})
in tests (codec rename from the #1083 era), union #1090 hasProcessedState
beside dropSessionForGc, keep master's updated BILI_ENCRYPTION_KEY doc
row (drop pre-#1083 wording). Squashed of the five prior commits.
@ranxianglei
ranxianglei force-pushed the 2026-09-21_session-file-gc branch from bcd7183 to 9e503f4 Compare September 23, 2026 06:28
@ranxianglei
ranxianglei merged commit c9e4572 into master Sep 23, 2026
8 checks passed
@ranxianglei
ranxianglei deleted the 2026-09-21_session-file-gc branch October 15, 2026 05:32
cskwork pushed a commit to cskwork/billion-context that referenced this pull request Oct 21, 2026
…nglei#1082)

Low item from ranxianglei#1084 review: a co-resident instance that does not persist
(e.g. BILI_PERSIST=0) never refreshes mtimes, so its live session files can
age out under a shared BILI_SESSIONS_DIR. Worst case is the same bounded cold
rebuild, backstopped by the age gate — documented in both languages.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature] Default state file cleanup strategy

1 participant