docs: add native multi-agent fleet architecture

[yiliang114]

What this PR does

This PR replaces the earlier native multi-agent collaboration plan on this branch with a concrete target architecture for a herdr-like multi-agent experience built natively in Qwen Code. The document is traced against the current implementation at 002305b90 rather than derived from the previous proposal, and every structural claim carries a file reference.

The architecture splits today's fused 20-method Backend into three contracts: AgentSession (semantics — status, turn correlation, message delivery, approval requests), AgentRuntime (lifecycle — start, reattach, list, stop, kill, answer routing) and AgentSurface (presentation — visibility, focus, raw attach). TeamManager depends only on the first two and must never see a surface, a PTY, or a socket. Core defines the contracts; the CLI implements the supervised runtime and injects it.

The organising distinction is between a semantic channel (JSON over the supervisor socket, carrying status, turn text, approvals with call IDs and transcript deltas) and a terminal channel (PTY bytes, used only for raw attach). The semantic channel is authoritative. That is precisely what a screen-scraping multiplexer cannot provide, and it is why the semantic fleet layer can ship with no PTY infrastructure at all.

The document also records four settled product decisions, a component-by-component disposition table, an explicit MVP boundary, an eight-phase plan, and six refactors that land before any user-visible change.

Why it's needed

The previous plan on this branch sequenced all coordination work behind finishing the Agent View PTY stack (#7800–#7803). Tracing the code showed that ordering is inverted:

• tasks.ts and mailbox.ts are already file-based with a two-tier lock — an in-process async-mutex wrapping a proper-lockfile cross-process file lock over atomicWriteJSON. The coordination plane was built for multi-process access, so no second task database and no lock upgrade are needed.
• The leader already polls its own inbox (ensureLeaderInboxPolling / drainLeaderInbox), so teammate → leader messaging needs no new transport for a first release.
• AgentChatContent already supports a read-only mode and AgentMessage[] is documented append-only, so remote transcript rendering reuses the existing tab UI.
• TeamManager uses only five methods of TeamAgentHandle and four of nineteen event types, so the semantic seam is cheap to extract.

Conversely, InProcessBackend — the only backend wired up — implements six of Backend's display methods as no-ops. The interface is wrong for its primary implementer, and its optional getAgent?() escape hatch is what structurally forces teammates to stay in-process.

This PR also corrects the framing of the earlier plan. Herdr is a terminal multiplexer that hosts unmodified agents and infers their state from the screen; Qwen Code is one of the agents it hosts. Rebuilding a multiplexer inside Qwen Code is not the goal. Building the semantic coordination herdr structurally lacks — task ownership, reliable mailbox, turn-level correlation, explicit routable approvals — is.

Reviewer Test Plan

How to verify

1. Confirm the document's structural claims against the tree at 002305b90: the Backend concern table against packages/core/src/agents/backends/types.ts, the no-op display methods against InProcessBackend.ts:338–376, and the four consumed event types against TeamManager.ts:1486-1510.
2. Confirm the cross-process locking claim against packages/core/src/agents/team/tasks.ts (lock options, withTaskFileLock) and mailbox.ts (withInboxLock), including the in-source rationale that the file lock guards "writers in other agent processes".
3. Confirm the control-plane claim: packages/cli/src/agent-view/protocol.ts separates session / process / attach / ownership state and defines an answer control event carrying callId and an outcome enum, while supervisor-process.ts:113-147 implements only status, list, subscribe and shutdown.
4. Confirm the phase ordering is honest: phases 1–4 and refactors R1–R6 change no user-visible behaviour, and the MVP requires seven supervisor ops rather than the full nineteen.

Evidence (Before & After)

N/A — documentation only. No runtime code is changed by this PR.

Tested on

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

Environment (optional)

N/A — documentation only.

Risk & Scope

• Main risk or tradeoff: the plan deliberately declines to build a terminal multiplexer, so raw PTY attach ("enter the teammate's session") is deferred to phase 7. MVP inspection is transcript-based. If reviewers consider raw attach essential to the first release, the phase ordering should be revisited before implementation starts rather than after.
• Not validated / out of scope: no runtime implementation, no benchmark, and no change to existing behaviour. Heterogeneous CLI hosting and remote/SSH transport are permanently out of scope for this line of work. Herdr's own socket API reference was unreachable, so verbatim subcommand names in §1 come from a third-party guide and are marked indicative.
• Breaking changes / migration notes: none. This PR only replaces a planning document that has never been merged.

Linked Issues

Refs #8718. Re-frames #8804 and the #7800–#7803 stack. Related to #6383.

中文说明

本 PR 做了什么

本 PR 将本分支上原有的原生多 Agent 协作计划，替换为一份在 Qwen Code 内原生构建 herdr 式多 Agent 体验的具体目标架构文档。该文档基于 002305b90 的当前实现逐条追踪得出，而不是从此前的提案推导，每一处结构性论断都附有文件引用。

该架构把当前融合了 20 个方法的 Backend 拆成三个契约：AgentSession（语义层——状态、轮次关联、消息投递、审批请求）、AgentRuntime（生命周期——启动、重连、列举、停止、终止、审批路由）和 AgentSurface（展示层——可见性、聚焦、原始 attach）。TeamManager 只依赖前两者，且绝不接触 surface、PTY 或 socket。Core 定义契约，CLI 实现受管 runtime 并注入。

核心区分在于语义通道（经 supervisor socket 的 JSON，承载状态、轮次文本、带 call ID 的审批和 transcript 增量）与终端通道（PTY 字节，仅用于原始 attach）。语义通道是权威来源。这正是靠读屏推断状态的多路复用器无法提供的能力，也是语义 fleet 层可以完全不依赖 PTY 基础设施就先行落地的原因。

文档同时记录了四项已确定的产品决策、逐组件的处置表、明确的 MVP 边界、八个阶段的计划，以及六项在任何用户可见变更之前即可独立合入的重构。

为什么需要

本分支此前的计划把所有协作工作排在完成 Agent View PTY 堆栈（#7800–#7803）之后。追踪代码后发现这个顺序是反的：

• tasks.ts 与 mailbox.ts 已经是基于文件的，并采用两级锁——进程内 async-mutex 包裹 proper-lockfile 跨进程文件锁，底层是 atomicWriteJSON。协作平面本就是为多进程访问设计的，因此既不需要第二套任务数据库，也不需要升级锁。
• Leader 已经在轮询自己的收件箱（ensureLeaderInboxPolling / drainLeaderInbox），所以队友到 leader 的消息在首个版本中无需任何新传输层。
• AgentChatContent 已支持只读模式，且 AgentMessage[] 文档标明为仅追加，因此远程 transcript 渲染可直接复用现有标签页 UI。
• TeamManager 只用到 TeamAgentHandle 的五个方法和十九种事件中的四种，因此语义接缝的抽取成本很低。

反过来，唯一真正接入的 backend InProcessBackend，把 Backend 的六个展示方法实现成空操作。这个接口对它的主要实现者来说是错的，而其可选的 getAgent?() 逃生口正是从结构上迫使队友只能留在进程内的原因。

本 PR 也修正了此前计划的定位。Herdr 是承载未经修改的 Agent 的终端多路复用器，并通过读屏推断其状态；Qwen Code 是它承载的 Agent 之一。在 Qwen Code 内重建一个多路复用器并不是目标；构建 herdr 结构上缺失的语义协作——任务归属、可靠 mailbox、轮次级关联、显式可路由审批——才是。

Reviewer 测试计划

如何验证

1. 对照 002305b90 的代码核对文档的结构性论断：Backend 职责表对应 packages/core/src/agents/backends/types.ts，空操作展示方法对应 InProcessBackend.ts:338–376，四种被消费的事件类型对应 TeamManager.ts:1486-1510。
2. 核对跨进程锁的论断，对应 packages/core/src/agents/team/tasks.ts（锁选项、withTaskFileLock）与 mailbox.ts（withInboxLock），包括源码中「文件锁用于防护其他 agent 进程的写入者」这一说明。
3. 核对控制面论断：packages/cli/src/agent-view/protocol.ts 区分 session / process / attach / ownership 四类状态，并定义了携带 callId 与 outcome 枚举的 answer 控制事件；而 supervisor-process.ts:113-147 只实现了 status、list、subscribe 和 shutdown。
4. 核对阶段划分是否诚实：阶段 1–4 与重构 R1–R6 不改变任何用户可见行为，MVP 只需要七个 supervisor 操作，而非完整的十九个。

证据（修改前与修改后）

N/A——仅文档变更，本 PR 不改动任何运行时代码。

测试平台

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

环境（可选）

N/A——仅文档变更。

风险与范围

• 主要风险或取舍：该计划有意不构建终端多路复用器，因此原始 PTY attach（「进入队友会话」）被推迟到阶段 7，MVP 的查看方式基于 transcript。如果评审认为原始 attach 是首个版本的必需能力，应在实现开始之前而不是之后重新审视阶段顺序。
• 未验证 / 范围外：不包含运行时实现、不包含评测，也不改变现有行为。异构 CLI 承载与远程 / SSH 传输在本条工作线中永久排除。Herdr 自身的 socket API 参考文档无法访问，因此 §1 中的具体子命令名称来自第三方指南，并已标注为仅供参考。
• 破坏性变更 / 迁移说明：无。本 PR 只替换了一份从未合入的规划文档。

关联 Issue

参考 #8718。重新定位 #8804 与 #7800–#7803 堆栈。另关联 #6383。

[yiliang114]

Superseded by #8804, which includes a smaller design aligned with the implemented /coordinate v1. The staged Agent View and persistent-team architecture is no longer a prerequisite for native coordination, so this broader planning draft is being closed.

中文说明

该方案已由 #8804 替代；新 PR 包含一个与已实现 /coordinate v1 对齐的更小设计。分阶段建设 Agent View 和持久 Team 架构不再是原生协作的前置条件，因此关闭这个范围更大的规划草稿。

[yiliang114]

After re-evaluating this direction against the merged #8804, the broader Fleet architecture is no longer the next step. /coordinate is now the native Qwen coordination baseline, while any remaining process-orchestration work should be driven by a concrete gap rather than introduced as a prerequisite. Closing this planning draft as superseded.