@zerwiz/ymir 0.1.4 → 0.1.7

package/scripts/electron.sh

@@ -0,0 +1,269 @@
+#!/usr/bin/env bash
+# electron.sh — the Ymir desktop shell (Hlidskjalf + Smiðja) in Electron.
+# Raises the web stack, then opens the native window(s). Galdr-style TOON.
+#
+# Hlidskjalf and Smiðja are separate desktop apps (own app-id, .desktop, icon)
+# so they never stack in the taskbar. `--both` starts both processes.
+#
+# Usage:
+#   electron.sh [start] [--no-install]        # launch the desktop app
+#   electron.sh start --view hlidskjalf|smidja
+#   electron.sh start --both                  # both apps, separate processes
+#   electron.sh stop
+#   electron.sh status
+#   electron.sh --version
+set -u
+
+# --- portability shim: bin/ymir-platform.sh --------------------------------
+if [ -z "${YMIR_PLATFORM_LOADED:-}" ]; then
+  _ymir_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+  for _ymir_c in "$(dirname "$_ymir_dir")/bin/ymir-platform.sh" "$_ymir_dir/bin/ymir-platform.sh"; do
+    [ -r "$_ymir_c" ] && { . "$_ymir_c"; YMIR_PLATFORM_LOADED=1; break; }
+  done
+  unset _ymir_dir _ymir_c
+fi
+
+VERSION="1.1.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# The roots that live OUTSIDE the code tree: this machine's records and the
+# runtime state belong to the home the operator chose at installation, never in
+# the tree — a packaged install replaces its tree on upgrade (Rule 04).
+if [ -z "${YMIR_HOARD_LIB_LOADED:-}" ]; then
+  _yr="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  for _yc in "$_yr/hoard-lib.sh" "$(dirname "$_yr")/bin/hoard-lib.sh"; do
+    [ -r "$_yc" ] && { . "$_yc"; YMIR_HOARD_LIB_LOADED=1; break; }
+  done
+  unset _yr _yc
+fi
+hoard_state_dir YMIR_STATE_DIR
+hoard_data_dir YMIR_DATA_DIR
+APP="$ROOT/apps/hlidskjalf"
+Odrerir_app="$ROOT/apps/odrerir"
+NO_INSTALL=0
+VIEW="${YMIR_DESKTOP_VIEW:-hlidskjalf}"
+VIEWS=(hlidskjalf smidja odrerir)
+
+case "${1-}" in -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;; -h|--help|"") sed -n '2,15p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; esac
+ACTION="${1:-start}"; shift || true
+while [ $# -gt 0 ]; do case "$1" in
+  --no-install) NO_INSTALL=1; shift ;;
+  --view) VIEW=${2-hlidskjalf}; shift 2 ;;
+  --both) VIEW=both; shift ;;
+  *) shift ;;
+esac; done
+
+pid_file() { case "$1" in smidja) printf '%s/state/electron-smidja.pid' "$ROOT" ;; odrerir) printf '%s/state/electron-odrerir.pid' "$ROOT" ;; *) printf '%s/state/electron.pid' "$ROOT" ;; esac; }
+log_file() { case "$1" in smidja) printf '%s/state/electron-smidja.log' "$ROOT" ;; odrerir) printf '%s/state/electron-odrerir.log' "$ROOT" ;; *) printf '%s/state/electron.log' "$ROOT" ;; esac; }
+
+# The `.bin/electron` shim is a node script that SPAWNS the real Electron, so its
+# pid (`$!`) is not the app. Track Electron by its own command line instead — the
+# per-view user-data-dir is a unique, stable identity — exactly as the Nornir
+# scheduler identifies itself. Without this, a stale/reused pid makes is_running
+# false while Electron is alive, and a second app launches on top of the first.
+view_mark() { case "$1" in smidja) printf '%s' 'ymir-smidja' ;; odrerir) printf '%s' 'ymir-odrerir' ;; *) printf '%s' 'ymir-hlidskjalf' ;; esac; }
+view_pids() {  # all live Electron pids for a view
+  local mark; mark="$(view_mark "$1")"
+  pgrep -f "electron/dist/electron.*--user-data-dir=.*${mark}" 2>/dev/null || true
+}
+# An integrated GPU backs its graphics memory with system RAM: a small VRAM
+# carve-out plus a large shared aperture (GTT). When a local model is served
+# on that same iGPU it can hold several GiB of GTT, and the amdgpu driver then
+# fails command submissions for the desktop's GPU process — which Electron
+# turns into a NULL dereference, killing the GPU process while the window
+# survives. These are dashboards, not 3D, so software rendering costs nothing.
+IGPU_VRAM_SMALL_MIB="${YMIR_IGPU_VRAM_SMALL_MIB:-2048}"
+igpu_vram_small() {
+  local d total
+  for d in /sys/class/drm/card*/device; do
+    [ -r "$d/mem_info_vram_total" ] || continue
+    total=$(( $(cat "$d/mem_info_vram_total" 2>/dev/null || echo 0) / 1048576 ))
+    [ "$total" -gt 0 ] && [ "$total" -lt "$IGPU_VRAM_SMALL_MIB" ] && return 0
+  done
+  return 1
+}
+
+real_electron() { printf '%s' "$APP/node_modules/electron/dist/electron"; }
+is_running() {
+  local pids; pids="$(view_pids "$1")"
+  [ -n "$pids" ]
+}
+pid_of() {
+  # Prefer the recorded pid when it is one of the live Electron pids; else the first.
+  local rec pids; pids="$(view_pids "$1")"
+  [ -n "$pids" ] || { printf '0'; return; }
+  rec="$(tr -d '[:space:]' <"$(pid_file "$1")" 2>/dev/null || true)"
+  if [ -n "$rec" ] && printf '%s\n' "$pids" | grep -qx "$rec"; then printf '%s' "$rec"; return; fi
+  printf '%s' "$(printf '%s\n' "$pids" | head -1)"
+}
+
+stop_view() {  # stop ONE view's pids - and only that view's
+  local v="$1" pids
+  pids="$(view_pids "$v")"
+  if [ -z "$pids" ]; then
+    printf 'electron: %s already stopped\n' "$v"
+    rm -f "$(pid_file "$v")"
+    return 0
+  fi
+  local list; list="$(printf '%s' "$pids" | tr '\n' ',')"
+  printf '%s\n' "$pids" | xargs -r kill 2>/dev/null || true
+  sleep 0.5
+  local left; left="$(view_pids "$v")"
+  [ -z "$left" ] || printf '%s\n' "$left" | xargs -r kill -KILL 2>/dev/null || true
+  rm -f "$(pid_file "$v")"
+  printf 'electron: stopped %s pid(s)=%s\n' "$v" "${list%,}"
+}
+
+case "$ACTION" in
+  status)
+    printf 'electron[%s]{view,state,pid}:\n' "${#VIEWS[@]}"
+    for v in "${VIEWS[@]}"; do
+      if is_running "$v"; then printf '  "%s","up",%s\n' "$v" "$(pid_of "$v")"; else printf '  "%s","down",0\n' "$v"; fi
+    done
+    exit 0 ;;
+  stop)
+    # ONLY the view asked for. Walking every view here is why `stop --view odrerir`
+    # used to take the smithy's window down with it.
+    if [ "$VIEW" = both ]; then
+      for v in "${VIEWS[@]}"; do stop_view "$v"; done
+    else
+      stop_view "$VIEW"
+    fi
+    printf 'electron: stopped\n'
+    exit 0 ;;
+  start|hlidskjalf|smidja|odrerir) [ "$ACTION" = smidja ] && VIEW=smidja; [ "$ACTION" = odrerir ] && VIEW=odrerir ;;
+  *) printf 'error: unknown action %s\nhelp: electron.sh [start|stop|status]\n' "$ACTION" >&2; exit 2 ;;
+esac
+
+command -v npm >/dev/null 2>&1 || { printf 'error: npm not found\nhelp: install node/npm to run the desktop shell\n' >&2; exit 1; }
+mkdir -p "$YMIR_STATE_DIR"
+
+if [ ! -x "$APP/node_modules/.bin/electron" ]; then
+  if [ "$NO_INSTALL" = 1 ]; then
+    printf 'error: electron not installed in %s\nhelp: (cd apps/hlidskjalf && npm install)\n' "$APP" >&2; exit 1
+  fi
+  printf 'electron: installing dependencies (first run)…\n' >&2
+  ( cd "$APP" && npm install ) >/dev/null 2>&1 || { printf 'error: npm install failed — see apps/hlidskjalf\n' >&2; exit 1; }
+fi
+
+# npm 11+ gates postinstall scripts (allowScripts), so Electron's binary is
+# often never downloaded even though the package installed. Heal that here:
+# run the package's own postinstall, and if it still yields no binary, extract
+# from the already-cached zip and write path.txt (what the postinstall does).
+ensure_electron_binary() {
+  local bin="$APP/node_modules/electron/dist/electron"
+  [ -x "$bin" ] && return 0
+  [ -d "$APP/node_modules/electron" ] || return 0   # nothing installed yet
+  if [ -f "$APP/node_modules/electron/install.js" ]; then
+    ( cd "$APP" && node node_modules/electron/install.js ) >/dev/null 2>&1 || true
+  fi
+  [ -x "$bin" ] && return 0
+  # Fall back to the download cache, which the postinstall populated.
+  local zip
+  zip="$(ls "$HOME"/.cache/electron/*/electron-v*-linux-*.zip 2>/dev/null | head -1)"
+  if [ -n "$zip" ] && command -v unzip >/dev/null 2>&1; then
+    mkdir -p "$APP/node_modules/electron/dist"
+    unzip -q -o "$zip" -d "$APP/node_modules/electron/dist" >/dev/null 2>&1 && \
+      printf 'electron' >"$APP/node_modules/electron/path.txt"
+  fi
+  [ -x "$bin" ] && return 0
+  return 1
+}
+
+if ! ensure_electron_binary; then
+  printf 'error: the Electron binary is missing (the package installed but its postinstall was blocked)\nhelp: cd apps/hlidskjalf && node node_modules/electron/install.js\nhelp: if npm blocks install scripts, run: npm install --foreground-scripts\n' >&2
+  exit 1
+fi
+
+app_dir() { case "$1" in odrerir) printf '%s' "$Odrerir_app" ;; *) printf '%s' "$APP" ;; esac; }
+view_host() { case "$1" in smidja) printf '%s' 'http://127.0.0.1:8437/' ;; odrerir) printf '%s' 'http://127.0.0.1:4322/' ;; *) printf '%s' 'http://127.0.0.1:3888/' ;; esac; }
+
+service_up() { curl -s -o /dev/null --max-time 3 "$1" 2>/dev/null; }
+wait_for_service() {
+  local u="$1" i
+  for i in $(seq 1 120); do service_up "$u" && return 0; sleep 0.5; done
+  return 1
+}
+# Does the compositor hold a window of this class at all? A process with no window
+# cannot be focused, and focusing nothing is exactly the silence a click must not get.
+window_present() {
+  command -v hyprctl >/dev/null 2>&1 || return 0   # no compositor to ask: assume yes
+  hyprctl clients 2>/dev/null | grep -qi "$1"
+}
+
+start_one() {
+  local v="$1" f l
+  f="$(pid_file "$v")"; l="$(log_file "$v")"
+  # THE SYSTEM FIRST. A shell whose backing service is down draws an empty window,
+  # and a window that never mapped cannot be focused. Clicking an icon must raise
+  # THE SYSTEM, so the service is converged before the window is judged.
+  local host; host="$(view_host "$v")"
+  if ! service_up "$host"; then
+    printf 'electron: %s has no service at %s — raising the system\n' "$v" "$host" >&2
+    ( nohup bash "$ROOT/scripts/start.sh" >/dev/null 2>&1 </dev/null & )
+    if ! wait_for_service "$host"; then
+      printf 'electron: %s still does not answer at %s — see $YMIR_STATE_DIR/\n' "$v" "$host" >&2
+    fi
+    # A process that lived through the outage is windowless; it must be reborn.
+    if is_running "$v"; then stop_view "$v"; fi
+  fi
+  if is_running "$v"; then
+    # A bound key must RAISE the app, never report that it is already up. The
+    # window lives on its own numbered desktop by design, so "nothing happens"
+    # is exactly what a click must not do. focuswindow also switches desktops.
+    local cls state=already-up
+    cls="$(view_mark "$v")"   # the window class, from the one place that defines it
+    if command -v hyprctl >/dev/null 2>&1; then
+      # Omarchy configures Hyprland in Lua, so `hyprctl dispatch` evaluates the
+      # remainder as a Lua expression — the classic `focuswindow class:...`
+      # string form is a syntax error there. This is the working idiom.
+      hyprctl dispatch "hl.dsp.focus({window=\"class:^${cls}\$\"})" >/dev/null 2>&1 && state=raised
+    fi
+    # A process whose window is gone cannot be focused — reborn, not silent.
+    if [ "$state" = already-up ] && ! window_present "$cls"; then
+      printf 'electron: %s is running without a window — restarting it\n' "$v" >&2
+      stop_view "$v"
+    else
+      printf 'electron[1]{view,state,pid}:\n  "%s","%s",%s\n' "$v" "$state" "$(pid_of "$v")"
+      return 0
+    fi
+  fi
+  # Launch the REAL Electron binary, not the .bin node shim, so the recorded pid
+  # is the app itself (the shim spawns and would leave a stale/incorrect pid).
+  local bin; bin="$(real_electron)"
+  local -a extra=()
+  # GPU safety — see igpu_vram_small() above for why this exists.
+  #   YMIR_DESKTOP_DISABLE_GPU=1  force software rendering
+  #   YMIR_DESKTOP_DISABLE_GPU=0  force the GPU path
+  #   unset (auto)                decide from the device's VRAM carve-out
+  case "${YMIR_DESKTOP_DISABLE_GPU:-auto}" in
+    1|true|yes) extra+=(--disable-gpu --disable-gpu-compositing) ;;
+    0|false|no) : ;;
+    *)
+      if [ "$(ymir_os 2>/dev/null)" = linux ] && igpu_vram_small; then
+        extra+=(--disable-gpu --disable-gpu-compositing)
+      fi ;;
+  esac
+  nohup env YMIR_DESKTOP_VIEW="$v" "$(real_electron)" "$(app_dir "$v")" \
+    --user-data-dir="$HOME/.config/$(view_mark "$v")" \
+    "${extra[@]}" >"$l" 2>&1 < /dev/null &
+  echo $! >"$f"
+  # Wait briefly for the real process to appear, so a following call sees it.
+  local i
+  for i in $(seq 1 20); do [ -n "$(view_pids "$v")" ] && break; sleep 0.5; done
+}
+
+if [ "$VIEW" = both ]; then
+  start_one hlidskjalf
+  start_one smidja
+  start_one odrerir
+  sleep 2
+  for v in "${VIEWS[@]}"; do
+    if is_running "$v"; then printf 'electron[1]{view,state,pid,url}:\n  "%s","up",%s,"%s"\n' "$v" "$(pid_of "$v")" "$(view_host "$v")"; else printf 'error: electron %s failed to start; see %s\n' "$v" "${log_file "$v"#"$ROOT"/}" >&2; exit 1; fi
+  done
+else
+  start_one "$VIEW"
+  sleep 2
+  if is_running "$VIEW"; then printf 'electron[1]{view,state,pid,url}:\n  "%s","up",%s,"%s"\n' "$VIEW" "$(pid_of "$VIEW")" "$(view_host "$VIEW")"; else printf 'error: electron failed to start; see %s\n' "${log_file "$VIEW"#"$ROOT"/}" >&2; exit 1; fi
+fi

