[REMOTE-2661] Allow a debug agent in a retained setup-failure session (warp client)

[warp-agent-staging]

Description

What: An authorized user can run a debug agent inside the retained sandbox of a cloud run that failed during environment setup. The debug agent does not reopen the run and does not clear its failure record. A silent agent turn does not consume the idle timer.

Why: A run that fails during setup keeps its session alive for a bounded debug window (REMOTE-2208). But there is no way to get an agent into that session. If you start an agent the ordinary way, it creates a fresh conversation and flips the run back to "in progress". That destroys the failure record that you want to debug.

How: A no-token prompt against a retained, eligible session bootstraps a debug conversation through the server's authenticated follow-up path, not the direct viewer path. The client suppresses task-state reporting for that conversation, so the conversation cannot overwrite the failure record. Each debug turn pins the idle timer for its duration, so an autonomous agent does not lose its own session.

Server companion: warp-server#14231. Deploy the server PR first. Against an older server, the client fails closed (debug_agent_available defaults to false). Thus an early client deploy is inert, not wrong.

Reviewing guide

Suggested order:

1. task.rs — Start with is_setup_failure_debug_session_open. All downstream code trusts this one field.
2. cloud_conversation_continuation.rs — Read resolve_ai_query_routing and the new routing variant. Check the priority order (retained-debug check before live-viewer check).
3. terminal_view_adaptor.rs — Read the AgentPromptRequested handler as a whole, not as a diff, because a brace moved. This handler is the security boundary.
4. driver.rs — Read DebugWindowController and arm_setup_failure_debug_window. This is the most complex state machine in the PR. Check the pin and unpin transitions against the ConversationStatus variants.
5. conversation.rs / local_agent_task_sync_model.rs — Read TaskSyncMode::PreserveTerminalSetupFailure and the locations that set and read it.
6. input.rs / slash_commands/mod.rs — Read the submission entry points. Check that /agent and plain input resolve to the same routing.
7. The remaining files (footer indicator, GraphQL schema and query, tests) are plumbing for items 1-6.

Architecture overview

Six pieces, each with one job:

1. Eligibility (AmbientAgentTask::is_setup_failure_debug_session_open, task.rs) — The client trusts one server-computed boolean: debug_agent_available. The server knows the failure state, error code, feature flags, and window status from the same snapshot. The client does not re-derive this data.
2. Routing (cloud_conversation_continuation.rs) — Adds the AIQueryRouting::RetainedSetupFailureDebug variant. The resolver checks it before ordinary live-viewer routing. Thus every entry point (plain input, /agent, an attached viewer) converges on the authenticated follow-up service. No entry point uses the direct viewer-prompt path or a local conversation.
3. Sharer authorization (terminal_view_adaptor.rs + the new setupFailureDebugAuthorization GraphQL query) — The sharer cannot authenticate the requester itself. Thus the sharer honors a no-token prompt only after an explicit true from the server. There is no local fallback.
4. Idle-timer pin (driver.rs, DebugWindowController) — Runs inside the agent process. A debug turn pins the idle window open for its duration and re-arms it on completion. This is necessary because no viewer keystroke refreshes the window during an autonomous turn.
5. Task-state suppression (TaskSyncMode in conversation.rs, local_agent_task_sync_model.rs) — The debug conversation reports its ID (the injection and transcript APIs need it). But the conversation never derives task state from its own status. Thus it cannot overwrite the original failure record. The server independently guards the same rule.
6. Atomic failure report (driver.rs) — The driver sends the terminal failure state, the status message, and the first debug deadline in one server update. Thus the server never sees a failure without a debug-window deadline.

Testing

Unit tests cover:

• DebugWindowController pin, re-arm, and idempotence

• The sharer authorization decision (accept, deny, error, no token)

• Routing eligibility gated on the real debug_agent_available field, with team-owned runs included

• A later prompt that reuses the existing debug conversation

• TaskSyncMode suppression of task-state derivation.

• I have manually tested my changes locally with ./script/run

Agent Mode

