session-orchestrator 3.16.0

package/scripts/lib/config/handover-gate.mjs

@@ -0,0 +1,106 @@
+import { matchBlockHeader } from './block-header.mjs';
+
+/**
+ * handover-gate.mjs — Parser for the top-level `handover-gate:` YAML block
+ * (PRD 2026-07-07 /close Handover-Alignment-Gate — Epic #724).
+ *
+ * Drives the interactive Handover-Alignment-Gate in session-end Phase 1.65:
+ * gates carryover-candidate filing behind an AskUserQuestion triage pass
+ * instead of the silent-filing status quo.
+ *
+ * Returns `{ enabled, "max-open-questions" }`.
+ * Tolerant parser: malformed values silently fall back to defaults, EXCEPT
+ * `max-open-questions` — a malformed or negative value emits a stderr WARN
+ * before falling back (PRD §3.A FA5 "Unwanted behaviour" explicitly requires
+ * the WARN here — a deliberate minor divergence from sibling block parsers
+ * like `reconcile.min-rule-days`, which fall back silently).
+ *
+ * Consumer: `scripts/lib/config.mjs`, `skills/session-end/SKILL.md` Phase 1.65.
+ */
+
+/**
+ * Parse the top-level `handover-gate:` YAML block from markdown content.
+ * Independent of the `## Session Config` section boundary.
+ *
+ * Defaults:
+ *   enabled:            true
+ *   max-open-questions: 3 (integer >= 0; 0 is a VALID value — "no questions
+ *                          in the gate", the Open-Questions channel itself
+ *                          stays active). Malformed or negative input falls
+ *                          back to 3 and emits a stderr WARN.
+ *
+ * YAML shape:
+ *   handover-gate:
+ *     enabled: true
+ *     max-open-questions: 3
+ *
+ * @param {string} content — full file contents
+ * @returns {{ enabled: boolean, "max-open-questions": number }}
+ */
+export function _parseHandoverGate(content) {
+  const defaults = {
+    enabled: true,
+    'max-open-questions': 3,
+  };
+
+  const lines = content.split(/\r?\n/);
+  let inBlock = false;
+  const blockLines = [];
+
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/\r$/, '');
+    if (!inBlock) {
+      if (matchBlockHeader(line, 'handover-gate')) inBlock = true;
+      continue;
+    }
+    // Stop at next column-0 non-empty line (sibling top-level key or H2 heading)
+    if (line.length > 0 && !/^\s/.test(line)) break;
+    blockLines.push(line);
+  }
+
+  if (blockLines.length === 0) return defaults;
+
+  let enabled = true;
+  let maxOpenQuestions = 3;
+
+  for (const rawLine of blockLines) {
+    // Strip inline comments and trailing whitespace
+    const clean = rawLine.replace(/\s*#.*$/, '').replace(/\s+$/, '');
+    if (!clean.trim()) continue;
+
+    const kvMatch = clean.match(/^\s+([a-zA-Z_-]+):\s*(.*)/);
+    if (!kvMatch) continue;
+
+    const k = kvMatch[1];
+    let v = kvMatch[2].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 (k) {
+      case 'enabled':
+        // Default is true → only flip to false on explicit "false"
+        enabled = v.toLowerCase() !== 'false';
+        break;
+
+      case 'max-open-questions': {
+        if (/^\d+$/.test(v)) {
+          // Non-negative integer (0 is valid — see defaults doc above)
+          maxOpenQuestions = parseInt(v, 10);
+        } else {
+          // Malformed (non-numeric, empty) or negative (fails the \d+ test) —
+          // PRD §3.A FA5 requires a stderr WARN on this fallback path.
+          process.stderr.write(
+            `⚠ handover-gate.max-open-questions: '${v}' invalid — falling back to 3\n`
+          );
+          maxOpenQuestions = 3;
+        }
+        break;
+      }
+    }
+  }
+
+  return {
+    enabled,
+    'max-open-questions': maxOpenQuestions,
+  };
+}

