session-orchestrator 3.23.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.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,
   };

package/scripts/lib/dispatcher/enumerate.mjs

@@ -29,12 +29,12 @@
  */
 
 import { readdirSync, existsSync } from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 
 import { getConfinementRoot, getCrossRepoProjects } from '../config/cross-repo.mjs';
 import { validatePathInsideProject } from '../path-utils.mjs';
 import { readLock, isLockLive } from '../session-lock.mjs';
+import { expandTilde } from '../common.mjs';
 
 /**
  * @typedef {Object} Candidate
@@ -97,21 +97,6 @@ function shouldDescendInto(name) {
   return true;
 }
 
-/**
- * Expand a leading `~` to the current user's home directory. Mirrors the helper
- * in board-writer.mjs (a shared extraction is deferred to a later epic). Used to
- * normalise config-declared cross-repo paths that may begin with `~/`.
- *
- * @param {string} p
- * @returns {string}
- */
-function expandHome(p) {
-  if (typeof p !== 'string' || p.length === 0) return p;
-  if (p === '~') return os.homedir();
-  if (p.startsWith('~/')) return path.join(os.homedir(), p.slice(2));
-  return p;
-}
-
 /**
  * Derive free/busy status for a single repo from its session.lock lease.
  * Mirrors board-writer.mjs collectRows semantics exactly:
@@ -322,7 +307,7 @@ export async function enumerateCandidates({ startDir, now, deps } = {}) {
   if (Array.isArray(declared)) {
     for (const raw of declared) {
       if (typeof raw !== 'string' || raw.length === 0) continue;
-      const expanded = expandHome(raw);
+      const expanded = expandTilde(raw);
       const abs = path.resolve(expanded);
       // Confinement-filter against the same root as the FS scan.
       const guard = validatePathInsideProjectFn(abs, root);

package/scripts/lib/events-schema.mjs

@@ -12,6 +12,54 @@
  * Pure functions, no filesystem access — safe to import anywhere.
  */
 
+/**
+ * Current events.jsonl record schema version (#1177). Mirrors
+ * `subagents-schema.mjs § CURRENT_SCHEMA_VERSION`.
+ *
+ * Records written before #1177 carry NO `schema_version` key at all; an absent
+ * key therefore reads as "pre-versioned", never as version 0. Stamping is
+ * strictly additive — see `stampEventSchemaVersion()`.
+ */
+export const CURRENT_SCHEMA_VERSION = 1;
+
+/**
+ * Thrown by `emitEvent()` when a record fails `validateEventRecord()`.
+ *
+ * Carries the individual validator messages so a CLI/hook caller can surface
+ * them without re-running the validator.
+ */
+export class EventValidationError extends Error {
+  /**
+   * @param {string} message — human-readable summary.
+   * @param {string[]} [errors=[]] — the validator's individual error strings.
+   * @param {string} [eventType] — the offending event name, when known.
+   */
+  constructor(message, errors = [], eventType) {
+    super(message);
+    this.name = 'EventValidationError';
+    this.errors = errors;
+    this.eventType = eventType;
+  }
+}
+
+/**
+ * Return a shallow copy of `record` with `schema_version` stamped to
+ * `CURRENT_SCHEMA_VERSION` — but ONLY when the field is absent
+ * (`undefined`/`null`). An existing value is never overwritten, so a caller
+ * (or a migration re-writing historical records) keeps authority over its own
+ * version field.
+ *
+ * @param {object} record
+ * @returns {object} shallow copy, `schema_version` guaranteed present.
+ */
+export function stampEventSchemaVersion(record) {
+  const out = { ...record };
+  if (out.schema_version === undefined || out.schema_version === null) {
+    out.schema_version = CURRENT_SCHEMA_VERSION;
+  }
+  return out;
+}
+
 /** ISO-8601 UTC timestamp with trailing Z (e.g. 2026-05-28T14:35:13.123Z). */
 const ISO_8601_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/;