session-orchestrator 5.1.0 → 5.2.0

package/scripts/lib/command-blocker.mjs

@@ -743,6 +743,31 @@ export { splitSegments as splitChainSegments };
 
 const ENV_ASSIGN_RE = /^[A-Za-z_][A-Za-z0-9_]*=/;
 
+/**
+ * Verbs that name a WRITE TARGET as a bare operand — no redirect operator, no
+ * wrapper flag (#1366). A sibling of WRAPPER_UNWRAP's `fileArgFlags`: that table
+ * answers "does this WRAPPER flag's operand name a file the wrapper writes?",
+ * this one "does this VERB's operand name a file the verb writes?".
+ *
+ * Spec fields:
+ *   - prefix:   the operand's literal prefix (`of=`), matched on a token AFTER
+ *               the resolved verb.
+ *   - mode:     the default redirect mode the write is equivalent to.
+ *   - appendRe: operands that turn the write into an APPEND. `dd` truncates by
+ *               default (`conv=notrunc` / `oflag=append` do not), so reporting
+ *               `truncate` unconditionally would over-report a rule class that
+ *               deliberately permits `>>`.
+ *
+ * Deliberately narrow — one entry, measured. `tee`/`sponge` and in-process
+ * writers (`node -e fs.writeFileSync`) are NOT here: they are not redirect-shaped
+ * and belong to a different rule class (see the `redirect-harness-memory`
+ * rationale in .orchestrator/policy/blocked-commands.json). REVISIT TRIGGER: a
+ * second `<verb> <prefix>file` writer showing up in a transcript census.
+ */
+const VERB_FILE_OPERANDS = new Map([
+  ['dd', { prefix: 'of=', mode: 'truncate', appendRe: /^(?:conv=.*\bnotrunc\b|oflag=.*\bappend\b)/ }],
+]);
+
 /**
  * Transparent process-wrapper table for verb resolution (#982), keyed by
  * basename. Each spec describes how to skip a wrapper's own options so the
@@ -946,15 +971,37 @@ function resolveCore(segment, unknownFlagsTakeValue) {
       if (spec.splitString
           && (text === '-S' || text === '--split-string'
             || text.startsWith('--split-string=') || text.startsWith('-S'))) {
+        // env(1) APPENDS the remaining argv to the split string: `env -S bash
+        // -c '…'` runs `bash -c '…'`, not `bash` (#1366). Collecting only the
+        // operand made the trailing `-c '…'` execute unseen — the segment then
+        // resolved to `verb: 'echo x > CLAUDE.md'` (the quoted payload read as
+        // the verb) and neither the match surface nor the redirect surface ever
+        // saw it. So the payload is the operand PLUS every remaining token, and
+        // the wrapper CONSUMES the segment: nothing is left to resolve as a
+        // verb, which is why this now yields `verb: null, index: -1`.
+        let operand = null;
         if (text.startsWith('--split-string=')) {
-          payloads.push(text.slice('--split-string='.length));
+          operand = text.slice('--split-string='.length);
+          i++;
         } else if (text !== '-S' && text !== '--split-string') {
-          payloads.push(text.slice(2)); // attached form: -S'string'
-        } else if (i + 1 < segment.length) {
-          payloads.push(segment[i + 1].text);
+          operand = text.slice(2); // attached form: -S'string'
           i++;
+        } else if (i + 1 < segment.length) {
+          operand = segment[i + 1].text;
+          i += 2;
+        } else {
+          i++; // `env -S` with no operand at all — nothing to collect
+        }
+        if (operand !== null) {
+          // Raw token texts, joined by one space. Quoting is NOT re-applied:
+          // the tokenizer already stripped it, and re-inventing it would be a
+          // second quoting grammar. The direction of that loss is safe — an
+          // over-wide payload can only make MORE text visible to the matcher
+          // (fail-closed), never hide a redirect operator.
+          const rest = segment.slice(i).map((t) => t.text);
+          payloads.push(rest.length > 0 ? [operand, ...rest].join(' ') : operand);
+          i = segment.length;
         }
-        i++;
         continue;
       }
       if (spec.shellFlags && spec.shellFlags.has(text)) { sawShellFlag = true; i++; continue; }
@@ -1189,15 +1236,65 @@ function dedupedSegmentPayloads(segment, resolved) {
   if (resolved.verb && DASH_C_SHELLS.has(resolved.verb)) {
     for (const p of dashCPayloads(segment, resolved.index)) payloadSet.add(p);
   }
+  addArgJoinedPayload(segment, resolved.verb, resolved.index, payloadSet);
   if (resolved.alt) {
     for (const p of resolved.alt.payloads) payloadSet.add(p);
     if (resolved.alt.verb && DASH_C_SHELLS.has(resolved.alt.verb)) {
       for (const p of dashCPayloads(segment, resolved.alt.index)) payloadSet.add(p);
     }
+    addArgJoinedPayload(segment, resolved.alt.verb, resolved.alt.index, payloadSet);
   }
   return [...payloadSet];
 }
 
+/**
+ * Interpreters that JOIN their remaining arguments with a space and execute the
+ * result — no `-c` flag, no wrapper option to key on (#1366).
+ *
+ * `eval` is the whole set today. It was already in SHELL_EXEC_INTERPRETERS, but
+ * that set only powers the QUOTED-TOKEN match in matchSegments — it never fed
+ * the payload traversal, so `eval 'echo x > CLAUDE.md'` carried a redirect no
+ * redirect rule ever saw (`resolveSegmentVerb` reports `payloads: []` for it).
+ *
+ * NAMED CEILING (BV-004): only a LITERAL payload is reachable. `eval "$CMD"` and
+ * `eval $(…)` do not exist as command text at hook time and stay in the existing
+ * `unresolved` class (#641). REVISIT TRIGGER: a second arg-joining interpreter
+ * showing up in a transcript census — extend the set, never special-case `eval`.
+ */
+const ARG_JOINING_INTERPRETERS = new Set(['eval']);
+
+/**
+ * Add the joined post-verb argument text as a recursion payload when `verb` is
+ * an arg-joining interpreter. No-op otherwise — every other caller shape keeps
+ * the pre-#1366 payload set byte-identical.
+ *
+ * Quoting is not re-applied for the same reason as the `env -S` tail (see
+ * resolveCore): the tokenizer stripped it, and a wider payload can only make
+ * more text visible to the matcher, never hide an operator.
+ *
+ * @param {Array<{ text: string, quoted: boolean }>} segment
+ * @param {string|null} verb
+ * @param {number} index — the verb's token index (`-1` when unresolved)
+ * @param {Set<string>} payloadSet — mutated in place
+ */
+function addArgJoinedPayload(segment, verb, index, payloadSet) {
+  if (!verb || index < 0 || !ARG_JOINING_INTERPRETERS.has(verb)) return;
+  const words = [];
+  for (let i = index + 1; i < segment.length; i++) {
+    if (segment[i].redirect) {
+      // A redirect belongs to the SEGMENT (`eval 'x' > f` redirects eval's own
+      // stdout), never to the joined argv — the segment scan already reported
+      // it, and re-reporting it through the payload would duplicate the entry.
+      const end = redirectSpanEnd(segment, i);
+      if (end > i) i = end;
+      continue;
+    }
+    words.push(segment[i].text);
+  }
+  const joined = words.join(' ').trim();
+  if (joined.length > 0) payloadSet.add(joined);
+}
+
 /**
  * Match a blocked-pattern regex against tokenized chain segments — the shared
  * core of commandMatchesBlocked, recursion-capable for `-c` payloads (#982).
@@ -1347,6 +1444,37 @@ function collectRedirectTargets(segments, out, depth, budget) {
       out.push({ target: wa.value, mode: 'truncate', fd: null });
     }
 
+    // A VERB can name its write target as a bare operand, with no redirect
+    // operator and no wrapper flag: `dd of=CLAUDE.md` truncates CLAUDE.md while
+    // `> CLAUDE.md` is denied (measured ALLOW pre-#1366 against the real
+    // policy). Keyed on the RESOLVED verb, so `sudo dd of=X` is reached through
+    // the existing wrapper unwrap; both readings contribute, as above.
+    const seenVerbOperands = new Set();
+    for (const reading of resolved.alt ? [resolved, resolved.alt] : [resolved]) {
+      const spec = reading.verb ? VERB_FILE_OPERANDS.get(reading.verb) : null;
+      if (!spec || reading.index < 0) continue;
+      let operand = null;
+      let append = false;
+      for (let k = reading.index + 1; k < segment.length; k++) {
+        const text = segment[k].text;
+        if (segment[k].redirect) continue;
+        if (text.startsWith(spec.prefix)) operand = text.slice(spec.prefix.length);
+        else if (spec.appendRe?.test(text)) append = true;
+      }
+      if (operand === null || operand.length === 0) continue;
+      const mode = append ? 'append' : spec.mode;
+      const key = `${operand}:${mode}`;
+      if (seenVerbOperands.has(key)) continue;
+      seenVerbOperands.add(key);
+      if (/[$`]/.test(operand)) {
+        // Same fail-visible rule as a redirect operand (#983) — never guess at a
+        // variable or a command substitution, never silently drop it either.
+        out.push({ target: null, mode, fd: null, unresolved: true });
+        continue;
+      }
+      out.push({ target: operand, mode, fd: null });
+    }
+
     // Both readings of an ambiguous unknown flag contribute payloads (#1000),
     // UNIONED and de-duped (HIGH-2). Walking parse A only let
     // `env -Q x bash -c 'echo pwned > CLAUDE.md'` — which resolves to the

package/scripts/lib/config/drift-check.mjs

@@ -5,6 +5,25 @@ import { preprocessBlockLines } from './block-preprocess.mjs';
  * drift-check.mjs — Parser for the top-level `drift-check:` YAML block.
  *
  * Ported from config-yaml-parser.sh (v2).
+ *
+ * SCOPE NOTE — this file parses FLAGS ONLY; it implements no check. The
+ * `check-command-count` flag below toggles the `command-count` surface in
+ * `skills/claude-md-drift-check/checker.mjs`, which is where the counting lives.
+ *
+ * `command-count` STAYS on `ls commands/*.md | wc -l` on purpose. The checker is
+ * GENERIC over any consumer repo, where a slash command still IS a
+ * `commands/*.md` file. The 2026-09-16 command→skill fold (#1370) is a fact
+ * about THIS plugin — 24 command files folded into their same-named
+ * `skills/<name>/SKILL.md` behind an explicit `user-invocable: true` — so
+ * teaching the shared checker that union would mis-measure every repo that never
+ * folded. `scripts/site-numbers.mjs` `countCommands()` carries the union for this
+ * plugin's own tile, and names the divergence in its docblock.
+ *
+ * CONSEQUENCE for THIS repo, left deliberately visible rather than papered over:
+ * a prose claim of the shape "N commands" / "N slash commands" in a
+ * drift-check-scanned doc is compared against the `commands/` listing (2 after
+ * the fold), so such a claim must either be dropped or reworded off the
+ * `\b(\d+)\s+(?:\/)?commands?\b` pattern the checker matches.
  */
 
 /**

package/scripts/lib/convergence-monitor.mjs

@@ -45,7 +45,7 @@
 
 import { existsSync, statSync, openSync, readSync, closeSync } from 'node:fs';
 import { join } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { isMainModule } from './is-main-module.mjs';
 
 const DEFAULT_INTERVAL_S = 2;
 const EVENTS_FILE_REL = '.orchestrator/metrics/events.jsonl';
@@ -502,7 +502,7 @@ function main() {
 
 // Run the tail loop only when executed as a script. Importing the module (for
 // unit tests over `classify`) must not parse vitest's argv and exit 1.
-if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (isMainModule(import.meta.url)) {
   main();
 }
 

package/scripts/lib/cursor-hook-bridge.mjs

@@ -18,10 +18,10 @@
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
 
 import { matcherMatches, readHookDecision } from './pi-hook-bridge.mjs';
 import { resolvePluginRoot } from './plugin-root.mjs';
+import { isMainModule } from './is-main-module.mjs';
 
 export const CURSOR_TO_CANONICAL_EVENT = Object.freeze({
   sessionStart: 'SessionStart',
@@ -434,7 +434,7 @@ async function main() {
   process.stdout.write(`${JSON.stringify(toCursorHookOutput(eventName, result))}\n`);
 }
 
-const isMain = process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
+const isMain =isMainModule(import.meta.url);
 if (isMain) {
   main().catch((err) => {
     process.stderr.write(`cursor-hook-bridge: ${err instanceof Error ? err.message : err}\n`);

package/scripts/lib/description-surface.mjs

@@ -58,6 +58,7 @@
 import { readdirSync, readFileSync, statSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { join, relative, resolve } from 'node:path';
+import { isMainModule } from './is-main-module.mjs';
 
 /** Block-scalar indicator on the `description:` line: '>' (folded) or '|' (literal), optional chomping '+'/'-'. */
 const BLOCK_SCALAR_RE = /^([>|])([+-]?)\s*$/;
