session-orchestrator 3.20.0 → 3.21.0

package/scripts/lib/io.mjs

@@ -17,7 +17,16 @@
  */
 
 import { writeFile, rename, mkdir } from 'node:fs/promises';
-import { mkdirSync, writeFileSync, renameSync, readFileSync, existsSync, writeSync } from 'node:fs';
+import {
+  mkdirSync,
+  writeFileSync,
+  renameSync,
+  readFileSync,
+  existsSync,
+  writeSync,
+  copyFileSync,
+  unlinkSync,
+} from 'node:fs';
 import path, { dirname } from 'node:path';
 import { randomBytes, randomUUID } from 'node:crypto';
 
@@ -556,6 +565,26 @@ export async function writeJsonAtomic(filePath, value, opts = {}) {
  * used from any layer without violating the layering rule in
  * `scripts/lib/hardening.mjs`.
  *
+ * Implementation: this is the JSON-serializing façade over
+ * {@link atomicWriteWithBackup} (`backup: false`) — the two functions carried
+ * the identical `mkdir → tmp → write → rename → catch` body 60 lines apart,
+ * which is the very duplication `atomicWriteWithBackup` was introduced to end.
+ * Everything below the `JSON.stringify` is the delegate's; the wrapper exists
+ * for the serialization step and for NARROWING the envelope (see @returns).
+ *
+ * Two things are deliberately kept here rather than pushed into the delegate:
+ *
+ *  - **The stringify stays inside a try.** `JSON.stringify` throws on a cycle
+ *    (and on a BigInt). Hoisting it above the delegation call would turn that
+ *    into an escaping TypeError, and 4 of the 9 caller files (`loop-guard`,
+ *    `lock-bootstrap`, `file-lock`, `issue-budget`) invoke this without a
+ *    try/catch of their own. A serialization failure reports as `fs-error`
+ *    because that is what this helper has always returned for it.
+ *  - **The success envelope is narrowed back to `{ ok: true }`.** The delegate
+ *    also reports `path`/`bytes`/`backupPath`; `session-lock.mjs#writeOwnerProof`
+ *    propagates THIS object verbatim on failure (`if (!w.ok) return w`), so the
+ *    key set is part of a contract that reaches further than this file.
+ *
  * @param {string} filePath  Target path; parent dirs created with mkdir -p semantics.
  * @param {*} data           JSON-serializable value.
  * @param {object} [opts]
@@ -565,15 +594,172 @@ export async function writeJsonAtomic(filePath, value, opts = {}) {
  */
 export function writeJsonAtomicSync(filePath, data, opts = {}) {
   const { indent = 2, tmpPrefix = '.tmp' } = opts;
+
+  let body;
+  try {
+    body = JSON.stringify(data, null, indent) + '\n';
+  } catch (err) {
+    return { ok: false, reason: 'fs-error', error: err?.message ?? String(err) };
+  }
+
+  const res = atomicWriteWithBackup(filePath, body, { tmpPrefix });
+  return res.ok ? { ok: true } : res;
+}
+
+/**
+ * Content-agnostic sibling of {@link writeJsonAtomicSync}: atomically replace a
+ * file with an arbitrary string/Buffer body, optionally snapshotting the
+ * previous contents to a timestamped `.bak-<ISO>` sidecar first (issue #734).
+ *
+ * The repo carries the copy→tmp→rename idiom in ~25 hand-rolled places
+ * (`learnings/io.mjs#rewriteLearnings`, `session-record-repair.mjs`,
+ * `owner-interview.mjs`, `backfill-learnings.mjs`, …). Each spelling differs in
+ * small ways — some take the backup, some do not; some `mkdir -p`, some assume
+ * the directory exists — which is exactly how a crash-safety guarantee rots.
+ * This helper is the shared spelling; **validation policy stays with the
+ * callers** (this function never inspects `body`).
+ *
+ * Crash-safety: write `<dir>/<tmpPrefix>.<rand>`, then `renameSync` over the
+ * target. Same-filesystem rename is atomic on POSIX, so an observer sees either
+ * the previous contents or the new ones — never a half-written file. The tmp
+ * file is created as a SIBLING of the target on purpose: a tmp in `os.tmpdir()`
+ * may sit on a different filesystem, where `rename` degrades to a non-atomic
+ * copy (EXDEV).
+ *
+ * Backup (`backup: true`) copies the CURRENT file to `<filePath>.bak-<ISO>`
+ * before the rename, with `:`/`.` swapped for `-` so a lexical sort of the
+ * siblings is chronological (same convention as `learnings/io.mjs`). A
+ * first-time write has nothing to lose, so no backup is taken when the target
+ * does not exist. **Rotation is deliberately NOT done here** — how many
+ * snapshots a store is worth is a per-caller policy (`learnings/io.mjs` keeps
+ * 3; a re-derivable file wants 0), and a keep-N default baked into the
+ * primitive would silently unlink a caller's snapshots.
+ *
+ * Caller is responsible for path-confinement — this helper does NOT validate
+ * that `filePath` lives inside the project (mirrors {@link writeJsonAtomic} /
+ * {@link writeJsonAtomicSync}).
+ *
+ * On a FAILED write the tmp sibling is unlinked (best-effort) before the error
+ * envelope is returned. Without that, every failed write leaves a
+ * `<tmpPrefix>.<hex>` behind — the board writer's failure mode is a retry loop,
+ * so the litter accumulates in the operator's vault directory. The cleanup is
+ * attempted only when the write actually created the tmp file, and its own
+ * failure is swallowed: a leaked tmp is worse than a silent unlink miss, and
+ * neither may mask the original error.
+ *
+ * ── BV-004 ceiling + revisit trigger ────────────────────────────────────────
+ * TWO PRODUCTION CALL-SITES: `vault-status/board-writer.mjs#writeBoard`
+ * (`backup: false`) and {@link writeJsonAtomicSync}, which carries 12 further
+ * call-sites across 9 files behind it. That second one is the load-bearing
+ * evidence — the previous revision of this note recorded ONE call-site and
+ * concluded the signature was unproven, while the function with an identical
+ * body sat 60 lines above in this same file, unmigrated. The cheapest possible
+ * migration going unmade is not a neutral fact about a helper: it is the
+ * measurement that the helper is not paying for itself.
+ *
+ * What the second call-site does NOT prove: `writeJsonAtomicSync` passes
+ * `backup: false` and no `fs`, so the backup half and the injection seam still
+ * rest on tests plus one board-writer flag. REVISIT TRIGGER — when a sweep
+ * migrates the remaining hand-rolled sites, re-check before widening:
+ * (a) whether an `async` twin is needed rather than bolting a promise mode onto
+ * this one (three known sites are `fs/promises`), and (b) whether rotation
+ * belongs here after all (it does only if ≥2 migrated callers want the SAME
+ * keep-N). If NO caller ever passes `backup: true` in production, that half is
+ * still the part to shrink back.
+ *
+ * @param {string} filePath  Target path; parent dirs created with mkdir -p semantics.
+ * @param {string|Buffer} body  Bytes to write, verbatim. Never inspected.
+ * @param {object} [opts]
+ * @param {BufferEncoding} [opts.encoding='utf8']  Encoding for a string `body`.
+ * @param {boolean} [opts.backup=false]  Snapshot the existing file to `.bak-<ISO>` first.
+ * @param {string} [opts.tmpPrefix='.tmp']  Tmp-file prefix (callers pick their domain prefix).
+ * @param {Date} [opts.now]  Clock seam for the backup stamp (tests).
+ * @param {{ mkdirSync?: Function, writeFileSync?: Function, renameSync?: Function,
+ *   copyFileSync?: Function, existsSync?: Function, unlinkSync?: Function }} [opts.fs]
+ *   Injectable fs (tests). Omitted methods fall back to `node:fs` — EXCEPT on
+ *   the backup path, which fails closed (see below).
+ * @returns {{ ok: true, path: string, bytes: number, backupPath: string|null }
+ *   | { ok: false, reason: 'fs-error', error: string }}
+ */
+export function atomicWriteWithBackup(filePath, body, opts = {}) {
+  const {
+    encoding = 'utf8',
+    backup = false,
+    tmpPrefix = '.tmp',
+    now = new Date(),
+    fs: injectedFs,
+  } = opts;
+
+  const fsMkdir = injectedFs?.mkdirSync ?? mkdirSync;
+  const fsWriteFile = injectedFs?.writeFileSync ?? writeFileSync;
+  const fsRename = injectedFs?.renameSync ?? renameSync;
+  const fsCopyFile = injectedFs?.copyFileSync ?? copyFileSync;
+  const fsExists = injectedFs?.existsSync ?? existsSync;
+  const fsUnlink = injectedFs?.unlinkSync ?? unlinkSync;
+
+  // ── Partial-adapter fail-closed, backup path only ──────────────────────────
+  //
+  // Per-method fallback to the real `node:fs` is the right default for the
+  // three ALWAYS-used methods: `board-writer.mjs#writeBoard` passes an fs object
+  // on EVERY call, including production, where `renameSync`/`copyFileSync` are
+  // present-but-`undefined` because nothing was injected. "An injected object
+  // must be total" would therefore reject the only real caller — the shape is
+  // not evidence of a fake.
+  //
+  // The backup path is different in kind. It runs ONLY under `backup: true`, and
+  // there a missing method routes a real `copyFileSync`/`existsSync` at the real
+  // filesystem while the write goes to the fake: a suite that believes itself
+  // hermetic drops `.bak-<ISO>` files into the repo, and nothing says so. Both
+  // methods are guarded, not just `copyFileSync` — a missing `existsSync` probes
+  // the real target and silently decides the backup branch from it, which is the
+  // same escape one step earlier.
+  if (backup && injectedFs) {
+    for (const method of ['existsSync', 'copyFileSync']) {
+      if (typeof injectedFs[method] !== 'function') {
+        return {
+          ok: false,
+          reason: 'fs-error',
+          error: `partial fs adapter: ${method} required for backup`,
+        };
+      }
+    }
+  }
+
+  let tmpFile = null;
+  let tmpCreated = false;
+
   try {
     const dir = dirname(filePath);
-    mkdirSync(dir, { recursive: true });
-    const tmpSuffix = randomBytes(6).toString('hex');
-    const tmpFile = path.join(dir, `${tmpPrefix}.${tmpSuffix}`);
-    writeFileSync(tmpFile, JSON.stringify(data, null, indent) + '\n', { encoding: 'utf8' });
-    renameSync(tmpFile, filePath);
-    return { ok: true };
+    fsMkdir(dir, { recursive: true });
+
+    let backupPath = null;
+    if (backup && fsExists(filePath)) {
+      const stamp = (now instanceof Date ? now : new Date()).toISOString().replace(/[:.]/g, '-');
+      backupPath = `${filePath}.bak-${stamp}`;
+      fsCopyFile(filePath, backupPath);
+    }
+
+    tmpFile = path.join(dir, `${tmpPrefix}.${randomBytes(6).toString('hex')}`);
+    fsWriteFile(tmpFile, body, encoding);
+    tmpCreated = true;
+    fsRename(tmpFile, filePath);
+
+    return {
+      ok: true,
+      path: filePath,
+      bytes: Buffer.isBuffer(body) ? body.length : Buffer.byteLength(String(body), encoding),
+      backupPath,
+    };
   } catch (err) {
+    // Only when the write got far enough to create it. The name carries 12 hex
+    // chars of entropy, so this cannot collide with a caller's real file.
+    if (tmpCreated) {
+      try {
+        fsUnlink(tmpFile);
+      } catch {
+        // Best-effort: never let cleanup replace the error the caller needs.
+      }
+    }
     return { ok: false, reason: 'fs-error', error: err?.message ?? String(err) };
   }
 }

package/scripts/lib/learnings/select.mjs

@@ -52,6 +52,35 @@
  *     #1015 hardened for `.claude/rules/`. The primitives are imported, never
  *     re-implemented: a second copy is how this channel shipped raw beside the
  *     hardened one in the first place.
+ *   - `extractProvenance()` from `../validate/check-learning-provenance.mjs` and
+ *     `learningKeyOf()` from `./kebab.mjs` — the already-delivered filter below.
+ *     Both readers already exist; a second provenance parser here would be the
+ *     "same fact in two copies" defect this repo keeps paying for.
+ *
+ * ## Already-delivered filter (#1019)
+ *
+ * `/reconcile` converts a learning into a `.claude/rules/*.md` file, and Claude
+ * Code delivers every such file to every dispatched agent NATIVELY, in full.
+ * Measured first-person 2026-08-15 @fd73548+wave-2: a wave subagent's context
+ * carried all 29 of `.claude/rules/*.md` — `alwaysApply: false` and `globs:`
+ * notwithstanding, because `rule-loader.mjs` (the only code that understands
+ * that frontmatter) does not run on the delivery path
+ * (`docs/instruction-delivery.md` §1/§1.1). So a rule-derived learning that also
+ * enters this index arrives TWICE, and the second copy costs a slot in a
+ * 2000-char budget — displacing a learning the agent would otherwise never see.
+ *
+ * The filter therefore runs BEFORE the split caps, not after: dropping a
+ * duplicate after the Top-N cut would remove the line without freeing its slot,
+ * which is the whole harm. Two axes, mirroring the provenance checker's own
+ * `dangling` / `superseded` split: the rule's `learning-id` (exact record) and
+ * its `learning-key` (logical identity, stable across a re-minted UUID — the
+ * state any id backfill lands in). 13 of 29 rules carry provenance and all 13
+ * resolve by id today, so the key axis is currently inert by measurement, not
+ * by design.
+ *
+ * SILENT NO-OP is a hard requirement: no rules directory, no `.md` files, or no
+ * provenance block anywhere ⇒ empty sets ⇒ byte-identical output. A repo without
+ * `/reconcile` must never see FEWER learnings because this filter exists.
  *
  * NOT used: `filterByScope()` from `./filters.mjs`. Despite the name it filters
  * the PRIVACY enum `['local','private','public']` (schema.mjs), not file scope.
@@ -96,12 +125,17 @@
  *   5. Expired and sub-floor entries are never selected.
  */
 
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
 import { affinity } from './affinity.mjs';
 import {
   INSIGHT_MAX_BYTES,
   TITLE_MAX_BYTES,
   sanitizeProse,
 } from '../reconcile/sanitize.mjs';
+import { learningKeyOf } from './kebab.mjs';
+import { extractProvenance } from '../validate/check-learning-provenance.mjs';
 import { DECAY_DEFAULTS, effectiveScore, surfaceTopN } from './surface.mjs';
 
 // ---------------------------------------------------------------------------
@@ -178,9 +212,15 @@ export const DEFAULT_CONFIDENCE_FLOOR = 0.3;
  * @typedef {{entries: object[], selected: SelectedLearning[], lines: string[],
  *            text: string, chars: number, scopeMatched: number,
  *            globalCount: number, candidates: number, truncated: boolean,
- *            rejected: number}} Selection
+ *            rejected: number, deliveredFiltered: number}} Selection
  *   `rejected` counts records dropped by the untrusted-text guard — surfaced so
  *   a drop is observable in the injection event rather than silent.
