session-orchestrator 3.20.0 → 3.22.0

package/scripts/lib/wave-resource-gate.mjs

@@ -7,7 +7,7 @@
  * Part of v3.1.0 Epic #157, Sub-Epic resource-gate. Issue #193.
  */
 
-import { probe } from './resource-probe.mjs';
+import { probe, evaluate } from './resource-probe.mjs';
 
 // ---------------------------------------------------------------------------
 // Public API
@@ -30,10 +30,23 @@ async function extractMeasurements(opts) {
       ramFreeGb: probeOverride.ramFreeGb,
       // Tests may supply ramAvailableGb to exercise the macOS path; absent → null.
       ramAvailableGb: probeOverride.ramAvailableGb ?? null,
+      // macOS memory_pressure — the highest-precedence memory signal (#1089).
+      memoryPressurePctFree: probeOverride.memoryPressurePctFree ?? null,
       cpuLoadPct: probeOverride.cpuLoadPct,
       // 5m-average CPU pct (#943); absent → null (legacy overrides → 1m-only judging).
       cpuLoad5mPct: probeOverride.cpuLoad5mPct ?? null,
+      // #1089: live peer SESSIONS from the registry — the unit
+      // `concurrent-sessions-warn` is named for. Absent → null, and the
+      // rescaled process-count fallback applies.
+      peerSessions: probeOverride.peerSessions ?? null,
+      // Raw Claude PROCESS count. Historically (and misleadingly) named
+      // `concurrentSessions` on this override object; kept as an accepted alias
+      // so existing callers keep working, but it is compared against a
+      // process-denominated threshold now, never a session-denominated one.
+      claudeProcesses: probeOverride.claudeProcesses ?? probeOverride.concurrentSessions ?? null,
       concurrentSessions: probeOverride.concurrentSessions,
+      swapUsedMb: probeOverride.swapUsedMb ?? null,
+      zombieProcesses: probeOverride.zombieProcesses ?? null,
     };
   }
 
@@ -48,12 +61,22 @@ async function extractMeasurements(opts) {
     // macOS: free + reclaimable (vm_stat). null on Linux/Windows where
     // os.freemem() is already accurate. (#667)
     ramAvailableGb: snapshot.ram_available_gb ?? null,
+    // macOS memory_pressure — outranks both of the above (#1089).
+    memoryPressurePctFree: snapshot.memory_pressure_pct_free ?? null,
     cpuLoadPct: snapshot.cpu_load_pct,
     // 5m load-average as pct-of-cores (#943). null on Windows/zero-load, where
     // the gate falls back to judging the 1m-derived cpu_load_pct alone.
     cpuLoad5mPct: snapshot.cpu_load_5m_pct ?? null,
-    // concurrent sessions: number of claude processes found by the probe.
+    // #1089: live peer SESSIONS (registry, self excluded) — what
+    // `concurrent-sessions-warn` was always named for. This line used to read
+    // `concurrentSessions: snapshot.claude_processes_count`, a measured 6x unit
+    // error that made the gate reduce waves on essentially every dispatch.
+    peerSessions: snapshot.peer_sessions_count ?? null,
+    claudeProcesses: snapshot.claude_processes_count ?? null,
+    // Retained for the returned `measurements` object, which callers log.
     concurrentSessions: snapshot.claude_processes_count ?? 0,
+    swapUsedMb: snapshot.swap_used_mb ?? null,
+    zombieProcesses: snapshot.zombie_processes_count ?? null,
   };
 }
 
