@ngockhoale/ukit 3.4.0 → 3.4.2

package/src/core/fileOps.js

@@ -99,6 +99,67 @@ export function resolveProjectRelativePath(projectRoot, relPath) {
   return absolute;
 }
 
+/**
+ * resolveProjectPathReal(projectRoot, relPath) → resolved absolute path or null.
+ *
+ * Same lexical gate as resolveProjectRelativePath, then a post-resolution
+ * containment check: realpath BOTH the project root and the candidate so a
+ * project-local symlink — or a path resolving through a symlinked directory —
+ * that points outside the root is refused. The lexical check alone lets
+ * fs.readFile silently follow the link (C92-F-03 follow-up / dirty-set guard).
+ *
+ * A candidate whose leaf does not exist is still resolved: realpath walks to
+ * the nearest existing ancestor and the unresolved tail is re-attached
+ * lexically (ENOENT/ENOTDIR only — a missing leaf under a symlinked parent is
+ * still caught). Any other resolution failure (ELOOP, EACCES, …) is a refusal,
+ * never a pass. Returns the RESOLVED path so callers read exactly what was
+ * containment-checked.
+ */
+export async function resolveProjectPathReal(projectRoot, relPath) {
+  const absolute = resolveProjectRelativePath(projectRoot, relPath);
+  if (!absolute) return null;
+
+  let realRoot;
+  try {
+    realRoot = await fs.realpath(path.resolve(projectRoot));
+  } catch {
+    return null; // cannot pin the root — nothing is provably inside it
+  }
+
+  let real;
+  try {
+    real = await fs.realpath(absolute);
+  } catch (error) {
+    if (error?.code !== 'ENOENT' && error?.code !== 'ENOTDIR') {
+      return null;
+    }
+    const parts = [];
+    let cursor = absolute;
+    let resolvedAncestor = null;
+    while (true) {
+      const parent = path.dirname(cursor);
+      parts.unshift(path.basename(cursor));
+      if (parent === cursor) return null; // walked past the fs root — refuse
+      cursor = parent;
+      try {
+        resolvedAncestor = await fs.realpath(cursor);
+        break;
+      } catch (inner) {
+        if (inner?.code !== 'ENOENT' && inner?.code !== 'ENOTDIR') {
+          return null;
+        }
+      }
+    }
+    real = path.join(resolvedAncestor, ...parts);
+  }
+
+  const relative = path.relative(realRoot, real);
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+    return null;
+  }
+  return real;
+}
+
 export async function ensureDir(dirPath) {
   await fs.mkdir(dirPath, { recursive: true });
 }

package/src/core/memory/hygiene.js

