unbound-cli 1.6.5 → 1.7.1

package/LOCAL_DEV.md

@@ -83,7 +83,7 @@ node src/index.js setup --backend-url http://localhost:8000 --frontend-url http:
 sudo node src/index.js setup --api-key <ADMIN_KEY> --all --backend-url http://localhost:8000 --frontend-url http://localhost:3000
 
 # Onboarding (combined setup + discover)
-node src/index.js onboard --api-key <USER_KEY> --discovery-key <DISCOVERY_KEY> \
+node src/index.js onboard --api-key <USER_KEY> \
     --backend-url http://localhost:8000 --frontend-url http://localhost:3000
 sudo node src/index.js onboard --api-key <ADMIN_KEY> --discovery-key <DISCOVERY_KEY> \
     --backend-url http://localhost:8000 --frontend-url http://localhost:3000
@@ -183,8 +183,7 @@ node src/index.js setup --all
 node src/index.js setup --all --api-key <key>
 
 # Onboarding (one command: login + setup --all + discover)
-node src/index.js onboard --api-key <USER_KEY> --discovery-key <DISCOVERY_KEY>
-sudo node src/index.js onboard --api-key <USER_KEY> --discovery-key <DISCOVERY_KEY>
+node src/index.js onboard --api-key <USER_KEY>
 
 # MDM onboarding (admin device enrollment, requires root — MDM scope auto-detected from sudo)
 sudo node src/index.js onboard --api-key <ADMIN_KEY> --discovery-key <DISCOVERY_KEY>

package/README.md

@@ -37,7 +37,7 @@ For new users, the fastest path from install to a fully-configured device is the
 ```bash
 # End user
 npm install -g unbound-cli
-unbound onboard --api-key <USER_KEY> --discovery-key <DISCOVERY_KEY>
+unbound onboard --api-key <USER_KEY>
 
 # Admin enrolling a device via MDM (requires root)
 sudo unbound onboard --api-key <ADMIN_KEY> --discovery-key <DISCOVERY_KEY>

package/package.json

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

package/src/api.js

@@ -141,6 +141,25 @@ function getRaw(url) {
   });
 }
 
+// WEB-4949: Probe whether a key is tenant-valid by hitting the same endpoint
+// `unbound login` uses. 200 -> valid, 401/403 -> invalid, anything else
+// (timeout, DNS, 5xx) -> unknown. Callers in status/doctor fail open on
+// 'unknown' so an offline laptop doesn't false-tamper. Short default timeout
+// (3s) keeps `unbound status` snappy even when N keys are validated in
+// parallel against a slow link.
+async function validateApiKey(apiKey, { baseUrl, timeoutMs = 3000 } = {}) {
+  if (!apiKey) return 'invalid';
+  try {
+    await request('GET', '/api/v1/users/privileges/', { apiKey, baseUrl, timeoutMs });
+    return 'valid';
+  } catch (err) {
+    if (err instanceof ApiError && (err.statusCode === 401 || err.statusCode === 403)) {
+      return 'invalid';
+    }
+    return 'unknown';
+  }
+}
+
 module.exports = {
   ApiError,
   get: (path, opts) => request('GET', path, opts),
@@ -148,4 +167,5 @@ module.exports = {
   put: (path, opts) => request('PUT', path, opts),
   del: (path, opts) => request('DELETE', path, opts),
   getRaw,
+  validateApiKey,
 };

package/src/commands/discover.js

@@ -199,7 +199,9 @@ Scans this device for installed AI coding tools (Cursor, Claude Code,
 Gemini CLI, Codex, Windsurf, Roo Code, Cline, GitHub Copilot, JetBrains,
 and more) and reports findings to the Unbound backend.
 
-The --api-key is a discovery-specific key (separate from login credentials).
+Which --api-key to use depends on scope:
+  - Single-user scan (no sudo): use your own user API key.
+  - All-users scan (sudo): use the org discovery key.
 The --domain defaults to the backend URL configured via "unbound config set-backend-url"
 (falls back to https://backend.getunbound.ai when unset).
 

package/src/commands/doctor.js

@@ -3,7 +3,7 @@ const config = require('../config');
 const api = require('../api');
 const output = require('../output');
 const { getDeviceSerial } = require('../device-serial');
-const { detectTools } = require('../toolHealth');
+const { detectTools, validateToolKeys, countValidationSkipped } = require('../toolHealth');
 const { hasRootPrivileges } = require('./setup');
 
 // Validate the stored API key against the backend. Returns one of:
@@ -61,12 +61,16 @@ Examples:
     .option('--json', 'Output raw JSON')
     .action(async (opts) => {
       try {
-        const apiKey = config.getApiKey();
         const gatewayUrl = config.getGatewayUrl();
+        const baseUrl = config.getBaseUrl();
 
         const spin = output.spinner('Running diagnostics...');
         const key = await checkApiKey();
-        const tools = detectTools({ gatewayUrl, apiKey });
+        const tools = detectTools({ gatewayUrl });
+        // WEB-4949: per-tool API keys are validated against the gateway in
+        // parallel (fail-open on network errors).
+        await validateToolKeys(tools, (k) => api.validateApiKey(k, { baseUrl }));
+        const keySkippedCount = countValidationSkipped(tools);
         spin.stop();
 
         const tampered = tools.filter((t) => t.status === 'tampered');
@@ -81,9 +85,13 @@ Examples:
               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 })),
+              checks: t.checks.map((c) => ({
+                name: c.name, ok: c.ok, kind: c.kind, detail: c.detail,
+                warn: !!c.warn, validation_skipped: !!c.validationSkipped,
+              })),
             })),
             healthy: !unhealthy,
+            key_validations_skipped: keySkippedCount,
           });
           if (unhealthy) process.exitCode = 1;
           return;
@@ -116,6 +124,11 @@ Examples:
           } else s = C.dim('○ Not set up');
           console.log(`  ${labelOf(t).padEnd(W)}   ${s}`);
         }
+        // WEB-4949: surface fail-open so CI/operators don't read an offline
+        // run as "everything verified". Mirrors the unverified-key-state line.
+        if (keySkippedCount > 0) {
+          console.log(`  ${C.dim(`Note: ${keySkippedCount} per-tool API key validation${keySkippedCount === 1 ? '' : 's'} skipped (gateway unreachable).`)}`);
+        }
         console.log('');
 
         // Fix routing. User-level tools are fixable by anyone (`unbound doctor

