Floating always-on-top agent status overlay — reverted from main, revisit with a different window approach #518

Status

Shipped in #514 (+ review fixes), patched in #516, reverted in #517. The feature is OUT of main. This issue is the memory of what happened so the next attempt doesn't re-derive it.

What the feature was

A second frameless, always-on-top BrowserWindow showing live agent status while working in other apps: collapsed pill of activity-dot counts (working / waiting-on-approval / idle / exited), click to expand per-agent rows, click a row → raise Agent Code and focus that agent. Toggled via command palette; position/enabled/expanded persisted; auto-hide while Agent Code focused.

Architecture (worth keeping for attempt #2)

The design that worked and is worth reusing:

• No session-IPC fan-out. The main renderer (which already owns all derivation: dispatchActivity, dispatchAttentionLabelFromConditions, buildVisibleDispatchRows, sessionTitle) published a precomputed throttled snapshot over dedicated agent-overlay:* channels; main cached + forwarded to the overlay window. sendToMainWindow and the forwarder stayed untouched.
• Tiny second Vite renderer entry (~8.5 kB) sharing styles.css + theme via opaque settings pass-through; dedicated least-privilege preload (4 methods).
• Two-agent codex review hardening landed on top: hasMainWindow()-based activate handling, overlay destroyed with main window, nav guards, payload validation, display clamping, visibility-gated attention labels (in dispatchAttentionLabelFromConditions).

All of it is recoverable from the reverted history: git log 5135028 --oneline (feature at dce73b7/c3fbf93, dock fix at 2106c3e).

Why it was reverted

macOS window-layer behavior around a second always-on-top window was unacceptable in real use:

1. First failure (fixed in fix: overlay no longer transforms the app into an accessory process #516): setVisibleOnAllWorkspaces(true, { visibleOnFullScreen: true }) transforms the ENTIRE app's activation policy to UIElementApplication (accessory): Dock icon vanished, menu bar gone, main window couldn't be moved/focused (electron#26350, electron#37487). Fixed with skipTransformProcessType: true (electron#27200).
2. Even after the fix, the overall experience remained bad in practice — window/focus behavior around the main app still felt broken enough that the feature was pulled rather than iterated on main.

Notes for the next attempt

• Do NOT reintroduce visibleOnFullScreen without solving the process-transform side effect.
• Candidate alternatives to a second Electron window: a panel-type window (electron's NSPanel support / type: 'panel'), the macOS-native NSStatusBar (menu-bar extra showing counts, no window layering at all), or piggybacking on the existing dictation-style native helper.
• The renderer-side reporter pipeline (snapshot over IPC) is independent of the window strategy and can be reused as-is.
• Related: Unify the floating-surface UI layer: one dismiss/focus/layer system + shared surface primitives #512 (floating-surface UI layer unification) may be the right umbrella when this comes back.