session-orchestrator 5.3.0 → 5.4.0

package/scripts/lib/gates/gate-incremental.mjs

@@ -6,7 +6,7 @@
 // Required env: TYPECHECK_CMD, TEST_CMD
 // Optional env: FILES (comma-separated), SESSION_START_REF
 
-import { runCheck, resolveTestFiles, extractErrorLinesJson } from './gate-helpers.mjs';
+import { runCheck, resolveTestFiles, extractErrorLinesJson, commandKillFields } from './gate-helpers.mjs';
 
 const typecheckCmd = process.env.TYPECHECK_CMD;
 const testCmd = process.env.TEST_CMD;
@@ -49,41 +49,32 @@ if (!testCmd) {
 
 const start = Date.now();
 
-let testStatus;
+// A skipped test run spawned nothing: `{ status: 'skip' }`, no kill keys.
+let testResult = { status: 'skip' };
 let errors = [];
 
 // --- typecheck (always runs unless cmd is "skip") ---
 const tcResult = await runCheck(typecheckCmd, CHECK_OPTS);
-const tcStatus = tcResult.status;
-if (tcStatus === 'fail') {
+if (tcResult.status === 'fail') {
   errors = errors.concat(extractErrorLinesJson(tcResult.output, /error TS\d+/));
 }
 
 // --- test (scoped to changed/specified files) ---
-if (testCmd === 'skip') {
-  testStatus = 'skip';
-} else {
+if (testCmd !== 'skip') {
   const testFiles = await resolveTestFiles(files, sessionStartRef);
   if (testFiles.length > 0) {
     const fileArgs = testFiles.join(' ');
-    const testResult = await runCheck(`${testCmd} -- ${fileArgs}`, CHECK_OPTS);
-    testStatus = testResult.status;
-    if (testStatus === 'fail') {
-      const testErrors = extractErrorLinesJson(testResult.output, /(fail|error|FAIL)/i);
-      errors = errors.concat(testErrors);
-    }
+    testResult = await runCheck(`${testCmd} -- ${fileArgs}`, CHECK_OPTS);
   } else if (!files && !sessionStartRef) {
     // No FILES or SESSION_START_REF supplied: run the full test suite
-    const testResult = await runCheck(testCmd, CHECK_OPTS);
-    testStatus = testResult.status;
-    if (testStatus === 'fail') {
-      const testErrors = extractErrorLinesJson(testResult.output, /(fail|error|FAIL)/i);
-      errors = errors.concat(testErrors);
-    }
+    testResult = await runCheck(testCmd, CHECK_OPTS);
   } else {
     // Files/ref supplied but no test files found — skip
     process.stderr.write('warn: No test files found for incremental run; skipping tests\n');
-    testStatus = 'skip';
+  }
+  if (testResult.status === 'fail') {
+    const testErrors = extractErrorLinesJson(testResult.output, /(fail|error|FAIL)/i);
+    errors = errors.concat(testErrors);
   }
 }
 
@@ -92,8 +83,18 @@ const duration_seconds = Math.round((Date.now() - start) / 1000);
 const result = {
   variant: 'incremental',
   duration_seconds,
-  typecheck: tcStatus,
-  test: testStatus,
+  // Each command object also carries its INNER kill ladder (`timed_out`,
+  // `kill_signals`, `survivors` pids) when `runCheck` spawned it — omitted for
+  // skip/stub (#1457). `run-quality-gate.mjs` joins them into its event.
+  typecheck: { status: tcResult.status, ...commandKillFields(tcResult) },
+  test: { status: testResult.status, ...commandKillFields(testResult) },
+  // Stub map, same shape as gate-full: a command `runCheck` recognised as a
+  // stub (`echo …`/`true`) spawned nothing, so `joinGateKillFields` may count
+  // it as measured instead of declaring the whole inner ladder unknown.
+  stubbed: {
+    ...(tcResult.stubbed ? { typecheck: tcResult.stubbed } : {}),
+    ...(testResult.stubbed ? { test: testResult.stubbed } : {}),
+  },
   errors,
 };
 

package/scripts/lib/gates/gate-per-file.mjs

@@ -9,7 +9,7 @@
  * Part of v3.2 shell-helper port migration (issue #218 / #317).
  */
 
-import { runCheck, csvToJsonArray } from './gate-helpers.mjs';
+import { runCheck, csvToJsonArray, commandKillFields } from './gate-helpers.mjs';
 
 const typecheckCmd = process.env.TYPECHECK_CMD;
 const testCmd = process.env.TEST_CMD;
@@ -59,20 +59,29 @@ if (files.length === 0) {
 
 // Typecheck runs on the whole project, not per-file
 const tcResult = await runCheck(typecheckCmd, CHECK_OPTS);
-const tcStatus = tcResult.status;
 
-let testStatus = 'skip';
+// A skipped test run spawned nothing: `{ status: 'skip' }`, no kill keys.
+let testResult = { status: 'skip' };
 
 if (testCmd !== 'skip' && files.length > 0) {
   const fileArgs = files.join(' ');
-  const testResult = await runCheck(`${testCmd} -- ${fileArgs}`, CHECK_OPTS);
-  testStatus = testResult.status;
+  testResult = await runCheck(`${testCmd} -- ${fileArgs}`, CHECK_OPTS);
 }
 
 const result = {
   variant: 'per-file',
-  typecheck: tcStatus,
-  test: testStatus,
+  // Each command object also carries its INNER kill ladder (`timed_out`,
+  // `kill_signals`, `survivors` pids) when `runCheck` spawned it — omitted for
+  // skip/stub (#1457). `run-quality-gate.mjs` joins them into its event.
+  typecheck: { status: tcResult.status, ...commandKillFields(tcResult) },
+  test: { status: testResult.status, ...commandKillFields(testResult) },
+  // Stub map, same shape as gate-full: a command `runCheck` recognised as a
+  // stub (`echo …`/`true`) spawned nothing, so `joinGateKillFields` may count
+  // it as measured instead of declaring the whole inner ladder unknown.
+  stubbed: {
+    ...(tcResult.stubbed ? { typecheck: tcResult.stubbed } : {}),
+    ...(testResult.stubbed ? { test: testResult.stubbed } : {}),
+  },
   files,
 };
 

package/scripts/lib/instruction-budget-guard.mjs

@@ -47,6 +47,16 @@
  * tier-gate conditionals `applyGates` already implements (the `context`
  * param below is the exact mechanism rule-loader exposes for this).
  *
+ * #1449: that membership now matches what Claude Code actually loads. The
+ * loader used to skip a leading provenance comment before `---`, so a rule
+ * Claude Code loads always-on (it reads frontmatter only from line 1) counted
+ * here as path-scoped, and every consumer's always-on total was short by the
+ * vendored rules carrying that header. Such a file now counts as always-on —
+ * its displaced frontmatter as body bytes, since that is how Claude Code
+ * delivers it — and is listed in `defects` and on its own banner line. The
+ * list is report-only: it is not an `overBudget` term, so a defect never turns
+ * a budget verdict red.
+ *
  * Cross-references:
  * - "2026-06-20 instruction-budget audit" (#668 / #687; archived in the private Meta-Vault)
  * - scripts/lib/rule-loader.mjs (always-on classification + tier-gate SSOT)
@@ -79,7 +89,11 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { basename, join } from 'node:path';
 import { scanEventsBackwards } from './events.mjs';
-import { loadApplicableRules, parseGlobsFrontmatter } from './rule-loader.mjs';
+import {
+  FRONTMATTER_NOT_AT_TOP,
+  loadApplicableRules,
+  parseGlobsFrontmatter,
+} from './rule-loader.mjs';
 
 /** Default directive ceiling (operator-chosen growth ratchet just above the ~457 baseline). */
 export const DEFAULT_CEILING = 480;
@@ -1055,12 +1069,18 @@ function measureRuleCorpora(rulesDir) {
  *   bySurface: { coordinator: number, wave: number, always: number,
  *               generated: {bytes: number, files: number},
  *               pathScoped: {bytes: number, files: number} },
+ *   defects: string[],
  * }}
- *   perFile is sorted DESC by count. On missing/unreadable dir →
+ *   perFile is sorted DESC by count. `defects` (#1449) lists, sorted by name,
+ *   the rule files whose frontmatter does not start on line 1 — Claude Code
+ *   ignores it, so they load always-on and are counted as such. It is
+ *   independent of `context` (such a file has no tier to gate on) and never
+ *   feeds `overBudget`. On missing/unreadable dir →
  *   { totalDirectives: 0, totalBytes: 0, perFile: [], ceiling, byteCeiling,
  *     overDirectiveBudget: false, overByteBudget: false, overBudget: false,
  *     severity: 'ok', bySurface: { coordinator: 0, wave: 0, always: 0,
- *     generated: {bytes:0,files:0}, pathScoped: {bytes:0,files:0} } }.
+ *     generated: {bytes:0,files:0}, pathScoped: {bytes:0,files:0} },
+ *     defects: [] }.
  *
  *   #931a verdict rule — `overBudget` is the OR of the two axes
  *   (`overDirectiveBudget || overByteBudget`), NOT a per-axis severity split:
@@ -1165,6 +1185,7 @@ export function computeInstructionBudget(opts = {}) {
       generated: { bytes: 0, files: 0 },
       pathScoped: { bytes: 0, files: 0 },
     },
+    defects: [],
   };
 
   let allEntries;
@@ -1256,6 +1277,13 @@ export function computeInstructionBudget(opts = {}) {
   const overPathScopedBudget = bySurface.pathScoped.bytes > pathScopedByteCeiling;
   const overBudget = overDirectiveBudget || overByteBudget || overGeneratedBudget || overPathScopedBudget;
 
+  // #1449: read off the untiered list — a defective file carries no meta, so
+  // no tier gate drops it and `alwaysOnAll` holds every one of them.
+  const defects = alwaysOnAll
+    .filter((e) => e.defect === FRONTMATTER_NOT_AT_TOP)
+    .map((e) => basename(e.path))
+    .sort((a, b) => a.localeCompare(b));
+
   return {
     totalDirectives,
     totalBytes,
@@ -1271,6 +1299,7 @@ export function computeInstructionBudget(opts = {}) {
     overBudget,
     severity: overBudget ? 'warn' : 'ok',
     bySurface,
+    defects,
   };
 }
 
@@ -1351,6 +1380,21 @@ function formatNearPathScopedLine(budget, repoRoot) {
   );
 }
 
+/**
+ * The #1449 defect line: rule files whose frontmatter Claude Code never reads.
+ * Names every file — the fix is per file (move the text above `---` below the
+ * closing fence), so a count alone would send the operator hunting.
+ *
+ * @param {string[]} defects - basenames from `computeInstructionBudget().defects`
+ * @returns {string}
+ */
+function formatFrontmatterDefectLine(defects) {
+  return (
+    `⚠ ${defects.length} rule(s) carry frontmatter that Claude Code ignores ` +
+    `(text before the opening ---): ${defects.join(', ')} — they load always-on.`
+  );
+}
+
 /**
  * Banner wrapper — session-start Phase 4 convention.
  *
@@ -1367,7 +1411,9 @@ function formatNearPathScopedLine(budget, repoRoot) {
  *
  * The message names WHICH axis breached (#931a) — a banner that only said
  * "over budget" would leave the operator guessing whether to prune bullets or
- * prose. It stays at three lines because it renders at every session start.
+ * prose. It stays short because it renders at every session start: the breach
+ * block is three lines, plus one line per extra finding (near-threshold,
+ * frontmatter defect).
  *
  * @param {object} [opts]  forwarded to computeInstructionBudget.
  * @param {string} [opts.repoRoot] project root for the config read.
@@ -1382,8 +1428,10 @@ function formatNearPathScopedLine(budget, repoRoot) {
  *   raises it at {@link PATH_SCOPED_NEAR_THRESHOLD} of its ceiling, before the
  *   breach: that band used to be silent, and the ceiling then surfaced only
  *   inside `writeApprovedRules` — after the operator had approved rules it
- *   refused to write. The RETURN SHAPE is unchanged (`{severity:'warn',
- *   message}` | null), so `session-start-probes.mjs` needs no new vocabulary.
+ *   refused to write. Since #1449 a rule whose frontmatter is not on line 1
+ *   raises it too (one line naming the files), whether or not any axis is
+ *   close. The RETURN SHAPE is unchanged (`{severity:'warn', message}` |
+ *   null), so `session-start-probes.mjs` needs no new vocabulary.
  */
 export function checkInstructionBudget(opts = {}) {
   let cfg;
@@ -1455,18 +1503,27 @@ export function checkInstructionBudget(opts = {}) {
     budget.pathScopedByteCeiling > 0 &&
     budget.bySurface.pathScoped.bytes >= budget.pathScopedByteCeiling * PATH_SCOPED_NEAR_THRESHOLD;
 
-  if (!budget.overBudget && !nearPathScoped) return null;
+  // #1449 — reported on its own line, never folded into `overBudget`.
+  const defectLine =
+    budget.defects.length > 0 ? formatFrontmatterDefectLine(budget.defects) : null;
+
+  if (!budget.overBudget && !nearPathScoped && !defectLine) return null;
 
   const nearLine = nearPathScoped ? formatNearPathScopedLine(budget, opts.repoRoot) : null;
 
-  // Near-threshold and nothing breached: a one-finding banner, carrying the
-  // same remedy as the breach clause below (consolidate — never raise).
+  // Nothing breached: one block per finding — the near-threshold line carries
+  // the same remedy as the breach clause below (consolidate — never raise).
   if (!budget.overBudget) {
     return {
       severity: 'warn',
       message: [
-        `⚠ ${nearLine}.`,
-        '  Consolidate generated rules per docs/rule-authoring.md § Consolidated rules; never raise the ceiling.',
+        ...(nearLine
+          ? [
+              `⚠ ${nearLine}.`,
+              '  Consolidate generated rules per docs/rule-authoring.md § Consolidated rules; never raise the ceiling.',
+            ]
+          : []),
+        ...(defectLine ? [defectLine] : []),
       ].join('\n'),
     };
   }
@@ -1523,6 +1580,7 @@ export function checkInstructionBudget(opts = {}) {
     ...(nearLine ? [`  ${nearLine}.`] : []),
     `  Top files: ${top}`,
     '  See the instruction-budget audit (#687; archived in the private Meta-Vault) for the prune/demote list.',
+    ...(defectLine ? [defectLine] : []),
   ].join('\n');
 
   return { severity: 'warn', message };

package/scripts/lib/learnings/expiry-sweep.mjs

@@ -62,7 +62,7 @@
 import { existsSync } from 'node:fs';
 import { mkdir, appendFile } from 'node:fs/promises';
 import path from 'node:path';
-import { readLearnings, rewriteLearnings } from './io.mjs';
+import { readLearnings, rewriteLearnings, withLearningsLock } from './io.mjs';
 
 /**
  * Composite-key separator for the in-memory consolidation Map.
@@ -284,7 +284,22 @@ async function archiveThenRewrite({ filePath, archivePath, keep, archiveBatch, n
  *   `filePath` and `archivePath` are required; a missing/invalid `filePath`
  *   throws a plain `Error` (programmer error, not a runtime data condition).
  */
-export async function sweepExpiredLearnings({
+export async function sweepExpiredLearnings(opts = {}) {
+  const { filePath, dryRun = true } = opts;
+  // The read → rewrite runs under the store lock (#1447 point 8). A run that
+  // cannot write takes no lock: a dry run, an absent store (zeroed shape, see
+  // below), or an unusable `filePath` (the body owns that error).
+  if (dryRun || typeof filePath !== 'string' || !existsSync(filePath)) {
+    return sweepExpiredLearningsUnlocked(opts);
+  }
+  return withLearningsLock(filePath, () => sweepExpiredLearningsUnlocked(opts));
+}
+
+/**
+ * Body of {@link sweepExpiredLearnings}; the caller holds the store lock or
+ * runs a pass that cannot write.
+ */
+async function sweepExpiredLearningsUnlocked({
   filePath,
   archivePath,
   now,
@@ -399,7 +414,23 @@ export async function sweepExpiredLearnings({
  * @returns {Promise<{scanned: number, kept: number, archived: number,
  *   byReason: Record<string, number>, dryRun: boolean, archivePath: string}>}
  */
-export async function pruneLearnings({
+export async function pruneLearnings(opts = {}) {
+  const { filePath, dryRun = true } = opts;
+  // The read → archive → rewrite runs under the store lock (#1447 point 8): an
+  // append landing after the read below would otherwise vanish in the rename
+  // with no archive line. A dry run writes nothing and takes no lock; an
+  // unusable `filePath` goes straight to the body, which owns that error.
+  if (dryRun || typeof filePath !== 'string' || filePath.length === 0) {
+    return pruneLearningsUnlocked(opts);
+  }
+  return withLearningsLock(filePath, () => pruneLearningsUnlocked(opts));
+}
+
+/**
+ * Body of {@link pruneLearnings}; the caller holds the store lock or runs a
+ * dry run.
+ */
+async function pruneLearningsUnlocked({
   filePath,
   archivePath,
   entries,

package/scripts/lib/learnings/io.mjs

@@ -8,14 +8,18 @@
 import {
   readFile,
   writeFile,
+  appendFile,
   mkdir,
   rename,
   copyFile,
   readdir,
   unlink,
 } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
+import { existsSync, realpathSync } from 'node:fs';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
 import path from 'node:path';
+import { withFileLock } from '../file-lock.mjs';
 import {
   validateLearning,
   normalizeLearning,
@@ -24,6 +28,117 @@ import {
   ValidationError,
 } from './schema.mjs';
 
+// ---------------------------------------------------------------------------
+// Store lock (GitLab #1447 point 8)
+// ---------------------------------------------------------------------------
+
+/**
+ * How long a writer waits for the store lock before giving up — the
+ * `withFileLock` default. Every critical section here is one read plus one
+ * append or rewrite of a JSONL file (milliseconds), so ten seconds of
+ * contention means a stuck holder, not a slow one.
+ */
+export const LEARNINGS_LOCK_TIMEOUT_MS = 10000;
+
+/**
+ * Thrown when the learnings store lock cannot be acquired. Every writer takes
+ * the lock BEFORE it touches the store, so this error always means nothing was
+ * written. The message is one line and names the lock file.
+ */
+export class LearningsLockError extends Error {
+  /**
+   * @param {string} lockPath
+   * @param {'timeout'|'fs-error'} reason
+   * @param {number} timeoutMs
+   * @param {string} [detail]
+   */
+  constructor(lockPath, reason, timeoutMs, detail) {
+    const why =
+      reason === 'timeout'
+        ? `held by another writer, waited ${timeoutMs} ms`
+        : `${reason}${detail ? `: ${detail}` : ''}`;
+    super(`learnings store lock ${lockPath} not acquired (${why}) — nothing written`);
+    this.name = 'LearningsLockError';
+    this.lockPath = lockPath;
+    this.reason = reason;
+  }
+}
+
+/**
+ * Store locks held by the CURRENT async call chain, so a nested writer inside a
+ * critical section (apply → prune → rewrite, sweep → rewrite, promote →
+ * rewrite) runs straight through instead of waiting on its own lock until the
+ * timeout. Keyed per async context, deliberately NOT per process: a concurrent
+ * call chain in the same process does not inherit the entry and waits like a
+ * second process would — which is exactly the interleaving the lock exists for.
+ * @type {AsyncLocalStorage<Map<string, {live: boolean}>>}
+ */
+const heldStoreLocks = new AsyncLocalStorage();
+
+/**
+ * `<store>.lock` beside the store. The directory is canonicalised so two
+ * spellings of one store (`/var` vs `/private/var`, a realpath'd repo root as
+ * `memory-proposals/sink.mjs` passes it) contend on ONE lock file. Creates the
+ * directory: the lock file needs it, and every caller is about to write there.
+ *
+ * @param {string} filePath
+ * @returns {Promise<string>}
+ */
+async function resolveStoreLockPath(filePath) {
+  const dir = path.dirname(path.resolve(filePath));
+  await mkdir(dir, { recursive: true });
+  return path.join(realpathSync(dir), `${path.basename(filePath)}.lock`);
+}
+
+/**
+ * Run `fn` while holding the exclusive lock of the learnings store at
+ * `filePath`. Every read-modify-write of the store must run its WHOLE
+ * read → write sequence inside one call: a write outside the lock is silently
+ * lost when a rewriter that read before it renames its next generation over
+ * the file. `appendLearning()` and `rewriteLearnings()` take the lock
+ * themselves.
+ *
+ * Reentrant within one async call chain (see `heldStoreLocks`). Reentrancy
+ * prevents a deadlock, not a lost write: an `appendLearning()` issued INSIDE a
+ * read → rewrite section lands in the file that section is about to replace —
+ * fold such a record into the rewrite batch instead.
+ *
+ * Crash safety comes from `withFileLock`'s default `staleCheck: 'pid'`: a lock
+ * whose holder process is gone is overridden (WARN on stderr); a live holder or
+ * one on another host is waited for until `timeoutMs`.
+ *
+ * @template T
+ * @param {string} filePath — the learnings store (the lock file sits beside it)
+ * @param {() => (T | Promise<T>)} fn
+ * @param {{ timeoutMs?: number }} [opts]
+ * @returns {Promise<T>}
+ * @throws {LearningsLockError} when the lock is not acquired — `fn` never ran
+ */
+export async function withLearningsLock(filePath, fn, { timeoutMs = LEARNINGS_LOCK_TIMEOUT_MS } = {}) {
+  const lockPath = await resolveStoreLockPath(filePath);
+  const held = heldStoreLocks.getStore();
+  if (held?.get(lockPath)?.live === true) return fn();
+
+  const token = { live: true };
+  const scope = new Map(held ?? []);
+  scope.set(lockPath, token);
+  let result;
+  try {
+    result = await withFileLock(lockPath, () => heldStoreLocks.run(scope, fn), {
+      timeoutMs,
+      // A per-acquisition holder makes the owner-guarded release delete only
+      // THIS acquisition's lock, never a successor's (#1285).
+      holder: `learnings-store:${process.pid}:${randomUUID()}`,
+    });
+  } finally {
+    // A continuation `fn` left running past its own return must not keep
+    // treating the released lock as held.
+    token.live = false;
+  }
+  if (!result.ok) throw new LearningsLockError(lockPath, result.reason, timeoutMs, result.error);
+  return result.value;
+}
+
 // ---------------------------------------------------------------------------
 // Pre-write self-validation seam (issue #662)
 // ---------------------------------------------------------------------------
@@ -42,7 +157,7 @@ import {
  * append touches disk, so a bad write can never reach the file.
  *
  * @param {object} validated — already validated+normalized learning entry
- * @param {{ legacyTolerant?: boolean }} [opts] — GitLab #386. When `true`,
+ * @param {{ legacyTolerant?: boolean }} [opts] — EventDrop #386. When `true`,
  *   a field that was ALREADY ABSENT on `validated` (e.g. a legacy record with
  *   no `source_session`, tolerated by `readLearnings()`) stays tolerated after
  *   the round-trip too — the re-validation call below runs in the same
@@ -80,8 +195,9 @@ function serializeLearningLineChecked(validated, { legacyTolerant = false } = {}
     // A key that existed on `validated` (present, even as `undefined`) but
     // vanished from `reparsed` was DROPPED by JSON.stringify — the exact
     // undefined/NaN/etc. corruption #662 exists to catch. A key that was
-    // never on `validated` in the first place (the #386 legacy-field case)
-    // cannot appear here, because we only iterate `validated`'s own keys.
+    // never on `validated` in the first place (the EventDrop #386
+    // legacy-field case) cannot appear here, because we only iterate
+    // `validated`'s own keys.
     const droppedKeys = Object.keys(validated).filter((k) => !(k in reparsed));
     if (droppedKeys.length > 0) {
       throw new ValidationError(
@@ -143,11 +259,18 @@ export async function readLearnings(filePath) {
  * atomic on POSIX append. For very large insight/evidence fields that
  * might exceed that boundary, use rewriteLearnings() instead.
  *
+ * The append runs under the store lock ({@link withLearningsLock}): an append
+ * that landed between a rewriter's read and its rename was silently lost.
+ * Validation runs first, outside the lock — a rejected record never waits.
+ *
  * @param {string} filePath
  * @param {object} entry
+ * @param {{ lockTimeoutMs?: number }} [opts] — store-lock wait, default
+ *   {@link LEARNINGS_LOCK_TIMEOUT_MS}
  * @returns {Promise<object>} validated entry
+ * @throws {LearningsLockError} when the store lock is not acquired (nothing appended)
  */
-export async function appendLearning(filePath, entry) {
+export async function appendLearning(filePath, entry, { lockTimeoutMs } = {}) {
   // Ensure created_at is set first — many writers omit it, and expires_at
   // derivation depends on it. Use ISO 8601 UTC.
   const createdAt =
@@ -173,9 +296,10 @@ export async function appendLearning(filePath, entry) {
   // parses back AND re-validates before any append touches disk. Throws
   // ValidationError on a non-round-tripping record — file is left untouched.
   const line = serializeLearningLineChecked(validated);
-  await mkdir(path.dirname(filePath), { recursive: true });
-  const { appendFile } = await import('node:fs/promises');
-  await appendFile(filePath, line, 'utf8');
+  // The lock path resolution creates the parent directory.
+  await withLearningsLock(filePath, () => appendFile(filePath, line, 'utf8'), {
+    timeoutMs: lockTimeoutMs,
+  });
   return validated;
 }
 
@@ -281,7 +405,7 @@ async function rotateBackups(dir, baseName, keep = BACKUP_KEEP) {
  * - `backup` (default `true`): before the destructive rename, copy the current
  *   file to `${filePath}.bak-<ISO>`, then rotate to keep only the newest
  *   {@link BACKUP_KEEP}. Rotation is best-effort and never blocks the rewrite.
- * - `legacyTolerant` (default `true`, GitLab #386): this function is a
+ * - `legacyTolerant` (default `true`, EventDrop #386): this function is a
  *   ROUND-TRIP writer — its usual caller (`sweepExpiredLearnings` /
  *   `pruneLearnings` in `expiry-sweep.mjs`) reads the store with
  *   `readLearnings()` first, and that reader already tolerates a legacy
@@ -298,7 +422,7 @@ async function rotateBackups(dir, baseName, keep = BACKUP_KEEP) {
  *   round-trip (a value JSON.stringify drops or coerces, e.g. `undefined`/
  *   `NaN`) is still caught by the #662 checked serializer regardless of this
  *   flag — see {@link serializeLearningLineChecked}. Pass `false` to restore
- *   the pre-#386 fully-strict behaviour.
+ *   the fully-strict behaviour from before EventDrop #386.
  *
  * @param {string} filePath
  * @param {object[]} entries
@@ -331,24 +455,28 @@ export async function rewriteLearnings(
   if (dryRun) return validated;
 
   const body = lines.join('');
-  await mkdir(path.dirname(filePath), { recursive: true });
 
-  // Backup-before-rewrite (#721): snapshot the current store to a timestamped
-  // sidecar BEFORE the destructive rename, then prune to keep-N. Only meaningful
-  // when the target already exists (a first-time write has nothing to lose).
-  if (backup && existsSync(filePath)) {
-    const ts = new Date().toISOString().replace(/[:.]/g, '-');
-    await copyFile(filePath, `${filePath}.bak-${ts}`);
-    try {
-      await rotateBackups(path.dirname(filePath), path.basename(filePath));
-    } catch {
-      // Rotation is best-effort — a stale/undeletable sibling must never abort
-      // the rewrite. The fresh backup above is already safely on disk.
+  // Under the store lock (#1447 point 8) so no append lands between the backup
+  // and the rename. The CALLER's read must sit inside the same lock for a
+  // read-modify-write to be safe — this call joins it reentrantly.
+  await withLearningsLock(filePath, async () => {
+    // Backup-before-rewrite (#721): snapshot the current store to a timestamped
+    // sidecar BEFORE the destructive rename, then prune to keep-N. Only meaningful
+    // when the target already exists (a first-time write has nothing to lose).
+    if (backup && existsSync(filePath)) {
+      const ts = new Date().toISOString().replace(/[:.]/g, '-');
+      await copyFile(filePath, `${filePath}.bak-${ts}`);
+      try {
+        await rotateBackups(path.dirname(filePath), path.basename(filePath));
+      } catch {
+        // Rotation is best-effort — a stale/undeletable sibling must never abort
+        // the rewrite. The fresh backup above is already safely on disk.
+      }
     }
-  }
 
-  const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
-  await writeFile(tmp, body, 'utf8');
-  await rename(tmp, filePath);
+    const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    await writeFile(tmp, body, 'utf8');
+    await rename(tmp, filePath);
+  });
   return validated;
 }