fix(core): keep agent usage rounds cumulative

[yiliang114]

What this PR does

Keeps background-agent usage event round numbers cumulative when one logical run enters a second reasoning-loop segment to consume late external input.

Why it's needed

The runtime already preserves cumulative execution statistics across the final-drain segment, but usage events still restarted at round 1. Consumers using the run and round as an idempotency key could silently discard the second segment's token usage.

Reviewer Test Plan

How to verify

Run the named headless-agent test and confirm that two segments in one logical execution emit usage rounds 1 and 2, while the existing continuation and statistics tests remain green.

Evidence (Before & After)

Before: the regression test observed [1, 1]. After: it observes [1, 2].

Tested on

OS	Status
🍏 macOS	✅
🪟 Windows	N/A
🐧 Linux	N/A

Environment (optional)

Named Vitest file with the existing workspace dependencies.

Risk & Scope

• Main risk or tradeoff: downstream consumers now see cumulative rather than segment-local usage round numbers.
• Not validated / out of scope: provider-level token completeness outside emitted usage events.
• Breaking changes / migration notes: none.

Linked Issues

Follow-up for the multi-agent shared-thread design.

中文说明

本 PR 做什么

当同一个后台 Agent 逻辑 run 为消费迟到的外部输入而进入第二个推理循环段时，保持 usage 事件的轮次编号连续递增。

为什么需要

运行时已经在最终 drain 段保留累计执行统计，但 usage 事件仍从第 1 轮重新编号。以 run 和 round 作为幂等键的消费者会静默丢弃第二段的 token 用量。

Reviewer Test Plan

如何验证

运行命名的 headless-agent 测试，确认同一逻辑执行的两个分段依次发出第 1、2 轮 usage，同时已有续跑与统计测试仍通过。

证据（修复前后）

修复前：回归测试观测为 [1, 1]。修复后：观测为 [1, 2]。

测试平台

OS	状态
🍏 macOS	✅
🪟 Windows	N/A
🐧 Linux	N/A

环境（可选）

使用现有 workspace 依赖运行命名 Vitest 文件。

风险与范围

• 主要风险或取舍：下游消费者现在看到累计 usage 轮次，而不是分段局部轮次。
• 未验证 / 范围外：usage 事件之外的 provider token 完整性。
• 破坏性变更 / 迁移说明：无。

关联 Issue

multi-agent shared-thread 设计的后续修正。

[qwen-code-ci-bot]

✅ Qwen Triage finished — view run. See the stage comments in this thread for the result.

✅ Qwen Triage 已完成 —— 查看运行。结果见本线程中的各阶段评论。

[qwen-code-ci-bot]

Thanks for the PR!

Template looks good ✓ — all sections present, including the Chinese translation.

Problem: the behaviour itself is real and reproducible. roundOffset is non-zero only when a segment runs with resetStats: false, and there are exactly two production call sites that do that — the background subagent late-input path and the background-agent resume path — so a second reasoning-loop segment genuinely does renumber usage from 1 while executionStats.rounds keeps counting. The new test pins that ([1, 1] → [1, 2]) and it exercises the real execute → executeExternalInputs path rather than a mock.

What I could not substantiate is the harm the description claims: "consumers using the run and round as an idempotency key could silently discard the second segment's token usage." I checked all eight USAGE_METADATA subscription sites — five take no arguments at all, and the three that read the payload use usage.candidatesTokenCount, usage + durationMs, and usage.promptTokenCount/totalTokenCount. Nothing reads round. AgentUsageEvent also has no runId field, so a (run, round) key can't be built from this event today, and it isn't exported from the core public barrel, so there's no external consumer surface either. Is this preparing the contract for a consumer landing with the shared-thread work? If so, naming it in the description would make the change much easier to judge.

Direction: aligned in principle — making the usage event agree with the cumulative round count the stats already report is defensible, and getExecutionSummary().rounds being cumulative across segments is already asserted by two existing tests. Flagging for maintainer awareness that this is token-usage accounting, which sits next to the telemetry surface. No direct CHANGELOG reference, but the area is relevant.

