Skip to content

fix: guard rememberedPluginMessages against side-shaped snapshot eviction (#1307) - #1312

Merged
ranxianglei merged 4 commits into
masterfrom
2026-09-25_side-request-snapshot-guard
Sep 25, 2026
Merged

ranxianglei merged 4 commits into
masterfrom
2026-09-25_side-request-snapshot-guard

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Fixes #1307

Root cause

rememberPluginMessages() (src/plugin.ts) rewrote remembered[sessionId] unconditionally after every forward. An auxiliary request riding the main session key with a normal output budget (the host layer stack fills one in — DSH auto-review resolves to max_tokens=384000) bypasses the #388 ≤200 heuristic, walks the full pipeline with a 1-2 message synthetic view, and evicts the main turn's snapshot. The plugin tool API then anchors compress ranges from a 1-message window → every other ref dangles → Requested range(s) cannot be anchored. The issue's 4 MB production log: 163/163 plugin-path compress failures with ctx==1, 62/62 successes with ctx>1, zero crossovers — fully deterministic.

Fix (Fix A from the issue, write-point guard)

An incoming view of ≤2 messages never evicts a richer remembered snapshot (shrink direction only):

  • fresh session (no previous view) still writes — first turns unaffected;
  • same-size refresh still writes — only the shrink is guarded;
  • empty views (side-passthrough prepared) never clobber;
  • a genuinely larger view always overwrites.

Litmus ("would this hold if the same root cause surfaced in a different shape tomorrow?"): the invariant guarded is the tool API's anchor view must never be replaced by a strictly smaller one — any future auxiliary shape (WebSearch refinement, risk classifiers, new hosts) hitting this write point is caught regardless of its budget/tools/message mix.

Why Fix B (pipeline-entry isNonSnapshotRequest) is NOT included

It was implemented and tested on this branch, then deliberately dropped. The proposed signature (no tools + ≤2 messages + zero ref overlap) is ambiguous on the wire:

Scoping the predicate to plugin mode fixed the thin-client class but still broke the window-resolution contract; unscoped it broke 14 existing e2e contracts. Same wire shape, different intent, no reliable structural separator — details in the issue thread. The residual side effects of a pipeline-walking auxiliary request (one ref minted — #1075-bounded; nudge-baseline rewrite; orphan-GC streaks after 3+ consecutive auxiliary requests) are view-layer only, bounded, and self-heal on the next main turn; tracked for follow-up in the issue.

Tests (tests/issue1307-side-snapshot.test.ts)

  • unit: the guard's full decision table (fresh write, replace-by-larger, review-shape kept, empty view kept, same-size refresh replaces, fresh-session small write);
  • e2e plugin lane (the issue's §3.5 A/B shape): main turn (12 msgs + tools) → review-shaped request (no tools, max_tokens=384000, system+user pair) → POST /__bili/plugin/tool compress succeeds (Compressed m00001–…, no cannot be anchored).
  • A/B: both tests fail with the guard removed (bug reproduced), pass with it.

Pre-flight

  • npm run typecheck ✅
  • new tests 2/2 ✅; A/B red without the fix ✅
  • regression sweep vs pristine master on this sandbox (281 test files, dsh-native excluded — it times out on master here too): failure set identical to master's (4 environmental host-detection failures, all reproduce on master) — zero regressions.
  • npm run build ✅; full suite deferred to CI as agreed.

Merge stays human (wire-path change, AGENTS.md §7.4).

…tion (#1307)

Auxiliary requests (DSH auto-review etc.) ride the main session key with a
NORMAL output budget — the layer stack fills one in — so the #388 <=200
side-request heuristic never fires and they walk the full pipeline with a
1-2 message synthetic view. The post-forward rememberPluginMessages() then
evicted the main turn's remembered snapshot with that view, and the plugin
tool API (compress) anchored ranges from a 1-message window: every long-
session ref turned dangling ("Requested range(s) cannot be anchored");
production log in the issue: 163/163 compress failures with ctx==1, 62/62
successes with ctx>1, 0 crossovers.

Fix: shape-guard the WRITE POINT — an incoming view of <=2 messages never
evicts a richer remembered snapshot (shrink direction only; fresh sessions
and same-size refreshes still write). Verified end-to-end: main turn ->
review-shaped request (no tools, normal budget, system+user pair) ->
plugin-path compress still anchors.

Fix B from the issue (pipeline-entry non-snapshot classification via zero
ref overlap) was implemented and deliberately dropped: the shape is
ambiguous on the wire. Wire-mode thin clients legitimately send stateless
1-2 message no-tools turns (compress injection, #1075's one-ref contract)
and the plugin lane's per-request window resolution (anthropic-beta) rides
the same shape — classifying those breaks 14 existing e2e contracts. The
residual side effects (nudge baseline rewrite, orphan-GC streaks after 3+
consecutive auxiliary requests) are bounded and self-heal on the next main
turn; tracked in the issue thread.
@github-actions

github-actions Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-09-25_side-request-snapshot-guard (0515d33)

Option A — Install from npm PR tag (recommended)

npm install -g billion-context@pr-1312

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

Option B — Download artifact

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

Install instructions are refreshed on each push.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 ## PR Review — #1312 (fix: guard rememberPluginMessages against side-shaped snapshot eviction, Fixes #1307)

Reviewed head bbe42aae (branch 2026-09-25_side-request-snapshot-guard, base master dc8bdea5). Single commit, 2 files (src/plugin.ts +20, tests/issue1307-side-snapshot.test.ts +170), no version bump, no lockfile churn. Verdict up front: mergeable — merge stays human (wire-path change, §7.4).

① Original issue (direction gate) — pass

#1307's root-cause analysis is sound and I independently re-verified the code path on master: isSideRequest() (budget ≤200) misses the DSH auto-review shape (no tools, 1–2 msgs, max_tokens=384000) → full pipeline walk → src/server.ts:2189 writes the 1-message view into remembered unconditionally → handlePluginTool (src/plugin.ts:901) anchors compress ranges from a 1-message visible set → every other ref dangles. The 163/163-vs-62/62 deterministic split confirms it.
The fix sits at the write point — the decision point where the bad value is produced — matching #1307 §5 Fix A and the #1075 risk-asymmetry principle. Litmus holds: the guarded invariant (anchor view must never be replaced by a strictly smaller one) catches any future auxiliary shape at this write point regardless of budget/tools/message mix — the unit table proves it (1-msg, 2-msg, and empty shapes all held). Rejecting Fix B is well-evidenced (entry-level routing collides with #1075's one-ref consumption contract and the anthropic-beta per-request window-resolution contract — same wire shape, different intent), and the policy conflict is properly escalated to owner decision in open follow-up #1309 instead of being silently resolved. Correct handling.

② Regression review — existing behaviors on touched paths, itemized

The only write site is src/server.ts:2189 (all modes, post-forward); the only readers are handlePluginTool (src/plugin.ts:901) and handlePluginStatus (src/plugin.ts:733) — both plugin-lane endpoints. Verified each existing behavior:

Existing behavior Verdict
Fresh session first write (no previous view) Preserved — previousCount=0, guard can't fire. Unit-tested.
Main-turn monotonic growth (ACP hosts resend full history) Preserved — larger views always overwrite. Unit-tested (8→9).
Same-size refresh Preserved — only strict shrink is guarded (iso-c case). Deliberate, keeps content freshness.
Empty prepared view (side-passthrough) Intentionally changed — no longer clobbers a richer snapshot. This closes a second variant of the same bug (empty view → messages=[] → total anchor failure), strictly an improvement. Real main requests never produce empty prepared views.
Native-compaction shrink to ≤2 live msgs Intentionally changed, disclosed — refresh delayed one turn, self-heals on next normal request. Old→new stated in the PR body; accepted cost.
Wire-mode (non-plugin) sessions Unaffected — their ≤2-msg thin turns no longer shrink their own remembered entry, but nothing in wire mode reads remembered (consumers are plugin-header-gated). Zero wire impact.
Nudge snapshot Preserved — skipped write keeps the previous entry verbatim (incl. its nudge); the status panel recomputes nudge from live state anyway (#387 path at src/plugin.ts:735-758).
#1075 one-ref consumption contract Preserved — auxiliary still walks the pipeline; tests/fix-1075-side-request.test.ts 9/9 pass locally on this head.
anthropic-beta context-1m per-request window resolution (the contract Fix B would have broken) Preserved — tests/anthropic-beta-window.test.ts 3/3 pass locally on this head.
Residuals (ref minting, nudge-baseline/lastMessages rewrite, orphan-GC streaks on 3+ consecutive auxiliaries) Not covered by design — view-layer only, bounded, self-heal on next main turn; tracked in #1309. Consistent with #1307 §6.

No unintended regressions found.

③ Code review

Guard logic is correct and minimal; the incoming/previousCount convention mirrors the reader side (processed.length > 0 ? processed : original) exactly, so the comparison measures what the tool API actually sees. Two notes:

  1. Small fix applied directly (labeled commit): the original guard body contained remembered.delete(sessionId); remembered.set(sessionId, previous!); — a no-op (re-inserts the same reference; nothing iterates remembered order-dependently — only the stale-cleanup key filter and .clear()). Replaced with a bare return;. Pushed as 9ba1b5b9 refactor: drop redundant map rewrite in #1307 guard (no-op) on the PR branch; typecheck + issue1307 + side-request-isolation suites re-run green (16/16). CI re-triggers on it.
  2. Observation, non-blocking: the early return also skips the stale-session cleanup loop, so during an all-auxiliary burst dead sessions' entries linger until the next non-skipped write. Bounded (session-count × message arrays), self-healing within seconds on the next main turn — acceptable as-is; moving the cleanup block above the guard would be a trivial hardening if you ever want it.
  3. Optional consideration: the guard fires silently (no log line). Given this bug was diagnosed from production logs, a single info line on guard hit would aid future triage — noting you did ship this without the log that fix: hold remembered anchor snapshot against auxiliary <=2-message views (#1307) #1308 had, so treating this as your call, not a requirement.

④ Test validity — real teeth, independently re-verified

  • Unit: full decision table of the guard (fresh write / replace-by-larger / 1-msg held / 2-msg held / empty held / same-size replaces / fresh-small writes). Covers every branch.
  • E2E: reproduces the issue §3.5 A/B shape exactly (12 msgs + tools main turn → same-session no-tools max_tokens=384000 system+user pair → POST /__bili/plugin/tool compress), asserting both the intermediate invariant (snapshot ≥12 survives) and the outcome (Compressed m00001…, no cannot be anchored).
  • I reproduced the A/B myself: in a worktree of pristine master with only the _rememberedForTest seam added (guard absent), both tests fail — unit on "main snapshot survives the side-shaped write", e2e on "the main snapshot survived the review-shaped request" — i.e. the tests fail on the exact bug symptom and pass with the guard. Not tautological; they pin the behavior.
  • Pre-flight claims check out: typecheck clean locally; CI on bbe42aae fully green (ubuntu 22/24, windows 22/24, real-codex e2e, pi lane, hermetic registry e2e, build-artifact, version-guard).

⑤ Diff cleanliness

Clean. Every line serves the fix; no unrelated files, no whitespace churn, version untouched. After my cosmetic commit the PR is two linear commits, both labeled.

Behavior-change disclosure (Deliverables #4) — confirmed present

Old: any prepared view overwrote remembered[sessionId] (≤2-msg auxiliary views evicted the main snapshot). New: a ≤2-msg incoming view never evicts a strictly richer remembered snapshot; fresh writes, same-size refreshes, and larger views behave exactly as before; native-compaction shrinks to ≤2 delay one turn. Stated in the PR body with rationale. ✅

Duplicate screening

Direct fix for #1307 (whose §4 documents the #388/#398-family dedup). Earlier attempt PR #1308 is closed-unmerged (superseded by this one). Follow-up #1309 (Fix B vs #1075 policy conflict) open for owner decision. No duplicates.

结论(中文一句话): 修复了辅助请求(auto-review 等「≤2 条消息 + 正常输出预算」形状)冲掉 plugin 会话 remembered 锚点快照、导致长会话 compress 全部报 cannot be anchored 的问题——在写点加「小视图不得顶掉大快照」护栏(根因在写点,方向正确),既有行为逐项清点无意外回归、测试红绿双向独立复验通过、diff 干净,我已顺手清掉一处无效代码(单独标注的 commit),可以合并。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Addendum (base moved during review): master advanced by one merge since the PR was opened — #1311 (fix: absorb same-frame tool_call deltas before the finish_reason settle (#1306)), which touches stream parsing only and neither src/plugin.ts nor this PR's test file. I rebased both PR commits onto the fresh master locally and re-ran the gate: typecheck clean, targeted suites 29/29 (issue1307-side-snapshot, side-request-isolation, fix-1075-side-request, anthropic-beta-window, proxy-orphan-gc), build success. The remote branch is left untouched (no rebase push needed — zero file overlap, GitHub merges cleanly); verdict unchanged: mergeable, merge stays human.

The ≤2-message threshold is the same class of proxy the issue convicted in
the ≤200 budget: a 3+ message auxiliary prompt (few-shot review shapes)
walks straight through it. The causal signal is identity — a main turn
RESENDS the conversation, so it always carries messages the previous
snapshot already holds (content-hash ids are stable); an auxiliary prompt
shares nothing with it by construction. Guard becomes: zero overlap AND
smaller than the snapshot → refuse to evict.

- 3-message zero-overlap auxiliary shapes are now refused (count missed them)
- a smaller view that OVERLAPS is a genuine continuation (client trimmed
  history) and MUST write — count-only would wrongly freeze the snapshot
- larger zero-overlap views (real restart on the same session id) still write
- fresh sessions, same-size refreshes unchanged
@ranxianglei

Copy link
Copy Markdown
Owner Author

Guard upgraded from the message-count threshold to identity overlap (follow-up to review feedback — count was the same class of proxy the issue convicted in the ≤200 budget):

if (previous && previousView.length > incoming.length) {
    const knownIds = new Set(previousView.map((m) => m.id));
    if (!incoming.some((m) => knownIds.has(m.id))) return;   // keep the snapshot
}

Rationale: a main turn resends the conversation, so it always carries messages the previous snapshot already holds (content-hash ids are stable); an auxiliary prompt shares nothing with it by construction — regardless of its message count or budget. Litmus: a 3+ message few-shot review shape walks through the ≤2 guard but is still refused here; a client that genuinely trims history resends a smaller overlapping view and must (and does) still write.

  • 3-message zero-overlap auxiliary shape → refused (new unit case)
  • smaller overlapping view (trimmed history) → writes (count-only would have wrongly frozen the snapshot — new unit case)
  • larger zero-overlap view (real restart on the same session id) → writes (guard is shrink-direction only)
  • fresh session / same-size refresh → unchanged

Pre-flight re-run: typecheck ✅, new tests ✅ (red with the guard removed), 281-file sweep vs pristine master → failure set identical (4 sandbox-environmental, all reproduce on master). CI re-running.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Round-2 review — identity-overlap guard (ad04c73b): verified, mergeable (merge stays human).

① Direction. Strictly better than the count threshold: message count was indeed the same class of proxy the issue convicted in the ≤200 budget; ID overlap is causal — a main turn resends the conversation (stable ids), an auxiliary prompt shares nothing by construction regardless of count or budget. This is exactly the conservative variant issue §5 proposed (「把条数换成与已知 ref 的重叠度」), so the fix now holds under the litmus for any future auxiliary shape.

Id-stability premise verified in kernel source: deriveMessageId(role, contentType, text) = "h_" + sha256(${role}|${contentType}|${toolCallId}|${toolName}|${text})[:16] (acp-kernel dist/wire/index.js:8–11), assigned once per request at parse time (clusters.next(base)); kernel processing mutates .text but never .id, so processed/original views carry identical ids per logical message, and both sides of the guard use the processed-preferred convention consistently. Same property the ref/anchor system already depends on — no new fragility introduced.

Behavior delta (old→new disclosure):

  • Stricter: smaller zero-overlap views with any message count are now refused — round 1 left 3+-message auxiliary shapes (few-shot review prompts) still evicting.
  • Looser: smaller overlapping views now always write — including shrinks to ≤2, releasing round 1's disclosed cost (a client trimming history down to its last 2 messages would have frozen the snapshot for one turn).
    Both directions are pinned by the new unit cases; the e2e section is unchanged.

Verification matrix (all run locally by me):

  • GREEN ad04c73b: typecheck clean; 29/29 across issue1307-side-snapshot, side-request-isolation, fix-1075-side-request, anthropic-beta-window, proxy-orphan-gc.
  • RED pristine master (test seam only, no guard): new tests fail 0/2 — bug reproduced (unit "main snapshot survives" + e2e anchor).
  • OLD head 9ba1b5b9 (count guard) running the NEW tests: e2e passes, unit fails exactly on the new 3-message zero-overlap assertion (expected: 8, actual: 3) — proving the upgrade changes behavior precisely where intended, not cosmetically.

Edge cases walked: fresh session writes ✓; larger view writes (grow direction) ✓; empty incoming refused (some() over [] = false) ✓; same-size zero-overlap writes (not a shrink) ✓; post-compaction views keep ≥1 surviving raw-tail message id → overlap preserved → snapshot updates ✓; a true restart on a reused session id keeps the stale snapshot until the new conversation outgrows the old one — degenerate case, author-disclosed in the code comment, no worse than round 1; ClusterCounter _N suffix shifts (trimming changing duplicate counts) can cause at most one extra refused turn, never persistent (ids re-derived from wire text each request).

Regression inventory delta vs round 1: only the two behavior items above; all other behaviors from the round-1 inventory are unchanged. Diff vs 9ba1b5b9 is exactly src/plugin.ts (+28/−19) and the test file (+36/−24) — clean.

Small fix pushed directly on the branch (labeled commit, new head 0515d331): the decision-table comment "(8 messages, carries the previous one)" was factually wrong — {r0} ∩ {raw-0..raw-7} = ∅, that line exercises the grow direction, not overlap; corrected so a future reader can't misattribute which invariant pins it. CI re-runs on the new head.

📌 中文摘要:把 #1307 快照守卫从「≤2 条消息」阈值升级为「与既有快照零 id 重叠才拒绝」——用因果判据替代代理指标,堵住 3+ 条辅助请求的残余驱逐、同时解除对真实修剪历史的误冻结;已在 master / 旧守卫 / 新头三个基线上独立复验(红 / 红 / 绿),可以合并(合并仍由人工执行)。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 重复投递确认:本条(identity-overlap 守卫升级)的完整 review 已在上楼发出(round-2 review,含三基线红/红/绿验证矩阵与行为变更披露),分支上已直接补了标注注释修正提交,当前 PR head = 0515d331,CI 在其上重跑中。无新增待办;合并仍由人工执行。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 CI 状态更新:最终 head 0515d331 上全部 10 项检查通过(ubuntu/windows × node22/24 测试矩阵、codex/pi/registry e2e、build-artifact、version-guard),无失败项。PR #1312 无任何待办,可以合并(合并仍由人工执行)。

@ranxianglei

Copy link
Copy Markdown
Owner Author

Scope note (reviewer please read): this PR is a stopgap, not the root fix — tracked in #1314.

It blocks exactly one fatal path (auxiliary requests evicting the remembered snapshot) and leaves open: pipeline side-effect isolation (orphan-GC streaks, nudge baseline), a general conversation-identity mechanism (known edges: same-session restart, byte-verbatim echo false-positive), and — likely the bigger cost — the review request's OWN compression economics (flattened ~1.2MB transcript, zero prefix-cache hits, no foldable ranges). #1314 discusses the root directions: prefix-chain identity (src/prefix-affinity.ts), host-side structured review requests, marker headers. This guard stays on as defense-in-depth.

@ranxianglei
ranxianglei merged commit 5e7b085 into master Sep 25, 2026
10 checks passed
@github-actions github-actions Bot mentioned this pull request Sep 25, 2026
ranxianglei pushed a commit that referenced this pull request Sep 27, 2026
…vs-remembered naming (#1431 review)

- F1: extractWireTexts treated content:null/absent as unrecognized and
  abandoned the whole view — but content:null is the canonical agent shape
  for tool-calling assistant turns (our own e2e fixtures send it), so the
  anchor was never recorded and auxiliary routing stayed silently inert for
  exactly the sessions it targets. Null/absent now contributes empty text
  (mirrors the array branch skipping non-text parts; identity rides
  role + position).
- F2: e2e the true discriminator boundary — a 2-message request carrying a
  recognized anchor message runs the full pipeline (overlap beats the ≤2
  gate), not side-passthrough.
- F4: one-line comment distinguishing the anchor view (side-request.ts,
  routing) from the remembered view (#1312 plugin.ts store, write guard).
@ranxianglei
ranxianglei deleted the 2026-09-25_side-request-snapshot-guard branch October 15, 2026 05:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant