@jaybeeuu/agent-cortex 1.42.0 → 2.0.0

package/extensions/subagent/agents.test.ts

@@ -0,0 +1,176 @@
+/**
+ * Subagent agent discovery — the directories the "user" scope reads.
+ *
+ * pi has no agent resource type: agents ship beside the extensions that serve
+ * them, so user-scope discovery covers pi's own user agent dir (hand-written
+ * personal agents, plus copies older installers made) and the package this
+ * extension ships inside. `agent-cortex install pi` renders the flat pi agents
+ * into `<package>/agents`; a source checkout keeps its composable tree there
+ * instead, plus flat renders for other harnesses, which are not pi's agents.
+ */
+
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { describe, it } from "node:test";
+import { fileURLToPath } from "node:url";
+import { discoverAgents, loadUserAgents, parseToolList, resolveUserAgentDirs } from "./agents.ts";
+
+const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+/** Write a flat agent file the way a renderer does: frontmatter plus body. */
+function writeAgent(dir: string, name: string, body = `# ${name}\n`): string {
+	const filePath = join(dir, `${name}.agent.md`);
+	mkdirSync(dir, { recursive: true });
+	writeFileSync(filePath, `---\nname: "${name}"\ndescription: "${name} agent"\n---\n\n${body}`);
+	return filePath;
+}
+
+/** Write a composable agent source dir: `<agentsDir>/<name>/agent.md`. */
+function writeComposableAgent(agentsDir: string, name: string): void {
+	const dir = join(agentsDir, name);
+	mkdirSync(dir, { recursive: true });
+	writeFileSync(join(dir, "agent.md"), `# ${name}\n`);
+}
+
+describe("resolveUserAgentDirs", () => {
+	it("reads the agents a staged package rendered beside the extension", () => {
+		const root = mkdtempSync(join(tmpdir(), "subagent-package-"));
+		try {
+			const shipped = writeAgent(join(root, "agents"), "ralph", "Staged ralph body.\n");
+
+			const dirs = resolveUserAgentDirs(root);
+
+			assert.ok(dirs.includes(join(root, "agents")), `expected ${join(root, "agents")} in ${dirs.join(", ")}`);
+			assert.equal(loadUserAgents(dirs).find((agent) => agent.name === "ralph")?.filePath, shipped);
+		} finally {
+			rmSync(root, { recursive: true, force: true });
+		}
+	});
+
+	it("leaves a source checkout's composable agents tree to the agent-modes extension", () => {
+		const root = mkdtempSync(join(tmpdir(), "subagent-checkout-"));
+		try {
+			writeComposableAgent(join(root, "agents"), "ralph");
+			writeAgent(join(root, "agents"), "ralph", "Copilot render.\n");
+
+			const dirs = resolveUserAgentDirs(root);
+
+			assert.ok(!dirs.includes(join(root, "agents")), `checkout agents dir must not be read: ${dirs.join(", ")}`);
+		} finally {
+			rmSync(root, { recursive: true, force: true });
+		}
+	});
+});
+
+describe("discoverAgents (user scope)", () => {
+	it("does not hand pi the flat renders this checkout holds for other harnesses", () => {
+		const { agents } = discoverAgents(tmpdir(), "user");
+
+		assert.ok(
+			agents.every((agent) => !agent.filePath.startsWith(join(PACKAGE_ROOT, "agents"))),
+			`checkout renders leaked into discovery: ${agents.map((agent) => agent.filePath).join(", ")}`,
+		);
+	});
+});
+
+describe("loadUserAgents", () => {
+	it("merges every dir and lets the earlier dir win a name collision", () => {
+		const root = mkdtempSync(join(tmpdir(), "subagent-agents-"));
+		try {
+			const personal = join(root, "pi", "agent", "agents");
+			const shipped = join(root, "package", "agents");
+			writeAgent(personal, "plan", "Personal plan body.\n");
+			writeAgent(personal, "personal-only", "Personal agent body.\n");
+			writeAgent(shipped, "plan", "Shipped plan body.\n");
+			writeAgent(shipped, "shipped-only", "Shipped agent body.\n");
+
+			const agents = loadUserAgents([personal, shipped]);
+
+			assert.deepEqual(
+				agents.map((agent) => agent.name).sort(),
+				["personal-only", "plan", "shipped-only"],
+			);
+			assert.equal(agents.find((agent) => agent.name === "plan")?.filePath, join(personal, "plan.agent.md"));
+		} finally {
+			rmSync(root, { recursive: true, force: true });
+		}
+	});
+
+	it("reads a tool list whether it is a YAML scalar or sequence", () => {
+		const root = mkdtempSync(join(tmpdir(), "subagent-agents-"));
+		try {
+			const shipped = join(root, "agents");
+			mkdirSync(shipped, { recursive: true });
+			writeFileSync(join(shipped, "scalar.agent.md"), `---\nname: "scalar"\ndescription: "d"\ntools: "bash, read"\n---\n\n# scalar\n`);
+			writeFileSync(join(shipped, "sequence.agent.md"), `---\nname: "sequence"\ndescription: "d"\ntools: ["bash", "read"]\n---\n\n# sequence\n`);
+
+			const tools = Object.fromEntries(loadUserAgents([shipped]).map((agent) => [agent.name, agent.tools]));
+
+			assert.deepEqual(tools, { scalar: ["bash", "read"], sequence: ["bash", "read"] });
+		} finally {
+			rmSync(root, { recursive: true, force: true });
+		}
+	});
+
+	it("ignores directories that do not exist", () => {
+		const root = mkdtempSync(join(tmpdir(), "subagent-agents-"));
+		try {
+			const shipped = join(root, "agents");
+			writeAgent(shipped, "ralph", "Shipped ralph body.\n");
+
+			const agents = loadUserAgents([join(root, "missing"), shipped]);
+
+			assert.deepEqual(
+				agents.map((agent) => agent.name),
+				["ralph"],
+			);
+		} finally {
+			rmSync(root, { recursive: true, force: true });
+		}
+	});
+});
+
+// The frontmatter `tools` value reaches this extension as one scalar string
+// (pi's parseFrontmatter does not split it) and is turned into `pi --tools`,
+// whose parser splits on commas. A whitespace-separated list used to collapse
+// into a single bogus name, producing an allowlist that matched no tool — the
+// delegated agent then started with an empty tool block (agnt-ctx-rpm3).
+
+describe("parseToolList", () => {
+	it("splits the comma-separated form", () => {
+		assert.deepEqual(parseToolList("bash, read, grep, find, task"), [
+			"bash",
+			"read",
+			"grep",
+			"find",
+			"task",
+		]);
+	});
+
+	it("splits the space-separated form instead of collapsing it to one name", () => {
+		assert.deepEqual(parseToolList("bash read grep find task"), [
+			"bash",
+			"read",
+			"grep",
+			"find",
+			"task",
+		]);
+	});
+
+	it("tolerates mixed and padded separators", () => {
+		assert.deepEqual(parseToolList("  bash,read   grep ,\ttask "), [
+			"bash",
+			"read",
+			"grep",
+			"task",
+		]);
+	});
+
+	it("returns undefined when there is no tool list", () => {
+		assert.equal(parseToolList(undefined), undefined);
+		assert.equal(parseToolList(""), undefined);
+		assert.equal(parseToolList("   "), undefined);
+	});
+});

