Adom Hydrogen (platform base)

@@ -0,0 +1,92 @@+---+name: hd-wake-repair+description: >+  How Hydrogen Desktop automatically repairs the workspace connection after the+  laptop wakes from sleep: the wake-heal cascade, the header wake indicator with+  its live info tooltip, the Settings > Desktop > Wake section (heal toggle,+  indicator toggle, linger slider), and the /wake/* control API endpoints. Read+  this when the user reports HD did not reconnect after sleep, sees a "cannot+  reconnect" dialog, asks what the sunrise/sync icon in the header is, or wants+  to test or configure wake behavior.+  Trigger words: wake from sleep, laptop sleep, lid close, sleep resume, resume+  from sleep, reconnect after sleep, wake repair, wake heal, wake indicator,+  sunrise icon, cannot reconnect, workspace stuck after wake, wake status,+  wake simulate, wake settings.+---++# HD Wake Repair (reconnect after laptop sleep)++> WSL2-runtime version (default). The heal cascade below manipulates the+> `Adom-Workspace` WSL distro; the legacy Docker runtime does not have this+> feature.++When the laptop sleeps, WSL2 networking and code-server often come back wedged:+the user reopens the lid and sees a dead editor pane or VS Code's "Cannot+reconnect" dialog. HD detects the wake natively (Win32 power notifications,+both manual and automatic resume, deduplicated) and runs an automatic repair so+the user should normally have to do NOTHING.++## What the user sees++- **Wake indicator** in the header, to the right of the lightbulb (only if+  enabled in settings, default off): a spinning sync icon while healing, a+  sunrise icon when the heal finished, an alert icon if it failed.+- Hovering the small **info (i) icon** next to it shows a live tooltip with the+  current phase and the last log lines, updating as the heal runs.+- The indicator lingers for a configurable time after the wake (default 60s),+  then hides itself.++## Settings (Settings window > Desktop > Wake)++| Setting | Key | Default | Meaning |+|---|---|---|---|+| Repair connection after wake | `desktop.wake_heal` | on | Run the heal cascade on resume. Turning it off means wakes are only logged. |+| Show wake indicator | `desktop.wake_indicator` | off | Show the header indicator + info tooltip after a wake. |+| Indicator linger | `desktop.wake_indicator_linger` | 60s | Slider (0-600s, 15s steps): how long the indicator stays visible after a wake. |++If the user complains about reconnects, suggest turning the indicator ON so+they (and you) can watch what the heal is doing.++## Control API endpoints++On the HD control API (port from `~/.adom/hd-control-url`, see `hd-api`):++- `GET /wake/status` — full state: `last_sleep_at`, `last_wake_at`, `wake_kind`,+  current `phase`, `healing`, `heal_enabled`, and the recent log (capped 40+  lines). **Always read this first** when debugging a wake complaint.+- `POST /wake/simulate` — fires a fake wake event and runs the real heal+  cascade end-to-end. Safe to use for testing; takes ~20-60s on a healthy+  system.+- `POST /wake/config` `{"heal_enabled": true|false}` — toggle healing at+  runtime (the settings toggle calls this).++## What the heal actually does (so you can explain or debug it)++Three phases, visible in the `/wake/status` log:++1. **Backend** — polls workspace health up to 8 rounds x 12s. Restarts+   code-server at round 2 if still down. If a WSL wedge is suspected, runs+   `wsl --terminate Adom-Workspace` at round 4 and lets the distro boot fresh.+   A full `wsl --shutdown` is NEVER automatic (it would kill other distros);+   that remains a manual last resort.+2. **Token re-stamp** — `/var/run/adom/api-key` lives on tmpfs inside the+   distro, so a distro restart wipes it. HD re-writes it from the saved+   session so agents inside the workspace keep working.+3. **Pane** — checks the VS Code pane up to 3 x 15s for a stuck "Cannot+   reconnect" dialog and, only if stuck, reloads the editor iframe (pane-only+   reload, not the whole app).++## From inside the workspace (your perspective)++A laptop sleep looks to you like a frozen clock and a brief network blackout.+After a wake: your API key file may have just been re-stamped, and code-server+may have restarted underneath you. If the user says "it didn't come back":++1. `GET /wake/status` and read the log — did the heal run, and where did it+   stop?+2. If `heal_enabled` is false, ask the user if they want it on+   (`POST /wake/config`).+3. `POST /wake/simulate` reproduces the whole flow on demand.+4. If the heal reports failure repeatedly, the workspace may need a manual+   restart: Adom menu > Restart Container (which shows a live log of what it+   is doing).