test(core): stub the registry methods agent.ts actually calls

[chinesepowered]

Fixes #7537 — packages/core's test:ci is red on main, so every open PR's Test (ubuntu-latest, Node 22.x) job fails regardless of its own diff.

What this PR does

Adds the six BackgroundTaskRegistry methods that agent.ts calls but the shared stubRegistry in agent.test.ts never stubbed, and asserts registry.fail was not called before asserting completion. Test-only change; no production code touched.

Why it's needed

agent.test.ts's outer beforeEach hand-rolls a stub registry. Diffing the registry.* calls in agent.ts against that stub's keys:

missing from stub	real signature
unregisterResidentAgent	(agentId, resident?) => boolean
registerResidentAgent	(agentId, resident) => void
restartCompletedAgent	(agentId, abortController) => AgentTask | undefined
bridgeApprovalEvents	(agentId, emitter) => () => void
waitForMessages	(agentId, signal) => Promise<AgentExternalInput[]>
getQueuedCount	() => number

This is not a benign omission. The background body wraps its work in a try/catch that routes any throw into registry.fail(), so a missing method never surfaces as "not a function" — it silently turns a successful run into a failed one.

On the GOAL completion path, unregisterResidentAgent is called immediately before complete() (agent.ts:3370 and :3378), so the TypeError replaced the completion outright. Confirmed by instrumenting registry.fail in the failing test:

FAIL CALLS: [["fork-06a26e81",
              "registry2.unregisterResidentAgent is not a function",
              "[object Object]"]]

That is exactly why runs a non-interactive fork through the background registry fails with complete → Number of calls: 0 while every earlier assertion in the same test passes.

Why this only appeared now: #7460 added the registry.complete assertion. Before it, nothing checked whether the background body finished successfully, so the TypeError was swallowed by the .catch handler and the incomplete stub went unnoticed. The stub has been out of date since the resident-agent lifecycle landed; #7460 is what made it visible.

bridgeApprovalEvents is stubbed to return a callback rather than undefined because agent.ts stores the result and later invokes it as the unsubscribe — a bare vi.fn() would throw the same class of error on cleanup.

Reviewer Test Plan

How to verify

• On main: npx vitest run --root packages/core src/tools/agent/agent.test.ts → 1 failed | 196 passed (197).
• On this branch: same command → 197 passed (197).
• Broader: npx vitest run --root packages/core src/tools/agent/ src/agents/ → 1386 passed, 6 skipped (40 files).
• Typecheck and eslint clean. Note tsc initially flagged the new fail assertion, because the test's local cast of getBackgroundTaskRegistry() declared only register and complete; the cast now includes fail.

Evidence (Before & After)

# main (d064bd7dc)
 FAIL  src/tools/agent/agent.test.ts > AgentTool > Fork dispatch (subagent_type: "fork")
       > runs a non-interactive fork through the background registry
 AssertionError: expected "spy" to be called with arguments: [ Any<String>, …(2) ]
 Number of calls: 0
      Tests  1 failed | 196 passed (197)

# this branch
      Tests  197 passed (197)

Tested on

OS	Status
🍏 macOS	✅
🪟 Windows	⚠️
🐧 Linux	⚠️

macOS: agent.test.ts 197/197 and the wider agent suites 1386/1392 pass locally; typecheck and eslint clean. Test-only change to mock objects with no platform-dependent behavior, so no manual QA is required; CI covers Windows/Linux — and this PR's own green Test (ubuntu) job is the direct confirmation.

Environment (optional)

Node v24; @qwen-code/qwen-code-core workspace; vitest 3.2.

Risk & Scope

• Main risk or tradeoff: none to production — only mock objects in a test file change. The added methods are no-ops returning the shapes the real registry returns, so no existing assertion changes meaning; all 197 tests in the file pass, including the 196 that already did.
• Not validated / out of scope: the swallowing behavior itself. That the background body converts a TypeError into registry.fail(...) means a genuine production bug on this path would be reported as a failed agent with a cryptic message rather than surfacing as a crash. That seemed worth flagging but not worth changing error handling in the agent background path in a PR whose job is to get CI green. The new expect(stubRegistry.fail).not.toHaveBeenCalled() at least makes it visible in this test.
• Breaking changes / migration notes: none.

Linked Issues

Fixes #7537.

中文说明

修复 #7537 —— packages/core 的 test:ci 在 main 上是红的，导致每个已开启 PR 的 Test (ubuntu-latest, Node 22.x) 任务都会失败，与其自身改动无关。

本 PR 的作用

补齐 agent.ts 会调用、但 agent.test.ts 中共享的 stubRegistry 从未 stub 的六个 BackgroundTaskRegistry 方法，并在断言完成之前先断言 registry.fail 未被调用。纯测试改动，不涉及任何生产代码。

