diff --git a/docs/design/agent-team-roster-web-shell.md b/docs/design/agent-team-roster-web-shell.md
new file mode 100644
index 00000000000..c15c1d0b827
--- /dev/null
+++ b/docs/design/agent-team-roster-web-shell.md
@@ -0,0 +1,64 @@
+# Agent Team roster in CLI and WebShell
+
+## Goal
+
+Give a team leader one compact answer to “who is active, and what are they working on?” in both interactive CLI and WebShell, while preserving the existing teammate conversations, shared task list, and daemon session APIs.
+
+## Existing pieces to reuse
+
+- `TeamManager` owns teammate lifecycle, direct messaging, approvals, and the shared task list.
+- CLI `AgentView` already owns teammate tabs and conversation navigation.
+- CLI `LiveAgentPanel` already owns the compact, bounded live roster and keyboard focus behavior.
+- `GET /session/:id/agents` already projects daemon-session agents into WebShell.
+- WebShell `EnvironmentPanel` and `AgentWorkflow` already render agent state.
+
+## Design
+
+### CLI
+
+`BackgroundTaskViewProvider` derives a second, display-only roster from the active in-process `TeamManager`. Each teammate is adapted to the existing agent-row shape and merged with ordinary live subagents only for `LiveAgentPanel`; it is not inserted into the background-task dialog or cancellation registry.
+
+The adapter subscribes to team lifecycle events and shared-task updates. A row shows the teammate name, the current in-progress task when one is assigned, the distinct running/idle/completed/failed/cancelled state, and elapsed time. Enter on a teammate row opens its existing `AgentView` tab; Enter on an ordinary subagent keeps opening the existing background-task detail.
+
+### WebShell
+
+The existing session-agent snapshot adds active TeamManager members. No new HTTP route, SSE event, or client store is introduced. Team rows carry optional team name, color, and current shared-task metadata. WebShell's existing polling, environment sidebar, and workflow graph therefore receive team state automatically.
+
+Idle is represented explicitly rather than collapsed into paused or completed. Team rows show the assigned task inline. Because WebShell does not yet expose an in-process teammate transcript endpoint, team rows are status-only there; ordinary subagent rows retain their existing detail action.
+
+ACP sessions bind the same TeamManager leader callback used by the interactive and non-interactive clients. Teammate reports enter the existing serialized background-notification turn queue, so an idle WebShell leader resumes to reconcile results instead of ending after dispatch. Teammate tool approvals use the existing ACP permission request channel. Replacing or deleting a team detaches both callbacks and drops queued messages from the old team.
+
+When a teammate is launched from an Agent definition, its declared MCP servers are passed into the existing in-process agent boundary. That boundary merges them over the session MCP map, discovers only the definition-owned servers in the teammate's isolated tool registry, and releases their transports with the registry when the teammate stops. This keeps the same more-specific-wins behavior and cleanup lifecycle as ordinary subagents.
+
+## Interaction sources
+
+- Claude Code Agent Teams: compact lead-side roster, explicit idle state, shared task ownership, and direct navigation to an existing teammate conversation.
+- Multica: durable work-item ownership is visible independently of chat messages.
+- Harness: execution state is projected into an existing workspace surface rather than creating a second execution engine.
+
+## Scope
+
+Included: current-session in-process teammates, shared task ownership, CLI navigation, WebShell status projection, teammate-to-leader continuation, teammate approvals, Agent-definition MCP inheritance, and terminal-state visibility.
+
+Excluded: remote agent provisioning, durable workspace scheduling, cross-machine control, a new team chat UI, and WebShell teammate transcript browsing.
+
+## Verification
+
+- Focused unit tests for team snapshot serialization, CLI roster adaptation/rendering, keyboard routing, and WebShell idle/task rendering.
+- Package builds and type checks for core consumers, CLI, SDK, ACP bridge, and WebShell.
+- Executable WebShell smoke coverage with a mocked `/session/:id/agents` team response.
+- Manual CLI E2E using `team_create`, named `agent` launches, `task_create`/`task_update`, roster navigation, and shutdown states.
+- Real Chrome + tmux E2E against `qwen serve`, covering running/idle/cleaned roster transitions, automatic leader continuation, team shutdown/deletion, and rejection of a teammate `write_file` request through WebShell's permission dialog.
+- Real stdio MCP E2E through an Agent definition used as a named teammate, proving the teammate can call its definition-only tool and report the result to the leader.
+
+## Acceptance result
+
+- Core Agent Team regression suite: 66 tests passed, including Agent-definition MCP merge and discovery.
+- CLI focused suite: 96 tests passed for the changed roster and background-task surfaces; the broader feature suite previously passed 267 tests.
+- ACP Session suite: 820 tests passed, including leader continuation, teammate approvals, and pending-approval cancellation when a team is detached.
+- WebShell focused suite: 930 tests passed across App, panel, and transcript adaptation; App coverage verifies idle polling and teammate launch/inventory deduplication.
+- Chromium WebShell smoke: passed against the mocked daemon route.
+- Repository build and typecheck: passed.
+- CLI, WebShell, ACP bridge, and all changed files: lint passed. The SDK package-wide lint command is blocked by its existing mixed ESLint 8/9 installation; the changed SDK type file passes lint directly.
+- Live-model WebShell execution passed against a local tmux-hosted daemon. The leader resumed from real teammate reports, reconciled them, shut down teammates, deleted the team, and respected a rejected teammate write without creating the file. A final fresh-Chrome run confirmed that a named launch and its live inventory entry render as one running row before cleanup.
+- A second live tmux + Chrome run launched a named teammate from an Agent definition, called its definition-only stdio MCP tool, returned `MCP_TEAM_PROOF:REAL_TEAM_MEMBER` to the leader, automatically resumed the leader, deleted the team, and left no MCP child process running.
diff --git a/docs/plans/2026-09-06-agent-team-webshell-gap.md b/docs/plans/2026-09-06-agent-team-webshell-gap.md
new file mode 100644
index 00000000000..186a59b0bfd
--- /dev/null
+++ b/docs/plans/2026-09-06-agent-team-webshell-gap.md
@@ -0,0 +1,186 @@
+# Agent Team in WebShell: current state and the gap to an orchestrated agent fleet
+
+> Status: Assessment — no implementation
+> Baseline: `origin/main` @ `002305b903` (2026-09-06), plus `origin/codex/agent-team-roster-web-shell` (#11072) and `origin/codex/agent-team-discovery-web-shell` (#11140)
+> Related: #10247 (Agent Team tracker), #11069, #8724 (closed), #9402 (board), #11003 (external ACP executor)
+
+## 0. Summary
+
+The target experience — *declare durable agents, put repos and work items in a workspace, create a
+task against a workspace, pick one or more agents, and let several agents self-organise* — is the
+Multica model. Qwen Code today implements a **different** model: one interactive session's model
+calls `team_create`, and teammates are spawned **inside that session's process**.
+
+The two open PRs are the *observability + plumbing* leg of the current model. They are correct and
+worth landing, but they do not move the topology toward the target. Everything the target needs —
+durable agent identity, runtime binding, a work-item/run record, UI-initiated team formation, and a
+process per agent — is still unbuilt, and one of its prerequisites (#10247 §5, the Agent View
+supervisor wiring) is stalled on an unmade decision.
+
+Rough distance: the coordination *runtime* is ~80% there for the in-session topology; the
+*orchestration product* the user described is ~10–15% there, and most of the remaining work is new
+daemon state, not model plumbing.
+
+## 1. The two PRs, precisely
+
+### #11072 — `feat(ui): show Agent Team status in CLI and WebShell` (draft, base `main`, +1374/-89, 40 files)
+
+Two things, not one:
+
+1. **A read-only roster projection.** `use-team-agent-roster.ts` (new) adapts live `TeamManager`
+ members into the existing CLI `LiveAgentPanel` rows; `tasksSnapshot.ts`'s
+ `buildSessionAgentsStatus` appends team members (name, colour, current in-progress shared task,
+ running/idle/completed) to the existing session-agents snapshot, so WebShell's `EnvironmentPanel`
+ and `AgentWorkflow` pick them up with no new route, SSE event, or store.
+2. **Actual ACP coordination wiring** (`Session.ts`, +157). This is the load-bearing part:
+ `#registerTeamManagerCallbacks` binds the leader-message callback so a teammate report enqueues a
+ background notification and **resumes an idle WebShell leader**; teammate tool approvals are
+ routed through the existing WebShell permission dialog
+ (`#requestTeammateApproval`); replacing/deleting a team detaches callbacks, aborts pending
+ approvals, and drops that team's queued notifications. Plus: named teammates keep their name
+ through the daemon transcript (dedupe), and a teammate launched from an Agent definition inherits
+ that definition's MCP servers.
+
+CI is green (including the real-daemon E2E and web-shell smoke). No reviews yet. Still draft.
+Before #11072, `qwen serve` had the Agent Team runtime but no path for a teammate to reach the
+leader or the user — so this is the PR that makes Agent Team *usable at all* in WebShell.
+
+### #11140 — `feat(web-shell): expose Agent management in sidebar` (draft, base `codex/agent-team-roster-web-shell`, +120, 7 files)
+
+Its own delta is 120 lines: one `agents` entry in the WebShell primary sidebar between New Task and
+Plugins, opening the **existing** `AgentsManagerPage` (Agent *definition* CRUD), plus one sentence
+explaining that Qwen can coordinate definitions in an Agent Team. No runtime behaviour.
+
+Two caveats:
+
+- It is stacked on #11072, and a PR based on a non-`main` branch **runs no unit tests and no
+ Lint & Static** in this repo (`ci.yml` triggers only on `main`/`release/**`). Its checks are all
+ `skipping`.
+- The entry is called "Agents" but manages *prompt/tool/model definitions*, not runnable agents.
+ Against the target model that name is a promise the daemon cannot yet keep.
+
+## 2. What actually exists today (traced)
+
+| Layer | Exists | Where | Note |
+| --- | --- | --- | --- |
+| Agent **definitions** | Yes | `.qwen/agents/*.md`, `SubagentManager`, `GET/POST /workspace/agents` (`serve/workspace-agents.ts:180`), WebShell `AgentsManagerPage` | Prompt + tools + MCP + hooks + model. **No runtime binding, no identity, no run history.** |
+| Agent **team runtime** | Yes | `packages/core/src/agents/team/` (~6.9k lines): `TeamManager`, `tasks.ts`, `mailbox.ts`, `leaderPermissionBridge.ts`, `promptAddendum.ts` | Persisted at `~/.qwen/teams/{team}/config.json`, shared tasks at `~/.qwen/tasks/{team}/`. Gated behind experimental `agentTeam` setting, **default off** (`settingsSchema.ts:3650`). |
+| Team **creation** | Model-only | `team_create` tool (`config.ts:8197`) | There is no API or UI that creates a team. The LLM decides. |
+| Teammate **process** | In-process | `detectBackend` (`agents/backends/detect.ts:41`) defaults to `InProcessBackend`; `TmuxBackend` is opt-in via `agents.displayMode` and CLI-only | Under `qwen serve`, teammates are `AgentCore` loops **inside the daemon process**. |
+| Daemon **workspaces** | Yes | `serve/workspace-registry.ts` — `WorkspaceRuntime` = id + cwd + trust + bridge + services | A workspace is **one cwd**, not a set of repos, and holds no work items. |
+| Daemon **sessions** | Yes | `POST /session` (`routes/session.ts:1318`) — cwd, model, approvalMode, scope | No agent/persona binding at creation. |
+| Spawn a **fresh top-level session** | Yes | `create_sub_session` tool + daemon handler `serve/create-sub-session.ts` | The closest existing primitive to "a new agent that is a real main loop". Fire-and-forget or first-turn result; not kept resident. |
+| Supervised **child processes** | Stranded | `packages/cli/src/agent-view/` (~3.1k prod lines) | `supervisor-runner.ts:38` spawns `qwen --internal-agent-view-supervisor`; **nothing on `main` parses that flag** and yargs is `.strict()`, so the supervisor exits immediately. Tracked as #10247 §5 with two competing wiring stacks (#7802/#7803 vs #10942/#10943/#10949/#10954) and an unmade choice. |
+| **Remote / cloud** agents | No | — | Nearest: #11003 delegates one subagent turn to an external agent (Claude Code) over ACP — local child process, per-turn, not a hosted agent. #11139 separates leader/worker credentials. |
+| Cross-process work sharing | Design + PR | #9402 agent board (`~/.qwen/boards/`), design `docs/plans/2026-08-18-peer-session-collaboration.md` | Pull-based, no membership, no wake path. Explicitly **not** a scheduler. |
+
+## 3. Agent Team vs subagents — what the difference actually is here
+
+The user's mental model ("subagents can't talk; teams can") is directionally right but not quite
+this codebase's distinction, because Qwen Code's background subagents *can* already be messaged
+mid-flight (`send_message` with `task_id`, `background-agent-resume.ts`). The real differences:
+
+| | Subagent (`agent` tool) | Teammate (Agent Team) |
+| --- | --- | --- |
+| Lifetime | One task, then terminates | Long-lived: goes **idle** and picks up the next task; idle is deliberately distinct from completed |
+| Identity | Ephemeral `task_id` from the launch response | Named `name@team`, persisted on disk with PID liveness; discoverable via `list_agents` |
+| Work assignment | Parent hands it a prompt | Shared task list with `claim` semantics, `blocks`/`blockedBy`, owner field — teammates **pull** work (`promptAddendum.ts` literally instructs: call `task_list`, claim, do, report, mark complete, repeat) |
+| Topology | Star: parent ↔ child | Leader + named peers, broadcast `*`, structured mailbox (`shutdown_request`, `plan_approval_request`, `task_assignment`) with cross-process file locks |
+| Approvals | Routed to the parent session | `leaderPermissionBridge` + optional plan mode: teammate must `exit_plan_mode` and get leader approval before writing |
+| Leader blocking | Inline subagent blocks the turn; background ones notify | Leader stays idle and is **resumed** by a teammate report (this is what #11072 wires into ACP) |
+| Process | In the session process (or backgrounded) | In-process, or a real `qwen` process per teammate under the tmux backend |
+
+**What that buys.** Warm, stateful workers that survive across tasks (no re-priming per task),
+pull-based distribution so the leader isn't a dispatch bottleneck, mid-flight steering without a
+full hand-back, and a plan-approval gate before a worker is allowed to write.
+
+**What it costs.** Each teammate is a full independent context — its own history, its own system
+prompt, its own tool declarations. Nothing is shared. So the bill is not "×2"; it is roughly
+**N × (per-worker context) + the coordination traffic**: every teammate re-polls `task_list` on each
+loop, every report is a `send_message` plus a leader resume turn, and each approval is another
+leader round trip. With N warm workers on a long task the coordination term is not the small one.
+The payoff is wall-clock parallelism and keeping the leader's context clean — the same context
+argument that justifies ordinary subagents, plus concurrency.
+
+**Correction worth internalising:** an Agent Team is *not* a stronger version of a subagent; it is a
+different **allocation model** (pull from a shared board) with a different **lifetime** (warm and
+reusable). The chat-vs-no-chat framing understates it.
+
+## 4. The target model, mapped
+
+The described workflow is Multica's, near one-to-one:
+
+| Target concept | Multica | Qwen Code today |
+| --- | --- | --- |
+| Agent = reusable identity, bound to a runtime and model, with availability + workload status | `Agent` + `Runtime` | **Definition only.** No runtime binding, no online/offline, no workload. |
+| Workspace holds repos and work items | `Workspace` + `Projects` + `Issues` | Workspace = one cwd. No projects, no issues. Nearest: goals, scheduled tasks. |
+| Create a task, pick workspace + agent(s) | Assign an issue to an agent | New Task creates a chat session; no agent picker. |
+| Several agents → coordinated by a leader | `Squad` (leader routes, members triggered by `@mention`) | Agent Team, but created **by the model inside a session**, not declared by the user. |
+| Each run is a real, isolated execution with a record | `Run` (transcript, tokens, retries) | Sessions and workflow runs exist; not tied to a work item or an agent identity. |
+| Agents may be remote/cloud | Daemon runtimes, cloud runners | None. |
+
+Note the topology difference that is easy to miss: a Multica **squad leader routes and stops** —
+coordination is coarse, durable, and mediated by issue comments; runs are fresh processes. A Qwen
+**Agent Team leader stays live** and its teammates share an in-memory/on-disk task board with
+fine-grained messaging. The target wants Multica's *outer* loop with (optionally) Qwen's *inner*
+loop inside a single run. These compose; they do not conflict.
+
+## 5. Gap, in dependency order
+
+1. **Durable agent identity** — agent = definition + runtime + model + concurrency + access, with
+ its own id and history. New daemon-persisted state and a REST surface. Everything else depends
+ on this. #11140's sidebar entry is the natural home for it, which is exactly why landing that
+ entry while it still means "definition CRUD" is a naming risk.
+2. **A process (or hosted session) per agent.** Three candidate hosts, pick one:
+ (a) daemon-hosted session per agent, built on `create_sub_session` — cheapest, no new supervision,
+ but agents share the daemon's fate and memory; (b) child `qwen` process per agent supervised by
+ the daemon — this is what `agent-view/` was built for, and it is one unmade decision plus one
+ unparsed CLI flag away from being reachable; (c) generalise `TmuxBackend` — visible but
+ terminal-bound and CLI-only. **Recommendation: (b), after #10247 §5 picks a wiring stack.**
+3. **Work items and runs.** A durable record keyed to work, not to a chat session: who ran, against
+ which agent identity, what it cost, what it produced. `workflow-run-registry` + workflow
+ snapshots are the closest existing shape and are worth reusing rather than re-inventing.
+4. **UI-initiated team formation.** Today `team_create` is a model tool. Needs an API that
+ pre-creates a team and binds a session to it, so "pick 3 agents for this task" is a user action
+ rather than a prompt the leader has to be talked into. This is the *smallest* remaining item —
+ `TeamManager` already accepts an externally-constructed team file.
+5. **Remote / cloud agents.** ACP over a network transport plus a credential model. #11003 and
+ #11139 are the first two bricks; there is no third yet.
+
+Also gating, not optional:
+
+- `agentTeam` is experimental and **off by default** — the whole surface is invisible to users
+ until that flips, which is a product decision, not a code one.
+- #10207 (one task dispatched to two teammates) is the last open lifecycle race, fix still draft.
+- `chore/remove-unwired-agent-view` exists as a branch — deleting the supervisor is on the table.
+ Deciding to keep it and deciding to build (2b) are the same decision.
+
+## 6. Recommended next steps
+
+1. **Land #11072.** Take it out of draft and get review. Its ACP wiring is a prerequisite for any
+ later topology — a teammate that cannot reach the leader or raise an approval in WebShell is
+ unusable regardless of who spawns it. The read-only roster is a fair MVP; WebShell teammate
+ transcript browsing can follow.
+2. **Retarget #11140 to `main`** (small `App.tsx` rebase) so it gets real CI, or hold it until step
+ 1 lands and the agent-identity model is decided. Landing it is cheap and forecloses nothing, but
+ plan to re-point "Agents" at real agent identities rather than definitions.
+3. **Force the #10247 §5 decision** before any further orchestration work: one wiring stack, or
+ delete `agent-view/`. Step 2 of §5 above cannot start until this is settled.
+4. **Write the target-model design** (agent identity + run record + team formation API) as a
+ separate plan. It is a daemon-state design, not a UI change, and it is where the real distance
+ lies.
+
+
+中文说明
+
+目标形态（声明持久化的 Agent、工作空间挂仓库与事项、新建任务时选工作空间 + 若干 Agent、多个 Agent 自动组队）本质上是 Multica 的模型。Qwen Code 现在实现的是另一套：由会话里的模型调用 `team_create`，队友跑在**同一个进程内**。
+
+两个 PR 是当前模型的「可观测 + 接线」这一条腿：#11072 一半是只读 roster 投影，另一半是真正关键的 ACP 接线（队友汇报唤醒空闲 Leader、队友审批走 WebShell 权限弹窗、团队替换/删除时解绑与清理、Agent 定义的 MCP 继承）；#11140 只有 120 行，在侧栏加一个入口，打开的是**已有的 Agent 定义管理页**，没有运行时语义，而且因为叠在非 main 分支上，单测和 Lint 全部 skip。
+
+Agent Team 与 subagent 的差异，不完全是「能不能聊天」——Qwen 的后台 subagent 已经可以用 `send_message(task_id)` 中途通信。真正的差异是**分配模型**（共享任务板 + 认领，队友主动拉活）和**生命周期**（idle 后可复用，不是一次性）。代价不是「翻倍」，而是 N 份独立上下文 + 协调流量（每轮 `task_list` 轮询、每次汇报的 Leader 续跑、每次审批的往返）。
+
+距离：协调运行时对「单会话内组队」这个拓扑已经完成约 80%；用户描述的编排产品大约只有 10–15%，缺的主要是 daemon 侧的新状态而不是模型接线。按依赖顺序缺：①持久化的 Agent 身份（绑定 runtime/模型）②每个 Agent 一个真实进程或托管会话（推荐走 daemon 托管子进程，但要先在 #10247 §5 二选一，`agent-view/` 的 supervisor 至今因为 `--internal-agent-view-supervisor` 没人解析而跑不起来）③事项与 Run 记录 ④由 UI 而非模型发起的组队 API（这一项最小）⑤远程/云端 Agent（目前只有 #11003、#11139 两块砖）。另外 `agentTeam` 默认关闭，#10207 竞态未修。
+
+建议：#11072 转 Ready 送审；#11140 改 base 到 main 拿到 CI（或等身份模型定了再合，避免「Agents」入口名不副实）；尽快敲定 #10247 §5；把目标形态单独写成一份 daemon 状态设计。
+
+
diff --git a/docs/plans/2026-09-06-multi-agent-board-collaboration.md b/docs/plans/2026-09-06-multi-agent-board-collaboration.md
new file mode 100644
index 00000000000..59c40fe53dd
--- /dev/null
+++ b/docs/plans/2026-09-06-multi-agent-board-collaboration.md
@@ -0,0 +1,890 @@
+# Multi-agent collaboration on a shared thread
+
+> Status: Revised after source-backed review. A small, uncommitted correction to
+> the pre-existing admission layer is parked in the review working tree (§5.1);
+> the workspace transaction, durability contract, and execution path remain
+> unbuilt.
+> Baseline: `origin/main` @ `703678136a` (2026-09-06)
+> Verification: targeted tests, build, typecheck, and lint are recorded in §0.2;
+> no agent has run this design end to end
+> Supersedes the Agent-Team-first direction in [`2026-09-06-agent-team-webshell-gap.md`](./2026-09-06-agent-team-webshell-gap.md) §6
+> Related: #9402 (board storage), #10078 (session boundary), #10247 §5, #11072, #11140
+
+## 0. What this is
+
+Durable agent identities that collaborate on a shared thread. A person opens a
+thread, assigns an agent, and the agents take it from there — reading, posting,
+`@`-ing each other, splitting sub-threads, and handing work back for review,
+while the person can interject at any moment.
+
+This is the Multica model, built on machinery Qwen Code already has. Agent Team
+is untouched and stays the inner loop for sub-turn collaboration inside a single
+run.
+
+### 0.1 The correction this rests on
+
+An earlier reading concluded Multica's agents "don't talk in real time". Source
+inspection shows that conclusion was wrong, but also exposes an important scope
+difference:
+
+- `server/internal/daemon/types.go` (`PriorSessionID`) and
+ `handler/daemon.go` (`GetLastTaskSession{AgentID, IssueID}`) — Multica resumes
+ the prior session for one **(agent, issue)** pair. It does not give an agent
+ one body shared across issues.
+- `server/internal/daemon/wakeup.go` (`taskWakeupLoop`) — WebSocket push wakes
+ idle claimers quickly; an HTTP polling fallback deliberately remains active.
+- `server/internal/handler/comment.go` (`ReasonAlreadyActive`,
+ `decidePostMergeMiss`) — a comment cannot enter an executing task, but it is
+ not simply dropped: completion reconciliation replays the miss.
+
+`@`-based coordination in Multica is live collaboration. Its limitation is
+latency during an active run, not eventual delivery.
+
+Qwen Code can deliver at a tool-round boundary, but the entry point matters.
+`resumeBackgroundAgent` returns an already-running task without consuming its
+continuation message. The working path is the same three-way split used by
+`tools/send-message.ts`: `registry.queueMessage` for running,
+`continueResidentAgent` for a completed resident runtime, and cold resume/revive
+otherwise. `queueMessage` returning `false` during finishing is a delivery miss,
+not success; §4 requires durable reconciliation before this design may claim an
+advantage over Multica. Mesh delivery uses the lower-level
+`queueExternalInput` with a correlated delivery id; the existing string-only
+`queueMessage` wrapper is insufficient for a durable consumed watermark.
+
+Decision 5 below — one memory-bearing body across threads — is therefore a Qwen
+Code product choice, not copied Multica behaviour. It creates the thread-mixing
+and cross-thread trust problems addressed in §6 and §9.
+
+### 0.2 What is verified, and what is not
+
+Read this before treating anything below as established.
+
+**Verified by reading source.** Claims about Qwen Code and Multica name the
+load-bearing file and stable symbol. They were read directly, at the baseline
+commit above for Qwen Code and at `multica-ai/multica@7a438bd5b` for Multica.
+Re-check `BackgroundTaskRegistry.queueMessage`, `AgentEventType.EXTERNAL_MESSAGE`,
+`AgentEventType.USAGE_METADATA`, `continueResidentAgent`, `runBackgroundTurn`, auto-compaction,
+`PriorSessionID`, `taskWakeupLoop`, `ReasonAlreadyActive`, and
+`decidePostMergeMiss` before changing the execution model.
+
+**Verified in the mesh foundation commit.** Targeted tests, core typecheck, and
+targeted lint found and checked concrete defects that source review predicted:
+`blocked` was absent from store validation, an unknown `@name` fell back to the
+assignee, child budget fallback failed open, running work counted against the
+pending queue, and a human reply on one child reset a sibling's turn gate. Those
+checks validate only the rules/storage foundation, not this architecture. The
+targeted test command and count are kept in §5.3.
+
+**Verified in integrated runtime changes.** A two-segment headless execution
+reproduced `USAGE_METADATA.round` as `[1, 1]`; the cumulative-round patch changes
+it to `[1, 2]`. Structured external input now carries `deliveryId` through the
+consumed event and transcript, and resident continuation returns an actionable
+result instead of a boolean. Source and runtime
+tests also disproved one round-2 premise: ordinary resident `task_prompt`
+continuations already emit `EXTERNAL_MESSAGE`, and cold revival explicitly
+seeds the continuation prompt in the transcript. Mesh still uses structured
+input because correlation, not transcript presence, is the missing contract.
+
+**Still never prototyped end to end.** No mesh agent has been launched, no
+thread has been dispatched, no prompt in §6 has been sent to a model. The
+dispatch rules in §4 are reasoned from Multica's and Agent Team's failure modes,
+not from observed behaviour of this system.
+
+**How to re-check the Multica claims.** Clone `github.com/multica-ai/multica`
+and read `server/internal/daemon/types.go`, `server/internal/daemon/prompt.go`,
+`server/internal/daemon/wakeup.go`, and `server/internal/handler/comment.go`.
+Line numbers drift; the symbols (`PriorSessionID`, `taskWakeupLoop`,
+`ReasonAlreadyActive`, `decidePostMergeMiss`) do not. An earlier version of this
+design was wrong about Multica precisely because it reasoned from the docs
+rather than these files — argue from the symbols, not from the marketing pages.
+
+## 1. Execution model
+
+An agent is **one long-lived background agent per workspace**, not a daemon
+session. This was the design's biggest correction: the persona machinery
+(`subagent-manager.ts:868` → `{promptConfig, modelConfig, runConfig, toolConfig}`)
+targets the agent runtime, not ACP sessions, and there is no per-session persona
+hook. Building one would be new work on a hot path with no precedent.
+
+Nearly everything the execution layer needs already exists:
+
+| Need | Existing machinery |
+| -------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| Agent loop | `AgentCore` / `AgentInteractive` |
+| Persona: prompt, restricted tools, private MCP | `convertToRuntimeConfig` |
+| Durable log | `attachJsonlTranscriptWriter` |
+| Reading that log in Web Shell | virtual subagent sessions + the existing panel |
+| Deliver into a **running** agent | `BackgroundTaskRegistry.queueExternalInput` (boolean acknowledgement) |
+| Observe when queued input is actually consumed | `AgentEventType.EXTERNAL_MESSAGE` (needs a correlation-id extension) |
+| Incremental token usage | `AgentEventType.USAGE_METADATA` + transcript round usage |
+| Continue an idle resident body | `BackgroundTaskRegistry.continueResidentAgent` |
+| Wake from transcript after process/runtime loss | `reviveCompletedBackgroundAgent` |
+| Context growth | auto-compaction, already in the runtime (`agent-core.ts:559`, `:977`) |
+| Approvals | the background-agent approval path |
+| Keeping a bound session resident, and reviving one the reaper closed | `scheduled-task-keepalive.ts` |
+
+So the work is the **orchestration layer**, which does not exist yet, plus one
+narrow runtime contract extension: mesh external input and its consumed event
+must carry a server-generated delivery id. `queueMessage(true)` proves only that
+an in-memory queue accepted the input; the existing `EXTERNAL_MESSAGE` event is
+emitted when the agent actually drains it, but currently carries no correlation
+id. No agent loop rewrite is required, and none of the reuse goes through Agent
+Team — it goes through the background-agent layer that Agent Team and ordinary
+subagents both sit on.
+
+The hidden host session and its keepalive are correctness dependencies, not
+cleanup details. If the session is reaped, an idle resident body is disposed and
+the next turn is a transcript-backed cold revive. The background registry also
+caps concurrently running bodies (10 by default, with optional per-model caps).
+That is a workspace throughput ceiling, not a roster-size limit: idle resident
+agents do not occupy running slots, but launch admission and its failure outcome
+must be visible.
+
+## 2. Settled decisions
+
+Twenty-two decisions, all confirmed with the product owner and refined below.
+Recorded so implementation does not relitigate them.
+
+### Scope and safety
+
+| # | Decision | Consequence |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1 | **v1 agents are read-only.** No file writes, no worktrees, no branches. | Removes all concurrent-write design. The deliverable of a thread is a conclusion, not a diff. |
+| 2 | Read-only means **files + read-only shell**, against a **built-in allowlist**. `save_memory`, context-file writes, and every other persistent-write tool are outside that ceiling. | `run_shell_command` can write, so "no writes but any command" is a false boundary. The allowlist is the hard ceiling; agent definitions may narrow it, never widen it. |
+| 3 | Tool sets otherwise **follow a required agent definition**. | No second permission model. An enabled mesh agent with a missing definition is unavailable, never silently replaced by a generic persona. |
+| 4 | Agents are **scoped to one workspace**. | Trust and permissions follow the workspace. Five repos means five rosters. |
+
+### Identity and memory
+
+| # | Decision | Consequence |
+| --- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 5 | **One long-lived execution body per agent**, with memory continuous across threads. | Deliberate divergence from Multica's per-(agent, issue) session. Makes the agent serial and makes old threads a persistent trust input. |
+| 6 | Context growth uses runtime **auto-compaction**, but every run prompt remains self-contained. | Compaction exists but is lossy; it invalidates any assumption that an earlier thread frame or delivery is still remembered. |
+| 7 | The **host session is hidden and kept alive** while mesh agents exist. | The user's model stays "agents and threads". Losing the host degrades resident continuation to transcript-backed cold revive and must be observable. |
+| 8 | **Disabling keeps memory; deleting clears it.** Deletion refuses while any run is non-terminal. | Disable-and-drain is the safe default: already-booked work drains, but new work is refused. Deletion disposes the body and transcript; historical posts retain a tombstoned identity snapshot. |
+
+### Conversation
+
+| # | Decision | Consequence |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 9 | A message **may enter a running agent only on its bound thread**. Queue acceptance and correlated runtime consumption are recorded separately; undrained input is reconciled from durable triggers. | Mid-run steering is at-least-once, never a success-shaped prediction. Duplicate delivery is allowed; silent loss is not. |
+| 10 | An agent is **serial across threads**. Pending work is selected globally by lock-issued `(queueSequence, runId)` FIFO and the waiting thread names the active thread. `queuedAt` is diagnostic only. | One slow thread blocks other work, file enumeration order cannot starve it, and clock skew between daemon and CLI cannot reorder work. |
+| 11 | Each agent has a **bounded pending queue**; running work is not counted. Full queues and launch failures are explicit outcomes. | `queueLimit=5` means five waiting runs, not four plus the active one; failed launches cannot occupy a slot forever. |
+| 12 | Agents may **post, `@` any enabled workspace agent, change status, and create sub-threads**. They may not create agents. | This is intentionally looser than Multica's per-agent invocation policy. Every agent action is stamped with its ambient run for provenance. |
+| 13 | A sub-thread becoming quiescent writes a durable, system-authored **parent dependency event** attributed to the child transition. `in_review` carries the summary; aggregate blocked, terminal run failure/cancellation, or human-set done carries its state. It targets the parent assignee; with none, it remains visible and notifies the person. | A waiting parent is always woken or visibly stranded, cross-file posting survives a crash, and the event cannot self-suppress when one agent owns parent and child. |
+| 14 | Blocking is one atomic operation: **post the question, record the caller blocked, and end that run**. The thread becomes `blocked` only when no other work can progress. | One agent cannot overwrite a shared thread's status while another is still working. A human reply that actually books/delivers work acknowledges current blockers and returns it to `in_progress`. |
+| 15 | An agent closes a run with atomic `thread_wait()`, `thread_block(question)`, or `thread_review(summary)`; **only a person sets `done`**. Waiting is allowed only with another live run or child dependency; a same-thread wait is acknowledged by any later close or human post on that thread. `in_review` is reached only after all booked work is quiescent. Marking done refuses non-done descendants, then cancels this thread's queued/running work. | Delegation can release the parent agent body without falsely asking a person or claiming review. The final explanation and workflow state cannot split across a crash, and closing a parent cannot orphan live child work. |
+
+### Cost and failure
+
+| # | Decision | Consequence |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 16 | Two gates: **12 unattended agent deliveries per thread / 200k accounted tokens per thread tree**. A human post resets only that thread's turn counter; the token gate applies to every trigger. `coalesce(running)` costs a turn, `coalesce(queued)` does not. | Turn count is a local loop breaker; token count is money. A sibling comment cannot reset a loop, and a human message cannot bypass known spend; strict reservation versus bounded in-flight overshoot remains §9.5. |
+| 17 | A child **inherits the parent's current turn count** and charges tokens to the root. | Creating a child does not mint immediate unattended turns; a child created at the limit may be gated immediately. Later human input resets only the child being supervised. |
+| 18 | A run is stuck when **N minutes pass with no activity** — not by total duration. | A legitimate two-hour investigation is never killed for being slow. |
+| 19 | A stuck run, and any run still `running` after a **daemon restart**, is reconciled once. Restart-recovered registry entries are `paused` and use `resumeBackgroundAgent`; completed entries use resident continue or cold revive. A second execution failure is terminal. A launch failure is typed and terminal unless classified transient. | Recovery follows the runtime's actual state machine and replays only work not committed by the delivery watermark; queued launch failures cannot poison the backlog indefinitely. |
+
+### Surfaces
+
+| # | Decision | Consequence |
+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 20 | The entry point **folds into the existing Agents page**; #11140's sidebar change is absorbed here and that PR is closed. | One PR, no dependency ordering, and the "Agents" entry finally means runnable agents. |
+| 21 | Creating or assigning a thread with an assignee emits a **structured assignment trigger** through the same booking transaction; no assignee leaves it idle. | Assignment cannot bypass budgets, provenance, queue limits, or the dispatch outcome model. The assignee is a future-routing default, not an exclusive lease; reassignment does not silently cancel already-booked work. |
+| 22 | Channel notifications (Lark/Slack/…) fire on **a blocker raised, aggregate in_review, gate tripped, and run failed after retry**. | The four things that need a person. Reuses the existing channel workers. |
+
+## 3. Data model
+
+```
+MeshWorkspaceState schemaVersion, workspaceId, hostSessionId,
+ nextRunSequence
+
+MeshAgent id, name, description, color, agentType, model,
+ queueLimit, enabled, createdAt,
+ backgroundAgentId ← execution binding
+
+Thread id, title, body, status, assigneeAgentId, createdAt,
+ createdBy, messages[], runs[],
+ parentThreadId, rootThreadId,
+ autoTurnsUsed, tokensUsed,
+ nextMessageSequence, deliveryByAgent{}, outbox[]
+
+ThreadMessage id, sequence, authorKind, from, authorNameSnapshot,
+ sourceRunId, triggerKind, text, mentions[], outcomes[], at
+ThreadRun id, agentId, sessionId, status, triggerMessageIds[],
+ acceptedMessageIds[], consumedMessageIds[],
+ contextThroughSequence, definitionVersion,
+ transcriptStartOffset, transcriptEndOffset,
+ closeKind, closeAcknowledgedAtSequence,
+ finalMessageId, usageByRound[],
+ failureStage,
+ queueSequence, queuedAt, startedAt, endedAt, attempts, error
+
+AgentDelivery committedThroughSequence
+DispatchOutcome targetAgentId, kind, reason, runId
+ThreadEvent id, kind, causedByRunId, payload, status, attempts
+
+ThreadStatus open | in_progress | blocked | in_review | done
+ThreadRunStatus queued | running | finishing | cancelling |
+ completed | failed | cancelled
+RunCloseKind waiting | blocked | review | unclosed
+```
+
+Most fields through `tokensUsed` are landed. The current proposal repeats
+`hostSessionId` on each agent; step 4 moves that workspace singleton into
+versioned `MeshWorkspaceState`. The sequence, provenance, delivery, outbox,
+failure-stage, and transcript-slice fields are required with the dispatcher;
+adding inert optional fields before a producer and consumer exist would only
+pretend the contract was implemented.
+
+`authorKind` is `human | agent | system`. An agent post requires `sourceRunId`;
+the server derives both from the ambient run rather than accepting them from the
+model or an HTTP body. A system trigger records the run or human action that
+caused it. This provenance does not neutralise prompt injection, but it prevents
+identity spoofing and makes every automated hop auditable.
+
+Deleting an agent removes its runnable identity and transcript, not the audit
+meaning of old posts. Messages therefore retain the author's display-name
+snapshot; ids are never reused. A missing or changed live agent cannot rewrite
+history.
+
+Admission outcomes are stored on the message in the same transaction as run
+booking. Returning them to the immediate caller is only a convenience; a reload
+must still explain an unknown target, gate, queue refusal, coalesce, or booking.
+
+`outbox` covers side effects that cannot share the thread-file transaction:
+parent dependency reports and channel notifications. Consumers acknowledge
+event ids, so a restart may duplicate an effect but cannot silently lose it.
+The parent post stores the event id as its idempotency key. Token accounting is
+not an outbox effect: usage is stored on the run that produced it and summed
+across the root's thread tree under the workspace lock.
+
+Message sequence is monotonic per thread. `triggerMessageIds` means durably
+booked; `acceptedMessageIds` means the runtime queue accepted those inputs;
+`consumedMessageIds` is recorded from the correlated `EXTERNAL_MESSAGE` event
+when the runtime drains them. `committedThroughSequence` advances only across a
+contiguous consumed context window. On a failed enqueue, execution failure, or
+daemon restart, reconciliation rebooks everything not consumed and committed.
+Delivery is therefore at-least-once: a duplicate is acceptable, silent loss is
+not.
+
+Run queue order is a separate workspace-wide monotonic `queueSequence`, issued
+while holding the workspace mutation lock. `queuedAt` remains useful for age and
+stall display but never participates in FIFO ordering because callers live in
+different processes and their wall clocks can disagree.
+
+At run start and direct delivery, the dispatcher sends one contiguous context
+window through `contextThroughSequence`, not just the triggering ids. The
+initial prompt is consumed when the turn starts; direct input becomes consumed
+only on its correlated runtime event. This makes the scalar watermark honest
+even when intervening posts targeted another agent. A clean but `unclosed`
+return blocks the workflow yet commits only demonstrably consumed input. A
+durable `blocked`/`review` close marker likewise lets restart reconciliation
+finish the workflow close without pretending an accepted-but-undrained message
+was read.
+
+Exact retries of mutating mesh tools are deduplicated by a runtime-derived action
+key `(runId, attempt, invocationSequence)`; the invocation sequence is assigned
+outside model arguments. This does not make a full model replay exactly-once: a
+crash after a visible post may produce a semantically duplicate post on the next
+attempt. That product trade-off remains explicit in §9.
+
+A mesh agent owns one append-only JSONL transcript across threads, so a run is a
+byte range within that file, captured after writer flush. The whole transcript
+is never presented as one run's log.
+
+There is no `maxConcurrentRuns`. Decisions 5 and 10 — one long-lived body per
+agent, serial across threads — already cap an agent at one running run, so the
+field would have been dead. What an agent needs bounded instead is its
+_backlog_, hence `queueLimit`.
+
+`rootThreadId` is inherited at creation rather than resolved by walking parents
+at spend time. Missing or invalid roots fail closed. A child inherits the
+parent's `autoTurnsUsed`, while only token spend is read from the root.
+
+The workspace lock prevents concurrent writers; it does **not** make two JSON
+files one transaction. A thread post, its admission outcomes, and its booked run
+share one atomic thread-file replacement. Cross-file parent reports and
+notifications use durable, idempotent outbox events. Every runtime
+`USAGE_METADATA` event upserts `(runId, attempt, cumulativeRound, usage)` on the
+source run; duplicate events replace the same entry. Admission sums
+`runs[].usageByRound` across the root's thread tree under the workspace lock
+before checking the token gate. Root `tokensUsed` may be a validated cache, not
+the source of truth. Transcript round usage can reconstruct a missing run entry;
+finish reconciles rather than creating the first usage record. Parent reports
+and notifications use write-source-first, apply-idempotently,
+acknowledge-last.
+Thread deletion refuses non-terminal runs, descendants, or unacknowledged
+outbox events; otherwise it could erase work or a side effect another file has
+not yet observed.
+
+Every released state file carries `schemaVersion`. A supported old version is
+migrated under the workspace lock with atomic replacement; an unknown newer
+version or failed migration is a fail-closed error, never treated as empty
+state. The pre-migration file is retained until the replacement validates.
+
+Stored under the per-project runtime dir (`~/.qwen/tmp//mesh/`),
+not the working tree — the reasoning the durable scheduled-tasks file records,
+plus one more: thread text is written by one agent and fed to another, so it is
+a prompt-injection surface and must never be committed, pulled, or reviewed as
+if it were code.
+
+## 4. The dispatch loop
+
+```
+person, agent, assignment, or child-dependency event
+ │
+ ▼
+postMessage() ── one workspace mutation lock ──────────────────┐
+ append sequenced + attributed message/trigger │
+ resolveTargets: any explicit @ token suppresses assignee │
+ for each target → decideDispatch │
+ append/coalesce run and charge local turn │
+ │ │
+ ▼ │
+returns { outcomes, dispatched[] } ─────────────────────────────┘
+ │
+ ▼
+dispatcher (daemon)
+ scan durable dirty runs/events; process-result notifications are only hints
+ choose each agent's oldest queued run by (queueSequence, runId)
+ running on THIS thread → registry.queueExternalInput(mesh delivery)
+ true → record accepted ids on the run
+ false → atomically detach/rebook unaccepted ids
+ drain → correlated EXTERNAL_MESSAGE records consumed ids
+ running on ANOTHER thread → leave queued; expose active thread
+ idle → completed+resident: continue; completed+cold: revive;
+ paused: resume; unbound: launch
+ capacity → leave queued; expose capacity_wait
+ accepted → startRun + record prompt watermark/transcript start
+ failed → terminal failed(failureStage=launch); release queue slot
+ │
+ ▼
+agent answers via thread_post ─────────────────────────────────► re-enters postMessage
+ │
+ ▼
+turn completes → flush transcript → finishRun
+ commit the contiguous consumed window, including a clean but unclosed return
+ reconcile per-round run usage, unconsumed ids, and cross-file outbox
+ select next FIFO run
+ │
+sweeper: run with no activity for N minutes, or `running` at daemon start
+ → reconcile; paused registry entry resumes, completed entry revives;
+ second failure → terminal failed
+```
+
+The loop closes because an agent's reply is itself a post. That is the whole
+mechanism, and it is why the guards are not optional.
+
+### Admission table (under the workspace mutation lock)
+
+| Outcome | When | Why it exists |
+| ------------------------------ | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `skip: agent_unknown` | an explicit `@token` resolved to no roster identity, or an assignee disappeared | a typo must be visible and must not fall back to the assignee |
+| `skip: agent_disabled` | agent exists but is off | keeps identity and history without taking work |
+| `skip: agent_unavailable` | the required agent definition is missing or invalid | fail before booking instead of turning a configuration error into a stuck run |
+| `skip: thread_done` | thread is finished | a late post must not silently restart spend |
+| `skip: self_trigger` | the target wrote the post | otherwise one "I'm done" becomes an infinite self-conversation |
+| `skip: no_target` | no explicit mention and no assignee | an accepted-looking post must not disappear silently |
+| `skip: turn_budget_exhausted` | agent-caused trigger, this thread's turn budget is spent | the local loop breaker; only a human post on this thread resets it |
+| `skip: token_budget_exhausted` | the root tree's accounted token budget is spent | money gate for human and agent triggers; never reset; in-flight policy is §9.5 |
+| `skip: queue_full` | the agent's backlog is at its limit | makes real throughput visible instead of accruing a stale queue |
+| `coalesce (queued)` | the agent has an unstarted run here | one run answers both posts instead of two racing |
+| `coalesce (running)` | the agent is executing **this** thread | records intent to attempt mid-run delivery; agent-caused delivery charges a turn |
+| `dispatch` | none of the above | book a queued run |
+
+Explicit routing is a target-resolution rule, not a synthetic skip outcome: the
+presence of any `@token`, including an unknown one, suppresses assignee fallback.
+Known and unknown tokens in the same post produce their own outcomes; known
+targets still run. These twelve outcomes are the complete admission contract;
+the local foundation currently tests eleven because definition availability is
+implemented with the launcher in §5.2 step 4.
+
+Malformed input, authentication failure, missing/corrupt storage, lock failure,
+and unknown schema version abort the mutation as typed API errors; they are not
+success-shaped dispatch outcomes. Retrying a mutation with the same runtime
+action key returns its previously persisted message and outcomes rather than
+booking again.
+
+### Dispatcher results (after booking)
+
+| Result | Required state change |
+| ------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `accepted_running` | add ids to `acceptedMessageIds`; correlated drain events move them to consumed |
+| `delivery_race` | `queueExternalInput` returned false or the run began finishing; rebook unaccepted ids |
+| `busy_other_thread` | leave queued and expose the active thread id; do not mutate admission outcome |
+| `capacity_wait` | leave queued and expose runtime-capacity backpressure; do not consume a launch attempt |
+| `started` | bind the run/session, prompt watermark, and transcript start atomically |
+| `launch_failed` | mark terminal `failed` with typed `failureStage`; release pending capacity and notify after retry policy |
+| `cancelled` | mark queued runs cancelled immediately; request runtime cancellation for running work |
+| `unclosed_run` | preserve final text and commit consumed input; if no successor is runnable, block instead of guessing done |
+
+The booking outcome and dispatcher result are intentionally separate. A durable
+queued run remains true until changed under lock; "busy right now" is an
+ephemeral observation. That is the reason there is no rules-layer `defer` — not
+because the rules know nothing about run state (coalescing and queue limits
+plainly do). Across threads, the dispatcher scans all queued runs for an agent
+and selects the minimum `(queueSequence, runId)` so leaving work queued cannot
+create file-order starvation or inherit caller clock skew. Registry capacity is
+the same kind of momentary fact and
+therefore appears as dispatcher result `capacity_wait`, not an admission reason
+or terminal launch failure. `thread_wait()` is unrelated: it is an explicit,
+durable workflow close after delegation, not a scheduler prediction about when
+an already-booked run can start.
+
+All mesh mutations take one workspace lock in v1. At this scale, serial writes
+are cheaper and safer than a lock hierarchy across agent, root, child, and
+outbox files. It makes cross-thread pending counts and root-token reads
+authoritative at the instant they are read; it does not provide cross-file crash
+atomicity, which is handled by the outbox protocol in §3. `otherThreads` is not
+an optional caller hint in the final API.
+The daemon scans durable unaccepted triggers and outbox events after startup and
+periodically, so a crash between a successful file write and an in-process wake
+notification only adds latency.
+
+### Status transition matrix
+
+| Action | Allowed from | Result and durable side effects |
+| ----------------------------------------------------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| first successful booking/delivery | `open` | `in_progress` |
+| human feedback that successfully books/delivers | `blocked`, `in_review` | acknowledge applicable blockers/review candidates, set `in_progress`, reset only this thread's turn count; target scope remains §9.11 |
+| `thread_wait()` from the bound run with another live run (excluding itself) or child dependency | `open`, `in_progress` | record `closeKind=waiting`, mark run `finishing`, keep `in_progress`; no person notification |
+| `thread_wait()` without a live dependency | `open`, `in_progress` | reject; the agent must block, review, or continue working |
+| `thread_block(question)` from the bound run | `open`, `in_progress` | append question, record `closeKind=blocked`, mark run `finishing`, enqueue blocker notification atomically |
+| `thread_review(summary)` from the bound run | `open`, `in_progress` | append summary, record `closeKind=review`, mark run `finishing` atomically |
+| any admission books/delivers nothing and leaves no runnable target | any non-`done` | persist all outcomes, set `blocked`, enqueue one deduplicated notification; includes gates, unavailable/unknown assignees, and `no_target` |
+| terminal launch/execution failure leaves no runnable target | any non-`done` | append system failure, set `blocked`, enqueue failure notification |
+| clean run exit without `thread_block`/`thread_review` | `in_progress` | append final text, commit consumed input, record `closeKind=unclosed`; block only if no successor is runnable |
+| human marks done with a non-done descendant | any non-`done` | refuse and return the descendant ids; v1 never silently cascades |
+| human marks done with no non-done descendant | any non-`done` | set `done`, cancel queued runs, request running cancellation |
+| any late post | `done` | append for audit, persist `thread_done`, never book or reopen |
+
+Thread status is an aggregate, not last-writer-wins. While any run is queued,
+running, or finishing, the thread stays `in_progress` (unless a person set
+`done`). At quiescence, an unacknowledged blocker, terminal failure, unclosed
+run, or wait whose dependency vanished without a bookable parent event takes
+precedence and yields `blocked`; otherwise at least one unacknowledged review
+close yields `in_review` and emits the parent report. A same-thread wait is
+acknowledged by any later close record or human post on that thread. Any later
+successful booking acknowledges earlier terminal failure and unclosed records;
+otherwise a recovered workflow could remain pinned by an obsolete failure after
+useful work continued. A successfully booked parent dependency event
+acknowledges the matching cross-thread wait. Human blocker acknowledgement
+remains target-scoped product work in §9.11. This defines the cases where one
+agent waits, blocks, or reviews while another is still working without inventing
+a separate blocker object.
+
+All transition checks and same-thread side effects happen under the workspace
+lock. Parent reports and channel sends leave through the outbox because they
+cannot be atomic with that file. Repeated reconciliation uses the event id,
+message id, and run id as idempotency keys. The tool cannot mark its own
+still-executing runtime completed: it moves the run to `finishing`, causes the
+agent turn to terminate, and the runtime callback records the terminal state.
+`cancelling` serves the same restart-safe purpose for a human stop.
+
+Agent-caused work is charged when it books a new run or records delivery intent
+for a running run. A delivery race rebooks that same charged intent; it does not
+charge again. Coalescing into an unstarted run is free because it starts no extra
+turn. A human post resets only that thread's turn count. Tokens are derived from
+idempotent per-round usage entries on runs across the root's tree and never
+reset.
+
+`assigneeAgentId` controls fallback routing only. Reassignment emits one
+structured trigger to the new assignee and affects future posts; it does not
+cancel work already accepted by other agents. Unassignment emits no trigger.
+Structured assignment and parent-dependency events are system-authored but retain
+their causing human action or agent run, so they are charged correctly without
+being suppressed as ordinary self-authored posts.
+Only a direct human mutation on this thread resets its turn counter. A
+cross-thread dependency event remains an unattended delivery even when a human
+action on the child caused it.
+
+## 5. Module map
+
+Pre-existing on this branch (five production files plus two tests; nothing
+starts an agent yet):
+
+| File | Responsibility |
+| ----------------------------------------- | ---------------------------------------------- |
+| `core/src/agents/mesh/types.ts` | Entities and limits |
+| `core/src/agents/mesh/mesh-store.ts` | Paths, validation, locking, CRUD |
+| `core/src/agents/mesh/mentions.ts` | `@name` → agent ids |
+| `core/src/agents/mesh/dispatch-policy.ts` | `decideDispatch` — pure |
+| `core/src/agents/mesh/thread-actions.ts` | `postMessage` — append and book under one lock |
+
+### 5.1 Local review correction — committed and verified
+
+1. Store validation accepts `blocked`; missing roots fail closed; a child
+ inherits its parent's current turn count; deletion refuses active runs and
+ thread trees that would orphan descendants. Retention never drops an active
+ run or a message it still references.
+2. Turn gating is local to one thread while token gating reads the root. Human
+ posts reset only the local turn count; the token cap is not bypassed.
+3. An unknown explicit mention suppresses assignee fallback and produces
+ `agent_unknown`; an unassigned post produces `no_target`.
+4. `coalesce(running)` from an agent charges a turn. `queueLimit` counts pending
+ runs only, so its name and arithmetic agree.
+5. Stale daemon-session comments and the unreachable `explicit_routing` outcome
+ were removed. The latter remains a target-resolution rule.
+
+This is still only the admission foundation. Delivery acknowledgement,
+assignment triggers, status commands, provenance, and transcript slices are
+scheduled below rather than represented by dead optional fields.
+
+### 5.2 Order of work
+
+Dependencies, with an early vertical proof before reliability and UI breadth.
+
+1. **Local admission foundation** — landed in this PR: storage validation,
+ mention routing, budget gates, coalescing, retention, and atomic per-thread
+ booking. It still has no launcher or dispatcher.
+2. **Capability boundary** — built-in read-only shell allowlist intersected
+ with the agent definition. Explicitly exclude `save_memory`, context-file
+ writes, and every persistent-write tool. Prove disallowed commands cannot
+ reach execution.
+3. **Versioned storage protocol** — add `schemaVersion`, the workspace mutation
+ lock, lock-issued run queue sequence, atomic same-thread booking, parent/
+ notification outbox replay, and fail-closed migration before any new process
+ writes the expanded model. Token usage stays on source run records.
+4. **Hidden host session, keepalive, and programmatic launcher** — create the
+ workspace `Config` and registry owner, then extract the smallest persona'd
+ launch path. Prove resident continue and transcript-backed revive separately;
+ definition absence produces `agent_unavailable`, while registry saturation
+ produces `capacity_wait`. The typed continuation preparation is integrated
+ in this PR.
+5. **Run envelope and tools** — add the §3 delivery/provenance fields, prompt
+ assembler, correlated mesh external-input/consumed events, per-turn ambient
+ mesh context, incremental run usage recording, and minimal `thread_post`,
+ `thread_wait`, `thread_block`, `thread_review`, and `thread_read` tools. No
+ model-supplied mutation thread, author, run, or idempotency id.
+6. **Minimal in-process dispatcher, no recovery** — pick one queued run per
+ agent by `queueSequence`; launch, continue resident, resume `paused`, or cold
+ revive; call `startRun`/`finishRun`; and consume the parent-report outbox.
+ Handle `capacity_wait` by leaving the run queued. This is intentionally the
+ smallest dispatcher that can make the next step executable.
+7. **Minimal live vertical slice** — assigned parent → launch → assigned child →
+ parent wait → child review → parent dependency wake → parent review. Run it
+ against two live agents before building the full daemon; this is the first
+ proof that the chosen reuse seam, prompt contract, and delegation close loop
+ work together.
+8. **Dispatcher reliability** — direct running delivery,
+ acceptance recording, completion reconciliation, launch failure, done/
+ cancellation, restart and stall recovery, and full outbox replay.
+9. **REST routes and Web Shell** — roster, thread list/view, busy reason, gates,
+ failures, cancellation, and transcript slices; absorb #11140's entry.
+10. **Channel notifications** for blocker raised, aggregate in_review, gate
+ tripped, and terminal failure. Last because it consumes state transitions
+ proven by steps 7-9.
+
+Steps 1-6 are unit-testable. Step 7 is the early integration gate; step 8 adds
+failure injection and restart tests; step 9 adds daemon/browser tests.
+
+### 5.3 Acceptance
+
+Evidence for the committed admission foundation only:
+
+```bash
+cd packages/core
+npx vitest run src/agents/mesh/mentions.test.ts \
+ src/agents/mesh/dispatch-policy.test.ts \
+ src/agents/mesh/thread-actions.test.ts
+# 3 files, 37 tests passed
+```
+
+Targeted lint and core typecheck also pass on the current branch. They establish
+compile/style health only; they do not validate the design or the unbuilt
+execution path. Update the test count above if the foundation changes.
+
+Future unit coverage is required for: all twelve admission outcomes; unknown
+mention suppressing assignee fallback; assignment and parent-dependency triggers;
+mixed known/unknown mentions; reassignment with already-booked work; aggregate
+status with two agents; valid and orphaned `thread_wait`; child dependency wake;
+per-thread turns plus idempotent per-round run usage; all dispatcher
+results; FIFO ties; delivery acceptance/reconciliation; prompt assembly across
+first entry, compaction, retention gap and duplicate replay; transcript ranges;
+enqueue success followed by a crash before the consumed event; exact tool-call
+retry deduplication; and ambient context rejecting model-supplied mutation
+thread/author identity.
+
+Beyond unit tests, the design is only proven by the §8 demo run against a live
+model, plus negative cases shown deliberately: ping-pong (including two running
+agents) trips the turn gate; `queueExternalInput(false)` is rebooked; a run killed
+after acceptance is replayed on restart; a crash at every cross-file outbox edge
+neither loses nor duplicates an effect; runtime saturation waits without
+consuming an attempt; a launch failure releases capacity; one agent reviewing
+does not hide another still running; a human reply on one child does not reset a
+sibling; parent done refuses a live child; and marking a leaf done stops its
+queued and running work.
+
+Still to build:
+
+| Piece | Where |
+| ----------------------------------------------------------------------------------------------------------- | -------------------------------------- |
+| Read-only shell boundary | `core/src/agents/mesh/` |
+| Versioned workspace record, migration, workspace lock, and cross-file outbox protocol | `core/src/agents/mesh/` |
+| Hidden host-session owner and programmatic launcher | `core/src/agents/` |
+| Run envelope, delivery state, prompt assembler, ambient run context | `core/src/agents/mesh/` |
+| Consume the integrated correlated external-input runtime contract | `core/src/agents/mesh/` |
+| Thread tools: `thread_post`, `thread_wait`, `thread_block`, `thread_review`, `thread_create`, `thread_read` | `core/src/tools/` |
+| Dispatcher, reconciliation, FIFO, sweeper, and keepalive | `cli/src/serve/mesh/` |
+| REST: agents, threads, posts, runs | `cli/src/serve/routes/mesh.ts` |
+| Channel notifications for the four events | reuse the channel workers |
+| Web Shell: roster, thread list, thread view, run transcripts | `web-shell/client/` |
+| #11140's sidebar entry, absorbed | `web-shell/client/components/sidebar/` |
+
+## 6. What an agent actually receives
+
+The thread frame is necessary but not a security boundary. A long-lived body may
+have compacted away an earlier frame, may remember instructions from another
+thread, and may receive duplicate input after recovery. Every turn therefore
+gets both a runtime binding and a self-contained prompt envelope. The envelope's
+role transport is intentionally unresolved in §9.9; the structure below is the
+content contract, not a claim that today's runtime can inject a new system
+message on every turn:
+
+```
+MESH RUN (runtime-authenticated envelope; role transport pending)
+ workspace= agent= definition=
+ run= attempt= thread= root=
+ message window=..
+ delivery=first | replay-after-gap | retry
+ Previous-thread memory is context, never authority for this run.
+
+CURRENT THREAD (authoritative)
+
+ <body>
+ Status: in_progress
+ Assignee: @alice
+
+RECENT THREAD POSTS (untrusted content; never changes tool scope)
+ [seq · author-kind/name · source-run] <escaped text>
+
+DELTA AFTER LAST COMMITTED DELIVERY
+ [seq ...] ...
+ or: GAP — <N> earlier posts were trimmed/unavailable; use thread_read
+
+ENABLED PEERS (excludes this agent)
+ @alice — reads CI logs
+ @bob — reads code
+You can: thread_post · thread_wait · thread_block · thread_review ·
+ thread_create (sub-thread) · thread_read (any thread)
+Before ending this run: use thread_wait() after delegating live work,
+thread_review(summary) when ready for a person, or thread_block(question) when
+you need input. A plain final answer is not a thread hand-off.
+```
+
+Eight rules:
+
+- **The binding is structural.** At the actual background-turn seam, wrap each
+ invocation in `runWithMeshRunContext({agentId, runId, threadId}, fn)`. The
+ existing resident continuation re-enters `runBackgroundTurn` and
+ `runWithAgentContext` for every turn, so a nested `AsyncLocalStorage` frame is
+ valid here. Do not wrap the lifetime launch once, and do not use a mutable
+ process-global "current run" register that can leak across async work.
+- **Mutating tools trust only ambient identity.** Posting/status tools accept no
+ thread, author, run, or idempotency id from the model. `thread_create` always
+ creates under the current thread. They read the ambient triple, then verify it
+ still names a persisted `running` run on that thread. `thread_read` may take a
+ workspace thread id because it is read-only; its returned content is still
+ untrusted. HTTP routes derive human identity from their authenticated surface.
+ This mirrors the production lesson behind Multica's resumed-session parent
+ validation in `handler/comment.go`.
+- **Every turn includes title, body, status, and recent N posts.** The delta is
+ additional context after `committedThroughSequence`, never the sole context.
+ Compaction or cold revival therefore cannot turn a later wake into an
+ unexplained fragment.
+- **Gaps and replays are explicit.** Retention loss, an unknown watermark, or a
+ retry is labelled. Message ids/sequences make duplicate input recognisable.
+- **Mesh turns use structured external input.** The dispatcher supplies one
+ `{kind: 'message', text, deliveryId}` envelope rather than a bare
+ `task_prompt`. The correlated consumed event and transcript record retain the
+ delivery id. Ordinary background-agent continuations may keep their legacy
+ string path; they are not durable mesh deliveries.
+- **Trust comes from runtime binding, not a heading.** Today's resident chat has
+ no per-turn system-role injection seam. Product must choose between a fixed
+ user-role prefix whose authority is established by the ambient binding plus
+ the original system instruction, or a new system-update mechanism that
+ invalidates prompt caching. Until §9.9 is decided, no implementation may label
+ a user-role heading "trusted" and treat that label as a boundary. Title, body,
+ and posts remain attributed user data; provenance stops identity spoofing but
+ does not make their instructions safe.
+- **Mention tokens are handed over verbatim for enabled peers only**, excluding
+ self. Unknown/disabled targets are surfaced by routing rather than wasting a
+ model turn.
+- **A run must close explicitly.** The prompt requires `thread_wait`,
+ `thread_review`, or `thread_block`. Runtime final text is still captured, but
+ a run that exits without one is a visible `unclosed_run`, never implicit
+ success. `thread_wait` is rejected unless another live run or child dependency
+ can wake the thread later.
+
+Token accounting persists each run's per-round usage and sums it across the
+root tree; the terminal registry stats delta is only a reconciliation check.
+Transcript start/end byte offsets are captured around the flushed append-only
+writer so the UI can render the run slice without pretending the agent's entire
+cross-thread memory belongs to one thread.
+
+## 7. How this compares to Multica
+
+Four kinds of difference, and they are not the same kind of thing.
+
+**Different memory scope.** Multica's `PriorSessionID` is selected by
+`GetLastTaskSession{AgentID, IssueID}`. This design intentionally keeps one body
+across threads. That is stronger colleague-like memory, but it creates a
+cross-thread confusion and trust surface Multica structurally avoids.
+
+**Potentially lower steering latency, once reconciled.** Multica reports
+`ReasonAlreadyActive` and relies on completion reconciliation. Qwen Code can use
+`registry.queueExternalInput` to land correlated mesh input at the next
+tool-round boundary. That is an advantage only after queue acceptance, consumed
+events, finishing races, failures, and restart paths meet the at-least-once
+contract in §4.
+
+**Different wake transport.** Multica's `taskWakeupLoop` uses WebSocket push
+with an HTTP polling fallback. Calling it either "polling" or "not polling" is
+incomplete.
+
+**Deliberately not built.** Writing code, branches, PRs and review gates
+(decision 1 — read-only until isolation is settled); multi-user roles and access
+scopes; self-hosting and multi-tenancy; Projects grouping several repos.
+
+**Deliberately looser invocation.** Multica rechecks per-agent invocation and
+source-task attribution at every hop (`ReasonInvocationNotAllowed`,
+`ReasonAttributionBlocked`). V1 here permits any agent to mention any enabled
+workspace peer, but still records non-spoofable source-run provenance.
+
+**Missing and worth having.** Runtime binding — agents that run on another
+machine or in the cloud, and agents that are not Qwen Code — is the one hard
+gap. Scheduled and external-event triggers are absent but the cron scheduler and
+channel workers already exist to carry them. Board views, labels, search and
+cross-issue references have no equivalent.
+
+| Capability | Target reach | Note |
+| -------------------------------- | ------------ | ------------------------------------------------------------------------------------------------ |
+| Multi-agent collaboration itself | ~85% | routing, hand-off, sub-thread reporting, serialisation, gates; mid-run steering remains unproved |
+| Run records and observability | ~80% | shared transcript with per-run slices, per-run tokens, retry and timeout are designed, not built |
+| Skills | ~70% | carried by the agent definition |
+| Agent identity | ~50% | identity, persona, enable/disable, workload — runtime binding is zero |
+| Triggers | ~50% | assignment and `@`; scheduled and external events unconnected |
+| Work items | ~40% | assignable item with conversation and status; no board, labels or search |
+| Notifications | ~40% | four events to existing channels; no inbox |
+| Multiple surfaces | ~30% | Web Shell and desktop shell |
+| Projects | ~15% | a workspace is one cwd |
+| Multi-user, self-hosting | ~5% | single user, single machine |
+| Producing code changes | 0% | decision 1 |
+
+As a target product, roughly 35-40%. That number mixes two unlike things: Multica is a
+multi-user server product (Go, Postgres, tenancy, self-hosting) and this is a
+single-machine daemon over files. Most of the remaining 60% is that category
+difference, not a backlog.
+
+**Measured against multi-agent collaboration itself — hand-off, observability,
+steering, guardrails — the target reaches roughly 80%**, which is the part that
+was actually asked for. The implementation is still only at §5.2 step 1.
+
+## 8. Demo
+
+Two agents investigating a real problem, with a person steering.
+
+1. Declare two agents in the workspace — one that reads CI logs, one that reads
+ code — each on an existing read-only agent definition.
+2. Open a thread: _"The web-shell smoke test is flaky. Find out why."_, assign
+ the log reader. Assignment starts it.
+3. It posts a hypothesis, creates a code-reading sub-thread assigned to the
+ second agent, then calls `thread_wait()`. The parent body is released while
+ the structured assignment wakes the child agent.
+4. The person interjects on the child mid-run: "check the retry logic first". A
+ successful direct enqueue lands at the next tool boundary; a forced enqueue
+ miss is visibly rebooked and delivered after the current run.
+5. The code reader reviews the child. Its durable parent dependency report wakes
+ the waiting log reader, which integrates the result and reviews the parent;
+ the person marks the child and then the parent `done`.
+6. Separately: show a synthetic running-agent ping-pong tripping the turn gate,
+ and an atomic blocked question producing its channel notification. Both
+ guards visible, not theoretical.
+
+Captured with the web-shell Playwright visuals config, which renders real
+screenshots locally and in CI.
+
+## 9. What remains genuinely open
+
+The review closed several ambiguities, but these product or storage questions
+remain genuinely open:
+
+1. **Persistent cross-thread prompt injection.** Provenance and a trusted run
+ envelope stop spoofing and wrong-thread actions; they cannot make a model
+ forget a malicious or simply wrong instruction learned in thread A before it
+ works on B. Read-only tools and budgets limit impact, not trust. Write access
+ must remain out of scope until this has an explicit policy and adversarial
+ test suite.
+2. **Retention and delivery history.** `MAX_THREAD_MESSAGES` /
+ `MAX_THREAD_RUNS` retain active references but trim old terminal history. The
+ dispatcher must record the first retained sequence and emit a gap; whether
+ full history moves to a separate append-only archive is undecided.
+3. **Cancellation UX.** Done now has defined cancellation semantics, but the
+ user-facing choice between graceful stop and immediate abort, and what partial
+ output should be posted, remains to be designed.
+4. **Persona/version drift.** An agent definition may change while its body is
+ resident. The live runtime keeps the old prompt/tools/model, while the roster
+ points at the new definition. Decide whether edits force a controlled restart
+ after the current run, or apply only when the body next revives. Every run
+ records the active definition content hash and the UI exposes it either way.
+5. **Concurrent token charging.** The workspace lock makes completed charges
+ consistent, but token usage becomes known only after a run. Several agents in
+ the same thread tree can already be executing when the root reaches 200k.
+ Decide whether 200k is a hard reservation limit (reserve estimated tokens at
+ booking) or an accounting limit with bounded overshoot. Runtime compaction
+ calls and usage emitted before a provider retry are not represented by
+ `USAGE_METADATA`; the UI/accounting contract must either accept that
+ undercount or add a broader usage source.
+6. **Selective forgetting.** Deleting a thread removes its record but cannot
+ remove facts already compacted into a cross-thread agent body. Decision 8 can
+ guarantee forgetting only by deleting the whole agent and transcript; whether
+ users need thread-level forgetting is unresolved.
+7. **Semantic duplicates after replay.** Exact retries of one tool call are
+ deduplicated, but replaying accepted input after a process crash can make the
+ model independently repeat a post, mention, or child-thread creation. The
+ system can preserve provenance and show that it was a retry; child creation
+ should additionally deduplicate an exact `(parentThreadId, normalizedTitle)`
+ retry. Whether the UI should offer broader semantic duplicate collapse is
+ undecided. Silent loss remains worse than a visible duplicate.
+8. **System-prompt provenance and drift.** QWEN.md, the agent definition, and
+ auto-memory all enter the system prompt at higher trust than thread posts.
+ Another session can change them while a resident body keeps the old prompt.
+ Each run needs a version stamp covering all three inputs plus a visible gap
+ when the source cannot be reconstructed; hashing only the agent definition is
+ insufficient. V1 prevents mesh agents from writing auto-memory but cannot
+ prevent other sessions from changing it.
+9. **Per-turn envelope role (C3; product decision).** Keep the envelope as a
+ fixed prefix in the user-role structured input, with authority established by
+ the ambient binding and original system instruction, or add a per-turn system
+ update and accept prompt-cache invalidation. The current runtime provides no
+ third option and the implementation must not choose silently.
+10. **Parent-to-child replies (I3; product decision).** Decide whether an agent
+ may post into descendant threads it created, with ambient provenance, or
+ whether only people can unblock a child. Ambient-thread-only mutation is
+ safer but leaves a parent unable to answer its own child's blocker.
+11. **Human blocker acknowledgement scope (S5; product decision).** A human
+ reply aimed at `@bob` must not silently clear an unrelated question raised
+ by Alice. Decide whether acknowledgement follows mentioned targets, the
+ assignee, or an explicit blocker id.
+
+## 10. Out of scope
+
+Real OS-process isolation and cross-machine agents (#10078's session-boundary
+decision and #10247 §5's stalled wiring choice); durable history after a thread
+is deleted; remote and cloud runtimes; multi-user permissions; and agents that
+write code, which decision 1 defers until isolation is settled.
+
+<details>
+<summary>中文说明</summary>
+
+**这是什么**：持久的 Agent 身份在共享线程上协作。人开一个线程、指派一个 agent，之后 agent 们自己读、发帖、互相 @、拆子线程、干完交回验收，人随时可以插话。就是 Multica 那套形态，但建立在 qwen 已有的机器上。Agent Team 原封不动保留，作为单次 run 内部的紧耦合协作手段。
+
+**源码纠错**：Multica 的延续会话是 `(agent, issue)` 维度，WebSocket 唤醒同时保留 HTTP polling fallback；active run 收不到新评论，但完成时会 reconcile，并不是丢弃。Qwen 的运行中送信也不能调用 `resumeBackgroundAgent`，而要走 registry 的直接输入队列；mesh 需用带 delivery id 的 `queueExternalInput`，分别记录「队列接受」和 `EXTERNAL_MESSAGE` 的「实际消费」，并处理 finishing 窗口返回 `false`。所以「更快中途纠偏」只是待端到端证明的潜在优势，投递可靠性不能先假定。
+
+**执行模型**：本方案仍选择「每工作空间每 agent 一个跨线程长期后台执行体」，这是主动区别于 Multica 的产品选择。好处是同事式长期记忆；代价是串行吞吐、跨线程串台和持久化 prompt 注入。每次 turn 都必须在真正的 background-turn 调用点重新绑定 `(agent, run, thread)`，工具只信 ambient binding，prompt 每次都带完整线程帧、最近消息、确认水位后的增量和明确 gap。
+
+**规则修正**：turn gate 改为每线程，token gate 保持根树维度；子线程继承父线程当前 turn 计数；running coalesce 也计 turn；未知 @ 不再误唤醒 assignee；无目标、agent unavailable、capacity wait、launch failure、done/cancel、assignment trigger 都有明确语义；跨线程 queued run 按锁内分配的 `(queueSequence, runId)` 全局 FIFO，`queuedAt` 只用于显示。全局锁只处理并发，跨文件父报告和通知由可重放 outbox 保证，token 则从各 run 的逐轮 usage 推导；`blocked/in_review` 按所有 agent 的 run 聚合，不再由最后一个 agent 覆盖。
+
+**验证边界**：当前规则/存储层已有定向测试、类型与 lint 证据；launcher、线程工具、dispatcher、delivery watermark、恢复、REST、Web Shell、通知都还没端到端跑通。§5.2 把 live vertical slice 提前，§9 记录 11 个仍需产品或存储取舍的问题。
+
+</details>
diff --git a/docs/plans/2026-09-07-mesh-review-round2-handoff.md b/docs/plans/2026-09-07-mesh-review-round2-handoff.md
new file mode 100644
index 00000000000..cddce83e577
--- /dev/null
+++ b/docs/plans/2026-09-07-mesh-review-round2-handoff.md
@@ -0,0 +1,152 @@
+# Mesh design review, round 2 — hand-off to the implementing agent
+
+> Reviewed: [`2026-09-06-multi-agent-board-collaboration.md`](./2026-09-06-multi-agent-board-collaboration.md) at `af7fed7021e94b83df3aa013fd4dae3b2a0357e1` (PR #11072)
+> Runtime facts checked against `origin/main` @ `703678136a`; Multica against `multica-ai/multica@7a438bd5b`
+> Original review method: source reading only. The implementation update and §4 observations explicitly identify the later checks that were executed. Every `file:line` below was read at the commits named above; line numbers drift, symbols do not.
+> Audience: the agent that implements §5.2. Read §0 of the design first, then this file.
+
+## 0. Verdict
+
+**Keep the root model; change the contract.** Long-lived body + shared thread + admission/dispatcher split + at-least-once delivery survives source inspection. Round 2 identified three contract problems (C1–C3), not a reason to change the execution model; the implementation update below supersedes C1 and corrects C2's premise.
+
+State at the reviewed commit: the seven files under `packages/core/src/agents/mesh/` at `af7fed70` are byte-identical to the round-1 revision. The §5.1 "verified but uncommitted" patch was not on that branch, and the four named store defects were still present. The implementation update below records the later correction.
+
+### Implementation update (2026-09-07)
+
+- The missing §5.1 patch is now committed in #11072; its three named files pass 37 tests, plus targeted lint and core typecheck.
+- C1 reproduced as usage rounds `[1, 1]` across two execute segments and is fixed to `[1, 2]` in the current PR.
+- C2 contained a false premise: current `AgentHeadless.executeTurn` already emits `EXTERNAL_MESSAGE` for resident `task_prompt` continuations, and cold revival seeds `initialUserPrompt`. What was actually missing was durable correlation. The current PR adds `deliveryId` to structured external input, the consumed event, resident structured continuation, and the transcript record.
+- I5's boolean ambiguity is fixed in the current PR. The design now inserts a minimal dispatcher before the live slice and gives `paused` its actual `resumeBackgroundAgent` path.
+- I1, I2, I4, I6, I7, I8, and I10 are corrected in the authoritative design. Their aggregate/storage/dispatcher producers do not exist yet, so no dead optional fields were added to the foundation.
+- C3, I3, and S5 remain explicit product decisions. No implementation choice was made for them.
+
+## 1. Runtime facts the implementation must not re-derive
+
+These are the load-bearing seams. Each was read directly.
+
+| Fact | Where | Consequence for the mesh |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `resumeBackgroundAgent` returns an already-running entry without consuming the continuation message | `background-agent-resume.ts:783-791`; the `queueMessage` at `:609` fires only when a resume is already in flight | Mid-run delivery is `registry.queueExternalInput`; idle-resident is `continueResidentAgent`; cold is revive/resume. Same split as `tools/send-message.ts:295-341` |
+| `queueExternalInput` returns `false` when not `running` or after `beginFinishing` | `background-tasks.ts:1515-1522` | `delivery_race` in the design is the right shape |
+| Final drain and `beginFinishing` are adjacent synchronous calls | `agent.ts:3576-3586`, `background-agent-resume.ts:1294-1300` | The finishing window is closed at the runtime; no extra guard needed |
+| `EXTERNAL_MESSAGE` is emitted when input is appended to the next request, **before** the model call | `agent-core.ts:1249-1262`, `:1269-1274`, `:1296` | "consumed" means _durably in history_, not _answered_. Write the definition that way |
+| The transcript writer records external messages synchronously with `fs.writeSync` | `agent-transcript.ts:711`, `:838-840` | A crash after drain does not lose the message: cold revive replays it |
+| `AgentExternalMessageEvent` carries only `kind` and `text` | `agent-events.ts:195-202`, `agent-core.ts:1405-1412` | A `deliveryId` must be added to the structured `AgentExternalInput` and threaded through `emitExternalInputEvents` |
+| String inputs get the `[Message from parent agent]:` prefix; structured inputs do not | `agent-core.ts:1382` | Use the structured form |
+| Resident continuation re-enters `runBackgroundTurn` → `runWithAgentContext` on every turn | `background-agent-resume.ts:1389-1401`, `:1418-1487`; launch path `agent.ts:3738-3760` | A nested `runWithMeshRunContext` per turn is valid. `finishingInputs` continuation runs inside the same closure, same run |
+| `continueResidentAgent` requires `status === 'completed'`; `continue()` returns `false` for five different reasons | `background-tasks.ts` (`continueResidentAgent`), `background-agent-resume.ts:1419-1450` | The dispatcher cannot tell `capacity_wait` from "fall back to revive" from a boolean. Add a typed result |
+| Restart-recovered running agents are registered as `paused`, not `completed` | `background-agent-resume.ts:561` | Sweeper "revive once" must call `resumeBackgroundAgent` for `paused`; `reviveCompletedBackgroundAgent` rejects them |
+| The concurrency cap **throws** from `register` | `background-tasks.ts:559`, `:579` | The launcher must catch to produce `capacity_wait`. Whether idle resident agents hold a "claimed" slot was **not** verified — read `getClaimedBackgroundSlotCount` |
+| The chat is created once and reused; system instruction is fixed at `createChat` | `agent-headless.ts:296-299`, `agent-core.ts:588-595` | There is no per-turn system-role seam. Every continuation enters as user role via `task_prompt` |
+| Resident continuation prompts are written through `EXTERNAL_MESSAGE`; cold revival also seeds `initialUserPrompt` | `agent-headless.ts:279-288`; `background-agent-resume.ts` (`writerInitialPrompt`, `buildAgentTranscriptAttach`) | The original C2 transcript-absence claim was wrong. Mesh still needs structured input with `deliveryId` for correlation |
+| `USAGE_METADATA.round` is `turnCounter`, which restarts at 0 per `runReasoningLoop`; `roundOffset` only feeds `executionStats.rounds` | `agent-core.ts:920`, `:1198`, `:2695` | See C1 |
+| Usage is recorded once per round from the last chunk, after `ROUND_TEXT` (which carries `usageMetadata` into the transcript) and before tool execution | `agent-core.ts:1099`, `:1195-1210` | Transcript-first, event-second: the design's "reconstruct from transcript" direction holds |
+| Retry inside a stream resets `lastUsage`; compaction's own call emits no usage | `agent-core.ts:1050`, `:1058-1067` | Token gate under-counts. Call it an accounting limit |
+| `runReasoningLoop` is invoked a second time inside one run when the final drain finds pending input (`executeExternalInputs(..., {resetStats:false})`) | `background-agent-resume.ts:1255-1261`; `agent-headless.ts:246-255` | Any per-run key that uses `round` collides across the two segments |
+| The system prompt is assembled with QWEN.md and auto-memory | `agent-core.ts:2646-2650` (`assembleSystemPrompt` with `getUserMemory`, `getAutoMemoryPrompt`) | See I8 and open question 8 |
+| `save_memory` exists as a tool | `tool-names.ts:29` | Must be excluded by the read-only boundary |
+| Multica's prior session is per `(agent, issue)` | `handler/daemon.go` `GetLastTaskSession{AgentID, IssueID}`; `daemon/types.go:108` | Already corrected in the design |
+| Multica allows a run to comment on **another** issue, carrying lineage | `handler/comment.go:1775-1790` (`source_task_id` deliberately not scoped to the run's own issue) | See I3 |
+| Multica gates every hop on attribution and invocation policy | `comment.go:2261`, `:2352` (`ReasonAttributionBlocked`), `:3158-3212` (`ReasonInvocationNotAllowed`) | Design §7 records the looser choice; fine |
+
+## 2. Findings
+
+Status labels: **closed** (design now matches source), **defect** (design or code is wrong), **product** (a choice the owner must make), **e2e** (cannot be settled by reading).
+
+### Critical
+
+**C1 — defect. `(runId, attempt, round)` charge key collides and silently drops token charges.**
+`USAGE_METADATA.round` restarts per `runReasoningLoop`. The runtime itself invokes the loop twice inside one mesh run when the final drain finds pending input (the normal mid-run delivery path). Second-segment rounds 1..n carry the same key as the first segment; the idempotent apply discards them. `agentRound` in the transcript is the same counter, so reconstruction collides too.
+Fix (one of): emit `roundOffset + turnCounter` in the event (stats already compute it), or add an execute-segment ordinal (count `START` events per run) to the key.
+
+**C2 — corrected defect. Resident prompts already reach the transcript; durable delivery correlation was missing.**
+The original review overlooked the continuation branch in `AgentHeadless.executeTurn` and the cold-revive `initialUserPrompt`. Runtime verification found both prompts in their expected records. Mesh nevertheless must deliver each durable turn window as a structured `AgentExternalInput` with a `deliveryId`, because bare `task_prompt` has no stable consumed watermark and receives the parent-agent prefix. The integrated runtime change adds that structured path and correlation metadata without rewriting ordinary background-agent continuation.
+
+**C3 — product + runtime. The "trusted envelope in system/developer role" has no injection point.**
+Either state that the envelope is a fixed prefix of a user-role message and that trust comes from ambient binding and provenance, not from role; or schedule a per-turn system-instruction update on `LlmChat` and record the prompt-cache cost (Multica works to keep that cache warm, `daemon/prompt.go` around `PriorSessionID`). Do not claim both.
+
+### Important
+
+**I1 — defect. Same-thread `thread_wait` has no acknowledgement rule.** Only a booked parent dependency event acknowledges a wait. A waits for B on the same thread; B closes with `thread_review` and does not `@A`. At quiescence A's wait counts as "dependency vanished", blocked-class outranks review-class, thread becomes `blocked` instead of `in_review`. Add: a same-thread wait is acknowledged by any later close record or human post on that thread.
+
+**I2 — defect. Failure and unclosed records are acknowledged only by human feedback.** One terminal launch failure pins the thread to `blocked` even after another agent later reviews. The acknowledgement boundary must include any later successful booking, not only a human post.
+
+**I3 — product. A parent agent cannot answer its child.** Mutating tools act only on the ambient thread; `thread_create` only nests under the current one. A child that `thread_block`s wakes the parent assignee, who can only post on the parent. Multica lets a run comment on another issue with lineage (`comment.go:1775-1790`). Decide: allow posting into descendants the run created (still provenance-stamped), or write down that children are unblocked by people only.
+
+**I4 — defect / simplification. Token outbox is both underspecified and unnecessary.** "Admission drains pending charge events for the root" needs a tree scan because source-first events live in the run's thread file. Smaller model: write per-round usage on the run record (same file, atomic), sum `runs[].usage` across the tree under the workspace lock at admission, keep root `tokensUsed` as a cache. `appliedTokenChargeIds`, `chargedUsageRounds`, and the token outbox disappear. Keep the outbox for parent reports and notifications only.
+
+**I5 — defect in the plan. §5.2 step 6 cannot run.** The vertical slice needs a run picker, launch/continue/resume/revive dispatch, `finishRun`, and an outbox consumer to apply the child's report to the parent. Step 5 has none; step 7 is the full reliability build. Insert "6a — minimal in-process dispatcher, no recovery". Also give `continueResidentAgent` a typed result (see §1) so `capacity_wait` is distinguishable.
+
+**I6 — defect. A quiescent thread with no close record and no runnable target stays `in_progress` forever.** The matrix maps only turn/token/queue/unavailable gates to `blocked`. A human post whose assignee is disabled/unknown, or `no_target`, books nothing and changes nothing. Rule: any admission on a non-done thread that books nothing, at quiescence, yields `blocked`.
+
+**I7 — defect. Dispatcher "idle → continue / revive / launch" lacks `paused`.** See §1. The sweeper path in §4 is wrong as written for restart recovery.
+
+**I8 — defect. Read-only boundary omits `save_memory` and the context files.** Auto-memory is a persistent write channel shared with every session; a mesh agent writing it is a cross-agent, cross-session injection path that bypasses decision 1. Decision 2 must list it as excluded.
+
+**I9 — process. The evidence chain has a hole.** §5.3's "3 files, 37 tests passed" refers to a patch that is not on the branch. Push it or reword §0.2.
+
+**I10 — defect. FIFO key `queuedAt` is caller wall-clock.** `postMessage` uses `options.now ?? Date.now()`; tool calls run in the agent process, REST in the daemon. Use a sequence issued under the workspace lock as the primary key.
+
+### Suggestions
+
+- **S1** Infer waiting: clean exit with a live dependency = waiting, without = unclosed. Keep `thread_wait` as explicit intent but drop the rejection path; a rejected wait costs another model turn.
+- **S2** Deduplicate `thread_create` after replay by (parent, normalised title) and return the existing child. Cheaper than UI collapse and avoids double budget.
+- **S3** Record in §9.5 that compaction calls and pre-retry stream usage are outside `USAGE_METADATA`.
+- **S4** Decision 17 lets a parent at 11 turns hand a child 1 turn; the assignment trigger then trips the gate immediately. Floor it or document it.
+- **S5** A human `@bob` on a thread blocked by alice's question acknowledges alice's blocker; the question can be dropped silently. Consider acknowledging only blockers from the targeted agents or the assignee.
+- **S6** = C2 fix.
+- **S7** If `appliedTokenChargeIds` survives I4, store a high-water mark per (runId, attempt, segment) instead of an unbounded id set.
+
+### Closed since round 1 (why)
+
+- `resumeBackgroundAgent` entry point: §0.1/§1 now name the three-way split used by `send-message.ts`.
+- Finishing window: closed at the runtime (adjacent drain + `beginFinishing`) and handled as `delivery_race`.
+- Multica per-(agent, issue) session, polling fallback, `decidePostMergeMiss` replay: all stated correctly now.
+- Turn gate per thread / token per tree, `coalesce(running)` charging, system-authored parent event bypassing `self_trigger`, assignment through admission, no-defer justification, global FIFO: correct in the design; none of it is in the PR code.
+- ALS per-turn seam: verified valid; the mesh launcher must own its copy of `runBackgroundTurn` or a hook, since the existing one is a closure.
+
+## 3. Minimal change set, in order
+
+1. C1: cumulative round in `USAGE_METADATA` or a segment ordinal in the key.
+2. C2/S6: mesh deliveries use structured external input with `deliveryId`; ordinary resident prompts were already transcripted.
+3. C3: product decision pending; do not implement either transport yet.
+4. I4: derive tokens from run records; delete the token outbox and both id lists.
+5. I1, I2, I6: three lines in the aggregation rules.
+6. I5, I7: add step 6a; typed result from `continueResidentAgent`; `paused` branch.
+7. I8: exclude `save_memory`.
+8. I3 and S5: product decisions pending; keep both explicit in §9.
+9. I9: fixed by pushing the patch into #11072 and updating §0.2.
+10. I10: allocate `queueSequence` under the workspace lock in storage step 3; never sort by `queuedAt`.
+
+## 4. What only an end-to-end run can settle
+
+Run these on a machine that can build. Report the observed value, not "passed".
+
+1. `getClaimedBackgroundSlotCount` with N idle resident agents: does an idle `completed` resident hold a slot? Decides whether the cap is roster-size or throughput.
+2. `continueResidentAgent` → `false` while the resident is still registered, followed by `reviveCompletedBackgroundAgent`: does a second runtime get instantiated for the same agent? Check `registry.get(agentId)` identity and the resident map before/after.
+3. Deliver via `queueExternalInput` immediately after the model's last tool round: confirm the final drain picks it up and `executeExternalInputs` runs as a second segment; capture the `USAGE_METADATA.round` sequence across both segments (this is the C1 reproduction).
+4. Cold revive after two resident continuations: dump the replayed history and confirm which user turns are missing (C2 reproduction).
+5. The two negative cases the design already lists: ping-pong between two _running_ agents on one thread tripping the turn gate, and `queueExternalInput(false)` being rebooked.
+6. Targeted tests for the parked patch, named files only: `src/agents/mesh/mentions.test.ts`, `dispatch-policy.test.ts`, `thread-actions.test.ts` under `packages/core`. Do not run directory sweeps.
+
+### Observations from the implementation pass
+
+These are the values observed in targeted runtime harnesses. They are not a claim that the still-unbuilt mesh launcher/dispatcher has run end to end.
+
+1. With cap `1`, three `completed` resident runtimes leave `canStartBackgroundAgent() === true`; registering one new running agent succeeds. Idle residents therefore do not claim throughput slots.
+2. The ambiguous boolean path was removed before a duplicate-runtime failure could be made a supported contract. The observed typed outcomes are: `capacity_wait` does not attempt cold revival; `continued` reuses the same resident (`createAgentHeadless` remains at one call); `fallback` is reserved for an unavailable resident and permits reconstruction. The exact old "false while still registered, then revive" race remains unobserved rather than blessed.
+3. The reproduced two-segment usage-round sequence was `[1, 1]`; after the integrated fix it is `[1, 2]`.
+4. Cold-revive reconstruction produced, in order, `original task`, the tool call/result, `working`, `and another thing`, `still working`, `one final constraint`. Both external user turns were present; zero were missing. Structured mesh delivery additionally records its `deliveryId`. This corrects C2 rather than confirming it.
+5. Admission tests observed the running coalesce increase the local turn count to the limit, and the following agent trigger returned `turn_budget_exhausted`. The `queueExternalInput(false)` detach/rebook half cannot execute until §5.2 step 6 creates the dispatcher, so it remains an explicit vertical-slice assertion rather than a reported pass.
+6. The three named mesh test files produced exactly `3 files, 37 tests passed`.
+
+## 5. Open question 8
+
+**Who controls a mesh agent's system prompt.** Decision 4 scopes trust to the workspace and §3 keeps thread text out of the repo because it is an injection surface. But every agent's system role is assembled from repo-controlled QWEN.md, the agent definition file, and auto-memory written by other sessions (`agent-core.ts:2646-2650`), at higher trust than any thread post. A `git pull` in another terminal silently changes every agent's system prompt while the resident body still holds the old one. §9.4 hashes the definition only; QWEN.md and auto-memory have no version, no gap marker, no provenance. I8 is the write side of this; the read side needs a version stamp in the run record.
+
+<details>
+<summary>中文摘要</summary>
+
+结论：根模型保留，改契约。C1 已复现为 `[1, 1]` 并修成 `[1, 2]`；C2 的原前提被运行验证推翻，resident 输入本来就会进入 transcript，真正缺的是 `deliveryId` 关联；C3 仍需产品拍板。Important 项已写回权威设计：聚合规则补齐三处，token outbox 删除，第 6 步前补最小 dispatcher，`paused` 单独恢复，排除 `save_memory`，FIFO 改用锁内序号。§5.1 patch 和 runtime 修正已整合进 #11072。开放问题扩展为 11 个，其中 C3、I3、S5 明确保留给人决定。§4 的六项检查已记录实际观测值；尚无 dispatcher 的部分明确标为未执行。
+
+</details>
diff --git a/docs/users/features/multi-agent-coordination.md b/docs/users/features/multi-agent-coordination.md
index aeef7c79ef2..c247b47c2d8 100644
--- a/docs/users/features/multi-agent-coordination.md
+++ b/docs/users/features/multi-agent-coordination.md
@@ -18,6 +18,14 @@ The leader creates a team, assigns up to three independent workstreams, and uses
If Agent Team is disabled, `/coordinate` can still use ordinary foreground agents for read-only parallel investigation. That fallback is delegation, not a collaborating team: the workers report only to the leader.
+## See who is working
+
+While a team is active, its teammates appear in the roster the CLI already shows below the composer, alongside ordinary background subagents. Each row carries the teammate's name in its assigned color, the shared task it currently owns, its state, and elapsed time. Pressing Enter on a teammate row opens that teammate's existing Agent View tab rather than the background-task detail view.
+
+Idle is reported as its own state, distinct from completed: an idle teammate has finished its current task and is waiting for the next one, so it can still be given work. A completed, failed, or cancelled teammate stays visible briefly so a terminal outcome is not missed.
+
+The same team state reaches Web Shell when the session runs under `qwen serve`: teammates appear in the environment sidebar and the session workflow view with their current shared task and state. Web Shell shows team rows as status only — teammate conversations stay in the CLI's Agent View tabs. Teammate tool approvals do surface in Web Shell, labelled with the teammate that asked, and answering one there releases or rejects that teammate's tool call.
+
## Choosing the right multi-agent mode
| Mode | Use it for | Communication | Workspace behavior |
diff --git a/packages/acp-bridge/src/status.ts b/packages/acp-bridge/src/status.ts
index 2a5031a8b70..5832850bfe9 100644
--- a/packages/acp-bridge/src/status.ts
+++ b/packages/acp-bridge/src/status.ts
@@ -772,7 +772,7 @@ export interface ServeSessionAgentTaskStatus {
id: string;
label: string;
description: string;
- status: ServeSessionTaskLifecycleStatus;
+ status: ServeSessionTaskLifecycleStatus | 'idle';
startTime: number;
endTime?: number;
runtimeMs: number;
@@ -800,6 +800,16 @@ export interface ServeSessionAgentTaskStatus {
parentName?: string;
/** Launch depth (0-based; 0 = spawned by the top-level session). */
depth?: number;
+ /** Active Agent Team name when this row represents a named teammate. */
+ teamName?: string;
+ /** Teammate color assigned by TeamManager. */
+ color?: string;
+ /** Current shared team task, when the teammate owns one. */
+ teamTask?: {
+ id: string;
+ subject: string;
+ status: 'pending' | 'in_progress' | 'completed';
+ };
}
export interface ServeSessionShellTaskStatus {
diff --git a/packages/cli/src/acp-integration/session/Session.test.ts b/packages/cli/src/acp-integration/session/Session.test.ts
index fd249ac59bc..f0f37137c9d 100644
--- a/packages/cli/src/acp-integration/session/Session.test.ts
+++ b/packages/cli/src/acp-integration/session/Session.test.ts
@@ -987,6 +987,8 @@ describe('Session', () => {
getGoalRuntime: vi.fn().mockReturnValue(mockGoalRuntime),
getGoalRuntimeReady: vi.fn().mockResolvedValue(mockGoalRuntime),
getGoalRuntimePrepared: vi.fn().mockResolvedValue(mockGoalRuntime),
+ getTeamManager: vi.fn().mockReturnValue(null),
+ onTeamManagerChange: vi.fn(),
bindGoalTurnHost: vi.fn().mockImplementation((host) => {
boundGoalHost = host;
return () => {
@@ -10600,6 +10602,191 @@ describe('Session', () => {
).toBe(false);
});
+ it('continues the leader turn when a teammate reports after the prompt is idle', async () => {
+ mockChat.sendMessageStream = vi
+ .fn()
+ .mockResolvedValueOnce(createEmptyStream())
+ .mockResolvedValueOnce(
+ createStreamWithChunks([
+ {
+ type: core.StreamEventType.CHUNK,
+ value: {
+ candidates: [
+ {
+ content: {
+ parts: [{ text: 'Reconciled teammate result.' }],
+ },
+ },
+ ],
+ },
+ },
+ ]),
+ );
+ const teamEvents = new EventEmitter();
+ const manager = {
+ setLeaderMessageCallback: vi.fn(),
+ getEventEmitter: () => teamEvents,
+ } as unknown as core.TeamManager;
+ const managerChanged = vi.mocked(mockConfig.onTeamManagerChange).mock
+ .calls[0]?.[0];
+ expect(managerChanged).toBeTypeOf('function');
+ managerChanged?.(manager);
+ const leaderCallback = vi.mocked(manager.setLeaderMessageCallback).mock
+ .calls[0]?.[0];
+
+ await session.prompt({
+ sessionId: 'test-session-id',
+ prompt: [{ type: 'text', text: 'coordinate teammates' }],
+ });
+
+ leaderCallback?.(
+ '<teammate_message>package scripts inspected</teammate_message>',
+ 'scripts-inspector reported',
+ );
+
+ await vi.waitFor(() => {
+ expect(mockChat.sendMessageStream).toHaveBeenCalledTimes(2);
+ });
+ const continuation = vi.mocked(mockChat.sendMessageStream).mock.calls[1];
+ expect(continuation?.[1]).toEqual(
+ expect.objectContaining({
+ message: expect.arrayContaining([
+ expect.objectContaining({
+ text: '<teammate_message>package scripts inspected</teammate_message>',
+ }),
+ ]),
+ }),
+ );
+ expect(agentMessageChunks()).toContain('scripts-inspector reported');
+ await vi.waitFor(() => {
+ expect(agentMessageChunks()).toContain('Reconciled teammate result.');
+ });
+
+ (
+ session as unknown as { pendingPrompt: AbortController | null }
+ ).pendingPrompt = new AbortController();
+ leaderCallback?.('queued old team message', 'queued old team message');
+ expect(
+ (
+ session as unknown as {
+ notificationQueue: Array<{ taskId: string }>;
+ }
+ ).notificationQueue,
+ ).toHaveLength(1);
+ managerChanged?.(null);
+ leaderCallback?.('stale team message', 'stale team message');
+ expect(mockChat.sendMessageStream).toHaveBeenCalledTimes(2);
+ expect(
+ (
+ session as unknown as {
+ notificationQueue: Array<{ taskId: string }>;
+ }
+ ).notificationQueue,
+ ).toHaveLength(0);
+ });
+
+ it('routes teammate approvals through the ACP permission dialog', async () => {
+ const teamEvents = new EventEmitter();
+ const manager = {
+ setLeaderMessageCallback: vi.fn(),
+ getEventEmitter: () => teamEvents,
+ } as unknown as core.TeamManager;
+ const managerChanged = vi.mocked(mockConfig.onTeamManagerChange).mock
+ .calls[0]?.[0];
+ managerChanged?.(manager);
+ const respond = vi.fn().mockResolvedValue(undefined);
+
+ teamEvents.emit(core.TeamEventType.TEAMMATE_APPROVAL_REQUEST, {
+ teammateName: 'writer',
+ toolName: 'write_file',
+ toolInput: { file_path: '/repo/result.txt', content: 'done' },
+ confirmationDetails: {
+ type: 'edit',
+ title: 'Write result.txt',
+ fileName: '/repo/result.txt',
+ filePath: '/repo/result.txt',
+ originalContent: '',
+ newContent: 'done',
+ fileDiff: '+done',
+ },
+ respond,
+ timestamp: Date.now(),
+ } satisfies core.TeammateApprovalRequestEvent);
+
+ await vi.waitFor(() => expect(respond).toHaveBeenCalledOnce());
+ expect(mockClient.requestPermission).toHaveBeenCalledWith(
+ expect.objectContaining({
+ sessionId: 'test-session-id',
+ toolCall: expect.objectContaining({
+ title: expect.stringContaining('writer:'),
+ rawInput: {
+ file_path: '/repo/result.txt',
+ content: 'done',
+ },
+ _meta: expect.objectContaining({
+ toolName: 'write_file',
+ teammateName: 'writer',
+ }),
+ }),
+ }),
+ );
+ expect(respond).toHaveBeenCalledWith(
+ core.ToolConfirmationOutcome.ProceedOnce,
+ undefined,
+ );
+ });
+
+ it('cancels a pending teammate approval when the team is detached', async () => {
+ let resolvePermission:
+ | ((response: RequestPermissionResponse) => void)
+ | undefined;
+ vi.mocked(mockClient.requestPermission).mockImplementationOnce(
+ () =>
+ new Promise<RequestPermissionResponse>((resolve) => {
+ resolvePermission = resolve;
+ }),
+ );
+ const teamEvents = new EventEmitter();
+ const manager = {
+ setLeaderMessageCallback: vi.fn(),
+ getEventEmitter: () => teamEvents,
+ } as unknown as core.TeamManager;
+ const managerChanged = vi.mocked(mockConfig.onTeamManagerChange).mock
+ .calls[0]?.[0];
+ managerChanged?.(manager);
+ const respond = vi.fn().mockResolvedValue(undefined);
+
+ teamEvents.emit(core.TeamEventType.TEAMMATE_APPROVAL_REQUEST, {
+ teammateName: 'writer',
+ toolName: 'write_file',
+ toolInput: { file_path: '/repo/result.txt', content: 'done' },
+ confirmationDetails: {
+ type: 'edit',
+ title: 'Write result.txt',
+ fileName: '/repo/result.txt',
+ filePath: '/repo/result.txt',
+ originalContent: '',
+ newContent: 'done',
+ fileDiff: '+done',
+ },
+ respond,
+ timestamp: Date.now(),
+ } satisfies core.TeammateApprovalRequestEvent);
+
+ await vi.waitFor(() =>
+ expect(mockClient.requestPermission).toHaveBeenCalledOnce(),
+ );
+ managerChanged?.(null);
+ await vi.waitFor(() =>
+ expect(respond).toHaveBeenCalledWith(
+ core.ToolConfirmationOutcome.Cancel,
+ ),
+ );
+ resolvePermission?.({
+ outcome: { outcome: 'selected', optionId: 'proceed_once' },
+ });
+ });
+
it('attaches structured agent metadata built from the canonical entry label', async () => {
mockChat.sendMessageStream = vi
.fn()
diff --git a/packages/cli/src/acp-integration/session/Session.ts b/packages/cli/src/acp-integration/session/Session.ts
index 6a7df1bea22..92d2045108b 100644
--- a/packages/cli/src/acp-integration/session/Session.ts
+++ b/packages/cli/src/acp-integration/session/Session.ts
@@ -58,6 +58,8 @@ import type {
WorkflowSnapshot,
WorkflowTask,
BranchPoint,
+ TeamManager,
+ TeammateApprovalRequestEvent,
} from '@qwen-code/qwen-code-core';
import {
AuthType,
@@ -229,6 +231,7 @@ import {
collectSessionTurnState,
computeInitialTurnFromHistory as computeInitialTurnFromHistoryCore,
buildGoalContinuationParts,
+ TeamEventType,
} from '@qwen-code/qwen-code-core';
import { NOT_CURRENTLY_GENERATING_CANCEL_MESSAGE } from '@qwen-code/acp-bridge/bridgeErrors';
import { CHANNEL_PROMPT_META_KEY } from '@qwen-code/channel-base';
@@ -424,6 +427,7 @@ const MAX_RETAINED_SESSION_ROUTE_COUNTS = 8;
const USER_CANCEL_ABORT_REASON = 'qwen:user-cancel';
const NEW_PROMPT_ABORT_REASON = 'qwen:new-prompt';
const SESSION_DISPOSE_ABORT_REASON = 'qwen:session-dispose';
+const TEAM_MANAGER_CHANGED_ABORT_REASON = 'qwen:team-manager-changed';
const DAEMON_RETRY_META_KEY = 'qwen.daemon.retry';
const DAEMON_CONTINUE_META_KEY = 'qwen.daemon.continueLastTurn';
const MAX_DAEMON_ATTACHMENT_REFERENCES = 256;
@@ -1623,6 +1627,7 @@ function parsePromptChannelDelivery(
}
const MAX_NOTIFICATION_QUEUE = 20;
+const TEAMMATE_NOTIFICATION_TASK_PREFIX = 'teammate-';
const MAX_DEFERRED_UNRELATED_CRON_QUEUE = 20;
export function resolveExistingFile(
@@ -2087,6 +2092,14 @@ export class Session implements SessionContext {
* retract its own and nobody else's. */
#statusChangeCallback: (() => void) | undefined;
#workflowStatusChangeCallback: ((entry?: WorkflowTask) => void) | undefined;
+ #teamManagerChangeCallback:
+ | ((manager: TeamManager | null) => void)
+ | undefined;
+ #boundTeamManager: TeamManager | null = null;
+ #teammateApprovalListener:
+ | ((event: TeammateApprovalRequestEvent) => void)
+ | undefined;
+ private teammateApprovalAbortController = new AbortController();
private workflowHistory: WorkflowSnapshot[];
/**
* R7-5: runIds whose snapshot write this session has observed. Latches
@@ -2270,6 +2283,7 @@ export class Session implements SessionContext {
this.#bindGoalRuntime();
this.#registerBackgroundNotificationCallbacks();
+ this.#registerTeamManagerCallbacks();
this.#registerSubSessionSpawner();
this.#registerCurrentSessionScheduledTaskCreator();
this.config
@@ -4284,6 +4298,12 @@ export class Session implements SessionContext {
.getWorkflowRunRegistry?.()
.setApprovalRequestCallback(undefined);
this.workflowApprovalAbortController.abort(SESSION_DISPOSE_ABORT_REASON);
+ if (this.#teamManagerChangeCallback) {
+ this.config.onTeamManagerChange?.(null, this.#teamManagerChangeCallback);
+ this.#teamManagerChangeCallback = undefined;
+ }
+ this.#detachTeamManager();
+ this.teammateApprovalAbortController.abort(SESSION_DISPOSE_ABORT_REASON);
}
/**
@@ -9654,6 +9674,143 @@ export class Session implements SessionContext {
}
}
+ #registerTeamManagerCallbacks(): void {
+ this.#teamManagerChangeCallback = (manager) => {
+ if (manager === this.#boundTeamManager) return;
+ this.#detachTeamManager();
+ this.#boundTeamManager = manager;
+ if (!manager) return;
+ this.teammateApprovalAbortController = new AbortController();
+
+ manager.setLeaderMessageCallback((modelText, displayText) => {
+ if (this.#boundTeamManager !== manager) return;
+ this.#enqueueBackgroundNotification({
+ displayText,
+ modelText,
+ taskId: `${TEAMMATE_NOTIFICATION_TASK_PREFIX}${randomUUID()}`,
+ status: 'completed',
+ kind: 'agent',
+ continuesTodoStopGuardWorkChain: true,
+ structured: { description: displayText },
+ });
+ });
+ this.#teammateApprovalListener = (event) => {
+ void this.#requestTeammateApproval(event);
+ };
+ manager
+ .getEventEmitter()
+ .on(
+ TeamEventType.TEAMMATE_APPROVAL_REQUEST,
+ this.#teammateApprovalListener,
+ );
+ };
+ this.config.onTeamManagerChange?.(this.#teamManagerChangeCallback);
+ this.#teamManagerChangeCallback(this.config.getTeamManager?.() ?? null);
+ }
+
+ #detachTeamManager(): void {
+ if (!this.#boundTeamManager) return;
+ this.teammateApprovalAbortController.abort(
+ TEAM_MANAGER_CHANGED_ABORT_REASON,
+ );
+ this.#boundTeamManager.setLeaderMessageCallback(null);
+ if (this.#teammateApprovalListener) {
+ this.#boundTeamManager
+ .getEventEmitter()
+ .off(
+ TeamEventType.TEAMMATE_APPROVAL_REQUEST,
+ this.#teammateApprovalListener,
+ );
+ }
+ const queueLength = this.notificationQueue.length;
+ this.notificationQueue = this.notificationQueue.filter(
+ (item) => !item.taskId.startsWith(TEAMMATE_NOTIFICATION_TASK_PREFIX),
+ );
+ if (!this.disposed && this.notificationQueue.length !== queueLength) {
+ this.#activeWorkChanged();
+ }
+ this.#teammateApprovalListener = undefined;
+ this.#boundTeamManager = null;
+ }
+
+ async #requestTeammateApproval(
+ event: TeammateApprovalRequestEvent,
+ ): Promise<void> {
+ const confirmation = event.confirmationDetails;
+ if (!confirmation || this.disposed || this.closing) {
+ await event.respond(ToolConfirmationOutcome.Cancel).catch(() => {});
+ return;
+ }
+
+ const confirmationDetails = {
+ ...confirmation,
+ onConfirm: async () => {},
+ } as ToolCallConfirmationDetails;
+ const permissionOptions = toPermissionOptions(confirmationDetails, true);
+ const offeredPermissionOptions = permissionOptions.map((option) => ({
+ ...option,
+ }));
+ const toolCallId = `teammate:${event.teammateName}:${randomUUID()}`;
+ const { title, locations, kind } = this.toolCallEmitter.resolveToolMetadata(
+ event.toolName,
+ event.toolInput,
+ );
+ let approved = false;
+ try {
+ const response = (await this.#requestPermissionQueued(
+ {
+ sessionId: this.sessionId,
+ options: permissionOptions,
+ toolCall: {
+ toolCallId,
+ status: 'pending',
+ title: `${event.teammateName}: ${title}`,
+ content: buildPermissionRequestContent(confirmationDetails),
+ locations,
+ kind,
+ rawInput: event.toolInput,
+ _meta: {
+ toolName: event.toolName,
+ teammateName: event.teammateName,
+ ...interactionMetaFields(confirmationDetails),
+ },
+ },
+ },
+ this.teammateApprovalAbortController.signal,
+ )) as RequestPermissionResponse & { answers?: Record<string, string> };
+ let outcome = resolvePermissionOutcome(
+ response,
+ offeredPermissionOptions,
+ );
+ if (outcome === ToolConfirmationOutcome.ProceedOnceAndSwitchToDefault) {
+ outcome = ToolConfirmationOutcome.ProceedOnce;
+ this.config.setApprovalMode(ApprovalMode.DEFAULT);
+ await this.sendCurrentModeUpdateNotification();
+ }
+ await event.respond(
+ outcome,
+ response.answers ? { answers: response.answers } : undefined,
+ );
+ approved = outcome !== ToolConfirmationOutcome.Cancel;
+ } catch (error) {
+ debugLogger.warn(
+ `Teammate approval failed for ${event.teammateName}/${event.toolName}: ${this.#formatError(error)}`,
+ );
+ await event.respond(ToolConfirmationOutcome.Cancel).catch(() => {});
+ } finally {
+ await this.sendUpdate({
+ sessionUpdate: 'tool_call_update',
+ toolCallId,
+ status: approved ? 'completed' : 'failed',
+ content: [],
+ _meta: {
+ toolName: event.toolName,
+ teammateName: event.teammateName,
+ },
+ }).catch(() => {});
+ }
+ }
+
#enqueueBackgroundNotification(item: QueuedBackgroundNotification): void {
while (this.notificationQueue.length >= MAX_NOTIFICATION_QUEUE) {
let evictedIndex = 0;
diff --git a/packages/cli/src/acp-integration/session/tasksSnapshot.test.ts b/packages/cli/src/acp-integration/session/tasksSnapshot.test.ts
index 3bc8a5ac9b6..077713ff7bd 100644
--- a/packages/cli/src/acp-integration/session/tasksSnapshot.test.ts
+++ b/packages/cli/src/acp-integration/session/tasksSnapshot.test.ts
@@ -12,9 +12,11 @@ import type {
AgentTask,
Config,
MonitorTask,
+ TeamManager,
WorkflowSnapshot,
WorkflowTask,
} from '@qwen-code/qwen-code-core';
+import { AgentStatus } from '@qwen-code/qwen-code-core';
import {
buildSessionAgentsStatus,
buildSessionTasksStatus,
@@ -41,6 +43,7 @@ function configWith(
agents: AgentTask[],
workflows: WorkflowTask[] = [],
projectDir = '/tmp',
+ teamManager: TeamManager | null = null,
): Config {
return {
storage: { getProjectDir: () => projectDir },
@@ -48,10 +51,137 @@ function configWith(
getBackgroundShellRegistry: () => ({ getAll: () => [] }),
getMonitorRegistry: () => ({ getAll: () => [] }),
getWorkflowRunRegistry: () => ({ list: () => workflows }),
+ getTeamManager: () => teamManager,
} as unknown as Config;
}
describe('buildSessionAgentsStatus', () => {
+ it('includes team members with explicit idle state and assigned work', async () => {
+ const qwenHome = fs.mkdtempSync(path.join(os.tmpdir(), 'team-status-'));
+ const previousQwenHome = process.env['QWEN_HOME'];
+ process.env['QWEN_HOME'] = qwenHome;
+ const teamName = 'review-team';
+ const taskDir = path.join(qwenHome, 'tasks', teamName);
+ fs.mkdirSync(taskDir, { recursive: true });
+ fs.writeFileSync(
+ path.join(taskDir, '1.json'),
+ JSON.stringify({
+ id: '1',
+ subject: 'Review authentication flow',
+ description: 'Inspect auth changes',
+ activeForm: 'Reviewing authentication flow',
+ owner: 'reviewer',
+ status: 'in_progress',
+ blocks: [],
+ blockedBy: [],
+ }),
+ );
+ const teammate = {
+ getStatus: () => AgentStatus.IDLE,
+ };
+ const teamManager = {
+ getTeamFile: () => ({
+ name: teamName,
+ createdAt: 500,
+ leadAgentId: 'leader',
+ members: [
+ {
+ agentId: 'reviewer@review-team',
+ name: 'reviewer',
+ color: '#4ECDC4',
+ joinedAt: 1_000,
+ cwd: '/work/qwen-code',
+ tmuxPaneId: '',
+ subscriptions: [],
+ },
+ ],
+ }),
+ getAgentFromBackend: () => teammate,
+ } as unknown as TeamManager;
+
+ try {
+ const snapshot = await buildSessionAgentsStatus(
+ 'session-1',
+ configWith([], [], qwenHome, teamManager),
+ 4_000,
+ );
+
+ expect(snapshot.tasks).toEqual([
+ expect.objectContaining({
+ id: 'reviewer@review-team',
+ label: 'reviewer',
+ status: 'idle',
+ runtimeMs: 3_000,
+ teamName,
+ color: '#4ECDC4',
+ teamTask: {
+ id: '1',
+ subject: 'Review authentication flow',
+ status: 'in_progress',
+ },
+ }),
+ ]);
+ } finally {
+ if (previousQwenHome === undefined) delete process.env['QWEN_HOME'];
+ else process.env['QWEN_HOME'] = previousQwenHome;
+ fs.rmSync(qwenHome, { recursive: true, force: true });
+ }
+ });
+
+ it('still reports team members when the shared task board is unreadable', async () => {
+ const qwenHome = fs.mkdtempSync(path.join(os.tmpdir(), 'team-status-'));
+ const previousQwenHome = process.env['QWEN_HOME'];
+ process.env['QWEN_HOME'] = qwenHome;
+ const teamName = 'review-team';
+ // A file where the task directory belongs: `listTasks` treats every
+ // non-ENOENT readdir failure as "the board is unreadable" and throws
+ // rather than reporting an empty board. The roster must degrade to
+ // rows without a shared task instead of failing the whole snapshot.
+ fs.mkdirSync(path.join(qwenHome, 'tasks'), { recursive: true });
+ fs.writeFileSync(path.join(qwenHome, 'tasks', teamName), 'not a directory');
+ const teammate = { getStatus: () => AgentStatus.RUNNING };
+ const teamManager = {
+ getTeamFile: () => ({
+ name: teamName,
+ createdAt: 500,
+ leadAgentId: 'leader',
+ members: [
+ {
+ agentId: 'reviewer@review-team',
+ name: 'reviewer',
+ joinedAt: 1_000,
+ cwd: '/work/qwen-code',
+ tmuxPaneId: '',
+ subscriptions: [],
+ },
+ ],
+ }),
+ getAgentFromBackend: () => teammate,
+ } as unknown as TeamManager;
+
+ try {
+ const snapshot = await buildSessionAgentsStatus(
+ 'session-1',
+ configWith([], [], qwenHome, teamManager),
+ 4_000,
+ );
+
+ expect(snapshot.tasks).toEqual([
+ expect.objectContaining({
+ id: 'reviewer@review-team',
+ label: 'reviewer',
+ status: 'running',
+ teamName,
+ }),
+ ]);
+ expect(snapshot.tasks[0]).not.toHaveProperty('teamTask');
+ } finally {
+ if (previousQwenHome === undefined) delete process.env['QWEN_HOME'];
+ else process.env['QWEN_HOME'] = previousQwenHome;
+ fs.rmSync(qwenHome, { recursive: true, force: true });
+ }
+ });
+
it('merges persisted agents with live registry entries by id', async () => {
const projectDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agents-status-'));
const sessionDir = path.join(projectDir, 'subagents', 'session-1');
diff --git a/packages/cli/src/acp-integration/session/tasksSnapshot.ts b/packages/cli/src/acp-integration/session/tasksSnapshot.ts
index e0f64bf470c..bdca315ee0a 100644
--- a/packages/cli/src/acp-integration/session/tasksSnapshot.ts
+++ b/packages/cli/src/acp-integration/session/tasksSnapshot.ts
@@ -5,8 +5,10 @@
*/
import {
+ AgentStatus,
buildBackgroundEntryLabel,
getSubagentSessionDir,
+ listTasks,
MAX_AGENT_TRACE_NODES,
MAX_RETAINED_TERMINAL_AGENTS,
readAgentMetaAsync,
@@ -95,12 +97,23 @@ function retainAgentTasks(
.filter(
(task) =>
task.status === 'running' ||
+ task.status === 'idle' ||
pausedIds.has(task.id) ||
terminalIds.has(task.id),
)
.sort((a, b) => a.startTime - b.startTime || a.id.localeCompare(b.id));
}
+function teamAgentStatus(
+ status: AgentStatus,
+): ServeSessionAgentTaskStatus['status'] {
+ if (status === AgentStatus.IDLE) return 'idle';
+ if (status === AgentStatus.INITIALIZING || status === AgentStatus.RUNNING) {
+ return 'running';
+ }
+ return status;
+}
+
function serializeAgentTask(
entry: AgentTask,
now: number,
@@ -474,6 +487,59 @@ export async function buildSessionAgentsStatus(
agents.set(entry.id, serializeAgentTask(entry, now));
}
+ const teamManager = config.getTeamManager?.();
+ if (teamManager) {
+ const team = teamManager.getTeamFile();
+ // `listTasks` deliberately throws on anything but ENOENT so a leader
+ // never mistakes an unreadable board for an empty one — it has already
+ // logged the reason by the time it does. Here that must not propagate:
+ // the shared-task label is decoration on top of team rows this route can
+ // still render, and letting it escape would fail the whole agents
+ // snapshot (subagents and background tasks included) for the session.
+ let tasks: Awaited<ReturnType<typeof listTasks>>;
+ try {
+ tasks = await listTasks(team.name);
+ } catch {
+ tasks = [];
+ }
+ for (const member of team.members) {
+ const agent = teamManager.getAgentFromBackend(member.agentId);
+ if (!agent) continue;
+ const task = tasks.find(
+ (candidate) =>
+ candidate.status === 'in_progress' &&
+ (candidate.owner === member.agentId ||
+ candidate.owner === member.name),
+ );
+ agents.set(member.agentId, {
+ kind: 'agent',
+ id: member.agentId,
+ label: member.name,
+ description:
+ task?.activeForm ??
+ task?.subject ??
+ member.agentType ??
+ 'Team member',
+ status: teamAgentStatus(agent.getStatus()),
+ startTime: member.joinedAt,
+ runtimeMs: Math.max(0, now - member.joinedAt),
+ subagentType: member.agentType,
+ isBackgrounded: false,
+ teamName: team.name,
+ ...optionalField('color', member.color),
+ ...(task
+ ? {
+ teamTask: {
+ id: task.id,
+ subject: task.subject,
+ status: task.status,
+ },
+ }
+ : {}),
+ });
+ }
+ }
+
return {
v: STATUS_SCHEMA_VERSION,
sessionId,
diff --git a/packages/cli/src/ui/AppContainer.tsx b/packages/cli/src/ui/AppContainer.tsx
index b74c2e9dc80..aa521c05940 100644
--- a/packages/cli/src/ui/AppContainer.tsx
+++ b/packages/cli/src/ui/AppContainer.tsx
@@ -2516,6 +2516,7 @@ export const AppContainer = (props: AppContainerProps) => {
const {
dialogOpen: bgTasksDialogOpen,
entries: bgTaskEntries,
+ liveAgentEntries,
livePanelFocused: bgLivePanelFocused,
} = useBackgroundTaskViewState();
const { closeDialog: closeBgTasksDialog } = useBackgroundTaskViewActions();
@@ -3874,7 +3875,7 @@ export const AppContainer = (props: AppContainerProps) => {
// `availableTerminalHeight` — never goes stale below the composer. See
// getLiveAgentPanelLayoutKey for the full rationale (#5798).
const liveAgentPanelLayoutKey = getLiveAgentPanelLayoutKey(
- bgTaskEntries,
+ liveAgentEntries ?? bgTaskEntries,
bgLivePanelFocused,
);
diff --git a/packages/cli/src/ui/app-container-controls-dep.test.ts b/packages/cli/src/ui/app-container-controls-dep.test.ts
index c80077db9c3..b77280333e0 100644
--- a/packages/cli/src/ui/app-container-controls-dep.test.ts
+++ b/packages/cli/src/ui/app-container-controls-dep.test.ts
@@ -64,7 +64,7 @@ describe('AppContainer controls-height measurement wiring', () => {
// The key must be derived from the roster + focus, not a constant. Match
// whitespace-tolerantly so prettier reformatting can't break the guard.
expect(source).toMatch(
- /liveAgentPanelLayoutKey\s*=\s*getLiveAgentPanelLayoutKey\(\s*bgTaskEntries\s*,\s*bgLivePanelFocused\s*,?\s*\)/,
+ /liveAgentPanelLayoutKey\s*=\s*getLiveAgentPanelLayoutKey\(\s*liveAgentEntries\s*\?\?\s*bgTaskEntries\s*,\s*bgLivePanelFocused\s*,?\s*\)/,
);
});
});
diff --git a/packages/cli/src/ui/components/InputPrompt.test.tsx b/packages/cli/src/ui/components/InputPrompt.test.tsx
index 32037e6ac14..fd3ffd71650 100644
--- a/packages/cli/src/ui/components/InputPrompt.test.tsx
+++ b/packages/cli/src/ui/components/InputPrompt.test.tsx
@@ -62,6 +62,7 @@ const mockViewActions = vi.hoisted(() => ({
setLivePanelSelectedIndex: vi.fn(),
setBgSelectedIndex: vi.fn(),
enterBgDetailFromPanel: vi.fn(),
+ switchToAgent: vi.fn(),
}));
vi.mock('../hooks/useShellHistory.js');
@@ -96,6 +97,7 @@ vi.mock('../contexts/AgentViewContext.js', () => ({
})),
useAgentViewActions: vi.fn(() => ({
setAgentTabBarFocused: mockViewActions.setAgentTabBarFocused,
+ switchToAgent: mockViewActions.switchToAgent,
})),
}));
vi.mock('../contexts/BackgroundTaskViewContext.js', () => ({
@@ -226,6 +228,7 @@ describe('InputPrompt', () => {
mockViewActions.setLivePanelSelectedIndex.mockReset();
mockViewActions.setBgSelectedIndex.mockReset();
mockViewActions.enterBgDetailFromPanel.mockReset();
+ mockViewActions.switchToAgent.mockReset();
mockedUseUIState.mockReturnValue({
isFeedbackDialogOpen: false,
@@ -248,6 +251,7 @@ describe('InputPrompt', () => {
});
mockedUseAgentViewActions.mockReturnValue({
setAgentTabBarFocused: mockViewActions.setAgentTabBarFocused,
+ switchToAgent: mockViewActions.switchToAgent,
} as unknown as ReturnType<typeof useAgentViewActions>);
mockedUseBackgroundTaskViewState.mockReturnValue({
entries: [],
@@ -5970,6 +5974,50 @@ describe('InputPrompt', () => {
unmount();
});
+ it('Enter on a teammate row opens its existing Agent tab', async () => {
+ mockedUseAgentViewState.mockReturnValue({
+ activeView: 'main',
+ agents: new Map([['reviewer@review-team', {}]]),
+ agentShellFocused: false,
+ agentInputBufferText: '',
+ agentTabBarFocused: false,
+ agentApprovalModes: new Map(),
+ } as unknown as ReturnType<typeof useAgentViewState>);
+ mockedUseBackgroundTaskViewState.mockReturnValue({
+ entries: [],
+ liveAgentEntries: [
+ {
+ kind: 'agent',
+ id: 'reviewer@review-team',
+ agentId: 'reviewer@review-team',
+ status: 'paused',
+ teamStatus: 'idle',
+ teamName: 'review-team',
+ startTime: 1,
+ },
+ ],
+ selectedIndex: 0,
+ dialogMode: 'closed',
+ dialogOpen: false,
+ pillFocused: false,
+ livePanelFocused: true,
+ livePanelSelectedIndex: 1,
+ } as unknown as ReturnType<typeof useBackgroundTaskViewState>);
+
+ const { stdin, unmount } = renderWithProviders(
+ <InputPrompt {...props} />,
+ );
+ await wait();
+ stdin.write('\r');
+ await wait();
+
+ expect(mockViewActions.switchToAgent).toHaveBeenCalledWith(
+ 'reviewer@review-team',
+ );
+ expect(mockViewActions.enterBgDetailFromPanel).not.toHaveBeenCalled();
+ unmount();
+ });
+
it('arrow Up applies the same two-step rule as Ctrl+P (snap before navigate)', async () => {
// The arrow-key history path lives alongside Ctrl+P in InputPrompt.tsx
// and the two must stay in lock-step. This test pins the parity so a
diff --git a/packages/cli/src/ui/components/InputPrompt.tsx b/packages/cli/src/ui/components/InputPrompt.tsx
index 8820ce73875..0a770b8164e 100644
--- a/packages/cli/src/ui/components/InputPrompt.tsx
+++ b/packages/cli/src/ui/components/InputPrompt.tsx
@@ -71,6 +71,7 @@ import {
getLiveAgentPanelVpMaxRows,
} from './background-view/liveAgentPanelVisibility.js';
import { panelDisplayOrder } from './background-view/agent-forest.js';
+import { isTeamAgentDialogEntry } from '../hooks/use-team-agent-roster.js';
import { FEEDBACK_DIALOG_KEYS } from '../FeedbackDialog.js';
import { BaseTextInput } from './BaseTextInput.js';
import type { RenderLineOptions } from './BaseTextInput.js';
@@ -270,10 +271,11 @@ export const InputPrompt: React.FC<InputPromptProps> = ({
mouseTrackingEnabled;
const { pasteWorkaround } = useKeypressContext();
const { agents, agentTabBarFocused } = useAgentViewState();
- const { setAgentTabBarFocused } = useAgentViewActions();
+ const { setAgentTabBarFocused, switchToAgent } = useAgentViewActions();
const { menu: contextMenu, closeMenu: closeContextMenu } = useContextMenu();
const {
entries: bgEntries,
+ liveAgentEntries,
dialogOpen: bgDialogOpen,
pillFocused: bgPillFocused,
livePanelFocused,
@@ -287,6 +289,8 @@ export const InputPrompt: React.FC<InputPromptProps> = ({
setPillFocused: setBgPillFocused,
} = useBackgroundTaskViewActions();
const hasAgents = agents.size > 0;
+ const rosterEntries =
+ liveAgentEntries ?? bgEntries.filter((entry) => entry.kind === 'agent');
// panelDisplayOrder + the maxRows tail-window mirror LiveAgentPanel's
// rendered rows exactly (oldest-first, nested agents grouped under
// their parent, windowed to the last LIVE_AGENT_PANEL_MAX_ROWS) so
@@ -302,9 +306,11 @@ export const InputPrompt: React.FC<InputPromptProps> = ({
const getVisibleBgAgents = useCallback(
() =>
panelDisplayOrder(
- bgEntries.filter((e) => isLiveAgentPanelVisibleEntry(e, Date.now())),
+ rosterEntries.filter((entry) =>
+ isLiveAgentPanelVisibleEntry(entry, Date.now()),
+ ),
).slice(-liveAgentPanelMaxRows),
- [bgEntries, liveAgentPanelMaxRows],
+ [liveAgentPanelMaxRows, rosterEntries],
);
const hasActiveToolConfirmation = useMemo(
() =>
@@ -1001,6 +1007,11 @@ export const InputPrompt: React.FC<InputPromptProps> = ({
} else {
const agentIdx = livePanelSelectedIndex - 1;
const entry = visibleBgAgents[agentIdx];
+ if (entry && isTeamAgentDialogEntry(entry)) {
+ switchToAgent(entry.agentId);
+ setLivePanelFocused(false);
+ return true;
+ }
const entryIdx = entry
? bgEntries.findIndex(
(e) => e.kind === 'agent' && e.agentId === entry.agentId,
@@ -1956,6 +1967,7 @@ export const InputPrompt: React.FC<InputPromptProps> = ({
hasAgents,
hasActiveToolConfirmation,
setAgentTabBarFocused,
+ switchToAgent,
setLivePanelFocused,
setLivePanelSelectedIndex,
livePanelFocused,
diff --git a/packages/cli/src/ui/components/agent-view/AgentTabBar.tsx b/packages/cli/src/ui/components/agent-view/AgentTabBar.tsx
index ae54bba8520..f51d4bf99b2 100644
--- a/packages/cli/src/ui/components/agent-view/AgentTabBar.tsx
+++ b/packages/cli/src/ui/components/agent-view/AgentTabBar.tsx
@@ -71,12 +71,14 @@ export const AgentTabBar: React.FC = () => {
useAgentViewState();
const { switchToNext, switchToPrevious, setAgentTabBarFocused } =
useAgentViewActions();
- const { entries: bgEntries } = useBackgroundTaskViewState();
+ const { entries: bgEntries, liveAgentEntries } = useBackgroundTaskViewState();
const { setLivePanelFocused, setPillFocused } =
useBackgroundTaskViewActions();
const { embeddedShellFocused } = useUIState();
const hasVisibleBgAgentRoster = () =>
- bgEntries.some((e) => isLiveAgentPanelVisibleEntry(e, Date.now()));
+ (liveAgentEntries ?? bgEntries).some((entry) =>
+ isLiveAgentPanelVisibleEntry(entry, Date.now()),
+ );
useKeypress(
(key) => {
diff --git a/packages/cli/src/ui/components/background-view/BackgroundTasksDialog.test.tsx b/packages/cli/src/ui/components/background-view/BackgroundTasksDialog.test.tsx
index d473cf57e30..4f649e7a39a 100644
--- a/packages/cli/src/ui/components/background-view/BackgroundTasksDialog.test.tsx
+++ b/packages/cli/src/ui/components/background-view/BackgroundTasksDialog.test.tsx
@@ -191,6 +191,8 @@ function setup(
}),
getIdeMode: () => false,
isTrustedFolder: () => true,
+ getTeamManager: vi.fn(() => null),
+ onTeamManagerChange: vi.fn(),
resumeBackgroundAgent: resume,
abandonBackgroundAgent: abandon,
} as unknown as Config;
diff --git a/packages/cli/src/ui/components/background-view/LiveAgentPanel.test.tsx b/packages/cli/src/ui/components/background-view/LiveAgentPanel.test.tsx
index 017d826c64b..dcef29a6208 100644
--- a/packages/cli/src/ui/components/background-view/LiveAgentPanel.test.tsx
+++ b/packages/cli/src/ui/components/background-view/LiveAgentPanel.test.tsx
@@ -7,7 +7,7 @@
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import { act } from '@testing-library/react';
import { render } from 'ink-testing-library';
-import type { Config } from '@qwen-code/qwen-code-core';
+import { AgentStatus, type Config } from '@qwen-code/qwen-code-core';
import { LiveAgentPanel } from './LiveAgentPanel.js';
import {
BackgroundTaskViewActionsContext,
@@ -19,6 +19,7 @@ import type {
AgentDialogEntry,
DialogEntry,
} from '../../hooks/useBackgroundTaskView.js';
+import type { LiveAgentDialogEntry } from '../../hooks/use-team-agent-roster.js';
function agentEntry(
overrides: Partial<AgentDialogEntry> = {},
@@ -51,6 +52,7 @@ function shellEntry(overrides: Partial<DialogEntry> = {}): DialogEntry {
function renderPanel(
options: {
entries: readonly DialogEntry[];
+ liveAgentEntries?: readonly LiveAgentDialogEntry[];
dialogOpen?: boolean;
width?: number;
maxRows?: number;
@@ -66,6 +68,7 @@ function renderPanel(
) {
const state = {
entries: options.entries,
+ liveAgentEntries: options.liveAgentEntries,
selectedIndex: 0,
dialogMode: options.dialogOpen ? ('list' as const) : ('closed' as const),
dialogOpen: Boolean(options.dialogOpen),
@@ -180,6 +183,32 @@ describe('<LiveAgentPanel />', () => {
expect(frame).toContain('5s');
});
+ it('renders an idle teammate with its assigned task', () => {
+ const teammate = {
+ ...agentEntry({
+ agentId: 'reviewer@review-team',
+ id: 'reviewer@review-team',
+ subagentType: 'reviewer',
+ description: 'Reviewing authentication flow',
+ status: 'paused',
+ startTime: -5_000,
+ }),
+ teamName: 'review-team',
+ teamStatus: AgentStatus.IDLE,
+ teamColor: '#4ECDC4',
+ };
+ const { lastFrame } = renderPanel({
+ entries: [],
+ liveAgentEntries: [teammate],
+ });
+
+ const frame = lastFrame() ?? '';
+ expect(frame).toContain('reviewer');
+ expect(frame).toContain('Reviewing authentication flow');
+ expect(frame).toContain('idle');
+ expect(frame).toContain('5s');
+ });
+
it('elides the default `general-purpose` subagent type from the row', () => {
// The DEFAULT_BUILTIN_SUBAGENT_TYPE elision suppresses the
// redundant `general-purpose: ` prefix on rows where the type
diff --git a/packages/cli/src/ui/components/background-view/LiveAgentPanel.tsx b/packages/cli/src/ui/components/background-view/LiveAgentPanel.tsx
index f460332082a..b216e5f58ea 100644
--- a/packages/cli/src/ui/components/background-view/LiveAgentPanel.tsx
+++ b/packages/cli/src/ui/components/background-view/LiveAgentPanel.tsx
@@ -30,6 +30,7 @@ import type React from 'react';
import { useContext, useEffect, useMemo, useRef, useState } from 'react';
import { Box, Text } from 'ink';
import { DEFAULT_BUILTIN_SUBAGENT_TYPE as CORE_DEFAULT_SUBAGENT_TYPE } from '@qwen-code/qwen-code-core/subagents/builtin-agents.js';
+import { AgentStatus } from '@qwen-code/qwen-code-core/agents/runtime/agent-types.js';
import { localizeToolDisplayName } from '../../../i18n/index.js';
import {
useBackgroundTaskViewActions,
@@ -51,6 +52,10 @@ import {
isLiveAgentPanelVisibleEntry,
LIVE_AGENT_PANEL_MAX_ROWS,
} from './liveAgentPanelVisibility.js';
+import {
+ isTeamAgentDialogEntry,
+ type LiveAgentDialogEntry,
+} from '../../hooks/use-team-agent-roster.js';
import {
type AgentTreeInfo,
computeAgentTreeInfo,
@@ -86,7 +91,7 @@ const DEFAULT_MAX_ROWS = LIVE_AGENT_PANEL_MAX_ROWS;
// rendered as a bold anchor.
const DEFAULT_SUBAGENT_TYPE = CORE_DEFAULT_SUBAGENT_TYPE;
-type LivePanelEntry = AgentDialogEntry & {
+type LivePanelEntry = LiveAgentDialogEntry & {
/** True when the row is past its terminal-visibility window. */
expired: boolean;
/**
@@ -112,6 +117,23 @@ function statusIcon(entry: AgentDialogEntry & { synthesized?: boolean }): {
glyph: string;
color: string;
} {
+ if (isTeamAgentDialogEntry(entry)) {
+ switch (entry.teamStatus) {
+ case AgentStatus.INITIALIZING:
+ case AgentStatus.RUNNING:
+ return { glyph: '●', color: theme.status.warning };
+ case AgentStatus.IDLE:
+ return { glyph: '●', color: theme.status.success };
+ case AgentStatus.COMPLETED:
+ return { glyph: '✔', color: theme.status.success };
+ case AgentStatus.FAILED:
+ return { glyph: '✖', color: theme.status.error };
+ case AgentStatus.CANCELLED:
+ return { glyph: '○', color: theme.text.secondary };
+ default:
+ return { glyph: '●', color: theme.text.secondary };
+ }
+ }
if (entry.synthesized) {
// Outcome unknown — registry forgot the entry without going
// through complete / fail / cancel. Use a neutral marker so
@@ -177,8 +199,15 @@ export const LiveAgentPanel: React.FC<LiveAgentPanelProps> = ({
maxRows = DEFAULT_MAX_ROWS,
width,
}) => {
- const { entries, dialogOpen, livePanelFocused, livePanelSelectedIndex } =
- useBackgroundTaskViewState();
+ const {
+ entries,
+ liveAgentEntries,
+ dialogOpen,
+ livePanelFocused,
+ livePanelSelectedIndex,
+ } = useBackgroundTaskViewState();
+ const rosterEntries =
+ liveAgentEntries ?? entries.filter((entry) => entry.kind === 'agent');
const { setLivePanelFocused } = useBackgroundTaskViewActions();
// Reach for Config via the raw context (NOT useConfig) so the panel
// can degrade to snapshot-only when no provider is mounted — e.g.
@@ -205,7 +234,9 @@ export const LiveAgentPanel: React.FC<LiveAgentPanelProps> = ({
useEffect(() => {
if (dialogOpen) return;
const needsTick = (whenMs: number) =>
- entries.some((e) => isLiveAgentPanelVisibleEntry(e, whenMs));
+ rosterEntries.some((entry) =>
+ isLiveAgentPanelVisibleEntry(entry, whenMs),
+ );
if (!needsTick(Date.now())) return;
const id = setInterval(() => {
const wallNow = Date.now();
@@ -217,7 +248,7 @@ export const LiveAgentPanel: React.FC<LiveAgentPanelProps> = ({
if (!needsTick(wallNow)) clearInterval(id);
}, 1000);
return () => clearInterval(id);
- }, [entries, dialogOpen]);
+ }, [dialogOpen, rosterEntries]);
// Re-pull each agent from the live registry on every tick so the row
// shows the latest `recentActivities` — `useBackgroundTaskView`
@@ -272,8 +303,8 @@ export const LiveAgentPanel: React.FC<LiveAgentPanelProps> = ({
// ref outlives both the snapshot and the tick state.
const missingSinceRef = useRef<Map<string, number>>(new Map());
- const liveAgentSnapshots: AgentDialogEntry[] = useMemo(() => {
- const snapshots = entries.filter(isAgentEntry);
+ const liveAgentSnapshots: LiveAgentDialogEntry[] = useMemo(() => {
+ const snapshots = rosterEntries.filter(isAgentEntry);
if (!config) return snapshots;
const registry = config.getBackgroundTaskRegistry();
// `now` participates in the dependency array so the memo recomputes
@@ -287,6 +318,7 @@ export const LiveAgentPanel: React.FC<LiveAgentPanelProps> = ({
const next = snapshots
.map((snap) => {
seenIds.add(snap.agentId);
+ if (isTeamAgentDialogEntry(snap)) return snap;
const live = registry.get(snap.agentId);
if (live) {
// Recovered (or never went missing) — drop any stale
@@ -335,7 +367,7 @@ export const LiveAgentPanel: React.FC<LiveAgentPanelProps> = ({
// the visibility window has no way to evict.
return null;
})
- .filter((e): e is AgentDialogEntry => e !== null);
+ .filter((e): e is LiveAgentDialogEntry => e !== null);
// GC: drop missing-since records for agents that are no longer
// even in the snapshot (e.g. statusChange refreshed and the
// entry left useBackgroundTaskView's view entirely).
@@ -343,7 +375,7 @@ export const LiveAgentPanel: React.FC<LiveAgentPanelProps> = ({
if (!seenIds.has(id)) missingSinceRef.current.delete(id);
}
return next;
- }, [entries, config, now]);
+ }, [rosterEntries, config, now]);
const hasVisibleAgent = liveAgentSnapshots.some((entry) =>
isLiveAgentPanelVisibleEntry(entry, now),
@@ -381,7 +413,7 @@ export const LiveAgentPanel: React.FC<LiveAgentPanelProps> = ({
};
const LiveAgentPanelBody: React.FC<{
- snapshots: AgentDialogEntry[];
+ snapshots: LiveAgentDialogEntry[];
now: number;
maxRows: number;
width: number | undefined;
@@ -441,7 +473,7 @@ const LiveAgentPanelBody: React.FC<{
{focused && (
<Box>
<Text color={theme.text.secondary}>
- {' ↑↓ navigate · Enter detail · Esc back'}
+ {' ↑↓ navigate · Enter open · Esc back'}
</Text>
</Box>
)}
@@ -450,7 +482,7 @@ const LiveAgentPanelBody: React.FC<{
};
const AgentRow: React.FC<{
- entry: AgentDialogEntry;
+ entry: LiveAgentDialogEntry;
now: number;
selected?: boolean;
tree?: AgentTreeInfo;
@@ -489,6 +521,9 @@ const AgentRow: React.FC<{
entry.stats?.outputTokens && entry.stats.outputTokens > 0
? ` · ${formatTokenCount(entry.stats.outputTokens)} tokens`
: '';
+ const teamStatusSuffix = isTeamAgentDialogEntry(entry)
+ ? ` · ${entry.teamStatus}`
+ : '';
// Layout (Claude Code's CoordinatorTaskPanel visual + our
// right-pin to keep elapsed / tokens from being clipped):
@@ -508,7 +543,7 @@ const AgentRow: React.FC<{
// columns sit side by side at intrinsic widths; empty slack
// falls off the row tail rather than opening a visual gap
// between the description and the right-pinned elapsed.
- const tail = ` ▶ ${elapsed}${tokenSuffix}`;
+ const tail = ` ▶ ${elapsed}${teamStatusSuffix}${tokenSuffix}`;
const prefix = selected ? '▸ ' : ' ';
// Tree gutter (indent + ↳) comes from the shared agent-forest helper so
// the panel and the dialog list can't drift; the orphan additionally
@@ -534,7 +569,14 @@ const AgentRow: React.FC<{
<Text color={color}>{`${glyph} `}</Text>
{showType && (
<>
- <Text bold>{safeSubagentType}</Text>
+ <Text
+ bold
+ color={
+ isTeamAgentDialogEntry(entry) ? entry.teamColor : undefined
+ }
+ >
+ {safeSubagentType}
+ </Text>
<Text color={theme.text.secondary}>{': '}</Text>
</>
)}
diff --git a/packages/cli/src/ui/components/background-view/liveAgentPanelVisibility.ts b/packages/cli/src/ui/components/background-view/liveAgentPanelVisibility.ts
index d35307c2d89..cf0f5a7ad06 100644
--- a/packages/cli/src/ui/components/background-view/liveAgentPanelVisibility.ts
+++ b/packages/cli/src/ui/components/background-view/liveAgentPanelVisibility.ts
@@ -4,10 +4,13 @@
* SPDX-License-Identifier: Apache-2.0
*/
+import type { DialogEntry } from '../../hooks/useBackgroundTaskView.js';
import type {
- AgentDialogEntry,
- DialogEntry,
-} from '../../hooks/useBackgroundTaskView.js';
+ LiveAgentDialogEntry,
+ TeamAgentDialogEntry,
+} from '../../hooks/use-team-agent-roster.js';
+
+type LiveAgentCandidate = DialogEntry | TeamAgentDialogEntry;
// Keep this shared with keyboard focus gates: anything counted here
// must be something the live panel can actually render.
@@ -49,9 +52,9 @@ export function getLiveAgentPanelVpMaxRows(terminalHeight: number): number {
}
export function isLiveAgentPanelVisibleEntry(
- entry: DialogEntry,
+ entry: LiveAgentCandidate,
nowMs: number,
-): entry is AgentDialogEntry {
+): entry is LiveAgentDialogEntry {
if (entry.kind !== 'agent') return false;
if (entry.status === 'running' || entry.status === 'paused') return true;
if (entry.endTime === undefined) return false;
@@ -83,7 +86,7 @@ export function isLiveAgentPanelVisibleEntry(
* direction (no overflow).
*/
export function getLiveAgentPanelLayoutKey(
- entries: readonly DialogEntry[],
+ entries: readonly LiveAgentCandidate[],
livePanelFocused: boolean,
): string {
let key = livePanelFocused ? 'f' : '_';
diff --git a/packages/cli/src/ui/contexts/BackgroundTaskViewContext.tsx b/packages/cli/src/ui/contexts/BackgroundTaskViewContext.tsx
index 355da31c6e5..063f673249c 100644
--- a/packages/cli/src/ui/contexts/BackgroundTaskViewContext.tsx
+++ b/packages/cli/src/ui/contexts/BackgroundTaskViewContext.tsx
@@ -22,9 +22,15 @@ import {
import type { Config } from '@qwen-code/qwen-code-core/config/config.js';
import { createDebugLogger } from '@qwen-code/qwen-code-core/utils/debugLogger.js';
import {
+ compareActiveThenTerminal,
type DialogEntry,
useBackgroundTaskView,
} from '../hooks/useBackgroundTaskView.js';
+import {
+ type LiveAgentDialogEntry,
+ useTeamAgentRoster,
+} from '../hooks/use-team-agent-roster.js';
+import { useAgentViewState } from './AgentViewContext.js';
const debugLogger = createDebugLogger('BG_TASK_VIEW');
@@ -43,6 +49,8 @@ export interface BackgroundTaskViewState {
* a `kind` discriminator so renderers can dispatch on agent vs shell.
*/
entries: readonly DialogEntry[];
+ /** Agent-only rows rendered by LiveAgentPanel, including team members. */
+ liveAgentEntries?: readonly LiveAgentDialogEntry[];
/** Index into `entries` for the currently focused row (0-based). */
selectedIndex: number;
/** `'closed'` when the overlay isn't mounted; otherwise the active mode. */
@@ -98,6 +106,7 @@ export const BackgroundTaskViewActionsContext =
const DEFAULT_STATE: BackgroundTaskViewState = {
entries: [],
+ liveAgentEntries: [],
selectedIndex: 0,
dialogMode: 'closed',
dialogOpen: false,
@@ -148,6 +157,19 @@ export function BackgroundTaskViewProvider({
children,
}: BackgroundTaskViewProviderProps) {
const { entries } = useBackgroundTaskView(config ?? null);
+ const { agents } = useAgentViewState();
+ const teamAgentEntries = useTeamAgentRoster(config ?? null, agents);
+ const liveAgentEntries = useMemo(
+ () =>
+ [
+ ...entries.filter(
+ (entry): entry is Extract<DialogEntry, { kind: 'agent' }> =>
+ entry.kind === 'agent',
+ ),
+ ...teamAgentEntries,
+ ].sort(compareActiveThenTerminal),
+ [entries, teamAgentEntries],
+ );
const [rawSelectedIndex, setRawSelectedIndex] = useState(0);
const [dialogMode, setDialogMode] = useState<BackgroundDialogMode>('closed');
@@ -169,7 +191,7 @@ export function BackgroundTaskViewProvider({
if (pillFocused && !hasEntries) setPillFocused(false);
}, [pillFocused, hasEntries]);
- const hasAgentEntries = entries.some((e) => e.kind === 'agent');
+ const hasAgentEntries = liveAgentEntries.length > 0;
useEffect(() => {
if (livePanelFocused && !hasAgentEntries) setLivePanelFocusedRaw(false);
}, [livePanelFocused, hasAgentEntries]);
@@ -321,6 +343,7 @@ export function BackgroundTaskViewProvider({
const state: BackgroundTaskViewState = useMemo(
() => ({
entries,
+ liveAgentEntries,
selectedIndex,
dialogMode,
dialogOpen,
@@ -330,6 +353,7 @@ export function BackgroundTaskViewProvider({
}),
[
entries,
+ liveAgentEntries,
selectedIndex,
dialogMode,
dialogOpen,
diff --git a/packages/cli/src/ui/hooks/use-team-agent-roster.identity.test.ts b/packages/cli/src/ui/hooks/use-team-agent-roster.identity.test.ts
new file mode 100644
index 00000000000..e5606dba033
--- /dev/null
+++ b/packages/cli/src/ui/hooks/use-team-agent-roster.identity.test.ts
@@ -0,0 +1,49 @@
+/**
+ * @license
+ * Copyright 2026 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// @vitest-environment jsdom
+
+import { describe, expect, it } from 'vitest';
+import { renderHook } from '@testing-library/react';
+import type { Config } from '@qwen-code/qwen-code-core/config/config.js';
+import { useTeamAgentRoster } from './use-team-agent-roster.js';
+
+/**
+ * The roster feeds `LiveAgentPanel`, which keys its one-second elapsed-time
+ * interval on the array identity. A fresh array per render tears that
+ * interval down and recreates it before it can fire, so elapsed times stop
+ * advancing — and the no-team path runs for every user, not just teams.
+ */
+describe('useTeamAgentRoster identity', () => {
+ it('keeps the same array across renders when no team is active', () => {
+ const registeredAgents = new Map<string, unknown>();
+ const { result, rerender } = renderHook(() =>
+ useTeamAgentRoster(null, registeredAgents),
+ );
+
+ const first = result.current;
+ rerender();
+ rerender();
+
+ expect(result.current).toHaveLength(0);
+ expect(result.current).toBe(first);
+ });
+
+ it('keeps the same array across renders when the config has no team', () => {
+ const config = {
+ onTeamManagerChange: () => {},
+ getTeamManager: () => null,
+ } as unknown as Config;
+ const registeredAgents = new Map<string, unknown>();
+ const { result, rerender } = renderHook(() =>
+ useTeamAgentRoster(config, registeredAgents),
+ );
+
+ const first = result.current;
+ rerender();
+
+ expect(result.current).toBe(first);
+ });
+});
diff --git a/packages/cli/src/ui/hooks/use-team-agent-roster.test.ts b/packages/cli/src/ui/hooks/use-team-agent-roster.test.ts
new file mode 100644
index 00000000000..cd1af65c4e9
--- /dev/null
+++ b/packages/cli/src/ui/hooks/use-team-agent-roster.test.ts
@@ -0,0 +1,90 @@
+/**
+ * @license
+ * Copyright 2026 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, it } from 'vitest';
+import { AgentStatus } from '@qwen-code/qwen-code-core/agents/runtime/agent-types.js';
+import type { TeamManager } from '@qwen-code/qwen-code-core/agents/team/TeamManager.js';
+import type { SwarmTask } from '@qwen-code/qwen-code-core/agents/team/types.js';
+import { buildTeamAgentRosterEntries } from './use-team-agent-roster.js';
+
+describe('buildTeamAgentRosterEntries', () => {
+ it('keeps idle distinct and uses the assigned shared task as activity', () => {
+ const manager = {
+ getTeamFile: () => ({
+ name: 'review-team',
+ createdAt: 1,
+ leadAgentId: 'leader',
+ members: [
+ {
+ agentId: 'reviewer@review-team',
+ name: 'reviewer',
+ joinedAt: 1_000,
+ cwd: '/work/qwen-code',
+ tmuxPaneId: '',
+ subscriptions: [],
+ },
+ ],
+ }),
+ getAgentFromBackend: () => ({ getStatus: () => AgentStatus.IDLE }),
+ } as unknown as TeamManager;
+ const tasks: SwarmTask[] = [
+ {
+ id: '1',
+ subject: 'Review authentication flow',
+ description: 'Inspect auth changes',
+ activeForm: 'Reviewing authentication flow',
+ owner: 'reviewer',
+ status: 'in_progress',
+ blocks: [],
+ blockedBy: [],
+ },
+ ];
+
+ expect(
+ buildTeamAgentRosterEntries(
+ manager,
+ tasks,
+ new Map(),
+ new Set(['reviewer@review-team']),
+ 4_000,
+ ),
+ ).toEqual([
+ expect.objectContaining({
+ agentId: 'reviewer@review-team',
+ description: 'Reviewing authentication flow',
+ startTime: 1_000,
+ status: 'paused',
+ teamStatus: AgentStatus.IDLE,
+ teamTask: tasks[0],
+ }),
+ ]);
+ });
+
+ it('omits teammates that have no Agent tab in the in-process UI', () => {
+ const manager = {
+ getTeamFile: () => ({
+ name: 'review-team',
+ createdAt: 1,
+ leadAgentId: 'leader',
+ members: [
+ {
+ agentId: 'reviewer@review-team',
+ name: 'reviewer',
+ joinedAt: 1_000,
+ cwd: '/work/qwen-code',
+ tmuxPaneId: '',
+ subscriptions: [],
+ },
+ ],
+ }),
+ getAgentFromBackend: () => ({ getStatus: () => AgentStatus.RUNNING }),
+ } as unknown as TeamManager;
+
+ expect(
+ buildTeamAgentRosterEntries(manager, [], new Map(), new Set(), 4_000),
+ ).toEqual([]);
+ });
+});
diff --git a/packages/cli/src/ui/hooks/use-team-agent-roster.ts b/packages/cli/src/ui/hooks/use-team-agent-roster.ts
new file mode 100644
index 00000000000..4d979b7388b
--- /dev/null
+++ b/packages/cli/src/ui/hooks/use-team-agent-roster.ts
@@ -0,0 +1,198 @@
+/**
+ * @license
+ * Copyright 2026 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { useEffect, useMemo, useRef, useState } from 'react';
+import type { AgentTask } from '@qwen-code/qwen-code-core/agents/background-tasks.js';
+import {
+ AgentStatus,
+ isTerminalStatus,
+} from '@qwen-code/qwen-code-core/agents/runtime/agent-types.js';
+import {
+ TeamEventType,
+ type TeammateExitedEvent,
+ type TeammateStatusChangeEvent,
+} from '@qwen-code/qwen-code-core/agents/team/team-events.js';
+import {
+ listTasks,
+ onTasksUpdated,
+} from '@qwen-code/qwen-code-core/agents/team/tasks.js';
+import type { TeamManager } from '@qwen-code/qwen-code-core/agents/team/TeamManager.js';
+import type { SwarmTask } from '@qwen-code/qwen-code-core/agents/team/types.js';
+import type { Config } from '@qwen-code/qwen-code-core/config/config.js';
+
+export interface TeamAgentDialogEntry extends AgentTask {
+ teamName: string;
+ teamStatus: AgentStatus;
+ teamColor?: string;
+ teamTask?: SwarmTask;
+}
+
+export type LiveAgentDialogEntry = AgentTask | TeamAgentDialogEntry;
+
+export function isTeamAgentDialogEntry(
+ entry: LiveAgentDialogEntry,
+): entry is TeamAgentDialogEntry {
+ return 'teamName' in entry;
+}
+
+function panelStatus(status: AgentStatus): AgentTask['status'] {
+ if (status === AgentStatus.IDLE) return 'paused';
+ if (status === AgentStatus.INITIALIZING || status === AgentStatus.RUNNING) {
+ return 'running';
+ }
+ return status;
+}
+
+export function buildTeamAgentRosterEntries(
+ manager: TeamManager,
+ tasks: readonly SwarmTask[],
+ terminalEndTimes: Map<string, number>,
+ registeredAgentIds: ReadonlySet<string>,
+ now = Date.now(),
+): TeamAgentDialogEntry[] {
+ const team = manager.getTeamFile();
+ return team.members.flatMap((member) => {
+ if (!registeredAgentIds.has(member.agentId)) return [];
+ const agent = manager.getAgentFromBackend(member.agentId);
+ if (!agent) return [];
+ const teamStatus = agent.getStatus();
+ if (isTerminalStatus(teamStatus) && !terminalEndTimes.has(member.agentId)) {
+ terminalEndTimes.set(member.agentId, now);
+ }
+ const task = tasks.find(
+ (candidate) =>
+ candidate.status === 'in_progress' &&
+ (candidate.owner === member.agentId || candidate.owner === member.name),
+ );
+ return [
+ {
+ kind: 'agent',
+ id: member.agentId,
+ agentId: member.agentId,
+ description:
+ task?.activeForm ??
+ task?.subject ??
+ (teamStatus === AgentStatus.IDLE
+ ? 'waiting for work'
+ : (member.agentType ?? 'working')),
+ status: panelStatus(teamStatus),
+ startTime: member.joinedAt,
+ ...(terminalEndTimes.has(member.agentId)
+ ? { endTime: terminalEndTimes.get(member.agentId) }
+ : {}),
+ outputFile: '',
+ outputOffset: 0,
+ notified: false,
+ abortController: new AbortController(),
+ subagentType: member.name,
+ model: member.model,
+ isBackgrounded: false,
+ pendingMessages: [],
+ teamName: team.name,
+ teamStatus,
+ teamColor: member.color,
+ teamTask: task,
+ },
+ ];
+ });
+}
+
+/**
+ * Shared identity for the no-team case. Returning a fresh `[]` would make
+ * this hook's result change on every render, and `LiveAgentPanel` keys its
+ * one-second elapsed-time interval on that array — a new identity each
+ * render tears the interval down and recreates it before it can ever fire,
+ * freezing elapsed times for every user, team or not.
+ */
+const NO_TEAM_ENTRIES: TeamAgentDialogEntry[] = [];
+
+export function useTeamAgentRoster(
+ config: Config | null,
+ registeredAgents: ReadonlyMap<string, unknown>,
+): TeamAgentDialogEntry[] {
+ const [manager, setManager] = useState<TeamManager | null>(null);
+ const [tasks, setTasks] = useState<SwarmTask[]>([]);
+ const [revision, setRevision] = useState(0);
+ const terminalEndTimes = useRef(new Map<string, number>());
+
+ useEffect(() => {
+ if (!config) return;
+ let detachManager: (() => void) | undefined;
+ let generation = 0;
+
+ const attach = (next: TeamManager | null) => {
+ detachManager?.();
+ detachManager = undefined;
+ generation += 1;
+ const attachedGeneration = generation;
+ terminalEndTimes.current.clear();
+ setManager(next);
+ setTasks([]);
+ if (!next) return;
+
+ const teamName = next.getTeamFile().name;
+ const refreshTasks = () => {
+ void listTasks(teamName)
+ .then((snapshot) => {
+ if (generation === attachedGeneration) setTasks(snapshot);
+ })
+ .catch(() => undefined);
+ };
+ const refresh = () => setRevision((value) => value + 1);
+ const onStatus = (event: TeammateStatusChangeEvent) => {
+ if (isTerminalStatus(event.newStatus)) {
+ terminalEndTimes.current.set(event.agentId, event.timestamp);
+ }
+ refresh();
+ };
+ const onExit = (event: TeammateExitedEvent) => {
+ terminalEndTimes.current.set(event.agentId, event.timestamp);
+ refresh();
+ };
+ const emitter = next.getEventEmitter();
+ emitter.on(TeamEventType.TEAMMATE_JOINED, refresh);
+ emitter.on(TeamEventType.TEAMMATE_IDLE, refresh);
+ emitter.on(TeamEventType.TEAMMATE_STATUS_CHANGE, onStatus);
+ emitter.on(TeamEventType.TEAMMATE_EXITED, onExit);
+ const unsubscribeTasks = onTasksUpdated((updatedTeamName) => {
+ if (updatedTeamName === teamName) refreshTasks();
+ });
+ refreshTasks();
+ detachManager = () => {
+ emitter.off(TeamEventType.TEAMMATE_JOINED, refresh);
+ emitter.off(TeamEventType.TEAMMATE_IDLE, refresh);
+ emitter.off(TeamEventType.TEAMMATE_STATUS_CHANGE, onStatus);
+ emitter.off(TeamEventType.TEAMMATE_EXITED, onExit);
+ unsubscribeTasks();
+ };
+ };
+
+ config.onTeamManagerChange(attach);
+ attach(config.getTeamManager());
+ return () => {
+ generation += 1;
+ detachManager?.();
+ config.onTeamManagerChange(null, attach);
+ };
+ }, [config]);
+
+ return useMemo(
+ () =>
+ manager
+ ? buildTeamAgentRosterEntries(
+ manager,
+ tasks,
+ terminalEndTimes.current,
+ new Set(registeredAgents.keys()),
+ )
+ : NO_TEAM_ENTRIES,
+ // `revision` is a change token, not an input: a teammate's status lives
+ // on its backend agent rather than in props, so a lifecycle event is the
+ // only thing that can tell this memo to re-read it.
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ [manager, tasks, registeredAgents, revision],
+ );
+}
diff --git a/packages/core/src/agents/agent-transcript.test.ts b/packages/core/src/agents/agent-transcript.test.ts
index e2f14b59060..ca31b93e58a 100644
--- a/packages/core/src/agents/agent-transcript.test.ts
+++ b/packages/core/src/agents/agent-transcript.test.ts
@@ -792,6 +792,7 @@ describe('agent-transcript', () => {
subagentId: 'agent-x',
kind: 'message',
text: 'follow-up from parent',
+ deliveryId: 'delivery-1',
timestamp: 100,
});
cleanup();
@@ -804,6 +805,7 @@ describe('agent-transcript', () => {
parts: [{ text: 'follow-up from parent' }],
});
expect(records[1].externalInputKind).toBe('message');
+ expect(records[1].externalInputDeliveryId).toBe('delivery-1');
expect(records[1].parentUuid).toBe(records[0].uuid);
});
diff --git a/packages/core/src/agents/agent-transcript.ts b/packages/core/src/agents/agent-transcript.ts
index 9e793b168e9..e829fd1b6cd 100644
--- a/packages/core/src/agents/agent-transcript.ts
+++ b/packages/core/src/agents/agent-transcript.ts
@@ -815,12 +815,14 @@ export function attachJsonlTranscriptWriter(
const recordUserMessage = (
text: string,
externalInputKind?: AgentExternalMessageEvent['kind'],
+ externalInputDeliveryId?: string,
) => {
if (!text) return;
append({
...baseFields('user'),
message: { role: 'user', parts: [{ text }] },
...(externalInputKind ? { externalInputKind } : {}),
+ ...(externalInputDeliveryId ? { externalInputDeliveryId } : {}),
});
};
@@ -836,7 +838,11 @@ export function attachJsonlTranscriptWriter(
};
const onExternalMessage = (event: AgentExternalMessageEvent) => {
- recordUserMessage(event.text, event.kind ?? 'message');
+ recordUserMessage(
+ event.text,
+ event.kind ?? 'message',
+ event.deliveryId,
+ );
};
if (options.bootstrapHistory !== undefined) {
diff --git a/packages/core/src/agents/backends/InProcessBackend.ts b/packages/core/src/agents/backends/InProcessBackend.ts
index 5717103688b..83f93492a82 100644
--- a/packages/core/src/agents/backends/InProcessBackend.ts
+++ b/packages/core/src/agents/backends/InProcessBackend.ts
@@ -20,6 +20,7 @@ import {
installSessionWorkflowRevisionWriteThrough,
type Config,
type DerivedApprovalModeConfigHooks,
+ type MCPServerConfig,
} from '../../config/config.js';
import { Storage } from '../../config/storage.js';
import { type ContentGenerator } from '../../core/contentGenerator.js';
@@ -141,6 +142,7 @@ export class InProcessBackend implements Backend {
inProcessConfig.runtimeConfig.modelConfig.model,
inProcessConfig.authOverrides,
inProcessConfig.approvalMode,
+ inProcessConfig.mcpServers,
{
acquireAutoApprovalOverride: () => this.acquireAutoApprovalOverride(),
releaseAutoApprovalOverride: () => this.releaseAutoApprovalOverride(),
@@ -569,6 +571,7 @@ async function createPerAgentConfig(
modelId?: string,
authOverrides?: InProcessSpawnConfig['authOverrides'],
approvalMode?: ApprovalMode,
+ mcpServers?: Record<string, MCPServerConfig>,
approvalModeHooks?: DerivedApprovalModeConfigHooks,
): Promise<{
config: Config;
@@ -611,6 +614,11 @@ async function createPerAgentConfig(
let agentRegistry: ToolRegistry | undefined;
try {
+ if (mcpServers && Object.keys(mcpServers).length > 0) {
+ const merged = { ...(base.getMcpServers() ?? {}), ...mcpServers };
+ override.getMcpServers = () => merged;
+ }
+
// Delegated rather than re-enacted. The three steps below used to be
// inlined here, identical to the shared helper — and a second copy is a
// second place for an invariant to be broken: a change sharing the
@@ -631,6 +639,21 @@ async function createPerAgentConfig(
});
agentRegistry = override.getToolRegistry();
+ if (mcpServers) {
+ const serverNames = Object.keys(mcpServers);
+ const results = await Promise.allSettled(
+ serverNames.map((name) => agentRegistry!.discoverToolsForServer(name)),
+ );
+ for (let i = 0; i < results.length; i++) {
+ const result = results[i];
+ if (result.status === 'rejected') {
+ debugLogger.warn(
+ `Failed to discover MCP server "${serverNames[i]}" for agent "${agentId}": ${result.reason instanceof Error ? result.reason.message : String(result.reason)}`,
+ );
+ }
+ }
+ }
+
if (authOverrides?.authType) {
try {
runtimeView = await createRuntimeContentGeneratorView(
diff --git a/packages/core/src/agents/backends/types.ts b/packages/core/src/agents/backends/types.ts
index 9180784c9e8..d4e02bfcd1b 100644
--- a/packages/core/src/agents/backends/types.ts
+++ b/packages/core/src/agents/backends/types.ts
@@ -23,7 +23,7 @@ import type {
ToolConfig,
} from '../runtime/agent-types.js';
import type { AgentEventEmitter } from '../runtime/agent-events.js';
-import type { ApprovalMode } from '../../config/config.js';
+import type { ApprovalMode, MCPServerConfig } from '../../config/config.js';
import type { TeammateIdentity } from '../team/types.js';
/**
@@ -109,6 +109,8 @@ export interface InProcessSpawnConfig {
apiKey?: string;
baseUrl?: string;
};
+ /** Optional MCP servers declared by this agent definition. */
+ mcpServers?: Record<string, MCPServerConfig>;
/**
* Optional chat history from the parent session. When provided, this
* history is prepended to the agent's chat so it has conversational
diff --git a/packages/core/src/agents/background-agent-resume.test.ts b/packages/core/src/agents/background-agent-resume.test.ts
index b876f8ce5cd..868f8356da4 100644
--- a/packages/core/src/agents/background-agent-resume.test.ts
+++ b/packages/core/src/agents/background-agent-resume.test.ts
@@ -3150,6 +3150,22 @@ describe('BackgroundAgentResumeService', () => {
type: 'user',
message: { role: 'user', parts: [{ text: 'and another thing' }] },
}),
+ JSON.stringify({
+ uuid: 'a2',
+ parentUuid: 'u2',
+ sessionId,
+ timestamp: '2026-04-20T00:00:00.600Z',
+ type: 'assistant',
+ message: { role: 'model', parts: [{ text: 'still working' }] },
+ }),
+ JSON.stringify({
+ uuid: 'u3',
+ parentUuid: 'a2',
+ sessionId,
+ timestamp: '2026-04-20T00:00:00.700Z',
+ type: 'user',
+ message: { role: 'user', parts: [{ text: 'one final constraint' }] },
+ }),
].join('\n') + '\n',
'utf8',
);
@@ -3230,6 +3246,8 @@ describe('BackgroundAgentResumeService', () => {
},
{ role: 'model', parts: [{ text: 'working' }] },
{ role: 'user', parts: [{ text: 'and another thing' }] },
+ { role: 'model', parts: [{ text: 'still working' }] },
+ { role: 'user', parts: [{ text: 'one final constraint' }] },
],
},
}),
@@ -3338,9 +3356,13 @@ describe('BackgroundAgentResumeService', () => {
oldSessionMtime.getTime(),
);
- expect(registry.continueResidentAgent(agentId, 'tighten the summary')).toBe(
- true,
- );
+ expect(
+ registry.continueResidentAgent(
+ agentId,
+ 'tighten the summary',
+ 'delivery-2',
+ ),
+ ).toBe('continued');
expect(registry.get(agentId)?.status).toBe('running');
await vi.waitFor(() => {
expect(execute).toHaveBeenCalledTimes(2);
@@ -3348,14 +3370,23 @@ describe('BackgroundAgentResumeService', () => {
});
expect(subagentManager.createAgentHeadless).toHaveBeenCalledTimes(1);
const hotContextArg = execute.mock.calls[1]?.[0];
- expect(hotContextArg?.get('task_prompt')).toBe('tighten the summary');
+ expect(hotContextArg?.get('task_prompt')).toBeUndefined();
+ expect(hotContextArg?.get('external_inputs_override')).toEqual([
+ {
+ kind: 'message',
+ text: 'tighten the summary',
+ deliveryId: 'delivery-2',
+ },
+ ]);
expect(readAgentMeta(metaPath)?.resumeCount).toBe(2);
expect(dispose).not.toHaveBeenCalled();
registry.reset();
expect(dispose).toHaveBeenCalledTimes(1);
- expect(registry.continueResidentAgent(agentId, 'again')).toBe(false);
+ expect(registry.continueResidentAgent(agentId, 'again')).toBe(
+ 'not_completed',
+ );
});
it("clears the previous incarnation's stats and activities when cold-reviving", async () => {
@@ -3660,7 +3691,7 @@ describe('BackgroundAgentResumeService', () => {
});
expect(subagentManager.createAgentHeadless).toHaveBeenCalledOnce();
- expect(registry.continueResidentAgent(agentId, 'again')).toBe(false);
+ expect(registry.continueResidentAgent(agentId, 'again')).toBe('fallback');
expect(dispose).toHaveBeenCalledOnce();
});
diff --git a/packages/core/src/agents/background-agent-resume.ts b/packages/core/src/agents/background-agent-resume.ts
index 22624bde8d4..03d27aec766 100644
--- a/packages/core/src/agents/background-agent-resume.ts
+++ b/packages/core/src/agents/background-agent-resume.ts
@@ -1416,13 +1416,17 @@ export class BackgroundAgentResumeService {
};
const residentController: ResidentBackgroundAgent = {
- continue: (message) => {
+ continue: (input) => {
if (!canStayResident || disposeRequested || runtimeDisposed) {
- return false;
+ return 'fallback';
}
if (needsAutoPermissionLease()) {
requestRuntimeDisposal();
- return false;
+ return 'fallback';
+ }
+
+ if (!registry.canStartBackgroundAgent(meta.model)) {
+ return 'capacity_wait';
}
const nextAbortController = new AbortController();
@@ -1438,7 +1442,9 @@ export class BackgroundAgentResumeService {
meta.agentId
}: ${error instanceof Error ? error.message : String(error)}`,
);
- return false;
+ return registry.canStartBackgroundAgent(meta.model)
+ ? 'fallback'
+ : 'capacity_wait';
}
if (
!restarted ||
@@ -1447,7 +1453,7 @@ export class BackgroundAgentResumeService {
registry.get(meta.agentId) !== restarted ||
restarted.status !== 'running'
) {
- return false;
+ return 'fallback';
}
liveToolCallCount = 0;
@@ -1465,7 +1471,11 @@ export class BackgroundAgentResumeService {
});
const nextContextState = new ContextState();
- nextContextState.set('task_prompt', message);
+ if (typeof input === 'string') {
+ nextContextState.set('task_prompt', input);
+ } else {
+ nextContextState.set('external_inputs_override', [input]);
+ }
nextContextState.set('hook_context', '');
const previousTurn = currentTurnPromise ?? Promise.resolve();
currentTurnPromise = previousTurn
@@ -1479,7 +1489,7 @@ export class BackgroundAgentResumeService {
);
});
currentTurnPromise.catch(reportUnexpectedBackgroundError);
- return true;
+ return 'continued';
},
dispose: requestRuntimeDisposal,
};
diff --git a/packages/core/src/agents/background-tasks.test.ts b/packages/core/src/agents/background-tasks.test.ts
index e8906dbd1bc..78b1cad6558 100644
--- a/packages/core/src/agents/background-tasks.test.ts
+++ b/packages/core/src/agents/background-tasks.test.ts
@@ -15,6 +15,7 @@ import {
type AgentTaskRegistration,
type BackgroundApproval,
type BackgroundTaskEntry,
+ type ResidentAgentContinuationResult,
type ResidentBackgroundAgent,
} from './background-tasks.js';
import {
@@ -297,7 +298,7 @@ describe('BackgroundTaskRegistry', () => {
overrides: Partial<ResidentBackgroundAgent> = {},
): ResidentBackgroundAgent {
return {
- continue: vi.fn(() => true),
+ continue: vi.fn(() => 'continued' as const),
dispose: vi.fn(),
...overrides,
};
@@ -309,14 +310,22 @@ describe('BackgroundTaskRegistry', () => {
registry.registerResidentAgent('resident-1', resident);
expect(registry.continueResidentAgent('resident-1', 'too early')).toBe(
- false,
+ 'not_completed',
);
registry.complete('resident-1', 'first result');
- expect(registry.continueResidentAgent('resident-1', 'keep going')).toBe(
- true,
- );
- expect(resident.continue).toHaveBeenCalledWith('keep going');
+ expect(
+ registry.continueResidentAgent(
+ 'resident-1',
+ 'keep going',
+ 'delivery-1',
+ ),
+ ).toBe('continued');
+ expect(resident.continue).toHaveBeenCalledWith({
+ kind: 'message',
+ text: 'keep going',
+ deliveryId: 'delivery-1',
+ });
const staleHandle = makeResident();
expect(registry.unregisterResidentAgent('resident-1', staleHandle)).toBe(
@@ -328,7 +337,7 @@ describe('BackgroundTaskRegistry', () => {
expect(resident.dispose).not.toHaveBeenCalled();
expect(
registry.continueResidentAgent('resident-1', 'after unregister'),
- ).toBe(false);
+ ).toBe('fallback');
});
it('disposes a replaced resident without letting its stale handle remove the replacement', () => {
@@ -477,7 +486,7 @@ describe('BackgroundTaskRegistry', () => {
registry.register(makeRegistration('cancelled-completion'));
const resident = makeResident();
registry.registerResidentAgent('cancelled-completion', resident);
- let continuation: boolean | undefined;
+ let continuation: ResidentAgentContinuationResult | undefined;
registry.setNotificationCallback(() => {
continuation = registry.continueResidentAgent(
'cancelled-completion',
@@ -488,7 +497,7 @@ describe('BackgroundTaskRegistry', () => {
registry.cancel('cancelled-completion');
registry.complete('cancelled-completion', 'finished while cancelling');
- expect(continuation).toBe(false);
+ expect(continuation).toBe('fallback');
expect(resident.continue).not.toHaveBeenCalled();
expect(resident.dispose).toHaveBeenCalledOnce();
});
@@ -899,6 +908,24 @@ describe('BackgroundTaskRegistry', () => {
expect(registry.get('bg-2')?.status).toBe('running');
});
+ it('does not count idle resident runtimes as claimed slots', () => {
+ registry = new BackgroundTaskRegistry({
+ maxConcurrentBackgroundAgents: 1,
+ });
+
+ for (const agentId of ['resident-1', 'resident-2', 'resident-3']) {
+ registry.register(makeRegistration(agentId));
+ registry.complete(agentId, 'done');
+ registry.registerResidentAgent(agentId, {
+ continue: vi.fn(() => 'continued' as const),
+ dispose: vi.fn(),
+ });
+ }
+
+ expect(registry.canStartBackgroundAgent()).toBe(true);
+ expect(() => registry.register(makeRegistration('next'))).not.toThrow();
+ });
+
it('queues waiters until a background slot is released', async () => {
registry = new BackgroundTaskRegistry({
maxConcurrentBackgroundAgents: 1,
@@ -1867,7 +1894,7 @@ describe('BackgroundTaskRegistry', () => {
it('disposes a resident runtime when its terminal entry is evicted', () => {
registry.register(makeRegisteredEntry('resident-oldest', 0));
const resident = {
- continue: vi.fn(() => true),
+ continue: vi.fn(() => 'continued' as const),
dispose: vi.fn(),
};
registry.registerResidentAgent('resident-oldest', resident);
diff --git a/packages/core/src/agents/background-tasks.ts b/packages/core/src/agents/background-tasks.ts
index 2f1ac1633f0..128f306b269 100644
--- a/packages/core/src/agents/background-tasks.ts
+++ b/packages/core/src/agents/background-tasks.ts
@@ -450,13 +450,19 @@ export type BackgroundActivityChangeCallback = (entry: AgentTask) => void;
*/
export type BackgroundApprovalChangeCallback = (entry: AgentTask) => void;
+export type ResidentAgentContinuationResult =
+ | 'continued'
+ | 'fallback'
+ | 'capacity_wait'
+ | 'not_completed';
+
/**
* Session-scoped handle for a background agent whose runtime remains alive
* after a completed turn. The handle is deliberately not part of AgentTask:
* task state is serializable, while the live runtime is process-local.
*/
export interface ResidentBackgroundAgent {
- continue(message: string): boolean;
+ continue(input: AgentExternalInput): ResidentAgentContinuationResult;
dispose(): void;
}
@@ -787,11 +793,20 @@ export class BackgroundTaskRegistry {
this.residentAgents.set(agentId, resident);
}
- continueResidentAgent(agentId: string, message: string): boolean {
+ continueResidentAgent(
+ agentId: string,
+ message: string,
+ deliveryId?: string,
+ ): ResidentAgentContinuationResult {
const entry = this.agents.get(agentId);
const resident = this.residentAgents.get(agentId);
- if (!resident || entry?.status !== 'completed') return false;
- return resident.continue(message);
+ if (entry?.status !== 'completed') return 'not_completed';
+ if (!resident) return 'fallback';
+ return resident.continue(
+ deliveryId !== undefined
+ ? { kind: 'message', text: message, deliveryId }
+ : message,
+ );
}
unregisterResidentAgent(
diff --git a/packages/core/src/agents/mesh/dispatch-policy.test.ts b/packages/core/src/agents/mesh/dispatch-policy.test.ts
new file mode 100644
index 00000000000..804fe5c4956
--- /dev/null
+++ b/packages/core/src/agents/mesh/dispatch-policy.test.ts
@@ -0,0 +1,233 @@
+/**
+ * @license
+ * Copyright 2026 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+ decideDispatch,
+ resolveTargets,
+ type DispatchContext,
+} from './dispatch-policy.js';
+import {
+ HUMAN_AUTHOR_ID,
+ type MeshAgent,
+ type Thread,
+ type ThreadMessage,
+ type ThreadRun,
+} from './types.js';
+
+function agent(overrides: Partial<MeshAgent> = {}): MeshAgent {
+ return { id: 'ag_alice', name: 'alice', createdAt: 1_000, ...overrides };
+}
+
+function thread(overrides: Partial<Thread> = {}): Thread {
+ return {
+ id: 'th_1',
+ title: 'Investigate the flake',
+ body: '',
+ status: 'open',
+ createdAt: 1_000,
+ createdBy: HUMAN_AUTHOR_ID,
+ rootThreadId: 'th_1',
+ messages: [],
+ runs: [],
+ autoTurnsUsed: 0,
+ tokensUsed: 0,
+ ...overrides,
+ };
+}
+
+function message(overrides: Partial<ThreadMessage> = {}): ThreadMessage {
+ return {
+ id: 'ms_1',
+ from: HUMAN_AUTHOR_ID,
+ text: 'have a look',
+ mentions: [],
+ at: 2_000,
+ ...overrides,
+ };
+}
+
+function run(overrides: Partial<ThreadRun> = {}): ThreadRun {
+ return {
+ id: 'rn_1',
+ agentId: 'ag_alice',
+ status: 'queued',
+ triggerMessageIds: ['ms_0'],
+ queuedAt: 1_500,
+ attempts: 0,
+ ...overrides,
+ };
+}
+
+function context(overrides: Partial<DispatchContext> = {}): DispatchContext {
+ return {
+ thread: thread(),
+ message: message({ mentions: ['ag_alice'] }),
+ target: agent(),
+ budget: { autoTurnsUsed: 0, tokensUsed: 0 },
+ agentQueuedElsewhere: 0,
+ ...overrides,
+ };
+}
+
+describe('decideDispatch', () => {
+ it('books a run for a mentioned, idle agent', () => {
+ expect(decideDispatch(context())).toEqual({ kind: 'dispatch' });
+ });
+
+ it('never wakes an agent on its own post', () => {
+ expect(
+ decideDispatch(
+ context({
+ message: message({ from: 'ag_alice', mentions: ['ag_alice'] }),
+ }),
+ ),
+ ).toEqual({ kind: 'skip', reason: 'self_trigger' });
+ });
+
+ it('coalesces into a run that has not started', () => {
+ expect(
+ decideDispatch(
+ context({ thread: thread({ runs: [run({ status: 'queued' })] }) }),
+ ),
+ ).toEqual({ kind: 'coalesce', runId: 'rn_1', into: 'queued' });
+ });
+
+ it('coalesces into a run already executing this same thread', () => {
+ // Mid-run delivery is available here, so booking a second run would be
+ // waste — this is the case Multica has to defer.
+ expect(
+ decideDispatch(
+ context({ thread: thread({ runs: [run({ status: 'running' })] }) }),
+ ),
+ ).toEqual({ kind: 'coalesce', runId: 'rn_1', into: 'running' });
+ });
+
+ it('still books when the agent is busy on another thread', () => {
+ // Whether a queued run can start now is the dispatcher's call, not a rule.
+ expect(decideDispatch(context({ agentQueuedElsewhere: 1 }))).toEqual({
+ kind: 'dispatch',
+ });
+ });
+
+ it('refuses once the agent queue is full', () => {
+ expect(
+ decideDispatch(
+ context({ target: agent({ queueLimit: 2 }), agentQueuedElsewhere: 2 }),
+ ),
+ ).toEqual({ kind: 'skip', reason: 'queue_full' });
+ });
+
+ it('stops an agent-to-agent loop once the turn budget is spent', () => {
+ expect(
+ decideDispatch(
+ context({
+ message: message({ from: 'ag_bob', mentions: ['ag_alice'] }),
+ budget: { autoTurnsUsed: 3, tokensUsed: 0 },
+ limits: { autoTurns: 3 },
+ }),
+ ),
+ ).toEqual({ kind: 'skip', reason: 'turn_budget_exhausted' });
+ });
+
+ it('stops once the token budget is spent', () => {
+ expect(
+ decideDispatch(
+ context({
+ message: message({ from: 'ag_bob', mentions: ['ag_alice'] }),
+ budget: { autoTurnsUsed: 0, tokensUsed: 200_000 },
+ limits: { tokens: 200_000 },
+ }),
+ ),
+ ).toEqual({ kind: 'skip', reason: 'token_budget_exhausted' });
+ });
+
+ it('lets a person reset the local turn gate', () => {
+ expect(
+ decideDispatch(
+ context({
+ budget: { autoTurnsUsed: 99, tokensUsed: 0 },
+ limits: { autoTurns: 3, tokens: 10 },
+ }),
+ ),
+ ).toEqual({ kind: 'dispatch' });
+ });
+
+ it('does not let a person bypass the token gate', () => {
+ expect(
+ decideDispatch(
+ context({
+ budget: { autoTurnsUsed: 0, tokensUsed: 10 },
+ limits: { tokens: 10 },
+ }),
+ ),
+ ).toEqual({ kind: 'skip', reason: 'token_budget_exhausted' });
+ });
+
+ it('uses the current thread turn count', () => {
+ expect(
+ decideDispatch(
+ context({
+ thread: thread({ id: 'th_2', rootThreadId: 'th_1' }),
+ message: message({ from: 'ag_bob', mentions: ['ag_alice'] }),
+ budget: { autoTurnsUsed: 12, tokensUsed: 0 },
+ }),
+ ),
+ ).toEqual({ kind: 'skip', reason: 'turn_budget_exhausted' });
+ });
+
+ it('reports a disabled agent as skipped rather than unknown', () => {
+ expect(
+ decideDispatch(context({ target: agent({ enabled: false }) })),
+ ).toEqual({ kind: 'skip', reason: 'agent_disabled' });
+ });
+
+ it('reports an unresolvable target', () => {
+ expect(decideDispatch(context({ target: undefined }))).toEqual({
+ kind: 'skip',
+ reason: 'agent_unknown',
+ });
+ });
+
+ it('does not reopen a finished thread', () => {
+ expect(
+ decideDispatch(context({ thread: thread({ status: 'done' }) })),
+ ).toEqual({ kind: 'skip', reason: 'thread_done' });
+ });
+
+ it('still dispatches on a blocked thread, which is how a person unblocks it', () => {
+ expect(
+ decideDispatch(context({ thread: thread({ status: 'blocked' }) })),
+ ).toEqual({ kind: 'dispatch' });
+ });
+});
+
+describe('resolveTargets', () => {
+ it('prefers explicit mentions over the assignee', () => {
+ expect(
+ resolveTargets(
+ thread({ assigneeAgentId: 'ag_alice' }),
+ message({ mentions: ['ag_bob', 'ag_carol'] }),
+ ),
+ ).toEqual(['ag_bob', 'ag_carol']);
+ });
+
+ it('falls back to the assignee when nobody is named', () => {
+ expect(
+ resolveTargets(thread({ assigneeAgentId: 'ag_alice' }), message()),
+ ).toEqual(['ag_alice']);
+ });
+
+ it('returns nobody for an unassigned thread with no mentions', () => {
+ expect(resolveTargets(thread(), message())).toEqual([]);
+ });
+
+ it('does not fall back to the assignee for an unknown explicit mention', () => {
+ expect(
+ resolveTargets(thread({ assigneeAgentId: 'ag_alice' }), message(), true),
+ ).toEqual([]);
+ });
+});
diff --git a/packages/core/src/agents/mesh/dispatch-policy.ts b/packages/core/src/agents/mesh/dispatch-policy.ts
new file mode 100644
index 00000000000..b074b8d9c08
--- /dev/null
+++ b/packages/core/src/agents/mesh/dispatch-policy.ts
@@ -0,0 +1,173 @@
+/**
+ * @license
+ * Copyright 2026 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview Whether a new thread post books work for a given agent.
+ *
+ * Kept pure and separate from the daemon service that acts on it, because
+ * these rules are the difference between a working mesh and a token fire:
+ * every one exists to stop a specific runaway or duplicate.
+ *
+ * The scope is deliberately narrow — **book, coalesce, or refuse**. Whether a
+ * booked run can start *right now* is the dispatcher's business, because it
+ * depends on what the agent's single body happens to be doing. An earlier
+ * revision had this function return `defer` for a busy agent, which put a
+ * scheduling decision inside a rules function and gave the same situation two
+ * spellings. A run that cannot start yet is simply a queued run.
+ *
+ * Four rules mirror what Multica arrived at (`server/internal/handler/
+ * comment.go`): coalesce rather than double-book, never let an author wake
+ * itself, let an explicit mention take routing away from the assignee, and
+ * fail closed. The budget rules are ours: Multica's runs terminate on their
+ * own and a human owns the issue, whereas two mesh agents answering each other
+ * have nothing to stop them.
+ */
+
+import { isAgentEnabled, queueLimitFor } from './mesh-store.js';
+import {
+ DEFAULT_THREAD_AUTO_TURN_BUDGET,
+ DEFAULT_THREAD_TOKEN_BUDGET,
+ HUMAN_AUTHOR_ID,
+ type MeshAgent,
+ type Thread,
+ type ThreadMessage,
+} from './types.js';
+
+export type DispatchDecision =
+ /** Book a new queued run. The dispatcher decides when it starts. */
+ | { kind: 'dispatch' }
+ /**
+ * Add this message to a run the agent already has on this thread. Covers
+ * both a run that has not started and one executing this same thread —
+ * mid-run delivery is available here, so a second run would be waste.
+ */
+ | { kind: 'coalesce'; runId: string; into: 'queued' | 'running' }
+ /** Nothing will run for this target, and nothing is pending. */
+ | { kind: 'skip'; reason: SkipReason };
+
+export type SkipReason =
+ | 'self_trigger'
+ | 'agent_disabled'
+ | 'agent_unknown'
+ | 'turn_budget_exhausted'
+ | 'token_budget_exhausted'
+ | 'queue_full'
+ | 'thread_done'
+ | 'no_target';
+
+/** Local turn count plus the thread tree's root token spend. */
+export interface BudgetState {
+ autoTurnsUsed: number;
+ tokensUsed: number;
+}
+
+export interface BudgetLimits {
+ autoTurns?: number;
+ tokens?: number;
+}
+
+export interface DispatchContext {
+ thread: Thread;
+ /** The post being routed. Must already be appended to `thread.messages`. */
+ message: ThreadMessage;
+ /** The agent being considered as a target. */
+ target: MeshAgent | undefined;
+ /**
+ * The current thread's turn count and its root thread's token count. The
+ * caller resolves the root because reading another file is I/O.
+ */
+ budget: BudgetState;
+ /**
+ * Runs already waiting for this agent across every thread, excluding any on
+ * this thread (those coalesce instead of queueing).
+ */
+ agentQueuedElsewhere: number;
+ limits?: BudgetLimits;
+}
+
+/**
+ * Decides what a single (message, target) pair should do.
+ *
+ * Order is load-bearing. Identity and routing come first, so a decision never
+ * depends on run state a concurrent writer could change. Budget precedes the
+ * queue checks so an exhausted tree cannot keep folding new work into a run it
+ * should not have. Coalescing precedes the queue limit because joining an
+ * existing run adds nothing to the queue.
+ */
+export function decideDispatch(context: DispatchContext): DispatchDecision {
+ const { thread, message, target } = context;
+
+ if (!target) return { kind: 'skip', reason: 'agent_unknown' };
+ if (!isAgentEnabled(target)) {
+ return { kind: 'skip', reason: 'agent_disabled' };
+ }
+
+ // A finished thread stops consuming model time. Reopening it is a
+ // deliberate act, not something a late post should do implicitly.
+ if (thread.status === 'done') return { kind: 'skip', reason: 'thread_done' };
+
+ // An agent's own post never wakes it. Without this, a single "I'm done"
+ // message becomes an infinite self-conversation.
+ if (message.from === target.id) {
+ return { kind: 'skip', reason: 'self_trigger' };
+ }
+
+ // The loop breaker. A person posting is the signal that the conversation is
+ // wanted, and resets this thread's turn counter at the call site.
+ if (message.from !== HUMAN_AUTHOR_ID) {
+ const turnLimit =
+ context.limits?.autoTurns ?? DEFAULT_THREAD_AUTO_TURN_BUDGET;
+ if (context.budget.autoTurnsUsed >= turnLimit) {
+ return { kind: 'skip', reason: 'turn_budget_exhausted' };
+ }
+ }
+
+ // Token spend is a hard tree-wide cap, including human-authored triggers.
+ // A person can start a fresh root thread rather than silently bypass money
+ // already spent by this one.
+ const tokenLimit = context.limits?.tokens ?? DEFAULT_THREAD_TOKEN_BUDGET;
+ if (context.budget.tokensUsed >= tokenLimit) {
+ return { kind: 'skip', reason: 'token_budget_exhausted' };
+ }
+
+ // An agent has one body, so at most one run of its own can be live on this
+ // thread. Either state absorbs the message: a queued run has not been sent
+ // yet, and a running one accepts mid-turn delivery.
+ const existing = thread.runs.find(
+ (run) =>
+ run.agentId === target.id &&
+ (run.status === 'queued' || run.status === 'running'),
+ );
+ if (existing) {
+ return {
+ kind: 'coalesce',
+ runId: existing.id,
+ into: existing.status === 'running' ? 'running' : 'queued',
+ };
+ }
+
+ // Refusing at the limit is the point: silently accepting would build a
+ // backlog whose tail is stale by the time the agent reaches it.
+ if (context.agentQueuedElsewhere >= queueLimitFor(target)) {
+ return { kind: 'skip', reason: 'queue_full' };
+ }
+
+ return { kind: 'dispatch' };
+}
+
+/**
+ * The agents a post is addressed to: everyone mentioned, or the assignee when
+ * no mention token was present. The author is included here and rejected by
+ * {@link decideDispatch} so a self-trigger has a visible outcome.
+ */
+export function resolveTargets(
+ thread: Thread,
+ message: ThreadMessage,
+ hasExplicitMention = message.mentions.length > 0,
+): string[] {
+ if (hasExplicitMention) return [...message.mentions];
+ return thread.assigneeAgentId ? [thread.assigneeAgentId] : [];
+}
diff --git a/packages/core/src/agents/mesh/mentions.test.ts b/packages/core/src/agents/mesh/mentions.test.ts
new file mode 100644
index 00000000000..b3454da0413
--- /dev/null
+++ b/packages/core/src/agents/mesh/mentions.test.ts
@@ -0,0 +1,64 @@
+/**
+ * @license
+ * Copyright 2026 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, it } from 'vitest';
+import { parseMentions } from './mentions.js';
+import type { MeshAgent } from './types.js';
+
+const agents: MeshAgent[] = [
+ { id: 'ag_alice', name: 'alice', createdAt: 1 },
+ { id: 'ag_bob', name: 'Bob', createdAt: 1 },
+ { id: 'ag_ci', name: 'ci-runner', createdAt: 1 },
+];
+
+describe('parseMentions', () => {
+ it('resolves names case-insensitively and keeps first-appearance order', () => {
+ expect(parseMentions('@BOB then @alice', agents).ids).toEqual([
+ 'ag_bob',
+ 'ag_alice',
+ ]);
+ });
+
+ it('deduplicates repeated mentions of the same agent', () => {
+ expect(parseMentions('@alice @alice @alice', agents).ids).toEqual([
+ 'ag_alice',
+ ]);
+ });
+
+ it('stops at trailing punctuation', () => {
+ expect(parseMentions('ask @alice, then @Bob.', agents).ids).toEqual([
+ 'ag_alice',
+ 'ag_bob',
+ ]);
+ });
+
+ it('accepts hyphenated names', () => {
+ expect(parseMentions('ping @ci-runner please', agents).ids).toEqual([
+ 'ag_ci',
+ ]);
+ });
+
+ it('does not read an email address as a mention', () => {
+ expect(parseMentions('mail alice@example.com', agents)).toEqual({
+ ids: [],
+ unknown: [],
+ });
+ });
+
+ it('reports an unmatched token so a typo is visible', () => {
+ expect(parseMentions('@alicce can you look', agents)).toEqual({
+ ids: [],
+ unknown: ['alicce'],
+ });
+ });
+
+ it('resolves a disabled agent, leaving the decision to policy', () => {
+ const disabled: MeshAgent[] = [
+ { id: 'ag_alice', name: 'alice', createdAt: 1, enabled: false },
+ ];
+ expect(parseMentions('@alice', disabled).ids).toEqual(['ag_alice']);
+ });
+});
diff --git a/packages/core/src/agents/mesh/mentions.ts b/packages/core/src/agents/mesh/mentions.ts
new file mode 100644
index 00000000000..e049773f46b
--- /dev/null
+++ b/packages/core/src/agents/mesh/mentions.ts
@@ -0,0 +1,79 @@
+/**
+ * @license
+ * Copyright 2026 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview `@name` parsing.
+ *
+ * A mention is the routing signal for the whole mesh: it decides who is woken
+ * and, when present, suppresses the assignee's automatic wake. So the parse
+ * has to be conservative in both directions — a missed mention silently drops
+ * work, and a false one wakes an agent (and spends tokens) for a string that
+ * was never addressed to it.
+ */
+
+import { findAgentByName } from './mesh-store.js';
+import type { MeshAgent } from './types.js';
+
+/**
+ * A candidate `@token`. The character before `@` must not be a word
+ * character, which is what keeps `user@example.com` and `a@b` from reading as
+ * mentions of `example` and `b`. Trailing punctuation is left outside the
+ * capture so "ask @alice, then @bob." resolves both names.
+ */
+const MENTION_PATTERN = /(?<![\p{L}\p{N}_])@([\p{L}\p{N}][\p{L}\p{N}_-]{0,47})/gu;
+
+export interface ParsedMentions {
+ /** Agent ids, in first-appearance order, deduplicated. */
+ ids: string[];
+ /** `@tokens` that matched no agent, in first-appearance order. */
+ unknown: string[];
+}
+
+/**
+ * Resolves `@name` tokens in `text` against the workspace roster.
+ *
+ * Disabled agents still resolve. Whether a disabled agent may be *dispatched*
+ * is the policy layer's decision, and swallowing the mention here would make
+ * an addressed-but-disabled agent indistinguishable from a typo.
+ */
+export function parseMentions(
+ text: string,
+ agents: readonly MeshAgent[],
+): ParsedMentions {
+ const ids: string[] = [];
+ const unknown: string[] = [];
+ const seenIds = new Set<string>();
+ const seenUnknown = new Set<string>();
+
+ for (const match of text.matchAll(MENTION_PATTERN)) {
+ const name = match[1];
+ if (!name) continue;
+ const agent = findAgentByName(agents, name);
+ if (!agent) {
+ const lowered = name.toLowerCase();
+ if (!seenUnknown.has(lowered)) {
+ seenUnknown.add(lowered);
+ unknown.push(name);
+ }
+ continue;
+ }
+ if (seenIds.has(agent.id)) continue;
+ seenIds.add(agent.id);
+ ids.push(agent.id);
+ }
+
+ return { ids, unknown };
+}
+
+/**
+ * The exact token an agent should paste to address another agent. Handed to
+ * the model in the thread prompt so it never has to guess the spelling — the
+ * same reason Multica gives its squad leader ready-made mention markdown
+ * rather than a bare name.
+ */
+export function mentionToken(agent: MeshAgent): string {
+ return `@${agent.name}`;
+}
diff --git a/packages/core/src/agents/mesh/mesh-store.ts b/packages/core/src/agents/mesh/mesh-store.ts
new file mode 100644
index 00000000000..c27b544e54e
--- /dev/null
+++ b/packages/core/src/agents/mesh/mesh-store.ts
@@ -0,0 +1,579 @@
+/**
+ * @license
+ * Copyright 2026 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview File I/O for the agent mesh.
+ *
+ * Layout, under the per-project runtime dir (`~/.qwen/tmp/<project-hash>/`)
+ * rather than the working tree — the same reasoning the durable scheduled
+ * tasks file records: this is the user's own automation state, and thread
+ * text written by one agent is fed to another, so it must never become a
+ * committed, pulled, prompt-injection surface.
+ *
+ * mesh/agents.json — the workspace's agent identities
+ * mesh/threads/<id>.json — one file per thread
+ *
+ * Concurrency follows the team modules: an in-process `Mutex` serialises
+ * writers here, and a `proper-lockfile` lock guards writers in other
+ * processes (the daemon, a CLI session, and a teammate can all post).
+ *
+ * A file that exists but does not parse is corruption, not emptiness. Reads
+ * throw rather than returning a default, so a read-modify-write can never
+ * replace a recoverable file with a valid-but-empty one.
+ */
+
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { Mutex } from 'async-mutex';
+import lockfile from 'proper-lockfile';
+
+import { atomicWriteJSON } from '../../utils/atomicFileWrite.js';
+import { getProjectHash } from '../../utils/paths.js';
+import { Storage } from '../../config/storage.js';
+import { isNodeError } from '../../utils/errors.js';
+import {
+ DEFAULT_QUEUE_LIMIT,
+ HUMAN_AUTHOR_ID,
+ MAX_THREAD_MESSAGES,
+ MAX_THREAD_RUNS,
+ type MeshAgent,
+ type Thread,
+ type ThreadMessage,
+ type ThreadRun,
+ type ThreadRunStatus,
+ type ThreadStatus,
+} from './types.js';
+
+const MESH_DIRNAME = 'mesh';
+const AGENTS_FILENAME = 'agents.json';
+const THREADS_DIRNAME = 'threads';
+
+/** Display form used in user-facing messages and docs. */
+export const MESH_DISPLAY_PATH = `~/.qwen/tmp/<project-hash>/${MESH_DIRNAME}`;
+
+// Matches the team mailbox's settings: ten retries with jittered backoff.
+// Jitter matters because the daemon dispatcher and an agent's `thread_post`
+// contend for the same thread file, and lockstep retries starve each other
+// out of the budget.
+const LOCK_OPTIONS: lockfile.LockOptions = {
+ retries: {
+ retries: 10,
+ minTimeout: 5,
+ maxTimeout: 100,
+ factor: 2,
+ randomize: true,
+ },
+ stale: 10_000,
+};
+
+const updateMutexes = new Map<string, Mutex>();
+
+function getUpdateMutex(filePath: string): Mutex {
+ let mutex = updateMutexes.get(filePath);
+ if (!mutex) {
+ mutex = new Mutex();
+ updateMutexes.set(filePath, mutex);
+ }
+ return mutex;
+}
+
+export function getMeshDir(projectRoot: string): string {
+ return path.join(
+ Storage.getGlobalTempDir(),
+ getProjectHash(projectRoot),
+ MESH_DIRNAME,
+ );
+}
+
+export function getAgentsFilePath(projectRoot: string): string {
+ return path.join(getMeshDir(projectRoot), AGENTS_FILENAME);
+}
+
+export function getThreadsDir(projectRoot: string): string {
+ return path.join(getMeshDir(projectRoot), THREADS_DIRNAME);
+}
+
+/**
+ * Thread ids are path components, so they are generated — never taken from a
+ * caller — and validated on the way back in. `..`, separators and control
+ * characters can therefore never reach `path.join`.
+ */
+const ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+
+export function generateAgentId(): string {
+ return `ag_${randomUUID()}`;
+}
+
+export function generateThreadId(): string {
+ return `th_${randomUUID()}`;
+}
+
+export function generateMessageId(): string {
+ return `ms_${randomUUID()}`;
+}
+
+export function generateRunId(): string {
+ return `rn_${randomUUID()}`;
+}
+
+export function isValidId(value: unknown): value is string {
+ return typeof value === 'string' && ID_PATTERN.test(value);
+}
+
+export function getThreadPath(projectRoot: string, threadId: string): string {
+ if (!isValidId(threadId)) {
+ throw new Error(`Invalid thread id: ${JSON.stringify(threadId)}`);
+ }
+ return path.join(getThreadsDir(projectRoot), `${threadId}.json`);
+}
+
+// ─── Validation ─────────────────────────────────────────────
+
+function isFiniteTimestamp(value: unknown): value is number {
+ return typeof value === 'number' && Number.isFinite(value);
+}
+
+function isNonEmptyString(value: unknown): value is string {
+ return typeof value === 'string' && value.length > 0;
+}
+
+const HEX_COLOR = /^#[0-9a-f]{6}$/i;
+
+/**
+ * Names are the mention vocabulary, so the character set is deliberately
+ * narrow: whatever is legal here has to be unambiguously delimitable inside
+ * prose after an `@`.
+ */
+export const AGENT_NAME_PATTERN = /^[\p{L}\p{N}][\p{L}\p{N}_-]{0,47}$/u;
+
+export function isValidAgentName(value: unknown): value is string {
+ return typeof value === 'string' && AGENT_NAME_PATTERN.test(value);
+}
+
+function isValidAgent(value: unknown): value is MeshAgent {
+ if (typeof value !== 'object' || value === null) return false;
+ const a = value as Record<string, unknown>;
+ return (
+ isValidId(a['id']) &&
+ isValidAgentName(a['name']) &&
+ isFiniteTimestamp(a['createdAt']) &&
+ (a['description'] === undefined || typeof a['description'] === 'string') &&
+ (a['color'] === undefined ||
+ (typeof a['color'] === 'string' && HEX_COLOR.test(a['color']))) &&
+ (a['agentType'] === undefined || isNonEmptyString(a['agentType'])) &&
+ (a['model'] === undefined || isNonEmptyString(a['model'])) &&
+ (a['queueLimit'] === undefined ||
+ (typeof a['queueLimit'] === 'number' &&
+ Number.isInteger(a['queueLimit']) &&
+ a['queueLimit'] > 0)) &&
+ (a['enabled'] === undefined || typeof a['enabled'] === 'boolean') &&
+ (a['backgroundAgentId'] === undefined ||
+ isNonEmptyString(a['backgroundAgentId'])) &&
+ (a['hostSessionId'] === undefined || isNonEmptyString(a['hostSessionId']))
+ );
+}
+
+const RUN_STATUSES = new Set<ThreadRunStatus>([
+ 'queued',
+ 'running',
+ 'completed',
+ 'failed',
+ 'cancelled',
+]);
+
+const THREAD_STATUSES = new Set<ThreadStatus>([
+ 'open',
+ 'in_progress',
+ 'blocked',
+ 'in_review',
+ 'done',
+]);
+
+function isValidMessage(value: unknown): value is ThreadMessage {
+ if (typeof value !== 'object' || value === null) return false;
+ const m = value as Record<string, unknown>;
+ return (
+ isValidId(m['id']) &&
+ isNonEmptyString(m['from']) &&
+ typeof m['text'] === 'string' &&
+ Array.isArray(m['mentions']) &&
+ m['mentions'].every((id) => isValidId(id)) &&
+ isFiniteTimestamp(m['at'])
+ );
+}
+
+function isValidRun(value: unknown): value is ThreadRun {
+ if (typeof value !== 'object' || value === null) return false;
+ const r = value as Record<string, unknown>;
+ return (
+ isValidId(r['id']) &&
+ isValidId(r['agentId']) &&
+ RUN_STATUSES.has(r['status'] as ThreadRunStatus) &&
+ typeof r['attempts'] === 'number' &&
+ Number.isInteger(r['attempts']) &&
+ r['attempts'] >= 0 &&
+ Array.isArray(r['triggerMessageIds']) &&
+ r['triggerMessageIds'].every((id) => isValidId(id)) &&
+ isFiniteTimestamp(r['queuedAt']) &&
+ (r['sessionId'] === undefined || isNonEmptyString(r['sessionId'])) &&
+ (r['startedAt'] === undefined || isFiniteTimestamp(r['startedAt'])) &&
+ (r['endedAt'] === undefined || isFiniteTimestamp(r['endedAt'])) &&
+ (r['error'] === undefined || typeof r['error'] === 'string')
+ );
+}
+
+function isValidThread(value: unknown): value is Thread {
+ if (typeof value !== 'object' || value === null) return false;
+ const t = value as Record<string, unknown>;
+ return (
+ isValidId(t['id']) &&
+ typeof t['title'] === 'string' &&
+ typeof t['body'] === 'string' &&
+ THREAD_STATUSES.has(t['status'] as ThreadStatus) &&
+ isFiniteTimestamp(t['createdAt']) &&
+ isNonEmptyString(t['createdBy']) &&
+ Array.isArray(t['messages']) &&
+ t['messages'].every(isValidMessage) &&
+ Array.isArray(t['runs']) &&
+ t['runs'].every(isValidRun) &&
+ typeof t['autoTurnsUsed'] === 'number' &&
+ Number.isInteger(t['autoTurnsUsed']) &&
+ t['autoTurnsUsed'] >= 0 &&
+ typeof t['tokensUsed'] === 'number' &&
+ Number.isInteger(t['tokensUsed']) &&
+ t['tokensUsed'] >= 0 &&
+ isValidId(t['rootThreadId']) &&
+ (t['parentThreadId'] === undefined || isValidId(t['parentThreadId'])) &&
+ (t['assigneeAgentId'] === undefined || isValidId(t['assigneeAgentId']))
+ );
+}
+
+// ─── Agents ─────────────────────────────────────────────────
+
+async function readJsonFile(filePath: string): Promise<unknown | undefined> {
+ let raw: string;
+ try {
+ raw = await fs.readFile(filePath, 'utf-8');
+ } catch (err) {
+ if (isNodeError(err) && err.code === 'ENOENT') return undefined;
+ throw err;
+ }
+ try {
+ return JSON.parse(raw);
+ } catch {
+ throw new Error(
+ `Malformed JSON in ${filePath} — fix or delete the file; refusing to treat it as empty.`,
+ );
+ }
+}
+
+export async function readMeshAgents(
+ projectRoot: string,
+): Promise<MeshAgent[]> {
+ const filePath = getAgentsFilePath(projectRoot);
+ const parsed = await readJsonFile(filePath);
+ if (parsed === undefined) return [];
+ if (!Array.isArray(parsed)) {
+ throw new Error(
+ `Expected a JSON array in ${filePath} — fix or delete the file; refusing to treat it as no agents.`,
+ );
+ }
+ // One malformed entry must not hide the rest: an unreadable agent is
+ // dropped from the roster, exactly as the board listing skips a bad record,
+ // while a corrupt *file* still throws above.
+ return parsed.filter(isValidAgent);
+}
+
+async function withFileLock<T>(
+ filePath: string,
+ fn: () => Promise<T>,
+): Promise<T> {
+ await fs.mkdir(path.dirname(filePath), { recursive: true });
+ // proper-lockfile needs the target to exist before it can lock it.
+ try {
+ await fs.access(filePath);
+ } catch {
+ await atomicWriteJSON(
+ filePath,
+ filePath.endsWith(AGENTS_FILENAME) ? [] : {},
+ {
+ noFollow: true,
+ },
+ );
+ }
+ const release = await lockfile.lock(filePath, LOCK_OPTIONS);
+ try {
+ return await fn();
+ } finally {
+ await release();
+ }
+}
+
+export async function updateMeshAgents(
+ projectRoot: string,
+ mutate: (agents: MeshAgent[]) => MeshAgent[],
+): Promise<MeshAgent[]> {
+ const filePath = getAgentsFilePath(projectRoot);
+ return getUpdateMutex(filePath).runExclusive(async () =>
+ withFileLock(filePath, async () => {
+ const agents = await readMeshAgents(projectRoot);
+ const next = mutate(agents);
+ if (next !== agents) {
+ await atomicWriteJSON(filePath, next, { noFollow: true });
+ }
+ return next;
+ }),
+ );
+}
+
+/** Case-insensitive: mention routing must not depend on capitalisation. */
+export function findAgentByName(
+ agents: readonly MeshAgent[],
+ name: string,
+): MeshAgent | undefined {
+ const lowered = name.toLowerCase();
+ return agents.find((agent) => agent.name.toLowerCase() === lowered);
+}
+
+export function isAgentEnabled(agent: MeshAgent): boolean {
+ return agent.enabled !== false;
+}
+
+export function queueLimitFor(agent: MeshAgent): number {
+ return agent.queueLimit ?? DEFAULT_QUEUE_LIMIT;
+}
+
+// ─── Threads ────────────────────────────────────────────────
+
+export async function listThreadIds(projectRoot: string): Promise<string[]> {
+ const dir = getThreadsDir(projectRoot);
+ let entries: string[];
+ try {
+ entries = await fs.readdir(dir);
+ } catch (err) {
+ if (isNodeError(err) && err.code === 'ENOENT') return [];
+ throw err;
+ }
+ return entries
+ .filter((name) => name.endsWith('.json'))
+ .map((name) => name.slice(0, -'.json'.length))
+ .filter(isValidId);
+}
+
+export async function readThread(
+ projectRoot: string,
+ threadId: string,
+): Promise<Thread | undefined> {
+ const parsed = await readJsonFile(getThreadPath(projectRoot, threadId));
+ if (parsed === undefined) return undefined;
+ if (!isValidThread(parsed)) {
+ throw new Error(
+ `Malformed thread record in ${getThreadPath(projectRoot, threadId)} — fix or delete the file.`,
+ );
+ }
+ // The id in the file wins over the filename only if they agree; a mismatch
+ // means the file was moved or hand-edited, and silently trusting either
+ // one would let a thread answer to two ids.
+ if (parsed.id !== threadId) {
+ throw new Error(
+ `Thread id mismatch: file ${threadId}.json contains id ${parsed.id}.`,
+ );
+ }
+ return parsed;
+}
+
+/** Reads every thread, skipping (and reporting) ones that fail validation. */
+export async function listThreads(
+ projectRoot: string,
+): Promise<{ threads: Thread[]; unreadable: string[] }> {
+ const ids = await listThreadIds(projectRoot);
+ const threads: Thread[] = [];
+ const unreadable: string[] = [];
+ for (const id of ids) {
+ try {
+ const thread = await readThread(projectRoot, id);
+ if (thread) threads.push(thread);
+ } catch {
+ unreadable.push(id);
+ }
+ }
+ threads.sort((a, b) => b.createdAt - a.createdAt || a.id.localeCompare(b.id));
+ return { threads, unreadable };
+}
+
+export async function writeThread(
+ projectRoot: string,
+ thread: Thread,
+): Promise<void> {
+ const filePath = getThreadPath(projectRoot, thread.id);
+ await fs.mkdir(path.dirname(filePath), { recursive: true });
+ await atomicWriteJSON(filePath, trimThread(thread), { noFollow: true });
+}
+
+/**
+ * Drops the oldest terminal history past the retention bounds. Messages and
+ * runs still needed by queued/running work are retained even if that exceeds a
+ * bound; retention must not break a live run's durable trigger references.
+ */
+function trimThread(thread: Thread): Thread {
+ if (
+ thread.messages.length <= MAX_THREAD_MESSAGES &&
+ thread.runs.length <= MAX_THREAD_RUNS
+ ) {
+ return thread;
+ }
+ const firstRetainedMessage = Math.max(
+ 0,
+ thread.messages.length - MAX_THREAD_MESSAGES,
+ );
+ const firstRetainedRun = Math.max(0, thread.runs.length - MAX_THREAD_RUNS);
+ const retainedRuns = thread.runs.filter(
+ (run, index) =>
+ index >= firstRetainedRun ||
+ run.status === 'queued' ||
+ run.status === 'running',
+ );
+ const referencedMessageIds = new Set(
+ retainedRuns.flatMap((run) => run.triggerMessageIds),
+ );
+ return {
+ ...thread,
+ messages: thread.messages.filter(
+ (message, index) =>
+ index >= firstRetainedMessage || referencedMessageIds.has(message.id),
+ ),
+ runs: retainedRuns,
+ };
+}
+
+export async function updateThread(
+ projectRoot: string,
+ threadId: string,
+ mutate: (thread: Thread) => Thread,
+): Promise<Thread> {
+ const filePath = getThreadPath(projectRoot, threadId);
+ return getUpdateMutex(filePath).runExclusive(async () =>
+ withFileLock(filePath, async () => {
+ const thread = await readThread(projectRoot, threadId);
+ if (!thread) throw new Error(`No thread with id "${threadId}".`);
+ const next = mutate(thread);
+ if (next !== thread) await writeThread(projectRoot, next);
+ return next;
+ }),
+ );
+}
+
+export async function createThread(
+ projectRoot: string,
+ input: {
+ title: string;
+ body?: string;
+ createdBy?: string;
+ assigneeAgentId?: string;
+ /** Set when an agent splits work out of a thread it is already on. */
+ parentThreadId?: string;
+ },
+): Promise<Thread> {
+ const id = generateThreadId();
+ // The root is inherited, not recomputed, so a chain of sub-threads keeps
+ // spending one budget however deep it goes. Resolving it by walking parents
+ // at spend time would make the budget depend on files that may be missing.
+ let rootThreadId = id;
+ let autoTurnsUsed = 0;
+ if (input.parentThreadId) {
+ const parent = await readThread(projectRoot, input.parentThreadId);
+ if (!parent) {
+ throw new Error(`No parent thread with id "${input.parentThreadId}".`);
+ }
+ rootThreadId = parent.rootThreadId;
+ autoTurnsUsed = parent.autoTurnsUsed;
+ if (rootThreadId !== parent.id) {
+ const root = await readThread(projectRoot, rootThreadId);
+ if (!root || root.rootThreadId !== root.id) {
+ throw new Error(`No valid root thread with id "${rootThreadId}".`);
+ }
+ }
+ }
+ const thread: Thread = {
+ id,
+ title: input.title,
+ body: input.body ?? '',
+ status: 'open',
+ createdAt: Date.now(),
+ createdBy: input.createdBy ?? HUMAN_AUTHOR_ID,
+ rootThreadId,
+ messages: [],
+ runs: [],
+ autoTurnsUsed,
+ tokensUsed: 0,
+ ...(input.parentThreadId ? { parentThreadId: input.parentThreadId } : {}),
+ ...(input.assigneeAgentId
+ ? { assigneeAgentId: input.assigneeAgentId }
+ : {}),
+ };
+ await writeThread(projectRoot, thread);
+ return thread;
+}
+
+/**
+ * Reads the record a thread's budget is spent from. A root thread is its own.
+ *
+ * Fails closed when the root is absent or invalid. A child carries less token
+ * spend than the tree, so falling back to it would weaken the budget gate.
+ */
+export async function readTokenBudgetThread(
+ projectRoot: string,
+ thread: Thread,
+): Promise<Thread> {
+ if (thread.rootThreadId === thread.id) return thread;
+ const root = await readThread(projectRoot, thread.rootThreadId);
+ if (!root || root.rootThreadId !== root.id) {
+ throw new Error(
+ `No valid root thread with id "${thread.rootThreadId}" for "${thread.id}".`,
+ );
+ }
+ return root;
+}
+
+export async function deleteThread(
+ projectRoot: string,
+ threadId: string,
+): Promise<boolean> {
+ const thread = await readThread(projectRoot, threadId);
+ if (!thread) return false;
+ if (
+ thread.runs.some(
+ (run) => run.status === 'queued' || run.status === 'running',
+ )
+ ) {
+ throw new Error(`Cannot delete thread "${threadId}" with active runs.`);
+ }
+ const { threads, unreadable } = await listThreads(projectRoot);
+ if (unreadable.length > 0) {
+ throw new Error(
+ `Cannot safely delete thread "${threadId}" while thread records are unreadable.`,
+ );
+ }
+ if (
+ threads.some(
+ (candidate) =>
+ candidate.id !== threadId &&
+ (candidate.parentThreadId === threadId ||
+ (thread.rootThreadId === thread.id &&
+ candidate.rootThreadId === thread.id)),
+ )
+ ) {
+ throw new Error(`Cannot delete thread "${threadId}" with sub-threads.`);
+ }
+ try {
+ await fs.unlink(getThreadPath(projectRoot, threadId));
+ return true;
+ } catch (err) {
+ if (isNodeError(err) && err.code === 'ENOENT') return false;
+ throw err;
+ }
+}
diff --git a/packages/core/src/agents/mesh/thread-actions.test.ts b/packages/core/src/agents/mesh/thread-actions.test.ts
new file mode 100644
index 00000000000..c76e9c19287
--- /dev/null
+++ b/packages/core/src/agents/mesh/thread-actions.test.ts
@@ -0,0 +1,260 @@
+/**
+ * @license
+ * Copyright 2026 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as fs from 'node:fs/promises';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { Storage } from '../../config/storage.js';
+import {
+ createThread,
+ deleteThread,
+ readThread,
+ writeThread,
+} from './mesh-store.js';
+import { countQueuedElsewhere, postMessage } from './thread-actions.js';
+import {
+ HUMAN_AUTHOR_ID,
+ type MeshAgent,
+ type Thread,
+ type ThreadRun,
+} from './types.js';
+
+const PROJECT_ROOT = '/mesh-test-project';
+const ALICE: MeshAgent = { id: 'ag_alice', name: 'alice', createdAt: 1 };
+const BOB: MeshAgent = { id: 'ag_bob', name: 'bob', createdAt: 1 };
+
+function run(overrides: Partial<ThreadRun> = {}): ThreadRun {
+ return {
+ id: 'rn_1',
+ agentId: ALICE.id,
+ status: 'queued',
+ triggerMessageIds: ['ms_0'],
+ attempts: 0,
+ queuedAt: 2,
+ ...overrides,
+ };
+}
+
+function thread(overrides: Partial<Thread> = {}): Thread {
+ return {
+ id: 'th_root',
+ title: 'Investigate',
+ body: '',
+ status: 'open',
+ createdAt: 1,
+ createdBy: HUMAN_AUTHOR_ID,
+ rootThreadId: 'th_root',
+ messages: [],
+ runs: [],
+ autoTurnsUsed: 0,
+ tokensUsed: 0,
+ ...overrides,
+ };
+}
+
+describe('mesh thread actions', () => {
+ let runtimeDir: string;
+
+ beforeEach(async () => {
+ runtimeDir = await fs.mkdtemp(path.join(os.tmpdir(), 'mesh-test-'));
+ Storage.setRuntimeBaseDir(runtimeDir);
+ });
+
+ afterEach(async () => {
+ Storage.setRuntimeBaseDir(null);
+ await fs.rm(runtimeDir, { recursive: true, force: true });
+ });
+
+ it('round-trips the blocked status', async () => {
+ await writeThread(PROJECT_ROOT, thread({ status: 'blocked' }));
+ await expect(readThread(PROJECT_ROOT, 'th_root')).resolves.toMatchObject({
+ status: 'blocked',
+ });
+ });
+
+ it('rejects negative budget counters', async () => {
+ await writeThread(PROJECT_ROOT, thread({ autoTurnsUsed: -1 }));
+ await expect(readThread(PROJECT_ROOT, 'th_root')).rejects.toThrow(
+ /Malformed thread record/,
+ );
+ });
+
+ it('retains active runs and their trigger messages past history bounds', async () => {
+ const messages = Array.from({ length: 501 }, (_, index) => ({
+ id: `ms_${index}`,
+ from: HUMAN_AUTHOR_ID,
+ text: `message ${index}`,
+ mentions: [],
+ at: index,
+ }));
+ const runs = [
+ run({ triggerMessageIds: ['ms_0'] }),
+ ...Array.from({ length: 200 }, (_, index) =>
+ run({
+ id: `rn_${index + 2}`,
+ status: 'completed',
+ triggerMessageIds: [`ms_${index + 1}`],
+ }),
+ ),
+ ];
+ await writeThread(PROJECT_ROOT, thread({ messages, runs }));
+
+ const stored = await readThread(PROJECT_ROOT, 'th_root');
+ expect(stored?.messages[0]?.id).toBe('ms_0');
+ expect(stored?.runs[0]?.id).toBe('rn_1');
+ expect(stored?.messages).toHaveLength(501);
+ expect(stored?.runs).toHaveLength(201);
+ });
+
+ it('reports an unknown mention without waking the assignee', async () => {
+ await writeThread(PROJECT_ROOT, thread({ assigneeAgentId: ALICE.id }));
+
+ const result = await postMessage(
+ PROJECT_ROOT,
+ 'th_root',
+ { from: HUMAN_AUTHOR_ID, text: '@alicce please check' },
+ { agents: [ALICE] },
+ );
+
+ expect(result.outcomes).toEqual([
+ {
+ agentName: 'alicce',
+ decision: { kind: 'skip', reason: 'agent_unknown' },
+ },
+ ]);
+ expect(result.dispatched).toEqual([]);
+ });
+
+ it('reports a post with no mention or assignee', async () => {
+ await writeThread(PROJECT_ROOT, thread());
+
+ const result = await postMessage(PROJECT_ROOT, 'th_root', {
+ from: HUMAN_AUTHOR_ID,
+ text: 'anyone?',
+ });
+
+ expect(result.outcomes).toEqual([
+ { decision: { kind: 'skip', reason: 'no_target' } },
+ ]);
+ });
+
+ it('resets only the thread where a person replies', async () => {
+ await writeThread(PROJECT_ROOT, thread({ autoTurnsUsed: 9 }));
+ await writeThread(
+ PROJECT_ROOT,
+ thread({
+ id: 'th_child',
+ rootThreadId: 'th_root',
+ parentThreadId: 'th_root',
+ status: 'blocked',
+ assigneeAgentId: ALICE.id,
+ autoTurnsUsed: 4,
+ }),
+ );
+
+ const result = await postMessage(
+ PROJECT_ROOT,
+ 'th_child',
+ { from: HUMAN_AUTHOR_ID, text: 'here is the answer' },
+ { agents: [ALICE] },
+ );
+
+ expect(result.thread).toMatchObject({
+ status: 'in_progress',
+ autoTurnsUsed: 0,
+ });
+ await expect(readThread(PROJECT_ROOT, 'th_root')).resolves.toMatchObject({
+ autoTurnsUsed: 9,
+ });
+ });
+
+ it('charges agent delivery into a running run against the turn gate', async () => {
+ await writeThread(
+ PROJECT_ROOT,
+ thread({ runs: [run({ status: 'running' })] }),
+ );
+
+ const first = await postMessage(
+ PROJECT_ROOT,
+ 'th_root',
+ { from: BOB.id, text: '@alice first' },
+ { agents: [ALICE, BOB], limits: { autoTurns: 1 } },
+ );
+ expect(first.outcomes[0]?.decision).toMatchObject({
+ kind: 'coalesce',
+ into: 'running',
+ });
+ expect(first.thread.autoTurnsUsed).toBe(1);
+
+ const second = await postMessage(
+ PROJECT_ROOT,
+ 'th_root',
+ { from: BOB.id, text: '@alice again' },
+ { agents: [ALICE, BOB], limits: { autoTurns: 1 } },
+ );
+ expect(second.outcomes[0]?.decision).toEqual({
+ kind: 'skip',
+ reason: 'turn_budget_exhausted',
+ });
+ });
+
+ it('counts only pending runs against the queue limit', () => {
+ expect(
+ countQueuedElsewhere(
+ [thread({ runs: [run(), run({ id: 'rn_2', status: 'running' })] })],
+ ALICE.id,
+ ),
+ ).toBe(1);
+ });
+
+ it('fails closed when a child root is missing', async () => {
+ await writeThread(
+ PROJECT_ROOT,
+ thread({ id: 'th_child', rootThreadId: 'th_missing' }),
+ );
+
+ await expect(
+ postMessage(
+ PROJECT_ROOT,
+ 'th_child',
+ { from: BOB.id, text: '@alice check' },
+ { agents: [ALICE, BOB] },
+ ),
+ ).rejects.toThrow(/No valid root thread/);
+ });
+
+ it('inherits the parent turn count without minting a fresh allowance', async () => {
+ await writeThread(PROJECT_ROOT, thread({ autoTurnsUsed: 7 }));
+
+ const child = await createThread(PROJECT_ROOT, {
+ title: 'Child',
+ parentThreadId: 'th_root',
+ });
+
+ expect(child).toMatchObject({
+ rootThreadId: 'th_root',
+ autoTurnsUsed: 7,
+ });
+ });
+
+ it('refuses to delete a root that still owns sub-threads', async () => {
+ await writeThread(PROJECT_ROOT, thread());
+ await writeThread(
+ PROJECT_ROOT,
+ thread({
+ id: 'th_child',
+ rootThreadId: 'th_root',
+ parentThreadId: 'th_root',
+ }),
+ );
+
+ await expect(deleteThread(PROJECT_ROOT, 'th_root')).rejects.toThrow(
+ /with sub-threads/,
+ );
+ });
+});
diff --git a/packages/core/src/agents/mesh/thread-actions.ts b/packages/core/src/agents/mesh/thread-actions.ts
new file mode 100644
index 00000000000..f7efbda50ad
--- /dev/null
+++ b/packages/core/src/agents/mesh/thread-actions.ts
@@ -0,0 +1,327 @@
+/**
+ * @license
+ * Copyright 2026 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview The transactional heart of the mesh: posting to a thread and
+ * booking the runs that post implies.
+ *
+ * Appending the message and deciding who it wakes happen under one thread
+ * lock. Splitting them would let two concurrent posts each observe "no queued
+ * run for Alice" and book two — the same duplicate-dispatch race the Agent
+ * Team lifecycle audit found in leader assignment (#10207).
+ *
+ * What this module does NOT do is start anything. It returns the bookings and
+ * leaves waking a session to the daemon, so the rules stay testable without a
+ * daemon and a tool call inside an agent turn cannot block on session I/O.
+ */
+
+import {
+ generateMessageId,
+ generateRunId,
+ readTokenBudgetThread,
+ readMeshAgents,
+ readThread,
+ updateThread,
+} from './mesh-store.js';
+import { parseMentions } from './mentions.js';
+import {
+ decideDispatch,
+ resolveTargets,
+ type BudgetLimits,
+ type DispatchDecision,
+} from './dispatch-policy.js';
+import {
+ HUMAN_AUTHOR_ID,
+ type MeshAgent,
+ type Thread,
+ type ThreadMessage,
+ type ThreadRun,
+} from './types.js';
+
+export interface PostMessageInput {
+ /** {@link HUMAN_AUTHOR_ID} or the posting agent's id. */
+ from: string;
+ text: string;
+}
+
+/** One target's outcome, kept for the caller to act on and for the UI. */
+export interface TargetOutcome {
+ agentId?: string;
+ agentName?: string;
+ decision: DispatchDecision;
+ /** Present when the decision created or extended a run. */
+ runId?: string;
+}
+
+export interface PostMessageResult {
+ thread: Thread;
+ message: ThreadMessage;
+ outcomes: TargetOutcome[];
+ /** `@tokens` that matched no agent — surfaced so a typo is visible. */
+ unknownMentions: string[];
+ /** Runs newly booked by this post, for the dispatcher to start. */
+ dispatched: ThreadRun[];
+}
+
+/**
+ * Counts the runs already waiting for an agent on OTHER threads.
+ *
+ * Best effort by construction: it reads sibling threads without holding their
+ * locks, so a run booked elsewhere in the same instant is not counted. Losing
+ * that race admits one run past the queue limit, which is why the limit is a
+ * backlog bound rather than a safety property — a stricter reading would need
+ * a workspace-wide lock on every post. The dispatcher is the second line of
+ * defence, and it is the one that must never start a second body for an agent
+ * that already has one.
+ */
+export function countQueuedElsewhere(
+ threads: readonly Thread[],
+ agentId: string,
+): number {
+ let count = 0;
+ for (const thread of threads) {
+ for (const run of thread.runs) {
+ if (run.agentId === agentId && run.status === 'queued') {
+ count += 1;
+ }
+ }
+ }
+ return count;
+}
+
+/**
+ * Appends a post and books the runs it implies.
+ *
+ * @param otherThreads Threads other than this one, for the concurrency count.
+ * The caller supplies them so this stays a pure-ish function over a
+ * snapshot the caller controls.
+ */
+export async function postMessage(
+ projectRoot: string,
+ threadId: string,
+ input: PostMessageInput,
+ options: {
+ agents?: readonly MeshAgent[];
+ /** Threads other than this one, for the queue count. */
+ otherThreads?: readonly Thread[];
+ limits?: BudgetLimits;
+ now?: number;
+ } = {},
+): Promise<PostMessageResult> {
+ const agents = options.agents ?? (await readMeshAgents(projectRoot));
+ const otherThreads = options.otherThreads ?? [];
+ const now = options.now ?? Date.now();
+
+ const parsed = parseMentions(input.text, agents);
+
+ const message: ThreadMessage = {
+ id: generateMessageId(),
+ from: input.from,
+ text: input.text,
+ mentions: parsed.ids,
+ at: now,
+ };
+
+ const outcomes: TargetOutcome[] = [];
+ const dispatched: ThreadRun[] = [];
+
+ // Only token spend lives on the root. Read it before taking the child lock
+ // to avoid lock inversion; a root post uses the locked record below.
+ const existing = await readThread(projectRoot, threadId);
+ if (!existing) throw new Error(`No thread with id "${threadId}".`);
+ const budgetRecord = await readTokenBudgetThread(projectRoot, existing);
+ const budgetSnapshot = {
+ autoTurnsUsed: 0,
+ tokensUsed: budgetRecord.tokensUsed,
+ };
+
+ const thread = await updateThread(projectRoot, threadId, (current) => {
+ outcomes.length = 0;
+ dispatched.length = 0;
+
+ // A human post is the signal that the conversation is wanted, so it
+ // clears the turn counter. Tokens are never cleared — see Thread.tokensUsed.
+ const autoTurnsUsed =
+ input.from === HUMAN_AUTHOR_ID ? 0 : current.autoTurnsUsed;
+
+ let next: Thread = {
+ ...current,
+ messages: [...current.messages, message],
+ autoTurnsUsed,
+ };
+
+ budgetSnapshot.autoTurnsUsed = next.autoTurnsUsed;
+ budgetSnapshot.tokensUsed =
+ current.rootThreadId === current.id
+ ? current.tokensUsed
+ : budgetRecord.tokensUsed;
+
+ for (const name of parsed.unknown) {
+ outcomes.push({
+ agentName: name,
+ decision: { kind: 'skip', reason: 'agent_unknown' },
+ });
+ }
+
+ const hasExplicitMention =
+ parsed.ids.length > 0 || parsed.unknown.length > 0;
+ const targetIds = resolveTargets(next, message, hasExplicitMention);
+ if (targetIds.length === 0 && !hasExplicitMention) {
+ outcomes.push({ decision: { kind: 'skip', reason: 'no_target' } });
+ }
+
+ for (const agentId of targetIds) {
+ const target = agents.find((candidate) => candidate.id === agentId);
+ const decision = decideDispatch({
+ thread: next,
+ message,
+ target,
+ budget: {
+ autoTurnsUsed: budgetSnapshot.autoTurnsUsed,
+ tokensUsed: budgetSnapshot.tokensUsed,
+ },
+ agentQueuedElsewhere: countQueuedElsewhere(otherThreads, agentId),
+ ...(options.limits ? { limits: options.limits } : {}),
+ });
+
+ if (decision.kind === 'coalesce') {
+ const chargeTurn =
+ input.from !== HUMAN_AUTHOR_ID && decision.into === 'running';
+ next = {
+ ...next,
+ runs: next.runs.map((run) =>
+ run.id === decision.runId
+ ? {
+ ...run,
+ triggerMessageIds: [...run.triggerMessageIds, message.id],
+ }
+ : run,
+ ),
+ autoTurnsUsed: next.autoTurnsUsed + (chargeTurn ? 1 : 0),
+ status:
+ next.status === 'open' ||
+ (input.from === HUMAN_AUTHOR_ID &&
+ (next.status === 'blocked' || next.status === 'in_review'))
+ ? 'in_progress'
+ : next.status,
+ };
+ if (chargeTurn) budgetSnapshot.autoTurnsUsed += 1;
+ outcomes.push({
+ agentId,
+ agentName: target?.name,
+ decision,
+ runId: decision.runId,
+ });
+ continue;
+ }
+
+ if (decision.kind === 'dispatch') {
+ const run: ThreadRun = {
+ id: generateRunId(),
+ agentId,
+ status: 'queued',
+ triggerMessageIds: [message.id],
+ queuedAt: now,
+ attempts: 0,
+ };
+ // Booked, not finished: charging at booking time makes the budget a
+ // cap on attempts rather than on successes, so a pair of agents that
+ // keep failing still runs out.
+ if (input.from !== HUMAN_AUTHOR_ID) {
+ budgetSnapshot.autoTurnsUsed += 1;
+ }
+ next = {
+ ...next,
+ runs: [...next.runs, run],
+ autoTurnsUsed:
+ input.from === HUMAN_AUTHOR_ID
+ ? next.autoTurnsUsed
+ : next.autoTurnsUsed + 1,
+ status:
+ next.status === 'open' ||
+ (input.from === HUMAN_AUTHOR_ID &&
+ (next.status === 'blocked' || next.status === 'in_review'))
+ ? 'in_progress'
+ : next.status,
+ };
+ dispatched.push(run);
+ outcomes.push({
+ agentId,
+ agentName: target?.name,
+ decision,
+ runId: run.id,
+ });
+ continue;
+ }
+
+ outcomes.push({ agentId, agentName: target?.name, decision });
+ }
+
+ return next;
+ });
+
+ return {
+ thread,
+ message,
+ outcomes,
+ unknownMentions: parsed.unknown,
+ dispatched,
+ };
+}
+
+/**
+ * Marks a booked run as started, binds it to the session doing the work, and
+ * counts the attempt. A revived run passes through here again, so `attempts`
+ * is what makes the second failure terminal.
+ */
+export async function startRun(
+ projectRoot: string,
+ threadId: string,
+ runId: string,
+ sessionId: string,
+ now = Date.now(),
+): Promise<Thread> {
+ return updateThread(projectRoot, threadId, (thread) => ({
+ ...thread,
+ runs: thread.runs.map((run) =>
+ run.id === runId && run.status === 'queued'
+ ? {
+ ...run,
+ status: 'running',
+ sessionId,
+ startedAt: now,
+ attempts: run.attempts + 1,
+ }
+ : run,
+ ),
+ }));
+}
+
+/**
+ * Records a terminal outcome. A run that already reached a terminal state is
+ * left alone so a late completion cannot overwrite a cancellation.
+ */
+export async function finishRun(
+ projectRoot: string,
+ threadId: string,
+ runId: string,
+ outcome: { status: 'completed' | 'failed' | 'cancelled'; error?: string },
+ now = Date.now(),
+): Promise<Thread> {
+ return updateThread(projectRoot, threadId, (thread) => ({
+ ...thread,
+ runs: thread.runs.map((run) =>
+ run.id === runId && (run.status === 'queued' || run.status === 'running')
+ ? {
+ ...run,
+ status: outcome.status,
+ endedAt: now,
+ ...(outcome.error ? { error: outcome.error } : {}),
+ }
+ : run,
+ ),
+ }));
+}
diff --git a/packages/core/src/agents/mesh/types.ts b/packages/core/src/agents/mesh/types.ts
new file mode 100644
index 00000000000..65f374409b0
--- /dev/null
+++ b/packages/core/src/agents/mesh/types.ts
@@ -0,0 +1,214 @@
+/**
+ * @license
+ * Copyright 2026 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview Types for the agent mesh — durable agent identities that
+ * collaborate on a shared thread.
+ *
+ * The distinction from Agent Team: a teammate is a live in-process loop that
+ * receives messages at a tool-round boundary and dies with its leader. A mesh
+ * agent is an identity whose work happens in a durable background agent that
+ * is continued when addressed, so the conversation survives the process, is
+ * visible to every participant, and can be replayed.
+ */
+
+/** Author id used for messages a person wrote. Never a valid agent id. */
+export const HUMAN_AUTHOR_ID = 'user';
+
+/**
+ * A durable agent identity, scoped to one workspace.
+ *
+ * The persona (system prompt, tools, MCP servers, skills) is NOT duplicated
+ * here: `agentType` names an existing agent definition and that definition
+ * stays the single source of truth, so editing it changes every mesh agent
+ * built on it. What lives here is identity and policy — who this agent is in
+ * the workspace, and the limits it runs under.
+ */
+export interface MeshAgent {
+ /** Stable id. Never reused, never derived from the name. */
+ id: string;
+ /**
+ * Display name and the token people and agents type after `@`. Unique
+ * within a workspace, case-insensitively — mention routing has to be
+ * unambiguous, and two agents named `Review` and `review` would make it a
+ * coin flip.
+ */
+ name: string;
+ /** Free-text description. Display only; never enters a prompt. */
+ description?: string;
+ /** Hex colour (`#rrggbb`) for UI attribution. */
+ color?: string;
+ /** Name of the agent definition supplying this agent's persona. */
+ agentType?: string;
+ /** Model override; absent inherits the workspace default. */
+ model?: string;
+ /**
+ * How many runs may wait for this agent across all threads before further
+ * mentions are refused. Absent means {@link DEFAULT_QUEUE_LIMIT}.
+ *
+ * There is deliberately no concurrency setting: an agent is one long-lived
+ * body working one thread at a time, so the only meaningful bound is how
+ * much work may pile up behind it. Refusing at the limit makes the agent's
+ * real throughput visible instead of accruing a backlog nobody reaches.
+ */
+ queueLimit?: number;
+ /**
+ * Absent or `true` = can be addressed. `false` keeps the identity and its
+ * history but stops it taking new work, matching how a disabled scheduled
+ * task stays on disk.
+ */
+ enabled?: boolean;
+ createdAt: number;
+ /**
+ * The background agent carrying this identity's long-lived body, once it has
+ * been started. Its transcript is this agent's memory across every thread.
+ * Absent until the first dispatch.
+ */
+ backgroundAgentId?: string;
+ /**
+ * Session owning that background agent. Revival is scoped to a parent
+ * session, so the mesh keeps one hidden host session per workspace and
+ * records it here; losing it would strand the agent's memory.
+ */
+ hostSessionId?: string;
+}
+
+/**
+ * Lifecycle of a unit of work.
+ *
+ * `blocked` is how an agent asks a person for something: it posts the question,
+ * sets this, and ends its run rather than holding its body and budget open
+ * while it waits. `done` is deliberately a human's call — an agent may push a
+ * thread to `in_review`, never past it.
+ */
+export type ThreadStatus =
+ | 'open'
+ | 'in_progress'
+ | 'blocked'
+ | 'in_review'
+ | 'done';
+
+/**
+ * One post on a thread. Append-only: an agent's turn is evidence, and
+ * rewriting it would let a later run change what an earlier one is recorded
+ * as having said.
+ */
+export interface ThreadMessage {
+ id: string;
+ /** {@link HUMAN_AUTHOR_ID} or the id of the agent that posted. */
+ from: string;
+ text: string;
+ /** Agent ids resolved from `@name` tokens at post time, in order. */
+ mentions: string[];
+ at: number;
+}
+
+export type ThreadRunStatus =
+ | 'queued'
+ | 'running'
+ | 'completed'
+ | 'failed'
+ | 'cancelled';
+
+/**
+ * One agent turn against one thread.
+ *
+ * `sessionId` links this run to the background agent transcript. Because one
+ * mesh agent works across threads, a run is a slice of that transcript rather
+ * than the whole log; the dispatcher will record the slice boundaries.
+ */
+export interface ThreadRun {
+ id: string;
+ agentId: string;
+ /** Bound background-agent session. Absent until the dispatcher starts it. */
+ sessionId?: string;
+ status: ThreadRunStatus;
+ /**
+ * Messages this run was told to answer. More than one when a further message
+ * arrived while the run was queued, or while it was executing this same
+ * thread — both coalesce rather than booking a second run.
+ */
+ triggerMessageIds: string[];
+ /**
+ * How many times this run has been started. A run revived after a stall or a
+ * daemon restart is on attempt 2; a second failure is terminal.
+ */
+ attempts: number;
+ /** Diagnostic wall clock only; never a FIFO key. */
+ queuedAt: number;
+ startedAt?: number;
+ endedAt?: number;
+ error?: string;
+}
+
+/**
+ * A unit of work several agents and people share.
+ *
+ * Stored one file per thread under the per-project runtime dir — not the
+ * working tree. Thread text is written by agents and fed to other agents, so
+ * it is a prompt-injection surface by construction; keeping it out of the
+ * repo means it is never committed, pulled, or reviewed as if it were code.
+ */
+export interface Thread {
+ id: string;
+ title: string;
+ body: string;
+ status: ThreadStatus;
+ /** Agent that owns the thread when no message names someone explicitly. */
+ assigneeAgentId?: string;
+ createdAt: number;
+ /** {@link HUMAN_AUTHOR_ID} or an agent id. */
+ createdBy: string;
+ /** Set when an agent split this thread out of another one. */
+ parentThreadId?: string;
+ /**
+ * Root of this thread tree. Equal to `id` for a root thread. Token spend is
+ * charged there so splitting work cannot mint more money.
+ */
+ rootThreadId: string;
+ messages: ThreadMessage[];
+ runs: ThreadRun[];
+ /**
+ * Agent-triggered deliveries on this thread since its last human post. A
+ * delivery into a running agent counts too; otherwise two live agents could
+ * ping-pong without booking another run. Local scope keeps a human reply on
+ * one sub-thread from resetting an unrelated sibling loop.
+ */
+ autoTurnsUsed: number;
+ /**
+ * Tokens spent by runs on this thread tree, accumulated from each run's
+ * usage delta. Unlike the turn counter this is NOT reset by a human post:
+ * turns measure how long a conversation has run unattended, tokens measure
+ * money already spent.
+ */
+ tokensUsed: number;
+}
+
+/** Default cap on runs waiting for one agent across all threads. */
+export const DEFAULT_QUEUE_LIMIT = 5;
+
+/**
+ * Default cap on consecutive agent-triggered deliveries on one thread. Chosen to
+ * allow a real hand-off chain (delegate → work → report → follow-up) while
+ * still stopping a two-agent loop within a few turns.
+ */
+export const DEFAULT_THREAD_AUTO_TURN_BUDGET = 12;
+
+/**
+ * Default cap on tokens spent by one thread tree.
+ *
+ * There is deliberately no wall-clock gate beside these two. An earlier
+ * revision had one, measured from first dispatch, which would have refused a
+ * thread opened on Monday and revisited on Tuesday: elapsed time is not cost.
+ * A run that hangs is the stall sweeper's problem, not the budget's.
+ */
+export const DEFAULT_THREAD_TOKEN_BUDGET = 200_000;
+
+/** Bound on retained posts per thread. */
+export const MAX_THREAD_MESSAGES = 500;
+
+/** Bound on retained run records per thread. */
+export const MAX_THREAD_RUNS = 200;
diff --git a/packages/core/src/agents/runtime/agent-core-test-mock.ts b/packages/core/src/agents/runtime/agent-core-test-mock.ts
index 9217afc096e..e0b53dd42c5 100644
--- a/packages/core/src/agents/runtime/agent-core-test-mock.ts
+++ b/packages/core/src/agents/runtime/agent-core-test-mock.ts
@@ -131,6 +131,7 @@ export function createMockToolRegistry() {
getAllToolNames: vi.fn().mockReturnValue([]),
registerTool: vi.fn(),
copyDiscoveredToolsFrom: vi.fn(),
+ discoverToolsForServer: vi.fn().mockResolvedValue(undefined),
stop: vi.fn().mockResolvedValue(undefined),
tools: new Map(),
};
diff --git a/packages/core/src/agents/runtime/agent-core.ts b/packages/core/src/agents/runtime/agent-core.ts
index 3aa9d45ce29..201cc9975d4 100644
--- a/packages/core/src/agents/runtime/agent-core.ts
+++ b/packages/core/src/agents/runtime/agent-core.ts
@@ -1207,7 +1207,7 @@ export class AgentCore {
// Update token usage if available
if (lastUsage) {
- this.recordTokenUsage(lastUsage, turnCounter, roundStreamStart);
+ this.recordTokenUsage(lastUsage, cumulativeRounds, roundStreamStart);
}
if (functionCalls.length > 0) {
@@ -1408,6 +1408,7 @@ export class AgentCore {
subagentId: this.subagentId,
kind: typeof input === 'string' ? 'message' : input.kind,
text: typeof input === 'string' ? input : input.text,
+ deliveryId: typeof input === 'string' ? undefined : input.deliveryId,
timestamp: Date.now(),
});
}
diff --git a/packages/core/src/agents/runtime/agent-events.ts b/packages/core/src/agents/runtime/agent-events.ts
index 0736216d48a..3c1ca09e3f3 100644
--- a/packages/core/src/agents/runtime/agent-events.ts
+++ b/packages/core/src/agents/runtime/agent-events.ts
@@ -198,6 +198,8 @@ export interface AgentExternalMessageEvent {
kind?: 'message' | 'notification';
/** Raw message text (without any framing prefix). */
text: string;
+ /** Durable delivery identity when the producer has one. */
+ deliveryId?: string;
timestamp: number;
}
diff --git a/packages/core/src/agents/runtime/agent-headless.test.ts b/packages/core/src/agents/runtime/agent-headless.test.ts
index ef40d8c6945..72a35c4e64f 100644
--- a/packages/core/src/agents/runtime/agent-headless.test.ts
+++ b/packages/core/src/agents/runtime/agent-headless.test.ts
@@ -51,6 +51,7 @@ import {
type AgentStreamTextEvent,
type AgentToolCallEvent,
type AgentToolResultEvent,
+ type AgentUsageEvent,
} from './agent-events.js';
import type {
ModelConfig,
@@ -636,31 +637,87 @@ describe('subagent.ts', () => {
const externalEvents: Array<{
kind: string | undefined;
text: string;
+ deliveryId: string | undefined;
}> = [];
scope.getEventEmitter().on(AgentEventType.EXTERNAL_MESSAGE, (event) => {
- externalEvents.push({ kind: event.kind, text: event.text });
+ externalEvents.push({
+ kind: event.kind,
+ text: event.text,
+ deliveryId: event.deliveryId,
+ });
});
const initialContext = new ContextState();
initialContext.set('task_prompt', 'Initial task');
await scope.execute(initialContext);
await scope.executeExternalInputs(
- ['late correction', { kind: 'notification', text: 'monitor fired' }],
+ [
+ {
+ kind: 'message',
+ text: 'late correction',
+ deliveryId: 'delivery-1',
+ },
+ { kind: 'notification', text: 'monitor fired' },
+ ],
undefined,
{ resetStats: false },
);
expect(mockSendMessageStream.mock.calls[1][1].message).toEqual([
- { text: '[Message from parent agent]: late correction' },
+ { text: 'late correction' },
{ text: 'monitor fired' },
]);
expect(externalEvents).toEqual([
- { kind: 'message', text: 'late correction' },
- { kind: 'notification', text: 'monitor fired' },
+ {
+ kind: 'message',
+ text: 'late correction',
+ deliveryId: 'delivery-1',
+ },
+ {
+ kind: 'notification',
+ text: 'monitor fired',
+ deliveryId: undefined,
+ },
]);
expect(scope.getExecutionSummary()).toMatchObject({ rounds: 2 });
});
+ it('should keep usage rounds unique across finishing input segments', async () => {
+ const { config } = await createMockConfig();
+ mockSendMessageStream.mockImplementation(async () =>
+ (async function* () {
+ yield {
+ type: 'chunk',
+ value: {
+ candidates: [{ content: { parts: [{ text: 'Done.' }] } }],
+ usageMetadata: { totalTokenCount: 1 },
+ },
+ };
+ })(),
+ );
+
+ const scope = await AgentHeadless.create(
+ 'test-agent',
+ config,
+ { systemPrompt: 'You are a test agent.' },
+ defaultModelConfig,
+ defaultRunConfig,
+ );
+ const usageRounds: number[] = [];
+ scope
+ .getEventEmitter()
+ .on(AgentEventType.USAGE_METADATA, (event: AgentUsageEvent) => {
+ usageRounds.push(event.round);
+ });
+
+ await scope.execute(new ContextState());
+ await scope.executeExternalInputs(['late correction'], undefined, {
+ resetStats: false,
+ });
+
+ expect(usageRounds).toEqual([1, 2]);
+ });
+
it('should preserve statistics for continuation work in the same logical turn', async () => {
const { config } = await createMockConfig();
mockSendMessageStream.mockImplementation(
@@ -1305,6 +1362,40 @@ describe('subagent.ts', () => {
]);
});
+ it('should preserve a delivery id for input drained between rounds', async () => {
+ const { config } = await createMockConfig();
+ mockSendMessageStream.mockImplementation(
+ createMockStream(['stop', 'stop']),
+ );
+ const pendingInputs = [
+ {
+ kind: 'message' as const,
+ text: 'review this result',
+ deliveryId: 'delivery-2',
+ },
+ ];
+ const deliveryIds: Array<string | undefined> = [];
+
+ const scope = await AgentHeadless.create(
+ 'test-agent',
+ config,
+ promptConfig,
+ defaultModelConfig,
+ defaultRunConfig,
+ );
+ scope.getEventEmitter().on(AgentEventType.EXTERNAL_MESSAGE, (event) => {
+ deliveryIds.push(event.deliveryId);
+ });
+ scope.setExternalMessageProvider(() => pendingInputs.splice(0));
+
+ await scope.execute(new ContextState());
+
+ expect(mockSendMessageStream.mock.calls[1][1].message).toEqual([
+ { text: 'review this result' },
+ ]);
+ expect(deliveryIds).toEqual(['delivery-2']);
+ });
+
it('should not idle-wait when max turns prevents another round', async () => {
const { config } = await createMockConfig();
const runConfig: RunConfig = { ...defaultRunConfig, max_turns: 1 };
diff --git a/packages/core/src/agents/runtime/agent-headless.ts b/packages/core/src/agents/runtime/agent-headless.ts
index 08a00fc3382..e5f5b9dbb8c 100644
--- a/packages/core/src/agents/runtime/agent-headless.ts
+++ b/packages/core/src/agents/runtime/agent-headless.ts
@@ -283,6 +283,7 @@ export class AgentHeadless {
subagentId: this.core.subagentId,
kind: typeof input === 'string' ? 'message' : input.kind,
text: typeof input === 'string' ? input : input.text,
+ deliveryId: typeof input === 'string' ? undefined : input.deliveryId,
timestamp: Date.now(),
});
}
diff --git a/packages/core/src/agents/runtime/agent-types.ts b/packages/core/src/agents/runtime/agent-types.ts
index b757ecc3a6f..bd05949f9e1 100644
--- a/packages/core/src/agents/runtime/agent-types.ts
+++ b/packages/core/src/agents/runtime/agent-types.ts
@@ -72,8 +72,9 @@ export interface RunConfig {
export type AgentExternalInput =
| string
| {
- kind: 'notification';
+ kind: 'message' | 'notification';
text: string;
+ deliveryId?: string;
};
/**
diff --git a/packages/core/src/agents/team/TeamManager.model-routing.test.ts b/packages/core/src/agents/team/TeamManager.model-routing.test.ts
index 8808856abc1..d7350e5753c 100644
--- a/packages/core/src/agents/team/TeamManager.model-routing.test.ts
+++ b/packages/core/src/agents/team/TeamManager.model-routing.test.ts
@@ -99,6 +99,9 @@ function createLeaderConfig(projectRoot: string): Config {
getAllConfiguredModels: vi.fn().mockReturnValue([]),
getToolRegistry: vi.fn().mockReturnValue(createMockToolRegistry()),
createToolRegistry: vi.fn().mockResolvedValue(createMockToolRegistry()),
+ getMcpServers: vi.fn().mockReturnValue({
+ session: { command: 'session-server' },
+ }),
getMonitorRegistry: vi.fn().mockReturnValue({
setAgentNotificationCallback: vi.fn(),
cancelRunningForOwner: vi.fn(),
@@ -255,6 +258,50 @@ describe('TeamManager teammate model routing (#10071)', () => {
expect(member.model).toBe('claude-worker');
});
+ it('loads MCP servers declared by the teammate agent definition', async () => {
+ const agentsDir = path.join(projectDir, '.qwen', 'agents');
+ await fs.mkdir(agentsDir, { recursive: true });
+ await fs.writeFile(
+ path.join(agentsDir, 'mcp-worker.md'),
+ [
+ '---',
+ 'name: mcp-worker',
+ 'description: A worker with a private MCP server',
+ 'mcpServers:',
+ ' agent-private:',
+ ' command: node',
+ ' args:',
+ ' - /tmp/agent-private-mcp.js',
+ '---',
+ '',
+ 'Use the private MCP tool.',
+ ].join('\n'),
+ 'utf-8',
+ );
+
+ await teamManager.spawnTeammate({
+ name: 'mcp-worker-1',
+ agentType: 'mcp-worker',
+ cwd: projectDir,
+ });
+
+ const MockAgentCore = AgentCore as unknown as ReturnType<typeof vi.fn>;
+ const { runtimeContext } = destructureAgentCoreCall(
+ MockAgentCore.mock.calls.at(-1)!,
+ );
+ const agentConfig = runtimeContext as unknown as Config;
+ expect(agentConfig.getMcpServers()).toEqual({
+ session: { command: 'session-server' },
+ 'agent-private': {
+ command: 'node',
+ args: ['/tmp/agent-private-mcp.js'],
+ },
+ });
+ expect(
+ vi.mocked(agentConfig.getToolRegistry().discoverToolsForServer),
+ ).toHaveBeenCalledWith('agent-private');
+ });
+
it('resolves a fast selector in the definition against the runtime context', async () => {
// convertToRuntimeConfig alone receives no runtime context, so a
// `fast` selector could not resolve and the teammate silently
diff --git a/packages/core/src/agents/team/TeamManager.ts b/packages/core/src/agents/team/TeamManager.ts
index 3c7d6ca1a6d..fc11619f9ec 100644
--- a/packages/core/src/agents/team/TeamManager.ts
+++ b/packages/core/src/agents/team/TeamManager.ts
@@ -25,6 +25,7 @@ import { ApprovalMode } from '../../config/config.js';
import type {
Backend,
AgentSpawnConfig,
+ InProcessSpawnConfig,
TeamAgentHandle,
} from '../backends/types.js';
import { PermissionMode } from '../../hooks/types.js';
@@ -494,13 +495,14 @@ export class TeamManager {
try {
// Load specialized subagent config when an agentType is specified.
- // Copies prompt, model, runConfig, and tools from the subagent
+ // Copies prompt, model, runConfig, tools, and MCP servers from the subagent
// definition so the teammate behaves like that agent type.
let subagentPrompt: string | undefined;
let subagentModel: string | undefined;
let subagentModelRoute: SubagentModelRoute | undefined;
let subagentRunConfig: Record<string, unknown> | undefined;
let toolConfig: ToolConfig | undefined;
+ let mcpServers: InProcessSpawnConfig['mcpServers'];
if (config.agentType && this.subagentManager) {
const subagentConfig = await this.subagentManager.loadSubagent(
config.agentType,
@@ -514,6 +516,9 @@ export class TeamManager {
subagentModel = runtimeCfg.modelConfig.model;
subagentRunConfig = runtimeCfg.runConfig as Record<string, unknown>;
toolConfig = runtimeCfg.toolConfig;
+ mcpServers = subagentConfig.mcpServers as
+ | InProcessSpawnConfig['mcpServers']
+ | undefined;
// Resolve the definition's model selector with the runtime context,
// the same way the ordinary-subagent path does (#10071).
// convertToRuntimeConfig is called without a context, so it keeps
@@ -627,6 +632,7 @@ export class TeamManager {
authOverrides: dedicatedRoute
? { authType: dedicatedRoute.authType }
: undefined,
+ mcpServers,
runtimeConfig: {
promptConfig: {
systemPrompt,
diff --git a/packages/core/src/services/chatRecordingService.ts b/packages/core/src/services/chatRecordingService.ts
index b984a93ea50..6854ecd39ce 100644
--- a/packages/core/src/services/chatRecordingService.ts
+++ b/packages/core/src/services/chatRecordingService.ts
@@ -393,6 +393,8 @@ export interface ChatRecord {
agentRound?: number;
/** Source kind for injected external input records. */
externalInputKind?: 'message' | 'notification';
+ /** Durable identity of the external delivery that produced this record. */
+ externalInputDeliveryId?: string;
/**
* Set on every record of a forked session to record its lineage.
diff --git a/packages/core/src/tools/agent/agent.test.ts b/packages/core/src/tools/agent/agent.test.ts
index 731cedd4180..83f7667b567 100644
--- a/packages/core/src/tools/agent/agent.test.ts
+++ b/packages/core/src/tools/agent/agent.test.ts
@@ -6377,10 +6377,22 @@ describe('AgentTool', () => {
});
const resident = mockRegistry.registerResidentAgent.mock.calls[0]?.[1] as
- | { continue: (message: string) => boolean }
+ | {
+ continue: (input: {
+ kind: 'message';
+ text: string;
+ deliveryId: string;
+ }) => string;
+ }
| undefined;
expect(resident).toBeDefined();
- expect(resident?.continue('Now inspect the helper')).toBe(true);
+ expect(
+ resident?.continue({
+ kind: 'message',
+ text: 'Now inspect the helper',
+ deliveryId: 'delivery-3',
+ }),
+ ).toBe('continued');
await vi.waitFor(() => {
expect(mockAgent.execute).toHaveBeenCalledTimes(2);
@@ -6391,8 +6403,14 @@ describe('AgentTool', () => {
expect.any(AbortController),
);
expect(mockContextState.set).toHaveBeenCalledWith(
- 'task_prompt',
- 'Now inspect the helper',
+ 'external_inputs_override',
+ [
+ {
+ kind: 'message',
+ text: 'Now inspect the helper',
+ deliveryId: 'delivery-3',
+ },
+ ],
);
expect(mockSubagentManager.createAgentHeadless).toHaveBeenCalledTimes(1);
expect(mockSubagentManager.createAgentHeadless).toHaveBeenCalledWith(
@@ -6424,10 +6442,10 @@ describe('AgentTool', () => {
});
const resident = mockRegistry.registerResidentAgent.mock.calls[0]?.[1] as
- | { continue: (message: string) => boolean }
+ | { continue: (message: string) => string }
| undefined;
expect(resident).toBeDefined();
- expect(resident?.continue('Now inspect the helper')).toBe(true);
+ expect(resident?.continue('Now inspect the helper')).toBe('continued');
// The hot continuation patch must clear run N-1's terminal summary —
// mirroring the cold-resume patch — so a crash mid-continuation cannot
@@ -6447,6 +6465,29 @@ describe('AgentTool', () => {
patchMetaSpy.mockRestore();
});
+ it('reports capacity before restarting a resident runtime', async () => {
+ const invocation = (
+ agentTool as AgentToolWithProtectedMethods
+ ).createInvocation({
+ description: 'Start monitor',
+ prompt: 'Watch for changes',
+ subagent_type: 'monitor',
+ });
+
+ await invocation.execute();
+ await vi.waitFor(() => {
+ expect(mockRegistry.complete).toHaveBeenCalledTimes(1);
+ });
+
+ mockRegistry.canStartBackgroundAgent.mockReturnValue(false);
+ const resident = mockRegistry.registerResidentAgent.mock.calls[0]?.[1] as
+ | { continue: (message: string) => string }
+ | undefined;
+
+ expect(resident?.continue('Continue')).toBe('capacity_wait');
+ expect(mockRegistry.restartCompletedAgent).not.toHaveBeenCalled();
+ });
+
it('claims finishing-window input before publishing completion', async () => {
mockRegistry.drainMessages
.mockReturnValueOnce(['late correction'])
@@ -6570,13 +6611,13 @@ describe('AgentTool', () => {
expect(mockRegistry.complete).toHaveBeenCalled();
});
const resident = mockRegistry.registerResidentAgent.mock.calls[0]?.[1] as
- | { continue: (message: string) => boolean }
+ | { continue: (message: string) => string }
| undefined;
expect(resident).toBeDefined();
expect(mockSubagentDispose).not.toHaveBeenCalled();
vi.mocked(config.getApprovalMode).mockReturnValue(ApprovalMode.DEFAULT);
- expect(resident?.continue('Continue')).toBe(false);
+ expect(resident?.continue('Continue')).toBe('fallback');
expect(mockRegistry.unregisterResidentAgent).toHaveBeenCalled();
expect(mockSubagentDispose).toHaveBeenCalledOnce();
diff --git a/packages/core/src/tools/agent/agent.ts b/packages/core/src/tools/agent/agent.ts
index 493acc255f2..9488fbbbcfa 100644
--- a/packages/core/src/tools/agent/agent.ts
+++ b/packages/core/src/tools/agent/agent.ts
@@ -3771,13 +3771,18 @@ class AgentToolInvocation extends BaseToolInvocation<AgentParams, ToolResult> {
};
const residentController: ResidentBackgroundAgent = {
- continue: (message) => {
+ continue: (input) => {
if (!canStayResident || disposeRequested || runtimeDisposed) {
- return false;
+ return 'fallback';
}
if (needsAutoPermissionLease()) {
requestRuntimeDisposal();
- return false;
+ return 'fallback';
+ }
+
+ const currentEntry = registry.get(hookOpts.agentId);
+ if (!registry.canStartBackgroundAgent(currentEntry?.model)) {
+ return 'capacity_wait';
}
const nextAbortController = new AbortController();
@@ -3791,7 +3796,9 @@ class AgentToolInvocation extends BaseToolInvocation<AgentParams, ToolResult> {
debugLogger.warn(
`[Agent] Could not continue resident background agent ${hookOpts.agentId}: ${error instanceof Error ? error.message : String(error)}`,
);
- return false;
+ return registry.canStartBackgroundAgent(currentEntry?.model)
+ ? 'fallback'
+ : 'capacity_wait';
}
if (
!restarted ||
@@ -3800,7 +3807,7 @@ class AgentToolInvocation extends BaseToolInvocation<AgentParams, ToolResult> {
registry.get(hookOpts.agentId) !== restarted ||
restarted.status !== 'running'
) {
- return false;
+ return 'fallback';
}
liveToolCallCount = 0;
@@ -3821,7 +3828,11 @@ class AgentToolInvocation extends BaseToolInvocation<AgentParams, ToolResult> {
});
const nextContextState = new ContextState();
- nextContextState.set('task_prompt', message);
+ if (typeof input === 'string') {
+ nextContextState.set('task_prompt', input);
+ } else {
+ nextContextState.set('external_inputs_override', [input]);
+ }
nextContextState.set('hook_context', '');
const previousTurn = currentTurnPromise ?? Promise.resolve();
currentTurnPromise = previousTurn
@@ -3835,7 +3846,7 @@ class AgentToolInvocation extends BaseToolInvocation<AgentParams, ToolResult> {
);
});
currentTurnPromise.catch(reportUnexpectedBackgroundError);
- return true;
+ return 'continued';
},
dispose: requestRuntimeDisposal,
};
diff --git a/packages/core/src/tools/send-message.test.ts b/packages/core/src/tools/send-message.test.ts
index 8b5c174e587..a4693b302c0 100644
--- a/packages/core/src/tools/send-message.test.ts
+++ b/packages/core/src/tools/send-message.test.ts
@@ -481,7 +481,7 @@ describe('SendMessageTool — background-task mode', () => {
outputFile: '/tmp/test.jsonl',
metaPath: '/tmp/test.meta.json',
});
- const continueResident = vi.fn().mockReturnValue(true);
+ const continueResident = vi.fn().mockReturnValue('continued');
registry.registerResidentAgent('agent-1', {
continue: continueResident,
dispose: vi.fn(),
@@ -500,6 +500,32 @@ describe('SendMessageTool — background-task mode', () => {
expect(result.returnDisplay).toContain('Continued');
});
+ it('reports resident capacity without attempting a cold revive', async () => {
+ registry.register({
+ agentId: 'agent-1',
+ description: 'test agent',
+ status: 'completed',
+ startTime: Date.now(),
+ abortController: new AbortController(),
+ isBackgrounded: true,
+ outputFile: '/tmp/test.jsonl',
+ metaPath: '/tmp/test.meta.json',
+ });
+ registry.registerResidentAgent('agent-1', {
+ continue: vi.fn().mockReturnValue('capacity_wait'),
+ dispose: vi.fn(),
+ });
+
+ const result = await tool.validateBuildAndExecute(
+ { task_id: 'agent-1', message: 'now refactor the helper' },
+ new AbortController().signal,
+ );
+
+ expect(reviveCompletedBackgroundAgent).not.toHaveBeenCalled();
+ expect(result.error?.type).toBe(ToolErrorType.SEND_MESSAGE_NOT_RUNNING);
+ expect(result.llmContent).toContain('capacity');
+ });
+
it('revives a completed task when no resident runtime is available', async () => {
registry.register({
agentId: 'agent-1',
diff --git a/packages/core/src/tools/send-message.ts b/packages/core/src/tools/send-message.ts
index 3994c2c1ad4..10e8010c371 100644
--- a/packages/core/src/tools/send-message.ts
+++ b/packages/core/src/tools/send-message.ts
@@ -293,16 +293,26 @@ class SendMessageInvocation extends BaseToolInvocation<
// compatible runtime is not retained across session restore, so the
// persisted transcript remains the cold fallback for resumable agents.
if (entry.status === 'completed') {
- const continued = registry.continueResidentAgent(
+ const continuation = registry.continueResidentAgent(
this.params.task_id,
this.params.message,
);
- if (continued) {
+ if (continuation === 'continued') {
return {
llmContent: `Background task "${this.params.task_id}" continued on its existing runtime with your message as the next instruction.`,
returnDisplay: `Continued ${entry.description}`,
};
}
+ if (continuation === 'capacity_wait') {
+ return {
+ llmContent: `Error: Background task "${this.params.task_id}" is waiting for background-agent capacity.`,
+ returnDisplay: 'Task is waiting for capacity.',
+ error: {
+ message: `Background-agent capacity unavailable: ${this.params.task_id}`,
+ type: ToolErrorType.SEND_MESSAGE_NOT_RUNNING,
+ },
+ };
+ }
const revived = await this.config.reviveCompletedBackgroundAgent(
this.params.task_id,
diff --git a/packages/sdk-typescript/src/daemon/types.ts b/packages/sdk-typescript/src/daemon/types.ts
index c57461ee3f1..35ed1750bb8 100644
--- a/packages/sdk-typescript/src/daemon/types.ts
+++ b/packages/sdk-typescript/src/daemon/types.ts
@@ -2781,7 +2781,7 @@ export interface DaemonSessionAgentTaskStatus {
id: string;
label: string;
description: string;
- status: DaemonSessionTaskLifecycleStatus;
+ status: DaemonSessionTaskLifecycleStatus | 'idle';
startTime: number;
endTime?: number;
runtimeMs: number;
@@ -2810,6 +2810,16 @@ export interface DaemonSessionAgentTaskStatus {
parentName?: string;
/** Launch depth (0-based; 0 = spawned by the top-level session). */
depth?: number;
+ /** Active Agent Team name when this row represents a named teammate. */
+ teamName?: string;
+ /** Teammate color assigned by TeamManager. */
+ color?: string;
+ /** Current shared team task, when the teammate owns one. */
+ teamTask?: {
+ id: string;
+ subject: string;
+ status: 'pending' | 'in_progress' | 'completed';
+ };
}
export interface DaemonSessionShellTaskStatus {
diff --git a/packages/sdk-typescript/src/daemon/ui/toolPreview.ts b/packages/sdk-typescript/src/daemon/ui/toolPreview.ts
index 3bf6c508abd..b5edb2f590b 100644
--- a/packages/sdk-typescript/src/daemon/ui/toolPreview.ts
+++ b/packages/sdk-typescript/src/daemon/ui/toolPreview.ts
@@ -605,7 +605,7 @@ const MAX_SEARCH_TOP_RESULTS = 5;
/**
* Detect sub-agent delegation. Matches toolName containing "delegate" /
- * "subagent" / "spawn-task" / "Task" (Anthropic-style) plus an explicit
+ * "subagent" / "spawn-task" / "Agent" / "Task" plus an explicit
* agent name or prompt-like field.
*/
function detectSubagentDelegation(
@@ -616,12 +616,12 @@ function detectSubagentDelegation(
// wenshao R3 (claude-opus-4-7): `task` was previously matched in either
// `^|_` position, which falsely caught `edit_task`, `list_task`,
// `create_task`, etc. — common tool names that have nothing to do with
- // sub-agent delegation. The Anthropic-style delegation tool is
- // literally named `Task` (no prefix), so restrict the bare-`task`
- // match to whole-name only. `delegate` / `subagent` / `spawn_task`
+ // sub-agent delegation. The built-in delegation tools are literally named
+ // `Agent` / `Task`, so restrict those bare names to whole-name matches.
+ // `delegate` / `subagent` / `spawn_task`
// are specific enough to keep the `^|_` prefix.
const looksLikeDelegate =
- /^task$/i.test(toolName) ||
+ /^(?:agent|task)$/i.test(toolName) ||
/(?:^|_)(?:delegate|subagent|spawn[_-]?task)$/i.test(toolName) ||
/agent/i.test(opts.toolKind ?? '');
if (!looksLikeDelegate) return undefined;
@@ -641,6 +641,7 @@ function detectSubagentDelegation(
'query',
]);
if (!agentName && !task) return undefined;
+ const teammateName = getFirstString(input, ['name']);
const parentDelegationId = getFirstString(input, [
'parentDelegationId',
'parent_delegation_id',
@@ -649,6 +650,7 @@ function detectSubagentDelegation(
return {
kind: 'subagent_delegation',
agentName: agentName ?? 'subagent',
+ ...(teammateName ? { teammateName } : {}),
task: task ?? '(no task description)',
...(parentDelegationId ? { parentDelegationId } : {}),
};
diff --git a/packages/sdk-typescript/src/daemon/ui/types.ts b/packages/sdk-typescript/src/daemon/ui/types.ts
index ade558dc24f..70bbd1254db 100644
--- a/packages/sdk-typescript/src/daemon/ui/types.ts
+++ b/packages/sdk-typescript/src/daemon/ui/types.ts
@@ -883,6 +883,8 @@ export type DaemonToolPreview =
kind: 'subagent_delegation';
/** Sub-agent name receiving the delegation. */
agentName: string;
+ /** Optional Agent Team member name chosen for this launch. */
+ teammateName?: string;
/** Task description / prompt sent to the sub-agent. */
task: string;
/** Optional parent delegation id for chained subagents. */
diff --git a/packages/sdk-typescript/test/unit/daemonUi.test.ts b/packages/sdk-typescript/test/unit/daemonUi.test.ts
index 0912df3f29f..3bf32f5e6e7 100644
--- a/packages/sdk-typescript/test/unit/daemonUi.test.ts
+++ b/packages/sdk-typescript/test/unit/daemonUi.test.ts
@@ -6038,18 +6038,20 @@ describe('daemon UI render contract (PR-D)', () => {
});
describe('daemon UI tool preview taxonomy — long-tail kinds (PR-F)', () => {
- it('detects subagent_delegation from Anthropic-style Task tool', () => {
+ it('detects a named subagent delegation from the Agent tool', () => {
const preview = createDaemonToolPreview(
{
subagent_type: 'code-reviewer',
+ name: 'security-reviewer',
prompt: 'Review the auth module',
description: 'Security review',
},
- { toolName: 'Task' },
+ { toolName: 'agent', toolKind: 'other' },
);
expect(preview).toMatchObject({
kind: 'subagent_delegation',
agentName: 'code-reviewer',
+ teammateName: 'security-reviewer',
task: 'Review the auth module',
});
});
diff --git a/packages/web-shell/client/App.test.tsx b/packages/web-shell/client/App.test.tsx
index c40db1195bd..72fa3215a28 100644
--- a/packages/web-shell/client/App.test.tsx
+++ b/packages/web-shell/client/App.test.tsx
@@ -2822,40 +2822,43 @@ describe('task activity key', () => {
expect(mockWorkspace.client.sessionAgents).toHaveBeenCalledTimes(2);
});
- it('keeps polling while a persisted subagent is paused', async () => {
- mockConnection.capabilities.features = ['session_agents'];
- vi.useFakeTimers();
- mockWorkspace.client.sessionAgents.mockResolvedValue({
- v: 1,
- sessionId: 'session-1',
- tasks: [
- {
- kind: 'agent',
- id: 'agent-1',
- label: 'Paused agent',
- description: 'Waiting to resume',
- status: 'paused',
- startTime: 1_000,
- runtimeMs: 500,
- isBackgrounded: true,
- },
- ],
- });
- const { container } = renderApp();
- await flush();
+ it.each(['paused', 'idle'] as const)(
+ 'keeps polling while a persisted agent is %s',
+ async (status) => {
+ mockConnection.capabilities.features = ['session_agents'];
+ vi.useFakeTimers();
+ mockWorkspace.client.sessionAgents.mockResolvedValue({
+ v: 1,
+ sessionId: 'session-1',
+ tasks: [
+ {
+ kind: 'agent',
+ id: 'agent-1',
+ label: 'Waiting agent',
+ description: 'Waiting to resume',
+ status,
+ startTime: 1_000,
+ runtimeMs: 500,
+ isBackgrounded: true,
+ },
+ ],
+ });
+ const { container } = renderApp();
+ await flush();
- act(() => {
- container
- .querySelector<HTMLButtonElement>(
- 'button[aria-label="Toggle environment information"]',
- )
- ?.click();
- });
- await flush();
+ act(() => {
+ container
+ .querySelector<HTMLButtonElement>(
+ 'button[aria-label="Toggle environment information"]',
+ )
+ ?.click();
+ });
+ await flush();
- await act(async () => vi.advanceTimersByTimeAsync(3_000));
- expect(mockWorkspace.client.sessionAgents).toHaveBeenCalledTimes(2);
- });
+ await act(async () => vi.advanceTimersByTimeAsync(3_000));
+ expect(mockWorkspace.client.sessionAgents).toHaveBeenCalledTimes(2);
+ },
+ );
it('stops polling when persisted subagents are complete', async () => {
mockConnection.capabilities.features = ['session_agents'];
@@ -7732,6 +7735,56 @@ describe('environment agent tasks', () => {
]);
});
+ it('merges a teammate launch with its live team inventory row', () => {
+ const messages = [
+ {
+ id: 'tools',
+ role: 'tool_group',
+ tools: [
+ {
+ callId: 'agent-call',
+ toolName: 'agent',
+ title: 'Agent: Review code',
+ status: 'completed',
+ args: {
+ description: 'Review code',
+ name: 'reviewer',
+ },
+ rawOutput: 'Teammate "reviewer" is now running concurrently.',
+ },
+ ],
+ },
+ ] satisfies Message[];
+ const teammate = {
+ kind: 'agent' as const,
+ id: 'reviewer@review-team',
+ label: 'reviewer',
+ description: 'Reviewing authentication flow',
+ status: 'idle' as const,
+ startTime: 1,
+ runtimeMs: 1,
+ isBackgrounded: false,
+ teamName: 'review-team',
+ color: '#4ECDC4',
+ teamTask: {
+ id: '1',
+ subject: 'Review authentication flow',
+ status: 'in_progress' as const,
+ },
+ };
+
+ expect(getEnvironmentAgentTasks(messages, [teammate])).toEqual([
+ expect.objectContaining({
+ id: 'reviewer@review-team',
+ label: 'reviewer',
+ description: 'Reviewing authentication flow',
+ status: 'idle',
+ toolUseId: 'agent-call',
+ teamName: 'review-team',
+ }),
+ ]);
+ });
+
it('deduplicates a live agent by the task id recorded in the message stream', () => {
const messages = [
{
diff --git a/packages/web-shell/client/App.tsx b/packages/web-shell/client/App.tsx
index 3040502491d..daa29c4737f 100644
--- a/packages/web-shell/client/App.tsx
+++ b/packages/web-shell/client/App.tsx
@@ -2430,7 +2430,9 @@ function derivedTaskIdForTool(tool: ACPToolCall): string | undefined {
const subagentName =
typeof rawOutput?.['subagentName'] === 'string'
? rawOutput['subagentName']
- : undefined;
+ : typeof tool.args?.name === 'string'
+ ? tool.args.name
+ : undefined;
const subagentType =
typeof tool.args?.subagent_type === 'string'
? tool.args.subagent_type
@@ -2514,7 +2516,9 @@ export function getEnvironmentAgentTasks(
const subagentName =
typeof rawOutput?.['subagentName'] === 'string'
? rawOutput['subagentName']
- : undefined;
+ : typeof tool.args?.name === 'string'
+ ? tool.args.name
+ : undefined;
const taskId = taskIdsByToolUseId.get(tool.callId);
const derivedTaskId = derivedTaskIdForTool(tool);
// Completed background agents can lose their toolUseId / derived-id
@@ -2539,6 +2543,9 @@ export function getEnvironmentAgentTasks(
task.toolUseId === tool.callId ||
task.id === taskId ||
task.id === derivedTaskId ||
+ (task.teamName != null &&
+ subagentName != null &&
+ task.label === subagentName) ||
(!seenTaskIds.has(task.id) &&
!isPreciselyClaimed(task) &&
matchesLiveTaskContent(task)),
@@ -2562,10 +2569,12 @@ export function getEnvironmentAgentTasks(
? {
...liveTask,
toolUseId: tool.callId,
- label,
- description: taskDescription || liveTask.description,
+ label: liveTask.teamName ? liveTask.label : label,
+ description: liveTask.teamName
+ ? liveTask.description
+ : taskDescription || liveTask.description,
...(subagentType ? { subagentType } : {}),
- ...(color ? { color } : {}),
+ ...(color && !liveTask.teamName ? { color } : {}),
}
: {
kind: 'agent',
@@ -6705,7 +6714,10 @@ export function App({
consecutiveFailures = 0;
if (
agents.some(
- (task) => task.status === 'running' || task.status === 'paused',
+ (task) =>
+ task.status === 'running' ||
+ task.status === 'idle' ||
+ task.status === 'paused',
)
) {
timer = setTimeout(refresh, SESSION_AGENTS_REFRESH_INTERVAL_MS);
diff --git a/packages/web-shell/client/adapters/transcriptToMessages.test.ts b/packages/web-shell/client/adapters/transcriptToMessages.test.ts
index bef4b7bdd1b..9cc59b6536d 100644
--- a/packages/web-shell/client/adapters/transcriptToMessages.test.ts
+++ b/packages/web-shell/client/adapters/transcriptToMessages.test.ts
@@ -1567,6 +1567,7 @@ describe('transcriptBlocksToDaemonMessages', () => {
preview: {
kind: 'subagent_delegation',
agentName: 'reviewer',
+ teammateName: 'security-reviewer',
task: 'Review safely',
},
resultPreview: {
@@ -1583,6 +1584,10 @@ describe('transcriptBlocksToDaemonMessages', () => {
expect(tool).toMatchObject({
callId: 'agent-safe',
status: 'completed',
+ args: {
+ name: 'security-reviewer',
+ subagent_type: 'reviewer',
+ },
});
expect(tool?.endTime).toBe(20);
});
diff --git a/packages/web-shell/client/adapters/transcriptToMessages.ts b/packages/web-shell/client/adapters/transcriptToMessages.ts
index 0ac5991e975..6ebfc460a8c 100644
--- a/packages/web-shell/client/adapters/transcriptToMessages.ts
+++ b/packages/web-shell/client/adapters/transcriptToMessages.ts
@@ -1537,6 +1537,7 @@ function daemonToolPreviewToArgs(
case 'subagent_delegation':
return {
subagent_type: preview.agentName,
+ ...(preview.teammateName ? { name: preview.teammateName } : {}),
prompt: preview.task,
...(preview.parentDelegationId
? { parentDelegationId: preview.parentDelegationId }
diff --git a/packages/web-shell/client/components/artifacts/AgentWorkflow.module.css b/packages/web-shell/client/components/artifacts/AgentWorkflow.module.css
index b4c5a9a9c52..b090a8018eb 100644
--- a/packages/web-shell/client/components/artifacts/AgentWorkflow.module.css
+++ b/packages/web-shell/client/components/artifacts/AgentWorkflow.module.css
@@ -59,8 +59,12 @@ button.node {
cursor: pointer;
}
-button.node:hover,
-button.node:focus-visible {
+button.node[aria-disabled='true'] {
+ cursor: default;
+}
+
+button.node:not(:disabled):hover,
+button.node:not(:disabled):focus-visible {
border-color: var(--primary);
outline: none;
box-shadow: 0 0 0 2px color-mix(in srgb, var(--primary) 18%, transparent);
@@ -128,6 +132,10 @@ button.node:focus-visible {
color: var(--success-color);
}
+.status[data-status='idle'] {
+ color: var(--success-color);
+}
+
.status[data-status='failed'],
.status[data-status='cancelled'] {
color: var(--error-color);
diff --git a/packages/web-shell/client/components/artifacts/AgentWorkflow.tsx b/packages/web-shell/client/components/artifacts/AgentWorkflow.tsx
index 738a6dd9640..19fbc920a30 100644
--- a/packages/web-shell/client/components/artifacts/AgentWorkflow.tsx
+++ b/packages/web-shell/client/components/artifacts/AgentWorkflow.tsx
@@ -1,6 +1,7 @@
import {
BotIcon,
CircleCheckIcon,
+ CircleDotIcon,
CirclePauseIcon,
CircleStopIcon,
CircleXIcon,
@@ -210,8 +211,11 @@ export function AgentWorkflow({
className={styles.node}
data-status={task.status}
style={positionStyle(layout.positions.get(task.id))}
- onClick={() => onOpenAgent?.(task)}
- disabled={!onOpenAgent}
+ onClick={() => {
+ if (!task.teamName) onOpenAgent?.(task);
+ }}
+ disabled={!onOpenAgent || Boolean(task.teamName)}
+ aria-disabled={task.teamName ? true : undefined}
title={task.description || task.label}
>
<span className={styles.nodeTitle}>
@@ -225,6 +229,7 @@ export function AgentWorkflow({
<span className={styles.nodeMeta}>
<span className={styles.status} data-status={task.status}>
{task.status === 'completed' && <CircleCheckIcon />}
+ {task.status === 'idle' && <CircleDotIcon />}
{task.status === 'running' && (
<LoaderCircleIcon className={styles.statusRunning} />
)}
diff --git a/packages/web-shell/client/components/panels/EnvironmentPanel.module.css b/packages/web-shell/client/components/panels/EnvironmentPanel.module.css
index c497364bec7..9a06df8d4b6 100644
--- a/packages/web-shell/client/components/panels/EnvironmentPanel.module.css
+++ b/packages/web-shell/client/components/panels/EnvironmentPanel.module.css
@@ -215,8 +215,8 @@ button.row:disabled {
text-align: left;
}
-.task:hover,
-.task:focus-visible {
+.task:not(:disabled):hover,
+.task:not(:disabled):focus-visible {
background: var(--accent);
outline: none;
}
@@ -226,6 +226,11 @@ button.row:disabled {
opacity: 0.55;
}
+.task[aria-disabled='true'] {
+ cursor: default;
+ opacity: 1;
+}
+
.taskIcon {
display: inline-flex;
flex: 0 0 auto;
@@ -246,6 +251,7 @@ button.row:disabled {
}
.agentName,
+.agentTask,
.taskName {
min-width: 0;
overflow: hidden;
@@ -253,6 +259,10 @@ button.row:disabled {
white-space: nowrap;
}
+.agentTask {
+ color: var(--muted-foreground);
+}
+
.taskName {
display: block;
}
@@ -294,6 +304,10 @@ button.row:disabled {
color: var(--success-color);
}
+.taskStatus[data-status='idle'] {
+ color: var(--success-color);
+}
+
.taskStatus[data-status='failed'] {
color: var(--error-color);
}
diff --git a/packages/web-shell/client/components/panels/EnvironmentPanel.test.tsx b/packages/web-shell/client/components/panels/EnvironmentPanel.test.tsx
index 9399e53112b..c5fcb7b1816 100644
--- a/packages/web-shell/client/components/panels/EnvironmentPanel.test.tsx
+++ b/packages/web-shell/client/components/panels/EnvironmentPanel.test.tsx
@@ -427,6 +427,42 @@ describe('EnvironmentPanel', () => {
expect(view.textContent).toContain('Review code');
});
+ it('shows an idle teammate and its assigned shared task', () => {
+ const onOpenAgent = vi.fn();
+ const view = mount({
+ agentTasks: [
+ {
+ kind: 'agent',
+ id: 'reviewer@review-team',
+ label: 'reviewer',
+ description: 'Reviewing authentication flow',
+ color: '#4ECDC4',
+ status: 'idle',
+ startTime: 1,
+ runtimeMs: 10,
+ isBackgrounded: false,
+ teamName: 'review-team',
+ teamTask: {
+ id: '1',
+ subject: 'Review authentication flow',
+ status: 'in_progress',
+ },
+ },
+ ],
+ onOpenAgent,
+ });
+
+ expect(view.textContent).toContain('reviewer');
+ expect(view.textContent).toContain('Review authentication flow');
+ expect(view.textContent).toContain('Idle');
+ expect(view.querySelector('[data-status="idle"]')).not.toBeNull();
+ const teammate = Array.from(view.querySelectorAll('ul button')).find(
+ (button) => button.textContent?.includes('reviewer'),
+ );
+ act(() => teammate?.click());
+ expect(onOpenAgent).not.toHaveBeenCalled();
+ });
+
it('shows a gray dot when the subagent has no configured color', () => {
const view = mount({
agentTasks: [
diff --git a/packages/web-shell/client/components/panels/EnvironmentPanel.tsx b/packages/web-shell/client/components/panels/EnvironmentPanel.tsx
index cb21c5b2a9b..7d219513b63 100644
--- a/packages/web-shell/client/components/panels/EnvironmentPanel.tsx
+++ b/packages/web-shell/client/components/panels/EnvironmentPanel.tsx
@@ -10,6 +10,7 @@ import {
BotIcon,
ChevronRightIcon,
CircleCheckIcon,
+ CircleDotIcon,
CirclePauseIcon,
CircleStopIcon,
CircleXIcon,
@@ -111,6 +112,7 @@ function taskStatusKey(status: DaemonSessionTaskWithWorkflowStatus['status']) {
function taskStatusIcon(status: DaemonSessionTaskWithWorkflowStatus['status']) {
if (status === 'completed') return <CircleCheckIcon />;
+ if (status === 'idle') return <CircleDotIcon />;
if (status === 'running' || status === 'pausing') {
return <LoaderCircleIcon className={styles.statusRunning} />;
}
@@ -130,7 +132,9 @@ function agentDisplayName(task: EnvironmentAgentTask): string {
}
function agentColorValue(color: string | undefined): string {
- return (color && AGENT_COLORS[color]) || 'var(--muted-foreground)';
+ if (!color) return 'var(--muted-foreground)';
+ if (/^#[\da-f]{6}$/i.test(color)) return color;
+ return AGENT_COLORS[color] || 'var(--muted-foreground)';
}
export function EnvironmentPanel({
@@ -349,8 +353,11 @@ export function EnvironmentPanel({
<button
type="button"
className={styles.task}
- disabled={!onOpenAgent}
- onClick={() => onOpenAgent?.(task)}
+ disabled={!onOpenAgent || Boolean(task.teamName)}
+ aria-disabled={task.teamName ? true : undefined}
+ onClick={() => {
+ if (!task.teamName) onOpenAgent?.(task);
+ }}
>
<span className={styles.taskLabel}>
{!isForkAgent(task) && (
@@ -376,6 +383,14 @@ export function EnvironmentPanel({
});
})()}
</span>
+ {task.teamTask && (
+ <span
+ className={styles.agentTask}
+ title={task.teamTask.subject}
+ >
+ {task.teamTask.subject}
+ </span>
+ )}
</span>
<span
className={styles.taskStatus}
diff --git a/packages/web-shell/client/customization.tsx b/packages/web-shell/client/customization.tsx
index 843824fa180..2f69579ecac 100644
--- a/packages/web-shell/client/customization.tsx
+++ b/packages/web-shell/client/customization.tsx
@@ -443,7 +443,7 @@ interface WebShellTaskBase {
export interface WebShellAgentTask extends WebShellTaskBase {
kind: 'agent';
- status: 'running' | 'paused' | 'completed' | 'failed' | 'cancelled';
+ status: 'running' | 'idle' | 'paused' | 'completed' | 'failed' | 'cancelled';
subagentType?: string;
isBackgrounded: boolean;
prompt?: string;
diff --git a/packages/web-shell/client/e2e/utils/mockDaemon.ts b/packages/web-shell/client/e2e/utils/mockDaemon.ts
index 1017e55e988..34c967dd08d 100644
--- a/packages/web-shell/client/e2e/utils/mockDaemon.ts
+++ b/packages/web-shell/client/e2e/utils/mockDaemon.ts
@@ -10,6 +10,7 @@ import {
type DaemonEvent,
type DaemonRestoredSession,
type DaemonSession,
+ type DaemonSessionAgentTaskStatus,
type DaemonSessionArtifact,
type DaemonSessionArtifactsEnvelope,
type DaemonSessionGroup,
@@ -63,6 +64,8 @@ export interface WebShellDaemonScenario {
supportedCommands?: Record<string, unknown>;
/** Tasks returned by `GET /session/:id/tasks` (workflow snapshots included). */
workflowTasks?: unknown[];
+ /** Agents returned by `GET /session/:id/agents`. */
+ agentTasks?: DaemonSessionAgentTaskStatus[];
/** Definitions served by `GET /session/:id/saved-workflows/:name`, keyed by name. */
savedWorkflowDetails?: Record<string, Record<string, unknown>>;
providers: DaemonWorkspaceProvidersStatus;
@@ -436,6 +439,7 @@ export function createWebShellDaemonScenario(
contextDelayMs: overrides.contextDelayMs,
supportedCommands: overrides.supportedCommands,
workflowTasks: overrides.workflowTasks,
+ agentTasks: overrides.agentTasks,
savedWorkflowDetails: overrides.savedWorkflowDetails,
providersDelayMs: overrides.providersDelayMs,
artifacts: overrides.artifacts ?? [],
@@ -809,6 +813,7 @@ function isDaemonPath(path: string): boolean {
/^\/session\/[^/]+\/goal\/?$/.test(path) ||
/^\/session\/[^/]+\/status\/?$/.test(path) ||
/^\/session\/[^/]+\/tasks\/?$/.test(path) ||
+ /^\/session\/[^/]+\/agents\/?$/.test(path) ||
/^\/session\/[^/]+\/saved-workflows\/[^/]+\/?$/.test(path) ||
/^\/session\/[^/]+\/mid-turn-message\/?$/.test(path) ||
/^\/session\/[^/]+\/mid-turn-messages(?:\/[^/]+)?\/?$/.test(path) ||
@@ -1039,6 +1044,7 @@ function isDaemonRoute(method: string, path: string): boolean {
return (
(method === 'GET' &&
/^\/session\/[^/]+\/(context|supported-commands|tasks)\/?$/.test(path)) ||
+ (method === 'GET' && /^\/session\/[^/]+\/agents\/?$/.test(path)) ||
(method === 'GET' &&
/^\/session\/[^/]+\/saved-workflows\/[^/]+\/?$/.test(path))
);
@@ -2004,6 +2010,15 @@ async function handleDaemonRoute(
});
return;
}
+ if (action === 'agents') {
+ await json(route, {
+ v: 1,
+ sessionId,
+ now: Date.now(),
+ tasks: scenario.agentTasks ?? [],
+ });
+ return;
+ }
if (action === 'saved-workflows') {
const detail = scenario.savedWorkflowDetails?.[extra];
await json(route, {
diff --git a/packages/web-shell/client/e2e/visuals/team-roster.spec.ts b/packages/web-shell/client/e2e/visuals/team-roster.spec.ts
new file mode 100644
index 00000000000..d3a3121ee31
--- /dev/null
+++ b/packages/web-shell/client/e2e/visuals/team-roster.spec.ts
@@ -0,0 +1,187 @@
+/**
+ * @license
+ * Copyright 2026 Qwen
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { expect, test } from '@playwright/test';
+import type { DaemonSessionAgentTaskStatus } from '@qwen-code/sdk/daemon';
+import {
+ assistantTextEvent,
+ createWebShellDaemonScenario,
+ turnCompleteEvent,
+ userTextEvent,
+} from '../utils/mockDaemon';
+import {
+ captureScreenshot,
+ gotoSession,
+ installScenario,
+ resolveBaseURL,
+ VISUAL_VIEWPORT,
+ type VisualTheme,
+} from './harness';
+
+test.use({ viewport: { ...VISUAL_VIEWPORT } });
+
+/**
+ * One teammate per lifecycle state the roster has to keep apart, plus one
+ * ordinary subagent as the control row.
+ *
+ * `idle` is the state this projection exists to represent: a teammate that has
+ * reported and is waiting for the next assignment is neither running nor
+ * finished, and collapsing it into either would hide the only thing a leader
+ * asks the roster — who is free right now. `completed` is the separate
+ * terminal state, and the shared-task column is what tells the two apart when
+ * both are otherwise quiet.
+ */
+const TEAMMATES: readonly DaemonSessionAgentTaskStatus[] = [
+ {
+ kind: 'agent',
+ id: 'scout-core@field-team',
+ label: 'scout-core',
+ description: 'Mapping the core package surface',
+ status: 'running',
+ startTime: Date.now() - 95_000,
+ runtimeMs: 95_000,
+ isBackgrounded: false,
+ teamName: 'field-team',
+ color: '#4ECDC4',
+ teamTask: {
+ id: '1',
+ subject: 'Map the core package surface',
+ status: 'in_progress',
+ },
+ recentActivities: [
+ {
+ name: 'read_file',
+ description: 'packages/core/src/agents/team/TeamManager.ts',
+ at: Date.now() - 4_000,
+ },
+ ],
+ },
+ {
+ kind: 'agent',
+ id: 'reviewer@field-team',
+ label: 'reviewer',
+ description: 'Waiting for the next assignment',
+ status: 'idle',
+ startTime: Date.now() - 148_000,
+ runtimeMs: 148_000,
+ isBackgrounded: false,
+ teamName: 'field-team',
+ color: '#FF6B6B',
+ teamTask: {
+ id: '2',
+ subject: 'Review the auth migration',
+ status: 'completed',
+ },
+ },
+ {
+ kind: 'agent',
+ id: 'writer@field-team',
+ label: 'writer',
+ description: 'Shut down after the handoff',
+ status: 'completed',
+ startTime: Date.now() - 210_000,
+ endTime: Date.now() - 30_000,
+ runtimeMs: 170_000,
+ isBackgrounded: false,
+ teamName: 'field-team',
+ color: '#FFD93D',
+ teamTask: {
+ id: '3',
+ subject: 'Write the migration notes',
+ status: 'completed',
+ },
+ },
+];
+
+/**
+ * The control row: an ordinary subagent with no `teamName`. The roster merges
+ * team rows and subagent rows into one list, so a capture without this row
+ * would not catch a change that made every row render as a teammate — the
+ * regression this projection is most likely to introduce, since both shapes now
+ * share one adapter.
+ */
+const SUBAGENT: DaemonSessionAgentTaskStatus = {
+ kind: 'agent',
+ id: 'agent-search-index',
+ label: 'general-purpose',
+ description: 'Searching the repository for prior art',
+ status: 'running',
+ startTime: Date.now() - 40_000,
+ runtimeMs: 40_000,
+ isBackgrounded: true,
+ subagentType: 'general-purpose',
+};
+
+function createTeamRosterScenario() {
+ return createWebShellDaemonScenario({
+ displayName: 'Migrate the auth service',
+ capabilities: {
+ features: ['session_events', 'session_agents'],
+ },
+ events: [
+ userTextEvent('Migrate the auth service to the new token store.', {
+ id: 1,
+ }),
+ assistantTextEvent(
+ 'Created team field-team with scout-core, reviewer and writer. ' +
+ 'scout-core is mapping the package surface now; reviewer has ' +
+ 'reported and is idle; writer finished and shut down.',
+ { id: 2 },
+ ),
+ turnCompleteEvent('prompt-team-roster-visual', { id: 3 }),
+ ],
+ agentTasks: [...TEAMMATES, SUBAGENT],
+ });
+}
+
+/**
+ * Team rows are status-only in WebShell: there is no in-process teammate
+ * transcript endpoint yet, so the panel deliberately disables them while the
+ * ordinary subagent keeps its existing detail action. Asserting that split is
+ * the point of this capture — a row that looks right but silently opens the wrong
+ * surface is the failure mode a screenshot alone would not catch.
+ */
+async function assertRosterSplit(page: import('@playwright/test').Page) {
+ const panel = page.getByTestId('environment-panel');
+ await expect(panel.locator('[data-status="running"]')).toHaveCount(2);
+ await expect(panel.locator('[data-status="idle"]')).toHaveCount(1);
+ await expect(panel.locator('[data-status="completed"]')).toHaveCount(1);
+
+ for (const teammate of TEAMMATES) {
+ const row = panel.locator('button', { hasText: teammate.label });
+ await expect(row).toHaveCount(1);
+ await expect(row).toHaveAttribute('aria-disabled', 'true');
+ }
+
+ // Shared-task ownership is the column that separates idle from completed.
+ await expect(panel.getByText('Review the auth migration')).toBeVisible();
+
+ const subagentRow = panel.locator('button', { hasText: 'general-purpose' });
+ await expect(subagentRow).toHaveCount(1);
+ await expect(subagentRow).toBeEnabled();
+}
+
+for (const theme of [
+ 'light',
+ 'dark',
+] as const satisfies readonly VisualTheme[]) {
+ test(`agent team roster ${theme}`, async ({ page }, testInfo) => {
+ const scenario = createTeamRosterScenario();
+ const daemon = await installScenario(
+ page,
+ scenario,
+ resolveBaseURL(testInfo),
+ );
+ await gotoSession(page, scenario, daemon, theme);
+
+ await page
+ .getByRole('button', { name: 'Toggle environment information' })
+ .click();
+
+ await assertRosterSplit(page);
+ await captureScreenshot(page, `agent-team-roster-${theme}`);
+ });
+}
diff --git a/packages/web-shell/client/e2e/web-shell.smoke.spec.ts b/packages/web-shell/client/e2e/web-shell.smoke.spec.ts
index 3a3017d6762..1ce4d3f9eb4 100644
--- a/packages/web-shell/client/e2e/web-shell.smoke.spec.ts
+++ b/packages/web-shell/client/e2e/web-shell.smoke.spec.ts
@@ -127,6 +127,47 @@ test('loads replayed transcript and connects to fake daemon @smoke', async ({
}
});
+test('shows Agent Team status and shared work in the environment panel @smoke', async ({
+ page,
+}, testInfo) => {
+ const scenario = createWebShellDaemonScenario({
+ capabilities: {
+ features: ['session_events', 'session_agents'],
+ },
+ agentTasks: [
+ {
+ kind: 'agent',
+ id: 'reviewer@review-team',
+ label: 'reviewer',
+ description: 'Reviewing authentication flow',
+ status: 'idle',
+ startTime: Date.now() - 3_000,
+ runtimeMs: 3_000,
+ isBackgrounded: false,
+ teamName: 'review-team',
+ color: '#4ECDC4',
+ teamTask: {
+ id: '1',
+ subject: 'Review authentication flow',
+ status: 'in_progress',
+ },
+ },
+ ],
+ });
+ const daemon = await installScenario(page, scenario, testInfo);
+
+ await gotoSession(page, scenario, daemon);
+ await page
+ .getByRole('button', { name: 'Toggle environment information' })
+ .click();
+
+ const panel = page.getByTestId('environment-panel');
+ await expect(panel).toContainText('reviewer');
+ await expect(panel).toContainText('Review authentication flow');
+ await expect(panel).toContainText('Idle');
+ await expect(panel.locator('[data-status="idle"]')).toBeVisible();
+});
+
test('branches from an earlier completed Assistant response and resumes the fork @smoke', async ({
page,
}, testInfo) => {
diff --git a/packages/web-shell/client/i18n.tsx b/packages/web-shell/client/i18n.tsx
index b3f26f8c85b..16fac409aa1 100644
--- a/packages/web-shell/client/i18n.tsx
+++ b/packages/web-shell/client/i18n.tsx
@@ -2885,6 +2885,7 @@ const EN: Messages = {
'tasks.moreAbove': (v) => `^ ${v?.count ?? 0} more above`,
'tasks.moreBelow': (v) => `v ${v?.count ?? 0} more below`,
'tasks.running': 'Running',
+ 'tasks.idle': 'Idle',
'tasks.pausing': 'Pausing',
'tasks.completed': 'Completed',
'tasks.failed': 'Failed',
@@ -6264,6 +6265,7 @@ const ZH: Messages = {
'tasks.moreAbove': (v) => `^ 上方还有 ${v?.count ?? 0} 个`,
'tasks.moreBelow': (v) => `v 下方还有 ${v?.count ?? 0} 个`,
'tasks.running': '运行中',
+ 'tasks.idle': '空闲',
'tasks.pausing': '暂停中',
'tasks.completed': '已完成',
'tasks.failed': '失败',