session-orchestrator 3.16.0 → 3.19.0

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

@@ -20,7 +20,7 @@ import { probe } from './resource-probe.mjs';
  * "proceed" decision.
  *
  * @param {object} opts - Same opts shape as evaluateWaveResourceGate
- * @returns {Promise<{ramFreeGb: number, ramAvailableGb: number|null, cpuLoadPct: number, concurrentSessions: number} | {probeFailed: true}>}
+ * @returns {Promise<{ramFreeGb: number, ramAvailableGb: number|null, cpuLoadPct: number, cpuLoad5mPct: number|null, concurrentSessions: number} | {probeFailed: true}>}
  */
 async function extractMeasurements(opts) {
   const { probeOverride } = opts;
@@ -31,6 +31,8 @@ async function extractMeasurements(opts) {
       // Tests may supply ramAvailableGb to exercise the macOS path; absent → null.
       ramAvailableGb: probeOverride.ramAvailableGb ?? null,
       cpuLoadPct: probeOverride.cpuLoadPct,
+      // 5m-average CPU pct (#943); absent → null (legacy overrides → 1m-only judging).
+      cpuLoad5mPct: probeOverride.cpuLoad5mPct ?? null,
       concurrentSessions: probeOverride.concurrentSessions,
     };
   }
@@ -47,6 +49,9 @@ async function extractMeasurements(opts) {
     // os.freemem() is already accurate. (#667)
     ramAvailableGb: snapshot.ram_available_gb ?? 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.
     concurrentSessions: snapshot.claude_processes_count ?? 0,
   };
