docs(handoff): add local↔cloud handoff documentation

src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx

@@ -0,0 +1,92 @@
+---
+title: Handoff from cloud to cloud
+description: >-
+  Send a follow-up to a cloud agent run after its sandbox shut down. Oz creates
+  a new execution on the same run and rehydrates the prior workspace state so
+  the agent picks up where it left off.
+sidebar:
+  label: "Cloud to cloud"
+---
+
+Hand off a cloud agent run to a fresh cloud execution when the original sandbox has shut down but you still want to push the same unit of work further. Oz creates a new execution on the same run id, reuses the same agent conversation, and rehydrates the prior execution's workspace state so the new agent picks up where the old one left off — not from scratch.
+
+This direction is the right move when:
+
+* A cloud agent finished and you want to send a follow-up after the sandbox has already torn down.
+* A scheduled or integration-triggered run completed and you want to keep iterating without losing context.
+* You want to continue an ambient agent task across multiple cloud executions while preserving the run as a single unit of work in the [management view](/agent-platform/cloud-agents/managing-cloud-agents/).
+
+## How cloud-to-cloud handoff works
+
+When you submit a follow-up to a cloud run, Oz routes the message based on the run's current state:
+
+* **Appended** - The run hasn't started yet, so the follow-up is appended to the prompt.
+* **Injected** - The current execution is still reachable, so the follow-up is injected into the live shared session.
+* **Requeued** - The sandbox has ended, so Oz creates a new execution on the same run.
+
+Cloud-to-cloud handoff is the **requeued** path. The user-facing effect is the same — you submit a follow-up and the run continues — but the underlying mechanics differ because the new execution starts on a fresh sandbox.
+
+## What the new execution receives
+
+Each cloud agent run captures a snapshot of its workspace at the end of its execution and uploads it to a per-execution prefix in storage (`snapshots/{run_id}/{execution_id}/`). When a new execution starts on the same run, Oz discovers the prior execution's snapshot and rehydrates from it.
+
+* **The same agent conversation** - The new execution writes to the same agent conversation id as the prior execution. From the user's perspective, the run is one continuous conversation across multiple sandboxes.
+* **The prior workspace state** - The prior execution's repository diffs (tracked and untracked) and any orphan files declared in its `snapshot_state.json` manifest are downloaded into the new sandbox and applied via `git apply` before the agent answers the follow-up.
+* **Stable run identity** - The run id, task id, and run metadata (creator, environment, schedule trigger, integration source) are preserved. Compute usage is recorded per execution but rolls up to the same run.
+
+The receiving agent's first turn applies the patches and reports any that failed. If a patch fails outright, the agent retries it with `git apply --3way` and only proceeds to the user's follow-up after every patch has been attempted.
+
+## Prerequisites
+
+* **An ended cloud agent run** - The run must have a `succeeded`, `failed`, `error`, `blocked`, or `cancelled` state and an associated agent conversation id. Runs with no conversation id (rare; mostly legacy) cannot be continued via handoff.
+* **A snapshot from the prior execution** - The agent driver uploads a snapshot at the end of every cloud agent run by default. If the prior execution didn't upload a snapshot (for example, the snapshot upload itself failed), the new execution still proceeds — it just starts without rehydrated workspace state.
+* **Access to the run** - You must have permission to submit follow-ups for the run. For team runs, this is normally any member of the team.
+
+## Sending a follow-up that triggers cloud-to-cloud handoff
+
+Cloud-to-cloud handoff is automatic. You don't choose between "send a follow-up" and "hand off" — you just send a follow-up, and Oz picks the routing.
+
+### From the Warp app
+
+1. **Open the ended cloud run.** Navigate to the run in the [management view](/agent-platform/cloud-agents/managing-cloud-agents/) or via the conversation panel.
+2. **Send your follow-up.** Type the next message into the conversation's input bar and submit it. Oz routes the message and, if the sandbox has ended, creates a new execution on the same run.
+3. **Watch the new execution.** A new execution appears in the run's history with its own start time. The conversation continues in the same thread, and the new sandbox's first tool calls are the rehydration patches.
+
+### From the Oz web app
+
+1. **Open the run at oz.warp.dev.** Click into the run from the **Runs** tab in the [Oz web app](/agent-platform/cloud-agents/oz-web-app/).
+2. **Send the follow-up.** Use the in-page input to send your next message. The same routing rules apply.
+
+### From an integration
+
+When a Slack-triggered or Linear-triggered cloud run ends, the integration can post follow-up messages into the same run. The server treats those follow-ups identically to ones sent from the Warp app — if the sandbox is gone, a new execution starts and rehydrates from the prior snapshot. See [Slack integration](/agent-platform/cloud-agents/integrations/slack/) and [Linear integration](/agent-platform/cloud-agents/integrations/linear/) for the integration-specific follow-up surfaces.
+
+## Inspecting handoff executions
+
+The [management view](/agent-platform/cloud-agents/managing-cloud-agents/) shows a single row per run, even when the run spans multiple executions. To inspect each execution:
+
+1. **Open the run detail.** Click the run row to open the conversation transcript.
+2. **Look at the execution timeline.** The run detail surfaces each execution separately. You can see which execution wrote each message and how long each execution ran.
+3. **Check the rehydration tool calls.** The first tool calls in each requeued execution are the patch-apply commands. If any failed, the agent's report appears in that execution's transcript.
+
+## Troubleshooting
+
+**My follow-up didn't trigger a new execution — it just appended to the prompt.**
+The original run hasn't started yet (state is still `queued` or `pending`). Oz appended your message to the prompt the new execution will pick up. This is the **appended** path, not handoff; the run hasn't ended yet so there's nothing to hand off from.
+
+**My follow-up injected into the live session instead of creating a new execution.**
+The original sandbox is still reachable. Oz injected your message into the live shared session — the **injected** path. This is the cheapest routing and avoids spinning up a fresh sandbox. You don't need to do anything; the agent will handle the follow-up in the existing execution.
+
+**The new execution started but no patches were applied.**
+The prior execution didn't upload a snapshot. This is rare but possible — snapshot upload is best-effort and can fail (for example, on a transient storage error). The new execution still proceeds with the same agent conversation, so the agent has the full transcript context even without the workspace state.
+
+**The run is in a terminal state with no conversation id and follow-ups are rejected.**
+Some very old runs predate the agent conversation model and cannot be continued via handoff. Start a new cloud agent run with the prompt you want and reference the prior run in the prompt if needed.
+
+## Related pages
+
+* [Handoff overview](/agent-platform/cloud-agents/handoff/) - What handoff is, the three directions, and what carries over.
+* [Handoff from local to cloud](/agent-platform/cloud-agents/handoff/local-to-cloud/) - Promote a local conversation to a cloud run.
+* [Handoff from cloud to local](/agent-platform/cloud-agents/handoff/cloud-to-local/) - Take over a cloud run inside the Warp terminal.
+* [Managing Cloud Agents](/agent-platform/cloud-agents/managing-cloud-agents/) - Find runs to send follow-ups to.
+* [Oz API and SDK](/reference/api-and-sdk/) - Programmatic follow-up submission via `POST /agent/runs/{runId}/followups`.

