unbound-cli 1.6.4 → 1.7.0

package/src/commands/setup.js

@@ -1,13 +1,14 @@
-const { execSync, spawn, spawnSync } = require('child_process');
+const { spawn, spawnSync } = require('child_process');
 const { Option } = require('commander');
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
-const https = require('https');
 const config = require('../config');
 const output = require('../output');
+const telemetry = require('../telemetry');
 const { ensureLoggedIn } = require('../auth');
-const { confirm } = require('../utils');
+const { confirm, downloadToFile, withSecureTempFile } = require('../utils');
+const { reportSetupFailure, exitCodeForError } = require('../setup-report');
 
 const SETUP_BASE_URL = 'https://raw.githubusercontent.com/websentry-ai/setup/refs/heads/main';
 
@@ -120,16 +121,7 @@ function shellEscape(str) {
 }
 
 /**
- * Builds a shell command that curls a setup script and pipes it to python3.
- * Used on macOS/Linux/WSL. Native Windows takes the runPythonScriptWindows path.
- */
-function buildSetupCommand(scriptPath, args) {
-  const url = `${SETUP_BASE_URL}/${scriptPath}`;
-  return `curl -fsSL "${url}" | python3 - ${args}`;
-}
-
-/**
- * Reverses shellEscape back into an argv list so the Windows path can call
+ * Reverses shellEscape back into an argv list so the script runner can call
  * spawn() directly without going through a shell. Handles unquoted tokens and
  * single-quoted strings with '\'' for embedded quotes (the exact format
  * shellEscape produces).
@@ -154,64 +146,59 @@ function parsePosixArgs(s) {
 }
 
 /**
- * Downloads a URL to a local file. Follows one level of redirect (GitHub raw
- * occasionally 302s). Used only by the Windows execution path.
- */
-function downloadToFile(url, destPath) {
-  return new Promise((resolve, reject) => {
-    const request = (u, remaining) => {
-      https.get(u, (res) => {
-        if ([301, 302, 303, 307, 308].includes(res.statusCode) && res.headers.location && remaining > 0) {
-          res.resume();
-          return request(res.headers.location, remaining - 1);
-        }
-        if (res.statusCode !== 200) {
-          res.resume();
-          return reject(new Error(`Failed to download ${u}: HTTP ${res.statusCode}`));
-        }
-        const file = fs.createWriteStream(destPath);
-        res.pipe(file);
-        file.on('finish', () => file.close(resolve));
-        file.on('error', reject);
-      }).on('error', reject);
-    };
-    request(url, 3);
-  });
-}
-
-/**
- * Resolves the Python launcher to use on native Windows.
- * Prefers the `py` launcher (installed by python.org at C:\Windows\py.exe —
- * no spaces in PATH), falls back to `python` on PATH.
+ * Resolves the Python launcher to use. On native Windows prefers the `py`
+ * launcher (installed by python.org at C:\Windows\py.exe — no spaces in PATH),
+ * then `python`. On macOS/Linux/WSL prefers `python3`, then `python`.
  */
