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): bind readiness to runtime instance

Rahman6c9b9307b8aa
diff --git a/app/api/health/route.test.ts b/app/api/health/route.test.ts
index 3393e5ae..fb19c173 100644
--- a/app/api/health/route.test.ts
+++ b/app/api/health/route.test.ts
@@ -22,6 +22,14 @@ describe("/api/health", () => {
expect((body.version as string).length).toBeGreaterThan(0);
});
+ 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");
+ const res = await GET();
+ const body = (await res.json()) as Record<string, unknown>;
+ expect(body.runtimeInstanceId).toBe("restart-proof-123");
+ });
+
it("sets Cache-Control: no-store", async () => {
const { GET } = await import("./route");
const res = await GET();
diff --git a/app/api/health/route.ts b/app/api/health/route.ts
index 6621fcf2..88333c70 100644
--- a/app/api/health/route.ts
+++ b/app/api/health/route.ts
@@ -13,6 +13,7 @@ export async function GET() {
{
status: "ok",
buildId: process.env.NEXT_PUBLIC_BUILD_ID || "dev",
+ runtimeInstanceId: process.env.MSO_RUNTIME_INSTANCE_ID || null,
version: pkg.version ?? "0.0.0",
demo: true,
},
@@ -24,6 +25,7 @@ export async function GET() {
{
status: "ok",
buildId: process.env.NEXT_PUBLIC_BUILD_ID || "dev",
+ 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.md
index fbfc7961..cd57fe44 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` bind readiness to runtime instance
- `install` preserve caller path semantics
- `install` prove stable-id service takeover
- `install` keep security hint literal
diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md
index ffa4139f..0dbc901b 100644
--- a/docs/PROGRESS.md
+++ b/docs/PROGRESS.md
@@ -21,11 +21,12 @@ parent shell where `command -v mso` and `mso -h` succeed. The invoking cwd is ca
PATH entries such as `bin` are normalized against that cwd before discoverability is claimed, so a
later `cd` into the checkout cannot manufacture a false positive.
-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. Runtime reporting also
+The service readiness gate was also corrected for explicit `NEXT_DEPLOYMENT_ID`. Each installer-
+driven service restart now receives a fresh random runtime instance ID in the systemd unit, and the
+public no-store health route echoes that non-secret value. Readiness accepts the response only when
+it carries the exact freshly injected ID. This is stronger than either build-ID or MainPID change:
+it still works when the deployment ID intentionally stays stable, while a stale or unrelated process
+that happens to answer on the same port cannot satisfy the gate. Runtime reporting also
distinguishes “WSL without systemd” from “systemd existed, the unit was attempted, but health/takeover
verification failed,” so a failed WSL service keeps its journal recovery path instead of being mislabeled.
diff --git a/lib/config/env-example.test.ts b/lib/config/env-example.test.ts
index fb03dfc3..b70cbcf8 100644
--- a/lib/config/env-example.test.ts
+++ b/lib/config/env-example.test.ts
@@ -21,6 +21,7 @@ const NOT_A_KNOB: Record<string, string> = {
// Injected by the framework or the runtime.
NEXT_RUNTIME: "set by Next itself",
NEXT_PUBLIC_BUILD_ID: "injected by next.config.mjs at build time",
+ MSO_RUNTIME_INSTANCE_ID: "injected by the installer-managed service to prove restart readiness",
VITEST: "set by the test runner",
// The OS gives these to every process.
SHELL: "the OS's",
diff --git a/lib/install-contract.test.ts b/lib/install-contract.test.ts
index fdb3cc0a..3c843020 100644
--- a/lib/install-contract.test.ts
+++ b/lib/install-contract.test.ts
@@ -34,6 +34,7 @@ describe("one-line installer contract", () => {
expect(src).toContain('"$BIN_DIR/mso" -h');
expect(src).toContain("# >>> mso cli >>>");
expect(src).toContain('export PATH="$BIN_DIR:$PATH"');
+ expect(src).toContain('custom MSO_BIN_DIR is not persisted automatically');
});
it("requires systemd as PID 1 before service setup and gates onboarding on verified health", () => {
@@ -46,8 +47,9 @@ describe("one-line installer contract", () => {
expect(src).toContain("SERVICE_ATTEMPTED=1");
expect(src).toContain('elif [ "$SERVICE_ATTEMPTED" -eq 1 ]; then');
expect(src.indexOf('elif [ "$SERVICE_ATTEMPTED" -eq 1 ]; then')).toBeLessThan(src.indexOf('elif is_wsl; then'));
- expect(src).toContain('systemctl show "$SERVICE" -p MainPID --value');
- expect(src).toContain('[ "$now_pid" -gt 0 ] && [ "$now_pid" != "$prev_pid" ]');
+ expect(src).toContain('RUNTIME_INSTANCE_ID="$(rand_hex 16)"');
+ expect(src).toContain('Environment=MSO_RUNTIME_INSTANCE_ID=$RUNTIME_INSTANCE_ID');
+ expect(src).toContain('[ "$now_instance" = "$RUNTIME_INSTANCE_ID" ]');
expect(src).toContain('[ "$RUN_ONBOARD" -eq 1 ] && [ "$SERVICE_READY" -eq 1 ]');
});
diff --git a/scripts/install.sh b/scripts/install.sh
index a477df53..19e3df6a 100755
--- a/scripts/install.sh
+++ b/scripts/install.sh
@@ -403,7 +403,11 @@ if [ "$CLI_IMMEDIATE" -eq 1 ]; then
else
warn "mso is installed, but this shell's existing PATH cannot see it yet"
warn "for this shell run: export PATH=\"$BIN_DIR:\$PATH\""
- info "future shells will load the persisted ~/.local/bin PATH block"
+ if [ "$BIN_DIR" = "$HOME/.local/bin" ]; then
+ info "future shells will load the persisted ~/.local/bin PATH block"
+ else
+ warn "custom MSO_BIN_DIR is not persisted automatically; add $BIN_DIR to your shell profile"
+ fi
fi
# ---- systemd unit ----
@@ -412,6 +416,7 @@ if [ "$DO_SERVICE" -eq 1 ] && systemd_ready; then
# Start via npm (always on PATH, ships with node) to match the proven prod unit;
# PORT/HOSTNAME are set as env too so `next start` binds correctly regardless.
NPM_BIN="$(command -v npm)"
+ RUNTIME_INSTANCE_ID="$(rand_hex 16)"
info "installing $SERVICE (needs sudo)…"
sudo_do tee "/etc/systemd/system/$SERVICE" >/dev/null <<EOF
[Unit]
@@ -425,6 +430,10 @@ WorkingDirectory=$DIR
EnvironmentFile=$DIR/.env.local
Environment=PORT=$PORT
Environment=HOSTNAME=$BIND
+# Fresh on every installer-driven restart. /api/health echoes this non-secret nonce
+# so readiness proves the HTTP response came from THIS restarted unit, not a stale
+# process that happened to keep answering on the configured port.
+Environment=MSO_RUNTIME_INSTANCE_ID=$RUNTIME_INSTANCE_ID
# A system unit with User= inherits no login session, so it gets no user-bus
# address and every \`systemctl --user\` it runs answers "Failed to connect to bus:
# No medium found". That silently broke the managed-app installs (which create
@@ -461,15 +470,6 @@ EOF
HEALTH_HOST="$BIND"
case "$BIND" in 0.0.0.0|::|"") HEALTH_HOST=127.0.0.1 ;; esac
- # 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
# without linger it would point at nothing after the installing shell exits.
@@ -503,17 +503,14 @@ EOF
body="$(curl -fsS --max-time 3 "http://$HEALTH_HOST:$PORT/api/health" 2>/dev/null || true)"
if [ -n "$body" ]; then
now_build="$(printf '%s' "$body" | sed -n 's/.*"buildId":"\([^"]*\)".*/\1/p')"
- # 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
+ now_instance="$(printf '%s' "$body" | sed -n 's/.*"runtimeInstanceId":"\([^"]*\)".*/\1/p')"
+ # A healthy response is accepted only when it carries the nonce injected into
+ # THIS service unit before restart. This remains correct when NEXT_DEPLOYMENT_ID
+ # intentionally keeps buildId stable and cannot be satisfied by a stale or
+ # unrelated process still listening on the same port.
+ if [ "$now_instance" = "$RUNTIME_INSTANCE_ID" ]; then
up=1; SERVICE_READY=1
- ok "health OK (build ${now_build:-unknown}, pid ${now_pid:-unknown})"
+ ok "health OK (build ${now_build:-unknown}, runtime instance verified)"
break
fi
fi
@@ -522,7 +519,7 @@ EOF
if [ "$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 build/process identity did not change (build $prev_build, pid $prev_pid) — check: journalctl -u mso -e"
+ warn "service is running but /api/health did not prove the restarted runtime instance — check: journalctl -u mso -e"
else
warn "$SERVICE is not running — check: journalctl -u mso -e"
fi