Pup - the AI's own browser

@@ -449,6 +449,23 @@ the user. Every detection signal was shipped and every one false-fired (`GetLast    verb and the off-screen SELF-HEAL (which checks bounds first and never touches an on-screen    window). +## The foreground gate (v1.8.70) — abe-parity dual key, and the AD interception hole++Foregrounding (open `foreground:true`, `browser_raise_os_window`, `browser_focus_window`) requires a+`foregroundReason` (min 10 chars — quote/paraphrase of what the user said). Open-time: without it the+open SUCCEEDS but stays background (`foregroundDenied`) — abe semantics: withhold the foregrounding,+not the work. Raise-time: refused (`foreground_reason_required`). Granted foregrounds are logged+(`[foreground] ... GRANTED`), recorded in `lastAgentUpdate` (`FOREGROUND: <reason>`), and surfaced as+`lastForeground {ts,verb,reason}` in status. Mirrors abe's `userRequestedForeground`+`foregroundReason`+(also accepted as an arg alias) so the contract is identical across Adom's browser surfaces.++**⚠ KNOWN HOLE (adom/adom-desktop issue #163):** AD-core INTERCEPTS `browser_raise_os_window` /+`browser_focus_window` natively (response shape `{raised, hwnd, resolvedBy}`) and never forwards them+to pup — so pup's raise gate is bypassed until AD forwards the verbs or applies the same gate. The+open-time gate is NOT affected (open always reaches pup). This is exactly how a thread foregrounded a+window with no reason and no audit trail on 2026-07-15 (forensics needed the in-page focus-latch+timestamp `window.__pupFocusTs` — which remains the ground-truth "when did this window gain focus").+ ## The taskbar flash — pulse vs. the persistent tint (clearing it programmatically)  The flash SET routes through **AD-core `desktop_flash_window`** (`flashViaAD`); do not re-add pup's own

@@ -51,18 +51,24 @@ adom-desktop browser_open_window '{"sessionId":"wiki","url":"<url>"}' **pup is the AI's workspace, not the user's.** Every window opens **in the background** (behind the user's windows, no focus stolen) and stays fully drivable + screenshottable there — you do NOT lower it yourself. -- **`foreground:true` is the ONLY thing that shows a window.** Not sizing, not navigating, not-  screenshotting, not recording setup. Pass it ONLY when the user explicitly wants to WATCH (a demo, a-  "show me", a live recording).+- **`foreground:true` is the ONLY thing that shows a window — and it is GATED (v1.8.70).** Not+  sizing, not navigating, not screenshotting, not recording setup. Foregrounding requires BOTH+  `foreground:true` AND `foregroundReason:"<quote/paraphrase what the user said>"` (min 10 chars).+  Without the reason the open still succeeds but the window stays BACKGROUND+  (`foregroundDenied:'foreground_reason_required'`). The reason is logged, recorded in+  `lastAgentUpdate`, and surfaced as `lastForeground` in status — the user can always audit who+  put a window on their screen and why. Pass it ONLY when the user explicitly wants to WATCH (a+  demo, a "show me", a live recording); after the show-me, `browser_lower_os_window` to return it. - **Sizing/positioning does NOT foreground** — `browser_open_window {width,height,x,y}` places the window   at an exact size/spot **for clean screenshot framing** while it stays in the background. So you can frame   a shot without ever disturbing the user's main work. - **`browser_alert_window`** flashes the taskbar (a non-intrusive "it's ready/done" nudge) — prefer it over   raising the window. Use it for an explicit end-of-task "it's ready".-- `browser_raise_os_window` / `browser_focus_window` bring a window forward (use sparingly, only to show-  the user); `browser_lower_os_window` tucks it back. **Raise steals focus and can leak a mid-typed-  keystroke into the page** (pup blurs the page's focused element first to reduce it) — to just signal "I-  updated this window", use the auto-flash / `browser_alert_window`, NOT raise.+- `browser_raise_os_window` / `browser_focus_window` bring a window forward — **GATED the same way:+  REFUSED (`foreground_reason_required`) unless you pass `foregroundReason`.** Use only for an+  explicit user show-me; `browser_lower_os_window` tucks it back after. **Raise steals focus and can+  leak a mid-typed keystroke into the page** (pup blurs the page's focused element first to reduce+  it) — to just signal "I updated this window", use the auto-flash / `browser_alert_window`, NOT raise.  ## Signalling what you changed — auto-flash + `updateNote` (so the user follows along)