@beeos-ai/cli 1.1.0 → 1.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beeos-ai/cli",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "type": "module",
   "description": "BeeOS CLI — run AI agents from your desktop",
   "bin": {

package/scripts/install.Tests.ps1

@@ -86,7 +86,12 @@ Describe "install.ps1 parse-time integrity" {
             # function for Linux. Listed here so a future cleanup
             # that drops the helper triggers a Pester failure
             # before reaching customers.
-            "Test-VncServer"
+            "Test-VncServer",
+            # EACCES auto-recovery (Phase 3 of the install pipeline).
+            # install.sh has the parallel `recover_eacces_prefix`.
+            # Dropping this helper would silently regress the Phase 3
+            # self-healing path back to "hint + exit 3".
+            "Invoke-RecoverEaccesPrefix"
         )
 
         foreach ($name in $expected) {
@@ -167,6 +172,58 @@ Describe "install.ps1 stderr log file (P1-I)" {
     }
 }
 
+# ── EACCES auto-recovery (Phase 3) ───────────────────────────
+#
+# Static / structural guards for the Phase 3 self-healing path.
+# Mirrors the install.sh design: when `npm install -g` fails with
+# EACCES on the global node_modules, swap the npm prefix to a
+# user-owned directory and retry exactly once. We deliberately do
+# NOT mock `npm` / `[Environment]::SetEnvironmentVariable` here —
+# Pester mocks for static .NET methods are fragile, and the rest of
+# this test file uses structural / regex assertions for the same
+# reason. Behaviour is exercised end-to-end via the staging EACCES
+# soak (see `.cursor/skills/deploy-staging/install-verify.md`).
+
+Describe "install.ps1 EACCES auto-recovery" {
+    It "writes to User-scope PATH (never Machine, to avoid UAC)" {
+        $content = Get-Content -Raw -Path $script:ScriptPath
+        # The recovery MUST persist on User scope; Machine-scope writes
+        # would silently re-prompt UAC and undo the whole point of
+        # falling back to a user-owned prefix.
+        $content | Should -Match 'SetEnvironmentVariable\(\s*"PATH"\s*,[^,]+,\s*"User"\s*\)'
+        $content | Should -Not -Match 'SetEnvironmentVariable\(\s*"PATH"\s*,[^,]+,\s*"Machine"\s*\)'
+    }
+
+    It "honours BEEOS_NO_NPM_PREFIX_FIX=1 as an opt-out" {
+        $content = Get-Content -Raw -Path $script:ScriptPath
+        $content | Should -Match "BEEOS_NO_NPM_PREFIX_FIX"
+    }
+
+    It "matches the EACCES fingerprint in the npm log" {
+        $content = Get-Content -Raw -Path $script:ScriptPath
+        # Same fingerprint string as install.sh's `grep -qE` — keeps
+        # the two scripts' classifier behaviour aligned. If you tighten
+        # the regex on one side, tighten it here too (and on
+        # install.sh) so a real EACCES on either platform still
+        # triggers recovery.
+        $content | Should -Match 'EACCES.*permission denied.*node_modules'
+    }
+
+    It "emits install.bootstrap.npm_recovered on retry success" {
+        $content = Get-Content -Raw -Path $script:ScriptPath
+        $content | Should -Match 'install\.bootstrap\.npm_recovered'
+        $content | Should -Match 'eacces_prefix'
+    }
+
+    It "still falls through to exit 3 when recovery is skipped or fails" {
+        $content = Get-Content -Raw -Path $script:ScriptPath
+        # Regression guard: the original hint + exit 3 path MUST stay
+        # reachable for non-EACCES failure modes (ETIMEDOUT, EBADENGINE,
+        # ENOSPC ...) and for the case where recovery itself bails.
+        $content | Should -Match 'exit 3'
+    }
+}
+
 # ── Dry-run hook ─────────────────────────────────────────────
 
 Describe "install.ps1 dry-run hook" {

package/scripts/install.ps1

@@ -31,6 +31,16 @@
                                      install-link refactor).
       $env:BEEOS_USE_NPX = "1"      Power-user throwaway install (beeos
                                      won't persist on PATH).
+      $env:BEEOS_NO_NPM_PREFIX_FIX="1" Disable Phase 3 EACCES auto-recovery.
+                                     Recovery (default ON) detects
+                                     "EACCES on lib/node_modules" in the
+                                     npm log, switches the npm prefix
+                                     to %APPDATA%\npm, prepends it on
+                                     User-scope PATH (NEVER Machine —
+                                     that would re-trigger UAC), and
+                                     retries `npm install -g` once.
+                                     Set to 1 to fall back to the legacy
+                                     "hint + exit 3" behaviour.
 
     IMPORTANT (env inheritance):
       $env:BEEOS_API_URL / BEEOS_AGENT_GATEWAY_URL / BEEOS_DASHBOARD_URL
@@ -431,6 +441,80 @@ function Show-InstallHints {
     }
 }
 
+# ── EACCES auto-recovery (Phase 3) ────────────────────────────
+#
+# Mirror of `install.sh::recover_eacces_prefix`. Phase 2 (Node install)
+# already self-heals via winget → choco; Phase 3 (`npm install -g`)
+# historically just printed a hint and exited. EACCES on Windows is
+# rarer than on macOS — the default npm prefix is already user-scoped
+# (`%APPDATA%\npm`) — but it does happen when an Administrator-
+# installed Node has flipped the prefix to `C:\Program Files\nodejs\
+# node_modules`. The fix is symmetric to the POSIX path: switch the
+# prefix back to a user-owned directory and persist on User-scope
+# PATH. We DELIBERATELY do not touch Machine-scope PATH — that would
+# require UAC and silently re-trigger the elevation prompt the user
+# already declined when winget/choco asked.
+#
+# Escape hatch: `$env:BEEOS_NO_NPM_PREFIX_FIX = "1"` short-circuits
+# this function so power users / strict-policy operators can opt out.
+function Invoke-RecoverEaccesPrefix {
+    if ($env:BEEOS_NO_NPM_PREFIX_FIX -eq "1") {
+        Write-BeeInfo "BEEOS_NO_NPM_PREFIX_FIX=1 — skipping auto npm prefix switch."
+        return $false
+    }
+
+    $appData = $env:APPDATA
+    if (-not $appData -or $appData.Length -eq 0) {
+        Write-BeeWarn "APPDATA env not set — cannot pick a user prefix. Falling back to hint."
+        return $false
+    }
+    $prefix = Join-Path $appData "npm"
+    Write-BeeInfo "Switching npm global prefix to $prefix (user-owned)."
+
+    try {
+        New-Item -ItemType Directory -Path $prefix -Force | Out-Null
+    } catch {
+        Write-BeeError "Could not create ${prefix}: $_"
+        return $false
+    }
+
+    try {
+        & npm config set prefix "$prefix" 2>&1 | Tee-Object -FilePath $BeeosInstallLog -Append | Out-Null
+        if ($LASTEXITCODE -ne 0) {
+            Write-BeeError "npm config set prefix failed (exit $LASTEXITCODE)."
+            return $false
+        }
+    } catch {
+        Write-BeeError "npm config set prefix threw: $_"
+        return $false
+    }
+
+    # Make $prefix usable for the upcoming retry IN this session.
+    # Persistence (next terminal) happens via SetEnvironmentVariable
+    # below.
+    $env:Path = "$prefix;" + $env:Path
+
+    # Persist to User-scope PATH so a new terminal sees it. Idempotent —
+    # re-running on an already-fixed host MUST NOT append a duplicate
+    # entry (the User PATH is global to the account; appending without
+    # a contains-check would grow it unboundedly across re-runs).
+    try {
+        $userPath = [Environment]::GetEnvironmentVariable("PATH", "User")
+        if (-not $userPath) { $userPath = "" }
+        if (($userPath -split ";") -notcontains $prefix) {
+            $newUserPath = if ($userPath.Length -gt 0) { "$prefix;$userPath" } else { "$prefix" }
+            [Environment]::SetEnvironmentVariable("PATH", $newUserPath, "User")
+            Write-BeeInfo "Persisted PATH to user environment. Set BEEOS_NO_NPM_PREFIX_FIX=1 to skip on re-runs."
+        } else {
+            Write-BeeInfo "User PATH already contains $prefix — leaving as-is."
+        }
+    } catch {
+        Write-BeeWarn "Could not persist user PATH: $_"
+        Write-BeeWarn "  Add $prefix to PATH manually to keep beeos discoverable in new terminals."
+    }
+    return $true
+}
+
 # ── Run CLI ──────────────────────────────────────────────────
 
 function Invoke-BeeosCli {
@@ -469,18 +553,49 @@ function Invoke-BeeosCli {
     & npm install -g $CliPackage 2>&1 | Tee-Object -FilePath $BeeosInstallLog -Append
     $npmExit = $LASTEXITCODE
     if ($npmExit -ne 0) {
-        # P0-A of the install-link review: fail-after-bootstrap signal.
-        # The `install.bootstrap.cli_installed` event is only emitted
-        # AFTER npm reports success.
-        Send-Telemetry -Event "install.bootstrap.npm_fail" -ErrorCode "npm_install_cli_failed" -Success $false
-        Write-BeeError "npm install -g $CliPackage failed."
-        Write-BeeError "  Full log: $BeeosInstallLog"
-        Write-BeeError ""
-        Write-BeeError "Common fixes:"
-        Write-BeeError "  - EEXIST on beeos from another package:"
-        Write-BeeError "      npm uninstall -g @beeos-ai/cli    # then re-run installer"
-        Write-BeeError "  - EACCES / permission error: run PowerShell as Administrator"
-        exit 3
+        # ── EACCES auto-recovery ──────────────────────────────────
+        # Mirror of install.sh's failure-branch recovery. We grep the
+        # teed log for the EACCES fingerprint; if it matches AND the
+        # user hasn't disabled the auto-fix, we swap the npm prefix
+        # to %APPDATA%\npm + persist to User PATH and retry exactly
+        # once. Other npm error classes (ENOSPC / E401 / EBADENGINE
+        # / ...) fall through to the existing hint+exit path —
+        # rarer, and need user judgement we can't safely automate.
+        $recovered = $false
+        $logContent = if (Test-Path $BeeosInstallLog) {
+            Get-Content -Raw -Path $BeeosInstallLog
+        } else { "" }
+        if ($logContent -match 'EACCES.*permission denied.*node_modules') {
+            Write-BeeWarn "Detected EACCES on global node_modules — attempting auto-recovery."
+            if (Invoke-RecoverEaccesPrefix) {
+                Write-BeeInfo "Retrying npm install with user-owned prefix..."
+                & npm install -g $CliPackage 2>&1 | Tee-Object -FilePath $BeeosInstallLog -Append
+                if ($LASTEXITCODE -eq 0) {
+                    Send-Telemetry -Event "install.bootstrap.npm_recovered" -ErrorCode "eacces_prefix"
+                    $recovered = $true
+                }
+            }
+        }
+        # ── End recovery ──────────────────────────────────────────
+
+        if (-not $recovered) {
+            # P0-A of the install-link review: fail-after-bootstrap signal.
+            # The `install.bootstrap.cli_installed` event is only emitted
+            # AFTER npm reports success.
+            Send-Telemetry -Event "install.bootstrap.npm_fail" -ErrorCode "npm_install_cli_failed" -Success $false
+            Write-BeeError "npm install -g $CliPackage failed."
+            Write-BeeError "  Full log: $BeeosInstallLog"
+            Write-BeeError ""
+            Write-BeeError "Common fixes:"
+            Write-BeeError "  - EEXIST on beeos from another package:"
+            Write-BeeError "      npm uninstall -g @beeos-ai/cli    # then re-run installer"
+            Write-BeeError "  - EACCES / permission error:"
+            Write-BeeError "      auto-recovery already attempted; if it failed, manually"
+            Write-BeeError "      run ``npm config set prefix `"`$env:APPDATA\npm`"`` and"
+            Write-BeeError "      add `$env:APPDATA\npm to your User PATH, then re-run installer."
+            Write-BeeError "      (Set `$env:BEEOS_NO_NPM_PREFIX_FIX = '1' to disable auto-recovery.)"
+            exit 3
+        }
     }
     # Device-agent suite is intentionally NOT installed here; `beeos
     # device attach` will auto-install it on first use via

package/scripts/install.sh

@@ -29,7 +29,9 @@
 #   3   `npm install -g @beeos-ai/cli` failed (CLI didn't reach PATH)
 #
 # Automation can branch on these — `1` is "fix your Node install",
-# `2` is "wrong machine", `3` is "your npm prefix / proxy / disk".
+# `2` is "wrong machine", `3` is "your npm prefix / proxy / disk
+# (after EACCES auto-recovery already attempted, see
+# `BEEOS_NO_NPM_PREFIX_FIX` below)".
 #
 # ── Optional env vars ─────────────────────────────────────────────
 #   BEEOS_API_URL            Public API base (this script uses it for
@@ -51,6 +53,22 @@
 #                            install.ps1's same-named env var.
 #   BEEOS_USE_NPX=1          Power-user throwaway install (beeos won't
 #                            persist on PATH).
+#   BEEOS_NO_NPM_PREFIX_FIX=1 Disable Phase 3 EACCES auto-recovery.
+#                            Recovery (default ON) detects "EACCES on
+#                            lib/node_modules" in the npm log, switches
+#                            the npm global prefix to ~/.npm-global,
+#                            persists $HOME/.npm-global/bin on PATH via
+#                            the user's shell rc (zsh -> ~/.zshrc, bash
+#                            -> ~/.bash_profile on macOS or ~/.bashrc
+#                            on Linux), and retries `npm install -g`
+#                            exactly once. The shell rc edit is wrapped
+#                            in a sentinel block (`# >>> beeos
+#                            npm-prefix >>>` ... `# <<< beeos
+#                            npm-prefix <<<`) so it can be reverted by
+#                            removing the block AND running
+#                            `npm config delete prefix`. Set this var
+#                            to 1 to fall back to the legacy
+#                            "hint + exit 3" behaviour.
 #
 # IMPORTANT (env inheritance):
 #   BEEOS_API_URL / BEEOS_AGENT_GATEWAY_URL / BEEOS_DASHBOARD_URL must
@@ -401,8 +419,8 @@ try_install_node() {
     fi
   fi
 
-  # 4. macOS Homebrew (last resort — already-installed brew only,
-  # we don't try to install brew itself).
+  # 4. macOS Homebrew (already-installed brew only — we don't install
+  # brew itself).
   if [[ "$OS_KIND" == "darwin" ]] && command -v brew &>/dev/null; then
     info "Trying Homebrew..."
     if brew install node >> "$BEEOS_INSTALL_LOG" 2>&1; then
@@ -411,6 +429,91 @@ try_install_node() {
     fi
   fi
 
+  # 5. Linux distro package manager (last resort).
+  #
+  # nvm + fnm both depend on `curl` to fetch the Node tarball from
+  # nodejs.org. Locked-down corporate networks frequently block
+  # `nodejs.org` while still allowing the distro mirror, so a system
+  # package install is the only way through. We deliberately put this
+  # AFTER nvm/fnm because:
+  #
+  #   1. distro Node LTS versions lag — Debian stable was on Node 18
+  #      well into the Node 20 era, breaking device-agent's engines
+  #      requirement. nvm/fnm pull current LTS regardless.
+  #   2. apt/dnf/pacman normally need root, which is a different
+  #      security posture than user-scope nvm. We require sudo -n
+  #      (non-interactive) to detect "user is already root or has
+  #      passwordless sudo" — anything else falls through to the
+  #      hint block.
+  #
+  # Operators on hardened systems can disable this branch entirely
+  # with BEEOS_NO_PKG_MANAGER_NODE=1 and rely on their own provisioning.
+  if [[ "$OS_KIND" == "linux" ]] \
+     && [[ "${BEEOS_NO_PKG_MANAGER_NODE:-}" != "1" ]]; then
+    # `sudo -n true` returns 0 only when sudo is configured to skip the
+    # password prompt for the current user, OR when we're already root.
+    # No prompt = no surprise password dialog mid-install.
+    local sudo_cmd=""
+    if [[ $EUID -eq 0 ]]; then
+      sudo_cmd=""
+    elif command -v sudo &>/dev/null && sudo -n true 2>/dev/null; then
+      sudo_cmd="sudo -n"
+    else
+      info "Linux package managers require root and sudo is not passwordless — skipping."
+    fi
+
+    if [[ -n "$sudo_cmd" || $EUID -eq 0 ]]; then
+      # Probe in order of decreasing prevalence. Each branch is
+      # idempotent and short-circuits the chain on success.
+      if command -v apt-get &>/dev/null; then
+        info "Trying apt-get (Debian / Ubuntu)..."
+        # NodeSource setup script is the canonical way to get a
+        # current Node LTS on Debian-family distros. Same retry/log
+        # discipline as nvm above.
+        if curl -fsSL https://deb.nodesource.com/setup_lts.x \
+              | $sudo_cmd bash >> "$BEEOS_INSTALL_LOG" 2>&1 \
+           && $sudo_cmd apt-get install -y nodejs >> "$BEEOS_INSTALL_LOG" 2>&1; then
+          success "Node.js installed via apt-get"
+          return 0
+        fi
+      elif command -v dnf &>/dev/null; then
+        info "Trying dnf (Fedora / RHEL)..."
+        if curl -fsSL https://rpm.nodesource.com/setup_lts.x \
+              | $sudo_cmd bash >> "$BEEOS_INSTALL_LOG" 2>&1 \
+           && $sudo_cmd dnf install -y nodejs >> "$BEEOS_INSTALL_LOG" 2>&1; then
+          success "Node.js installed via dnf"
+          return 0
+        fi
+      elif command -v yum &>/dev/null; then
+        info "Trying yum (CentOS / Amazon Linux)..."
+        if curl -fsSL https://rpm.nodesource.com/setup_lts.x \
+              | $sudo_cmd bash >> "$BEEOS_INSTALL_LOG" 2>&1 \
+           && $sudo_cmd yum install -y nodejs >> "$BEEOS_INSTALL_LOG" 2>&1; then
+          success "Node.js installed via yum"
+          return 0
+        fi
+      elif command -v pacman &>/dev/null; then
+        info "Trying pacman (Arch)..."
+        if $sudo_cmd pacman -Sy --noconfirm nodejs npm >> "$BEEOS_INSTALL_LOG" 2>&1; then
+          success "Node.js installed via pacman"
+          return 0
+        fi
+      elif command -v zypper &>/dev/null; then
+        info "Trying zypper (openSUSE)..."
+        if $sudo_cmd zypper --non-interactive install nodejs npm >> "$BEEOS_INSTALL_LOG" 2>&1; then
+          success "Node.js installed via zypper"
+          return 0
+        fi
+      elif command -v apk &>/dev/null; then
+        info "Trying apk (Alpine)..."
+        if $sudo_cmd apk add --no-cache nodejs npm >> "$BEEOS_INSTALL_LOG" 2>&1; then
+          success "Node.js installed via apk"
+          return 0
+        fi
+      fi
+    fi
+  fi
+
   return 1
 }
 
@@ -507,6 +610,182 @@ test_vnc_server() {
   echo ""
 }
 
+# ── EACCES auto-recovery (Phase 3) ────────────────────────────
+#
+# Phase 2 of the bootstrap pipeline (Node install) already has a
+# multi-strategy auto-recovery loop in `try_install_node` (nvm → fnm
+# → brew). Phase 3 (`npm install -g @beeos-ai/cli`) historically had
+# none — it just printed a hint and exited 3. The single most common
+# Phase 3 failure is EACCES on the system-owned global node_modules
+# (typically `/usr/local/lib/node_modules` after a nodejs.org .pkg
+# install or a sudo brew install). The two helpers below close that
+# gap with the same shape Phase 2 uses: a small detect function +
+# an idempotent recovery function. `run_cli` calls them only when
+# the npm log carries the EACCES fingerprint; every other npm
+# failure mode is rarer and needs user judgement we can't safely
+# automate from a curl|bash one-liner.
+
+# Detect the user's preferred shell init file so that an `export
+# PATH=...` write survives a new terminal. We support zsh, bash, fish,
+# and pwsh-on-Unix (~99% of macOS / Linux users); tcsh / nushell users
+# still get the printed hint instead of a silent edit to a file we
+# don't fully understand. `$SHELL` is the login shell as recorded in
+# /etc/passwd, NOT the currently-running interpreter — that's exactly
+# what we want for "what does the user's NEXT terminal source?".
+#
+# fish + pwsh emit different PATH syntaxes. The persisted block in
+# `recover_eacces_prefix` below picks the right form by checking the
+# rc path's basename, keeping shell detection isolated to this helper.
+detect_shell_rc() {
+  local shell_name
+  shell_name="$(basename "${SHELL:-}")"
+  case "$shell_name" in
+    zsh)
+      # zsh's per-user interactive rc. macOS Terminal.app sources it
+      # for both login and non-login zsh sessions. We deliberately do
+      # NOT touch ~/.zprofile (login-only) — keeping all our writes
+      # in a single file makes "how do I revert?" a one-line answer.
+      printf '%s' "$HOME/.zshrc"
+      ;;
+    bash)
+      # macOS Terminal.app launches each window as a login bash, so
+      # the canonical sourced file is ~/.bash_profile. Linux GUI
+      # terminals run interactive non-login bash and source ~/.bashrc.
+      if [[ "$OS_KIND" == "darwin" ]]; then
+        printf '%s' "$HOME/.bash_profile"
+      else
+        printf '%s' "$HOME/.bashrc"
+      fi
+      ;;
+    fish)
+      # fish auto-sources every *.fish under ~/.config/fish/conf.d/,
+      # so a single dropped-in file is the idiomatic way to add PATH
+      # without touching the user's main config.fish. mkdir is
+      # idempotent and ignored on permission errors.
+      mkdir -p "$HOME/.config/fish/conf.d" 2>/dev/null || true
+      printf '%s' "$HOME/.config/fish/conf.d/beeos.fish"
+      ;;
+    pwsh)
+      # PowerShell on Linux / macOS reads
+      # ~/.config/powershell/Microsoft.PowerShell_profile.ps1 by
+      # default for the current user, all hosts. The exact filename
+      # is case-sensitive on Linux — preserve it.
+      mkdir -p "$HOME/.config/powershell" 2>/dev/null || true
+      printf '%s' "$HOME/.config/powershell/Microsoft.PowerShell_profile.ps1"
+      ;;
+    *)
+      # Empty string ⇒ caller falls back to a manual-paste hint.
+      printf '%s' ""
+      ;;
+  esac
+}
+
+# Switch the npm global prefix to a user-owned directory and persist
+# the resulting PATH change to the user's shell rc. Used as the EACCES
+# auto-recovery in `run_cli`. Idempotent — running on an already-
+# fixed host is a no-op (the sentinel block check below prevents
+# duplicate appends).
+#
+# Why this approach (and not the alternatives):
+#
+#   - sudo retry: would leave /usr/local/lib/node_modules/@beeos-ai/cli
+#     owned by root, breaking the next `npm update -g` and creating
+#     ownership inconsistencies between the CLI binary and ~/.beeos
+#     (which the user owns). It's the kind of "fix" that buries the
+#     real problem deeper.
+#
+#   - force-install nvm: intrusive for a user who already has a
+#     working Node toolchain, and risks breaking other tools that
+#     depend on the system Node path.
+#
+#   - just print a hint: the original behaviour. Pushes the fix onto
+#     the user, who has to switch contexts mid-install. Most users
+#     give up here.
+#
+# The chosen path mirrors npm's own documentation:
+# https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally
+#
+# Escape hatch: `BEEOS_NO_NPM_PREFIX_FIX=1` short-circuits this
+# function so power users / strict-dotfiles operators can opt out.
+recover_eacces_prefix() {
+  if [[ "${BEEOS_NO_NPM_PREFIX_FIX:-}" == "1" ]]; then
+    info "BEEOS_NO_NPM_PREFIX_FIX=1 — skipping auto npm prefix switch."
+    return 1
+  fi
+
+  local prefix="$HOME/.npm-global"
+  info "Switching npm global prefix to ${prefix} (user-owned)."
+
+  if ! mkdir -p "$prefix" >> "$BEEOS_INSTALL_LOG" 2>&1; then
+    error "Could not create ${prefix} — falling back to hint."
+    return 1
+  fi
+  if ! npm config set prefix "$prefix" >> "$BEEOS_INSTALL_LOG" 2>&1; then
+    error "npm config set prefix failed — falling back to hint."
+    return 1
+  fi
+
+  # Make the new prefix usable for the upcoming retry IN this
+  # session. Persistence (next terminal) happens via shell rc below.
+  export PATH="$prefix/bin:$PATH"
+
+  local rc
+  rc="$(detect_shell_rc)"
+  if [[ -z "$rc" ]]; then
+    warn "Unsupported login shell ($(basename "${SHELL:-unknown}")) — could not"
+    warn "  persist PATH automatically. Add this line to your shell init:"
+    warn "    export PATH=\"$prefix/bin:\$PATH\""
+    return 0
+  fi
+
+  # Sentinel block — grep + sed can remove it cleanly. We check for
+  # the BEGIN marker so re-runs of the installer don't append the
+  # block twice (the file may have been edited by hand between runs).
+  local marker_begin="# >>> beeos npm-prefix >>>"
+  local marker_end="# <<< beeos npm-prefix <<<"
+  if [[ -f "$rc" ]] && grep -qF "$marker_begin" "$rc"; then
+    info "Sentinel block already present in ${rc} — leaving as-is."
+    return 0
+  fi
+
+  # Pick PATH-export syntax based on the rc file's basename. fish and
+  # pwsh need different forms; sh-family rcs all share `export PATH=...`.
+  local rc_base
+  rc_base="$(basename "$rc")"
+  local export_line
+  case "$rc_base" in
+    *.fish)
+      # `fish_add_path -g` prepends to the global PATH list and is the
+      # idiomatic way fish persists PATH (universal fish_user_paths).
+      export_line="fish_add_path -g \"${prefix}/bin\""
+      ;;
+    Microsoft.PowerShell_profile.ps1)
+      # PowerShell uses semicolon-delimited PATH on Windows but ':' on
+      # Unix where pwsh runs. `$env:PATH` mutation in the profile is
+      # the canonical way; we use the Unix separator literal because
+      # pwsh-on-Unix is the only host that reads this rc.
+      export_line="\$env:PATH = \"${prefix}/bin:\" + \$env:PATH"
+      ;;
+    *)
+      # zsh / bash / dash-family — the historical contract.
+      export_line="export PATH=\"${prefix}/bin:\$PATH\""
+      ;;
+  esac
+
+  # `>>` never clobbers existing content. If the rc doesn't exist yet
+  # (fresh user account), the redirect creates it with 0644 perms.
+  {
+    printf '\n%s\n' "$marker_begin"
+    printf '# Added by https://beeos.ai/install on %s\n' "$(date -u +%FT%TZ)"
+    printf '# Reason: system npm prefix was not writable (EACCES).\n'
+    printf '# To revert: delete this block AND run `npm config delete prefix`.\n'
+    printf '%s\n' "$export_line"
+    printf '%s\n' "$marker_end"
+  } >> "$rc"
+  info "Persisted PATH to ${rc}. Set BEEOS_NO_NPM_PREFIX_FIX=1 to skip on re-runs."
+  return 0
+}
+
 # ── Main ─────────────────────────────────────────────────────
 
 run_cli() {
@@ -553,6 +832,28 @@ run_cli() {
   # the time they go to copy-paste. `set -o pipefail` (file header)
   # ensures the pipe's exit status is `npm`'s, not `tee`'s.
   if ! npm install -g "$CLI_PACKAGE" 2>&1 | tee -a "$BEEOS_INSTALL_LOG"; then
+    # ── EACCES auto-recovery ──────────────────────────────────────
+    # The single most common Phase 3 failure: the system npm prefix
+    # is owned by root, EACCES on rename. Detect the fingerprint in
+    # the npm log we just teed; if it matches, swap the prefix to a
+    # user-owned dir (see `recover_eacces_prefix` for the rationale)
+    # and retry exactly once. Every other npm error class
+    # (ENOSPC / ETIMEDOUT / EBADENGINE / ...) falls through to the
+    # hint+exit path below — those are rarer in practice and need
+    # human judgement we can't safely automate.
+    if grep -qE 'EACCES.*permission denied.*node_modules' "$BEEOS_INSTALL_LOG"; then
+      warn "Detected EACCES on global node_modules — attempting auto-recovery."
+      if recover_eacces_prefix; then
+        info "Retrying npm install with user-owned prefix..."
+        if npm install -g "$CLI_PACKAGE" 2>&1 | tee -a "$BEEOS_INSTALL_LOG"; then
+          send_telemetry "install.bootstrap.npm_recovered" "eacces_prefix"
+          send_telemetry "install.bootstrap.cli_installed"
+          exec beeos "$subcmd" "$@" <"$stdin_src"
+        fi
+      fi
+    fi
+    # ── End recovery ──────────────────────────────────────────────
+
     # P0-A of the install-link review: separate "Node ready" from
     # "CLI is actually on PATH" so the dashboard never reports a
     # success that the user can't reproduce. `install.bootstrap.npm_fail`
@@ -565,7 +866,10 @@ run_cli() {
     error "  - EEXIST on /bin/beeos from another package:"
     error "      npm uninstall -g @beeos-ai/cli    # then re-run installer"
     error "  - EACCES permission error:"
-    error "      use a node version manager (nvm / fnm) or sudo"
+    error "      auto-recovery already attempted; if it failed, manually"
+    error "      run \`npm config set prefix \"\$HOME/.npm-global\"\` and"
+    error "      add \$HOME/.npm-global/bin to PATH, then re-run installer."
+    error "      (Set BEEOS_NO_NPM_PREFIX_FIX=1 to disable auto-recovery.)"
     exit 3
   fi
   # NPM succeeded — CLI is now on PATH. The device-agent suite is