@klhapp/skillmux 1.7.1 → 1.9.0

package/src/router-core.ts

@@ -1,5 +1,5 @@
 import type { Database } from "bun:sqlite";
-import { existsSync, watch } from "node:fs";
+import { existsSync, lstatSync, watch } from "node:fs";
 import { join } from "node:path";
 import { buildAuditRow } from "./audit";
 import { embeddingDimension, embeddingFingerprint, expandHome, loadConfig } from "./config";
@@ -8,11 +8,15 @@ import {
   deleteSkill,
   findExactMatch,
   ftsSearch,
+  getAuditRowByRequestId,
   getIndexMeta,
   getSkillRow,
   ingestVault,
   insertAudit,
+  insertFetch,
+  openAudit,
   openIndex,
+  pruneAudit,
   replaceSkills,
   setIndexMeta,
   skillCount,
@@ -22,7 +26,7 @@ import {
   upsertVector,
   vectorTopK,
 } from "./db";
-import type { SkillRow } from "./db";
+import type { PruneResult, SkillRow } from "./db";
 import type {
   RankedCandidate,
   RetrievalCapability,
@@ -73,26 +77,45 @@ const defaultClients: Clients = {
 };
 
 let overrides: Overrides = {};
-let env: { config: Config; db: Database } | null = null;
+type Env = { config: Config; db: Database; auditDb: Database };
+
+let envPromise: Promise<Env> | null = null;
+let resolvedEnv: Env | null = null;
+let lastAuditPruneAt: number | null = null;
+
+const AUDIT_PRUNE_INTERVAL_MS = 24 * 60 * 60 * 1000;
 
 /** Replace config/client overrides wholesale (tests, ops). Resets the cached index handle. */
 export function configure(opts: Overrides): void {
   overrides = opts;
-  env = null;
+  envPromise = null;
+  resolvedEnv = null;
+  lastAuditPruneAt = null;
 }
 
-async function getEnv(): Promise<{ config: Config; db: Database }> {
-  if (env) return env;
-  const config = overrides.config ?? (await loadConfig());
-  const db = openIndex(expandHome(config.state_dir));
-  if (skillCount(db) === 0) {
-    const vaultPath = expandHome(config.vault_path);
-    const localVaultPaths = config.local_vault_paths.map(expandHome);
-    ingestVault(db, await scanVaults(vaultPath, localVaultPaths));
-    setIndexMeta(db, "last_indexed_mtime", String(maxVaultMtime(vaultPath, localVaultPaths)));
-  }
-  env = { config, db };
-  return env;
+/**
+ * Memoizes the in-flight promise, not just the resolved value: startup fires
+ * initializeRuntime()'s getRuntime() and pruneAuditIfDue() back-to-back before
+ * either has awaited anything, so caching only the resolved env would let both
+ * open their own index/audit handles and race an ingestVault (AC14 regression).
+ */
+async function getEnv(): Promise<Env> {
+  if (envPromise) return envPromise;
+  envPromise = (async () => {
+    const config = overrides.config ?? (await loadConfig());
+    const stateDir = expandHome(config.state_dir);
+    const db = openIndex(stateDir);
+    const auditDb = openAudit(stateDir);
+    if (skillCount(db) === 0) {
+      const vaultPath = expandHome(config.vault_path);
+      const localVaultPaths = config.local_vault_paths.map(expandHome);
+      ingestVault(db, await scanVaults(vaultPath, localVaultPaths));
+      setIndexMeta(db, "last_indexed_mtime", String(maxVaultMtime(vaultPath, localVaultPaths)));
+    }
+    resolvedEnv = { config, db, auditDb };
+    return resolvedEnv;
+  })();
+  return envPromise;
 }
 
 function getClients(): Clients {
@@ -100,14 +123,21 @@ function getClients(): Clients {
 }
 
 /** Runtime accessor for the eval harness and CLI — not part of the MCP surface. */
-export async function getRuntime(): Promise<{ config: Config; db: Database; clients: Clients }> {
-  const { config, db } = await getEnv();
-  return { config, db, clients: getClients() };
+export async function getRuntime(): Promise<{
+  config: Config;
+  db: Database;
+  auditDb: Database;
+  clients: Clients;
+}> {
+  const { config, db, auditDb } = await getEnv();
+  return { config, db, auditDb, clients: getClients() };
 }
 
 export function closeRuntime(): void {
-  env?.db.close();
-  env = null;
+  resolvedEnv?.db.close();
+  resolvedEnv?.auditDb.close();
+  envPromise = null;
+  resolvedEnv = null;
 }
 
 /**
@@ -131,8 +161,20 @@ async function deliverSkill(db: Database, config: Config, skillId: string): Prom
   let raw = "";
   for (let i = 0; i < candidates.length; i++) {
     const candidate = candidates[i]!;
-    const file = Bun.file(join(candidate, skillId, "SKILL.md"));
+    const skillDir = join(candidate, skillId);
+    const path = join(skillDir, "SKILL.md");
+    const file = Bun.file(path);
     if (!(await file.exists())) continue;
+    // A symlinked SKILL.md must never be read here: this is the direct "zero-loss
+    // delivery" read path that bypasses the index and readSkill's own symlink guard
+    // (vault.ts), and its `body` is served straight into the agent's context.
+    //
+    // The skill directory itself must be checked too, separately from SKILL.md's
+    // leaf check above: `lstat` only refuses to follow the *final* path component,
+    // so a symlinked skill directory (e.g. a tampered local_vault_paths override)
+    // containing a real, non-symlink SKILL.md at its target silently passes the
+    // leaf check while still resolving straight through to arbitrary host content.
+    if (lstatSync(skillDir).isSymbolicLink() || lstatSync(path).isSymbolicLink()) continue;
     const candidateBytes = await file.bytes();
     const candidateRaw = decodeUtf8Strict(candidateBytes);
     if (i < candidates.length - 1) {
@@ -365,7 +407,7 @@ export async function startVaultWatcher(): Promise<() => void> {
 
 export async function resolveSkill(input: ResolveSkillInput): Promise<ResolveResult> {
   const t0 = performance.now();
-  const { config, db } = await getEnv();
+  const { config, db, auditDb } = await getEnv();
   await syncVaultIfNeeded();
 
   if (input.top_k !== undefined) {
@@ -392,7 +434,10 @@ export async function resolveSkill(input: ResolveSkillInput): Promise<ResolveRes
       score: c.score,
     }));
 
+  const requestId = crypto.randomUUID();
+
   const result: ResolveResult = {
+    request_id: requestId,
     retrieval,
     ...(retrievalResult.degraded_from
       ? {
@@ -404,10 +449,11 @@ export async function resolveSkill(input: ResolveSkillInput): Promise<ResolveRes
   };
 
   insertAudit(
-    db,
+    auditDb,
     buildAuditRow({
       id: 0, // assigned by SQLite
       ts: new Date().toISOString(),
+      request_id: requestId,
       query: input.query,
       retrieval,
       degraded_from: retrievalResult.degraded_from ?? null,
@@ -592,11 +638,48 @@ export async function retrieveAndRerank(
   };
 }
 
+/**
+ * AC14: runs at most once per 24 hours per process. Callers must not await
+ * this on the startup or resolve path -- it is meant to be fired and left to
+ * resolve in the background so it never blocks readiness or a resolve.
+ */
+export async function pruneAuditIfDue(now: Date = new Date()): Promise<PruneResult | null> {
+  const { config, auditDb } = await getEnv();
+  const retentionDays = config.audit?.retention_days ?? 90;
+  if (retentionDays <= 0) return null;
+  if (lastAuditPruneAt !== null && now.getTime() - lastAuditPruneAt < AUDIT_PRUNE_INTERVAL_MS) {
+    return null;
+  }
+  lastAuditPruneAt = now.getTime();
+  return pruneAudit(auditDb, retentionDays, now);
+}
+
 export async function fetchSkill(input: FetchSkillInput): Promise<FetchSkillResult> {
-  const { config, db } = await getEnv();
+  const { config, db, auditDb } = await getEnv();
   await syncVaultIfNeeded();
   if (getSkillRow(db, input.skill_id) === null) {
     throw new Error(`SKILL_NOT_FOUND: no skill '${input.skill_id}' in the index`);
   }
-  return deliverSkill(db, config, input.skill_id);
+  const result = await deliverSkill(db, config, input.skill_id);
+
+  let resolveAuditId: number | null = null;
+  let rankAtResolve: number | null = null;
+  if (input.request_id) {
+    const resolveRow = getAuditRowByRequestId(auditDb, input.request_id);
+    if (resolveRow) {
+      resolveAuditId = resolveRow.id;
+      const index = resolveRow.candidates.findIndex((c) => c.skill_id === input.skill_id);
+      rankAtResolve = index === -1 ? null : index + 1;
+    }
+  }
+
+  insertFetch(auditDb, {
+    ts: new Date().toISOString(),
+    skill_id: input.skill_id,
+    request_id: input.request_id ?? null,
+    resolve_audit_id: resolveAuditId,
+    rank_at_resolve: rankAtResolve,
+  });
+
+  return result;
 }

package/src/scan.ts

@@ -1,4 +1,4 @@
-import { existsSync } from "node:fs";
+import { existsSync, lstatSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { decodeUtf8Strict, listSupportingFiles, scanVault } from "./vault";
 
@@ -162,8 +162,14 @@ interface ScanContentTarget {
   content: string;
 }
 
+/** Refuses (returns null for) a symlinked path instead of following it — every
+ *  caller feeds vault content into scan findings, so a symlink swapped in after
+ *  an earlier symlink-filtering pass (e.g. listSupportingFiles' walk, which runs
+ *  before this read, not at it) must still be caught right here, not trusted to
+ *  have stayed excluded. Same defense-in-depth pattern as readSkill/hashSkillContent. */
 export async function readTextFileOrNull(path: string): Promise<string | null> {
   try {
+    if (lstatSync(path).isSymbolicLink()) return null;
     const bytes = await Bun.file(path).bytes();
     return decodeUtf8Strict(bytes);
   } catch {

package/src/server.ts

@@ -12,6 +12,7 @@ import {
   backfillEmbeddings,
   configure,
   fetchSkill,
+  pruneAuditIfDue,
   resolveSkill,
 } from "./router-core";
 import { closeRuntime, getRuntime, startVaultWatcher } from "./router-core";
@@ -113,12 +114,16 @@ export function createMcpServer(): McpServer {
     {
       description:
         "Fetch a skill's SKILL.md verbatim by skill_id, with sha256 and supporting-file paths. " +
-        "Independent of any prior resolve_skill outcome.",
-      inputSchema: { skill_id: z.string().regex(SKILL_ID_PATTERN) },
+        "Independent of any prior resolve_skill outcome. Pass the request_id from a prior " +
+        "resolve_skill call to link this fetch to it for quality measurement.",
+      inputSchema: {
+        skill_id: z.string().regex(SKILL_ID_PATTERN),
+        request_id: z.string().min(1).max(128).optional(),
+      },
     },
-    async ({ skill_id }) => {
+    async ({ skill_id, request_id }) => {
       try {
-        const result = await fetchSkill({ skill_id });
+        const result = await fetchSkill({ skill_id, request_id });
         const { body, ...meta } = result;
         return {
           content: [{ type: "text" as const, text: body }],
@@ -175,6 +180,14 @@ export async function startServer(opts?: {
     .then(() => metricsRegistry.setReadiness(readinessState.get()))
     .catch((err) => console.error("skillmux runtime init error:", err));
 
+  // AC14: fire-and-forget so this never delays readiness or blocks a resolve;
+  // not chained onto initPromise, which is awaited below for HTTP transport.
+  const runAuditPrune = () =>
+    pruneAuditIfDue().catch((err) => console.error("skillmux audit prune error:", err));
+  runAuditPrune();
+  const auditPruneInterval = setInterval(runAuditPrune, 24 * 60 * 60 * 1000);
+  auditPruneInterval.unref();
+
   const server = createMcpServer();
 
   const transportType = opts?.transport ?? "stdio";
@@ -345,13 +358,13 @@ export async function startServer(opts?: {
               { status: 400, headers: { "Content-Type": "application/json" } },
             );
           }
-          const { db } = await getRuntime();
+          const { auditDb } = await getRuntime();
           const headers = new Headers({ "Content-Type": "application/json" });
           if (allowOriginHeader)
             headers.set("Access-Control-Allow-Origin", allowOriginHeader);
           for (const [key, value] of Object.entries(rateLimitResult.headers))
             headers.set(key, value);
-          return new Response(JSON.stringify(getStats(db, since)), {
+          return new Response(JSON.stringify(getStats(auditDb, since)), {
             status: 200,
             headers,
           });
@@ -521,6 +534,7 @@ export async function startServer(opts?: {
       async stop() {
         if (stopped) return;
         stopped = true;
+        clearInterval(auditPruneInterval);
         readinessState.set({ ...readinessState.get(), status: "stopping" });
         metricsRegistry.setReadiness(readinessState.get());
         bunServer.stop(true);
@@ -540,6 +554,7 @@ export async function startServer(opts?: {
       async stop() {
         if (stopped) return;
         stopped = true;
+        clearInterval(auditPruneInterval);
         readinessState.set({ ...readinessState.get(), status: "stopping" });
         metricsRegistry.setReadiness(readinessState.get());
         configWatcher?.stop();

package/src/stats.ts

@@ -1,5 +1,5 @@
 import type { Database } from "bun:sqlite";
-import type { AuditCandidate, AuditRow } from "./types";
+import type { AuditCandidate, AuditRow, FetchAuditRow } from "./types";
 
 export const SINCE_PATTERN = /^(\d+[hdwmy]|\d{4}-\d{2}-\d{2}([T ].+)?)$/;
 
@@ -20,6 +20,18 @@ export interface RetrievalTotals {
   lexical: number;
 }
 
+export type AcceptanceSignal =
+  | { available: false; uncorrelated_fetch_count: number }
+  | {
+      available: true;
+      resolves_with_candidates: number;
+      accepted_count: number;
+      acceptance_rate: number;
+      observed_mrr: number;
+      top1_acceptance_rate: number;
+      uncorrelated_fetch_count: number;
+    };
+
 export interface StatsResponse {
   since: string;
   until: string;
@@ -31,6 +43,8 @@ export interface StatsResponse {
   average_latency_ms: number;
   skills: SkillStat[];
   top_empty_shortlist_queries: EmptyShortlistQuery[];
+  acceptance: AcceptanceSignal;
+  top_unused_shortlist_queries: EmptyShortlistQuery[];
 }
 
 const RELATIVE_WINDOW = /^(\d+)([hdwmy])$/;
@@ -63,10 +77,16 @@ function compareCodeUnits(a: string, b: string): number {
   return 0;
 }
 
-export function computeStats(rows: AuditRow[], since: Date, until: Date): StatsResponse {
+export function computeStats(
+  rows: AuditRow[],
+  since: Date,
+  until: Date,
+  fetchRows: FetchAuditRow[] = [],
+): StatsResponse {
   const retrieval_totals: RetrievalTotals = { exact: 0, reranked: 0, hybrid: 0, lexical: 0 };
   const skillCounts = new Map<string, number>();
   const emptyShortlistCounts = new Map<string, number>();
+  const resolvesWithCandidates = new Map<number, AuditRow>();
   let empty_shortlist_count = 0;
   let degraded_count = 0;
   let total_latency_ms = 0;
@@ -86,6 +106,7 @@ export function computeStats(rows: AuditRow[], since: Date, until: Date): StatsR
       empty_shortlist_count++;
       emptyShortlistCounts.set(row.query, (emptyShortlistCounts.get(row.query) ?? 0) + 1);
     } else {
+      resolvesWithCandidates.set(row.id, row);
       const seenInRow = new Set<string>();
       for (const candidate of row.candidates) {
         if (!candidate.skill_id) continue;
@@ -96,6 +117,52 @@ export function computeStats(rows: AuditRow[], since: Date, until: Date): StatsR
     }
   }
 
+  let uncorrelated_fetch_count = 0;
+  const firstFetchByResolve = new Map<number, FetchAuditRow>();
+  for (const fetch of fetchRows) {
+    if (fetch.resolve_audit_id === null) {
+      uncorrelated_fetch_count++;
+      continue;
+    }
+    if (!resolvesWithCandidates.has(fetch.resolve_audit_id)) continue;
+    const existing = firstFetchByResolve.get(fetch.resolve_audit_id);
+    if (!existing || fetch.ts < existing.ts) {
+      firstFetchByResolve.set(fetch.resolve_audit_id, fetch);
+    }
+  }
+
+  const acceptedResolveIds = new Set(firstFetchByResolve.keys());
+  const accepted_count = acceptedResolveIds.size;
+  const acceptance: AcceptanceSignal =
+    accepted_count > 0
+      ? (() => {
+          let reciprocalRankSum = 0;
+          let top1Count = 0;
+          for (const fetch of firstFetchByResolve.values()) {
+            const rank = fetch.rank_at_resolve;
+            if (rank !== null) {
+              reciprocalRankSum += 1 / rank;
+              if (rank === 1) top1Count++;
+            }
+          }
+          return {
+            available: true as const,
+            resolves_with_candidates: resolvesWithCandidates.size,
+            accepted_count,
+            acceptance_rate: accepted_count / resolvesWithCandidates.size,
+            observed_mrr: reciprocalRankSum / accepted_count,
+            top1_acceptance_rate: top1Count / accepted_count,
+            uncorrelated_fetch_count,
+          };
+        })()
+      : { available: false as const, uncorrelated_fetch_count };
+
+  const unusedShortlistCounts = new Map<string, number>();
+  for (const [id, row] of resolvesWithCandidates) {
+    if (acceptedResolveIds.has(id)) continue;
+    unusedShortlistCounts.set(row.query, (unusedShortlistCounts.get(row.query) ?? 0) + 1);
+  }
+
   const total_requests = rows.length;
   const empty_shortlist_rate = total_requests > 0 ? empty_shortlist_count / total_requests : 0;
   const average_latency_ms = total_requests > 0 ? total_latency_ms / total_requests : 0;
@@ -109,15 +176,8 @@ export function computeStats(rows: AuditRow[], since: Date, until: Date): StatsR
       return compareCodeUnits(a.skill_id, b.skill_id);
     });
 
-  const top_empty_shortlist_queries: EmptyShortlistQuery[] = [...emptyShortlistCounts.entries()]
-    .map(([query, count]) => ({ query, count }))
-    .sort((a, b) => {
-      if (b.count !== a.count) {
-        return b.count - a.count;
-      }
-      return compareCodeUnits(a.query, b.query);
-    })
-    .slice(0, 20);
+  const top_empty_shortlist_queries = topQueryCounts(emptyShortlistCounts);
+  const top_unused_shortlist_queries = topQueryCounts(unusedShortlistCounts);
 
   return {
     since: since.toISOString(),
@@ -130,12 +190,27 @@ export function computeStats(rows: AuditRow[], since: Date, until: Date): StatsR
     average_latency_ms,
     skills,
     top_empty_shortlist_queries,
+    acceptance,
+    top_unused_shortlist_queries,
   };
 }
 
+function topQueryCounts(counts: Map<string, number>): EmptyShortlistQuery[] {
+  return [...counts.entries()]
+    .map(([query, count]) => ({ query, count }))
+    .sort((a, b) => {
+      if (b.count !== a.count) {
+        return b.count - a.count;
+      }
+      return compareCodeUnits(a.query, b.query);
+    })
+    .slice(0, 20);
+}
+
 interface AuditTableRow {
   id: number;
   ts: string;
+  request_id: string | null;
   query: string;
   retrieval: AuditRow["retrieval"];
   degraded_from: string | null;
@@ -147,7 +222,7 @@ interface AuditTableRow {
 export function queryAuditRows(db: Database, sinceIso: string): AuditRow[] {
   const rows = db
     .query(
-      "SELECT id, ts, query, retrieval, degraded_from, degradation_reason, candidates, latency_ms FROM audit WHERE ts >= ? ORDER BY ts ASC",
+      "SELECT id, ts, request_id, query, retrieval, degraded_from, degradation_reason, candidates, latency_ms FROM audit WHERE ts >= ? ORDER BY ts ASC",
     )
     .all(sinceIso) as AuditTableRow[];
 
@@ -178,6 +253,7 @@ export function queryAuditRows(db: Database, sinceIso: string): AuditRow[] {
     const result: AuditRow = {
       id: row.id,
       ts: row.ts,
+      request_id: row.request_id,
       query: row.query,
       retrieval: row.retrieval,
       candidates,
@@ -193,10 +269,19 @@ export function queryAuditRows(db: Database, sinceIso: string): AuditRow[] {
   });
 }
 
+export function queryFetchRows(db: Database, sinceIso: string): FetchAuditRow[] {
+  return db
+    .query(
+      "SELECT id, ts, skill_id, request_id, resolve_audit_id, rank_at_resolve FROM fetch WHERE ts >= ? ORDER BY ts ASC",
+    )
+    .all(sinceIso) as FetchAuditRow[];
+}
+
 export function getStats(db: Database, since: string, now: Date = new Date()): StatsResponse {
   const sinceDate = parseSince(since, now);
   const rows = queryAuditRows(db, sinceDate.toISOString());
-  return computeStats(rows, sinceDate, now);
+  const fetchRows = queryFetchRows(db, sinceDate.toISOString());
+  return computeStats(rows, sinceDate, now, fetchRows);
 }
 
 export function renderStatsText(stats: StatsResponse): string {
@@ -230,5 +315,26 @@ export function renderStatsText(stats: StatsResponse): string {
     }
   }
 
+  if (stats.acceptance.available) {
+    lines.push(
+      `acceptance: acceptance_rate=${stats.acceptance.acceptance_rate.toFixed(3)} ` +
+        `observed_mrr=${stats.acceptance.observed_mrr.toFixed(3)} ` +
+        `top1_acceptance_rate=${stats.acceptance.top1_acceptance_rate.toFixed(3)} ` +
+        `(accepted=${stats.acceptance.accepted_count}/${stats.acceptance.resolves_with_candidates}, ` +
+        `uncorrelated_fetch_count=${stats.acceptance.uncorrelated_fetch_count})`,
+    );
+  } else {
+    lines.push(`acceptance: unavailable (uncorrelated_fetch_count=${stats.acceptance.uncorrelated_fetch_count})`);
+  }
+
+  lines.push("top unused shortlist queries:");
+  if (stats.top_unused_shortlist_queries.length === 0) {
+    lines.push("  (none)");
+  } else {
+    for (const entry of stats.top_unused_shortlist_queries) {
+      lines.push(`  "${entry.query}" (${entry.count})`);
+    }
+  }
+
   return lines.join("\n");
 }

package/src/sync.ts

@@ -1,6 +1,7 @@
 import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, relative } from "node:path";
+import { findSymlinks } from "./install";
 import { resolveSkillRoot } from "./vault";
 
 export const SKILLMUX_MARKER_FILENAME = ".skillmux";
@@ -101,25 +102,47 @@ export interface SyncTargetParams {
 export interface SyncTargetResult {
   added: string[];
   removed: string[];
+  /** Core skills whose directory contains an internal symlink and were refused —
+   *  syncTarget symlinks the whole skill directory into the target, so an internal
+   *  symlink would otherwise be exposed to the agent regardless of how it got into
+   *  the vault (install/update already reject them, but a shared git-backed vault
+   *  can still be tampered with directly). */
+  skipped: string[];
 }
 
 export interface SyncTargetOptions {
   dryRun?: boolean;
 }
 
+/** Splits `skillIds` into those safe to symlink into a target and those refused
+ *  for containing an internal symlink (see SyncTargetResult.skipped). */
+function partitionSyncable(
+  skillIds: string[],
+  skillSource: (skillId: string) => string,
+): { syncable: string[]; skipped: string[] } {
+  const syncable: string[] = [];
+  const skipped: string[] = [];
+  for (const skillId of skillIds) {
+    if (findSymlinks(join(skillSource(skillId), skillId)).length > 0) skipped.push(skillId);
+    else syncable.push(skillId);
+  }
+  return { syncable, skipped };
+}
+
 export function syncTarget(params: SyncTargetParams, options: SyncTargetOptions = {}): SyncTargetResult {
   const { vaultPath, targetDir, targetName, coreSkillIds, localVaultPaths = [] } = params;
   const { dryRun = false } = options;
   const skillSource = (skillId: string) => resolveSkillRoot(skillId, vaultPath, localVaultPaths) ?? vaultPath;
 
   if (!existsSync(targetDir)) {
-    if (dryRun) return { added: [...coreSkillIds], removed: [] };
+    const { syncable, skipped } = partitionSyncable(coreSkillIds, skillSource);
+    if (dryRun) return { added: syncable, removed: [], skipped };
     mkdirSync(targetDir, { recursive: true });
-    for (const skillId of coreSkillIds) {
+    for (const skillId of syncable) {
       symlinkSync(join(skillSource(skillId), skillId), join(targetDir, skillId));
     }
-    writeTargetMarker(targetDir, targetName, vaultPath, coreSkillIds);
-    return { added: [...coreSkillIds], removed: [] };
+    writeTargetMarker(targetDir, targetName, vaultPath, syncable);
+    return { added: syncable, removed: [], skipped };
   }
 
   let marker = readSkillmuxMarker(targetDir);
@@ -167,14 +190,21 @@ export function syncTarget(params: SyncTargetParams, options: SyncTargetOptions
   }
 
   const removed = [...managedEntries].filter((name) => existing.includes(name) && !desired.has(name));
-  const added = coreSkillIds.filter((skillId) => !existing.includes(skillId));
-  if (dryRun) return { added, removed };
+  const addedCandidates = coreSkillIds.filter((skillId) => !existing.includes(skillId));
+  const { syncable: added, skipped } = partitionSyncable(addedCandidates, skillSource);
+  if (dryRun) return { added, removed, skipped };
 
   for (const name of removed) unlinkSync(join(targetDir, name));
   for (const skillId of added) symlinkSync(join(skillSource(skillId), skillId), join(targetDir, skillId));
-  writeTargetMarker(targetDir, targetName, vaultPath, coreSkillIds, marker.created_at);
+  writeTargetMarker(
+    targetDir,
+    targetName,
+    vaultPath,
+    coreSkillIds.filter((skillId) => !skipped.includes(skillId)),
+    marker.created_at,
+  );
 
-  return { added, removed };
+  return { added, removed, skipped };
 }
 
 export interface AdoptTargetResult {

package/src/types.ts

@@ -107,6 +107,11 @@ export interface ConfigPolicy {
   environment_overrides?: boolean;
 }
 
+export interface AuditConfig {
+  /** Age in days beyond which audit rows are pruned. 0 disables pruning. */
+  retention_days: number;
+}
+
 export interface Config {
   config?: ConfigPolicy;
   vault_path: string;
@@ -116,6 +121,7 @@ export interface Config {
   output: OutputConfig;
   inference: InferenceConfig;
   server?: ServerConfig;
+  audit?: AuditConfig;
 }
 
 export interface RankedCandidate {
@@ -136,6 +142,7 @@ export type DegradationReason =
   | "reranker_protocol_error";
 
 export interface ResolveResult {
+  request_id: string;
   retrieval: RetrievalCapability;
   degraded_from?: "reranked" | "hybrid";
   degradation_reason?: DegradationReason;
@@ -151,6 +158,7 @@ export interface ResolveSkillInput {
 
 export interface FetchSkillInput {
   skill_id: string;
+  request_id?: string;
 }
 
 export interface FetchSkillResult {
@@ -169,6 +177,8 @@ export interface AuditCandidate {
 export interface AuditRow {
   id: number;
   ts: string;
+  /** Null for rows written before request_id existed (AC4). */
+  request_id: string | null;
   query: string;
   retrieval: RetrievalCapability;
   degraded_from?: "reranked" | "hybrid" | null;
@@ -177,6 +187,18 @@ export interface AuditRow {
   latency_ms: number;
 }
 
+export interface FetchAuditRow {
+  id: number;
+  ts: string;
+  skill_id: string;
+  /** Exactly as supplied by the caller, including an unknown value. Null when the caller sent none. */
+  request_id: string | null;
+  /** Null when the fetch is uncorrelated: no request_id, an unknown/malformed one, or a pruned resolve row. */
+  resolve_audit_id: number | null;
+  /** Rank of skill_id in the correlated resolve's shortlist. Null when uncorrelated or absent from the shortlist. */
+  rank_at_resolve: number | null;
+}
+
 export interface Clients {
   embed(texts: string[]): Promise<Float32Array[]>;
   rerank?: (query: string, docs: { skill_id: string; text: string }[]) => Promise<number[]>;