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): preserve portable host commits and validate WSL2
Rahmanaa7a6dffaab5
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.mdindex efce35fb..17ebde21 100644--- a/docs/CHANGELOG.md+++ b/docs/CHANGELOG.md@@ -13,6 +13,7 @@ this is the *what*, and it is what Settings → Account → About shows as “Wh**Fixed**+- `install` preserve portable host commits and validate WSL2- `jev` validate decision release contract- `jev` open responsive session details in release journey- `settings` align MCP release journey with breadcrumbsdiff --git a/docs/PLATFORMS.md b/docs/PLATFORMS.mdindex 9e5f46fc..d9063581 100644--- a/docs/PLATFORMS.md+++ b/docs/PLATFORMS.md@@ -66,7 +66,10 @@ iwr -useb https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install-The bootstrap installs or reuses WSL2 Ubuntu and runs the canonical Linux installer inside it.A first-time WSL setup can require a Windows reboot or first-launch Linux user creation; rerun the-same MSO command afterward.+same MSO command afterward. The installer verifies the chosen distro is WSL2 before invoking the+Linux installer. It reuses Ubuntu when present, otherwise a sole existing distro; for several+non-Ubuntu distros, set `MSO_WSL_DISTRO` explicitly. An existing WSL1 distro is never converted+without the operator running `wsl --set-version <distro> 2` deliberately.The MSO host tools manage the **WSL2 Linux distro**, not Windows Service Control Manager orarbitrary Win32 processes.@@ -80,8 +83,12 @@ curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install~~~The Android adapter creates or reuses Ubuntu PRoot and exposes a Termux-side `mso` launcher.-No Android root access is required. Because Android may suspend background processes, this is best-for local/personal use; an always-on Linux host is still the stronger production target.+MSO **runs and hosts work on that Android device**, including a tablet; a separate VPS is optional.+No Android root access is required. Use `mso web` for a local browser workspace, and verify+access from a second device through a protected private/HTTPS route. Raw MSO binds to loopback+by default; a plain HTTP LAN-IP login is not a valid substitute for trusted HTTPS. Android can+suspend background processes, so a tablet remains a personal/conditional host until actual+background, reboot, power, network and recovery tests pass.See [TERMUX.md](./TERMUX.md) for repair and PRoot details.diff --git a/docs/PROGRESS.md b/docs/PROGRESS.mdindex 13f7bb74..1ccc44de 100644--- a/docs/PROGRESS.md+++ b/docs/PROGRESS.md@@ -1,3 +1,23 @@+## 2026-09-27 — Portable host installer safety++An Android tablet with supported arm64/x86_64 architecture can host the MSO Linux+runtime inside Termux/Ubuntu PRoot; the tablet does not require a second VPS.+The adapter now rejects unsupported CPU architectures before package downloads.+On rerun, the canonical core installer rejects a checkout whose current commit+is not an ancestor of the fetched target. The Termux adapter only reattaches+`main` when its old tip is an ancestor of the installed tip, avoiding the old+forced branch reset over local commits. Both installer digest pins advance with+the changed payloads. The Windows bootstrap now verifies the chosen distro is+WSL2 before installing; when several distros exist without Ubuntu it asks for+an explicit choice instead of taking the first list entry.++Focused installer/platform/docs tests passed 39/39 plus TypeScript and shell syntax+checks in an isolated worktree. A physical Android tablet and Windows/WSL2 host+still need fresh-install, process-background, remote-access, update and recovery+acceptance before those platforms can be claimed verified. This increment does+not implement the managed app manifest, domain/IP provisioning or multi-host+registry from the broader agnostic audit.+## 2026-09-27 — JEV decision plane and value capsulesJEV is now a versioned bounded decision plane rather than a Workflow-only adapter.diff --git a/docs/TERMUX.md b/docs/TERMUX.mdindex 13f97492..1ab43f1c 100644--- a/docs/TERMUX.md+++ b/docs/TERMUX.md@@ -22,6 +22,7 @@ If a partial Termux package upgrade has broken `curl` before that command can rusteps below first.The Termux bootstrap is idempotent. Re-running the same command repairs/upgrades the host packages, reuses the `mso-ubuntu` PRoot environment when it already exists, and runs the normal MSO installer again to update the existing checkout.+Before package downloads, it rejects unsupported CPU architectures (Linux Bun requires arm64 or x86_64). On an existing checkout, it refuses to replace local commits absent from the requested ref, and will not force-move `main` over unique commits; preserve/reconcile those commits first.The script deliberately does **not** enable YOLO mode.@@ -112,7 +113,7 @@ This Android installation is optimized for MSO CLI and local browser workspace u- long-running Android processes are still subject to Android background/battery policies;- performance is lower than a native Linux host because PRoot translates filesystem/syscall paths in userspace.-For always-on production hosting, install MSO on a normal Linux VPS and use Termux as the client/operator terminal instead.+An Android tablet can be the MSO host: MSO, its data, and compatible applications run inside its Ubuntu PRoot guest. Start `mso web` on the tablet, confirm `mso doctor` and local health, then test protected access from a second device through a private network or HTTPS tunnel. The default loopback bind is intentional: plain HTTP on the tablet's LAN IP is not a supported login path. Keep the foreground process alive, and test backgrounding, battery policy, reboot, update, storage pressure and network changes on the actual tablet before treating it as an always-on server. A separate VPS is optional; an always-on Linux host remains the better choice when the tablet fails those acceptance tests.## Securitydiff --git a/lib/platform-install-guides.ts b/lib/platform-install-guides.tsindex d9ab5f63..10776765 100644--- a/lib/platform-install-guides.ts+++ b/lib/platform-install-guides.ts@@ -94,13 +94,13 @@ export const PLATFORM_INSTALL_GUIDES: Record<MsoPlatformId, PlatformInstallGuidebestFor: "Windows 10/11 users who want the full MSO host runtime without maintaining a separate VPS.",prerequisites: ["Windows 10 version 2004+ or Windows 11 for the modern WSL install flow.",- "WSL2 is the stable MSO host path; the bootstrap reuses a normal existing distro when possible and ignores docker-desktop distros.",+ "WSL2 is the stable MSO host path; the bootstrap verifies the chosen distro is version 2 and ignores docker-desktop distros.","Use PowerShell. Administrator elevation is needed when Windows itself still needs WSL installed.","MSO manages the Linux distro inside WSL2, not Windows Service Control Manager or arbitrary Win32 processes.",],steps: [{ title: "Open PowerShell", body: "If WSL is already installed, a normal PowerShell window is enough. If this is the first WSL setup, reopen PowerShell as Administrator." },- { title: "Run the Windows bootstrap", body: "It finds an existing Linux distro or installs Ubuntu, then runs the canonical MSO Linux installer inside WSL2.", command: WINDOWS_INSTALL },+ { title: "Run the Windows bootstrap", body: "It chooses Ubuntu if installed, reuses a sole other distro, or asks you to select among several; it verifies WSL2 before running the Linux installer.", command: WINDOWS_INSTALL },{ title: "Complete first-time WSL setup when prompted", body: "If the command installed WSL/Ubuntu, restart Windows when requested, launch the distro once, create the Linux username/password, then rerun the same MSO PowerShell command.", command: "wsl --status\nwsl -l -v" },{ title: "Enter WSL and verify MSO", body: "Use the distro shell for direct diagnostics.", command: "wsl\nexport PATH=\"$HOME/.local/bin:$HOME/.bun/bin:$PATH\"\nmso --version\nmso doctor" },{ title: "Start/open the workspace", body: "Run from WSL. WSL2 normally forwards Linux localhost services to Windows localhost.", command: "mso web", note: "Open http://localhost:4005 in Edge/Chrome when it does not open automatically." },@@ -109,6 +109,7 @@ export const PLATFORM_INSTALL_GUIDES: Record<MsoPlatformId, PlatformInstallGuidetroubleshooting: ["If wsl.exe is missing, follow Microsoft's WSL installation guide and rerun the MSO bootstrap after the required reboot.","If no distro appears in wsl -l -v, install one with wsl --install -d Ubuntu, complete first launch, then rerun MSO.",+ "If the chosen distro is WSL1, explicitly convert it with wsl --set-version <distro> 2, then rerun MSO; if several distros exist, set MSO_WSL_DISTRO first.","If Windows cannot reach port 4005, verify mso web is running inside WSL and review Microsoft's localhost-forwarding documentation.",],links: [diff --git a/lib/platform-support.test.ts b/lib/platform-support.test.tsindex 2982e44b..dffb4ef3 100644--- a/lib/platform-support.test.ts+++ b/lib/platform-support.test.ts@@ -113,6 +113,19 @@ describe("MSO platform support contract", () => {expect(WINDOWS_INSTALLER).toContain('Where-Object { $_ -and ($_ -notlike "docker-desktop*") }');});+ it("refuses WSL1 and ambiguous distro choices before running the guest installer", () => {+ expect(WINDOWS_INSTALLER).toContain("wsl.exe --list --verbose");+ expect(WINDOWS_INSTALLER).toContain('if ($Version -ne "2")');+ expect(WINDOWS_INSTALLER).toContain('elseif ($Distros.Count -eq 1)');+ expect(WINDOWS_INSTALLER).toContain("Multiple WSL distros are installed");+ expect(WINDOWS_INSTALLER).toContain("wsl --set-version $Distro 2");+ expect(WINDOWS_INSTALLER).toContain(String.raw`"^\*?\s*"`);+ expect(WINDOWS_INSTALLER).not.toContain(String.raw`"^\\*?\\s*"`);+ expect(WINDOWS_INSTALLER.indexOf('if ($Version -ne "2")')).toBeLessThan(+ WINDOWS_INSTALLER.indexOf("Installing/updating MSO inside WSL2"),+ );+ });+it("prevents Termux recursion inside the Ubuntu guest", () => {expect(TERMUX_INSTALLER).toContain('proot-distro login "$DISTRO" --user "$GUEST_USER" -- /usr/bin/env -i');expect(TERMUX_INSTALLER).not.toMatch(/\/bin\/bash -lc(?:\s|['"])/);diff --git a/scripts/install-core.sh b/scripts/install-core.shindex 59e6cf8c..497f7a92 100755--- a/scripts/install-core.sh+++ b/scripts/install-core.sh@@ -426,6 +426,7 @@ if [ -d "$DIR/.git" ]; theninstall_git_noninteractive git -C "$DIR" fetch --quiet origin "$REF" || die "could not fetch origin $REF non-interactively; canonical MSO uses public HTTPS, custom/private origins need preconfigured credentials"target_commit="$(git -C "$DIR" rev-parse --short FETCH_HEAD)" || die "could not resolve fetched ref $REF"info "target commit: $target_commit"+ git -C "$DIR" merge-base --is-ancestor HEAD FETCH_HEAD || die "checkout has commits not present in the requested ref; preserve/reconcile them before updating $DIR"git -C "$DIR" checkout --quiet FETCH_HEAD || die "could not check out $target_commit"ok "updated checkout $old_commit → $(git -C "$DIR" rev-parse --short HEAD)"else@@ -434,7 +435,6 @@ elseinstall_git_noninteractive git clone --quiet --branch "$REF" "$REPO_URL" "$DIR" 2>/dev/null || install_git_noninteractive git clone --quiet "$REPO_URL" "$DIR"ficd "$DIR"-# ---- post-checkout phases ----# Fresh installs have the requested checkout now, so the rest of the installer is# split into bounded repo-owned phases without adding bootstrap downloads.diff --git a/scripts/install-termux.sh b/scripts/install-termux.shindex 9b0b5802..2f6206ce 100755--- a/scripts/install-termux.sh+++ b/scripts/install-termux.sh@@ -7,7 +7,7 @@ DISTRO="${MSO_TERMUX_DISTRO:-mso-ubuntu}"GUEST_USER="${MSO_TERMUX_USER:-mso}"IMAGE="${MSO_TERMUX_IMAGE:-ubuntu:24.04}"GUEST_INSTALL_URL_DEFAULT="https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install-core.sh"-GUEST_INSTALL_SHA256_DEFAULT="794d8893285c045a8ab608d8c1d2803188b4a2a13058695d6c1fd54520973b65"+GUEST_INSTALL_SHA256_DEFAULT="d56a6ed0f1330e53d18d796caf272ac47a1b1abc0ee86c92b4eff5cd2a5bb206"INSTALL_URL="${MSO_TERMUX_INSTALL_URL:-$GUEST_INSTALL_URL_DEFAULT}"INSTALL_SHA256="${MSO_TERMUX_INSTALL_SHA256:-$GUEST_INSTALL_SHA256_DEFAULT}"GUEST_REF="${MSO_TERMUX_REF:-main}"@@ -45,6 +45,10 @@ if [ "${MSO_TERMUX_NO_TEE:-0}" != 1 ]; thenfiinfo "persistent install log: $INSTALL_LOG"info "Android-safe build limits: workers=$BUILD_CPUS node-heap=${NODE_HEAP_MB}MiB"+case "$(uname -m)" in+ aarch64|x86_64) ;;+ *) fail "This Android CPU architecture has no supported Linux Bun runtime; MSO needs arm64 or x86_64." ;;+esaccommand -v apt >/dev/null 2>&1 || fail 'Termux apt is missing.'info 'repairing/updating Termux packages'@@ -138,9 +142,24 @@ proot-distro login "$DISTRO" --user "$GUEST_USER" -- /usr/bin/env -i \mso --versionmso -h >/dev/null- # Normal installs must end attached to main so future `mso update` calls work.+ # Reattach main only when its previous tip is reachable from the installed tip.+ # A detached checkout may carry a different main branch with unique work.+ reconcile_main_branch() {+ local repo="$1"+ [ "$(git -C "$repo" symbolic-ref --quiet --short HEAD || true)" != main ] || return 0+ if git -C "$repo" show-ref --verify --quiet refs/heads/main; then+ git -C "$repo" merge-base --is-ancestor refs/heads/main HEAD || {+ echo "Local main has commits absent from the installed ref; preserve/reconcile them before switching." >&2+ return 1+ }+ git -C "$repo" branch -f main HEAD >/dev/null+ else+ git -C "$repo" branch main HEAD >/dev/null+ fi+ git -C "$repo" switch --quiet main+ }if [ "$MSO_REF" = main ] && [ -d "$HOME/mso/.git" ]; then- git -C "$HOME/mso" switch -C main origin/main >/dev/null+ reconcile_main_branch "$HOME/mso"fi' bash "$INSTALL_URL" "$INSTALL_SHA256"diff --git a/scripts/install-termux.test.ts b/scripts/install-termux.test.tsindex 1c58a642..44edd2c7 100644--- a/scripts/install-termux.test.ts+++ b/scripts/install-termux.test.ts@@ -61,6 +61,18 @@ describe("Termux PRoot Linux environment boundary", () => {const result = spawnSync("/bin/bash", ["-n", installer], { encoding: "utf8" });expect(result.status, result.stderr).toBe(0);});+ it("rejects unsupported CPU architectures before touching Termux packages", () => {+ const f = fixture();+ const script = `uname() { printf 'armv7l\\n'; }+apt() { echo APT_SHOULD_NOT_RUN; }+source ${quote(installer)}`;+ const result = spawnSync("/bin/bash", ["--noprofile", "--norc", "-c", script], {+ env: f.env, encoding: "utf8", timeout: 10000,+ });+ expect(result.status).not.toBe(0);+ expect(result.stderr).toContain("needs arm64 or x86_64");+ expect(result.stdout).not.toContain("APT_SHOULD_NOT_RUN");+ });it("clears Android PATH, Node/Bun configuration, loader flags and shell startup hooks before either guest shell", () => {const f = fixture();for (const name of ["root", "owner"]) {diff --git a/scripts/install-update-lock-contract.test.ts b/scripts/install-update-lock-contract.test.tsindex c3f8d381..42686e58 100644--- a/scripts/install-update-lock-contract.test.ts+++ b/scripts/install-update-lock-contract.test.ts@@ -1,4 +1,6 @@import fs from "node:fs";+import os from "node:os";+import { spawnSync } from "node:child_process";import path from "node:path";import { describe, expect, it } from "vitest";@@ -27,4 +29,66 @@ describe("installer update transaction ordering", () => {expect(core).toContain("install_private_state_ensure_file()");});+ it("preserves unique commits on both the installer checkout and the Termux main branch", () => {+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), "mso-install-git-"));+ const git = (...args: string[]) => {+ const p = spawnSync("git", args, { cwd: dir, encoding: "utf8" });+ expect(p.status, p.stderr).toBe(0);+ return p.stdout.trim();+ };+ const run = (definition: string, call: string) =>+ spawnSync("bash", ["-c", `die() { echo "$*" >&2; exit 1; }+${definition}+${call}`, "bash", dir], { encoding: "utf8" });+ try {+ git("init", "-q", "-b", "main");+ git("config", "user.email", "[email protected]");+ git("config", "user.name", "Install Test");+ fs.writeFileSync(path.join(dir, "state.txt"), "base\n");+ git("add", "state.txt"); git("commit", "-qm", "base");+ const base = git("rev-parse", "HEAD");++ git("checkout", "--detach", "-q", base);+ fs.writeFileSync(path.join(dir, "state.txt"), "target\n");+ git("commit", "-qam", "target");+ const target = git("rev-parse", "HEAD");+ git("checkout", "-q", "main");+ fs.writeFileSync(path.join(dir, "state.txt"), "local only\n");+ git("commit", "-qam", "local only");+ const local = git("rev-parse", "HEAD");+ git("fetch", "-q", ".", target);++ const core = fs.readFileSync(path.join(ROOT, "scripts/install-core.sh"), "utf8");+ const coreGuard = core.split("\n").find((line) => line.includes('git -C "$DIR" merge-base --is-ancestor HEAD FETCH_HEAD || die'));+ expect(coreGuard).toBeDefined();+ const refused = run("", `DIR="$1"; ${coreGuard}`);+ expect(refused.status).not.toBe(0);+ expect(refused.stderr).toContain("commits not present");+ expect(git("rev-parse", "main")).toBe(local);+ git("checkout", "--detach", "-q", base);+ const accepted = run("", `DIR="$1"; ${coreGuard}`);+ expect(accepted.status, accepted.stderr).toBe(0);++ const termux = fs.readFileSync(path.join(ROOT, "scripts/install-termux.sh"), "utf8");+ const branchGuard = termux.match(/ reconcile_main_branch\(\) \{[\s\S]*?\n \}/)?.[0];+ expect(branchGuard).toBeDefined();+ const rejectedBranch = run(branchGuard!, 'reconcile_main_branch "$1"');+ expect(rejectedBranch.status).not.toBe(0);+ expect(rejectedBranch.stderr).toContain("Local main has commits");+ expect(git("rev-parse", "main")).toBe(local);+ expect(git("rev-parse", "HEAD")).toBe(base);++ git("checkout", "--detach", "-q", local);+ fs.writeFileSync(path.join(dir, "state.txt"), "descendant\n");+ git("commit", "-qam", "descendant");+ const descendant = git("rev-parse", "HEAD");+ const switched = run(branchGuard!, 'reconcile_main_branch "$1"');+ expect(switched.status, switched.stderr).toBe(0);+ expect(git("symbolic-ref", "--short", "HEAD")).toBe("main");+ expect(git("rev-parse", "main")).toBe(descendant);+ } finally {+ fs.rmSync(dir, { recursive: true, force: true });+ }+ });+});diff --git a/scripts/install-windows.ps1 b/scripts/install-windows.ps1index baa6645e..485213c5 100644--- a/scripts/install-windows.ps1+++ b/scripts/install-windows.ps1@@ -34,10 +34,14 @@ $Distros = @($Distro = if ($RequestedDistro) {$RequestedDistro-} elseif ($Distros.Count -gt 0) {+} elseif ($Distros -contains "Ubuntu") {+ "Ubuntu"+} elseif ($Distros.Count -eq 1) {$Distros[0]-} else {+} elseif ($Distros.Count -eq 0) {"Ubuntu"+} else {+ Fail "Multiple WSL distros are installed. Set MSO_WSL_DISTRO to the one that should host MSO, then rerun."}if ($Distros -notcontains $Distro) {@@ -52,6 +56,22 @@ if ($Distros -notcontains $Distro) {exit 0}+# WSL1 has a different kernel/process contract; refuse before invoking the Linux installer.+$WslDetails = & wsl.exe --list --verbose 2>$null+if ($LASTEXITCODE -ne 0) {+ Fail "Could not verify WSL2 distro version. Run wsl --list --verbose and rerun the installer."+}+$EscapedDistro = [regex]::Escape($Distro)+$VersionLine = @($WslDetails | ForEach-Object { $_.Trim([char]0).Trim() } |+ Where-Object { $_ -match ("^\*?\s*" + $EscapedDistro + "\s+.+\s+[12]\s*$") })+if ($VersionLine.Count -ne 1) {+ Fail "Could not determine the WSL version for $Distro. Run wsl --list --verbose and select a WSL2 distro explicitly."+}+$Version = [regex]::Match($VersionLine[0], "([12])\s*$").Groups[1].Value+if ($Version -ne "2") {+ Fail "$Distro is WSL1. Convert it explicitly with: wsl --set-version $Distro 2 ; then rerun this installer."+}+Info "Installing/updating MSO inside WSL2 ($Distro)"$Script = @'set -Eeuo pipefaildiff --git a/scripts/install.sh b/scripts/install.shindex 2aeb6d17..6c3344e1 100755--- a/scripts/install.sh+++ b/scripts/install.sh@@ -11,10 +11,10 @@ umask 077RAW_BASE="${MSO_INSTALL_RAW_BASE:-https://raw.githubusercontent.com/rahmanef63/mso/main/scripts}"CORE_URL="${MSO_INSTALL_CORE_URL:-https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install-core.sh}"-CORE_SHA256="794d8893285c045a8ab608d8c1d2803188b4a2a13058695d6c1fd54520973b65"+CORE_SHA256="d56a6ed0f1330e53d18d796caf272ac47a1b1abc0ee86c92b4eff5cd2a5bb206"CORE_EOF='# MSO_INSTALLER_CORE_EOF'MACOS_SHA256="668ec3c8bbf3ee36dc2ae70952c3ba43c6f73ebc3acd6956fa4be2f65a076bfe"-TERMUX_SHA256="ade7528826e50b17d2f288cbc763272441242bb3ab548ad5dcf9ef2c1be01644"+TERMUX_SHA256="12a979b6ef9a8dc62253e059e612cd1f6201014b7a4c20f5a6dc3d46d0436f10"TMP_INSTALLER=''TMP_PLATFORM=''