session-orchestrator 3.24.0 → 4.0.0

package/scripts/lib/config/moc-staleness.mjs

@@ -1,4 +1,5 @@
 import { matchBlockHeader } from './block-header.mjs';
+import { preprocessBlockLines } from './block-preprocess.mjs';
 
 /**
  * moc-staleness.mjs — Parser for the top-level `moc-staleness:` YAML block.
@@ -31,7 +32,7 @@ export function _parseMocStaleness(content) {
     mode: 'warn',
   };
 
-  const lines = content.split(/\r?\n/);
+  const lines = preprocessBlockLines(content);
   let inBlock = false;
   const blockLines = [];
 

package/scripts/lib/config/persona-gate-wave.mjs

@@ -20,6 +20,7 @@
 import { parseThreshold } from '../persona-panel/threshold.mjs';
 import { ALLOWED_MODEL_ALIASES, MODEL_ID_RE } from '../agent-frontmatter.mjs';
 import { matchBlockHeader } from './block-header.mjs';
+import { preprocessBlockLines } from './block-preprocess.mjs';
 
 const ALLOWED_AFTER = new Set(['quality', 'impl-polish']);
 const ALLOWED_MODE = new Set(['off', 'warn', 'strict']);
@@ -169,7 +170,7 @@ export function _normalizePersonaGateWave(parsed) {
  * @returns {string[]}
  */
 function _extractBlock(content, key) {
-  const lines = content.split(/\r?\n/);
+  const lines = preprocessBlockLines(content);
   const blockLines = [];
   let inBlock = false;
 

package/scripts/lib/config/private-config-dir.mjs

@@ -0,0 +1,67 @@
+/**
+ * private-config-dir.mjs — THE resolver for the host-private config directory (#1223).
+ *
+ * Every per-host artefact below that directory (`host-private.json`,
+ * `owner.yaml`, the self-alias ledger) moves with it, so the precedence has to
+ * live in exactly ONE place. Before #1223 three copies with three different
+ * precedences existed: `owner-yaml.mjs`'s import-time homedir-only
+ * `OWNER_YAML_PATH`, `owner-config-loader.mjs`'s XDG-only + untrimmed
+ * `resolveOwnerConfigPath()`, and `host-identity.mjs`'s `_privateDir()`. The
+ * live consequence: `SO_CONFIG_HOME=<sandbox>` moved the alias ledger but NOT
+ * owner.yaml, which kept being read from the operator's REAL home — the
+ * CLAUDE.md (Codex CLI alias: AGENTS.md) "vault-dir resolves HOST-LOCALLY"
+ * hazard class.
+ *
+ * ── Why this is a standalone ZERO-IMPORT leaf ────────────────────────────────
+ *
+ * Two independent consumers constrain it, and neither tolerates the other's
+ * import graph:
+ *
+ *   1. `host-identity.mjs` is reachable from LIVE hooks (via `session-lock.mjs`),
+ *      `hooks/on-stop.mjs` among them. on-stop must degrade with one actionable
+ *      line when `node_modules` is absent (GH#63), so nothing on ITS subgraph —
+ *      this leaf included — may pull a bare specifier. Putting the resolver in
+ *      `owner-yaml.mjs` dragged `js-yaml` onto that subgraph and turned the GH#63
+ *      contract red with `ERR_MODULE_NOT_FOUND: Cannot find package 'js-yaml'`.
+ *      Since GitLab #1230 (2026-09-06) `owner-yaml.mjs` resolves `js-yaml`
+ *      lazily, so that particular collision can no longer recur — but the
+ *      constraint on THIS file is unchanged, because it is what let the resolver
+ *      be shared in the first place. Measured 2026-09-06 over a `hooks/` +
+ *      `scripts/` copy with no `node_modules`, the four hooks that reach
+ *      `owner-yaml.mjs` (on-session-start, on-session-end, post-edit-validate,
+ *      skill-invocation-telemetry) now load instead of throwing.
+ *   2. `tests/husky/pre-commit-owner-leakage.test.mjs` copies the CP11 scanner's
+ *      import chain FILE BY FILE into a tmp repo. Every repo-local import added
+ *      to a file on that chain must be added to the copied-file list there.
+ *
+ * Hence: `node:os` + `node:path` only. No repo-local imports, no bare
+ * specifiers beyond the two Node builtins.
+ */
+
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * Resolve the host-private config directory.
+ *
+ * Precedence, most specific first: `SO_CONFIG_HOME` names the private dir
+ * ITSELF; `XDG_CONFIG_HOME` names its PARENT (the `session-orchestrator`
+ * segment is appended); without either, `~/.config/session-orchestrator`.
+ *
+ * `.trim() || fallback` throughout — a whitespace-only env var is truthy and
+ * would short-circuit a bare `||`, returning the spaces verbatim
+ * (`.claude/rules/development.md` § Error Handling, env-var fallback
+ * whitespace trap).
+ *
+ * Reads env at CALL time, so a test may stub `process.env` after import.
+ *
+ * @param {{ env?: Record<string, string|undefined> }} [opts]
+ * @returns {string} absolute path to the host-private config directory
+ */
+export function resolvePrivateConfigDir({ env = process.env } = {}) {
+  const own = (env.SO_CONFIG_HOME || '').trim();
+  if (own) return own;
+  const xdg = (env.XDG_CONFIG_HOME || '').trim();
+  if (xdg) return join(xdg, 'session-orchestrator');
+  return join(homedir(), '.config', 'session-orchestrator');
+}

package/scripts/lib/config/reconcile.mjs

@@ -1,4 +1,5 @@
 import { matchBlockHeader } from './block-header.mjs';
+import { preprocessBlockLines } from './block-preprocess.mjs';
 
 /**
  * reconcile.mjs — Parser for the top-level `reconcile:` YAML block.
@@ -169,7 +170,7 @@ export function _parseReconcile(content) {
     'max-proposals-per-run': 10,
   };
 
-  const lines = content.split(/\r?\n/);
+  const lines = preprocessBlockLines(content);
   let inBlock = false;
   const blockLines = [];
 

package/scripts/lib/config/remote-hosts.mjs

@@ -1,4 +1,5 @@
 import { matchBlockHeader } from './block-header.mjs';
+import { preprocessBlockLinesNoDash } from './block-preprocess.mjs';
 
 /**
  * remote-hosts.mjs — Parser for the `remote-hosts:` Session Config block (#1160).
@@ -73,7 +74,7 @@ const SAFE_PATH_RE = /^[A-Za-z0-9._~/][A-Za-z0-9._~/-]*$/;
  * @returns {Array<{alias: string, 'roles-allowed': string[], 'repo-path': string|null, 'claude-path': string|null}>}
  */
 export function _parseRemoteHosts(content) {
-  const lines = String(content ?? '').split(/\r?\n/);
+  const lines = preprocessBlockLinesNoDash(String(content ?? ''));
   let inBlock = false;
   const blockLines = [];
 

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

@@ -214,10 +214,16 @@ function isCodeFence(line) {
  * this repo's own convention encourages. Revisit if a fleet CLAUDE.md is ever
  * measured opening a multi-line comment after a value.
  *
+ * EXPORTED since #1162 for a third consumer: `block-preprocess.mjs`, which
+ * gives the ~36 block parsers under `scripts/lib/config/` the same
+ * commented-out-is-not-live-config semantics. Same argument as the export of
+ * `isSessionConfigHeading` — a fourth copy of this state machine that drifts
+ * loose is worse than no check at all. Behaviour is unchanged by the export.
+ *
  * @returns {(line: string) => boolean} true when the line is inside (or opens)
  *   a multi-line HTML comment and must be ignored by both consumers.
  */
-function htmlCommentSkipper() {
+export function htmlCommentSkipper() {
   let inComment = false;
   return function skipHtmlComment(line) {
     if (inComment) {

package/scripts/lib/config/skill-evolution.mjs

@@ -1,4 +1,5 @@
 import { matchBlockHeader } from './block-header.mjs';
+import { preprocessBlockLines } from './block-preprocess.mjs';
 
 /**
  * skill-evolution.mjs — Parser for the top-level `skill-evolution:` YAML block
@@ -39,7 +40,7 @@ export function _parseSkillEvolution(content) {
     'judge-budget-tokens': 8000,
   };
 
-  const lines = content.split(/\r?\n/);
+  const lines = preprocessBlockLines(content);
   let inBlock = false;
   const blockLines = [];
 

package/scripts/lib/config/slopcheck.mjs

@@ -1,4 +1,5 @@
 import { matchBlockHeader } from './block-header.mjs';
+import { preprocessBlockLines } from './block-preprocess.mjs';
 
 /**
  * slopcheck.mjs — Parser for the top-level `slopcheck:` YAML block
@@ -36,7 +37,7 @@ export function _parseSlopcheck(content) {
     sources: [...DEFAULT_SOURCES],
   };
 
-  const lines = content.split(/\r?\n/);
+  const lines = preprocessBlockLines(content);
   let inBlock = false;
   const blockLines = [];
 

package/scripts/lib/config/state-md-lock.mjs

@@ -1,4 +1,5 @@
 import { matchBlockHeader } from './block-header.mjs';
+import { preprocessBlockLines } from './block-preprocess.mjs';
 
 /**
  * state-md-lock.mjs — Parser for the top-level `state-md-lock:` YAML block
@@ -30,7 +31,7 @@ export function _parseStateMdLock(content) {
     'timeout-ms': 10000,
   };
 
-  const lines = content.split(/\r?\n/);
+  const lines = preprocessBlockLines(content);
   let inBlock = false;
   const blockLines = [];
 

package/scripts/lib/config/templates-first.mjs

@@ -1,4 +1,5 @@
 import { matchBlockHeader } from './block-header.mjs';
+import { preprocessBlockLines } from './block-preprocess.mjs';
 
 /**
  * templates-first.mjs — Parser for the top-level `templates-first:` YAML block
@@ -34,7 +35,7 @@ export function _parseTemplatesFirst(content) {
     hosts: [...DEFAULT_HOSTS],
   };
 
-  const lines = content.split(/\r?\n/);
+  const lines = preprocessBlockLines(content);
   let inBlock = false;
   const blockLines = [];
 

package/scripts/lib/config/test.mjs

@@ -8,6 +8,7 @@
 
 import { validatePathInsideProject } from '../path-utils.mjs';
 import { matchBlockHeader } from './block-header.mjs';
+import { preprocessBlockLines } from './block-preprocess.mjs';
 
 /**
  * Parse the top-level `test:` YAML block from markdown content.
@@ -27,7 +28,7 @@ export function _parseTest(content) {
     'retention-days': 30,
   };
 
-  const lines = content.split(/\r?\n/);
+  const lines = preprocessBlockLines(content);
   let inBlock = false;
   const blockLines = [];
 

package/scripts/lib/config/vault-integration.mjs

@@ -22,6 +22,7 @@
 
 import { _coerceBoolean, _coerceInteger } from './coercers.mjs';
 import { matchBlockHeader } from './block-header.mjs';
+import { preprocessBlockLines } from './block-preprocess.mjs';
 
 // ---------------------------------------------------------------------------
 // vault-integration
@@ -68,7 +69,12 @@ export function _parseVaultIntegration(content) {
   const defaults = { enabled: false, 'vault-dir': null, mode: 'warn', 'vault-name': null };
   if (typeof content !== 'string' || content === '') return defaults;
 
-  const lines = content.split(/\r?\n/);
+  // #1162: NOT a raw split. `preprocessBlockLines` drops HTML-commented lines
+  // (a commented-out block was read as live config) and rewrites bold-bullet
+  // sub-keys (`- **enabled:** true` fell back to the `false` default). This
+  // parser has no dash-RECORD body, so the bold pass is safe here — see the
+  // named risk in block-preprocess.mjs.
+  const lines = preprocessBlockLines(content);
 
   // Pass 1: inline-object form. Matches `vault-integration: { ... }` with or
   // without a leading `- ` (baseline list-item form per #497).

package/scripts/lib/config/vault-mirror-quality.mjs

@@ -1,4 +1,5 @@
 import { matchBlockHeader } from './block-header.mjs';
+import { preprocessBlockLines } from './block-preprocess.mjs';
 
 /**
  * vault-mirror-quality.mjs — Parser for the top-level `vault-mirror:` YAML block,
@@ -30,7 +31,7 @@ export function _parseVaultMirrorQuality(content) {
     },
   };
 
-  const lines = content.split(/\r?\n/);
+  const lines = preprocessBlockLines(content);
   let inBlock = false;
   const blockLines = [];
 

package/scripts/lib/config/vault-staleness.mjs

@@ -1,4 +1,5 @@
 import { matchBlockHeader } from './block-header.mjs';
+import { preprocessBlockLines } from './block-preprocess.mjs';
 
 /**
  * vault-staleness.mjs — Parser for the top-level `vault-staleness:` YAML block.
@@ -17,7 +18,7 @@ export function _parseVaultStaleness(content) {
     mode: 'warn',
   };
 
-  const lines = content.split(/\r?\n/);
+  const lines = preprocessBlockLines(content);
   let inBlock = false;
   const blockLines = [];
 

package/scripts/lib/config/vault-sync.mjs

@@ -1,4 +1,5 @@
 import { matchBlockHeader } from './block-header.mjs';
+import { preprocessBlockLines } from './block-preprocess.mjs';
 
 /**
  * vault-sync.mjs — Parser for the top-level `vault-sync:` YAML block.
@@ -16,7 +17,7 @@ import { matchBlockHeader } from './block-header.mjs';
 export function _parseVaultSync(content) {
   const defaults = { enabled: false, mode: 'warn', 'vault-dir': null, exclude: [] };
 
-  const lines = content.split(/\r?\n/);
+  const lines = preprocessBlockLines(content);
   let inBlock = false;
   const blockLines = [];
 

package/scripts/lib/config/verification-auto-fix.mjs

@@ -1,4 +1,5 @@
 import { matchBlockHeader } from './block-header.mjs';
+import { preprocessBlockLines } from './block-preprocess.mjs';
 
 /**
  * verification-auto-fix.mjs — Parser for the top-level `verification-auto-fix:`
@@ -31,7 +32,7 @@ export function _parseVerificationAutoFix(content) {
     'max-retries': 2,
   };
 
-  const lines = content.split(/\r?\n/);
+  const lines = preprocessBlockLines(content);
   let inBlock = false;
   const blockLines = [];
 

package/scripts/lib/config/wave-reviewers.mjs

@@ -1,4 +1,5 @@
 import { matchBlockHeader } from './block-header.mjs';
+import { preprocessBlockLines } from './block-preprocess.mjs';
 
 /**
  * wave-reviewers.mjs — Parser for the `wave-reviewers` / `persona-reviewers` sub-block.
@@ -58,7 +59,7 @@ export function _parseWaveReviewers(content) {
  * @returns {string[]}
  */
 function _extractBlock(content, key) {
-  const lines = content.split(/\r?\n/);
+  const lines = preprocessBlockLines(content);
   const blockLines = [];
   let inBlock = false;
 

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

@@ -1,4 +1,5 @@
 import { matchBlockHeader } from './block-header.mjs';
+import { preprocessBlockLines } from './block-preprocess.mjs';
 
 /**
  * worktree-orphans.mjs — Parser for the top-level `worktree-orphans:` YAML block.
@@ -85,7 +86,7 @@ export function _parseWorktreeOrphans(content) {
 
   if (typeof content !== 'string' || content === '') return defaults;
 
-  const lines = content.split(/\r?\n/);
+  const lines = preprocessBlockLines(content);
   let inBlock = false;
   const blockLines = [];
 

package/scripts/lib/convergence-monitor.mjs

@@ -39,6 +39,7 @@
  * @property {number} waveNumber
  * @property {number | null} filesChanged
  * @property {number | null} testPassed
+ * @property {number | null} testFailed
  * @property {number | null} agentDispatchCount
  */
 
@@ -143,21 +144,56 @@ 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.
+ * 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 gate admission is a TYPE-AND-SHAPE gate, never a bare prefix widening —
+ * see `isWaveScopedEvent` for why.
  */
 const WAVE_EVENT_PREFIX = 'orchestrator.wave.';
 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 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
+ * payload are all rejected — the shape half of the type-and-shape gate.
+ *
+ * @param {Record<string, unknown>} rec
+ * @returns {boolean}
+ */
+function hasFoldableCounts(rec) {
+  const counts = rec.counts;
+  if (counts === null || typeof counts !== 'object' || Array.isArray(counts)) return false;
+  return pickInt(/** @type {Record<string, unknown>} */ (counts).passed) !== null;
+}
 
 /**
+ * Type-AND-shape gate: admit a record only when its event type is one this
+ * monitor classifies AND the record actually carries a measurement `classify`
+ * can fold. A bare prefix widening for `orchestrator.quality_gate.*` would
+ * re-open the #966 trap — the gate is the single highest-volume record type in
+ * `events.jsonl`, and admitting the session-level runs (no `wave_number`, or an
+ * envelope without `counts`) would instantiate a `WaveSummary` per gate run,
+ * advance `latestWave`, and burn the once-per-wave `alreadyEmitted` keys before
+ * 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`.
+ *
  * @param {string} evType
+ * @param {Record<string, unknown>} rec
  * @returns {boolean}
  */
-function isWaveScopedEvent(evType) {
-  return evType.startsWith(WAVE_EVENT_PREFIX) || WAVE_EVENT_NAMES.has(evType);
+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.startsWith(GATE_EVENT_PREFIX)) {
+    return pickInt(rec.wave_number) !== null && hasFoldableCounts(rec);
+  }
+  return false;
 }
 
 /**
@@ -179,12 +215,29 @@ function isWaveScopedEvent(evType) {
  * `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.
+ * record arrived later. Several other high-volume types (`turn.stopped` — and its
+ * deprecated alias `session.stopped`, GitLab #1234 — plus `memory.propose_invoked`)
+ * already carry a wave and sat in the same trap. The gate is an ALLOWLIST
+ * (`isWaveRelevantType`), so the rename needed no edit here: a new name is
+ * ignored by default, which is the correct default for this classifier.
  *
- * 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.
+ * ## Where the pass count actually comes from (#980)
+ *
+ * Two independent paths, deliberately not merged:
+ *   - the FLAT `rec['test.passed']` alias, kept for a future direct emitter on
+ *     a wave-lifecycle record — no producer writes it today;
+ *   - the gate envelope's NESTED `counts.passed`, folded ONLY for
+ *     `orchestrator.quality_gate.*` records that also carry `wave_number`.
+ *     That gating is what keeps the #966 invariant intact: an ungated record
+ *     (a `wave.completed` carrying `counts`, or a session-level gate run with
+ *     no `wave_number`) still folds NOTHING, so a gate run cannot manufacture a
+ *     `WaveSummary` and burn the once-per-wave emit keys.
+ *
+ * `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`).
  *
  * @param {Record<string, unknown>} rec
  * @param {Map<number, WaveSummary>} state
@@ -192,7 +245,7 @@ function isWaveScopedEvent(evType) {
  */
 function classify(rec, state) {
   const evType = String(rec.event_type ?? rec.event ?? '');
-  if (!isWaveScopedEvent(evType)) return null;
+  if (!isWaveScopedEvent(evType, rec)) return null;
 
   const waveNumber = pickInt(rec.wave_number ?? rec.wave ?? rec.waveId);
   if (waveNumber === null) return null;
@@ -202,6 +255,7 @@ function classify(rec, state) {
       waveNumber,
       filesChanged: null,
       testPassed: null,
+      testFailed: null,
       agentDispatchCount: null,
     };
     state.set(waveNumber, summary);
@@ -210,8 +264,17 @@ function classify(rec, state) {
   if (filesChanged !== null) summary.filesChanged = filesChanged;
   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.
-  if (WAVE_EVENT_NAMES.has(evType)) {
+  // Nested gate envelope — admitted by isWaveScopedEvent only WITH wave_number,
+  // so the ungated #966 invariant (no fold) survives for every other record.
+  if (evType.startsWith(GATE_EVENT_PREFIX)) {
+    const counts = /** @type {Record<string, unknown>} */ (rec.counts);
+    const gatePassed = pickInt(counts.passed);
+    if (gatePassed !== null) summary.testPassed = gatePassed;
+    const gateFailed = pickInt(counts.failed);
+    if (gateFailed !== null) summary.testFailed = gateFailed;
+  }
+  // Count one dispatched/stopped agent record toward this wave's agent count.
+  if (WAVE_EVENT_NAMES.has(evType) || evType === AGENT_STOPPED_EVENT) {
     summary.agentDispatchCount = (summary.agentDispatchCount ?? 0) + 1;
   } else {
     const dispatched = pickInt(rec.agents_dispatched ?? rec.agentsDispatched);
@@ -443,4 +506,7 @@ if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.a
   main();
 }
 
-export { classify, isWaveScopedEvent };
+// `_evaluateSignals` is a test-only export (leading `_` per the repo convention,
+// cf. `_clearCompileCache` in scripts/lib/agent-output-schema.mjs): the signal
+// firing is otherwise reachable only through the live tail loop.
+export { classify, isWaveScopedEvent, evaluateSignals as _evaluateSignals };