package/scripts/lib/config/host-paths.mjs

@@ -0,0 +1,76 @@
+/**
+ * host-paths.mjs — Host-local path resolution layer (issue #653).
+ *
+ * Resolves machine-specific paths (`vault-dir`, projects-baseline path) from a
+ * host-local source instead of the version-controlled Session Config. This keeps
+ * personal absolute paths out of committed CLAUDE.md (a dual privacy + portability
+ * hazard the owner-leakage scanner P1–P9 does not catch) while still letting the
+ * committed default act as a fallback for unconfigured hosts.
+ *
+ * Precedence (highest first):
+ *   1. env-var               (SO_VAULT_DIR / SO_BASELINE_PATH)
+ *   2. owner.yaml paths[key]  (host-local, never committed — ~/.config/session-orchestrator/owner.yaml)
+ *   3. committed Session Config default (the value the committed CLAUDE.md —
+ *      AGENTS.md on Codex CLI — produced)
+ *
+ * SYNCHRONOUS by design: `parseSessionConfig` in scripts/lib/config.mjs is sync,
+ * so this layer reuses the SYNC owner loader (`loadOwnerConfig`) and exposes only
+ * sync functions. An empty/whitespace value at any tier is treated as "unset" and
+ * falls through to the next tier.
+ */
+
+import { loadOwnerConfig } from '../owner-yaml.mjs';
+
+/** Maps a logical path key to its environment-variable name. */
+const ENV_KEYS = /** @type {const} */ ({
+  'vault-dir': 'SO_VAULT_DIR',
+  'baseline-path': 'SO_BASELINE_PATH',
+  // #725 D5 — host-local pseudonym map for vault-mirror namespace resolution.
+  'namespace-map-path': 'SO_NAMESPACE_MAP',
+  // #728a — host-local confidential customer/repo name list for CP11 leak scanning.
+  'confidential-names-file': 'SO_CONFIDENTIAL_NAMES_FILE',
+});
+
+/**
+ * Load the host-local resolution context once (owner.yaml + env), so a caller can
+ * resolve many keys without re-reading disk per key.
+ *
+ * Defensive: `loadOwnerConfig` never throws, but the try/catch guards against a
+ * future loader change. `ownerConfig` may be the raw parsed object — it is NOT
+ * merged with defaults, so a real owner.yaml without a `paths:` section yields
+ * `ownerConfig.paths === undefined`. Callers must read defensively.
+ *
+ * @param {{ env?: Record<string, string|undefined>, ownerLoader?: () => { config: object } }} [opts]
+ * @returns {{ ownerConfig: object|undefined, env: Record<string, string|undefined> }}
+ */
+export function loadHostPaths({ env = process.env, ownerLoader = loadOwnerConfig } = {}) {
+  let ownerConfig;
+  try {
+    ownerConfig = ownerLoader().config;
+  } catch {
+    ownerConfig = undefined;
+  }
+  return { ownerConfig, env };
+}
+
+/**
+ * Resolve a host-local path with precedence: env-var > owner.yaml paths[key] >
+ * committedDefault. An empty/whitespace string at a tier is treated as "unset"
+ * (fall through to the next tier). When no override is set, `committedDefault`
+ * passes through unchanged — including `null`/`undefined`, preserving back-compat.
+ *
+ * @param {'vault-dir'|'baseline-path'|'namespace-map-path'|'confidential-names-file'} key — logical path key
+ * @param {string|null|undefined} committedDefault — value the committed Session Config produced
+ * @param {{ env?: Record<string, string|undefined>, ownerConfig?: object }} [ctx] — from loadHostPaths()
+ * @returns {string|null|undefined} resolved value
+ */
+export function resolveHostPath(key, committedDefault, { env = process.env, ownerConfig } = {}) {
+  const envName = ENV_KEYS[key];
+  const envVal = envName ? env[envName] : undefined;
+  if (typeof envVal === 'string' && envVal.trim() !== '') return envVal;
+
+  const ownerVal = ownerConfig?.paths?.[key];
+  if (typeof ownerVal === 'string' && ownerVal.trim() !== '') return ownerVal;
+
+  return committedDefault;
+}