@@ -526,10 +527,6 @@ function main() {
 }
 
 const __filename = fileURLToPath(import.meta.url);
-const isMain =
-  typeof process !== 'undefined' &&
-  process.argv[1] !== null &&
-  process.argv[1] !== undefined &&
-  resolve(process.argv[1]) === resolve(__filename);
+const isMain =isMainModule(import.meta.url);
 
 if (isMain) main();

package/scripts/lib/dispatcher/cli.mjs

@@ -32,6 +32,7 @@ import { warn } from '../common.mjs';
 import { acquire } from '../session-lock.mjs';
 import { enumerateCandidates, freeCandidates } from './enumerate.mjs';
 import { rankCandidates } from './rank.mjs';
+import { isMainModule } from '../is-main-module.mjs';
 
 const VERSION = '1.0.0';
 
@@ -247,7 +248,7 @@ export async function main(argv) {
 }
 
 // Run main only when executed directly, never on import.
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isMainModule(import.meta.url)) {
   main(process.argv.slice(2))
     .then((code) => process.exit(code))
     .catch((err) => {

package/scripts/lib/ecosystem-wizard.mjs

@@ -7,6 +7,7 @@
  */
 
 import { runEcosystemWizard } from './ecosystem-wizard/wizard-prompt.mjs';
+import { isMainModule } from './is-main-module.mjs';
 
 export { detectCiProvider } from './ecosystem-wizard/ci-detector.mjs';
 export {
@@ -31,7 +32,7 @@ export { runEcosystemWizard } from './ecosystem-wizard/wizard-prompt.mjs';
 // CLI entry
 // ---------------------------------------------------------------------------
 
-if (process.argv[1] && process.argv[1].endsWith('ecosystem-wizard.mjs')) {
+if (isMainModule(import.meta.url)) {
   const args = process.argv.slice(2);
   const repoRootIdx = args.indexOf('--repo-root');
   const dryRun = args.includes('--dry-run');

package/scripts/lib/fetch-baseline.mjs

@@ -30,6 +30,8 @@ import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { execSync } from 'node:child_process';
 
+import { isMainModule } from './is-main-module.mjs';
+
 // ---------------------------------------------------------------------------
 // Configuration defaults (mirrors the .sh defaults)
 // ---------------------------------------------------------------------------
@@ -296,14 +298,7 @@ async function _cliMain() {
   process.exit(3);
 }
 
-// Detect CLI invocation: import.meta.url matches the argv[1] path
-const isMain = process.argv[1] && (
-  process.argv[1] === new URL(import.meta.url).pathname ||
-  // Handle invocation without file:// prefix
-  process.argv[1].endsWith('fetch-baseline.mjs')
-);
-
-if (isMain) {
+if (isMainModule(import.meta.url)) {
   _cliMain().catch((err) => {
     process.stderr.write(`FATAL: ${err instanceof Error ? err.message : String(err)}\n`);
     process.exit(3);

package/scripts/lib/gitlab-ops/stale-mr-sweep.mjs

@@ -24,6 +24,7 @@ import { promisify } from 'node:util';
 
 import { detectVcsForRepo, discoverVaultRepos } from '../gitlab-portfolio/vcs-detect.mjs';
 import { resolveRepoSpec } from '../vcs-repo-spec.mjs';
+import { isMainModule } from '../is-main-module.mjs';
 
 const realExecFile = promisify(execFileCb);
 
@@ -455,7 +456,7 @@ export async function main(argv, deps = {}) {
 
 // ── CLI guard — prevent process.exit during test-time imports ─────────────────
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isMainModule(import.meta.url)) {
   main(process.argv.slice(2))
     .then((result) => {
       process.exit(result.exitCode);

package/scripts/lib/gitlab-portfolio/cli.mjs

@@ -36,6 +36,7 @@ import { expandTilde } from '../common.mjs';
 import { discoverVaultRepos } from './vcs-detect.mjs';
 import { fetchIssuesMultiRepo, summarizeRepo } from './aggregator.mjs';
 import { renderPortfolio, writePortfolio } from './markdown-writer.mjs';
+import { isMainModule } from '../is-main-module.mjs';
 
 // ── Helpers ───────────────────────────────────────────────────────────────────
 
@@ -406,7 +407,7 @@ EXIT CODES
 
 // ── CLI guard — prevent process.exit during test-time imports ─────────────────
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isMainModule(import.meta.url)) {
   main(process.argv.slice(2)).then((result) => {
     process.exit(result.exitCode);
   }).catch((err) => {

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

@@ -255,17 +255,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 +273,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 +381,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 +416,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`
@@ -749,7 +785,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 +794,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: