session-orchestrator 5.2.0 → 5.4.0

package/scripts/lib/instruction-budget-guard.mjs

@@ -47,6 +47,16 @@
  * tier-gate conditionals `applyGates` already implements (the `context`
  * param below is the exact mechanism rule-loader exposes for this).
  *
+ * #1449: that membership now matches what Claude Code actually loads. The
+ * loader used to skip a leading provenance comment before `---`, so a rule
+ * Claude Code loads always-on (it reads frontmatter only from line 1) counted
+ * here as path-scoped, and every consumer's always-on total was short by the
+ * vendored rules carrying that header. Such a file now counts as always-on —
+ * its displaced frontmatter as body bytes, since that is how Claude Code
+ * delivers it — and is listed in `defects` and on its own banner line. The
+ * list is report-only: it is not an `overBudget` term, so a defect never turns
+ * a budget verdict red.
+ *
  * Cross-references:
  * - "2026-06-20 instruction-budget audit" (#668 / #687; archived in the private Meta-Vault)
  * - scripts/lib/rule-loader.mjs (always-on classification + tier-gate SSOT)
@@ -78,7 +88,12 @@
 
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { basename, join } from 'node:path';
-import { loadApplicableRules, parseGlobsFrontmatter } from './rule-loader.mjs';
+import { scanEventsBackwards } from './events.mjs';
+import {
+  FRONTMATTER_NOT_AT_TOP,
+  loadApplicableRules,
+  parseGlobsFrontmatter,
+} from './rule-loader.mjs';
 
 /** Default directive ceiling (operator-chosen growth ratchet just above the ~457 baseline). */
 export const DEFAULT_CEILING = 480;
@@ -443,6 +458,35 @@ export const DEFAULT_GENERATED_BYTE_CEILING = 95000;
  */
 export const DEFAULT_PATH_SCOPED_BYTE_CEILING = 124000;
 
+/**
+ * Share of {@link DEFAULT_PATH_SCOPED_BYTE_CEILING} at which the banner warns
+ * BEFORE the writer refuses (#1419).
+ *
+ * The defect #1419 records is not the ceiling but its TIMING: it becomes
+ * visible only inside `writeApprovedRules`, after the operator has already
+ * decided. Measured on that case (2026-09-20, /reconcile run): 117,973 of
+ * 124,000 B = 95.1 % — ~6 kB of headroom holding back `capped: 91`
+ * candidates, and `overPathScopedBudget` (a HARD `bytes > ceiling` test) did
+ * not fire, so nothing warned.
+ *
+ * 90 % is the distance of ~4 materialised rules: 10 % of 124,000 B = 12,400 B
+ * against the ~1.5 kB a generated rule file occupied on the #1419 tree — i.e.
+ * roughly four more accepted learnings until the hard break. A fixed fraction,
+ * deliberately not a per-repo calibration: it cannot know how large THIS
+ * repo's next rule is, and a second calibrated number would need its own
+ * falsification record.
+ *
+ * BV-004 ceiling + revisit trigger (HR-105): measure this line's firing rate
+ * after ~20 sessions from the probe records in
+ * `.orchestrator/metrics/events.jsonl`
+ * (`jq -c 'select(.event=="orchestrator.probes.completed")
+ * | .probes[] | select(.id=="instruction-budget")' …` — count `ran-warn`
+ * against the record total).
+ * Above ~10 % the instrument is RE-AIMED per HR-101 — neither lowered nor
+ * silenced; below it, leave it alone.
+ */
+export const PATH_SCOPED_NEAR_THRESHOLD = 0.9;
+
 /**
  * Read the `instruction-budget:` nested block from the `## Session Config`
  * section of CLAUDE.md (or AGENTS.md) at `repoRoot`. Synchronous + never throws.
@@ -1025,12 +1069,18 @@ function measureRuleCorpora(rulesDir) {
  *   bySurface: { coordinator: number, wave: number, always: number,
  *               generated: {bytes: number, files: number},
  *               pathScoped: {bytes: number, files: number} },
+ *   defects: string[],
  * }}
- *   perFile is sorted DESC by count. On missing/unreadable dir →
+ *   perFile is sorted DESC by count. `defects` (#1449) lists, sorted by name,
+ *   the rule files whose frontmatter does not start on line 1 — Claude Code
+ *   ignores it, so they load always-on and are counted as such. It is
+ *   independent of `context` (such a file has no tier to gate on) and never
+ *   feeds `overBudget`. On missing/unreadable dir →
  *   { totalDirectives: 0, totalBytes: 0, perFile: [], ceiling, byteCeiling,
  *     overDirectiveBudget: false, overByteBudget: false, overBudget: false,
  *     severity: 'ok', bySurface: { coordinator: 0, wave: 0, always: 0,
- *     generated: {bytes:0,files:0}, pathScoped: {bytes:0,files:0} } }.
+ *     generated: {bytes:0,files:0}, pathScoped: {bytes:0,files:0} },
+ *     defects: [] }.
  *
  *   #931a verdict rule — `overBudget` is the OR of the two axes
  *   (`overDirectiveBudget || overByteBudget`), NOT a per-axis severity split:
@@ -1135,6 +1185,7 @@ export function computeInstructionBudget(opts = {}) {
       generated: { bytes: 0, files: 0 },
       pathScoped: { bytes: 0, files: 0 },
     },
+    defects: [],
   };
 
   let allEntries;
@@ -1226,6 +1277,13 @@ export function computeInstructionBudget(opts = {}) {
   const overPathScopedBudget = bySurface.pathScoped.bytes > pathScopedByteCeiling;
   const overBudget = overDirectiveBudget || overByteBudget || overGeneratedBudget || overPathScopedBudget;
 
+  // #1449: read off the untiered list — a defective file carries no meta, so
+  // no tier gate drops it and `alwaysOnAll` holds every one of them.
+  const defects = alwaysOnAll
+    .filter((e) => e.defect === FRONTMATTER_NOT_AT_TOP)
+    .map((e) => basename(e.path))
+    .sort((a, b) => a.localeCompare(b));
+
   return {
     totalDirectives,
     totalBytes,
@@ -1241,9 +1299,102 @@ export function computeInstructionBudget(opts = {}) {
     overBudget,
     severity: overBudget ? 'warn' : 'ok',
     bySurface,
+    defects,
   };
 }
 
+/** Ledger event the backlog number below is read from (`reconcile/engine.mjs`). */
+const RECONCILE_EVENT = 'orchestrator.reconcile.completed';
+
+/**
+ * Wall-clock budget for the backwards ledger walk. Deliberately small: this
+ * runs inside a session-start probe whose own budget is 2 s, and the number it
+ * fetches is DECORATION on a line that is already actionable without it.
+ */
+const RECONCILE_SCAN_BUDGET_MS = 150;
+
+/**
+ * `capped` from the most recent `orchestrator.reconcile.completed` record —
+ * how many rule-eligible learnings the last /reconcile run held back.
+ *
+ * Three-state on purpose (`feedback_missing_measurement_looks_like_zero`):
+ * `null` means NOT MEASURED (no ledger, no such record, unreadable source, or
+ * the walk ran out of budget), which the caller must render as ABSENCE — never
+ * as `0`, which is a measured "nothing waiting".
+ *
+ * @param {string|undefined} repoRoot
+ * @returns {number|null}
+ */
+function readLastReconcileCapped(repoRoot) {
+  if (typeof repoRoot !== 'string' || repoRoot === '') return null;
+  const filePath = join(repoRoot, '.orchestrator', 'metrics', 'events.jsonl');
+  let capped = null;
+  let scan;
+  try {
+    scan = scanEventsBackwards({
+      filePath,
+      budgetMs: RECONCILE_SCAN_BUDGET_MS,
+      // Cheap raw-line pre-filter before JSON.parse — same reason as
+      // `maintenance-due-banner.mjs`: parsing every line of a multi-MB ledger
+      // to answer one question is the cost this option exists to avoid.
+      filter: RECONCILE_EVENT,
+      onRecord: (rec) => {
+        if (rec?.event !== RECONCILE_EVENT) return false;
+        capped = Number.isFinite(rec.capped) ? rec.capped : null;
+        return true; // newest record wins; stop the walk
+      },
+    });
+  } catch {
+    return null; // never throw out of the banner wrapper
+  }
+  // A walk that did not finish has not proven anything about the backlog.
+  if (scan.truncated || scan.unreadable.length > 0) return null;
+  return capped;
+}
+
+/**
+ * The #1419 early-warning line: the path-scoped ceiling is close, not broken.
+ *
+ * Reports the numbers the RULE judged (HR-106) — the same `pathScoped.bytes`
+ * and ceiling `writeApprovedRules` will compare later — plus, when the ledger
+ * carries one, how many learnings the last /reconcile run already held back.
+ * The percentage is formatted locale-free so the same corpus renders the same
+ * string on every host.
+ *
+ * @param {ReturnType<typeof computeInstructionBudget>} budget
+ * @param {string|undefined} repoRoot
+ * @returns {string}
+ */
+function formatNearPathScopedLine(budget, repoRoot) {
+  const used = budget.bySurface.pathScoped.bytes;
+  const ceiling = budget.pathScopedByteCeiling;
+  const pct = ((used / ceiling) * 100).toFixed(1);
+  const capped = readLastReconcileCapped(repoRoot);
+  // Only a POSITIVE measured backlog is worth a clause; `0` and `null` both
+  // add nothing the operator can act on, and printing `0` for `null` would be
+  // the false-negative this helper's three-state contract exists to prevent.
+  const backlog = typeof capped === 'number' && capped > 0 ? ` — ${capped} Learnings warten` : '';
+  return (
+    `path-scoped Regel-Decke zu ${pct} % belegt (${used}/${ceiling} B)${backlog} — ` +
+    '/reconcile wird Learnings zurueckhalten'
+  );
+}
+
+/**
+ * The #1449 defect line: rule files whose frontmatter Claude Code never reads.
+ * Names every file — the fix is per file (move the text above `---` below the
+ * closing fence), so a count alone would send the operator hunting.
+ *
+ * @param {string[]} defects - basenames from `computeInstructionBudget().defects`
+ * @returns {string}
+ */
+function formatFrontmatterDefectLine(defects) {
+  return (
+    `⚠ ${defects.length} rule(s) carry frontmatter that Claude Code ignores ` +
+    `(text before the opening ---): ${defects.join(', ')} — they load always-on.`
+  );
+}
+
 /**
  * Banner wrapper — session-start Phase 4 convention.
  *
@@ -1260,7 +1411,9 @@ export function computeInstructionBudget(opts = {}) {
  *
  * The message names WHICH axis breached (#931a) — a banner that only said
  * "over budget" would leave the operator guessing whether to prune bullets or
- * prose. It stays at three lines because it renders at every session start.
+ * prose. It stays short because it renders at every session start: the breach
+ * block is three lines, plus one line per extra finding (near-threshold,
+ * frontmatter defect).
  *
  * @param {object} [opts]  forwarded to computeInstructionBudget.
  * @param {string} [opts.repoRoot] project root for the config read.
@@ -1268,10 +1421,17 @@ export function computeInstructionBudget(opts = {}) {
  * @param {number} [opts.byteCeiling] explicit byte-ceiling override (wins over config).
  * @param {number} [opts.pathScopedByteCeiling] explicit path-scoped-ceiling override.
  * @returns {{ severity: 'warn', message: string } | null}
- *   null when disabled / off / every axis at-or-under its ceiling OR on any
- *   read failure. Since #1316 each of the four axes — directives, bytes,
+ *   null when disabled / off / every axis comfortably under its ceiling OR on
+ *   any read failure. Since #1316 each of the four axes — directives, bytes,
  *   generated, path-scoped — raises the banner on its own (see
- *   DEFAULT_PATH_SCOPED_BYTE_CEILING).
+ *   DEFAULT_PATH_SCOPED_BYTE_CEILING). Since #1419 the path-scoped axis ALSO
+ *   raises it at {@link PATH_SCOPED_NEAR_THRESHOLD} of its ceiling, before the
+ *   breach: that band used to be silent, and the ceiling then surfaced only
+ *   inside `writeApprovedRules` — after the operator had approved rules it
+ *   refused to write. Since #1449 a rule whose frontmatter is not on line 1
+ *   raises it too (one line naming the files), whether or not any axis is
+ *   close. The RETURN SHAPE is unchanged (`{severity:'warn', message}` |
+ *   null), so `session-start-probes.mjs` needs no new vocabulary.
  */
 export function checkInstructionBudget(opts = {}) {
   let cfg;
@@ -1331,7 +1491,42 @@ export function checkInstructionBudget(opts = {}) {
     return null; // never throw out of the banner wrapper
   }
 
-  if (!budget || !budget.overBudget) return null;
+  if (!budget) return null;
+
+  // #1419 near-threshold stage. Strictly BELOW the hard test (a breach is
+  // reported as a breach, never twice), and computed before the early return
+  // so a corpus at 90–100 % of the path-scoped ceiling stops being silent —
+  // that silence is the defect: the ceiling used to surface only inside
+  // `writeApprovedRules`, after the operator had already approved rules.
+  const nearPathScoped =
+    !budget.overPathScopedBudget &&
+    budget.pathScopedByteCeiling > 0 &&
+    budget.bySurface.pathScoped.bytes >= budget.pathScopedByteCeiling * PATH_SCOPED_NEAR_THRESHOLD;
+
+  // #1449 — reported on its own line, never folded into `overBudget`.
+  const defectLine =
+    budget.defects.length > 0 ? formatFrontmatterDefectLine(budget.defects) : null;
+
+  if (!budget.overBudget && !nearPathScoped && !defectLine) return null;
+
+  const nearLine = nearPathScoped ? formatNearPathScopedLine(budget, opts.repoRoot) : null;
+
+  // Nothing breached: one block per finding — the near-threshold line carries
+  // the same remedy as the breach clause below (consolidate — never raise).
+  if (!budget.overBudget) {
+    return {
+      severity: 'warn',
+      message: [
+        ...(nearLine
+          ? [
+              `⚠ ${nearLine}.`,
+              '  Consolidate generated rules per docs/rule-authoring.md § Consolidated rules; never raise the ceiling.',
+            ]
+          : []),
+        ...(defectLine ? [defectLine] : []),
+      ].join('\n'),
+    };
+  }
 
   // Name only the breached axes — listing a healthy axis would pad the line
   // without telling the operator anything they must act on.
@@ -1377,10 +1572,15 @@ export function checkInstructionBudget(opts = {}) {
     .map((f) => `${f.file} (${f.count} dir, ${f.bytes} B)`)
     .join(', ');
 
+  // The near-threshold line rides ALONGSIDE the breach line rather than inside
+  // `axes`: the path-scoped axis is not over, and folding a healthy-but-close
+  // axis into a sentence that says "over" would misreport which ceiling broke.
   const message = [
     `⚠ Instruction budget over — ${axes.join(' · ')} across ${budget.perFile.length} always-on rules.`,
+    ...(nearLine ? [`  ${nearLine}.`] : []),
     `  Top files: ${top}`,
     '  See the instruction-budget audit (#687; archived in the private Meta-Vault) for the prune/demote list.',
+    ...(defectLine ? [defectLine] : []),
   ].join('\n');
 
   return { severity: 'warn', message };

package/scripts/lib/io.mjs

@@ -711,12 +711,33 @@ export function emitRewrite(updatedInput) {
     process.exit(0);
   };
 
-  if (updatedInput === null || typeof updatedInput !== 'object' || Array.isArray(updatedInput)) {
-    // `updatedInput` is a MAP in the bundle schema, so an array is as wrong as a
-    // string — and an array would serialize into a shape the harness cannot use.
-    bail(
-      `was called with ${Array.isArray(updatedInput) ? 'an array' : String(updatedInput === null ? 'null' : typeof updatedInput)}, not a tool-input object`,
-    );
+  // `updatedInput` is a MAP in the bundle schema, so an array is as wrong as a
+  // string — and an array would serialize into a shape the harness cannot use.
+  //
+  // PLAIN object only, and `typeof === 'object'` is not that test. An object
+  // WRAPPER passes it and then serializes to something else entirely:
+  // `new Date()` and `new String('x')` become JSON STRINGS (their `toJSON` /
+  // primitive form), `new Map([...])` becomes `{}` — which looks valid and,
+  // per the doc above, deletes every field of the tool input. Each of the three
+  // reaches the harness as a schema-invalid `updatedInput`, and the bundle
+  // turns that into `behavior: "deny"`: on the `AskUserQuestion` path the
+  // operator's question is destroyed to save a rewrite. A prototype of
+  // `Object.prototype` (a literal) or `null` (`Object.create(null)`) is the
+  // whole admissible set; everything else takes the same no-op-plus-stderr
+  // contract as `null`, an array or a string.
+  const proto =
+    updatedInput !== null && typeof updatedInput === 'object'
+      ? Object.getPrototypeOf(updatedInput)
+      : undefined;
+  const isPlainObject =
+    !Array.isArray(updatedInput) && (proto === Object.prototype || proto === null);
+  if (!isPlainObject) {
+    let described;
+    if (Array.isArray(updatedInput)) described = 'an array';
+    else if (updatedInput === null) described = 'null';
+    else if (typeof updatedInput !== 'object') described = String(typeof updatedInput);
+    else described = `a non-plain object (${proto?.constructor?.name ?? 'unknown prototype'})`;
+    bail(`was called with ${described}, not a tool-input object`);
   }
 
   let line;
@@ -731,11 +752,24 @@ export function emitRewrite(updatedInput) {
       },
     });
   } catch (err) {
-    // A cycle or a BigInt in the caller's object. JSON.stringify can also return
-    // undefined (a toJSON that yields undefined) — caught by the same guard.
+    // A cycle or a BigInt in the caller's object.
     bail(`could not serialize the tool input (${err?.message ?? String(err)})`);
   }
 
+  // `JSON.stringify` returns `undefined` only for a TOP-LEVEL value it drops —
+  // and `updatedInput` sits NESTED inside the envelope literal above, so at this
+  // call site it never can. Measured 2026-09-18 with
+  // `{ toJSON() { return undefined; } }` as `updatedInput`: stdout is
+  // `{"hookSpecificOutput":{"hookEventName":"PreToolUse"}}` (53 bytes) — the
+  // property is silently OMITTED, not undefined, and the guard below does not
+  // fire. That degraded state is the safe one (an envelope without
+  // `updatedInput` carries no rewrite, so the tool call runs with its original
+  // input — exactly what `bail` produces), which is why it is documented rather
+  // than checked: re-parsing up to REWRITE_ENVELOPE_MAX_BYTES on every rewrite
+  // to recover one stderr line is a poor trade. The guard stays because it is
+  // the envelope SHAPE that makes the case unreachable: hoist `updatedInput` to
+  // the top level, or hand the literal to a helper that returns it, and
+  // `undefined` becomes reachable again.
   if (typeof line !== 'string') {
     bail('serialized the tool input to undefined (a toJSON returning undefined?)');
   }