session-orchestrator 3.16.0 → 3.19.0

package/scripts/lib/reconcile/idempotency.mjs

@@ -10,7 +10,13 @@
  * lines — an append would leave stale duplicates.
  *
  * Store: `.orchestrator/runtime/reconcile-candidates.jsonl` — a mutable
- * work-queue in JSON-Lines format (one ReconcileCandidate per line).
+ * work-queue in JSON-Lines format (one ReconcileCandidate per line). The store
+ * is OWNED by `mergeCandidates`: it is the only sanctioned writer. Nothing else
+ * — no report, no analysis run, no agent — may append to it; a read-side shape
+ * guard drops any record that is not a ReconcileCandidate and COUNTS the drop.
+ * The count reaches readers through the ONE reader ({@link loadCandidates}
+ * returns `{records, skipped}`) and writers through `mergeCandidates`'s
+ * `skipped` — there is deliberately no lossy array-only variant beside them.
  *
  * Two responsibilities differ from the repair store:
  *   1. The IDEMPOTENCY KEY is the LOGICAL `learning_key` (issue #695), not the
@@ -66,12 +72,40 @@ function resolveStorePath(repoRoot, storePath) {
   return join(root, rel);
 }
 
+/**
+ * Minimal shape guard for a persisted store line. A record is accepted only
+ * when it carries the two fields every consumer of this store depends on:
+ *   - `learning_key` — THE logical dedupe key (`mergeCandidates`, `isProcessed`).
+ *   - `created_at`   — the recency axis (`reconcile-nudge-banner.mjs` `_lastRunAt`).
+ *
+ * This is deliberately NOT a full schema check: the store is a mutable
+ * work-queue whose records may gain fields across schema versions, so
+ * over-strict validation would silently drop legitimate future records. It
+ * rejects only records that no writer in this repo produces — the concrete
+ * incident being a hand-written report artefact using `candidate_id` /
+ * `generated_at` / `status:"candidate"` (2026-07-31, see
+ * `docs/reconcile/2026-07-31-reconcile-candidates.md`).
+ * @param {unknown} rec
+ * @returns {boolean}
+ */
+function isCandidateShape(rec) {
+  if (!rec || typeof rec !== 'object' || Array.isArray(rec)) return false;
+  const r = /** @type {Record<string, unknown>} */ (rec);
+  if (typeof r.learning_key !== 'string' || r.learning_key.length === 0) return false;
+  if (typeof r.created_at !== 'string') return false;
+  return true;
+}
+
 /**
  * Read + defensively parse the store's JSONL lines into ReconcileCandidate
- * records. Malformed lines (bad JSON, non-object) are skipped silently. A
- * missing file yields `[]`. Never throws.
+ * records. Malformed lines (bad JSON, non-object) and shape-foreign records
+ * (see {@link isCandidateShape}) are skipped — the latter are COUNTED, because
+ * the store is a mutable work-queue that `mergeCandidates` rewrites in full, so
+ * a skipped line is dropped from disk on the next merge and a silent drop would
+ * be unattributable data loss. A missing file yields `{ records: [], skipped: 0 }`.
+ * Never throws.
  * @param {string} absPath
- * @returns {ReconcileCandidate[]}
+ * @returns {{ records: ReconcileCandidate[], skipped: number }}
  */
 function readStore(absPath) {
   let raw;
@@ -79,11 +113,12 @@ function readStore(absPath) {
     raw = readFileSync(absPath, 'utf8');
   } catch {
     // ENOENT or any read error → empty store.
-    return [];
+    return { records: [], skipped: 0 };
   }
 
   /** @type {ReconcileCandidate[]} */
   const records = [];
+  let skipped = 0;
   for (const line of raw.split('\n')) {
     const trimmed = line.trim();
     if (trimmed.length === 0) continue;
@@ -91,13 +126,16 @@ function readStore(absPath) {
     try {
       parsed = JSON.parse(trimmed);
     } catch {
+      skipped += 1;
       continue; // skip malformed line
     }
-    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+    if (isCandidateShape(parsed)) {
       records.push(/** @type {ReconcileCandidate} */ (parsed));
+    } else {
+      skipped += 1;
     }
   }
-  return records;
+  return { records, skipped };
 }
 
 /**
@@ -153,13 +191,70 @@ export function makeCandidateId(learningKey, slug) {
 }
 
 /**
- * Load every ReconcileCandidate currently persisted in the store. Reads JSONL,
- * skips malformed lines, returns `[]` for a missing file. Does NOT create the
+ * Build a ReconcileCandidate line-record for a proposed or rejected learning.
+ *
+ * Lives here — beside the {@link ReconcileCandidate} typedef it instantiates and
+ * the read-side `isCandidateShape` guard that judges it — so ONE file decides
+ * which fields a persisted record carries. It deliberately does NOT mint the
+ * `id` (see {@link makeCandidateId}): rejections currently derive their id from
+ * `(learningKey, 'rejected-<type>')` while storing `slug: ''`, so folding the
+ * mint in here using the record's own slug would change every rejection
+ * candidate's id and orphan every rejection row already on disk. Caller-supplied
+ * `id` keeps that decision at the call site.
+ *
+ * `created_at` is caller-supplied (from the engine's injectable clock) so output
+ * stays deterministic under test. `processed_at`/`superseded_by` always start
+ * null — only the merge/approval path stamps them. Never throws.
+ *
+ * @param {Object} params
+ * @param {string} params.id - deterministic physical id, see {@link makeCandidateId}.
+ * @param {string|null} params.learningKey - logical dedupe key; a non-string coerces to `''`.
+ * @param {string} params.slug - `.claude/rules/<slug>.md` slug (`''` for rejections).
+ * @param {'proposed'|'rejected'} params.status
+ * @param {string} params.reason
+ * @param {number} params.confidence
+ * @param {string} params.createdAt - ISO timestamp.
+ * @returns {ReconcileCandidate}
+ */
+export function buildCandidate({ id, learningKey, slug, status, reason, confidence, createdAt }) {
+  return {
+    id,
+    schema_version: 1,
+    learning_key: typeof learningKey === 'string' ? learningKey : '',
+    slug,
+    status,
+    reason,
+    confidence,
+    created_at: createdAt,
+    processed_at: null,
+    superseded_by: null,
+  };
+}
+
+/**
+ * Load the persisted store: every ReconcileCandidate that survives the read-side
+ * shape guard, PLUS the count of lines it rejected. Reads JSONL, skips malformed
+ * lines and shape-foreign records (missing `learning_key` / `created_at`),
+ * yields `{ records: [], skipped: 0 }` for a missing file. Does NOT create the
  * runtime dir (mkdir -p happens only on write). Never throws.
+ *
+ * `skipped` is part of the return value rather than a second, "diagnostics"
+ * reader beside this one, because `records.length === 0` is AMBIGUOUS on its
+ * own: a missing store and a store whose every line is shape-foreign both yield
+ * `[]`, and a consumer that sees only the array reports "no reconcile run on
+ * record" for a store that in fact holds quarantined evidence of one (the
+ * concrete defect in `scripts/lib/reconcile-nudge-banner.mjs`, GitLab #955
+ * finding 2). Splitting the honest reader off under a longer name left the
+ * OBVIOUS name as the lossy one — the next consumer would reach for
+ * `loadCandidates`, get `[]`, and re-derive the same wrong conclusion. One
+ * reader, one answer.
+ *
+ * Read-only: unlike {@link mergeCandidates} this does NOT rewrite the store, so
+ * the skipped lines are still on disk after this call.
  * @param {Object} [params]
  * @param {string} [params.repoRoot] - repo root; relative `storePath` is resolved against it (defaults to `process.cwd()`).
  * @param {string} [params.storePath] - store path (relative ⇒ joined to repoRoot). Defaults to {@link DEFAULT_STORE_PATH}.
- * @returns {ReconcileCandidate[]}
+ * @returns {{ records: ReconcileCandidate[], skipped: number }}
  */
 export function loadCandidates({ repoRoot, storePath } = {}) {
   const absPath = resolveStorePath(repoRoot, storePath);
@@ -198,16 +293,21 @@ export function isProcessed(candidate, existing) {
  * The runtime dir is created with mkdir -p semantics. The store is rewritten in
  * full (read-all → merge → atomic tmp+rename), never appended. Output lines are
  * sorted by `learning_key` for deterministic output. Never throws; on write
- * failure returns `{ merged, written: false }`.
+ * failure returns `written: false`.
+ *
+ * `skipped` reports how many persisted lines the read-side shape guard rejected
+ * (malformed JSON, or a record missing `learning_key`/`created_at`). Because the
+ * store is rewritten in full, those lines are DROPPED from disk by this call —
+ * the count is what makes that loss attributable instead of silent.
  * @param {Object} [params]
  * @param {ReconcileCandidate[]} [params.candidates] - newly minted candidates to merge.
  * @param {string} [params.repoRoot]
  * @param {string} [params.storePath]
- * @returns {{ merged: ReconcileCandidate[], written: boolean }}
+ * @returns {{ merged: ReconcileCandidate[], written: boolean, skipped: number }}
  */
 export function mergeCandidates({ candidates, repoRoot, storePath } = {}) {
   const absPath = resolveStorePath(repoRoot, storePath);
-  const store = readStore(absPath);
+  const { records: store, skipped } = readStore(absPath);
 
   // Index existing records by learning_key for O(1) lookup. Last write wins for
   // any pre-existing duplicates in the file (defensive — store should be unique).
@@ -235,5 +335,5 @@ export function mergeCandidates({ candidates, repoRoot, storePath } = {}) {
   );
 
   const result = writeStore(absPath, merged);
-  return { merged, written: result.ok === true };
+  return { merged, written: result.ok === true, skipped };
 }

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}
  */