session-orchestrator 3.23.0 → 4.0.0

package/scripts/lib/config/moc-staleness.mjs

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

package/scripts/lib/config/persona-gate-wave.mjs

@@ -20,6 +20,7 @@
 import { parseThreshold } from '../persona-panel/threshold.mjs';
 import { ALLOWED_MODEL_ALIASES, MODEL_ID_RE } from '../agent-frontmatter.mjs';
 import { matchBlockHeader } from './block-header.mjs';
+import { preprocessBlockLines } from './block-preprocess.mjs';
 
 const ALLOWED_AFTER = new Set(['quality', 'impl-polish']);
 const ALLOWED_MODE = new Set(['off', 'warn', 'strict']);
@@ -169,7 +170,7 @@ export function _normalizePersonaGateWave(parsed) {
  * @returns {string[]}
  */
 function _extractBlock(content, key) {
-  const lines = content.split(/\r?\n/);
+  const lines = preprocessBlockLines(content);
   const blockLines = [];
   let inBlock = false;
 

package/scripts/lib/config/private-config-dir.mjs

@@ -0,0 +1,67 @@
+/**
+ * private-config-dir.mjs — THE resolver for the host-private config directory (#1223).
+ *
+ * Every per-host artefact below that directory (`host-private.json`,
+ * `owner.yaml`, the self-alias ledger) moves with it, so the precedence has to
+ * live in exactly ONE place. Before #1223 three copies with three different
+ * precedences existed: `owner-yaml.mjs`'s import-time homedir-only
+ * `OWNER_YAML_PATH`, `owner-config-loader.mjs`'s XDG-only + untrimmed
+ * `resolveOwnerConfigPath()`, and `host-identity.mjs`'s `_privateDir()`. The
+ * live consequence: `SO_CONFIG_HOME=<sandbox>` moved the alias ledger but NOT
+ * owner.yaml, which kept being read from the operator's REAL home — the
+ * CLAUDE.md (Codex CLI alias: AGENTS.md) "vault-dir resolves HOST-LOCALLY"
+ * hazard class.
+ *
+ * ── Why this is a standalone ZERO-IMPORT leaf ────────────────────────────────
+ *
+ * Two independent consumers constrain it, and neither tolerates the other's
+ * import graph:
+ *
+ *   1. `host-identity.mjs` is reachable from LIVE hooks (via `session-lock.mjs`),
+ *      `hooks/on-stop.mjs` among them. on-stop must degrade with one actionable
+ *      line when `node_modules` is absent (GH#63), so nothing on ITS subgraph —
+ *      this leaf included — may pull a bare specifier. Putting the resolver in
+ *      `owner-yaml.mjs` dragged `js-yaml` onto that subgraph and turned the GH#63
+ *      contract red with `ERR_MODULE_NOT_FOUND: Cannot find package 'js-yaml'`.
+ *      Since GitLab #1230 (2026-09-06) `owner-yaml.mjs` resolves `js-yaml`
+ *      lazily, so that particular collision can no longer recur — but the
+ *      constraint on THIS file is unchanged, because it is what let the resolver
+ *      be shared in the first place. Measured 2026-09-06 over a `hooks/` +
+ *      `scripts/` copy with no `node_modules`, the four hooks that reach
+ *      `owner-yaml.mjs` (on-session-start, on-session-end, post-edit-validate,
+ *      skill-invocation-telemetry) now load instead of throwing.
+ *   2. `tests/husky/pre-commit-owner-leakage.test.mjs` copies the CP11 scanner's
+ *      import chain FILE BY FILE into a tmp repo. Every repo-local import added
+ *      to a file on that chain must be added to the copied-file list there.
+ *
+ * Hence: `node:os` + `node:path` only. No repo-local imports, no bare
+ * specifiers beyond the two Node builtins.
+ */
+
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * Resolve the host-private config directory.
+ *
+ * Precedence, most specific first: `SO_CONFIG_HOME` names the private dir
+ * ITSELF; `XDG_CONFIG_HOME` names its PARENT (the `session-orchestrator`
+ * segment is appended); without either, `~/.config/session-orchestrator`.
+ *
+ * `.trim() || fallback` throughout — a whitespace-only env var is truthy and
+ * would short-circuit a bare `||`, returning the spaces verbatim
+ * (`.claude/rules/development.md` § Error Handling, env-var fallback
+ * whitespace trap).
+ *
+ * Reads env at CALL time, so a test may stub `process.env` after import.
+ *
+ * @param {{ env?: Record<string, string|undefined> }} [opts]
+ * @returns {string} absolute path to the host-private config directory
+ */
+export function resolvePrivateConfigDir({ env = process.env } = {}) {
+  const own = (env.SO_CONFIG_HOME || '').trim();
+  if (own) return own;
+  const xdg = (env.XDG_CONFIG_HOME || '').trim();
+  if (xdg) return join(xdg, 'session-orchestrator');
+  return join(homedir(), '.config', 'session-orchestrator');
+}

package/scripts/lib/config/reconcile.mjs

@@ -1,4 +1,5 @@
 import { matchBlockHeader } from './block-header.mjs';
+import { preprocessBlockLines } from './block-preprocess.mjs';
 
 /**
  * reconcile.mjs — Parser for the top-level `reconcile:` YAML block.
@@ -169,7 +170,7 @@ export function _parseReconcile(content) {
     'max-proposals-per-run': 10,
   };
 
-  const lines = content.split(/\r?\n/);
+  const lines = preprocessBlockLines(content);
   let inBlock = false;
   const blockLines = [];
 

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

@@ -0,0 +1,234 @@
+import { matchBlockHeader } from './block-header.mjs';
+import { preprocessBlockLinesNoDash } from './block-preprocess.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 = preprocessBlockLinesNoDash(String(content ?? ''));
+  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

@@ -214,10 +214,16 @@ function isCodeFence(line) {
  * this repo's own convention encourages. Revisit if a fleet CLAUDE.md is ever
  * measured opening a multi-line comment after a value.
  *
+ * EXPORTED since #1162 for a third consumer: `block-preprocess.mjs`, which
+ * gives the ~36 block parsers under `scripts/lib/config/` the same
+ * commented-out-is-not-live-config semantics. Same argument as the export of
+ * `isSessionConfigHeading` — a fourth copy of this state machine that drifts
+ * loose is worse than no check at all. Behaviour is unchanged by the export.
+ *
  * @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() {
+export function htmlCommentSkipper() {
   let inComment = false;
   return function skipHtmlComment(line) {
     if (inComment) {

package/scripts/lib/config/skill-evolution.mjs

@@ -1,4 +1,5 @@
 import { matchBlockHeader } from './block-header.mjs';
+import { preprocessBlockLines } from './block-preprocess.mjs';
 
 /**
  * skill-evolution.mjs — Parser for the top-level `skill-evolution:` YAML block
@@ -39,7 +40,7 @@ export function _parseSkillEvolution(content) {
     'judge-budget-tokens': 8000,
   };
 
-  const lines = content.split(/\r?\n/);
+  const lines = preprocessBlockLines(content);
   let inBlock = false;
   const blockLines = [];
 

package/scripts/lib/config/slopcheck.mjs

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

package/scripts/lib/config/state-md-lock.mjs

@@ -1,4 +1,5 @@
 import { matchBlockHeader } from './block-header.mjs';
+import { preprocessBlockLines } from './block-preprocess.mjs';
 
 /**
  * state-md-lock.mjs — Parser for the top-level `state-md-lock:` YAML block
@@ -30,7 +31,7 @@ export function _parseStateMdLock(content) {
     'timeout-ms': 10000,
   };
 
-  const lines = content.split(/\r?\n/);
+  const lines = preprocessBlockLines(content);
   let inBlock = false;
   const blockLines = [];
 

package/scripts/lib/config/templates-first.mjs

@@ -1,4 +1,5 @@
 import { matchBlockHeader } from './block-header.mjs';
+import { preprocessBlockLines } from './block-preprocess.mjs';
 
 /**
  * templates-first.mjs — Parser for the top-level `templates-first:` YAML block
@@ -34,7 +35,7 @@ export function _parseTemplatesFirst(content) {
     hosts: [...DEFAULT_HOSTS],
   };
 
-  const lines = content.split(/\r?\n/);
+  const lines = preprocessBlockLines(content);
   let inBlock = false;
   const blockLines = [];
 

package/scripts/lib/config/test.mjs

@@ -8,6 +8,7 @@
 
 import { validatePathInsideProject } from '../path-utils.mjs';
 import { matchBlockHeader } from './block-header.mjs';
+import { preprocessBlockLines } from './block-preprocess.mjs';
 
 /**
  * Parse the top-level `test:` YAML block from markdown content.
@@ -27,7 +28,7 @@ export function _parseTest(content) {
     'retention-days': 30,
   };
 
-  const lines = content.split(/\r?\n/);
+  const lines = preprocessBlockLines(content);
   let inBlock = false;
   const blockLines = [];
 

package/scripts/lib/config/vault-integration.mjs

@@ -22,6 +22,7 @@
 
 import { _coerceBoolean, _coerceInteger } from './coercers.mjs';
 import { matchBlockHeader } from './block-header.mjs';
+import { preprocessBlockLines } from './block-preprocess.mjs';
 
 // ---------------------------------------------------------------------------
 // vault-integration
@@ -68,7 +69,12 @@ export function _parseVaultIntegration(content) {
   const defaults = { enabled: false, 'vault-dir': null, mode: 'warn', 'vault-name': null };
   if (typeof content !== 'string' || content === '') return defaults;
 
-  const lines = content.split(/\r?\n/);
+  // #1162: NOT a raw split. `preprocessBlockLines` drops HTML-commented lines
+  // (a commented-out block was read as live config) and rewrites bold-bullet
+  // sub-keys (`- **enabled:** true` fell back to the `false` default). This
+  // parser has no dash-RECORD body, so the bold pass is safe here — see the
+  // named risk in block-preprocess.mjs.
+  const lines = preprocessBlockLines(content);
 
   // Pass 1: inline-object form. Matches `vault-integration: { ... }` with or
   // without a leading `- ` (baseline list-item form per #497).

package/scripts/lib/config/vault-mirror-quality.mjs

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

package/scripts/lib/config/vault-staleness.mjs

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

package/scripts/lib/config/vault-sync.mjs

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

package/scripts/lib/config/verification-auto-fix.mjs

@@ -1,4 +1,5 @@
 import { matchBlockHeader } from './block-header.mjs';
+import { preprocessBlockLines } from './block-preprocess.mjs';
 
 /**
  * verification-auto-fix.mjs — Parser for the top-level `verification-auto-fix:`
@@ -31,7 +32,7 @@ export function _parseVerificationAutoFix(content) {
     'max-retries': 2,
   };
 
-  const lines = content.split(/\r?\n/);
+  const lines = preprocessBlockLines(content);
   let inBlock = false;
   const blockLines = [];
 

package/scripts/lib/config/wave-reviewers.mjs

@@ -1,4 +1,5 @@
 import { matchBlockHeader } from './block-header.mjs';
+import { preprocessBlockLines } from './block-preprocess.mjs';
 
 /**
  * wave-reviewers.mjs — Parser for the `wave-reviewers` / `persona-reviewers` sub-block.
@@ -58,7 +59,7 @@ export function _parseWaveReviewers(content) {
  * @returns {string[]}
  */
 function _extractBlock(content, key) {
-  const lines = content.split(/\r?\n/);
+  const lines = preprocessBlockLines(content);
   const blockLines = [];
   let inBlock = false;
 

package/scripts/lib/config/worktree-orphans.mjs

@@ -1,4 +1,5 @@
 import { matchBlockHeader } from './block-header.mjs';
+import { preprocessBlockLines } from './block-preprocess.mjs';
 
 /**
  * worktree-orphans.mjs — Parser for the top-level `worktree-orphans:` YAML block.
@@ -85,7 +86,7 @@ export function _parseWorktreeOrphans(content) {
 
   if (typeof content !== 'string' || content === '') return defaults;
 
-  const lines = content.split(/\r?\n/);
+  const lines = preprocessBlockLines(content);
   let inBlock = false;
   const blockLines = [];
 

package/scripts/lib/config.mjs

@@ -61,6 +61,7 @@ import { _parseAutoDream } from './config/auto-dream.mjs';
 import { _parseStateMdLock } from './config/state-md-lock.mjs';
 import { _parseHandoverGate } from './config/handover-gate.mjs';
 import { _parseIssueBudget } from './config/issue-budget.mjs';
+import { _parseHealthEndpoints, _parseEcosystemHealthBlockEnabled } from './config/health-endpoints.mjs';
 import { _parseBrokenWindow } from './config/broken-window.mjs';
 import { _parseSlopcheck } from './config/slopcheck.mjs';
 import { _parseDiscoveryValidator } from './config/discovery-validator.mjs';
@@ -71,6 +72,7 @@ import { _parseEval } from './config/eval.mjs';
 import { _parseMemory } from './config/memory.mjs';
 import { _parseReconcile } from './config/reconcile.mjs';
 import { _parseCustomPhases } from './config/custom-phases.mjs';
+import { _parseRemoteHosts } from './config/remote-hosts.mjs';
 import { _parseEvolve, _parseEvolveDecay } from './config/evolve.mjs';
 import { _parseSkillEvolution } from './config/skill-evolution.mjs';
 import { _parseDispatcherAutonomy, resolveDispatcherAutonomy } from './config/dispatcher-autonomy.mjs';
@@ -198,7 +200,14 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
 
   // Boolean fields
   const persistence = _coerceBoolean(kv, 'persistence', true);
-  const ecosystemHealth = _coerceBoolean(kv, 'ecosystem-health', false);
+  // ecosystem-health has TWO spellings and only the scalar one reaches `kv`:
+  // the wizard writes a valueless `ecosystem-health:` header opening a block,
+  // which carries no `key: value` pair and is therefore invisible to the KV
+  // map (#1174). Scalar wins when present; otherwise the block form decides.
+  const ecosystemHealth =
+    _getVal(kv, 'ecosystem-health', undefined) !== undefined
+      ? _coerceBoolean(kv, 'ecosystem-health', false)
+      : (_parseEcosystemHealthBlockEnabled(mdContent) ?? false);
   const discoveryOnClose = _coerceBoolean(kv, 'discovery-on-close', false);
   const reasoningOutput = _coerceBoolean(kv, 'reasoning-output', false);
   const groundingCheck = _coerceBoolean(kv, 'grounding-check', true);
@@ -214,7 +223,6 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
   const ssotFiles = _coerceList(kv, 'ssot-files', undefined);
   const discoveryProbes = _coerceList(kv, 'discovery-probes', '[all]');
   const discoveryExcludePaths = _coerceList(kv, 'discovery-exclude-paths', '[]');
-  const healthEndpoints = _coerceList(kv, 'health-endpoints', undefined);
   const worktreeExclude = _coerceList(
     kv,
     'worktree-exclude',
@@ -230,6 +238,11 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
   // follow-up (see docs/session-config-reference.md). This wires the parser + value only.
   const worktreeCleanup = _coerceEnum(kv, 'worktree-cleanup', 'default', ['default', 'aggressive']);
 
+  // remote-hosts: opt-in ssh-reachable hosts heavy roles may be offloaded to (#1160).
+  // Parsed HERE, before agent-mapping, because the `ssh:<alias>` channel below
+  // validates its target against the declared aliases. Defaults to [].
+  const remoteHosts = _parseRemoteHosts(mdContent);
+
   // Object fields
   const agentMapping = _coerceObject(kv, 'agent-mapping');
   if (agentMapping !== null) {
@@ -240,10 +253,11 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
     // dispatched natively, exactly as before.
     //   impl: code-implementer      → native Agent dispatch (unchanged)
     //   impl: cursor:composer-2.5   → foreign model over the Cursor channel
+    //   test: ssh:m5                → same Claude, another host (#1160)
     // 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'];
+    const KNOWN_CHANNELS = ['cursor', 'session-orchestrator', 'ssh'];
     // 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.
@@ -272,6 +286,15 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
             `role '${k}' has channel '${channel}' but no target in value '${v}' ` +
               `(expected '${channel}:<model-or-agent>')`
           );
+        } else if (channel === 'ssh' && !remoteHosts.some((h) => h.alias === target)) {
+          // An ssh target is a host ALIAS, and the only place aliases are declared
+          // is the remote-hosts: block. An undeclared alias would reach argv as
+          // `-H <target>` and fail at connect time, one wave too late.
+          const declared = remoteHosts.map((h) => h.alias).join(', ') || 'none';
+          valueProblems.push(
+            `role '${k}' names ssh host '${target}' which is not declared in remote-hosts: ` +
+              `(declared: ${declared})`
+          );
         }
       }
     }
@@ -442,6 +465,10 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
   const evolveDecay = _parseEvolveDecay(mdContent);
 
   // persona-gate-wave: opt-in mid-wave persona-panel hook (#458). Returns null when absent.
+  // health-endpoints: content-scoped (NOT _coerceList, which bails to null on
+  // any '{' and cannot see the wizard's nested block form at all) — #1174.
+  const healthEndpoints = _parseHealthEndpoints(mdContent);
+
   const personaGateWave = _parsePersonaGateWave(mdContent);
   if (personaGateWave !== null && personaGateWave.enabled === true && personaGateWave.mode === 'off') {
     process.stderr.write(
@@ -538,6 +565,7 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
     'wave-reviewers': waveReviewers,
     'persona-gate-wave': personaGateWave,
     'custom-phases': customPhases,
+    'remote-hosts': remoteHosts,
     'evolve.extra-sources': evolveExtraSources,
     'evolve.decay': evolveDecay,
   };