session-orchestrator 3.23.0 → 4.0.0

package/scripts/lib/codex/plugin-contract.mjs

@@ -43,18 +43,94 @@ const REQUIRED_CODEX_EVENTS = [
   'Stop',
 ];
 
-const FORBIDDEN_CODEX_EVENTS = new Set([
-  'SessionEnd',
-  'PostToolUseFailure',
-  'PostToolBatch',
-  'CwdChanged',
+/**
+ * Every hook event the Codex runtime knows, MEASURED — not quoted from release
+ * notes. Read out of the `codex` binary shipped as codex-cli **0.144.4**
+ * (`@openai/codex-darwin-arm64/vendor/aarch64-apple-darwin/bin/codex`,
+ * 2026-09-06), which embeds one JSON Schema pair per event:
+ *
+ *   strings -a <codex> | grep '"title": "'
+ *     -> pre-tool-use / post-tool-use / permission-request / pre-compact
+ *        / post-compact / session-start / subagent-start / subagent-stop
+ *        / user-prompt-submit / stop   .command.{input,output}   (10 pairs)
+ *
+ * The same binary carries the manifest deserializer's key list
+ * (`PreToolUse PermissionRequest PostToolUse PreCompact PostCompact
+ * SessionStart SubagentStart SubagentStop` + the substring-deduped `Stop` /
+ * `UserPromptSubmit`) directly beside its `unexpected map key` error string —
+ * so an event key outside this set is rejected, and rejecting one key rejects
+ * the manifest that carries it.
+ *
+ * **`SessionEnd` and `Interrupt` are NOT in it.** They are not merely unwired
+ * here: at 0.144.4 they do not exist, and adding either to hooks-codex.json
+ * risks taking every already-working hook down with it. Newer Codex releases
+ * (0.148+ async hooks, 0.150+ `Interrupt`) are documented-but-unverified on
+ * this host — re-measure against the shipped binary before widening this set,
+ * never against a changelog.
+ */
+export const CODEX_NATIVE_EVENTS = new Set([
+  'SessionStart',
+  'UserPromptSubmit',
+  'PreToolUse',
+  'PermissionRequest',
+  'PostToolUse',
+  'PreCompact',
+  'PostCompact',
+  'SubagentStart',
+  'SubagentStop',
+  'Stop',
 ]);
 
-const DISALLOWED_EDIT_HANDLERS = [
+/**
+ * Claude hook events this repo wires that Codex 0.144.4 has no counterpart for.
+ * DERIVED from {@link CODEX_NATIVE_EVENTS} rather than hand-listed, so a new
+ * Claude event is forbidden on Codex by construction until someone measures it
+ * into the native set above.
+ */
+const FORBIDDEN_CODEX_EVENTS = new Set(
+  ['SessionEnd', 'PostToolUseFailure', 'PostToolBatch', 'CwdChanged', 'Interrupt']
+    .filter((event) => !CODEX_NATIVE_EVENTS.has(event)),
+);
+
+/**
+ * The tool-name vocabulary Codex puts in `tool_name`, measured at 0.144.4 from
+ * the same binary. This is the load-bearing incompatibility, and it is NOT the
+ * one the older comments in `check-hooks-symmetry.mjs` claimed.
+ *
+ * `pre-tool-use.command.input` REQUIRES `tool_name` and `tool_input` (alongside
+ * `cwd`, `hook_event_name`, `model`, `permission_mode`, `session_id`,
+ * `tool_use_id`, `transcript_path`, `turn_id`) — so the payload fields ARE
+ * delivered. What differs is their VALUES: Codex has no `Bash`, `Edit`, `Write`
+ * or `MultiEdit` tool (`strings -a <codex> | grep -c '"Bash"'` -> 0). Every
+ * PreToolUse guard in `hooks/` opens with an equality gate on one of those four
+ * names and returns `emitAllow()` otherwise, so wiring one here yields a
+ * handler that runs, matches nothing, and allows everything — false
+ * enforcement, which is worse than a registered gap.
+ *
+ * The adapter this actually needs is a tool-name MAP (shell/exec_command/
+ * unified_exec -> Bash, apply_patch -> Edit/Write), not a payload bridge.
+ */
+export const CODEX_TOOL_NAMES = Object.freeze([
+  'shell',
+  'exec_command',
+  'unified_exec',
+  'apply_patch',
+  'update_plan',
+  'view_image',
+]);
+
+/**
+ * Hook handlers that read an Edit/Write `tool_input.file_path` payload. Codex
+ * emits `apply_patch` payloads of a different shape, so wiring one of these into
+ * hooks-codex.json produces a handler that silently never fires. Exported so the
+ * contract test can assert the census rather than re-list it.
+ */
+export const DISALLOWED_EDIT_HANDLERS = [
   'enforce-scope.mjs',
   'config-protection.mjs',
   'post-edit-validate.mjs',
   'post-tooluse-frontend-slop.mjs',
+  'post-edit-import-probe.mjs',
 ];
 
 const CODEX_HOOK_WRAPPER_COMMAND =

package/scripts/lib/cold-start-detector.mjs

@@ -10,8 +10,9 @@
  * Behaviour (PRD §F1.3):
  *   1. Skip if `bootstrap.lock` is missing (repo not yet bootstrapped —
  *      the bootstrap-gate handles that path).
- *   2. Skip if `sessions.jsonl` line count ≥ `silence-after-sessions`
- *      (operator has already engaged at least once).
+ *   2. Skip if the `sessions.jsonl` DISTINCT-session count ≥
+ *      `silence-after-sessions` — identities, not lines (see `countSessions`);
+ *      the operator has already engaged at least once.
  *   3. Skip if bootstrap age < `nudge-after-hours` (give the operator a
  *      reasonable window after bootstrap before nudging).
  *   4. Emit otherwise, with a `markerPath` when the migration marker
@@ -34,6 +35,7 @@ import { stat, readFile, unlink } from 'node:fs/promises';
 import path from 'node:path';
 
 import { parseBootstrapLock } from './bootstrap-lock-freshness.mjs';
+import { countSessionsInJsonl } from './sessions-canonical.mjs';
 
 /** Milliseconds in one hour — exported for testability. */
 export const MS_PER_HOUR = 60 * 60 * 1000;
@@ -77,24 +79,31 @@ function buildBannerLines({ bootstrappedAt = null } = {}) {
 }
 
 /**
- * Best-effort line counter for NDJSON files. Returns 0 when the file is
- * missing OR empty OR unreadable — all three are equivalent for the
- * cold-start decision ("no sessions yet").
+ * Best-effort counter of DISTINCT physical sessions in an NDJSON ledger.
+ * Returns 0 when the file is missing OR empty OR unreadable — all three are
+ * equivalent for the cold-start decision ("no sessions yet").
+ *
+ * Counts IDENTITIES, not lines (#1167): `sessions.jsonl` is append-only, so one
+ * physical session can occupy two lines (a backfilled abandoned stub plus the
+ * authoritative record that supersedes it, or the systemic double-stub pair
+ * written by the two backfill writers). A raw line count therefore reports
+ * "the operator has already engaged" one session earlier than is true, and the
+ * cold-start nudge — one-shot per repo at the default threshold of 1 — is
+ * silently never emitted.
  *
  * Reads the full file because sessions.jsonl is small (1 line/session, ~2 KB
- * each — even 100 sessions = ~200 KB).
+ * each — even 100 sessions = ~200 KB). The async `readFile` is kept (the
+ * SessionStart hook's 5s budget must not block); only the collapse rules come
+ * from the shared canonical module.
  *
  * @param {string} filePath
  * @returns {Promise<number>}
  */
-async function countLines(filePath) {
+async function countSessions(filePath) {
   try {
-    const raw = await readFile(filePath, 'utf8');
-    if (!raw) return 0;
-    // Trailing newline must not inflate the count. split-then-filter handles
-    // both Unix (\n) and Windows (\r\n) line endings.
-    const lines = raw.split('\n').filter((l) => l.length > 0);
-    return lines.length;
+    // Counting rule (blank/malformed lines, id-less records) lives in
+    // `countSessionsInJsonl`; only the async read is local.
+    return countSessionsInJsonl(await readFile(filePath, 'utf8'));
   } catch {
     return 0;
   }
@@ -166,7 +175,7 @@ export async function detectColdStart(opts = {}) {
 
   // PRD §F1.3 Ubiquitous: silence once the repo has ≥ N sessions. This is
   // the auto-silence path — banner is one-shot per repo (default N=1).
-  const sessionCount = await countLines(sessionsPath);
+  const sessionCount = await countSessions(sessionsPath);
   if (sessionCount >= silenceAfterSessions) {
     return {
       shouldEmit: false,

package/scripts/lib/config/auto-dream.mjs

@@ -1,4 +1,5 @@
 import { matchBlockHeader } from './block-header.mjs';
+import { preprocessBlockLines } from './block-preprocess.mjs';
 
 /**
  * auto-dream.mjs — Parser for the top-level `auto-dream:` YAML block (issue #566).
@@ -32,7 +33,7 @@ export function _parseAutoDream(content) {
     'min-confidence': 0.5,
   };
 
-  const lines = content.split(/\r?\n/);
+  const lines = preprocessBlockLines(content);
   let inBlock = false;
   const blockLines = [];
 

package/scripts/lib/config/block-header.mjs

@@ -31,6 +31,19 @@
  *
  * The two `**` markers are independent (`**key:` and `key:**` both match),
  * mirroring the tolerant #823 vault-integration regex.
+ *
+ * COMMENT-STRIPPING IS THE CALLER'S JOB (#1222). Every matcher here sees RAW
+ * lines: a header inside a `<!-- … -->` HTML comment matches exactly like a live
+ * one. That is deliberate — stripping comments needs the `block-preprocess.mjs`
+ * state machine, and importing it would end this module's zero-import leaf
+ * status. A caller that must agree with a comment-STRIPPING parser preprocesses
+ * its content first (`preprocessBlockLinesNoDash(content).join('\n')`) — see
+ * `dispatcher-autonomy-capture.mjs` `isDispatcherAutonomyBlockPresent()`.
+ *
+ * `matchBlockHeaderDetailed` (#1185) is a SEPARATE, additive matcher below for
+ * parsers that need what this contract deliberately rejects — an indented
+ * (nested) header and/or an inline value. It does not change the contract
+ * above; `matchBlockHeader`/`hasBlockHeader` keep exactly this behaviour.
  */
 
 /**
@@ -73,6 +86,56 @@ export function matchBlockHeader(line, key) {
   return blockHeaderRe(key).test(line);
 }
 
+/**
+ * Build the indent-aware, inline-value-capturing block-header regex for a key.
+ * A strict SUPERSET of `blockHeaderRe`: it additionally matches an ARBITRARY
+ * leading indent (group 1) and an optional inline value trailing the colon
+ * (group 2) — the two things `matchBlockHeader` deliberately rejects (a
+ * nested sub-key, and a header carrying a value, per the module docblock).
+ *
+ * @param {string} key
+ * @returns {RegExp}
+ */
+function detailedBlockHeaderRe(key) {
+  return new RegExp(
+    '^(\\s*)(?:-\\s+)?(?:\\*\\*)?' + escapeRegExp(key) + ':(?:\\*\\*)?(?:[ \\t]+(.*))?$'
+  );
+}
+
+/**
+ * Indent + inline-value variant of `matchBlockHeader` (#1185). Additive —
+ * `matchBlockHeader`/`hasBlockHeader` are unchanged and every existing caller
+ * keeps its current behaviour untouched.
+ *
+ * Built for parsers whose header can be NESTED under a parent block (e.g.
+ * `health-endpoints:` one level under `ecosystem-health:`) and/or carry an
+ * INLINE value (`health-endpoints: [{name: …}]`) on the same line — exactly
+ * the two forms `matchBlockHeader` treats as "not a top-level block-opener".
+ * This is a separate, purpose-built matcher, not a relaxed replacement: a
+ * caller that only needs the boolean top-level check keeps using
+ * `matchBlockHeader`.
+ *
+ * The captured value is RAW text, never comment-stripped — `key:  # note`
+ * reports `value: '# note'`, exactly as the pre-#1185 `health-endpoints.mjs`
+ * `HEADER_RE` did. A caller that needs comment semantics strips them itself
+ * (as `health-endpoints.mjs` already does for its block BODY via its own
+ * `stripComment()` — only the header line's raw capture moved here).
+ *
+ * @param {string} line — a single line (callers strip the trailing `\n`)
+ * @param {string} key — the literal block key
+ * @returns {{indent: number, value: string|null}|null} `null` on no match;
+ *   `value` is `null` for a bare header (`key:`, optionally trailing
+ *   whitespace only), else the trimmed text following the colon.
+ */
+export function matchBlockHeaderDetailed(line, key) {
+  if (typeof line !== 'string' || typeof key !== 'string' || key === '') return null;
+  const m = line.match(detailedBlockHeaderRe(key));
+  if (!m) return null;
+  const indent = m[1].length;
+  const trimmed = (m[2] ?? '').trim();
+  return { indent, value: trimmed === '' ? null : trimmed };
+}
+
 /**
  * Multiline presence variant: true when ANY line of `content` opens the
  * top-level block for `key`. For whole-file PRESENCE guards (e.g.

package/scripts/lib/config/block-preprocess.mjs

@@ -0,0 +1,177 @@
+/**
+ * block-preprocess.mjs — THE line-preprocessing contract for the block parsers
+ * under `scripts/lib/config/` (#1162).
+ *
+ * Every block parser here begins with `content.split(/\r?\n/)`, then walks lines
+ * looking for its own header and the indented sub-keys under it. Two markdown
+ * shapes that are ordinary in a CLAUDE.md / AGENTS.md were invisible to that
+ * walk, and both failed in the dangerous direction:
+ *
+ *   (a) A block commented OUT with a multi-line `<!-- … -->` was read as LIVE
+ *       config. Commenting a key out is the most ordinary way to disable it; it
+ *       must not arm it. (`_extractConfigSection` learned this in #1097 — the
+ *       block parsers never did.)
+ *   (b) The bold-bullet rendering of a SUB-key (`- **enabled:** true`) matched
+ *       no sub-key regex, so the key was absent and its DEFAULT applied. For a
+ *       boolean that default is `false`, which reads exactly like a deliberately
+ *       disabled block — no error, in any log. #823 fixed this for the block
+ *       HEADER only (see `block-header.mjs`); this fixes it for the body.
+ *
+ * ZERO IMPORTS beyond the sibling `section-extractor.mjs` skipper, stdlib only —
+ * `tests/lib/config/cycle-guard.test.mjs` forbids any `scripts/lib/config/*.mjs`
+ * from importing `../config.mjs`, and the RAW-PARITY constraint (block-header.mjs
+ * docblock) requires the normalisation to live in the helper each parser calls,
+ * never in a preprocessing step in `config.mjs`.
+ *
+ * DELIBERATE NON-GOAL — fenced code blocks. These parsers are fence-UNAWARE, and
+ * that is a pinned contract, not an oversight. Two tests, cited by NAME because
+ * line numbers rot: `tests/lib/config/frontend-slop-hook.test.mjs` — "parses a
+ * block wrapped in a fenced code block — the parser is fence-unaware", and
+ * `tests/lib/config/dispatcher-autonomy-capture.test.mjs` — "treats a header
+ * inside a fenced code block as PRESENT". Both assert that a ```-fenced block IS
+ * parsed. Teaching this module about
+ * fences would flip ~36 parsers at once and break those pins, so it does not.
+ * Revisit only as its own change, with those two tests as the blast radius.
+ */
+
+import { htmlCommentSkipper } from './section-extractor.mjs';
+
+/**
+ * Drop every line that lies inside — or opens — a multi-line `<!-- … -->` HTML
+ * comment (#1162a).
+ *
+ * Wraps `htmlCommentSkipper()` from `section-extractor.mjs` rather than
+ * re-deriving the state machine, so the block parsers and the Session Config
+ * KV extractor share ONE definition of "this line is commented-out
+ * documentation" by construction. A fresh closure is built per call: the skipper
+ * carries per-document state, and a shared instance would leak an unterminated
+ * comment from one document into the next.
+ *
+ * Inherits the skipper's deliberate ceiling: the opener must be at the START of
+ * a line (`/^\s*<!--/`), so `waves: 5 <!-- note` does NOT swallow the following
+ * lines — the trailing single-line comment form this repo's own convention
+ * encourages keeps working.
+ *
+ * Never touches `- ` list markers, indentation, or line content.
+ *
+ * FAIL-CLOSED on an UNTERMINATED comment. A stray `<!--` with no `-->` after it
+ * puts the skipper in the swallowing state for the REST of the document, so
+ * every later block silently disappears and each parser falls back to its
+ * defaults — for `config-protection` that is `strict` → `warn`, i.e. a guard
+ * disarmed by a typo, with no error anywhere. When the skipper would still be
+ * inside a comment at EOF, this returns the INPUT lines unfiltered (the
+ * pre-#1162 behaviour: the opener is treated as literal text), so nothing can
+ * vanish. The condition is reported via `onUnterminated` and is separately
+ * observable through {@link findUnterminatedComment}.
+ *
+ * @param {string[]} lines
+ * @param {(lineNo: number) => void} [onUnterminated] — called with the 1-based
+ *   line number of the unterminated opener when stripping is disabled.
+ * @returns {string[]} a new array; the input is not mutated.
+ */
+export function stripHtmlCommentBlocks(lines, onUnterminated) {
+  if (!Array.isArray(lines)) return [];
+  const unterminatedAt = findUnterminatedComment(lines);
+  if (unterminatedAt !== null) {
+    if (typeof onUnterminated === 'function') onUnterminated(unterminatedAt);
+    return lines.slice();
+  }
+  const skip = htmlCommentSkipper();
+  return lines.filter((line) => !skip(typeof line === 'string' ? line : ''));
+}
+
+/**
+ * The 1-based line number of an `<!--` that is never closed, or `null` when
+ * every comment in `lines` is terminated.
+ *
+ * Derived from the SAME `htmlCommentSkipper()` state machine rather than a
+ * second copy of it (the RAW-PARITY constraint): the skipper swallows the
+ * closing `-->` line too, so the document ends inside a comment exactly when
+ * the LAST swallowed line carries no `-->`. A swallowed line that follows a
+ * closing line (or the first one of all) is an opener, which is how the
+ * reported line number is obtained.
+ *
+ * @param {string[]} lines
+ * @returns {number|null}
+ */
+export function findUnterminatedComment(lines) {
+  if (!Array.isArray(lines)) return null;
+  const skip = htmlCommentSkipper();
+  let openerLine = null;
+  /** @type {string|null} */
+  let lastSwallowed = null;
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = typeof lines[i] === 'string' ? lines[i] : '';
+    if (!skip(line)) continue;
+    if (lastSwallowed === null || lastSwallowed.includes('-->')) openerLine = i + 1;
+    lastSwallowed = line;
+  }
+  if (lastSwallowed === null || lastSwallowed.includes('-->')) return null;
+  return openerLine;
+}
+
+/**
+ * `- **key:** value` / `- **key**: value` / `**key:** value` → `key: value`,
+ * preserving the leading indentation EXACTLY (#1162b).
+ *
+ * The indent is load-bearing: every block parser ends its block at the first
+ * non-empty non-indented line, so an indent-eating rewrite would truncate the
+ * block one line early. Only the `**` markers and the optional `- ` bullet
+ * immediately around the `key:` token at line start are removed; the value
+ * portion (including any literal `**` inside it) is untouched — same rule as the
+ * `_matchKVLine` Format-1 branch and the #823 header tolerance.
+ *
+ * A line that is not a bold key/value pair is returned byte-identical.
+ *
+ * @internal — exported for this module's own tests. Production callers use
+ * {@link preprocessBlockLines} / {@link preprocessBlockLinesNoDash}.
+ *
+ * NAMED RISK — dash-record blocks. In any block whose body uses `- ` as a RECORD
+ * boundary, de-dashing the first key of a record merges it into the PREVIOUS
+ * record, silently producing one record where two were written. Those parsers
+ * must use
+ * `preprocessBlockLinesNoDash` instead. `tests/lib/config/block-preprocess.test.mjs`
+ * demonstrates the merge so the next reader sees why the NoDash variant exists.
+ *
+ * @param {string[]} lines
+ * @returns {string[]} a new array; the input is not mutated.
+ */
+export function normalizeBoldSubkeys(lines) {
+  if (!Array.isArray(lines)) return [];
+  return lines.map((line) => {
+    if (typeof line !== 'string') return line;
+    // (1) indent  (2) optional bullet  (3) **key:**  or  **key**:  (4) rest
+    const m = line.match(/^(\s*)(?:-\s+)?\*\*([^*:]+?)(?::\*\*|\*\*:)\s*(.*)$/);
+    if (!m) return line;
+    const value = m[3];
+    return value === '' ? `${m[1]}${m[2]}:` : `${m[1]}${m[2]}: ${value}`;
+  });
+}
+
+/**
+ * THE drop-in replacement for `content.split(/\r?\n/)` in a flat or
+ * nested-OBJECT block parser: strip commented-out lines, then normalise bold
+ * sub-keys.
+ *
+ * @param {string} content — full file contents
+ * @returns {string[]} preprocessed lines (empty array for non-string input)
+ */
+export function preprocessBlockLines(content) {
+  if (typeof content !== 'string') return [];
+  return normalizeBoldSubkeys(stripHtmlCommentBlocks(content.split(/\r?\n/)));
+}
+
+/**
+ * THE drop-in for every dash-RECORD parser — any parser whose block body uses
+ * `- ` as a record boundary, so the dash must survive: HTML-comment stripping
+ * only, no bold-subkey normalisation. (Enumerating them here goes stale; the
+ * rule is the criterion. `grep -l preprocessBlockLinesNoDash scripts/lib/config/`
+ * lists the current set.)
+ *
+ * @param {string} content — full file contents
+ * @returns {string[]} preprocessed lines (empty array for non-string input)
+ */
+export function preprocessBlockLinesNoDash(content) {
+  if (typeof content !== 'string') return [];
+  return stripHtmlCommentBlocks(content.split(/\r?\n/));
+}

package/scripts/lib/config/broken-window.mjs

@@ -1,4 +1,5 @@
 import { matchBlockHeader } from './block-header.mjs';
+import { preprocessBlockLines } from './block-preprocess.mjs';
 
 /**
  * broken-window.mjs — Parser for the top-level `broken-window-budget:` YAML block
@@ -48,7 +49,7 @@ export function _parseBrokenWindow(content) {
     'due-days': 7,
   };
 
-  const lines = String(content ?? '').split(/\r?\n/);
+  const lines = preprocessBlockLines(String(content ?? ''));
   let inBlock = false;
   const blockLines = [];
 

package/scripts/lib/config/cold-start.mjs

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

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

@@ -1,4 +1,5 @@
 import { matchBlockHeader } from './block-header.mjs';
+import { findUnterminatedComment, preprocessBlockLines, preprocessBlockLinesNoDash } from './block-preprocess.mjs';
 import { isSessionConfigHeading } from './section-extractor.mjs';
 
 /**
@@ -45,7 +46,7 @@ export function _parseConfigProtection(content) {
 
   if (typeof content !== 'string' || content.length === 0) return defaults;
 
-  const lines = content.split(/\r?\n/);
+  const lines = preprocessBlockLines(content);
   let inBlock = false;
   const blockLines = [];
 
@@ -107,7 +108,26 @@ export function _parseConfigProtection(content) {
 export function _isConfigWeakeningAllowed(content) {
   if (typeof content !== 'string' || content.length === 0) return false;
 
-  const lines = content.split(/\r?\n/);
+  // HTML-comment stripping ONLY (`preprocessBlockLinesNoDash`), never the full
+  // `preprocessBlockLines`: bold-subkey normalisation would make
+  // `- **allow-config-weakening:** true` arm the bypass, and
+  // `tests/lib/config/config-protection.test.mjs` pins the opposite — only the
+  // plain form is the supported bypass. Fail-closed beats markdown tolerance there.
+  // The comment strip is the OTHER direction and is mandatory (W4/F1): with a raw
+  // `content.split(/\r?\n/)` a COMMENTED-OUT `<!--\nallow-config-weakening: true\n-->`
+  // inside `## Session Config` ARMED the bypass — commenting a key out is the most
+  // ordinary way to disable it and must never enable it (same class as #1162a).
+  //
+  // UNTERMINATED `<!--` — the fail-closed direction INVERTS for a bypass scan.
+  // `stripHtmlCommentBlocks` returns the lines UNFILTERED when a comment is never
+  // closed, which is right for a block PARSER (nothing may silently vanish) and
+  // wrong here: it hands the commented-out bypass line straight back and re-arms
+  // the guard's own off switch. For this scan "I cannot tell where the comments
+  // end" must mean NOT ARMED — the bypass is opt-in, so refusing to grant it is
+  // the safe reading in every ambiguous document.
+  if (findUnterminatedComment(content.split(/\r?\n/)) !== null) return false;
+
+  const lines = preprocessBlockLinesNoDash(content);
   let inConfig = false;
   for (const line of lines) {
     if (isSessionConfigHeading(line)) { inConfig = true; continue; }

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

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

package/scripts/lib/config/cross-repo.mjs

@@ -20,6 +20,7 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { readConfigFile } from './io.mjs';
 import { matchBlockHeader } from './block-header.mjs';
+import { preprocessBlockLines } from './block-preprocess.mjs';
 
 /**
  * Resolve the cross-repo confinement root. Defaults to ~/Projects.
@@ -47,7 +48,7 @@ const SAFE_PATH_RE = /^[A-Za-z0-9._~/-]+$/;
  * @returns {string[]} list of project paths, or [] when absent/empty/none/null
  */
 export function _parseCrossRepo(content) {
-  const lines = content.split(/\r?\n/);
+  const lines = preprocessBlockLines(content);
   let inBlock = false;
 
   for (const rawLine of lines) {

package/scripts/lib/config/custom-phases.mjs

@@ -1,4 +1,5 @@
 import { matchBlockHeader } from './block-header.mjs';
+import { preprocessBlockLinesNoDash } from './block-preprocess.mjs';
 
 /**
  * custom-phases.mjs — Parser for the `custom-phases:` Session Config block (#637).
@@ -65,7 +66,7 @@ const SAFE_PATH_RE = /^[A-Za-z0-9._~/-]+$/;
  * @returns {Array<{name: string, when: string, command: string, mode: string, review: string|null}>}
  */
 export function _parseCustomPhases(content) {
-  const lines = content.split(/\r?\n/);
+  const lines = preprocessBlockLinesNoDash(content);
   let inBlock = false;
   const blockLines = [];
 

package/scripts/lib/config/dialectic.mjs

@@ -1,4 +1,5 @@
 import { matchBlockHeader } from './block-header.mjs';
+import { preprocessBlockLines } from './block-preprocess.mjs';
 
 /**
  * dialectic.mjs — Parser for top-level `dialectic:` YAML block (#506).
@@ -30,7 +31,7 @@ const ALLOWED_MODELS = new Set(['haiku', 'sonnet', 'opus']);
 export function _parseDialectic(content) {
   const defaults = { cadence: 5, model: 'haiku', 'budget-tokens': 8000 };
 
-  const lines = content.split(/\r?\n/);
+  const lines = preprocessBlockLines(content);
   let inBlock = false;
   const blockLines = [];
 

package/scripts/lib/config/discovery-validator.mjs

@@ -1,4 +1,5 @@
 import { matchBlockHeader } from './block-header.mjs';
+import { preprocessBlockLines } from './block-preprocess.mjs';
 
 /**
  * discovery-validator.mjs — Parser for the top-level `discovery-validator:`
@@ -10,6 +11,11 @@ import { matchBlockHeader } from './block-header.mjs';
  * transcript. v1 is log+warn only (events.jsonl + stderr WARN); exit 2
  * (blocking) is reserved for a future hard-gate.
  *
+ * OFF by default (opt-in) — issue #567's original acceptance criterion. The
+ * #690 flip to ON (2026-06-25) was reverted 2026-09-02 (#1191) after fleet
+ * measurement: 6,946 `discovery_validator_violation` events accumulated in 18
+ * repos that never declared the block.
+ *
  * Returns `{ enabled }`.
  * Tolerant parser: malformed values silently fall back to defaults.
  *
@@ -21,17 +27,17 @@ import { matchBlockHeader } from './block-header.mjs';
  * Independent of the `## Session Config` section boundary.
  *
  * Defaults:
- *   enabled: true
+ *   enabled: false (opt-in)
  *
  * @param {string} content — full file contents
  * @returns {{ enabled: boolean }}
  */
 export function _parseDiscoveryValidator(content) {
   const defaults = {
-    enabled: true,
+    enabled: false,
   };
 
-  const lines = content.split(/\r?\n/);
+  const lines = preprocessBlockLines(content);
   let inBlock = false;
   const blockLines = [];