← Commit history

Update 1 file(s)

John Lauer ·15eecbf176 ·3mo ago ·parent 29f6e15
1 file changed +20
dev-skills/developing-the-bridge/SKILL.md+20
@@ -276,3 +276,23 @@ two verbs disagree about whether the extension is installed. was forced to regex our `_hint` to detect it. Contract now: **`ok:true` + `launched:true`** whenever the launch fired, with **`hwndResolved:bool` + `hwndReason`** reported separately. Never make a caller parse prose to learn an outcome — give them a stable boolean.++## ⭐ Two badges, and SHOW the human the foreground reason (John, 2026-07-22)+The overlay badge must distinguish the two capability layers, because conflating them is a security+ambiguity ("is an AI reading this window, or did it just open it?"):+- **LAYER 2 — solid teal Adom favicon** (`adom-favicon.png`) = the extension is installed and the AI has+  LIVE CONTROL (read/click/type). Painted at `open_window`, re-asserted by every drive verb.+- **LAYER 1 — HOLLOW teal outline** (`adom-favicon-hollow.png`) = extension-free `open_os_window`: Adom+  OPENED this window but cannot see or drive it; the USER is in control. Filled-vs-outline is the+  convention everyone already reads, and it survives at the true ~24px overlay size (a merely *muted*+  variant did not — it was indistinguishable from layer 2, which defeats the whole point).+Both use the SAME lifecycle: `applyBadge` arms the 3-min idle expiry, so they self-clear back to the+profile's plain avatar and never linger.++**Foreground requires a reason AND now shows it.** Background is the hard default in both layers+(layer 2: `userRequestedForeground` + non-empty `foregroundReason`, else auto-reverted + logged as a+`focus_violation`; layer 1: `foreground:true` without `foregroundReason` → refused+`foreground_unjustified`). But the reason only ever reached the AI. When a foreground grant is actually+exercised, `announceForeground()` now paints a full-desktop `desktop_caption` with that reason for 3s+(auto-dismiss) and logs `_foreground_announce`. A takeover the user cannot see explained is exactly what+erodes trust in an agent that can touch their desktop.