Adom Bridge

@@ -2240,6 +2240,29 @@ Every `wsl_exec` / `run_script bash` spawns a `wsl.exe` client. If WSL's service    It classifies each `wsl.exe`: childless + (0-CPU & old | runaway-CPU) → **candidate**; everything else → **spared**. It **spares any `wsl.exe` with child processes** (that's almost certainly the live distro, e.g. the HD `Adom-Workspace`), honors `sparePids`, and never touches `wslservice`/`wslhost`/`vmmem`. Review each candidate's `cmd` in the dry-run to confirm the live workspace isn't among them, then confirm. **Never** `wsl --shutdown` (it kills the live workspace too). Reaping childless orphans often cascades — their now-parentless children exit on their own (observed 114 → 18 from reaping 54). 3. **status wsl block** — `{wslProcessCount, wedged, _hint}` lets you see a pile-up *before* it blocks work. Path differs by transport: **`status.desktop.wsl`** via the CLI/relay (`adom-desktop status` — nested like `desktop.apps`), or top-level **`status.wsl`** on the local direct API (`GET /status`). `wedged:true` at/above `WSL_WARN_AT=50`. +#### Long-running in-distro work + distro lifecycle — golden-image bakes (v1.8.161+)++`wsl_exec` is **synchronous** — it waits for the command and is bounded by the relay's HTTP timeout (~60-120s), so a multi-minute bake (apt, a big download) EOFs. Backgrounding inside the distro (`nohup … &`) doesn't help either: the `wsl.exe` client returns, WSL sees no active session, shuts the distro down, and kills the bg process (wiping `/tmp`). For anything long, use the **async held-session** verbs — AD holds one `wsl.exe` in the foreground for the command's whole lifetime, so the distro stays up:++- **`wsl_exec_async`** → returns a `jobId` + `outputPath` (a live UTF-8 log) immediately; the command runs detached for as long as it takes.+- **`wsl_job_status {jobId}`** → `{running, exitCode, elapsedMs, outputTail, outputPath}`. Poll until `running:false`; `pull_file` the `outputPath` for the full log. (`wsl_job_list`, `wsl_job_kill {jobId}` round it out.)++```bash+# golden-image bake: import → run (async) → poll → export → unregister, all via AD+adom-desktop wsl_import '{"distro":"bake","installDir":"C:/Users/<you>/.adom/wsl/bake","tarball":"C:/.../base.tar"}'+#   → {jobId}; poll wsl_job_status until done (exitCode 0)+B64=$(printf 'set -euo pipefail\napt-get update && apt-get install -y build-essential\n' | base64 -w0)+adom-desktop wsl_exec_async "{\"distro\":\"bake\",\"user\":\"root\",\"scriptB64\":\"$B64\"}"+adom-desktop wsl_job_status '{"jobId":"wsljob-xxxxxxxx"}'   # repeat until running:false; outputTail = progress+adom-desktop wsl_export '{"distro":"bake","tarball":"C:/.../golden.tar"}'   # poll, then pull_file the tarball+adom-desktop wsl_unregister '{"distro":"bake"}'            # cleanup (REFUSES Adom-Workspace)+adom-desktop wsl_list                                      # {distros:[{name,state,version,default}]}+```++**systemd user session — `viaRoot`.** On a `systemd=true` distro, `-u <user>` can fail "Failed to start the systemd user session for '<user>'". Pass `"viaRoot": true` to `wsl_exec_async` — AD runs `-u root -- runuser -u <user> -- bash -l`, dropping to the user WITHOUT depending on `[email protected]`.++`wsl_import` / `wsl_export` / `wsl_unregister` are async (jobId + poll) too, so big imports/exports never EOF. All are **strictly scoped to the named distro** — there is no global `wsl --shutdown` path (that would kill the live HD workspace), and `wsl_unregister` refuses `Adom-Workspace`. Job ids live in AD's memory only (not persisted across an AD restart; the log file survives). The wedge defense above still applies — an over-cap spawn returns `wsl_wedged`.+ ## Detecting App Installation  After connecting, always run `adom-desktop status` to check what's installed. The `desktop.apps` object tells you exactly what the user has:

⋯ 1 unchanged line ⋯