+ *   `deliveredFiltered` counts records dropped because a `.claude/rules/*.md`
+ *   file already delivers them natively (#1019) — same reason, and it is the
+ *   only way to tell "the filter bit" from "the corpus has no such learning".
+ *
+ * @typedef {{ids: Set<string>, keys: Set<string>}} DeliveredProvenance
+ *   Learning ids and logical keys already delivered as `.claude/rules/*.md`.
  */
 
 // ---------------------------------------------------------------------------
@@ -214,6 +254,43 @@ function _isActive(entry, nowMs, confidenceFloor) {
   return true;
 }
 
+/**
+ * Normalize a caller-supplied delivered-provenance option into two Sets, or
+ * `null` when there is nothing to filter against.
+ *
+ * `null` (not empty Sets) is the no-filter signal so the hot loop can skip the
+ * per-entry `learningKeyOf()` call entirely — and so the SILENT NO-OP guarantee
+ * is one explicit branch rather than an emergent property of empty membership.
+ *
+ * @param {unknown} v `{ids, keys}` with Sets or arrays; anything else ⇒ `null`
+ * @returns {DeliveredProvenance|null}
+ */
+function _resolveDelivered(v) {
+  if (!_isRecord(v)) return null;
+  const toSet = (x) => (x instanceof Set ? x : Array.isArray(x) ? new Set(x) : new Set());
+  const ids = toSet(v.ids);
+  const keys = toSet(v.keys);
+  return ids.size === 0 && keys.size === 0 ? null : { ids, keys };
+}
+
+/**
+ * True when this learning already reaches the agent as a natively-delivered
+ * `.claude/rules/*.md` file.
+ *
+ * Id first (exact record), then the logical key — a rule whose `learning-id`
+ * was re-minted by a backfill still delivers the same content, which is the
+ * `superseded-learning-id` state `check-learning-provenance.mjs` names.
+ *
+ * @param {object} entry
+ * @param {DeliveredProvenance} delivered
+ * @returns {boolean}
+ */
+function _isDelivered(entry, delivered) {
+  if (typeof entry.id === 'string' && entry.id !== '' && delivered.ids.has(entry.id)) return true;
+  const key = learningKeyOf(entry); // total: a shape-foreign entry yields null
+  return key !== null && delivered.keys.has(key);
+}
+
 /** Epoch ms from a Date | number | undefined clock option. */
 function _resolveNowMs(now) {
   if (now instanceof Date) return now.getTime();
@@ -274,9 +351,60 @@ export function emptySelection() {
     candidates: 0,
     truncated: false,
     rejected: 0,
+    deliveredFiltered: 0,
   };
 }
 
+/**
+ * Read the provenance pointers of every `.claude/rules/*.md` — the set of
+ * learnings the agent already receives natively (#1019).
+ *
+ * Reuses `extractProvenance()` rather than re-deriving the block format. Total
+ * by construction: an absent, unreadable or provenance-free directory yields
+ * empty sets, which {@link selectLearnings} reads as "no filter" (SILENT NO-OP).
+ *
+ * Read discipline mirrors `check-learning-provenance.mjs`: `readFileSync`, never
+ * a `grep` spawn — one NUL byte makes a text file invisible to a grep-based
+ * audit, and a silently-skipped rule file reads exactly like a rule with no
+ * provenance.
+ *
+ * Ceiling: one synchronous read per rule file, linear in the corpus (29 files /
+ * ~170 KB today). Revisit — cache per process or read async — if
+ * `.claude/rules/` passes a few hundred files.
+ *
+ * @param {string} rulesDir absolute path to the `.claude/rules` directory
+ * @returns {DeliveredProvenance}
+ */
+export function readDeliveredProvenance(rulesDir) {
+  /** @type {Set<string>} */
+  const ids = new Set();
+  /** @type {Set<string>} */
+  const keys = new Set();
+  if (typeof rulesDir !== 'string' || rulesDir.trim() === '') return { ids, keys };
+
+  /** @type {string[]} */
+  let names;
+  try {
+    names = readdirSync(rulesDir);
+  } catch {
+    return { ids, keys }; // no rules directory ⇒ nothing is natively delivered
+  }
+
+  for (const name of names) {
+    if (!name.endsWith('.md')) continue;
+    let body;
+    try {
+      body = readFileSync(join(rulesDir, name), 'utf8');
+    } catch {
+      continue; // one unreadable rule must not cost the whole census
+    }
+    const { id, key } = extractProvenance(body);
+    if (id) ids.add(id);
+    if (key) keys.add(key);
+  }
+  return { ids, keys };
+}
+
 /**
  * Truncate to at most `maxUnits` UTF-16 code units, cutting on a CODE-POINT
  * boundary.
@@ -413,6 +541,9 @@ export function scoreLearning(entry, scope, opts = {}) {
  * @param {Date|number} [opts.now] — injectable clock
  * @param {object} [opts.decay] — #670 decay tuning, forwarded to effectiveScore
  * @param {object} [opts.affinityOpts] — forwarded to affinity()
+ * @param {DeliveredProvenance} [opts.delivered] — learnings already delivered
+ *   natively as `.claude/rules/*.md` (#1019); omitted/empty ⇒ no filtering, and
+ *   the selection is byte-identical to the pre-filter one
  * @returns {Selection}
  */
 export function selectLearnings(entries, scope, opts = {}) {
@@ -433,6 +564,7 @@ export function selectLearnings(entries, scope, opts = {}) {
         ? o.confidenceFloor
         : DEFAULT_CONFIDENCE_FLOOR;
     const nowMs = _resolveNowMs(o.now);
+    const delivered = _resolveDelivered(o.delivered);
     const scoreOpts = { now: nowMs, decay: o.decay, affinityOpts: o.affinityOpts };
 
     /** @type {SelectedLearning[]} */
@@ -441,12 +573,23 @@ export function selectLearnings(entries, scope, opts = {}) {
     const global = [];
     let candidates = 0;
     let rejected = 0;
+    let deliveredFiltered = 0;
 
     for (const entry of entries) {
       if (!_isRecord(entry)) continue;
       if (!_isActive(entry, nowMs, confidenceFloor)) continue;
       candidates++;
 
+      // #1019 — BEFORE the split caps below, never after. This entry already
+      // reaches the agent in full as a `.claude/rules/*.md` file; dropping it
+      // here frees its slot for a learning the agent would otherwise never see,
+      // whereas dropping it after the Top-N cut would only shorten the index.
+      // `candidates` still counts it: the pool it was drawn from is unchanged.
+      if (delivered !== null && _isDelivered(entry, delivered)) {
+        deliveredFiltered++;
+        continue;
+      }
+
       const s = scoreLearning(entry, scope, scoreOpts);
       // Fail CLOSED per entry: a record whose text forges the delivery wrapper
       // is dropped, not neutralised in place — with 100 candidates competing for
@@ -510,6 +653,7 @@ export function selectLearnings(entries, scope, opts = {}) {
       candidates,
       truncated,
       rejected,
+      deliveredFiltered,
     };
   } catch {
     // Contract point 1 — a ranking primitive on the dispatch hot path must
@@ -525,7 +669,11 @@ export function selectLearnings(entries, scope, opts = {}) {
  * @param {string} filePath — absolute path to learnings.jsonl
  * @param {AgentScope} scope
  * @param {object} [opts] — everything {@link selectLearnings} accepts, plus
- *   `poolSize` (how many active entries to pull before ranking).
+ *   `poolSize` (how many active entries to pull before ranking) and `rulesDir`
+ *   (absolute `.claude/rules` path; read via {@link readDeliveredProvenance} into
+ *   the `delivered` filter). `rulesDir` is EXPLICIT rather than derived from
+ *   `filePath`: guessing a repo root from a metrics path is the hand-maintained
+ *   fact this repo keeps getting wrong. Omit it and nothing is filtered.
  * @returns {Promise<Selection>} `emptySelection()` on a missing/unreadable file
  */
 export async function selectLearningsFromFile(filePath, scope, opts = {}) {
@@ -538,12 +686,18 @@ export async function selectLearningsFromFile(filePath, scope, opts = {}) {
         ? o.confidenceFloor
         : DEFAULT_CONFIDENCE_FLOOR;
 
+    const delivered = _isRecord(o.delivered)
+      ? o.delivered
+      : typeof o.rulesDir === 'string' && o.rulesDir.trim() !== ''
+        ? readDeliveredProvenance(o.rulesDir)
+        : undefined;
+
     const entries = await surfaceTopN(filePath, poolSize, {
       now: nowMs,
       confidenceFloor,
       decay: o.decay,
     });
-    return selectLearnings(entries, scope, { ...o, now: nowMs, confidenceFloor });
+    return selectLearnings(entries, scope, { ...o, now: nowMs, confidenceFloor, delivered });
   } catch {
     return emptySelection();
   }

package/scripts/lib/memory-cleanup-stamp.mjs

@@ -1,20 +1,41 @@
 /**
- * memory-cleanup-stamp.mjs — Pure helper: stamp `memory_cleanup_at` on a
- * session record when `/memory-cleanup` ran this session.
+ * memory-cleanup-stamp.mjs — stamp `memory_cleanup_at` on a session record when
+ * `/memory-cleanup` ran this session, and DERIVE that fact from the event log
+ * instead of from coordinator recall.
  *
  * Issue #699 fix: a healthy no-op run of `/memory-cleanup` previously left
  * `memory_cleanup_at` unstamped, so `auto-dream.mjs` `readDreamSignals`
  * never advanced `lastCleanupAt` and `shouldDispatchAutoDream` kept firing a
- * false nudge. This helper stamps the field unconditionally whenever the
- * cleanup ran — including a healthy no-op where no memory files were mutated.
+ * false nudge. `stampMemoryCleanup()` stamps the field unconditionally whenever
+ * the cleanup ran — including a healthy no-op where no memory files were mutated.
+ *
+ * #699 follow-up (Disziplin statt Mechanik): the `ranCleanup` boolean itself used
+ * to come from the coordinator-LLM remembering a prose step at session-end. It
+ * measurably failed — a `/memory-cleanup` ran on 2026-08-14 and all three session
+ * records of that day read `memory_cleanup_at: null`, so the session-start banner
+ * reported "29 days ago" while the operator's own notes said 3. Since then
+ * `/memory-cleanup` emits `orchestrator.memory.cleanup_completed` and
+ * `deriveMemoryCleanupSignal()` reads that event back out of
+ * `.orchestrator/metrics/events.jsonl`, which is what `scripts/emit-session.mjs`
+ * calls at write time. Nothing depends on recall any more.
  *
  * Design constraints:
- *   - Pure function — no I/O, no side-effects.
- *   - No-throw — invalid inputs return the record unchanged (defensive).
- *   - Testable seam — the Quality wave (Q2) unit-tests this function directly.
- *   - No external deps — Node 20+ stdlib only (none needed here).
+ *   - `stampMemoryCleanup()` stays pure — no I/O, no side-effects.
+ *   - No-throw — invalid inputs / unreadable-or-corrupt event log return the
+ *     "no cleanup" answer rather than blocking a session close.
+ *   - Testable seam — both functions are unit-tested directly.
+ *   - No external deps — Node stdlib only.
  */
 
+import { readFileSync } from 'node:fs';
+
+/**
+ * Event `/memory-cleanup` emits when a run completes (any mode, any outcome —
+ * including a healthy no-op). Emitted via `scripts/emit-event.mjs` → the
+ * canonical `emitEvent()` path; see `skills/memory-cleanup/SKILL.md` § Output.
+ */
+export const MEMORY_CLEANUP_EVENT = 'orchestrator.memory.cleanup_completed';
+
 /**
  * Stamp `memory_cleanup_at` on a session record when `/memory-cleanup` ran.
  *
@@ -54,3 +75,106 @@ export function stampMemoryCleanup(record, { ranCleanup, completedAt } = {}) {
   // Return a shallow clone with the stamp applied — never mutate the input.
   return { ...record, memory_cleanup_at: completedAt };
 }
+
+/**
+ * Derive "did `/memory-cleanup` run in THIS session?" from the event log.
+ *
+ * Reads `eventsFile` and looks for `orchestrator.memory.cleanup_completed`
+ * records that fall inside the session's own `[startedAt, completedAt]` window.
+ * This is the mechanical replacement for the coordinator-supplied boolean.
+ *
+ * Matching rule (two clauses, both mechanical):
+ *   1. the event's `timestamp` lies within `[startedAt, completedAt]` inclusive;
+ *   2. IF the event carries a non-empty `semantic_session_id`, it must equal
+ *      `sessionId` (sessions.jsonl `session_id` is the SEMANTIC id — the UUID
+ *      `session_id` some events carry lives in a different id space and is
+ *      deliberately NOT used for matching).
+ *
+ * Named ceiling (deliberate simplification): an event with NO attribution is
+ * claimed on the window alone, so two parallel sessions in one repo with
+ * overlapping windows both derive `ranCleanup: true`. The consequence is a
+ * marginally generous cadence marker on the peer's record — never a MISSED
+ * cleanup, which is the failure this whole path exists to prevent. Revisit
+ * trigger: if per-session cleanup accounting is ever needed, attach
+ * `semantic_session_id` to the emitted event and clause 2 makes it exact.
+ * Scan cost is a single linear pass over `events.jsonl` (~23k lines,
+ * size-rotated at SessionStart by `events-rotation.mjs`) — revisit if rotation
+ * is ever removed.
+ *
+ * No-throw: a missing, unreadable, or partly-corrupt event log yields
+ * `{ ranCleanup: false, ... }`. A session close must never fail because
+ * telemetry is damaged.
+ *
+ * @param {object} opts
+ * @param {string} opts.eventsFile  Absolute or CWD-relative path to events.jsonl.
+ * @param {string} [opts.sessionId] The record's `session_id` (semantic form).
+ * @param {string} opts.startedAt   Session `started_at` (ISO-8601).
+ * @param {string} opts.completedAt Session `completed_at` (ISO-8601).
+ * @returns {{ranCleanup: boolean, at: string|null, matches: number}}
+ *   `at` is the LATEST matching event timestamp (null when none matched);
+ *   `matches` is how many events matched (a run can emit more than one).
+ */
+export function deriveMemoryCleanupSignal({
+  eventsFile,
+  sessionId,
+  startedAt,
+  completedAt,
+} = {}) {
+  const none = { ranCleanup: false, at: null, matches: 0 };
+
+  if (typeof eventsFile !== 'string' || eventsFile.length === 0) return none;
+
+  const startMs = Date.parse(startedAt);
+  const endMs = Date.parse(completedAt);
+  if (!Number.isFinite(startMs) || !Number.isFinite(endMs) || endMs < startMs) {
+    return none;
+  }
+
+  let raw;
+  try {
+    raw = readFileSync(eventsFile, 'utf8');
+  } catch {
+    // Missing / unreadable event log — no signal, never an error.
+    return none;
+  }
+
+  const wantSession = typeof sessionId === 'string' && sessionId.length > 0 ? sessionId : null;
+  let matches = 0;
+  let latestMs = -Infinity;
+  let latestTs = null;
+
+  for (const line of raw.split('\n')) {
+    // Cheap substring prefilter before the JSON.parse cost.
+    if (line.length === 0 || !line.includes(MEMORY_CLEANUP_EVENT)) continue;
+
+    let rec;
+    try {
+      rec = JSON.parse(line);
+    } catch {
+      continue; // corrupt line — skip, best-effort reader
+    }
+    if (rec === null || typeof rec !== 'object' || Array.isArray(rec)) continue;
+    if (rec.event !== MEMORY_CLEANUP_EVENT) continue;
+
+    const tsMs = Date.parse(rec.timestamp);
+    if (!Number.isFinite(tsMs) || tsMs < startMs || tsMs > endMs) continue;
+
+    const semantic = rec.semantic_session_id;
+    if (
+      wantSession !== null &&
+      typeof semantic === 'string' &&
+      semantic.length > 0 &&
+      semantic !== wantSession
+    ) {
+      continue; // attributed to a DIFFERENT session — not ours
+    }
+
+    matches += 1;
+    if (tsMs > latestMs) {
+      latestMs = tsMs;
+      latestTs = rec.timestamp;
+    }
+  }
+
+  return { ranCleanup: matches > 0, at: latestTs, matches };
+}