@luanpdd/kit-mcp 1.16.0 → 1.18.0

package/kit/file-manifest.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.16.0",
-  "timestamp": "2026-05-09T14:17:38.936Z",
+  "version": "1.18.0",
+  "timestamp": "2026-05-09T17:01:35.745Z",
   "files": {
     "COMANDOS.md": "d24ec61a6ec35db314cc5f2ae287bfb927b794789c8f1d558c55862f5e6534b2",
     "COMPATIBILITY.md": "794e336a87045cdf0161785b9a7a0975a49abbd80bdd816b8852251fcc8126ca",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luanpdd/kit-mcp",
-  "version": "1.16.0",
+  "version": "1.18.0",
   "description": "Generic infrastructure to ship YOUR personal kit of agents/commands/skills as an MCP server, with cross-IDE sync (Claude Code, Cursor, Codex, Gemini, Windsurf, Antigravity, Copilot, Trae).",
   "type": "module",
   "bin": {
@@ -49,11 +49,11 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "commander": "^14.0.3",
-    "open": "^11.0.0",
     "picocolors": "^1.1.1"
   },
   "optionalDependencies": {
     "@inquirer/prompts": "^8.4.2",
-    "chokidar": "^5.0.0"
+    "chokidar": "^5.0.0",
+    "open": "^11.0.0"
   }
 }

package/src/cli/index.js

@@ -30,7 +30,7 @@ import { installMcp, listInstallTargets } from '../mcp-server/install.js';
 import * as render from './render.js';
 import { c, icons, spinner, progress, select, confirm } from '../core/ui.js';
 import { readLock, lockPathFor } from '../ui/lockfile.js';
-import { checkUpgrade, getLocalVersion } from './upgrade-check.js';
+import { checkUpgrade } from './upgrade-check.js';
 // PERF-16-04: ui/server.js, ui/wrapper.js, ui/browser.js are loaded LAZILY
 // inside the subcommand handlers that need them. See:
 //   - maybeWrapForUi (gated on lockfile presence)

package/src/core/manifest-verify.js

@@ -14,8 +14,39 @@ import path from 'node:path';
 import fs from 'node:fs/promises';
 import crypto from 'node:crypto';
 
+// PERF-17-01: parallelize SHA256 hashing in batches of 16. Same pattern
+// as Phase 88.01 sync.js. Hardcoded — env override is overengineering
+// for verifyManifest (single hot path, not user-facing latency budget).
+const BATCH_SIZE = 16;
+
+// PERF-17-01: in-memory cache for verifyManifest. Same pattern as kit.js
+// listKit cache (PERF-01). Watch triggers (file save → re-sync) call this
+// back-to-back; the 2nd+ call within TTL hits cache and returns <5ms.
+//
+// Caching rules:
+//   - Only cache ok=true results. mismatches/missing → recompute every call
+//     so devs see fixes immediately (don't punish them for the slow path).
+//   - Bypass via KIT_MCP_VERIFY_NO_CACHE=1 (test isolation + emergency dev escape).
+//   - Cache key is kitRoot — different roots are independent entries.
+const VERIFY_CACHE_TTL_MS = 30_000;
+const verifyManifestCache = new Map(); // kitRoot -> { value, ts }
+const NO_CACHE_ENV = 'KIT_MCP_VERIFY_NO_CACHE';
+
+/**
+ * Test/emergency helper — clears the cache. Exported for unit tests.
+ * Production code should never need this; use the env var instead.
+ */
+export function clearVerifyManifestCache() { verifyManifestCache.clear(); }
+
 const SKIP_ENV = 'KIT_MCP_SKIP_MANIFEST_CHECK';
 
