@cohortapp/agent-sdk 2.11.15 → 2.13.0

package/lib/collective/presence.mjs

@@ -20,9 +20,10 @@
 "use strict";
 
 import {
-  writeFileSync, readFileSync, unlinkSync, readdirSync, mkdirSync, existsSync,
+  readFileSync, unlinkSync, readdirSync, mkdirSync, existsSync,
 } from "node:fs";
 import { join, basename } from "node:path";
+import { writeJsonAtomic } from "../fs-atomic.mjs";
 
 const PRESENCE_REL = "state/collective/presence";
 const DEFAULT_STALE_SEC = 300;
@@ -84,7 +85,7 @@ export function register(agentRoot, info = {}) {
       status: info.status || "active",
       kind: info.kind || "interactive",
     };
-    writeFileSync(path, JSON.stringify(rec, null, 2));
+    writeJsonAtomic(path, rec);
     return true;
   } catch {
     return false;
@@ -104,7 +105,7 @@ export function heartbeat(agentRoot, sessionId, updates = {}) {
     rec.lastBeat = nowIso(updates.nowMs);
     if (updates.intent !== undefined) rec.intent = String(updates.intent).slice(0, 200);
     if (updates.status !== undefined) rec.status = updates.status;
-    writeFileSync(path, JSON.stringify(rec, null, 2));
+    writeJsonAtomic(path, rec);
     return true;
   } catch {
     return false;

package/lib/collective/vendor-skills.mjs

@@ -0,0 +1,305 @@
+/**
+ * lib/collective/vendor-skills.mjs — install the VENDORED design skill packs
+ * into ~/.claude/skills so any Claude Code session on the seat machine has
+ * them, alongside the maestro-authored skills that lib/collective/global-skills.mjs
+ * installs.
+ *
+ * The two installers differ in two ways that matter:
+ *
+ *   - **Directory name.** A maestro skill lands at `maestro-<file>`; a vendored
+ *     skill lands at its own frontmatter `name`, because that name is what its
+ *     own prose, its sibling references and the harmoniser skill all refer to.
+ *   - **Copy, never symlink.** A vendored skill is a small tree (SKILL.md plus
+ *     reference files), and the point of vendoring is that the seat holds
+ *     reviewed bytes rather than a pointer into a package that `npm` may replace
+ *     underneath a running session.
+ *
+ * **Never clobber a directory that is not ours.** `~/.claude/skills/impeccable`
+ * may already exist because the human installed the upstream skill themselves —
+ * with its launcher, its hooks and its live mode, none of which belong on a
+ * seat. Overwriting that would silently take their install away, and merging
+ * into it would produce a tree that is neither. So every directory we own
+ * carries {@link MARKER_FILE}; a directory without one is left exactly as it is
+ * and reported. The marker's content is derived entirely from the pack (no
+ * timestamps), so a re-run of an unchanged install writes nothing at all.
+ *
+ * Nothing here executes a vendored file. It is content.
+ *
+ * @module lib/collective/vendor-skills
+ */
+
+"use strict";
+
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, rmSync, statSync, cpSync } from "node:fs";
+import { join, dirname, sep } from "node:path";
+
+/** Where the vendored packs live, relative to the SDK root. */
+export const VENDOR_REL = join("plugins", "maestro-skills", "vendor");
+
+/** The file that says "maestro owns this skill directory". */
+export const MARKER_FILE = ".maestro-vendor.json";
+
+/** Written into MARKER_FILE so the owner is unambiguous to a human reading it. */
+export const MARKER_OWNER = "@cohortapp/agent-sdk";
+
+/**
+ * The `name` from a SKILL.md's YAML frontmatter. Pure. Returns null when the
+ * file has no frontmatter or no name — the caller must not guess a directory
+ * name, because a wrong guess is a directory nobody can find again.
+ * @param {string} body
+ * @returns {string|null}
+ */
+export function frontmatterName(body) {
+  const text = String(body || "");
+  if (!text.startsWith("---")) return null;
+  const end = text.indexOf("\n---", 3);
+  if (end === -1) return null;
+  for (const line of text.slice(3, end).split("\n")) {
+    const m = /^name:\s*(.+?)\s*$/.exec(line);
+    if (!m) continue;
+    const name = m[1].replace(/^["']|["']$/g, "").trim();
+    return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name) ? name : null;
+  }
+  return null;
+}
+
+/** Recursively list files under `dir` relative to it (POSIX), sorted. */
+export function listFiles(dir, prefix = "") {
+  let out = [];
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return out; }
+  for (const e of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
+    const rel = prefix ? `${prefix}/${e.name}` : e.name;
+    if (e.isDirectory()) out = out.concat(listFiles(join(dir, e.name), rel));
+    else if (e.isFile()) out.push(rel);
+  }
+  return out;
+}
+
+/**
+ * The marker body for one installed skill. Deterministic — no clock, so a
+ * re-run over an unchanged install writes nothing.
+ *
+ * `files` records the sha256 of every file THIS installer wrote. That is what
+ * lets the next run tell a file it wrote itself from a file a person edited or
+ * added, and back the latter up instead of deleting it — the module's own
+ * "additive, idempotent, backed up" contract, which the first cut honoured for
+ * every JSON file `global-setup` touches and not for this step.
+ *
+ * @param {object} pack @param {string} name
+ * @param {Array<{to:string, sha256:string}>} [files]
+ */
+export function markerFor(pack, name, files = []) {
+  const doc = {
+    owner: MARKER_OWNER, pack: pack.id, repo: pack.repo, sha: pack.sha, license: pack.license, skill: name,
+    files: files.slice().sort((a, b) => (a.to < b.to ? -1 : 1)).map((f) => ({ path: f.to, sha256: f.sha256 })),
+  };
+  return `${JSON.stringify(doc, null, 2)}\n`;
+}
+
+/** sha256 of a buffer or string. Pure. */
+export function sha256(body) {
+  return createHash("sha256").update(body).digest("hex");
+}
+
+/**
+ * What this installer last wrote into `dir`, as path → sha256, from its marker.
+ * An older marker with no `files` map yields an empty map, which is read as
+ * "we cannot prove we wrote any of this" — so nothing there is deleted without
+ * a backup. Failing safe costs one backup directory; failing open costs
+ * somebody their edits.
+ * @param {string} dir @returns {Map<string,string>}
+ */
+export function recordedFiles(dir) {
+  try {
+    const doc = JSON.parse(readFileSync(join(dir, MARKER_FILE), "utf8"));
+    if (!doc || !Array.isArray(doc.files)) return new Map();
+    return new Map(doc.files.map((f) => [String(f && f.path), String(f && f.sha256)]));
+  } catch { return new Map(); }
+}
+
+/**
+ * Does this directory belong to us? `absent` when there is nothing there,
+ * `ours` when it carries our marker, `foreign` otherwise — and `foreign` is
+ * always left alone.
+ * @param {string} dir
+ * @returns {"absent"|"ours"|"foreign"}
+ */
+export function ownership(dir) {
+  if (!existsSync(dir)) return "absent";
+  const marker = join(dir, MARKER_FILE);
+  if (!existsSync(marker)) return "foreign";
+  try {
+    const doc = JSON.parse(readFileSync(marker, "utf8"));
+    return doc && doc.owner === MARKER_OWNER ? "ours" : "foreign";
+  } catch {
+    return "foreign"; // an unreadable marker is not our proof of ownership
+  }
+}
+
+/**
+ * Plan the install: which vendored file goes to which destination, per skill.
+ * Pure over the filesystem it reads (no writes). A pack whose vendored tree is
+ * absent (a checkout that has not synced, a tarball built before WP-M7) simply
+ * contributes nothing.
+ *
+ * @param {{sdkRoot:string, skillsDir:string, packs:Array}} o
+ * @returns {{ skills: Array<{pack:object, name:string, root:string, dest:string, files:Array<{from:string,to:string}>}>, errors: Array<{pack:string, error:string}> }}
+ */
+export function planVendorSkills(o = {}) {
+  const sdkRoot = String(o.sdkRoot || "");
+  const skillsDir = String(o.skillsDir || "");
+  const skills = [];
+  const errors = [];
+  for (const pack of o.packs || []) {
+    const packDir = join(sdkRoot, VENDOR_REL, pack.id);
+    if (!existsSync(packDir)) { errors.push({ pack: pack.id, error: `vendored tree absent at ${packDir}` }); continue; }
+    const packFiles = listFiles(packDir).filter((f) => f !== "UPSTREAM.json");
+    for (const root of pack.skillRoots || []) {
+      const rel = root === "." ? "" : root;
+      const prefix = rel ? `${rel}/` : "";
+      const inRoot = packFiles.filter((f) => (prefix ? f.startsWith(prefix) : true));
+      // A nested skill root (emilkowalski/taste-skill hold several) must not
+      // swallow its siblings when the outer root is the pack itself.
+      const owned = rel
+        ? inRoot
+        : packFiles.filter((f) => !(pack.skillRoots || []).some((r) => r !== "." && f.startsWith(`${r}/`)));
+      const skillMd = owned.find((f) => f === `${prefix}SKILL.md`);
+      if (!skillMd) { errors.push({ pack: pack.id, error: `no SKILL.md under ${root}` }); continue; }
+      let name;
+      try {
+        name = frontmatterName(readFileSync(join(packDir, skillMd), "utf8"));
+      } catch (err) {
+        errors.push({ pack: pack.id, error: `unreadable ${skillMd}: ${err && err.message}` });
+        continue;
+      }
+      if (!name) { errors.push({ pack: pack.id, error: `${skillMd} has no usable frontmatter name` }); continue; }
+      const files = owned.map((f) => ({ from: f, to: prefix ? f.slice(prefix.length) : f }));
+      // A skill installed out of a sub-directory still ships its licence.
+      if (rel) {
+        for (const lic of ["LICENSE", "NOTICE.md"]) {
+          if (packFiles.includes(lic) && !files.some((f) => f.to === lic)) files.push({ from: lic, to: lic });
+        }
+      }
+      files.sort((a, b) => (a.to < b.to ? -1 : 1));
+      skills.push({ pack, name, root, dest: join(skillsDir, name), files });
+    }
+  }
+  skills.sort((a, b) => (a.name < b.name ? -1 : 1));
+  // Two packs claiming one frontmatter name would install into one directory:
+  // `ownership()` reads only the marker's `owner`, so the second pack would see
+  // "ours", compute the first pack's files as stale, delete them and write its
+  // own — reported as a normal install. There is no collision today; the
+  // registry is meant to grow, so the collision is an error rather than a race.
+  const kept = [];
+  const claimed = new Map();
+  for (const s of skills) {
+    const first = claimed.get(s.name);
+    if (first) {
+      errors.push({ pack: s.pack.id, error: `skill name "${s.name}" is already claimed by pack ${first} — refusing to install one over the other; rename it in the registry` });
+      continue;
+    }
+    claimed.set(s.name, s.pack.id);
+    kept.push(s);
+  }
+  return { skills: kept, errors };
+}
+
+/**
+ * Apply the plan. Idempotent: an up-to-date directory is left untouched and
+ * reported as unchanged; a foreign directory is skipped with a reason; a stale
+ * file inside a directory we own is removed. Never throws.
+ *
+ * @param {{sdkRoot:string, skillsDir:string, packs:Array, dryRun?:boolean}} o
+ * @returns {{ok:boolean, installed:string[], unchanged:string[], skipped:Array<{name:string,reason:string}>, backups:Array<{name:string,path:string,files:string[]}>, errors:Array<{pack:string,error:string}>, plan:Array}}
+ */
+export function installVendorSkills(o = {}) {
+  // A destination that is not a skills directory is a bug upstream of us — an
+  // unset variable interpolating to "undefined/home/.claude/skills" once had
+  // this installer create a full 14-skill tree relative to the cwd, inside a
+  // repo checkout. `looksLikeSkillsDir` existed for exactly that and was never
+  // called, which is worse than not having it: its passing test read as proof.
+  if (!looksLikeSkillsDir(o.skillsDir)) {
+    return { ok: false, installed: [], unchanged: [], skipped: [], plan: [],
+      errors: [{ pack: "-", error: `refusing to install: ${JSON.stringify(String(o.skillsDir || ""))} is not a skills directory` }] };
+  }
+  const { skills, errors } = planVendorSkills(o);
+  const installed = [];
+  const unchanged = [];
+  const skipped = [];
+  const backups = [];
+  const stamp = o.stamp || new Date().toISOString().replace(/[:.]/g, "-");
+  for (const skill of skills) {
+    try {
+      const own = ownership(skill.dest);
+      if (own === "foreign") {
+        skipped.push({ name: skill.name, reason: `${skill.dest} exists and is not maestro's — leaving it alone` });
+        continue;
+      }
+      const packDir = join(o.sdkRoot, VENDOR_REL, skill.pack.id);
+      const wanted = new Map(skill.files.map((f) => [f.to, readFileSync(join(packDir, f.from))]));
+      wanted.set(MARKER_FILE, Buffer.from(markerFor(
+        skill.pack, skill.name,
+        skill.files.map((f) => ({ to: f.to, sha256: sha256(wanted.get(f.to)) })),
+      )));
+      const present = own === "ours" ? listFiles(skill.dest) : [];
+      const stale = present.filter((f) => !wanted.has(f));
+      const wrote = recordedFiles(skill.dest);
+
+      // Anything in this directory we cannot prove we wrote is somebody's work:
+      // a file they added, or one of ours they edited. Copy the directory aside
+      // once before touching it, exactly as every other global-setup step backs
+      // up a file it is about to rewrite.
+      const mine = (rel, cur) => rel === MARKER_FILE || (wrote.has(rel) && cur !== null && wrote.get(rel) === sha256(cur));
+      const readOr = (rel) => { try { return readFileSync(join(skill.dest, rel)); } catch { return null; } };
+      const humanTouched = present.filter((rel) => !mine(rel, readOr(rel)));
+
+      let changed = stale.length > 0;
+      let backedUp = null;
+      const backup = () => {
+        if (backedUp || o.dryRun) return;
+        backedUp = `${skill.dest}.backup.${stamp}`;
+        cpSync(skill.dest, backedUp, { recursive: true });
+        backups.push({ name: skill.name, path: backedUp, files: humanTouched.slice() });
+      };
+      if (humanTouched.length) backup();
+
+      for (const [rel, body] of wanted) {
+        const abs = join(skill.dest, rel);
+        const cur = readOr(rel);
+        if (cur !== null && cur.equals(body)) continue;
+        changed = true;
+        if (o.dryRun) continue;
+        mkdirSync(dirname(abs), { recursive: true });
+        writeFileSync(abs, body, { mode: 0o644 });
+      }
+      if (!o.dryRun) for (const rel of stale) rmSync(join(skill.dest, rel), { force: true });
+      (changed ? installed : unchanged).push(skill.name);
+    } catch (err) {
+      errors.push({ pack: skill.pack.id, error: `${skill.name}: ${err && err.message ? err.message : err}` });
+    }
+  }
+  return { ok: errors.length === 0, installed, unchanged, skipped, backups, errors, plan: skills };
+}
+
+/** Guard against a skills dir that is not under a home-ish path. Pure. */
+export function looksLikeSkillsDir(dir) {
+  const d = String(dir || "");
+  return d.endsWith(`${sep}skills`) || d.endsWith("/skills");
+}
+
+/** File count + byte size of a vendored pack, for reporting. */
+export function packSize(sdkRoot, pack) {
+  const dir = join(sdkRoot, VENDOR_REL, pack.id);
+  let bytes = 0;
+  const files = listFiles(dir);
+  for (const f of files) { try { bytes += statSync(join(dir, f)).size; } catch { /* a file that vanished mid-scan is not a size */ } }
+  return { files: files.length, bytes };
+}
+
+export default {
+  VENDOR_REL, MARKER_FILE, MARKER_OWNER, frontmatterName, listFiles, markerFor,
+  ownership, planVendorSkills, installVendorSkills, looksLikeSkillsDir, packSize,
+  sha256, recordedFiles,
+};

package/lib/collective/vendor-skills.test.mjs

@@ -0,0 +1,306 @@
+/**
+ * Tests for lib/collective/vendor-skills.mjs — installing the VENDORED design
+ * skill packs into a seat's ~/.claude/skills.
+ *
+ * Three properties carry the weight, and each is pinned here:
+ *
+ *   1. **It installs under the frontmatter name**, not the directory name —
+ *      `taste-skill/skills/soft-skill` is `high-end-visual-design` to every
+ *      piece of prose that refers to it, including the harmoniser skill.
+ *   2. **It is idempotent.** A second run over an unchanged tree writes
+ *      nothing, because `global-setup` runs on every upgrade hop on 40+ seats.
+ *   3. **It never clobbers a directory that is not ours.** A human who
+ *      installed upstream `impeccable` themselves — launcher, hooks, live mode
+ *      — keeps it, and the run says so instead of silently taking it away.
+ *
+ * The end-to-end cases run against the REAL vendored trees in a throwaway HOME,
+ * because a plan that is right about a synthetic pack and wrong about
+ * `emilkowalski`'s nested skill roots would ship.
+ *
+ * @module lib/collective/vendor-skills.test
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, existsSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  frontmatterName, ownership, planVendorSkills, installVendorSkills, markerFor,
+  packSize, looksLikeSkillsDir, MARKER_FILE, MARKER_OWNER,
+} from "./vendor-skills.mjs";
+import { PACKS, findPack } from "../../scripts/vendor/skill-packs.mjs";
+
+const SDK_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+/** A throwaway HOME. Returns {home, skillsDir, cleanup}. */
+function throwawayHome() {
+  const home = mkdtempSync(join(tmpdir(), "maestro-vendor-home-"));
+  return {
+    home,
+    skillsDir: join(home, ".claude", "skills"),
+    cleanup: () => rmSync(home, { recursive: true, force: true }),
+  };
+}
+
+describe("vendor-skills: pure helpers", () => {
+  it("frontmatterName reads the name and refuses a body that has none", () => {
+    assert.equal(frontmatterName("---\nname: impeccable\nversion: 4.3.1\n---\n# x"), "impeccable");
+    assert.equal(frontmatterName('---\nname: "quoted-name"\n---\n'), "quoted-name");
+    assert.equal(frontmatterName("# no frontmatter\n"), null);
+    assert.equal(frontmatterName("---\ndescription: no name here\n---\n"), null);
+  });
+
+  it("frontmatterName refuses a name that would escape the skills directory", () => {
+    assert.equal(frontmatterName("---\nname: ../../etc\n---\n"), null);
+    assert.equal(frontmatterName("---\nname: a/b\n---\n"), null);
+  });
+
+  it("looksLikeSkillsDir only accepts a path ending in skills/", () => {
+    assert.equal(looksLikeSkillsDir("/home/x/.claude/skills"), true);
+    assert.equal(looksLikeSkillsDir("/home/x/.claude"), false);
+  });
+
+  it("markerFor is deterministic — no clock, so a re-run writes nothing", () => {
+    const pack = findPack("unlazy");
+    assert.equal(markerFor(pack, "unlazy"), markerFor(pack, "unlazy"));
+    const doc = JSON.parse(markerFor(pack, "unlazy"));
+    assert.equal(doc.owner, MARKER_OWNER);
+    assert.equal(doc.sha, pack.sha);
+  });
+});
+
+describe("vendor-skills: ownership", () => {
+  it("reports absent / ours / foreign", () => {
+    const { home, cleanup } = throwawayHome();
+    try {
+      const absent = join(home, "nothing");
+      assert.equal(ownership(absent), "absent");
+
+      const foreign = join(home, "impeccable");
+      mkdirSync(foreign, { recursive: true });
+      writeFileSync(join(foreign, "SKILL.md"), "the human's own install\n");
+      assert.equal(ownership(foreign), "foreign");
+
+      const ours = join(home, "unlazy");
+      mkdirSync(ours, { recursive: true });
+      writeFileSync(join(ours, MARKER_FILE), markerFor(findPack("unlazy"), "unlazy"));
+      assert.equal(ownership(ours), "ours");
+
+      writeFileSync(join(ours, MARKER_FILE), "{not json");
+      assert.equal(ownership(ours), "foreign", "an unreadable marker is not proof of ownership");
+
+      writeFileSync(join(ours, MARKER_FILE), JSON.stringify({ owner: "someone-else" }));
+      assert.equal(ownership(ours), "foreign");
+    } finally { cleanup(); }
+  });
+});
+
+describe("vendor-skills: the plan over the real vendored trees", () => {
+  const { skills, errors } = planVendorSkills({ sdkRoot: SDK_ROOT, skillsDir: "/tmp/unused", packs: PACKS });
+
+  it("plans one skill per declared skill root, with no errors", () => {
+    assert.deepEqual(errors, [], "every pack's tree is present and every root has a SKILL.md");
+    const roots = PACKS.reduce((n, p) => n + p.skillRoots.length, 0);
+    assert.equal(skills.length, roots);
+  });
+
+  it("installs under the frontmatter name, not the directory name", () => {
+    const names = skills.map((s) => s.name);
+    for (const expected of [
+      "impeccable", "unlazy",
+      "emil-design-eng", "animate", "animation-vocabulary", "apple-design",
+      "find-animation-opportunities", "improve-animations", "review-animations", "prototype",
+      "design-taste-frontend", "redesign-existing-projects", "high-end-visual-design", "minimalist-ui",
+    ]) assert.ok(names.includes(expected), `expected skill ${expected}, got ${names.join(", ")}`);
+    assert.equal(new Set(names).size, names.length, "no two packs claim the same directory");
+  });
+
+  it("gives every skill a SKILL.md at its root and never a sibling skill's files", () => {
+    for (const s of skills) {
+      assert.ok(s.files.some((f) => f.to === "SKILL.md"), `${s.name} has SKILL.md at its root`);
+      assert.ok(s.files.every((f) => !f.to.startsWith("skills/")), `${s.name} carries no nested skills/ path`);
+    }
+    const animate = skills.find((s) => s.name === "animate");
+    assert.ok(animate.files.some((f) => f.to === "RECIPES.md"), "sibling reference file comes along");
+    assert.ok(animate.files.some((f) => f.to === "LICENSE"), "a sub-directory skill still ships its licence");
+    assert.ok(!animate.files.some((f) => f.to.includes("apple-design")), "a sibling skill's files stay out");
+  });
+
+  it("impeccable brings its reference tree, its subordinate briefs and its NOTICE", () => {
+    const imp = skills.find((s) => s.name === "impeccable");
+    assert.ok(imp.files.some((f) => f.to === "NOTICE.md"));
+    assert.ok(imp.files.some((f) => f.to.startsWith("reference/")));
+    assert.ok(imp.files.some((f) => f.to.startsWith("agents/impeccable-")));
+  });
+
+  it("a pack whose vendored tree is absent is an error, not a crash", () => {
+    const r = planVendorSkills({ sdkRoot: join(tmpdir(), "no-such-sdk-root"), skillsDir: "/tmp/unused", packs: PACKS });
+    assert.equal(r.skills.length, 0);
+    assert.equal(r.errors.length, PACKS.length);
+  });
+});
+
+describe("vendor-skills: install into a throwaway HOME", () => {
+  it("installs every pack skill, is idempotent, and heals a tampered file", () => {
+    const { skillsDir, cleanup } = throwawayHome();
+    try {
+      const first = installVendorSkills({ sdkRoot: SDK_ROOT, skillsDir, packs: PACKS });
+      assert.deepEqual(first.errors, []);
+      assert.deepEqual(first.skipped, []);
+      assert.equal(first.unchanged.length, 0);
+      assert.ok(first.installed.length >= 14, `installed ${first.installed.length} skills`);
+
+      // The bytes landed, under the frontmatter name, with our marker.
+      const impeccable = join(skillsDir, "impeccable");
+      assert.ok(existsSync(join(impeccable, "SKILL.md")));
+      assert.ok(existsSync(join(impeccable, "reference", "critique.md")));
+      assert.ok(existsSync(join(impeccable, "LICENSE")));
+      assert.equal(ownership(impeccable), "ours");
+      assert.equal(statSync(join(impeccable, "SKILL.md")).mode & 0o777, 0o644);
+
+      const minimalist = join(skillsDir, "minimalist-ui");
+      assert.match(readFileSync(join(minimalist, "SKILL.md"), "utf8"), /name: minimalist-ui/);
+
+      // Second run: nothing written.
+      const second = installVendorSkills({ sdkRoot: SDK_ROOT, skillsDir, packs: PACKS });
+      assert.deepEqual(second.installed, [], "idempotent");
+      assert.equal(second.unchanged.length, first.installed.length);
+
+      // A locally edited file is restored; a stray file inside a directory we
+      // own is removed (it would otherwise be read as skill content forever).
+      writeFileSync(join(impeccable, "SKILL.md"), "tampered\n");
+      writeFileSync(join(impeccable, "stray.md"), "not upstream\n");
+      const third = installVendorSkills({ sdkRoot: SDK_ROOT, skillsDir, packs: PACKS });
+      assert.ok(third.installed.includes("impeccable"));
+      assert.match(readFileSync(join(impeccable, "SKILL.md"), "utf8"), /^---\nname: impeccable/);
+      assert.equal(existsSync(join(impeccable, "stray.md")), false);
+    } finally { cleanup(); }
+  });
+
+  it("leaves a FOREIGN directory exactly as it is and says which one", () => {
+    const { skillsDir, cleanup } = throwawayHome();
+    try {
+      // The human installed upstream impeccable themselves — launcher and all.
+      const foreign = join(skillsDir, "impeccable");
+      mkdirSync(join(foreign, "scripts"), { recursive: true });
+      const own = "---\nname: impeccable\n---\nthe human's own copy, with its launcher\n";
+      writeFileSync(join(foreign, "SKILL.md"), own);
+      writeFileSync(join(foreign, "scripts", "impeccable"), "#!/bin/sh\n");
+
+      const r = installVendorSkills({ sdkRoot: SDK_ROOT, skillsDir, packs: PACKS });
+      assert.deepEqual(r.installed.includes("impeccable"), false, "not installed over the human's copy");
+      assert.equal(r.skipped.length, 1);
+      assert.equal(r.skipped[0].name, "impeccable");
+      assert.match(r.skipped[0].reason, /not maestro's/);
+      assert.equal(readFileSync(join(foreign, "SKILL.md"), "utf8"), own, "byte-for-byte untouched");
+      assert.ok(existsSync(join(foreign, "scripts", "impeccable")), "their launcher is still theirs");
+      // Every other pack still installed.
+      assert.ok(r.installed.includes("unlazy"));
+      assert.ok(existsSync(join(skillsDir, "unlazy", "SKILL.md")));
+    } finally { cleanup(); }
+  });
+
+  it("dryRun reports what it would do and writes nothing", () => {
+    const { skillsDir, cleanup } = throwawayHome();
+    try {
+      const r = installVendorSkills({ sdkRoot: SDK_ROOT, skillsDir, packs: PACKS, dryRun: true });
+      assert.ok(r.installed.length > 0);
+      assert.equal(existsSync(skillsDir), false, "nothing written");
+    } finally { cleanup(); }
+  });
+
+  it("refuses a destination that is not a skills directory, and writes nothing", () => {
+    // The failure this pins: an unset variable interpolated to
+    // "undefined/home/.claude/skills" and a full 14-skill tree was created at
+    // ./undefined/ relative to the cwd, inside a repo checkout.
+    const home = mkdtempSync(join(tmpdir(), "maestro-vendor-bogus-"));
+    try {
+      const bogus = join(home, ".claude", "skulls");
+      const r = installVendorSkills({ sdkRoot: SDK_ROOT, skillsDir: bogus, packs: PACKS });
+      assert.equal(r.ok, false);
+      assert.deepEqual(r.installed, []);
+      assert.match(r.errors[0].error, /not a skills directory/);
+      assert.equal(existsSync(bogus), false, "nothing was created");
+    } finally { rmSync(home, { recursive: true, force: true }); }
+  });
+
+  it("refuses to install two packs into one skill name rather than letting one eat the other", () => {
+    // No collision exists today; the registry is meant to grow, and
+    // ownership() reads only the owner string, so the second pack would see
+    // "ours", delete the first pack's files as stale and report a normal
+    // install.
+    const fakeSdk = mkdtempSync(join(tmpdir(), "maestro-vendor-sdk-"));
+    const { skillsDir, cleanup } = throwawayHome();
+    try {
+      const packs = ["alpha", "beta"].map((id) => {
+        const dir = join(fakeSdk, "plugins", "maestro-skills", "vendor", id);
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(join(dir, "SKILL.md"), `---\nname: shared-skill\n---\nfrom ${id}\n`);
+        return { id, repo: `example/${id}`, sha: "0".repeat(40), license: "MIT", skillRoots: ["."] };
+      });
+      const r = planVendorSkills({ sdkRoot: fakeSdk, skillsDir, packs });
+      assert.equal(r.skills.length, 1, "only the first claim stands");
+      assert.equal(r.skills[0].pack.id, "alpha");
+      assert.ok(r.errors.some((e) => e.pack === "beta" && /already claimed by pack alpha/.test(e.error)), JSON.stringify(r.errors));
+
+      const inst = installVendorSkills({ sdkRoot: fakeSdk, skillsDir, packs });
+      assert.equal(inst.ok, false, "a collision is an error, not a silent overwrite");
+      assert.match(readFileSync(join(skillsDir, "shared-skill", "SKILL.md"), "utf8"), /from alpha/);
+    } finally { cleanup(); rmSync(fakeSdk, { recursive: true, force: true }); }
+  });
+
+  it("copies a directory aside before overwriting work somebody did in it", () => {
+    const { skillsDir, cleanup } = throwawayHome();
+    try {
+      installVendorSkills({ sdkRoot: SDK_ROOT, skillsDir, packs: PACKS, stamp: "STAMP" });
+      const dir = join(skillsDir, "impeccable");
+      const tuned = "---\nname: impeccable\n---\ntuned for Cohort\n";
+      writeFileSync(join(dir, "SKILL.md"), tuned);
+      writeFileSync(join(dir, "cohort-notes.md"), "a person's own notes\n");
+
+      const r = installVendorSkills({ sdkRoot: SDK_ROOT, skillsDir, packs: PACKS, stamp: "STAMP" });
+      const b = r.backups.find((x) => x.name === "impeccable");
+      assert.ok(b, `expected a backup, got ${JSON.stringify(r.backups)}`);
+      assert.deepEqual(b.files.sort(), ["SKILL.md", "cohort-notes.md"]);
+      assert.equal(readFileSync(join(b.path, "SKILL.md"), "utf8"), tuned, "their edit survives");
+      assert.equal(readFileSync(join(b.path, "cohort-notes.md"), "utf8"), "a person's own notes\n");
+      // …and the live directory is back to the vendored bytes.
+      assert.match(readFileSync(join(dir, "SKILL.md"), "utf8"), /^---\nname: impeccable/);
+      assert.equal(existsSync(join(dir, "cohort-notes.md")), false);
+    } finally { cleanup(); }
+  });
+
+  it("backs nothing up when it only rewrites files it wrote itself", () => {
+    const { skillsDir, cleanup } = throwawayHome();
+    try {
+      const first = installVendorSkills({ sdkRoot: SDK_ROOT, skillsDir, packs: PACKS, stamp: "STAMP" });
+      assert.deepEqual(first.backups, []);
+      const second = installVendorSkills({ sdkRoot: SDK_ROOT, skillsDir, packs: PACKS, stamp: "STAMP" });
+      assert.deepEqual(second.backups, [], "an idempotent re-run leaves no backup directories behind");
+      assert.deepEqual(second.installed, []);
+    } finally { cleanup(); }
+  });
+
+  it("puts no hook machinery on the seat", () => {
+    const { skillsDir, cleanup } = throwawayHome();
+    try {
+      installVendorSkills({ sdkRoot: SDK_ROOT, skillsDir, packs: PACKS });
+      const unlazy = join(skillsDir, "unlazy");
+      assert.ok(existsSync(join(unlazy, "scripts", "gate-check.mjs")), "the gate checker is the reason scripts/ is vendored");
+      for (const name of ["install-hooks.mjs", "stop-hook.mjs"]) {
+        assert.equal(existsSync(join(unlazy, "scripts", name)), false,
+          `${name} would be one \`node <path>\` away from a Stop hook in the settings file every session reads`);
+      }
+    } finally { cleanup(); }
+  });
+
+  it("packSize reports a file count and a byte size for every pack", () => {
+    for (const pack of PACKS) {
+      const s = packSize(SDK_ROOT, pack);
+      assert.ok(s.files > 0, `${pack.id} has files`);
+      assert.ok(s.bytes > 0, `${pack.id} has bytes`);
+    }
+  });
+});