session-orchestrator 5.1.0 → 5.3.0

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

@@ -78,6 +78,7 @@
 
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { basename, join } from 'node:path';
+import { scanEventsBackwards } from './events.mjs';
 import { loadApplicableRules, parseGlobsFrontmatter } from './rule-loader.mjs';
 
 /** Default directive ceiling (operator-chosen growth ratchet just above the ~457 baseline). */
@@ -255,17 +256,17 @@ export const DEFAULT_BYTE_CEILING = 121000;
  *      → rulesDir extracted from `c73c094f`: { bytes: 76114, files: 8 }
  *      → rulesDir extracted from `e4674109`: { bytes: 89763, files: 43 }
  *
- * The CONCLUSION stands, on a wider base: firing rate is 0 of 3, not 0 of 2 —
- * the guard would not have fired at any of the three states this repo has
- * recorded. What does NOT stand is the headroom claim it rested on. The live
- * corpus is **2,427 B** below the historical peak, not 13,649 B: a single
- * /reconcile wave of the size this one just absorbed puts the generated corpus
- * back at its worst recorded state, and the ceiling still would not notice.
- * "Decorative" is therefore an understatement of the gap, not an overstatement
- * — which strengthens the case for the operator decision this block defers,
- * and changes none of its terms. Still tracked rather than silently patched:
- * raising OR lowering a threshold inside a population fix is exactly the
- * conflation this comment exists to end.
+ * HISTORY as of 2026-09-16 — every number in this paragraph described the
+ * 124,000 ceiling, which no longer exists on this axis. It read, correctly for
+ * 2026-09-11: firing rate 0 of 3, not 0 of 2; the generated corpus then sat
+ * **2,427 B** below the peak known at that time (87,336 of 89,763 B), not
+ * 13,649 B, so one /reconcile wave of the size that session absorbed would have
+ * restored its worst recorded state with the ceiling still silent. Superseded
+ * on BOTH terms by the RE-CALIBRATED block below (ceiling 95,000, true peak
+ * 99,774 B, live distance to the peak 29,833 B measured 2026-09-16). Kept
+ * because it records the rule that produced the eventual fix: raising OR
+ * lowering a threshold inside a population fix is exactly the conflation this
+ * comment exists to end.
  *
  * FIRING-RATE AUDIT — widened from 3 states to 89 (#1308, 2026-09-11T17:26Z,
  * clean tree @ `4a49adc6`). HR-105 forbids a rule nothing records; "0 of 3"
@@ -273,35 +274,63 @@ export const DEFAULT_BYTE_CEILING = 121000;
  * guard was replayed over EVERY commit that touched `.claude/rules/`:
  * `git log --format=%h -- .claude/rules/` → 89 commits, each extracted with
  * `git archive <sha> .claude/rules | tar -x -C <tmp>` and fed to
- * `computeInstructionBudget({rulesDir})`:
+ * `computeInstructionBudget({rulesDir})`. Firing rates only — the headroom
+ * annotations this table used to carry are deliberately gone, because an
+ * absolute headroom rots between two edits of the corpus; read the live one
+ * from the axis itself (command in the RE-MEASURED block below):
  *
  *   directive axis  (480)      → fires  4/89 =  4.5 %   rare, healthy
