Overall Plan — Mac Brian Control Center

Overall Plan — Mac Brian Control Center

Architecture pivot 2026-05-09 (later afternoon, Jonah): v4 — HeyBrian app becomes the host of everything. User installs HeyBrian, gets the whole system. App closed → everything down. mac.jonahtebaa.com is the same product viewed remotely.
Source-of-truth design: 02_v4_heybrian_consolidated.md (codex round-table integrated). 01_control_center_architecture.md keeps the wire protocol (HMAC, /v2/action, capability registry) that v4 inherits.
Status keys: DONE | IN PROGRESS | TO DO

Already shipped (v3 — v4 will reuse these as the wire protocol)

• Lua control center on Hammerspoon — DONE
• hs.httpserver:8765, HMAC-verified /v2, /v2/action (12 executors), /v2/caps, /cpanel, capability registry at ~/.brian/capabilities.json, audit log + size rotation, in-memory metrics, breathing 4-layer cyan border, clickable pause/stop pill, translucent status box, Glass/Submarine chimes, heartbeat watchdog
• Cpanel HTML+JS — DONE
• Vanilla JS, XSS-safe DOM construction, token-bearer auth, live capabilities/connections/audit/session view, atomic registry writes
• Hetzner thin-client gateway — DONE
• Zero SSH/SCP — every operation routes through /v2/action. _raw_ssh tripwire raises if anyone touches it.
• TTS narration mute — DONE
• v1 painter purge — DONE (commit 44a66ea)
• First caller migrated: LinkedIn relink — DONE

v4 Phases (the real plan from here)

Phase 1 — HTTP control plane in HeyBrian (smallest first ship) (NEXT)

Per codex: ship JUST the HeyBrian-hosted HTTP control plane + audit/security parity. Defer visual rewrite + remote PWA polish until executor parity is proven.

• 1.1 HMAC verifier + nonce LRU + /v2/caps GET in HTTPServer.swift. HeyBrian binds :9100 (HS keeps :8765). Hetzner gateway gets a MAC_CONTROL_PORT env knob; flip to 9100 for shadow testing. — TO DO
• 1.2 Port the 12 executors to Swift (run, click, screencap, type, keystroke, chrome.eval, chrome.url, file.read, file.write, applescript, notify, say). — TO DO
• 1.3 Contract tests: replay 50 real captured envelopes against both Lua and Swift; compare result/error/audit. — TO DO
• 1.4 Capability registry + atomic-write + audit log + in-memory metrics, all in Swift. — TO DO
• 1.5 Cpanel routes (/cpanel, /cpanel/api/state|toggle|source-allow|stop-session) in Swift. Same HTML I built, served from app bundle. — TO DO
• 1.6 Settings menu in HeyBrian opens WKWebView pointing at http://127.0.0.1:9100/cpanel with token via WKURLSchemeHandler + WKUserScript injection (per codex — no URL params/fragments). — TO DO
• 1.6b Same cpanel also reachable at https://mac.jonahtebaa.com/cpanel (Jonah requirement — no separate phone UI). The HTML detects its origin: localhost → token auth direct to HeyBrian; remote → Caddy gate auth, calls go through Hetzner mac_control_routes.py which proxies HMAC-signed to HeyBrian over Tailscale. One HTML file, two delivery paths, same state. — TO DO
• 1.7 Migrate secrets to Keychain. Move capabilities.json to Application Support with one-version compat reads from ~/.brian/. — TO DO
• 1.8 Hetzner watchdog probe: detect HeyBrian-down, log to LOGS chat (no SIP). — TO DO
• 1.9 Cutover: unload HS brian_controller_ui_v2.lua, HeyBrian rebinds :8765, retire Lua module. Keep dual-port for a week. — TO DO
• 1.10 TCC failure-mode tests for each executor (Accessibility / Screen Recording / Automation / FDA denied). — TO DO
• 1.11 Security hardening from codex's under-considered list: file path sandbox, AppleScript parameterization, large-payload caps, nonce persistence, audit hash chain. — TO DO

Phase 2 — Native overlays (visual rewrite)

• 2.1 Border = native NSWindow + CALayer breathing animation
• 2.2 Pill = NSPanel with NSMenu chooser
• 2.3 Status box = NSPanel with NSVisualEffectView
• 2.4 Retire Hammerspoon canvas painters; app-closed = visual-system-down becomes true

Phase 3 — mac.jonahtebaa.com is the remote view

