@luanpdd/kit-mcp 1.18.0 → 1.20.0

package/src/core/kit.js

@@ -1,216 +1,216 @@
-// Read the canonical kit/ directory and return a structured index.
-// Source of truth: kit/agents/*.md, kit/commands/*.md, kit/skills/*/SKILL.md
-//
-// Frontmatter is parsed loosely (no external dep) — we only need name & description.
-
-import path from 'node:path';
-import fs from 'node:fs/promises';
-import { fileURLToPath } from 'node:url';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname  = path.dirname(__filename);
-
-// PERF-02: Frontmatter regexes compiled once at module load (was being recompiled
-// on every readMdDir / readSkillsDir entry — 60+ times per listKit call).
-const FRONTMATTER_SPLIT_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
-const FRONTMATTER_RAW_RE   = /^(---\r?\n[\s\S]*?\r?\n---\r?\n?)/;
-const YAML_KEY_RE          = /^([A-Za-z0-9_-]+):\s*(.*)$/;
-
-// Resolution order for the kit root (re-evaluated on each call so env-var
-// overrides set after module load — e.g. by the CLI preAction hook — work):
-//   1. explicit `kitRoot` opt passed by caller
-//   2. KIT_MCP_KIT_ROOT env var (per-session override)
-//   3. ./kit relative to this package (the bundled example kit)
-export const BUNDLED_KIT_ROOT = path.resolve(__dirname, '../../kit');
-export function resolveKitRoot(kitRoot) {
-  if (kitRoot) return path.resolve(kitRoot);
-  if (process.env.KIT_MCP_KIT_ROOT) return path.resolve(process.env.KIT_MCP_KIT_ROOT);
-  return BUNDLED_KIT_ROOT;
-}
-
-// PERF-01: TTL cache for listKit output. Repeated calls within KIT_CACHE_TTL_MS
-// return the cached value — sync/reverse-sync/MCP list-* tools used to walk the
-// disk on every invocation. Trade-off: callers that edit kit/ inside the same
-// process may see stale data for up to 30s. Acceptable for MCP/CLI ergonomics.
-const KIT_CACHE_TTL_MS = 30_000;
-const kitCache = new Map(); // `${kitRoot}:${mode}` -> { value, ts }
-
-// PERF-S1: when sync runs in mode=reference (default), the body/content of each
-// kit file is never used — only frontmatter (name + description). Reading just
-// the first STUB_READ_BYTES is enough for any frontmatter we'd ever produce and
-// avoids loading 50 KB+ files (planner.md etc) from disk.
-const STUB_READ_BYTES = 4096;
-
-export function clearKitCache() { kitCache.clear(); }
-
-export async function listKit(kitRoot, opts = {}) {
-  kitRoot = resolveKitRoot(kitRoot);
-  const stubsOnly = opts.stubsOnly === true;
-  const cacheKey = `${kitRoot}:${stubsOnly ? 'stubs' : 'full'}`;
-  const cached = kitCache.get(cacheKey);
-  if (cached && Date.now() - cached.ts < KIT_CACHE_TTL_MS) {
-    return cached.value;
-  }
-  const [agents, commands, skills, skillsExtras] = await Promise.all([
-    readMdDir(path.join(kitRoot, 'agents'),    'agent',   { stubsOnly }),
-    readMdDir(path.join(kitRoot, 'commands'),  'command', { stubsOnly }),
-    readSkillsDir(path.join(kitRoot, 'skills'), { stubsOnly }),
-    readSkillsDir(path.join(kitRoot, 'skills-extras'), { stubsOnly }).catch(() => []),
-  ]);
-  const value = { agents, commands, skills, skillsExtras, kitRoot, stubsOnly };
-  kitCache.set(cacheKey, { value, ts: Date.now() });
-  return value;
-}
-
-// Read just enough bytes from the head of the file to capture the frontmatter.
-// Returns the partial string. fs.open + fd.read avoids the OS pre-fetching the
-// rest of the file (which fs.readFile would force).
-async function readHead(absPath, n) {
-  const fd = await fs.open(absPath, 'r');
-  try {
-    const buf = Buffer.alloc(n);
-    const { bytesRead } = await fd.read(buf, 0, n, 0);
-    return buf.subarray(0, bytesRead).toString('utf8');
-  } finally {
-    await fd.close();
-  }
-}
-
-async function readMdDir(dir, kind, { stubsOnly = false } = {}) {
-  let entries;
-  try {
-    entries = await fs.readdir(dir, { withFileTypes: true });
-  } catch {
-    return [];
-  }
-  const out = [];
-  for (const e of entries) {
-    if (!e.isFile() || !e.name.endsWith('.md')) continue;
-    const absPath = path.join(dir, e.name);
-    const raw = stubsOnly
-      ? await readHead(absPath, STUB_READ_BYTES)
-      : await fs.readFile(absPath, 'utf8');
-    const { frontmatter, body } = splitFrontmatter(raw);
-    const item = {
-      kind,
-      name: e.name.replace(/\.md$/, ''),
-      absPath,
-      frontmatter,
-      frontmatterRaw: matchFrontmatterRaw(raw),
-      description: frontmatter?.description ?? firstNonEmptyLine(body),
-    };
-    if (!stubsOnly) {
-      item.body = body;
-      item.content = raw;
-    }
-    out.push(item);
-  }
-  return out.sort((a, b) => a.name.localeCompare(b.name));
-}
-
-async function readSkillsDir(dir, { stubsOnly = false } = {}) {
-  let entries;
-  try {
-    entries = await fs.readdir(dir, { withFileTypes: true });
-  } catch {
-    return [];
-  }
-  const out = [];
-  for (const e of entries) {
-    if (!e.isDirectory()) continue;
-    const skillPath = path.join(dir, e.name, 'SKILL.md');
-    let raw;
-    try {
-      raw = stubsOnly
-        ? await readHead(skillPath, STUB_READ_BYTES)
-        : await fs.readFile(skillPath, 'utf8');
-    } catch { continue; }
-    const { frontmatter, body } = splitFrontmatter(raw);
-    const item = {
-      kind: 'skill',
-      name: e.name,
-      absPath: skillPath,
-      dirPath: path.join(dir, e.name),
-      frontmatter,
-      frontmatterRaw: matchFrontmatterRaw(raw),
-      description: frontmatter?.description ?? firstNonEmptyLine(body),
-    };
-    if (!stubsOnly) {
-      item.body = body;
-      item.skillContent = raw;
-    }
-    out.push(item);
-  }
-  return out.sort((a, b) => a.name.localeCompare(b.name));
-}
-
-// --- minimal YAML-ish frontmatter parser (no deps) ---
-// Handles `key: value`, `key: >` multiline, but NOT nested objects/arrays.
-// Good enough for our SKILL.md / agent.md headers.
-
-function splitFrontmatter(raw) {
-  const m = raw.match(FRONTMATTER_SPLIT_RE);
-  if (!m) return { frontmatter: null, body: raw };
-  return { frontmatter: parseLooseYaml(m[1]), body: m[2] };
-}
-
-function matchFrontmatterRaw(raw) {
-  const m = raw.match(FRONTMATTER_RAW_RE);
-  return m ? m[1] : '';
-}
-
-function parseLooseYaml(text) {
-  const out = {};
-  const lines = text.split(/\r?\n/);
-  let i = 0;
-  while (i < lines.length) {
-    const line = lines[i];
-    const m = line.match(YAML_KEY_RE);
-    if (!m) { i++; continue; }
-    const key = m[1];
-    let val = m[2];
-    if (val === '>' || val === '|') {
-      // Multiline: collect indented lines
-      const collected = [];
-      i++;
-      while (i < lines.length && /^\s+/.test(lines[i])) {
-        collected.push(lines[i].replace(/^\s+/, ''));
-        i++;
-      }
-      out[key] = collected.join(' ').trim();
-      continue;
-    }
-    out[key] = val.trim().replace(/^["']|["']$/g, '');
-    i++;
-  }
-  return out;
-}
-
-function firstNonEmptyLine(body) {
-  for (const line of body.split(/\r?\n/)) {
-    const t = line.trim();
-    if (!t) continue;                      // blank
-    if (t.startsWith('#')) continue;       // markdown heading
-    if (t.startsWith('<!--')) continue;    // HTML comment (e.g. STUB_MARKER)
-    return t.slice(0, 200);
-  }
-  return '';
-}
-
-// --- search helpers ---
-
-export function searchKit(kit, query) {
-  const q = query.toLowerCase();
-  const all = [...kit.agents, ...kit.commands, ...kit.skills, ...kit.skillsExtras];
-  return all.filter(item =>
-    item.name.toLowerCase().includes(q) ||
-    (item.description ?? '').toLowerCase().includes(q)
-  ).map(({ kind, name, description, absPath }) => ({ kind, name, description, absPath }));
-}
-
-export function findItem(kit, kind, name) {
-  const buckets = { agent: kit.agents, command: kit.commands, skill: [...kit.skills, ...kit.skillsExtras] };
-  const b = buckets[kind];
-  if (!b) throw new Error(`Unknown kind: ${kind}`);
-  return b.find(x => x.name === name) ?? null;
-}
+// Read the canonical kit/ directory and return a structured index.
+// Source of truth: kit/agents/*.md, kit/commands/*.md, kit/skills/*/SKILL.md
+//
+// Frontmatter is parsed loosely (no external dep) — we only need name & description.
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname  = path.dirname(__filename);
+
+// PERF-02: Frontmatter regexes compiled once at module load (was being recompiled
+// on every readMdDir / readSkillsDir entry — 60+ times per listKit call).
+const FRONTMATTER_SPLIT_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+const FRONTMATTER_RAW_RE   = /^(---\r?\n[\s\S]*?\r?\n---\r?\n?)/;
+const YAML_KEY_RE          = /^([A-Za-z0-9_-]+):\s*(.*)$/;
+
+// Resolution order for the kit root (re-evaluated on each call so env-var
+// overrides set after module load — e.g. by the CLI preAction hook — work):
+//   1. explicit `kitRoot` opt passed by caller
+//   2. KIT_MCP_KIT_ROOT env var (per-session override)
+//   3. ./kit relative to this package (the bundled example kit)
+export const BUNDLED_KIT_ROOT = path.resolve(__dirname, '../../kit');
+export function resolveKitRoot(kitRoot) {
+  if (kitRoot) return path.resolve(kitRoot);
+  if (process.env.KIT_MCP_KIT_ROOT) return path.resolve(process.env.KIT_MCP_KIT_ROOT);
+  return BUNDLED_KIT_ROOT;
+}
+
+// PERF-01: TTL cache for listKit output. Repeated calls within KIT_CACHE_TTL_MS
+// return the cached value — sync/reverse-sync/MCP list-* tools used to walk the
+// disk on every invocation. Trade-off: callers that edit kit/ inside the same
+// process may see stale data for up to 30s. Acceptable for MCP/CLI ergonomics.
+const KIT_CACHE_TTL_MS = 30_000;
+const kitCache = new Map(); // `${kitRoot}:${mode}` -> { value, ts }
+
+// PERF-S1: when sync runs in mode=reference (default), the body/content of each
+// kit file is never used — only frontmatter (name + description). Reading just
+// the first STUB_READ_BYTES is enough for any frontmatter we'd ever produce and
+// avoids loading 50 KB+ files (planner.md etc) from disk.
+const STUB_READ_BYTES = 4096;
+
+export function clearKitCache() { kitCache.clear(); }
+
+export async function listKit(kitRoot, opts = {}) {
+  kitRoot = resolveKitRoot(kitRoot);
+  const stubsOnly = opts.stubsOnly === true;
+  const cacheKey = `${kitRoot}:${stubsOnly ? 'stubs' : 'full'}`;
+  const cached = kitCache.get(cacheKey);
+  if (cached && Date.now() - cached.ts < KIT_CACHE_TTL_MS) {
+    return cached.value;
+  }
+  const [agents, commands, skills, skillsExtras] = await Promise.all([
+    readMdDir(path.join(kitRoot, 'agents'),    'agent',   { stubsOnly }),
+    readMdDir(path.join(kitRoot, 'commands'),  'command', { stubsOnly }),
+    readSkillsDir(path.join(kitRoot, 'skills'), { stubsOnly }),
+    readSkillsDir(path.join(kitRoot, 'skills-extras'), { stubsOnly }).catch(() => []),
+  ]);
+  const value = { agents, commands, skills, skillsExtras, kitRoot, stubsOnly };
+  kitCache.set(cacheKey, { value, ts: Date.now() });
+  return value;
+}
+
+// Read just enough bytes from the head of the file to capture the frontmatter.
+// Returns the partial string. fs.open + fd.read avoids the OS pre-fetching the
+// rest of the file (which fs.readFile would force).
+async function readHead(absPath, n) {
+  const fd = await fs.open(absPath, 'r');
+  try {
+    const buf = Buffer.alloc(n);
+    const { bytesRead } = await fd.read(buf, 0, n, 0);
+    return buf.subarray(0, bytesRead).toString('utf8');
+  } finally {
+    await fd.close();
+  }
+}
+
+async function readMdDir(dir, kind, { stubsOnly = false } = {}) {
+  let entries;
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const e of entries) {
+    if (!e.isFile() || !e.name.endsWith('.md')) continue;
+    const absPath = path.join(dir, e.name);
+    const raw = stubsOnly
+      ? await readHead(absPath, STUB_READ_BYTES)
+      : await fs.readFile(absPath, 'utf8');
+    const { frontmatter, body } = splitFrontmatter(raw);
+    const item = {
+      kind,
+      name: e.name.replace(/\.md$/, ''),
+      absPath,
+      frontmatter,
+      frontmatterRaw: matchFrontmatterRaw(raw),
+      description: frontmatter?.description ?? firstNonEmptyLine(body),
+    };
+    if (!stubsOnly) {
+      item.body = body;
+      item.content = raw;
+    }
+    out.push(item);
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+async function readSkillsDir(dir, { stubsOnly = false } = {}) {
+  let entries;
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    const skillPath = path.join(dir, e.name, 'SKILL.md');
+    let raw;
+    try {
+      raw = stubsOnly
+        ? await readHead(skillPath, STUB_READ_BYTES)
+        : await fs.readFile(skillPath, 'utf8');
+    } catch { continue; }
+    const { frontmatter, body } = splitFrontmatter(raw);
+    const item = {
+      kind: 'skill',
+      name: e.name,
+      absPath: skillPath,
+      dirPath: path.join(dir, e.name),
+      frontmatter,
+      frontmatterRaw: matchFrontmatterRaw(raw),
+      description: frontmatter?.description ?? firstNonEmptyLine(body),
+    };
+    if (!stubsOnly) {
+      item.body = body;
+      item.skillContent = raw;
+    }
+    out.push(item);
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+// --- minimal YAML-ish frontmatter parser (no deps) ---
+// Handles `key: value`, `key: >` multiline, but NOT nested objects/arrays.
+// Good enough for our SKILL.md / agent.md headers.
+
+function splitFrontmatter(raw) {
+  const m = raw.match(FRONTMATTER_SPLIT_RE);
+  if (!m) return { frontmatter: null, body: raw };
+  return { frontmatter: parseLooseYaml(m[1]), body: m[2] };
+}
+
+function matchFrontmatterRaw(raw) {
+  const m = raw.match(FRONTMATTER_RAW_RE);
+  return m ? m[1] : '';
+}
+
+function parseLooseYaml(text) {
+  const out = {};
+  const lines = text.split(/\r?\n/);
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    const m = line.match(YAML_KEY_RE);
+    if (!m) { i++; continue; }
+    const key = m[1];
+    let val = m[2];
+    if (val === '>' || val === '|') {
+      // Multiline: collect indented lines
+      const collected = [];
+      i++;
+      while (i < lines.length && /^\s+/.test(lines[i])) {
+        collected.push(lines[i].replace(/^\s+/, ''));
+        i++;
+      }
+      out[key] = collected.join(' ').trim();
+      continue;
+    }
+    out[key] = val.trim().replace(/^["']|["']$/g, '');
+    i++;
+  }
+  return out;
+}
+
+function firstNonEmptyLine(body) {
+  for (const line of body.split(/\r?\n/)) {
+    const t = line.trim();
+    if (!t) continue;                      // blank
+    if (t.startsWith('#')) continue;       // markdown heading
+    if (t.startsWith('<!--')) continue;    // HTML comment (e.g. STUB_MARKER)
+    return t.slice(0, 200);
+  }
+  return '';
+}
+
+// --- search helpers ---
+
+export function searchKit(kit, query) {
+  const q = query.toLowerCase();
+  const all = [...kit.agents, ...kit.commands, ...kit.skills, ...kit.skillsExtras];
+  return all.filter(item =>
+    item.name.toLowerCase().includes(q) ||
+    (item.description ?? '').toLowerCase().includes(q)
+  ).map(({ kind, name, description, absPath }) => ({ kind, name, description, absPath }));
+}
+
+export function findItem(kit, kind, name) {
+  const buckets = { agent: kit.agents, command: kit.commands, skill: [...kit.skills, ...kit.skillsExtras] };
+  const b = buckets[kind];
+  if (!b) throw new Error(`Unknown kind: ${kind}`);
+  return b.find(x => x.name === name) ?? null;
+}

package/src/core/metrics.js

@@ -1,4 +1,5 @@
 // OBS-18-01 / OBS-18-02 — in-memory golden signals for kit-mcp server.
+// OBS-19-01 / OBS-19-02 / OBS-19-03 — disk-persistent rolling snapshots.
 //
 // Phase 94: Eat Your Own Dog Food. The skill `four-golden-signals` says any
 // user-facing service worth its salt instruments Latency + Traffic + Errors
@@ -7,31 +8,48 @@
 // operator wants when something feels off.
 //
 // Scope decisions (see .planning/phases/94-golden-signals-mcp-server/94-CONTEXT.md):
-//   - Zero dependencies. Map + array stdlib only — preserves the 6-deps budget
-//     that Phase 92.01 fought to maintain and that Phase 93.01 enforces in CI.
-//   - In-memory only. No file persistence, no socket export, no OTel SDK.
-//     kit-mcp is a developer tool launched on demand by an IDE; cross-process
-//     telemetry pipelines are explicit non-goals (see <deferred> block in
-//     94-CONTEXT.md). A future phase can layer OTel on top of this API.
+//   - Zero new dependencies. Phase 99 adds fs/promises + path from stdlib only —
+//     the 6-deps budget Phase 92.01 fought to maintain and Phase 93.01 enforces
+//     in CI is preserved.
+//   - In-memory primary, on-demand persistence. The Map+array core stays
+//     in-memory; persistSnapshot writes a JSON file under .planning/metrics/
+//     snapshots/ when called. No background timer, no implicit writes — the
+//     /burn-rate-status command and metrics-snapshot tool are the writers.
 //   - Bounded memory. Histograms cap at HISTOGRAM_CAP=1000 samples per tool
-//     with FIFO drop. At cap, p50/p95/p99 over the latest 1000 samples is
-//     more useful than an unbounded array that could grow for the lifetime
-//     of a long-lived MCP session.
+//     with FIFO drop.
+//   - Bounded disk. cleanupOldSnapshots prunes files > 30 days old on every
+//     persistSnapshot call (rolling window, no separate retention job).
 //   - Snapshot is read-only. Returns a fresh plain-object copy so callers
 //     can JSON.stringify it without exposing internal Map references.
+//   - Persisted shape includes `ts` (epoch ms) inside the JSON. We do NOT
+//     parse the filename for windowing — filesystem-safe ISO encoding
+//     (`replace(/[:.]/g, '-')`) is one-way (cannot reliably round-trip back
+//     through Date.parse) and mtime is unreliable across copy/touch. The
+//     in-file ts is authoritative.
 //
-// API surface (4 exports):
+// API surface (5 exports + 2 async):
 //   incrementInvocation(tool, status)  — counter++ keyed `${tool}:${status}`
 //   recordLatency(tool, ms)            — push to histogram, FIFO at cap
 //   snapshot()                         — { counters, latency } plain object
 //   reset()                            — clear both maps; called on boot if
 //                                         KIT_MCP_METRICS_RESET=1
+//   persistSnapshot(rootDir)           — write {ts, counters, latency} to
+//                                         .planning/metrics/snapshots/<ts>.json
+//                                         + cleanup files > 30d
+//   loadSnapshots(rootDir, windowMs)   — read all snapshots whose in-file ts
+//                                         is within windowMs (default 30d),
+//                                         sorted ascending by ts
 //
 // Boot-time reset honors the env var by calling reset() at module load when
 // the flag is set. This keeps the signal "fresh" for a probe in tests or for
 // an operator who spawned the server with the flag for a clean comparison.
 
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
 const HISTOGRAM_CAP = 1000;
+const DEFAULT_RETENTION_MS = 30 * 86400 * 1000; // 30 days rolling.
+const SNAPSHOT_DIR_REL = path.join('.planning', 'metrics', 'snapshots');
 
 const counters = new Map();   // key: `${tool}:${status}` → count (number)
 const histograms = new Map(); // key: tool → number[] (length ≤ HISTOGRAM_CAP)
@@ -130,6 +148,112 @@ export function reset() {
   histograms.clear();
 }
 
+/**
+ * OBS-19-01 — Persist the current snapshot to disk under
+ * `<rootDir>/.planning/metrics/snapshots/<timestamp>.json`. Runs the rolling
+ * cleanup of files older than `retentionMs` (default 30d) on every call so
+ * callers don't need a separate retention job.
+ *
+ * The on-disk shape is `{ ts: <epoch_ms>, counters, latency }`. The `ts` field
+ * inside the JSON — NOT the filename — is the authoritative timestamp for
+ * loadSnapshots windowing. The filename uses an ISO encoding with `:` and `.`
+ * replaced by `-` for filesystem safety; that encoding is one-way (cannot
+ * round-trip back through Date.parse), so we never parse it for ordering.
+ *
+ * @param {string} [rootDir=process.cwd()]  Project root. Snapshots land under
+ *   `<rootDir>/.planning/metrics/snapshots/`.
+ * @param {object} [opts]
+ * @param {number} [opts.retentionMs]  Override the rolling-window age in ms.
+ *   Defaults to 30 days. Tests use shorter windows to drive the cleanup path.
+ * @returns {Promise<{file: string, snap: {ts: number, counters: object, latency: object}}>}
+ */
+export async function persistSnapshot(rootDir = process.cwd(), opts = {}) {
+  const retentionMs = Number.isFinite(opts.retentionMs) ? opts.retentionMs : DEFAULT_RETENTION_MS;
+  const dir = path.join(rootDir, SNAPSHOT_DIR_REL);
+  await fs.mkdir(dir, { recursive: true });
+  const ts = Date.now();
+  const snap = { ts, ...snapshot() };
+  // Filesystem-safe ISO encoding — Windows forbids `:` in paths and `.` is
+  // ambiguous with extension separators on shells with brace expansion.
+  const isoSafe = new Date(ts).toISOString().replace(/[:.]/g, '-');
+  const file = path.join(dir, `${isoSafe}.json`);
+  await fs.writeFile(file, JSON.stringify(snap, null, 2));
+  await cleanupOldSnapshots(dir, retentionMs);
+  return { file, snap };
+}
+
+/**
+ * OBS-19-02 — Load all snapshots from disk whose in-file `ts` is within the
+ * sliding window. Returns the array sorted ascending by `ts` so consumers
+ * (`/burn-rate-status`) can compute first-vs-last deltas without re-sorting.
+ *
+ * Defensive against malformed JSON: a corrupt file is skipped silently rather
+ * than aborting the whole load. The 30d window is rolling from "now" — pass a
+ * smaller value to drive recent-only views (e.g. `60 * 60 * 1000` for last
+ * hour) when computing burn rate over a baseline window.
+ *
+ * @param {string} [rootDir=process.cwd()]  Project root.
+ * @param {number} [windowMs]  Sliding window in ms. Defaults to 30 days.
+ * @returns {Promise<Array<{ts: number, counters: object, latency: object}>>}
+ *   Empty array if the snapshots directory does not exist.
+ */
+export async function loadSnapshots(rootDir = process.cwd(), windowMs = DEFAULT_RETENTION_MS) {
+  const dir = path.join(rootDir, SNAPSHOT_DIR_REL);
+  const cutoff = Date.now() - windowMs;
+  let files;
+  try {
+    files = await fs.readdir(dir);
+  } catch {
+    return []; // Dir absent on first run — not an error.
+  }
+  const results = [];
+  for (const f of files) {
+    if (!f.endsWith('.json')) continue;
+    try {
+      const raw = await fs.readFile(path.join(dir, f), 'utf-8');
+      const parsed = JSON.parse(raw);
+      if (Number.isFinite(parsed?.ts) && parsed.ts >= cutoff) {
+        results.push(parsed);
+      }
+    } catch {
+      // Corrupt file — skip silently rather than break the whole burn-rate
+      // calculation. A future phase can surface counts via a doctor probe.
+    }
+  }
+  return results.sort((a, b) => a.ts - b.ts);
+}
+
+/**
+ * OBS-19-03 — Internal helper: delete snapshot files older than `maxAgeMs`.
+ * Called from persistSnapshot on every write so retention is implicit.
+ * Uses fs.stat().mtimeMs as the age proxy; we accept the small drift versus
+ * the in-file `ts` because cleanup is best-effort eviction, not authoritative
+ * windowing (loadSnapshots reads the in-file ts).
+ *
+ * @param {string} dir         Absolute path to the snapshots directory.
+ * @param {number} maxAgeMs    Files with mtime older than this are unlinked.
+ * @returns {Promise<void>}
+ */
+async function cleanupOldSnapshots(dir, maxAgeMs) {
+  const cutoff = Date.now() - maxAgeMs;
+  let files;
+  try {
+    files = await fs.readdir(dir);
+  } catch {
+    return;
+  }
+  for (const f of files) {
+    if (!f.endsWith('.json')) continue;
+    const fp = path.join(dir, f);
+    try {
+      const stat = await fs.stat(fp);
+      if (stat.mtimeMs < cutoff) await fs.unlink(fp);
+    } catch {
+      // Unlink can race with concurrent cleanup; ignore ENOENT and friends.
+    }
+  }
+}
+
 // Boot-time reset honors KIT_MCP_METRICS_RESET=1. We call reset() instead of
 // merely skipping init because the maps are already empty at module load —
 // the call is a no-op today but documents the contract for any future module
@@ -141,3 +265,4 @@ if (process.env.KIT_MCP_METRICS_RESET === '1') {
 // Exported for tests only — keeps the API surface explicit while letting unit
 // tests assert on the FIFO behavior at the boundary.
 export const __TEST_HISTOGRAM_CAP = HISTOGRAM_CAP;
+export const __TEST_SNAPSHOT_DIR_REL = SNAPSHOT_DIR_REL;