package/scripts/lower.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# lower.sh — the whole house in one word: the windows first, then the web.
+#
+# The shells are lowered BEFORE the services, so no window is left watching a
+# port that has just gone away. That order is the whole point of owning both
+# lifecycles in one place.
+#
+#   scripts/lower.sh              # every shell + the services
+#   scripts/lower.sh --desktop    # the shells only
+#   scripts/lower.sh --web        # the services only
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+WHAT="all"
+case "${1-}" in
+  --web) WHAT=web ;;
+  --desktop) WHAT=desktop ;;
+  -h|--help|"") sed -n '2,12p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+esac
+
+if [ "$WHAT" != "web" ]; then
+  printf '\n— the windows —\n'
+  if [ -x "$ROOT/bin/sessrumnir.sh" ]; then
+    "$ROOT/bin/sessrumnir.sh" stop || printf 'lower: sessrumnir did not stop cleanly\n' >&2
+  fi
+  "$ROOT/scripts/electron.sh" stop || printf 'lower: electron.sh stop reported errors\n' >&2
+fi
+
+if [ "$WHAT" != "desktop" ]; then
+  printf '\n— the web —\n'
+  "$ROOT/scripts/stop.sh" || printf 'lower: stop.sh reported errors\n' >&2
+fi

package/scripts/raise.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# raise.sh — the whole house in one word: the web AND the windows.
+#
+# scripts/start.sh raises the services; scripts/electron.sh raises the desktop
+# shells. Two lifecycles that never met — which is why "the electrons are not
+# running" was true while 28 processes stood, and why a web restart left the
+# shells pointing at a dead port. This is the pair of hands.
+#
+#   scripts/raise.sh              # services + every desktop shell
+#   scripts/raise.sh --web        # the services only
+#   scripts/raise.sh --desktop    # the shells only
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+WHAT="all"
+case "${1-}" in
+  --web) WHAT=web ;;
+  --desktop) WHAT=desktop ;;
+  -h|--help|"") sed -n '2,12p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+esac
+
+if [ "$WHAT" != "desktop" ]; then
+  printf '\n— the web —\n'
+  "$ROOT/scripts/start.sh" || printf 'raise: start.sh reported errors\n' >&2
+fi
+
+if [ "$WHAT" != "web" ]; then
+  printf '\n— the windows —\n'
+  # Every shell, by name: hlidskjalf is the default view; smidja and odrerir need
+  # their own start; sessrumnir is its own app.
+  "$ROOT/scripts/electron.sh" start || printf 'raise: hlidskjalf failed\n' >&2
+  for v in smidja odrerir; do
+    "$ROOT/scripts/electron.sh" start --view "$v" || printf 'raise: %s failed\n' "$v" >&2
+  done
+  if [ -x "$ROOT/bin/sessrumnir.sh" ]; then
+    "$ROOT/bin/sessrumnir.sh" start || printf 'raise: sessrumnir failed\n' >&2
+  fi
+  printf '\n'
+  "$ROOT/scripts/electron.sh" status
+fi

