diff --git a/src/content/docs/platform/environments/troubleshooting-environments.mdx b/src/content/docs/platform/environments/troubleshooting-environments.mdx
index fcf6e5f27..cb7c9336e 100644
--- a/src/content/docs/platform/environments/troubleshooting-environments.mdx
+++ b/src/content/docs/platform/environments/troubleshooting-environments.mdx
@@ -13,6 +13,14 @@ Setup commands run in a new container on every cloud agent run. Commands that de
 2. Use lockfile-based dependency commands such as `npm ci` when your project supports them.
 3. Run the complete setup from a clean container before updating the environment.
 
+## "Setup command #N timed out"
+
+A setup command that runs longer than 30 minutes fails environment setup. The error identifies the command number, command text, elapsed limit, and phase. If the phase is "resetting the working directory after the command", the timeout is 30 seconds instead.
+
+1. Inspect the named command and its output in the run's transcript. Check for an interactive prompt, a long-running server, or a stalled download.
+2. Make the command finish without user input. For example, use `sudo apt-get install -y` for package installation, and don't start a foreground development server during setup.
+3. Move lengthy dependency installation into your Docker image when possible, then test the revised setup from a fresh container and start a new run.
+
 ## `Permission denied` or `EACCES`
 
 Cloud agents run as a non-root user by default. A command fails when it needs root access or writes to a directory that the agent user cannot modify.
diff --git a/src/content/docs/platform/managing-cloud-agents.mdx b/src/content/docs/platform/managing-cloud-agents.mdx
index 1cade7354..cf3ae4e09 100644
--- a/src/content/docs/platform/managing-cloud-agents.mdx
+++ b/src/content/docs/platform/managing-cloud-agents.mdx
@@ -93,7 +93,9 @@ Where the agent was launched from. Common sources include:
 
 Warp uses a small set of statuses to help you quickly identify what needs attention:
 
-<table><thead><tr><th width="173.375">Status</th><th width="78.41973876953125">Icon</th><th>Description</th></tr></thead><tbody><tr><td><code>Working</code></td><td>N/A</td><td>in progress (may include queued / running states)</td></tr><tr><td><code>Blocked</code></td><td>🟨</td><td><p><em>(interactive only)</em></p><p><br />the conversation is waiting on user input or a required step</p></td></tr><tr><td><code>Canceled</code></td><td>⬜️</td><td>(interactive only)<br /><br />the interactive conversation was canceled before completion</td></tr><tr><td><a href="/factories/api-and-sdk/troubleshooting/errors/"><code>Failed / Errored</code></a></td><td>🔺</td><td>something went wrong (applies to both interactive and cloud agent runs)</td></tr><tr><td><code>Success</code></td><td>✅</td><td>completed successfully (applies to both interactive and cloud agent runs)</td></tr></tbody></table>
+<table><thead><tr><th width="173.375">Status</th><th width="78.41973876953125">Icon</th><th>Description</th></tr></thead><tbody><tr><td><code>Working</code></td><td>N/A</td><td>in progress (may include queued / running states)</td></tr><tr><td><code>Blocked</code></td><td>🟨</td><td>waiting on user input or a required step; an unattended third-party harness run can end in this state</td></tr><tr><td><code>Canceled</code></td><td>⬜️</td><td>(interactive only)<br /><br />the interactive conversation was canceled before completion</td></tr><tr><td><a href="/factories/api-and-sdk/troubleshooting/errors/"><code>Failed / Errored</code></a></td><td>🔺</td><td>something went wrong (applies to both interactive and cloud agent runs)</td></tr><tr><td><code>Success</code></td><td>✅</td><td>completed successfully (applies to both interactive and cloud agent runs)</td></tr></tbody></table>
+
+When an unattended [third-party harness](/platform/harnesses/) reports that it needs user input, the run ends as **Blocked** instead of waiting indefinitely. Inspect the status message and transcript to identify the missing input, then include that information in the prompt before starting another run.
 
 **Duration (for cloud agent tasks)**