session-orchestrator 5.1.0 → 5.3.0

package/scripts/lib/events.mjs

@@ -39,7 +39,18 @@
  * 0.0961 ms/call.
  */
 
-import { promises as fs, existsSync, readFileSync } from 'node:fs';
+import {
+  promises as fs,
+  closeSync,
+  existsSync,
+  fstatSync,
+  openSync,
+  readFileSync,
+  readSync,
+  readdirSync,
+  realpathSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { getProjectDir, SO_SHARED_DIR } from './platform.mjs';
 import { readLock } from './session-lock.mjs';
@@ -49,8 +60,14 @@ import {
   readProcessLocalSessionIds,
 } from './session-identity/own-session.mjs';
 import {
+  ARCHIVE_DIR_NAME,
+  ARCHIVE_NAME_RE,
   EventValidationError,
+  LEGACY_RING_MAX,
+  ROTATION_EVENT,
+  parseEventLines,
   stampEventSchemaVersion,
+  summarizeEventRecords,
   validateEventRecord,
 } from './events-schema.mjs';
 
@@ -58,6 +75,67 @@ import {
 // Public API
 // ---------------------------------------------------------------------------
 
+/**
+ * Test seam (#1397 item 11): the absolute path of a sandbox ledger that the
+ * DEFAULT destination is redirected to whenever that default would land outside
+ * the OS temp root. Set by `tests/setup/events-ledger-guard.mjs` in every
+ * vitest worker, and inherited by every child process the suite spawns — which
+ * is the point: the default resolves via `SO_PROJECT_DIR` (env, else a walk up
+ * from the cwd), so a spawned script with `cwd = <repo>` otherwise appended
+ * synthetic records, stamped with the LIVE session id, to the real ledger.
+ * Nothing in production sets it.
+ */
+export const EVENTS_LEDGER_SANDBOX_ENV = 'SO_EVENTS_LEDGER_SANDBOX';
+
+/**
+ * OS temp root in both spellings (macOS `os.tmpdir()` is `/var/folders/…`, a
+ * symlink to `/private/var/folders/…`; `process.cwd()` inside it reports the
+ * canonical form). Only called while the sandbox variable is set.
+ * @returns {string[]}
+ */
+function tmpRoots() {
+  const raw = path.resolve(tmpdir());
+  let real = raw;
+  try { real = realpathSync(raw); } catch { /* keep the raw spelling */ }
+  return real === raw ? [raw] : [raw, real];
+}
+
+/** @param {string} p @param {string[]} roots @returns {boolean} */
+function isUnderAny(p, roots) {
+  const abs = path.resolve(p);
+  return roots.some((r) => abs === r || abs.startsWith(r + path.sep));
+}
+
+/**
+ * Apply the sandbox redirect to a DEFAULT-resolved ledger path.
+ *
+ * Rule: redirect only a default that would leave the temp root. A fixture
+ * project dir under tmp (`CLAUDE_PROJECT_DIR=<mkdtemp>`, or `cwd: <mkdtemp>`) is
+ * where a test EXPECTS its records — measured 2026-09-19 @ d92c2ca4, 38 test
+ * files set a project-dir env var and read `events.jsonl` back — so it is kept
+ * byte-identical. Keying on "outside tmp" rather than on "is this repo's ledger"
+ * is deliberate: an allow-list of protected roots fails open on the root it did
+ * not name (a sibling repo, a copied plugin tree), this invariant does not.
+ *
+ * Why the sandbox value must itself sit under the temp root: a stray or
+ * malformed export in an operator's shell must never be able to aim real
+ * telemetry at another tracked file. A value outside tmp, a relative value, or
+ * a whitespace-only value is IGNORED → production resolution, unchanged. What
+ * this cannot prevent (BV-004 ceiling): a stray export that DOES point under
+ * tmp diverts a real session's records there. The name marks it a test seam;
+ * revisit if it is ever found set outside a vitest process.
+ *
+ * @param {string} defaultPath
+ * @returns {string}
+ */
+function sandboxedDefault(defaultPath) {
+  const sandbox = (process.env[EVENTS_LEDGER_SANDBOX_ENV] || '').trim();
+  if (!sandbox || !path.isAbsolute(sandbox)) return defaultPath;
+  const roots = tmpRoots();
+  if (!isUnderAny(sandbox, roots) || isUnderAny(defaultPath, roots)) return defaultPath;
+  return path.resolve(sandbox);
+}
+
 /**
  * Returns the absolute path to `.orchestrator/metrics/events.jsonl` under `repoRoot`.
  *
@@ -67,11 +145,17 @@ import {
  * CWD/env-resolved project — e.g. a unit test running the gate against a tmp
  * repo, which must NOT append synthetic records to the real fleet telemetry.
  *
+ * Only the zero-arg (default) form honours {@link EVENTS_LEDGER_SANDBOX_ENV};
+ * an explicit `repoRoot` is never redirected. Readers that resolve the default
+ * (session-start rotation) and raw writers that use it (the discovery-validator
+ * hook) therefore see the same sandbox `emitEvent()` writes to.
+ *
  * @param {string} [repoRoot=SO_PROJECT_DIR] — project root the events log lives under.
  * @returns {string}
  */
-export function eventsFilePath(repoRoot = getProjectDir()) {
-  return path.join(repoRoot, SO_SHARED_DIR, 'metrics', 'events.jsonl');
+export function eventsFilePath(repoRoot) {
+  if (repoRoot !== undefined) return path.join(repoRoot, SO_SHARED_DIR, 'metrics', 'events.jsonl');
+  return sandboxedDefault(path.join(getProjectDir(), SO_SHARED_DIR, 'metrics', 'events.jsonl'));
 }
 
 /**
@@ -352,8 +436,9 @@ export async function emitEvent(type, payload = {}, opts = {}) {
   //   1. explicit opts.filePath (a pre-resolved path — #611)
   //   2. opts.repoRoot → <repoRoot>/.orchestrator/metrics/events.jsonl (#941)
   //   3. the SO_PROJECT_DIR default (unchanged for 2-arg callers)
-  // eventsFilePath(undefined) falls through to its SO_PROJECT_DIR default param,
-  // so a caller passing neither behaves EXACTLY as before (additive).
+  // 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.
   const filePath = opts.filePath ?? eventsFilePath(opts.repoRoot);
   await fs.mkdir(path.dirname(filePath), { recursive: true });
   await fs.appendFile(filePath, line, 'utf8');
@@ -379,3 +464,437 @@ export async function emitEvent(type, payload = {}, opts = {}) {
     }).catch(() => {});
   }
 }
+
+// ---------------------------------------------------------------------------
+// Rotation-aware reading (#1401)
+// ---------------------------------------------------------------------------
+
+/**
+ * Read one JSONL source into a descriptor — never throws.
+ *
+ * @param {string} filePath
+ * @param {'active'|'archive'|'legacy-ring'} kind
+ * @returns {{path: string, kind: string, readable: boolean, records: object[],
+ *            malformed_lines: number, first_ts: string|null, last_ts: string|null,
+ *            error?: string}}
+ */
+function readEventSource(filePath, kind) {
+  let text;
+  try {
+    text = readFileSync(filePath, 'utf8');
+  } catch (err) {
+    return {
+      path: filePath,
+      kind,
+      readable: false,
+      records: [],
+      malformed_lines: 0,
+      first_ts: null,
+      last_ts: null,
+      error: err?.message ?? String(err),
+    };
+  }
+  const { records, malformedLines } = parseEventLines(text);
+  const { firstTs, lastTs } = summarizeEventRecords(records);
+  return {
+    path: filePath,
+    kind,
+    readable: true,
+    records,
+    malformed_lines: malformedLines,
+    first_ts: firstTs,
+    last_ts: lastTs,
+  };
+}
+
+/**
+ * Every archive belonging to `logPath`, in BOTH schemes.
+ *
+ * Reading the legacy `.1`..`.N` ring is not politeness towards old code — it is
+ * a live requirement: measured 2026-09-19, two fleet repos hold a ~10 MB
+ * `events.jsonl.1` written before #1401 switched the writer to `_archive/`. A
+ * reader that saw only the new scheme would drop that history and call the
+ * result complete.
+ *
+ * `unindexed` (#1423) names every OTHER `.jsonl` in that directory — a file the
+ * reader will NOT fold into the timeline because rotation did not write it.
+ * Reporting it is not the same as counting it as missing: this repo's own
+ * `_archive/` holds a hand-placed `events-worktree-vault-session-analysis-…`
+ * (80 records), and calling that a GAP would pin the ledger at
+ * `complete: false` forever, which is the instrument HR-101 calls broken. It is
+ * a NOTICE — visible, never a verdict.
+ *
+ * @param {string} logPath — absolute path of the ACTIVE log.
+ * @returns {{archives: string[], legacy: string[], ringHoles: number[], unindexed: string[]}}
+ */
+function discoverArchives(logPath) {
+  const dir = path.dirname(logPath);
+
+  const archives = [];
+  const unindexed = [];
+  const archiveDir = path.join(dir, ARCHIVE_DIR_NAME);
+  try {
+    for (const name of readdirSync(archiveDir).sort()) {
+      const abs = path.join(archiveDir, name);
+      if (ARCHIVE_NAME_RE.test(name)) archives.push(abs);
+      else if (name.endsWith('.jsonl')) unindexed.push(abs);
+    }
+  } catch {
+    /* no archive directory yet — not a gap, just nothing rotated here */
+  }
+
+  // The ring was contiguous BY CONSTRUCTION (each rotation shifted every slot
+  // up by one), so a hole between two present slots can only mean a backup was
+  // removed out of band. Slots above the highest present one are simply
+  // "not rotated that many times" and are not holes.
+  const present = [];
+  for (let i = 1; i <= LEGACY_RING_MAX; i += 1) {
+    if (existsSync(`${logPath}.${i}`)) present.push(i);
+  }
+  const highest = present.length > 0 ? present[present.length - 1] : 0;
+  const ringHoles = [];
+  for (let i = 1; i < highest; i += 1) {
+    if (!present.includes(i)) ringHoles.push(i);
+  }
+  return { archives, legacy: present.map((i) => `${logPath}.${i}`), ringHoles, unindexed };
+}
+
+/**
+ * Read the events ledger ACROSS rotation boundaries — active file plus every
+ * archive still on disk — in time order, reporting what is missing instead of
+ * silently returning less.
+ *
+ * ## Why this exists (#1401)
+ *
+ * Before it, nothing in `scripts/` or `hooks/` read a rotated backup at all
+ * (census 2026-09-19 @ `8f15f77b`: `rg -n 'jsonl\.1|jsonl\.[0-9]' scripts/ hooks/`
+ * excluding tests → zero code hits). Every window analysis therefore lost its
+ * whole history at each rotation, silently — which is what reduced the #1037
+ * guard-attribution join to 2 of 38 sessions.
+ *
+ * ## The three honesty rules
+ *
+ * 1. **A missing archive is a FINDING, not an empty result.** When a record in
+ *    a later file names `archived_as: X` and X is not on disk, that appears in
+ *    `gaps` with the range X covered, and `complete` is `false`. This is the
+ *    exact shape of the 2026-09-19 loss, and it is detectable only because the
+ *    rotation writes that pointer (see `events-rotation.mjs`) — an archive
+ *    deleted before #1401 left no trace and is undetectable by construction.
+ *    EXISTENCE IS NOT READING (#1423): the sibling counts only when it was an
+ *    actual SOURCE of this read. A file that exists beside the active log but
+ *    whose name misses `ARCHIVE_NAME_RE` is never read, so treating
+ *    `existsSync` as proof silenced the tombstone while its records stayed
+ *    out — that case is its own gap kind, `unindexed-archive`.
+ * 2. **Unreadable lines are COUNTED** (`malformed_lines`, per source and total).
+ *    A silently skipping JSONL parser turns a partial result into a clean
+ *    verdict.
+ * 3. **Order is by measured time, not by filename.** Sources are sorted on
+ *    their earliest parseable timestamp; records within a source keep file
+ *    (append) order. A source with no parseable timestamp sorts last rather
+ *    than being dropped.
+ * 4. **`complete` has THREE states, because the answer does (#1423).** `true` =
+ *    measured and whole, `false` = measured with a named gap, `null` = NOT
+ *    MEASURED: no source existed at all (no active file, no archive, no legacy
+ *    ring), so `events: []` is the absence of a ledger and not the absence of
+ *    events. `complete: true` on a repo with no ledger is the house failure
+ *    class "a missing measurement looks like zero".
+ *
+ * Separate from `gaps`, `notices` carries what was SEEN but deliberately not
+ * read — today only `unindexed-archive-file` (see {@link discoverArchives}).
+ * A notice never moves `complete`.
+ *
+ * CEILING (BV-004): every source is read fully into memory — at the default
+ * `max-size-mb: 10` / `max-backups: 5` that is up to ~60 MB transient. There is
+ * no windowing parameter because no caller has asked for one; revisit when a
+ * consumer needs a `since` filter or `max-size-mb` is raised past ~100.
+ *
+ * @param {string} [repoRoot] — project root; defaults exactly as
+ *   {@link eventsFilePath} does (and only the default form honours the test
+ *   sandbox seam).
+ * @param {object} [opts={}]
+ * @param {string} [opts.filePath] — override the active-log path outright.
+ * @returns {{events: object[], sources: object[], malformed_lines: number,
+ *            gaps: object[], notices: object[], complete: boolean|null,
+ *            active_path: string}}
+ */
+export function readEventsWithRotations(repoRoot, opts = {}) {
+  const activePath = opts.filePath ?? eventsFilePath(repoRoot);
+  const { archives, legacy, ringHoles, unindexed } = discoverArchives(activePath);
+
+  const sources = [
+    ...archives.map((p) => readEventSource(p, 'archive')),
+    ...legacy.map((p) => readEventSource(p, 'legacy-ring')),
+  ];
+  if (existsSync(activePath)) sources.push(readEventSource(activePath, 'active'));
+
+  // Time order across sources; undatable sources last, stable by path.
+  sources.sort((a, b) => {
+    const am = a.first_ts ? Date.parse(a.first_ts) : Infinity;
+    const bm = b.first_ts ? Date.parse(b.first_ts) : Infinity;
+    if (am !== bm) return am - bm;
+    return a.path < b.path ? -1 : a.path > b.path ? 1 : 0;
+  });
+
+  const gaps = [];
+  const onDisk = new Set(sources.map((s) => s.path));
+  // Same construction `discoverArchives` uses, so its unresolved entries in
+  // `onDisk` still match by string.
+  const ownArchiveDir = path.join(path.dirname(activePath), ARCHIVE_DIR_NAME);
+
+  // Rule 1 — every rotation tombstone must still point at a file.
+  for (const source of sources) {
+    for (const record of source.records) {
+      if (record?.event !== ROTATION_EVENT) continue;
+      const target = record.archived_as;
+      if (typeof target !== 'string' || target.length === 0) continue;
+      // #1411 — resolve the tombstone against THIS ledger's own `_archive/`,
+      // by BASENAME, and never against the absolute value it stores.
+      //
+      // The writer keeps `archived_as` absolute (`events-rotation.mjs` joins
+      // the repo root) and that value stays in the record as PROVENANCE. It is
+      // not a lookup key: a moved checkout, a clone, or a sibling git worktree
+      // — routine here — makes every tombstone name a path that does not exist
+      // in THIS tree, so the old exact comparison reported a phantom
+      // `missing-archive` for an archive sitting right beside the active file.
+      // Basename, not `realpath`: realpath cannot resolve a path that no longer
+      // exists, which IS the failure mode.
+      //
+      // ORDER (why the absolute value has no second chance): the sibling answer
+      // is consulted first, and an absolute hit would only be trustworthy while
+      // it pointed INSIDE this ledger's own archive dir — but any such path
+      // resolves to exactly the sibling path already tested, so once the
+      // sibling misses, an absolute hit can ONLY be a still-present OLD
+      // checkout. Honouring it would validate THIS ledger against a FOREIGN
+      // repo's archive: a silent false negative, worse than the phantom gap.
+      const sibling = path.join(ownArchiveDir, path.basename(target));
+      if (onDisk.has(sibling)) continue;
+      gaps.push({
+        // #1423 — THREE outcomes, not two: read (above), present-but-unread
+        // (here), gone (below). The middle one used to be silently folded into
+        // the first by `existsSync`, so a tombstone whose archive had been
+        // RENAMED out of `ARCHIVE_NAME_RE` reported `complete: true` while its
+        // records were absent from `events`.
+        kind: existsSync(sibling) ? 'unindexed-archive' : 'missing-archive',
+        path: sibling,
+        archived_as: target,
+        first_ts: record.first_ts ?? null,
+        last_ts: record.last_ts ?? null,
+        lines: record.lines ?? null,
+        size_before: record.size_before ?? null,
+        reported_by: source.path,
+        rotated_at: record.timestamp ?? null,
+      });
+    }
+  }
+
+  for (const slot of ringHoles) {
+    gaps.push({
+      kind: 'ring-hole',
+      archived_as: `${activePath}.${slot}`,
+      first_ts: null,
+      last_ts: null,
+      reported_by: activePath,
+    });
+  }
+
+  for (const source of sources) {
+    if (source.readable) continue;
+    gaps.push({
+      kind: 'unreadable-source',
+      archived_as: source.path,
+      first_ts: null,
+      last_ts: null,
+      reported_by: source.path,
+      error: source.error ?? null,
+    });
+  }
+
+  const events = [];
+  let malformed = 0;
+  for (const source of sources) {
+    events.push(...source.records);
+    malformed += source.malformed_lines;
+  }
+
+  return {
+    events,
+    sources: sources.map(({ records, ...rest }) => ({ ...rest, records: records.length })),
+    malformed_lines: malformed,
+    gaps,
+    notices: unindexed.map((p) => ({ kind: 'unindexed-archive-file', path: p })),
+    // Honesty rule 4: no source at all ⇒ NOT MEASURED (`null`), never a clean
+    // `true` over an empty read.
+    complete: sources.length === 0 ? null : gaps.length === 0,
+    active_path: activePath,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Streaming reads across rotations (#1414)
+// ---------------------------------------------------------------------------
+
+/**
+ * Default chunk for the streaming readers — 256 KiB, ~800 records in this
+ * repo's ledger.
+ *
+ * NAMED CEILING (BV-004): a line LONGER than one chunk is carried, never
+ * dropped, so the constant bounds memory and not correctness. REVISIT when one
+ * repo's `events.jsonl` passes 50 MB — at that size the backwards "never
+ * happened" walk needs an index rather than a scan.
+ */
+export const SCAN_CHUNK_BYTES = 256 * 1024;
+
+/**
+ * Every source of this ledger that EXISTS, NEWEST FIRST — without reading one
+ * byte of their contents (#1414).
+ *
+ * Order: the active file, then `_archive/` archives by name DESCENDING (the
+ * name encodes `first_ts`/`last_ts`, so lexical order is chronological), then
+ * the legacy ring ASCENDING (`.1` is the most recent backup, `.N` the oldest).
+ * Reverse the result for an oldest-first pass.
+ *
+ * Hand-placed files in `_archive/` that rotation did not write are NOT sources
+ * here, exactly as in {@link readEventsWithRotations} — one definition of "what
+ * belongs to this ledger", not two.
+ *
+ * @param {object} [opts={}]
+ * @param {string} [opts.filePath] — the ACTIVE log path; defaults as {@link eventsFilePath}.
+ * @param {string} [opts.repoRoot] — used only when `filePath` is absent.
+ * @returns {Array<{path: string, kind: 'active'|'archive'|'legacy-ring'}>}
+ */
+export function listEventSourcesNewestFirst(opts = {}) {
+  const activePath = opts.filePath ?? eventsFilePath(opts.repoRoot);
+  const { archives, legacy } = discoverArchives(activePath);
+  const out = [];
+  if (existsSync(activePath)) out.push({ path: activePath, kind: 'active' });
+  for (const p of [...archives].reverse()) out.push({ path: p, kind: 'archive' });
+  for (const p of legacy) out.push({ path: p, kind: 'legacy-ring' });
+  return out;
+}
+
+/**
+ * Walk the ledger BACKWARDS across rotation boundaries, newest record first,
+ * stopping at the first record the caller accepts (#1414).
+ *
+ * ## Why this exists
+ *
+ * `readEventsWithRotations` loads every source fully — up to ~60 MB transient
+ * at the default `max-size-mb: 10` × `max-backups: 5`. That is the right shape
+ * for a cold analysis and the wrong one for a session-start probe, so the two
+ * HOT-PATH readers (`maintenance-due-banner.mjs`, `backfill-abandoned-sessions.mjs`)
+ * stayed single-file and answered "never happened" from the active file alone.
+ * This reader gives them the whole history at a bounded memory cost.
+ *
+ * A record SPLIT across a chunk boundary is CARRIED, never parsed twice or
+ * dropped: the bytes before a chunk's first newline are the tail of a line
+ * whose head sits in the chunk not read yet. Splitting on the 0x0A byte is safe
+ * on UTF-8 (no continuation byte equals a newline), and the carry is joined as
+ * a BUFFER, so a multibyte character never splits either.
+ *
+ * @param {object} opts
+ * @param {string} [opts.filePath] — the ACTIVE log path; defaults as {@link eventsFilePath}.
+ * @param {string} [opts.repoRoot] — used only when `filePath` is absent.
+ * @param {number} [opts.chunkBytes={@link SCAN_CHUNK_BYTES}]
+ * @param {(record: object, source: {path: string, kind: string}) => boolean} opts.onRecord —
+ *   called with each PARSED record, newest first; returning `true` stops the walk.
+ * @param {string} [opts.filter] — cheap substring pre-filter applied to the RAW
+ *   line before `JSON.parse`. The measured reason it exists: the caller that
+ *   this replaced pre-filtered on the event name, and parsing every line of a
+ *   7.9 MB ledger to answer one question is the cost that made it do so.
+ *   NOTE: with a filter set, `malformed_lines` counts only unreadable lines
+ *   AMONG THE MATCHING ones — the rest are never parsed.
+ * @param {number} [opts.budgetMs] — wall-clock budget. When it runs out before
+ *   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[]}}
+ */
+export function scanEventsBackwards(opts = {}) {
+  const { onRecord, filter, budgetMs } = opts;
+  if (typeof onRecord !== 'function') {
+    throw new TypeError('scanEventsBackwards: opts.onRecord must be a function');
+  }
+  const chunkBytes =
+    Number.isInteger(opts.chunkBytes) && opts.chunkBytes > 0 ? opts.chunkBytes : SCAN_CHUNK_BYTES;
+  const deadline = Number.isFinite(budgetMs) ? Date.now() + budgetMs : null;
+  const outOfTime = () => deadline !== null && Date.now() > deadline;
+
+  const scanned = [];
+  const unreadable = [];
+  let malformed = 0;
+  let stopped = false;
+  let truncated = false;
+
+  /** @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;
+      if (typeof filter === 'string' && !line.includes(filter)) continue;
+      let record;
+      try {
+        record = JSON.parse(line);
+      } catch {
+        malformed += 1; // counted, never silently skipped (honesty rule 2)
+        continue;
+      }
+      if (onRecord(record, source) === true) return true;
+    }
+    return false;
+  };
+
+  for (const source of listEventSourcesNewestFirst(opts)) {
+    if (stopped || truncated) break;
+    if (outOfTime()) {
+      truncated = true;
+      break;
+    }
+    scanned.push(source.path);
+    let fd;
+    try {
+      fd = openSync(source.path, 'r');
+      let pos = fstatSync(fd).size;
+      /** Partial line at the FRONT of everything read from THIS source so far. */
+      let carry = Buffer.alloc(0);
+      while (pos > 0) {
+        if (outOfTime()) {
+          truncated = true;
+          break;
+        }
+        const length = Math.min(chunkBytes, 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; // a line longer than one chunk — no complete line yet
+          continue;
+        }
+        if (consume(block.subarray(firstNewline + 1), source)) {
+          stopped = true;
+          break;
+        }
+        carry = block.subarray(0, firstNewline);
+      }
+      // pos === 0: the carry is this source's FIRST line, complete by construction.
+      if (!stopped && !truncated && consume(carry, source)) stopped = true;
+    } catch (err) {
+      // An unreadable source is a FINDING, not an empty one: it is exactly the
+      // case where "no record found" must not be reported as "never happened".
+      unreadable.push(source.path);
+      void err;
+    } finally {
+      if (fd !== undefined) {
+        try {
+          closeSync(fd);
+        } catch {
+          /* best-effort */
+        }
+      }
+    }
+  }
+
+  return { stopped, truncated, malformed_lines: malformed, sources: scanned, unreadable };
+}

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/frontmatter-guard.mjs

@@ -12,6 +12,7 @@
 
 import { digestSha256Short } from './crypto-digest-utils.mjs';
 import { resolveHostPath } from './config/host-paths.mjs';
+import { maskSource } from './js-mask.mjs';
 import { readFileSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
@@ -117,25 +118,34 @@ let _warnedFallback = false;
  */
 const _cache = { mtime: null, result: null };
 
+/** One quoted string literal — its interior in group 2. */
+const STRING_LITERAL_RE = /(['"`])((?:\\.|(?!\1)[^\\\n])*)\1/g;
+
 /**
- * Parse the type-enum values out of a Zod `z.enum([...])` call in source text.
+ * Parse the enum values out of a Zod `z.enum([...])` call in source text.
  *
- * @param {string} text
+ * `codeText` must be the source with its COMMENTS blanked
+ * (`maskSource(text, { keepLiterals: true })`): the values are the quoted
+ * literals of the enum body and nothing else. Splitting the raw body on commas
+ * rendered comment prose between the literals as enum values — 6 of 16
+ * `statusEnum` entries against the real baseline schema, one fused onto
+ * `'maintenance'` (#1298) — and every one reached agent prompts as an allowed
+ * `status`. Masking via the shared lexer also keeps a `//` inside a literal
+ * intact and a `]` inside a comment from ending the body early.
+ *
+ * @param {string} codeText - comment-masked source
  * @param {string} exportName - e.g. 'vaultNoteTypeSchema'
  * @returns {string[]}
  */
-function _extractEnum(text, exportName) {
+function _extractEnum(codeText, exportName) {
   // Match: export const <name> = z.enum([ ...values... ]);
   const re = new RegExp(
     `export\\s+const\\s+${exportName}\\s*=\\s*z\\.enum\\(\\s*\\[([^\\]]+)\\]`,
     's',
   );
-  const match = text.match(re);
+  const match = codeText.match(re);
   if (!match) return [];
-  return match[1]
-    .split(',')
-    .map((s) => s.trim().replace(/^['"]|['"]$/g, ''))
-    .filter(Boolean);
+  return [...match[1].matchAll(STRING_LITERAL_RE)].map((m) => m[2]).filter(Boolean);
 }
 
 /**
@@ -145,8 +155,9 @@ function _extractEnum(text, exportName) {
  * @returns {{ typeEnum: string[], statusEnum: string[], requiredFields: string[], idRegex: string, tagsRegex: string, schemaText: string }}
  */
 function _parseSchema(text) {
-  const typeEnum = _extractEnum(text, 'vaultNoteTypeSchema');
-  const statusEnum = _extractEnum(text, 'vaultNoteStatusSchema');
+  const codeText = maskSource(text, { keepLiterals: true });
+  const typeEnum = _extractEnum(codeText, 'vaultNoteTypeSchema');
+  const statusEnum = _extractEnum(codeText, 'vaultNoteStatusSchema');
 
   // Required fields are id, type, created, updated — stable; extracted
   // from the schema object declaration (non-optional fields).