unbound-cli 1.16.19 → 1.16.20

package/README.md

@@ -32,7 +32,7 @@ unbound setup cursor
 
 ## Onboarding (one command)
 
-For new users, the fastest path from install to a fully-configured device is the `onboard` command. It logs you in, installs the default tool bundle (Cursor, Claude Code hooks, Codex hooks), and runs device discovery — all in one step.
+For new users, the fastest path from install to a fully-configured device is the `onboard` command. It logs you in, installs the default tool bundle (Cursor, Claude Code hooks, Codex hooks), and runs device discovery — all in one step. Pi Coding Agent is also set up, after the bundle, when pi is already installed on the device, and is skipped otherwise (`unbound setup pi` sets it up regardless). A failed Pi setup does not stop discovery.
 
 ```bash
 # End user

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unbound-cli",
-  "version": "1.16.19",
+  "version": "1.16.20",
   "description": "CLI tool for Unbound - AI Gateway management",
   "main": "src/index.js",
   "bin": {

package/src/commands/onboard.js

@@ -3,8 +3,9 @@ const config = require('../config');
 const output = require('../output');
 const telemetry = require('../telemetry');
 const { ensureLoggedIn, fetchDeviceOwnerKey } = require('../auth');
-const { runSetupAllBundle, runMdmSetupAllBundle, hasRootPrivileges, elevated, scopeNotice, ALL_TOOLS, MDM_ALL_TOOLS } = require('./setup');
+const { runSetupAllBundle, runMdmSetupAllBundle, hasRootPrivileges, elevated, scopeNotice, ALL_TOOLS, MDM_ALL_TOOLS, SETUP_TOOL_MAP, MDM_TOOLS } = require('./setup');
 const { runDiscoveryScan } = require('./discover');
+const toolDetect = require('../toolDetect');
 
 /**
  * Builds the recovery-command suffix for partial-failure hints.
@@ -17,6 +18,34 @@ function domainHintSuffix(domain) {
   return ` --domain ${domain}`;
 }
 
+/**
+ * Whether onboarding should also set up Pi: only when pi is present on the
+ * device. Pi is the one tool onboarding installs only where it is already in
+ * use. A check that could not be completed counts as detected, so a device is
+ * never left ungoverned because the check itself broke.
+ */
+function shouldSetUpPi(label, { allUsers }) {
+  let detected;
+  try {
+    detected = toolDetect.detectInstalledTools(['pi'], { allUsers }).detected.includes('pi');
+  } catch (err) {
+    telemetry.captureError(err, { tags: { flow: 'onboard-detect' } });
+    output.warn(`Could not check whether ${label} is installed — setting it up anyway.`);
+    return true;
+  }
+  if (!detected) {
+    console.log(output.colors.dim(`  ${label} not detected — skipped (run \`unbound setup pi\` to set it up regardless)`));
+    return false;
+  }
+  output.info(`${label} detected — setting it up after the bundle`);
+  return true;
+}
+
+/** The command that retries a failed Pi setup in this scope. */
+function piRetryCommand(isMdm) {
+  return isMdm ? elevated('unbound setup --api-key <ADMIN_KEY> pi') : 'unbound setup pi';
+}
+
 function register(program) {
   const onboard = program
     .command('onboard')
@@ -39,6 +68,8 @@ Runs the full onboarding flow, auto-detecting scope from your privileges:
   With sudo, installs the MDM tool bundle (${MDM_ALL_TOOLS.join(', ')}) and scans
   every user on the device. Without sudo, installs the user bundle
   (${ALL_TOOLS.join(', ')}) and scans just the current user.
+  Pi Coding Agent (pi) is also set up, after the bundle, only when pi is detected
+  on the device; use \`unbound setup pi\` to set it up regardless.
 
   1. Logs in / resolves the API key (or reuses a stored \`unbound login\` key
      when --api-key is omitted).
@@ -82,6 +113,7 @@ Examples:
       let discoverySucceeded = false;
       let discoveryDomain;
       let skippedTools;
+      let piFailed = false;
       let mdmScanKey;  // device-owner key resolved from the serial (MDM scope only)
       try {
         // Persist URLs first, then login, then setup — order matters so the
@@ -120,6 +152,7 @@ Examples:
 
           console.log('');
           output.info('Step 1/2: Installing MDM tool bundle (all users)');
+          const setUpPi = shouldSetUpPi(MDM_TOOLS.pi.label, { allUsers: true });
           const { ok, skipped } = await runMdmSetupAllBundle(adminApiKey, {
             backendUrl, frontendUrl, gatewayUrl, backfill: !!opts.backfill,
           });
@@ -128,6 +161,14 @@ Examples:
           // non-zero exit explicit here so onboard never returns 0 on failure.
           if (!ok) { process.exitCode = 1; return; }
           setupSucceeded = true;
+          // Pi runs on its own so a failure there cannot cost the device its
+          // bundle, its discovery scan or its scheduled run.
+          if (setUpPi) {
+            const pi = await runMdmSetupAllBundle(adminApiKey, {
+              backendUrl, frontendUrl, gatewayUrl, tools: ['pi'],
+            });
+            piFailed = !pi.ok;
+          }
 
           console.log('');
           output.info('Step 2/2: Running device discovery');
@@ -145,6 +186,7 @@ Examples:
 
           console.log('');
           output.info('Step 1/2: Installing tool bundle');
+          const setUpPi = shouldSetUpPi(SETUP_TOOL_MAP.pi.label, { allUsers: false });
           const { ok, skipped } = await runSetupAllBundle(apiKey, {
             backendUrl, frontendUrl, gatewayUrl, backfill: !!opts.backfill,
           });
@@ -153,6 +195,14 @@ Examples:
           // non-zero exit explicit here so onboard never returns 0 on failure.
           if (!ok) { process.exitCode = 1; return; }
           setupSucceeded = true;
+          // Pi runs on its own so a failure there cannot cost the device its
+          // bundle, its discovery scan or its scheduled run.
+          if (setUpPi) {
+            const pi = await runSetupAllBundle(apiKey, {
+              backendUrl, frontendUrl, gatewayUrl, tools: ['pi'],
+            });
+            piFailed = !pi.ok;
+          }
 
           console.log('');
           output.info('Step 2/2: Running device discovery');
@@ -195,6 +245,12 @@ Examples:
         }
 
         console.log('');
+        if (piFailed) {
+          // Everything else is done, but a failed setup must NOT report onboarding success.
+          output.error(`Onboarding finished, but ${SETUP_TOOL_MAP.pi.label} setup failed (see above). Retry it with: ${piRetryCommand(isMdm)}`);
+          process.exitCode = 1;
+          return;
+        }
         output.success(skippedTools && skippedTools.length
           ? 'Onboarding complete — tools managed by MDM were skipped (see above)'
           : 'Onboarding complete');
@@ -209,20 +265,29 @@ Examples:
           // step failed. Retry just the cron: under sudo the scheduled job is a
           // discovery-only scan, so point at `discover --set-cron`; in user
           // scope it re-runs the full onboard (the bundle reinstall is intended).
-          console.error('  Setup and discovery completed successfully — only scheduled-run setup failed.');
+          console.error(piFailed
+            ? '  The tool bundle and discovery completed — scheduled-run setup failed.'
+            : '  Setup and discovery completed successfully — only scheduled-run setup failed.');
           if (isMdm) {
             console.error(`  Re-run with: ${elevated(`unbound onboard --api-key <ADMIN_KEY> --set-cron${suffix}`)}`);
           } else {
             console.error(`  Re-run cron setup with: unbound onboard --api-key <KEY> --set-cron${suffix}`);
           }
         } else if (setupSucceeded && !discoverySucceeded) {
-          console.error('  Tool setup completed successfully — only discovery failed.');
+          console.error(piFailed
+            ? '  The tool bundle is set up — discovery failed.'
+            : '  Tool setup completed successfully — only discovery failed.');
           if (isMdm) {
             console.error(`  Re-run onboarding with: ${elevated(`unbound onboard --api-key <ADMIN_KEY>${suffix}`)}`);
           } else {
             console.error(`  Re-run discovery only with: unbound discover --api-key <KEY>${suffix}`);
           }
         }
+        // A later failure must not bury an earlier one: the hints above retry
+        // discovery or the schedule, and neither of those retries Pi.
+        if (piFailed) {
+          console.error(`  ${SETUP_TOOL_MAP.pi.label} setup also failed (see above). Retry it with: ${piRetryCommand(isMdm)}`);
+        }
         process.exitCode = 1;
       }
     }));

package/src/commands/setup.js

@@ -1289,12 +1289,13 @@ Examples:
 }
 
 /**
- * Runs the user-level default bundle (Cursor, Claude Code hooks, Codex hooks, Copilot hooks) with spinners.
+ * Runs the user-level default bundle (Cursor, Claude Code hooks, Codex hooks, Copilot hooks) with spinners,
+ * or just `tools` when the caller has narrowed it.
  * Assumes the caller has already ensured the user is logged in.
  * Returns true on success, false on failure.
  */
-async function runSetupAllBundle(apiKey, { backendUrl, frontendUrl, gatewayUrl, backfill = false } = {}) {
-  const resolvedTools = ALL_TOOLS.map(name => ({ name, ...SETUP_TOOL_MAP[name] }));
+async function runSetupAllBundle(apiKey, { backendUrl, frontendUrl, gatewayUrl, backfill = false, tools = ALL_TOOLS } = {}) {
+  const resolvedTools = tools.map(name => ({ name, ...SETUP_TOOL_MAP[name] }));
   if (backfill) {
     for (const tool of resolvedTools) {
       if (!scriptSupportsBackfill(tool.script)) noteBackfillUnsupported(tool.label, tool.script);
@@ -1315,12 +1316,13 @@ async function runSetupAllBundle(apiKey, { backendUrl, frontendUrl, gatewayUrl,
 }
 
 /**
- * Runs the MDM default bundle (Cursor, Claude Code hooks, Gemini CLI, Codex hooks, Copilot hooks) with spinners.
+ * Runs the MDM default bundle (Cursor, Claude Code hooks, Gemini CLI, Codex hooks, Copilot hooks) with spinners,
+ * or just `tools` when the caller has narrowed it.
  * Caller must ensure the process is running as root.
  * Returns true on success, false on failure.
  */
-async function runMdmSetupAllBundle(adminApiKey, { backendUrl, frontendUrl, gatewayUrl, backfill = false } = {}) {
-  const resolvedTools = MDM_ALL_TOOLS.map(name => ({ name, ...MDM_TOOLS[name] }));
+async function runMdmSetupAllBundle(adminApiKey, { backendUrl, frontendUrl, gatewayUrl, backfill = false, tools = MDM_ALL_TOOLS } = {}) {
+  const resolvedTools = tools.map(name => ({ name, ...MDM_TOOLS[name] }));
   if (backfill) {
     for (const tool of resolvedTools) {
       if (!scriptSupportsBackfill(tool.script)) noteBackfillUnsupported(tool.label, tool.script);

package/src/toolDetect.js

@@ -0,0 +1,239 @@
+// Detects whether an AI coding tool is actually present on this device, so
+// `unbound onboard` can set a tool up only where it is in use. Pi is the only
+// tool gated on detection today; every other tool has no signals here and is
+// always treated as installed.
+//
+// A tool counts as installed when ANY of its signals is found: its CLI binary,
+// or a file the tool writes for itself. Detection deliberately leans towards
+// "installed": a false positive only installs an unused extension, while a
+// false negative leaves a tool ungoverned. For the same reason detection
+// throws, instead of answering "not installed", when it found nothing but
+// could not inspect some place it needed to.
+//
+// The one thing a signal must never be is a path Unbound's own setup scripts
+// create (~/.pi/agent/extensions/unbound/). That would make pi look installed
+// on any device that was onboarded before, so the markers below are files only
+// pi itself writes.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const childProcess = require('child_process');
+
+// Where a per-user CLI lands, relative to a home. PATH alone is not enough:
+// under sudo and under the scheduled run it is a minimal system PATH that
+// lacks these. `.pi/agent/bin` is where pi's own installer puts its binary.
+const HOME_BIN_DIRS = [
+  '.pi/agent/bin',
+  '.local/bin',
+  '.bun/bin',
+  '.npm-global/bin',
+  '.volta/bin',
+  '.yarn/bin',
+  'AppData/Roaming/npm',
+  'AppData/Local/Microsoft/WinGet/Links',
+];
+
+const TOOL_SIGNALS = {
+  'pi': {
+    bins: ['pi'],
+    markers: ['.pi/agent/auth.json', '.pi/agent/sessions'],
+  },
+};
+
+// Directories under the users root that are not accounts. Linux has no entry:
+// a user named Shared or Guest there is a real one.
+const SKIP_HOME_NAMES = {
+  darwin: ['Shared', 'Guest'],
+  win32: ['Public', 'Default', 'Default User', 'All Users'],
+};
+
+// "Not there" and "could not look" are different answers. Only the first means
+// a signal is absent; anything else (no permission, an I/O error) is kept in
+// `errors` so the caller does not report a tool it could not rule out as
+// missing.
+const ABSENT = new Set(['ENOENT', 'ENOTDIR']);
+
+function stat(p, errors) {
+  try {
+    return fs.statSync(p);
+  } catch (err) {
+    if (!ABSENT.has(err.code)) errors.push(err);
+    return null;
+  }
+}
+
+function listDir(p, errors) {
+  try {
+    return fs.readdirSync(p);
+  } catch (err) {
+    if (!ABSENT.has(err.code)) errors.push(err);
+    return [];
+  }
+}
+
+function isLink(p) {
+  try {
+    return fs.lstatSync(p).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+function pathDirs() {
+  return (process.env.PATH || '').split(path.delimiter).filter(Boolean);
+}
+
+function machineBinDirs(platform) {
+  if (platform === 'win32') return [];
+  return ['/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/snap/bin'];
+}
+
+// Dirs the OS package manager owns, where a bare tool name may be another
+// program: Debian and Ubuntu ship a digits-of-pi calculator at /usr/bin/pi.
+function osPackageBinDirs(platform) {
+  return platform === 'win32' ? [] : ['/usr/bin', '/bin'];
+}
+
+function realDir(dir) {
+  try {
+    return fs.realpathSync(dir);
+  } catch {
+    return path.resolve(dir);
+  }
+}
+
+const HOME_PREFIXES = { darwin: '/Users/', linux: '/home/' };
+const ACCOUNT_LOOKUP_TIMEOUT_MS = 30000;
+
+// Home directories from the account database. A listing of the users root
+// alone misses a home that is not its direct child, such as /home/DOMAIN/alice.
+// The MDM setup scripts are Python and find their users with pwd.getpwall(),
+// so the same interpreter is asked the same question: detection then looks in
+// every home a setup script would install into. Windows has no such database;
+// its profile directories are the list.
+//
+// Two ways of getting no answer are told apart:
+// - Python is missing, or getpwall() itself fails. A setup script fails the
+//   same way, so it could not install into those homes either. Nothing
+//   reachable went unseen, and the users root listing is the whole answer.
+// - The lookup timed out or printed something unreadable. The database may be
+//   slow rather than down, and a setup script, which waits far longer, could
+//   still list those homes. That is kept in `errors` as a place that could
+//   not be inspected.
+function accountHomes(platform, errors) {
+  const prefix = HOME_PREFIXES[platform];
+  if (!prefix) return [];
+  const script = 'import json, pwd; print(json.dumps([e.pw_dir for e in pwd.getpwall()]))';
+  for (const python of ['python3', 'python']) {
+    let out;
+    try {
+      out = childProcess.execFileSync(python, ['-c', script], {
+        encoding: 'utf8', timeout: ACCOUNT_LOOKUP_TIMEOUT_MS, stdio: ['ignore', 'pipe', 'ignore'],
+      });
+    } catch (err) {
+      if (err.code === 'ETIMEDOUT') {
+        errors.push(err);
+        return [];
+      }
+      continue;
+    }
+    try {
+      return JSON.parse(out).filter(home => typeof home === 'string' && home.startsWith(prefix));
+    } catch (err) {
+      errors.push(err);
+      return [];
+    }
+  }
+  return [];
+}
+
+// Every real user's home, for the sudo/MDM scope where the tools belong to
+// users other than the one running the command: every home the account
+// database names, and every directory under the users root for accounts the
+// database does not enumerate.
+function allUserHomes(platform, { errors = [], root, accounts } = {}) {
+  const usersRoot = root || (platform === 'win32'
+    ? path.join(process.env.SystemDrive || 'C:', path.sep, 'Users')
+    : platform === 'darwin' ? '/Users' : '/home');
+  const skip = new Set(SKIP_HOME_NAMES[platform] || []);
+  const candidates = [
+    ...(accounts || accountHomes(platform, errors)),
+    ...listDir(usersRoot, errors).filter(name => !name.startsWith('.')).map(name => path.join(usersRoot, name)),
+  ];
+  const homes = new Set([os.homedir()]);
+  for (const home of candidates) {
+    if (skip.has(path.basename(home))) continue;
+    const found = stat(home, errors);
+    if (found && found.isDirectory()) homes.add(home);
+  }
+  return [...homes];
+}
+
+function binDirsFor(ctx) {
+  const dirs = [...ctx.pathDirs, ...ctx.machineBinDirs];
+  for (const home of ctx.homes) {
+    for (const rel of HOME_BIN_DIRS) dirs.push(path.join(home, rel));
+    // nvm keeps one bin dir per installed Node version.
+    const nvm = path.join(home, '.nvm', 'versions', 'node');
+    for (const version of listDir(nvm, ctx.errors)) dirs.push(path.join(nvm, version, 'bin'));
+  }
+  return dirs;
+}
+
+function hasBinary(name, ctx) {
+  const names = ctx.platform === 'win32'
+    ? [`${name}.exe`, `${name}.cmd`, `${name}.ps1`, name]
+    : [name];
+  return binDirsFor(ctx).some((dir) => {
+    // In a dir the OS package manager owns, a regular file with the tool's
+    // name is the OS's own program. npm links a tool in, so there only a
+    // symlink counts.
+    const linksOnly = ctx.osPackageBinDirs.has(realDir(dir));
+    return names.some((n) => {
+      const p = path.join(dir, n);
+      if (!stat(p, ctx.errors)) return false;
+      return !linksOnly || isLink(p);
+    });
+  });
+}
+
+function isInstalled(toolName, ctx) {
+  const signals = TOOL_SIGNALS[toolName];
+  // An unknown tool has no way to be ruled out, so it is treated as installed.
+  if (!signals) return true;
+  if ((signals.bins || []).some(bin => hasBinary(bin, ctx))) return true;
+  if ((signals.markers || []).some(rel => ctx.homes.some(home => stat(path.join(home, rel), ctx.errors)))) return true;
+  return false;
+}
+
+/**
+ * Splits `toolNames` into those present on this device and those that are not.
+ * `allUsers` checks every user's home (sudo/MDM scope) instead of only the
+ * current user's. The remaining options exist so tests can point detection at
+ * a fixture tree instead of the real machine.
+ *
+ * Throws when a tool was not found but some place could not be inspected, so
+ * the caller can set the tool up instead of treating it as absent.
+ */
+function detectInstalledTools(toolNames, { allUsers = false, platform = process.platform, ...overrides } = {}) {
+  const errors = [];
+  const ctx = {
+    platform,
+    errors,
+    homes: overrides.homes || (allUsers ? allUserHomes(platform, { errors }) : [os.homedir()]),
+    pathDirs: overrides.pathDirs || pathDirs(),
+    machineBinDirs: overrides.machineBinDirs || machineBinDirs(platform),
+    osPackageBinDirs: new Set((overrides.osPackageBinDirs || osPackageBinDirs(platform)).map(realDir)),
+  };
+
+  const detected = [];
+  const missing = [];
+  for (const name of toolNames) {
+    (isInstalled(name, ctx) ? detected : missing).push(name);
+  }
+  if (missing.length && errors.length) throw errors[0];
+  return { detected, missing };
+}
+
+module.exports = { detectInstalledTools, allUserHomes, accountHomes, TOOL_SIGNALS };

package/test/onboard-failure-exit.test.js

@@ -27,6 +27,9 @@ function loadOnboard({ isRoot, setupOk, reportThrows }) {
   const setupReport = require('../src/setup-report');
 
   setup.hasRootPrivileges = () => isRoot;
+  // Detection and the Pi step are covered in tool-detect.test.js; here pi is absent,
+  // so the bundle is the only setup call.
+  require('../src/toolDetect').detectInstalledTools = (names) => ({ detected: [], missing: names });
   // Mirror runBatch's real behavior: on failure it sets exitCode and (best-effort)
   // reports, then returns { ok: false }. We model both the report call and the
   // exitCode side effect so the test exercises onboard's own handling.

package/test/onboard-scope.test.js

@@ -57,6 +57,9 @@ async function runOnboard(isRoot, { setCron = false, discoveryKey = 'd', domain,
   const scheduled = require('../src/scheduled');
 
   setup.hasRootPrivileges = () => isRoot;
+  // Detection and the Pi step are covered in tool-detect.test.js; here pi is absent,
+  // so the bundle is the only setup call.
+  require('../src/toolDetect').detectInstalledTools = (names) => ({ detected: [], missing: names });
   setup.runMdmSetupAllBundle = async () => { calls.mdm++; return { ok: true, skipped: [] }; };
   setup.runSetupAllBundle = async () => { calls.user++; return { ok: true, skipped: [] }; };
   discover.runDiscoveryScan = async (o) => { calls.discovery++; calls.discoveryArgs = o; };

package/test/tool-detect.test.js

@@ -0,0 +1,438 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { Command } = require('commander');
+const childProcess = require('child_process');
+const { detectInstalledTools, allUserHomes, accountHomes, TOOL_SIGNALS } = require('../src/toolDetect');
+
+// Detection runs against a throwaway home so the result never depends on what
+// the machine running the tests has installed.
+// `links` maps a path to the path it points at, both relative to the fixture root.
+function fixture(files = [], links = {}) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'unbound-detect-'));
+  const home = path.join(root, 'home');
+  fs.mkdirSync(home, { recursive: true });
+  for (const rel of files) {
+    const p = path.join(root, rel);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, '');
+  }
+  for (const [rel, target] of Object.entries(links)) {
+    const p = path.join(root, rel);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.symlinkSync(path.join(root, target), p);
+  }
+  const opts = (extra = {}) => ({
+    platform: 'darwin',
+    homes: [home],
+    pathDirs: [path.join(root, 'path')],
+    machineBinDirs: [path.join(root, 'global-bin')],
+    osPackageBinDirs: [],
+    ...extra,
+  });
+  return { root, home, opts };
+}
+
+test('an empty device does not detect pi', () => {
+  const { opts } = fixture();
+  assert.deepEqual(detectInstalledTools(['pi'], opts()), { detected: [], missing: ['pi'] });
+});
+
+test('files pi writes for itself detect it', () => {
+  for (const marker of ['home/.pi/agent/auth.json', 'home/.pi/agent/sessions/x.jsonl']) {
+    const { opts } = fixture([marker]);
+    assert.deepEqual(detectInstalledTools(['pi'], opts()), { detected: ['pi'], missing: [] }, marker);
+  }
+});
+
+test('a pi binary detects it: per-user bin dir, nvm, PATH, machine-wide', () => {
+  for (const bin of [
+    'home/.pi/agent/bin/pi', // where pi's own installer puts it
+    'home/.local/bin/pi',
+    'home/.nvm/versions/node/v22.1.0/bin/pi',
+    'path/pi',
+    'global-bin/pi',
+  ]) {
+    const { opts } = fixture([bin]);
+    assert.deepEqual(detectInstalledTools(['pi'], opts()).detected, ['pi'], bin);
+  }
+});
+
+// Debian and Ubuntu ship a digits-of-pi calculator at /usr/bin/pi. A regular
+// file in a dir the OS package manager owns is the OS's own program.
+test('a plain file named pi in an OS package dir is not the agent', () => {
+  const { root, opts } = fixture(['usr-bin/pi']);
+  const usrBin = path.join(root, 'usr-bin');
+  for (const where of ['machineBinDirs', 'pathDirs']) {
+    const result = detectInstalledTools(['pi'], opts({ [where]: [usrBin], osPackageBinDirs: [usrBin] }));
+    assert.deepEqual(result.detected, [], where);
+  }
+});
+
+test('pi linked into an OS package dir detects it', () => {
+  // npm with its prefix at /usr links the agent into /usr/bin.
+  const cli = 'usr-lib/node_modules/pi-coding-agent/dist/cli.js';
+  const { root, opts } = fixture([cli], { 'usr-bin/pi': cli });
+  const usrBin = path.join(root, 'usr-bin');
+  const result = detectInstalledTools(['pi'], opts({ machineBinDirs: [usrBin], osPackageBinDirs: [usrBin] }));
+  assert.deepEqual(result.detected, ['pi']);
+});
+
+test('an OS package dir reached through a link is still one', () => {
+  // /bin is a link to /usr/bin on a merged-usr system.
+  const { root, opts } = fixture(['usr-bin/pi'], { bin: 'usr-bin' });
+  const result = detectInstalledTools(['pi'], opts({
+    pathDirs: [path.join(root, 'bin')], osPackageBinDirs: [path.join(root, 'usr-bin')],
+  }));
+  assert.deepEqual(result.detected, []);
+});
+
+test('a link whose target is gone is not a signal', () => {
+  const { opts } = fixture([], { 'global-bin/pi': 'uninstalled/cli.js' });
+  assert.deepEqual(detectInstalledTools(['pi'], opts()).detected, []);
+});
+
+// The regression that matters: a device where `unbound setup pi` ran before has
+// Unbound's own extension under pi's config dir. That must not count.
+test('files written by Unbound\'s own setup are not install signals', () => {
+  const { opts } = fixture([
+    'home/.pi/agent/extensions/unbound/index.js',
+    'home/.pi/agent/extensions/unbound/index.ts',
+    'home/.unbound/config.json',
+  ]);
+  assert.deepEqual(detectInstalledTools(['pi'], opts()), { detected: [], missing: ['pi'] });
+});
+
+test('windows binaries are matched by their .exe/.cmd/.ps1 shims', () => {
+  for (const shim of ['pi.cmd', 'pi.exe', 'pi.ps1']) {
+    const { opts } = fixture([`home/AppData/Roaming/npm/${shim}`]);
+    assert.deepEqual(detectInstalledTools(['pi'], opts()).detected, [], shim);
+    assert.deepEqual(detectInstalledTools(['pi'], opts({ platform: 'win32' })).detected, ['pi'], shim);
+  }
+});
+
+test('all-users scope finds pi when only another user has it', () => {
+  const { root, home, opts } = fixture(['other/.local/bin/pi']);
+  assert.deepEqual(detectInstalledTools(['pi'], opts()).detected, []);
+  assert.deepEqual(detectInstalledTools(['pi'], opts({ homes: [home, path.join(root, 'other')] })).detected, ['pi']);
+});
+
+// ---- a place that could not be inspected ----
+// Absent and unreadable are different answers. Reporting the second as the
+// first skipped setup on exactly the devices where nothing could be ruled out.
+function withStatFailingUnder(blocked, code, run) {
+  const real = fs.statSync;
+  fs.statSync = (p, ...rest) => {
+    if (String(p).startsWith(blocked)) throw Object.assign(new Error(`${code}: ${p}`), { code });
+    return real(p, ...rest);
+  };
+  try {
+    return run();
+  } finally {
+    fs.statSync = real;
+  }
+}
+
+test('a home that cannot be inspected throws instead of reporting pi missing', () => {
+  for (const code of ['EACCES', 'EPERM', 'EIO']) {
+    const { root, home, opts } = fixture();
+    const locked = path.join(root, 'locked');
+    fs.mkdirSync(locked);
+    assert.throws(
+      () => withStatFailingUnder(locked, code, () => detectInstalledTools(['pi'], opts({ homes: [home, locked] }))),
+      { code },
+    );
+  }
+});
+
+test('a signal found elsewhere wins over a home that cannot be inspected', () => {
+  const { root, home, opts } = fixture(['home/.pi/agent/auth.json']);
+  const locked = path.join(root, 'locked');
+  fs.mkdirSync(locked);
+  const result = withStatFailingUnder(locked, 'EACCES', () => detectInstalledTools(['pi'], opts({ homes: [home, locked] })));
+  assert.deepEqual(result, { detected: ['pi'], missing: [] });
+});
+
+test('an nvm dir that cannot be listed throws instead of reporting pi missing', () => {
+  const { home, opts } = fixture();
+  const nvm = path.join(home, '.nvm', 'versions', 'node');
+  fs.mkdirSync(nvm, { recursive: true });
+  const real = fs.readdirSync;
+  fs.readdirSync = (p, ...rest) => {
+    if (String(p) === nvm) throw Object.assign(new Error('EACCES'), { code: 'EACCES' });
+    return real(p, ...rest);
+  };
+  try {
+    assert.throws(() => detectInstalledTools(['pi'], opts()), { code: 'EACCES' });
+  } finally {
+    fs.readdirSync = real;
+  }
+});
+
+// ---- which homes the all-users scope looks in ----
+test('a home that is not a direct child of the users root is found', () => {
+  // /home/DOMAIN/alice: the MDM setup script installs for that account, so
+  // detection has to look there too. A listing of /home sees only DOMAIN.
+  const { root, opts } = fixture(['users/DOMAIN/alice/.pi/agent/auth.json']);
+  const usersRoot = path.join(root, 'users');
+  const alice = path.join(usersRoot, 'DOMAIN', 'alice');
+
+  const listed = allUserHomes('linux', { root: usersRoot, accounts: [] });
+  assert.equal(listed.includes(alice), false);
+  assert.deepEqual(detectInstalledTools(['pi'], opts({ homes: listed.slice(1) })).detected, []);
+
+  const homes = allUserHomes('linux', { root: usersRoot, accounts: [alice] });
+  assert.equal(homes.includes(alice), true);
+  assert.deepEqual(detectInstalledTools(['pi'], opts({ homes: homes.slice(1) })).detected, ['pi']);
+});
+
+test('linux users named Shared or Guest are real accounts; on macOS they are not', () => {
+  const { root } = fixture(['users/Shared/x', 'users/Guest/x', 'users/alice/x', 'users/.hidden/x']);
+  const usersRoot = path.join(root, 'users');
+  const at = name => path.join(usersRoot, name);
+
+  const linux = allUserHomes('linux', { root: usersRoot, accounts: [] });
+  for (const name of ['Shared', 'Guest', 'alice']) assert.equal(linux.includes(at(name)), true, name);
+  assert.equal(linux.includes(at('.hidden')), false);
+
+  const mac = allUserHomes('darwin', { root: usersRoot, accounts: [at('Guest')] });
+  assert.equal(mac.includes(at('alice')), true);
+  for (const name of ['Shared', 'Guest']) assert.equal(mac.includes(at(name)), false, name);
+});
+
+test('an account home that does not exist is dropped', () => {
+  const { root } = fixture();
+  const homes = allUserHomes('linux', { root: path.join(root, 'users'), accounts: [path.join(root, 'users', 'ghost')] });
+  assert.deepEqual(homes, [os.homedir()]);
+});
+
+// ---- the account database ----
+function withAccountLookup(fake, run) {
+  const real = childProcess.execFileSync;
+  childProcess.execFileSync = fake;
+  try {
+    return run();
+  } finally {
+    childProcess.execFileSync = real;
+  }
+}
+
+test('account homes are the database\'s homes under the platform prefix', () => {
+  const answer = JSON.stringify(['/home/alice', '/home/DOMAIN/bob', '/var/lib/postgres', '/root', '', null]);
+  const errors = [];
+  const homes = withAccountLookup(() => answer, () => accountHomes('linux', errors));
+  assert.deepEqual(homes, ['/home/alice', '/home/DOMAIN/bob']);
+  assert.deepEqual(errors, []);
+  assert.deepEqual(withAccountLookup(() => answer, () => accountHomes('win32', errors)), []);
+});
+
+// A setup script fails the same way, so it could not install into those homes
+// either: forcing Pi here would only fail onboarding on a device without pi.
+test('a missing python or a failing account database is not a detection error', () => {
+  for (const failure of [
+    Object.assign(new Error('spawn python3 ENOENT'), { code: 'ENOENT' }),
+    Object.assign(new Error('Command failed'), { status: 1 }),
+  ]) {
+    const errors = [];
+    const homes = withAccountLookup(() => { throw failure; }, () => accountHomes('linux', errors));
+    assert.deepEqual(homes, []);
+    assert.deepEqual(errors, [], failure.message);
+  }
+});
+
+// The database may be slow rather than down, and a setup script waits longer.
+test('an account lookup that times out counts as a place that could not be inspected', () => {
+  const timeout = Object.assign(new Error('spawnSync python3 ETIMEDOUT'), { code: 'ETIMEDOUT' });
+  const errors = [];
+  assert.deepEqual(withAccountLookup(() => { throw timeout; }, () => accountHomes('linux', errors)), []);
+  assert.deepEqual(errors, [timeout]);
+
+  const { root } = fixture();
+  const seen = [];
+  withAccountLookup(() => { throw timeout; }, () => allUserHomes('linux', { errors: seen, root: path.join(root, 'users') }));
+  assert.deepEqual(seen, [timeout]);
+});
+
+test('an unreadable answer from the account lookup is kept as an error', () => {
+  const errors = [];
+  assert.deepEqual(withAccountLookup(() => 'Traceback (most recent call last)', () => accountHomes('linux', errors)), []);
+  assert.equal(errors.length, 1);
+});
+
+test('a tool with no signals is never ruled out', () => {
+  const { opts } = fixture();
+  assert.deepEqual(detectInstalledTools(['cursor', 'pi'], opts()), { detected: ['cursor'], missing: ['pi'] });
+});
+
+test('pi is the only tool with detection signals', () => {
+  assert.deepEqual(Object.keys(TOOL_SIGNALS), ['pi']);
+});
+
+// ---- onboard uses the detection result ----
+const USER_BUNDLE = ['cursor', 'claude-code-subscription', 'codex-subscription', 'copilot', 'augment'];
+const MDM_BUNDLE = ['cursor', 'claude-code-subscription', 'gemini-cli', 'codex-subscription', 'copilot', 'augment'];
+const piDetected = (names) => ({ detected: names, missing: [] });
+const piMissing = (names) => ({ detected: [], missing: names });
+
+async function runOnboard({ isRoot, detect, fail, discoveryThrows }) {
+  for (const m of [
+    '../src/commands/onboard', '../src/commands/setup', '../src/commands/discover',
+    '../src/auth', '../src/config', '../src/output', '../src/toolDetect',
+  ]) {
+    delete require.cache[require.resolve(m)];
+  }
+  const calls = { bundle: [], candidates: null, allUsers: null, discovery: 0, lines: [], errors: [] };
+  const setup = require('../src/commands/setup');
+  const discover = require('../src/commands/discover');
+  const auth = require('../src/auth');
+  const config = require('../src/config');
+  const output = require('../src/output');
+  const toolDetect = require('../src/toolDetect');
+
+  setup.hasRootPrivileges = () => isRoot;
+  // The core bundle is called with no `tools`; Pi is its own call with ['pi'].
+  const bundle = async (_key, opts) => {
+    const step = opts.tools ? opts.tools.join(',') : 'core';
+    calls.bundle.push(step);
+    return { ok: step !== fail, skipped: [] };
+  };
+  setup.runSetupAllBundle = bundle;
+  setup.runMdmSetupAllBundle = bundle;
+  toolDetect.detectInstalledTools = (names, opts) => {
+    calls.candidates = names;
+    calls.allUsers = opts.allUsers;
+    return detect(names);
+  };
+  discover.runDiscoveryScan = async () => {
+    calls.discovery++;
+    if (discoveryThrows) throw new Error('scan failed');
+  };
+  auth.ensureLoggedIn = async () => {};
+  auth.fetchDeviceOwnerKey = async () => 'owner-key';
+  config.setUrls = () => ({});
+  config.getApiKey = () => 'resolved-key';
+  config.getBaseUrl = () => 'https://b.acme';
+  config.getFrontendUrl = () => 'https://f.acme';
+  config.getGatewayUrl = () => 'https://g.acme';
+  config.isLoggedIn = () => true;
+  output.success = (msg) => calls.lines.push(String(msg));
+  output.error = (msg) => calls.errors.push(String(msg));
+  for (const k of ['info', 'warn']) output[k] = (msg) => calls.lines.push(String(msg));
+
+  const { register } = require('../src/commands/onboard');
+  const program = new Command();
+  program.exitOverride();
+  register(program);
+  const savedLog = console.log;
+  const savedError = console.error;
+  const savedExit = process.exitCode;
+  console.log = (...args) => calls.lines.push(args.join(' '));
+  console.error = (...args) => calls.errors.push(args.join(' '));
+  process.exitCode = 0;
+  try {
+    await program.parseAsync(['node', 'unbound', 'onboard', '--api-key', 'k']);
+    calls.exitCode = process.exitCode;
+  } finally {
+    console.log = savedLog;
+    console.error = savedError;
+    process.exitCode = savedExit;
+  }
+  calls.piLines = calls.lines.filter(l => /\bPi\b/.test(l));
+  calls.setup = setup;
+  return calls;
+}
+
+test('onboard sets pi up after the user bundle when pi is detected', async () => {
+  const calls = await runOnboard({ isRoot: false, detect: piDetected });
+  assert.deepEqual(calls.candidates, ['pi']);
+  assert.equal(calls.allUsers, false);
+  assert.deepEqual(calls.bundle, ['core', 'pi']);
+  assert.equal(calls.discovery, 1);
+  assert.equal(calls.exitCode, 0);
+  assert.equal(calls.piLines.length, 1);
+});
+
+test('onboard installs exactly the user bundle when pi is not detected', async () => {
+  const calls = await runOnboard({ isRoot: false, detect: piMissing });
+  assert.deepEqual(calls.bundle, ['core']);
+  assert.equal(calls.discovery, 1);
+  assert.equal(calls.piLines.length, 1);
+});
+
+test('sudo onboard detects pi across all users and sets it up after the MDM bundle', async () => {
+  const calls = await runOnboard({ isRoot: true, detect: piDetected });
+  assert.deepEqual(calls.candidates, ['pi']);
+  assert.equal(calls.allUsers, true);
+  assert.deepEqual(calls.bundle, ['core', 'pi']);
+  assert.equal(calls.piLines.length, 1);
+});
+
+test('sudo onboard installs exactly the MDM bundle when pi is not detected', async () => {
+  const calls = await runOnboard({ isRoot: true, detect: piMissing });
+  assert.deepEqual(calls.bundle, ['core']);
+  assert.equal(calls.piLines.length, 1);
+});
+
+test('a detection crash still sets pi up, and onboarding exits 0', async () => {
+  for (const isRoot of [false, true]) {
+    const calls = await runOnboard({ isRoot, detect: () => { throw new Error('EPERM'); } });
+    assert.deepEqual(calls.bundle, ['core', 'pi']);
+    assert.equal(calls.discovery, 1);
+    assert.equal(calls.exitCode, 0);
+    assert.equal(calls.piLines.length, 1);
+  }
+});
+
+// Pi is opportunistic: before it joined onboarding, a device with pi still got
+// its bundle and its discovery scan. A broken pi setup must not take those away.
+test('a failed pi setup still runs discovery, and onboarding exits 1', async () => {
+  for (const isRoot of [false, true]) {
+    const calls = await runOnboard({ isRoot, detect: piDetected, fail: 'pi' });
+    assert.deepEqual(calls.bundle, ['core', 'pi']);
+    assert.equal(calls.discovery, 1);
+    assert.equal(calls.exitCode, 1);
+    assert.equal(calls.errors.length, 1);
+    assert.match(calls.errors[0], /Pi Coding Agent setup failed/);
+    assert.match(calls.errors[0], /unbound setup .*pi/);
+    assert.equal(calls.lines.some(l => /Onboarding complete/.test(l)), false);
+  }
+});
+
+// The hints printed for a failed scan retry the scan only. Without its own line
+// the earlier Pi failure would be reported as "tool setup completed".
+test('a failed pi setup is still reported when discovery fails after it', async () => {
+  for (const isRoot of [false, true]) {
+    const calls = await runOnboard({ isRoot, detect: piDetected, fail: 'pi', discoveryThrows: true });
+    assert.equal(calls.exitCode, 1);
+    const text = calls.errors.join('\n');
+    assert.match(text, /Pi Coding Agent setup also failed/);
+    assert.match(text, /unbound setup .*pi/);
+    assert.doesNotMatch(text, /Tool setup completed successfully/);
+  }
+});
+
+test('a failed scan after a clean pi setup keeps the usual message', async () => {
+  const calls = await runOnboard({ isRoot: false, detect: piDetected, discoveryThrows: true });
+  const text = calls.errors.join('\n');
+  assert.match(text, /Tool setup completed successfully — only discovery failed/);
+  assert.doesNotMatch(text, /Pi Coding Agent/);
+});
+
+test('a failed core bundle stops before pi and before discovery', async () => {
+  for (const isRoot of [false, true]) {
+    const calls = await runOnboard({ isRoot, detect: piDetected, fail: 'core' });
+    assert.deepEqual(calls.bundle, ['core']);
+    assert.equal(calls.discovery, 0);
+    assert.equal(calls.exitCode, 1);
+  }
+});
+
+test('the default bundles themselves never gain pi', async () => {
+  for (const isRoot of [false, true]) {
+    const { setup } = await runOnboard({ isRoot, detect: piDetected });
+    assert.deepEqual(setup.ALL_TOOLS, USER_BUNDLE);
+    assert.deepEqual(setup.MDM_ALL_TOOLS, MDM_BUNDLE);
+  }
+});