diagnostics(cloud): correlate multi-machine terminal state

[austinywang]

Problem

Installed Nightly 0.64.22-nightly.3479285704001 (11e2ee0) made multiple healthy Cloud terminals appear stuck. The observed state is a presentation/readiness mismatch, not a transport outage.

Evidence

• The Nightly startup log records cloud.link.start and cloud.link.connected for all three machines at 2026-09-14T01:16:37–01:16:38Z.
• Read-only probes against the Nightly's existing link sockets found connected sessions and running terminals for every machine:
  • vm-87a90f06e0634c1594801a9f63e5f67e: 4/4 running, 5 native-mirror client references, 4/4 compatibility-tree resolutions.
  • vm-f3e995d835424588b1478451937ad729: 5/5 running, 15 native-mirror client references, 5/5 compatibility-tree resolutions.
  • vm-ed09805c787847e397493b6a58966409: 2/2 running, 4 native-mirror client references, 2/2 compatibility-tree resolutions.
• The deployed daemon returns invalid_terminal_id for the newer resolve-terminal spelling on all sampled terminals; the authoritative snapshot and compatibility-tree fallback resolve every terminal. This is an expected compatibility path, not a missing terminal.
• Native-mirror client sizing shows one currently participating focused pane and attached-but-not-participating clients for the other projections, matching a presentation/geometry symptom.
• The running Nightly accessibility tree still shows all three Cloud machine projections. It was not restarted or otherwise changed.

Root cause and version boundary

The installed build contains #12549 but predates merged #12551 and #12559. #12549 removed the duplicate reconnect banner but retained the #12505 first-visible-frame readiness gate and startup loader. #12551 unified terminal connection presentation, and #12559 reverted the first-visible-frame recovery path after Nightly reports of indefinitely stuck Cloud overlays. Both fixes are already on current main (f9d2490) and are awaiting a Nightly containing them.

Open PR #12556 is not a complete explanation or a safe replacement: it is based on the pre-#12551 history, is currently merge-conflicting, and adds attachment-owned fallback state for catalog/projection churn. The actual Nightly evidence has complete links, projections, and resolver fallback; the practical user fix is #12551+#12559 in a newer Nightly. This PR does not duplicate those runtime changes.

Diagnostics

• Link breadcrumbs now include a per-connect correlation and explicit started/connected/failed outcomes, including preflight failures.
• Attachment resolver, projection, phase, retry, give-up, and presentation logs now include a stable per-attachment correlation and explicit outcomes.
• Materialization passes the same correlation from resolver to native mirror session and presentation ownership.
• Diagnostics contain only machine/terminal identities, state labels, surface/placement identifiers, and private-annotated reason text; no terminal contents or command payloads are logged.
• Added runtime coverage that a materialization can carry one correlation through resolver and session.

Validation

Passed:

• swiftc -parse on all changed Swift files
• python3 scripts/swift_file_length_budget.py
• bash scripts/lint-pbxproj-test-wiring.sh
• python3 scripts/check-package-resolved-policy.py
• python3 scripts/check-workspace-package-groups.py --check
• python3 scripts/localization_catalog.py check
• git diff --check

The tagged reload was attempted twice and reached the app module, but current main fails on the pre-existing CmuxTuiSurfaceProviders.swift:715 visibility error (pendingRemoteRename exposes a private type). The warning-budget report contains two unrelated existing warnings; none reference the changed files. No app launch, Nightly restart, VM mutation, deployment, or merge was performed.

Closes #12567

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

---

Summary by cubic

Adds end-to-end correlation IDs to Cloud terminal link and attachment logs so multi-machine stuck states can be traced without exposing terminal contents. This is diagnostics only; runtime behavior is unchanged, and it does not fix the underlying stuck-terminal bug (#12567).

• Link breadcrumbs now carry a per-connect correlation and explicit started/connected/failed outcomes, including preflight failures.
• Resolver, projection, phase, retry, give-up, and presentation logs share one correlation per attachment transaction.
• The correlation is generated at materialization and passed through the resolver and native mirror session.
• Adds a test that a single correlation flows from resolver to session.

^{Written for commit a5410da. Summary will update on new commits.}

Summary by CodeRabbit

• Observability
  • Added consistent correlation IDs across cloud terminal attachment and manual mirror activity, making related events easier to trace.
  • Cloud link and attachment events now record explicit outcomes, including start, connection, failure, and recovery-related states.
  • Presentation transitions now include visibility, binding, phase, and presentation status.
  • Diagnostic presentation records exclude terminal contents and payloads.

[github-actions]

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

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 0709a8c9-eecb-414d-9739-e1af11845d8d

📥 Commits

Reviewing files that changed from the base of the PR and between 4efabf8 and a5410da.

📒 Files selected for processing (7)

• Sources/Cloud/CloudMachineLinkManager.swift
• Sources/Cloud/CloudTerminalAttachmentLog.swift
• Sources/Cloud/CloudTuiManualMirrorSession.swift
• Sources/CloudTerminalOverlayCoordinator.swift
• Sources/Surfaces/CloudTerminalAttachmentResolver.swift
• Sources/Surfaces/CmuxTuiSurfaceProvider+ManualMirror.swift
• cmuxTests/CloudTerminalAttachmentRecoveryTests.swift

---

📝 Walkthrough

Walkthrough

Cloud link and terminal attachment diagnostics now carry correlation IDs and explicit outcomes. Manual mirror creation propagates one ID through the resolver and session. Presentation transitions log correlated state. Tests verify shared ID propagation.

Changes

Cloud attachment diagnostics

Layer / File(s)	Summary
Diagnostic logging contracts Sources/Cloud/CloudTerminalAttachmentLog.swift, Sources/Cloud/CloudMachineLinkManager.swift	Attachment and link events now include correlation IDs and explicit outcomes. Presentation logging records machine, terminal, destination, visibility, binding, phase, and presentation state without terminal contents or payloads.
Correlation ID propagation Sources/Surfaces/CloudTerminalAttachmentResolver.swift, Sources/Surfaces/CmuxTuiSurfaceProvider+ManualMirror.swift, Sources/Cloud/CloudTuiManualMirrorSession.swift	Manual mirror materialization generates or accepts one correlation ID and passes it to the resolver and session. Both expose the ID through attachmentCorrelationID.
Presentation diagnostics and validation Sources/CloudTerminalOverlayCoordinator.swift, cmuxTests/CloudTerminalAttachmentRecoveryTests.swift	Overlay presentation transitions use the session correlation ID. A test verifies that the resolver and session retain a supplied ID.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature · Severity of issue fixed: Medium

Suggested reviewers: lawrencecchen

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch issue-12567-cloud-machine-connectivity

---

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.}