为什么需要

agent.test.ts 的外层 beforeEach 手写了一个 stub registry。将 agent.ts 中的 registry.* 调用与该 stub 的键做差集：

stub 中缺失	真实签名
unregisterResidentAgent	(agentId, resident?) => boolean
registerResidentAgent	(agentId, resident) => void
restartCompletedAgent	(agentId, abortController) => AgentTask | undefined
bridgeApprovalEvents	(agentId, emitter) => () => void
waitForMessages	(agentId, signal) => Promise<AgentExternalInput[]>
getQueuedCount	() => number

这并非无害的遗漏。后台执行体将其工作包在 try/catch 中，任何抛出都会被导流至 registry.fail()，因此缺失的方法根本不会以 "not a function" 的形式浮现——它会悄无声息地把一次成功的运行变成失败。

在 GOAL 完成路径上，unregisterResidentAgent 恰好在 complete() 之前被调用（agent.ts:3370 与 :3378），于是 TypeError 直接取代了完成流程。通过在失败测试中给 registry.fail 加探针得到确认：

FAIL CALLS: [["fork-06a26e81",
              "registry2.unregisterResidentAgent is not a function",
              "[object Object]"]]

这正是 runs a non-interactive fork through the background registry 以 complete → Number of calls: 0 失败、而同一测试中此前所有断言却都通过的原因。

为何现在才暴露： #7460 新增了 registry.complete 断言。在此之前，没有任何测试检查后台执行体是否成功完成，TypeError 被 .catch 处理器吞掉，这个不完整的 stub 便一直无人察觉。自 resident-agent 生命周期引入以来该 stub 就已过时，#7460 只是让它显形。

bridgeApprovalEvents 被 stub 为返回一个回调而非 undefined，因为 agent.ts 会保存该返回值并在稍后作为取消订阅函数调用——若用裸的 vi.fn()，清理时会抛出同一类错误。

复核测试计划

如何验证

• 在 main 上：npx vitest run --root packages/core src/tools/agent/agent.test.ts → 1 failed | 196 passed (197)。
• 在本分支上：同一命令 → 197 passed (197)。
• 更大范围：npx vitest run --root packages/core src/tools/agent/ src/agents/ → 1386 passed、6 skipped（40 个文件）。
• typecheck 与 eslint 均干净。注意 tsc 最初对新增的 fail 断言报错，因为该测试中对 getBackgroundTaskRegistry() 的局部类型断言只声明了 register 与 complete；现已补入 fail。

证据（修复前后对比）

# main (d064bd7dc)
 FAIL  src/tools/agent/agent.test.ts > AgentTool > Fork dispatch (subagent_type: "fork")
       > runs a non-interactive fork through the background registry
 AssertionError: expected "spy" to be called with arguments: [ Any<String>, …(2) ]
 Number of calls: 0
      Tests  1 failed | 196 passed (197)

# 本分支
      Tests  197 passed (197)

测试环境

系统	状态
🍏 macOS	✅
🪟 Windows	⚠️
🐧 Linux	⚠️

macOS：agent.test.ts 197/197、更大范围的 agent 套件 1386/1392 本地通过；typecheck 与 eslint 干净。纯测试文件中 mock 对象的改动，无平台相关行为，因此无需人工 QA；Windows/Linux 由 CI 覆盖——本 PR 自身变绿的 Test (ubuntu) 任务就是最直接的确认。

运行环境（可选）

Node v24；@qwen-code/qwen-code-core 工作区；vitest 3.2。

风险与影响范围

• 主要风险或权衡：对生产代码无风险——仅改动测试文件中的 mock 对象。新增方法均为返回真实 registry 对应形状的空实现，因此不改变任何既有断言的含义；该文件全部 197 个测试通过，其中包括原本已通过的 196 个。
• 未验证 / 范围之外：吞异常这一行为本身。 后台执行体把 TypeError 转成 registry.fail(...)，意味着该路径上真正的生产 bug 会表现为「一个带着晦涩信息的失败 agent」，而非直接暴露为崩溃。这一点值得指出，但在一个以「让 CI 变绿」为目标的 PR 里改动 agent 后台路径的错误处理并不合适。新增的 expect(stubRegistry.fail).not.toHaveBeenCalled() 至少让它在本测试中可见。
• 破坏性变更 / 迁移说明：无。

关联 Issue

Fixes #7537。

[qwen-code-ci-bot]

Thanks for the PR — and for the unusually thorough write-up.

Template: complete ✓

Problem: observed, not theoretical. Linked P1 issue #7537 with a deterministic reproduction and a git bisect pointing at #7460. I confirmed it locally: on main (d064bd7) the fork-dispatch test fails with complete → Number of calls: 0, exactly as described.

