[ACP on Cloud] Epic: ACP agents (Claude Code / Codex / Gemini) in Docker + cloud

[simonrosenberg]

Epic / tracker. Make ACP agents (Claude Code, Codex, Gemini) work when the agent-server runs outside the user's machine — first containerized (Docker), then cloud. Today ACP only works against a local agent-server because the subprocess silently inherits the user's machine (shell env + CLI login files ~/.claude, ~/.codex/auth.json, ~/.gemini/), both of which vanish in a container/pod. Details live in the sub-issues; this issue holds shared context + the ordered task list.

Key finding — transport already works

At the SDK layer ACP rides the same REST+WebSocket conversation transport as the regular agent, with the CLI as a co-located subprocess inside the agent-server (proven by examples/02_remote_agent_server/09_acp_agent_with_remote_runtime.py). The cloud proxy / exposed_urls / session_api_key are agent-agnostic. The real work is: carry the agent spec, inject credentials, persist state, plus onboarding UX — and a set of pre-cloud refactors that de-risk all of it.

Guiding principle

Stop treating ACP as a special case. ACP today runs parallel channels (secrets, request-building, event fan-out, persistence, model-state, type-detection) for things the regular agent does through one canonical path. Every strongest move collapses an ACP-only channel onto the regular agent's canonical one — which is the channel that already crosses the process/cipher/network boundary. ACP has no production users → no backward-compat, so refactors are deletes, not shims.

Shared reference — credential matrix (verified against CLI sources/binaries)

