Adom Hydrogen

@@ -0,0 +1,147 @@+# Setup steps pitfalls++Everything we know can go wrong while Hydrogen sets itself up on a Windows PC, what the person in front of the screen sees when it does, and what Hydrogen does about it. Each pitfall is a real report from a user or a test box, and the ones we can reproduce have a scenario script that runs against every build before it ships, so a fix stays fixed.++If you hit something during setup that is not on this page, please use **Report this problem** on the setup card. It's early days for Adom and unusual setups are exactly what we need to hear about; we try to fix reported problems within 2 hours.++## How setup works, in one paragraph++Hydrogen runs a Linux workspace (a WSL2 distro called `Adom-Workspace`) on your PC and puts a code editor and your AIs inside it. Setup does, in order: make sure WSL2 is on (installing it, with one Windows restart, if it is not), download and import the workspace image, connect the workspace to Windows (WSL's *mirrored networking*, so both share one `localhost`), start the editor, connect Adom Bridge (the link to your desktop apps), and finally check every piece for real before it calls itself done. Signing in to your AIs happens after setup, in the **Choose your AI** dialog.++## Recorded scenarios++Each video was recorded on a test PC with the build named in its caption, sped up where nothing is happening, with captions on every step.++| Scenario | What it shows | Video | Regression script |+|---|---|---|---|+| WSL2 installed from scratch | A PC that has never had WSL2: Hydrogen turns it on, asks for one restart, and finishes setup by itself afterwards | [video](wsl2-from-scratch.mp4) | `hd-vm-test.sh` (fresh snapshot) |+| Mirrored networking: first install and an advanced user's own choice | Hydrogen connects the workspace to Windows without asking; a user who deliberately set NAT keeps it, and the Your AIs dialog explains what that costs | [video](mirrored-networking.mp4) | `scripts/test-scenarios/wslconfig-mirrored.sh` |+| WSL's firewall blocks the workspace | A security tool or policy blocked WSL's network; Hydrogen allows exactly outbound and loopback with one admin prompt and finishes | *video to come* (passes on every build since 1.0.545) | `scripts/test-scenarios/wsl-network-blocked.sh` |+| 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 | [video](disk-almost-full.mp4) | `scripts/test-scenarios/disk-almost-full.sh` |++<video controls preload="metadata" width="1080" src="setup-steps-pitfalls/wsl2-from-scratch.mp4" style="max-width:100%;height:auto"></video>++*WSL2 from scratch, recorded on 1.0.554 on a clean Windows 11 PC with no WSL2. About 10 minutes of setup work: the installer, turning on WSL2 (about 30 seconds), one restart that waits for the user's click, then Hydrogen resumes by itself, builds the workspace and asks for the Adom sign-in. The frames where the tester typed their account details are replaced by a card.*++<video controls preload="metadata" width="1080" src="setup-steps-pitfalls/no-virtualization.mp4" style="max-width:100%;height:auto"></video>++*A PC that cannot run WSL2 (an Azure VM with the Windows hypervisor turned off), on 1.0.554. Captions say what 1.0.555 changes.*++<video controls preload="metadata" width="1080" src="setup-steps-pitfalls/disk-almost-full.mp4" style="max-width:100%;height:auto"></video>++*Not enough disk space (0.8 GB free on C:), on 1.0.554. Fixed in 1.0.556.*++<video controls preload="metadata" width="1080" src="setup-steps-pitfalls/windows10.mp4" style="max-width:100%;height:auto"></video>++*Windows 10 22H2: the installer stops before installing anything.*++<video controls preload="metadata" width="1080" src="setup-steps-pitfalls/mirrored-networking.mp4" style="max-width:100%;height:auto"></video>++*Mirrored networking, recorded on 1.0.552: first install turns it on with no question, the original setting is saved for uninstall, a user who sets NAT is respected, and the Your AIs dialog warns about AI sign-in. (On 1.0.554 and later the setup card no longer shows a warning at all; the Your AIs dialog is the only place it appears.)*++## 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.++### Before WSL2 is involved++| Pitfall | What you see | What Hydrogen does | Tested by |+|---|---|---|---|+| ARM64 PC (Surface Pro X and similar) | Setup stops: "This PC's processor is ARM64; Hydrogen needs an x64 PC" | Stops before the 800 MB download; nothing else is changed | Not yet (adom/hydrogen#89) |+| Setup started twice at once | (was) steps marked done that never ran | A lock makes the second start a no-op | Not yet |+| Saved progress says done but the workspace is gone | (was) "all steps done" with no workspace | Checks the real distro first; starts fresh if it is missing | Not yet |+| Workspace there but the editor died with an old Hydrogen | Editor stuck on "Starting" | Re-runs the workspace and editor steps | Not yet |+| A step left "running" by a crash | (was) setup stuck at one step forever | Only trusts a step as running if it really is | Not yet |+| A minute of silence on a cold PC | (was) a dead panel | Reads Windows' registry instead of waking WSL, and narrates | Not yet |+| A console window flashes during install | A black terminal pops up | Every helper runs hidden | Not yet |+| An old Adom Bridge from a previous install still running | Setup talks to a leftover | Reclaims stale processes; the uninstaller cleans up | Not yet |++### Turning on WSL2 (and the one restart)++| Pitfall | What you see | What Hydrogen does | Tested by |+|---|---|---|---|+| WSL2 is not installed | The card explains, one Windows permission prompt, then Restart now / Restart later | Installs WSL2 itself, shows the download and Windows' own progress, never restarts without your click, and resumes setup after the restart | `hd-vm-test.sh` |+| You click No on the permission prompt (or miss it over remote desktop) | "One quick permission to turn on WSL2" with a button to ask again | Waits for you; the button asks again | Not yet |+| GitHub is blocked on your network | "Couldn't download WSL2: this PC can't reach github.com" | Names the network problem instead of blaming your Windows edition | Not yet |+| WSL2 still missing after the install and restart | Manual steps for an admin PowerShell | Stops instead of restarting in a loop | Not yet |+| No hardware virtualization (BIOS setting off, an older or locked-down laptop, or a virtual machine without nested virtualization) | 1.0.555: "This PC can't run Hydrogen's workspace yet", two sentences, and a How to turn on virtualization button | Checks before installing WSL2 when Windows can tell (no hypervisor running and virtualization off in firmware); otherwise stops at the first workspace build with the same message, and brings the card to the front | [video](no-virtualization.mp4) |+| 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) |+| 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) |+| 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` |+| WSL is wedged before the install | A heartbeat, then a gentle restart countdown | Clears stuck WSL processes, asks for a restart at most twice, then gives manual steps | Not yet |++### Building the workspace++| Pitfall | What you see | What Hydrogen does | Tested by |+|---|---|---|---|+| 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 |+| 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) |+| 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) |++### Connecting the workspace to Windows (networking)++| Pitfall | What you see | What Hydrogen does | Tested by |+|---|---|---|---|+| WSL's default networking (NAT) | "Connecting your workspace to Windows" | Turns on mirrored networking, saves your original setting, and puts it back if you uninstall | `wslconfig-mirrored.sh` |+| You deliberately set another networking mode | Nothing during setup; the Your AIs dialog warns that AI sign-in needs mirrored networking, with a button to turn it back on | Respects your choice and never changes it back on its own | `wslconfig-mirrored.sh` (adom/hydrogen#100) |+| A security tool or policy set WSL's firewall to block it | (was) setup stopped at "Building your workspace" | One WSL restart, then one admin prompt that allows exactly outbound traffic and loopback; inbound stays blocked | `wsl-network-blocked.sh` (adom/hydrogen#100) |+| The network comes back slowly after that fix | (was) "not confirmed", and Try again worked a minute later | Waits up to 90 seconds for the network, then carries on | `wsl-network-blocked.sh` |+| Your organization's policy overrides the firewall | "A policy managed by your organization may be overriding it" | Says so and carries on | Not yet |+| Windows too old for mirrored networking (before Windows 11 22H2) | The installer stops (see Windows 10 above) | Since 1.0.555 the installer's own minimum is 22H2, so setup never meets this | [video](windows10.mp4) |+| A full-tunnel VPN | Windows is online but the workspace is not | Names the VPN adapter after setup | Not yet (adom/hydrogen#77) |+| A Windows proxy leaking into WSL | (was) a false "port taken" error | Checks from Windows first, bypassing the proxy | Not yet (adom/hydrogen#89) |++### Starting the editor++| 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 |+| 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 |++### Signing in++| Pitfall | What you see | What Hydrogen does | Tested by |+|---|---|---|---|+| 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 |+| 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)++| Pitfall | What you see | What Hydrogen does | Tested by |+|---|---|---|---|+| Adom Bridge can't be installed (no network) | A note that Hydrogen will retry on its next launch | Carries on; it is not needed to finish setup | Not yet |+| Adom Bridge slow to start | A note; it keeps trying | Carries on | Not yet |+| The connection to your desktop apps doesn't start | "Adom Bridge isn't connected yet: run setup again" | Run setup again restarts it | Not yet |++### The final check and the setup card++| Pitfall | What you see | What Hydrogen does | Tested by |+|---|---|---|---|+| A check fails at the very end | A title that names the problem, one sentence on what to do, and one button that says what it does (for example Run setup again, or Reconnect and finish setup) | Every failure has a plain explanation; Continue anyway skips ahead; Report this problem sends us the log | Any scenario that stops |+| (was) the card quoted a log line and offered Try again / Open Hydrogen / Report side by side | | Replaced on 1.0.554 | |++## For developers: running the scenarios++Each script lives in `scripts/test-scenarios/` in the Hydrogen source and has three phases: `arm` (put the test PC into the bad state), `check` (exit 0 means Hydrogen handled it), and `disarm` (always run it, even after a failure). They run on the Azure test VM `winvm` with the tester's remote-desktop view open. The ralph skill lists them under "Regression scenarios (run on EVERY build)"; adding a pitfall to this page means adding a script there too.