session-orchestrator 5.1.0 → 5.3.0

package/scripts/lib/maintenance-due-banner.mjs

@@ -20,7 +20,7 @@
  * ## Design constraints it is written against
  *
  * - **HR-101 (a signal may only warn if it is rare).** Nothing is due ⇒ the
- *   probe is SILENT. Six independent signals are ANDed with a cooldown, not
+ *   probe is SILENT. Seven independent signals are ANDed with a cooldown, not
  *   ORed into a permanent warning: a repo that ran `/session housekeeping`
  *   within the last {@link HOUSEKEEPING_COOLDOWN_DAYS} days says nothing at
  *   all, because the operator already did the thing the banner would ask for.
@@ -33,7 +33,7 @@
  *   an existing module constant. Same posture as `reconcile-nudge-banner.mjs`
  *   and `loop-readiness-banner.mjs`: an advisory banner needs no switch.
  *
- * ## The six signals
+ * ## The seven signals
  *
  * | id                | due when                                                              | source |
  * |-------------------|-----------------------------------------------------------------------|--------|
@@ -43,6 +43,20 @@
  * | `dialectic`       | `shouldDispatchAutoDialectic().trigger === true`                      | `auto-dialectic.mjs` |
  * | `memory-cleanup`  | `shouldDispatchAutoDream().trigger === true`                          | `auto-dream.mjs` |
  * | `pending-sidecar` | a pending dream/dialectic proposal younger than 14 days is unapplied   | `.orchestrator/*-pending*.md` |
+ * | `generated-rules-expiring` | a machine-generated rule is expired or expires within {@link GENERATED_RULE_EXPIRY_HORIZON_DAYS} days | `instruction-budget-guard.mjs` |
+ *
+ * ### Why the expiry alarm is HERE and not in the test suite (#1372 follow-up)
+ *
+ * The invariant "no generated rule file sits expired in `.claude/rules/`" was
+ * first written as a vitest case comparing `expires-at` against TODAY. That is
+ * a calendar time-bomb in a BLOCKING gate: with nothing committed and nothing
+ * broken, `npm test` — pre-push hook and CI alike — turns red on the morning
+ * after the earliest date and blocks every unrelated hotfix, while the repair
+ * (consolidate the file, move its provenance pairs, delete it) is a human
+ * decision no test run can take. HR-101/HR-105: a signal must fire when
+ * something CHANGED, at a moment the operator can act, and be repairable by the
+ * thing that fires it. Session start, recommending `/session housekeeping`, is
+ * that moment; the predicate itself is still tested, against an INJECTED clock.
  *
  * Only SIDE-EFFECT-FREE signal functions are called — never a variant that
  * advances `.orchestrator/dialectic-last-run`, because a probe that writes the
@@ -56,9 +70,10 @@
  * @module scripts/lib/maintenance-due-banner
  */
 
-import { closeSync, existsSync, fstatSync, openSync, readSync, statSync } from 'node:fs';
+import { existsSync, statSync } from 'node:fs';
 import path from 'node:path';
 
+import { SCAN_CHUNK_BYTES, scanEventsBackwards } from './events.mjs';
 import { computeReconcileNudge } from './reconcile-nudge-banner.mjs';
 import { sweepExpiredLearnings } from './learnings/expiry-sweep.mjs';
 import { shouldDispatchAutoDialectic } from './auto-dialectic.mjs';
@@ -66,13 +81,32 @@ import { shouldDispatchAutoDream } from './auto-dream.mjs';
 import { resolveMemoryDir } from './memory-paths.mjs';
 import { readCanonicalSessions } from './sessions-canonical.mjs';
 import { filterRealSessions } from './session-schema.mjs';
+import {
+  daysUntilGeneratedRuleExpiry,
+  listMachineGeneratedRules,
+} from './instruction-budget-guard.mjs';
 
 /**
  * How many signals this probe knows about. The banner denominator is this
  * number MINUS the signals a kill-switch skipped on this host — see the
  * `skipped` array in {@link computeMaintenanceDue}'s result.
  */
