@ngockhoale/ukit 2.6.10 → 2.7.0

package/src/core/unattendedDoctor.js

@@ -0,0 +1,227 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { parse } from 'yaml';
+import { pathExists, readJsonIfExists } from './fileOps.js';
+import { VALID_PERMISSION_MODES } from './runtimeConfig.js';
+
+// TASK-011 / SPEC §8 — unattended-mode doctor checks (FR-007).
+// Seven checks, each returning the projectChecks remediation-class shape:
+// { label, passed, applicable?, failed, remediationClass, remedy, detail? }
+// remediationClass ∈ install-repairable | owner-action | advisory.
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const INSTALL_REPAIR = 'Run ukit install';
+const OMP_CONFIG_TIMEOUT_MS = 5000;
+const COMPLETION_LOOP_HEADER = '## Unattended Completion Loop';
+
+async function readOmpConfig(projectRoot) {
+  const configPath = path.join(projectRoot, '.omp', 'config.yml');
+  try {
+    const text = await fs.readFile(configPath, 'utf8');
+    const parsed = parse(text);
+    return { exists: true, parsed: parsed && typeof parsed === 'object' ? parsed : {}, parseError: null };
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { exists: false, parsed: null, parseError: null };
+    return { exists: true, parsed: null, parseError: error?.message ?? String(error) };
+  }
+}
+
+const ANSI_PATTERN = /\u001b\[[0-9;]*m/g;
+
+function execOmpConfigGet(projectRoot, ompPath) {
+  return new Promise((resolve) => {
+    execFile(
+      ompPath,
+      ['config', 'get', 'tools.approvalMode'],
+      { cwd: projectRoot, timeout: OMP_CONFIG_TIMEOUT_MS },
+      (error, stdout) => {
+        if (error) {
+          resolve({ ok: false, value: null });
+          return;
+        }
+        const value = String(stdout ?? '').replace(ANSI_PATTERN, '').trim();
+        resolve({ ok: value.length > 0, value: value || null });
+      },
+    );
+  });
+}
+
+async function readTemplateDenyMatches() {
+  try {
+    const text = await fs.readFile(path.join(PACKAGE_ROOT, 'templates', '.omp', 'config.yml'), 'utf8');
+    const parsed = parse(text);
+    const patterns = parsed?.bash?.patterns;
+    if (!Array.isArray(patterns)) return [];
+    return patterns
+      .filter((entry) => entry && entry.approval === 'deny' && typeof entry.match === 'string')
+      .map((entry) => entry.match);
+  } catch {
+    return [];
+  }
+}
+
+export async function inspectUnattendedMode({ projectRoot, ompPath = 'omp' }) {
+  const runtimeConfig = await readJsonIfExists(
+    path.join(projectRoot, '.ukit', 'storage', 'config.json'),
+  );
+  const permissionModeRaw = runtimeConfig?.orchestration?.permissionMode;
+  const permissionModeValid = permissionModeRaw === undefined
+    || VALID_PERMISSION_MODES.has(permissionModeRaw);
+  const permissionMode = permissionModeRaw === undefined ? 'unattended' : permissionModeRaw;
+
+  const omp = await readOmpConfig(projectRoot);
+  const tools = omp.parsed?.tools ?? {};
+  const approvalMap = tools.approval && typeof tools.approval === 'object' ? tools.approval : {};
+  const bashPatterns = Array.isArray(omp.parsed?.bash?.patterns) ? omp.parsed.bash.patterns : [];
+
+  // Check 2 — effective approvalMode: `omp config get` first (5s timeout), YAML fallback.
+  let effectiveApprovalMode = null;
+  let approvalSource = null;
+  if (omp.exists) {
+    const ompResult = await execOmpConfigGet(projectRoot, ompPath);
+    if (ompResult.ok) {
+      effectiveApprovalMode = ompResult.value;
+      approvalSource = 'omp config get';
+    } else if (tools.approvalMode !== undefined) {
+      effectiveApprovalMode = tools.approvalMode ?? null;
+      approvalSource = '.omp/config.yml (omp binary unavailable)';
+    }
+  }
+
+  const promptValues = [tools.approvalMode, ...Object.values(approvalMap)];
+  for (const entry of bashPatterns) {
+    if (entry && typeof entry === 'object' && 'approval' in entry) promptValues.push(entry.approval);
+  }
+  const promptPolicyCount = promptValues.filter((v) => v === 'prompt').length;
+
+  const bridgePath = path.join(projectRoot, '.omp', 'hooks', 'pre', 'ukit-bridge.js');
+  const bridgeExists = await pathExists(bridgePath);
+  const requiredDenyMatches = await readTemplateDenyMatches();
+  const installedDenyMatches = new Set(
+    bashPatterns
+      .filter((entry) => entry && entry.approval === 'deny' && typeof entry.match === 'string')
+      .map((entry) => entry.match),
+  );
+  const missingDenyMatches = requiredDenyMatches.filter((m) => !installedDenyMatches.has(m));
+  const guardState = !bridgeExists
+    ? 'degraded'
+    : (missingDenyMatches.length > 0 ? 'partial' : 'enabled');
+
+  let loopGuidanceInstalled = false;
+  let instructionDocExists = false;
+  for (const docName of ['CLAUDE.md', 'AGENTS.md']) {
+    try {
+      const text = await fs.readFile(path.join(projectRoot, docName), 'utf8');
+      instructionDocExists = true;
+      if (text.includes(COMPLETION_LOOP_HEADER)) {
+        loopGuidanceInstalled = true;
+        break;
+      }
+    } catch {
+      // file may not exist
+    }
+  }
+
+  const check = (label, passed, remediationClass, remedy, extra = {}) => ({
+    label,
+    passed,
+    failed: !passed,
+    remediationClass,
+    remedy,
+    ...extra,
+  });
+
+  const checks = [
+    // 1 — permissionMode declared
+    check(
+      '`permissionMode` declared',
+      permissionModeValid,
+      'owner-action',
+      `Set orchestration.permissionMode in .ukit/storage/config.json to one of: ${[...VALID_PERMISSION_MODES].join(', ')}.`,
+      permissionModeRaw === undefined ? { detail: 'unattended (default)' } : {},
+    ),
+    // 2 — effective approvalMode is yolo
+    effectiveApprovalMode === null
+      ? check(
+        'effective approvalMode is `yolo`',
+        false,
+        'install-repairable',
+        INSTALL_REPAIR,
+        {
+          applicable: false,
+          detail: omp.exists
+            ? 'no tools.approvalMode readable (omp unavailable and YAML value absent)'
+            : 'no .omp/config.yml project override',
+        },
+      )
+      : check(
+        'effective approvalMode is `yolo`',
+        effectiveApprovalMode === 'yolo',
+        'install-repairable',
+        'Run ukit install to pin tools.approvalMode: yolo in .omp/config.yml.',
+        { detail: `value: ${effectiveApprovalMode} (source: ${approvalSource})` },
+      ),
+    // 3 — eval/bash policy allow
+    check(
+      "eval/bash policy 'allow'",
+      omp.exists && approvalMap.eval === 'allow' && approvalMap.bash === 'allow',
+      'install-repairable',
+      'Run ukit install to restore tools.approval.eval/bash: allow.',
+      omp.exists
+        ? {}
+        : { applicable: false, detail: '.omp/config.yml absent' },
+    ),
+    // 4 — zero prompt policies
+    check(
+      'zero `prompt` policies',
+      promptPolicyCount === 0,
+      'install-repairable',
+      'Run ukit install to strip `prompt` approvals (unattended mode cannot surface prompts).',
+      {
+        ...(omp.exists ? {} : { applicable: false, detail: '.omp/config.yml absent' }),
+        detail: `${promptPolicyCount} prompt policy(ies)`,
+      },
+    ),
+    // 5 — project override active
+    check(
+      'project override active',
+      omp.exists,
+      'advisory',
+      'Run ukit install to materialize the project .omp/config.yml override.',
+      omp.exists ? {} : { applicable: false, detail: '.omp/config.yml absent' },
+    ),
+    // 6 — completion loop guidance installed
+    check(
+      'completion loop guidance installed',
+      loopGuidanceInstalled,
+      'install-repairable',
+      `Run ukit install to add the '${COMPLETION_LOOP_HEADER}' section to CLAUDE.md/AGENTS.md.`,
+      instructionDocExists ? {} : { applicable: false, detail: 'no CLAUDE.md/AGENTS.md' },
+    ),
+    // 7 — safety guard enabled
+    check(
+      'safety guard enabled',
+      guardState === 'enabled',
+      'advisory',
+      !bridgeExists
+        ? 'Restore .omp/hooks/pre/ukit-bridge.js (run ukit install); guard is degraded.'
+        : `Add the missing deny patterns to .omp/config.yml bash.patterns (${missingDenyMatches.length} missing).`,
+      {
+        ...(omp.exists || bridgeExists ? {} : { applicable: false }),
+        detail: `guard state: ${guardState}${missingDenyMatches.length > 0 ? ` (${missingDenyMatches.length} deny pattern(s) missing)` : ''}`,
+      },
+    ),
+  ];
+
+  return {
+    checks,
+    summary: {
+      permissionMode,
+      effectiveApprovalMode,
+      promptPolicyCount,
+      guardState,
+    },
+  };
+}

package/src/diagnostics/failurePatterns.js

@@ -19,10 +19,9 @@
 
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { listLedgerFiles, LEDGER_DIR_REL } from './ledgerFiles.js';
 
-const LEDGER_DIR_REL = path.join('.ukit', 'storage', 'cache', 'exec-ledger');
 const ARTIFACT_REL = path.join('.ukit', 'storage', 'cache', 'failure-patterns.json');
-const NON_LEDGER_FILES = new Set(['gate-crash-counter.json']);
 const MAX_PATTERNS = 10;
 const MAX_EXAMPLES = 3;
 
@@ -33,14 +32,6 @@ function isObject(value) {
   return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }
 
-function isLedgerFilename(name) {
-  if (typeof name !== 'string' || !name.endsWith('.json')) return false;
-  if (NON_LEDGER_FILES.has(name)) return false;
-  if (name.includes('.journal')) return false;
-  if (name.includes('.quarantine')) return false;
-  return true;
-}
-
 // First two whitespace tokens, lowercased; path-like or numeric tokens become `<arg>`.
 function normalizeSignature(command) {
   if (typeof command !== 'string') return null;
@@ -74,30 +65,6 @@ function failureCommands(ledger) {
   return out;
 }
 
-async function listLedgerFiles(dir, limit) {
-  let entries;
-  try {
-    entries = await fs.readdir(dir, { withFileTypes: true });
-  } catch {
-    return [];
-  }
-  const files = [];
-  for (const entry of entries) {
-    if (!entry.isFile() || !isLedgerFilename(entry.name)) continue;
-    files.push(entry.name);
-  }
-  const withMtime = await Promise.all(files.map(async (name) => {
-    try {
-      const stat = await fs.stat(path.join(dir, name));
-      return { name, mtimeMs: stat.mtimeMs };
-    } catch {
-      return { name, mtimeMs: 0 };
-    }
-  }));
-  withMtime.sort((a, b) => b.mtimeMs - a.mtimeMs);
-  return withMtime.slice(0, limit).map((f) => f.name);
-}
-
 async function writeArtifact(filePath, result) {
   const dir = path.dirname(filePath);
   const tmp = path.join(dir, `.failure-patterns-${process.pid}.tmp`);

package/src/diagnostics/feedbackEvents.js

@@ -0,0 +1,196 @@
+// feedbackEvents.js — labeled wrong-route feedback events collector (SPEC C32 §3b).
+//
+// Derives labeled events from telemetry already on disk:
+//   * rescue          — route-audit entry with `rescueMode != null` → detail = rescueMode
+//   * re-route        — consecutive same-fingerprint audit entries where the later
+//                       entry changed executionMode (detail "<prev>→<new>")
+//   * repeat-stall    — audit `repeatCount >= minRepeat` with no matching
+//                       ledger `writeSucceeded` (join on requestKey)
+//   * user-correction — manual labels appended by `ukit feedback "<text>"` to
+//                       `.ukit/storage/cache/feedback-manual.jsonl`
+//
+// Contracts:
+//   * NEVER THROWS. Missing/malformed telemetry → zeroed result, `error` field
+//     on failure. Artifact write failure is non-fatal.
+//   * EVIDENCE-ONLY. The only side effect is the advisory artifact
+//     `.ukit/storage/learning/feedback-events.json` (tmp+rename).
+//   * Gated by config `learning?.feedback?.enabled !== false` (default true;
+//     the `learning` namespace lands in TASK-232 so the read is defensive).
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { listLedgerFiles, LEDGER_DIR_REL } from './ledgerFiles.js';
+
+const CACHE_DIR_REL = path.join('.ukit', 'storage', 'cache');
+const AUDIT_REL = path.join(CACHE_DIR_REL, 'route-audit.json');
+const MANUAL_REL = path.join(CACHE_DIR_REL, 'feedback-manual.jsonl');
+const ARTIFACT_REL = path.join('.ukit', 'storage', 'learning', 'feedback-events.json');
+const CONFIG_REL = path.join('.ukit', 'storage', 'config.json');
+const MAX_EVENTS = 200;
+
+function isObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function zeroedResult(extra = {}) {
+  return {
+    generatedAt: new Date().toISOString(),
+    auditRowsScanned: 0,
+    ledgersScanned: 0,
+    byKind: { rescue: 0, 're-route': 0, 'repeat-stall': 0, 'user-correction': 0 },
+    events: [],
+    ...extra,
+  };
+}
+
+async function readJson(filePath) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// Default true when `learning`/`feedback` is absent (namespace lands in TASK-232).
+async function feedbackEnabled(projectRoot) {
+  const config = await readJson(path.join(projectRoot, CONFIG_REL));
+  return config?.learning?.feedback?.enabled !== false;
+}
+
+// Manual jsonl is field-tolerant: unknown keys ignored, a legacy `context`
+// key is treated as an optional extra. Bad lines are skipped, not fatal.
+async function readManualEvents(projectRoot, byKind) {
+  const events = [];
+  let raw;
+  try {
+    raw = await fs.readFile(path.join(projectRoot, MANUAL_REL), 'utf8');
+  } catch {
+    return events;
+  }
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let record;
+    try {
+      record = JSON.parse(trimmed);
+    } catch {
+      continue;
+    }
+    if (!isObject(record) || typeof record.text !== 'string') continue;
+    const event = {
+      ts: typeof record.ts === 'number' ? record.ts : 0,
+      kind: 'user-correction',
+      detail: record.text,
+      source: 'manual',
+    };
+    if (typeof record.targetFile === 'string') event.targetFile = record.targetFile;
+    events.push(event);
+    byKind['user-correction'] += 1;
+  }
+  return events;
+}
+
+async function writeArtifact(filePath, result) {
+  const dir = path.dirname(filePath);
+  const tmp = path.join(dir, `.feedback-events-${process.pid}.tmp`);
+  try {
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(tmp, JSON.stringify(result, null, 2));
+    await fs.rename(tmp, filePath);
+  } catch {
+    await fs.rm(tmp, { force: true }).catch(() => {});
+  }
+}
+
+/**
+ * Collect labeled wrong-route feedback events.
+ *
+ * @param {string} projectRoot repository root containing `.ukit/storage/`.
+ * @param {{ limitLedgers?: number, minRepeat?: number }} [options]
+ * @returns {Promise<{generatedAt: string, auditRowsScanned: number,
+ *   ledgersScanned: number, byKind: Record<string, number>,
+ *   events: Array<object>, error?: string}>} never throws.
+ */
+export async function collectFeedbackEvents(projectRoot, { limitLedgers = 500, minRepeat = 2 } = {}) {
+  const result = zeroedResult();
+  try {
+    if (!(await feedbackEnabled(projectRoot))) {
+      return result;
+    }
+
+    const auditDoc = await readJson(path.join(projectRoot, AUDIT_REL));
+    const auditEntries = Array.isArray(auditDoc?.entries)
+      ? auditDoc.entries.filter(isObject)
+      : [];
+    result.auditRowsScanned = auditEntries.length;
+
+    const ledgerDir = path.join(projectRoot, LEDGER_DIR_REL);
+    const ledgerNames = await listLedgerFiles(ledgerDir, limitLedgers);
+    const writeOkKeys = new Set();
+    for (const name of ledgerNames) {
+      const ledger = await readJson(path.join(ledgerDir, name));
+      if (!isObject(ledger)) continue;
+      result.ledgersScanned += 1;
+      if (ledger.writeSucceeded === true && typeof ledger.requestKey === 'string') {
+        writeOkKeys.add(ledger.requestKey);
+      }
+    }
+
+    const events = [];
+    for (const entry of auditEntries) {
+      const base = {
+        ts: typeof entry.ts === 'number' ? entry.ts : 0,
+        requestKey: typeof entry.requestKey === 'string' ? entry.requestKey : undefined,
+        targetFile: typeof entry.targetFile === 'string' ? entry.targetFile : undefined,
+        taskType: typeof entry.taskType === 'string' ? entry.taskType : undefined,
+        executionMode: typeof entry.executionMode === 'string' ? entry.executionMode : undefined,
+        source: 'derived',
+      };
+
+      if (entry.rescueMode != null) {
+        events.push({ ...base, kind: 'rescue', detail: String(entry.rescueMode) });
+        result.byKind.rescue += 1;
+      }
+
+      if ((entry.repeatCount ?? 0) >= minRepeat && !writeOkKeys.has(entry.requestKey)) {
+        events.push({ ...base, kind: 'repeat-stall', detail: `repeatCount=${entry.repeatCount}` });
+        result.byKind['repeat-stall'] += 1;
+      }
+    }
+
+    // re-route: audit is newest-first — entry i is the later entry, i+1 the
+    // previous one for the same promptFingerprint + targetFile.
+    for (let i = 0; i < auditEntries.length - 1; i += 1) {
+      const later = auditEntries[i];
+      const prev = auditEntries[i + 1];
+      if (typeof later.promptFingerprint !== 'string' || !later.promptFingerprint) continue;
+      if (later.promptFingerprint !== prev.promptFingerprint) continue;
+      if (later.targetFile !== prev.targetFile) continue;
+      if (later.wideningBlocked === true) continue;
+      const prevMode = prev.executionMode;
+      const newMode = later.executionMode;
+      if (prevMode == null || newMode == null || prevMode === newMode) continue;
+      events.push({
+        ts: typeof later.ts === 'number' ? later.ts : 0,
+        kind: 're-route',
+        requestKey: typeof later.requestKey === 'string' ? later.requestKey : undefined,
+        targetFile: typeof later.targetFile === 'string' ? later.targetFile : undefined,
+        taskType: typeof later.taskType === 'string' ? later.taskType : undefined,
+        executionMode: typeof later.executionMode === 'string' ? later.executionMode : undefined,
+        detail: `${prevMode}→${newMode}`,
+        source: 'derived',
+      });
+      result.byKind['re-route'] += 1;
+    }
+
+    events.push(...await readManualEvents(projectRoot, result.byKind));
+
+    events.sort((a, b) => b.ts - a.ts);
+    result.events = events.slice(0, MAX_EVENTS);
+  } catch (error) {
+    result.error = error?.message ?? String(error);
+  }
+
+  await writeArtifact(path.join(projectRoot, ARTIFACT_REL), result);
+  return result;
+}

package/src/diagnostics/laneStats.js

@@ -0,0 +1,111 @@
+// laneStats.js — retriever lane contribution stats (SPEC C32 §5b).
+//
+// Reads `.ukit/storage/cache/retriever-lanes.jsonl` emitted by the retriever
+// (FR-202b) and rolls up per-lane counters:
+//   retrievals   = events where the lane had hits > 0
+//   totalHits    = sum of lane hits
+//   exclusive    = events where this lane was the SOLE lane with hits > 0
+//                  (emitters record per-lane hit counts only, so exclusivity
+//                  is approximated rather than per-path recomputed)
+//   avgWeight    = mean weightUsed over events that recorded one
+//   contribution = retrievals / max(1, events)
+//
+// Contracts: NEVER THROWS — missing/empty file → `empty: true` + zeroed lanes.
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const LANES_REL = path.join('.ukit', 'storage', 'cache', 'retriever-lanes.jsonl');
+
+function isObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function zeroedResult(extra = {}) {
+  return {
+    generatedAt: new Date().toISOString(),
+    events: 0,
+    lanes: {},
+    empty: false,
+    ...extra,
+  };
+}
+
+function emptyLaneBucket() {
+  return {
+    retrievals: 0,
+    totalHits: 0,
+    exclusive: 0,
+    avgWeight: 0,
+    contribution: 0,
+    _weightSum: 0,
+    _weightCount: 0,
+  };
+}
+
+/**
+ * Collect retriever lane contribution stats.
+ *
+ * @param {string} projectRoot repository root containing `.ukit/storage/`.
+ * @param {{ maxEvents?: number }} [options]
+ * @returns {Promise<object>} never throws.
+ */
+export async function collectLaneStats(projectRoot, { maxEvents = 2000 } = {}) {
+  const result = zeroedResult();
+  try {
+    let raw;
+    try {
+      raw = await fs.readFile(path.join(projectRoot, LANES_REL), 'utf8');
+    } catch {
+      return { ...result, empty: true };
+    }
+    const lines = raw.split('\n');
+    const events = [];
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      try {
+        const record = JSON.parse(trimmed);
+        if (isObject(record) && isObject(record.lanes)) events.push(record);
+      } catch {
+        // skip malformed line
+      }
+      if (events.length >= maxEvents) break;
+    }
+    if (events.length === 0) {
+      return { ...result, empty: true };
+    }
+    result.events = events.length;
+
+    for (const event of events) {
+      const positive = [];
+      for (const [lane, stats] of Object.entries(event.lanes)) {
+        if (!isObject(stats)) continue;
+        const bucket = result.lanes[lane] ??= emptyLaneBucket();
+        const hits = typeof stats.hits === 'number' ? stats.hits : 0;
+        if (hits > 0) {
+          bucket.retrievals += 1;
+          bucket.totalHits += hits;
+          positive.push(lane);
+        }
+        if (typeof stats.weightUsed === 'number') {
+          bucket._weightSum += stats.weightUsed;
+          bucket._weightCount += 1;
+        }
+      }
+      if (positive.length === 1) {
+        result.lanes[positive[0]].exclusive += 1;
+      }
+    }
+
+    for (const bucket of Object.values(result.lanes)) {
+      bucket.avgWeight = bucket._weightCount === 0 ? 0 : bucket._weightSum / bucket._weightCount;
+      bucket.contribution = bucket.retrievals / Math.max(1, result.events);
+      delete bucket._weightSum;
+      delete bucket._weightCount;
+    }
+  } catch (error) {
+    result.error = error?.message ?? String(error);
+  }
+  return result;
+}

package/src/diagnostics/ledgerFiles.js

@@ -0,0 +1,47 @@
+// ledgerFiles.js — shared exec-ledger directory helpers (SPEC C32 §3a).
+//
+// Extracted from failurePatterns.js so feedbackEvents (and any future
+// ledger-scanning diagnostics) share one glob/mtime discipline:
+//   * glob `*.json`, skip `gate-crash-counter.json`, `*.journal*`,
+//     `*.quarantine*`, bound results by mtime-desc order.
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export const LEDGER_DIR_REL = path.join('.ukit', 'storage', 'cache', 'exec-ledger');
+
+const NON_LEDGER_FILES = new Set(['gate-crash-counter.json']);
+
+export function isLedgerFilename(name) {
+  if (typeof name !== 'string' || !name.endsWith('.json')) return false;
+  if (NON_LEDGER_FILES.has(name)) return false;
+  if (name.includes('.journal')) return false;
+  if (name.includes('.quarantine')) return false;
+  return true;
+}
+
+// Returns up to `limit` ledger filenames sorted by mtime descending.
+// Missing/unreadable dir → [] (never throws).
+export async function listLedgerFiles(dir, limit) {
+  let entries;
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const files = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !isLedgerFilename(entry.name)) continue;
+    files.push(entry.name);
+  }
+  const withMtime = await Promise.all(files.map(async (name) => {
+    try {
+      const stat = await fs.stat(path.join(dir, name));
+      return { name, mtimeMs: stat.mtimeMs };
+    } catch {
+      return { name, mtimeMs: 0 };
+    }
+  }));
+  withMtime.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return withMtime.slice(0, Math.max(0, limit)).map((f) => f.name);
+}