session-orchestrator 3.24.0 → 4.0.0

package/scripts/lib/gates/gate-helpers.mjs

@@ -268,6 +268,82 @@ export function extractTestCounts(output) {
   return { passed, failed, total, files };
 }
 
+/**
+ * ANSI SGR / CSI escapes vitest emits when it believes it writes to a TTY.
+ * `runCheck` captures through a pipe, where vitest disables colour — but a
+ * runner invoked through a pty wrapper, or with `FORCE_COLOR`, still colours
+ * its output and would defeat every anchored match below.
+ */
+// eslint-disable-next-line no-control-regex
+const ANSI_ESCAPE = /\u001b\[[0-9;]*[A-Za-z]/g;
+
+/** Path shape of a test/spec file, as printed by vitest/jest. */
+const TEST_FILE_PATH = String.raw`[^\s()]+\.(?:test|spec)\.[cm]?[jt]sx?`;
+
+/**
+ * `FAIL <path>` — printed once per failing FILE in the "Failed Tests" and
+ * "Failed Suites" sections. Two real shapes, both covered by this anchor
+ * (measured against vitest 4.1.5, 2026-09-06):
+ *
+ *   ` FAIL  dead.test.mjs [ dead.test.mjs ]`      ← suite died at import
+ *   ` FAIL  red.test.mjs > red > fails`           ← a test case failed
+ */
+const FAIL_LINE = new RegExp(String.raw`^\s*FAIL\s+(${TEST_FILE_PATH})(?:\s|$)`);
+
+/**
+ * `❯ <path> (N tests | M failed)` — the per-file line of the run summary.
+ *
+ * The `(… | … failed)` group is load-bearing, NOT decoration: vitest prefixes
+ * STACK FRAMES with the same `❯` and the frame carries the same file name
+ * (` ❯ red.test.mjs:3:33`). Requiring the parenthesised counts is what keeps a
+ * frame — and a PASSING file's summary line, ` ❯ green.test.mjs (2 tests)` —
+ * out of the result.
+ */
+const FILE_SUMMARY_FAIL_LINE = new RegExp(
+  String.raw`^\s*❯\s+(${TEST_FILE_PATH})\s+\(\d+\s+tests?[^)]*\|\s*\d+\s+failed`,
+);
+
+/**
+ * Name the test FILES a failing run blamed — the one thing the gate envelope
+ * never carried.
+ *
+ * Measured 2026-09-06: a husky pre-push run blocked `git push origin main` with
+ * `{"test":{"status":"fail","total":16417,"passed":16415,"failed":2,
+ * "files_total":662,"files_passed":661,"files_failed":1,…}}` — a COUNT and no
+ * name. `files_failed: 1` says a file died; reconstructing WHICH one cost a
+ * full manual re-materialisation of the tracked tree, even though the runner
+ * had printed the path in the very output this envelope was built from.
+ *
+ * Order is first-appearance and duplicates are dropped: vitest names the same
+ * file on its summary line AND once per failing case inside it, so a raw match
+ * list would repeat one path N times and read as N failing files.
+ *
+ * Absolute paths are relativised against `cwd` when it is a prefix — a gate
+ * report is read next to `git status`, so a repo-relative path is the useful
+ * form. A path outside `cwd` is left verbatim rather than turned into a `../..`
+ * chain that names nothing an operator can act on.
+ *
+ * @param {string} output - Captured test-runner stdout/stderr.
+ * @param {string} [cwd=process.cwd()] - Root to relativise absolute paths against.
+ * @returns {string[]} De-duplicated file paths, in first-appearance order.
+ */
+export function extractFailedTestFiles(output, cwd = process.cwd()) {
+  if (!output || typeof output !== 'string') return [];
+
+  const prefix = cwd.endsWith('/') ? cwd : `${cwd}/`;
+  const seen = new Set();
+
+  for (const rawLine of output.split('\n')) {
+    const line = rawLine.replace(ANSI_ESCAPE, '');
+    const match = FAIL_LINE.exec(line) ?? FILE_SUMMARY_FAIL_LINE.exec(line);
+    if (!match) continue;
+    const file = match[1].startsWith(prefix) ? match[1].slice(prefix.length) : match[1];
+    seen.add(file);
+  }
+
+  return [...seen];
+}
+
 /**
  * Admit a suite-count triple, or refuse to claim a measurement.
  *

package/scripts/lib/hardware-pattern-detector.mjs

@@ -49,9 +49,26 @@ export const HW_SIGNALS = Object.freeze([
 // Per-signal detectors — stateless, pure functions over arrays
 // ---------------------------------------------------------------------------
 
+/**
+ * Terminal turn-event names accepted by the OOM detector.
+ *
+ * `orchestrator.turn.stopped` is the canonical name; `orchestrator.session.stopped`
+ * is the DEPRECATED legacy alias `hooks/on-stop.mjs` still emits beside it
+ * (carrying `deprecated: true`) for one deprecation generation. BOTH must be
+ * accepted here: every OOM record already on disk carries only the legacy name,
+ * so a hard switch would blind this detector to the entire history it exists to
+ * mine — and the `≥2 occurrences` aggregation threshold makes that silent
+ * (fewer hits, never an error).
+ *
+ * REMOVAL: drop `'orchestrator.session.stopped'` from this set on 2027-03-06,
+ * the date `hooks/on-stop.mjs` stops emitting the legacy name. See
+ * `skills/evolve/SKILL.md` § hardware-pattern, which documents the same window.
+ */
+const OOM_TERMINAL_EVENTS = new Set(['orchestrator.turn.stopped', 'orchestrator.session.stopped']);
+
 function detectOomKill(events) {
   const hits = events.filter((e) => {
-    if (e.event !== 'orchestrator.session.stopped') return false;
+    if (!OOM_TERMINAL_EVENTS.has(e.event)) return false;
     if (e.exit_code === 137) return true;
     if (typeof e.error === 'string' && /out of memory|killed/i.test(e.error)) return true;
     return false;

package/scripts/lib/harness-audit/categories/category4.mjs

@@ -4,7 +4,9 @@
  * Checks: state-md-schema, sessions-jsonl-recent, learnings-prunable,
  *         vault-sync-validator, orphaned-session-lock
  *
- * Stdlib only: node:fs, node:path.
+ * Stdlib + intra-repo helpers only (node:fs, node:path, ./helpers.mjs,
+ * ../../session-schema/filters.mjs, ../../sessions-canonical.mjs,
+ * ../../config/section-extractor.mjs).
  */
 
 import { existsSync } from 'node:fs';
@@ -12,6 +14,7 @@ import { join, relative, sep } from 'node:path';
 
 import { parseFrontmatter, safeRead, parseJsonl, pass, fail } from './helpers.mjs';
 import { isRealSession } from '../../session-schema/filters.mjs';
+import { canonicalizeSessions } from '../../sessions-canonical.mjs';
 import { findSessionConfigBlock } from '../../config/section-extractor.mjs';
 
 // Default session-lock TTL in hours — mirrors DEFAULT_TTL_HOURS in
@@ -95,17 +98,34 @@ export function runCategory4(root) {
           { latestCompletedAt: null, ageInDays: null },
           'sessions.jsonl is empty'));
       } else {
-        // Scan backward past any trailing `status: 'abandoned'` phantom stubs
-        // (#834, session-close-backfill) to the last REAL session — otherwise a
-        // recent phantom lets a dormant repo pass a check meant to certify
-        // recent REAL engagement.
+        // Most-recent REAL session by completed_at, over the CANONICAL record
+        // set (#1209b) — canonicalizeSessions() already collapses duplicate
+        // `session_id` lines to the newest occurrence, drops the systemic
+        // double-stub twin, and removes any record a surviving one
+        // `supersedes`. A raw backward-scan-to-last-real-LINE (the pre-#1209b
+        // approach) cannot see this: a duplicate id whose LAST occurrence was
+        // retroactively corrected to `status: 'abandoned'` still let an
+        // EARLIER, now-superseded raw line for the same identity count as
+        // "recent". Max, not backward-scan, because canonical order is
+        // first-appearance order per id, not completed_at order.
+        //
+        // `keepUnidentified: true` — unlike the bare `readCanonicalSessions()`
+        // wrapper, this check has never required a `session_id` (it only ever
+        // read `completed_at`/`status`), so silently dropping id-less records
+        // would be a behaviour change this migration does not intend.
+        const parsedLines = [];
+        for (const line of lines) {
+          try { parsedLines.push(JSON.parse(line)); } catch { /* skip malformed */ }
+        }
+        const records = canonicalizeSessions(parsedLines, { keepUnidentified: true });
         let lastObj = null;
-        for (let i = lines.length - 1; i >= 0; i -= 1) {
-          let parsed = null;
-          try { parsed = JSON.parse(lines[i]); } catch { /* ignore */ }
-          if (parsed && isRealSession(parsed)) {
-            lastObj = parsed;
-            break;
+        let lastMs = -Infinity;
+        for (const rec of records) {
+          if (!isRealSession(rec)) continue;
+          const ms = Date.parse(rec?.completed_at);
+          if (Number.isFinite(ms) && ms > lastMs) {
+            lastMs = ms;
+            lastObj = rec;
           }
         }
         const completedAt = lastObj ? lastObj.completed_at : null;

package/scripts/lib/host-identity.mjs

@@ -17,7 +17,7 @@
  *     ram_total_gb: 18,
  *     hostname_hash: '<sha256 hex>',
  *     is_ssh: false,
- *     platform: 'claude' | 'codex' | 'cursor' | null,
+ *     platform: 'claude' | 'codex' | 'cursor' | 'pi',
  *     first_seen: '2026-04-19T11:00:00Z',
  *   }
  *
@@ -40,16 +40,25 @@ import {
   unlinkSync,
 } from 'node:fs';
 import { digestSha256WithSalt } from './crypto-digest-utils.mjs';
+import { resolvePrivateConfigDir } from './config/private-config-dir.mjs';
 import path from 'node:path';
 import os from 'node:os';
 // NOTE (#1072 gate fix): platform.mjs is deliberately NOT imported statically.
-// Its module level computes SO_PLATFORM/SO_PLUGIN_ROOT via detectPlatform()/
-// resolvePluginRoot(), which walk the filesystem (existsSync + readFileSync of
-// package.json up the tree). session-lock.mjs now imports this module, which
-// put those import-time reads into every graph that imports session-lock —
-// including fs-mocked test graphs (tests/lib/vault-mirror/process.test.mjs went
-// red: the walk consumed the mocks' sequenced return values). The only two
-// consumers (SO_OS/SO_PLATFORM in collectFingerprint) are async — load lazily.
+// Its module level used to compute SO_PLATFORM/SO_PLUGIN_ROOT via
+// detectPlatform()/resolvePluginRoot(), which walk the filesystem
+// (existsSync + readFileSync of package.json up the tree). session-lock.mjs
+// now imports this module, which put those import-time reads into every
+// graph that imports session-lock — including fs-mocked test graphs
+// (tests/lib/vault-mirror/process.test.mjs went red: the walk consumed the
+// mocks' sequenced return values). The only two consumers in
+// collectFingerprint (os name + platform) are async — load lazily.
+//
+// (#1153 P5) platform.mjs now exports memoized lazy getters
+// (getPlatform(), getPluginRoot(), ...); the old SO_PLATFORM/SO_PROJECT_DIR/…
+// names are deprecated `export let` live bindings that stay `undefined`
+// until the matching getter has run elsewhere in the process. Destructure
+// and CALL getPlatform() below — never read the deprecated SO_PLATFORM
+// binding directly, or `platform` silently records null/undefined.
 
 const FINGERPRINT_TTL_MS = 24 * 60 * 60 * 1000; // 24h
 const PLACEHOLDER_SALT = 'env-aware-v1-default-salt-replaced-by-owner-yaml';
@@ -345,8 +354,38 @@ export function lockHostCandidate(lock) {
 // Paths
 // ---------------------------------------------------------------------------
 
+/**
+ * The host-private config directory — every per-host artefact below it
+ * (`host-private.json`, `owner.yaml`, the alias ledger) moves with it.
+ *
+ * Precedence (`SO_CONFIG_HOME` = the dir itself > `XDG_CONFIG_HOME` = its
+ * parent > homedir, each trimmed) now lives in ONE place: `resolvePrivateConfigDir`
+ * in `config/private-config-dir.mjs` (#1223) — a ZERO-IMPORT leaf (`node:os` +
+ * `node:path` only).
+ *
+ * The leaf is deliberately NOT `owner-yaml.mjs`, although that module re-exports
+ * the same function: owner-yaml.mjs statically imports `js-yaml`, and THIS module
+ * sits on `on-stop.mjs`'s import subgraph (via `session-lock.mjs`). Importing the
+ * resolver from owner-yaml.mjs therefore put a bare specifier on THAT subgraph and
+ * broke the GH#63 contract that on-stop degrades with one actionable line when
+ * node_modules is absent (measured: `ERR_MODULE_NOT_FOUND: Cannot find package
+ * 'js-yaml' imported from …/scripts/lib/owner-yaml.mjs`, 2 red tests in
+ * tests/hooks/on-stop.test.mjs). Never import owner-yaml.mjs from here.
+ *
+ * This says nothing about the WHOLE hook import graph, which is NOT bare-free.
+ * Measured 2026-09-05 over `hooks/_lib/hook-import-set.json` (150 entries, head
+ * 4b45130): two bare specifiers remain, both pre-existing — `owner-yaml.mjs →
+ * js-yaml` (reachable from on-session-start, on-session-end, post-edit-validate,
+ * skill-invocation-telemetry) and `scripts/lib/worktree/listing.mjs → zx`
+ * (on-session-start). Only `on-stop.mjs` degrades without node_modules today;
+ * the other four throw ERR_MODULE_NOT_FOUND. The guard in
+ * `tests/hooks/on-stop.test.mjs` allowlists exactly those two, so a THIRD one
+ * turns red.
+ *
+ * @returns {string} absolute path to the host-private config directory
+ */
 function _privateDir() {
-  return path.join(os.homedir(), '.config', 'session-orchestrator');
+  return resolvePrivateConfigDir();
 }
 
 function _privateFile() {
@@ -393,7 +432,7 @@ export async function resolveSalt() {
  * @param {string} [opts.salt] — override salt (tests)
  */
 export async function collectFingerprint(opts = {}) {
-  const { SO_OS, SO_PLATFORM } = await import('./platform.mjs');
+  const { SO_OS, getPlatform } = await import('./platform.mjs');
   const osName = SO_OS;
   const arch = process.arch;
   const cpus = os.cpus() || [];
@@ -417,7 +456,7 @@ export async function collectFingerprint(opts = {}) {
     ram_total_gb: ramTotalGb,
     hostname_hash: hostnameHash,
     is_ssh: isSSH(),
-    platform: SO_PLATFORM || null,
+    platform: getPlatform(),
     first_seen: new Date().toISOString(),
   };
 }

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

@@ -76,9 +76,9 @@
  *   self-relative growth ratchet calibrated just above our own baseline.
  */
 
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { basename, join } from 'node:path';
-import { loadApplicableRules } from './rule-loader.mjs';
+import { loadApplicableRules, parseGlobsFrontmatter } from './rule-loader.mjs';
 
 /** Default directive ceiling (operator-chosen growth ratchet just above the ~457 baseline). */
 export const DEFAULT_CEILING = 480;
@@ -140,6 +140,76 @@ export const DEFAULT_CEILING = 480;
  */
 export const DEFAULT_BYTE_CEILING = 121000;
 
+/**
+ * Default byte ceiling for the PATH-SCOPED rule surface — the third axis, and
+ * the one that closes this guard's largest blind spot.
+ *
+ * Both ceilings above measure ONLY always-on rules (`loadApplicableRules`
+ * with `scopePaths: []` returns nothing else), so every `globs:`-scoped rule
+ * file was invisible to this guard by construction. That blind spot was
+ * MEASURED, not hypothesised: on 2026-09-06 @ `e4674109` the reconciliation
+ * engine had accumulated **43 generated rule files / 112,443 B** in
+ * `.claude/rules/` — 46.2 % of it pure frontmatter+provenance overhead — while
+ * this guard reported a comfortable 470/480 directives over 15 files and could
+ * not have fired on that growth at any ceiling, because it never counted it.
+ * A wave agent paid those bytes twice (rule-injection block + native delivery,
+ * see `docs/instruction-delivery.md` §5).
+ *
+ * Derivation (HR-105 — a threshold whose firing rate nothing records is not a
+ * rule): measured 2026-09-06 after the 43→8 consolidation AND the
+ * harness-parity repair that followed it, the path-scoped surface is
+ * **96,757 B over 11 files** (8 consolidated + the 3 hand-written scoped rules
+ * `testing.md` / `cli-design.md` / `bash-harness-pitfalls.md`), counted the
+ * same way as `totalBytes` — frontmatter stripped, via
+ * {@link countContentBytes}. RE-MEASURED 2026-09-06 later the same day
+ * (`computeInstructionBudget({repoRoot}).bySurface.generated` @ `bc49301b` →
+ * `{ bytes: 109593, files: 11 }`): the live figure is **109,593 B over the same
+ * 11 files**, ×1.13 under the unchanged 124,000 ceiling — restored prose, not
+ * reconciliation growth (the consolidation pass had dropped 10 learnings'
+ * bodies, which were written back into the same 8 files).
+ *
+ * CORRECTED 2026-09-06, one wave after the line above was first written. Two
+ * things in that first derivation no longer hold:
+ *
+ *  - The base was **95,277 B**, measured while the 8 consolidated files still
+ *    carried `globs:` with no `paths:`. Adding `paths:` + `learning-key:` did
+ *    NOT move this number by a single byte — {@link countContentBytes} strips
+ *    frontmatter — so the +1,480 B is entirely the 8 × 185 B provenance note
+ *    the repair added to the BODIES. Written down because the number moved and
+ *    the cause was hand-editing, NOT the reconciliation growth this axis
+ *    exists to catch.
+ *  - "The ~30 % headroom is deliberately the SAME relative slack the byte
+ *    ceiling above carries" was simply false. {@link DEFAULT_BYTE_CEILING}
+ *    carries +5 % (121,000 / 115,730 = 1.046), not +30 %. The axes are NOT
+ *    calibrated alike, and saying they were hid a 6× difference in tolerance.
+ *
+ * The ceiling STAYS at 124,000 rather than re-deriving upward to
+ * 96,757 × 1.30 ≈ 126,000. The guard has never fired at this base, and raising
+ * an unfired ceiling to preserve a round multiplier is the threshold-patch
+ * `.claude/rules/development.md` § Guard & Threshold Design forbids. 124,000 is
+ * now ×1.28 over the live corpus — tighter than before, not looser.
+ * Re-derive it (never merely raise it) with:
+ *
+ *   `node -e "…parseGlobsFrontmatter over .claude/rules/*.md…"` — or simply
+ *   read `computeInstructionBudget().bySurface.generated` and re-apply ×1.30.
+ *
+ * What makes this ceiling reachable rather than decorative (HR-105 again — a
+ * threshold nobody can falsify is not a rule): the SAME measurement replayed
+ * against `git show HEAD:.claude/rules/*` at `e4674109`, i.e. the tree one
+ * commit before the consolidation, returns **137,410 B over 46 path-scoped
+ * files** — over this ceiling, so the guard WOULD have fired there and is
+ * silent at 96,757 B / 11 files now. Firing rate on the two states that exist:
+ * 1 of 2. That is the intended condition — reconciliation growth, not the
+ * hand-written corpus, which contributes 3 of the 11 files.
+ *
+ * (Note 137,410 is not the 112,443 B the audit quotes for the 43 generated
+ * files: that figure is raw bytes INCLUDING frontmatter and EXCLUDING the 3
+ * hand-written scoped rules; this axis strips frontmatter and counts all 46.
+ * Two different populations — see `.claude/rules/measurement-discipline.md`
+ * § "the unnamed population".)
+ */
+export const DEFAULT_GENERATED_BYTE_CEILING = 124000;
+
 /**
  * Read the `instruction-budget:` nested block from the `## Session Config`
  * section of CLAUDE.md (or AGENTS.md) at `repoRoot`. Synchronous + never throws.
@@ -412,6 +482,65 @@ function sumBytes(entries) {
   return bytes;
 }
 
+/**
+ * Measure the PATH-SCOPED rule surface: every `.claude/rules/*.md` whose
+ * frontmatter carries `globs:` (or its `paths:` alias — issue #795), i.e.
+ * exactly the complement of the always-on set the three tier surfaces above
+ * measure.
+ *
+ * This cannot reuse `loadApplicableRules`: that loader takes a `scopePaths`
+ * list and returns the rules APPLICABLE to it, so with `scopePaths: []` it
+ * yields always-on rules only, and with a non-empty list it yields a
+ * scope-dependent subset. Neither answers "how big is the path-scoped corpus",
+ * which is a property of the DIRECTORY, not of any one wave's file scope. The
+ * frontmatter reading is still delegated (`parseGlobsFrontmatter`), so the
+ * always-on/path-scoped split stays decided in exactly one place.
+ *
+ * Named `generated` at the call site because reconciliation output is what
+ * grows here, but it deliberately measures every path-scoped file, including
+ * the hand-written ones — a ceiling that skipped them would report a number
+ * the operator cannot reproduce from `ls .claude/rules/` (HR-106: the banner
+ * reports what the rule judges).
+ *
+ * Bytes are counted with {@link countContentBytes} — frontmatter stripped —
+ * so this axis is directly comparable to `totalBytes` and to the tier
+ * surfaces. Never throws: an unreadable dir or file yields `{bytes:0,files:0}`
+ * / is skipped, matching this module's never-throw posture.
+ *
+ * @param {string} rulesDir
+ * @returns {{ bytes: number, files: number }}
+ */
+function measurePathScopedSurface(rulesDir) {
+  let names;
+  try {
+    names = readdirSync(rulesDir);
+  } catch {
+    return { bytes: 0, files: 0 };
+  }
+
+  let bytes = 0;
+  let files = 0;
+  for (const name of names) {
+    if (!name.endsWith('.md')) continue;
+    let content;
+    try {
+      content = readFileSync(join(rulesDir, name), 'utf8');
+    } catch {
+      continue; // unreadable file — skip, never throw
+    }
+    let globs;
+    try {
+      ({ globs } = parseGlobsFrontmatter(content));
+    } catch {
+      continue;
+    }
+    if (globs === null) continue; // always-on — already counted by the tier surfaces
+    files += 1;
+    bytes += countContentBytes(content);
+  }
+  return { bytes, files };
+}
+
 /**
  * Pure computation — always returns the full shape (never null, never throws).
  *
@@ -517,6 +646,10 @@ export function computeInstructionBudget(opts = {}) {
   const ceiling = typeof opts.ceiling === 'number' ? opts.ceiling : DEFAULT_CEILING;
   const byteCeiling =
     typeof opts.byteCeiling === 'number' ? opts.byteCeiling : DEFAULT_BYTE_CEILING;
+  const generatedByteCeiling =
+    typeof opts.generatedByteCeiling === 'number'
+      ? opts.generatedByteCeiling
+      : DEFAULT_GENERATED_BYTE_CEILING;
   // #893 fix: 'coordinator' used to fall through to the `null` (untiered)
   // branch below — silently measuring the WRONG rule set for a coordinator
   // context (it never excluded `tier: wave-only`). Now explicitly recognised
@@ -531,11 +664,13 @@ export function computeInstructionBudget(opts = {}) {
     perFile: [],
     ceiling,
     byteCeiling,
+    generatedByteCeiling,
     overDirectiveBudget: false,
     overByteBudget: false,
+    overGeneratedBudget: false,
     overBudget: false,
     severity: 'ok',
-    bySurface: { coordinator: 0, wave: 0, always: 0 },
+    bySurface: { coordinator: 0, wave: 0, always: 0, generated: { bytes: 0, files: 0 } },
   };
 
   let allEntries;
@@ -574,6 +709,13 @@ export function computeInstructionBudget(opts = {}) {
     coordinator: sumBytes(alwaysOnCoordinator),
     wave: sumBytes(alwaysOnWave),
     always: sumBytes(alwaysOnAll.filter((e) => e.tier === 'always')),
+    // The fourth surface is deliberately a different SHAPE from its three
+    // siblings ({bytes, files} vs. a bare byte number): a path-scoped corpus
+    // grows by FILE COUNT as much as by size — 43 files averaging 2.6 kB is
+    // the shape this axis exists to catch — and a bare number would hide that.
+    // It is also the only surface disjoint from `totalBytes`, which counts
+    // always-on rules exclusively.
+    generated: measurePathScopedSurface(rulesDir),
   };
 
   // Surface-selected entry set for the PRIMARY totals. `context: null`
@@ -605,7 +747,9 @@ export function computeInstructionBudget(opts = {}) {
   // long-standing boundary semantics rather than inventing a second rule.
   const overDirectiveBudget = totalDirectives > ceiling;
   const overByteBudget = totalBytes > byteCeiling;
-  const overBudget = overDirectiveBudget || overByteBudget;
+  // Third axis, same strict `>` boundary semantics as the two above.
+  const overGeneratedBudget = bySurface.generated.bytes > generatedByteCeiling;
+  const overBudget = overDirectiveBudget || overByteBudget || overGeneratedBudget;
 
   return {
     totalDirectives,
@@ -613,8 +757,10 @@ export function computeInstructionBudget(opts = {}) {
     perFile,
     ceiling,
     byteCeiling,
+    generatedByteCeiling,
     overDirectiveBudget,
     overByteBudget,
+    overGeneratedBudget,
     overBudget,
     severity: overBudget ? 'warn' : 'ok',
     bySurface,
@@ -655,6 +801,7 @@ export function checkInstructionBudget(opts = {}) {
       enabled: true,
       ceiling: DEFAULT_CEILING,
       'byte-ceiling': DEFAULT_BYTE_CEILING,
+      'generated-byte-ceiling': DEFAULT_GENERATED_BYTE_CEILING,
       mode: 'warn',
     };
   }
@@ -671,9 +818,19 @@ export function checkInstructionBudget(opts = {}) {
         ? cfg['byte-ceiling']
         : DEFAULT_BYTE_CEILING;
 
+  // Same precedence as the two axes above: explicit opt > Session Config >
+  // module default. Config-key is optional, so a repo that never heard of this
+  // axis still gets the measured default rather than `undefined`.
+  const generatedByteCeiling =
+    typeof opts.generatedByteCeiling === 'number'
+      ? opts.generatedByteCeiling
+      : typeof cfg['generated-byte-ceiling'] === 'number'
+        ? cfg['generated-byte-ceiling']
+        : DEFAULT_GENERATED_BYTE_CEILING;
+
   let budget;
   try {
-    budget = computeInstructionBudget({ ...opts, ceiling, byteCeiling });
+    budget = computeInstructionBudget({ ...opts, ceiling, byteCeiling, generatedByteCeiling });
   } catch {
     return null; // never throw out of the banner wrapper
   }
@@ -689,6 +846,15 @@ export function checkInstructionBudget(opts = {}) {
   if (budget.overByteBudget) {
     axes.push(`bytes ${budget.totalBytes} > ${budget.byteCeiling}`);
   }
+  if (budget.overGeneratedBudget) {
+    // Reported with its FILE COUNT, because the actionable lever on this axis
+    // is consolidating files, not trimming prose inside them (HR-106: the
+    // banner reports the number the rule judged).
+    axes.push(
+      `path-scoped ${budget.bySurface.generated.bytes} B over ` +
+        `${budget.bySurface.generated.files} files > ${budget.generatedByteCeiling} B`,
+    );
+  }
 
   // `perFile` arrives sorted DESC by directive count. When ONLY the byte axis
   // broke, that ordering points at the wrong files — re-sort by bytes so the