package/scripts/lib/config/io.mjs

@@ -0,0 +1,54 @@
+/**
+ * io.mjs — Dependency-free leaf for Session Config file IO.
+ *
+ * Holds the shared `readConfigFile` primitive so that both the orchestrator
+ * (config.mjs) and the per-section parsers (e.g. config/cross-repo.mjs) can
+ * import it without forming a cycle. This module imports ONLY Node built-ins —
+ * never config.mjs, never any sibling config/*.mjs parser.
+ *
+ * Extracted from config.mjs to break the length-2 cycle
+ * config.mjs ⇄ config/cross-repo.mjs (issue #664).
+ */
+
+import { readFile, access } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * Read CLAUDE.md or AGENTS.md from the project root.
+ * Precedence: if AGENTS.md exists AND env var SO_PLATFORM === "codex" or "pi", prefer AGENTS.md.
+ * Otherwise CLAUDE.md. Throws if neither file found.
+ * @param {string} projectRoot — absolute path to project root
+ * @returns {Promise<string>} file contents as string (CRLF-tolerant)
+ */
+export async function readConfigFile(projectRoot) {
+  const claudeMd = join(projectRoot, 'CLAUDE.md');
+  const agentsMd = join(projectRoot, 'AGENTS.md');
+
+  const prefersAgents = process.env.SO_PLATFORM === 'codex' || process.env.SO_PLATFORM === 'pi';
+
+  if (prefersAgents) {
+    // Prefer AGENTS.md for Codex/Pi platforms
+    try {
+      await access(agentsMd);
+      return await readFile(agentsMd, 'utf8');
+    } catch {
+      // Fall through to CLAUDE.md
+    }
+  }
+
+  try {
+    await access(claudeMd);
+    return await readFile(claudeMd, 'utf8');
+  } catch {
+    // Try AGENTS.md as fallback (non-Codex)
+  }
+
+  try {
+    await access(agentsMd);
+    return await readFile(agentsMd, 'utf8');
+  } catch {
+    // Neither found
+  }
+
+  throw new Error(`config.mjs: neither CLAUDE.md nor AGENTS.md found in '${projectRoot}'`);
+}

package/scripts/lib/config/loop-guard.mjs

