docs(orchestration): rebase on main, address review, refresh for launch state

Refreshes PR #84 with a single commit that:

* Adds two new orchestration pages (concept + how-to) describing the launched
  multi-agent orchestration model.
* Updates four existing pages (agent-notifications, deployment-patterns,
  managing-cloud-agents, oz-web-app) with orchestration cross-references that
  describe surfaces accurately.

Matthew's review (cephalonaut):

* Child agents do not spawn their own children today; orchestrations are one
  level deep.
* Documents the four execution combinations including cloud -> cloud-local.
* Rewrites /orchestrate vs /plan: both flows require user approval before
  children launch, and the agent considers orchestration during /plan and
  surfaces an inline orchestration config block on the plan card.
* Replaces 'child agent status card above the agent input' with the orchestration
  pill bar that ships in the agent view pane header.
* Rewrites 'Notifications in orchestrated runs' to reflect that in-app
  notifications fire on the parent's conversation only (child conversations
  are excluded from the toast stream and the notification mailbox).

Rachael's review (rachaelrenk):

* Tightens the Common patterns intro to directly frame the H3 list.

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

Author: hongyi-chen

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

@@ -99,10 +99,21 @@ 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/), the parent agent and each child agent are separate conversations. Today, in-app notifications fire on the parent's conversation only: child agent conversations are excluded from the toast stream and the notification mailbox so the mailbox doesn't get cluttered with per-child status churn.
+
+That means:
+
+* **Toasts and the mailbox** - watch the parent's conversation for `Complete`, `Request`, and `Error` notifications.
+* **Per-child state** - use the orchestration pill bar above the agent view header (in the Warp app) or the parent's **Sub-agents** tab on the [Runs page](https://oz.warp.dev/runs) (in the Oz web app) to see each child's live status. Both surfaces update as children transition through `INPROGRESS`, `SUCCEEDED`, `BLOCKED`, `FAILED`, `ERROR`, and `CANCELLED`.
+* **Blocked children** - if a child blocks on user input (for example, a command approval request), open that child from the pill bar to resolve the block. The parent's transcript also reflects the child's `BLOCKED` state so the parent can wait, send a follow-up, or cancel the child.
+
 ## 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, run state transitions, and the orchestration pill bar
 * [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 agent 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 slash command, CLI, web app, and API examples.
 
 #### Example recipe: same task across multiple models
 

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

@@ -100,9 +100,22 @@ In both _Personal_ and _All_ views, you can open the filter menu and filter by:
 
 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 parent and each child are tracked as separate runs. Where you see them depends on the surface:
+
+* **Local children in the Warp app** - while you're viewing the parent agent, an orchestration pill bar above the agent view header shows one pill per child with a live status badge. Click a child pill to switch the pane to that child's conversation in place; click the parent pill - or the breadcrumb that replaces the pill bar while you're viewing a child - to return. Local children don't appear as separate rows in the management view list.
+* **Cloud children in the Warp app** - appear in the management view list as their own rows alongside the parent and other runs. Filter by source, status, or creator to isolate them.
+* **Cloud children in the [Oz web app](/agent-platform/cloud-agents/oz-web-app/)** - grouped under the parent's row on the Runs page, and surfaced together inside the parent's detail pane on a **Sub-agents** tab.
+
+The parent's own status reflects only its work - a parent can finish successfully while a child is still running or has failed. To verify that an orchestration completed, check each child individually from the pill bar (in the Warp app) or the **Sub-agents** tab (in the Oz web app).
+
 ## Related pages
 
 * [Cloud agents overview](/agent-platform/cloud-agents/overview/) — What cloud agents are and when to use them.
+* [Multi-agent orchestration](/agent-platform/cloud-agents/orchestration/) — Parent/child model, run state transitions, and common orchestration patterns.
 * [Viewing cloud agent runs](/agent-platform/cloud-agents/viewing-cloud-agent-runs/) — Open and inspect a remote cloud agent run.
 * [Handoff between local and cloud agents](/agent-platform/cloud-agents/handoff/) — Move agent work between local and cloud, or continue a finished cloud run.
 * [Oz web app](/agent-platform/cloud-agents/oz-web-app/) — Manage runs and schedules from any browser.

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

@@ -0,0 +1,107 @@
+---
+title: Multi-agent orchestration
+description: Coordinate a parent agent and its direct child agents across local and cloud runs to build supervisor/worker, fan-out, critic, DAG, and swarm workflows on the Oz Platform.
+sidebar:
+  label: "Orchestration"
+---
+
+Multi-agent orchestration lets one agent spawn and coordinate other agents to parallelize work, delegate specialized tasks, or verify another agent's output. The parent/child model works from the Warp app, the [Oz CLI](/reference/cli/), and the [Oz API](/reference/api-and-sdk/), and supports local, cloud, and mixed execution.
+
+This page covers the orchestration model and the patterns it supports. To learn 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. Any agent can become a parent the first time it spawns a child.
+* **Child agent** - an agent spawned by a parent with its own prompt, environment, and (optionally) a different model or agent runtime. A child runs its own work and reports back; it does not spawn its own children.
+
+Orchestrations today are exactly one level deep: a parent and its direct children. The Warp app, the [Oz web app](/agent-platform/cloud-agents/oz-web-app/), and the [Oz API](/reference/api-and-sdk/) render that single level. The parent and each child each have an independent **run** with its own lifecycle, transcript, conversation, and credit usage.
+
+### Where parent and child agents 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 trying 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 keeps working while children execute in parallel.
+* **Cloud → cloud** - a cloud parent spawns cloud children that each run in their own environment. This is the canonical pattern for review swarms, large fan-outs, and any orchestration triggered from Slack, Linear, a schedule, or the API.
+* **Cloud → cloud-local** - a cloud parent spawns children that run inside the parent's own cloud environment, rather than each child getting its own environment. Useful when children need to share state with the parent (a filesystem, a long-running process, a shell session) or when spinning up an environment per child would be wasteful.
+
+Children can also run with a different agent runtime than the parent. A parent running with the default Warp Agent can spawn children that run with [Claude Code](/agent-platform/cli-agents/claude-code/) or [Codex](/agent-platform/cli-agents/codex/), and vice versa.
+
+## Run state transitions
+
+Each run progresses through a small set of states. The parent observes these transitions to decide what to do next - keep waiting, send a follow-up, spawn a replacement, or finish.
+
+The main user-visible states a child run can reach are:
+
+* **`INPROGRESS`** - the run is actively executing (or has restarted after being blocked).
+* **`SUCCEEDED`** - the run completed successfully.
+* **`FAILED`** - the run hit a terminal failure.
+* **`BLOCKED`** - the run is waiting on a user action (for example, command approval or a permission request).
+* **`ERROR`** - the run encountered an error during startup or execution.
+* **`CANCELLED`** - the run was cancelled before reaching a terminal state.
+
+Track run state transitions in these places:
+
+* **The parent's transcript** - the parent agent receives child state transitions as it runs and reflects them in its own conversation.
+* **The orchestration pill bar** - in the Warp desktop app, while you're viewing the parent agent, a horizontal pill bar above the agent view header shows the parent on the left and one pill per child. Each pill displays the child's name and a status badge that updates live. Click a pill to switch the pane to that child's conversation in place; click the parent pill to switch back.
+* **The Oz web app** - cloud children appear under the parent on the [Runs page](https://oz.warp.dev/runs) and in the parent's **Sub-agents** tab, with their status updating live.
+* **The Oz API** - `GET /agent/runs/{runId}` returns the latest state of any run, and `GET /agent/runs?ancestor_run_id=PARENT_RUN_ID` lists every descendant in one call.
+
+## Messaging between agents
+
+The parent and children can exchange short, durable messages - handoffs, status updates, and final results. Use messages for coordination signals, not for piping full transcripts around: the parent's prompt to the child and the child's final output carry the work itself.
+
+## Common patterns
+
+The following patterns show common ways to structure parent and child agents, depending on whether you need parallel execution, review, dependency ordering, or loose coordination.
+
+### 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 state transitions, 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 messaging 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
+
+Two slash commands surface orchestration in the Warp app, and both require explicit user approval before any children launch:
+
+* **`/orchestrate`** asks the agent to apply orchestration to the task. The agent proposes a breakdown - number of children, prompts, environments, parallelism - and waits for approval. The API equivalent is setting `mode: orchestrate` on `POST /agent/runs`.
+* **`/plan`** asks the agent to research and produce a plan for a complex task. The agent always considers orchestration while planning, and proposes it as part of the plan when the work would benefit. When orchestration is part of the plan, the plan card surfaces an inline **orchestration config** block above the plan with model, harness, environment, host, and parallelism pickers; you can adjust the config and then approve the plan to start spawning children. The API equivalent is `mode: plan`.
+
+In both cases, approval is required before the parent launches children. Approving an orchestration also approves the run-wide config (model, harness, environment, host) that every child inherits unless the parent overrides it per child.
+
+## Observability
+
+Because every parent and child is tracked as its own conversation or run, the existing observability surfaces work without changes:
+
+* **[Managing cloud agents](/agent-platform/cloud-agents/managing-cloud-agents/)** - in the Warp app, the orchestration pill bar above the agent view header lets you switch between the parent and each child while you're viewing the parent. Cloud children also appear as their own rows in the management view list.
+* **[Oz web app](/agent-platform/cloud-agents/oz-web-app/)** - the Runs page groups cloud children under the parent's row, and the parent's detail pane adds a **Sub-agents** tab.
+* **[Oz API](/reference/api-and-sdk/)** - list every descendant of a parent in one call and fetch any run with its conversation, transcript, and artifacts. See [Running orchestrated agents](/agent-platform/cloud-agents/orchestration/multi-agent-runs/#retrieving-conversations-and-artifacts).
+* **[Agent notifications](/agent-platform/capabilities/agent-notifications/)** - in-app notifications fire on the parent agent's conversation only. Use the pill bar or the **Sub-agents** tab to drill into a specific child.
+
+## 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 runs, conversations, and artifacts.
+* [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.