session-orchestrator 3.23.0 → 4.0.0

package/scripts/lib/telemetry/schema.mjs

@@ -35,7 +35,7 @@
  * none and holds no mutable runtime state.
  */
 
-import { SO_PLATFORM, SO_PLUGIN_ROOT } from '../platform.mjs';
+import { getPlatform, getPluginRoot } from '../platform.mjs';
 import { enumerateSurface } from '../sunset/walker.mjs';
 import { readPluginVersionFromPackageJson } from '../bootstrap-lock-freshness.mjs';
 
@@ -70,6 +70,52 @@ export const USAGE_PING_FIELDS = Object.freeze([
   'commands',
 ]);
 
+/**
+ * ADDITIVE optional fields (schema v1, GitLab #1234). Deliberately a SECOND
+ * list rather than an extension of USAGE_PING_FIELDS above, for two reasons:
+ *
+ *  1. USAGE_PING_FIELDS is the REQUIRED v1 contract — `tests/telemetry/parity.mjs`
+ *     asserts, field by field, that the server independently REQUIRES every
+ *     member. An optional field is by definition not required, so putting it in
+ *     that list would force the parity guard to be weakened for all 15 fields to
+ *     accommodate one.
+ *  2. The frozen-list tripwire (`projectUsagePing` drops anything unlisted)
+ *     stays intact: the projection whitelist is the UNION of both lists, so a
+ *     leaky field still has to be added to a reviewed list before it can reach
+ *     the wire.
+ *
+ * Server tolerance: `server/ingest/validate.mjs` accepts unknown top-level
+ * fields and preserves them verbatim in `raw_json` (see its module docblock), so
+ * every member here round-trips through a server that predates it.
+ */
+export const USAGE_PING_OPTIONAL_FIELDS = Object.freeze([
+  'fleet_self_declared',
+  'session_record',
+  'session_profile',
+]);
+
+/**
+ * The full projection whitelist: required v1 fields + additive optional fields.
+ * `projectUsagePing` is driven from THIS, so neither list alone can leak a field.
+ */
+const USAGE_PING_PROJECTED_FIELDS = Object.freeze([...USAGE_PING_FIELDS, ...USAGE_PING_OPTIONAL_FIELDS]);
+
+/**
+ * `session_record` provenance tokens — WHICH source the session facts
+ * (`session_type`, `duration_bucket`) in this ping came from.
+ *
+ *  - `ledger`  — `.orchestrator/metrics/sessions.jsonl` had a matching record.
+ *  - `derived` — no ledger record; the facts were reconstructed from
+ *                `events.jsonl` (`orchestrator.session.started` + last event).
+ *  - `absent`  — neither source produced a session type. `session_type` is then
+ *                `'unknown'` and `duration_bucket` is NOT a measurement.
+ *
+ * Measured 2026-09-06 (d8 audit): this repo has NO sessions.jsonl, so 100 % of
+ * its pings took the `absent` path and were indistinguishable on the wire from
+ * a genuinely-measured `other` / `<15m` session — 32 such pings on the server.
+ */
+export const SESSION_RECORD_SOURCES = Object.freeze(['ledger', 'derived', 'absent']);
+
 /** Exact duration-bucket tokens (ASCII, stable wire values). */
 export const DURATION_BUCKETS = Object.freeze(['<15m', '15-60m', '1-3h', '>3h']);
 
