Skip to content

fix(pi-subagents): reclaim idle delegate-notification hosts from the enumeration registry (#2390) - #2392

Merged
ranxianglei merged 1 commit into
2026-10-08_delegate-notify-boundaryfrom
2026-10-08_delegate-notify-host-reclaim
Oct 8, 2026
Merged

ranxianglei merged 1 commit into
2026-10-08_delegate-notify-boundaryfrom
2026-10-08_delegate-notify-host-reclaim

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Closes #2390

Stacked on #2389. Base is #2389's branch (2026-10-08_delegate-notify-boundary) because the registry this fixes (knownHosts / hostNotificationStates in pi-subagents/src/delegate-tool.ts) only exists there — it is not yet on master. Stacking keeps #2389 fully mergeable on its own (per "低优先级,不阻塞 PR #2389 合并") and keeps this diff isolated to one concern. After #2389 merges, rebase this onto master.

What / why

#2389 introduced per-host notification state keyed off the host: a WeakMap<ExtensionAPI, HostNotificationState> (weak keys — not a leak) plus a strong-ref Set<ExtensionAPI> knownHosts used so a target-less flushDelegateNotifications() can enumerate hosts. That set had no removal path, so every session's host was pinned forever in a long-lived process (TUI /new, RPC multi-session) — monotonic growth proportional to sessions created. No correctness impact (flushing a dead host is a no-op), purely memory.

Confirmed against #2389 head d07c13ab: exactly three knownHosts references — declaration, .add() inside the getter, and Array.from(knownHosts) for enumeration — and zero .delete()/.clear(). So the set could only grow.

Fix (a refinement of the issue's option 1)

The issue's option 1 proposed deleting from both tables plus refactoring every state access through the getter so handlers stop capturing st (to avoid queue split-brain). That full refactor is unnecessary here: the split-brain risk comes from deleting the state object, not from deleting the enumeration entry. So this fix prunes only the enumeration set and never touches the WeakMap state:

  • pruneKnownHostIfIdle(pi) drops a host from knownHosts only when it is fully idle — activeRuns === 0 && queue.length === 0 && !flushScheduled. It reads the state map directly (not the creating getter, whose re-add would undo the delete).
  • The getter now re-adds the host on every access (moved knownHosts.add(pi) out of the if(!st) block), so a pruned-idle host rejoins enumeration the instant it is touched again — a later target-less flush cannot miss its pending delivery.
  • Prune is called after the settle handler and inside the idle-flush macrotask. Because maybeFlush sets flushScheduled=true synchronously on settle, the effective prune is the one in the timeout callback (next macrotask, after the flush drains the queue).

Since the per-host state object lives as long as the host does (WeakMap) and is never recreated, a handler that captured it at registration can never desync — the safety goal of option 1 is met without the getter-indirection rewrite, for less churn and lower regression risk.

Behavior change (flagged)

  • Cleanup timing: knownHosts entries went from never removed to removed once the host is idle (one macrotask after its settle/flush). A host re-registers on next access. No change to what is delivered or when — delivery still goes through the same settle/context/idle tiers, and the global findUndeliveredRuns recovery is unchanged and host-agnostic.

New surface

  • One new internal export knownDelegateHostCount(): number — a test/diagnostic hook asserting the boundedness guarantee. Not user-facing, not a config field. No config/env/CLI surface added.

Component version

pi-subagents/package.json bumped 0.1.3 → 0.1.4 (Pi-Subagents Boundary rule 1: any src/ change must bump the component version; CI pi-subagents-guard enforces it). Root package.json untouched.

Tests

  • New deterministic regression suite pi-subagents/tests/delegate-host-reclaim.test.ts (no --expose-gc needed): asserts the registry count returns to baseline after N idle hosts settle (fails on the pre-fix no-prune code), a pruned host rejoins enumeration on access and still delivers, plus per-host isolation and target-less enumeration regression guards.
  • Local: tsc --noEmit clean; targeted notification-path tests green (delegate-host-reclaim / delegate-settle-notify / delegate-context-notify / delegate-tool — 114 pass, 0 fail). Full suite + e2e left to CI.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 已核对 PR #2392 分支(2026-10-08_delegate-notify-host-reclaim @ 657479e1d,base = #2389 分支 d07c13ab)。代码与描述一致,机制正确,回归测试有牙。结论:可合(待 #2389 合并后 rebase 到 master 跑满核心 CI)。

结构化八问:

  1. 是什么问题:fix(pi-subagents): commit delegate completion notifications at the model's next safe boundary (#2320) #2389 引入的 knownHosts(强引用 Set,供无目标 flushDelegateNotifications() 枚举宿主)只有 .add()、没有任何移除路径——长驻进程(TUI /new、RPC 多会话)里每个退役会话的宿主对象被永久钉住,内存随创建过的会话数单调增长。纯内存问题,无正确性影响。
  2. 什么原因导致的:JS 没有可迭代的弱集合,枚举注册表被迫用强引用;原注释假设「一个进程只有一个活宿主」所以不会无界增长,但该前提在 TUI /new / RPC 多会话下不成立。已在 base d07c13ab 上核实:恰好 3 处引用(声明、getter 内 add、Array.from),零 delete/clear。
  3. 影响范围与严重程度:仅长驻多会话进程的内存占用;触发条件 = 同一进程内反复创建会话;严重度为泄漏级(缓慢增长),无功能/正确性影响。
  4. 怎么修复的:只修剪枚举条目,绝不删 WeakMap 状态对象——split-brain 风险来自删状态对象而非删枚举项,因此 issue option 1 的「全部访问走 getter」重构被证明不必要且被省掉。pruneKnownHostIfIdle 仅在完全空闲(activeRuns===0 && queue 空 && !flushScheduled)时删除;getter 每次访问都重新加入集合;剪枝点放在 settle handler 与 idle-flush 宏任务回调内。关键不变量:任何产生待投递工作的路径(scheduleRunNotification/maybeFlushNotifications)都必经创建型 getter → 先重新入集再可能投递,故无目标 flush 不可能漏投。
  5. 是否有回归问题:审过并逐项确认——① handler 注册幂等性:ensureHostNotificationHandlers 的 hostNotificationStates.has(pi) 守卫依赖 WeakMap 条目永不删除,本 PR 恰好满足,无双注册/双计数;② 三级投递(settle/context/idle)语义未动;③ 无目标枚举对活宿主仍完整(不变量 + 测试 4 钉住);④ findUndeliveredRuns 全局恢复路径未触碰;⑤ 每宿主隔离不受影响。本地证据(核心 CI 对本 stacked PR 不跑,见下):pi-subagents 组件套件 227 pass / 0 fail,tsc --noEmit clean;牙齿验证:把新测试文件放到 base 代码上(仅注入诊断导出使 import 成立)实跑,测试 1、2 按预期失败,3、4 通过——确认真回归测试。CI 侧:9 个 e2e lane check-run 全绿。
  6. 是否破坏缓存:不涉及(无缓存/重试/游标/去重键)。
  7. 是否改了设计方向:不涉及——是 fix(pi-subagents): commit delegate completion notifications at the model's next safe boundary (#2320) #2389 设计的内部细化,且明确论证了为何不做 option 1 的全量 getter 间接化重构(更少 churn、更低回归面)。
  8. 是否引入了新的配置:无用户可见配置/env/CLI 新增;仅一个内部导出 knownDelegateHostCount()(测试/诊断钩子);pi-subagents/package.json 0.1.3→0.1.4(Pi-Subagents Boundary 规则 1 强制,根 package.json 未动)。

需要 owner 知晓的一点(非缺陷):核心 ci.yml 的触发条件是 pull_request: branches: [master],本 PR base 是 #2389 分支,所以 typecheck/test/build/guards 全套没有在本 PR 上运行——目前只有 e2e lane 工作流(base 不限)跑了且全绿。这是 stacked PR 的固有后果,PR 描述已写明「#2389 合并后 rebase 到 master」,届时核心 CI 会补全;合并前建议以 rebase 后的绿色为准。本地组件级验证(227 测试 + typecheck + 牙齿复现)已覆盖核心 CI 对本 diff 的增量检查面。

判定:方向对、实现最小化、测试有牙、行为变更已披露(清理时机从「永不清理」→「空闲后一个宏任务清理,再次访问即重新注册」,投递语义零变化)。无拦截项;待 #2389 落地后 rebase + 核心 CI 绿即可合。

@ranxianglei
ranxianglei force-pushed the 2026-10-08_delegate-notify-boundary branch from d07c13a to b3c4039 Compare October 8, 2026 13:45
…enumeration registry (#2390)

knownHosts (the strong-ref set a target-less flush enumerates) had no removal path, so every session's host was pinned forever in a long-lived process. Prune a host from enumeration once it is fully idle (no in-flight runs, empty coalescing queue, no pending flush) and re-add it on every state access; the per-host state object itself is never deleted, so captured handlers cannot desync. Deterministic regression test asserts the registry count returns to baseline after idle hosts settle.
@ranxianglei
ranxianglei force-pushed the 2026-10-08_delegate-notify-host-reclaim branch from 657479e to cecabf0 Compare October 8, 2026 13:48
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 ⚠️ merge_conflict 已处理完毕。PR #2392 已 rebase 到移动后的 base 并推送,冲突解除(mergeable: True)。

结构化八问:

  1. 是什么问题:系统转发的「上游 PR 冲突」——本 PR 与其目标分支(= fix(pi-subagents): commit delegate completion notifications at the model's next safe boundary (#2320) #2389 分支 2026-10-08_delegate-notify-boundary)merge 状态变 dirty。不是代码缺陷,是 stacked 结构的状态问题。
  2. 什么原因导致的:base 分支被 rebase 到了更新的 master(头从 d07c13ab 移到 b3c40395a,内容 = 同一笔 [Bug][Pi] acp_delegate 完成通知使用 followUp,主任务运行期间长期滞留队列;建议改用 steer #2320 提交 + 新 master 的 kernel/src/docs 变更),而本 PR 的单提交仍基于旧 base。新 master 未触碰 pi-subagents/,所以实际是 stacked rebase 的常规状态错位,不是语义冲突。
  3. 影响范围与严重程度:仅本 PR 的合并状态(暂时不可合);代码行为零影响。
  4. 怎么修复的:git rebase --onto b3c40395a d07c13ab(单提交重放)——干净落位,无需手工解冲突;--force-with-lease 推送(自己的 PR 分支,非 master)。rebase 后 diff 与 rebase 前逐字节一致(同 3 文件,+174/−4,已用 diff-of-diffs 校验 IDENTICAL)。
  5. 是否有回归问题:无——内容零变化。本地复验:pi-subagents tsc --noEmit clean、组件套件 227 pass / 0 fail。CI:新 head cecabf0fa 上 e2e lane 已重新触发,6/9 绿(registry ubuntu/windows、pi-codex-ws 在跑)。核心 ci.yml 依旧因 base≠master 不触发(上次回复已说明的 stacked 固有限制),fix(pi-subagents): commit delegate completion notifications at the model's next safe boundary (#2320) #2389 合并后最终 rebase 到 master 时补全。
  6. 是否破坏缓存:不涉及。
  7. 是否改了设计方向:不涉及。
  8. 是否引入了新的配置:无。

判定:冲突已解,mergeable: True;等 e2e lane 跑完转绿即可,后续按原计划待 #2389 落地后 rebase 到 master 跑满核心 CI 再合。

@ranxianglei
ranxianglei merged commit 9714145 into 2026-10-08_delegate-notify-boundary Oct 8, 2026
9 checks passed
@ranxianglei
ranxianglei deleted the 2026-10-08_delegate-notify-host-reclaim 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

Development

Successfully merging this pull request may close these issues.

1 participant