Direction: aligned. packages/core's test:ci being red on main fails every open PR's Test (ubuntu) job through no fault of its own — getting it green is squarely worth doing.

Size: the only changed file is agent.test.ts (a *.test.ts), so this is 0 production logic lines / 24 test additions. Not a refactor, no core hard-block, no production risk surface.

Approach: minimal and on-point — add exactly the six registry methods the stub was missing, with the correct return shapes, plus a fail-not-called assertion so the next stub drift surfaces loudly instead of being swallowed. No drive-by changes. I agree with keeping the deeper "the background body converts a TypeError into registry.fail(...)" concern out of this PR; worth a follow-up issue, not a scope expansion here.

Moving on to code review. 🔍

中文说明

感谢贡献，也感谢这份异常详尽的说明。

模板： 完整 ✓

问题： 已观测到的真实 bug，而非理论性问题。关联了 P1 issue #7537，附带确定性复现，并用 git bisect 定位到 #7460。我在本地确认：在 main（d064bd7）上 fork-dispatch 测试以 complete → Number of calls: 0 失败，与描述完全一致。

方向： 对齐。packages/core 的 test:ci 在 main 上是红的，会连累每个已开启 PR 的 Test (ubuntu) 任务——把它修绿完全值得做。

规模： 唯一改动的文件是 agent.test.ts（*.test.ts），因此是 0 行生产逻辑 / 24 行测试新增。不是 refactor，不触发核心硬拦截，也没有生产风险面。

方案： 最小且切题——恰好补齐 stub 缺失的六个 registry 方法并给出正确返回形状，再加一条「fail 未被调用」的断言，让下一次 stub 失配能响亮地暴露出来，而不是被吞掉。没有顺手改动。我赞同把更深层的「后台执行体把 TypeError 转成 registry.fail(...)」这一顾虑排除在本 PR 之外；它值得单独开一个 issue，而不是在此扩大范围。

进入代码审查。🔍

— Qwen Code · qwen3.8-max-preview

_{Reviewed at 755a7121bcee686ae4955eb42423fe08a028d282 · re-run with @qwen-code /triage}

[qwen-code-ci-bot]

Code review

My independent take before reading the diff: diff the registry.* calls in agent.ts against the stub's keys, add the missing ones with the shapes the real registry returns, and assert registry.fail stays uncalled so future drift is visible. The PR does exactly this — nothing more, nothing less.

I verified the diagnosis against the code, not just the description:

• agent.ts reaches all six methods the stub was missing (getQueuedCount, registerResidentAgent, unregisterResidentAgent, restartCompletedAgent, bridgeApprovalEvents, waitForMessages).
• On the GOAL path, unregisterResidentAgent (agent.ts:3370) runs immediately before registry.complete (:3381), inside a try/catch that routes any throw to registry.fail (:3467). So a missing stub method throws a TypeError that gets swallowed into fail() — complete() never fires, which is precisely the Number of calls: 0 the issue reports.
• Each stub's return shape matches the real BackgroundTaskRegistry (background-tasks.ts): getQueuedCount(): number, unregisterResidentAgent(...): boolean (stubbed true), bridgeApprovalEvents(...): () => void (stubbed with a callable unsubscribe — a bare vi.fn() would throw on cleanup, as the PR notes), waitForMessages(...): Promise<AgentExternalInput[]> (resolved []), restartCompletedAgent(...): AgentTask | undefined, registerResidentAgent(...): void.

No correctness, security, or regression concerns. The added comments explain the non-obvious why (the swallow-into-fail behavior) rather than narrating the code — appropriate. No over-abstraction or duplication.

Real-scenario testing

