pairling 0.2.10 → 0.2.12

package/payload/mac/install/install-runtime.sh

@@ -33,7 +33,6 @@ PACKAGED_SOURCE_PATHS=(
   "mac/connectd/internal"
   "mac/connectd/go.mod"
   "mac/connectd/go.sum"
-  "mac/guardian"
   "mac/install"
   "mac/mcp"
 )
@@ -48,7 +47,6 @@ fi
 
 PAIRLING_RUNTIME_PORT="${PAIRLING_RUNTIME_PORT:-7773}"
 PAIRLING_DAEMON_LABEL="dev.pairling.companiond"
-PAIRLING_GUARDIAN_LABEL="dev.pairling.power-guardian"
 PAIRLING_CONNECTD_LABEL="dev.pairling.connectd"
 PAIRLING_PTYBROKER_LABEL="dev.pairling.ptybroker"
 APP_SUPPORT="${PAIRLING_APP_SUPPORT_ROOT:-${COMPANION_APP_SUPPORT_ROOT:-$HOME/Library/Application Support/Pairling}}"
@@ -57,6 +55,7 @@ RELEASES_ROOT="$RUNTIME_ROOT/releases"
 STATE_ROOT="$APP_SUPPORT/state"
 PAIR_ROOT="$APP_SUPPORT/pair"
 LOGS_ROOT="${PAIRLING_LOGS_ROOT:-${COMPANION_LOGS_ROOT:-$HOME/Library/Logs/Pairling}}"
+PAIRDROP_ROOT="${PAIRLING_PAIRDROP_ROOT:-$HOME/PairDrop}"
 PLIST_BUILD_DIR="$RUNTIME_ROOT/plists"
 CURRENT_LINK="$RUNTIME_ROOT/current"
 PREVIOUS_LINK="$RUNTIME_ROOT/previous"
@@ -69,11 +68,9 @@ INSTALL_HISTORY="$STATE_ROOT/install-history.jsonl"
 USER_PLIST="$HOME/Library/LaunchAgents/$PAIRLING_DAEMON_LABEL.plist"
 CONNECTD_USER_PLIST="$HOME/Library/LaunchAgents/$PAIRLING_CONNECTD_LABEL.plist"
 PTYBROKER_USER_PLIST="$HOME/Library/LaunchAgents/$PAIRLING_PTYBROKER_LABEL.plist"
-SYSTEM_PLIST="/Library/LaunchDaemons/$PAIRLING_GUARDIAN_LABEL.plist"
 MCP_SERVER_DIR="$HOME/.claude/mcp-servers"
 MCP_SERVER_SHIM="$MCP_SERVER_DIR/phone-tools.py"
 PYTHON3_BIN="${PAIRLING_DAEMON_PYTHON:-${COMPANION_DAEMON_PYTHON:-$(command -v python3)}}"
-GUARDIAN_PYTHON_BIN="${PAIRLING_GUARDIAN_PYTHON:-${COMPANION_GUARDIAN_PYTHON:-/usr/bin/python3}}"
 # P3 Python custody: the npm shim points PAIRLING_DAEMON_PYTHON at the vendored
 # CPython inside the platform runtime package (…/python/bin/python3). When that
 # is in play we stage the whole interpreter into the release tree and run the
@@ -100,6 +97,686 @@ is_dry_run() {
   [[ "$DRY_RUN" == "1" || "$DRY_RUN" == "true" || "$DRY_RUN" == "TRUE" ]]
 }
 
