Adom Hydrogen

@@ -20,6 +20,9 @@ Each video was recorded on a test PC with the build named in its caption, sped u | Windows 10 | The installer stops right away with a clear message, before installing anything | [video](windows10.mp4) | installer gate (manual run on an Azure Windows 10 VM) | | No hardware virtualization | A PC that cannot run WSL2: what it saw on 1.0.554 (installed WSL2, restarted, then hid the explanation behind other windows) and what 1.0.555 changes | [video](no-virtualization.mp4) | manual run on an Azure VM with the hypervisor off | | Not enough disk space | With 0.8 GB free the import filled the drive, setup sat silent for ten minutes, then asked for a Windows restart; 1.0.556 checks for 8 GB first and stops in a second (verified on winvm); Adom Bridge's approval box covered that message, fixed for 1.0.557 | [video](disk-almost-full.mp4) | `scripts/test-scenarios/disk-almost-full.sh` |+| Expired Adom sign-in | The saved session is rejected; Hydrogen clears it and opens a fresh sign-in while setup carries on | [video](dead-session.mp4) | `scripts/test-scenarios/dead-session.sh` |+| Another WSL distro already running | Hydrogen never stops it on its own; when it needs one WSL restart it names the distro and lets you choose (1.0.559) | [video](other-distro-running.mp4) | `scripts/test-scenarios/other-distro-running.sh` |+| Workspace download blocked | Setup stops in seconds and says your network is blocking Adom's download server (1.0.557) | [video](image-download-blocked.mp4) | `scripts/test-scenarios/image-download-blocked.sh` |  <video controls preload="metadata" width="1080" src="setup-steps-pitfalls/wsl2-from-scratch.mp4" style="max-width:100%;height:auto"></video> @@ -45,6 +48,18 @@ Each video was recorded on a test PC with the build named in its caption, sped u  *WSL's firewall blocks the workspace, recorded on 1.0.554: Hydrogen finds outbound and loopback blocked, allows exactly those two with one admin prompt (this test PC has UAC off, so the prompt does not show), and setup finishes on its own.* +<video controls preload="metadata" width="1080" src="setup-steps-pitfalls/dead-session.mp4" style="max-width:100%;height:auto"></video>++*Expired Adom sign-in, recorded on 1.0.559: Hydrogen clears the dead session and opens a fresh sign-in; setup carries on.*++<video controls preload="metadata" width="1080" src="setup-steps-pitfalls/other-distro-running.mp4" style="max-width:100%;height:auto"></video>++*Another WSL distro running, 1.0.556 then 1.0.559: Hydrogen never stops it on its own; 1.0.559 explains the one restart it needs and lets you choose.*++<video controls preload="metadata" width="1080" src="setup-steps-pitfalls/image-download-blocked.mp4" style="max-width:100%;height:auto"></video>++*Workspace download blocked, 1.0.556 then 1.0.559: from the wrong advice to a plain explanation.*+ ## The pitfalls, by setup phase  **Tested by** names the scenario script that reproduces it on a test PC. *Not yet* means it is documented here and handled in the code, but has no automated reproduction yet.@@ -74,9 +89,9 @@ Each video was recorded on a test PC with the build named in its caption, sped u | Windows 10, or Windows 11 before 22H2 | The installer says "Adom Hydrogen needs Windows 11, version 22H2 or newer" with the PC's version and build | Stops before installing anything. Before 1.0.555 the gate let Windows 11 21H2 through (build 22000), which then failed in setup, and named the wrong reason | [video](windows10.mp4) | | Restart later | Setup waits; a gentle reminder every few minutes | Never forces a restart; finishes after whatever restart you choose | Not yet | | Edge says "Restore pages: Microsoft Edge closed unexpectedly" after the restart | A bubble over the Adom sign-in page | Nothing yet: the restart closed Edge, and Edge offers to restore it. Harmless, but confusing at the one moment we need the user | `hd-vm-test.sh` (seen 2026-10-06) |-| Windows asks "Allow important notifications from Adom Bridge?" | A Windows prompt about an app the user has never heard of, on top of the sign-in | Nothing yet: Adom Bridge asks for that permission on its first start, which lands during setup. To fix: ask later, after setup | `hd-vm-test.sh` (seen 2026-10-06) |+| Windows asks "Allow important notifications from Adom Bridge?" | A Windows prompt about an app the user has never heard of, on top of the sign-in (Seen on test PCs signed in to an account whose Adom Bridge is linked to other machines, which mirror their alerts in; still to confirm on a single-PC account.) | Nothing yet: Adom Bridge asks for that permission on its first start, which lands during setup. To fix: ask later, after setup | `hd-vm-test.sh` (seen 2026-10-06) | | Edge's own first-run welcome takes over the screen | A brand-new PC: the first thing that opens Edge (the Adom sign-in) gets "Welcome to Microsoft Edge" first | Nothing yet; the user clicks through Edge's welcome. Seen on a fresh Windows 11 VM, 2026-10-06 | Not yet |-| Hydrogen's message hidden behind other windows when setup stops | (was) the Adom sign-in in Edge and Adom Bridge's red activity log on top, Hydrogen's explanation found last | 1.0.555 brings the setup card to the front when setup stops (only then) | [video](no-virtualization.mp4) |+| Hydrogen's message hidden behind other windows when setup stops | (was) the Adom sign-in in Edge and Adom Bridge's red activity log on top, Hydrogen's explanation found last (Seen on test PCs signed in to an account whose Adom Bridge is linked to other machines, which mirror their alerts in; still to confirm on a single-PC account.) | 1.0.555 brings the setup card to the front when setup stops (only then) | [video](no-virtualization.mp4) | | Windows Defender flags an unsigned helper as a trojan | The program disappears | Hydrogen and Adom Bridge are code-signed; on a Windows 10 test PC Defender's machine-learning check quarantined our own unsigned test robot (`Trojan:Win32/Bearfoos.B!ml`), not anything we ship | Seen on a test PC, 2026-10-06 | | Windows' "You're almost done setting up your PC" page after the restart | (was) that page covered Hydrogen | Turns those pages off before the restart | Not yet | | The "Welcome to WSL" window pops over Hydrogen | A stray WSL window | Minimizes it | `hd-vm-test.sh` |@@ -89,12 +104,13 @@ Each video was recorded on a test PC with the build named in its caption, sped u | Slow download of the workspace image | Progress with size, speed and time left | Starts the download early (it overlaps the WSL restart) and resumes after an interruption | Not yet | | Download cut short (restart, crash, network drop) | "Stopped at X of Y, resumes" | Resumes from where it stopped | Not yet | | Corrupt download | Setup stops on the image check | Deletes it; Run setup again downloads it fresh | Not yet |+| The workspace download is blocked (company network, VPN, proxy, security tool) | 1.0.557+: "Hydrogen couldn't download your workspace. Your PC could not reach Adom's download server..." (was, on 1.0.556: "open PowerShell and run wsl --unregister", the wrong fix) | Stops within seconds, no hang, no crash; Run setup again resumes once the network allows it | `image-download-blocked.sh`, [video](image-download-blocked.mp4) | | Not enough disk space | 1.0.556: "Your C: drive is almost full (N GB free). Hydrogen's workspace needs about 8 GB..." before anything is built | Checks before building; if a drive fills anyway, the four-minute no-progress watchdog says the drive is full instead of asking for a Windows restart (which it did before) | `disk-almost-full.sh`, [video](disk-almost-full.mp4) | | A workspace left half-registered by a crash | (was) every import failed | Removes only Hydrogen's own leftover and imports again | Not yet | | Another WSL command during the workspace's first boot | (was) a permanently broken workspace | One WSL command at a time while it boots | Not yet | | The workspace never finishes booting | "WSL2 looks wedged: run wsl --shutdown, then Run setup again" | Stops with the exact fix | Not yet | | WSL's management service throws "Catastrophic failure" | Retries, then the fix | Retries with backoff, never shuts down your other WSL distros | `HD_TEST_WSL_FAIL` test hook |-| Other WSL distros running (Docker Desktop, your own Ubuntu) | A note that a WSL restart was skipped | Never stops your distros; applies its settings at the next natural WSL restart | Not yet (adom/hydrogen#85) |+| Other WSL distros running (Docker Desktop, your own Ubuntu) while a setting needs a WSL restart | 1.0.559: "Hydrogen needs to restart WSL once. Another Linux distribution is running (*name*)... Restarting WSL stops *name* too: save your work there, then restart." with a Restart WSL and finish setup button (was: "This usually clears up on its own: run setup again", which never could, verified on 1.0.556) | Never stops your distros on its own; the restart happens only when you press the button | `other-distro-running.sh` (adom/hydrogen#85), [video](other-distro-running.mp4) | | A busy workspace mistaken for a broken disk | (was) a WSL restart, then a request to restart Windows on a healthy PC | Waits for a real answer; only a real disk failure counts | Not yet (found on a test PC, 2026-10-06) | | A busy workspace mistaken for a missing editor | (was) the editor reinstalled from scratch | Only reinstalls on a real "not installed" | Not yet (found on a test PC, 2026-10-06) | @@ -116,7 +132,7 @@ Each video was recorded on a test PC with the build named in its caption, sped u | Pitfall | What you see | What Hydrogen does | Tested by | |---|---|---|---| | Windows can't reach the editor | "Windows could not reach the workspace: a VPN, security tool or firewall" | Three repair rounds, then the network fix, then a clear diagnosis | `wsl-network-blocked.sh` |-| Port 7380 already taken by another app | "Port 7380 is held by *app name*; free the port" | Names the app holding it | Not yet |+| Port 7380 already taken by a Windows app | 1.0.558: "Another app is using Hydrogen's editor port. Port 7380 is in use by *app name* on Windows... Close it, then run setup again." (was: the generic "Setup didn't finish", verified on 1.0.556) | Asks Windows which app is listening and names it; an app inside the workspace was already named | `port-7380-taken.sh` | | The editor listening on your whole network | (was) a passwordless editor visible on your Wi-Fi | Listens on this PC only, and moves older installs over at launch | ralph `codeserver.localhost_only` (adom/hydrogen#100) | | The editor waits for your Adom sign-in | "Waiting for you to finish signing in to Adom" | Waits as long as you need | `hd-vm-test.sh` | | The editor's extension never starts | "The editor didn't finish starting" | Run setup again restarts it | Not yet |@@ -128,7 +144,7 @@ Each video was recorded on a test PC with the build named in its caption, sped u | You close the Adom sign-in window | "Closed, so I am opening it again" | Reopens it up to three times, then shows a button | Not yet | | The sign-in link expires (about 15 minutes) | "The link expired, I opened a fresh one" | Opens a fresh link twice, then a button | Not yet (adom/hydrogen#39) | | You sign in hours later | Setup waits | No deadline; carries on when you sign in | Not yet |-| A saved sign-in from an old install has expired | (was) setup stuck for 6 minutes at "Opening your editor" | Checks the saved sign-in with Adom; if it is dead, asks you to sign in fresh | Not yet |+| A saved sign-in from an old install has expired | The Adom sign-in page opens with one Approve button (verified on 1.0.559; was: stuck 6 minutes at "Opening your editor") | Checks the saved sign-in with Adom at launch; if it is dead, clears it and asks you to sign in fresh while the workspace keeps building | `dead-session.sh`, [video](dead-session.mp4) | | The sign-in opens in Edge instead of your browser | (was) the wrong browser | Opens your default browser | Not yet |  ### Adom Bridge (your desktop apps)

⋯ 1 unchanged line ⋯

⋯ 1 unchanged line ⋯

⋯ 1 unchanged line ⋯