@@ -0,0 +1,117 @@
+import { matchBlockHeader } from './block-header.mjs';
+
+/**
+ * loop-guard.mjs — Parser for the top-level `loop-guard:` YAML block
+ * (ecc-analysis / issue #619).
+ *
+ * Drives the lean PostToolUse hook that maintains a per-session ring buffer of
+ * recent {tool, argsHash} pairs and injects an additionalContext loop-warning
+ * when the same (tool+argsHash) recurs >= `threshold` times within the last
+ * `window` tool calls. Warn-only / non-blocking; profile-gate also applies.
+ *
+ * Returns `{ enabled, threshold, window }`.
+ * Tolerant parser: malformed values silently fall back to defaults.
+ *
+ * Consumer: `hooks/loop-guard.mjs`.
+ */
+
+/** Lower bounds — fewer than 2 identical calls / a window < 2 is nonsensical. */
+const MIN_THRESHOLD = 2;
+const MIN_WINDOW = 2;
+
+const DEFAULT_THRESHOLD = 3;
+const DEFAULT_WINDOW = 5;
+
+/**
+ * Coerce a raw string value into a bounded positive integer, falling back to
+ * `fallback` when the value is not a finite integer >= `min`.
+ *
+ * @param {string} raw
+ * @param {number} fallback
+ * @param {number} min
+ * @returns {number}
+ */
+function parseBoundedInt(raw, fallback, min) {
+  if (!/^-?\d+$/.test(raw)) return fallback;
+  const n = Number.parseInt(raw, 10);
+  if (!Number.isFinite(n) || n < min) return fallback;
+  return n;
+}
+
+/**
+ * Parse the top-level `loop-guard:` YAML block from markdown content.
+ * Independent of the `## Session Config` section boundary.
+ *
+ * Defaults:
+ *   enabled:   true
+ *   threshold: 3   (bounded >= 2)
+ *   window:    5   (bounded >= 2)
+ *
+ * @param {string} content — full file contents
+ * @returns {{ enabled: boolean, threshold: number, window: number }}
+ */
+export function _parseLoopGuard(content) {
+  const defaults = {
+    enabled: true,
+    threshold: DEFAULT_THRESHOLD,
+    window: DEFAULT_WINDOW,
+  };
+
+  const lines = content.split(/\r?\n/);
+  let inBlock = false;
+  const blockLines = [];
+
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/\r$/, '');
+    if (!inBlock) {
+      if (matchBlockHeader(line, 'loop-guard')) inBlock = true;
+      continue;
+    }
+    if (line.length > 0 && !/^\s/.test(line)) break;
+    blockLines.push(line);
+  }
+
+  if (blockLines.length === 0) return defaults;
+
+  let lgEnabled = true;
+  let lgThreshold = DEFAULT_THRESHOLD;
+  let lgWindow = DEFAULT_WINDOW;
+
+  for (const rawLine of blockLines) {
+    const clean = rawLine.replace(/\s*#.*$/, '').replace(/\s+$/, '');
+    if (!clean.trim()) continue;
+
+    const kvMatch = clean.match(/^\s+([a-zA-Z_-]+):\s*(.*)/);
+    if (!kvMatch) continue;
+
+    const k = kvMatch[1];
+    let v = kvMatch[2].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 (k) {
+      case 'enabled':
+        // Default is true → only flip to false on explicit "false"
+        lgEnabled = v.toLowerCase() !== 'false';
+        break;
+      case 'threshold':
+        lgThreshold = parseBoundedInt(v, DEFAULT_THRESHOLD, MIN_THRESHOLD);
+        break;
+      case 'window':
+        lgWindow = parseBoundedInt(v, DEFAULT_WINDOW, MIN_WINDOW);
+        break;
+    }
+  }
+
+  // Clamp: a `window` smaller than `threshold` is dead config — the same
+  // (tool+argsHash) can never recur `threshold` times inside a shorter ring, so
+  // the guard would silently never fire. Self-heal by widening the window to at
+  // least `threshold` (#619 / #628 hardening).
+  if (lgWindow < lgThreshold) lgWindow = lgThreshold;
+
+  return {
+    enabled: lgEnabled,
+    threshold: lgThreshold,
+    window: lgWindow,
+  };
+}

package/scripts/lib/config/memory.mjs