+/**
+ * SEC-14-05: verify kit/file-manifest.json against actual file contents.
+ * PERF-17-01: hashes in Promise.all batches of 16 (was sequential pre-v1.17).
+ * Called by syncTo() in install path before any write — refuses to project a tampered kit.
+ * @param {string} kitRoot - absolute path to kit/ directory.
+ * @returns {Promise<{ok: boolean, skipped?: boolean, reason?: string, mismatches?: Array, missing?: string[]}>}
+ */
 export async function verifyManifest(kitRoot) {
   if (process.env[SKIP_ENV] === '1') {
     process.stderr.write(
@@ -24,6 +55,15 @@ export async function verifyManifest(kitRoot) {
     return { ok: true, skipped: true };
   }
 
+  // PERF-17-01: cache hit — repeated calls within TTL skip the I/O + hashing.
+  // Bypass via KIT_MCP_VERIFY_NO_CACHE=1 (tests + dev emergency escape).
+  if (process.env[NO_CACHE_ENV] !== '1') {
+    const cached = verifyManifestCache.get(kitRoot);
+    if (cached && Date.now() - cached.ts < VERIFY_CACHE_TTL_MS) {
+      return cached.value;
+    }
+  }
+
   const manifestPath = path.join(kitRoot, 'file-manifest.json');
   let manifest;
   try {
@@ -50,27 +90,54 @@ export async function verifyManifest(kitRoot) {
   const mismatches = [];
   const missing = [];
 
-  for (const [rel, expected] of Object.entries(manifest.files)) {
+  const entries = Object.entries(manifest.files);
+
+  // Per-file check — returns { rel, status: 'ok'|'mismatch'|'missing', expected?, actual? }.
+  // Pure function (no side effects on shared arrays) so Promise.all in batches
+  // is safe — caller aggregates after each batch resolves.
+  const checkOne = async ([rel, expected]) => {
     const abs = path.join(kitRoot, rel);
     let buf;
     try {
       buf = await fs.readFile(abs);
     } catch {
-      missing.push(rel);
-      continue;
+      return { rel, status: 'missing' };
     }
     // Normalize CRLF→LF before hashing so manifest is platform-stable.
     // git checkout converts EOL on Windows but Linux CI checks out LF —
-    // hashing raw bytes would diverge across platforms.
+    // hashing raw bytes would diverge across platforms. (PRESERVED from v1.15)
     const normalized = Buffer.from(buf.toString('binary').replace(/\r\n/g, '\n'), 'binary');
     const actual = crypto.createHash('sha256').update(normalized).digest('hex');
     if (actual !== expected) {
-      mismatches.push({ path: rel, expected: expected.slice(0, 16), actual: actual.slice(0, 16) });
+      return { rel, status: 'mismatch', expected, actual };
+    }
+    return { rel, status: 'ok' };
+  };
+
+  // Sequential batches — within a batch, Promise.all parallelizes hashing;
+  // between batches, await bounds max-in-flight at BATCH_SIZE (defensive
+  // against fd ulimit on large kits). Order of completion within a batch
+  // doesn't matter — aggregator below is order-independent.
+  for (let i = 0; i < entries.length; i += BATCH_SIZE) {
+    const slice = entries.slice(i, i + BATCH_SIZE);
+    const results = await Promise.all(slice.map(checkOne));
+    for (const r of results) {
+      if (r.status === 'mismatch') {
+        mismatches.push({ path: r.rel, expected: r.expected.slice(0, 16), actual: r.actual.slice(0, 16) });
+      } else if (r.status === 'missing') {
+        missing.push(r.rel);
+      }
     }
   }
 
   if (mismatches.length === 0 && missing.length === 0) {
-    return { ok: true };
+    const result = { ok: true };
+    // PERF-17-01: cache only ok=true. Mismatch/missing always recompute
+    // so dev fixing a tampered file sees the next sync recover immediately.
+    if (process.env[NO_CACHE_ENV] !== '1') {
+      verifyManifestCache.set(kitRoot, { value: result, ts: Date.now() });
+    }
+    return result;
   }
 
   // Build a concise reason — first 3 mismatches, plus counts.

package/src/core/metrics.js

@@ -0,0 +1,143 @@
+// OBS-18-01 / OBS-18-02 — in-memory golden signals for kit-mcp server.
+//
+// Phase 94: Eat Your Own Dog Food. The skill `four-golden-signals` says any
+// user-facing service worth its salt instruments Latency + Traffic + Errors
+// + Saturation. The MCP server qualifies — every tool call is a request from
+// an LLM client and tail latency / error rate are exactly the signals an
+// 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.
+//   - 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.
+//   - Snapshot is read-only. Returns a fresh plain-object copy so callers
+//     can JSON.stringify it without exposing internal Map references.
+//
+// API surface (4 exports):
+//   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
+//
+// 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.
+
+const HISTOGRAM_CAP = 1000;
+
+const counters = new Map();   // key: `${tool}:${status}` → count (number)
+const histograms = new Map(); // key: tool → number[] (length ≤ HISTOGRAM_CAP)
+
+/**
+ * Increment the invocation counter for a tool/status pair.
+ *
+ * @param {string} tool   Tool name as it appears in the MCP request payload.
+ * @param {'ok'|'error'} [status='ok']  Outcome of the dispatch.
+ * @returns {void}
+ */
+export function incrementInvocation(tool, status = 'ok') {
+  if (typeof tool !== 'string' || tool.length === 0) return;
+  const key = `${tool}:${status}`;
+  counters.set(key, (counters.get(key) ?? 0) + 1);
+}
+
+/**
+ * Record an observed latency for a tool. Drops the oldest sample (FIFO) once
+ * the per-tool histogram reaches HISTOGRAM_CAP, keeping memory bounded across
+ * long-lived MCP sessions.
+ *
+ * @param {string} tool   Tool name.
+ * @param {number} ms     Elapsed wall-clock time in milliseconds.
+ * @returns {void}
+ */
+export function recordLatency(tool, ms) {
+  if (typeof tool !== 'string' || tool.length === 0) return;
+  if (typeof ms !== 'number' || !Number.isFinite(ms) || ms < 0) return;
+  let arr = histograms.get(tool);
+  if (!arr) {
+    arr = [];
+    histograms.set(tool, arr);
+  }
+  arr.push(ms);
+  if (arr.length > HISTOGRAM_CAP) arr.shift(); // FIFO drop oldest sample
+}
+
+/**
+ * Compute a percentile over a sorted ascending array. Linear-interpolation
+ * variant matches the typical Prometheus / Datadog reading. For N≤1000
+ * (HISTOGRAM_CAP) the sort cost on snapshot is acceptable — snapshots are
+ * read on-demand by the metrics-snapshot tool, not on every dispatch.
+ *
+ * @param {number[]} sorted  Ascending-sorted samples.
+ * @param {number} p         Percentile in [0, 1].
+ * @returns {number}
+ */
+function percentile(sorted, p) {
+  if (sorted.length === 0) return 0;
+  if (sorted.length === 1) return sorted[0];
+  const rank = p * (sorted.length - 1);
+  const lo = Math.floor(rank);
+  const hi = Math.ceil(rank);
+  if (lo === hi) return sorted[lo];
+  const frac = rank - lo;
+  return sorted[lo] + (sorted[hi] - sorted[lo]) * frac;
+}
+
+/**
+ * Build a read-only snapshot of all metrics. Counters are returned as a plain
+ * object keyed `${tool}:${status}` → count. Latency is keyed by tool to a
+ * `{ p50, p95, p99, count }` triple so a single tool never appears split
+ * across status outcomes (latency observation point is a single line in the
+ * dispatcher, success and failure both record).
+ *
+ * @returns {{
+ *   counters: Record<string, number>,
+ *   latency:  Record<string, { p50: number, p95: number, p99: number, count: number }>
+ * }}
+ */
+export function snapshot() {
+  const out = { counters: {}, latency: {} };
+  for (const [key, val] of counters) out.counters[key] = val;
+  for (const [tool, samples] of histograms) {
+    if (samples.length === 0) continue;
+    const sorted = [...samples].sort((a, b) => a - b);
+    out.latency[tool] = {
+      p50: percentile(sorted, 0.50),
+      p95: percentile(sorted, 0.95),
+      p99: percentile(sorted, 0.99),
+      count: samples.length,
+    };
+  }
+  return out;
+}
+
+/**
+ * Clear both counters and histograms. Used by tests and by the boot-time
+ * KIT_MCP_METRICS_RESET=1 path so an operator can probe a fresh window.
+ *
+ * @returns {void}
+ */
+export function reset() {
+  counters.clear();
+  histograms.clear();
+}
+
+// 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
+// that imports metrics.js after another module has already populated state.
+if (process.env.KIT_MCP_METRICS_RESET === '1') {
+  reset();
+}
+
+// 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;

package/src/core/path-safety.js

@@ -32,6 +32,36 @@ import fs from 'node:fs/promises';
 // six regexes; one suffices.
 const SENTINEL = 'MCP sync requires projectRoot to be a git workspace';
 
+/**
+ * SEC-14-03: validate that a `projectRoot` supplied via MCP message points to
+ * a real git workspace before any handler dispatches into sync.js / reverse-sync.js.
+ *
+ * Pure function — never throws. Returns a discriminated union so MCP handlers
+ * can wrap rejections in `{ error }` envelopes without try/catch boilerplate
+ * (matches handleSync/handleGates/handleForensics in src/mcp-server/index.js).
+ *
+ * Validation chain (each step short-circuits on rejection):
+ *   1. `projectRoot` is non-empty string (rejects nullish, empty, non-string types).
+ *   2. `path.resolve()` collapses `..` segments and produces an absolute path.
+ *   3. The resolved path exists and is a directory (UNC failures bubble up here).
+ *   4. A `.git` entry exists somewhere in the ancestor chain (file or directory —
+ *      `git worktree` uses a file). Walk-up bounded by `path.dirname()` fixed point.
+ *
+ * The CLI does NOT call this — `bin/cli.js` trusts whoever invoked it (same
+ * trust model as Phase 79.01's gates.run guard). Only MCP-message-sourced paths
+ * need this check.
+ *
+ * Rejection reasons all embed the literal `"git workspace"` string — public
+ * contract relied on by test/unit/mcp-projectroot-guard.test.js and downstream
+ * MCP clients. Don't rephrase without coordinating callers.
+ *
+ * @param {unknown} projectRoot - the candidate path supplied by an MCP client.
+ *   Expected to be an absolute filesystem path; any other shape is rejected.
+ * @returns {Promise<{ok: true, resolvedPath: string} | {ok: false, reason: string}>}
+ *   On success, `resolvedPath` is the path-resolved absolute form of `projectRoot`
+ *   (callers should use it instead of the raw input). On failure, `reason` is a
+ *   human-readable string suitable for MCP `{error}` envelopes.
+ */
 export async function validateProjectRoot(projectRoot) {
   // Reject empty / nullish up-front. We require an explicit projectRoot from
   // MCP messages — falling back to `process.cwd()` of the MCP server would let

package/src/core/sync.js

@@ -31,6 +31,40 @@ function resolveBatchSize() {
   return n;
 }
 
+// PERF-17-02: opt-out of stat-based diff skip. Forces full sync (every op writes)
+// for cleanup/recovery scenarios where target files may be subtly out of sync
+// (manual edits, partial fs corruption) but pass the mtime+size diff heuristic.
+function resolveForceFullSync() {
+  return process.env.KIT_MCP_FORCE_FULL_SYNC === '1';
+}
+
+/**
+ * Project the canonical kit/ into an IDE-specific layout (claude-code, cursor, etc.).
+ *
+ * Workflow:
+ *   1. SEC-14-05: verifyManifest(kitRoot) — refuses tampered kits (Phase 83+90).
+ *   2. Build ops[] (rules + agents + commands + skills + framework/hooks treeCopy).
+ *   3. PERF-17-02: stat-based diff filter — skip treeCopy ops whose target already
+ *      matches source (mtime+size). Bypassed via KIT_MCP_FORCE_FULL_SYNC=1.
+ *   4. PERF-16-01: Promise.all batches=16 over writeOps (Phase 88.01).
+ *
+ * onProgress callback receives one event per op (written or skipped); skipped ops
+ * carry `skipped: true` for UI granularity.
+ *
+ * Stable API v1.0+ preserved: return shape unchanged. `written[]` lists all op
+ * paths (projected files), not just actually-written — semantics: "what's in the
+ * target tree after this call", not "what fs.writeFile ran".
+ *
+ * @param {string} targetId - registry target id (e.g. 'claude-code', 'cursor').
+ * @param {object} [opts]
+ * @param {string} [opts.projectRoot=process.cwd()] - destination project root.
+ * @param {string} [opts.kitRoot] - canonical kit/ root (auto-resolved if absent).
+ * @param {'reference'|'copy'|'symlink'} [opts.mode='reference'] - projection mode.
+ * @param {boolean} [opts.dryRun=false] - skip all fs writes; ops still listed.
+ * @param {Function} [opts.onProgress] - per-op callback ({phase, current, total, label, skipped?}).
+ * @param {object} [opts.kit] - pre-loaded kit (skips listKit re-walk).
+ * @returns {Promise<{target, mode, projectRoot, kitRoot, written, dryRun}>}
+ */
 export async function syncTo(targetId, opts = {}) {
   const target      = getTarget(targetId);
   const projectRoot = path.resolve(opts.projectRoot ?? process.cwd());
@@ -116,6 +150,51 @@ export async function syncTo(targetId, opts = {}) {
     let completed = 0;
     const total = ops.length;
 
+    // PERF-17-02: stat-based diff filter — skip ops whose target already matches source.
+    // Only applies to treeCopy ops (framework/hooks subtrees) — content ops (agents,
+    // commands, skills, rules) include `Generated by kit-mcp at ${ISO timestamp}` so
+    // they re-render every time and can't safely diff. treeCopy ops dominate wall
+    // time on large kits (327+ files), so this captures the PERF-17-02 win.
+    //
+    // Filter logic per op:
+    //   - forceFullSync env set     → never skip
+    //   - !treeCopy (content op)    → never skip
+    //   - target stat fails (absent)→ never skip (must write)
+    //   - src stat fails (defensive)→ never skip (let copy fail naturally)
+    //   - target.size === src.size AND target.mtimeMs >= src.mtimeMs → SKIP
+    //
+    // Implementation: Promise.all over ops produces { op, skip } pairs. Skipped ops
+    // emit onProgress({ skipped: true }) and increment the same `completed` counter
+    // as written ops (so progress UI shows full ops.length total).
+    const forceFullSync = resolveForceFullSync();
+
+    const diffOne = async (op) => {
+      if (forceFullSync) return { op, skip: false };
+      if (!op.treeCopy) return { op, skip: false };
+      let targetStat;
+      try { targetStat = await fs.stat(op.path); }
+      catch { return { op, skip: false }; }
+      let srcStat;
+      try { srcStat = await fs.stat(op.srcAbs); }
+      catch { return { op, skip: false }; }
+      if (targetStat.size === srcStat.size && targetStat.mtimeMs >= srcStat.mtimeMs) {
+        return { op, skip: true };
+      }
+      return { op, skip: false };
+    };
+
+    // Stats are cheap — no batch limit needed (Promise.all over all ops is fine).
+    const diffResults = await Promise.all(ops.map(diffOne));
+    const writeOps = [];
+    for (const { op, skip } of diffResults) {
+      if (skip) {
+        completed += 1;
+        onProgress({ phase: op.kind, current: completed, total, label: path.basename(op.path), skipped: true });
+      } else {
+        writeOps.push(op);
+      }
+    }
+
     // Apply one op (mkdir + write or copy + onProgress).
     // Each op is independent: ops[] is built so writes don't share parent
     // directories that need ordering — mkdir({recursive:true}) is idempotent
@@ -129,17 +208,20 @@ export async function syncTo(targetId, opts = {}) {
       }
       // Counter increment is single-threaded by JS event loop semantics —
       // no torn reads even with 16 ops resolving in any order.
+      // (PERF-17-02: diff filter increments the same counter for skipped ops before
+      // this batch loop runs, so `current` in onProgress reflects total progress.)
       completed += 1;
       onProgress({ phase: op.kind, current: completed, total, label: path.basename(op.path) });
     };
 
+    // PERF-16-01 batched writes — now operating on writeOps (post-diff filter).
     // Sequential batches — within a batch, Promise.all parallelizes writes;
     // between batches, we await to bound max-in-flight at BATCH_SIZE. If any
     // op in a batch rejects, Promise.all rejects on first failure (matches
     // existing behavior — sync.js had no retry logic, so a single fs error
     // already aborted the install).
-    for (let i = 0; i < ops.length; i += BATCH_SIZE) {
-      const slice = ops.slice(i, i + BATCH_SIZE);
+    for (let i = 0; i < writeOps.length; i += BATCH_SIZE) {
+      const slice = writeOps.slice(i, i + BATCH_SIZE);
       await Promise.all(slice.map(applyOp));
     }
   }

package/src/mcp-server/index.js

@@ -1,10 +1,11 @@
-// kit-mcp server — exposes 5 tools, each with action-based dispatch.
+// kit-mcp server — exposes 7 tools, each with action-based dispatch (or none).
 //
-//   kit       action: list-agents | list-commands | list-skills | get | search
-//   sync      action: targets | status | install | remove
-//   gates     action: list | get | for-stage
-//   forensics action: collect | summarize | write-learnings | list-replays | record-replay | load-replay
-//   install   action: targets | install | dry-run                    (registers this MCP into an IDE)
+//   kit              action: list-agents | list-commands | list-skills | get | search
+//   sync             action: targets | status | install | remove
+//   gates            action: list | get | for-stage
+//   forensics        action: collect | summarize | write-learnings | list-replays | record-replay | load-replay
+//   install          action: targets | install | dry-run                    (registers this MCP into an IDE)
+//   metrics-snapshot (parameterless)                                          (OBS-18 four-golden-signals readout)
 //
 // Transport: stdio (MCP standard).
 
@@ -30,6 +31,7 @@ import { recordReplay, listReplays, loadReplay, annotateReplay } from '../core/r
 import { installMcp, listInstallTargets } from './install.js';
 import { ensureSidecar } from '../ui/auto-spawn.js';
 import { wrapProgressForUi } from '../ui/wrapper.js';
+import { incrementInvocation, recordLatency, snapshot as metricsSnapshot } from '../core/metrics.js';
 
 const TOOLS = [
   {
@@ -130,6 +132,17 @@ const TOOLS = [
       required: ['action'],
     },
   },
+  {
+    // OBS-18 (Phase 94.01): expose four-golden-signals data for the MCP server itself.
+    // Read-only (no auth needed beyond the underlying transport): returns counters
+    // keyed `${tool}:${status}` and per-tool latency p50/p95/p99/count.
+    name: 'metrics-snapshot',
+    description: 'Read in-memory golden-signals metrics for this MCP server (counters + latency p50/p95/p99 per tool).',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  },
 ];
 
 // DRIFT-13-03: read version from package.json at module load (NOT inside
@@ -292,13 +305,21 @@ async function handleInstall(args) {
   }
 }
 
+// OBS-18 (Phase 94.01): metrics-snapshot is parameterless and read-only.
+// Returns the live snapshot synchronously — no auth, no projectRoot guard
+// (no disk reads, no shell). Wraps in an async fn for handler-API uniformity.
+async function handleMetricsSnapshot() {
+  return metricsSnapshot();
+}
+
 const HANDLERS = {
-  kit:           handleKit,
-  sync:          handleSync,
-  'reverse-sync':handleReverseSync,
-  gates:         handleGates,
-  forensics:     handleForensics,
-  install:       handleInstall,
+  kit:               handleKit,
+  sync:              handleSync,
+  'reverse-sync':    handleReverseSync,
+  gates:             handleGates,
+  forensics:         handleForensics,
+  install:           handleInstall,
+  'metrics-snapshot': handleMetricsSnapshot,
 };
 
 function slim(x) {
@@ -330,12 +351,30 @@ export async function createServer() {
     const { name, arguments: args } = req.params;
     const handler = HANDLERS[name];
     if (!handler) {
+      // OBS-18 (Phase 94.01): unknown-tool path counts as an error against
+      // the unknown name itself — useful signal if a client is mis-spelling
+      // a tool name in production. No latency observation (handler never ran).
+      incrementInvocation(name || 'unknown', 'error');
       return { content: [{ type: 'text', text: JSON.stringify({ error: `Unknown tool: ${name}` }) }], isError: true };
     }
+    // OBS-18 (Phase 94.01): timestamp the dispatch boundary. The four-golden-signals
+    // skill cares about the *user-facing* latency, which for the MCP server is the
+    // time from request receipt (we are inside the SDK callback) to the JSON envelope
+    // being ready. Date.now() is sub-millisecond-cheap and aligns with the bucket
+    // granularity we report (50/100/250/500ms thresholds in CONTEXT.md).
+    const start = Date.now();
     try {
       const result = await handler(args ?? {});
+      recordLatency(name, Date.now() - start);
+      incrementInvocation(name, 'ok');
       return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
     } catch (e) {
+      // OBS-18: still record latency on the error path — half the value of a
+      // latency histogram is catching tail-latency-then-fail patterns. Status
+      // 'error' covers any thrown exception, including Phase 79.01 gates guard
+      // and the validateProjectRoot rejection (Phase 83.01).
+      recordLatency(name, Date.now() - start);
+      incrementInvocation(name, 'error');
       // SEC-14-06: full stack stays in stderr for operator debug; client envelope is sanitized.
       // sanitizeMcpError redacts secrets/paths from e.message, preserves e.code (Phase 83
       // EMANIFESTMISMATCH invariant), and emits NO stack field.