Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.
TypeScript browser-shellcontrol-planefile-managerhomelabmobile-firstnextjsptyreactself-hostedserver-managementshadcn-uisysadmintailwindcssterminaltypescriptvpsweb-desktopweb-terminal
fix(install): prove stable-id service takeover
Rahman3a43bfbb2df8
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.mdindex 88176187..af0316f1 100644--- a/docs/CHANGELOG.md+++ b/docs/CHANGELOG.md@@ -8,6 +8,7 @@ this is the *what*, and it is what Settings → About shows as “What's new”.**Fixed**+- `install` prove stable-id service takeover- `install` keep security hint literal- `install` make WSL CLI setup reliable- `security` harden GitHub quality controlsdiff --git a/docs/PROGRESS.md b/docs/PROGRESS.mdindex ec50e3b1..937e12cd 100644--- a/docs/PROGRESS.md+++ b/docs/PROGRESS.md@@ -2,6 +2,41 @@Running log of what shipped each phase. Newest at top.+## 2026-08-30 — WSL installer reliability and recognized property fuzzing (SHIPPED)++A WSL install exposed two assumptions that were true on the production VPS but not on a fresh+Linux shell. The installer treated the presence of a `systemctl` executable as proof that systemd+was PID 1, and it did service setup before creating the CLI launchers. On WSL with systemd disabled,+`systemctl` therefore aborted the `set -e` installer before `mso` existed. Separately, `curl | bash`+can never modify the parent shell's PATH, so claiming `mso -h` was immediately available without+checking the invoking PATH was not a valid installation contract.++The installer now creates and validates the CLI before service setup, requires systemd to actually+be PID 1, persists `~/.local/bin` for future bash/zsh sessions, and uses a guarded launcher in an+already-reachable system bin directory when possible. It checks the original invoking PATH rather+than its child-process PATH and prints an exact fallback export when immediate discovery cannot be+proven. WSL without systemd remains a supported CLI-only shape; background service/onboarding waits+for a verified service. An isolated clean-HOME/PATH install proved the child installer returns to a+parent shell where `command -v mso` and `mso -h` succeed.++The service readiness gate was also corrected for explicit `NEXT_DEPLOYMENT_ID`. Build ID change is+still the preferred takeover proof, but a deliberately stable deployment ID can no longer make a+healthy restart look stale: the installer records the pre-restart systemd MainPID and accepts a+healthy response from a changed live MainPID as the fallback proof. This keeps the old-process/stale-+chunk defense without assuming every deployment changes its public build ID.++OpenSSF's remaining Fuzzing posture gap is addressed with real TypeScript property testing rather+than a dismissed alert. `fast-check` now generates adversarial cases for filesystem containment,+private-provider SSRF rejection, and PKCE exactness; the package/import form is one that Scorecard's+Fuzzing check recognizes. Code Review and CII Best Practices remain external governance evidence:+they require genuine independent review and OpenSSF badge enrollment rather than repository-side+alert suppression.++Verification: installer Bash syntax + hosted ShellCheck, installer contract tests, hundreds of+property-generated security cases, full TypeScript/lint/test gates, docs/changelog parity, dependency+audit, isolated production build, an isolated clean-HOME/PATH install, and protected-branch hosted+CodeQL/dependency/Gitleaks/Trivy/OSV/Semgrep checks.+> **How to read this log:** it is the source of truth for **why/when work shipped**, not> today's API/runbook. Phases 0–14 were built on **Convex self-hosted + a Control-Room> host-agent bridge**; that stack was removed in Phase 15 and later entries describe thediff --git a/lib/install-contract.test.ts b/lib/install-contract.test.tsindex 4d49fed3..0c7192c2 100644--- a/lib/install-contract.test.ts+++ b/lib/install-contract.test.ts@@ -40,6 +40,8 @@ describe("one-line installer contract", () => {expect(src).toContain('= "systemd"');expect(src).toContain("WSL detected without systemd as PID 1");expect(src).toContain("SERVICE_READY=1");+ expect(src).toContain('systemctl show "$SERVICE" -p MainPID --value');+ expect(src).toContain('[ "$now_pid" -gt 0 ] && [ "$now_pid" != "$prev_pid" ]');expect(src).toContain('[ "$RUN_ONBOARD" -eq 1 ] && [ "$SERVICE_READY" -eq 1 ]');});diff --git a/scripts/install.sh b/scripts/install.shindex 1b93dded..7a39b4c2 100755--- a/scripts/install.sh+++ b/scripts/install.sh@@ -435,11 +435,14 @@ EOFHEALTH_HOST="$BIND"case "$BIND" in 0.0.0.0|::|"") HEALTH_HOST=127.0.0.1 ;; esac- # Read the id of the build that is CURRENTLY answering, before we touch the- # unit. Every build gets a fresh NEXT_PUBLIC_BUILD_ID (next.config.mjs), so a- # changed id is what proves the new process took over.+ # Record BOTH the build id and service PID that are CURRENTLY answering before+ # the restart. Normally next.config.mjs mints a fresh build id, but an explicit+ # NEXT_DEPLOYMENT_ID intentionally makes that id stable across deploys. In that+ # supported mode, a changed MainPID plus a healthy response proves takeover.prev_build="$(curl -fsS --max-time 3 "http://$HEALTH_HOST:$PORT/api/health" 2>/dev/null \| sed -n 's/.*"buildId":"\([^"]*\)".*/\1/p' || true)"+ prev_pid="$(systemctl show "$SERVICE" -p MainPID --value 2>/dev/null || true)"+ case "$prev_pid" in ''|*[!0-9]*) prev_pid=0 ;; esac# Makes /run/user/<uid> — where the user bus lives — exist without a login# session and survive logout. The XDG_RUNTIME_DIR above names that directory, so@@ -474,11 +477,18 @@ EOFbody="$(curl -fsS --max-time 3 "http://$HEALTH_HOST:$PORT/api/health" 2>/dev/null || true)"if [ -n "$body" ]; thennow_build="$(printf '%s' "$body" | sed -n 's/.*"buildId":"\([^"]*\)".*/\1/p')"- # Gate on the id, not on curl's exit status: the old process answers- # /api/health perfectly while serving stale chunks, which is exactly how- # a failed update used to report "health OK".- if [ -z "$prev_build" ] || [ "$now_build" != "$prev_build" ]; then- up=1; SERVICE_READY=1; ok "health OK (build ${now_build:-unknown})"; break+ # Do not trust curl alone: the OLD process can answer /api/health while+ # serving stale chunks. Prefer a changed build id; when a configured+ # deployment id keeps it stable, require systemd to report a different+ # live MainPID. Fresh installs have no previous healthy build and pass.+ now_pid="$(systemctl show "$SERVICE" -p MainPID --value 2>/dev/null || true)"+ case "$now_pid" in ''|*[!0-9]*) now_pid=0 ;; esac+ if [ -z "$prev_build" ] \+ || [ "$now_build" != "$prev_build" ] \+ || { [ "$now_pid" -gt 0 ] && [ "$now_pid" != "$prev_pid" ]; }; then+ up=1; SERVICE_READY=1+ ok "health OK (build ${now_build:-unknown}, pid ${now_pid:-unknown})"+ breakfifisleep 2@@ -486,7 +496,7 @@ EOFif [ "$up" -ne 1 ]; then# is-active needs no privileges — do not spend a sudo prompt on the sad path.if systemctl is-active --quiet "$SERVICE"; then- warn "service is running but still serving build $prev_build — check: journalctl -u mso -e"+ warn "service is running but build/process identity did not change (build $prev_build, pid $prev_pid) — check: journalctl -u mso -e"elsewarn "$SERVICE is not running — check: journalctl -u mso -e"fi