session-orchestrator 3.16.0 → 3.17.0

package/scripts/lib/skill-health/join.mjs

@@ -15,6 +15,18 @@
  * the session is still in progress, or the record was never written), the session
  * contributes `unknown` to the outcome tally — it is never silently dropped.
  *
+ * ABANDONED-SESSION HANDLING (#834): a session_id CAN be found in sessions.jsonl
+ * yet be a phantom stub (`status: 'abandoned'`, written by session-close-backfill
+ * for a session that ended without a real close — 0 waves, all-zero agent_summary).
+ * Counting such a join as `sessionsJoined` would inflate the skill's join
+ * denominator with zero real contribution — the join "succeeds" but carries no
+ * signal. Per this module's own "never silently dropped" contract, an abandoned
+ * join is routed to a DISTINCT `abandoned` outcome bucket rather than either (a)
+ * silently folding into `sessionsJoined`/the numeric outcome fields with zero
+ * contribution (inflates the denominator invisibly), or (b) folding into
+ * `unknown` (which means "not found in the ledger at all" — a different failure
+ * mode a caller may want to distinguish from "found but phantom").
+ *
  * Part of Epic #645 — Skill Self-Evolution Foundation, Layer 2.
  */
 
@@ -22,6 +34,8 @@ import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { isRealSession } from '../session-schema/filters.mjs';
+
 const DEFAULT_INVOCATIONS_PATH = path.resolve(
   fileURLToPath(import.meta.url),
   '../../../../.orchestrator/metrics/skill-invocations.jsonl',
@@ -61,18 +75,21 @@ async function readJsonl(filePath) {
 }
 
 /**
- * Builds a Map<session_id, agent_summary> from sessions.jsonl records.
+ * Builds a Map<session_id, { agentSummary, real }> from sessions.jsonl records.
  * Records without a session_id or with a non-object agent_summary are skipped.
+ * `real` is false for phantom `status: 'abandoned'` stubs (#834) — callers use
+ * it to route the join to the `abandoned` outcome bucket instead of counting
+ * a zero-signal join as `sessionsJoined`.
  *
  * @param {object[]} sessionRecords
- * @returns {Map<string, { complete: number, partial: number, failed: number, spiral: number }>}
+ * @returns {Map<string, { agentSummary: { complete: number, partial: number, failed: number, spiral: number }, real: boolean }>}
  */
 function buildSessionMap(sessionRecords) {
   const map = new Map();
   for (const rec of sessionRecords) {
     if (typeof rec.session_id !== 'string' || !rec.session_id) continue;
     if (rec.agent_summary && typeof rec.agent_summary === 'object') {
-      map.set(rec.session_id, rec.agent_summary);
+      map.set(rec.session_id, { agentSummary: rec.agent_summary, real: isRealSession(rec) });
     }
   }
   return map;
@@ -91,12 +108,13 @@ function buildSessionMap(sessionRecords) {
  *       skill: string,
  *       selections: number,
  *       sessions: string[],
- *       outcomes: { complete: number, partial: number, failed: number, spiral: number, unknown: number }
+ *       outcomes: { complete: number, partial: number, failed: number, spiral: number, unknown: number, abandoned: number }
  *     }
  *   },
  *   totalSelections: number,
  *   sessionsJoined: number,
- *   sessionsUnknown: number
+ *   sessionsUnknown: number,
+ *   sessionsAbandoned: number
  * }>}
  */
 export async function joinSkillOutcomes({
@@ -116,6 +134,7 @@ export async function joinSkillOutcomes({
   let totalSelections = 0;
   let sessionsJoined = 0;
   let sessionsUnknown = 0;
+  let sessionsAbandoned = 0;
 
   for (const inv of invocations) {
     // Only process skill-selection events with a valid skill field
@@ -132,7 +151,7 @@ export async function joinSkillOutcomes({
         skill,
         selectionCount: 0,
         sessions: new Set(),
-        outcomes: { complete: 0, partial: 0, failed: 0, spiral: 0, unknown: 0 },
+        outcomes: { complete: 0, partial: 0, failed: 0, spiral: 0, unknown: 0, abandoned: 0 },
       });
     }
 
@@ -144,14 +163,21 @@ export async function joinSkillOutcomes({
       record.sessions.add(sessionId);
 
       if (isNew) {
-        const summary = sessionMap.get(sessionId);
-        if (summary) {
+        const entry = sessionMap.get(sessionId);
+        if (entry && entry.real) {
+          const summary = entry.agentSummary;
           // Sum session-level aggregate outcomes into this skill's buckets
           record.outcomes.complete += typeof summary.complete === 'number' ? summary.complete : 0;
           record.outcomes.partial += typeof summary.partial === 'number' ? summary.partial : 0;
           record.outcomes.failed += typeof summary.failed === 'number' ? summary.failed : 0;
           record.outcomes.spiral += typeof summary.spiral === 'number' ? summary.spiral : 0;
           sessionsJoined += 1;
+        } else if (entry && !entry.real) {
+          // Found in sessions.jsonl but a phantom abandoned stub (#834) — a
+          // zero-signal join. Route to a distinct bucket instead of inflating
+          // sessionsJoined or conflating with "not found at all" (unknown).
+          record.outcomes.abandoned += 1;
+          sessionsAbandoned += 1;
         } else {
           // Session id not found in sessions.jsonl — count as unknown, never drop
           record.outcomes.unknown += 1;
@@ -177,5 +203,5 @@ export async function joinSkillOutcomes({
     };
   }
 
-  return { bySkill: bySkillObj, totalSelections, sessionsJoined, sessionsUnknown };
+  return { bySkill: bySkillObj, totalSelections, sessionsJoined, sessionsUnknown, sessionsAbandoned };
 }

package/scripts/lib/telemetry/anon-id.mjs

@@ -0,0 +1,141 @@
+/**
+ * telemetry/anon-id.mjs — rotating anonymous ID for usage-telemetry (Epic #841,
+ * S2 / GitLab #843; PRD docs/prd/2026-07-20-anonymous-usage-telemetry.md §3-FA2).
+ *
+ * PURE, no I/O. The anonymous ID is a random UUID that rotates every
+ * ANON_ID_MAX_AGE_DAYS days. It is NEVER machine-derived (no hostname, MAC,
+ * install path, or any stable hardware/user identifier) — this is the privacy
+ * invariant that avoids the persistent-ID correlation criticism (PRD §4
+ * "Privacy engineering"). Rotation discards the old ID entirely.
+ *
+ * All time is passed IN as a parameter (`now`), never read from the clock inside
+ * this module, so callers stay deterministic and testable.
+ *
+ * Contract:
+ *   newAnonId()                          → a fresh random UUID (v4).
+ *   isExpired(createdAtISO, now, maxAge) → boolean; unparsable createdAt ⇒ true.
+ *   ensureAnonId(record, opts)           → { record, anon_id, rotated, created }.
+ */
+
+import { randomUUID } from 'node:crypto';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Rotate the anonymous ID after this many days. */
+export const ANON_ID_MAX_AGE_DAYS = 90;
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+/**
+ * Resolve a `now` argument to epoch-ms. Accepts either a number (already epoch-ms)
+ * or an ISO 8601 string. Returns NaN when it cannot be parsed.
+ * @param {number|string} now
+ * @returns {number}
+ */
+function toEpochMs(now) {
+  if (typeof now === 'number') return now;
+  if (typeof now === 'string') return Date.parse(now);
+  return NaN;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Mint a fresh anonymous ID. A random UUID (v4) — never derived from any machine
+ * or user attribute.
+ *
+ * @returns {string} a v4 UUID
+ */
+export function newAnonId() {
+  return randomUUID();
+}
+
+/**
+ * Decide whether an anonymous ID minted at `createdAtISO` is older than
+ * `maxAgeDays` relative to `now` and must be rotated.
+ *
+ * Fail-safe posture: an unparsable / missing `createdAtISO` (or `now`) returns
+ * `true` (rotate) — an ID whose age cannot be verified is treated as stale
+ * rather than trusted indefinitely. The age comparison is strict: exactly
+ * `maxAgeDays` old is NOT expired (only strictly older rotates).
+ *
+ * @param {string} createdAtISO — ISO 8601 timestamp the current ID was minted at.
+ * @param {number|string} now   — reference time (epoch-ms or ISO 8601 string).
+ * @param {number} [maxAgeDays=ANON_ID_MAX_AGE_DAYS]
+ * @returns {boolean} true ⇒ rotate.
+ */
+export function isExpired(createdAtISO, now, maxAgeDays = ANON_ID_MAX_AGE_DAYS) {
+  const createdMs = typeof createdAtISO === 'string' ? Date.parse(createdAtISO) : NaN;
+  if (Number.isNaN(createdMs)) return true; // unverifiable age ⇒ rotate
+
+  const nowMs = toEpochMs(now);
+  if (Number.isNaN(nowMs)) return true; // unverifiable reference ⇒ rotate
+
+  const ageMs = nowMs - createdMs;
+  const maxMs = maxAgeDays * MS_PER_DAY;
+  return ageMs > maxMs;
+}
+
+/**
+ * Ensure `record` carries a fresh-enough anonymous ID, returning a NEW record
+ * (the input is never mutated). Three outcomes:
+ *
+ *   - created  — the record had no `anon_id`: mint one, stamp `anon_id_created_at`
+ *                to `now`. Returns `{ created: true, rotated: false }`.
+ *   - rotated  — the existing ID is older than `maxAgeDays` (or its
+ *                `anon_id_created_at` is unparsable): mint a new one, re-stamp
+ *                `anon_id_created_at`, discard the old ID.
+ *                Returns `{ created: false, rotated: true }`.
+ *   - unchanged — the ID is present and fresh: return it as-is (in a shallow
+ *                copy). Returns `{ created: false, rotated: false }`.
+ *
+ * @param {object} record — a record that may carry `anon_id` + `anon_id_created_at`.
+ * @param {{now?: string, maxAgeDays?: number}} [opts]
+ * @returns {{record: object, anon_id: string, rotated: boolean, created: boolean}}
+ */
+export function ensureAnonId(record, { now = new Date().toISOString(), maxAgeDays = ANON_ID_MAX_AGE_DAYS } = {}) {
+  const rec = isPlainObject(record) ? record : {};
+  const currentId = rec.anon_id;
+
+  // created — no usable ID present.
+  if (typeof currentId !== 'string' || currentId.trim() === '') {
+    const anon_id = newAnonId();
+    return {
+      record: { ...rec, anon_id, anon_id_created_at: now },
+      anon_id,
+      rotated: false,
+      created: true,
+    };
+  }
+
+  // rotated — present ID is too old (or its created_at is unparsable).
+  if (isExpired(rec.anon_id_created_at, now, maxAgeDays)) {
+    const anon_id = newAnonId();
+    return {
+      record: { ...rec, anon_id, anon_id_created_at: now },
+      anon_id,
+      rotated: true,
+      created: false,
+    };
+  }
+
+  // unchanged — present and fresh. Return a copy so the input stays untouched.
+  return {
+    record: { ...rec },
+    anon_id: currentId,
+    rotated: false,
+    created: false,
+  };
+}

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');