oysterun 1.6.0-beta.2 → 1.6.0-beta.21

package/static/site/install.sh

@@ -6,53 +6,138 @@ platform=""
 architecture=""
 target_user=""
 target_home=""
+target_uid=""
+target_gid=""
+canonical_home=""
+config_dir=""
+setup_input_file=""
+setup_input_root_memory=false
 profile_file=""
-runtime_path_prefix=""
 temporary_root=""
+install_lock=""
+lock_owned=false
 dry_run=false
 install_only=false
-direct_root_account_created=false
+reinstall=false
+modify_path=true
+package_install_spec=""
+requested_channel_override=""
+version_compare_script='const p=v=>{const m=String(v).match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);return m?[+m[1],+m[2],+m[3],m[4]||""]:null},a=p(process.argv[1]),b=p(process.argv[2]);if(!a||!b)process.exit(2);let result=null;for(let i=0;i<3;i++){if(a[i]!==b[i]){result=a[i]>b[i]?1:-1;break}}if(result===null){if(a[3]===b[3])result=0;else if(!a[3])result=1;else if(!b[3])result=-1;else result=a[3].localeCompare(b[3],undefined,{numeric:true})>0?1:-1}console.log(result)'
 
 cleanup() {
   local exit_status=$?
+  unset setup_input_snapshot
   [[ -z "$temporary_root" ]] || rm -rf "$temporary_root"
-  if [[ "$exit_status" -ne 0 && "$dry_run" != true && "$direct_root_account_created" == true ]]; then
-    userdel -r "$target_user" >/dev/null 2>&1 || true
+  if [[ "$lock_owned" == true && -n "$install_lock" ]]; then
+    rmdir "$install_lock" >/dev/null 2>&1 || true
   fi
+  return "$exit_status"
+}
+print_recovery_inspection() {
+  # Signal handlers only print this command. They must not inspect or mutate
+  # a Host while an interrupted child may still own a lifecycle transaction.
+  if [[ -n "${node_bin:-}" && -n "${driver_prefix:-}" && -n "${config_dir:-}" && -n "${selected_channel:-}" && \
+        -f "$driver_prefix/lib/node_modules/oysterun/host-service/cli/installer-recovery-guidance.mjs" ]]; then
+    printf 'Next (read-only recovery inspection):' >&2
+    # Mirror capture_user's supported account routing without executing it.
+    if [[ "$EUID" -eq 0 ]]; then
+      if [[ "$platform" == "Darwin" ]]; then
+        printf ' %q' sudo -H -u "$target_user" env "HOME=$target_home" "USER=$target_user" "LOGNAME=$target_user" >&2
+      else
+        printf ' %q' runuser -u "$target_user" -- env "HOME=$target_home" "USER=$target_user" "LOGNAME=$target_user" >&2
+      fi
+    else
+      printf ' %q' env "HOME=$target_home" "USER=$target_user" "LOGNAME=$target_user" >&2
+    fi
+    printf ' %q' "$node_bin" "$driver_prefix/lib/node_modules/oysterun/host-service/cli/installer-recovery-guidance.mjs" \
+      "$config_dir" "${active_package_root:-}" "" "$selected_channel" \
+      "$canonical_home" "$target_uid" "$reinstall" >&2
+    printf '\n' >&2
+  elif [[ -n "${config_dir:-}" ]]; then
+    printf 'Next (inspect target ownership): ls -ld -- %q\n' "$config_dir" >&2
+  else
+    printf 'Next (inspect platform): uname -sm\n' >&2
+  fi
+}
+fail() {
+  trap - ERR
+  printf 'Oysterun installer failed during %s: %s\n' "$stage" "$1" >&2
+  if [[ -n "${node_bin:-}" && -n "${driver_prefix:-}" && -n "${active_package_root:-}" && \
+        -f "$driver_prefix/lib/node_modules/oysterun/host-service/cli/installer-recovery-guidance.mjs" ]]; then
+    capture_user "$node_bin" "$driver_prefix/lib/node_modules/oysterun/host-service/cli/installer-recovery-guidance.mjs" \
+      "$config_dir" "$active_package_root" "" "$selected_channel" \
+      "$canonical_home" "$target_uid" "$reinstall" >&2 || true
+  fi
+  print_recovery_inspection
+  exit 1
+}
+interrupted() {
+  trap - ERR INT TERM
+  printf 'Oysterun installer interrupted by %s during %s; completion and running Host readiness are unproved. Preserve the Host and lifecycle receipts.\n' "$1" "$stage" >&2
+  print_recovery_inspection
+  exit "$2"
 }
-fail() { trap - ERR; printf 'Oysterun installer failed during %s: %s\n' "$stage" "$1" >&2; exit 1; }
 trap 'fail "command exited with status $?"' ERR
 trap cleanup EXIT
+trap 'interrupted INT 130' INT
+trap 'interrupted TERM 143' TERM
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --dry-run) dry_run=true ;;
     --install-only) install_only=true ;;
-    *) fail "supported options: --dry-run, --install-only" ;;
+    --reinstall) reinstall=true ;;
+    --no-modify-path) modify_path=false ;;
+    --channel)
+      [[ $# -ge 2 ]] || fail "--channel requires latest or beta"
+      requested_channel_override="$2"
+      shift
+      ;;
+    --channel=*) requested_channel_override="${1#--channel=}" ;;
+    --setup-input-file)
+      [[ $# -ge 2 ]] || fail "--setup-input-file requires an absolute path"
+      setup_input_file="$2"; shift
+      ;;
+    --setup-input-file=*) setup_input_file="${1#--setup-input-file=}" ;;
+    --config-dir)
+      [[ $# -ge 2 ]] || fail "--config-dir requires an absolute path"
+      config_dir="$2"
+      shift
+      ;;
+    --config-dir=*) config_dir="${1#--config-dir=}" ;;
+    *) fail "supported options: --channel latest|beta, --reinstall (preserve config; stops sessions), --dry-run, --install-only, --no-modify-path, --config-dir PATH, --setup-input-file PATH" ;;
   esac
   shift
 done
 
+if $reinstall && $install_only; then
+  fail "--reinstall includes service restoration and cannot be combined with --install-only"
+fi
+
+case "$requested_channel_override" in
+  ""|latest|beta) ;;
+  *) fail "--channel must be latest or beta" ;;
+esac
+
 platform="$(uname -s)"
 architecture="$(uname -m)"
 case "$platform:$architecture" in
   Darwin:x86_64|Darwin:arm64|Linux:x86_64|Linux:aarch64|Linux:arm64) ;;
   Darwin:*|Linux:*) fail "unsupported CPU architecture: $architecture" ;;
-  *) fail "supported operating systems: macOS and Debian/Ubuntu Linux" ;;
+  *) fail "supported operating systems: macOS and Ubuntu Linux" ;;
 esac
 
 if [[ "$platform" == "Linux" ]]; then
   os_release="/etc/os-release"
-  if $dry_run && [[ -n "${P230_TEST_OS_RELEASE:-}" ]]; then os_release="$P230_TEST_OS_RELEASE"; fi
+  if $dry_run && [[ -n "${P230_TEST_OS_RELEASE:-}" ]]; then
+    os_release="$P230_TEST_OS_RELEASE"
+  fi
   [[ -f "$os_release" ]] || fail "Linux distribution metadata is missing"
   distro_id="$(. "$os_release"; printf '%s' "${ID:-}")"
   distro_version="$(. "$os_release"; printf '%s' "${VERSION_ID:-}")"
   distro_major="${distro_version%%.*}"