@@ -1,6 +1,7 @@
 const DEFAULT_CONFIG = {
   archiveAfterDays: 30,
   maxSessionsKept: 20,
+  maxPatternCandidates: 50,
   conflictResolution: 'latest_wins',
   redactPatterns: [
     /sk-[a-z0-9_-]+/gi,
@@ -151,12 +152,61 @@ function normalizeConfig(config = {}) {
     maxSessionsKept: Number.isInteger(mergedConfig.maxSessionsKept) && mergedConfig.maxSessionsKept > 0
       ? mergedConfig.maxSessionsKept
       : DEFAULT_CONFIG.maxSessionsKept,
+    maxPatternCandidates: Number.isInteger(mergedConfig.maxPatternCandidates) && mergedConfig.maxPatternCandidates > 0
+      ? mergedConfig.maxPatternCandidates
+      : DEFAULT_CONFIG.maxPatternCandidates,
     redactPatterns: Array.isArray(mergedConfig.redactPatterns)
       ? mergedConfig.redactPatterns
       : DEFAULT_CONFIG.redactPatterns,
   };
 }
 
+// W3-F6: patternCandidates grew without bound — resolved entries were never
+// evicted. Resolved entries older than archiveAfterDays drop first; the
+// surviving list is then capped at maxPatternCandidates, evicting oldest
+// detectedAt first and preferring to evict resolved over still-pending
+// (a pending entry is an open decision; resolved ones are history).
+const PATTERN_CANDIDATE_RESOLVED = new Set(['approved', 'rejected']);
+
+function candidateDetectedAt(entry) {
+  const detectedAt = Number(entry?.detectedAt ?? 0);
+  return Number.isFinite(detectedAt) ? detectedAt : 0;
+}
+
+function prunePatternCandidates(projectMemory, config) {
+  const candidates = Array.isArray(projectMemory.patternCandidates)
+    ? projectMemory.patternCandidates
+    : [];
+  if (candidates.length === 0) return;
+
+  const now = config.now ?? Date.now();
+  const maxAgeMs = config.archiveAfterDays * 24 * 60 * 60 * 1000;
+  const cap = config.maxPatternCandidates;
+
+  // Age eviction: only resolved candidates — pending ones never expire unseen.
+  const fresh = candidates.filter((entry) => {
+    if (!PATTERN_CANDIDATE_RESOLVED.has(entry?.status)) return true;
+    const detectedAt = candidateDetectedAt(entry);
+    return detectedAt <= 0 || now - detectedAt <= maxAgeMs;
+  });
+  if (fresh.length <= cap) {
+    projectMemory.patternCandidates = fresh;
+    return;
+  }
+
+  // Cap eviction: oldest resolved first, then oldest pending — the newest
+  // cap-sized survivors keep their original relative order.
+  const isResolved = (entry) => PATTERN_CANDIDATE_RESOLVED.has(entry?.status);
+  const resolved = fresh.filter(isResolved).sort((a, b) => candidateDetectedAt(a) - candidateDetectedAt(b));
+  const pending = fresh.filter((entry) => !isResolved(entry)).sort((a, b) => candidateDetectedAt(a) - candidateDetectedAt(b));
+  const dropCount = fresh.length - cap;
+  const dropped = new Set([
+    ...resolved.slice(0, dropCount),
+    ...pending.slice(0, Math.max(0, dropCount - resolved.length)),
+  ]);
+  projectMemory.patternCandidates = fresh.filter((entry) => !dropped.has(entry));
+}
+
 export function runHygiene(projectMemory, config = {}) {
   const mergedConfig = normalizeConfig(config);
   const nextMemory = redactValue(clone(projectMemory), mergedConfig.redactPatterns);
@@ -164,7 +214,7 @@ export function runHygiene(projectMemory, config = {}) {
   nextMemory.conventions = uniqueStrings(nextMemory.conventions);
   nextMemory.techStack = uniqueStrings(nextMemory.techStack);
   nextMemory.activeRules = uniqueStrings(nextMemory.activeRules);
-
+  prunePatternCandidates(nextMemory, mergedConfig);
   const conflicts = resolveDecisionConflicts(nextMemory, mergedConfig.conflictResolution);
   const archivedSessions = archiveSessions(nextMemory, mergedConfig);
 

package/src/core/memory/migrate.js

@@ -145,14 +145,17 @@ export async function needsMigration(projectRoot) {
 
 /**
  * runMigration(projectRoot, { dryRun?, homeDir? } = {})
- * → { migrated, skipped, plan, markerPath, backupDir }
+ * → { migrated, skipped, plan, markerPath, backupDir, corruptFiles, corrupt }
  * No-op when the marker exists or no legacy files exist. dryRun returns the
  * full per-record plan ({id, source, action, reason}) and writes nothing.
+ * `corruptFiles`/`corrupt` surface unreadable legacy sources; the marker is
+ * written only when corruptFiles === 0 — otherwise needsMigration stays true
+ * and the corrupt remainder is never silently abandoned.
  */
 export async function runMigration(projectRoot, { dryRun = false, homeDir } = {}) {
   const paths = buildRuntimePaths(projectRoot);
   const markerPath = path.join(paths.memoryV2Dir, MARKER_NAME);
-  const empty = { migrated: 0, skipped: 0, plan: [], markerPath, backupDir: null };
+  const empty = { migrated: 0, skipped: 0, plan: [], markerPath, backupDir: null, corruptFiles: 0, corrupt: [] };
 
   if (await pathExists(markerPath)) return empty;
 
@@ -185,25 +188,32 @@ export async function runMigration(projectRoot, { dryRun = false, homeDir } = {}
     resolveProjectId: (legacyId) => resolvedIds.get(legacyId) ?? null,
   });
 
+  const corruptFiles = sources.corruptFiles;
+  const corrupt = [...sources.corrupt];
   if (dryRun) {
-    return { migrated: records.length, skipped, plan, markerPath, backupDir: null };
+    return { migrated: records.length, skipped, plan, markerPath, backupDir: null, corruptFiles, corrupt };
   }
 
-  // Backup-first: copy legacy memory dir (excluding v2 + prior backups) before writing.
-  const backupDir = path.join(paths.memoryRoot, `v1-backup-${Date.now()}`);
-  const entries = await fs.readdir(paths.memoryRoot, { withFileTypes: true });
-  for (const entry of entries) {
-    if (entry.name === 'v2' || entry.name.startsWith('v1-backup-')) continue;
-    const src = path.join(paths.memoryRoot, entry.name);
-    const dest = path.join(backupDir, entry.name);
-    if (entry.isDirectory()) {
-      await copyDirRecursive(src, dest);
-    } else if (entry.isFile()) {
-      await fs.mkdir(backupDir, { recursive: true });
-      await fs.copyFile(src, dest);
+  // Backup-first only when there are records to merge — a corrupt-only rerun
+  // would otherwise pile up empty v1-backup dirs on every lazy retry.
+  let backupDir = null;
+  if (records.length > 0) {
+    backupDir = path.join(paths.memoryRoot, `v1-backup-${Date.now()}`);
+    const entries = await fs.readdir(paths.memoryRoot, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name === 'v2' || entry.name.startsWith('v1-backup-')) continue;
+      const src = path.join(paths.memoryRoot, entry.name);
+      const dest = path.join(backupDir, entry.name);
+      if (entry.isDirectory()) {
+        await copyDirRecursive(src, dest);
+      } else if (entry.isFile()) {
+        await fs.mkdir(backupDir, { recursive: true });
+        await fs.copyFile(src, dest);
+      }
     }
   }
 
+
   // Merge into the existing store through mutateMemory's restore op — the
   // single guarded write entry. Tombstone precedence lives there, so a
   // purged record can never resurrect via re-migration; source_fingerprint
@@ -228,11 +238,21 @@ export async function runMigration(projectRoot, { dryRun = false, homeDir } = {}
     skipped,
     byType: records.reduce((acc, r) => ({ ...acc, [r.type]: (acc[r.type] ?? 0) + 1 }), {}),
   };
-  await writeJson(markerPath, {
-    migratedAt: Date.now(),
-    counts,
-    backupDir,
-  });
+  // C90-02: the marker is written ONLY when no corrupt legacy file remains.
+  // Writing it while a file is unreadable would flip needsMigration to false
+  // and silently abandon that file's data forever.
+  if (corruptFiles === 0) {
+    await writeJson(markerPath, {
+      migratedAt: Date.now(),
+      counts,
+      backupDir,
+    });
+  } else {
+    console.warn(
+      `[UKit] migration skipped ${corruptFiles} corrupt legacy file(s): ${corrupt.join(', ')}`
+      + ' — marker NOT written; repair or remove them and migrate again.',
+    );
+  }
 
-  return { migrated, skipped, plan, markerPath, backupDir };
+  return { migrated, skipped, plan, markerPath, backupDir, corruptFiles, corrupt };
 }

package/src/core/memory/store.js

@@ -2,7 +2,7 @@ import fs from 'node:fs/promises';
 import crypto from 'node:crypto';
 import path from 'node:path';
 import { buildRuntimePaths } from '../runtimePaths.js';
-import { readJsonIfExists, writeJson } from '../fileOps.js';
+import { readJsonIfExists, writeJson, withFileLock } from '../fileOps.js';
 import { loadRuntimeConfig } from '../runtimeConfig.js';
 import { runHygiene } from './hygiene.js';
 import { redactWritePayload } from './writeGuard.js';
@@ -534,6 +534,7 @@ async function persistProjectMemoryWithHygiene(projectRoot, runtimePaths, projec
   const hygieneConfig = {
     archiveAfterDays: memoryConfig.archiveAfterDays,
     maxSessionsKept: memoryConfig.maxSessions,
+    maxPatternCandidates: memoryConfig.maxPatternCandidates,
     ...(memoryConfig.redactSecrets === false ? { redactPatterns: [] } : {}),
   };
 
@@ -543,12 +544,43 @@ async function persistProjectMemoryWithHygiene(projectRoot, runtimePaths, projec
   return hygienicMemory;
 }
 
+// W2-B1: the whole read → mutate → persist chain on <id>.json (plus the
+// <id>.archive.json append inside persist) runs under withFileLock — the
+// same serialization mutateRecordStore gives the v2 doc. Without it two
+// writers (learn + approve, parallel hooks) read the same snapshot and the
+// last write silently eats the other's mutation.
+//
+// `mutate(memory)` returns:
+//   - { result }             → persist, resolve with result;
+//   - { skip: true, result } → skip the write, resolve with result;
+//   - falsy / no `result`    → persist, resolve with the persisted (hygienic) memory.
+// A lock-wait timeout THROWS (mutateRecordStore convention): returning the
+// computed entry as if persisted would tell callers a dropped write landed.
+async function mutateProjectMemory(projectRoot, runtimePaths, projectId, mutate) {
+  const filePath = projectMemoryPath(runtimePaths, projectId);
+  const outcome = await withFileLock(filePath, async () => {
+    const existing = await readMemoryJson(filePath);
+    const memory = { id: projectId, conventions: [], patternCandidates: [], ...existing };
+    const mutation = await mutate(memory);
+    const skip = mutation?.skip === true;
+    const explicitResult = mutation != null && typeof mutation === 'object' && 'result' in mutation;
+    const result = explicitResult ? mutation.result : mutation;
+    if (skip) return result;
+    const persisted = await persistProjectMemoryWithHygiene(projectRoot, runtimePaths, projectId, filePath, memory);
+    return explicitResult ? result : persisted;
+  });
+  if (outcome === undefined) {
+    throw new Error(`mutateProjectMemory: lock wait expired for ${filePath} — mutation skipped`);
+  }
+  return outcome;
+}
+
 export async function runProjectHygiene(projectRoot, projectId) {
   const runtimePaths = buildRuntimePaths(projectRoot);
-  const { filePath, memory } = await readProjectMemoryForId(runtimePaths, projectId);
-  return persistProjectMemoryWithHygiene(projectRoot, runtimePaths, projectId, filePath, memory);
+  return mutateProjectMemory(projectRoot, runtimePaths, projectId, () => ({}));
 }
 
+
 function patternCandidateFromRecord(record) {
   const isLearningCandidate = record.provenance === 'learning-candidate';
   return {
@@ -678,45 +710,46 @@ export async function proposePatternCandidate(projectRoot, projectId, candidate,
     const entry = await proposePatternCandidateV2(projectRoot, projectId, candidate, { homeDir });
     // Mirror into the legacy project file (hygiene + conventions) so the
     // untouched-on-disk legacy format stays read-compatible.
-    const { filePath, memory } = await readProjectMemoryForId(runtimePaths, projectId);
-    const patternCandidates = Array.isArray(memory.patternCandidates) ? memory.patternCandidates : [];
-    if (!patternCandidates.some((existing) => existing.id === entry.id)) {
+    await mutateProjectMemory(projectRoot, runtimePaths, projectId, (memory) => {
+      const patternCandidates = Array.isArray(memory.patternCandidates) ? memory.patternCandidates : [];
+      if (patternCandidates.some((existing) => existing.id === entry.id)) {
+        return { skip: true, result: entry };
+      }
       memory.patternCandidates = [...patternCandidates, entry];
-      await persistProjectMemoryWithHygiene(projectRoot, runtimePaths, projectId, filePath, memory);
-    }
+      return { result: entry };
+    });
     return entry;
   }
 
-  const { filePath, memory } = await readProjectMemoryForId(runtimePaths, projectId);
-
   const normalizedText = normalizePatternText(candidate?.text);
   if (!normalizedText) {
     throw new Error('proposePatternCandidate requires candidate.text');
   }
 
-  const patternCandidates = Array.isArray(memory.patternCandidates) ? memory.patternCandidates : [];
-  const existingPending = patternCandidates.find(
-    (entry) => entry.status === 'pending'
-      && (normalizePatternText(entry.text) === normalizedText
-        || (candidate?.signature && entry.signature === candidate.signature)),
-  );
-  if (existingPending) {
-    return existingPending;
-  }
+  return mutateProjectMemory(projectRoot, runtimePaths, projectId, (memory) => {
+    const patternCandidates = Array.isArray(memory.patternCandidates) ? memory.patternCandidates : [];
+    const existingPending = patternCandidates.find(
+      (entry) => entry.status === 'pending'
+        && (normalizePatternText(entry.text) === normalizedText
+          || (candidate?.signature && entry.signature === candidate.signature)),
+    );
+    if (existingPending) {
+      return { skip: true, result: existingPending };
+    }
 
-  const entry = {
-    id: `pc_${crypto.randomBytes(6).toString('hex')}`,
-    text: candidate.text,
-    category: candidate?.category ?? null,
-    detectedFrom: candidate?.detectedFrom ?? null,
-    detectedAt: Date.now(),
-    status: 'pending',
-  };
-  if (candidate?.signature) entry.signature = candidate.signature;
+    const entry = {
+      id: `pc_${crypto.randomBytes(6).toString('hex')}`,
+      text: candidate.text,
+      category: candidate?.category ?? null,
+      detectedFrom: candidate?.detectedFrom ?? null,
+      detectedAt: Date.now(),
+      status: 'pending',
+    };
+    if (candidate?.signature) entry.signature = candidate.signature;
 
-  memory.patternCandidates = [...patternCandidates, entry];
-  await persistProjectMemoryWithHygiene(projectRoot, runtimePaths, projectId, filePath, memory);
-  return entry;
+    memory.patternCandidates = [...patternCandidates, entry];
+    return { result: entry };
+  });
 }
 
 export async function listPendingPatternCandidates(projectRoot, projectId, { homeDir } = {}) {
@@ -739,46 +772,48 @@ export async function resolvePatternCandidate(projectRoot, projectId, candidateI
   if (await v2Active(projectRoot, { homeDir })) {
     const resolved = await resolvePatternCandidateV2(projectRoot, projectId, candidateId, decision, { homeDir });
     // Mirror the resolution into the legacy project file.
-    const { filePath, memory } = await readProjectMemoryForId(runtimePaths, projectId);
-    const patternCandidates = Array.isArray(memory.patternCandidates) ? memory.patternCandidates : [];
-    const target = patternCandidates.find((entry) => entry.id === candidateId);
-    if (target) {
-      target.status = resolved.status;
+    await mutateProjectMemory(projectRoot, runtimePaths, projectId, (memory) => {
+      const patternCandidates = Array.isArray(memory.patternCandidates) ? memory.patternCandidates : [];
+      const target = patternCandidates.find((entry) => entry.id === candidateId);
+      if (target) {
+        target.status = resolved.status;
+        if (decision === 'approve') {
+          const conventions = Array.isArray(memory.conventions) ? memory.conventions : [];
+          if (!conventions.includes(target.text)) {
+            memory.conventions = [...conventions, target.text];
+          }
+        }
+        return {};
+      }
       if (decision === 'approve') {
         const conventions = Array.isArray(memory.conventions) ? memory.conventions : [];
-        if (!conventions.includes(target.text)) {
-          memory.conventions = [...conventions, target.text];
+        if (!conventions.includes(resolved.text)) {
+          memory.conventions = [...conventions, resolved.text];
+          return {};
         }
       }
-      await persistProjectMemoryWithHygiene(projectRoot, runtimePaths, projectId, filePath, memory);
-    } else if (decision === 'approve') {
-      const conventions = Array.isArray(memory.conventions) ? memory.conventions : [];
-      if (!conventions.includes(resolved.text)) {
-        memory.conventions = [...conventions, resolved.text];
-        await persistProjectMemoryWithHygiene(projectRoot, runtimePaths, projectId, filePath, memory);
-      }
-    }
+      return { skip: true };
+    });
     return resolved;
   }
 
-  const { filePath, memory } = await readProjectMemoryForId(runtimePaths, projectId);
-
-  const patternCandidates = Array.isArray(memory.patternCandidates) ? memory.patternCandidates : [];
-  const target = patternCandidates.find((entry) => entry.id === candidateId);
-  if (!target) {
-    throw new Error(`Pattern candidate not found: ${candidateId}`);
-  }
+  return mutateProjectMemory(projectRoot, runtimePaths, projectId, (memory) => {
+    const patternCandidates = Array.isArray(memory.patternCandidates) ? memory.patternCandidates : [];
+    const target = patternCandidates.find((entry) => entry.id === candidateId);
+    if (!target) {
+      throw new Error(`Pattern candidate not found: ${candidateId}`);
+    }
 
-  target.status = decision === 'approve' ? 'approved' : 'rejected';
-  if (decision === 'approve') {
-    const conventions = Array.isArray(memory.conventions) ? memory.conventions : [];
-    if (!conventions.includes(target.text)) {
-      memory.conventions = [...conventions, target.text];
+    target.status = decision === 'approve' ? 'approved' : 'rejected';
+    if (decision === 'approve') {
+      const conventions = Array.isArray(memory.conventions) ? memory.conventions : [];
+      if (!conventions.includes(target.text)) {
+        memory.conventions = [...conventions, target.text];
+      }
     }
-  }
 
-  await persistProjectMemoryWithHygiene(projectRoot, runtimePaths, projectId, filePath, memory);
-  return target;
+    return { result: target };
+  });
 }
 
 export async function countMemoryItems(projectRoot, { homeDir } = {}) {

package/src/core/metadata.js

@@ -1,6 +1,41 @@
 import path from 'node:path';
 import { ensureDir, writeJson, readJsonIfExists, withFileLock } from './fileOps.js';
 
+// FR-015 (W2-C2): install.json is the project's install ledger — a corrupt
+// file must never read as "not installed" (data loss: reinstall would wipe the
+// tracked-file manifest and orphan managed files) and never surface as a bare
+// SyntaxError. Every read site wraps parse failures in a typed error; real fs
+// failures (EACCES, EISDIR, …) keep their own codes.
+export class InstallMetadataError extends Error {
+  constructor(message, code = 'install_metadata_corrupt', { cause } = {}) {
+    super(message);
+    this.name = 'InstallMetadataError';
+    this.code = code;
+    if (cause !== undefined) this.cause = cause;
+  }
+}
+
+/**
+ * `readJsonIfExists` + typed parse failures: absent → null (first install),
+ * corrupt JSON → InstallMetadataError naming the file. Non-parse errors keep
+ * their fs codes so callers can still distinguish EACCES/EIO from corruption.
+ */
+export async function readInstallMetadata(installMetaPath) {
+  try {
+    return await readJsonIfExists(installMetaPath);
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new InstallMetadataError(
+        `Install metadata is corrupt: ${installMetaPath} is not valid JSON (${error.message}). `
+        + 'Remove it to reinstall cleanly, or restore it from a backup — UKit will not overwrite it.',
+        'install_metadata_corrupt',
+        { cause: error },
+      );
+    }
+    throw error;
+  }
+}
+
 function normalizeTrackedRelativePath(relativePath) {
   if (typeof relativePath !== 'string') {
     return null;
@@ -43,7 +78,7 @@ export async function writeInstallMetadata({
     // uninstall). The read→merge→write runs under withFileLock (C79-12):
     // concurrent installs used to read the same pre-state and last-writer-wins
     // the merge, silently losing tracked-file entries.
-    const previousData = await readJsonIfExists(installMetaPath);
+    const previousData = await readInstallMetadata(installMetaPath);
     const previousFiles = previousData?.tool === 'ukit' && Array.isArray(previousData?.files)
       ? previousData.files
       : [];
@@ -147,7 +182,7 @@ export async function removeTrackedPathsFromMetadata({
   }
 
   const removeResult = await withFileLock(installMetaPath, async () => {
-    const metadata = await readJsonIfExists(installMetaPath);
+    const metadata = await readInstallMetadata(installMetaPath);
     if (!metadata || metadata.tool !== 'ukit' || !Array.isArray(metadata.files)) {
       return 'noop';
     }

package/src/core/observability/adapters/ingest.js

@@ -17,9 +17,10 @@
 //                   → adaptContextItems
 //
 //   ingestStoredTelemetry({ projectRoot, recorder, deadlineMs?, sources?, now? })
-//     → Promise<{ ok, status:'complete'|'partial'|'degraded',
+//     → Promise<{ ok:true, status:'complete'|'partial'|'degraded',
 //                  coverage: { <source>: { read, emitted, rejected, skipped, reason? } },
-//                  last_cursors }>
+//                  last_cursors }
+//             | { ok:false, reason:'invalid_args'|'ingest_lock_timeout' }>
 //
 // Counters: `read` rows consumed by the adapter lane; `emitted` records
 // accepted (or queued-at-full-queue) by recorder.emit; `rejected` covers
@@ -45,6 +46,7 @@ import { adaptDecisionReceipts } from './decisionAdapter.js';
 import { adaptContextItems } from './contextAdapter.js';
 import { createAdapterContext, isPlainObject } from './common.js';
 import { listLedgerFiles } from '../../../diagnostics/ledgerFiles.js';
+import { withFileLock } from '../../fileOps.js';
 
 const STORAGE_REL = path.join('.ukit', 'storage');
 const CACHE_REL = path.join(STORAGE_REL, 'cache');
@@ -362,6 +364,32 @@ export async function ingestStoredTelemetry({
     return { ok: false, reason: 'invalid_args' };
   }
 
+  // C90-10: the whole loadCursors → emit → saveCursors transaction runs
+  // under the per-cursor-file withFileLock. Two overlapping collectors used
+  // to read the same cursor snapshot and double-emit every row, then
+  // last-writer-wins the cursor file. An expired lock wait fails closed:
+  // the collect is dropped (journaled by fileOps), never run unlocked.
+  const cursorFile = path.join(projectRoot, CURSOR_REL);
+  let result;
+  try {
+    result = await withFileLock(cursorFile, () =>
+      ingestOnce({ projectRoot, recorder, deadlineMs, sources, now, limitLedgers }));
+  } catch (error) {
+    // Lock protocol itself failed (e.g. EACCES making the lock dir) —
+    // typed failure, never an unlocked run.
+    return { ok: false, reason: error?.code ?? 'ingest_lock_error' };
+  }
+  return result === undefined ? { ok: false, reason: 'ingest_lock_timeout' } : result;
+}
+
+async function ingestOnce({
+  projectRoot,
+  recorder,
+  deadlineMs,
+  sources,
+  now,
+  limitLedgers,
+}) {
   const nowFn = typeof now === 'function' ? now : () => Date.now();
   const start = nowFn();
   const deadline = Number.isFinite(deadlineMs) ? start + deadlineMs : null;

package/src/core/observability/emit/config.js

@@ -47,18 +47,33 @@ export function resolveStage(config = null) {
 const SAMPLING_RATE_KEYS = new Set(['low', 'normal', 'high', 'critical']);
 const MAX_POLICY_VERSION_CHARS = 128;
 
-// Process-wide latch: a recorder boot is a process, so "once per boot" is a
-// module-level one-shot — the same granularity resolveStage operates at.
+// Process-wide latches: a recorder boot is a process, so "once per boot" is
+// module-level — the same granularity resolveStage operates at. The REPORT
+// latch is separate from the SEEN latch (TASK-C91-015, W3-OB2): consumers
+// like sessionBoot.js create a fresh recorder per emit, so a per-recorder
+// `config_invalid_reported` flag re-reported the aggregate every time.
 let samplingConfigInvalidSeen = false;
+let samplingConfigInvalidReportedFlag = false;
 
 export function samplingConfigInvalid() {
   return samplingConfigInvalidSeen;
 }
 
-// Test/secondary-consumer hook: the flag is a boot-scoped observation, not
-// stateful policy — clearing it re-arms the one-shot report.
+/** True when the CONFIG_INVALID aggregate was already queued in this process. */
+export function samplingConfigInvalidReported() {
+  return samplingConfigInvalidReportedFlag;
+}
+
+/** Mark the CONFIG_INVALID aggregate as emitted — call before queueing it. */
+export function markSamplingConfigInvalidReported() {
+  samplingConfigInvalidReportedFlag = true;
+}
+
+// Test/secondary-consumer hook: the flags are boot-scoped observations, not
+// stateful policy — clearing them re-arms the one-shot report.
 export function resetSamplingConfigInvalid() {
   samplingConfigInvalidSeen = false;
+  samplingConfigInvalidReportedFlag = false;
 }
 
 export function resolveSampling(config = null) {

package/src/core/observability/emit/crash.js

@@ -279,7 +279,9 @@ export function registerCrashCapture({ root, writerId, bootId, now } = {}) {
 
   function writeRecord(record, name) {
     const target = path.join(dir, name);
-    const tmpPath = `${target}.tmp-${process.pid}`;
+    // C90-15 / TASK-C91-015: per-call entropy — pid alone lets a stale
+    // `.tmp-<pid>` or a second write to the same target collide mid-publish.
+    const tmpPath = `${target}.tmp-${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
     try {
       fs.writeFileSync(tmpPath, `${JSON.stringify(record)}\n`, 'utf8');
       fs.renameSync(tmpPath, target);