session-orchestrator 5.2.0 → 5.4.0

package/scripts/lib/config/reaper.mjs

@@ -0,0 +1,163 @@
+import { matchBlockHeader } from './block-header.mjs';
+import { preprocessBlockLines } from './block-preprocess.mjs';
+
+/**
+ * reaper.mjs — Parser for the top-level `reaper:` YAML block
+ * (PRD `docs/prd/2026-09-20-prozessgruppen-kill-und-waisen-waechter.md` §4,
+ * Epic #1425 / issue #1432 B4).
+ *
+ * Configures the orphan watchdog that `hooks/post-tool-batch-wave-signal.mjs`
+ * (PostToolBatch) and `hooks/on-stop.mjs` (Stop + SubagentStop) trigger as a
+ * detached fire-and-forget scan. The scan itself lives in
+ * `scripts/lib/orphan-reaper.mjs`; this module only reads the numbers.
+ *
+ * DEFAULT OFF. `enabled` defaults to `false` — unlike `loop-guard`, this signal
+ * can SEND SIGNALS to processes, so it ships inert and is armed per repo only
+ * after its firing rate has been measured (`.claude/rules/host-resources.md`
+ * HR-101: a class above ~10 % is a broken instrument; HR-105: a rule nothing
+ * records is unfalsifiable).
+ *
+ * Tolerant parser: malformed values silently fall back to defaults.
+ *
+ * Returns `{ enabled, mode, 'min-age-seconds', 'min-scan-interval-seconds',
+ * 'kill-grace-ms', 'verify-wait-ms', 'max-hook-latency-ms', 'false-alarm-window' }`.
+ */
+
+/**
+ * Startwerte für Stufe 1 — NOT calibrated. Every number carries its provenance
+ * from the PRD §4 parameter table ("keine Zahl ohne ihre Population").
+ *
+ * RUNTIME SSOT is `REAPER_DEFAULTS` in `scripts/lib/orphan-reaper/defaults.mjs`; these
+ * literals mirror it rather than importing it. The original reason — the
+ * single-file `orphan-reaper.mjs` pulled `process-group.mjs` +
+ * `resource-probe/parsers.mjs` into the config import graph — no longer holds
+ * since the #1437 split (`defaults.mjs` imports only `node:path`); revisit the
+ * mirror there. The parity is held by a test, not by an import
+ * (`tests/lib/config/reaper.test.mjs` § defaults mirror REAPER_DEFAULTS).
+ */
+/** 300 s — DevWatchdog's hard limit for `tsgo`; the 2026-09-20 orphans were 7–17 min old. */
+const DEFAULT_MIN_AGE_SECONDS = 300;
+/** 30 s — DevWatchdog's normal scan cadence; keeps a PostToolBatch storm from taxing every tool call. */
+const DEFAULT_MIN_SCAN_INTERVAL_SECONDS = 30;
+/** 10 000 ms — `DEFAULT_KILL_GRACE_MS` from `process-group.mjs`; repo convention, not newly invented. */
+const DEFAULT_KILL_GRACE_MS = 10_000;
+/** 500 ms — wait before reading the effect back; without it the 2026-09-20 check falsely reported "still alive". */
+const DEFAULT_VERIFY_WAIT_MS = 500;
+/** 50 ms — ceiling a scan may delay a hook by; above that the scan counts as too expensive. */
+const DEFAULT_MAX_HOOK_LATENCY_MS = 50;
+/** 50 decisions — rolling window over the JSONL audit (B5), so the rate has a population on quiet hosts too. */
+const DEFAULT_FALSE_ALARM_WINDOW = 50;
+
+/** `report` = decide + audit only (dryRun); `kill` = send signals (PRD Stufe 2, after calibration). */
+const MODE_VALUES = new Set(['report', 'kill']);
+const DEFAULT_MODE = 'report';
+
+/**
+ * Coerce a raw string into a finite integer >= `min`, else `fallback`.
+ *
+ * @param {string} raw
+ * @param {number} fallback
+ * @param {number} min
+ * @returns {number}
+ */
+function parseBoundedInt(raw, fallback, min) {
+  if (!/^-?\d+$/.test(raw)) return fallback;
+  const n = Number.parseInt(raw, 10);
+  if (!Number.isFinite(n) || n < min) return fallback;
+  return n;
+}
+
+/**
+ * Parse the top-level `reaper:` YAML block from markdown content.
+ * Independent of the `## Session Config` section boundary.
+ *
+ * @param {string} content — full file contents
+ * @returns {{enabled: boolean, mode: string, 'min-age-seconds': number,
+ *   'min-scan-interval-seconds': number, 'kill-grace-ms': number,
+ *   'verify-wait-ms': number, 'max-hook-latency-ms': number,
+ *   'false-alarm-window': number}}
+ */
+export function _parseReaper(content) {
+  let enabled = false;
+  let mode = DEFAULT_MODE;
+  let minAgeSeconds = DEFAULT_MIN_AGE_SECONDS;
+  let minScanIntervalSeconds = DEFAULT_MIN_SCAN_INTERVAL_SECONDS;
+  let killGraceMs = DEFAULT_KILL_GRACE_MS;
+  let verifyWaitMs = DEFAULT_VERIFY_WAIT_MS;
+  let maxHookLatencyMs = DEFAULT_MAX_HOOK_LATENCY_MS;
+  let falseAlarmWindow = DEFAULT_FALSE_ALARM_WINDOW;
+
+  const lines = preprocessBlockLines(content);
+  let inBlock = false;
+  const blockLines = [];
+
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/\r$/, '');
+    if (!inBlock) {
+      if (matchBlockHeader(line, 'reaper')) inBlock = true;
+      continue;
+    }
+    if (line.length > 0 && !/^\s/.test(line)) break;
+    blockLines.push(line);
+  }
+
+  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':
+        // Default is false → only an explicit "true" arms the watchdog.
+        enabled = v.toLowerCase() === 'true';
+        break;
+      case 'mode':
+        // An unknown mode falls back to the INERT one — never to `kill`.
+        mode = MODE_VALUES.has(v.toLowerCase()) ? v.toLowerCase() : DEFAULT_MODE;
+        break;
+      case 'min-age-seconds':
+        minAgeSeconds = parseBoundedInt(v, DEFAULT_MIN_AGE_SECONDS, 0);
+        break;
+      case 'min-scan-interval-seconds':
+        minScanIntervalSeconds = parseBoundedInt(v, DEFAULT_MIN_SCAN_INTERVAL_SECONDS, 1);
+        break;
+      case 'kill-grace-ms':
+        killGraceMs = parseBoundedInt(v, DEFAULT_KILL_GRACE_MS, 0);
+        break;
+      case 'verify-wait-ms':
+        verifyWaitMs = parseBoundedInt(v, DEFAULT_VERIFY_WAIT_MS, 0);
+        break;
+      case 'max-hook-latency-ms':
+        maxHookLatencyMs = parseBoundedInt(v, DEFAULT_MAX_HOOK_LATENCY_MS, 1);
+        break;
+      case 'false-alarm-window':
+        falseAlarmWindow = parseBoundedInt(v, DEFAULT_FALSE_ALARM_WINDOW, 1);
+        break;
+    }
+  }
+
+  // Self-healing clamp: a `min-age-seconds` below the scan interval is dead
+  // config — a process younger than one scan period can be born and reaped
+  // between two scans, so the watchdog would fire on processes it has never
+  // seen before. Widen the age floor to at least one scan period (the same
+  // shape as loop-guard's window >= threshold clamp).
+  if (minAgeSeconds < minScanIntervalSeconds) minAgeSeconds = minScanIntervalSeconds;
+
+  return {
+    enabled,
+    mode,
+    'min-age-seconds': minAgeSeconds,
+    'min-scan-interval-seconds': minScanIntervalSeconds,
+    'kill-grace-ms': killGraceMs,
+    'verify-wait-ms': verifyWaitMs,
+    'max-hook-latency-ms': maxHookLatencyMs,
+    'false-alarm-window': falseAlarmWindow,
+  };
+}

