unbound-cli 1.16.17 → 1.16.19

package/package.json

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

package/src/commands/setup.js

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

package/src/toolHealth.js

@@ -192,11 +192,17 @@ function envKeyCheck(label, name, kind = 'aux') {
   if (!r.found || !r.value) {
     return { name: label, ok: false, kind, detail: `${name} is not set`, summary: `${base} not set` };
   }
+  // Offer the rc-file keys as fallbacks so a shell opened before setup rewrote
+  // the rc (stale key in process.env) isn't misread as tampered. Only for
+  // Unbound-owned vars: a user-owned var like OPENAI_API_KEY may carry the
+  // user's personal key beside ours, and doctor must never upload that.
+  const rcFallback = name.startsWith('UNBOUND_') ? rcEnvValues(name).map((v) => v.value) : [];
+  const candidates = [...new Set([r.value, ...rcFallback].filter(Boolean))];
   return {
     name: label, ok: true, kind,
     detail: `${name} set (${r.source})`,
     summary: `${base} set`,
-    keyCheck: true, envName: name, value: r.value,
+    keyCheck: true, envName: name, value: r.value, candidates,
   };
 }
 
@@ -482,43 +488,53 @@ function detectTools({ gatewayUrl, _mdmDirs, _binaryPath } = {}) {
 // 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);
+  const verdict = new Map();
+  const check = async (keys) => {
+    const pending = [...keys].filter((k) => k && !verdict.has(k));
+    for (const [k, r] of await Promise.all(pending.map(async (k) => {
+      try { return [k, await validateKey(k)]; } catch { return [k, 'unknown']; }
+    }))) verdict.set(k, r);
+  };
+  // Validate the live value first; consult the rc-file fallbacks only when it is
+  // rejected. Avoids needless calls on the healthy path and, with the
+  // UNBOUND_-only candidate rule above, keeps rc siblings off the wire until a
+  // stale shell forces the search.
+  const live = new Set();
+  for (const t of tools) for (const c of t.checks || []) if (c.keyCheck && c.value) live.add(c.value);
+  if (!live.size) return tools;
+  await check(live);
+  const fallbacks = new Set();
+  for (const t of tools) for (const c of t.checks || []) {
+    if (c.keyCheck && c.value && verdict.get(c.value) === 'invalid') {
+      for (const v of c.candidates || []) if (v !== c.value) fallbacks.add(v);
     }
   }
-  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);
+  await check(fallbacks);
   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') {
+      if (!c.keyCheck || !c.value) continue;
+      const liveVerdict = verdict.get(c.value);
+      if (liveVerdict === 'valid') continue;
+      // rc fallbacks were fetched only when the live key was invalid.
+      const others = liveVerdict === 'invalid'
+        ? (c.candidates || []).filter((v) => v !== c.value).map((v) => verdict.get(v))
+        : [];
+      if (others.includes('valid')) continue; // a configured rc key is valid — wiring intact
+      if (liveVerdict !== 'invalid' || others.includes('unknown')) {
+        // Gateway unreachable for the live key, or for the only surviving rc
+        // candidates — fail open so an offline run isn't read as tampered.
+        c.validationSkipped = true;
+        c.detail = `${c.detail}; validation skipped — gateway unreachable`;
+      } else {
+        // Live key rejected and no configured key is valid — genuinely 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,

package/test/setup-pi.test.js

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

package/test/setup-tables.test.js

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

package/test/tool-health.test.js

@@ -641,6 +641,98 @@ test('validateToolKeys: invalid verdict flips the tool to tampered', async () =>
   });
 });
 
