fix: let Cloud Desktop browsers own route navigation

[austinywang]

Cloud Desktop loading still depended on SwiftUI phase tasks even though the browser state already had a readiness observer. Production never attached that observer. Activated Cloud browser panels now own route navigation, including cold/cached opens, retries, workspace/Dock duplicates and profile changes. The admitted machine/profile store is prepared before a cached route can navigate. Stop invalidates pending observation; closing or leaving a pane keeps delayed route completion from loading it.

Follow-up for #13893. The original selected-destination fix landed in #13897. This PR retains the native window fixture needed to verify the real click/drag path, and the executable CI cleanup guard. After pulling main, the E2E workflow itself matches main; the guard checks its per-run runner-temp path and rejects workspace cleanup.

The regressions are committed before their fixes: 519bf261c892e0808abf09d300acea37d0945d00 (navigation test), 4ce4f4fe26cfc8fd3a5b9ec5925164c1c1d41a4b (navigation fix), 39b61fcbb3 (pane-retention test), then 3ee2ece0f12d5efe47245dfdafc2dec6dceeecfb (pane-retention fix). It invokes the actual outline click/menu and workspace drop through CmuxTuiSurfaceProvider, BrowserPanel, WebKit, authenticated HTTP CONNECT and the WebSocket bridge, with endpoint acquisition and guest HTML substituted. It does not manually call nextURL or navigate. Additional cases cover retry, multiple projections, duplication/profile replacement, close/Stop before readiness, re-entry, and cross-VM rejection in both directions.

Verification is in progress:

• Navigation baseline, exact test-only SHA, macOS 26: queued; no behavioral result claimed yet.
• Fixed native run includes navigation, proxy integration, original click/drop actions, ownership, move/drag rejection, access state, and deferred browser restore suites. Its result will be recorded here when complete.
• The earlier destination regression failed on the original behavior and passed all 24 focused tests before this loading follow-up.
• Local Swift syntax parsing, test wiring, file-length checks and whitespace checks pass. No budget TSV or user-facing string changes. Runtime compilation/warnings are still pending hosted verification.

Limits: the fixture performs real HTTP/WebSocket navigation, but its noVNC-shaped page is not a guest RFB server. No live Cloud guest or isolated GUI proof is claimed. Carrier replacement/reconnect and guest input recovery remain separately owned in #13370. The supplied screenshot does not provide its app revision or authoritative VM/workspace IDs.

Austin explicitly requested a try-it developer build before the queued tests finish. Submission uses the controller build-fleet contract fetched in cmuxterm-hq2 and its backend helper, tag issue-13893-desktop-click-ownership, exact pushed fix SHA. The HQ2-backed attempt was rejected before submission with HTTP 507: 47 GiB free, 50 GiB required. No controller job, app artifact, or launch exists yet. The failure was reported through build-fleet feedback (5bdbecfdd4bec5cec12f16fa). Merge and issue close remain unauthorized.

— CobaltThimble (registration pending)
Run: run_13893_cmux102_20260923_0525 · Session: codex-cmux102-13893-20260923-0525

Summary by CodeRabbit

• Bug Fixes

  • Improved Cloud Desktop navigation when opening, reloading, duplicating, and switching profiles.
  • Preserved local Desktop views during workspace updates and improved routing of dropped items to the correct window and pane.
  • Corrected handling of canceled or pending Cloud routes and limited display-resource reuse to the active workspace.

• Tests

  • Added coverage for Cloud Desktop navigation, workspace projections, window visibility, and safe cleanup of test build data.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Cloud browser setup and route handling now use shared panel configuration. Display reuse and projection reconciliation have updated rules. New tests cover browser navigation and projection behavior. The changes also add task-owned window checks and an E2E DerivedData scope check.

Changes

Cloud browser lifecycle and workspace projections

