docs: correct the multi-agent orchestration documents

[Joob1n]

Summary

The Multi-agent orchestration group from #3522. Four documents were audited; three needed changes.

docs/agent-swarm.md documented a tool that no longer exists. The whole document was built around an agent_swarm tool taking items, a prompt_template and resume_run_ids. #2384 deleted packages/runtime/src/agent-swarm-tools.ts — where AGENT_SWARM_TOOL_NAME = 'agent_swarm' was defined — along with adaptive-swarm.ts, and replaced synchronous fan-out with asynchronous supervision over the Agent Graph. agent_swarm survives only as a tool-result kind on historical records, so a reader following this document would call a tool that is not in the catalog.

Rewritten around what swarm actually is now: an orchestration mode, not a tool. It is entered with /swarm on|off|status|<task> and changes four things — the system prompt, a guaranteed tool set that deliberately omits view_agent_graph, the durable agentSwarmAuthorization field on the Run header, and its own supervisor-wake rule. Items are ordinary child Sessions scheduled as graph work, and agent_swarm_status projects the same graph snapshot, where swarmId is the graphId.

Two questions a reader may reasonably ask, answered here so the diff does not have to carry them:

Was the tool deleted, or renamed and moved? Deleted. The file that defined it declared exactly one tool, the current catalog of 47 tools contains no agent_swarm, no tool anywhere accepts a batch items array, and every surviving mention is the result-kind type — nothing constructs one. agent_swarm_status is a different tool, not a rename: it takes no parameters and only projects a graph snapshot. The capability did move, onto the graph tools.

Is swarm now just a compatibility shell over graph? No. The execution machinery is entirely the graph — one scheduler, one ledger, one control plane. But swarm is a live mode over it, with its own guaranteed tool set, durable authorization record, and supervisor-wake trigger. Only the agent_swarm result kind is pure legacy, kept so old records stay readable.

The Agent Graph chapter had four smaller defects, corrected in both languages so translation_status: synced stays true:

• apps/desktop/src/main/agent-graph-ipc-main.ts does not exist. Graph change events travel through runtime-host-session-domains-ipc-main.ts as agentGraphChanged, and agent-graph-panel.tsx imports its types straight from @maka/runtime-host/client and @maka/runtime-host/protocol.
• apps/desktop/src/main/__tests__/graph-mode-host-contract.test.ts was deleted and has no successor.
• The comparison table described Agent Swarm as "one foreground tool call owns a bounded worker pool" — the removed synchronous model.
• The same table listed Agent Team beside four real mechanisms, but AgentTeam, agent_team and mailbox appear nowhere in the code. The row was removed and the section heading updated to match the rows that remain.

docs/side-conversation.md needs no change. Its unresolved symbols (excludeTurns, moveTabTo, receiveMovedTab, preserveOnClose, onBeforeClose) all sit inside the Codex Reference and Desktop Architecture Snapshot sections, which describe OpenAI Codex and carry their own inspection date.

Refs #3522

Verification

Claims in the rewritten document, each checked against the code:

Claim	Check	Result
agent_swarm tool existed and was deleted	git show 08b745028^:packages/runtime/src/agent-swarm-tools.ts | grep TOOL_NAME	AGENT_SWARM_TOOL_NAME = 'agent_swarm'; file deleted by that commit
no agent_swarm tool today	grep -n "name: 'agent" packages/core/src/tool-catalog.ts	agent_spawn, agent_list, agent_output, agent_swarm_status
/swarm grammar	packages/core/src/swarm-command.ts	status / on / off / run_once
prompt injection	packages/runtime/src/ai-sdk-backend.ts:1734	appended when mode === 'swarm'
guaranteed tool set	packages/runtime/src/ai-sdk-backend.ts:1670-1687	swarm set omits view_agent_graph; graph set includes it
durable authorization	packages/core/src/orchestration.ts:84,91, agent-run.ts:165	session_mode / turn_override / none
swarm wake rule	packages/runtime/src/stream-graph-coordinator.ts:1715	isSwarmCheckpointTransition
swarmId is graphId	packages/runtime/src/agent-swarm-status-tool.ts:79	swarmId: snapshot.graphId
status enums	same file, lines 28-70	9 item statuses; attention set is blocked/failed/aborted/cancelled
the missing IPC file	ls apps/desktop/src/main/agent-graph-ipc-main.ts	No such file
the missing test	find . -name 'graph-mode-host-contract*'	no matches
Agent Team absent	grep -rn "AgentTeam|agent_team|mailbox" packages/ apps/	no matches outside docs

Every packages/... and apps/... path in both reading maps was re-checked after the edit; all resolve.

Repository checks:

npm run format:check Checked 1597 files. No fixes applied.
npm run check:asf-source fail 0

No test covers prose and this PR changes no code, so no suite was added. npm test was not run.

AI use

Select exactly one:

• No generative tool made a substantive contribution
• Generative tooling made a substantive contribution

Tool(s) and scope: Claude Opus 5 via Claude Code — audited the four documents against the code, traced the swarm removal through git show, drafted the rewrite and the bilingual corrections. Every row in the table above was produced by running the listed command. The commit carries a Generated-by trailer.

Checklist

• Tests cover the change and fail without it
• Lint, format, typecheck and the affected suites pass locally

Does this PR entail a change in behavior?

• Yes — described under Summary above
• No

[Astro-Han]

LGTM.