session-orchestrator 5.3.0 → 5.5.0

package/scripts/lib/events-retention-banner.mjs

@@ -0,0 +1,393 @@
+/**
+ * events-retention-banner.mjs — session-start probe: does the rotated events
+ * ledger still hold the TIME WINDOW its readers need? (#1401 part 3, variant a)
+ *
+ * ## Why this exists
+ *
+ * `.orchestrator/metrics/events.jsonl` rotates into
+ * `_archive/events-<firstTs>_<lastTs>.jsonl`, and `events-rotation.max-backups`
+ * bounds the NUMBER of archives kept (`events-rotation.mjs` `pruneArchives`).
+ * The readers of the rotated ledger need a TIME window instead. Count and time
+ * are different units (`.claude/rules/host-resources.md` § HR-103), so nothing
+ * noticed when a high write rate made "five archives" mean "less history than
+ * a reader reads": the pruned records simply stopped existing.
+ *
+ * Each reader declares its need as `REQUIRED_EVENTS_WINDOW_DAYS` beside its call
+ * to `readEventsWithRotations(`, `scanEventsBackwards(` or
+ * `listEventSourcesNewestFirst(` — a finite number of days, or `null` when no
+ * day count bounds its question (it then cannot set a retention floor, and its
+ * declaration comment states what a cut history does to its answer). This probe
+ * takes the MAX of the finite declarations and compares it against the span
+ * the retained ledger covers. No new Session Config key: it reads the existing
+ * `events-rotation.max-backups` from the config the runner passes.
+ *
+ * ## When it warns (HR-101 — a signal may only warn if it is rare)
+ *
+ * Only when the archive ring is FULL (`archives >= max-backups`). Below that
+ * the rotator prunes nothing under the current config, so the ledger only
+ * grows — a two-hour-old repo covering two hours is not "short retention", and
+ * judging it so would fire on every young repo's start.
+ *
+ * "Not full" does not mean "never pruned": after `max-backups` is RAISED, the
+ * archives pruned under the old, smaller ring stay gone. The oldest retained
+ * archive then opens with a rotation record whose `archived_as` names a
+ * predecessor that no longer exists — that is the hole, and the silent
+ * coverage figure then starts at the oldest archive exactly as on a full ring,
+ * never at a legacy `events.jsonl.N` older than the hole.
+ *
+ * ## Rare vs. broken (HR-105, #1489 item 2)
+ *
+ * Measured 2026-10-02: 4 of 35 fleet ledgers hold any archive, at most 3 at
+ * `max-backups: 5`, so the warning has never fired — and a warning that never
+ * fires looks the same whether it is rare or dead. Every MEASURED answer
+ * therefore carries the measurement, warn or not: `coverageDays`,
+ * `oldestEventAt`, `requiredDays`/`requiredBy`, `archives`, `maxBackups`.
+ * `coverageDays` is now minus the oldest archive's start on a FULL ring — the
+ * span the verdict judges — and below it when that archive's predecessor is
+ * gone (see above); otherwise now minus the oldest stamp of any source
+ * (archives, legacy ring, active file), where nothing was pruned.
+ * The registry entry's `telemetry` (`session-start-probes.mjs`) persists
+ * `coverage_days`, `archives`, `max_backups` and `required_days` as `measure`
+ * on this probe's element of `orchestrator.probes.completed`; `oldestEventAt`
+ * and `requiredBy` reach the caller only.
+ *
+ * ## Three states, never two
+ *
+ *   - **not measured** — no live ledger and no `ARCHIVE_NAME_RE` archive in
+ *     `_archive/` (absent, empty, or holding only foreign files):
+ *     `{severity:'ok', kind:'not-measured', reason:'no-events-ledger'}`. The
+ *     registry's precondition (`hasRotationArchive` in
+ *     `session-start-probes.mjs`) lists `_archive/` the same way and skips
+ *     exactly these inputs, so the runner records them as `skipped`, never as
+ *     `ran-clean` — which is what severity ok would otherwise become.
+ *   - **unmeasurable** — `_archive/` exists but cannot be listed, a reader's
+ *     declaration cannot be read, the oldest retained stamp lies after now
+ *     (a future-dated archive or a clock set back — the span would be
+ *     negative), or no source carries a stamp at all (no archive, and no
+ *     parseable `timestamp` in the head of the active file or a legacy-ring
+ *     file — #1498: it answered `ring-not-full` with `coverageDays: null` and
+ *     recorded as `ran-clean`): `{severity:'warn', degraded:true}`. An
+ *     unreadable source must never read as "retention is fine".
+ *   - **measured** — `{severity:'ok', kind:'ring-not-full'|'no-finite-window'|'covered', …}`
+ *     or `{severity:'warn', kind:'retention-short', message, …}`.
+ *
+ * Cost: two `readdirSync` of `_archive/` per session start (the registry
+ * precondition, then this probe), below a full ring one ≤64 KiB head read of
+ * the oldest archive (for its rotation record) and — unless that shows a
+ * pruned predecessor — of the active file and of each legacy-ring file, and — on EVERY measured start,
+ * before the ring check, because `requiredDays` is part of the silent
+ * measurement — the import of every reader module to read its declaration:
+ * 20-28 ms cold for all seven in a fresh process (measured 2026-10-02, load
+ * average ~8); two of them are session-start probes and two the SessionStart
+ * backfill, already loaded in that process. So a reader module that fails to import degrades this probe on
+ * every start, not only on a full ring.
+ *
+ * @module scripts/lib/events-retention-banner
+ */
+
+import { closeSync, existsSync, openSync, readSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+
+import { ARCHIVE_DIR_NAME, ARCHIVE_NAME_RE, LEGACY_RING_MAX, ROTATION_EVENT } from './events-schema.mjs';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/** `_parseEventsRotation`'s own default (`scripts/lib/config/events-rotation.mjs`). */
+const DEFAULT_MAX_BACKUPS = 5;
+
+/**
+ * How much of a ledger file's head is read for its first timestamp. NAMED
+ * CEILING (BV-004): one record is ~300 B in this repo's ledger, so 64 KiB holds
+ * hundreds; a file whose first 64 KiB carry no parseable `timestamp` reports
+ * no stamp rather than a guessed one.
+ */
+const HEAD_BYTES = 64 * 1024;
+
+/**
+ * Every module that reads the rotated ledger. Census 2026-10-02 @ `84c107a1`:
+ * `rg -n "readEventsWithRotations\(|scanEventsBackwards\(|listEventSourcesNewestFirst\(" --glob '!tests/**' scripts hooks skills`
+ * → 6 call sites beside the definitions in `events.mjs` (and its internal
+ * `listEventSourcesNewestFirst` call); the seventh, `session-close-backfill`,
+ * joined with #1498. A test re-runs that census, so an eighth reader cannot
+ * join unlisted.
+ */
+export const EVENTS_WINDOW_READERS = Object.freeze([
+  { label: 'eval/engine', spec: './eval/engine.mjs' },
+  { label: 'telemetry/sync', spec: './telemetry/sync.mjs' },
+  { label: 'tmux-layout/telemetry-stats', spec: './tmux-layout/telemetry-stats.mjs' },
+  { label: 'maintenance-due-banner', spec: './maintenance-due-banner.mjs' },
+  { label: 'instruction-budget-guard', spec: './instruction-budget-guard.mjs' },
+  { label: 'backfill-abandoned-sessions', spec: '../backfill-abandoned-sessions.mjs' },
+  { label: 'session-close-backfill', spec: './session-close-backfill.mjs' },
+]);
+
+/**
+ * Epoch ms of the START of an archive's range, from its name alone. An
+ * `unknown` first stamp falls back to the LAST stamp — a later instant, so the
+ * covered span is understated and the probe errs toward reporting.
+ *
+ * Total over `ARCHIVE_NAME_RE` matches, the only names it is given: the regex
+ * guarantees two digit stamps, and `Date.UTC` normalizes an out-of-range field
+ * (month 13 → January of the next year) instead of returning NaN. The NaN
+ * return exists only to type the regex miss; no caller can reach it.
+ *
+ * @param {string} name — matches `ARCHIVE_NAME_RE`
+ * @returns {number} epoch ms; NaN only for a name outside `ARCHIVE_NAME_RE`
+ */
+function archiveStartMs(name) {
+  const m = /^events-(\d{8}T\d{6}Z|unknown)_(\d{8}T\d{6}Z)/.exec(name);
+  if (!m) return Number.NaN;
+  const stamp = m[1] === 'unknown' ? m[2] : m[1];
+  const p = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z$/.exec(stamp);
+  return p ? Date.UTC(+p[1], +p[2] - 1, +p[3], +p[4], +p[5], +p[6]) : Number.NaN;
+}
+
+/**
+ * The parseable JSON records within the first {@link HEAD_BYTES} of `file`, in
+ * file order; `[]` when absent or unreadable. Malformed lines — and the partial
+ * last line of the head — are skipped, never guessed at.
+ *
+ * @param {string} file
+ * @returns {Array<*>}
+ */
+function headRecords(file) {
+  let fd;
+  let text = '';
+  try {
+    fd = openSync(file, 'r');
+    const buf = Buffer.alloc(HEAD_BYTES);
+    const n = readSync(fd, buf, 0, HEAD_BYTES, 0);
+    text = buf.subarray(0, n).toString('utf8');
+  } catch {
+    /* absent or unreadable — no records from this file */
+  } finally {
+    if (fd !== undefined) {
+      try {
+        closeSync(fd);
+      } catch {
+        /* best-effort */
+      }
+    }
+  }
+  const records = [];
+  for (const line of text.split('\n')) {
+    try {
+      records.push(JSON.parse(line));
+    } catch {
+      /* malformed, or the partial last line of the head */
+    }
+  }
+  return records;
+}
+
+/**
+ * Epoch ms of the first parseable `timestamp` within the head of `file` — the
+ * file's oldest event, since every ledger file is append-ordered. NaN when
+ * absent, unreadable, or stampless: the caller then has no stamp from this
+ * file, never a guessed one.
+ *
+ * @param {string} file
+ * @returns {number}
+ */
+function firstTimestampMs(file) {
+  for (const rec of headRecords(file)) {
+    const ms = Date.parse(rec?.timestamp);
+    if (Number.isFinite(ms)) return ms;
+  }
+  return Number.NaN;
+}
+
+/**
+ * Was history pruned before `oldest`, the oldest retained archive? Its head
+ * carries the rotation record written when its predecessor was archived, and
+ * that record's `archived_as` names the predecessor: an archive name absent
+ * from `names` was pruned — under a smaller ring, before `max-backups` was
+ * raised — or deleted. `false` when the head holds no rotation record: the
+ * hole then goes unseen, it is never invented.
+ *
+ * Named ceiling (BV-004, #1498). A head without a rotation record is the FIRST
+ * archive a ledger ever wrote (its file predates any rotation, and the legacy
+ * ring wrote none) — no archive can have been pruned before it, so nothing is
+ * missed there. The tombstone is appended right after the rename, so it sits on
+ * the first lines, far inside {@link HEAD_BYTES}. The blind case is a later
+ * archive whose tombstone was never written (`maybeRotate` → `recordWritten:
+ * false`) AND whose predecessor is gone. Measured 2026-10-02 over the 5 fleet
+ * `_archive/` dirs: 4 of 4 first archives carry no tombstone, 2 of 2 later
+ * archives carry it on line 0. Revisit if a census finds a later archive
+ * without one.
+ *
+ * @param {string} archiveDir
+ * @param {string} oldest — a member of `names`
+ * @param {string[]} names — the retained `ARCHIVE_NAME_RE` archives
+ * @returns {boolean}
+ */
+function predecessorPruned(archiveDir, oldest, names) {
+  const rotation = headRecords(path.join(archiveDir, oldest)).find((r) => r?.event === ROTATION_EVENT);
+  if (typeof rotation?.archived_as !== 'string') return false;
+  const predecessor = path.basename(rotation.archived_as);
+  return ARCHIVE_NAME_RE.test(predecessor) && !names.includes(predecessor);
+}
+
+/**
+ * The largest finite window any reader declares, with the reader naming it.
+ *
+ * @param {ReadonlyArray<{label: string, spec: string}>} readers
+ * @returns {Promise<{days: number|null, by: string|null}>}
+ * @throws when a reader cannot be imported or declares a non-window value
+ */
+async function maxRequiredWindow(readers) {
+  const values = await Promise.all(
+    readers.map(async (r) => {
+      const mod = await import(new URL(r.spec, import.meta.url).href);
+      const v = mod.REQUIRED_EVENTS_WINDOW_DAYS;
+      if (v !== null && !(typeof v === 'number' && Number.isFinite(v) && v > 0)) {
+        throw new Error(`${r.label} declares no REQUIRED_EVENTS_WINDOW_DAYS`);
+      }
+      return { days: v, by: r.label };
+    }),
+  );
+  let best = { days: null, by: null };
+  for (const v of values) {
+    if (v.days !== null && (best.days === null || v.days > best.days)) best = v;
+  }
+  return best;
+}
+
+/**
+ * Compare the retained events ledger's time span against the window its
+ * readers need. Never throws; never blocks.
+ *
+ * @param {object} opts
+ * @param {string} opts.repoRoot
+ * @param {object} [opts.config] — parsed Session Config (`events-rotation.max-backups`)
+ * @param {number} [opts.now=Date.now()] — injectable clock, epoch ms
+ * @returns {Promise<null|{severity: 'ok'|'warn', kind: string, message?: string,
+ *   degraded?: boolean, reason?: string, coverageDays?: number,
+ *   oldestEventAt?: string, requiredDays?: number|null, requiredBy?: string|null,
+ *   archives?: number, maxBackups?: number}>} `null` only without a `repoRoot`.
+ */
+export async function checkEventsRetention({ repoRoot, config, now = Date.now() } = {}) {
+  if (!repoRoot || typeof repoRoot !== 'string') return null;
+  const metricsDir = path.join(repoRoot, '.orchestrator', 'metrics');
+  const archiveDir = path.join(metricsDir, ARCHIVE_DIR_NAME);
+  const activePath = path.join(metricsDir, 'events.jsonl');
+  const nowMs = typeof now === 'number' && Number.isFinite(now) ? now : Date.now();
+
+  let names;
+  try {
+    names = readdirSync(archiveDir).filter((n) => ARCHIVE_NAME_RE.test(n));
+  } catch (err) {
+    if (err?.code !== 'ENOENT') {
+      return {
+        severity: 'warn',
+        degraded: true,
+        kind: 'unmeasurable',
+        message: `⚠ events-retention: could not list ${ARCHIVE_DIR_NAME}/ (${err?.code ?? 'error'}) — retention span not measured, which is not the same as covered.`,
+      };
+    }
+    names = [];
+  }
+  // Mirrored by the registry precondition, which skips these inputs before the
+  // runner could record this severity-ok answer as `ran-clean`.
+  if (names.length === 0 && !existsSync(activePath)) {
+    return { severity: 'ok', kind: 'not-measured', reason: 'no-events-ledger' };
+  }
+
+  let required;
+  try {
+    required = await maxRequiredWindow(EVENTS_WINDOW_READERS);
+  } catch (err) {
+    return {
+      severity: 'warn',
+      degraded: true,
+      kind: 'unmeasurable',
+      message: `⚠ events-retention: required window not readable (${String(err?.message ?? err).slice(0, 120)}) — retention span not judged, which is not the same as covered.`,
+    };
+  }
+
+  const raw = config?.['events-rotation']?.['max-backups'];
+  const maxBackups = Number.isInteger(raw) && raw >= 1 ? raw : DEFAULT_MAX_BACKUPS;
+  const ringFull = names.length >= maxBackups;
+
+  // A FULL ring is judged on its archives alone. The rotator prunes archives
+  // but never the legacy ring, so a legacy `events.jsonl.N` from before the
+  // migration outlives the pruned archives and its stamp would span the hole
+  // they left (#1489 review MED-1: a `.1` from April turned 20 hours of
+  // contiguous history into "173.5d, covered"). Below a full ring the same
+  // hole exists when an archive was pruned under an earlier, smaller ring
+  // (`max-backups` raised since): the oldest archive's rotation record names a
+  // predecessor that is gone. Only without such a hole does every source
+  // count toward the silent coverage figure.
+  const oldestArchive = names.reduce(
+    (a, b) => (a === null || archiveStartMs(b) < archiveStartMs(a) ? b : a),
+    null,
+  );
+  const holeBeforeArchives = ringFull || (oldestArchive !== null && predecessorPruned(archiveDir, oldestArchive, names));
+  const starts = [
+    ...names.map(archiveStartMs),
+    ...(holeBeforeArchives
+      ? []
+      : [
+          ...Array.from({ length: LEGACY_RING_MAX }, (_, i) => `${activePath}.${i + 1}`)
+            .filter((p) => existsSync(p))
+            .map(firstTimestampMs),
+          firstTimestampMs(activePath),
+        ]),
+  ].filter(Number.isFinite);
+  const oldestMs = starts.length > 0 ? Math.min(...starts) : Number.NaN;
+
+  // Every retained source dated after now — a future-dated archive, or a clock
+  // set back — makes the span negative. That is no measurement, and an
+  // unmeasured span must never record as clean, so it degrades like an
+  // unreadable source instead of persisting a negative `coverage_days`.
+  if (oldestMs > nowMs) {
+    return {
+      severity: 'warn',
+      degraded: true,
+      kind: 'unmeasurable',
+      message: `⚠ events-retention: the oldest retained event is dated ${new Date(oldestMs).toISOString()}, after now — retention span not measured, which is not the same as covered.`,
+    };
+  }
+
+  // No stamp at all (#1498) — reachable only without archives (every archive
+  // dates itself by name), when the first 64 KiB of the active file and of
+  // every legacy-ring file carry no parseable `timestamp`. That span was not
+  // measured; answered `ring-not-full` with `coverageDays: null` it recorded
+  // as `ran-clean`. Census 2026-10-02: 0 of 37 fleet `events.jsonl` heads are
+  // stampless, so this degrades rarely (HR-101) — and visibly (HR-105).
+  if (!Number.isFinite(oldestMs)) {
+    return {
+      severity: 'warn',
+      degraded: true,
+      kind: 'unmeasurable',
+      message: `⚠ events-retention: no parseable timestamp in the first ${HEAD_BYTES / 1024} KiB of events.jsonl (or of a legacy events.jsonl.N) and no ${ARCHIVE_DIR_NAME}/ archive — retention span not measured, which is not the same as covered.`,
+    };
+  }
+
+  const measured = {
+    coverageDays: (nowMs - oldestMs) / DAY_MS,
+    oldestEventAt: new Date(oldestMs).toISOString(),
+    requiredDays: required.days,
+    requiredBy: required.by,
+    archives: names.length,
+    maxBackups,
+  };
+
+  // Ring not full ⇒ nothing is pruned under this config, so the retained
+  // ledger only grows; any older hole is already excluded from the figure
+  // above. Never a warning here — see the module header (HR-101).
+  if (!ringFull) return { severity: 'ok', kind: 'ring-not-full', ...measured };
+  if (required.days === null) return { severity: 'ok', kind: 'no-finite-window', ...measured };
+  // Finite here: the ring is full, so `names` is non-empty and
+  // `archiveStartMs` is total over `ARCHIVE_NAME_RE` matches.
+  if (measured.coverageDays >= required.days) return { severity: 'ok', kind: 'covered', ...measured };
+  const cov = measured.coverageDays.toFixed(1);
+  return {
+    severity: 'warn',
+    kind: 'retention-short',
+    // Names what the rule judged (HR-106): the measured span against the
+    // reader's DECLARED window — not a claim about how the reader reads.
+    message: `⚠ events-retention: the rotated events ledger covers ${cov}d (${names.length} archives at events-rotation.max-backups: ${maxBackups}), less than the ${required.days}d window ${required.by} declares as REQUIRED_EVENTS_WINDOW_DAYS — events older than ${cov}d are not retained; raise events-rotation.max-backups or max-size-mb.`,
+    ...measured,
+  };
+}

package/scripts/lib/events-rotation.mjs

@@ -6,7 +6,8 @@
  * synchronous fs calls (the hook is short-lived; async adds complexity).
  *
  * Issue #251 (CRITICAL). Rotation fires only at session-start, not per-append —
- * per-append overhead is wasteful given ~6 KiB/day growth.
+ * a size check per append buys nothing when one 10 MiB file takes days to
+ * weeks to fill (measured growth: see {@link pruneArchives}).
  *
  * Rename safety (POSIX): atomic rename is safe with in-flight writers. Old fds
  * continue writing to the original inode (now the archive); new writers will
@@ -104,8 +105,9 @@ function uniqueArchivePath(dir, firstTs, lastTs) {
   const to = lastTs ? compactStamp(lastTs) : compactStamp(new Date().toISOString());
   const base = `events-${from}_${to}`;
   let candidate = path.join(dir, `${base}.jsonl`);
-  // Ceiling (BV-004): 999 same-range archives. Rotation fires 2-3x/year at the
-  // measured ~6 KiB/day growth, and the range is content-derived, so a second
+  // Ceiling (BV-004): 999 same-range archives. Rotation fires every ~52 days in
+  // this repo and every ~5 days in the busiest fleet repo (measured 2026-10-02,
+  // see `pruneArchives`), and the range is content-derived, so a second
   // collision already implies something is re-rotating identical content.
   // Revisit if a `pruned`-less archive dir is ever seen holding a `-3` suffix.
   for (let n = 2; existsSync(candidate); n += 1) {
@@ -122,8 +124,19 @@ function uniqueArchivePath(dir, firstTs, lastTs) {
  *
  * The cap is kept rather than dropped because `events-rotation.max-backups` is
  * a live, documented config key: a key whose reader silently stops enforcing it
- * is the "config key nobody produces" defect in reverse. At the measured
- * rotation rate `max-backups: 5` is roughly two years of history.
+ * is the "config key nobody produces" defect in reverse.
+ *
+ * What `max-backups: 5` retains, measured 2026-10-02 (line bytes summed per
+ * calendar day of each record's `timestamp`, via a `node` read of
+ * `.orchestrator/metrics/events.jsonl` and `_archive/`): this repo's active
+ * ledger grew 2,770,612 B over 13.7 days (2026-09-18 → 2026-10-02), i.e.
+ * ~202,570 B/day with a 1,207,177 B peak day; across 35 fleet ledgers the median
+ * active-file rate was 59,388 B/day, and the busiest repo averaged ~2.1 MB/day
+ * (43,978,706 B over 2026-09-11 → 2026-10-02) with a 10,248,010 B peak day.
+ * One archive holds ≥10 MiB, so five archives retain ~8.5 months here and ~3.5
+ * weeks in the busiest repo — not the "roughly two years" this comment used to
+ * claim from a ~6 KiB/day figure. Whether that suffices is judged per reader
+ * window by `events-retention-banner.mjs`.
  *
  * Only names matching {@link ARCHIVE_NAME_RE} are eligible, and the archive
  * just written is never a candidate. A failed unlink is swallowed: leaving one
@@ -221,7 +234,9 @@ export function maybeRotate({ logPath, maxSizeMb, maxBackups, enabled } = {}) {
 
     // Read BEFORE the rename: the content is what names the archive. Cost
     // ceiling (BV-004): one full read of a file at the rotation threshold —
-    // ~50 ms and ~40 MB transient at the default 10 MB cap, paid 2-3x/year.
+    // ~50 ms and ~40 MB transient at the default 10 MB cap, paid once per
+    // rotation (every ~52 days here, ~5 days in the busiest fleet repo —
+    // measured 2026-10-02, see `pruneArchives`).
     // Revisit if `max-size-mb` is ever raised past ~100.
     const { records, malformedLines } = parseEventLines(readFileSync(logPath, 'utf8'));
     const { firstTs, lastTs } = summarizeEventRecords(records);

package/scripts/lib/events.mjs

@@ -388,7 +388,11 @@ function waveForRecord(root, attribution) {
  *   metrics/events.jsonl` instead of the module-level `SO_PROJECT_DIR` default
  *   (#941). Ignored when `opts.filePath` is given (explicit path wins). This is
  *   the clean interface replacing the hand-built `join(repoRoot, …)` recipes that
- *   used to open-code this destination at each call-site.
+ *   used to open-code this destination at each call-site. A relative or empty
+ *   `repoRoot` is refused with one stderr WARN and nothing is written (no line,
+ *   no directory, no webhook): joining it would land relative to the working
+ *   directory — the incident class where an unset env var produced
+ *   `undefined/…/.orchestrator/metrics/events.jsonl` under the cwd.
  * @returns {Promise<void>}
  */
 export async function emitEvent(type, payload = {}, opts = {}) {
@@ -434,11 +438,26 @@ export async function emitEvent(type, payload = {}, opts = {}) {
 
   // Ensure the destination directory exists before appending. Resolution order:
   //   1. explicit opts.filePath (a pre-resolved path — #611)
-  //   2. opts.repoRoot → <repoRoot>/.orchestrator/metrics/events.jsonl (#941)
+  //   2. opts.repoRoot → <repoRoot>/.orchestrator/metrics/events.jsonl (#941),
+  //      or refused when relative/empty (WARN, no write — see below)
   //   3. the SO_PROJECT_DIR default (unchanged for 2-arg callers)
   // eventsFilePath(undefined) falls through to its SO_PROJECT_DIR default, so a
   // caller passing neither behaves EXACTLY as before (additive) — except under
   // the test-only EVENTS_LEDGER_SANDBOX_ENV seam, which only 3. honours.
+  // An explicit filePath is never second-guessed. A defined repoRoot that is not
+  // absolute would be joined relative to the cwd, so it is refused: WARN and
+  // return (hooks must never throw). The value itself is not printed — it may
+  // carry a host-local path.
+  if (
+    opts.filePath === undefined &&
+    opts.repoRoot !== undefined &&
+    (typeof opts.repoRoot !== 'string' || !path.isAbsolute(opts.repoRoot))
+  ) {
+    process.stderr.write(
+      `[events] ${String(type)} not emitted: opts.repoRoot is not an absolute path; refusing to write relative to the working directory.\n`,
+    );
+    return;
+  }
   const filePath = opts.filePath ?? eventsFilePath(opts.repoRoot);
   await fs.mkdir(path.dirname(filePath), { recursive: true });
   await fs.appendFile(filePath, line, 'utf8');
@@ -807,7 +826,13 @@ export function listEventSourcesNewestFirst(opts = {}) {
  *   a stop, the walk ends with `truncated: true` — which is NOT "not found":
  *   the caller must report undeterminable, never a clean negative.
  * @returns {{stopped: boolean, truncated: boolean, malformed_lines: number,
- *            sources: string[], unreadable: string[]}}
+ *            sources: string[], unreadable: string[], gaps: object[]}} `gaps`
+ *   (#1489): every rotation tombstone the walk passed, on any line and
+ *   regardless of `filter`, whose archive is not one of this walk's sources — pruned
+ *   (`missing-archive`) or renamed out of `ARCHIVE_NAME_RE`
+ *   (`unindexed-archive`), the same two kinds and fields
+ *   {@link readEventsWithRotations} reports. Non-empty ⇒ the history the walk
+ *   read is CUT, so a walk that found nothing has not proven "never happened".
  */
 export function scanEventsBackwards(opts = {}) {
   const { onRecord, filter, budgetMs } = opts;
@@ -821,16 +846,58 @@ export function scanEventsBackwards(opts = {}) {
 
   const scanned = [];
   const unreadable = [];
+  const gaps = [];
   let malformed = 0;
   let stopped = false;
   let truncated = false;
 
+  const sources = listEventSourcesNewestFirst(opts);
+  const listed = new Set(sources.map((s) => s.path));
+  // Same construction as `discoverArchives`, so a listed archive matches by string.
+  const ownArchiveDir = path.join(
+    path.dirname(opts.filePath ?? eventsFilePath(opts.repoRoot)),
+    ARCHIVE_DIR_NAME,
+  );
+
+  /**
+   * Every rotation tombstone the walk passes is checked, on whatever line it
+   * sits — the semantics of {@link readEventsWithRotations}, which checks every
+   * rotation record of every source. Not only first lines (#1489 review
+   * LOW-2): `maybeRotate` renames, prunes, THEN appends the tombstone, from an
+   * async SessionStart hook, so a concurrent append can land first and push it
+   * to line 2. Called BEFORE the caller's `filter`, which names another event
+   * and would otherwise hide the cut. Resolved by basename against this
+   * ledger's own `_archive/`, never by the absolute provenance value (#1411).
+   */
+  const noteCut = (line, source) => {
+    if (!line.includes(ROTATION_EVENT)) return;
+    let record;
+    try {
+      record = JSON.parse(line);
+    } catch {
+      return; // counted by `consume` like every other malformed line
+    }
+    const target = record?.event === ROTATION_EVENT ? record.archived_as : null;
+    if (typeof target !== 'string' || target.length === 0) return;
+    const sibling = path.join(ownArchiveDir, path.basename(target));
+    if (listed.has(sibling)) return;
+    gaps.push({
+      kind: existsSync(sibling) ? 'unindexed-archive' : 'missing-archive',
+      path: sibling,
+      archived_as: target,
+      first_ts: record.first_ts ?? null,
+      last_ts: record.last_ts ?? null,
+      reported_by: source.path,
+    });
+  };
+
   /** @returns {boolean} true ⇒ the caller accepted a record; stop everything. */
   const consume = (block, source) => {
     const lines = block.toString('utf8').split('\n');
     for (let i = lines.length - 1; i >= 0; i -= 1) {
       const line = lines[i];
       if (!line) continue;
+      noteCut(line, source);
       if (typeof filter === 'string' && !line.includes(filter)) continue;
       let record;
       try {
@@ -844,7 +911,7 @@ export function scanEventsBackwards(opts = {}) {
     return false;
   };
 
-  for (const source of listEventSourcesNewestFirst(opts)) {
+  for (const source of sources) {
     if (stopped || truncated) break;
     if (outOfTime()) {
       truncated = true;
@@ -896,5 +963,5 @@ export function scanEventsBackwards(opts = {}) {
     }
   }
 
-  return { stopped, truncated, malformed_lines: malformed, sources: scanned, unreadable };
+  return { stopped, truncated, malformed_lines: malformed, sources: scanned, unreadable, gaps };
 }