package/extensions/subagent/agents.ts

@@ -4,6 +4,7 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { fileURLToPath } from "node:url";
 import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
 
 export type AgentScope = "user" | "project" | "both";
@@ -23,6 +24,25 @@ export interface AgentDiscoveryResult {
 	projectAgentsDir: string | null;
 }
 
+/**
+ * Parse a frontmatter `tools` value into PI tool names.
+ *
+ * `parseFrontmatter` returns the scalar as a single string, and agent files are
+ * written with either a comma-separated list (`tools: read, grep`) or a
+ * whitespace-separated one. Splitting on commas alone collapses the whitespace
+ * form into one bogus name, which becomes a `--tools` allowlist matching no
+ * tool — the subagent then runs with an empty tool block. Accept both
+ * separators so neither form can zero out the tool list.
+ *
+ * @param {string | undefined} tools  Raw frontmatter `tools` scalar
+ * @returns {string[] | undefined} Tool names, or undefined when there are none
+ */
+export function parseToolList(tools: string | undefined): string[] | undefined {
+	const parsed = tools?.split(/[,\s]+/).filter(Boolean);
+
+	return parsed && parsed.length > 0 ? parsed : undefined;
+}
+
 function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig[] {
 	const agents: AgentConfig[] = [];
 
@@ -49,22 +69,17 @@ function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig
 			continue;
 		}
 
