@beeos-ai/cli 1.0.7 → 1.0.9

package/package.json

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

package/scripts/install.ps1

@@ -33,6 +33,26 @@ $MinNodeVersion = 18
 
 $CliPackage = if ($Version -eq "latest") { "@beeos-ai/cli@latest" } else { "@beeos-ai/cli@$Version" }
 
+# Sibling packages installed alongside the CLI so that `beeos device attach`
+# works on a clean machine without further `npm i -g` steps (a.k.a. the
+# "fleet ready" install strategy — see agents/device-agent/ARCHITECTURE.md
+# for the 0.2.0+ sibling-pair topology between device-agent and
+# device-mcp-server). Versions are independent of `-Version` (which only
+# pins the CLI) — both packages follow their own semver. Override via
+# $env:BEEOS_DEVICE_AGENT_VERSION / $env:BEEOS_MCP_SERVER_VERSION when you
+# need to pin a specific build (e.g. for a staging smoke test).
+$DeviceAgentVersion = if ($env:BEEOS_DEVICE_AGENT_VERSION) { $env:BEEOS_DEVICE_AGENT_VERSION } else { "latest" }
+$McpServerVersion   = if ($env:BEEOS_MCP_SERVER_VERSION)   { $env:BEEOS_MCP_SERVER_VERSION   } else { "latest" }
+$DeviceAgentPackage = "@beeos-ai/device-agent@$DeviceAgentVersion"
+$McpServerPackage   = "@beeos-ai/device-mcp-server@$McpServerVersion"
+
+# Telemetry endpoint (override with $env:BEEOS_API_URL for staging).
+if (-not $env:BEEOS_API_URL -or $env:BEEOS_API_URL.Length -eq 0) {
+    $script:BeeosApiUrl = "https://public-api.beeos.ai"
+} else {
+    $script:BeeosApiUrl = $env:BEEOS_API_URL
+}
+
 # ── Helpers ──────────────────────────────────────────────────
 
 function Write-BeeInfo  { param([string]$Msg) Write-Host "[beeos] $Msg" -ForegroundColor Cyan }
