unbound-cli 1.10.0 → 1.11.1

package/package.json

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

package/src/auth-pages.js

@@ -0,0 +1,178 @@
+/**
+ * HTML pages served by the local auth-callback server (src/auth.js).
+ *
+ * Design follows the unbound-fe light-surface language (matching the auth
+ * login page): #fafafb scene with a soft purple glow, white card on a gray-200
+ * border, #3d3d3d headings, brand purple #7B56FB (logo) accents, Inter-first
+ * font stack. Fully self-contained —
+ * no external fonts, scripts, or images — so the page renders identically
+ * offline and never blocks on a network fetch from a localhost one-shot server.
+ *
+ * SECURITY: email/org arrive as query params on a loopback URL anyone local
+ * can hit, so every interpolated value MUST go through escapeHtml. Never
+ * interpolate the api_key into a page.
+ */
+
+/** Minimal HTML entity escape for untrusted interpolated text. */
+function escapeHtml(value) {
+  return String(value)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+// Unbound shield mark (public/Unbound.svg in unbound-fe), inlined verbatim.
+const LOGO_SVG =
+  '<svg width="28" height="27" viewBox="0 0 24 23" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">' +
+  '<path d="M5.12736 6.88525C6.33833 14.4266 11.9473 18.6338 12.0038 18.6757L9.577 22.0419C9.28788 21.8335 2.47374 16.8456 0.979492 7.53649L5.12639 6.88525H5.12736Z" fill="#7B56FB"/>' +
+  '<path d="M18.7655 6.81787L22.8988 7.24132C22.8637 7.59566 21.9496 15.9907 14.6361 21.9394L12.0059 18.6755C17.9322 13.8559 18.7577 6.88796 18.7655 6.81787Z" fill="#7B56FB"/>' +
+  '<path d="M12.1878 1.4375C14.6214 1.4375 17.3928 1.8113 20.282 2.91325L18.7654 6.81775C11.5638 4.07068 5.19258 6.85572 5.12833 6.88492L3.42188 3.10697C3.63993 3.00865 7.20178 1.4375 12.1878 1.4375Z" fill="#7B56FB"/>' +
+  '</svg>';
+
+/**
+ * Shared page shell. `status` slots the icon block, heading, and body copy;
+ * `accent` tints the icon ring (brand purple on success, red on failure).
+ */
+function renderPage({ title, icon, heading, body }) {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${title}</title>
+<style>
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body {
+    font-family: Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+    background: #fafafb;
+    min-height: 100vh;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    padding: 24px;
+    /* Soft brand glow behind the card, echoing the light auth/login scene. */
+    background-image: radial-gradient(600px 400px at 50% 30%, rgba(123, 86, 251, 0.07), transparent 70%);
+  }
+  .card {
+    background: #ffffff;
+    border: 1px solid #e5e7eb;
+    border-radius: 16px;
+    padding: 44px 40px 36px;
+    max-width: 400px;
+    width: 100%;
+    text-align: center;
+    box-shadow: 0 16px 48px rgba(23, 19, 43, 0.08);
+    animation: rise 0.45s ease-out both;
+  }
+  .brand {
+    display: inline-flex;
+    align-items: center;
+    gap: 8px;
+    margin-bottom: 28px;
+  }
+  .brand span {
+    color: #17132B;
+    font-size: 17px;
+    font-weight: 600;
+    letter-spacing: 0.02em;
+  }
+  .icon {
+    display: block;
+    width: 64px;
+    height: 64px;
+    margin: 0 auto 20px;
+  }
+  .icon circle {
+    stroke-dasharray: 166;
+    stroke-dashoffset: 166;
+    animation: draw 0.6s 0.15s ease-out forwards;
+  }
+  .icon .mark {
+    stroke-dasharray: 48;
+    stroke-dashoffset: 48;
+    animation: draw 0.35s 0.65s ease-out forwards;
+  }
+  h1 { color: #3d3d3d; font-size: 20px; font-weight: 600; margin-bottom: 10px; }
+  p { color: #6b7280; font-size: 14px; line-height: 1.6; }
+  .identity {
+    display: inline-flex;
+    flex-direction: column;
+    gap: 2px;
+    margin: 14px 0 6px;
+    padding: 9px 18px;
+    border: 1px solid #e5e7eb;
+    border-radius: 12px;
+    background: #fafafb;
+    font-size: 13px;
+    max-width: 100%;
+    overflow-wrap: anywhere;
+  }
+  .identity b { color: #3d3d3d; font-weight: 500; }
+  .identity i { color: #6b7280; font-style: normal; font-size: 12px; }
+  @keyframes rise { from { opacity: 0; transform: translateY(10px); } to { opacity: 1; transform: none; } }
+  @keyframes draw { to { stroke-dashoffset: 0; } }
+  @media (prefers-reduced-motion: reduce) {
+    .card, .icon circle, .icon .mark { animation: none; stroke-dashoffset: 0; }
+  }
+</style>
+</head>
+<body>
+<main class="card">
+  <div class="brand">${LOGO_SVG}<span>unbound</span></div>
+  ${icon}
+  <h1>${heading}</h1>
+  ${body}
+</main>
+</body>
+</html>
+`;
+}
+
+// Stroke-drawn status icons: circle sweeps in first, then the mark.
+const CHECK_ICON =
+  '<svg class="icon" viewBox="0 0 56 56" fill="none" aria-hidden="true">' +
+  '<circle cx="28" cy="28" r="26" stroke="#7B56FB" stroke-width="2.5"/>' +
+  '<path class="mark" d="M17 29l8 8 14-16" stroke="#7B56FB" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>' +
+  '</svg>';
+
+const CROSS_ICON =
+  '<svg class="icon" viewBox="0 0 56 56" fill="none" aria-hidden="true">' +
+  '<circle cx="28" cy="28" r="26" stroke="#EF4444" stroke-width="2.5"/>' +
+  '<path class="mark" d="M20 20l16 16M36 20L20 36" stroke="#EF4444" stroke-width="3" stroke-linecap="round"/>' +
+  '</svg>';
+
+/**
+ * Success page shown after the API key lands. `email`/`orgName` are untrusted
+ * query-param values — escaped here, and omitted entirely when absent.
+ */
+function successPage({ email, orgName } = {}) {
+  // Stacked (email over org) rather than one truncating line — real tenant
+  // emails and org names routinely overflow a 400px card side by side.
+  const identityParts = [];
+  if (email) identityParts.push(`<b>${escapeHtml(email)}</b>`);
+  if (orgName) identityParts.push(`<i>${escapeHtml(orgName)}</i>`);
+  const identity = identityParts.length
+    ? `<div class="identity">${identityParts.join('')}</div>`
+    : '';
+
+  return renderPage({
+    title: 'Authentication Successful | Unbound',
+    icon: CHECK_ICON,
+    heading: 'Authentication Successful',
+    body: `${identity}<p>You can close this tab and return to the terminal.</p>`,
+  });
+}
+
+/** Failure page for a callback that arrived without an api_key. */
+function failurePage() {
+  return renderPage({
+    title: 'Authentication Failed | Unbound',
+    icon: CROSS_ICON,
+    heading: 'Authentication Failed',
+    body: '<p>You can close this tab and try again from the terminal.</p>',
+  });
+}
+
+module.exports = { successPage, failurePage, escapeHtml };

package/src/auth.js

@@ -4,6 +4,7 @@
  */
 const http = require('http');
 const { URL } = require('url');
+const authPages = require('./auth-pages');
 const config = require('./config');
 const output = require('./output');
 const api = require('./api');
@@ -35,18 +36,38 @@ async function loginWithBrowser(frontendUrl, { open: openFn } = {}) {
   // / timed-out socket so the process exits immediately. closeAllConnections is
   // Node >=18.2 — guard for the package's >=18 engine floor.
   //
-  // Calling this synchronously right after res.end() is safe ONLY because the
-  // callback responses are a few hundred bytes of static HTML — they fit in the
-  // socket send buffer, so the body reaches the kernel before closeAllConnections
-  // destroys the socket. If these pages ever grow to multi-KB (inline assets,
-  // styling), defer teardown to res.on('finish') to avoid truncating the response.
+  // The styled callback pages (auth-pages.js) are multi-KB, so calling this
+  // synchronously after res.end() could destroy the socket before the body
+  // flushes and truncate the page. Callback responses therefore defer teardown
+  // to res 'finish' (body flushed) / 'close' (client vanished mid-write) via
+  // respondAndShutdown; the guard keeps the second event and the timeout path
+  // from double-closing the server (server.close() on a closed server throws).
+  let tornDown = false;
   function shutdownServer() {
+    if (tornDown) return;
+    tornDown = true;
     server.close();
     if (typeof server.closeAllConnections === 'function') {
       server.closeAllConnections();
     }
   }
 
+  // Sends a terminal (success/failure) callback response and tears the server
+  // down once the body has actually left userspace. Resolution of the login
+  // promise stays with the caller — this only owns response + teardown.
+  function respondAndShutdown(res, statusCode, html) {
+    res.on('finish', shutdownServer);
+    res.on('close', shutdownServer);
+    res.writeHead(statusCode, { 'Content-Type': 'text/html; charset=utf-8', 'Connection': 'close' });
+    res.end(html);
+  }
+
+  // First /callback wins. Teardown is deferred until the response body
+  // flushes, which leaves a window where a second /callback could arrive and
+  // overwrite the just-persisted credentials after the login promise has
+  // settled — reject duplicates outright instead of processing them.
+  let callbackHandled = false;
+
   server.on('request', (req, res) => {
     const url = new URL(req.url, `http://localhost`);
 
@@ -56,15 +77,20 @@ async function loginWithBrowser(frontendUrl, { open: openFn } = {}) {
       return;
     }
 
+    if (callbackHandled) {
+      res.writeHead(409, { 'Connection': 'close' });
+      res.end('Callback already processed');
+      return;
+    }
+    callbackHandled = true;
+
     const apiKey = url.searchParams.get('api_key');
     const email = url.searchParams.get('email');
     const orgName = url.searchParams.get('org');
 
     if (!apiKey) {
-      res.writeHead(400, { 'Content-Type': 'text/html', 'Connection': 'close' });
-      res.end('<html><body><h2>Authentication failed</h2><p>No API key received. Please try again.</p></body></html>');
+      respondAndShutdown(res, 400, authPages.failurePage());
       callbackReject(new Error('No API key received in callback'));
-      shutdownServer();
       return;
     }
 
@@ -74,11 +100,8 @@ async function loginWithBrowser(frontendUrl, { open: openFn } = {}) {
     if (orgName) cfg.org_name = orgName;
     config.writeConfig(cfg);
 
-    res.writeHead(200, { 'Content-Type': 'text/html', 'Connection': 'close' });
-    res.end('<html><body><h2>Authentication successful!</h2><p>You can close this tab and return to the terminal.</p></body></html>');
-
+    respondAndShutdown(res, 200, authPages.successPage({ email, orgName }));
     callbackResolve({ email, orgName });
-    shutdownServer();
   });
 
   await new Promise((resolve, reject) => {

package/src/commands/setup.js

@@ -209,11 +209,15 @@ async function runPythonScript(scriptPath, args, { capture }) {
         windowsHide: true,
       });
       let out = '';
+      // stderr is also kept on its own. Python block-buffers stdout when piped,
+      // so a crash's stdout can flush after the traceback and interleave with it
+      // in `out` — failureReason needs an uncontaminated stream to read.
+      let errOut = '';
       if (capture) {
         child.stdin.on('error', () => {});
         child.stdin.end();
         child.stdout.on('data', (d) => { out += d.toString(); });
-        child.stderr.on('data', (d) => { out += d.toString(); });
+        child.stderr.on('data', (d) => { const s = d.toString(); out += s; errOut += s; });
       }
       child.on('close', (code) => {
         if (code === 0) return resolve();
@@ -223,7 +227,10 @@ async function runPythonScript(scriptPath, args, { capture }) {
         // Carry the numeric exit code so callers can report it to the failure
         // ledger (reportSetupFailure) without re-parsing the message.
         err.exitCode = code;
-        if (capture) err.setupOutput = out.trim();
+        if (capture) {
+          err.setupOutput = out.trim();
+          err.stderr = errOut.trim();
+        }
         reject(err);
       });
       child.on('error', reject);
@@ -576,6 +583,61 @@ async function runBatch(tools, runFn, { clear = false, summary = null, report =
   return { ok: true, skipped: mdmSkipped };
 }
 
+/**
+ * Picks the most useful one-line reason out of a failed setup script's captured
+ * output. The python scripts open AND close with a `====` banner, so the first
+ * line is never the reason a step failed — taking it verbatim produced the
+ * useless `Codex (gateway) (====================)` that hid a real bug. Prefer
+ * the last line the script itself flagged as an error, then the exit code.
+ *
+ * Tolerates a non-Error throw: this runs inside nuke's per-tool catch, so
+ * throwing here would abort the remaining tools instead of clearing them.
+ */
+function failureReason(err) {
+  err = err || {};
+  // Read the traceback from stderr when we have it: `out` merges both streams by
+  // arrival order, so buffered stdout can land between the header and the
+  // exception. Fall back to the merged text for callers that don't set stderr.
+  const crash = exceptionLine(err.stderr) || exceptionLine(err.message);
+  if (crash) return truncate(crash);
+  const lines = (err.message || '').split('\n').map((l) => l.trim()).filter(Boolean);
+  // Otherwise the lines the scripts themselves flag. The dotted form catches a
+  // bare exception line captured without its traceback header.
+  const flagged = lines.filter((l) => /^(❌|failed\b|error\b|exception\b|[\w.]*(error|exception):)/i.test(l));
+  const pick = flagged.length ? flagged[flagged.length - 1] : null;
+  if (pick) return truncate(pick);
+  if (err.exitCode != null) return `exit code ${err.exitCode}`;
+  return truncate(lines[0] || 'failed');
+}
+
+/**
+ * The exception a python traceback ended on, or null if `text` has no traceback.
+ * Structural rather than positional: frame lines are indented, so the exception
+ * is the first UNindented line after the header. That holds even if buffered
+ * stdout flushed into the middle of the traceback. The LAST header wins, since
+ * with chained exceptions ("During handling of the above exception...") the final
+ * one is what actually propagated.
+ */
+function exceptionLine(text) {
+  const raw = (text || '').split('\n');
+  let header = -1;
+  for (let i = 0; i < raw.length; i++) {
+    if (/^traceback\b/i.test(raw[i].trim())) header = i;
+  }
+  if (header === -1) return null;
+  const exc = raw.slice(header + 1).find(
+    (l) => l.trim() && !/^\s/.test(l) && !/^=+$/.test(l.trim())
+  );
+  return exc ? exc.trim() : null;
+}
+
+// Slice by code point, not code unit, so an 80-char cut can't split an emoji
+// or other astral character into a broken fragment.
+function truncate(s, max = 80) {
+  const chars = Array.from(s);
+  return chars.length > max ? chars.slice(0, max).join('') : s;
+}
+
 /**
  * Clears a set of tools best-effort: a single tool failing does not abort the
  * rest (unlike runBatch, which stops on first failure). Used by `uninstall`,
@@ -592,8 +654,7 @@ async function clearToolsBestEffort(layer, tools, { mdm, backendUrl, gatewayUrl,
       await runScriptPiped(tool.script, args);
       s.succeed(`${layer}: ${tool.label}`);
     } catch (err) {
-      const reason = (err.message || 'failed').split('\n')[0].slice(0, 80);
-      s.fail(`${layer}: ${tool.label} (${reason})`);
+      s.fail(`${layer}: ${tool.label} (${failureReason(err)})`);
       failed.push(tool.label);
     }
   }
@@ -1183,6 +1244,7 @@ module.exports = {
   scriptSupportsBackfill,
   resolveSetupAllTools,
   clearUnboundEnvsEverywhere,
+  failureReason,
   NUKE_ENV_VARS,
   removeBinaryInstall,
   runBinaryClear,

package/test/auth-server-leak.test.js

@@ -134,6 +134,42 @@ test('loginWithBrowser: success path resolves, sets Connection: close, and stops
   });
 });
 
+test('loginWithBrowser: duplicate /callback cannot overwrite the stored credentials', async () => {
+  await withStubbedConfig(async () => {
+    const agent = new http.Agent({ keepAlive: true });
+    const storedKeys = [];
+    config.setApiKey = (key) => { storedKeys.push(key); };
+
+    const fakeOpen = async (authUrl) => {
+      const callbackUrl = new URL(authUrl).searchParams.get('callback_url');
+      await getKeepAlive(agent, `${callbackUrl}?api_key=sk-first&email=a@b.co&org=Acme`);
+      // Second callback with a different key: teardown is deferred to the
+      // response flush, so the server may still be up — it must answer 409
+      // without persisting; once down, ECONNREFUSED is equally acceptable.
+      // Either way the first credentials must be the only ones stored.
+      try {
+        const dup = await getKeepAlive(agent, `${callbackUrl}?api_key=sk-attacker&email=x@y.z&org=Evil`);
+        assert.equal(dup.statusCode, 409, 'late duplicate must be rejected, not processed');
+      } catch (err) {
+        if (err.code !== 'ECONNREFUSED') throw err;
+      }
+    };
+
+    try {
+      const result = await withTimeout(
+        auth.loginWithBrowser('http://frontend.invalid', { open: fakeOpen }),
+        10_000,
+        'loginWithBrowser duplicate-callback path',
+      );
+
+      assert.deepEqual(result, { email: 'a@b.co', orgName: 'Acme' });
+      assert.deepEqual(storedKeys, ['sk-first'], 'only the first callback may persist credentials');
+    } finally {
+      agent.destroy();
+    }
+  });
+});
+
 test('loginWithBrowser: 404 path also sets Connection: close', async () => {
   await withStubbedConfig(async () => {
     const agent = new http.Agent({ keepAlive: true });

package/test/setup-args.test.js

@@ -3,7 +3,7 @@ const assert = require('node:assert/strict');
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
-const { buildScriptArgs, scriptSupportsBackfill, resolveSetupAllTools, clearUnboundEnvsEverywhere, NUKE_ENV_VARS, removeBinaryInstall, runBinaryClear, BINARY_INSTALL_PATHS } = require('../src/commands/setup');
+const { buildScriptArgs, scriptSupportsBackfill, resolveSetupAllTools, clearUnboundEnvsEverywhere, failureReason, NUKE_ENV_VARS, removeBinaryInstall, runBinaryClear, BINARY_INSTALL_PATHS } = require('../src/commands/setup');
 
 // shellEscape single-quotes every value, so a real key surfaces as
 // --api-key '<key>' at the head of the argv tail.
@@ -451,3 +451,170 @@ test('runBinaryClear: clear exits non-zero — fail-open (ran:true, ok:false), n
     fs.rmSync(tmp, { recursive: true, force: true });
   }
 });
+
+// The python clears open AND close with a `====` banner, so the old
+// `.split('\n')[0]` reason rendered `Codex (gateway) (==================)` —
+// which is what hid the real MDM-clear bug. Prefer the script's own error line.
+test('failureReason: skips the ==== banner and reports the script error line', () => {
+  const err = new Error([
+    '============================================================',
+    'Codex - Clearing MDM Setup',
+    '============================================================',
+    '',
+    'Clearing environment variables...',
+    'Failed to clear openai_base_url in codex config for alice',
+    '',
+    'Clear Complete!',
+  ].join('\n'));
+  err.exitCode = 1;
+  assert.equal(failureReason(err), 'Failed to clear openai_base_url in codex config for alice');
+});
+
+test('failureReason: picks the LAST flagged line when a script reports several', () => {
+  const err = new Error('Failed to clear API_KEY for 1 user(s)\nFailed to clear BASE_URL for 1 user(s)');
+  assert.equal(failureReason(err), 'Failed to clear BASE_URL for 1 user(s)');
+});
+
+test('failureReason: recognises the scripts’ ❌ prefix', () => {
+  const err = new Error('====\nSetup\n====\n❌ No user home directories found');
+  err.exitCode = 1;
+  assert.equal(failureReason(err), '❌ No user home directories found');
+});
+
+// Banner-only output with no error line must not surface "Clear Complete!" as
+// the reason — the exit code is the honest answer there.
+test('failureReason: no flagged line falls back to the exit code, not the banner', () => {
+  const err = new Error('============\nCodex - Clearing MDM Setup\n============\n\nClear Complete!');
+  err.exitCode = 2;
+  assert.equal(failureReason(err), 'exit code 2');
+});
+
+// Download failures carry no exitCode; their message is already the reason.
+test('failureReason: download failure with no exitCode keeps its own message', () => {
+  const err = new Error('Download failed: 404 Not Found');
+  err.downloadFailed = true;
+  assert.equal(failureReason(err), 'Download failed: 404 Not Found');
+});
+
+test('failureReason: empty message never returns undefined', () => {
+  assert.equal(failureReason(new Error('')), 'failed');
+  assert.equal(failureReason({}), 'failed');
+});
+
+test('failureReason: long error lines are truncated to 80 chars', () => {
+  const err = new Error('Failed to ' + 'x'.repeat(200));
+  assert.equal(failureReason(err).length, 80);
+});
+
+// A python crash prints a traceback whose LAST line is the real cause. Falling
+// back to `exit code 1` there would be less useful than the old first-line rule.
+test('failureReason: python traceback reports the exception, not the header', () => {
+  const err = new Error([
+    'Traceback (most recent call last):',
+    '  File "/tmp/setup.py", line 704, in clear_setup',
+    '    remove_codex_config_base_url_for_user(username, home_dir)',
+    "NameError: name 'home_dir' is not defined",
+  ].join('\n'));
+  err.exitCode = 1;
+  assert.equal(failureReason(err), "NameError: name 'home_dir' is not defined");
+});
+
+// exitCode 0 is falsy — must not fall through to the banner-first branch.
+// Module-qualified exception names have dots, so a name-shaped regex misses
+// them. The traceback tail is taken instead, whatever the exception is called.
+test('failureReason: dotted exception name in a traceback is reported', () => {
+  const err = new Error([
+    'Traceback (most recent call last):',
+    '  File "/tmp/setup.py", line 800, in clear_managed_hooks',
+    '    settings = json.load(f)',
+    'json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)',
+  ].join('\n'));
+  err.exitCode = 1;
+  assert.equal(failureReason(err), 'json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)');
+});
+
+// Not every python exception name contains "Error"/"Exception".
+test('failureReason: traceback tail works for a non-Error exception name', () => {
+  const err = new Error('Traceback (most recent call last):\n  File "x.py", line 1\nsocket.timeout: timed out');
+  err.exitCode = 1;
+  assert.equal(failureReason(err), 'socket.timeout: timed out');
+});
+
+// A bare exception line captured without its traceback header still flags.
+test('failureReason: dotted exception line without a traceback header flags', () => {
+  const err = new Error('====\nCodex - Clearing MDM Setup\n====\nsubprocess.CalledProcessError: returned non-zero exit status 1');
+  err.exitCode = 1;
+  assert.equal(failureReason(err), 'subprocess.CalledProcessError: returned non-zero exit status 1');
+});
+
+// Banner lines after the traceback must not be mistaken for the cause.
+test('failureReason: banner trailing a traceback is skipped', () => {
+  const err = new Error('Traceback (most recent call last):\nValueError: bad\n============');
+  err.exitCode = 1;
+  assert.equal(failureReason(err), 'ValueError: bad');
+});
+
+// runPythonScript merges stdout+stderr by arrival order and python block-buffers
+// stdout when piped, so a crash's progress lines can land AFTER the traceback.
+// Picking the tail would report "Clear Complete!" as the failure reason.
+test('failureReason: stdout flushed after the traceback does not displace the exception', () => {
+  const err = new Error([
+    'Traceback (most recent call last):',
+    '  File "/tmp/setup.py", line 9, in clear_setup',
+    'ValueError: the real cause',
+    '============================================================',
+    'Clear Complete!',
+  ].join('\n'));
+  err.exitCode = 1;
+  assert.equal(failureReason(err), 'ValueError: the real cause');
+});
+
+// stderr is captured separately precisely so interleaving can't matter.
+test('failureReason: prefers the clean stderr stream over the merged output', () => {
+  const err = new Error('====\nClearing environment variables...\nTraceback (most recent call last):\nOSError: merged and interleaved\nClear Complete!');
+  err.stderr = 'Traceback (most recent call last):\n  File "x.py", line 1\nPermissionError: from stderr';
+  err.exitCode = 1;
+  assert.equal(failureReason(err), 'PermissionError: from stderr');
+});
+
+// Chained exceptions: the LAST traceback is the one that actually propagated.
+test('failureReason: chained exceptions report the final one', () => {
+  const err = new Error([
+    'Traceback (most recent call last):',
+    '  File "x.py", line 1',
+    'ValueError: the first one',
+    'During handling of the above exception, another exception occurred:',
+    'Traceback (most recent call last):',
+    '  File "x.py", line 5',
+    'RuntimeError: the one that propagated',
+  ].join('\n'));
+  err.exitCode = 1;
+  assert.equal(failureReason(err), 'RuntimeError: the one that propagated');
+});
+
+// Indented frame lines are never the reason.
+test('failureReason: never reports an indented traceback frame line', () => {
+  const err = new Error('Traceback (most recent call last):\n  File "x.py", line 1, in f\n    boom()\nKeyError: \'gateway_url\'');
+  err.exitCode = 1;
+  assert.equal(failureReason(err), "KeyError: 'gateway_url'");
+});
+
+test('failureReason: exitCode 0 is reported, not treated as absent', () => {
+  assert.equal(failureReason({ message: '====\nCodex\n====', exitCode: 0 }), 'exit code 0');
+});
+
+// Truncation slices code points, so an emoji at the boundary stays intact.
+test('failureReason: truncation never splits an astral character', () => {
+  const reason = failureReason(new Error('Failed ' + '🔥'.repeat(100)));
+  assert.equal(Array.from(reason).length, 80);
+  assert.ok(!reason.includes('\ufffd'), reason);
+  assert.ok(/🔥$/.test(reason), reason);
+});
+
+// Runs inside nuke's per-tool catch — throwing here would abort the remaining
+// tools instead of clearing them, so a non-Error throw must not blow up.
+test('failureReason: non-Error throw (null/undefined) never throws', () => {
+  assert.equal(failureReason(null), 'failed');
+  assert.equal(failureReason(undefined), 'failed');
+  assert.equal(failureReason('a string'), 'failed');
+});