---
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).