Control socket: never present resume approval UI from surface.resume.set (#13369)

[teamleaderleo]

Fixes #13369. This is a smaller alternative to #13397 by @austinywang. It takes only the "never park a socket command on modal UI" half of that PR.

Problem

surface.resume.set over the control socket called NSAlert.runModal() inside the command's main-actor job whenever the proposed command had no approval record (controlSurfaceResumeSet → surfaceResumeBindingWithApproval → surfacePromptForResumeApproval). The hang sample in #13369 shows this stack. While the alert was up, the command coordinator was parked on the main actor, so the socket stopped answering and new clients got Broken pipe.

Resulting behavior

• A socket or CLI surface.resume.set never presents approval UI. A binding that still needs approval is stored without resume trust (auto_resume: false, no approval record). It stays available for manual restore, which is already the default for socket-created commands.
• The reply now has approval_required (true/false). It tells the caller whether a person still has to approve the command in cmux. It appears only on surface.resume.set replies.
• The terminal's Resume Commands context menu still shows the "Allow Resume Command?" prompt. That path is user-initiated and was already modal (it runs from the editor alert).

The decision is made where the request enters. controlSurfaceResumeSet (the socket entry) passes .controlSocket, and the context menu passes .userInterface. SurfaceResumeApprovalStore.proposalNeedsApproval is now the trust policy alone. The main-thread and XCTest checks stay in shouldPromptForProposal.

Why this option and not an async prompt

The socket policy (skills/cmux-socket-policy) says a socket command must not steal focus or raise windows unless focus is what it is for. An app-modal approval alert does both, so the socket path should not present one at all.

Replying first and then showing the alert from a main-queue job does not fix the wedge. A nested runModal started from a main-queue job does not drain the main queue, so every other socket command's main hop still starves while the alert is up. Fixing that needs a non-modal, queued, coalescing prompter, and that is most of #13397's 2,600 lines.

The cost: a script that proposes a command can no longer surface the approval prompt. To approve it, the user sets the command from the context menu or changes the signed prefix in Settings > Terminal > Resume Commands. docs/agent-hooks.md now says so.

Validation

• Commit 1 (e4ab87a) adds only cmuxTests/SurfaceResumeSocketApprovalTests.swift, which is wired in project.pbxproj. The test drives surface.resume.set through the real v2 dispatcher (TerminalController.handleSocketLine) with a command that no approval record matches. It expects approval_required: true and the binding stored untrusted. On main the reply has no such field, so the test fails. A second case checks that a trusted agent-hook binding reports approval_required: false.
• Package tests: swift test in Packages/macOS/CmuxControlSocket passed 463 tests in 59 suites locally, before the new payload tests moved into their own file. After the move, the two ControlCommandCoordinatorSurface* suites passed 30 tests, including the new ControlCommandCoordinatorSurfaceResumeApprovalTests (the approval_required field on set, and its absence on get).
• Not compiled locally for the app target. A cmux-unit build-for-testing in a tagged DerivedData directory failed with No space left on device: the Mac had about 1 GiB free, shared with other agents' builds. The app and cmuxTests compile check is left to this PR's CI. The package changes compiled and passed their tests (above).
• ./scripts/lint-pbxproj-test-wiring.sh passes. Every touched Swift file stays within its merge-base line budget. The approval helpers moved into a new Sources/TerminalController+SurfaceResumeApproval.swift for this.
• I did not run the app-host tests locally or launch the app. The app-host suite is red on main for unrelated reasons (Make app-host unit tests green on main #13643), so its CI result here will not cleanly show commit 1 red and commit 2 green.

Remaining gap

• The test host refuses the modal under XCTest on main as well, so no test observes the wedge itself. The regression test shows that the socket path takes the no-prompt branch and reports it. It does not show a modal being avoided at runtime.
• This PR does not touch Control socket: bound main-actor hops, answer rejected clients, expire stale jobs (#13369 second half) #13397's second half: bounded main-actor hops, overload replies instead of EPIPE, and pending-job expiry. Any other command that stalls the main actor can still fill the connection pool the same way. Control socket: bound main-actor hops, answer rejected clients, expire stale jobs (#13369 second half) #13397 remains the place for that.
• Localization: no user-facing strings were added or changed. The new reply field is a JSON key, and the docs edit is English-only docs/agent-hooks.md.

🤖 Generated with Claude Code

---

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

---

Summary by cubic

Fixes #13369. surface.resume.set over the control socket called NSAlert.runModal() inside the command's main-actor job when the proposed command had no approval record, parking the command coordinator on the main actor and stopping the socket from answering (new clients got Broken pipe). The socket path now never presents approval UI.

• A socket or CLI surface.resume.set stores a binding that still needs approval without resume trust (auto_resume: false, no approval record); it stays available for manual restore.
• The reply now carries approval_required (true/false) on surface.resume.set, telling the caller whether a person still has to approve the command in cmux.
• The terminal's Resume Commands context menu still shows the "Allow Resume Command?" prompt; that path is user-initiated.
• The entry point decides: the socket passes .controlSocket, the context menu passes .userInterface. SurfaceResumeApprovalStore.proposalNeedsApproval is now the pure trust policy, and the approval helpers moved into Sources/TerminalController+SurfaceResumeApproval.swift.
• docs/agent-hooks.md now notes that CLI and socket requests never show the prompt and that approval is done in the app.

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

[coderabbitai]

Warning

Review limit reached

Next included review available in 23 minutes.

Check out review usage here.

View limit details

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

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

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Repository: manaflow-ai/cmux/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: e56f3dee-96a4-4bef-a87f-8a3f1ed2476c

📥 Commits

Reviewing files that changed from the base of the PR and between e0b52a8 and 965fa5d.

📒 Files selected for processing (11)

• Packages/macOS/CmuxControlSocket/Sources/CmuxControlSocket/Coordinator/Surface/ControlCommandCoordinator+Surface3.swift
• Packages/macOS/CmuxControlSocket/Sources/CmuxControlSocket/Coordinator/Surface/ControlSurfaceContext.swift
• Packages/macOS/CmuxControlSocket/Sources/CmuxControlSocket/Coordinator/Surface/ControlSurfaceResumeSnapshot.swift
• Packages/macOS/CmuxControlSocket/Tests/CmuxControlSocketTests/ControlCommandCoordinatorSurfaceResumeApprovalTests.swift
• Sources/GhosttyNSView+ForkConversationContextMenu.swift
• Sources/SessionPersistence.swift
• Sources/TerminalController+SurfaceResumeApproval.swift
• Sources/TerminalController+SurfaceResumeBindings.swift
• cmux.xcodeproj/project.pbxproj
• cmuxTests/SurfaceResumeSocketApprovalTests.swift
• docs/agent-hooks.md

---

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