Pup - the AI's own browser

@@ -26,7 +26,7 @@ When you run `browser_open_window`, one of these happens — handle each: | Response | What it means | What you do | |---|---|---| | `ok:true` / a real session | A browser (Chrome or Edge) was found and launched. | Proceed — the common case. |-| `errorCode: "node_not_found"` / `could not run npm` / runtime not ready | The bridge's Node runtime isn't ready yet. On **AD ≥ 1.9.63 you do nothing** — AD provisions Node automatically (portable, no UAC) and prewarms it in the background right after first launch. | Check `adom-desktop runtimes '{}'`; if `state:"installing"`, wait a few seconds and **retry** the same `browser_*` call — it's ready once `state:"ready"`. No user action, no prompt. (Only on AD older than 1.9.63: `desktop_install_node` — see "The Node step".) |+| `errorCode: "node_not_found"` / `could not run npm` / runtime not ready | The bridge's Node runtime isn't ready yet. On **AD ≥ 1.9.63 you do nothing** — AD provisions Node automatically (portable, no UAC) and prewarms it in the background right after first launch. | Check `adom-desktop runtimes '{}'`; if `state:"installing"`, wait a few seconds and **retry** the same `browser_*` call — it's ready once `state:"ready"`. No user action, no prompt. (Only on AD older than 1.9.63: `desktop_install_node` — see "The Node step".) **KNOWN AD BUG (some 1.9.x):** if `runtimes` shows `node.state:"ready"` AND `browser_readiness` works but other `browser_*` verbs STILL return `node_not_found`, it's an AD verb-gate false-negative (node IS there) — NOT a real missing Node. Do NOT loop `desktop_install_node`; tell the user it's an Adom Desktop bug and to update AD. | | `errorCode: "chrome_for_testing_installing"` (`installing:true`) | **RARE** — the machine has NO Chrome AND no Edge, so pup is fetching Chrome for Testing as a fallback (~150 MB, in the background; it did NOT block). | Poll **`browser_readiness`** until `{ready:true}`, then re-issue the same `browser_open_window`. **Faster fix:** ask the user to install Chrome or Edge (Edge ships with Windows) — pup then uses it instantly, no download. Don't report failure. | | `errorCode: "chrome_install_no_disk"` | No Chrome/Edge and too little free disk to install Chrome for Testing (`readiness.diskFreeMb` shown). | Tell the user how much is free and that ~800 MB is needed; ask them to free space OR install Edge/Chrome (Edge needs ~nothing). Do NOT retry the download — it fails until disk is freed. | | `errorCode: "chrome_install_failed"` / `chrome_download_network` / `chrome_install_permission` | No Chrome/Edge AND the CfT fallback download failed (network/proxy, permission, or other). | Read `readiness.lastError`. Ask the user to install Chrome or Edge (Edge ships with Windows). |

@@ -144,6 +144,25 @@ What we learned and baked into the code:   is the AD reopen, which the shared-runtime proposal (absolute-path spawn) removes. `desktop_install_node`   (UAC MSI) + `shell_execute` (approval popup) are fallbacks only. +## Cold-start bugs found on fresh boxes (AD-owned — report, don't try to fix in pup)++- **AD npm-install can't find `node` for lifecycle scripts (fixed ~AD 1.9.69).** On AD 1.9.63–1.9.65 the+  managed runtime ran `npm install` by absolute path but didn't put node on the child-process PATH, so any+  dep with a native/postinstall script that shells to `node` (keytar, sharp, **puppeteer**'s `install.mjs`)+  died: `'node' is not recognized`. Pup-side mitigation shipped v1.7.1: `sharp`+`keytar` are+  `optionalDependencies` + `sharp` loads gracefully (screenshots fall back to capture-size via a PNG-header+  dimension read). AD fixed the PATH on ~1.9.69 (npm install now succeeds on a fresh Edge-only box).+- **AD node-gate false-negative (open as of AD 1.9.69).** On a fresh box, `runtimes` shows+  `node.state:ready` (adom-managed), the bridge is `status:running` with a live pid, and `browser_readiness`+  (the declared **statusVerb**) works — but EVERY other `browser_*` verb returns AD-core `node_not_found`.+  The node pre-gate only exempts the statusVerb and does a stale/PATH-based node check that misses the+  portable managed runtime. pup CANNOT fix this (node_not_found fires in AD before the bridge). Reported on+  discussion #59; SKILL tells the AI to recognize it (readiness OK + runtimes ready + other verbs+  node_not_found = AD bug, don't loop desktop_install_node).+- **Takeaway:** when a fresh-box open fails, first read `runtimes` + `bridge_list` (pid/status) + try+  `browser_readiness`. If the runtime is ready and the bridge is running but verbs fail, it's an AD gate/+  provisioning bug — report it with that evidence; it is not a pup code bug.+ ## Publishing (the wiki has TWO storage layers — don't mix them)  Full recipe in `PUBLISHING.md`. The load-bearing rules:

@@ -1,6 +1,6 @@ {   "slug": "adom-desktop-puppeteer-bridge",-  "version": "1.8.0",+  "version": "1.8.1",   "type": "app",   "description": "CONTAINER-SIDE install \u2014 the everyday `pup` user skill only. This pkg drops the `pup` skill (drive the browser bridge: open/close/tabs/screenshot/record, background-by-default) into ~/.claude/skills/ AND ~/.codex/skills/. It does NOT install the developer/publishing skills (pup-bridge-dev, pup-bridge-publish) \u2014 those are source-only; clone the repo (adom-wiki repo clone adom/adom-desktop-puppeteer-bridge) to get them from dev-skills/. It also does NOT contain the bridge runtime: the bridge (Node + Chrome for Testing) lives on the DESKTOP \u2014 bundled inside Adom Desktop and published here on the Releases tab as adom-bridge-puppeteer-v<ver>.zip, which Adom Desktop streams into its bridges-cache. TL;DR: `pkg install` = the pup user skill; dev skills = clone the source; the bridge = the Release zip + bundled in Adom Desktop.",   "keywords": [