macOS agent.sock: breeze group created but never applied, blocking user-helper IPC

[ToddHebebrand]

Reported by semotech in #bugs (Discord, message 1534257683362742472).

Report (PII-redacted):

Thanks — useful. On this 2019 iMac (macOS 14.7.2 / amd64 / agent 0.103.0):

Terminal: matches what we saw (paste reordering). Session drop on launchctl kickstart -k system/com.breeze.agent understood. We'll retest terminal paste after next agent build past 0.103.0.

Helper: User already toggled Screen Recording ON for breeze-desktop-helper (off→on), FDA ON, Admin user, reboot — TCC prompt still returns. LaunchAgent com.breeze.desktop-helper-user crash-looped (runs≈133, last exit 1). When run manually as jingxie we got:

• screenRecording=false / captureGranted=false (ScreenCaptureKit timeout) even while Settings showed the toggle ON
• accessibility=true, fullDiskAccess=true
• fatal: dial unix ".../Breeze/agent.sock": permission denied
• sock was srw-rw---- root:admin — chmod 666 let us proceed; after reboot sock likely recreated tight again
• from Breeze root PTY, launchctl kickstart/bootstrap on gui/<uid>/… returns 125 Domain does not support specified action (Aqua domain not manageable from agent terminal)

Will pull "/Library/Application Support/Breeze/desktop-helper.log" next. Questions:

1. Intended agent.sock mode/owner for user-session helper? admin-only 660 breaks non-admin (and we still saw denied before chmod).
2. Known issue where Screen Recording toggle shows ON but helper still reports screenRecording=false until a GUI-session restart of the helper (not reboot alone)?
3. Recommend path when gui launchctl returns 125 from remote terminal?

Filed automatically by @breeze-discord triage. Verify and add labels/repro as needed.

Triage analysis

The macOS agent IPC socket permission model is broken for exactly the case the reporter hit: a non-root user-session helper connecting to /Library/Application Support/Breeze/agent.sock. broker_unix.go's setupSocket() chmod's the socket to 0660 (owner+group only) but never chowns it — the group stays whatever the root launchd process's default primary group is (not breeze). Both real install paths — the DMG postinstall script (agent/installer/macos/postinstall) and the programmatic breeze-agent service install path (service_cmd_darwin.go -> ensureDarwinBreezeGroup) — only create the breeze group; neither ever chowns the config dir/socket to root:breeze, nor adds any user to that group. Contrast with agent/scripts/install/install-linux.sh, which both chowns /var/run/breeze to root:breeze AND auto-adds every logged-in user to the breeze group. So on macOS, unless an admin manually runs dscl . -append /Groups/breeze GroupMembership <user> (only documented as a manual step in the standalone bash installer, not the shipped DMG flow), no console user — admin or not — is in the socket's owning group, so LOCAL_PEERCRED-gated 0660 perms deny them, matching the reporter's observed srw-rw---- root:admin, permission-denied dial, and the fact chmod 666 was needed to proceed (and would reset on next agent restart since setupSocket() re-chmods to 0660 every start).

Affected code

• agent/internal/sessionbroker/broker_unix.go:12-37 — setupSocket() chmods dir 0755 and socket 0660 on every start but never chowns either to a group that real users belong to
• agent/internal/agentapp/service_cmd_darwin.go:235-238,610-633 — ensureDarwinBreezeGroup() only dscl-creates the 'breeze' group; no chown of CONFIG_DIR/socket, no user added
• agent/installer/macos/postinstall:15-33,68-69 — Shipped DMG postinstall: same gap — creates breeze group, never wires it to the socket or any user
• agent/scripts/install/install-linux.sh:126-172 — Contrast: Linux installer chowns IPC dir to root:breeze and auto-adds every logged-in user to breeze group — the macOS equivalent step is missing

Potential fix

On macOS, chown the socket (or its parent dir with setgid) to root:breeze in setupSocket()/service install, and either auto-add the console user to the breeze group at helper-bootstrap time (mirroring install-linux.sh) or document the manual dscl step in the DMG/postinstall flow, not just the standalone bash installer.

Triage analysis, affected code, and fix sketch above were produced by automated investigation (@breeze-discord). Verify before relying on them.

[SemoTech]

Follow-up to "macOS Remote Desktop permission stuck Missing — Desktop unavailable" (agent 0.103.0).

1. Healthy: MBP M4 Max, 15.7.8 arm64 — FDA/SR/A11y/RD all Granted; Desktop Ready After User Login. loginwindow helper disabled; agent.sock srw-rw-rw-; user_session helper as console Admin.
2. Broken same OS: MBA M1, 15.7.8 arm64 — FDA/SR/A11y Granted; RD Missing; Desktop Unavailable; Helper Not Connected (offline at check).
3. Older: MBA Intel, 12.7.6 amd64 — FDA/SR Granted; A11y Missing; RD Unknown; Desktop Unavailable.
4. Prior: 2019 iMac, 14.7.2 amd64 — RD Missing + loginwindow SR popup loop; sock 660 root:admin blocked user helper until chmod 666.