package/src/commands/onboard.js

@@ -27,7 +27,7 @@ function register(program) {
     )
     .option('--api-key <key>', 'API key (user key, or admin key when run with sudo). Falls back to UNBOUND_API_KEY or a stored `unbound login` key)')
     .addOption(new Option('--admin-api-key <key>', 'Alias for --api-key (back-compat)').hideHelp())
-    .option('--discovery-key <key>', 'Discovery API key for device scan (or set UNBOUND_DISCOVERY_KEY)')
+    .option('--discovery-key <key>', 'Org discovery key for the device scan — required only under sudo (MDM/org scope); ignored for per-user onboarding (or set UNBOUND_DISCOVERY_KEY)')
     .option('--domain <url>', 'Backend URL for discovery (defaults to configured backend)')
     .option('--set-cron', 'Set up a daily background job to keep governance up to date (under sudo, schedules a discovery scan only — not a full tool re-install)')
     .option('--backfill', 'Seed historical Claude Code / Codex / Copilot sessions from local transcripts into Unbound analytics (Cursor skipped automatically)')
@@ -37,24 +37,27 @@ function register(program) {
     .addHelpText('after', `
 Runs the full onboarding flow, auto-detecting scope from your privileges:
   With sudo, installs the MDM tool bundle (${MDM_ALL_TOOLS.join(', ')}) and
-  scans all users on the device. Without sudo, installs the user bundle
-  (${ALL_TOOLS.join(', ')}) and scans the current user.
+  scans all users on the device using --discovery-key. Without sudo, installs
+  the user bundle (${ALL_TOOLS.join(', ')}) and scans the current user using
+  your own API key.
 
   1. Logs in / resolves the API key (or reuses a stored \`unbound login\` key
      when --api-key is omitted).
   2. Installs the tool bundle for the detected scope.
-  3. Runs device discovery with --discovery-key. With --set-cron, sets up a
-     recurring daily scheduled scan (cross-platform) instead of a one-time scan.
+  3. Runs device discovery. Per-user scope scans with your API key so the
+     device is attributed to you from the first report; sudo/MDM scope scans
+     all users with --discovery-key. With --set-cron, sets up a recurring daily
+     scheduled scan (cross-platform) instead of a one-time scan.
 
-The API key and discovery API key are separate keys obtained from different
-parts of the Unbound dashboard. Discovery uses its own key that is not stored
-in the CLI config.
+Per-user onboarding needs only your API key. The separate --discovery-key is
+required only under sudo (MDM/org enrollment), where the scan covers every user
+on the device and cannot be attributed from a single user's key.
 
 Examples:
-  $ unbound onboard --api-key <USER_KEY> --discovery-key <DISCOVERY_KEY>
+  $ unbound onboard --api-key <USER_KEY>
   $ sudo unbound onboard --api-key <ADMIN_KEY> --discovery-key <DISCOVERY_KEY>
-  $ unbound onboard --api-key <USER_KEY> --discovery-key <DISCOVERY_KEY> --backfill
-  $ unbound onboard --api-key <USER_KEY> --discovery-key <DISCOVERY_KEY> --set-cron
+  $ unbound onboard --api-key <USER_KEY> --backfill
+  $ unbound onboard --api-key <USER_KEY> --set-cron
 `)
     .action(telemetry.wrapAction('onboard', async (opts) => {
       const apiKeyOpt = opts.apiKey || opts.adminApiKey || process.env.UNBOUND_API_KEY;
@@ -65,8 +68,12 @@ Examples:
       telemetry.rememberSecret(discoveryKeyOpt);
       const isMdm = hasRootPrivileges();
 
-      if (!discoveryKeyOpt) {
-        output.error('--discovery-key is required (or set UNBOUND_DISCOVERY_KEY env var)');
+      // MDM/org scope (sudo) scans every user on the device, so it still needs a
+      // dedicated org discovery key. Per-user scope scans only the current user
+      // and attributes the device via that user's own API key (see Step 2), so a
+      // separate discovery key is neither needed nor used.
+      if (isMdm && !discoveryKeyOpt) {
+        output.error('--discovery-key is required under sudo (MDM/org enrollment), or set UNBOUND_DISCOVERY_KEY env var');
         process.exitCode = 1;
         return;
       }
@@ -77,6 +84,13 @@ Examples:
         process.exitCode = 1;
         return;
       }
+      // Back-compat: --discovery-key used to be required for per-user onboarding.
+      // It is now ignored in user scope — the personal API key is used for the
+      // scan so the device is attributed to the user from the first report
+      // (WEB-4891). Warn rather than fail so existing scripts keep working.
+      if (!isMdm && discoveryKeyOpt) {
+        output.warn('--discovery-key is deprecated for per-user onboarding and is ignored; your API key is used for the device scan, so the device is attributed to you. You can drop --discovery-key (and unset UNBOUND_DISCOVERY_KEY if it is set in your environment).');
+      }
 
       let setupSucceeded = false;
       let discoverySucceeded = false;
@@ -148,7 +162,11 @@ Examples:
           console.log('');
           output.info('Step 2/2: Running device discovery');
           console.log('');
-          await runDiscoveryScan({ apiKey: discoveryKeyOpt, domain: discoveryDomain });
+          // Per-user scope: scan with the user's own API key so the backend
+          // attributes the device to them at ingestion. Using the org discovery
+          // key here leaves the device unattributed until a device->user mapping
+          // resolves later (WEB-4891).
+          await runDiscoveryScan({ apiKey, domain: discoveryDomain });
           discoverySucceeded = true;
           skippedTools = skipped;
         }
@@ -168,11 +186,12 @@ Examples:
               skipRunAtLoad: true,
             });
           } else {
+            // Per-user cron re-runs `unbound onboard`, which now scans with the
+            // user's own API key — no separate discovery key to store.
             output.info('Setting up daily scheduled run');
             await setupScheduledRun({
               command: 'onboard',
               apiKey: apiKeyOpt || config.getApiKey(),
-              discoveryKey: discoveryKeyOpt,
               domain: discoveryDomain,
               skipRunAtLoad: true,
             });
@@ -199,11 +218,15 @@ Examples:
           if (isMdm) {
             console.error(`  Re-run just the scheduled scan with: sudo unbound discover --api-key <DISCOVERY_KEY> --set-cron${suffix}`);
           } else {
-            console.error(`  Re-run cron setup with: unbound onboard --api-key <KEY> --discovery-key <DISCOVERY_KEY> --set-cron${suffix}`);
+            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(`  Re-run discovery only with: ${sudo}unbound discover --api-key <DISCOVERY_KEY>${suffix}`);
+          if (isMdm) {
+            console.error(`  Re-run discovery only with: sudo unbound discover --api-key <DISCOVERY_KEY>${suffix}`);
+          } else {
+            console.error(`  Re-run discovery only with: unbound discover --api-key <KEY>${suffix}`);
+          }
         }
         process.exitCode = 1;
       }

