docs(orchestration): add multi-agent orchestration pages

Add concept and run-how-to pages under cloud-agents/orchestration/.
Wire orchestration cross-references into deployment-patterns,
managing-cloud-agents, oz-web-app, and agent-notifications.

Co-Authored-By: Oz <oz-agent@warp.dev>

Author: hongyi-chen

src/content/docs/agent-platform/capabilities/agent-notifications.mdx

@@ -99,10 +99,22 @@ For **third-party CLI agents**, each agent requires a one-time setup. The proces
 
 If auto-install doesn't work or you're running an agent over SSH, Warp displays an installation-instructions chip in the terminal with setup steps you can follow directly.
 
+## Notifications in orchestrated runs
+
+In a [multi-agent orchestration](/agent-platform/cloud-agents/orchestration/), each child agent's lifecycle and messaging activity is surfaced to whoever is watching the parent.
+
+* **Lifecycle events from children** - when a child transitions to `succeeded`, `failed`, `errored`, `blocked`, or `cancelled`, the parent receives the event and the parent's session generates an in-app notification. If you are looking at a different tab, the toast notification identifies which child changed state.
+* **Messages from children** - when a child sends a message to the parent through the orchestration messaging API, the parent generates a **Request** notification so you can review the message and decide whether the parent should respond.
+* **Blocked children** - a child that blocks on user input (for example, a command approval request) raises a notification on the child's own session **and** propagates a `run_blocked` event to the parent. The parent can decide whether to wait, send a follow-up, or cancel the child.
+* **Mailbox grouping** - notifications from children are tagged with the parent's run so the mailbox can group an orchestration's notifications together.
+
+Notifications from cloud children are delivered to the user account that owns the orchestration. They do **not** fan out to every member of a team unless the parent run is configured for team-wide notification visibility.
+
 ## Related pages
 
 * [Desktop Notifications](/terminal/more-features/notifications/) - configure system-level notification permissions and troubleshoot delivery
 * [Managing Agents](/agent-platform/cloud-agents/managing-cloud-agents/) - monitor all agent conversations, filter by status, and inspect sessions
+* [Multi-agent orchestration](/agent-platform/cloud-agents/orchestration/) - parent/child model, lifecycle events, and the messaging API
 * [Third-Party CLI Agents](/agent-platform/cli-agents/overview/) - overview of supported CLI agents and Warp features
 * [Claude Code](/agent-platform/cli-agents/claude-code/) - setup and notification plugin installation
 * [Codex](/agent-platform/cli-agents/codex/) - setup and notification configuration

src/content/docs/agent-platform/cloud-agents/deployment-patterns.mdx

@@ -101,12 +101,7 @@ Use this when you want Oz to run agent workloads on Warp-managed infrastructure,
 
 #### Example recipe: fan-out parallel work (sharding)
 
-If a task is naturally divisible:
-
-* Launch multiple cloud agents via oz agent run-cloud, each with:
-  * A shard of the repo (directory/module ownership)
-  * A shard of the prompt (one responsibility)
-* Aggregate results (PRs, notes, plans) in whatever system you prefer.
+When a task is naturally divisible, use [multi-agent orchestration](/agent-platform/cloud-agents/orchestration/) to spawn one child per shard from a single parent run. The parent owns coordination and result aggregation; the children execute in parallel, each with their own repo subset, prompt, and (optionally) model. See [Running orchestrated agents](/agent-platform/cloud-agents/orchestration/multi-agent-runs/) for CLI, API, and slash command examples.
 
 #### Example recipe: same task across multiple models
 

src/content/docs/agent-platform/cloud-agents/managing-cloud-agents.mdx

@@ -99,3 +99,15 @@ In both _Personal_ and _All_ views, you can open the filter menu and filter by:
 * Status
 
 This is the fastest way to isolate "everything that failed today," "runs from Slack," or "what a specific teammate triggered via integrations."
