Report search-related terminal close freezes

[miracle2k]

Summary

This PR documents a freeze I have been hitting frequently in the local cmux macOS app. The common pattern is that terminal search/find state is active or recently active, then a terminal surface is closed or torn down, and the app becomes unresponsive with the spinner.

I am opening this primarily as a problem report plus a concrete possible fix path. The diagnosis and proposed fix are entirely AI-suggested, so they should be treated as a candidate explanation/patch that needs careful review rather than a fully human-audited conclusion.

What was observed

A sampled hung cmux process showed the main thread blocked in Ghostty surface teardown:

• ghostty_surface_free
• Surface.deinit
• pthread_join

The join point appears to be the per-surface Ghostty search thread shutdown.

Suspected cause

The suspected deadlock is:

1. cmux closes/frees a terminal surface on the app/main thread.
2. Ghostty asks the search thread to stop and synchronously joins it.
3. The search thread emits final search UI callbacks while exiting.
4. Those callbacks can wait forever while pushing renderer/app mailbox messages.
5. If the app/main thread is already waiting in the join and the mailbox is full, both sides can wait forever.

Possible fix

I opened the AI-suggested Ghostty-side patch here:

• Avoid search-thread deadlocks during surface teardown ghostty#55

The proposed patch makes search-thread callback delivery bounded/best-effort during teardown, so stale search UI reset messages cannot block surface destruction forever.

Local validation

The linked Ghostty patch was built locally into GhosttyKit and a tagged cmux debug build completed successfully:

zig fmt --check ghostty/src/Surface.zig
zig build -Demit-xcframework=true -Demit-macos-app=false -Dxcframework-target=universal -Doptimize=ReleaseFast
./scripts/reload.sh --tag fix-search-shutdown-hang

Caveat

The freeze is real and it has been happening a lot for me locally. The root-cause analysis and fix are AI-assisted. Please review the Ghostty PR carefully, especially around search-thread callbacks, mailbox backpressure, and surface teardown ordering.

---

Summary by cubic

Adds a report on a freeze when closing a terminal surface while search is active or recently active. It captures a suspected join deadlock in Ghostty surface teardown, links to a proposed upstream patch, and notes local build validation.

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

Summary by CodeRabbit

• Documentation
  • Added documentation describing a known macOS terminal freeze issue occurring during shutdown with active search functionality. Includes stack trace evidence, suspected deadlock analysis, reference to proposed solution, and comprehensive validation steps for local testing.

[vercel]

@miracle2k is attempting to deploy a commit to the Manaflow Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds a new documentation page analyzing a reproducible macOS cmux freeze that occurs during Ghostty terminal surface teardown when terminal search is active. The report includes an observed stack trace, a suspected deadlock hypothesis involving search-thread callbacks and mailbox blocking, a reference to a proposed Ghostty fix, and local validation steps.

Changes

Search Shutdown Freeze Analysis

Layer / File(s)

Summary

Search shutdown freeze report docs/search-shutdown-freeze-report.md

New documentation describing a reproducible cmux freeze during terminal teardown with active search state, including the observed pthread_join hang in Surface.deinit, suspected deadlock sequence involving search-thread callbacks waiting on mailbox queue progress, link to Ghostty PR #55 proposing bounded/best-effort callback delivery during teardown, local build/reload validation procedure, and caveat that analysis and fix are AI-assisted.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

A freeze caught mid-search, a tale to be told,
Stack traces whisper of deadlocks cold.
With bounded queues and patches in sight,
We document the journey through the terminal night. 🐰✨

---

Caution

Pre-merge checks failed

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

• Ignore

❌ Failed checks (1 error)

Check name	Status	Explanation	Resolution
Cmux Swift Actor Isolation	❌ Error	Implicit @MainActor static lets accessed from nonisolated function in RightSidebarBetaFeatureSettings violates Swift 6 actor isolation rules.	Add nonisolated keyword to feedEnabledKey and defaultFeedEnabled static properties

