@shuyhere/bb-agent 0.0.9 → 0.0.11

package/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to BB-Agent will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.0.11] - 2026-04-07
+
+### Added
+
+- startup update notices in the fullscreen transcript are now highlighted so available updates stand out clearly during startup
+- read-tool line ranges in fullscreen tool activity now highlight the requested span, so values like `2148-2267/5006` stand out while the model is using tools
+
+### Improved
+
+- npm install now caches verified native binaries by version/platform and reuses them on reinstall instead of re-downloading every time
+- npm install now shows more frequent download progress with transfer rate information to make slow installs easier to understand
+- npm install now avoids unnecessary re-verification on cache hits, making repeat installs faster
+
+## [0.0.10] - 2026-04-07
+
+### Fixed
+
+- npm install now uses a longer timeout, retries release-binary downloads, and reports real download errors instead of incorrectly saying no matching prebuilt binary exists
+- npm install now shows progress logs during native binary download and verification so first-time installs on macOS/Linux are less confusing
+- fullscreen `/login` provider-family status now correctly shows OpenAI OAuth state after ChatGPT login instead of incorrectly showing the API key path as not authenticated
+
+### Changed
+
+- README install docs now lead with `npm install -g @shuyhere/bb-agent`, move terminal/font guidance into Troubleshooting, and clearly separate npm install from building from source for development
+
 ## [0.0.9] - 2026-04-07
 
 ### Added
@@ -46,5 +71,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - latest published package includes the post-0.0.7 startup, auth, model-default, and update-notice improvements
 
+[0.0.11]: https://github.com/shuyhere/bb-agent/releases/tag/v0.0.11
+[0.0.10]: https://github.com/shuyhere/bb-agent/releases/tag/v0.0.10
 [0.0.9]: https://github.com/shuyhere/bb-agent/releases/tag/v0.0.9
 [0.0.8]: https://github.com/shuyhere/bb-agent/releases/tag/v0.0.8

package/README.md

@@ -2,44 +2,36 @@
 
 ![BB-Agent title figure](assets/title-figure.png)
 
-BB means Bridge Baby in Death Stranding. I named this project that way because while building it, I was also enjoying Death Stranding and loved the idea of connecting everyone together.
+> BB means Bridge Baby in Death Stranding. I named this project that way because while building it, I was also enjoying Death Stranding and loved the idea of connecting everyone together.
 
 A Rust-native AI coding agent for the terminal — featuring a fullscreen TUI, multi-provider support, tool use, session persistence, branching, extensions, and skills.
 
 ## Install
 
-### Terminal & Font Compatibility
-
-BB-Agent uses Unicode glyphs and ANSI color in the fullscreen TUI. For the best visual experience, use a modern terminal and a Unicode-capable monospace font such as:
-
-- JetBrains Mono
-- SF Mono / Menlo
-- Fira Code
-- Cascadia Mono
-- Nerd Font variants of the above
-
-If some symbols look broken, missing, or too narrow in your terminal:
+```bash
+npm install -g @shuyhere/bb-agent
+```
 
-1. switch to a Unicode-capable monospace font
-2. make sure your terminal uses UTF-8
-3. enable BB-Agent compatibility mode
+### 1. Install with npm
 
-Compatibility mode uses safer ASCII-style fallback glyphs for spinner/status/tool markers:
+npm install downloads a small wrapper package first, then fetches the matching native BB-Agent binary from the GitHub release for your platform.
 
-```bash
-BB_TUI_COMPAT=1 bb
-```
+What to expect:
+- first install can take a bit because npm downloads and verifies the native binary
+- the installer now prints progress and retry information while downloading
+- after install, run `bb`
 
-Or set this in `~/.bb-agent/settings.json`:
+Current GitHub release binaries are published for:
+- Linux x86_64
+- macOS x86_64
+- macOS arm64 (Apple Silicon)
+- Windows x86_64
 
-```json
-{
-  "compatibility_mode": true
-}
-```
+If no matching prebuilt binary is available, or the download fails, npm install will print source-build instructions instead.
 