@@ -1,6 +1,6 @@ {   "slug": "adom-desktop",-  "version": "1.8.160",+  "version": "1.8.161",   "type": "app",   "description": "Laptop bridge: file transfer, screenshots, notifications, KiCad + Fusion 360 control, real-Chrome (Puppeteer) automation, and Hydrogen Desktop proxy. One install gives Claude every desktop verb it needs.",   "keywords": [

@@ -1,6 +1,6 @@ {   "slug": "adom-desktop",-  "version": "1.8.160",+  "version": "1.8.161",   "type": "app",   "description": "Laptop bridge: file transfer, screenshots, notifications, KiCad + Fusion 360 control, real-Chrome (Puppeteer) automation, and Hydrogen Desktop proxy. One install gives Claude every desktop verb it needs.",   "keywords": [@@ -45,19 +45,11 @@     "skills/**",     "dist/**"   ],-  "visibility": {-    "public": true-  },+  "visibility": "public",   "org": "adom",   "tag": "latest",   "author": {     "name": "Kyle Bergstedt",     "email": "[email protected]"-  },-  "hero": {-    "type": "image",-    "path": "screenshots/hero.png"-  },-  "title": "Adom Desktop",-  "brief": "The laptop bridge for cloud AI — file transfer, screenshots, KiCad / Fusion 360 / real-Chrome automation, WSL bakes, and RDP tunnels, all driven by Claude."+  } }\ No newline at end of file

@@ -2240,6 +2240,29 @@ Every `wsl_exec` / `run_script bash` spawns a `wsl.exe` client. If WSL's service    It classifies each `wsl.exe`: childless + (0-CPU & old | runaway-CPU) → **candidate**; everything else → **spared**. It **spares any `wsl.exe` with child processes** (that's almost certainly the live distro, e.g. the HD `Adom-Workspace`), honors `sparePids`, and never touches `wslservice`/`wslhost`/`vmmem`. Review each candidate's `cmd` in the dry-run to confirm the live workspace isn't among them, then confirm. **Never** `wsl --shutdown` (it kills the live workspace too). Reaping childless orphans often cascades — their now-parentless children exit on their own (observed 114 → 18 from reaping 54). 3. **status wsl block** — `{wslProcessCount, wedged, _hint}` lets you see a pile-up *before* it blocks work. Path differs by transport: **`status.desktop.wsl`** via the CLI/relay (`adom-desktop status` — nested like `desktop.apps`), or top-level **`status.wsl`** on the local direct API (`GET /status`). `wedged:true` at/above `WSL_WARN_AT=50`. +#### Long-running in-distro work + distro lifecycle — golden-image bakes (v1.8.161+)++`wsl_exec` is **synchronous** — it waits for the command and is bounded by the relay's HTTP timeout (~60-120s), so a multi-minute bake (apt, a big download) EOFs. Backgrounding inside the distro (`nohup … &`) doesn't help either: the `wsl.exe` client returns, WSL sees no active session, shuts the distro down, and kills the bg process (wiping `/tmp`). For anything long, use the **async held-session** verbs — AD holds one `wsl.exe` in the foreground for the command's whole lifetime, so the distro stays up:++- **`wsl_exec_async`** → returns a `jobId` + `outputPath` (a live UTF-8 log) immediately; the command runs detached for as long as it takes.+- **`wsl_job_status {jobId}`** → `{running, exitCode, elapsedMs, outputTail, outputPath}`. Poll until `running:false`; `pull_file` the `outputPath` for the full log. (`wsl_job_list`, `wsl_job_kill {jobId}` round it out.)++```bash+# golden-image bake: import → run (async) → poll → export → unregister, all via AD+adom-desktop wsl_import '{"distro":"bake","installDir":"C:/Users/<you>/.adom/wsl/bake","tarball":"C:/.../base.tar"}'+#   → {jobId}; poll wsl_job_status until done (exitCode 0)+B64=$(printf 'set -euo pipefail\napt-get update && apt-get install -y build-essential\n' | base64 -w0)+adom-desktop wsl_exec_async "{\"distro\":\"bake\",\"user\":\"root\",\"scriptB64\":\"$B64\"}"+adom-desktop wsl_job_status '{"jobId":"wsljob-xxxxxxxx"}'   # repeat until running:false; outputTail = progress+adom-desktop wsl_export '{"distro":"bake","tarball":"C:/.../golden.tar"}'   # poll, then pull_file the tarball+adom-desktop wsl_unregister '{"distro":"bake"}'            # cleanup (REFUSES Adom-Workspace)+adom-desktop wsl_list                                      # {distros:[{name,state,version,default}]}+```++**systemd user session — `viaRoot`.** On a `systemd=true` distro, `-u <user>` can fail "Failed to start the systemd user session for '<user>'". Pass `"viaRoot": true` to `wsl_exec_async` — AD runs `-u root -- runuser -u <user> -- bash -l`, dropping to the user WITHOUT depending on `[email protected]`.++`wsl_import` / `wsl_export` / `wsl_unregister` are async (jobId + poll) too, so big imports/exports never EOF. All are **strictly scoped to the named distro** — there is no global `wsl --shutdown` path (that would kill the live HD workspace), and `wsl_unregister` refuses `Adom-Workspace`. Job ids live in AD's memory only (not persisted across an AD restart; the log file survives). The wedge defense above still applies — an over-cap spawn returns `wsl_wedged`.+ ## Detecting App Installation  After connecting, always run `adom-desktop status` to check what's installed. The `desktop.apps` object tells you exactly what the user has: