# REMOTE-172: Requested-command-style setup UI for Cloud Mode environments
## Summary
Cloud Mode should show environment setup as part of the agent conversation instead of making startup commands feel like unrelated terminal activity. When a cloud agent run starts, the user should immediately see their submitted prompt, clear environment startup progress, and collapsible rows for any setup commands that run before the first agent response.
The desired outcome is a Cloud Mode startup experience that is readable, debuggable, and consistent with the requested-command UX used elsewhere in Agent Mode.
## Problem
Cloud Mode environments can execute startup commands before the agent sends its first response. Without a dedicated UI, those commands can obscure the user's original request, leak command text into the prompt/input area, generate unrelated passive suggestions, or look like ordinary terminal blocks rather than setup work performed for the cloud agent.
Users need to understand that Warp is preparing the environment, what commands ran, whether those commands succeeded, and how to inspect details when setup fails or looks slow.
## Goals
- Preserve the initial user request in the conversation while the cloud agent environment starts.
- Show startup progress and setup commands in a visually cohesive Agent Mode surface.
- Make each environment startup command inspectable without overwhelming the default view.
- Clearly communicate running, succeeded, failed, cancelled, and authentication-required states.
- Avoid treating environment setup commands as normal user-entered terminal commands.
- Avoid leaking remote setup-command input state into the local visible prompt.
- Keep the old Cloud Mode setup UI available when the rollout flag is disabled.
## Non-goals
- Changing how cloud environments are created or which startup commands run.
- Allowing users to edit, approve, reject, or re-run environment startup commands from this UI.
- Replacing the existing requested-command UX for agent-requested commands.
- Changing cloud agent scheduling, task dispatch, capacity limits, or billing behavior.
- Providing a Figma-perfect redesign of all Cloud Mode loading and details-panel surfaces.
## Figma / design references
Figma: none provided.
Reference issue: https://linear.app/warpdotdev/issue/REMOTE-172/use-requested-command-ux-for-create-environment-like-init
## User experience
### Entry and initial prompt
- When the user starts a Cloud Mode run with an initial prompt, the cloud agent view should show that prompt as a user query block as soon as the run is dispatched.
- The initial prompt block should use the same user-query visual treatment as Agent Mode: user avatar/display name, bold prompt text, and normal Agent Mode spacing.
- If the cloud agent is cancelled before producing an exchange, the prompt block should show a simple `Cancelled` state.
- If the cloud agent requires GitHub authentication before producing an exchange, the prompt block should show a simple `Auth required` state.
- If the cloud agent fails before producing an exchange, the prompt block should show a simple `Failed` state.
- The first real AI exchange should not duplicate the same initial prompt/header when an optimistic initial prompt block was already inserted for the live startup flow.
- Historical replay should remain faithful to persisted conversation data and must not suppress the first AI block query solely because the new live startup UI exists.
### Startup progress
- While Warp is waiting for the cloud agent session to become ready, the status surface should show a shimmering progress message.
- Progress text should map to the known startup phase:
  - `Connecting to Host (Step 1/3)` before the task is claimed.
  - `Creating Environment (Step 2/3)` after the task is claimed but before the harness starts.
  - `Starting Environment (Step 3/3)` after the harness starts but before the shared session is ready.
