session-orchestrator 5.2.0 → 5.4.0

package/scripts/lib/session-schema/normalizer.mjs

@@ -5,12 +5,12 @@
  * Imports: constants.mjs. No imports from siblings (validator, timestamps,
  * aliases) or parent barrel.
  *
- * Exports: normalizeSession
+ * Exports: normalizeSession, normalizeWaveKeys
  * Module-private: _warnedMissingSchemaVersion (Set, per-process dedupe),
- *   isPlainObject, _canonicalizeExpressPath
+ *   isPlainObject, _canonicalizeExpressPath, _aliasWaves
  */
 
-import { SESSION_KEY_ALIASES } from './constants.mjs';
+import { SESSION_KEY_ALIASES, WAVE_KEY_ALIASES } from './constants.mjs';
 
 // ---------------------------------------------------------------------------
 // Module-level state
@@ -79,12 +79,61 @@ function _canonicalizeExpressPath(next) {
   next.express_path = raw.activated;
 }
 
+/**
+ * Apply WAVE_KEY_ALIASES to every plain-object wave, mirroring the top-level
+ * SESSION_KEY_ALIASES rule: the legacy key is preserved, and an existing
+ * canonical key is never clobbered. Copy-on-write — the caller's wave objects
+ * are never mutated (normalizeSession's `{ ...entry }` is shallow, so `waves`
+ * is still the caller's array).
+ *
+ * @param {any[]} waves
+ * @returns {any[]} the same array reference when no wave needed an alias
+ */
+function _aliasWaves(waves) {
+  let changed = false;
+  const out = waves.map((w) => {
+    if (!isPlainObject(w)) return w;
+    let copy = null;
+    for (const [oldKey, newKey] of Object.entries(WAVE_KEY_ALIASES)) {
+      if (oldKey in w && !(newKey in w)) {
+        copy ??= { ...w };
+        copy[newKey] = w[oldKey];
+      }
+    }
+    if (copy === null) return w;
+    changed = true;
+    return copy;
+  });
+  return changed ? out : waves;
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
 
 /**
- * Normalize a session entry read from disk. Applies SAFE key aliases, collapses
+ * Apply ONLY the per-wave key aliases (WAVE_KEY_ALIASES) to a session entry —
+ * the subset of normalizeSession that is safe on the WRITE path
+ * (scripts/emit-session.mjs, #1390 P1). The rest of normalizeSession is not:
+ * it tags a missing `schema_version` as 0 where validateSession stamps the
+ * current version, and applies top-level aliases the write-path contract
+ * explicitly excludes.
+ *
+ * Never throws. Non-objects and entries without a `waves` array are returned
+ * unchanged; so is an entry none of whose waves needs an alias (same reference).
+ *
+ * @param {any} entry
+ * @returns {any} a new entry with aliased waves, or the input unchanged
+ */
+export function normalizeWaveKeys(entry) {
+  if (!isPlainObject(entry) || !Array.isArray(entry.waves)) return entry;
+  const waves = _aliasWaves(entry.waves);
+  return waves === entry.waves ? entry : { ...entry, waves };
+}
+
+/**
+ * Normalize a session entry read from disk. Applies SAFE key aliases (top-level
+ * SESSION_KEY_ALIASES and per-wave WAVE_KEY_ALIASES), collapses
  * the legacy object form of `express_path` onto its canonical boolean, and tags
  * legacy entries without `schema_version` as 0 (distinct from
  * CURRENT_SESSION_SCHEMA_VERSION=2 which is stamped on new writes; bumped
@@ -112,6 +161,9 @@ export function normalizeSession(entry) {
     }
   }
 
+  // Per-wave aliases (#1390 P1) — same non-clobber rule, one level down.
+  if (Array.isArray(next.waves)) next.waves = _aliasWaves(next.waves);
+
   // express_path — same key, two shapes. Collapse onto the canonical boolean.
   _canonicalizeExpressPath(next);
 

package/scripts/lib/session-schema/validator.mjs

@@ -386,7 +386,9 @@ function _validateOptionalFields(entry) {
   }
   // #1244 — cache buckets, cost estimate and the token-contract marker.
   // Same non-negative-finite-or-null contract as the two totals above;
-  // total_cost_usd is fractional and null means "unknown model", never 0.
+  // total_cost_usd is fractional; null means "cost unknown" — at least one
+  // subagent record could not be priced (#1475: unknown model, no model, or no
+  // tokens; see cost_records_* below) — never 0.
   for (const field of [
     'total_token_input_uncached',
     'total_token_cache_read',
@@ -417,6 +419,31 @@ function _validateOptionalFields(entry) {
     }
   }
 
+  // #1436 — the session-level token total and the rollup's record count, merged
+  // by emit-session from subagents.jsonl. Same contract as subagents_with_tokens:
+  // a non-negative integer, null/absent = not measured. Before this, neither was
+  // checked and `total_tokens: "abc"` validated — the field the autopilot token
+  // budget reads. #1475 adds the rollup's cost-coverage counters under the same
+  // contract, plus the one relation between them: priced never exceeds total.
+  for (const field of ['total_tokens', 'matched_records', 'cost_records_priced', 'cost_records_total']) {
+    const value = entry[field];
+    if (value !== undefined && value !== null) {
+      if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+        throw new ValidationError(`${field} must be a non-negative integer, got: ${value}`);
+      }
+    }
+  }
+  if (
+    Number.isInteger(entry.cost_records_priced) &&
+    Number.isInteger(entry.cost_records_total) &&
+    entry.cost_records_priced > entry.cost_records_total
+  ) {
+    throw new ValidationError(
+      `cost_records_priced must not exceed cost_records_total, got: ` +
+        `${entry.cost_records_priced} > ${entry.cost_records_total}`
+    );
+  }
+
   // Epic #724 C1 — SessionEnd close-through backfill provenance fields.
   // All additive-optional; null/absent passes without further checks so that
   // pre-#724 records (and every normally-closed record) validate cleanly.

package/scripts/lib/session-schema.mjs

@@ -59,7 +59,7 @@
  *                                   SESSION_KEY_ALIASES, VALID_SESSION_TYPES,
  *                                   REQUIRED_FIELDS, AGENT_SUMMARY_FIELDS
  *   session-schema/validator.mjs  — ValidationError, validateSession
- *   session-schema/normalizer.mjs — normalizeSession
+ *   session-schema/normalizer.mjs — normalizeSession, normalizeWaveKeys
  *   session-schema/timestamps.mjs — clampTimestampsMonotonic
  *   session-schema/aliases.mjs    — aliasLegacyEndedAt
  */
@@ -67,7 +67,12 @@
 export { CURRENT_SESSION_SCHEMA_VERSION, SESSION_KEY_ALIASES } from './session-schema/constants.mjs';
 export { ValidationError, validateSession } from './session-schema/validator.mjs';
 export { serializeSessionLineChecked } from './session-schema/serializer.mjs';
-export { normalizeSession } from './session-schema/normalizer.mjs';
+export { normalizeSession, normalizeWaveKeys } from './session-schema/normalizer.mjs';
 export { clampTimestampsMonotonic } from './session-schema/timestamps.mjs';
 export { aliasLegacyEndedAt } from './session-schema/aliases.mjs';
-export { isRealSession, filterRealSessions, tailRealSessions } from './session-schema/filters.mjs';
+export {
+  isRealSession,
+  filterRealSessions,
+  tailRealSessions,
+  isCoordinatorDirectHousekeeping,
+} from './session-schema/filters.mjs';

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

@@ -70,11 +70,22 @@ const local = (rel) => pathToFileURL(path.join(import.meta.dirname, rel)).href;
 const CI_UNKNOWN_HINT_DEFAULT = 'run `glab ci status` on demand';
 
 /**
- * `ci-status` "no data for HEAD" reasons after which the last PUSHED commit is
- * worth asking about: GitLab's `no-pipeline-for-head-sha` and GitHub's
- * `no-check-runs-for-head` (both emitted by `checkCiStatus`).
+ * `ci-status` "no usable reading for HEAD" reasons after which the last PUSHED
+ * commit is worth asking about: GitLab's `no-pipeline-for-head-sha`, GitHub's
+ * `no-check-runs-for-head`, and GitLab's `pipeline-unmatched-ref` (all emitted
+ * by `checkCiStatus`).
+ *
+ * `pipeline-unmatched-ref` (#857) is not a "no data" state — pipelines EXIST for
+ * the sha, they just all sit on a foreign ref, so the reading stays `unknown`.
+ * For this consumer that is the same DARK outcome: the operator learns nothing
+ * about HEAD. Routing it to the pushed-commit re-query at least yields the
+ * pushed sha's own verdict instead of an unactionable line.
  */
-const PUSHED_FOLLOW_UP_REASONS = new Set(['no-pipeline-for-head-sha', 'no-check-runs-for-head']);
+const PUSHED_FOLLOW_UP_REASONS = new Set([
+  'no-pipeline-for-head-sha',
+  'no-check-runs-for-head',
+  'pipeline-unmatched-ref',
+]);
 
 /**
  * Full SHAs for `refs`, in order, from ONE `git rev-parse` — or `null` when
@@ -190,6 +201,22 @@ function pushedVerdictText(v) {
   return `CI ${v.status}${parts.length > 0 ? ` (${parts.join(', ')})` : ''}`;
 }
 
+/**
+ * On-demand command listing every CI run of ONE commit, in the CLI that read
+ * CI — a glab command cannot answer in a GitHub repo (#1339 P1).
+ *
+ * Takes the FULL sha. Measured 2026-09-19, glab 1.117.0: `glab ci status` has
+ * no `--ref` flag ("Unknown flag: --ref.", exit 1), and `glab ci list --sha`
+ * matches exactly, so a short sha lists nothing.
+ *
+ * @param {boolean} gh  The reading came from the gh CLI
+ * @param {string} sha  Full commit sha
+ * @returns {string}
+ */
+function commitRunsCommand(gh, sha) {
+  return gh ? `gh run list --commit ${sha}` : `glab ci list --sha ${sha}`;
+}
+
 /**
  * Hint text for a `status: 'unknown'` ci-status reading.
  *
@@ -212,8 +239,7 @@ function ciUnknownHint(result, ctx) {
   if (pushed?.sameAsHead) return `last pushed: ${short} = HEAD — ${onDemand}`;
   const verdict = pushedVerdictText(pushed?.verdict);
   if (verdict) return `last pushed: ${short} — ${verdict}`;
-  const check = gh ? `gh run list --commit ${sha}` : `glab ci status --ref ${short}`;
-  return `last pushed: ${short} (pipeline not checked; run \`${check}\`)`;
+  return `last pushed: ${short} (pipeline not checked; run \`${commitRunsCommand(gh, sha)}\`)`;
 }
 
 /**
@@ -229,6 +255,53 @@ function hasFailedAllowFailureJobs(r) {
   return Array.isArray(r?.allowFailureJobs) && r.allowFailureJobs.length > 0;
 }
 
+/**
+ * How many same-commit pipelines the ref preference SET ASIDE ended `failed`
+ * (#1390 P5) — the ONE predicate the `ci-status` renderer and its `severityOf`
+ * share, for the reason {@link hasFailedAllowFailureJobs} records (#1333).
+ * Only `failed` counts: a set-aside `canceled`/`skipped` run says nothing about
+ * the commit, and a line that fires on those would teach the operator to skip
+ * the banner (HR-101).
+ *
+ * @param {*} r
+ * @returns {number}
+ */
+function droppedFailedCount(r) {
+  const statuses = r?.details?.droppedStatuses;
+  return Array.isArray(statuses) ? statuses.filter((s) => s === 'failed').length : 0;
+}
+
+/**
+ * Banner line for a `green` reading beside a FAILED pipeline of the same
+ * commit that the ref preference set aside (#1390 P5). The verdict stays the
+ * #857 ref-preference result; this only stops the failure from vanishing
+ * behind a silent green.
+ *
+ * NAMED CEILING (BV-004): one `git rev-parse HEAD` (2s timeout), run only on
+ * this branch — a green reading WITH a set-aside `failed` run, behind the
+ * network opt-in. The reading carries no sha, and the GitLab path read the
+ * local HEAD, so HEAD is the commit it spoke for. REVISIT TRIGGER: once
+ * `checkCiStatus` publishes the sha it read, take it from the reading.
+ *
+ * Only the GitLab path publishes `droppedStatuses` today (`candidateEvidence`
+ * is called from `checkGitlab` alone); the gh form exists so a GitHub producer
+ * can never print a glab command (#1339 P1 class) — see {@link commitRunsCommand}.
+ *
+ * @param {*} r  A green reading with `droppedFailedCount(r) > 0`
+ * @param {{repoRoot?: string}} [ctx]
+ * @returns {string}
+ */
+function droppedFailedLine(r, ctx) {
+  const sha = revParseShas(ctx?.repoRoot, ['HEAD'])?.[0] ?? null;
+  const gh = r.details.cliUsed === 'gh';
+  let check;
+  if (sha) check = commitRunsCommand(gh, sha);
+  else check = gh ? 'gh run list' : 'glab ci list --status=failed';
+  const ref = r.details.matchedRef ?? 'HEAD';
+  const on = sha ? `${ref} for ${sha.slice(0, 8)}` : ref;
+  return `⚠ CI green on ${on}, but ${droppedFailedCount(r)} other pipeline(s) for the same commit FAILED (set-aside statuses: ${r.details.droppedStatuses.join(', ')}) — check \`${check}\``;
+}
+
 // ---------------------------------------------------------------------------
 // Budget
 // ---------------------------------------------------------------------------
@@ -476,9 +549,17 @@ export const PROBES = [
         const job = r.failingJobName ? ` Failing job: ${r.failingJobName}` : '';
         return `🚨 CI RED on HEAD (pipeline #${pid})${green}.${job}`;
       }
-      if (r.status === 'green' && hasFailedAllowFailureJobs(r)) {
-        const names = r.allowFailureJobs.map((j) => j?.name ?? String(j)).join(', ');
-        return `⚠ CI green on HEAD, but ${r.allowFailureJobs.length} allow_failure job(s) FAILED: ${names}. A pipeline reports success regardless of these.`;
+      if (r.status === 'green') {
+        const lines = [];
+        if (hasFailedAllowFailureJobs(r)) {
+          const names = r.allowFailureJobs.map((j) => j?.name ?? String(j)).join(', ');
+          lines.push(`⚠ CI green on HEAD, but ${r.allowFailureJobs.length} allow_failure job(s) FAILED: ${names}. A pipeline reports success regardless of these.`);
+        }
+        // #1390 P5: a failed same-commit pipeline the ref preference set aside.
+        if (droppedFailedCount(r) > 0) lines.push(droppedFailedLine(r, ctx));
+        // Both findings can hold at once; `pushBanner` takes a multi-line
+        // string verbatim, so neither swallows the other.
+        return lines.length > 0 ? lines.join('\n') : null;
       }
       return null;
     },
@@ -493,7 +574,11 @@ export const PROBES = [
       if (!r || typeof r !== 'object') return 'ok';
       if (r.degraded) return 'warn';
       if (r.status === 'red') return 'alert';
-      if (r.status === 'green') return hasFailedAllowFailureJobs(r) ? 'warn' : 'ok';
+      // A set-aside failed run (#1390 P5) is `warn`, never `alert`: the reading
+      // itself is green, and `alert` is what a red pipeline scores.
+      if (r.status === 'green') {
+        return hasFailedAllowFailureJobs(r) || droppedFailedCount(r) > 0 ? 'warn' : 'ok';
+      }
       // #1337: HEAD undetermined but the pushed commit's pipeline is red —
       // the code on origin is broken, so this is an alert, not a warning.
       if (r.pushed?.verdict?.status === 'red') return 'alert';