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(gateway): serialize runtime recovery and updates

Rahman10ae35d9bade
diff --git a/SECURITY.md b/SECURITY.md
index 6eb8f26f..4a233726 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -38,8 +38,10 @@ application roles, but they still share the same deployment and underlying Unix
Tunnel and fallback-runtime startup additionally use a parent/child release handshake, so neither
Cloudflared nor Next can execute before its process lifetime is tracked; interruption before release
makes the held child self-exit. Gateway state is namespaced by canonical checkout + loopback origin,
- lifecycle/update serialization uses crash-released kernel `flock`, and public readiness must match
- the exact local build/runtime identity rather than only the MSO version.
+ lifecycle/update serialization uses crash-released kernel `flock`; a checkout-wide runtime
+ exclusion prevents `mso web`/gateway runtime starts during offline `.next` mutation, and a live
+ tunnel with a dead local runtime is reconciled before reuse. Public readiness must match the exact
+ local build/runtime identity rather than only the MSO version.
- Use `NEXT_PUBLIC_OS_DEMO=1` only in a separate mock-only public demo checkout.
The core gateway client follows the same immutable-artifact rule as managed apps: MSO pins the
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index ee71d80d..d6fdcb82 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**
+- `gateway` serialize runtime recovery and updates
- `gateway` close final lifecycle boundaries
- `gateway` close tunnel fork signal race
- `gateway` serialize offline recovery state
diff --git a/docs/INSTALL.md b/docs/INSTALL.md
index eafd9cee..fd356b7e 100644
--- a/docs/INSTALL.md
+++ b/docs/INSTALL.md
@@ -169,7 +169,12 @@ is gateway-owned. `gateway stop` terminates only recorded identities: Cloudflare
origin. The fallback Next process uses the same held-child release handshake as Cloudflared, so neither
child may execute before the parent records PID + kernel start-ticks. Gateway/update lifecycle
transactions use kernel `flock`, which is released automatically when a process exits instead of
-trying to reclaim stale lock directories. Before a public tunnel is accepted, MSO snapshots the
+trying to reclaim stale lock directories. A second checkout-wide shared/exclusive runtime lock blocks
+`mso web`/`gateway start` while an offline update is mutating `.next`; the updater releases that
+exclusive lock only after the build tree and deployment receipt are stable, then restores the runtime.
+If a tunnel is still alive but its local runtime died, `mso gateway start` reconciles/restarts the
+runtime, preserves the existing tunnel identity, and re-verifies the public endpoint before reporting
+success. Before a public tunnel is accepted, MSO snapshots the
selected local `{version, buildId, runtimeInstanceId}` and requires the HTTPS endpoint to return the
exact same identity; a same-version deployment routed from the wrong hostname is rejected.
diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md
index e04ebc40..692ce2b7 100644
--- a/docs/PROGRESS.md
+++ b/docs/PROGRESS.md
@@ -40,7 +40,11 @@ self-terminates. The same handshake now protects the detached Next fallback. Fin
gateway/update serialization to kernel `flock` (no stale-lock ABA reclaim), scoped gateway state by
canonical checkout + selected loopback origin, and made public readiness compare the exact local
`version + buildId + runtimeInstanceId`. This closes the cross-clone control and wrong-deployment
-readiness classes without widening the raw app bind.
+readiness classes without widening the raw app bind. The last P1 review pass added a checkout-wide
+shared/exclusive runtime exclusion: offline update owns it exclusively through `.next` mutation and
+deployment-receipt persistence, while all runtime-start paths take the shared side. An already-live
+tunnel is no longer treated as sufficient proof of readiness; `gateway start` recovers a dead local
+runtime, preserves the tunnel PID, and re-probes the exact public health identity before success.
The global response policy additionally sends `X-Robots-Tag: noindex, nofollow, noarchive` because an
MSO control plane should not be indexed merely because a temporary HTTPS endpoint exists. The
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index 7ee220f6..9241b5c0 100644
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -47,6 +47,12 @@ This is a safety refusal. A machine may contain multiple MSO clones, but an acti
one canonical `WorkingDirectory`. Run the update from that checkout (normally the directory targeted
by the installer) instead of letting a secondary clone rebuild itself and restart someone else's unit.
+### `mso gateway start` says an offline update is mutating this checkout
+
+This is an intentional safety exclusion. An offline `mso update` 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.
+
### `mso gateway start` cannot install or verify cloudflared
Current MSO installs a reviewed `cloudflared` release automatically into `~/.mso/tools` on first
diff --git a/scripts/lib/gateway-config.sh b/scripts/lib/gateway-config.sh
index 3f0bf30e..bf12fb55 100644
--- a/scripts/lib/gateway-config.sh
+++ b/scripts/lib/gateway-config.sh
@@ -101,14 +101,20 @@ gateway_cmd_web() {
done
case "$mode" in
public)
- if state="$(gateway_active_state)"; then url="$(jq -r .url <<<"$state")"
+ if state="$(gateway_active_state)"; then
+ gateway_with_lock gateway_with_runtime_shared gateway_cmd_start_locked >/dev/null
+ state="$(gateway_active_state)" || gateway_fail "public gateway stopped during reconciliation"
+ url="$(jq -r .url <<<"$state")"
else rc=$?; [ "$rc" = 1 ] || return "$rc"; gateway_fail "public gateway is not running; run: mso gateway start"; fi ;;
- local) gateway_health_ok || gateway_with_lock gateway_cmd_local_start_locked >/dev/null; url="$LOCAL_URL" ;;
+ local) gateway_health_ok || gateway_with_lock gateway_with_runtime_shared gateway_cmd_local_start_locked >/dev/null; url="$LOCAL_URL" ;;
auto)
- if state="$(gateway_active_state)"; then url="$(jq -r .url <<<"$state")"
+ if state="$(gateway_active_state)"; then
+ gateway_with_lock gateway_with_runtime_shared gateway_cmd_start_locked >/dev/null
+ state="$(gateway_active_state)" || gateway_fail "public gateway stopped during reconciliation"
+ url="$(jq -r .url <<<"$state")"
else rc=$?; [ "$rc" = 1 ] || return "$rc"
if [ -n "${OS_PUBLIC_ORIGIN:-}" ]; then url="$(gateway_validate_public_origin "$OS_PUBLIC_ORIGIN" 2>/dev/null || true)"
- else gateway_health_ok || gateway_with_lock gateway_cmd_local_start_locked >/dev/null; url="$LOCAL_URL"; fi
+ else gateway_health_ok || gateway_with_lock gateway_with_runtime_shared gateway_cmd_local_start_locked >/dev/null; url="$LOCAL_URL"; fi
fi ;;
esac
case "$url" in http:*) url="$(gateway_validate_loopback_origin "$url" 2>/dev/null || true)" ;;
diff --git a/scripts/lib/gateway-reconcile.sh b/scripts/lib/gateway-reconcile.sh
new file mode 100755
index 00000000..49d8ae0f
--- /dev/null
+++ b/scripts/lib/gateway-reconcile.sh
@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# Reconcile an already-live tunnel with the selected local runtime before reuse.
+
+gateway_reconcile_active_tunnel() {
+ local state="$1" existing_tunnel provider mode public
+ existing_tunnel="$(jq -c '.tunnelIdentity // null' <<<"$state")"
+ [ "$existing_tunnel" != null ] && gateway_identity_matches_retry "$existing_tunnel" \
+ || gateway_fail "active gateway state no longer matches its tunnel process"
+ provider="$(jq -r '.provider // "cloudflare-quick"' <<<"$state")"
+ mode="$(jq -r '.mode // "temporary"' <<<"$state")"
+ public="$(gateway_validate_public_origin "$(jq -r '.url // empty' <<<"$state")" 2>/dev/null || true)"
+ [ -n "$public" ] || gateway_fail "active gateway state has an invalid public origin"
+
+ # Keep the already-live tunnel outside pending cleanup. If runtime recovery or
+ # public verification fails, the old tunnel remains for diagnosis; only a newly
+ # started fallback runtime is rolled back.
+ TUNNEL_IDENTITY=null
+ GATEWAY_PROVIDER="$provider"; GATEWAY_MODE="$mode"; GATEWAY_PUBLIC_URL="$public"
+ gateway_assert_port_loopback_only
+ gateway_runtime_from_state "$state"
+ gateway_start_runtime_if_needed
+ gateway_assert_port_loopback_only
+ LOCAL_HEALTH_IDENTITY="$(gateway_health_url_identity "$LOCAL_URL" "${RUNTIME_INSTANCE_ID:-}")" \
+ || { gateway_reconcile_runtime_rollback; gateway_fail "active tunnel has no verified local MSO runtime"; }
+ if ! gateway_probe_public; then
+ gateway_reconcile_runtime_rollback
+ gateway_fail "active tunnel did not return the selected local MSO health identity"
+ fi
+
+ TUNNEL_IDENTITY="$existing_tunnel"
+ if ! gateway_write_state "$provider" "$mode" "$public" "$existing_tunnel"; then
+ TUNNEL_IDENTITY=null
+ gateway_reconcile_runtime_rollback
+ gateway_fail "recovered runtime is healthy but gateway state could not be persisted"
+ fi
+ GATEWAY_PENDING_CLEANUP=0
+ gateway_cmd_status
+}
+
+gateway_reconcile_runtime_rollback() {
+ if [ "${RUNTIME_STARTED_NOW:-false}" = true ] && [ "${RUNTIME_IDENTITY:-null}" != null ]; then
+ gateway_stop_identity "$RUNTIME_IDENTITY"
+ else
+ gateway_stop_pending_runtime
+ fi
+ RUNTIME_IDENTITY=null; RUNTIME_INSTANCE_ID=''; RUNTIME_OWNED=false; RUNTIME_STARTED_NOW=false
+ GATEWAY_PENDING_CLEANUP=0
+}
diff --git a/scripts/lib/gateway-tunnel.sh b/scripts/lib/gateway-tunnel.sh
index 88547f79..765410a1 100644
--- a/scripts/lib/gateway-tunnel.sh
+++ b/scripts/lib/gateway-tunnel.sh
@@ -157,7 +157,7 @@ gateway_cleanup_failed_start() {
gateway_cmd_start_locked() {
local state active rc
- if active="$(gateway_active_state)"; then gateway_cmd_status; return 0; else rc=$?; fi
+ if active="$(gateway_active_state)"; then gateway_reconcile_active_tunnel "$active"; return 0; else rc=$?; fi
[ "$rc" = 1 ] || return "$rc"
[ -z "$GATEWAY_CONFIG$GATEWAY_TUNNEL" ] || gateway_validate_named_tunnel
gateway_resolve_cloudflared
diff --git a/scripts/lib/runtime-exclusion.sh b/scripts/lib/runtime-exclusion.sh
new file mode 100755
index 00000000..97b10733
--- /dev/null
+++ b/scripts/lib/runtime-exclusion.sh
@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# Checkout-wide shared/exclusive lock preventing .next mutation under a fallback runtime.
+
+RUNTIME_EXCLUSION_DIR=''
+RUNTIME_EXCLUSION_FILE=''
+RUNTIME_EXCLUSION_FD=''
+RUNTIME_EXCLUSION_HELD=0
+
+runtime_exclusion_init() {
+ local canonical base key requested
+ [ -n "$RUNTIME_EXCLUSION_FILE" ] && return 0
+ canonical="$(realpath -e -- "$ROOT" 2>/dev/null || true)"
+ [ -n "$canonical" ] || { printf 'cannot canonicalize runtime-exclusion checkout\n' >&2; return 1; }
+ requested="${MSO_RUNTIME_EXCLUSION_DIR:-$HOME/.mso/private/runtime-exclusion}"
+ base="$(mso_private_state_dir "$requested")" || return 1
+ key="$(printf '%s' "$canonical" | sha256sum | awk '{print $1}')"
+ [[ "$key" =~ ^[0-9a-f]{64}$ ]] || { printf 'cannot derive runtime-exclusion scope\n' >&2; return 1; }
+ RUNTIME_EXCLUSION_DIR="$(mso_private_state_dir "$base/$key")" || return 1
+ RUNTIME_EXCLUSION_FILE="$RUNTIME_EXCLUSION_DIR/runtime.lock"
+ mso_private_state_ensure_file "$RUNTIME_EXCLUSION_FILE" >/dev/null || return 1
+}
+
+runtime_exclusion_acquire() {
+ local mode="$1" timeout="$2" flag
+ runtime_exclusion_init || return 1
+ case "$mode" in shared) flag=-s ;; exclusive) flag=-x ;; *) return 2 ;; esac
+ [[ "$timeout" =~ ^[0-9]+([.][0-9]+)?$ ]] || return 2
+ exec {RUNTIME_EXCLUSION_FD}<>"$RUNTIME_EXCLUSION_FILE" || return 1
+ if ! flock "$flag" -w "$timeout" "$RUNTIME_EXCLUSION_FD"; then
+ exec {RUNTIME_EXCLUSION_FD}>&- || true
+ RUNTIME_EXCLUSION_FD=''
+ return 1
+ fi
+ RUNTIME_EXCLUSION_HELD=1
+}
+
+runtime_exclusion_acquire_shared() {
+ runtime_exclusion_acquire shared "${MSO_RUNTIME_EXCLUSION_TIMEOUT_SECONDS:-12}"
+}
+
+runtime_exclusion_acquire_exclusive() {
+ runtime_exclusion_acquire exclusive "${MSO_RUNTIME_EXCLUSION_UPDATE_TIMEOUT_SECONDS:-900}"
+}
+
+runtime_exclusion_release() {
+ [ "$RUNTIME_EXCLUSION_HELD" = 1 ] || return 0
+ if [ -n "${RUNTIME_EXCLUSION_FD:-}" ]; then
+ flock -u "$RUNTIME_EXCLUSION_FD" 2>/dev/null || true
+ exec {RUNTIME_EXCLUSION_FD}>&- || true
+ RUNTIME_EXCLUSION_FD=''
+ fi
+ RUNTIME_EXCLUSION_HELD=0
+}
diff --git a/scripts/mso-gateway b/scripts/mso-gateway
index 66107a06..a2e4a6c3 100755
--- a/scripts/mso-gateway
+++ b/scripts/mso-gateway
@@ -60,6 +60,8 @@ GATEWAY_LOCK_FD=''
. "$ROOT/scripts/lib/gateway-tool.sh"
# shellcheck source=scripts/lib/gateway-lock.sh
. "$ROOT/scripts/lib/gateway-lock.sh"
+# shellcheck source=scripts/lib/runtime-exclusion.sh
+. "$ROOT/scripts/lib/runtime-exclusion.sh"
# shellcheck source=scripts/lib/gateway-health.sh
. "$ROOT/scripts/lib/gateway-health.sh"
# shellcheck source=scripts/lib/gateway-recovery.sh
@@ -70,8 +72,16 @@ GATEWAY_LOCK_FD=''
. "$ROOT/scripts/lib/gateway-pending.sh"
# shellcheck source=scripts/lib/gateway-tunnel.sh
. "$ROOT/scripts/lib/gateway-tunnel.sh"
+# shellcheck source=scripts/lib/gateway-reconcile.sh
+. "$ROOT/scripts/lib/gateway-reconcile.sh"
+gateway_with_runtime_shared() {
+ runtime_exclusion_acquire_shared || gateway_fail "offline update is mutating this checkout; retry after mso update finishes"
+ "$@"
+ runtime_exclusion_release
+}
+
case "${1:-status}" in
- start) gateway_parse_start_args "$@"; gateway_with_lock gateway_cmd_start_locked ;;
+ start) gateway_parse_start_args "$@"; gateway_with_lock gateway_with_runtime_shared gateway_cmd_start_locked ;;
stop) gateway_with_lock gateway_cmd_stop_locked ;;
status) gateway_cmd_status ;;
url) gateway_cmd_url ;;
@@ -79,7 +89,7 @@ case "${1:-status}" in
install) gateway_cmd_install_tool ;;
domain) shift; gateway_cmd_domain "$@" ;;
web) gateway_cmd_web "$@" ;;
- local-start) gateway_with_lock gateway_cmd_local_start_locked ;; # internal: onboard/web/update fallback
+ local-start) gateway_with_lock gateway_with_runtime_shared gateway_cmd_local_start_locked ;; # internal: onboard/web/update fallback
runtime-stop) gateway_with_lock gateway_cmd_runtime_stop_locked ;; # internal: quiesce owned runtime before offline build
*) gateway_fail "usage: mso gateway start|stop|status|url|doctor|install|domain ..." ;;
esac
diff --git a/scripts/mso-gateway-active-recovery.test.ts b/scripts/mso-gateway-active-recovery.test.ts
new file mode 100644
index 00000000..29589e87
--- /dev/null
+++ b/scripts/mso-gateway-active-recovery.test.ts
@@ -0,0 +1,45 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { GATEWAY, ROOT, VERSION, cleanupGatewayFixtures, fixture } from "./mso-gateway-test-fixture";
+
+afterEach(() => cleanupGatewayFixtures());
+
+describe("mso active tunnel runtime recovery", () => {
+ it("restarts a dead local runtime while preserving the already-live tunnel", () => {
+ const f = fixture(), root = path.join(f.dir, "recovery-root"), port = 43000 + Math.floor(Math.random() * 10000);
+ fs.mkdirSync(path.join(root, "scripts"), { recursive: true });
+ fs.cpSync(path.join(ROOT, "scripts/lib"), path.join(root, "scripts/lib"), { recursive: true });
+ fs.copyFileSync(GATEWAY, path.join(root, "scripts/mso-gateway")); fs.chmodSync(path.join(root, "scripts/mso-gateway"), 0o755);
+ fs.copyFileSync(path.join(ROOT, "package.json"), path.join(root, "package.json"));
+ fs.mkdirSync(path.join(root, ".next"), { recursive: true }); fs.writeFileSync(path.join(root, ".next/BUILD_ID"), "fixture\n");
+ fs.mkdirSync(path.join(root, "node_modules/next/dist/bin"), { recursive: true });
+ fs.writeFileSync(path.join(root, "node_modules/next/dist/bin/next"), `
+const http=require('http'); const args=process.argv.slice(2); const port=Number(args[args.indexOf('--port')+1]);
+http.createServer((req,res)=>{res.setHeader('content-type','application/json');res.end(JSON.stringify({status:'ok',buildId:'recovered-build',runtimeInstanceId:process.env.MSO_RUNTIME_INSTANCE_ID,version:${JSON.stringify(VERSION)}}));}).listen(port,'127.0.0.1');
+process.on('SIGTERM',()=>process.exit(0));
+`);
+ const baseEnv = { ...f.baseEnv, MSO_GATEWAY_ROOT: root, MSO_GATEWAY_ARTIFACT_LOCK: path.join(ROOT, "security/gateway-artifacts.env"),
+ MSO_GATEWAY_LOCAL_URL: `http://127.0.0.1:${port}`, MSO_RUNTIME_EXCLUSION_DIR: path.join(f.dir, "runtime-exclusion") };
+ const gateway = path.join(root, "scripts/mso-gateway");
+ const first = spawnSync(gateway, ["start"], { encoding: "utf8", env: baseEnv });
+ expect(first.status).toBe(0);
+ const before = JSON.parse(fs.readFileSync(path.join(f.state, "state.json"), "utf8")) as { tunnelIdentity: { pid: number }; runtimeOwned: boolean };
+ expect(before.runtimeOwned).toBe(false);
+
+ fs.writeFileSync(f.curl, "#!/bin/sh\nexec /usr/bin/curl \"$@\"\n", { mode: 0o700 });
+ const second = spawnSync(gateway, ["start"], { encoding: "utf8", env: baseEnv, timeout: 15_000 });
+ expect(second.status).toBe(0);
+ const after = JSON.parse(fs.readFileSync(path.join(f.state, "state.json"), "utf8")) as {
+ tunnelIdentity: { pid: number }; runtimeIdentity: { pid: number; instanceId: string }; runtimeOwned: boolean;
+ };
+ expect(after.tunnelIdentity.pid).toBe(before.tunnelIdentity.pid);
+ expect(after.runtimeOwned).toBe(true);
+ expect(after.runtimeIdentity.instanceId).toMatch(/^[0-9a-f]{32}$/);
+ const health = JSON.parse(require("node:child_process").execFileSync("curl", ["-fsS", `http://127.0.0.1:${port}/api/health`], { encoding: "utf8" }));
+ expect(health.buildId).toBe("recovered-build");
+ expect(health.runtimeInstanceId).toBe(after.runtimeIdentity.instanceId);
+ spawnSync(gateway, ["stop"], { env: baseEnv, encoding: "utf8" });
+ }, 20_000);
+});
diff --git a/scripts/mso-gateway-boundaries.test.ts b/scripts/mso-gateway-boundaries.test.ts
index 01fae570..6f75f744 100644
--- a/scripts/mso-gateway-boundaries.test.ts
+++ b/scripts/mso-gateway-boundaries.test.ts
@@ -1,4 +1,4 @@
-import { execFileSync, spawnSync } from "node:child_process";
+import { execFileSync, spawn, spawnSync } from "node:child_process";
import fs from "node:fs";
import path from "node:path";
import { afterEach, describe, expect, it } from "vitest";
@@ -56,6 +56,25 @@ esac
expect(fs.existsSync(path.join(f.state, "state.json"))).toBe(false);
}, 15_000);
+ it("refuses local runtime starts while an offline update holds the checkout exclusion", async () => {
+ const f = fixture(), base = path.join(f.dir, "runtime-exclusion");
+ const key = require("node:crypto").createHash("sha256").update(fs.realpathSync(ROOT)).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 });
+ const holder = spawn("flock", ["-x", lock, "-c", "sleep 2"], { stdio: "ignore" });
+ await new Promise((r) => setTimeout(r, 100));
+ try {
+ const out = spawnSync(GATEWAY, ["local-start"], { encoding: "utf8", env: { ...f.baseEnv,
+ MSO_RUNTIME_EXCLUSION_DIR: base, MSO_RUNTIME_EXCLUSION_TIMEOUT_SECONDS: "0.1" } });
+ expect(out.status).not.toBe(0);
+ expect(out.stderr).toContain("offline update is mutating this checkout");
+ } finally {
+ try { holder.kill("SIGTERM"); } catch {}
+ await new Promise<void>((resolve) => holder.once("close", () => resolve()));
+ }
+ });
+
it("uses kernel flock locks instead of stale-directory reclamation", () => {
for (const name of ["gateway-lock.sh", "update-state.sh"]) {
const source = fs.readFileSync(path.join(ROOT, "scripts/lib", name), "utf8");
diff --git a/scripts/mso-update b/scripts/mso-update
index ef14b29c..47268b29 100755
--- a/scripts/mso-update
+++ b/scripts/mso-update
@@ -12,6 +12,8 @@ GATEWAY="$ROOT/scripts/mso-gateway"
. "$ROOT/scripts/lib/private-state.sh"
# shellcheck source=scripts/lib/update-state.sh
. "$ROOT/scripts/lib/update-state.sh"
+# shellcheck source=scripts/lib/runtime-exclusion.sh
+. "$ROOT/scripts/lib/runtime-exclusion.sh"
fail() { printf 'mso update: %s\n' "$*" >&2; exit 1; }
git_root() { [ "$(git -C "$ROOT" rev-parse --show-toplevel 2>/dev/null || true)" = "$ROOT" ]; }
@@ -118,15 +120,20 @@ offline_build_locked() {
return 0
fi
- # Never mutate .next under a gateway-owned detached Next process. If an earlier
- # attempt failed after quiescing it, the private restart marker survives and the
- # next ordinary `mso update` finishes the deployment instead of trusting HEAD.
+ # Exclude every local-start/gateway-start from this checkout while .next can
+ # change. Runtime-starting gateway paths take a shared lock; this updater holds
+ # the exclusive side through quiesce/install/verify/build/receipt. The lock is
+ # released only after the build tree is stable, then restoration may safely race
+ # 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
(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"
- restore_offline_runtime
write_receipt
+ runtime_exclusion_release
+ restore_offline_runtime
if restart_pending; then fail "runtime restart marker remained after restore"; fi
printf 'updated to %s. No system service was active; run: mso web\n' "$(git -C "$ROOT" rev-parse --short HEAD)"
}
diff --git a/scripts/mso-update.test.ts b/scripts/mso-update.test.ts
index 2ccfd1fa..c1094396 100644
--- a/scripts/mso-update.test.ts
+++ b/scripts/mso-update.test.ts
@@ -7,6 +7,7 @@ import { afterEach, describe, expect, it } from "vitest";
const SCRIPT = path.join(process.cwd(), "scripts/mso-update");
const PRIVATE = path.join(process.cwd(), "scripts/lib/private-state.sh");
const UPDATE_STATE = path.join(process.cwd(), "scripts/lib/update-state.sh");
+const RUNTIME_EXCLUSION = path.join(process.cwd(), "scripts/lib/runtime-exclusion.sh");
const roots: string[] = [];
function git(cwd: string, ...args: string[]) { return execFileSync("git", args, { cwd, encoding: "utf8" }).trim(); }
@@ -16,6 +17,7 @@ function fixture(options: { failInstallOnce?: boolean; activeService?: "same" |
fs.mkdirSync(path.join(repo, "scripts/lib"), { recursive: true }); fs.mkdirSync(path.join(repo, "bin")); fs.mkdirSync(bin);
fs.copyFileSync(PRIVATE, path.join(repo, "scripts/lib/private-state.sh"));
fs.copyFileSync(UPDATE_STATE, path.join(repo, "scripts/lib/update-state.sh"));
+ fs.copyFileSync(RUNTIME_EXCLUSION, path.join(repo, "scripts/lib/runtime-exclusion.sh"));
fs.writeFileSync(path.join(repo, "scripts/verify-build.sh"), "#!/bin/sh\nexit 0\n", { mode: 0o755 });
fs.writeFileSync(path.join(repo, "scripts/mso-gateway"), `#!/bin/sh
printf 'gateway %s\\n' "$*" >> "${capture}"
@@ -162,6 +164,25 @@ describe("mso update without a running web API", () => {
expect([a.stdout, b.stdout].join("\n")).toContain("offline deployment receipt matches");
});
+ it("holds the checkout-wide runtime exclusion exclusively through the mutable build phase", async () => {
+ const f = fixture({ installDelayMs: 900 });
+ const exclusionBase = path.join(f.root, "runtime-exclusion");
+ const env = { ...f.env, MSO_RUNTIME_EXCLUSION_DIR: exclusionBase };
+ const update = runAsync(env);
+ for (let i = 0; i < 120; i++) {
+ if (fs.existsSync(f.capture) && fs.readFileSync(f.capture, "utf8").includes("bun install")) break;
+ await new Promise((r) => setTimeout(r, 20));
+ }
+ const key = require("node:crypto").createHash("sha256").update(fs.realpathSync(f.repo)).digest("hex");
+ const lock = path.join(exclusionBase, key, "runtime.lock");
+ expect(fs.existsSync(lock)).toBe(true);
+ const during = spawnSync("flock", ["-s", "-n", lock, "-c", "true"], { encoding: "utf8" });
+ expect(during.status).not.toBe(0);
+ const result = await update; expect(result.code).toBe(0);
+ const after = spawnSync("flock", ["-s", "-n", lock, "-c", "true"], { encoding: "utf8" });
+ expect(after.status).toBe(0);
+ });
+
it("prints an update notice from cached Git state without touching the web API", () => {
const f = fixture();
const result = execFileSync(SCRIPT, ["notice"], { env: f.env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });