@cohortapp/agent-sdk 2.12.0 → 2.13.0

package/lib/cli/global-setup-extras.test.mjs

@@ -12,6 +12,7 @@ import { join } from "node:path";
 
 import { applyFrontDoorSetup, mergeJsonFileAtomic, findOnPath, pickClaudeBin, checkPersonaHookScript } from "./global-setup-extras.mjs";
 import { IDENTITY_BEGIN, CLAUDE_MD_BEGIN, PRE_SEND_HOOK_MATCHER } from "../collective/global-config.mjs";
+import { SDK_ROOT } from "./global-setup-extras.mjs";
 
 function fixture() {
   const root = mkdtempSync(join(tmpdir(), "gs-extras-"));
@@ -365,3 +366,97 @@ test("applyFrontDoorSetup: skills are rendered to the agent's identity (config/a
     assert.ok(f.logs.some((l) => /rendered/.test(l)), "the summary line says which skills were rendered");
   } finally { rmSync(f.root, { recursive: true, force: true }); }
 });
+
+// ---------------------------------------------------------------------------
+// Step 5 (WP-M7): the vendored design skill packs. These run against the REAL
+// vendored trees in this checkout, into a throwaway HOME — the seam that
+// matters is "global-setup put impeccable/unlazy/... on the machine", and a
+// synthetic pack would not prove it.
+// ---------------------------------------------------------------------------
+
+test("applyFrontDoorSetup: installs the vendored design packs into a throwaway HOME under their own names, idempotently", async () => {
+  const f = fixture();
+  try {
+    const opts = {
+      agentRoot: f.agentRoot, sdkRoot: SDK_ROOT, claudeDir: f.claudeDir, claudeJsonPath: f.claudeJsonPath,
+      claudeBin: null, globalRoot: "", now: Date.parse("2026-09-08T12:00:00Z"), ...f.io,
+    };
+    const r = await applyFrontDoorSetup(opts);
+    assert.deepEqual(r.vendorSkills.errors, []);
+    assert.deepEqual(r.vendorSkills.skipped, []);
+    for (const name of ["impeccable", "unlazy", "animate", "design-taste-frontend"]) {
+      assert.ok(r.vendorSkills.installed.includes(name), `${name} installed`);
+      assert.ok(existsSync(join(f.claudeDir, "skills", name, "SKILL.md")), `${name}/SKILL.md on disk`);
+    }
+    // Under its own name, NOT the maestro- prefix the shipped skills use.
+    assert.equal(existsSync(join(f.claudeDir, "skills", "maestro-impeccable")), false);
+    // Licences travel with the content.
+    assert.ok(existsSync(join(f.claudeDir, "skills", "impeccable", "NOTICE.md")));
+    assert.ok(existsSync(join(f.claudeDir, "skills", "animate", "LICENSE")));
+    // No hook manifest is ever written next to a vendored skill.
+    assert.equal(existsSync(join(f.claudeDir, "skills", "unlazy", "hooks.json")), false);
+    assert.equal(existsSync(join(f.claudeDir, "skills", "unlazy", "settings.json")), false);
+
+    const again = await applyFrontDoorSetup({ ...opts, now: Date.parse("2026-09-08T12:05:00Z") });
+    assert.deepEqual(again.vendorSkills.installed, [], "second run writes nothing");
+    assert.ok(again.vendorSkills.unchanged.length >= 14);
+  } finally { rmSync(f.root, { recursive: true, force: true }); }
+});
+
+test("applyFrontDoorSetup: a design-skill directory that is not ours is left alone and reported", async () => {
+  const f = fixture();
+  try {
+    const foreign = join(f.claudeDir, "skills", "impeccable");
+    mkdirSync(foreign, { recursive: true });
+    const body = "---\nname: impeccable\n---\nthe human's own install\n";
+    writeFileSync(join(foreign, "SKILL.md"), body);
+    const r = await applyFrontDoorSetup({
+      agentRoot: f.agentRoot, sdkRoot: SDK_ROOT, claudeDir: f.claudeDir, claudeJsonPath: f.claudeJsonPath,
+      claudeBin: null, globalRoot: "", now: Date.parse("2026-09-08T12:00:00Z"), ...f.io,
+    });
+    assert.equal(readFileSync(join(foreign, "SKILL.md"), "utf8"), body, "untouched");
+    assert.deepEqual(r.vendorSkills.skipped.map((s) => s.name), ["impeccable"]);
+    assert.ok(f.logs.some((l) => l.startsWith("warn:") && /impeccable/.test(l) && /left alone/.test(l)));
+    assert.ok(r.vendorSkills.installed.includes("unlazy"), "the other packs still install");
+  } finally { rmSync(f.root, { recursive: true, force: true }); }
+});
+
+test("applyFrontDoorSetup: MAESTRO_SKIP_VENDOR_SKILLS keeps the packs off the machine and every other step on", async () => {
+  // ~/.claude/skills is global: these packs load for work in the product repo,
+  // in customer repos and in scratch directories that have nothing to do with
+  // Cohort design. A seat that does not want them needs a way to say so that
+  // does not cost it its identity block or its tools.
+  const f = fixture();
+  const prev = process.env.MAESTRO_SKIP_VENDOR_SKILLS;
+  process.env.MAESTRO_SKIP_VENDOR_SKILLS = "1";
+  try {
+    const r = await applyFrontDoorSetup({
+      agentRoot: f.agentRoot, sdkRoot: SDK_ROOT, claudeDir: f.claudeDir, claudeJsonPath: f.claudeJsonPath,
+      claudeBin: null, globalRoot: "", now: Date.parse("2026-09-08T12:00:00Z"), ...f.io,
+    });
+    assert.equal(r.vendorSkills.skippedByEnv, true);
+    assert.equal(existsSync(join(f.claudeDir, "skills", "impeccable")), false);
+    assert.equal(existsSync(join(f.claudeDir, "skills", "design-taste-frontend")), false);
+    assert.equal(r.ok, true);
+    assert.equal(r.identity.changed, true, "identity still wired");
+    assert.ok(existsSync(join(f.claudeDir, "skills", "maestro-cohort-design")), "maestro's own skills still install");
+  } finally {
+    if (prev === undefined) delete process.env.MAESTRO_SKIP_VENDOR_SKILLS;
+    else process.env.MAESTRO_SKIP_VENDOR_SKILLS = prev;
+    rmSync(f.root, { recursive: true, force: true });
+  }
+});
+
+test("applyFrontDoorSetup: an SDK copy with no vendored trees warns and still wires everything else", async () => {
+  const f = fixture();
+  try {
+    const r = await applyFrontDoorSetup({
+      agentRoot: f.agentRoot, sdkRoot: f.sdkRoot, claudeDir: f.claudeDir, claudeJsonPath: f.claudeJsonPath,
+      claudeBin: null, globalRoot: "", now: Date.parse("2026-09-08T12:00:00Z"), ...f.io,
+    });
+    assert.equal(r.ok, true, "a missing vendor tree is fail-open, not a failed setup");
+    assert.ok(r.vendorSkills.errors.length > 0);
+    assert.ok(f.logs.some((l) => l.startsWith("warn:") && /design pack/.test(l)));
+    assert.equal(r.identity.changed, true, "identity still wired");
+  } finally { rmSync(f.root, { recursive: true, force: true }); }
+});

package/lib/cli/session.mjs

@@ -65,6 +65,7 @@ import { writeJsonAtomic } from "../fs-atomic.mjs";
 import { resolveAgentRoot } from "../agent-root.mjs";
 import { resolveClaudeBin } from "../claude-bin.mjs";
 import { sessionPermissionArgs } from "../session-permissions.mjs";
+import { withParallelism } from "../prompts/parallelism.mjs";
 
 /** The SDK's own package.json version — what "installed" means for an upgrade notice. */
 function ownVersion() {
@@ -215,11 +216,20 @@ export function peerPermissionArgs({ env = process.env, allowedTools } = {}) {
  * CLI args for a spawned peer: `--name <first>-<slug>`, the interactive
  * permission posture ({@link peerPermissionArgs}), then the prompt. The binary
  * itself is prepended by the caller.
+ *
+ * THE PROMPT IS LED BY THE PARALLELISM DIRECTIVE (WP-M7 mechanic 5). A peer is
+ * spawned precisely when there is more work than one session can hold, so it is
+ * the one lane where "dispatch the independent tasks together" pays every time
+ * — and the directive carries the file-scope rule that makes that safe on a
+ * shared checkout. `withParallelism` is idempotent, so a caller that already
+ * led its prompt with it (a daemon prompt handed on to `session spawn`) does
+ * not get it twice; the peers registry still records the OPERATOR's prompt as
+ * the peer's purpose, not the directive.
  * @param {{first:string, slug:string, prompt:string, env?:object, allowedTools?:string[]}} o
  * @returns {string[]}
  */
 export function buildSpawnArgs({ first, slug, prompt, env, allowedTools }) {
-  return ["--name", `${first}-${slug}`, ...peerPermissionArgs({ env, allowedTools }), prompt];
+  return ["--name", `${first}-${slug}`, ...peerPermissionArgs({ env, allowedTools }), withParallelism(prompt)];
 }
 
 /**

package/lib/cli/session.test.mjs

@@ -21,6 +21,7 @@ import {
   run, usage, resolveFirstName, sessionLabel, muxSessionName, sessionPaths,
   heartbeatAgeMs, isLive, attachCommand, buildSpawnArgs, prunePeers, STALE_MS, updatePeers,
 } from "./session.mjs";
+import { withParallelism, countParallelism, PARALLELISM_DIRECTIVE } from "../prompts/parallelism.mjs";
 
 const NOW = Date.parse("2026-09-08T12:00:00Z");
 
@@ -108,12 +109,21 @@ test("attachCommand prints the exact tmux/screen attach line", () => {
   assert.deepEqual(attachCommand("ivy", "screen"), ["screen", "-r", "maestro-ivy"]);
 });
 
-test("buildSpawnArgs: claude --name <first>-<slug> + permission args + prompt", () => {
+test("buildSpawnArgs: claude --name <first>-<slug> + permission args + the prompt, led by the parallelism directive", () => {
   const prev = process.env.MAESTRO_SCOPED_PERMISSIONS;
   delete process.env.MAESTRO_SCOPED_PERMISSIONS;
   try {
+    // WP-M7 mechanic 5: a peer is spawned precisely when there is more work than
+    // one session can hold, so every peer prompt carries the standing permission
+    // to fan out — and the file-scope rule that makes fanning out safe.
     const a = buildSpawnArgs({ first: "ivy", slug: "research", prompt: "Look into X" });
-    assert.deepEqual(a, ["--name", "ivy-research", "--dangerously-skip-permissions", "Look into X"]);
+    assert.deepEqual(a, ["--name", "ivy-research", "--dangerously-skip-permissions", withParallelism("Look into X")]);
+    assert.equal(countParallelism(a[3]), 1);
+    assert.ok(a[3].startsWith(PARALLELISM_DIRECTIVE) && a[3].endsWith("Look into X"));
+
+    // Idempotent: a caller that already led its prompt with it is not doubled.
+    const b = buildSpawnArgs({ first: "ivy", slug: "research", prompt: withParallelism("Look into X") });
+    assert.deepEqual(b, a);
   } finally {
     if (prev === undefined) delete process.env.MAESTRO_SCOPED_PERMISSIONS; else process.env.MAESTRO_SCOPED_PERMISSIONS = prev;
   }
@@ -321,7 +331,7 @@ test("spawn launches a detached tmux session running claude --name <first>-<slug
     const spawnCall = d.exec.calls.find((c) => c[0] === "tmux" && c[1] === "new-session");
     assert.ok(spawnCall, `expected a tmux new-session; calls: ${JSON.stringify(d.exec.calls)}`);
     assert.deepEqual(spawnCall, ["tmux", "new-session", "-d", "-s", "maestro-ivy-research", "-c", root, "--",
-      "/stub/claude", "--name", "ivy-research", "--dangerously-skip-permissions", "Look into X"]);
+      "/stub/claude", "--name", "ivy-research", "--dangerously-skip-permissions", withParallelism("Look into X")]);
     const peers = JSON.parse(readFileSync(join(root, "state", "session", "peers.json"), "utf8"));
     assert.equal(peers.peers.length, 1);
     assert.equal(peers.peers[0].name, "ivy-research");
@@ -465,13 +475,14 @@ test("resolveFirstName falls back to config/agent.ts firstName (legacy seat) bef
 
 test("buildSpawnArgs: a peer is interactive — scoped mode uses the configured allowlist or bypass, never the read-only --print default", () => {
   const scoped = { MAESTRO_SCOPED_PERMISSIONS: "1" };
+  const p = withParallelism("p"); // the prompt as the peer actually receives it (WP-M7)
   assert.deepEqual(buildSpawnArgs({ first: "ivy", slug: "fix", prompt: "p", env: scoped }),
-    ["--name", "ivy-fix", "--dangerously-skip-permissions", "p"]);
+    ["--name", "ivy-fix", "--dangerously-skip-permissions", p]);
   assert.deepEqual(buildSpawnArgs({ first: "ivy", slug: "fix", prompt: "p", env: scoped, allowedTools: ["Read", " Edit ", "", "Bash"] }),
-    ["--name", "ivy-fix", "--allowedTools", "Read,Edit,Bash", "p"]);
+    ["--name", "ivy-fix", "--allowedTools", "Read,Edit,Bash", p]);
   // Unscoped: the allowlist is ignored (byte-for-byte the pre-H1 posture).
   assert.deepEqual(buildSpawnArgs({ first: "ivy", slug: "fix", prompt: "p", env: {}, allowedTools: ["Read"] }),
-    ["--name", "ivy-fix", "--dangerously-skip-permissions", "p"]);
+    ["--name", "ivy-fix", "--dangerously-skip-permissions", p]);
 });
 
 test("spawn honours config/session.yaml `mux:` (M1 loadSessionConfig) over tmux-on-PATH and MAESTRO_SESSION_MUX", async () => {

package/lib/collective/global-config.mjs

@@ -187,6 +187,11 @@ export function buildIdentityClaudeMd(agentJson, o = {}) {
     "  `maestro board track`, and close it with `maestro board complete`.",
     `- Skills: \`maestro-main-session\`, \`maestro-inbound-triage\`, \`maestro-board-work\`,`,
     "  `maestro-peer-sessions`, `maestro-persona-discipline` carry the operating rules.",
+    "- Design, redesign, polish, critique, audit or motion work on any interface: start from",
+    "  `maestro-cohort-design`. It sets the precedence — this agent's `DESIGN.md` and `PRODUCT.md`",
+    "  plus the `cohort` MCP `design_*` tools are the source of truth for tokens, type and voice;",
+    "  the vendored craft packs (`impeccable`, the motion skills, `design-taste-frontend` for",
+    "  marketing pages, `unlazy` for completion gates) sit under them.",
   ].join("\n");
 }
 

package/lib/collective/global-config.test.mjs

@@ -105,6 +105,11 @@ test("buildIdentityClaudeMd: names the agent, the seat, the main session and the
   assert.match(md, /board/i);
   // Persona rules are present and phrased as rules the agent follows outbound.
   assert.match(md, /never .*(assistant|session|sub-?agent)/i);
+  // Design work is routed to the harmoniser, which is what keeps the vendored
+  // craft skills from deciding the typeface (WP-M7).
+  assert.match(md, /maestro-cohort-design/);
+  assert.match(md, /DESIGN\.md/);
+  assert.match(md, /design_\*/);
   // The identity block is a different block from the collective one.
   assert.notEqual(IDENTITY_BEGIN, CLAUDE_MD_BEGIN);
 });

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,
+};