Layer / File(s)	Summary
Centralize Cloud browser configuration Sources/Panels/BrowserPanel+CloudConnection.swift, Sources/DockSplitStore+BrowserActions.swift, Sources/Panels/BrowserPanel.swift, Sources/Surfaces/Workspace+BrowserDuplication.swift, Sources/Surfaces/CmuxTuiSurfaceProvider+PortForward.swift	A shared configureCloudBrowser method configures and connects Cloud browsers. Duplication, profile switching, and surface configuration use this method or prepare and adopt a preserved route.
Update route and projection behavior Sources/Cloud/PortForward/CloudBrowserAccessState.swift, Sources/Cloud/PortForward/CloudBrowserAccessView.swift, Sources/Cloud/CloudTreeNodeActions.swift, Sources/Surfaces/CloudWorkspaceProjectionPlan.swift, Sources/Surfaces/SurfaceCatalog.swift	Route adoption retains the committed URL and avoids replaying navigation while the route becomes ready. Cancellation can apply while a route is connecting. Retry actions reload without automatic navigation. Display reuse is scoped to a workspace, and local workspace views with a remote workspace ID are skipped during obsolete-placement detection.
Add the navigation test harness cmuxTests/CloudBrowserProxyTestServer.swift, cmuxTests/CloudDesktopNavigationFixture.swift, cmuxTests/CloudBrowserProxyIntegrationTests.swift, cmux.xcodeproj/project.pbxproj	A loopback proxy server and desktop fixture support navigation tests. The proxy fixture moves out of the integration test file, and the Xcode project registers the new test sources.
Cover navigation and projection behavior cmuxTests/CloudDesktopNavigationLifecycleTests.swift, cmuxTests/CloudBrowserRouteAdoptionTests.swift, cmuxTests/CloudWorkspaceProjectionPlanTests.swift, cmux.xcodeproj/project.pbxproj	Lifecycle tests cover navigation entry points, route readiness, reload, duplication, profile switching, projection, closure, provider reattachment, and foreign-workspace rejection. Other tests cover committed-route adoption and projection reconciliation.

Cloud Desktop window fixture

Layer / File(s)	Summary
Register and validate the task-owned window Sources/AppDelegate.swift, cmuxTests/CloudDesktopOpenFixture.swift	The fixture creates and registers a task-owned window, adds a workspace with addWorkspaceIfActive, and records identity details. It checks that the window remains hidden and non-key during activation and drops, validates pane routing, and forgets the recoverable route during cleanup.

E2E DerivedData scope

Layer / File(s)	Summary
Verify DerivedData preparation and cleanup tests/test_ci_app_host_home_isolation.py	The check verifies that preparation creates the expected RUNNER_TEMP path without changing a workspace sentinel. It checks that cleanup removes the prepared path, preserves the sentinel, and rejects a workspace-owned path.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant CmuxTuiSurfaceProvider
  participant BrowserPanel
  participant CloudBrowserAccessState
  CmuxTuiSurfaceProvider->>BrowserPanel: Configure Cloud browser
  BrowserPanel->>CloudBrowserAccessState: Configure route and connect model
  BrowserPanel->>BrowserPanel: Bind automatic navigation

Loading

Possibly related PRs

• manaflow-ai/cmux#12912: Both changes cover Cloud browser route handling, proxy/WebSocket routing, and local preview projection behavior. PR #13938 changes committed-route preservation and panel navigation setup.

Merge Risk: 🔵 Low · up to 31f69

The route-adoption test should also verify that the adopted page can finish loading. This gap is bounded and does not, by itself, prevent merging.

---

Important

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

❌ Failed checks (2 errors, 1 warning)