Provider	API key	Subscription	Inject into container?
Claude Code	ANTHROPIC_API_KEY	CLAUDE_CODE_OAUTH_TOKEN env (from claude setup-token)	✅ env-var secret. ⚠️ _ENV_CONFLICT_MAP only guards the CLAUDE_CONFIG_DIR path, not the token — don't co-set ANTHROPIC_BASE_URL (silently breaks bearer auth); Max/Pro desktop token is in the macOS Keychain → cloud = env-token only
Codex	OPENAI_API_KEY	$CODEX_HOME/auth.json — interactive login, rewritten on refresh	⚠️ file materialisation into a writable CODEX_HOME (detection hardcodes ~/.codex/auth.json, acp_agent.py:234; fixed in #1020)
Gemini	GEMINI_API_KEY	personal OAuth file is AES-GCM bound to hostname+username	❌ personal not deployable; only Vertex SA file

Shared reference — persistence reality

/workspace is a per-runtime PVC that survives pause/resume only: STOP / last-conversation-delete deletes it (runtime-api/k8s.py:488), a reaper kills it at a 14-day creation-time TTL (prod/staging), eval stops on idle, reclaimPolicy: Delete. HOME=/home/openhands is NOT on the PVC → the CLIs' ~/.claude, ~/.codex, ~/.gemini state is ephemeral. ⇒ the per-conversation CLI data root must live under the durable conversations tree (/workspace/conversations/{id.hex}/), and "resume beyond 14 days / across stop" needs a Retain volume. (Details: #1018.)

---

Tasks — implementation order

Unlabelled = required (P0). P1/P2 = optional / can follow. Order is dependency-driven (no hard deadlines).

Phase 0 — Pre-cloud refactors (de-risk before building cloud)

• [ACP on Cloud] Surface structured errors on ACP spawn/auth/init failure #1024 — Surface structured errors on ACP spawn/auth/init failure (front-load — cheapest, makes bring-up debuggable)
• [ACP on Cloud] Refactor: consolidate ACP secret/env channels onto state.secret_registry #1022 — Consolidate ACP's 4 secret/env channels onto state.secret_registry (the anchor; SDK-core — the backend builder collapse already landed on main)
• [ACP on Cloud] Refactor: mask injected secrets in ACP tool-call output #1023 — Mask injected secrets in ACP tool-call output (security; ships with [ACP on Cloud] Refactor: consolidate ACP secret/env channels onto state.secret_registry #1022)
• [ACP on Cloud] Refactor: decouple ACP tool-call streaming (live deltas) from persistence (one terminal event) #1025 — P1 Decouple ACP tool-call streaming (live deltas) from persistence — O(n²)→O(1), streaming-ready (before real cloud load)
• [ACP on Cloud] Refactor: ACP<->regular-agent alignment cleanups (acp_server field, capability props, init spine) #1026 — P1/P2 ACP↔regular-agent alignment cleanups (first-class acp_server/agent_kind detection; capability props; init spine)

Phase 1 — SDK foundation

• [ACP on Cloud] SDK: materialise reserved file-content auth secrets (Codex auth.json, Gemini Vertex SA) #1020 — Materialise reserved file-content auth secrets (Codex auth.json, Gemini Vertex SA) → persisted per-conv root, reads secret_registry, CODEX_HOME-aware detection

Phase 2 — Persistence & isolation

• [ACP on Cloud] Sandbox isolation: per-conversation CLI data root #1019 — Per-conversation CLI data root (sandbox isolation under grouping)
• [ACP on Cloud] Persistence: durable config + native session storage across pod recycles #1018 — Durable config + native session storage across pod recycles (resume, #3343)

Phase 3 — Docker (first deployable target)

• [ACP on Cloud] Phase 3 (Docker): run ACP against a containerized agent-server #1014 — Run ACP against a containerized (Docker) agent-server (wiring, credential UX, image pin/npx, persistent volume, docker-compose)

Phase 4 — Cloud

• [ACP on Cloud] Cloud: carry the ACP agent spec (snapshot agent_settings at creation) #1015 — Carry the ACP agent spec to cloud (snapshot agent_settings at creation)
• [ACP on Cloud] Cloud backend: build ACPAgent + inject per-provider credentials #1016 — Cloud backend: build ACPAgent + inject per-provider credentials (encrypted store + cipher; bump the runtime image pin)
• [ACP on Cloud] Onboarding: capability-driven flow for local / Docker / cloud #1013 — Capability-driven onboarding for local / Docker / cloud (cross-cutting; can parallelize)
• [ACP on Cloud] Cloud: enable ACP model switching #1017 — P1 Enable ACP model switching in cloud

---

Non-goals / accepted divergences (do NOT "fix" — alignment would fight the design)

• Don't make ACP secret injection lazy/per-command like bash — the subprocess is a black-box CLI; creds must be present from spawn. Mitigate with masking ([ACP on Cloud] Refactor: mask injected secrets in ACP tool-call output #1023) + a minimal injected set.
• Don't remap ACPToolCallEvent→Action/Observation wholesale — ACP is deliberately non-LLM-convertible and streams N updates.
• Don't touch on_token streaming — already unified with stream=True LLMs via StreamingDeltaEvent (event_service.py:706).
• Don't touch the disabledByAcp nav or the cloud model-picker gate — inherent ACP semantics (the CLI owns its own LLM/condenser/MCP) / symmetric with the regular switchProfile local-only throw.

Related SDK PRs

#3343 (resume-session-id → #1018) · #3436 (acp_env→SecretStr — merged) · #3458 (MCP forwarding — tangential, not required for this epic).

[simonrosenberg]

Engineering review — flaws, overlooked risks, and corrected critical path

Consolidated from two independent review passes against software-agent-sdk, OpenHands, agent-canvas, runtime-api, deploy, infra (a cross-repo code audit + local ACP validation). Reviewing the live body (updated 2026-06-02). All citations are file:line; "main" = SDK origin/main (HEAD e00da77d7).

Verdict: directionally sound and a good tracking scaffold, but it materially understates the hardest integration risks. The architectural insight is correct (ACP reuses the existing REST/WS transport with the CLI as a co-located subprocess; /workspace is a real PVC; the backend already routes ACPAgentSettings → ACPAgent). But nearly every load-bearing capability lives on unmerged, mutually-conflicting PR branches; the persistence substrate is weaker than claimed; and several items are mis-framed against code that already exists. Below, each item is claim in the issue → reality (evidence) → fix.

---

🔴 Blockers — resolve before treating the epic as implementable

B1. /workspace is not durable in the sense the persistence section needs.
Claim: "/workspace is already the runtime-api PVC that survives sandbox recycles (ownerReference is the Deployment, not the Pod)." Reality: it survives pause/resume of one runtime, but stop_runtime → remove_runtime_in_k8s deletes the PVC (runtime-api/k8s.py:488); deleting the last conversation on a sandbox calls /stop (OpenHands/.../app_conversation_router.py:754-772); the reaper destroys any runtime (incl. paused) at a creation-time TTL = 14 days prod/staging (runtime-api/cleanup.py:147-173, deploy/envs/{production,staging}/values.yaml); eval sets STOP_IDLE_RUNTIME=true (deploy/envs/evaluation/values.yaml:23); STORAGE_CLASS=standard-rwo, reclaimPolicy: Delete, no Retain. The very ownerReference=Deployment the issue cites as durability is the cascade-delete vector (k8s.py:383-390). Fix: state the real lifecycle; if resume must outlive it, use a Retain/long-lived volume (the ADDITIONAL_PVC mechanism, k8s_resources.py:215-242), a bumped TTL, or an out-of-band store.

B2. HOME is not on the PVC — the relocation strategy is necessary but unbuilt (root cause).
HOME=/home/openhands is ephemeral container FS; only /workspace is mounted (Dockerfile:135, k8s_resources.py:212). So ~/.claude/projects, ~/.codex/sessions, ~/.gemini/* are lost on container recreation. The SDK persists only its own resume token to /workspace (acp_agent.py:1222-1237), not the CLI's backing store, and no HOME/CLAUDE_CONFIG_DIR/CODEX_HOME → /workspace redirect exists on main. The redirect the issue treats as config is the actual work and isn't started; without it, resume is robust only for same-container pause/resume.

B3. File-secret materialisation reads agent_context.secrets only — not state.secret_registry.
There are two secret channels: the canonical remote one is StartConversationRequest.secret_registry → state.secret_registry (openhands-agent-server/.../models.py:156; runtime updates via conversation_router.py:284-301), which the env-var injection reads (acp_agent.py:1342). But materialisation reads only agent_context.secrets — #3292:_materialize_provider_auth_files guards on self.agent_context.secrets (lines 1083-1094); #3269:_materialise_file_secrets "walks self.agent_context.secrets" (1078-1115). Consequence: a CODEX_AUTH_JSON delivered via the standard secret_registry channel never becomes a file — it lands as a multi-KB env var that codex-acp ignores (it reads $CODEX_HOME/auth.json) → silent auth failure. OpenHands #14425 happens to route file secrets through agent_context.secrets, so the cloud path may work, but it's an undocumented coupling and self-hosted/direct-SDK callers using the normal channel break. Fix: materialisation must consume both state.secret_registry and agent_context.secrets.

B4. #3269 and #3292 are mutually-colliding reimplementations of the same feature — pick one first.
Both are independent (non-stacked) branches editing the same regions of acp_agent.py/acp_providers.py/settings/__init__.py + the same test files, with overlapping hunks; #3292 is not an ancestor of #3269. They differ in tempdir prefix, path layout, overwrite semantics, and public API. Both report mergeable=CONFLICTING, none is approved, and #3343 has a failing unresolved-review-threads check. The linear "critical path #3269 → #3292" hides that whichever merges first invalidates the other. Fix: make "pick one mechanism" an explicit gate — recommend #3269's command-independent keying (avoids #3292's brittle acp_command-substring detection that silently skips custom commands), fold #3292's Vertex-AI auth-method preference into it, and fold in B3's "both secret sources."

B5. The deployed cloud/runtime agent-server image predates ACP, and the pinned CLI versions are dead code at runtime.
Claim (#1014/#1016): "the standard image already pre-installs the binaries." Reality: (a) cloud pins agent-server:d96a368-python (deploy/.github/workflows/deploy.yaml:37, 2025-12-09) and feature pins 8daf576-python (runtime-api/.../feature/values.yaml:41, 2025-09-27); the ACP install block first landed 2026-04-23 — so the deployed images contain neither the ACP binaries nor most ACP SDK code. (b) Even a fresh image doesn't run the pins: PATH=$ACP_NODE_DIR/bin:$PATH is set only inside the RUN shell (Dockerfile:172), never as global ENV PATH, and the SDK default launch command is npx -y @agentclientprotocol/claude-agent-acp (acp_providers.py:240, verbatim from resolve_acp_command, model.py:1191-1203) → at runtime npx -y runs under the base node and downloads npm-latest (non-reproducible; hard outbound-npm dependency at conversation start — fatal for air-gapped/SWE-bench eval; the bridge's version-specific assumptions at acp_agent.py:464,530 can silently break). The install is also best-effort (rm -rf $ACP_NODE_DIR/* on musl/old-glibc, Dockerfile:189-196). Fix: bump the runtime image pin to an ACP-enabled build, and decide npx-vs-pinned-binary (point resolve_acp_command at the /usr/local/bin wrappers or accept npx-latest + document egress/drift); add a test asserting the pre-installed binary executes.

B6. The cloud agent spec is built from persisted user settings → races; #1015 needs a conversation-scoped snapshot.
The backend already builds an ACPAgent (merged #14004/#14171/#14185/#14401: _build_acp_start_conversation_request → create_agent(), OpenHands/.../live_status_app_conversation_service.py:1348-1366,1640-1657), and the cloud create request omits agent_settings by design (AppConversationStartRequest has no such field, agent-server-conversation-service.types.ts:62-77; secrets stay server-side). So "the cloud path strips the spec / never learns it's ACP" is misleading — but the actual model (build from mutable global user.agent_settings) is not conversation-scoped, so concurrent/closely-spaced conversations or a mid-flight settings edit race. Fix (first-class backend task): the cloud start request must accept/snapshot agent_settings/agent_settings_diff onto the conversation at creation, rather than resolving from the live persisted setting.

---

🟠 High

H1. The Codex durability story contradicts the code. Table says Codex CODEX_HOME = "✅ full — seed once; refresh writes back to PVC." Both branches write auth.json into a tempfile.TemporaryDirectory (#3292:1075-1102), O_TRUNC overwrite (:210-223), cleanup() on close (:1777-1782) — never /workspace. So a rotated token is discarded at conversation end and the next run replays the (possibly stale) vaulted blob; once that rotating refresh token is server-invalidated, the paste is permanently dead. Even the intended rework inherits B1 (PVC reaped) + a vault-vs-PVC staleness hole. Fix: downgrade to "⚠️ requires unbuilt rework + bounded by PVC TTL + revocation-propagation design."

H2. CODEX_HOME relocation breaks auth detection on main. Detection hardcodes Path.home()/.codex/auth.json and ignores CODEX_HOME (acp_agent.py:205,234; git grep CODEX_HOME on SDK main = empty) — validated locally: codex-acp advertises chatgpt, but the SDK returns no auth method when only $CODEX_HOME/auth.json exists. So relocation is actively harmful until #3292 lands. The issue flags #3292 as required (good) — just put CODEX_HOME-aware detection on the critical path and warn against shipping the relocation default first.

H3. CLAUDE_CONFIG_DIR / ANTHROPIC_API_KEY collisions — both directions. _ENV_CONFLICT_MAP = {CLAUDE_CONFIG_DIR: {ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL}} (acp_agent.py:143-145), stripped unconditionally when CLAUDE_CONFIG_DIR is present (:1365-1368). (a) The relocation table says "Claude → relocate via CLAUDE_CONFIG_DIR" — doing that for persistence silently strips an API-key user's ANTHROPIC_API_KEY and breaks auth. (b) Conversely, the map does not cover CLAUDE_CODE_OAUTH_TOKEN, so a token-only session with an inherited ANTHROPIC_BASE_URL (OpenHands' LiteLLM proxy) breaks bearer auth with no stripping/error. Also: no onboarding field for the token (acp-providers.ts:202-212 has only API key/base-url), and Claude Max/Pro desktop tokens live in the macOS Keychain (no file to materialise) → cloud Claude-subscription = env-token-only. Fix: call out both collisions explicitly; consider keying the conflict map on the token too; add the token as an onboarding field.

H4. #1016's credential injection is net-new across the stack, and acp_env is plaintext at rest. Main maps exactly one LLM api_key → one env var (live_status_app_conversation_service.py:1490-1517); zero CLAUDE_CODE_OAUTH_TOKEN/Codex auth.json/Gemini Vertex SA handling — that needs OpenHands #14425 (OPEN) + SDK #3269/#3292. And acp_env is stored as a member-private plain dict in SaasSettingsStore (no encrypt_value; only SaasSecretsStore encrypts) — raw tokens pasted into acp_env persist unencrypted until #3436 lands and the enterprise store encrypts it.

H5. #1017 is a feature build, not a one-line ungate. The guard is real (agent-server-conversation-service.api.ts:721-725), but: a second cloud gate hides the picker UI (use-chat-input-model-state.ts:67); switchAcpModel(conversationId, model) must be rewritten to plumb conversationUrl + sessionApiKey and callCloudProxy to the runtime (no app_server switch_acp_model route exists — git grep on OpenHands main is empty); and live switch only works while the session is warm (acp_agent.py:2482-2486 → 409 otherwise, cold/resumed falls back to the persisted hint).

H6. Cross-conversation isolation in shared (grouped) sandboxes → tracked in #1019. (Correction to this point as first posted — the cwd-collision framing was wrong.) Under a non-default SandboxGroupingStrategy, conversations share one sandbox. cwd is in fact namespaced per conversation — working_dir=/workspace/project/{conversation_id.hex} (live_status_app_conversation_service.py:303-306) — so cwd-keyed transcripts and the cwd-equality resume guard (acp_agent.py:1382-1395) are not the problem. The real gap is the shared, non-cwd-keyed HOME: concurrent ACP subprocesses race on ~/.codex/auth.json, ~/.gemini/oauth_creds.json, global config/caches/locks, and the injected subscription token is shared across the group (no per-conversation HOME/CLAUDE_CONFIG_DIR/CODEX_HOME — grep across OpenHands = 0 hits). Regular conversations are safe because their state is server-managed and conversation_id-keyed (/workspace/conversations/{id.hex}/, base.py:278-292), HOME-independent. Fix: namespace the CLI data root per conversation_id.hex via acp_env — mirroring OpenHands' own per-conversation model — under a hidden /workspace/.openhands/acp/{conversation_id.hex}/{provider} root (which also avoids the repo-tree pollution of a flat /workspace/.codex); reserve NO_GROUPING as a per-provider fallback.

H7. Structured error surfacing belongs on the critical path, not as polish. Missing executable, initialize failure, auth failure, and startup timeout must emit typed ConversationErrorEvents; otherwise remote ACP failures look like vague task stalls. This compounds with the silent feature-detect no-ops (_sdk_supports_acp_secrets, acp_resume_session_id in model_fields) that drop secrets/resume on a stale SDK pin with no error.

---

🟡 Medium / Low

• Onboarding writes orphaned cloud secrets (false readiness). On a cloud backend, SetupAcpSecretsStep → createCloudSecret stores the key and toasts success (setup-acp-secrets-step.tsx:85-95), but no cloud ACP conversation can consume it and the ACP step has no backend-kind gating (onboarding-modal.tsx). Gate the step on capability; don't toast success for a dead path. (This is the concrete payoff of [ACP on Cloud] Onboarding: capability-driven flow for local / Docker / cloud #1013's capability descriptor — host-local vs Docker vs cloud, provider availability, file-secret support, persistence support.)
• Auth-status line is stale. "No successor" is wrong — canvas feat(onboarding): client-side ACP login detection + collect Gemini credentials (no SDK changes) #1002 (MERGED) is the successor, but it's local-only (shells provider CLIs via the bash endpoint, gated to local), so Docker/cloud post-entry validation — the exact topology this epic targets — is unimplemented. Update the line; close the orphaned dependents typescript-client Reduce dev-load request fanout #196 and agent-canvas feat(onboarding): auto-detect ACP subscription/login via /api/acp/auth-status #971.
• Session-id should stay server-private. Mirroring acp_session_id is right, but as durable backend metadata injected into future ACPAgent construction — not broadly exposed in app-conversation responses.
• "Transport already works" omits real deliverables. Carry/verify the idle-activity heartbeat that prevents pod idle-kill during long ACP turns (event_service.py:589-609, ~20-min threshold), the 100 MiB StreamReader limit (acp_agent.py:147-156), and base-image compatibility — not zero work.
• Canvas "cloud" is not standalone. Every cloud call funnels through callCloudProxy → POST {localhost:8000}/api/cloud-proxy (cloud/proxy.ts) because the browser can't reach cloud/runtime hosts (CORS) — "just point canvas at cloud" still needs a co-located local agent-server.
• Drop the Gemini ~/.gemini → PVC symlink item. Zero implementation; even if built, host-bound personal creds are useless on a recycled pod and only transcripts would survive (nothing wires them up) — bootstrap-prompt resume already covers continuity.
• The cited reference impl 92983b3be is unmerged WIP on feat-acp-session-resume-persistence, ~41 commits behind main, uses the pre-divergence create_agent() shape that conflicts with main's direct ACPAgent(...), and carries an unlanded Alembic migration (114_…) — net-new backend+schema work, not "productize."

---

Corrected critical path (for the cloud goal)

DECISION: pick #3269 OR #3292 (colliding) + fold in "both secret sources" (B3,B4 → #1020)
  → rebase + first-approval the chosen file-secret PR + #3343 (all CONFLICTING/unapproved)
  → #3436 (acp_env SecretStr; rebase) + OpenHands #14425 (per-provider injection) + at-rest encryption (H4)
  → CODEX_HOME-aware detection on critical path (H2); CLAUDE_CONFIG_DIR collision handling (H3)
  → BUMP runtime/cloud agent-server image to an ACP-enabled build + resolve npx-vs-pinned (B5)
  → HOME/CODEX_HOME/CLAUDE_CONFIG_DIR → /workspace redirect + per-conversation namespaced root (B2,H6)
     on a volume that actually persists (B1)
  → DESIGN GATE: sandbox-grouping HOME isolation (H6 → #1019)
  → #1015 = cloud start request snapshots agent_settings (B6) → #1016 → #1017 (H5)
  → structured ACP errors (H7) + capability-driven onboarding (#1013)

Note the Phase-1/Phase-2 back-edge: #1014 → #1013 → #1015 (Phase 2). Split #1013 into a Docker-only credential-UX slice or relabel the phases.

Suggested issue edits

• Persistence section: replace "survives recycles / Codex ✅ full" with the bounded reality (B1, B2, H1).
• Add backend task: cloud start request must accept/snapshot agent_settings/agent_settings_diff (B6).
• Amend SDK file-secret work to consume both state.secret_registry and agent_context.secrets (B3), and make the "pick one mechanism" decision (B4). → [ACP on Cloud] SDK: materialise reserved file-content auth secrets (Codex auth.json, Gemini Vertex SA) #1020
• Put CODEX_HOME-aware detection (H2) and CLAUDE_CONFIG_DIR/API-key handling (H3) on the critical path.
• Add "bump runtime image pin + resolve npx-latest" as a Phase-1 deliverable (B5).
• Replace flat /workspace relocation with a hidden per-conversation ACP data root, and decide sandbox-grouping isolation (H6). → [ACP on Cloud] Sandbox isolation: per-conversation CLI data root #1019
• Move structured ACP startup/auth errors onto the critical path (H7).
• Fix the auth-status line; close Reduce dev-load request fanout #196/feat(onboarding): auto-detect ACP subscription/login via /api/acp/auth-status #971. Drop the Gemini symlink item.
• Add a "Security & multi-tenancy" section (at-rest acp_env encryption, subscription-token blast radius in shared sandboxes, rotation/revocation).
• Add tests for all of the above before treating the epic as implementable.

[simonrosenberg]

Design lens: align ACP with the regular agent (don't invent)

A recurring theme across this epic: the strongest fixes all come from making ACP mirror a pattern the regular (non-ACP) OpenHands agent already uses, rather than building ACP-specific machinery. The two earlier review findings were the same shape (secret source → state.secret_registry, see #1020; per-conversation isolation → namespace by conversation_id.hex, see #1019). Below are the remaining decisions where a regular-agent precedent should drive the ACP implementation. All verified against origin/main.

Plan decision	What the regular agent already does	ACP inspiration	Feeds
Carry the agent spec to cloud (the #1015 "races" concern)	The resolved Agent (incl. LLM) is snapshotted onto the conversation at creation — StoredConversation.agent → meta.json — and rebuilt from that snapshot on resume (request.py:211,219-232; conversation_service.py:670-675; event_service.py:688-691). It is never re-resolved from live user settings.	Snapshot agent_settings → ACPAgent onto StoredConversation.agent at creation. meta.json already round-trips any AgentBase subtype, so ACP gets race-free persistence for free — no new request field needed.	#1015 / #1016
Inject + store subscription credentials	The LLM api_key is split out of agent_settings into an encrypted column / SaasSecretsStore (org.py:128-137; saas_secrets_store.py:80,114-125) and decrypted at the agent-server Cipher boundary via the secrets_encrypted round-trip (config.py:219-228; conversation_service.py:664-673).	Route ACP subscription creds through the same encrypted store + cipher boundary — not org.agent_settings's plain JSON column (org.py:52-53), where they're either redacted-and-lost or plaintext-at-rest. Fixes the at-rest gap flagged in the review (H4).	#1016 / #3436
Error surfacing on spawn/auth failure	The run loop wraps exceptions in a typed ConversationErrorEvent (local_conversation.py:1055-1066) that canvas already renders as a banner (conversation-websocket-context.tsx:461-474; type-guards.ts:216-234).	ACP emits this at prompt time but not on the spawn/auth/init path (acp_agent.py init_state → _init, no try/except) → failures just stall. Wrap that path to emit the same ConversationErrorEvent → reuses the existing canvas render path, no new UI.	#1014 (review H7)
Don't leak injected secrets into the stream — new; not currently in the epic	The terminal tool masks all command output via secret_registry.mask_secrets_in_output() (openhands-tools/.../terminal/impl.py:364).	ACP runs no masking on its streamed chunks / tool-call output (acp_agent.py:613-698) — so an injected subscription token can echo back into the event log. Run on_token / tool-call raw_output+content through the same masking, mirroring TerminalExecutor._mask_observation.	new security item
Where per-conversation durable data lives	Regular per-conversation server state lives under OH_CONVERSATIONS_PATH=/workspace/conversations/{id.hex}/ (remote_sandbox_spec_service.py:30; config.py:129-134; event_service.py:96-98).	Put the per-conversation ACP CLI data root under that same tree (/workspace/conversations/{id.hex}/acp/{provider}) instead of a parallel /workspace/.openhands/acp/… — inheriting the exact per-conversation location + lifecycle the regular agent already uses. Refines #1019.	#1019 / #1018

Already aligned (keep it that way) / already noted

• Cloud→runtime calls ([ACP on Cloud] Cloud: enable ACP model switching #1017): reuse the existing callCloudProxy(hostOverride, session-api-key) pattern (sendMessage / getRuntimeConversation / getVSCodeUrl) — don't build a new route (review H5).
• Agent-settings discriminated union (OpenHandsAgentSettings | ACPAgentSettings) and mcp_config reuse — ACP already mirrors the regular agent here; hold to it (don't fork ACP-specific fields).
• Onboarding capability gating ([ACP on Cloud] Onboarding: capability-driven flow for local / Docker / cloud #1013): derive from the same active-backend capability source canvas already uses for feature gating, not scattered if (kind === …).

Principle for planning

ACP is mis-scoped precisely where it diverges from the regular agent's model — per-conversation, server-owned, encrypted-at-rest, event-driven. Every strongest fix (secret source, isolation, spec snapshot, credential encryption, error events, output masking, data-root location) is the same move: re-align ACP to a mechanism the regular agent already proved. Corollary: the ACP cloud work is less "build new subsystems" and more "stop treating ACP as a special case" — which both de-risks and shrinks it.

Two of these are new vs the current epic: the output-masking gap (a security item) and the snapshot-at-creation reframing of #1015/#1016 (which shrinks that work — no new create-request contract if the agent is snapshotted like the regular one).