Adom Hydrogen (platform base)

@@ -0,0 +1,240 @@+---+name: hydrogen-adom-bridge-triage+description: >+  Triage Adom Bridge (ab) when it will not connect from a Hydrogen workspace —+  especially the case where ab CRASHES ON BOOT because a bad release shipped,+  which looks identical to "not installed" / "not signed in" from the container+  side. Teaches the cheapest-first diagnostic ladder (read ab's crash.log BEFORE+  touching any config), the two out-of-band channels that work while ab is dead+  (Hydrogen's control API and WSL2 interop), how to compare the installed build+  against the wiki and install the fix, and the config changes you must NOT make+  while guessing. Read this when `adom-bridge ping` says no desktop client is+  connected, when the user says the app "never actually starts", when it starts+  and vanishes, or when hydrogen-doctor's adom-bridge / adom-bridge-direct check+  fails. Trigger words: adom bridge won't start, ab won't connect, bridge not+  connected, no desktop client connected, ab never starts, ab starts then+  disappears, bridge offline, ab crash loop, ab crashing on boot, bad ab release,+  connectedClients 0, adom-bridge-direct failed, bridge keeps dying, ab tray+  missing.+---++# Triage: Adom Bridge won't connect++`ping` returning **"No desktop client connected"** tells you only that the+desktop half is absent. It does **not** tell you whether ab is uninstalled,+signed out, misconfigured, or **installed and crash-looping**. Those need+opposite fixes, and the last one is invisible from the container unless you+go looking for it.++> **The failure that motivated this skill.** ab 2.0.91 panicked on startup,+> died in under a second, and was respawned by Hydrogen's supervisor every+> ~30-60s — 367 times over ~3 hours. From the container it looked exactly like+> "the user never installed it." The user's own words were *"when I launch it+> from the Windows menu it never actually starts."* The fix was one version+> newer on the wiki. Time wasted before reading `crash.log`: most of the session.++## The ladder — cheapest first, and read crash.log EARLY++### 1. Which half is broken? (container-side, free)++```bash+curl -sf http://127.0.0.1:8766/health     # connectedClients, usingDefaultToken+adom-bridge --ai-thread "<your thread>" ping+adom-bridge --ai-thread "<your thread>" targets+```++`connectedClients: 0` with a healthy relay ⇒ the container is fine; **every+remaining step is about the desktop**. Do not start reconfiguring the container.++### 2. Ask Hydrogen — it can see the host while ab is dead++Hydrogen's control API (`127.0.0.1:47084`, port from+`~/.adom/hydrogen-ports.json`) is reachable from the workspace and does **not**+depend on ab:++```bash+curl -s http://127.0.0.1:47084/diagnostics/all | python3 -m json.tool+```++Look for the `adom-bridge-direct` check. Its failure text names the cause and+carries a `fix` field. Note it probes ab's direct API, so read the port caveat+in **Gotchas** below before trusting a "silent range" message.++### 3. **Read ab's crash log. Do this before touching any config.**++This is the step that collapses a long session into two minutes.++| What | Windows path | From a WSL2 workspace |+|---|---|---|+| Crash log | `%LOCALAPPDATA%\Adom Bridge\crash.log` | `/mnt/c/Users/<user>/AppData/Local/Adom Bridge/crash.log` |+| Install dir | `%LOCALAPPDATA%\Adom Bridge\` | same, without `crash.log` |+| Direct-API port | `%USERPROFILE%\.adom\direct-api-port` | `/mnt/c/Users/<user>/.adom/direct-api-port` |+| Embedded marker | `%LOCALAPPDATA%\Adom Bridge\embedded.json` | same |+| Server list | `%USERPROFILE%\.adom\config.json` | `/mnt/c/Users/<user>/.adom/config.json` |++```bash+C="/mnt/c/Users/<user>/AppData/Local/Adom Bridge/crash.log"+ls -l "$C"      # mtime is the whole story+tail -40 "$C"+```++**Read the mtime first.** A `crash.log` modified *seconds or minutes ago* means+ab is crash-looping **right now** — it is installed, it is being launched, and+it is dying. That single fact rules out the entire "not installed / not signed+in / wrong URL" branch you were about to explore.++A crash loop looks like one repeating panic with a marching clock:++```+[2026-08-31 19:44:04] PANIC: panicked at src\carbon_runtime.rs:113:5:+there is no reactor running, must be called from the context of a Tokio 1.x runtime+[2026-08-31 19:44:55] PANIC: panicked at src\carbon_runtime.rs:113:5:+...+```++Useful shape checks:++```bash+grep -c "PANIC" "$C"                                   # how bad+grep -n "PANIC" "$C" | head -3                         # when it STARTED+grep -v "carbon_runtime\|no reactor running" "$C" | tail   # other panic classes+```++A panic in a path under `src\...` is **ab's own code** — i.e. a shipped+regression, not a broken machine. A panic inside `.cargo\registry\...` is a+dependency/host-environment issue and usually a different story.++### 4. Compare the installed build against the wiki++```bash+"/mnt/c/Users/<user>/AppData/Local/Adom Bridge/adom-bridge-cli.exe" --version+adom-wiki release list adom/adom-bridge          # newest version + assets+```++A `-dirty` suffix in the installed version means it was built locally, not+installed from a signed wiki release — common on a developer's own machine and+a strong hint that it is ahead of, or diverged from, anything published.++If the installed build is older than the wiki's newest **and** `crash.log`+shows a repeating panic, **the newer release is the fix**. Go to step 5.++### 5. Install the newer release++```bash+adom-wiki release download adom/adom-bridge <version>     # verifies integrity+sha256sum ./Adom.Bridge_<version>_windows_x64-setup.exe    # confirm independently++cp ./Adom.Bridge_<version>_windows_x64-setup.exe /mnt/c/Users/<user>/AppData/Local/Temp/+cd /mnt/c/Users/<user>/AppData/Local/Temp+/mnt/c/Windows/System32/taskkill.exe /F /IM adom-bridge.exe   # release the mmap lock+./Adom.Bridge_<version>_windows_x64-setup.exe /S /NOLAUNCH+tr -d '\r' < ./adom-bridge-install.log | tail -20              # [START]...[DONE]+```++**Use `/NOLAUNCH` when Hydrogen manages ab** (the usual case in a Hydrogen+workspace — see the `hd-managed` marker in the install dir). Hydrogen's+supervisor spawns ab itself with `--embedded --start-hidden --relay-url+... --session-token ...`; let it, or you get a standalone instance that the+single-instance logic then fights.++### 6. Verify — three independent signals, not one++```bash+sleep 45                                                     # let the supervisor respawn+/mnt/c/Windows/System32/tasklist.exe /FI "IMAGENAME eq adom-bridge.exe"+curl -sf http://127.0.0.1:24680/health                       # {"service":"adom-bridge","pid":...}+adom-bridge --ai-thread "<thread>" targets                   # name, os, version+ls -l "$C"                                                   # crash.log mtime must STOP advancing+```++The crash.log mtime going quiet is the one that proves you fixed the loop+rather than catching ab between crashes. Give it more than one crash interval+before declaring success.++## The out-of-band channels (why you are not blind)++When ab is dead you have not lost the host — you have lost one route to it.++1. **Hydrogen's control API** — `127.0.0.1:47084`, always up if Hydrogen is+   running. Diagnostics, ports, container state. See `hydrogen-api`.+2. **WSL2 interop (Windows hosts)** — a Hydrogen Windows workspace is a WSL2+   distro, so `/mnt/c` is the real Windows filesystem and Windows `.exe`s are+   directly executable from the workspace:++   ```bash+   ls /mnt/c/Users                                   # is it mounted?+   cat /proc/sys/fs/binfmt_misc/WSLInterop           # "enabled"?+   /mnt/c/Windows/System32/tasklist.exe              # proof it works+   ```++   This is how you read crash logs, check versions, and run an installer+   **without ab**. On macOS/Linux Hydrogen hosts this section does not apply;+   use the platform bootstrap's equivalent and the control API.++## Do NOT do these while guessing++Every one of these was tried during the incident above. None helped, and the+first two left changes that had to be reverted.++| Don't | Why |+|---|---|+| `register_container` when Hydrogen already manages ab | Creates a **second** connection to the same workspace relay alongside the managed `hydrogen` entry — a duplicate path the user sees in the Connections list. It also writes **three** cloud keys, not one. Check for the managed entry / the `hd-managed` marker first. |+| Rotate the relay auth token | For a cloud container the auth model is the **Adom account**, not a relay token — `setup_desktop` deliberately emits `auth_token: ""`. Rotating adds a mismatch failure mode to a system that is already broken, and the relay's `usingDefaultToken` warning assumes a directly-exposed port, which a proxied container relay is not. |+| `POST /setup/run-step` on Hydrogen's control API | Marked `_safety: destructive`. It refuses without a visible UI (HTTP 410) and points you at the Setup panel. Not a debugging tool. |+| Conclude "not installed" / "not signed in" from `ping` alone | Indistinguishable from a crash loop without reading `crash.log`. |+| Restart the relay, re-register, re-sign-in as a first move | All container-side; none of them touch a desktop process that is panicking. |++## Reverting a mistaken `register_container`++If you (or a previous agent) registered a container that should not exist,+removing it locally is **not enough** — ab re-reads the cloud profile at boot,+at sign-in, and hourly, so a local-only removal comes back. Remove both:++```bash+TOK=$(cat /var/run/adom/api-key)++# 1. cloud profile (the authoritative copy)+curl -s -X PATCH https://carbon.adom.inc/user/hydrogen/settings \+  -H "Authorization: Bearer $TOK" -H 'Content-Type: application/json' \+  -d '{"key":"bridge.container.<id>","value":null}'++# 2. ab's local list+adom-bridge --ai-thread "<thread>" \+  server_remove '{"name":"<name>","reason":"<why>"}'+```++`register_container` writes **`bridge.container.<id>`, `bridge.last_slug`, and+`bridge.enabled`**. `bridge.last_slug` will be left pointing at the entry you+just deleted; null it too. Its previous value is **not recoverable** — which is+the real argument for not calling `register_container` speculatively.++Verify with `server_list` and by re-reading `hydrogen_preferences.settings`+(see `hydrogen-key-values`). Removing a relay entry you are *talking through*+severs your own transport (adom/adom-bridge#387) — check `ping`'s `transport`+field first; if it says `direct-http` you are on the loopback API and a relay+entry removal cannot cut you off.++## Gotchas that cost time++- **ab's direct API is on `24680`** (stable since ab 2.0.27); `47200-47209` is+  legacy. A diagnostic that probes only the legacy range can report ab+  unreachable when it is merely elsewhere. `%USERPROFILE%\.adom\direct-api-port`+  is authoritative (written at bind, removed on clean shutdown), so a *stale*+  file plus a silent port is itself a crash signal.+- The 2.0.92 installer reserves `24680-24689` via `netsh excludedportrange`+  (best-effort, needs elevation) to stop Windows HNS grabbing the range.+- **Caller identity is mandatory.** Verbs refuse with+  `errorCode: caller_identity_required` unless you pass+  `--ai-thread "<a name the user would recognize>"`. Gated verbs additionally+  need a per-call `reason`. See `adom-bridge-caller-identity`.+- `embedded.json` with `entered_via: "launch-flag"` plus a dead Hydrogen makes+  ab exit by design ("no hanging chad"). Pre-1.8.74 builds did not delete the+  stale marker, leaving ab unlaunchable — a different crash-on-boot cause with+  the same symptom, so confirm which one `crash.log` actually shows.++## When it is genuinely not a crash++If `crash.log` is old and quiet and no ab process exists, you are in ordinary+setup territory: installed? signed in? does the workspace's connection appear+in the Connections list? Then follow `adom-bridge` / `adom-bridge-auth`. The+point of this skill is to make you *prove* that before you go there.