package/scripts/lib/config-schema.mjs

@@ -120,6 +120,19 @@ export function validateSessionConfig(config) {
     }
   }
 
+  // #1465 cross-field: offload-first with no declared host can never place a
+  // wave anywhere — advisory (warn-level), it never flips `ok`.
+  if (config['offload-first'] === true) {
+    const hosts = config['remote-hosts'];
+    if (!Array.isArray(hosts) || hosts.length === 0) {
+      warnings.push({
+        path: 'remote-hosts',
+        rule: 'offload-first-cross-field',
+        message: 'offload-first: true but no remote-hosts declared — every wave stays local',
+      });
+    }
+  }
+
   if (errors.length > 0) {
     return { ok: false, errors, warnings };
   }

package/scripts/lib/config.mjs

@@ -65,6 +65,8 @@ import { _parseHealthEndpoints, _parseEcosystemHealthBlockEnabled } from './conf
 import { _parseBrokenWindow } from './config/broken-window.mjs';
 import { _parseSlopcheck } from './config/slopcheck.mjs';
 import { _parseDiscoveryValidator } from './config/discovery-validator.mjs';
+import { _parseReaper } from './config/reaper.mjs';
+import { _parseGate } from './config/gate.mjs';
 import { _parseTemplatesFirst } from './config/templates-first.mjs';
 import { _parseVerificationAutoFix } from './config/verification-auto-fix.mjs';
 import { _parseDialectic } from './config/dialectic.mjs';
