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(runtime): verify live update identities
Rahmane7acdafab5ff
diff --git a/app/api/health/route.test.ts b/app/api/health/route.test.tsindex fb19c173..c90b8d5e 100644--- a/app/api/health/route.test.ts+++ b/app/api/health/route.test.ts@@ -15,13 +15,24 @@ describe("/api/health", () => {expect(res.status).toBe(200);const body = (await res.json()) as Record<string, unknown>;expect(body.status).toBe("ok");+ expect(body.service).toBe("mso");expect(typeof body.buildId).toBe("string");+ expect(body.buildSha === null || typeof body.buildSha === "string").toBe(true);expect(typeof body.uptime).toBe("number");expect((body.uptime as number) >= 0).toBe(true);expect(typeof body.version).toBe("string");expect((body.version as string).length).toBeGreaterThan(0);});+ it("returns the commit identity baked into the running build", async () => {+ vi.stubEnv("NEXT_PUBLIC_COMMIT_SHA", "abc1234");+ const { GET } = await import("./route");+ const res = await GET();+ const body = (await res.json()) as Record<string, unknown>;+ expect(body.service).toBe("mso");+ expect(body.buildSha).toBe("abc1234");+ });+it("returns the runtime instance id supplied by the service manager", async () => {vi.stubEnv("MSO_RUNTIME_INSTANCE_ID", "restart-proof-123");const { GET } = await import("./route");diff --git a/app/api/health/route.ts b/app/api/health/route.tsindex 88333c70..c884d5fe 100644--- a/app/api/health/route.ts+++ b/app/api/health/route.ts@@ -12,7 +12,9 @@ export async function GET() {return NextResponse.json({status: "ok",+ service: "mso",buildId: process.env.NEXT_PUBLIC_BUILD_ID || "dev",+ buildSha: process.env.NEXT_PUBLIC_COMMIT_SHA || null,runtimeInstanceId: process.env.MSO_RUNTIME_INSTANCE_ID || null,version: pkg.version ?? "0.0.0",demo: true,@@ -24,7 +26,9 @@ export async function GET() {return NextResponse.json({status: "ok",+ service: "mso",buildId: process.env.NEXT_PUBLIC_BUILD_ID || "dev",+ buildSha: process.env.NEXT_PUBLIC_COMMIT_SHA || null,runtimeInstanceId: process.env.MSO_RUNTIME_INSTANCE_ID || null,uptime: Math.round(process.uptime()),version: pkg.version ?? "0.0.0",diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.mdindex bf18938e..8e5fad9d 100644--- a/docs/CHANGELOG.md+++ b/docs/CHANGELOG.md@@ -13,6 +13,7 @@ this is the *what*, and it is what Settings → About shows as “What's new”.**Fixed**+- `runtime` verify live update identities- `runtime` close final update web edges- `update` emit success after runtime restore- `update` serialize all checkout runtimesdiff --git a/docs/INSTALL.md b/docs/INSTALL.mdindex 09b01625..362fee96 100644--- a/docs/INSTALL.md+++ b/docs/INSTALL.md@@ -165,7 +165,7 @@ never changes the application bind to `0.0.0.0`. The tool cache is user-local anwith Cloudflare auto-update disabled. The tunnel process also receives a scrubbed environment ratherthan inheriting MSO login/session/BYOK secrets from the application shell. If systemd is unavailable (common on WSL), it may start thealready-built Next production runtime itself, still on `127.0.0.1`, and records whether that process-is gateway-owned. `gateway stop` terminates only recorded identities: Cloudflared is matched by PID/start-time/executable/exact argv, while the Next fallback uses PID/start-time/Node executable plus a random runtime-instance nonce echoed by `/api/health` so Next's mutable process title cannot confuse ownership. Private state and logs are owner-only and scoped by the canonical checkout plus selected loopback+is gateway-owned. `gateway stop` terminates only recorded identities: Cloudflared is matched by PID/start-time/executable/exact argv, while the Next fallback uses PID/start-time/Node executable plus a random runtime-instance nonce echoed by `/api/health` so Next's mutable process title cannot confuse ownership. After TERM/SIGKILL, MSO re-verifies that the exact recorded process identity disappeared before deleting lifecycle state; an unverified survivor leaves state intact and the stop fails closed. Private state and logs are owner-only and scoped by the canonical checkout plus selected loopbackorigin. The fallback Next process uses the same held-child release handshake as Cloudflared, so neitherchild may execute before the parent records PID + kernel start-ticks. Gateway/update lifecycletransactions use kernel `flock`, which is released automatically when a process exits instead of@@ -284,7 +284,7 @@ when the application exists.Production health is:```text-GET /api/health -> {status, buildId, uptime, version}+GET /api/health -> {status, service, buildId, buildSha, runtimeInstanceId, uptime, version}```### Service Center policy@@ -453,8 +453,11 @@ Git already reached `origin/main` is retried by the next ordinary `mso update` imislabeled "already up to date". The state is keyed by canonical checkout path, so two clones at thesame SHA cannot borrow each other's receipt. One owner-only transaction lock covers every service-active or offline in-place update, from source/receipt reconciliation through gateway runtime restore and receipt write. Recovery intent is written to private statebefore a gateway-owned runtime is quiesced, so an interrupted post-quiesce state update stays retryable.-Interactive CLI commands also show a throttled Git-backed update notice;-the notice never depends on port 4005. A successful service finalizer log ends with `UPDATE OK`.+Interactive CLI commands also show a throttled Git-backed source-update notice. When the system+service is active and source is already current, the notice/status path performs a bounded loopback+`/api/health` identity check and offers `mso update --rebuild` if the running build SHA differs or+cannot be proven. The offline updater itself remains API-independent. A successful service finalizer+log ends with `UPDATE OK`.If the installed source is correct but the production build tree is inconsistent, use:diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.mdindex 1b999fed..d274dbbf 100644--- a/docs/TROUBLESHOOTING.md+++ b/docs/TROUBLESHOOTING.md@@ -38,6 +38,8 @@ when Git HEAD already equals `origin/main`. Offline transactions are serialized;owner-only update-state directory just to bypass a pending recovery. Recovery intent is written beforea gateway-owned runtime is quiesced, so an interrupted state update remains safely retryable. Use`mso update status` for source/deployment state and `mso update log` for the service-updater transcript.+When `mso.service` is active, status also compares the commit baked into the live loopback `/api/health`+response with source `HEAD`; source equality alone is not treated as proof that deployment finished.### `mso update` says the active service belongs to another checkoutdiff --git a/scripts/gateway-stop-identity.test.ts b/scripts/gateway-stop-identity.test.tsnew file mode 100644index 00000000..1769cb41--- /dev/null+++ b/scripts/gateway-stop-identity.test.ts@@ -0,0 +1,35 @@+import { spawnSync } from "node:child_process";+import path from "node:path";+import { describe, expect, it } from "vitest";++const COMMON = path.join(process.cwd(), "scripts/lib/gateway-common.sh");++function run(body: string) {+ return spawnSync("bash", ["-c", `set -euo pipefail+source ${JSON.stringify(COMMON)}+${body}`], { encoding: "utf8" });+}++describe("gateway_stop_identity", () => {+ it("fails closed when the same process identity survives SIGKILL", () => {+ const result = run(`+gateway_identity_matches() { return 0; }+kill() { return 0; }+sleep() { :; }+gateway_stop_identity '{"pid":4242}'+`);+ expect(result.status).not.toBe(0);+ expect(result.stderr).toContain("survived SIGKILL; preserving lifecycle state");+ });++ it("succeeds once the recorded identity disappears", () => {+ const result = run(`+checks=0+gateway_identity_matches() { checks=$((checks+1)); [ "$checks" -lt 3 ]; }+kill() { return 0; }+sleep() { :; }+gateway_stop_identity '{"pid":4242}'+`);+ expect(result.status).toBe(0);+ });+});diff --git a/scripts/lib/gateway-common.sh b/scripts/lib/gateway-common.shindex fc7910d5..d17150c1 100644--- a/scripts/lib/gateway-common.sh+++ b/scripts/lib/gateway-common.sh@@ -155,5 +155,16 @@ gateway_stop_identity() {gateway_identity_matches "$identity" || return 0sleep 0.1done- gateway_identity_matches "$identity" && kill -KILL "$pid" 2>/dev/null || true+ if gateway_identity_matches "$identity"; then+ kill -KILL "$pid" 2>/dev/null || true+ for i in $(seq 1 20); do+ gateway_identity_matches "$identity" || return 0+ sleep 0.05+ done+ fi+ if gateway_identity_matches "$identity"; then+ printf 'mso gateway: process %s survived SIGKILL; preserving lifecycle state\n' "$pid" >&2+ return 1+ fi+ return 0}diff --git a/scripts/lib/gateway-runtime.sh b/scripts/lib/gateway-runtime.shindex 142e9e06..db4522b0 100644--- a/scripts/lib/gateway-runtime.sh+++ b/scripts/lib/gateway-runtime.sh@@ -165,8 +165,12 @@ gateway_cmd_stop_locked() {tunnel="$(jq -c '.tunnelIdentity // null' <<<"$state")"runtime="$(jq -c '.runtimeIdentity // null' <<<"$state")"owned="$(jq -r '.runtimeOwned // false' <<<"$state")"- [ "$tunnel" = null ] || gateway_stop_identity "$tunnel"- [ "$owned" != true ] || [ "$runtime" = null ] || gateway_stop_identity "$runtime"+ if [ "$tunnel" != null ]; then+ gateway_stop_identity "$tunnel" || gateway_fail "tunnel process could not be proven stopped; lifecycle state was preserved"+ fi+ if [ "$owned" = true ] && [ "$runtime" != null ]; then+ gateway_stop_identity "$runtime" || gateway_fail "runtime process could not be proven stopped; lifecycle state was preserved"+ fimso_private_state_remove_file "$STATE_FILE" >/dev/null 2>&1 || truegateway_info "gateway stopped; MSO remains loopback-only"}diff --git a/scripts/mso-update b/scripts/mso-updateindex 177a1363..8ce9dfc7 100755--- a/scripts/mso-update+++ b/scripts/mso-update@@ -33,6 +33,26 @@ fetch_main() { git -C "$ROOT" fetch --quiet origin main || fail "could not reachservice_is_active() { command -v systemctl >/dev/null 2>&1 && systemctl is-active --quiet mso.service; }+service_port() {+ local raw port+ raw="$(systemctl show -p Environment --value mso.service 2>/dev/null || true)"+ port="$(printf '%s\n' "$raw" | tr ' ' '\n' | sed -n 's/^PORT=//p' | head -1)"+ if ! [[ "$port" =~ ^[0-9]+$ ]] || [ "$port" -lt 1 ] || [ "$port" -gt 65535 ]; then port=4005; fi+ printf '%s' "$port"+}++service_build_sha() {+ local timeout="${1:-3}" port body sha+ port="$(service_port)"+ body="$(curl --noproxy '*' -fsS --connect-timeout "$timeout" --max-time "$timeout" "http://127.0.0.1:$port/api/health" 2>/dev/null)" || return 1+ sha="$(printf '%s' "$body" | jq -er '+ select(.status == "ok" and .service == "mso")+ | .buildSha+ | select(type == "string" and test("^[0-9a-f]{7,40}$"))+ ' 2>/dev/null)" || return 1+ printf '%s' "$sha"+}+require_service_checkout() {local configured canonical_root canonical_serviceconfigured="$(systemctl show -p WorkingDirectory --value mso.service 2>/dev/null || true)"@@ -59,8 +79,17 @@ print_status() {returnfiif service_is_active; then+ local running_sha head_shortrequire_service_checkout- printf 'mso %s is up to date (%s)\n' "${local_v:-unknown}" "${head:0:7}"+ head_short="$(git -C "$ROOT" rev-parse --short HEAD)"+ running_sha="$(service_build_sha 2>/dev/null || true)"+ if [ -z "$running_sha" ]; then+ printf 'source is current at %s, but the active service build identity is unavailable. deployment verification/rebuild is pending. run: mso update --rebuild\n' "$head_short"+ 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"+ fireturnfiinit_update_state@@ -82,9 +111,28 @@ notice() {printf '%s\n' "$now" | mso_private_state_atomic_write "$stamp" >/dev/null 2>&1 || true(cd "$ROOT" && nohup git fetch --quiet origin main >/dev/null 2>&1 </dev/null &) || truefi- n="$(behind)"; [ "$n" -gt 0 ] || return 0; 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+ n="$(behind)"+ 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+ return 0+ fi+ if service_is_active; then+ local running_sha head_short head_full configured canonical_root canonical_service+ configured="$(systemctl show -p WorkingDirectory --value mso.service 2>/dev/null || true)"+ canonical_root="$(realpath -e -- "$ROOT" 2>/dev/null || true)"+ canonical_service="$(realpath -e -- "$configured" 2>/dev/null || true)"+ if [ -n "$canonical_root" ] && [ "$canonical_service" = "$canonical_root" ]; then+ head_short="$(git -C "$ROOT" rev-parse --short HEAD 2>/dev/null || true)"+ head_full="$(git -C "$ROOT" rev-parse HEAD 2>/dev/null || true)"+ running_sha="$(service_build_sha 0.5 2>/dev/null || true)"+ if [ -n "$head_short" ] && { [ -z "$running_sha" ] || [[ "$head_full" != "$running_sha"* ]]; }; then+ printf 'MSO deployment rebuild pending: source %s, running %s. Run: mso update --rebuild\n' \+ "$head_short" "${running_sha:-unknown}" >&2+ fi+ fi+ fi}offline_build_locked() {diff --git a/scripts/mso-update-service-status.test.ts b/scripts/mso-update-service-status.test.tsnew file mode 100644index 00000000..202c2d07--- /dev/null+++ b/scripts/mso-update-service-status.test.ts@@ -0,0 +1,81 @@+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 LIBS = ["private-state.sh", "update-state.sh", "runtime-exclusion.sh", "update-gateway-runtimes.sh"];+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-service-status-")); roots.push(root);+ const repo = path.join(root, "repo"), remote = path.join(root, "remote.git"), bin = path.join(root, "bin");+ fs.mkdirSync(path.join(repo, "scripts/lib"), { recursive: true }); fs.mkdirSync(path.join(repo, "bin")); fs.mkdirSync(bin);+ for (const lib of LIBS) fs.copyFileSync(path.join(process.cwd(), "scripts/lib", lib), path.join(repo, "scripts/lib", lib));+ fs.writeFileSync(path.join(repo, "bin/mso"), '#!/bin/sh\nVERSION="1.3.0"\n', { mode: 0o755 });+ fs.writeFileSync(path.join(repo, "scripts/mso-gateway"), "#!/bin/sh\nexit 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", "old build"); 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 build"); const current = git(repo, "rev-parse", "HEAD"); git(repo, "push", "-q", "origin", "main");+ fs.writeFileSync(path.join(bin, "systemctl"), `#!/bin/sh+if [ "$1" = is-active ]; then exit 0; fi+if [ "$1" = show ]; then+ case "$3" in+ WorkingDirectory) printf '%s\n' ${JSON.stringify(repo)} ;;+ Environment) printf '%s\n' 'PORT=4555' ;;+ esac+ exit 0+fi+exit 3+`, { mode: 0o755 });+ fs.writeFileSync(path.join(bin, "curl"), `#!/bin/sh+case "$*" in+ *127.0.0.1:4555/api/health*) printf '{"status":"ok","service":"mso","buildSha":"%s"}\n' "\${MSO_TEST_BUILD_SHA:-}" ;;+ *) exit 97 ;;+esac+`, { mode: 0o755 });+ const env = { ...process.env, HOME: path.join(root, "home"), PATH: `${bin}:${process.env.PATH}`, MSO_UPDATE_ROOT: repo,+ MSO_UPDATE_STATE_DIR: path.join(root, "update-state"), MSO_UPDATE_NOTICE_DIR: path.join(root, "notice") };+ return { repo, old, current, env };+}++afterEach(() => { for (const root of roots.splice(0)) fs.rmSync(root, { recursive: true, force: true }); });++describe("mso update active-service build identity", () => {+ it("reports pending rebuild when source is current but the service runs an older build", () => {+ const f = fixture(); const oldShort = git(f.repo, "rev-parse", "--short", f.old);+ const out = execFileSync(SCRIPT, ["status"], { env: { ...f.env, MSO_TEST_BUILD_SHA: oldShort }, encoding: "utf8" });+ expect(out).toContain("deployment verification/rebuild is pending");+ expect(out).toContain(`still running ${oldShort}`);+ expect(out).not.toContain("is up to date");+ });++ 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).not.toContain("deployment verification/rebuild is pending");+ });++ it("fails safe when an active service cannot prove its running build identity", () => {+ const f = fixture(); const out = execFileSync(SCRIPT, ["status"], { env: f.env, encoding: "utf8" });+ expect(out).toContain("active service build identity is unavailable");+ expect(out).toContain("deployment verification/rebuild is pending");+ expect(out).not.toContain("is up to date");+ });++ it("prints an interactive rebuild notice when the running service build is stale", () => {+ const f = fixture(); const oldShort = git(f.repo, "rev-parse", "--short", f.old);+ const out = spawnSync(SCRIPT, ["notice"], { env: { ...f.env, MSO_TEST_BUILD_SHA: oldShort }, encoding: "utf8" });+ expect(out.status).toBe(0); expect(out.stdout).toBe("");+ expect(out.stderr).toContain(`source ${git(f.repo, "rev-parse", "--short", f.current)}, running ${oldShort}`);+ expect(out.stderr).toContain("mso update --rebuild");+ });+});