@@ -131,29 +154,32 @@ function applyHeavyRepoCap(result, opts) {
 }
 
 /**
- * Rules 3-8: resource-driven decision sequence (RAM/CPU/concurrent-sessions).
- * Extracted so `applyDecisionRules` can layer the HR-004 heavy-repo cap on
- * top without duplicating this sequence.
+ * Resource-driven decision, delegated to `evaluate()` (#1089).
  *
- * @param {{ramFreeGb: number, ramAvailableGb?: number|null, cpuLoadPct: number, cpuLoad5mPct?: number|null, concurrentSessions: number}} measurements
+ * This function used to carry its OWN copy of the RAM/CPU/concurrency rules,
+ * running in sequence with first-match-wins. That duplication is exactly why
+ * the #667 available-RAM correction only ever landed halfway: it was applied
+ * here and in `evaluate()` separately, and the memory_pressure precedence that
+ * followed reached only one of the two. There is now one rule engine and this
+ * is a translation layer over it.
+ *
+ * Verdict → decision mapping:
+ *   critical (hard signal)      → coordinator-direct, 0 agents
+ *   warn     (2+ soft signals)  → reduce, plannedAgents / 2 (floor 1)
+ *   green    (0-1 soft signals) → proceed at plannedAgents, reasons retained
+ *
+ * The halving on `warn` is this gate's own policy and deliberately differs
+ * from `evaluate()`'s flat cap of 2: the gate knows `plannedAgents` (a wave of
+ * 3 should not be "capped" UP to nothing), `evaluate()` does not.
+ *
+ * @param {object} measurements — from extractMeasurements
  * @param {object} opts - Same opts shape as evaluateWaveResourceGate
  * @returns {{decision: string, agents: number, reasons: string[], measurements: object}}
  */
 function computeResourceDecision(measurements, opts) {
   const { config, plannedAgents } = opts;
-  const { ramFreeGb, ramAvailableGb, cpuLoadPct, cpuLoad5mPct, concurrentSessions } = measurements;
   const T = config['resource-thresholds'];
 
-  // macOS fix (#667): os.freemem() reports only `Pages free`, which reads
-  // sub-1 GB even on a 128 GB host with 80+ GB reclaimable cache — a false
-  // RAM-critical that forced spurious coordinator-direct fallbacks. When the
-  // probe supplied a numeric `ramAvailableGb` (free + reclaimable, via vm_stat),
-  // judge RAM thresholds on AVAILABLE; otherwise fall back to FREE (Linux/Win,
-  // where os.freemem() is already accurate).
-  const hasAvailable = ramAvailableGb !== null && ramAvailableGb !== undefined;
-  const effectiveRamGb = hasAvailable ? ramAvailableGb : ramFreeGb;
-  const ramLabel = hasAvailable ? 'RAM available' : 'RAM free';
-
   // Rule 3: resource-thresholds missing → degrade to proceed (defensive).
   // Handles legacy pre-#166 configs and test fixtures that omit the key.
   // The gate is considered "ran" — caller receives measurements but no enforcement.
@@ -166,77 +192,45 @@ function computeResourceDecision(measurements, opts) {
     };
   }
 