- After the shared session is ready but before the first agent exchange arrives, the status surface should show `Setting up environment`.
- Cloud Mode tips may appear below these progress messages when available.
- In the new setup flow, progress should be shown in the Agent Mode status surface instead of covering the tab with the legacy full-screen loading screen.
### Startup command grouping
- Startup commands that run before the first cloud-agent exchange should be grouped under a single setup summary row.
- The summary row should say `Running startup commands...` while the cloud agent is still before the first exchange.
- The summary row should say `Ran startup commands` once the cloud agent has moved past the pre-first-exchange setup phase.
- The summary row should include a chevron that communicates whether startup command rows are expanded or collapsed.
- Clicking the summary row should toggle the visibility of startup command rows.
- Startup command rows should default to expanded during setup so users can see what is happening.
- Once the first agent exchange is appended, startup command rows should automatically collapse.
- Users can expand the summary row again after collapse to inspect the commands.
### Individual startup command rows
- Each startup command should render as a compact requested-command-style row before the corresponding terminal command block.
- A running startup command should show a running/progress icon.
- A completed startup command with a successful exit code should show a success/check icon.
- A completed startup command with a non-success exit code should show a failure icon.
- When collapsed, the row should display the command text in a monospace style.
- When expanded, the row should display `Viewing command detail` and reveal the underlying terminal command block/output.
- Clicking a startup command row should toggle only that command's detail visibility.
- Startup command output should be hidden by default behind the row, but must remain available when the user expands the row.
- Startup command rows should update their status when the backing command completes.
### Terminal blocks and input state
- Environment startup command blocks should not appear as ordinary user terminal blocks by default.
- Startup command blocks should be marked as setup commands so they can be hidden, shown, and excluded from unrelated terminal features.
- The visible prompt/input should not be populated by remote setup-command text while the cloud agent is in the pre-first-exchange setup phase.
- Remote input mode changes caused by environment setup should not force the visible local input mode to change while the cloud agent is in the pre-first-exchange setup phase.
- Passive prompt/code suggestions should not be generated for environment startup command completion.
- Cloud Mode sessions should generally suppress passive suggestions for agent conversation output so startup and cloud-agent internals do not create irrelevant suggestions.
### Parent terminal entry block
- When Cloud Mode is started from an existing terminal session, the parent terminal should receive a cloud-agent entry block only after the agent run is dispatched.
- Entering Cloud Mode and exiting without sending a prompt should not leave a persistent `New cloud agent` entry block behind.
- The entry block should show the cloud conversation title when available and fall back to `New cloud agent`.
- The entry block should show a status detail when relevant:
  - `Starting environment...` while waiting for the session.
  - `Agent is working on task` once the agent is running.
  - `Agent failed` on failure.
  - `Authentication required` when GitHub auth is required.
  - `Cancelled` when cancelled.
