session-orchestrator 3.17.0 → 3.19.0

package/scripts/lib/config/config-protection.mjs

@@ -1,4 +1,5 @@
 import { matchBlockHeader } from './block-header.mjs';
+import { isSessionConfigHeading } from './section-extractor.mjs';
 
 /**
  * config-protection.mjs — Parser for the top-level `config-protection:` YAML
@@ -109,7 +110,7 @@ export function _isConfigWeakeningAllowed(content) {
   const lines = content.split(/\r?\n/);
   let inConfig = false;
   for (const line of lines) {
-    if (line === '## Session Config') { inConfig = true; continue; }
+    if (isSessionConfigHeading(line)) { inConfig = true; continue; }
     if (inConfig && /^## /.test(line)) break;
     if (inConfig) {
       const m = line.match(/^\s*(?:-\s+\*\*)?allow-config-weakening(?::\*\*)?\s*:\s*(\S+)/);

package/scripts/lib/config/drift-check.mjs

@@ -99,7 +99,15 @@ export function _parseDriftCheck(content) {
         dcEnabled = v.toLowerCase() === 'true';
         break;
       case 'mode':
-        if (['hard', 'warn', 'off'].includes(v)) dcMode = v;
+        // Enum: strict|warn|off. `hard` is a legacy alias for `strict`,
+        // normalized here. This is the drift-check half of the #217 enum
+        // migration (vault-sync moved hard→strict on 2026-04-21; drift-check
+        // was forgotten, so a committed `mode: strict` silently fell back to
+        // the `warn` default and the narrative-drift gate ran unenforced).
+        // Invalid values still fall back to the 'warn' default below.
+        if (['strict', 'hard', 'warn', 'off'].includes(v)) {
+          dcMode = v === 'hard' ? 'strict' : v;
+        }
         break;
       case 'include-paths':
         if (!v) inIncludeList = true;

package/scripts/lib/config/gitlab-portfolio.mjs

@@ -9,7 +9,7 @@ export const GITLAB_PORTFOLIO_DEFAULTS = {
   enabled: false,
   mode: 'warn',
   'stale-days': 30,
-  'critical-labels': ['priority:critical', 'priority:high'],
+  'critical-labels': ['priority::critical', 'priority::high'],
 };
 
 const VALID_MODES = new Set(['warn', 'strict', 'off']);

package/scripts/lib/config/issue-budget.mjs

@@ -0,0 +1,123 @@
+import { matchBlockHeader } from './block-header.mjs';
+
+/**
+ * issue-budget.mjs — Parser for the `issue-budget:` block-style Session Config key.
+ *
+ * Bounds how many issues ONE session may create. Motivation (measured on the
+ * private instance over four weeks): 1784 issues created against 1285 closed
+ * (net +499), median inter-creation gap 2.6 s, 62 % of creations inside bursts
+ * of >= 5 per minute. The pre-existing `discovery-confidence-threshold` /
+ * `discovery-severity-threshold` knobs do NOT bound this: they are per-finding
+ * QUALITY filters (and the `low` default filters nothing), they are only read
+ * in skill prose, and the largest producers never consult them at all.
+ *
+ * This key is a QUANTITY cap, enforced mechanically by
+ * `hooks/pre-bash-issue-budget.mjs` (shell path) and
+ * `scripts/lib/spiral-carryover.mjs` `runCli()` (programmatic path), both via
+ * `scripts/lib/issue-budget.mjs`.
+ *
+ * Returns `{ "max-per-session", mode, overflow }`.
+ * Tolerant parser: malformed values silently fall back to defaults (the
+ * `reconcile.min-rule-days` posture, NOT the noisier handover-gate WARN) —
+ * a hook must never spam stderr on every single Bash call.
+ *
+ * Consumers: `scripts/lib/config.mjs`, `scripts/lib/issue-budget.mjs`,
+ * `hooks/pre-bash-issue-budget.mjs`, `skills/session-end/SKILL.md` Phase 5.
+ */
+
+/** Valid `mode` values. */
+const MODES = ['strict', 'warn', 'off'];
+
+/** Valid `overflow` values. */
+const OVERFLOW_SINKS = ['collect-issue', 'vault-note'];
+
+/**
+ * Parse the `issue-budget:` block from markdown content.
+ *
+ * Like every sibling block parser this scans the FULL content rather than the
+ * `## Session Config` fence, so the block resolves identically whether it is
+ * nested inside `## Session Config` (the documented home) or lifted to a
+ * top-level block. Bold-bullet headers (`- **issue-budget:**`) are tolerated
+ * via the shared `matchBlockHeader` (#830).
+ *
+ * Defaults:
+ *   max-per-session: 12        integer >= 0; 0 means "no issue may be created"
+ *                              (a valid, deliberately harsh setting). Malformed
+ *                              or negative input falls back to 12.
+ *   mode:            strict    strict | warn | off
+ *   overflow:        collect-issue   collect-issue | vault-note
+ *
+ * YAML shape:
+ *   issue-budget:
+ *     max-per-session: 12
+ *     mode: strict
+ *     overflow: collect-issue
+ *
+ * @param {string} content — full file contents
+ * @returns {{ "max-per-session": number, mode: string, overflow: string }}
+ */
+export function _parseIssueBudget(content) {
+  const defaults = {
+    'max-per-session': 12,
+    mode: 'strict',
+    overflow: 'collect-issue',
+  };
+
+  if (typeof content !== 'string' || content === '') return { ...defaults };
+
+  const lines = content.split(/\r?\n/);
+  let inBlock = false;
+  const blockLines = [];
+
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/\r$/, '');
+    if (!inBlock) {
+      if (matchBlockHeader(line, 'issue-budget')) inBlock = true;
+      continue;
+    }
+    // Stop at next column-0 non-empty line (sibling top-level key or H2 heading)
+    if (line.length > 0 && !/^\s/.test(line)) break;
+    blockLines.push(line);
+  }
+
+  if (blockLines.length === 0) return { ...defaults };
+
+  let maxPerSession = defaults['max-per-session'];
+  let mode = defaults.mode;
+  let overflow = defaults.overflow;
+
+  for (const rawLine of blockLines) {
+    // Strip inline comments and trailing whitespace
+    const clean = rawLine.replace(/\s*#.*$/, '').replace(/\s+$/, '');
+    if (!clean.trim()) continue;
+
+    const kvMatch = clean.match(/^\s+([a-zA-Z_-]+):\s*(.*)/);
+    if (!kvMatch) continue;
+
+    const k = kvMatch[1];
+    let v = kvMatch[2].trim();
+    if (v.startsWith('"') && v.endsWith('"') && v.length >= 2) v = v.slice(1, -1);
+    else if (v.startsWith("'") && v.endsWith("'") && v.length >= 2) v = v.slice(1, -1);
+
+    switch (k) {
+      case 'max-per-session':
+        // Non-negative integer only; a leading '-' fails \d+ → default.
+        if (/^\d+$/.test(v)) maxPerSession = parseInt(v, 10);
+        break;
+
+      case 'mode':
+        if (MODES.includes(v.toLowerCase())) mode = v.toLowerCase();
+        break;
+
+      case 'overflow':
+        if (OVERFLOW_SINKS.includes(v.toLowerCase())) overflow = v.toLowerCase();
+        break;
+    }
+  }
+
+  return {
+    'max-per-session': maxPerSession,
+    mode,
+    overflow,
+  };
+}

