session-orchestrator 3.16.0 → 3.19.0

package/scripts/lib/config/worktree-orphans.mjs

@@ -0,0 +1,138 @@
+import { matchBlockHeader } from './block-header.mjs';
+
+/**
+ * worktree-orphans.mjs — Parser for the top-level `worktree-orphans:` YAML block.
+ *
+ * Config block shape (see docs/session-config-template.md):
+ *   worktree-orphans:
+ *     enabled: false
+ *     base-branch: main
+ *     mode: warn
+ *
+ * Mirrors the docs-staleness.mjs parser design (issue #831 / B5), but flat —
+ * there is no nested threshold map, just three scalar keys.
+ *
+ * Opt-in by design: `enabled` defaults to `false`, so a repo that has never
+ * heard of this block never pays a single git invocation for it.
+ *
+ * ZERO IMPORTS beyond ./block-header.mjs: tests/lib/config/cycle-guard.test.mjs
+ * forbids any scripts/lib/config/*.mjs from importing ../config.mjs.
+ */
+
+/**
+ * Valid `base-branch` character set — mirrors `ENTER_WORKTREE_BRANCH_RE` in
+ * scripts/lib/autopilot/worktree-pipeline.mjs (itself mirroring the private
+ * `isValidBranch()` in scripts/lib/session-id.mjs). Duplicated rather than
+ * imported because this parser is dependency-free by contract (see header) and
+ * `isValidBranch` is module-private; worktree-pipeline.mjs sets the precedent
+ * for mirroring it locally.
+ */
+const BASE_BRANCH_CHARSET = /^[A-Za-z0-9._/-]+$/;
+
+/**
+ * Decide whether a `base-branch` value is safe to hand to the Phase 4b sweep.
+ *
+ * The consumer (scripts/lib/session-end/worktree-orphan-sweep.mjs) interpolates
+ * this value into the argv token `` `${baseBranch}..${branch}` `` for
+ * `git rev-list --count`. Two failure modes make a charset check load-bearing:
+ *
+ *  1. OPTION-SHAPED values. `git rev-list` parses a leading-`-` token as an
+ *     OPTION, not a revision. `--glob=refs/heads/*` makes rev-list answer about
+ *     a completely different ref set and exit 0 with `0` — a silent WRONG
+ *     answer, not an error, so the sweep's conservative-on-error guard never
+ *     fires and every worktree is reported as a 0-ahead orphan.
+ *  2. RANGE-CORRUPTING values. A value containing `..` yields `a..b..branch`.
+ *
+ * No shell-out: `git check-ref-format --branch` is the semantic reference, but
+ * a config parser must stay a pure function. The charset + prefix/suffix rules
+ * below are a conservative SUBSET of what git accepts — a rejected value falls
+ * back to the `main` default rather than failing the parse, because a
+ * mistyped branch name must never escalate into a broken session config.
+ *
+ * @param {unknown} v
+ * @returns {boolean}
+ */
+export function _isSafeBaseBranch(v) {
+  if (typeof v !== 'string' || v.length === 0) return false;
+  // Rejects whitespace and every shell-ish character (= * ; | & $ ` ' " ( ) < >),
+  // which also rejects `--glob=refs/heads/*` on the `=` and `*` alone.
+  if (!BASE_BRANCH_CHARSET.test(v)) return false;
+  // The charset permits `-` so that `my-branch` works; a LEADING `-` is the
+  // option-shaped case and must be rejected explicitly.
+  if (v.startsWith('-')) return false;
+  // Would corrupt the `<base>..<branch>` range token at the sink.
+  if (v.includes('..')) return false;
+  // git check-ref-format: no leading/trailing `/` or `.`, no `.lock` suffix.
+  if (v.startsWith('/') || v.endsWith('/')) return false;
+  if (v.startsWith('.') || v.endsWith('.')) return false;
+  if (v.endsWith('.lock')) return false;
+  return true;
+}
+
+/**
+ * Parse the top-level `worktree-orphans:` YAML block from markdown content.
+ * Defaults: enabled=false, base-branch="main", mode="warn".
+ *
+ * @param {string} content — full file contents
+ * @returns {{enabled: boolean, 'base-branch': string, mode: string}}
+ */
+export function _parseWorktreeOrphans(content) {
+  const defaults = {
+    enabled: false,
+    'base-branch': 'main',
+    mode: 'warn',
+  };
+
+  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) {
+      // #830: bold-tolerant header match — never a hand-rolled regex.
+      if (matchBlockHeader(line, 'worktree-orphans')) inBlock = true;
+      continue;
+    }
+    if (line.length > 0 && !/^\s/.test(line)) break;
+    blockLines.push(line);
+  }
+
+  if (blockLines.length === 0) return defaults;
+
+  let woEnabled = false;
+  let woBaseBranch = 'main';
+  let woMode = 'warn';
+
+  for (const rawLine of blockLines) {
+    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 'enabled':
+        woEnabled = v.toLowerCase() === 'true';
+        break;
+      case 'base-branch':
+        // NOT "any non-empty scalar": an option-shaped or range-corrupting
+        // value is silently dropped in favour of the safe `main` default.
+        // See _isSafeBaseBranch() for why this is a security boundary.
+        if (_isSafeBaseBranch(v)) woBaseBranch = v;
+        break;
+      case 'mode':
+        if (['warn', 'off'].includes(v)) woMode = v;
+        break;
+    }
+  }
+
+  return { enabled: woEnabled, 'base-branch': woBaseBranch, mode: woMode };
+}

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