- The entry block icon should reflect the run state: cloud icon for normal/running, clock/loading for startup, warning for failure, info for auth, and cancelled icon for cancellation.
- Clicking the entry block should navigate back into the Cloud Mode view.
### Completion, failure, auth, and cancellation
- When the cloud agent session becomes ready, Warp should join the shared session and continue showing setup status until the first exchange arrives.
- When the agent produces the first exchange, the startup-command summary should switch from running to completed language and command details should collapse.
- If startup fails before the session is ready, the UI should preserve the initial prompt and show the failure state.
- If GitHub authentication is required, the UI should preserve the initial prompt and show the auth-required state.
- If the user cancels the run before the first exchange, the UI should preserve the initial prompt and show the cancelled state.
- Cloud-agent details UI should still auto-open when task/session data is available, both for local Cloud Mode and shared ambient sessions.
### Shared ambient sessions and ended conversations
- Joining an existing cloud-agent shared session should mark the terminal as an ambient-agent session and use cloud-agent-specific behavior.
- For shared ambient sessions, ended conversations should show a conversation-ended tombstone once, including under the new setup flow.
- Historical conversation replay must not prematurely insert the ended tombstone.
- Ending a shared ambient session should preserve the shareable object needed for the share dialog when appropriate.
- Session-ended internal-server-error toasts that are specific to normal shared-session recovery should not be shown for Cloud Mode when they do not apply.
### Rollout behavior
- The behavior in this spec is gated by `CloudModeSetupV2`.
- When the flag is disabled, legacy Cloud Mode loading behavior should continue to work.
- When the flag is enabled, the new setup UI should replace the legacy full-screen waiting overlay for startup progress.
## Edge cases
1. **No startup commands run**: the initial prompt and progress/status behavior should still work; no empty startup-command section should appear.
2. **Multiple startup commands run**: all commands before the first exchange should be represented under the same summary row and should maintain independent expanded/collapsed detail state.
3. **Startup command fails**: the failed command row should show a failure icon and remain inspectable; subsequent cloud-agent failure handling should still show the failed state for the run if the run cannot continue.
4. **Command completes while collapsed**: the row status should update from running to success/failure even if details are hidden.
5. **First exchange arrives while commands are expanded**: the setup section should collapse automatically, but the user should be able to re-expand it.
6. **User starts Cloud Mode but sends no prompt**: no parent entry block should be left in the terminal.
7. **User re-enters a cloud agent from the parent terminal**: clicking the entry block should return to the correct cloud agent view.
8. **Nested Cloud Mode session with no dispatched query**: starting another Cloud Mode session should be ignored to avoid empty nested sessions.
9. **Nested Cloud Mode session after a query starts**: starting another Cloud Mode session should create a sibling from the parent terminal context rather than nesting indefinitely.
10. **Historical replay**: replayed conversation data should not hide the first persisted AI block query/header merely because the new live startup UI can render an optimistic prompt.
11. **Shared session replay**: conversation-ended tombstones should not appear during replay before task/conversation liveness is known.
12. **Remote input sync during setup**: setup-command text and input mode changes from the shared session should not overwrite the user's visible local prompt state.
13. **Capacity, quota, or server overload errors**: existing modal/error handling should continue to appear, while the startup UI preserves the initial prompt context.
14. **GitHub auth required**: the run should show an auth-required state rather than looking like an ordinary failure.
15. **Cancelled before task ID arrives**: cancellation should show immediately and should still cancel the server task if the task ID arrives later.
## Success criteria
- Starting a Cloud Mode run immediately renders the submitted prompt in the conversation.
- While the cloud environment starts, users see a clear progress message with the correct phase label.
- Startup commands appear as requested-command-style rows, not as ordinary visible terminal blocks.
- Startup command rows show running, success, and failure states correctly.
- Users can expand a startup command to inspect its terminal details and collapse it again.
- Startup command rows collapse automatically when the first agent exchange arrives.
- The first AI exchange does not duplicate the initial user query in the live startup flow.
- Historical replay still shows the persisted conversation without losing the first query.
- The visible input is not overwritten by environment setup commands.
- Passive suggestions are not generated for environment setup commands.
- Parent terminal entry blocks are created only for dispatched cloud-agent runs and navigate back into the correct cloud-agent view.
- Failure, GitHub auth, and cancellation states remain visible and understandable from the initial prompt context.
- Shared ambient sessions get the appropriate ended-conversation tombstone exactly once and not during replay.
- Disabling `CloudModeSetupV2` restores the legacy loading behavior.
## Validation
- Start a Cloud Mode run against an environment with no startup commands and confirm the initial prompt and progress/status surfaces render without an empty setup-command section.
- Start a Cloud Mode run against an environment with multiple successful startup commands and confirm rows appear expanded during setup, show success after completion, and collapse after the first exchange.
- Start a Cloud Mode run with a failing startup command and confirm the failed row is inspectable and the run failure state is visible if setup cannot proceed.
- While a run is before the first exchange, verify remote setup-command input does not populate the visible prompt and does not flip the visible input mode.
- Verify prompt/passive suggestions are not emitted for startup command blocks.
- Click the setup summary and individual command rows to confirm expand/collapse behavior.
- Start Cloud Mode from a parent terminal, send a prompt, return to the parent, and confirm the entry block shows the correct title/status and navigates back.
- Enter Cloud Mode from a parent terminal and exit without sending a prompt; confirm no parent entry block remains.
- Test failure, cancellation, and GitHub-auth-required startup paths and confirm the initial prompt remains visible with the correct status text.
- Join or replay a shared ambient session and confirm conversation-ended tombstones appear only after the task/conversation is no longer running and not during replay.
- Run with `CloudModeSetupV2` disabled and confirm legacy Cloud Mode setup behavior remains available.