DB: healthy = remoteDesktop:true + user_session; broken = helper_not_connected (RD false despite other grants) or missing_permission (FDA/A11y false — often shared local account). Not OS-only (15.7.8 in both). API drops malformed term-command_result keys (written/cols/rows) — garbled remote terminal.

Need guidance: how RD TCC is granted/detected; why Helper Not Connected when SR+A11y+FDA Granted; intended sock perms Admin vs Standard; whether disabling loginwindow helper is supported.

[ToddHebebrand]

Thanks for the four-machine matrix — that's exactly the data needed to answer this precisely. Taking your questions in order, everything below verified against current agent code.

1. How Remote Desktop TCC is detected. The "Remote Desktop" status is not read from a TCC flag at all — it's a live probe. agent/internal/userhelper/tcc_darwin.go runs a real ScreenCaptureKit capture attempt (desktop.ProbeCaptureAccess()), while the "Screen Recording" line you see uses CGPreflightScreenCaptureAccess (with a CGWindowListCreateImage fallback on newer macOS). They are independent signals, which is why FDA/SR/A11y can all read Granted while RD reads Missing or Unknown: the preflight says the permission bit is set, the probe says an actual capture worked from the helper's context. If the helper isn't running or can't answer, the probe has no result — and a nil probe result is mapped to helper_not_connected, not missing_permission (desktop_access_darwin.go). That's exactly your MBA M1 row: RD false with everything else granted, because the machine was offline/asleep at check time and the probe never ran.

2. Why "Helper Not Connected" with all grants fine. The reason string is derived from the session broker's view of connected helper sessions, and it wins over TCC state: no live helper session (or no TCC report from one) → helper_not_connected, regardless of grants. There was a real bug in this area — helper LaunchAgents were written to disk at install but never launchctl bootstrap'd — and the current code fixes it on install, on service start, and re-checks on daemon startup, so it self-heals within about a minute of a user session existing. If a machine that is online and logged-in still shows Helper Not Connected persistently, grab the agent diagnostic logs from that window and I'll dig in.

3. Socket permissions — your observation found a real bug, and the healthy machine is the anomaly. The intended design is 0660 with a dedicated breeze group so Standard (non-admin) users' helpers can connect. What actually ships: the group is created but never applied to the socket — every daemon start recreates agent.sock and chmods it 0660 with whatever group the root daemon inherits (typically admin, matching your iMac). So Standard users are always locked out, and Admin users work only incidentally. That's tracked as #3133/#3134. Your healthy MBP's srw-rw-rw- is not something any shipped code produces — I grepped the agent tree for a 0666 chmod and there is none — so that's the manual chmod 666 workaround (same one you applied on the iMac) surviving until the next agent restart, at which point it reverts to 0660. Until #3133 ships, the manual chmod is the workaround, and it needs reapplying after restarts.

4. Disabling the loginwindow helper is not an officially supported toggle, but it costs you nothing real. Apple blocks synthetic input at the login window without a private entitlement, so the loginwindow helper's WebRTC desktop control can never actually function there — the agent already reports that path unsupported and falls back to the VNC relay, which drives Apple's built-in ARDAgent and is entirely independent of the Breeze loginwindow LaunchAgent. Disabling it stops the Screen Recording prompt loop you saw on the iMac and removes no working capability. I'd still call it a workaround rather than a supported configuration until we make it one.

On the malformed term-command_result keys garbling the remote terminal — that's a separate defect from everything above; please file it as its own issue with a sample of the dropped payload if you have one, so it doesn't get lost in this thread.

Status: #3133/#3134 (socket group never applied) are the confirmed bugs from your matrix; RD detection and Helper Not Connected are behaving as designed, with the design explained above.

[SemoTech]

Thanks @ToddHebebrand that clears it up.

I'll keep two workarounds until #3133/#3134 ship in an agent release:

1. chmod 666 on agent.sock after install/restart (aware it reverts to 0660 on daemon start)
2. disable/move com.breeze.desktop-helper-loginwindow.plist to stop SR prompt spam

I'm on agent 0.103.0 — please flag which release will include the socket-group fix and the LaunchAgent bootstrap self-heal so I know when to drop the workarounds.

Have opened a separate issue for the malformed term-command_result / garbled remote terminal (API dropping written/cols/rows keys) - #3163

One follow-up question:

For an online, logged-in Mac that still shows Helper Not Connected after ~1 min, which diagnostic log paths/commands do you want (agent.log vs desktop-helper.log under Application Support/Breeze/logs)?