-  // Rule 4: RAM below critical → coordinator-direct.
-  if (effectiveRamGb < T['ram-free-critical-gb']) {
+  // Translate the gate's measurement shape into a probe-shaped snapshot so the
+  // single rule engine can judge it. Field names differ because the override
+  // object is a documented public test seam that predates the snapshot shape.
+  const snapshot = {
+    ram_free_gb: measurements.ramFreeGb,
+    ram_available_gb: measurements.ramAvailableGb ?? null,
+    memory_pressure_pct_free: measurements.memoryPressurePctFree ?? null,
+    cpu_load_pct: measurements.cpuLoadPct,
+    cpu_load_5m_pct: measurements.cpuLoad5mPct ?? null,
+    peer_sessions_count: measurements.peerSessions ?? null,
+    claude_processes_count: measurements.claudeProcesses ?? null,
+    swap_used_mb: measurements.swapUsedMb ?? null,
+    zombie_processes_count: measurements.zombieProcesses ?? null,
+  };
+
+  // heavyRepo is applied by applyHeavyRepoCap() on the way out, so it is
+  // deliberately NOT passed here — passing it would apply the ceiling twice.
+  const verdict = evaluate(snapshot, T);
+
+  if (verdict.verdict === 'critical') {
     return {
       decision: 'coordinator-direct',
       agents: 0,
-      reasons: [
-        `${ramLabel} ${effectiveRamGb}GB < critical ${T['ram-free-critical-gb']}GB — escalating to coordinator-direct`,
-      ],
-      measurements,
-    };
-  }
-
-  // Rule 5: RAM below min (but above critical) → reduce.
-  if (effectiveRamGb < T['ram-free-min-gb']) {
-    return {
-      decision: 'reduce',
-      agents: Math.max(1, Math.floor(plannedAgents / 2)),
-      reasons: [
-        `${ramLabel} ${effectiveRamGb}GB < min ${T['ram-free-min-gb']}GB — reducing agent count`,
-      ],
+      reasons: verdict.reasons,
       measurements,
     };
   }
-
-  // Rule 6: CPU overloaded → reduce. #943: this gate runs, by construction,
-  // right after the coordinator's own CPU-saturating quality-gate run — the 1m
-  // load average still carries that decaying tail (observed 2026-07-30:
-  // 96% → 91% → 78% → 75% within 36s), so a 1m-only reading systematically
-  // over-reports and halves waves without a real bottleneck. When the probe
-  // supplied a numeric 5m percentage, judge on min(1m, 5m): only-1m-high is a
-  // decaying transient (informational, no reduce), both-high is genuine
-  // sustained load. `cpuLoad5mPct` null (legacy overrides, Windows) → 1m-only.
-  const has5mCpu = typeof cpuLoad5mPct === 'number' && Number.isFinite(cpuLoad5mPct);
-  const effectiveCpuLoadPct = has5mCpu ? Math.min(cpuLoadPct, cpuLoad5mPct) : cpuLoadPct;
-  if (effectiveCpuLoadPct > T['cpu-load-max-pct']) {
-    const detail = has5mCpu ? ` (min of 1m ${cpuLoadPct}% / 5m ${cpuLoad5mPct}%)` : '';
+  if (verdict.verdict === 'warn') {
     return {
       decision: 'reduce',
       agents: Math.max(1, Math.floor(plannedAgents / 2)),
-      reasons: [
-        `CPU load ${effectiveCpuLoadPct}%${detail} > max ${T['cpu-load-max-pct']}% — reducing agent count`,
-      ],
-      measurements,
-    };
-  }
-  const cpuTransientNote =
-    has5mCpu && cpuLoadPct > T['cpu-load-max-pct']
-      ? `info: CPU 1m load ${cpuLoadPct}% > max ${T['cpu-load-max-pct']}% but 5m load ${cpuLoad5mPct}% is below — decaying transient (typically the coordinator's own just-finished gate run), not reducing (#943)`
-      : null;
-
-  // Rule 7: concurrent sessions above warn → proceed with warning.
-  if (concurrentSessions > T['concurrent-sessions-warn']) {
-    return {
-      decision: 'proceed',
-      agents: plannedAgents,
-      reasons: [
-        ...(cpuTransientNote ? [cpuTransientNote] : []),
-        `warn: ${concurrentSessions} concurrent sessions`,
-      ],
+      reasons: verdict.reasons,
       measurements,
     };
   }
-
-  // Rule 8: all within bounds.
   return {
     decision: 'proceed',
     agents: plannedAgents,
-    reasons: [
-      ...(cpuTransientNote ? [cpuTransientNote] : []),
-      'all thresholds within bounds',
-    ],
+    reasons: verdict.reasons.length > 0 ? verdict.reasons : ['all thresholds within bounds'],
     measurements,
   };
 }

package/scripts/materialize-wave-scope.mjs

@@ -0,0 +1,281 @@
+#!/usr/bin/env node
+/**
+ * Materialize both wave file-scope declaration shapes from one canonical array.
+ *
+ * Usage:
+ *   node scripts/materialize-wave-scope.mjs --state-dir <dir> --wave <positive-int> [--json] < scopes.json
+ *
+ * The stdin document is an array of `{ id, files }` records. The command writes
+ * each bare `files` array first, then writes the complete record array as the
+ * aggregate sidecar consumed by validate-wave-scope's --assert-disjoint and
+ * --union modes.
+ */
+
+import { readFileSync, unlinkSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { writeJsonAtomicSync } from './lib/io.mjs';
+
+const HELP = `Usage: node scripts/materialize-wave-scope.mjs --state-dir <dir> --wave <positive-int> [--json]
+
+Read one JSON array of {id, files} records from stdin and materialize both
+wave-scope declaration shapes from that canonical record array.
+
+Required:
+  --state-dir <dir>   State directory that owns filescopes/.
+  --wave <positive-int>
+                      Positive wave number used in filescopes/wave-N/.
+
+Options:
+  --json              Emit {ok, aggregatePath, perAgentPaths} to stdout.
+  -h, --help          Show this help and exit 0.
+
+Output:
+  Human mode prints only the aggregate sidecar path. --json prints one JSON
+  object. Diagnostics are written only to stderr.
+
+Examples:
+  printf '%s' '[{"id":"W1-I1","files":["scripts/example.mjs"]},{"id":"coordinator","files":[]}]' | \\
+    node scripts/materialize-wave-scope.mjs --state-dir .claude --wave 1
+  node scripts/materialize-wave-scope.mjs --state-dir .claude --wave 1 --json < scopes.json
+
+Writes:
+  <state-dir>/filescopes/wave-N/<id>.json       Bare string[] for each record
+  <state-dir>/filescopes/wave-N.scopes.json     Aggregate [{id, files}, ...]
+
+Exit codes:
+  0  All declaration files and the aggregate sidecar were written.
+  1  Usage or input validation error; no write was attempted.
+  2  Filesystem or write error; earlier per-agent writes are retained and any
+     previous aggregate is invalidated before per-agent writes begin.
+`;
+
+class InputError extends Error {}
+class WriteError extends Error {}
+
+/**
+ * @param {string[]} argv
+ * @returns {{ stateDir: string, wave: number, json: boolean, help: boolean }}
+ */
+export function parseCliArgs(argv) {
+  let stateDir;
+  let waveRaw;
+  let json = false;
+  let help = false;
+
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index];
+    if (arg === '--json') {
+      json = true;
+      continue;
+    }
+    if (arg === '--help' || arg === '-h') {
+      help = true;
+      continue;
+    }
+    if (arg === '--state-dir' || arg === '--wave') {
+      const value = argv[index + 1];
+      if (value === undefined || value.startsWith('--')) {
+        throw new InputError(`${arg} requires a value`);
+      }
+      if (arg === '--state-dir') {
+        if (stateDir !== undefined) throw new InputError('--state-dir may be specified only once');
+        stateDir = value;
+      } else {
+        if (waveRaw !== undefined) throw new InputError('--wave may be specified only once');
+        waveRaw = value;
+      }
+      index++;
+      continue;
+    }
+    throw new InputError(`unknown argument: ${arg}`);
+  }
+
+  if (help) return { stateDir: '', wave: 0, json, help: true };
+  if (stateDir === undefined) throw new InputError('--state-dir is required');
+  if (waveRaw === undefined) throw new InputError('--wave is required');
+  if (stateDir.length === 0 || /[\0\r\n]/.test(stateDir)) {
+    throw new InputError('--state-dir must be a non-empty path without NUL or newline characters');
+  }
+  if (!/^[1-9]\d*$/.test(waveRaw)) {
+    throw new InputError('--wave must be a positive integer');
+  }
+
+  const wave = Number(waveRaw);
+  if (!Number.isSafeInteger(wave)) throw new InputError('--wave must be a safe positive integer');
+  return { stateDir, wave, json, help: false };
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * A path is scope data rather than an output target, so absolute paths remain
+ * valid for sanctioned out-of-repository grants. Traversal/control characters
+ * are rejected because no scope consumer can safely interpret them verbatim.
+ *
+ * @param {unknown} value
+ * @param {number} recordIndex
+ * @param {number} fileIndex
+ */
+function validateScopePath(value, recordIndex, fileIndex) {
+  if (typeof value !== 'string' || value.length === 0 || value.trim().length === 0) {
+    throw new InputError(`record #${recordIndex} files[${fileIndex}] must be a non-empty string`);
+  }
+  if (/[\0\r\n]/.test(value)) {
+    throw new InputError(`record #${recordIndex} files[${fileIndex}] must not contain NUL or newline characters`);
+  }
+  if (value.split(/[\\/]+/).includes('..')) {
+    throw new InputError(`record #${recordIndex} files[${fileIndex}] must not contain path traversal`);
+  }
+}
+
+/**
+ * Validate the canonical record array completely before a write is attempted.
+ * The original values are returned without sorting, deduplication, or expansion.
+ *
+ * @param {unknown} value
+ * @returns {Array<{id: string, files: string[]}>}
+ */
+export function validateScopeRecords(value) {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new InputError('stdin must be a non-empty JSON array of {id, files} records');
+  }
+
+  const seenIds = new Set();
+  let coordinatorCount = 0;
+  for (let recordIndex = 0; recordIndex < value.length; recordIndex++) {
+    const record = value[recordIndex];
+    if (!isRecord(record)) {
+      throw new InputError(`record #${recordIndex} must be an object with id and files`);
+    }
+    if (typeof record.id !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(record.id)) {
+      throw new InputError(`record #${recordIndex} has an unsafe id`);
+    }
+    const idKey = record.id.toLowerCase();
+    if (seenIds.has(idKey)) {
+      throw new InputError(`record #${recordIndex} has duplicate id (case-insensitive): ${record.id}`);
+    }
+    seenIds.add(idKey);
+    if (idKey === 'coordinator') {
+      if (record.id !== 'coordinator') {
+        throw new InputError(`record #${recordIndex} id must be exactly coordinator (lowercase)`);
+      }
+      coordinatorCount++;
+    }
+
+    if (!Array.isArray(record.files)) {
+      throw new InputError(`record #${recordIndex} (${record.id}) must have a files string array`);
+    }
+    for (let fileIndex = 0; fileIndex < record.files.length; fileIndex++) {
+      validateScopePath(record.files[fileIndex], recordIndex, fileIndex);
+    }
+  }
+
+  if (coordinatorCount !== 1) {
+    throw new InputError(`input must contain exactly one coordinator record; found ${coordinatorCount}`);
+  }
+  return value;
+}
+
+/**
+ * Materialize validated declarations in their required write order.
+ *
+ * The optional writer is a narrow seam for deterministic write-failure tests;
+ * production always delegates to writeJsonAtomicSync. There is intentionally no
+ * rollback: a prior aggregate is invalidated before per-agent writes, then the
+ * aggregate publication marker is written only after every per-agent declaration
+ * has succeeded.
+ *
+ * @param {Array<{id: string, files: string[]}>} records
+ * @param {{ stateDir: string, wave: number, writeJson?: typeof writeJsonAtomicSync }} options
+ * @returns {{ aggregatePath: string, perAgentPaths: string[] }}
+ */
+export function materializeWaveScope(records, { stateDir, wave, writeJson = writeJsonAtomicSync }) {
+  const scopeDir = resolve(stateDir, 'filescopes', `wave-${wave}`);
+  const aggregatePath = resolve(stateDir, 'filescopes', `wave-${wave}.scopes.json`);
+  const perAgentPaths = records.map(({ id }) => resolve(scopeDir, `${id}.json`));
+
+  try {
+    unlinkSync(aggregatePath);
+  } catch (error) {
+    if (error?.code !== 'ENOENT') {
+      throw new WriteError(`cannot invalidate aggregate declaration ${aggregatePath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  for (let index = 0; index < records.length; index++) {
+    const result = writeJson(perAgentPaths[index], records[index].files, { tmpPrefix: '.materialize-wave-scope' });
+    if (!result?.ok) {
+      throw new WriteError(`cannot write per-agent declaration ${perAgentPaths[index]}: ${result?.error ?? 'unknown write failure'}`);
+    }
+  }
+
+  const aggregateResult = writeJson(aggregatePath, records, { tmpPrefix: '.materialize-wave-scope' });
+  if (!aggregateResult?.ok) {
+    throw new WriteError(`cannot write aggregate declaration ${aggregatePath}: ${aggregateResult?.error ?? 'unknown write failure'}`);
+  }
+  return { aggregatePath, perAgentPaths };
+}
+
+/**
+ * @param {string} message
+ * @param {number} code
+ */
+function fail(message, code) {
+  process.stderr.write(`materialize-wave-scope: ${message}\n`);
+  process.exitCode = code;
+}
+
+function readStdinJson() {
+  let raw;
+  try {
+    raw = readFileSync(0, 'utf8');
+  } catch (error) {
+    throw new WriteError(`cannot read stdin: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new InputError('stdin is not valid JSON');
+  }
+}
+
+/** Execute the CLI, mapping usage/input and I/O failures to its exit contract. */
+export function main() {
+  let args;
+  try {
+    args = parseCliArgs(process.argv.slice(2));
+    if (args.help) {
+      process.stdout.write(HELP);
+      return;
+    }
+    const records = validateScopeRecords(readStdinJson());
+    const { aggregatePath, perAgentPaths } = materializeWaveScope(records, args);
+    process.stdout.write(
+      args.json
+        ? `${JSON.stringify({ ok: true, aggregatePath, perAgentPaths })}\n`
+        : `${aggregatePath}\n`,
+    );
+  } catch (error) {
+    if (error instanceof InputError) {
+      fail(error.message, 1);
+      return;
+    }
+    if (error instanceof WriteError) {
+      fail(error.message, 2);
+      return;
+    }
+    fail(`unexpected system error: ${error instanceof Error ? error.message : String(error)}`, 2);
+  }
+}
+
+const invokedPath = process.argv[1] ? resolve(process.argv[1]) : null;
+if (invokedPath === fileURLToPath(import.meta.url)) {
+  main();
+}

package/scripts/print-learnings-index.mjs

@@ -23,6 +23,13 @@
  * block therefore rides the dispatch-prompt channel the repo already owns and
  * writes itself — it adds no new delivery mechanism.
  *
+ * With ONE exception, closed in #1019: a learning that `/reconcile` has already
+ * turned into a `.claude/rules/*.md` file DOES have a native path, and shipping
+ * it here too is the same duplication in miniature. `--rules-dir` (default
+ * `.claude/rules`) feeds that set to the selector, which drops those records
+ * before its Top-N cut so the freed slot goes to a learning the agent has no
+ * other way to see. A repo with no rules directory is unaffected, byte for byte.
+ *
  * ## An INDEX, not a corpus
  *
  * One line per learning plus a retrieval pointer. The agent that needs the full
@@ -65,7 +72,8 @@
  *                `<learnings-<token>>` … `</learnings-<token>>` fence. Empty
  *                selection → NO output at all (exit 0) so the caller prepends
  *                nothing.
- *   - --json   → `{ count, scopeMatched, rejected, learnings: [...] }`
+ *   - --json   → `{ count, scopeMatched, rejected, deliveredFiltered,
+ *                   learnings: [...] }`
  *
  * Exit codes (per .claude/rules/cli-design.md):
  *   0 — success, INCLUDING EPIPE (a truncating reader — `| head`, `| grep -q` —
@@ -144,6 +152,10 @@ Options:
   --max-chars <n>       Hard cap on the rendered index body (default: ${LEARNINGS_INDEX_MAX_CHARS}).
   --pool-size <n>       Active entries pulled before ranking (default: ${CANDIDATE_POOL_SIZE}).
   --learnings <path>    Learnings JSONL (default: .orchestrator/metrics/learnings.jsonl).
+  --rules-dir <path>    Natively-delivered rule corpus (default: .claude/rules).
+                        Learnings already delivered as a rule file there are
+                        excluded from the index (#1019). A path that does not
+                        exist means "this repo delivers no rules" -> no filtering.
   --no-event            Suppress the orchestrator.learnings.index.injected event.
   --json                Emit { count, scopeMatched, learnings:[...] } instead of
                         the Markdown block.
@@ -194,6 +206,7 @@ try {
       'max-chars': { type: 'string' },
       'pool-size': { type: 'string' },
       learnings: { type: 'string' },
+      'rules-dir': { type: 'string' },
       'no-event': { type: 'boolean', default: false },
       json: { type: 'boolean', default: false },
     },
@@ -236,6 +249,13 @@ const learningsPath = opts.learnings
   ? opts.learnings
   : join(repoRoot, '.orchestrator', 'metrics', 'learnings.jsonl');
 const eventsPath = join(repoRoot, '.orchestrator', 'metrics', 'events.jsonl');
+// #1019 — the natively-delivered rule corpus. Every `.claude/rules/*.md` reaches
+// a dispatched agent in FULL through Claude Code's own project-instruction
+// loading (`docs/instruction-delivery.md` §1: the `globs:`/`tier:` frontmatter is
+// inert because `rule-loader.mjs` does not run on that path), so a learning that
+// already became a rule must not also spend a slot in this index. An absent
+// directory yields an empty set and the index is byte-identical to before.
+const rulesDir = opts['rules-dir'] ? opts['rules-dir'] : join(repoRoot, '.claude', 'rules');
 
 // ---------------------------------------------------------------------------
 // Scope resolution ladder: --file-scope -> --wave-scope allowedPaths -> empty
@@ -284,7 +304,8 @@ if (opts['file-scope']) {
   const doc = readJsonOrNull(opts['file-scope'], true, '--file-scope');
   // The agent's "Files:" scope is written as a bare JSON array (#796
   // $AGENT_FILESCOPE_JSON); tolerate an {allowedPaths:[...]} wrapper too so the
-  // same temp file can be reused for either flag without a reshape step.
+  // same file can be reused for either flag without a reshape step. That file is
+  // `<state-dir>/filescopes/wave-<N>/<agent-id>.json` (#1020), never a $TMPDIR copy.
   scopePaths = cleanPaths(Array.isArray(doc) ? doc : doc?.allowedPaths);
   if (scopePaths.length > 0) scopeSource = 'file-scope';
 }
@@ -315,7 +336,7 @@ try {
   selection = await selectLearningsFromFile(
     learningsPath,
     { file_paths: scopePaths, text: taskText },
-    { maxScoped, maxGlobal, maxChars, poolSize },
+    { maxScoped, maxGlobal, maxChars, poolSize, rulesDir },
   );
 } catch (err) {
   // `selectLearningsFromFile` is contractually total (contract point 1), so this
@@ -419,6 +440,11 @@ function emitInjectedEvent(bytes) {
       // Non-zero means the untrusted-text guard dropped a record. Carried in the
       // event so a drop is observable after the fact rather than silent.
       rejected: selection.rejected,
+      // #1019 — records skipped because `.claude/rules/*.md` already delivers
+      // them natively. Same reason as `rejected`: without the count, a filter
+      // that stopped biting looks exactly like a corpus with no rule-derived
+      // learnings in it.
+      delivered_filtered: selection.deliveredFiltered,
       bytes,
       scope_source: scopeSource,
     });
@@ -451,6 +477,7 @@ if (opts.json) {
     count: selected.length,
     scopeMatched,
     rejected: selection.rejected,
+    deliveredFiltered: selection.deliveredFiltered,
     learnings: selected.map((e) => ({
       id: e.id,
       type: e.type,