session-orchestrator 5.7.0 → 5.9.0

package/scripts/lib/reconcile/idempotency.mjs

@@ -57,9 +57,10 @@
  *        (absence reads as `'written'`, the only outcome that existed then).
  */
 
-import { mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
-import { dirname, isAbsolute, join } from 'node:path';
-import { createHash, randomBytes } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { atomicWriteWithBackup } from '../io.mjs';
 
 /** Default repo-relative location of the reconcile-candidate work-queue. */
 export const DEFAULT_STORE_PATH = '.orchestrator/runtime/reconcile-candidates.jsonl';
@@ -159,18 +160,16 @@ function readStore(absPath) {
  * @returns {{ ok: true, lines: number } | { ok: false, reason: 'fs-error', error: string }}
  */
 function writeStore(absPath, records) {
+  let content;
   try {
-    const dir = dirname(absPath);
-    mkdirSync(dir, { recursive: true });
     const body = records.map((r) => JSON.stringify(r)).join('\n');
-    const content = records.length > 0 ? body + '\n' : '';
-    const tmpFile = join(dir, `.reconcile-candidates.${randomBytes(6).toString('hex')}.tmp`);
-    writeFileSync(tmpFile, content, { encoding: 'utf8' });
-    renameSync(tmpFile, absPath);
-    return { ok: true, lines: records.length };
+    content = records.length > 0 ? body + '\n' : '';
   } catch (err) {
     return { ok: false, reason: 'fs-error', error: err?.message ?? String(err) };
   }
+  // mkdir -p + tmp + rename; its failure envelope is this function's own.
+  const res = atomicWriteWithBackup(absPath, content, { tmpPrefix: '.reconcile-candidates.tmp' });
+  return res.ok ? { ok: true, lines: records.length } : res;
 }
 
 /**

package/scripts/lib/reconcile/rule-expiry-sweep.mjs

@@ -146,6 +146,7 @@ import { join, resolve, sep } from 'node:path';
 import { atomicWriteWithBackup } from '../io.mjs';
 import { readLearnings } from '../learnings/io.mjs';
 import { listMachineGeneratedRules } from '../instruction-budget-guard.mjs';
+import { parseGlobsFrontmatter, ruleExpiryInstantMs } from '../rule-loader.mjs';
 import { markCandidateProcessed } from './idempotency.mjs';
 
 /** Repo-relative learnings store — the only source of a per-entry date. */
@@ -290,6 +291,18 @@ export function parseConsolidatedRule(content) {
       break;
     }
   }
+  // The VALUE is taken the loader's way (quote-stripped): a hand-edited
+  // `"2026-06-01"` would otherwise reach Date.parse with its quotes and be read
+  // as LOCAL midnight — up to 26 h before the loader stops injecting the rule.
+  // The line index above stays the rewrite anchor.
+  if (expiresAtLine >= 0) {
+    try {
+      const loaderValue = parseGlobsFrontmatter(String(content ?? '')).meta['expires-at'];
+      if (typeof loaderValue === 'string') expiresAt = loaderValue;
+    } catch {
+      // frontmatter the loader rejects — keep the raw value (fail-open downstream)
+    }
+  }
 
   const bodyStart = frontmatterEnd >= 0 ? frontmatterEnd + 1 : 0;
   for (let i = bodyStart; i < lines.length; i += 1) {
@@ -403,12 +416,23 @@ function dateOnly(iso) {
  * `unresolvedPairIds`), so a file whose ids all fail to resolve yields `null`
  * rather than a guess.
  *
+ * One exclusion: a markers-only pair whose date lies before `cutoffMs` is
+ * dropped. Its substance is already gone, so its elapsed date protects nothing
+ * — yet left in, it pins the raise target at or below a header that has already
+ * passed, and `rule-loader.mjs` excludes the whole file forever (live
+ * 2026-10-04: `guard-design.md` header 2026-10-04 pinned by markers-only
+ * `d86c9b5f-…`, next absorbed date 2026-10-07). The pair itself stays in the
+ * file and in `N` — it is still a dedupe marker. Expired SUBSTANTIVE pairs stay
+ * in the population: raising past one would revive prose not yet swept.
+ *
  * @param {ReturnType<typeof parseConsolidatedRule>} parsed
  * @param {Map<string, string>} expiryById
+ * @param {number} cutoffMs  expiry cutoff (now minus grace)
  * @returns {string|null}
  */
-function earliestResolvableDate(parsed, expiryById) {
+function earliestResolvableDate(parsed, expiryById, cutoffMs) {
   const dates = parsed.pairs
+    .filter((p) => !p.markersOnly || !(Date.parse(expiryById.get(p.id) ?? '') < cutoffMs))
     .map((p) => expiryById.get(p.id))
     .filter((v) => typeof v === 'string' && Number.isFinite(Date.parse(v)))
     .sort();
@@ -423,15 +447,20 @@ function earliestResolvableDate(parsed, expiryById) {
  * outlives its content is never lowered here — see the module header for why
  * the two directions are not symmetric.
  *
+ * Already-expired markers-only pairs do not hold the target down (see
+ * {@link earliestResolvableDate}); they stay in the file as dedupe markers and
+ * keep counting toward `N`.
+ *
  * @param {ReturnType<typeof parseConsolidatedRule>} parsed
  * @param {Map<string, string>} expiryById
+ * @param {number} cutoffMs  expiry cutoff (now minus grace)
  * @returns {string|null}
  */
-function headerRaiseTarget(parsed, expiryById) {
+function headerRaiseTarget(parsed, expiryById, cutoffMs) {
   if (!parsed.expiresAt || parsed.expiresAtLine < 0) return null;
   const headerMs = Date.parse(parsed.expiresAt);
   if (!Number.isFinite(headerMs)) return null;
-  const earliest = earliestResolvableDate(parsed, expiryById);
+  const earliest = earliestResolvableDate(parsed, expiryById, cutoffMs);
   if (earliest === null) return null;
   const earliestMs = Date.parse(earliest);
   if (!Number.isFinite(earliestMs) || earliestMs <= headerMs) return null;
@@ -450,15 +479,20 @@ function headerRaiseTarget(parsed, expiryById) {
  *
  * Deliberately NOT the `newExpiresAt` population: that one excludes expired
  * pairs so a rewritten file is not instantly expired again. This is a
- * diagnostic about the file AS COMMITTED, so it excludes nothing.
+ * diagnostic about the file AS COMMITTED, so it excludes nothing — except an
+ * already-expired markers-only pair, the same exclusion the raise target makes.
+ * Without it, every file the raise (or an expired-entries rewrite) moved past
+ * such a pair would carry a permanent advisory naming the elapsed date, i.e.
+ * an instruction to lower the header back to where the loader drops the file.
  *
  * @param {ReturnType<typeof parseConsolidatedRule>} parsed
  * @param {Map<string, string>} expiryById
+ * @param {number} cutoffMs  expiry cutoff (now minus grace)
  * @returns {string|undefined} undefined when there is nothing to report
  */
-function headerAdvisory(parsed, expiryById) {
+function headerAdvisory(parsed, expiryById, cutoffMs) {
   if (!parsed.expiresAt) return undefined;
-  const earliest = earliestResolvableDate(parsed, expiryById);
+  const earliest = earliestResolvableDate(parsed, expiryById, cutoffMs);
   if (earliest === null || earliest === parsed.expiresAt) return undefined;
   return `header expires-at ${parsed.expiresAt} != earliest resolvable absorbed date ${earliest}`;
 }
@@ -587,8 +621,8 @@ export async function planRuleExpirySweep(opts = {}) {
     // most likely to carry a stale header, `test-hygiene.md` among them — could
     // never receive one. Measured 2026-09-17: the advisory reached 3 of 7 files
     // where 6 of 7 have the discrepancy.
-    const advisory = headerAdvisory(parsed, expiryById);
-    const raiseTo = headerRaiseTarget(parsed, expiryById);
+    const advisory = headerAdvisory(parsed, expiryById, cutoffMs);
+    const raiseTo = headerRaiseTarget(parsed, expiryById, cutoffMs);
 
     if (
       parsed.counterLine === -1 &&
@@ -596,7 +630,7 @@ export async function planRuleExpirySweep(opts = {}) {
       parsed.pairs.length === 1 &&
       substantive.length === 1 &&
       parsed.expiresAt !== null &&
-      Number.isFinite(Date.parse(parsed.expiresAt))
+      ruleExpiryInstantMs(parsed.expiresAt) !== null
     ) {
       // SINGLE-ENTRY file (#1513): one learning, one pair, no `### ` entries,
       // no counter sentence — the shape the reconciliation engine writes per
@@ -612,7 +646,10 @@ export async function planRuleExpirySweep(opts = {}) {
       // before the unlink, so `/reconcile` does not re-propose it.
       const pair = substantive[0];
       const storeAt = expiryById.has(pair.id) ? Date.parse(expiryById.get(pair.id)) : Number.NaN;
-      const fileAt = Date.parse(parsed.expiresAt);
+      // The file's own `expires-at` goes through the loader's predicate: a bare
+      // date is inclusive (#1521), so the file is not deleted while
+      // `rule-loader.mjs` still injects it on its last day.
+      const fileAt = ruleExpiryInstantMs(parsed.expiresAt);
       const effectiveAt = Number.isFinite(storeAt) ? Math.max(storeAt, fileAt) : fileAt;
       const base = {
         file: rule.file,
@@ -623,7 +660,7 @@ export async function planRuleExpirySweep(opts = {}) {
         headings: 0,
         substantivePairs: 1,
       };
-      if (effectiveAt < cutoffMs) {
+      if (effectiveAt <= cutoffMs) {
         plans.push({
           ...base,
           expiredPairIds: [pair.id],

package/scripts/lib/reconcile/writer.mjs

@@ -39,9 +39,10 @@
  *    pushes an error string.
  *
  * Atomic write strategy (rule files):
- *  - Write content to `<target>.XXXXXXXX.tmp` via `writeFileSync`, then
- *    `renameSync` over the final path. Same-filesystem rename is atomic on POSIX,
- *    so the rule file is never partially visible. Mirrors idempotency.mjs pattern.
+ *  - `atomicWriteWithBackup` (`../io.mjs`): content goes to a sibling
+ *    `.<file>.tmp.<hex>`, then is renamed over the final path. Same-filesystem
+ *    rename is atomic on POSIX, so the rule file is never partially visible.
+ *    Mirrors idempotency.mjs pattern.
  *
  * JSONL append strategy (rejected log):
  *  - `appendFileSync` for the rejected log — each record is a self-contained line,
@@ -63,17 +64,16 @@ import {
   writeFileSync,
   readFileSync,
   readdirSync,
-  renameSync,
   appendFileSync,
   realpathSync,
   rmSync,
   statSync,
 } from 'node:fs';
-import { randomBytes } from 'node:crypto';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 
 import { withFileLock } from '../file-lock.mjs';
+import { atomicWriteWithBackup, envelopeToError } from '../io.mjs';
 import { validatePathInsideProject } from '../path-utils.mjs';
 import { parseGlobsFrontmatter } from '../rule-loader.mjs';
 import { markCandidateProcessed } from './idempotency.mjs';
@@ -308,24 +308,18 @@ function resolveDest(item, target, prep, roots, errors) {
 }
 
 /**
- * Write `content` to `destPath` atomically via tmp+rename.
+ * Write `content` to `destPath` atomically via tmp+rename
+ * (`atomicWriteWithBackup`, random tmp suffix, tmp unlinked on failure).
  *
- * Uses a random 8-hex-char suffix for the tmp file to avoid collisions when
- * multiple proposals write to the same directory concurrently (defensive;
- * under the lock this should not happen, but the pattern is cheap).
- *
- * Throws on filesystem errors — callers must catch.
+ * Throws on filesystem errors — callers must catch. The helper returns an
+ * envelope; `envelopeToError` re-raises it with the same message and `code`.
  *
  * @param {string} destPath - absolute path of the target rule file.
  * @param {string} content  - UTF-8 text content to write.
  */
 function writeTextAtomic(destPath, content) {
-  const dir = path.dirname(destPath);
-  mkdirSync(dir, { recursive: true });
-  const suffix = randomBytes(4).toString('hex');
-  const tmpPath = `${destPath}.${suffix}.tmp`;
-  writeFileSync(tmpPath, content, 'utf8');
-  renameSync(tmpPath, destPath);
+  const res = atomicWriteWithBackup(destPath, content, { tmpPrefix: `.${path.basename(destPath)}.tmp` });
+  if (!res.ok) throw envelopeToError(res);
 }
 
 /**

package/scripts/lib/rule-loader.mjs

@@ -48,8 +48,9 @@
  * Deterministic gating (issue #694) runs after a successful frontmatter parse
  * and applies to BOTH always-on and glob-matched candidate rules — a rule must
  * pass ALL active gates to be included:
- *   - Expiry: a rule with a parseable `expires-at` strictly before `now` is
- *     EXCLUDED (with a mandatory stderr WARN). A malformed `expires-at` never
+ *   - Expiry: a rule whose parseable `expires-at` has passed is EXCLUDED (with
+ *     a mandatory stderr WARN). A bare date is inclusive — the rule loads
+ *     through that whole UTC day ({@link ruleExpiryInstantMs}, #1521). A malformed `expires-at` never
  *     excludes (fail-open).
  *   - Mode-gating: when the `mode` param is non-null and the rule declares a
  *     `mode` that differs, the rule is EXCLUDED. A null `mode` param disables
@@ -411,16 +412,41 @@ function metaToEntryFields(meta) {
  * @param {unknown} rawExpiry - the raw `expires-at` frontmatter value (or undefined)
  * @param {number} [now] - epoch ms; defaults to `Date.now()`
  * @param {(raw: unknown) => void} [onUnparseable] - called when `expires-at` is present but unparseable
- * @returns {boolean} true only when a PARSEABLE `expires-at` lies before `now`
+ * @returns {boolean} true only when `now` has reached a PARSEABLE `expires-at`'s {@link ruleExpiryInstantMs}
  */
 export function isRuleExpired(rawExpiry, now = Date.now(), onUnparseable) {
   if (rawExpiry === undefined || rawExpiry === null) return false;
-  const ts = Date.parse(String(rawExpiry));
-  if (Number.isNaN(ts)) {
+  const ts = ruleExpiryInstantMs(rawExpiry);
+  if (ts === null) {
     if (typeof onUnparseable === 'function') onUnparseable(rawExpiry);
     return false;
   }
-  return ts < now;
+  return ts <= now;
+}
+
+const BARE_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const MS_PER_DAY = 86_400_000;
+
+/**
+ * The instant (epoch ms) from which a rule with this `expires-at` counts as
+ * expired, or `null` when the value is absent or unparseable.
+ *
+ * `expires-at` is INCLUSIVE (#1521): a bare `YYYY-MM-DD` keeps the rule live
+ * through the whole of that UTC day, so the instant is the FOLLOWING UTC
+ * midnight. A full timestamp is taken as written. Every consumer that judges
+ * "expired" — the loader gate above, `instruction-budget-guard.mjs`
+ * (maintenance probe S7) and `reconcile/rule-expiry-sweep.mjs` — goes through
+ * this one function so the three never disagree about the boundary day.
+ *
+ * @param {unknown} rawExpiry
+ * @returns {number|null}
+ */
+export function ruleExpiryInstantMs(rawExpiry) {
+  if (rawExpiry === undefined || rawExpiry === null) return null;
+  const text = String(rawExpiry).trim();
+  const ts = Date.parse(text);
+  if (Number.isNaN(ts)) return null;
+  return BARE_DATE_RE.test(text) ? ts + MS_PER_DAY : ts;
 }
 
 /**

package/scripts/lib/scope-echo.mjs

@@ -420,7 +420,8 @@ export function digestScopeFiles(stateDir, wave, { readDir = readdirSync, readFi
  * @param {number} params.wave
  * @param {string} params.stateDir
  * @param {string} [params.session]    semantic (or raw) session id to filter on
- * @param {string} [params.eventsPath] defaults to `.orchestrator/metrics/events.jsonl`
+ * @param {string} [params.eventsPath] defaults to the cwd-relative `.orchestrator/metrics/events.jsonl`;
+ *   the CLI passes `eventsFilePath(<state-dir>/..)` (the repo's one ledger, #1514)
  * @param {typeof readFileSync} [params.readFile]
  * @param {typeof readdirSync} [params.readDir]
  * @returns {{wave: number, transport: 'observable'|'unobservable', dispatches: number,
@@ -639,11 +640,20 @@ async function mainVerify(args) {
     return 1;
   }
 
+  // #1514 point 1 — read the ledger the send-side hook WRITES: the one ledger
+  // of the repo this state dir belongs to (`eventsFilePath(<root>)`, a linked
+  // worktree mapped to its main checkout), not a cwd-relative path that, run
+  // from an entered worktree, found 0 `scope_checked` records. Resolved here,
+  // not in `verifyWaveScope`, so this module stays pure (stdlib +
+  // `crypto-digest-utils.mjs`) for the hook that imports it.
+  const eventsPath = typeof args.events === 'string'
+    ? args.events
+    : (await import('./events.mjs')).eventsFilePath(resolve(stateDir, '..'));
   const report = verifyWaveScope({
     wave,
     stateDir,
     session: typeof args.session === 'string' ? args.session : undefined,
-    eventsPath: typeof args.events === 'string' ? args.events : undefined,
+    eventsPath,
   });
 
   if (args.emit) {

package/scripts/lib/scope-gate.mjs

@@ -405,7 +405,8 @@ export function testSiblingExpansionApplies(opts = {}) {
  * tests/lib/X.test.mjs`). The DATED figures — population, both ratios, the
  * measuring command and the SHA — live in ONE place:
  * skills/wave-executor/references/wave-loop-scope-manifest.md § Test-Sibling
- * Expansion (#970). Cite and re-measure them there, never restate them here: an
+ * Expansion (#970), measured by `scripts/lib/test-sibling-coverage.mjs` (#1030 P3).
+ * Cite and re-measure them there, never restate them here: an
  * undated copy drifted to a second, contradicting set of numbers (#1026.5,
  * PSA-006 item 4). The glob's failure mode is HARMLESS — it grants write access
  * to files that may not exist. A computed concrete path is wrong more often AND

package/scripts/lib/session-close-backfill.mjs

@@ -66,7 +66,7 @@ import { parseStateMd as defaultParseStateMd } from './state-md/yaml-parser.mjs'
 import { canonicalizeSessions } from './sessions-canonical.mjs';
 // Already in the hook import set (`emitEvent` lives there): the rotation-aware
 // reader adds no new file to the SessionStart/SessionEnd hook graph.
-import { scanEventsBackwards } from './events.mjs';
+import { eventsFilePath, scanEventsBackwards } from './events.mjs'; // eventsFilePath: #1514, the repo's one ledger
 // Leaf constants module (no imports of its own) and ALREADY in the hook import
 // set via session-schema/validator.mjs — importing it here adds no new file to
 // the SessionStart/SessionEnd hook graph. The profile enum must not be
@@ -114,7 +114,6 @@ const EVENT_STOPPED = 'orchestrator.session.stopped';
 const EVENT_TURN_STOPPED = 'orchestrator.turn.stopped';
 const EVENT_ENDED = 'orchestrator.session.ended';
 
-const EVENTS_REL = ['.orchestrator', 'metrics', 'events.jsonl'];
 const SESSIONS_REL = ['.orchestrator', 'metrics', 'sessions.jsonl'];
 const BACKFILL_LOG_REL = ['.orchestrator', 'metrics', 'session-close-backfill.log'];
 
@@ -973,7 +972,7 @@ export async function backfillAbandonedSession({
         return { action: 'skipped-no-identifier' };
       }
 
-      const eventsPath = path.join(repoRoot, ...EVENTS_REL);
+      const eventsPath = eventsFilePath(repoRoot);
       const sessionsPath = path.join(repoRoot, ...SESSIONS_REL);
 
       // -- Resolve the SEMANTIC record id (sessions.jsonl key) ----------------
@@ -1368,7 +1367,7 @@ export async function backfillCompletedFromStateMd({
       if (supersedes) recordId = supersedes;
 
       // -- Derive whatever is derivable from events.jsonl (never STATE.md body) -
-      const eventsPath = path.join(repoRoot, ...EVENTS_REL);
+      const eventsPath = eventsFilePath(repoRoot);
       const gathered = gatherSessionEvents(readFileSync, eventsPath, { sessionId: nativeId, semanticSessionId });
 
       // -- Synthesize + validate (round-trip gate) BEFORE any disk mutation ----

package/scripts/lib/session-id.mjs

@@ -42,6 +42,7 @@
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 
+import { eventsFilePath } from './events.mjs';
 import { readCanonicalSessions } from './sessions-canonical.mjs';
 import { readTailWindow } from './tail-window.mjs';
 import { withStateMdLock } from './session-lock.mjs';
@@ -207,7 +208,7 @@ const EVENTS_MAX_AGE_MS = 2 * 24 * 60 * 60 * 1000;
  * @returns {Promise<string[]>}  Array of semantic_session_id strings (may include duplicates).
  */
 async function readSessionIdsFromEvents(repoRoot) {
-  const filePath = path.join(repoRoot, '.orchestrator', 'metrics', 'events.jsonl');
+  const filePath = eventsFilePath(repoRoot); // #1514 point 1: the repo's one ledger
 
   let window;
   try {

package/scripts/lib/session-record-repair.mjs

@@ -68,6 +68,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+import { atomicWriteWithBackup, envelopeToError } from './io.mjs';
 import { validateSession as defaultValidateSession } from './session-schema/validator.mjs';
 import { serializeSessionLineChecked as defaultSerialize } from './session-schema.mjs';
 import { checkSessionsIntegrity as defaultCheckIntegrity } from './sessions-integrity-banner.mjs';
@@ -123,12 +124,11 @@ const INCOMPLETE_FIELD_ORDER = Object.freeze([
 const MS_PRECISION_FIELDS = Object.freeze(['started_at', 'completed_at', 'lease_acquired_at']);
 
 /**
- * ISO-8601 UTC with MORE than three fractional digits (`.994600Z`) — the one
- * rejected shape that has an unambiguous canonical form. Group 1 is the value
- * cut at the millisecond. Offsets, `.3Z` and non-ISO strings do not match and
- * stay for the validator to reject: there is no defensible default for them.
+ * ISO-8601 UTC with MORE than three fractional digits and exactly `Z` or
+ * `+00:00` (#1525). Group 1 is the value cut at the millisecond. Nonzero
+ * offsets, other timezone spellings and shorter fractions stay unrepaired.
  */
-const ISO_UTC_SUB_MS_RE = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3})\d+Z$/;
+const ISO_UTC_SUB_MS_RE = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3})\d+(?:Z|\+00:00)$/;
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -154,7 +154,13 @@ function isCount(v) {
 function truncateToMs(value) {
   if (typeof value !== 'string') return null;
   const m = ISO_UTC_SUB_MS_RE.exec(value);
-  return m ? `${m[1]}Z` : null;
+  if (!m) return null;
+  const canonical = `${m[1]}Z`;
+  const ms = Date.parse(canonical);
+  // Date.parse rolls over e.g. April 31, non-leap February 29 and 24:00.
+  // Equality with the original calendar components refuses those repairs.
+  if (!Number.isFinite(ms) || new Date(ms).toISOString() !== canonical) return null;
+  return canonical;
 }
 
 function orderIncompleteFields(fields) {
@@ -390,10 +396,16 @@ export function repairRecord(record) {
     preserveRaw(out, 'completed_at', record.completed_at, rescued);
     const endedMs = typeof out.ended_at === 'string' ? Date.parse(out.ended_at) : NaN;
     const startedMs = Date.parse(out.started_at);
-    if (Number.isFinite(endedMs) && Number.isFinite(startedMs) && endedMs >= startedMs) {
+    const endedTruncated = truncateToMs(out.ended_at);
+    if (typeof out.ended_at === 'string' &&
+        (!Number.isFinite(endedMs) ||
+         (ISO_UTC_SUB_MS_RE.test(out.ended_at) && endedTruncated === null))) {
+      // Preserve an invalid legacy measurement for the final schema gate to
+      // reject; do not turn it into a valid default or a rolled-over date.
+      out.completed_at = out.ended_at;
+    } else if (Number.isFinite(endedMs) && Number.isFinite(startedMs) && endedMs >= startedMs) {
       // The COPY is cut to milliseconds; `ended_at` itself is not a validated
       // field and keeps its original bytes, so nothing needs a sidecar here.
-      const endedTruncated = truncateToMs(out.ended_at);
       if (endedTruncated !== null) precisionCut = true;
       out.completed_at = endedTruncated ?? out.ended_at;
     } else {
@@ -716,7 +728,6 @@ export function repairLedger({ file, repoRoot = null, apply = false, backup = tr
     renameSync = fs.renameSync,
     copyFileSync = fs.copyFileSync,
     unlinkSync = fs.unlinkSync,
-    existsSync = fs.existsSync,
   } = deps;
 
   const { checkIntegrity = defaultCheckIntegrity } = deps;
@@ -751,18 +762,14 @@ export function repairLedger({ file, repoRoot = null, apply = false, backup = tr
   }
 
   // -- atomic swap ----------------------------------------------------------
-  const tmpPath = `${file}.tmp-${process.pid}`;
-  try {
-    writeFileSync(tmpPath, text, 'utf8');
-    renameSync(tmpPath, file);
-  } catch (err) {
-    try {
-      if (existsSync(tmpPath)) unlinkSync(tmpPath);
-    } catch {
-      /* best-effort cleanup */
-    }
-    throw err;
-  }
+  // The helper unlinks its tmp on failure; the backup above keeps its own
+  // `.bak-<compact stamp>` schema, so the helper takes none. The injected fs
+  // seams (`deps`) are threaded through so a test fake still sees the write.
+  const res = atomicWriteWithBackup(file, text, {
+    tmpPrefix: `.${path.basename(file)}.tmp`,
+    fs: { writeFileSync, renameSync, unlinkSync },
+  });
+  if (!res.ok) throw envelopeToError(res);
 
   // -- post-verification ----------------------------------------------------
   const verdict = verifyWritten({

package/scripts/lib/session-schema/constants.mjs

@@ -162,11 +162,11 @@ export const AGENT_SUMMARY_FIELDS = Object.freeze(['complete', 'partial', 'faile
  * #964). These are NOT in REQUIRED_FIELDS — older entries lacking them validate
  * cleanly. Validator: see `_validateOptionalFields` in validator.mjs.
  *
- * NOT YET EXHAUSTIVE. `_validateOptionalFields` additionally shape-checks
- * `discovery_stats`, `review_stats`, `platform`, `branch`, `base_branch`,
- * `notes`, `duration_seconds`, `issues_closed` and `issues_created` without
- * listing them here. Treat membership as "declared optional", never absence as
- * "not a known field" — see the #964 follow-up note in the session report.
+ * Exhaustive since #986: every optional key `validateSession` inspects is
+ * declared here. tests/lib/session-schema/constants.test.mjs takes that census
+ * from the validator itself (a Proxy records the keys it reads) and also pins
+ * the declared-but-unchecked remainder (`session_start_ref`, `raw_session_id`,
+ * `_repair_source`).
  */
 export const OPTIONAL_FIELDS = Object.freeze([
   'agent_identity',
@@ -252,4 +252,19 @@ export const OPTIONAL_FIELDS = Object.freeze([
   // 2026-10-01), so the counters say which of the two it is.
   'cost_records_priced',
   'cost_records_total',
+  // #986 — shape-checked by `_validateOptionalFields` since before this list
+  // existed, never declared until the census test made the gap visible.
+  'discovery_stats',
+  'review_stats',
+  'platform',
+  'branch',
+  'base_branch',
+  'notes',
+  'duration_seconds',
+  'issues_closed',
+  'issues_created',
+  // `express_path` (canonical boolean, legacy {activated} object tolerated) and
+  // its forensic sidecar `_express_path_detail` written by `normalizeSession`.
+  'express_path',
+  '_express_path_detail',
 ]);

package/scripts/lib/session-schema/validator.mjs

@@ -182,6 +182,12 @@ function _validateTimestamps(entry) {
       `started_at must match ISO-8601 UTC ms format (YYYY-MM-DDTHH:MM:SS[.SSS]Z), got: ${entry.started_at}`
     );
   }
+  // Date.parse normalizes impossible calendar dates; compare without mutating the record.
+  const startedCanonical = entry.started_at.includes('.')
+    ? entry.started_at : entry.started_at.replace(/Z$/, '.000Z');
+  if (new Date(startedMs).toISOString() !== startedCanonical) {
+    throw new ValidationError(`started_at must be a valid calendar timestamp, got: ${entry.started_at}`);
+  }
   if (typeof entry.completed_at !== 'string') {
     throw new ValidationError('completed_at must be an ISO timestamp string');
   }
@@ -194,6 +200,12 @@ function _validateTimestamps(entry) {
       `completed_at must match ISO-8601 UTC ms format (YYYY-MM-DDTHH:MM:SS[.SSS]Z), got: ${entry.completed_at}`
     );
   }
+  // Date.parse normalizes impossible calendar dates; compare without mutating the record.
+  const completedCanonical = entry.completed_at.includes('.')
+    ? entry.completed_at : entry.completed_at.replace(/Z$/, '.000Z');
+  if (new Date(completedMs).toISOString() !== completedCanonical) {
+    throw new ValidationError(`completed_at must be a valid calendar timestamp, got: ${entry.completed_at}`);
+  }
   if (completedMs < startedMs) {
     throw new ValidationError(
       `completed_at (${entry.completed_at}) must be >= started_at (${entry.started_at})`

package/scripts/lib/session-start-probes.mjs

@@ -50,7 +50,7 @@ import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { promisify } from 'node:util';
 
-import { emitEvent } from './events.mjs';
+import { emitEvent, eventsFilePath } from './events.mjs';
 import { ARCHIVE_DIR_NAME, ARCHIVE_NAME_RE } from './events-schema.mjs';
 
 /**
@@ -258,10 +258,11 @@ function commitRunsCommand(gh, sha) {
  * @returns {string}
  */
 function ciUnknownHint(result) {
-  if (!PUSHED_FOLLOW_UP_REASONS.has(result?.details?.reason)) return CI_UNKNOWN_HINT_DEFAULT;
-  // The GitHub reason names the gh CLI; a glab command there would be wrong.
-  const gh = result.details.cliUsed === 'gh';
+  // Every GitHub unknown reason needs a GitHub hint, including running,
+  // queued and cancelled checks that do not trigger a pushed-commit query.
+  const gh = result?.details?.cliUsed === 'gh';
   const onDemand = gh ? 'run `gh run list` on demand' : CI_UNKNOWN_HINT_DEFAULT;
+  if (!PUSHED_FOLLOW_UP_REASONS.has(result?.details?.reason)) return onDemand;
   const pushed = result.pushed && typeof result.pushed === 'object' ? result.pushed : null;
   // Pure (#1396): the SHA is whatever the follow-up resolved inside the budget.
   // Without `pushed` (the follow-up overran or threw before resolving it) the
@@ -275,6 +276,20 @@ function ciUnknownHint(result) {
   return `last pushed: ${short} (pipeline not checked; run \`${commitRunsCommand(gh, sha)}\`)`;
 }
 
+/** Additive GitHub diagnostics; absent counts leave existing banners unchanged. */
+function checkRunCountsText(result) {
+  const counts = result?.details?.checkRunCounts;
+  if (!counts || result?.details?.cliUsed !== 'gh') return '';
+  const parts = [
+    ['success', 'successful'], ['failure', 'failed/action required'],
+    ['inProgress', 'in progress'], ['queued', 'queued'],
+    ['cancelled', 'cancelled'], ['skipped', 'skipped'],
+    ['neutral', 'neutral'], ['waiting', 'waiting'], ['other', 'unrecognised'],
+  ].filter(([key]) => Number.isSafeInteger(counts[key]) && counts[key] > 0)
+    .map(([key, label]) => `${label}: ${counts[key]}`);
+  return parts.length ? ` — Check runs: ${parts.join(', ')}` : '';
+}
+
 /**
  * "Green, but allow_failure jobs failed" — the ONE predicate both the
  * `ci-status` renderer and its `severityOf` use (#1333). Two predicates once
@@ -584,7 +599,7 @@ export const PROBES = [
         // #1337: a RED pushed commit is an alert, and the banner says what the
         // rule judges (HR-106) — same 🚨 as a red HEAD.
         const mark = r.pushed?.verdict?.status === 'red' ? '🚨' : '⚠';
-        return `${mark} ci-status: CI status for HEAD could not be determined (${reason}) — ${ciUnknownHint(r)}`;
+        return `${mark} ci-status: CI status for HEAD could not be determined (${reason})${checkRunCountsText(r)} — ${ciUnknownHint(r)}`;
       }
       if (r.status === 'red') {
         const pid = r.details?.currentPipelineId ?? '?';
@@ -592,7 +607,7 @@ export const PROBES = [
           ? ` — last green: #${r.lastGreen.pipelineId} (commit ${String(r.lastGreen.sha ?? '').slice(0, 7)}, ${r.redCount} pipelines ago)`
           : '';
         const job = r.failingJobName ? ` Failing job: ${r.failingJobName}` : '';
-        return `🚨 CI RED on HEAD (pipeline #${pid})${green}.${job}`;
+        return `🚨 CI RED on HEAD (pipeline #${pid})${green}.${job}${checkRunCountsText(r)}`;
       }
       if (r.status === 'green') {
         const lines = [];
@@ -762,7 +777,7 @@ export const PROBES = [
     fn: 'checkEventsRetention',
     network: false,
     precondition: ({ repoRoot }) => {
-      const metrics = path.join(repoRoot, '.orchestrator', 'metrics');
+      const metrics = path.dirname(eventsFilePath(repoRoot)); // #1514: the ledger checkEventsRetention reads
       return existsSync(path.join(metrics, 'events.jsonl')) || hasRotationArchive(metrics)
         ? null
         : 'no-events-ledger';