• Warp Agent Mode - This PR was created via Warp's AI Agent Mode

[warp-agent-staging]

End-to-end verification: 4/4 required states proven against a real local stack

Run 019fef07-4c18-7a53-a088-48c9d37ea4f5, environment q1ZcbtEBf2wIqCvcHvFYeo.

1. Setup fails, run FAILED with its message. state=FAILED, error_code=environment_setup_failed, message="Environment setup failed: Failed to run setup command: ls /workspace/remote-2661-missing-dependency-dir", session_debug_until=04:44:28, retained_debug_execution_id=6, debug_agent_available=true, is_sandbox_running=true. The retained agent process stayed alive; its log shows idle_timeout_scheduled timeout=1800s outcome=setup_failure.

2. Debug prompt reaches an agent in the broken environment. POST /agent/runs/{id}/followups with {"message":"/agent why did my setup fail"} returned HTTP 200 at 04:15:14. The timeline then recorded setup_failure_debug_started (04:15:14.759, exec=6) and setup_failure_debug_finished (04:15:15.633, exec=6). These events are produced by setupFailureDebugTimelineEventType mapping the agent's own reported task state (IN_PROGRESS → started, SUCCEEDED → finished), so their presence means the agent genuinely received the prompt and ran a turn, and the server converted its status reports into debug events rather than lifecycle transitions.

3. Run still FAILED afterwards, message and code intact. Sampled continuously and again 8 minutes later: state=FAILED, error_code=environment_setup_failed, message byte-identical, retained_debug_execution_id still 6. The timeline contains no second oz_run_claimed and no second oz_run_failed — the debug turn produced only non-lifecycle debug events. The terminal state was never rewritten.

4. Timer refreshes, pins, re-arms. Sampled every 2s: before, until=2026-08-11T04:44:28.057911817Z active=false; on acceptance at 04:15:15, until=2026-08-11T04:45:15.054934977Z active=true (refreshed and pinned); after at 04:15:17, until=2026-08-11T04:45:16.400373102Z active=false (re-armed, later still).

Reproduction. Branches: warp-server factory/remote-2661-server-setup-failure-debug, warp factory/remote-2661-warp-client. Client built with cargo build --bin warp --features gui and WITH_LOCAL_SERVER=1 WITH_LOCAL_SESSION_SHARING_SERVER=1 WARP_CLOUD_MODE_DEFAULT_HOST=local-dev, after ./script/install_channel_config (must log channel: local). config/local.yaml needs failure_session_debug_agent: true; failure_session_retention was already true; both are required. Stack: ./script/oz-local up --detach --wait --oz-path /workspace/warp/target/debug/warp --worker-dir /workspace/oz-agent-worker --session-sharing-dir /workspace/session-sharing-server -e WARP_ISOLATION_PLATFORM=docker_sandbox. Environment created via upsertCloudEnvironment with failureSessionRetentionMinutes: 30 and setup commands ending in one that fails without exiting the shell. Run submitted via POST /api/v1/agent/runs with worker_host: "local-dev".

Scaffolding — everything stubbed or patched, none of it in the feature's path.

1. Firebase user directory stubbed (FIREBASE_AUTH_EMULATOR_HOST, serving only accounts:lookup), because profile.needsSsoLink forces an uncached Identity Toolkit call this sandbox is denied. Ambient auth infrastructure; no feature code changed.
2. LLM mocked via /debug/llm-mock for determinism — no provider credentials exist in the sandbox. This shapes the content of the agent's answer, not whether a turn ran or what the run state did.
3. WARP_ISOLATION_PLATFORM=docker_sandbox passed to tasks, correcting a misdetection: the runner is itself a Namespace sandbox, so the agent saw /var/run/nsc/token.json and shelled out to nsc instead of using the WARP_WORKLOAD_TOKEN the server already provided.
4. session-sharing-server/script/server shebang #!/bin/sh → #!/bin/bash (sibling checkout, neither PR) — bash-only syntax meant args were silently dropped and --features local_warp_server never applied.
5. session-sharing-server/script/bootstrap gcloud components install pubsub-emulator made conditional.
6. Fixture API key flipped to a user principal in the local DB so upsertCloudEnvironment would accept it.
7. An ADC wrapper so the sandbox's credential helper keeps seeing the platform key while the stack uses the local fixture key.
8. Root-owned CARGO_HOME and target/ chowned; net.git-fetch-with-cli=true.