@@ -76,8 +78,57 @@ import { _parseRemoteHosts } from './config/remote-hosts.mjs';
 import { _parseEvolve, _parseEvolveDecay } from './config/evolve.mjs';
 import { _parseSkillEvolution } from './config/skill-evolution.mjs';
 import { _parseDispatcherAutonomy, resolveDispatcherAutonomy } from './config/dispatcher-autonomy.mjs';
-import { loadHostPaths, resolveHostPath } from './config/host-paths.mjs';
+import { loadHostPaths, resolveHostPath, resolveVaultIntegrationHost } from './config/host-paths.mjs';
 import { resolveNamedBaseline } from './named-baseline-resolver.mjs';
+import { expandTilde } from './common.mjs';
+
+/**
+ * Resolve `vault-dir` and report which tier produced it (agents/vault#319).
+ *
+ * Precedence (highest first): SO_VAULT_DIR env > owner.yaml `vault-dirs:`
+ * path-prefix match against the cwd > owner.yaml `paths.vault-dir` > committed.
+ * The env tier stays on top because tests/setup/vault-guard.mjs relies on it to
+ * shadow every host-local vault for the whole suite.
+ *
+ * Lives here, not in config/host-paths.mjs: host-paths.mjs is a direct CP11
+ * helper of check-owner-leakage.mjs, whose standalone vendored copy carries only
+ * its three direct helpers. The named-baseline-resolver import edge would make
+ * CP11 fail closed there (tests/husky/pre-commit-owner-leakage.test.mjs).
+ *
+ * The two owner.yaml tiers (`match`, `owner`) come back tilde-expanded: owner.yaml
+ * is host-local and `~/…` is the natural way to write a path there, but consumers
+ * such as vault-mirror.mjs `existsSync(resolve(vaultDir))` would read a literal
+ * `~` as `<cwd>/~/…`. The `env` and `committed` tiers keep their pass-through;
+ * vault-mirror.mjs expands its `--vault-dir` at entry for every tier anyway.
+ *
+ * `cwd` in the ctx is a test-only DI seam; production reads `process.cwd()`.
+ *
+ * @param {string|null|undefined} committed — value the committed Session Config produced
+ * @param {{ env?: Record<string, string|undefined>, ownerConfig?: object, cwd?: string }} [ctx] — from loadHostPaths()
+ * @returns {{ value: string|null|undefined, source: 'env'|'match'|'owner'|'committed' }}
+ */
+function resolveVaultDir(committed, { env = process.env, ownerConfig, cwd } = {}) {
+  const isNonBlank = (v) => typeof v === 'string' && v.trim() !== '';
+
+  const envVal = env?.SO_VAULT_DIR;
+  if (isNonBlank(envVal)) return { value: envVal, source: 'env' };
+
+  const matched = resolveNamedBaseline({
+    cwd: cwd ?? process.cwd(),
+    ownerConfig,
+    env,
+    section: 'vault-dirs',
+    envKey: 'SO_VAULT_DIR',
+  });
+  if (matched.source === 'match' && isNonBlank(matched.path)) {
+    return { value: expandTilde(matched.path), source: 'match' };
+  }
+
+  const ownerVal = ownerConfig?.paths?.['vault-dir'];
+  if (isNonBlank(ownerVal)) return { value: expandTilde(ownerVal), source: 'owner' };
+
+  return { value: committed, source: 'committed' };
+}
 // express-path lives one level UP from config/ (see its module header for why):
 // the parser is a sibling of config/state-md-lock.mjs in every respect except
 // its directory. Only the pure parser is imported here — `evaluateExpressPath`
