session-orchestrator 5.6.0 → 5.8.0

package/scripts/lib/plugin-surface.mjs

@@ -0,0 +1,121 @@
+/**
+ * plugin-surface.mjs — the one enumeration of the plugin's public sources
+ * (`commands/*.md`, `skills/<name>/SKILL.md`) and the one hand-written
+ * frontmatter parser the Cursor and Pi wrapper generators share (#1240).
+ *
+ * Four generators derive harness surfaces from the same sources
+ * (`generate-agents-skills.mjs`, `generate-codex-skills.mjs`,
+ * `generate-cursor-adapter.mjs`, `generate-pi-prompts.mjs`). Before this module
+ * the agents/codex pair skipped names with a leading `.` or `_` while the
+ * cursor/pi pair did not, so a `commands/_draft.md` produced Cursor and Pi
+ * wrappers but no Codex or `.agents` mirror. {@link isHiddenSourceName} is now
+ * the single NAME filter all four apply. The file/directory test is not yet
+ * shared: the list helpers here follow symlinks (statSync), while
+ * generate-codex-skills.mjs keeps its own dirent loop, which does not. No
+ * source is a symlink today (`find skills commands -maxdepth 2 -type l` → 0);
+ * revisit when one is added.
+ */
+
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * A source name with a leading `.` or `_` is private (drafts, `_shared/`
+ * helpers, dotfiles) and never becomes a public command or skill.
+ *
+ * @param {string} name file or directory name
+ * @returns {boolean}
+ */
+export function isHiddenSourceName(name) {
+  return /^[._]/.test(name);
+}
+
+function isDir(p) {
+  try { return statSync(p).isDirectory(); } catch { return false; }
+}
+
+function isFile(p) {
+  try { return statSync(p).isFile(); } catch { return false; }
+}
+
+/**
+ * Public `commands/*.md` file names (with extension), sorted.
+ *
+ * @param {string} root plugin root
+ * @returns {string[]}
+ */
+export function listCommandFiles(root) {
+  const dir = path.join(root, 'commands');
+  if (!isDir(dir)) return [];
+  return readdirSync(dir)
+    .filter((name) => name.endsWith('.md') && !isHiddenSourceName(name) && isFile(path.join(dir, name)))
+    .sort();
+}
+
+/**
+ * Public `skills/<name>` directory names that carry a SKILL.md, sorted.
+ *
+ * @param {string} root plugin root
+ * @returns {string[]}
+ */
+export function listSkillDirs(root) {
+  const dir = path.join(root, 'skills');
+  if (!isDir(dir)) return [];
+  return readdirSync(dir)
+    .filter((name) => !isHiddenSourceName(name) && isDir(path.join(dir, name)) && existsSync(path.join(dir, name, 'SKILL.md')))
+    .sort();
+}
+
+/**
+ * Parse YAML-ish frontmatter including `>` / `|` folded scalars, returning
+ * DECODED values (one layer of surrounding quotes stripped). Not js-yaml on
+ * purpose: the Cursor/Pi wrappers re-emit these values verbatim, and every
+ * merged skill uses `description: >`, which this parser folds to its text.
+ *
+ * A UTF-8 BOM before the opening `---`, or CRLF line endings, used to make the
+ * probes below miss the block entirely: the file parsed as "no frontmatter",
+ * so every flag in it (`user-invocable`, `disable-model-invocation`) silently
+ * disappeared and the skill was demoted out of the generated surface with no
+ * diagnostic anywhere. Both are normalised away first — the same treatment
+ * `parseAgentFrontmatter` (`scripts/lib/agent-frontmatter.mjs`) gives them.
+ *
+ * NOT replaced by the shared `parseSkillFrontmatter`: that one returns the
+ * `__BLOCK_SCALAR__` sentinel for a `description: >`, which would be emitted
+ * as the wrapper description.
+ *
+ * @param {string} content
+ * @returns {Record<string, string>}
+ */
+export function parseFrontmatter(content) {
+  const text = (content.charCodeAt(0) === 0xfeff ? content.slice(1) : content).replace(/\r\n?/g, '\n');
+  if (!text.startsWith('---\n')) return {};
+  const end = text.indexOf('\n---\n', 4);
+  if (end === -1) return {};
+
+  const lines = text.slice(4, end).split('\n');
+  const fields = {};
+  let i = 0;
+  while (i < lines.length) {
+    const match = lines[i].match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!match) {
+      i += 1;
+      continue;
+    }
+    const key = match[1];
+    const raw = match[2];
+    if (raw === '>' || raw === '| ' || raw === '|' || raw === '>-' || raw === '|-') {
+      const folded = [];
+      i += 1;
+      while (i < lines.length && (lines[i].startsWith(' ') || lines[i].startsWith('\t') || lines[i] === '')) {
+        folded.push(lines[i].replace(/^\s+/, ''));
+        i += 1;
+      }
+      const joiner = raw.startsWith('|') ? '\n' : ' ';
+      fields[key] = folded.filter(Boolean).join(joiner).trim();
+      continue;
+    }
+    fields[key] = raw.replace(/^["']|["']$/g, '');
+    i += 1;
+  }
+  return fields;
+}

package/scripts/lib/quality-gate.mjs

@@ -62,7 +62,7 @@
  */
 
 import { spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -75,6 +75,7 @@ import {
   spawnInGroup,
 } from './process-group.mjs';
 import { redactDiagnosticsBundle } from './quality-gate/diagnostics.mjs';
+import { atomicWriteWithBackup, writeJsonAtomicSync } from './io.mjs';
 import { readProcessLocalSessionIds } from './session-identity/own-session.mjs';
 
 export { redactDiagnosticsBundle } from './quality-gate/diagnostics.mjs';
@@ -406,12 +407,10 @@ function writeLastGreenSha(repoRoot) {
     if (sha.status !== 0 || !sha.stdout) return;
     const head = sha.stdout.trim();
     if (!head) return;
-    const runtimeDir = join(repoRoot, '.orchestrator', 'runtime');
-    mkdirSync(runtimeDir, { recursive: true });
-    const target = join(runtimeDir, 'last-green-sha.txt');
-    const tmp = `${target}.tmp-${process.pid}-${Date.now()}`;
-    writeFileSync(tmp, head + '\n', 'utf8');
-    renameSync(tmp, target);
+    // Never throws; an fs failure is the same silent best-effort as before.
+    atomicWriteWithBackup(join(repoRoot, '.orchestrator', 'runtime', 'last-green-sha.txt'), head + '\n', {
+      tmpPrefix: '.tmp-last-green-sha',
+    });
   } catch {
     // best-effort
   }
@@ -657,14 +656,12 @@ function readCorrectiveContext(repoRoot) {
 function writeDiagnosticsBundle(repoRoot, bundle) {
   try {
     const dir = join(repoRoot, '.orchestrator', 'metrics', 'verification-failures');
-    mkdirSync(dir, { recursive: true });
     // Replace colons in ISO timestamp for cross-fs portability.
     const ts = new Date().toISOString().replace(/:/g, '-');
     const target = join(dir, `${ts}.json`);
-    const tmp = `${target}.tmp-${process.pid}-${Date.now()}`;
-    writeFileSync(tmp, JSON.stringify(redactDiagnosticsBundle(bundle), null, 2) + '\n', 'utf8');
-    renameSync(tmp, target);
-    return target;
+    // Same bytes as before: indent 2 + trailing newline, mkdir -p of `dir`.
+    const res = writeJsonAtomicSync(target, redactDiagnosticsBundle(bundle), { tmpPrefix: '.tmp-diagnostics' });
+    return res.ok ? target : null;
   } catch {
     return null;
   }
@@ -842,19 +839,27 @@ export function gateKillFields(run) {
  * through two LLM hops: `skills/wave-executor/wave-loop.md` step 7 hand-writes
  * them, `skills/session-end/metrics-collection.md` § 1.7 parses them back out of
  * the STATE.md Wave History header into sessions.jsonl. `counts` is a SECOND,
- * machine-measured emission of the same fact, and as of 2026-07-31 it has zero
- * readers (`grep -c '"counts"' .orchestrator/metrics/events.jsonl` → 0 across
- * 4404 `orchestrator.quality_gate.*` records).
- *
- * Retiring the prose path needs a producer change no docblock can make:
- * `waves[].*` is PER-WAVE, and gate events carry no `wave_number` (0 of those
- * 4404 records). A session-end reader could only attribute a gate event to a
- * wave by a wall-clock window whose own boundaries (`waves[].started_at` /
- * `completed_at`) are themselves LLM-written — one LLM hop traded for another,
- * against the posture `scripts/lib/eval/session-resolve.mjs` already documents
- * for window-attributed gate events ("a contaminated window means
- * gate-attribution is unsafe"). The concrete remaining work is named in
- * `skills/session-end/metrics-collection.md` § 1.7.
+ * machine-measured emission of the same fact. Measured 2026-10-05 against this
+ * repo's `.orchestrator/metrics/events.jsonl` (main checkout @ 1386a98e; the
+ * file has been rotated since the 4404-record 2026-07-31 reading this note
+ * used to quote): 82 `orchestrator.quality_gate.*` records, 46 carrying
+ * `counts` (`grep '"orchestrator.quality_gate' <file> | grep -c '"counts"'`).
+ *
+ * `waves[].*` is PER-WAVE, so the event needs a per-wave key. The
+ * `scripts/run-quality-gate.mjs` wrapper emits `wave_number` when a wave-scope
+ * sidecar names one (#966 step 1, `resolveWaveNumber`) and OMITS it otherwise —
+ * 37 of the same 82 records carry it
+ * (`grep '"orchestrator.quality_gate' <file> | grep -c '"wave_number"'`).
+ * Readers exist: `skills/session-end/metrics-collection.md` § 1.7 reads
+ * `counts` by `wave_number` first and keeps the STATE.md header only as a
+ * fallback (#966 step 3), and `scripts/lib/convergence-monitor.mjs` folds a
+ * gate record only when it carries both. THIS emitter still sets no
+ * `wave_number` — its records are mid-wave auto-fix retries, so they fall to
+ * that fallback by design. A record without the key could only be attributed
+ * to a wave by a wall-clock window whose own boundaries (`waves[].started_at`
+ * / `completed_at`) are themselves LLM-written, against the posture
+ * `scripts/lib/eval/session-resolve.mjs` documents for window-attributed gate
+ * events ("a contaminated window means gate-attribution is unsafe").
  *
  * Note also that THIS emitter only runs under `verification-auto-fix.enabled:
  * true` (default `false`, and `false` in this repo's Session Config). The gate

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,63 @@ 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 &&
+      parsed.entries.length === 0 &&
+      parsed.pairs.length === 1 &&
+      substantive.length === 1 &&
+      parsed.expiresAt !== null &&
+      ruleExpiryInstantMs(parsed.expiresAt) !== null
+    ) {
+      // SINGLE-ENTRY file (#1513): one learning, one pair, no `### ` entries,
+      // no counter sentence — the shape the reconciliation engine writes per
+      // learning in consumer repos (measured 2026-10-03: all 21 generated rules
+      // of the Meta-Vault). The fail-closed branch below skipped every one of
+      // them as `no-counter-sentence`, so they stayed on disk forever after
+      // expiry. Here the date is unambiguous — the file's own frontmatter
+      // `expires-at`, the one `rule-loader.mjs` acts on — and there is no
+      // body sentence to keep in agreement. The later of that date and the
+      // learning's store `expires_at` (when it resolves) decides, so a
+      // re-stamped learning never loses its rule. Expired → the same `delete`
+      // as a fully expired consolidated file: the pair is stamped terminal
+      // 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;
+      // 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,
+        expiredPairIds: [],
+        keptPairIds: [pair.id],
+        unresolvedPairIds: expiryById.has(pair.id) ? [] : [pair.id],
+        bytesBefore: Buffer.byteLength(content, 'utf8'),
+        headings: 0,
+        substantivePairs: 1,
+      };
+      if (effectiveAt <= cutoffMs) {
+        plans.push({
+          ...base,
+          expiredPairIds: [pair.id],
+          keptPairIds: [],
+          unresolvedPairIds: [],
+          action: 'delete',
+          reason: 'single-entry-expired',
+          newExpiresAt: null,
+          newAbsorbedCount: 0,
+          bytesAfter: 0,
+          stampKeys: [pair.key],
+        });
+      } else {
+        plans.push({ ...base, action: 'keep', newExpiresAt: null, newAbsorbedCount: 1, bytesAfter: base.bytesBefore });
+      }
+      continue;
+    }
 
     if (parsed.counterLine === -1) {
       // FAIL-CLOSED (GH#70). Every write this module performs moves the

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,10 +114,25 @@ 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'];
 
+/**
+ * Which outcomes reach the side-log (#1513). Only EVENTS — `backfilled`,
+ * `would-backfill`, `error` and any other non-skip action — are written; every
+ * `skipped-*` outcome is the steady state of a session close and stays out.
+ * Measured in the Meta-Vault 2026-10-03: 5.786 lines / 723 KB, 86 %
+ * `skipped-already-recorded`, one commit-worthy diff per close. The skips lose
+ * nothing: on-session-end emits every outcome, skips included, as a queryable
+ * event (#1068 AC2), and an injected `log` callback still receives them all.
+ *
+ * @param {unknown} action
+ * @returns {boolean}
+ */
+export function isLoggedBackfillAction(action) {
+  return typeof action === 'string' && !action.startsWith('skipped-');
+}
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -957,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) ----------------
@@ -1169,6 +1184,7 @@ export async function backfillAbandonedSession({
         return;
       }
       if (typeof repoRoot !== 'string' || repoRoot.length === 0) return;
+      if (!isLoggedBackfillAction(res.action)) return;
       const logPath = path.join(repoRoot, ...BACKFILL_LOG_REL);
       fs.mkdirSync(path.dirname(logPath), { recursive: true });
       fs.appendFileSync(
@@ -1351,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 ----
@@ -1432,6 +1448,7 @@ export async function backfillCompletedFromStateMd({
         return;
       }
       if (typeof repoRoot !== 'string' || repoRoot.length === 0) return;
+      if (!isLoggedBackfillAction(res.action)) return;
       const logPath = path.join(repoRoot, ...BACKFILL_LOG_REL);
       fs.mkdirSync(path.dirname(logPath), { recursive: true });
       fs.appendFileSync(