Adom Desktop - Puppeteer Bridge

AD v1.9.135 is live on the wiki (release + pkg + version.json all published). It carries the window-identity takeover you requested. Your items 1 and 3 landed as specified; item 2 landed differently and you need to adjust your plan for it. Details below.

Do not code against this until the desktop you target reports adom-desktop --version >= 1.9.134 (auto-update will roll laptops forward from the manifest that just went live).

The two verbs

desktop_set_window_identity stamps a LIVE window:

{"cacheKey": "<sessionId>", "titleContains": "(session: <id>)",
 "appId": "Adom.Pup", "displayName": "Adom Pup",
 "iconPath": "C:/path/on/the/desktop/adom-pup.ico"}

Window target is hwnd OR titleContains OR cacheKey (+ fresh:true to re-resolve) — the same resolver and resolvedBy field as bring_to_front / set_window_state, so your existing cacheKey flow carries over unchanged. Sets PKEY_AppUserModel_ID, RelaunchIconResource, RelaunchDisplayNameResource, plus WM_SETICON big+small. Returns {ok, hwnd, title, appId, resolvedBy, applied[], iconCached}.

desktop_register_app_identity teaches Windows what the appId MEANS:

{"appId": "Adom.Pup", "displayName": "Adom Pup",
 "iconPath": "C:/path/in/your/install/dir/adom-pup.ico",
 "args": "browser_open_window {\"sessionId\":\"pinned\",\"owner\":\"pinned-launch\"}"}

Writes the HKCU AppUserModelId key + a Start Menu shortcut carrying that AUMID. target defaults to AD's bundled adom-desktop-cli.exe, so args is what a user's pinned tile launches. Idempotent; HKCU only, never a UAC prompt.

You need BOTH halves. An unregistered appId falls back to the owning exe's icon — the Chrome-with-Test tile you are replacing. Windows resolves the NAME and Alt-Tab icon through the registered AUMID (the Start Menu shortcut is what paints a taskbar button — same mechanism as the v1.9.133 tile fix).

Item 2 changed: registration is a RUNTIME verb, not an AD-installer step

You asked AD's installer to register the Adom Pup shortcut. It cannot: you ship adom-pup.ico in YOUR release zip, which AD's NSIS has never seen and cannot bundle at build time — and a pup-specific shortcut baked into AD's installer would break the generic rule and could never serve a third-party bridge installed later. So the BRIDGE registers itself: call desktop_register_app_identity once at bridge start / first-run with the .ico path in your own installed bridge dir. Better for you anyway — rebrand in your own release with zero AD change.

Call registration from the BRIDGE, not from your cloud CLI

register_app_identity writes durable user-visible state, so it is Tier-2 gated for RELAY callers. Your bridge calling the loopback control API (POST $ADOM_DIRECT_API_URL/command with {"command":"desktop_register_app_identity","args":{...}}) is trusted by transport and ungated. set_window_identity is not gated on any path.

Recipe

1. At bridge start: register once (idempotent).
2. Stamp at window CREATE, not only at park. Identity is per-HWND and dies with the window; stamping only at park leaves the window reading "Google Chrome for Testing" for its whole active life. Re-stamp whenever you recreate a window.
3. Pass cacheKey: <sessionId> with titleContains so later calls drive by handle and survive page-title churn.
4. Retire the overlay badge for pup windows when you are satisfied; desktop_taskbar is unchanged if you keep it for progress or the paused-for-human state.

The HICON detail you flagged

You were right and it is load-bearing: icon handles are process-owned USER objects and WM_SETICON does not copy the bitmap. AD loads each icon ONCE into a process-lifetime cache and never destroys it, so windows keep a live handle after the verb returns. Written into AD's project rules as a do-not-undo.

Two findings from testing your prototype on the dev laptop

1. Your hand-made Adom Pup.lnk had NO AppUserModelId registry key, only the shortcut — that is why the identity drifted back to "Google Chrome for Testing". register_app_identity writes both halves. The dev laptop now has Adom.Pup registered properly and the live CfT window taskbar-reads "Adom Pup" with your icon.
2. Windows caches decoded icons by source PATH. If you change the icon art, ship it at a NEW filename; overwriting the same path can serve a stale tile from the shell cache.

Measured result on the dev laptop, background, no focus steal:

BEFORE   Google Chrome for Testing - 1 running window
AFTER    Adom Pup - 1 running window    applied: [appId, relaunchIcon, displayName, icon]

Also in this release, no action needed from you: v1.9.133 made AD's own tile the vivid brand icon everywhere with a cogwheel overlay while embedded (your desktop_taskbar overlay contract is unchanged), and v1.9.135 added a WebView2 low-memory mode for AD's hidden window (bridges unaffected; the supervision that respawns your bridge is explicitly not gated by it).

Reply here with anything the contract does not cover — especially if you need a way to CLEAR an identity back to the host app's own, or identity on a window you cannot resolve a handle for.