-  case "$distro_id" in
-    ubuntu) [[ "$distro_major" =~ ^[0-9]+$ && "$distro_major" -ge 22 ]] || fail "Ubuntu 22.04 or newer is required" ;;
-    debian) [[ "$distro_major" =~ ^[0-9]+$ && "$distro_major" -ge 12 ]] || fail "Debian 12 or newer is required" ;;
-    *) fail "supported Linux distributions: Ubuntu 22.04+ and Debian 12+" ;;
-  esac
+  [[ "$distro_id" == "ubuntu" ]] || fail "supported Linux distribution: Ubuntu 22.04 or newer"
+  [[ "$distro_major" =~ ^[0-9]+$ && "$distro_major" -ge 22 ]] || fail "Ubuntu 22.04 or newer is required"
 fi
 
 lookup_home() {
@@ -75,182 +160,646 @@ else
 fi
 
 stage="target account"
+# BEGIN generated setup input validation
+# Canonical read-only setup-file/pre-input validation; also embedded in install.sh.
+setup_input_error() { printf '%s\n' "$1" >&2; return 1; }
+setup_config_has() {
+  local file="$1" key="$2" kind="$3" value
+  [[ -f "$file" ]] || return 1
+  if [[ "$(uname -s)" == Darwin ]]; then
+    local expected="$kind"; [[ "$kind" != direct ]] || expected=string
+    value=$(/usr/bin/plutil -extract "$key" raw -expect "$expected" -o - "$file" 2>/dev/null) || return 1
+    case "$kind" in bool) return 0;; direct) [[ "$value" == direct ]];; integer) [[ "$value" =~ ^[0-9]+$ ]] && (( value > 0 && value <= 65535 ));; *) [[ "$value" =~ [^[:space:]] ]];; esac
+  else
+    command -v python3 >/dev/null || { setup_input_error 'Read-only Ubuntu configuration preflight requires python3; no changes made'; return 2; }
+    python3 - "$file" "$key" "$kind" <<'PY'
+import json,sys
+try:
+ c=json.load(open(sys.argv[1]));v=c.get(sys.argv[2]);kind=sys.argv[3];ok=isinstance(v,bool) if kind=='bool' else (type(v)==int and 0<v<=65535) if kind=='integer' else v=='direct' if kind=='direct' else isinstance(v,str) and bool(v.strip())
+except Exception: ok=False
+sys.exit(0 if ok else 1)
+PY
+  fi
+}
+setup_config_ready() {
+  local dir="$1" cfg="$1/config.json"
+  setup_config_has "$cfg" port integer && setup_config_has "$cfg" dashboard_user string && setup_config_has "$cfg" dashboard_password_hash string && setup_config_has "$cfg" default_browse_path string || return 1
+  if setup_config_has "$cfg" connection_mode direct; then
+    setup_config_has "$cfg" direct_host_url string || setup_config_has "$cfg" public_base_url string
+  else
+    setup_config_has "$cfg" managed_endpoint string &&
+      { setup_config_has "$dir/cloud_identity.json" device_id string || setup_config_has "$dir/cloud_identity.json" host_id string || setup_config_has "$cfg" device_id string || setup_config_has "$cfg" host_id string; } &&
+      { setup_config_has "$dir/cloud_identity.json" device_token string || setup_config_has "$dir/cloud_identity.json" host_credential string || setup_config_has "$cfg" device_token string || setup_config_has "$cfg" host_credential string; }
+  fi
+}
+setup_input_validate() {
+  set +x
+  set +a
+  unset setup_input_snapshot
+  setup_input_snapshot=''
+  local source="$1" uid="$2" config="$3" line key value mode owner missing='' seen='|' name='' root='' password='' consent=''
+  export -n password line value
+  if [[ -f "$config/config.json" && "$(uname -s)" == Linux ]] && ! command -v python3 >/dev/null; then setup_input_error "Read-only Ubuntu configuration preflight requires python3; no changes made"; return 1; fi
+  if [[ -f "$config/config.json" ]]; then
+    if [[ "$(uname -s)" == Darwin ]]; then
+      /usr/bin/osascript -l JavaScript -e 'function run(argv) { ObjC.import("Foundation"); const text = $.NSString.stringWithContentsOfFileEncodingError(argv[0], $.NSUTF8StringEncoding, null).js; const value = JSON.parse(text); if (!value || Array.isArray(value) || typeof value !== "object") throw Error("invalid configuration"); return "valid"; }' "$config/config.json" >/dev/null 2>&1 || { setup_input_error 'Existing configuration is invalid JSON; preserve it and restore the configuration before retrying'; return 1; }
+    else
+      python3 -c 'import json,sys; value=json.load(open(sys.argv[1])); assert isinstance(value,dict)' "$config/config.json" >/dev/null 2>&1 || { setup_input_error 'Existing configuration is invalid JSON; preserve it and restore the configuration before retrying'; return 1; }
+    fi
+  fi
+  if [[ -n "$source" ]]; then
+    [[ "$source" == /* && -f "$source" && ! -L "$source" ]] || { setup_input_error 'Setup input must be an absolute regular file, not a symlink'; return 1; }
+    local parent parent_path="${source%/*}"; [[ -n "$parent_path" ]] || parent_path=/
+    parent=$(cd -P "$parent_path" && pwd) || return 1
+    [[ "$parent" == "$parent_path" ]] || { setup_input_error "Setup input path must not traverse symlinks"; return 1; }
+    exec 9< "$source" || { setup_input_error 'Setup input is not readable'; return 1; }
+    local opened=/dev/fd/9; [[ "$(uname -s)" != Linux ]] || opened=/proc/self/fd/9
+    if [[ "$(uname -s)" == Darwin ]]; then
+      owner=$(/usr/bin/stat -Lf %u "$opened"); mode=$(/usr/bin/stat -Lf %Lp "$opened")
+    else
+      owner=$(/usr/bin/stat -Lc %u "$opened"); mode=$(/usr/bin/stat -Lc %a "$opened")
+    fi
+    if ! [[ -f "$opened" && -n "$uid" && "$owner" == "$uid" && ( "$mode" == 600 || "$mode" == 400 ) ]]; then
+      exec 9<&-; setup_input_error 'Setup input must belong to the selected source owner and have private permissions (0600 or 0400)'; return 1
+    fi
+    if IFS= read -r -d '' setup_input_snapshot <&9; then
+      exec 9<&-; unset setup_input_snapshot; setup_input_error 'Setup input must be UTF-8 text without NULs'; return 1
+    fi
+    exec 9<&-
+    builtin printf '%s' "$setup_input_snapshot" | /usr/bin/iconv -f UTF-8 -t UTF-8 >/dev/null 2>&1 || { unset setup_input_snapshot; setup_input_error 'Setup input must be UTF-8 text without NULs'; return 1; }
+    while IFS= read -r line || [[ -n "$line" ]]; do
+      [[ -z "$line" || "$line" == \#* ]] && continue
+      [[ "$line" == *=* ]] || { setup_input_error 'Invalid setup input format'; return 1; }
+      key=${line%%=*}; value=${line#*=}
+      case "$key" in display_name|default_browse_root|dashboard_password|daily_telemetry_enabled) ;; *) setup_input_error 'Unknown setup input field'; return 1;; esac
+      [[ "$seen" != *"|$key|"* ]] || { setup_input_error 'Duplicate setup input field'; return 1; }; seen="$seen$key|"
+      case "$key" in
+        display_name) name="$value" ;;
+        default_browse_root) [[ -z "$value" || "$value" == /* ]] || { setup_input_error 'Setup Browse Root must be absolute'; return 1; }; root="$value" ;;
+        dashboard_password) password="$value" ;;
+        daily_telemetry_enabled) [[ "$value" == true || "$value" == false ]] || { setup_input_error 'Setup telemetry consent must be true or false'; return 1; }; consent="$value" ;;
+      esac
+    done < <(builtin printf '%s' "$setup_input_snapshot")
+    [[ -z "$root" || -d "$root" ]] || { setup_input_error "Setup Browse Root must be an existing directory"; return 1; }
+  fi
+  setup_config_ready "$config" && return 0
+  setup_config_has "$config/config.json" display_name string || [[ "$name" =~ [^[:space:]] ]] || missing="$missing display_name"
+  setup_config_has "$config/config.json" default_browse_path string || [[ -n "$root" ]] || missing="$missing default_browse_root"
+  setup_config_has "$config/config.json" dashboard_password_hash string || [[ "$password" =~ [^[:space:]] ]] || missing="$missing dashboard_password"
+  if ! { setup_config_has "$config/config.json" daily_telemetry_enabled bool && setup_config_has "$config/config.json" daily_telemetry_consent_recorded_at string; } && [[ -z "$consent" ]]; then missing="$missing daily_telemetry_enabled"; fi
+  [[ -z "$missing" ]] || { setup_input_error "Missing onboarding inputs:$missing. Resume the same command from a terminal or with --setup-input-file /absolute/private-file"; return 1; }
+}
+
+# Only the invoking-root account-creation branch may emit this memory snapshot.
+# Anonymous pipes retain root ownership and read-only access in the target child.
+setup_input_emit_for_uid() {
+  set +x
+  builtin printf 'oysterun-root-setup-v1:%s\n' "$1"
+  builtin printf '%s' "$setup_input_snapshot"
+}
+# END generated setup input validation
+require_fresh_onboarding_terminal() {
+  local prospective_config="$1" prospective_uid="${2:-${target_uid:-}}"
+  if ! $dry_run && ! $install_only && { [[ -n "$setup_input_file" ]] || { [[ ! -t 0 ]] && ! ( : </dev/tty ) 2>/dev/null; }; }; then
+    setup_input_validate "$setup_input_file" "$prospective_uid" "$prospective_config" || fail "onboarding inputs are incomplete or unsafe; no changes made"
+  fi
+}
 if [[ "$platform" == "Linux" && "$(id -u)" -eq 0 && "$target_user" == "oysterun" ]] && ! id "$target_user" >/dev/null 2>&1; then
+  if ! $dry_run && ! $install_only && [[ -n "$setup_input_file" ]]; then
+    setup_input_validate "$setup_input_file" 0 "${config_dir:-${OYSTERUN_CONFIG_DIR:-/home/oysterun/.oysterun}}" || fail "onboarding inputs are incomplete or unsafe; no changes made"
+    setup_input_root_memory=true
+  else
+    require_fresh_onboarding_terminal "${config_dir:-${OYSTERUN_CONFIG_DIR:-/home/oysterun/.oysterun}}"
+  fi
   if $dry_run; then
-    printf '+ root: useradd --create-home --home-dir /home/oysterun --shell /bin/bash %q\n' "$target_user"
-    direct_root_account_created=true
+    printf '+ root: useradd --create-home --home-dir /home/oysterun --shell /bin/bash oysterun\n'
   else
-    useradd --create-home --home-dir /home/oysterun --shell /bin/bash "$target_user"
-    direct_root_account_created=true
+    useradd --create-home --home-dir /home/oysterun --shell /bin/bash oysterun
   fi
 fi
 
 stage="target identity validation"
-if $dry_run && $direct_root_account_created; then
-  target_uid="<created-user-uid>"
+if $dry_run && [[ "$target_user" == "oysterun" ]] && ! id "$target_user" >/dev/null 2>&1; then
   target_home="/home/oysterun"
+  target_uid="1000"
+  target_gid="1000"
   canonical_home="$target_home"
 else
   target_home="$(lookup_home "$target_user")" || fail "target account has no home directory"
   [[ "$target_user" != "root" && "$target_home" == /* && "$target_home" != "/" && "$target_home" != "/root" ]] || fail "unsafe target user or home"
-  if [[ "$(id -u)" -ne 0 && "${HOME:?HOME is required}" != "$target_home" ]]; then fail "HOME does not match the invoking account database home"; fi
+  if [[ "$(id -u)" -ne 0 && "${HOME:?HOME is required}" != "$target_home" ]]; then
+    fail "HOME does not match the invoking account database home"
+  fi
   target_uid="$(id -u "$target_user")" || fail "target user does not exist"
+  target_gid="$(id -g "$target_user")" || fail "target user group does not exist"
   [[ "$target_uid" =~ ^[0-9]+$ && "$target_uid" -ne 0 ]] || fail "target user must have a non-root numeric UID"
   [[ -d "$target_home" && ! -L "$target_home" ]] || fail "target home must be an existing non-symlink directory"
   canonical_home="$(cd -P "$target_home" && pwd -P)"
   [[ "$canonical_home" == "$target_home" ]] || fail "target home must already be canonical"
-  if [[ "$platform" == "Darwin" ]]; then home_uid="$(stat -f %u "$target_home")"; else home_uid="$(stat -c %u "$target_home")"; fi
+  if [[ "$platform" == "Darwin" ]]; then
+    home_uid="$(stat -f %u "$target_home")"
+  else
+    home_uid="$(stat -c %u "$target_home")"
+  fi
   [[ "$home_uid" == "$target_uid" ]] || fail "target home must be owned by the target user"
 fi
 
-stage="existing installation check"
-default_config_dir="$canonical_home/.oysterun"
-if [[ -n "${OYSTERUN_CONFIG_DIR:-}" && "$OYSTERUN_CONFIG_DIR" != "$default_config_dir" ]]; then
-  fail "custom OYSTERUN_CONFIG_DIR is ambiguous; use the existing installation's update command"
-fi
-existing_config_found=false
-[[ -f "$default_config_dir/config.json" ]] && existing_config_found=true
-
-if [[ "$platform" == "Linux" ]]; then
-  command -v apt-get >/dev/null 2>&1 || fail "this release supports Debian and Ubuntu Linux (apt-get)"
-  profile_file="$target_home/.profile"
-else
-  profile_file="$target_home/.zprofile"
-fi
-
 run_root() {
-  if $dry_run; then printf '+ root: '; printf '%q ' "$@"; printf '\n'
-  elif [[ "$(id -u)" -eq 0 ]]; then "$@"
-  else sudo "$@"
+  if $dry_run; then
+    printf '+ root:'
+    printf ' %q' "$@"
+    printf '\n'
+  elif [[ "$(id -u)" -eq 0 ]]; then
+    "$@"
+  else
+    sudo "$@"
   fi
 }
 
-run_user_shell() {
-  local command="$1"
-  command="set -Eeuo pipefail; unset NPM_CONFIG_PREFIX npm_config_prefix; $command"
-  if [[ -n "$runtime_path_prefix" ]]; then command="export PATH='$runtime_path_prefix':\$PATH; $command"; fi
+run_user() {
   if $dry_run; then
-    printf '+ user %s (HOME=%s): %s\n' "$target_user" "$target_home" "$command"
+    printf '+ user %s (HOME=%s):' "$target_user" "$target_home"
+    printf ' %q' "$@"
+    printf '\n'
   elif [[ "$(id -u)" -eq 0 ]]; then
     if [[ "$platform" == "Darwin" ]]; then
-      sudo -H -u "$target_user" env HOME="$target_home" USER="$target_user" LOGNAME="$target_user" /bin/bash -c "$command"
+      sudo -H -u "$target_user" env HOME="$target_home" USER="$target_user" LOGNAME="$target_user" "$@"
     else
-      runuser -u "$target_user" -- env HOME="$target_home" USER="$target_user" LOGNAME="$target_user" /bin/bash -c "$command"
+      runuser -u "$target_user" -- env HOME="$target_home" USER="$target_user" LOGNAME="$target_user" "$@"
     fi
   else
-    HOME="$target_home" USER="$target_user" LOGNAME="$target_user" /bin/bash -c "$command"
+    HOME="$target_home" USER="$target_user" LOGNAME="$target_user" "$@"
   fi
 }
 
-user_output() {
-  local command="$1"
-  command="set -Eeuo pipefail; unset NPM_CONFIG_PREFIX npm_config_prefix; $command"
-  if [[ -n "$runtime_path_prefix" ]]; then command="export PATH='$runtime_path_prefix':\$PATH; $command"; fi
-  if $dry_run; then
-    HOME="$target_home" USER="$target_user" LOGNAME="$target_user" /bin/bash -c "$command"
-  elif [[ "$(id -u)" -eq 0 ]]; then
+capture_user() {
+  if [[ "$(id -u)" -eq 0 ]]; then
     if [[ "$platform" == "Darwin" ]]; then
-      sudo -H -u "$target_user" env HOME="$target_home" USER="$target_user" LOGNAME="$target_user" /bin/bash -c "$command"
+      sudo -H -u "$target_user" env HOME="$target_home" USER="$target_user" LOGNAME="$target_user" "$@"
     else
-      runuser -u "$target_user" -- env HOME="$target_home" USER="$target_user" LOGNAME="$target_user" /bin/bash -c "$command"
+      runuser -u "$target_user" -- env HOME="$target_home" USER="$target_user" LOGNAME="$target_user" "$@"
     fi
   else
-    HOME="$target_home" USER="$target_user" LOGNAME="$target_user" /bin/bash -c "$command"
+    HOME="$target_home" USER="$target_user" LOGNAME="$target_user" "$@"
   fi
 }
 
-if $existing_config_found; then
-  existing_cli="$(user_output 'command -v oysterun || true')"
-  if [[ -n "$existing_cli" ]]; then
-    fail "an existing configured Oysterun installation and CLI were found; use 'oysterun service:update --channel latest' from that user instead"
+if [[ -z "$config_dir" ]]; then
+  config_dir="${OYSTERUN_CONFIG_DIR:-$canonical_home/.oysterun}"
+fi
+[[ "$config_dir" == /* ]] || fail "--config-dir must be absolute"
+if [[ -e "$config_dir" ]]; then
+  [[ -d "$config_dir" && ! -L "$config_dir" ]] || fail "config path must be a non-symlink directory"
+  if [[ "$platform" == "Darwin" ]]; then
+    config_uid="$(stat -f %u "$config_dir")"
+  else
+    config_uid="$(stat -c %u "$config_dir")"
+  fi
+  [[ "$config_uid" == "$target_uid" ]] || fail "config directory is not owned by the target user"
+fi
+export OYSTERUN_CONFIG_DIR="$config_dir"
+# Invoking-root FILE authority survives account creation, failures and repeats.
+# Target-owned files retain their ordinary target-user path below.
+if ! $dry_run && ! $install_only && [[ -n "$setup_input_file" && "$setup_input_root_memory" != true && "$platform" == Linux && "$(id -u)" -eq 0 ]] && [[ "$(stat -c %u "$setup_input_file" 2>/dev/null)" == 0 ]]; then
+  setup_input_validate "$setup_input_file" 0 "$config_dir" || fail "onboarding inputs are incomplete or unsafe; no changes made"
+  setup_input_root_memory=true
+fi
+if ! $dry_run && ! $install_only && [[ -n "$setup_input_file" && "$setup_input_root_memory" != true ]]; then
+  run_user test -r "$setup_input_file" || fail "setup input is not readable through the target user route; no changes made"
+fi
+if [[ "$setup_input_root_memory" != true ]]; then require_fresh_onboarding_terminal "$config_dir"; fi
+if $reinstall && [[ "$config_dir" != "$canonical_home/.oysterun" ]]; then
+  fail "--reinstall targets the default user Host only; it cannot remove another stack's service"
+fi
+
+stage="installer lock"
+state_root="$canonical_home/.local/state/oysterun"
+install_lock="$state_root/install.lock"
+run_user mkdir -p "$state_root"
+if $dry_run; then
+  printf '+ acquire exclusive installer lock %q\n' "$install_lock"
+else
+  if ! run_user mkdir "$install_lock" 2>/dev/null; then
+    fail "another Oysterun install, update, or repair is already running"
   fi
-  printf 'Existing Oysterun configuration found; preserving it while reinstalling the missing CLI.\n'
+  lock_owned=true
 fi
 
-stage="Node.js runtime"
-node_major=0
-node_major="$(user_output "if command -v node >/dev/null 2>&1; then node -p 'Number(process.versions.node.split(\".\")[0])'; else printf 0; fi")"
-if [[ "$node_major" -ne 22 ]]; then
-  if [[ "$platform" == "Darwin" ]]; then
-    brew_command=""
-    if [[ "${P230_ISOLATED_TEST_MODE:-}" == "true" ]]; then
-      fixture_root="${P230_TEST_FIXTURE_ROOT:-}"
-      test_brew="${P230_TEST_BREW_COMMAND:-}"
-      [[ -n "$fixture_root" && -d "$fixture_root" && ! -L "$fixture_root" && -n "$test_brew" && -x "$test_brew" && ! -L "$test_brew" ]] || fail "isolated test mode requires an executable non-symlink Brew mock inside its fixture root"
-      fixture_root="$(cd -P "$fixture_root" && pwd -P)"
-      test_brew="$(cd -P "$(dirname "$test_brew")" && pwd -P)/$(basename "$test_brew")"
-      [[ "$test_brew" == "$fixture_root"/* ]] || fail "isolated Brew mock must resolve inside its fixture root"
-      brew_command="$test_brew"
-    elif $dry_run && [[ "${P230_TEST_BREW_MODE:-}" == "missing" ]]; then
-      brew_command=""
-    elif $dry_run && [[ -n "${P230_TEST_BREW_COMMAND:-}" ]]; then
-      brew_command="$P230_TEST_BREW_COMMAND"
+if [[ "$platform" == "Darwin" ]]; then
+  profile_file="$canonical_home/.zprofile"
+else
+  profile_file="$canonical_home/.profile"
+fi
+
+stage="Oysterun-managed Node.js 22"
+runtime_root="$canonical_home/.local/share/oysterun/runtime"
+case "$platform:$architecture" in
+  Darwin:arm64) node_suffix="darwin-arm64.tar.gz" ;;
+  Darwin:x86_64) node_suffix="darwin-x64.tar.gz" ;;
+  Linux:arm64|Linux:aarch64) node_suffix="linux-arm64.tar.gz" ;;
+  Linux:x86_64) node_suffix="linux-x64.tar.gz" ;;
+esac
+
+if $dry_run; then
+  node_version="v22.latest"
+  node_release_dir="$runtime_root/$node_version"
+  node_bin="$node_release_dir/bin/node"
+  npm_cli="$node_release_dir/lib/node_modules/npm/bin/npm-cli.js"
+  printf '+ download and verify official Node.js 22 %s artifact with SHASUMS256.txt\n' "$node_suffix"
+  printf '+ install versioned user-owned runtime at %q\n' "$node_release_dir"
+else
+  temporary_root="$(mktemp -d)"
+  chmod 700 "$temporary_root"
+  curl --proto '=https' --tlsv1.2 -fsSLo "$temporary_root/SHASUMS256.txt" https://nodejs.org/dist/latest-v22.x/SHASUMS256.txt
+  node_archive="$(awk -v suffix="$node_suffix" 'index($2, suffix) == length($2) - length(suffix) + 1 { print $2; exit }' "$temporary_root/SHASUMS256.txt")"
+  [[ -n "$node_archive" ]] || fail "official Node.js 22 checksum manifest has no artifact for this platform"
+  node_version="${node_archive%%-$node_suffix}"
+  node_release_dir="$runtime_root/$node_version"
+  node_bin="$node_release_dir/bin/node"
+  npm_cli="$node_release_dir/lib/node_modules/npm/bin/npm-cli.js"
+  run_user mkdir -p "$runtime_root"
+  if [[ ! -x "$node_bin" ]] || ! "$node_bin" -e 'if (process.versions.node.split(".")[0] !== "22") process.exit(1)'; then
+    curl --proto '=https' --tlsv1.2 -fsSLo "$temporary_root/$node_archive" "https://nodejs.org/dist/latest-v22.x/$node_archive"
+    expected_sha="$(awk -v file="$node_archive" '$2 == file { print $1; exit }' "$temporary_root/SHASUMS256.txt")"
+    if command -v shasum >/dev/null 2>&1; then
+      actual_sha="$(shasum -a 256 "$temporary_root/$node_archive" | awk '{print $1}')"
+    elif command -v sha256sum >/dev/null 2>&1; then
+      actual_sha="$(sha256sum "$temporary_root/$node_archive" | awk '{print $1}')"
     else
-      for candidate in /opt/homebrew/bin/brew /usr/local/bin/brew; do [[ -x "$candidate" ]] && brew_command="$candidate" && break; done
-      if [[ -z "$brew_command" ]]; then brew_command="$(user_output 'command -v brew || true')"; fi
+      fail "SHA-256 verification tool is required (shasum or sha256sum)"
     fi
-    [[ -n "$brew_command" ]] || fail "Node.js 22 is required. Install it from https://nodejs.org/en/download, then run this installer again; no changes were made"
-    if $dry_run; then
-      printf '+ user %s: %s install node@22\n' "$target_user" "$brew_command"
-      runtime_path_prefix="$target_home/.p230-dry-run-node22/bin"
+    [[ -n "$expected_sha" && "$actual_sha" == "$expected_sha" ]] || fail "official Node.js 22 artifact checksum mismatch"
+    tar -xzf "$temporary_root/$node_archive" -C "$temporary_root"
+    extracted="$temporary_root/${node_archive%.tar.gz}"
+    [[ -x "$extracted/bin/node" && -f "$extracted/lib/node_modules/npm/bin/npm-cli.js" ]] || fail "official Node.js archive is incomplete"
+    if [[ "$(id -u)" -eq 0 ]]; then
+      rm -rf "$node_release_dir.pending"
+      mv "$extracted" "$node_release_dir.pending"
+      chown -R "$target_uid:$target_gid" "$node_release_dir.pending"
+      mv "$node_release_dir.pending" "$node_release_dir"
     else
-      run_user_shell "'$brew_command' install node@22"
-      runtime_path_prefix="$(user_output "'$brew_command' --prefix node@22")/bin"
-      export PATH="$runtime_path_prefix:$PATH"
+      mv "$extracted" "$node_release_dir"
     fi
-  else
-    run_root apt-get update
-    run_root apt-get install -y ca-certificates curl gnupg
-    if $dry_run; then
-      printf '+ download https://deb.nodesource.com/setup_22.x to a protected unique temporary directory\n'
-      printf '+ root: bash <protected-temporary-directory>/nodesource-setup.sh\n'
-    else
-      temporary_root="$(mktemp -d)"
-      chmod 700 "$temporary_root"
-      curl --proto '=https' --tlsv1.2 -fsSLo "$temporary_root/nodesource-setup.sh" https://deb.nodesource.com/setup_22.x
-      run_root bash "$temporary_root/nodesource-setup.sh"
-      rm -rf "$temporary_root"
-      temporary_root=""
+  fi
+  "$node_bin" -e 'if (process.versions.node.split(".")[0] !== "22") process.exit(1)'
+  [[ -f "$npm_cli" ]] || fail "managed Node.js runtime does not include npm"
+  run_user ln -sfn "$node_release_dir" "$runtime_root/current"
+fi
+printf '  ✓ Oysterun-managed Node.js 22 verified: %s\n' "$node_version"
+managed_runtime_path="$node_release_dir/bin:${PATH:-/usr/local/bin:/usr/bin:/bin}"
+
+stage="release resolution"
+npm_prefix="$canonical_home/.local/npm"
+active_package_root="$npm_prefix/lib/node_modules/oysterun"
+active_cli_module="$active_package_root/bin/oysterun.mjs"
+installed_version=""
+active_cli_usable=false
+if ! $dry_run && [[ -f "$active_package_root/package.json" ]]; then
+  installed_version="$(capture_user "$node_bin" -p "require(process.argv[1]).version" "$active_package_root/package.json" 2>/dev/null || true)"
+  if [[ -f "$active_cli_module" ]] && capture_user "$node_bin" "$active_cli_module" --version >/dev/null 2>&1; then
+    active_cli_usable=true
+  fi
+fi
+
+recorded_channel=""
+if ! $dry_run && [[ -f "$config_dir/config.json" ]]; then
+  recorded_channel="$(capture_user "$node_bin" -e 'const fs=require("fs");try{const c=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));process.stdout.write(typeof c.oysterun_update_channel==="string"?c.oysterun_update_channel:"")}catch{}' "$config_dir/config.json")"
+fi
+if [[ -n "$requested_channel_override" ]]; then
+  requested_spec="$requested_channel_override"
+  selected_channel="$requested_channel_override"
+else
+  case "$recorded_channel" in
+    beta) requested_spec="beta"; selected_channel="beta" ;;
+    exact:*) requested_spec="${recorded_channel#exact:}"; selected_channel="$recorded_channel" ;;
+    latest|"") requested_spec="latest"; selected_channel="latest" ;;
+    *) fail "existing update channel metadata is invalid: $recorded_channel" ;;
+  esac
+fi
+
+if [[ -n "${OYSTERUN_INSTALL_TEST_PACKAGE:-}" ]]; then
+  [[ -n "${OYSTERUN_INSTALL_TEST_ROOT:-}" && -n "${OYSTERUN_INSTALL_TEST_VERSION:-}" ]] || fail "isolated test package requires TEST_ROOT and TEST_VERSION"
+  [[ "$OYSTERUN_INSTALL_TEST_ROOT" == /* && "$OYSTERUN_INSTALL_TEST_PACKAGE" == /* ]] || fail "isolated test paths must be absolute"
+  [[ -d "$OYSTERUN_INSTALL_TEST_ROOT" && ! -L "$OYSTERUN_INSTALL_TEST_ROOT" ]] || fail "isolated test root must be a non-symlink directory"
+  [[ -f "$OYSTERUN_INSTALL_TEST_PACKAGE" && ! -L "$OYSTERUN_INSTALL_TEST_PACKAGE" ]] || fail "isolated test package must be a regular non-symlink file"
+  test_root="$(cd -P "$OYSTERUN_INSTALL_TEST_ROOT" && pwd -P)"
+  test_package_dir="$(cd -P "$(dirname "$OYSTERUN_INSTALL_TEST_PACKAGE")" && pwd -P)"
+  test_package_path="$test_package_dir/$(basename "$OYSTERUN_INSTALL_TEST_PACKAGE")"
+  [[ "$test_package_path" == "$test_root/"* ]] || fail "isolated test package must be contained by TEST_ROOT"
+  [[ "$OYSTERUN_INSTALL_TEST_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+([+-][0-9A-Za-z.-]+)?$ ]] || fail "isolated test version is invalid"
+  selected_version="$OYSTERUN_INSTALL_TEST_VERSION"
+  selected_channel="beta"
+  package_install_spec="$test_package_path"
+  printf '+ isolated verification package accepted inside %q\n' "$test_root"
+elif $dry_run; then
+  selected_version="<resolved-$requested_spec-version>"
+  package_install_spec="oysterun@$selected_version"
+  printf '+ resolve one exact oysterun@%s package version\n' "$requested_spec"
+else
+  selected_version="$(capture_user env PATH="$managed_runtime_path" NPM_CONFIG_PREFIX="$npm_prefix" "$node_bin" "$npm_cli" view "oysterun@$requested_spec" version --json | "$node_bin" -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const v=JSON.parse(s);process.stdout.write(Array.isArray(v)?v[v.length-1]:v)})')"
+  [[ "$selected_version" =~ ^[0-9]+\.[0-9]+\.[0-9]+([+-][0-9A-Za-z.-]+)?$ ]] || fail "npm returned an invalid Oysterun version"
+  if [[ -n "$installed_version" && -z "$recorded_channel" ]]; then
+    comparison="$("$node_bin" -e "$version_compare_script" "$selected_version" "$installed_version")"
+    if [[ "$comparison" == "-1" ]]; then
+      selected_channel="exact:$installed_version"
+      selected_version="$installed_version"
+      if ( : </dev/tty ) 2>/dev/null; then
+        printf 'This Host runs Oysterun %s.\n' "$installed_version"
+        printf 'Public latest is older and would downgrade this persistent Host.\n\n'
+        printf '  1) Keep %s and repair this exact version\n' "$installed_version"
+        printf '  2) Continue on the Beta channel\n'
+        printf '  3) Stop without changes\n\n'
+        printf 'Update choice [1]: '
+        IFS= read -r downgrade_choice </dev/tty || exit 130
+        case "${downgrade_choice:-1}" in
+          1) ;;
+          2)
+            selected_channel="beta"
+            selected_version="$(capture_user env PATH="$managed_runtime_path" NPM_CONFIG_PREFIX="$npm_prefix" "$node_bin" "$npm_cli" view oysterun@beta version --json | "$node_bin" -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>process.stdout.write(JSON.parse(s)))')"
+            ;;
+          3) fail "stopped before version or service changes" ;;
+          *) fail "update choice must be 1, 2, or 3" ;;
+        esac
+      fi
     fi
-    run_root apt-get install -y nodejs
   fi
+  package_install_spec="oysterun@$selected_version"
 fi
+printf '  ✓ Oysterun release selected: %s (%s)\n' "$selected_version" "$selected_channel"
 
-stage="Node.js verification"
-if ! $dry_run; then
-  user_output 'command -v node >/dev/null' || fail "Node.js installation completed without a node executable for the target user"
-  node_major="$(user_output "node -p 'Number(process.versions.node.split(\".\")[0])'")"
-  [[ "$node_major" -eq 22 ]] || fail "Node.js 22 is required"
-  user_output 'command -v npm >/dev/null' || fail "npm is required for the target user"
+stage="verified package staging"
+driver_prefix="$canonical_home/.local/share/oysterun/bootstrap/$selected_version"
+driver_cli_module="$driver_prefix/lib/node_modules/oysterun/bin/oysterun.mjs"
+run_user mkdir -p "$npm_prefix" "$canonical_home/.local/bin" "$driver_prefix"
+if $dry_run; then
+  printf '+ stage and verify oysterun@%s at %q\n' "$selected_version" "$driver_prefix"
+else
+  capture_user env PATH="$managed_runtime_path" NPM_CONFIG_PREFIX="$driver_prefix" "$node_bin" "$npm_cli" install -g "$package_install_spec" --prefer-online --no-audit --no-fund
+  [[ -f "$driver_cli_module" ]] || fail "staged Oysterun CLI is missing"
+  staged_version="$(capture_user "$node_bin" -p "require(process.argv[1]).version" "$driver_prefix/lib/node_modules/oysterun/package.json")"
+  [[ "$staged_version" == "$selected_version" ]] || fail "staged Oysterun version does not match the selected release"
+  capture_user "$node_bin" --input-type=module - "$driver_prefix/lib/node_modules/oysterun" <<'PORT_CAPABILITY'
+import { pathToFileURL } from 'node:url';
+import path from 'node:path';
+const root = process.argv[2];
+let capability;
+try { capability = await import(pathToFileURL(path.join(root, 'host-service/host-port-resolution.mjs')).href); }
+catch { throw new Error('Selected package cannot preserve configured Host ports. Select a published release with this capability on your chosen channel; no service or active package was changed.'); }
+if (capability.USER_HOST_PORT_CAPABILITY !== 1) throw new Error('Selected package lacks the required persisted-port capability.');
+PORT_CAPABILITY
+  if ! $install_only && [[ -n "$setup_input_file" ]]; then
+    [[ -f "$driver_prefix/lib/node_modules/oysterun/host-service/setup-input-file.mjs" && -f "$driver_prefix/lib/node_modules/oysterun/tool_scripts/oysterun_setup_input.sh" ]] || fail "Selected package cannot accept --setup-input-file; select a capable release on your chosen channel. No service or active package was changed"
+  fi
+  capture_user "$node_bin" "$driver_cli_module" --version
+  capture_user "$node_bin" -e 'require(process.argv[1]);const Database=require(process.argv[2]);const db=new Database(":memory:");db.prepare("select 1").get();db.close()' "$driver_prefix/lib/node_modules/oysterun/node_modules/node-datachannel" "$driver_prefix/lib/node_modules/oysterun/node_modules/better-sqlite3"
 fi
+printf '  ✓ Package prepared: %s; running Host qualification follows onboarding.\n' "$selected_version"
 
-stage="user-owned npm prefix"
-run_user_shell "mkdir -p \"\$HOME/.local/npm\"; npm config set prefix \"\$HOME/.local/npm\" --location=user; touch \"$profile_file\"; grep -qxF 'export PATH=\"\$HOME/.local/npm/bin:\$PATH\"' \"$profile_file\" || printf '\\nexport PATH=\"\$HOME/.local/npm/bin:\$PATH\"\\n' >> \"$profile_file\""
+service_running=false
+service_healthy=false
+if ! $dry_run && [[ -f "$config_dir/config.json" ]]; then
+  stage="existing Host service binding"
+  # The parent supplies the contextual failure. Bash 3.2 otherwise inherits
+  # ERR inside this guarded command substitution and prints recovery twice.
+  staged_status="$(trap - ERR; capture_user env OYSTERUN_CONFIG_DIR="$config_dir" OYSTERUN_NODE_BIN="$node_bin" "$node_bin" "$driver_cli_module" service:status)" || fail "cannot bind the existing Host service; preserve its config/runtime and resolve the reported target mismatch before retrying"
+  printf '%s\n' "$staged_status" | grep -q '^health=yes$' && service_healthy=true
+  if printf '%s\n' "$staged_status" | grep -q '^loaded=yes$' && printf '%s\n' "$staged_status" | grep -Eq '^pid=[0-9]+$'; then
+    service_running=true
+  fi
+fi
 
-if [[ -n "$runtime_path_prefix" ]]; then
-  run_user_shell "grep -qxF 'export PATH=\"$runtime_path_prefix:\$PATH\"' \"$profile_file\" || printf '\\nexport PATH=\"$runtime_path_prefix:\$PATH\"\\n' >> \"$profile_file\""
+# A stopped Host may still own an interrupted update. Preserve its active
+# package and receipts, and use the existing exact staged recovery path before
+# considering an ordinary package install. Explicit reinstall has its own
+# narrower initial-preflight eligibility checks below.
+if ! $dry_run && ! $reinstall && [[ "$service_running" != true && -f "$config_dir/config.json" ]]; then
+  retained_blocking="$(capture_user "$node_bin" --input-type=module - "$driver_prefix/lib/node_modules/oysterun" "$config_dir" <<'RETAINED_LIFECYCLE'
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+const [driver, configDir] = process.argv.slice(2);
+const { readUpdateOperationState, isUpdateOperationBlocking } = await import(pathToFileURL(path.join(driver, 'host-service/update-reminder-state.mjs')).href);
+process.stdout.write(isUpdateOperationBlocking(readUpdateOperationState({ configDir })) ? 'yes' : 'no');
+RETAINED_LIFECYCLE
+)"
+  if [[ "$retained_blocking" == yes ]]; then
+    stage="recover retained lifecycle before package replacement"
+    capture_user env OYSTERUN_CONFIG_DIR="$config_dir" OYSTERUN_RELEASE_STACK=production \
+      "$node_bin" "$driver_prefix/lib/node_modules/oysterun/host-service/cli/recover-installer-lifecycle.mjs" "$config_dir" "$active_package_root"
+    staged_status="$(capture_user env OYSTERUN_CONFIG_DIR="$config_dir" OYSTERUN_NODE_BIN="$node_bin" "$node_bin" "$driver_cli_module" service:status)"
+    printf '%s\n' "$staged_status" | grep -q '^health=yes$' && service_healthy=true
+    if printf '%s\n' "$staged_status" | grep -q '^loaded=yes$' && printf '%s\n' "$staged_status" | grep -Eq '^pid=[0-9]+$'; then
+      service_running=true
+    fi
+    [[ "$service_running" == true && "$service_healthy" == true ]] || fail "retained lifecycle recovery did not restore a healthy bound Host; its package and receipts were preserved"
+    installed_version="$(capture_user "$node_bin" -p "require(process.argv[1]).version" "$active_package_root/package.json")"
+    active_cli_usable=false
+    capture_user "$node_bin" "$active_cli_module" --version >/dev/null && active_cli_usable=true
+  fi
 fi
 
-stage="Oysterun package"
-run_user_shell 'export PATH="$HOME/.local/npm/bin:$PATH"; npm install -g oysterun@latest --prefer-online --no-audit --no-fund; command -v oysterun; oysterun --version; help_text="$(oysterun --help)"; grep -q "oysterun service:status" <<<"$help_text"; grep -q "oysterun show-qr" <<<"$help_text"'
+if $reinstall; then
+  stage="preserve-config reinstall preflight"
+  printf 'Reinstall requested: running sessions will stop; saved configuration, Cloud identity, history and Agent folders are preserved.\n'
+  if $dry_run; then
+    printf '+ verify exact installed Host and reject in-progress or post-mutation recovery before service removal\n'
+  else
+    [[ "$active_cli_usable" == true && -f "$config_dir/config.json" ]] || fail "--reinstall requires the existing usable CLI and Host configuration"
+    reinstall_operation="$(capture_user "$node_bin" --input-type=module - "$driver_prefix/lib/node_modules/oysterun" "$active_package_root" "$config_dir" "$installed_version" "$selected_channel" "$canonical_home" "$target_uid" <<'REINSTALL_PREFLIGHT'
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+const [driver, active, configDir, version, channel, userHome, uid] = process.argv.slice(2);
+const { inspectInstallerReinstall } = await import(pathToFileURL(path.join(driver, 'host-service/installer-recovery-guidance.mjs')).href);
+const { operationId } = inspectInstallerReinstall({ configDir, activePackage: active, installedVersion: version, selectedChannel: channel, userHome, uid });
+process.stdout.write(operationId);
+REINSTALL_PREFLIGHT
+)"
+  fi
+  stage="remove existing service while preserving configuration"
+  run_user env OYSTERUN_CONFIG_DIR="$config_dir" OYSTERUN_RELEASE_STACK=production OYSTERUN_NODE_BIN="$node_bin" \
+    "$node_bin" "$active_cli_module" uninstall --stack production --keep-config
+  if ! $dry_run && [[ -n "$reinstall_operation" ]]; then
+    stage="reconcile stopped initial-preflight failure"
+    run_user env OYSTERUN_CONFIG_DIR="$config_dir" "$node_bin" \
+      "$driver_prefix/lib/node_modules/oysterun/host-service/cli/reconcile-initial-preflight.mjs" \
+      --config-dir "$config_dir" --operation-id "$reinstall_operation"
+  fi
+  if ! $dry_run; then
+    stage="verify stopped Host before package replacement"
+    capture_user "$node_bin" --input-type=module - "$driver_prefix/lib/node_modules/oysterun" "$active_package_root" "$config_dir" <<'REINSTALL_STOPPED'
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+const [driver, active, configDir] = process.argv.slice(2);
+const load = relative => import(pathToFileURL(path.join(driver, 'host-service', relative)).href);
+const { readHostRuntimeMetadata } = await load('host-runtime-diagnostics.mjs');
+const { processDefinitelyAbsent } = await load('initial-preflight-recovery.mjs');
+const { readUpdateOperationState, isUpdateOperationBlocking } = await load('update-reminder-state.mjs');
+const runtime = readHostRuntimeMetadata(configDir);
+if (!runtime || runtime.config_dir !== configDir || runtime.stack_name !== 'production' ||
+    fs.realpathSync(runtime.repo_root) !== fs.realpathSync(active) || !processDefinitelyAbsent(runtime.pid)) {
+  throw new Error('The original Host has not been proven stopped; its active package was not replaced.');
+}
+if (isUpdateOperationBlocking(readUpdateOperationState({ configDir }))) {
+  throw new Error('A lifecycle operation changed during service removal; its evidence and package are preserved.');
+}
+REINSTALL_STOPPED
+  fi
+  service_running=false
+  service_healthy=false
+fi
 
-stage="installation ownership verification"
+package_changed=false
+onboard_mode=()
+[[ "$installed_version" != "$selected_version" ]] && package_changed=true
+if [[ "$service_running" == true && "$service_healthy" != true ]]; then
+  fail "the existing Host is still running but unhealthy; its package was preserved. Inspect its service logs and use its supported lifecycle recovery before retrying"
+fi
+if [[ "$service_running" == true && "$package_changed" == true && "$selected_channel" == exact:* ]]; then
+  fail "the restored running version differs from the selected exact package; its working package was preserved. Choose a compatible update channel explicitly before retrying"
+fi
+if [[ "$service_running" == true && "$service_healthy" == true ]]; then
+  if [[ "$package_changed" == true && "$selected_channel" != exact:* ]]; then
+    onboard_mode+=(--update-required)
+  elif [[ "$active_cli_usable" != true ]]; then
+    onboard_mode+=(--repair-required)
+  fi
+else
+  stage="active package installation"
+  if $dry_run; then
+    printf '+ install verified oysterun@%s into active user prefix %q\n' "$selected_version" "$npm_prefix"
+  else
+    capture_user "$node_bin" "$driver_prefix/lib/node_modules/oysterun/host-service/stopped-user-host-package.mjs" "$config_dir"
+    capture_user env PATH="$managed_runtime_path" NPM_CONFIG_PREFIX="$npm_prefix" "$node_bin" "$npm_cli" config set prefix "$npm_prefix" --location=user
+    capture_user env PATH="$managed_runtime_path" NPM_CONFIG_PREFIX="$npm_prefix" "$node_bin" "$npm_cli" install -g "$package_install_spec" --prefer-online --no-audit --no-fund
+    [[ -f "$active_cli_module" ]] || fail "active Oysterun CLI is missing"
+    active_version="$(capture_user "$node_bin" -p "require(process.argv[1]).version" "$active_package_root/package.json")"
+    [[ "$active_version" == "$selected_version" ]] || fail "active Oysterun version does not match the selected release"
+    capture_user "$node_bin" "$active_cli_module" --version
+  fi
+  if ! $reinstall && [[ "$package_changed" == true ]]; then
+    onboard_mode+=(--package-changed)
+  fi
+fi
+
+if $reinstall; then
+  stage="restore installed Host service"
+  # Install from the active package, never from the temporary bootstrap prefix.
+  # Explicit install recreates launchd and persisted Node/npm identity; start
+  # alone would leave macOS in pid-file mode after service uninstall.
+  run_user env OYSTERUN_CONFIG_DIR="$config_dir" OYSTERUN_RELEASE_STACK=production OYSTERUN_NODE_BIN="$node_bin" \
+    "$node_bin" "$active_cli_module" service:install --stack production
+fi
+
+stage="command launcher"
+launcher_dir="$canonical_home/.local/bin"
+launcher_path="$launcher_dir/oysterun"
+launcher_text="#!/bin/sh
+# Managed by Oysterun installer. Do not edit.
+exec \"$node_bin\" \"$active_cli_module\" \"\$@\"
+"
 if $dry_run; then
-  printf '+ verify npm prefix=%q, executable=%q, and owner=%s\n' "$canonical_home/.local/npm" "$canonical_home/.local/npm/bin/oysterun" "$target_uid"
+  printf '+ write ownership-checked managed launcher %q\n' "$launcher_path"
+else
+  if [[ -e "$launcher_path" || -L "$launcher_path" ]]; then
+    if [[ -f "$launcher_path" ]] && grep -q 'Managed by Oysterun installer' "$launcher_path"; then
+      :
+    elif [[ -L "$launcher_path" ]] && [[ "$(readlink "$launcher_path")" == "$npm_prefix/bin/oysterun" || "$(readlink "$launcher_path")" == "$active_cli_module" ]]; then
+      rm "$launcher_path"
+    else
+      fail "refused to replace a foreign command at $launcher_path"
+    fi
+  fi
+  if [[ "$(id -u)" -eq 0 ]]; then
+    temporary_launcher="$temporary_root/oysterun-user-launcher"
+    printf '%s' "$launcher_text" > "$temporary_launcher"
+    run_root install -o "$target_uid" -g "$target_gid" -m 755 "$temporary_launcher" "$launcher_path"
+  else
+    printf '%s' "$launcher_text" > "$launcher_path"
+    chmod 755 "$launcher_path"
+  fi
+fi
+
+path_has_launcher=false
+case ":${PATH:-}:" in *":$launcher_dir:"*) path_has_launcher=true ;; esac
+if [[ "$path_has_launcher" != true ]]; then
+  IFS=':' read -r -a inherited_path_parts <<< "${PATH:-}"
+  # Bash 3.2 treats an empty array as unset under nounset. Preserve zero
+  # arguments (not one empty argument), without disabling nounset globally.
+  for candidate_dir in ${inherited_path_parts[@]+"${inherited_path_parts[@]}"}; do
+    [[ "$candidate_dir" == "/usr/local/bin" || "$candidate_dir" == "/opt/homebrew/bin" ]] || continue
+    candidate="$candidate_dir/oysterun"
+    if [[ -e "$candidate" || -L "$candidate" ]]; then
+      if [[ -f "$candidate" ]] &&
+        grep -q 'Managed by Oysterun installer' "$candidate" &&
+        grep -Fq -- "$node_bin" "$candidate" &&
+        grep -Fq -- "$active_cli_module" "$candidate"; then
+        :
+      else
+        continue
+      fi
+    fi
+    if $dry_run; then
+      printf '+ install narrow system launcher %q using sudo only if required\n' "$candidate"
+    else
+      temporary_launcher="$temporary_root/oysterun-launcher"
+      printf '%s' "$launcher_text" > "$temporary_launcher"
+      chmod 755 "$temporary_launcher"
+      run_root install -m 755 "$temporary_launcher" "$candidate"
+    fi
+    launcher_path="$candidate"
+    path_has_launcher=true
+    break
+  done
+fi
+
+if [[ "$modify_path" == true ]]; then
+  run_user touch "$profile_file"
+  managed_begin="# >>> Oysterun managed PATH >>>"
+  managed_end="# <<< Oysterun managed PATH <<<"
+  if ! $dry_run; then
+    capture_user "$node_bin" -e 'const fs=require("fs"),p=process.argv[1],b=process.argv[2],e=process.argv[3],d=process.argv[4],esc=v=>v.replace(/[.*+?^${}()|[\]\\]/g,"\\$&");let s=fs.readFileSync(p,"utf8");s=s.replace(new RegExp(`\\n?${esc(b)}[\\s\\S]*?${esc(e)}\\n?`,"g"),"\n").replace(/\\s*$/,"");fs.writeFileSync(p,`${s}\n\n${b}\nexport PATH="${d}:$PATH"\n${e}\n`)' "$profile_file" "$managed_begin" "$managed_end" "$launcher_dir"
+  fi
+  printf '  ✓ PATH configured for future terminals: %s\n' "$profile_file"
 else
-  installed_prefix="$(user_output 'unset NPM_CONFIG_PREFIX npm_config_prefix; npm config get prefix')"
-  installed_cli="$(user_output 'export PATH="$HOME/.local/npm/bin:$PATH"; command -v oysterun')"
-  [[ "$installed_prefix" == "$canonical_home/.local/npm" && "$installed_cli" == "$canonical_home/.local/npm/bin/oysterun" ]] || fail "npm prefix or Oysterun executable is outside the target home"
-  if [[ "$platform" == "Darwin" ]]; then cli_uid="$(stat -f %u "$installed_cli")"; else cli_uid="$(stat -c %u "$installed_cli")"; fi
-  [[ "$cli_uid" == "$target_uid" ]] || fail "Oysterun executable is not owned by the target user"
+  printf '  ○ Shell profile unchanged (--no-modify-path)\n'
 fi
 
-stage="interactive setup"
+stage="Oysterun onboarding"
+onboard_cli_module="$driver_cli_module"
+# A staged driver is needed to update an older live Host. Once the selected
+# package is active, setup and service rendering must use that durable package.
+if [[ "$service_running" != true || ( "$package_changed" != true && "$active_cli_usable" == true ) ]]; then
+  onboard_cli_module="$active_cli_module"
+fi
 if $install_only; then
-  printf 'Oysterun is installed for %s. Run oysterun setup when you are ready to configure and start this Host.\n' "$target_user"
+  printf 'Oysterun files are installed for %s; Host onboarding was intentionally not run (--install-only).\n' "$target_user"
 elif $dry_run; then
-  printf '+ user %s (HOME=%s): oysterun\n' "$target_user" "$target_home"
+  printf '+ user %s: %q onboard --channel %q%s\n' "$target_user" "$onboard_cli_module" "$selected_channel" "${onboard_mode[*]:+ ${onboard_mode[*]}}"
+else
+  # Reinstall and already-current Hosts intentionally have no mode flags.
+  # The guarded expansion also works with macOS system Bash 3.2 and set -u.
+  [[ -z "$setup_input_file" ]] || onboard_mode+=(--setup-input-file "$setup_input_file")
+  onboard_command=(env OYSTERUN_CONFIG_DIR="$config_dir" "$node_bin" "$onboard_cli_module" onboard --channel "$selected_channel" ${onboard_mode[@]+"${onboard_mode[@]}"})
+  if [[ "$setup_input_root_memory" == true ]]; then
+    # target_uid is the verified existing or canonically created account UID.
+    # Two root-owned anonymous read pipes let onboard and setup independently
+    # validate the same snapshot, with no disk copy or secret argv/environment.
+    run_user env OYSTERUN_SETUP_INPUT_FD=3 OYSTERUN_SETUP_INPUT_NEXT_FD=4 "${onboard_command[@]}" \
+      3< <(setup_input_emit_for_uid "$target_uid") 4< <(setup_input_emit_for_uid "$target_uid")
+  elif ( : </dev/tty ) 2>/dev/null; then
+    run_user "${onboard_command[@]}" </dev/tty
+  else
+    run_user "${onboard_command[@]}"
+  fi
+fi
+
+stage="final command verification"
+if ! $dry_run; then
+  capture_user "$launcher_path" --version
+fi
+printf '  ✓ Oysterun command verified: %s\n' "$launcher_path"
+if [[ "$path_has_launcher" == true ]]; then
+  printf 'Current terminal command: oysterun\n'
 else
-  printf 'Oysterun is installed for %s. Starting guided setup now.\n' "$target_user"
-  run_user_shell 'export PATH="$HOME/.local/npm/bin:$PATH"; exec oysterun'
+  printf 'Current terminal: export PATH="%s:$PATH"\n' "$launcher_dir"
 fi