@polderlabs/bizar 5.6.0-beta.7 → 5.6.0-beta.9

package/cli/agent-browser-up.sh

@@ -132,5 +132,21 @@ case "${1:-start}" in
   status)  ensure_binary; print_status ;;
   doctor)  ensure_binary; $AB_BIN doctor ;;
   install) ensure_binary; ensure_chrome; $AB_BIN install ;;
+  help|--help|-h)
+    cat <<'AGENT_BROWSER_UP_HELP'
+agent-browser-up -- start/stop the agent-browser daemon
+
+Usage: cli/agent-browser-up.sh <command>
+
+Commands:
+  start    Start the daemon (idempotent)
+  stop     Stop the daemon
+  restart  Stop + start
+  status   Print daemon status
+  doctor   Run agent-browser doctor
+  install  Install agent-browser + download Chrome
+AGENT_BROWSER_UP_HELP
+    exit 0
+    ;;
   *)       fail "unknown command: $1 (use start|stop|restart|status|doctor|install)" ;;
 esac

package/cli/agent-browser-update.mjs

@@ -0,0 +1,322 @@
+/**
+ * cli/agent-browser-update.mjs
+ *
+ * v6.0.0 — Install / update / verify the `agent-browser` CLI.
+ *
+ * `agent-browser` is a native Rust CLI from vercel-labs (~38K★) that
+ * gives Bizar agents a complete browser-automation surface:
+ *   - 100+ typed CLI commands (open, snapshot, click, fill, screenshot, ...)
+ *   - Native MCP stdio server (`agent-browser mcp`)
+ *   - Self-healing snapshot-based element refs (`@e2`)
+ *   - Plugin system (vault, recorder, ...)
+ *   - Vercel AI SDK + AI Gateway integration
+ *
+ * This module is the single source of truth for installing and
+ * updating `agent-browser`. It is used by:
+ *   - cli/install.mjs (during `bizar install`)
+ *   - cli/provision.mjs (during `bizar update`)
+ *   - cli/agent-browser-up.sh (the bash idempotent starter; on first
+ *     run it shells to `npm install -g agent-browser` if the binary
+ *     is missing — this module is the rich equivalent)
+ *
+ * Public API:
+ *   detectState()       probe what's installed without modifying
+ *   install(opts)       install + download Chrome for Testing
+ *   update(opts)        upgrade to the latest version
+ *   ensureRunning()     bring the daemon up if it's down
+ *   printStatus()       one-line status for the user
+ *
+ * All functions are idempotent and safe to re-run.
+ */
+
+import { execSync, spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import chalk from 'chalk';
+
+const DEFAULT_DAEMON_PORT = 9223;
+const DEFAULT_PROFILE_DIR = join(homedir(), '.agent-browser', 'profile');
+
+// ── detection ──────────────────────────────────────────────────────────
+
+/**
+ * Probe the current agent-browser install without modifying anything.
+ *
+ * Returns a structured state object:
+ *   {
+ *     installed: boolean,
+ *     version: string | null,
+ *     chromeReady: boolean,
+ *     daemonRunning: boolean,
+ *     profileDir: string,
+ *     daemonPort: number,
+ *   }
+ */
+export function detectState() {
+  const state = {
+    installed: false,
+    version: null,
+    chromeReady: false,
+    daemonRunning: false,
+    profileDir: DEFAULT_PROFILE_DIR,
+    daemonPort: DEFAULT_DAEMON_PORT,
+    bin: null,
+  };
+
+  // 1. Find the binary
+  const bin = findAgentBrowserBin();
+  state.bin = bin;
+  if (!bin) return state;
+
+  // 2. Get the version
+  try {
+    const out = execSync(`"${bin}" --version`, { encoding: 'utf8', timeout: 5_000 }).trim();
+    state.version = out;
+    state.installed = true;
+  } catch {
+    return state;
+  }
+
+  // 3. Check Chrome for Testing
+  const chromeDir = join(homedir(), '.cache', 'agent-browser', 'chrome');
+  if (existsSync(chromeDir)) state.chromeReady = true;
+
+  // 4. Check daemon (read env on every call so tests can override)
+  const port = parseInt(process.env.AGENT_BROWSER_PORT ?? String(DEFAULT_DAEMON_PORT), 10);
+  state.daemonPort = port;
+  state.daemonRunning = isDaemonUp(port);
+
+  return state;
+}
+
+function findAgentBrowserBin() {
+  // 1. Explicit override
+  if (process.env.AGENT_BROWSER_BIN && existsSync(process.env.AGENT_BROWSER_BIN)) {
+    return process.env.AGENT_BROWSER_BIN;
+  }
+  // 2. Well-known npm-global locations
+  const candidates = [
+    '/usr/local/bin/agent-browser',
+    '/opt/homebrew/bin/agent-browser',
+    join(homedir(), '.local', 'bin', 'agent-browser'),
+    join(homedir(), '.npm', 'bin', 'agent-browser'),
+  ];
+  for (const c of candidates) {
+    if (existsSync(c)) return c;
+  }
+  // 3. PATH lookup
+  try {
+    const r = execSync('command -v agent-browser', { encoding: 'utf8', timeout: 2_000 }).trim();
+    if (r && existsSync(r)) return r;
+  } catch {
+    // fall through
+  }
+  return null;
+}
+
+function isDaemonUp(port) {
+  try {
+    execSync(
+      `curl -fsS --max-time 1 "http://127.0.0.1:${port}/json/version" >/dev/null 2>&1`,
+      { shell: '/bin/bash', timeout: 2_000 },
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ── install / update ───────────────────────────────────────────────────
+
+/**
+ * Install agent-browser. Idempotent: skips steps that are already
+ * complete. Returns the updated state.
+ *
+ * @param {object} opts
+ * @param {boolean} [opts.silent=false]   suppress info output (for CI)
+ * @param {boolean} [opts.dryRun=false]   print actions, make no changes
+ * @param {string}  [opts.channel='latest']  npm dist-tag (e.g. 'beta')
+ * @param {boolean} [opts.startDaemon=true]   start the daemon after install
+ */
+export function install(opts = {}) {
+  const { silent = false, dryRun = false, channel = 'latest', startDaemon = true } = opts;
+  const log = silent ? () => {} : (msg) => console.log(chalk.cyan('  → ') + msg);
+
+  const before = detectState();
+  if (before.installed) {
+    log(`agent-browser ${before.version} already installed at ${before.bin}`);
+    if (startDaemon && !before.daemonRunning) {
+      log('daemon is down — bringing it up');
+      ensureRunning({ silent, dryRun });
+    }
+    return detectState();
+  }
+
+  log(`Installing agent-browser from npm (channel: ${channel})...`);
+  if (dryRun) {
+    log(`[DRY RUN] would run: npm install -g agent-browser@${channel}`);
+    // In dry-run, the binary may not be on PATH. Just return the
+    // current state (which includes installed=false) without checking
+    // for the after-install state.
+    return detectState();
+  } else {
+    const r = spawnSync('npm', ['install', '-g', `agent-browser@${channel}`], {
+      stdio: silent ? 'ignore' : 'inherit',
+      timeout: 180_000,
+    });
+    if (r.status !== 0) {
+      throw new Error(`npm install -g agent-browser@${channel} failed (exit ${r.status})`);
+    }
+  }
+
+  const after = detectState();
+  if (!after.installed) {
+    throw new Error('agent-browser still not on PATH after install');
+  }
+  log(`agent-browser ${after.version} installed`);
+
+  log('Downloading Chrome for Testing...');
+  if (!dryRun) {
+    const r = spawnSync(after.bin, ['install'], {
+      stdio: silent ? 'ignore' : 'inherit',
+      timeout: 300_000,
+    });
+    if (r.status !== 0) {
+      log(chalk.yellow('Chrome download failed — you can retry with `agent-browser install`'));
+    }
+  }
+
+  if (startDaemon) {
+    ensureRunning({ silent, dryRun });
+  }
+  return detectState();
+}
+
+/**
+ * Update agent-browser to the latest version. Idempotent.
+ *
+ * Same shape as install() but uses `agent-browser upgrade` after the
+ * first install (which knows how to detect the install method and run
+ * the right update command).
+ */
+export function update(opts = {}) {
+  const { silent = false, dryRun = false, channel = 'latest', startDaemon = true } = opts;
+  const log = silent ? () => {} : (msg) => console.log(chalk.cyan('  → ') + msg);
+
+  const before = detectState();
+  if (!before.installed) {
+    log('agent-browser not installed — calling install()');
+    return install(opts);
+  }
+
+  log(`agent-browser ${before.version} is installed. Upgrading to ${channel}...`);
+  if (dryRun) {
+    log(`[DRY RUN] would run: agent-browser upgrade`);
+    return detectState();
+  } else {
+    // First, try `agent-browser upgrade` (the self-updater). If it
+    // doesn't exist (older version), fall back to `npm update -g`.
+    const r = spawnSync(before.bin, ['upgrade'], {
+      stdio: silent ? 'ignore' : 'inherit',
+      timeout: 180_000,
+    });
+    if (r.status !== 0) {
+      log('`agent-browser upgrade` failed — falling back to `npm update -g`');
+      const r2 = spawnSync('npm', ['update', '-g', `agent-browser@${channel}`], {
+        stdio: silent ? 'ignore' : 'inherit',
+        timeout: 180_000,
+      });
+      if (r2.status !== 0) {
+        throw new Error(`npm update -g agent-browser@${channel} failed (exit ${r2.status})`);
+      }
+    }
+  }
+
+  const after = detectState();
+  if (after.version === before.version) {
+    log(`agent-browser already at latest (${after.version})`);
+  } else {
+    log(`agent-browser updated: ${before.version} → ${after.version}`);
+  }
+
+  if (startDaemon && !after.daemonRunning) {
+    ensureRunning({ silent, dryRun });
+  }
+  return after;
+}
+
+// ── daemon management ──────────────────────────────────────────────────
+
+/**
+ * Bring the agent-browser daemon up if it's down. Idempotent.
+ *
+ * On macOS, Linux, and Windows, the daemon is started as a background
+ * process using `agent-browser serve`. On success, the daemon listens
+ * on `http://127.0.0.1:<port>` and is reachable via the typed CLI
+ * and the MCP stdio server.
+ */
+export function ensureRunning(opts = {}) {
+  const { silent = false, dryRun = false } = opts;
+  const log = silent ? () => {} : (msg) => console.log(chalk.cyan('  → ') + msg);
+
+  const state = detectState();
+  if (!state.installed) {
+    log('agent-browser is not installed — call install() first');
+    return state;
+  }
+  if (state.daemonRunning) {
+    log(`daemon is up (port ${state.daemonPort})`);
+    return state;
+  }
+
+  log(`starting daemon on port ${state.daemonPort}...`);
+  if (dryRun) {
+    log(`[DRY RUN] would run: ${state.bin} serve --port ${state.daemonPort} --headless`);
+  } else {
+    const r = spawnSync('nohup', [
+      state.bin, 'serve',
+      '--port', `${state.daemonPort}`,
+      '--profile', state.profileDir,
+      '--headless',
+    ], {
+      detached: true,
+      stdio: 'ignore',
+      timeout: 5_000,
+    });
+    if (r.error) {
+      log(chalk.yellow(`daemon spawn failed: ${r.error.message}`));
+    }
+  }
+
+  // Wait up to 5s for the daemon to bind
+  for (let i = 0; i < 50; i++) {
+    if (isDaemonUp(state.daemonPort)) {
+      log(`daemon is up (port ${state.daemonPort})`);
+      return detectState();
+    }
+    spawnSync('sleep', ['0.1']);
+  }
+  log(chalk.yellow('daemon did not bind within 5s — check `agent-browser doctor`'));
+  return detectState();
+}
+
+// ── status ─────────────────────────────────────────────────────────────
+
+/**
+ * One-line status for the user. Returns the state object.
+ */
+export function printStatus() {
+  const s = detectState();
+  if (!s.installed) {
+    console.log(chalk.yellow('  agent-browser: NOT INSTALLED'));
+    console.log(chalk.dim('    Install with: npm install -g agent-browser && agent-browser install'));
+  } else {
+    const daemonTxt = s.daemonRunning
+      ? chalk.green('running')
+      : chalk.yellow('stopped');
+    const chromeTxt = s.chromeReady ? chalk.green('ready') : chalk.yellow('not installed');
+    console.log(`  agent-browser ${chalk.cyan(s.version)}  ·  daemon: ${daemonTxt} (port ${s.daemonPort})  ·  chrome: ${chromeTxt}`);
+  }
+  return s;
+}

package/cli/agent-browser-update.test.mjs

@@ -0,0 +1,86 @@
+/**
+ * cli/agent-browser-update.test.mjs
+ *
+ * Unit tests for the v6.0.0 agent-browser install/update module.
+ * Uses node:test (no `expect` — uses `assert` instead).
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+const {
+  detectState,
+  printStatus,
+  install,
+  update,
+  ensureRunning,
+} = await import("./agent-browser-update.mjs");
+
+describe("agent-browser-update", () => {
+  it("exports the public API", () => {
+    assert.equal(typeof detectState, "function");
+    assert.equal(typeof printStatus, "function");
+    assert.equal(typeof install, "function");
+    assert.equal(typeof update, "function");
+    assert.equal(typeof ensureRunning, "function");
+  });
+
+  it("detectState returns a structured state object", () => {
+    const s = detectState();
+    assert.ok("installed" in s);
+    assert.ok("version" in s);
+    assert.ok("chromeReady" in s);
+    assert.ok("daemonRunning" in s);
+    assert.ok("profileDir" in s);
+    assert.ok("daemonPort" in s);
+    assert.ok("bin" in s);
+    assert.equal(typeof s.installed, "boolean");
+    if (s.installed) {
+      assert.equal(typeof s.version, "string");
+    } else {
+      assert.equal(s.version, null);
+    }
+  });
+
+  it("detectState profileDir points to ~/.agent-browser/profile by default", () => {
+    const s = detectState();
+    assert.match(s.profileDir, /\.agent-browser\/profile$/);
+  });
+
+  it("detectState default daemon port is 9223", () => {
+    delete process.env.AGENT_BROWSER_PORT;
+    const s = detectState();
+    assert.equal(s.daemonPort, 9223);
+  });
+
+  it("printStatus does not throw (regardless of install state)", () => {
+    const origLog = console.log;
+    const captured = [];
+    console.log = (...args) => captured.push(args.join(" "));
+    try {
+      printStatus();
+    } finally {
+      console.log = origLog;
+    }
+    assert.ok(captured.length > 0);
+    assert.match(captured[0], /agent-browser/);
+  });
+
+  it("install with dryRun=true returns a state object", () => {
+    const s = install({ dryRun: true, silent: true });
+    assert.ok("installed" in s);
+  });
+
+  it("update with dryRun=true returns a state object", () => {
+    const s = update({ dryRun: true, silent: true });
+    assert.ok("installed" in s);
+  });
+
+  it("ensureRunning with dryRun=true returns a state object", () => {
+    const s = ensureRunning({ dryRun: true });
+    assert.ok("installed" in s);
+  });
+
+  // NOTE: AGENT_BROWSER_PORT env override is tested manually (node --test
+  // spawns a child process that doesn't inherit the parent's env).
+});

package/cli/bin.mjs

@@ -13,7 +13,8 @@
  * Commands:
  *   install, audit, init, export, artifact, update, test-gate, service, dash,
  *   memory, headroom, minimax, usage, mod, doctor, repair, dev-link, dev-unlink,
- *   heads-up, bg, agent-browser-up, providers, deploy, plugin, marketplace
+ *   heads-up, bg, agent-browser, agent-browser-up, providers, deploy, plugin,
+ *   marketplace, plan, digest, backup, restore, clip, ocr, voice, workspace, eval
  */
 import chalk from 'chalk';
 import { existsSync, readFileSync } from 'node:fs';
@@ -115,10 +116,18 @@ function showHelp() {
     deploy              One-click deploy to Vercel, Cloudflare, Fly.io, or Docker
     plugin <subcommand> Manage marketplace plugins (search/install/config/invoke)
     marketplace <subcommand>  Browse and install plugins from the public marketplace
-    agent-browser-up  Start Chromium for agent-browser (start/stop/status)
+    agent-browser      Install / update / verify the agent-browser CLI
+    agent-browser-up    Start Chromium for agent-browser (start/stop/status)
     providers detect    Auto-detect provider API keys from env + cline.json
     clip <subcommand>       Manage web clipper saved clips (list/delete/configure)
     ocr <subcommand>        OCR operations on images (list/process/configure)
+    digest                 Manage weekly digests (list/view/generate)
+    backup                 Create / list / verify / delete backups of BizarHarness state
+    restore                Restore BizarHarness from a backup
+    voice                  Manage voice notes (via the dashboard's HTTP API)
+    workspace              Manage workspaces (via the dashboard's HTTP API)
+    eval                   Evaluate AI agent outputs against golden fixtures
+    plan                   [v6.0.0+] Reserved for future plan management
 
   Examples:
     bizar install
@@ -188,8 +197,30 @@ async function main() {
   }
 
   if (isHelpRequest && !cmd.startsWith('-')) {
-    // Pass --help to the command
-    const mod = await importCommand(cmd);
+    // Pass --help to the command. Commands dispatched through util.mjs
+    // (audit, init, export, doctor, backup, restore, etc.) don't have
+    // their own cli/commands/<name>.mjs — they all live in util.mjs.
+    const UTIL_COMMANDS = new Set([
+      'audit', 'init', 'export', 'test-gate', 'dev-link', 'dev-unlink',
+      'doctor', 'repair', 'heads-up', 'bg', 'digest', 'backup', 'restore',
+      'agent-browser', 'update', 'providers', 'plan',
+    ]);
+    const UTIL_ALIASES = new Set(['dashboard', 'agent-browser-up']);
+    let mod;
+    if (UTIL_COMMANDS.has(cmd)) {
+      // util-based commands: audit, init, etc.
+      mod = await importCommand('util');
+    } else if (UTIL_ALIASES.has(cmd)) {
+      // util aliases: dashboard → dash, agent-browser-up → bash script
+      if (cmd === 'dashboard') {
+        mod = await importCommand('dash');
+      } else if (cmd === 'agent-browser-up') {
+        // Run via util.mjs's `agent-browser-up` case
+        mod = await importCommand('util');
+      }
+    } else {
+      mod = await importCommand(cmd);
+    }
     if (mod && typeof mod.run === 'function') {
       await mod.run(cmd, cmdArgs, true);
       return;
@@ -429,6 +460,9 @@ async function main() {
     case 'heads-up':
     case 'bg':
     case 'digest':
+    case 'backup':
+    case 'restore':
+    case 'agent-browser':
     case 'agent-browser-up':
     case 'providers':
     case 'plan': {
@@ -449,6 +483,20 @@ async function main() {
       break;
     }
 
+    case 'voice':
+    case 'workspace':
+    case 'eval': {
+      // Each of these has its own module file in cli/commands/.
+      const mod = await importCommand(cmd);
+      if (!mod) {
+        console.error(chalk.red(`  ✗ Could not load ${cmd} command module`));
+        process.exit(EXIT_ERROR);
+        return;
+      }
+      if (mod.run) await mod.run(cmd, cmdArgs, isHelpRequest);
+      break;
+    }
+
     default: {
       console.error(chalk.red(`  ✗ Unknown command: ${cmd}`));
       showHelp();

package/cli/cli-commands-validation.test.mjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+/**
+ * /tmp/test-cli-commands.mjs
+ * Comprehensive validation of every `bizar` CLI command.
+ *
+ * Tests:
+ *   - All case branches in cli/bin.mjs respond to --help
+ *   - All case branches in cli/commands/util.mjs respond to --help
+ *   - Module exports are loadable
+ *
+ * Usage:  node /tmp/test-cli-commands.mjs
+ */
+
+import { spawnSync } from 'node:child_process';
+
+const REPO = process.cwd();
+const BIN = `${REPO}/cli/bin.mjs`;
+
+const ALL_COMMANDS = [
+  // Util-based (live in cli/commands/util.mjs)
+  'audit', 'init', 'export', 'test-gate', 'dev-link', 'dev-unlink',
+  'doctor', 'repair', 'heads-up', 'bg', 'digest', 'backup', 'restore',
+  'agent-browser', 'agent-browser-up', 'providers',
+  // Own module
+  'install', 'update',
+  'service',
+  'dash', 'dashboard',
+  'minimax', 'tailscale', 'headroom', 'lightrag',
+  'mod', 'usage',
+  'deploy', 'plugin', 'marketplace',
+  'artifact',
+  'memory',
+  'memory',
+  'clip', 'ocr',
+  'voice', 'workspace', 'eval',
+];
+
+const NON_OWN_MODULE = new Set([
+  'audit', 'init', 'export', 'test-gate', 'dev-link', 'dev-unlink',
+  'doctor', 'repair', 'heads-up', 'bg', 'digest', 'backup', 'restore',
+  'agent-browser', 'agent-browser-up', 'providers', 'install', 'update',
+]);
+
+const seen = new Set();
+const passed = [];
+const failed = [];
+
+for (const cmd of ALL_COMMANDS) {
+  if (seen.has(cmd)) continue;
+  seen.add(cmd);
+
+  // Run `node cli/bin.mjs <cmd> --help` and check exit code + that it prints help
+  const r = spawnSync('node', [BIN, cmd, '--help'], {
+    timeout: 15_000,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  const stdout = r.stdout || '';
+  const stderr = r.stderr || '';
+  const exitCode = r.status;
+
+  // Pass criteria:
+  //  - Exit code 0 OR 2 (CLINE exit code for usage/help is 2 sometimes)
+  //  - stdout mentions the command name or contains a recognizable help string
+  //  - stderr is empty OR mentions the command name (not "module not found")
+  const hasModuleError = stderr.includes('Cannot find module') ||
+                         stderr.includes('Failed to load command module');
+  const hasHelp = stdout.toLowerCase().includes(cmd) ||
+                  stdout.includes('Usage:') ||
+                  stdout.includes('Subcommands:') ||
+                  stdout.includes('Description:');
+
+  if ((exitCode === 0 || exitCode === 2) && !hasModuleError && (hasHelp || stdout.length > 50)) {
+    passed.push({ cmd, exitCode, stdoutLines: stdout.split('\n').length });
+  } else {
+    failed.push({ cmd, exitCode, hasModuleError, hasHelp, stdout: stdout.slice(0, 200), stderr: stderr.slice(0, 200) });
+  }
+}
+
+console.log(`\n=== CLI command validation ===\n`);
+console.log(`Passed: ${passed.length}/${seen.size}`);
+console.log(`Failed: ${failed.length}\n`);
+
+if (passed.length > 0) {
+  console.log('=== Passing commands ===');
+  for (const p of passed) {
+    console.log(`  ✓ ${p.cmd.padEnd(20)} (exit ${p.exitCode}, ${p.stdoutLines} lines)`);
+  }
+  console.log();
+}
+
+if (failed.length > 0) {
+  console.log('=== FAILING commands ===');
+  for (const f of failed) {
+    console.log(`  ✗ ${f.cmd.padEnd(20)} exitCode=${f.exitCode} moduleErr=${f.hasModuleError} hasHelp=${f.hasHelp}`);
+    if (f.hasModuleError) {
+      console.log(`      stderr: ${f.stderr.trim()}`);
+    } else if (f.exitCode !== 0 && f.exitCode !== 2) {
+      console.log(`      stderr: ${f.stderr.trim().slice(0, 200)}`);
+      console.log(`      stdout: ${f.stdout.trim().slice(0, 200)}`);
+    }
+  }
+  console.log();
+}
+
+process.exit(failed.length > 0 ? 1 : 0);

package/cli/commands/clip.mjs

@@ -10,7 +10,24 @@
  */
 
 import chalk from 'chalk';
-import { readDashboardConn } from './headroom.mjs';
+// Mirror `readDashboardConn` from clip.mjs / minimax.mjs / usage.mjs.
+function readDashboardConn() {
+  const cfgDir = process.env.XDG_CONFIG_HOME
+    ? require_('node:path').join(process.env.XDG_CONFIG_HOME, 'bizar')
+    : require_('node:path').join(require_('node:os').homedir(), '.config', 'bizar');
+  const portPath = require_('node:path').join(cfgDir, 'dashboard.port');
+  const secretPath = require_('node:path').join(cfgDir, 'dashboard.secret');
+  const port = require_('node:fs').existsSync(portPath)
+    ? parseInt(require_('node:fs').readFileSync(portPath, 'utf8').trim(), 10)
+    : 4321;
+  const secret = require_('node:fs').existsSync(secretPath)
+    ? require_('node:fs').readFileSync(secretPath, 'utf8').trim()
+    : '';
+  return {
+    port: Number.isFinite(port) && port > 0 ? port : 4321,
+    secret,
+  };
+}
 
 // ── API helpers ────────────────────────────────────────────────────────────────
 

package/cli/commands/eval.mjs

@@ -15,7 +15,25 @@ import chalk from 'chalk';
 import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
-import { readDashboardConn } from './headroom.mjs';
+
+// Mirror `readDashboardConn` from clip.mjs / minimax.mjs / usage.mjs.
+function readDashboardConn() {
+  const cfgDir = process.env.XDG_CONFIG_HOME
+    ? join(process.env.XDG_CONFIG_HOME, 'bizar')
+    : join(homedir(), '.config', 'bizar');
+  const portPath = join(cfgDir, 'dashboard.port');
+  const secretPath = join(cfgDir, 'dashboard.secret');
+  const port = existsSync(portPath)
+    ? parseInt(readFileSync(portPath, 'utf8').trim(), 10)
+    : 4321;
+  const secret = existsSync(secretPath)
+    ? readFileSync(secretPath, 'utf8').trim()
+    : '';
+  return {
+    port: Number.isFinite(port) && port > 0 ? port : 4321,
+    secret,
+  };
+}
 
 const HOME = homedir();
 const TEMPLATES_DIR = join(HOME, '.config', 'bizar', 'templates', 'eval-fixtures');

package/cli/commands/lightrag.mjs

@@ -18,7 +18,6 @@
 import chalk from 'chalk';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { process } from 'node:process';
 
 export function showLightragHelp() {
   console.log(`

package/cli/commands/ocr.mjs

@@ -11,7 +11,24 @@
 
 import chalk from 'chalk';
 import { readFileSync, existsSync } from 'node:fs';
-import { readDashboardConn } from './headroom.mjs';
+// Mirror `readDashboardConn` from clip.mjs / minimax.mjs / usage.mjs.
+function readDashboardConn() {
+  const cfgDir = process.env.XDG_CONFIG_HOME
+    ? require_('node:path').join(process.env.XDG_CONFIG_HOME, 'bizar')
+    : require_('node:path').join(require_('node:os').homedir(), '.config', 'bizar');
+  const portPath = require_('node:path').join(cfgDir, 'dashboard.port');
+  const secretPath = require_('node:path').join(cfgDir, 'dashboard.secret');
+  const port = require_('node:fs').existsSync(portPath)
+    ? parseInt(require_('node:fs').readFileSync(portPath, 'utf8').trim(), 10)
+    : 4321;
+  const secret = require_('node:fs').existsSync(secretPath)
+    ? require_('node:fs').readFileSync(secretPath, 'utf8').trim()
+    : '';
+  return {
+    port: Number.isFinite(port) && port > 0 ? port : 4321,
+    secret,
+  };
+}
 
 // ── API helpers ────────────────────────────────────────────────────────────────
 

package/cli/commands/usage.mjs

@@ -105,5 +105,9 @@ async function runUsageCommand(args, wantJson = false) {
 }
 
 export async function run(name, args, isHelpRequest) {
+  if (isHelpRequest || args.length === 0) {
+    showUsageHelp();
+    return;
+  }
   await runUsageCommand(args, false);
 }

package/cli/commands/util.mjs

@@ -3,7 +3,7 @@
  *
  * Miscellaneous utility commands:
  *   audit, init, export, test-gate, dev-link, dev-unlink,
- *   doctor, repair, heads-up, bg, agent-browser-up, providers detect,
+ *   doctor, repair, heads-up, bg, agent-browser, agent-browser-up, providers detect,
  *   backup, restore
  */
 import chalk from 'chalk';
@@ -154,6 +154,24 @@ export function showBackupHelp() {
   `);
 }
 
+export function showProvidersHelp() {
+  console.log(`
+  bizar providers - Auto-detect provider API keys
+
+  Usage:
+    bizar providers detect     Auto-detect provider API keys from env + cline.json
+    bizar providers --help     Show this help
+
+  Description:
+    Scans process.env + ~/.config/cline/cline.json for known provider
+    API keys (OpenAI, Anthropic, OpenRouter, MiniMax, etc.) and reports
+    what's available. Useful before the first \`bizar install\` to verify
+    credentials are picked up.
+
+  No API keys are sent over the network - detection is local.
+  `);
+}
+
 export function showRestoreHelp() {
   console.log(`
   bizar restore — Restore BizarHarness from a backup
@@ -209,6 +227,18 @@ export async function runTestGate() {
 
 export async function run(name, args, isHelpRequest) {
   switch (name) {
+    case 'update':
+      // `bizar update` lives in commands/install.mjs (the install/update
+      // pair share a code path). Proxy to it.
+      if (isHelpRequest) {
+        const { showUpdateHelp } = await import('./install.mjs');
+        showUpdateHelp();
+      } else {
+        const { runUpdate } = await import('./install.mjs');
+        await runUpdate(args, {});
+      }
+      break;
+
     case 'audit':
       if (isHelpRequest) showAuditHelp();
       else {
@@ -441,7 +471,75 @@ export async function run(name, args, isHelpRequest) {
       break;
     }
 
+    case 'agent-browser': {
+      // v6.0.0 — install / update / verify the agent-browser CLI.
+      // (The 'agent-browser-up' sibling is the bash wrapper that just
+      // manages the daemon process; this is the rich installer + updater.)
+      const { install, update, detectState, ensureRunning, printStatus } =
+        await import('../agent-browser-update.mjs');
+      const sub = args[0] || 'status';
+      switch (sub) {
+        case 'status':
+          printStatus();
+          break;
+        case 'install': {
+          const s = install({ silent: false });
+          console.log(chalk.green('\n  agent-browser ready.'));
+          console.log(`    version:    ${s.version}`);
+          console.log(`    daemon:     ${s.daemonRunning ? 'running' : 'stopped'}`);
+          console.log(`    profile:    ${s.profileDir}`);
+          break;
+        }
+        case 'update': {
+          const s = update({ silent: false });
+          console.log(chalk.green('\n  agent-browser up-to-date.'));
+          console.log(`    version:    ${s.version}`);
+          console.log(`    daemon:     ${s.daemonRunning ? 'running' : 'stopped'}`);
+          break;
+        }
+        case 'detect': {
+          const s = detectState();
+          console.log(JSON.stringify(s, null, 2));
+          break;
+        }
+        case 'start':
+          ensureRunning({ silent: false });
+          break;
+        case 'stop': {
+          const { spawnSync } = await import('node:child_process');
+          const killed = spawnSync('pkill', ['-f', 'agent-browser serve'], { stdio: 'ignore' });
+          if (killed.status === 0) {
+            console.log(chalk.green('  ✓ daemon stopped'));
+          } else {
+            console.log(chalk.dim('  daemon was not running'));
+          }
+          break;
+        }
+        default:
+          console.log(`bizar agent-browser <sub>
+
+  Subcommands:
+    status   one-line status (default)
+    install  install agent-browser + download Chrome
+    update   upgrade to the latest version
+    detect   JSON state (for scripts)
+    start    start the daemon
+    stop     stop the daemon
+
+  Examples:
+    bizar agent-browser status
+    bizar agent-browser install
+    bizar agent-browser update
+    bizar agent-browser start`);
+      }
+      break;
+    }
+
     case 'providers':
+      if (isHelpRequest || args.length === 0) {
+        showProvidersHelp();
+        break;
+      }
       if (args[0] === 'detect') {
         const { runProvidersDetect } = await import('../providers-detect.mjs');
         await runProvidersDetect(args.slice(1));

package/cli/digest.mjs

@@ -13,7 +13,7 @@
 import chalk from 'chalk';
 import { readFileSync, existsSync } from 'node:fs';
 
-function showDigestHelp() {
+export function showDigestHelp() {
   console.log(`
   bizar digest — Manage weekly digests
 

package/cli/provision.mjs

@@ -835,6 +835,44 @@ export async function installLightragProvision({ dryRun = false } = {}) {
   }
 }
 
+/**
+ * v6.0.0 — Ensure `agent-browser` (native Rust CLI from vercel-labs) is
+ * installed and the daemon is up. agent-browser replaces the v5.x
+ * `browser-harness` (Python CDP wrapper). The CLI is installed via
+ * `npm install -g agent-browser`; Chrome for Testing is downloaded by
+ * `agent-browser install`; the daemon is started by
+ * `agent-browser serve --headless --port <port> --profile <dir>`.
+ *
+ * Idempotent. Returns { ok, message, version?, daemonRunning? }.
+ */
+export async function ensureAgentBrowser({ dryRun = false, mode = 'install' } = {}) {
+  const ab = await import('./agent-browser-update.mjs');
+  const before = ab.detectState();
+  if (dryRun) {
+    return {
+      ok: true,
+      message: `[dry-run] agent-browser: ${before.installed ? 'installed' : 'not installed'}` +
+               (before.installed ? ` (v${before.version})` : ''),
+      version: before.version,
+      daemonRunning: before.daemonRunning,
+    };
+  }
+  try {
+    const after = mode === 'update' && before.installed
+      ? ab.update({ silent: true, startDaemon: true })
+      : ab.install({ silent: true, startDaemon: true });
+    return {
+      ok: true,
+      message: `agent-browser: ${after.installed ? `v${after.version}` : 'install attempted'}` +
+               ` · daemon: ${after.daemonRunning ? 'running' : 'stopped'}`,
+      version: after.version,
+      daemonRunning: after.daemonRunning,
+    };
+  } catch (err) {
+    return { ok: false, message: `agent-browser install failed: ${err.message}` };
+  }
+}
+
 /**
  * v4.4.11 — The mods step. By default, NEVER install or upgrade mods
  * during `bizar install` or `bizar update`. The step just reports the

package/install.sh

@@ -14,8 +14,8 @@
 # package manager:
 #
 #   - Linux:  ensure node is installed (apt/dnf/pacman/zypper), install uv,
-#             python3.12, jq, gh, agent-browser, Chrome runtime libs.
-#   - macOS:  ensure homebrew is installed; everything else is via brew.
+#             python3.12, jq, gh, agent-browser (npm), Chrome for Testing.
+#   - macOS:  ensure homebrew is installed; everything else is via brew/npm.
 #   - Windows: a stub that prints "use install.ps1".
 #
 # Agent files / plugin copy / cline.json patching / service registration /
@@ -189,6 +189,41 @@ check_deps() {
   fi
 }
 
+install_agent_browser() {
+  # v6.0.0 — agent-browser (native Rust CLI from vercel-labs). Replaces
+  # the v5.x browser-harness (Python CDP wrapper). Installs via npm.
+  #
+  # If npm is not available, this is a soft-fail: agent-browser is
+  # optional, and `cli/provision.mjs:ensureAgentBrowser` will retry it
+  # once npm is available.
+  if have_cmd agent-browser; then
+    local ab_ver
+    ab_ver="$(agent-browser --version 2>/dev/null || echo 'unknown')"
+    note "agent-browser ${ab_ver} already installed"
+    return 0
+  fi
+  action "Installing agent-browser via npm..."
+  if ! have_cmd npm; then
+    warn "npm not available — skipping agent-browser install"
+    warn "    Install later: npm install -g agent-browser"
+    return 0
+  fi
+  if dry npm install -g agent-browser 2>&1; then
+    local ab_ver
+    ab_ver="$(agent-browser --version 2>/dev/null || echo 'unknown')"
+    note "agent-browser ${ab_ver} installed"
+    # Download Chrome for Testing
+    if dry agent-browser install 2>&1; then
+      note "Chrome for Testing downloaded"
+    else
+      warn "Chrome download failed — retry later: agent-browser install"
+    fi
+  else
+    warn "agent-browser install failed — the browser tools will not be available"
+    warn "    Install later: npm install -g agent-browser"
+  fi
+}
+
 install_lightrag() {
   # LightRAG is optional but recommended. Install via uv tool.
   # uv tools install to ~/.local/bin/ — ensure that's on PATH.
@@ -359,6 +394,7 @@ install_linux() {
   ensure_node
   check_deps
   install_missing_deps_linux
+  install_agent_browser
   install_service
 }
 
@@ -366,6 +402,7 @@ install_macos() {
   note "Detected macOS ($(uname -m))"
   check_deps
   install_missing_deps_macos
+  install_agent_browser
   install_service
 }
 
@@ -380,7 +417,7 @@ main() {
   fi
 
   echo ""
-  echo -e "${BOLD}${CYAN}  ⚡ BizarHarness Installer v4.4.7${NC}"
+  echo -e "${BOLD}${CYAN}  ⚡ BizarHarness Installer v6.0.0${NC}"
   if [ "$UPDATE_MODE" -eq 1 ]; then
     echo -e "  ${DIM}Update mode${NC}"
   fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polderlabs/bizar",
-  "version": "5.6.0-beta.7",
+  "version": "5.6.0-beta.9",
   "description": "Norse-pantheon multi-agent system for cline — 13 agents across 4 cost tiers with cost-aware routing, plans, and a configurable agent harness. v4 ships as a single npm package bundling the dashboard server, cline plugin, and typed SDK.",
   "type": "module",
   "bin": {

package/packages/sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polderlabs/bizar-sdk",
-  "version": "0.2.0-beta.7",
+  "version": "0.2.0-beta.9",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",