session-orchestrator 5.7.0 → 5.8.0

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';
@@ -716,7 +717,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 +751,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-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';
 
 /**
@@ -762,7 +762,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';

package/scripts/lib/sessions-staleness-banner.mjs

@@ -143,6 +143,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 
+import { eventsFilePath } from './events.mjs';
 import { readLock, DEFAULT_TTL_HOURS } from './session-lock.mjs';
 import { isRealSession } from './session-schema/filters.mjs';
 import { readCanonicalSessions } from './sessions-canonical.mjs';
@@ -150,8 +151,6 @@ import { readCanonicalSessions } from './sessions-canonical.mjs';
 /** Repo-relative path to the session ledger (one record per closed session). */
 const SESSIONS_PATH = '.orchestrator/metrics/sessions.jsonl';
 
-/** Repo-relative path to the generic telemetry stream (one line per event). */
-const EVENTS_PATH = '.orchestrator/metrics/events.jsonl';
 
 /** warn threshold: 2x the session-lock default TTL (8h) — imported, not duplicated. */
 export const WARN_THRESHOLD_HOURS = DEFAULT_TTL_HOURS * 2;
@@ -527,7 +526,7 @@ export function checkSessionsStaleness({ repoRoot, now = Date.now() } = {}) {
     const ledger = lastLedgerEntry(sessionRecords);
     if (ledger === null) return null;
 
-    const eventLines = readJsonlLines(path.join(repoRoot, EVENTS_PATH));
+    const eventLines = readJsonlLines(eventsFilePath(repoRoot)); // #1514: the repo's one ledger
     if (eventLines === null || eventLines.length === 0) return null;
 
     const { cutoffMs, ownSessionId } = resolveCutoff(repoRoot, nowMs);

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

@@ -49,9 +49,9 @@
  * Part of Epic #643 → issue #647 (C2 auto-repair engine).
  */
 
-import { readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import path from 'node:path';
-import { randomBytes } from 'node:crypto';
+import { atomicWriteWithBackup } from '../io.mjs';
 
 import { extractCandidates as realExtractCandidates } from './candidate-intake.mjs';
 import {
@@ -281,13 +281,10 @@ async function defaultApplyConfigRepair(candidate, repoRoot) {
     return { ok: true, applied: false, reason: 'already-current (no-op)' };
   }
 
-  try {
-    const dir = path.dirname(abs);
-    const tmpFile = path.join(dir, `.${path.basename(abs)}.${randomBytes(6).toString('hex')}.tmp`);
-    writeFileSync(tmpFile, next, { encoding: 'utf8' });
-    renameSync(tmpFile, abs);
-  } catch (err) {
-    return { ok: true, applied: false, reason: `write failed: ${err?.message ?? String(err)}` };
+  // The helper's mkdir -p is a no-op here: `abs` was just read, so its dir exists.
+  const written = atomicWriteWithBackup(abs, next, { tmpPrefix: `.${path.basename(abs)}.tmp` });
+  if (!written.ok) {
+    return { ok: true, applied: false, reason: `write failed: ${written.error}` };
   }
 
   return { ok: true, applied: true };

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

@@ -45,9 +45,9 @@
  * Part of Epic #643 → issue #647 (C2 auto-repair engine).
  */
 
-import { mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
-import { dirname, isAbsolute, join } from 'node:path';
-import { randomBytes } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { atomicWriteWithBackup } from '../io.mjs';
 
 /**
  * @typedef {import('./candidate-intake.mjs').RepairCandidate} RepairCandidate
@@ -202,18 +202,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, `.repair-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: '.repair-candidates.tmp' });
+  return res.ok ? { ok: true, lines: records.length } : res;
 }
 
 // ---------------------------------------------------------------------------

package/scripts/lib/slopcheck.mjs

@@ -43,6 +43,7 @@
 import { execFile } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
+import { atomicWriteWithBackup } from './io.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -164,15 +165,16 @@ function ensureCacheLoaded(repoRoot) {
 function persistCache(repoRoot) {
   if (_cache === null) return;
   const file = cachePathFor(repoRoot);
-  const dir = path.dirname(file);
+  let body;
   try {
-    fs.mkdirSync(dir, { recursive: true });
-    const obj = Object.fromEntries(_cache.entries());
-    const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
-    fs.writeFileSync(tmp, JSON.stringify(obj, null, 2) + '\n', 'utf8');
-    fs.renameSync(tmp, file);
+    body = JSON.stringify(Object.fromEntries(_cache.entries()), null, 2) + '\n';
   } catch (err) {
-    console.warn(`slopcheck: cache write failed (${err.code ?? 'unknown'}): ${err.message}`);
+    console.warn(`slopcheck: cache write failed (serialize): ${err.message}`);
+    return;
+  }
+  const res = atomicWriteWithBackup(file, body, { tmpPrefix: `.${path.basename(file)}.tmp` });
+  if (!res.ok) {
+    console.warn(`slopcheck: cache write failed (${res.code ?? 'unknown'}): ${res.error}`);
   }
 }
 

package/scripts/lib/sunset/walker.mjs

@@ -606,8 +606,8 @@ export function staticReferenceScan(repoRoot, { kind, name }) {
  * NOTE since the 2026-09-16 command→skill fold (#1370): this linkage now covers
  * almost nothing. `commands/` holds two files (`session`, `templates-ack`), so
  * `skillToCommands` is near-empty by construction — the operator entry point for
- * every other slash command is an explicit `user-invocable: true` in the skill's
- * own frontmatter, not a command file pointing at it. `runSunsetWalk` therefore
+ * every other slash command is a skill whose `user-invocable` is `true` or absent
+ * (Claude Code picker semantics, #1515) in its own frontmatter, not a command file pointing at it. `runSunsetWalk` therefore
  * threads that flag alongside this linkage, and `classifyItem` treats the two as
  * equivalent evidence of "an operator can invoke this directly". Without that, 26
  * live slash commands would have been demoted the day their command file was
@@ -783,7 +783,7 @@ export function classifyItem({
   const strictRefs = staticRefs.strictRefs;
   const nonBoilerplateRefs = staticRefs.nonBoilerplateRefs;
   const invokedByCommands = linkage?.invokedByCommands ?? [];
-  // #1370 fold: an explicit `user-invocable: true` in SKILL.md frontmatter is the
+  // #1370 fold: a picker-visible skill (`user-invocable` true or absent, #1515) is the
   // post-fold form of "an operator invokes this directly" — the same evidence a
   // command file used to carry. Default false so older callers/tests that do not
   // thread it behave exactly as before.

package/scripts/lib/telemetry/sync.mjs

@@ -42,6 +42,7 @@ 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 { resolveEventsLedgerRoot } from '../platform.mjs';
 import { readCanonicalSessions } from '../sessions-canonical.mjs';
 import { resolvePrivateConfigDir } from '../config/private-config-dir.mjs';
 import { readSessionProfile } from '../state-md.mjs';
@@ -382,7 +383,8 @@ export function deriveSessionFromEvents(metricsDir) {
     // 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'),
+      // #1514: the repo's one ledger (identity unless metricsDir is in a linked worktree).
+      filePath: path.join(resolveEventsLedgerRoot(metricsDir), 'events.jsonl'),
     });
     const events = ledger.events;
     // A missing archive is a GAP, never an empty window (#1407 AC-3). Carried

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

@@ -32,8 +32,8 @@
  */
 
 import { existsSync } from 'node:fs';
-import path from 'node:path';
 
+import { eventsFilePath } from './events.mjs';
 import { readTailWindow } from './tail-window.mjs';
 
 /**
@@ -122,7 +122,7 @@ export function checkTelemetryFlushHealth({ repoRoot } = {}) {
   try {
     if (!repoRoot || typeof repoRoot !== 'string') return null;
 
-    const file = path.join(repoRoot, '.orchestrator', 'metrics', 'events.jsonl');
+    const file = eventsFilePath(repoRoot); // #1514: the repo's one ledger
     if (!existsSync(file)) return null;
 
     const tail = readTail(file);