+# launchd_skipped is true when a testing smoke run asked us not to touch launchd,
+# so a real setup can render the polished screen without booting the dev.pairling
+# agents. is_dry_run already suppresses these launchctl calls in a preview. This
+# adds the explicit testing skip on top of that, mirroring the pattern in
+# mac/testing/reset-first-run-state.sh. A normal run leaves the variable unset,
+# so the check is false and launchctl runs exactly as before.
+launchd_skipped() {
+  [ "${PAIRLING_TESTING_SKIP_LAUNCHD:-0}" = 1 ]
+}
+
+setup_intro() {
+  # When the guided screen is on and this is not a dry run, draw the optional
+  # one-shot splash tied to a real recheck. It is bash-only and skippable, and it
+  # never aborts setup. The three plain log lines below are the WIZARD_TUI=0
+  # fallback and they always print.
+  if [ "${WIZARD_TUI:-0}" = 1 ] && ! is_dry_run; then
+    wizard_splash || true
+  fi
+  log "Pairling setup"
+  log "This stages the Mac runtime and opens a pairing code for the iPhone."
+  log ""
+}
+
+# ----- Guided setup: TTY-aware stage/progress wrapper -----
+# All guided output is plain printf and gated on one IS_TTY check, so it reads as
+# a clear numbered flow in a normal terminal and degrades to plain prefixed lines
+# in a pipe, in CI, or under the bootstrap-first-run.sh log capture. Setting
+# PAIRLING_GUIDED_PLAIN=1 forces the ASCII form even on a TTY.
+if [ -t 1 ] && [ "${PAIRLING_GUIDED_PLAIN:-0}" != "1" ]; then
+  GUIDED_TTY=1
+else
+  GUIDED_TTY=0
+fi
+GUIDED_STAGE_TOTAL=8
+GUIDED_STAGE_N=0
+GUIDED_STAGE_CURRENT=""
+GUIDED_COMPLETE=0
+# Set to 1 only before an integrity or code signature exit so guided_on_exit
+# shows the no-bypass fatal recovery menu instead of the recoverable one. It
+# stays 0 for every recoverable failure. Declared here so it is always defined
+# under set -u.
+WIZARD_FATAL=0
+
+# _machine_path_blocks: returns success when a machine condition should keep the
+# polished screen off, so both gate functions share one authoritative guard list.
+# It returns success for NO_COLOR, for CI, for a dry run, for the --json or
+# --plan-only arguments, and for a dumb, unknown, or empty TERM. It returns
+# failure when no machine condition blocks the screen. A future sixth guard is
+# added here once, so want_tui and want_tui_tty stay authoritative on every path.
+_machine_path_blocks() {
+  [ -n "${NO_COLOR:-}" ] && return 0
+  [ -n "${CI:-}" ] && return 0
+  [ -n "${PAIRLING_DRY_RUN:-}" ] && return 0
+  case " $* " in *" --json "*|*" --plan-only "*) return 0;; esac
+  case "${TERM:-dumb}" in dumb|unknown|"") return 0;; esac
+  return 1
+}
+
+# want_tui: the single decision that keeps the polished screen off every machine
+# path. It returns success only when the guided screen should render. It returns
+# failure for a non-terminal stdout and for every machine condition in
+# _machine_path_blocks, which are NO_COLOR, CI, a dry run, the --json or
+# --plan-only arguments, and a dumb or unknown terminal. The bash spine runs the
+# plain numbered flow whenever this returns failure, so machine output stays
+# byte-for-byte the same. The --json and --plan-only checks are defensive only,
+# because those flags do not reach install_runtime on the setup arm today. The
+# gate checks them so the function stays correct if a future caller ever threads
+# them in.
+want_tui() {
+  [ -t 1 ] || return 1
+  _machine_path_blocks "$@" && return 1
+  return 0
+}
+
+# want_tui_tty: the first-run variant of the gate. The first-run flow pipes our
+# stdout through tee, so [ -t 1 ] is false even though a controlling terminal
+# still exists, and want_tui returns failure for that reason alone. This variant
+# skips only the stdout tty check. It still fails for every machine condition in
+# _machine_path_blocks, so NO_COLOR, CI, a dry run, --json, --plan-only, and a
+# dumb or unknown TERM still disable the screen on the first-run path. It then
+# proves a controlling terminal with a real write to /dev/tty, so only a true
+# controlling terminal enables the screen. The device node can test as writable
+# with no controlling terminal, so the guard writes one empty line instead of
+# testing -w.
+want_tui_tty() {
+  _machine_path_blocks "$@" && return 1
+  { : >/dev/tty; } 2>/dev/null || return 1
+  return 0
+}
+
+# wizard_splash_verify: the real recheck the splash result is tied to. It runs a
+# bounded integrity recheck of the staged release. Before staging there is no
+# staged binary, so it returns 0, which means there is nothing to contradict yet.
+# The splash runs in setup_intro, before copy_release, so this is bash-only and
+# starts no python. A real per-file hash recheck happens later in the doctor gate,
+# so the splash result is honest about what it can confirm at intro time.
+wizard_splash_verify() {
+  local binary="$CURRENT_LINK/connectd/pairling-connectd"
+  if [ -x "$binary" ]; then
+    /usr/bin/codesign --verify --strict "$binary" >/dev/null 2>&1 || return 1
+  fi
+  return 0
+}
+
+# wizard_splash: an optional one-shot brand beat under about 800 milliseconds.
+# It is bash-only, because it runs before the python is staged. It draws a boxed
+# brand header, the brand word in the accent-to-e-ink gradient and the tagline in
+# paper, then a short non-interactive spinner with sleep 0.08, which bash
+# 3.2.57 allows, then prints a result tied to the recheck. It renders only when
+# GUIDED_TTY is 1, so it follows the same guided screen gate as the numbered
+# stages. GUIDED_TTY is 1 exactly when WIZARD_TUI is 1 and PAIRLING_GUIDED_PLAIN
+# is not 1, so the splash renders on the first-run path where GUIDED_TTY is 1 and
+# the knob is unset, it honors the PAIRLING_GUIDED_PLAIN opt-out and stays plain
+# when that knob is set, and it stays silent on every machine path where
+# GUIDED_TTY is 0. Whether it drops the spinner is decided by reduced_motion_on,
+# which honors PAIRLING_REDUCED_MOTION first and otherwise reads the macOS
+# ReduceMotionEnabled setting. When reduce motion is on it skips the spinner and
+# still prints the brand line and the result line. This
+# is the most cuttable piece of the wizard. If it ever adds risk, drop it and keep
+# the plain intro.
+# reduced_motion_on: decide whether the splash should drop its spinner. The
+# explicit PAIRLING_REDUCED_MOTION knob wins when set to any non-empty value,
+# matching the prior behavior. When it is unset, fall back to the macOS system
+# setting com.apple.Accessibility ReduceMotionEnabled. defaults exits non-zero
+# and prints nothing when that key was never written, so a missing key reads as
+# reduce motion off and the helper returns non-zero, so the spinner runs. A
+# stored value of 1 means reduce motion
+# is on. DEFAULTS_BIN defaults to the pinned /usr/bin/defaults and exists only
+# so tests can point it at a stub.
+reduced_motion_on() {
+  if [ "${PAIRLING_REDUCED_MOTION:-}" != "" ]; then
+    return 0
+  fi
+  [ "$("${DEFAULTS_BIN:-/usr/bin/defaults}" read com.apple.Accessibility ReduceMotionEnabled 2>/dev/null)" = 1 ]
+}
+# wizard_palette_init: detect the terminal color tier and set the brand palette
+# variables the guided splash, the box helpers, and the stage markers read. It
+# mirrors the tier detection in mac/docs/setup-wizard-mockup-bash.sh. The tier is
+# true when COLORTERM is truecolor or 24bit, else 256 when tput reports at least
+# 256 colors, else 16 when tput reports at least 8, else none. NO_COLOR forces the
+# none tier. Each palette variable carries a real escape string spelled with the
+# file's \033[ CSI prefix, and is empty in the none tier so a no-color terminal
+# gets plain text. WZ_ERR is a clear error red for the splash failure marker, kept
+# distinct from the warm brand accent and consistent across tiers, so a failure
+# never reads as the brand. The function is idempotent through the WZ_PALETTE_READY guard
+# and never prints, so the load-time call, the defensive call in wizard_splash, and
+# the calls in the stage markers cost only one string test after the first.
+wizard_palette_init() {
+  [ "${WZ_PALETTE_READY:-0}" = 1 ] && return 0
+  WZ_TIER="none"
+  if [ -z "${NO_COLOR:-}" ]; then
+    if [ "${COLORTERM:-}" = "truecolor" ] || [ "${COLORTERM:-}" = "24bit" ]; then
+      WZ_TIER="true"
+    elif [ "$(tput colors 2>/dev/null || echo 0)" -ge 256 ]; then
+      WZ_TIER="256"
+    elif [ "$(tput colors 2>/dev/null || echo 0)" -ge 8 ]; then
+      WZ_TIER="16"
+    fi
+  fi
+  case "$WZ_TIER" in
+    true)
+      WZ_ACCENT=$'\033[38;2;226;70;42m'; WZ_EINK=$'\033[38;2;168;51;28m'
+      WZ_PAPER=$'\033[38;2;231;228;216m'; WZ_OK=$'\033[38;2;120;170;90m'
+      WZ_GREY=$'\033[38;2;150;145;135m'; WZ_ERR=$'\033[38;2;208;48;48m' ;;
+    256)
+      WZ_ACCENT=$'\033[38;5;166m'; WZ_EINK=$'\033[38;5;130m'
+      WZ_PAPER=$'\033[38;5;223m'; WZ_OK=$'\033[38;5;107m'; WZ_GREY=$'\033[38;5;244m'
+      WZ_ERR=$'\033[38;5;160m' ;;
+    16)
+      WZ_ACCENT=$'\033[91m'; WZ_EINK=$'\033[31m'; WZ_PAPER=$'\033[37m'
+      WZ_OK=$'\033[32m'; WZ_GREY=$'\033[90m'; WZ_ERR=$'\033[31m' ;;
+    *)
+      WZ_ACCENT=""; WZ_EINK=""; WZ_PAPER=""; WZ_OK=""; WZ_GREY=""; WZ_ERR="" ;;
+  esac
+  WZ_PALETTE_READY=1
+  return 0
+}
+
+# wizard_gradient: print text in the brand gradient, accent (226,70,42) sweeping to
+# e-ink (168,51,28), one color step per character. It ports the mockup gradient and
+# runs the per-character sweep only in the true tier, where 24-bit color exists. In
+# every other tier it prints the whole text in bold accent. bash 3.2.57 arithmetic
+# evaluates the n>1 ternary, and the d guard keeps a single-character word from
+# dividing by zero. It emits no trailing reset, so the caller closes the color.
+wizard_gradient() {
+  local text="$1"
+  if [ "${WZ_TIER:-none}" != "true" ]; then
+    printf '\033[1m%s%s\033[0m' "${WZ_ACCENT:-}" "$text"
+    return 0
+  fi
+  local n=${#text} i=0 ch r g b d
+  d=$(( n > 1 ? n - 1 : 1 ))
+  while [ "$i" -lt "$n" ]; do
+    ch="${text:$i:1}"
+    r=$(( 226 - (58 * i / d) ))
+    g=$(( 70 - (19 * i / d) ))
+    b=$(( 42 - (14 * i / d) ))
+    printf '\033[38;2;%d;%d;%dm\033[1m%s' "$r" "$g" "$b" "$ch"
+    i=$((i + 1))
+  done
+  return 0
+}
+
+# wizard_progress_bar: print a fixed-width brand progress bar, accent-filled cells
+# for the completed fraction and grey empty cells for the rest. It ports the bar in
+# mac/docs/setup-wizard-mockup-bash.sh and reads the palette WZ_ACCENT and WZ_GREY,
+# each with a set -u default so a direct caller before wizard_palette_init still
+# runs. The fill glyph and the empty glyph are held in variables and appended as
+# ${s}${glyph}, never as a glyph written right after a variable expansion, because
+# bash 3.2.57 under set -u misparses a multibyte glyph placed directly after $var.
+# The total is guarded to at least one so a zero total never divides by zero, even
+# though every caller passes the fixed stage total. A single trailing reset closes
+# the color, matching the stage header, which already emits escapes in its TTY branch.
+wizard_progress_bar() {
+  local done="$1" total="$2" width=34 fill i s='' full='█' empty='░'
+  [ "$total" -gt 0 ] || total=1
+  fill=$(( width * done / total ))
+  i=0
+  while [ "$i" -lt "$width" ]; do
+    if [ "$i" -lt "$fill" ]; then
+      s="${s}${WZ_ACCENT:-}${full}"
+    else
+      s="${s}${WZ_GREY:-}${empty}"
+    fi
+    i=$((i + 1))
+  done
+  printf '%s\033[0m' "$s"
+}
+
+# wizard_line_h: print one character repeated width times, used for the horizontal
+# rules inside the box borders. It holds the repeat character in a variable and
+# appends it as ${s}${c}, never as a literal glyph placed directly after $s, because
+# bash 3.2.57 under set -u misparses a multibyte glyph written right after a
+# variable expansion as part of the variable name.
+wizard_line_h() {
+  local w="$1" c="$2" s="" i=0
+  while [ "$i" -lt "$w" ]; do s="${s}${c}"; i=$((i + 1)); done
+  printf '%s' "$s"
+}
+
+# wizard_box_top / wizard_box_bot: draw the rounded top and bottom borders of the
+# header box in e-ink. The box glyphs sit in the printf format string, not after a
+# variable expansion, so the multibyte parse hazard does not apply here.
+wizard_box_top() {
+  printf '  %s╭%s╮\033[0m\n' "${WZ_EINK:-}" "$(wizard_line_h "$1" "─")"
+}
+
+wizard_box_bot() {
+  printf '  %s╰%s╯\033[0m\n' "${WZ_EINK:-}" "$(wizard_line_h "$1" "─")"
+}
+
+# wizard_box_row: draw one content row of the header box. It takes the inner width,
+# a plain copy of the text used only to size the right pad, and the styled text
+# printed between the borders. It pads to the width with spaces so the right border
+# lines up, and clamps a negative pad to zero when the text is wider than the box.
+wizard_box_row() {
+  local w="$1" plain="$2" styled="$3" pad
+  pad=$(( w - 2 - ${#plain} )); [ "$pad" -lt 0 ] && pad=0
+  printf '  %s│\033[0m %s%s %s│\033[0m\n' "${WZ_EINK:-}" "$styled" "$(wizard_line_h "$pad" " ")" "${WZ_EINK:-}"
+}
+
+wizard_splash() {
+  [ "${GUIDED_TTY:-0}" = 1 ] || return 0
+  wizard_palette_init
+  local inner=54 row1 row2
+  # printf turns \033 into a real escape byte, so the captured rows carry real
+  # escapes for wizard_box_row to place between the borders. row1 is the gradient
+  # brand word, a reset to drop the gradient bold, then the paper tagline. The
+  # plain-copy arguments size the right pad and never reach the screen.
+  row1="$(wizard_gradient "Pairling"; printf '\033[0m%s   Pair your iPhone with your coding agents' "$WZ_PAPER")"
+  row2="${WZ_PAPER}           on this Mac."
+  wizard_box_top "$inner"
+  wizard_box_row "$inner" "Pairling   Pair your iPhone with your coding agents" "$row1"
+  wizard_box_row "$inner" "           on this Mac." "$row2"
+  wizard_box_bot "$inner"
+  if ! reduced_motion_on; then
+    local frames='⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏' f
+    for f in $frames; do
+      printf '\r  %s%s\033[0m %sVerifying the staged runtime\033[0m' "$WZ_ACCENT" "$f" "$WZ_GREY"
+      sleep 0.08
+    done
+    printf '\r'
+  fi
+  if wizard_splash_verify; then
+    printf '  %sok\033[0m Runtime verified.            \n' "$WZ_OK"
+  else
+    printf '  %sx\033[0m Runtime check failed. See the steps below.\n' "${WZ_ERR:-}"
+  fi
+  return 0
+}
+
+# safety_status_line: print the live SafetyMonitorBridge status as one parseable
+# line. It runs as "$PYTHON3_BIN", the staged vendored python, and imports the
+# bridge from the staged companiond, exactly as doctor.sh and pairlingd.py do. It
+# constructs the bridge as SafetyMonitorBridge(APP_SUPPORT_ROOT, HOME), the same
+# construction the daemon uses. It never reads a TCC store and never calls the
+# safety HTTP routes, which need a device bearer token the local wizard does not
+# have. The companiond dir and the app support root are passed as argv, so an
+# install path with a space is passed whole. On any failure it prints
+# installed=false, so the caller fails closed to the not-installed advisory.
+safety_status_line() {
+  "$PYTHON3_BIN" - "$CURRENT_LINK/companiond" "$APP_SUPPORT" <<'PY' 2>/dev/null || printf 'installed=false full_disk_access=unknown\n'
+import os
+import sys
+from pathlib import Path
+
+companiond_dir = sys.argv[1]
+app_support_root = Path(sys.argv[2])
+sys.path.insert(0, companiond_dir)
+try:
+    from safety_monitor import SafetyMonitorBridge
+    bridge = SafetyMonitorBridge(app_support_root, Path(os.path.expanduser("~")))
+    status = bridge.status()
+    installed = "true" if status.get("installed") else "false"
+    fda = str(status.get("full_disk_access") or "unknown")
+except Exception:
+    installed, fda = "false", "unknown"
+print("installed=%s full_disk_access=%s" % (installed, fda))
+PY
+}
+
+# safety_status_installed: return 0 when the bridge reports installed true, 1
+# when it reports installed false, and the not-installed advisory path handles
+# both 1 and any read failure, which also prints installed=false. The reader is
+# the single source of truth for whether the future PairlingSafety.app is present.
+safety_status_installed() {
+  case "$(safety_status_line)" in
+    *"installed=true"*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+# stage_begin: print the numbered header for one guided stage. The TTY branch keeps
+# the bold [N/total] prefix, pads the title to a fixed field so the bar aligns across
+# stages, then draws the brand progress bar filled to the current stage over the
+# total, so the bar fills as the flow advances. It calls wizard_palette_init, which is
+# idempotent, so the bar colors exist even if a caller reaches here first. The plain
+# GUIDED_TTY=0 branch is unchanged and stays byte-identical, so every machine path
+# keeps the exact \n[N/total] Title\n form with no bar and no escape byte.
+stage_begin() {
+  GUIDED_STAGE_N=$((GUIDED_STAGE_N + 1))
+  GUIDED_STAGE_CURRENT="$1"
+  if [ "$GUIDED_TTY" = 1 ]; then
+    wizard_palette_init
+    printf '\n\033[1m[%d/%d] %-30s\033[0m  %s\n' \
+      "$GUIDED_STAGE_N" "$GUIDED_STAGE_TOTAL" "$1" \
+      "$(wizard_progress_bar "$GUIDED_STAGE_N" "$GUIDED_STAGE_TOTAL")"
+  else
+    printf '\n[%d/%d] %s\n' "$GUIDED_STAGE_N" "$GUIDED_STAGE_TOTAL" "$1"
+  fi
+}
+
+stage_ok() {
+  if [ "$GUIDED_TTY" = 1 ]; then
+    wizard_palette_init
+    printf '  %sok\033[0m %s\n' "$WZ_OK" "$1"
+  else
+    printf '  ok: %s\n' "$1"
+  fi
+}
+
+stage_skip() {
+  if [ "$GUIDED_TTY" = 1 ]; then
+    wizard_palette_init
+    printf '  %s--\033[0m %s\n' "$WZ_GREY" "$1"
+  else
+    printf '  skip: %s\n' "$1"
+  fi
+}
+
+stage_note() {
+  printf '     %s\n' "$1"
+}
+
+# wizard_recovery_menu: a plain bash recovery menu. It uses a plain blocking
+# read with no timeout, which bash 3.2.57 supports, so it works without any
+# python. The recoverable kind offers open Full Disk Access settings, skip, and
+# quit and resume. The fatal kind, an integrity or signature failure,
+# has no retry and no skip, which mirrors the install script that exits with no
+# bypass on a hash mismatch or a code-signature failure. When stdin is not a
+# terminal it prints the options and returns, so a headless or piped run never
+# blocks. open_full_disk_access_pane is defined by the safety step and runs the
+# bridge open_full_disk_access method.
+wizard_recovery_menu() {
+  local kind="$1" stage="$2"
+  if [ "$kind" = "fatal" ]; then
+    stage_note "Pairling stopped to protect your Mac at the $stage step."
+    stage_note "A file did not match its signed checksum, so setup will not continue. There is no way to skip this check."
+    stage_note "Options: [1] reinstall from a verified copy   [2] view logs   [q] quit"
+  else
+    stage_note "Setup needs your help at the $stage step."
+    stage_note "Options: [o] open Full Disk Access settings   [s] skip for now   [q] quit and resume"
+  fi
+  # Off a terminal, print the options and return without blocking.
+  [ -t 0 ] || return 0
+  local choice=""
+  while :; do
+    printf '  Choose an option: '
+    read -r choice || return 0
+    case "$kind:$choice" in
+      # Retry was removed here because no caller loops on the menu return today.
+      # In guided_on_exit the process is already exiting, and in safety_step the
+      # evidence poll has already timed out before the menu shows, so an [r] key
+      # did nothing. When the future PairlingSafety.app makes the evidence poll
+      # live, add a real retry loop in safety_step with a distinct menu return
+      # code, then reinstate an [r] option that maps to it. An r keypress now
+      # falls through to the reprompt below, which is correct.
+      recoverable:o|recoverable:O) open_full_disk_access_pane ;;
+      recoverable:s|recoverable:S) stage_note "Skipped. You can grant it later and run pairling setup again."; return 0 ;;
+      *:q|*:Q) stage_note "Quitting. Run pairling setup again to resume right here."; return 0 ;;
+      fatal:1) stage_note "Reinstall Pairling from a verified copy, then run pairling setup again."; return 0 ;;
+      fatal:2) stage_note "The full details are in the setup log under the audit folder."; return 0 ;;
+      *) stage_note "Pick one of the listed options." ;;
+    esac
+  done
+}
+
+# safety_call_method: run one no-argument SafetyMonitorBridge method as the
+# staged python and print whatever the method returns as a single status word.
+# It imports the bridge from the staged companiond and constructs it the same
+# way the daemon does. The method name is passed as argv, so the python source
+# is fixed. It is used by request_safety_activation, open_full_disk_access_pane,
+# and poll_evidence_test, so they all share one import path.
+safety_call_method() {
+  local method="$1"
+  "$PYTHON3_BIN" - "$CURRENT_LINK/companiond" "$APP_SUPPORT" "$method" <<'PY' 2>/dev/null || printf 'error\n'
+import os
+import sys
+from pathlib import Path
+
+companiond_dir, app_support_root, method = sys.argv[1], Path(sys.argv[2]), sys.argv[3]
+sys.path.insert(0, companiond_dir)
+try:
+    from safety_monitor import SafetyMonitorBridge
+    bridge = SafetyMonitorBridge(app_support_root, Path(os.path.expanduser("~")))
+    result = getattr(bridge, method)()
+    # request_activation returns "state", run_evidence_test returns "status",
+    # open_full_disk_access returns "state". Print the first present one.
+    word = result.get("status") or result.get("state") or ("ok" if result.get("ok") else "error")
+    print(word)
+except Exception:
+    print("error")
+PY
+}
+
+# request_safety_activation: guide System Extension approval through the bridge.
+# It only runs when the app is installed, so the bridge launches
+# PairlingSafety.app --pairling-request-activation. The wizard never claims it
+# installed the app.
+request_safety_activation() {
+  local state
+  state="$(safety_call_method request_activation)"
+  if [ "$state" = "approval_requested" ]; then
+    stage_note "Approve Pairling Safety Monitor in System Settings, then come back here."
+  else
+    stage_note "Could not request Safety Monitor approval right now. You can approve it later in System Settings."
+  fi
+}
+
+# open_full_disk_access_pane: open the Full Disk Access settings page through the
+# bridge open_full_disk_access method, which runs the open command for the
+# Privacy_AllFiles anchor. The wizard does not change any privacy setting itself.
+open_full_disk_access_pane() {
+  safety_call_method open_full_disk_access >/dev/null 2>&1 || true
+  stage_note "Turn on Full Disk Access for Pairling Safety Monitor, then come back here."
+}
+
+# poll_evidence_test: re-run the bridge run_evidence_test every two seconds until
+# it reports passed or the time runs out. It uses sleep, not a fractional read,
+# because bash 3.2.57 rejects a sub-second read timeout. It returns 0 on a passed
+# result and 124 on timeout. A "limited" result means process evidence passed but
+# file visibility still needs Full Disk Access, so the loop keeps waiting. The
+# interval and timeout are overridable for tests. The step clamp keeps waited
+# advancing even when the interval is 0, so an always-limited result cannot loop
+# forever.
+poll_evidence_test() {
+  local interval="${PAIRLING_SAFETY_POLL_INTERVAL:-2}"
+  local timeout="${PAIRLING_SAFETY_POLL_TIMEOUT:-300}"
+  local step="$interval"
+  [ "$step" -lt 1 ] && step=1
+  local waited=0 result
+  while [ "$waited" -le "$timeout" ]; do
+    result="$(safety_call_method run_evidence_test)"
+    if [ "$result" = "passed" ]; then
+      return 0
+    fi
+    [ "$waited" -ge "$timeout" ] && break
+    sleep "$interval"
+    waited=$((waited + step))
+  done
+  return 124
+}
+
+# safety_step: the one safety gate in v1. It reads the live SafetyMonitorBridge
+# status. Today the app is not installed, so the bridge reports installed false,
+# and this prints one plain advisory line that the Safety Monitor is a future
+# feature and is not installed, and that pairing works without it, then continues.
+# It never claims it installed the app. It never shows or blocks on Full Disk
+# Access when the app is absent. When a future PairlingSafety.app reports
+# installed true, the same flow guides System Extension approval, then Full Disk
+# Access, then polls the evidence test until file evidence passes, advancing on
+# pass or showing the recovery menu on timeout. It never blocks pairing and
+# always returns 0.
+safety_step() {
+  if safety_status_installed; then
+    stage_note "Pairling Safety Monitor is installed. Setting it up so it can watch your agent sessions."
+    request_safety_activation
+    open_full_disk_access_pane
+    stage_note "Checking that the Safety Monitor can see process and file evidence. We check every 2 seconds."
+    if poll_evidence_test; then
+      stage_note "The Safety Monitor sees full evidence. Thank you."
+    else
+      stage_note "The Safety Monitor did not reach full file evidence within the time limit."
+      # A skip never blocks pairing. File visibility is the only thing limited
+      # until Full Disk Access is granted.
+      wizard_recovery_menu recoverable "macOS permissions" || true
+    fi
+  else
+    # The not-installed advisory. This is today's path. It states the truth: the
+    # Safety Monitor is a future feature, it is not installed, and pairing works
+    # without it. It never claims setup installed anything.
+    stage_note "Pairling Safety Monitor is a future feature and is not installed yet. Pairing works without it."
+  fi
+  stage_note "On first pair your iPhone asks for Local Network access, so allow it. This Mac and the iPhone must be on the same Wi-Fi so the Mac can see the phone."
+  stage_note "If Local Network is allowed and pairing still stalls, the block is on the Mac or the network side, not the iPhone."
+  stage_note "Accessibility and Automation are only needed later if you enable typing into Terminal from the phone. Run pairling doctor --json to see the exact Mac grantee path before enabling it."
+  return 0
+}
+
+# guided_on_exit — fires on ANY premature exit during setup (a set -e abort or an
+# explicit exit 1 in staging, service startup, the QR, or auth), so a failure
+# always leaves a clear recovery path. Suppressed once setup sets
+# GUIDED_COMPLETE=1, so a clean run prints nothing here.
+guided_on_exit() {
+  local code=$?
+  if [ "$GUIDED_COMPLETE" != 1 ] && [ "$code" != 0 ]; then
+    if [ "${WIZARD_TUI:-0}" = 1 ]; then
+      # Show the bash recovery menu. The kind is recoverable by default. The
+      # caller sets WIZARD_FATAL=1 before a fatal integrity or signature exit, so
+      # the menu drops retry and skip to mirror this script's no-bypass behavior.
+      if [ "${WIZARD_FATAL:-0}" = 1 ]; then
+        wizard_recovery_menu fatal "${GUIDED_STAGE_CURRENT:-startup}" || true
+      else
+        wizard_recovery_menu recoverable "${GUIDED_STAGE_CURRENT:-startup}" || true
+      fi
+    fi
+    printf '\nSetup did not finish (stage: %s, exit %s).\n' "${GUIDED_STAGE_CURRENT:-startup}" "$code" >&2
+    printf 'Recovery: run `pairling doctor --json` to inspect, then re-run `pairling setup`.\n' >&2
+    printf 'Retry pairing only: `pairling pair --qr`. Sign in to Pairling Connect: `pairling connect-auth-open`.\n' >&2
+  fi
+}
+
+# guided_permission_notice — advisory only. Surfaces ONLY the permissions the
+# code actually uses (verified against doctor.sh permission_readiness): the
+# iPhone shows a Local Network prompt on first pair, and this Mac needs no
+# privacy permission for basic pairing. It never reads or modifies any privacy
+# setting and never blocks setup.
+guided_permission_notice() {
+  stage_note "This Mac needs no special privacy permission to pair."
+  stage_note "On your iPhone allow Local Network access when Pairling asks. This Mac and the iPhone must be on the same Wi-Fi so the Mac can see the phone."
+  stage_note "If you already allowed Local Network on the iPhone and pairing still stalls, the block is on the Mac or the network, not the iPhone. Check that both devices are on the same Wi-Fi."
+  stage_note "Accessibility and Automation are only needed if you later enable typing into Terminal from the phone. Run pairling doctor --json to see the exact Mac grantee path before enabling it."
+}
+
+# guided_route_proof — one bounded, best-effort read of connectd /status that
+# tells the user whether the remote Pairling Connect route is live yet. Local and
+# LAN pairing already work regardless of the result. This never blocks or fails
+# setup (the whole probe is wrapped in `|| true`).
+guided_route_proof() {
+  python3 - "$REPO_ROOT" <<'PY' || true
+import os
+import sys
+
+repo_root = sys.argv[1]
+sys.path.insert(0, os.path.join(repo_root, "mac", "companiond"))
+try:
+    from pairling_connectd_status import fetch_connectd_status, advertised_pairling_connect_routes
+except Exception:
+    sys.exit(0)
+
+status = fetch_connectd_status(timeout_seconds=0.7) or {}
+try:
+    routes = advertised_pairling_connect_routes(status)
+except Exception:
+    routes = []
+
+if routes:
+    print("     Route check: the Pairling Connect remote route is ready.")
+elif str(status.get("auth_state") or "") == "authenticated":
+    print("     Route check: Pairling Connect is signed in; the remote route will advertise shortly.")
+else:
+    print("     Route check: local pairing is ready now; the remote route hardens after you sign in and the phone joins.")
+PY
+}
+
+# guided_pairing_seen_proof is one bounded, best-effort, read-only check of the
+# devices database that tells the user whether this Mac has recorded the iPhone
+# finishing pairing in this session. It takes the session-start epoch as its
+# first argument, so a device paired in an earlier run does not read as seen on a
+# re-run. It opens the database read-only with mode=ro, so it never locks the
+# file the daemon is writing, and it treats a missing or empty database or any
+# sqlite error as "not seen". It polls up to about 6 seconds at 1 second steps
+# and exits early the moment a matching device appears, so a scanned phone is
+# confirmed within about a second and only an unscanned run waits the full
+# window. The whole probe is wrapped in `|| true`, so it never blocks or fails
+# setup.
+guided_pairing_seen_proof() {
+  local since="${1:-0}"
+  PAIRLING_PAIRING_SEEN_POLL_STEPS="${PAIRLING_PAIRING_SEEN_POLL_STEPS:-6}" \
+    python3 - "$DEVICES_DB" "$since" <<'PY' || true
+import os
+import sqlite3
+import sys
+import time
+
+db_path = sys.argv[1] if len(sys.argv) > 1 else ""
+try:
+    since = float(sys.argv[2])
+except (IndexError, ValueError):
+    since = 0.0
+try:
+    steps = int(os.environ.get("PAIRLING_PAIRING_SEEN_POLL_STEPS") or "6")
+except ValueError:
+    steps = 6
+if steps < 1:
+    steps = 1
+
+def count_session_devices():
+    # Open read-only with mode=ro so this never locks or creates the database the
+    # daemon is writing. Count only non-revoked rows created at or after the
+    # session start, so a device from an earlier run does not read as seen.
+    con = sqlite3.connect("file:" + db_path + "?mode=ro", uri=True, timeout=0.5)
+    try:
+        row = con.execute(
+            "SELECT COUNT(*) FROM devices WHERE revoked_at IS NULL AND created_at >= ?",
+            (since,),
+        ).fetchone()
+        return int(row[0]) if row else 0
+    finally:
+        con.close()
+
+seen = 0
+try:
+    for step in range(steps):
+        try:
+            seen = count_session_devices()
+        except Exception:
+            # A missing or empty database, or any sqlite error, means not seen.
+            seen = 0
+        if seen > 0:
+            break
+        if step < steps - 1:
+            time.sleep(1)
+    if seen > 0:
+        print("     Pairing check: this Mac saw your iPhone connect and finish pairing.")
+    else:
+        print("     Pairing check: this Mac has not recorded your iPhone finishing pairing yet.")
+        print("     If you just scanned the code, give it a moment and it should appear.")
+        print("     If it keeps stalling, confirm the iPhone allowed Local Network and both devices are on the same Wi-Fi.")
+except Exception:
+    # Any unexpected error means not seen. Never raise, so setup continues.
+    pass
+sys.exit(0)
+PY
+}
+
+# guided_finish_summary — the success and recovery surface. It states the next
+# device step, proves the route, and prints the exact re-run commands for any
+# step the operator may need to repeat.
+guided_finish_summary() {
+  stage_note "The pairing code is shown above. Open Pairling on your iPhone, scan it, then approve this Mac."
+  if ! is_dry_run; then
+    guided_route_proof || true
+  fi
+  if ! is_dry_run; then guided_pairing_seen_proof "${PAIRLING_PAIRING_STARTED_AT:-0}" || true; fi
+  stage_note "Inspect status anytime:        pairling doctor --json"
+  stage_note "Re-show the pairing code:       pairling pair --qr"
+  stage_note "Sign in for the remote route:   pairling connect-auth-open"
+}
+
 append_history() {
   local status="$1"
   local detail="$2"
@@ -165,8 +842,6 @@ run_compile_checks() {
   PYTHONPYCACHEPREFIX="$pycache_root" python3 -m py_compile "$REPO_ROOT/mac/companiond/providers/external.py"
   PYTHONPYCACHEPREFIX="$pycache_root" python3 -m py_compile "$REPO_ROOT/mac/companiond/providers/registry.py"
   PYTHONPYCACHEPREFIX="$pycache_root" python3 -m py_compile "$REPO_ROOT/mac/mcp/phone_tools.py"
-  PYTHONPYCACHEPREFIX="$pycache_root" python3 -m py_compile "$REPO_ROOT/mac/guardian/companion-power-guardian.py"
-  PYTHONPYCACHEPREFIX="$pycache_root" python3 -m py_compile "$REPO_ROOT/mac/guardian/guardian_contract.py"
   PYTHONPYCACHEPREFIX="$pycache_root" python3 -m py_compile "$REPO_ROOT/mac/install/render-launchd.py"
   PYTHONPYCACHEPREFIX="$pycache_root" python3 -m py_compile "$REPO_ROOT/mac/install/psk_dependency_check.py"
   rm -rf "$pycache_root"
@@ -266,10 +941,43 @@ clear_release_quarantine() {
   fi
 }
 
+ensure_pairdrop_folder() {
+  mkdir -p "$PAIRDROP_ROOT"
+  chmod 700 "$PAIRDROP_ROOT" 2>/dev/null || true
+  local probe="$PAIRDROP_ROOT/.pairling-write-test.$$"
+  if ! printf 'ok\n' > "$probe" 2>/dev/null; then
+    log "ERROR: PairDrop folder is not writable: $(display_path "$PAIRDROP_ROOT")" >&2
+    exit 1
+  fi
+  rm -f "$probe"
+  log "PairDrop folder: $(display_path "$PAIRDROP_ROOT")"
+}
+
+payload_manifest_path() {
+  local candidate="$REPO_ROOT/../payload-manifest.json"
+  if [[ -f "$candidate" ]]; then
+    printf '%s\n' "$candidate"
+  fi
+}
+
+verify_payload_manifest() {
+  local manifest
+  manifest="$(payload_manifest_path)"
+  if [[ -z "$manifest" ]]; then
+    return 0
+  fi
+  log "Verifying npm payload manifest"
+  if ! "$PYTHON3_BIN" "$REPO_ROOT/mac/install/verify-payload-manifest.py" "$REPO_ROOT" "$manifest"; then
+    WIZARD_FATAL=1
+    exit 1
+  fi
+}
+
 copy_release() {
   local tmp="$RELEASE_ROOT.tmp"
   rm -rf "$tmp"
-  mkdir -p "$tmp/bin" "$tmp/companiond" "$tmp/companiond/providers" "$tmp/companiond/integrations/aperture_cli" "$tmp/connectd" "$tmp/guardian" "$tmp/mac" "$tmp/mcp"
+  verify_payload_manifest
+  mkdir -p "$tmp/bin" "$tmp/companiond" "$tmp/companiond/providers" "$tmp/companiond/integrations/aperture_cli" "$tmp/connectd" "$tmp/mac" "$tmp/mcp"
   cp "$REPO_ROOT/mac/companiond/pairlingd.py" "$tmp/companiond/"
   cp "$REPO_ROOT/mac/companiond/runtime_contract.py" "$tmp/companiond/"
   cp "$REPO_ROOT/mac/companiond/runtime_manifest.py" "$tmp/companiond/"
@@ -303,19 +1011,17 @@ copy_release() {
   cp "$REPO_ROOT/mac/companiond/integrations/aperture_cli/"*.py "$tmp/companiond/integrations/aperture_cli/"
   cp "$REPO_ROOT/mac/companiond/providers/"*.py "$tmp/companiond/providers/"
   cp "$REPO_ROOT/mac/mcp/phone_tools.py" "$tmp/mcp/"
-  cp "$REPO_ROOT/mac/guardian/companion-power-guardian.py" "$tmp/guardian/"
-  cp "$REPO_ROOT/mac/guardian/guardian_contract.py" "$tmp/guardian/"
   build_connectd_binary "$tmp/connectd/pairling-connectd"
   stage_vendored_python "$tmp/python"
   run_staged_psk_dependency_checks "$tmp"
   copy_runtime_source_tree "$tmp/mac" "$tmp/connectd/pairling-connectd"
   write_installed_pairling_launcher "$tmp/bin/pairling"
-  chmod 755 "$tmp/bin/pairling" "$tmp/companiond/pairlingd.py" "$tmp/mcp/phone_tools.py" "$tmp/guardian/companion-power-guardian.py"
+  chmod 755 "$tmp/bin/pairling" "$tmp/companiond/pairlingd.py" "$tmp/mcp/phone_tools.py"
   chmod 755 "$tmp/connectd/pairling-connectd"
-  chmod 644 "$tmp/companiond/"*.py "$tmp/mcp/"*.py "$tmp/guardian/"*.py
+  chmod 644 "$tmp/companiond/"*.py "$tmp/mcp/"*.py
   chmod 644 "$tmp/companiond/providers/"*.py
   chmod 644 "$tmp/companiond/integrations/"*.py "$tmp/companiond/integrations/aperture_cli/"*.py
-  chmod 755 "$tmp/companiond/pairlingd.py" "$tmp/mcp/phone_tools.py" "$tmp/guardian/companion-power-guardian.py"
+  chmod 755 "$tmp/companiond/pairlingd.py" "$tmp/mcp/phone_tools.py"
   clear_release_quarantine "$tmp"
   rm -rf "$RELEASE_ROOT"
   mv "$tmp" "$RELEASE_ROOT"
@@ -330,7 +1036,6 @@ copy_runtime_source_tree() {
     "$mac_root/companiond/providers" \
     "$mac_root/companiond/integrations/aperture_cli" \
     "$mac_root/connectd/bin" \
-    "$mac_root/guardian" \
     "$mac_root/install" \
     "$mac_root/mcp" \
     "$mac_root/packaging/bin"
@@ -351,7 +1056,6 @@ copy_runtime_source_tree() {
   cp -R "$REPO_ROOT/mac/connectd/cmd" "$mac_root/connectd/"
   cp -R "$REPO_ROOT/mac/connectd/internal" "$mac_root/connectd/"
   cp "$connectd_binary" "$mac_root/connectd/bin/pairling-connectd"
-  cp "$REPO_ROOT/mac/guardian/"*.py "$mac_root/guardian/"
   cp "$REPO_ROOT/mac/install/"*.sh "$mac_root/install/"
   cp "$REPO_ROOT/mac/install/"*.py "$mac_root/install/"
   cp "$REPO_ROOT/mac/mcp/"*.py "$mac_root/mcp/"
@@ -396,12 +1100,14 @@ stage_vendored_python() {
   # switch (-) disables that one check for local ad-hoc builds.
   if ! /usr/bin/codesign --verify --strict "$src_tree/bin/python3" >/dev/null 2>&1; then
     log "ERROR: vendored python failed codesign verification; refusing to stage: $src_tree/bin/python3" >&2
+    WIZARD_FATAL=1
     exit 1
   fi
   local team identifier
   identifier="$(/usr/bin/codesign -dvv "$src_tree/bin/python3" 2>&1 | sed -n 's/^Identifier=//p')"
   if [[ "$identifier" != "$PYTHON_CODESIGN_IDENTIFIER" ]]; then
     log "ERROR: vendored python identifier '${identifier:-none}' is not '$PYTHON_CODESIGN_IDENTIFIER'; refusing to stage." >&2
+    WIZARD_FATAL=1
     exit 1
   fi
   if [[ "$required_team" == "-" ]]; then
@@ -410,6 +1116,7 @@ stage_vendored_python() {
     team="$(/usr/bin/codesign -dvv "$src_tree/bin/python3" 2>&1 | sed -n 's/^TeamIdentifier=//p')"
     if [[ "$team" != "$required_team" ]]; then
       log "ERROR: vendored python TeamIdentifier '${team:-none}' does not match required '$required_team'; refusing to stage." >&2
+      WIZARD_FATAL=1
       exit 1
     fi
   fi
@@ -441,12 +1148,14 @@ build_connectd_binary() {
     else
       if ! /usr/bin/codesign --verify --strict "$prebuilt_env" >/dev/null 2>&1; then
         log "ERROR: connectd binary failed codesign verification; refusing to stage: $prebuilt_env" >&2
+        WIZARD_FATAL=1
         exit 1
       fi
       local team
       team="$(/usr/bin/codesign -dvv "$prebuilt_env" 2>&1 | sed -n 's/^TeamIdentifier=//p')"
       if [[ "$team" != "$required_team" ]]; then
         log "ERROR: connectd binary TeamIdentifier '${team:-none}' does not match required '$required_team'; refusing to stage: $prebuilt_env" >&2
+        WIZARD_FATAL=1
         exit 1
       fi
     fi
@@ -536,8 +1245,6 @@ for rel in [
     "companiond/providers/registry.py",
     "connectd/pairling-connectd",
     "mcp/phone_tools.py",
-    "guardian/companion-power-guardian.py",
-    "guardian/guardian_contract.py",
 ]:
     path = root / rel
     digest = hashlib.sha256(path.read_bytes()).hexdigest()
@@ -567,13 +1274,11 @@ manifest = {
         "daemon_label": "dev.pairling.companiond",
         "ptybroker_label": "dev.pairling.ptybroker",
         "connectd_label": "dev.pairling.connectd",
-        "guardian_label": "dev.pairling.power-guardian",
     },
     "paths": {
         "app_support": app_support,
         "logs": logs_root,
         "pair_records": str(Path(app_support) / "pair"),
-        "guardian_state": "/var/run/pairling-power-state.json",
     },
     "migration": {
         "legacy_port": 7723,
@@ -702,7 +1407,6 @@ render_plists() {
     --logs-root "$LOGS_ROOT"
     --output-dir "$PLIST_BUILD_DIR"
     --daemon-python "$daemon_python"
-    --guardian-python "$GUARDIAN_PYTHON_BIN"
   )
   python3 "$REPO_ROOT/mac/install/render-launchd.py" "${render_args[@]}"
 }
@@ -715,6 +1419,7 @@ start_user_agent() {
     log "dry-run: rendered $USER_PLIST"
     return
   fi
+  if launchd_skipped; then return 0; fi
   launchctl bootout "gui/$(id -u)" "$USER_PLIST" >/dev/null 2>&1 || true
   launchctl bootstrap "gui/$(id -u)" "$USER_PLIST" >/dev/null 2>&1 || true
   launchctl kickstart -k "gui/$(id -u)/$PAIRLING_DAEMON_LABEL"
@@ -728,6 +1433,7 @@ start_connectd_agent() {
     log "dry-run: rendered $CONNECTD_USER_PLIST"
     return
   fi
+  if launchd_skipped; then return 0; fi
   launchctl bootout "gui/$(id -u)" "$CONNECTD_USER_PLIST" >/dev/null 2>&1 || true
   launchctl bootstrap "gui/$(id -u)" "$CONNECTD_USER_PLIST" >/dev/null 2>&1 || true
   launchctl kickstart -k "gui/$(id -u)/$PAIRLING_CONNECTD_LABEL"
@@ -988,6 +1694,7 @@ ensure_ptybroker_agent() {
     fi
     return
   fi
+  if launchd_skipped; then return 0; fi
   if ! launchctl print "gui/$(id -u)/$PAIRLING_PTYBROKER_LABEL" >/dev/null 2>&1; then
     launchctl bootstrap "gui/$(id -u)" "$PTYBROKER_USER_PLIST" >/dev/null 2>&1 || true
     launchctl kickstart "gui/$(id -u)/$PAIRLING_PTYBROKER_LABEL" >/dev/null 2>&1 || true
@@ -1069,28 +1776,6 @@ stop_connectd_agent() {
   launchctl bootout "gui/$(id -u)" "$CONNECTD_USER_PLIST" >/dev/null 2>&1 || true
 }
 
-install_guardian_if_possible() {
-  local rendered="$PLIST_BUILD_DIR/$PAIRLING_GUARDIAN_LABEL.plist"
-  if [[ "${PAIRLING_INSTALL_GUARDIAN:-0}" != "1" ]]; then
-    log "Optional power guardian not installed; pairing can continue without the privileged sleep helper."
-    return
-  fi
-  if is_dry_run; then
-    log "dry-run: would install $PAIRLING_GUARDIAN_LABEL"
-    return
-  fi
-  if sudo -n true >/dev/null 2>&1; then
-    sudo cp "$rendered" "$SYSTEM_PLIST"
-    sudo chown root:wheel "$SYSTEM_PLIST"
-    sudo chmod 644 "$SYSTEM_PLIST"
-    sudo launchctl bootout system "$SYSTEM_PLIST" >/dev/null 2>&1 || true
-    sudo launchctl bootstrap system "$SYSTEM_PLIST" >/dev/null 2>&1 || true
-    sudo launchctl kickstart -k "system/$PAIRLING_GUARDIAN_LABEL"
-  else
-    log "Skipping guardian install: passwordless sudo is unavailable. Re-run with privileges when ready."
-  fi
-}
-
 run_doctor() {
   "$REPO_ROOT/mac/install/doctor.sh"
 }
@@ -1118,6 +1803,41 @@ rollback() {
 }
 
 install_runtime() {
+  local setup_args=("$@")
+  # Guard the empty-array expansion: install_runtime is called with no args
+  # today, and under bash 3.2 with set -u "${setup_args[@]}" raises an unbound
+  # variable error when the array is empty. The length check avoids that.
+  # The first-run flow pipes our stdout through tee, so want_tui fails its
+  # [ -t 1 ] check even with a real terminal present. When PAIRLING_WIZARD is set,
+  # want_tui_tty re-enables the screen, but only when a /dev/tty write probe
+  # succeeds and no machine condition blocks it, so NO_COLOR, CI, dry-run, --json,
+  # --plan-only, and a dumb TERM still disable it on the first-run path too.
+  if [ "${#setup_args[@]}" -gt 0 ]; then
+    { want_tui "${setup_args[@]:-}" || { [ "${PAIRLING_WIZARD:-0}" = 1 ] && want_tui_tty "${setup_args[@]:-}"; }; } \
+      && [ -x "$PYTHON3_BIN" ] && WIZARD_TUI=1 || WIZARD_TUI=0
+  else
+    { want_tui || { [ "${PAIRLING_WIZARD:-0}" = 1 ] && want_tui_tty; }; } \
+      && [ -x "$PYTHON3_BIN" ] && WIZARD_TUI=1 || WIZARD_TUI=0
+  fi
+  # The stage color and the splash follow WIZARD_TUI, not raw stdout, because the
+  # first-run flow pipes our stdout through tee to the terminal, so [ -t 1 ] is
+  # false there even with a real terminal. A machine path keeps WIZARD_TUI 0, so
+  # it stays plain and byte-stable. GUIDED_TTY follows WIZARD_TUI except when
+  # PAIRLING_GUIDED_PLAIN forces the plain form, which keeps the user opt-out the
+  # load-time GUIDED_TTY honors. The knob is unset on the first-run path, so
+  # first-run rendering is unaffected.
+  if [ "$WIZARD_TUI" = 1 ] && [ "${PAIRLING_GUIDED_PLAIN:-0}" != "1" ]; then GUIDED_TTY=1; else GUIDED_TTY=0; fi
+  # Load the brand palette exactly when the guided screen turns on. It sits on its
+  # own line, not inside the gate above, because a contract test extracts that gate
+  # by its literal one-line form. The call is idempotent, so the later defensive
+  # calls in wizard_splash and the stage markers cost only one string test.
+  if [ "$GUIDED_TTY" = 1 ]; then wizard_palette_init; fi
+  if is_dry_run; then GUIDED_STAGE_TOTAL=5; else GUIDED_STAGE_TOTAL=8; fi
+  trap guided_on_exit EXIT
+  # When WIZARD_TUI is 1 the guided stages add the splash, the live safety step,
+  # and the bash recovery menu, all behind a WIZARD_TUI check and the dry-run
+  # guard. When it is 0 the existing plain printf flow runs unchanged.
+  setup_intro
   log "Pairling setup preview:"
   log "  app support: $(display_path "$APP_SUPPORT")"
   log "  logs: $(display_path "$LOGS_ROOT")"
@@ -1125,18 +1845,31 @@ install_runtime() {
   log "  PTY Broker LaunchAgent: $PAIRLING_PTYBROKER_LABEL"
   log "  Connect LaunchAgent: $PAIRLING_CONNECTD_LABEL"
   log "  runtime port: $PAIRLING_RUNTIME_PORT"
+
+  stage_begin "Preparing the Mac runtime"
   run_compile_checks
   run_psk_dependency_checks
   ensure_state
+  stage_ok "checks passed and state is ready"
+
+  stage_begin "PairDrop folder"
+  ensure_pairdrop_folder
+  stage_ok "$(display_path "$PAIRDROP_ROOT") is ready (private, mode 0700)"
+
+  stage_begin "Staging runtime"
   copy_release
   switch_current
   install_mcp_adapter_shim
   install_shell_wrapper
+  stage_ok "staged $RELEASE_NAME"
+
+  stage_begin "Starting Pairling services"
   render_plists
   ensure_ptybroker_agent
   start_user_agent
   start_connectd_agent
-  install_guardian_if_possible
+  stage_ok "companiond, connectd, and ptybroker are running"
+
   append_history "installed" "installed $RELEASE_NAME"
   if is_dry_run; then
     log "dry-run: skipping doctor gate"
@@ -1144,17 +1877,46 @@ install_runtime() {
     run_doctor || true
   fi
   log "Installed Pairling runtime $RELEASE_NAME"
+
+  stage_begin "macOS permissions"
+  if [ "${WIZARD_TUI:-0}" = 1 ] && ! is_dry_run; then
+    # The safety step reads the live SafetyMonitorBridge status. Today it reports
+    # not installed, so it prints one advisory line and continues. When a future
+    # PairlingSafety.app is installed, it guides approval, Full Disk Access, and
+    # the evidence test. It never blocks pairing. The plain advisory notice is the
+    # WIZARD_TUI=0 fallback.
+    safety_step
+  else
+    guided_permission_notice
+  fi
+  stage_ok "no Mac privacy permission is required to pair"
+
   if ! is_dry_run; then
-    # Kick off the Tailscale sign-in before the QR so the pairing code can
-    # advertise the now-ready Pairling Connect tailnet route instead of
-    # downgrading to LAN/Bonjour. Never blocks or fails setup.
-    auto_open_connect_auth
-    log ""
-    if ! PAIRLING_CONNECTD_ROUTE_WAIT_SECONDS="${PAIRLING_CONNECTD_ROUTE_WAIT_SECONDS:-35}" pair_runtime --qr; then
+    stage_begin "Pairing code for the iPhone"
+    if [ "${WIZARD_TUI:-0}" = 1 ]; then
+      stage_note "Open Pairling on your iPhone and scan this code. The pair address is printed below it too."
+    fi
+    # Record when this pairing attempt started, so the seen probe in
+    # guided_finish_summary counts only a device paired during this session.
+    export PAIRLING_PAIRING_STARTED_AT="$(python3 -c 'import time;print(time.time())')"
+    if ! PAIRLING_CONNECTD_ROUTE_WAIT_SECONDS="${PAIRLING_CONNECTD_ROUTE_WAIT_SECONDS:-0}" pair_runtime --qr; then
       log "Pairling installed, but setup could not generate a pairing invitation. Run: pairling doctor --json; pairling pair --qr" >&2
       exit 1
     fi
+    stage_ok "pairing code displayed (local-first)"
+    log ""
+    # Browser auth is useful, but it must not block or precede the first pairing
+    # code. First-pair bootstrap is local-first; Pairling Connect hardens after
+    # the phone has joined.
+    stage_begin "Pairling Connect sign-in (Mac)"
+    auto_open_connect_auth
+    stage_ok "Pairling Connect sign-in handled"
+
+    stage_begin "Finish and next steps"
+    guided_finish_summary
+    stage_ok "setup complete"
   fi
+  GUIDED_COMPLETE=1
 }
 
 status_runtime() {
@@ -1366,10 +2128,11 @@ def default_pair_route(port_number: int) -> dict:
         value = os.environ.get(key)
         if value:
             return {"base_url": value, "source": "explicit_override", "status": "override"}
-    # Remote-first pairing: if connectd reports a ready Pairling Connect route,
-    # the QR advertises that route and the iOS app claims it through the
-    # embedded pre-pair transport. LAN/Bonjour are explicit degraded fallbacks
-    # when Pairling Connect is not ready.
+    # First-pair bootstrap: prefer LAN when it exists. iOS blocks plain HTTP to
+    # a tailnet IP before the embedded Pairling Connect route is ready.
+    lan_ip = detected_lan_ip()
+    if lan_ip:
+        return {"base_url": f"http://{lan_ip}:{port_number}", "source": "lan", "status": "fallback", "kind": "lan"}
     route = ready_connectd_route()
     if route:
         return {
@@ -1378,9 +2141,6 @@ def default_pair_route(port_number: int) -> dict:
             "status": route["status"],
             "kind": route["kind"],
         }
-    lan_ip = detected_lan_ip()
-    if lan_ip:
-        return {"base_url": f"http://{lan_ip}:{port_number}", "source": "lan", "status": "fallback", "kind": "lan"}
     if os.environ.get("PAIRLING_DISABLE_BONJOUR") != "1" and os.environ.get("PAIRLING_TEST_DISABLE_BONJOUR") != "1":
         return {"base_url": f"http://{socket.gethostname()}.local:{port_number}", "source": "bonjour", "status": "fallback", "kind": "bonjour"}
     tailnet_ip = detected_tailnet_ip()
@@ -1612,7 +2372,7 @@ connect_auth_open() {
   exit 1
 }
 
-# auto_open_connect_auth — kicked off by install_runtime BEFORE the pairing QR.
+# auto_open_connect_auth — kicked off by install_runtime after the first QR.
 # Polls connectd /status for readiness (reusing fetch_connectd_status, the same
 # helper pair_runtime imports). When connectd is in interactive mode and not yet
 # authenticated (auth_url_present == true AND auth_state != "authenticated"), it
@@ -1826,7 +2586,7 @@ case "$cmd" in
       shift
       "$REPO_ROOT/mac/install/bootstrap-first-run.sh" "$@"
     else
-      install_runtime
+      install_runtime "$@"
     fi
     ;;
   first-run)