@@ -8,6 +8,9 @@
  *   drift-check.mjs       — _parseDriftCheck
  *   docs-orchestrator.mjs — _parseDocsOrchestrator
  *   vault-staleness.mjs   — _parseVaultStaleness
+ *   moc-staleness.mjs     — _parseMocStaleness
+ *   context-coverage.mjs  — _parseContextCoverage
+ *   worktree-orphans.mjs  — _parseWorktreeOrphans
  *   events-rotation.mjs   — _parseEventsRotation
  *   vault-integration.mjs — _parseVaultIntegration + _parseResourceThresholds
  *
@@ -38,6 +41,9 @@ import { _parseDriftCheck } from './config/drift-check.mjs';
 import { _parseDocsOrchestrator } from './config/docs-orchestrator.mjs';
 import { _parseVaultStaleness } from './config/vault-staleness.mjs';
 import { _parseDocsStaleness } from './config/docs-staleness.mjs';
+import { _parseMocStaleness } from './config/moc-staleness.mjs';
+import { _parseContextCoverage } from './config/context-coverage.mjs';
+import { _parseWorktreeOrphans } from './config/worktree-orphans.mjs';
 import { _parseEventsRotation } from './config/events-rotation.mjs';
 import { _parseVaultIntegration, _parseResourceThresholds } from './config/vault-integration.mjs';
 import { _parseTest } from './config/test.mjs';
@@ -50,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';
@@ -189,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);
@@ -206,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');
@@ -262,6 +276,12 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
   const vaultStaleness = _parseVaultStaleness(mdContent);
   // docs-staleness: parsed from full content (standalone top-level block, #781)
   const docsStaleness = _parseDocsStaleness(mdContent);
+  // moc-staleness: parsed from full content (standalone top-level block, #831/B2)
+  const mocStaleness = _parseMocStaleness(mdContent);
+  // context-coverage: parsed from full content (standalone top-level block, #831/B4)
+  const contextCoverage = _parseContextCoverage(mdContent);
+  // worktree-orphans: parsed from full content (standalone top-level block, #831/B5)
+  const worktreeOrphans = _parseWorktreeOrphans(mdContent);
 
   // events-rotation: parsed from full content (standalone top-level block)
   const eventsRotation = _parseEventsRotation(mdContent);
@@ -284,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);
 
@@ -425,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,
@@ -433,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,
@@ -449,6 +478,9 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
     'docs-orchestrator': docsOrchestrator,
     'vault-staleness': vaultStaleness,
     'docs-staleness': docsStaleness,
+    'moc-staleness': mocStaleness,
+    'context-coverage': contextCoverage,
+    'worktree-orphans': worktreeOrphans,
     'events-rotation': eventsRotation,
     'test': testConfig,
     'gitlab-portfolio': gitlabPortfolio,

package/scripts/lib/context-coverage-banner.mjs