• 3.1 Hetzner mac_control_routes.py proxies /api/mac/cpanel/* to HeyBrian over Tailscale
• 3.2 PWA renders the same cpanel HTML, phone-first responsive
• 3.3 Optional: SSE/WebSocket for live audit feed

Phase 4 — Pull the rest of Hammerspoon into HeyBrian (later)

• 4.1 brian_panel.lua / brian_prompt.lua → HeyBrian native input window
• 4.2 file_watcher.lua → HeyBrian
• 4.3 Uninstall Hammerspoon entirely

v3 sections that pre-dated v4 — status update

• Section 1 (action router + executors + UI lifecycle) — DONE in Lua. Reimplemented in Swift during Phase 1.
• Section 2 (cpanel) — DONE in Lua + HTML. HTML survives. Routes reimplemented in Swift during Phase 1.
• Section 3 (HeyBrian wired in) — SUBSUMED. v4 makes HeyBrian the HOST, not a client. Phase 1 = this section.
• Section 4 (voice/Puck wired in) — DEFERRED to Phase 4-ish.
• Section 5 (CLI thin-client) — DEFERRED.
• Section 6 (legacy tarball) — DEFERRED until cutover lands.

(legacy v3 section header — kept for reference)

Section 1 — Action Router + Capability Registry on the control center (NEXT)

Goal: turn the existing UI module into a true control center. Every Mac action enters through one HTTP endpoint, the router renders the UI around it, and a JSON registry decides whether it's allowed.

• Add POST /v2/action {action, params, source, session_id} — TO DO
• Add capability registry at ~/.brian/capabilities.json — TO DO
• Fields per capability: name, executor, params schema, toggle (on/off), source allowlist, audit level
• Wrap every dispatch in UI lifecycle (border + pill + status box + chime) — TO DO
• Audit log ~/Library/Logs/Brian/control_center.jsonl — TO DO
• Baseline executors (5 to start): — TO DO
  1. run (local shell via hs.task) — replaces remote SSH for in-Mac work
  2. click (cliclick → eventtap fallback)
  3. screencap (screencapture)
  4. type (cliclick t: → eventtap fallback)
  5. chrome.eval (AppleScript execute javascript — the LinkedIn-API trick)
• HMAC scoped per client — TO DO (~/.brian/secrets/<client>.key)
• Smoke test: each capability fires UI, executes, logs, returns — TO DO

Section 2 — Cpanel (/cpanel)

• HTML page served from the same hs.httpserver — TO DO
• Sections:
• Connections (HeyBrian connected? Hetzner? Voice?) — TO DO
• Capability toggles (per-capability on/off + per-source allowlist) — TO DO
• Live activity feed (tail of control_center.jsonl) — TO DO
• Active sessions list with pause/stop — TO DO
• Secret rotation (regen HMAC keys per client) — TO DO
• Local-loopback session cookie auth — TO DO

Section 3 — Hetzner becomes a thin client

• mac_access_gateway.py drops _raw_ssh and routes through /v2/action for every operation — TO DO
• Drop the planned Hetzner brian-mac-controller daemon — n/a (orchestration moved to Mac)
• Drop mac_gatekeeper ProxyCommand — n/a (no SSH path to gate anymore)
• PGID kills — moves to the Mac side: control center owns the local subprocesses it spawns, kills by PGID on stop — TO DO

Section 4 — HeyBrian wired in

• Orb's TTSManager.speak routes through /v2/action {action: "say"} — TO DO (gives mute flag + audit + UI for free)
• Proactive /notify calls the same endpoint — TO DO
• Wake-word event registers a "user-initiated" session in the control center — TO DO (border lights up, pill clickable)
• Step A/B/C loop progress visible in status box — TO DO

Section 5 — Voice (Gemini Live + Puck) wired in

• Puck's tool-use that touches Mac → /v2/action — TO DO

Section 6 — CLI thin-client

• mac_helper_client.py queue → /v2/action calls — TO DO

Section 7 — Cleanup

• Tarball legacy systems → /opt/agent/data/archives/mac_legacy_v1.tar.gz — TO DO
• git rm mac-bin/ssh, mac_ssh_guard.sh, brian_mac_active.sh, brian_mac_status.sh, queue parts of mac_helper_client.py — TO DO
• Final adversarial codex review of v3 — TO DO
• Per-capability docs in capabilities/<name>.md — TO DO

What this consolidates (the "why")

Today's mess: a half-dozen scripts can paint the Mac and trigger TTS. Each is its own painter. The breathing-border rule has to be applied (or accidentally bypassed) at every one.

After v3: one painter, one auth, one toggle panel, one audit log. The breathing-border rule is in the control center's dispatch path — apply it once, it covers everything forever. HeyBrian, voice, Hetzner, and the CLI all become callers, not painters. Jonah can flip any capability on/off from the cpanel without redeploys.