@agentikos/omega-os 0.1.0 → 0.19.5

package/bootstrap/lib/common.sh

@@ -7,6 +7,12 @@ STATE_DIR="$OMEGA_HOME/Agentik_Extra/var"
 STATE_FILE="$STATE_DIR/.install-state"
 LOG_FILE="$STATE_DIR/logs/install.log"
 
+# --- user defaults ---
+# The friendly name used when --create-user is given with no explicit value.
+# Chosen because it matches the install dir (~/Omega), is short, neutral, and
+# never collides with a stock Linux/macOS account. (Override on the CLI.)
+OMEGA_DEFAULT_NEW_USER="${OMEGA_DEFAULT_NEW_USER:-omega}"
+
 # --- colours (only when attached to a tty) ---
 if [ -t 1 ]; then
   C_OK=$'\033[32m'; C_ERR=$'\033[31m'; C_INFO=$'\033[36m'; C_DIM=$'\033[2m'; C_RST=$'\033[0m'
@@ -43,7 +49,30 @@ detect_os() {
 # --- step state (idempotent / resumable) ---
 step_done()   { [ -f "$STATE_FILE" ] && grep -qx "$1" "$STATE_FILE"; }
 mark_done()   { mkdir -p "$STATE_DIR"; printf '%s\n' "$1" >> "$STATE_FILE"; }
-reset_state() { rm -f "$STATE_FILE"; }
+reset_state() { rm -f "$STATE_FILE" "$STATE_DIR/.install-version" 2>/dev/null || true; }
+
+# state_version_drift — return 0 (drift) when the state file was written by a
+# different OmegaOS version than the one we're about to run. We track the
+# version that wrote a state file in a sibling marker `$STATE_DIR/.install-version`.
+# When drift is detected we reset state automatically so re-running an upgraded
+# installer actually executes the NEW steps instead of skipping them all as
+# "already done". This was the v0.19.x UX regression: a Mac with an old state
+# file from v0.2.0 was skipping every step on a v0.19.x re-run.
+state_version_drift() {
+  local current="${OMEGA_BUNDLED_VERSION:-}"
+  [ -n "$current" ] || return 1
+  local marker="$STATE_DIR/.install-version"
+  [ -f "$marker" ] || return 0   # state present but no version marker → drift
+  local recorded; recorded="$(cat "$marker" 2>/dev/null || echo '')"
+  [ "$recorded" = "$current" ] && return 1
+  return 0
+}
+record_state_version() {
+  local current="${OMEGA_BUNDLED_VERSION:-}"
+  [ -n "$current" ] || return 0
+  mkdir -p "$STATE_DIR"
+  printf '%s\n' "$current" > "$STATE_DIR/.install-version"
+}
 
 # run_step <name> <function>
 run_step() {
@@ -61,6 +90,132 @@ run_step() {
   fi
 }
 
+# --- user resolution ---------------------------------------------------------
+#
+# The installer is modular about WHICH user it runs as. Three modes, decided
+# from the CLI by install.sh before anything else happens:
+#
+#   1. (default) no flag           — run as the current user; OMEGA_HOME=$HOME/Omega.
+#   2. --user <name>               — re-exec as that existing user.
+#   3. --create-user [<name>]      — create a system user (Linux only), then
+#                                    re-exec as them. Default name: $OMEGA_DEFAULT_NEW_USER.
+#
+# Re-exec is via `sudo -u <user> -H bash <copied-installer>`. We copy the
+# repo into the target user's ~/.cache/omega-installer/ first because the
+# original clone (e.g. /root/OmegaOS) is rarely readable by the target user.
+
+# user_home <name> — print the home directory of a Unix user, or empty if missing.
+user_home() {
+  local name="$1" home
+  if [ "$(uname -s)" = "Darwin" ]; then
+    home="$(dscl . -read "/Users/$name" NFSHomeDirectory 2>/dev/null | awk '{print $2}')"
+  else
+    home="$(getent passwd "$name" 2>/dev/null | cut -d: -f6)"
+  fi
+  printf '%s' "$home"
+}
+
+# ensure_user_exists <name> — create a system user if missing (Linux only).
+# Adds them to the sudo/wheel group so `step_system_deps` can apt/dnf.
+ensure_user_exists() {
+  local name="$1"
+  if id "$name" >/dev/null 2>&1; then
+    info "user '$name' already exists — adopting"
+    return 0
+  fi
+  if [ "$(uname -s)" = "Darwin" ]; then
+    die "creating users on macOS is not supported by this installer — pass --user <existing-user> or install as yourself"
+  fi
+  if [ "$(id -u)" -ne 0 ]; then
+    die "creating user '$name' requires root — re-run with sudo (e.g. \`sudo bash install.sh --create-user $name\`)"
+  fi
+  info "creating system user '$name' (shell=/bin/bash, home=/home/$name)"
+  if ! useradd -m -s /bin/bash "$name" >>"$LOG_FILE" 2>&1; then
+    die "useradd failed for '$name' — see $LOG_FILE"
+  fi
+  if getent group sudo >/dev/null 2>&1; then
+    usermod -aG sudo "$name" >>"$LOG_FILE" 2>&1 || true
+  elif getent group wheel >/dev/null 2>&1; then
+    usermod -aG wheel "$name" >>"$LOG_FILE" 2>&1 || true
+  fi
+  # Passwordless sudo for system-deps step only, scoped to apt/dnf. We
+  # intentionally do NOT grant NOPASSWD on all sudo — that's the operator's
+  # decision later.
+  ok "user '$name' created and granted sudo group membership"
+}
+
+# resolve_target_user — call this from install.sh BEFORE run_step.
+#
+# Inputs (variables set by install.sh argument parsing):
+#   USER_REQUESTED        — "" | a username from --user
+#   CREATE_USER           — 0 | 1 from --create-user
+#   CREATE_USER_NAME      — name to create (defaults to OMEGA_DEFAULT_NEW_USER)
+#   INSTALL_CLEAN_ARGS[]  — reconstructed args without --user/--create-user
+#
+# Effect: either sets OMEGA_USER to the current user (no-op), or
+# `exec`s the installer into the resolved user's shell with INSTALL_CLEAN_ARGS.
+resolve_target_user() {
+  local current; current="$(id -un)"
+  local target=""
+
+  if [ "${CREATE_USER:-0}" = "1" ]; then
+    target="${CREATE_USER_NAME:-$OMEGA_DEFAULT_NEW_USER}"
+    ensure_user_exists "$target"
+  elif [ -n "${USER_REQUESTED:-}" ]; then
+    target="$USER_REQUESTED"
+    if ! id "$target" >/dev/null 2>&1; then
+      die "user '$target' does not exist — either create it first, or use --create-user $target"
+    fi
+  fi
+
+  # Mode 1 — no flag, or flag matches current user: just continue.
+  if [ -z "$target" ] || [ "$target" = "$current" ]; then
+    if [ "$current" = "root" ]; then
+      err "running as root with no user mode chosen — this leaves Omega OS owned by root"
+      err "pick one:"
+      err "    bash install.sh --create-user           # create a new user named '$OMEGA_DEFAULT_NEW_USER'"
+      err "    bash install.sh --create-user <name>    # create with a custom name"
+      err "    bash install.sh --user <existing-name>  # adopt an existing user"
+      die "(if you really want root, set OMEGA_ALLOW_ROOT=1; this is almost never what you want)"
+    fi
+    OMEGA_USER="$current"
+    export OMEGA_USER
+    return 0
+  fi
+
+  # Mode 2/3 — re-exec as `target`. We need to be either root or current target.
+  if [ "$(id -u)" -ne 0 ] && ! have sudo; then
+    die "cannot switch to user '$target' without root or sudo — re-run with sudo"
+  fi
+
+  local thome; thome="$(user_home "$target")"
+  [ -n "$thome" ] || die "could not resolve home directory for user '$target'"
+
+  # Copy installer into the target user's cache so they can definitely read it.
+  local stage="$thome/.cache/omega-installer"
+  info "staging installer for '$target' at $stage"
+  if [ "$(id -u)" -eq 0 ]; then
+    mkdir -p "$stage"
+    cp -R "$REPO_DIR/." "$stage/"
+    chown -R "$target:$target" "$stage" 2>/dev/null \
+      || chown -R "$target" "$stage" 2>/dev/null || true
+  else
+    sudo mkdir -p "$stage"
+    sudo cp -R "$REPO_DIR/." "$stage/"
+    sudo chown -R "$target" "$stage" 2>/dev/null || true
+  fi
+
+  local exec_args=("${INSTALL_CLEAN_ARGS[@]:-}")
+  info "re-executing installer as '$target' (clean args: ${exec_args[*]:-<none>})"
+  if [ "$(id -u)" -eq 0 ]; then
+    exec sudo -u "$target" -H bash "$stage/install.sh" "${exec_args[@]}"
+  else
+    exec sudo -u "$target" -H bash "$stage/install.sh" "${exec_args[@]}"
+  fi
+  # `exec` never returns; if we get here something's wrong.
+  die "exec to user '$target' failed"
+}
+
 # ask <var> <prompt> <default> — respects --non-interactive
 ask() {
   local __var="$1" __prompt="$2" __default="${3:-}" __reply
@@ -71,3 +226,304 @@ ask() {
   read -r -p "$__prompt ${__default:+[$__default] }" __reply || true
   printf -v "$__var" '%s' "${__reply:-$__default}"
 }
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# UX — banner, preflight card, profile picker, step progress, post-install
+# ─────────────────────────────────────────────────────────────────────────────
+
+if [ -t 1 ]; then
+  C_BOLD=$'\033[1m'
+  C_DIM=$'\033[2m'
+  # Claude-Code brand orange (#D97757) in 24-bit truecolor. Every modern
+  # macOS/Linux terminal (iTerm2, Termius, kitty, alacritty, gnome-terminal,
+  # WezTerm) supports truecolor. We expose the legacy C_CYAN/etc names
+  # below for back-compat — the banner + boxes use C_ORANGE.
+  C_ORANGE=$'\033[38;2;217;119;87m'
+  C_CYAN="$C_ORANGE"
+  C_GREEN=$'\033[32m'
+  C_YELLOW=$'\033[33m'
+  C_RED=$'\033[31m'
+  C_MAGENTA=$'\033[35m'
+  C_BLUE=$'\033[34m'
+else
+  # Non-TTY (CI, --non-interactive, pipe) — make every colour var safe
+  # to reference. Without these the install.sh plan-mode block crashes
+  # on `set -u` when running headless.
+  C_BOLD=''; C_DIM=''; C_ORANGE=''; C_CYAN=''; C_GREEN=''; C_YELLOW=''
+  C_RED=''; C_MAGENTA=''; C_BLUE=''
+fi
+
+# --- prompt helpers --------------------------------------------------------
+#
+# prompt_yes_no <question> [default=yes|no]
+#   Read a y/n answer from stdin. Default is "yes" when omitted. Returns 0
+#   for yes, 1 for no. Re-prompts on garbage input (typo-safe). When stdin
+#   is not a TTY (piped/non-interactive), accepts the default silently —
+#   `install.sh` already gates the call with `[ -t 0 ]` so the non-TTY
+#   path is only hit when the call site forgot, in which case "yes" is the
+#   safe assumption (the user opted into the install by running it).
+#
+# This was missing in v0.19.1/0.19.4 and caused a "command not found" abort
+# on the very first install on macOS — the install.sh plan-mode block fell
+# through to `aborted by operator — no changes made` without any work done.
+prompt_yes_no() {
+  local q="$1" default="${2:-yes}" reply hint
+  case "$default" in
+    y|yes|Y|YES) hint="Y/n" ;;
+    n|no|N|NO)   hint="y/N" ;;
+    *)           hint="y/n" ;;
+  esac
+  while :; do
+    # Only print the prompt when stdin is a TTY. Always try to read —
+    # piped input (e.g. `printf 'n\n' | install.sh`) must be honoured.
+    [ -t 0 ] && printf '%s %s[%s]%s ' "$q" "$C_DIM" "$hint" "$C_RST"
+    if ! IFS= read -r reply; then
+      # EOF (no input at all) → fall back to the default.
+      reply=""
+    fi
+    [ -z "$reply" ] && reply="$default"
+    case "$reply" in
+      y|Y|yes|YES|Yes) return 0 ;;
+      n|N|no|NO|No)    return 1 ;;
+      *) printf '  please answer y or n\n' ;;
+    esac
+  done
+}
+
+# Stable wall-clock start time — used to print mm:ss next to each step.
+INSTALL_START_TS="${INSTALL_START_TS:-$(date +%s)}"
+STEP_COUNT="${STEP_COUNT:-0}"
+STEP_TOTAL="${STEP_TOTAL:-0}"
+
+# Read $OMEGA_REPO/omega/Agentik_SSOT/VERSION (single source of truth).
+omega_version() {
+  local f="$OMEGA_REPO/omega/Agentik_SSOT/VERSION"
+  [ -f "$f" ] && cat "$f" 2>/dev/null || echo "?.?.?"
+}
+
+# install_banner — printed once at the very top of install.sh.
+#
+# The G letter (position 4) used to read as a B because row 3 closed the
+# upper-right with `█▀` (looked like the top loop of B) and the bottom row
+# used `████████▀` instead of a clean ` ▀██████▀ ` arc. v0.19.5 makes the
+# G unambiguous: open right side at row 3, classic arc bottom, with the
+# canonical middle hook at row 5. Colour is Claude-Code brand orange.
+install_banner() {
+  local v; v="$(omega_version)"
+  printf '\n'
+  printf '%s  ▄██████▄   ▄▄▄▄███▄▄▄▄      ▄████████    ▄██████▄     ▄████████%s\n' "$C_ORANGE" "$C_RST"
+  printf '%s ███    ███ ▄██▀▀▀███▀▀▀██▄   ███    ███   ███    ███   ███    ███%s\n' "$C_ORANGE" "$C_RST"
+  printf '%s ███    ███ ███   ███   ███   ███    █▀    ███          ███    ███%s\n' "$C_ORANGE" "$C_RST"
+  printf '%s ███    ███ ███   ███   ███  ▄███▄▄▄      ▄███         ▄███▄▄▄▄██▀%s\n' "$C_ORANGE" "$C_RST"
+  printf '%s ███    ███ ███   ███   ███ ▀▀███▀▀▀     ▀▀███ ████▄  ▀▀███▀▀▀▀▀  %s\n' "$C_ORANGE" "$C_RST"
+  printf '%s ███    ███ ███   ███   ███   ███    █▄    ███    ███ ▀███████████%s\n' "$C_ORANGE" "$C_RST"
+  printf '%s ███    ███ ███   ███   ███   ███    ███   ███    ███   ███    ███%s\n' "$C_ORANGE" "$C_RST"
+  printf '%s  ▀██████▀   ▀█   ███   █▀    ██████████    ▀██████▀    ███    ███%s\n' "$C_ORANGE" "$C_RST"
+  printf '\n'
+  printf '   %sOmega OS%s  %sv%s%s  ·  %sagentik-os/OmegaOS%s\n' \
+         "$C_BOLD" "$C_RST" "$C_DIM" "$v" "$C_RST" "$C_DIM" "$C_RST"
+  printf '   %sEvent-sourced, verified-completion agentic operating system.%s\n' \
+         "$C_DIM" "$C_RST"
+  printf '\n'
+}
+
+# preflight_card — print a one-screen detection summary before any step runs.
+# Heuristics only; never blocks. Operator reads it and either accepts or aborts.
+preflight_card() {
+  local cpus mem_gb disk_h disk_pct internet shell_name
+  cpus="$(getconf _NPROCESSORS_ONLN 2>/dev/null || echo "?")"
+  if [ "$(uname -s)" = "Linux" ]; then
+    mem_gb="$(awk '/MemTotal/ {printf "%.1f", $2/1024/1024}' /proc/meminfo 2>/dev/null || echo "?")"
+    disk_h="$(df -h "$HOME" 2>/dev/null | awk 'NR==2 {print $4 " free / " $2}' || echo "?")"
+    disk_pct="$(df -P "$HOME" 2>/dev/null | awk 'NR==2 {gsub("%",""); print $5}' || echo "?")"
+  else
+    mem_gb="$(sysctl -n hw.memsize 2>/dev/null | awk '{printf "%.1f", $1/1024/1024/1024}' || echo "?")"
+    disk_h="$(df -h "$HOME" 2>/dev/null | awk 'NR==2 {print $4 " free / " $2}' || echo "?")"
+    disk_pct="$(df "$HOME" 2>/dev/null | awk 'NR==2 {gsub("%",""); print $5}' || echo "?")"
+  fi
+  shell_name="$(basename "${SHELL:-/bin/sh}")"
+  if curl -sS --max-time 3 -o /dev/null -w '%{http_code}' https://www.google.com 2>/dev/null | grep -q '^[23]'; then
+    internet="${C_GREEN}online${C_RST}"
+  else
+    internet="${C_RED}offline${C_RST}"
+  fi
+
+  local _yes="${C_GREEN}✓${C_RST}"
+  local _no="${C_RED}✗${C_RST}"
+  _have_mark() { have "$1" && printf '%s %s' "$_yes" "$(command -v "$1" | head -1)" || printf '%s missing' "$_no"; }
+
+  printf '   %s──── pre-flight detection ────%s\n' "$C_DIM" "$C_RST"
+  printf '   %sOS%s         %-30s %sPkg manager%s  %s\n'         "$C_DIM" "$C_RST" "$OMEGA_OS"                       "$C_DIM" "$C_RST" "$OMEGA_PKG"
+  printf '   %sShell%s      %-30s %sUser%s         %s\n'          "$C_DIM" "$C_RST" "$shell_name"                     "$C_DIM" "$C_RST" "$OMEGA_USER"
+  printf '   %sCPUs%s       %-30s %sRAM%s          %s GiB\n'      "$C_DIM" "$C_RST" "$cpus"                           "$C_DIM" "$C_RST" "$mem_gb"
+  printf '   %sDisk%s       %-30s %sFull%s         %s%%\n'        "$C_DIM" "$C_RST" "$disk_h"                         "$C_DIM" "$C_RST" "$disk_pct"
+  printf '   %sInternet%s   %-30b %sProfile%s      %s\n'          "$C_DIM" "$C_RST" "$internet"                       "$C_DIM" "$C_RST" "$PROFILE"
+  printf '\n'
+  printf '   %s──── required tools ────%s\n' "$C_DIM" "$C_RST"
+  printf '   git        %s\n'    "$(_have_mark git)"
+  printf '   python3    %s\n'    "$(_have_mark python3)"
+  printf '   tmux       %s\n'    "$(_have_mark tmux)"
+  printf '   sqlite3    %s\n'    "$(_have_mark sqlite3)"
+  printf '   curl       %s\n'    "$(_have_mark curl)"
+  printf '   jq         %s\n'    "$(_have_mark jq)"
+  printf '\n'
+  printf '   %s──── optional (Omega will install or skip)%s\n' "$C_DIM" "$C_RST"
+  printf '   claude     %s   %s(Max OAuth — no API key needed)%s\n' "$(_have_mark claude)"  "$C_DIM" "$C_RST"
+  printf '   uv         %s   %s(Python pkg + venv manager)%s\n'    "$(_have_mark uv)"       "$C_DIM" "$C_RST"
+  printf '   node       %s   %s(MCP servers)%s\n'                  "$(_have_mark node)"     "$C_DIM" "$C_RST"
+  printf '   age        %s   %s(encrypted secrets vault)%s\n'      "$(_have_mark age)"      "$C_DIM" "$C_RST"
+  printf '   gh         %s   %s(GitHub workflow)%s\n'              "$(_have_mark gh)"       "$C_DIM" "$C_RST"
+  printf '\n'
+
+  # Soft block: if disk < 2 GB free, warn loud.
+  local disk_free_kb
+  disk_free_kb="$(df -Pk "$HOME" 2>/dev/null | awk 'NR==2 {print $4}')"
+  if [ -n "$disk_free_kb" ] && [ "$disk_free_kb" -lt 2000000 ]; then
+    printf '   %s! warning:%s less than ~2 GB free in %s — install may run out of space\n' \
+           "$C_YELLOW" "$C_RST" "$HOME"
+    printf '\n'
+  fi
+}
+
+# pick_profile_interactive — whiptail picker when --profile not given.
+# Falls through silently if whiptail is missing or stdin is not a tty.
+pick_profile_interactive() {
+  [ "${NONINTERACTIVE:-0}" = "1" ] && return 0
+  [ -t 0 ] || return 0
+  if [ "$PROFILE_EXPLICIT" = "1" ]; then return 0; fi
+  if ! have whiptail; then return 0; fi
+  local choice
+  choice="$(whiptail --title "Omega OS — install profile" \
+           --menu "Pick the install profile for this machine:" 16 78 5 \
+           "vps"         "Headless 24/7 VPS — daemons + Telegram + autonomous" \
+           "workstation" "Local laptop — interactive, no daemons" \
+           "minimal"     "Engine + CLI only — no MCP, no Telegram, no plugins" \
+           3>&1 1>&2 2>&3)" || return 0
+  [ -n "$choice" ] && PROFILE="$choice"
+}
+
+# step_progress_header <step_name>
+# Wraps run_step. Prints "[N/M] step  ⏱ elapsed".
+step_progress_header() {
+  local name="$1"
+  STEP_COUNT=$((STEP_COUNT + 1))
+  local now elapsed mm ss bar tail
+  now="$(date +%s)"; elapsed=$((now - INSTALL_START_TS))
+  mm=$((elapsed / 60)); ss=$((elapsed % 60))
+  if [ "$STEP_TOTAL" -gt 0 ]; then
+    bar="[$STEP_COUNT/$STEP_TOTAL]"
+  else
+    bar="[$STEP_COUNT]"
+  fi
+  tail="$(printf '%02d:%02d' "$mm" "$ss")"
+  log "${C_BLUE}${bar}${C_RST}  ${C_BOLD}${name}${C_RST}  ${C_DIM}elapsed ${tail}${C_RST}"
+}
+
+# path_setup_user_rc — append an idempotent shellrc block exporting OMEGA_HOME
+# and prepending Agentik_Tools/bin to PATH. Honours --no-path-setup.
+path_setup_user_rc() {
+  if [ "${NO_PATH_SETUP:-0}" = "1" ]; then
+    info "PATH setup skipped (--no-path-setup)"
+    return 0
+  fi
+  local rc
+  case "$(basename "${SHELL:-/bin/sh}")" in
+    zsh)  rc="$HOME/.zshrc" ;;
+    bash) rc="$HOME/.bashrc" ;;
+    fish) rc="$HOME/.config/fish/config.fish" ;;
+    *)    rc="$HOME/.profile" ;;
+  esac
+  # Idempotent: if our marker already exists, just refresh the path inside.
+  local marker="# >>> omega-os >>>"
+  local close="# <<< omega-os <<<"
+  if [ -f "$rc" ] && grep -q "$marker" "$rc" 2>/dev/null; then
+    info "PATH already wired in $rc — skipping"
+    return 0
+  fi
+  mkdir -p "$(dirname "$rc")"
+  if [ "$(basename "$rc")" = "config.fish" ]; then
+    {
+      echo ""
+      echo "$marker"
+      echo "set -gx OMEGA_HOME \"$OMEGA_HOME\""
+      echo "set -gx PATH \"\$OMEGA_HOME/Agentik_Tools/bin\" \$PATH"
+      echo "$close"
+    } >> "$rc"
+  else
+    {
+      echo ""
+      echo "$marker"
+      echo "export OMEGA_HOME=\"$OMEGA_HOME\""
+      echo "export PATH=\"\$OMEGA_HOME/Agentik_Tools/bin:\$PATH\""
+      echo "$close"
+    } >> "$rc"
+  fi
+  ok "PATH wired in $rc — open a new shell or \`source $rc\`"
+}
+
+# post_install_card — beautiful boxed summary printed at the very end.
+# Reads `omega doctor --json` to compute the verdict.
+post_install_card() {
+  local omega="$OMEGA_HOME/Agentik_Tools/bin/omega"
+  local verdict_text verdict_color
+  if [ -x "$omega" ]; then
+    local readiness
+    readiness="$(OMEGA_HOME="$OMEGA_HOME" "$omega" doctor --json 2>/dev/null \
+                | python3 -c 'import sys,json
+try: d=json.load(sys.stdin); print(d.get("readiness","unknown"))
+except Exception: print("unknown")' 2>/dev/null)" || readiness="unknown"
+    case "${readiness,,}" in
+      ready)        verdict_text="READY"   ; verdict_color="$C_GREEN" ;;
+      partial)      verdict_text="PARTIAL" ; verdict_color="$C_YELLOW" ;;
+      not-ready|not_ready) verdict_text="NOT READY"; verdict_color="$C_RED" ;;
+      *)            verdict_text="UNKNOWN" ; verdict_color="$C_DIM" ;;
+    esac
+  else
+    verdict_text="UNKNOWN" ; verdict_color="$C_DIM"
+  fi
+
+  local now elapsed mm ss
+  now="$(date +%s)"; elapsed=$((now - INSTALL_START_TS))
+  mm=$((elapsed / 60)); ss=$((elapsed % 60))
+  local v; v="$(omega_version)"
+
+  # Side-rule style — only a left bar + a top/bottom thread.
+  # ANSI-safe (no right padding to misalign).
+  local bar="${C_CYAN}│${C_RST}"
+  local top="${C_CYAN}╭───  ${C_BOLD}Omega OS v$v${C_RST}${C_CYAN}  —  install complete  ─────────${C_RST}"
+  local bot="${C_CYAN}╰────────────────────────────────────────────────────────────${C_RST}"
+  printf '\n'
+  printf '   %s\n' "$top"
+  printf '   %s\n' "$bar"
+  printf '   %s   status   %s%s%s\n'  "$bar" "$verdict_color$C_BOLD" "$verdict_text" "$C_RST"
+  printf '   %s   home     %s\n'      "$bar" "$OMEGA_HOME"
+  printf '   %s   user     %s\n'      "$bar" "$OMEGA_USER"
+  printf '   %s   elapsed  %s\n'      "$bar" "$(printf '%02d:%02d' "$mm" "$ss")"
+  printf '   %s\n' "$bar"
+  printf '   %s   %snext steps%s\n'                       "$bar" "$C_BOLD" "$C_RST"
+  printf "   %s     1.  %stmux attach -t AISB-chat%s     %salways-on Hermès conversation%s\n" \
+         "$bar" "$C_BOLD" "$C_RST" "$C_DIM" "$C_RST"
+  printf "   %s     2.  open a new shell  ${C_DIM}(or \`source ~/.zshrc\`)${C_RST}\n"          "$bar"
+  printf '   %s     3.  %somega status%s         every task + derived state\n'   "$bar" "$C_BOLD" "$C_RST"
+  printf '   %s     4.  %somega account list%s   wire your Claude Max OAuth\n'   "$bar" "$C_BOLD" "$C_RST"
+  printf '   %s     5.  %somega run "hello"%s    first verified mission\n'       "$bar" "$C_BOLD" "$C_RST"
+  printf '   %s     6.  %somega%s                interactive menu (whiptail)\n'  "$bar" "$C_BOLD" "$C_RST"
+  printf '   %s\n' "$bar"
+  printf '   %s   %ssessions%s    all Omega/Claude/LLM sessions run inside tmux\n' \
+         "$bar" "$C_BOLD" "$C_RST"
+  printf "   %s              ${C_DIM}prefix+Z = picker, prefix+d = detach (keeps running)${C_RST}\n" "$bar"
+  printf '   %s\n' "$bar"
+  printf '   %s   %sdocs%s    %sgithub.com/agentik-os/OmegaOS%s\n'   "$bar" "$C_BOLD" "$C_RST" "$C_DIM" "$C_RST"
+  printf '   %s   %sissues%s  %sgithub.com/agentik-os/OmegaOS/issues%s\n' "$bar" "$C_BOLD" "$C_RST" "$C_DIM" "$C_RST"
+  printf '   %s\n' "$bot"
+
+  # If PARTIAL or NOT READY, tell them where to look.
+  case "$verdict_text" in
+    PARTIAL|"NOT READY")
+      printf '\n   %s↳ Some checks did not pass.%s Run %s\`omega doctor\`%s to see details.\n' \
+             "$C_YELLOW" "$C_RST" "$C_BOLD" "$C_RST"
+      printf '     Logs are at %s%s%s\n' "$C_DIM" "$LOG_FILE" "$C_RST"
+      ;;
+  esac
+}