impel-cli 0.20.45 → 0.20.46-beta.2

package/src/runtimeBrand.js

@@ -10,8 +10,8 @@ const SAFE_BUNDLE_PREFIX = /^[A-Za-z0-9]+(?:[.-][A-Za-z0-9]+)+$/u;
 const CONTROL_RE = /[\u0000-\u001F\u007F-\u009F]/u;
 const SUPPORTED_COMMANDS = new Set([
   "setup", "auth", "pat", "token", "mcp", "sessions", "claude", "codex",
-  "status", "doctor", "tasks", "tenant", "app", "nuke", "skills", "agents",
-  "update", "use", "experimental",
+  "status", "doctor", "report", "tasks", "tenant", "app", "nuke", "skills",
+  "agents", "update", "use", "experimental",
 ]);
 
 const DEFAULT = Object.freeze({

package/src/telemetryConsent.js

@@ -0,0 +1,334 @@
+// The single authority for three questions the telemetry paths must never
+// decide for themselves:
+//
+//   1. May telemetry run *at all* in this process? — `telemetryCaptureAllowed`
+//      and `telemetryFlushAllowed`. A context question, answered by where the
+//      process is running, never by what the user consented to.
+//   2. May analytics be sent? — `analyticsConsentGranted`. A consent question.
+//   3. May a failure report be sent? — `reportEnvOptOut`. A suppression
+//      question, and deliberately a narrower env surface than the second: only
+//      the two branded names silence reports. Bare `CI` and bare `DO_NOT_TRACK`
+//      keep suppressing analytics and keep *not* suppressing reports, because a
+//      machine that never asked to stop reporting its own broken installs is
+//      the machine whose broken installs are hardest to hear about. The two
+//      predicates therefore stay separate rather than one widening into the
+//      other.
+//
+// The context question is the security boundary. A managed vendor app profile
+// is only ever allowed to reach the gateway, so telemetry initializing inside
+// one puts an unexpected egress call in a profile carrying app credentials —
+// it presents as a PAT leak and fails the managed-app launch smoke. Detecting
+// "this is managed" is unbounded (every new vendor surface is a new marker);
+// detecting "a human typed `impel <command>`" is bounded. So capture is a
+// positive allowlist over interactive commands, and the marker list denies on
+// top of it.
+//
+// Flag reads and `impel report` deliberately bypass consent — a kill switch
+// that respects an opt-out is not a kill switch, and a report is the user
+// pressing send — but nothing bypasses the context guard.
+//
+// Every predicate reads its environment from an injected bag rather than
+// `process.env` so the per-surface fixture table in
+// `test/telemetry-consent.test.js` can assert each managed surface denies
+// without spawning that surface.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { environmentValue } from "./nativeProcess.js";
+import { brandedEnvironmentName, RUNTIME_BRAND } from "./runtimeBrand.js";
+
+/** The detached sender. Hidden: never added to `SUPPORTED_COMMANDS`. */
+export const TELEMETRY_FLUSH_COMMAND = "_telemetry";
+
+const DISABLE_TELEMETRY_ENV = brandedEnvironmentName("DISABLE_TELEMETRY");
+export const DO_NOT_TRACK_ENV = brandedEnvironmentName("DO_NOT_TRACK");
+/** Exported alongside `DO_NOT_TRACK_ENV` so help text can name both switches. */
+export const CI_ENV = brandedEnvironmentName("CI");
+const ACCEPTED_TRUE = ["1", "true", "yes"];
+
+/**
+ * Env names whose mere presence means this process is inside a managed
+ * surface. `IMPEL_DT` and the desktop-tasks group are written as literals by
+ * the launchers in `src/apps.js` and `src/desktopTasks.js`, so they are matched
+ * as literals here; the managed-MCP and managed-Cursor markers are branded at
+ * their writers, and both spellings are listed so a rebrand cannot open a hole.
+ *
+ * Managed Cursor is a presence marker rather than a profile path because
+ * `cursorLaunchSpec` deletes the vendor profile vars and repoints `HOME` at the
+ * managed root — there is no path left to key on.
+ */
+const MANAGED_PRESENCE_ENV_NAMES = Object.freeze([
+  brandedEnvironmentName("MANAGED_MCP"),
+  "IMPEL_MANAGED_MCP",
+  brandedEnvironmentName("MANAGED_CURSOR"),
+  "IMPEL_MANAGED_CURSOR",
+  "IMPEL_DT",
+  "IMPEL_DESKTOP_TASKS_TENANT",
+  "IMPEL_DESKTOP_TASKS_CLI",
+  "IMPEL_DESKTOP_TASKS_NODE",
+  "IMPEL_DESKTOP_TASKS_HOST_HTML",
+  "IMPEL_DESKTOP_TASKS_VIEW_PRELOAD",
+]);
+
+/**
+ * Env names carrying a profile directory. These are managed only when the path
+ * lands under one of `managedProfileRoots`; a user's own `~/.claude` is not a
+ * managed surface and must not suppress their telemetry.
+ */
+const MANAGED_PROFILE_ENV_NAMES = Object.freeze([
+  "CLAUDE_CONFIG_DIR",
+  "CLAUDE_USER_DATA_DIR",
+  "CODEX_HOME",
+]);
+
+/**
+ * Commands that are not a human at a terminal, and so never capture. The three
+ * hidden ones are already absent from `RUNTIME_BRAND.capabilities.commands`;
+ * naming them anyway means adding one to that list by mistake cannot silently
+ * open capture on a hidden surface.
+ */
+const NON_INTERACTIVE_COMMANDS = Object.freeze(new Set([
+  "sessions",
+  "mcp",
+  "token",
+  "_converge",
+  "_app-launch",
+  TELEMETRY_FLUSH_COMMAND,
+]));
+
+function nonEmpty(value) {
+  return typeof value === "string" && value.length > 0;
+}
+
+/**
+ * Resolve symlinks through the longest ancestor that exists, then re-append the
+ * rest.
+ *
+ * Plain `realpathSync` throws on a path that does not exist yet, and a managed
+ * profile directory is routinely created *after* this guard runs. Falling back
+ * to the literal string in that case would compare the two sides asymmetrically:
+ * on macOS an existing root under `/tmp` resolves to `/private/tmp` while the
+ * not-yet-created profile beneath it stays `/tmp/...`, and the containment check
+ * would miss — the one direction that leaks. Walking up to the nearest real
+ * ancestor gives both sides the same treatment.
+ *
+ * Only paths this host would call absolute are resolved. A Windows path on a
+ * POSIX host has no existing ancestor to find, and `dirname` would collapse it
+ * to `.` and splice in the working directory.
+ *
+ * Absoluteness is `path.isAbsolute`, not a `/` prefix: on Windows every native
+ * path starts with a drive letter or a backslash, so a `/`-prefix test skips
+ * resolution for exactly the paths Windows would have resolved. That reopens
+ * the symlink escape this function exists to close, and — worse — leaves a
+ * `/tmp/x`-style candidate resolved against the current drive while the
+ * `\tmp\x` root beside it stays literal, which is the asymmetry described
+ * above. `path.isAbsolute` agrees with the old test on every POSIX path.
+ */
+function realPathThroughExisting(value) {
+  if (!path.isAbsolute(value)) return value;
+  const trailing = [];
+  let current = value;
+  for (;;) {
+    try {
+      return path.join(fs.realpathSync(current), ...trailing);
+    } catch {
+      const parent = path.dirname(current);
+      // `dirname("/")` is `"/"`; every absolute path terminates here at worst.
+      if (parent === current) return value;
+      trailing.unshift(path.basename(current));
+      current = parent;
+    }
+  }
+}
+
+/**
+ * Normalize for containment comparison: resolve symlinks so a profile path
+ * pointed into a managed root cannot escape the check, then fold separators and
+ * case. Folding case over-matches on a case-sensitive filesystem holding two
+ * directories that differ only by case — the safe direction for a predicate
+ * whose false answer is the one that leaks.
+ */
+function normalizedPath(value) {
+  return realPathThroughExisting(String(value))
+    .replace(/[\\/]+/gu, "/")
+    .replace(/\/+$/u, "")
+    .toLowerCase();
+}
+
+function pathWithin(candidate, root) {
+  const child = normalizedPath(candidate);
+  const parent = normalizedPath(root);
+  if (!child || !parent) return false;
+  return child === parent || child.startsWith(`${parent}/`);
+}
+
+/**
+ * The roots under which a profile path means "managed".
+ *
+ * Deliberately derived here rather than imported from `apps.js` /
+ * `cliProfiles.js`: this guard sits on the process-start path and must stay a
+ * leaf module, and both of those roots are otherwise frozen at module load,
+ * which an injected `homeDir` could never move. `test/telemetry-consent.test.js`
+ * pins each derivation against its real producer so the duplication cannot
+ * drift.
+ *
+ * The two bases differ on purpose, matching the code that creates them:
+ * `appPaths` builds the apps root from `homeDir` directly (ignoring
+ * `IMPEL_CONFIG_DIR`), while `IMPEL_CLI_PROFILES_DIR` builds from `CONFIG_DIR`.
+ */
+function managedProfileRoots(env, homeDir) {
+  const configDir = environmentValue(env, brandedEnvironmentName("CONFIG_DIR"))
+    || path.join(homeDir, ".config", RUNTIME_BRAND.cli.configNamespace);
+  const localAppData = environmentValue(env, "LOCALAPPDATA")
+    || path.win32.join(environmentValue(env, "USERPROFILE") || homeDir, "AppData", "Local");
+  return [
+    // Managed vendor desktop apps (`appPaths(homeDir).root`).
+    environmentValue(env, brandedEnvironmentName("APP_HOME"))
+      || path.join(homeDir, ".config", RUNTIME_BRAND.cli.configNamespace, "apps"),
+    // Windows Claude keeps its profile outside the config dir entirely
+    // (`windowsClaudeUserData`). Denying the whole `Claude-3p` tree rather than
+    // just the Impel folder keeps a future tenant layout from slipping past.
+    path.win32.join(localAppData, "Claude-3p"),
+    // Isolated CLI profiles (`IMPEL_CLI_PROFILES_DIR`).
+    path.join(configDir, "cli"),
+  ];
+}
+
+/**
+ * True when this process is running inside an Impel-managed surface: a vendor
+ * desktop app, the desktop-tasks host, a managed MCP child, or an isolated CLI
+ * profile. Both context predicates consult exactly this function, so a new
+ * marker can never be added to only one of them.
+ */
+export function managedMarkerPresent(environment = process.env, homeDir = os.homedir()) {
+  const env = environment || {};
+  for (const name of MANAGED_PRESENCE_ENV_NAMES) {
+    // Every writer sets these to "1" or a path, but a deny gate must not be
+    // defeated by a different truthy spelling.
+    if (nonEmpty(environmentValue(env, name))) return true;
+  }
+  const roots = managedProfileRoots(env, homeDir);
+  for (const name of MANAGED_PROFILE_ENV_NAMES) {
+    const value = environmentValue(env, name);
+    if (nonEmpty(value) && roots.some((root) => pathWithin(value, root))) return true;
+  }
+  return false;
+}
+
+/**
+ * The public command a human invoked, or null when this is not an interactive
+ * foreground run. Aliases (`task`, `org`, `apps`, …) are not in the brand's
+ * command list and so read as null: an alias under-counts one event, which is
+ * the correct direction for a fail-closed gate and cheaper than duplicating
+ * `src/cli.js`'s alias table here.
+ */
+function interactiveCommand(argv) {
+  const command = Array.isArray(argv) ? argv[0] : undefined;
+  if (typeof command !== "string" || NON_INTERACTIVE_COMMANDS.has(command)) return null;
+  return RUNTIME_BRAND.capabilities.commands.includes(command) ? command : null;
+}
+
+/**
+ * A rebranded fork runs its own product; it must not report into Impel's
+ * project. This is the same first-party check `maybePrintUpdateNotice` and the
+ * stable-entrypoint work use.
+ *
+ * Exported because automatic failure reporting needs the identical answer: a
+ * fork's broken install is the fork's problem to hear about, and a phone-home
+ * that survives a rebrand is the one bug nobody downstream can see.
+ */
+export function firstPartyCli() {
+  return RUNTIME_BRAND.cli.packageName === "impel-cli";
+}
+
+/** May this process *produce* telemetry events? */
+export function telemetryCaptureAllowed(
+  environment = process.env,
+  argv = process.argv.slice(2),
+  homeDir = os.homedir(),
+) {
+  if (!firstPartyCli()) return false;
+  if (interactiveCommand(argv) === null) return false;
+  return !managedMarkerPresent(environment, homeDir);
+}
+
+/**
+ * May this process *send* a queued batch?
+ *
+ * Split from capture because the sender is not an interactive command: keying
+ * one predicate on interactivity would deny `_telemetry` by name and no batch
+ * would ever leave, while admitting `_telemetry` into the capture predicate
+ * would reopen capture on a hidden surface. The managed-marker denial is
+ * identical on both sides.
+ */
+export function telemetryFlushAllowed(
+  environment = process.env,
+  argv = process.argv.slice(2),
+  homeDir = os.homedir(),
+) {
+  if (!firstPartyCli()) return false;
+  const command = Array.isArray(argv) ? argv[0] : undefined;
+  if (command !== TELEMETRY_FLUSH_COMMAND && interactiveCommand(argv) === null) return false;
+  return !managedMarkerPresent(environment, homeDir);
+}
+
+/**
+ * True when the environment alone says no, whatever the config records.
+ *
+ * Separate from the config check because three surfaces need this answer for
+ * different reasons and must agree: sending consults it, the setup prompt skips
+ * asking a machine that has already refused, and the first-run notice stays
+ * quiet rather than announcing a feature that is already off here.
+ */
+export function analyticsEnvOptOut(environment = process.env) {
+  const env = environment || {};
+  const disabled = String(environmentValue(env, DISABLE_TELEMETRY_ENV) || "").toLowerCase();
+  if (ACCEPTED_TRUE.includes(disabled)) return true;
+  // consumer spec: exactly "1" is the opt-out signal.
+  if (String(environmentValue(env, "DO_NOT_TRACK") || "") === "1") return true;
+  // Any non-empty CI value suppresses, including "0" and "false" — a CI system
+  // that sets CI at all is a CI system. Under-collecting in CI costs a metric;
+  // over-collecting costs trust.
+  if (nonEmpty(environmentValue(env, "CI"))) return true;
+  return false;
+}
+
+/**
+ * True when this machine has asked not to send failure reports.
+ *
+ * Only the two branded names are read. `analyticsEnvOptOut` above additionally
+ * honors bare `DO_NOT_TRACK=1` and any non-empty `CI`, and must keep doing so —
+ * but neither is a statement about failure reports. A CI system that sets `CI`
+ * has said nothing about whether its operators want to hear that `impel setup`
+ * is broken there, and silently deciding for them is how a broken install stays
+ * broken. Suppressing reports takes the branded name, typed on purpose.
+ *
+ * Consequence, accepted rather than papered over: an unmodified CI runner sets
+ * `CI`, not `IMPEL_CI`, so a repeatedly failing `impel setup` in CI reports
+ * every run until someone sets the branded name. That is the cost of the same
+ * rule that makes the signal trustworthy everywhere else.
+ */
+export function reportEnvOptOut(environment = process.env) {
+  const env = environment || {};
+  for (const name of [DO_NOT_TRACK_ENV, CI_ENV]) {
+    const value = String(environmentValue(env, name) || "").toLowerCase();
+    if (ACCEPTED_TRUE.includes(value)) return true;
+  }
+  return false;
+}
+
+/**
+ * Has the user consented to analytics? Opt-in only: an absent or non-boolean
+ * `telemetry.enabled` is a no, and each env opt-out independently overrides a
+ * stored yes.
+ *
+ * This answers consent alone — it does not consult the managed-profile guard.
+ * Callers AND the two, so consent can never talk a managed surface into
+ * sending.
+ */
+export function analyticsConsentGranted(config, environment = process.env) {
+  if (config?.telemetry?.enabled !== true) return false;
+  return !analyticsEnvOptOut(environment);
+}

package/src/telemetryNotice.js

@@ -0,0 +1,147 @@
+// The one-time "this CLI can now send product analytics" notice.
+//
+// Nothing asks. Analytics are opt-in through `impel setup --analytics on`, and
+// a flag nobody knows about is not much of an opt-in — so this notice is the
+// sole disclosure path, for new installs and old ones alike. Without it the
+// first someone would hear of telemetry is a changelog they did not read.
+// Analytics stay off either way — consent is opt-in — but "off by default and
+// we told you" and "off by default and we said nothing" are different products.
+//
+// Two rules shape everything here.
+//
+// **Printing is not consent.** The shown-marker is a separate file from
+// `config.telemetry.enabled` on purpose: no sequence of prints can add up to an
+// opt-in, and no reader of the consent key has to know this file exists.
+//
+// **At most once.** The marker is written *before* the notice prints, and a
+// marker that cannot be persisted suppresses the notice entirely. A config
+// directory this CLI cannot write is a directory where "once" cannot be
+// promised, and a nag on every command is worse than silence — nothing is being
+// collected in the meantime regardless.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { CONFIG_DIR, loadConfig } from "./config.js";
+import { RUNTIME_BRAND } from "./runtimeBrand.js";
+import {
+  analyticsEnvOptOut,
+  telemetryCaptureAllowed,
+} from "./telemetryConsent.js";
+import { renameWithWindowsRetry } from "./windowsFs.js";
+
+/**
+ * Beside `update-check.json` and `flags.json` rather than inside the telemetry
+ * outbox directory: the outbox is redirectable per-process
+ * (`IMPEL_TELEMETRY_STATE_DIR`) and is erased when a batch drains, and neither
+ * is true of a fact about the person using this machine. Still under
+ * `CONFIG_DIR`, so `impel nuke` takes it with everything else.
+ */
+const TELEMETRY_NOTICE_FILE = "telemetry-notice.json";
+
+export const TELEMETRY_NOTICE_PATH = path.join(CONFIG_DIR, TELEMETRY_NOTICE_FILE);
+
+/**
+ * Every entry point below takes `configDir` for the same reason they take
+ * `homeDir` and `stream`: `CONFIG_DIR` is frozen when `src/config.js` is first
+ * imported, so a caller that wants this marker somewhere else — a test, or any
+ * future caller reasoning about a directory other than its own — cannot get
+ * there by moving the environment afterwards. The default is the frozen path,
+ * which is what production always wants.
+ */
+function noticePath(configDir) {
+  return path.join(configDir, TELEMETRY_NOTICE_FILE);
+}
+
+export function telemetryNoticeText() {
+  const command = RUNTIME_BRAND.cli.command;
+  return [
+    `${RUNTIME_BRAND.product.displayName} can now report anonymous CLI usage — which command ran, whether`,
+    "it succeeded, how long it took as a coarse bucket, the CLI version, release",
+    "channel, and platform. Never arguments, file contents, prompts, or session data.",
+    `It is off. Turn it on with \`${command} setup --analytics on\`, or keep it off`,
+    `permanently with \`IMPEL_DISABLE_TELEMETRY=1\`, \`DO_NOT_TRACK=1\`, or any \`CI\` value.`,
+  ].join("\n");
+}
+
+function readMarker(configDir) {
+  try {
+    const marker = JSON.parse(fs.readFileSync(noticePath(configDir), "utf8"));
+    return marker && typeof marker === "object" ? marker : null;
+  } catch {
+    return null;
+  }
+}
+
+/** True once the notice has been printed on this machine. */
+export function telemetryNoticeShown({ configDir = CONFIG_DIR } = {}) {
+  return typeof readMarker(configDir)?.shownAt === "string";
+}
+
+/**
+ * Persist the shown-marker. Returns false when it could not be written, which
+ * both callers read as "do not print".
+ *
+ * `impel setup` calls this too, on every path including the silent ones: having
+ * run setup at all is the event the first-run notice exists to announce, so
+ * someone who has just been through it is not told again on their next command.
+ */
+export function markTelemetryNoticeShown({ now = Date.now(), configDir = CONFIG_DIR } = {}) {
+  const contents = `${JSON.stringify({ shownAt: new Date(now).toISOString() }, null, 2)}\n`;
+  const markerPath = noticePath(configDir);
+  const temporaryPath = `${markerPath}.tmp-${process.pid}`;
+  try {
+    fs.mkdirSync(configDir, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(temporaryPath, contents, { mode: 0o600 });
+    renameWithWindowsRetry(temporaryPath, markerPath);
+    return true;
+  } catch {
+    return false;
+  } finally {
+    try {
+      fs.rmSync(temporaryPath, { force: true });
+    } catch {
+      // A successful rename already removed it; cleanup must not mask the write.
+    }
+  }
+}
+
+/**
+ * Print the notice at most once, or do nothing.
+ *
+ * Called from `main` before dispatch rather than from `maybePrintUpdateNotice`:
+ * that helper is wired into `status` and the app commands only, so the people
+ * who live in `impel claude` and `impel codex` — the ones this notice is for —
+ * would never see it. The same reasoning rejected it as the flush hook.
+ *
+ * `telemetryCaptureAllowed` is the gate because it already answers the exact
+ * question: first-party CLI, interactive foreground command, no managed-surface
+ * marker. Anything that cannot emit an event has nothing to disclose.
+ */
+export function maybePrintTelemetryNotice({
+  argv = process.argv.slice(2),
+  environment = process.env,
+  homeDir = os.homedir(),
+  stream = process.stderr,
+  config = undefined,
+  now = Date.now(),
+  configDir = CONFIG_DIR,
+} = {}) {
+  try {
+    if (!stream?.isTTY) return false;
+    if (!telemetryCaptureAllowed(environment, argv, homeDir)) return false;
+    // Already answered yes, or already switched off by the environment — in
+    // both cases there is no pending question to raise.
+    if (analyticsEnvOptOut(environment)) return false;
+    if ((config === undefined ? loadConfig() : config)?.telemetry?.enabled === true) return false;
+    if (telemetryNoticeShown({ configDir })) return false;
+
+    if (!markTelemetryNoticeShown({ now, configDir })) return false;
+    stream.write(`${telemetryNoticeText()}\n`);
+    return true;
+  } catch {
+    // A notice is a courtesy. It must never be the reason a command fails.
+    return false;
+  }
+}

package/src/tenants.js

@@ -42,6 +42,33 @@ export function productAccessLabel(value) {
   return "Unknown";
 }
 
+/**
+ * Who the PAT resolves to, as reported by `/api/cli/tenants`.
+ *
+ * Local display and a correlation hint only — the server stamps identity on
+ * everything it records and never trusts this copy. So a control plane that
+ * predates the field, or one that returns something unreadable, is not an
+ * error: `allowMissing` yields `null`, and every writer deletes the key rather
+ * than leaving a stale user attached to a new PAT.
+ *
+ * `displayName` is omitted rather than fabricated when identity has none, so a
+ * caller can fall back to the id instead of rendering an empty string.
+ */
+export function normalizeCliUser(value, { allowMissing = false } = {}) {
+  if ((value === undefined || value === null) && allowMissing) return null;
+  const id = typeof value?.id === "string" ? value.id.trim() : "";
+  if (!id || id.length > 256) {
+    if (allowMissing) return null;
+    throw new Error("tenant API returned an invalid user");
+  }
+  const user = { id: redactSecretText(id) };
+  const displayName = typeof value.displayName === "string"
+    ? redactSecretText(value.displayName).trim().slice(0, 256)
+    : "";
+  if (displayName) user.displayName = displayName;
+  return user;
+}
+
 export function normalizePatScopes(value, { allowMissing = false } = {}) {
   if ((value === undefined || value === null) && allowMissing) return null;
   if (!Array.isArray(value) || value.some((scope) => typeof scope !== "string" || !PAT_SCOPE_RE.test(scope))) {
@@ -131,6 +158,7 @@ export async function fetchTenants(config, fetchImpl = fetchHttp1) {
   // during a staged rollout, but never infer a privileged access level here.
   const productAccess = normalizeProductAccess(payload.productAccess, { allowMissing: true });
   const scopes = normalizePatScopes(payload.scopes, { allowMissing: true });
+  const user = normalizeCliUser(payload.user, { allowMissing: true });
   const tenants = payload.tenants.map((tenant) => {
     const id = normalizeTenantId(tenant?.id || tenant?.slug);
     return {
@@ -156,9 +184,22 @@ export async function fetchTenants(config, fetchImpl = fetchHttp1) {
     patTenantId: payload.patTenantId || null,
     productAccess,
     scopes,
+    user,
   };
 }
 
+/**
+ * Apply a listing's `user` to a config object.
+ *
+ * Every config writer calls this instead of inlining the clause: the field
+ * would otherwise appear and vanish depending on which command last wrote
+ * config, and a `user` left over from a previous PAT is worse than none.
+ */
+export function applyCliUser(config, listing) {
+  if (listing?.user) config.user = listing.user;
+  else delete config.user;
+}
+
 export async function ensureTenantSelection(config, { refresh = false } = {}) {
   if (!config?.pat) throw new Error(`not authenticated; run \`${RUNTIME_BRAND.cli.command} setup\` (or \`${RUNTIME_BRAND.cli.command} auth\`) first`);
   if (config.tenantId && !refresh) {
@@ -176,6 +217,7 @@ export async function ensureTenantSelection(config, { refresh = false } = {}) {
       defaultTenantId: null,
       productAccess: normalizeProductAccess(config.productAccess, { allowMissing: true }),
       scopes: normalizePatScopes(config.scopes, { allowMissing: true }),
+      user: normalizeCliUser(config.user, { allowMissing: true }),
     };
   }
 
@@ -190,6 +232,7 @@ export async function ensureTenantSelection(config, { refresh = false } = {}) {
   else delete config.productAccess;
   if (listing.scopes) config.scopes = listing.scopes;
   else delete config.scopes;
+  applyCliUser(config, listing);
   config.tenantsUpdatedAt = new Date().toISOString();
   saveConfig(config);
   return {
@@ -201,6 +244,10 @@ export async function ensureTenantSelection(config, { refresh = false } = {}) {
     defaultTenantId: listing.defaultTenantId,
     productAccess: listing.productAccess,
     scopes: listing.scopes,
+    // The cached branch above returns `user`, so omitting it here would make
+    // the field's presence depend on whether the caller passed `refresh` —
+    // and the refresh branch is the one that just fetched a fresh identity.
+    user: listing.user,
   };
 }
 
@@ -217,6 +264,7 @@ export async function selectTenant(config, tenantId) {
   else delete config.productAccess;
   if (listing.scopes) config.scopes = listing.scopes;
   else delete config.scopes;
+  applyCliUser(config, listing);
   config.tenantsUpdatedAt = new Date().toISOString();
   saveConfig(config);
   return { tenant, listing };

package/src/updates.js

@@ -295,9 +295,26 @@ export function spawnDetachedAppRefresh(tenantId = null) {
   ]);
 }
 
-function spawnDetached(args) {
+/**
+ * Background telemetry send. Lives here beside the other detached spawns so
+ * `spawnDetached`'s Windows-console handling has exactly one implementation,
+ * and so `src/posthog.js` — which decides *whether* to send — does not also
+ * own the process-spawning mechanics.
+ *
+ * The child is marked so it can adopt the flush lock its parent already took
+ * out; without that it would find the lock held, exit having sent nothing, and
+ * leave the spool to drain only after the lock went stale.
+ */
+export function spawnDetachedTelemetryFlush() {
+  spawnDetached(["_telemetry", "flush"], {
+    [brandedEnvironmentName("TELEMETRY_FLUSH_CHILD")]: "1",
+  });
+}
+
+function spawnDetached(args, extraEnvironment = null) {
   try {
     const child = spawn(process.execPath, [IMPEL_CLI_ENTRYPOINT, ...args], {
+      ...(extraEnvironment ? { env: { ...process.env, ...extraEnvironment } } : {}),
       detached: true,
       stdio: "ignore",
       // Windows: a detached console-subsystem child gets its OWN console — a
@@ -305,6 +322,14 @@ function spawnDetached(args) {
       // the same option startDetachedFlush already passes.
       windowsHide: true,
     });
+    // `spawn` reports an OS-level exec failure asynchronously, as an 'error'
+    // event — the try/catch around it cannot see one. An 'error' event with no
+    // listener is thrown, so without this the parent dies with exit code 1 the
+    // instant the spawn fails, overwriting the exit code its own command
+    // already decided on. The telemetry flush runs from `main()`'s finally on
+    // every command exit, so that would be a crash on the one path whose whole
+    // contract is that the outcome survives unchanged.
+    child.on("error", () => {});
     child.unref();
   } catch {
     // Purely opportunistic; the next explicit `impel update` still works.