Backends, Cloud and sharing

Gotchas and known limits

• Export the second run as OH_VERIFY_RUN_2 and pass it with --run; never export it as OH_VERIFY_RUN, or the browser commands look for a browser that run does not have. OH_VERIFY_RUN= control-openhands launch --new ... keeps the launch from reusing this run.
• The second backend asks its own telemetry consent the first time it becomes active, over whatever page you are on; onboard --skip answers it. Consent is stored per backend, so a later restart of the second run does not ask again.
• browser fill <sel> --value-file FILE takes no positional value; it keeps the key out of the shell history and the evidence. Edit forms show the stored key masked, but browser snapshot of the Edit form prints it in clear: do not save that snapshot as evidence with a real key.
• Manage-row test ids use the backend name (manage-backends-row-QA_Second), so they change after a rename and are not unique when two backends share a name; the Cloud Log back in id uses the backend id instead (manage-backends-login-<id>-login-button).
• Selector options are named <status> <name> (Connected Local, Disconnected QA_Renamed): select them with role=option[name="Connected <name>"].
• After a navigating option click, --expect-url must allow ?backend=...: end regexes with (\?|$).
• browser wait-tab <regex> matches any open page, including the current one, unless --new leaves out the tab the daemon is on: for a second tab at the same URL (/conversations from New Chat) use wait-tab '/conversations$' --new, or read browser tabs and switch with browser tab <i>. browser tab new /conversations opens a plain second tab (no opener, empty sessionStorage), the state a user reaches by opening the app again. Close extra tabs highest index first, or the indexes shift under you.
• browser tab new switches the daemon to the tab it opened, so a wait-tab <regex> --new run right after it reports the tab you came from (index 0 with two tabs); browser tab 0 first when you want the new tab's index from wait-tab. A tab new and a click --modifiers Control on New Chat reach the same state (selector from the localStorage fallback, sessionStorage item null).
• A tab opened with click --modifiers Control starts with an empty sessionStorage, so it boots from the localStorage fallback (the backend last chosen in any tab) unless its URL carries ?backend=. Opening a ?backend= link writes that backend to localStorage too: a per-tab check that relies on "last choice" must run before opening pinned links.
• The Add Backend Agent-server form has no inline "required" messages; it only disables Connect. The messages exist in the Edit form.
• Footer clicks from the collapsed popover or the phone drawer open the modals a moment later: browser wait for them instead of count.
• The device-flow popup survives errors: every failed attempt leaves an about:blank tab (#17953). Cancel closes it; after an error close it with browser close-tab.
• With the default host the device flow talks to the real app.all-hands.dev (POST /oauth/device/authorize, then token polling). Starting and cancelling is harmless; never approve a code.
• While the second stack's agent server is stopped or restarting, its ingress answers without CORS headers, so the browser logs Access to fetch at '<second-url>/api/settings' ... blocked by CORS policy (also /server_info, /api/conversations/search, /api/llm/models/verified). That is the dead upstream, not a CORS bug; a healthy second stack sends access-control-allow-origin for this origin.
• Local and remote backends are probed every 30 s (settings + server_info), Cloud backends every 5 min (#18128), so allow up to 40 s for a local dot to change. While the active backend is down, any reload lands on the recovery gate: drive the disconnected rows on the page that was already loaded.
• /oauth/device/verify is a Cloud page that also ships in Canvas: on a local stack its POST target does not exist, so Authorize always ends in Error. The "Authentication Required" state is unreachable (useIsAuthed always resolves true).
• /shared/conversations/<id> on a local backend also raises a raw toast HTTP request failed (404 Not Found): {"detail":"Not Found"} next to Conversation not found (#17953).
• Known failure (repro candidate, not an exemption): F25.edit-escape closes the Manage modal underneath and drops the Edit draft (Cancel and X close only Edit, F25.edit-cancel) (#17953).
• The add bullet's network --external --filter 'ids=' check guards an earlier race: on a backend's first activation from /conversations/<id>, about 1 attempt in 5 asked the new backend for the old conversation id. It did not happen in 15 first activations at 4eff80237: each time QA_Second was removed, its consent unset with control-openhands api PATCH /api/settings --run "$OH_VERIFY_RUN_2" --write --data '{"misc_settings_diff":{"app_preferences":{"user_consents_to_analytics":null}}}' (arrange only) and the backend added again from /conversations/<id>. A backend that lacks an id answers [null], which now reads as "not found" (only the This conversation does not exist… toast), not as incompatible data. No merged change was shown to fix the race itself (#18009 only changed how a [null] answer reads; #18024 only moved the redirect into a shared hook, still called after addBackend), so a hit (an ids= request to <second-url>) is a bug to file. At 95115e84f6dd it hit on 1 of 2 first activations from /conversations/<id> (one GET <second-url>/api/conversations?ids=<id> answered 200, with no This conversation does not exist… toast after it). The hit followed a failed Connect in the same modal (an empty key, Invalid API key) before the successful one; the clean retry, which connected once, had none, so a repro should try both sequences. On 2026-10-08 at d2c89252d it did not reproduce in 17 first activations (8 clean, 9 failed-then-clean, some under CPU load and some human-paced): every ids= capture was empty, and no merged change touched the activation logic since the hit, so it stays a watch item rather than a filed defect. Record the Add bullet as fail when the request appears, even though the redirect and the selector look right.
• Toasts are not page or HTTP errors, so browser errors --app-only misses them: read browser toasts --history after every add or switch, before anything reloads the page (the history starts with each page load).
• F25.locked-cloud needs scripts/static-server.mjs --lock-to-cloud <url>, which neither bin/agent-canvas.mjs nor control-openhands launch can pass today; even with it, reconnecting needs a Cloud account.
• The Cloud tab title truncates to OpenHan… at 390 px when the Agent-server tab is selected; the layout still fits.