session-orchestrator 5.1.0 → 5.3.0

package/scripts/lib/config/reaper.mjs

@@ -0,0 +1,162 @@
+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.mjs`; these
+ * literals mirror it deliberately rather than importing it, because that module
+ * pulls `process-group.mjs` + `resource-probe/parsers.mjs` into the config
+ * import graph, which every `parseSessionConfig()` caller would then pay for.
+ * 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 `dispatch-common.mjs:61`; 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.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';
@@ -417,6 +419,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);
 
@@ -555,6 +567,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

@@ -45,7 +45,7 @@
 
 import { existsSync, statSync, openSync, readSync, closeSync } from 'node:fs';
 import { join } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { isMainModule } from './is-main-module.mjs';
 
 const DEFAULT_INTERVAL_S = 2;
 const EVENTS_FILE_REL = '.orchestrator/metrics/events.jsonl';
@@ -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} */
@@ -502,7 +565,7 @@ function 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) {
+if (isMainModule(import.meta.url)) {
   main();
 }
 

package/scripts/lib/cursor-hook-bridge.mjs

@@ -18,10 +18,10 @@
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
 
 import { matcherMatches, readHookDecision } from './pi-hook-bridge.mjs';
 import { resolvePluginRoot } from './plugin-root.mjs';
+import { isMainModule } from './is-main-module.mjs';
 
 export const CURSOR_TO_CANONICAL_EVENT = Object.freeze({
   sessionStart: 'SessionStart',
@@ -434,7 +434,7 @@ async function main() {
   process.stdout.write(`${JSON.stringify(toCursorHookOutput(eventName, result))}\n`);
 }
 
-const isMain = process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
+const isMain =isMainModule(import.meta.url);
 if (isMain) {
   main().catch((err) => {
     process.stderr.write(`cursor-hook-bridge: ${err instanceof Error ? err.message : err}\n`);

package/scripts/lib/description-surface.mjs

@@ -58,6 +58,7 @@
 import { readdirSync, readFileSync, statSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { join, relative, resolve } from 'node:path';
+import { isMainModule } from './is-main-module.mjs';
 
 /** Block-scalar indicator on the `description:` line: '>' (folded) or '|' (literal), optional chomping '+'/'-'. */
 const BLOCK_SCALAR_RE = /^([>|])([+-]?)\s*$/;
@@ -526,10 +527,6 @@ function main() {
 }
 
 const __filename = fileURLToPath(import.meta.url);
-const isMain =
-  typeof process !== 'undefined' &&
-  process.argv[1] !== null &&
-  process.argv[1] !== undefined &&
-  resolve(process.argv[1]) === resolve(__filename);
+const isMain =isMainModule(import.meta.url);
 
 if (isMain) main();

package/scripts/lib/dispatcher/cli.mjs

@@ -32,6 +32,7 @@ import { warn } from '../common.mjs';
 import { acquire } from '../session-lock.mjs';
 import { enumerateCandidates, freeCandidates } from './enumerate.mjs';
 import { rankCandidates } from './rank.mjs';
+import { isMainModule } from '../is-main-module.mjs';
 
 const VERSION = '1.0.0';
 
@@ -247,7 +248,7 @@ export async function main(argv) {
 }
 
 // Run main only when executed directly, never on import.
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isMainModule(import.meta.url)) {
   main(process.argv.slice(2))
     .then((code) => process.exit(code))
     .catch((err) => {

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

package/scripts/lib/ecosystem-wizard.mjs

@@ -7,6 +7,7 @@
  */
 
 import { runEcosystemWizard } from './ecosystem-wizard/wizard-prompt.mjs';
+import { isMainModule } from './is-main-module.mjs';
 
 export { detectCiProvider } from './ecosystem-wizard/ci-detector.mjs';
 export {
@@ -31,7 +32,7 @@ export { runEcosystemWizard } from './ecosystem-wizard/wizard-prompt.mjs';
 // CLI entry
 // ---------------------------------------------------------------------------
 
-if (process.argv[1] && process.argv[1].endsWith('ecosystem-wizard.mjs')) {
+if (isMainModule(import.meta.url)) {
   const args = process.argv.slice(2);
   const repoRootIdx = args.indexOf('--repo-root');
   const dryRun = args.includes('--dry-run');