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): bind readiness to runtime instance
Rahman6c9b9307b8aa
diff --git a/app/api/health/route.test.ts b/app/api/health/route.test.tsindex 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.tsindex 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.mdindex 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 literaldiff --git a/docs/PROGRESS.md b/docs/PROGRESS.mdindex 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 caPATH entries such as `bin` are normalized against that cwd before discoverability is claimed, so alater `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 alsodistinguishes “WSL without systemd” from “systemd existed, the unit was attempted, but health/takeoververification 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.tsindex 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.tsindex 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.shindex a477df53..19e3df6a 100755--- a/scripts/install.sh+++ b/scripts/install.sh@@ -403,7 +403,11 @@ if [ "$CLI_IMMEDIATE" -eq 1 ]; thenelsewarn "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"+ fifi# ---- 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=$DIREnvironmentFile=$DIR/.env.localEnvironment=PORT=$PORTEnvironment=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 @@ EOFHEALTH_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 @@ EOFbody="$(curl -fsS --max-time 3 "http://$HEALTH_HOST:$PORT/api/health" 2>/dev/null || true)"if [ -n "$body" ]; thennow_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" ]; thenup=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)"breakfifi@@ -522,7 +519,7 @@ EOFif [ "$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"elsewarn "$SERVICE is not running — check: journalctl -u mso -e"fi