session-orchestrator 3.17.0 → 3.19.0

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);

package/scripts/print-applicable-rules.mjs

@@ -26,7 +26,9 @@
  *   - --json       → `{ count, rules: [{path, alwaysOn, matchedGlobs}] }`
  *
  * Exit codes (per .claude/rules/cli-design.md):
- *   0 — success
+ *   0 — success, INCLUDING EPIPE (the reader closed its end of the pipe
+ *       early — `| head`, `| grep -q`, any truncating consumer — before the
+ *       full payload drained; see the process.stdout 'error' handler below)
  *   1 — user/input error (bad --wave-scope path, malformed wave-scope JSON)
  *   2 — system error (unexpected internal failure)
  * Data → stdout, diagnostics → stderr.
@@ -34,6 +36,11 @@
  * Best-effort by design: a missing rules dir, missing STATE.md, or missing
  * host.json each degrade to "no gating / no rules" rather than failing — the
  * wave-executor caller treats any non-zero exit as "inject nothing, continue".
+ * EPIPE is deliberately EXCLUDED from that "non-zero = inject nothing"
+ * contract: the actual wave-executor caller drains stdout fully
+ * (execFileSync/spawnSync-style capture) and never closes the pipe early, so
+ * EPIPE can only be triggered by an exploratory or truncating reader — never
+ * by the real caller this CLI exists to serve.
  *
  * Related: issue #336 (glob-scoped rules), #694 (rule-activation / FA1),
  *   scripts/lib/rule-loader.mjs (loadApplicableRules),
@@ -49,6 +56,31 @@ import { findProjectRoot } from './lib/common.mjs';
 import { loadApplicableRules } from './lib/rule-loader.mjs';
 import { readHostClass } from './lib/autopilot/telemetry.mjs';
 
+// ---------------------------------------------------------------------------
+// EPIPE hardening (regression follow-up on #876)
+// ---------------------------------------------------------------------------
+//
+// process.stdout.write() to a pipe is ASYNCHRONOUS in Node. When the reader
+// closes its end early — `| head`, `| grep -q`, any truncating consumer —
+// before the writer has finished draining, the deferred write fails and
+// process.stdout emits an 'error' event carrying err.code === 'EPIPE'. Left
+// unhandled, that is an UNCAUGHT EXCEPTION: Node prints a stack trace to
+// stderr ("Unhandled 'error' event") and exits 1 — even though nothing
+// actually failed on the producer side; the reader simply chose to stop
+// consuming. Registered before any stdout write below so it covers every
+// output branch (--help, --json, Markdown, and the empty-match no-op).
+//
+// Exit 0 on EPIPE, matching conventional Unix CLI behaviour (`cat file |
+// head` reports no error to its caller) and restoring the pre-#876 exit
+// contract for this specific case. Any other stdout write error is
+// unexpected and is re-thrown rather than swallowed.
+process.stdout.on('error', (err) => {
+  if (err && err.code === 'EPIPE') {
+    process.exit(0);
+  }
+  throw err;
+});
+
 const HELP = `Usage: node scripts/print-applicable-rules.mjs [options]
 
 Prints the glob-scoped + always-on rule set applicable to the current wave,
@@ -223,6 +255,18 @@ try {
   fail(`Rule loading failed: ${err.message}`, 2);
 }
 
+// NOTE (#876): deliberately no `process.exit(0)` after these stdout writes.
+// process.stdout.write() to a pipe is ASYNCHRONOUS in Node — an explicit
+// process.exit() terminates the process before the kernel pipe buffer (64KiB
+// on macOS) has been fully drained, silently truncating any payload beyond
+// that threshold with exit code still 0. Letting the script fall off the end
+// lets Node's event loop wait for the pending write to flush before the
+// process exits naturally (default exit code 0) — the fix generalizes to any
+// payload size, not just today's measured ~105KB. The three branches below
+// are mutually exclusive (if/else-if/else) so only one ever writes to stdout.
+// When the reader closes early instead of draining to completion, the write
+// fails with EPIPE — handled asynchronously by the process.stdout 'error'
+// listener registered near the top of this file, not by anything here.
 if (opts.json) {
   const out = {
     count: rules.length,
@@ -233,15 +277,10 @@ if (opts.json) {
     })),
   };
   process.stdout.write(JSON.stringify(out, null, 2) + '\n');
-  process.exit(0);
-}
-
-// Markdown block. Empty match set → print nothing (caller injects nothing).
-if (rules.length === 0) {
-  process.exit(0);
+} else if (rules.length === 0) {
+  // Empty match set → print nothing (caller injects nothing).
+} else {
+  const header = '## Applicable Rules (scoped to this wave)';
+  const body = rules.map((r) => r.content.trimEnd()).join('\n\n---\n\n');
+  process.stdout.write(`${header}\n\n${body}\n`);
 }
-
-const header = '## Applicable Rules (scoped to this wave)';
-const body = rules.map((r) => r.content.trimEnd()).join('\n\n---\n\n');
-process.stdout.write(`${header}\n\n${body}\n`);
-process.exit(0);