unbound-cli 1.16.18 → 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.18",
+  "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

@@ -36,6 +36,7 @@ const SETUP_TOOLS = [
   { label: 'Gemini CLI', value: 'gemini', script: 'gemini-cli/gateway/setup.py' },
   { label: 'Codex \u2014 subscription (hooks)', value: 'codex-sub', script: 'codex/hooks/setup.py', group: 'codex' },
   { label: 'Codex \u2014 gateway (gateway)', value: 'codex-gw', script: 'codex/gateway/setup.py', group: 'codex' },
+  { label: 'Pi Coding Agent', value: 'pi', script: 'pi/setup.py' },
 ];
 
 // Labels drop the `(subscription)` suffix on the default mode and keep
@@ -49,6 +50,7 @@ const MDM_TOOLS = {
   'gemini-cli':               { label: 'Gemini CLI',            script: 'gemini-cli/gateway/mdm/setup.py' },
   'codex-subscription':       { label: 'Codex',                 script: 'codex/hooks/mdm/setup.py' },
   'codex-gateway':            { label: 'Codex (gateway)',       script: 'codex/gateway/mdm/setup.py' },
+  'pi':                       { label: 'Pi Coding Agent',       script: 'pi/mdm/setup.py' },
 };
 
 // Default MDM tools for `sudo unbound onboard` (subscription mode for Claude Code/Codex since only one can be active)
@@ -73,6 +75,7 @@ const SETUP_TOOL_MAP = {
   'gemini-cli':               { label: 'Gemini CLI',            script: 'gemini-cli/gateway/setup.py' },
   'codex-subscription':       { label: 'Codex',                 script: 'codex/hooks/setup.py' },
   'codex-gateway':            { label: 'Codex (gateway)',       script: 'codex/gateway/setup.py' },
+  'pi':                       { label: 'Pi Coding Agent',       script: 'pi/setup.py' },
 };
 
 /**
@@ -763,6 +766,7 @@ Available tools:
   claude-code               Claude Code (use --subscription or --gateway)
   gemini-cli                Gemini CLI
   codex                     Codex (use --subscription or --gateway)
+  pi                        Pi Coding Agent
   roo-code                  Roo Code (shows config values)
   cline                     Cline (shows config values)
   kilo-code                 Kilo Code (shows config values)
@@ -782,6 +786,7 @@ Examples:
   $ unbound setup claude-code --gateway                    Claude Code gateway mode
   $ unbound setup claude-code --subscription               Claude Code hooks only
   $ unbound setup codex --gateway                          Codex gateway mode
+  $ unbound setup pi                                       Set up Pi Coding Agent
 
   Install the default bundle (Cursor + Copilot + Augment + Claude Code hooks + Codex hooks):
   $ unbound setup --all                                    Set up the default bundle
@@ -1284,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);
@@ -1310,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);
@@ -1341,6 +1348,8 @@ module.exports = {
   hasRootPrivileges,
   ALL_TOOLS,
   MDM_ALL_TOOLS,
+  SETUP_TOOL_MAP,
+  MDM_TOOLS,
   buildScriptArgs,
   configDirForScript,
   scriptSupportsBackfill,

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/setup-pi.test.js

@@ -0,0 +1,206 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+const {
+  SETUP_TOOL_MAP,
+  MDM_TOOLS,
+  ALL_TOOLS,
+  MDM_ALL_TOOLS,
+  resolveSetupAllTools,
+  buildScriptArgs,
+  configDirForScript,
+  scriptSupportsBackfill,
+} = require('../src/commands/setup');
+
+const SETUP_SOURCE_PATH = path.join(__dirname, '..', 'src', 'commands', 'setup.js');
+const SETUP_SOURCE = fs.readFileSync(SETUP_SOURCE_PATH, 'utf8');
+
+// The 10-00 harness in test/setup-tables.test.js is a test file, not a module: it has
+// no module.exports, and requiring it would re-run its five tests inside this file.
+// The five-check shape below is therefore the same contract re-stated locally rather
+// than imported — test/setup-tables.test.js stays byte-identical.
+function sourceArrayBlock(name) {
+  const start = SETUP_SOURCE.indexOf(`const ${name} = [`);
+  assert.notEqual(start, -1, `${name} not found in setup.js`);
+  const end = SETUP_SOURCE.indexOf('];', start);
+  assert.notEqual(end, -1, `${name} is not terminated`);
+  return SETUP_SOURCE.slice(start, end);
+}
+
+// The "Available tools:" block ends at the first blank line, before the
+// "For multi-tool setup" section that lists the explicit mode names.
+function helpToolLines() {
+  const start = SETUP_SOURCE.indexOf('Available tools:');
+  assert.notEqual(start, -1, 'the help text has no "Available tools:" block');
+  const block = SETUP_SOURCE.slice(start).split('\n\n')[0];
+  return block.split('\n').slice(1).filter((line) => line.trim());
+}
+
+const HELP_TOOL_LINES = helpToolLines();
+const HELP_TOOL_NAMES = HELP_TOOL_LINES.map((line) => line.trim().split(/\s+/)[0]);
+const PICKER_BLOCK = sourceArrayBlock('SETUP_TOOLS');
+
+// SETUP_ALL_TOOLS and MDM_SETUP_ALL_TOOLS are deliberately NOT exported — keeping them
+// unexported is what holds this plan's setup.js diff at five lines — so their membership
+// is read off the array literals, the same seam 10-00 already uses for the help text.
+function sourceStringListBlock(name) {
+  const match = SETUP_SOURCE.match(new RegExp(`const ${name} = \\[([^\\]]*)\\]`));
+  assert.ok(match, `${name} not found as an array literal in setup.js`);
+  return match[1];
+}
+
+const BUNDLES = {
+  // exported, asserted through the real object
+  ALL_TOOLS: (name) => ALL_TOOLS.includes(name),
+  MDM_ALL_TOOLS: (name) => MDM_ALL_TOOLS.includes(name),
+  // unexported, asserted through the source literal
+  SETUP_ALL_TOOLS: (name) => sourceStringListBlock('SETUP_ALL_TOOLS').includes(`'${name}'`),
+  MDM_SETUP_ALL_TOOLS: (name) => sourceStringListBlock('MDM_SETUP_ALL_TOOLS').includes(`'${name}'`),
+};
+
+function checkToolWired(name, spec = {}) {
+  const mdmKey = spec.mdmKey || name;
+  const entry = SETUP_TOOL_MAP[name];
+  const mdmEntry = MDM_TOOLS[mdmKey];
+  return {
+    inSetupMap: Boolean(entry) && entry.script === spec.script,
+    inMdmTools: Boolean(mdmEntry) && mdmEntry.script === spec.mdmScript,
+    inPicker: PICKER_BLOCK.includes(`value: '${name}'`),
+    inHelp: HELP_TOOL_NAMES.includes(name),
+    inSetupAllClear: resolveSetupAllTools(true).includes(name),
+    bundles: Object.keys(BUNDLES).filter((bundle) => BUNDLES[bundle](name)),
+  };
+}
+
+function assertToolWired(name, spec) {
+  const got = checkToolWired(name, spec);
+  assert.ok(got.inSetupMap, `${name}: SETUP_TOOL_MAP entry missing or script !== ${spec.script}`);
+  assert.ok(got.inMdmTools, `${name}: MDM_TOOLS entry missing or script !== ${spec.mdmScript}`);
+  assert.ok(got.inPicker, `${name}: absent from the interactive SETUP_TOOLS picker`);
+  assert.ok(got.inHelp, `${name}: absent from the "Available tools:" help block`);
+  assert.ok(got.inSetupAllClear, `${name}: absent from resolveSetupAllTools(true)`);
+  assert.deepEqual(got.bundles.sort(), [...spec.bundles].sort(), `${name}: bundle membership drifted`);
+  return got;
+}
+
+const PI_SPEC = {
+  script: 'pi/setup.py',
+  mdmScript: 'pi/mdm/setup.py',
+  bundles: [],
+};
+
+// INST-01/INST-02: `unbound setup pi` and `sudo unbound setup pi` resolve to the two
+// Python installers through the dispatcher every other tool already uses.
+test('pi is wired across the four setup tables and in no default bundle', () => {
+  const got = assertToolWired('pi', PI_SPEC);
+  assert.deepEqual(got.bundles, []);
+  assert.equal(SETUP_TOOL_MAP.pi.label, 'Pi Coding Agent');
+  assert.equal(SETUP_TOOL_MAP.pi.script, 'pi/setup.py');
+  assert.equal(MDM_TOOLS.pi.label, 'Pi Coding Agent');
+  assert.equal(MDM_TOOLS.pi.script, 'pi/mdm/setup.py');
+});
+
+// No `group` key: pi has a single mode, so the picker must not offer it as a
+// subscription/gateway pair the way claude-code and codex are grouped.
+test('the interactive picker entry for pi has a script, a label and no group', () => {
+  const line = PICKER_BLOCK.split('\n').find((l) => l.includes("value: 'pi'"));
+  assert.ok(line, `no SETUP_TOOLS entry with value: 'pi'\n${PICKER_BLOCK}`);
+  assert.ok(line.includes("label: 'Pi Coding Agent'"), line);
+  assert.ok(line.includes("script: 'pi/setup.py'"), line);
+  assert.ok(!line.includes('group:'), `pi has one mode, so the picker entry must carry no group: ${line}`);
+});
+
+// `unbound setup --all` and `unbound onboard` print the bundles verbatim, so pi must
+// stay out of all four — but `--all --clear` must still sweep it, because
+// resolveSetupAllTools(true) returns every SETUP_TOOL_MAP key.
+test('pi is absent from each of the four default bundles, asserted one by one', () => {
+  assert.equal(ALL_TOOLS.includes('pi'), false, 'pi leaked into ALL_TOOLS');
+  assert.equal(MDM_ALL_TOOLS.includes('pi'), false, 'pi leaked into MDM_ALL_TOOLS');
+  assert.equal(sourceStringListBlock('SETUP_ALL_TOOLS').includes("'pi'"), false,
+    'pi leaked into the SETUP_ALL_TOOLS literal');
+  assert.equal(sourceStringListBlock('MDM_SETUP_ALL_TOOLS').includes("'pi'"), false,
+    'pi leaked into the MDM_SETUP_ALL_TOOLS literal');
+  // the negative half: the regex reader is not vacuously returning nothing
+  assert.equal(sourceStringListBlock('SETUP_ALL_TOOLS').includes("'cursor'"), true);
+  assert.equal(sourceStringListBlock('MDM_SETUP_ALL_TOOLS').includes("'cursor'"), true);
+});
+
+test('resolveSetupAllTools sweeps pi on --all --clear but never installs it via --all', () => {
+  assert.ok(resolveSetupAllTools(true).includes('pi'), resolveSetupAllTools(true));
+  assert.equal(resolveSetupAllTools(false).includes('pi'), false, resolveSetupAllTools(false));
+});
+
+test('the help text lists pi as "Pi Coding Agent" and shows an `unbound setup pi` example', () => {
+  const piHelpLine = HELP_TOOL_LINES.find((l) => l.trim().startsWith('pi '));
+  assert.ok(piHelpLine, `no pi line in the "Available tools:" block\n${HELP_TOOL_LINES.join('\n')}`);
+  assert.match(piHelpLine, /^\s*pi\s+Pi Coding Agent\s*$/);
+  const examples = SETUP_SOURCE.slice(SETUP_SOURCE.indexOf('Examples:'));
+  assert.match(examples, /\$ unbound setup pi\s+Set up Pi Coding Agent/);
+});
+
+// buildScriptArgs takes no tool argument (setup.js:256), so pi adds no argv behaviour.
+// This is a cross-check of the generic flag shape — test/setup-args.test.js:126-137
+// already owns the primary coverage — asserted once against pi's own call shape.
+test('buildScriptArgs stays tool-agnostic: --domain non-MDM, --frontend-url under MDM, --clear keyless', () => {
+  const user = buildScriptArgs('k-123', { backendUrl: 'https://b', gatewayUrl: 'https://g', frontendUrl: 'https://f' });
+  assert.match(user, /--api-key /);
+  assert.match(user, /--domain /);
+  assert.ok(!user.includes('--frontend-url'), user);
+
+  const mdm = buildScriptArgs('k-123', { frontendUrl: 'https://f', mdm: true });
+  assert.match(mdm, /--frontend-url /);
+  assert.ok(!mdm.includes('--domain'), mdm);
+
+  // --clear runs no auth in the Python installers, so no key is present and the
+  // literal string "undefined" must never reach the argv.
+  const cleared = buildScriptArgs(undefined, { clear: true, backendUrl: 'https://b' });
+  assert.match(cleared, /--clear/);
+  assert.ok(!cleared.includes('--api-key'), cleared);
+  assert.ok(!cleared.includes('undefined'), cleared);
+});
+
+// configDirForScript returns undefined for any script outside this set, and also for a
+// member when CLAUDE_CONFIG_DIR is unset — so set membership, not the return value, is
+// the positive control that keeps the pi assertion from passing vacuously.
+const CLAUDE_CONFIG_DIR_SOURCE = SETUP_SOURCE.slice(
+  SETUP_SOURCE.indexOf('const CLAUDE_CONFIG_DIR_SCRIPTS'),
+  SETUP_SOURCE.indexOf(']);', SETUP_SOURCE.indexOf('const CLAUDE_CONFIG_DIR_SCRIPTS')),
+);
+
+test('pi honours neither CLAUDE_CONFIG_DIR nor --backfill', () => {
+  assert.ok(!configDirForScript('pi/setup.py'), String(configDirForScript('pi/setup.py')));
+  assert.equal(scriptSupportsBackfill('pi/setup.py'), false);
+  assert.equal(scriptSupportsBackfill('pi/mdm/setup.py'), false);
+  // positive controls
+  assert.equal(scriptSupportsBackfill('claude-code/hooks/setup.py'), true);
+  assert.ok(CLAUDE_CONFIG_DIR_SOURCE.includes("'claude-code/hooks/setup.py'"),
+    'the CLAUDE_CONFIG_DIR set no longer lists the Claude hooks installer');
+  assert.ok(!CLAUDE_CONFIG_DIR_SOURCE.includes("'pi/setup.py'"),
+    'pi must not be added to CLAUDE_CONFIG_DIR_SCRIPTS');
+});
+
+// T-10-01: integrity is verified once, in pi/setup.py, against the committed sidecar.
+// A second hash path in JavaScript could diverge from the Python one.
+test('the CLI gains no hashing path — integrity stays in Python', () => {
+  assert.equal(/createHash|sha256/i.test(SETUP_SOURCE), false,
+    'setup.js must contain no hashing: downloadToFile checks status, redirects, wx-open and length only');
+});
+
+// T-10-13: the release-version bump is validated by .github/workflows/version-check.yml,
+// which diffs package.json against a real checkout of `main` on every PR. It is
+// deliberately NOT asserted here: this suite has to pass on any checkout, and a
+// version assertion would couple it to mutable Git state — it would fail on `main`
+// immediately after this PR merges (ours would then equal main's) and would need
+// editing on every future bump. Release state belongs in the release workflow.
+
+// The Edit-tool hazard from 10-VALIDATION: setup.js:33-38 holds four real two-character
+// — escapes. An edit near them must not normalise them into literal em-dashes.
+// Scoped to the picker block on purpose: literal em-dashes are used freely in setup.js
+// comments, so only the four string-literal escapes inside SETUP_TOOLS are asserted.
+test('the four \\u2014 escapes in the picker labels survive byte-for-byte', () => {
+  assert.equal((SETUP_SOURCE.match(/\\u2014/g) || []).length, 4, 'the \\u2014 escape count changed');
+  assert.equal((PICKER_BLOCK.match(/\\u2014/g) || []).length, 4, 'a picker label escape was lost');
+  assert.equal(PICKER_BLOCK.includes('—'), false,
+    'a literal em-dash appeared inside SETUP_TOOLS: an escape was normalised');
+});

package/test/setup-tables.test.js

@@ -0,0 +1,132 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+const {
+  SETUP_TOOL_MAP,
+  MDM_TOOLS,
+  ALL_TOOLS,
+  MDM_ALL_TOOLS,
+  resolveSetupAllTools,
+} = require('../src/commands/setup');
+
+const SETUP_SOURCE_PATH = path.join(__dirname, '..', 'src', 'commands', 'setup.js');
+const SETUP_SOURCE = fs.readFileSync(SETUP_SOURCE_PATH, 'utf8');
+
+// SETUP_TOOLS (the interactive picker) and MDM_SETUP_ALL_TOOLS are not exported and
+// the help text is built inline by addHelpText, so all three are read from source.
+function sourceArrayBlock(name) {
+  const start = SETUP_SOURCE.indexOf(`const ${name} = [`);
+  assert.notEqual(start, -1, `${name} not found in setup.js`);
+  const end = SETUP_SOURCE.indexOf('];', start);
+  assert.notEqual(end, -1, `${name} is not terminated`);
+  return SETUP_SOURCE.slice(start, end);
+}
+
+// The "Available tools:" block ends at the first blank line, before the
+// "For multi-tool setup" section that lists the explicit mode names.
+function helpToolLines() {
+  const start = SETUP_SOURCE.indexOf('Available tools:');
+  assert.notEqual(start, -1, 'the help text has no "Available tools:" block');
+  const block = SETUP_SOURCE.slice(start).split('\n\n')[0];
+  return block.split('\n').slice(1).filter((line) => line.trim());
+}
+
+const HELP_TOOL_NAMES = helpToolLines().map((line) => line.trim().split(/\s+/)[0]);
+const PICKER_BLOCK = sourceArrayBlock('SETUP_TOOLS');
+const MDM_SETUP_ALL_TOOLS_BLOCK = sourceArrayBlock('MDM_SETUP_ALL_TOOLS');
+
+// Every bundle a tool can be in. `pi` must stay out of all four (RESEARCH A1) while
+// still appearing in resolveSetupAllTools(true), so membership is asserted by name.
+const BUNDLES = {
+  SETUP_ALL_TOOLS: (name) => resolveSetupAllTools(false).includes(name),
+  ALL_TOOLS: (name) => ALL_TOOLS.includes(name),
+  MDM_ALL_TOOLS: (name) => MDM_ALL_TOOLS.includes(name),
+  MDM_SETUP_ALL_TOOLS: (name) => MDM_SETUP_ALL_TOOLS_BLOCK.includes(`'${name}'`),
+};
+
+// The five wiring facts a `unbound setup <tool>` entry needs, as booleans, so the
+// negative case can prove each one individually rather than trusting a thrown error.
+function checkToolWired(name, spec = {}) {
+  const mdmKey = spec.mdmKey || name;
+  const entry = SETUP_TOOL_MAP[name];
+  const mdmEntry = MDM_TOOLS[mdmKey];
+  return {
+    inSetupMap: Boolean(entry) && entry.script === spec.script,
+    inMdmTools: Boolean(mdmEntry) && mdmEntry.script === spec.mdmScript,
+    inPicker: PICKER_BLOCK.includes(`value: '${name}'`),
+    inHelp: HELP_TOOL_NAMES.includes(name),
+    inSetupAllClear: resolveSetupAllTools(true).includes(name),
+    bundles: Object.keys(BUNDLES).filter((bundle) => BUNDLES[bundle](name)),
+  };
+}
+
+function assertToolWired(name, spec) {
+  const got = checkToolWired(name, spec);
+  assert.ok(got.inSetupMap, `${name}: SETUP_TOOL_MAP entry missing or script !== ${spec.script}`);
+  assert.ok(got.inMdmTools, `${name}: MDM_TOOLS entry missing or script !== ${spec.mdmScript}`);
+  assert.ok(got.inPicker, `${name}: absent from the interactive SETUP_TOOLS picker`);
+  assert.ok(got.inHelp, `${name}: absent from the "Available tools:" help block`);
+  assert.ok(got.inSetupAllClear, `${name}: absent from resolveSetupAllTools(true)`);
+  assert.deepEqual(got.bundles.sort(), [...spec.bundles].sort(),
+    `${name}: bundle membership drifted`);
+  return got;
+}
+
+// The maps have to be reachable at all before any assertion about them means anything.
+test('setup.js exports SETUP_TOOL_MAP and MDM_TOOLS as plain objects', () => {
+  assert.equal(typeof SETUP_TOOL_MAP, 'object');
+  assert.equal(typeof MDM_TOOLS, 'object');
+  assert.ok(Object.keys(SETUP_TOOL_MAP).length >= 8, Object.keys(SETUP_TOOL_MAP));
+  assert.ok(Object.keys(MDM_TOOLS).length >= 8, Object.keys(MDM_TOOLS));
+});
+
+// Proves the five-check assertion against a tool that is already fully wired.
+test('assertToolWired: augment is wired across all four tables', () => {
+  const got = assertToolWired('augment', {
+    script: 'augment/hooks/setup.py',
+    mdmScript: 'augment/hooks/mdm/setup.py',
+    bundles: ['SETUP_ALL_TOOLS', 'ALL_TOOLS', 'MDM_ALL_TOOLS', 'MDM_SETUP_ALL_TOOLS'],
+  });
+  assert.equal(SETUP_TOOL_MAP.augment.label, 'Augment Code');
+  assert.equal(got.bundles.length, 4);
+});
+
+// The regression half: a tool in SETUP_TOOL_MAP is in `--all --clear` for free,
+// because resolveSetupAllTools(true) returns Object.keys(SETUP_TOOL_MAP).
+test('resolveSetupAllTools: clear covers every SETUP_TOOL_MAP key, install covers the bundle only', () => {
+  assert.deepEqual(resolveSetupAllTools(true).sort(), Object.keys(SETUP_TOOL_MAP).sort());
+  const install = resolveSetupAllTools(false);
+  assert.ok(install.length < resolveSetupAllTools(true).length, install);
+  for (const name of install) {
+    assert.ok(SETUP_TOOL_MAP[name], `${name} is in the install bundle but not in SETUP_TOOL_MAP`);
+  }
+});
+
+// Without this the five checks could all pass vacuously on a typo'd tool name.
+test('assertToolWired: a made-up tool fails every one of the five checks', () => {
+  const got = checkToolWired('definitely-not-a-tool', {
+    script: 'definitely-not-a-tool/setup.py',
+    mdmScript: 'definitely-not-a-tool/mdm/setup.py',
+  });
+  assert.equal(got.inSetupMap, false);
+  assert.equal(got.inMdmTools, false);
+  assert.equal(got.inPicker, false);
+  assert.equal(got.inHelp, false);
+  assert.equal(got.inSetupAllClear, false);
+  assert.deepEqual(got.bundles, []);
+  assert.throws(() => assertToolWired('definitely-not-a-tool', {
+    script: 'definitely-not-a-tool/setup.py',
+    mdmScript: 'definitely-not-a-tool/mdm/setup.py',
+    bundles: [],
+  }), /SETUP_TOOL_MAP entry missing/);
+});
+
+// The source-read helpers are the fragile half of this file: if a rename made either
+// block unfindable, every membership check would silently report false.
+test('the source-read blocks are real and non-empty', () => {
+  assert.ok(PICKER_BLOCK.includes("value: 'cursor'"), 'SETUP_TOOLS block did not parse');
+  assert.ok(MDM_SETUP_ALL_TOOLS_BLOCK.includes("'cursor'"), 'MDM_SETUP_ALL_TOOLS did not parse');
+  assert.ok(HELP_TOOL_NAMES.length >= 10, HELP_TOOL_NAMES);
+  assert.ok(HELP_TOOL_NAMES.includes('cursor'), HELP_TOOL_NAMES);
+});

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);
+  }
+});