@@ -54,15 +59,89 @@ async function extractMeasurements(opts) {
 
 /**
  * Apply the gate decision rule sequence (rules 3-8) given measurements and
- * config. Returns the full gate result.
+ * config, then apply the HR-004 heavy-repo preflight ceiling on top. Returns
+ * the full gate result.
  *
- * @param {{ramFreeGb: number, cpuLoadPct: number, concurrentSessions: number}} measurements
+ * @param {{ramFreeGb: number, ramAvailableGb?: number|null, cpuLoadPct: number, cpuLoad5mPct?: number|null, concurrentSessions: number}} measurements
  * @param {object} opts - Same opts shape as evaluateWaveResourceGate
  * @returns {{decision: string, agents: number, reasons: string[], measurements: object}}
  */
 function applyDecisionRules(measurements, opts) {
+  const result = computeResourceDecision(measurements, opts);
+  return applyHeavyRepoCap(result, opts);
+}
+
+/**
+ * Resolve an `agents-per-wave` config value into a plain numeric cap, or
+ * `null` when no cap should apply.
+ *
+ * `_coerceInteger()` (scripts/lib/config/coercers.mjs) parses the documented
+ * HR-003 parenthetical-override syntax — `agents-per-wave: 4 (deep: 18)` —
+ * into an OBJECT `{ default: 4, deep: 18 }`, not a plain number. Feeding that
+ * object straight into a `typeof cap !== 'number'` guard makes the heavy-repo
+ * cap silently no-op for every repo using the override syntax, which defeats
+ * HR-004 exactly where it matters most (a heavy repo that also runs deep
+ * sessions).
+ *
+ * `evaluateWaveResourceGate()` has no session-mode input in scope — `waveRole`
+ * is a wave role (e.g. "Impl-Core"), not a session mode (e.g. "deep") — so the
+ * object shape resolves to `cap.default` here. That is the conservative
+ * choice: the documented HR-003 convention writes the override as
+ * `<default> (mode: <higher-ceiling>)`, i.e. `default` is the MORE
+ * restrictive of the pair. Falling back to it can only under-apply a looser
+ * mode-specific ceiling; it never lets a heavy repo exceed its base cap.
+ *
+ * @param {number|{default: number, [mode: string]: number}|*} cap
+ * @returns {number|null}
+ */
+function resolveApwCap(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;
+}
+
+/**
+ * HR-003/HR-004 heavy-repo preflight ceiling (baseline #60). A STATIC cap
+ * independent of the live resource-probe verdict: when `config['heavy-repo']`
+ * is `true`, `agents` is clamped to at most `config['agents-per-wave']`
+ * (resolved via {@link resolveApwCap} to handle the object-override shape).
+ * More-restrictive-wins — this only ever LOWERS `agents`, never raises it
+ * above what the resource-driven rules already decided (e.g. a
+ * coordinator-direct 0 stays 0).
+ *
+ * @param {{decision: string, agents: number, reasons: string[], measurements: object}} result
+ * @param {object} opts - Same opts shape as evaluateWaveResourceGate
+ * @returns {{decision: string, agents: number, reasons: string[], measurements: object}}
+ */
+function applyHeavyRepoCap(result, opts) {
+  const { config } = opts;
+  if (!config || config['heavy-repo'] !== true) return result;
+  const cap = resolveApwCap(config['agents-per-wave']);
+  if (cap === null) return result;
+  if (result.agents <= cap) return result; // already within the ceiling — never raise
+  return {
+    ...result,
+    decision: result.decision === 'coordinator-direct' ? 'coordinator-direct' : 'reduce',
+    agents: cap,
+    reasons: [...result.reasons, `heavy-repo: true caps agents-per-wave to ${cap} (HR-004)`],
+  };
+}
+
+/**
+ * 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.
+ *
+ * @param {{ramFreeGb: number, ramAvailableGb?: number|null, cpuLoadPct: number, cpuLoad5mPct?: number|null, concurrentSessions: number}} measurements
+ * @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, concurrentSessions } = measurements;
+  const { ramFreeGb, ramAvailableGb, cpuLoadPct, cpuLoad5mPct, concurrentSessions } = measurements;
   const T = config['resource-thresholds'];
 
   // macOS fix (#667): os.freemem() reports only `Pages free`, which reads
@@ -111,24 +190,41 @@ function applyDecisionRules(measurements, opts) {
     };
   }
 
-  // Rule 6: CPU overloaded → reduce.
-  if (cpuLoadPct > T['cpu-load-max-pct']) {
+  // 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}%)` : '';
     return {
       decision: 'reduce',
       agents: Math.max(1, Math.floor(plannedAgents / 2)),
       reasons: [
-        `CPU load ${cpuLoadPct}% > max ${T['cpu-load-max-pct']}% — reducing agent count`,
+        `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: [`warn: ${concurrentSessions} concurrent sessions`],
+      reasons: [
+        ...(cpuTransientNote ? [cpuTransientNote] : []),
+        `warn: ${concurrentSessions} concurrent sessions`,
+      ],
       measurements,
     };
   }
@@ -137,7 +233,10 @@ function applyDecisionRules(measurements, opts) {
   return {
     decision: 'proceed',
     agents: plannedAgents,
-    reasons: ['all thresholds within bounds'],
+    reasons: [
+      ...(cpuTransientNote ? [cpuTransientNote] : []),
+      'all thresholds within bounds',
+    ],
     measurements,
   };
 }
@@ -148,14 +247,19 @@ function applyDecisionRules(measurements, opts) {
  * @param {object} opts.config - Parsed Session Config (from parse-config.sh output)
  * @param {number} opts.plannedAgents - Number of agents the session-plan wants to dispatch
  * @param {string} opts.waveRole - e.g. "Impl-Core", "Quality"
- * @param {object} [opts.probeOverride] - {ramFreeGb, cpuLoadPct, concurrentSessions} for
- *   testing; when omitted, calls resource-probe
+ * @param {object} [opts.probeOverride] - {ramFreeGb, cpuLoadPct, cpuLoad5mPct?, concurrentSessions}
+ *   for testing; when omitted, calls resource-probe
  * @returns {Promise<{decision: "proceed"|"reduce"|"coordinator-direct", agents: number, reasons: string[], measurements: object}>}
  */
 export async function evaluateWaveResourceGate(opts) {
   const { config, plannedAgents } = opts;
 
   // Rule 1: resource-awareness disabled — skip all probing.
+  // `resource-awareness: false` is a FULL opt-out, INCLUDING the HR-004
+  // heavy-repo static cap below (applyHeavyRepoCap runs only inside
+  // applyDecisionRules, which this early return bypasses entirely). The
+  // static cap only applies on the resource-aware path — deliberate,
+  // reviewed 2026-07-23, baseline #60.
   if (config['resource-awareness'] === false) {
     return {
       decision: 'proceed',

package/scripts/lib/worktree/listing.mjs

@@ -2,7 +2,8 @@
  * worktree/listing.mjs — list and filter worktrees.
  *
  * Exports:
- *   listWorktrees()                            — list all git worktrees
+ *   listWorktrees()                            — list all git worktrees (bare array; swallows git failure)
+ *   listWorktreesChecked()                     — same listing WITH a "git actually ran" signal (#919.3)
  *   applyWorktreeExcludes(wtPath, patterns)    — remove top-level dirs from worktree
  *
  * No imports from lifecycle.mjs — this module is intentionally a leaf of the
@@ -18,23 +19,39 @@ import path from 'node:path';
 // ---------------------------------------------------------------------------
 
 /**
- * List all git worktrees in the current repository.
+ * List all git worktrees WITH an explicit "git actually ran" signal (#919.3).
+ *
+ * The bare `listWorktrees()` below swallows a failing `git worktree list` into
+ * an empty array — indistinguishable from "git ran, repo has no extra
+ * worktrees". That collapse is the last fail-open gap in the
+ * `checkLiveForeignSession` full path (peer-discovery.mjs, #906/#908 residual):
+ * a total surface failure read as "nobody home". This variant keeps the listing
+ * contract but makes the failure DISTINGUISHABLE, so callers that need the
+ * distinction can make the fail-safe call themselves.
  *
  * @param {object} [opts]
  * @param {Function} [opts.$]  Optional zx-compatible executor. Defaults to real zx.$.
  *   Tests pass a mock here to avoid vi.mock('zx') under fork pool.
- * @returns {Promise<Array<{path: string, branch: string, head: string}>>}
- *   Array of worktree descriptors; empty array if none or on parse error.
+ * @returns {Promise<{ok: boolean, worktrees: Array<{path: string, branch: string, head: string}>, error?: string}>}
+ *   `ok: true`  — `git worktree list` ran; `worktrees` is the (possibly empty)
+ *                 parsed listing. An empty list here is a MEASUREMENT.
+ *   `ok: false` — the git invocation itself failed (spawn error, non-zero
+ *                 exit, not a repo, …); `worktrees` is `[]` and `error` carries
+ *                 the failure message. An empty list here is NOT a measurement.
  */
-export async function listWorktrees(opts = {}) {
+export async function listWorktreesChecked(opts = {}) {
   const dollar = opts.$ ?? defaultDollar;
   const git = dollar({ cwd: process.cwd() });
   let output;
   try {
     const result = await git`git worktree list --porcelain`;
     output = result.stdout;
-  } catch {
-    return [];
+  } catch (err) {
+    return {
+      ok: false,
+      worktrees: [],
+      error: err instanceof Error ? err.message : String(err),
+    };
   }
 
   const worktrees = [];
@@ -67,6 +84,26 @@ export async function listWorktrees(opts = {}) {
     worktrees.push(current);
   }
 
+  return { ok: true, worktrees };
+}
+
+/**
+ * List all git worktrees in the current repository.
+ *
+ * Thin backward-compatible wrapper over `listWorktreesChecked()`: existing
+ * callers get the bare array they always got, INCLUDING the historical
+ * swallow-to-`[]` on git failure. Callers that must distinguish "git ran,
+ * empty" from "git failed" use `listWorktreesChecked()` instead (#919.3).
+ *
+ * @param {object} [opts]
+ * @param {Function} [opts.$]  Optional zx-compatible executor. Defaults to real zx.$.
+ *   Tests pass a mock here to avoid vi.mock('zx') under fork pool.
+ * @returns {Promise<Array<{path: string, branch: string, head: string}>>}
+ *   Array of worktree descriptors; empty array if none OR on git failure
+ *   (the two are indistinguishable here — by design, see wrapper note).
+ */
+export async function listWorktrees(opts = {}) {
+  const { worktrees } = await listWorktreesChecked(opts);
   return worktrees;
 }
 

package/scripts/mcp-server.sh

@@ -8,7 +8,8 @@ set -euo pipefail
 #   - session_config  — reads Session Config from the project instruction file
 #                       (CLAUDE.md, or AGENTS.md alias on Codex CLI — see
 #                       skills/_shared/instruction-file-resolution.md)
-#   - session_metrics — reads last 5 session metrics entries
+#   - session_metrics — reads last 5 REAL session metrics entries (#834:
+#                       abandoned phantom stubs are filtered out first)
 
 # ---------------------------------------------------------------------------
 # Helpers
@@ -75,7 +76,7 @@ handle_tools_list() {
       },
       {
         "name": "session_metrics",
-        "description": "Reads the last 5 session metrics entries from .orchestrator/metrics/sessions.jsonl",
+        "description": "Reads the last 5 REAL session metrics entries from .orchestrator/metrics/sessions.jsonl (abandoned phantom stubs excluded)",
         "inputSchema": {"type": "object", "properties": {}, "required": []}
       }
     ]
@@ -127,9 +128,23 @@ tool_session_config() {
     return
   fi
 
-  # Extract everything from "## Session Config" to the next heading or EOF
-  local config
-  config=$(sed -n '/^## Session Config$/,/^## /{/^## Session Config$/d;/^## /d;p;}' "$instr_file" 2>/dev/null) || true
+  # Extract everything from "## Session Config" to the next heading or EOF.
+  #
+  # The address matches isSessionConfigHeading() in
+  # scripts/lib/config/section-extractor.mjs (the SSOT) exactly: the literal
+  # heading, plus an optional CR so a CRLF checkout is read the same way. Shell
+  # cannot import the JS predicate, so the alignment is by hand and this
+  # comment names the authority. Before #968 this was the only STRICTER site in
+  # the repo — a bare `$` anchors before the CR in a BRE, so on a CRLF checkout
+  # (this plugin ships to Windows-side Codex/Cursor users) the tool reported
+  # "no Session Config section" for a file the runtime parses fine.
+  #
+  # `\r` is not portable inside a BRE (GNU sed only), so the CR is injected as
+  # a literal byte via printf.
+  local cr config sc_re
+  cr=$(printf '\r')
+  sc_re="^## Session Config${cr}\{0,1\}\$"
+  config=$(sed -n "/$sc_re/,/^## /{/$sc_re/d;/^## /d;p;}" "$instr_file" 2>/dev/null) || true
 
   if [[ -z "$config" ]]; then
     respond "$id" "$(text_content "No '## Session Config' section found in $instr_file")"
@@ -156,8 +171,19 @@ tool_session_metrics() {
     return
   fi
 
+  # Filter out phantom `status: 'abandoned'` stubs (#834, session-close-backfill
+  # — 0 waves, seconds of runtime) BEFORE taking the tail, so a recent phantom
+  # cannot displace real session records out of the last-5 window.
+  #
+  # `-R` (raw-input) + `fromjson?` parses each line individually and SKIPS
+  # unparseable ones instead of aborting the whole stream — plain
+  # `jq -c 'select(...)'` aborts at the FIRST malformed line (jq: parse error,
+  # exit 5), which is fatal here because sessions.jsonl is append-only from
+  # multiple writers and a torn write is exactly the case that matters. This
+  # mirrors the per-line try/catch behaviour of the .mjs path
+  # (scripts/lib/session-schema/filters.mjs).
   local entries
-  entries=$(tail -n 5 "$metrics_file" 2>/dev/null) || true
+  entries=$(jq -R -c 'fromjson? | select(.status != "abandoned")' "$metrics_file" 2>/dev/null | tail -n 5) || true
 
   if [[ -z "$entries" ]]; then
     respond "$id" "$(text_content "No metrics found (file is empty)")"

package/scripts/measure-context-overhead.sh

@@ -0,0 +1,151 @@
+#!/usr/bin/env bash
+# measure-context-overhead.sh — measure the REAL instruction overhead of a directory.
+#
+# Why this exists (and why token-audit.sh does not replace it):
+# token-audit.sh measures instruction bytes ON DISK. That is a proxy, and a poor
+# one: it cannot see which rule files the loader classifies as always-on, it
+# cannot see plugin skill descriptions, and it cannot see the tool definitions.
+# This script measures what actually reaches the model, by sending a trivial
+# prompt and reading the token accounting back out of the API response. Every
+# token it reports is overhead, because the prompt itself does no work.
+#
+# Method: `claude -p "<trivial prompt>" --output-format json`, then sum
+#   input_tokens + cache_creation_input_tokens + cache_read_input_tokens.
+# The cache split varies between runs; the SUM is the stable quantity and is
+# what the model is charged for reading.
+#
+# COST WARNING: each measurement is a real API call against the configured
+# model. Measured 2026-07-30 on claude-opus-5[1m]: USD 0.27 (empty directory)
+# to USD 1.06 (this repo). Budget accordingly before running a large matrix.
+#
+# Usage:
+#   bash scripts/measure-context-overhead.sh <dir> [<dir> ...]
+#   bash scripts/measure-context-overhead.sh --ablate <repo-root>
+#
+# --ablate builds throwaway copies of <repo-root>'s instruction surface
+# (CLAUDE.md (or AGENTS.md on Codex CLI) + .claude/rules/) under $TMPDIR and
+# measures the full / reduced / stripped variants, so the cost of each layer can
+# be attributed. It never writes to, and never deletes from, the source repository.
+#
+# Instruction-file resolution follows skills/_shared/instruction-file-resolution.md:
+# CLAUDE.md wins, AGENTS.md is the Codex CLI alias, empty counts as absent, and
+# exactly ONE of the two is ever read. The resolved file is copied into every
+# variant under the name the measuring harness reads (`claude -p` -> CLAUDE.md),
+# so an AGENTS.md-only repo gets its instruction layer measured instead of
+# silently reported as 0 bytes.
+#
+# Baseline recorded 2026-07-30 (claude-opus-5[1m], CLI 2.1.220) for THIS repo,
+# which resolves to CLAUDE.md — a repo resolving to AGENTS.md has its own:
+#   full 110687 tok | no top-3 rules 83138 | no rules 43291 | nothing 42001
+# Reading: the 26 rule files account for 67396 tokens (61% of total); the
+# instruction file itself accounts for 1290. Optimising the instruction file is
+# optimising the wrong file.
+
+set -uo pipefail
+
+PROMPT='Antworte nur mit dem Wort: OK'
+
+measure_one() {
+  local dir="$1" label="$2"
+  if [ ! -d "$dir" ]; then
+    printf '%s\tNO-SUCH-DIR\n' "$label"
+    return
+  fi
+  ( cd "$dir" && claude -p "$PROMPT" --output-format json 2>/dev/null ) | node -e "
+let s = '';
+process.stdin.on('data', (d) => (s += d)).on('end', () => {
+  const label = process.argv[1];
+  try {
+    const j = JSON.parse(s);
+    const u = j.usage || {};
+    const ctx =
+      (u.input_tokens || 0) +
+      (u.cache_creation_input_tokens || 0) +
+      (u.cache_read_input_tokens || 0);
+    process.stdout.write(
+      [label, ctx, u.cache_creation_input_tokens || 0, u.cache_read_input_tokens || 0,
+       u.output_tokens || 0, (j.total_cost_usd || 0).toFixed(4)].join('\t') + '\n',
+    );
+  } catch {
+    process.stdout.write(label + '\tPARSE-ERROR\n');
+  }
+});
+" "$label"
+}
+
+header() { printf 'LABEL\tCONTEXT_TOK\tcache_create\tcache_read\toutput\tUSD\n'; }
+
+# ── --ablate mode ───────────────────────────────────────────────────
+if [ "${1:-}" = "--ablate" ]; then
+  SRC="${2:-$(pwd)}"
+  [ -d "$SRC" ] || { echo "not a directory: $SRC" >&2; exit 1; }
+
+  # Resolve the project-instruction file. CLAUDE.md wins; AGENTS.md is the
+  # Codex CLI alias; an empty file counts as absent; never both.
+  if   [ -s "$SRC/CLAUDE.md" ]; then INSTR_SRC="$SRC/CLAUDE.md"
+  elif [ -s "$SRC/AGENTS.md" ]; then INSTR_SRC="$SRC/AGENTS.md"
+  else
+    echo "no project-instruction file in $SRC (looked for CLAUDE.md, then AGENTS.md)." >&2
+    echo "Refusing to ablate: v2-no-rules and v3-bare differ ONLY by that file, so" >&2
+    echo "the table would render as 'the instruction layer costs 0 tokens' — the" >&2
+    echo "one reading this tool must never produce without evidence." >&2
+    exit 1
+  fi
+  # The measuring harness is `claude -p`, whose instruction file is CLAUDE.md.
+  # Copy the resolved source under THAT name so the content is actually loaded,
+  # whichever of the two aliases the source repo happens to use.
+  INSTR_DEST="CLAUDE.md"
+  echo "instruction file: $INSTR_SRC -> <variant>/$INSTR_DEST" >&2
+  src_rules=("$SRC"/.claude/rules/*.md)
+  [ -e "${src_rules[0]}" ] || \
+    echo "note: no .claude/rules/*.md in $SRC — the rule layers measure as zero." >&2
+
+  BASE="${TMPDIR:-/tmp}/so-ablation-$$"
+  mkdir -p "$BASE"
+  # Copy ONLY the instruction surface. No git, no source, no side effects.
+  build() {
+    local v="$BASE/$1"
+    mkdir -p "$v/.claude/rules"
+    cp "$INSTR_SRC" "$v/$INSTR_DEST" || {
+      echo "failed to copy $INSTR_SRC -> $v/$INSTR_DEST" >&2
+      exit 1
+    }
+    cp "$SRC"/.claude/rules/*.md "$v/.claude/rules/" 2>/dev/null || true
+  }
+  build v0-full
+  build v1-no-top3
+  rm -f "$BASE/v1-no-top3/.claude/rules/loop-and-monitor.md" \
+        "$BASE/v1-no-top3/.claude/rules/parallel-sessions.md" \
+        "$BASE/v1-no-top3/.claude/rules/security.md"
+  build v2-no-rules
+  rm -f "$BASE"/v2-no-rules/.claude/rules/*.md
+  build v3-bare
+  rm -f "$BASE"/v3-bare/.claude/rules/*.md "$BASE/v3-bare/$INSTR_DEST"
+
+  echo "=== instruction bytes on disk ==="
+  for v in v0-full v1-no-top3 v2-no-rules v3-bare; do
+    b=$(cat "$BASE/$v/$INSTR_DEST" "$BASE/$v"/.claude/rules/*.md 2>/dev/null | wc -c | tr -d ' ')
+    n=$(ls "$BASE/$v"/.claude/rules/*.md 2>/dev/null | wc -l | tr -d ' ')
+    printf '  %-14s %8s B  rules=%s\n' "$v" "${b:-0}" "${n:-0}"
+  done
+  echo
+  header
+  for v in v0-full v1-no-top3 v2-no-rules v3-bare; do
+    measure_one "$BASE/$v" "$v"
+  done
+  echo
+  echo "variants left in $BASE (throwaway; remove when done)"
+  exit 0
+fi
+
+# ── direct mode ─────────────────────────────────────────────────────
+if [ "$#" -eq 0 ]; then
+  echo "usage: bash scripts/measure-context-overhead.sh <dir> [<dir> ...]" >&2
+  echo "       bash scripts/measure-context-overhead.sh --ablate <repo-root>" >&2
+  exit 1
+fi
+
+header
+for d in "$@"; do
+  measure_one "$d" "$(basename "$d")"
+done

package/scripts/memory-propose.mjs

@@ -42,7 +42,7 @@
 import { parseArgs } from 'node:util';
 import { readFileSync, existsSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
-import { dirname, join } from 'node:path';
+import { dirname, join, isAbsolute } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { isWaveAgentContext, WAVE_AGENT_ENV_VAR, WAVE_AGENT_ENV_VALUE } from './lib/wave-context.mjs';
@@ -104,7 +104,8 @@ const rawArgv = process.argv.slice(2);
 if (rawArgv.includes('--help') || rawArgv.includes('-h')) {
   process.stdout.write(
     'Usage: SO_WAVE_AGENT=1 memory-propose.mjs --type <type> --subject "..." ' +
-    '--insight "..." --evidence "..." --confidence <0-1> [--dry-run]\n\n' +
+    '--insight "..." --evidence "..." --confidence <0-1> ' +
+    '[--file-paths "a.mjs,b.mjs"] [--dry-run]\n\n' +
     'Environment:\n' +
     '  SO_WAVE_AGENT=1 — REQUIRED. The CLI returns exit 3 (rejected-wrong-context)\n' +
     '                    when this env-var is absent or not exactly "1".\n' +
@@ -113,7 +114,14 @@ if (rawArgv.includes('--help') || rawArgv.includes('-h')) {
     '  --dry-run — Validate the proposal (argv + schema) but do NOT write to\n' +
     '              proposals.jsonl. Bypasses the STATE.md / SO_WAVE_AGENT /\n' +
     '              current-wave context gates so it can be run safely from\n' +
-    '              coordinator context (issue #741.3).\n\n' +
+    '              coordinator context (issue #741.3).\n' +
+    '  --file-paths — Optional. Repo-relative path(s) this learning applies to.\n' +
+    '                 Repeatable AND/OR comma-separated (`--file-paths a.mjs\n' +
+    '                 --file-paths b.mjs,c.mjs`), deduped. Rejects absolute\n' +
+    '                 paths, ".." segments, embedded newlines, entries over 256\n' +
+    '                 chars, and more than 20 entries (exit 4). Without\n' +
+    '                 --file-paths this learning can never become /reconcile-\n' +
+    '                 eligible (issue #900).\n\n' +
     'Exit codes / stdout status:\n' +
     `  0 — ${STATUS.QUEUED} (or ${STATUS.DRY_RUN_OK} under --dry-run)\n` +
     `  1 — ${STATUS.QUOTA_EXCEEDED}\n` +
@@ -133,12 +141,13 @@ try {
   parsedArgs = parseArgs({
     args: rawArgv,
     options: {
-      type:       { type: 'string' },
-      subject:    { type: 'string' },
-      insight:    { type: 'string' },
-      evidence:   { type: 'string' },
-      confidence: { type: 'string' },
-      'dry-run':  { type: 'boolean' },
+      type:          { type: 'string' },
+      subject:       { type: 'string' },
+      insight:       { type: 'string' },
+      evidence:      { type: 'string' },
+      confidence:    { type: 'string' },
+      'dry-run':     { type: 'boolean' },
+      'file-paths':  { type: 'string', multiple: true },
     },
     strict: false, // emit unknown flags as positionals rather than throwing
   });
@@ -173,6 +182,59 @@ if (confidenceRaw !== undefined) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Step 1b — Parse + validate --file-paths (issue #900 C)
+// ---------------------------------------------------------------------------
+//
+// --file-paths is repeatable AND each occurrence may itself be comma-separated
+// (`--file-paths a.mjs --file-paths b.mjs,c.mjs`). Flattened, trimmed,
+// empty-filtered, and deduped BEFORE validation so callers see one clean
+// error per genuinely-bad entry rather than noise from formatting.
+//
+// Validation runs here (Step 1, argv-level) — BEFORE createProposalRecord
+// (Step 6) — so a malformed --file-paths value produces the same exit-4
+// argv-error contract as every other required/optional flag, never a
+// downstream schema-validation surprise.
+
+const FILE_PATHS_MAX_COUNT = 20;
+const FILE_PATH_MAX_CHARS = 256;
+
+const filePathsRaw = parsedArgs.values['file-paths'];
+/** @type {string[]|undefined} */
+let filePaths;
+if (Array.isArray(filePathsRaw) && filePathsRaw.length > 0) {
+  const flattened = filePathsRaw
+    .flatMap((entry) => String(entry).split(','))
+    .map((p) => p.trim())
+    .filter((p) => p.length > 0);
+  filePaths = [...new Set(flattened)];
+}
+
+if (filePaths !== undefined) {
+  if (filePaths.length > FILE_PATHS_MAX_COUNT) {
+    argErrors.push(
+      `--file-paths accepts at most ${FILE_PATHS_MAX_COUNT} paths (got ${filePaths.length})`,
+    );
+  }
+  for (const p of filePaths) {
+    if (isAbsolute(p)) {
+      argErrors.push(`--file-paths must be repo-relative — absolute path rejected: "${p}"`);
+    } else if (p.split(/[\\/]/).includes('..')) {
+      argErrors.push(`--file-paths must not contain ".." path segments: "${p}"`);
+    } else if (/[\r\n]/.test(p)) {
+      argErrors.push(`--file-paths entries must not contain newline characters: "${p}"`);
+    } else if (/[*?[\]{}]/.test(p)) {
+      argErrors.push(
+        `--file-paths must not contain glob metacharacters (* ? [ ] { }) — a literal repo-relative path is required: "${p}"`,
+      );
+    } else if (p.length > FILE_PATH_MAX_CHARS) {
+      argErrors.push(
+        `--file-paths entry exceeds ${FILE_PATH_MAX_CHARS} chars (got ${p.length}): "${p.slice(0, 40)}..."`,
+      );
+    }
+  }
+}
+
 if (argErrors.length > 0) {
   exit({ status: STATUS.ERROR, validation: argErrors }, 4);
 }
@@ -362,6 +424,7 @@ try {
     evidence,
     confidence,
     waveId,
+    filePaths,
   });
 } catch (err) {
   exit({ status: STATUS.ERROR, validation: [`Failed to create proposal record: ${err.message}`] }, 4);