@@ -83,6 +129,43 @@ 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';
+/**
+ * The type was never measured — distinct from `'other'`, which means "measured,
+ * but not one of the three known modes". Conflating the two is the defect this
+ * token fixes: before it existed, a ping built with NO session record silently
+ * reported `'other'`, so "we could not tell" and "we looked and it was unusual"
+ * were the same wire value.
+ *
+ * NOT an enum widening server-side: `session_type` is validated as a bounded
+ * STRING (`server/ingest/validate.mjs` `requireString` + `MAX_SESSION_TYPE`),
+ * never against a closed set, so `'unknown'` is accepted by today's server.
+ */
+const SESSION_TYPE_UNKNOWN = 'unknown';
+
+/**
+ * CLOSED whitelist of PUBLIC session-profile names that may reach the wire.
+ *
+ * WHY A WHITELIST AND NOT A REGEX: `session_profile` is copied from the STATE.md
+ * frontmatter key `session-profile`, which is written per repo by whoever runs
+ * `/session <alias>` — i.e. it is the only field on the usage-ping whose VALUE is
+ * repo-authored free text. Two independent Wave-1 reviewers reproduced the leak
+ * end-to-end (2026-09-06): `session-profile: client-acme-private-repo` travelled
+ * verbatim through `buildUsagePing` → `projectUsagePing` → the ingest server's
+ * `raw_json` column. A shape regex does NOT close it — that example string is
+ * already lowercase-and-hyphens and passes any such pattern. Only an
+ * enumeration of names that are public BY CONSTRUCTION does.
+ *
+ * Today exactly one profile exists: `ultradeep`, the 7-wave variant of a `deep`
+ * session (writer: `commands/session.md` § "Argument alias: ultradeep" → STATE.md
+ * frontmatter `session-profile`; wave shape: `skills/session-plan/SKILL.md`).
+ * Adding a profile there means adding it HERE and in the server's mirror
+ * (`server/ingest/validate.mjs` `SESSION_PROFILES`) — a deliberate two-line,
+ * reviewed edit, the same contract `ACCEPTED_VERSIONS` already uses server-side.
+ *
+ * NOT a member of VALID_SESSION_TYPES: the profile is a SECOND axis. An
+ * ultradeep session is `session_type: "deep"` PLUS `session_profile: "ultradeep"`.
+ */
+export const VALID_SESSION_PROFILES = Object.freeze(['ultradeep']);
 
 /**
  * Closed sets for os/arch client-side normalization. A value outside the set —
@@ -121,7 +204,8 @@ function isNonEmptyString(v) {
 // ---------------------------------------------------------------------------
 
 /**
- * Project an arbitrary object onto the usage-ping whitelist (USAGE_PING_FIELDS).
+ * Project an arbitrary object onto the usage-ping whitelist (USAGE_PING_FIELDS
+ * PLUS USAGE_PING_OPTIONAL_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.
@@ -132,7 +216,7 @@ function isNonEmptyString(v) {
 export function projectUsagePing(input) {
   if (!isPlainObject(input)) return {};
   const out = {};
-  for (const key of USAGE_PING_FIELDS) {
+  for (const key of USAGE_PING_PROJECTED_FIELDS) {
     if (key in input) {
       const v = input[key];
       out[key] = Array.isArray(v) ? [...v] : v;
@@ -163,7 +247,7 @@ export function projectUsagePing(input) {
 export function loadRoster({ pluginRoot } = {}) {
   const root = (typeof pluginRoot === 'string' && pluginRoot.trim() !== '')
     ? pluginRoot
-    : SO_PLUGIN_ROOT;
+    : getPluginRoot();
 
   if (!isNonEmptyString(root)) {
     process.stderr.write(
@@ -220,6 +304,54 @@ export function filterRosterNames(names, rosterSet) {
   return deduped.slice(0, MAX_NAMES);
 }
 
+/**
+ * Classify a single raw invocation name into the skills or commands bucket.
+ *
+ * The Skill tool surfaces slash-commands that have NO backing `skills/` directory
+ * under the same plugin-prefixed name form as real skills (e.g.
+ * `session-orchestrator:session` for `commands/session.md`). `roster.skills` holds
+ * PREFIXED names, `roster.commands` holds BARE ones — so a prefixed command name
+ * matches neither set and used to be bucketed to 'other' (GitLab #1189: commands
+ * was `[]` in 345/345 usage pings).
+ *
+ * Decision order (skill roster wins on a spelling collision such as
+ * `memory-cleanup`, which is both a skill dir and a command file):
+ *   1. name in rosterSkills                     → {kind:'skill',   name}  (verbatim)
+ *   2. name is PREFIXED and its bare form is in rosterCommands
+ *                                               → {kind:'command', bare}
+ *   3. otherwise                                → {kind:'skill',   name}  (verbatim)
+ *
+ * Case 2 REQUIRES the plugin prefix (session-reviewer W2 finding, 2026-09-02).
+ * Without that requirement, a BARE third-party or personal skill name that
+ * happens to collide with one of our shipped command names (`test`, `close`,
+ * `go`, `release`, `portfolio` are all plausible foreign skill names) would be
+ * recorded as OUR command — a data-integrity defect, and the same rule made
+ * `memory-cleanup` reach BOTH buckets in one ping (bare → commands, prefixed →
+ * skills), double-counting a single surface. Requiring the prefix removes both:
+ * a bare arrival can only ever be a skill-path name, so an unknown one becomes
+ * 'other'. Cost: the one genuine bare `memory-cleanup` record is recorded as
+ * 'other' rather than as the command.
+ *
+ * Case 3 keeps foreign/third-party names on the SKILLS path only, where
+ * filterRosterNames projects them to the opaque token 'other' — an unclassified
+ * name is never duplicated into `commands`, preserving the privacy invariant.
+ *
+ * @param {unknown} name raw invocation name
+ * @param {Set<string>} rosterSkills prefixed shipped-skill names
+ * @param {Set<string>} rosterCommands bare shipped-command names
+ * @returns {{kind: 'skill'|'command', name: unknown}}
+ */
+export function classifyInvocationName(name, rosterSkills, rosterCommands) {
+  const skills = rosterSkills instanceof Set ? rosterSkills : new Set();
+  const commands = rosterCommands instanceof Set ? rosterCommands : new Set();
+  if (typeof name !== 'string') return { kind: 'skill', name };
+  if (skills.has(name)) return { kind: 'skill', name };
+  if (!name.startsWith(SKILL_PREFIX)) return { kind: 'skill', name };
+  const bare = name.slice(SKILL_PREFIX.length);
+  if (commands.has(bare)) return { kind: 'command', name: bare };
+  return { kind: 'skill', name };
+}
+
 // ---------------------------------------------------------------------------
 // Duration bucketing
 // ---------------------------------------------------------------------------
