Pup - the AI's own browser

@@ -0,0 +1,72 @@+---+name: pup-icon-audit+description: "DEVELOPER-only (user-invocable:false). What to DO when John says 'audit your taskbar icons' — it is never a request for a report. It means: detect whether pup's AUMID/icon tracking has drifted from the shell, find out WHY, FIX THE CODE so that class can never drift again, then REAPPLY every AUMID icon so the glass is right, and prove it with red-boxed pixels. The end state John is paying for: he never has to ask, because pup audits and heals itself. Trigger words: audit your taskbar icons, audit the icons, icon audit, aumid tracking, are your icons right, taskbar drift, check your icons, reapply aumids, self-heal icons."+---++# pup-icon-audit — "audit your icons" means DETECT → DIAGNOSE → FIX THE CODE → REAPPLY → PROVE++**John, 2026-08-18, verbatim intent:** *"whenever i ask you to audit your taskbar icons, i'm not+saying that for my health. i mean detect whether you're off on your aumid tracking, find out why,+fix your code, then reapply all aumid icons to fix it… the goal is that i never have to ask you to+audit in the future because you've written so much code, that so perfectly handles all situations,+and you run your icons so perfectly, i never have to ask."*++So an audit request is a BUG REPORT plus a MANDATE. Reporting findings and stopping is a failure of+the task. Every audit ends with: the code changed so the class is impossible, the live taskbar+repaired, and red-boxed pixel proof in shotlog.++## The five steps, every time++1. **Run the product's own audit first** — `pup_audit_icons {}` (it repairs by default; `fix:false`+   for a dry run). If it reports findings, that is the machine agreeing with John. If it reports+   CLEAN while the glass is wrong, **the detector has a blind spot and fixing the detector is part+   of the job.**+2. **Get shell ground truth yourself** — UIA button names + rects across `Shell_TrayWnd` AND+   `Shell_SecondaryTrayWnd` (multi-monitor taskbars are separate bars; a "missing" button is often+   just on the other bar). Enumerate by `-match "running window"`, then compare against the live+   session OWNERS from `pup_status`. **Never grep with a hardcoded name list** — that once made me+   report 2 missing buttons that were both present under names my pattern did not know.+3. **Red-box the pixels** — fresh tray capture (freshness-gated; a stale file poisons everything),+   map UIA rects to image px via the capture's own `coordMap.screenRect` against THIS image's width+   (never `imageToScreen`, which describes the shrunk "safe" image, and never an assumed 2560), draw+   a red box around every pup button, and paste an 8x crop of each with its real UIA name captioned.+   Then LOOK at it. Names are not pixels.+4. **Fix the code, not the symptom** — repair the live bar only after the class is closed in+   `src/server.js`. A hand-repair with no code change guarantees John asks again.+5. **Prove it** — re-run the audit until CLEAN, capture the after shot with red boxes, inject both+   into shotlog, and run `tools/selftest.sh` + `tools/mode-ralph.sh`.++## The drift classes (all seen in the wild; all must stay covered)++| Class | Symptom on glass | Root cause | Where it is handled |+|---|---|---|---|+| `no_button` | window rides the stock "Google Chrome for Testing" group in tiles/aumid mode | identity never reached the shell | audit re-stamps + nudges |+| `nudge_pending` | button keeps its OLD name/art indefinitely | the hide/show nudge is skipped while a window is FOCUSED, and pre-2.0.227 nothing retried | `NUDGE_RETRY_DELAYS` backoff (6s→5m), each retry re-checks foreground |+| `stale_art` | right NAME, wrong ART | Win11 bakes a button's icon at CREATION; the tile `.ico` was written afterwards | audit compares tile mtime vs `_buttonBuiltAt`, re-registers + rebuilds |+| `unverified_art` | unknown | pup has never rebuilt that button since the tile existed | same repair, conservatively |+| `leftover_identity` | pup-branded button while in plain mode | strip/converge missed a window | audit re-runs `stripAllPupIdentities` |+| two CfT groups | two identical "Chrome for Testing" buttons | wiping AUMIDs to VT_EMPTY while Chrome re-asserts its own | plain = CONVERGE to Chrome's native AUMID (see pup-mode-ralph) |++## When the audit runs on its own (why John should never have to ask)++- ~25s after **any mode switch** and after **any brandSweep** (that is when a rebuild races the art)+- 12s after a **thread tile first renders** (the button was necessarily built before the art existed)+- every **4 minutes** in steady state while any session is live+- on demand via `pup_audit_icons`++`_lastAudit` rides on `pup_status.iconAudit` so any thread can see the last verdict without running one.++## Traps this file exists to remember++- **The log ring is part of the audit.** A faviconless page once retried two fetch rails every 30s+  forever and pushed every audit line out of the tail — the diagnosis died with it. Any repeating+  log line must collapse per URL and any retry loop must be bounded (fixed 2.0.229).+- `titleTag` defaults **off**, so every title-based window lookup (`titleContains`) fails by design;+  hwnd is the only real targeting. If a window op fails with `No visible window with title+  containing "(session: X)"`, the true cause is a MISSING HWND, not the title.+- A respawn re-stamps everything, which silently repairs drift — so auditing right after a respawn+  proves nothing. To test the repair path, INJECT drift (delete a thread's `.ico` from+  `%TEMP%\pup-thread-tiles\<gen>\`, then force a re-register) and watch the audit catch it.+- Cross-check `pup_status` session count against the button count. A session with no button of its+  own in tiles mode IS the finding.+- Never leave test windows open, and always land the user's mode back where they chose it.

@@ -65,7 +65,7 @@ a failed walk. - After a respawn, WAIT for re-stamps before judging icons: sessions reload with `_curAppId=null`   and every identity check lies until the first stamp lands (see #51's prune gate). -## The icon audit (run it when John says "audit your taskbar icons")+## The icon audit — see dev-skills/pup-icon-audit (an audit means FIX + REAPPLY, never a report)  UIA names + rects -> fresh tray capture -> red box EVERY pup button -> 8x crops captioned with the real button name -> compare each against the mode's contract (tiles = thread-name tile; aumid =