@indigoai-us/hq-cloud 6.15.0 → 6.15.2

package/src/telemetry.ts

@@ -1,1109 +0,0 @@
-/**
- * Usage telemetry collector — TypeScript port of the Tauri Rust collector that
- * used to live at `hq-workspace/apps/hq-sync/src-tauri/src/commands/telemetry.rs`.
- *
- * Why it moved: the Rust copy only ran inside the macOS menubar app. By moving
- * the logic into `@indigoai-us/hq-cloud`, every consumer of the package
- * (`hq-sync-runner`, `hq-cli`, mobile wrappers) emits telemetry uniformly.
- *
- * What it does: after each successful sync (`all-complete` arm of
- * `bin/sync-runner.ts`), walks Claude session logs plus live and archived Codex
- * rollouts, then diffs each file against the persisted byte-offset cursor at `~/.hq/telemetry-cursor.json`, sanitizes new rows through a tight allowlist that matches the server's
- * KEEP_FIELDS set in `apps/hq-pro/src/vault-service/handlers/usage.ts`,
- * batches into server-sized POST bodies, and ships them to `/v1/usage`.
- *
- * Trust model: the caller's `personUid` is resolved on the server from the
- * Cognito JWT — never from the body. `sanitizeRow` strips prompt bodies,
- * thinking content, tool inputs/outputs, and any nested `message` object so
- * the wire payload contains only token-accounting fields.
- *
- * Errors are swallowed by design — telemetry must never abort or delay a
- * sync. The cursor is only advanced for batches the server 2xx'd, so a
- * transient outage retries automatically on the next sync.
- */
-
-import { createHash } from "node:crypto";
-import { promises as fs } from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-
-import {
-  buildRepoCompanyMap,
-  resolveCompanyForCwd,
-  type RepoCompanyMap,
-} from "./company-resolver.js";
-import type {
-  TelemetryOptInResponse,
-  UsageBatch,
-  UsageIngestResult,
-} from "./vault-client.js";
-
-// ── Public surface ────────────────────────────────────────────────────────────
-
-/**
- * Minimal subset of `VaultClient` the collector needs. Declared as an
- * interface so tests can inject a stub without spinning up a fetch mock.
- * The real `VaultClient` from `./vault-client.js` satisfies this structurally.
- */
-export interface TelemetryClientSurface {
-  getTelemetryOptIn(): Promise<TelemetryOptInResponse>;
-  postUsage(batch: UsageBatch): Promise<UsageIngestResult>;
-  /**
-   * Optional so an older client (or a narrow test stub) still satisfies the
-   * surface — when it is absent the consent self-heal is simply skipped.
-   */
-  setTelemetryOptIn?(
-    enabled: boolean,
-    opts?: { onlyIfUnset?: boolean },
-  ): Promise<{ applied: boolean } | void>;
-}
-
-export interface CollectTelemetryOptions {
-  client: TelemetryClientSurface;
-  /** Stable per-machine id. The Tauri menubar reads this from `~/.hq/menubar.json`; the runner can pass it through or generate one once and cache. */
-  machineId: string;
-  /** Version of the wrapping caller (menubar app, CLI, etc.). Reaches CloudWatch metrics as the `installerVersion` dimension. */
-  installerVersion: string;
-  /**
-   * HQ root, used to resolve each event's `cwd` → owning repo → owning company
-   * via `<hqRoot>/companies/manifest.yaml` and stamp `companyUid` on the event
-   * (surface-hq-console-telemetry US-002). The manifest is parsed ONCE per run
-   * (see `buildRepoCompanyMap`); the resulting map is reused for every event.
-   * When omitted (or when no repo matches), `companyUid` is left UNSET and the
-   * server treats the event as unattributed/personal.
-   */
-  hqRoot?: string;
-  /**
-   * Explicit single-company sync scope (`--company <slug-or-uid>`). Used only
-   * when an event cwd does not resolve through the manifest. This is intentionally
-   * absent for multi-company and personal runs to prevent cross-tenant attribution.
-   */
-  fallbackCompany?: string;
-  /** Override `~/.claude/projects` for tests. */
-  claudeProjectsRoot?: string;
-  /** Override `~/.codex` for tests. Both live and archived rollouts are scanned. */
-  codexRoot?: string;
-  /** Override the per-runtime scan budget for deterministic tests. */
-  maxScanBytesPerSource?: number;
-  /** Override the upload batch cap for deterministic tests. */
-  maxBatchesPerRun?: number;
-  /** Override `~/.hq/telemetry-cursor.json` for tests. */
-  cursorPath?: string;
-  /** Override `~/.hq/menubar.json` (the offline opt-in fallback) for tests. */
-  menubarPath?: string;
-  /** Diagnostic sink. No-op by default. */
-  log?: (msg: string) => void;
-}
-
-export interface CollectTelemetryResult {
-  /** Whether the opt-in check resolved to true (either server-side or via the menubar fallback). When false, nothing else ran. */
-  enabled: boolean;
-  /** Source for the `enabled` decision — useful for diagnosing missing-events reports. */
-  optInSource: "server" | "menubar-fallback" | "menubar-reasserted" | "skipped";
-  /** How many `.jsonl` files we considered (before the cursor diff). */
-  filesScanned: number;
-  /** Total events successfully POSTed across all batches. */
-  eventsSent: number;
-  /** Number of `POST /v1/usage` requests made. */
-  batchesSent: number;
-}
-
-// ── Cursor schema ─────────────────────────────────────────────────────────────
-
-interface CodexUsageContext {
-  session_id?: string;
-  cwd?: string;
-  git_branch?: string;
-  session_model?: string;
-  collaboration_model?: string;
-  turn_model?: string;
-  discarding_partial_line?: boolean;
-}
-
-interface CursorEntry {
-  offset: number;
-  mtime: number;
-  /** Runtime context needed to resume a Codex rollout from a byte offset. */
-  context?: CodexUsageContext;
-}
-
-interface TelemetryCursor {
-  version: string;
-  files: Record<string, CursorEntry>;
-  /** Preserved for cursor compatibility with the desktop collector. */
-  codex_next_rollout?: string;
-}
-
-function emptyCursor(): TelemetryCursor {
-  return { version: "1", files: {} };
-}
-
-async function loadCursor(cursorPath: string): Promise<TelemetryCursor> {
-  try {
-    const raw = await fs.readFile(cursorPath, "utf-8");
-    const parsed = JSON.parse(raw) as Partial<TelemetryCursor>;
-    if (parsed && typeof parsed === "object" && parsed.files && typeof parsed.files === "object") {
-      return {
-        version: parsed.version ?? "1",
-        files: parsed.files as Record<string, CursorEntry>,
-        ...(typeof parsed.codex_next_rollout === "string"
-          ? { codex_next_rollout: parsed.codex_next_rollout }
-          : {}),
-      };
-    }
-  } catch {
-    // Missing / unparseable — start fresh.
-  }
-  return emptyCursor();
-}
-
-async function saveCursor(cursorPath: string, cursor: TelemetryCursor): Promise<void> {
-  // Atomic write: tmp + rename. The Rust impl uses the same .tmp suffix; we
-  // keep it for cross-implementation grep-ability.
-  await fs.mkdir(path.dirname(cursorPath), { recursive: true });
-  const tmp = `${cursorPath}.tmp`;
-  await fs.writeFile(tmp, JSON.stringify(cursor, null, 2), "utf-8");
-  await fs.rename(tmp, cursorPath);
-}
-
-// ── Local opt-in fallback ─────────────────────────────────────────────────────
-
-async function readLocalTelemetryEnabled(menubarPath: string): Promise<boolean> {
-  return (await readLocalTelemetryPreference(menubarPath)) === true;
-}
-
-/**
- * Tri-state read of the locally-stored consent.
- *
- * `~/.hq/menubar.json` → `telemetryEnabled` is written by the installer the
- * moment the user answers the prompt, and that local write ALWAYS succeeds —
- * unlike the paired server write, which fires before the person entity exists
- * and 404s. So this file is frequently the ONLY durable record of the user's
- * actual choice.
- *
- * `undefined` means absent / unreadable / not a boolean — "we hold no answer" —
- * as distinct from `false`, which is a real opt-out. The self-heal path must
- * never conflate the two: it replays an answer, it does not invent one.
- */
-async function readLocalTelemetryPreference(
-  menubarPath: string,
-): Promise<boolean | undefined> {
-  return (await readLocalConsentRecord(menubarPath)).enabled;
-}
-
-/**
- * The locally-cached consent plus the account it belongs to.
- *
- * `telemetryOptInPersonUid` binds the answer to the `prs_*` that gave it.
- * `menubar.json` is a per-MACHINE file, so when two people sign in under the
- * same OS user it holds whoever answered LAST — replaying it unconditionally
- * would opt in an account that never consented. The binding is what makes the
- * replay safe; an unbound (legacy) record cannot be proven to belong to the
- * current caller and is therefore never replayed.
- */
-async function readLocalConsentRecord(
-  menubarPath: string,
-): Promise<{ enabled?: boolean; personUid?: string }> {
-  try {
-    const raw = await fs.readFile(menubarPath, "utf-8");
-    const parsed = JSON.parse(raw) as {
-      telemetryEnabled?: unknown;
-      telemetryOptInPersonUid?: unknown;
-    };
-    return {
-      enabled:
-        typeof parsed.telemetryEnabled === "boolean" ? parsed.telemetryEnabled : undefined,
-      personUid:
-        typeof parsed.telemetryOptInPersonUid === "string" &&
-        parsed.telemetryOptInPersonUid.length > 0
-          ? parsed.telemetryOptInPersonUid
-          : undefined,
-    };
-  } catch {
-    return {};
-  }
-}
-
-// ── Sanitizer ─────────────────────────────────────────────────────────────────
-
-/** Top-level fields the server accepts. Keep aligned with `KEEP_FIELDS` in
- *  `apps/hq-pro/src/vault-service/handlers/usage.ts` — any drift will surface
- *  as an `unexpected-event-field` rejection in `UsageIngestResult.skipped`. */
-const KEEP_TOP_LEVEL = [
-  "sessionId",
-  "timestamp",
-  "uuid",
-  "cwd",
-  "gitBranch",
-  "userType",
-] as const;
-
-/**
- * MCP tool_use blocks name their tool `mcp__<server>__<tool>` in a Claude Code
- * session row's `message.content[]`. This recovers the SERVER segment only —
- * the server/connector name (e.g. `slack`, `figma`). The tool segment and the
- * block's `input` (args/URLs/payloads) are deliberately NEVER read.
- *
- * The `__` (double underscore) is the server↔tool delimiter, so the server is
- * everything between the `mcp__` prefix and the LAST `__`. Using `lastIndexOf`
- * (rather than a first-`__` split or a single-underscore-only regex) preserves
- * legal underscores in server names — `_foo`, `foo_`, and `foo__bar` all parse
- * correctly instead of being truncated or dropped. Returns `undefined` for a
- * name that is not an `mcp__<server>__<tool>` with a non-empty server segment.
- */
-const MCP_PREFIX = "mcp__";
-function mcpServerName(toolName: string): string | undefined {
-  if (!toolName.startsWith(MCP_PREFIX)) return undefined;
-  const rest = toolName.slice(MCP_PREFIX.length);
-  const delim = rest.lastIndexOf("__");
-  if (delim <= 0) return undefined; // no tool segment, or empty server
-  return rest.slice(0, delim);
-}
-
-/**
- * SECURITY-CRITICAL (owner-telemetry-v2 US-007). Extract the MCP servers /
- * connectors / integrations a session row touched as a NAMES-AND-COUNTS-ONLY map
- * `{ <serverName>: <count> }` — e.g. `{ slack: 2, figma: 1 }`.
- *
- * This mirrors the `hasArgs` redaction precedent in skill-telemetry.ts: we look
- * ONLY at the tool-use block's `name` (to recover the server segment of
- * `mcp__<server>__<tool>`) and count occurrences. We NEVER read the block's
- * `input` (which carries the args/URLs/payloads), never emit the tool name, and
- * never emit any argument text. So no args, URLs, payloads, or secrets can reach
- * the wire — only a service name and how many times it was invoked in this row.
- *
- * Returns `undefined` when the row touched no MCP server, so the caller omits the
- * `services` field entirely (backward-compatible: old-shaped rows carry nothing
- * new, and the server treats absence as "no services").
- */
-export function extractServices(
-  message: unknown,
-): Record<string, number> | undefined {
-  if (!message || typeof message !== "object" || Array.isArray(message)) {
-    return undefined;
-  }
-  const content = (message as Record<string, unknown>).content;
-  if (!Array.isArray(content)) return undefined;
-
-  // Null-prototype map: server names come from untrusted session content and can
-  // legally be `constructor`, `toString`, etc. A plain `{}` would read those off
-  // Object.prototype, so `counts[server] ?? 0` would yield a function and the
-  // increment would produce a non-numeric count — poisoning the whole row (the
-  // backend then drops it as `invalid-services`, losing its token/session data).
-  const counts: Record<string, number> = Object.create(null);
-  for (const blk of content as unknown[]) {
-    if (!blk || typeof blk !== "object" || Array.isArray(blk)) continue;
-    const b = blk as Record<string, unknown>;
-    // Only tool_use blocks name an MCP tool. We read `name` and NOTHING ELSE —
-    // the block's `input` (args/URLs/payloads) is never touched.
-    if (b.type !== "tool_use" || typeof b.name !== "string") continue;
-    const server = mcpServerName(b.name);
-    if (!server) continue;
-    counts[server] = (counts[server] ?? 0) + 1;
-  }
-
-  return Object.keys(counts).length > 0 ? counts : undefined;
-}
-
-/**
- * Build an outgoing event row matching the server's KEEP allowlist.
- *
- * Two transforms:
- *   1. Top-level fields are copied straight through (string identity).
- *   2. `message.model` and `message.usage.{input_tokens, output_tokens,
- *      cache_creation_input_tokens, cache_read_input_tokens}` are promoted to
- *      camelCase top-level fields. The original `message` object — which
- *      carries prompt/response text, thinking, and tool data — is dropped.
- *
- * `services` (US-007): the MCP servers / connectors / integrations this row
- * touched, as a names-and-counts-only map (see `extractServices`). NAMES + COUNTS
- * ONLY — never args/URLs/payloads/secrets, matching the `hasArgs` precedent.
- * Omitted when the row touched no MCP server (the server treats absence as none).
- *
- * `companyUid` (US-002): when the caller has resolved the row's `cwd` to an
- * owning company (`resolveCompanyForCwd`), it passes that `cmp_*` uid here and
- * it is stamped on the wire row. It is on the server's KEEP allowlist
- * (`apps/hq-pro/src/vault-service/handlers/usage.ts`). When `companyUid` is
- * undefined (cwd maps to no company repo) the field is OMITTED — the server
- * treats absence as unattributed/personal. The reserved value `unattributed`
- * is never produced (it can only come from a resolved manifest `cmp_*` uid).
- *
- * Returns `null` when the input isn't an object. Empty results (e.g. a row
- * with no recognised fields) are still returned as `{}` and emitted; the
- * server accepts empty rows and they're useful as a "Claude Code was run at
- * this time" heartbeat.
- */
-export function sanitizeRow(
-  row: unknown,
-  companyUid?: string,
-): Record<string, unknown> | null {
-  if (!row || typeof row !== "object" || Array.isArray(row)) return null;
-  const obj = row as Record<string, unknown>;
-  const out: Record<string, unknown> = {};
-
-  for (const key of KEEP_TOP_LEVEL) {
-    if (key in obj) {
-      out[key] = obj[key];
-    }
-  }
-
-  // Stamp the resolved company attribution. Omit when unresolved so the server
-  // reads it as unattributed/personal. Never the reserved `unattributed`.
-  if (companyUid !== undefined) {
-    out.companyUid = companyUid;
-  }
-
-  const message = obj.message;
-  if (message && typeof message === "object" && !Array.isArray(message)) {
-    const m = message as Record<string, unknown>;
-    if ("model" in m) out.model = m.model;
-    const usage = m.usage;
-    if (usage && typeof usage === "object" && !Array.isArray(usage)) {
-      const u = usage as Record<string, unknown>;
-      if ("input_tokens" in u) out.inputTokens = u.input_tokens;
-      if ("output_tokens" in u) out.outputTokens = u.output_tokens;
-      if ("cache_creation_input_tokens" in u) {
-        out.cacheCreationInputTokens = u.cache_creation_input_tokens;
-      }
-      if ("cache_read_input_tokens" in u) {
-        out.cacheReadInputTokens = u.cache_read_input_tokens;
-      }
-    }
-  }
-
-  // services/integrations touched (US-007). Names + counts only — extracted from
-  // the message's tool_use block NAMES, never their inputs. Omitted when none, so
-  // the wire row is unchanged for rows that touched no MCP server.
-  const services = extractServices(message);
-  if (services !== undefined) {
-    out.services = services;
-  }
-
-  return out;
-}
-
-// ── File walker ───────────────────────────────────────────────────────────────
-
-/** Recursively collect every `.jsonl` file under `root`. Skips errors silently
- *  (missing dir, EACCES on a stray subdir) — anything we can't enter is
- *  treated as absent rather than fatal, matching the Rust glob behavior. */
-async function listJsonlFiles(root: string): Promise<string[]> {
-  const out: string[] = [];
-  async function walk(dir: string): Promise<void> {
-    let entries;
-    try {
-      entries = await fs.readdir(dir, { withFileTypes: true });
-    } catch {
-      return;
-    }
-    for (const ent of entries) {
-      const full = path.join(dir, ent.name);
-      if (ent.isDirectory()) {
-        await walk(full);
-      } else if (ent.isFile() && ent.name.endsWith(".jsonl")) {
-        out.push(full);
-      }
-    }
-  }
-  await walk(root);
-  return out;
-}
-
-// ── Codex rollout adapter ────────────────────────────────────────────────────
-
-const MAX_ID_BYTES = 256;
-const MAX_TIMESTAMP_BYTES = 128;
-const MAX_PATH_BYTES = 4 * 1024;
-const MAX_MODEL_BYTES = 256;
-
-function boundedString(value: unknown, maxBytes: number): string | undefined {
-  return typeof value === "string" &&
-    value.length > 0 &&
-    Buffer.byteLength(value, "utf-8") <= maxBytes
-    ? value
-    : undefined;
-}
-
-function tokenCount(value: unknown): number {
-  return typeof value === "number" &&
-    Number.isSafeInteger(value) &&
-    value >= 0
-    ? value
-    : 0;
-}
-
-function cloneCodexContext(context: CodexUsageContext): CodexUsageContext {
-  return { ...context };
-}
-
-function codexModel(context: CodexUsageContext): string | undefined {
-  return context.turn_model ?? context.collaboration_model ?? context.session_model;
-}
-
-function codexGitBranch(payload: Record<string, unknown>): string | undefined {
-  const direct =
-    boundedString(payload.gitBranch, MAX_PATH_BYTES) ??
-    boundedString(payload.git_branch, MAX_PATH_BYTES);
-  if (direct) return direct;
-  const git = payload.git;
-  return git && typeof git === "object" && !Array.isArray(git)
-    ? boundedString((git as Record<string, unknown>).branch, MAX_PATH_BYTES)
-    : undefined;
-}
-
-function collaborationModel(
-  payload: Record<string, unknown>,
-): string | undefined {
-  const settings = payload.settings;
-  if (!settings || typeof settings !== "object" || Array.isArray(settings)) {
-    return undefined;
-  }
-  return boundedString((settings as Record<string, unknown>).model, MAX_MODEL_BYTES);
-}
-
-function stableCodexEventId(
-  rolloutIdentity: string,
-  startOffset: number,
-  endOffset: number,
-): string {
-  const offsets = Buffer.alloc(16);
-  offsets.writeBigUInt64BE(BigInt(startOffset), 0);
-  offsets.writeBigUInt64BE(BigInt(endOffset), 8);
-  return "codex-" + createHash("sha256")
-    .update(rolloutIdentity)
-    .update(Buffer.from([0]))
-    .update(offsets)
-    .digest("hex");
-}
-
-/** Adapt a Codex rollout record to the Claude-shaped sanitizer input. */
-function codexUsageRow(
-  row: unknown,
-  context: CodexUsageContext,
-  rolloutIdentity: string,
-  startOffset: number,
-  endOffset: number,
-): Record<string, unknown> | null {
-  if (!row || typeof row !== "object" || Array.isArray(row)) return null;
-  const obj = row as Record<string, unknown>;
-  const kind = obj.type;
-  const rawPayload = obj.payload;
-  const payload =
-    rawPayload && typeof rawPayload === "object" && !Array.isArray(rawPayload)
-      ? (rawPayload as Record<string, unknown>)
-      : undefined;
-
-  if (kind === "session_meta") {
-    if (!payload) return null;
-    context.session_id = boundedString(payload.id, MAX_ID_BYTES) ?? context.session_id;
-    context.cwd = boundedString(payload.cwd, MAX_PATH_BYTES);
-    context.git_branch = codexGitBranch(payload);
-    context.session_model = boundedString(payload.model, MAX_MODEL_BYTES);
-    return null;
-  }
-  if (kind === "turn_context") {
-    context.turn_model = payload
-      ? boundedString(payload.model, MAX_MODEL_BYTES)
-      : undefined;
-    const mode = payload?.collaboration_mode;
-    if (mode && typeof mode === "object" && !Array.isArray(mode)) {
-      const model = collaborationModel(mode as Record<string, unknown>);
-      if (model) context.collaboration_model = model;
-    }
-    return null;
-  }
-  if (kind === "collaboration_mode") {
-    context.collaboration_model = payload
-      ? collaborationModel(payload)
-      : undefined;
-    return null;
-  }
-  if (kind !== "event_msg" || !payload) return null;
-  if (payload.type === "collaboration_mode") {
-    context.collaboration_model = collaborationModel(payload);
-    return null;
-  }
-  if (payload.type !== "token_count") return null;
-
-  const info = payload.info;
-  if (!info || typeof info !== "object" || Array.isArray(info)) return null;
-  const last = (info as Record<string, unknown>).last_token_usage;
-  if (!last || typeof last !== "object" || Array.isArray(last)) return null;
-  const usage = last as Record<string, unknown>;
-  const outputTokens =
-    tokenCount(usage.output_tokens) + tokenCount(usage.reasoning_output_tokens);
-  const model = codexModel(context);
-  const normalized: Record<string, unknown> = {
-    uuid:
-      boundedString(obj.uuid, MAX_ID_BYTES) ??
-      stableCodexEventId(rolloutIdentity, startOffset, endOffset),
-    message: {
-      usage: {
-        input_tokens: tokenCount(usage.input_tokens),
-        output_tokens: outputTokens,
-        ...(typeof usage.cached_input_tokens === "number"
-          ? { cache_read_input_tokens: tokenCount(usage.cached_input_tokens) }
-          : {}),
-      },
-      ...(model ? { model } : {}),
-    },
-  };
-  if (context.session_id) normalized.sessionId = context.session_id;
-  const timestamp = boundedString(obj.timestamp, MAX_TIMESTAMP_BYTES);
-  if (timestamp) normalized.timestamp = timestamp;
-  if (context.cwd) normalized.cwd = context.cwd;
-  if (context.git_branch) normalized.gitBranch = context.git_branch;
-  return normalized;
-}
-
-async function sortFilesFreshestFirst(files: string[]): Promise<string[]> {
-  const ranked = await Promise.all(
-    files.map(async (filePath) => {
-      try {
-        return { filePath, mtime: (await fs.stat(filePath)).mtimeMs };
-      } catch {
-        return { filePath, mtime: 0 };
-      }
-    }),
-  );
-  ranked.sort(
-    (left, right) =>
-      right.mtime - left.mtime || left.filePath.localeCompare(right.filePath),
-  );
-  return ranked.map(({ filePath }) => filePath);
-}
-
-async function listCodexRolloutFiles(codexRoot: string): Promise<string[]> {
-  const [live, archived] = await Promise.all([
-    listJsonlFiles(path.join(codexRoot, "sessions")),
-    listJsonlFiles(path.join(codexRoot, "archived_sessions")),
-  ]);
-  return sortFilesFreshestFirst(
-    [...live, ...archived].filter((file) =>
-      path.basename(file).startsWith("rollout-"),
-    ),
-  );
-}
-
-// ── Batching primitives ───────────────────────────────────────────────────────
-
-const MAX_BATCH_EVENTS = 100;
-const MAX_BATCH_BYTES = 240 * 1024;
-const MAX_SCAN_BYTES_PER_SOURCE = 4 * 1024 * 1024;
-const MAX_BATCHES_PER_RUN = 4;
-const MAX_PARTIAL_LINE_BYTES = 64 * 1024;
-const ROW_TRUNCATION_SUFFIX = "...[truncated]";
-
-interface RowSource {
-  filePath: string;
-  endOffset: number;
-  mtime: number;
-  context?: CodexUsageContext;
-}
-
-/**
- * Byte cost of the fixed wire-payload skeleton:
- *   {"machineId":"…","installerVersion":"…","events":[]}
- *
- * The Rust implementation re-serializes the entire growing batch on every
- * row to check size — O(n²) bytes of JSON.stringify work per batch, which
- * for 60K events takes ~4 minutes wall-clock in V8. This computes the same
- * payload size incrementally instead: skeleton + Σ(per-row JSON length) +
- * commas between rows. Same threshold semantics, O(n) total cost.
- */
-function envelopeBytes(machineId: string, installerVersion: string): number {
-  // Serialize the empty-events envelope once and measure it. Captures the
-  // exact JSON whitespace / escaping V8 produces so we match what would
-  // actually go over the wire.
-  return Buffer.byteLength(
-    JSON.stringify({ machineId, installerVersion, events: [] }),
-    "utf-8",
-  );
-}
-
-function jsonBytes(value: unknown): number {
-  return Buffer.byteLength(JSON.stringify(value), "utf-8");
-}
-
-function truncateLongestStringField(row: Record<string, unknown>): boolean {
-  let longestKey: string | undefined;
-  let longestBytes = 0;
-  for (const [key, value] of Object.entries(row)) {
-    if (typeof value !== "string" || value.length === 0) continue;
-    const bytes = Buffer.byteLength(value, "utf-8");
-    if (bytes > longestBytes) {
-      longestBytes = bytes;
-      longestKey = key;
-    }
-  }
-  if (longestKey === undefined) return false;
-
-  const value = row[longestKey] as string;
-  const keepChars =
-    value.length > ROW_TRUNCATION_SUFFIX.length
-      ? Math.floor((value.length - ROW_TRUNCATION_SUFFIX.length) / 2)
-      : 0;
-  const next =
-    keepChars > 0
-      ? `${value.slice(0, keepChars)}${ROW_TRUNCATION_SUFFIX}`
-      : "";
-  if (next === value) return false;
-  row[longestKey] = next;
-  return true;
-}
-
-function boundRowForPost(
-  row: Record<string, unknown>,
-  maxRowBytes: number,
-): Record<string, unknown> | null {
-  if (maxRowBytes < 0) return null;
-  const bounded = { ...row };
-  while (jsonBytes(bounded) > maxRowBytes) {
-    if (!truncateLongestStringField(bounded)) return null;
-  }
-  return bounded;
-}
-
-// ── Main entry point ──────────────────────────────────────────────────────────
-
-/**
- * Scan, sanitize, and POST new Claude Code and Codex usage rows.
- *
- * Fire-and-forget from the caller's perspective: errors are caught internally
- * and surfaced only via `log`. The returned summary lets observers (e.g.
- * sync-runner) decide whether to record a "telemetry attempted" breadcrumb,
- * but no consumer is expected to react to it.
- */
-export async function collectAndSendTelemetry(
-  opts: CollectTelemetryOptions,
-): Promise<CollectTelemetryResult> {
-  const home = os.homedir();
-  const claudeProjectsRoot = opts.claudeProjectsRoot ?? path.join(home, ".claude", "projects");
-  const codexRoot = opts.codexRoot ?? path.join(home, ".codex");
-  const cursorPath = opts.cursorPath ?? path.join(home, ".hq", "telemetry-cursor.json");
-  const menubarPath = opts.menubarPath ?? path.join(home, ".hq", "menubar.json");
-  const log = opts.log ?? (() => {});
-  const maxScanBytesPerSource =
-    opts.maxScanBytesPerSource ?? MAX_SCAN_BYTES_PER_SOURCE;
-  const maxBatchesPerRun = opts.maxBatchesPerRun ?? MAX_BATCHES_PER_RUN;
-
-  // Company attribution (US-002): parse the manifest ONCE per run and reuse the
-  // repo-path→companyUid map for every event below. No per-event manifest read.
-  // When `hqRoot` is omitted the map is empty → every event stays unattributed.
-  const repoCompanyMap: RepoCompanyMap = opts.hqRoot
-    ? await buildRepoCompanyMap(opts.hqRoot)
-    : { entries: [], bySlug: new Map(), foldsCase: false, ambiguous: new Set<string>() };
-  const fallbackCompanyUid = opts.fallbackCompany?.startsWith("cmp_")
-    ? opts.fallbackCompany
-    : opts.fallbackCompany
-      ? repoCompanyMap.bySlug.get(opts.fallbackCompany)
-      : undefined;
-
-  // 1. Opt-in check (server-authoritative, with local fallback + self-heal).
-  let enabled: boolean;
-  let optInSource: CollectTelemetryResult["optInSource"];
-  try {
-    const resp = await opts.client.getTelemetryOptIn();
-    enabled = resp.enabled === true;
-    optInSource = "server";
-
-    // Self-heal a consent the user gave but that never reached the server.
-    //
-    // The installer writes the answer to `~/.hq/menubar.json` (always succeeds)
-    // AND posts it to `/v1/usage/opt-in` — but that post fires before the
-    // person entity exists, so it 404s and the attribute is never written.
-    // Absence then reads as `false`, the emitter goes silent, and the person
-    // shows as "not opted in" forever. Measured: 22 of 33 active Indigo members
-    // had no attribute at all, against only 2 genuine opt-outs.
-    //
-    // `unset` (never answered) is the ONLY state we heal. An explicit server
-    // `false` is a real opt-out and is left strictly alone. We also require a
-    // local answer to actually exist — we never invent consent, we only replay
-    // the answer the user already gave.
-    //
-    // And it must be THIS account's answer. `menubar.json` is per-MACHINE, so
-    // when two people sign in under the same OS user it holds whoever answered
-    // last; replaying that for the second account would opt in someone who
-    // never consented. The replay therefore requires the cached record to name
-    // the same `prs_*` the server says we are. A legacy record with no binding
-    // cannot be proven to belong to this caller and is skipped — for those
-    // machines the installer's own post-sign-in upload is the recovery path,
-    // and it is correctly account-scoped because it runs right after that
-    // person authenticates.
-    if (resp.unset === true && opts.client.setTelemetryOptIn) {
-      const record = await readLocalConsentRecord(menubarPath);
-      const local = record.enabled;
-      const boundToCaller =
-        record.personUid !== undefined &&
-        resp.personUid !== undefined &&
-        record.personUid === resp.personUid;
-      if (local !== undefined && !boundToCaller) {
-        log(
-          "[telemetry] skipping consent re-assert: the locally cached answer is not bound to the signed-in account",
-        );
-      }
-      if (local !== undefined && boundToCaller) {
-        try {
-          // `onlyIfUnset` keeps the replay atomic. Reading `unset` and writing
-          // are two requests, so without it another device could record a real
-          // opt-out in between and this stale local answer would overwrite it.
-          // The server tests "still unset?" as part of the write instead.
-          const ack = await opts.client.setTelemetryOptIn(local, { onlyIfUnset: true });
-          if (ack && ack.applied === false) {
-            // Lost the race — a real answer was recorded first and it stands.
-            // Keep the server's answer for this run rather than the local one.
-            log(
-              "[telemetry] consent was recorded elsewhere before the re-assert landed; deferring to the server",
-            );
-          } else {
-            enabled = local;
-            optInSource = "menubar-reasserted";
-            log(
-              `[telemetry] server had no recorded consent; re-asserted the local install-time answer (enabled=${local})`,
-            );
-          }
-        } catch (err) {
-          // Non-fatal: fall through on the server's answer. Next run retries.
-          log(
-            `[telemetry] failed to re-assert local opt-in (${(err as Error).message ?? err})`,
-          );
-        }
-      }
-    }
-  } catch (err) {
-    log(`[telemetry] opt-in check failed (${(err as Error).message ?? err}) — falling back to local menubar.json`);
-    enabled = await readLocalTelemetryEnabled(menubarPath);
-    optInSource = "menubar-fallback";
-  }
-
-  if (!enabled) {
-    return { enabled: false, optInSource, filesScanned: 0, eventsSent: 0, batchesSent: 0 };
-  }
-
-  // 2. Cursor + file enumeration.
-  const cursor = await loadCursor(cursorPath);
-  const loadedFiles = { ...cursor.files };
-  const rotationResets: Record<string, CursorEntry> = {};
-  const newlyCommitted: Record<string, CursorEntry> = {};
-
-  const [claudeFilesUnsorted, codexFiles] = await Promise.all([
-    listJsonlFiles(claudeProjectsRoot),
-    listCodexRolloutFiles(codexRoot),
-  ]);
-  const claudeFiles = await sortFilesFreshestFirst(claudeFilesUnsorted);
-  // Codex goes first so a fresh Linux install cannot spend its entire bounded
-  // pass replaying an older Claude backlog before reporting current Codex use.
-  const files: Array<{ filePath: string; kind: "claude" | "codex" }> = [
-    ...codexFiles.map((filePath) => ({ filePath, kind: "codex" as const })),
-    ...claudeFiles.map((filePath) => ({ filePath, kind: "claude" as const })),
-  ];
-
-  // 3. Walk each file, sanitize new rows, batch, flush at the server contract.
-  //
-  // Byte accounting is incremental: we track `batchBytes` as the projected
-  // serialized size of the current batch (envelope + per-row JSON + commas).
-  // Each row contributes its own JSON.stringify length once; we never
-  // re-serialize the growing batch. This is the O(n) replacement for the
-  // O(n²) projected-payload check the Rust impl uses (which spent ~4 min
-  // on a 60K-event first-run in the E2E smoke against hq-prod).
-  const ENVELOPE_BYTES = envelopeBytes(opts.machineId, opts.installerVersion);
-  let batchEvents: Array<Record<string, unknown>> = [];
-  let batchSources: RowSource[] = [];
-  let batchBytes = ENVELOPE_BYTES;
-  let eventsSent = 0;
-  let batchesSent = 0;
-  let uploadFailed = false;
-  let batchLimitReached = false;
-  const scannedBytes = { claude: 0, codex: 0 };
-
-  const commitSources = (sources: RowSource[]): void => {
-    const maxPerFile = new Map<
-      string,
-      { mtime: number; offset: number; context?: CodexUsageContext }
-    >();
-    for (const source of sources) {
-      const current = maxPerFile.get(source.filePath);
-      if (!current || source.endOffset > current.offset) {
-        maxPerFile.set(source.filePath, {
-          mtime: source.mtime,
-          offset: source.endOffset,
-          ...(source.context
-            ? { context: cloneCodexContext(source.context) }
-            : {}),
-        });
-      }
-    }
-    for (const [filePath, entry] of maxPerFile) {
-      const current = newlyCommitted[filePath];
-      if (!current || entry.offset > current.offset) {
-        newlyCommitted[filePath] = entry;
-      }
-    }
-  };
-
-  const flush = async (): Promise<boolean> => {
-    const events = batchEvents;
-    const sources = batchSources;
-    batchEvents = [];
-    batchSources = [];
-    batchBytes = ENVELOPE_BYTES;
-    if (events.length === 0) {
-      commitSources(sources);
-      return true;
-    }
-    try {
-      await opts.client.postUsage({
-        machineId: opts.machineId,
-        installerVersion: opts.installerVersion,
-        events,
-      });
-      batchesSent++;
-      eventsSent += events.length;
-      commitSources(sources);
-      return true;
-    } catch (err) {
-      log(
-        "[telemetry] postUsage failed (" +
-          ((err as Error).message ?? err) +
-          ") — cursor not advanced for " +
-          sources.length +
-          " rows",
-      );
-      return false;
-    }
-  };
-
-  filesLoop: for (const { filePath, kind } of files) {
-    if (uploadFailed || batchLimitReached) break;
-    const sourceBudgetRemaining =
-      maxScanBytesPerSource - scannedBytes[kind];
-    if (sourceBudgetRemaining <= 0) continue;
-
-    let stat;
-    try {
-      stat = await fs.stat(filePath);
-    } catch {
-      continue;
-    }
-    const currentSize = stat.size;
-    const currentMtime = Math.floor(stat.mtimeMs / 1000);
-    const stored = cursor.files[filePath] ?? { offset: 0, mtime: 0 };
-    let offset = stored.offset;
-    let codexContext: CodexUsageContext | undefined =
-      kind === "codex" ? cloneCodexContext(stored.context ?? {}) : undefined;
-    const rotated =
-      currentSize < offset || (stored.mtime > 0 && currentMtime < stored.mtime);
-    if (rotated) {
-      offset = 0;
-      if (kind === "codex") codexContext = {};
-      rotationResets[filePath] = { offset: 0, mtime: currentMtime };
-    }
-    if (offset >= currentSize && !rotated) continue;
-
-    let content: string;
-    let bytesRead = 0;
-    let readBuffer = Buffer.alloc(0);
-    try {
-      const fileHandle = await fs.open(filePath, "r");
-      try {
-        const length = Math.max(
-          0,
-          Math.min(currentSize - offset, sourceBudgetRemaining),
-        );
-        readBuffer = Buffer.alloc(length);
-        ({ bytesRead } = await fileHandle.read(
-          readBuffer,
-          0,
-          length,
-          offset,
-        ));
-        content = readBuffer.toString("utf-8", 0, bytesRead);
-      } finally {
-        await fileHandle.close();
-      }
-    } catch {
-      continue;
-    }
-    if (bytesRead === 0) continue;
-
-    // Resume a previously discarded oversized Codex row using raw byte
-    // positions. Decoding from the middle of a multibyte UTF-8 codepoint would
-    // otherwise skew byte offsets and could skip or replay later rows.
-    if (codexContext?.discarding_partial_line) {
-      const newlineIndex = readBuffer.subarray(0, bytesRead).indexOf(0x0a);
-      const discardedBytes = newlineIndex >= 0 ? newlineIndex + 1 : bytesRead;
-      codexContext.discarding_partial_line = newlineIndex < 0;
-      scannedBytes[kind] += discardedBytes;
-      batchSources.push({
-        filePath,
-        endOffset: offset + discardedBytes,
-        mtime: currentMtime,
-        context: cloneCodexContext(codexContext),
-      });
-      if (newlineIndex < 0) continue;
-      offset += discardedBytes;
-      bytesRead -= discardedBytes;
-      readBuffer = readBuffer.subarray(discardedBytes);
-      content = readBuffer.toString("utf-8", 0, bytesRead);
-      if (bytesRead === 0) continue;
-    }
-
-    const reachedPhysicalEof = offset + bytesRead >= currentSize;
-    const segments = content.split("\n");
-    const lineEndOffsets: number[] = [];
-    let cumulative = 0;
-    for (let i = 0; i < segments.length; i++) {
-      cumulative += Buffer.byteLength(segments[i], "utf-8");
-      if (i < segments.length - 1) cumulative += 1;
-      lineEndOffsets.push(offset + cumulative);
-    }
-
-    for (let i = 0; i < segments.length; i++) {
-      const startOffset = i === 0 ? offset : lineEndOffsets[i - 1];
-      const hasNewline = i < segments.length - 1;
-      const endOffset =
-        !hasNewline && !reachedPhysicalEof
-          ? offset + bytesRead
-          : lineEndOffsets[i];
-      const lineBytes = endOffset - startOffset;
-      if (!hasNewline && !reachedPhysicalEof) {
-        const discarding = codexContext?.discarding_partial_line === true;
-        if (discarding || lineBytes >= MAX_PARTIAL_LINE_BYTES) {
-          if (codexContext) codexContext.discarding_partial_line = true;
-          scannedBytes[kind] += lineBytes;
-          batchSources.push({
-            filePath,
-            endOffset,
-            mtime: currentMtime,
-            ...(codexContext
-              ? { context: cloneCodexContext(codexContext) }
-              : {}),
-          });
-        }
-        break;
-      }
-
-      scannedBytes[kind] += lineBytes;
-      const source = (): RowSource => ({
-        filePath,
-        endOffset,
-        mtime: currentMtime,
-        ...(codexContext
-          ? { context: cloneCodexContext(codexContext) }
-          : {}),
-      });
-      if (codexContext?.discarding_partial_line) {
-        codexContext.discarding_partial_line = false;
-        batchSources.push(source());
-        continue;
-      }
-      const trimmed = segments[i].trim();
-      if (trimmed.length === 0) {
-        batchSources.push(source());
-        continue;
-      }
-      let parsed: unknown;
-      try {
-        parsed = JSON.parse(trimmed);
-      } catch {
-        batchSources.push(source());
-        continue;
-      }
-      const sourceRow =
-        kind === "codex"
-          ? codexUsageRow(
-              parsed,
-              codexContext!,
-              filePath,
-              startOffset,
-              endOffset,
-            )
-          : parsed;
-      const rowCwd =
-        sourceRow && typeof sourceRow === "object" && !Array.isArray(sourceRow)
-          ? (sourceRow as Record<string, unknown>).cwd
-          : undefined;
-      const companyUid =
-        resolveCompanyForCwd(
-          typeof rowCwd === "string" ? rowCwd : undefined,
-          repoCompanyMap,
-        ) ?? fallbackCompanyUid;
-      const sanitized = sanitizeRow(sourceRow, companyUid);
-      if (!sanitized) {
-        batchSources.push(source());
-        continue;
-      }
-
-      const maxRowBytes = MAX_BATCH_BYTES - ENVELOPE_BYTES;
-      const wasOversized = jsonBytes(sanitized) > maxRowBytes;
-      const bounded = boundRowForPost(sanitized, maxRowBytes);
-      if (!bounded) {
-        log(
-          "[telemetry] oversized row dropped before send (" +
-            filePath +
-            ":" +
-            (i + 1) +
-            ")",
-        );
-        batchSources.push(source());
-        continue;
-      }
-      if (wasOversized) {
-        log(
-          "[telemetry] oversized row truncated before send (" +
-            filePath +
-            ":" +
-            (i + 1) +
-            ")",
-        );
-      }
-
-      const rowJsonBytes = jsonBytes(bounded);
-      const addCost = rowJsonBytes + (batchEvents.length > 0 ? 1 : 0);
-      if (
-        batchEvents.length > 0 &&
-        (batchEvents.length >= MAX_BATCH_EVENTS ||
-          batchBytes + addCost > MAX_BATCH_BYTES)
-      ) {
-        if (!(await flush())) {
-          uploadFailed = true;
-          break filesLoop;
-        }
-        if (batchesSent >= maxBatchesPerRun) {
-          batchLimitReached = true;
-          break filesLoop;
-        }
-        batchBytes = ENVELOPE_BYTES + rowJsonBytes;
-      } else {
-        batchBytes += addCost;
-      }
-      batchEvents.push(bounded);
-      batchSources.push(source());
-    }
-  }
-
-  if (!uploadFailed && !batchLimitReached) {
-    uploadFailed = !(await flush());
-  }
-
-  // 4. Persist cursor: loaded < rotation_resets < newly_committed.
-  const finalFiles: Record<string, CursorEntry> = { ...loadedFiles };
-  for (const [fp, entry] of Object.entries(rotationResets)) finalFiles[fp] = entry;
-  for (const [fp, entry] of Object.entries(newlyCommitted)) finalFiles[fp] = entry;
-
-  await saveCursor(cursorPath, {
-    version: "1",
-    files: finalFiles,
-    ...(cursor.codex_next_rollout
-      ? { codex_next_rollout: cursor.codex_next_rollout }
-      : {}),
-  });
-
-  return {
-    enabled: true,
-    optInSource,
-    filesScanned: files.length,
-    eventsSent,
-    batchesSent,
-  };
-}