Items 4–8 are environment plumbing. Items 1–3 are the only ones touching a runtime path, and none is inside the retained-session or debug-window logic under verification.

Why there is no screenshot. The Oz web app could not be reached honestly. The app shell serves at /agents.html on the Vite dev server, and a browser session could be authenticated by minting a session cookie the Admin SDK accepts in emulator mode — /auth/session returned authenticated: true. But the app's Apollo client authenticates through apollo-auth-wrapper.firebase.tsx, i.e. Firebase client-side sign-in against the real staging project, for which no account exists here. Making the UI show real data would have required patching that wrapper as a third layer of scaffolding on top of a stubbed directory and a forged cookie, at which point the capture stops being evidence. MSW mode would render instantly but shows mocked data, which would be a fabricated capture. The verification therefore rests on API and database observation of a genuinely running stack. A rendered capture is cheap on any deployment where Firebase auth works normally; the feature itself needs nothing further.

[dmichelin]

Pushed a follow-up commit closing the last gap in the retained setup-failure debug flow: the sharer authorized and started a debug conversation for a purpose-tagged bootstrap request, but never reported which conversation resulted back to session-sharing-server. That server endpoint requires a conversation_id in its response to resolve the caller's synchronous wait, so every bootstrap injection was indistinguishable from a failed delivery and kept getting retried — the debug agent could never actually be observed as started.

This required corresponding changes in two upstream repos:

• feat(REMOTE-2661): Add idempotency key to support server initiated bootstraps session-sharing-protocol#65 — adds AgentPromptPurpose/idempotency_key to AgentPromptRequest, and a new AcknowledgeAgentPromptRequest upstream message for the sharer to report the resulting conversation.
• warpdotdev/session-sharing-server#483 — accepts purpose/idempotency_key on the inject endpoint, returns conversation_id, and polls for the sharer's ack/reject (with idempotency dedup for retries).

This repo's commit adds the sharer-side piece: it registers a pending-ack correlation when accepting a purpose-tagged request, and sends the acknowledgement once BlocklistAIHistoryEvent::ConversationServerTokenAssigned reports the new conversation's token. Cargo.toml is temporarily pinned to the protocol PR's branch commit until it merges (see the TODO(REMOTE-2661) comment).

cargo check -p warp / --tests, cargo clippy -p warp --lib --tests -- -D warnings, and cargo fmt --check -p warp all clean.

[dmichelin]

make sure this gets reverted

[warp-agent-staging]

Not reverted yet, deliberately — leaving this open. The pin is now 4888e758, the head of session-sharing-protocol#65, which is where AgentPromptRequest.purpose and AgentPromptFailureReason::NotEligibleForPurpose are gone; this client will not compile against main until #65 merges. The TODO(REMOTE-2661) above it is the reminder to point back at main at that moment, and the merge-order warning at the top of the PR description names the same gate.

Responding as wilson: Open session · View factory task

[warp-agent-staging]

Overview

Client leg of REMOTE-2661, reviewed for size after a request to trim the feature's ~5.4k added lines. The largest single cut in the whole feature lives here, and the read also turned up a routing predicate that diverges from the spec.

Concerns

