@cohortapp/agent-sdk 2.11.15 → 2.13.0

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

@@ -0,0 +1,462 @@
+/**
+ * global-setup-extras.test.mjs — the front-door half of `maestro global-setup`.
+ * Run: node --test lib/cli/global-setup-extras.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync, existsSync, readdirSync, lstatSync, statSync, chmodSync } from "node:fs";
+import { tmpdir } from "node:os";
+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-"));
+  const agentRoot = join(root, "alex-ai");
+  mkdirSync(join(agentRoot, "config"), { recursive: true });
+  writeFileSync(join(agentRoot, "config", "agent.json"), JSON.stringify({ firstName: "Alex", fullName: "Alex Rivera", title: "Chief of Staff", company: "Acme", repoSlug: "alex-ai" }));
+  const sdkRoot = join(root, "sdk");
+  mkdirSync(join(sdkRoot, "plugins", "maestro-skills", "skills"), { recursive: true });
+  writeFileSync(join(sdkRoot, "plugins", "maestro-skills", "skills", "main-session.md"), "---\nname: main-session\n---\nbody\n");
+  const claudeDir = join(root, "home", ".claude");
+  mkdirSync(claudeDir, { recursive: true });
+  const claudeJsonPath = join(root, "home", ".claude.json");
+  const logs = [];
+  const io = { log: (m) => logs.push(`log:${m}`), ok: (m) => logs.push(`ok:${m}`), warn: (m) => logs.push(`warn:${m}`) };
+  return { root, agentRoot, sdkRoot, claudeDir, claudeJsonPath, logs, io };
+}
+
+test("applyFrontDoorSetup: identity block, JSON-merged MCP entry (no claude CLI), settings, skills copy — then a no-op re-run", async () => {
+  const f = fixture();
+  try {
+    writeFileSync(join(f.claudeDir, "CLAUDE.md"), `# mine\n\n${CLAUDE_MD_BEGIN}\nold collective\n<!-- END maestro:collective -->\n`);
+    writeFileSync(join(f.claudeDir, "settings.json"), JSON.stringify({ permissions: { allow: ["Bash(ls)"] }, hooks: { Stop: [] } }));
+    writeFileSync(f.claudeJsonPath, JSON.stringify({ mcpServers: { other: { command: "x" } }, oauthAccount: { id: "keep" } }));
+    const execCalls = [];
+    const r = await applyFrontDoorSetup({
+      agentRoot: f.agentRoot, sdkRoot: f.sdkRoot, claudeDir: f.claudeDir, claudeJsonPath: f.claudeJsonPath,
+      execImpl: (bin, args) => { execCalls.push({ bin, args }); return { status: 1, stderr: "no such command" }; },
+      claudeBin: null, globalRoot: "/opt/homebrew/lib/node_modules", now: Date.parse("2026-09-08T12:00:00Z"), ...f.io,
+    });
+    assert.equal(r.ok, true);
+    // 1) identity block written, collective block preserved.
+    const md = readFileSync(join(f.claudeDir, "CLAUDE.md"), "utf8");
+    assert.match(md, /# mine/);
+    assert.match(md, /old collective/);
+    assert.match(md, new RegExp(IDENTITY_BEGIN));
+    assert.match(md, /Alex Rivera/);
+    assert.equal(r.identity.changed, true);
+    // 2) MCP entry merged via JSON (no CLI available → not even attempted).
+    assert.equal(execCalls.length, 0, "claudeBin:null → no CLI attempt");
+    const cj = JSON.parse(readFileSync(f.claudeJsonPath, "utf8"));
+    assert.deepEqual(cj.mcpServers.other, { command: "x" });
+    assert.equal(cj.mcpServers.cohort.command, "cohort-mcp");
+    assert.equal(cj.mcpServers.cohort.env.COHORT_AGENT_ROOT, f.agentRoot);
+    assert.deepEqual(cj.oauthAccount, { id: "keep" });
+    assert.equal(r.mcp.via, "json");
+    assert.ok(readdirSync(join(f.root, "home")).some((n) => n.startsWith(".claude.json.backup.")), "timestamped backup of ~/.claude.json");
+    // 3) settings merged with backup.
+    const st = JSON.parse(readFileSync(join(f.claudeDir, "settings.json"), "utf8"));
+    assert.equal(st.crossSessionInbound, "accept");
+    assert.ok(st.permissions.allow.includes("Bash(ls)"));
+    assert.ok(st.permissions.allow.includes("mcp__cohort__*"));
+    assert.ok(st.hooks.PreToolUse.some((g) => g.matcher === PRE_SEND_HOOK_MATCHER && /messaging_send\|/.test(g.matcher)));
+    assert.deepEqual(st.hooks.Stop, []);
+    assert.ok(readdirSync(f.claudeDir).some((n) => n.startsWith("settings.json.backup.")), "timestamped backup of settings.json");
+    assert.ok(r.settings.changes.length > 0);
+    // 4) skills copied (sdk is not under the global root).
+    assert.equal(r.skills.mode, "copy");
+    const skill = join(f.claudeDir, "skills", "maestro-main-session", "SKILL.md");
+    assert.ok(existsSync(skill));
+    assert.equal(lstatSync(skill).isSymbolicLink(), false);
+    assert.deepEqual(r.skills.installed, ["main-session"]);
+
+    // Re-run: nothing changes, no new backups.
+    const backupsBefore = readdirSync(f.claudeDir).filter((n) => n.includes(".backup.")).length;
+    const r2 = await applyFrontDoorSetup({
+      agentRoot: f.agentRoot, sdkRoot: f.sdkRoot, claudeDir: f.claudeDir, claudeJsonPath: f.claudeJsonPath,
+      execImpl: () => ({ status: 1 }), claudeBin: null, globalRoot: "/opt/homebrew/lib/node_modules", now: Date.parse("2026-09-08T12:05:00Z"), ...f.io,
+    });
+    assert.equal(r2.ok, true);
+    assert.equal(r2.identity.changed, false);
+    assert.equal(r2.mcp.changed, false);
+    assert.deepEqual(r2.settings.changes, []);
+    assert.deepEqual(r2.skills.installed, []);
+    assert.equal(readdirSync(f.claudeDir).filter((n) => n.includes(".backup.")).length, backupsBefore, "idempotent: no new backups");
+  } finally { rmSync(f.root, { recursive: true, force: true }); }
+});
+
+test("applyFrontDoorSetup: uses `claude mcp add-json --scope user` when the CLI is available and it succeeds; symlinks skills for a global install", async () => {
+  const f = fixture();
+  try {
+    const globalRoot = join(f.root, "global", "node_modules");
+    const sdkRoot = join(globalRoot, "@cohortapp", "agent-sdk");
+    mkdirSync(join(sdkRoot, "plugins", "maestro-skills", "skills"), { recursive: true });
+    writeFileSync(join(sdkRoot, "plugins", "maestro-skills", "skills", "board-work.md"), "---\nname: board-work\n---\nbw\n");
+    const execCalls = [];
+    const r = await applyFrontDoorSetup({
+      agentRoot: f.agentRoot, sdkRoot, claudeDir: f.claudeDir, claudeJsonPath: f.claudeJsonPath,
+      claudeBin: "/fake/claude",
+      execImpl: (bin, args) => {
+        execCalls.push({ bin, args });
+        // Emulate the CLI writing the user-scope entry.
+        const cur = existsSync(f.claudeJsonPath) ? JSON.parse(readFileSync(f.claudeJsonPath, "utf8")) : {};
+        cur.mcpServers = { ...(cur.mcpServers || {}), [args[2]]: JSON.parse(args[3]) };
+        writeFileSync(f.claudeJsonPath, JSON.stringify(cur));
+        return { status: 0, stdout: "Added stdio MCP server cohort" };
+      },
+      globalRoot, now: Date.parse("2026-09-08T12:00:00Z"), ...f.io,
+    });
+    assert.equal(r.ok, true);
+    assert.equal(execCalls.length, 1);
+    assert.equal(execCalls[0].bin, "/fake/claude");
+    assert.deepEqual(execCalls[0].args.slice(0, 3), ["mcp", "add-json", "cohort"]);
+    assert.ok(execCalls[0].args.includes("--scope") && execCalls[0].args.includes("user"));
+    assert.equal(JSON.parse(execCalls[0].args[3]).env.COHORT_AGENT_ROOT, f.agentRoot);
+    assert.equal(r.mcp.via, "cli");
+    assert.equal(r.mcp.changed, true);
+    const cj = JSON.parse(readFileSync(f.claudeJsonPath, "utf8"));
+    assert.equal(cj.mcpServers.cohort.command, "cohort-mcp");
+    // Skills: symlink for a global install.
+    assert.equal(r.skills.mode, "symlink");
+    assert.ok(lstatSync(join(f.claudeDir, "skills", "maestro-board-work", "SKILL.md")).isSymbolicLink());
+    // Settings created from scratch when absent.
+    const st = JSON.parse(readFileSync(join(f.claudeDir, "settings.json"), "utf8"));
+    assert.equal(st.crossSessionInbound, "accept");
+  } finally { rmSync(f.root, { recursive: true, force: true }); }
+});
+
+test("applyFrontDoorSetup: CLI failure falls back to the JSON merge; dry-run writes nothing", async () => {
+  const f = fixture();
+  try {
+    const r = await applyFrontDoorSetup({
+      agentRoot: f.agentRoot, sdkRoot: f.sdkRoot, claudeDir: f.claudeDir, claudeJsonPath: f.claudeJsonPath,
+      claudeBin: "/fake/claude", execImpl: () => { throw new Error("spawn ENOENT"); },
+      globalRoot: "", now: Date.parse("2026-09-08T12:00:00Z"), ...f.io,
+    });
+    assert.equal(r.ok, true);
+    assert.equal(r.mcp.via, "json", "a throwing CLI is survivable");
+    assert.equal(JSON.parse(readFileSync(f.claudeJsonPath, "utf8")).mcpServers.cohort.command, "cohort-mcp");
+
+    const g = fixture();
+    try {
+      const d = await applyFrontDoorSetup({
+        agentRoot: g.agentRoot, sdkRoot: g.sdkRoot, claudeDir: g.claudeDir, claudeJsonPath: g.claudeJsonPath,
+        claudeBin: null, execImpl: () => ({ status: 1 }), globalRoot: "", dryRun: true, now: Date.parse("2026-09-08T12:00:00Z"), ...g.io,
+      });
+      assert.equal(d.ok, true);
+      assert.equal(d.identity.changed, true, "reports what it WOULD do");
+      assert.equal(existsSync(join(g.claudeDir, "CLAUDE.md")), false);
+      assert.equal(existsSync(join(g.claudeDir, "settings.json")), false);
+      assert.equal(existsSync(g.claudeJsonPath), false);
+      assert.equal(existsSync(join(g.claudeDir, "skills")), false);
+    } finally { rmSync(g.root, { recursive: true, force: true }); }
+  } finally { rmSync(f.root, { recursive: true, force: true }); }
+});
+
+test("applyFrontDoorSetup: a repo with no agent.json still wires MCP/settings/skills and skips the identity block with a warning", async () => {
+  const f = fixture();
+  try {
+    rmSync(join(f.agentRoot, "config", "agent.json"));
+    const r = await applyFrontDoorSetup({
+      agentRoot: f.agentRoot, sdkRoot: f.sdkRoot, claudeDir: f.claudeDir, claudeJsonPath: f.claudeJsonPath,
+      claudeBin: null, execImpl: () => ({ status: 1 }), globalRoot: "", now: Date.parse("2026-09-08T12:00:00Z"), ...f.io,
+    });
+    assert.equal(r.ok, true);
+    assert.equal(r.identity.changed, false);
+    assert.equal(r.identity.skipped, true);
+    assert.ok(f.logs.some((l) => l.startsWith("warn:") && /identity/i.test(l)));
+    assert.equal(JSON.parse(readFileSync(f.claudeJsonPath, "utf8")).mcpServers.cohort.command, "cohort-mcp");
+  } finally { rmSync(f.root, { recursive: true, force: true }); }
+});
+
+// ── Review fixes (2026-09-08): never clobber a state file we could not parse ─
+
+test("applyFrontDoorSetup: an unparseable ~/.claude.json or settings.json is left byte-for-byte alone (warned, skipped) — never replaced with a fresh {}", async () => {
+  const f = fixture();
+  try {
+    const garbage = "{\"oauthAccount\":{\"id\":\"keep\"},\"projects\":{} trailing-garbage";
+    writeFileSync(f.claudeJsonPath, garbage);
+    const badSettings = "{ hooks: [ not json";
+    writeFileSync(join(f.claudeDir, "settings.json"), badSettings);
+    const execCalls = [];
+    const r = await applyFrontDoorSetup({
+      agentRoot: f.agentRoot, sdkRoot: f.sdkRoot, claudeDir: f.claudeDir, claudeJsonPath: f.claudeJsonPath,
+      claudeBin: "/fake/claude", execImpl: (bin, args) => { execCalls.push(args); return { status: 0 }; },
+      globalRoot: "", now: Date.parse("2026-09-08T12:00:00Z"), ...f.io,
+    });
+    assert.equal(readFileSync(f.claudeJsonPath, "utf8"), garbage, "~/.claude.json untouched");
+    assert.equal(readFileSync(join(f.claudeDir, "settings.json"), "utf8"), badSettings, "settings.json untouched");
+    assert.equal(execCalls.length, 0, "the CLI is not asked to rewrite a file we cannot read back");
+    assert.equal(r.mcp.skipped, "unparseable");
+    assert.equal(r.settings.skipped, "unparseable");
+    assert.equal(r.ok, false, "a skipped step is reported, not hidden");
+    assert.ok(f.logs.some((l) => l.startsWith("warn:") && /\.claude\.json/.test(l) && /parse/i.test(l)));
+    assert.ok(f.logs.some((l) => l.startsWith("warn:") && /settings\.json/.test(l) && /parse/i.test(l)));
+    assert.equal(readdirSync(join(f.root, "home")).filter((n) => n.startsWith(".claude.json.backup.")).length, 0, "no backup of a file we did not write");
+    // The other steps still ran.
+    assert.equal(r.identity.changed, true);
+    assert.deepEqual(r.skills.installed, ["main-session"]);
+  } finally { rmSync(f.root, { recursive: true, force: true }); }
+});
+
+test("applyFrontDoorSetup: the JSON merge keeps the file's mode (0600 stays 0600); a fresh ~/.claude.json is created 0600", async () => {
+  const f = fixture();
+  try {
+    writeFileSync(f.claudeJsonPath, JSON.stringify({ oauthAccount: { id: "x" } }), { mode: 0o600 });
+    chmodSync(f.claudeJsonPath, 0o600);
+    writeFileSync(join(f.claudeDir, "settings.json"), "{}", { mode: 0o640 });
+    chmodSync(join(f.claudeDir, "settings.json"), 0o640);
+    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(statSync(f.claudeJsonPath).mode & 0o777, 0o600);
+    assert.equal(statSync(join(f.claudeDir, "settings.json")).mode & 0o777, 0o640);
+    assert.equal(JSON.parse(readFileSync(f.claudeJsonPath, "utf8")).mcpServers.cohort.command, "cohort-mcp");
+
+    const g = fixture();
+    try {
+      await applyFrontDoorSetup({
+        agentRoot: g.agentRoot, sdkRoot: g.sdkRoot, claudeDir: g.claudeDir, claudeJsonPath: g.claudeJsonPath,
+        claudeBin: null, globalRoot: "", now: Date.parse("2026-09-08T12:00:00Z"), ...g.io,
+      });
+      assert.equal(statSync(g.claudeJsonPath).mode & 0o777, 0o600, "a new ~/.claude.json is private: it will carry oauthAccount");
+    } finally { rmSync(g.root, { recursive: true, force: true }); }
+  } finally { rmSync(f.root, { recursive: true, force: true }); }
+});
+
+test("mergeJsonFileAtomic: a concurrent rewrite between read and publish is re-merged, never lost", () => {
+  const root = mkdtempSync(join(tmpdir(), "gs-merge-"));
+  try {
+    const p = join(root, "state.json");
+    writeFileSync(p, JSON.stringify({ numStartups: 1, projects: {} }));
+    let calls = 0;
+    const r = mergeJsonFileAtomic(p, (cur) => {
+      calls += 1;
+      if (calls === 1) {
+        // Another process (an interactive claude) rewrites the file while we merge.
+        writeFileSync(p, JSON.stringify({ numStartups: 2, projects: { "/x": { trust: true } } }));
+      }
+      return { config: { ...cur, mcpServers: { cohort: { command: "cohort-mcp" } } }, changed: true };
+    });
+    assert.equal(r.ok, true);
+    assert.equal(r.attempts, 2, "first attempt detected the concurrent write and retried");
+    const final = JSON.parse(readFileSync(p, "utf8"));
+    assert.equal(final.numStartups, 2, "the other writer's update survived");
+    assert.deepEqual(final.projects, { "/x": { trust: true } });
+    assert.equal(final.mcpServers.cohort.command, "cohort-mcp", "ours landed too");
+    // Unparseable → refuses, untouched.
+    writeFileSync(p, "nope{");
+    const bad = mergeJsonFileAtomic(p, () => ({ config: {}, changed: true }));
+    assert.equal(bad.ok, false);
+    assert.equal(bad.reason, "unparseable");
+    assert.equal(readFileSync(p, "utf8"), "nope{");
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("pickClaudeBin / findOnPath: a bare `claude` from the resolver is looked up on PATH instead of being discarded", () => {
+  const root = mkdtempSync(join(tmpdir(), "gs-path-"));
+  try {
+    const bin = join(root, "nvm", "bin");
+    mkdirSync(bin, { recursive: true });
+    writeFileSync(join(bin, "claude"), "#!/bin/sh\n", { mode: 0o755 });
+    const pathEnv = `${join(root, "empty")}:${bin}`;
+    assert.equal(findOnPath("claude", pathEnv), join(bin, "claude"));
+    assert.equal(findOnPath("claude", join(root, "empty")), null);
+    assert.equal(findOnPath("claude", ""), null);
+    assert.equal(pickClaudeBin("claude", { pathEnv }), join(bin, "claude"), "bare name → PATH lookup");
+    assert.equal(pickClaudeBin("claude", { pathEnv: "" }), null, "not on PATH → null (JSON merge path)");
+    assert.equal(pickClaudeBin(join(bin, "claude"), { pathEnv: "" }), join(bin, "claude"), "absolute + exists → itself");
+    assert.equal(pickClaudeBin(join(root, "missing", "claude"), { pathEnv }), null, "absolute + missing → null");
+    assert.equal(pickClaudeBin("", { pathEnv }), null);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("applyFrontDoorSetup: when `cohort-mcp` is not on PATH the MCP entry runs the SDK's own bin under the current node (a 2.11 seat without a global install still gets a working server)", async () => {
+  const f = fixture();
+  try {
+    mkdirSync(join(f.sdkRoot, "bin"), { recursive: true });
+    writeFileSync(join(f.sdkRoot, "bin", "cohort-mcp.mjs"), "// stub\n");
+    const r = await applyFrontDoorSetup({
+      agentRoot: f.agentRoot, sdkRoot: f.sdkRoot, claudeDir: f.claudeDir, claudeJsonPath: f.claudeJsonPath,
+      claudeBin: null, globalRoot: "", pathEnv: join(f.root, "nothing-here"), now: Date.parse("2026-09-08T12:00:00Z"), ...f.io,
+    });
+    assert.equal(r.ok, true);
+    const cj = JSON.parse(readFileSync(f.claudeJsonPath, "utf8"));
+    assert.equal(cj.mcpServers.cohort.command, process.execPath);
+    assert.deepEqual(cj.mcpServers.cohort.args, [join(f.sdkRoot, "bin", "cohort-mcp.mjs")]);
+    assert.equal(cj.mcpServers.cohort.env.COHORT_AGENT_ROOT, f.agentRoot);
+    assert.ok(f.logs.some((l) => /not on PATH/.test(l)), "says why the entry is not the bare command");
+
+    // Once the global install lands (cohort-mcp on PATH), a re-run rewrites to the bare command.
+    const bin = join(f.root, "gbin");
+    mkdirSync(bin, { recursive: true });
+    writeFileSync(join(bin, "cohort-mcp"), "#!/bin/sh\n", { mode: 0o755 });
+    const r2 = await applyFrontDoorSetup({
+      agentRoot: f.agentRoot, sdkRoot: f.sdkRoot, claudeDir: f.claudeDir, claudeJsonPath: f.claudeJsonPath,
+      claudeBin: null, globalRoot: "", pathEnv: bin, now: Date.parse("2026-09-08T12:10:00Z"), ...f.io,
+    });
+    assert.equal(r2.mcp.changed, true);
+    const cj2 = JSON.parse(readFileSync(f.claudeJsonPath, "utf8"));
+    assert.equal(cj2.mcpServers.cohort.command, "cohort-mcp");
+    assert.deepEqual(cj2.mcpServers.cohort.args, []);
+  } finally { rmSync(f.root, { recursive: true, force: true }); }
+});
+
+test("applyFrontDoorSetup: warns when the agent's pre-send-audit.sh predates the persona gate (upgrade keeps locally modified copies), and when it is missing", async () => {
+  const f = fixture();
+  try {
+    const hooks = join(f.agentRoot, "scripts", "hooks");
+    mkdirSync(hooks, { recursive: true });
+    writeFileSync(join(hooks, "pre-send-audit.sh"), "#!/bin/bash\nBANNED_SUBSTRINGS=(\"As an AI\")\nexit 0\n");
+    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.settings.hookScript.present, true);
+    assert.equal(r.settings.hookScript.personaGate, false);
+    assert.ok(f.logs.some((l) => l.startsWith("warn:") && /no persona gate/.test(l) && /pre-send-audit\.sh/.test(l)));
+    assert.equal(checkPersonaHookScript(f.agentRoot).personaGate, false);
+
+    writeFileSync(join(hooks, "pre-send-audit.sh"), "#!/bin/bash\nPERSONA_PATTERNS=('sub-sessions?')\nexit 0\n");
+    assert.equal(checkPersonaHookScript(f.agentRoot).personaGate, true);
+    f.logs.length = 0;
+    await applyFrontDoorSetup({
+      agentRoot: f.agentRoot, sdkRoot: f.sdkRoot, claudeDir: f.claudeDir, claudeJsonPath: f.claudeJsonPath,
+      claudeBin: null, globalRoot: "", now: Date.parse("2026-09-08T12:01:00Z"), ...f.io,
+    });
+    assert.ok(!f.logs.some((l) => /persona gate/.test(l) || /pre-send-audit\.sh is missing/.test(l)), "no warning once the gate is present");
+
+    rmSync(join(hooks, "pre-send-audit.sh"));
+    assert.deepEqual(checkPersonaHookScript(f.agentRoot).present, false);
+    f.logs.length = 0;
+    await applyFrontDoorSetup({
+      agentRoot: f.agentRoot, sdkRoot: f.sdkRoot, claudeDir: f.claudeDir, claudeJsonPath: f.claudeJsonPath,
+      claudeBin: null, globalRoot: "", now: Date.parse("2026-09-08T12:02:00Z"), ...f.io,
+    });
+    assert.ok(f.logs.some((l) => l.startsWith("warn:") && /is missing/.test(l)));
+  } finally { rmSync(f.root, { recursive: true, force: true }); }
+});
+
+test("applyFrontDoorSetup: skills are rendered to the agent's identity (config/agent.json + config/company.json) — a global install still symlinks token-free skills", async () => {
+  const f = fixture();
+  try {
+    const globalRoot = join(f.root, "global", "node_modules");
+    const sdkRoot = join(globalRoot, "@cohortapp", "agent-sdk");
+    const src = join(sdkRoot, "plugins", "maestro-skills", "skills");
+    mkdirSync(src, { recursive: true });
+    writeFileSync(join(src, "main-session.md"), "---\nname: main-session\n---\nYou are `{{agent.firstName}}`'s main session; {{agent.fullName}}, {{agent.title}} at {{company.name}}.\n");
+    writeFileSync(join(src, "board-work.md"), "---\nname: board-work\n---\nplain\n");
+    writeFileSync(join(f.agentRoot, "config", "company.json"), JSON.stringify({ name: "Acme Corp" }));
+    const r = await applyFrontDoorSetup({
+      agentRoot: f.agentRoot, sdkRoot, claudeDir: f.claudeDir, claudeJsonPath: f.claudeJsonPath,
+      claudeBin: null, globalRoot, now: Date.parse("2026-09-08T12:00:00Z"), ...f.io,
+    });
+    assert.equal(r.skills.mode, "symlink");
+    assert.deepEqual(r.skills.rendered, ["main-session"]);
+    const main = join(f.claudeDir, "skills", "maestro-main-session", "SKILL.md");
+    assert.equal(lstatSync(main).isSymbolicLink(), false);
+    assert.match(readFileSync(main, "utf8"), /You are `Alex`'s main session; Alex Rivera, Chief of Staff at Acme Corp\./);
+    assert.ok(lstatSync(join(f.claudeDir, "skills", "maestro-board-work", "SKILL.md")).isSymbolicLink());
+    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 }); }
+});