src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-local.mdx

@@ -0,0 +1,90 @@
+---
+title: Handoff from cloud to local
+description: >-
+  Pick up a cloud agent run inside the Warp terminal to verify, iterate, or
+  polish changes before shipping — without losing the cloud agent's
+  conversation history.
+sidebar:
+  label: "Cloud to local"
+---
+
+Hand off a cloud agent run to your local Warp terminal when you want to take over the work in person. The local session forks the cloud conversation in place, so you keep the full transcript, can ask follow-up questions, and can make manual edits inside the same flow the cloud agent was using.
+
+This direction is the right move when:
+
+* A cloud agent has done the heavy lifting and you want to verify the changes against your local checkout.
+* You want to make manual tweaks before approving a PR.
+* You want to ask follow-up questions to a cloud run interactively rather than waiting on another cloud round-trip.
+* A teammate triggered a cloud run from Slack or a schedule and you want to push it further from your machine.
+
+## What the local conversation receives
+
+When you continue a cloud run locally, the Warp client materializes a fork of the cloud conversation and opens it as a new pane next to your current one. The fork inherits:
+
+* **The full transcript** - Every user turn, agent turn, and tool call from the cloud run is visible in the local conversation.
+* **Conversation attachments** - Files attached during the cloud run remain available to reference locally.
+* **The agent's plan and artifacts** - Any plan documents, branch artifacts, or pull request links the cloud agent produced are accessible from the local view.
+
+Continuing a cloud run locally creates a fork rather than modifying the source. The original cloud run stays intact; your local conversation diverges from it as soon as you send a new prompt or make a manual edit. This matches [Conversation Forking](/agent-platform/local-agents/interacting-with-agents/conversation-forking/) behavior — the cloud run continues to live in the [management view](/agent-platform/cloud-agents/managing-cloud-agents/) and can be revisited later.
+
+:::note
+Cloud-to-local handoff brings the cloud agent's conversation and artifacts into your terminal. It does not automatically apply the cloud agent's uncommitted workspace changes to your local checkout — review the agent's PR or branch artifact to inspect and pull in those changes.
+:::
+
+## Prerequisites
+
+* **A cloud agent run to pick up** - The run can be in any state: still working, completed, failed, or canceled. The conversation must be cloud-synced (cloud agent runs are stored in the cloud by default).
+* **Cloud conversation storage enabled** - **Settings** > **Privacy** > **Store AI conversations in the cloud** must be on. Cloud agent conversations are always synced regardless of this setting, but storage must be on for the local fork to write back.
+* **Warp desktop app** - Cloud-to-local handoff continues the conversation inside the Warp app. From the [Oz web app](/agent-platform/cloud-agents/oz-web-app/), the equivalent action is **Open in Warp**, which launches Warp and starts the local fork.
+
+## Continuing a cloud run locally
+
+There are three entry points to continue a cloud run locally, depending on where you are in the workflow.
+
+### From the conversation details panel
+
+Use this when you're already inspecting a cloud run inside the Warp app.
+
+1. **Open the cloud run.** In the conversation panel or the [management view](/agent-platform/cloud-agents/managing-cloud-agents/), click the run you want to continue.
+2. **Open the conversation details panel.** Click the info button in the pane header to open the side panel that shows run metadata.
+3. **Click Continue locally.** Warp forks the conversation and opens it in a split pane next to the cloud run. The new pane is the local conversation; the cloud run pane remains on its side for reference.
+
+### From the ended-run tombstone
+
+Use this when a cloud run has just finished and you want to take over without leaving the pane.
+
+1. **Wait for the cloud agent to finish.** When the run ends, an ended-run tombstone card appears at the bottom of the pane with the run's metadata and artifacts.
+2. **Click Continue locally on the tombstone.** Warp forks the conversation into a split pane the same way the details panel does.
+
+### Via the `/continue-locally` slash command
+
+Use this when you want to continue a cloud conversation by name without first navigating to it.
+
+1. **Open the cloud conversation in the Warp terminal.** Run `/continue-locally` from inside the cloud conversation pane (or from a fresh pane if the conversation panel surfaces a recent run you want to pick up).
+2. **Confirm the fork.** Warp creates the local fork in a split pane and focuses the input so you can immediately type your follow-up.
+
+## Continuing in your next turn
+
+After the local fork opens, you can interact with the agent the same way you would in any local Warp conversation.
+
+1. **Send a follow-up prompt.** Anything you type in the local pane is now a turn in the forked conversation. The cloud run is unaffected.
+2. **Inspect the agent's workspace changes.** If the cloud agent produced a branch or PR artifact, the local conversation surfaces the same buttons (visible in the artifacts row). Click through to review the changes in your local checkout or in GitHub.
+3. **Make manual edits if needed.** The local conversation is a regular Warp Agent conversation. You can edit files, run commands, or use any other Warp surface alongside the agent.
+
+## Troubleshooting
+
+**The Continue locally button doesn't appear.**
+The button is hidden when AI features are disabled. Confirm in **Settings** > **AI** that AI is enabled and that you're signed in. The button is also hidden while a conversation is still in progress in a few states — wait for the agent to enter a stable state (working, completed, blocked, failed, or canceled) and the button should appear.
+
+**The local fork opens but doesn't show the full transcript.**
+The conversation data may not have finished syncing yet. Cloud agent conversations stream their state in near-real-time, so this is usually a few-second delay. If the transcript still looks truncated after a minute, refresh the conversation panel.
+
+**I'm in the Oz web app on a mobile device — there's no Continue locally button.**
+Continuing locally requires the Warp desktop app. On mobile or in a browser, you'll see **Open in Warp** instead. Clicking it deep-links into the desktop app and runs the same fork-and-open flow.
+
+## Related pages
+
+* [Handoff overview](/agent-platform/cloud-agents/handoff/) - What handoff is, the three directions, and what carries over.
+* [Handoff from local to cloud](/agent-platform/cloud-agents/handoff/local-to-cloud/) - The reverse direction, for promoting a local conversation to a cloud run.
+* [Cloud-synced conversations](/agent-platform/local-agents/cloud-conversations/) - How cloud conversations are stored, shared, and restored locally.
+* [Managing Cloud Agents](/agent-platform/cloud-agents/managing-cloud-agents/) - Find cloud runs to continue locally.