@@ -0,0 +1,223 @@
+/**
+ * context-coverage-banner.mjs — Session-start banner for issue #831 (building
+ * block B4).
+ *
+ * Surfaces a `warn` banner during session-start Phase 4 when a REGISTERED
+ * vault project — a `<vaultDir>/01-projects/<slug>/` directory that contains
+ * an `_overview.md` — has neither a `context.md` nor a `_passive.md` file. A
+ * manual audit found 11 such gap folders in one vault; this probe makes the
+ * gap mechanically visible at session-start instead of relying on manual
+ * sweeps.
+ *
+ * "Registered" is deliberately NOT reinvented here. `discoverVaultRepos()`
+ * (`scripts/lib/gitlab-portfolio/vcs-detect.mjs`) already establishes the
+ * exact convention this probe reuses: a `01-projects/<slug>/` directory
+ * without an `_overview.md` is silently skipped — it is not a project, and
+ * therefore it can never be a "gap".
+ *
+ * Design notes:
+ *  - Mirrors the contract used by every other Phase 4 banner
+ *    (`scripts/lib/vault-staleness-banner.mjs`, `scripts/lib/loop-readiness-banner.mjs`,
+ *    `scripts/lib/reconcile-nudge-banner.mjs`): a single `checkXxx()` entry
+ *    point that returns `null` (silent no-op) or `{ severity, message, ... }`
+ *    — never an array, never `undefined`, never a throw.
+ *  - Synchronous — the probe only touches `existsSync`/`readdirSync`/`statSync`,
+ *    so unlike the async peer-cards/reconcile-nudge probes this one needs no
+ *    `await` at the call site (mirrors `checkLoopReadiness`).
+ *  - Never throws. Wrapped in an outermost defensive `try/catch`; every
+ *    individually-fallible filesystem call additionally gets its own inner
+ *    bare (no-binding) catch with a one-line explanatory comment.
+ *  - `vault-dir` resolution mirrors the host-local-override pattern used
+ *    throughout the plugin (issue #653): an injected `opts.vaultDir` test
+ *    seam wins, then `config['vault-integration']['vault-dir']`, else the
+ *    probe silently no-ops (no vault configured — nothing to check).
+ *  - The committed repo default for `vault-integration.vault-dir` is
+ *    tilde-prefixed (`~/Projects/vault`) and is NOT pre-expanded anywhere
+ *    upstream of this module — `expandTilde()` from `./common.mjs` is applied
+ *    unconditionally before the first `path.join`, exactly as
+ *    `discoverVaultRepos()` does inline for the same reason.
+ *
+ * Cross-references:
+ *  - `scripts/lib/gitlab-portfolio/vcs-detect.mjs` (`discoverVaultRepos`) —
+ *    the canonical "registered" definition this probe reuses.
+ *  - `scripts/lib/config/context-coverage.mjs` (`_parseContextCoverage`) —
+ *    the `context-coverage:` Session Config block parser. NOT wired into
+ *    `scripts/lib/config.mjs` by this module — the coordinator registers it
+ *    separately. The exact lines to add there:
+ *
+ *      import { _parseContextCoverage } from './config/context-coverage.mjs';
+ *      // ... later, alongside the other top-level block parses:
+ *      const contextCoverage = _parseContextCoverage(mdContent);
+ *      // ... in the returned config object:
+ *      'context-coverage': contextCoverage,
+ *
+ *  - `skills/session-start/SKILL.md` Phase 4 — banner render site (wiring
+ *    snippet supplied separately; this module does not edit that file).
+ *  - Issue #831 (building block B4).
+ */
+
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+
+import { expandTilde } from './common.mjs';
+
+/** Vault-relative projects directory (mirrors discoverVaultRepos()'s own constant). */
+const PROJECTS_SUBDIR = '01-projects';
+
+/** File marking a `01-projects/<slug>/` directory as REGISTERED (discoverVaultRepos() convention). */
+const OVERVIEW_FILE = '_overview.md';
+
+/** Either file's presence satisfies "coverage" for a registered project. */
+const COVERAGE_FILES = ['context.md', '_passive.md'];
+
+/**
+ * Above this many gap slugs, the message truncates the name list and says so
+ * explicitly rather than silently dropping names past the limit.
+ */
+const MAX_GAP_NAMES_IN_MESSAGE = 20;
+
+/**
+ * Resolve the vault directory to scan.
+ *
+ * Precedence: `opts.vaultDir` (test seam) > `config['vault-integration']['vault-dir']` > null.
+ *
+ * @param {string|undefined} vaultDir
+ * @param {unknown} config
+ * @returns {string|null} raw (not-yet-tilde-expanded) vault dir, or null when unresolvable
+ */
+function _resolveRawVaultDir(vaultDir, config) {
+  if (typeof vaultDir === 'string' && vaultDir.length > 0) return vaultDir;
+
+  if (config && typeof config === 'object') {
+    const vaultIntegration = /** @type {Record<string, unknown>} */ (config)['vault-integration'];
+    if (vaultIntegration && typeof vaultIntegration === 'object') {
+      const raw = /** @type {Record<string, unknown>} */ (vaultIntegration)['vault-dir'];
+      if (typeof raw === 'string' && raw.length > 0) return raw;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Format the gap-slug list for the banner message, truncating (with an
+ * explicit note) past `MAX_GAP_NAMES_IN_MESSAGE`.
+ *
+ * @param {string[]} slugs
+ * @returns {string}
+ */
+function _formatGapNames(slugs) {
+  if (slugs.length <= MAX_GAP_NAMES_IN_MESSAGE) return slugs.join(', ');
+  const shown = slugs.slice(0, MAX_GAP_NAMES_IN_MESSAGE).join(', ');
+  const hiddenCount = slugs.length - MAX_GAP_NAMES_IN_MESSAGE;
+  return `${shown}, and ${hiddenCount} more (name list truncated)`;
+}
+
+/**
+ * Check context-coverage and produce a session-start banner.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.repoRoot] — REQUIRED absolute path to the repo root.
+ * @param {string} [opts.vaultDir] — test seam; overrides the config-resolved vault dir.
+ * @param {object} [opts.config] — optional already-parsed Session Config (avoids
+ *   a second CLAUDE.md (or AGENTS.md on Codex CLI) read; caller passes `$CONFIG`, mirrors `checkReconcileNudge`).
+ *   Read keys: `config['context-coverage']` (`.enabled`, `.mode`) and
+ *   `config['vault-integration']['vault-dir']`.
+ * @returns {null | {severity: 'warn', message: string, gaps: Array<{slug: string}>, registered: number, covered: number}}
+ */
+export function checkContextCoverage({ repoRoot, vaultDir, config } = {}) {
+  try {
+    if (!repoRoot || typeof repoRoot !== 'string') return null;
+
+    const cfg =
+      config &&
+      typeof config === 'object' &&
+      config['context-coverage'] &&
+      typeof config['context-coverage'] === 'object'
+        ? config['context-coverage']
+        : {};
+
+    // Config gate — returns null BEFORE any filesystem I/O. Explicit opt-in
+    // required: `cfg.enabled` must be the literal `true`, not merely
+    // truthy/absent. A config block that is entirely absent (or present
+    // without an `enabled` key) must fail CLOSED, not open — see issue #831
+    // fail-open regression (a config carrying `vault-integration.vault-dir`
+    // but no `context-coverage` block previously ran the probe unsolicited,
+    // because `undefined !== false`).
+    if (cfg?.enabled !== true || cfg?.mode === 'off') return null;
+
+    const rawVaultDir = _resolveRawVaultDir(vaultDir, config);
+    if (!rawVaultDir) return null;
+
+    const resolvedVaultDir = expandTilde(rawVaultDir);
+    const projectsDir = path.join(resolvedVaultDir, PROJECTS_SUBDIR);
+
+    let entries;
+    try {
+      entries = readdirSync(projectsDir);
+    } catch {
+      return null;
+    }
+    if (!Array.isArray(entries) || entries.length === 0) return null;
+
+    entries = [...entries].sort();
+
+    let registered = 0;
+    const gaps = [];
+
+    for (const entry of entries) {
+      if (typeof entry !== 'string' || entry.startsWith('.')) continue;
+
+      const entryPath = path.join(projectsDir, entry);
+
+      let stat;
+      try {
+        stat = statSync(entryPath);
+      } catch {
+        continue;
+      }
+      if (!stat || !stat.isDirectory()) continue;
+
+      // "Registered" is defined ELSEWHERE (discoverVaultRepos()) — a
+      // directory lacking `_overview.md` is not a project, and therefore not
+      // a gap. Do not invent a second definition here.
+      let hasOverview = false;
+      try {
+        hasOverview = existsSync(path.join(entryPath, OVERVIEW_FILE));
+      } catch {
+        // best-effort — treat an unreadable path as "no _overview.md".
+      }
+      if (!hasOverview) continue;
+
+      registered += 1;
+
+      let isCovered = false;
+      for (const file of COVERAGE_FILES) {
+        try {
+          if (existsSync(path.join(entryPath, file))) {
+            isCovered = true;
+            break;
+          }
+        } catch {
+          // best-effort — treat an unreadable path as "not covered by this file".
+        }
+      }
+
+      if (!isCovered) gaps.push({ slug: entry });
+    }
+
+    if (registered === 0 || gaps.length === 0) return null;
+
+    const covered = registered - gaps.length;
+    const gapSlugs = gaps.map((g) => g.slug);
+
+    const finding = `${gaps.length} of ${registered} registered projects lack context.md and _passive.md`;
+    const remediation = 'add a context.md or mark the project passive with _passive.md.';
+    const message = `⚠ context-coverage: ${finding} — ${_formatGapNames(gapSlugs)} — ${remediation}`;
+
+    return { severity: 'warn', message, gaps, registered, covered };
+  } catch {
+    // Defensive catch-all — banner must never throw.
+    return null;
+  }
+}

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 };