Adom Hydrogen (platform base)

@@ -1,144 +0,0 @@-----name: hydrogen-wake-repair-description: >-  How Hydrogen 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 Hydrogen 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, run wake check, wake check menu, backend-  banner, workspace stopped responding, reconnect button.------# Hydrogen Wake Repair (reconnect after laptop sleep)--> The heal cascade below manipulates the `Adom-Workspace` WSL distro.--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. Hydrogen 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.--## Running it manually: Adom menu > "Run Wake Check"--The whole cascade can be triggered on demand from the Adom menu ("Run Wake-Check", right after API Explorer). The tooltip behavior is deliberate:--- **Manual trigger** (menu item): the wake icon appears AND the info tooltip-  pins itself open so the user can watch every phase live, then unpins shortly-  after the heal reaches a terminal phase (with a 45s safety timeout).-- **Automatic wake** (real sleep resume, or `POST /wake/simulate`): icon only,-  no tooltip. Hovering the (i) icon shows it. An unrequested tooltip popping-  over the editor would be noise.--## The backend watchdog banner (catches what wake events miss)--Wake detection covers sleep resume, but a workspace can die without any wake-event (WSL wedge, code-server crash). The VS Code panel therefore polls-`/workspace/health` every 8 seconds for its whole life. Two consecutive misses-of `editor_will_load` show an amber banner over the editor: "Your workspace-stopped responding - this can happen after your laptop sleeps", with a-**Reconnect** button that runs the same heal cascade (`POST /wake/simulate`).-`editor_will_load` is honest: it is a real HTTP GET of code-server's-`/healthz` (success or redirect), not a bare TCP connect, because a wedged-code-server can still accept TCP while serving nothing.--For a full-stack diagnosis beyond wake issues, use the Doctor-(Adom menu > "Doctor...", or `GET/POST /doctor`, see `hydrogen-doctor`); its-"Fix problems" button runs this same cascade plus before/after evidence.--## 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 Hydrogen control API (port from `~/.adom/hydrogen-control-url`, see `hydrogen-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. Hydrogen 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).--## The reveal invariant (2026-08-06, the overnight grey-pane disaster)--The pane phase above got a hard rule after an overnight sleep left a dead grey-editor pane revealed all morning:--- **The editor pane may only be revealed after the iframe has (re)loaded-  against a backend CONFIRMED serving** (`/workspace/health` reports-  `editor_will_load`) **and painted.** A paint timeout alone proves nothing: a-  stale error page passes both a timeout and a healthy-backend check.-- **":8821 up" means the backend is alive, NOT that the iframe reloaded onto-  it.** If the iframe last loaded while the backend was dead, it is a stale-  corpse: force one reload onto the live backend before any reveal-  (the `reloadedAgainstHealthy` gate in PanelVisualStudioCode.svelte).-- While the backend is unreachable: keep the orbital splash up and hard-reload-  the iframe (about:blank then the URL) on a bounded cadence. Never reveal.-- The post-wake stuck-dialog reload waits up to ~60s for-  `editor_will_load` before reloading the pane (wake_heal.rs) so it cannot-  reload INTO a dead backend.--Testing rule (how round 1 shipped broken): **screenshot the RECOVERY frame,-not just the outage.** Kill code-server inside the distro, verify the splash-(outage frame), bring it back, and verify the editor self-reveals with real-content (recovery frame). Round 1 passed the outage and revealed a stale error-page on recovery; only the recovery screenshot caught it.