package/src/commands/status.js

@@ -2,7 +2,7 @@ const config = require('../config');
 const api = require('../api');
 const output = require('../output');
 const { getDeviceSerial } = require('../device-serial');
-const { detectTools } = require('../toolHealth');
+const { detectTools, validateToolKeys, countValidationSkipped } = require('../toolHealth');
 
 function roleFromPrivileges(p) {
   if (!p) return null;
@@ -76,8 +76,17 @@ Examples:
         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');
+        // WEB-4949: per-tool API keys are validated against the gateway in
+        // parallel (fail-open on network errors) — see toolHealth.validateToolKeys.
+        // The spinner is essential — N keys × 3s timeout on a slow link would
+        // otherwise look like the command had frozen.
+        const baseUrl = config.getBaseUrl();
+        const detected = detectTools({ gatewayUrl: config.getGatewayUrl() });
+        const keySpin = output.spinner('Validating tool API keys...');
+        await validateToolKeys(detected, (k) => api.validateApiKey(k, { baseUrl }));
+        keySpin.stop();
+        const connected = detected.filter((t) => t.status !== 'not-installed');
+        const skippedCount = countValidationSkipped(connected);
 
         if (opts.json) {
           const cfg = loggedIn ? config.readConfig() : {};
@@ -92,6 +101,7 @@ Examples:
             gateway_url: config.getGatewayUrl(),
             api_status: connectivity,
             connected_tools: connected.map((t) => ({ tool: t.key, label: t.label, mode: t.mode, status: t.status })),
+            key_validations_skipped: skippedCount,
           });
           return;
         }
@@ -113,6 +123,11 @@ Examples:
             console.log(`  ${mark} ${t.label}${mode}${note}`);
           }
         }
+        // WEB-4949: tell the operator when fail-open masked a real check.
+        // Without this, an offline run looks identical to a fully-validated one.
+        if (skippedCount > 0) {
+          console.log(`  ${C.dim(`Note: ${skippedCount} API key validation${skippedCount === 1 ? '' : 's'} skipped (gateway unreachable).`)}`);
+        }
         console.log('');
       } catch (err) {
         output.error(err.message);

package/src/index.js

@@ -55,7 +55,7 @@ AUTHENTICATION
   $ unbound config urls <gateway-url> <frontend-url> <backend-url>
 
 ONBOARDING (one-step install + discover; scope auto-detected from sudo)
-  $ unbound onboard --api-key <USER_KEY> --discovery-key <DISCOVERY_KEY>         Current user
+  $ unbound onboard --api-key <USER_KEY>                                         Current user
   $ sudo unbound onboard --api-key <ADMIN_KEY> --discovery-key <DISCOVERY_KEY>   All users (MDM)
 
 TOOL SETUP

package/src/toolHealth.js

@@ -126,6 +126,26 @@ function scriptCheck(label, file, kind = 'structural') {
   return { name: label, ok, kind, detail: ok ? file : `not found (${file})`, summary: `${label.toLowerCase()} missing` };
 }
 
+// Set-but-non-empty check + value capture, intended for per-tool API key envs.
+// WEB-4949: API keys are not equality-checked against the stored
+// `config.api_key` — per-tool keys can legitimately differ for the same tenant
+// (different keys for Cursor vs Codex, dashboard-rotated key, etc.). The
+// `keyCheck`/`envName`/`value` tags let `validateToolKeys` revisit each
+// captured value and flip the check not-ok when the gateway rejects it.
+function envKeyCheck(label, name, kind = 'aux') {
+  const base = label.replace(/ env$/, '');
+  const r = readEnvVar(name);
+  if (!r.found || !r.value) {
+    return { name: label, ok: false, kind, detail: `${name} is not set`, summary: `${base} not set` };
+  }
+  return {
+    name: label, ok: true, kind,
+    detail: `${name} set (${r.source})`,
+    summary: `${base} set`,
+    keyCheck: true, envName: name, value: r.value,
+  };
+}
+
 function envCheck(label, name, expected, kind = 'aux') {
   const base = label.replace(/ env$/, '');
   const r = readEnvVar(name);
@@ -217,8 +237,11 @@ function refsUnbound(obj) {
 }
 
 // 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, binaryPath) {
+// collapsed view shows a single line per product. `apiKey` is no longer
+// equality-checked (WEB-4949) — per-tool keys can legitimately differ from
+// the stored login key. Use `validateToolKeys` post-detection to verify each
+// captured key against the gateway.
+function buildVariants(gatewayUrl, binaryPath) {
   const gw = (gatewayUrl || GATEWAY_DEFAULT).replace(/\/+$/, ''); // setup rstrips too
   return [
     {
@@ -226,7 +249,7 @@ function buildVariants(gatewayUrl, apiKey, binaryPath) {
       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),
+        envKeyCheck('API key env', 'UNBOUND_CURSOR_API_KEY'),
       ],
     },
     {
@@ -234,7 +257,7 @@ function buildVariants(gatewayUrl, apiKey, binaryPath) {
       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),
+        envKeyCheck('API key env', 'UNBOUND_CLAUDE_API_KEY'),
       ],
     },
     {
@@ -242,7 +265,9 @@ function buildVariants(gatewayUrl, apiKey, binaryPath) {
       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),
+        envKeyCheck('API key env', 'UNBOUND_API_KEY'),
+        // Gateway URL is a real equality check — the hook must point at the
+        // configured backend; tenants don't generate different gateway URLs.
         envCheck('Gateway URL env', 'ANTHROPIC_BASE_URL', gw),
       ],
     },
@@ -252,14 +277,14 @@ function buildVariants(gatewayUrl, apiKey, binaryPath) {
         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),
+        envKeyCheck('API key env', 'UNBOUND_CODEX_API_KEY'),
       ],
     },
     {
       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),
