Companion app for OS notifications and machine-wide agent supervision (cctop-style)

[a9a4k]

Context

Issue #101 shipped OS notifications inside the extension via terminal-notifier and was reverted (51e226a): it required a user-installed macOS-only binary, gave Linux/WSL users nothing, and the in-extension degradation contract proved leaky. The conclusion (recorded in ADR-0025 Considered Options): native OS notifications belong in a dedicated companion process, not the extension.

Idea

A small cctop-style companion app (menubar/tray process) that watches Deck's machine-global status dir (~/.local/share/deck/status/ — one JSON file per Terminal, written by the agent hooks; the transport is already process-agnostic) and owns everything the extension API can't:

• Native notifications on NeedsInput/Completed transitions, with sounds, real click actions, and retraction on resolution — per platform (macOS UNUserNotification, Linux notify-send/DBus, Windows toasts), solving the parity gap that killed OS notifications: terminal-notifier channel with deep-link click-to-open #101.
• Click-through via vscode:// deep links into the existing Deck URI-handler path (reverted with OS notifications: terminal-notifier channel with deep-link click-to-open #101 but trivially restorable extension-side), or richer focus strategies later (cctop's FocusTerminal shows the ceiling).
• Single-process supervision: one watcher means the multi-window dedup/liveness problems (heartbeats, redundant banners, group hacks) disappear by construction.
• Possible later: a machine-wide status glance (menubar icon = NeedsInput count across all repos and VS Code installs — the global-vs-registry mismatch from the review becomes a feature).

Relationship to the extension

The extension keeps in-window toasts, tree status, badge, and rollups exactly as shipped. The companion is additive and optional; both read the same status files. cctop itself is prior art for nearly every component (file watching, debounce, state machine, notification dedup, focus strategies).

Open questions (for triage)

• Stack: Swift menubar (cctop clone, macOS-first) vs Tauri/Electron tray (cross-platform from day one)?
• Distribution: brew cask? bundled download prompted by the extension?
• Does the extension detect the companion and suppress its own toasts, or do both run (companion = unfocused channel, extension = focused channel)?

Refs: #90, #94, #100, #101, ADR-0025.