+test('validateToolKeys: stale live-env key invalid but rc file holds a valid key → 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');
+    // A shell opened before setup rewrote the rc carries a stale key in the
+    // live env, while the valid key sits in a shell rc. Must not be tampered.
+    // .zshrc is on both the macOS and Linux rc lists, so the test is portable.
+    writeFile(path.join(tmp, '.zshrc'), 'export UNBOUND_CURSOR_API_KEY="rc-valid-key"\n');
+    process.env.UNBOUND_CURSOR_API_KEY = 'stale-invalid-key';
+    try {
+      const seen = [];
+      const tools = th.detectTools();
+      await th.validateToolKeys(tools, async (k) => { seen.push(k); return k === 'rc-valid-key' ? 'valid' : 'invalid'; });
+      const cursor = tools.find((t) => t.key === 'cursor');
+      assert.equal(cursor.status, 'healthy');
+      assert.equal(cursor.checks.find((c) => c.keyCheck).ok, true);
+      // Guard the rc read itself: if the rc file were skipped the tool would
+      // still be tampered, so prove the rc key actually reached the validator.
+      assert.ok(seen.includes('rc-valid-key'), 'the rc-file key must be validated, not just the live env key');
+    } finally {
+      delete process.env.UNBOUND_CURSOR_API_KEY;
+    }
+  });
+});
+
+test('validateToolKeys: live-env AND rc keys both invalid → tampered (no false clean)', 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');
+    writeFile(path.join(tmp, '.zshrc'), 'export UNBOUND_CURSOR_API_KEY="rc-stale-key"\n');
+    process.env.UNBOUND_CURSOR_API_KEY = 'env-stale-key';
+    try {
+      const seen = [];
+      const tools = th.detectTools();
+      await th.validateToolKeys(tools, async (k) => { seen.push(k); return 'invalid'; });
+      const cursor = tools.find((t) => t.key === 'cursor');
+      assert.equal(cursor.status, 'tampered');
+      assert.equal(cursor.checks.find((c) => c.keyCheck).ok, false);
+      // Both candidates must be validated — otherwise a skipped rc file lets
+      // this "every candidate rejected" case pass without ever reading the rc.
+      assert.ok(seen.includes('env-stale-key') && seen.includes('rc-stale-key'), 'both the live env and rc keys must be validated');
+    } finally {
+      delete process.env.UNBOUND_CURSOR_API_KEY;
+    }
+  });
+});
+
+test('validateToolKeys: a valid live key short-circuits — rc siblings are never sent to 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');
+    // A user-owned var (e.g. OPENAI_API_KEY for codex-gateway) can carry the
+    // user's personal key exported beside ours. A valid live key must stop the
+    // check before any rc sibling is uploaded to the gateway.
+    writeFile(path.join(tmp, '.zshrc'), 'export UNBOUND_CURSOR_API_KEY="personal-secret"\nexport UNBOUND_CURSOR_API_KEY="live-valid-key"\n');
+    process.env.UNBOUND_CURSOR_API_KEY = 'live-valid-key';
+    try {
+      const seen = [];
+      const tools = th.detectTools();
+      await th.validateToolKeys(tools, async (k) => { seen.push(k); return k === 'live-valid-key' ? 'valid' : 'invalid'; });
+      const cursor = tools.find((t) => t.key === 'cursor');
+      assert.equal(cursor.status, 'healthy');
+      assert.deepEqual(seen, ['live-valid-key'], 'only the live key is validated on the healthy path');
+      assert.ok(!seen.includes('personal-secret'), 'a sibling rc key must never be sent');
+    } finally {
+      delete process.env.UNBOUND_CURSOR_API_KEY;
+    }
+  });
+});
+
+test('validateToolKeys: user-owned OPENAI_API_KEY never has its rc siblings sent, even when the live key is rejected', async () => {
+  await withHome(async (tmp, th) => {
+    writeFile(path.join(tmp, '.codex', 'config.toml'), 'openai_base_url = "https://gateway.example/v1"\n');
+    // The user's personal OpenAI key sits in the rc beside anything Unbound set.
+    // A rejected live key must NOT trigger a search that uploads the personal one.
+    writeFile(path.join(tmp, '.zshrc'), 'export OPENAI_API_KEY="sk-personal-secret"\n');
+    process.env.OPENAI_API_KEY = 'stale-live-key';
+    try {
+      const seen = [];
+      const tools = th.detectTools();
+      await th.validateToolKeys(tools, async (k) => { seen.push(k); return 'invalid'; });
+      assert.ok(!seen.includes('sk-personal-secret'), 'a personal OpenAI key in the rc must never be sent to the gateway');
+      assert.deepEqual(seen, ['stale-live-key'], 'only the live value is ever validated for a user-owned var');
+    } finally {
+      delete process.env.OPENAI_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');