[ranxianglei]

Closes #4006

What

The three per-session lane watchdogs (zcode #1145, claude #1821, kimi #963) hardcoded WATCHDOG_INTERVAL_MS = 30000 / WATCHDOG_FAILURE_LIMIT = 3. After an externally killed lane proxy (e.g. ZCode's process-tree cleanup in #4006), recovery took up to ~90 s (64 s measured). This makes both values configurable through the canonical knob machinery (#2030):

knob	env var	config key	default
probe tick	BILI_WATCHDOG_INTERVAL_MS	watchdog.intervalMs	30000 (floor 1000)
consecutive failures before respawn	BILI_WATCHDOG_FAILURE_LIMIT	watchdog.failureLimit	3

This is option A from #4006 (做成可配置, labeled 最佳). All three lanes share the one knob pair — same mechanism family, single source of truth in src/knobs.ts (laneWatchdogIntervalMs / laneWatchdogFailureLimit).

Config surface (owner-gated area — reported per discipline)

• Added: one new top-level config block watchdog with two numeric fields + two BILI_* env twins.
• Why the existing surface cannot express it: the watchdog runs inside the client-spawned MCP entry processes (zcode/claude/kimi), not the proxy. No existing block covers lane-lifecycle cadence: network.* is upstream transport timing read by the proxy, update.* is the self-update cycle, guardrails is pi/omp tool output. No existing key reaches "how fast does an entry respawn a dead lane proxy".
• Mechanisms considered: (a) env-only reads in each entry (the shape sketched in the issue) — rejected as the sole carrier because env vars only reach the MCP child if the user's shell exports them before launching the client host; the file tier works regardless of spawn chain. knobs.ts gives both tiers with the canonical env > file > default precedence for zero extra machinery. (b) Per-lane keys (zcode.watchdogIntervalMs, …) — rejected: identical mechanism across lanes, tripled surface for no semantic difference.
• Compat/migration: purely additive. Defaults are byte-identical to the old constants (30000/3); nothing migrates. KNOWN_TOP_LEVEL_KEYS updated so the block does not trip the unknown-key warning.

Behavior-change disclosure

None by default: with no env/file setting, all three lanes behave exactly as before (30 s tick × 3 failures). New semantics are (a) users can now shorten the window (e.g. 5000/3 → ≤15 s worst case; 1000/1 → ~1 s), and (b) out-of-range input falls back to the default instead of being applied (interval < 1000 ms → 30000; failureLimit < 1 → 3) — a typo guard, documented in CONFIGURATION.md en/zh.

Tests

• tests/knobs-config-precedence.test.ts: full precedence matrix for both knobs (default / file tier / env-wins / garbage / floor).
• tests/zcode-mcp-entry.test.ts: a tick without injected failureLimit resolves the knob live from env.
• tests/claude-mcp-entry.test.ts: same for the tick, plus a real-timer test proving startWatchdog honors BILI_WATCHDOG_INTERVAL_MS (respawn within ~3 s at the floored interval; the default 30 s tick never fires inside the test window).
• typecheck clean; targeted suites green (50/50 across the three files); full-suite verdict = CI on the pushed head.

---

kernel/: the early version of this branch carried a mechanical lockfile sync (kernel/package-lock.json still recorded 0.0.159 while the in-repo kernel/package.json had been bumped to 0.0.160 by f7d5e86/#4292). That fix already landed on master via #4416 and this branch is now rebased onto it — the current head touches NO files under kernel/** (no source, no build config, no version field); kernel-guard is not triggered.

[github-actions]

📦 Built Package Artifact

Branch: 2026-10-23_watchdog-cadence-knob (d27c793)

Latest build — install this exact version

npm install -g billion-context@0.0.5307-pr.4366.bec71bc

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
d27c793	billion-context@0.0.5307-pr.4366.bec71bc	build
24d533b	billion-context@0.0.5297-pr.4366.8f428eb	build
45d9126	billion-context@0.0.5294-pr.4366.19297fa	build
1295a57	billion-context@0.0.5292-pr.4366.0e1d1ef	build
7bf78ac	billion-context@0.0.5289-pr.4366.abac415	build
4409d8b	billion-context@0.0.5278-pr.4366.150573d	build
86bb776	billion-context@0.0.5263-pr.4366.9ce1de7	build

Download artifact

1. Download the artifact from the Actions run
2. Extract the tarball and install:

tar xzf billion-context-pr4366.tgz
npm install -g package

---

Install instructions are refreshed on each push.

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

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

查重: 不重复 —— open+closed issue/PR 检索「watchdog / respawn cadence」无并行工作项；本 PR 是 #4006 方案 A（做成可配置）的唯一实现，且与 #4367/#4368/#4369（#4006 附带观察的立项）机制不同、互不重叠。

标签: zcode + claude + kimi + scope/wiring + p2（三条 lane 的 MCP entry 看门狗属客户端接入层；严重度与 #4006 自身 triage 一致——可用但有明显恢复延迟）。

这是本 daemon 此前在 #4006 交付的 PR，本次按 [PR] 唤醒做复核：已取回分支读完全部 diff（12 文件 +155/−17），正在把分支 rebase 到当前 master 后本地跑 typecheck + 定向测试，随后核对 pushed head 的 CI 状态并给八问结论。

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

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

查重：不重复（首轮回复已声明，此处不展开）。标签：pr / zcode / claude / kimi / scope/wiring / p2（已打，理由：功能 PR、三车道看门狗接线、非破坏性）。

Review 结论

独立审核：通读全部 diff（12 files +155/−17）。方向正确——#4006 选项 A（做成可配置）落地为 canonical knobs 机制（#2030），三车道共享一对 knob（同一机制族，单一事实源 src/knobs.ts），默认值与旧常量逐字节一致。merge-base fba2d13 之后 master 没有触碰过本 PR 的任何文件，无热文件竞争，rebase 干净。代码质量达标：knob 解析复用 tInt（env > file > default）、interval 在 startWatchdog arm 时读一次、failureLimit 每 tick 活读（免重启调参）、越界输入回退默认（interval <1000 → 30000 防秒/毫秒笔误；limit <1 → 3）；测试有牙（完整优先级矩阵 + zcode/claude tick 活读断言 + claude 真定时器证明 startWatchdog 尊重 env 节拍）。

发现的缺陷（已修）：原 head 9e1b7c8 的 CI 三个 guard job 红——config-surface-guard、lifecycle-ledger-guard、docs-sync。本地在 rebase 后的树上复现确认根因：不是 stale-base 漂移，而是文档登记缺失——CONFIGURATION.md/zh 是由 website/config-reference/*.yaml 生成的（#2107 drift guard A），PR 手改了生成产物却没更新 seed 源；两个新 env var 也没进 LIFECYCLE.md 常设面登记表（#3249）。已在 PR 分支补 3 个 commit（force-push 到 5e9adb0）：

• 7560f79 docs(#4006): process.yaml 加 watchdog 父对象 + watchdog.intervalMs/watchdog.failureLimit 两个 leaf seed（描述文案沿用 PR 表格原文移植进 desc_en/desc_zh）+ LIFECYCLE.md §2.9 登记两个 env；跑 gen-config-docs.mjs generate 提交再生成产物。EN 文档零 diff（证明 PR 手写行本就符合生成器格式），zh 仅 2 行默认值写法归一，site 字典 +2 行。
• 5e9adb0 style(#4006): 修复 knob 改动把 src/claude-mcp-entry.ts 头注释折行弄断留下孤行的问题（纯换行，文字未动）。

本地验证（定向，全绿）：config-surface-guard ✓ / lifecycle-ledger-guard ✓ / check-coverage ✓（181 env + 59 top-level keys）/ docs-sync 模拟（generate 后四产物零 diff）✓；typecheck 干净；三个目标测试文件 50/50 通过；build 成功且 knob 已内联进 dist 三条 lane 入口 bundle。

CI 状态：新 head 5e9adb0 的运行批次目前整体排队中（今日 runner 池拥塞，ci.yml 注释里提到的 "447-run queue incident" 就是今天的事）。三个原红 guard 我已在本地逐一复现转绿，预期 CI 无意外；跑完我会跟进确认并回帖。另观察到 force-push 瞬间产生一个 event=push 的零 job 失败 stub run（ci.yml 的 push 触发器并不匹配本分支，疑似瞬时触发伪影），未出现在 PR check 汇总里，持续观察。

结构化八问

1. 是什么问题：PR 代码本身没问题，但它的 CI 红了三个文档 guard——新增配置面没有按仓库纪律登记到单一事实源（config-doc YAML seed）和 LIFECYCLE 常设台账。
2. 什么原因导致的：CONFIGURATION.md 是生成物，PR 直接手改了产物而没改 website/config-reference/process.yaml 的 seed（drift guard 必然红）；同时 Stale Item Cleanup: Transitional Feature Flag Ledger + Decommissioned Module Inventory + Remote Branch Hygiene (suitable for ework) | 陈年件清理:过渡开关台账 + 退役模块盘点 + 远端分支卫生(适合 ework) #3249 要求每个 BILI_* env 必须在 LIFECYCLE.md §1/§2 留痕，两个新 env 漏登。与 base 新旧无关——rebase 后同样红。
3. 影响范围与严重程度：只挡 CI 绿和合并，不影响任何运行时行为；属流程性遗漏（p3 级），用户侧零感知。
4. 怎么修复的：补齐单一事实源——seed 进 YAML（父对象 + 两 leaf，含 site 卡片）、LIFECYCLE §2.9 登记、用官方生成器重跑并提交产物；顺带一个注释折行的 style 小修。
5. 是否有回归问题：无。默认值 30000/3 与旧硬编码常量逐字节一致，不设任何配置时三车道行为不变；唯一新增语义是越界输入回退默认的笔误防护；重生判定逻辑（zcode/kimi/claude 各自分支）未动。审过的既有行为：knobs 解析路径（复用 tInt，未改）、KNOWN_TOP_LEVEL_KEYS（纯追加）、三入口的看门狗语义（默认下等价）、生成文档管线（按既有格式走）。
6. 是否破坏缓存：不涉及（未触碰缓存/重试/游标逻辑）。
7. 是否改了设计方向：无。纯 additive 配置面，完全走既有 knobs 机制（env > file > default），三车道共享一对 knob 而非各配各的。
8. 是否引入了新的配置：是——watchdog.intervalMs（env BILI_WATCHDOG_INTERVAL_MS，默认 30000，floor 1000）+ watchdog.failureLimit（env BILI_WATCHDOG_FAILURE_LIMIT，默认 3）。配置面变更已在 PR body 按纪律完整报告（为何现有面表达不了、考虑过的替代方案、兼容性）；本次补齐了 YAML seed + LIFECYCLE 登记 + en/zh 文档 + site 卡片。

判定：CI 在新 head 5e9adb0 上转绿后即可合并（合并由人执行）。CI 结果出来我再跟一条。

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

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

上游 PR 冲突已解决 —— 本 PR（#4366，实现 issue #4006「把 zcode/claude/kimi 三条 lane 的看门狗节奏做成可配置」）已从旧 master rebase 到最新 master，现在可干净合并。

八问：

1. 是什么问题：PR 分支落后于持续前进的 master，系统报 merge_conflict(dirty)。任务是 rebase 回当前 master、消除冲突。这不是代码缺陷，是 base 漂移。

2. 什么原因导致的：纯 base 漂移——PR 基于较旧的 master，之后 master 又合入约 8 个提交（zcode MCP-dialect compress [Feedback] Noticed during testing that Zcode doesn't seem to trigger compression very often. | [反馈]在测试途中发现Zcode好像不怎么会触发压缩 #4344、output-reservation [PR] fix: reserve output headroom by route, not wire — caliber split (redo of reverted #4184) #4236、corrupt-index handle leak [PR] fix(storage): close the sqlite handle when quick_check throws on a corrupt header (#4357) #4358、closeall-linger [PR] fix(server): closeAllConnections() cuts through the post-response linger (#4380) #4384、CI concurrency [PR] fix(ci): drop the duplicate top-level concurrency block that invalidates ci.yml #4405 等）。因为本 PR 触碰的文件（src/knobs.ts、src/config.ts、src/zcode/mcp-entry.ts、src/claude-mcp-entry.ts、src/kimi/native-mcp.ts + 文档 + website）与 master 近期改动（src/server/*、src/compress-tool.ts、src/host-profiles.ts、ci.yml 及各自测试）文件集不相交，rebase 全程零文本冲突，无需手工解冲突。

3. 影响范围与严重程度：对用户行为无影响——rebase 本身不改任何代码语义，PR 内容逐字节一致（diff 仍是同一 16 文件 / +185 −19）。严重程度：无；本次只是恢复可合并性。

4. 怎么修复的：git rebase 把 3 个 PR commit 落到最新 master（a7e55cc86），确认 diff stat 与原 PR 完全一致；本地跑 typecheck（含 kernel/pi-subagents 构建，绿）+ 三个直接受影响测试文件（knobs-config-precedence / zcode-mcp-entry / claude-mcp-entry，50/50 通过）；再 git push --force-with-lease 推回 origin/2026-10-23_watchdog-cadence-knob。另用 git merge-tree 非破坏性验证对最新 master 无冲突；GitHub 现回报 mergeable: true / mergeable_state: blocked（干净、仅待 CI，不再是 dirty/冲突）。

5. 是否有回归问题：rebase 未引入回归——除在更新的 base 上重放相同 patch 外没改任何源码行；已在 live-master 树上验证 typecheck 干净 + 定向测试全绿；master 近期提交不碰本 PR 文件，无交互。高危模式逐项过：无语义漂移、无阈值/时序/输出格式变化、无 fail-fast 变吞错（均不涉及——没动逻辑）。

6. 是否破坏缓存：不涉及（N/A）——未触碰缓存/重试/增量游标/去重键逻辑。

7. 是否改了设计方向：不涉及（N/A）——无架构/边界/数据流转向；同一功能，仅 rebase。

8. 是否引入了新的配置：本次动作不涉及——rebase 不新增任何东西。（附注：底层 PR In the ZCode environment, the proxy takes 64 seconds to recover after being terminated by an external signal — recommend | ZCode 环境下 proxy 被外部信号终止后需 64 秒才能恢复——建议将看门狗间隔改为可配置 #4006 本身新增 watchdog.intervalMs/watchdog.failureLimit 两个 config key 及 BILI_WATCHDOG_INTERVAL_MS/BILI_WATCHDOG_FAILURE_LIMIT env 孪生，默认 30000/3，已在 PR 描述按配置面纪律披露；rebase 不改变这些。）

收工判定：冲突已清除，可合并性已恢复；新 head 86bb77639 上 22 个 CI check 已排队/运行中（全量判定以远程 CI 为准），本地 typecheck + 定向测试已绿。CI 转绿后即可由你合并。

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

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

进度更新：又发现并修掉一个 master 自带的红灯（与 #4006 改动无关，但会卡住所有在途 PR），最终判定等本轮 CI 绿。

lock-sync 红灯根因：f7d5e86d8（#4292）把 in-repo kernel 版本 bump 到 0.0.160，但没有重新生成两个 lockfile，两边都还记着 0.0.159——

• package-lock.json 里的 kernel file:-link 条目；
• kernel/package-lock.json 自身（lock-sync 两个都查，见 [PR] kernel: sync package-lock.json to 0.0.136 (lock left at 0.0.133 by the bump chain) #3782 的注释，这个漂移模式历史上出过）。

已在 origin/master 本地复现确认是既有问题；出站查重：无既有 issue/PR。按几行级小修纪律直接在 PR 分支修掉：commit 45d9126 把两处记录同步到 0.0.160（纯机械同步，不碰任何 kernel 源码、构建配置或版本字段；Rule 2 版本纪律不受影响——无 src 变更、无版本变更）。

两个配套动作：

1. 触碰 kernel/** 触发 kernel-guard 规则 1，已在 PR body 末尾补 kernel-change: 声明（写明仅机械锁文件同步、host 侧 In the ZCode environment, the proxy takes 64 seconds to recover after being terminated by an external signal — recommend | ZCode 环境下 proxy 被外部信号终止后需 64 秒才能恢复——建议将看门狗间隔改为可配置 #4006 修复本身不碰 kernel/）——合入审核时请留意这一行。
2. 该声明写于上一次 push 之后，那轮 CI 读到的是旧 body 快照导致 kernel-guard 红；已推空提交 24d533b 带新 body 重跑。

提醒：在这个漂移修复合入之前，所有在途 PR 的 lock-sync 都会红（master 自身即此状态）。

等 24d533b 上 CI 全绿后给最终判定。

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

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

进度更新（接上条）：

• 分支已 rebase 到最新 master（a2d8cb9b2）。排查中发现 master 在 [PR] fix CI hygiene: root lockfile kernel 0.0.159→0.0.160 + 4 unused exports in corrupt-index-child #4416 / [PR] fix(#2155): keep the nudge/self-heal probe armed on headerless zombie rounds (zcode regression from #4372) #4423 里已经把我在分支上顺手修的那几处 CI 卫生问题合掉了（lockfile kernel 记录同步、corrupt-index-child 四个导出、LIVE_FILES 注册）——同一根因的修复已经在 master 落地，符合「一个根因一个修复」。
• rebase 自动丢弃了与我分支重复的三个 commit（unused-exports、双 lockfile 同步、空 re-trigger），现在分支 = 最新 master + 3 个 commit：feat watchdog knobs → docs（config 单一数据源 seed + LIFECYCLE 登记 + 重新生成的文档）→ style（注释换行）。diff 收敛到 16 个文件，全部是 In the ZCode environment, the proxy takes 64 seconds to recover after being terminated by an external signal — recommend | ZCode 环境下 proxy 被外部信号终止后需 64 秒才能恢复——建议将看门狗间隔改为可配置 #4006 功能本身，不再触碰 kernel/**、lockfile 或 scripts。
• PR 描述里的 kernel-change 段已改写为准确说明（早期版本带过的机械性 lockfile 同步已随 [PR] fix CI hygiene: root lockfile kernel 0.0.159→0.0.160 + 4 unused exports in corrupt-index-child #4416 进 master，当前 head 不碰任何 kernel/ 文件）。
• 本地验证全绿：config-surface-guard / lifecycle-ledger-guard / docs coverage / docs-sync 模拟均过；typecheck 干净；定向测试 50/50（knobs-config-precedence + zcode-mcp-entry + claude-mcp-entry）；build 成功且 knob 已内联进三个入口 bundle。

CI 正在新 head（d27c793af）上跑，全绿后我发最终结论（八问体例）。