@@ -40,14 +60,87 @@ function Write-BeeWarn  { param([string]$Msg) Write-Host "[beeos] $Msg" -Foregro
 function Write-BeeError { param([string]$Msg) Write-Host "[beeos] $Msg" -ForegroundColor Red }
 function Write-BeeOk    { param([string]$Msg) Write-Host "[beeos] $Msg" -ForegroundColor Green }
 
+# ── Script-level telemetry (mirror of install.sh send_telemetry) ──
+#
+# Fire-and-forget POST to `/api/v1/telemetry/install`, capped at 2 s,
+# error-swallowing. Matches `web/packages/cli/src/telemetry.ts` event
+# names so dashboard queries don't have to special-case Windows.
+#
+# Opt-out: `$env:BEEOS_NO_TELEMETRY = "1"`.
+function Send-Telemetry {
+    param(
+        [string]$Event,
+        [string]$ErrorCode = "",
+        [bool]$Success = $true
+    )
+    if ($env:BEEOS_NO_TELEMETRY -eq "1") { return }
+
+    $osArch = if ($env:PROCESSOR_ARCHITEW6432) { $env:PROCESSOR_ARCHITEW6432 } else { $env:PROCESSOR_ARCHITECTURE }
+    if (-not $osArch) { $osArch = "unknown" }
+    $nodeVer = ""
+    try {
+        $raw = & node -v 2>$null
+        if ($raw) { $nodeVer = $raw -replace '^v', '' }
+    } catch {}
+
+    $hostname = $env:COMPUTERNAME
+    if (-not $hostname) { $hostname = "unknown" }
+
+    $payload = @{
+        event        = $Event
+        cli_version  = ""
+        dist_tag     = ""
+        os           = "win32"
+        arch         = $osArch
+        node_version = $nodeVer
+        success      = $Success
+        error_code   = $ErrorCode
+        host_hint    = "$hostname-$osArch"
+    } | ConvertTo-Json -Compress
+
+    try {
+        # `-TimeoutSec 2` + `-UseBasicParsing` mirrors `curl --max-time 2`.
+        # Errors are fully swallowed (no Stop propagation).
+        Invoke-RestMethod `
+            -Method POST `
+            -Uri "$($script:BeeosApiUrl.TrimEnd('/'))/api/v1/telemetry/install" `
+            -ContentType "application/json" `
+            -Body $payload `
+            -TimeoutSec 2 `
+            -UseBasicParsing `
+            -ErrorAction SilentlyContinue | Out-Null
+    } catch {
+        # Telemetry MUST NOT break installs.
+    }
+}
+
 # ── Platform detection ───────────────────────────────────────
 
 function Test-Platform {
     $arch = $env:PROCESSOR_ARCHITECTURE
     $effectiveArch = if ($env:PROCESSOR_ARCHITEW6432) { $env:PROCESSOR_ARCHITEW6432 } else { $arch }
     Write-BeeInfo "detected: win32 $effectiveArch"
+
+    # Architecture policy (kept in sync with install.sh):
+    #   - Non-interactive: hard exit 2 — silent warnings are invisible
+    #     in piped installs (`irm | iex`) and would trap users on a
+    #     platform we don't ship native sidecars for.
+    #   - Interactive: warn and require explicit confirmation.
     if ($effectiveArch -notin @("AMD64","ARM64","x86_64")) {
-        Write-BeeWarn "Unusual CPU architecture: $effectiveArch. Some sidecar binaries may be unavailable."
+        $reason = "Unsupported Windows architecture: $effectiveArch (need AMD64 or ARM64)"
+        Write-BeeWarn $reason
+        if (-not [Environment]::UserInteractive) {
+            Send-Telemetry -Event "install.bootstrap.arch_fail" -ErrorCode $reason -Success $false
+            Write-BeeError "Non-interactive shell — aborting."
+            exit 2
+        }
+        $go = Read-Host "Continue anyway? [y/N]"
+        if ($go -notmatch '^(y|yes)$') {
+            Send-Telemetry -Event "install.bootstrap.arch_fail" -ErrorCode $reason -Success $false
+            Write-BeeError "Aborting per user."
+            exit 2
+        }
+        Write-BeeInfo "Proceeding on unsupported arch by user confirmation."
     }
 }
 
@@ -174,6 +267,39 @@ function Read-ExistingInstallAction {
     }
 }
 
+# ── Device-agent sibling suite installer ─────────────────────
+#
+# Installs `@beeos-ai/device-agent` + `@beeos-ai/device-mcp-server` globally
+# so the very first `beeos device attach` on a clean machine does not need
+# to fetch them separately. `@beeos-ai/device-common` is pulled
+# transitively as a `dependencies` entry of both — no separate install
+# needed.
+#
+# Failure here is NEVER fatal: the CLI itself was already installed
+# successfully, and `beeos device attach` will prompt to install missing
+# pieces via ensureDeviceAgent on first use. We just emit a WARN with the
+# manual recovery command.
+function Install-DeviceAgentSuite {
+    $npmPath = Get-Command npm -ErrorAction SilentlyContinue
+    if (-not $npmPath) {
+        Write-BeeWarn "npm not available — skipping device-agent suite install."
+        Write-BeeWarn "Manual fix: install Node + run ``npm i -g $DeviceAgentPackage $McpServerPackage``."
+        return
+    }
+
+    Write-BeeInfo "Installing device-agent suite ($DeviceAgentPackage, $McpServerPackage)..."
+    & npm install -g $DeviceAgentPackage $McpServerPackage
+    if ($LASTEXITCODE -eq 0) {
+        Write-BeeOk "device-agent suite installed."
+    } else {
+        Write-BeeWarn "Failed to install device-agent suite — ``beeos device attach`` will prompt for it on first use."
+        Write-BeeWarn "Manual fix: npm i -g $DeviceAgentPackage $McpServerPackage"
+        # Reset $LASTEXITCODE so subsequent `if ($LASTEXITCODE -ne 0)` checks
+        # in callers don't trip on this non-fatal failure.
+        $global:LASTEXITCODE = 0
+    }
+}
+
 # ── Run CLI ──────────────────────────────────────────────────
 
 function Invoke-BeeosCli {
@@ -187,6 +313,11 @@ function Invoke-BeeosCli {
     if ($ExtraArgs) { $args += $ExtraArgs }
 
     if ($npxPath) {
+        # Temporary / npx path: deliberately do NOT install the device-agent
+        # suite globally. The user opted into the throwaway-install flow, so
+        # we honor that — if they later run `beeos device attach`,
+        # ensureDeviceAgent will guide them through a global install at that
+        # point.
         & npx --yes $CliPackage @args
     } else {
         Write-BeeWarn "npx not found, installing globally..."
@@ -200,6 +331,7 @@ function Invoke-BeeosCli {
             Write-BeeError "  - EACCES / permission error: run PowerShell as Administrator"
             exit 1
         }
+        Install-DeviceAgentSuite
         & beeos @args
     }
 }
@@ -212,13 +344,16 @@ Write-Host "  https://beeos.ai" -ForegroundColor DarkGray
 Write-Host ""
 
 Test-Platform
+Send-Telemetry -Event "install.bootstrap.start"
 
 if (-not (Test-NodeVersion)) {
     if (-not (Install-NodeAuto)) {
+        Send-Telemetry -Event "install.bootstrap.node_fail" -ErrorCode "node_install_failed" -Success $false
         Show-InstallHints
         exit 1
     }
     if (-not (Test-NodeVersion)) {
+        Send-Telemetry -Event "install.bootstrap.node_fail" -ErrorCode "node_version_too_old" -Success $false
         Show-InstallHints
         exit 1
     }
@@ -247,6 +382,7 @@ if ($beeosCmd) {
                 Write-BeeError "  - EACCES / permission error: run PowerShell as Administrator"
                 exit 1
             }
+            Install-DeviceAgentSuite
         }
         "rerun" {
             Write-BeeInfo "Reusing existing install."
@@ -257,6 +393,8 @@ if ($beeosCmd) {
 Write-BeeInfo "Running BeeOS CLI..."
 Write-Host ""
 
+Send-Telemetry -Event "install.bootstrap.success"
+
 if ($Device) {
     Invoke-BeeosCli -Subcommand "device" -ExtraArgs (@("attach") + $Passthrough)
 } else {

package/scripts/install.sh

@@ -27,17 +27,103 @@ RED="\033[31m"
 CYAN="\033[36m"
 
 CLI_PACKAGE="@beeos-ai/cli@latest"
+# Sibling packages installed alongside the CLI so that `beeos device attach`
+# works on a clean machine without further `npm i -g` steps (a.k.a. the
+# "fleet ready" install strategy — see agents/device-agent/ARCHITECTURE.md
+# for the 0.2.0+ sibling-pair topology between device-agent and
+# device-mcp-server). Their versions are independent of `--version` (which
+# only pins the CLI) — both packages follow their own semver. Override via
+# BEEOS_DEVICE_AGENT_VERSION / BEEOS_MCP_SERVER_VERSION when you need to
+# pin a specific build (e.g. for a staging smoke test).
+DEVICE_AGENT_PACKAGE="@beeos-ai/device-agent@${BEEOS_DEVICE_AGENT_VERSION:-latest}"
+MCP_SERVER_PACKAGE="@beeos-ai/device-mcp-server@${BEEOS_MCP_SERVER_VERSION:-latest}"
 MIN_NODE_VERSION=18
 NVM_VERSION="v0.40.1"
 FNM_INSTALL_URL="https://fnm.vercel.app/install"
 
 BEEOS_HOME="${BEEOS_HOME:-$HOME/.beeos}"
+# Default telemetry endpoint. `$BEEOS_API_URL` lets developers aim at
+# staging / a local gateway; empty-or-unset falls back to production.
+BEEOS_API_URL="${BEEOS_API_URL:-https://public-api.beeos.ai}"
+
+# Where the installer writes verbose stderr for Node auto-install.
+# Overridable via `BEEOS_INSTALL_LOG=/path/to/file.log` so support can
+# ask "run the one-liner with `BEEOS_INSTALL_LOG=~/beeos-install.log`
+# and share the log" rather than asking the user to recreate the
+# failure with manual `bash -x`.
+#
+# Pre-P1-12 we buried every `2>/dev/null` in `try_install_node`, which
+# meant bug reports like "nvm install --lts failed" were unreproducible
+# from anything but the user's terminal. We now preserve stderr in a
+# per-PID file and reference it in the terminal hint on failure.
+BEEOS_INSTALL_LOG="${BEEOS_INSTALL_LOG:-/tmp/beeos-install-$$.log}"
+# Truncate on every run so the log reflects only the current attempt.
+: > "$BEEOS_INSTALL_LOG" 2>/dev/null || true
 
 info()    { printf "${BOLD}${CYAN}[beeos]${RESET} %s\n" "$*"; }
 warn()    { printf "${BOLD}${YELLOW}[beeos]${RESET} %s\n" "$*"; }
 error()   { printf "${BOLD}${RED}[beeos]${RESET} %s\n" "$*" >&2; }
 success() { printf "${BOLD}${GREEN}[beeos]${RESET} %s\n" "$*"; }
 
+# ── Telemetry (script-level, pre-CLI) ────────────────────────
+#
+# Mirrors `web/packages/cli/src/telemetry.ts` so we can capture
+# failures that happen BEFORE the Node CLI even starts (e.g. Node
+# install failure, unsupported arch). Fire-and-forget with a 2 s cap —
+# we must never block a real install on a flaky telemetry endpoint.
+#
+# Event names used here:
+#   - install.bootstrap.start        — script entered `main()`
+#   - install.bootstrap.node_fail    — could not install/find Node
+#   - install.bootstrap.arch_fail    — unsupported arch
+#   - install.bootstrap.success      — about to exec `beeos`
+#
+# `BEEOS_NO_TELEMETRY=1` short-circuits everything. This matches the
+# Node CLI's opt-out env var verbatim so a user who disabled telemetry
+# for the CLI doesn't unexpectedly get events from the bootstrap.
+send_telemetry() {
+  local event="$1"
+  local error_code="${2:-}"
+  local success_flag="${3:-true}"
+
+  if [[ "${BEEOS_NO_TELEMETRY:-}" == "1" ]]; then
+    return 0
+  fi
+  if ! command -v curl &>/dev/null; then
+    return 0
+  fi
+
+  local os_kind="${OS_KIND:-unknown}"
+  local os_arch="${OS_ARCH:-unknown}"
+  local node_ver=""
+  if command -v node &>/dev/null; then
+    node_ver=$(node -v 2>/dev/null | sed 's/^v//' || true)
+  fi
+  local host_hint
+  host_hint="$(hostname 2>/dev/null || echo unknown)-${os_arch}"
+
+  # POST body kept deliberately small — matches Node CLI payload.
+  # Note: `cli_version` is empty until after npx install; we fill it
+  # only when the bootstrap telemetry is fired post-install, from the
+  # Node side. For pre-install events it stays "" and that's fine.
+  local body
+  body=$(cat <<JSON
+{"event":"${event}","cli_version":"","dist_tag":"","os":"${os_kind}","arch":"${os_arch}","node_version":"${node_ver}","success":${success_flag},"error_code":"${error_code}","host_hint":"${host_hint}"}
+JSON
+)
+
+  # `--max-time 2` caps the whole request at 2 s. `-o /dev/null -s`
+  # silences output. Swallow non-zero exit — telemetry MUST NOT break
+  # an install.
+  curl -fsS -o /dev/null \
+    --max-time 2 \
+    -H "Content-Type: application/json" \
+    -X POST \
+    -d "$body" \
+    "${BEEOS_API_URL%/}/api/v1/telemetry/install" \
+    2>/dev/null || true
+}
+
 # ── Parse arguments ──────────────────────────────────────────
 
 CLI_VERSION=""
@@ -102,17 +188,46 @@ detect_platform() {
 
   info "detected: ${OS_KIND} ${OS_ARCH}${LIBC_KIND:+ (${LIBC_KIND})}"
 
+  # Architecture policy (kept in sync with install.ps1):
+  #   - Non-interactive (no TTY): hard exit 2. The user cannot see a
+  #     warning scroll past, and we must not silently install a CLI
+  #     that will later fail to download its native sidecars.
+  #   - Interactive TTY: warn and ask for confirmation. Power users
+  #     sometimes run on odd arches (RISC-V Linux, IBM z, early
+  #     Windows-on-ARM) for experimentation; bail out by default, but
+  #     let them override when they know what they're doing.
+  local interactive=0
+  if [[ -t 0 ]] || [[ -t 1 ]]; then interactive=1; fi
+  local arch_bail arch_confirm
+  arch_bail() {
+    local reason="$1"
+    error "$reason"
+    send_telemetry "install.bootstrap.arch_fail" "$reason" false
+    exit 2
+  }
+  arch_confirm() {
+    local reason="$1"
+    warn "$reason"
+    if (( interactive == 0 )); then
+      arch_bail "$reason"
+    fi
+    local yn=""
+    read -rp "Continue anyway? [y/N]: " yn </dev/tty 2>/dev/null || yn=""
+    case "${yn,,}" in
+      y|yes) info "Proceeding on unsupported arch by user confirmation." ;;
+      *)     arch_bail "$reason" ;;
+    esac
+  }
+
   case "$OS_KIND" in
     darwin)
       if [[ "$OS_ARCH" != "arm64" && "$OS_ARCH" != "x86_64" ]]; then
-        error "Unsupported macOS architecture: $OS_ARCH (need arm64 or x86_64)"
-        exit 2
+        arch_confirm "Unsupported macOS architecture: $OS_ARCH (need arm64 or x86_64)"
       fi
       ;;
     linux)
       if [[ "$OS_ARCH" != "arm64" && "$OS_ARCH" != "x86_64" ]]; then
-        error "Unsupported Linux architecture: $OS_ARCH (need arm64 or x86_64)"
-        exit 2
+        arch_confirm "Unsupported Linux architecture: $OS_ARCH (need arm64 or x86_64)"
       fi
       if [[ "$LIBC_KIND" == "musl" ]]; then
         # No musl prebuilt for scrcpy-bridge / vnc-bridge yet. The CLI
@@ -122,8 +237,7 @@ detect_platform() {
       fi
       ;;
     *)
-      error "Unsupported OS: $OS_KIND (use install.ps1 for Windows)"
-      exit 2
+      arch_bail "Unsupported OS: $OS_KIND (use install.ps1 for Windows)"
       ;;
   esac
 }
@@ -151,15 +265,26 @@ check_node() {
 
 try_install_node() {
   info "Node.js not found or too old. Attempting automatic installation..."
+  info "Verbose output appended to: ${BEEOS_INSTALL_LOG}"
   echo ""
 
+  # Every step below redirects stderr to $BEEOS_INSTALL_LOG (append)
+  # so that a post-mortem has the full picture. We deliberately do NOT
+  # use bare `2>/dev/null` anymore — it's the single biggest source of
+  # unactionable bug reports in this layer. Steps still short-circuit
+  # on success to avoid N-second retries when one tool works.
+  {
+    echo "=== try_install_node @ $(date -u +%FT%TZ) ==="
+    echo "OS_KIND=${OS_KIND} OS_ARCH=${OS_ARCH} LIBC_KIND=${LIBC_KIND:-}"
+  } >> "$BEEOS_INSTALL_LOG" 2>&1 || true
+
   # 1. Existing nvm
   export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"
   if [[ -s "$NVM_DIR/nvm.sh" ]]; then
     info "Loading existing nvm..."
     # shellcheck source=/dev/null
     . "$NVM_DIR/nvm.sh"
-    if nvm install --lts 2>/dev/null; then
+    if nvm install --lts >> "$BEEOS_INSTALL_LOG" 2>&1; then
       success "Node.js $(node -v) installed via existing nvm"
       return 0
     fi
@@ -167,10 +292,11 @@ try_install_node() {
 
   # 2. Fresh nvm install
   info "Installing nvm ${NVM_VERSION}..."
-  if curl -fsSL "https://raw.githubusercontent.com/nvm-sh/nvm/${NVM_VERSION}/install.sh" | bash 2>/dev/null; then
+  if curl -fsSL "https://raw.githubusercontent.com/nvm-sh/nvm/${NVM_VERSION}/install.sh" 2>>"$BEEOS_INSTALL_LOG" \
+        | bash >> "$BEEOS_INSTALL_LOG" 2>&1; then
     # shellcheck source=/dev/null
-    . "$NVM_DIR/nvm.sh" 2>/dev/null || true
-    if nvm install --lts 2>/dev/null; then
+    . "$NVM_DIR/nvm.sh" >> "$BEEOS_INSTALL_LOG" 2>&1 || true
+    if nvm install --lts >> "$BEEOS_INSTALL_LOG" 2>&1; then
       success "Node.js $(node -v) installed via nvm"
       return 0
     fi
@@ -179,10 +305,12 @@ try_install_node() {
   # 3. fnm — works on locked-down Linux without git/curl quirks
   if [[ "$OS_KIND" == "linux" ]] && ! command -v fnm &>/dev/null; then
     info "Trying fnm (single-user, no sudo)..."
-    if curl -fsSL "$FNM_INSTALL_URL" | bash -s -- --skip-shell 2>/dev/null; then
+    if curl -fsSL "$FNM_INSTALL_URL" 2>>"$BEEOS_INSTALL_LOG" \
+          | bash -s -- --skip-shell >> "$BEEOS_INSTALL_LOG" 2>&1; then
       export PATH="$HOME/.local/share/fnm:$PATH"
-      eval "$(fnm env --shell bash 2>/dev/null)" || true
-      if fnm install --lts 2>/dev/null && fnm use lts-latest 2>/dev/null; then
+      eval "$(fnm env --shell bash 2>>"$BEEOS_INSTALL_LOG")" || true
+      if fnm install --lts >> "$BEEOS_INSTALL_LOG" 2>&1 \
+         && fnm use lts-latest >> "$BEEOS_INSTALL_LOG" 2>&1; then
         success "Node.js $(node -v) installed via fnm"
         return 0
       fi
@@ -192,7 +320,7 @@ try_install_node() {
   # 4. macOS Homebrew
   if [[ "$OS_KIND" == "darwin" ]] && command -v brew &>/dev/null; then
     info "Trying Homebrew..."
-    if brew install node 2>/dev/null; then
+    if brew install node >> "$BEEOS_INSTALL_LOG" 2>&1; then
       success "Node.js installed via Homebrew"
       return 0
     fi
@@ -205,6 +333,7 @@ try_install_node() {
 
 print_install_hints() {
   error "Could not install Node.js automatically."
+  error "See ${BEEOS_INSTALL_LOG} for full stderr of every attempted method."
   echo ""
   info "Please install Node.js >= ${MIN_NODE_VERSION} manually:"
   echo ""
@@ -294,14 +423,60 @@ prompt_existing_install_action() {
   esac
 }
 
+# ── Device-agent sibling suite installer ─────────────────────
+#
+# Installs `@beeos-ai/device-agent` + `@beeos-ai/device-mcp-server` globally
+# so the very first `beeos device attach` on a clean machine does not need
+# to fetch them separately. `@beeos-ai/device-common` is pulled
+# transitively as a `dependencies` entry of both — no separate install
+# needed.
+#
+# Failure here is NEVER fatal: the CLI itself was already installed
+# successfully, and `beeos device attach` will prompt to install missing
+# pieces via ensureDeviceAgent on first use. We just emit a WARN with the
+# manual recovery command.
+install_device_agent_suite() {
+  if ! command -v npm &>/dev/null; then
+    warn "npm not available — skipping device-agent suite install."
+    warn "Manual fix: install Node + run \`npm i -g ${DEVICE_AGENT_PACKAGE} ${MCP_SERVER_PACKAGE}\`."
+    return 0
+  fi
+
+  info "Installing device-agent suite (${DEVICE_AGENT_PACKAGE}, ${MCP_SERVER_PACKAGE})..."
+  if npm install -g "$DEVICE_AGENT_PACKAGE" "$MCP_SERVER_PACKAGE"; then
+    success "device-agent suite installed."
+  else
+    warn "Failed to install device-agent suite — \`beeos device attach\` will prompt for it on first use."
+    warn "Manual fix: npm i -g ${DEVICE_AGENT_PACKAGE} ${MCP_SERVER_PACKAGE}"
+  fi
+  return 0
+}
+
 # ── Main ─────────────────────────────────────────────────────
 
 run_cli() {
   local subcmd="$1"
   shift || true
 
+  # When invoked as `curl ... | bash`, our own stdin is a pipe that has
+  # already been fully consumed by the time we exec the CLI. Node's
+  # readline treats a closed / non-TTY stdin as "no answer", silently
+  # collapsing every interactive prompt to its default. Reopen stdin
+  # against the controlling terminal so `beeos init` can still ask for
+  # framework choice, bind confirmation, etc. `-t 1` guards us against
+  # true headless runs (CI) where /dev/tty doesn't exist.
+  local stdin_src="/dev/stdin"
+  if [ -t 1 ] && [ -e /dev/tty ]; then
+    stdin_src="/dev/tty"
+  fi
+
   if command -v npx &>/dev/null; then
-    exec npx --yes "$CLI_PACKAGE" "$subcmd" "$@"
+    # Temporary / npx path: deliberately do NOT install the device-agent
+    # suite globally. The user opted into the throwaway-install flow, so
+    # we honor that — if they later run `beeos device attach`,
+    # ensureDeviceAgent will guide them through a global install at that
+    # point.
+    exec npx --yes "$CLI_PACKAGE" "$subcmd" "$@" <"$stdin_src"
   else
     warn "npx not found, installing globally..."
     if ! npm install -g "$CLI_PACKAGE"; then
@@ -314,7 +489,8 @@ run_cli() {
       error "      use a node version manager (nvm / fnm) or sudo"
       exit 1
     fi
-    exec beeos "$subcmd" "$@"
+    install_device_agent_suite
+    exec beeos "$subcmd" "$@" <"$stdin_src"
   fi
 }
 
@@ -325,13 +501,16 @@ main() {
   echo ""
 
   detect_platform
+  send_telemetry "install.bootstrap.start"
 
   if ! check_node; then
     if ! try_install_node; then
+      send_telemetry "install.bootstrap.node_fail" "node_install_failed" false
       print_install_hints
       exit 1
     fi
     if ! check_node; then
+      send_telemetry "install.bootstrap.node_fail" "node_version_too_old" false
       print_install_hints
       exit 1
     fi
@@ -361,6 +540,7 @@ main() {
             error "      use a node version manager (nvm / fnm) or sudo"
             exit 1
           fi
+          install_device_agent_suite
         fi
         ;;
       rerun)
@@ -372,6 +552,8 @@ main() {
   info "Running BeeOS CLI..."
   echo ""
 
+  send_telemetry "install.bootstrap.success"
+
   if [[ "$MODE" == "device" ]]; then
     run_cli "device" "attach" "${PASSTHROUGH_ARGS[@]+"${PASSTHROUGH_ARGS[@]}"}"
   else