session-orchestrator 3.22.0 → 3.23.0

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/reconcile.mjs

@@ -24,6 +24,76 @@ import { matchBlockHeader } from './block-header.mjs';
  * Consumers: `scripts/lib/config.mjs`, `skills/session-end/SKILL.md` Phase 3.6.8.
  */
 
+/**
+ * CLOSED set of valid `reconcile.targets` members.
+ *
+ * At module scope on purpose: `targets` has TWO parse sites (the bracket-list
+ * branch and the bare-scalar `case 'targets'`), whereas `mode` has one. An
+ * inline literal duplicated across two sites is a second register that drifts —
+ * the shape mirrors `VALID_MODES` below, hoisted because the duplication is real.
+ *
+ * `global` is documented-but-unimplemented and is deliberately NOT a member:
+ * admitting a value nothing implements is the same defect class as the
+ * unvalidated pass-through this constant replaces.
+ */
+const VALID_TARGETS = Object.freeze(['repo-local', 'baseline']);
+
+/** Fallback when every declared target was dropped (mirrors the `defaults` object). */
+const DEFAULT_TARGETS = Object.freeze(['repo-local']);
+
+/**
+ * Report dropped `reconcile.targets` members on stderr.
+ *
+ * stderr, NEVER stdout: `scripts/lib/config.mjs` consumers parse this parser's
+ * downstream output as JSON, so a diagnostic on stdout would corrupt it.
+ *
+ * Prior art for "make an attributable drop VISIBLE, not merely recorded":
+ * `warnDroppedStoreRecords` in `scripts/lib/reconcile/engine.mjs`.
+ *
+ * @param {string[]} dropped
+ */
+function warnUnknownTargets(dropped) {
+  try {
+    console.warn(
+      `⚠️  reconcile.targets: dropped unknown value(s) ${dropped.map((d) => JSON.stringify(d)).join(', ')} — ` +
+        `valid targets are ${VALID_TARGETS.join(' | ')}. The unknown value is IGNORED (no rule is ` +
+        `written for it); if every declared target was dropped, the parser falls back to ` +
+        `[${DEFAULT_TARGETS.join(', ')}].`,
+    );
+  } catch {
+    // A diagnostic must never become the failure it reports on.
+  }
+}
+
+/**
+ * Keep only {@link VALID_TARGETS} members, de-duplicated, order-preserving.
+ *
+ * Rejection is DROP + WARN, never a throw — not even under `enforcement: strict`:
+ *  (a) this module's stated contract ("Tolerant parser: malformed values silently
+ *      fall back to defaults") is obeyed by every other key here; making one key
+ *      throw is an internal inconsistency;
+ *  (b) `_parseReconcile` runs from `scripts/lib/config.mjs` at session-start, so a
+ *      throw would fail session-start on a config typo;
+ *  (c) the SILENCE was the defect, not the tolerance — the WARN closes it.
+ *
+ * Fail-loud belongs one layer up (`claude-md-drift-check` Check 6 could ERROR on
+ * an unknown value); that is deliberately NOT bundled here.
+ *
+ * @param {string[]} items
+ * @returns {string[]}
+ */
+function filterTargets(items) {
+  const kept = [];
+  const dropped = [];
+  for (const item of items) {
+    if (VALID_TARGETS.includes(item)) kept.push(item);
+    else dropped.push(item);
+  }
+  if (dropped.length > 0) warnUnknownTargets(dropped);
+  const uniq = [...new Set(kept)];
+  return uniq.length > 0 ? uniq : [...DEFAULT_TARGETS];
+}
+
 /**
  * Parse the top-level `reconcile:` YAML block from markdown content.
  *
@@ -32,8 +102,13 @@ import { matchBlockHeader } from './block-header.mjs';
  *   reconcile.mode:              'warn'  — advisory only; rules NEVER auto-applied,
  *                                          every write is operator-AUQ-gated (enum: off|warn)
  *   reconcile.targets:           ['repo-local']
- *                                         — where approved rules are written;
- *                                           repo-local = `.claude/rules/` in v1
+ *                                         — where approved rules are written.
+ *                                           CLOSED enum, see {@link VALID_TARGETS}:
+ *                                           repo-local = `.claude/rules/` in this repo;
+ *                                           baseline   = `<baselineRoot>/proposals/`
+ *                                           (issue #1099). An unknown member is DROPPED
+ *                                           with a stderr WARN — see {@link filterTargets}
+ *                                           for why a drop and not a throw.
  *   reconcile.rule-expiry-days:  null    — CRITICAL: must default to null so the
  *                                          reconcile engine (`emitter.mjs`
  *                                          `computeExpiresAt`) falls back to per-type
@@ -132,7 +207,7 @@ export function _parseReconcile(content) {
         .split(',')
         .map((s) => s.trim())
         .filter(Boolean);
-      if (items.length > 0) targets = items;
+      if (items.length > 0) targets = filterTargets(items);
       continue;
     }
 
@@ -206,7 +281,7 @@ export function _parseReconcile(content) {
       // targets inline-list with no brackets (e.g. targets: repo-local) — single value
       case 'targets': {
         if (v && !v.startsWith('[')) {
-          targets = [v];
+          targets = filterTargets([v]);
         }
         break;
       }

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

@@ -131,7 +131,8 @@ export function findSessionConfigBlock(content, { occurrence = 'first' } = {}) {
 /**
  * Extract the raw ## Session Config block lines from markdown content.
  * - CRLF-tolerant
- * - Skips code fence lines (``` alone on a line)
+ * - Skips code fence lines (``` alone or with an info string)
+ * - Skips lines inside a multi-line `<!-- … -->` block (`htmlCommentSkipper`)
  * - Strips trailing whitespace from each line
  * @param {string} content
  * @returns {string[]} lines of the Session Config block
@@ -140,6 +141,7 @@ export function _extractConfigSection(content) {
   const lines = content.split(/\r?\n/);
   const result = [];
   let inSection = false;
+  const skipHtmlComment = htmlCommentSkipper();
 
   for (const rawLine of lines) {
     const line = rawLine.replace(/\r$/, '');
@@ -152,8 +154,17 @@ export function _extractConfigSection(content) {
     if (inSection) {
       // Next ## header closes the section
       if (/^## /.test(line)) break;
-      // Skip standalone code fences
-      if (line.trim() === '```') continue;
+      // Commented-out config is documentation, not config (#1097 review).
+      // Shared with `collectUnparsableLines` so the two accept-sets cannot
+      // drift — see `htmlCommentSkipper`.
+      if (skipHtmlComment(line)) continue;
+      // Skip code fences — opener WITH an info string included (#1097).
+      // The old predicate was `line.trim() === '```'`, which skips a bare
+      // fence but lets ```` ```yaml ```` through as a config line. Harmless
+      // while an unmatched line was silently dropped; a false "unparsable"
+      // report the moment `collectUnparsableLines` below started naming them —
+      // and the fenced form is what one fleet repo actually writes.
+      if (isCodeFence(line)) continue;
       // Strip trailing whitespace and collect
       result.push(line.replace(/\s+$/, ''));
     }
@@ -162,6 +173,135 @@ export function _extractConfigSection(content) {
   return result;
 }
 
+/**
+ * True when `line` is a fenced-code-block delimiter — a bare ``` / ~~~ or an
+ * opener carrying an info string (```yaml).
+ *
+ * @param {string} line
+ * @returns {boolean}
+ */
+function isCodeFence(line) {
+  return /^\s*(?:```|~~~)/.test(line);
+}
+
+/**
+ * THE multi-line `<!-- … -->` state machine for the Session Config block —
+ * the one place that knows whether a line is commented-out documentation.
+ *
+ * Exported-by-use (same argument as `_matchKVLine`): `_extractConfigSection`
+ * feeds `_parseKV`, and `collectUnparsableLines` classifies — so both call this
+ * and their accept-sets are identical BY CONSTRUCTION. They were not, and the
+ * divergence ran in exactly the dangerous direction: the collector skipped
+ * commented blocks while the extractor read them, so
+ *
+ *     persistence: true
+ *     <!--
+ *     enforcement: strict
+ *     -->
+ *
+ * yielded a LIVE `enforcement: strict` (measured: `_parseKV` returned it) that
+ * `collectUnparsableLines` reported as a clean block — and `parse-config.mjs`
+ * branches its own #1097 gate on `config.enforcement`. Commenting a key out is
+ * the most ordinary way to disable it; it must not arm the strictest path.
+ *
+ * Returns a fresh closure per call — it carries per-document state, so a shared
+ * instance would leak an unterminated comment from one document into the next.
+ *
+ * Ceiling (deliberate): the opener must be at the START of a line
+ * (`/^\s*<!--/`). A comment opened mid-line (`waves: 5 <!--`) therefore does
+ * NOT swallow the following lines — which keeps every single-line trailing
+ * `<!-- … -->` on a heading or key line behaving exactly as before, the form
+ * this repo's own convention encourages. Revisit if a fleet CLAUDE.md is ever
+ * measured opening a multi-line comment after a value.
+ *
+ * @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() {
+  let inComment = false;
+  return function skipHtmlComment(line) {
+    if (inComment) {
+      if (line.includes('-->')) inComment = false;
+      return true;
+    }
+    if (/^\s*<!--/.test(line) && !line.includes('-->')) {
+      inComment = true;
+      return true;
+    }
+    return false;
+  };
+}
+
+/**
+ * Replace C0/C1 control characters with `?` before a line is handed to a
+ * reporter.
+ *
+ * `collectUnparsableLines` returns text taken verbatim from a file that is
+ * itself the thing being reported as malformed, and its only consumer prints
+ * it on stderr after a `WARN unparsable Session Config line N:` prefix. A
+ * planted `\x1b[2K…\r` erases that prefix and rewrites the operator's terminal
+ * line — the report of a defect becoming the vehicle for hiding it. Sanitising
+ * at the SOURCE (rather than at the one printer) means every future consumer
+ * inherits the safe form.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+function sanitizeReportText(text) {
+  // eslint-disable-next-line no-control-regex -- the control chars ARE the target
+  return text.replace(/[\u0000-\u001F\u007F-\u009F]/g, '?');
+}
+
+/**
+ * THE key/value predicate for a Session Config line — the one place that knows
+ * which of the two accepted spellings a line is in.
+ *
+ * Exported-by-use rather than by name: `_parseKV` builds the map from it and
+ * `collectUnparsableLines` decides "this line carries a key" from it, so the
+ * accept-set of the two can never drift. A classifier with its own regex would
+ * eventually report a line the map DID parse (noise) or stay silent on one it
+ * did not (the #1097 defect, unchanged).
+ *
+ * Format 1: `- **key:** value`
+ * Format 2: `key: value`, incl. the YAML list-item form `- key: value` (#497)
+ *   and any leading indentation (sub-keys of a nested block land here too).
+ *
+ * @param {string} line
+ * @returns {{ key: string, value: string } | null} null when the line carries
+ *   no key/value pair in either format.
+ */
+function _matchKVLine(line) {
+  let key;
+  let value;
+
+  // Format 1: - **key:** value
+  const fmt1 = line.match(/^\s*-\s+\*\*([^*:]+):\*\*\s*(.*)/);
+  if (fmt1) {
+    key = fmt1[1].trim();
+    value = fmt1[2].trim();
+  } else {
+    // Format 2: key: value — supports both plain "key: value" and
+    // YAML list-item form "- key: value" (issue #497). Key starts with
+    // letter; rest is alphanum/hyphen/underscore.
+    const fmt2 = line.match(/^\s*(?:-\s+)?([a-zA-Z][a-zA-Z0-9_-]+):\s+(.*)/);
+    if (!fmt2) return null;
+    key = fmt2[1].trim();
+    value = fmt2[2].trim();
+  }
+
+  if (!key) return null;
+
+  // Strip inline YAML comment (matches block-parser behaviour in _parseVaultSync etc.)
+  value = value.replace(/\s+#.*$/, '').trim();
+
+  // Strip surrounding double quotes from value
+  if (value.startsWith('"') && value.endsWith('"') && value.length >= 2) {
+    value = value.slice(1, -1);
+  }
+
+  return { key, value };
+}
+
 /**
  * Parse the key-value pairs from extracted Session Config lines.
  * Supports Format 1: `- **key:** value`
@@ -176,39 +316,9 @@ export function _parseKV(lines) {
 
   for (const line of lines) {
     if (!line.trim()) continue;
-
-    let key;
-    let value;
-
-    // Format 1: - **key:** value
-    const fmt1 = line.match(/^\s*-\s+\*\*([^*:]+):\*\*\s*(.*)/);
-    if (fmt1) {
-      key = fmt1[1].trim();
-      value = fmt1[2].trim();
-    } else {
-      // Format 2: key: value — supports both plain "key: value" and
-      // YAML list-item form "- key: value" (issue #497). Key starts with
-      // letter; rest is alphanum/hyphen/underscore.
-      const fmt2 = line.match(/^\s*(?:-\s+)?([a-zA-Z][a-zA-Z0-9_-]+):\s+(.*)/);
-      if (fmt2) {
-        key = fmt2[1].trim();
-        value = fmt2[2].trim();
-      } else {
-        continue;
-      }
-    }
-
-    if (!key) continue;
-
-    // Strip inline YAML comment (matches block-parser behaviour in _parseVaultSync etc.)
-    value = value.replace(/\s+#.*$/, '').trim();
-
-    // Strip surrounding double quotes from value
-    if (value.startsWith('"') && value.endsWith('"') && value.length >= 2) {
-      value = value.slice(1, -1);
-    }
-
-    allPairs.push([key, value]);
+    const match = _matchKVLine(line);
+    if (!match) continue;
+    allPairs.push([match.key, match.value]);
   }
 
   // Last match wins: build the map by iterating in order
@@ -218,3 +328,92 @@ export function _parseKV(lines) {
   }
   return kv;
 }
+
+// ---------------------------------------------------------------------------
+// Fail-loud: lines inside the block that carry no meaning (#1097)
+// ---------------------------------------------------------------------------
+
+/**
+ * A line that opens a nested block: `vault-integration:` with no value, in any
+ * of the four fleet spellings (column-zero, `- key:`, `**key:**`, `- **key:**`)
+ * and at any indent. Deliberately NOT imported from block-header.mjs: that
+ * matcher answers "does this line open the block for THIS key" for a known key,
+ * while here the key is unknown by construction.
+ */
+const NESTED_BLOCK_HEADER_RE = /^\s*(?:-\s+)?(?:\*\*)?[a-zA-Z][a-zA-Z0-9_.-]*:(?:\*\*)?\s*$/;
+
+/** A YAML sequence element that is not a `key: value` pair (`  - some-value`). */
+const LIST_ITEM_RE = /^\s*-\s+\S/;
+
+/** Documentation, not config: `# yaml comment` and `<!-- html -->` / `> quote`. */
+const COMMENT_RE = /^\s*(?:#|<!--|>)/;
+
+/**
+ * Collect the lines inside `## Session Config` that carry no meaning for any
+ * parser — the fail-loud half of #1097.
+ *
+ * The measured defect this exists to end: a key the extractor cannot read is
+ * simply absent from the KV map, and every consumer then applies its DEFAULT.
+ * For a boolean that default is `false`, so a mis-spelled `vault-integration`
+ * block reads exactly like a deliberately disabled one — no error, anywhere, in
+ * any log (fleet evidence: a repo whose vault mirror sat at
+ * `skipped-vault-disabled` for two months with the key present in its CLAUDE.md).
+ *
+ * A line is accounted for — and therefore NOT reported — when it is:
+ *   blank · a code fence · a `#`/`<!--`/`>` documentation line · a key/value
+ *   pair in either accepted format (`_matchKVLine`) · a nested-block header
+ *   (`key:` with no value) · a bare YAML list element (`- value`).
+ * Everything else is prose sitting where config is expected, which is the only
+ * shape a broken key can take once the six forms above are excluded.
+ *
+ * Line numbers are 1-based and count from the START OF THE DOCUMENT, not from
+ * the block — they are for an operator opening the file at that line. The text
+ * is run through `sanitizeReportText`, because it is quoted straight into a
+ * terminal by the one consumer that prints it.
+ *
+ * The accept-set is shared with the reader, not merely aligned with it: the
+ * `#`/`>` and blank/fence forms are literal here, and the multi-line HTML
+ * comment goes through the same `htmlCommentSkipper` call `_extractConfigSection`
+ * makes. A form the reader accepts but the classifier does not is noise; a form
+ * the READER accepts and the classifier waves through as documentation is the
+ * live-commented-out-key defect this shape exists to make unreachable.
+ *
+ * @param {string} content — full markdown document
+ * @returns {Array<{ line: number, text: string }>} empty when the block is
+ *   well-formed, absent, or the content is not a string.
+ */
+export function collectUnparsableLines(content) {
+  if (typeof content !== 'string' || content === '') return [];
+
+  const lines = content.split(/\r?\n/);
+  const unparsable = [];
+  let inSection = false;
+  const skipHtmlComment = htmlCommentSkipper();
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].replace(/\r$/, '');
+
+    if (isSessionConfigHeading(line)) {
+      inSection = true;
+      continue;
+    }
+    if (!inSection) continue;
+    if (/^## /.test(line)) break;
+
+    // A multi-line HTML comment: everything up to `-->` is documentation.
+    // Same call, same order, as `_extractConfigSection` — that shared call is
+    // what makes the two accept-sets identical rather than merely similar.
+    if (skipHtmlComment(line)) continue;
+
+    if (!line.trim()) continue;
+    if (isCodeFence(line)) continue;
+    if (COMMENT_RE.test(line)) continue;
+    if (_matchKVLine(line)) continue;
+    if (NESTED_BLOCK_HEADER_RE.test(line)) continue;
+    if (LIST_ITEM_RE.test(line)) continue;
+
+    unparsable.push({ line: i + 1, text: sanitizeReportText(line.trim()) });
+  }
+
+  return unparsable;
+}

package/scripts/lib/config-schema.mjs

@@ -8,7 +8,15 @@
  * Never throws. Never mutates input.
  */
 
-const ENFORCEMENT_VALUES = new Set(['strict', 'warn', 'off']);
+/**
+ * The values `enforcement:` accepts. Exported (#1097) so the gates that BRANCH
+ * on enforcement — `scripts/parse-config.mjs`'s unparsable-line gate is the
+ * first — read the same Set the validator judges against, instead of re-typing
+ * the literal `'strict'` beside a schema that could later add a mode.
+ *
+ * @type {Set<string>}
+ */
+export const ENFORCEMENT_VALUES = new Set(['strict', 'warn', 'off']);
 // Exported (issue #836) so cross-layer mode-vocabulary parity tests can use
 // this Set as the single source of truth for "the modes a Session Config
 // `*.mode` key accepts" — rather than re-deriving a duplicate literal list

package/scripts/lib/config.mjs

@@ -14,6 +14,10 @@
  *   events-rotation.mjs   — _parseEventsRotation
  *   vault-integration.mjs — _parseVaultIntegration + _parseResourceThresholds
  *
+ * One parser lives OUTSIDE that directory: `_parseExpressPath` in
+ * scripts/lib/express-path.mjs, alongside the express-path decision it configures.
+ * See that module's header for the reason and the revisit trigger.
+ *
  * Originally ported from parse-config.sh (v2) plus its helper libs
  * config-yaml-parser.sh and config-json-coercion.sh. Windows + CRLF safe.
  *
@@ -72,6 +76,11 @@ import { _parseSkillEvolution } from './config/skill-evolution.mjs';
 import { _parseDispatcherAutonomy, resolveDispatcherAutonomy } from './config/dispatcher-autonomy.mjs';
 import { loadHostPaths, resolveHostPath } from './config/host-paths.mjs';
 import { resolveNamedBaseline } from './named-baseline-resolver.mjs';
+// express-path lives one level UP from config/ (see its module header for why):
+// the parser is a sibling of config/state-md-lock.mjs in every respect except
+// its directory. Only the pure parser is imported here — `evaluateExpressPath`
+// and its telemetry stay out of this module's import graph by construction.
+import { _parseExpressPath } from './express-path.mjs';
 
 // Re-export the two functions that external callers import directly from this module.
 export { _coerceEnum, _coerceCollisionRisk } from './config/coercers.mjs';
@@ -226,24 +235,57 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
   if (agentMapping !== null) {
     // Validate role keys against canonical list from skills/_shared/config-reading.md
     const ALLOWED_ROLES = ['impl', 'test', 'db', 'ui', 'security', 'compliance', 'docs', 'perf'];
+    // Dispatch channels a mapping value may name via a `<channel>:<target>`
+    // prefix (#1150). Without a colon the value is a plain agent name and is
+    // dispatched natively, exactly as before.
+    //   impl: code-implementer      → native Agent dispatch (unchanged)
+    //   impl: cursor:composer-2.5   → foreign model over the Cursor channel
+    // An unknown prefix is a typo or a channel this build cannot route, and
+    // must fail loudly: silently accepting it would dispatch to an agent that
+    // does not exist, which surfaces only as an empty wave much later.
+    const KNOWN_CHANNELS = ['cursor', 'session-orchestrator'];
+    // Accumulate every defect, then report once. A config with two bad entries
+    // must name BOTH — throwing on the first one makes the operator re-run the
+    // parse per defect, and each re-run hides the ones behind it.
     const invalidKeys = [];
+    const valueProblems = [];
     for (const [k, v] of Object.entries(agentMapping)) {
       if (!ALLOWED_ROLES.includes(k)) {
         invalidKeys.push(k);
         continue;
       }
       if (typeof v !== 'string' || v === '') {
-        throw new Error(
-          `config.mjs: agent-mapping role '${k}' has invalid value '${v}' (expected non-empty string)`
-        );
+        valueProblems.push(`role '${k}' has invalid value '${v}' (expected non-empty string)`);
+        continue;
+      }
+      const colonIdx = v.indexOf(':');
+      if (colonIdx !== -1) {
+        const channel = v.slice(0, colonIdx).trim();
+        const target = v.slice(colonIdx + 1).trim();
+        if (!KNOWN_CHANNELS.includes(channel)) {
+          valueProblems.push(
+            `role '${k}' names unknown channel '${channel}' in value '${v}' ` +
+              `(known channels: ${KNOWN_CHANNELS.join(', ')}; a value without ':' is a plain agent name)`
+          );
+        } else if (target === '') {
+          valueProblems.push(
+            `role '${k}' has channel '${channel}' but no target in value '${v}' ` +
+              `(expected '${channel}:<model-or-agent>')`
+          );
+        }
       }
     }
+    const problems = [];
     if (invalidKeys.length > 0) {
-      throw new Error(
-        `config.mjs: agent-mapping contains invalid role key(s): ${invalidKeys.join(', ')} ` +
-          `(allowed: ${ALLOWED_ROLES.join(', ')})`
+      problems.push(
+        `invalid role key(s): ${invalidKeys.join(', ')} (allowed: ${ALLOWED_ROLES.join(', ')})`
       );
     }
+    problems.push(...valueProblems);
+    if (problems.length > 0) {
+      // Still fail loud — only the reporting shape changed, never the verdict.
+      throw new Error(`config.mjs: agent-mapping ${problems.join('; ')}`);
+    }
   }
   const enforcementGates = _coerceBoolObject(kv, 'enforcement-gates');
 
@@ -286,6 +328,14 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
   // events-rotation: parsed from full content (standalone top-level block)
   const eventsRotation = _parseEventsRotation(mdContent);
 
+  // express-path: parsed from full content (standalone top-level block, #214/#1119).
+  // Documented in docs/session-config-template.md:585 and
+  // docs/session-config-reference.md:1519 since #214, but never in the key schema —
+  // measured 2026-08-23, a probe carrying `express-path:\n  enabled: false` produced
+  // 88 keys and none of them was `express-path`. The key was dropped even when it
+  // stood in the file, so the documented default was prose rather than a value.
+  const expressPath = _parseExpressPath(mdContent);
+
   // vault-mirror.quality: parsed from full content (PRD F1.2 / issue #504)
   const vaultMirror = _parseVaultMirrorQuality(mdContent);
 
@@ -482,6 +532,7 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
     'context-coverage': contextCoverage,
     'worktree-orphans': worktreeOrphans,
     'events-rotation': eventsRotation,
+    'express-path': expressPath,
     'test': testConfig,
     'gitlab-portfolio': gitlabPortfolio,
     'wave-reviewers': waveReviewers,

package/scripts/lib/convergence-monitor.mjs

@@ -312,12 +312,23 @@ function evaluateSignals(state, alreadyEmitted, latestWave) {
 }
 
 /**
+ * Poll delay.
+ *
+ * The timer is deliberately NOT `unref()`d: it is the only handle this process
+ * holds, so an unref'd timer drains the event loop and node exits 0 the instant
+ * the first tick is scheduled — a monitor that supervises nothing while looking
+ * like a clean shutdown (it has already emitted `tail.started` and writes
+ * nothing to stderr). Measured 2026-08-25 on the unref'd variant:
+ * `node scripts/lib/convergence-monitor.mjs --tail --interval=1` returned
+ * exit 0 after 47 ms instead of running until SIGTERM. This is the mechanism
+ * behind #980 (convergence-monitor never fires) — the same defect A1 measured
+ * in `scripts/lib/wave-transcript-tail.mjs`, which this sleep() was copied to.
+ *
  * @param {number} ms
  */
 function sleep(ms) {
   return new Promise((resolve) => {
-    const t = setTimeout(resolve, ms);
-    t.unref?.();
+    setTimeout(resolve, ms);
   });
 }