session-orchestrator 3.17.0 → 3.20.0

package/scripts/lib/reconcile-nudge-banner.mjs

@@ -23,9 +23,13 @@
  * `.orchestrator/runtime/reconcile-candidates.jsonl` (owned by
  * `scripts/lib/reconcile/idempotency.mjs`). Every learning present at a given
  * run (eligible OR rejected) gets a candidate row, so:
- *   - the MAX `created_at` across `loadCandidates({repoRoot})` is the most
- *     recent reconcile run's timestamp (or `null` when the store is empty —
- *     i.e. no run on record, matching the fleet finding above).
+ *   - the MAX `created_at` across `loadCandidates({repoRoot}).records` is the
+ *     most recent reconcile run's timestamp (or `null` when the store is
+ *     empty — i.e. no run on record, matching the fleet finding above).
+ *     `.skipped` is read alongside it because `records.length === 0` alone is
+ *     AMBIGUOUS: a missing store and a store whose every line failed the
+ *     candidate shape guard both yield `[]`. Reporting "never" for the latter
+ *     denies a run whose record was merely quarantined (GitLab #955 finding 2).
  *   - the candidate COUNT is a reasonable proxy for "how many learnings had
  *     been seen as of the last run" (dedup is by `learning_key`, so it is a
  *     high-water mark across all runs to date), used for the "new learnings
@@ -116,7 +120,11 @@ function _lastRunAt(candidates) {
  *   delta: number,
  *   nudge: boolean,
  *   reasons: string[],
+ *   skippedCandidates?: number,
  * }>}