- *   byte axis       (121,000)  → fires  0/89 =  0.0 %   live: 586 B headroom
- *   generated axis  (124,000)  → fires  0/89 =  0.0 %   peak ever 89,763 B
- *   pathScoped axis (124,000)  → fires  4/89 =  4.5 %   falsifiable
- *
- * "Silently broken" is now RULED OUT: `pathScoped` runs the same code path off
- * the same walk and fires on 4 of the same 89 states. What remains is the
- * calibration gap — the all-time peak of this population is 89,763 B, i.e.
- * 72.4 % of the ceiling, so no state this repo has ever recorded could have
- * breached it, and none plausibly will before the corpus grows ~38 %.
- * A falsifiable ceiling for this axis would sit just above the recorded peak
- * (≈ 92,000 B, peak + 2.5 %); this module does NOT move it, because
- * `.claude/rules/development.md` § Guard & Threshold Design makes re-aiming a
- * threshold an operator decision, separate from measuring it. Revisit trigger:
- * re-run the 89-state replay above whenever the generated corpus passes
- * 92,000 B, or when this axis first fires (then it is calibrated, not
- * decorative).
- *
- * That trigger FIRED: the generated corpus stood at 99,774 B at `c16fb518`
- * (2026-09-12), past 92,000. It was answered by consolidation rather than by
- * a replay of this axis — the 8 generated files were merged down (prose only,
- * provenance unchanged) to 75,130 B / 8 files on the 2026-09-12 working tree
- * (#1316), back under the 92,000 mark. This ceiling is unchanged and the
- * 89-state replay of THIS axis was not re-run; the trigger stays armed for the
- * next pass of 92,000 B.
+ *   byte axis       (121,000)  → fires  0/89 =  0.0 %
+ *   generated axis  (124,000)  → fires  0/91 =  0.0 %   → superseded, see below
+ *   pathScoped axis (124,000)  → fires  5/91 =  5.5 %   → calibrated
+ *
+ * RE-CALIBRATED 2026-09-16 (#1308). The replay was re-run over the FULL
+ * recorded history of this directory, not the 89-state subset:
+ *
+ *   `git log --format=%h -- ./.claude/rules/` → 91 states; each materialized
+ *   with `git archive <sha> .claude/rules | tar -x -C <tmp>` and fed to
+ *   `computeInstructionBudget({ rulesDir })`.
+ *
+ * True peak of the generated axis: **99,774 B @ `2ae08fe0`** — which CORRECTS
+ * the "peak ever 89,763 B" this docblock carried until now (that number came
+ * from a single replayed commit, not from the population). Median state:
+ * 4,802 B. Firing table over the same 91 states:
+ *
+ *   124,000            → 0/91 = 0.0 %   (the standing, unfalsifiable value)
+ *   102,268 (peak+2.5%)→ 0/91 = 0.0 %   (a ceiling above the peak never fires)
+ *    95,000            → 1/91 = 1.1 %   ← chosen
+ *    88,000            → 3/91 = 3.3 %
+ *    80,000            → 5/91 = 5.5 %
+ *
+ * Why 95,000: it FIRES on recorded history (HR-105 — a rule you cannot falsify
+ * is not a rule), at 1.1 % it sits in HR-101's rare band (a class above ~10 %
+ * is a broken instrument), and it stays silent on the corpus it lands on, so it
+ * does not go red before the #1367 consolidation has been committed. "Peak +
+ * 2.5 %" is REJECTED here for the reason the old text recommended it: above the
+ * peak, the axis is decorative by construction.
+ *
+ * RE-MEASURED 2026-09-16 @ `ca214376`, after the #1367 consolidation landed in
+ * the working tree (the state this ceiling was calibrated for is the state it
+ * now judges):
+ *
+ *   node --input-type=module -e "const m = await import('./scripts/lib/instruction-budget-guard.mjs'); \
+ *     console.log(JSON.stringify(m.computeInstructionBudget({ repoRoot: process.cwd() }).bySurface))"
+ *   → generated  { bytes: 69941, files: 7 }   ×1.36 under 95,000
+ *     pathScoped { bytes: 109932, files: 10 }
+ *
+ * Read the headroom off that command, never off a sentence in this block: the
+ * two numbers a verdict needs are the AXIS and its CEILING, and the distance
+ * between them changes with every rule edit. For the record at that SHA the
+ * generated axis sat 25,059 B under its ceiling and 29,833 B under the 99,774 B
+ * peak — i.e. one /reconcile wave the size of the largest recorded one would
+ * still not reach the peak, but a repeat of the growth that produced it would
+ * cross 95,000 first. That is the intended, rare signal: a cue to consolidate.
+ *
+ * BV-004 revisit trigger: re-run the 91-state replay when the generated corpus
+ * passes 90,000 B, or on this ceiling's FIRST fire — at which point it is
+ * calibrated by a real event rather than by a replay.
  */
-export const DEFAULT_GENERATED_BYTE_CEILING = 124000;
+export const DEFAULT_GENERATED_BYTE_CEILING = 95000;
 
 /**
  * Default byte ceiling for the PATH-SCOPED rule surface — the fourth axis,
@@ -353,11 +382,14 @@ export const DEFAULT_GENERATED_BYTE_CEILING = 124000;
  *   working tree (2026-09-11):       134,969 B / 11 files → FIRES
  *
  * Firing rate 2 of 3, falsifiable in both directions — the condition
- * {@link DEFAULT_GENERATED_BYTE_CEILING} does NOT currently meet (0 of 3).
- * Confirmed on a wider base (#1308, 2026-09-11T17:26Z @ `4a49adc6`): replayed
- * over all 89 commits that touched `.claude/rules/`, this axis fires 4/89
- * (4.5 %) against the generated axis's 0/89 — inside HR-101's rare band, and
- * falsifiable, which is exactly the property the sibling ceiling lacks.
+ * {@link DEFAULT_GENERATED_BYTE_CEILING} did not meet while it stood at
+ * 124,000 (0 of 3). Confirmed on a wider base (#1308, 2026-09-11T17:26Z @
+ * `4a49adc6`): replayed over all 89 commits that touched `.claude/rules/`, this
+ * axis fires 4/89 (4.5 %) — inside HR-101's rare band, and falsifiable.
+ * SUPERSEDED as a CONTRAST 2026-09-16: the sibling ceiling was re-calibrated to
+ * 95,000 in the same #1308 replay and now fires 1/91 (1.1 %) on recorded
+ * history, so "the property the sibling ceiling lacks" is no longer true of it —
+ * both axes are falsifiable, and this one is simply the looser of the two.
  * This is also why it is not re-derived upward off the live number: a ceiling
  * placed above 134,969 would be silent on all three states, i.e. the same
  * unfalsifiable shape, obtained by the threshold-patch move
@@ -385,9 +417,14 @@ export const DEFAULT_GENERATED_BYTE_CEILING = 124000;
  * the threshold-patch move `development.md` § Guard & Threshold Design
  * forbids.
  *
- * Headroom is 1,237 B. The next `/reconcile` rule (~2.5 KB written
- * standalone) trips this axis unless it is absorbed into a thematic file in
- * the SAME write step — an obligation written in the /reconcile-overshoot
+ * Headroom moves with every rule edit, so it is measured, never quoted from
+ * here: `computeInstructionBudget({ repoRoot }).bySurface.pathScoped` against
+ * this constant. At 2026-09-16 @ `ca214376` that was 109,932 B / 10 files —
+ * 14,068 B under the ceiling, after the #1367 consolidation; on 2026-09-12 it
+ * was 1,237 B, which is how narrow this axis can get. The next `/reconcile`
+ * rule (~2.5 KB written standalone) trips it from a margin like that one
+ * unless it is absorbed into a thematic file in the SAME write step — an
+ * obligation written in the /reconcile-overshoot
  * learning of `.claude/rules/measurement-discipline.md` and checked by the
  * reconcile writer's budget pre-flight (`scripts/lib/reconcile/writer.mjs`).
  * A breach sets `overBudget` AND turns `tests/rules/receiving-review.test.mjs`
@@ -407,6 +444,35 @@ export const DEFAULT_GENERATED_BYTE_CEILING = 124000;
  */
 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.
@@ -749,7 +815,7 @@ function sumBytes(entries) {
  * @param {Record<string, unknown>} meta
  * @returns {boolean}
  */
-function isMachineGeneratedRule(meta) {
+export function isMachineGeneratedRule(meta) {
   if (!meta || typeof meta !== 'object') return false;
   return (
     meta['auto-generated'] === true ||
@@ -758,6 +824,110 @@ function isMachineGeneratedRule(meta) {
   );
 }
 
+/** One day in milliseconds — local to this module, as in every other lib here. */
+const MS_PER_DAY = 86_400_000;
+
+/**
+ * Whole days from `now` until this rule's `expires-at`, or `null` when the rule
+ * declares no expiry or an unparseable one.
+ *
+ * Negative ⇒ already expired. The comparison basis is deliberately the SAME one
+ * `rule-loader.mjs` `applyGates` uses — `Date.parse(expires-at) < now`, i.e. a
+ * bare `YYYY-MM-DD` is UTC midnight — so "expired" here means exactly "the
+ * loader already filters it out of every wave's rule set", never a second
+ * definition of the same word. `Math.floor` therefore returns `-1` for a rule
+ * that expired at midnight today: past, but by less than a day.
+ *
+ * An unparseable date returns `null` (fail-OPEN, matching the loader, which
+ * warns and ignores the expiry rather than excluding the file) — the malformed
+ * value is a separate finding, not an expiry verdict.
+ *
+ * @param {{ meta?: Record<string, unknown>, now?: Date|number|string }} [opts]
+ * @returns {number|null}
+ */
+export function daysUntilGeneratedRuleExpiry(opts = {}) {
+  const meta = opts.meta;
+  if (!meta || typeof meta !== 'object') return null;
+  if (!Object.prototype.hasOwnProperty.call(meta, 'expires-at')) return null;
+  const expiresAt = Date.parse(String(meta['expires-at']));
+  if (!Number.isFinite(expiresAt)) return null;
+
+  const raw = opts.now;
+  let now;
+  if (raw instanceof Date) now = raw.getTime();
+  else if (typeof raw === 'number' && Number.isFinite(raw)) now = raw;
+  else if (typeof raw === 'string' && Number.isFinite(Date.parse(raw))) now = Date.parse(raw);
+  else now = Date.now();
+
+  return Math.floor((expiresAt - now) / MS_PER_DAY);
+}
+
+/**
+ * Is this generated rule's `expires-at` already in the past?
+ *
+ * The defect it names (#1372): `rule-loader.mjs` filters an expired rule out at
+ * READ time, but nothing DELETES it — so the file keeps being counted by every
+ * byte ceiling above and keeps being loaded verbatim by Claude Code, which has
+ * no notion of `expires-at`.
+ *
+ * @param {{ meta?: Record<string, unknown>, now?: Date|number|string }} [opts]
+ * @returns {boolean}
+ */
+export function isExpiredGeneratedRule(opts = {}) {
+  const days = daysUntilGeneratedRuleExpiry(opts);
+  return days !== null && days < 0;
+}
+
+/**
+ * Enumerate the machine-generated rule files in `rulesDir`.
+ *
+ * Same population, same filter and same frontmatter parser as
+ * {@link measureRuleCorpora}'s `generated` surface — that is the point of
+ * exporting it: a consumer that needs the FILES rather than the BYTES (the
+ * expiry test, the session-start maintenance probe) must not mirror the
+ * predicate, because a mirror agrees only until one side is edited.
+ *
+ * Three-state, like every reader in the banner family: `ok: false` means the
+ * directory exists but could not be enumerated, which a caller must record as
+ * "undeterminable" and never as "no generated rules". A MISSING directory is
+ * `ok: true` with an empty list — a repo without `.claude/rules/` genuinely has
+ * none.
+ *
+ * @param {{ rulesDir?: string, repoRoot?: string }} [opts]
+ * @returns {{ ok: boolean, rules: Array<{ file: string, meta: Record<string, unknown>, expiresAt: string|null }> }}
+ */
+export function listMachineGeneratedRules(opts = {}) {
+  const dir =
+    typeof opts.rulesDir === 'string' && opts.rulesDir.length > 0
+      ? opts.rulesDir
+      : join(opts.repoRoot ?? process.cwd(), '.claude', 'rules');
+
+  /** @type {Array<{ file: string, meta: Record<string, unknown>, expiresAt: string|null }>} */
+  const rules = [];
+  let names;
+  try {
+    names = readdirSync(dir);
+  } catch (err) {
+    // ENOENT is an answer ("no generated rules"); anything else is not knowing.
+    return { ok: err?.code === 'ENOENT', rules };
+  }
+
+  for (const file of names) {
+    if (!file.endsWith('.md')) continue;
+    let meta;
+    try {
+      ({ meta } = parseGlobsFrontmatter(readFileSync(join(dir, file), 'utf8')));
+    } catch {
+      continue; // unreadable or unparseable — skip, never throw
+    }
+    if (!isMachineGeneratedRule(meta)) continue;
+    const raw = meta?.['expires-at'];
+    rules.push({ file, meta, expiresAt: typeof raw === 'string' ? raw : null });
+  }
+
+  return { ok: true, rules };
+}
+
 /**
  * Single-pass scan of `.claude/rules/*.md` producing the TWO corpus measures
  * this guard's third axis needs, which #1297 proved are NOT the same set:
@@ -1104,6 +1274,83 @@ export function computeInstructionBudget(opts = {}) {
   };
 }
 
+/** 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'
+  );
+}
+
 /**
  * Banner wrapper — session-start Phase 4 convention.
  *
@@ -1128,10 +1375,15 @@ 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. The RETURN SHAPE is unchanged (`{severity:'warn',
+ *   message}` | null), so `session-start-probes.mjs` needs no new vocabulary.
  */
 export function checkInstructionBudget(opts = {}) {
   let cfg;
@@ -1191,7 +1443,33 @@ 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;
+
+  if (!budget.overBudget && !nearPathScoped) return null;
+
+  const nearLine = nearPathScoped ? formatNearPathScopedLine(budget, opts.repoRoot) : null;
+
+  // Near-threshold and nothing breached: a one-finding banner, carrying the
+  // same remedy as the breach clause below (consolidate — never raise).
+  if (!budget.overBudget) {
+    return {
+      severity: 'warn',
+      message: [
+        `⚠ ${nearLine}.`,
+        '  Consolidate generated rules per docs/rule-authoring.md § Consolidated rules; never raise the ceiling.',
+      ].join('\n'),
+    };
+  }
 
   // Name only the breached axes — listing a healthy axis would pad the line
   // without telling the operator anything they must act on.
@@ -1237,8 +1515,12 @@ 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.',
   ].join('\n');

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?)');
   }

package/scripts/lib/is-main-module.mjs

@@ -0,0 +1,82 @@
+/**
+ * is-main-module.mjs — the one entry-guard predicate, symlink-safe.
+ *
+ * ## The incident class
+ *
+ * An ESM module that wants to run `main()` only when invoked as a CLI has to
+ * compare "the module I am" against "the script Node was told to run". The two
+ * sides are NOT the same kind of path:
+ *
+ *   - `import.meta.url` is resolved by Node to the module's **realpath**.
+ *   - `process.argv[1]` is the path **as typed on the command line**.
+ *
+ * With a symlink anywhere in the invocation path — a `node_modules/.bin/` shim,
+ * a `~/bin/foo -> /repo/scripts/foo.mjs` convenience link, a plugin directory
+ * symlinked into `~/.claude/plugins/`, or `/tmp` itself (on macOS `/tmp` is a
+ * symlink to `/private/tmp`) — the two strings differ and the guard is FALSE.
+ *
+ * The failure is silent and total: `main()` never runs, nothing is printed, and
+ * the process exits 0. Every caller — a hook, a CI job, an npm script, an
+ * operator — reads that as success. This is the single worst shape a defect can
+ * have in this repo, which is why the predicate is centralised here instead of
+ * being re-typed per file.
+ *
+ * ## The textual variants this replaces
+ *
+ * Measured 2026-09-16 @ ca214376 over the 50 files swept for #1371, the guard
+ * had been hand-written in 15 distinct textual forms (measured by extracting the
+ * guard expression from every file at HEAD), collapsing into four
+ * semantic variants — all four wrong in the same way:
+ *
+ *   V1  import.meta.url === `file://${process.argv[1]}`
+ *       (also breaks on any space or non-ASCII char in the path — no escaping)
+ *   V2  import.meta.url === pathToFileURL(process.argv[1] ?? '').href
+ *   V3  resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url))
+ *       / resolve(process.argv[1]) === resolve(__filename)
+ *   V4  fileURLToPath(import.meta.url) === process.argv[1]
+ *
+ * V2/V3 fix the `undefined`-argv and relative-path cases; none of them resolve
+ * symlinks, because only `realpath` does.
+ *
+ * ## Non-goal: Windows drive-letter / case folding
+ *
+ * `realpathSync.native` delegates to the OS, so on NTFS it canonicalises the
+ * stored casing of every path component and the two sides agree. Where the
+ * realpath call FAILS (deleted path, permission error) the fallback is a raw
+ * string compare, which on Windows can be case-sensitive against a
+ * case-insensitive filesystem. That residual case is deliberately out of scope:
+ * this repo runs on macOS and Linux CI, and a case-only mismatch degrades to
+ * today's behaviour rather than to something worse.
+ *
+ * @module scripts/lib/is-main-module
+ */
+
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Whether the module identified by `importMetaUrl` is the script Node was
+ * invoked with.
+ *
+ * Symlink-safe: both sides are canonicalised via `realpathSync.native` before
+ * comparison, so an invocation through a symlink (shim, `~/bin` link, `/tmp` on
+ * macOS) still matches. When either path cannot be realpath'd — it was deleted
+ * between spawn and this call, or is unreadable — the comparison degrades to a
+ * raw string compare rather than throwing, because an entry guard must never be
+ * the thing that crashes an import.
+ *
+ * @param {string} importMetaUrl the calling module's `import.meta.url`
+ * @param {string | undefined} [argv1] the invoked script path; defaults to
+ *   `process.argv[1]`, which is `undefined` under `node -e`, the REPL and some
+ *   dynamic-import contexts — those return `false`
+ * @returns {boolean} true when this module IS the entrypoint
+ */
+export function isMainModule(importMetaUrl, argv1 = process.argv[1]) {
+  if (!argv1) return false;
+  const self = fileURLToPath(importMetaUrl);
+  try {
+    return realpathSync.native(argv1) === realpathSync.native(self);
+  } catch {
+    return argv1 === self;
+  }
+}