-export const MAINTENANCE_TOTAL_SIGNALS = 6;
+export const MAINTENANCE_TOTAL_SIGNALS = 7;
+
+/**
+ * How far ahead the `generated-rules-expiring` signal looks.
+ *
+ * NAMED CEILING (BV-004): 7 days is one week of sessions — long enough that the
+ * operator meets the warning before the loader silently starts dropping the
+ * rule, short enough that it is not standing noise (HR-104: a signal that is
+ * essentially always present is no signal). On this repo's corpus at
+ * 2026-09-16 the earliest `expires-at` was 14 days out, so the row is silent.
+ *
+ * REVISIT TRIGGER: if the row is due on more than ~1 session start in 10, the
+ * horizon is measuring the reconcile engine's 30-day default TTL rather than an
+ * overdue consolidation — re-aim it (HR-101), never widen it.
+ */
+export const GENERATED_RULE_EXPIRY_HORIZON_DAYS = 7;
 
 /**
  * Active-learning floor for the `evolve` signal. Deliberately the SAME number
@@ -119,104 +153,64 @@ function isoDay(ts) {
 }
 
 /**
- * Backwards-scan chunk size (#1290 item 2).
- *
- * NAMED CEILING: 256 KiB is ~800 records in this repo's ledger, so the common
- * case — a repo that ran /evolve within its recent history — answers after a
- * handful of reads instead of loading the whole 7.9 MB file. The scan is
- * UNBOUNDED in the worst case ON PURPOSE: "never ran" is a claim about every
- * line and cannot be made from a tail, so a repo with no `evolve.completed`
- * record still walks the file to its start — just in chunks, never all at once
- * in one string.
- *
- * REVISIT TRIGGER: the maintenance probe's median passes 1000 ms (half
- * `PROBE_BUDGET_MS`), or one repo's `events.jsonl` passes 50 MB. Either means
- * the "never ran" walk has become the cost that matters and the answer needs an
- * index rather than a scan.
+ * Backwards-scan chunk size (#1290 item 2) — the shared reader's constant, kept
+ * under this module's own name because it is the number this probe's cost is
+ * reasoned about in. NAMED CEILING + revisit trigger live at
+ * {@link SCAN_CHUNK_BYTES}.
  */
-export const TAIL_CHUNK_BYTES = 256 * 1024;
+export const TAIL_CHUNK_BYTES = SCAN_CHUNK_BYTES;
 
 /**
- * Scan a buffer of COMPLETE lines backwards for the newest evolve record.
+ * Wall-clock budget for the "did /evolve ever run?" walk (#1414).
+ *
+ * NAMED CEILING (BV-004): 1000 ms is half of `PROBE_BUDGET_MS` (2000 ms in
+ * `session-start-probes.mjs`), which this probe shares with six other signals.
+ * The walk is UNBOUNDED in principle — "never ran" is a claim about every line
+ * of every source — so it needs an own limit now that it spans the archives
+ * too, and running out must report `truncated`, never a clean "never".
  *
- * @param {Buffer} buf
- * @returns {{lastAt: string|null}|null} null ⇒ no record in this buffer
+ * REVISIT TRIGGER: a repo where this reports `truncated` more than rarely. That
+ * means the answer needs an index rather than a scan, not a bigger budget
+ * (HR-101).
  */
