session-orchestrator 3.16.0 → 3.19.0

package/scripts/lib/telemetry/consent.mjs

@@ -0,0 +1,299 @@
+/**
+ * consent.mjs — anonymous-usage-telemetry consent layer (Epic #841, S1 / GL #842).
+ *
+ * Owns the persisted consent record (`~/.config/session-orchestrator/telemetry.json`)
+ * and the pure `resolveConsent()` precedence machine that decides — from env vars,
+ * the host-local owner.yaml fleet flag, and the stored per-user decision — whether
+ * telemetry may be SENT at all.
+ *
+ * ── Fail-closed by design (Learning conf 0.9) ────────────────────────────────
+ * The `send` bit is true ONLY when an explicitly affirmative signal is present
+ * (`SO_TELEMETRY=1`, `owner.yaml telemetry.enabled === true`, or a stored
+ * `consent: 'granted'`). Every ambiguous, missing, or corrupt state resolves to
+ * `send: false`. "Not explicitly disabled" is NEVER treated as consent.
+ *
+ * ── Precedence (highest wins) ────────────────────────────────────────────────
+ *   1. DO_NOT_TRACK (set, non-empty, not '0'/'false')  → disabled-env
+ *   2. SO_TELEMETRY_DISABLED === '1'                    → disabled-env
+ *   3. SO_TELEMETRY === '1'                             → enabled-env
+ *   4. ownerConfig.telemetry.enabled === true (strict) → enabled-fleet
+ *   5. state.consent === 'granted'                      → enabled-consent
+ *   6. state.consent === 'denied'                       → disabled-consent
+ *   7. (otherwise)                                      → no-consent
+ *
+ * The env pair (1/2) is the per-shell escape hatch that outranks the fleet flag
+ * (PRD AC FA5): a fleet-opted host still honours `SO_TELEMETRY_DISABLED=1` /
+ * `DO_NOT_TRACK` for a single shell. The fleet flag (4) intentionally outranks a
+ * stored `denied` (6) — owner.yaml is the operator's host-level decision.
+ *
+ * No `anon_id` is ever minted here — id generation is lazy and lives in a sibling
+ * module; this layer only preserves the field across read/modify/write.
+ *
+ * Node ESM, no external deps beyond `scripts/lib/io.mjs` (atomic write).
+ */
+
+import { readFileSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+import { writeJsonAtomicSync } from '../io.mjs';
+import { TELEMETRY_DIR, TELEMETRY_JSON_PATH, TELEMETRY_QUEUE_PATH } from './paths.mjs';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Schema version stamped into every telemetry.json record. */
+export const CONSENT_SCHEMA_VERSION = 1;
+
+// Path constants are single-sourced in ./paths.mjs — a constants-only leaf
+// module that both consent.mjs (policy) and queue.mjs (storage) import, so
+// neither depends on the other. Re-exported here for backward-compat: these
+// were consent.mjs exports before the extraction.
+export { TELEMETRY_DIR, TELEMETRY_JSON_PATH, TELEMETRY_QUEUE_PATH };
+
+/** Consent enum stored in the record's `consent` field. */
+const CONSENT_GRANTED = 'granted';
+const CONSENT_DENIED = 'denied';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+/**
+ * A fresh default record: everything null, schema_version pinned. Returned when
+ * the file is missing or corrupt so callers never see partial/garbage state.
+ * @returns {{schema_version: number, consent: null, decided_at: null, anon_id: null, anon_id_created_at: null, last_flush_at: null}}
+ */
+function defaultRecord() {
+  return {
+    schema_version: CONSENT_SCHEMA_VERSION,
+    consent: null,
+    decided_at: null,
+    anon_id: null,
+    anon_id_created_at: null,
+    last_flush_at: null,
+  };
+}
+
+/**
+ * True when an env var carries a truthy "on" signal: present, trims to a
+ * non-empty string that is neither '0' nor (case-insensitively) 'false'.
+ * @param {unknown} raw
+ * @returns {boolean}
+ */
+function isTruthyEnvFlag(raw) {
+  if (raw === undefined || raw === null) return false;
+  const t = String(raw).trim();
+  if (t === '' || t === '0') return false;
+  if (t.toLowerCase() === 'false') return false;
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Persistence
+// ---------------------------------------------------------------------------
+
+/**
+ * Read and normalise the persisted consent record. NEVER throws.
+ *
+ * - Missing file            → `{ source: 'default' }` + a fresh default record.
+ * - Unparseable / non-object → `{ source: 'corrupt' }` + default record + a
+ *   stderr WARN pointing at `telemetry status`; the errors array names the fault.
+ * - Valid object            → `{ source: 'file' }`; missing known fields are
+ *   filled from defaults and UNKNOWN fields are preserved (additive tolerance).
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.path]  Override the read path (test injection).
+ * @returns {{ record: object, source: 'file'|'default'|'corrupt', errors: string[] }}
+ */
+export function readTelemetryState({ path } = {}) {
+  const target = path || TELEMETRY_JSON_PATH;
+
+  if (!existsSync(target)) {
+    return { record: defaultRecord(), source: 'default', errors: [] };
+  }
+
+  let raw;
+  try {
+    raw = readFileSync(target, 'utf8');
+  } catch (err) {
+    const msg = `telemetry.json unreadable: ${err?.message ?? String(err)}`;
+    console.error(`⚠ telemetry: ${msg}. Using defaults — run 'telemetry status' to inspect.`);
+    return { record: defaultRecord(), source: 'corrupt', errors: [msg] };
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    const msg = `telemetry.json is not valid JSON: ${err?.message ?? String(err)}`;
+    console.error(`⚠ telemetry: ${msg}. Using defaults — run 'telemetry status' to inspect.`);
+    return { record: defaultRecord(), source: 'corrupt', errors: [msg] };
+  }
+
+  if (!isPlainObject(parsed)) {
+    const msg = `telemetry.json is not an object (got ${Array.isArray(parsed) ? 'array' : typeof parsed})`;
+    console.error(`⚠ telemetry: ${msg}. Using defaults — run 'telemetry status' to inspect.`);
+    return { record: defaultRecord(), source: 'corrupt', errors: [msg] };
+  }
+
+  // Additive tolerance: defaults fill missing known fields, `parsed` overrides
+  // and carries any unknown fields through untouched.
+  const record = { ...defaultRecord(), ...parsed };
+  return { record, source: 'file', errors: [] };
+}
+
+/**
+ * Atomically persist a consent record via {@link writeJsonAtomicSync}. Creates
+ * the parent directory first. NEVER throws — filesystem failures are returned.
+ *
+ * @param {object} record  The full record to persist.
+ * @param {object} [opts]
+ * @param {string} [opts.path]  Override the write path (test injection).
+ * @returns {{ ok: boolean, error?: string }}
+ */
+export function writeTelemetryState(record, { path } = {}) {
+  const target = path || TELEMETRY_JSON_PATH;
+  try {
+    mkdirSync(dirname(target), { recursive: true });
+  } catch (err) {
+    return { ok: false, error: err?.message ?? String(err) };
+  }
+  const res = writeJsonAtomicSync(target, record);
+  return res.ok ? { ok: true } : { ok: false, error: res.error };
+}
+
+// ---------------------------------------------------------------------------
+// Consent decision
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {'disabled-env'|'disabled-consent'|'enabled-env'|'enabled-fleet'|'enabled-consent'|'no-consent'} ConsentState
+ */
+
+/**
+ * Resolve the effective telemetry posture from all signals. Pure — no I/O.
+ * Fail-closed: `send` is true ONLY for the three `enabled-*` states.
+ *
+ * @param {object} [opts]
+ * @param {Record<string, string|undefined>} [opts.env]  Env source (default process.env).
+ * @param {object} [opts.ownerConfig]  Parsed owner.yaml object (fleet flag lives at `.telemetry.enabled`).
+ * @param {object|null} [opts.state]    A persisted record (from {@link readTelemetryState}).
+ * @param {boolean} [opts.interactive]  Whether a TTY prompt is possible right now.
+ * @returns {{ state: ConsentState, send: boolean, prompt: boolean, reason: string }}
+ */
+export function resolveConsent({ env = process.env, ownerConfig = {}, state = null, interactive = false } = {}) {
+  // 1. DO_NOT_TRACK — universal opt-out, per-shell escape above everything.
+  if (isTruthyEnvFlag(env?.DO_NOT_TRACK)) {
+    return { state: 'disabled-env', send: false, prompt: false, reason: 'DO_NOT_TRACK is set' };
+  }
+
+  // 2. SO_TELEMETRY_DISABLED=1 — per-shell escape, outranks SO_TELEMETRY and fleet.
+  if (env?.SO_TELEMETRY_DISABLED === '1') {
+    return { state: 'disabled-env', send: false, prompt: false, reason: 'SO_TELEMETRY_DISABLED=1' };
+  }
+
+  // 3. SO_TELEMETRY=1 — explicit per-shell opt-in.
+  if (env?.SO_TELEMETRY === '1') {
+    return { state: 'enabled-env', send: true, prompt: false, reason: 'SO_TELEMETRY=1' };
+  }
+
+  // 4. Fleet flag — owner.yaml telemetry.enabled must be STRICTLY boolean true.
+  if (ownerConfig?.telemetry?.enabled === true) {
+    return { state: 'enabled-fleet', send: true, prompt: false, reason: 'owner.yaml telemetry.enabled=true' };
+  }
+
+  // 5/6. Stored per-user decision.
+  if (state?.consent === CONSENT_GRANTED) {
+    return { state: 'enabled-consent', send: true, prompt: false, reason: 'stored consent: granted' };
+  }
+  if (state?.consent === CONSENT_DENIED) {
+    return { state: 'disabled-consent', send: false, prompt: false, reason: 'stored consent: denied' };
+  }
+
+  // 7. No decision on record — only prompt when a TTY is available; never send.
+  return {
+    state: 'no-consent',
+    send: false,
+    prompt: interactive === true,
+    reason: 'no consent decision recorded',
+  };
+}
+
+/**
+ * Read-modify-atomic-write helper shared by grant/deny. Preserves the anon_id
+ * fields and any unknown fields already on the record; starts from a clean
+ * default record when the on-disk file is missing or corrupt (no garbage merge).
+ *
+ * @param {'granted'|'denied'} decision
+ * @param {{ path?: string, now: string }} args
+ * @returns {{ ok: boolean, record: object }}
+ */
+function setConsentDecision(decision, { path, now }) {
+  const { record } = readTelemetryState({ path });
+  const next = { ...record, consent: decision, decided_at: now };
+  const res = writeTelemetryState(next, { path });
+  return { ok: res.ok, record: next };
+}
+
+/**
+ * Record an affirmative consent decision. anon_id fields are left untouched.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.path]  Override the state path (test injection).
+ * @param {string} [opts.now]   ISO timestamp for `decided_at` (defaults to now).
+ * @returns {{ ok: boolean, record: object }}
+ */
+export function grantConsent({ path, now = new Date().toISOString() } = {}) {
+  return setConsentDecision(CONSENT_GRANTED, { path, now });
+}
+
+/**
+ * Record a refusal decision. anon_id fields are left untouched.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.path]  Override the state path (test injection).
+ * @param {string} [opts.now]   ISO timestamp for `decided_at` (defaults to now).
+ * @returns {{ ok: boolean, record: object }}
+ */
+export function denyConsent({ path, now = new Date().toISOString() } = {}) {
+  return setConsentDecision(CONSENT_DENIED, { path, now });
+}
+
+// ---------------------------------------------------------------------------
+// Environment probes
+// ---------------------------------------------------------------------------
+
+/**
+ * True when running in a recognised CI environment: `CI` set to a truthy value,
+ * or any of the well-known CI marker vars present and non-empty.
+ *
+ * @param {Record<string, string|undefined>} [env]  Env source (default process.env).
+ * @returns {boolean}
+ */
+export function isCiEnv(env = process.env) {
+  if (isTruthyEnvFlag(env?.CI)) return true;
+  for (const key of ['GITHUB_ACTIONS', 'GITLAB_CI', 'CONTINUOUS_INTEGRATION']) {
+    const v = env?.[key];
+    if (v !== undefined && v !== null && String(v).trim() !== '') return true;
+  }
+  return false;
+}
+
+/**
+ * True when there is no interactive TTY to prompt on: any CI environment, or a
+ * stdout that is not a TTY. Fail-closed toward headless — anything that is not a
+ * confirmed interactive TTY counts as headless.
+ *
+ * @param {Record<string, string|undefined>} [env]  Env source (default process.env).
+ * @param {{ stdout?: { isTTY?: boolean } }} [streams]  Stream source (default process).
+ * @returns {boolean}
+ */
+export function isHeadless(env = process.env, streams = process) {
+  if (isCiEnv(env)) return true;
+  return streams?.stdout?.isTTY !== true;
+}

package/scripts/lib/telemetry/paths.mjs

@@ -0,0 +1,27 @@
+/**
+ * telemetry/paths.mjs — host-local telemetry paths (Epic #841).
+ *
+ * Host-local telemetry paths — constants only, imported by both consent.mjs
+ * (policy) and queue.mjs (storage) to avoid a wrong-direction dependency.
+ *
+ * This module holds NO logic and performs NO I/O beyond computing three path
+ * constants under `~/.config/session-orchestrator/` at import time. Because it
+ * depends on nothing else in the telemetry tree, both the policy layer
+ * (consent.mjs) and the storage layer (queue.mjs) single-source their paths
+ * here without either importing the other. The earlier queue.mjs → consent.mjs
+ * edge was a wrong-direction dependency — the generic offline queue must not
+ * hang off the telemetry consent policy; routing both through this leaf module
+ * removes that coupling while keeping a single source of truth for the paths.
+ */
+
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+/** Host-local config directory holding all telemetry state. */
+export const TELEMETRY_DIR = join(homedir(), '.config', 'session-orchestrator');
+
+/** Default path for the persisted consent record. */
+export const TELEMETRY_JSON_PATH = join(TELEMETRY_DIR, 'telemetry.json');
+
+/** Default path for the pending-events send queue (owned by queue.mjs). */
+export const TELEMETRY_QUEUE_PATH = join(TELEMETRY_DIR, 'telemetry-queue.ndjson');

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\./;