session-orchestrator 3.16.0 → 3.17.0

package/scripts/lib/telemetry/queue.mjs

@@ -0,0 +1,287 @@
+/**
+ * telemetry/queue.mjs — host-local bounded NDJSON offline queue for anonymous
+ * usage telemetry (Epic #841, Issue #844 FA3).
+ *
+ * Persists telemetry batches to a single NDJSON file at
+ * `~/.config/session-orchestrator/telemetry-queue.ndjson` (one JSON object per
+ * line: `{ queued_at, batch }`) so that a batch collected while the sender is
+ * offline (network down, endpoint unreachable) is not lost — it waits in the
+ * queue until the next successful `drain()`.
+ *
+ * The queue is BOUNDED on two independent axes — batch count (`MAX_BATCHES`)
+ * and serialized byte size (`MAX_QUEUE_BYTES`) — dropping the OLDEST entries
+ * first (FIFO) whenever either cap is exceeded. This prevents an unbounded
+ * queue from growing across an extended offline period.
+ *
+ * Every public function accepts a `{ path }` override (defaulting to
+ * `TELEMETRY_QUEUE_PATH`) for test injection, and NEVER throws — filesystem
+ * or serialization failures are swallowed and reported via the function's
+ * own result shape, mirroring the `scripts/lib/eval/sink.mjs` /
+ * `scripts/lib/events-rotation.mjs` "never throw a caller can't route around"
+ * convention used elsewhere in this repo.
+ *
+ * This storage layer imports ONLY the constants-only leaf module ./paths.mjs
+ * (for TELEMETRY_QUEUE_PATH) and the generic ../io.mjs helpers — never a policy
+ * sibling (consent.mjs) or the schema. Keeping the queue off the consent policy
+ * preserves the correct dependency direction: the generic offline queue must not
+ * hang off the telemetry consent layer.
+ */
+
+import { dirname, join } from 'node:path';
+import { mkdirSync, writeFileSync, renameSync, existsSync, statSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { readJsonlFile } from '../io.mjs';
+import { TELEMETRY_QUEUE_PATH } from './paths.mjs';
+
+/** Host-local NDJSON offline queue path — single-sourced from ./paths.mjs (a constants-only leaf module; two independently computed copies can silently drift). */
+export { TELEMETRY_QUEUE_PATH };
+
+/** Maximum number of queued batch entries before oldest-first eviction kicks in. */
+export const MAX_BATCHES = 50;
+
+/** Maximum serialized queue size in bytes before oldest-first eviction kicks in. */
+export const MAX_QUEUE_BYTES = 256 * 1024;
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Read all queue entries from disk. Never throws: a missing file yields `[]`
+ * and any corrupted/malformed line is silently skipped (readJsonlFile with
+ * `skipInvalid: true`) — a corrupted line is dropped for good the next time
+ * the queue is rewritten (enqueue/drain/dropOldest/clear all rewrite in full).
+ *
+ * @param {string} filePath
+ * @returns {Array<{queued_at: string, batch: object}>}
+ */
+function _readEntries(filePath) {
+  try {
+    return readJsonlFile(filePath, { skipInvalid: true });
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Serialize entries as NDJSON text (one JSON object per line, trailing
+ * newline when non-empty; empty string when entries is empty).
+ *
+ * @param {Array<object>} entries
+ * @returns {string}
+ */
+function _toNdjson(entries) {
+  if (entries.length === 0) return '';
+  return `${entries.map((entry) => JSON.stringify(entry)).join('\n')}\n`;
+}
+
+/**
+ * Byte length of the entries once serialized as NDJSON — used to enforce
+ * `MAX_QUEUE_BYTES`.
+ *
+ * @param {Array<object>} entries
+ * @returns {number}
+ */
+function _serializedByteLength(entries) {
+  return Buffer.byteLength(_toNdjson(entries), 'utf8');
+}
+
+/**
+ * Atomically replace `filePath` with the NDJSON serialization of `entries`
+ * via tmp-file + `renameSync` in the SAME directory (same-filesystem rename
+ * is atomic on POSIX — mirrors `writeJsonAtomicSync` in `scripts/lib/io.mjs`,
+ * which has no NDJSON-array variant). Creates the parent directory with
+ * `mkdirSync(dir, { recursive: true })` first.
+ *
+ * @param {string} filePath
+ * @param {Array<object>} entries
+ * @throws {Error} on filesystem failure — callers MUST catch (this helper is
+ *         intentionally throw-on-failure; the never-throws contract lives at
+ *         the public-API layer).
+ */
+function _writeEntriesAtomicSync(filePath, entries) {
+  const dir = dirname(filePath);
+  mkdirSync(dir, { recursive: true });
+  const tmpSuffix = randomBytes(6).toString('hex');
+  const tmpFile = join(dir, `.tmp.${tmpSuffix}`);
+  writeFileSync(tmpFile, _toNdjson(entries), 'utf8');
+  renameSync(tmpFile, filePath);
+}
+
+/**
+ * Evict oldest entries (FIFO) until both the batch-count cap and the
+ * serialized-byte cap are satisfied.
+ *
+ * @param {Array<object>} entries
+ * @param {number} maxBatches
+ * @param {number} maxBytes
+ * @returns {{entries: Array<object>, dropped: number}}
+ */
+function _enforceCaps(entries, maxBatches, maxBytes) {
+  let out = entries;
+  let dropped = 0;
+
+  while (out.length > maxBatches) {
+    out = out.slice(1);
+    dropped++;
+  }
+  while (out.length > 0 && _serializedByteLength(out) > maxBytes) {
+    out = out.slice(1);
+    dropped++;
+  }
+
+  return { entries: out, dropped };
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Append a telemetry batch to the offline queue, then evict the oldest
+ * entries (FIFO) until both `maxBatches` and `maxBytes` caps are satisfied.
+ * Rewrites the queue file atomically. Never throws.
+ *
+ * @param {object} batch — arbitrary JSON-serializable telemetry batch payload.
+ * @param {object} [opts]
+ * @param {string} [opts.path] — queue file path override (defaults to `TELEMETRY_QUEUE_PATH`).
+ * @param {string} [opts.now] — ISO8601 timestamp stamped as `queued_at` (defaults to `new Date().toISOString()`).
+ * @param {number} [opts.maxBatches] — batch-count cap (defaults to `MAX_BATCHES`).
+ * @param {number} [opts.maxBytes] — serialized-byte cap (defaults to `MAX_QUEUE_BYTES`).
+ * @returns {{ok: true, dropped: number, total: number} | {ok: false, dropped: 0, total: 0, error: string}}
+ */
+export function enqueue(batch, opts = {}) {
+  const {
+    path: filePath = TELEMETRY_QUEUE_PATH,
+    now = new Date().toISOString(),
+    maxBatches = MAX_BATCHES,
+    maxBytes = MAX_QUEUE_BYTES,
+  } = opts;
+
+  try {
+    const existing = _readEntries(filePath);
+    const entry = { queued_at: now, batch };
+    const combined = [...existing, entry];
+
+    const { entries, dropped } = _enforceCaps(combined, maxBatches, maxBytes);
+
+    _writeEntriesAtomicSync(filePath, entries);
+    return { ok: true, dropped, total: entries.length };
+  } catch (err) {
+    return { ok: false, dropped: 0, total: 0, error: err?.message ?? String(err) };
+  }
+}
+
+/**
+ * Drain the queue by handing all queued batches to `sender` as a single call.
+ * On success (sender's returned promise resolves), the queue is atomically
+ * emptied. On failure (sender's promise rejects or throws synchronously), the
+ * queue is left byte-identical to before the call. When `sender` is omitted,
+ * this is a no-op. Never throws.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.path] — queue file path override (defaults to `TELEMETRY_QUEUE_PATH`).
+ * @param {(batches: object[]) => Promise<void>} [opts.sender] — async callback invoked with all queued batch payloads.
+ * @returns {Promise<{sent: number, remaining: number, dropped: number}>}
+ */
+export async function drain(opts = {}) {
+  const { path: filePath = TELEMETRY_QUEUE_PATH, sender } = opts;
+
+  const entries = _readEntries(filePath);
+
+  if (typeof sender !== 'function') {
+    return { sent: 0, remaining: entries.length, dropped: 0 };
+  }
+
+  try {
+    await sender(entries.map((entry) => entry.batch));
+  } catch {
+    return { sent: 0, remaining: entries.length, dropped: 0 };
+  }
+
+  try {
+    _writeEntriesAtomicSync(filePath, []);
+    return { sent: entries.length, remaining: 0, dropped: 0 };
+  } catch {
+    // Sender succeeded but the queue could not be cleared — report the
+    // batches as unsent-safe (still on disk) rather than losing them.
+    return { sent: 0, remaining: entries.length, dropped: 0 };
+  }
+}
+
+/**
+ * Read all queue entries without mutating the queue. Never throws.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.path] — queue file path override (defaults to `TELEMETRY_QUEUE_PATH`).
+ * @returns {Array<{queued_at: string, batch: object}>} — `[]` when the queue file does not exist.
+ */
+export function peekAll(opts = {}) {
+  const { path: filePath = TELEMETRY_QUEUE_PATH } = opts;
+  return _readEntries(filePath);
+}
+
+/**
+ * Drop the `n` oldest entries (FIFO) from the queue and atomically rewrite
+ * it. Never throws.
+ *
+ * @param {number} n — number of oldest entries to drop (clamped to `[0, queue length]`).
+ * @param {object} [opts]
+ * @param {string} [opts.path] — queue file path override (defaults to `TELEMETRY_QUEUE_PATH`).
+ * @returns {{dropped: number, remaining: number}}
+ */
+export function dropOldest(n, opts = {}) {
+  const { path: filePath = TELEMETRY_QUEUE_PATH } = opts;
+
+  try {
+    const entries = _readEntries(filePath);
+    const count = Number.isFinite(n) && n > 0 ? Math.floor(n) : 0;
+    const dropCount = Math.min(count, entries.length);
+    const remaining = entries.slice(dropCount);
+
+    _writeEntriesAtomicSync(filePath, remaining);
+    return { dropped: dropCount, remaining: remaining.length };
+  } catch {
+    return { dropped: 0, remaining: 0 };
+  }
+}
+
+/**
+ * Empty the queue (atomic truncate to zero entries). Never throws.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.path] — queue file path override (defaults to `TELEMETRY_QUEUE_PATH`).
+ * @returns {{ok: boolean}}
+ */
+export function clear(opts = {}) {
+  const { path: filePath = TELEMETRY_QUEUE_PATH } = opts;
+  try {
+    _writeEntriesAtomicSync(filePath, []);
+    return { ok: true };
+  } catch {
+    return { ok: false };
+  }
+}
+
+/**
+ * Report current queue occupancy. Never throws.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.path] — queue file path override (defaults to `TELEMETRY_QUEUE_PATH`).
+ * @returns {{count: number, bytes: number}} — `bytes` is the on-disk file size (`0` when the file does not exist).
+ */
+export function queueStats(opts = {}) {
+  const { path: filePath = TELEMETRY_QUEUE_PATH } = opts;
+  try {
+    const entries = _readEntries(filePath);
+    const bytes = existsSync(filePath) ? statSync(filePath).size : 0;
+    return { count: entries.length, bytes };
+  } catch {
+    return { count: 0, bytes: 0 };
+  }
+}
+
+// Exported for atomicity-smoke tests that want to confirm no stray tmp file
+// is left behind after a write (avoids re-deriving the tmp-name pattern
+// baked into `_writeEntriesAtomicSync` above).
+export const _TMP_FILE_PATTERN = /^\.tmp\./;

package/scripts/lib/telemetry/schema.mjs

@@ -0,0 +1,384 @@
+/**
+ * telemetry/schema.mjs — usage-ping v1 schema, whitelist projection, roster
+ * filter, and payload builder for anonymous usage telemetry (Epic #841, S2 /
+ * GitLab #843; PRD docs/prd/2026-07-20-anonymous-usage-telemetry.md §3-FA2).
+ *
+ * Privacy is the raison d'être of this module. It mirrors the data-minimization
+ * pattern of scripts/lib/eval/schema.mjs (SUBMISSION_FIELDS + projectSubmission):
+ * a FROZEN field whitelist plus a data-driven projection so nothing outside the
+ * whitelist can ever reach the wire — no paths, repo names, prompts, args, git
+ * remotes, or hostnames. Skill/command names are additionally projected against
+ * the shipped plugin roster: any name not in the roster becomes the opaque token
+ * "other", so custom/third-party names never leave the machine.
+ *
+ * ── USAGE-PING RECORD (schema_version: 1, record_kind: "usage-ping") ─────────
+ *   record_kind      'usage-ping'
+ *   schema_version   1
+ *   anon_id          set downstream by ensureAnonId (anon-id.mjs) — NOT here
+ *   sent_at          ISO 8601 string (passed in as `now`)
+ *   plugin_version   package.json version at SO_PLUGIN_ROOT, or 'unknown'
+ *   platform         claude|codex|cursor|pi (+ 'other' fallback)
+ *   os               normalizeOs(process.platform) — closed set, else 'other'
+ *   arch             normalizeArch(process.arch) — closed set, else 'other'
+ *   node_major       integer major version of the running Node
+ *   ci               boolean — running under CI
+ *   fleet            boolean — operator fleet mode (owner.yaml telemetry.enabled)
+ *   session_type     housekeeping|feature|deep (+ 'other' fallback)
+ *   duration_bucket  '<15m'|'15-60m'|'1-3h'|'>3h'
+ *   skills           roster-filtered, deduped, sorted string[] (≤100)
+ *   commands         roster-filtered, deduped, sorted string[] (≤100)
+ *
+ * The builder returns the record WITHOUT anon_id — the caller sets it via
+ * ensureAnonId so the ID-rotation concern stays isolated in anon-id.mjs.
+ *
+ * This module reads files (package.json, the roster surface dirs) but writes
+ * none and holds no mutable runtime state.
+ */
+
+import { SO_PLATFORM, SO_PLUGIN_ROOT } from '../platform.mjs';
+import { enumerateSurface } from '../sunset/walker.mjs';
+import { readPluginVersionFromPackageJson } from '../bootstrap-lock-freshness.mjs';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Current usage-ping schema version. Additive-only within a version. */
+export const USAGE_PING_SCHEMA_VERSION = 1;
+
+/**
+ * FROZEN whitelist of the ONLY fields a usage-ping may carry. projectUsagePing is
+ * fully data-driven from this list: a field absent here is dropped. Widening this
+ * list is the intended fake-regression tripwire — adding a leaky field (e.g.
+ * 'repo') turns the data-minimization projection test RED.
+ */
+export const USAGE_PING_FIELDS = Object.freeze([
+  'record_kind',
+  'schema_version',
+  'anon_id',
+  'sent_at',
+  'plugin_version',
+  'platform',
+  'os',
+  'arch',
+  'node_major',
+  'ci',
+  'fleet',
+  'session_type',
+  'duration_bucket',
+  'skills',
+  'commands',
+]);
+
+/** Exact duration-bucket tokens (ASCII, stable wire values). */
+export const DURATION_BUCKETS = Object.freeze(['<15m', '15-60m', '1-3h', '>3h']);
+
+/** Roster-projection guardrails. */
+const ROSTER_OTHER = 'other';
+const MAX_NAME_LENGTH = 64;
+const MAX_NAMES = 100;
+
+/** Enum fallbacks. */
+const VALID_PLATFORMS = Object.freeze(['claude', 'codex', 'cursor', 'pi']);
+const VALID_SESSION_TYPES = Object.freeze(['housekeeping', 'feature', 'deep']);
+const PLATFORM_OTHER = 'other';
+const SESSION_TYPE_OTHER = 'other';
+
+/**
+ * Closed sets for os/arch client-side normalization. A value outside the set —
+ * including a future Node os/arch string — degrades to 'other', so the client
+ * never sends a value the server's enum would reject with a 400. These MUST
+ * mirror the server's OS/ARCH enums (server/validate.mjs); a loong64 client
+ * therefore sends 'loong64' (in-set → accepted with a signal), while a
+ * hypothetical unknown value degrades safely.
+ */
+const OS_VALUES = Object.freeze(['aix', 'darwin', 'freebsd', 'linux', 'openbsd', 'sunos', 'win32', 'android']);
+const ARCH_VALUES = Object.freeze([
+  'arm', 'arm64', 'ia32', 'loong64', 'mips', 'mipsel', 'ppc', 'ppc64', 'riscv64', 's390', 's390x', 'x64',
+]);
+const OS_OTHER = 'other';
+const ARCH_OTHER = 'other';
+
+/** Prefix under which skills are recorded in skill-invocations.jsonl. */
+const SKILL_PREFIX = 'session-orchestrator:';
+
+const MS_PER_SECOND = 1000;
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+function isNonEmptyString(v) {
+  return typeof v === 'string' && v.trim().length > 0;
+}
+
+// ---------------------------------------------------------------------------
+// Whitelist projection (Data-Minimization)
+// ---------------------------------------------------------------------------
+
+/**
+ * Project an arbitrary object onto the usage-ping whitelist (USAGE_PING_FIELDS).
+ * Fully data-driven: any key not on the whitelist — paths, repo names, prompts,
+ * args, hostnames, rogue extras — is dropped. Array fields (skills, commands) are
+ * copied as NEW arrays so no caller reference leaks into the projection.
+ *
+ * @param {object} input
+ * @returns {object} whitelist-safe projection
+ */
+export function projectUsagePing(input) {
+  if (!isPlainObject(input)) return {};
+  const out = {};
+  for (const key of USAGE_PING_FIELDS) {
+    if (key in input) {
+      const v = input[key];
+      out[key] = Array.isArray(v) ? [...v] : v;
+    }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Roster loader
+// ---------------------------------------------------------------------------
+
+/**
+ * Load the shipped plugin roster (skills + commands) from the on-disk surface.
+ * Uses enumerateSurface() against SO_PLUGIN_ROOT (never process.cwd()) so the
+ * roster reflects the INSTALLED plugin, not the operator's working directory.
+ *
+ * skills are returned prefixed with 'session-orchestrator:' (matching the names
+ * recorded in skill-invocations.jsonl); commands are bare.
+ *
+ * Fail-closed: if the surface directory is missing (e.g. a partial npm install)
+ * or enumeration throws, this returns EMPTY sets and a stderr WARN — an empty
+ * roster means every name projects to "other", never a leak.
+ *
+ * @param {{pluginRoot?: string}} [opts]
+ * @returns {{skills: Set<string>, commands: Set<string>}}
+ */
+export function loadRoster({ pluginRoot } = {}) {
+  const root = (typeof pluginRoot === 'string' && pluginRoot.trim() !== '')
+    ? pluginRoot
+    : SO_PLUGIN_ROOT;
+
+  if (!isNonEmptyString(root)) {
+    process.stderr.write(
+      "[telemetry] WARN: plugin root unresolved — roster empty, all skill/command names project to 'other'\n",
+    );
+    return { skills: new Set(), commands: new Set() };
+  }
+
+  try {
+    const surface = enumerateSurface(root);
+    const skills = new Set((surface.skills ?? []).map((name) => `${SKILL_PREFIX}${name}`));
+    const commands = new Set(surface.commands ?? []);
+    if (skills.size === 0 && commands.size === 0) {
+      process.stderr.write(
+        `[telemetry] WARN: roster surface empty at ${root} — all skill/command names project to 'other'\n`,
+      );
+    }
+    return { skills, commands };
+  } catch (err) {
+    process.stderr.write(
+      `[telemetry] WARN: roster enumeration failed (${err?.message ?? err}) — all names project to 'other'\n`,
+    );
+    return { skills: new Set(), commands: new Set() };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Roster name filter
+// ---------------------------------------------------------------------------
+
+/**
+ * Project a list of raw names onto the roster: a name present in `rosterSet` is
+ * kept verbatim; anything else (off-roster, non-string, or longer than
+ * MAX_NAME_LENGTH chars) becomes the opaque token "other". The result is
+ * deduplicated and sorted, "other" appears at most once, and the list is capped
+ * at MAX_NAMES entries.
+ *
+ * @param {string[]} names
+ * @param {Set<string>} rosterSet
+ * @returns {string[]} deduped, sorted, roster-safe names (≤ MAX_NAMES)
+ */
+export function filterRosterNames(names, rosterSet) {
+  const roster = rosterSet instanceof Set ? rosterSet : new Set();
+  const raw = Array.isArray(names) ? names : [];
+  const mapped = [];
+  for (const name of raw) {
+    if (typeof name !== 'string' || name.length > MAX_NAME_LENGTH) {
+      mapped.push(ROSTER_OTHER);
+      continue;
+    }
+    mapped.push(roster.has(name) ? name : ROSTER_OTHER);
+  }
+  const deduped = [...new Set(mapped)].sort();
+  return deduped.slice(0, MAX_NAMES);
+}
+
+// ---------------------------------------------------------------------------
+// Duration bucketing
+// ---------------------------------------------------------------------------
+
+/**
+ * Map a session duration to a coarse bucket. Boundaries (seconds):
+ *   <900        → '<15m'
+ *   [900, 3600) → '15-60m'
+ *   [3600, 10800] → '1-3h'   (exactly 1h and exactly 3h both land here)
+ *   >10800      → '>3h'
+ *
+ * Fail-safe: an unparsable, missing, or negative duration returns the most
+ * conservative bucket '<15m' (never throws).
+ *
+ * @param {string} startedAtISO
+ * @param {string} completedAtISO
+ * @returns {'<15m'|'15-60m'|'1-3h'|'>3h'}
+ */
+export function deriveDurationBucket(startedAtISO, completedAtISO) {
+  const start = typeof startedAtISO === 'string' ? Date.parse(startedAtISO) : NaN;
+  const end = typeof completedAtISO === 'string' ? Date.parse(completedAtISO) : NaN;
+  if (Number.isNaN(start) || Number.isNaN(end)) return '<15m';
+
+  const seconds = (end - start) / MS_PER_SECOND;
+  if (!Number.isFinite(seconds) || seconds < 0) return '<15m';
+  if (seconds < 900) return '<15m';
+  if (seconds < 3600) return '15-60m';
+  if (seconds <= 10800) return '1-3h';
+  return '>3h';
+}
+
+// ---------------------------------------------------------------------------
+// Field derivation helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Plugin version from package.json at SO_PLUGIN_ROOT; 'unknown' on any failure.
+ * Single-sourced through readPluginVersionFromPackageJson (bootstrap-lock-freshness.mjs),
+ * whose null return (missing/unparseable package.json or non-string version) maps to 'unknown'.
+ */
+function resolvePluginVersion() {
+  if (!isNonEmptyString(SO_PLUGIN_ROOT)) return 'unknown';
+  return readPluginVersionFromPackageJson(SO_PLUGIN_ROOT) ?? 'unknown';
+}
+
+/** Normalize the detected platform to the closed enum (+ 'other' fallback). */
+function normalizePlatform(platform) {
+  return VALID_PLATFORMS.includes(platform) ? platform : PLATFORM_OTHER;
+}
+
+/** Normalize the session type to the closed enum (+ 'other' fallback). */
+function normalizeSessionType(sessionType) {
+  return VALID_SESSION_TYPES.includes(sessionType) ? sessionType : SESSION_TYPE_OTHER;
+}
+
+/**
+ * Normalize an OS identifier (process.platform) against the closed OS_VALUES set.
+ * An in-set value is kept verbatim; anything else degrades to 'other' — mirrors
+ * normalizePlatform / normalizeSessionType so the client never emits a raw value
+ * the server enum would 400 on.
+ * @param {unknown} os
+ * @returns {string}
+ */
+export function normalizeOs(os) {
+  return OS_VALUES.includes(os) ? os : OS_OTHER;
+}
+
+/**
+ * Normalize a CPU arch identifier (process.arch) against the closed ARCH_VALUES
+ * set. In-set kept verbatim (e.g. 'loong64' survives); anything else → 'other'.
+ * @param {unknown} arch
+ * @returns {string}
+ */
+export function normalizeArch(arch) {
+  return ARCH_VALUES.includes(arch) ? arch : ARCH_OTHER;
+}
+
+/**
+ * CI detection from the env: a non-empty CI value that is not '0' and not (case-
+ * insensitively) 'false' counts as running under CI.
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {boolean}
+ */
+function deriveCi(env) {
+  const raw = env?.CI;
+  if (typeof raw !== 'string') return false;
+  const v = raw.trim();
+  if (v === '' || v === '0' || v.toLowerCase() === 'false') return false;
+  return true;
+}
+
+/** Distinct non-empty string values of `field` across a list of records. */
+function distinctField(records, field) {
+  const seen = new Set();
+  for (const rec of records) {
+    if (!isPlainObject(rec)) continue;
+    const value = rec[field];
+    if (isNonEmptyString(value)) seen.add(value);
+  }
+  return [...seen];
+}
+
+// ---------------------------------------------------------------------------
+// Payload builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a usage-ping record from local telemetry inputs. The returned record is
+ * whitelist-clean but does NOT carry `anon_id` — the caller sets it via
+ * ensureAnonId (anon-id.mjs), keeping ID rotation isolated there.
+ *
+ * skills are the distinct `.skill` values of `skillInvocations`; commands are the
+ * distinct `.command` values of the same records (none in v1 skill-invocations
+ * telemetry ⇒ []; the field is honored so a future command-telemetry stream feeds
+ * in without a signature change). Both are roster-filtered — off-roster names
+ * become "other" — deduped, sorted, and capped. No frequencies are recorded (v1
+ * decision).
+ *
+ * @param {{
+ *   sessionRecord: object,
+ *   skillInvocations: object[],
+ *   ownerConfig?: object,
+ *   env?: NodeJS.ProcessEnv,
+ *   now?: string,
+ *   roster?: {skills: Set<string>, commands: Set<string>}
+ * }} args
+ * @returns {object} usage-ping record (without anon_id)
+ */
+export function buildUsagePing({
+  sessionRecord,
+  skillInvocations,
+  ownerConfig,
+  env = process.env,
+  now = new Date().toISOString(),
+  roster,
+} = {}) {
+  const session = isPlainObject(sessionRecord) ? sessionRecord : {};
+  const invocations = Array.isArray(skillInvocations) ? skillInvocations : [];
+  const rst = roster ?? loadRoster();
+  const rosterSkills = rst?.skills instanceof Set ? rst.skills : new Set();
+  const rosterCommands = rst?.commands instanceof Set ? rst.commands : new Set();
+
+  const skillNames = distinctField(invocations, 'skill');
+  const commandNames = distinctField(invocations, 'command');
+
+  return {
+    record_kind: 'usage-ping',
+    schema_version: USAGE_PING_SCHEMA_VERSION,
+    sent_at: now,
+    plugin_version: resolvePluginVersion(),
+    platform: normalizePlatform(SO_PLATFORM),
+    os: normalizeOs(process.platform),
+    arch: normalizeArch(process.arch),
+    node_major: parseInt(process.versions.node, 10),
+    ci: deriveCi(env),
+    fleet: ownerConfig?.telemetry?.enabled === true,
+    session_type: normalizeSessionType(session.session_type),
+    duration_bucket: deriveDurationBucket(session.started_at, session.completed_at),
+    skills: filterRosterNames(skillNames, rosterSkills),
+    commands: filterRosterNames(commandNames, rosterCommands),
+  };
+}