Skip to content

fix: accept the kernel BLOCKED sentinel in plugin snapshot/fork validation (#2620) - #2625

Merged
ranxianglei merged 3 commits into
masterfrom
2026-10-10_protected-tools-snapshot
Oct 11, 2026
Merged

ranxianglei merged 3 commits into
masterfrom
2026-10-10_protected-tools-snapshot

Conversation

@ranxianglei

@ranxianglei ranxianglei commented Oct 10, 2026 •

Copy link
Copy Markdown
Owner

Closes #2620

What

With compress.protectedTools matching a tool call/result in plain-text history, GET /__bili/plugin/snapshot returned 409 {"code":"SNAPSHOT_UNAVAILABLE","error":"Error: raw/ref mapping inconsistent"} — so any session containing protected tool traffic could not be snapshotted or forked by plugin agents at all (and sessionRevision / expectedRevision paths threw the same way).

Root cause

The kernel deliberately maps protected messages into an unaddressable state: no numeric ref is issued, and byRef never holds them (kernel/src/refs.ts assignRefs). That is intended design — protected messages are never rendered, never CCR-stored, never foldable. The consumer bug is on the host side: the plugin protocol assumed every message has exactly one bidirectional byRaw ↔ byRef ref pair (a total function) and classified the kernel's partial-function state as corruption.

Fix (host-side only, no kernel change)

The clean model, per owner review: ref is optional in the protocol itself. The wire expresses "intentionally unaddressable" as ref: null — the kernel's internal sentinel never appears in any wire byte, and no consumer special-cases a magic string:

  • src/plugin.ts forkSnapshot (the reported 409 site) — the single boundary that maps the kernel sentinel to null; numeric refs keep the strict bidirectional check, so genuinely corrupted mappings still throw.
  • src/plugin.ts parseForkRequest — accepts only mNNNNN or null per entry (stricter fail-fast than before for garbage strings).
  • src/plugin.ts child ref copy-back — null reserves the raw id under the kernel sentinel exactly as the parent holds it; byRef / tokenSnapshot stay pure numeric-ref spaces.
  • src/plugin.ts CCR clone path — skips unaddressable entries (they have no store payload by construction).
  • src/fork-adoption.ts planForkAdoption + applyForkAdoption (Claude 上 resume 导致消息错乱 #1486 resume lane) — the internal plan/applier keep the same invariant: the sentinel may live in byRaw, must never be written into byRef. Pinned with unit regressions.
  • src/agent/fork-adopt.ts — client type/parser widened to string | null; matching and hashing are identity-based (identityHash excludes refs), so null flows through untouched. Hash-parity replicas unchanged.
  • PLUGIN.md (en+zh) — documents null as the only other legal ref value.

Forgery safety is unchanged: fork POSTs are still checked byte-for-byte against the live parent snapshot (stableJson(prefix) === stableJson(request.orderedMessages)), so a forged ref for a numbered message fails BRANCH_POINT_CONFLICT; multiple unaddressable messages stay distinguishable via rawId + identityHash + order.

Behavior change (disclosed)

Sessions with protected tool traffic go from unusable snapshot/fork (409 snapshot / 400 fork request / 409 FORK_PREFIX_CONFLICT child first request) to fully usable, with protected messages carrying "ref": null in orderedMessages/messages. Non-protected sessions are byte-identical — every previously-valid input behaves identically. No compression semantics, config fields, persistence format, or upstream wire changes. No new config surface.

Cross-version matrix: new proxy + old agent → old agent rejects the snapshot and adoption degrades gracefully (exactly today's pre-fix behavior); old proxy + new agent → unaffected (null simply never arrives). No released build ever emitted the intermediate "BLOCKED" literal this design replaced pre-merge, so there is nothing to migrate.

Verification (on rebased head = current master)

  • Regression tests in tests/plugin-fork.test.ts: (1) protected-on A/B history with two ask_user_question pairs → snapshot 200 with exactly four null refs, an explicit assertion that the string "BLOCKED" never appears on the wire, fork 201, child identity identical, child byRef["BLOCKED"] stays undefined, child continuation request 200, status revision present — reproduced the exact issue 409 body pre-fix; (2) genuinely corrupted numeric mapping still rejected with 409 raw/ref mapping inconsistent. Unit regression in tests/fork-adoption-plan.test.ts pins the applier facet.
  • Targeted suites green on the rebased head: 122 tests across plugin-fork, fork-adoption-plan, fork-adoption, dsh-fork-adopt (hash-parity contract), fork-ccr-adoption, pi-omp-fork-adopt, fork-side-request-lane, opencode-fork-adopt, side-lane-invariants, resume-ref-inheritance, resume-adoption-wires, protected-tools. npm run typecheck clean.
  • Built dist/ passes the issue's own stdlib-only Python repro end-to-end: protectedTools: [] → 200 and ["ask_user_question"] → 200 (previously 409).

Notes

@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-10_protected-tools-snapshot (7082175)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.2973-pr.2625.06af539

This exact version is immutable and reproducible. The rolling pr tag tracks the newest test build across all PRs.

Option B — Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr2625.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] 🏷 Reviewed #2625 (accept the kernel BLOCKED sentinel in plugin snapshot/fork validation, closes #2620). Confirmed the root cause against the kernel source, audited every touched path for regression, ran targeted suites + teeth-checks on the rebased head, and — while sweeping src/** for other instances of the same mechanism — found and fixed one more site on the branch. Structured conclusion:

① 是什么问题:任何历史里含 compress.protectedTools 命中的工具流量的会话,都无法被插件 agent 做 snapshot/fork——GET /__bili/plugin/snapshot 返回 409 SNAPSHOT_UNAVAILABLE "raw/ref mapping inconsistent",fork POST 返回 400,子会话首个请求返回 409 FORK_PREFIX_CONFLICT。

② 什么原因导致的:kernel 故意把受保护消息映射到 BLOCKED_REF("BLOCKED")哨兵——只写进 byRaw、永不写进 byRef(kernel/src/refs.ts assignRefs+rebuildRefIndex),它们没有数字 ref。host 侧五处插件协议代码无条件要求 byRaw↔byRef 双向一致,于是把合法哨兵判成了损坏。属消费方 bug,kernel 行为是设计使然。

③ 影响范围与严重程度:仅 plugin mode、且会话含受保护工具流量时触发;该配置条件下 snapshot/fork 功能完全不可用;proxy mode 不受影响;无数据丢失、无压缩语义影响。

④ 怎么修复的:五处都做哨兵感知校验,同时保留对真正损坏的数字映射的 fail-closed——对 BLOCKED_REF 跳过反向查找;parseForkRequest 接受字面量 "BLOCKED" ref(防伪造:fork POST 在 src/plugin.ts:1114 用 stableJson 与活的父快照逐字节比对,故给数字消息伪造 BLOCKED 仍会 BRANCH_POINT_CONFLICT);两条 copy-back 路径都只 reserve byRaw,绝不写 byRef["BLOCKED"]。

⑤ 是否有回归问题:无。五处改动都是严格泛化——对所有原本合法的(数字)输入行为逐字节不变,只有此前必然报错的哨兵现在被接受;真正损坏的数字映射仍会 throw(PR 第二个测试钉住)。无 fail-fast→吞错漂移、无阈值/时序/输出格式变化。未改动的 byRef 键消费方也逐一过过(stream.ts 正则门控、cache-ledger.ts snap??0、session.ts prune、kernel rebuildRefIndex/compress-detect),stray 哨兵键不会扰动任何一处。

⑥ 是否破坏缓存:否。只动 snapshot/fork 校验;压缩、CCR 去重、重试、revision 缓存策略均未变。

⑦ 是否改了设计方向:无架构转向——host 侧对齐既有 kernel 不变量的哨兵感知。一处已披露的 wire 变更:plugin snapshot/fork 协议新增接受字面量 "BLOCKED" ref(原先 409/400/409)。

⑧ 是否引入新配置:无。protectedTools 已存在,无新 env/config/默认值。

Review 中在分支上补修的一处(additive commit 9e8e1c8dc):扫 src/** 找同一机制的其它无条件 byRef 推导点时,发现 PR 漏掉的第六处同机制实例——src/fork-adoption.ts:255(applyForkAdoption)。它从 plan.refs.byRaw 反推 byRef,而 byRaw 仍带着共享的 BLOCKED 条目(planForkAdoption 守了 byRef 却没守它的 byRaw 兄弟),于是无条件写回——经 maybeAdoptResume(#1486)在「父会话含受保护工具流量」时可达,恰好把本 PR 在别处删掉的 byRef["BLOCKED"] 状态又引了回来。当前在所有消费方下均为惰性(已验证),但与 PR 自身守卫不一致且无测试覆盖。已按同款守卫堵住该写入点,并在 tests/fork-adoption-plan.test.ts 加了单测:pre-fix 失败(byRef["BLOCKED"] 被 clobber 成某个 raw id)、post-fix 通过;为此导出 applyForkAdoption(行为中性)以支持白盒测试。同机制 → 留在 #2620 内,不单独立项。

验证(定向、rebased head 上跑;全量套件 + e2e 门禁交给 CI):typecheck 干净;plugin-fork/fork-adoption/fork-adoption-plan/protected-tools 共 57 项全绿;把两个源文件临时回退到 master 复现了 issue 原样的 409 body(新 HTTP 测试随即 409 !== 200 失败),加回修复后转绿。

备注:本改动触碰 wire/message-shape + message-ref/id 逻辑 → §7.4 人工门禁(不自动合并),需人工 merge。PR 提到的 package-lock.json 版本漂移(vendored acp-kernel/pi-subagents 领先于 lockfile)是既有的表面漂移,file: 链接 install 时自愈,正确地未纳入 diff。

判定:可合(我补的修复 9e8e1c8dc 已在分支上);请按仓库规则手动合并。

ranxianglei pushed a commit that referenced this pull request Oct 10, 2026
…2605)

tests/issue2605-dsh-retry-patch.test.ts reads the patch file raw and
byte-matches multi-line rows; Git-for-Windows autocrlf=true converts it to
CRLF at checkout, failing both windows CI shards on every run since #2610
landed (master red at 98fb91c, run 38034641775). Same mechanism as the
#1305 golden pin above. In-passing fix carried on #2625.
@ranxianglei
ranxianglei force-pushed the 2026-10-10_protected-tools-snapshot branch from 1bc881f to 9136c63 Compare October 10, 2026 08:49
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 收到上游 PR 冲突转发(merge state: dirty)。先按纪律用 git 核实而非照单执行——结论:这个冲突已经被 owner 用 rebase 自行解决了,我这边无需再 push 任何内容(也没有强推覆盖分支)。结构化说明如下:

① 是什么问题:#2625 与 master 出现文本冲突,唯一冲突点是 .gitattributes——master(经 #2634/#2631)和 PR 分支各自独立加了同一行 dsh.bundle.patch.yml text eol=lf(只有上方注释不同),属 add/add 文本冲突;双方改动的代码文件不重叠(我这边是 src/fork-adoption.ts/src/plugin.ts/fork 测试,master 那边是 src/server/dsh-compaction-guard.ts + 两个 dsh 测试)。

② 什么原因导致的:两个 PR 针对同一个 Windows CRLF 失败类各自往 .gitattributes 加了同一条 pin——#2631 走了 master,而 #2605 的「in-passing pin」commit(1bc881f25)当时搭在本 PR 分支上;两者都在 base 98fb91cc2 之后改了同一文件 → 冲突。不是本次 #2620 的代码引起的。

③ 影响范围与严重程度:仅阻塞本 PR 合并(dirty merge state),不影响任何已发布行为、运行时或数据。低危。

④ 怎么处理的:fetch 后发现远端 head 已是 9136c63fc,是一条干净的线性栈(master tip 2d31e4212 → e079f9a07〔原 ca83fbf7c〕→ 9136c63fc〔我的 resume-adoption applier 修复,原 9e8e1c8dc〕)——即 owner 已把 PR rebase 到当前 master 并顺带解决了 .gitattributes。冗余的 #2605 重复 commit 在 rebase 时被正确丢弃(那条 pin 已由 #2631 落地),.gitattributes 保留 master 的 #2631 注释 + 单条 pin。因此我没有 push:我的本地 merge 要压过 owner 更干净的历史只能靠 force-push(规则禁止,也不该做),而且确实没有新增内容可提交。

⑤ 是否有回归问题:无。关键验证:git diff 9e8e1c8dc origin/head -- src/fork-adoption.ts tests/fork-adoption-plan.test.ts src/plugin.ts tests/plugin-fork.test.ts 为空 = 我的 #2620 代码+测试在 live head 上逐字节一致;rebase 只换了 SHA 并并入 master 的 dsh 变更,没动我的逻辑。又对 live head 9136c63fc 本地跑了 typecheck(干净)+ 57 项 #2620 相关测试(全绿)。

⑥ 是否破坏缓存:不涉及(纯分支历史 / 文件属性整合,未触碰压缩、重试、去重或增量游标)。

⑦ 是否改了设计方向:不涉及。

⑧ 是否引入新配置:不涉及。

判定:冲突已由 owner 的 rebase 清除,本 PR 现在处于干净可合状态,无需我再操作。 仍需人工合并——本改动触碰 wire/message-shape + message-ref/id 逻辑,按 §7.4 属人工门禁,不自动合并。

@ranxianglei

Copy link
Copy Markdown
Owner Author

重新做了 你再审核一下 之前的问题很大你没有拦住

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 重新审核完成(head b663386fa,已 rebase 到当前 master)。先直接回应你的批评:上次我确实没拦住核心问题。我把「在六个校验点接受 kernel 的 BLOCKED 字符串」当成了修复并放行,还顺着这个方向补了第 6 处。真正的病灶在协议层:把 kernel 内部常量 BLOCKED(kernel/src/refs.ts:13)当成 fork wire 协议自己的词汇暴露给客户端——外部消费者从此耦合一个 kernel 随时可改的内部值,且每个校验点都要重复一遍特判。我按「让校验别报错」的层次审了(堵症状),没上升到「协议不该借 kernel 内部常量」这一层(疏机制,§7.3),所以没拦下。这次重做是对的。

重做方案(b663386fa):协议里 ref 本就是可选值;renderer 在单一边界(plugin.ts:1020 forkSnapshot)把 kernel sentinel 映射成 null;校验统一把 null 当作「有意不可寻址」,数值 ref 仍走严格双向校验(真损坏依旧 fail-closed);fork 请求只接受 mNNNNN 或 null(对垃圾输入比原来更严)。sentinel 从此不出现在任何 wire 字节里。

逐点核实(都过了):

  • 全仓只有 plugin.ts:1020 一处把 BLOCKED→null,:1024 只是镜像它;没有别的 producer 往 wire 上放 "BLOCKED"。
  • resume-adoption(src/agent/fork-adopt.ts)matchForkPrefix 只按 identityHash 匹配、不碰 ref;fork POST 逐字回显 snapshot 前缀(null 原样透传),snapshotOf 放宽为 null|string。
  • 内部会话态层(src/fork-adoption.ts、kernel)仍用 BLOCKED 字符串,我上一轮加的 ref!==BLOCKED_REF 守卫作用在这一层、依然成立;wire→internal 唯一转换点是 plugin.ts:1139 ref ?? BLOCKED_REF。
  • 防伪造:live snapshot 与客户端声明现在都用 null,plugin.ts:1117 stableJson(prefix)!==stableJson(request.orderedMessages) 能抓住任何 null↔数值偷换;垃圾串、旧式 "BLOCKED" 串在 parseForkRequest 直接被拒(比原来更严)。
  • 兼容:非保护会话字节级不变;保护会话修前本就没有可用消费路径(全 409/400),换字面量零成本。新代理+新 agent(null↔null)✓;新 agent+旧代理(回显 "BLOCKED",旧代理认)✓;旧 agent+新代理(旧 snapshotOf 拒绝 null → adoption 优雅降级 = 修前行为)✓。
  • PLUGIN.md 中英两处都补了 "ref": null 说明与「合法 ref 仅 mNNNNN 或 null」。

本地证据(head b663386fa):typecheck 干净;9 个相关套件(plugin-fork / fork-adoption / fork-adoption-plan / protected-tools / resume-adoption-wires / fork-ccr-adoption / dsh-fork-adopt / opencode-fork-adopt / pi-omp-fork-adopt)共 109 项全绿。更新后的 HTTP 测试断言保护位为 [null,null,null,null] 且 !refs.includes("BLOCKED")。

八问:

  1. 是什么问题:fix: accept the kernel BLOCKED sentinel in plugin snapshot/fork validation (#2620) #2625 初版把 kernel 内部 BLOCKED 哨兵当成 fork wire 协议的合法 ref 值,把内部常量泄漏到客户端协议、并在 6 个校验点散落特判。
  2. 什么原因导致:以「让校验别报错」为目标,修在校验层(堵),没修到「协议不应借用 kernel 内部常量」这一层(疏);我初审停在症状层没拦截。
  3. 影响范围与严重程度:修前保护工具消息的会话 fork/snapshot 全部 409/400 不可用(功能缺失,非数据损坏);协议层面另埋下「外部消费者耦合 kernel 内部值」的长期隐患。属设计缺陷 + 功能不可用,非线上数据回归。
  4. 怎么修的:把「无 ref」作为协议原生概念(null),kernel sentinel 只在单一渲染边界映射为 null;校验统一视 null 为有意不可寻址、数值 ref 维持严格双向校验;请求侧收紧为 mNNNNN|null。
  5. 是否有回归:无。非保护会话字节级不变;数值 ref 的严格双向校验、CCR/孤儿/死引用过滤、ref 命名空间保留均未动;唯一语义变化是 wire 保护位由 "BLOCKED" 变 null,而该路径修前本不可用,无既有消费者受影响(跨版本均优雅降级)。
  6. 是否破坏缓存:不涉及(未触碰压缩块、tokenSnapshot 语义、增量游标或去重键;tokenSnapshot 依旧只对数值 ref 写入)。
  7. 是否改了设计方向:是(正向收敛)——fork wire 从「借 kernel 内部常量」改为「ref 可空的原生协议」,边界更清晰,方向更对。
  8. 是否引入新配置:不涉及(纯协议/代码;PLUGIN.md 仅补文档)。

判定:重做正确、完整、干净,且比初版更安全(彻底关闭了 "BLOCKED" 串的伪造面)。可合;因触碰 wire/message-shape + message-ref/id 逻辑,按 §7.4 仍需人工合并。

ework-agent added 3 commits October 11, 2026 12:23
…me-adoption applier

applyForkAdoption re-derived byRef from plan.refs.byRaw, which still carries the shared BLOCKED sentinel entries (planForkAdoption guards byRef but not its byRaw sibling), so a #1486 resume of a parent with protected tool traffic reintroduced byRef["BLOCKED"] - the exact state this change removes at every other site. Guard the applier write to match, and pin it with a unit regression.
…wire (#2620)

Owner review: accepting the kernel BLOCKED sentinel at six scattered
validation sites was a band-aid — the protocol borrowed a kernel-internal
constant as its own vocabulary, and every future consumer would have to
re-learn the special case.

The clean model: ref is optional in the protocol itself. The renderer maps
the kernel sentinel to null at the single boundary; validation uniformly
treats null as 'intentionally unaddressable' and keeps strict bidirectional
checks for numeric refs (genuine corruption still fails closed); fork
requests accept only mNNNNN or null (stricter than before for garbage).
The sentinel now appears nowhere in wire bytes and only at the boundary
mapping in host code.

Compat: non-protected sessions are byte-identical; protected sessions had
no working consumer path pre-fix (all 409/400), so swapping the literal
before merge costs nothing. New proxy + old agent degrades gracefully
(snapshot rejected -> adoption degrades, the pre-fix behavior); old proxy
+ new agent unaffected. PLUGIN.md documents the null value (en+zh).
@ranxianglei

Copy link
Copy Markdown
Owner Author

Rebased this PR onto current master (6dafceb → 9e95c32 ancestry; the only conflict was the acp-kernel import line in src/plugin.ts, resolved by union — BLOCKED_REF + COMPRESS_TOOL_NAME both kept). Verification on the rebased head 7082175: typecheck clean; this PR's suites (fork-adoption-plan + plugin-fork) 48/48; all plugin/fork-adjacent suites 220/220; persona/lineage/fold-reconcile adjacency 104/104; build OK. No semantic clash with #2719's persona-lineage routing (same hot-file region, union of intent).

Stacked on top: #2729 (session-continuity proof pinning both branch scenarios — model switch = one session, fork = copied state; its scenario B teeth reproduces this PR's fix target as a 409 on master-without-this-PR).

@ranxianglei
ranxianglei merged commit e9efe63 into master Oct 11, 2026
28 checks passed
@github-actions

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.257-master.e9efe63 (rolling master tag).

npm install -g billion-context@0.0.257-master.e9efe63  # this exact build
npm install -g billion-context@master  # always the newest merged build

npm view billion-context@master prints the current version at any time.

antclt pushed a commit to antclt/billion-context that referenced this pull request Oct 11, 2026
…lei#2601/ranxianglei#2676)

Scenario A pins the model-switch contract: a dsh model switch (system
model line + x-bili-plugin-model header) landing in the same window as
an unannounced history rewrite is ABSORBED — raw key kept, no |sub:
fork, kernel machinery (compress → decompress) still works on the same
session; the uncorroborated control still forks.

Scenario B pins the fork contract: a fork with context COPIES the
parent's state — inherited blocks (ids + summaries + originals, child
decompress round-trip), seeded raw→ref map equal to the parent's, the
durable-guard lane adoptable (null wire refs, BLOCKED never in byRef),
parent untouched.

A/B teeth: pre-ranxianglei#2719 master mints the fork (scenario A red); master
without ranxianglei#2625 fails scenario B with 409 raw/ref mapping inconsistent —
the ranxianglei#2676 silent degrade.
@ranxianglei
ranxianglei deleted the 2026-10-10_protected-tools-snapshot branch October 15, 2026 05:33
resec added a commit to resec/billion-context that referenced this pull request Nov 18, 2026
…itter shape (ranxianglei#7153)

The ranxianglei#7153 carrier gates require the complete <system-reminder> frame around the
workspace-instructions label, but two runtime fixtures still carried the bare
label, so their guard message stopped classifying as durable/agents-md and was
no longer pinned: the wire handed out a real ref where null was asserted.

- tests/plugin-fork.test.ts (ranxianglei#2676): the durable-guard history row now carries
  the frame dsh-agent-instructions emits.
- tests/session-continuity-proof.test.ts (ranxianglei#629/ranxianglei#2620/ranxianglei#2625/ranxianglei#2676): GUARD_TEXT
  likewise; the scenario-B fork-copy assertions are unchanged.

CI was red on the one assertion in each file (ubuntu 22/3, ubuntu 24/3,
windows 22/1, windows 22/4).
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.

[Bug][plugin] protectedTools 的 BLOCKED 映射导致纯文本 snapshot 返回 409

1 participant