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): serialize deploy and service starts
Rahman566ed0eaf5fe
diff --git a/bin/mso b/bin/msoindex eb9a73f6..018c4cda 100755--- a/bin/mso+++ b/bin/mso@@ -80,7 +80,7 @@# Service (local systemd)# service * status | start | stop | restart | logs# build Compile HEAD out-of-tree (safe against the live checkout)-# deploy next build, then restart the service+# deploy Rebuild active service with runtime quiesce/restore# update [--rebuild] Update from origin/main safely; works even when the web runtime is down## Escape hatches@@ -176,6 +176,63 @@ maybe_update_notice() {}# shellcheck source=scripts/lib/private-state.sh. "$ROOT/scripts/lib/private-state.sh"+# shellcheck source=scripts/lib/runtime-exclusion.sh+. "$ROOT/scripts/lib/runtime-exclusion.sh"++service_manager_read() {+ local manager="${MSO_SYSTEMCTL_BIN:-systemctl}"+ "$manager" "$@"+}++service_manager_write() {+ if [ -n "${MSO_SYSTEMCTL_BIN:-}" ]; then "$MSO_SYSTEMCTL_BIN" "$@";+ else sudo systemctl "$@"; fi+}++require_service_checkout_cli() {+ local configured canonical_root canonical_service+ configured="$(service_manager_read show -p WorkingDirectory --value mso.service 2>/dev/null || true)"+ [ -n "$configured" ] || die "mso.service has no readable WorkingDirectory; refusing lifecycle action"+ canonical_root="$(realpath -e -- "$ROOT" 2>/dev/null || true)"+ canonical_service="$(realpath -e -- "$configured" 2>/dev/null || true)"+ [ -n "$canonical_root" ] && [ -n "$canonical_service" ] \+ || die "cannot canonicalize mso.service WorkingDirectory"+ [ "$canonical_service" = "$canonical_root" ] \+ || die "mso.service belongs to $canonical_service, not this checkout $canonical_root"+}++service_with_runtime_shared() {+ local rc=0+ runtime_exclusion_acquire_shared \+ || die "offline update/deploy is mutating this checkout; retry the service action after it finishes"+ "$@" || rc=$?+ runtime_exclusion_release+ return "$rc"+}++service_start_safe() {+ require_service_checkout_cli+ service_with_runtime_shared service_manager_write start mso.service+}++service_restart_safe() {+ require_service_checkout_cli+ service_with_runtime_shared service_manager_write restart mso.service+}++deploy_safe() {+ local local_url helper+ require_service_checkout_cli+ service_manager_read is-active --quiet mso.service \+ || die "mso.service is not active; start the intended service first, then run mso deploy"+ local_url="$(gateway_local_url)"+ # The outer helper owns checkout-wide runtime inventory/quiesce/restore around+ # the in-place build, so deploy never mutates `.next` under a fallback runtime.+ helper="${MSO_SERVICE_UPDATE_BIN:-$ROOT/scripts/mso-service-update}"+ [ -x "$helper" ] || [ -f "$helper" ] || die "missing service deployment helper: $helper"+ MSO_UPDATE_ROOT="$ROOT" MSO_UPDATE_LOCAL_URL="$local_url" /bin/bash "$helper" --rebuild-only+ echo "deployed → $B"+}# ── local ops (no HTTP, no login) ───────────────────────────────────────────# These edit ~/.mso/auth-devices.json on THIS machine. They are deliberately local@@ -816,18 +873,18 @@ case "$cmd" inservice)case "${1:-status}" instatus) systemctl status --no-pager mso.service ;;- start) sudo systemctl start mso.service ;;+ start) service_start_safe ;;stop) sudo systemctl stop mso.service ;;- restart) sudo systemctl restart mso.service ;;+ restart) service_restart_safe ;;logs) journalctl -u mso.service -n "${2:-50}" --no-pager ;;*) die "usage: mso $U_service" ;;esac ;;# NOT `next build` — this is mso.service's WorkingDirectory, and a build here# deletes .next under the running process, 404ing every chunk until a restart.- # verify-build.sh compiles HEAD in a temp dir instead. `deploy` is the in-place- # one, and it restarts immediately after.+ # verify-build.sh compiles HEAD in a temp dir instead. `deploy` uses the same+ # checkout-wide quiesce/build/restart/restore lifecycle as service self-update.build) (cd "$ROOT" && bash scripts/verify-build.sh) ;;- deploy) (cd "$ROOT" && npm run build) && sudo systemctl restart mso.service && echo "deployed → $B" ;;+ deploy) deploy_safe ;;# The same self-update Settings → About drives, so both surfaces get the same# preflight and the same transient-unit handoff (a build spawned from the service# would be killed by the restart it performs).diff --git a/bin/mso-service-lifecycle.test.ts b/bin/mso-service-lifecycle.test.tsnew file mode 100644index 00000000..806a4d0b--- /dev/null+++ b/bin/mso-service-lifecycle.test.ts@@ -0,0 +1,63 @@+import { execFileSync, spawn, spawnSync } from "node:child_process";+import fs from "node:fs";+import os from "node:os";+import path from "node:path";+import crypto from "node:crypto";+import { afterEach, describe, expect, it } from "vitest";++const CLI = path.join(process.cwd(), "bin/mso");+const roots: string[] = [];++function fixture() {+ const root = fs.mkdtempSync(path.join(os.tmpdir(), "mso-service-cli-")); roots.push(root);+ const bin = path.join(root, "bin"), capture = path.join(root, "capture"), home = path.join(root, "home");+ fs.mkdirSync(bin); fs.mkdirSync(home);+ const manager = path.join(bin, "manager");+ fs.writeFileSync(manager, `#!/bin/sh\nprintf '%s\\n' "$*" >> "${capture}"\ncase "$*" in\n 'show -p WorkingDirectory --value mso.service') printf '%s\\n' "${process.cwd()}" ;;\n 'is-active --quiet mso.service') exit 0 ;;\nesac\n`, { mode: 0o755 });+ const helper = path.join(root, "service-update");+ fs.writeFileSync(helper, `#!/bin/sh\nprintf 'helper %s\\n' "$*" >> "${capture}"\n`, { mode: 0o755 });+ const exclusion = path.join(root, "runtime-exclusion");+ const env = { ...process.env, HOME: home, MSO_ENV: "/dev/null", MSO_GATEWAY_LOCAL_URL: "http://127.0.0.1:4005",+ MSO_SYSTEMCTL_BIN: manager, MSO_SERVICE_UPDATE_BIN: helper, MSO_RUNTIME_EXCLUSION_DIR: exclusion };+ return { root, capture, env, exclusion };+}++function lockPath(base: string) {+ const canonical = fs.realpathSync(process.cwd());+ const key = crypto.createHash("sha256").update(canonical).digest("hex");+ const dir = path.join(base, key); fs.mkdirSync(dir, { recursive: true, mode: 0o700 });+ fs.chmodSync(base, 0o700); fs.chmodSync(dir, 0o700);+ const lock = path.join(dir, "runtime.lock"); fs.writeFileSync(lock, "", { mode: 0o600 });+ return lock;+}++afterEach(() => { for (const root of roots.splice(0)) fs.rmSync(root, { recursive: true, force: true }); });++describe("mso service/deploy runtime exclusion", () => {+ it.each(["start", "restart"])("refuses service %s while an offline build owns the checkout", async (verb) => {+ const f = fixture(), lock = lockPath(f.exclusion);+ const holder = spawn("flock", ["-x", lock, "-c", "sleep 0.8"], { stdio: "ignore" });+ await new Promise((r) => setTimeout(r, 80));+ const out = spawnSync(CLI, ["service", verb], {+ env: { ...f.env, MSO_RUNTIME_EXCLUSION_TIMEOUT_SECONDS: "0.1" }, encoding: "utf8",+ });+ expect(out.status).not.toBe(0);+ expect(out.stderr).toContain("offline update/deploy is mutating this checkout");+ await new Promise<void>((resolve) => holder.once("close", () => resolve()));+ });++ it("routes deploy through the outer service-update lifecycle", () => {+ const f = fixture();+ const out = execFileSync(CLI, ["deploy"], { env: f.env, encoding: "utf8" });+ expect(out).toContain("deployed");+ expect(fs.readFileSync(f.capture, "utf8")).toContain("helper --rebuild-only");+ });++ it("refuses lifecycle actions from a checkout that does not own the service", () => {+ const f = fixture(), other = path.join(f.root, "other"); fs.mkdirSync(other);+ const manager = path.join(f.root, "wrong-manager");+ fs.writeFileSync(manager, `#!/bin/sh\ncase "$*" in 'show -p WorkingDirectory --value mso.service') printf '%s\\n' "${other}" ;; esac\n`, { mode: 0o755 });+ const out = spawnSync(CLI, ["service", "start"], { env: { ...f.env, MSO_SYSTEMCTL_BIN: manager }, encoding: "utf8" });+ expect(out.status).not.toBe(0); expect(out.stderr).toContain("mso.service belongs to");+ });+});diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.mdindex ad57f944..9568141d 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` serialize deploy and service starts- `gateway` recheck web state under lock- `update` reject unowned live runtimes- `runtime` verify live update identities@@ -42,6 +43,7 @@ this is the *what*, and it is what Settings → About shows as “What's new”.**Tests**+- `gateway` treat zombie children as stopped- `gateway` isolate lifecycle fixtures- `cli` lock offline update dispatch- `gateway` harden hosted security fixturesdiff --git a/docs/CLI.md b/docs/CLI.mdindex e558bf76..2cbe6a74 100644--- a/docs/CLI.md+++ b/docs/CLI.md@@ -114,7 +114,7 @@ Commands:Service (local systemd)service * status | start | stop | restart | logsbuild Compile HEAD out-of-tree (safe against the live checkout)- deploy next build, then restart the service+ deploy Rebuild active service with runtime quiesce/restoreupdate [--rebuild] Update from origin/main safely; works even when the web runtime is downEscape hatchesdiff --git a/docs/INSTALL.md b/docs/INSTALL.mdindex 401da4a6..46783146 100644--- a/docs/INSTALL.md+++ b/docs/INSTALL.md@@ -468,6 +468,13 @@ If the installed source is correct but the production build tree is inconsistentmso update --rebuild```+`mso deploy` is the developer-facing rebuild for an already-active `mso.service`. It now uses the same+outer checkout runtime lifecycle as self-update: verify the service belongs to this checkout, hold the+exclusive mutation boundary, quiesce every owned fallback runtime, rebuild/restart the service, then+restore those fallbacks. `mso service start` and `mso service restart` take the shared side of that same+checkout lock and refuse while an offline update/deploy is mutating `.next`; they also refuse when the+installed service belongs to another checkout.+### Developer releaseAfter code/docs changes and verification:diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.mdindex 752f603f..32969809 100644--- a/docs/TROUBLESHOOTING.md+++ b/docs/TROUBLESHOOTING.md@@ -56,8 +56,10 @@ mutation rather than rebuilding underneath a process that is actively serving th### `mso gateway start` says an offline update is mutating this checkout-This is an intentional safety exclusion. Every in-place `mso update` (service-active or offline) holds the checkout-wide runtime lock while `.next` can change, so `mso web`, onboarding fallback, and gateway runtime recovery cannot start-Next from a partially-mutated build. Let the update finish, then rerun the same gateway/web command.+This is an intentional safety exclusion. Every in-place `mso update` (service-active or offline) holds the checkout-wide runtime lock while `.next` can change, so `mso web`, onboarding fallback, gateway runtime recovery, and `mso service start/restart` cannot start+Next from a partially-mutated build. Let the update finish, then rerun the same gateway/web/service command.+`mso deploy` uses the same runtime-quiesce lifecycle and requires the active service to belong to the+checkout invoking the command.### `mso gateway start` cannot install or verify cloudflareddiff --git a/scripts/mso-update b/scripts/mso-updateindex 1e99ca7f..c3f94f49 100755--- a/scripts/mso-update+++ b/scripts/mso-update@@ -65,10 +65,6 @@ require_service_checkout() {|| fail "active mso.service belongs to $canonical_service, not this checkout $canonical_root; run update from the service checkout"}-quiesce_offline_runtime() { update_gateway_assert_offline_selected_origin_safe; update_gateway_quiesce_all; }--restore_offline_runtime() { update_gateway_restore_all; }-print_status() {local n local_v remote_v head receipt=''require_checkout; fetch_main; n="$(behind)"; local_v="$(current_version)"; remote_v="$(remote_version)"; head="$(git -C "$ROOT" rev-parse HEAD)"@@ -159,13 +155,18 @@ offline_build_locked() {# another post-build local-start without serving a partially-mutated .next.runtime_exclusion_acquire_exclusive \|| fail "could not acquire checkout runtime exclusion; another runtime start/update is active"- quiesce_offline_runtime+ # A service start may have raced the earlier pre-lock check. Service-starting CLI+ # paths take the shared side of this lock, so this second check closes the TOCTOU+ # window before any dependency/.next mutation.+ service_is_active && fail "mso.service became active before the offline build; rerun mso update"+ update_gateway_assert_offline_selected_origin_safe+ update_gateway_quiesce_all(cd "$ROOT" && bun install) || fail "dependency install failed"(cd "$ROOT" && bash scripts/verify-build.sh) || fail "candidate build verification failed"(cd "$ROOT" && node node_modules/next/dist/bin/next build) || fail "production build failed"write_receiptruntime_exclusion_release- restore_offline_runtime+ update_gateway_restore_allif update_gateway_restore_pending; then fail "gateway runtime restore inventory remained after restore"; fiprintf 'updated to %s. No system service was active; run: mso web\n' "$(git -C "$ROOT" rev-parse --short HEAD)"}