[austinywang]

Summary

Backgrounding the iOS terminal no longer clears the phone's confirmed viewport lease by default, so the host keeps the last rendered grid through resume instead of briefly letting the Mac choose a different size. A persisted Settings toggle, Hand Off Terminal Sizing When Inactive, opts into the earlier phone/computer handoff behavior when users want the Mac to own sizing while the phone is inactive.

The change keeps CMUXMobileShellStore's reported viewport and generation as the source of truth, threads the persisted preference through WorkspaceDetailView into the terminal coordinator, and applies the preference before inactive lifecycle cleanup. Enabling the toggle while already inactive releases the lease immediately; disabling it leaves the current lease intact until the next foreground mount.

Fixes #18624

Testing

• Added MobileDisplaySettingsTests coverage for the default-without-write behavior and cross-instance persistence.
• Added TerminalSurfaceMountOwnershipTests coverage for default background/resume lease preservation, explicit opt-in handoff release, and foreground recovery when the output stream has been torn down.
• Addressed the Cursor Bugbot finding: foreground reconciliation now uses the persisted handoff preference when stopping stale mounted tasks, so transient stream recovery cannot release the phone lease unless handoff is enabled.
• Regression-first commits: 4c7ea19b466 records the original behavioral expectation, 4e3dafcb78 records the foreground-recovery regression, and the following fix commits implement each behavior.
• Focused local command: swift test --package-path Packages/iOS/CmuxMobileShellUI --filter 'MobileDisplaySettingsTests|TerminalSurfaceMountOwnershipTests'. The pre-fix and fixed attempts in this checkout could not start because swift is unavailable (/bin/bash: swift: command not found), so zero local tests executed.
• Portable verification: git diff HEAD~2..HEAD --check passed and the changed XCStrings resource parses with python3 -m json.tool. The Swift syntax verifier reported swiftc is unavailable; native compilation and app launch were not checked locally.
• The iOS connectivity soak was not run: this lifecycle change needs a tagged app/device build, while the request explicitly prohibits reproducing on the user's machine. No user-device reproduction or app install was performed.
• CI run 38662110144 built the iOS simulator product. Its first package-test attempt exposed one unrelated flaky IrohMacSwitchRecoveryTests.macSwitchDuringRecoveryKeepsTheSwitchedMac failure; the failed jobs were rerun and the iPhone, iPad, package, and aggregate iOS checks passed.

Changelog

Fixed: iOS terminal sizing keeps its confirmed viewport across background and resume, with an opt-in Mac handoff setting.

Proof

CI-only for this pass. Native app launch and screenshots were intentionally skipped under the no-user-machine-reproduction constraint.

Issue lifecycle

• Pickup comment: iOS: remember resize priority and phone/computer handoff #18624 (comment)
• Resolution comment: pending until this PR merges.

Impact map

• Source of truth and owner: CMUXMobileShellStore's reported viewport and generation; GhosttySurfaceRepresentable.Coordinator owns the viewport lease and inactive lifecycle transition; MobileDisplaySettings persists the opt-in handoff choice.
• Direct callers and sibling entrypoints inspected: WorkspaceDetailView.terminalArtifactSurface, the representable coordinator factory/update path, didChangeWindowAttachment, detach, viewport report/clear methods, and existing terminal mount ownership tests.
• Cross-surface effects: the Settings toggle is localized in all 9 supported iOS locales; desktop sizing policy remains host-owned, and SSH/local terminal surfaces continue through the same coordinator lifecycle.
• Tests and evidence: persistence tests cover relaunch-style settings instances; lifecycle tests cover default lease retention, generation stability, and explicit handoff release.
• Residual risk: a native iOS build and suspended-app visual check remain for CI/device verification because the local SwiftPM package target cannot run on macOS 12 with its macOS 14 dependencies, and user-machine reproduction was explicitly excluded.

Mergeability

• Base SHA: fba804b
• Head SHA: d308b17
• Conflict-only gate: PASS; no conflicted paths (gate ref gate/task-18624-ios-resize-priority-1791493114)

HIG

The Apple Human Interface Guidelines Settings page was consulted for the persisted toggle placement and explanatory footer: https://developer.apple.com/design/human-interface-guidelines/settings

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 9 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 10 included reviews currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: Repository: manaflow-ai/cmux/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 542c435a-aee8-45be-ac24-182fe763b3f2

📥 Commits

Reviewing files that changed from the base of the PR and between fba804b and d308b17.

📒 Files selected for processing: 8

• Packages/iOS/CmuxMobileShellUI/Sources/CmuxMobileShellUI/GhosttySurfaceRepresentable+CoordinatorFactory.swift
• Packages/iOS/CmuxMobileShellUI/Sources/CmuxMobileShellUI/GhosttySurfaceRepresentable.swift
• Packages/iOS/CmuxMobileShellUI/Sources/CmuxMobileShellUI/MobileDisplaySettings.swift
• Packages/iOS/CmuxMobileShellUI/Sources/CmuxMobileShellUI/MobileSettingsView.swift
• Packages/iOS/CmuxMobileShellUI/Sources/CmuxMobileShellUI/Resources/Localizable.xcstrings
• Packages/iOS/CmuxMobileShellUI/Sources/CmuxMobileShellUI/WorkspaceDetailView+TerminalArtifacts.swift
• Packages/iOS/CmuxMobileShellUI/Tests/CmuxMobileShellUITests/MobileDisplaySettingsTests.swift
• Packages/iOS/CmuxMobileShellUI/Tests/CmuxMobileShellUITests/TerminalSurfaceMountOwnershipTests.swift

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 6a9daba. Configure here.}

[austinywang]

Addressed the Cursor Bugbot high-severity finding in d308b17b44c91d750ca1b3214a6b1c21fd48111f. Foreground recovery now passes the persisted handoffTerminalSizingWhenInactive preference into stopMountedTasks, so losing the output consumer during reconciliation does not release the phone viewport lease by default. Added foreground recovery preserves the viewport lease by default to TerminalSurfaceMountOwnershipTests to cover the stream-loss resume path and generation stability.

[austinywang]

Closeout verification update:\n\n- The PR head matches the verified local and remote branch head.\n- The PR is open, non-draft, mergeable, and clean.\n- Required checks are green or intentionally skipped.\n- No unresolved review threads remain.\n\nThis PR is ready for review. No merge was performed.

[github-actions]

Merge receipt for d308b17b44: every check was green at merge (16 verified; 16 skipped by policy). Full suite runs on main after merge.