-function resolveWindowsPython() {
+function resolvePython() {
   const probe = (cmd, args) => {
     try {
       const r = spawnSync(cmd, args, { stdio: 'ignore', shell: false, windowsHide: true });
       return r.status === 0;
     } catch { return false; }
   };
-  if (probe('py', ['-3', '--version'])) return { cmd: 'py', prefix: ['-3'] };
-  if (probe('python', ['--version'])) return { cmd: 'python', prefix: [] };
+  if (isWindowsNative()) {
+    if (probe('py', ['-3', '--version'])) return { cmd: 'py', prefix: ['-3'] };
+    if (probe('python', ['--version'])) return { cmd: 'python', prefix: [] };
+    if (probe('python3', ['--version'])) return { cmd: 'python3', prefix: [] };
+    throw new Error(
+      'Python 3 not found. Install Python 3 from https://www.python.org/downloads/ ' +
+      'and make sure the "Add python.exe to PATH" option is checked during install.'
+    );
+  }
   if (probe('python3', ['--version'])) return { cmd: 'python3', prefix: [] };
+  if (probe('python', ['--version'])) return { cmd: 'python', prefix: [] };
   throw new Error(
-    'Python 3 not found. Install Python 3 from https://www.python.org/downloads/ ' +
-    'and make sure the "Add python.exe to PATH" option is checked during install.'
+    'Python 3 not found. Install Python 3 and ensure `python3` is on your PATH.'
   );
 }
 
 /**
- * Windows counterpart to the curl|python3 pipe. Downloads the script to a
- * temp file and invokes Python directly — no shell required.
+ * Downloads a setup script to a temp file and invokes Python directly — no
+ * shell, no `curl | python3` pipe. This is now the ONLY execution path on every
+ * OS (macOS/Linux/WSL and native Windows), which closes the silent-success pipe
+ * hole: a failed/partial download rejects from downloadToFile() BEFORE Python
+ * ever runs, so a broken download can no longer exit 0 as a fake success.
+ *
+ * `download failure` is surfaced as an Error carrying `downloadFailed: true` so
+ * the caller can report it to the failure ledger with the download sentinel.
  */
-async function runPythonScriptWindows(scriptPath, args, { capture }) {
+async function runPythonScript(scriptPath, args, { capture }) {
   const url = `${SETUP_BASE_URL}/${scriptPath}`;
-  const tmp = path.join(os.tmpdir(), `unbound-${Date.now()}-${Math.random().toString(36).slice(2)}.py`);
-  await downloadToFile(url, tmp);
-  const py = resolveWindowsPython();
-  try {
-    // `return await` so the resolved value (e.g. { mdmSkipped: true }) reaches
-    // the caller; the finally below still runs before the function returns.
+  // The downloaded script is executed as the current user (root under
+  // `sudo unbound …`), so it must live in a per-run PRIVATE temp dir that a
+  // local attacker can't pre-create or symlink. withSecureTempFile creates that
+  // dir (mode 0700) and removes it — and the script file — when we're done.
+  return withSecureTempFile('.py', async (tmp) => {
+    try {
+      await downloadToFile(url, tmp);
+    } catch (err) {
+      // Mark download failures so callers can distinguish them from script-exit
+      // failures (different exit-code sentinel for the failure ledger).
+      err.downloadFailed = true;
+      throw err;
+    }
+    const py = resolvePython();
     return await new Promise((resolve, reject) => {
       const child = spawn(py.cmd, [...py.prefix, tmp, ...parsePosixArgs(args)], {
         stdio: capture ? ['pipe', 'pipe', 'pipe'] : 'inherit',
@@ -230,14 +217,15 @@ async function runPythonScriptWindows(scriptPath, args, { capture }) {
         // Managed by MDM — drop any captured output and signal a skip.
         if (code === EXIT_MDM_PRESENT) return resolve({ mdmSkipped: true });
         const err = new Error(out.trim() || `Setup script failed with exit code ${code}`);
+        // 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();
         reject(err);
       });
       child.on('error', reject);
     });
-  } finally {
-    try { fs.unlinkSync(tmp); } catch { /* best-effort */ }
-  }
+  });
 }
 
 /**
@@ -285,59 +273,46 @@ function noteBackfillUnsupported(label, scriptPath) {
 }
 
 /**
- * Runs a Python setup script from the setup repo with inherited stdio (live output).
+ * Runs a Python setup script from the setup repo with inherited stdio (live
+ * output). Download-then-run on every OS (see runPythonScript) so a failed
+ * download can't masquerade as success. Returns { mdmSkipped: true } when the
+ * script signals an MDM skip; throws on download or script failure.
  */
 async function runSetupScript(scriptPath, apiKey, { clear = false, backendUrl, frontendUrl, gatewayUrl, backfill = false } = {}) {
   const args = buildScriptArgs(apiKey, { backendUrl, frontendUrl, gatewayUrl, clear, backfill });
   console.log('');
-  if (isWindowsNative()) {
-    return runPythonScriptWindows(scriptPath, args, { capture: false });
-  }
-  try {
-    execSync(buildSetupCommand(scriptPath, args), { stdio: 'inherit' });
-  } catch (err) {
-    // Managed by MDM — the script already printed its one-line notice (stdio is
-    // inherited here). Signal a skip so the caller can add the CLI notice.
-    if (err.status === EXIT_MDM_PRESENT) return { mdmSkipped: true };
-    throw new Error(`Setup script failed with exit code ${err.status || 1}. Check the output above for details.`);
-  }
+  return runPythonScript(scriptPath, args, { capture: false });
 }
 
 /**
  * Runs a setup script with piped output (captured silently for spinner display).
- * Returns a promise that resolves on success, rejects with captured output on failure.
+ * Resolves on success ({ mdmSkipped: true } on an MDM skip), rejects with the
+ * captured output on failure. Download-then-run on every OS (see
+ * runPythonScript) so the previous `curl | python3` pipe hole — where a failed
+ * download exited 0 because dash has no pipefail — is closed.
  */
 function runScriptPiped(scriptPath, args) {
-  if (isWindowsNative()) {
-    return runPythonScriptWindows(scriptPath, args, { capture: true });
-  }
-  return new Promise((resolve, reject) => {
-    const child = spawn(buildSetupCommand(scriptPath, args), {
-      shell: true,
-      stdio: ['pipe', 'pipe', 'pipe'],
-    });
-    child.stdin.on('error', () => {});
-    child.stdin.end();
-
-    let captured = '';
-    child.stdout.on('data', (d) => { captured += d.toString(); });
-    child.stderr.on('data', (d) => { captured += d.toString(); });
-
-    child.on('close', (code) => {
-      if (code === 0) {
-        resolve();
-      } else if (code === EXIT_MDM_PRESENT) {
-        // Managed by MDM — drop the captured script output and signal a skip.
-        resolve({ mdmSkipped: true });
-      } else {
-        const err = new Error(captured.trim() || `Setup failed with exit code ${code}`);
-        err.setupOutput = captured.trim();
-        reject(err);
-      }
-    });
+  return runPythonScript(scriptPath, args, { capture: true });
+}
 
-    child.on('error', reject);
-  });
+/**
+ * Single-tool wrapper around runSetupScript that best-effort reports a failure
+ * to the backend ledger before rethrowing. Used by the live (inherited-stdio)
+ * single-tool setup path so it gets the same failure observability as the batch
+ * paths. The report never changes the thrown error or the exit code.
+ */
+async function runSetupScriptReported(script, stepName, apiKey, opts = {}) {
+  try {
+    return await runSetupScript(script, apiKey, opts);
+  } catch (err) {
+    await reportSetupFailure({
+      step: stepName,
+      exitCode: exitCodeForError(err),
+      apiKey,
+      backendUrl: opts.backendUrl,
+    });
+    throw err;
+  }
 }
 
 // Env vars Unbound writes during setup. The python `--clear` scripts strip
@@ -507,8 +482,13 @@ function reportMdmSkips(labels) {
  * MDM-managed tool labels so callers can qualify their own success message.
  * When `summary` is set, a green success line is printed for the configured
  * tools before the MDM notice.
+ *
+ * `report` (optional) enables best-effort failure reporting to the backend
+ * ledger on a hard failure: { apiKey, backendUrl }. Reporting is skipped for
+ * --clear (clearing isn't an onboarding step) and never affects the exit code
+ * or the error surfaced to the user.
  */
-async function runBatch(tools, runFn, { clear = false, summary = null } = {}) {
+async function runBatch(tools, runFn, { clear = false, summary = null, report = null } = {}) {
   const action = clear ? 'Clearing' : 'Setting up';
   const mdmSkipped = [];
   for (const tool of tools) {
@@ -528,6 +508,15 @@ async function runBatch(tools, runFn, { clear = false, summary = null } = {}) {
       s.fail(`Failed: ${tool.label}`);
       if (err.setupOutput) console.error('\n' + err.setupOutput);
       process.exitCode = 1;
+      // Best-effort failure report. await is safe — reportSetupFailure never rejects.
+      if (report && !clear) {
+        await reportSetupFailure({
+          step: tool.name || tool.label,
+          exitCode: exitCodeForError(err),
+          apiKey: report.apiKey,
+          backendUrl: report.backendUrl,
+        });
+      }
       // Still surface any tools skipped before this failure so the notice isn't lost.
       reportMdmSkips(mdmSkipped);
       return { ok: false, skipped: mdmSkipped };
@@ -660,7 +649,10 @@ setup for that tool is skipped automatically — the managed configuration alrea
 enforces Unbound for every user on the device. To change it, an administrator
 must update the MDM configuration.
 `)
-    .action(async (tools, opts) => {
+    .action(telemetry.wrapAction('setup', async (tools, opts) => {
+      // Register secret values so beforeSend redacts them from any captured event.
+      telemetry.rememberSecret(opts.apiKey);
+      telemetry.rememberSecret(opts.adminApiKey);
       try {
         // Persist URLs first, login, then setup. setUrls is atomic; a malformed
         // URL throws before any disk write.
@@ -759,7 +751,7 @@ must update the MDM configuration.
               });
               return runScriptPiped(tool.script, toolArgs);
             },
-            { clear: opts.clear, summary: opts.clear ? 'All tools cleared' : 'All tools configured' }
+            { clear: opts.clear, summary: opts.clear ? 'All tools cleared' : 'All tools configured', report: { apiKey: adminApiKey, backendUrl } }
           );
           if (!ok) return;
           return;
@@ -814,7 +806,7 @@ must update the MDM configuration.
               backfill: opts.backfill && scriptSupportsBackfill(tool.script),
             });
             return runScriptPiped(tool.script, toolArgs);
-          }, { clear: opts.clear, summary: opts.clear ? 'All tools cleared' : 'All tools configured' });
+          }, { clear: opts.clear, summary: opts.clear ? 'All tools cleared' : 'All tools configured', report: { apiKey, backendUrl } });
           return;
         }
 
@@ -880,7 +872,10 @@ must update the MDM configuration.
             const { script, label } = SETUP_TOOL_MAP[toolName];
             const backfill = opts.backfill && scriptSupportsBackfill(script);
             if (opts.backfill && !backfill) noteBackfillUnsupported(label, script);
-            const r = await runSetupScript(script, apiKey, { clear: opts.clear, backfill, ...urlOpts });
+            // Clear paths aren't onboarding steps, so don't report their failures.
+            const r = opts.clear
+              ? await runSetupScript(script, apiKey, { clear: true, backfill, ...urlOpts })
+              : await runSetupScriptReported(script, toolName, apiKey, { backfill, ...urlOpts });
             if (r && r.mdmSkipped) reportMdmSkips([label]);
           } else if (MODE_TOOLS[toolName]) {
             const mode = MODE_TOOLS[toolName];
@@ -898,7 +893,7 @@ must update the MDM configuration.
               const { script, label } = SETUP_TOOL_MAP[resolved];
               const backfill = opts.backfill && scriptSupportsBackfill(script);
               if (opts.backfill && !backfill) noteBackfillUnsupported(label, script);
-              const r = await runSetupScript(script, apiKey, { ...urlOpts, backfill });
+              const r = await runSetupScriptReported(script, resolved, apiKey, { ...urlOpts, backfill });
               if (r && r.mdmSkipped) reportMdmSkips([label]);
             }
           } else if (INSTRUCTION_TOOLS[toolName]) {
@@ -949,7 +944,7 @@ must update the MDM configuration.
               backfill: opts.backfill && scriptSupportsBackfill(tool.script),
             });
             return runScriptPiped(tool.script, toolArgs);
-          }, { clear: opts.clear, summary: opts.clear ? 'All tools cleared' : 'All tools configured' });
+          }, { clear: opts.clear, summary: opts.clear ? 'All tools cleared' : 'All tools configured', report: { apiKey, backendUrl } });
           if (!ok) return;
         }
 
@@ -962,10 +957,11 @@ must update the MDM configuration.
 
       } catch (err) {
         if (err.message === 'Selection cancelled') return;
+        telemetry.captureError(err, { tags: { flow: 'setup' } });
         if (!err.displayed) output.error(err.message);
         process.exitCode = 1;
       }
-    });
+    }));
 
   // --- Full uninstall ---
 
@@ -1096,14 +1092,13 @@ async function runSetupAllBundle(apiKey, { backendUrl, frontendUrl, gatewayUrl,
   // actually supports it (Claude Code hooks, Codex hooks, Copilot hooks).
   // Cursor would print "not supported"; passing the flag to gateway-mode
   // scripts would error out — `scriptSupportsBackfill` checks for both.
-  const result = await runBatch(resolvedTools, (tool) => {
+  return await runBatch(resolvedTools, (tool) => {
     const args = buildScriptArgs(apiKey, {
       backendUrl, frontendUrl, gatewayUrl,
       backfill: backfill && scriptSupportsBackfill(tool.script),
     });
     return runScriptPiped(tool.script, args);
-  });
-  return result;
+  }, { report: { apiKey, backendUrl } });
 }
 
 /**
@@ -1118,14 +1113,13 @@ async function runMdmSetupAllBundle(adminApiKey, { backendUrl, frontendUrl, gate
       if (!scriptSupportsBackfill(tool.script)) noteBackfillUnsupported(tool.label, tool.script);
     }
   }
-  const result = await runBatch(resolvedTools, (tool) => {
+  return await runBatch(resolvedTools, (tool) => {
     const args = buildScriptArgs(adminApiKey, {
       backendUrl, frontendUrl, gatewayUrl, mdm: true,
       backfill: backfill && scriptSupportsBackfill(tool.script),
     });
     return runScriptPiped(tool.script, args);
-  });
-  return result;
+  }, { report: { apiKey: adminApiKey, backendUrl } });
 }
 
 module.exports = {

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

@@ -14,6 +14,16 @@ const config = require('./config');
 const output = require('./output');
 const { version } = require('../package.json');
 const { checkForUpdates } = require('./update-check');
+const telemetry = require('./telemetry');
+const { getRunId } = require('./run-id');
+
+// Initialize opt-out Sentry as early as possible so a crash anywhere in command
+// parsing is captured. Fully disabled (no init, no network) unless
+// UNBOUND_CLI_SENTRY_DSN is set and UNBOUND_TELEMETRY is not opted out — see
+// telemetry.js. The global flow tag is the neutral 'cli' default; wrapAction
+// overrides it per command (setup/discover/onboard) so command events are
+// tagged accurately. Tagged with the shared run id for correlation. Never throws.
+telemetry.init({ flow: 'cli', runId: getRunId() });
 
 checkForUpdates();
 
@@ -367,4 +377,25 @@ configCmd
     ]);
   });
 
-program.parse(process.argv);
+// Every command inits telemetry at startup, but only setup/onboard/discover
+// flush via wrapAction — all other commands left Sentry's background timers
+// holding the event loop open ~1min when a DSN is configured. parseAsync runs
+// the (already-async) command actions to completion, then a single finally
+// flushes once for ALL current and future commands. flush() is a fast no-op
+// when telemetry is disabled (no DSN), so the common path adds zero latency,
+// and a double-flush with wrapAction is safe (flush sets initialized=false).
+// Command actions set process.exitCode themselves; this wrapper preserves it.
+(async () => {
+  try {
+    await program.parseAsync(process.argv);
+  } catch (err) {
+    // Defensive: every command action handles its own errors (prints + sets
+    // process.exitCode), so this only fires if one throws past its own
+    // try/catch. Surface a clean message and a non-zero exit instead of an
+    // UnhandledPromiseRejection crash, preserving any exit code already set.
+    output.error(err.message);
+    process.exitCode = process.exitCode || 1;
+  } finally {
+    await telemetry.flush();
+  }
+})();

package/src/run-id.js

@@ -0,0 +1,27 @@
+/**
+ * One run id per onboard / setup / discover invocation.
+ *
+ * Generated once (UUID v4) and reused for the whole flow so a broken onboard —
+ * setup step, discovery, and any captured Sentry event — is correlatable under
+ * a single id. Discovery's own backend DeviceScan run id is generated inside
+ * the discovery script (a separate repo), not the CLI, so there is no second
+ * client-side scheme to collide with; this is purely the CLI-side correlation
+ * id used for Sentry tags and failure-report logging.
+ */
+
+const { randomUUID } = require('node:crypto');
+
+let current = null;
+
+/** Returns the current run id, generating one on first use. */
+function getRunId() {
+  if (!current) current = randomUUID();
+  return current;
+}
+
+/** Test-only reset so each test starts from a clean slate. */
+function _reset() {
+  current = null;
+}
+
+module.exports = { getRunId, _reset };

package/src/setup-report.js

@@ -0,0 +1,119 @@
+/**
+ * Best-effort reporting of onboarding/setup step failures to the backend's
+ * setup-failure ledger (POST /api/v1/setup/failed/).
+ *
+ * This is the client half of "no onboarding step fails silently": when a setup
+ * step fails (script exits non-zero, throws, or its download fails) the CLI
+ * records the failure against the device so it shows up server-side instead of
+ * vanishing.
+ *
+ * CONTRACT (do not change here — backend owns it):
+ *   POST {backendUrl}/api/v1/setup/failed/
+ *   body: { serial_number: string (<=255, required),
+ *           step: string (<=64, required),
+ *           exit_code: integer }
+ *   auth: same as /setup/complete/ — gateway API key in Authorization header,
+ *         User-Agent "UnboundCLI/<version>". install_mode/managed are forced
+ *         server-side, so we never send them.
+ *
+ * BEST-EFFORT, ALWAYS: a telemetry POST failure (offline, 429, 4xx, timeout)
+ * must NEVER mask or replace the real error shown to the user, and must NOT
+ * change the CLI's exit code. Every path here swallows its own errors.
+ */
+
+const os = require('os');
+const api = require('./api');
+const config = require('./config');
+
+// The failure report is best-effort telemetry that runs while the user is
+// already waiting on a real setup failure. Bound it tightly (well under the
+// default 30s API timeout) so a hung/slow backend can't delay surfacing the
+// user's error. On timeout the POST rejects and the catch below swallows it.
+const REPORT_TIMEOUT_MS = 3000;
+
+// JS-thrown error (no process exit code available).
+const EXIT_THROWN = 1;
+// Download/transport failure before any process ran.
+const EXIT_DOWNLOAD_FAILED = -1;
+
+/**
+ * Best-effort device identifier for the failure ledger. The Node CLI can't read
+ * the hardware serial reliably, so we use os.hostname() — the backend only uses
+ * serial_number as an org-scoped upsert key, not as a true hardware serial.
+ * Truncated to the backend's 255-char limit; falls back to "unknown-device".
+ */
+function deviceIdentifier() {
+  let name;
+  try { name = os.hostname(); } catch { name = null; }
+  if (!name || typeof name !== 'string' || !name.trim()) return 'unknown-device';
+  return name.trim().slice(0, 255);
+}
+
+// Normalize a step name to the backend's 64-char limit so an over-long stage
+// label can't cause a 400 that we'd then (silently) drop.
+function normalizeStep(step) {
+  const s = (step == null ? '' : String(step)).trim() || 'unknown';
+  return s.slice(0, 64);
+}
+
+// Coerce to an integer exit code; default to the thrown-error sentinel.
+function normalizeExitCode(code) {
+  const n = Number(code);
+  return Number.isInteger(n) ? n : EXIT_THROWN;
+}
+
+// Maps a caught error to the exit code we report to the ledger: a download
+// failure uses the download sentinel, a script exit uses its real code, and
+// anything else falls back to the thrown sentinel.
+function exitCodeForError(err) {
+  if (err && err.downloadFailed) return EXIT_DOWNLOAD_FAILED;
+  if (err && Number.isInteger(err.exitCode)) return err.exitCode;
+  return EXIT_THROWN;
+}
+
+/**
+ * Reports a single failed setup step. Resolves to true if the POST succeeded,
+ * false otherwise — but NEVER rejects, so callers can `await` it inline in an
+ * error path without risk of masking the original failure.
+ *
+ * @param {object} args
+ * @param {string} args.step      - the tool/stage that failed (<=64 chars).
+ * @param {number} args.exitCode  - the process exit code (or a sentinel).
+ * @param {string} [args.apiKey]  - gateway API key (defaults to stored key).
+ * @param {string} [args.backendUrl] - explicit backend URL override.
+ */
+async function reportSetupFailure({ step, exitCode, apiKey, backendUrl } = {}) {
+  try {
+    const key = apiKey || config.getApiKey();
+    // No key → nothing to authenticate with; the ledger upserts by org, so a
+    // keyless report can't be attributed. Skip quietly.
+    if (!key) return false;
+
+    await api.post('/api/v1/setup/failed/', {
+      apiKey: key,
+      baseUrl: backendUrl,
+      timeoutMs: REPORT_TIMEOUT_MS,
+      body: {
+        serial_number: deviceIdentifier(),
+        step: normalizeStep(step),
+        exit_code: normalizeExitCode(exitCode),
+      },
+    });
+    return true;
+  } catch {
+    // Offline / 429 / 4xx / timeout — all swallowed. Telemetry must never
+    // surface over the real error or change the exit code.
+    return false;
+  }
+}
+
+module.exports = {
+  reportSetupFailure,
+  deviceIdentifier,
+  exitCodeForError,
+  EXIT_THROWN,
+  EXIT_DOWNLOAD_FAILED,
+  // Exported for tests:
+  _normalizeStep: normalizeStep,
+  _normalizeExitCode: normalizeExitCode,
+};