session-orchestrator 5.2.0 → 5.3.0

package/scripts/lib/skill-evolution/candidate-intake.mjs

@@ -6,10 +6,18 @@
  *   1. `/evolve` learnings (`.orchestrator/metrics/learnings.jsonl` records)
  *   2. `claude-md-drift-check` output (`driftResult.errors[]`)
  *
- * This module is a PURE transform: it performs NO I/O. It never reads or writes
- * any file. Persistence and the `processed_at` / `superseded_by` lifecycle are
- * OWNED BY the sibling `idempotency.mjs` module — this module only emits the
- * raw candidates with those fields nulled out.
+ * This module WRITES nothing. Its only read is target resolution for the
+ * learnings feeder: at most one `git ls-files` per `extractCandidates` call
+ * (lazy — only when a learning survives the cheaper filters), plus a
+ * `realpathSync` containment check that applies with or without git. A
+ * learning becomes a candidate only when its extracted path resolves — symlinks
+ * followed — to a regular file inside the realpath of `repoRoot` that is also
+ * the ONE tracked file it names (tracking is skipped when git is unavailable);
+ * the kept `target_path` is the repo-relative form of that resolved file, so a
+ * bare basename becomes its full path and `scripts/../x.mjs` becomes `x.mjs`. Persistence and
+ * the `processed_at` / `superseded_by` lifecycle are OWNED BY the sibling
+ * `idempotency.mjs` module — this module only emits the raw candidates with
+ * those fields nulled out.
  *
  * The `id` field is a deterministic short hash of (source, target_path,
  * fingerprint), so the same input always yields the same id. That determinism
@@ -18,7 +26,10 @@
  * Part of Epic #643 → issue #647 (C2 auto-repair engine).
  */
 
