@cohortapp/agent-sdk 2.11.14 → 2.12.0

package/lib/collective/global-config.mjs

@@ -13,7 +13,7 @@
 
 "use strict";
 
-import { join } from "node:path";
+import { join, basename } from "node:path";
 
 /** Marker substring present in every collective hook command. */
 export const HOOK_MARKER = "scripts/collective/hook-runner.mjs";
@@ -83,17 +83,19 @@ export function buildCollectiveClaudeMd(repoRoot) {
 function escapeRe(s) { return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); }
 
 /**
- * Insert or replace the delimited collective block in a CLAUDE.md body. Only our
- * own block is touched; the rest of the file is preserved. Pure.
+ * Insert or replace ONE delimited block in a CLAUDE.md body. Only the block
+ * between `begin`/`end` is touched; everything else (including a sibling
+ * block with different markers) is preserved byte-for-byte. Pure.
  *
  * @param {string} content - existing file content ("" if absent)
  * @param {string} body - block body (without the delimiters)
+ * @param {{begin:string, end:string}} markers
  * @returns {{ content: string, changed: boolean }}
  */
-export function upsertClaudeMdBlock(content, body) {
-  const block = `${CLAUDE_MD_BEGIN}\n${body}\n${CLAUDE_MD_END}`;
+export function upsertDelimitedBlock(content, body, { begin, end }) {
+  const block = `${begin}\n${body}\n${end}`;
   const cur = content || "";
-  const re = new RegExp(escapeRe(CLAUDE_MD_BEGIN) + "[\\s\\S]*?" + escapeRe(CLAUDE_MD_END));
+  const re = new RegExp(escapeRe(begin) + "[\\s\\S]*?" + escapeRe(end));
   if (re.test(cur)) {
     const updated = cur.replace(re, block);
     return { content: updated, changed: updated !== cur };
@@ -102,6 +104,202 @@ export function upsertClaudeMdBlock(content, body) {
   return { content: prefix + block + "\n", changed: true };
 }
 
+/**
+ * Insert or replace the delimited collective block in a CLAUDE.md body. Only our
+ * own block is touched; the rest of the file is preserved. Pure.
+ *
+ * @param {string} content - existing file content ("" if absent)
+ * @param {string} body - block body (without the delimiters)
+ * @returns {{ content: string, changed: boolean }}
+ */
+export function upsertClaudeMdBlock(content, body) {
+  return upsertDelimitedBlock(content, body, { begin: CLAUDE_MD_BEGIN, end: CLAUDE_MD_END });
+}
+
+// ---------------------------------------------------------------------------
+// Front-door session (2026-09): the identity block, the MCP server entry and
+// the settings.json additions that make ANY Claude Code session on a seat
+// machine know who the agent is (design spec §3.7). All pure — the I/O is in
+// lib/cli/global-setup-extras.mjs.
+// ---------------------------------------------------------------------------
+
+export const IDENTITY_BEGIN = "<!-- BEGIN maestro:identity -->";
+export const IDENTITY_END = "<!-- END maestro:identity -->";
+
+/** Lower-case first name from an agent.json (firstName, else the first word of fullName). */
+export function agentFirst(agentJson) {
+  const a = agentJson && typeof agentJson === "object" ? agentJson : {};
+  const raw = String(a.firstName || String(a.fullName || "").split(/\s+/)[0] || "").trim();
+  return raw.toLowerCase().replace(/[^a-z0-9-]+/g, "");
+}
+
+/** Seat slug: agent.json repoSlug, else the agent directory's basename. */
+export function agentSlug(agentJson, agentRoot) {
+  const a = agentJson && typeof agentJson === "object" ? agentJson : {};
+  return String(a.repoSlug || basename(String(agentRoot || "")) || "").trim();
+}
+
+/**
+ * The identity block for ~/.claude/CLAUDE.md: who the agent is, where the
+ * agent dir is, that every session on the machine is the same entity, the
+ * persona rules in two lines, where the main session lives, the commands, and
+ * the board duty. Pure; tolerates a sparse agent.json (never prints
+ * "undefined").
+ *
+ * @param {object} agentJson - config/agent.json
+ * @param {{agentRoot:string, first?:string, slug?:string}} o
+ * @returns {string} block body (without delimiters)
+ */
+export function buildIdentityClaudeMd(agentJson, o = {}) {
+  const a = agentJson && typeof agentJson === "object" ? agentJson : {};
+  const agentRoot = String(o.agentRoot || "");
+  const first = o.first || agentFirst(a) || "agent";
+  const slug = o.slug || agentSlug(a, agentRoot) || first;
+  const name = String(a.fullName || a.firstName || "this machine's agent").trim();
+  const p = a.principal && typeof a.principal === "object" ? a.principal : {};
+  const who = [
+    `You are ${name}`,
+    a.title ? `, ${a.title}` : "",
+    a.company ? ` at ${a.company}` : "",
+    p.fullName ? `, reporting to ${p.fullName}${p.title ? ` (${p.title})` : ""}` : "",
+    ".",
+  ].join("");
+  return [
+    "## Who you are on this machine (Maestro)",
+    "",
+    `${who} Agent directory: \`${agentRoot}\` (seat \`${slug}\`); \`config/agent.json\` there is the`,
+    "record of you. You are the same entity in every session on this machine — one",
+    "person, one voice, whatever window or directory this is.",
+    "",
+    `- Persona: to anyone outside this terminal you are ${a.firstName || name}, a colleague — never an`,
+    "  assistant, an AI helper, a model, a tool, or a \"session\". Parallel work is \"my team\" /",
+    "  \"a colleague\" / \"one of my analysts\"; never name a session, a sub-session or a subagent.",
+    "- Asked sincerely whether you are an AI, say yes plainly. That is a direct answer to a direct",
+    "  question, not a disclaimer to attach to your work.",
+    `- The front door is the main session, \`${first}-main\` (\`ListAgents\` shows it; \`SendMessage\``,
+    "  reaches it). It receives every inbound Cohort event; peer sessions it spawns are named",
+    `  \`${first}-<purpose>\`. If you are a peer, report back to \`${first}-main\` when done.`,
+    "- Commands: `maestro session status|spawn|ack`, `maestro inbox list|show|claim|reply|done|defer`,",
+    "  `maestro board mine|track|claim|complete`. The `cohort` MCP server carries the same",
+    "  surface as tools (`board_mine`, `board_track`, `session_status`, `messaging_send`, ...).",
+    "- Board duty: every item assigned to you on any board is yours to pull. `maestro board mine`",
+    "  lists them; claim the highest-priority one when idle, track progress with",
+    "  `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.",
+  ].join("\n");
+}
+
+/**
+ * The user-scope MCP server entry for cohort-mcp, pinned to one agent dir.
+ * Default command is the bare `cohort-mcp` (the global npm install); a caller
+ * that knows it is not on PATH passes `{command, args}` (e.g. the current node
+ * + this package's bin/cohort-mcp.mjs) so the server still starts. Pure.
+ * @param {string} agentRoot @param {{command?:string, args?:string[]}} [o]
+ */
+export function cohortMcpEntry(agentRoot, o = {}) {
+  const command = o.command ? String(o.command) : "cohort-mcp";
+  const args = Array.isArray(o.args) ? o.args.map(String) : [];
+  return { command, args, env: { COHORT_AGENT_ROOT: String(agentRoot || "") } };
+}
+
+function clone(v) { return JSON.parse(JSON.stringify(v)); }
+function isObj(v) { return v && typeof v === "object" && !Array.isArray(v); }
+
+/**
+ * Merge the `cohort` server into a ~/.claude.json document's `mcpServers`.
+ * Other servers and every other key are preserved; an existing `cohort` entry
+ * is rewritten only when it differs (a stale agent root). Pure, never throws.
+ *
+ * @param {object} claudeJson
+ * @param {object} entry - cohortMcpEntry(agentRoot)
+ * @returns {{ config: object, changed: boolean }}
+ */
+export function mergeMcpServers(claudeJson, entry) {
+  const config = isObj(claudeJson) ? clone(claudeJson) : {};
+  if (!isObj(config.mcpServers)) config.mcpServers = {};
+  const cur = config.mcpServers.cohort;
+  const same = cur && JSON.stringify(cur) === JSON.stringify(entry);
+  if (same) return { config, changed: false };
+  config.mcpServers.cohort = clone(entry);
+  return { config, changed: true };
+}
+
+/** Substring present in the persona/audit PreToolUse hook command. */
+export const PRE_SEND_HOOK_MARKER = "scripts/hooks/pre-send-audit.sh";
+
+/**
+ * Every outbound-content tool of the `cohort` MCP server. The persona/audit
+ * hook fronts ALL of them — a perimeter that gated `messaging_send` alone was
+ * bypassable by tool choice (email_send, org_rpc {method:"messaging.send"}).
+ * Mirrors the `outbound:true` tools in lib/org/tool-surface.mjs plus the
+ * `org_rpc` escape hatch.
+ */
+export const PRE_SEND_HOOK_TOOLS = Object.freeze([
+  "messaging_send",
+  "messaging_send_voice_note",
+  "email_send",
+  "email_draft_send",
+  "org_rpc",
+]);
+
+/** The PreToolUse matcher (a Claude Code matcher is a regex) for those tools. */
+export const PRE_SEND_HOOK_MATCHER = `mcp__cohort__(${PRE_SEND_HOOK_TOOLS.join("|")})`;
+
+/** permissions.allow entries a front-door session needs. */
+export const SESSION_PERMISSION_ALLOW = Object.freeze([
+  "mcp__cohort",
+  "mcp__cohort__*",
+  "ListAgents",
+  "SendMessage",
+  "Monitor",
+  "Workflow",
+  "Agent",
+]);
+
+/**
+ * Merge the front-door additions into ~/.claude/settings.json:
+ * `crossSessionInbound:"accept"` (only when unset — an operator's explicit
+ * choice is respected), `permissions.allow` += SESSION_PERMISSION_ALLOW, and a
+ * `PreToolUse` group matching every outbound `mcp__cohort__*` tool
+ * ({@link PRE_SEND_HOOK_MATCHER}) that runs the persona + audit hook. Existing hooks/permissions are preserved; re-running
+ * changes nothing. Pure.
+ *
+ * @param {object} settings
+ * @param {{agentRoot:string}} o
+ * @returns {{ settings: object, changes: string[] }}
+ */
+export function mergeSessionSettings(settings, o = {}) {
+  const out = isObj(settings) ? clone(settings) : {};
+  const changes = [];
+  if (out.crossSessionInbound === undefined) {
+    out.crossSessionInbound = "accept";
+    changes.push("crossSessionInbound");
+  }
+  if (!isObj(out.permissions)) out.permissions = {};
+  if (!Array.isArray(out.permissions.allow)) out.permissions.allow = [];
+  for (const p of SESSION_PERMISSION_ALLOW) {
+    if (!out.permissions.allow.includes(p)) {
+      out.permissions.allow.push(p);
+      changes.push(`permissions.allow:${p}`);
+    }
+  }
+  if (!isObj(out.hooks)) out.hooks = {};
+  if (!Array.isArray(out.hooks.PreToolUse)) out.hooks.PreToolUse = [];
+  const present = out.hooks.PreToolUse.some((g) =>
+    g && g.matcher === PRE_SEND_HOOK_MATCHER && Array.isArray(g.hooks) &&
+    g.hooks.some((h) => h && typeof h.command === "string" && h.command.includes(PRE_SEND_HOOK_MARKER)));
+  if (!present) {
+    const script = join(String(o.agentRoot || ""), "scripts", "hooks", "pre-send-audit.sh");
+    out.hooks.PreToolUse.push({
+      matcher: PRE_SEND_HOOK_MATCHER,
+      hooks: [{ type: "command", command: `${q("bash")} ${q(script)} cohort` }],
+    });
+    changes.push("hooks.PreToolUse:pre-send-audit");
+  }
+  return { settings: out, changes };
+}
+
 /** Build the machine pointer object. */
 export function buildPointer(repoRoot, agentName, nowMs) {
   return {

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

@@ -73,3 +73,143 @@ test("buildPointer: shape", () => {
   assert.match(p.memoryRoot, /memory\/collective$/);
   assert.equal(p.updatedAt, "2026-06-03T00:00:00.000Z");
 });
+
+// ── WP-M4: identity block + MCP/settings mergers (front-door session, §3.7) ──
+
+import {
+  IDENTITY_BEGIN, IDENTITY_END, buildIdentityClaudeMd, upsertDelimitedBlock,
+  mergeMcpServers, mergeSessionSettings, cohortMcpEntry, PRE_SEND_HOOK_MARKER, PRE_SEND_HOOK_MATCHER,
+  SESSION_PERMISSION_ALLOW,
+} from "./global-config.mjs";
+
+const AGENT = {
+  firstName: "Alex", fullName: "Alex Rivera", title: "Chief of Staff", company: "Acme",
+  principal: { fullName: "Jordan Lee", title: "CEO", firstName: "Jordan" },
+  repoSlug: "alex-ai",
+};
+
+test("buildIdentityClaudeMd: names the agent, the seat, the main session and the commands", () => {
+  const md = buildIdentityClaudeMd(AGENT, { agentRoot: "/Users/x/alex-ai", first: "alex", slug: "alex-ai" });
+  assert.match(md, /Alex Rivera/);
+  assert.match(md, /Chief of Staff/);
+  assert.match(md, /Acme/);
+  assert.match(md, /Jordan Lee/);
+  assert.match(md, /\/Users\/x\/alex-ai/);
+  assert.match(md, /`alex-ai`/, "seat slug");
+  assert.match(md, /same entity in every session/i);
+  assert.match(md, /`alex-main`/, "main session name");
+  assert.match(md, /ListAgents/);
+  assert.match(md, /maestro session status\|spawn\|ack/);
+  assert.match(md, /maestro inbox/);
+  assert.match(md, /maestro board mine/);
+  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);
+  // The identity block is a different block from the collective one.
+  assert.notEqual(IDENTITY_BEGIN, CLAUDE_MD_BEGIN);
+});
+
+test("buildIdentityClaudeMd: derives first/slug when not given; tolerates a sparse agent.json", () => {
+  const md = buildIdentityClaudeMd({ fullName: "Robin Park" }, { agentRoot: "/home/r/robin-ai" });
+  assert.match(md, /Robin Park/);
+  assert.match(md, /`robin-main`/, "first derived from fullName");
+  assert.match(md, /`robin-ai`/, "slug derived from the agent dir basename");
+  const empty = buildIdentityClaudeMd({}, { agentRoot: "/home/r/robin-ai" });
+  assert.equal(typeof empty, "string");
+  assert.ok(empty.length > 50);
+  assert.doesNotMatch(empty, /undefined/);
+});
+
+test("upsertDelimitedBlock: identity + collective blocks coexist and are each idempotent", () => {
+  const coll = upsertClaudeMdBlock("# rules", buildCollectiveClaudeMd("/repo"));
+  const idBody = buildIdentityClaudeMd(AGENT, { agentRoot: "/repo" });
+  const r1 = upsertDelimitedBlock(coll.content, idBody, { begin: IDENTITY_BEGIN, end: IDENTITY_END });
+  assert.equal(r1.changed, true);
+  assert.match(r1.content, new RegExp(CLAUDE_MD_BEGIN), "collective block preserved");
+  assert.match(r1.content, new RegExp(IDENTITY_BEGIN));
+  const r2 = upsertDelimitedBlock(r1.content, idBody, { begin: IDENTITY_BEGIN, end: IDENTITY_END });
+  assert.equal(r2.changed, false, "idempotent");
+  const r3 = upsertDelimitedBlock(r1.content, "changed body", { begin: IDENTITY_BEGIN, end: IDENTITY_END });
+  assert.equal((r3.content.match(new RegExp(IDENTITY_BEGIN, "g")) || []).length, 1);
+  assert.match(r3.content, new RegExp(CLAUDE_MD_BEGIN), "collective block still there after identity update");
+});
+
+test("cohortMcpEntry + mergeMcpServers: adds cohort once, preserves other servers, updates a stale root", () => {
+  const entry = cohortMcpEntry("/Users/x/alex-ai");
+  assert.equal(entry.command, "cohort-mcp");
+  assert.deepEqual(entry.args, []);
+  assert.equal(entry.env.COHORT_AGENT_ROOT, "/Users/x/alex-ai");
+  const existing = { mcpServers: { other: { command: "x" } }, someOtherKey: 1 };
+  const m1 = mergeMcpServers(existing, entry);
+  assert.equal(m1.changed, true);
+  assert.deepEqual(m1.config.mcpServers.other, { command: "x" });
+  assert.deepEqual(m1.config.mcpServers.cohort, entry);
+  assert.equal(m1.config.someOtherKey, 1);
+  assert.deepEqual(existing.mcpServers, { other: { command: "x" } }, "input not mutated");
+  const m2 = mergeMcpServers(m1.config, entry);
+  assert.equal(m2.changed, false, "idempotent");
+  const m3 = mergeMcpServers(m1.config, cohortMcpEntry("/Users/x/other-ai"));
+  assert.equal(m3.changed, true, "a different agent root rewrites the entry");
+  assert.equal(m3.config.mcpServers.cohort.env.COHORT_AGENT_ROOT, "/Users/x/other-ai");
+  // Garbage in → a fresh object out, never a throw.
+  assert.equal(mergeMcpServers(null, entry).config.mcpServers.cohort.command, "cohort-mcp");
+  assert.equal(mergeMcpServers("nope", entry).config.mcpServers.cohort.command, "cohort-mcp");
+});
+
+test("mergeSessionSettings: crossSessionInbound + permissions.allow + PreToolUse persona hook, idempotent, additive", () => {
+  const settings = {
+    permissions: { allow: ["Bash(git status)"], deny: ["Bash(rm -rf /)"] },
+    hooks: { PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: "./mine.sh" }] }] },
+    theme: "dark",
+  };
+  const r1 = mergeSessionSettings(settings, { agentRoot: "/repo" });
+  assert.equal(r1.settings.crossSessionInbound, "accept");
+  assert.ok(r1.changes.includes("crossSessionInbound"));
+  for (const p of SESSION_PERMISSION_ALLOW) assert.ok(r1.settings.permissions.allow.includes(p), `allow ${p}`);
+  assert.ok(r1.settings.permissions.allow.includes("mcp__cohort__*"));
+  assert.ok(r1.settings.permissions.allow.includes("ListAgents"));
+  assert.ok(r1.settings.permissions.allow.includes("SendMessage"));
+  assert.ok(r1.settings.permissions.allow.includes("Monitor"));
+  assert.ok(r1.settings.permissions.allow.includes("Workflow"));
+  assert.ok(r1.settings.permissions.allow.includes("Agent"));
+  assert.ok(r1.settings.permissions.allow.includes("Bash(git status)"), "existing allow preserved");
+  assert.deepEqual(r1.settings.permissions.deny, ["Bash(rm -rf /)"], "deny untouched");
+  assert.equal(r1.settings.theme, "dark");
+  // PreToolUse: our matcher added, the operator's own group preserved.
+  const pre = r1.settings.hooks.PreToolUse;
+  assert.ok(pre.some((g) => g.matcher === "Bash" && g.hooks[0].command === "./mine.sh"));
+  const ours = pre.find((g) => g.matcher === PRE_SEND_HOOK_MATCHER);
+  assert.ok(ours, "persona hook group present");
+  // The matcher is a regex that fronts EVERY outbound tool, not messaging_send alone.
+  const matcherRe = new RegExp(`^${ours.matcher}$`);
+  for (const t of ["messaging_send", "messaging_send_voice_note", "email_send", "email_draft_send", "org_rpc"]) {
+    assert.ok(matcherRe.test(`mcp__cohort__${t}`), `matcher covers ${t}`);
+  }
+  assert.ok(!matcherRe.test("mcp__cohort__board_mine"), "reads are not fronted");
+  assert.ok(!matcherRe.test("mcp__cohort__messaging_send_extra"), "anchored");
+  assert.match(ours.hooks[0].command, new RegExp(PRE_SEND_HOOK_MARKER.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")));
+  assert.match(ours.hooks[0].command, /\/repo\/scripts\/hooks\/pre-send-audit\.sh/);
+  assert.match(ours.hooks[0].command, / cohort$/, "channel arg is cohort");
+  // Input not mutated.
+  assert.equal(settings.crossSessionInbound, undefined);
+  assert.equal(settings.permissions.allow.length, 1);
+  // Idempotent.
+  const r2 = mergeSessionSettings(r1.settings, { agentRoot: "/repo" });
+  assert.deepEqual(r2.changes, []);
+  assert.deepEqual(r2.settings, r1.settings);
+  // An operator who set crossSessionInbound to something else is respected (additive, never clobber).
+  const r3 = mergeSessionSettings({ crossSessionInbound: "reject" }, { agentRoot: "/repo" });
+  assert.equal(r3.settings.crossSessionInbound, "reject");
+  assert.ok(!r3.changes.includes("crossSessionInbound"));
+  // Garbage → fresh.
+  assert.equal(mergeSessionSettings(null, { agentRoot: "/repo" }).settings.crossSessionInbound, "accept");
+});
+
+test("cohortMcpEntry: a caller that knows cohort-mcp is off PATH pins command+args; the default stays the bare command", () => {
+  const local = cohortMcpEntry("/Users/x/alex-ai", { command: "/usr/local/bin/node", args: ["/sdk/bin/cohort-mcp.mjs"] });
+  assert.deepEqual(local, { command: "/usr/local/bin/node", args: ["/sdk/bin/cohort-mcp.mjs"], env: { COHORT_AGENT_ROOT: "/Users/x/alex-ai" } });
+  assert.equal(cohortMcpEntry("/r").command, "cohort-mcp");
+  assert.deepEqual(cohortMcpEntry("/r", {}).args, []);
+  // Switching from the local pin to the bare command is a change (so a re-run after `npm i -g` rewrites it).
+  assert.equal(mergeMcpServers({ mcpServers: { cohort: local } }, cohortMcpEntry("/Users/x/alex-ai")).changed, true);
+});

package/lib/collective/global-skills.mjs

@@ -0,0 +1,145 @@
+/**
+ * lib/collective/global-skills.mjs — install the shipped skills into
+ * ~/.claude/skills so ANY Claude Code session on the machine loads them.
+ *
+ * Every `plugins/maestro-skills/skills/<name>.md` becomes
+ * `~/.claude/skills/maestro-<name>/SKILL.md`: a symlink when the SDK is a
+ * global npm install (so `npm i -g` upgrades refresh them for free), a copy
+ * otherwise (a checkout or an agent-local node_modules can move or vanish).
+ *
+ * Shipped skills are TEMPLATES (`{{agent.firstName}}`, `{{company.name}}` —
+ * lib/render.mjs). Claude Code loads a SKILL.md verbatim, so a skill whose body
+ * carries tokens is rendered against the agent's identity (`context`) and
+ * COPIED — even under a global install, because a symlink cannot render.
+ * Token-free skills keep the symlink. Without a context the templates are
+ * installed verbatim (the pre-2.12 behaviour).
+ *
+ * Idempotent: an up-to-date copy or a link at the right target is left alone;
+ * a stale one (or a copy rendered for a previous identity) is replaced.
+ * `planSkillInstall` is the pure half; `installSkills` does the I/O and
+ * reports what it did. Nothing here throws.
+ *
+ * @module lib/collective/global-skills
+ */
+
+"use strict";
+
+import {
+  existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, lstatSync, readlinkSync, unlinkSync, symlinkSync, rmSync,
+} from "node:fs";
+import { join, sep } from "node:path";
+import { renderTemplate } from "../render.mjs";
+
+/** ~/.claude/skills/<prefix><name>/SKILL.md */
+export const GLOBAL_SKILL_PREFIX = "maestro-";
+
+/** Where the shipped skills live, relative to the SDK root. */
+export const SKILLS_REL = join("plugins", "maestro-skills", "skills");
+
+/**
+ * Is the SDK a global npm install? True when its root sits under the global
+ * `node_modules` (`npm root -g`). An agent-local `node_modules` or a checkout
+ * is not global — those get copies.
+ * @param {string} sdkRoot
+ * @param {{globalRoot?:string}} o - the output of `npm root -g` ("" when unknown)
+ */
+export function isGlobalInstall(sdkRoot, o = {}) {
+  const root = String(sdkRoot || "");
+  const g = String(o.globalRoot || "").replace(/[\\/]+$/, "");
+  if (!root || !g) return false;
+  return root === g || root.startsWith(g + sep);
+}
+
+/**
+ * Plan: which files go where. Pure.
+ * @param {string[]} fileNames - entries of the skills dir
+ * @param {{sdkRoot:string, skillsDir:string, mode:"symlink"|"copy"}} o
+ * @returns {Array<{name:string, src:string, dest:string, mode:string}>}
+ */
+export function planSkillInstall(fileNames, o = {}) {
+  const mode = o.mode === "symlink" ? "symlink" : "copy";
+  const out = [];
+  for (const f of Array.isArray(fileNames) ? fileNames : []) {
+    if (typeof f !== "string" || !f.endsWith(".md") || f.startsWith(".")) continue;
+    const name = f.slice(0, -3);
+    if (!name || /^readme$/i.test(name)) continue;
+    out.push({
+      name,
+      src: join(String(o.sdkRoot || ""), SKILLS_REL, f),
+      dest: join(String(o.skillsDir || ""), `${GLOBAL_SKILL_PREFIX}${name}`, "SKILL.md"),
+      mode,
+    });
+  }
+  return out;
+}
+
+function currentState(dest) {
+  try {
+    const st = lstatSync(dest);
+    if (st.isSymbolicLink()) return { kind: "symlink", target: readlinkSync(dest) };
+    if (st.isFile()) return { kind: "file", content: readFileSync(dest, "utf8") };
+    return { kind: "other" };
+  } catch {
+    return { kind: "absent" }; // ENOENT is the common case on first install
+  }
+}
+
+/**
+ * Render one skill body against the identity context. Pure. Returns the body
+ * and whether rendering changed it (→ must be a copy, never a link).
+ * @param {string} body @param {object|null|undefined} context
+ */
+export function renderSkill(body, context) {
+  const src = typeof body === "string" ? body : "";
+  if (!context || typeof context !== "object") return { body: src, rendered: false };
+  const out = renderTemplate(src, context);
+  return { body: out, rendered: out !== src };
+}
+
+/**
+ * Apply the plan. Returns {ok, installed[], unchanged[], rendered[], errors[], plan}.
+ * @param {{sdkRoot:string, skillsDir:string, mode:"symlink"|"copy", dryRun?:boolean, context?:object}} o
+ *   `context` — the lib/render `buildContext(agent, archetype, company)` shape;
+ *   when given, token-bearing skills are rendered and copied.
+ */
+export function installSkills(o = {}) {
+  const sdkRoot = String(o.sdkRoot || "");
+  const srcDir = join(sdkRoot, SKILLS_REL);
+  let names;
+  try {
+    names = readdirSync(srcDir);
+  } catch (err) {
+    return { ok: false, error: `no skills directory at ${srcDir}: ${err && err.message}`, installed: [], unchanged: [], rendered: [], errors: [], plan: [] };
+  }
+  const plan = planSkillInstall(names, { sdkRoot, skillsDir: o.skillsDir, mode: o.mode });
+  const installed = [];
+  const unchanged = [];
+  const rendered = [];
+  const errors = [];
+  for (const p of plan) {
+    try {
+      const raw = readFileSync(p.src, "utf8");
+      const r = renderSkill(raw, o.context);
+      // A rendered body cannot live behind a symlink: the link would show the template.
+      const mode = r.rendered ? "copy" : p.mode;
+      if (r.rendered) rendered.push(p.name);
+      const cur = currentState(p.dest);
+      if (mode === "symlink" && cur.kind === "symlink" && cur.target === p.src) { unchanged.push(p.name); continue; }
+      if (mode === "copy" && cur.kind === "file" && cur.content === r.body) { unchanged.push(p.name); continue; }
+      installed.push(p.name);
+      if (o.dryRun) continue;
+      mkdirSync(join(p.dest, ".."), { recursive: true });
+      if (cur.kind !== "absent") {
+        if (cur.kind === "other") rmSync(p.dest, { recursive: true, force: true });
+        else unlinkSync(p.dest);
+      }
+      if (mode === "symlink") symlinkSync(p.src, p.dest);
+      else writeFileSync(p.dest, r.body);
+    } catch (err) {
+      errors.push({ name: p.name, error: err && err.message ? err.message : String(err) });
+    }
+  }
+  return { ok: errors.length === 0, installed, unchanged, rendered, errors, plan };
+}
+
+export default { planSkillInstall, isGlobalInstall, installSkills, renderSkill, GLOBAL_SKILL_PREFIX, SKILLS_REL };

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

@@ -0,0 +1,126 @@
+/**
+ * global-skills.test.mjs — the skills-install plan for ~/.claude/skills.
+ * Run: node --test lib/collective/global-skills.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync, lstatSync, readlinkSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { planSkillInstall, isGlobalInstall, installSkills, GLOBAL_SKILL_PREFIX } from "./global-skills.mjs";
+
+test("isGlobalInstall: true under the global npm root (or a node_modules path outside the agent repo)", () => {
+  assert.equal(isGlobalInstall("/opt/homebrew/lib/node_modules/@cohortapp/agent-sdk", { globalRoot: "/opt/homebrew/lib/node_modules" }), true);
+  assert.equal(isGlobalInstall("/Users/a/alex-ai/node_modules/@cohortapp/agent-sdk", { globalRoot: "/opt/homebrew/lib/node_modules" }), false);
+  assert.equal(isGlobalInstall("/Users/a/maestro", { globalRoot: "/opt/homebrew/lib/node_modules" }), false);
+  assert.equal(isGlobalInstall("/Users/a/maestro", { globalRoot: "" }), false, "unknown global root → copy");
+  assert.equal(isGlobalInstall("", { globalRoot: "/x" }), false);
+});
+
+test("planSkillInstall: one maestro-<name>/SKILL.md per skill file, mode symlink|copy", () => {
+  const plan = planSkillInstall(["org-board.md", "main-session.md", "README.md", "notes.txt", ".hidden.md"], {
+    sdkRoot: "/sdk", skillsDir: "/home/.claude/skills", mode: "symlink",
+  });
+  assert.deepEqual(plan.map((p) => p.name), ["org-board", "main-session"], "README/non-md/hidden skipped");
+  assert.equal(plan[0].src, "/sdk/plugins/maestro-skills/skills/org-board.md");
+  assert.equal(plan[0].dest, `/home/.claude/skills/${GLOBAL_SKILL_PREFIX}org-board/SKILL.md`);
+  assert.equal(plan[0].mode, "symlink");
+  assert.equal(planSkillInstall(["a.md"], { sdkRoot: "/s", skillsDir: "/d", mode: "copy" })[0].mode, "copy");
+});
+
+test("installSkills: copy mode writes files, symlink mode links, both idempotent and refresh on re-run", () => {
+  const root = mkdtempSync(join(tmpdir(), "global-skills-"));
+  try {
+    const sdk = join(root, "sdk");
+    const skillsSrc = join(sdk, "plugins", "maestro-skills", "skills");
+    mkdirSync(skillsSrc, { recursive: true });
+    writeFileSync(join(skillsSrc, "main-session.md"), "---\nname: main-session\n---\nbody v1\n");
+    writeFileSync(join(skillsSrc, "board-work.md"), "---\nname: board-work\n---\nbw\n");
+    const skillsDir = join(root, "home", ".claude", "skills");
+
+    const r1 = installSkills({ sdkRoot: sdk, skillsDir, mode: "copy" });
+    assert.equal(r1.ok, true);
+    assert.deepEqual(r1.installed.sort(), ["board-work", "main-session"]);
+    assert.equal(r1.unchanged.length, 0);
+    assert.equal(readFileSync(join(skillsDir, "maestro-main-session", "SKILL.md"), "utf8"), "---\nname: main-session\n---\nbody v1\n");
+
+    const r2 = installSkills({ sdkRoot: sdk, skillsDir, mode: "copy" });
+    assert.equal(r2.installed.length, 0, "idempotent");
+    assert.equal(r2.unchanged.length, 2);
+
+    writeFileSync(join(skillsSrc, "main-session.md"), "---\nname: main-session\n---\nbody v2\n");
+    const r3 = installSkills({ sdkRoot: sdk, skillsDir, mode: "copy" });
+    assert.deepEqual(r3.installed, ["main-session"], "a changed source refreshes the copy");
+    assert.match(readFileSync(join(skillsDir, "maestro-main-session", "SKILL.md"), "utf8"), /body v2/);
+
+    // Switch to symlink mode: replaces the copy with a link, then no-ops.
+    const r4 = installSkills({ sdkRoot: sdk, skillsDir, mode: "symlink" });
+    assert.equal(r4.installed.length, 2);
+    const link = join(skillsDir, "maestro-board-work", "SKILL.md");
+    assert.ok(lstatSync(link).isSymbolicLink());
+    assert.equal(readlinkSync(link), join(skillsSrc, "board-work.md"));
+    const r5 = installSkills({ sdkRoot: sdk, skillsDir, mode: "symlink" });
+    assert.equal(r5.installed.length, 0);
+    assert.equal(r5.unchanged.length, 2);
+
+    // Dry run touches nothing.
+    rmSync(skillsDir, { recursive: true, force: true });
+    const dry = installSkills({ sdkRoot: sdk, skillsDir, mode: "copy", dryRun: true });
+    assert.equal(dry.installed.length, 2);
+    assert.equal(existsSync(skillsDir), false);
+
+    // Missing source dir → ok:false with a reason, never a throw.
+    const none = installSkills({ sdkRoot: join(root, "nope"), skillsDir, mode: "copy" });
+    assert.equal(none.ok, false);
+    assert.match(none.error, /skills/);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+// ── Review fix: {{agent.*}} tokens must be rendered for Claude-Code-loaded skills ─
+// Only the cadence consumer rendered templates; a skill installed into
+// ~/.claude/skills read "You are `{{agent.firstName}}`'s main session". A symlink
+// cannot render, so a token-bearing skill is rendered + COPIED even under a
+// global install; token-free skills keep the symlink.
+
+test("installSkills: with a render context, token-bearing skills are rendered and copied (even in symlink mode); token-free skills stay symlinks; a changed identity refreshes the copy", () => {
+  const root = mkdtempSync(join(tmpdir(), "global-skills-render-"));
+  try {
+    const sdk = join(root, "sdk");
+    const skillsSrc = join(sdk, "plugins", "maestro-skills", "skills");
+    mkdirSync(skillsSrc, { recursive: true });
+    writeFileSync(join(skillsSrc, "main-session.md"), "---\nname: main-session\n---\nYou are `{{agent.firstName}}`'s main session at {{company.name}}.\n");
+    writeFileSync(join(skillsSrc, "persona-discipline.md"), "---\nname: persona-discipline\n---\nYou are `{{agent.fullName}}`, `{{agent.title}}`. Unknown {{agent.nope}} stays.\n");
+    writeFileSync(join(skillsSrc, "board-work.md"), "---\nname: board-work\n---\nno tokens here\n");
+    const skillsDir = join(root, "home", ".claude", "skills");
+    const context = { agent: { firstName: "Alex", fullName: "Alex Rivera", title: "Chief of Staff" }, company: { name: "Acme" } };
+
+    const r1 = installSkills({ sdkRoot: sdk, skillsDir, mode: "symlink", context });
+    assert.equal(r1.ok, true);
+    assert.deepEqual(r1.installed.sort(), ["board-work", "main-session", "persona-discipline"]);
+    assert.deepEqual(r1.rendered.sort(), ["main-session", "persona-discipline"], "the token-bearing skills are reported as rendered");
+    const main = join(skillsDir, "maestro-main-session", "SKILL.md");
+    assert.equal(lstatSync(main).isSymbolicLink(), false, "rendered → a real file, never a link");
+    assert.equal(readFileSync(main, "utf8"), "---\nname: main-session\n---\nYou are `Alex`'s main session at Acme.\n");
+    assert.match(readFileSync(join(skillsDir, "maestro-persona-discipline", "SKILL.md"), "utf8"), /You are `Alex Rivera`, `Chief of Staff`\. Unknown \{\{agent\.nope\}\} stays\./);
+    assert.ok(lstatSync(join(skillsDir, "maestro-board-work", "SKILL.md")).isSymbolicLink(), "token-free → symlink");
+
+    const r2 = installSkills({ sdkRoot: sdk, skillsDir, mode: "symlink", context });
+    assert.equal(r2.installed.length, 0, "idempotent against the RENDERED content");
+    assert.equal(r2.unchanged.length, 3);
+
+    const r3 = installSkills({ sdkRoot: sdk, skillsDir, mode: "symlink", context: { agent: { firstName: "Robin", fullName: "Robin Park", title: "COO" }, company: { name: "Acme" } } });
+    assert.deepEqual(r3.installed.sort(), ["main-session", "persona-discipline"], "a new identity refreshes exactly the rendered skills");
+    assert.match(readFileSync(main, "utf8"), /`Robin`'s main session/);
+
+    // Copy mode renders too; no context → raw copy (previous behaviour).
+    const r4 = installSkills({ sdkRoot: sdk, skillsDir, mode: "copy", context });
+    assert.match(readFileSync(main, "utf8"), /`Alex`'s main session/);
+    assert.deepEqual(r4.rendered.sort(), ["main-session", "persona-discipline"]);
+    const r5 = installSkills({ sdkRoot: sdk, skillsDir, mode: "copy" });
+    assert.match(readFileSync(main, "utf8"), /\{\{agent\.firstName\}\}/, "no context → template left verbatim");
+    assert.deepEqual(r5.rendered, []);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});