impel-cli 0.20.45 → 0.20.46-beta.0

package/src/commands/cursorExperimental.js

@@ -9,8 +9,11 @@ import {
   prepareManagedCursor,
   reusePreparedManagedCursor,
 } from "../cursorLocal.js";
+import { FEATURE_NOT_ENABLED_EXIT_CODE } from "../exitCodes.js";
+import { CURSOR_EXPERIMENT_FLAG, evaluateFlag, FlagStateUnknownError } from "../featureFlags.js";
 import { fetchHttp1 } from "../http1.js";
 import { loadConfig, normalizeGatewayUrl, redactSecretText, resolveDefaultGateway } from "../config.js";
+import { RUNTIME_BRAND } from "../runtimeBrand.js";
 import { assertProviderScopes, ensureTenantSelection, tenantCredential } from "../tenants.js";
 
 export const CURSOR_EXPERIMENT_HELP = `impel experimental cursor prepare|open|status
@@ -93,6 +96,55 @@ async function cursorGatewayCatalog(options, dependencies = {}) {
   return payload;
 }
 
+/**
+ * Resolve the Cursor experiment flag into a decision, without throwing.
+ *
+ * Returned as data rather than raised for two reasons. `status` has to keep
+ * working with the flag off — a diagnostic that refuses to run when the thing
+ * it diagnoses is disabled is useless — so it needs the state as a value. And
+ * a refusal carries its own exit code, which a throw cannot: `experimental`
+ * lets errors escape to `bin/impel.js`, whose catch-all 1 is indistinguishable
+ * from a crash.
+ *
+ * The two refusals are deliberately different numbers. "Off for this account"
+ * is a settled answer and retrying changes nothing; "could not establish the
+ * state" is worth retrying the moment the machine is back online.
+ */
+async function cursorFlagDecision({ config, homeDir }, dependencies) {
+  const evaluate = dependencies.evaluateFlag || evaluateFlag;
+  try {
+    const flag = await evaluate(CURSOR_EXPERIMENT_FLAG, {
+      config,
+      env: dependencies.environment || process.env,
+      homeDir,
+    });
+    if (flag.enabled) {
+      return { allowed: true, source: flag.source, stateLabel: `enabled (${flag.source})` };
+    }
+    return {
+      allowed: false,
+      reason: "disabled",
+      source: flag.source,
+      stateLabel: `disabled for this account (${flag.source})`,
+      exitCode: FEATURE_NOT_ENABLED_EXIT_CODE,
+      message: `managed Cursor is not enabled for this account; ask your ${RUNTIME_BRAND.product.displayName} workspace admin to turn on the Cursor experiment, or run \`${RUNTIME_BRAND.cli.command} report --message "requesting Cursor access"\``,
+    };
+  } catch (error) {
+    if (!(error instanceof FlagStateUnknownError)) throw error;
+    // The message is already one actionable sentence naming the specific cause
+    // — unreachable, undeployed route, backoff, managed surface — so it is
+    // passed through rather than flattened into a generic refusal.
+    return {
+      allowed: false,
+      reason: error.reason,
+      source: null,
+      stateLabel: `unknown — ${error.message}`,
+      exitCode: error.exitCode,
+      message: `managed Cursor cannot start: ${error.message}`,
+    };
+  }
+}
+
 function statusLines(status, tenantId) {
   const vendorLabel = status.vendor
     ? `${status.vendor.version} (${status.vendor.commit.slice(0, 12)})`
@@ -138,20 +190,40 @@ export async function cmdCursorExperimental(argv, dependencies = {}) {
   };
   const credential = tenantCredential(config.pat, tenantId);
 
+  // The fourth gate, after authentication, tenant selection, and scopes, and
+  // before anything touches the tenant's runtime. Those three answer "who are
+  // you"; this one answers "should this experiment run at all", which is the
+  // question that has to be answerable remotely — an experiment nobody can
+  // turn off from the control plane is not an experiment, it is a release.
+  const flag = await cursorFlagDecision({ config, homeDir }, dependencies);
+
   if (action === "status") {
     const status = (dependencies.managedCursorStatus || managedCursorStatus)(common, dependencies);
     for (const line of statusLines(status, tenantId)) log(line);
+    // `status` is exempt from the refusal on purpose: the flag state is one of
+    // the things someone runs `status` to find out, and reporting it is the
+    // opposite of leaking access.
+    log(`Cursor experiment access: ${flag.stateLabel}`);
     try {
       const catalog = await cursorGatewayCatalog({ gatewayUrl, credential, tenantId }, dependencies);
       log(`Gateway Cursor catalog: ready (${catalog.data.length} model${catalog.data.length === 1 ? "" : "s"})`);
-      return { ...status, gatewayReady: true, catalog };
+      return { ...status, flag, gatewayReady: true, catalog };
     } catch (error) {
       const gatewayError = redactSecretText(error?.message || error);
       log(`Gateway Cursor catalog: unavailable — ${gatewayError}`);
-      return { ...status, gatewayReady: false, gatewayError };
+      return { ...status, flag, gatewayReady: false, gatewayError };
     }
   }
 
+  if (!flag.allowed) {
+    // One line, a distinct code, and no runtime work — the same contract the
+    // managed-runtime preflight follows. `process.exitCode` rather than a throw
+    // keeps this distinguishable from a crash.
+    (dependencies.reportError || console.error)(flag.message);
+    process.exitCode = flag.exitCode;
+    return { refused: true, flag };
+  }
+
   let prepared;
   try {
     prepared = (dependencies.prepareManagedCursor || prepareManagedCursor)(common, dependencies);

package/src/commands/nuke.js

@@ -190,7 +190,7 @@ export async function cmdNuke(argv = [], overrides = {}) {
   if (libraryRemnants.length) io.log(`  macOS caches/preferences/state entries: ${libraryRemnants.length}`);
   if (keychainItems.length) io.log(`  Keychain Safe Storage items: ${keychainItems.length}`);
   if (windowsRemnants.length) io.log(`  Windows managed profiles and entry point: ${windowsRemnants.length}`);
-  if (configDirExists) io.log(`  CLI state, profiles, vendor cache, and auth: ${io.configDir}`);
+  if (configDirExists) io.log(`  CLI state, profiles, vendor cache, auth, analytics consent, queued analytics, flag cache, and saved bug reports: ${io.configDir}`);
   io.log("Vendor apps and native ~/.claude and ~/.codex profiles are not touched.");
 
   if (!flags.yes) {
@@ -233,7 +233,7 @@ export async function cmdNuke(argv = [], overrides = {}) {
 
   if (configDirExists) {
     fs.rmSync(io.configDir, { recursive: true, force: true });
-    io.log(`Removed ${io.configDir} (profiles, vendor cache, sessions, and auth).`);
+    io.log(`Removed ${io.configDir} (profiles, vendor cache, sessions, auth, analytics consent and queue, flag cache, and saved bug reports).`);
   }
 
   io.log("impel nuke: complete. Run `impel setup` for a clean install.");

package/src/commands/report.js

@@ -0,0 +1,309 @@
+// `impel report` — the user-initiated bug report path.
+//
+// This command exists for the moment something else is broken, and every
+// decision below follows from that:
+//
+//   - Typing the command *is* the decision to send (KD1). There is no payload
+//     preview to approve and no `[y/N]`, because there is nothing left to
+//     decide: the user asked for this. It follows that a non-TTY sends too —
+//     `impel report` inside a script is still someone reporting a bug.
+//   - It does not consult analytics consent, and it does not consult
+//     `reportEnvOptOut` either. Reporting a bug is a request the user typed,
+//     not passive measurement, so `telemetry.enabled: false` must not silence
+//     it (R3/KD5) — and `IMPEL_DO_NOT_TRACK` stops the CLI acting on its own
+//     rather than disabling a command someone ran on purpose.
+//   - The managed-surface guard still applies, because the P1-8 egress boundary
+//     is not a consent question (R7): a profile holding vendor app credentials
+//     may reach the gateway and nothing else.
+//   - It never loses the report. Anything short of an accepted response writes
+//     the envelope under `CONFIG_DIR` and prints the path, exiting with
+//     `REPORT_SPOOLED_EXIT_CODE` so a script can tell "saved, not sent" from a
+//     crash (R4).
+//
+// Everything about *what* is sent lives in `src/bugReport.js`, shared with the
+// automatic sender. What is left here is the part that has a person attached:
+// flags, files, printed sentences, and an exit code.
+//
+// The spool lives under `CONFIG_DIR`, so `impel nuke` erases it.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { parseFlags } from "../args.js";
+import {
+  BugReportError,
+  buildEnvelope,
+  deliverWithRetry,
+  REASON_NOTES,
+  REPORT_ENDPOINT_PATH,
+  REPORT_SPOOL_DIR,
+  resolveReportOrigin,
+  sleep,
+  SPOOL_MAX_FILES,
+  spoolReport,
+} from "../bugReport.js";
+import { loadConfig, redactSecretText, resolveDefaultAppUrl } from "../config.js";
+import { REPORT_SPOOLED_EXIT_CODE } from "../exitCodes.js";
+import { fetchHttp1 } from "../http1.js";
+import { RUNTIME_BRAND } from "../runtimeBrand.js";
+import { CI_ENV, DO_NOT_TRACK_ENV, managedMarkerPresent } from "../telemetryConsent.js";
+
+// Re-exported: the shared core owns these now, but they are this command's
+// public surface and callers should not have to know where they moved.
+export { REASON_NOTES, REPORT_ENDPOINT_PATH, REPORT_SPOOL_DIR };
+
+const REPORT_COMMAND = `${RUNTIME_BRAND.cli.command} report`;
+const REQUEST_TIMEOUT_MS = 10_000;
+
+const MIN_EXIT_CODE = -1;
+const MAX_EXIT_CODE = 65_535;
+
+const FLAG_SPEC = Object.freeze({
+  app: { type: "string" },
+  command: { type: "string" },
+  diagnostics: { type: "string" },
+  "error-code": { type: "string" },
+  "exit-code": { type: "string" },
+  help: { type: "boolean" },
+  log: { type: "string" },
+  message: { type: "string" },
+});
+
+const FLAG_NAMES = new Set(Object.keys(FLAG_SPEC));
+
+const HELP = `${REPORT_COMMAND} - send a bug report to ${RUNTIME_BRAND.product.displayName}
+
+Usage:
+  ${REPORT_COMMAND} --message "<what went wrong>" [options]
+
+Options:
+  --message <text>       What went wrong, in your words.
+  --command <name>       The ${RUNTIME_BRAND.cli.command} command that failed.
+  --exit-code <n>        The exit code it returned.
+  --error-code <code>    The error code it printed, when there was one.
+  --log <file>           A file holding that command's output.
+  --diagnostics <file>   Output from \`${RUNTIME_BRAND.cli.command} doctor --json\` to attach.
+  --app <url>            Override the app/control-plane URL for this command.
+
+The CLI version, Node version, platform, architecture, release channel, and your
+current organization are collected automatically. Credentials, home directory
+paths, and email addresses are removed before anything is sent. Running this
+command sends the report — reports work whether or not analytics are enabled.
+
+When \`${RUNTIME_BRAND.cli.command} setup\` or \`${RUNTIME_BRAND.cli.command} update\` runs out of ways to fix a failure, the CLI
+files one of these reports on its own and says so. To stop that, set
+${DO_NOT_TRACK_ENV}=1 or ${CI_ENV}=1. Neither switch disables this command, which
+is a message you chose to send. Bare \`DO_NOT_TRACK\` and \`CI\` turn off analytics
+but not failure reports — silence about a broken install is not something an
+unrelated environment variable should decide.
+
+If the report cannot be delivered it is written under
+${path.join("~", ".config", RUNTIME_BRAND.cli.configNamespace, "reports")}
+and the path is printed, so it is never lost. That directory keeps the last
+${SPOOL_MAX_FILES} reports and nothing older than 30 days.
+`;
+
+class ReportCommandError extends Error {}
+
+function fail(message) {
+  throw new ReportCommandError(message);
+}
+
+/* -------------------------------------------------------------------------- */
+/* Flags                                                                      */
+/* -------------------------------------------------------------------------- */
+
+function readAttachment(filePath, label) {
+  try {
+    return fs.readFileSync(filePath, "utf8");
+  } catch (error) {
+    fail(`${REPORT_COMMAND}: could not read ${label} file: ${redactSecretText(error?.message || error)}`);
+  }
+  return "";
+}
+
+function requestedExitCode(value) {
+  if (value === undefined) return undefined;
+  const raw = String(value).trim();
+  if (!/^-?\d+$/u.test(raw)) {
+    fail(`${REPORT_COMMAND}: --exit-code must be an integer from ${MIN_EXIT_CODE} to ${MAX_EXIT_CODE}.`);
+  }
+  const exitCode = Number(raw);
+  if (!Number.isSafeInteger(exitCode) || exitCode < MIN_EXIT_CODE || exitCode > MAX_EXIT_CODE) {
+    fail(`${REPORT_COMMAND}: --exit-code must be an integer from ${MIN_EXIT_CODE} to ${MAX_EXIT_CODE}.`);
+  }
+  return exitCode;
+}
+
+/**
+ * Turn parsed flags into the core's normalized field bag.
+ *
+ * Attachment reads and exit-code parsing stay here because they are this
+ * front-end's concerns: only the manual command has files to read and a
+ * `--exit-code` string to validate. The core takes values, not flags.
+ */
+function envelopeFields(flags) {
+  return {
+    message: flags.message,
+    command: flags.command,
+    errorCode: flags["error-code"],
+    exitCode: requestedExitCode(flags["exit-code"]),
+    log: flags.log === undefined ? "" : readAttachment(flags.log, "--log"),
+    doctor: flags.diagnostics === undefined
+      ? ""
+      : readAttachment(flags.diagnostics, "--diagnostics"),
+  };
+}
+
+/* -------------------------------------------------------------------------- */
+/* Spool                                                                      */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * The single "not sent" exit.
+ *
+ * Every failure lands here — unreachable, absent route, rate limited, refused,
+ * unreadable response — because from the reporter's side they are one state:
+ * the report exists, it is on disk, and it was not delivered.
+ */
+function reportNotSent({ envelope, reportId, appUrl, io, message }) {
+  io.warn(`${REPORT_COMMAND}: ${message}`);
+  let filePath = null;
+  try {
+    filePath = spoolReport({ envelope, reportId, appUrl, io });
+  } catch (error) {
+    io.warn(`${REPORT_COMMAND}: the report could not be saved either: ${redactSecretText(error?.message || error)}`);
+    // Nothing was printed to copy — the envelope is never dumped to the
+    // terminal (KD1 removed the confirmation that used to show it), and this
+    // branch is the one place where it also failed to reach disk. So print it
+    // here, redacted, as the only remaining copy.
+    io.warn(`${REPORT_COMMAND}: this is the whole report; copy it before closing this terminal.`);
+    io.warn(redactSecretText(JSON.stringify(envelope, null, 2)));
+    process.exitCode = REPORT_SPOOLED_EXIT_CODE;
+    return;
+  }
+  io.log(`Nothing was lost. The report is saved at ${filePath}`);
+  io.log(`Attach that file when you contact ${RUNTIME_BRAND.product.displayName} support, or run \`${REPORT_COMMAND}\` again once the connection is back.`);
+  process.exitCode = REPORT_SPOOLED_EXIT_CODE;
+}
+
+/* -------------------------------------------------------------------------- */
+/* Command                                                                    */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * The core's origin check, wearing this command's error messages.
+ *
+ * The rejection reasons are identical, but the wording belongs to the front-end
+ * that has a `--app` flag to name. The automatic sender has no flag and no
+ * stderr, so it reads the same `BugReportError` codes and stays silent instead.
+ */
+function requireAppUrl(flags, config) {
+  try {
+    return resolveReportOrigin(flags.app || config.appUrl || resolveDefaultAppUrl());
+  } catch (error) {
+    if (error instanceof BugReportError && error.code === "invalid_url") {
+      fail(`${REPORT_COMMAND}: --app must be an HTTP or HTTPS URL.`);
+    }
+    if (error instanceof BugReportError && error.code === "unsafe_origin") {
+      fail(`${REPORT_COMMAND}: --app must be a bare HTTP or HTTPS origin without credentials, a path, query, or fragment.`);
+    }
+    throw error;
+  }
+  return "";
+}
+
+export async function cmdReport(argv = [], overrides = {}) {
+  const io = {
+    loadConfig,
+    fetchImpl: fetchHttp1,
+    environment: process.env,
+    homeDir: os.homedir(),
+    platform: process.platform,
+    now: Date.now(),
+    spoolDir: REPORT_SPOOL_DIR,
+    timeoutMs: REQUEST_TIMEOUT_MS,
+    sleep,
+    log: console.log,
+    warn: console.warn,
+    ...overrides,
+  };
+
+  const { flags, positionals } = parseFlags(argv, FLAG_SPEC);
+  try {
+    if (flags.help) {
+      io.log(HELP);
+      return;
+    }
+    const unknownFlag = Object.keys(flags).find((name) => !FLAG_NAMES.has(name));
+    if (unknownFlag) fail(`${REPORT_COMMAND}: unknown option --${redactSecretText(unknownFlag)}.`);
+    if (positionals.length) {
+      fail(`${REPORT_COMMAND}: unexpected argument "${redactSecretText(positionals[0])}"; put your description in --message.`);
+    }
+
+    // The P1-8 egress boundary, checked before anything is collected. A managed
+    // vendor app profile may reach the gateway and nothing else, so a report
+    // sent from inside one presents as an unexpected call from a profile
+    // holding app credentials. Unlike analytics this is not a consent question.
+    if (managedMarkerPresent(io.environment, io.homeDir)) {
+      fail(`${REPORT_COMMAND}: bug reports cannot be sent from inside a managed ${RUNTIME_BRAND.product.displayName} app profile; run this from a terminal.`);
+    }
+
+    // Deliberately not `analyticsConsentGranted`: opting out of measurement is
+    // not opting out of being able to report a bug (R3/KD5).
+    const config = io.loadConfig();
+    if (!config?.pat) {
+      fail(`${REPORT_COMMAND}: not authenticated. Run \`${RUNTIME_BRAND.cli.command} setup\` first, then report the bug.`);
+    }
+    const appUrl = requireAppUrl(flags, config);
+    let envelope;
+    let reportId;
+    try {
+      ({ envelope, reportId } = buildEnvelope({ fields: envelopeFields(flags), config, io }));
+    } catch (error) {
+      if (error instanceof BugReportError && error.code === "too_many_diagnostics") {
+        fail(`${REPORT_COMMAND}: too many diagnostic fields to send.`);
+      }
+      throw error;
+    }
+
+    // Printed before the request, not after (KTD6): the id is a fingerprint of
+    // the envelope, so it is known now, and three attempts against an
+    // unreachable control plane is a long enough pause to owe the user a line
+    // first. Worded as an attempt for the same reason — the outcome, when it is
+    // not a plain success, is a separate sentence below.
+    io.log(`Sending this report (id ${reportId}). Set ${DO_NOT_TRACK_ENV}=1 to disable.`);
+
+    const { outcome, failure } = await deliverWithRetry({
+      envelope,
+      appUrl,
+      currentPat: config.pat,
+      io,
+    });
+    if (failure) {
+      reportNotSent({ envelope, reportId, appUrl, io, message: failure });
+      return;
+    }
+    if (outcome.taskCreated) {
+      io.log(`Reported. Task ${outcome.taskId} was created in your ${RUNTIME_BRAND.product.displayName} workspace.`);
+      return;
+    }
+    // `BUG_REPORT_REASONS` comes from the contract, so a reason added there
+    // reaches this line before anyone writes it a sentence. Fall back to the
+    // bare code rather than interpolating `undefined` at the user; the
+    // contract-derived test below keeps that fallback from becoming the
+    // normal path.
+    const sentence = REASON_NOTES[outcome.reason];
+    const note = sentence ? `: ${sentence}` : "";
+    const reason = outcome.reason ? ` (${outcome.reason})` : "";
+    io.log(`Recorded, no task${reason}${note}. Report ID ${reportId}.`);
+  } catch (error) {
+    if (error instanceof ReportCommandError) {
+      console.error(error.message);
+      process.exitCode = 1;
+      return;
+    }
+    throw error;
+  }
+}

package/src/commands/setup.js

@@ -11,7 +11,7 @@ import {
   redactSecretText,
 } from "../config.js";
 import { promptSecret, promptText } from "../prompt.js";
-import { fetchTenants, normalizeTenantId, tenantCredential } from "../tenants.js";
+import { applyCliUser, fetchTenants, normalizeTenantId, tenantCredential } from "../tenants.js";
 import {
   printReconciliationSummary,
   reconcileAllTenants,
@@ -19,9 +19,11 @@ import {
 } from "../provisioning.js";
 import { describeCliFailure, preparePlatformClis } from "../platformSetup.js";
 import { runInstallRecovery } from "../installRecovery/engine.js";
+import { reportInstallFailure } from "../autoReport.js";
 import { refreshUpdateCache, updateNoticeLine } from "../updates.js";
 import { restoreNativeProfiles } from "./use.js";
 import { brandedEnvironmentName, brandedText, RUNTIME_BRAND } from "../runtimeBrand.js";
+import { markTelemetryNoticeShown } from "../telemetryNotice.js";
 import {
   cacheProviderReadiness,
   probeGatewayProviderReadiness,
@@ -44,6 +46,11 @@ Usage:
   impel setup --skip-apps           Skip desktop apps
   impel setup --skip-clis           Do not install missing vendor CLIs
   impel setup --no-recovery         Disable automatic install recovery
+  impel setup --analytics on|off    Turn anonymous usage analytics on or off
+
+Analytics are off unless you turn them on. Separately, when setup or update
+fails, Impel files a bug report so the failure can be fixed; see \`impel report
+--help\`.
 `);
 
 /** Kept as a pure compatibility helper for callers/tests. */
@@ -119,10 +126,66 @@ function recomputeReport(report) {
   return report;
 }
 
+/**
+ * The message for an automatic report about a tenant-convergence failure.
+ *
+ * Every failed tenant contributes, because a setup that fails two tenants for
+ * two different reasons and reports only the first has reported the wrong
+ * thing. The tenant id prefixes each error since the ids are otherwise absent
+ * from the joined string. `sanitizeInstallFailureEnvelope` bounds the result.
+ */
+function failedTenantMessage(report) {
+  const failed = report.tenants.filter((tenant) => tenant.status === "failed");
+  const described = failed
+    .map((tenant) => `${tenant.tenantId}: ${tenant.errors.join("; ")}`)
+    .filter((line) => !line.endsWith(": "));
+  return described.join(" | ") || "Tenant readiness verification failed.";
+}
+
 function confirmed(answer) {
   return /^(?:y|yes)$/iu.test(String(answer || "").trim());
 }
 
+/**
+ * Record the analytics preference `--analytics` names, and normalize the key.
+ *
+ * Setup no longer asks. A question with a default answer is not much of a
+ * question, and the one thing `impel setup` must do — get a broken machine
+ * working — is not the moment to interrupt with an unrelated one. Analytics
+ * stay opt-in and stay switchable: `--analytics on` turns them on, and
+ * `--analytics off` (or nothing at all) leaves them off.
+ *
+ * Every path that is not an explicit `on` removes the key rather than storing
+ * `false`, which keeps one meaning for "absent" across the whole codebase —
+ * `analyticsConsentGranted` tests for exactly `true`.
+ *
+ * A branded extension runs its own product and must not inherit Impel's
+ * phone-home (KTD11), so `--analytics on` is a no-op there.
+ */
+function applyAnalyticsPreference(config, io, preference) {
+  if (RUNTIME_BRAND.cli.packageName !== "impel-cli") return;
+  if (preference === "on") {
+    config.telemetry = { ...(config.telemetry || {}), enabled: true };
+    io.saveConfig(config);
+    console.log("✓ Analytics on. Turn them off any time with `impel setup --analytics off`.");
+    io.markTelemetryNoticeShown();
+    return;
+  }
+
+  // Only an explicit `off` revokes a stored yes. A plain `impel setup` — which
+  // is also the repair command — must not silently undo a decision on file.
+  if (preference === "off" || config.telemetry?.enabled !== true) {
+    if (config.telemetry) {
+      delete config.telemetry.enabled;
+      if (Object.keys(config.telemetry).length === 0) delete config.telemetry;
+      io.saveConfig(config);
+    }
+  }
+  // Written on every path, including the ones that print nothing: having run
+  // setup at all is what the first-run notice exists to announce.
+  io.markTelemetryNoticeShown();
+}
+
 export async function cmdSetup(argv, overrides = {}) {
   const io = {
     loadConfig,
@@ -134,12 +197,14 @@ export async function cmdSetup(argv, overrides = {}) {
     reconcile: reconcileAllTenants,
     probe: probeGateway,
     recoverInstall: runInstallRecovery,
+    reportInstallFailure,
     restoreNativeProfiles,
     isTTY: process.stdin.isTTY,
     platform: process.platform,
     environment: process.env,
     refreshUpdateCache,
     updateNoticeLine,
+    markTelemetryNoticeShown,
     ...overrides,
   };
   if (overrides.prepareWindowsClis && !overrides.preparePlatformClis) {
@@ -154,6 +219,7 @@ export async function cmdSetup(argv, overrides = {}) {
     "skip-clis": { type: "boolean" },
     repair: { type: "boolean" }, // deprecated compatibility no-op
     "no-recovery": { type: "boolean" },
+    analytics: { type: "string" },
     help: { type: "boolean" },
   });
   if (flags.help) {
@@ -165,6 +231,15 @@ export async function cmdSetup(argv, overrides = {}) {
     process.exitCode = 1;
     return;
   }
+  // Rejected before the token prompt and any network call: a typo in a flag
+  // about analytics must not cost the user a setup run to discover.
+  // `in`, not `!== undefined`: a trailing bare `--analytics` parses to
+  // `undefined`, and silently ignoring it would look like it took effect.
+  if ("analytics" in flags && !["on", "off"].includes(flags.analytics)) {
+    console.error(`impel setup: --analytics accepts "on" or "off", not "${redactSecretText(flags.analytics)}".`);
+    process.exitCode = 1;
+    return;
+  }
 
   const existing = io.loadConfig();
   const gatewayUrl = normalizeGatewayUrl(flags.gateway || existing?.gatewayUrl || resolveDefaultGateway());
@@ -203,6 +278,7 @@ export async function cmdSetup(argv, overrides = {}) {
   config.tenantName = selected.name;
   if (listing.productAccess) config.productAccess = listing.productAccess;
   if (listing.scopes) config.scopes = listing.scopes;
+  applyCliUser(config, listing);
   config.tenantsUpdatedAt = new Date().toISOString();
   io.saveConfig(config);
 
@@ -212,6 +288,11 @@ export async function cmdSetup(argv, overrides = {}) {
     console.log(`  ${tenant.id}${tenant.id === selected.id ? " (CLI default)" : ""} — ${tenant.name}`);
   }
 
+  // After the credential is stored and the tenant chosen, so the preference is
+  // written into a config that already exists, and before convergence starts
+  // printing per-tenant progress the confirmation would be buried in.
+  applyAnalyticsPreference(config, io, flags.analytics);
+
   // Setup is where a stale CLI hurts most (it re-hits installer bugs newer
   // releases already fixed), and on a first run the launch-time notice cache
   // is still empty — so check synchronously here. The token was just verified
@@ -503,6 +584,58 @@ export async function cmdSetup(argv, overrides = {}) {
     if (sharedFailure) console.error(`Shared setup failure: ${sharedFailure}`);
     const setupCommand = io.platform === "win32" ? "impel.cmd setup" : "impel setup";
     console.error(`Setup is incomplete. Fix the reported issue or rerun \`${setupCommand}\`.`);
+    const failedTenantIds = report.tenants
+      .filter((tenant) => tenant.status === "failed")
+      .map((tenant) => tenant.tenantId);
+    // The one dispatch point for this command (R1). It sits here rather than
+    // in either recovery block above because a failure recovery repaired is
+    // not a failure (KTD2) — this branch is reached only by a setup that ran
+    // out of ways to fix itself. One report per run, whatever the tenant count.
+    //
+    // After the two `console.error`s so the actionable "rerun `impel setup`"
+    // stays the last thing a reader scrolls back to, and before
+    // `process.exitCode` because the report must not depend on the exit path.
+    //
+    // `reportInstallFailure` swallows its own errors, but it is an injection
+    // seam: this `catch` is the promise that whatever is behind it, a setup
+    // that failed with a clear message never becomes a setup that crashed.
+    try {
+      await io.reportInstallFailure({
+        failure: sharedFailure
+          ? {
+            scope: "shared",
+            platform: io.platform,
+            architecture: process.arch,
+            step: "setup.shared_vendor_clis",
+            message: sharedFailure,
+            diagnostics: { tenantId: selected.id },
+          }
+          : {
+            // Attribute the report to a tenant that actually failed, not to
+            // the CLI default: `selected.id` is whichever tenant this machine
+            // points at, which may well have converged fine. With more than one
+            // failure there is no single owner, so the report is `shared` and
+            // the ids ride along in diagnostics — the message already names
+            // every one of them.
+            ...(failedTenantIds.length === 1
+              ? { scope: "tenant", tenantId: failedTenantIds[0] }
+              : { scope: "shared" }),
+            platform: io.platform,
+            architecture: process.arch,
+            step: "setup.tenant_convergence",
+            message: failedTenantMessage(report),
+            diagnostics: {
+              cliTenantId: selected.id,
+              failedTenantIds: failedTenantIds.join(","),
+              failedTenants: String(failedTenantIds.length),
+            },
+          },
+        config,
+        io,
+      });
+    } catch {
+      // R10: one error message, and it is the one above.
+    }
     process.exitCode = 1;
     return report;
   }