@zerwiz/ymir 0.1.4 → 0.1.5

package/bin/ymir-invite.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+# ymir-invite — hand someone a way in to your Ymir, and take it back.
+#
+# One operator owns the instance; an invite code is how someone else is let in
+# to try it. Codes are machine state (never in the repo), each with its own
+# ceiling, and registration is closed when no live code exists.
+#
+#   ymir-invite mint [--limit N]   print a new code (default ceiling: 5)
+#   ymir-invite list               every code, and how much of it is spent
+#   ymir-invite revoke <CODE>      take a code back, now
+#   ymir-invite where              where the accounts live on this machine
+#   ymir-invite ensure             mint only if none is live (used by the installer)
+#
+# The accounts themselves are read and written by the gate's own store module,
+# so there is one definition of what an account and an invite are.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+MODULE="$ROOT/apps/hlidskjalf/server/accounts.ts"
+STORE="$ROOT/apps/hlidskjalf/server/accounts.ts" # absolute: one definition of an account, wherever this is run from
+
+die() { printf 'ymir-invite: %s\n' "$1" >&2; exit 1; }
+
+command -v bun >/dev/null 2>&1 || die "bun is required (bin/ymir-install.sh installs it)"
+
+# A tiny bun program per action — the module is the single source of truth.
+accounts() {
+  ( cd "$ROOT/apps/hlidskjalf" && bun -e "$1" )
+}
+
+[ -f "$MODULE" ] || die "the account store module is missing: $MODULE"
+
+action="${1:-}"
+case "$action" in
+  mint)
+    limit=5
+    shift || true
+    while [ $# -gt 0 ]; do
+      case "$1" in
+        --limit) limit="${2:?--limit needs a number}"; shift 2 ;;
+        *) die "unknown option: $1" ;;
+      esac
+    done
+    [[ "$limit" =~ ^[0-9]+$ ]] || die "--limit must be a number"
+    accounts "import { addInvite, STORE } from '$STORE';
+      const i = addInvite($limit);
+      console.log('invite[1]{code,limit,store}:');
+      console.log(\`  \"\${i.code}\",\${i.limit},\"\${STORE}\"\`);
+      console.error(\`\nShare it: it admits \${i.limit} account(s), then it is spent.\`);"
+    ;;
+
+  list)
+    accounts "import { listInvites, listAccounts } from '$STORE';
+      const inv = listInvites(), acc = listAccounts();
+      console.log(\`invites[\${inv.length}]{code,used,limit,state}:\`);
+      for (const i of inv) console.log(\`  \"\${i.code}\",\${i.used},\${i.limit},\"\${i.used >= i.limit ? 'spent' : 'live'}\"\`);
+      console.log(\`accounts[\${acc.length}]{login,created}:\`);
+      for (const a of acc) console.log(\`  \"\${a.login}\",\"\${a.created}\"\`);"
+    ;;
+
+  revoke)
+    code="${2:-}"; [ -n "$code" ] || die "usage: ymir-invite revoke <CODE>"
+    accounts "import { revokeInvite } from '$STORE';
+      const gone = revokeInvite('$code');
+      console.log(\`revoke[1]{code,removed}:\n  \"$code\",\${gone}\`);"
+    ;;
+
+  where)
+    accounts "import { STORE, CONFIG_DIR } from '$STORE';
+      console.log(\`store[1]{path,dir}:\n  \"\${STORE}\",\"\${CONFIG_DIR}\"\`);"
+    ;;
+
+  ensure)
+    # Mint one only when nothing is live — so the installer is idempotent and
+    # never quietly grows a pile of codes.
+    accounts "import { addInvite, invitesOpen, listInvites, STORE } from '$STORE';
+      if (invitesOpen()) {
+        const live = listInvites().filter(i => i.used < i.limit);
+        console.log(\`invite[\${live.length}]{code,used,limit}:\`);
+        for (const i of live) console.log(\`  \"\${i.code}\",\${i.used},\${i.limit}\`);
+      } else {
+        const i = addInvite();
+        console.log('invite[1]{code,limit,store}:');
+        console.log(\`  \"\${i.code}\",\${i.limit},\"\${STORE}\"\`);
+      }"
+    ;;
+
+  ""|-h|--help|help)
+    sed -n '2,20p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+    ;;
+
+  *) die "unknown action: $action (try: mint, list, revoke, where, ensure)" ;;
+esac

package/bin/ymir-isolation.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# ymir-isolation.sh — capability-probed confinement for a single agent command.
+#
+# The layered model (audit §12): the container is the boundary against the rest of
+# a shared host; bwrap is an OPTIONAL innermost scope for one model-generated
+# command; Utgard remains the place for untrusted code. This script never assumes
+# bwrap is usable — it probes, then degrades cleanly.
+#
+# Usage:
+#   ymir-isolation.sh probe
+#   ymir-isolation.sh run <worktree> -- <command...> [--net on|off]
+#   ymir-isolation.sh --version
+#
+# Exit: 0 ok, 1 error, 2 usage, 3 unavailable (no isolating layer; ran anyway).
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=bin/ymir-platform.sh
+. "$SCRIPT_DIR/ymir-platform.sh"
+
+usage() { sed -n '2,15p' "$0" | sed 's/^# \{0,1\}//'; }
+
+CMD="${1-}"; shift || true
+case "$CMD" in
+  -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help|"") usage; exit 0 ;;
+esac
+
+case "$CMD" in
+  probe)
+    layers="$(ymir_isolation_layers)"
+    in_ctr="$(ymir_in_container && echo yes || echo no)"
+    bwrap_ok="$(ymir_bwrap_available && echo yes || echo no)"
+    bwrap_bin="$(command -v bwrap 2>/dev/null || echo -)"
+    printf 'isolation[1]{layers,in_container,bwrap_binary,bwrap_usable}:\n'
+    printf '  "%s","%s","%s","%s"\n' "$layers" "$in_ctr" "$bwrap_bin" "$bwrap_ok"
+    if [ "$bwrap_ok" = no ] && [ "$bwrap_bin" != "-" ]; then
+      printf 'note[1]: bwrap is installed but cannot create a namespace here.\n'
+      printf '  A rootless/Hardened container (e.g. a Quadlet) denies nested user namespaces;\n'
+      printf '  keep the container as the boundary, or opt the container in (see deploy/README.md).\n'
+    elif [ "$bwrap_bin" = "-" ]; then
+      printf 'note[1]: bwrap not installed (Fedora: sudo dnf install bubblewrap).\n'
+    fi
+    ;;
+
+  run)
+    WT=""; NET="off"
+    while [ $# -gt 0 ]; do
+      case "$1" in
+        --) shift; break ;;
+        --net) NET="${2-off}"; shift 2 ;;
+        *) WT=$1; shift ;;
+      esac
+    done
+    [ -n "$WT" ] || { printf 'error: run needs a worktree path\nhelp: bin/ymir-isolation.sh run <worktree> -- <command>\n' >&2; exit 2; }
+    [ -d "$WT" ] || { printf 'error: worktree not found: %s\n' "$WT" >&2; exit 1; }
+    [ "$#" -gt 0 ] || { printf 'error: run needs a command after --\n' >&2; exit 2; }
+    WT="$(cd "$WT" && pwd)"
+
+    if ymir_bwrap_available; then
+      # Bind the read-only system, a writable worktree, a private /tmp, and no
+      # network unless asked. --die-with-parent leaves nothing behind.
+      ARGS=(--die-with-parent --unshare-all)
+      [ "$NET" = on ] && ARGS+=(--share-net)
+      ARGS+=(--proc /proc --dev /dev --tmpfs /tmp --setenv HOME /tmp)
+      for d in /usr /lib /lib64 /bin /sbin /etc; do
+        [ -e "$d" ] && ARGS+=(--ro-bind "$d" "$d")
+      done
+      ARGS+=(--bind "$WT" "$WT" --chdir "$WT" -- bash -lc "$*")
+      exec bwrap "${ARGS[@]}"
+    fi
+
+    # No bwrap: degrade to the isolation already in force (the container), never
+    # pretend the command was confined.
+    if ymir_in_container; then
+      printf 'isolation[1]{layer,status}:\n  "container","running in the container boundary (bwrap unavailable)"\n' >&2
+    else
+      printf 'isolation[1]{layer,status}:\n  "none","UNCONFINED — bwrap unavailable and not in a container"\n' >&2
+    fi
+    ( cd "$WT" && bash -lc "$*" )
+    exit 3
+    ;;
+
+  *)
+    printf 'error: unknown command %s\nhelp: bin/ymir-isolation.sh [probe|run|--version]\n' "$CMD" >&2
+    exit 2 ;;
+esac

package/bin/ymir-migrate.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# ymir-migrate.sh — versioned STRUCTURE migrations for existing Ymir homes.
+#
+#   bin/ymir-migrate.sh status           # which migrations exist / are applied
+#   bin/ymir-migrate.sh apply            # apply everything pending, in order
+#   bin/ymir-migrate.sh apply --dry-run  # show what would run, touch nothing
+#   bin/ymir-migrate.sh --version
+#
+# Each migration is `.agents/migrations/<NNNN>-<name>.sh`, MUST be idempotent,
+# and runs with `bash`. Applied ids are recorded in `state/migrations` (private).
+# `bin/ymir-install.sh` and `bin/brokk-update.sh` call `apply` after an update.
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+YMIR_HOME="${YMIR_HOME:-$HOME/Documents/Ymir}"
+MIG_DIR="$ROOT/.agents/migrations"
+STATE_DIR="${YMIR_STATE_DIR:-$YMIR_HOME/state}"
+APPLIED="$STATE_DIR/migrations"
+
+case "${1-}" in -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help|"") sed -n '2,12p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; esac
+
+ACTION="${1:-status}"; shift || true
+DRY=0
+for a in "$@"; do case "$a" in --dry-run|-n) DRY=1 ;; esac; done
+
+[ -d "$MIG_DIR" ] || { printf 'ymir-migrate[1]{state}:\n  "none","no migrations directory"\n'; exit 0; }
+mkdir -p "$STATE_DIR"; [ -f "$APPLIED" ] || : >"$APPLIED"
+
+is_applied() { grep -qxF "$1" "$APPLIED" 2>/dev/null; }
+desc_of() { sed -n 's/^# *[0-9]\{4\}-[a-z0-9-]* *—* *//p' "$1" | head -1; }
+
+mapfile -t MIGS < <(ls "$MIG_DIR"/[0-9][0-9][0-9][0-9]-*.sh 2>/dev/null | sort)
+
+if [ "$ACTION" = status ]; then
+  printf 'ymir-migrate[%d]{migration,state,description}:\n' "${#MIGS[@]}"
+  for m in "${MIGS[@]}"; do
+    id="$(basename "$m" .sh)"
+    if is_applied "$id"; then st=applied; else st=pending; fi
+    printf '  "%s","%s","%s"\n' "$id" "$st" "$(desc_of "$m")"
+  done
+  exit 0
+fi
+
+[ "$ACTION" = apply ] || { printf 'error: unknown action %s\nhelp: bin/ymir-migrate.sh [status|apply [--dry-run]]\n' "$ACTION" >&2; exit 2; }
+
+ran=0; skipped=0
+for m in "${MIGS[@]}"; do
+  id="$(basename "$m" .sh)"
+  if is_applied "$id"; then skipped=$((skipped+1)); continue; fi
+  printf 'ymir-migrate[1]{apply,migration}:\n  "%s","%s"\n' "$([ "$DRY" = 1 ] && echo dry-run || echo run)" "$id"
+  if [ "$DRY" = 1 ]; then continue; fi
+  if bash "$m"; then
+    printf '%s\n' "$id" >>"$APPLIED"; ran=$((ran+1))
+  else
+    printf 'error: migration %s failed — stopping; fix and re-run\n' "$id" >&2; exit 1
+  fi
+done
+printf 'ymir-migrate[1]{action,applied,pending}:\n  "%s",%s,%s\n' "$([ "$DRY" = 1 ] && echo dry-run || echo apply)" "$ran" "$skipped"

package/bin/ymir-platform.sh

@@ -0,0 +1,348 @@
+#!/usr/bin/env bash
+# ymir-platform.sh — the portability layer.
+#
+# Ymir must run on Linux, macOS and Windows (through WSL2 or MSYS/Git Bash).
+# GNU coreutils are not guaranteed: BSD `readlink` has no `-f`, BSD `stat` uses
+# `-f` not `-c`, macOS `date` has no `%N`, and `nproc`, `setsid`, `flock` and
+# `/proc` do not exist there at all. This file is the ONE place that knows a
+# platform difference; every other script calls these functions.
+#
+# Sourced, never executed:   . "$ROOT/bin/ymir-platform.sh"
+# It defines functions only and has no side effects.
+#
+# Convention: every function is `ymir_*`, prints to stdout, and never exits the
+# caller. A capability that is genuinely absent returns a non-zero status so the
+# caller can decide; a capability with a sane fallback always succeeds.
+
+# ── platform ─────────────────────────────────────────────────────────────────
+
+ymir_os() {  # linux | macos | wsl | msys | unknown
+  case "$(uname -s 2>/dev/null)" in
+    Linux*)
+      if [ -r /proc/version ] && grep -qiE 'microsoft|wsl' /proc/version 2>/dev/null; then
+        printf 'wsl'
+      else
+        printf 'linux'
+      fi ;;
+    Darwin*)               printf 'macos' ;;
+    MINGW*|MSYS*|CYGWIN*)  printf 'msys' ;;
+    *)                     printf 'unknown' ;;
+  esac
+}
+
+ymir_has_gnu() {  # true when GNU-style tool flags are available
+  case "$(ymir_os)" in linux|wsl|msys) return 0 ;; *) return 1 ;; esac
+}
+
+# ── basic tools ──────────────────────────────────────────────────────────────
+
+ymir_nproc() {  # CPU count
+  if command -v nproc >/dev/null 2>&1; then nproc
+  elif command -v sysctl >/dev/null 2>&1 && sysctl -n hw.ncpu >/dev/null 2>&1; then sysctl -n hw.ncpu
+  elif command -v getconf >/dev/null 2>&1; then getconf _NPROCESSORS_ONLN 2>/dev/null || printf '4'
+  else printf '4'; fi
+}
+
+ymir_readlink_f() {  # resolve symlinks; BSD readlink has no -f
+  [ $# -ge 1 ] || return 1
+  local p=$1
+  if readlink -f -- "$p" >/dev/null 2>&1; then readlink -f -- "$p"; return 0; fi
+  # Portable resolution: follow one link at a time, keeping the result absolute.
+  local dir base target hops=0
+  case "$p" in /*) : ;; *) p="$PWD/$p" ;; esac
+  while [ -L "$p" ] && [ "$hops" -lt 40 ]; do
+    hops=$((hops+1))
+    dir=$(dirname "$p"); base=$(basename "$p")
+    target=$(readlink "$p") || break
+    case "$target" in /*) p="$target" ;; *) p="$dir/$target" ;; esac
+  done
+  # normalise . and .. lexically
+  local resolved
+  resolved=$(printf '%s' "$p" | awk -F/ '{
+    n=0; for (i=1;i<=NF;i++) { if ($i==""||$i==".") continue; if ($i=="..") { if (n>0) n--; continue } a[++n]=$i }
+    out=""; for (i=1;i<=n;i++) out=out"/"a[i]; if (out=="") out="/"; print out }')
+  # Mirror GNU -f: every component but the last must exist, or the call fails
+  # and prints nothing. Callers rely on that to detect a dangling link.
+  if [ ! -d "$(dirname "$resolved")" ]; then return 1; fi
+  printf '%s' "$resolved"
+}
+
+ymir_epoch_ns() {  # high-resolution epoch for timing (BSD date has no %N)
+  local s n
+  s=$(date +%s 2>/dev/null) || s=0
+  n=$(date +%N 2>/dev/null)
+  case "$n" in ''|*[!0-9]*) n=000000000 ;; esac
+  printf '%s%s' "$s" "$n"
+}
+
+ymir_realpath_dir() {  # directory of the running script, resolved
+  local src=${1:-${BASH_SOURCE[0]}}
+  dirname "$(ymir_readlink_f "$src" 2>/dev/null || printf '%s' "$src")"
+}
+
+# ── stat: GNU -c vs BSD -f ───────────────────────────────────────────────────
+
+ymir_stat_mtime() {  # epoch seconds
+  if ymir_has_gnu; then stat -c %Y -- "$1" 2>/dev/null
+  else stat -f %m -- "$1" 2>/dev/null; fi
+}
+
+ymir_stat_size() {   # bytes
+  if ymir_has_gnu; then stat -c %s -- "$1" 2>/dev/null
+  else stat -f %z -- "$1" 2>/dev/null; fi
+}
+
+ymir_stat_id() {     # "<device>:<inode>" — identity of a file
+  if ymir_has_gnu; then stat -c '%d:%i' -- "$1" 2>/dev/null
+  else stat -f '%d:%i' -- "$1" 2>/dev/null; fi
+}
+
+ymir_stat_birth() {  # birth/creation time as epoch seconds, or 0 when unknown
+  local b=''
+  if ymir_has_gnu; then
+    b=$(stat -c %W -- "$1" 2>/dev/null)
+  else
+    b=$(stat -f %B -- "$1" 2>/dev/null)   # macOS: %B is birth time
+  fi
+  case "$b" in ''|*[!0-9]*) printf '0' ;; *) printf '%s' "$b" ;; esac
+}
+
+ymir_stat_mode() {   # "file" | "dir" | "link" | "other"
+  local f
+  if ymir_has_gnu; then f=$(stat -c %F -- "$1" 2>/dev/null)
+  else f=$(stat -f %HT -- "$1" 2>/dev/null); fi
+  case "$f" in
+    *directory*)                printf 'dir' ;;
+    *symbolic*|*link*)          printf 'link' ;;
+    *regular*|*"regular file"*) printf 'file' ;;
+    '')                         printf 'other' ;;
+    *)                          printf 'other' ;;
+  esac
+}
+
+# ── processes ────────────────────────────────────────────────────────────────
+
+ymir_pid_alive() {  # 0 when the pid exists
+  [ -n "${1:-}" ] && kill -0 "$1" 2>/dev/null
+}
+
+ymir_pid_cmdline() {  # the command line of a pid, one line; empty when gone
+  local pid=${1:-}
+  [ -n "$pid" ] || return 1
+  if [ -r "/proc/$pid/cmdline" ]; then
+    tr '\0' ' ' <"/proc/$pid/cmdline" 2>/dev/null
+  else
+    ps -o command= -p "$pid" 2>/dev/null     # works on macOS and BSD
+  fi
+}
+
+ymir_pid_matches() {  # 0 when the pid is alive AND its cmdline contains the mark
+  local pid=${1:-} mark=${2:-}
+  ymir_pid_alive "$pid" || return 1
+  [ -n "$mark" ] || return 0
+  ymir_pid_cmdline "$pid" 2>/dev/null | grep -q -- "$mark"
+}
+
+ymir_kill_matching() {  # <pattern> [signal] — signal processes whose cmdline matches
+  local pat=${1:-} sig=${2:-TERM}
+  [ -n "$pat" ] || return 1
+  if command -v pkill >/dev/null 2>&1; then
+    pkill -"$sig" -f -- "$pat" 2>/dev/null || true
+    return 0
+  fi
+  # No pkill (some MSYS/WSL images): ps + kill, never matching our own line.
+  local pids
+  pids=$(ps -eo pid=,args= 2>/dev/null | grep -F -- "$pat" | grep -v -e grep -e ymir_kill_matching | awk '{print $1}')
+  [ -n "$pids" ] && kill -s "$sig" $pids 2>/dev/null || true
+  return 0
+}
+
+ymir_detach() {  # run a command detached from this shell's lifetime
+  # setsid where available (Linux/WSL); MSYS has it; macOS does not.
+  if command -v setsid >/dev/null 2>&1; then
+    setsid "$@" < /dev/null &
+  else
+    nohup "$@" < /dev/null > /dev/null 2>&1 &
+  fi
+  printf '%s' "$!"
+}
+
+# ── locking: flock vs a portable mkdir lock ─────────────────────────────────
+
+ymir_lock() {  # <lockfile> <cmd...> — run cmd under an exclusive lock, or fail
+  local lock=$1; shift
+  if command -v flock >/dev/null 2>&1; then
+    exec 9>"$lock" 2>/dev/null || return 1
+    flock -n 9 || return 1
+    "$@"; local rc=$?
+    exec 9>&- 2>/dev/null || true
+    return $rc
+  fi
+  # Portable fallback: mkdir is atomic on every filesystem we care about.
+  local d="${lock}.d"
+  mkdir "$d" 2>/dev/null || return 1
+  "$@"; local rc=$?
+  rmdir "$d" 2>/dev/null || true
+  return $rc
+}
+
+# ── services: systemd (Linux) vs launchd (macOS) vs nothing ─────────────────
+
+ymir_service_backend() {  # systemd | launchd | none
+  if command -v systemctl >/dev/null 2>&1 && systemctl --user >/dev/null 2>&1; then printf 'systemd'
+  elif command -v launchctl >/dev/null 2>&1; then printf 'launchd'
+  else printf 'none'; fi
+}
+
+ymir_service_active() {  # <name> -> 0 when running
+  case "$(ymir_service_backend)" in
+    systemd) systemctl --user is-active --quiet "$1" 2>/dev/null ;;
+    launchd) launchctl list 2>/dev/null | grep -q -- "$1" ;;
+    *)       return 1 ;;
+  esac
+}
+
+# ── containers: Docker or rootless Podman ───────────────────────────────────
+
+# Which container engine to use. Fedora ships rootless Podman and frequently has
+# no `docker` at all; Debian/Ubuntu usually have Docker. YMIR_CONTAINER_ENGINE
+# forces one. Prints the engine name and returns 0, or returns 1 when none of
+# them can actually be reached.
+ymir_container_engine() {
+  local e
+  for e in ${YMIR_CONTAINER_ENGINE:-} docker podman; do
+    [ -n "$e" ] || continue
+    command -v "$e" >/dev/null 2>&1 || continue
+    # podman answers `info` with no daemon; docker needs one running. Accept either.
+    if "$e" info >/dev/null 2>&1; then printf '%s' "$e"; return 0; fi
+  done
+  return 1
+}
+
+# The engine binary that exists, even if its daemon is not reachable. Useful for
+# diagnostics that want to name the engine rather than run it.
+ymir_container_engine_name() {
+  local e
+  for e in ${YMIR_CONTAINER_ENGINE:-} docker podman; do
+    [ -n "$e" ] || continue
+    command -v "$e" >/dev/null 2>&1 && { printf '%s' "$e"; return 0; }
+  done
+  return 1
+}
+
+# true when SELinux is enforcing (Fedora). A bind mount into a container then
+# needs the :Z relabel, or the container is denied access to the host path.
+ymir_selinux_enforcing() {
+  if [ -r /sys/fs/selinux/enforce ]; then
+    [ "$(cat /sys/fs/selinux/enforce 2>/dev/null)" = 1 ]
+  elif command -v getenforce >/dev/null 2>&1; then
+    [ "$(getenforce 2>/dev/null)" = "Enforcing" ]
+  else
+    return 1
+  fi
+}
+
+# true when the resolved engine is Podman — including when the `docker` binary is
+# really Podman (the podman-docker shim), which names itself in `info`.
+ymir_engine_is_podman() {
+  local e
+  e="$(ymir_container_engine 2>/dev/null || ymir_container_engine_name 2>/dev/null)" || return 1
+  [ -n "$e" ] || return 1
+  [ "$e" = podman ] && return 0
+  "$e" info 2>/dev/null | grep -qi podman
+}
+
+# true when rootless Podman: bind-mount ownership then needs --userns=keep-id so
+# files land owned by the invoking user. Docker (and rootful Podman) do not.
+ymir_rootless_podman() {
+  ymir_engine_is_podman && [ "$(id -u)" -ne 0 ]
+}
+
+# true when Ymir itself is running inside a container (podman or docker).
+ymir_in_container() {
+  [ -e /run/.containerenv ] || [ -e /.dockerenv ] || [ -n "${container:-}" ]
+}
+
+# The `-v` suffix for a bind mount: `:Z` whenever SELinux is enforcing — Docker
+# and Podman both need the relabel there — else empty. Append to `<host>:<ctr>`.
+ymir_volume_suffix() {
+  ymir_selinux_enforcing && printf ':Z'
+}
+
+# ── GPUs: report what exists, without assuming NVIDIA ───────────────────────
+
+ymir_gpu_name() {  # best-effort device name, or empty
+  if command -v nvidia-smi >/dev/null 2>&1; then
+    nvidia-smi --query-gpu=name --format=csv,noheader 2>/dev/null | head -1
+  elif command -v rocm-smi >/dev/null 2>&1; then
+    rocm-smi --showproductname 2>/dev/null | head -2 | tr '\n' ' '
+  elif [ "$(ymir_os)" = macos ]; then
+    printf 'Apple Silicon (unified memory)'
+  else
+    printf ''
+  fi
+}
+
+ymir_gpu_mem_used() {  # MiB in use, or "?" when unknown
+  if command -v nvidia-smi >/dev/null 2>&1; then
+    nvidia-smi --query-gpu=memory.used --format=csv,noheader,nounits 2>/dev/null | head -1 || printf '?'
+  elif command -v rocm-smi >/dev/null 2>&1; then
+    rocm-smi --showmemuse 2>/dev/null | grep -oE '[0-9]+' | head -1 || printf '?'
+  else
+    printf '?'
+  fi
+}
+
+ymir_llama_server() {  # locate a llama-server without assuming a path
+  local c
+  for c in "${LLAMA_SERVER:-}" llama-server; do
+    [ -n "$c" ] || continue
+    if command -v "$c" >/dev/null 2>&1; then command -v "$c"; return 0; fi
+  done
+  for c in /opt/homebrew/bin/llama-server /usr/local/bin/llama-server; do
+    [ -x "$c" ] && { printf '%s' "$c"; return 0; }
+  done
+  return 1
+}
+
+# ── paths ────────────────────────────────────────────────────────────────────
+
+ymir_tmp() {  # a private temporary directory, on every OS
+  local base=${TMPDIR:-${TEMP:-/tmp}}
+  mktemp -d "${base%/}/ymir.XXXXXX" 2>/dev/null || mktemp -d
+}
+
+ymir_expand_tilde() {  # expand a leading ~ in a user-supplied path
+  case "${1:-}" in
+    '~')   printf '%s' "$HOME" ;;
+    '~/'*) printf '%s/%s' "$HOME" "${1#\~/}" ;;
+    *)     printf '%s' "$1" ;;
+  esac
+}
+
+# ── isolation: is bwrap usable here? ─────────────────────────────────────────
+
+# True when bubblewrap can actually create the namespaces it needs. This is a
+# real probe, not a presence check: inside a hardened container (rootless Podman
+# Quadlet), nested user namespaces are often denied and bwrap fails with
+# "Creating new namespace failed: Operation not permitted". Callers must degrade,
+# never assume.
+ymir_bwrap_available() {
+  command -v bwrap >/dev/null 2>&1 || return 1
+  bwrap --unshare-all --die-with-parent --ro-bind / / true >/dev/null 2>&1
+}
+
+# True when Ymir itself is running inside a container (podman or docker).
+ymir_in_container() {
+  [ -e /run/.containerenv ] || [ -e /.dockerenv ] || [ -n "${container:-}" ]
+}
+
+# The isolation layers available here, outermost first. Prints a csv of any of
+# `container,bwrap,none` — the caller picks, never assumes bwrap.
+ymir_isolation_layers() {
+  local out=""
+  ymir_in_container && out="container"
+  if ymir_bwrap_available; then out="${out:+$out,}bwrap"; fi
+  [ -n "$out" ] || out="none"
+  printf '%s' "$out"
+}