session-orchestrator 5.2.0 → 5.3.0

package/scripts/lib/session-close-backfill.mjs

@@ -531,15 +531,23 @@ function synthesizeRecord({ recordId, synthetic, gathered, nowMs, status = 'aban
 const BACKFILL_STUB_STATUSES = new Set(['abandoned']);
 
 /**
- * True when a sessions.jsonl record is a backfilled STUB — reconstructed
- * provenance (`_backfill_source`) AND a stub status. Both are required: a
- * hand-written `abandoned` record with no backfill provenance is somebody's
- * deliberate statement and is never superseded on our own initiative.
+ * True when a sessions.jsonl record is a backfilled stub this module may
+ * SUPERSEDE — reconstructed provenance (`_backfill_source`) AND a stub status.
+ * Both are required: a hand-written `abandoned` record with no backfill
+ * provenance is somebody's deliberate statement and is never superseded on our
+ * own initiative.
+ *
+ * Named for the decision it makes, not for the record class, because
+ * `sessions-staleness-banner.mjs` asks a DIFFERENT question about the same
+ * records — `isNonAnchorStub()` there accepts EITHER marker, since a record
+ * only needs to be doubtful to be disqualified as a time anchor, where this
+ * one must be proven reconstructed before it may be overwritten. Both are
+ * module-local on purpose; they must not be shared.
  *
  * @param {unknown} record
  * @returns {boolean}
  */
-function isBackfillStub(record) {
+function isSupersedableStub(record) {
   if (!record || typeof record !== 'object' || Array.isArray(record)) return false;
   if (typeof record._backfill_source !== 'string') return false;
   return BACKFILL_STUB_STATUSES.has(record.status);
@@ -636,7 +644,7 @@ function classifyExisting(readFileSync, sessionsPath, { recordId, sessionId, sem
   const sessionRecords = readJsonlSafe(readFileSync, sessionsPath);
   const newest = findRecordedSession(sessionRecords, { sessionId, semanticSessionId, startedAt });
   if (!newest) return { kind: 'absent' };
-  if (isBackfillStub(newest)) {
+  if (isSupersedableStub(newest)) {
     return { kind: 'stub', matchedId: newest.session_id, stubId: newest.session_id };
   }
   return { kind: 'canonical', matchedId: newest.session_id };
@@ -1034,6 +1042,9 @@ export async function backfillAbandonedSession({
  *   { action: 'skipped-not-completed', status }       — STATE.md status isn't 'completed'
  *   { action: 'skipped-no-session-id' }               — completed but no `session:` field
  *   { action: 'skipped-already-recorded', sessionId } — sessions.jsonl already has it
+ *   { action: 'skipped-key-occupied', sessionId }     — identity absent, but a canonical
+ *                                                       non-stub record of a DIFFERENT session
+ *                                                       already holds this key (#1388 P8)
  *   { action: 'skipped-marker-exists', sessionId }    — lost the TOCTOU claim
  *   { action: 'error', error, sessionId? }             — any failure, swallowed
  *
@@ -1118,6 +1129,22 @@ export async function backfillCompletedFromStateMd({
       if (existing.kind === 'canonical') {
         return { action: 'skipped-already-recorded', sessionId: existing.matchedId };
       }
+      // Key-occupancy guard (#1380 P6) — the counterpart of the abandoned
+      // path's occupied-key check. Identity can say `absent` (label drift
+      // veto, conflicting native join) while a canonical, authoritative record
+      // already holds `recordId`; canonical readers collapse by session_id
+      // newest-wins, so appending here would displace that record with this
+      // zero-counter one. `recordId` is already the native id whenever STATE.md
+      // carries one, so there is no alternate key to fall back to: skip.
+      if (existing.kind === 'absent'
+        && canonicalizeSessions(readJsonlSafe(readFileSync, sessionsPath))
+          .some((record) => record?.session_id === recordId && !isSupersedableStub(record))) {
+        // Distinct action (#1388 P8): `skipped-already-recorded` above means
+        // "this very session is already on file"; here identity said ABSENT and
+        // a DIFFERENT session's record occupies the key. Sharing one string made
+        // the two causes indistinguishable in the backfill_completed telemetry.
+        return { action: 'skipped-key-occupied', sessionId: recordId };
+      }
       const supersedes = existing.kind === 'stub' ? existing.stubId : null;
       // Preserve a matched stub's key for its append-only replacement. Without
       // event timestamps or a raw join on a legacy stub, a new UUID key would

package/scripts/lib/session-id.mjs

@@ -39,10 +39,11 @@
  *  - Production code is silent: no console.log, no console.warn.
  */
 
-import { open, readFile } from 'node:fs/promises';
+import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 
 import { readCanonicalSessions } from './sessions-canonical.mjs';
+import { readTailWindow } from './tail-window.mjs';
 import { withStateMdLock } from './session-lock.mjs';
 import { resolveStateMdPath } from './state-md/frontmatter-mutators.mjs';
 import { parseStateMd } from './state-md/yaml-parser.mjs';
@@ -208,31 +209,19 @@ const EVENTS_MAX_AGE_MS = 2 * 24 * 60 * 60 * 1000;
 async function readSessionIdsFromEvents(repoRoot) {
   const filePath = path.join(repoRoot, '.orchestrator', 'metrics', 'events.jsonl');
 
-  let text = '';
-  // Assigned in the try below; every path that reaches its read site has
-  // passed through that assignment (the catch returns early).
-  let windowIsPartial;
-  let handle = null;
+  let window;
   try {
-    handle = await open(filePath, 'r');
-    const { size } = await handle.stat();
-    const start = size > EVENTS_TAIL_BYTES ? size - EVENTS_TAIL_BYTES : 0;
-    windowIsPartial = start > 0;
-    const length = size - start;
-    if (length > 0) {
-      const buf = Buffer.alloc(length);
-      const { bytesRead } = await handle.read(buf, 0, length, start);
-      text = buf.subarray(0, bytesRead).toString('utf8');
-    }
+    // Sync read inside an async function: 1 MiB ceiling, one call per n-claim —
+    // the shared primitive (tail-window.mjs) owns the byte window, this reader
+    // keeps its own fail-open mapping.
+    window = readTailWindow(filePath, EVENTS_TAIL_BYTES);
   } catch {
     return [];
-  } finally {
-    if (handle !== null) await handle.close().catch(() => {});
   }
 
-  const lines = text.split(/\r?\n/);
+  const lines = window.text.split(/\r?\n/);
   // The window started mid-file, so line 0 may be a truncated record.
-  if (windowIsPartial) lines.shift();
+  if (window.cut) lines.shift();
 
   const cutoff = Date.now() - EVENTS_MAX_AGE_MS;
   const ids = [];

package/scripts/lib/session-invocation.mjs

@@ -0,0 +1,20 @@
+/**
+ * Resolve the leading /session mode independently of the user's task context.
+ * This is a text boundary, not a shell/option parser: quotes and command syntax
+ * in the context remain data. `unknown` is a ledger value, never a live mode.
+ *
+ * @param {string} [argumentsText] Complete text following /session.
+ * @returns {{sessionType: string, context: string, profile?: string, invalidMode?: string}}
+ */
+export function resolveSessionInvocation(argumentsText = '') {
+  if (typeof argumentsText !== 'string') {
+    throw new TypeError('session invocation arguments must be a string');
+  }
+  const [_, mode, context = ''] = argumentsText.trimStart().match(/^(\S+)(?:\s+([\s\S]*))?$/u) ?? [];
+  if (mode === undefined) return { sessionType: 'deep', context: '' };
+  if (mode === 'ultradeep') return { sessionType: 'deep', profile: 'ultradeep', context };
+  if (['housekeeping', 'feature', 'deep'].includes(mode)) {
+    return { sessionType: mode, context };
+  }
+  return { sessionType: 'deep', context, invalidMode: mode };
+}

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

@@ -5,8 +5,8 @@
  * Leaf module — no imports from siblings or parent.
  *
  * Exports: CURRENT_SESSION_SCHEMA_VERSION, SESSION_KEY_ALIASES,
- *          VALID_SESSION_TYPES, VALID_SESSION_PROFILES, REQUIRED_FIELDS,
- *          AGENT_SUMMARY_FIELDS
+ *          WAVE_KEY_ALIASES, VALID_SESSION_TYPES, VALID_SESSION_PROFILES,
+ *          REQUIRED_FIELDS, AGENT_SUMMARY_FIELDS, OPTIONAL_FIELDS
  */
 
 // ---------------------------------------------------------------------------
@@ -53,6 +53,24 @@ export const SESSION_KEY_ALIASES = Object.freeze({
   isolation_override: 'isolation',
 });
 
+/**
+ * Safe per-wave key aliases (legacy -> canonical) — the `waves[]` counterpart of
+ * SESSION_KEY_ALIASES, same-shape renames only. Applied by normalizeWaveKeys
+ * (normalizer.mjs) on read AND by scripts/emit-session.mjs on write (#1390 P1).
+ *
+ * The canonical spelling is `agent_count_*` (skills/session-end/
+ * metrics-collection.md). The ledger carried 23 sessions in that spelling and
+ * exactly one, `main-2026-09-18-session-1` (5 waves), in the de-underscored
+ * `agents_*` spelling (measured 2026-09-19 @ 8f6ac022 over
+ * .orchestrator/metrics/sessions.jsonl) — a consumer reading
+ * `w.agent_count_completed` got `undefined` for every one of its waves.
+ */
+export const WAVE_KEY_ALIASES = Object.freeze({
+  agents_planned: 'agent_count_planned',
+  agents_started: 'agent_count_started',
+  agents_completed: 'agent_count_completed',
+});
+
 // ---------------------------------------------------------------------------
 // Enums / required field lists
 // ---------------------------------------------------------------------------
@@ -198,4 +216,14 @@ export const OPTIONAL_FIELDS = Object.freeze([
   // lacking the field validates unchanged. Value set + the full rationale for
   // why it is NOT a VALID_SESSION_TYPES member: VALID_SESSION_PROFILES above.
   'session_profile',
+  // #1339 P8 — HEAD sha at session start. Gives `/evolve analyze` an
+  // attributable commit range instead of a time window that also catches
+  // parallel sessions' commits. Absent = not measured. NOT guaranteed to be a
+  // full sha: scripts/emit-session.mjs adopts STATE.md `session-start-ref`
+  // only when it is a full 40/64-hex sha, but an explicit key already on the
+  // record wins unchecked (even `null`), and every record before that
+  // derivation was hand-composed — 19 with a 40-char and 9 with a 7-char
+  // value (measured 2026-09-19 @ 8f6ac022, jq over sessions.jsonl).
+  // Consumers must accept a short sha or `null`, never assume a full one.
+  'session_start_ref',
 ]);

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

package/scripts/lib/sessions-canonical.mjs

@@ -399,6 +399,29 @@ export function countSessionsInJsonl(raw) {
  * is skipped rather than aborting the whole read (same posture as the readers
  * in `session-close-backfill.mjs` and `backfill-abandoned-sessions.mjs`).
  *
+ * NOT EVERY RAW READ OF `sessions.jsonl` IS A GAP TO CLOSE (#1221 P2). Five
+ * more readers bypass this module's collapse on purpose — verified via
+ * `rg -n "sessions.jsonl|SESSIONS"` against each file — and none of them
+ * should be "migrated" to `readCanonicalSessions`:
+ *   - `scripts/lib/sessions-integrity-banner.mjs` reads every raw line
+ *     (`readJsonlLines`) because it EXISTS to count malformed/mirror-invalid
+ *     records; canonicalizing first would hide the corruption it reports on.
+ *   - `scripts/lib/session-record-repair.mjs` is the repair tool itself — it
+ *     must see every raw record, malformed and duplicate alike, to fix them;
+ *     a canonical read would collapse or drop the very rows it needs to repair.
+ *   - `scripts/migrate-sessions-jsonl.mjs` rewrites legacy-shaped records one
+ *     raw line at a time; a canonicalized read could silently skip a
+ *     superseded or duplicate legacy record before the migration ever sees it.
+ *   - `scripts/gc-stale-worktrees.mjs` (`loadRecentSessionRefs`) scans every
+ *     raw line's string content for worktree references within a 7-day
+ *     window; a canonical read could drop a duplicate/superseded stub that
+ *     still names a worktree, making a live worktree look unreferenced and
+ *     eligible for garbage collection.
+ *   - `readTailSession()` in `scripts/autopilot.mjs` parses only the LAST raw
+ *     line to project the record this run's own session just appended,
+ *     verbatim; canonicalizing could return a different record than the tail
+ *     line if a collapse rule folded it away.
+ *
  * @param {object} [args]
  * @param {string} [args.repoRoot] project root; the ledger is resolved as
  *   `<repoRoot>/.orchestrator/metrics/sessions.jsonl`. Defaults to

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

@@ -103,7 +103,13 @@ import {
 } from './vault-mirror/render-sessions.mjs';
 
 /** Repo-relative path to the session ledger (one record per closed session). */
-const SESSIONS_PATH = '.orchestrator/metrics/sessions.jsonl';
+/**
+ * Ledger path, relative to the repo root. EXPORTED (#1417) so the CLI front-end
+ * `scripts/check-sessions-integrity.mjs` addresses the same file this banner
+ * judges instead of re-typing the literal — two spellings of one path is how a
+ * guard ends up measuring a file nobody writes.
+ */
+export const SESSIONS_PATH = '.orchestrator/metrics/sessions.jsonl';
 
 /** Max session_ids listed inline before the message collapses to "+N more". */
 export const MAX_LISTED_IDS = 5;