@@ -112,8 +163,9 @@ export { readConfigFile } from './config/io.mjs';
  *   hermetic ctx (e.g. `{ env: {}, ownerConfig: undefined }`) when asserting COMMITTED values:
  *   the default reads the real `owner.yaml`, so a host-local `paths:` override would otherwise
  *   bleed into fixture assertions (incident: 2026-07-03 Full-Gate red after the operator set
- *   `paths.baseline-path` host-locally). `cwd` feeds the `baselines:` match tier (#819) — a
- *   test-only DI seam; production always resolves it from `process.cwd()`.
+ *   `paths.baseline-path` host-locally). `cwd` feeds the `baselines:` (#819) and
+ *   `vault-dirs:` (agents/vault#319) match tiers — a test-only DI seam; production
+ *   always resolves it from `process.cwd()`.
  * @returns {object} config object with EXACT same shape as parse-config.sh stdout
  * @throws if any enum value is invalid
  */
@@ -228,6 +280,9 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
   // 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);
+  // offload-first (#1465): route offloadable wave roles to a ready remote host
+  // even on a `proceed` resource verdict (consumed by wave-resource-gate.mjs).
+  const offloadFirst = _coerceBoolean(kv, 'offload-first', false);
 
   // List fields
   const crossRepos = _coerceList(kv, 'cross-repos', undefined);
@@ -329,18 +384,25 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
   // vault-integration: parsed from full content (block-scoped, avoids the
   // pre-#593 KV-name collision where `enabled:` was shared with 15+ other
   // blocks like docs-orchestrator/vault-staleness/slopcheck).
-  const vaultIntegration = _parseVaultIntegration(mdContent);
-  // Host-local override (issue #653) — applied here, NOT inside _parseVaultIntegration,
-  // so claude-md-drift-check (which calls the parser directly) keeps seeing raw values.
-  vaultIntegration['vault-dir'] = resolveHostPath('vault-dir', vaultIntegration['vault-dir'], hostCtx);
+  // Host-local overrides — applied here, NOT inside _parseVaultIntegration, so
+  // claude-md-drift-check (which calls the parser directly) keeps seeing raw values.
+  //   - the enabled/mode switch (SO#1448): env SO_VAULT_INTEGRATION > owner.yaml
+  //     `vault-integration:` > committed, LOWER-ONLY; `host-override` names the tier.
+  //   - vault-dir (#653, agents/vault#319): env > owner.yaml `vault-dirs:` cwd match >
+  //     owner.yaml paths.vault-dir > committed; `vault-dir-source` names the tier.
+  const vaultIntegration = resolveVaultIntegrationHost(_parseVaultIntegration(mdContent), hostCtx);
+  const vaultIntegrationDir = resolveVaultDir(vaultIntegration['vault-dir'], hostCtx);
+  vaultIntegration['vault-dir'] = vaultIntegrationDir.value;
+  vaultIntegration['vault-dir-source'] = vaultIntegrationDir.source;
 
   // resource-thresholds sub-keys (v3.1.0 env-aware — issue #166)
   const resourceThresholds = _parseResourceThresholds(kv);
 
   // vault-sync: parsed from full content (can live outside Session Config)
   const vaultSync = _parseVaultSync(mdContent);
-  // Host-local override (issue #653) — same host source as vault-integration above.
-  vaultSync['vault-dir'] = resolveHostPath('vault-dir', vaultSync['vault-dir'], hostCtx);
+  // Host-local override (issue #653) — same resolver as vault-integration above, so the
+  // two blocks cannot disagree about which vault this repo writes to (agents/vault#319).
+  vaultSync['vault-dir'] = resolveVaultDir(vaultSync['vault-dir'], hostCtx).value;
 
   // drift-check: parsed from full content (standalone top-level block)
   const driftCheck = _parseDriftCheck(mdContent);
@@ -406,7 +468,7 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
   // dispatcher-autonomy: opt-in cross-repo dispatcher autonomy block (Epic #673 / issue #679).
   // Parser stays pure (raw committed value) for claude-md-drift-check raw-value parity;
   // the host-local override (env > owner.yaml > committed > off) is overlaid onto the
-  // FINAL object only — mirroring the vault-dir resolveHostPath pattern above. Reuses the
+  // FINAL object only — mirroring the vault-dir host-override pattern above. Reuses the
   // already-loaded hostCtx.ownerConfig so owner.yaml is not read twice.
   const dispatcherAutonomy = _parseDispatcherAutonomy(mdContent);
   dispatcherAutonomy.autonomy = resolveDispatcherAutonomy({
@@ -417,6 +479,16 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
   // discovery-validator: parsed from full content (PSA-006 enforcement / issue #567)
   const discoveryValidator = _parseDiscoveryValidator(mdContent);
 
+  // reaper: orphan-process watchdog, default OFF (PRD 2026-09-20 Prozessgruppen-Kill
+  // und Waisen-Wächter, Epic #1425 / #1432 B4). Consumed by the two hooks that
+  // trigger the detached scan — post-tool-batch-wave-signal.mjs and on-stop.mjs.
+  const reaper = _parseReaper(mdContent);
+
+  // gate: wall-clock ceiling for gate path B (run-quality-gate.mjs →
+  // gate-*.mjs), which had no timeout at all before #1425 A3. The operator
+  // override SO_GATE_TIMEOUT_MS still wins over this committed value.
+  const gate = _parseGate(mdContent);
+
   // templates-first: parsed from full content (PRD gsd Pattern 3 / issues #517, #519)
   const templatesFirst = _parseTemplatesFirst(mdContent);
 
@@ -540,6 +612,7 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
     'resource-awareness': resourceAwareness,
     'enable-host-banner': enableHostBanner,
     'heavy-repo': heavyRepo,
+    'offload-first': offloadFirst,
     'worktree-cleanup': worktreeCleanup,
     'resource-thresholds': resourceThresholds,
     'worktree-exclude': worktreeExclude,
@@ -555,6 +628,8 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
     'skill-evolution': skillEvolution,
     'dispatcher-autonomy': dispatcherAutonomy,
     'discovery-validator': discoveryValidator,
+    'reaper': reaper,
+    'gate': gate,
     'templates-first': templatesFirst,
     'verification-auto-fix': verificationAutoFix,
     'dialectic': dialectic,

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