@geekbeer/minion 3.43.0 → 3.49.1

package/mac/minion-cli.sh

@@ -0,0 +1,1353 @@
+#!/usr/bin/env bash
+#
+# Minion Agent CLI (macOS) - @geekbeer/minion
+# CLI tool for setting up and managing the minion agent on macOS via launchd.
+#
+# Usage:
+#   sudo minion-cli-mac setup --user <USERNAME>      # System setup (root): user, sudoers, Screen Sharing, plists
+#   minion-cli-mac configure [options]               # Connect to HQ, deploy skills, restart agent (run as agent user)
+#   sudo minion-cli-mac uninstall [--keep-data]      # Remove agent and services (root)
+#   minion-cli-mac start                             # Bootstrap agent LaunchAgents
+#   minion-cli-mac stop                              # Bootout agent LaunchAgents
+#   minion-cli-mac restart                           # Kickstart agent LaunchAgent
+#   minion-cli-mac status                            # Get current status
+#   minion-cli-mac health                            # Health check
+#   minion-cli-mac daemons                           # Daemon status
+#   minion-cli-mac diagnose                          # Run full service diagnostics
+#   minion-cli-mac set-status busy "Running X"       # Set status and task
+#
+# Setup options:
+#   --user <USERNAME>     Target user for the agent (required)
+#
+# Configure options:
+#   --hq-url <URL>        HQ server URL (required)
+#   --minion-id <UUID>    Minion ID (required)
+#   --api-token <TOKEN>   API token (required)
+#   --setup-tunnel        Set up cloudflared tunnel as a LaunchAgent
+
+set -euo pipefail
+
+# Set MINION_TRACE=1 to enable shell tracing (every command printed to stderr
+# with a line number prefix). Useful when setup hangs and the standard output
+# does not pinpoint the culprit.
+#
+# To capture setup output to a log file while preserving live terminal output,
+# use macOS's built-in `script` command (it allocates a pty so output stays
+# line-buffered):
+#
+#   script -q /tmp/minion-setup.log sudo minion-cli-mac setup --user minion
+#
+# Avoid `... | tee log` — piping converts stdout to a pipe, which can buffer
+# output and make setup appear frozen even when it is making progress.
+if [ "${MINION_TRACE:-0}" = "1" ]; then
+  PS4='+ ${BASH_SOURCE##*/}:${LINENO}: '
+  set -x
+fi
+
+# ============================================================
+# Globals & helpers
+# ============================================================
+
+# Default target user is whoever invoked the script, refined per subcommand.
+if [ "$(id -u)" -eq 0 ]; then
+  # When running via sudo, prefer SUDO_USER over root for ergonomics.
+  TARGET_USER="${SUDO_USER:-root}"
+else
+  TARGET_USER="$(whoami)"
+fi
+TARGET_HOME="$(eval echo "~${TARGET_USER}")"
+RUN_AS=""
+
+# Use sudo only when not running as root
+SUDO=""
+if [ "$(id -u)" -ne 0 ] && command -v sudo &>/dev/null; then
+  SUDO="sudo"
+fi
+
+# Resolve CLI version from package.json
+CLI_DIR="$(cd "$(dirname "$0")" && pwd)"
+CLI_VERSION="$(node -p "require('${CLI_DIR}/../package.json').version" 2>/dev/null || echo "unknown")"
+
+AGENT_URL="${MINION_AGENT_URL:-http://localhost:8080}"
+
+# Brew prefix detection (Apple Silicon vs Intel)
+detect_brew_prefix() {
+  if command -v brew &>/dev/null; then
+    brew --prefix 2>/dev/null
+    return
+  fi
+  if [ -d /opt/homebrew ]; then echo "/opt/homebrew"; return; fi
+  if [ -d /usr/local/Homebrew ]; then echo "/usr/local"; return; fi
+  echo ""
+}
+BREW_PREFIX="$(detect_brew_prefix)"
+
+# Resolve a user's home directory using dscl (macOS-native; getent does not exist).
+resolve_user_home() {
+  local user="$1"
+  dscl . -read "/Users/${user}" NFSHomeDirectory 2>/dev/null | awk '{print $2}'
+}
+
+# Check whether a user exists.
+user_exists() {
+  dscl . -read "/Users/$1" >/dev/null 2>&1
+}
+
+# Get a user's UID via dscl (since Linux's `id -u <user>` exists on macOS too,
+# but dscl is the canonical macOS lookup that works for any user, including
+# pre-creation validation — wrap both for robustness).
+resolve_uid() {
+  local user="$1"
+  id -u "$user" 2>/dev/null || dscl . -read "/Users/${user}" UniqueID 2>/dev/null | awk '{print $2}'
+}
+
+# Generate a random alphanumeric string of length $1.
+#
+# We deliberately avoid `tr -dc 'A-Za-z0-9' </dev/urandom | head -c N` which
+# is the typical Linux idiom but hangs intermittently on macOS: BSD `tr`
+# blocks in read() on /dev/urandom and does not always honor SIGPIPE when
+# `head` exits, leaving the script stuck. Reading a fixed number of bytes
+# upfront and base64-encoding sidesteps the SIGPIPE timing entirely.
+gen_random_string() {
+  local len="$1"
+  # base64 of 48 bytes = 64 chars; that's plenty even after stripping
+  # +/= and newlines for any practical len <= 48.
+  LC_ALL=C dd if=/dev/urandom bs=48 count=1 2>/dev/null | base64 | LC_ALL=C tr -d '+/=\n' | cut -c1-"$len"
+}
+
+# Require root for system management commands.
+require_root() {
+  if [ "$(id -u)" -ne 0 ]; then
+    echo "Error: 'minion-cli-mac $1' requires root privileges."
+    echo "Usage: sudo minion-cli-mac $1"
+    exit 1
+  fi
+}
+
+# Detect LAN IPv4 address (best-effort)
+detect_lan_ip() {
+  ipconfig getifaddr en0 2>/dev/null \
+    || ipconfig getifaddr en1 2>/dev/null \
+    || ifconfig 2>/dev/null | awk '/inet / && $2 != "127.0.0.1" {print $2; exit}'
+}
+
+# Auto-load .env so that API_TOKEN etc. are available in interactive shells
+ENV_FILE="${TARGET_HOME}/.minion/.env"
+if [ -f "$ENV_FILE" ] && [ -r "$ENV_FILE" ]; then
+  while IFS='=' read -r key value; do
+    [[ "$key" =~ ^#.*$ || -z "$key" ]] && continue
+    if [ -z "${!key:-}" ]; then
+      export "$key=$value"
+    fi
+  done < "$ENV_FILE"
+fi
+
+# ============================================================
+# launchctl helpers
+# ============================================================
+
+# Path to a user's LaunchAgent plist.
+plist_path() {
+  local user="$1"
+  local label="$2"
+  echo "$(resolve_user_home "$user")/Library/LaunchAgents/${label}.plist"
+}
+
+# Domain target for `launchctl` (gui/<uid>/<label>).
+launchd_target() {
+  local user="$1"
+  local label="$2"
+  local uid
+  uid="$(resolve_uid "$user")"
+  echo "gui/${uid}/${label}"
+}
+
+# Bootstrap a LaunchAgent for a target user (idempotent).
+bootstrap_launch_agent() {
+  local user="$1"
+  local label="$2"
+  local plist
+  plist="$(plist_path "$user" "$label")"
+  local uid
+  uid="$(resolve_uid "$user")"
+
+  if [ ! -f "$plist" ]; then
+    echo "  WARNING: plist not found: $plist"
+    return 1
+  fi
+
+  # `launchctl bootstrap gui/<uid>` requires that GUI session to exist (i.e.,
+  # the user must be logged in). If not logged in, the plist still loads on
+  # next login because it lives in ~/Library/LaunchAgents.
+  if [ "$(id -u)" -eq 0 ]; then
+    sudo -u "$user" launchctl bootstrap "gui/${uid}" "$plist" 2>/dev/null || return 1
+  else
+    launchctl bootstrap "gui/${uid}" "$plist" 2>/dev/null || return 1
+  fi
+}
+
+# Bootout (unload) a LaunchAgent for a target user (idempotent).
+bootout_launch_agent() {
+  local user="$1"
+  local label="$2"
+  local target
+  target="$(launchd_target "$user" "$label")"
+  if [ "$(id -u)" -eq 0 ]; then
+    sudo -u "$user" launchctl bootout "$target" 2>/dev/null || true
+  else
+    launchctl bootout "$target" 2>/dev/null || true
+  fi
+}
+
+# Kickstart-restart a LaunchAgent.
+kickstart_launch_agent() {
+  local user="$1"
+  local label="$2"
+  local target
+  target="$(launchd_target "$user" "$label")"
+  if [ "$(id -u)" -eq 0 ]; then
+    sudo -u "$user" launchctl kickstart -k "$target"
+  else
+    launchctl kickstart -k "$target"
+  fi
+}
+
+# ============================================================
+# Admin-context helper (Homebrew refuses to run as root)
+# ============================================================
+#
+# Setup runs via `sudo`, so $UID is 0. But Homebrew explicitly refuses to
+# operate as root (it would give every build script unrestricted system
+# access). We must drop back to the user who invoked sudo — which is also
+# the user who installed Homebrew.
+
+# Resolve the non-root admin user who invoked the script.
+resolve_admin_user() {
+  if [ "$(id -u)" -ne 0 ]; then
+    whoami
+    return
+  fi
+  if [ -n "${SUDO_USER:-}" ] && [ "$SUDO_USER" != "root" ]; then
+    echo "$SUDO_USER"
+    return
+  fi
+  # Fall back to the brew binary's owner (whoever installed Homebrew)
+  if command -v brew &>/dev/null; then
+    stat -f%Su "$(command -v brew)" 2>/dev/null && return
+  fi
+  echo ""
+}
+
+# Run a command as the admin (non-root) user. Fails loudly if no admin user
+# can be resolved (e.g., logged in directly as root with no Homebrew).
+run_as_admin() {
+  local admin
+  admin="$(resolve_admin_user)"
+  if [ -z "$admin" ] || [ "$admin" = "root" ]; then
+    echo "ERROR: cannot determine the non-root user to run '$*' as." >&2
+    echo "       Setup must be invoked via sudo from a regular admin account" >&2
+    echo "       (e.g., 'sudo minion-cli-mac setup --user minion')." >&2
+    exit 1
+  fi
+  if [ "$admin" = "$(whoami)" ]; then
+    "$@"
+  else
+    sudo -u "$admin" -H "$@"
+  fi
+}
+
+# Run a command as the target user. The `-H` flag is critical: without it,
+# sudo preserves HOME from the caller (e.g. /Users/yunoda when setup is run
+# via `sudo minion-cli-mac`), causing tools like pipx and the claude
+# installer to write into the wrong user's home directory.
+run_as_target() {
+  sudo -u "$TARGET_USER" -H "$@"
+}
+
+# Service control helper for default agent label.
+LABEL_AGENT="com.geekbeer.minion"
+LABEL_TMUX_INIT="com.geekbeer.tmux-init"
+LABEL_WEBSOCKIFY="com.geekbeer.websockify"   # legacy; kept for uninstall path
+LABEL_VNC_PROXY="com.geekbeer.vnc-proxy"
+LABEL_CLOUDFLARED="com.geekbeer.cloudflared"
+
+svc_control() {
+  local action="$1"
+  local user="${2:-$TARGET_USER}"
+  case "$action" in
+    start)   bootstrap_launch_agent "$user" "$LABEL_AGENT" ;;
+    stop)    bootout_launch_agent   "$user" "$LABEL_AGENT" ;;
+    restart) kickstart_launch_agent "$user" "$LABEL_AGENT" ;;
+    *) echo "Unknown svc_control action: $action"; exit 1 ;;
+  esac
+}
+
+# ============================================================
+# Plist generation
+# ============================================================
+
+# Write a LaunchAgent plist file. Args:
+#   $1 = path
+#   $2 = body (XML, between <dict>...</dict>)
+write_plist() {
+  local path="$1"
+  local body="$2"
+  $SUDO mkdir -p "$(dirname "$path")"
+  $SUDO tee "$path" > /dev/null <<PLISTEOF
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+${body}
+</dict>
+</plist>
+PLISTEOF
+}
+
+# ============================================================
+# setup subcommand
+# ============================================================
+do_setup() {
+  require_root setup
+
+  local CLI_USER=""
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --user) CLI_USER="$2"; shift 2 ;;
+      --non-interactive) shift ;;
+      *) echo "Unknown option: $1"; echo "Usage: sudo minion-cli-mac setup --user <USERNAME>"; exit 1 ;;
+    esac
+  done
+
+  if [ -z "$CLI_USER" ]; then
+    echo "ERROR: --user flag is required."
+    echo "Usage: sudo minion-cli-mac setup --user <USERNAME>"
+    echo ""
+    echo "If the user doesn't exist yet, the script will create it for you."
+    exit 1
+  fi
+
+  TARGET_USER="$CLI_USER"
+
+  echo "========================================="
+  echo " @geekbeer/minion macOS Setup"
+  echo "========================================="
+  echo "Target user: $TARGET_USER"
+  echo "macOS:       $(sw_vers -productVersion 2>/dev/null || echo unknown)"
+  echo "Arch:        $(uname -m)"
+  echo "Brew prefix: ${BREW_PREFIX:-NOT FOUND}"
+  echo ""
+
+  if [ -z "$BREW_PREFIX" ] || ! command -v brew &>/dev/null; then
+    echo "ERROR: Homebrew is not installed."
+    echo ""
+    echo "Install it first:"
+    echo "  /bin/bash -c \"\$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\""
+    echo ""
+    echo "Then re-run setup."
+    exit 1
+  fi
+
+  local TOTAL_STEPS=14
+
+  # Step 1: Create target user if missing
+  echo "[1/${TOTAL_STEPS}] Verifying target user '$TARGET_USER'..."
+  if user_exists "$TARGET_USER"; then
+    # Verify the existing user has a usable password (else auto-login + VNC will fail)
+    if dscl . -read "/Users/${TARGET_USER}" Password 2>/dev/null | grep -q '^Password: \*$'; then
+      echo "  -> User exists but has NO PASSWORD set."
+      echo "     macOS auto-login and Screen Sharing both require a password."
+      echo "     Set one with: sudo dscl . -passwd /Users/${TARGET_USER}"
+      echo "     Then re-run setup."
+      exit 1
+    fi
+    echo "  -> User already exists"
+  else
+    echo "  -> User does not exist; creating..."
+    # Prompt for a password: macOS auto-login + Screen Sharing both REQUIRE a real
+    # password. sysadminctl's `-password -` (read from stdin) is unreliable inside
+    # sudo subshells, so we prompt via /dev/tty and pass the password as a literal.
+    if [ ! -t 0 ] && [ ! -r /dev/tty ]; then
+      echo "  ERROR: cannot prompt for password (non-interactive shell)."
+      echo "         Run setup from an interactive terminal, or pre-create the user:"
+      echo "           sudo sysadminctl -addUser ${TARGET_USER} -fullName 'Minion Agent' -password 'YOUR_PASSWORD'"
+      exit 1
+    fi
+
+    local PW="" PW2=""
+    while :; do
+      printf "  Set initial password for '%s' (required for auto-login + VNC): " "$TARGET_USER" > /dev/tty
+      IFS= read -r -s PW < /dev/tty
+      echo "" > /dev/tty
+      printf "  Confirm: " > /dev/tty
+      IFS= read -r -s PW2 < /dev/tty
+      echo "" > /dev/tty
+      if [ -z "$PW" ]; then
+        echo "  ERROR: password cannot be empty. Try again." > /dev/tty
+        continue
+      fi
+      if [ "$PW" != "$PW2" ]; then
+        echo "  ERROR: passwords do not match. Try again." > /dev/tty
+        continue
+      fi
+      break
+    done
+
+    if ! sysadminctl -addUser "$TARGET_USER" -fullName "Minion Agent" -password "$PW" 2>&1; then
+      unset PW PW2
+      echo "  ERROR: sysadminctl failed to create user"
+      exit 1
+    fi
+    unset PW PW2
+
+    # Sanity check: confirm the user was actually created with a password
+    if ! user_exists "$TARGET_USER"; then
+      echo "  ERROR: user creation appeared to succeed but '$TARGET_USER' does not exist"
+      exit 1
+    fi
+    if dscl . -read "/Users/${TARGET_USER}" Password 2>/dev/null | grep -q '^Password: \*$'; then
+      echo "  ERROR: user was created but has no password set (sysadminctl issue)"
+      echo "         Set it manually: sudo dscl . -passwd /Users/${TARGET_USER}"
+      exit 1
+    fi
+    echo "  -> User '$TARGET_USER' created"
+  fi
+
+  TARGET_HOME="$(resolve_user_home "$TARGET_USER")"
+  if [ -z "$TARGET_HOME" ]; then
+    echo "ERROR: Failed to resolve home directory for '$TARGET_USER'"
+    exit 1
+  fi
+  echo "  Home: $TARGET_HOME"
+
+  # FileVault warning
+  if fdesetup status 2>/dev/null | grep -q "FileVault is On"; then
+    echo ""
+    echo "  ⚠️  FileVault is ENABLED. macOS does NOT permit auto-login when"
+    echo "      FileVault is on, which means the minion user will not log in"
+    echo "      automatically at boot — and Screen Sharing requires a logged-in"
+    echo "      GUI session. Disable FileVault, or accept that the agent will"
+    echo "      only run after manual login."
+    echo ""
+  fi
+
+  # Step 2: Install Homebrew dependencies (as the admin who invoked sudo;
+  # Homebrew refuses to run as root)
+  echo "[2/${TOTAL_STEPS}] Installing dependencies via Homebrew..."
+  local ADMIN_USER
+  ADMIN_USER="$(resolve_admin_user)"
+  echo "  Running brew as: $ADMIN_USER"
+  # - cloudflared: bundled here so `configure --setup-tunnel` works without
+  #         bouncing back to admin (the minion user can't run brew install).
+  # NOTE: websockify and noVNC web assets are NO LONGER required as of v3.47.8.
+  #       VNC is bridged by mac/vnc-auth-proxy.js (Node, bundled with the
+  #       package), which performs RFB auth against macOS Screen Sharing
+  #       using a password stored only in ~/.minion/.env. The HQ-side noVNC
+  #       supplies the web assets.
+  local BREW_PKGS=(tmux ttyd jq node cloudflared)
+  for pkg in "${BREW_PKGS[@]}"; do
+    if run_as_admin brew list --formula "$pkg" >/dev/null 2>&1; then
+      echo "  -> $pkg already installed"
+    else
+      echo "  -> installing $pkg..."
+      run_as_admin brew install "$pkg"
+    fi
+  done
+
+  # Step 3: Install Claude Code (as target user)
+  echo "[3/${TOTAL_STEPS}] Installing Claude Code (as $TARGET_USER)..."
+  if run_as_target bash -lc 'command -v claude' &>/dev/null; then
+    echo "  -> Claude Code already installed"
+  else
+    run_as_target bash -lc 'curl -fsSL https://claude.ai/install.sh | bash' || {
+      echo "  WARNING: Claude Code installation may have failed"
+    }
+  fi
+  echo "  IMPORTANT: Authenticate later by logging in via Screen Sharing and running: claude"
+
+  # Step 4: Install Gemini CLI (run as admin to avoid root-owned files in
+  # Homebrew Node's /opt/homebrew/lib/node_modules/, which is brew-owned)
+  echo "[4/${TOTAL_STEPS}] Installing Gemini CLI..."
+  if command -v gemini &>/dev/null; then
+    echo "  -> Gemini CLI already installed"
+  else
+    run_as_admin npm install -g @google/gemini-cli || echo "  WARNING: Gemini CLI install failed; continuing"
+  fi
+
+  # Step 5: Create data directory under target user's home
+  echo "[5/${TOTAL_STEPS}] Creating ${TARGET_HOME}/.minion/..."
+  run_as_target mkdir -p "${TARGET_HOME}/.minion" "${TARGET_HOME}/.minion/logs" "${TARGET_HOME}/files"
+  echo "  -> ${TARGET_HOME}/.minion/ ready"
+
+  # Step 6: Ensure Homebrew shellenv is loaded for the target user's login shells.
+  # Freshly-created macOS users get an empty $PATH (no Homebrew bin), so the
+  # `minion-cli-mac configure` step in the next phase fails with "command not
+  # found" unless the user logs in via a shell that has been bootstrapped.
+  # zsh is the default login shell on modern macOS, so .zprofile is sufficient.
+  echo "[6/${TOTAL_STEPS}] Configuring shell PATH for ${TARGET_USER}..."
+  local ZPROFILE="${TARGET_HOME}/.zprofile"
+  run_as_target touch "$ZPROFILE"
+  if run_as_target grep -qF "brew shellenv" "$ZPROFILE"; then
+    echo "  -> brew shellenv already present in $ZPROFILE"
+  else
+    run_as_target tee -a "$ZPROFILE" > /dev/null <<EOF
+
+# Added by minion-cli-mac setup — exposes Homebrew + npm-global bins
+eval "\$(${BREW_PREFIX}/bin/brew shellenv)"
+EOF
+    echo "  -> appended brew shellenv to $ZPROFILE"
+  fi
+
+  # Step 7: Generate default .env
+  # Includes a randomly-generated VNC_PASSWORD that is shared between the
+  # macOS Screen Sharing config (set in Step 11) and the Node-based VNC auth
+  # proxy (mac/vnc-auth-proxy.js). The password never leaves this machine —
+  # HQ does not need it because the proxy authenticates locally on its behalf.
+  echo "[7/${TOTAL_STEPS}] Generating .env file..."
+  echo "  ENV_PATH: ${TARGET_HOME}/.minion/.env"
+  if [ ! -f "${TARGET_HOME}/.minion/.env" ]; then
+    echo "  (.env does not exist; creating fresh)"
+    echo "  -> generating VNC password..."
+    local VNC_PW
+    VNC_PW="$(gen_random_string 24)"
+    if [ -z "$VNC_PW" ]; then
+      echo "  ERROR: gen_random_string produced empty value; aborting"
+      exit 1
+    fi
+    echo "  -> VNC password generated (${#VNC_PW} chars)"
+    echo "  -> writing .env via tee (as ${TARGET_USER})..."
+    # Pre-create the directory so `tee` doesn't trip on a missing path.
+    run_as_target mkdir -p "${TARGET_HOME}/.minion"
+    run_as_target tee "${TARGET_HOME}/.minion/.env" > /dev/null <<EEOF
+# Minion Agent Configuration
+# Generated by minion-cli-mac setup
+
+AGENT_PORT=8080
+MINION_USER=${TARGET_USER}
+REFLECTION_TIME=03:00
+
+# VNC password used by mac/vnc-auth-proxy.js to authenticate with
+# macOS Screen Sharing. Never sent to HQ.
+VNC_PASSWORD=${VNC_PW}
+EEOF
+    echo "  -> tee complete; setting mode 0600..."
+    run_as_target chmod 600 "${TARGET_HOME}/.minion/.env"
+    echo "  -> ${TARGET_HOME}/.minion/.env created (mode 0600, VNC password generated)"
+  else
+    echo "  (.env exists; checking for VNC_PASSWORD line)"
+    if ! run_as_target grep -q '^VNC_PASSWORD=' "${TARGET_HOME}/.minion/.env"; then
+      echo "  -> VNC_PASSWORD missing; generating and appending"
+      local VNC_PW
+      VNC_PW="$(gen_random_string 24)"
+      run_as_target tee -a "${TARGET_HOME}/.minion/.env" > /dev/null <<EEOF
+
+# VNC password used by mac/vnc-auth-proxy.js (added by setup upgrade)
+VNC_PASSWORD=${VNC_PW}
+EEOF
+      echo "  -> appended VNC_PASSWORD to existing .env"
+    else
+      echo "  -> ${TARGET_HOME}/.minion/.env already exists, preserving"
+    fi
+    run_as_target chmod 600 "${TARGET_HOME}/.minion/.env"
+  fi
+
+  # Step 8: Configure sudoers for agent user
+  echo "[8/${TOTAL_STEPS}] Configuring sudoers..."
+  local NPM_BIN BREW_BIN LAUNCHCTL_BIN
+  NPM_BIN="$(command -v npm)"
+  BREW_BIN="${BREW_PREFIX}/bin/brew"
+  LAUNCHCTL_BIN="/bin/launchctl"
+  local SUDOERS_FILE="/etc/sudoers.d/minion-agent"
+
+  {
+    echo "Defaults:${TARGET_USER} passwd_tries=0"
+    echo ""
+    echo "${TARGET_USER} ALL=(root) NOPASSWD: ${NPM_BIN} install -g @geekbeer/minion@latest"
+    echo "${TARGET_USER} ALL=(root) NOPASSWD: ${NPM_BIN} install -g @geekbeer/minion@latest --registry *"
+    echo "${TARGET_USER} ALL=(root) NOPASSWD: ${BREW_BIN} install *"
+    echo "${TARGET_USER} ALL=(root) NOPASSWD: ${BREW_BIN} upgrade *"
+    echo "${TARGET_USER} ALL=(root) NOPASSWD: ${LAUNCHCTL_BIN} kickstart -k *"
+    echo "${TARGET_USER} ALL=(root) NOPASSWD: ${LAUNCHCTL_BIN} bootstrap *"
+    echo "${TARGET_USER} ALL=(root) NOPASSWD: ${LAUNCHCTL_BIN} bootout *"
+  } > "$SUDOERS_FILE"
+  chmod 440 "$SUDOERS_FILE"
+  if visudo -c -f "$SUDOERS_FILE" >/dev/null; then
+    echo "  -> $SUDOERS_FILE created and validated"
+  else
+    echo "  ERROR: sudoers file failed validation; removing"
+    rm -f "$SUDOERS_FILE"
+    exit 1
+  fi
+
+  # Step 9: Locate installed @geekbeer/minion server.js
+  echo "[9/${TOTAL_STEPS}] Locating @geekbeer/minion installation..."
+  local NPM_ROOT SERVER_PATH
+  NPM_ROOT="$(npm root -g)"
+  SERVER_PATH="${NPM_ROOT}/@geekbeer/minion/mac/server.js"
+  if [ ! -f "$SERVER_PATH" ]; then
+    echo "  ERROR: server.js not found at $SERVER_PATH"
+    echo "  Run: sudo npm install -g @geekbeer/minion"
+    exit 1
+  fi
+  echo "  -> $SERVER_PATH"
+
+  local NODE_BIN VNC_PROXY_PATH
+  NODE_BIN="$(command -v node)"
+  VNC_PROXY_PATH="${NPM_ROOT}/@geekbeer/minion/mac/vnc-auth-proxy.js"
+  if [ ! -f "$VNC_PROXY_PATH" ]; then
+    echo "  ERROR: vnc-auth-proxy.js not found at $VNC_PROXY_PATH"
+    echo "         Re-install the package: sudo npm install -g @geekbeer/minion@latest"
+    exit 1
+  fi
+
+  # Step 10: Generate LaunchAgent plists
+  echo "[10/${TOTAL_STEPS}] Generating LaunchAgent plists..."
+  local LA_DIR="${TARGET_HOME}/Library/LaunchAgents"
+  run_as_target mkdir -p "$LA_DIR"
+
+  # 9a: tmux-init plist (one-shot at login: ensures `main` session exists)
+  write_plist "${LA_DIR}/${LABEL_TMUX_INIT}.plist" "  <key>Label</key>
+  <string>${LABEL_TMUX_INIT}</string>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <false/>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/bin/bash</string>
+    <string>-lc</string>
+    <string>tmux has-session -t main 2>/dev/null || tmux new-session -d -s main; tmux set-option -g mouse on</string>
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>${BREW_PREFIX}/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+  </dict>
+  <key>StandardOutPath</key>
+  <string>${TARGET_HOME}/.minion/logs/tmux-init.out.log</string>
+  <key>StandardErrorPath</key>
+  <string>${TARGET_HOME}/.minion/logs/tmux-init.err.log</string>"
+  echo "  -> ${LABEL_TMUX_INIT}.plist"
+
+  # 9b: agent plist
+  write_plist "${LA_DIR}/${LABEL_AGENT}.plist" "  <key>Label</key>
+  <string>${LABEL_AGENT}</string>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
+  <key>ThrottleInterval</key>
+  <integer>10</integer>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${NODE_BIN}</string>
+    <string>${SERVER_PATH}</string>
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${TARGET_HOME}/.minion</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>HOME</key>
+    <string>${TARGET_HOME}</string>
+    <key>PATH</key>
+    <string>${BREW_PREFIX}/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:${TARGET_HOME}/.local/bin:${TARGET_HOME}/.claude/bin</string>
+    <key>MINION_USER</key>
+    <string>${TARGET_USER}</string>
+  </dict>
+  <key>StandardOutPath</key>
+  <string>${TARGET_HOME}/.minion/logs/agent.out.log</string>
+  <key>StandardErrorPath</key>
+  <string>${TARGET_HOME}/.minion/logs/agent.err.log</string>"
+  echo "  -> ${LABEL_AGENT}.plist"
+
+  # 9c: vnc-proxy plist (Node-based RFB auth proxy, replaces websockify as of v3.48.0).
+  # --openssl-legacy-provider is REQUIRED: VNC Auth (RFB security type 2) uses
+  # DES, which OpenSSL 3 (shipped with Node 17+) removed from the default
+  # provider. Without this flag the proxy fails at challenge encryption.
+  write_plist "${LA_DIR}/${LABEL_VNC_PROXY}.plist" "  <key>Label</key>
+  <string>${LABEL_VNC_PROXY}</string>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ThrottleInterval</key>
+  <integer>5</integer>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${NODE_BIN}</string>
+    <string>--openssl-legacy-provider</string>
+    <string>${VNC_PROXY_PATH}</string>
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>HOME</key>
+    <string>${TARGET_HOME}</string>
+    <key>PATH</key>
+    <string>${BREW_PREFIX}/bin:/usr/local/bin:/usr/bin:/bin</string>
+  </dict>
+  <key>StandardOutPath</key>
+  <string>${TARGET_HOME}/.minion/logs/vnc-proxy.out.log</string>
+  <key>StandardErrorPath</key>
+  <string>${TARGET_HOME}/.minion/logs/vnc-proxy.err.log</string>"
+  echo "  -> ${LABEL_VNC_PROXY}.plist"
+
+  # Migrate from old websockify plist if present (upgrade path from < 3.47.8).
+  # Bootout the old service and remove its plist so the user is not left with
+  # two services racing for port 6080.
+  if [ -f "${LA_DIR}/${LABEL_WEBSOCKIFY}.plist" ]; then
+    echo "  -> migrating: removing legacy ${LABEL_WEBSOCKIFY}.plist"
+    bootout_launch_agent "$TARGET_USER" "$LABEL_WEBSOCKIFY" 2>/dev/null || true
+    rm -f "${LA_DIR}/${LABEL_WEBSOCKIFY}.plist"
+  fi
+
+  # Set ownership on plists
+  chown -R "${TARGET_USER}:staff" "${TARGET_HOME}/Library/LaunchAgents"
+
+  # Step 11: Enable native Screen Sharing + set VNC password for the proxy
+  echo "[11/${TOTAL_STEPS}] Enabling native macOS Screen Sharing..."
+  launchctl enable system/com.apple.screensharing 2>/dev/null || true
+  launchctl kickstart -k system/com.apple.screensharing 2>/dev/null || true
+  echo "  -> Screen Sharing daemon enabled (port 5900)"
+
+  # Configure VNC password via Apple Remote Desktop's `kickstart` (NOT launchctl
+  # kickstart — same name, different binary). This enables VNC Auth security
+  # type 2 on screensharingd, which the bundled mac/vnc-auth-proxy.js then
+  # uses to authenticate. Runs as root (we are root).
+  local VNC_PW_FROM_ENV=""
+  if [ -f "${TARGET_HOME}/.minion/.env" ]; then
+    VNC_PW_FROM_ENV="$(awk -F'=' '/^VNC_PASSWORD=/{print $2; exit}' "${TARGET_HOME}/.minion/.env")"
+  fi
+  local ARD_KICKSTART="/System/Library/CoreServices/RemoteManagement/ARDAgent.app/Contents/Resources/kickstart"
+  if [ -n "$VNC_PW_FROM_ENV" ] && [ -x "$ARD_KICKSTART" ]; then
+    # macOS Screen Sharing truncates VNC password to 8 chars; the proxy
+    # sends the same truncated value, so they match.
+    "$ARD_KICKSTART" -configure -clientopts \
+      -setvnclegacy -vnclegacy yes \
+      -setvncpw -vncpw "$VNC_PW_FROM_ENV" >/dev/null 2>&1 \
+      && echo "  -> VNC password installed via ARD kickstart" \
+      || echo "  WARNING: ARD kickstart failed; VNC may require manual System Settings configuration"
+  else
+    echo "  WARNING: VNC_PASSWORD not found in .env or ARD kickstart unavailable; VNC may not authenticate"
+  fi
+
+  # Note: System Settings -> General -> Sharing -> Screen Sharing toggle still
+  # requires manual user action on modern macOS (Ventura+) due to TCC. The
+  # final summary instructs the user to verify this.
+
+  # Add target user to access_screensharing group
+  if dseditgroup -o read com.apple.access_screensharing >/dev/null 2>&1; then
+    if dseditgroup -o checkmember -m "$TARGET_USER" com.apple.access_screensharing >/dev/null 2>&1; then
+      echo "  -> User '$TARGET_USER' is already in com.apple.access_screensharing"
+    else
+      dseditgroup -o edit -a "$TARGET_USER" -t user com.apple.access_screensharing
+      echo "  -> Added '$TARGET_USER' to com.apple.access_screensharing"
+    fi
+  else
+    # Group doesn't exist (rare); fall back to dscl
+    dscl . append /Groups/com.apple.access_screensharing GroupMembership "$TARGET_USER" 2>/dev/null || true
+    echo "  -> Added '$TARGET_USER' to com.apple.access_screensharing (via dscl)"
+  fi
+
+  # Step 12: Disable screen lock, screen saver, and display sleep.
+  # VNC is the primary way humans observe and intervene with the agent. Without
+  # these settings macOS locks the screen and blanks the display after a few
+  # minutes, requiring a password (which the human operator may not have) to
+  # resume work. The agent runs unattended on a dedicated machine, so the
+  # security trade-off is acceptable; physical access to the machine is the
+  # real boundary.
+  echo "[12/${TOTAL_STEPS}] Disabling screen lock and display sleep..."
+
+  # 12a: Disable "Require password after sleep or screen saver begins".
+  # `defaults` (vs `sysadminctl -screenLock`) avoids needing the user's
+  # password and writes to the same per-user preference domain.
+  run_as_target defaults write com.apple.screensaver askForPassword -int 0 \
+    && echo "  -> askForPassword=0 (no password after sleep/screensaver)" \
+    || echo "  WARNING: failed to write com.apple.screensaver askForPassword"
+  run_as_target defaults write com.apple.screensaver askForPasswordDelay -int 0 2>/dev/null || true
+
+  # 12b: Disable screensaver activation entirely (idleTime=0 means never).
+  # Must use -currentHost; the screensaver domain is host-scoped.
+  run_as_target defaults -currentHost write com.apple.screensaver idleTime -int 0 \
+    && echo "  -> screensaver idleTime=0 (never activate)" \
+    || echo "  WARNING: failed to disable screensaver"
+
+  # 12c: Disable display sleep system-wide. Requires root (we are root here).
+  # -a applies to all power sources (AC, battery, UPS).
+  if pmset -a displaysleep 0 >/dev/null 2>&1; then
+    echo "  -> pmset displaysleep=0 (display never sleeps)"
+  else
+    echo "  WARNING: pmset displaysleep=0 failed"
+  fi
+
+  # Step 13: Bootstrap LaunchAgents (best-effort; only works if user is logged in)
+  echo "[13/${TOTAL_STEPS}] Bootstrapping LaunchAgents..."
+  local TARGET_UID
+  TARGET_UID="$(resolve_uid "$TARGET_USER")"
+  # Detect whether the target user has an active GUI session
+  if launchctl print "gui/${TARGET_UID}" >/dev/null 2>&1; then
+    for label in "$LABEL_TMUX_INIT" "$LABEL_AGENT" "$LABEL_VNC_PROXY"; do
+      if bootstrap_launch_agent "$TARGET_USER" "$label"; then
+        echo "  -> bootstrapped: $label"
+      else
+        echo "  -> already bootstrapped or failed: $label (will load on next login)"
+      fi
+    done
+  else
+    echo "  -> User '$TARGET_USER' is not currently logged in to a GUI session."
+    echo "     LaunchAgents will load automatically on next login."
+  fi
+
+  # Step 14: Deploy bundled skills, rules
+  echo "[14/${TOTAL_STEPS}] Deploying bundled skills and rules..."
+  local BUNDLED_SKILLS_DIR="${NPM_ROOT}/@geekbeer/minion/skills"
+  local CLAUDE_SKILLS_DIR="${TARGET_HOME}/.claude/skills"
+  if [ -d "$BUNDLED_SKILLS_DIR" ]; then
+    run_as_target mkdir -p "$CLAUDE_SKILLS_DIR"
+    for skill_dir in "$BUNDLED_SKILLS_DIR"/*/; do
+      [ -d "$skill_dir" ] || continue
+      local skill_name
+      skill_name="$(basename "$skill_dir")"
+      run_as_target cp -r "$skill_dir" "${CLAUDE_SKILLS_DIR}/${skill_name}"
+      echo "  -> Deployed skill: $skill_name"
+    done
+  else
+    echo "  -> No bundled skills found"
+  fi
+
+  local BUNDLED_RULES_DIR="${NPM_ROOT}/@geekbeer/minion/rules"
+  local CLAUDE_RULES_DIR="${TARGET_HOME}/.claude/rules"
+  if [ -d "$BUNDLED_RULES_DIR" ]; then
+    run_as_target mkdir -p "$CLAUDE_RULES_DIR"
+    run_as_target cp "$BUNDLED_RULES_DIR/core.md" "$CLAUDE_RULES_DIR/core.md"
+    echo "  -> Deployed rules: core.md"
+  fi
+
+  # Final summary & manual steps
+  echo ""
+  echo "========================================="
+  echo " Setup Complete!"
+  echo "========================================="
+  echo ""
+  echo "Agent user: $TARGET_USER  ($TARGET_HOME)"
+  echo "Plists:     $LA_DIR/"
+  echo ""
+  echo "Manual steps remaining:"
+  echo "  1. (Required) Enable Screen Sharing in System Settings:"
+  echo "       System Settings -> General -> Sharing -> Screen Sharing -> ON"
+  echo "       (launchctl enable is silently ignored on Ventura+ due to TCC.)"
+  echo "       Verify with: lsof -nP -iTCP:5900 -sTCP:LISTEN"
+  echo ""
+  echo "  2. (Required for production / persistent VNC) Set auto-login for '$TARGET_USER':"
+  echo "       System Settings -> Users & Groups -> Automatically log in as -> $TARGET_USER"
+  echo "       (LaunchAgents only run while the user has a GUI session."
+  echo "        Auto-login requires FileVault to be OFF.)"
+  echo ""
+  echo "  3. Switch to the agent user with a login shell so brew/npm bins are on PATH:"
+  echo "       sudo su - $TARGET_USER"
+  echo ""
+  echo "  4. Connect to HQ (as $TARGET_USER, no sudo needed):"
+  echo "       minion-cli-mac configure \\"
+  echo "         --hq-url <HQ_URL> \\"
+  echo "         --minion-id <MINION_ID> \\"
+  echo "         --api-token <API_TOKEN>"
+  echo ""
+  echo "Health check:    minion-cli-mac health"
+  echo "Diagnose:        minion-cli-mac diagnose"
+  echo ""
+}
+
+# ============================================================
+# configure subcommand
+# ============================================================
+do_configure() {
+  local HQ_URL=""
+  local MINION_ID=""
+  local API_TOKEN=""
+  local SETUP_TUNNEL=false
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --hq-url) HQ_URL="$2"; shift 2 ;;
+      --minion-id) MINION_ID="$2"; shift 2 ;;
+      --api-token) API_TOKEN="$2"; shift 2 ;;
+      --setup-tunnel) SETUP_TUNNEL=true; shift ;;
+      --non-interactive) shift ;;
+      *) echo "Unknown option: $1"; exit 1 ;;
+    esac
+  done
+
+  if [ -z "$HQ_URL" ] || [ -z "$MINION_ID" ] || [ -z "$API_TOKEN" ]; then
+    echo "ERROR: --hq-url, --minion-id, --api-token are all required"
+    exit 1
+  fi
+
+  # configure runs as the agent user (no sudo). Resolve TARGET_USER from .env if needed.
+  local CFG_USER CFG_HOME
+  CFG_USER="$(whoami)"
+  CFG_HOME="$HOME"
+
+  if [ ! -f "${CFG_HOME}/.minion/.env" ]; then
+    echo "ERROR: ${CFG_HOME}/.minion/.env not found."
+    echo "Run 'sudo minion-cli-mac setup --user $CFG_USER' first (from an admin account)."
+    exit 1
+  fi
+
+  local TOTAL_STEPS=4
+  if [ "$SETUP_TUNNEL" = true ]; then TOTAL_STEPS=5; fi
+
+  echo "========================================="
+  echo " @geekbeer/minion Configure (macOS)"
+  echo "========================================="
+  echo "User:      $CFG_USER"
+  echo "HQ:        $HQ_URL"
+  echo "Minion ID: $MINION_ID"
+  [ "$SETUP_TUNNEL" = true ] && echo "Tunnel:    Enabled"
+  echo ""
+
+  # Step 1: Update .env
+  echo "[1/${TOTAL_STEPS}] Writing HQ credentials to .env..."
+  local TMP_ENV
+  TMP_ENV="$(mktemp)"
+  {
+    echo "# Minion Agent Configuration"
+    echo "# Configured by minion-cli-mac configure"
+    echo ""
+    echo "HQ_URL=${HQ_URL}"
+    echo "API_TOKEN=${API_TOKEN}"
+    echo "MINION_ID=${MINION_ID}"
+    if [ -f "${CFG_HOME}/.minion/.env" ]; then
+      while IFS='=' read -r key value; do
+        [[ -z "$key" || "$key" == \#* ]] && continue
+        case "$key" in
+          HQ_URL|API_TOKEN|MINION_ID) ;;
+          *) echo "${key}=${value}" ;;
+        esac
+      done < "${CFG_HOME}/.minion/.env"
+    fi
+  } > "$TMP_ENV"
+  mv "$TMP_ENV" "${CFG_HOME}/.minion/.env"
+  echo "  -> ${CFG_HOME}/.minion/.env updated"
+
+  # Step 2: Deploy bundled skills/rules
+  echo "[2/${TOTAL_STEPS}] Deploying bundled assets..."
+  local NPM_ROOT
+  NPM_ROOT="$(npm root -g 2>/dev/null || echo "")"
+  local BUNDLED_SKILLS_DIR="${NPM_ROOT}/@geekbeer/minion/skills"
+  local CLAUDE_SKILLS_DIR="${CFG_HOME}/.claude/skills"
+  if [ -d "$BUNDLED_SKILLS_DIR" ]; then
+    mkdir -p "$CLAUDE_SKILLS_DIR"
+    for skill_dir in "$BUNDLED_SKILLS_DIR"/*/; do
+      [ -d "$skill_dir" ] || continue
+      local skill_name
+      skill_name="$(basename "$skill_dir")"
+      cp -r "$skill_dir" "${CLAUDE_SKILLS_DIR}/${skill_name}"
+      echo "  -> Deployed skill: $skill_name"
+    done
+  fi
+
+  local BUNDLED_RULES_DIR="${NPM_ROOT}/@geekbeer/minion/rules"
+  local CLAUDE_RULES_DIR="${CFG_HOME}/.claude/rules"
+  if [ -d "$BUNDLED_RULES_DIR" ]; then
+    mkdir -p "$CLAUDE_RULES_DIR"
+    cp "$BUNDLED_RULES_DIR/core.md" "$CLAUDE_RULES_DIR/core.md"
+    echo "  -> Deployed rules: core.md"
+  fi
+
+  # Step 3 (optional): Cloudflare Tunnel
+  local CURRENT_STEP=3
+  if [ "$SETUP_TUNNEL" = true ]; then
+    echo "[${CURRENT_STEP}/${TOTAL_STEPS}] Setting up Cloudflare Tunnel..."
+    if ! command -v cloudflared &>/dev/null; then
+      echo "  ERROR: cloudflared is not installed."
+      echo "         The minion user cannot install brew packages."
+      echo "         Re-run setup as admin to install cloudflared:"
+      echo "           sudo minion-cli-mac setup --user $CFG_USER"
+      exit 1
+    fi
+
+    local TUNNEL_DATA
+    TUNNEL_DATA="$(curl -sfL -H "Authorization: Bearer ${API_TOKEN}" "${HQ_URL}/api/minion/tunnel-credentials" 2>&1)" || true
+
+    if [ -z "$TUNNEL_DATA" ] || ! echo "$TUNNEL_DATA" | jq -e '.tunnel_id' > /dev/null 2>&1; then
+      echo "  ERROR: Failed to fetch tunnel credentials from HQ; skipping tunnel setup"
+    else
+      local TUNNEL_ID CREDS_JSON CONFIG_YML
+      TUNNEL_ID="$(echo "$TUNNEL_DATA" | jq -r '.tunnel_id')"
+      CREDS_JSON="$(echo "$TUNNEL_DATA" | jq -r '.credentials_json')"
+      CONFIG_YML="$(echo "$TUNNEL_DATA" | jq -r '.config_yml')"
+
+      mkdir -p "${CFG_HOME}/.cloudflared"
+      echo "$CREDS_JSON" > "${CFG_HOME}/.cloudflared/${TUNNEL_ID}.json"
+      chmod 600 "${CFG_HOME}/.cloudflared/${TUNNEL_ID}.json"
+      echo "$CONFIG_YML" > "${CFG_HOME}/.cloudflared/config.yml"
+
+      local CLOUDFLARED_BIN
+      CLOUDFLARED_BIN="$(command -v cloudflared)"
+      local LA_DIR="${CFG_HOME}/Library/LaunchAgents"
+      mkdir -p "$LA_DIR"
+      cat > "${LA_DIR}/${LABEL_CLOUDFLARED}.plist" <<CFEOF
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${LABEL_CLOUDFLARED}</string>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${CLOUDFLARED_BIN}</string>
+    <string>tunnel</string>
+    <string>--config</string>
+    <string>${CFG_HOME}/.cloudflared/config.yml</string>
+    <string>run</string>
+  </array>
+  <key>StandardOutPath</key>
+  <string>${CFG_HOME}/.minion/logs/cloudflared.out.log</string>
+  <key>StandardErrorPath</key>
+  <string>${CFG_HOME}/.minion/logs/cloudflared.err.log</string>
+</dict>
+</plist>
+CFEOF
+      bootstrap_launch_agent "$CFG_USER" "$LABEL_CLOUDFLARED" || true
+      echo "  -> cloudflared LaunchAgent installed and bootstrapped"
+    fi
+    CURRENT_STEP=$((CURRENT_STEP + 1))
+  fi
+
+  # Step N-1: Restart agent
+  echo "[$((TOTAL_STEPS - 1))/${TOTAL_STEPS}] Restarting agent..."
+  if launchctl print "$(launchd_target "$CFG_USER" "$LABEL_AGENT")" >/dev/null 2>&1; then
+    kickstart_launch_agent "$CFG_USER" "$LABEL_AGENT" || true
+    echo "  -> minion-agent restarted (launchd)"
+  else
+    bootstrap_launch_agent "$CFG_USER" "$LABEL_AGENT" || true
+    echo "  -> minion-agent bootstrapped (launchd)"
+  fi
+
+  # Step N: Health check
+  echo "[${TOTAL_STEPS}/${TOTAL_STEPS}] Verifying agent health..."
+  local HEALTH_OK=false
+  for i in $(seq 1 5); do
+    if curl -sf http://localhost:8080/api/health > /dev/null 2>&1; then
+      HEALTH_OK=true
+      break
+    fi
+    sleep 2
+  done
+  if [ "$HEALTH_OK" = true ]; then
+    echo "  -> Agent is healthy"
+  else
+    echo "  WARNING: Health check failed after 5 attempts"
+    echo "  Logs: tail -f ${CFG_HOME}/.minion/logs/agent.err.log"
+  fi
+
+  # Notify HQ with machine specs
+  echo ""
+  echo "Notifying HQ..."
+  local LAN_IP HOSTNAME_VAL
+  LAN_IP="$(detect_lan_ip)"
+  HOSTNAME_VAL="$(hostname 2>/dev/null || echo "")"
+
+  local CPU_MODEL CPU_CORES MEMORY_MB DISK_GB OS_INFO ARCH_INFO
+  CPU_MODEL="$(sysctl -n machdep.cpu.brand_string 2>/dev/null || echo unknown)"
+  CPU_CORES="$(sysctl -n hw.ncpu 2>/dev/null || echo 0)"
+  local MEMORY_BYTES
+  MEMORY_BYTES="$(sysctl -n hw.memsize 2>/dev/null || echo 0)"
+  MEMORY_MB="$(( MEMORY_BYTES / 1024 / 1024 ))"
+  DISK_GB="$(df -g / 2>/dev/null | awk 'NR==2 {print $2}')"
+  OS_INFO="macOS $(sw_vers -productVersion 2>/dev/null || echo unknown)"
+  ARCH_INFO="$(uname -m 2>/dev/null || echo unknown)"
+
+  local MACHINE_SPECS
+  MACHINE_SPECS=$(cat <<SPECEOF
+{"cpu_model":"${CPU_MODEL}","cpu_cores":${CPU_CORES},"memory_mb":${MEMORY_MB},"disk_gb":${DISK_GB:-0},"os":"${OS_INFO}","arch":"${ARCH_INFO}"}
+SPECEOF
+  )
+
+  local BODY
+  if [ -n "$LAN_IP" ]; then
+    BODY="{\"internal_ip_address\":\"${LAN_IP}\",\"ip_address\":\"${LAN_IP}\",\"machine_specs\":${MACHINE_SPECS}}"
+  else
+    BODY="{\"internal_ip_address\":\"${HOSTNAME_VAL}\",\"machine_specs\":${MACHINE_SPECS}}"
+  fi
+
+  local NOTIFY_RESPONSE
+  NOTIFY_RESPONSE="$(curl -sfL -X POST "${HQ_URL}/api/minion/setup-complete" \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer ${API_TOKEN}" \
+    -d "$BODY" 2>&1)" || true
+
+  if echo "$NOTIFY_RESPONSE" | grep -q '"success":true' 2>/dev/null; then
+    echo "  -> HQ notified successfully${LAN_IP:+ (LAN IP: ${LAN_IP})}"
+  else
+    echo "  -> Skipped (heartbeat will notify HQ within 30s)"
+  fi
+
+  echo ""
+  echo "========================================="
+  echo " Configure Complete!"
+  echo "========================================="
+  echo ""
+  echo "Useful commands:"
+  echo "  minion-cli-mac status                 # Agent status"
+  echo "  minion-cli-mac health                 # Health check"
+  echo "  minion-cli-mac restart                # Restart agent"
+  echo "  tail -f ${CFG_HOME}/.minion/logs/agent.err.log  # Agent logs"
+  echo ""
+}
+
+# ============================================================
+# uninstall subcommand
+# ============================================================
+do_uninstall() {
+  require_root uninstall
+
+  local KEEP_DATA=false
+  local CLI_USER=""
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --keep-data) KEEP_DATA=true; shift ;;
+      --user) CLI_USER="$2"; shift 2 ;;
+      *) echo "Unknown option: $1"; exit 1 ;;
+    esac
+  done
+
+  # If --user not provided, try to read from any existing /etc/sudoers.d/minion-agent
+  if [ -z "$CLI_USER" ] && [ -f /etc/sudoers.d/minion-agent ]; then
+    CLI_USER="$(grep -m1 '^Defaults:' /etc/sudoers.d/minion-agent 2>/dev/null | sed 's/Defaults://; s/[[:space:]].*//')"
+  fi
+  if [ -z "$CLI_USER" ]; then
+    echo "ERROR: cannot determine target user; pass --user <USERNAME>"
+    exit 1
+  fi
+
+  local UN_HOME
+  UN_HOME="$(resolve_user_home "$CLI_USER" 2>/dev/null || echo "")"
+  if [ -z "$UN_HOME" ]; then
+    echo "  WARNING: User '$CLI_USER' does not exist; will only clean system-level state"
+  fi
+
+  echo "========================================="
+  echo " @geekbeer/minion Uninstall (macOS)"
+  echo "========================================="
+  echo ""
+  echo "Target user:  $CLI_USER"
+  echo "Target home:  ${UN_HOME:-<missing>}"
+  if [ "$KEEP_DATA" = true ]; then
+    echo "  --keep-data: ${UN_HOME}/.minion will be preserved."
+  else
+    echo "  ${UN_HOME}/.minion will be deleted."
+  fi
+  echo ""
+  echo -n "Type 'yes' to continue: "
+  read -r CONFIRM
+  if [ "$CONFIRM" != "yes" ]; then
+    echo "Uninstall cancelled."
+    exit 0
+  fi
+
+  # Step 1: Bootout LaunchAgents
+  echo "[1/4] Removing LaunchAgents..."
+  if [ -n "$UN_HOME" ]; then
+    for label in "$LABEL_AGENT" "$LABEL_TMUX_INIT" "$LABEL_VNC_PROXY" "$LABEL_WEBSOCKIFY" "$LABEL_CLOUDFLARED"; do
+      bootout_launch_agent "$CLI_USER" "$label"
+      local plist="${UN_HOME}/Library/LaunchAgents/${label}.plist"
+      if [ -f "$plist" ]; then
+        rm -f "$plist"
+        echo "  -> Removed $plist"
+      fi
+    done
+  fi
+
+  # Step 2: Remove sudoers
+  echo "[2/4] Removing sudoers configuration..."
+  if [ -f /etc/sudoers.d/minion-agent ]; then
+    rm -f /etc/sudoers.d/minion-agent
+    echo "  -> Removed /etc/sudoers.d/minion-agent"
+  fi
+
+  # Step 3: Remove data dir & cloudflared config
+  echo "[3/4] Removing user data..."
+  if [ -n "$UN_HOME" ]; then
+    if [ "$KEEP_DATA" = false ] && [ -d "${UN_HOME}/.minion" ]; then
+      rm -rf "${UN_HOME}/.minion"
+      echo "  -> Removed ${UN_HOME}/.minion"
+    fi
+    if [ -d "${UN_HOME}/.cloudflared" ]; then
+      rm -rf "${UN_HOME}/.cloudflared"
+      echo "  -> Removed ${UN_HOME}/.cloudflared"
+    fi
+  fi
+
+  # Step 4: Remove user from screen sharing group (do NOT delete user)
+  echo "[4/4] Removing user from com.apple.access_screensharing..."
+  dseditgroup -o edit -d "$CLI_USER" -t user com.apple.access_screensharing 2>/dev/null || true
+  echo "  -> Done"
+
+  echo ""
+  echo "Uninstall complete."
+  echo "  • Native Screen Sharing service is left enabled (it is system-managed)."
+  echo "  • The '$CLI_USER' user account was NOT deleted; remove with:"
+  echo "        sudo sysadminctl -deleteUser $CLI_USER"
+  echo "  • Brew packages (tmux, ttyd, websockify, cloudflared, etc.) were NOT removed."
+}
+
+# ============================================================
+# Main dispatch
+# ============================================================
+case "${1:-}" in
+  --version|-v)
+    echo "@geekbeer/minion (macOS) v${CLI_VERSION}"
+    ;;
+
+  setup)
+    shift
+    do_setup "$@"
+    ;;
+
+  configure|reconfigure)
+    shift
+    do_configure "$@"
+    ;;
+
+  uninstall)
+    shift
+    do_uninstall "$@"
+    ;;
+
+  status)
+    curl -s "$AGENT_URL/api/status" | jq .
+    ;;
+
+  set-status)
+    STATUS="${2:-online}"
+    TASK="${3:-}"
+    if [ -n "$TASK" ]; then
+      curl -s -X POST "$AGENT_URL/api/status" \
+        -H "Content-Type: application/json" \
+        -d "{\"status\": \"$STATUS\", \"current_task\": \"$TASK\"}" | jq .
+    else
+      curl -s -X POST "$AGENT_URL/api/status" \
+        -H "Content-Type: application/json" \
+        -d "{\"status\": \"$STATUS\", \"current_task\": null}" | jq .
+    fi
+    ;;
+
+  health)
+    curl -s "$AGENT_URL/api/health" | jq .
+    ;;
+
+  daemons)
+    curl -s "$AGENT_URL/api/daemons/status" | jq .
+    ;;
+
+  diagnose)
+    echo "Running diagnostics..."
+    echo ""
+    RESULT=$(curl -s --max-time 15 "$AGENT_URL/api/diagnose" 2>/dev/null) || {
+      echo "FAIL: Cannot reach minion agent at $AGENT_URL"
+      echo "      Is the agent running? Try: minion-cli-mac start"
+      exit 1
+    }
+    SUMMARY=$(echo "$RESULT" | jq -r '.summary // "UNKNOWN"')
+    VERSION=$(echo "$RESULT" | jq -r '.version // "?"')
+    PLATFORM=$(echo "$RESULT" | jq -r '.platform // "?"')
+    echo "=== Minion Diagnostics (v${VERSION}, ${PLATFORM}) ==="
+    echo ""
+    for CHECK in agent hq tunnel vnc terminal llm env; do
+      OK=$(echo "$RESULT" | jq -r ".checks.${CHECK}.ok")
+      DETAILS=$(echo "$RESULT" | jq -r ".checks.${CHECK}.details // \"\"")
+      CHECK_UPPER=$(echo "$CHECK" | tr '[:lower:]' '[:upper:]')
+      if [ "$OK" = "true" ]; then
+        printf "  \033[32m[PASS]\033[0m %-10s %s\n" "$CHECK_UPPER" "$DETAILS"
+      else
+        printf "  \033[31m[FAIL]\033[0m %-10s %s\n" "$CHECK_UPPER" "$DETAILS"
+      fi
+    done
+    echo ""
+    if [ "$SUMMARY" = "ALL OK" ]; then
+      echo -e "\033[32m$SUMMARY\033[0m"
+    else
+      echo -e "\033[33m$SUMMARY\033[0m"
+    fi
+    ;;
+
+  start)
+    svc_control start "${TARGET_USER}"
+    echo "minion-agent started (launchd, user=$TARGET_USER)"
+    ;;
+
+  stop)
+    svc_control stop "${TARGET_USER}"
+    echo "minion-agent stopped (launchd, user=$TARGET_USER)"
+    ;;
+
+  restart)
+    svc_control restart "${TARGET_USER}"
+    echo "minion-agent restarted (launchd, user=$TARGET_USER)"
+    ;;
+
+  skill)
+    shift
+    SKILL_CMD="${1:-}"
+    shift || true
+    case "$SKILL_CMD" in
+      push)
+        SKILL_NAME="${1:-}"
+        if [ -z "$SKILL_NAME" ]; then echo "Usage: minion-cli-mac skill push <skill-name>"; exit 1; fi
+        curl -s -X POST "$AGENT_URL/api/skills/push/$SKILL_NAME" -H "Authorization: Bearer $API_TOKEN" | jq .
+        ;;
+      fetch)
+        SKILL_NAME="${1:-}"
+        if [ -z "$SKILL_NAME" ]; then echo "Usage: minion-cli-mac skill fetch <skill-name>"; exit 1; fi
+        curl -s -X POST "$AGENT_URL/api/skills/fetch/$SKILL_NAME" -H "Authorization: Bearer $API_TOKEN" | jq .
+        ;;
+      list)
+        FLAG="${1:-}"
+        if [ "$FLAG" = "--local" ]; then
+          curl -s "$AGENT_URL/api/list-skills" -H "Authorization: Bearer $API_TOKEN" | jq .
+        else
+          curl -s "$AGENT_URL/api/skills/remote" -H "Authorization: Bearer $API_TOKEN" | jq .
+        fi
+        ;;
+      *)
+        echo "Usage: minion-cli-mac skill <push|fetch|list>"
+        ;;
+    esac
+    ;;
+
+  *)
+    echo "Minion Agent CLI (@geekbeer/minion macOS) v${CLI_VERSION}"
+    echo ""
+    echo "Usage:"
+    echo "  sudo minion-cli-mac setup --user <USERNAME>   # System setup (root): user, sudoers, Screen Sharing, plists"
+    echo "  minion-cli-mac configure [options]            # Connect to HQ (run as agent user)"
+    echo "  sudo minion-cli-mac uninstall [options]       # Remove agent and services (root)"
+    echo "  minion-cli-mac start                          # Bootstrap agent LaunchAgent"
+    echo "  minion-cli-mac stop                           # Bootout agent LaunchAgent"
+    echo "  minion-cli-mac restart                        # Kickstart agent LaunchAgent"
+    echo "  minion-cli-mac status                         # Get current status"
+    echo "  minion-cli-mac health                         # Health check"
+    echo "  minion-cli-mac diagnose                       # Run full service diagnostics"
+    echo "  minion-cli-mac set-status <status> [task]     # Set status and optional task"
+    echo "  minion-cli-mac skill <push|fetch|list>        # Manage skills with HQ"
+    echo "  minion-cli-mac --version                      # Show version"
+    echo ""
+    echo "Configure options:"
+    echo "  --hq-url <URL>        HQ server URL (required)"
+    echo "  --minion-id <UUID>    Minion ID (required)"
+    echo "  --api-token <TOKEN>   API token (required)"
+    echo "  --setup-tunnel        Set up cloudflared tunnel"
+    echo ""
+    echo "Status values: online, offline, busy"
+    echo ""
+    echo "Environment:"
+    echo "  MINION_AGENT_URL  Agent URL (default: http://localhost:8080)"
+    ;;
+esac