Skip to content

[PR] fix: isolate ZCode project_memory_extract onto a per-run child compression lane (#4952) - #4965

Closed
ranxianglei wants to merge 8 commits into
masterfrom
2026-10-27_zcode-memory-extract-split
Closed

ranxianglei wants to merge 8 commits into
masterfrom
2026-10-27_zcode-memory-extract-split

Conversation

@ranxianglei

@ranxianglei ranxianglei commented Oct 27, 2026 •

Copy link
Copy Markdown
Owner

(ai: vllm-qwen/qwen3.8-27b)

是什么问题

ZCode 后台的 project_memory_extract 记忆抽取循环复用父会话 id(x-session-id)却往自己的历史快照里追加临时工具消息。billion 把两个分支都 key 到同一个可变压缩会话上——主会话恢复时没有这些 worker-only 消息,worker 的压缩块就成了孤儿被 reap(#4952)。

什么原因导致的

身份绑定层的缺口:src/session-id.ts 只有 dsh persona / claude subagent / codex turn / instructions fingerprint 四条分裂谓词,没有任何一条认 ZCode 的显式归因头。ZCode worker 骑在父 x-session-id 上落回父原始 key,和主会话共享同一份 usage 基线 / 消息快照 / ref 分配 / orphan 清理计数器。根因是「可变状态共享」,reap 只是它的一个症状(不是去修 reap 本身)。

影响范围与严重程度

仅当 ZCode 发出带 x-zcode-query-source=project_memory_extract + x-query-id + 父 x-session-id 归因头的后台抽取请求时触发。本次事故只丢了 worker-local 块、主历史无损、缓存很快恢复(47%→87%→97%)→ 定为 p2。但机制面与 #4769(Claude subagent 反向 orphan-reap,p1)同属「辅助循环共享主身份」失败域——本 PR 只处理 ZCode 这一条 wire(OpenAI-compatible + 显式归因),不碰 #4769 的 Anthropic system-text 路径。

怎么修复的

把 worker 分裂到一个稳定的按运行子 key <parent>|zmem:<query-id>:

一个已钉进回归测试的设计前提:x-query-id 在一次抽取运行内稳定、跨运行不同(见 issue 里向 reporter 确认的开放项)。若真实 ZCode 行为改成每模型调用铸新 query-id,child key 会按请求碎片化——此时每个 worker 回合各占一个极小子车道,不再共享状态(比现状 bug 安全),只是失去 run 内 fold 复用。优雅降级,不破坏正确性。

是否有回归问题

审过的既有行为逐项:①非 ZCode 客户端(dsh/opencode/pi/codex/claude)——新谓词对它们恒返回 undefined,零改动;②ZCode 主对话(无 project_memory_extract 归因头)——保持父原始 key,不变;③#388 side-request passthrough——判定顺序在 getSession 之后,行为不变,且被显式归因有意压过(见上);④upstream affinity——不变(child key 不上线);⑤personaNamespace / split-canary——child key 无 |sub: 子串且 stamp personaNamespace=true,双重安全,不误报 drift。定向测试 52/52 绿(新套件 11 + dsh-persona-fingerprint / subagent-namespace / fork-side-request-lane / side-lane-truth-table / side-lane-invariants),typecheck 干净,基于当前 master rebase 后复验通过。

是否破坏缓存

否。转发给模型的 x-session-id 仍是父原始值,前缀缓存亲和连续;worker 块落在自己的子会话,不再污染主会话的缓存基线(这正是本 PR 要消除的副作用)。

是否改了设计方向

否。沿用既有 copy-on-fork / persona-fork 机制(KDD#9),只新增一条 ZCode 专属窄谓词 + 一个与既有 |sub: 并列的 |zmem: 命名空间。无架构转向。

是否引入了新的配置

否(config surface):无新 env、无新 config 字段、无 CLI flag。分裂完全由请求头驱动,符合 env-var discipline(#2030)——不需要任何旋钮。


Kernel boundary:无 kernel/** 改动(kernel-guard 不触发)。
Review tier:人工审核——触碰 session-binding / message-ref 逻辑(§7.4,不可 auto-merge)。
Local test:仅跑定向测试(§7.2 本地测试纪律),全量回归交给 CI test 车道;pushed head = 3f833f6d9,base = master c499b1450。

Closes #4952

…ssion lane (#4952)

ZCode's background project_memory_extract loop reuses the parent conversation id (x-session-id) while appending worker-only tool messages, so both branches landed on one mutable compression session. When the main conversation resumed without the worker-only messages, the worker's blocks were orphaned and reaped.

Split the worker onto a stable per-run child key derived from its explicit attribution (x-zcode-query-source=project_memory_extract + x-query-id): each extraction run gets an isolated lane while the raw parent key stays owned by the main session and upstream cache affinity is unchanged. The child adopts the parent's refs/blocks via copy-on-fork at birth (read-only lineage, no ongoing mutable sharing). Detection is explicit-attribution-only - it never classifies arbitrary requests or inspects prompt wording.
@ranxianglei ranxianglei changed the title fix: isolate ZCode project_memory_extract onto a per-run child compression lane (#4952) [PR] fix: isolate ZCode project_memory_extract onto a per-run child compression lane (#4952) Oct 27, 2026
@github-actions

github-actions Bot commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-27_zcode-memory-extract-split (aa0c8d6)

Latest build — install this exact version

npm install -g billion-context@0.0.7369-pr.4965.4185653

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

Recent builds (commit → version)

commit version build
aa0c8d6 billion-context@0.0.7369-pr.4965.4185653 build
2eb22eb billion-context@0.0.7077-pr.4965.2a8348a build
fbdcad7 billion-context@0.0.7027-pr.4965.2c9af84 build
5fec236 billion-context@0.0.6875-pr.4965.09455c1 build
c0a7b34 billion-context@0.0.6547-pr.4965.2161cb3 build
985df8f billion-context@0.0.6494-pr.4965.c3f8992 build
3f833f6 billion-context@0.0.6476-pr.4965.1cb5a90 build

Download artifact

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

Install instructions are refreshed on each push.

@ranxianglei ranxianglei added bug Something isn't working p2 scope/wiring zcode 改动范围:内核之外的主机侧接线(src/agent 适配器、server 路由、注入拦截)/范围兜底/客户端标签 labels Oct 27, 2026
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

PR #4965 审核结论(八问)

审核独立性:以下结论由我独立通读全 diff(3 文件 +415/-3)并逐路径核对代码得出;PR 正文仅作需求背景,未照抄其结论。

1. 是什么问题:ZCode 后台记忆抽取 worker 复用父会话 x-session-id,却往自己的历史快照里追加临时工具消息;bili 把两个分支 key 到同一个可变压缩会话上,主会话恢复时没有这些临时消息,worker 的压缩块成了孤儿被 reap(#4952)。

2. 什么原因导致的:身份绑定层缺口——既有分裂谓词不认 ZCode 的显式归因头,worker 落回父原始 key,与主会话共享 usage 基线 / 消息快照 / ref 分配 / orphan 计数器。根因 = 可变状态共享,reap 只是症状。修复方向(分裂到独立车道)打的是根因。✓

3. 影响范围与严重程度:仅当三个归因头同时具备(x-zcode-query-source=project_memory_extract + 非空 x-query-id + 客户端提供的父 id)才触发;其他客户端与 ZCode 主对话零改动。p2 定级成立(本次只丢 worker-local 块、主历史无损、缓存快速恢复)。

4. 怎么修复的(逐项核实):

  • 谓词 zcodeMemoryExtractChildKey(src/session-id.ts):source 值精确匹配且大小写敏感、string-only(array 形态拒绝)、OWS trim、三要素缺一 → undefined(保持现状)。✓
  • 覆盖位置(handle.ts L1189-1193):在 base 解析完成之后,且仅当 base 确实落在声明父上才覆盖——更强信号(plugin-conversation / claude-sub / codex-turn)永不被压。✓
  • 按运行稳定:key = f(parent, queryId),同 run 同一子 key、不同 run 独立;单测钉住。✓
  • copy-on-fork 收养:derivedParent = 声明父 → 走既有 Claude 上 resume 导致消息错乱 #1486 findResumeParentWithin 继承 + [pi plugin] Prime RLM inline 派生子会话在代理模式下零继承:搜不到也解压不了父会话压缩块(billion-context-pi#531 同场景) #1333 derivedFrom lineage link(decompress/search_context 沿父链回退),机制均为既有。✓
  • 上游亲和不变:affinityToken 仅转发 clientProvided 值,fallback 取 raw clientConv;e2e 实测上游从未见 child key、父原始 x-session-id 持续流转。✓
  • conversations map 纪律:fork 记录在子 key 下(L1612 personaForked 分支),父原始 key 仍归主会话。✓
  • canary 防误报双重安全:child key 无 |sub: 子串 + 各 wire 分裂必 stamp personaNamespace=true(逐 wire 核过 rawPersonaIdentity 表达式)→ splitSessionWarnings 不会误报。✓
  • plugin.ts 的 |sub: lineage-follow 逻辑正确不含 |zmem: 车道:那些路由的是宿主 stamped 的插件管理调用,proxy-mode worker 绝不应吸收。✓
  • anonAffinity 无冲突:zcodeMemSplit ⇒ clientProvided ⇒ 匿名亲和分支不可达。✓

5. 是否有回归问题:逐项清点既有行为——①非 ZCode 客户端谓词恒 undefined,零改动;②ZCode 主对话(无归因头)保持父原始 key;③#388 side-request 判定顺序不变(getSession 之后),其 body-shape 启发式被显式归因有意压过——注意:side 形态的带归因子调用会分裂到子车道(然后在那里 verbatim passthrough),test 3 钉住的正是这一点,与正文八问③一致;原「怎么修复的」一节写「side request 不分裂」与代码/测试事实矛盾,我已直接修正 PR 正文该句(PATCH 已生效,披露于此);④上游亲和不变;⑤无阈值/时序/输出格式漂移;⑥无 kernel/ 改动。未发现无意回归。

6. 是否破坏缓存:否。转发给模型的 x-session-id 仍是父原始值(e2e 断言);worker 块落自己子会话,不再污染主会话缓存基线——这正是本 PR 要消除的副作用。

7. 是否改了设计方向:否。沿用 KDD#9 copy-on-fork / persona-fork 机制,新增一条窄谓词 + 一个与 |sub: 并列的 |zmem: 命名空间。

8. 是否引入了新的配置:无。完全头驱动,不加 env/config/CLI 面(符合 #2030)。

测试有效性:断言有牙——核心回归钉是「worker 回合后主会话 stats.requests 与 byRaw ref 集合前后逐字相等」(直接否定 reap 前提);另有负向/边界行(大小写、空 qid、缺父 id、array 形态、trim)+ e2e 对照(非归因保持原 key;归因压过 #388 启发式)。可接受缺口:copy-on-fork 收养(块继承)与 derivedFrom link 未在本套件直接断言(rig 历史太小触发不了压缩;两机制均既有且有各自覆盖)。

CI:head 3f833f6d9 = 53 checks:37 success / 15 skipped / 1 failure(test windows-latest, 22, 1)。job 日志分类:两条失败均为 flake 签名(dsh-native #1365 cancelledByParent/event-loop-pending = #4599 floor 284 在档;codex-mcp-shell report-file 为空 = Windows spawn 形态、与本 diff 零交集);master c499b1450 自身 73 checks 全绿 → 非继承红。已触发 failed-job rerun(run 40502378553,HTTP 201),并已在 #4599 留一行记录。

判定:代码与行为审核通过、无回归、测试有牙;CI 红已定性为 flake 并重跑中。rerun 转绿后即可合并(合并动作留给人工)。

@ranxianglei

Copy link
Copy Markdown
Owner Author

(ai: vllm-qwen/qwen3.8-27b) Merge-guard sync done: merged master @ 7f2e119 into this branch — clean, no conflicts (handle.ts changes from both sides touch disjoint regions); new head 985df8f, PR is now up-to-date with master (no longer behind); CI re-running on the new head with all guard gates green so far.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Merge-guard 同步完成:master @ 7f2e119(领先 27 提交)已合入本 PR 分支,零冲突(两侧唯一重叠文件 src/server/handle.ts 改动区域不相交),新 head 985df8f 已推送。API 验证 mergeable=MERGEABLE,状态由 behind 转为仅等 CI;新 head 上全部 guard 门禁已绿,test 分片运行中。详见 #issuecomment-6444807622。无需设计决策,未开 decision-request issue。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 这条是上面 merge-guard 同步评论的上游回同步(同一条消息),无新指令、无需操作。当前状态不变:head 985df8f,仅等 CI test 分片跑完。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Merge-guard 二次同步完成:master @ 9b6ec23(#4904 dsh direct-window guard + #4980 版本 0.1.208)零冲突合入,新 head c0a7b34 已推送;mergeable=True,状态仅等 CI(blocked,不再 behind)。上一 head 985df8f 全量 test 分片已全绿。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷
🔶 需要决策
(ai: vllm-qwen/qwen3.8-27b)

Why I stopped instead of resolving the conflict

The merge conflict in src/server/handle.ts is not a mechanical conflict — it is two competing fixes for the same issue #4952 that landed independently on master and on this branch. Resolving it requires choosing which mechanism wins. I have not pushed anything; the branch is clean at its original head aa0c8d607c.

What I found

Why a mechanical merge is wrong here
The only textual conflict is the conversation declaration in src/server/handle.ts (PR: let conversation = protocol === "google"…; master: adds zcodeParentIdentity + the #5719/#5825 msgid machinery + const conversation = zcodeMemory !== undefined ? zcodeMemory : …). Keeping master's block and flipping const→let compiles, but:

  • it leaves the PR's |zmem: mechanism as dead code — the PR's split guard conversation === zcodeMem.parent is always false whenever master's zcodeMemory is set (which is the primary project_memory_extract case), so the PR's child lane never fires;
  • it breaks the PR's own regression test tests/zcode-memory-extract-lane.test.ts (asserts the worker mints <parent>|zmem:<qid>), while master's tests/zcode-memory-isolation.test.ts asserts <parent>|aux:zcode-memory:<query> — two tests, same request, different expected keys.

So the branch cannot merge cleanly without a decision on which key scheme / detection wins.

Options

  • A (recommended): master's mechanism wins; PR superseded. Keep zcodeMemoryConversation → |aux:zcode-memory: (already merged + shipped, uses the established |aux: aux-lane convention). Drop the PR's competing |zmem: mechanism and its test. Net effect: PR [PR] fix: isolate ZCode project_memory_extract onto a per-run child compression lane (#4952) #4965 has no unique contribution → close as superseded by aa479bc210. If the PR's looser detection (not requiring x-zcode-session-type==other) has real value, file a small follow-up to fold that condition into master's zcodeMemoryConversation.
  • B: PR's mechanism wins; revert master's. Keep zcodeMemoryExtractChildKey → |zmem:, revert aa479bc210 from master. Cost: reverting an already-shipped fix is riskier; |zmem: is a non-standard namespace vs the |aux: convention.
  • C: reconcile into one. Merge the two into a single detection + key scheme (e.g. master's |aux:zcode-memory: key with the PR's broader detection). Best of both, but needs design + test work.

Recommendation

Option A. Master's fix is already merged and is the canonical, shipped solution; it uses the established |aux: aux-lane convention. The PR is a parallel effort that simply didn't know master's fix had landed. Keeping two competing key schemes for the same lane is a latent bug.

Default if undecided

If no decision is made, my default is Option A: resolve the merge keeping master's |aux:zcode-memory: mechanism (the already-shipped canonical one), drop the PR's now-dead |zmem: mechanism + its test so the branch merges with no dead code and no broken tests, and leave the PR open for you to close as superseded (I can't close it — owner-only). I will not unilaterally keep the PR's competing mechanism.

Please pick A / B / C (or direct a different path); I'll apply the chosen resolution and re-run the merge once you decide.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[ework] auto-fix stalled: test (windows-latest, 22, 3), test (ubuntu-latest, 22, 2), test (ubuntu-latest, 24, 2) — stopping for human review

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷
Status after the restart — the work is already complete, nothing to redo:

No code changes pushed — I'm holding for your A/B/C decision (A recommended: master's mechanism wins, PR superseded). Once you pick, I'll apply the resolution and re-run the merge.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[ework] auto-fix stalled: test (windows-latest, 22, 3), test (ubuntu-latest, 22, 2), test (ubuntu-latest, 24, 2) — stopping for human review

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷
(ai: vllm-qwen/qwen3.8-27b)

Re-verified live this run — the situation is unchanged and still blocked on your A/B/C call (full options at the 🔶 需要决策 comment, floor 62). Posting a current verdict so the thread isn't left quiet.

What I checked this run

So the conflict is exactly as before — two independent #4952 fixes (master's |aux:zcode-memory: vs this PR's |zmem:) colliding on the conversation declaration in src/server/handle.ts. It is a design decision, not a mechanical merge: taking either side leaves the other's mechanism as dead code and breaks that side's regression test (the PR's tests/zcode-memory-extract-lane.test.ts asserts |zmem:, master's tests/zcode-memory-isolation.test.ts asserts |aux:zcode-memory: — same request, two keys).

State

  • Nothing pushed; branch clean at its original head aa0c8d607c.
  • needs-decision label applied.
  • CI auto-fix lane hit its limit (floors 66-67) — this is fully on your decision now.

Holding for your pick — A (recommended: master's |aux:zcode-memory: wins, PR superseded → close), B (PR's |zmem: wins, revert master's aa479bc210), or C (reconcile into one). Once you decide I'll apply the resolution and re-run the merge in one pass. I will not unilaterally drop the PR's mechanism.


八问(中文,供人工审核)

  1. 是什么问题:PR [PR] fix: isolate ZCode project_memory_extract onto a per-run child compression lane (#4952) #4965 与 master 冲突(dirty);冲突本质是同一 issue ZCode project_memory_extract shares main compression state and causes orphan-reap on resume #4952 的两套独立修复(master 的 |aux:zcode-memory: vs 本 PR 的 |zmem:)在 src/server/handle.ts 的 conversation 声明处相撞。
  2. 什么原因导致的:PR 分支在 master 的 ZCode project_memory_extract shares main compression state and causes orphan-reap on resume #4952 修复(aa479bc210)之前分叉,master 此后前进数百提交,两套修复直到本次 merge 才正面冲突(非本 PR 引入的回归)。
  3. 影响范围与严重程度:仅 ZCode project_memory_extract worker 的会话 key 命名空间;两套 key 并存 = 同一请求两个 key 的潜在 bug。当前 PR 处于 dirty 无法合并(阻塞合入,非线上事故)。
  4. 怎么修复的:本轮未改代码——定性为设计决策,floor 62 已列 A/B/C 选项并打 needs-decision 标签,等 owner 拍板。
  5. 是否有回归问题:无(本轮无代码改动);master 前进的 5 个提交不触碰 zcode memory 代码,不影响本冲突。
  6. 是否破坏缓存:不涉及(无代码改动)。
  7. 是否改了设计方向:不涉及(无代码改动)。
  8. 是否引入了新的配置:不涉及。

判定:本轮为状态复核 + 决策等待,无代码改动、无 push;冲突为设计决策,等 owner A/B/C 拍板后一次完成。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[ework] auto-fix stalled: test (windows-latest, 22, 3), test (ubuntu-latest, 22, 2), test (ubuntu-latest, 24, 2) — stopping for human review

1 similar comment
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[ework] auto-fix stalled: test (windows-latest, 22, 3), test (ubuntu-latest, 22, 2), test (ubuntu-latest, 24, 2) — stopping for human review

@ranxianglei

Copy link
Copy Markdown
Owner Author

Closing: the fix landed on master as aa479bc "fix(zcode): isolate project memory extraction sessions (#4952)" (x-zcode-query-source guard in src/session-id.ts:107 + tests/zcode-memory-isolation.test.ts).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working needs-decision p2 scope/wiring zcode 改动范围:内核之外的主机侧接线(src/agent 适配器、server 路由、注入拦截)/范围兜底/客户端标签

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant