unbound-cli 1.2.0 → 1.3.0

package/LOCAL_DEV.md

@@ -119,8 +119,8 @@ node src/index.js login --base-url http://localhost:8000 --api-key <your-key>
 
 ```bash
 # Auth
-node src/index.js whoami
 node src/index.js status
+node src/index.js doctor
 
 # Policies — overview
 node src/index.js policy                         # overview + docs links

package/README.md

@@ -17,8 +17,8 @@ unbound login
 # Or login with an API key (for CI/CD or headless environments)
 unbound login --api-key <your-api-key>
 
-# Check who you are
-unbound whoami
+# Check your status, role, and connected tools
+unbound status
 
 # List policies
 unbound policy list
@@ -55,8 +55,8 @@ The user API key and discovery API key are separate — discovery uses its own k
 | `unbound login --api-key <key>` | Sign in with an API key (non-interactive) |
 | `unbound login --domain <domain>` | Sign in via a custom domain |
 | `unbound logout` | Remove stored credentials |
-| `unbound whoami` | Show current user, org, and role |
-| `unbound status` | Show CLI status and API connectivity |
+| `unbound status` | Show CLI status, role, and connected tools |
+| `unbound doctor` | Diagnose per-tool health (config, hook, env) and API key |
 
 ### Tool Setup
 

package/package.json

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

package/src/commands/chat.js

@@ -121,7 +121,7 @@ function normalizeAssistantTurn(turn) {
 // backend-supplied strings out of the shell line so copy-pastes stay safe.
 function friendlyChatError(err) {
   if (err?.statusCode === 401) return 'Not authenticated. Run `unbound login` and try again.';
-  if (err?.statusCode === 403) return 'Chat requires Admin or Manager role. Run `unbound whoami` to check yours.';
+  if (err?.statusCode === 403) return 'Chat requires Admin or Manager role. Run `unbound status` to check yours.';
   if (err?.statusCode === 429) return 'Rate limited. Please wait a moment and try again.';
   return sanitizeForTerminal(err?.message || 'Request failed.');
 }
@@ -479,7 +479,7 @@ INTERACTIVE SESSION
     /exit              quit (Ctrl+C also works)
 
 NOTES
-  * Requires Admin or Manager role in your organization. Run 'unbound whoami' to check.
+  * Requires Admin or Manager role in your organization. Run 'unbound status' to check.
   * Conversation history is held in memory only; nothing is ever written to disk.
   * Each -m invocation sends no history; keep each prompt self-contained.
   * -o writes a new file with mode 0600 and refuses to overwrite existing files.

package/src/commands/doctor.js

@@ -0,0 +1,198 @@
+const { spawnSync } = require('child_process');
+const config = require('../config');
+const api = require('../api');
+const output = require('../output');
+const { getDeviceSerial } = require('../device-serial');
+const { detectTools } = require('../toolHealth');
+const { hasRootPrivileges } = require('./setup');
+
+// Validate the stored API key against the backend. Returns one of:
+// valid | invalid | not-logged-in | unverified (network/other error).
+async function checkApiKey() {
+  if (!config.isLoggedIn()) return { state: 'not-logged-in', detail: 'no API key stored — run `unbound login`' };
+  try {
+    const deviceSerial = await getDeviceSerial();
+    const privileges = await api.get('/api/v1/users/privileges/', { query: { device_serial: deviceSerial } });
+    config.backfillUserInfo(privileges);
+    return { state: 'valid', detail: 'verified against the backend' };
+  } catch (err) {
+    // The HTTP status is the reliable signal; the message wording can change.
+    if (err && (err.statusCode === 401 || /invalid or expired|401|unauthor/i.test(err.message || ''))) {
+      return { state: 'invalid', detail: 'the stored key was rejected (401) — run `unbound login`' };
+    }
+    return { state: 'unverified', detail: `could not verify (${err.message})` };
+  }
+}
+
+// Exit code for `--fix`: signal/spawn error → 1; otherwise the `setup` status. A
+// successful non-root run that left MDM tools tampered still fails so a CI gate
+// doesn't read the machine as clean. As root those tools were just repaired, so a
+// status-0 run is clean — don't penalize.
+function fixExitCode(status, root, mdmRemaining) {
+  if (status == null) return 1;
+  return status || (!root && mdmRemaining ? 1 : 0);
+}
+
+function register(program) {
+  program
+    .command('doctor')
+    .description('Diagnose the local Unbound install: per-tool config, hook script and env wiring, plus API-key validity. Prints how to fix anything broken.')
+    .addHelpText('after', `
+For each AI coding tool, doctor verifies:
+  Config       - the tool's config file contains the Unbound integration
+  Hook script  - the installed hook/key-helper file exists
+  Env wiring   - the API key (and gateway URL, for gateway mode) is exported
+
+Per-tool status:
+  Healthy       - everything in place
+  Tampered      - partially installed (reinstall to fix)
+  Not installed - no Unbound integration found
+  Managed by MDM- configured org-wide by your administrator
+
+Exit code is non-zero when any tool is tampered or the API key is invalid, so
+doctor can gate scripts/CI.
+
+Examples:
+  $ unbound doctor
+  $ unbound doctor --fix      Reinstall every tampered tool
+  $ unbound doctor --json
+`)
+    .option('--fix', 'Reinstall every tool reported as tampered')
+    .option('--json', 'Output raw JSON')
+    .action(async (opts) => {
+      try {
+        const apiKey = config.getApiKey();
+        const gatewayUrl = config.getGatewayUrl();
+
+        const spin = output.spinner('Running diagnostics...');
+        const key = await checkApiKey();
+        const tools = detectTools({ gatewayUrl, apiKey });
+        spin.stop();
+
+        const tampered = tools.filter((t) => t.status === 'tampered');
+        const unhealthy = tampered.length > 0 || key.state === 'invalid';
+
+        if (opts.json) {
+          output.json({
+            api_key: key,
+            tools: tools.map((t) => ({
+              tool: t.key,
+              label: t.label,
+              mode: t.mode,
+              status: t.status,
+              conflict: !!t.conflict,
+              checks: t.checks.map((c) => ({ name: c.name, ok: c.ok, kind: c.kind, detail: c.detail, warn: !!c.warn })),
+            })),
+            healthy: !unhealthy,
+          });
+          if (unhealthy) process.exitCode = 1;
+          return;
+        }
+
+        const C = output.colors;
+        const labelOf = (t) => t.label + (t.mode ? ` (${t.mode})` : '');
+        const W = Math.max(7, ...tools.map((t) => labelOf(t).length)); // 7 = "API key"
+
+        console.log('');
+        const keyText = {
+          valid: C.green('✓ Valid'),
+          invalid: C.red('✗ Invalid or expired'),
+          'not-logged-in': C.dim('– Not logged in'),
+          unverified: `${C.yellow('? Could not verify')} ${C.dim(`(${key.detail})`)}`,
+        }[key.state];
+        console.log(`  ${C.bold('API key'.padEnd(W))}   ${keyText}`);
+        console.log('');
+
+        for (const t of tools) {
+          let s;
+          if (t.status === 'healthy') s = C.green('✓ Healthy');
+          else if (t.status === 'managed-by-mdm') s = C.green('✓ Healthy') + C.dim(' · managed by MDM');
+          else if (t.status === 'tampered') {
+            // Status + reason on one line. Mode sits next to the tool name.
+            const reasons = [];
+            if (t.conflict) reasons.push('two modes installed');
+            for (const c of t.checks) if (!c.ok) reasons.push(c.summary || c.name);
+            s = C.red(`✗ Tampered — ${reasons.join(', ')}`);
+          } else s = C.dim('○ Not set up');
+          console.log(`  ${labelOf(t).padEnd(W)}   ${s}`);
+        }
+        console.log('');
+
+        // Fix routing. User-level tools are fixable by anyone (`unbound doctor
+        // --fix`); MDM-managed ones need `sudo`. One sudo run repairs everything
+        // (sudo `setup` installs MDM-wide, and on macOS sudo keeps HOME so it sees
+        // the user's tools too). When both kinds are broken we show both commands
+        // so a user WITHOUT sudo can still repair their own user-level tools.
+        const userTampered = tampered.filter((t) => t.scope !== 'mdm');
+        const mdmTampered = tampered.filter((t) => t.scope === 'mdm');
+        const userFix = userTampered.map((t) => t.key);
+        const mdmFix = mdmTampered.map((t) => t.key);
+        const userNames = userTampered.map((t) => t.label).join(', ');
+        const mdmNames = mdmTampered.map((t) => t.label).join(', ');
+        const allFix = tampered.map((t) => t.key);
+        const anyInstalled = tools.some((t) => t.status !== 'not-installed');
+
+        if (opts.fix) {
+          if (!tampered.length) {
+            if (!anyInstalled) console.log(`${C.yellow('No tools are set up yet')} — nothing to fix. Run ${C.bold('unbound setup')} first.`);
+            else output.success('Nothing to fix — all set up tools are healthy.');
+            console.log('');
+            return;
+          }
+          const root = hasRootPrivileges();
+          // sudo → reinstall everything (MDM-wide); without sudo → the user-level
+          // tools only, and point at sudo for whatever's org-managed.
+          if (!root && !userFix.length) {
+            console.log(`${mdmNames} ${mdmFix.length === 1 ? 'is' : 'are'} set up by your organization.`);
+            console.log(`  Run ${C.bold('sudo unbound doctor --fix')} to repair ${mdmFix.length === 1 ? 'it' : 'them'}.`);
+            console.log('');
+            process.exitCode = 1;
+            return;
+          }
+          const fixNow = root ? allFix : userFix;
+          output.info(`Reinstalling: ${fixNow.join(', ')}${root ? ' (org-wide, all users)' : ''}`);
+          console.log('');
+          const r = spawnSync(process.argv[0], [process.argv[1], 'setup', ...fixNow], { stdio: 'inherit' });
+          if (!root && mdmFix.length) console.error(`  ${mdmNames} ${mdmFix.length === 1 ? 'is' : 'are'} set up by your organization — run ${C.bold('sudo unbound doctor --fix')} to repair ${mdmFix.length === 1 ? 'it' : 'them'}.`);
+          process.exitCode = fixExitCode(r.status, root, mdmFix.length > 0);
+          return;
+        }
+
+        // No `--fix`: report and show the command(s) that fix it.
+        if (!anyInstalled && key.state !== 'invalid') {
+          console.log(`${C.yellow('No AI tools are set up yet.')} Run ${C.bold('unbound setup')} to get started.`);
+          console.log('');
+          return;
+        }
+        if (!unhealthy) {
+          output.success('All set up tools are healthy.');
+          console.log('');
+          return;
+        }
+        if (tampered.length) {
+          console.log(C.red(`✗ ${tampered.length} tool${tampered.length === 1 ? ' needs' : 's need'} attention.`));
+          if (!mdmFix.length) {
+            console.log(`  Run ${C.bold('unbound doctor --fix')} to repair ${userNames}.`);
+          } else if (!userFix.length) {
+            console.log(`  ${mdmNames} ${mdmFix.length === 1 ? 'is' : 'are'} set up by your organization.`);
+            console.log(`  Run ${C.bold('sudo unbound doctor --fix')} to repair ${mdmFix.length === 1 ? 'it' : 'them'}.`);
+          } else {
+            // Both: a user without sudo can still fix their own tools; sudo fixes everything.
+            console.log(`  Run ${C.bold('unbound doctor --fix')} to repair ${userNames}.`);
+            console.log(`  ${mdmNames} ${mdmFix.length === 1 ? 'is' : 'are'} set up by your organization — run ${C.bold('sudo unbound doctor --fix')} to repair ${mdmFix.length === 1 ? 'it' : 'them'} too.`);
+          }
+        }
+        if (key.state === 'invalid') {
+          if (!tampered.length) console.log(C.red('✗ Your API key is invalid or expired.'));
+          console.log(`  Run ${C.bold('unbound login')} to re-authenticate.`);
+        }
+        console.log('');
+        process.exitCode = 1;
+      } catch (err) {
+        if (!err.displayed) output.error(err.message);
+        process.exitCode = 1;
+      }
+    });
+}
+
+module.exports = { register, fixExitCode };

package/src/commands/status.js

@@ -2,21 +2,36 @@ const config = require('../config');
 const api = require('../api');
 const output = require('../output');
 const { getDeviceSerial } = require('../device-serial');
+const { detectTools } = require('../toolHealth');
+
+function roleFromPrivileges(p) {
+  if (!p) return null;
+  if (p.is_admin) return 'Admin';
+  if (p.is_manager) return 'Manager';
+  if (p.is_member) return 'Member';
+  return 'Unknown';
+}
+
 
 function register(program) {
   program
     .command('status')
-    .description('Show the current CLI status including config location, login state, and API connectivity. Useful for debugging connection issues.')
+    .description('Show the current CLI status: config location, login state, role, connected tools, and API connectivity. Useful for debugging connection issues.')
     .addHelpText('after', `
 Output fields:
   Config file      - Path to the config file (~/.unbound/config.json)
   Logged in        - Whether credentials are stored (Yes/No)
   Email            - The authenticated user's email (if logged in)
   Organization     - The organization name (if logged in)
+  Role             - Admin / Manager / Member (if logged in)
   Backend URL      - REST API host (configurable for tenant deployments)
   Frontend URL     - Browser login host
   Gateway URL      - AI gateway host (used by tool setup)
   API status       - Connectivity check result (Connected / Error)
+  Connected tools  - AI tools wired through Unbound on this device, with mode
+
+For a deep per-tool health check (config, hook script, env wiring), run
+\`unbound doctor\`.
 
 Examples:
   $ unbound status
@@ -32,8 +47,8 @@ Examples:
           ['Logged in', loggedIn ? 'Yes' : 'No'],
         ];
 
-        // Check API connectivity
         let connectivity = 'Not checked (not logged in)';
+        let role = null;
         if (loggedIn) {
           const spin = output.spinner('Checking API connectivity...');
           try {
@@ -42,6 +57,7 @@ Examples:
               query: { device_serial: deviceSerial },
             });
             config.backfillUserInfo(privileges);
+            role = roleFromPrivileges(privileges);
             spin.stop();
             connectivity = 'Connected';
           } catch (err) {
@@ -52,12 +68,17 @@ Examples:
           const cfg = config.readConfig();
           pairs.push(['Email', cfg.email || '-']);
           pairs.push(['Organization', cfg.org_name || '-']);
+          pairs.push(['Role', role || '-']);
         }
         pairs.push(['Backend URL', config.getBaseUrl()]);
         pairs.push(['Frontend URL', config.getFrontendUrl()]);
         pairs.push(['Gateway URL', config.getGatewayUrl()]);
         pairs.push(['API status', connectivity]);
 
+        // Locally detected AI tools wired through Unbound, with their mode.
+        const connected = detectTools({ gatewayUrl: config.getGatewayUrl(), apiKey: config.getApiKey() })
+          .filter((t) => t.status !== 'not-installed');
+
         if (opts.json) {
           const cfg = loggedIn ? config.readConfig() : {};
           output.json({
@@ -65,15 +86,34 @@ Examples:
             logged_in: loggedIn,
             email: loggedIn ? (cfg.email || null) : null,
             organization: loggedIn ? (cfg.org_name || null) : null,
+            role: role,
             backend_url: config.getBaseUrl(),
             frontend_url: config.getFrontendUrl(),
             gateway_url: config.getGatewayUrl(),
             api_status: connectivity,
+            connected_tools: connected.map((t) => ({ tool: t.key, label: t.label, mode: t.mode, status: t.status })),
           });
           return;
         }
 
         output.keyValue(pairs);
+
+        console.log('');
+        output.info('Connected tools');
+        const C = output.colors;
+        if (connected.length === 0) {
+          console.log(`  ${C.dim('None set up yet.')} Run ${C.bold('unbound setup')} to wire a tool.`);
+        } else {
+          for (const t of connected) {
+            const mode = t.mode ? C.dim(` (${t.mode})`) : '';
+            let mark = C.green('✓');
+            let note = '';
+            if (t.status === 'tampered') { mark = C.red('✗'); note = C.dim(' — run `unbound doctor`'); }
+            else if (t.status === 'managed-by-mdm') { note = C.dim(' (managed by MDM)'); }
+            console.log(`  ${mark} ${t.label}${mode}${note}`);
+          }
+        }
+        console.log('');
       } catch (err) {
         output.error(err.message);
         process.exitCode = 1;

package/src/config.js

@@ -141,7 +141,7 @@ function isLoggedIn() {
  * Refreshes cached user identity (email, org_name) from a backend response.
  * Always overwrites when the response carries a non-empty value so that
  * switching tenants under the same API key (or rotating the key to a new org)
- * shows the correct organization in `whoami` / `status` instead of stale data.
+ * shows the correct organization in `status` instead of stale data.
  * Defensive: leaves an existing cached value untouched if the response field
  * is missing or empty, so a partial API response can't blank the local config.
  */

package/src/index.js

@@ -29,8 +29,8 @@ AUTHENTICATION
   $ unbound login --api-key <key>          Sign in with an API key (for CI/CD)
   $ unbound login --domain custom.co       Sign in via custom domain
   $ unbound logout                         Remove stored credentials
-  $ unbound whoami                         Show current user and organization
-  $ unbound status                         Show CLI status and API connectivity
+  $ unbound status                         Show CLI status, role, and connected tools
+  $ unbound doctor                         Diagnose per-tool health and API key
 
   Tenant deployments — pass URL flags on login; they persist to ~/.unbound/config.json:
   $ unbound login --api-key <YOUR_API_KEY> \\
@@ -178,8 +178,8 @@ LEARN MORE
 // Register all command modules
 require('./commands/login').register(program);
 require('./commands/logout').register(program);
-require('./commands/whoami').register(program);
 require('./commands/status').register(program);
+require('./commands/doctor').register(program);
 require('./commands/policy').register(program);
 require('./commands/users').register(program);
 require('./commands/user-groups').register(program);
@@ -241,7 +241,7 @@ Use this on a fresh install for tenant deployments. Positional order is fixed:
   2. <frontend-url>  — Frontend host (e.g. https://gateway.acme.com)
                        Used by the browser login flow.
   3. <backend-url>   — REST API host (e.g. https://backend.acme.com)
-                       All "unbound *" commands (whoami, status, policies, ...) hit this.
+                       All "unbound *" commands (status, doctor, policies, ...) hit this.
 
 Bare hostnames are accepted; "https://" is added automatically.
 The three values are written atomically to ~/.unbound/config.json.

package/src/toolHealth.js

@@ -0,0 +1,288 @@
+// Per-tool local health detection shared by `unbound doctor` and `unbound status`.
+//
+// Source of truth for what each tool installs is the setup repo's per-tool
+// setup.py (mirrored here). Each tool has STRUCTURAL artifacts (a config file
+// with an Unbound marker + an optional hook/script file) that decide whether it
+// is installed, plus AUXILIARY wiring (an env var holding the api key, or the
+// gateway URL). Env vars are persisted to a shell rc file (Unix) or the user
+// registry (Windows), NOT reliably to the current process env, so we read those.
+//
+// Install state (matches the doctor spec):
+//   none of the structural artifacts present  -> not installed
+//   all structural present AND all wiring ok   -> healthy
+//   some present (or wiring broken)            -> tampered
+//   nothing local but an org MDM install found -> managed by MDM
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const HOME = os.homedir();
+const GATEWAY_DEFAULT = 'https://api.getunbound.ai';
+
+function expand(p) {
+  return p.startsWith('~') ? path.join(HOME, p.slice(1)) : p;
+}
+
+function fileExists(p) {
+  try {
+    return fs.statSync(expand(p)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function readText(p) {
+  try {
+    return fs.readFileSync(expand(p), 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function readJson(p) {
+  const text = readText(p);
+  if (text == null) return null;
+  try {
+    return JSON.parse(text.replace(/^\uFEFF/, '')); // tolerate a UTF-8 BOM
+  } catch {
+    return undefined; // file exists but is corrupt
+  }
+}
+
+// Candidate shell rc files where the setup scripts append `export NAME=...`.
+function rcFiles() {
+  if (process.platform === 'win32') return [];
+  if (process.platform === 'darwin') return ['~/.zprofile', '~/.bash_profile', '~/.zshrc', '~/.bashrc'];
+  return ['~/.zshrc', '~/.bashrc', '~/.profile'];
+}
+
+// Read a persisted env var: live process env first, then the shell rc (Unix) or
+// the user registry (Windows). Returns the value so callers can flag mismatch.
+function readEnvVar(name) {
+  // `in`, not truthiness: an env var explicitly set to "" is "set but empty", not
+  // absent — without this we'd fall through and return a stale rc-file value,
+  // masking the fact that the live env blanked the key.
+  if (name in process.env) return { found: true, value: process.env[name], source: 'process env' };
+
+  if (process.platform === 'win32') {
+    try {
+      const r = spawnSync('reg', ['query', 'HKCU\\Environment', '/v', name], { encoding: 'utf8' });
+      if (r.status === 0 && r.stdout) {
+        const m = r.stdout.match(new RegExp(`${name}\\s+REG_[A-Z_]+\\s+(.*)`));
+        if (m) return { found: true, value: m[1].trim(), source: 'user registry' };
+      }
+    } catch {
+      /* fall through */
+    }
+    return { found: false };
+  }
+
+  const re = new RegExp(`^\\s*export\\s+${name}=(.*)$`, 'm');
+  for (const rc of rcFiles()) {
+    const text = readText(rc);
+    if (!text) continue;
+    const m = text.match(re);
+    if (m) {
+      const val = m[1].trim().replace(/^["']|["']$/g, '');
+      return { found: true, value: val, source: path.basename(expand(rc)) };
+    }
+  }
+  return { found: false };
+}
+
+// --- check builders. Each returns { name, ok, kind, detail, summary, warn? }. ---
+// kind: 'structural' (decides installed) | 'aux' (wiring health only).
+// summary: a short reason shown inline on the tampered line.
+
+function configCheck(label, file, marker, opts = {}) {
+  const kind = opts.kind || 'structural';
+  const data = marker.json ? readJson(file) : readText(file);
+  let ok = false;
+  let detail;
+  let summary;
+  if (data == null) {
+    detail = `not found (${file})`;
+    summary = opts.short || `${label.toLowerCase()} not found`;
+  } else if (data === undefined) {
+    detail = `unreadable / corrupt (${file})`;
+    summary = `${label.toLowerCase()} unreadable`;
+  } else {
+    ok = marker.test(data);
+    detail = ok ? file : `present but missing the Unbound integration (${file})`;
+    summary = opts.short || `${label.toLowerCase()} not integrated`;
+  }
+  return { name: label, ok, kind, detail, summary };
+}
+
+function scriptCheck(label, file, kind = 'structural') {
+  const ok = fileExists(file);
+  return { name: label, ok, kind, detail: ok ? file : `not found (${file})`, summary: `${label.toLowerCase()} missing` };
+}
+
+function envCheck(label, name, expected, kind = 'aux') {
+  const base = label.replace(/ env$/, '');
+  const r = readEnvVar(name);
+  // An explicitly-empty value is broken wiring, same as absent.
+  if (!r.found || !r.value) return { name: label, ok: false, kind, detail: `${name} is not set`, summary: `${base} not set` };
+  // A value that doesn't match what setup wrote (stale key, wrong gateway URL) is a
+  // real misconfiguration: mark it not-ok so the tool reports tampered, not healthy.
+  if (expected && r.value !== expected) {
+    return { name: label, ok: false, kind, warn: true, summary: `${base} differs from setup`, detail: `${name} set (${r.source}) but differs from what setup configured` };
+  }
+  return { name: label, ok: true, kind, detail: `${name} set (${r.source})`, summary: `${base} set` };
+}
+
+// MDM (org-wide) install detection. An Unbound MDM install is only real when the
+// system managed config REFERENCES the Unbound hook AND the hook script exists.
+// A plain managed-settings.json (Claude Enterprise / generic MDM) does NOT count,
+// and a managed config that points at a missing hook script is a broken (tampered)
+// MDM install, not a healthy one. Returns { status: 'healthy'|'tampered'|null, checks }.
+function mdmDetect(family, dirOverride) {
+  // Only Cursor / Claude Code / Codex have a managed (MDM) directory. Copilot and
+  // Gemini have none — their org install writes the same per-user config into
+  // every profile, so they're checked exactly like a user-level tool.
+  const configName = { cursor: 'hooks.json', 'claude-code': 'managed-settings.json', codex: 'managed-settings.json' };
+  if (!configName[family]) return { status: null, checks: [] };
+
+  const mac = '/Library/Application Support';
+  const win = process.env.ProgramData || 'C:\\ProgramData';
+  const dirs = {
+    cursor: { darwin: `${mac}/Cursor`, linux: '/etc/cursor', win32: path.join(win, 'Cursor') },
+    'claude-code': { darwin: `${mac}/ClaudeCode`, linux: '/etc/claude-code', win32: path.join(win, 'ClaudeCode') },
+    codex: { darwin: `${mac}/Codex`, linux: '/etc/codex', win32: path.join(win, 'Codex') },
+  };
+  const dir = dirOverride || dirs[family][process.platform] || dirs[family].linux;
+  const configPath = path.join(dir, configName[family]);
+  const scriptPath = path.join(dir, 'hooks', 'unbound.py');
+
+  const cfgText = readText(configPath);
+  if (cfgText == null || !cfgText.includes('unbound.py')) return { status: null, checks: [] };
+
+  const scriptOk = fileExists(scriptPath);
+  const checks = [
+    { name: 'MDM config', ok: true, kind: 'structural', detail: configPath, summary: 'managed config' },
+    { name: 'MDM hook script', ok: scriptOk, kind: 'structural', summary: 'managed hook not installed', detail: scriptOk ? scriptPath : `managed config references a hook that isn't installed (${scriptPath})` },
+  ];
+  return { status: scriptOk ? 'healthy' : 'tampered', checks };
+}
+
+// Marker that a claude/codex/cursor hooks block references unbound.py.
+function refsUnbound(obj) {
+  return JSON.stringify(obj || {}).includes('unbound.py');
+}
+
+// One descriptor per (tool, mode). `family` groups the two-mode tools so the
+// collapsed view shows a single line per product.
+function buildVariants(gatewayUrl, apiKey) {
+  const gw = (gatewayUrl || GATEWAY_DEFAULT).replace(/\/+$/, ''); // setup rstrips too
+  return [
+    {
+      key: 'cursor', label: 'Cursor', family: 'cursor', mode: null,
+      checks: () => [
+        configCheck('Config', '~/.cursor/hooks.json', { json: true, test: refsUnbound }),
+        scriptCheck('Hook script', '~/.cursor/hooks/unbound.py'),
+        envCheck('API key env', 'UNBOUND_CURSOR_API_KEY', apiKey),
+      ],
+    },
+    {
+      key: 'claude-code-subscription', label: 'Claude Code (subscription)', family: 'claude-code', mode: 'subscription',
+      checks: () => [
+        configCheck('Config', '~/.claude/settings.json', { json: true, test: refsUnbound }),
+        scriptCheck('Hook script', '~/.claude/hooks/unbound.py'),
+        envCheck('API key env', 'UNBOUND_CLAUDE_API_KEY', apiKey),
+      ],
+    },
+    {
+      key: 'claude-code-gateway', label: 'Claude Code (gateway)', family: 'claude-code', mode: 'gateway',
+      checks: () => [
+        configCheck('Config', '~/.claude/settings.json', { json: true, test: (j) => typeof j.apiKeyHelper === 'string' && j.apiKeyHelper.includes('anthropic_key.sh') }),
+        scriptCheck('Key helper', '~/.claude/anthropic_key.sh'),
+        envCheck('API key env', 'UNBOUND_API_KEY', apiKey),
+        envCheck('Gateway URL env', 'ANTHROPIC_BASE_URL', gw),
+      ],
+    },
+    {
+      key: 'codex-subscription', label: 'Codex (subscription)', family: 'codex', mode: 'subscription',
+      checks: () => [
+        configCheck('Config', '~/.codex/hooks.json', { json: true, test: refsUnbound }),
+        configCheck('Hooks feature flag', '~/.codex/config.toml', { json: false, test: (t) => /codex_hooks\s*=\s*true/.test(t) }, { short: 'codex hooks not enabled' }),
+        scriptCheck('Hook script', '~/.codex/hooks/unbound.py'),
+        envCheck('API key env', 'UNBOUND_CODEX_API_KEY', apiKey),
+      ],
+    },
+    {
+      key: 'codex-gateway', label: 'Codex (gateway)', family: 'codex', mode: 'gateway',
+      checks: () => [
+        configCheck('Config', '~/.codex/config.toml', { json: false, test: (t) => /openai_base_url\s*=/.test(t) }),
+        envCheck('API key env', 'OPENAI_API_KEY', apiKey),
+      ],
+    },
+    {
+      key: 'copilot', label: 'GitHub Copilot', family: 'copilot', mode: null,
+      checks: () => [
+        // Copilot has no managed (MDM) directory: the org install writes the same
+        // ~/.copilot config into every user profile, so it's checked like a
+        // user-level tool and never reports "managed by MDM".
+        configCheck('Config', '~/.copilot/hooks/unbound.json', { json: true, test: refsUnbound }),
+        scriptCheck('Hook script', '~/.copilot/hooks/unbound.py'),
+        envCheck('API key env', 'UNBOUND_COPILOT_API_KEY', apiKey),
+      ],
+    },
+    // Gemini CLI is intentionally omitted here — it isn't part of `setup --all`
+    // and has no managed directory. Add it back when its scope is settled.
+  ];
+}
+
+function statusOf(checks) {
+  const structural = checks.filter((c) => c.kind === 'structural');
+  const present = structural.filter((c) => c.ok);
+  if (present.length === 0) return 'not-installed';
+  if (present.length === structural.length && checks.every((c) => c.ok)) return 'healthy';
+  return 'tampered';
+}
+
+function detectVariant(variant) {
+  const checks = variant.checks();
+  return { key: variant.key, label: variant.label, family: variant.family, mode: variant.mode, status: statusOf(checks), checks };
+}
+
+// Collapse the per-(tool,mode) variants to one entry per product family. Picks
+// the installed/tampered mode if any; otherwise reports managed-by-mdm or
+// not-installed. This is what both `doctor` and `status` render.
+// `_mdmDirs` (test-only) overrides the system MDM directories per family so the
+// org-managed scenarios can be exercised without writing under /Library or /etc.
+function detectTools({ gatewayUrl, apiKey, _mdmDirs } = {}) {
+  const variants = buildVariants(gatewayUrl, apiKey).map(detectVariant);
+  const families = [];
+  const seen = new Set();
+  for (const v of variants) {
+    if (seen.has(v.family)) continue;
+    seen.add(v.family);
+    const sameFamily = variants.filter((x) => x.family === v.family);
+    const present = sameFamily.filter((x) => x.status !== 'not-installed');
+    if (present.length) {
+      // Prefer a tampered variant so a conflicting/partial install surfaces (and
+      // `--fix` reinstalls it). Flag when more than one mode is present at once.
+      const active = present.find((x) => x.status === 'tampered') || present[0];
+      if (present.length > 1) active.conflict = true;
+      active.label = active.label.replace(/ \(.*\)$/, ''); // mode is shown via .mode
+      families.push(active);
+    } else {
+      const family = v.family;
+      const label = v.label.replace(/ \(.*\)$/, '');
+      const mdm = mdmDetect(family, _mdmDirs && _mdmDirs[family]);
+      if (mdm.status === 'healthy') {
+        families.push({ key: family, label, family, mode: null, status: 'managed-by-mdm', checks: mdm.checks, scope: 'mdm' });
+      } else if (mdm.status === 'tampered') {
+        families.push({ key: family, label, family, mode: null, status: 'tampered', checks: mdm.checks, scope: 'mdm' });
+      } else {
+        families.push({ key: family, label, family, mode: null, status: 'not-installed', checks: [] });
+      }
+    }
+  }
+  return families;
+}
+
+module.exports = { detectTools, statusOf, readEnvVar, GATEWAY_DEFAULT };

package/test/doctor-exit.test.js

@@ -0,0 +1,31 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+
+const { fixExitCode } = require('../src/commands/doctor');
+
+// `--fix` exit code: a CI gate runs `unbound doctor --fix` and reads the exit code.
+// It must be 0 only when the machine is actually clean after the repair.
+
+test('fixExitCode: spawn/signal error (null status) → 1', () => {
+  assert.equal(fixExitCode(null, false, false), 1);
+  assert.equal(fixExitCode(null, true, true), 1);
+});
+
+test('fixExitCode: setup failure propagates its status', () => {
+  assert.equal(fixExitCode(2, false, false), 2);
+  assert.equal(fixExitCode(1, true, true), 1);
+});
+
+test('fixExitCode: non-root, user tools fixed but MDM still tampered → 1 (not clean)', () => {
+  assert.equal(fixExitCode(0, false, true), 1);
+});
+
+test('fixExitCode: non-root, nothing org-managed left → 0 (clean)', () => {
+  assert.equal(fixExitCode(0, false, false), 0);
+});
+
+test('fixExitCode: root run repaired the MDM tools too → 0 (clean, no false failure)', () => {
+  // Regression guard: sudo `--fix` reinstalls MDM tools, so a status-0 run is clean
+  // even though mdmRemaining was true going in.
+  assert.equal(fixExitCode(0, true, true), 0);
+});

package/test/tool-health.test.js

@@ -0,0 +1,210 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { statusOf } = require('../src/toolHealth');
+
+// --- statusOf rollup (pure): structural artifacts decide install-state; aux
+// wiring only downgrades an installed tool to tampered. ---
+const chk = (kind, ok) => ({ kind, ok });
+
+test('statusOf: no structural artifact present → not-installed (dangling env ignored)', () => {
+  assert.equal(statusOf([chk('structural', false), chk('structural', false), chk('aux', true)]), 'not-installed');
+});
+
+test('statusOf: all structural + all aux present → healthy', () => {
+  assert.equal(statusOf([chk('structural', true), chk('structural', true), chk('aux', true)]), 'healthy');
+});
+
+test('statusOf: structural partially present → tampered', () => {
+  assert.equal(statusOf([chk('structural', true), chk('structural', false), chk('aux', true)]), 'tampered');
+});
+
+test('statusOf: structural complete but wiring (aux) missing → tampered', () => {
+  assert.equal(statusOf([chk('structural', true), chk('structural', true), chk('aux', false)]), 'tampered');
+});
+
+// --- detectTools integration: fabricate a tool's on-disk artifacts in a temp
+// HOME and assert the per-tool status. toolHealth reads os.homedir() at load
+// (which honors $HOME on POSIX), so we re-require it under the temp home. ---
+function withHome(fn) {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'unbound-doctor-'));
+  const origHome = process.env.HOME;
+  process.env.HOME = tmp;
+  delete require.cache[require.resolve('../src/toolHealth')];
+  try {
+    return fn(tmp, require('../src/toolHealth'));
+  } finally {
+    if (origHome === undefined) delete process.env.HOME;
+    else process.env.HOME = origHome;
+    delete require.cache[require.resolve('../src/toolHealth')];
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+function writeFile(p, content) {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, content);
+}
+
+test('detectTools: cursor with config + script + env → healthy', () => {
+  withHome((tmp, th) => {
+    const script = path.join(tmp, '.cursor', 'hooks', 'unbound.py');
+    writeFile(path.join(tmp, '.cursor', 'hooks.json'), JSON.stringify({ hooks: { PreToolUse: [{ command: script }] } }));
+    writeFile(script, '# unbound');
+    process.env.UNBOUND_CURSOR_API_KEY = 'k';
+    try {
+      const cursor = th.detectTools({ apiKey: 'k' }).find((t) => t.key === 'cursor');
+      assert.equal(cursor.status, 'healthy');
+    } finally {
+      delete process.env.UNBOUND_CURSOR_API_KEY;
+    }
+  });
+});
+
+test('detectTools: cursor config + script present but env key blank → tampered (empty != set)', () => {
+  withHome((tmp, th) => {
+    const script = path.join(tmp, '.cursor', 'hooks', 'unbound.py');
+    writeFile(path.join(tmp, '.cursor', 'hooks.json'), JSON.stringify({ hooks: { PreToolUse: [{ command: script }] } }));
+    writeFile(script, '# unbound');
+    process.env.UNBOUND_CURSOR_API_KEY = ''; // explicitly blanked, not absent
+    try {
+      const cursor = th.detectTools({ apiKey: 'k' }).find((t) => t.key === 'cursor');
+      assert.equal(cursor.status, 'tampered');
+    } finally {
+      delete process.env.UNBOUND_CURSOR_API_KEY;
+    }
+  });
+});
+
+test('detectTools: cursor env key differs from the configured key → tampered, not healthy', () => {
+  withHome((tmp, th) => {
+    const script = path.join(tmp, '.cursor', 'hooks', 'unbound.py');
+    writeFile(path.join(tmp, '.cursor', 'hooks.json'), JSON.stringify({ hooks: { PreToolUse: [{ command: script }] } }));
+    writeFile(script, '# unbound');
+    process.env.UNBOUND_CURSOR_API_KEY = 'stale-key';
+    try {
+      const cursor = th.detectTools({ apiKey: 'current-key' }).find((t) => t.key === 'cursor');
+      assert.equal(cursor.status, 'tampered');
+    } finally {
+      delete process.env.UNBOUND_CURSOR_API_KEY;
+    }
+  });
+});
+
+test('detectTools: cursor with only the hook script (no config) → tampered', () => {
+  withHome((tmp, th) => {
+    writeFile(path.join(tmp, '.cursor', 'hooks', 'unbound.py'), '# unbound');
+    const cursor = th.detectTools({ apiKey: 'k' }).find((t) => t.key === 'cursor');
+    assert.equal(cursor.status, 'tampered');
+  });
+});
+
+test('detectTools: cursor with a config that lacks the Unbound marker → not-installed', () => {
+  withHome((tmp, th) => {
+    writeFile(path.join(tmp, '.cursor', 'hooks.json'), JSON.stringify({ hooks: {} })); // no unbound.py reference
+    const cursor = th.detectTools({ apiKey: 'k' }).find((t) => t.label === 'Cursor');
+    assert.equal(cursor.status, 'not-installed');
+  });
+});
+
+test('detectTools: claude-code collapses to ONE line and reports the installed mode (gateway)', () => {
+  withHome((tmp, th) => {
+    const helper = path.join(tmp, '.claude', 'anthropic_key.sh');
+    writeFile(path.join(tmp, '.claude', 'settings.json'), JSON.stringify({ apiKeyHelper: helper }));
+    writeFile(helper, 'echo $UNBOUND_API_KEY');
+    const claude = th.detectTools({ apiKey: 'k' }).filter((t) => t.family === 'claude-code');
+    assert.equal(claude.length, 1, 'one collapsed claude-code line');
+    assert.equal(claude[0].mode, 'gateway');
+    assert.notEqual(claude[0].status, 'not-installed');
+  });
+});
+
+test('detectTools: both claude-code modes present at once → one line, flagged as a conflict', () => {
+  withHome((tmp, th) => {
+    const helper = path.join(tmp, '.claude', 'anthropic_key.sh');
+    // settings.json references BOTH an unbound.py hook AND the gateway key helper.
+    writeFile(path.join(tmp, '.claude', 'settings.json'), JSON.stringify({
+      hooks: { PreToolUse: [{ command: path.join(tmp, '.claude', 'hooks', 'unbound.py') }] },
+      apiKeyHelper: helper,
+    }));
+    const claude = th.detectTools({ apiKey: 'k' }).filter((t) => t.family === 'claude-code');
+    assert.equal(claude.length, 1, 'still one collapsed line');
+    assert.equal(claude[0].conflict, true, 'conflict flagged');
+    assert.equal(claude[0].status, 'tampered', 'prefers the tampered variant so --fix cleans it up');
+  });
+});
+
+// --- MDM (org-managed) scenarios, exercised via the _mdmDirs test override ---
+test('MDM: managed config references unbound + hook present → managed by MDM', () => {
+  withHome((tmp, th) => {
+    const mdmDir = path.join(tmp, 'mdm', 'ClaudeCode');
+    writeFile(path.join(mdmDir, 'managed-settings.json'), JSON.stringify({ hooks: { PreToolUse: [{ command: path.join(mdmDir, 'hooks', 'unbound.py') }] } }));
+    writeFile(path.join(mdmDir, 'hooks', 'unbound.py'), '#');
+    const t = th.detectTools({ apiKey: 'k', _mdmDirs: { 'claude-code': mdmDir } }).find((x) => x.family === 'claude-code');
+    assert.equal(t.status, 'managed-by-mdm');
+    assert.equal(t.scope, 'mdm');
+  });
+});
+
+test('MDM: managed config references unbound but hook missing → tampered (mdm scope)', () => {
+  withHome((tmp, th) => {
+    const mdmDir = path.join(tmp, 'mdm', 'ClaudeCode');
+    writeFile(path.join(mdmDir, 'managed-settings.json'), JSON.stringify({ hooks: { x: [{ command: path.join(mdmDir, 'hooks', 'unbound.py') }] } }));
+    const t = th.detectTools({ apiKey: 'k', _mdmDirs: { 'claude-code': mdmDir } }).find((x) => x.family === 'claude-code');
+    assert.equal(t.status, 'tampered');
+    assert.equal(t.scope, 'mdm');
+  });
+});
+
+test('MDM: a generic managed-settings.json without an unbound reference → not installed (no false positive)', () => {
+  withHome((tmp, th) => {
+    const mdmDir = path.join(tmp, 'mdm', 'ClaudeCode');
+    writeFile(path.join(mdmDir, 'managed-settings.json'), JSON.stringify({ permissions: { allow: ['*'] } }));
+    const t = th.detectTools({ apiKey: 'k', _mdmDirs: { 'claude-code': mdmDir } }).find((x) => x.label === 'Claude Code');
+    assert.equal(t.status, 'not-installed');
+  });
+});
+
+test('MDM: a user-level install takes precedence over an MDM config', () => {
+  withHome((tmp, th) => {
+    writeFile(path.join(tmp, '.claude', 'settings.json'), JSON.stringify({ hooks: { x: [{ command: path.join(tmp, '.claude', 'hooks', 'unbound.py') }] } }));
+    writeFile(path.join(tmp, '.claude', 'hooks', 'unbound.py'), '#');
+    const mdmDir = path.join(tmp, 'mdm', 'ClaudeCode');
+    writeFile(path.join(mdmDir, 'managed-settings.json'), JSON.stringify({ hooks: { x: [{ command: path.join(mdmDir, 'hooks', 'unbound.py') }] } }));
+    process.env.UNBOUND_CLAUDE_API_KEY = 'k';
+    try {
+      const t = th.detectTools({ apiKey: 'k', _mdmDirs: { 'claude-code': mdmDir } }).find((x) => x.family === 'claude-code');
+      assert.notEqual(t.scope, 'mdm');
+      assert.equal(t.status, 'healthy');
+      assert.equal(t.mode, 'subscription');
+    } finally { delete process.env.UNBOUND_CLAUDE_API_KEY; }
+  });
+});
+
+test('codex subscription: hooks.json + script present but the feature flag is off → tampered', () => {
+  withHome((tmp, th) => {
+    writeFile(path.join(tmp, '.codex', 'hooks.json'), JSON.stringify({ hooks: { x: [{ command: path.join(tmp, '.codex', 'hooks', 'unbound.py') }] } }));
+    writeFile(path.join(tmp, '.codex', 'hooks', 'unbound.py'), '#');
+    writeFile(path.join(tmp, '.codex', 'config.toml'), 'model = "gpt-5"\n');
+    const t = th.detectTools({ apiKey: 'k' }).find((x) => x.family === 'codex');
+    assert.equal(t.status, 'tampered');
+  });
+});
+
+test('copilot has no MDM scope — even with a managed dir it never reports managed-by-mdm', () => {
+  withHome((tmp, th) => {
+    const t = th.detectTools({ apiKey: 'k', _mdmDirs: { copilot: path.join(tmp, 'mdm', 'Copilot') } }).find((x) => x.family === 'copilot');
+    assert.equal(t.status, 'not-installed');
+    assert.notEqual(t.scope, 'mdm');
+  });
+});
+
+test('only four tools are reported (Gemini CLI is omitted)', () => {
+  withHome((tmp, th) => {
+    const keys = th.detectTools({ apiKey: 'k' }).map((t) => t.family);
+    assert.deepEqual(new Set(keys), new Set(['cursor', 'claude-code', 'codex', 'copilot']));
+  });
+});

