session-orchestrator 3.22.0 → 3.24.0

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

@@ -0,0 +1,233 @@
+import { matchBlockHeader } from './block-header.mjs';
+
+/**
+ * remote-hosts.mjs — Parser for the `remote-hosts:` Session Config block (#1160).
+ *
+ * Lets a repo DECLARE ssh-reachable hosts that heavy wave roles (test / ui / perf)
+ * may be offloaded to instead of shrinking the wave under local resource pressure.
+ * This module only declares — it never probes the network, never dispatches, and
+ * never decides. Placement is `scripts/lib/wave-resource-gate.mjs`; the dispatch
+ * adapter lives in `scripts/lib/wave-executor/`.
+ *
+ * Exports:
+ *   REMOTE_HOST_DEFAULTS  — per-host defaults
+ *   ALLOWED_REMOTE_ROLES  — the agent-mapping roles a host may accept
+ *   _parseRemoteHosts(content) — PURE, no side effects beyond a stderr WARN when a
+ *                                record is dropped. Returns [] when absent/empty.
+ *
+ * Block shape:
+ *   remote-hosts:
+ *     - alias: m5                        # required; becomes `-H <alias>` argv
+ *       roles-allowed: [test, ui, perf]  # subset of ALLOWED_REMOTE_ROLES
+ *       repo-path: ~/Projects/Alice   # optional
+ *       claude-path: ~/.local/bin/claude # optional
+ *
+ * Modelled on custom-phases.mjs (per-entry SAFE-regex validation, drop-with-warn,
+ * column-0 block termination, silent enum fallback). The one shape it adds is the
+ * inline `[a, b]` list for `roles-allowed`.
+ */
+
+/** Per-host defaults. */
+export const REMOTE_HOST_DEFAULTS = Object.freeze({
+  'roles-allowed': ['test', 'ui', 'perf'],
+  'repo-path': null,
+  'claude-path': null,
+});
+
+/**
+ * The roles a remote host may accept. A deliberate SUBSET of `ALLOWED_ROLES` in
+ * scripts/lib/config.mjs — impl / db / security / compliance / docs stay local.
+ *
+ * NOT the wave-role enum ("Impl-Core", "Quality", …): those are two different
+ * enums and conflating them is the documented trap (see resolveApwCap's docstring
+ * in wave-resource-gate.mjs). The wave→agent-mapping-role translation is
+ * `OFFLOADABLE_WAVE_ROLES` in that same module.
+ *
+ * @type {readonly string[]}
+ */
+export const ALLOWED_REMOTE_ROLES = Object.freeze(['test', 'ui', 'perf']);
+
+// A host `alias` is an ssh destination that reaches argv as `-H <alias>`: letters,
+// digits, hyphen, underscore, dot only. No spaces, no shell metacharacters.
+//
+// The first character is anchored separately from the rest because a charset
+// cannot express a POSITION: an alias of `-H` passes any hyphen-inclusive
+// allowlist and then reaches argv as an OPTION token, where the CLI swallows the
+// operand behind it. Interior hyphens (`m5-box`) stay legal.
+const SAFE_NAME_RE = /^[A-Za-z0-9._][A-Za-z0-9._-]*$/;
+
+// `repo-path` / `claude-path` are filesystem paths handed to a remote shell —
+// same allowlist as custom-phases' `review`, with the same leading-hyphen anchor
+// as SAFE_NAME_RE above (`--x` is a flag, not a path).
+const SAFE_PATH_RE = /^[A-Za-z0-9._~/][A-Za-z0-9._~/-]*$/;
+
+/**
+ * Parse the top-level `remote-hosts:` YAML list block from markdown content.
+ *
+ * A record missing `alias`, or carrying an unsafe `alias` / `repo-path` /
+ * `claude-path`, is DROPPED with a stderr WARN. Unknown entries in
+ * `roles-allowed` are filtered out with a WARN; a record whose list is empty
+ * after filtering is dropped (it could never be selected anyway).
+ *
+ * @param {string} content — full CLAUDE.md / AGENTS.md file content
+ * @returns {Array<{alias: string, 'roles-allowed': string[], 'repo-path': string|null, 'claude-path': string|null}>}
+ */
+export function _parseRemoteHosts(content) {
+  const lines = String(content ?? '').split(/\r?\n/);
+  let inBlock = false;
+  const blockLines = [];
+
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/\r$/, '');
+
+    if (!inBlock) {
+      if (matchBlockHeader(line, 'remote-hosts')) inBlock = true;
+      continue;
+    }
+
+    // Block terminates at the first non-indented, non-empty line (next top-level key).
+    if (line.length > 0 && !/^\s/.test(line)) break;
+
+    blockLines.push(line);
+  }
+
+  if (blockLines.length === 0) return [];
+
+  const records = [];
+  /** @type {Record<string, string>|null} */
+  let current = null;
+
+  const flush = () => {
+    if (current === null) return;
+    const rec = _validateRecord(current);
+    if (rec !== null) records.push(rec);
+    current = null;
+  };
+
+  for (const rawLine of blockLines) {
+    // Strip inline comments + trailing whitespace, preserve leading indent.
+    const clean = rawLine.replace(/\s*#.*$/, '').replace(/\s+$/, '');
+    if (!clean.trim()) continue;
+
+    const dashMatch = clean.match(/^\s*-\s+(.*)$/);
+    if (dashMatch) {
+      flush();
+      current = {};
+      const inlineKv = dashMatch[1].match(/^([a-zA-Z][a-zA-Z0-9_-]*):\s*(.*)$/);
+      if (inlineKv) _assignKv(current, inlineKv[1], inlineKv[2]);
+      continue;
+    }
+
+    const kvMatch = clean.match(/^\s+([a-zA-Z][a-zA-Z0-9_-]*):\s*(.*)$/);
+    if (kvMatch && current !== null) {
+      _assignKv(current, kvMatch[1], kvMatch[2]);
+    }
+  }
+
+  flush();
+
+  return records;
+}
+
+/**
+ * Assign a raw key/value onto a record being built, stripping surrounding quotes.
+ * Unknown keys are silently ignored (additive-friendly).
+ *
+ * @param {Record<string, string>} record
+ * @param {string} key
+ * @param {string} rawValue
+ */
+function _assignKv(record, key, rawValue) {
+  let v = rawValue.trim();
+  if (v.startsWith('"') && v.endsWith('"') && v.length >= 2) v = v.slice(1, -1);
+  else if (v.startsWith("'") && v.endsWith("'") && v.length >= 2) v = v.slice(1, -1);
+
+  switch (key) {
+    case 'alias':
+    case 'roles-allowed':
+    case 'repo-path':
+    case 'claude-path':
+      record[key] = v;
+      break;
+    default:
+      break;
+  }
+}
+
+/**
+ * Parse an inline `[a, b]` (or bare `a, b`) list into trimmed non-empty strings.
+ *
+ * @param {string} raw
+ * @returns {string[]}
+ */
+function _parseInlineList(raw) {
+  const inner = raw.trim().replace(/^\[/, '').replace(/\]$/, '');
+  return inner
+    .split(',')
+    .map((s) => s.trim().replace(/^["']|["']$/g, ''))
+    .filter((s) => s !== '');
+}
+
+/**
+ * Validate + normalise a raw record.
+ *
+ * @param {Record<string, string>} raw
+ * @returns {{alias: string, 'roles-allowed': string[], 'repo-path': string|null, 'claude-path': string|null}|null}
+ */
+function _validateRecord(raw) {
+  const alias = (raw.alias ?? '').trim();
+  if (alias === '') {
+    process.stderr.write('remote-hosts: dropped record missing required field: alias\n');
+    return null;
+  }
+  if (!SAFE_NAME_RE.test(alias)) {
+    process.stderr.write(
+      `remote-hosts: dropped record with unsafe alias: ${JSON.stringify(alias)}\n`,
+    );
+    return null;
+  }
+
+  let rolesAllowed = [...REMOTE_HOST_DEFAULTS['roles-allowed']];
+  const rawRoles = (raw['roles-allowed'] ?? '').trim();
+  if (rawRoles !== '') {
+    const declared = _parseInlineList(rawRoles);
+    const kept = declared.filter((r) => ALLOWED_REMOTE_ROLES.includes(r));
+    const dropped = declared.filter((r) => !ALLOWED_REMOTE_ROLES.includes(r));
+    if (dropped.length > 0) {
+      process.stderr.write(
+        `remote-hosts: host '${alias}' declares unknown role(s) ${dropped.join(', ')} ` +
+          `(allowed: ${ALLOWED_REMOTE_ROLES.join(', ')}) — ignored\n`,
+      );
+    }
+    if (kept.length === 0) {
+      process.stderr.write(
+        `remote-hosts: dropped record '${alias}' — roles-allowed is empty after filtering\n`,
+      );
+      return null;
+    }
+    rolesAllowed = kept;
+  }
+
+  const paths = {};
+  for (const key of ['repo-path', 'claude-path']) {
+    let value = REMOTE_HOST_DEFAULTS[key];
+    const rawPath = (raw[key] ?? '').trim();
+    if (rawPath !== '' && rawPath !== 'null' && rawPath !== 'none') {
+      if (!SAFE_PATH_RE.test(rawPath)) {
+        process.stderr.write(
+          `remote-hosts: dropped record '${alias}' with shell metacharacter in ${key}: ${JSON.stringify(rawPath)}\n`,
+        );
+        return null;
+      }
+      value = rawPath;
+    }
+    paths[key] = value;
+  }
+
+  return {
+    alias,
+    'roles-allowed': rolesAllowed,
+    'repo-path': paths['repo-path'],
+    'claude-path': paths['claude-path'],
+  };
+}

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