+
+---
+
+### Orchestrated runs (parent and child)
+
+When a parent agent spawns one or more child agents through [multi-agent orchestration](/agent-platform/cloud-agents/orchestration/), the management view renders the hierarchy:
+
+* **Parent rows** include a child count chip showing how many children the parent has spawned and how many are still running.
+* **Child rows** appear nested under their parent and inherit a reference to the parent's run for quick navigation.
+* **Filtering** by parent: open any parent row to drill into a view scoped to its descendants.
+
+Each child is a full Oz run, so credit usage, status, transcript, and artifacts are all available from the same row click as any other run. The parent row's status reflects only the parent's own work — a parent can finish successfully while a child is still running or has failed, so check the child rows separately when verifying that an orchestration completed.

src/content/docs/agent-platform/cloud-agents/orchestration/index.mdx

@@ -0,0 +1,112 @@
+---
+title: Multi-agent orchestration
+description: >-
+  Coordinate parent and child agents across local and cloud runs. Spawn,
+  message, and subscribe to lifecycle events to build supervisor/worker,
+  fan-out, critic, DAG, and swarm patterns.
+sidebar:
+  label: "Orchestration"
+---
+
+Multi-agent orchestration lets one agent spawn and coordinate other agents to parallelize work, delegate specialized tasks, or check each other's output. Every primitive — spawning a child, sending a message, subscribing to lifecycle events — is exposed as a public REST endpoint on the [Oz Platform](/agent-platform/cloud-agents/platform/), so the same patterns work from the Warp app, the [Oz CLI](/reference/cli/), and any system that can call the [Oz API](/reference/api-and-sdk/).
+
+This page covers the orchestration model and the patterns it supports. For how to start an orchestrated run, see [Running orchestrated agents](/agent-platform/cloud-agents/orchestration/multi-agent-runs/).
+
+## The parent/child model
+
+An orchestrated workflow always has one **parent agent** and one or more **child agents**.
+
+* **Parent agent** - the agent that decides what work needs to be done, spawns child agents, and (optionally) merges their results. The parent is just an Oz agent; any Oz agent can become a parent the first time it spawns a child.
+* **Child agent** - an Oz agent spawned by a parent with its own prompt, environment, and (optionally) a different model or harness. A child can spawn its own children, so orchestrations are arbitrarily deep.
+
+The parent and child each have an independent **run** with its own lifecycle, transcript, and credit usage. The child run records its parent in `parent_run_id` so the management view, API, and web app can render the hierarchy.
+
+### Where each side can run
+
+The parent and child don't have to run in the same place. Orchestration supports four combinations:
+
+* **Local → local** - A [Warp Agent](/agent-platform/local-agents/overview/) conversation in the desktop app spawns child Warp Agent conversations on the same machine. Useful for dogfooding orchestration patterns without spinning up cloud infrastructure.
+* **Local → cloud** - A local parent spawns one or more cloud children that run in [environments](/agent-platform/cloud-agents/environments/) on Warp-hosted or self-hosted infrastructure. The parent can keep working while children execute in parallel.
+* **Cloud → cloud** - A cloud parent spawns cloud children. This is the canonical pattern for review swarms, large fan-outs, and any orchestration triggered from Slack, Linear, a schedule, or the API.
+* **Cloud → local** - Less common, but supported when a cloud parent needs to hand off a task to a local Warp Agent for human-in-the-loop review.
+
+Children can also use a different [harness](/agent-platform/cli-agents/overview/) than the parent. A parent Warp Agent can spawn Claude Code or Codex children, and vice versa.
+
+## Lifecycle events
+
+Each run emits lifecycle events that the parent (or any subscriber) can react to. The server records every event in an append-only log; the parent receives events in real time over SSE and can also poll the event log for catch-up.
+
+The supported event types are:
+
+* **`run_in_progress`** - the run started executing (or restarted after being paused or blocked).
+* **`run_succeeded`** - the run completed successfully.
+* **`run_failed`** - the run hit a terminal failure.
+* **`run_errored`** - the run encountered an error during startup or execution. Includes a `stage` (`startup` or `runtime`) and an error reason on the event payload.
+* **`run_blocked`** - the run is waiting on a user action (for example, command approval, permission request, or `ask_user_question`).
+* **`run_cancelled`** - the run was cancelled before reaching a terminal state.
+
+The parent's harness sees these events as inputs and decides what to do next: keep waiting, send a follow-up message, spawn a replacement, or finish.
+
+:::note
+Lifecycle subscription is opt-in per child. When the parent calls the spawn tool, it passes an optional `lifecycle_subscription` list that filters which event types the parent wants to receive. Omit it to subscribe to all event types.
+:::
+
+## Messaging between agents
+
+The parent and children communicate through a per-run inbox. Messages have a sender run, one or more recipient runs, a subject, and a body.
+
+* The sender writes to `POST /agent/messages` with `to`, `subject`, `body`, and `sender_run_id`.
+* The recipient sees the message in its inbox; the parent receives a `MessagesReceivedFromAgents` input the next time it runs.
+* Messages are durable. A child that wakes up after the parent sent a message still receives the inbox contents.
+
+Messages are intentionally lightweight — they are not streamed transcripts. Use them for handoffs, status updates, and final results, not for piping a full conversation back to the parent.
+
+## Common patterns
+
+Orchestration primitives are general-purpose. Teams typically compose them into a handful of recurring patterns.
+
+### Supervisor / worker
+
+A parent supervisor agent breaks the task into a queue of work items, spawns worker children to claim and complete each item, and writes a summary when the queue is empty. Use this when the task is naturally divisible and you want a single agent to own coordination.
+
+### Fan-out / fan-in
+
+The parent spawns N children in parallel, each with a sharded prompt (one module, one file set, one test target, one model), then waits for all of them to complete and merges their results. Use this for large refactors, repo-wide migrations, or running the same task across multiple targets.
+
+### Critic / verifier
+
+The parent (the "writer") proposes a solution, then spawns a critic child to review it. The critic returns notes; the writer revises; the cycle repeats until the critic approves or a budget is exhausted. Useful when correctness matters more than throughput.
+
+### Review swarm (cloud → cloud)
+
+A scheduled or webhook-triggered parent spawns one cloud child per open pull request to run reviews in parallel. Each child posts its findings as a comment and exits. The parent fans in the results and posts a summary back to the triggering system.
+
+### DAG
+
+The parent encodes a directed acyclic graph of subtasks where some nodes depend on the outputs of others. It spawns ready nodes, waits on their lifecycle events, and spawns dependents as upstream nodes complete. Use this when the workflow has explicit ordering constraints (build → test → deploy, for example).
+
+### Swarm
+
+A flat group of peer agents discover each other through the messaging API and coordinate without a strict hierarchy. The parent acts more like a coordinator than a supervisor. Use sparingly — swarms are powerful but harder to debug than hierarchical patterns.
+
+## Approval mode
+
+When an agent runs in `orchestrate` mode (set by the `/orchestrate` slash command or the API's `mode: orchestrate` field), the agent **proposes** an orchestration plan and waits for approval before spawning any children. This gives you a chance to review the breakdown — number of children, prompts, environments, parallelism — before paying for it. Once you approve, the parent starts spawning children.
+
+`orchestrate` mode is distinct from `plan` mode. A plan-mode agent produces a written plan for *itself* to execute. An orchestrate-mode agent produces a plan for itself plus a fleet of children.
+
+## Observability
+
+Because every parent and child is a normal Oz run, all existing observability surfaces work without changes:
+
+* **[Managing cloud agents](/agent-platform/cloud-agents/managing-cloud-agents/)** - parent and child rows appear in the management view with the parent rendered above its children.
+* **[Oz web app](/agent-platform/cloud-agents/oz-web-app/)** - the Runs page renders the hierarchy and lets you open any run's transcript.
+* **[Oz API](/reference/api-and-sdk/)** - `GET /agent/runs?parent_run_id=...` lists a parent's children; `GET /agent/runs/{runId}` returns `parent_run_id` on each run.
+* **[Agent notifications](/agent-platform/capabilities/agent-notifications/)** - lifecycle and message events from children show up in the parent's notification mailbox.
+
+## Related pages
+
+* [Running orchestrated agents](/agent-platform/cloud-agents/orchestration/multi-agent-runs/) - how to start an orchestrated run from the CLI, slash command, web app, or API
+* [Oz API and SDK](/reference/api-and-sdk/) - REST endpoints for messages, events, and runs
+* [Cloud agents overview](/agent-platform/cloud-agents/overview/) - what a cloud agent run is and how it fits into the Oz Platform
+* [Deployment patterns](/agent-platform/cloud-agents/deployment-patterns/) - higher-level deployment models that orchestration composes with