Skip to content

armgit / mso

Public Imported from GitHub
0

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.

fix(install): preserve portable host commits and validate WSL2

Rahmanaa7a6dffaab5
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 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 breadcrumbs
diff --git a/docs/PLATFORMS.md b/docs/PLATFORMS.md
index 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 or
arbitrary 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.md
index 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 capsules
JEV is now a versioned bounded decision plane rather than a Workflow-only adapter.
diff --git a/docs/TERMUX.md b/docs/TERMUX.md
index 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 ru
steps 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.
## Security
diff --git a/lib/platform-install-guides.ts b/lib/platform-install-guides.ts
index 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, PlatformInstallGuide
bestFor: "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, PlatformInstallGuide
troubleshooting: [
"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.ts
index 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.sh
index 59e6cf8c..497f7a92 100755
--- a/scripts/install-core.sh
+++ b/scripts/install-core.sh
@@ -426,6 +426,7 @@ if [ -d "$DIR/.git" ]; then
install_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 @@ else
install_git_noninteractive git clone --quiet --branch "$REF" "$REPO_URL" "$DIR" 2>/dev/null || install_git_noninteractive git clone --quiet "$REPO_URL" "$DIR"
fi
cd "$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.sh
index 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 ]; then
fi
info "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." ;;
+esac
command -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 --version
mso -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.ts
index 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.ts
index 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.ps1
index 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 pipefail
diff --git a/scripts/install.sh b/scripts/install.sh
index 2aeb6d17..6c3344e1 100755
--- a/scripts/install.sh
+++ b/scripts/install.sh
@@ -11,10 +11,10 @@ umask 077
RAW_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=''