-function scanEvolveLines(buf) {
-  if (buf.length === 0) return null;
-  const lines = buf.toString('utf8').split('\n');
-  for (let i = lines.length - 1; i >= 0; i -= 1) {
-    const line = lines[i];
-    if (!line || !line.includes(EVOLVE_EVENT)) continue; // cheap pre-filter before JSON.parse
-    try {
-      const rec = JSON.parse(line);
-      if (rec?.event !== EVOLVE_EVENT) continue;
-      return { lastAt: typeof rec.timestamp === 'string' ? rec.timestamp : null };
-    } catch {
-      continue; // a malformed line is not evidence either way — keep scanning
-    }
-  }
-  return null;
-}
+export const EVOLVE_SCAN_BUDGET_MS = 1000;
 
 /**
- * Find the most recent `orchestrator.evolve.completed` record.
- *
- * Reads the ledger BACKWARDS in {@link TAIL_CHUNK_BYTES} chunks and stops at
- * the first hit, because the interesting answer is the LAST occurrence. The
- * former implementation `readFileSync`-ed the whole file (7.9 MB here, 30–44 ms)
- * to answer a question the last few kilobytes usually settle.
+ * Find the most recent `orchestrator.evolve.completed` record — across ROTATION
+ * boundaries (#1414).
  *
- * The one bug a naive chunked scan introduces is a record SPLIT across a chunk
- * boundary: the bytes before the first newline of a chunk are the tail of a line
- * whose head is in the chunk not read yet, so they are CARRIED, never parsed
- * here. Splitting on the 0x0A byte is safe on UTF-8 — no continuation byte can
- * equal a newline — so a multibyte character never splits a line either.
+ * Walks the ledger backwards through every source, newest first, and stops at
+ * the first hit, because the interesting answer is the LAST occurrence. Reading
+ * the active file alone was the bug: "never ran" is a claim about EVERY line
+ * ever written, and after a rotation the only `evolve.completed` record on the
+ * host can sit in `_archive/` — the probe then nags a repo that has run
+ * /evolve, which is the HR-101 failure mode this module exists to avoid.
  *
  * @param {string} repoRoot
- * @returns {{ok: boolean, lastAt: string|null}} `ok: false` ⇒ the ledger exists
- *   but could not be read — the caller must record `undeterminable`, never clean.
+ * @returns {{ok: boolean, lastAt: string|null, truncated: boolean}} `ok: false`
+ *   ⇒ a source exists but could not be read; `truncated: true` ⇒ the budget ran
+ *   out before the walk finished. In BOTH cases the caller must record
+ *   `undeterminable`, never clean — a walk that did not finish has not proven
+ *   "never".
  */
 function readLastEvolveRun(repoRoot) {
   const file = path.join(repoRoot, '.orchestrator', 'metrics', 'events.jsonl');
-  if (!existsSync(file)) return { ok: true, lastAt: null }; // fresh repo: genuinely never
-  let fd;
-  try {
-    fd = openSync(file, 'r');
-    let pos = fstatSync(fd).size;
-    /** Partial line at the FRONT of everything read so far. */
-    let carry = Buffer.alloc(0);
-
-    while (pos > 0) {
-      const length = Math.min(TAIL_CHUNK_BYTES, pos);
-      pos -= length;
-      const buf = Buffer.alloc(length);
-      readSync(fd, buf, 0, length, pos);
-      const block = carry.length > 0 ? Buffer.concat([buf, carry]) : buf;
-      const firstNewline = block.indexOf(0x0a);
-      if (firstNewline === -1) {
-        carry = block; // no complete line yet — a line longer than one chunk
-        continue;
-      }
-      const hit = scanEvolveLines(block.subarray(firstNewline + 1));
-      if (hit) return { ok: true, lastAt: hit.lastAt };
-      carry = block.subarray(0, firstNewline);
-    }
-
-    // pos === 0: the carry is the file's FIRST line, complete by construction.
-    const hit = scanEvolveLines(carry);
-    return { ok: true, lastAt: hit ? hit.lastAt : null };
-  } catch {
-    return { ok: false, lastAt: null };
-  } finally {
-    if (fd !== undefined) {
-      try {
-        closeSync(fd);
-      } catch {
-        /* best-effort */
-      }
-    }
-  }
+  let lastAt = null;
+  const scan = scanEventsBackwards({
+    filePath: file,
+    chunkBytes: TAIL_CHUNK_BYTES,
+    budgetMs: EVOLVE_SCAN_BUDGET_MS,
+    // Cheap substring pre-filter before JSON.parse — the property the previous
+    // hand-rolled scan was written for, kept here rather than re-derived.
+    filter: EVOLVE_EVENT,
+    onRecord: (rec) => {
+      if (rec?.event !== EVOLVE_EVENT) return false;
+      lastAt = typeof rec.timestamp === 'string' ? rec.timestamp : null;
+      return true;
+    },
+  });
+  if (scan.unreadable.length > 0) return { ok: false, lastAt: null, truncated: false };
+  return { ok: true, lastAt, truncated: scan.truncated };
 }
 
 /**
@@ -302,7 +296,9 @@ export async function computeMaintenanceDue(opts = {}) {
   } else {
     // --- evolve (S1) -------------------------------------------------------
     const evolve = readLastEvolveRun(repoRoot);
-    if (!evolve.ok) {
+    // `truncated` is NOT "not found": a walk that ran out of budget proves
+    // nothing about the lines it never reached (#1414).
+    if (!evolve.ok || evolve.truncated) {
       undeterminable.push('evolve');
     } else if (evolve.lastAt === null && nudge.activeLearnings >= MAINTENANCE_MIN_LEARNINGS) {
       markDue('evolve', `never, ${nudge.activeLearnings} active learnings`);
@@ -311,7 +307,9 @@ export async function computeMaintenanceDue(opts = {}) {
     // --- reconcile (S3) ----------------------------------------------------
     if (nudge.nudge === true) {
       // HR-106: report what the rule JUDGED. `computeReconcileNudge` nudges on
-      // a BACKLOG (eligible-unmaterialized learnings), never on a date — so
+      // a BACKLOG — rule-eligible learnings minus those already materialized
+      // in the sidecar or `.claude/rules/` (`countReconcileBacklog`, #1380;
+      // before #1380 it counted all eligible ones) — never on a date — so
       // printing `lastRunAt` here put today's date next to the word "due" and
       // read as "last run today and already due again". Measured 2026-09-09
       // (learning 013a45ba): with 108 learnings capped under
@@ -391,6 +389,39 @@ export async function computeMaintenanceDue(opts = {}) {
     undeterminable.push('pending-sidecar');
   }
 
+  // --- generated-rules-expiring (S7) ---------------------------------------
+  // The predicate and the population both come from `instruction-budget-guard`,
+  // which is where the generated corpus is DEFINED (its byte ceiling judges the
+  // same set). A local re-implementation would be a second definition of
+  // "machine-generated" that agrees only until one of the two is edited.
+  try {
+    const listed = listMachineGeneratedRules({ repoRoot });
+    if (!listed.ok) {
+      // The directory is there but unreadable — not knowing is not clean.
+      undeterminable.push('generated-rules-expiring');
+    } else {
+      const expiring = listed.rules
+        .map((r) => ({ ...r, days: daysUntilGeneratedRuleExpiry({ meta: r.meta, now }) }))
+        .filter((r) => r.days !== null && r.days <= GENERATED_RULE_EXPIRY_HORIZON_DAYS)
+        .sort((a, b) => a.days - b.days);
+      if (expiring.length > 0) {
+        // HR-106: name the files and the dates the verdict was computed from —
+        // the operator has to open exactly those files to repair this.
+        // HR-106 again, one step further: name the REPAIR, not only the
+        // finding. The sweep (#1377) is the mechanical half — prose out, the
+        // provenance pair kept as `markers only` — and an operator who is told
+        // only which files expired has to rediscover that the command exists.
+        markDue(
+          'generated-rules-expiring',
+          `${expiring.map((r) => `${r.file} ${r.expiresAt}`).join(', ')} → ` +
+            'node scripts/sweep-expired-rules.mjs (dry-run first)',
+        );
+      }
+    }
+  } catch {
+    undeterminable.push('generated-rules-expiring');
+  }
+
   return {
     due,
     // HR-106: the denominator counts the signals this host actually EVALUATED.