Skip to content

feat(#2408): declare claude --fork-session lineage for scoped resume inheritance - #2409

Merged
ranxianglei merged 2 commits into
masterfrom
2026-10-08_claude-fork-lineage
Oct 8, 2026
Merged

ranxianglei merged 2 commits into
masterfrom
2026-10-08_claude-fork-lineage

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Closes #2408

What

claude --resume <parent> --fork-session mints a FRESH session id while replaying the parent's wire history. Master's #1486 already covers byte-exact replay-forks via the UNSCOPED content scan, but the survey in #2408 showed the remaining gap: no explicit declaration, so a duplicate same-content chain elsewhere wins the tie (most-recently-seen) and mis-links the fork.

This PR adds the lineage-only declaration lane from the #2408 survey (option "hook declares, server scopes"):

Why not the other lanes

Survey result (#2408): kimi/zcode are anonymous (no conversation header — register can never bind, the #629 anonymous content net already covers them); hermes has a seam but no parent signal in its context (no key to read — not inventing one); codex reuses the same id on resume (nothing to adopt). claude was the only actionable lane.

Tests

tests/claude-fork-lineage.test.ts (6 tests): argv parse matrix, parent-sticky register merge, findResumeParentWithin matrix, and three end-to-end runs through the real server (startServer port 0, mock upstream): declared fork inherits parent refs+block+lineage on the first request; declared parent BEATS a same-content interloper chain (the scoping win); non-matching replay links read-only with zero state copied. Regression families all green: resume-ref-inheritance, issue1333-derived-inheritance, plugin-native-binding, resume-adoption-wires, plugin-fork, prefix-affinity, dsh-persona-fingerprint, claude-subagent-split, opencode-acp-command, subagent-sessions, fork-adoption family (430+ tests across batches; only environmental port-occupancy failures on this machine, live bili lane holds 18787).

typecheck ✅

@github-actions

github-actions Bot commented Oct 8, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-08_claude-fork-lineage (828da1e)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.2617-pr.2409.16ab1fa

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-pr2409.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 规范审查本 PR(方向关 → 回归关 → 代码关 → 测试关 → diff 整洁度)。初查:单 commit、基于 96be7a6,master 已前进到 51a4eee(落后若干提交),会先核对与现 master 的冲突面,再逐项过。完整八问结论稍后回复。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Review 结论(结构化八问)

① 是什么问题:#1486 的 unscoped content scan 已覆盖 byte-exact replay-fork,但留了个歧义缺口——同 proxy 内存在多条相同内容链时,tie-break 取「最近见过」,fork 会被误挂到 interloper 链上。本 PR 为 claude --resume <parent> --fork-session 加 lineage-only declaration lane:SessionStart hook(source:"fork")从 argv 解析 parent,register parentConversationId;server 把 #1486 match scope 到声明 parent 的单条链,hit 继承 refs/blocks/lineage,miss 回退 #1333 read-only link。

② 什么原因导致的:根因是声明信号缺失,不是匹配算法缺陷——没有显式 lineage 时,unscoped scan 无法在多条同内容候选间消歧,findResumeParent 的 tie-break(最深→最近见)只能盲选。修法方向(hook declares, server scopes)打到了 producer:歧义的产生者是「无声明」,修在声明侧而非 matcher 侧,符合疏不堵原则。

③ 影响范围与严重程度:目标场景是 claude fork + 同 proxy 多同内容链(现状会误链)。⚠️ 但 review 发现阻断性缺陷:该功能在生产路径上实际是死的(详见⑤),严重度 = 新功能主路径不工作;对既有行为零回归。

④ 怎么修复的:三层机制——(a) hook 层:claudeForkParentFromArgv UUID-tight 解析三种拼法(--resume <u>/--resume=<u>/-r <u>),best-effort POST; (b) register 层:parent sticky——不带 parent 的 re-register(MCP shim)不清除声明,显式新 parent 可更新,self-parent 入口拒收; (c) server 层:#1486 match 移到 #1333 link 之前,有声明走 findResumeParentWithin(单链变体,规则与原版逐条一致:strictly deeper、≥MIN_RESUME_PREFIX=8、head-anchored tailHash),hit → 富继承 + 跳过冗余 link,miss → link 同一首个请求落地,无 deferral。keying 已验证正确:identified client 的 sessionId === conversation verbatim(server.ts:2155),trackedChains 以同一 key note(server.ts:2290),且 #499 snapshot 跨重启保留。

⑤ 是否回归问题:逐项审过,既有行为无破坏——

⑥ 是否破坏缓存:不涉及。prefix-cache 相关路径(system message 字节、稳定前缀)未动;继承只 seed refs/blocks 元数据,wire shape 不变。

⑦ 是否改了设计方向:未转向。不动 §8 full fork protocol,平行加一条更弱的 declaration lane(PLUGIN.md §8 段落写清了边界:无 dead-ref namespace / 无 nudge inheritance / 无 receipt verification);kimi/zcode/hermes/codex 按 #2408 survey 结论明确不收,理由成立。

⑧ 是否引入新配置:无。复用既有 /__bili/plugin/register endpoint 与 postIdentityRegister,无新 env/config/CLI 面。

其他审查项:

  • diff 整洁度 ✅:6 文件全部与本 PR 目的相关,无无关改动、无 lockfile churn、version 未动、kernel/ 未动。
  • 测试质量:断言有牙(refs 逐条相等、block adoption、interloper 优先权、零拷贝回退);缺的正是 entrypoint 级 stdin 回归测试——即阻断缺陷漏网的原因。
  • CI:26/28 绿(ubuntu 全 shard + 全部 e2e lane + kernel/pi-subagents/version guard),剩 2 个 windows test shard 在跑。
  • 分支状态:base 落后 master 3 提交(master 侧 a0952c9/a77eb28b9 动了 src/server.ts 的另一区域,无文本冲突,mergeable=true);合并前建议 rebase 到最新 master 并重跑定向回归族。

判定:拦下(blocked)。server 侧机制(scoped match / stickiness / 排序)审毕正确,但 hook 侧声明因 stdin 时序 bug 整体失效,功能主路径不工作,不能按现状合并。修法最小(drain stdin + entrypoint 回归测试),owner 拍板后继续(回复「继续」即可推进修复)。

ework-agent added 2 commits October 8, 2026 21:38
…inheritance

claude --resume <parent> --fork-session mints a fresh session id and
replays the parent's wire history. The SessionStart hook now parses the
parent off the claude host argv (UUID-tight) and posts an identity
register with parentConversationId; the parent declaration is sticky
across parent-less re-registers (MCP shim). The server scopes the #1486
resume-inheritance content match to the declared parent's chain
(findResumeParentWithin) — disambiguating duplicate replayed content —
and runs the match BEFORE the #1333 link so a hit takes the richer
refs/blocks inheritance while a miss links read-only on the same first
request (pi RLM timing unchanged). kimi/zcode (anonymous) and hermes
(no parent signal) stay as-is per the survey in #2408.
hookMain() called run(payload) synchronously while Node only emits 'data'
asynchronously, so declareForkLineage always received an empty string —
the lineage declaration never fired on the real wire. Rework to
hookMainWithDeps(): collect chunks, fire once on 'end'/'error' or a
HOOK_STDIN_DRAIN_TIMEOUT_MS (2s) safety net, then run the full payload.
Pinned by three regression tests (partial chunks, never-closed stdin,
empty stdin); verified against a real claude --resume <uuid>
--fork-session run declaring parent 6e772aa4.
@ranxianglei
ranxianglei force-pushed the 2026-10-08_claude-fork-lineage branch from c1e950e to 828da1e Compare October 8, 2026 13:54
@ranxianglei

Copy link
Copy Markdown
Owner Author

Fixed in 828da1e (branch rebased onto master 51a4eee first).

Root cause — exactly as reviewed: hookMain() invoked run(payload) synchronously while Node only emits stream 'data' events on a later tick, so the payload string was still empty at call time; every test injected the payload directly (fake stdin still delivered the string synchronously), which is how the seam slipped through. The observation that declareForkLineage could only ever see "" on the real wire was correct — the declaration never fired outside unit tests.

Fix: new hookMainWithDeps({input, runImpl, exit, drainTimeoutMs}) — chunks are collected with a single-fire guard (started), the bootstrap runs once on the earlier of stdin 'end'/'error' or HOOK_STDIN_DRAIN_TIMEOUT_MS = 2_000 (safety net for hosts that never close the pipe), then runImpl(fullPayload).finally(destroyInput + exit(0)). hookMain() is now a thin binding. setEncoding is only called when present.

Regression pins (3 new tests, red on the old code):

  1. run receives the FULL payload only after drain — asserts runs.length === 0 immediately after calling, then feeds two partial chunks + end;
  2. never-closed stdin still fires via the timeout with the complete payload;
  3. empty stdin (immediate end) exits cleanly with runImpl("").

Real-binary verification (beyond the mocked seams): ran actual claude --resume <uuid> --fork-session -p with the SessionStart hook bound to the rebuilt dist — hook stderr printed fork session 634fabef declared parent 6e772aa4 (#2408), i.e. async drain → argv walk → parent extraction → identity register all fired on the production path. Probe environment and repinned settings were cleaned up afterwards.

Touched-family suite green (claude-fork-lineage 9/9, 1333/native-binding/resume-adoption/plugin-fork/prefix-affinity 94/94); typecheck clean. CI running on 828da1e.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Fix commit 828da1e 已核对(结构化八问)

① 是什么问题:上一轮阻断缺陷——hookMain() 在 Node 异步 stdin 事件到达前同步调用 run(payload),declareForkLineage 在生产路径上永远收到空串,lineage 声明从未发出。本轮验证修复是否打到了 producer。

② 什么原因导致的:根因是「读值时机」——accumulator 的读取发生在同步调用点而非 drain 完成点。修复没有改 payload 内容(堵),而是把读取点移到 drain 后(疏):hookMainWithDeps 里 start() 只在 'end'/'error'/超时三者之一触发时执行,此时才把完整 accumulator 传给 runImpl。方向正确。

③ 影响范围与严重程度:修复后主路径恢复——真实 claude --resume <uuid> --fork-session -p 探针(hook stderr 打出 fork session 634fabef declared parent 6e772aa4 (#2408))证明 async drain → argv walk → parent extraction → identity register 全链路在生产路径触发,日志格式与代码逐字一致。对非 fork 会话零影响(source !== "fork" 早退)。

④ 怎么修复的:机制三层核对过——(a) 单次触发:started 单飞 guard + clearTimeout(timer),end/error/timeout 竞态下恰好一次; (b) 安全网:HOOK_STDIN_DRAIN_TIMEOUT_MS = 2_000 兜住永不关管的 host(claude 等 hook 退出,挂死 = 卡 session start),timer 在调 runImpl 前已清,bootstrap 运行期间无悬挂 timer; (c) 生命周期不变:runImpl(fullyPayload).finally(destroyInput + exit(0)),与旧行为同形,non-fatal 语义保留。测试驱动的是真实 wiring(hookMainWithDeps + PassThrough 管道,生产时序:同步点断言 runs.length === 0,异步喂两个 partial chunk + end,断言恰一次且为完整 payload)——正是上一轮要求的 entrypoint 级回归钉,旧代码下必红。

⑤ 是否回归问题:逐项审过——

  • fix commit 只动 src/claude-native-bootstrap.ts + 测试文件;server/plugin/prefix-affinity 侧机制与上一轮审毕版本逐字节相同(rebase 未引入漂移),上轮结论全部继续成立。
  • 有意时序变更(披露):hook 启动从「立即起 bootstrap(不读 payload)」变为「等 stdin 'end'/'error' 后再起,最坏 2s 封顶」。实践延迟:claude 写完即关管,毫秒级;2s 仅出现在异常 host 永不关管的场景,且该场景旧行为是永久等待 run 完成、新行为反而更确定。判定:可接受,方向是收紧不确定性而非放松。
  • 新增导出 HOOK_STDIN_DRAIN_TIMEOUT_MS 无外部引用:已核 scripts/check-unused-exports.mjs——src/claude-native-bootstrap.ts 在 ENTRY_FILES 豁免集(line 27),gate 不会拦。可选微 nit(不挡合并):测试可引用该常量断言默认值(给导出一个用途),或去掉 export;留 owner 定。
  • master 漂移(PR base 51a4eee → HEAD a5e7af1,fix: exclude display-only plugins & separate suspected from confirmed conflicts (#2324) #2331):触碰 conflict-watch/thirdparty-scan/web/i18n + 2 个 web 测试,与本 PR 六文件零重叠,无语义交互;mergeable,GitHub 可直接合,可选 rebase 仅为整洁。

⑥ 是否破坏缓存:不涉及。wire shape、system 字节、prefix-cache 相关性均未变。

⑦ 是否改了设计方向:不涉及——修复完全落在本 PR 既定的 hook-declares/server-scopes 设计内,未扩大 lane 边界。

⑧ 是否引入新配置:无。HOOK_STDIN_DRAIN_TIMEOUT_MS 是硬编码内部常量(导出仅因文件属 entry 面),非 env/config/CLI 新面,无迁移。

CI:828da1eb3 上 28 job 已启动,目前 5 success、其余 queued/in_progress,无红。

判定:修复验证通过,可合——待 828da1e 的 CI 全绿即可由人工合并;唯一遗留是上述可选微 nit(常量导出的用途),不构成阻塞。

@ranxianglei
ranxianglei merged commit de338aa into master Oct 8, 2026
28 checks passed
@github-actions

github-actions Bot commented Oct 8, 2026

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.148-master.de338aa (rolling master tag).

npm install -g billion-context@0.0.148-master.de338aa  # 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.

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.

Fork adoption: survey + designs for the remaining lanes (claude, kimi, zcode, hermes; codex N/A)

1 participant