@klhapp/skillmux 1.7.1 → 1.9.0

package/src/db.ts

@@ -1,5 +1,5 @@
 import { Database } from "bun:sqlite";
-import { mkdirSync } from "node:fs";
+import { existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import type { AuditCandidate, AuditRow } from "./types";
 import type { VaultSkill } from "./vault";
@@ -12,6 +12,81 @@ export interface SkillRow {
   content_sha256: string;
 }
 
+export function openAudit(stateDir: string): Database {
+  mkdirSync(stateDir, { recursive: true });
+  const db = new Database(join(stateDir, "audit.sqlite3"), { create: true });
+  // auto_vacuum only takes on an empty database, so it must precede both the
+  // journal-mode switch and any CREATE TABLE. It is what lets a retention
+  // prune reclaim space without a full VACUUM.
+  db.run("PRAGMA auto_vacuum = INCREMENTAL");
+  db.run("PRAGMA journal_mode = WAL");
+  db.run("PRAGMA busy_timeout = 2000");
+  db.run(`CREATE TABLE IF NOT EXISTS audit (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    ts TEXT NOT NULL,
+    request_id TEXT,
+    query TEXT NOT NULL,
+    retrieval TEXT NOT NULL DEFAULT 'lexical',
+    degraded_from TEXT,
+    degradation_reason TEXT,
+    candidates TEXT NOT NULL,
+    latency_ms INTEGER NOT NULL
+  )`);
+  // CREATE TABLE IF NOT EXISTS no-ops on a table opened from before request_id
+  // existed (AC4), so add it explicitly when missing.
+  const auditColumns = new Set(
+    (db.query("PRAGMA table_info(audit)").all() as { name: string }[]).map((c) => c.name),
+  );
+  if (!auditColumns.has("request_id")) {
+    db.run("ALTER TABLE audit ADD COLUMN request_id TEXT");
+  }
+  db.run(`CREATE TABLE IF NOT EXISTS fetch (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    ts TEXT NOT NULL,
+    skill_id TEXT NOT NULL,
+    request_id TEXT,
+    resolve_audit_id INTEGER,
+    rank_at_resolve INTEGER
+  )`);
+  adoptAuditFromIndex(db, stateDir);
+  return db;
+}
+
+// Audit rows used to live in index.sqlite3. Move any that remain there into the
+// audit store, then drop the old table so the index carries no user queries.
+function adoptAuditFromIndex(db: Database, stateDir: string): void {
+  const indexPath = join(stateDir, "index.sqlite3");
+  if (!existsSync(indexPath)) return;
+
+  db.run("ATTACH DATABASE ? AS legacy", [indexPath]);
+  try {
+    const legacyAudit = db
+      .query("SELECT name FROM legacy.sqlite_master WHERE type = 'table' AND name = 'audit'")
+      .get();
+    if (!legacyAudit) return;
+
+    // Older audit tables predate the retrieval columns and carry outcome /
+    // degraded / selected_skill_id instead. Select what is actually there and
+    // let the canonical defaults stand in for the rest.
+    const legacyColumns = new Set(
+      (db.query("PRAGMA legacy.table_info(audit)").all() as { name: string }[]).map((c) => c.name),
+    );
+    const retrieval = legacyColumns.has("retrieval") ? "COALESCE(retrieval, 'lexical')" : "'lexical'";
+    const degradedFrom = legacyColumns.has("degraded_from") ? "degraded_from" : "NULL";
+    const degradationReason = legacyColumns.has("degradation_reason") ? "degradation_reason" : "NULL";
+
+    // SQLite commits atomically across attached databases, so the copy and the
+    // drop either both land or neither does.
+    db.transaction(() => {
+      db.run(`INSERT INTO audit (ts, query, retrieval, degraded_from, degradation_reason, candidates, latency_ms)
+        SELECT ts, query, ${retrieval}, ${degradedFrom}, ${degradationReason}, candidates, latency_ms FROM legacy.audit`);
+      db.run("DROP TABLE legacy.audit");
+    })();
+  } finally {
+    db.run("DETACH DATABASE legacy");
+  }
+}
+
 export function openIndex(stateDir: string): Database {
   mkdirSync(stateDir, { recursive: true });
   const db = new Database(join(stateDir, "index.sqlite3"), { create: true });
@@ -39,48 +114,7 @@ export function openIndex(stateDir: string): Database {
   if (!vectorColumns.some((column) => column.name === "embedding_fingerprint")) {
     db.run("ALTER TABLE vectors ADD COLUMN embedding_fingerprint TEXT NOT NULL DEFAULT ''");
   }
-  db.run(`CREATE TABLE IF NOT EXISTS audit (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    ts TEXT NOT NULL,
-    query TEXT NOT NULL,
-    retrieval TEXT NOT NULL DEFAULT 'lexical',
-    degraded_from TEXT,
-    degradation_reason TEXT,
-    candidates TEXT NOT NULL,
-    latency_ms INTEGER NOT NULL
-  )`);
-  const auditColumns = db.query("PRAGMA table_info(audit)").all() as { name: string }[];
-  const columnNames = new Set(auditColumns.map((column) => column.name));
-  const hasLegacyColumns =
-    columnNames.has("outcome") ||
-    columnNames.has("selected_skill_id") ||
-    columnNames.has("degraded");
-  const missingCanonicalColumns =
-    !columnNames.has("retrieval") ||
-    !columnNames.has("degraded_from") ||
-    !columnNames.has("degradation_reason");
-
-  if (hasLegacyColumns || missingCanonicalColumns) {
-    db.transaction(() => {
-      db.run(`CREATE TABLE audit_new (
-        id INTEGER PRIMARY KEY AUTOINCREMENT,
-        ts TEXT NOT NULL,
-        query TEXT NOT NULL,
-        retrieval TEXT NOT NULL DEFAULT 'lexical',
-        degraded_from TEXT,
-        degradation_reason TEXT,
-        candidates TEXT NOT NULL,
-        latency_ms INTEGER NOT NULL
-      )`);
-      const retrievalExpr = columnNames.has("retrieval") ? "COALESCE(retrieval, 'lexical')" : "'lexical'";
-      const degradedFromExpr = columnNames.has("degraded_from") ? "degraded_from" : "NULL";
-      const degradationReasonExpr = columnNames.has("degradation_reason") ? "degradation_reason" : "NULL";
-      db.run(`INSERT INTO audit_new (id, ts, query, retrieval, degraded_from, degradation_reason, candidates, latency_ms)
-        SELECT id, ts, query, ${retrievalExpr}, ${degradedFromExpr}, ${degradationReasonExpr}, candidates, latency_ms FROM audit`);
-      db.run("DROP TABLE audit");
-      db.run("ALTER TABLE audit_new RENAME TO audit");
-    })();
-  }
+  // Audit rows live in audit.sqlite3; openAudit adopts any left here.
   db.run(`CREATE TABLE IF NOT EXISTS index_meta (
     key TEXT PRIMARY KEY,
     value TEXT NOT NULL
@@ -281,6 +315,7 @@ export function vectorTopK(db: Database, query: Float32Array, k: number): SkillR
 
 export interface AuditInsert {
   ts: string;
+  request_id?: string | null;
   query: string;
   retrieval: AuditRow["retrieval"];
   degraded_from?: string | null;
@@ -291,10 +326,11 @@ export interface AuditInsert {
 
 export function insertAudit(db: Database, row: AuditInsert): void {
   db.run(
-    `INSERT INTO audit (ts, query, retrieval, degraded_from, degradation_reason, candidates, latency_ms)
-     VALUES (?, ?, ?, ?, ?, ?, ?)`,
+    `INSERT INTO audit (ts, request_id, query, retrieval, degraded_from, degradation_reason, candidates, latency_ms)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
     [
       row.ts,
+      row.request_id ?? null,
       row.query,
       row.retrieval,
       row.degraded_from ?? null,
@@ -304,3 +340,74 @@ export function insertAudit(db: Database, row: AuditInsert): void {
     ],
   );
 }
+
+/**
+ * Correlation lookup for AC5/AC7: looks up the resolve that produced
+ * `requestId`, or null when it names no known resolve (including malformed
+ * input, which is never validated at the boundary per AC7).
+ */
+export function getAuditRowByRequestId(
+  db: Database,
+  requestId: string,
+): { id: number; candidates: AuditCandidate[] } | null {
+  const row = db
+    .query("SELECT id, candidates FROM audit WHERE request_id = ?")
+    .get(requestId) as { id: number; candidates: string } | null;
+  if (!row) return null;
+  return { id: row.id, candidates: JSON.parse(row.candidates) as AuditCandidate[] };
+}
+
+export interface FetchInsert {
+  ts: string;
+  skill_id: string;
+  request_id?: string | null;
+  resolve_audit_id?: number | null;
+  rank_at_resolve?: number | null;
+}
+
+export function insertFetch(db: Database, row: FetchInsert): void {
+  db.run(
+    `INSERT INTO fetch (ts, skill_id, request_id, resolve_audit_id, rank_at_resolve)
+     VALUES (?, ?, ?, ?, ?)`,
+    [
+      row.ts,
+      row.skill_id,
+      row.request_id ?? null,
+      row.resolve_audit_id ?? null,
+      row.rank_at_resolve ?? null,
+    ],
+  );
+}
+
+export interface PruneResult {
+  audit_deleted: number;
+  fetch_deleted: number;
+}
+
+/**
+ * Deletes resolve and fetch rows with ts before `cutoffIso`, each by its own
+ * timestamp; no FK ties them, so a fetch outliving its resolve row simply
+ * reads back uncorrelated (AC7's existing null path). Reclaims the freed
+ * pages with an incremental vacuum, which only touches audit.sqlite3 (AC16).
+ */
+export function pruneAuditBefore(db: Database, cutoffIso: string): PruneResult {
+  const auditResult = db.run("DELETE FROM audit WHERE ts < ?", [cutoffIso]);
+  const fetchResult = db.run("DELETE FROM fetch WHERE ts < ?", [cutoffIso]);
+  db.run("PRAGMA incremental_vacuum");
+
+  return { audit_deleted: auditResult.changes, fetch_deleted: fetchResult.changes };
+}
+
+/** AC12: retentionDays <= 0 disables pruning entirely. */
+export function pruneAudit(db: Database, retentionDays: number, now: Date = new Date()): PruneResult {
+  if (retentionDays <= 0) return { audit_deleted: 0, fetch_deleted: 0 };
+  const cutoff = new Date(now.getTime() - retentionDays * 86_400_000).toISOString();
+  return pruneAuditBefore(db, cutoff);
+}
+
+/** Dry-run counterpart of pruneAuditBefore: counts without deleting (AC15). */
+export function countPrunable(db: Database, cutoffIso: string): PruneResult {
+  const auditRow = db.query("SELECT count(*) AS n FROM audit WHERE ts < ?").get(cutoffIso) as { n: number };
+  const fetchRow = db.query("SELECT count(*) AS n FROM fetch WHERE ts < ?").get(cutoffIso) as { n: number };
+  return { audit_deleted: auditRow.n, fetch_deleted: fetchRow.n };
+}

package/src/eval.ts

@@ -1,3 +1,4 @@
+import type { Database } from "bun:sqlite";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import {
@@ -58,6 +59,74 @@ export function parseEvalCases(raw: unknown): EvalCase[] {
   return result;
 }
 
+/** AC17: dedup key for promoted cases. Collapses whitespace and case differences that are not meaningfully distinct queries. */
+export function normalizeQuery(query: string): string {
+  return query.trim().replace(/\s+/g, " ").toLowerCase();
+}
+
+export interface ObservedFetch {
+  query: string;
+  skill_id: string;
+}
+
+/** AC17: groups fetched skill ids by normalized query into observed-split eval cases. */
+export function buildPromotedCases(fetches: ObservedFetch[]): EvalCase[] {
+  const byQuery = new Map<string, { query: string; skillIds: string[]; seen: Set<string> }>();
+  for (const fetch of fetches) {
+    const key = normalizeQuery(fetch.query);
+    if (!key) continue;
+    let entry = byQuery.get(key);
+    if (!entry) {
+      entry = { query: fetch.query, skillIds: [], seen: new Set() };
+      byQuery.set(key, entry);
+    }
+    if (!entry.seen.has(fetch.skill_id)) {
+      entry.seen.add(fetch.skill_id);
+      entry.skillIds.push(fetch.skill_id);
+    }
+  }
+  return [...byQuery.values()].map((entry) => ({
+    query: entry.query,
+    split: "observed",
+    relevant_skill_ids: entry.skillIds,
+  }));
+}
+
+/** AC18: never rewrites a case whose normalized query already exists in the target file. */
+export function excludeExistingCases(
+  cases: EvalCase[],
+  existing: EvalCase[],
+): { cases: EvalCase[]; skipped: number } {
+  const existingKeys = new Set(existing.map((c) => normalizeQuery(c.query)));
+  const kept: EvalCase[] = [];
+  let skipped = 0;
+  for (const c of cases) {
+    if (existingKeys.has(normalizeQuery(c.query))) {
+      skipped++;
+    } else {
+      kept.push(c);
+    }
+  }
+  return { cases: kept, skipped };
+}
+
+/**
+ * AC17: joins fetches to the resolve that produced them for promotion. Only
+ * correlated fetches (a known resolve_audit_id) carry a query to promote;
+ * uncorrelated fetches have no resolve to join against and are excluded.
+ */
+export function queryPromotableFetches(db: Database, sinceIso: string): ObservedFetch[] {
+  return db
+    .query(
+      `SELECT audit.query AS query, fetch.skill_id AS skill_id
+       FROM fetch
+       JOIN audit ON fetch.resolve_audit_id = audit.id
+       WHERE fetch.ts >= ?
+       ORDER BY fetch.ts ASC`,
+    )
+    .all(sinceIso) as ObservedFetch[];
+}
+
 export interface EvalMetrics {
   recall_at_5: number;
   recall_at_10: number;

package/src/install.ts

@@ -1,6 +1,6 @@
-import { cpSync, existsSync, mkdtempSync, readdirSync, rmSync } from "node:fs";
+import { cpSync, existsSync, lstatSync, mkdtempSync, readdirSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { basename, dirname, join } from "node:path";
+import { basename, dirname, join, relative } from "node:path";
 import { type ScanFinding, readTextFileOrNull, scanContent } from "./scan";
 import { decodeUtf8Strict, listSupportingFiles, parseSkillMd } from "./vault";
 
@@ -12,10 +12,21 @@ export interface RepoSource {
 const GIT_URL_PREFIXES = ["http://", "https://", "git://", "ssh://", "file://"];
 const SCP_LIKE_URL_PATTERN = /^[^/\s]+@[^/\s]+:/;
 
-function isGitUrl(repo: string): boolean {
+export function isGitUrl(repo: string): boolean {
   return GIT_URL_PREFIXES.some((prefix) => repo.startsWith(prefix)) || SCP_LIKE_URL_PATTERN.test(repo);
 }
 
+/** A `file://` source_url reaches the local filesystem directly, not just a network
+ *  remote. That's fine when the user typed it themselves at `skillmux install` time,
+ *  but a `.skillmux-origin` sidecar is vault content — readable and writable by
+ *  whatever populated the vault (a shared git-backed vault pulled in, or a hand-edit),
+ *  same threat model as every other vault-content read this codebase guards. `skillmux
+ *  outdated`/`update` must not blindly git-clone/ls-remote whatever local path a
+ *  forged sidecar names. */
+export function isLocalFileUrl(url: string): boolean {
+  return url.startsWith("file://");
+}
+
 export function resolveRepoSource(repo: string): RepoSource {
   if (isGitUrl(repo)) return { url: repo };
 
@@ -49,11 +60,70 @@ export async function cloneToTemp(url: string): Promise<string> {
   return dir;
 }
 
+export function resolveCloneCommit(cloneDir: string): string {
+  const proc = Bun.spawnSync(["git", "-C", cloneDir, "rev-parse", "HEAD"], { stdout: "pipe", stderr: "pipe" });
+  if (proc.exitCode !== 0) {
+    throw new Error(`git rev-parse HEAD failed in ${cloneDir}: ${proc.stderr.toString().trim()}`);
+  }
+  return proc.stdout.toString().trim();
+}
+
+export async function remoteHeadCommit(url: string, ref = "HEAD"): Promise<string> {
+  const proc = Bun.spawn(["git", "ls-remote", url, ref], { stdout: "pipe", stderr: "pipe" });
+  const exitCode = await proc.exited;
+  const stdout = await new Response(proc.stdout).text();
+  if (exitCode !== 0) {
+    const stderr = await new Response(proc.stderr).text();
+    throw new Error(`git ls-remote failed for ${url}: ${stderr.trim()}`);
+  }
+  const line = stdout.split("\n").find((l) => l.trim().length > 0);
+  if (!line) throw new Error(`git ls-remote returned no ref "${ref}" for ${url}`);
+  const sha = line.split("\t")[0]?.trim();
+  if (!sha || !/^[0-9a-f]{40}$/.test(sha)) {
+    throw new Error(`git ls-remote returned an unparseable SHA for ${url}: ${line}`);
+  }
+  return sha;
+}
+
+/** Recursively finds symlinks under `dir` (skipping `.git`), without following them.
+ *  A skill's content must be regular files only — a symlink here is how a malicious
+ *  skill smuggles an escape out of the vault once `skillmux sync` exposes it inside
+ *  an agent's native skill directory. `dir` itself is checked too: a `skill_path`
+ *  can point straight at a directory that git committed *as a symlink* (git supports
+ *  storing symlink blobs) — walking its descendants alone would silently resolve
+ *  through it and report the target's real files as clean. */
+export function findSymlinks(dir: string): string[] {
+  const found: string[] = [];
+  if (lstatSync(dir).isSymbolicLink()) {
+    return ["(the skill directory itself is a symlink)"];
+  }
+  const walk = (current: string) => {
+    for (const entry of readdirSync(current, { withFileTypes: true })) {
+      if (entry.name === ".git") continue;
+      const abs = join(current, entry.name);
+      if (entry.isSymbolicLink()) {
+        found.push(relative(dir, abs));
+      } else if (entry.isDirectory()) {
+        walk(abs);
+      }
+    }
+  };
+  walk(dir);
+  return found.sort();
+}
+
 export interface ValidationResult {
   findings: ScanFinding[];
 }
 
 export async function validateSkillCandidate(skillId: string, dir: string): Promise<ValidationResult> {
+  const symlinks = findSymlinks(dir);
+  if (symlinks.length > 0) {
+    throw new Error(
+      `"${skillId}" contains symlink(s), which are not allowed in skill content: ${symlinks.join(", ")}`,
+    );
+  }
+
   const bytes = await Bun.file(join(dir, "SKILL.md")).bytes();
   const body = decodeUtf8Strict(bytes);
   parseSkillMd(skillId, body);
@@ -78,6 +148,12 @@ export async function validateSkillCandidate(skillId: string, dir: string): Prom
 }
 
 export function installIntoVault(vaultPath: string, skillId: string, sourceDir: string, force = false): string {
+  const symlinks = findSymlinks(sourceDir);
+  if (symlinks.length > 0) {
+    throw new Error(
+      `refusing to install "${skillId}": source contains symlink(s), which are not allowed in skill content: ${symlinks.join(", ")}`,
+    );
+  }
   const targetDir = join(vaultPath, skillId);
   if (existsSync(targetDir)) {
     if (!force) {
@@ -96,6 +172,9 @@ export interface ResolvedSkillDir {
 
 export function resolveSkillDir(cloneDir: string, fallbackName: string, skillPath?: string): ResolvedSkillDir {
   if (skillPath) {
+    if (skillPath.startsWith("/") || skillPath.split("/").includes("..")) {
+      throw new Error(`invalid skill_path "${skillPath}": must be a relative path within the repo`);
+    }
     return { skillId: basename(skillPath), dir: join(cloneDir, skillPath) };
   }
   if (existsSync(join(cloneDir, "SKILL.md"))) {

package/src/provenance.ts

@@ -0,0 +1,99 @@
+import { existsSync, lstatSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { isGitUrl } from "./install";
+import { SKILLMUX_ORIGIN_FILENAME, listSupportingFiles } from "./vault";
+
+export { SKILLMUX_ORIGIN_FILENAME };
+
+export interface SkillOrigin {
+  schema_version: 1;
+  source_url: string;
+  skill_path?: string;
+  commit: string;
+  installed_at: string;
+  content_hash: string;
+}
+
+function validateOrigin(origin: SkillOrigin, path: string): SkillOrigin {
+  if (origin.schema_version !== 1) throw new Error(`${path}: unsupported .skillmux-origin schema_version`);
+  if (typeof origin.source_url !== "string" || origin.source_url.length === 0) {
+    throw new Error(`${path}: .skillmux-origin is missing source_url`);
+  }
+  if (!isGitUrl(origin.source_url)) {
+    throw new Error(`${path}: .skillmux-origin has a source_url that is not a recognized git protocol`);
+  }
+  if (typeof origin.commit !== "string" || !/^[0-9a-f]{40}$/.test(origin.commit)) {
+    throw new Error(`${path}: .skillmux-origin has an invalid commit`);
+  }
+  if (typeof origin.installed_at !== "string") throw new Error(`${path}: .skillmux-origin is missing installed_at`);
+  if (typeof origin.content_hash !== "string" || !/^[a-f0-9]{64}$/.test(origin.content_hash)) {
+    throw new Error(`${path}: .skillmux-origin has an invalid content_hash`);
+  }
+  return origin;
+}
+
+/** Same defense-in-depth as readSkill/hashSkillContent: a tampered vault entry
+ *  (shared git-backed vault pulled in, or a hand-edit) could symlink the sidecar
+ *  itself to an arbitrary host file — refuse to follow it rather than feeding
+ *  that file's bytes into JSON.parse and, on a schema-shaped coincidence, into
+ *  the git commands `outdated`/`update` run against `source_url`. */
+export function readSkillOrigin(dir: string): SkillOrigin | null {
+  // The skill directory itself must be checked separately from the sidecar's own
+  // leaf check below: `lstat` only refuses to follow the *final* path component,
+  // so a symlinked skill directory containing a real, non-symlink sidecar at its
+  // target would otherwise resolve straight through to arbitrary host content.
+  if (existsSync(dir) && lstatSync(dir).isSymbolicLink()) {
+    throw new Error(`${dir}: refusing to read .skillmux-origin — the skill directory is a symlink`);
+  }
+  const path = join(dir, SKILLMUX_ORIGIN_FILENAME);
+  if (!existsSync(path)) return null;
+  if (lstatSync(path).isSymbolicLink()) {
+    throw new Error(`${path}: refusing to read .skillmux-origin — it is a symlink`);
+  }
+  return validateOrigin(JSON.parse(readFileSync(path, "utf-8")), path);
+}
+
+export function writeSkillOrigin(
+  dir: string,
+  params: {
+    source_url: string;
+    skill_path?: string;
+    commit: string;
+    installed_at: string;
+    content_hash: string;
+  },
+): void {
+  const origin: SkillOrigin = { schema_version: 1, ...params };
+  writeFileSync(join(dir, SKILLMUX_ORIGIN_FILENAME), JSON.stringify(origin, null, 2));
+}
+
+/** Deterministic sha256 over every file in a skill directory (SKILL.md plus every
+ *  file listSupportingFiles returns), used for local-drift detection. listSupportingFiles
+ *  already excludes symlinks it finds, but SKILL.md is read separately (same reason
+ *  readSkill/deliverSkill guard it independently in vault.ts/router-core.ts) — this is
+ *  a local, already-installed vault dir, not the freshly cloned candidate that
+ *  validateSkillCandidate has vetted, so a swapped-in symlinked SKILL.md must be
+ *  refused here rather than followed. `dir` itself is checked too: every per-file
+ *  lstat below only refuses to follow a symlinked *leaf*, so a symlinked `dir`
+ *  containing real (non-symlink) files at its target would otherwise resolve
+ *  straight through to arbitrary host content. */
+export function hashSkillContent(dir: string): string {
+  const vaultPath = dirname(dir);
+  const skillId = basename(dir);
+  if (lstatSync(dir).isSymbolicLink()) {
+    throw new Error(`refusing to hash ${skillId}: the skill directory is a symlink`);
+  }
+  const hasher = new Bun.CryptoHasher("sha256");
+  const files = ["SKILL.md", ...listSupportingFiles(vaultPath, skillId)];
+  for (const rel of files) {
+    const path = join(dir, rel);
+    if (lstatSync(path).isSymbolicLink()) {
+      throw new Error(`refusing to hash ${skillId}/${rel}: it is a symlink`);
+    }
+    hasher.update(rel);
+    hasher.update("\0");
+    hasher.update(readFileSync(path));
+    hasher.update("\0");
+  }
+  return hasher.digest("hex");
+}