session-orchestrator 3.23.0 → 4.0.0

package/scripts/lib/convergence-monitor.mjs

@@ -39,6 +39,7 @@
  * @property {number} waveNumber
  * @property {number | null} filesChanged
  * @property {number | null} testPassed
+ * @property {number | null} testFailed
  * @property {number | null} agentDispatchCount
  */
 
@@ -143,21 +144,56 @@ function tailRead(absPath, prevOffset) {
  * Event types this monitor is meant to classify. Anything else is ignored even
  * when it carries a wave number.
  *
- * The allowlist is a wave-LIFECYCLE prefix plus the agent-dispatch counters —
- * i.e. exactly the records that can carry the three measurements
- * `evaluateSignals` compares (`files_changed`, `test.passed`,
- * `agents_dispatched`). It is deliberately fail-CLOSED: a new event type that
- * gains a `wave_number` field must be added here consciously.
+ * The allowlist is a wave-LIFECYCLE prefix, the agent-dispatch/-stop counters,
+ * and the quality-gate envelope — i.e. exactly the records that can carry the
+ * three measurements `evaluateSignals` compares (`files_changed`, the test
+ * pass count, the per-wave agent count). It is deliberately fail-CLOSED: a new
+ * event type that gains a `wave_number` field must be added here consciously.
+ *
+ * The gate admission is a TYPE-AND-SHAPE gate, never a bare prefix widening —
+ * see `isWaveScopedEvent` for why.
  */
 const WAVE_EVENT_PREFIX = 'orchestrator.wave.';
 const WAVE_EVENT_NAMES = new Set(['agent.dispatched', 'orchestrator.agent.dispatched']);
+const AGENT_STOPPED_EVENT = 'orchestrator.agent.stopped';
+const GATE_EVENT_PREFIX = 'orchestrator.quality_gate.';
+
+/**
+ * True when a record carries a `counts` object this monitor can fold, i.e. a
+ * plain object with a numeric `passed`. `counts: null`, an array, or a string
+ * payload are all rejected — the shape half of the type-and-shape gate.
+ *
+ * @param {Record<string, unknown>} rec
+ * @returns {boolean}
+ */
+function hasFoldableCounts(rec) {
+  const counts = rec.counts;
+  if (counts === null || typeof counts !== 'object' || Array.isArray(counts)) return false;
+  return pickInt(/** @type {Record<string, unknown>} */ (counts).passed) !== null;
+}
 
 /**
+ * Type-AND-shape gate: admit a record only when its event type is one this
+ * monitor classifies AND the record actually carries a measurement `classify`
+ * can fold. A bare prefix widening for `orchestrator.quality_gate.*` would
+ * re-open the #966 trap — the gate is the single highest-volume record type in
+ * `events.jsonl`, and admitting the session-level runs (no `wave_number`, or an
+ * envelope without `counts`) would instantiate a `WaveSummary` per gate run,
+ * advance `latestWave`, and burn the once-per-wave `alreadyEmitted` keys before
+ * the real wave record arrives. Hence the discriminator: a gate record is
+ * wave-scoped only when it has BOTH `wave_number` and a well-formed `counts`.
+ *
  * @param {string} evType
+ * @param {Record<string, unknown>} rec
  * @returns {boolean}
  */
-function isWaveScopedEvent(evType) {
-  return evType.startsWith(WAVE_EVENT_PREFIX) || WAVE_EVENT_NAMES.has(evType);
+function isWaveScopedEvent(evType, rec = {}) {
+  if (evType.startsWith(WAVE_EVENT_PREFIX)) return true;
+  if (WAVE_EVENT_NAMES.has(evType) || evType === AGENT_STOPPED_EVENT) return true;
+  if (evType.startsWith(GATE_EVENT_PREFIX)) {
+    return pickInt(rec.wave_number) !== null && hasFoldableCounts(rec);
+  }
+  return false;
 }
 
 /**
@@ -179,12 +215,29 @@ function isWaveScopedEvent(evType) {
  * `wave_number`, every gate run would have instantiated or refreshed a
  * `WaveSummary`, advanced `latestWave`, and burnt the once-per-wave
  * `alreadyEmitted` keys — suppressing the genuine signal when the real wave
- * record arrived later. Several other high-volume types (`session.stopped`,
- * `memory.propose_invoked`) already carry a wave and sat in the same trap.
+ * record arrived later. Several other high-volume types (`turn.stopped` — and its
+ * deprecated alias `session.stopped`, GitLab #1234 — plus `memory.propose_invoked`)
+ * already carry a wave and sat in the same trap. The gate is an ALLOWLIST
+ * (`isWaveRelevantType`), so the rename needed no edit here: a new name is
+ * ignored by default, which is the correct default for this classifier.
  *
- * Note the measurement keys are read FLAT (`rec['test.passed']`) and are
- * deliberately NOT reconciled with the gate event's nested `counts.passed` —
- * folding one into the other would silently change what this monitor measures.
+ * ## Where the pass count actually comes from (#980)
+ *
+ * Two independent paths, deliberately not merged:
+ *   - the FLAT `rec['test.passed']` alias, kept for a future direct emitter on
+ *     a wave-lifecycle record — no producer writes it today;
+ *   - the gate envelope's NESTED `counts.passed`, folded ONLY for
+ *     `orchestrator.quality_gate.*` records that also carry `wave_number`.
+ *     That gating is what keeps the #966 invariant intact: an ungated record
+ *     (a `wave.completed` carrying `counts`, or a session-level gate run with
+ *     no `wave_number`) still folds NOTHING, so a gate run cannot manufacture a
+ *     `WaveSummary` and burn the once-per-wave emit keys.
+ *
+ * `orchestrator.agent.stopped` is counted per record toward the wave's agent
+ * count, the same way `agent.dispatched` is — it is the only per-agent record
+ * this repo actually emits with a wave number (11,754 records measured
+ * 2026-09-05 in `.orchestrator/metrics/events.jsonl`, against 0 for
+ * `agent.dispatched`).
  *
  * @param {Record<string, unknown>} rec
  * @param {Map<number, WaveSummary>} state
@@ -192,7 +245,7 @@ function isWaveScopedEvent(evType) {
  */
 function classify(rec, state) {
   const evType = String(rec.event_type ?? rec.event ?? '');
-  if (!isWaveScopedEvent(evType)) return null;
+  if (!isWaveScopedEvent(evType, rec)) return null;
 
   const waveNumber = pickInt(rec.wave_number ?? rec.wave ?? rec.waveId);
   if (waveNumber === null) return null;
@@ -202,6 +255,7 @@ function classify(rec, state) {
       waveNumber,
       filesChanged: null,
       testPassed: null,
+      testFailed: null,
       agentDispatchCount: null,
     };
     state.set(waveNumber, summary);
@@ -210,8 +264,17 @@ function classify(rec, state) {
   if (filesChanged !== null) summary.filesChanged = filesChanged;
   const testPassed = pickInt(rec['test.passed'] ?? rec.test_passed ?? rec.testsPassed);
   if (testPassed !== null) summary.testPassed = testPassed;
-  // Count one agent.dispatched event toward this wave's dispatch count.
-  if (WAVE_EVENT_NAMES.has(evType)) {
+  // Nested gate envelope — admitted by isWaveScopedEvent only WITH wave_number,
+  // so the ungated #966 invariant (no fold) survives for every other record.
+  if (evType.startsWith(GATE_EVENT_PREFIX)) {
+    const counts = /** @type {Record<string, unknown>} */ (rec.counts);
+    const gatePassed = pickInt(counts.passed);
+    if (gatePassed !== null) summary.testPassed = gatePassed;
+    const gateFailed = pickInt(counts.failed);
+    if (gateFailed !== null) summary.testFailed = gateFailed;
+  }
+  // Count one dispatched/stopped agent record toward this wave's agent count.
+  if (WAVE_EVENT_NAMES.has(evType) || evType === AGENT_STOPPED_EVENT) {
     summary.agentDispatchCount = (summary.agentDispatchCount ?? 0) + 1;
   } else {
     const dispatched = pickInt(rec.agents_dispatched ?? rec.agentsDispatched);
@@ -443,4 +506,7 @@ if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.a
   main();
 }
 
-export { classify, isWaveScopedEvent };
+// `_evaluateSignals` is a test-only export (leading `_` per the repo convention,
+// cf. `_clearCompileCache` in scripts/lib/agent-output-schema.mjs): the signal
+// firing is otherwise reachable only through the live tail loop.
+export { classify, isWaveScopedEvent, evaluateSignals as _evaluateSignals };

package/scripts/lib/dispatcher/enumerate.mjs

@@ -29,12 +29,12 @@
  */
 
 import { readdirSync, existsSync } from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 
 import { getConfinementRoot, getCrossRepoProjects } from '../config/cross-repo.mjs';
 import { validatePathInsideProject } from '../path-utils.mjs';
 import { readLock, isLockLive } from '../session-lock.mjs';
+import { expandTilde } from '../common.mjs';
 
 /**
  * @typedef {Object} Candidate
@@ -97,21 +97,6 @@ function shouldDescendInto(name) {
   return true;
 }
 
-/**
- * Expand a leading `~` to the current user's home directory. Mirrors the helper
- * in board-writer.mjs (a shared extraction is deferred to a later epic). Used to
- * normalise config-declared cross-repo paths that may begin with `~/`.
- *
- * @param {string} p
- * @returns {string}
- */
-function expandHome(p) {
-  if (typeof p !== 'string' || p.length === 0) return p;
-  if (p === '~') return os.homedir();
-  if (p.startsWith('~/')) return path.join(os.homedir(), p.slice(2));
-  return p;
-}
-
 /**
  * Derive free/busy status for a single repo from its session.lock lease.
  * Mirrors board-writer.mjs collectRows semantics exactly:
@@ -322,7 +307,7 @@ export async function enumerateCandidates({ startDir, now, deps } = {}) {
   if (Array.isArray(declared)) {
     for (const raw of declared) {
       if (typeof raw !== 'string' || raw.length === 0) continue;
-      const expanded = expandHome(raw);
+      const expanded = expandTilde(raw);
       const abs = path.resolve(expanded);
       // Confinement-filter against the same root as the FS scan.
       const guard = validatePathInsideProjectFn(abs, root);

package/scripts/lib/dispatcher/rank.mjs

@@ -29,12 +29,12 @@
  * @typedef {{ repoRoot: string, repoName: string, free: boolean, status: 'frei'|'in-progress'|'force-closed', heartbeat: string|null, sessionId: string|null }} Candidate
  */
 
-import { readFileSync } from 'node:fs';
 import path from 'node:path';
 
 import { scanBacklog } from '../backlog-scan.mjs';
 import { checkCiStatus as realCheckCiStatus } from '../ci-status-banner.mjs';
 import { probe as realProbe, evaluate as realEvaluate, DEFAULT_RESOURCE_THRESHOLDS as CANONICAL_RESOURCE_THRESHOLDS } from '../resource-probe.mjs';
+import { readCanonicalSessions } from '../sessions-canonical.mjs';
 import { isRealSession } from '../session-schema/filters.mjs';
 
 /** Staleness cap (days). Beyond this, additional age does not raise the score. */
@@ -154,17 +154,29 @@ async function defaultFetchPriority(repoRoot, nowMs) {
 
 /**
  * Default STALENESS source: read `<repoRoot>/.orchestrator/metrics/sessions.jsonl`,
- * find the last REAL (non-phantom) record scanning backward from the tail, and
- * compute days since `completed_at` (fallback `started_at`). No file / no
- * parsable REAL record / no timestamp ⇒ `STALENESS_CAP_DAYS` (treat as
- * maximally stale = most worthwhile).
+ * find the MOST RECENT REAL (non-phantom) record's timestamp, and compute days
+ * since `completed_at` (fallback `started_at`). No file / no parsable REAL
+ * record / no timestamp ⇒ `STALENESS_CAP_DAYS` (treat as maximally stale =
+ * most worthwhile).
  *
- * Scans backward PAST any trailing `status: 'abandoned'` phantom stubs (#834)
- * — session-close-backfill writes these for sessions that ended without a real
- * close (0 waves, seconds of runtime). Stopping at the raw last LINE would let
- * a single recent phantom make a genuinely neglected repo look freshly
- * touched, defeating the dispatcher's whole purpose (this is the N=1 extreme
- * case of the phantom-tail problem — one stub is enough to zero out staleness).
+ * Skips `status: 'abandoned'` phantom stubs (#834) — session-close-backfill
+ * writes these for sessions that ended without a real close (0 waves, seconds
+ * of runtime). Counting one would let a single recent phantom make a
+ * genuinely neglected repo look freshly touched, defeating the dispatcher's
+ * whole purpose (this is the N=1 extreme case of the phantom-tail problem —
+ * one stub is enough to zero out staleness).
+ *
+ * #1209: takes the MAX timestamp over every canonical REAL record instead of
+ * scanning backward through raw file lines from the tail. A raw backward scan
+ * trusts FILE POSITION as a proxy for recency, which silently breaks the
+ * moment a backfill/repair writer appends an OLDER record after genuinely
+ * newer ones already exist — `session-record-repair.mjs` and
+ * `migrate-sessions-jsonl.mjs` both do this by design (see
+ * `sessions-canonical.mjs`'s module header, "by-design raw" list). A
+ * duplicated `session_id` re-appended late at the tail would make the old
+ * backward scan report the STALE re-append's date instead of the genuinely
+ * newer session's date; `readCanonicalSessions` collapses the duplicate to
+ * one record first, so the max-reduce below sees only the true timestamps.
  *
  * @param {string} repoRoot
  * @param {number} nowMs
@@ -173,33 +185,21 @@ async function defaultFetchPriority(repoRoot, nowMs) {
 async function defaultStaleDaysFor(repoRoot, nowMs) {
   try {
     const file = path.join(repoRoot, '.orchestrator', 'metrics', 'sessions.jsonl');
-    const raw = readFileSync(file, 'utf8');
-    const lines = raw.split('\n').map((l) => l.trim()).filter(Boolean);
-    if (lines.length === 0) return STALENESS_CAP_DAYS;
-
-    // Scan backward for the last REAL (non-abandoned) session record, skipping
-    // both corrupt lines and phantom stubs.
-    let last = null;
-    for (let i = lines.length - 1; i >= 0; i -= 1) {
-      let parsed;
-      try {
-        parsed = JSON.parse(lines[i]);
-      } catch {
-        continue; // Skip a corrupt line and try the previous one.
-      }
-      if (isRealSession(parsed)) {
-        last = parsed;
-        break;
-      }
+    const records = readCanonicalSessions({ filePath: file });
+    if (records.length === 0) return STALENESS_CAP_DAYS;
+
+    let latestMs = null;
+    for (const rec of records) {
+      if (!isRealSession(rec)) continue;
+      const iso = rec.completed_at || rec.started_at || null;
+      if (!iso || typeof iso !== 'string') continue;
+      const t = Date.parse(iso);
+      if (Number.isNaN(t)) continue;
+      if (latestMs === null || t > latestMs) latestMs = t;
     }
-    if (!last || typeof last !== 'object') return STALENESS_CAP_DAYS;
-
-    const iso = last.completed_at || last.started_at || null;
-    if (!iso || typeof iso !== 'string') return STALENESS_CAP_DAYS;
-    const t = Date.parse(iso);
-    if (Number.isNaN(t)) return STALENESS_CAP_DAYS;
+    if (latestMs === null) return STALENESS_CAP_DAYS;
 
-    const days = (nowMs - t) / MS_PER_DAY;
+    const days = (nowMs - latestMs) / MS_PER_DAY;
     return days > 0 ? days : 0;
   } catch {
     // No sessions file (or unreadable) ⇒ never worked on ⇒ maximally stale.
@@ -209,21 +209,75 @@ async function defaultStaleDaysFor(repoRoot, nowMs) {
 
 /**
  * Default READINESS (CI) source: thin wrapper over `checkCiStatus`.
- * Returns the 'green'|'red'|'unknown' status string, or null (no-op).
- * null / 'unknown' are treated as non-blocking by `scoreCandidate`.
+ *
+ * Passes the probe's result through VERBATIM rather than flattening it to a
+ * status string (#1031 follow-up). `checkCiStatus` has THREE return states —
+ * `null` (benign absence), `{status, …}` (a real reading), and
+ * `{severity:'warn', degraded:<reason>}` (the state could NOT be read) — and
+ * the old `typeof result.status === 'string' ? result.status : null` collapsed
+ * the third onto the first. That was not a scoring bug (both are non-blocking)
+ * but it discarded the one thing the operator needs to know: the ranking was
+ * computed WITHOUT a CI reading, and why. {@link normalizeCiSignal} in
+ * `rankCandidates` performs the shape reduction and keeps the reason.
+ *
+ * A THROW is the fourth state, and it is NOT the first: `checkCiStatus` is
+ * documented never to throw, so an exception here means the probe itself broke
+ * (a bad import, an unexpected runtime error). Returning `null` for it would
+ * assert measured ABSENCE — the one thing we know is false. It is mapped to the
+ * degraded shape instead, so {@link normalizeCiSignal} surfaces it as
+ * `ciStatus: 'unknown'` + `ciDegraded: 'probe-threw'` rather than silently.
  *
  * @param {{ repoRoot: string }} args
- * @returns {Promise<'green'|'red'|'unknown'|null>}
+ * @returns {Promise<'green'|'red'|'unknown'|null|object>} raw probe result.
  */
 async function defaultCheckCiStatus({ repoRoot }) {
   try {
-    const result = await realCheckCiStatus({ repoRoot });
-    return result && typeof result.status === 'string' ? result.status : null;
-  } catch {
-    return null;
+    return (await realCheckCiStatus({ repoRoot })) ?? null;
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    return {
+      severity: 'warn',
+      ok: false,
+      message: `⚠ ci-status: CI probe threw — state UNKNOWN, not "green". ${detail}`,
+      degraded: 'probe-threw',
+    };
   }
 }
 
+/**
+ * Reduce whatever a `checkCiStatus` dep returned to the pair the ranking needs:
+ * a scoring status and — when the state was UNREADABLE — the reason.
+ *
+ * Accepts every shape the dep contract permits, old and new:
+ *   - a bare status string (`'green'`/`'red'`/`'unknown'`) — the shape every
+ *     injected test dep uses; passed through unchanged.
+ *   - `null`/`undefined` — genuine absence, no signal, no reason.
+ *   - `{status: <string>}` — a real reading from `checkCiStatus`.
+ *   - `{degraded: <reason>}` with no usable `status` — the probe FAILED. Mapped
+ *     to `'unknown'`, which `scoreCandidate` already treats as non-blocking
+ *     (`ciFactor` dampens on `'red'` only), so ranking is byte-identical to the
+ *     previous `null` — but the reason survives into `readiness.ciDegraded`
+ *     and into a `warnings` entry.
+ *   - anything else — `null`, as before.
+ *
+ * `ciDegraded` is `null` (and the caller OMITS the key) whenever the state was
+ * readable, so existing strict `toEqual` pins on `signals.readiness` hold.
+ *
+ * @param {unknown} raw
+ * @returns {{ ciStatus: 'green'|'red'|'unknown'|null, ciDegraded: string|null }}
+ */
+export function normalizeCiSignal(raw) {
+  if (typeof raw === 'string' && raw) return { ciStatus: raw, ciDegraded: null };
+  if (!raw || typeof raw !== 'object') return { ciStatus: null, ciDegraded: null };
+  if (typeof raw.status === 'string' && raw.status) {
+    return { ciStatus: raw.status, ciDegraded: null };
+  }
+  if (typeof raw.degraded === 'string' && raw.degraded) {
+    return { ciStatus: 'unknown', ciDegraded: raw.degraded };
+  }
+  return { ciStatus: null, ciDegraded: null };
+}
+
 /**
  * Default READINESS (resource) source: probe the host ONCE and evaluate against
  * the canonical default thresholds. This is a HOST-level signal (identical for
@@ -290,7 +344,7 @@ export function defaultDeps() {
  *   ranked: Array<{ candidate: Candidate, score: number, signals: {
  *     priority: { criticalCount: number, highCount: number } | null,
  *     staleDays: number,
- *     readiness: { ciStatus: 'green'|'red'|'unknown'|null, resourceVerdict: 'green'|'warn'|'degraded'|'critical' },
+ *     readiness: { ciStatus: 'green'|'red'|'unknown'|null, resourceVerdict: 'green'|'warn'|'degraded'|'critical', ciDegraded?: string },
  *   } }>,
  *   warnings: string[],
  * }>}
@@ -342,18 +396,40 @@ export async function rankCandidates(freeCandidates, opts = {}) {
       staleDays = STALENESS_CAP_DAYS;
     }
 
-    // READINESS — CI status.
+    // READINESS — CI status. A degraded probe result ("state unknown") is
+    // NON-BLOCKING but not INVISIBLE: it scores like `null`, and reports why.
+    // Declared WITHOUT an initialiser on purpose: both paths below assign, and
+    // a `= null` seed would quietly re-create a fall-through "absent" default.
     let ciStatus;
+    let ciDegraded;
     try {
-      ciStatus = await deps.checkCiStatus({ repoRoot });
+      ({ ciStatus, ciDegraded } = normalizeCiSignal(await deps.checkCiStatus({ repoRoot })));
     } catch {
-      ciStatus = null;
+      // A THROWING dep is not measured ABSENCE. Leaving `ciDegraded` at null
+      // here re-created the exact collapse `normalizeCiSignal` exists to
+      // prevent: the ranking silently proceeded as if no CI signal existed,
+      // when in truth the probe broke. Scoring is unchanged (`'unknown'` is
+      // non-blocking) — only the reason becomes visible.
+      ciStatus = 'unknown';
+      ciDegraded = 'probe-threw';
+    }
+    if (ciDegraded) {
+      warnings.push(
+        `CI state unknown for ${repoName} (${ciDegraded}) — ranked without CI dampening`,
+      );
     }
 
     const signals = {
       priority,
       staleDays,
-      readiness: { ciStatus, resourceVerdict },
+      readiness: {
+        ciStatus,
+        resourceVerdict,
+        // Key OMITTED when the CI state was readable — a strict `toEqual` on
+        // `signals.readiness` must not have to know about a field that only
+        // exists on the failure path.
+        ...(ciDegraded ? { ciDegraded } : {}),
+      },
     };
     const score = scoreCandidate(signals);
 

package/scripts/lib/ecosystem-health.mjs

@@ -164,13 +164,27 @@ async function watchLoop(intervalS) {
 }
 
 /**
+ * Poll delay.
+ *
+ * The timer is deliberately NOT `unref()`d: it is the only handle this process
+ * holds (the two signal handlers do not keep the loop alive), so an unref'd
+ * timer drains the event loop and node exits 0 the instant the first tick is
+ * scheduled — a watcher that supervises nothing while looking like a clean
+ * shutdown, because it exits 0 with an empty stderr. Measured 2026-09-06 on the
+ * unref'd variant: `node scripts/lib/ecosystem-health.mjs --watch --interval=1`
+ * returned exit 0 after 48 ms instead of running until SIGTERM. Third copy of
+ * the #980 defect A1 measured in `scripts/lib/wave-transcript-tail.mjs` and
+ * `scripts/lib/convergence-monitor.mjs`; this one was missed when those two
+ * were fixed. Pinned by a DURATION assertion (an exit-code assertion cannot
+ * tell a healthy monitor from a dead one) in
+ * `tests/lib/ecosystem-health-watch.test.mjs`.
+ *
  * @param {number} ms
  * @returns {Promise<void>}
  */
 function sleep(ms) {
   return new Promise((resolve) => {
-    const t = setTimeout(resolve, ms);
-    t.unref?.();
+    setTimeout(resolve, ms);
   });
 }
 

package/scripts/lib/eval/engine.mjs

@@ -36,6 +36,7 @@ import path from 'node:path';
 
 import { resolvePluginRoot } from '../common.mjs';
 import { readJsonlFile } from '../io.mjs';
+import { readCanonicalSessions } from '../sessions-canonical.mjs';
 import { buildRunId, CURRENT_STANDARD_VERSION, VALID_MODEL_SOURCES } from './schema.mjs';
 import { resolveSession, computeWindow, findPeerOverlap } from './session-resolve.mjs';
 
@@ -538,7 +539,14 @@ export function evaluateSession(opts = {}) {
 
   const sessionsPath = path.join(metricsDir, 'sessions.jsonl');
   const eventsPath = path.join(metricsDir, 'events.jsonl');
-  const records = readJsonlFile(sessionsPath, { skipInvalid: true });
+  // #1209: sessions.jsonl is APPEND-ONLY (the same physical session can carry
+  // more than one line — crash-recovery re-appends, #1068 stub/supersede
+  // pairs), so a raw readJsonlFile() left resolveSession()/findPeerOverlap()
+  // to hand-roll their own dedup over duplicated / phantom-doubled records.
+  // readCanonicalSessions() collapses those first (newest-wins per
+  // session_id, #1068 double-stub collapse, supersede removal) — see
+  // session-resolve.mjs for how that simplifies both callers below.
+  const records = readCanonicalSessions({ filePath: sessionsPath });
   const events = readJsonlFile(eventsPath, { skipInvalid: true });
 
   const { record: session, resolvedVia } = resolveSession(records, sessionId);

package/scripts/lib/eval/session-resolve.mjs

@@ -48,11 +48,17 @@ export function resolveSession(records, sessionId) {
 
   // Explicit selection: the LAST record carrying this session_id (records may be
   // rewritten/backfilled across a session's life; the latest is authoritative).
+  //
+  // #1209: engine.mjs's production caller now passes CANONICAL records
+  // (readCanonicalSessions already resolved newest-wins per session_id before
+  // this array reaches here — see sessions-canonical.mjs), so at most one
+  // record can carry a given id in practice. `resolveSession` stays a
+  // general, pure function — `findLast` keeps the exact "last match wins"
+  // semantics for a caller that hands in raw, un-deduped records directly
+  // (e.g. the unit tests below), while degenerating to a single candidate on
+  // the canonical path.
   if (sessionId) {
-    let match = null;
-    for (const r of records) {
-      if (isPlainObject(r) && r.session_id === sessionId) match = r;
-    }
+    const match = records.findLast((r) => isPlainObject(r) && r.session_id === sessionId) ?? null;
     if (!match) {
       throw new SessionResolutionError(`session not found: ${sessionId}`);
     }
@@ -114,6 +120,19 @@ export function computeWindow(record) {
  * rewrites of the SAME session) are excluded, as are records without a valid
  * window.
  *
+ * #1209: the #1068 double-stub class — two ABANDONED records for ONE physical
+ * session (a real semantic `session_id` + a synthetic backfill twin, sharing
+ * an exact `started_at`/`completed_at` tuple, see `sessions-canonical.mjs`
+ * rule 2) — used to be counted as TWO distinct peers here, because the raw
+ * `records` array carried both lines under different ids and this function has
+ * no way to know they are the same physical session. With engine.mjs's
+ * production caller now passing `readCanonicalSessions()` output,
+ * `collapseAbandonedTuples()` has already dropped the synthetic twin before
+ * this array reaches here — a double-stub pair can therefore no longer
+ * produce a false EXTRA peer (`count` inflated by one) on the canonical path.
+ * `findPeerOverlap` itself stays general/pure for callers (including the unit
+ * tests below) that pass raw, un-deduped records directly.
+ *
  * @param {object[]} records — all sessions.jsonl records.
  * @param {object} resolved — the resolved session record.
  * @returns {{ count: number, peers: string[] }} unique overlapping session_ids.

package/scripts/lib/events-schema.mjs

@@ -12,6 +12,54 @@
  * Pure functions, no filesystem access — safe to import anywhere.
  */
 
+/**
+ * Current events.jsonl record schema version (#1177). Mirrors
+ * `subagents-schema.mjs § CURRENT_SCHEMA_VERSION`.
+ *
+ * Records written before #1177 carry NO `schema_version` key at all; an absent
+ * key therefore reads as "pre-versioned", never as version 0. Stamping is
+ * strictly additive — see `stampEventSchemaVersion()`.
+ */
+export const CURRENT_SCHEMA_VERSION = 1;
+
+/**
+ * Thrown by `emitEvent()` when a record fails `validateEventRecord()`.
+ *
+ * Carries the individual validator messages so a CLI/hook caller can surface
+ * them without re-running the validator.
+ */
+export class EventValidationError extends Error {
+  /**
+   * @param {string} message — human-readable summary.
+   * @param {string[]} [errors=[]] — the validator's individual error strings.
+   * @param {string} [eventType] — the offending event name, when known.
+   */
+  constructor(message, errors = [], eventType) {
+    super(message);
+    this.name = 'EventValidationError';
+    this.errors = errors;
+    this.eventType = eventType;
+  }
+}
+
+/**
+ * Return a shallow copy of `record` with `schema_version` stamped to
+ * `CURRENT_SCHEMA_VERSION` — but ONLY when the field is absent
+ * (`undefined`/`null`). An existing value is never overwritten, so a caller
+ * (or a migration re-writing historical records) keeps authority over its own
+ * version field.
+ *
+ * @param {object} record
+ * @returns {object} shallow copy, `schema_version` guaranteed present.
+ */
+export function stampEventSchemaVersion(record) {
+  const out = { ...record };
+  if (out.schema_version === undefined || out.schema_version === null) {
+    out.schema_version = CURRENT_SCHEMA_VERSION;
+  }
+  return out;
+}
+
 /** ISO-8601 UTC timestamp with trailing Z (e.g. 2026-05-28T14:35:13.123Z). */
 const ISO_8601_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/;