✅ Passed checks (14 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically summarizes the main change: documenting a search-related terminal close freeze issue in the cmux app.
Description check	✅ Passed	The description covers the required template sections: Summary (what changed and why), Testing (local validation steps), and most checklist items; however, the Demo Video section is not included and some checklist items are not explicitly marked.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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 Swift Blocking Runtime	✅ Passed	PR adds only documentation file (docs/search-shutdown-freeze-report.md). No production Swift code changes. Check applies only to production code.
Cmux No Hacky Sleeps	✅ Passed	PR contains only documentation (docs/search-shutdown-freeze-report.md). No runtime code modifications in TypeScript, JavaScript, shell or build scripts. Check applies only to production code changes.
Cmux Swift Concurrency	✅ Passed	PR adds only documentation (docs/search-shutdown-freeze-report.md, +62 lines). No Swift code changes or legacy async patterns introduced.
Cmux Swift @Concurrent	✅ Passed	PR adds nonisolated synchronous pure helper function. Allowed case per rules: "nonisolated synchronous pure helpers." No @concurrent violations detected.
Cmux Swift File And Package Boundaries	✅ Passed	This PR is documentation-only, adding a single markdown file that describes a bug report. No Swift files were added or modified, making the Swift file and package boundaries check inapplicable.
Cmux Swift Logging	✅ Passed	PR adds documentation-only content (docs/search-shutdown-freeze-report.md). No Swift code changes present. Custom check applies only to production Swift changes, which this PR does not contain.
Cmux Swiftui State Layout	✅ Passed	This PR is documentation-only (adds docs/search-shutdown-freeze-report.md). No SwiftUI or code changes present. The custom check for SwiftUI state layout violations is not applicable.
Cmux Architecture Rethink	✅ Passed	Documentation PR reporting a Ghostty deadlock. Code changes (test locks, UI dispatch, pasteboard logic) are appropriate. No symptom patches, timing hacks, or architectural violations detected.
Cmux Swift Auxiliary Window Close Shortcuts	✅ Passed	All Swift window changes comply with the rule. Main workspace windows (cmux.main.) are allowed. Auxiliary windows have proper cmux. identifiers and registration. Lint passed.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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 and usage tips.}

[greptile-apps]

Greptile Summary

This PR adds a documentation file (docs/search-shutdown-freeze-report.md) that records a reproducible macOS app freeze and links a candidate Ghostty-side fix. No production Swift or runtime code is changed.

• The document describes a suspected deadlock between Surface.deinit's synchronous pthread_join on the search thread and the search thread's final mailbox pushes, with a stack trace sample and step-by-step causation analysis.
• A proposed fix is referenced via a linked external Ghostty PR; local validation commands are included; the document is explicitly marked as AI-assisted analysis requiring human review.

Confidence Score: 5/5

This PR is safe to merge — it adds only a documentation file with no production code changes.

The change is a single new markdown document. It makes no modifications to Swift source, runtime behavior, build configuration, or any executable path. The document is clearly written, honestly discloses its AI-assisted provenance, and accurately points the actual fix to an external PR for proper review.

No files require special attention; the only change is a new documentation file.

Important Files Changed

Filename	Overview
docs/search-shutdown-freeze-report.md	New documentation file recording a search-shutdown freeze report with stack trace, deadlock analysis, proposed fix link, and local validation steps; no code changes.

Sequence Diagram

sequenceDiagram
    participant AppThread as App/Main Thread
    participant SearchThread as Ghostty Search Thread
    participant Mailbox as Renderer/App Mailbox

    AppThread->>AppThread: Close/free terminal surface
    AppThread->>SearchThread: Signal stop (Surface.deinit)
    AppThread->>AppThread: pthread_join (WAITING)
    Note over AppThread: blocked here

    SearchThread->>SearchThread: Emit final UI callbacks
    SearchThread->>Mailbox: Enqueue renderer/app messages
    Note over Mailbox: Mailbox full, indefinite wait

    Mailbox-->>SearchThread: blocked waiting for space
    SearchThread-->>AppThread: Never returns from join

    Note over AppThread,Mailbox: DEADLOCK: both sides wait forever

Loading

_{Reviews (1): Last reviewed commit: "Document search-related freeze investiga..." | Re-trigger Greptile}