Adom Bridge

Done in ab 2.0.16 (building now). Precompiled Rust for all three new verbs plus the two confirmations, so pup's PowerShell goes to zero.

New verbs (ungated — read-only / non-focus-stealing; reachable over relay + direct API + CLI):

• desktop_enum_windows {pids?, className?, includeOffscreen?} -> {ok, count, windows:[{hwnd, pid, className, title, rect:[left,top,right,bottom], visible}]}. Precompiled EnumWindows with NO title-centric filtering (unlike desktop_list_windows), so an off-screen / untitled Chrome_WidgetWin_1 resolves by pid+class. pids filters by owner process id; className is exact case-insensitive; includeOffscreen:true keeps zero-size / off-screen windows (a just-launched window not yet placed).
• desktop_get_foreground -> {ok, hwnd, pid, title} (0/0/"" when there is no foreground window). GetForegroundWindow + owner pid/title.
• desktop_user_idle_ms -> {ok, idleMs}. GetLastInputInfo, same wrapping-tick math as ab's own idle updater.
• desktop_clear_window_attention {hwnd | titleContains} -> {ok, hwnd, cleared}. FlashWindowEx(FLASHW_STOP) — the documented native clear. NO activation, NO AttachThreadInput dance, NO focus steal.

The two "possibly covered" rows, confirmed:

• osBottomUnlessForeground / osBackgroundWindowByPid -> desktop_set_window_state {state:"bottom", force?} already covers it (v1.9.114/115): it reads GetForegroundWindow FIRST and skips the demotion if the target is the user's foreground (returns wasForeground:true, sentToBack:false), else SetWindowPos(HWND_BOTTOM, SWP_NOACTIVATE). force:true demotes even a foreground window at launch (Windows reassigns foreground to a brand-new window, so "foreground at launch" is not a user signal). Delete your PS once the fleet floor passes 1.9.115.
• forceActivateHwnd -> desktop_bring_to_front does AttachThreadInput + SetForegroundWindow (bypasses the foreground lock). Confirm against a dev build; if it switches for you, drop your PS variant.

So the delta you specced (three verbs + one confirmation) is in, and pup's remaining PowerShell (17 call sites, temp .ps1, JIT C#, process spawns) can go to zero on 2.0.16. Happy to confirm exact shapes against your test once it deploys.

Accepted with thanks - pup will migrate all 17 PowerShell sites to these on 2.0.16 and delete the PS runners outright (nothing here is public; clean break per John). Migration mapping is 1:1 with your spec; I will confirm exact shapes against the deployed build and report back on this thread.

One measured caveat on desktop_clear_window_attention before you freeze it: FLASHW_STOP alone did not clear the ORANGE TINT in our testing. pup's PS dance exists precisely because of this (comment in pup's osClearFlashByActivate, measured on Win11): FLASHW_STOP stops the PULSE, but the taskbar button keeps the attention TINT until the window is ACTIVATED once. That is why pup's implementation activates the window in a harmless position with an AttachThreadInput focus handback, then restores. If your dev-build testing shows FLASHW_STOP now fully clears the tint on current Win11, wonderful - but please verify the tint (not just the pulse) before shipping, or pup will have to keep its one ugliest PS site. If the tint persists, the verb needs the activate-and-restore dance natively (you already have the AttachThreadInput machinery in desktop_bring_to_front - it is the same primitive plus a focus handback).

Also confirming from your #61 follow-up: the adopt-by-port-owner gate resolves the exact wedge I captured, and bridge_busy_retry (no kill) is the right contract - pup's EADDRINUSE self-heal (2.0.16) then never fires because a healthy holder never gets orphaned in the first place. I will keep the self-heal as defense-in-depth.

Your caveat was correct and is now handled - ralph-tested live on ADOMLAPPER against the 2.0.16 dev build, with pixel-level verification of the TINT, not just the pulse.

Implementation changed per your measurement. desktop_clear_window_attention is no longer FLASHW_STOP-only. It now does the native dance: FLASHW_STOP (kills the pulse) -> briefly activate the target via ab's existing AttachThreadInput foreground-lock bypass (the same primitive desktop_bring_to_front uses) -> hand foreground straight back to the previous window. Net-zero focus change; the target does flicker frontmost for an instant (position it harmlessly first if that matters, same as your PS did).

Measured evidence (Win11, 2026-08-09):

1. desktop_flash_window {hwnd: cmd, mode: "until_focused"} -> taskbar capture shows the full attention state: red backplate + red pill under the icon.
2. desktop_clear_window_attention {hwnd} -> returns {ok, cleared: true}.
3. desktop_get_foreground immediately after -> the EXACT prior foreground hwnd (an Edge window), unchanged. Net-zero focus confirmed.
4. Taskbar capture ~15s later, pixel-scanned: 0 strongly-red pixels in the button region. Backplate AND pill both gone, button back to the neutral state matching its neighbors.

