session-orchestrator 3.22.0 → 3.24.0

package/scripts/lib/ci-status-banner.mjs

@@ -47,6 +47,128 @@ async function execWithTimeout(cmd, args, opts = {}) {
   ]);
 }
 
+/** C0 controls plus DEL — matching them is the POINT, hence the disable. */
+// eslint-disable-next-line no-control-regex
+const CONTROL_BYTE_RE = /[\u0000-\u001f\u007f]/g;
+
+/**
+ * Replace every C0/DEL control byte with its printable `\uXXXX` escape.
+ *
+ * `JSON.stringify` covers the payload preview, but NOT `SyntaxError.message` —
+ * V8 quotes the offending input INTO that message verbatim, so an ANSI/CR
+ * payload reached the operator's terminal through the error text even after
+ * the preview was escaped. Both halves go through here.
+ *
+ * @param {unknown} text
+ * @returns {string}
+ */
+function escapeControlBytes(text) {
+  return String(text).replace(
+    CONTROL_BYTE_RE,
+    (ch) => `\\u${ch.charCodeAt(0).toString(16).padStart(4, '0')}`,
+  );
+}
+
+/**
+ * Name a parsed JSON value's type WITHOUT quoting any of its content.
+ *
+ * @param {unknown} value
+ * @returns {'null'|'array'|'object'|'string'|'number'|'boolean'|'undefined'}
+ */
+function jsonTypeOf(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  return /** @type {any} */ (typeof value);
+}
+
+/**
+ * Parse CLI stdout as JSON, degrading an unparseable payload onto this module's
+ * documented failure channel instead of a bare `SyntaxError` (CWE-502).
+ *
+ * The throw IS that channel, not an escape from it: every call site runs under
+ * `checkCiStatus`'s outer catch, whose comment already names "unparseable
+ * output" as a case it converts to `console.warn` + `null`. Measured
+ * 2026-08-28 at 30940cb, BEFORE this helper existed: an HTML login page from
+ * `gh repo view`, a literal `null`, and an empty `glab` stdout ALL already
+ * returned `null` with a warn — nothing crashed, and
+ * `tests/lib/ci-status-banner.test.mjs` § "error containment" pinned it. So
+ * this does not fix a crash — the outer catch already turned non-JSON output
+ * into a warn + `null`. The rule this helper closes is lexical
+ * (`json-parse-untrusted-input`, see below), not a crash it prevents.
+ *
+ * What it does fix is the message. The raw parse error (`Unexpected token
+ * '<'`) named neither the CLI nor the request, and this banner spawns four
+ * different subprocesses — an operator reading that line at session-start
+ * could not tell which one returned garbage, which is the same
+ * "could not read looks like nothing to report" class #1022/#1039 attacked.
+ * Guarding at the parse also satisfies the `json-parse-untrusted-input` rule,
+ * which keys on a LEXICALLY enclosing try/catch and cannot see the outer one.
+ *
+ * Ceiling (BV-004): the payload preview is clamped to 120 characters. An
+ * unbounded one would bury the session-start banner it is printed beside — a
+ * paginated HTML error page is the realistic worst case. Revisit if a CLI
+ * starts emitting a diagnostic that needs more than one line to identify.
+ *
+ * The preview is emitted through `JSON.stringify`, not raw. It comes from a
+ * subprocess whose stdout this module does not control and lands in a
+ * `console.warn` beside the session-start banner: a payload carrying ANSI
+ * escapes, a `\r`, or a bare newline could otherwise repaint or overwrite the
+ * lines around it. `JSON.stringify` escapes every control byte and quotes the
+ * result, so the preview stays exactly one line of printable text.
+ *
+ * `expect` closes the second half of the same gap: valid JSON of the WRONG
+ * SHAPE parsed fine and escaped this named channel entirely. Measured
+ * 2026-08-28 at 7daa3d2 — a `gh repo view` that printed `null` reached
+ * `const { nameWithOwner } = …` and threw a bare
+ * `TypeError: Cannot destructure property 'nameWithOwner' of 'null'`, which
+ * names neither the CLI nor the request; a `glab api …/pipelines` that printed
+ * `null` was swallowed by `!Array.isArray(pipelines) → return null`, silent.
+ * Both now fail as the SAME named error the parse failure produces.
+ *
+ * @param {string} stdout  Raw child-process stdout (untrusted)
+ * @param {string} label   The command that produced it, for the failure message
+ * @param {'object'|'array'} [expect]  Required shape; omit to accept any JSON
+ * @returns {unknown} The parsed value
+ * @throws {Error} Named parse/shape failure carrying a bounded payload preview
+ */
+function parseCliJson(stdout, label, expect) {
+  const raw = String(stdout ?? '');
+  // Bounded (BV-004: 120 chars — a paginated HTML error page is the realistic
+  // worst case) AND escaped, so it can never break the line it is printed on.
+  const preview = raw.trim().slice(0, 120);
+  const shown = preview
+    ? `got: ${escapeControlBytes(JSON.stringify(preview))}`
+    : 'got: (empty stdout)';
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    const reason = escapeControlBytes(err instanceof Error ? err.message : String(err));
+    // `cause` preserves the original for a debugger; the reason is ALSO
+    // inlined into the message because the outer catch reads `err.message`
+    // only — a cause-only wrapper would lose it on the operator-facing line.
+    throw new Error(
+      `${label} returned unparseable JSON (${reason}) — ${shown}`,
+      { cause: err },
+    );
+  }
+
+  // A shape mismatch reports the JSON TYPE, never the payload. The parse
+  // succeeded, so the bytes add nothing an operator can act on — and
+  // `tests/lib/ci-status-banner.test.mjs` § "unexpected benign pipeline
+  // metadata" pins that a well-formed-but-wrong-shaped API body must not have
+  // its contents echoed anywhere. A type name carries no body content.
+  const actual = jsonTypeOf(parsed);
+  if (expect === 'array' && actual !== 'array') {
+    throw new Error(`${label} returned JSON of an unexpected shape — expected an array, got ${actual}`);
+  }
+  if (expect === 'object' && actual !== 'object') {
+    throw new Error(`${label} returned JSON of an unexpected shape — expected an object, got ${actual}`);
+  }
+  return parsed;
+}
+
 /**
  * The one failure this probe can produce that the frozen
  * `REMOTE_RESOLUTION_REASONS` set has no member for: the async timeout race
@@ -201,16 +323,17 @@ async function getHeadSha(repoRoot, deps = {}) {
  * @param {string} apiPath
  * @param {string} repoRoot
  * @param {{ execFile?: Function, timeoutMs?: number, repoHost: string }} deps
+ * @param {'object'|'array'} [expect]  Required payload shape (see `parseCliJson`)
  * @returns {Promise<unknown>}
  */
