Adom Hydrogen (Windows / WSL2)

@@ -1,165 +0,0 @@-----name: hd-workspace-lifecycle-description: WSL2 distro (`Adom-Workspace`) lifecycle management for Hydrogen Desktop on Windows. Import/export/unregister/terminate, code-server-as-HD-child, the resume reality-check, recovery after sleep/hibernate, and every hard-won rule about what NOT to do — above all, NEVER run global WSL operations; touch ONLY Adom-Workspace so a co-installed Docker Desktop WSL integration stays safe. MUST READ before any workspace operation. Trigger words — wsl, workspace, distro, Adom-Workspace, restart workspace, terminate distro, unregister, wsl --import, wsl --unregister, code-server, workspace broken, workspace unhealthy, wsl hung, fix workspace, /wsl/status.------# Hydrogen Desktop — WSL2 Workspace Lifecycle--> This is the WSL2-runtime version (default). The legacy Docker equivalent-> (`HD_RUNTIME=docker`) is in the docker/ bucket.--Under the WSL2 runtime the workspace is the **`Adom-Workspace` distro** (Ubuntu,-imported with `wsl --import`), running locally on the user's Windows machine.-`/home/adom/project` lives inside the distro — there is no Docker volume.--## ABSOLUTE RULE — NEVER touch global WSL state--**Operate ONLY on `Adom-Workspace`. Never run any global / cross-distro WSL command.**--Forbidden, no exceptions:-- ❌ `wsl --shutdown` (kills the entire WSL utility VM and every distro)-- ❌ `wsl --terminate` on any distro other than `Adom-Workspace`-- ❌ blanket killing of `wsl.exe` processes-- ❌ restarting the WSL service / utility VM-- ❌ `wsl --unregister` on anything but `Adom-Workspace`--**Why this matters:** the user may already run Docker Desktop, which cross-mounts a-proxy into every distro via the shared `/mnt/wsl` namespace-(`/mnt/wsl/docker-desktop/docker-desktop-user-distro`). Any global WSL teardown makes-that path vanish and pops a "Docker Desktop - Ubuntu: WSL integration unexpectedly-stopped" dialog. It's harmless to HD's own `Adom-Workspace`, but it looks to the user-like HD broke their Docker — terrible first-run UX. So every HD operation must be-scoped to `Adom-Workspace` and nothing else.--Allowed, scoped operations:-- ✅ `wsl --terminate Adom-Workspace` (this is what "Restart" does)-- ✅ `wsl --unregister Adom-Workspace` (destructive wipe, this distro only)-- ✅ `wsl --import Adom-Workspace <dir> <tarball>` (fresh import)-- ✅ `wsl -d Adom-Workspace -u adom -- <cmd>` (exec inside the distro)--## In-distro exec — NEVER `docker exec`--To run a command inside the workspace:-```bash-wsl -d Adom-Workspace -u adom -- <cmd>-# or-wsl -d Adom-Workspace -u adom -- su - adom -c '...'-```-There is no `docker exec` under this runtime, and no Docker container to exec into.--## Workspace Lifecycle--### Import (fresh setup)-`setup_and_start` → `WslDistroRuntime::setup_and_start` → `fresh_import`:-download `adom-golden.tar.gz` (the full pre-baked golden image, downloaded-anonymously from the `adom-inc/hd-wsl2-image` GitHub release, SHA256-verified)-then `wsl --import Adom-Workspace <dir> adom-golden.tar.gz`, then start code-server.-Log proof: `[wsl-tarball] downloaded … SHA256 OK` → `[setup] WSL setup_and_start completed`-and `wsl -l -v` shows `Adom-Workspace  Running  2`.--### code-server is an HD-OWNED CHILD process-code-server (`CODE_SERVER_CHILD` in `runtime/wsl.rs`) runs as a child of HD, deliberately-tied to HD's lifetime — **NOT a detached `nohup`** (a detached process dies when WSL-tears down the session anyway). Consequence: every HD restart (rebuild / crash /-relaunch) orphans the old code-server, so a fresh HD can come up with the distro-`Running` but the editor DEAD ("Starting AI Environment" forever) even when setup is-otherwise complete.--Fix (already in HD): HD **re-ensures code-server on every launch**-(`[wsl-startup] re-ensured code-server on launch`). And the resume reality-check in-`run_all_wsl` requires code-server reachable on the host port **7380** — not just-"distro registered" — before it trusts the workspace as ready.--### Restart-"Restart Workspace" = `wsl --terminate Adom-Workspace` + re-ensure code-server.-NOT `docker restart`. This is the fix for a workspace that's gone unreachable after-laptop sleep/hibernate.--### Stop-`wsl --terminate Adom-Workspace`. The distro stays registered (and your project files-persist); it just isn't Running.--### Export / backup-`wsl --export Adom-Workspace <file>.tar` snapshots the distro to a tarball. Re-import-with `wsl --import Adom-Workspace <dir> <file>.tar`. (Scoped to this distro, so safe.)--### Unregister (DESTRUCTIVE wipe)-`wsl --unregister Adom-Workspace` — deletes the distro AND everything in it, including-`/home/adom/project`. This is the only destructive wipe, and it names ONLY-`Adom-Workspace`. Never unregister any other distro.--## Control API--The HD control API is on loopback **`http://127.0.0.1:<dynamic>`** (NOT 9001). The-port is dynamic per launch — read the live URL from `~/.adom/hd-control-url`. From-inside the distro, reach the host at the same `127.0.0.1` URL: WSL2 mirrored-networking shares loopback with the Windows host.--| Endpoint | What it does |-|---|---|-| `GET /wsl/status` | Reports `Adom-Workspace` state — registered? Running? code-server reachable on :7380? |-| `POST /wsl/unregister` | Destructive: `wsl --unregister Adom-Workspace` (this distro only) |-| `GET /container-stats` | Live CPU/RAM/disk from the `workspace_stats()` probe (see hd-container-stats) |--```bash-BASE="$(cat ~/.adom/hd-control-url)"   # http://127.0.0.1:<dynamic>--# Workspace status (from inside the distro)-curl -s "$BASE/wsl/status"--# Destructive wipe of ONLY Adom-Workspace-curl -s -X POST "$BASE/wsl/unregister"-```--## Diagnosing Workspace Problems--### "Workspace unhealthy" / editor stuck on "Starting AI Environment"-- **Cause**: code-server child was orphaned by an HD restart, or the distro went-  unreachable after sleep.-- **Check**: `[wsl] Workspace unhealthy …` in the HD log (the real signal). NOTE: a-  `[docker] Container runtime unhealthy …` line under WSL is **benign noise** — a-  leftover heartbeat with no container bound. Ignore it; look at the `[wsl]` line.-- **Fix**: Restart Workspace (Adom menu) = `wsl --terminate Adom-Workspace` + re-ensure-  code-server. Verify code-server answers on :7380.--### Distro `Running` but editor dead-- **Cause**: code-server (HD's child) isn't up even though `wsl -l -v` shows Running.-- **Fix**: relaunch HD (it re-ensures code-server on launch), or Restart Workspace.-  Confirm via the resume reality-check — code-server reachable on :7380, not just-  "distro registered."--### WSL2 not available at all-- **Cause**: WSL2 isn't installed/enabled on the machine.-- **Fix**: the "WSL2 Not Available" floaty → "Run Setup Steps" walks the user through-  enabling it. See [hd-workspace-monitoring](../hd-workspace-monitoring/SKILL.md).--## Recovery Checklist--When the workspace is broken, follow this order:--1. **Check WSL2 itself**: `wsl --status` (NOT `wsl --shutdown`).-2. **Check the distro**: `wsl -l -v` — is `Adom-Workspace` listed and Running?-3. **If Running but editor dead**: code-server child orphaned → Restart Workspace-   (`wsl --terminate Adom-Workspace` + re-ensure code-server), or relaunch HD.-4. **Verify code-server**: it must answer on host :7380 (the resume reality-check).-5. **Last resort (destructive)**: `wsl --unregister Adom-Workspace` then re-import via-   `setup_and_start` — wipes the distro and re-imports `adom-golden.tar.gz`.-6. **NEVER** reach for global WSL ops to "fix" things — that breaks co-installed Docker-   Desktop, doesn't help your distro, and angers the user.--## What NOT To Do (learned the hard way)--- Do NOT run `wsl --shutdown` — global, kills every distro, breaks Docker Desktop's-  WSL integration.-- Do NOT `wsl --terminate` or `wsl --unregister` any distro except `Adom-Workspace`.-- Do NOT blanket-kill `wsl.exe` — same blast radius as `--shutdown`.-- Do NOT use `docker exec` / `docker restart` — there is no container in this runtime.-- Do NOT trust "distro registered" as healthy — require code-server reachable on :7380.-- Do NOT treat `[docker] … unhealthy` in the log as a real failure under WSL — it's-  benign; the real signal is `[wsl] Workspace unhealthy …`.--## Related skills--- [hd-workspace-monitoring](../hd-workspace-monitoring/SKILL.md) — the 15s poll, floaty states, lifecycle dialog, auto-start-- [hd-container-stats](../hd-container-stats/SKILL.md) — title-bar CPU/RAM bars + `workspace_stats()` probe-- [hd-networking](../hd-networking/SKILL.md) — port 7380 code-server, control port 47084, host reachability