@beeos-ai/cli 1.0.24 → 1.1.1

package/package.json

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

package/scripts/install.Tests.ps1

@@ -80,7 +80,18 @@ Describe "install.ps1 parse-time integrity" {
             "Invoke-BeeosCli",
             # P2-8: PSCore + RunAs auto-elevation helpers.
             "Test-IsAdministrator",
-            "Request-Elevation"
+            "Request-Elevation",
+            # Multi-OS install-link refactor Phase 2: TightVNC
+            # pre-check. install.sh has a parallel `test_vnc_server`
+            # function for Linux. Listed here so a future cleanup
+            # that drops the helper triggers a Pester failure
+            # before reaching customers.
+            "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) {
@@ -161,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

@@ -24,8 +24,23 @@
       $env:BEEOS_DASHBOARD_URL      Dashboard base (OAuth / bind redirect).
       $env:BEEOS_INSTALL_DRY_RUN=1  CI smoke-test escape hatch.
       $env:BEEOS_NO_TELEMETRY=1     Disable script-level telemetry POSTs.
+      $env:BEEOS_NO_DESKTOP=1       Skip TightVNC detection/install hint.
+                                     Forwarded to `beeos init` so the
+                                     CLI's desktop pipeline also stays
+                                     dormant (Phase 2 of the multi-OS
+                                     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
@@ -426,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 {
@@ -464,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
@@ -562,6 +682,47 @@ if (-not (Test-NodeVersion)) {
 $nodeVer = & node -v
 Write-BeeOk "Node.js $nodeVer detected"
 
+# ── TightVNC detection (Phase 2 of multi-OS install-link refactor) ────
+#
+# BeeOS desktop streaming on Windows uses TightVNC + the existing
+# vnc-bridge sidecar (same RFB pipeline as macOS / Linux). The CLI's
+# `DesktopPlatform.windows` adapter takes over once `beeos init` runs:
+# it generates a viewer password, writes the TightVNC registry config
+# under UAC, and starts/restarts `tvnserver`. This script's only job
+# at install time is the user-facing hint — pointing the user at
+# `winget install GlavSoft.TightVNC` so the cold-start has something
+# to configure on the next `beeos init`.
+#
+# Skipped entirely when:
+#   - $env:BEEOS_NO_DESKTOP = "1" (hint AND CLI desktop pipeline off)
+#   - the user opted into `-Device` mode (device-attach flow has its
+#     own VNC handling via `--vnc-host`).
+function Test-VncServer {
+    if ($env:BEEOS_NO_DESKTOP -eq "1") {
+        Write-BeeInfo "BEEOS_NO_DESKTOP=1 — skipping TightVNC detection."
+        return
+    }
+    if ($Device) {
+        # device-attach handles its own VNC story; the OpenClaw
+        # auto-desktop path is only taken by `beeos init`.
+        return
+    }
+    $svc = Get-Service tvnserver -ErrorAction SilentlyContinue
+    $reg = Test-Path "HKLM:\SOFTWARE\TightVNC\Server"
+    if ($svc -or $reg) {
+        Write-BeeOk "TightVNC detected — `beeos init` will configure it for desktop streaming."
+        return
+    }
+    Write-Host ""
+    Write-BeeInfo "Optional: BeeOS desktop streaming on Windows uses TightVNC."
+    Write-Host "  Install with:" -ForegroundColor White
+    Write-Host "    winget install GlavSoft.TightVNC --accept-package-agreements --accept-source-agreements --silent"
+    Write-Host ""
+    Write-Host "  Then re-run `beeos init`. Set $env:BEEOS_NO_DESKTOP = '1' to suppress this hint." -ForegroundColor DarkGray
+    Write-Host ""
+}
+Test-VncServer
+
 # Bootstrap is finished. Hand off to `Invoke-BeeosCli` which performs
 # `npm install -g @beeos-ai/cli` (idempotent — npm short-circuits when
 # the requested version is already on disk) and then runs the freshly

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
@@ -43,8 +45,30 @@
 #   BEEOS_INSTALL_DRY_RUN=1  CI smoke-test escape hatch — return 0
 #                            from main() before any side effect.
 #   BEEOS_NO_TELEMETRY=1     Disable the script-level telemetry POSTs.
+#   BEEOS_NO_DESKTOP=1       Skip the TigerVNC pre-check (Linux) and
+#                            forwarded to `beeos init` so the CLI's
+#                            `getDesktopPipeline()` chokepoint also
+#                            short-circuits, suppressing every macOS /
+#                            Linux cold-start side effect. Mirrors
+#                            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
@@ -451,6 +475,188 @@ print_install_hints() {
   echo ""
 }
 
+# ── TigerVNC pre-check (Linux desktop streaming) ─────────────
+#
+# Mirrors install.ps1's `Test-VncServer`. BeeOS desktop streaming on
+# Linux uses TigerVNC + the `vnc-bridge` sidecar (same RFB pipeline
+# as macOS / Windows). The CLI's `LinuxDesktopPlatform` adapter takes
+# over once `beeos init` runs: it generates a viewer password,
+# writes `~/.vnc/passwd` via `tigervncpasswd -f`, mirrors plaintext
+# into `~/.beeos/vnc.password`, and starts `vncserver :1 -localhost
+# yes` if not already listening. This script's only job at install
+# time is the user-facing hint — pointing the user at the
+# distro-appropriate package so the cold-start has something to
+# configure on the next `beeos init`.
+#
+# Skipped entirely when:
+#   - $BEEOS_NO_DESKTOP = "1" (hint AND CLI desktop pipeline off)
+#   - the user invoked `--device` mode (device-attach handles its own
+#     VNC story via `--vnc-host`).
+#   - host is darwin (macOS Screen Sharing is built-in; the CLI's
+#     `MacosDesktopPlatform` cold-start handles enable + password
+#     generation, no install-time hint needed).
+#
+# Detection: command -v tigervncpasswd or vncpasswd. Both are part
+# of standard distro packages (tigervnc-standalone-server on
+# Debian/Ubuntu, tigervnc-server on Fedora/RHEL, tigervnc on Arch).
+test_vnc_server() {
+  if [[ "${BEEOS_NO_DESKTOP:-}" == "1" ]]; then
+    info "BEEOS_NO_DESKTOP=1 — skipping TigerVNC pre-check."
+    return 0
+  fi
+  if [[ "$MODE" == "device" ]]; then
+    return 0
+  fi
+  if [[ "$OS_KIND" != "linux" ]]; then
+    return 0
+  fi
+  if command -v tigervncpasswd &>/dev/null || command -v vncpasswd &>/dev/null; then
+    success "TigerVNC detected — \`beeos init\` will configure it for desktop streaming."
+    return 0
+  fi
+  echo ""
+  info "Optional: BeeOS desktop streaming on Linux uses TigerVNC."
+  echo "  Install with one of:"
+  echo "    Debian/Ubuntu:  sudo apt install tigervnc-standalone-server"
+  echo "    RHEL/Fedora:    sudo dnf install tigervnc-server"
+  echo "    Arch:           sudo pacman -S tigervnc"
+  echo ""
+  echo "  Then re-run \`beeos init\`. Set BEEOS_NO_DESKTOP=1 to suppress this hint."
+  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
+# (~95% of macOS / Linux users); fish / tcsh / nushell users get a
+# 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?".
+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
+      ;;
+    *)
+      # 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
+
+  # `>>` 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 'export PATH="%s/bin:$PATH"\n' "$prefix"
+    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() {
@@ -497,6 +703,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`
@@ -509,7 +737,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
@@ -559,6 +790,13 @@ main() {
 
   success "Node.js $(node -v) detected"
 
+  # Phase 3 of the multi-OS install-link refactor: TigerVNC pre-check
+  # for Linux. Parallels install.ps1's `Test-VncServer`. Silent
+  # success when the tool is on PATH; printable hint when missing.
+  # Skipped on darwin (macOS Screen Sharing is configured by the
+  # CLI's `MacosDesktopPlatform` cold-start) and in `--device` mode.
+  test_vnc_server
+
   # Bootstrap is finished. Hand off to `run_cli` which performs
   # `npm install -g @beeos-ai/cli` (idempotent — npm short-circuits
   # when the requested version is already on disk) and then `exec`s