-async function glabApi(apiPath, repoRoot, deps = {}) {
+async function glabApi(apiPath, repoRoot, deps = {}, expect = undefined) {
   const args = ['api', apiPath, '--hostname', deps.repoHost];
   const result = await execWithTimeout(
     'glab',
     args,
     { cwd: repoRoot, timeoutMs: deps.timeoutMs ?? DEFAULT_TIMEOUT_MS, execFile: deps.execFile },
   );
-  return JSON.parse(result.stdout);
+  return parseCliJson(result.stdout, `glab api ${apiPath}`, expect);
 }
 
 /**
@@ -222,9 +345,10 @@ async function glabApi(apiPath, repoRoot, deps = {}) {
  * @param {string} apiPath
  * @param {string} repoRoot
  * @param {{ execFile?: Function, timeoutMs?: number, repoHost?: string }} deps
+ * @param {'object'|'array'} [expect]  Required payload shape (see `parseCliJson`)
  * @returns {Promise<unknown>}
  */
-async function ghApi(apiPath, repoRoot, deps = {}) {
+async function ghApi(apiPath, repoRoot, deps = {}, expect = undefined) {
   const args = ['api', apiPath];
   if (deps.repoHost) args.push('--hostname', deps.repoHost);
   const result = await execWithTimeout(
@@ -232,7 +356,7 @@ async function ghApi(apiPath, repoRoot, deps = {}) {
     args,
     { cwd: repoRoot, timeoutMs: deps.timeoutMs ?? DEFAULT_TIMEOUT_MS, execFile: deps.execFile },
   );
-  return JSON.parse(result.stdout);
+  return parseCliJson(result.stdout, `gh api ${apiPath}`, expect);
 }
 
 /**
@@ -276,14 +400,18 @@ async function checkGitlab(repoRoot, now, deps = {}) {
   const currentSha = await getHeadSha(repoRoot, deps);
   const apiDeps = { ...deps, repoHost: project.host };
   const projectPath = `projects/${project.encodedProjectPath}`;
+  // `'array'` is load-bearing, not decoration: before it, a `glab api` that
+  // returned valid JSON of the wrong shape (`null`, `"ok"`, an object) fell
+  // into `!Array.isArray(pipelines) → return null` — a SILENT no-op an operator
+  // reads as "nothing to report". It now raises the same named error an
+  // unparseable payload does, so the outer catch warns.
   const pipelines = await glabApi(
     `${projectPath}/pipelines?order_by=updated_at&sort=desc&per_page=15`,
     repoRoot,
     apiDeps,
+    'array',
   );
 
-  if (!Array.isArray(pipelines)) return null;
-
   const currentPipeline = pipelines.find((p) => p.sha === currentSha);
 
   if (!currentPipeline) {
@@ -312,6 +440,7 @@ async function checkGitlab(repoRoot, now, deps = {}) {
         `${projectPath}/pipelines/${currentPipeline.id}/jobs`,
         repoRoot,
         apiDeps,
+        'array',
       );
       if (Array.isArray(jobs)) {
         const softFailed = jobs
@@ -379,6 +508,7 @@ async function checkGitlab(repoRoot, now, deps = {}) {
         `${projectPath}/pipelines/${currentPipeline.id}/jobs`,
         repoRoot,
         apiDeps,
+        'array',
       );
       if (Array.isArray(jobs)) {
         const failedJob = jobs.find((j) => j.status === 'failed');
@@ -450,12 +580,22 @@ async function checkGithub(repoRoot, deps = {}) {
     repoViewArgs,
     { cwd: repoRoot, timeoutMs: deps.timeoutMs ?? DEFAULT_TIMEOUT_MS, execFile: deps.execFile },
   );
-  const { nameWithOwner } = JSON.parse(repoViewResult.stdout);
+  // `'object'` before the destructuring: a `gh repo view` that printed `null`
+  // (or a bare string, or an array) used to throw a bare
+  // `TypeError: Cannot destructure property 'nameWithOwner' of 'null'`, whose
+  // message names neither the CLI nor the request — the exact identification
+  // failure this helper exists to fix.
+  const { nameWithOwner } = parseCliJson(
+    repoViewResult.stdout,
+    `gh ${repoViewArgs.join(' ')}`,
+    'object',
+  );
 
   const data = await ghApi(
     `repos/${nameWithOwner}/commits/HEAD/check-runs`,
     repoRoot,
     deps,
+    'object',
   );
 
   const checkRuns = data.check_runs;
@@ -516,12 +656,19 @@ async function checkGithub(repoRoot, deps = {}) {
  *     or >= 2 remotes with no preference match) — a benign, measured absence
  *   - Required CLI (glab / gh) not in PATH
  *   - Any CLI invocation times out
- *   - JSON parse failure on CLI output
  *
  * Also returns `null`, but with a `console.warn` trace, when the VCS-detection
- * QUERY ITSELF failed (`git` not on PATH, `git remote -v` erroring) or when a
- * present CLI rejected its invocation. `null` alone cannot express "could not
- * read" — see the outer catch and Step 1 for why the warn channel carries it.
+ * QUERY ITSELF failed (`git` not on PATH, `git remote -v` erroring), when a
+ * present CLI rejected its invocation, or when a CLI returned output this
+ * module could not parse (see {@link parseCliJson}). `null` alone cannot
+ * express "could not read" — see the outer catch and Step 1 for why the warn
+ * channel carries it.
+ *
+ * The unparseable-output case was listed above as SILENT until 2026-08-28.
+ * That was never the behaviour — it has always fallen through to the outer
+ * catch's warn branch (measured at 30940cb). The drift survived because the
+ * one test covering it asserted only the `null` and let the file-wide
+ * `console.warn` spy swallow the rest.
  *
  * @param {{
  *   repoRoot?: string,

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/command-blocker.mjs

@@ -648,12 +648,57 @@ export function tokenizeCommand(command) {
   return tokens;
 }
 
+/**
+ * Shell RESERVED WORDS and grouping tokens that bash recognises ONLY in COMMAND
+ * POSITION — the first word of a statement (#1145). Everywhere else they are
+ * ordinary arguments (`echo do`, `git commit -m then`), which is exactly why the
+ * drop below is position-gated rather than a blanket text filter.
+ *
+ * Two classes, both dropped, for the same reason:
+ *   - OPENERS (`{`, `(`, `!`, `if`, `elif`, `then`, `else`, `while`, `until`,
+ *     `do`) are followed by a COMMAND. Dropping one moves verb resolution
+ *     towards the real command — the identical safety argument WRAPPER_UNWRAP
+ *     makes for a transparent wrapper: a dropped token is a reserved word, never
+ *     an interpreter, so this cannot turn a match into a miss.
+ *   - CLOSERS (`}`, `)`, `fi`, `done`, `esac`) end one. In command position they
+ *     are the whole segment, which then filters out as empty.
+ *
+ * Deliberately NOT listed:
+ *   - `for` / `select` / `case` / `in` / `function` — followed by a NAME or WORD,
+ *     never a command. Dropping them would invent a verb (`for t in a` → `t`)
+ *     where the truthful answer is "this segment has no command".
+ *   - `time` — a reserved word AND an external binary, already classified as a
+ *     transparent wrapper in WRAPPER_UNWRAP. One classification per token, in
+ *     one table: a second entry here would fork the wrapper-vs-keyword decision
+ *     the way `VERB_PREFIXES` once forked WRAPPER_UNWRAP (#991).
+ *
+ * NAMED CEILING (BV-004): only a STANDALONE token is dropped. bash requires
+ * whitespace around `{` / `}`, so brace groups are always covered; a subshell
+ * written WITHOUT the space (`(rm -rf /)`) lexes as the glued word `(rm` and is
+ * not reached — the pre-#1145 behaviour, unchanged. Peeling the paren off the
+ * token TEXT would mutate a token five consumers read positionally, which is a
+ * larger contract change than this defect justifies. Revisit if a glued-paren
+ * form shows up in a real overflow triage or guard-bypass measurement.
+ */
+const COMMAND_POSITION_KEYWORDS = new Set([
+  '{', '(', '!', 'if', 'elif', 'then', 'else', 'while', 'until', 'do',
+  '}', ')', 'fi', 'done', 'esac',
+]);
+
 /**
  * Split a tokenized command into chained segments on shell control operators
  * (`;`, `&&`, `||`, `|`, `&`) and on newline separators (#981). Only UNQUOTED
  * single-token operators split; an operator that arrived inside quotes stays
  * part of its segment.
  *
+ * A segment additionally has its COMMAND-POSITION reserved words stripped
+ * (#1145) — see {@link COMMAND_POSITION_KEYWORDS}. Without this the first token
+ * of a compound statement is `do` / `then` / `{` / `(` and NEVER the command,
+ * so every consumer that reads a segment head saw a keyword: measured against
+ * the live issue-budget guard with `max-per-session: 1, mode: strict`,
+ * `for t in a b c; do glab issue create …; done` and `{ glab issue create …; }`
+ * were allowed with NO accounting at all, while the plain form denied at 1/1.
+ *
  * The newline separator is checked by its `operator` field as well as its text,
  * so the split survives a future change to that token's spelling. Because a
  * separator token is CONSUMED here, it can never reach a per-segment operand
@@ -678,6 +723,13 @@ function splitSegments(tokens) {
       current = [];
       continue;
     }
+    // Reserved word in COMMAND POSITION (`current` still empty) → drop it, so
+    // the NEXT token becomes the segment head and is itself judged in command
+    // position (`do { rm …` peels both). A keyword anywhere else is an ordinary
+    // argument and is kept verbatim (#1145).
+    if (current.length === 0 && !tok.quoted && COMMAND_POSITION_KEYWORDS.has(tok.text)) {
+      continue;
+    }
     current.push(tok);
   }
   segments.push(current);
@@ -763,6 +815,24 @@ export const WRAPPER_UNWRAP = new Map([
   }],
   ['command', {}],
   ['nohup', {}],
+  // `exec cmd args` REPLACES the shell with `cmd` — it delegates to a real verb
+  // and never executes a command STRING, so by the #982 classification it is a
+  // TRANSPARENT wrapper, not an interpreter (contrast `su -c`, which is in
+  // SHELL_EXEC_INTERPRETERS for exactly the opposite reason). `-a NAME` is the
+  // one value-taking flag; `-c` (clear environment) and `-l` are BOOLEANS here
+  // — despite the spelling, `exec -c` carries no payload, so it must NOT reach
+  // DASH_C_SHELLS, and it does not: that set is keyed on the RESOLVED verb.
+  // Redirect-only `exec > file` keeps working. Measured both namespaces: on the
+  // RAW segment the wrapper consumes `exec` and the redirect operator resolves
+  // as the verb (`>`, previously `exec`); on scope-gate's paren-peeled,
+  // redirect-stripped projection the segment exhausts in wrappers and yields
+  // `verb: null, index: -1` — the shape a bare `sudo` already produced. Neither
+  // is `rm`/`tee`/`sed`/`dd`, and a redirect target is read from the redirect
+  // token stream rather than from the verb, so detection is unaffected:
+  // measured `extractBashWriteTargets('exec > src/out.ts')` → `['src/out.ts']`.
+  ['exec', {
+    argFlags: new Set(['-a']),
+  }],
   // `-o FILE` is the BSD/GNU `time` report destination and it TRUNCATES without
   // `-a` (BSD time(1): "If file exists and the -a flag is not specified, the
   // file will be overwritten"). With an empty spec the operand was read as the

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

@@ -31,6 +31,11 @@
  *
  * The two `**` markers are independent (`**key:` and `key:**` both match),
  * mirroring the tolerant #823 vault-integration regex.
+ *
+ * `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 +78,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/discovery-validator.mjs

@@ -10,6 +10,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,14 +26,14 @@ 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/);