This is a test-only change to a mock object, so the meaningful before/after evidence is the test runner itself. (tmux is not installed in this environment and there's no passwordless sudo to add it, so I captured the real vitest output directly rather than via capture-pane.)

Before (main, d064bd7)

 FAIL  src/tools/agent/agent.test.ts > AgentTool > Fork dispatch (subagent_type: "fork") > runs a non-interactive fork through the background registry
AssertionError: expected "spy" to be called with arguments: [ Any<String>, …(2) ]

Number of calls: 0

 ❯ src/tools/agent/agent.test.ts:3157:37
    3156|       await vi.runAllTimersAsync();
    3157|       expect(stubRegistry.complete).toHaveBeenCalledWith(

 Test Files  1 failed (1)
      Tests  1 failed | 196 passed (197)

After (this PR, 755a712)

 ✓ src/tools/agent/agent.test.ts (197 tests) 1209ms

 Test Files  1 passed (1)
      Tests  197 passed (197)

Broader agent suites (this PR)

 Test Files  39 passed | 1 skipped (40)
      Tests  1386 passed | 6 skipped (1392)

Also clean: tsc --noEmit -p packages/core (exit 0) and eslint agent.test.ts (exit 0).

中文说明

代码审查

我在读 diff 之前的独立想法：把 agent.ts 里的 registry.* 调用与 stub 的键做差集，补齐缺失项并给出真实 registry 的返回形状，再断言 registry.fail 未被调用，让以后的失配可见。PR 的做法与此完全一致——不多不少。

我对照代码（而非仅凭描述）核实了诊断：

• agent.ts 确实会调用 stub 缺失的全部六个方法。
• 在 GOAL 路径上，unregisterResidentAgent（agent.ts:3370）紧接在 registry.complete（:3381）之前执行，外层 try/catch 会把任何抛出导流到 registry.fail（:3467）。因此缺失的 stub 方法会抛出 TypeError 并被吞进 fail()——complete() 永远不会触发，这正是 issue 所报 Number of calls: 0 的成因。
• 每个 stub 的返回形状都与真实 BackgroundTaskRegistry（background-tasks.ts）一致：getQueuedCount(): number、unregisterResidentAgent(...): boolean（stub 为 true）、bridgeApprovalEvents(...): () => void（stub 为可调用的取消订阅函数——裸 vi.fn() 会在清理时抛错，正如 PR 所述）、waitForMessages(...): Promise<AgentExternalInput[]>（resolve 为 []）、restartCompletedAgent(...): AgentTask | undefined、registerResidentAgent(...): void。

无正确性、安全性或回归问题。新增注释解释的是不显然的「为什么」（吞进 fail 的行为），而非复述代码——恰当。无过度抽象或重复。

真实场景测试

这是对 mock 对象的纯测试改动，因此最有说服力的 before/after 证据就是测试运行器本身。（本环境未安装 tmux，且无免密 sudo 可安装，故直接捕获真实 vitest 输出，而非通过 capture-pane。）

before（main）：1 failed | 196 passed (197)；after（本 PR）：197 passed (197)；更大范围 agent 套件：1386 passed | 6 skipped (1392)。另外 tsc --noEmit -p packages/core 与 eslint agent.test.ts 均干净（exit 0）。

— Qwen Code · qwen3.8-max-preview

_{Reviewed at 755a7121bcee686ae4955eb42423fe08a028d282 · re-run with @qwen-code /triage}

[qwen-code-ci-bot]

Confidence: 5/5 — clean across every stage; would merge without hesitation.

Stepping back: this is exactly the kind of PR the gate should wave through quickly. The problem is real and verified (I reproduced the red test on main myself), the root-cause analysis is correct down to the line numbers, and the fix is the minimal change that solves it — six stub methods with the right return shapes, plus one assertion that makes the next stub drift impossible to miss. There's no production code touched, no scope creep, and no abstraction for its own sake.

What I appreciated: the author found the genuinely interesting bit — that the background body silently converts a TypeError into registry.fail(...) — and deliberately left it out of scope while flagging it. That restraint is the right call for a "get CI green" PR, and it's worth a follow-up issue so it doesn't get lost.

The before/after matches the promise (1 failed → 197 passed), the broader agent suites show no regressions, and typecheck + lint are clean. If I'm maintaining this in six months, the added comments tell me exactly why the stub has to stay in sync. Approving. ✅

中文说明

置信度：5/5 —— 每个阶段都干净，毫不犹豫地合入。

退一步看：这正是 gate 应当快速放行的那类 PR。问题真实且已验证（我自己在 main 上复现了那个变红的测试），根因分析精确到行号，修复是解决问题所需的最小改动——六个返回形状正确的 stub 方法，外加一条让下一次 stub 失配无法被忽略的断言。没有触及生产代码，没有范围蔓延，也没有为抽象而抽象。

我欣赏的一点：作者发现了真正有意思的地方——后台执行体会悄无声息地把 TypeError 转成 registry.fail(...)——并刻意将其排除在范围之外，同时加以提示。对于一个「让 CI 变绿」的 PR 来说，这种克制是恰当的，值得单独开个 issue 以免被遗忘。

before/after 与承诺一致（1 failed → 197 passed），更大范围的 agent 套件无回归，typecheck 与 lint 均干净。批准。✅

— Qwen Code · qwen3.8-max-preview

_{Reviewed at 755a7121bcee686ae4955eb42423fe08a028d282 · re-run with @qwen-code /triage}

[qwen-code-ci-bot]

LGTM, looks ready to ship. ✅

[qwen-code-ci-bot]

⚠️ Downgraded from Approve to Comment: CI still running. Reviewed.

— qwen3.7-max via Qwen Code /review

[doudouOUC]

No issues found. LGTM! ✅

— qwen3.7-max via Qwen Code /review

[yiliang114]

LGTM! Thanks for your job