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(cli): clarify version and update labels

Rahman80f59ce1f05d
diff --git a/README.md b/README.md
index 9e69eee7..8a0c9da9 100644
--- a/README.md
+++ b/README.md
@@ -38,6 +38,8 @@
MSO is **Public Alpha / Developer Preview** software. It runs on top of Linux as a normal non-root Node process. It is not an operating system, Linux distribution, desktop environment, VPS provider, or production-grade security platform.
+**Version labels:** the badge and Settings → About show the MSO **app/package version**. The shell has a separately versioned **CLI contract** because older installs may receive CLI/update compatibility changes without an app-semver bump. `mso --version` labels both plus the Git build; `mso update status` uses the Git build as release authority, so commit-only updates never appear as a misleading same-version arrow.
+
For a real deployment, put MSO behind **Tailscale, a VPN, or a TLS reverse proxy with tight access control**. Do not expose the raw app port to the public internet.
**Security assurance:** MSO publishes its [security policy](./SECURITY.md) and [repeatable assurance process](./docs/SECURITY-ASSURANCE.md), with CodeQL, independent SAST/dependency/secret scanners, OpenSSF Scorecard, SBOM generation, passive OWASP ZAP checks, and MSO-specific security regression tests. The evidence is intentionally presented as testing—not as a security certification.
diff --git a/bin/mso b/bin/mso
index e511af2f..d9a7040e 100755
--- a/bin/mso
+++ b/bin/mso
@@ -704,7 +704,11 @@ fi
cmd="${1:-agent}"; maybe_update_notice "$cmd"; shift || true
case "$cmd" in
- version|--version|-V|-v) echo "mso $VERSION (base $B, root $ROOT)"; exit 0 ;;
+ version|--version|-V|-v)
+ app_version="$(jq -r '.version // "unknown"' "$ROOT/package.json" 2>/dev/null || printf unknown)"
+ build_sha="$(git -C "$ROOT" rev-parse --short HEAD 2>/dev/null || printf unknown)"
+ echo "mso CLI $VERSION · app $app_version · build $build_sha (base $B, root $ROOT)"
+ exit 0 ;;
# ── files ────────────────────────────────────────────────────────────────
ls) jget "/api/v1/fs/list?path=$(enc "${1:-~}")" ;;
diff --git a/bin/mso.test.ts b/bin/mso.test.ts
index b5f06170..9a61f747 100644
--- a/bin/mso.test.ts
+++ b/bin/mso.test.ts
@@ -11,6 +11,11 @@ const run = (...args: string[]) =>
execFileSync(CLI, args, { encoding: "utf8", env: { ...process.env, MSO_ENV: "/dev/null" } });
describe("bin/mso", () => {
+ it("labels CLI, app, and build versions instead of presenting one ambiguous number", () => {
+ const out = run("--version");
+ expect(out).toMatch(/^mso CLI \d+\.\d+\.\d+ · app \d+\.\d+\.\d+ · build [0-9a-f]+/);
+ });
+
it("prints help without logging in", () => {
const out = run("-h");
expect(out).toContain("Manef Shell OS");
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index c15261a2..f73b50fc 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -17,6 +17,7 @@ this is the *what*, and it is what Settings → About shows as “What's new”.
**Fixed**
+- `cli` clarify version and update labels
- `agent` stabilize terminal banner navigation
- `cli` make updates visible and idempotent
- `mcp` preserve app-only workflow status schema
diff --git a/docs/INSTALL.md b/docs/INSTALL.md
index f7c98e5d..ade8f51e 100644
--- a/docs/INSTALL.md
+++ b/docs/INSTALL.md
@@ -495,11 +495,13 @@ no API-key storage. Do not toggle demo mode in the production owner checkout.
Use Settings → About or:
```bash
-mso update status # fetch + show incoming CLI version/commits
+mso update status # fetch + show incoming commits and labeled CLI/build identity
mso update # preferred: update safely even if :4005 is down
mso update log
```
+MSO has two explicitly labeled version domains: the app/package version shown in Settings → About and the independently versioned CLI contract shown by `mso --version`. The Git commit/build remains update authority. If commits changed without a CLI bump, status says `N new commits on mso CLI X` rather than rendering `X -> X`.
+
The updater verifies the incoming checkout/build before replacing the service. Re-running the installer on an existing checkout acquires the same checkout-scoped transaction lock **before** Git fetch/checkout mutation and hands that open lock FD to the post-checkout runtime lifecycle, so installer, `mso update`, and `mso deploy` cannot mutate one checkout concurrently. The lock primitive is carried by the verified installer payload itself, so older MSO checkouts that predate the current private-state helper remain upgradeable in place. A normal `mso update` treats fetched `origin/main` as the release authority: after any fast-forward, local `main` must equal that remote commit exactly. A clean branch that is locally ahead or diverged is refused before dependency/build mutation instead of deploying unpushed code. `mso update status` reports that state explicitly. `mso update --rebuild` is different by design: it rebuilds the already-selected clean checkout without changing Git history. With an active
`mso.service` it first canonicalizes the unit's `WorkingDirectory` and requires it to equal the checkout
that invoked `mso update`; a secondary clone is never allowed to restart an unrelated live service.
diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md
index ce53383c..d36ac0f7 100644
--- a/docs/PROGRESS.md
+++ b/docs/PROGRESS.md
@@ -2,6 +2,19 @@
Running log of what shipped each phase. Newest at top.
+## 2026-09-01 — Version identity and update messaging DX — SHIPPED
+
+MSO's two legitimate version domains are now explicit instead of looking like drift. The app/package
+version remains the runtime/service compatibility identity used by health/readiness and Settings → About;
+the CLI keeps its independently versioned interaction contract. `mso --version` labels **CLI**, **app**
+and the exact Git **build**, About says **App version**, and README/install docs explain why those values
+can differ. Git commit identity remains the release/update authority.
+
+`mso update status` and its interactive background notice also distinguish a CLI-version change from a
+commit-only release. A commit-only update now says `N new commits on mso CLI X` instead of the confusing
+`X -> X`; a true CLI bump still shows an explicit `mso CLI X -> Y`. Up-to-date status labels both CLI and
+build identity. Regression tests cover version-change, commit-only, active-service build matching and CLI
+version output so the ambiguity cannot silently return.
## 2026-09-01 — Terminal banner geometry + stable slash navigation — SHIPPED
MSO Agent now uses the compact canonical folder + `MSO` ASCII geometry from the terminal logger instead of the oversized 12-row title. The seven title rows render as a cool blue → cyan → teal/emerald gradient with no purple. The slash palette also reserves its physical terminal rows only when it opens or grows; subsequent `↑/↓` selection redraws use ANSI cursor movement only, and the input prompt no longer embeds a leading newline that would be replayed on every redraw. A real PTY regression verifies both arrow directions emit zero LF/CRLF while still moving selection, so terminal scrollback stays stable. CLI patch version: **1.5.4**.
diff --git a/frontend/slices/os-settings/components/about-section.tsx b/frontend/slices/os-settings/components/about-section.tsx
index 1ad9f73e..fa9d038c 100644
--- a/frontend/slices/os-settings/components/about-section.tsx
+++ b/frontend/slices/os-settings/components/about-section.tsx
@@ -59,7 +59,7 @@ export function AboutSection() {
const rows: [string, string][] = [
["Status", "Public Alpha"],
- ["Version", pkg.version ?? "0.0.0"],
+ ["App version", pkg.version ?? "0.0.0"],
["Build ID", process.env.NEXT_PUBLIC_BUILD_ID || "dev"],
["Commit", process.env.NEXT_PUBLIC_COMMIT_SHA || "not set"],
["Runtime mode", IS_DEMO ? "Demo — mock data only" : "Live-capable"],
diff --git a/scripts/mso-update b/scripts/mso-update
index c719993a..8ada6050 100755
--- a/scripts/mso-update
+++ b/scripts/mso-update
@@ -72,7 +72,11 @@ print_status() {
return
fi
if [ "$n" -gt 0 ]; then
- printf 'update available: mso %s -> %s (%s commit%s)\n' "${local_v:-unknown}" "${remote_v:-newer}" "$n" "$([ "$n" = 1 ] || printf s)"
+ if [ -n "$local_v" ] && [ "$local_v" = "$remote_v" ]; then
+ printf 'update available: %s new commit%s on mso CLI %s\n' "$n" "$([ "$n" = 1 ] || printf s)" "$local_v"
+ else
+ printf 'update available: mso CLI %s -> %s (%s commit%s)\n' "${local_v:-unknown}" "${remote_v:-newer}" "$n" "$([ "$n" = 1 ] || printf s)"
+ fi
git -C "$ROOT" log --format=' %h %s' -5 HEAD..origin/main
printf 'run: mso update\n'
return
@@ -87,7 +91,7 @@ print_status() {
elif [[ "$head" != "$running_sha"* ]]; then
printf 'source is current at %s, but mso.service is still running %s. deployment verification/rebuild is pending. run: mso update --rebuild\n' "$head_short" "$running_sha"
else
- printf 'mso %s is up to date (%s)\n' "${local_v:-unknown}" "$head_short"
+ printf 'mso is up to date (CLI %s, build %s)\n' "${local_v:-unknown}" "$head_short"
fi
return
fi
@@ -96,7 +100,7 @@ print_status() {
if [ "$receipt" != "$head" ] || update_gateway_restore_pending; then
printf 'source is current at %s, but offline deployment verification/restart is pending. run: mso update\n' "${head:0:7}"
else
- printf 'mso %s is up to date (%s)\n' "${local_v:-unknown}" "${head:0:7}"
+ printf 'mso is up to date (CLI %s, build %s)\n' "${local_v:-unknown}" "${head:0:7}"
fi
}
notice() {
@@ -117,8 +121,13 @@ notice() {
fi
if [ "$n" -gt 0 ]; then
local_v="$(current_version)"; remote_v="$(remote_version)"
- printf 'MSO update available: %s -> %s (%s commit%s). Run: mso update\n' \
- "${local_v:-current}" "${remote_v:-newer}" "$n" "$([ "$n" = 1 ] || printf s)" >&2
+ if [ -n "$local_v" ] && [ "$local_v" = "$remote_v" ]; then
+ printf 'MSO update available: %s new commit%s on CLI %s. Run: mso update\n' \
+ "$n" "$([ "$n" = 1 ] || printf s)" "$local_v" >&2
+ else
+ printf 'MSO update available: CLI %s -> %s (%s commit%s). Run: mso update\n' \
+ "${local_v:-current}" "${remote_v:-newer}" "$n" "$([ "$n" = 1 ] || printf s)" >&2
+ fi
return 0
fi
if service_is_active; then
diff --git a/scripts/mso-update-service-status.test.ts b/scripts/mso-update-service-status.test.ts
index cafc8b4f..d3656811 100644
--- a/scripts/mso-update-service-status.test.ts
+++ b/scripts/mso-update-service-status.test.ts
@@ -60,7 +60,7 @@ describe("mso update active-service build identity", () => {
it("reports up to date only when the active service build matches source HEAD", () => {
const f = fixture(); const currentShort = git(f.repo, "rev-parse", "--short", f.current);
const out = execFileSync(SCRIPT, ["status"], { env: { ...f.env, MSO_TEST_BUILD_SHA: currentShort }, encoding: "utf8" });
- expect(out).toContain(`is up to date (${currentShort})`);
+ expect(out).toContain(`is up to date (CLI 1.4.0, build ${currentShort})`);
expect(out).not.toContain("deployment verification/rebuild is pending");
});
diff --git a/scripts/mso-update-version-labels.test.ts b/scripts/mso-update-version-labels.test.ts
new file mode 100644
index 00000000..88c15aed
--- /dev/null
+++ b/scripts/mso-update-version-labels.test.ts
@@ -0,0 +1,43 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+const SCRIPT = path.join(process.cwd(), "scripts/mso-update");
+const roots: string[] = [];
+function git(cwd: string, ...args: string[]) {
+ return execFileSync("git", args, { cwd, encoding: "utf8" }).trim();
+}
+function fixture() {
+ const root = fs.mkdtempSync(path.join(os.tmpdir(), "mso-update-labels-")); roots.push(root);
+ const repo = path.join(root, "repo"), remote = path.join(root, "remote.git"), fakeBin = path.join(root, "bin");
+ fs.mkdirSync(path.join(repo, "scripts/lib"), { recursive: true }); fs.mkdirSync(path.join(repo, "bin")); fs.mkdirSync(fakeBin);
+ for (const name of ["private-state.sh", "update-state.sh", "runtime-exclusion.sh", "update-gateway-runtimes.sh", "update-git-authority.sh"]) {
+ fs.copyFileSync(path.join(process.cwd(), "scripts/lib", name), path.join(repo, "scripts/lib", name));
+ }
+ fs.writeFileSync(path.join(repo, "bin/mso"), '#!/bin/sh\nVERSION="1.3.0"\n', { mode: 0o755 });
+ git(repo, "init", "-q", "-b", "main"); git(repo, "config", "user.name", "MSO Test");
+ git(repo, "config", "user.email", "[email protected]"); git(repo, "add", ".");
+ git(repo, "commit", "-q", "-m", "initial"); const old = git(repo, "rev-parse", "HEAD");
+ git(root, "init", "--bare", "-q", remote); git(repo, "remote", "add", "origin", remote);
+ git(repo, "push", "-q", "-u", "origin", "main"); fs.writeFileSync(path.join(repo, "README.md"), "commit-only update\n");
+ git(repo, "add", "README.md"); git(repo, "commit", "-q", "-m", "commit-only update");
+ git(repo, "push", "-q", "origin", "main"); git(repo, "reset", "--hard", "-q", old);
+ fs.writeFileSync(path.join(fakeBin, "systemctl"), "#!/bin/sh\nexit 3\n", { mode: 0o755 });
+ return { env: { ...process.env, HOME: path.join(root, "home"), PATH: `${fakeBin}:${process.env.PATH}`,
+ MSO_UPDATE_ROOT: repo, MSO_UPDATE_NOTICE_DIR: path.join(root, "notice"),
+ MSO_UPDATE_STATE_DIR: path.join(root, "update-state"), MSO_RUNTIME_EXCLUSION_DIR: path.join(root, "runtime-exclusion") } };
+}
+afterEach(() => { for (const root of roots.splice(0)) fs.rmSync(root, { recursive: true, force: true }); });
+
+describe("mso update version labels", () => {
+ it("describes commit-only updates without a same-version arrow", () => {
+ const f = fixture(); const out = execFileSync(SCRIPT, ["status"], { env: f.env, encoding: "utf8" });
+ expect(out).toContain("update available: 1 new commit on mso CLI 1.3.0");
+ expect(out).not.toContain("1.3.0 -> 1.3.0");
+ const notice = spawnSync(SCRIPT, ["notice"], { env: f.env, encoding: "utf8" });
+ expect(notice.stderr).toContain("MSO update available: 1 new commit on CLI 1.3.0");
+ expect(notice.stderr).not.toContain("1.3.0 -> 1.3.0");
+ });
+});
diff --git a/scripts/mso-update.test.ts b/scripts/mso-update.test.ts
index 97338c44..4ac8bfa4 100644
--- a/scripts/mso-update.test.ts
+++ b/scripts/mso-update.test.ts
@@ -50,7 +50,8 @@ esac
git(repo, "add", "."); git(repo, "commit", "-q", "-m", "initial"); const old = git(repo, "rev-parse", "HEAD");
git(root, "init", "--bare", "-q", remote); git(repo, "remote", "add", "origin", remote); git(repo, "push", "-q", "-u", "origin", "main");
fs.writeFileSync(path.join(repo, "bin/mso"), '#!/bin/sh\nVERSION="1.4.0"\n', { mode: 0o755 });
- git(repo, "add", "bin/mso"); git(repo, "commit", "-q", "-m", "new cli"); const newer = git(repo, "rev-parse", "HEAD"); git(repo, "push", "-q", "origin", "main");
+ git(repo, "add", "bin/mso");
+ git(repo, "commit", "-q", "-m", "new cli"); const newer = git(repo, "rev-parse", "HEAD"); git(repo, "push", "-q", "origin", "main");
git(repo, "reset", "--hard", "-q", old);
const serviceRoot = options.activeService === "same" ? repo : options.activeService === "other" ? path.join(root, "other-service") : "";
if (serviceRoot && serviceRoot !== repo) fs.mkdirSync(serviceRoot, { recursive: true });
@@ -104,7 +105,7 @@ afterEach(() => { for (const root of roots.splice(0)) fs.rmSync(root, { recursiv
describe("mso update without a running web API", () => {
it("reports the incoming CLI version directly from origin/main", () => {
const f = fixture(); const out = execFileSync(SCRIPT, ["status"], { env: f.env, encoding: "utf8" });
- expect(out).toContain("update available: mso 1.3.0 -> 1.4.0 (1 commit)");
+ expect(out).toContain("update available: mso CLI 1.3.0 -> 1.4.0 (1 commit)");
expect(out).toContain("run: mso update"); expect(git(f.repo, "rev-parse", "HEAD")).toBe(f.old);
});