macOS: what "Quit" does, and which first-run prompts YazSes raises¶

Evidence note for #578 (a daemon survived "Quit") and #562 (a fresh .dmg install on macOS 26.6.2 shows no permission prompt). Written from the code and the reporter's daemon.log; nobody on this project has a Mac, so every statement about what macOS does is marked. Status labels: READ = seen in this repository's source or in the reporter's pasted log; DOC = from Apple documentation as recalled, not re-fetched here; UNVERIFIED = needs a real Mac.

1. The process model (READ)¶

launchd (render_launch_agent): RunAtLoad true, KeepAlive is {Crashed: true} only. By the plist's own semantics a clean exit after SIGTERM or an IPC shutdown is not restarted (UNVERIFIED on a Mac; DOC for KeepAlive). So the launchd agent is not the reason a daemon survived Quit. Nothing was changed in the plist.

2. What Quit did before this change (READ for the code, UNVERIFIED for the mechanism)¶

MacosTray.run built rumps.App("YazSes", ...) with rumps' default quit button and then called self._app.run() followed by self._on_quit(). The on-quit callback is what sends the IPC shutdown (tray/app.py::_on_quit). rumps' built-in Quit calls NSApplication.terminate:, and AppKit's NSApplicationMain never returns (DOC), so the line after run() very probably never executed. The Windows tray puts the same call in a finally around icon.run(); the macOS one had no equivalent.

This explains every line of the #562 log without a second hypothesis:

• 2026-10-02 10:16 the daemon starts (tray pid 1303 launched by the daemon exits at once: the user's own tray holds tray.lock).
• 2026-10-05 16:17:01.129 the supervisor finds tray.lock free and relaunches a tray. The tray the user quit was gone; no Shutting down. line was ever written by that daemon, i.e. the shutdown RPC never arrived. That is the answer to "why did the supervisor say tray is not running while the lock was held": the lock was not held at that moment.
• The text under "it said: A YazSes tray is already running" is not about the tray that just died. _last_tray_error reads tray-stderr.log, which holds the stderr of the last tray the daemon launched, that is the duplicate from 10-02 that exited at once. It is a stale, misleading attachment (not fixed; see section 6).
• 16:17:01.842 the relaunched tray found lifecycle.is_running() false (the case-sensitive process-name bug, already fixed on main in 1e20ebd3), spawned a second daemon, and that one exited "Another YazSes daemon is already running".

What would falsify this: ps aux | grep -i [y]azses after pressing Quit on a build with the new menu still listing a daemon.

3. What was changed for Quit¶

The Quit fix that shipped is v2.43.1's (7326b59f): platform/macos/tray.py registers the shutdown call on rumps' before_quit event, which fires from applicationWillTerminate: on the stock Quit path, and keeps the post-run() call as a de-duplicated backstop (tests/test_macos_tray_quit_stops_the_daemon.py). An earlier draft of this note proposed a second mechanism (quit_button=None plus an explicit "Quit YazSes" entry that sent shutdown on a worker thread before rumps.quit_application); it was dropped when this work landed, so that one fix exists, not two. Contract either way: Quit stops the daemon, then the icon. (Linux differs on purpose: its "Quit tray" leaves the daemon running.)

Not changed: MacosHotkey.stop calls CFRunLoopStop from the IPC thread. I believe CFRunLoopStop wakes the loop itself (DOC) and did not add a blind CFRunLoopWakeUp; if a daemon survives an IPC shutdown that did arrive (the log would then contain Shutting down.), that is the next suspect. yazses restart is unaffected: it escalates to SIGKILL.

4. Which first-run prompts exist (READ)¶

Consequences for the #562 flow: after tccutil reset Accessibility com.yazses.app the app is removed from the Accessibility list and, with no request, never re-added; the docs said "On first launch, YazSes triggers macOS to show an Accessibility prompt", which was false. Both new requests share the existing persisted five-minute rate limit (system/diagnosis.should_notify), so a login item cannot put a system dialog up at every start; only an undecided or denied grant asks.

A note on the doctor wording: the "Keyboard capture" row checks Accessibility, but the hotkey tap itself is listen-only and needs Input Monitoring; Accessibility gates typing. The wording was left as is (changing it is a product decision), but it is why a green Accessibility row with a dead hotkey reads as a contradiction.

5. A daemon that predates a grant (#578)¶

The Input Monitoring grant is read when the tap is created (the in-repo comments and the docs say so; UNVERIFIED on a Mac, though System Settings itself offers "Quit & Reopen" for several privacy toggles). The daemon now records the Input Monitoring answer at start and, only if it was not OK, re-asks from its own process (so the answer is about YazSes and not about the terminal a user typed doctor into, the attribution problem in #562), at most every 30 s, and reports stale_permissions: ["input_monitoring"] in status. doctor's Daemon row turns WARN with the restart command. Healthy installs never probe. Daemons built before this change cannot report it; for them doctor's existing version-skew WARN applies.

6. Findings not acted on¶

1. _last_tray_error can attach another launch's stderr to a later death (section 2).
2. Double-clicking the .app starts two trays (the user's, and the daemon's duplicate that exits). Benign, but it makes the log read like an error.
3. docs/macos-install.md still told Sequoia/Tahoe users to right-click Open, which those releases no longer offer for unsigned apps (DOC). The page now leads with Settings → Privacy & Security → Open Anyway, the flow the #562 reporter actually followed.
4. In #562 the reporter's headset microphone stopped working on 10-06; that is hardware and unrelated. mic-level --set choosing three different thresholds is #579.
5. The ad-hoc signature (Signature=adhoc, Internal requirements count=0, from the pasted codesign output) makes the code identity a cdhash, so every build is a new TCC identity. This is the existing, documented reason a grant "stops applying while the toggle looks on"; only signing fixes it (design/packaging/macos-signing.md).

7. UNVERIFIED on a real Mac¶

1. rumps' before_quit event fires on the stock Quit path (from the rumps 0.4.0 source, not run).
2. Quit really stops the daemon, and no tray reappears 20 s later.
3. AXIsProcessTrustedWithOptions(prompt=True) shows a dialog from the background daemon process, and does so once per launch while untrusted.
4. AVCaptureDevice.requestAccessForMediaType:completionHandler: through PyObjC accepts a Python lambda as the block and shows the microphone prompt from a non-GUI process.
5. A grant given after start leaves the existing tap deaf, so a restart is what is needed.
6. Whether the Input Monitoring prompt (IOHIDRequestAccess) appears for a daemon launched by the tray with start_new_session, versus launched by launchd.

8. Questions for the #562 / #578 reporter¶

On a build containing this change (for 1 and 2, v2.43.1 or later):

1. After pressing Quit in the menu bar, what do ps aux | grep -i [y]azses and launchctl list | grep yazses print? Then, 30 seconds later, again.
2. Does the icon come back after Quit? If so, how long after?
3. On first launch after tccutil reset Accessibility com.yazses.app and tccutil reset ListenEvent com.yazses.app and tccutil reset Microphone com.yazses.app: which system dialogs appear, in which order, and what does each say?
4. After switching a toggle on while YazSes is running, what does yazses doctor (run as /Applications/YazSes.app/Contents/MacOS/YazSes --cli doctor) print on the Daemon row?
5. The last 40 lines of ~/Library/Logs/yazses/daemon.log after step 3, and whether Shutting down. appears there after Quit.