+ *   `skippedCandidates` is ABSENT when the candidate store was never inspected
+ *   (early empty-corpus return, or an unreadable store); `0` means inspected and
+ *   clean, `> 0` means that many persisted lines failed the candidate shape guard.
  */
 export async function computeReconcileNudge(opts = {}) {
   const empty = {
@@ -167,20 +175,39 @@ export async function computeReconcileNudge(opts = {}) {
 
   /** @type {Array<Record<string, unknown>>} */
   let candidates;
+  /** @type {number|undefined} */
+  let skippedCandidates;
   try {
-    candidates = loadCandidates({ repoRoot });
+    const diag = loadCandidates({ repoRoot });
+    candidates = Array.isArray(diag?.records) ? diag.records : [];
+    // Absence-preserving, mirroring `engine.mjs` `summary.skipped`: only a
+    // finite count means "the store was inspected". Absent ⇒ never checked,
+    // 0 ⇒ checked and clean.
+    if (Number.isFinite(diag?.skipped)) skippedCandidates = Number(diag.skipped);
   } catch {
     candidates = [];
+    // Store never inspected → leave `skippedCandidates` absent rather than
+    // fabricating a clean 0.
   }
 
   const lastRunAt = _lastRunAt(candidates);
   const lastRunCandidateCount = Array.isArray(candidates) ? candidates.length : 0;
   const delta = entries.length - lastRunCandidateCount;
+  const quarantined = typeof skippedCandidates === 'number' ? skippedCandidates : 0;
 
   const reasons = [];
-  // (a) — plenty of active learnings, but no reconcile run has ever recorded them.
+  // (a) — plenty of active learnings and no DATEABLE run on record. When the
+  // store holds quarantined lines the honest claim is "undeterminable", not
+  // "never": the evidence exists, it is merely unreadable. /reconcile is still
+  // the right action either way — mergeCandidates rewrites the store in full and
+  // purges the bad lines — so the nudge fires in both cases, only the wording
+  // differs.
   if (active.length >= NUDGE_MIN_LEARNINGS && lastRunAt === null) {
-    reasons.push(`${active.length} active learnings with no reconcile run on record`);
+    reasons.push(
+      quarantined > 0
+        ? `${active.length} active learnings; last reconcile run undeterminable — ${quarantined} unreadable record(s) in the candidate store`
+        : `${active.length} active learnings with no reconcile run on record`,
+    );
   }
   // (b) — a determinable prior run exists, and the corpus has grown meaningfully since.
   if (lastRunAt !== null && delta > NUDGE_MIN_DELTA) {
@@ -191,7 +218,7 @@ export async function computeReconcileNudge(opts = {}) {
     reasons.push(`${eligibleCount} rule-eligible learnings`);
   }
 
-  return {
+  const computed = {
     totalLearnings: entries.length,
     activeLearnings: active.length,
     eligibleCount,
@@ -201,6 +228,12 @@ export async function computeReconcileNudge(opts = {}) {
     nudge: reasons.length > 0,
     reasons,
   };
+  // Additive + absence-preserving: the key exists ONLY when the candidate store
+  // was actually inspected, so no consumer can read a false `skippedCandidates: 0`.
+  if (typeof skippedCandidates === 'number') {
+    /** @type {any} */ (computed).skippedCandidates = skippedCandidates;
+  }
+  return computed;
 }
 
 /**
@@ -261,10 +294,33 @@ export async function checkReconcileNudge(opts = {}) {
       }
     }
 
-    const lastRunLabel =
+    // Three-state last-run label. `never` is a claim about history and must only
+    // be made when the store was inspected and held nothing: a store whose lines
+    // were quarantined by the shape guard is EVIDENCE OF A RUN that can no longer
+    // be dated, so it reads `undeterminable` — saying "never" there would assert
+    // an absence the file on disk contradicts (GitLab #955 finding 2).
+    const quarantined =
+      Number.isFinite(computed.skippedCandidates) && computed.skippedCandidates > 0
+        ? Number(computed.skippedCandidates)
+        : 0;
+    const dated =
       typeof computed.lastRunAt === 'string' && computed.lastRunAt.length >= 10
         ? computed.lastRunAt.slice(0, 10)
-        : 'never';
+        : null;
+    let lastRunLabel;
+    if (dated !== null) {
+      // Partially contaminated: the date is real but derived only from the
+      // surviving records, so flag that it may under-report.
+      lastRunLabel =
+        quarantined > 0
+          ? `${dated} (+${quarantined} unreadable record(s) — date may be stale)`
+          : dated;
+    } else {
+      lastRunLabel =
+        quarantined > 0
+          ? `undeterminable (${quarantined} unreadable record(s) in the candidate store)`
+          : 'never';
+    }
 
     const lines = [
       `⚠ reconcile-nudge: ${computed.activeLearnings} active learnings, ${computed.eligibleCount} rule-eligible, ` +

package/scripts/lib/resource-probe/evaluate.mjs

@@ -47,14 +47,54 @@ const MACOS_HEALTHY_PRESSURE_PCT = 30;
  * and return a verdict used by session-start Phase 4.5.
  * @param {object} snapshot — output of probe()
  * @param {object} thresholds — resource-thresholds block from parseSessionConfig
+ * @param {{heavyRepo?: boolean, agentsPerWave?: number|{default: number, [mode: string]: number}}} [options] — HR-003/HR-004
+ *   preflight ceiling (baseline #60). When `heavyRepo` is true and `agentsPerWave`
+ *   resolves to a number (see {@link resolveAgentsPerWaveCap}), `recommended_agents_per_wave_cap`
+ *   is forced to at most that number REGARDLESS of the live-probe verdict — a
+ *   static preflight ceiling, not a runtime signal. More-restrictive-wins:
+ *   effective = min(existing cap ?? Infinity, agentsPerWave). Omitted entirely
+ *   = today's behaviour (back-compat).
+ *
+ *   `agentsPerWave` accepts either a plain number OR the `{default, <mode>: N}`
+ *   object `_coerceInteger()` (scripts/lib/config/coercers.mjs) produces for
+ *   the parenthetical override syntax (e.g. `agents-per-wave: 4 (deep: 18)`) —
+ *   `skills/session-start/phase-4-5-resource-health.md` documents wiring
+ *   `config['agents-per-wave']` straight into this option, so the object shape
+ *   is a real input here, not a hypothetical one.
  * @returns {{verdict: 'green'|'warn'|'degraded'|'critical', reasons: string[], recommended_agents_per_wave_cap: number|null}}
  */
-export function evaluate(snapshot, thresholds) {
+
+/**
+ * Resolve an `agentsPerWave` option value into a plain numeric cap, or `null`
+ * when no cap should apply. Mirrors `resolveApwCap()` in
+ * `../wave-resource-gate.mjs` — kept as a local pure helper here rather than
+ * a cross-module import since both sites are ≤10 lines and evolve
+ * independently per their own gate's options shape.
+ *
+ * `evaluate()` has no session-mode input in scope, so the object shape
+ * resolves to `cap.default` — the documented HR-003 convention writes the
+ * override as `<default> (mode: <higher-ceiling>)`, i.e. `default` is the
+ * MORE restrictive of the pair, so this can only under-apply a looser
+ * mode-specific ceiling, never let a heavy repo exceed its base cap.
+ *
+ * @param {number|{default: number, [mode: string]: number}|*} cap
+ * @returns {number|null}
+ */
+function resolveAgentsPerWaveCap(cap) {
+  if (typeof cap === 'number') return Number.isFinite(cap) ? cap : null;
+  if (cap !== null && typeof cap === 'object' && !Array.isArray(cap)) {
+    const def = cap.default;
+    return typeof def === 'number' && Number.isFinite(def) ? def : null;
+  }
+  return null;
+}
+
+export function evaluate(snapshot, thresholds, options = {}) {
   const reasons = [];
   let verdict = 'green';
   let cap = null;
 
-  const { ram_free_gb, cpu_load_pct, claude_processes_count, memory_pressure_pct_free, ram_available_gb } = snapshot;
+  const { ram_free_gb, cpu_load_pct, cpu_load_5m_pct, claude_processes_count, memory_pressure_pct_free, ram_available_gb } = snapshot;
   const {
     'ram-free-min-gb': ramMin,
     'ram-free-critical-gb': ramCrit,
@@ -93,10 +133,24 @@ export function evaluate(snapshot, thresholds) {
     reasons.push(`macOS memory_pressure healthy (${memory_pressure_pct_free}% free ≥ ${MACOS_HEALTHY_PRESSURE_PCT}%) — free-RAM signal suppressed (Pages-free underreports on Darwin).`);
   }
 
-  if (cpu_load_pct > cpuMax) {
+  // CPU axis (#943): the 1m load average systematically carries the decaying
+  // tail of the coordinator's own just-finished gate run (the caller sits right
+  // after the inter-wave Quality Gate by construction). When the probe supplied
+  // a numeric `cpu_load_5m_pct`, judge CPU on min(1m, 5m) — only-1m-high is a
+  // decaying transient (informational, no cap), both-high is genuine sustained
+  // load. Mirrors the memory_pressure healthy-suppression pattern above.
+  // `cpu_load_5m_pct` absent/null (legacy snapshots, Windows) → legacy 1m-only.
+  const has5mCpu = typeof cpu_load_5m_pct === 'number' && Number.isFinite(cpu_load_5m_pct);
+  const effectiveCpuPct = has5mCpu ? Math.min(cpu_load_pct, cpu_load_5m_pct) : cpu_load_pct;
+  if (effectiveCpuPct > cpuMax) {
     if (verdict === 'green') verdict = 'warn';
     cap = cap === null ? 2 : Math.min(cap, 2);
-    reasons.push(`CPU load ${cpu_load_pct}% above threshold ${cpuMax}% — capping agents-per-wave at 2.`);
+    const detail = has5mCpu ? ` (min of 1m ${cpu_load_pct}% / 5m ${cpu_load_5m_pct}%)` : '';
+    reasons.push(`CPU load ${effectiveCpuPct}%${detail} above threshold ${cpuMax}% — capping agents-per-wave at 2.`);
+  } else if (has5mCpu && cpu_load_pct > cpuMax) {
+    // Informational only: 1m spike with a calm 5m average = decaying transient
+    // (typically the coordinator's own just-finished gate run). No cap.
+    reasons.push(`CPU 1m load ${cpu_load_pct}% above threshold ${cpuMax}% but 5m load ${cpu_load_5m_pct}% is below — decaying transient (likely the coordinator's own gate run); no cap (#943).`);
   }
 
   if (claude_processes_count !== null && claude_processes_count !== undefined && claude_processes_count >= concWarn) {
@@ -186,5 +240,17 @@ export function evaluate(snapshot, thresholds) {
     cap = 0;
   }
 
+  // ---------------------------------------------------------------------------
+  // HR-003/HR-004 heavy-repo preflight ceiling (#60): a STATIC cap independent
+  // of the live-probe verdict. Applies only when heavyRepo is true and
+  // agentsPerWave is a finite number — more-restrictive-wins against whatever
+  // the live-probe signals already computed.
+  // ---------------------------------------------------------------------------
+  const { heavyRepo, agentsPerWave } = options;
+  const resolvedApwCap = resolveAgentsPerWaveCap(agentsPerWave);
+  if (heavyRepo === true && resolvedApwCap !== null) {
+    cap = cap === null ? resolvedApwCap : Math.min(cap, resolvedApwCap);
+  }
+
   return { verdict, reasons, recommended_agents_per_wave_cap: cap };
 }

package/scripts/lib/resource-probe.mjs

@@ -15,6 +15,8 @@
  *     ram_used_pct: 78,
  *     cpu_load_1m: 2.4,
  *     cpu_load_pct: 65,
+ *     cpu_load_5m: 1.8,
+ *     cpu_load_5m_pct: 45 | null,   // 5m load-average as pct-of-cores; null on Windows/zero-load (#943)
  *     claude_processes_count: 3 | null,
  *     codex_processes_count: 0 | null,
  *     other_node_processes: 12 | null,
@@ -37,6 +39,7 @@
  *   - scripts/lib/resource-probe/evaluate.mjs     — verdict + threshold logic
  */
 
+import os from 'node:os';
 import { ramSnapshot, cpuSnapshot, processCounts, swapUsedMb, memoryPressurePctFree, ramAvailableGb } from './resource-probe/probe-platform.mjs';
 
 // ---------------------------------------------------------------------------
@@ -63,6 +66,20 @@ export async function probe(opts = {}) {
   const start = Date.now();
   const ram = ramSnapshot();
   const cpu = cpuSnapshot();
+
+  // #943: additionally sample the 5-minute load average. The wave-resource-gate
+  // runs, by construction, right after the coordinator's own CPU-saturating
+  // quality-gate run — the 1m average still carries that decaying tail
+  // (observed 2026-07-30: 96% → 91% → 78% → 75% within 36s after a Full Gate at
+  // 813% CPU), while the 5m average smooths it. Consumers (evaluate(),
+  // wave-resource-gate) judge CPU on min(1m, 5m) when the 5m signal exists.
+  // Windows reports loadavg [0,0,0] → cpu_load_5m_pct stays null there and
+  // consumers fall back to cpu_load_pct alone (which cpuSnapshot() derives from
+  // per-core times on Windows).
+  const load5m = os.loadavg()[1];
+  const cpuCores = (os.cpus() || []).length || 1;
+  const cpu_load_5m = Math.round(load5m * 10) / 10;
+  const cpu_load_5m_pct = load5m > 0 ? Math.min(100, Math.round((load5m / cpuCores) * 100)) : null;
   const zombieThresholdMin = opts.zombieThresholdMin ?? null;
   const procs = opts.skipProcessCounts
     ? { claude_processes_count: null, codex_processes_count: null, other_node_processes: null, zombie_processes_count: null }
@@ -84,6 +101,8 @@ export async function probe(opts = {}) {
     timestamp: new Date().toISOString(),
     ...ram,
     ...cpu,
+    cpu_load_5m,
+    cpu_load_5m_pct,
     ...procs,
     swap_used_mb,
     memory_pressure_pct_free,

package/scripts/lib/rule-loader.mjs

@@ -88,6 +88,12 @@ function getPicomatch() {
  * Minimal glob-to-RegExp fallback used only when picomatch is absent.
  * Handles `**`, `*`, and literal character matching.
  *
+ * Drift contract (W4 B2): a semantically FROZEN twin of this function lives in
+ * scripts/lib/command-blocker.mjs (`redirectGlobToRegExp`) — duplicated there
+ * because that module is hook-hot-path pure and must not import this one.
+ * Syntax extensions made here do NOT automatically apply there; mirror them
+ * deliberately or document the divergence.
+ *
  * @param {string} pattern
  * @returns {RegExp}
  */