-		const { frontmatter, body } = parseFrontmatter<Record<string, string>>(content);
+		const { frontmatter, body } = parseFrontmatter<Record<string, unknown>>(content);
 
-		if (!frontmatter.name || !frontmatter.description) {
+		if (typeof frontmatter.name !== "string" || typeof frontmatter.description !== "string") {
 			continue;
 		}
 
-		const tools = frontmatter.tools
-			?.split(",")
-			.map((t: string) => t.trim())
-			.filter(Boolean);
-
 		agents.push({
 			name: frontmatter.name,
 			description: frontmatter.description,
-			tools: tools && tools.length > 0 ? tools : undefined,
-			model: frontmatter.model,
+			tools: readTools(frontmatter.tools),
+			model: typeof frontmatter.model === "string" ? frontmatter.model : undefined,
 			systemPrompt: body,
 			source,
 			filePath,
@@ -74,6 +89,21 @@ function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig
 	return agents;
 }
 
+/**
+ * The tools of a frontmatter `tools` value, which is written either as a YAML
+ * scalar (one string) or as a YAML sequence (an array).
+ */
+function readTools(value: unknown): string[] | undefined {
+	if (Array.isArray(value)) {
+		const tools = value
+			.filter((tool): tool is string => typeof tool === "string")
+			.map((tool) => tool.trim())
+			.filter(Boolean);
+		return tools.length > 0 ? tools : undefined;
+	}
+	return parseToolList(typeof value === "string" ? value : undefined);
+}
+
 function isDirectory(p: string): boolean {
 	try {
 		return fs.statSync(p).isDirectory();
@@ -94,11 +124,71 @@ function findNearestProjectAgentsDir(cwd: string): string | null {
 	}
 }
 
+/**
+ * The package this extension ships inside: `<extension>/../..`, i.e. the repo
+ * checkout or the staged pi package.
+ */
+const PACKAGE_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+/**
+ * True when `agentsDir` is a rendered tree — flat `*.agent.md` files and no
+ * composable `<name>/agent.md` source directories.
+ */
+function isRenderedAgentsTree(agentsDir: string): boolean {
+	if (!isDirectory(agentsDir)) return false;
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(agentsDir, { withFileTypes: true });
+	} catch {
+		return false;
+	}
+	return !entries.some((entry) => entry.isDirectory() && fs.existsSync(path.join(agentsDir, entry.name, "agent.md")));
+}
+
+/**
+ * Directories the "user" scope discovers agents from, in precedence order.
+ *
+ * pi's own user agent dir comes first: it holds hand-written personal agents
+ * and the copies older installers made, so existing setups keep resolving what
+ * they did before. Second is the package this extension ships inside, which is
+ * what makes a staged pi package self-contained — `agent-cortex install pi`
+ * renders the flat pi agents into `<package>/agents`.
+ *
+ * A source checkout contributes nothing: its `agents/` tree is the composable
+ * source, composed at runtime by the agent-modes extension.
+ */
+export function resolveUserAgentDirs(packageRoot: string = PACKAGE_ROOT): string[] {
+	const dirs: string[] = [];
+	const add = (dir: string) => {
+		const resolved = path.resolve(dir);
+		if (!dirs.includes(resolved) && isDirectory(resolved)) dirs.push(resolved);
+	};
+
+	add(path.join(getAgentDir(), "agents"));
+	const packageAgentsDir = path.join(packageRoot, "agents");
+	if (isRenderedAgentsTree(packageAgentsDir)) add(packageAgentsDir);
+
+	return dirs;
+}
+
+/**
+ * Load the user-scope agents from `dirs`, first directory wins on a name
+ * collision. Missing directories contribute nothing.
+ */
+export function loadUserAgents(dirs: string[]): AgentConfig[] {
+	const byName = new Map<string, AgentConfig>();
+	for (const dir of dirs) {
+		for (const agent of loadAgentsFromDir(dir, "user")) {
+			if (!byName.has(agent.name)) byName.set(agent.name, agent);
+		}
+	}
+	return Array.from(byName.values());
+}
+
 export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryResult {
-	const userDir = path.join(getAgentDir(), "agents");
 	const projectAgentsDir = findNearestProjectAgentsDir(cwd);
 
-	const userAgents = scope === "project" ? [] : loadAgentsFromDir(userDir, "user");
+	const userAgents = scope === "project" ? [] : loadUserAgents(resolveUserAgentDirs());
 	const projectAgents = scope === "user" || !projectAgentsDir ? [] : loadAgentsFromDir(projectAgentsDir, "project");
 
 	const agentMap = new Map<string, AgentConfig>();

package/extensions/subagent/index.ts

@@ -461,7 +461,8 @@ export default function (pi: ExtensionAPI) {
 		description: [
 			"Delegate tasks to specialized subagents with isolated context.",
 			"Modes: single (agent + task), parallel (tasks array), chain (sequential with {previous} placeholder).",
-			'Default agent scope is "user" (from ~/.pi/agent/agents).',
+			'Default agent scope is "user": ~/.pi/agent/agents plus the agents/ tree of the package',
+			"this extension ships inside.",
 			'To enable project-local agents in .pi/agents, set agentScope: "both" (or "project").',
 		].join(" "),
 		parameters: SubagentParams,

package/extensions/subagent/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "test": "node --test --import tsx/esm wait.test.ts",
+    "test": "node --test --import tsx/esm wait.test.ts agents.test.ts",
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {

package/lib/cli.mjs

@@ -1,4 +1,4 @@
-const SUPPORTED_HARNESSES = ["copilot", "claude", "pi"];
+const SUPPORTED_HARNESSES = ["claude", "pi"];
 
 // Options accepted by `install <harness>`. `--output`/`--dry-run` are shared by
 // the claude and pi installers; `--plugin-root` is pi-specific. Unknown or
@@ -9,7 +9,6 @@ const INSTALL_OPTIONS = {
   "--output": { key: "output" },
   "--plugin-root": { key: "pluginRoot" },
   "--require-register": { key: "requireRegister", boolean: true },
-  "--no-provision": { key: "noProvision", boolean: true },
 };
 
 export function parseArgs(argv) {
@@ -88,28 +87,53 @@ Commands:
                                         registration cannot run (missing CLI,
                                         pre-v2 build); default warns and prints
                                         the manual registration commands
-                      Options (copilot):
-                        --output <dir>   Write the flat *.agent.md files to <dir>
-                                         (default: <package root>/agents — the dir
-                                         plugin.json "agents" scans)
-                        --dry-run        Print what would be generated without writing
                       Options (pi):
-                        --dry-run             Show what would be installed without writing
-                        --output <dir>        Install into <dir> — agents/, skills/,
-                                              settings.json (merged, packages managed)
-                                              and keybindings.json (default: ~/.pi/agent)
+                        (no --output)         Materialise the pi package into
+                                              ~/.agent-cortex/pi: package.json,
+                                              agents/, skills/, extensions/ and
+                                              the bundled third-party pi packages
+                                              (pi-questions, pi-web-access), then
+                                              REGISTER that directory with pi via
+                                              "pi install" (user scope, idempotent
+                                              by state: a re-run is a no-op update,
+                                              and stale raw-repo sources are
+                                              removed so one source remains).
+                                              Once registered, the artifacts the
+                                              pre-staged-model installer rendered
+                                              into ~/.pi/agent are removed in a
+                                              one-time migration: agents and
+                                              skills whose names this package
+                                              ships or once shipped. Anything
+                                              else there is left alone, including
+                                              the whole extensions/ directory.
+                                              A migration that removed every
+                                              copy it attributed is recorded in
+                                              ~/.agent-cortex/legacy-sweep.json
+                                              (keyed by the pi user directory)
+                                              and never runs there twice; one
+                                              that could not be completed warns
+                                              and is retried on the next install.
+                        --output <dir>        Stage the package into <dir> only —
+                                              no registration (default:
+                                              ~/.agent-cortex/pi)
+                        --dry-run             Show what would be staged and
+                                              registered without writing or spawning
                         --plugin-root <dir>   Override the plugin root used for {{PATH:...}}
                                               tokens (default: token-map.json's pi value)
-                        --no-provision        Skip installing the third-party pi packages
-                                              declared in the package manifest (e.g.
-                                              pi-questions, pi-web-access). They are
-                                              installed by default on a real install.
+                        --require-register
+                                              Fail the install when the pi CLI
+                                              cannot register the staged package
+                                              (missing from PATH); default warns and
+                                              prints the manual commands
   --help, -h          Show this help text`;
 }
 
 export function validateHarness(harness) {
   if (harness === null) {
-    return { ok: false, error: "Missing harness argument. Supported harnesses: copilot, claude, pi" };
+    return {
+      ok: false,
+      error: `Missing harness argument. Supported harnesses: ${SUPPORTED_HARNESSES.join(", ")}`,
+    };
   }
   if (!SUPPORTED_HARNESSES.includes(harness)) {
     return { ok: false, error: `Unknown harness "${harness}". Supported harnesses: ${SUPPORTED_HARNESSES.join(", ")}` };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaybeeuu/agent-cortex",
-  "version": "1.42.0",
+  "version": "2.0.0",
   "description": "Personal PI package with custom agents, skills, and extensions",
   "keywords": [
     "pi-package"
@@ -27,23 +27,22 @@
     ],
     "skills": [
       "./skills"
-    ],
-    "packages": [
-      "npm:pi-questions",
-      "npm:pi-web-access@0.10.7"
     ]
   },
+  "dependencies": {
+    "pi-questions": "^0.3.4",
+    "pi-web-access": "0.10.7"
+  },
   "scripts": {
     "build": "echo 'Build complete — no compilation needed for PI package'",
     "lint": "pnpm typecheck && pnpm check:sync",
     "check:sync": "node scripts/check-no-sync.mjs",
     "test": "node --test test/*.test.mjs && pnpm -r test",
     "typecheck": "pnpm -r typecheck",
-    "build:copilot": "node scripts/build-copilot-agents.mjs",
     "changeset": "changeset",
-    "version-packages": "changeset version && bash scripts/sync-plugin-version.sh && pnpm build:copilot",
+    "version-packages": "changeset version",
     "publish-package": "TARBALL=$(pnpm pack | tail -n 1) && npm publish \"$TARBALL\" --provenance --access public",
-    "release": "changeset publish",
-    "postinstall": "bash scripts/install-instructions.sh"
+    "publish-noop": "echo 'No publish: the merged PR carries the no-publish label.'",
+    "release": "changeset publish"
   }
 }

package/pi/settings.json

@@ -6,15 +6,9 @@
   },
   "lastChangelogVersion": "0.87.1",
   "packages": [
-    {
-      "source": "../../src/agent-cortex",
-      "skills": []
-    },
-    "npm:pi-web-access@0.10.7",
     "npm:@getpipher/vision",
     "npm:@hypabolic/pi-hypa",
-    "npm:context-mode",
-    "npm:pi-questions"
+    "npm:context-mode"
   ],
   "defaultProvider": "opencode-go",
   "defaultModel": "deepseek-v4.1-flash",

package/pnpm-workspace.yaml

@@ -5,4 +5,10 @@ packages:
 allowBuilds:
   '@google/genai': false
   esbuild: false
+  # koffi (an optionalDependency of @mariozechner/pi-tui, which pi-questions
+  # peers on) ships prebuilt build/koffi/<platform>_<arch>/*.node binaries that
+  # index.js loads directly. Its install script (cnoke --prebuild) only
+  # matters for toolchains with no shipped binary, so deny it: acknowledged
+  # explicitly to satisfy the strict allowlist, no compilation, no download.
+  koffi: false
   protobufjs: false

package/scripts/check-changeset.mjs

@@ -0,0 +1,42 @@
+// PR gate: a pull request must add a changeset (.changeset/*.md) unless it is
+// the changesets bot's Version Packages PR or carries the `no-publish` label.
+// Reads `git diff --name-status <base>...HEAD` on stdin and the PR metadata
+// from the environment (CI supplies all three).
+import { evaluateChangesetGate, parseNameStatus } from "./lib/release-gates.mjs";
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+function readLabels(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    console.error("::error::PR_LABELS must be a JSON array of label names.");
+    process.exit(1);
+  }
+}
+
+const labels = readLabels(process.env.PR_LABELS ?? "[]");
+const changes = parseNameStatus(await readStdin());
+const result = evaluateChangesetGate({
+  changes,
+  labels,
+  headRef: process.env.PR_HEAD_REF ?? "",
+  actor: process.env.PR_ACTOR ?? "",
+});
+
+if (result.ok) {
+  console.log(`✓ Changeset gate passed (${result.reason}).`);
+} else {
+  console.error(
+    [
+      "::error::This PR adds no changeset (.changeset/*.md).",
+      "Publishing is the default: write a changeset file (see the style-versioning skill)",
+      "and commit it, or label the PR 'no-publish' when it genuinely ships nothing.",
+    ].join("\n"),
+  );
+  process.exitCode = 1;
+}

package/scripts/lib/compose-agent.mjs

@@ -1,8 +1,8 @@
 // Shared composer: reads a composable agent directory (agents/<name>/) and emits
-// the harness-specific agent content defined by agents/README.md. The Copilot
-// generator (scripts/build-copilot-agents.mjs) and the Claude install-time generator
-// (bin/installers/claude.mjs) compose from here, so the composable dirs are
-// the single source of truth and the flat/generated files stay in lockstep.
+// the harness-specific agent content defined by agents/README.md. The Claude and pi
+// install-time generators (bin/installers/claude.mjs, bin/installers/pi.mjs) compose
+// from here, so the composable dirs are the single source of truth and the generated
+// files stay in lockstep.
 //
 // Composition per the agents/README.md contract:
 //   1. {{SECTION:name}} is replaced with <dir>/<harness>/<name>.md content.
@@ -15,15 +15,15 @@
 // silently dropped section.
 //
 // Options (the pi installer passes `dropNullTools`, `pluginRoot` and
-// `resolveRelativePaths`; the copilot generator and claude installer use the strict defaults):
+// `resolveRelativePaths`; the claude installer uses the strict defaults):
 //   dropNullTools          replace null-mapped tool tokens with an empty string and
 //                          warn instead of throwing (pi's prose rule per the
 //                          token-map contract)
 //   pluginRoot             override the plugin_root used for resolved paths
 //                          (installers compute it from the actual install layout)
 //   resolveRelativePaths   non-keyed {{PATH:...}} args resolve to pluginRoot/arg
-//                          instead of staying verbatim (install time; the build
-//                          scripts leave them bare for Copilot CLI resolution)
+//                          instead of staying verbatim (install time; without it
+//                          they stay bare for runtime resolution)
 //   warn                   callback for drop/omit warnings (default: no-op; the
 //                          pi installer collects them into its result)
 //
@@ -61,7 +61,7 @@ function noop() {}
  *   the harness's section files before calling this.
  *
  * @param {string} content  Source text containing {{TOOL:...}}/{{PATH:...}} tokens
- * @param {string} harness  Harness id: "copilot" | "claude" | "pi"
+ * @param {string} harness  Harness id: "claude" | "pi"
  * @param {object} tokenMap Parsed token-map.json (from loadTokenMap)
  * @param {object} options  { dropNullTools, pluginRoot, resolveRelativePaths, warn, context }
  * @returns {string}
@@ -99,7 +99,7 @@ export function substituteTokens(content, harness, tokenMap, options = {}) {
  *
  * @param {string} root    Package root (contains agents/ and token-map.json)
  * @param {string} name    Agent directory name (e.g. "ralph", "plan")
- * @param {string} harness Harness id: "copilot" | "claude" | "pi"
+ * @param {string} harness Harness id: "claude" | "pi"
  * @returns {{ name: string, description: string, tools: string[], model?: string, argumentHint?: string, body: string }}
  */
 export async function composeAgent(root, name, harness, options = {}) {
@@ -218,7 +218,7 @@ function resolvePath(arg, harness, tokenMap, opts = {}) {
  *
  * @param {string[]} tools  Canonical tool names from a harness frontmatter.json
  * @param {object} tokenMap Parsed token-map.json (from loadTokenMap)
- * @param {string} harness  Harness id: "copilot" | "claude" | "pi"
+ * @param {string} harness  Harness id: "claude" | "pi"
  * @param {object} options  { warn }
  * @returns {string[]}
  */

package/scripts/lib/release-gates.mjs

@@ -0,0 +1,61 @@
+// Decision logic for the two release gates that stop `main` re-publishing an
+// already-published version. Both gates are pure: the CLI adapters read git
+// diffs, env vars, and the GitHub API, then delegate the decision here.
+//
+// Model: publishing is the default. The only path to "no publish" is an
+// explicit `no-publish` label on the merged PR — skipping is never implicit.
+
+export const NO_PUBLISH_LABEL = "no-publish";
+export const PUBLISH_COMMAND = "pnpm publish-package";
+export const NO_PUBLISH_COMMAND = "pnpm publish-noop";
+
+// The changesets bot's Version Packages PR consumes changesets and adds none.
+const VERSION_PACKAGES_HEAD_REF = "changeset-release/";
+const GITHUB_ACTIONS_BOT = "github-actions[bot]";
+
+const CHANGESET_PATH = /^\.changeset\/[^/]+\.md$/;
+const CHANGESET_EXEMPT_PATHS = new Set([".changeset/README.md"]);
+
+/**
+ * Parse `git diff --name-status` output into `{ status, path }` entries, where
+ * `status` is the single-letter change type and `path` is the new path.
+ */
+export function parseNameStatus(output) {
+  return output
+    .split("\n")
+    .filter((line) => line.trim() !== "")
+    .map((line) => {
+      const [status, ...paths] = line.split("\t");
+      return { status: status.charAt(0), path: paths.at(-1) };
+    });
+}
+
+/**
+ * Decide whether a pull request may skip adding a changeset. Exempt only the
+ * Version Packages PR and PRs explicitly labelled `no-publish`; every other PR
+ * must add its own changeset.
+ */
+export function evaluateChangesetGate({ changes, labels, headRef, actor }) {
+  if (headRef.startsWith(VERSION_PACKAGES_HEAD_REF) || actor === GITHUB_ACTIONS_BOT) {
+    return { ok: true, reason: "version-packages-pr" };
+  }
+  if (labels.includes(NO_PUBLISH_LABEL)) {
+    return { ok: true, reason: "no-publish-label" };
+  }
+  if (changes.some((change) => change.status === "A" && isChangeset(change.path))) {
+    return { ok: true, reason: "changeset-added" };
+  }
+  return { ok: false, reason: "missing-changeset" };
+}
+
+/**
+ * Resolve the command changesets/action should exec for publishing, based on
+ * the labels of the PR merged for the pushed commit.
+ */
+export function resolvePublishCommand(labels) {
+  return labels.includes(NO_PUBLISH_LABEL) ? NO_PUBLISH_COMMAND : PUBLISH_COMMAND;
+}
+
+function isChangeset(path) {
+  return CHANGESET_PATH.test(path) && !CHANGESET_EXEMPT_PATHS.has(path);
+}