package/scripts/lib/config/reconcile.mjs

@@ -16,6 +16,7 @@ import { matchBlockHeader } from './block-header.mjs';
  *     'confidence-floor': number,
  *     'min-rule-days': number,
  *     'min-insight-chars': number,
+ *     'max-proposals-per-run': number,
  *   }
  *
  * Tolerant parser: malformed values silently fall back to defaults.
@@ -51,6 +52,12 @@ import { matchBlockHeader } from './block-header.mjs';
  *                                          gating the eligibility placeholder-insight check
  *                                          (issue #741.2). Malformed, absent, or negative
  *                                          values fall back to 24.
+ *   reconcile.max-proposals-per-run: 10  — positive integer (min 1); volume brake (issue
+ *                                          #900 D) — the reconcile engine sorts eligible
+ *                                          learnings by confidence DESC and proposes at
+ *                                          most this many per run, recording the cut count
+ *                                          in the run summary (`summary.capped`). Malformed,
+ *                                          absent, or non-positive values fall back to 10.
  *
  * YAML shape:
  *   reconcile:
@@ -61,6 +68,7 @@ import { matchBlockHeader } from './block-header.mjs';
  *     confidence-floor: 0.5
  *     min-rule-days: 7
  *     min-insight-chars: 24
+ *     max-proposals-per-run: 10
  *
  * @param {string} content — full file contents
  * @returns {{
@@ -71,6 +79,7 @@ import { matchBlockHeader } from './block-header.mjs';
  *   'confidence-floor': number,
  *   'min-rule-days': number,
  *   'min-insight-chars': number,
+ *   'max-proposals-per-run': number,
  * }}
  */
 export function _parseReconcile(content) {
@@ -82,6 +91,7 @@ export function _parseReconcile(content) {
     'confidence-floor': 0.5,
     'min-rule-days': 7,
     'min-insight-chars': 24,
+    'max-proposals-per-run': 10,
   };
 
   const lines = content.split(/\r?\n/);
@@ -108,6 +118,7 @@ export function _parseReconcile(content) {
   let confidenceFloor = 0.5;
   let minRuleDays = 7;
   let minInsightChars = 24;
+  let maxProposalsPerRun = 10;
 
   for (const rawLine of blockLines) {
     // Strip inline comments and trailing whitespace
@@ -183,6 +194,15 @@ export function _parseReconcile(content) {
         break;
       }
 
+      case 'max-proposals-per-run': {
+        if (/^\d+$/.test(v)) {
+          const n = parseInt(v, 10);
+          if (n >= 1) maxProposalsPerRun = n;
+          // 0 or malformed: silently ignore, keep default 10
+        }
+        break;
+      }
+
       // targets inline-list with no brackets (e.g. targets: repo-local) — single value
       case 'targets': {
         if (v && !v.startsWith('[')) {
@@ -201,5 +221,6 @@ export function _parseReconcile(content) {
     'confidence-floor': confidenceFloor,
     'min-rule-days': minRuleDays,
     'min-insight-chars': minInsightChars,
+    'max-proposals-per-run': maxProposalsPerRun,
   };
 }

package/scripts/lib/config/section-extractor.mjs

@@ -8,6 +8,126 @@
 // Section extraction (ported from config-yaml-parser.sh)
 // ---------------------------------------------------------------------------
 
+/**
+ * THE canonical predicate for "this line opens the `## Session Config` block".
+ *
+ * Exported (#959 follow-up) because this repo previously carried FIVE
+ * independent copies of this fact, and the loosest of them —
+ * `scripts/lib/claude-md-budget-lint.mjs` — was the module whose whole job is
+ * to MEASURE the block. That asymmetry was not academic: the lint accepted a
+ * heading decorated with a trailing HTML comment (`## Session Config <!-- … -->`,
+ * a decoration this repo's own convention encourages on sibling headings),
+ * while `_extractConfigSection` below rejected it. An author following the
+ * cited convention therefore got a CLAUDE.md (or AGENTS.md on Codex CLI —
+ * transparent aliases, see skills/_shared/instruction-file-resolution.md)
+ * whose every runtime config key
+ * silently fell back to its default, while the lint simultaneously reported
+ * "148 exempt: '## Session Config'" — the instrument affirming the block is
+ * present and runtime-critical at the exact moment the runtime cannot see it.
+ *
+ * The invariant this export exists to hold: **no consumer's predicate may
+ * accept a heading this one rejects.** Importing beats re-deriving; a copy
+ * that drifts loose is worse than no check at all.
+ *
+ * Intentionally EXACT (not a fuzzy regex) apart from CRLF tolerance — it is
+ * the literal comparison `_extractConfigSection` has always used, merely
+ * given a name. `##  Session Config` (two spaces), a trailing HTML comment,
+ * and `## Session Config Convention` are all correctly rejected.
+ *
+ * Dependency note: this module imports NOTHING. Keep it that way — the budget
+ * lint consumes this predicate at bootstrap-scaffold time, before
+ * `.claude/rules/` (or most of the repo) exists.
+ *
+ * @param {string} line - a single line, with or without a trailing '\r'.
+ * @returns {boolean}
+ */
+export function isSessionConfigHeading(line) {
+  return typeof line === 'string' && line.replace(/\r$/, '') === SESSION_CONFIG_HEADING;
+}
+
+/**
+ * The literal heading text, for the one site that legitimately WRITES it
+ * (`scripts/lib/ecosystem-wizard/config-writer.mjs` appends a fresh
+ * `## Session Config` section when none exists).
+ *
+ * A producer and a comparator agreeing by coincidence is the same disease
+ * `isSessionConfigHeading` exists to cure, one level down: a writer that
+ * emits a heading the reader rejects manufactures exactly the silent
+ * everything-falls-back-to-defaults failure described above. Writers import
+ * this; comparators import the predicate. Neither re-types the string.
+ *
+ * @type {string}
+ */
+export const SESSION_CONFIG_HEADING = '## Session Config';
+
+/**
+ * Locate the `## Session Config` block and return its body span.
+ *
+ * THE canonical block-extractor, and the companion to
+ * `isSessionConfigHeading` above. Four consumers previously re-derived this
+ * span with four different regexes, and the divergence was not academic:
+ * `harness-audit/categories/category4.mjs` used
+ * `/^## Session Config\s*\n([\s\S]*?)(?=^## |\s*$)/m`, whose `\s*$` lookahead
+ * (with `/m`, `$` matches at every line end) makes the lazy body quantifier
+ * stop at the FIRST line of the block. On this repo's own CLAUDE.md that
+ * captured 17 characters — `persistence: true` — instead of 2877, so the
+ * `vault-integration:` block three lines below was structurally invisible and
+ * the c4.4 check scored 2/2 with "vault-integration not enabled — skip" in a
+ * repo where it is enabled. A capture bug in a scoring instrument reads as a
+ * pass, never as an error.
+ *
+ * The body runs from the line AFTER the heading up to (not including) the
+ * next `## ` heading, or EOF. Line-based over `isSessionConfigHeading`, so
+ * the heading predicate cannot drift from the span extractor.
+ *
+ * Offsets are indices into the ORIGINAL `content` string, so callers that
+ * need to splice (insert/replace) can do so without re-finding the block.
+ *
+ * @param {string} content - full markdown document
+ * @param {{ occurrence?: 'first'|'last' }} [options] - which heading to match
+ *   when a document carries several (docs/session-config-template.md carries
+ *   two, both inside fenced examples).
+ * @returns {{ body: string, bodyStart: number, bodyEnd: number,
+ *   headingLine: number } | null} null when no heading matches.
+ */
+export function findSessionConfigBlock(content, { occurrence = 'first' } = {}) {
+  if (typeof content !== 'string' || content.length === 0) return null;
+
+  const lines = content.split('\n');
+
+  // Byte offset of the start of each line in `content`.
+  const lineStarts = [];
+  let offset = 0;
+  for (const line of lines) {
+    lineStarts.push(offset);
+    offset += line.length + 1; // +1 for the '\n' consumed by split
+  }
+
+  const headingIdxs = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (isSessionConfigHeading(lines[i])) headingIdxs.push(i);
+  }
+  if (headingIdxs.length === 0) return null;
+
+  const targetIdx = occurrence === 'last' ? headingIdxs[headingIdxs.length - 1] : headingIdxs[0];
+
+  // Body ends at the next `## ` heading (any H2 closes the block), or EOF.
+  let endIdx = lines.length;
+  for (let i = targetIdx + 1; i < lines.length; i++) {
+    if (/^## /.test(lines[i].replace(/\r$/, ''))) { endIdx = i; break; }
+  }
+
+  const bodyStart = targetIdx + 1 < lines.length ? lineStarts[targetIdx + 1] : content.length;
+  const bodyEnd = endIdx < lines.length ? lineStarts[endIdx] : content.length;
+
+  return {
+    body: lines.slice(targetIdx + 1, endIdx).join('\n'),
+    bodyStart,
+    bodyEnd,
+    headingLine: targetIdx + 1, // 1-based, for error reporting
+  };
+}
+
 /**
  * Extract the raw ## Session Config block lines from markdown content.
  * - CRLF-tolerant
@@ -24,7 +144,7 @@ export function _extractConfigSection(content) {
   for (const rawLine of lines) {
     const line = rawLine.replace(/\r$/, '');
 
-    if (line === '## Session Config') {
+    if (isSessionConfigHeading(line)) {
       inSection = true;
       continue;
     }

package/scripts/lib/config-schema.mjs

@@ -9,7 +9,11 @@
  */
 
 const ENFORCEMENT_VALUES = new Set(['strict', 'warn', 'off']);
-const VAULT_MODE_VALUES = new Set(['strict', 'warn', 'off']);
+// Exported (issue #836) so cross-layer mode-vocabulary parity tests can use
+// this Set as the single source of truth for "the modes a Session Config
+// `*.mode` key accepts" — rather than re-deriving a duplicate literal list
+// that could silently drift from this schema.
+export const VAULT_MODE_VALUES = new Set(['strict', 'warn', 'off']);
 
 const REQUIRED_STRING_FIELDS = [
   'test-command',
@@ -25,11 +29,13 @@ const REQUIRED_STRING_FIELDS = [
  */
 export function validateSessionConfig(config) {
   const errors = [];
+  const warnings = [];
 
   if (config === null || typeof config !== 'object' || Array.isArray(config)) {
     return {
       ok: false,
       errors: [{ path: '$', rule: 'type', message: 'config must be a JSON object' }],
+      warnings,
     };
   }
 
@@ -90,10 +96,24 @@ export function validateSessionConfig(config) {
     for (const msg of gpErrs) errors.push({ path: 'gitlab-portfolio', rule: 'object', message: msg });
   }
 
+  // HR-003 cross-field anti-pattern (baseline #60): a heavy repo left on
+  // isolation: auto|none accumulates worktrees without the aggressive cleanup
+  // HR-003 recommends — this is advisory (warn-level), it never flips `ok`.
+  if (config['heavy-repo'] === true) {
+    const isolationVal = config['isolation'];
+    if (isolationVal === 'auto' || isolationVal === 'none') {
+      warnings.push({
+        path: 'isolation',
+        rule: 'heavy-repo-cross-field',
+        message: `heavy-repo: true but isolation is '${isolationVal}' — heavy repos should pin isolation: worktree (HR-003)`,
+      });
+    }
+  }
+
   if (errors.length > 0) {
-    return { ok: false, errors };
+    return { ok: false, errors, warnings };
   }
-  return { ok: true, config };
+  return { ok: true, config, warnings };
 }
 
 function validateAgentsPerWave(value, errors) {

package/scripts/lib/config.mjs

@@ -56,6 +56,7 @@ import { _parseColdStart } from './config/cold-start.mjs';
 import { _parseAutoDream } from './config/auto-dream.mjs';
 import { _parseStateMdLock } from './config/state-md-lock.mjs';
 import { _parseHandoverGate } from './config/handover-gate.mjs';
+import { _parseIssueBudget } from './config/issue-budget.mjs';
 import { _parseBrokenWindow } from './config/broken-window.mjs';
 import { _parseSlopcheck } from './config/slopcheck.mjs';
 import { _parseDiscoveryValidator } from './config/discovery-validator.mjs';
@@ -195,6 +196,9 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
   const allowDestructiveOps = _coerceBoolean(kv, 'allow-destructive-ops', false);
   const resourceAwareness = _coerceBoolean(kv, 'resource-awareness', true);
   const enableHostBanner = _coerceBoolean(kv, 'enable-host-banner', true);
+  // heavy-repo / worktree-cleanup: HR-003 preflight fields (templates/shared/.claude/rules/heavy-repo.md),
+  // documented but previously unwired — silently dropped by the parser (baseline issue #60).
+  const heavyRepo = _coerceBoolean(kv, 'heavy-repo', false);
 
   // List fields
   const crossRepos = _coerceList(kv, 'cross-repos', undefined);
@@ -212,6 +216,10 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
   const enforcement = _coerceEnum(kv, 'enforcement', 'warn', ['strict', 'warn', 'off']);
   const isolation = _coerceEnum(kv, 'isolation', 'auto', ['worktree', 'none', 'auto']);
   const discoverySeverityThreshold = _coerceEnum(kv, 'discovery-severity-threshold', 'low', ['critical', 'high', 'medium', 'low']);
+  // worktree-cleanup: HR-003 (baseline issue #60). NOTE: 'aggressive' currently behaves
+  // identically to 'default' at runtime — the per-wave aggressive sweep is a tracked
+  // follow-up (see docs/session-config-reference.md). This wires the parser + value only.
+  const worktreeCleanup = _coerceEnum(kv, 'worktree-cleanup', 'default', ['default', 'aggressive']);
 
   // Object fields
   const agentMapping = _coerceObject(kv, 'agent-mapping');
@@ -296,6 +304,12 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
   // Handover-Alignment-Gate — Epic #724)
   const handoverGate = _parseHandoverGate(mdContent);
 
+  // issue-budget: per-session issue-creation cap (QUANTITY gate). Distinct from
+  // discovery-severity-threshold / discovery-confidence-threshold above, which
+  // are per-finding QUALITY filters and cannot bound creation volume. Enforced
+  // by hooks/pre-bash-issue-budget.mjs + scripts/lib/spiral-carryover.mjs.
+  const issueBudget = _parseIssueBudget(mdContent);
+
   // broken-window-budget: parsed from full content (#730/H5 — session-end Phase 2.6)
   const brokenWindow = _parseBrokenWindow(mdContent);
 
@@ -437,6 +451,8 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
     'allow-destructive-ops': allowDestructiveOps,
     'resource-awareness': resourceAwareness,
     'enable-host-banner': enableHostBanner,
+    'heavy-repo': heavyRepo,
+    'worktree-cleanup': worktreeCleanup,
     'resource-thresholds': resourceThresholds,
     'worktree-exclude': worktreeExclude,
     'vault-integration': vaultIntegration,
@@ -445,6 +461,7 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
     'auto-dream': autoDream,
     'state-md-lock': stateMdLock,
     'handover-gate': handoverGate,
+    'issue-budget': issueBudget,
     'broken-window-budget': brokenWindow,
     'slopcheck': slopcheck,
     'skill-evolution': skillEvolution,

package/scripts/lib/convergence-monitor.mjs

@@ -44,6 +44,7 @@
 
 import { existsSync, statSync, openSync, readSync, closeSync } from 'node:fs';
 import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
 
 const DEFAULT_INTERVAL_S = 2;
 const EVENTS_FILE_REL = '.orchestrator/metrics/events.jsonl';
@@ -138,6 +139,27 @@ 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.
+ */
+const WAVE_EVENT_PREFIX = 'orchestrator.wave.';
+const WAVE_EVENT_NAMES = new Set(['agent.dispatched', 'orchestrator.agent.dispatched']);
+
+/**
+ * @param {string} evType
+ * @returns {boolean}
+ */
+function isWaveScopedEvent(evType) {
+  return evType.startsWith(WAVE_EVENT_PREFIX) || WAVE_EVENT_NAMES.has(evType);
+}
+
 /**
  * Classify a raw events.jsonl record and update the in-memory wave summary
  * map. Returns the wave number affected, or null if the record is not a
@@ -148,11 +170,30 @@ function tailRead(absPath, prevOffset) {
  *   - { event_type, wave, wave_number, files_changed, test.passed,
  *       agent.dispatched, agents_dispatched }
  *
+ * ## Event-type gate (#966 step 1)
+ *
+ * A wave number alone is NOT sufficient to classify — the type gate runs first.
+ * `orchestrator.quality_gate.*` is by far the highest-volume record in
+ * `events.jsonl` and was ignored here only ACCIDENTALLY, because it happened to
+ * carry no wave number. The moment `run-quality-gate.mjs` started emitting
+ * `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.
+ *
+ * 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.
+ *
  * @param {Record<string, unknown>} rec
  * @param {Map<number, WaveSummary>} state
  * @returns {number | null}
  */
 function classify(rec, state) {
+  const evType = String(rec.event_type ?? rec.event ?? '');
+  if (!isWaveScopedEvent(evType)) return null;
+
   const waveNumber = pickInt(rec.wave_number ?? rec.wave ?? rec.waveId);
   if (waveNumber === null) return null;
   let summary = state.get(waveNumber);
@@ -170,8 +211,7 @@ function classify(rec, state) {
   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.
-  const evType = String(rec.event_type ?? rec.event ?? '');
-  if (evType === 'agent.dispatched') {
+  if (WAVE_EVENT_NAMES.has(evType)) {
     summary.agentDispatchCount = (summary.agentDispatchCount ?? 0) + 1;
   } else {
     const dispatched = pickInt(rec.agents_dispatched ?? rec.agentsDispatched);
@@ -386,4 +426,10 @@ function main() {
   });
 }
 
-main();
+// Run the tail loop only when executed as a script. Importing the module (for
+// unit tests over `classify`) must not parse vitest's argv and exit 1.
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main();
+}
+
+export { classify, isWaveScopedEvent };