Pairing, TCC, and iteration amendment — 2026-07-15
This section supersedes the “code-only or broker-handoff” language below.
- Code-only public pairing is mandatory. An authenticated broker handoff may be an optional convenience, but it cannot replace or bypass the public code path.
- The backend authority for issue/redeem is https://github.com/electricsheephq/electric-sheep-website-dashboard-6158a244/issues/669.
- Permission guidance and proof must name the exact TCC-granted executable and its designated code requirement; “app/helper” is not sufficiently precise.
- The native Mac Access app/helper must build without
packages/desktop or a full Workbench build.
- Add path-gated focused CI and record incremental and clean native build times. Initial advisory budgets: under two minutes incremental and under five minutes clean, pending measurement.
#701 cannot close from UI fixtures alone; code entry must integrate with the frozen #669 contract without exposing codes or relay credentials to renderer, logs, screenshots, or default diagnostics.
Parent epic: #698
Depends on: #699. Integrates with #700.
Context
Customers who only need VM-agent access to their Mac should not install or understand the full Workbench. They need a native, low-friction menu-bar product that explains connection and permission state and makes remote access immediately controllable.
Required change
Build packages/mac-access as a native Swift/AppKit or SwiftUI menu-bar app with stable bundle/helper identities. It owns onboarding, Keychain custody, connector-core lifecycle, macOS permission handoff, local notifications, and the visible safety controls.
Required experience
- no Dock icon during normal operation;
- one menu-bar icon whose state is distinguishable without opening a window;
- dropdown states:
Disconnected, Connecting, Approval needed, Connected, Paused, and Blocked;
- actions: connect/disconnect, pair/unpair, access mode, permissions, last activity, pause, revoke selected VM, emergency stop, diagnostics, update, quit;
- a first-run window only when onboarding or recovery needs more space;
- code-only or broker-handoff pairing with no endpoint/token/private-network material shown;
- permission guidance that names the exact signed app/helper the user must approve and deep-links to the correct macOS settings pane;
- clear recovery for denied permission, stale pairing, revoked grant, offline broker, core crash, update required, and conflicting Workbench connector ownership.
Acceptance criteria
- A fresh user can install, open, pair, grant permissions, and reach a truthful connected/blocked state without Workbench or a terminal.
- The app uses bundle ID
com.evaos.mac-access; the helper uses com.evaos.mac-access.helper; any LaunchAgent uses com.evaos.mac-access.connector.
- App/helper code-signing requirements are verified before connector start, and identity mismatch fails closed with a typed blocker.
- Pairing secrets and connector credentials are stored only in Keychain/native custody and never appear in SwiftUI state, pasteboard, screenshots, analytics, or default diagnostics.
- TCC state is read and presented truthfully. The app never claims permission from a fixture or attempts to bypass macOS consent.
- Closing onboarding leaves the menu-bar service running; Quit performs an orderly disconnect and leaves no remote-control path.
- Crash/relaunch restores safe state, never silently upgrades
Off or Ask Every Time to Full Access, and surfaces an interrupted action safely.
- All user-facing strings are localized through the repository's supported localization workflow.
- Accessibility labels and keyboard navigation cover the menu and onboarding window.
- Unit/UI tests cover every visible state and recovery branch.
Testing plan
- pure view-model/state-machine tests;
- Keychain and lifecycle adapters with fakes;
- signed helper identity negative tests;
- permission denied/revoked/stale fixtures;
- crash/relaunch and quit cleanup;
- menu-bar accessibility/UI automation on GitHub macOS runners where supported;
- exact installed-app path smoke on a signed candidate before any release claim.
Rollback
The app remains unpublished until packaging/proof issues pass. A failed prototype is removed by reverting its isolated PR without touching Workbench v2.1.36 or the shared core contract.
Non-goals
- no Windows or Linux UI;
- no iPhone Mirroring;
- no embedded Workbench screens;
- no customer rollout or public release in this issue.
Pairing, TCC, and iteration amendment — 2026-07-15
This section supersedes the “code-only or broker-handoff” language below.
packages/desktopor a full Workbench build.#701 cannot close from UI fixtures alone; code entry must integrate with the frozen #669 contract without exposing codes or relay credentials to renderer, logs, screenshots, or default diagnostics.
Parent epic: #698
Depends on: #699. Integrates with #700.
Context
Customers who only need VM-agent access to their Mac should not install or understand the full Workbench. They need a native, low-friction menu-bar product that explains connection and permission state and makes remote access immediately controllable.
Required change
Build
packages/mac-accessas a native Swift/AppKit or SwiftUI menu-bar app with stable bundle/helper identities. It owns onboarding, Keychain custody, connector-core lifecycle, macOS permission handoff, local notifications, and the visible safety controls.Required experience
Disconnected,Connecting,Approval needed,Connected,Paused, andBlocked;Acceptance criteria
com.evaos.mac-access; the helper usescom.evaos.mac-access.helper; any LaunchAgent usescom.evaos.mac-access.connector.OfforAsk Every TimetoFull Access, and surfaces an interrupted action safely.Testing plan
Rollback
The app remains unpublished until packaging/proof issues pass. A failed prototype is removed by reverting its isolated PR without touching Workbench v2.1.36 or the shared core contract.
Non-goals