session-orchestrator 3.24.0 → 4.0.1

package/scripts/lib/session-start-probes.mjs

@@ -168,6 +168,18 @@ export const PROBES = [
     // vault-staleness-banner.mjs's header for the "one vocabulary, not two"
     // rationale.
   },
+  {
+    id: 'telemetry-flush-health',
+    spec: local('./telemetry-flush-health-banner.mjs'),
+    fn: 'checkTelemetryFlushHealth',
+    network: false,
+    args: ({ repoRoot }) => ({ repoRoot }),
+    // No custom render/severityOf: the probe returns `{severity:'warn',
+    // message}` — exactly the shape the module-level defaults below read. It
+    // reports the LAST `orchestrator.telemetry.flush` record when that record
+    // is a `sandbox:*` refusal (#1255); the refusal reached the ledger and
+    // nothing else before this entry existed.
+  },
   {
     id: 'ci-status',
     spec: local('./ci-status-banner.mjs'),
@@ -176,8 +188,16 @@ export const PROBES = [
     args: ({ repoRoot }) => ({ repoRoot }),
     // Bespoke shape: `{status, ok, details, …}` with no `message` field. The
     // banner text is prescribed by SKILL.md § Phase 4.
+    //
+    // The degraded branch is NOT decoration (#1031): this entry overrides BOTH
+    // `render` and `severityOf`, so the module-level defaults that already
+    // handle a `{severity:'warn', message, degraded}` result never run for this
+    // probe. Without these two lines a degraded ci-status result scored `'ok'`
+    // and rendered nothing — "could not read" displayed exactly like "green",
+    // which is the confusion the probe's own migration removed one layer down.
     render: (r) => {
       if (!r || typeof r !== 'object') return null;
+      if (r.degraded) return typeof r.message === 'string' && r.message ? r.message : null;
       if (r.status === 'red') {
         const pid = r.details?.currentPipelineId ?? '?';
         const green = r.lastGreen
@@ -193,7 +213,16 @@ export const PROBES = [
       return null;
     },
     // `status: 'red'` is an alert even though the probe publishes no severity.
-    severityOf: (r) => (r?.status === 'red' ? 'alert' : r?.status === 'green' && r?.allowFailureJobs ? 'warn' : 'ok'),
+    // A degraded result is a finding, never clean — same rule as the generic
+    // path in `severityOf()` below.
+    severityOf: (r) =>
+      r?.degraded
+        ? 'warn'
+        : r?.status === 'red'
+          ? 'alert'
+          : r?.status === 'green' && r?.allowFailureJobs
+            ? 'warn'
+            : 'ok',
   },
   {
     id: 'qg-command-drift',

package/scripts/lib/sessions-staleness-banner.mjs

@@ -132,6 +132,7 @@ import path from 'node:path';
 
 import { readLock, DEFAULT_TTL_HOURS } from './session-lock.mjs';
 import { isRealSession } from './session-schema/filters.mjs';
+import { readCanonicalSessions } from './sessions-canonical.mjs';
 
 /** Repo-relative path to the session ledger (one record per closed session). */
 const SESSIONS_PATH = '.orchestrator/metrics/sessions.jsonl';
@@ -240,20 +241,21 @@ function keepNewer(current, candidate) {
  * result so the caller can say the anchor is a stub start, not a measured close;
  * the key is omitted (`undefined`) on the genuine path.
  *
- * @param {string[]} lines
+ * `records` is the CANONICAL (#1209b) record set — `readCanonicalSessions()`
+ * has already collapsed a duplicated `session_id` to its newest occurrence, so
+ * a since-corrected raw LINE for the same identity (e.g. one later marked
+ * `status: 'abandoned'`, or a stale `completed_at` a later record for the same
+ * id superseded) can no longer independently skew this max-reduce the way a
+ * raw-line scan over every append could.
+ *
+ * @param {object[]} records
  * @returns {{iso: string, ms: number, stubFallback?: true}|null}
  */
-function lastLedgerEntry(lines) {
+function lastLedgerEntry(records) {
   let newestGenuine = null; // newest genuine completed_at (or started_at floor)
   let newestStub = null; // newest stub started_at
 
-  for (const line of lines) {
-    let record;
-    try {
-      record = JSON.parse(line);
-    } catch {
-      continue;
-    }
+  for (const record of records) {
     if (!record || typeof record !== 'object') continue;
 
     if (isBackfillStub(record)) {
@@ -370,10 +372,15 @@ export function checkSessionsStaleness({ repoRoot, now = Date.now() } = {}) {
 
     const nowMs = typeof now === 'number' && Number.isFinite(now) ? now : Date.now();
 
-    const sessionLines = readJsonlLines(path.join(repoRoot, SESSIONS_PATH));
+    const sessionsPath = path.join(repoRoot, SESSIONS_PATH);
+    const sessionLines = readJsonlLines(sessionsPath);
     if (sessionLines === null || sessionLines.length === 0) return null;
 
-    const ledger = lastLedgerEntry(sessionLines);
+    // CANONICAL (#1209b) record set — readJsonlLines() above only decides
+    // missing-vs-empty (readCanonicalSessions() cannot tell those apart, see
+    // its own doc); the anchor scan itself now runs over the collapsed set.
+    const sessionRecords = readCanonicalSessions({ filePath: sessionsPath });
+    const ledger = lastLedgerEntry(sessionRecords);
     if (ledger === null) return null;
 
     const eventLines = readJsonlLines(path.join(repoRoot, EVENTS_PATH));

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

@@ -35,6 +35,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { isRealSession } from '../session-schema/filters.mjs';
+import { readCanonicalSessions } from '../sessions-canonical.mjs';
 
 const DEFAULT_INVOCATIONS_PATH = path.resolve(
   fileURLToPath(import.meta.url),
@@ -81,6 +82,15 @@ async function readJsonl(filePath) {
  * it to route the join to the `abandoned` outcome bucket instead of counting
  * a zero-signal join as `sessionsJoined`.
  *
+ * Callers pass `sessionRecords` from `readCanonicalSessions()` (#1209b) — one
+ * record per physical session (newest-wins per `session_id`, systemic
+ * double-stub twin dropped, superseded stubs removed). Without that upstream
+ * collapse, the two-writer double-stub class (a SEPARATE synthetic
+ * `session_id` for the SAME physical session) would enter this map as a
+ * second, independent `abandoned` entry — this function's own `map.set()`
+ * overwrite only dedupes an EXACT `session_id` repeat, never two different
+ * ids for one session.
+ *
  * @param {object[]} sessionRecords
  * @returns {Map<string, { agentSummary: { complete: number, partial: number, failed: number, spiral: number }, real: boolean }>}
  */
@@ -121,10 +131,13 @@ export async function joinSkillOutcomes({
   invocationsPath = DEFAULT_INVOCATIONS_PATH,
   sessionsPath = DEFAULT_SESSIONS_PATH,
 } = {}) {
-  const [invocations, sessionRecords] = await Promise.all([
-    readJsonl(invocationsPath),
-    readJsonl(sessionsPath),
-  ]);
+  // Invocations stay on the raw async reader (no identity-collapse concept
+  // applies to a selection-event stream). Sessions move to the CANONICAL
+  // (#1209b) reader — synchronous by contract (see sessions-canonical.mjs) —
+  // so a session_id counted twice under the two-writer double-stub bug no
+  // longer inflates `sessionsAbandoned` (see buildSessionMap doc above).
+  const invocations = await readJsonl(invocationsPath);
+  const sessionRecords = readCanonicalSessions({ filePath: sessionsPath });
 
   const sessionMap = buildSessionMap(sessionRecords);
 

package/scripts/lib/state-md.mjs

@@ -9,8 +9,15 @@
  * @see scripts/lib/state-md/body-sections.mjs       readCurrentTask, appendDeviation, markExpressPathComplete, appendWhatNotToRetry, readWhatNotToRetry, readOpenQuestions, appendOpenQuestion, markOpenQuestionAnswered
  * @see scripts/lib/state-md/mission-status.mjs      parseMissionStatus, parseMissionStatusStrict, MISSION_STATUS_VALUES, writeMissionStatus, setMissionStatus, setMissionStatusDetailed, readMissionStatus, recoverFrontmatterMissionStatusDetailed, writeMissionStatusOnDisk, setMissionStatusOnDisk
  * @see scripts/lib/state-md/recommendations.mjs     parseRecommendations
+ *
+ * Plus ONE small non-re-export surface: the `session-profile` frontmatter
+ * accessors at the bottom of this file (see their docblock for why they are
+ * composed here rather than added as a fourth mutator module).
  */
 
+import { parseStateMd as _parseStateMd } from './state-md/yaml-parser.mjs';
+import { updateFrontmatterFields as _updateFrontmatterFields } from './state-md/frontmatter-mutators.mjs';
+
 export { parseStateMd, serializeStateMd } from './state-md/yaml-parser.mjs';
 
 export {
@@ -61,3 +68,74 @@ export {
 } from './state-md/mission-status.mjs';
 
 export { parseRecommendations } from './state-md/recommendations.mjs';
+
+// ---------------------------------------------------------------------------
+// Session profile (PRD docs/prd/2026-09-06-ultradeep-session-profile.md)
+// ---------------------------------------------------------------------------
+//
+// `session-profile` is an OPTIONAL STATE.md frontmatter scalar that names a
+// wave-shape variant on top of an unchanged `session-type`. Today exactly one
+// value is defined — `ultradeep` (7 waves, coordinator-direct Synthesis-Gate at
+// wave 2) — resolved from the `/session ultradeep` argument alias in
+// `commands/session.md`.
+//
+// The vocabulary is deliberately NOT a closed set here. A profile changes only
+// how the coordinator shapes waves; unlike `session_type` (a closed set in
+// scripts/lib/session-schema/constants.mjs, telemetry and the close-backfill),
+// no consumer branches on the value, so an unknown one degrades to "a profile
+// this reader does not recognise" rather than to a silent mislabel. Revisit
+// trigger: the first consumer that BRANCHES on a specific profile value — at
+// that point the set becomes load-bearing and belongs in a shared constant.
+//
+// Composed from the two existing helpers above rather than reaching into the
+// frontmatter with a second parser: `parseStateMd` for the read,
+// `updateFrontmatterFields` for the write (whose null/undefined semantics
+// already mean DELETE, which is exactly "no profile").
+
+/** Frontmatter key holding the optional session profile. */
+export const SESSION_PROFILE_FIELD = 'session-profile';
+
+/**
+ * Read the session profile from STATE.md contents.
+ *
+ * ABSENCE IS NEVER COERCED. Returns `null` — not `''`, not `'none'` — when the
+ * document has no frontmatter, no `session-profile` key, or a value that is not
+ * a non-empty string. Callers test `=== null` for "no profile"; they must not
+ * test truthiness of a string they assumed was always present.
+ *
+ * @param {string} contents  Full STATE.md text.
+ * @returns {string|null} The profile name, or null when no profile is set.
+ */
+export function readSessionProfile(contents) {
+  if (typeof contents !== 'string') return null;
+  const parsed = _parseStateMd(contents);
+  if (parsed === null) return null;
+  const value = parsed.frontmatter[SESSION_PROFILE_FIELD];
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+/**
+ * Set or clear the session profile in STATE.md contents.
+ *
+ * Passing `null` DELETES the key, restoring the absent (= no profile) state —
+ * it never writes a placeholder value. Every other frontmatter key, including
+ * unknown extensions, is preserved verbatim by `updateFrontmatterFields`.
+ * No-ops (returns the input unchanged) when `contents` has no frontmatter.
+ *
+ * @param {string} contents  Full STATE.md text.
+ * @param {string|null} profile  Profile name, or null to clear.
+ * @returns {string} The new STATE.md text.
+ * @throws {TypeError} when `profile` is neither a non-empty string nor null.
+ */
+export function setSessionProfile(contents, profile) {
+  if (profile !== null && (typeof profile !== 'string' || profile.trim().length === 0)) {
+    throw new TypeError(
+      `setSessionProfile: profile must be a non-empty string or null, got: ${JSON.stringify(profile)}`
+    );
+  }
+  return _updateFrontmatterFields(contents, {
+    [SESSION_PROFILE_FIELD]: profile === null ? null : profile.trim(),
+  });
+}

package/scripts/lib/sunset/walker.mjs

@@ -471,6 +471,12 @@ function collectFiles(dir) {
 function isBoilerplateSite(relPath, kind, name) {
   if (kind === 'agent') {
     if (relPath === `agents/${name}.md`) return true;
+    // Kept for repoRoots where an authoring-spec file still lives at this path
+    // (pre-4.0.0 checkouts, template/consumer repos) — see
+    // tests/lib/sunset-walker.test.mjs "boilerplate exclusion (agents)". The
+    // session-orchestrator repo itself moved the spec to docs/agent-authoring.md,
+    // which is outside SCAN_DIRS and can never appear as a relPath here, so
+    // there is no live path to repoint this exclusion to.
     if (relPath === 'agents/AGENTS.md') return true;
     if (relPath === `agents/schemas/${name}.schema.json`) return true;
     // Routing-table / validator boilerplate.

package/scripts/lib/telemetry/schema.mjs

@@ -35,9 +35,10 @@
  * 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';
+import { VALID_SESSION_PROFILES } from '../session-schema/constants.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -70,6 +71,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']);
 
@@ -78,11 +125,68 @@ const ROSTER_OTHER = 'other';
 const MAX_NAME_LENGTH = 64;
 const MAX_NAMES = 100;
 
+/**
+ * The two list bounds that are genuinely SHARED with the ingest server
+ * (`server/ingest/validate.mjs` `INGEST_LIST_BOUNDS` — MAX_LIST_ITEMS /
+ * MAX_LIST_ITEM_LEN). Exported so `tests/telemetry/parity.test.mjs` can compare
+ * the two trees instead of trusting two hand-typed numbers: a client that caps
+ * higher than the server emits pings the server 400s.
+ *
+ * The server's other five bounds (MAX_ANON_ID, MAX_SENT_AT, MAX_PLUGIN_VERSION,
+ * MAX_SESSION_TYPE, MAX_SESSION_PROFILE) are SERVER-ONLY BY DESIGN — they bound
+ * inputs from any client, including foreign or tampered ones, and have no client
+ * counterpart to keep in lockstep. Do not mirror them here.
+ */
+export const SHARED_LIST_BOUNDS = Object.freeze({
+  maxItems: MAX_NAMES,
+  maxItemLength: MAX_NAME_LENGTH,
+});
+
 /** Enum fallbacks. */
 const VALID_PLATFORMS = Object.freeze(['claude', 'codex', 'cursor', 'pi']);
+// DELIBERATE ASYMMETRY, not a drift: this is the TELEMETRY type set and omits
+// `'unknown'`, which session-schema/constants.mjs VALID_SESSION_TYPES carries.
+// There `unknown` is a storable ledger value; here it is a NORMALIZER FALLBACK
+// (SESSION_TYPE_UNKNOWN below) that must never be reachable from the input set,
+// or "we could not tell" would be indistinguishable from a measured type. Not
+// unified with constants.mjs for exactly that reason.
 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.
+ *
+ * RE-EXPORT, not a definition (GitLab #1252): the SSOT is
+ * `scripts/lib/session-schema/constants.mjs` `VALID_SESSION_PROFILES`, whose
+ * docblock carries the reproduced leak and the whitelist-over-regex rationale.
+ *
+ * Kept as a pure COMPATIBILITY SHIM, and measured as one: since 2026-09-07 no
+ * module in this repo imports the name from here (`rg -n VALID_SESSION_PROFILES
+ * scripts server hooks skills tests` — the two telemetry tests that used to now
+ * address constants.mjs). It stays because removing an export is a MAJOR change
+ * and this is a patch line; a deep importer outside the repo may still hold it.
+ * `tests/telemetry/schema.test.mjs` pins it with an IDENTITY assertion
+ * (`toBe`, not `toEqual`) so the shim can never quietly become a second
+ * definition of the whitelist.
+ *
+ * Adding a profile is a reviewed edit in constants.mjs AND in the server's
+ * mirror (`server/ingest/validate.mjs` `SESSION_PROFILES`) — the same two-tree
+ * contract `ACCEPTED_VERSIONS` already uses server-side.
+ */
+export { VALID_SESSION_PROFILES };
 
 /**
  * Closed sets for os/arch client-side normalization. A value outside the set —
@@ -121,7 +225,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 +237,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 +268,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(
@@ -309,8 +414,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). */
@@ -320,7 +426,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;
 }
 
 /**
@@ -403,6 +538,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 : [];
@@ -431,19 +569,74 @@ export function buildUsagePing({
     (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),
   };