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
#!/usr/bin/env bash
# API-independent CLI updater. It keeps `mso update` useful even when :4005 is down.
set -euo pipefail
umask 077
ROOT="${MSO_UPDATE_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
LOG="${MSO_UPDATE_LOG:-$HOME/.mso/self-update.log}"
NOTICE_DIR="${MSO_UPDATE_NOTICE_DIR:-$HOME/.mso/private/update-notice}"
UPDATE_STATE_DIR_REQUESTED="${MSO_UPDATE_STATE_DIR:-$HOME/.mso/private/update-state}"
LOCAL_URL="${MSO_UPDATE_LOCAL_URL:-${MSO_GATEWAY_LOCAL_URL:-http://127.0.0.1:${MSO_PORT:-4005}}}"
GATEWAY="$ROOT/scripts/mso-gateway"
# shellcheck source=scripts/lib/private-state.sh
. "$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"
# shellcheck source=scripts/lib/update-gateway-runtimes.sh
. "$ROOT/scripts/lib/update-gateway-runtimes.sh"
# shellcheck source=scripts/lib/update-git-authority.sh
. "$ROOT/scripts/lib/update-git-authority.sh"
# shellcheck source=scripts/lib/update-remote-authority.sh
. "$ROOT/scripts/lib/update-remote-authority.sh"
fail() { printf 'mso update: %s\n' "$*" >&2; exit 1; }
git_root() { [ "$(git -C "$ROOT" rev-parse --show-toplevel 2>/dev/null || true)" = "$ROOT" ]; }
current_version() { sed -n 's/^VERSION="\([^"]*\)".*/\1/p' "$ROOT/bin/mso" | head -1; }
remote_version() { git -C "$ROOT" show "${1:-origin/main}:bin/mso" 2>/dev/null | sed -n 's/^VERSION="\([^"]*\)".*/\1/p' | head -1; }
require_checkout() {
git_root || fail "$ROOT is not a Git checkout; reinstall from the official repository"
[ "$(git -C "$ROOT" branch --show-current)" = main ] || fail "updates require the installed checkout to be on main"
[ -z "$(git -C "$ROOT" status --porcelain)" ] || fail "checkout has local changes; refusing to overwrite them"
}
fetch_main() { update_git_fetch_origin "$ROOT" main --tags || fail "could not reach origin/main"; }
# The owner's channel. Precedence: the caller's resolved enum (the detached offline
# wrapper passes the same value the API chose) → the prefs file the Settings panel
# writes → the documented default. Only the two-word enum is ever accepted.
configured_channel() {
local raw
raw="${MSO_UPDATE_CHANNEL:-$(jq -r '.updates.channel // "stable"' "${OS_PREFS_PATH:-$HOME/.mso/prefs.json}" 2>/dev/null || printf 'stable')}"
case "$raw" in
main) printf 'main' ;;
*) printf 'stable' ;;
esac
}
# Clear the unattended failure streak after a manual attempt. Failure is ignored: the
# state file is evidence for the panel, never a precondition for updating by hand.
clear_automation_pause() {
local module="$ROOT/scripts/mso-update-automation.ts"
if [ -f "$module" ] && command -v bun >/dev/null 2>&1; then
bun "$module" resume >/dev/null 2>&1 || true
fi
}
# Relation of HEAD to a channel target. A checkout PAST its release tag is normal,
# not "unpushed local work", so `ahead` only counts when the release has something to
# apply. Mirrors stableRelationAhead() in lib/host/self-update-channel.ts.
read_relation() {
local target="$1" relation ahead behind
read -r relation ahead behind < <(update_git_relation_to "$ROOT" "$target") || return 1
if [ "$target" != origin/main ] && [ "$behind" -eq 0 ]; then
ahead=0
[ "$relation" = ahead ] && relation=exact
fi
printf '%s %s %s\n' "$relation" "$ahead" "$behind"
}
service_is_active() {
# Containers/Codespaces often ship the systemctl binary without systemd as PID 1.
# A read-only probe must classify that as "no active service" without leaking
# systemd bus errors into ordinary `mso update` output.
command -v systemctl >/dev/null 2>&1 || return 1
systemctl is-active --quiet mso.service >/dev/null 2>&1
}
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_service
configured="$(systemctl show -p WorkingDirectory --value mso.service 2>/dev/null || true)"
[ -n "$configured" ] || fail "active mso.service has no readable WorkingDirectory; refusing update handoff"
canonical_root="$(realpath -e -- "$ROOT" 2>/dev/null || true)"
canonical_service="$(realpath -e -- "$configured" 2>/dev/null || true)"
[ -n "$canonical_root" ] && [ -n "$canonical_service" ] \
|| fail "cannot canonicalize active mso.service WorkingDirectory; refusing update handoff"
[ "$canonical_service" = "$canonical_root" ] \
|| fail "active mso.service belongs to $canonical_service, not this checkout $canonical_root; run update from the service checkout"
}
print_status() {
local relation ahead n local_v remote_v head receipt='' channel target target_note=''
require_checkout; fetch_main
channel="$(configured_channel)"
target="$(update_git_resolve_target "$ROOT" "$channel")" || fail "could not resolve the $channel channel target"
read -r relation ahead n < <(read_relation "$target") || fail "could not compare HEAD with $target"
target_note="$(update_channel_note "$channel" "$target" "$UPDATE_TARGET_FALLBACK")"
local_v="$(current_version)"; remote_v="$(remote_version "$target")"; head="$(git -C "$ROOT" rev-parse HEAD)"
printf 'channel: %s%s\n' "$channel" "$target_note"
if [ "$relation" = ahead ]; then
printf 'local main is ahead of %s by %s commit%s; refusing to deploy unpushed code.\n' "$target" "$ahead" "$([ "$ahead" = 1 ] || printf s)"
printf 'run: mso update reconcile # preserves current HEAD on a rescue branch first\n'
return
fi
if [ "$relation" = diverged ]; then
printf 'local main has diverged from %s (ahead %s, behind %s); refusing update.\n' "$target" "$ahead" "$n"
printf 'run: mso update reconcile # preserves current HEAD on a rescue branch first\n'
return
fi
if [ "$n" -gt 0 ]; then
if [ -n "$local_v" ] && [ "$local_v" = "$remote_v" ]; then
printf 'update available: %s new commit%s on mso CLI %s\n' "$n" "$([ "$n" = 1 ] || printf s)" "$local_v"
else
printf 'update available: mso CLI %s -> %s (%s commit%s)\n' "${local_v:-unknown}" "${remote_v:-newer}" "$n" "$([ "$n" = 1 ] || printf s)"
fi
git -C "$ROOT" log --format=' %h %s' -5 "HEAD..$target"
printf 'run: mso update\n'
return
fi
if service_is_active; then
local running_sha head_short
require_service_checkout
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 is up to date (CLI %s, build %s)\n' "${local_v:-unknown}" "$head_short"
fi
return
fi
init_update_state
if [ -e "$DEPLOY_RECEIPT" ] || [ -L "$DEPLOY_RECEIPT" ]; then receipt="$(read_receipt)"; fi
if [ "$receipt" != "$head" ] || update_gateway_restore_pending; then
printf 'source is current at %s, but offline deployment verification/restart is pending. run: mso update\n' "${head:0:7}"
else
printf 'mso is up to date (CLI %s, build %s)\n' "${local_v:-unknown}" "${head:0:7}"
fi
}
reconcile_checkout() {
local relation ahead behind rescue stamp head
require_checkout
fetch_main
read -r relation ahead behind < <(update_git_relation "$ROOT") || fail "could not compare HEAD with origin/main"
case "$relation" in
exact)
printf 'checkout already matches origin/main at %s\n' "$(git -C "$ROOT" rev-parse --short HEAD)"
return 0
;;
behind)
git -C "$ROOT" merge --ff-only origin/main >/dev/null \
|| fail "could not fast-forward local main to origin/main"
printf 'checkout fast-forwarded to origin/main at %s\n' "$(git -C "$ROOT" rev-parse --short HEAD)"
printf 'run: mso update\n'
return 0
;;
ahead|diverged)
stamp="$(date -u +%Y%m%dT%H%M%SZ)"
rescue="rescue/mso-update-$stamp"
head="$(git -C "$ROOT" rev-parse HEAD)"
git -C "$ROOT" branch "$rescue" "$head" \
|| fail "could not preserve local HEAD on a rescue branch"
git -C "$ROOT" reset --hard origin/main >/dev/null \
|| fail "rescue branch $rescue was created, but main could not be reset to origin/main"
read -r relation ahead behind < <(update_git_relation "$ROOT") || fail "could not verify reconciled checkout"
[ "$relation" = exact ] \
|| fail "rescue branch $rescue preserved the old HEAD, but checkout still does not match origin/main"
printf 'preserved previous local HEAD %s on %s\n' "${head:0:7}" "$rescue"
printf 'checkout now matches origin/main at %s\n' "$(git -C "$ROOT" rev-parse --short HEAD)"
printf 'run: mso update\n'
return 0
;;
*) fail "unknown Git authority state" ;;
esac
}
notice() {
local dir stamp now last=0 relation ahead n local_v remote_v
git_root || return 0
[ "$(git -C "$ROOT" branch --show-current 2>/dev/null || true)" = main ] || return 0
dir="$(mso_private_state_dir "$NOTICE_DIR")" || return 0; stamp="$dir/last-fetch"; now="$(date +%s)"
if [ -s "$stamp" ] && mso_private_state_validate_file "$stamp" >/dev/null 2>&1; then last="$(cat "$stamp" 2>/dev/null || printf 0)"; fi
if ! [[ "$last" =~ ^[0-9]+$ ]] || [ $((now-last)) -ge 21600 ]; then
printf '%s\n' "$now" | mso_private_state_atomic_write "$stamp" >/dev/null 2>&1 || true
(cd "$ROOT" && nohup bash -c 'source "$1/scripts/lib/update-remote-authority.sh"; update_git_fetch_origin "$1" main --no-write-fetch-head' _ "$ROOT" >/dev/null 2>&1 </dev/null &) || true
fi
read -r relation ahead n < <(update_git_relation "$ROOT") || return 0
if [ "$relation" = ahead ] || [ "$relation" = diverged ]; then
printf 'MSO update refused: local main is %s origin/main (ahead %s, behind %s). Run: mso update reconcile\n' \
"$relation" "$ahead" "$n" >&2
return 0
fi
if [ "$n" -gt 0 ]; then
local_v="$(current_version)"; remote_v="$(remote_version)"
if [ -n "$local_v" ] && [ "$local_v" = "$remote_v" ]; then
printf 'MSO update available: %s new commit%s on CLI %s. Run: mso update\n' \
"$n" "$([ "$n" = 1 ] || printf s)" "$local_v" >&2
else
printf 'MSO update available: CLI %s -> %s (%s commit%s). Run: mso update\n' \
"${local_v:-current}" "${remote_v:-newer}" "$n" "$([ "$n" = 1 ] || printf s)" >&2
fi
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() {
local rebuild_only="$1" n head receipt='' channel target
require_checkout
service_is_active && fail "mso.service became active while waiting for the offline update lock; rerun mso update"
init_update_state
if [ "$rebuild_only" != 1 ]; then
local relation ahead
channel="$(configured_channel)"
fetch_main
target="$(update_git_resolve_target "$ROOT" "$channel")" || fail "could not resolve the $channel channel target"
read -r relation ahead n < <(read_relation "$target") || fail "could not compare HEAD with $target"
case "$relation" in
exact) ;;
behind)
# A fast-forward only. A release tag that is not reachable from HEAD means
# the checkout left that release line; reconciling is a human decision.
git -C "$ROOT" merge-base --is-ancestor HEAD "$target" \
|| fail "HEAD is not an ancestor of $target; run: mso update reconcile"
git -C "$ROOT" merge --ff-only "$target" || fail "cannot fast-forward to $target" ;;
ahead) fail "local main is ahead of $target by $ahead commit(s); run: mso update reconcile" ;;
diverged) fail "local main has diverged from $target (ahead $ahead, behind $n); run: mso update reconcile" ;;
*) fail "unknown Git authority state" ;;
esac
read -r relation ahead n < <(read_relation "$target") || fail "could not re-check $target after fast-forward"
[ "$relation" = exact ] || fail "checkout does not exactly match $target after update; refusing deployment"
fi
head="$(git -C "$ROOT" rev-parse HEAD)"
if [ -e "$DEPLOY_RECEIPT" ] || [ -L "$DEPLOY_RECEIPT" ]; then receipt="$(read_receipt)"; fi
if [ "$rebuild_only" != 1 ] && [ "$receipt" = "$head" ] && ! update_gateway_restore_pending; then
printf 'MSO is already up to date and the offline deployment receipt matches.\n'
return 0
fi
# 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"
# 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_receipt
runtime_exclusion_release
update_gateway_restore_all
if update_gateway_restore_pending; then fail "gateway runtime restore inventory remained after restore"; fi
printf 'updated to %s. No system service was active; run: mso web\n' "$(git -C "$ROOT" rev-parse --short HEAD)"
}
offline_build() {
init_update_state
update_with_lock offline_build_locked "$1"
}
service_source_matches_runtime() {
local relation ahead behind head running_sha channel target
channel="$(configured_channel)"
fetch_main
target="$(update_git_resolve_target "$ROOT" "$channel")" || fail "could not resolve the $channel channel target"
read -r relation ahead behind < <(read_relation "$target") || fail "could not compare HEAD with $target"
[ "$relation" = exact ] || return 1
head="$(git -C "$ROOT" rev-parse HEAD)"
running_sha="$(service_build_sha 2>/dev/null || true)"
[ -n "$running_sha" ] && [[ "$head" = "$running_sha"* ]]
}
update_unit_active() {
local state
state="$(systemctl --user show -p ActiveState --value mso-self-update.service 2>/dev/null || true)"
case "$state" in
activating|active|reloading|deactivating) return 0 ;;
*) return 1 ;;
esac
}
update_stage() {
[ -f "$LOG" ] || return 0
sed -n 's/^\[[^]]*\] == / • /p' "$LOG" | tail -1
}
wait_for_service_update() {
local last='' stage='' loops=0 max_loops=1800
printf 'Updating MSO…\n'
while update_unit_active; do
stage="$(update_stage)"
if [ -n "$stage" ] && [ "$stage" != "$last" ]; then
printf '%s\n' "$stage"
last="$stage"
fi
sleep 1
loops=$((loops + 1))
[ "$loops" -lt "$max_loops" ] || fail "update is still running after 30 minutes; inspect: mso update log"
done
if ! grep -qx 'UPDATE OK' "$LOG" 2>/dev/null; then
tail -n 40 "$LOG" 2>/dev/null || true
fail "update did not finish successfully; inspect: mso update log"
fi
local head running version
head="$(git -C "$ROOT" rev-parse HEAD)"
running="$(service_build_sha 5 2>/dev/null || true)"
version="$(current_version)"
if [ -n "$running" ] && [[ "$head" = "$running"* ]]; then
printf '✓ MSO %s is ready (%s)\n' "${version:-unknown}" "${head:0:7}"
else
printf '✓ update finished; verifying runtime may take a moment. Check: mso update status\n'
fi
}
run_update() {
local rebuild_only="$1" arg="" channel
require_checkout
channel="$(configured_channel)"
[ "$rebuild_only" != 1 ] || arg="--rebuild-only"
# A manual run is the operator's answer to the unattended pause. Clear the streak
# BEFORE handing off, because the transient unit replaces this process tree on
# success — and because the gate's own refusal text tells the operator to do this.
clear_automation_pause
if service_is_active; then
require_service_checkout
if [ "$rebuild_only" != 1 ] && service_source_matches_runtime; then
printf 'mso %s is already up to date (%s); no rebuild needed.\n' "$(current_version)" "$(git -C "$ROOT" rev-parse --short HEAD)"
return 0
fi
if command -v systemd-run >/dev/null 2>&1 && systemctl --user show-environment >/dev/null 2>&1; then
mkdir -p "$(dirname "$LOG")"; chmod 700 "$(dirname "$LOG")" 2>/dev/null || true
if update_unit_active; then
printf 'an MSO update is already running.\n'
else
# The channel is the stored enum, never a ref: self-update.sh resolves the
# actual target and re-validates it at the point of use.
systemd-run --user --collect --unit=mso-self-update --property=TimeoutStartSec=3600 \
"--property=WorkingDirectory=$ROOT" "--setenv=MSO_UPDATE_LOG=$LOG" /bin/bash "$ROOT/scripts/mso-service-update" \
$arg "--channel=$channel" >/dev/null
fi
if [ -t 1 ]; then
wait_for_service_update
else
printf 'update started safely outside mso.service. Follow: mso update log\n'
fi
else
/bin/bash "$ROOT/scripts/mso-service-update" $arg
tail -n 30 "$LOG" 2>/dev/null || true
fi
else offline_build "$rebuild_only"; fi
}
# Unattended-update settings, from the SAME authority the Settings toggle and the
# nightly timer use. Skipped (with one neutral line) when this checkout predates the
# automation module, so `mso update status` stays useful in older fixtures/installs.
print_automation() {
local module="$ROOT/scripts/mso-update-automation.ts"
if [ -f "$module" ] && command -v bun >/dev/null 2>&1; then
bun "$module" status --brief 2>/dev/null || printf 'automatic updates state unavailable\n'
else
printf 'automatic updates not configured in this checkout\n'
fi
}
case "${1:-run}" in
notice) notice ;;
status|check) print_status; print_automation ;;
reconcile) reconcile_checkout ;;
log) [ -f "$LOG" ] && tail -n "${2:-80}" "$LOG" || printf 'no update log yet: %s\n' "$LOG" ;;
run) case "${2-}" in
"" ) run_update 0 ;;
--rebuild|--rebuild-only) run_update 1 ;;
*) fail "usage: mso update [--rebuild] | status | reconcile | log | --auto on|off | --channel stable|main" ;;
esac ;;
--rebuild|--rebuild-only) run_update 1 ;;
*) fail "usage: mso update [--rebuild] | status | reconcile | log | --auto on|off | --channel stable|main" ;;
esac