Size: core path (packages/core/src/**), fix type, maintainer-authored. 2 production lines (1 added / 1 removed in agent-core.ts), 37 test lines, 0 generated/schema. Far below both the 500-line escalation and the 1000-line advisory.

Approach: minimal and focused — one line plus one regression test, no drive-by edits or scope creep. The open design question is the one that line raises: USAGE_METADATA becomes cumulative while its five siblings in the same loop iteration (ROUND_START, STREAM_TEXT, ROUND_TEXT, ROUND_END, and the tool events via processFunctionCalls) stay segment-local. Worth settling before this lands — I go into detail in the code review below.

Risk: no elevated risk signals — neither changed file matches the revert-correlated path list.

Moving on to code review. 🔍

中文说明

感谢贡献！

模板完整 ✓ —— 各小节齐全，含中文翻译。

问题： 行为本身真实且可复现。roundOffset 仅在以 resetStats: false 运行的分段中非零，而生产代码里只有两处这样调用——后台 subagent 的迟到输入路径和 background-agent resume 路径——所以第二个推理循环段确实会把 usage 重新从 1 编号，而 executionStats.rounds 仍在累计。新增测试固定了这一点（[1, 1] → [1, 2]），并且走的是真实的 execute → executeExternalInputs 路径，不是 mock。

我无法证实的是描述里声称的危害："以 run 和 round 作为幂等键的消费者会静默丢弃第二段的 token 用量"。我检查了全部八个 USAGE_METADATA 订阅点——五个完全不接收参数，另外三个读取 payload 的分别用 usage.candidatesTokenCount、usage + durationMs、usage.promptTokenCount/totalTokenCount。没有任何一处读 round。AgentUsageEvent 也没有 runId 字段，因此今天无法从该事件构造 (run, round) 键；它也没有从 core 公共 barrel 导出，所以同样不存在外部消费者。这是在为 shared-thread 工作中即将落地的消费者预先约定契约吗？如果是，在描述中点名会让这个改动容易判断得多。

方向： 原则上对齐——让 usage 事件与 stats 已经上报的累计轮次一致是站得住脚的，且 getExecutionSummary().rounds 跨分段累计已由两个既有测试断言。提请维护者注意：这属于 token 用量核算，紧邻 telemetry 面。CHANGELOG 无直接引用，但该领域相关。

规模： 核心路径（packages/core/src/**），fix 类型，维护者提交。2 行生产代码（agent-core.ts 中 1 增 1 删），37 行测试，0 行生成/schema。远低于 500 行升级阈值和 1000 行大 PR 建议阈值。

方案： 精简且聚焦——一行改动加一个回归测试，无顺手改动或范围蔓延。待定的设计问题正是这一行引出的：USAGE_METADATA 变为累计，而同一次循环迭代中的另外五个事件（ROUND_START、STREAM_TEXT、ROUND_TEXT、ROUND_END，以及经 processFunctionCalls 的 tool 事件）仍是分段局部编号。建议落地前先定下来——下面的代码审查会详述。

风险： 无升级风险信号——两个改动文件都不匹配与 revert 相关的路径列表。

进入代码审查 🔍

— Qwen Code · qwen3.8-max-2026-09-02

_{Reviewed at 6358ff16b3e6cc338ea3d9fca47c22b5061e22cd · re-run with @qwen-code /triage}

[qwen-code-ci-bot]

Code review

My independent proposal (written from the title and "Why it's needed", before reading the diff): cumulativeRounds is already computed in the loop and already applied to executionStats.rounds / stats.setRounds(). If the goal is "round numbers stay cumulative across segments", the consistent way to get there is to decide what round means on the event bus and apply it uniformly — either thread cumulativeRounds into every round-bearing emission for that iteration, or leave all events segment-local and keep the cumulative count where it already lives (stats, and the FINISH summary). What I would not do is convert one event type and leave its five siblings alone, because then round means two different things depending on which event you happen to be holding.

Comparing that to the diff, the PR takes the third path, and that is my one substantive concern.

USAGE_METADATA.round now disagrees with every sibling event from the same iteration. All the other round-bearing emissions in that loop still pass turnCounter: ROUND_START (997), STREAM_TEXT (1093), ROUND_TEXT (1190), the three ROUND_END sites (1278, 1324, 1347), and TOOL_CALL/TOOL_RESULT via the turnCounter argument to processFunctionCalls (1218). Only recordTokenUsage (1210) switches to cumulativeRounds. So in a continuation segment with roundOffset = 1, the first round of that segment emits usage as round 2 while ROUND_START/ROUND_TEXT/ROUND_END/tool events for that very same round all say 1. Before this PR all six agreed.

The sharpest instance is the transcript. ROUND_TEXT carries the same lastUsage object in its usageMetadata field, and agent-transcript.ts subscribes to ROUND_TEXT — persisting agentRound: event.round alongside usageMetadata — while it does not subscribe to USAGE_METADATA at all. So after this change, one round's token usage is written to the JSONL transcript under round 1 and reported on the event bus under round 2. That is a new mismatch between two views of the same numbers, introduced by the fix rather than removed by it.

To be clear about severity: nothing breaks today, precisely because no consumer reads the field. I checked all eight USAGE_METADATA subscribers — workflow-stall.ts:179, ArenaManager.ts:1427, background-agent-resume.ts:1168, agent.ts:3347 and agent.ts:4063 take no arguments at all; agent.ts:1562 reads usage.candidatesTokenCount; SubAgentTracker.ts:351 reads usage + durationMs; useAgentStreamingState.ts:89 reads usage.promptTokenCount/totalTokenCount. AgentUsageEvent is not exported from packages/core/src/index.ts, so there is no extension-facing surface either. That is exactly why this is a design question rather than a blocker — but it also means the change is currently inert, and the divergence it plants is what a future consumer will trip over first.

The stated rationale doesn't match the code. "Consumers using the run and round as an idempotency key could silently discard the second segment's token usage" — there is no such consumer, and AgentUsageEvent has no runId field, so that composite key cannot be constructed from this event even in principle. Likewise the Risk section's "downstream consumers now see cumulative rather than segment-local usage round numbers" describes an audience that doesn't exist yet. If this is groundwork for the shared-thread consumer, saying so would change how I'd judge it.

Minor: recordTokenUsage's second parameter is still named turnCounter (2656) while now receiving cumulativeRounds. Worth renaming in the same commit so the callee doesn't misdescribe its own input.

What's good: the diff is genuinely minimal — one production line, no drive-by edits. The test is real and non-vacuous: I confirmed the mock's usageMetadata reaches lastUsage via the resp.usageMetadata assignment at 1099, so the assertion [1, 2] exercises the actual execute → executeExternalInputs({ resetStats: false }) → roundOffset path and would have failed ([1, 1]) before the change. It sits next to the two existing continuation tests that already assert cumulative rounds: 2, so it's consistent with the established stats contract.

Test evidence

This is an unattended CI run, so per the gate rules I did not build or execute any PR-derived code — the evidence below is the PR's own CI, read through the API for the reviewed commit.

Nothing is red. The three checks that would actually exercise this change — unit tests, lint/typecheck, and integration — were still running when I fetched, so the new test's pass/fail result is not verified yet; I confirmed its logic statically instead. No failing job, so there is no log excerpt to quote.

review-pr and triage in the table are bot orchestration jobs (pull_request_target), not PR CI — they don't gate the change.

Final CI results for 6358ff1 (auto-updated by the triage finalize job after CI completed):

Check	Conclusion
web-shell E2E Smoke (ubuntu-latest, Node 22.x)	❌ failure
Classify PR	✅ success
Desktop Shell (ubuntu-22.04)	✅ success
Desktop Shell (windows-2022)	✅ success
Integration Tests (no-AK, No Sandbox)	✅ success
Lint & Static (ubuntu-latest, Node 22.x)	✅ success
Test (ubuntu-latest, Node 22.x)	✅ success

_{One row per check name (latest run); skipped checks omitted; failures sort first. / 每个检查名一行（取最新一次运行），省略 skipped，失败项排在最前。}

58 further checks are skipped (platform-conditional matrix legs and unused lanes) — normal for this repo.

Sandboxed verification would settle the part the unit test can't: @qwen-code /verify — the new test drives AgentHeadless directly with a mocked sendMessageStream, so it never touches the two production call sites where roundOffset actually becomes non-zero (agent.ts:3494 and background-agent-resume.ts:1256). An A/B run would show whether cumulative usage rounds appear end-to-end in a real background agent that consumes late input, and whether the usage-vs-transcript round divergence above shows up in a persisted transcript. The author reports testing on macOS only (Windows/Linux N/A), which is a second reason not to take the behaviour as settled from the diff alone.

中文说明

我的独立方案（只看标题和"为什么需要"、未读 diff 时写下）：cumulativeRounds 已在循环中算好，并已用于 executionStats.rounds / stats.setRounds()。如果目标是"轮次编号跨分段累计"，一致的做法是先确定 round 在事件总线上的语义再统一应用——要么把 cumulativeRounds 传入该次迭代中所有带 round 的事件，要么让所有事件保持分段局部编号、把累计值留在它已有的位置（stats 与 FINISH 摘要）。我不会只改一种事件而留下另外五种，因为那样 round 的含义就取决于你手上拿到的是哪个事件。

与 diff 对比，本 PR 走了第三条路，这是我唯一的实质性顾虑。

USAGE_METADATA.round 现在与同一次迭代的其他事件不一致。 循环中其他带 round 的事件仍传 turnCounter：ROUND_START(997)、STREAM_TEXT(1093)、ROUND_TEXT(1190)、三处 ROUND_END(1278、1324、1347)，以及经 processFunctionCalls 的 turnCounter 实参传入的 TOOL_CALL/TOOL_RESULT(1218)。只有 recordTokenUsage(1210) 换成了 cumulativeRounds。因此在 roundOffset = 1 的续跑分段中，该分段第一轮发出的 usage 是第 2 轮，而同一轮的 ROUND_START/ROUND_TEXT/ROUND_END/tool 事件全是第 1 轮。本 PR 之前六者是一致的。

最尖锐的例子是 transcript。ROUND_TEXT 的 usageMetadata 字段携带的是同一个 lastUsage 对象，而 agent-transcript.ts 订阅了 ROUND_TEXT（把 agentRound: event.round 与 usageMetadata 一起落盘），却完全没有订阅 USAGE_METADATA。所以改动之后，同一轮的 token 用量在 JSONL transcript 中记为第 1 轮，在事件总线上报为第 2 轮。这是修复本身引入的、同一份数据两个视图之间的新错配，而不是消除的错配。

关于严重程度需要说清楚：今天不会出问题，恰恰因为没有消费者读这个字段。我检查了全部八个 USAGE_METADATA 订阅点——workflow-stall.ts:179、ArenaManager.ts:1427、background-agent-resume.ts:1168、agent.ts:3347、agent.ts:4063 完全不接收参数；agent.ts:1562 读 usage.candidatesTokenCount；SubAgentTracker.ts:351 读 usage + durationMs；useAgentStreamingState.ts:89 读 usage.promptTokenCount/totalTokenCount。AgentUsageEvent 也未从 packages/core/src/index.ts 导出，因此不存在面向扩展的接口。正因如此这是设计问题而非阻塞项——但这也意味着该改动目前是惰性的，而它埋下的这处分歧会是未来消费者最先踩到的东西。

描述中的理由与代码不符。"以 run 和 round 作为幂等键的消费者会静默丢弃第二段的 token 用量"——不存在这样的消费者，且 AgentUsageEvent 没有 runId 字段，因此该复合键在原理上就无法从此事件构造。同样，Risk 小节"下游消费者现在看到累计 usage 轮次"描述的受众也尚不存在。如果这是为 shared-thread 消费者铺路，说明这一点会改变我的判断。

次要：recordTokenUsage 的第二个参数仍名为 turnCounter(2656)，但现在接收的是 cumulativeRounds。建议同一次提交里改名，免得被调函数的名字误述自己的入参。

做得好的地方： diff 确实精简——一行生产代码，无顺手改动。测试真实且非空转：我确认了 mock 的 usageMetadata 会经 1099 行的 resp.usageMetadata 赋值进入 lastUsage，所以 [1, 2] 断言走的是真实的 execute → executeExternalInputs({ resetStats: false }) → roundOffset 路径，改动前会失败（[1, 1]）。它与两个已断言累计 rounds: 2 的既有续跑测试相邻，符合已确立的 stats 契约。

测试证据： 本次为无人值守 CI 运行，按门禁规则我没有构建或执行任何 PR 派生代码——以上证据来自 API 读取的该 PR 自身 CI（针对被审 commit）。

没有红灯。真正能覆盖此改动的三项检查——单元测试、lint/类型检查、集成测试——在我拉取时仍在运行，因此新测试的通过/失败结果尚未验证；我改为静态确认了它的逻辑。无失败作业，故无日志摘录可引。

表中 review-pr 与 triage 是机器人编排作业（pull_request_target），不属于 PR CI，不构成对本改动的门禁。另有 58 项检查为 skipped（平台条件矩阵分支与未使用通道），对本仓库属正常。

沙箱验证可以解决单元测试覆盖不到的部分：@qwen-code /verify——新测试直接驱动 AgentHeadless 并 mock 了 sendMessageStream，因此完全没有触及 roundOffset 在生产中真正变为非零的两个调用点（agent.ts:3494 与 background-agent-resume.ts:1256）。A/B 运行可以验证：真实后台 Agent 在消费迟到输入时是否端到端出现累计 usage 轮次，以及上述 usage 与 transcript 的轮次分歧是否会出现在落盘的 transcript 中。作者仅在 macOS 上测试（Windows/Linux 为 N/A），这也是不宜仅凭 diff 认定行为的第二个理由。

— Qwen Code · qwen3.8-max-2026-09-02

_{Reviewed at 6358ff16b3e6cc338ea3d9fca47c22b5061e22cd · re-run with @qwen-code /triage}

[qwen-code-ci-bot]

Confidence: 3/5 — the change itself is safe, minimal and properly tested, but it makes round mean two different things on the same event bus and I can't find the consumer it's justified by; the contract needs a human call.

Stepping back: my independent proposal was to decide what round means on the event bus and apply it uniformly, and this PR doesn't do that — it converts USAGE_METADATA to cumulative numbering while ROUND_START, STREAM_TEXT, ROUND_TEXT, ROUND_END and the tool events all stay segment-local. That's the whole reservation, and it's a design one rather than a correctness one.

I want to be precise about why this is a defer and not a request-changes. I traced the blast radius and it is genuinely tiny: all eight USAGE_METADATA subscribers either ignore the payload entirely or read only usage/durationMs, nothing reads round, and AgentUsageEvent isn't exported from the core barrel, so no extension can be reading it either. Nothing regresses when this merges. Every downstream consumer is named in my Stage 2 comment, so this isn't uncertainty about scope.

But the same fact cuts the other way: if no consumer reads the field, the change buys nothing observable today, and what it does leave behind is a divergence a future reader will hit first. The concrete case is the transcript — ROUND_TEXT carries the identical lastUsage object and agent-transcript.ts persists it as agentRound: event.round, while not subscribing to USAGE_METADATA at all. So one round's token usage gets written to the JSONL under round 1 and reported on the bus under round 2. If I were maintaining this in six months and tried to correlate those two, I'd curse the change, not thank it.

On the justification: the description rests on a consumer that keys on (run, round) and could silently drop usage. That consumer doesn't exist in this repo, and AgentUsageEvent has no runId field, so the key can't be built from it even in principle. I also checked the obvious candidate for "groundwork" — #11202 from the same author today, in this same subsystem — and it doesn't touch AgentUsageEvent. So I can't find what this is preparing for. If there is a consumer in flight that I'm not seeing, naming it would likely move me to approve, ideally together with the sibling events so the contract is one thing.

Worth saying plainly: the author has 40 open PRs, six of them today, several in this same corner of packages/core. I'm evaluating this one on its own merits and not letting volume push me toward a yes — but a stack of adjacent core PRs in one subsystem is exactly the condition under which a mixed contract like this slips through unremarked, so I'd rather flag it than wave it.

CI hasn't settled either: unit tests, lint/typecheck and integration were all still running when I fetched, so the new test's actual result is unverified. I confirmed its logic statically — it's non-vacuous and would have failed before the change — but I'm not approving against a result that doesn't exist yet, and this comment deliberately carries no deferred-approval instruction, because the verdict is defer rather than approve.

⏸️ Deferring — not approving, not requesting changes. The question for a maintainer is narrow: should round numbering on the agent event bus be cumulative across continuation segments, or segment-local? If cumulative, this PR should extend to the five sibling events (and the transcript's agentRound) rather than usage alone; if segment-local, the cumulative count already lives correctly in executionStats.rounds and this line should stay as it was. Either answer is fine — picking one implicitly, for one event type, is what I don't want to land silently.

I could not resolve an accountable owner to hand this to: no maintainer handle is configured for this run, the PR carries no labels so no area owner matched, and there are no human reviews yet. Posting without an @mention rather than guessing a login — a maintainer passing through should pick this up.

中文说明

Confidence: 3/5 —— 改动本身安全、精简、测试得当，但它让 round 在同一条事件总线上有了两种含义，而我又找不到其理由所依赖的消费者；这个契约需要人来定。

退一步看：我的独立方案是先确定 round 在事件总线上的语义再统一应用，而本 PR 没有这么做——它把 USAGE_METADATA 改为累计编号，而 ROUND_START、STREAM_TEXT、ROUND_TEXT、ROUND_END 以及 tool 事件全都保持分段局部编号。这就是我全部的保留意见，且属于设计层面而非正确性层面。

我想说清楚为什么这是 defer 而不是 request-changes。我追踪了影响面，它确实极小：全部八个 USAGE_METADATA 订阅者要么完全忽略 payload，要么只读 usage/durationMs，没有任何一处读 round；AgentUsageEvent 也未从 core barrel 导出，因此扩展同样读不到。合并后不会有任何回归。我的 Stage 2 评论已点名每一个下游消费者，所以这不是对范围的不确定。

但同一事实也指向反面：如果没有消费者读这个字段，该改动今天就买不到任何可观测收益，而它留下的、未来读者最先撞上的，是一处分歧。具体例子是 transcript——ROUND_TEXT 携带的是完全相同的 lastUsage 对象，agent-transcript.ts 将其以 agentRound: event.round 落盘，却完全没有订阅 USAGE_METADATA。于是同一轮的 token 用量在 JSONL 中记为第 1 轮，在总线上报为第 2 轮。如果六个月后由我维护、并试图把这两者关联起来，我会埋怨这个改动，而不是感谢它。

关于理由：描述依赖一个以 (run, round) 为键、可能静默丢弃用量的消费者。该消费者在本仓库不存在，且 AgentUsageEvent 没有 runId 字段，因此这个键在原理上就无法构造。我也检查了"铺路"最可能的对象——同一作者今天在同一子系统的 #11202——它并未触及 AgentUsageEvent。所以我找不到这是在为什么做准备。如果确有我没看到的在途消费者，点名它很可能让我转为 approve，最好连同兄弟事件一起改，使契约统一。

需要坦白说明：作者有 40 个开放 PR，其中六个是今天的，且有几个就在 packages/core 的同一角落。我是按本 PR 自身价值评估，不让数量把我推向"同意"——但同一子系统中一叠相邻的核心 PR，恰恰是这种混合契约最容易不被察觉地溜过去的条件，所以我宁愿指出来，也不愿放过。

CI 也尚未落定：我拉取时单元测试、lint/类型检查、集成测试都还在运行，因此新测试的实际结果未经验证。我静态确认了它的逻辑——非空转，且改动前会失败——但我不会针对一个尚不存在的结果 approve；本评论也刻意不携带任何延迟审批指令，因为结论是 defer 而非 approve。

⏸️ 暂缓——不 approve，也不 request changes。 留给维护者的问题很窄：Agent 事件总线上的轮次编号，跨续跑分段应该是累计的，还是分段局部的？如果是累计，本 PR 应扩展到另外五个兄弟事件（以及 transcript 的 agentRound），而不只是 usage；如果是分段局部，累计值已经正确地存在于 executionStats.rounds，这一行应保持原样。两种答案都可以——我不希望看到的是为单一事件类型隐式地选定其中一种，并让它悄悄落地。

我无法解析出可交接的负责人：本次运行未配置维护者 handle，PR 没有标签因而没有匹配到领域负责人，也还没有人类 review。我选择不 @ 任何人，而不是猜一个 login——路过的维护者请接手。

— Qwen Code · qwen3.8-max-2026-09-02

_{Reviewed at 6358ff16b3e6cc338ea3d9fca47c22b5061e22cd · re-run with @qwen-code /triage}

[yiliang114]

Converted to draft, not closed. The mesh work is being delivered as one PR (#11206), so this change is folded into codex/multi-agent-mesh-foundation as a commit rather than merged on its own. Keeping this PR open preserves its review threads and CI history as the reference for that commit. Please do not merge separately.

Tracking: #11206 (umbrella), acceptance criteria in docs/plans/2026-09-07-mesh-implementation-acceptance.md on that branch.

[yiliang114]

This PR is intentionally kept as a draft checkpoint. Its C1 changes are now integrated into #11072, which is the canonical implementation and relay PR. Please continue review and implementation on #11072.

[yiliang114]

Retargeted to base codex/multi-agent-mesh-foundation and marked ready: sub-PRs merge into the mesh PR one at a time, #11206 merges to main. Merge order for the stack: #11200 → #11204 → #11202. CI on the main-based run was green; a PR based on the mesh branch runs no unit tests or lint here, so check #11206's CI after this merges.