• Retained-session routing stops working after the first bootstrap (important). AmbientAgentTask::is_open_for_setup_failure_debug_bootstrap requires conversation_id().is_none() (app/src/ai/ambient_agents/task.rs:330-365), and both is_retained_setup_failure_debug_editable and resolve_ai_query_routing gate on it (cloud_conversation_continuation.rs:106-124,191-201). Once the first bootstrap persists a conversation ID, an attached viewer stops resolving to RetainedSetupFailureDebug and falls back to the direct LiveRemoteVm path — but PRODUCT.md §7 and TECH "Update the Warp client tombstone and routing" require every later prompt to reuse the conversation through the authenticated run-follow-up service, never the direct viewer path. Split bootstrap eligibility from retained-session routing so the latter stays true for an eligible retained failure after a token exists.
• Same predicate ignores the pinned window (important). It requires an unexpired deadline rather than also honoring debug_agent_active while a turn has the timer pinned, which PRODUCT.md §1 and §24 both call for. A long autonomous turn that pins past the displayed deadline would lose its own entry point.
• A second idempotency mechanism guarding one failure mode (~375-390 lines, suggestion). The task-ID→conversation retry map at app/src/ai/blocklist/controller/shared_session.rs:31-50,850-1097 is ~125-135 production lines, plus shared_session_tests.rs (68) and controller_tests.rs:425-608 (184). TECH.md:96 calls it "a second, independent safeguard" that "does not replace the protocol-level idempotency key", and this PR's own body concedes it does not prevent the failure on its own; it is keyed only by task_id, not the transmitted key, and stops reusing once the token is assigned, so it is strictly weaker than the service contract. Once session-sharing-protocol#65 and session-sharing-server#484 are merged, deployed, and their retry contract proven, this is the biggest safe cut in the feature — but only in that order.
• A 184-line test that does not exercise what it is filed under (suggestion). controller_tests.rs:425-608 (cancelling_and_resending_within_one_conversation_reports_success) never reaches the new task-ID map or reuse path; it drives pre-existing same-conversation cancellation and would have passed before this PR. Reduce it to a small contract test, or delete it with the map above. Every other added test earns its place under the test-value gate — the timer pin/re-arm cases, the sync-mode regression, the routing capability and team-member cases, and the authorization true/deny/error/no-UID/no-token cases each pin a distinct spec requirement.
• Comment volume and eligibility logging (~120-150 lines, suggestion). The non-test diff adds 417 ////// lines: controller/shared_session.rs +68, driver.rs +62, terminal_view_adaptor.rs +47, ambient_agents/task.rs +46, continuation routing +35. Keep the why-level comments on the authorization boundary and the timer invariant; drop the call-path recounting and issue history per AGENTS.md. Separately, task.rs:330-365 and cloud_conversation_continuation.rs:262-304 emit warn! on every eligibility evaluation on a routing/input path — that is breadcrumb-level noise at warn severity and carries no feature behavior.
• Duplicated unresolved-task-cache policy (~40-55 lines, suggestion). The same "cache unresolved, block and fetch" handling appears at app/src/terminal/input.rs:4197-4247 and app/src/terminal/input/slash_commands/mod.rs:485-535, after eager warming at shared_session/viewer/terminal_manager.rs:848-859. Keep the fail-closed behavior, but collapse the duplicated model locking, lookup, fetch, and toast into one Input helper used by both ordinary submit and /agent//new, and assert it once at the helper level.

Not trim candidates: the timer pin/re-arm controller (PRODUCT.md §18-24 requires idempotence by turn ID and a pin while at least one turn is active, so the turn-keyed set is not gratuitous), TaskSyncMode::PreserveTerminalSetupFailure, TaskScope/team access, and setupFailureDebugAuthorization — I looked for an existing workload-token query the sharer could reuse for a task+participant check and found none on master. Its ~250 production/schema lines are proportionate to a credit-spend authorization boundary; its four fail-closed inputs already converge through one .unwrap_or(false).

Verdict

Checks: build not run, tests not run, CI not checked, visual proof n/a — this was a read-only size analysis, so the two routing findings above are unverified against a running client.

Found: 0 critical, 2 important, 4 suggestions, 0 nits

Of the +2,462 here, 934 lines (37.9%) are test-only and 1,528 are non-test; conservative non-overlapping trim is ~550 lines, leaving a floor near ~1.9k.

Responding as wilson: Open session · View factory task

[warp-local-for-testing-only]

An unexpected error has occurred: managed MCP server 01a01a21-3ec9-71a1-99f2-f13b1773c920 is not active