session-orchestrator 5.2.0 → 5.3.0

package/scripts/lib/convergence-monitor.mjs

@@ -144,20 +144,62 @@ 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, 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 allowlist is the wave-COMPLETION record, 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.
+ *
+ * `orchestrator.wave.completed` is admitted by its EXACT name. The
+ * `orchestrator.wave.` prefix that stood here until 2026-09-19 also admitted
+ * `wave.started` (and `wave.final_refused`), neither of which carries a
+ * measurement — and it cost the one signal the diff keys
+ * exist for: the batch hook wrote completed{N} and started{N+1} in the same
+ * millisecond, so they shared a tail tick, started{N+1} instantiated an EMPTY
+ * summary for N+1, the tick's highest wave became N+1, and the (N-1, N)
+ * `shrinking_diff` pair was never compared (architect-reviewer repro,
+ * 40 -> 10 -> 5 files: same tick `[]`, split ticks `shrinking_diff:2` and `:3`).
  */
-const WAVE_EVENT_PREFIX = 'orchestrator.wave.';
+const WAVE_COMPLETED_EVENT = 'orchestrator.wave.completed';
 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 an `orchestrator.agent.stopped` record names the agent that stopped.
+ *
+ * The shape half of the type-and-shape gate for the agent counter: the event
+ * type is BIMODAL (#939/#949, documented at `hooks/on-stop.mjs:554-580`). Only
+ * the records carrying a non-empty `agent` describe a real dispatched agent;
+ * the rest are the phantom-stop class the coordinator's own `Stop` emits, and
+ * counting them inflates every per-wave agent count and the `velocity_drop`
+ * signal derived from it.
+ *
+ * Measured 2026-09-18 over the then-active `.orchestrator/metrics/events.jsonl`
+ * plus the legacy `.jsonl.1` backup beside it (destroyed 2026-09-19):
+ *   → { total_stopped: 16438, with_wave: 6553, with_wave_no_agent: 5930 }
+ * i.e. 90.5% of the wave-scoped stops carry no `agent` — a ~10.5x inflation.
+ *
+ * To re-measure, read the ledger with `readEventsWithRotations(repoRoot)` from
+ * `scripts/lib/events.mjs` — it yields the active file plus every archive in
+ * time order and reports a rotation whose archive is gone as a `gaps` entry
+ * with `complete: false`, which a `cat` over rotation files cannot. Rotation
+ * writes `_archive/events-<firstTs>_<lastTs>.jsonl` and an
+ * `orchestrator.events.rotated` first line since #1401; the `.1`..`.N` ring is
+ * no longer written (see `events-rotation.mjs` § Why `_archive/<name>`).
+ * Recipe with the jq filter: `skills/convergence-monitoring/SIGNALS.md`
+ * § Live monitor input.
+ *
+ * @param {Record<string, unknown>} rec
+ * @returns {boolean}
+ */
+function namesAnAgent(rec) {
+  return typeof rec.agent === 'string' && rec.agent.trim() !== '';
+}
+
 /**
  * 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
@@ -183,13 +225,18 @@ function hasFoldableCounts(rec) {
  * 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`.
  *
+ * The same discriminator applies to `orchestrator.agent.stopped`: the type is
+ * bimodal, so a stop record is admitted only when it NAMES an agent — see
+ * `namesAnAgent`.
+ *
  * @param {string} evType
  * @param {Record<string, unknown>} rec
  * @returns {boolean}
  */
 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 === WAVE_COMPLETED_EVENT) return true;
+  if (WAVE_EVENT_NAMES.has(evType)) return true;
+  if (evType === AGENT_STOPPED_EVENT) return namesAnAgent(rec);
   if (evType.startsWith(GATE_EVENT_PREFIX)) {
     return pickInt(rec.wave_number) !== null && hasFoldableCounts(rec);
   }
@@ -235,9 +282,16 @@ function isWaveScopedEvent(evType, rec = {}) {
  *
  * `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`).
+ * this repo actually emits with a wave number. But it is counted ONLY when the
+ * record NAMES its agent (`namesAnAgent`): the type is bimodal, and the
+ * unfiltered count is dominated by the #939/#949 phantom-stop class.
+ *
+ * Measured 2026-09-18 over `.orchestrator/metrics/events.jsonl{,.1}` (same jq
+ * envelope quoted at `namesAnAgent`):
+ *   agent.stopped, any shape ................. 16438
+ *   ... carrying a wave number ...............  6553
+ *   ... of those, WITHOUT an `agent` field ...  5930  (90.5% — not counted)
+ *   ... of those, WITH a non-empty `agent` ...   623  (what this counter reads)
  *
  * @param {Record<string, unknown>} rec
  * @param {Map<number, WaveSummary>} state
@@ -431,6 +485,15 @@ async function tailLoop(intervalS) {
       continue;
     }
     offset = tick.offset;
+    // Only the HIGHEST wave this tick touched is evaluated. NAMED CEILING
+    // (BV-004): a wave-(N+1) record that DOES carry a measurement (a named
+    // agent.dispatched/-stopped, a gated quality_gate envelope) landing in the
+    // same tick as completed{N} still masks the (N-1, N) pair. Evaluating every
+    // touched wave would close that, but the first tick reads the whole ledger
+    // from offset 0 and wave numbers are not session-scoped, so one stale
+    // startup evaluation would become one per wave number in history. Revisit
+    // if the ledger shows such a record within one poll interval of a
+    // completed{N}.
     let latestWave = -1;
     for (const line of tick.lines) {
       /** @type {Record<string, unknown> | null} */

package/scripts/lib/ecosystem-health.mjs

@@ -40,6 +40,17 @@
 import { existsSync, statSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 
+// Ceiling (BV-004): one process per session that invoked session-start
+// (monitors/monitors.json `when: on-skill-invoke:session-start`), alive until
+// SIGTERM; one stat + one full readFileSync of ONE local file per 900 s
+// (resolved against CLAUDE_PLUGIN_ROOT, not the repo); no network, no repo
+// enumeration, no Session Config read (runs even with `ecosystem-health: false`).
+// The watched file has NO producer (0 writers, measured 2026-09-18:
+// `rg -l "ecosystem-health\.jsonl"` → this file only) — every run emits
+// `no-state-yet` and idles. Revisit when: (1) code starts writing
+// .orchestrator/metrics/ecosystem-health.jsonl → switch to a tail read and gate
+// on `ecosystem-health` enabled; or (2) peer sessions regularly exceed ~5 (one
+// idle node process per live session).
 const DEFAULT_INTERVAL_S = 15 * 60; // 15min
 const STATE_FILE_REL = '.orchestrator/metrics/ecosystem-health.jsonl';