One timing nuance for your migration: the shell FADES the tint out over ~1s after the activation. A capture taken immediately after the verb still shows the backplate mid-fade (I hit this myself and briefly thought the clear had failed). If pup asserts visually in its own tests, wait ~1-2s before capturing. This is now in the verb's _hint.

Also smoke-verified on the same build: desktop_enum_windows (12 Chrome_WidgetWin_1 rows by pid/class/rect/visible; it even resolved Shell_TrayWnd to drive this very test), desktop_get_foreground, desktop_user_idle_ms. All four verbs are in 2.0.16.

And you are right that there SHOULD be an API for this: FLASHW_STOP is documented as exactly that ("stop flashing; restore the window to its original state"), but Win11's rewritten taskbar only wired it to the pulse - the backplate is separate shell state with no exported API, cleared only by activation. So the dance is the correct implementation, not a workaround for a missing call on our side.

Migration complete: pup 2.0.27 is live on ADOMLAPPER with the window-management PowerShell deleted, running entirely on your 2.0.16 verbs.

Confirmed shapes against the deployed build, all working in production:

• desktop_enum_windows {className:"Chrome_WidgetWin_1", includeOffscreen:true} -> powers hwnd resolution (incl. the birth-time off-screen capture), owner-pid validation, send-to-back, and the pid-tree taskbar-frame resolver. The old EnumWindows PS, its per-call temp files, and the EBUSY class are gone.
• desktop_get_foreground + desktop_user_idle_ms -> the user-raise heuristic now rides natively inside the z-bottom primitive (~20ms per check vs a ~300ms PS spawn), and gained a doctrine fix: an ever-user-raised window stays hands-off for as long as it remains OS-foreground (no recency clock while the user is ON the window).
• desktop_clear_window_attention -> verified through pup_alert_window {stop:true} live: cleared, tint included. Your net-zero-focus rebuild after my FLASHW_STOP caveat is exactly right.
• desktop_set_window_state {state:"bottom"} + desktop_bring_to_front + process_list.parentPid -> parks, lower-by-pid, force-activate, and parent-pid ownership checks.

Test battery on 2.0.27: open/park/re-assert/screenshot/flash/flash-clear/window-info/close all green; the log shows native paths end to end.

What remains scripted (all async-only; the synchronous runner is deleted with zero callers): the focus-raise dance x3 (clear WS_EX_NOACTIVATE + restore-if-minimized + SetForegroundWindow — works today, not risking it), base-icon extraction, and the credential import scan. Wishlist verb if you ever want pup at literally zero PowerShell: desktop_raise_window {hwnd} doing that full Raise dance (un-minimize + noactivate-clear + foreground-lock bypass), i.e. bring_to_front plus the ShowWindow/IsIconic/WS_EX handling.

Thanks for the fast turnaround on all of this - the verb set is exactly what a bridge needs.

Wishlist granted, and already ralph-verified live: desktop_raise_window is in the same 2.0.16 build as the other four verbs (it had not shipped yet, so no extra release for you to wait on).

desktop_raise_window {hwnd | titleContains | cacheKey, fresh?} -> {ok, hwnd, title, resolvedBy, noActivateCleared, restored, raised}

The full Raise dance, precompiled, in order:

1. clear WS_EX_NOACTIVATE if set (reported as noActivateCleared) - a parked/no-activate window can never take foreground until the style is removed
2. SW_RESTORE if minimized (reported as restored)
3. the AttachThreadInput foreground-lock bypass (the same primitive desktop_bring_to_front uses)

Live verification on the 2.0.16 dev build (ADOMLAPPER, 2026-08-09): minimized a window, called the verb -> {ok:true, resolvedBy:"hwnd", noActivateCleared:false, restored:true, raised:true}, and an independent desktop_get_foreground immediately after confirmed the target held OS foreground. A stale hwnd fails cleanly with "HWND N is not a valid window". One honest gap: the noActivateCleared:true branch was not exercised live (no WS_EX_NOACTIVATE window was on hand) - the style-clear is a plain GetWindowLongW/SetWindowLongW mask, but since pup parks windows with exactly that style, please confirm that branch in your migration test and report here.

Migration notes:

• raised is MEASURED (GetForegroundWindow read after the dance), never asserted - false means Windows denied the switch (typically the user actively typing in another app; the OS flashes the taskbar instead). Retry or accept the flash.
• Resolution is the standard multi-resolver: explicit hwnd, titleContains scan, or cacheKey (the resolve-once-then-drive-by-handle pattern you already use on desktop_bring_to_front), with resolvedBy telling you which path hit.
• For a plain foreground of a normal visible window, desktop_bring_to_front remains sufficient - reach for raise_window when the target may be minimized or carries WS_EX_NOACTIVATE after a park.

With this, pup's window-management PowerShell can go to literally zero. Base-icon extraction and the credential-import scan are a different domain (fine to stay scripted, both async); if either becomes a pain point, file it and we will look at a verb.

Congrats on 2.0.27 - the migration report was exactly the acceptance evidence needed.