package/src/commands/whoami.js

@@ -1,65 +0,0 @@
-const config = require('../config');
-const api = require('../api');
-const output = require('../output');
-const { getDeviceSerial } = require('../device-serial');
-
-function roleFromPrivileges(privileges) {
-  if (privileges.is_admin) return 'Admin';
-  if (privileges.is_manager) return 'Manager';
-  if (privileges.is_member) return 'Member';
-  return 'Unknown';
-}
-
-function register(program) {
-  program
-    .command('whoami')
-    .description('Display the currently authenticated user, organization, and role. Requires an active login session.')
-    .addHelpText('after', `
-Output fields:
-  Email        - The authenticated user's email address
-  Organization - The organization the user belongs to
-  Role         - One of: Admin, Manager, Member
-
-Examples:
-  $ unbound whoami
-  $ unbound whoami --json
-`)
-    .option('--json', 'Output raw JSON')
-    .action(async (opts) => {
-      if (!config.isLoggedIn()) {
-        output.error('Not logged in. Run `unbound login` first.');
-        process.exitCode = 1;
-        return;
-      }
-
-      const cfg = config.readConfig();
-      const spin = output.spinner('Fetching user info...');
-      try {
-        const deviceSerial = await getDeviceSerial();
-        const privileges = await api.get('/api/v1/users/privileges/', {
-          query: { device_serial: deviceSerial },
-        });
-        spin.stop();
-        config.backfillUserInfo(privileges);
-
-        const role = roleFromPrivileges(privileges);
-        const freshCfg = config.readConfig();
-
-        if (opts.json) {
-          output.json({ email: freshCfg.email || null, organization: freshCfg.org_name || null, role });
-          return;
-        }
-
-        output.keyValue([
-          ['Email', freshCfg.email || '-'],
-          ['Organization', freshCfg.org_name || '-'],
-          ['Role', role],
-        ]);
-      } catch (err) {
-        spin.fail(err.message);
-        process.exitCode = 1;
-      }
-    });
-}
-
-module.exports = { register };