+import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
+import { realpathSync, statSync } from 'node:fs';
+import path from 'node:path';
 
 /**
  * @typedef {Object} RepairCandidate
@@ -96,6 +107,104 @@ function extractPath(text) {
   return match ? match[0] : null;
 }
 
+/**
+ * Build the target resolver for ONE extraction run. `PATH_RE` also admits bare
+ * basenames (`engine.mjs`, `mcp.json`) that exist nowhere at the repo root, so
+ * an extracted path is a claim, not a target, until it resolves here.
+ *
+ * Resolution is fail-closed — `null` drops the candidate. In BOTH modes the
+ * path is resolved with `realpathSync` (every symlink followed) and must land
+ * on a regular file inside `realpathSync(repoRoot)`; any resolution error
+ * drops it. The kept `target_path` is the repo-relative POSIX form of that
+ * RESOLVED path, so `scripts/../CLAUDE.md` and `CLAUDE.md` name one target
+ * (and mint one id). Containment follows `classifyTarget` in
+ * `blast-radius-classifier.mjs`, plus the realpath of the target itself.
+ *
+ * With git, the resolved path must additionally be a tracked file:
+ *   - a path containing `/` is resolved as given;
+ *   - a bare basename must match exactly ONE tracked file (zero = unresolvable,
+ *     two or more = ambiguous) and is resolved from that file's full path.
+ * A tracked symlink whose target lies outside the repo is therefore dropped.
+ *
+ * The tracked-file index is read lazily and at most once per resolver
+ * (`git ls-files -z` in `repoRoot`), so a run without a qualifying learning
+ * never spawns git. Without git (binary missing, not a repository) only the
+ * realpath containment applies — a bare basename then resolves only at the
+ * root, since nothing enumerates the tree.
+ *
+ * @param {string} repoRoot
+ * @returns {(extracted: string) => string|null}
+ */
+function makeTargetResolver(repoRoot) {
+  /** @type {{ tracked: Set<string>, byBasename: Map<string, string[]> }|null|undefined} */
+  let index; // undefined = not read yet, null = git unavailable
+
+  // Canonicalise the root once, as blast-radius-classifier does: a symlinked
+  // repoRoot (macOS /var → /private/var) must still anchor the escape check.
+  let root;
+  try {
+    root = realpathSync(path.resolve(repoRoot));
+  } catch {
+    root = path.resolve(repoRoot);
+  }
+
+  function readIndex() {
+    try {
+      const out = execFileSync('git', ['ls-files', '-z'], {
+        cwd: repoRoot,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        maxBuffer: 64 * 1024 * 1024,
+      });
+      const tracked = new Set(out.split('\0').filter(Boolean));
+      /** @type {Map<string, string[]>} */
+      const byBasename = new Map();
+      for (const file of tracked) {
+        const base = file.slice(file.lastIndexOf('/') + 1);
+        const list = byBasename.get(base);
+        if (list) list.push(file);
+        else byBasename.set(base, [file]);
+      }
+      return { tracked, byBasename };
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Realpath-resolve `rel` against the canonical root.
+   * @param {string} rel
+   * @returns {string|null} repo-relative POSIX path of the regular file it
+   *   resolves to, or null when it escapes the root, is not a regular file, or
+   *   does not resolve at all.
+   */
+  function resolveInsideRoot(rel) {
+    let real;
+    try {
+      real = realpathSync(path.resolve(root, rel));
+      if (!statSync(real).isFile()) return null;
+    } catch {
+      return null;
+    }
+    const back = path.relative(root, real);
+    if (back === '' || back.startsWith('..') || path.isAbsolute(back)) return null;
+    return back.split(path.sep).join('/');
+  }
+
+  return (extracted) => {
+    if (index === undefined) index = readIndex();
+    if (index === null) return resolveInsideRoot(extracted);
+    let candidate = extracted;
+    if (!extracted.includes('/')) {
+      const matches = index.byBasename.get(extracted) ?? [];
+      if (matches.length !== 1) return null;
+      candidate = matches[0];
+    }
+    const resolved = resolveInsideRoot(candidate);
+    return resolved !== null && index.tracked.has(resolved) ? resolved : null;
+  };
+}
+
 /**
  * Map a single learning record to a RepairCandidate, or null when it fails any
  * actionable filter. learnings.jsonl records are NOT uniform — only `confidence`
@@ -104,9 +213,10 @@ function extractPath(text) {
  * @param {Record<string, unknown>} learning
  * @param {number} evidenceFloor
  * @param {string} nowIso
+ * @param {(extracted: string) => string|null} resolveTarget
  * @returns {RepairCandidate|null}
  */
-function learningToCandidate(learning, evidenceFloor, nowIso) {
+function learningToCandidate(learning, evidenceFloor, nowIso, resolveTarget) {
   if (!learning || typeof learning !== 'object') return null;
 
   // Filter 1: confidence gate.
@@ -123,13 +233,18 @@ function learningToCandidate(learning, evidenceFloor, nowIso) {
   const subject = typeof learning.subject === 'string' ? learning.subject : '';
   const insight = typeof learning.insight === 'string' ? learning.insight : '';
 
-  // Filter 2: resolvable target path from subject OR insight.
-  const targetPath = extractPath(subject) ?? extractPath(insight);
-  if (!targetPath) return null;
+  // Filter 2: a path-shaped token in subject OR insight.
+  const extracted = extractPath(subject) ?? extractPath(insight);
+  if (!extracted) return null;
 
   // Filter 3: insight must be prescriptive.
   if (!PRESCRIPTIVE_RE.test(insight)) return null;
 
+  // Filter 5: the token resolves to exactly one tracked file (last — it is the
+  // only filter that may spawn git).
+  const targetPath = resolveTarget(extracted);
+  if (!targetPath) return null;
+
   const source = 'evolve-learning';
   const sourceRef = typeof learning.id === 'string' && learning.id.length > 0
     ? learning.id
@@ -218,7 +333,9 @@ function driftErrorToCandidate(err, nowIso) {
 
 /**
  * Ingest the two repair-candidate feeders and return a normalised
- * `RepairCandidate[]`. Pure transform — performs no I/O.
+ * `RepairCandidate[]`. Writes nothing; learnings are resolved against the files
+ * tracked in `repoRoot` (see `makeTargetResolver`). Drift errors pass through
+ * unresolved — the checker reported them from a file it read.
  *
  * @param {Object} params
  * @param {Array<Record<string, unknown>>} [params.learnings] - `/evolve` learning records.
@@ -226,7 +343,10 @@ function driftErrorToCandidate(err, nowIso) {
  *        claude-md-drift-check output. Only `errors[]` are mapped; `warnings[]`
  *        are skipped. A null result, or a status of `skipped`/`skipped-mode-off`/
  *        undefined, emits zero drift candidates.
- * @param {string} [params.repoRoot] - repo root (accepted for caller symmetry; unused in the pure transform).
+ * @param {string} [params.repoRoot] - repo root learning targets must resolve in
+ *        (default `process.cwd()`). A learning is dropped unless its extracted
+ *        path realpath-resolves to a regular file inside this root that is
+ *        exactly one tracked file there (tracking skipped without git).
  * @param {number} [params.evidenceFloor=0.5] - minimum learning confidence to qualify.
  * @param {string} [params.now] - ISO timestamp for `created_at` + expiry checks (test determinism).
  * @returns {RepairCandidate[]}
@@ -234,13 +354,14 @@ function driftErrorToCandidate(err, nowIso) {
 export function extractCandidates({
   learnings,
   driftResult,
-  // eslint-disable-next-line no-unused-vars -- accepted for caller symmetry; pure transform does no path resolution
   repoRoot,
   evidenceFloor = 0.5,
   now,
 } = {}) {
   const nowIso = typeof now === 'string' && now.length > 0 ? now : new Date().toISOString();
   const floor = Number.isFinite(evidenceFloor) ? evidenceFloor : 0.5;
+  const root = typeof repoRoot === 'string' && repoRoot.length > 0 ? repoRoot : process.cwd();
+  const resolveTarget = makeTargetResolver(root);
 
   /** @type {RepairCandidate[]} */
   const candidates = [];
@@ -248,7 +369,7 @@ export function extractCandidates({
   // Feeder 1: /evolve learnings.
   if (Array.isArray(learnings)) {
     for (const learning of learnings) {
-      const candidate = learningToCandidate(learning, floor, nowIso);
+      const candidate = learningToCandidate(learning, floor, nowIso, resolveTarget);
       if (candidate) candidates.push(candidate);
     }
   }

package/scripts/lib/skill-evolution/engine.mjs

@@ -8,7 +8,7 @@
  * — the matrix is the load-bearing deliverable, not the file-write mechanics.
  *
  * COMPOSITION (the five siblings, all DI-injectable via `opts`):
- *   - candidate-intake.mjs       → extractCandidates    (pure transform)
+ *   - candidate-intake.mjs       → extractCandidates    (no writes; resolves targets against repoRoot)
  *   - idempotency.mjs            → mergeCandidates / markProcessed / isProcessed
  *                                   / loadCandidates    (store I/O + supersession)
  *   - blast-radius-classifier.mjs→ classifyTarget       (R5 posture/gate triple)
@@ -17,7 +17,7 @@
  *
  * PIPELINE:
  *   extractCandidates(learnings, driftResult)
- *     → mergeCandidates (persist + supersede)
+ *     → mergeCandidates (persist + supersede; skipped under dryRun)
  *     → for each NON-processed candidate:
  *         classify → decide per matrix → act
  *
@@ -583,7 +583,8 @@ async function finishOpenMr({ candidate, candidateId, targetPath, targetType, re
  * @param {Array<Record<string, unknown>>} [params.learnings] — `/evolve` learning records.
  * @param {{ status?: string, errors?: Array<Record<string, unknown>> }|null} [params.driftResult]
  *        claude-md-drift-check output.
- * @param {boolean} [params.dryRun=false] — when true, no mutation/MR/stamp; previews only.
+ * @param {boolean} [params.dryRun=false] — when true, no mutation/MR/stamp and no
+ *        candidate-store write (the skip is logged via `opts.log`); previews only.
  * @param {Object} [opts] — DI seams (all default to the real sibling functions).
  * @param {typeof realExtractCandidates} [opts.extractCandidates]
  * @param {typeof realMergeCandidates} [opts.mergeCandidates]
@@ -629,7 +630,7 @@ export async function runRepairEngine(
   const outcomes = [];
   const summary = { autonomousApplied: 0, mrsOpened: 0, advisories: 0, blocked: 0, total: 0 };
 
-  // --- Pipeline step 1 — intake (pure transform) ---------------------------
+  // --- Pipeline step 1 — intake (no writes; repoRoot anchors target resolution)
   let candidates;
   try {
     candidates = seams.extractCandidates({
@@ -650,11 +651,19 @@ export async function runRepairEngine(
   }
 
   // --- Pipeline step 2 — merge (persist + supersede) -----------------------
-  try {
-    seams.mergeCandidates({ candidates, repoRoot });
-  } catch (err) {
-    seams.log('error', `engine: mergeCandidates threw — ${err?.message ?? err}`);
-    // Persistence failure is non-fatal: continue with the in-memory candidates.
+  // A dry run previews from the in-memory candidates and never writes the store.
+  if (dryRun === true) {
+    seams.log(
+      'info',
+      `engine: dry-run — candidate store write skipped (${candidates.length} candidate(s) not persisted)`,
+    );
+  } else {
+    try {
+      seams.mergeCandidates({ candidates, repoRoot });
+    } catch (err) {
+      seams.log('error', `engine: mergeCandidates threw — ${err?.message ?? err}`);
+      // Persistence failure is non-fatal: continue with the in-memory candidates.
+    }
   }
 
   // --- Pipeline step 3 — per-candidate classify → decide → act -------------

package/scripts/lib/skill-judge.mjs

@@ -31,6 +31,7 @@
  *  - estimateInputTokens(str)          — char-count/4 heuristic
  *  - checkBudget(estimated, budget)    — verdict for the budget gate
  *  - buildJudgePrompt(skills, tail, nonce) — pure prompt assembly (untrusted-data fence)
+ *  - evidenceBudgetChars(skills, budget)   — characters left for evidence after the prompt frame
  *  - parseJudgeResponse(text)          — extract one fenced ```json block, validate, drop malformed
  */
 
@@ -54,6 +55,9 @@ export const DEFAULT_BUDGET = Object.freeze({ input: 8000, output: 4000 });
 /** Industry-standard heuristic: ~4 chars per token for English prose. */
 const CHARS_PER_TOKEN = 4;
 
+/** Hex length of the per-call untrusted-data nonce (`randomBytes(16)` → 32 hex). */
+const NONCE_HEX_LENGTH = 32;
+
 // ---------------------------------------------------------------------------
 // Pure-function gates
 // ---------------------------------------------------------------------------
@@ -182,6 +186,25 @@ export function buildJudgePrompt(selectedSkills, transcriptTail, nonce) {
   ].join('\n');
 }
 
+/**
+ * How many characters of evidence fit inside `budget.input` for THIS judged set.
+ *
+ * The caller must not have to guess: the prompt frame is MEASURED by building
+ * the very prompt that will be sent with an empty fence, so the answer tracks
+ * every future edit to `buildJudgePrompt` automatically. The nonce is
+ * length-accurate (`NONCE_HEX_LENGTH`) rather than the real random value, since
+ * only its length affects the frame.
+ *
+ * @param {string[]} selectedSkills — the judged set (its JSON is part of the frame)
+ * @param {{input?: number}} [budget]
+ * @returns {number} characters available for `evidence.text` (never negative)
+ */
+export function evidenceBudgetChars(selectedSkills = [], budget = DEFAULT_BUDGET) {
+  const maxInput = typeof budget?.input === 'number' ? budget.input : DEFAULT_BUDGET.input;
+  const frame = buildJudgePrompt(selectedSkills, '', 'f'.repeat(NONCE_HEX_LENGTH)).length;
+  return Math.max(0, maxInput * CHARS_PER_TOKEN - frame);
+}
+
 /**
  * Parse the judge response into validated judgment records. Extracts the FIRST
  * fenced ```json block, JSON.parses it, and validates each entry against
@@ -253,7 +276,7 @@ export function parseJudgeResponse(text) {
 
 /**
  * @typedef {Object} JudgeResult
- * @property {'ok' | 'empty-input' | 'budget-exceeded'} status
+ * @property {'ok' | 'empty-input' | 'no-evidence' | 'budget-exceeded'} status
  * @property {Array<{skill: string, applied: string, completed: string, confidence: number}>} judgments
  * @property {{input_tokens?: number, output_tokens?: number, estimated_input?: number}} [usage]
  * @property {string} [skipped_reason]
@@ -269,6 +292,7 @@ export function parseJudgeResponse(text) {
  *
  * Control flow (matches the ratified #645 L3 contract):
  *   - empty selectedSkills → {status:'empty-input', judgments:[]} (no dispatch).
+ *   - empty evidence text  → {status:'no-evidence', judgments:[]} (no dispatch, #1399).
  *   - budget exceeded     → {status:'budget-exceeded', judgments:[]} (no dispatch,
  *                            NOT truncated — mirrors dialectic-deriver).
  *   - else → dispatch → parse → {status:'ok', judgments, usage}.
@@ -277,7 +301,8 @@ export function parseJudgeResponse(text) {
  * @param {(args: {model: string, prompt: string, maxTokens: number}) => Promise<{text: string, usage?: {input_tokens?: number, output_tokens?: number}}>} opts.dispatchAgent — REQUIRED, injected DI boundary
  * @param {string} [opts.repoRoot]
  * @param {string|null} [opts.sessionId]
- * @param {string} [opts.transcriptTail]
+ * @param {{text?: string}} [opts.evidence] — preferred input; `buildSkillEvidence()` output (#1399)
+ * @param {string} [opts.transcriptTail] — legacy raw-string input; used when `evidence` is absent
  * @param {string[]} [opts.selectedSkills]
  * @param {'haiku'|'sonnet'|'opus'} [opts.model='haiku']
  * @param {{input: number, output: number}} [opts.budget]
@@ -293,6 +318,7 @@ export async function runSkillJudge({
   // `_`-prefixed names so the contract keys stay documented without tripping no-unused-vars.
   repoRoot: _repoRoot,
   sessionId: _sessionId,
+  evidence,
   transcriptTail = '',
   selectedSkills = [],
   model = 'haiku',
@@ -313,8 +339,24 @@ export async function runSkillJudge({
     return { status: 'empty-input', judgments: [], skipped_reason: 'no-selected-skills' };
   }
 
+  // Gate 2b (#1399): empty evidence — do NOT dispatch. Measured 2026-09-19 at
+  // `8f15f77b`: a prompt whose fence is empty is 1387 chars = 346 estimated
+  // tokens, so the budget gate below waves it through and the judge is asked to
+  // rule on a transcript it was never shown. An advisory verdict from no
+  // evidence is worse than no verdict — it looks exactly like a real one in
+  // `skill-judgments.jsonl`.
+  const evidenceText =
+    typeof evidence?.text === 'string' && evidence.text.trim()
+      ? evidence.text
+      : typeof transcriptTail === 'string'
+        ? transcriptTail
+        : '';
+  if (!evidenceText.trim()) {
+    return { status: 'no-evidence', judgments: [], skipped_reason: 'empty-transcript-evidence' };
+  }
+
   const nonce = randomNonce();
-  const prompt = buildJudgePrompt(skills, transcriptTail, nonce);
+  const prompt = buildJudgePrompt(skills, evidenceText, nonce);
 
   // Gate 3: budget — fail-fast BEFORE dispatch when the prompt would exceed it.
   const estimatedInput = estimateInputTokens(prompt);

package/scripts/lib/tail-window.mjs

@@ -0,0 +1,56 @@
+/**
+ * tail-window.mjs — the ONE bounded tail-window reader for append-only JSONL
+ * ledgers and transcripts (#1272).
+ *
+ * Five call sites used to carry their own copy of this byte-window primitive,
+ * and one of them (hooks/subagent-telemetry.mjs) ignored the returned read
+ * length and decoded a whole `allocUnsafe` buffer — on a short read that is
+ * uninitialised memory handed to JSON.parse. This module owns ONLY the byte
+ * window; every caller keeps its own error mapping (null / [] / discriminated
+ * result / throw) and its own line logic.
+ *
+ * Ceiling: the whole window is held in memory at once and decoded in one pass
+ * — fine for the windows in use today (64 KiB .. 1 MiB). Revisit if a caller
+ * needs a window above ~16 MiB: stream backwards in chunks instead.
+ */
+
+import fs from 'node:fs';
+
+/**
+ * Read the last `maxBytes` of `file` as UTF-8.
+ *
+ * `cut` is true when the window did not start at byte 0 — the first line of
+ * `text` is then (or may be) a fragment of a record, possibly starting inside
+ * a multi-byte UTF-8 sequence, and callers that parse lines should drop it.
+ * Loops until the window is filled or the file reports EOF, so a short read
+ * never leaves undecoded buffer bytes in `text`.
+ *
+ * THROWS on any fs error (ENOENT, EACCES, …) — mapping the failure is the
+ * caller's decision.
+ *
+ * @param {string} file
+ * @param {number} maxBytes  window size in bytes (> 0)
+ * @returns {{ text: string, cut: boolean, size: number }}  `size` is the file size at open time
+ */
+export function readTailWindow(file, maxBytes) {
+  const fd = fs.openSync(file, 'r');
+  try {
+    const size = fs.fstatSync(fd).size;
+    const want = Math.min(size, maxBytes);
+    const start = size - want;
+    const buf = Buffer.allocUnsafe(want);
+    let read = 0;
+    while (read < want) {
+      const n = fs.readSync(fd, buf, read, want - read, start + read);
+      if (n <= 0) break;
+      read += n;
+    }
+    return { text: buf.subarray(0, read).toString('utf8'), cut: start > 0, size };
+  } finally {
+    try {
+      fs.closeSync(fd);
+    } catch {
+      /* best-effort */
+    }
+  }
+}

package/scripts/lib/telemetry/schema.mjs

@@ -93,6 +93,7 @@ export const USAGE_PING_OPTIONAL_FIELDS = Object.freeze([
   'fleet_self_declared',
   'session_record',
   'session_profile',
+  'ledger_complete',
 ]);
 
 /**
@@ -117,6 +118,29 @@ const USAGE_PING_PROJECTED_FIELDS = Object.freeze([...USAGE_PING_FIELDS, ...USAG
  */
 export const SESSION_RECORD_SOURCES = Object.freeze(['ledger', 'derived', 'absent']);
 
+/*
+ * `ledger_complete` — a SECOND, ORTHOGONAL axis beside `session_record`
+ * (GitLab #1416), deliberately NOT a fourth provenance token.
+ *
+ * `deriveSessionFromEvents` (telemetry/sync.mjs) returns a three-state verdict on
+ * the events ledger it read FROM: `true` (every rotation archive present),
+ * `false` (at least one measured gap — a deleted/missing archive), and `null`
+ * (no verdict was produced at all: the read threw, or there was no source). That
+ * verdict decided nothing on the wire, so a derived record reconstructed from a
+ * holey ledger was indistinguishable from one reconstructed from a whole one.
+ *
+ * Why a boolean and not a `derived-partial` token: `SESSION_RECORD_SOURCES` is a
+ * frozen enum mirrored in prose and in the server's `raw_json` consumers, and
+ * completeness is a property of the SOURCE READ, not of WHICH source was used —
+ * widening the provenance enum would make the two facts inseparable and force
+ * every reader of `session_record === 'derived'` to learn a second spelling.
+ *
+ * THE THIRD STATE IS OMISSION: only a real boolean is written. `null` (nothing
+ * measured) omits the key, exactly like `session_profile` — "we did not look" is
+ * never sent as a measured `false`. On the `ledger` branch the field is not set
+ * at ALL: that path never reads the events ledger, so it has no verdict to give.
+ */
+
 /** Exact duration-bucket tokens (ASCII, stable wire values). */
 export const DURATION_BUCKETS = Object.freeze(['<15m', '15-60m', '1-3h', '>3h']);
 
@@ -541,6 +565,7 @@ export function buildUsagePing({
   consentState,
   sessionRecordSource,
   sessionProfile,
+  ledgerComplete,
 } = {}) {
   const session = isPlainObject(sessionRecord) ? sessionRecord : {};
   const invocations = Array.isArray(skillInvocations) ? skillInvocations : [];
@@ -637,6 +662,11 @@ export function buildUsagePing({
     session_record: SESSION_RECORD_SOURCES.includes(sessionRecordSource)
       ? sessionRecordSource
       : 'absent',
+    // ONLY a real boolean travels (#1416). `null`/`undefined` — the read never
+    // happened, or this path never read the events ledger at all — OMITS the
+    // key, the same absent-is-not-empty contract `session_profile` uses above.
+    // Writing `false` there would turn "we did not look" into a measured gap.
+    ...(typeof ledgerComplete === 'boolean' ? { ledger_complete: ledgerComplete } : {}),
     skills: filterRosterNames(skillNames, rosterSkills),
     commands: filterRosterNames(commandNames, rosterCommands),
   };

package/scripts/lib/telemetry/sync.mjs

@@ -41,6 +41,7 @@ import { ensureAnonId } from './anon-id.mjs';
 import { peekAll, enqueue, clear, queueStats } from './queue.mjs';
 import { loadOwnerConfig } from '../owner-yaml.mjs';
 import { readJsonlFile } from '../io.mjs';
+import { readEventsWithRotations } from '../events.mjs';
 import { readCanonicalSessions } from '../sessions-canonical.mjs';
 import { resolvePrivateConfigDir } from '../config/private-config-dir.mjs';
 import { readSessionProfile } from '../state-md.mjs';
@@ -338,12 +339,54 @@ export function readSessionProfileForMetricsDir(metricsDir) {
  * Never throws.
  *
  * @param {string} metricsDir
- * @returns {{ session: object, source: 'derived'|'absent' }}
+ * @returns {{ session: object, source: 'derived'|'absent',
+ *             ledger_complete: boolean|null, ledger_gaps: object[] }}
+ *   `ledger_complete` is `null` — never `false` — when the read produced no
+ *   verdict at all: an undetermined ledger is not a proven gap. TWO paths reach
+ *   that third state (#1423): this function throwing, and the reader finding NO
+ *   source (no active file, no archive, no legacy ring) — in the latter case
+ *   `events: []` is the absence of a ledger, not a measured quiet window.
+ *   `ledger_complete === false` additionally writes ONE stderr line naming the
+ *   gap kinds, because a verdict nothing surfaces is a verdict nobody acts on.
  */
 export function deriveSessionFromEvents(metricsDir) {
   try {
-    const events = readJsonlFile(path.join(metricsDir, 'events.jsonl'), { skipInvalid: true });
-    if (!Array.isArray(events) || events.length === 0) return { session: {}, source: 'absent' };
+    // #1407: read ACROSS rotation boundaries. This reconstruction is the ONLY
+    // source of session facts whenever `sessions.jsonl` has no usable record,
+    // and its sibling window is `DAILY_FLUSH_MS` (24 h) — so a rotation between
+    // a session's start and its flush silently truncated it.
+    //
+    // CEILING (BV-004): the reader loads the active file AND every archive
+    // fully into memory — up to ~60 MB transient at the default
+    // `max-size-mb: 10` / `max-backups: 5`. Measured 2026-09-20 A/B in ONE
+    // process on exactly that worst case (60 MB / 6 sources / 293,994 records,
+    // host loadavg 11.2): median 25.5 ms → 215.8 ms, i.e. +190 ms, which is
+    // 6.4 % of this path's `POST_TIMEOUT_MS` (3000). Acceptable for a
+    // once-per-flush cold read. Revisit if `max-size-mb` is raised past ~100,
+    // if `max-backups` grows, or if the flush budget drops below ~1 s.
+    const ledger = readEventsWithRotations(undefined, {
+      filePath: path.join(metricsDir, 'events.jsonl'),
+    });
+    const events = ledger.events;
+    // A missing archive is a GAP, never an empty window (#1407 AC-3). Carried
+    // on EVERY return below, including the empty ones — that is precisely where
+    // a deleted archive and a quiet period are otherwise indistinguishable.
+    const ledgerVerdict = { ledger_complete: ledger.complete, ledger_gaps: ledger.gaps };
+    // Visibility (#1423): the field had ZERO production consumers — a measured
+    // gap reached nobody. ONE stderr line, at the single point the verdict is
+    // formed, so every return below is covered by construction. Diagnostics on
+    // stderr, never stdout (cli-design.md); no new event, because the gap is a
+    // property of the LEDGER and an event about it would land in the same file.
+    if (ledger.complete === false) {
+      const kinds = [...new Set((ledger.gaps ?? []).map((g) => g?.kind ?? 'unknown'))].sort();
+      process.stderr.write(
+        `⚠ telemetry: events ledger INCOMPLETE — ${ledger.gaps.length} gap(s) ` +
+          `[${kinds.join(', ')}]; the session facts below are reconstructed from a PARTIAL read\n`,
+      );
+    }
+    if (!Array.isArray(events) || events.length === 0) {
+      return { session: {}, source: 'absent', ...ledgerVerdict };
+    }
 
     let startedAt = null;
     let sessionType = null;
@@ -412,7 +455,9 @@ export function deriveSessionFromEvents(metricsDir) {
       profile = undatedShapeProfile;
     }
 
-    if (startedAt === null && sessionType === null && profile === null) return { session: {}, source: 'absent' };
+    if (startedAt === null && sessionType === null && profile === null) {
+      return { session: {}, source: 'absent', ...ledgerVerdict };
+    }
 
     const session = {};
     if (sessionType !== null) session.session_type = sessionType;
@@ -422,9 +467,11 @@ export function deriveSessionFromEvents(metricsDir) {
     // omit-never-fabricate contract session-close-backfill.mjs uses (#914 R1).
     if (lastTs !== null && startedAt !== null && lastTs >= startedAt) session.completed_at = lastTs;
 
-    return { session, source: 'derived' };
+    return { session, source: 'derived', ...ledgerVerdict };
   } catch {
-    return { session: {}, source: 'absent' };
+    // No verdict was ever produced — `null`, not `false`: a measurement that
+    // did not happen is not a measured zero.
+    return { session: {}, source: 'absent', ledger_complete: null, ledger_gaps: [] };
   }
 }
 
@@ -483,6 +530,12 @@ export function buildBatch({
     let sessionForPing;
     /** @type {'ledger'|'derived'|'absent'} */
     let sessionRecordSource = 'ledger';
+    // #1416: the events-ledger completeness verdict, carried to the ping as its
+    // own optional boolean. Stays `null` on the LEDGER branch by construction —
+    // that branch never reads events.jsonl, so it has nothing to report, and
+    // `buildUsagePing` omits the key for anything that is not a real boolean.
+    /** @type {boolean|null} */
+    let ledgerComplete = null;
     if (sessionRecord && typeof sessionRecord.started_at === 'string' && !Number.isNaN(Date.parse(sessionRecord.started_at))) {
       const startMs = Date.parse(sessionRecord.started_at);
       windowInvocations = invocations.filter((rec) => {
@@ -500,6 +553,7 @@ export function buildBatch({
       const derived = deriveSessionFromEvents(dir);
       sessionForPing = derived.session;
       sessionRecordSource = derived.source;
+      ledgerComplete = derived.ledger_complete;
 
       const derivedStartMs = Date.parse(sessionForPing.started_at);
       const cutoff = (Number.isNaN(Date.parse(nowIso)) ? Date.now() : Date.parse(nowIso)) - DAILY_FLUSH_MS;
@@ -522,6 +576,7 @@ export function buildBatch({
       consentState,
       sessionRecordSource,
       sessionProfile: readSessionProfileForMetricsDir(dir),
+      ledgerComplete,
     });
 
     const target = statePath || TELEMETRY_JSON_PATH;

package/scripts/lib/telemetry-flush-health-banner.mjs

@@ -31,9 +31,11 @@
  * @module scripts/lib/telemetry-flush-health-banner
  */
 
-import { existsSync, openSync, readSync, fstatSync, closeSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import path from 'node:path';
 
+import { readTailWindow } from './tail-window.mjs';
+
 /**
  * Bytes of `events.jsonl` read from the END of the file.
  *
@@ -82,31 +84,11 @@ function sanitizeReason(reason) {
  * @returns {{text: string} | {missing: true} | {error: string}}
  */
 function readTail(file) {
-  let fd;
   try {
-    fd = openSync(file, 'r');
-    const { size } = fstatSync(fd);
-    const length = Math.min(size, TAIL_BYTES);
-    const start = size - length;
-    const buf = Buffer.allocUnsafe(length);
-    let read = 0;
-    while (read < length) {
-      const n = readSync(fd, buf, read, length - read, start + read);
-      if (n <= 0) break;
-      read += n;
-    }
-    return { text: buf.subarray(0, read).toString('utf8') };
+    return { text: readTailWindow(file, TAIL_BYTES).text };
   } catch (err) {
     if (err?.code === 'ENOENT') return { missing: true };
     return { error: typeof err?.code === 'string' ? err.code : 'EUNKNOWN' };
-  } finally {
-    if (fd !== undefined) {
-      try {
-        closeSync(fd);
-      } catch {
-        /* best effort */
-      }
-    }
   }
 }