package/scripts/start.sh

@@ -0,0 +1,217 @@
+#!/usr/bin/env bash
+# ============================================================
+# YMIR — start the Hlidskjalf control plane (dev)
+# Raises the SPA on http://127.0.0.1:3888/
+# Usage: scripts/start.sh [--foreground]
+# ============================================================
+set -euo pipefail
+
+# --- portability shim: bin/ymir-platform.sh --------------------------------
+# One place knows the OS differences (readlink -f, /proc, setsid, stat, nproc).
+if [ -z "${YMIR_PLATFORM_LOADED:-}" ]; then
+  _ymir_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+  for _ymir_c in "$_ymir_dir/ymir-platform.sh" "$(dirname "$_ymir_dir")/bin/ymir-platform.sh"; do
+    [ -r "$_ymir_c" ] && { . "$_ymir_c"; YMIR_PLATFORM_LOADED=1; break; }
+  done
+  unset _ymir_dir _ymir_c
+fi
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+# The operator's settings and secrets live in the home they chose, never in the
+# code tree — a packaged install replaces its tree on upgrade, and a credential
+# must never sit in a tree that ships (Rule 04).
+if [ -z "${YMIR_HOARD_LIB_LOADED:-}" ]; then
+  _yr="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  for _yc in "$_yr/hoard-lib.sh" "$(dirname "$_yr")/bin/hoard-lib.sh"; do
+    [ -r "$_yc" ] && { . "$_yc"; YMIR_HOARD_LIB_LOADED=1; break; }
+  done
+  unset _yr _yc
+fi
+hoard_settings_dir YMIR_SETTINGS_DIR
+hoard_local_env YMIR_ENV_FILE
+hoard_state_dir YMIR_STATE_DIR
+hoard_data_dir YMIR_DATA_DIR
+
+# The roots that live OUTSIDE the code tree: this machine's records and the
+# runtime state belong to the home the operator chose at installation, never in
+# the tree — a packaged install replaces its tree on upgrade (Rule 04).
+APP="$ROOT/apps/hlidskjalf"
+RUN="$ROOT/.run"
+PID_FILE="$RUN/hlidskjalf.pid"
+LOG="$RUN/hlidskjalf.log"
+
+# Load the platform env once (Rule 04): the gate, the Bifrost bridge and Mimir
+# all read their credentials from .env.local — 0600, gitignored, never printed.
+# The bun gate reads process.env, and nothing loaded the file for it, so a
+# credential set by bin/ymir-setup-auth.sh never reached it — and the gate treats
+# an empty GATE_AUTH as "open". Loaded before the ports below so those may be
+# overridden from it too.
+if [ -r "$YMIR_ENV_FILE" ]; then
+  set +eu
+  set -a
+  # shellcheck disable=SC1090,SC1091
+  . "$YMIR_ENV_FILE" || true
+  set +a
+  set -eu
+fi
+
+PORT="${HLIDSKJALF_PORT:-3888}"
+
+mkdir -p "$RUN"
+
+if [[ -f "$PID_FILE" ]] && kill -0 "$(cat "$PID_FILE")" 2>/dev/null; then
+  echo "Hlidskjalf already running (pid $(cat "$PID_FILE")) → http://127.0.0.1:${PORT}/"
+  SPA_UP=1
+else
+  SPA_UP=0
+fi
+
+if [[ ! -d "$APP/node_modules" ]]; then
+  echo "Installing dependencies…"
+  (cd "$APP" && npm install --no-audit --no-fund)
+fi
+
+# NOTE: when the SPA is already up we still raise the API and the services
+# below — the old early exit skipped them, leaving only :3888 listening.
+
+# Raise the gate API (real runtime data) when bun is available. Demo mode works
+# without it; live data needs it.
+API_PORT="${HLIDSKJALF_API_PORT:-3889}"
+# The public hostnames the gate fronts (written by bin/gjallarhorn-expose.sh):
+# without them the gate cannot route a host to its app, and the login page for
+# that app would never be reached.
+[ -r "$YMIR_STATE_DIR/gjallarhorn-hosts.env" ] && . "$YMIR_STATE_DIR/gjallarhorn-hosts.env" && \
+  export SMIDJA_HOST ODRERIR_HOST YMIR_PRIMARY_HOST
+API_PID_FILE="$RUN/hlidskjalf-api.pid"
+API_LOG="$RUN/hlidskjalf-api.log"
+if command -v bun >/dev/null 2>&1; then
+  if [[ -f "$API_PID_FILE" ]] && kill -0 "$(cat "$API_PID_FILE")" 2>/dev/null; then
+    echo "Gate API already running (pid $(cat "$API_PID_FILE")) → http://127.0.0.1:${API_PORT}/api/health"
+  else
+    ymir_detach env PORT="$API_PORT" bun run "$APP/server/index.ts" >"$API_LOG" 2>&1
+    echo $! > "$API_PID_FILE"
+    for _ in $(seq 1 20); do
+      curl -s -o /dev/null "http://127.0.0.1:${API_PORT}/api/health" && break
+      sleep 0.5
+    done
+    echo "Gate API raised (pid $(cat "$API_PID_FILE")) → http://127.0.0.1:${API_PORT}/api/health"
+  fi
+else
+  echo "bun not found — SPA will run; live data disabled (demo mode still works)." >&2
+fi
+
+# Runtime services: the Nornir schedule and the Bifrost model bridge.
+if [ -x "$ROOT/bin/nornir-cron-start.sh" ]; then
+  if "$ROOT/bin/nornir-cron-start.sh" >/dev/null 2>&1; then echo "Nornir cron: started"; else echo "Nornir cron: start failed" >&2; fi
+fi
+if [ -x "$ROOT/bin/bifrost-bridge.sh" ]; then
+  if BROKK_ENV_FILE="$YMIR_ENV_FILE" "$ROOT/bin/bifrost-bridge.sh" --start >/dev/null 2>&1; then echo "Bifrost bridge: up"; else echo "Bifrost bridge: not up (needs OPENCODE_GO_API_KEY)" >&2; fi
+fi
+# The well — Mimirsbrunn (engram) on :4602; the gate API and mimir.sh drink here.
+if [ -x "$ROOT/bin/mimir-bridge.sh" ]; then
+  if "$ROOT/bin/mimir-bridge.sh" --start >/dev/null 2>&1; then echo "Mimir bridge: up"; else echo "Mimir bridge: not up (needs engram)" >&2; fi
+fi
+
+# Smíðja's eye — the Vue trace visualizer (API :8437, UI :8438). Reads the repo's
+# own smidja.db and exposes the Sessions/Trace/Decisions/Stats views behind the
+# Hlidskjalf Sessions gate's "Open visualizer" button.
+VIZ_DIR="$ROOT/.agents/skills/smidja-factory/apps/visualizer"
+VIZ_API_PORT="${SMIDJA_VIZ_API_PORT:-8437}"
+VIZ_UI_PORT="${SMIDJA_VIZ_UI_PORT:-8438}"
+VIZ_API_PID_FILE="$RUN/smidja-viz-api.pid"
+VIZ_UI_PID_FILE="$RUN/smidja-viz-ui.pid"
+SMIDJA_DB_PATH="${SMIDJA_DB:-}"
+# The smithy DB follows the HOME: 0003-private-data-separation moved it to
+# $YMIR_HOME/smidja/smidja.db. Prefer an existing DB there, then an in-repo copy
+# for a checkout that keeps its own; SMIDJA_DB overrides either.
+if [ -z "$SMIDJA_DB_PATH" ]; then
+  for _db in "${YMIR_HOME:-$HOME/Documents/Ymir}/smidja/smidja.db" \
+             "$ROOT/apps/smidja/smidja_data/smidja.db"; do
+    [ -f "$_db" ] && { SMIDJA_DB_PATH="$_db"; break; }
+  done
+  SMIDJA_DB_PATH="${SMIDJA_DB_PATH:-${YMIR_HOME:-$HOME/Documents/Ymir}/smidja/smidja.db}"
+fi
+if command -v bun >/dev/null 2>&1 && [ -d "$VIZ_DIR" ]; then
+  [ -d "$VIZ_DIR/node_modules" ] || (cd "$VIZ_DIR" && bun install >/dev/null 2>&1 || true)
+  # The API serves the UI from ./dist. Without a build it answers the API but
+  # shows "No ./dist build found", so build once when dist is absent.
+  if [ ! -d "$VIZ_DIR/dist" ]; then
+    # `bun run build` runs vue-tsc (typecheck) which may be absent; build with
+    # vite directly first so the UI is produced even without the typechecker.
+    (cd "$VIZ_DIR" && bunx vite build >/dev/null 2>&1) || \
+      (cd "$VIZ_DIR" && bun run build >/dev/null 2>&1) || \
+      echo "Smíðja visualizer UI build failed — run: (cd $VIZ_DIR && bunx vite build)" >&2
+  fi
+  if [ -f "$VIZ_API_PID_FILE" ] && kill -0 "$(cat "$VIZ_API_PID_FILE")" 2>/dev/null; then
+    echo "Smíðja visualizer API already running (pid $(cat "$VIZ_API_PID_FILE")) → http://127.0.0.1:${VIZ_API_PORT}/"
+  else
+    ymir_detach env CMD_DB="$SMIDJA_DB_PATH" PORT="$VIZ_API_PORT" bun run "$VIZ_DIR/server/index.ts" >"$RUN/smidja-viz-api.log" 2>&1
+    echo $! > "$VIZ_API_PID_FILE"
+    for _ in $(seq 1 20); do curl -s -o /dev/null "http://127.0.0.1:${VIZ_API_PORT}/api/health" && break; sleep 0.5; done
+    echo "Smíðja visualizer API raised (pid $(cat "$VIZ_API_PID_FILE")) → http://127.0.0.1:${VIZ_API_PORT}/"
+  fi
+  if [ -f "$VIZ_UI_PID_FILE" ] && kill -0 "$(cat "$VIZ_UI_PID_FILE")" 2>/dev/null; then
+    echo "Smíðja visualizer dev UI already running (pid $(cat "$VIZ_UI_PID_FILE")) → http://127.0.0.1:${VIZ_UI_PORT}/"
+  elif [ "${SMIDJA_VIZ_DEV:-0}" = "1" ]; then
+    # Opt-in Vite dev server for working on the visualizer itself.
+    ymir_detach bash -c "cd '$VIZ_DIR' && exec bunx vite --port ${VIZ_UI_PORT} --strictPort" >"$RUN/smidja-viz-ui.log" 2>&1
+    echo $! > "$VIZ_UI_PID_FILE"
+    for _ in $(seq 1 30); do curl -s -o /dev/null "http://127.0.0.1:${VIZ_UI_PORT}/" && break; sleep 0.5; done
+    echo "Smíðja visualizer dev UI raised (pid $(cat "$VIZ_UI_PID_FILE")) → http://127.0.0.1:${VIZ_UI_PORT}/"
+  else
+    echo "Smíðja visualizer UI: served by the API at http://127.0.0.1:${VIZ_API_PORT}/"
+  fi
+else
+  echo "Smíðja visualizer skipped (needs bun + $VIZ_DIR)." >&2
+fi
+
+# Óðrerir — the Live Hall. Its own Astro board on :4322, the carved planning
+# glass every hall door opens. Raised before the SPA so a window never waits.
+HALL_DIR="$ROOT/apps/odrerir"
+HALL_PORT="${ODRERIR_PORT:-4322}"
+HALL_PID_FILE="$RUN/odrerir.pid"
+HALL_LOG="$RUN/odrerir.log"
+if [ -d "$HALL_DIR" ]; then
+  [ -d "$HALL_DIR/node_modules" ] || (cd "$HALL_DIR" && npm install --no-audit --no-fund >/dev/null 2>&1 || true)
+  if [ -f "$HALL_PID_FILE" ] && kill -0 "$(cat "$HALL_PID_FILE")" 2>/dev/null; then
+    echo "Óðrerir — Live Hall already running (pid $(cat "$HALL_PID_FILE")) → http://127.0.0.1:${HALL_PORT}/"
+  else
+    ymir_detach bash -c "cd '$HALL_DIR' && exec npm run dev -- --port '$HALL_PORT' --host" >"$HALL_LOG" 2>&1
+    echo $! > "$HALL_PID_FILE"
+    for _ in $(seq 1 30); do curl -s -o /dev/null "http://127.0.0.1:${HALL_PORT}/" && break; sleep 0.5; done
+    echo "Óðrerir — Live Hall raised (pid $(cat "$HALL_PID_FILE")) → http://127.0.0.1:${HALL_PORT}/"
+  fi
+else
+  echo "Óðrerir — Live Hall skipped (missing apps/odrerir)." >&2
+fi
+
+cd "$APP"
+
+if [[ "${1:-}" == "--foreground" ]]; then
+  exec npm run dev
+fi
+
+# The SPA is already serving — nothing more for us to raise here.
+if [[ "$SPA_UP" == "1" ]]; then
+  echo "Hlidskjalf SPA already up → http://127.0.0.1:${PORT}/"
+  exit 0
+fi
+
+# New session so we can signal the whole process group on stop.
+ymir_detach npm run dev >"$LOG" 2>&1
+PID=$!
+echo "$PID" > "$PID_FILE"
+
+# Wait for the port to answer (max ~15s).
+for _ in $(seq 1 30); do
+  if curl -s -o /dev/null "http://127.0.0.1:${PORT}/"; then
+    echo "Hlidskjalf raised (pid $PID) → http://127.0.0.1:${PORT}/"
+    echo "Logs: $LOG"
+    exit 0
+  fi
+  sleep 0.5
+done
+
+echo "Hlidskjalf started (pid $PID) but the port did not answer yet — check $LOG" >&2
+exit 1