impel-cli 0.20.45 → 0.20.46-beta.0

package/src/posthog.js

@@ -0,0 +1,833 @@
+// The CLI half of product telemetry: a disk outbox plus a detached sender.
+//
+// Two properties shape every decision here.
+//
+// It never blocks. `captureEvent` validates and appends one small file, then
+// returns; nothing on a command's foreground path waits on a network call. The
+// send happens in a separate detached process (`impel _telemetry flush`) that
+// the exiting command spawns and never waits for.
+//
+// It never leaks. Events are validated against an allowlist embedded from the
+// server's own projection — an event name, property key, or value the contract
+// does not name is rejected locally, before it reaches disk. On top of that, a
+// redaction tripwire re-reads the serialized event and refuses to spool
+// anything that still looks like a credential after redaction.
+//
+// The tripwire firing is a bug, not a routine outcome, so it is *observable*:
+// the event is dropped, a bounded local notice is written, and `impel status`
+// prints it. `src/nativeAgentTelemetry.js` throws into a silent catch in the
+// same situation; that is right for opt-in performance traces nobody is
+// waiting on and wrong here, where a silent drop is indistinguishable from
+// working telemetry.
+//
+// Everything this module writes lives under `CONFIG_DIR`, so `impel nuke`
+// erases it along with the rest of the local state.
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  CONFIG_DIR,
+  loadConfig,
+  normalizeGatewayUrl,
+  redactCredentialText,
+  redactSecretText,
+  resolveDefaultAppUrl,
+} from "./config.js";
+import {
+  FEATURE_NOT_ENABLED_EXIT_CODE,
+  FLAG_STATE_UNKNOWN_EXIT_CODE,
+  TELEMETRY_FLUSH_FAILED_EXIT_CODE,
+} from "./exitCodes.js";
+import { fetchHttp1 } from "./http1.js";
+import { brandedEnvironmentName } from "./runtimeBrand.js";
+import {
+  analyticsConsentGranted,
+  TELEMETRY_FLUSH_COMMAND,
+  telemetryCaptureAllowed,
+  telemetryFlushAllowed,
+} from "./telemetryConsent.js";
+
+export { TELEMETRY_FLUSH_COMMAND };
+import { installedVersion, spawnDetachedTelemetryFlush, updateTagForVersion } from "./updates.js";
+import { renameWithWindowsRetry } from "./windowsFs.js";
+
+/**
+ * The closed allowlist, embedded from `next`'s generated projection.
+ *
+ * This is a deliberate second copy of a contract that also lives in the server
+ * repo: the CLI ships without runtime dependencies and cannot import it, and a
+ * client that validates against something *other* than what the server accepts
+ * would discover the difference as a 400 in production.
+ *
+ * Regenerate it from `next`'s projection at
+ * `src/features/cli-telemetry/contracts/cli-telemetry-contract.json` whenever
+ * that changes; the two are kept in step by review and by CI with both repos
+ * checked out, not by anything in this repo alone. Local tests can only check
+ * this copy's internal shape — see `test/cli-telemetry-contract.test.js`.
+ */
+export const TELEMETRY_CONTRACT = Object.freeze({
+  schema: "impel.cli-telemetry-contract.v1",
+  protocolVersion: 1,
+  limits: {
+    maxEventsPerBatch: 100,
+    maxEventPropertyKeys: 24,
+    maxPropertyKeyLength: 64,
+    maxPropertyValueLength: 256,
+    maxSerializedBatchBytes: 262144,
+    maxSerializedBugReportBytes: 131072,
+    maxFlagsPerResponse: 64,
+  },
+  reservedIdentityPropertyKeys: [
+    "$device_id",
+    "$group_key",
+    "$group_set",
+    "$groups",
+    "$process_person_profile",
+    "$session_id",
+    "$set",
+    "$set_once",
+    "$user_id",
+    "api_key",
+    "distinct_id",
+    "uuid",
+  ],
+  featureFlagKeys: ["cli-cursor-experiment"],
+  bugReportReasons: ["scope_required", "task_creation_failed", "workspace_required"],
+  events: [
+    {
+      name: "cli_bug_report",
+      origin: "server",
+      properties: [
+        { key: "channel", type: "string", required: true, values: ["latest", "next"] },
+        { key: "cliVersion", type: "string", required: true, maxLength: 32 },
+        { key: "hasMessage", type: "boolean", required: true },
+        {
+          key: "platform",
+          type: "string",
+          required: true,
+          values: ["darwin", "linux", "unknown", "win32"],
+        },
+        {
+          key: "reason",
+          type: "string",
+          required: false,
+          values: ["scope_required", "task_creation_failed", "workspace_required"],
+        },
+        { key: "taskCreated", type: "boolean", required: true },
+      ],
+    },
+    {
+      name: "cli_command_run",
+      origin: "cli",
+      properties: [
+        { key: "channel", type: "string", required: true, values: ["latest", "next"] },
+        { key: "cliVersion", type: "string", required: true, maxLength: 32 },
+        { key: "command", type: "string", required: true, maxLength: 64 },
+        {
+          key: "durationBucket",
+          type: "string",
+          required: true,
+          values: ["lt_1s", "lt_5s", "lt_30s", "lt_2m", "gte_2m"],
+        },
+        {
+          key: "outcome",
+          type: "string",
+          required: true,
+          values: ["failure", "refused", "success"],
+        },
+        {
+          key: "platform",
+          type: "string",
+          required: true,
+          values: ["darwin", "linux", "unknown", "win32"],
+        },
+      ],
+    },
+  ],
+});
+
+/** The route this module posts to. */
+export const TELEMETRY_ENDPOINT_PATH = "/api/cli/telemetry";
+
+/** Set on the detached sender so it can adopt the lock its parent created. */
+export const TELEMETRY_FLUSH_CHILD_ENV = brandedEnvironmentName("TELEMETRY_FLUSH_CHILD");
+
+const REQUEST_TIMEOUT_MS = 10_000;
+
+/**
+ * How long a transient failure suppresses further attempts. Long enough that a
+ * gateway outage costs one request per half hour rather than one per command,
+ * short enough that a recovered gateway is noticed the same session.
+ */
+const TRANSIENT_BACKOFF_MS = 30 * 60_000;
+
+/**
+ * How long a 404 disables capture. R16: a `next` that predates the route is a
+ * deployment-ordering state, not an error — it must cost nothing and heal
+ * without user action. A day is well past any rollout window.
+ */
+const DISABLED_TTL_MS = 24 * 60 * 60_000;
+
+/** Permanent-failure attempts before a batch is quarantined rather than retried. */
+const MAX_BATCH_FAILURES = 3;
+
+/** Spool ceiling. Beyond this the oldest events are dropped with a notice. */
+const MAX_SPOOLED_EVENTS = 500;
+
+/** Quarantine ceiling; the oldest quarantined events are discarded past it. */
+const MAX_QUARANTINED_EVENTS = 100;
+
+/** A local problem stops being news after a week. */
+const NOTICE_TTL_MS = 7 * 24 * 60 * 60_000;
+
+/** A flush lock older than this belonged to a process that died mid-send. */
+const LOCK_STALE_MS = 60_000;
+
+/**
+ * Property values are identifiers, versions, and enum members — never free
+ * text. Constraining the character set as well as the length means a value
+ * that somehow carried a credential fragment or an escape sequence is rejected
+ * by shape before the tripwire has to catch it by content.
+ */
+const SAFE_VALUE_RE = /^[A-Za-z0-9 _.:@/+-]{1,256}$/u;
+
+/** HTTP statuses where resending the identical batch cannot succeed. */
+const PERMANENT_STATUSES = new Set([
+  400, // Allowlist violation: the server rejected the batch's shape.
+  413, // Oversize: the batch exceeds what the route will read.
+  422, // Semantically rejected.
+]);
+
+const EVENTS_BY_NAME = new Map(TELEMETRY_CONTRACT.events.map((event) => [event.name, event]));
+const RESERVED_KEYS = new Set(TELEMETRY_CONTRACT.reservedIdentityPropertyKeys);
+
+function telemetryRoot() {
+  return process.env[brandedEnvironmentName("TELEMETRY_STATE_DIR")]
+    || path.join(CONFIG_DIR, "telemetry");
+}
+
+function spoolDirectory() {
+  return path.join(telemetryRoot(), "spool");
+}
+
+function quarantineDirectory() {
+  return path.join(telemetryRoot(), "quarantine");
+}
+
+function statePath() {
+  return path.join(telemetryRoot(), "state.json");
+}
+
+function noticePath() {
+  return path.join(telemetryRoot(), "notice.json");
+}
+
+function lockPath() {
+  return path.join(telemetryRoot(), "flush.lock");
+}
+
+function privateDirectory(directory) {
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  try {
+    fs.chmodSync(directory, 0o700);
+  } catch {
+    // Best effort on platforms without POSIX modes.
+  }
+}
+
+function atomicWrite(filePath, contents) {
+  privateDirectory(path.dirname(filePath));
+  const temporaryPath = `${filePath}.tmp-${process.pid}-${crypto.randomUUID()}`;
+  try {
+    fs.writeFileSync(temporaryPath, contents, { mode: 0o600 });
+    renameWithWindowsRetry(temporaryPath, filePath);
+  } finally {
+    try {
+      fs.rmSync(temporaryPath, { force: true });
+    } catch {
+      // A successful rename already removed it; cleanup must not mask the write.
+    }
+  }
+}
+
+function readJson(filePath, fallback = null) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+function removeQuietly(filePath) {
+  try {
+    fs.rmSync(filePath, { force: true });
+  } catch {
+    // A file we cannot remove is retried on the next flush.
+  }
+}
+
+/* -------------------------------------------------------------------------- */
+/* Durable state                                                              */
+/* -------------------------------------------------------------------------- */
+
+function readState() {
+  const state = readJson(statePath());
+  return state && typeof state === "object" ? state : {};
+}
+
+function writeState(patch) {
+  const next = { ...readState(), ...patch };
+  atomicWrite(statePath(), `${JSON.stringify(next, null, 2)}\n`);
+  return next;
+}
+
+/**
+ * True while the route is known-absent. R16's quiet disable: an older `next`
+ * has no telemetry route, and the CLI must neither spool events it can never
+ * deliver nor tell the user about a deployment they do not control.
+ *
+ * The marker expires rather than being cleared by a probe, so the re-probe
+ * costs one request per day instead of one per command.
+ */
+function telemetryDisabled(state, now) {
+  return Number.isFinite(state.disabledUntil) && state.disabledUntil > now;
+}
+
+function flushBackedOff(state, now) {
+  return Number.isFinite(state.retryAfter) && state.retryAfter > now;
+}
+
+/* -------------------------------------------------------------------------- */
+/* Local notices                                                              */
+/* -------------------------------------------------------------------------- */
+
+const NOTICE_REASONS = Object.freeze({
+  redaction_tripwire: "an event looked like it still contained a credential after redaction",
+  quarantined: "the server rejected them and they were discarded",
+  overflow: "the local queue was full",
+});
+
+/**
+ * Record that events were dropped locally.
+ *
+ * `kind` selects a fixed sentence from `NOTICE_REASONS`; no caller-supplied
+ * text is stored. That is deliberate for the tripwire in particular: it fires
+ * *because* redaction was incomplete, so echoing the offending value into a
+ * file — and from there into `impel status` output — would persist and print
+ * exactly the credential the tripwire just caught.
+ */
+function noteDroppedEvents(kind, count, now = Date.now()) {
+  if (!NOTICE_REASONS[kind] || count < 1) return;
+  const previous = readJson(noticePath());
+  const carried = previous?.kind === kind && Number.isSafeInteger(previous.count) ? previous.count : 0;
+  try {
+    atomicWrite(noticePath(), `${JSON.stringify({
+      at: new Date(now).toISOString(),
+      kind,
+      count: Math.min(carried + count, Number.MAX_SAFE_INTEGER),
+    }, null, 2)}\n`);
+  } catch {
+    // The notice is an observability aid; failing to write it must not turn a
+    // dropped event into a failed command.
+  }
+}
+
+function clearNotice() {
+  removeQuietly(noticePath());
+}
+
+/**
+ * The one-line drop notice for `impel status`, or null when there is nothing
+ * to say. Exported so the status command reads it through its injectable `io`
+ * bag rather than reaching into this module's files.
+ */
+export function telemetryNoticeLine({ now = Date.now() } = {}) {
+  const notice = readJson(noticePath());
+  const reason = NOTICE_REASONS[notice?.kind];
+  if (!reason || !Number.isSafeInteger(notice.count) || notice.count < 1) return null;
+  const at = Date.parse(notice.at);
+  if (!Number.isFinite(at) || now - at > NOTICE_TTL_MS) return null;
+  const events = notice.count === 1 ? "1 event" : `${notice.count} events`;
+  return `Telemetry: ${events} dropped locally because ${reason}; nothing was sent.`;
+}
+
+/* -------------------------------------------------------------------------- */
+/* Validation                                                                 */
+/* -------------------------------------------------------------------------- */
+
+function validatedValue(spec, value) {
+  if (spec.type === "boolean") return typeof value === "boolean" ? value : undefined;
+  if (typeof value !== "string") return undefined;
+  if (!SAFE_VALUE_RE.test(value)) return undefined;
+  if (value.length > TELEMETRY_CONTRACT.limits.maxPropertyValueLength) return undefined;
+  if (spec.values && !spec.values.includes(value)) return undefined;
+  if (spec.maxLength && value.length > spec.maxLength) return undefined;
+  return value;
+}
+
+/**
+ * Build the wire event for `name`, or null when anything about it falls
+ * outside the contract. Rejecting here rather than at the server keeps a
+ * client bug from becoming a 400 loop that quarantines real data.
+ */
+function contractEvent(name, properties) {
+  const spec = EVENTS_BY_NAME.get(name);
+  // `origin: "server"` events are minted by `next` from data it already holds.
+  // A CLI that could post one would be asserting a server-side fact.
+  if (!spec || spec.origin !== "cli") return null;
+
+  const supplied = properties && typeof properties === "object" ? properties : {};
+  const keys = Object.keys(supplied);
+  if (keys.length > TELEMETRY_CONTRACT.limits.maxEventPropertyKeys) return null;
+  for (const key of keys) {
+    if (key.length > TELEMETRY_CONTRACT.limits.maxPropertyKeyLength) return null;
+    // The server strips forged identity keys rather than rejecting them, so a
+    // client that sent one would be silently ignored. Refusing locally means
+    // the mistake is visible where it can be fixed.
+    if (RESERVED_KEYS.has(key)) return null;
+    if (!spec.properties.some((property) => property.key === key)) return null;
+  }
+
+  const result = {};
+  for (const property of spec.properties) {
+    const raw = supplied[property.key];
+    if (raw === undefined) {
+      if (property.required) return null;
+      continue;
+    }
+    const value = validatedValue(property, raw);
+    if (value === undefined) return null;
+    result[property.key] = value;
+  }
+  return { event: name, properties: result };
+}
+
+/**
+ * True when the serialized event survives redaction unchanged.
+ *
+ * Same construction as `nativeAgentTelemetry.js`: if redacting the text
+ * changes it, the text contained something redaction recognizes as a secret,
+ * and no schema check caught it.
+ */
+function redactionClean(serialized) {
+  return redactCredentialText(serialized) === serialized
+    && redactSecretText(serialized) === serialized;
+}
+
+/* -------------------------------------------------------------------------- */
+/* Capture                                                                    */
+/* -------------------------------------------------------------------------- */
+
+function spoolFileName(now) {
+  return `${String(now).padStart(15, "0")}-${crypto.randomUUID()}.json`;
+}
+
+function spooledFiles(directory = spoolDirectory()) {
+  try {
+    // Names lead with a zero-padded timestamp, so lexicographic order is
+    // chronological and the oldest event is always the batch's first element.
+    return fs.readdirSync(directory).filter((name) => name.endsWith(".json")).sort();
+  } catch {
+    return [];
+  }
+}
+
+function enforceSpoolCeiling(now) {
+  const directory = spoolDirectory();
+  const names = spooledFiles(directory);
+  const excess = names.length - MAX_SPOOLED_EVENTS;
+  if (excess <= 0) return;
+  for (const name of names.slice(0, excess)) removeQuietly(path.join(directory, name));
+  noteDroppedEvents("overflow", excess, now);
+}
+
+/**
+ * Validate, redaction-check, and spool one event.
+ *
+ * Returns true when the event reached disk. Never throws: this runs on the way
+ * out of every command, and a telemetry problem must not become the user's
+ * problem.
+ */
+export function captureEvent(name, properties, options = {}) {
+  const {
+    now = Date.now(),
+    environment = process.env,
+    homeDir = os.homedir(),
+    // The consent guard keys on the command being run, not on the event, so
+    // the caller passes the command it is reporting about. Defaulting to the
+    // real argv keeps a direct `captureEvent` call honest.
+    argv = process.argv.slice(2),
+    config = undefined,
+  } = options;
+  try {
+    if (!telemetryCaptureAllowed(environment, argv, homeDir)) return false;
+    if (!analyticsConsentGranted(config === undefined ? loadConfig() : config, environment)) return false;
+    if (telemetryDisabled(readState(), now)) return false;
+
+    const event = contractEvent(name, properties);
+    if (!event) return false;
+
+    const record = { ...event, timestamp: new Date(now).toISOString() };
+    const serialized = JSON.stringify(record);
+    if (!redactionClean(serialized)) {
+      noteDroppedEvents("redaction_tripwire", 1, now);
+      return false;
+    }
+
+    atomicWrite(path.join(spoolDirectory(), spoolFileName(now)), `${serialized}\n`);
+    enforceSpoolCeiling(now);
+    return true;
+  } catch {
+    // Disk full, a read-only config dir, a clock that produces a bad date —
+    // every one of these is a reason to lose a metric, never a reason to fail
+    // the command the user actually ran.
+    return false;
+  }
+}
+
+/* -------------------------------------------------------------------------- */
+/* Command-run capture                                                        */
+/* -------------------------------------------------------------------------- */
+
+const SUPPORTED_PLATFORMS = new Set(["darwin", "linux", "win32"]);
+
+export function platformLabel(platform = process.platform) {
+  return SUPPORTED_PLATFORMS.has(platform) ? platform : "unknown";
+}
+
+export function durationBucket(milliseconds) {
+  if (!Number.isFinite(milliseconds) || milliseconds < 0) return "lt_1s";
+  if (milliseconds < 1_000) return "lt_1s";
+  if (milliseconds < 5_000) return "lt_5s";
+  if (milliseconds < 30_000) return "lt_30s";
+  if (milliseconds < 120_000) return "lt_2m";
+  return "gte_2m";
+}
+
+/**
+ * Exit codes that mean the CLI declined on purpose. Both are set by the flag
+ * gate, which returns normally rather than throwing, so without this set they
+ * would be indistinguishable from a crash in the data — and the refusal rate is
+ * the signal the fail-closed gate exists to make queryable.
+ *
+ * `REPORT_SPOOLED_EXIT_CODE` is deliberately absent: the send genuinely did not
+ * happen, so it stays a failure.
+ */
+const REFUSAL_EXIT_CODES = Object.freeze(new Set([
+  FLAG_STATE_UNKNOWN_EXIT_CODE,
+  FEATURE_NOT_ENABLED_EXIT_CODE,
+]));
+
+function commandOutcome(threw, exitCode) {
+  if (threw) return "failure";
+  if (!Number.isInteger(exitCode) || exitCode === 0) return "success";
+  return REFUSAL_EXIT_CODES.has(exitCode) ? "refused" : "failure";
+}
+
+/**
+ * Capture one `cli_command_run`.
+ *
+ * `outcome` is derived from what the process is about to do, not from what the
+ * command believes: a throw is a failure, a deliberate-refusal exit code is a
+ * refusal, and any other non-zero code is a failure. A declined `impel report`
+ * confirmation exits 0 and so still reads as a success — reaching it would take
+ * an explicit outcome passed down from the command, not a code to read.
+ */
+export function captureCommandRun({
+  command,
+  durationMs,
+  threw = false,
+  exitCode = process.exitCode,
+  platform = process.platform,
+  version = process.env.IMPEL_CLI_EXTENSION_VERSION || installedVersion(),
+  now = Date.now(),
+  ...options
+} = {}) {
+  const resolvedVersion = typeof version === "string" && version ? version.slice(0, 32) : "unknown";
+  return captureEvent("cli_command_run", {
+    channel: updateTagForVersion(resolvedVersion),
+    cliVersion: resolvedVersion,
+    command: typeof command === "string" ? command.slice(0, 64) : "",
+    durationBucket: durationBucket(durationMs),
+    outcome: commandOutcome(threw, exitCode),
+    platform: platformLabel(platform),
+  }, { ...options, argv: [command], now });
+}
+
+/* -------------------------------------------------------------------------- */
+/* Flush lock                                                                 */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Take the flush lock, or return null when another sender holds it.
+ *
+ * The parent takes this lock *before* spawning and does not release it — the
+ * child inherits ownership and releases it when the send finishes. Locking at
+ * the spawn seam rather than inside the child is what makes two commands
+ * exiting at the same instant produce one sender instead of two racing to
+ * acquire it after both have already spawned.
+ */
+export function acquireFlushLock({ now = Date.now(), adopt = false } = {}) {
+  const lock = lockPath();
+  privateDirectory(telemetryRoot());
+  const token = crypto.randomUUID();
+  const release = () => {
+    const current = readJson(lock);
+    // Only the owner clears it; a process whose lock was taken over as stale
+    // must not delete the successor's.
+    if (current?.token === token) removeQuietly(lock);
+  };
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      const descriptor = fs.openSync(lock, "wx", 0o600);
+      fs.writeFileSync(descriptor, `${JSON.stringify({ token, pid: process.pid, at: now })}\n`);
+      fs.closeSync(descriptor);
+      return release;
+    } catch (error) {
+      if (error?.code !== "EEXIST") return null;
+    }
+    const owner = readJson(lock);
+    const age = Number.isFinite(owner?.at) ? now - owner.at : Number.POSITIVE_INFINITY;
+    // `adopt` is the spawned child claiming the lock its own parent took out.
+    // Without it the child would always see a fresh lock and exit having sent
+    // nothing, and the spool would never drain.
+    if (!adopt && age <= LOCK_STALE_MS) return null;
+    removeQuietly(lock);
+  }
+  return null;
+}
+
+/* -------------------------------------------------------------------------- */
+/* Flush                                                                      */
+/* -------------------------------------------------------------------------- */
+
+function batchWithinLimit(records, names) {
+  let events = records;
+  let files = names;
+  // The server rejects an oversize batch outright, so trim before sending
+  // rather than discovering the ceiling as a 413 that quarantines real events.
+  while (events.length > 1
+    && JSON.stringify({ events }).length > TELEMETRY_CONTRACT.limits.maxSerializedBatchBytes) {
+    events = events.slice(0, events.length - 1);
+    files = files.slice(0, events.length);
+  }
+  return { events, files };
+}
+
+function quarantineBatch(files, now) {
+  const source = spoolDirectory();
+  const target = quarantineDirectory();
+  privateDirectory(target);
+  for (const name of files) {
+    try {
+      renameWithWindowsRetry(path.join(source, name), path.join(target, name));
+    } catch {
+      // The fallback deletes evidence, so it must only run once the retry has
+      // ruled out a scanner holding the file open for a moment.
+      removeQuietly(path.join(source, name));
+    }
+  }
+  const retained = spooledFiles(target);
+  const excess = retained.length - MAX_QUARANTINED_EVENTS;
+  if (excess > 0) {
+    for (const name of retained.slice(0, excess)) removeQuietly(path.join(target, name));
+  }
+  noteDroppedEvents("quarantined", files.length, now);
+}
+
+/**
+ * Classify a response. Explicitly enumerated rather than derived from the
+ * status class: "4xx is permanent" would quarantine a batch on the 401 a
+ * re-authentication fixes, and "5xx is transient" would retry a 501 forever.
+ */
+function failureKind(status) {
+  if (status === 404) return "absent";
+  if (PERMANENT_STATUSES.has(status)) return "permanent";
+  return "transient";
+}
+
+/**
+ * Send one batch of spooled events.
+ *
+ * Returns a status describing what happened to the spool, never throwing: the
+ * caller is a detached process whose only jobs are to drain the spool and set
+ * an exit code.
+ */
+export async function flushOutbox(options = {}) {
+  const {
+    fetchImpl = fetchHttp1,
+    now = Date.now(),
+    config = loadConfig(),
+    timeoutMs = REQUEST_TIMEOUT_MS,
+  } = options;
+
+  const state = readState();
+  if (telemetryDisabled(state, now)) return { status: "disabled", sent: 0 };
+  if (flushBackedOff(state, now)) return { status: "backoff", sent: 0 };
+  if (!config?.pat) return { status: "unauthenticated", sent: 0 };
+
+  const directory = spoolDirectory();
+  const names = spooledFiles(directory).slice(0, TELEMETRY_CONTRACT.limits.maxEventsPerBatch);
+  if (names.length === 0) return { status: "empty", sent: 0 };
+
+  const loaded = [];
+  const readable = [];
+  for (const name of names) {
+    const record = readJson(path.join(directory, name));
+    // A truncated or hand-edited spool file is unsendable. Drop it silently:
+    // it carries no user-visible data and nothing downstream can act on it.
+    if (!record?.event) {
+      removeQuietly(path.join(directory, name));
+      continue;
+    }
+    loaded.push(record);
+    readable.push(name);
+  }
+  if (loaded.length === 0) return { status: "empty", sent: 0 };
+
+  const { events, files } = batchWithinLimit(loaded, readable);
+  const appUrl = normalizeGatewayUrl(config.appUrl || resolveDefaultAppUrl());
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  let response;
+  try {
+    response = await fetchImpl(new URL(TELEMETRY_ENDPOINT_PATH, appUrl), {
+      method: "POST",
+      headers: {
+        accept: "application/json",
+        authorization: `Bearer ${config.pat}`,
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({ events }),
+      signal: controller.signal,
+    });
+  } catch {
+    // A network error, a DNS failure, or our own timeout. The spool is left
+    // exactly as it was and the failure count is untouched — an unreachable
+    // gateway must never look like a poisoned batch.
+    writeState({ retryAfter: now + TRANSIENT_BACKOFF_MS });
+    return { status: "transient", sent: 0 };
+  } finally {
+    clearTimeout(timeout);
+  }
+
+  if (response.ok) {
+    for (const name of files) removeQuietly(path.join(directory, name));
+    // `{accepted: true, forwarded: 0}` is the success path for a deployment
+    // with no PostHog configured — accepted-and-dropped, not a failure.
+    writeState({ retryAfter: 0, failures: {}, disabledUntil: 0 });
+    clearNotice();
+    return { status: "sent", sent: files.length };
+  }
+
+  const kind = failureKind(response.status);
+  if (kind === "absent") {
+    // R16: this `next` predates the route. Discard the batch — it can never be
+    // delivered — and stop capturing until the marker expires.
+    for (const name of files) removeQuietly(path.join(directory, name));
+    writeState({ disabledUntil: now + DISABLED_TTL_MS, retryAfter: 0, failures: {} });
+    return { status: "disabled", sent: 0 };
+  }
+  if (kind === "transient") {
+    writeState({ retryAfter: now + TRANSIENT_BACKOFF_MS });
+    return { status: "transient", sent: 0, httpStatus: response.status };
+  }
+
+  // Permanent. Count against the batch's oldest event rather than the whole
+  // set, so a capture landing between two attempts does not reset the counter
+  // and let a rejected batch retry forever.
+  const key = files[0];
+  const failures = { ...(state.failures && typeof state.failures === "object" ? state.failures : {}) };
+  const count = (Number.isSafeInteger(failures[key]) ? failures[key] : 0) + 1;
+  if (count >= MAX_BATCH_FAILURES) {
+    quarantineBatch(files, now);
+    delete failures[key];
+    writeState({ failures });
+    return { status: "quarantined", sent: 0, httpStatus: response.status };
+  }
+  failures[key] = count;
+  writeState({ failures, retryAfter: now + TRANSIENT_BACKOFF_MS });
+  return { status: "permanent", sent: 0, httpStatus: response.status };
+}
+
+/* -------------------------------------------------------------------------- */
+/* Detached sender                                                            */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Decide whether the exiting command should spawn a sender, and do it.
+ *
+ * Called from `main()`'s `finally`, which runs in the sender too — so the
+ * sender must be excluded by name. `telemetryFlushAllowed` deliberately admits
+ * `_telemetry`, and without this guard a transient failure (which leaves the
+ * spool intact on purpose) would have the child spawn another child on the way
+ * out, with nothing between that and unbounded fan-out but a lock the exiting
+ * parent is in the middle of releasing.
+ */
+export function maybeSpawnTelemetryFlush(command, options = {}) {
+  const {
+    now = Date.now(),
+    environment = process.env,
+    homeDir = os.homedir(),
+    spawn = spawnDetachedTelemetryFlush,
+  } = options;
+  try {
+    if (command === TELEMETRY_FLUSH_COMMAND) return false;
+    if (!telemetryFlushAllowed(environment, [command], homeDir)) return false;
+
+    const state = readState();
+    if (telemetryDisabled(state, now) || flushBackedOff(state, now)) return false;
+    if (spooledFiles().length === 0) return false;
+
+    const release = acquireFlushLock({ now });
+    if (!release) return false;
+    try {
+      spawn();
+    } catch {
+      // The lock would otherwise pin the spool shut until it went stale.
+      release();
+      return false;
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * `impel _telemetry flush` — the hidden, detached sender.
+ *
+ * Hidden means hidden: it is absent from `HELP` and from
+ * `RUNTIME_BRAND.capabilities.commands`, exactly like `_converge` and
+ * `_app-launch`, and `test/cli-surface.test.js` asserts it stays that way.
+ */
+export async function cmdTelemetry(argv = [], options = {}) {
+  const {
+    environment = process.env,
+    homeDir = os.homedir(),
+    now = Date.now(),
+    ...rest
+  } = options;
+  if (argv[0] !== "flush") {
+    // Not user-facing surface area; a wrong invocation is a bug in our own
+    // spawn call, and exiting quietly keeps it out of a user's terminal.
+    return { status: "unknown-subcommand" };
+  }
+  if (!telemetryFlushAllowed(environment, [TELEMETRY_FLUSH_COMMAND], homeDir)) {
+    return { status: "not-allowed" };
+  }
+
+  const adopt = environment[TELEMETRY_FLUSH_CHILD_ENV] === "1";
+  const release = acquireFlushLock({ now, adopt });
+  if (!release) return { status: "locked" };
+  try {
+    const result = await flushOutbox({ now, ...rest });
+    if (result.status === "transient") process.exitCode = TELEMETRY_FLUSH_FAILED_EXIT_CODE;
+    return result;
+  } finally {
+    release();
+  }
+}