+        envKeyCheck('API key env', 'OPENAI_API_KEY'),
       ],
     },
     {
@@ -276,7 +301,7 @@ function buildVariants(gatewayUrl, apiKey, binaryPath) {
         const checks = [configCheck('Config', '~/.copilot/hooks/unbound.json', { json: true, test: refsUnbound })];
         if (hasBinary) checks.push(scriptCheck('Hook binary', binaryPath || BINARY_PATH));
         else checks.push(scriptCheck('Hook script', '~/.copilot/hooks/unbound.py'));
-        checks.push(envCheck('API key env', 'UNBOUND_COPILOT_API_KEY', apiKey));
+        checks.push(envKeyCheck('API key env', 'UNBOUND_COPILOT_API_KEY'));
         return checks;
       },
     },
@@ -305,8 +330,8 @@ function detectVariant(variant) {
 // org-managed scenarios can be exercised without writing under /Library or /etc.
 // `_binaryPath` (test-only) overrides the system hook-binary path so binary-mode
 // scenarios can be exercised without writing under /opt.
-function detectTools({ gatewayUrl, apiKey, _mdmDirs, _binaryPath } = {}) {
-  const variants = buildVariants(gatewayUrl, apiKey, _binaryPath).map(detectVariant);
+function detectTools({ gatewayUrl, _mdmDirs, _binaryPath } = {}) {
+  const variants = buildVariants(gatewayUrl, _binaryPath).map(detectVariant);
   const families = [];
   const seen = new Set();
   for (const v of variants) {
@@ -337,4 +362,80 @@ function detectTools({ gatewayUrl, apiKey, _mdmDirs, _binaryPath } = {}) {
   return families;
 }
 
-module.exports = { detectTools, statusOf, readEnvVar, GATEWAY_DEFAULT };
+// WEB-4949: Validate each tool's captured env-var key against the gateway and
+// mutate the corresponding `keyCheck: true` entries in place. Fail-open: an
+// 'unknown' verdict (network error, timeout, 5xx) leaves the check healthy
+// but tags it `validationSkipped: true` so status/doctor can surface
+// "gateway unreachable — N key(s) not verified" instead of silently lying.
+// Unique keys are fanned out in parallel so N tools share one round-trip's
+// worth of latency. `validateKey` is
+// `(key) => Promise<'valid'|'invalid'|'unknown'>` — injected from
+// status/doctor (which wrap `api.validateApiKey`) so tests can stub it. A
+// validator that throws is coerced to 'unknown' so a regression in the api
+// client can never wipe out the local-state view callers depend on.
+async function validateToolKeys(tools, validateKey) {
+  if (!tools?.length) return tools;
+  const unique = new Set();
+  for (const t of tools) {
+    for (const c of t.checks || []) {
+      if (c.keyCheck && c.value) unique.add(c.value);
+    }
+  }
+  if (!unique.size) return tools;
+  const entries = await Promise.all(
+    [...unique].map(async (k) => {
+      try {
+        return [k, await validateKey(k)];
+      } catch {
+        return [k, 'unknown'];
+      }
+    })
+  );
+  const validity = new Map(entries);
+  for (const t of tools) {
+    if (!t.checks?.length) continue;
+    let okFlipped = false;
+    for (const c of t.checks) {
+      if (!c.keyCheck) continue;
+      const verdict = validity.get(c.value);
+      if (verdict === 'invalid') {
+        c.ok = false;
+        c.warn = true;
+        const base = c.name.replace(/ env$/, '');
+        c.summary = `${base} invalid`;
+        c.detail = `${c.envName} set but not valid for this tenant`;
+        okFlipped = true;
+      } else if (verdict === 'unknown') {
+        // Stay healthy (fail-open), but record the skip so the caller can
+        // surface it. Without this tag the operator can't tell an offline
+        // run from a fully-validated one — that's the WEB-4922 lesson.
+        // Does NOT flip `ok`, so the `statusOf` re-derivation stays guarded.
+        c.validationSkipped = true;
+        c.detail = `${c.detail}; validation skipped — gateway unreachable`;
+      }
+    }
+    // ONLY re-derive when a check's `ok` actually flipped. Without this guard,
+    // `statusOf` overwrites `managed-by-mdm` (the sentinel `detectTools` sets
+    // for MDM-managed tools) back to a plain 'healthy', erasing the MDM badge
+    // from both human + JSON output. MDM checks have no `keyCheck` entries so
+    // this guard naturally excludes them — no MDM-specific carve-out needed.
+    if (okFlipped) t.status = statusOf(t.checks);
+  }
+  return tools;
+}
+
+// WEB-4949: Convenience accessor for status/doctor. Returns the count of
+// `keyCheck` entries flagged `validationSkipped: true` across all tools.
+// Used to render a one-line "N key(s) not verified" note when the validator
+// failed open. Returns 0 when validation ran cleanly or no key checks exist.
+function countValidationSkipped(tools) {
+  let n = 0;
+  for (const t of tools || []) {
+    for (const c of t.checks || []) {
+      if (c.keyCheck && c.validationSkipped) n += 1;
+    }
+  }
+  return n;
+}
+
+module.exports = { detectTools, statusOf, readEnvVar, validateToolKeys, countValidationSkipped, GATEWAY_DEFAULT };

package/test/api-validate-key.test.js

@@ -0,0 +1,107 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const http = require('http');
+const api = require('../src/api');
+
+// WEB-4949: validateApiKey wraps the /api/v1/users/privileges/ probe with the
+// fail-open semantics status/doctor need. Stand up a real local HTTP server
+// per case so we exercise the actual transport (timeout, status mapping, no
+// throw on 4xx) instead of mocking the api client.
+function withServer(handler, fn) {
+  return new Promise((resolve, reject) => {
+    const server = http.createServer(handler);
+    server.listen(0, '127.0.0.1', async () => {
+      const { address, port } = server.address();
+      const baseUrl = `http://${address}:${port}`;
+      try {
+        await fn(baseUrl);
+        resolve();
+      } catch (err) {
+        reject(err);
+      } finally {
+        server.close();
+      }
+    });
+    server.on('error', reject);
+  });
+}
+
+test('validateApiKey: 200 → valid', async () => {
+  await withServer(
+    (_req, res) => { res.writeHead(200, { 'content-type': 'application/json' }); res.end('{}'); },
+    async (baseUrl) => {
+      assert.equal(await api.validateApiKey('k', { baseUrl }), 'valid');
+    }
+  );
+});
+
+test('validateApiKey: 401 → invalid', async () => {
+  await withServer(
+    (_req, res) => { res.writeHead(401, { 'content-type': 'application/json' }); res.end('{"error":"bad key"}'); },
+    async (baseUrl) => {
+      assert.equal(await api.validateApiKey('k', { baseUrl }), 'invalid');
+    }
+  );
+});
+
+test('validateApiKey: 403 → invalid', async () => {
+  await withServer(
+    (_req, res) => { res.writeHead(403); res.end(''); },
+    async (baseUrl) => {
+      assert.equal(await api.validateApiKey('k', { baseUrl }), 'invalid');
+    }
+  );
+});
+
+test('validateApiKey: 500 → unknown (fail-open)', async () => {
+  await withServer(
+    (_req, res) => { res.writeHead(500); res.end(''); },
+    async (baseUrl) => {
+      assert.equal(await api.validateApiKey('k', { baseUrl }), 'unknown');
+    }
+  );
+});
+
+test('validateApiKey: timeout → unknown (fail-open)', async () => {
+  // Handler never responds; short timeout forces the unknown branch.
+  await withServer(
+    (_req, _res) => { /* hang */ },
+    async (baseUrl) => {
+      assert.equal(await api.validateApiKey('k', { baseUrl, timeoutMs: 100 }), 'unknown');
+    }
+  );
+});
+
+test('validateApiKey: connection refused → unknown (fail-open)', async () => {
+  // Pick a localhost port nothing is listening on. 1 is reliably refused.
+  assert.equal(
+    await api.validateApiKey('k', { baseUrl: 'http://127.0.0.1:1', timeoutMs: 500 }),
+    'unknown'
+  );
+});
+
+test('validateApiKey: missing key → invalid without a network call', async () => {
+  // baseUrl points at a dead port; if we made a network call the test would
+  // hang or take ages. A short timeout would also work but is unnecessary
+  // because the function should short-circuit before any IO.
+  assert.equal(await api.validateApiKey('', { baseUrl: 'http://127.0.0.1:1' }), 'invalid');
+  assert.equal(await api.validateApiKey(null, { baseUrl: 'http://127.0.0.1:1' }), 'invalid');
+  assert.equal(await api.validateApiKey(undefined, { baseUrl: 'http://127.0.0.1:1' }), 'invalid');
+});
+
+test('validateApiKey: sends the key as bearer + hits /api/v1/users/privileges/', async () => {
+  let observedAuth = null;
+  let observedPath = null;
+  await withServer(
+    (req, res) => {
+      observedAuth = req.headers['authorization'];
+      observedPath = req.url;
+      res.writeHead(200, { 'content-type': 'application/json' }); res.end('{}');
+    },
+    async (baseUrl) => {
+      await api.validateApiKey('sk-abc123', { baseUrl });
+      assert.equal(observedAuth, 'Bearer sk-abc123');
+      assert.ok(observedPath.startsWith('/api/v1/users/privileges/'), observedPath);
+    }
+  );
+});

package/test/onboard-cron.test.js

@@ -100,7 +100,9 @@ test('onboard schedules via setupScheduledRun with command onboard', () => {
   );
 });
 
-test('onboard passes both apiKey and discoveryKey to setupScheduledRun', () => {
+// WEB-4891: per-user onboarding scans with the user's own API key, so the
+// per-user cron stores a single key — no separate discoveryKey.
+test('per-user onboard cron passes apiKey but NOT discoveryKey to setupScheduledRun', () => {
   const callIdx = onboardSrc.indexOf("command: 'onboard'");
   assert.notEqual(callIdx, -1, 'expected command: onboard call site in onboard.js');
   const open = onboardSrc.lastIndexOf('{', callIdx);
@@ -112,10 +114,31 @@ test('onboard passes both apiKey and discoveryKey to setupScheduledRun', () => {
   }
   const callArgs = onboardSrc.slice(open, close + 1);
   assert.ok(callArgs.includes('apiKey'), 'setupScheduledRun call must include apiKey');
-  assert.ok(callArgs.includes('discoveryKey'), 'setupScheduledRun call must include discoveryKey');
+  assert.ok(!callArgs.includes('discoveryKey'), 'per-user onboard cron must NOT pass a discoveryKey (single-key onboarding, WEB-4891)');
   assert.ok(!callArgs.toLowerCase().includes('backfill'), 'setupScheduledRun call must not include backfill');
 });
 
+// WEB-4891 core fix: the per-user discovery scan must run with the user's own
+// API key so the backend attributes the device to them at ingestion. Only the
+// MDM (sudo) branch — which scans every user and cannot be attributed from one
+// user's key — may scan with the org discovery key.
+test('per-user discovery scans with the user key; only MDM uses the discovery key', () => {
+  const userBranchStart = onboardSrc.indexOf('const apiKey = config.getApiKey();');
+  assert.notEqual(userBranchStart, -1, 'expected the per-user branch in onboard.js');
+  const userBranch = onboardSrc.slice(userBranchStart);
+  assert.match(
+    userBranch,
+    /runDiscoveryScan\(\{\s*apiKey\s*,/,
+    'per-user onboarding must scan with the user apiKey, not the org discovery key'
+  );
+  const discoveryKeyScans = (onboardSrc.match(/runDiscoveryScan\(\{\s*apiKey:\s*discoveryKeyOpt/g) || []).length;
+  assert.equal(
+    discoveryKeyScans,
+    1,
+    'exactly one runDiscoveryScan (the MDM branch) may use the org discovery key'
+  );
+});
+
 test('onboard imports setupScheduledRun from ../scheduled', () => {
   assert.match(
     onboardSrc,

package/test/onboard-scope.test.js

@@ -35,7 +35,7 @@ test('hasRootPrivileges: false when effective uid is not 0 (no sudo)', () => {
 // ---- 2. onboard routes by detected scope ----
 // Reloads the module graph with stubbed deps so we can observe which bundle
 // helper the single `onboard` command invokes.
-async function runOnboard(isRoot, { setCron = false } = {}) {
+async function runOnboard(isRoot, { setCron = false, discoveryKey = 'd' } = {}) {
   for (const m of [
     '../src/commands/onboard',
     '../src/commands/setup',
@@ -48,7 +48,7 @@ async function runOnboard(isRoot, { setCron = false } = {}) {
     delete require.cache[require.resolve(m)];
   }
 
-  const calls = { mdm: 0, user: 0, discovery: 0, loggedIn: 0, cron: null };
+  const calls = { mdm: 0, user: 0, discovery: 0, loggedIn: 0, cron: null, warns: [] };
   const setup = require('../src/commands/setup');
   const discover = require('../src/commands/discover');
   const auth = require('../src/auth');
@@ -59,7 +59,7 @@ async function runOnboard(isRoot, { setCron = false } = {}) {
   setup.hasRootPrivileges = () => isRoot;
   setup.runMdmSetupAllBundle = async () => { calls.mdm++; return { ok: true, skipped: [] }; };
   setup.runSetupAllBundle = async () => { calls.user++; return { ok: true, skipped: [] }; };
-  discover.runDiscoveryScan = async () => { calls.discovery++; };
+  discover.runDiscoveryScan = async (o) => { calls.discovery++; calls.discoveryArgs = o; };
   auth.ensureLoggedIn = async () => { calls.loggedIn++; };
   scheduled.setupScheduledRun = async (o) => { calls.cron = o; };
   config.setUrls = () => ({});
@@ -68,13 +68,15 @@ async function runOnboard(isRoot, { setCron = false } = {}) {
   config.getFrontendUrl = () => 'https://f.acme';
   config.getGatewayUrl = () => 'https://g.acme';
   config.isLoggedIn = () => true;
-  for (const k of ['info', 'success', 'error', 'warn']) output[k] = () => {};
+  for (const k of ['info', 'success', 'error']) output[k] = () => {};
+  output.warn = (m) => calls.warns.push(m);
 
   const { register } = require('../src/commands/onboard');
   const program = new Command();
   program.exitOverride();
   register(program);
-  const argv = ['node', 'unbound', 'onboard', '--api-key', 'k', '--discovery-key', 'd'];
+  const argv = ['node', 'unbound', 'onboard', '--api-key', 'k'];
+  if (discoveryKey) argv.push('--discovery-key', discoveryKey);
   if (setCron) argv.push('--set-cron');
   await program.parseAsync(argv);
   return calls;
@@ -86,6 +88,7 @@ test('onboard with sudo/root → installs the MDM bundle (all users), no login',
   assert.equal(calls.user, 0, 'user bundle NOT installed');
   assert.equal(calls.loggedIn, 0, 'MDM scope does not run ensureLoggedIn');
   assert.equal(calls.discovery, 1, 'discovery still runs');
+  assert.equal(calls.discoveryArgs.apiKey, 'd', 'MDM scope scans with the org discovery key');
 });
 
 test('onboard without sudo → logs in and installs the user bundle', async () => {
@@ -94,6 +97,9 @@ test('onboard without sudo → logs in and installs the user bundle', async () =
   assert.equal(calls.mdm, 0, 'MDM bundle NOT installed');
   assert.equal(calls.loggedIn, 1, 'user scope runs ensureLoggedIn');
   assert.equal(calls.discovery, 1, 'discovery still runs');
+  // WEB-4891: per-user scan uses the resolved user key, NOT the org discovery key.
+  assert.equal(calls.discoveryArgs.apiKey, 'resolved-key', 'user scope scans with the user API key');
+  assert.notEqual(calls.discoveryArgs.apiKey, 'd', 'user scope must NOT scan with the discovery key');
 });
 
 // --set-cron under sudo schedules discovery only (not a daily full MDM
@@ -110,5 +116,34 @@ test('onboard --set-cron without sudo → schedules the full onboard run', async
   const calls = await runOnboard(false, { setCron: true });
   assert.ok(calls.cron, 'a scheduled run was set up');
   assert.equal(calls.cron.command, 'onboard', 'user scope keeps the full onboard cron');
-  assert.equal(calls.cron.discoveryKey, 'd', 'discovery key forwarded for the onboard cron');
+  // WEB-4891: the per-user cron re-runs onboard, which scans with the user's own
+  // key — so the user key is stored and no separate discovery key is.
+  assert.equal(calls.cron.apiKey, 'k', 'per-user cron stores the user API key');
+  assert.equal(calls.cron.discoveryKey, undefined, 'per-user onboard cron no longer forwards a discovery key');
+});
+
+// WEB-4891: the clean per-user path passes NO --discovery-key. It must work
+// without error, scan with the user key, and emit no deprecation warning.
+test('onboard without sudo and without --discovery-key → clean single-key path', async () => {
+  const calls = await runOnboard(false, { discoveryKey: null });
+  assert.equal(calls.user, 1, 'user bundle installed');
+  assert.equal(calls.discovery, 1, 'discovery runs');
+  assert.equal(calls.discoveryArgs.apiKey, 'resolved-key', 'scans with the user API key');
+  assert.equal(
+    calls.warns.filter((w) => /discovery-key is deprecated/.test(w)).length,
+    0,
+    'no deprecation warning when --discovery-key is omitted',
+  );
+});
+
+// Passing --discovery-key in user scope is deprecated: it is ignored (the scan
+// still uses the user key) and exactly one deprecation warning is emitted.
+test('onboard without sudo WITH --discovery-key → ignored + deprecation warning', async () => {
+  const calls = await runOnboard(false, { discoveryKey: 'd' });
+  assert.equal(calls.discoveryArgs.apiKey, 'resolved-key', 'still scans with the user API key, not the discovery key');
+  assert.equal(
+    calls.warns.filter((w) => /discovery-key is deprecated/.test(w)).length,
+    1,
+    'emits exactly one deprecation warning',
+  );
 });

package/test/tool-health.test.js

@@ -79,15 +79,19 @@ test('detectTools: cursor config + script present but env key blank → tampered
   });
 });
 
-test('detectTools: cursor env key differs from the configured key → tampered, not healthy', () => {
+// WEB-4949: per-tool API keys are no longer equality-checked against the
+// stored config key — different valid keys for the same tenant are legal.
+// detectTools just verifies presence; validateToolKeys (separately tested
+// below) handles tenant-validity.
+test('detectTools: cursor env key differs from the configured key → still healthy (no equality check)', () => {
   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';
+    process.env.UNBOUND_CURSOR_API_KEY = 'different-but-presumed-valid';
     try {
-      const cursor = th.detectTools({ apiKey: 'current-key' }).find((t) => t.key === 'cursor');
-      assert.equal(cursor.status, 'tampered');
+      const cursor = th.detectTools().find((t) => t.key === 'cursor');
+      assert.equal(cursor.status, 'healthy');
     } finally {
       delete process.env.UNBOUND_CURSOR_API_KEY;
     }
@@ -302,20 +306,242 @@ test('detectTools: codex binary regression (wrapper at ~/.codex/hooks/unbound.py
   });
 });
 
-test('detectTools: envCheck rc-file fallback (process.env stale, shell rc holds expected value) → healthy', () => {
+// envCheck's rc-file fallback applies to the gateway URL check
+// (ANTHROPIC_BASE_URL is still equality-checked since tenants share one
+// gateway URL). API keys are no longer equality-checked — see WEB-4949 — so
+// this test is repointed at the gateway-URL case to keep the rc-fallback
+// path covered. Stale process.env + fresh rc value → still healthy.
+test('detectTools: envCheck rc-file fallback (gateway URL env stale, rc holds the configured URL) → healthy', () => {
   withHome((tmp, th) => {
+    const settings = { apiKeyHelper: '/Users/whatever/.claude/anthropic_key.sh' };
+    writeFile(path.join(tmp, '.claude', 'settings.json'), JSON.stringify(settings));
+    writeFile(path.join(tmp, '.claude', 'anthropic_key.sh'), '#!/bin/sh\necho $UNBOUND_API_KEY\n');
+    process.env.UNBOUND_API_KEY = 'k';
+    // rcFiles() lists different files per platform; .bashrc is in both.
+    writeFile(path.join(tmp, '.bashrc'),
+      'export ANTHROPIC_BASE_URL="https://gateway.example.com"\n');
+    process.env.ANTHROPIC_BASE_URL = 'https://stale.example.com';
+    try {
+      const t = th.detectTools({ gatewayUrl: 'https://gateway.example.com' })
+        .find((x) => x.family === 'claude-code');
+      assert.equal(t.status, 'healthy');
+    } finally {
+      delete process.env.UNBOUND_API_KEY;
+      delete process.env.ANTHROPIC_BASE_URL;
+    }
+  });
+});
+
+// WEB-4949: validateToolKeys post-processes detectTools output. Verify the
+// three branches: valid → unchanged healthy; invalid → flips to tampered with
+// a meaningful summary; unknown (network error / 5xx) → fail-open healthy.
+
+test('validateToolKeys: valid verdict leaves the tool healthy', async () => {
+  await withHome(async (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');
-    // rcFiles() lists different files per platform (zprofile on darwin,
-    // zshrc/bashrc/profile on linux). Write to .bashrc — both lists include it.
-    writeFile(path.join(tmp, '.bashrc'), 'export UNBOUND_CURSOR_API_KEY="fresh-key"\n');
-    process.env.UNBOUND_CURSOR_API_KEY = 'stale-key';
+    process.env.UNBOUND_CURSOR_API_KEY = 'valid-key';
     try {
-      const t = th.detectTools({ apiKey: 'fresh-key' }).find((x) => x.key === 'cursor');
-      assert.equal(t.status, 'healthy');
+      const tools = th.detectTools();
+      await th.validateToolKeys(tools, async () => 'valid');
+      const cursor = tools.find((t) => t.key === 'cursor');
+      assert.equal(cursor.status, 'healthy');
+      const keyCheck = cursor.checks.find((c) => c.keyCheck);
+      assert.equal(keyCheck.ok, true);
+    } finally {
+      delete process.env.UNBOUND_CURSOR_API_KEY;
+    }
+  });
+});
+
+test('validateToolKeys: invalid verdict flips the tool to tampered', async () => {
+  await withHome(async (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 = 'rejected-key';
+    try {
+      const tools = th.detectTools();
+      await th.validateToolKeys(tools, async () => 'invalid');
+      const cursor = tools.find((t) => t.key === 'cursor');
+      assert.equal(cursor.status, 'tampered');
+      const keyCheck = cursor.checks.find((c) => c.keyCheck);
+      assert.equal(keyCheck.ok, false);
+      assert.match(keyCheck.summary, /invalid/);
+      assert.match(keyCheck.detail, /not valid for this tenant/);
+    } finally {
+      delete process.env.UNBOUND_CURSOR_API_KEY;
+    }
+  });
+});
+
+test('validateToolKeys: unknown verdict fails open — tool stays healthy', async () => {
+  await withHome(async (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 = 'cant-reach-gateway';
+    try {
+      const tools = th.detectTools();
+      await th.validateToolKeys(tools, async () => 'unknown');
+      const cursor = tools.find((t) => t.key === 'cursor');
+      assert.equal(cursor.status, 'healthy');
+    } finally {
+      delete process.env.UNBOUND_CURSOR_API_KEY;
+    }
+  });
+});
+
+test('validateToolKeys: distinct keys across tools are each validated once', async () => {
+  await withHome(async (tmp, th) => {
+    // Two tools with two distinct env-var values + one shared value.
+    const cursorScript = path.join(tmp, '.cursor', 'hooks', 'unbound.py');
+    writeFile(path.join(tmp, '.cursor', 'hooks.json'), JSON.stringify({ hooks: { PreToolUse: [{ command: cursorScript }] } }));
+    writeFile(cursorScript, '# unbound');
+    const copilotCfg = path.join(tmp, '.copilot', 'hooks', 'unbound.json');
+    const copilotScript = path.join(tmp, '.copilot', 'hooks', 'unbound.py');
+    writeFile(copilotCfg, JSON.stringify({ hooks: { PreToolUse: [{ command: copilotScript }] } }));
+    writeFile(copilotScript, '# unbound');
+    process.env.UNBOUND_CURSOR_API_KEY = 'key-A';
+    process.env.UNBOUND_COPILOT_API_KEY = 'key-B';
+    try {
+      const tools = th.detectTools();
+      const seen = [];
+      await th.validateToolKeys(tools, async (k) => { seen.push(k); return 'valid'; });
+      // Each unique key is validated exactly once, regardless of how many
+      // tools reference it. Order isn't asserted.
+      assert.deepEqual(new Set(seen), new Set(['key-A', 'key-B']));
+      assert.equal(seen.length, 2);
+    } finally {
+      delete process.env.UNBOUND_CURSOR_API_KEY;
+      delete process.env.UNBOUND_COPILOT_API_KEY;
+    }
+  });
+});
+
+// Real-world common case: one tool's key was rotated and the env wasn't
+// updated. The valid tool stays healthy; the invalid one flips. They share
+// the same fan-out, so a partial verdict must round-trip correctly.
+test('validateToolKeys: mixed verdicts — invalid tool flips, valid tool unchanged', async () => {
+  await withHome(async (tmp, th) => {
+    const cursorScript = path.join(tmp, '.cursor', 'hooks', 'unbound.py');
+    writeFile(path.join(tmp, '.cursor', 'hooks.json'), JSON.stringify({ hooks: { PreToolUse: [{ command: cursorScript }] } }));
+    writeFile(cursorScript, '# unbound');
+    const copilotCfg = path.join(tmp, '.copilot', 'hooks', 'unbound.json');
+    const copilotScript = path.join(tmp, '.copilot', 'hooks', 'unbound.py');
+    writeFile(copilotCfg, JSON.stringify({ hooks: { PreToolUse: [{ command: copilotScript }] } }));
+    writeFile(copilotScript, '# unbound');
+    process.env.UNBOUND_CURSOR_API_KEY = 'good';
+    process.env.UNBOUND_COPILOT_API_KEY = 'bad';
+    try {
+      const tools = th.detectTools();
+      await th.validateToolKeys(tools, async (k) => k === 'good' ? 'valid' : 'invalid');
+      const cursor = tools.find((t) => t.key === 'cursor');
+      const copilot = tools.find((t) => t.key === 'copilot');
+      assert.equal(cursor.status, 'healthy');
+      assert.equal(copilot.status, 'tampered');
+    } finally {
+      delete process.env.UNBOUND_CURSOR_API_KEY;
+      delete process.env.UNBOUND_COPILOT_API_KEY;
+    }
+  });
+});
+
+// Defensive: a validator that throws (a future api.validateApiKey bug, a
+// transport regression) must NOT take down `unbound status`/`doctor`. Each
+// thrown key is coerced to 'unknown' so the tool stays healthy and the skip
+// counter surfaces the issue to the operator.
+test('validateToolKeys: throwing validator coerces to unknown (does not propagate)', async () => {
+  await withHome(async (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 tools = th.detectTools();
+      await assert.doesNotReject(
+        th.validateToolKeys(tools, async () => { throw new Error('boom'); })
+      );
+      const cursor = tools.find((t) => t.key === 'cursor');
+      assert.equal(cursor.status, 'healthy');
+      const keyCheck = cursor.checks.find((c) => c.keyCheck);
+      assert.equal(keyCheck.validationSkipped, true);
+      assert.equal(th.countValidationSkipped(tools), 1);
+    } finally {
+      delete process.env.UNBOUND_CURSOR_API_KEY;
+    }
+  });
+});
+
+// Tag for offline surfacing — without this the operator can't distinguish a
+// fully-validated run from one that silently failed open.
+test('validateToolKeys: unknown verdict tags the check with validationSkipped + countValidationSkipped reports it', async () => {
+  await withHome(async (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 tools = th.detectTools();
+      await th.validateToolKeys(tools, async () => 'unknown');
+      assert.equal(th.countValidationSkipped(tools), 1);
+      const cursor = tools.find((t) => t.key === 'cursor');
+      const keyCheck = cursor.checks.find((c) => c.keyCheck);
+      assert.equal(keyCheck.validationSkipped, true);
+      assert.equal(keyCheck.ok, true); // fail-open: still healthy
     } finally {
       delete process.env.UNBOUND_CURSOR_API_KEY;
     }
   });
 });
+
+// Bot regression (Bugbot Medium / Greptile P1): validateToolKeys was
+// unconditionally re-running statusOf, which overwrites `managed-by-mdm`
+// (since `statusOf` doesn't know about that sentinel) back to `healthy`,
+// erasing the MDM badge from both human + JSON output. The fix is to only
+// re-derive status when a check's `ok` actually flipped.
+test('validateToolKeys: managed-by-mdm status survives validation when nothing flips', async () => {
+  await withHome(async (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 tools = th.detectTools({ _mdmDirs: { 'claude-code': mdmDir } });
+    const claude = tools.find((t) => t.family === 'claude-code');
+    assert.equal(claude.status, 'managed-by-mdm', 'pre-validation sanity');
+    // No keyCheck entries on the MDM variant, so the validator is never
+    // consulted. Status must NOT collapse to plain 'healthy'.
+    let called = false;
+    await th.validateToolKeys(tools, async () => { called = true; return 'valid'; });
+    assert.equal(claude.status, 'managed-by-mdm', 'MDM badge was overwritten');
+    assert.equal(claude.scope, 'mdm');
+    assert.equal(called, false);
+  });
+});
+
+// W2 defensive guards.
+test('validateToolKeys: null/empty tools — no throw, no validator calls', async () => {
+  const th = require('../src/toolHealth');
+  let called = false;
+  await th.validateToolKeys(null, async () => { called = true; });
+  await th.validateToolKeys(undefined, async () => { called = true; });
+  await th.validateToolKeys([], async () => { called = true; });
+  assert.equal(called, false);
+});
+
+test('validateToolKeys: missing key (no env var) → tampered without consulting the validator', async () => {
+  await withHome(async (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');
+    delete process.env.UNBOUND_CURSOR_API_KEY;
+    let called = false;
+    const tools = th.detectTools();
+    await th.validateToolKeys(tools, async () => { called = true; return 'valid'; });
+    const cursor = tools.find((t) => t.key === 'cursor');
+    assert.equal(cursor.status, 'tampered');
+    // The validator is never called for missing keys — there's no value to check.
+    assert.equal(called, false);
+  });
+});