Check name	Status	Explanation	Resolution
Cmux Swift @Concurrent	❌ Error	The PR introduces a main-actor-bound network server in cmuxTests/CloudBrowserProxyTestServer.swift. CloudBrowserProxyTestServer is @MainActor, and start() schedules serve(_:) with Task { @M`…	Move the proxy server's network-serving and request-parsing path off @MainActor. Restore a thread-safe/nonisolated server design, or make the async network helpers explicitly nonisolated @concurrent`` and use explicit MainActor hops onl…
Cmux Swift Package Boundaries	❌ Error	The diff adds independent workspace-projection domain logic in the app target. Sources/Surfaces/CloudWorkspaceProjectionPlan.swift now contains the local-preview reconciliation rule and uses only Fo…	Create a small macOS SwiftPM target named CmuxCloudWorkspaceCore. Expose CloudWorkspaceProjectionPlan as its first public type, together with the minimal public placement/projection value types it needs. Move the reconciliation rule and…
Docstring Coverage	⚠️ Warning	Docstring coverage is 14.58% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 48 functions across 16 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (22 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: Cloud Desktop browsers now own route navigation.
Description check	✅ Passed	The description provides a detailed summary, rationale, testing scope, limitations, issue context, and verification status. It does not include the template's Demo Video, Review Trigger, or Checklist …
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Cmux Cloud Persistent Session And Early Input	✅ Passed	PASS. The diff does not introduce Cloud terminal creation, cmux-tui transport, PTY or shell startup, manual Ghostty rendering, or input attachment logic. The production changes are limited to Cloud br…
Cmux Swift Actor Isolation	✅ Passed	The production diff does not introduce a covered actor-isolation mistake. CloudBrowserAccessState is already @MainActor, CloudPortAccessModel is already @MainActor, BrowserPanel is already `…
Cmux Swift Blocking Runtime	✅ Passed	The production Swift diff adds no semaphores, blocking waits, sleeps, delayed dispatch, polling loops, manual locks, or main-queue synchronous dispatch. The existing CloudBrowserAccessState deadline s…
Cmux Browser Automation Off-Main	✅ Passed	PASS: The PR does not change cmux browser socket automation routing. The policy source files Sources/TerminalController.swift and `Packages/macOS/CmuxControlSocket/Sources/CmuxControlSocket/Wire/Con…
Cmux Expensive Synchronous Load	✅ Passed	The production Swift diff does not add or move an expensive agent-history load. Added code handles Cloud browser route state, WebKit store setup, navigation binding, and model connection. It contains …
Cmux Cache Substitution Correctness	✅ Passed	PASS. The production diff does not replace a fresh authoritative read in a persistence, history, undo, or snapshot path. The Swift changes move Cloud route activation to browser-owned readiness observ…
Cmux No Hacky Sleeps	✅ Passed	PASS. The only changed non-Swift file is the test-only tests/test_ci_app_host_home_isolation.py. Its added code runs deterministic temporary-scope checks for DerivedData preparation and cleanup. The…
Cmux Algorithmic Complexity	✅ Passed	PASS. The production diff adds route-state handling and Cloud browser configuration, but it does not add nested collection scans, per-target batch rescans, or repeated sorting/filtering. `CloudWorkspa…
Cmux Swift Concurrency	✅ Passed	The production Swift diff adds no background Dispatch queues, Combine state, completion-handler API, or new fire-and-forget Task. The existing observer Task in CloudBrowserAccessState remains present …
Cmux Swiftpm Lockfiles	✅ Passed	The PR changes no Package.swift, Package.resolved, .gitignore, or workflow file. The cmux.xcodeproj/project.pbxproj diff only registers five Swift test source files; it adds no SwiftPM package-referen…
Cmux Swift Logging	✅ Passed	PASS. The reviewed production Swift diff adds no print, debugPrint, dump, NSLog, ad hoc file/stdout logging, or new Logger declaration. The existing cloudDisplayLogger and other logging stat…
Cmux User-Facing Error Privacy	✅ Passed	PASS. The authoritative diff adds no production user-facing error, alert, command output, API error body, or recovery text. Production additions only change route ownership, state, and navigation wiri…
Cmux Full Internationalization	✅ Passed	The production diff adds or changes no user-facing copy, localization key, string catalog, Info.plist locale entry, web message, or locale registry. The only production text-related change is moving t…
Cmux Swiftui State Layout	✅ Passed	PASS. The only changed SwiftUI view is CloudBrowserAccessView; the diff removes its .task(id:) render-time navigation calls and the helper they invoked. No new ObservableObject, @Published, `G…
Cmux Architecture Rethink	✅ Passed	PASS. The production diff does not add sleeps, polling, locks, delayed dispatch, or blocking repair paths. CloudBrowserAccessState already owned withObservationTracking; this change activates that…
Cmux Swift Auxiliary Window Close Shortcuts	✅ Passed	PASS. The production diff adds no NSWindow, NSPanel, NSWindowController, SwiftUI Window, or WindowGroup code, and it does not change auxiliary-window shortcut ownership. The only changed window constr…
Cmux Source Artifacts	✅ Passed	PASS. The diff contains only Swift source, test fixtures and suites, Xcode test-target configuration, and an existing Python CI test guard. The new proxy and navigation files are deliberate test fixtu…
Cmux No Test Or Debug Seam In Production Source	✅ Passed	PASS. The production diff adds no #if DEBUG or test-build seam, and no member named debug…, …ForTesting, TestHook, or similar. Sources/AppDelegate.swift only widens `mainWindowVisibilityCont…

Full details: Cmux Swift `@Concurrent`

Explanation

The PR introduces a main-actor-bound network server in cmuxTests/CloudBrowserProxyTestServer.swift. CloudBrowserProxyTestServer is @MainActor, and start() schedules serve(_:) with Task { @mainactor in ... await self.serve(connection) }. serve(_:) and readRequest(_:) perform repeated NWConnection receives/sends, WebSocket handling, request parsing, and CloudPortForwardRelay.relay while remaining actor-isolated. The base revision used a lock-based @unchecked Sendable server and handled serve outside @MainActor, so this is introduced by the PR. This violates the rule for network-heavy async helpers called from UI isolation without an explicit hop or @concurrent boundary.

Resolution

Move the proxy server's network-serving and request-parsing path off @MainActor. Restore a thread-safe/nonisolated server design, or make the async network helpers explicitly nonisolated @concurrent`` and use explicit MainActor hops only when recording requests, targets, connections, or other actor-owned state. Do not await `serve`, `readRequest`, or the relay from a `Task { `@MainActor` in ... }` network loop.

Full details: Cmux Swift Package Boundaries

Explanation

The diff adds independent workspace-projection domain logic in the app target. Sources/Surfaces/CloudWorkspaceProjectionPlan.swift now contains the local-preview reconciliation rule and uses only Foundation plus value data. cmuxTests/CloudWorkspaceProjectionPlanTests.swift tests it directly without UI. The reviewed range adds no SwiftPM target, while the repository already uses small Cloud core packages with dedicated test targets. The browser-panel and AppKit lifecycle changes are app glue, but this projection-plan change matches the package-boundary failure condition.

Resolution

Create a small macOS SwiftPM target named CmuxCloudWorkspaceCore. Expose CloudWorkspaceProjectionPlan as its first public type, together with the minimal public placement/projection value types it needs. Move the reconciliation rule and its tests into that package. Keep CloudWorkspaceProjectionCoordinator in the app target as composition glue that maps app projections to package values and applies the plan.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[cursor]

Bugbot is paused — on-demand spend limit reached

Bugbot uses usage-based billing for this team and has hit its on-demand spend limit.

A team admin can raise the spend limit in the Cursor dashboard, or wait for the next billing cycle to continue.

[cursor]

Bugbot is paused — on-demand spend limit reached

Bugbot uses usage-based billing for this team and has hit its on-demand spend limit.

A team admin can raise the spend limit in the Cursor dashboard, or wait for the next billing cycle to continue.

[cursor]

Bugbot is paused — on-demand spend limit reached

Bugbot uses usage-based billing for this team and has hit its on-demand spend limit.

A team admin can raise the spend limit in the Cursor dashboard, or wait for the next billing cycle to continue.

[cursor]

Bugbot is paused — on-demand spend limit reached

Bugbot uses usage-based billing for this team and has hit its on-demand spend limit.

A team admin can raise the spend limit in the Cursor dashboard, or wait for the next billing cycle to continue.

[cursor]

Bugbot is paused — on-demand spend limit reached

Bugbot uses usage-based billing for this team and has hit its on-demand spend limit.

A team admin can raise the spend limit in the Cursor dashboard, or wait for the next billing cycle to continue.