@indigoai-us/hq-cloud 6.15.0 → 6.15.2

package/src/skill-telemetry.ts

@@ -1,1439 +0,0 @@
-/**
- * Skill-invocation telemetry collector.
- *
- * Sibling to `./telemetry.ts` (the token-usage collector). Where that one
- * promotes token-accounting fields off each Claude Code session row, this one
- * extracts *which skill / slash-command was invoked*, reading the SAME
- * `~/.claude/projects/**\/*.jsonl` session logs but with an independent
- * byte-offset cursor at `~/.hq/skill-telemetry-cursor.json` and shipping to
- * `/v1/skill-invocations`.
- *
- * Why a separate collector rather than folding into `./telemetry.ts`: the
- * token path is proven and its per-batch cursor mechanics are load-bearing.
- * Skill events are sparse, so this collector uses a simpler all-or-nothing
- * per-run cursor commit (re-delivery is idempotent server-side via the
- * composite eventKey). Keeping it standalone means a bug here can never
- * regress token telemetry.
- *
- * Two capture paths, both recoverable from the transcript (verified against
- * real sessions):
- *   - User-typed slash command → a `user` row whose content carries
- *     `<command-name>/foo</command-name>` (+ optional `<command-args>`).
- *   - Model-invoked skill → an `assistant` row with a `tool_use` block whose
- *     `name === "Skill"` and `input.skill` names the skill.
- * The two are mutually exclusive per invocation, so there is no double-count.
- *
- * Codex CLI is captured too, from its own rollout logs at
- * `~/.codex/sessions/YYYY/MM/DD/rollout-<ISO>-<uuid>.jsonl`. Codex records cwd +
- * sessionId ONCE in a leading `session_meta` line (not on every row). Two Codex
- * paths feed the same wire shape, scope filter, batcher, and per-file cursor:
- *   - Typed (`source: "typed"`) — a slash command, including an HQ skill, e.g.
- *     `/indigo:hello-world`, is logged verbatim as a later `event_msg`
- *     `user_message` (Codex does not expand it). Parallels Claude's typed path.
- *   - Model-driven (`source: "model"`) — Codex has no discrete "Skill tool_use"
- *     event like Claude. Instead it *runs* a skill by reading its instruction
- *     file: the model issues a shell command that reads `…/skills/<name>/
- *     SKILL.md`. Codex logs that exec in one of two shapes depending on CLI
- *     version — an `event_msg` `exec_command_end` (with `turn_id`, `cwd`, and a
- *     `parsed_cmd` it tags `type: "read"`) or a `response_item` `function_call`
- *     named `exec_command` (command + `workdir` in its `arguments`). Both are
- *     handled. We treat the read as one invocation of `<name>`. A single use
- *     re-reads the file several times (line ranges, greps) and a version may log
- *     both shapes for one exec, so events are deduped per (sessionId, turn_id,
- *     skill) — at most one per Codex turn. Edits to a SKILL.md travel via
- *     `apply_patch` (authoring, not using) and never reach this path, so skill
- *     development is not miscounted as usage.
- *
- * Privacy: raw `<command-args>` / `input.args` content is NEVER sent to the
- * cloud — only a `hasArgs` boolean. This matches the message-stripping posture
- * of `./telemetry.ts::sanitizeRow`, which deliberately drops all prompt/tool
- * content client-side. Flip `INCLUDE_ARGS_PREVIEW` only with a deliberate
- * privacy review and a matching server-side allowlist change.
- *
- * Trust model + error handling are identical to `./telemetry.ts`: personUid is
- * resolved server-side from the JWT (never the body), and all errors are
- * swallowed so telemetry never aborts or delays a 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,
-  resolveCompanyForSkill,
-  type RepoCompanyMap,
-} from "./company-resolver.js";
-import {
-  canonicalVaultSegmentSpelling,
-  encodeLocalVaultSegment,
-} from "./local-path-codec.js";
-import type {
-  SkillInvocationBatch,
-  SkillInvocationIngestResult,
-  TelemetryOptInResponse,
-} from "./vault-client.js";
-
-// ── Public surface ────────────────────────────────────────────────────────────
-
-export interface SkillTelemetryClientSurface {
-  getTelemetryOptIn(): Promise<TelemetryOptInResponse>;
-  postSkillInvocations(
-    batch: SkillInvocationBatch,
-  ): Promise<SkillInvocationIngestResult>;
-}
-
-export interface CollectSkillTelemetryOptions {
-  client: SkillTelemetryClientSurface;
-  machineId: string;
-  installerVersion: string;
-  /**
-   * When set, only invocations whose recorded `cwd` equals this path are
-   * emitted — scoping capture to the HQ project and excluding skill usage in
-   * unrelated repos on the same machine. The walk still covers all of
-   * `~/.claude/projects` (so the cursor stays consistent and no session is
-   * silently missed by a project-dir-name encoding guess), but non-matching
-   * events are dropped before they are batched. Omit to capture every project.
-   */
-  hqRoot?: string;
-  /** Override `~/.claude/projects` for tests. */
-  claudeProjectsRoot?: string;
-  /** Override `~/.codex/sessions` (the Codex CLI rollout root) for tests. */
-  codexSessionsRoot?: string;
-  /** Override `~/.hq/skill-telemetry-cursor.json` for tests. */
-  cursorPath?: string;
-  /** Override `~/.hq/menubar.json` (the offline opt-in fallback) for tests. */
-  menubarPath?: string;
-  /**
-   * Maximum transcript bytes to inspect per source (Claude or Codex) in one
-   * collection pass. The next pass resumes from the last complete line.
-   * Override for deterministic bounded-scan tests.
-   */
-  maxScanBytesPerSource?: number;
-  /**
-   * Override skillVersion resolution (skills-first-class US-015). Given a skill
-   * name, return its content-hash version marker (`sha256:<hex>`) or undefined.
-   * Defaults to hashing `<hqRoot>/.claude/skills/<skill>/SKILL.md` via
-   * {@link computeSkillVersion}. Injected in tests to decouple emission from the
-   * on-disk skills tree.
-   */
-  resolveSkillVersion?: (
-    skill: string,
-  ) => Promise<string | undefined> | string | undefined;
-  /** Diagnostic sink. No-op by default. */
-  log?: (msg: string) => void;
-}
-
-export interface CollectSkillTelemetryResult {
-  enabled: boolean;
-  optInSource: "server" | "menubar-fallback" | "skipped";
-  filesScanned: number;
-  eventsSent: number;
-  batchesSent: number;
-}
-
-/** A single extracted skill-invocation event. Mirrors the server allowlist in
- *  `apps/hq-pro/src/vault-service/handlers/skill-invocations.ts` (KEEP_FIELDS).
- *  Any drift surfaces as `unexpected-event-field` in the ingest result. */
-export interface SkillEvent {
-  skill: string;
-  source: "typed" | "model";
-  sessionId?: string;
-  timestamp?: string;
-  uuid?: string;
-  cwd?: string;
-  hasArgs: boolean;
-  /**
-   * Content-version marker (skills-first-class US-015) — the sha256 of the
-   * skill's SKILL.md, `sha256:<hex>`. The version half of the analytics-v2 usage
-   * join key (`skill_uid` + `skillVersion`), so a run maps to the version that
-   * produced it. Resolved + stamped at capture (see `computeSkillVersion` +
-   * `collectAndSendSkillTelemetry`); OPTIONAL — absent when the SKILL.md can't
-   * be located, and additive on the wire (old clients/rows simply omit it).
-   */
-  skillVersion?: string;
-}
-
-// Privacy switch — keep false (see file header). When false, raw argument text
-// never leaves the machine; only the `hasArgs` boolean is emitted.
-const INCLUDE_ARGS_PREVIEW = false;
-
-// ── Cursor schema (independent from the token collector's) ──────────────────────
-
-type SkillTelemetrySource = "claude" | "codex";
-
-interface PendingLineCursor {
-  /** Offset of the unterminated JSONL record's first byte. */
-  start: number;
-  /** Furthest byte inspected for that record; no transcript bytes are stored. */
-  scannedOffset: number;
-}
-
-interface CodexCursorState {
-  /** Latest turn context, needed by function_call rows after a bounded resume. */
-  turnId?: string;
-  /** Dedupe keys from the active turn, so repeated skill reads stay collapsed. */
-  seen?: string[];
-}
-
-interface CursorEntry {
-  offset: number;
-  mtime: number;
-  pendingLine?: PendingLineCursor;
-  codex?: CodexCursorState;
-}
-
-interface SkillCursor {
-  version: string;
-  files: Record<string, CursorEntry>;
-  /** Rotate each runtime's file order so one growing backlog cannot starve peers. */
-  lastScannedBySource?: Partial<Record<SkillTelemetrySource, string>>;
-}
-
-function clonePendingLine(value: unknown): PendingLineCursor | undefined {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
-  const pending = value as Partial<PendingLineCursor>;
-  const { start, scannedOffset } = pending;
-  if (
-    typeof start !== "number" ||
-    typeof scannedOffset !== "number" ||
-    !Number.isSafeInteger(start) ||
-    !Number.isSafeInteger(scannedOffset) ||
-    start < 0 ||
-    scannedOffset < start
-  ) {
-    return undefined;
-  }
-  return { start, scannedOffset };
-}
-
-function cloneCodexCursorState(value: unknown): CodexCursorState | undefined {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
-  const state = value as Partial<CodexCursorState>;
-  const turnId = typeof state.turnId === "string" ? state.turnId : undefined;
-  const seen = Array.isArray(state.seen)
-    ? state.seen.filter((entry): entry is string => typeof entry === "string")
-    : [];
-  return turnId === undefined && seen.length === 0 ? undefined : { turnId, seen };
-}
-
-function snapshotCodexCursorState(
-  turnId: string | undefined,
-  seen: Set<string> | undefined,
-): CodexCursorState | undefined {
-  if (turnId === undefined && (seen === undefined || seen.size === 0)) return undefined;
-  return { turnId, ...(seen && seen.size > 0 ? { seen: [...seen] } : {}) };
-}
-
-function rotateFilesFromLast(
-  files: string[],
-  lastScanned: string | undefined,
-): string[] {
-  if (!lastScanned) return files;
-  const index = files.indexOf(lastScanned);
-  return index < 0 ? files : [...files.slice(index + 1), ...files.slice(0, index + 1)];
-}
-
-async function loadCursor(cursorPath: string): Promise<SkillCursor> {
-  try {
-    const raw = await fs.readFile(cursorPath, "utf-8");
-    const parsed = JSON.parse(raw) as Partial<SkillCursor>;
-    if (parsed && typeof parsed === "object" && parsed.files && typeof parsed.files === "object") {
-      return {
-        version: parsed.version ?? "1",
-        files: parsed.files as Record<string, CursorEntry>,
-        ...(parsed.lastScannedBySource && typeof parsed.lastScannedBySource === "object"
-          ? {
-              lastScannedBySource: parsed.lastScannedBySource as Partial<
-                Record<SkillTelemetrySource, string>
-              >,
-            }
-          : {}),
-      };
-    }
-  } catch {
-    // Missing / unparseable — start fresh.
-  }
-  return { version: "1", files: {} };
-}
-
-async function saveCursor(cursorPath: string, cursor: SkillCursor): Promise<void> {
-  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);
-}
-
-async function readLocalTelemetryEnabled(menubarPath: string): Promise<boolean> {
-  try {
-    const raw = await fs.readFile(menubarPath, "utf-8");
-    const parsed = JSON.parse(raw) as { telemetryEnabled?: unknown };
-    return parsed.telemetryEnabled === true;
-  } catch {
-    return false;
-  }
-}
-
-// ── Extractor ───────────────────────────────────────────────────────────────
-
-const CMD_NAME = /<command-name>\s*\/?([^<]+?)\s*<\/command-name>/;
-const CMD_ARGS = /<command-args>([\s\S]*?)<\/command-args>/;
-
-function rowText(content: unknown): string {
-  if (typeof content === "string") return content;
-  if (Array.isArray(content)) {
-    return content
-      .map((b) => (b && typeof b === "object" && typeof (b as Record<string, unknown>).text === "string"
-        ? ((b as Record<string, unknown>).text as string)
-        : ""))
-      .join(" ");
-  }
-  return "";
-}
-
-/**
- * Extract zero or more skill-invocation events from a single parsed session
- * row. A `user` row yields at most one typed command; an `assistant` row can
- * carry multiple `Skill` tool_use blocks (rare, but handled).
- */
-export function extractSkillEvents(row: unknown): SkillEvent[] {
-  if (!row || typeof row !== "object" || Array.isArray(row)) return [];
-  const obj = row as Record<string, unknown>;
-  const type = obj.type;
-  const msg =
-    obj.message && typeof obj.message === "object" && !Array.isArray(obj.message)
-      ? (obj.message as Record<string, unknown>)
-      : undefined;
-  if (!msg) return [];
-
-  const sessionId = typeof obj.sessionId === "string" ? obj.sessionId : undefined;
-  const timestamp = typeof obj.timestamp === "string" ? obj.timestamp : undefined;
-  const cwd = typeof obj.cwd === "string" ? obj.cwd : undefined;
-  const rowUuid = typeof obj.uuid === "string" ? obj.uuid : undefined;
-
-  // Path A — user-typed slash command.
-  if (type === "user") {
-    const text = rowText(msg.content);
-    const m = CMD_NAME.exec(text);
-    if (!m) return [];
-    const a = CMD_ARGS.exec(text);
-    return [
-      {
-        skill: m[1].trim(),
-        source: "typed",
-        sessionId,
-        timestamp,
-        cwd,
-        uuid: rowUuid,
-        hasArgs: Boolean(a && a[1].trim()),
-      },
-    ];
-  }
-
-  // Path B — model-invoked Skill tool_use.
-  if (type === "assistant" && Array.isArray(msg.content)) {
-    const out: SkillEvent[] = [];
-    for (const blk of msg.content as unknown[]) {
-      if (!blk || typeof blk !== "object") continue;
-      const b = blk as Record<string, unknown>;
-      if (b.type !== "tool_use" || b.name !== "Skill") continue;
-      const input =
-        b.input && typeof b.input === "object" && !Array.isArray(b.input)
-          ? (b.input as Record<string, unknown>)
-          : {};
-      const skill = typeof input.skill === "string" ? input.skill : "";
-      if (!skill) continue;
-      const args = input.args;
-      out.push({
-        skill,
-        source: "model",
-        sessionId,
-        timestamp,
-        cwd,
-        // Prefer the tool_use block id (stable, globally unique) for dedup.
-        uuid: typeof b.id === "string" ? b.id : rowUuid,
-        hasArgs: typeof args === "string" ? args.trim().length > 0 : Boolean(args),
-      });
-    }
-    return out;
-  }
-
-  return [];
-}
-
-// ── Codex rollout extractor ───────────────────────────────────────────────────
-
-/** Match a leading slash command in a Codex `user_message`: a single token
- *  (no internal "/", so file paths like "/etc/hosts" are rejected) optionally
- *  followed by whitespace + args. Group 1 = skill/command, group 2 = args. */
-const CODEX_CMD = /^\/([^/\s]+)(?:\s+([\s\S]*))?$/;
-
-/** Parse cwd + sessionId from a Codex `session_meta` rollout line. Returns null
- *  for any other line type. */
-export function parseCodexSessionMeta(
-  row: unknown,
-): { sessionId?: string; cwd?: string } | null {
-  if (!row || typeof row !== "object" || Array.isArray(row)) return null;
-  const obj = row as Record<string, unknown>;
-  if (obj.type !== "session_meta") return null;
-  const payload =
-    obj.payload && typeof obj.payload === "object" && !Array.isArray(obj.payload)
-      ? (obj.payload as Record<string, unknown>)
-      : {};
-  const sessionId = typeof payload.id === "string" ? payload.id : undefined;
-  const cwd = typeof payload.cwd === "string" ? payload.cwd : undefined;
-  return { sessionId, cwd };
-}
-
-/** The `turn_id` a Codex rollout row belongs to, when it carries one
- *  (`turn_context` and `exec_command_end` do; bare `function_call` execs do
- *  not). Used to track the running turn so the function_call exec shape can be
- *  attributed to the turn that preceded it. */
-export function codexRowTurnId(row: unknown): string | undefined {
-  if (!row || typeof row !== "object" || Array.isArray(row)) return undefined;
-  const payload = (row as Record<string, unknown>).payload;
-  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return undefined;
-  const t = (payload as Record<string, unknown>).turn_id;
-  return typeof t === "string" ? t : undefined;
-}
-
-/**
- * Extract a typed skill/slash-command invocation from a Codex `event_msg`
- * `user_message` row. Session context (cwd, sessionId) lives in the file's
- * leading `session_meta` line and is threaded in via `ctx`. Returns 0 or 1
- * event (a Codex user_message carries at most one command).
- */
-export function extractCodexSkillEvents(
-  row: unknown,
-  ctx: { sessionId?: string; cwd?: string },
-): SkillEvent[] {
-  if (!row || typeof row !== "object" || Array.isArray(row)) return [];
-  const obj = row as Record<string, unknown>;
-  if (obj.type !== "event_msg") return [];
-  const payload =
-    obj.payload && typeof obj.payload === "object" && !Array.isArray(obj.payload)
-      ? (obj.payload as Record<string, unknown>)
-      : undefined;
-  if (!payload || payload.type !== "user_message") return [];
-  const message = typeof payload.message === "string" ? payload.message : "";
-  const m = CODEX_CMD.exec(message.trim());
-  if (!m) return [];
-  const skill = m[1].trim();
-  if (!skill) return [];
-  const timestamp = typeof obj.timestamp === "string" ? obj.timestamp : undefined;
-  // Codex events carry no per-event id, so synthesize a stable, content-derived
-  // uuid (sessionId + timestamp + skill are unique per invocation) for
-  // idempotent re-delivery — the server dedups on the composite eventKey.
-  const uuid =
-    ctx.sessionId !== undefined && timestamp !== undefined
-      ? `codex:${ctx.sessionId}:${timestamp}:${skill}`
-      : undefined;
-  return [
-    {
-      skill,
-      source: "typed",
-      sessionId: ctx.sessionId,
-      timestamp,
-      cwd: ctx.cwd,
-      uuid,
-      hasArgs: Boolean(m[2] && m[2].trim()),
-    },
-  ];
-}
-
-/** Match a `…/skills/<name>/SKILL.md` path inside a shell command. `skills/`
- *  may be nested arbitrarily deep (`.agents/skills/…`, `.codex/skills/hq/…`),
- *  and `<name>` is always the directory immediately above SKILL.md — captured
- *  as the last segment so the bridge's `skills/hq/<name>/` layout resolves to
- *  `<name>`, not `hq`. The segment classes deliberately exclude `/` so segment
- *  boundaries are unambiguous and non-matching `skills/...` paths cannot
- *  catastrophically backtrack. */
-const CODEX_SKILL_FILE =
-  /(?:^|\/)skills\/(?:[^/\s'"]+\/)*?([^/\s'"]+)\/SKILL\.md\b/;
-
-/** A company skill read via its REAL path `companies/<slug>/skills/<name>/
- *  SKILL.md`. Codex loads a skill by *reading* its file, and a company skill's
- *  real file lives under `companies/<slug>/skills/` — so, unlike the namespaced
- *  `.claude/skills/<slug>:<name>/` symlink (whose captured directory already
- *  carries the `<slug>:` prefix), this path names the owning company in a
- *  SEPARATE `<slug>` segment that {@link CODEX_SKILL_FILE} discards, leaving a
- *  bare `<name>` that no prefix-based attribution can place (the company view
- *  then misses the run). Group 1 = `<slug>`, group 2 = `<name>`: we rebuild the
- *  canonical `<slug>:<name>` invocation token from them so the event flows
- *  through the SAME attribution as every other runtime — the client
- *  `resolveCompanyForSkill` and the server rollup both key off that `<slug>:`
- *  prefix — and shares one `skill_uid` with the Claude/typed forms. The slug
- *  segment excludes `:` (a real company slug has none); skill discovery is one
- *  level deep, so `<name>` is a single segment. The leading boundary admits a
- *  RELATIVE `companies/…` path too (preceded by whitespace/quote/start, not just
- *  `/`), since Codex often reads it relative to the run cwd. */
-const CODEX_COMPANY_SKILL_FILE =
-  /(?:^|[\s/'"])companies\/([^/\s'":]+)\/skills\/([^/\s'"]+)\/SKILL\.md\b/;
-
-/** Pull the shell command string out of a Codex `exec_command_end` `command`,
- *  which is `["/bin/zsh", "-lc", "<cmd>"]` (array) on the runtimes we see, but
- *  tolerate a bare string too. */
-function codexCommandString(command: unknown): string {
-  if (typeof command === "string") return command;
-  if (Array.isArray(command)) {
-    // The interpreter + flags lead; the actual command is the trailing string.
-    for (let i = command.length - 1; i >= 0; i--) {
-      if (typeof command[i] === "string") return command[i] as string;
-    }
-  }
-  return "";
-}
-
-/** Classify a Codex exec from its own `parsed_cmd`:
- *   - `"read"`    — every classified sub-command is a read; authoritative.
- *   - `"nonread"` — at least one write/apply_patch-style entry; authoritative,
- *                   the command text is NOT consulted (Codex's call wins).
- *   - `"unknown"` — no usable classification (missing/empty); the caller then
- *                   falls back to a read-verb check on the command text.
- */
-function classifyCodexExec(parsedCmd: unknown): "read" | "nonread" | "unknown" {
-  if (!Array.isArray(parsedCmd)) return "unknown";
-  let sawRead = false;
-  for (const entry of parsedCmd) {
-    if (!entry || typeof entry !== "object") continue;
-    const t = (entry as Record<string, unknown>).type;
-    if (typeof t !== "string") continue;
-    if (t !== "read") return "nonread";
-    sawRead = true;
-  }
-  return sawRead ? "read" : "unknown";
-}
-
-// A leading read verb in the command — the positive signal that an exec is
-// inspecting SKILL.md rather than rewriting it. Anchored after an optional
-// `cd …;`/env-var prefix so `sed`, `rg`, `cat`, … are recognized at the head of
-// the real command.
-const CODEX_READ_VERB =
-  /(?:^|[;&|]\s*|\bcd\s+[^\s;]+\s*;\s*)(sed|cat|head|tail|nl|rg|grep|less|bat|wc|awk|cut|fold|view|print)\b/;
-// Writing into the skill file disqualifies regardless of a read verb elsewhere.
-const CODEX_WRITE_TO_SKILL = /(?:>>?|\btee\b)[^\n]*\/SKILL\.md\b/;
-
-/** Codex tool-call names that run a shell command (the `response_item`
- *  `function_call` form). Excludes `apply_patch` — that is an edit, not a read. */
-const CODEX_EXEC_TOOLS = new Set([
-  "exec_command",
-  "shell",
-  "local_shell",
-  "local_shell_call",
-  "bash",
-  "container.exec",
-]);
-
-/**
- * Normalize a completed Codex exec from either shape the CLI emits (it varies
- * by version), returning the command string, the turn it belongs to, the run
- * `cwd`, and any `parsed_cmd` classification — or null when the row is neither.
- *   - `event_msg` / `exec_command_end`: `command` array, own `turn_id` + `cwd`,
- *     and a `parsed_cmd` Codex tags `type: "read"`.
- *   - `response_item` / `function_call` (name `exec_command`/`shell`/…): the
- *     command lives in `arguments` (a JSON string) as `cmd`/`command`, the run
- *     dir as `workdir`. No `turn_id`/`parsed_cmd` on the row, so the turn comes
- *     from the scan's running `ctx.turnId` (tracked from `turn_context`) and
- *     read-intent is decided by the command text.
- */
-function codexExecParams(
-  obj: Record<string, unknown>,
-  payload: Record<string, unknown>,
-  ctx: { cwd?: string; turnId?: string },
-): { cmd: string; turnId?: string; cwd?: string; parsedCmd: unknown } | null {
-  if (obj.type === "event_msg" && payload.type === "exec_command_end") {
-    const cmd = codexCommandString(payload.command);
-    if (!cmd) return null;
-    return {
-      cmd,
-      turnId: typeof payload.turn_id === "string" ? payload.turn_id : ctx.turnId,
-      cwd: typeof payload.cwd === "string" ? payload.cwd : ctx.cwd,
-      parsedCmd: payload.parsed_cmd,
-    };
-  }
-  if (obj.type === "response_item" && payload.type === "function_call") {
-    const name = typeof payload.name === "string" ? payload.name : "";
-    if (!CODEX_EXEC_TOOLS.has(name)) return null;
-    let args: Record<string, unknown> = {};
-    const raw = payload.arguments;
-    if (typeof raw === "string") {
-      try {
-        const parsed = JSON.parse(raw);
-        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-          args = parsed as Record<string, unknown>;
-        }
-      } catch {
-        return null;
-      }
-    } else if (raw && typeof raw === "object" && !Array.isArray(raw)) {
-      args = raw as Record<string, unknown>;
-    }
-    const cmdRaw = args.cmd ?? args.command;
-    const cmd = typeof cmdRaw === "string" ? cmdRaw : codexCommandString(cmdRaw);
-    if (!cmd) return null;
-    return {
-      cmd,
-      turnId: ctx.turnId,
-      cwd: typeof args.workdir === "string" ? args.workdir : ctx.cwd,
-      parsedCmd: undefined,
-    };
-  }
-  return null;
-}
-
-/**
- * Extract a model-driven skill invocation from a completed Codex exec — the
- * model ran a shell command that *reads* a skill's `SKILL.md`, which is how
- * Codex loads and runs a skill (it has no discrete Skill tool_use). Handles both
- * Codex exec shapes (see `codexExecParams`). Returns 0 or 1 event tagged
- * `source: "model"`.
- *
- * Dedup is per (sessionId, turn_id, skill): a single skill use re-reads the file
- * several times (line ranges, greps) and some Codex versions log both exec
- * shapes for one exec, so the caller threads a `seen` Set to collapse them to
- * one event per Codex turn. When `seen` is omitted (unit tests), no dedup is
- * applied. Session context (sessionId, cwd, and the running turnId) comes via
- * `ctx`; the row's own `cwd` is preferred when present.
- */
-export function extractCodexSkillToolEvents(
-  row: unknown,
-  ctx: { sessionId?: string; cwd?: string; turnId?: string },
-  seen?: Set<string>,
-): SkillEvent[] {
-  if (!row || typeof row !== "object" || Array.isArray(row)) return [];
-  const obj = row as Record<string, unknown>;
-  const payload =
-    obj.payload && typeof obj.payload === "object" && !Array.isArray(obj.payload)
-      ? (obj.payload as Record<string, unknown>)
-      : undefined;
-  if (!payload) return [];
-
-  const exec = codexExecParams(obj, payload, ctx);
-  if (!exec) return [];
-  const { cmd } = exec;
-  // Real exec commands are tiny; avoid running regexes over pathological rows.
-  if (cmd.length > 100_000) return [];
-  const m = CODEX_SKILL_FILE.exec(cmd);
-  if (!m) return [];
-  // Confirm the exec is a read of the skill file, not a write to it. Codex's own
-  // classification leads; only when it is absent does the command text decide.
-  if (CODEX_WRITE_TO_SKILL.test(cmd)) return [];
-  const cls = classifyCodexExec(exec.parsedCmd);
-  if (cls === "nonread") return [];
-  if (cls === "unknown" && !CODEX_READ_VERB.test(cmd)) return [];
-
-  // Prefer the canonical `<slug>:<name>` token when the read is of a company
-  // skill's real file (`companies/<slug>/skills/<name>/SKILL.md`) — the slug is
-  // in the path but dropped by CODEX_SKILL_FILE, so reconstruct it here to keep
-  // the run attributable. Otherwise keep the last-segment name (core/personal/
-  // namespaced skills already carry their prefix in the captured directory).
-  const co = CODEX_COMPANY_SKILL_FILE.exec(cmd);
-  const skill = co ? `${co[1]}:${co[2]}` : m[1].trim();
-  if (!skill) return [];
-
-  const sessionId = ctx.sessionId;
-  const turnId = exec.turnId;
-  const timestamp = typeof obj.timestamp === "string" ? obj.timestamp : undefined;
-  const cwd = exec.cwd;
-
-  // Dedup key: one invocation per (session, turn, skill). Fall back to the
-  // session when no turn_id is present (still collapses a turn's repeat reads
-  // for the common single-turn case, since they share a timestamp-free key).
-  const dedupKey = `${sessionId ?? ""}:${turnId ?? ""}:${skill}`;
-  if (seen) {
-    if (seen.has(dedupKey)) return [];
-    seen.add(dedupKey);
-  }
-
-  // Synthesize a stable uuid so re-delivery across syncs is idempotent
-  // server-side. Prefer (session, turn) — globally unique per invocation; fall
-  // back to (session, timestamp) so distinct reads aren't all collapsed when a
-  // turn_id is somehow absent.
-  const uuid =
-    sessionId !== undefined && turnId !== undefined
-      ? `codex:skill:${sessionId}:${turnId}:${skill}`
-      : sessionId !== undefined && timestamp !== undefined
-        ? `codex:skill:${sessionId}:${timestamp}:${skill}`
-        : undefined;
-
-  return [
-    {
-      skill,
-      source: "model",
-      sessionId,
-      timestamp,
-      cwd,
-      uuid,
-      hasArgs: false,
-    },
-  ];
-}
-
-/**
- * Resolve a skill's content-version marker ("skillVersion", skills-first-class
- * US-015) — the sha256 of its SKILL.md as `sha256:<hex>` (the canonical
- * content-hash shape used across hq-cloud, e.g. `watcher.ts`). This is the
- * version half of the analytics-v2 usage join key (`skill_uid` + `skillVersion`),
- * so a captured run maps to the exact version that produced it.
- *
- * Resolution is best-effort against `<hqRoot>/.claude/skills/<skill>/SKILL.md` —
- * the canonical single-source skills location, which holds an entry (a real dir
- * or a symlink) for every skill by its FULL invocation name incl. namespace
- * (`indigo:hello-world`, `personal:worktree`, `deploy`, …). A `.agents/skills/`
- * fallback covers the Codex bridge layout. `readFile` follows symlinks, so a
- * company/personal skill surfaced into `.claude/skills/` resolves transparently.
- * Returns undefined when `hqRoot` is absent or the file can't be located/read,
- * so the wire field is simply OMITTED — additive + backwards-compatible, exactly
- * like the optional `companyUid` attribution.
- *
- * "At invocation time" is approximated by the SKILL.md's content AT CAPTURE TIME:
- * the collector scans historical session logs during sync, so the file's current
- * bytes are the closest available proxy for the version that ran. A skill edited
- * between run and sync can differ — acceptable for a usage-rollup join key (the
- * overwhelming majority of runs sync before any edit to the skill).
- */
-export async function computeSkillVersion(
-  hqRoot: string | undefined,
-  skill: string,
-): Promise<string | undefined> {
-  if (!hqRoot || !skill) return undefined;
-  // A skill token maps to exactly one directory name here; reject anything that
-  // could escape the skills dir (path traversal / separators). Namespaced names
-  // use `:` (not a separator) and pass.
-  if (skill.includes("/") || skill.includes("\\") || skill.includes("..")) {
-    return undefined;
-  }
-  // Codec boundary: callers hand us EITHER the canonical invocation name
-  // (`indigo:hello-world`) or an already-encoded local dir segment captured
-  // from a win32 path (`indigo%3Ahello-world`, Codex telemetry extraction).
-  // Normalize to canonical first — encoding an already-encoded name would
-  // look under `indigo%253A...` and miss the real wrapper — then encode for
-  // THIS host. Re-run the traversal guard on the decoded form: a crafted
-  // `%2F`/`%5C` escape must not smuggle a separator past the raw check.
-  const canonicalSkill = canonicalVaultSegmentSpelling(skill);
-  if (
-    canonicalSkill.includes("/") ||
-    canonicalSkill.includes("\\") ||
-    canonicalSkill.includes("..")
-  ) {
-    return undefined;
-  }
-  const localSkillDirName = encodeLocalVaultSegment(canonicalSkill);
-  const candidates = [
-    path.join(hqRoot, ".claude", "skills", localSkillDirName, "SKILL.md"),
-    path.join(hqRoot, ".agents", "skills", localSkillDirName, "SKILL.md"),
-  ];
-  // Colon-free names do not normalize (amplifier families are namespaced),
-  // so a win32 capture of a space-named skill's dir (`foo%20bar`) would
-  // re-encode to `foo%2520bar` and miss — also try the raw segment as-is.
-  if (skill !== localSkillDirName) {
-    candidates.push(
-      path.join(hqRoot, ".claude", "skills", skill, "SKILL.md"),
-      path.join(hqRoot, ".agents", "skills", skill, "SKILL.md"),
-    );
-  }
-  for (const candidate of candidates) {
-    try {
-      const bytes = await fs.readFile(candidate);
-      return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
-    } catch {
-      // Not at this candidate — try the next.
-    }
-  }
-  return undefined;
-}
-
-/** Shape the event for the wire. Drops raw args unless explicitly enabled.
- *
- *  `companyUid` (US-002): the caller resolves the event's `cwd` → owning company
- *  (`resolveCompanyForCwd`) and passes that `cmp_*` uid here. It is on the
- *  server's KEEP allowlist (`apps/hq-pro/src/vault-service/handlers/
- *  skill-invocations.ts`). When 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.
- *
- *  `skillVersion` (US-015): the caller stamps `ev.skillVersion` from
- *  `computeSkillVersion` before shaping; a `sha256:<hex>` marker (or omitted when
- *  unresolved). Also on the server KEEP allowlist; additive + backwards-compatible. */
-function toWireRow(ev: SkillEvent, companyUid?: string): Record<string, unknown> {
-  const row: Record<string, unknown> = {
-    skill: ev.skill,
-    source: ev.source,
-    hasArgs: ev.hasArgs,
-  };
-  if (ev.sessionId !== undefined) row.sessionId = ev.sessionId;
-  if (ev.timestamp !== undefined) row.timestamp = ev.timestamp;
-  if (ev.uuid !== undefined) row.uuid = ev.uuid;
-  if (ev.cwd !== undefined) row.cwd = ev.cwd;
-  if (ev.skillVersion !== undefined) row.skillVersion = ev.skillVersion;
-  if (companyUid !== undefined) row.companyUid = companyUid;
-  // INCLUDE_ARGS_PREVIEW is intentionally a compile-time constant `false`;
-  // the guarded branch documents the (currently disabled) egress path.
-  if (INCLUDE_ARGS_PREVIEW) {
-    // Reserved: a server allowlist change must land before this is enabled.
-  }
-  return row;
-}
-
-// ── File walker ───────────────────────────────────────────────────────────────
-
-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.sort((a, b) => a.localeCompare(b));
-}
-
-// Codex's `session_meta` is always the first, small line of a rollout. Read a
-// bounded prefix from the top so a mid-file (cursor-resumed) scan still has
-// session context without slurping a multi-MiB transcript.
-const CODEX_META_PREFIX_BYTES = 64 * 1024;
-
-/**
- * Largest length passed to a single `FileHandle.read()`. Node's native fs.read
- * asserts `args[3]->IsInt32()` on the length argument, so a single read whose
- * length exceeds 2**31-1 (≈2 GiB) does NOT throw a catchable error — it aborts
- * the whole process with SIGABRT. A skill/session log whose unread tail had
- * grown past ~2 GiB crashed the entire `hq sync` runner this way
- * (Sentry HQ-SYNC-WEB-15). 256 MiB stays comfortably within Int32 while keeping
- * the read-loop iteration count small.
- */
-const MAX_FS_READ_CHUNK_BYTES = 256 * 1024 * 1024;
-
-/**
- * A sync pass must never turn an unbounded transcript tail into one V8 string.
- * Node aborts the process once Buffer#toString receives a length >= 2**31; this
- * conservative cap is also below the smaller practical string ceilings across
- * supported Node versions. Keep this assertion close to the call site so a
- * future increase cannot reintroduce the native SIGTRAP failure.
- */
-export const MAX_DECODE_BYTES = 256 * 1024 * 1024;
-if (MAX_DECODE_BYTES >= 2 ** 31) {
-  throw new Error("MAX_DECODE_BYTES must remain below the V8 string length limit");
-}
-
-/** Minimal structural view of the `FileHandle.read` we depend on. */
-type ReadableFileHandle = {
-  read(
-    buffer: Buffer,
-    offset: number,
-    length: number,
-    position: number,
-  ): Promise<{ bytesRead: number }>;
-};
-
-/**
- * Read `length` bytes from `fh` starting at byte `position` into `buf`, issuing
- * native reads no larger than `chunkBytes` so the length argument never exceeds
- * Int32 and trips the SIGABRT-on-assert path (HQ-SYNC-WEB-15). Returns the total
- * bytes actually read — which may be < `length` if the file was truncated
- * between `stat` and this read (a 0-byte read means EOF, so we stop).
- */
-export async function readFileRegion(
-  fh: ReadableFileHandle,
-  buf: Buffer,
-  position: number,
-  length: number,
-  chunkBytes: number = MAX_FS_READ_CHUNK_BYTES,
-): Promise<number> {
-  let filled = 0;
-  while (filled < length) {
-    const chunk = Math.min(chunkBytes, length - filled);
-    const { bytesRead } = await fh.read(buf, filled, chunk, position + filled);
-    if (bytesRead === 0) break; // EOF / truncated since stat — stop cleanly.
-    filled += bytesRead;
-  }
-  return filled;
-}
-
-/** Read cwd + sessionId from a Codex rollout's leading `session_meta` line.
- *  Always reads from offset 0 (independent of the byte cursor). Best-effort:
- *  any error → empty context (events then fail the hqRoot scope filter, which
- *  is the safe default). */
-async function readCodexSessionContext(
-  filePath: string,
-): Promise<{ sessionId?: string; cwd?: string }> {
-  try {
-    const fh = await fs.open(filePath, "r");
-    try {
-      const buf = Buffer.alloc(CODEX_META_PREFIX_BYTES);
-      const bytesRead = await readFileRegion(fh, buf, 0, CODEX_META_PREFIX_BYTES);
-      const firstLine = buf.toString("utf-8", 0, bytesRead).split("\n", 1)[0]?.trim();
-      if (!firstLine) return {};
-      return parseCodexSessionMeta(JSON.parse(firstLine)) ?? {};
-    } finally {
-      await fh.close();
-    }
-  } catch {
-    return {};
-  }
-}
-
-const MAX_BATCH_EVENTS = 100;
-const MAX_BATCH_BYTES = 240 * 1024;
-const MAX_SCAN_BYTES_PER_SOURCE = 4 * 1024 * 1024;
-const ROW_TRUNCATION_SUFFIX = "...[truncated]";
-
-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, extract, and POST any new skill-invocation events.
- *
- * Cursor model (per-batch commit, matching the token collector for robustness):
- * each file is scanned from its stored byte offset through a bounded region;
- * extracted events carry the byte offset of the line they came from. Events are
- * flushed in server-sized batches, and the cursor advances **per successful
- * batch** — so if one batch in a large (e.g. first-run backfill) fails, the
- * batches that already succeeded stay committed and only the rest re-send next
- * sync. A bounded region settles only at a complete-line boundary, preventing
- * a cursor from skipping an unread tail or resuming mid-line.
- *
- * Per-file commit rule:
- *   - All of a file's events sent OK (including zero-event files) → commit EOF,
- *     so quiet/non-skill tails are never re-scanned.
- *   - Some of a file's events failed → commit the max byte offset whose batch
- *     succeeded (partial progress); the remainder re-sends next sync.
- * Server-side dedup on the composite eventKey makes any re-send idempotent.
- * Rotation/truncation resets the offset to 0 (re-read from the top).
- */
-export async function collectAndSendSkillTelemetry(
-  opts: CollectSkillTelemetryOptions,
-): Promise<CollectSkillTelemetryResult> {
-  const home = os.homedir();
-  const claudeProjectsRoot =
-    opts.claudeProjectsRoot ?? path.join(home, ".claude", "projects");
-  const codexSessionsRoot =
-    opts.codexSessionsRoot ?? path.join(home, ".codex", "sessions");
-  const cursorPath =
-    opts.cursorPath ?? path.join(home, ".hq", "skill-telemetry-cursor.json");
-  const menubarPath = opts.menubarPath ?? path.join(home, ".hq", "menubar.json");
-  const log = opts.log ?? (() => {});
-  // Match the usage collector's per-runtime budget, with an independent hard
-  // decode ceiling as defence in depth for future callers/configuration.
-  const maxScanBytesPerSource = Math.min(
-    opts.maxScanBytesPerSource ?? MAX_SCAN_BYTES_PER_SOURCE,
-    MAX_DECODE_BYTES,
-  );
-
-  // Normalize the scope path once (drop a single trailing slash, keeping "/").
-  const normalizePath = (p: string): string => (p.length > 1 ? p.replace(/\/+$/, "") : p);
-  const scopeCwd = opts.hqRoot !== undefined ? normalizePath(opts.hqRoot) : undefined;
-
-  // 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>() };
-
-  // skillVersion resolution (US-015): resolve each skill's SKILL.md content hash
-  // ONCE per run (skills repeat across a session) and stamp it onto every event.
-  // Injectable for tests; defaults to hashing under hqRoot. Errors degrade to
-  // undefined so a resolver failure never blocks telemetry (additive field).
-  const resolveSkillVersion =
-    opts.resolveSkillVersion ??
-    ((skill: string) => computeSkillVersion(opts.hqRoot, skill));
-  const skillVersionCache = new Map<string, string | undefined>();
-  const skillVersionFor = async (skill: string): Promise<string | undefined> => {
-    if (skillVersionCache.has(skill)) return skillVersionCache.get(skill);
-    let version: string | undefined;
-    try {
-      version = await resolveSkillVersion(skill);
-    } catch {
-      version = undefined;
-    }
-    skillVersionCache.set(skill, version);
-    return version;
-  };
-
-  // 1. Opt-in check — reuse the same gate as token telemetry.
-  let enabled: boolean;
-  let optInSource: CollectSkillTelemetryResult["optInSource"];
-  try {
-    const resp = await opts.client.getTelemetryOptIn();
-    enabled = resp.enabled === true;
-    optInSource = "server";
-  } catch (err) {
-    log(`[skill-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. Both runtimes share one cursor (keyed by
-  //    absolute path — the roots never collide) and one batcher. Each file is
-  //    tagged with its runtime so the scan picks the right line extractor.
-  const cursor = await loadCursor(cursorPath);
-  const claudeFiles = await listJsonlFiles(claudeProjectsRoot);
-  const codexFiles = await listJsonlFiles(codexSessionsRoot);
-  const files: { filePath: string; kind: SkillTelemetrySource }[] = [
-    ...rotateFilesFromLast(
-      claudeFiles,
-      cursor.lastScannedBySource?.claude,
-    ).map((f) => ({ filePath: f, kind: "claude" as const })),
-    ...rotateFilesFromLast(
-      codexFiles,
-      cursor.lastScannedBySource?.codex,
-    ).map((f) => ({ filePath: f, kind: "codex" as const })),
-  ];
-
-  // 3. Scan every file from its stored offset, collecting events tagged with
-  //    the byte offset of the line they came from (for per-batch commit).
-  interface FileScan {
-    eof: number;
-    mtime: number;
-    eventCount: number; // events extracted from this file this run
-    pendingLine?: PendingLineCursor;
-    codex?: CodexCursorState;
-  }
-  interface Sourced {
-    row: Record<string, unknown>;
-    filePath: string;
-    endOffset: number; // absolute byte offset at the end of the source line
-    codex?: CodexCursorState;
-  }
-
-  const fileScans: Record<string, FileScan> = {};
-  const rotationResets: Record<string, CursorEntry> = {};
-  const scannedBytes: Record<SkillTelemetrySource, number> = { claude: 0, codex: 0 };
-  const lastScannedBySource: Partial<Record<SkillTelemetrySource, string>> = {
-    ...cursor.lastScannedBySource,
-  };
-  const sourced: Sourced[] = [];
-  const envelopeBytes = Buffer.byteLength(
-    JSON.stringify({ machineId: opts.machineId, installerVersion: opts.installerVersion, events: [] }),
-    "utf-8",
-  );
-  const maxRowBytes = MAX_BATCH_BYTES - envelopeBytes;
-
-  for (const { filePath, kind } of files) {
-    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 pendingLine = clonePendingLine(stored.pendingLine);
-    let codexCursor = kind === "codex" ? cloneCodexCursorState(stored.codex) : undefined;
-
-    // Rotation / truncation → re-read from the top.
-    const rotated =
-      currentSize < offset || (stored.mtime > 0 && currentMtime < stored.mtime);
-    if (rotated) {
-      offset = 0;
-      pendingLine = undefined;
-      codexCursor = undefined;
-      rotationResets[filePath] = { offset: 0, mtime: currentMtime };
-    }
-    // A malformed/stale pending continuation is never allowed to move the
-    // durable complete-line cursor. Start scanning fresh from that cursor.
-    if (
-      pendingLine &&
-      (pendingLine.start !== offset || pendingLine.scannedOffset > currentSize)
-    ) {
-      pendingLine = undefined;
-    }
-    const scanOffset = pendingLine?.scannedOffset ?? offset;
-
-    // Record the scan even when there are no new bytes — a fully-drained file
-    // (eventCount 0, offset already at EOF) should still settle at EOF below.
-    fileScans[filePath] = {
-      eof: currentSize,
-      mtime: currentMtime,
-      eventCount: 0,
-      ...(pendingLine ? { pendingLine } : {}),
-      ...(codexCursor ? { codex: codexCursor } : {}),
-    };
-
-    if (offset >= currentSize && !rotated) continue;
-
-    let content: string;
-    let bytesRead = 0;
-    let readBuffer = Buffer.alloc(0);
-    try {
-      const fh = await fs.open(filePath, "r");
-      try {
-        const length = Math.max(
-          0,
-          Math.min(currentSize - scanOffset, sourceBudgetRemaining, MAX_DECODE_BYTES),
-        );
-        readBuffer = Buffer.alloc(length);
-        // Chunked: a single fh.read() with length > Int32 aborts the process
-        // with SIGABRT (HQ-SYNC-WEB-15). `MAX_DECODE_BYTES` separately keeps
-        // the following toString below V8's fatal >= 2**31 boundary; an
-        // oversized configured budget cannot bypass this guard.
-        bytesRead = await readFileRegion(fh, readBuffer, scanOffset, length);
-        content = readBuffer.toString("utf-8", 0, Math.min(bytesRead, MAX_DECODE_BYTES));
-      } finally {
-        await fh.close();
-      }
-    } catch {
-      // Could not read — drop the scan so we don't claim progress for it.
-      delete fileScans[filePath];
-      continue;
-    }
-    scannedBytes[kind] += bytesRead;
-    if (bytesRead > 0) lastScannedBySource[kind] = filePath;
-
-    let reachedPhysicalEof = scanOffset + bytesRead >= currentSize;
-    if (!reachedPhysicalEof) {
-      log(`[skill-telemetry] scan budget reached; deferring unread transcript bytes (${filePath})`);
-    }
-
-    let completedPendingLine = false;
-    if (pendingLine) {
-      const newlineIndex = readBuffer.subarray(0, bytesRead).indexOf(0x0a);
-      if (newlineIndex < 0 && !reachedPhysicalEof) {
-        // The record itself is larger than the normal per-pass budget. Persist
-        // only byte positions and continue searching from this new suffix next
-        // pass — never the transcript's contents, and never the same prefix.
-        fileScans[filePath].eof = offset;
-        fileScans[filePath].pendingLine = {
-          start: offset,
-          scannedOffset: scanOffset + bytesRead,
-        };
-        log(`[skill-telemetry] continuing oversized JSONL record on a later pass (${filePath})`);
-        continue;
-      }
-
-      const lineEnd =
-        newlineIndex >= 0 ? scanOffset + newlineIndex + 1 : scanOffset + bytesRead;
-      const lineLength = lineEnd - offset;
-      if (lineLength > MAX_DECODE_BYTES) {
-        // This guard still makes the failure recoverable rather than allowing a
-        // native V8 abort. Keep the byte-only continuation so a later file
-        // rotation/truncation can reset it safely; diagnostics reveal the
-        // exceptional transcript without leaking its contents.
-        fileScans[filePath].eof = offset;
-        fileScans[filePath].pendingLine = { start: offset, scannedOffset: lineEnd };
-        log(`[skill-telemetry] JSONL record exceeds safe decode limit (${filePath})`);
-        continue;
-      }
-
-      try {
-        const fh = await fs.open(filePath, "r");
-        try {
-          readBuffer = Buffer.alloc(lineLength);
-          bytesRead = await readFileRegion(fh, readBuffer, offset, lineLength);
-          if (bytesRead !== lineLength) {
-            fileScans[filePath].eof = offset;
-            fileScans[filePath].pendingLine = {
-              start: offset,
-              scannedOffset: offset + bytesRead,
-            };
-            continue;
-          }
-          content = readBuffer.toString("utf-8", 0, bytesRead);
-        } finally {
-          await fh.close();
-        }
-      } catch {
-        delete fileScans[filePath];
-        continue;
-      }
-      reachedPhysicalEof = lineEnd >= currentSize;
-      completedPendingLine = true;
-      pendingLine = undefined;
-      delete fileScans[filePath].pendingLine;
-    }
-
-    // Codex events lack per-row cwd/sessionId — they live in the file's leading
-    // `session_meta` line, which we read from the top regardless of the cursor.
-    const codexCtx =
-      kind === "codex" ? await readCodexSessionContext(filePath) : undefined;
-    // Per-file dedup of model-driven Codex skill loads: a single skill use
-    // re-reads SKILL.md several times within one turn, so collapse them to one
-    // event per (session, turn, skill). Scoped per file = per Codex session.
-    const codexSeen =
-      kind === "codex" ? new Set(codexCursor?.seen ?? []) : undefined;
-    // Running turn id for Codex: the `function_call` exec shape carries no
-    // turn_id of its own, so we track the latest one seen (from `turn_context`,
-    // which precedes a turn's execs) and attribute those execs to it.
-    let codexTurnId: string | undefined = codexCursor?.turnId;
-
-    // A region capped before EOF can end part-way through a JSONL row (and even
-    // part-way through a multibyte UTF-8 character). Only process its newline-
-    // terminated segments; the next pass resumes at the last settled boundary.
-    // At physical EOF retain today's behaviour of handling a final newline-less
-    // record in the same pass.
-    const segments = content.split("\n");
-    const completeSegmentCount = reachedPhysicalEof
-      ? segments.length
-      : Math.max(0, segments.length - 1);
-    let cumulative = offset;
-    let settledOffset = offset;
-    for (let i = 0; i < completeSegmentCount; i++) {
-      cumulative += Buffer.byteLength(segments[i], "utf-8");
-      if (i < segments.length - 1) cumulative += 1; // the split newline byte
-      // For the final physical-EOF segment, use the bytes actually returned by
-      // fs rather than re-encoding it. This preserves byte-exact cursor
-      // offsets even if a writer left an invalid/incomplete UTF-8 tail.
-      const endOffset =
-        i === segments.length - 1 ? offset + bytesRead : cumulative;
-      settledOffset = endOffset;
-
-      const trimmed = segments[i].trim();
-      if (trimmed.length === 0) continue;
-      let parsed: unknown;
-      try {
-        parsed = JSON.parse(trimmed);
-      } catch {
-        continue;
-      }
-      if (kind === "codex") {
-        const t = codexRowTurnId(parsed);
-        if (t !== undefined) {
-          if (t !== codexTurnId) codexSeen?.clear();
-          codexTurnId = t;
-        }
-      }
-      const events =
-        kind === "codex"
-          ? [
-              ...extractCodexSkillEvents(parsed, codexCtx ?? {}),
-              ...extractCodexSkillToolEvents(
-                parsed,
-                { ...(codexCtx ?? {}), turnId: codexTurnId },
-                codexSeen,
-              ),
-            ]
-          : extractSkillEvents(parsed);
-      for (const ev of events) {
-        // Scope filter: only emit invocations made from the HQ project — its
-        // root or any path beneath it (worktrees, nested apps), so a session run
-        // from `<hqRoot>/.claude/worktrees/…` still counts. Sibling repos that
-        // merely share a path prefix (`<hqRoot>-other`) are excluded by the
-        // trailing-slash boundary.
-        if (scopeCwd !== undefined) {
-          const c = ev.cwd === undefined ? undefined : normalizePath(ev.cwd);
-          if (c === undefined || (c !== scopeCwd && !c.startsWith(`${scopeCwd}/`))) {
-            continue;
-          }
-        }
-        // Attribute the event to a company (cmp_* uid) from the per-run map.
-        // A company SKILL (`<slug>:<skill>`) belongs to ITS company regardless of
-        // the cwd it ran in, so skill-based resolution takes precedence; a core
-        // skill falls back to the cwd's owning company. Unresolved by both →
-        // undefined → companyUid omitted (unattributed/personal).
-        const companyUid =
-          resolveCompanyForSkill(ev.skill, repoCompanyMap) ??
-          resolveCompanyForCwd(ev.cwd, repoCompanyMap);
-        // Stamp the skill's content-version marker (US-015). Unresolved → the
-        // field is omitted from the wire row (additive).
-        ev.skillVersion = await skillVersionFor(ev.skill);
-        const wireRow = toWireRow(ev, companyUid);
-        const wasOversized = jsonBytes(wireRow) > maxRowBytes;
-        const bounded = boundRowForPost(wireRow, maxRowBytes);
-        if (!bounded) {
-          log(
-            `[skill-telemetry] oversized row dropped before send (${filePath}:${i + 1})`,
-          );
-          continue;
-        }
-        if (wasOversized) {
-          log(
-            `[skill-telemetry] oversized row truncated before send (${filePath}:${i + 1})`,
-          );
-        }
-        sourced.push({
-          row: bounded,
-          filePath,
-          endOffset,
-          ...(kind === "codex"
-            ? { codex: snapshotCodexCursorState(codexTurnId, codexSeen) }
-            : {}),
-        });
-        fileScans[filePath].eventCount++;
-      }
-    }
-    // Commit only bytes that reached a complete record boundary. In particular,
-    // never claim currentSize merely because the first budgeted region was read.
-    fileScans[filePath].eof = settledOffset;
-    if (!completedPendingLine && !reachedPhysicalEof) {
-      const lastNewline = readBuffer.subarray(0, bytesRead).lastIndexOf(0x0a);
-      const partialStart = offset + lastNewline + 1;
-      const inspectedThrough = offset + bytesRead;
-      if (partialStart < inspectedThrough) {
-        fileScans[filePath].pendingLine = {
-          start: partialStart,
-          scannedOffset: inspectedThrough,
-        };
-      }
-    }
-    if (kind === "codex") {
-      fileScans[filePath].codex = snapshotCodexCursorState(codexTurnId, codexSeen);
-    }
-  }
-
-  // 4. Flush in server-sized batches, advancing per-file progress on each 2xx.
-  let eventsSent = 0;
-  let batchesSent = 0;
-
-  // Per file: count of events successfully sent + max committed byte offset.
-  const sentCount: Record<string, number> = {};
-  const committed: Record<string, { offset: number; codex?: CodexCursorState }> = {};
-
-  let batch: Sourced[] = [];
-  let batchBytes = envelopeBytes;
-
-  const flush = async (): Promise<boolean> => {
-    if (batch.length === 0) return true;
-    const toSend = batch;
-    batch = [];
-    batchBytes = envelopeBytes;
-    try {
-      await opts.client.postSkillInvocations({
-        machineId: opts.machineId,
-        installerVersion: opts.installerVersion,
-        events: toSend.map((s) => s.row),
-      });
-      batchesSent++;
-      eventsSent += toSend.length;
-      // Advance per-file progress for the events in this (successful) batch.
-      for (const s of toSend) {
-        sentCount[s.filePath] = (sentCount[s.filePath] ?? 0) + 1;
-        const prev = committed[s.filePath];
-        if (!prev || s.endOffset > prev.offset) {
-          committed[s.filePath] = {
-            offset: s.endOffset,
-            ...(s.codex ? { codex: s.codex } : {}),
-          };
-        }
-      }
-      return true;
-    } catch (err) {
-      log(`[skill-telemetry] postSkillInvocations failed (${(err as Error).message ?? err}) — these rows re-send next sync`);
-      // Cursor not advanced for this batch; eventKey dedups the eventual re-send.
-      return false;
-    }
-  };
-
-  let stoppedAfterFailure = false;
-  for (const s of sourced) {
-    const rowBytes = Buffer.byteLength(JSON.stringify(s.row), "utf-8");
-    const addCost = rowBytes + (batch.length > 0 ? 1 : 0);
-    if (
-      batch.length > 0 &&
-      (batch.length >= MAX_BATCH_EVENTS || batchBytes + addCost > MAX_BATCH_BYTES)
-    ) {
-      if (!(await flush())) {
-        stoppedAfterFailure = true;
-        break;
-      }
-      batchBytes = envelopeBytes + rowBytes;
-    } else {
-      batchBytes += addCost;
-    }
-    batch.push(s);
-  }
-  if (!stoppedAfterFailure) await flush();
-
-  // 5. Build the new cursor: loaded < rotationResets < per-file commit.
-  //    A file settles at EOF only when every event extracted from it this run
-  //    was sent OK (zero-event files included); otherwise it settles at the
-  //    highest byte offset whose batch succeeded, so the rest re-sends.
-  const finalFiles: Record<string, CursorEntry> = { ...cursor.files };
-  for (const [fp, entry] of Object.entries(rotationResets)) finalFiles[fp] = entry;
-  for (const [fp, scan] of Object.entries(fileScans)) {
-    if ((sentCount[fp] ?? 0) >= scan.eventCount) {
-      finalFiles[fp] = {
-        offset: scan.eof,
-        mtime: scan.mtime,
-        ...(scan.pendingLine ? { pendingLine: scan.pendingLine } : {}),
-        ...(scan.codex ? { codex: scan.codex } : {}),
-      };
-    } else if (fp in committed) {
-      const entry = committed[fp];
-      finalFiles[fp] = {
-        offset: entry.offset,
-        mtime: scan.mtime,
-        ...(entry.codex ? { codex: entry.codex } : {}),
-      };
-    }
-    // else: no progress for this file — leave loaded/rotation-reset offset.
-  }
-  await saveCursor(cursorPath, {
-    version: "1",
-    files: finalFiles,
-    ...(Object.keys(lastScannedBySource).length > 0 ? { lastScannedBySource } : {}),
-  });
-
-  return {
-    enabled: true,
-    optInSource,
-    filesScanned: files.length,
-    eventsSent,
-    batchesSent,
-  };
-}