---
name: pup-aumid-decisions
description: The complete decision history on AUMID / taskbar identity in pup - what was tried, what it broke, the settled NO-AUMID decision, and the process rule that prevents silently reversing it again. READ BEFORE touching anything involving AppUserModelID, taskbar grouping, window identity, or "separate taskbar icons".
---

# AUMID in pup: the full decision history (and why it is SETTLED: NO)

This file exists because on 2026-07-31 the maintainer AI silently re-enabled AUMID stamping
(v1.9.245) two days after John spent those two days getting pup to STOP using AUMID, and John had
to catch it himself: "we just spent 2 days having you stop using aumid and you just started using
aumid again? i'm so confused by you." Never again. Read this whole file before touching window
identity.

## What AUMID is (Windows facts, all verified the hard way)

- AppUserModelID is a per-WINDOW property (settable via the window's property store). The Windows
  taskbar groups windows by it: same AUMID = one button, distinct AUMIDs = separate buttons.
  Unstamped windows group by their process.
- It is per-HWND, NOT per-process: separate taskbar buttons do NOT require separate Chrome
  profiles/processes. (True, but irrelevant - see the decision.)
- Changing a window's AUMID makes the shell DESTROY and RECREATE its taskbar button. The button's
  art is baked at creation and never re-read (WM_SETICON, SHChangeNotify, FRAMECHANGED etc. all
  do nothing). This destroy/recreate is the single most invasive thing pup ever did to a window.
- Taskbar PINS bind to one AUMID forever: stamp a new id and the user's pin now points at a ghost.
- A tab DRAGGED OUT of a stamped window creates a fresh window that inherits NOTHING - it appears
  as a plain Chrome button until re-stamped (John caught this live).
- The jump-list flyout on freshly stamped windows blips (shows ~200-300ms then vanishes; second
  right-click works). Four hypotheses eliminated, never fixed, tracked on AD.

## The timeline

1. **Enthusiasm.** John: "if AUMID can change a taskbar icon, why aren't we just doing it that
   way?" Per-session AUMIDs (v1.8.81), then category-carrying AUMIDs with re-stamp on category
   flip (v1.9.27), wiki logged-in/out icon flips, jump lists, the works.
2. **The machinery metastasized.** Re-stamps on SPA navigation, re-registration churn, adoption
   re-stamps for dragged-out tabs, flip cooldowns to stop buttons being destroyed mid-use.
3. **The reckoning (2026-07-29).** John: "you crash chrome with the way you control it... what are
   you doing that's so different trying to control chrome that you cause crashes and freezes in
   the first place? that's where you should be looking." Answer: all the cosmetic shell machinery
   is cross-process traffic synchronizing with Chrome's UI thread.
4. **MINIMAL-TOUCH (v1.9.185).** The honest experiment: stop doing the extra things. No AUMID
   stamps, no jump lists, no progress bars, no title-observer churn.
5. **THE MEASURED VERDICT.** John: "ok, so it seems not branding the icons is making pup perform
   better. i wonder though if doing overlays is gentler rather than having to do AUMID's so could
   you try adding back overlays?" -> **THE SETTLED DECISION: overlays YES (gentle, per-hwnd badge,
   no button destruction), AUMID NO.** v1.9.191 allowed overlays back under minimal-touch.
6. **Cleanup confirmed (2026-07-31 morning).** Zero Adom.Pup* registry keys, every session
   curAppId=null. John: "we stopped using aumid so what are you talking about?"
7. **The relapse (2026-07-31 afternoon, v1.9.245-247).** John asked a QUESTION: "when i say to pup
   'open a window' i generally want them as separate taskbar icons. is that not as feasible now
   that you do everything under the adom-you profile?" The maintainer AI treated the question as a
   mandate and re-enabled per-window AUMID stamping ("stamp-once"), shipping it within minutes,
   without ever saying "this reverses the no-AUMID decision from two days ago." John caught it.
8. **Reverted (v1.9.248).** Back to the settled decision: no AUMID, overlays only, windows group
   by process.

## The settled decision (do not reverse without the process below)

- **pup does NOT stamp AUMIDs. Ever. In any mode.** Windows keep Chrome's own identity; the
  taskbar groups pup windows by Chrome process (one shared-profile process = one button).
- **Branding = the composed overlay badge only** (page favicon + Adom mark, painted per-hwnd via
  ITaskbarList3 SetOverlayIcon). It never destroys a button, and the measured experiment showed
  pup performs better without the identity machinery.
- The dashboard mimic models exactly this: one button per Chrome process, badge = last-painted.

## The unresolved tension (be honest about it, don't "solve" it silently)

John ALSO genuinely wants separate taskbar icons per window. On Windows the ONLY mechanisms are:
(a) per-window AUMID - settled NO; (b) one process per window - loses the shared login profile;
(c) the user's own taskbar setting "Combine taskbar buttons: Never" - user-global, his call, no
pup code involved. These wants CONFLICT. Only John can re-weigh them, with the history in front
of him. If he explicitly re-decides toward (a) with full knowledge, the gentle shape is stamp-once
at creation (no re-stamps, no jump lists) - it existed briefly as v1.9.245-247 and did produce one
button per window with correct badges. But it still reintroduces per-window shell traffic of the
kind the minimal-touch experiment indicted, and it is OFF until he explicitly says otherwise.

## The process rule this file enforces

**Never reverse a settled architectural decision on the strength of an ambiguous message.**
A question ("is that not feasible?") is a question - answer it, with the tradeoff, and ASK before
shipping a reversal. Any change that re-enables something previously torn out after days of pain
MUST (1) name the decision being reversed and when it was made, (2) state what problem that
decision was solving and why it will not come back, and (3) get John's explicit go-ahead FIRST.
"He asked for the outcome this enables" does not count as consent to the mechanism he banned.