+### 2. Build from source for development
 
-### From source (all platforms — macOS, Linux, Windows)
+Use this if you want to develop BB-Agent itself, work on the Rust codebase, or install directly without the npm downloader.
 
 Requires [Rust](https://rustup.rs). Install Rust first if you don't have it:
 
@@ -48,7 +40,7 @@ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
 source ~/.cargo/env
 ```
 
-Then build and install BB-Agent:
+Then build and install BB-Agent from source:
 
 ```bash
 git clone https://github.com/shuyhere/bb-agent.git
@@ -58,16 +50,6 @@ cargo install --path crates/cli
 
 This compiles the `bb` binary and installs it to `~/.cargo/bin/bb` (which Rust adds to your PATH).
 
-### npm (Linux/macOS/Windows — downloads matching prebuilt binary when available)
-
-```bash
-npm install -g @shuyhere/bb-agent
-```
-
-> If no matching prebuilt binary is available for your platform, npm install will print source-build instructions instead. After install, run `bb` to start.
->
-> Current GitHub release binaries are published for Linux x86_64, macOS x86_64/arm64, and Windows x86_64.
-
 ## Getting Started
 
 ### 1. Start the TUI
@@ -205,6 +187,38 @@ BB-Agent uses layered configuration:
 | `bb-tui` | Terminal UI components and fullscreen experience |
 | `bb-cli` | The `bb` command-line application |
 
+## Troubleshooting
+
+### Terminal & Font Compatibility
+
+BB-Agent uses Unicode glyphs and ANSI color in the fullscreen TUI. For the best visual experience, use a modern terminal and a Unicode-capable monospace font such as:
+
+- JetBrains Mono
+- SF Mono / Menlo
+- Fira Code
+- Cascadia Mono
+- Nerd Font variants of the above
+
+If some symbols look broken, missing, or too narrow in your terminal:
+
+1. switch to a Unicode-capable monospace font
+2. make sure your terminal uses UTF-8
+3. enable BB-Agent compatibility mode
+
+Compatibility mode uses safer ASCII-style fallback glyphs for spinner/status/tool markers:
+
+```bash
+BB_TUI_COMPAT=1 bb
+```
+
+Or set this in `~/.bb-agent/settings.json`:
+
+```json
+{
+  "compatibility_mode": true
+}
+```
+
 ## Documentation
 
 - [Configuration Reference](docs/configuration.md) — settings.json, AGENTS.md, templates

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shuyhere/bb-agent",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "description": "BB-Agent — a Rust-native AI coding agent for the terminal",
   "license": "MIT",
   "repository": {

package/scripts/postinstall.js

@@ -2,18 +2,21 @@
 
 "use strict";
 
-const { execSync } = require("child_process");
+const { execFileSync } = require("child_process");
 const fs = require("fs");
 const path = require("path");
 const os = require("os");
 const https = require("https");
+const http = require("http");
 
 const packageJson = require("../package.json");
 const BINARY_RELEASE_TAG = `v${packageJson.version}`;
 const REPO = "shuyhere/bb-agent";
-const PACKAGE_ROOT = path.resolve(__dirname, "..");
 const NATIVE_DIR = path.join(__dirname, "..", "native");
-const DOWNLOAD_TIMEOUT_MS = 15_000;
+const DOWNLOAD_TIMEOUT_MS = 120_000;
+const DOWNLOAD_PROGRESS_INTERVAL_MS = 1_000;
+const MAX_REDIRECTS = 8;
+const MAX_DOWNLOAD_ATTEMPTS = 3;
 
 function isWindows() {
   return os.platform() === "win32";
@@ -44,119 +47,482 @@ function getTarget() {
   return `${a}-${p}`;
 }
 
-function downloadBinary(url, dest, timeoutMs) {
-  return new Promise((resolve, reject) => {
-    const timer = setTimeout(() => reject(new Error("Download timed out")), timeoutMs);
+function assetNameForTarget(target) {
+  return isWindows() ? `bb-${target}.exe` : `bb-${target}`;
+}
 
-    const follow = (url, redirects = 0) => {
-      if (redirects > 5) { clearTimeout(timer); return reject(new Error("Too many redirects")); }
+function logLine(message = "") {
+  try {
+    process.stderr.write(`${message}\n`);
+  } catch (_) {}
+}
 
-      const mod = url.startsWith("https") ? https : require("http");
-      const req = mod.get(url, (res) => {
-        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
-          return follow(res.headers.location, redirects + 1);
-        }
-        if (res.statusCode !== 200) {
-          clearTimeout(timer);
-          return reject(new Error(`HTTP ${res.statusCode}`));
-        }
-        const file = fs.createWriteStream(dest);
-        res.pipe(file);
-        file.on("finish", () => { clearTimeout(timer); file.close(); resolve(); });
-        file.on("error", (e) => { clearTimeout(timer); reject(e); });
-      });
-      req.on("error", (e) => { clearTimeout(timer); reject(e); });
-      req.on("timeout", () => { req.destroy(); clearTimeout(timer); reject(new Error("Request timed out")); });
-    };
-    follow(url);
-  });
+function makeDownloadError(kind, message, statusCode) {
+  const err = new Error(message);
+  err.kind = kind;
+  if (statusCode) err.statusCode = statusCode;
+  return err;
 }
 
-function assetNameForTarget(target) {
-  return isWindows() ? `bb-${target}.exe` : `bb-${target}`;
+function formatBytes(bytes) {
+  if (!Number.isFinite(bytes) || bytes <= 0) return "0 B";
+  const units = ["B", "KB", "MB", "GB"];
+  let value = bytes;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit += 1;
+  }
+  return `${value.toFixed(value >= 10 || unit === 0 ? 0 : 1)} ${units[unit]}`;
+}
+
+function formatRate(bytesPerSecond) {
+  if (!Number.isFinite(bytesPerSecond) || bytesPerSecond <= 0) return "0 B/s";
+  return `${formatBytes(bytesPerSecond)}/s`;
+}
+
+function ensureParentDir(filePath) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+function removeIfExists(filePath) {
+  try {
+    fs.unlinkSync(filePath);
+  } catch (_) {}
+}
+
+function binaryVersion(binaryPath) {
+  try {
+    const out = execFileSync(binaryPath, ["--version"], {
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 2500,
+      encoding: "utf8",
+    });
+    return (out || "").trim();
+  } catch (err) {
+    return null;
+  }
+}
+
+function binaryMatchesCurrentVersion(binaryPath) {
+  const version = binaryVersion(binaryPath);
+  if (!version) return false;
+  return version.includes(packageJson.version);
 }
 
 function hasBundledNativeBinary() {
   const dest = nativeBinaryPath();
   if (!fs.existsSync(dest)) return false;
+  if (!binaryMatchesCurrentVersion(dest)) return false;
   try {
-    execSync(`"${dest}" --version`, { stdio: "pipe", timeout: 5000 });
+    fs.accessSync(dest, fs.constants.X_OK);
     return true;
   } catch {
     return false;
   }
 }
 
-async function tryDownloadPrebuilt(target) {
-  const assetName = assetNameForTarget(target);
-  const url = `https://github.com/${REPO}/releases/download/${BINARY_RELEASE_TAG}/${assetName}`;
+function cacheRootDir() {
+  if (process.env.BB_INSTALL_CACHE_DIR && process.env.BB_INSTALL_CACHE_DIR.trim()) {
+    return process.env.BB_INSTALL_CACHE_DIR;
+  }
 
-  fs.mkdirSync(NATIVE_DIR, { recursive: true });
-  const dest = nativeBinaryPath();
+  const home = os.homedir();
+  if (isWindows()) {
+    return path.join(
+      process.env.LOCALAPPDATA || process.env.APPDATA || path.join(home, "AppData", "Local"),
+      "bb-agent"
+    );
+  }
+  if (os.platform() === "darwin") {
+    return path.join(home, "Library", "Caches", "bb-agent");
+  }
+  return path.join(process.env.XDG_CACHE_HOME || path.join(home, ".cache"), "bb-agent");
+}
+
+function cacheBinaryPath(target) {
+  return path.join(cacheRootDir(), "prebuilt", packageJson.version, assetNameForTarget(target));
+}
 
+function cacheMetadataPath(target) {
+  return `${cacheBinaryPath(target)}.json`;
+}
+
+function loadCacheMetadata(target) {
+  try {
+    return JSON.parse(fs.readFileSync(cacheMetadataPath(target), "utf8"));
+  } catch (_) {
+    return null;
+  }
+}
+
+function storeCacheMetadata(target, binaryPath) {
   try {
-    console.log(`Downloading BB-Agent ${BINARY_RELEASE_TAG} for ${target}...`);
-    await downloadBinary(url, dest, DOWNLOAD_TIMEOUT_MS);
+    const stat = fs.statSync(binaryPath);
+    ensureParentDir(cacheMetadataPath(target));
+    fs.writeFileSync(
+      cacheMetadataPath(target),
+      JSON.stringify(
+        {
+          version: packageJson.version,
+          target,
+          assetName: assetNameForTarget(target),
+          binaryName: nativeBinaryName(),
+          size: stat.size,
+          verifiedAt: new Date().toISOString(),
+        },
+        null,
+        2
+      )
+    );
+  } catch (_) {}
+}
+
+function copyBinary(src, dest) {
+  ensureParentDir(dest);
+  fs.copyFileSync(src, dest);
+  if (!isWindows()) {
     fs.chmodSync(dest, 0o755);
+  }
+}
+
+function installFromVerifiedCache(target) {
+  const cached = cacheBinaryPath(target);
+  const meta = loadCacheMetadata(target);
+  if (!fs.existsSync(cached) || !meta) return false;
+  if (meta.version !== packageJson.version || meta.target !== target) return false;
+
+  let stat;
+  try {
+    stat = fs.statSync(cached);
+  } catch (_) {
+    return false;
+  }
+  if (!stat.isFile() || stat.size <= 0) return false;
+  if (meta.size && stat.size !== meta.size) return false;
+
+  logLine(`Using cached BB-Agent binary for ${target} (${formatBytes(stat.size)}).`);
+  copyBinary(cached, nativeBinaryPath());
+  return true;
+}
+
+function refreshCacheFromExistingBinary(target, sourcePath) {
+  if (!binaryMatchesCurrentVersion(sourcePath)) return false;
+  const cached = cacheBinaryPath(target);
+  copyBinary(sourcePath, cached);
+  storeCacheMetadata(target, cached);
+  return true;
+}
+
+function maybeRepairCache(target) {
+  const cached = cacheBinaryPath(target);
+  if (!fs.existsSync(cached)) return false;
 
-    // Verify the binary is executable
+  const meta = loadCacheMetadata(target);
+  if (meta && meta.version === packageJson.version && meta.target === target && meta.size) {
     try {
-      execSync(`"${dest}" --version`, { stdio: "pipe", timeout: 5000 });
-    } catch {
-      // Binary may not run on this platform (e.g. wrong arch) — remove it
-      fs.unlinkSync(dest);
+      const stat = fs.statSync(cached);
+      if (stat.isFile() && stat.size === meta.size) {
+        return false;
+      }
+    } catch (_) {
       return false;
     }
+  }
 
-    console.log("✓ BB-Agent binary installed successfully.");
-    return true;
-  } catch (err) {
-    // Clean up partial download
-    try { fs.unlinkSync(dest); } catch {}
+  logLine(`Checking cached BB-Agent binary for ${target}...`);
+  if (!binaryMatchesCurrentVersion(cached)) {
+    removeIfExists(cached);
+    removeIfExists(cacheMetadataPath(target));
     return false;
   }
+
+  storeCacheMetadata(target, cached);
+  logLine("Verified cached BB-Agent binary for reuse.");
+  return true;
+}
+
+function requestBinary(url, dest, redirects = 0) {
+  return new Promise((resolve, reject) => {
+    if (redirects > MAX_REDIRECTS) {
+      reject(makeDownloadError("redirect", "Too many redirects"));
+      return;
+    }
+
+    const client = url.startsWith("https:") ? https : http;
+    const req = client.get(
+      url,
+      {
+        headers: {
+          "User-Agent": `${packageJson.name}/${packageJson.version} (postinstall)`,
+          Accept: "application/octet-stream,application/octet-stream; q=0.9,*/*;q=0.1",
+        },
+      },
+      (res) => {
+        const status = res.statusCode || 0;
+
+        if (status >= 300 && status < 400 && res.headers.location) {
+          res.resume();
+          requestBinary(res.headers.location, dest, redirects + 1)
+            .then(resolve)
+            .catch(reject);
+          return;
+        }
+
+        if (status === 404) {
+          res.resume();
+          reject(makeDownloadError("not-found", `HTTP 404 for ${url}`, 404));
+          return;
+        }
+
+        if (status !== 200) {
+          res.resume();
+          reject(makeDownloadError("http", `HTTP ${status} for ${url}`, status));
+          return;
+        }
+
+        const totalBytes = Number(res.headers["content-length"] || 0);
+        const startedAt = Date.now();
+        let downloadedBytes = 0;
+        let lastLoggedAt = 0;
+
+        if (totalBytes > 0) {
+          logLine(`Release asset size: ${formatBytes(totalBytes)}.`);
+        } else {
+          logLine("Release asset size: unknown (streaming download).");
+        }
+
+        ensureParentDir(dest);
+        const file = fs.createWriteStream(dest);
+        let settled = false;
+
+        const finish = (fn, value) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timeout);
+          fn(value);
+        };
+
+        res.on("data", (chunk) => {
+          downloadedBytes += chunk.length;
+          const now = Date.now();
+          if (now - lastLoggedAt >= DOWNLOAD_PROGRESS_INTERVAL_MS) {
+            lastLoggedAt = now;
+            const elapsedSeconds = Math.max((now - startedAt) / 1000, 0.001);
+            const rate = downloadedBytes / elapsedSeconds;
+            if (totalBytes > 0) {
+              const percent = Math.min(100, Math.round((downloadedBytes / totalBytes) * 100));
+              logLine(
+                `Download progress: ${percent}% (${formatBytes(downloadedBytes)} / ${formatBytes(totalBytes)}, ${formatRate(rate)})`
+              );
+            } else {
+              logLine(`Downloaded ${formatBytes(downloadedBytes)} so far (${formatRate(rate)})...`);
+            }
+          }
+        });
+
+        file.on("finish", () => {
+          file.close((closeErr) => {
+            if (closeErr) {
+              finish(reject, makeDownloadError("write", closeErr.message));
+            } else {
+              const elapsedSeconds = Math.max((Date.now() - startedAt) / 1000, 0.001);
+              const rate = downloadedBytes / elapsedSeconds;
+              if (totalBytes > 0) {
+                logLine(
+                  `Download complete: ${formatBytes(downloadedBytes)} / ${formatBytes(totalBytes)} in ${elapsedSeconds.toFixed(1)}s (${formatRate(rate)}).`
+                );
+              } else {
+                logLine(
+                  `Download complete: ${formatBytes(downloadedBytes)} in ${elapsedSeconds.toFixed(1)}s (${formatRate(rate)}).`
+                );
+              }
+              finish(resolve);
+            }
+          });
+        });
+
+        file.on("error", (err) => {
+          try { file.close(() => {}); } catch (_) {}
+          removeIfExists(dest);
+          finish(reject, makeDownloadError("write", err.message));
+        });
+
+        res.on("error", (err) => {
+          try { file.close(() => {}); } catch (_) {}
+          removeIfExists(dest);
+          finish(reject, makeDownloadError("network", err.message));
+        });
+
+        res.pipe(file);
+      }
+    );
+
+    const timeout = setTimeout(() => {
+      req.destroy(makeDownloadError("timeout", `Download timed out after ${DOWNLOAD_TIMEOUT_MS}ms`));
+    }, DOWNLOAD_TIMEOUT_MS);
+
+    req.on("error", (err) => {
+      clearTimeout(timeout);
+      reject(makeDownloadError(err.kind || "network", err.message));
+    });
+  });
+}
+
+function verifyBinary(binaryPath) {
+  logLine("Verifying downloaded binary...");
+  const version = binaryVersion(binaryPath);
+  if (!version) {
+    return {
+      ok: false,
+      message: "binary verification failed",
+    };
+  }
+  if (!version.includes(packageJson.version)) {
+    return {
+      ok: false,
+      message: `expected version ${packageJson.version}, got '${version}'`,
+    };
+  }
+  return { ok: true, version };
 }
 
+async function tryDownloadPrebuilt(target) {
+  const assetName = assetNameForTarget(target);
+  const url = `https://github.com/${REPO}/releases/download/${BINARY_RELEASE_TAG}/${assetName}`;
+
+  fs.mkdirSync(NATIVE_DIR, { recursive: true });
+  const dest = nativeBinaryPath();
+  const tmpDest = `${dest}.tmp`;
+
+  if (installFromVerifiedCache(target)) {
+    logLine("✓ BB-Agent binary installed successfully from cache.");
+    return { ok: true, source: "cache" };
+  }
+
+  if (maybeRepairCache(target) && installFromVerifiedCache(target)) {
+    logLine("✓ BB-Agent binary installed successfully from cache.");
+    return { ok: true, source: "cache" };
+  }
+
+  let lastError = null;
+  for (let attempt = 1; attempt <= MAX_DOWNLOAD_ATTEMPTS; attempt += 1) {
+    try {
+      logLine(
+        `Downloading BB-Agent ${BINARY_RELEASE_TAG} for ${target} (attempt ${attempt}/${MAX_DOWNLOAD_ATTEMPTS})...`
+      );
+      logLine("This may take a little while on first install because npm downloads the native binary from the GitHub release.");
+      removeIfExists(tmpDest);
+      await requestBinary(url, tmpDest, 0);
+      if (!isWindows()) {
+        fs.chmodSync(tmpDest, 0o755);
+      }
+
+      const verified = verifyBinary(tmpDest);
+      if (!verified.ok) {
+        removeIfExists(tmpDest);
+        return {
+          ok: false,
+          kind: "verify",
+          message: `Downloaded binary could not run: ${verified.message}`,
+        };
+      }
+
+      fs.renameSync(tmpDest, dest);
+      refreshCacheFromExistingBinary(target, dest);
+      logLine("Cached verified BB-Agent binary for future installs.");
+      logLine("✓ BB-Agent binary installed successfully.");
+      return { ok: true, source: "download" };
+    } catch (err) {
+      lastError = err;
+      removeIfExists(tmpDest);
+      if (err.kind === "not-found") {
+        return {
+          ok: false,
+          kind: "not-found",
+          message: `No release asset named ${assetName} was found for ${BINARY_RELEASE_TAG}.`,
+        };
+      }
+      if (attempt < MAX_DOWNLOAD_ATTEMPTS) {
+        logLine(`Download failed (${err.message}). Retrying...`);
+        await new Promise((resolve) => setTimeout(resolve, 1000 * attempt));
+      }
+    }
+  }
+
+  return {
+    ok: false,
+    kind: (lastError && lastError.kind) || "download",
+    message: (lastError && lastError.message) || "unknown download failure",
+  };
+}
+
+function printFallbackHelp(platform, reason) {
+  logLine("");
+  if (reason && reason.kind === "not-found") {
+    logLine(`BB-Agent ${packageJson.version}: matching prebuilt binary is not published for ${platform}.`);
+  } else if (reason) {
+    logLine(`BB-Agent ${packageJson.version}: failed to download the prebuilt binary for ${platform}.`);
+    logLine(`Reason: ${reason.message}`);
+  } else {
+    logLine(`BB-Agent ${packageJson.version}: matching prebuilt binary not available yet for ${platform}.`);
+  }
+  logLine("");
+  logLine("╔══════════════════════════════════════════════════════════════╗");
+  logLine(
+    "║  BB-Agent: npm could not install native binary for " +
+      platform.padEnd(16) +
+      "   ║"
+  );
+  logLine("║                                                              ║");
+  logLine("║  Install Rust (if needed):                                   ║");
+  logLine("║    https://rustup.rs                                         ║");
+  logLine("║    Then install with rustup for your platform                ║");
+  logLine("║                                                              ║");
+  logLine("║  Then build BB-Agent:                                        ║");
+  logLine("║    git clone https://github.com/shuyhere/bb-agent.git        ║");
+  logLine("║    cd bb-agent && cargo install --path crates/cli            ║");
+  logLine("║                                                              ║");
+  logLine("║  Then run:  bb                                               ║");
+  logLine("╚══════════════════════════════════════════════════════════════╝");
+  logLine("");
+}
 
 async function main() {
   if (process.env.BB_SKIP_POSTINSTALL) {
     return;
   }
 
-  if (hasBundledNativeBinary()) return;
+  if (hasBundledNativeBinary()) {
+    logLine(`BB-Agent ${packageJson.version} native binary already present; skipping download.`);
+    return;
+  }
 
   const target = getTarget();
+  const platform = `${os.platform()}-${os.arch()}`;
 
-  // Try prebuilt binary
   if (target) {
-    const ok = await tryDownloadPrebuilt(target);
-    if (ok) return;
+    const result = await tryDownloadPrebuilt(target);
+    if (result.ok) {
+      return;
+    }
+    printFallbackHelp(platform, result);
+    return;
   }
 
-  // No prebuilt available — print instructions instead of trying cargo build
-  // (cargo build takes 5+ minutes and would appear to hang)
-  const platform = `${os.platform()}-${os.arch()}`;
-  console.log("");
-  console.log(`BB-Agent ${packageJson.version}: matching prebuilt binary not available yet for ${platform}.`);
-  console.log("");
-  console.log("╔══════════════════════════════════════════════════════════════╗");
-  console.log("║  BB-Agent: no prebuilt binary for " + platform.padEnd(19) + "       ║");
-  console.log("║                                                              ║");
-  console.log("║  Install Rust (if needed):                                   ║");
-  console.log("║    https://rustup.rs                                         ║");
-  console.log("║    Then install with rustup for your platform                ║");
-  console.log("║                                                              ║");
-  console.log("║  Then build BB-Agent:                                        ║");
-  console.log("║    git clone https://github.com/shuyhere/bb-agent.git        ║");
-  console.log("║    cd bb-agent && cargo install --path crates/cli            ║");
-  console.log("║                                                              ║");
-  console.log("║  Then run:  bb                                               ║");
-  console.log("╚══════════════════════════════════════════════════════════════╝");
-  console.log("");
-}
-
-main().catch((err) => {
-  // Never fail npm install — just print instructions
-  console.error("BB-Agent postinstall notice:", err.message);
-  console.log("Install manually: git clone https://github.com/shuyhere/bb-agent.git && cd bb-agent && cargo install --path crates/cli");
-});
+  printFallbackHelp(platform, {
+    kind: "unsupported-platform",
+    message: `Unsupported target mapping for ${platform}`,
+  });
+}
+
+main()
+  .catch((err) => {
+    logLine(`BB-Agent postinstall notice: ${err && err.message ? err.message : String(err)}`);
+    logLine(
+      "Install manually: git clone https://github.com/shuyhere/bb-agent.git && cd bb-agent && cargo install --path crates/cli"
+    );
+  })
+  .finally(() => {
+    process.exitCode = 0;
+  });