@@ -261,8 +393,9 @@ export function deriveDurationBucket(startedAtISO, completedAtISO) {
  * 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';
+  const root = getPluginRoot();
+  if (!isNonEmptyString(root)) return 'unknown';
+  return readPluginVersionFromPackageJson(root) ?? 'unknown';
 }
 
 /** Normalize the detected platform to the closed enum (+ 'other' fallback). */
@@ -272,7 +405,36 @@ function normalizePlatform(platform) {
 
 /** Normalize the session type to the closed enum (+ 'other' fallback). */
 function normalizeSessionType(sessionType) {
-  return VALID_SESSION_TYPES.includes(sessionType) ? sessionType : SESSION_TYPE_OTHER;
+  if (VALID_SESSION_TYPES.includes(sessionType)) return sessionType;
+  // ABSENT ≠ UNRECOGNISED. A missing/blank value means nothing was measured
+  // (`unknown`); a present-but-unlisted value means something WAS measured and
+  // is not one of the three modes (`other`). The old single-branch version
+  // returned `other` for both, which is how 394 pings from a host with no
+  // sessions.jsonl arrived looking like measured `other` sessions (d8, 2026-09-06).
+  return isNonEmptyString(sessionType) ? SESSION_TYPE_OTHER : SESSION_TYPE_UNKNOWN;
+}
+
+/**
+ * Normalize a session PROFILE against the closed VALID_SESSION_PROFILES
+ * whitelist. Anything else — absent, blank, or an unlisted repo-authored value —
+ * returns `null`, and the caller OMITS the field.
+ *
+ * DELIBERATELY NOT MIRRORING normalizeSessionType's two-token report. That helper
+ * can distinguish ABSENT (`'unknown'`) from UNRECOGNISED (`'other'`) because both
+ * of its answers are public constants. Here the unrecognised VALUE is precisely
+ * what must not travel, and there is no third token that carries the distinction
+ * without carrying the string: an `'other'` profile would say "this host ran a
+ * profile we do not ship" — a fact of no product use, bought with a new wire
+ * value. So both cases collapse to omission, and the wire cannot tell them apart
+ * BY DESIGN. The local `session-profile` key is untouched either way.
+ *
+ * @param {unknown} profile
+ * @returns {string|null} a whitelisted profile name, or null (⇒ field omitted).
+ */
+export function normalizeSessionProfile(profile) {
+  if (!isNonEmptyString(profile)) return null;
+  const trimmed = profile.trim();
+  return VALID_SESSION_PROFILES.includes(trimmed) ? trimmed : null;
 }
 
 /**
@@ -331,12 +493,12 @@ function distinctField(records, field) {
  * 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).
+ * The distinct `.skill` and `.command` values of `skillInvocations` go through a
+ * single classifyInvocationName pass that routes each name to skills or commands
+ * (the `.command` field carries nothing today; it is honored so a future direct
+ * command-telemetry stream feeds in without a signature change). Both buckets are
+ * then roster-filtered — off-roster names become "other" — deduped, sorted, and
+ * capped. No frequencies are recorded (v1 decision).
  *
  * @param {{
  *   sessionRecord: object,
@@ -355,6 +517,9 @@ export function buildUsagePing({
   env = process.env,
   now = new Date().toISOString(),
   roster,
+  consentState,
+  sessionRecordSource,
+  sessionProfile,
 } = {}) {
   const session = isPlainObject(sessionRecord) ? sessionRecord : {};
   const invocations = Array.isArray(skillInvocations) ? skillInvocations : [];
@@ -362,22 +527,95 @@ export function buildUsagePing({
   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');
+  // ONE classification pass over the union of both producer fields: today only
+  // `.skill` is written by hooks/skill-invocation-telemetry.mjs, `.command` is
+  // kept for the forward-compat producer documented above.
+  //
+  // `.command` records carry the BARE name, and classifyInvocationName requires
+  // the plugin prefix before it will route anything to the commands bucket (see
+  // its doc comment). So a `.command` name is normalized to the prefixed form
+  // first — the field itself is the "this is one of ours" signal that a bare
+  // `.skill` arrival lacks. Without this the forward-compat producer would be
+  // wired but dead: every record it writes would silently become 'other'.
+  const skillNames = [];
+  const commandNames = [];
+  const rawNames = [
+    ...distinctField(invocations, 'skill'),
+    ...distinctField(invocations, 'command').map((n) => (n.startsWith(SKILL_PREFIX) ? n : `${SKILL_PREFIX}${n}`)),
+  ];
+  for (const raw of rawNames) {
+    const { kind, name } = classifyInvocationName(raw, rosterSkills, rosterCommands);
+    (kind === 'command' ? commandNames : skillNames).push(name);
+  }
+
+  // ── fleet: a statement about the OPERATOR, derived from the RESOLVED consent
+  // state, not from a raw owner.yaml read ────────────────────────────────────
+  // The old expression was `ownerConfig?.telemetry?.enabled === true` — a
+  // statement about a FILE. Measured 2026-09-06 (d8): the operator's second Mac
+  // has consent granted but no `telemetry:` block in owner.yaml, so 394 of 490
+  // server records (80,4 %) counted the operator as an external user and every
+  // week's `fleet_vs_external` was wrong.
+  //
+  // `resolveConsent()` already answers this question correctly: it returns
+  // `enabled-fleet` for the owner.yaml opt-in AND `enabled-env` for
+  // `SO_TELEMETRY=1`, both of which are operator-side postures. Callers that
+  // pass `consentState` get that answer; the ownerConfig fallback below keeps
+  // the two-argument callers (and the CLI preview) behaviourally identical.
+  //
+  // CEILING, named because the client cannot close it: this is still
+  // SELF-DECLARED — a sandbox or a host whose owner.yaml is unreachable declares
+  // `false` however honest it is. The authoritative classification is
+  // server-side (`SO_INGEST_FLEET_ANON_IDS`, server/ingest/config.mjs).
+  // `session_profile` (STATE.md frontmatter `session-profile`) is bounded by the
+  // CLOSED VALID_SESSION_PROFILES whitelist — it was the one free-text value on
+  // the wire until 2026-09-06, and a repo-authored one at that (see the
+  // whitelist's own docblock for the reproduced leak). It is still deliberately
+  // NOT routed through normalizeSessionType: that helper degrades anything
+  // outside ['housekeeping','feature','deep'] to 'other', which is exactly the
+  // silent loss the profile exists to prevent. The contract is
+  // `session_type: "deep"` PLUS `session_profile: "ultradeep"` — never
+  // `session_type: "ultradeep"`, and never a profile flattened to 'other'.
+  //
+  // ABSENT IS NOT EMPTY: with no profile — and with an UNLISTED one — the KEY IS
+  // OMITTED, matching every other optional ping field. `projectUsagePing` copies
+  // only keys that are `in` the input, so an omitted key never reaches the wire
+  // as `null`, and an unlisted profile never reaches it at all.
+  //
+  // SOURCE PRECEDENCE is resolved BEFORE normalization (explicit argument beats
+  // the session record), so an unlisted explicit profile is dropped rather than
+  // silently replaced by the record's value.
+  const rawProfile =
+    isNonEmptyString(sessionProfile) ? sessionProfile
+      : isNonEmptyString(session.session_profile) ? session.session_profile
+        : null;
+  const profile = normalizeSessionProfile(rawProfile);
+
+  const fleetSelfDeclared =
+    consentState === undefined || consentState === null
+      ? ownerConfig?.telemetry?.enabled === true
+      : consentState === 'enabled-fleet' || consentState === 'enabled-env';
 
   return {
     record_kind: 'usage-ping',
     schema_version: USAGE_PING_SCHEMA_VERSION,
     sent_at: now,
     plugin_version: resolvePluginVersion(),
-    platform: normalizePlatform(SO_PLATFORM),
+    platform: normalizePlatform(getPlatform()),
     os: normalizeOs(process.platform),
     arch: normalizeArch(process.arch),
     node_major: parseInt(process.versions.node, 10),
     ci: deriveCi(env),
-    fleet: ownerConfig?.telemetry?.enabled === true,
+    fleet: fleetSelfDeclared,
+    // DEPRECATED alias of `fleet_self_declared`, kept for one schema generation
+    // (removal: 2027-03-06 — see docs/telemetry.md § Schema evolution) so the
+    // server's existing `fleet` column stays comparable across the rename.
+    fleet_self_declared: fleetSelfDeclared,
     session_type: normalizeSessionType(session.session_type),
+    ...(profile !== null ? { session_profile: profile } : {}),
     duration_bucket: deriveDurationBucket(session.started_at, session.completed_at),
+    session_record: SESSION_RECORD_SOURCES.includes(sessionRecordSource)
+      ? sessionRecordSource
+      : 'absent',
     skills: filterRosterNames(skillNames, rosterSkills),
     commands: filterRosterNames(commandNames, rosterCommands),
   };