session-orchestrator 3.23.0 → 3.24.0

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/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/);

package/scripts/lib/config/health-endpoints.mjs

@@ -0,0 +1,383 @@
+/**
+ * health-endpoints.mjs — Content-scoped parser for the `health-endpoints:`
+ * Session Config key, plus the block-form reading of `ecosystem-health:`.
+ *
+ * WHY THIS EXISTS (#1174): `health-endpoints` was read off the FLAT KV map via
+ * `_coerceList`, which bails to `null` the moment a value contains `{` and
+ * cannot see a nested YAML block at all. The ecosystem wizard
+ * (`scripts/lib/ecosystem-wizard/config-writer.mjs` `_buildEcosystemSnippetLines`)
+ * writes exactly the block form:
+ *
+ *   ecosystem-health:
+ *     health-endpoints:
+ *       - name: API
+ *         url: https://api.example.com/health
+ *
+ * Measured before the fix: the flat KV map ended up with bare `name` / `url`
+ * entries (last one wins → silent data loss), `health-endpoints` resolved to
+ * `null`, and because the header line `ecosystem-health:` carries no value it
+ * never matched the KV regex either — so the whole feature stayed dark while
+ * the wizard reported success. Consumers (`skills/ecosystem-health/SKILL.md`,
+ * `docs/session-config-reference.md`) expect an array of `{ name, url }`.
+ *
+ * ACCEPTED FORMS (contract — every one of these is written by some producer in
+ * this repo today):
+ *
+ *   A) inline object array (docs/USER-GUIDE.md):
+ *      health-endpoints: [{name: "API", url: "https://a/health"}, {name: "W", url: "http://w:8080/z"}]
+ *
+ *   B) nested block, top-level OR one level under `ecosystem-health:`
+ *      (the wizard's output, skills/ecosystem-health/wizard.md):
+ *      health-endpoints:
+ *        - name: API
+ *          url: https://a/health
+ *      Block list items may themselves be inline objects
+ *      (`- { name: API, url: … }`) — the form docs/session-config-template.md
+ *      uses.
+ *
+ *   C) bare list of URLs — each URL becomes its own name
+ *      (`{ name: <url>, url: <url> }`). Both spellings are accepted, because
+ *      an operator extending the wizard's BLOCK by hand writes the block one:
+ *        health-endpoints: [https://a/health, https://b/health]
+ *      and
+ *        health-endpoints:
+ *          - https://a/health
+ *
+ *   Empty list (`[]`) → `[]`. `none` / `null` / key absent → `null`.
+ *
+ * NOT accepted (deliberately): the `name=url` shorthand. An item carrying `=`
+ * is treated verbatim as a Form-C URL, never split.
+ *
+ * Malformed input (an entry missing `name` or `url`, an unmatched brace) →
+ * `null` plus exactly ONE `console.warn` line prefixed `config: health-endpoints:`.
+ * Never throws: a broken config key must not take down every session-start.
+ *
+ * Consumers: `scripts/lib/config.mjs` (`health-endpoints`, `ecosystem-health`).
+ *
+ * The header line itself (indent + optional inline value) is matched via the
+ * shared `matchBlockHeaderDetailed()` (#1185) rather than a private regex —
+ * this was the one parser in `scripts/lib/config/` whose header needed BOTH
+ * arbitrary indent (nested under `ecosystem-health:`) AND an inline value
+ * (Form A/C), which the plain `matchBlockHeader()` contract deliberately
+ * excludes. See `scripts/lib/config/block-header.mjs` for the shared matcher.
+ */
+
+import { matchBlockHeader, matchBlockHeaderDetailed } from './block-header.mjs';
+import { _coerceBoolean } from './coercers.mjs';
+
+/**
+ * A scalar that is a URL: a scheme followed by `//`. Used to tell a Form-C
+ * bare-URL list item (`- https://a/health`) from a `key: value` pair
+ * (`- name: API`) inside a block. `https://…` would otherwise match the
+ * key/value regex with key `https`, which is why the check must come first.
+ */
+const URL_SCALAR_RE = /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//;
+
+/**
+ * Strip a trailing YAML comment. Only a `#` PRECEDED BY WHITESPACE counts, so a
+ * URL fragment (`https://a/health#frag`) survives untouched.
+ * @param {string} s
+ * @returns {string}
+ */
+function stripComment(s) {
+  return s.replace(/\s+#.*$/, '');
+}
+
+/**
+ * Strip one layer of matching surrounding quotes.
+ * @param {string} v
+ * @returns {string}
+ */
+function unquote(v) {
+  if (v.length >= 2 && ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'")))) {
+    return v.slice(1, -1);
+  }
+  return v;
+}
+
+/**
+ * Split on commas that sit at brace/bracket depth 0 and outside quotes — so a
+ * comma inside a quoted URL never splits an entry.
+ * @param {string} s
+ * @returns {string[]}
+ */
+function splitTopLevel(s) {
+  const out = [];
+  let depth = 0;
+  let quote = null;
+  let cur = '';
+  for (const ch of s) {
+    if (quote) {
+      cur += ch;
+      if (ch === quote) quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") { quote = ch; cur += ch; continue; }
+    if (ch === '{' || ch === '[') depth++;
+    else if (ch === '}' || ch === ']') depth--;
+    if (ch === ',' && depth === 0) { out.push(cur); cur = ''; continue; }
+    cur += ch;
+  }
+  out.push(cur);
+  return out;
+}
+
+/**
+ * Split `{…}, {…}` into the inner text of each object. Quote-aware, so a `}`
+ * inside a quoted value does not close an object.
+ * @param {string} s
+ * @returns {string[]|null} null on an unmatched brace.
+ */
+function splitObjects(s) {
+  const out = [];
+  let depth = 0;
+  let quote = null;
+  let cur = '';
+  for (const ch of s) {
+    if (quote) {
+      if (depth > 0) cur += ch;
+      if (ch === quote) quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      if (depth > 0) cur += ch;
+      continue;
+    }
+    if (ch === '{') {
+      depth++;
+      if (depth === 1) { cur = ''; continue; }
+    } else if (ch === '}') {
+      depth--;
+      if (depth < 0) return null;
+      if (depth === 0) { out.push(cur); cur = ''; continue; }
+    }
+    if (depth > 0) cur += ch;
+  }
+  if (depth !== 0 || quote) return null;
+  return out;
+}
+
+/**
+ * Parse the inner text of one `{ name: X, url: Y }` object.
+ * @param {string} inner
+ * @returns {{name: string, url: string}|null} null when name or url is missing.
+ */
+function parseObjectBody(inner) {
+  let name = null;
+  let url = null;
+  for (const pair of splitTopLevel(inner)) {
+    const colonIdx = pair.indexOf(':');
+    if (colonIdx === -1) continue;
+    const k = pair.slice(0, colonIdx).trim().toLowerCase();
+    const v = unquote(pair.slice(colonIdx + 1).trim());
+    if (k === 'name') name = v;
+    else if (k === 'url') url = v;
+  }
+  if (!name || !url) return null;
+  return { name, url };
+}
+
+/**
+ * Parse an inline value (everything right of `health-endpoints:` on one line).
+ * @param {string} raw
+ * @returns {{ok: true, value: {name: string, url: string}[]|null} | {ok: false}}
+ */
+function parseInlineValue(raw) {
+  let v = raw.trim();
+  // A trailing comment is only stripped when the value ends with `]` — that
+  // keeps `#` inside an unbracketed value (a URL fragment) intact.
+  const bracketed = v.match(/^(\[.*\])\s*(?:#.*)?$/s);
+  if (bracketed) v = bracketed[1];
+
+  if (v === '' || v === 'none' || v === 'null') return { ok: true, value: null };
+
+  const stripped = v.replace(/^\[/, '').replace(/\]$/, '').trim();
+  if (stripped === '') return { ok: true, value: [] };
+
+  if (stripped.includes('{')) {
+    const bodies = splitObjects(stripped);
+    if (bodies === null) return { ok: false };
+    const entries = [];
+    for (const body of bodies) {
+      const entry = parseObjectBody(body);
+      if (entry === null) return { ok: false };
+      entries.push(entry);
+    }
+    return entries.length === 0 ? { ok: false } : { ok: true, value: entries };
+  }
+
+  // Form C — bare list of URLs; the URL is its own name.
+  const urls = splitTopLevel(stripped).map((s) => unquote(s.trim())).filter((s) => s.length > 0);
+  if (urls.length === 0) return { ok: true, value: [] };
+  return { ok: true, value: urls.map((u) => ({ name: u, url: u })) };
+}
+
+/**
+ * Parse the indented block that follows a valueless `health-endpoints:` header.
+ * Terminates at the first non-blank line indented no deeper than the header —
+ * the same rule `issue-budget.mjs` uses, generalised so a header nested under
+ * `ecosystem-health:` terminates correctly too.
+ *
+ * @param {string[]} lines — all document lines
+ * @param {number} start — index of the first line after the header
+ * @param {number} headerIndent — indent width of the header line
+ * @returns {{ok: true, value: {name: string, url: string}[]|null} | {ok: false}}
+ */
+function parseBlock(lines, start, headerIndent) {
+  /** @type {{name: string|null, url: string|null}[]} */
+  const entries = [];
+  let cur = null;
+
+  for (let i = start; i < lines.length; i++) {
+    const line = lines[i].replace(/\r$/, '');
+    if (line.trim() === '') continue;
+    const indent = line.match(/^[ \t]*/)[0].length;
+    if (indent <= headerIndent) break;
+
+    const clean = stripComment(line).replace(/\s+$/, '');
+    if (clean.trim() === '') continue;
+
+    const itemMatch = clean.match(/^[ \t]*-\s*(.*)$/);
+    if (itemMatch) {
+      const rest = itemMatch[1].trim();
+      if (rest.startsWith('{')) {
+        const bodies = splitObjects(rest);
+        if (bodies === null || bodies.length === 0) return { ok: false };
+        for (const body of bodies) {
+          const entry = parseObjectBody(body);
+          if (entry === null) return { ok: false };
+          entries.push(entry);
+        }
+        cur = null;
+        continue;
+      }
+      // Form C inside a block: a bare URL item is its own name — the same rule
+      // the inline form applies. Without this, `- https://a/health` fell into
+      // assignKV, matched as key `https`, and the whole key WARNed to null
+      // while the identical inline list parsed fine.
+      const scalar = unquote(rest);
+      if (URL_SCALAR_RE.test(scalar)) {
+        entries.push({ name: scalar, url: scalar });
+        cur = null;
+        continue;
+      }
+      cur = { name: null, url: null };
+      entries.push(cur);
+      if (rest === '') continue;
+      if (!assignKV(cur, rest)) return { ok: false };
+      continue;
+    }
+
+    const kvMatch = clean.match(/^[ \t]*[a-zA-Z][a-zA-Z0-9_-]*:\s*/);
+    if (!kvMatch) return { ok: false };
+    if (cur === null) return { ok: false };
+    if (!assignKV(cur, clean.trim())) return { ok: false };
+  }
+
+  if (entries.length === 0) return { ok: true, value: null };
+  for (const e of entries) {
+    if (!e.name || !e.url) return { ok: false };
+  }
+  return { ok: true, value: entries.map((e) => ({ name: e.name, url: e.url })) };
+}
+
+/**
+ * Assign one `key: value` line into an in-progress entry. Unknown keys are
+ * ignored (forward-compatible with a future `timeout:` sub-key); a line that
+ * is not a `key: value` pair at all is a parse failure.
+ *
+ * @param {{name: string|null, url: string|null}} entry
+ * @param {string} text
+ * @returns {boolean} false when the line is not a key/value pair.
+ */
+function assignKV(entry, text) {
+  const m = text.match(/^([a-zA-Z][a-zA-Z0-9_-]*):\s*(.*)$/);
+  if (!m) return false;
+  const k = m[1].toLowerCase();
+  const v = unquote(m[2].trim());
+  if (k === 'name') entry.name = v;
+  else if (k === 'url') entry.url = v;
+  return true;
+}
+
+/**
+ * Parse `health-endpoints` from the raw markdown content.
+ *
+ * Scans the FULL document (not just the `## Session Config` fence), matching
+ * every sibling block parser in this directory, and takes the FIRST
+ * `health-endpoints:` occurrence — top-level or nested under `ecosystem-health:`.
+ *
+ * @param {string} content — full file contents
+ * @returns {{name: string, url: string}[]|null} `null` when absent, explicitly
+ *   `none`/`null`, or malformed (malformed additionally emits one WARN).
+ */
+export function _parseHealthEndpoints(content) {
+  if (typeof content !== 'string' || content === '') return null;
+
+  const lines = content.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].replace(/\r$/, '');
+    const m = matchBlockHeaderDetailed(line, 'health-endpoints');
+    if (!m) continue;
+
+    const headerIndent = m.indent;
+    const inline = m.value ?? '';
+    const result = inline !== ''
+      ? parseInlineValue(inline)
+      : parseBlock(lines, i + 1, headerIndent);
+
+    if (!result.ok) {
+      console.warn(
+        `config: health-endpoints: malformed value at line ${i + 1} — expected a list of {name, url} entries; ignoring.`
+      );
+      return null;
+    }
+    return result.value;
+  }
+  return null;
+}
+
+/**
+ * Read `ecosystem-health` in its BLOCK form (`ecosystem-health:` with no value,
+ * followed by an indented body — what the wizard writes). The scalar form
+ * (`ecosystem-health: true`) is read by the caller off the KV map and takes
+ * precedence; this function only answers the case the KV map cannot see.
+ *
+ * A non-empty block means the feature is configured, hence enabled — unless the
+ * block carries an explicit `enabled: false`.
+ *
+ * @param {string} content — full file contents
+ * @returns {boolean|null} `null` when no block form is present (caller keeps its default).
+ */
+export function _parseEcosystemHealthBlockEnabled(content) {
+  if (typeof content !== 'string' || content === '') return null;
+
+  const lines = content.split(/\r?\n/);
+  let inBlock = false;
+  const blockLines = [];
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/\r$/, '');
+    if (!inBlock) {
+      if (matchBlockHeader(line, 'ecosystem-health')) inBlock = true;
+      continue;
+    }
+    if (line.length > 0 && !/^\s/.test(line)) break;
+    blockLines.push(line);
+  }
+
+  const meaningful = blockLines.filter((l) => stripComment(l).trim() !== '');
+  if (!inBlock || meaningful.length === 0) return null;
+
+  for (const l of meaningful) {
+    const m = stripComment(l).trim().match(/^enabled:\s*(\S+)$/i);
+    // Same truth table as the scalar path — `_coerceBoolean` accepts only
+    // true/false (case-insensitively) and THROWS on anything else. A local
+    // `=== 'true'` comparison silently mapped `yes` to false, so the block form
+    // disagreed with `ecosystem-health: yes` on the very same document.
+    // NB: `_coerceBoolean` uses its `key` argument for BOTH the map lookup and
+    // the error text, so the synthetic map must be keyed by that same string.
+    if (m) return _coerceBoolean(new Map([['ecosystem-health.enabled', m[1]]]), 'ecosystem-health.enabled', false);
+  }
+  return true;
+}