@@ -0,0 +1,150 @@
+import { matchBlockHeader } from './block-header.mjs';
+
+/**
+ * memory.mjs — Parser for the top-level `memory:` YAML block.
+ *
+ * Drives:
+ *   - memory-banner (issue #505) that surfaces at session-start when the
+ *     operator has accumulated significant learnings.
+ *   - memory-proposals (issue #501, F2.1) — agent-writable memory tool with
+ *     per-wave quotas and a confidence floor.
+ *
+ * Returns:
+ *   {
+ *     banner: { enabled },
+ *     proposals: { enabled, "quota-per-wave", "confidence-floor" }
+ *   }
+ *
+ * Tolerant parser: malformed values silently fall back to defaults.
+ *
+ * Consumers: `scripts/lib/memory-banner.mjs`, `scripts/parse-config.mjs`.
+ */
+
+/**
+ * Parse the top-level `memory:` YAML block from markdown content.
+ * Independent of the `## Session Config` section boundary.
+ *
+ * Defaults:
+ *   memory.banner.enabled:           true
+ *   memory.proposals.enabled:        true
+ *   memory.proposals.quota-per-wave: 5    (integer ≥ 0)
+ *   memory.proposals.confidence-floor: 0.5 (float 0.0..1.0)
+ *
+ * YAML shape:
+ *   memory:
+ *     banner:
+ *       enabled: true
+ *     proposals:
+ *       enabled: true
+ *       quota-per-wave: 5
+ *       confidence-floor: 0.5
+ *
+ * @param {string} content — full file contents
+ * @returns {{
+ *   banner: { enabled: boolean },
+ *   proposals: { enabled: boolean, "quota-per-wave": number, "confidence-floor": number }
+ * }}
+ */
+export function _parseMemory(content) {
+  const defaults = {
+    banner: { enabled: true },
+    proposals: {
+      enabled: true,
+      'quota-per-wave': 5,
+      'confidence-floor': 0.5,
+    },
+  };
+
+  const lines = content.split(/\r?\n/);
+  let inBlock = false;
+  const blockLines = [];
+
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/\r$/, '');
+    if (!inBlock) {
+      if (matchBlockHeader(line, 'memory')) inBlock = true;
+      continue;
+    }
+    if (line.length > 0 && !/^\s/.test(line)) break;
+    blockLines.push(line);
+  }
+
+  if (blockLines.length === 0) return defaults;
+
+  let bannerEnabled = true;
+  let proposalsEnabled = true;
+  let proposalsQuotaPerWave = 5;
+  let proposalsConfidenceFloor = 0.5;
+
+  let inBannerBlock = false;
+  let inProposalsBlock = false;
+
+  for (const rawLine of blockLines) {
+    const clean = rawLine.replace(/\s*#.*$/, '').replace(/\s+$/, '');
+    if (!clean.trim()) continue;
+
+    // Detect `  banner:` sub-block header (2-space indent)
+    if (/^\s{2}banner:\s*$/.test(clean)) {
+      inBannerBlock = true;
+      inProposalsBlock = false;
+      continue;
+    }
+
+    // Detect `  proposals:` sub-block header (2-space indent)
+    if (/^\s{2}proposals:\s*$/.test(clean)) {
+      inProposalsBlock = true;
+      inBannerBlock = false;
+      continue;
+    }
+
+    // If we hit a sibling top-level key inside the memory block, exit any sub-block
+    if (/^\s{2}[a-zA-Z_-]+:/.test(clean) && !/^\s{4}/.test(clean)) {
+      inBannerBlock = false;
+      inProposalsBlock = false;
+    }
+
+    const kvMatch = clean.match(/^\s+([a-zA-Z_-]+):\s*(.*)/);
+    if (!kvMatch) continue;
+
+    const k = kvMatch[1];
+    let v = kvMatch[2].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);
+
+    if (inBannerBlock && k === 'enabled') {
+      // Default is true → only flip to false on explicit "false"
+      bannerEnabled = v.toLowerCase() !== 'false';
+      continue;
+    }
+
+    if (inProposalsBlock) {
+      switch (k) {
+        case 'enabled':
+          // Default is true → only flip to false on explicit "false"
+          proposalsEnabled = v.toLowerCase() !== 'false';
+          break;
+        case 'quota-per-wave': {
+          if (/^\d+$/.test(v)) {
+            const n = parseInt(v, 10);
+            if (n >= 0) proposalsQuotaPerWave = n;
+          }
+          break;
+        }
+        case 'confidence-floor': {
+          const f = parseFloat(v);
+          if (!isNaN(f) && f >= 0.0 && f <= 1.0) proposalsConfidenceFloor = f;
+          break;
+        }
+      }
+    }
+  }
+
+  return {
+    banner: { enabled: bannerEnabled },
+    proposals: {
+      enabled: proposalsEnabled,
+      'quota-per-wave': proposalsQuotaPerWave,
+      'confidence-floor': proposalsConfidenceFloor,
+    },
+  };
+}