unbound-cli 1.6.3 → 1.6.5

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.
+ * 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 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.
- */
-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
@@ -390,6 +365,85 @@ function clearUnboundEnvsEverywhere() {
   return cleared;
 }
 
+// Layout written by the setup pkg's postinstall (setup repo @ 41ca7b2 —
+// packaging/pkg/postinstall + pkg/ai.getunbound.discovery.plist). Hard-coded;
+// never accept user input here. Frozen so a misbehaving test can't mutate the
+// production paths for the rest of the process.
+const BINARY_INSTALL_PATHS = Object.freeze({
+  optDir: '/opt/unbound',
+  daemonPlist: '/Library/LaunchDaemons/ai.getunbound.discovery.plist',
+  daemonLabel: 'ai.getunbound.discovery',
+  newsyslogConf: '/etc/newsyslog.d/ai.getunbound.conf',
+  logDir: '/var/log/unbound',
+});
+
+// Tears down the privileged binary install. Best-effort: a failure on any
+// single path is logged via output.warn AND pushed onto the returned
+// `failed` array, but never aborts the rest. Bootout the daemon FIRST so
+// its supervisor doesn't relaunch mid-rm. Callers MUST gate this on root.
+// Returns { removed, failed } — both labelled lists; nuke folds `failed`
+// into its closing summary so a partial wipe doesn't print "success".
+// Path overrides + `runLaunchctl` exist so tests stay hermetic — see
+// test/setup-args.test.js. Safety net: any production-default path (or
+// daemonLabel, when runLaunchctl is true) requires the caller to explicitly
+// pass `_confirmProductionPaths:true` — dev machines often have a real
+// install, and a forgotten override would wipe it. Production sets the
+// flag; tests omit it and rely on the throw.
+function removeBinaryInstall({
+  optDir = BINARY_INSTALL_PATHS.optDir,
+  daemonPlist = BINARY_INSTALL_PATHS.daemonPlist,
+  daemonLabel = BINARY_INSTALL_PATHS.daemonLabel,
+  newsyslogConf = BINARY_INSTALL_PATHS.newsyslogConf,
+  logDir = BINARY_INSTALL_PATHS.logDir,
+  runLaunchctl = process.platform === 'darwin',
+  _confirmProductionPaths = false,
+} = {}) {
+  const usesProdDefaults =
+    optDir === BINARY_INSTALL_PATHS.optDir ||
+    daemonPlist === BINARY_INSTALL_PATHS.daemonPlist ||
+    newsyslogConf === BINARY_INSTALL_PATHS.newsyslogConf ||
+    logDir === BINARY_INSTALL_PATHS.logDir ||
+    (runLaunchctl && daemonLabel === BINARY_INSTALL_PATHS.daemonLabel);
+  if (usesProdDefaults && !_confirmProductionPaths) {
+    throw new Error('removeBinaryInstall: production-default path(s) used without _confirmProductionPaths:true — pass tmp overrides or set the flag explicitly');
+  }
+  const removed = [];
+  const failed = [];
+  if (runLaunchctl) {
+    // spawnSync does NOT throw on non-zero exit — it returns { status, error,
+    // stderr }. Treat "Could not find specified service" / "No such process"
+    // as the legitimate "daemon not loaded" case (first install, already
+    // booted out) and swallow it. Surface anything else so the operator knows
+    // the bootout-then-rm ordering may have lost the race.
+    const r = spawnSync('launchctl', ['bootout', `system/${daemonLabel}`], { stdio: 'pipe' });
+    const stderr = r.stderr ? r.stderr.toString().trim() : '';
+    if (r.error) {
+      output.warn(`nuke: launchctl bootout failed to spawn: ${r.error.message}`);
+      failed.push(`launchctl bootout ${daemonLabel}`);
+    } else if (r.status !== 0 && !/Could not find specified service|No such process/i.test(stderr)) {
+      output.warn(`nuke: launchctl bootout exited ${r.status}: ${stderr || '(no stderr)'}`);
+      failed.push(`launchctl bootout ${daemonLabel}`);
+    }
+  }
+  const targets = [
+    ['LaunchDaemon plist', daemonPlist],
+    ['newsyslog conf', newsyslogConf],
+    ['log dir', logDir],
+    ['install tree', optDir],
+  ];
+  for (const [label, p] of targets) {
+    try {
+      if (!fs.existsSync(p)) continue;
+      fs.rmSync(p, { recursive: true, force: true });
+      removed.push(`${label} (${p})`);
+    } catch (err) {
+      output.warn(`nuke: failed to remove ${label} (${p}): ${err.message}`);
+      failed.push(`${label} (${p})`);
+    }
+  }
+  return { removed, failed };
+}
+
 /**
  * Returns true when the process has the privileges needed to touch system-level
  * (MDM) configuration. On Windows, `net session` succeeds only when elevated, so
@@ -428,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) {
@@ -449,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 };
@@ -581,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.
@@ -680,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;
@@ -735,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;
         }
 
@@ -801,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];
@@ -819,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]) {
@@ -870,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;
         }
 
@@ -883,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 ---
 
@@ -956,9 +1031,21 @@ Examples:
 
         // MDM clears need root and touch all users — run them only when we have it.
         let mdmFailed = [];
+        let binaryFailed = [];
         if (includeMdm) {
           const mdmTools = Object.keys(MDM_TOOLS).map(name => ({ name, ...MDM_TOOLS[name] }));
           mdmFailed = await clearToolsBestEffort('mdm', mdmTools, { mdm: true, backendUrl, gatewayUrl });
+
+          // Root-only by construction (gated on includeMdm). No-op when no binary
+          // install is present (python-only setups) and on Windows.
+          // `_confirmProductionPaths` is the explicit "this is the real call site"
+          // ack — the function refuses production defaults without it as a guard
+          // against tests forgetting to override paths.
+          const { removed: binaryRemoved, failed: bf } = removeBinaryInstall({ _confirmProductionPaths: true });
+          binaryFailed = bf;
+          if (binaryRemoved.length) {
+            output.info(`Removed binary install: ${binaryRemoved.join('; ')}.`);
+          }
         } else {
           output.info('Skipped MDM (system-level) config — that needs root. Re-run with sudo to remove it too.');
         }
@@ -975,12 +1062,12 @@ Examples:
         output.success('Stored credentials and settings removed.');
 
         console.log('');
-        const failed = [...userFailed, ...mdmFailed];
+        const failed = [...userFailed, ...mdmFailed, ...binaryFailed];
         const scope = includeMdm ? 'on this device' : 'for your user';
         if (failed.length === 0) {
           output.success(`Unbound removed ${scope}. The CLI is back to a fresh state — run "unbound login" to start over.`);
         } else {
-          output.warn(`Done ${scope}, but ${failed.length} tool clear(s) reported issues: ${failed.join(', ')}. Credentials were still removed.`);
+          output.warn(`Done ${scope}, but ${failed.length} step(s) reported issues: ${failed.join(', ')}. Credentials were still removed.`);
         }
       } catch (err) {
         output.error(err.message);
@@ -1005,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 } });
 }
 
 /**
@@ -1027,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 = {
@@ -1049,4 +1134,6 @@ module.exports = {
   resolveSetupAllTools,
   clearUnboundEnvsEverywhere,
   NUKE_ENV_VARS,
+  removeBinaryInstall,
+  BINARY_INSTALL_PATHS,
 };

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 };