@selesai/code 0.13.39 → 0.14.0

package/dist/extensions/pi-subagents/test/unit/agent-exclude-dirs.test.ts

@@ -0,0 +1,246 @@
+import assert from "node:assert/strict";
+import { afterEach, beforeEach, describe, it, mock } from "node:test";
+import fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { clearAgentDiscoveryCache, discoverAgents, discoverAgentsAll, discoverAgentSnapshot } from "../../src/agents/agents.ts";
+
+function writeAgent(dir: string, name: string): void {
+	fs.mkdirSync(dir, { recursive: true });
+	fs.writeFileSync(path.join(dir, `${name}.md`), `---\nname: ${name}\ndescription: exclusion test\n---\nbody\n`);
+}
+
+function recordReads(): string[] {
+	const reads: string[] = [];
+	const readdir = fs.readdirSync;
+	const readFile = fs.readFileSync;
+	mock.method(fs, "readdirSync", (...args: Parameters<typeof fs.readdirSync>) => {
+		reads.push(String(args[0]));
+		return readdir(...args);
+	});
+	mock.method(fs, "readFileSync", (...args: Parameters<typeof fs.readFileSync>) => {
+		reads.push(String(args[0]));
+		return readFile(...args);
+	});
+	return reads;
+}
+
+describe("settings subagents.agentExcludeDirs", () => {
+	let root: string;
+	let user: string;
+	let project: string;
+	let previousAgentDir: string | undefined;
+	beforeEach(() => {
+		root = fs.mkdtempSync(path.join(os.tmpdir(), "agent-exclude-"));
+		user = path.join(root, "user");
+		project = path.join(root, "project");
+		fs.mkdirSync(user);
+		fs.mkdirSync(path.join(project, ".selesai"), { recursive: true });
+		previousAgentDir = process.env.SELESAI_CODING_AGENT_DIR;
+		process.env.SELESAI_CODING_AGENT_DIR = user;
+		clearAgentDiscoveryCache();
+	});
+	afterEach(() => {
+		mock.restoreAll();
+		if (previousAgentDir === undefined) delete process.env.SELESAI_CODING_AGENT_DIR;
+		else process.env.SELESAI_CODING_AGENT_DIR = previousAgentDir;
+		fs.rmSync(root, { recursive: true, force: true });
+		clearAgentDiscoveryCache();
+	});
+	function settings(dir: string, subagents: unknown, extra = {}): void {
+		fs.writeFileSync(path.join(dir, "settings.json"), JSON.stringify({ subagents, ...extra }));
+	}
+
+	it("prunes nested sources, diagnostics and explicit roots in every projection while retaining legacy agents", () => {
+		const userPlugins = path.join(user, "agents", "plugins");
+		const projectPlugins = path.join(project, ".agents", "plugins");
+		const fixedProjectRoot = path.join(project, ".selesai", "agents");
+		writeAgent(path.join(user, "agents"), "user-legacy");
+		writeAgent(path.join(project, ".agents"), "project-legacy");
+		fs.mkdirSync(fixedProjectRoot, { recursive: true });
+		fs.writeFileSync(path.join(fixedProjectRoot, "fixed-invalid.md"), "---\nname: fixed-invalid\n---\nbody");
+		for (const dir of [userPlugins, projectPlugins]) {
+			writeAgent(path.join(dir, "nested", "agents"), "plugin-only");
+			writeAgent(dir, "user-legacy");
+			fs.writeFileSync(path.join(dir, "invalid.md"), "---\nname: invalid\n---\nbody");
+		}
+		settings(user, { agentExcludeDirs: ["agents/plugins"], agentScanDirs: [userPlugins, projectPlugins] });
+		settings(path.join(project, ".selesai"), { agentExcludeDirs: ["../.agents/plugins", "agents"] });
+		for (const scope of ["user", "project", "both"] as const) {
+			for (const result of [discoverAgents(project, scope), discoverAgentSnapshot(project, scope, undefined, { includeChains: false }).effective]) {
+				assert.equal(result.agents.some((agent) => agent.name === "plugin-only"), false);
+				assert.equal(result.agents.some((agent) => agent.name === (scope === "project" ? "project-legacy" : "user-legacy")), true);
+				assert.equal(result.agentDiagnostics?.some((diagnostic) => diagnostic.filePath.includes("plugins")), false);
+				assert.equal(result.directories?.some((directory) => directory.path.includes("plugins")), false);
+			}
+		}
+		const all = discoverAgentsAll(project);
+		assert.equal([...all.user, ...all.project, ...all.package].some((agent) => agent.name === "plugin-only"), false);
+		assert.equal([...all.user, ...all.project, ...all.package].some((agent) => agent.filePath.includes("plugins")), false, "collision inputs must not retain excluded definitions");
+		assert.equal(all.agentDiagnostics?.some((diagnostic) => diagnostic.filePath.includes("plugins")), false);
+		assert.equal(discoverAgents(project, "project").directories?.some((directory) => directory.path === fixedProjectRoot), false);
+		assert.equal(discoverAgentSnapshot(project, "project", undefined, { includeChains: false }).all.agentDiagnostics?.some((diagnostic) => diagnostic.filePath.startsWith(fixedProjectRoot)), false);
+	});
+
+	it("invalidates cached exclusions when settings change and discovers later additions after removal", () => {
+		const plugins = path.join(user, "agents", "plugins");
+		writeAgent(plugins, "plugin-cache");
+		assert.equal(discoverAgents(project, "both").agents.some((agent) => agent.name === "plugin-cache"), true);
+		settings(user, { agentExcludeDirs: ["agents/plugins"] });
+		assert.equal(discoverAgents(project, "both").agents.some((agent) => agent.name === "plugin-cache"), false);
+		writeAgent(plugins, "late-plugin");
+		settings(user, { agentExcludeDirs: [] });
+		assert.equal(discoverAgents(project, "both").agents.some((agent) => agent.name === "late-plugin"), true);
+	});
+
+	it("matches real paths and symlink aliases without matching sibling prefixes", () => {
+		const plugins = path.join(user, "agents", "plugins");
+		writeAgent(plugins, "hidden-alias");
+		writeAgent(`${plugins}-kept`, "sibling-kept");
+		writeAgent(path.join(plugins, "..kept"), "hidden-descendant");
+		fs.symlinkSync(plugins, path.join(user, "agents", "alias"), "dir");
+		fs.symlinkSync(path.join(plugins, "hidden-alias.md"), path.join(user, "agents", "alias.md"));
+		fs.symlinkSync(plugins, path.join(root, "excluded-alias"), "dir");
+		settings(user, { agentExcludeDirs: [path.join(root, "excluded-alias", ".")], agentScanDirs: [plugins] });
+		const names = discoverAgents(project, "both").agents.map((agent) => agent.name);
+		assert.equal(names.includes("hidden-alias"), false);
+		assert.equal(names.includes("hidden-descendant"), false);
+		assert.equal(names.includes("sibling-kept"), true);
+		fs.unlinkSync(path.join(root, "excluded-alias"));
+		fs.symlinkSync(`${plugins}-kept`, path.join(root, "excluded-alias"), "dir");
+		const retargeted = discoverAgents(project, "both").agents.map((agent) => agent.name);
+		assert.equal(retargeted.includes("hidden-alias"), true);
+		assert.equal(retargeted.includes("sibling-kept"), false);
+	});
+
+	it("invalidates excluded explicit scan-root aliases when retargeted to allowed storage", () => {
+		const hidden = path.join(root, "hidden");
+		const allowed = path.join(root, "allowed");
+		writeAgent(hidden, "hidden-retarget");
+		writeAgent(allowed, "allowed-retarget");
+		for (const scope of ["user", "project"] as const) {
+			clearAgentDiscoveryCache();
+			const alias = path.join(root, `${scope}-scan-alias`);
+			fs.symlinkSync(hidden, alias, "dir");
+			settings(user, { agentExcludeDirs: [hidden], ...(scope === "user" ? { agentScanDirs: [alias] } : {}) });
+			settings(path.join(project, ".selesai"), scope === "project" ? { agentScanDirs: [alias] } : {});
+			const reads = recordReads();
+			for (let attempt = 0; attempt < 2; attempt++) {
+				const initial = discoverAgentSnapshot(project, "both", undefined, { includeChains: false });
+				assert.equal(initial.effective.agents.some((agent) => agent.name.endsWith("-retarget")), false);
+			}
+			assert.equal(reads.some((filePath) => [hidden, alias].some((dir) => filePath === dir || filePath.startsWith(`${dir}${path.sep}`))), false);
+			mock.restoreAll();
+			fs.unlinkSync(alias);
+			fs.symlinkSync(allowed, alias, "dir");
+			const cached = discoverAgentSnapshot(project, "both", undefined, { includeChains: false });
+			assert.equal(cached.effective.agents.some((agent) => agent.name === "allowed-retarget"), true);
+			assert.equal(cached.all[scope].some((agent) => agent.name === "allowed-retarget"), true);
+			clearAgentDiscoveryCache();
+			assert.deepEqual(cached.effective.agents.map((agent) => agent.filePath), discoverAgents(project, "both").agents.map((agent) => agent.filePath));
+		}
+	});
+
+	for (const source of ["wildcard", "environment", "package", "fixed"] as const) it(`invalidates excluded ${source} root aliases on reverse retarget`, () => {
+		const hidden = path.join(root, "hidden");
+		const allowed = path.join(root, "allowed");
+		const container = path.join(root, "sources", "child");
+		fs.mkdirSync(container, { recursive: true });
+		const alias = path.join(source === "fixed" ? user : container, "agents");
+		writeAgent(hidden, "hidden-source");
+		writeAgent(allowed, "allowed-source");
+		fs.symlinkSync(hidden, alias, "dir");
+		const previousExtraDirs = process.env.SELESAI_SUBAGENT_EXTRA_AGENT_DIRS;
+		try {
+			if (source === "environment") process.env.SELESAI_SUBAGENT_EXTRA_AGENT_DIRS = alias;
+			if (source === "package") fs.writeFileSync(path.join(container, "package.json"), JSON.stringify({ name: "alias-fixture", "pi-subagents": { agents: ["./agents"] } }));
+			settings(user, { agentExcludeDirs: [hidden], ...(source === "wildcard" ? { agentScanDirs: [path.join(root, "sources", "*", "agents")] } : {}) }, source === "package" ? { packages: [container] } : {});
+			assert.equal(discoverAgents(project, "both").agents.some((agent) => agent.name === "allowed-source"), false);
+			fs.unlinkSync(alias);
+			fs.symlinkSync(allowed, alias, "dir");
+			assert.equal(discoverAgents(project, "both").agents.some((agent) => agent.name === "allowed-source"), true);
+		} finally {
+			if (previousExtraDirs === undefined) delete process.env.SELESAI_SUBAGENT_EXTRA_AGENT_DIRS;
+			else process.env.SELESAI_SUBAGENT_EXTRA_AGENT_DIRS = previousExtraDirs;
+		}
+	});
+
+	it("resolves home paths and missing descendants through symlinked ancestors", () => {
+		const previousHome = process.env.HOME;
+		const previousUserProfile = process.env.USERPROFILE;
+		try {
+			process.env.HOME = root;
+			process.env.USERPROFILE = root;
+			const plugins = path.join(user, "agents", "plugins");
+			fs.mkdirSync(plugins, { recursive: true });
+			fs.symlinkSync(plugins, path.join(root, "plugin-alias"), "dir");
+			settings(user, { agentExcludeDirs: ["~/plugin-alias/later"], agentScanDirs: [path.join(plugins, "*", "agents")] });
+			discoverAgents(project, "both");
+			writeAgent(path.join(plugins, "later", "agents"), "missing-hidden");
+			writeAgent(path.join(plugins, "later-kept", "agents"), "missing-kept");
+			const names = discoverAgents(project, "both").agents.map((agent) => agent.name);
+			assert.equal(names.includes("missing-hidden"), false);
+			assert.equal(names.includes("missing-kept"), true);
+		} finally {
+			if (previousHome === undefined) delete process.env.HOME;
+			else process.env.HOME = previousHome;
+			if (previousUserProfile === undefined) delete process.env.USERPROFILE;
+			else process.env.USERPROFILE = previousUserProfile;
+		}
+	});
+
+	it("does not read or traverse excluded trees on fresh scans or cache fingerprints", () => {
+		const plugins = path.join(user, "agents", "plugins");
+		writeAgent(plugins, "never-read");
+		writeAgent(path.join(user, "agents"), "kept");
+		settings(user, { agentExcludeDirs: [plugins] });
+		const reads = recordReads();
+		for (const scope of ["user", "project", "both"] as const) discoverAgents(project, scope);
+		discoverAgentsAll(project);
+		assert.equal(reads.some((filePath) => filePath === plugins || filePath.startsWith(`${plugins}${path.sep}`)), false);
+		reads.length = 0;
+		writeAgent(path.join(plugins, "late"), "still-hidden");
+		discoverAgents(project, "both");
+		assert.equal(reads.some((filePath) => filePath === plugins || filePath.startsWith(`${plugins}${path.sep}`)), false);
+		assert.equal(reads.includes(path.join(user, "agents", "kept.md")), false, "excluded changes must not force a source reload");
+	});
+
+	it("does not re-include excluded package roots or change chain discovery", () => {
+		const pkg = path.join(root, "pkg");
+		writeAgent(path.join(pkg, "agents"), "package-hidden");
+		fs.writeFileSync(path.join(pkg, "package.json"), JSON.stringify({ name: "exclude-fixture", "pi-subagents": { agents: ["./agents"], chains: ["./agents"] } }));
+		fs.writeFileSync(path.join(pkg, "agents", "kept.chain.json"), JSON.stringify({ name: "kept-chain", description: "Retained chain", chain: [{ agent: "scout", task: "Inspect" }] }));
+		settings(user, {}, { packages: [pkg] });
+		assert.equal(discoverAgentsAll(project).package.some((agent) => agent.name === "package-hidden"), true);
+		settings(user, { agentExcludeDirs: [path.join(pkg, "agents")] }, { packages: [pkg] });
+		const all = discoverAgentsAll(project);
+		assert.equal(all.package.some((agent) => agent.name === "package-hidden"), false);
+		assert.equal(all.chains.some((chain) => chain.name === "kept-chain"), true);
+		fs.writeFileSync(path.join(pkg, "agents", "late.chain.json"), JSON.stringify({ name: "late-chain", description: "New chain", chain: [{ agent: "scout", task: "Inspect" }] }));
+		assert.equal(discoverAgentsAll(project).chains.some((chain) => chain.name === "late-chain"), true);
+	});
+
+	it("invalidates agent-only discovery when an excluded package declares an allowed external root", () => {
+		const pkg = path.join(root, "pkg");
+		const excludedAgents = path.join(pkg, "agents");
+		writeAgent(excludedAgents, "package-hidden");
+		writeAgent(path.join(root, "allowed"), "outside");
+		const manifest = path.join(pkg, "package.json");
+		fs.writeFileSync(manifest, JSON.stringify({ name: "fixture", "pi-subagents": { agents: ["./agents"] } }));
+		settings(user, { agentExcludeDirs: [pkg] }, { packages: [pkg] });
+		const reads = recordReads();
+		assert.equal(discoverAgents(project, "both").agents.some((agent) => agent.name === "outside"), false);
+		fs.writeFileSync(manifest, JSON.stringify({ name: "fixture", "pi-subagents": { agents: ["../allowed"] } }));
+		const cached = discoverAgents(project, "both");
+		assert.equal(cached.agents.some((agent) => agent.name === "outside"), true);
+		assert.equal(cached.agents.some((agent) => agent.name === "package-hidden"), false);
+		assert.equal(discoverAgentSnapshot(project, "both", undefined, { includeChains: false }).all.package.some((agent) => agent.name === "outside"), true);
+		assert.equal(reads.some((filePath) => filePath === excludedAgents || filePath.startsWith(`${excludedAgents}${path.sep}`)), false);
+	});
+
+	it("rejects malformed exclusions in participating settings", () => {
+		settings(user, { agentExcludeDirs: [42] });
+		assert.throws(() => discoverAgents(project, "user"), /invalid 'agentExcludeDirs'/);
+		assert.throws(() => discoverAgents(project, "both"), /invalid 'agentExcludeDirs'/);
+	});
+});

package/dist/extensions/pi-subagents/test/unit/agent-frontmatter.test.ts

@@ -102,6 +102,56 @@ afterEach(() => {
 	}
 });
 
+describe("agent outputSchema frontmatter", () => {
+	it("parses and serializes an inline object schema", () => withTempHome(() => {
+		const project = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-output-schema-"));
+		tempDirs.push(project);
+		writeAgent(path.join(project, ".selesai", "agents", "typed.md"), `---\nname: typed\ndescription: Typed agent\noutputSchema: {"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean"}}}\n---\n\nReturn data.\n`);
+		const discovered = discoverAgents(project, "project");
+		const typed = discovered.agents.find((agent) => agent.name === "typed");
+		assert.deepEqual(typed?.outputSchema, { type: "object", required: ["ok"], properties: { ok: { type: "boolean" } } });
+		writeAgent(path.join(project, ".selesai", "agents", "typed.md"), serializeAgent(typed!));
+		assert.deepEqual(discoverAgents(project, "project").agents.find((agent) => agent.name === "typed")?.outputSchema, typed?.outputSchema);
+	}));
+
+	it("rejects malformed, null, and array output schemas", () => withTempHome(() => {
+		const project = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-output-schema-invalid-"));
+		tempDirs.push(project);
+		for (const [name, value] of [["malformed", "{"], ["null", "null"], ["array", "[]"]]) {
+			writeAgent(path.join(project, ".selesai", "agents", `${name}.md`), `---\nname: ${name}\ndescription: Invalid schema\noutputSchema: ${value}\n---\nBody\n`);
+		}
+		const discovered = discoverAgents(project, "project");
+		assert.deepEqual(discovered.agents.filter((agent) => ["malformed", "null", "array"].includes(agent.name)), []);
+		assert.equal(discovered.agentDiagnostics?.length, 3);
+		assert.match(discovered.agentDiagnostics?.find(({ name }) => name === "malformed")?.error ?? "", /JSON|position|property/i);
+		assert.equal(discovered.agentDiagnostics?.filter(({ error }) => /outputSchema.*object/i.test(error)).length, 2);
+	}));
+});
+
+describe("agent allowedAgents frontmatter", () => {
+	it("preserves omission and empty lists, round-trips canonical lists, and rejects malformed names", () => withTempHome(() => {
+		const project = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-allowed-agents-"));
+		tempDirs.push(project);
+		const dir = path.join(project, ".selesai", "agents");
+		writeAgent(path.join(dir, "omitted.md"), "---\nname: omitted\ndescription: Omitted\n---\n\nPrompt.\n");
+		writeAgent(path.join(dir, "empty.md"), "---\nname: empty\ndescription: Empty\nallowedAgents:\n---\n\nPrompt.\n");
+		writeAgent(path.join(dir, "listed.md"), "---\nname: listed\ndescription: Listed\nallowedAgents: worker, scout\n---\n\nPrompt.\n");
+		writeAgent(path.join(dir, "blocked.md"), "---\nname: blocked\ndescription: Blocked\nallowedAgents:\n  - reviewer\n  - package.scout\n---\n\nPrompt.\n");
+		writeAgent(path.join(dir, "invalid.md"), "---\nname: invalid\ndescription: Invalid\nallowedAgents: bad name\n---\n\nPrompt.\n");
+
+		const discovered = discoverAgents(project, "project");
+		assert.equal(discovered.agents.find((entry) => entry.name === "omitted")?.allowedAgents, undefined);
+		assert.deepEqual(discovered.agents.find((entry) => entry.name === "empty")?.allowedAgents, []);
+		assert.deepEqual(discovered.agents.find((entry) => entry.name === "listed")?.allowedAgents, ["scout", "worker"]);
+		assert.deepEqual(discovered.agents.find((entry) => entry.name === "blocked")?.allowedAgents, ["package.scout", "reviewer"]);
+		assert.match(discovered.agentDiagnostics.find((entry) => entry.name === "invalid")?.error ?? "", /Invalid capability ceiling allowedAgents entry 'bad name'/u);
+
+		const listed = discovered.agents.find((entry) => entry.name === "listed")!;
+		writeAgent(path.join(dir, "listed.md"), serializeAgent(listed));
+		assert.deepEqual(discoverAgents(project, "project").agents.find((entry) => entry.name === "listed")?.allowedAgents, ["scout", "worker"]);
+	}));
+});
+
 describe("agent definition directory inspection", () => {
 	it("distinguishes absent, empty, candidates, unreadable, and non-directory paths", () => {
 		const root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-agent-inspection-"));
@@ -312,6 +362,8 @@ Review carefully.`);
 		tempDirs.push(project);
 		writeAgent(path.join(project, ".selesai", "agents", "external.md"), `---\nname: external\ndescription: External\nrunner:\n  type: external-cli\n  command: node\nmodel: provider/model\n---\nBody`);
 		assert.match(discoverAgents(project, "project").agentDiagnostics?.[0]?.error ?? "", /unsupported Pi-only fields: model/);
+		writeAgent(path.join(project, ".selesai", "agents", "external.md"), `---\nname: external\ndescription: External\nrunner:\n  type: external-cli\n  command: node\nallowedAgents: worker\n---\nBody`);
+		assert.match(discoverAgents(project, "project").agentDiagnostics?.[0]?.error ?? "", /unsupported Pi-only fields: allowedAgents/);
 	}));
 
 	it("keeps valid agents executable when another agent is malformed", () => withTempHome(() => {
@@ -470,9 +522,6 @@ skill:
 skillPath:
   - ./private-skills
   - ../shared-skills
-fallbackModels:
-  - openai/gpt-5-mini
-  - anthropic/claude-sonnet-4
 extensions:
   - ./extension-one.ts
   - ./extension-two.ts
@@ -490,7 +539,6 @@ Do work
 		assert.deepEqual(worker?.defaultReads, ["input-one.md", "input-two.md"]);
 		assert.deepEqual(worker?.skills, ["review-checklist", "safe-bash"]);
 		assert.deepEqual(worker?.skillPath, ["./private-skills", "../shared-skills"]);
-		assert.deepEqual(worker?.fallbackModels, ["openai/gpt-5-mini", "anthropic/claude-sonnet-4"]);
 		assert.deepEqual(worker?.extensions, [path.join(dir, ".selesai", "agents", "extension-one.ts"), path.join(dir, ".selesai", "agents", "extension-two.ts")]);
 		assert.deepEqual(worker?.subagentOnlyExtensions, [path.join(dir, ".selesai", "agents", "child-only.ts"), path.join(dir, ".selesai", "agents", "child-helper.ts")]);
 	});
@@ -523,7 +571,6 @@ tools: read-only, mcp:github/search_repositories
 defaultReads: input-one.md, input-two.md
 skills: review-checklist, safe-bash
 skillPath: ./private-skills, ../shared-skills
-fallbackModels: openai/gpt-5-mini, anthropic/claude-sonnet-4
 extensions: ./extension-one.ts, ./extension-two.ts
 subagentOnlyExtensions: ./child-only.ts, ./child-helper.ts
 ---
@@ -537,7 +584,6 @@ Do work
 		assert.deepEqual(worker?.defaultReads, ["input-one.md", "input-two.md"]);
 		assert.deepEqual(worker?.skills, ["review-checklist", "safe-bash"]);
 		assert.deepEqual(worker?.skillPath, ["./private-skills", "../shared-skills"]);
-		assert.deepEqual(worker?.fallbackModels, ["openai/gpt-5-mini", "anthropic/claude-sonnet-4"]);
 		assert.deepEqual(worker?.extensions, [path.join(dir, ".selesai", "agents", "extension-one.ts"), path.join(dir, ".selesai", "agents", "extension-two.ts")]);
 		assert.deepEqual(worker?.subagentOnlyExtensions, [path.join(dir, ".selesai", "agents", "child-only.ts"), path.join(dir, ".selesai", "agents", "child-helper.ts")]);
 	});
@@ -638,7 +684,7 @@ Do work
 		assert.equal(worker?.defaultContext, "fork");
 	});
 
-	it("loads packaged worker with fresh writer defaults and keeps oracle fork context", () => {
+	it("loads packaged worker fresh and oracle forked with advisor alias", () => {
 		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-builtin-default-context-"));
 		tempDirs.push(dir);
 		const agents = discoverAgentsAll(dir).builtin;
@@ -1225,6 +1271,8 @@ Agent prompt
 				},
 			},
 		});
+		// Mark this fixture as the project root, even when /tmp is a project.
+		fs.mkdirSync(path.join(dir, ".selesai"));
 		writeAgent(path.join(dir, "root-agent.md"), `---
 name: root-agent
 description: Root package agent
@@ -1388,62 +1436,6 @@ Review only.
 	}));
 });
 
-describe("agent frontmatter completionGuard", () => {
-	it("serializes disabled completion guard into agent frontmatter", () => {
-		const agent: AgentConfig = {
-			name: "test-runner",
-			description: "Test runner",
-			systemPrompt: "Validate changes",
-			systemPromptMode: "replace",
-			inheritProjectContext: false,
-			inheritSkills: false,
-			source: "project",
-			filePath: "/tmp/test-runner.md",
-			completionGuard: false,
-		};
-
-		const serialized = serializeAgent(agent);
-		assert.match(serialized, /completionGuard: false/);
-	});
-
-	it("omits enabled completion guard from serialized frontmatter", () => {
-		const agent: AgentConfig = {
-			name: "test-runner",
-			description: "Test runner",
-			systemPrompt: "Validate changes",
-			systemPromptMode: "replace",
-			inheritProjectContext: false,
-			inheritSkills: false,
-			source: "project",
-			filePath: "/tmp/test-runner.md",
-			completionGuard: true,
-		};
-
-		const serialized = serializeAgent(agent);
-		assert.doesNotMatch(serialized, /completionGuard:/);
-	});
-
-	it("parses completionGuard from discovered agent frontmatter", () => {
-		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-agent-completion-guard-"));
-		tempDirs.push(dir);
-		const agentsDir = path.join(dir, ".selesai", "agents");
-		fs.mkdirSync(agentsDir, { recursive: true });
-		fs.writeFileSync(path.join(agentsDir, "test-runner.md"), `---
-name: test-runner
-description: Test runner
-completionGuard: false
----
-
-Validate changes
-`, "utf-8");
-
-		const result = discoverAgents(dir, "project");
-		const runner = result.agents.find((agent) => agent.name === "test-runner");
-		assert.equal(runner?.completionGuard, false);
-		assert.equal(runner?.extraFields?.completionGuard, undefined);
-	});
-});
-
 describe("agent frontmatter maxSubagentDepth", () => {
 	it("serializes maxSubagentDepth into agent frontmatter", () => {
 		const agent: AgentConfig = {
@@ -1582,25 +1574,8 @@ Do work
 	});
 });
 
-describe("agent frontmatter fallbackModels", () => {
-	it("serializes fallbackModels into agent frontmatter", () => {
-		const agent: AgentConfig = {
-			name: "worker",
-			description: "Worker",
-			systemPrompt: "Do work",
-			systemPromptMode: "replace",
-			inheritProjectContext: false,
-			inheritSkills: false,
-			source: "project",
-			filePath: "/tmp/worker.md",
-			fallbackModels: ["openai/gpt-5-mini", "anthropic/claude-sonnet-4"],
-		};
-
-		const serialized = serializeAgent(agent);
-		assert.match(serialized, /fallbackModels: openai\/gpt-5-mini, anthropic\/claude-sonnet-4/);
-	});
-
-	it("parses fallbackModels from discovered agent frontmatter", () => {
+describe("removed agent frontmatter", () => {
+	it("rejects fallbackModels clearly", () => {
 		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-agent-fallback-frontmatter-"));
 		tempDirs.push(dir);
 		const agentsDir = path.join(dir, ".selesai", "agents");
@@ -1615,8 +1590,7 @@ Do work
 `, "utf-8");
 
 		const result = discoverAgents(dir, "project");
-		const worker = result.agents.find((agent) => agent.name === "worker");
-		assert.deepEqual(worker?.fallbackModels, ["openai/gpt-5-mini", "anthropic/claude-sonnet-4"]);
+		assert.match(result.agentDiagnostics?.find((diagnostic) => diagnostic.name === "worker")?.error ?? "", /removed frontmatter field 'fallbackModels'/);
 	});
 });
 
@@ -1794,7 +1768,7 @@ Do work
 		assert.equal(worker?.extraFields?.fast, undefined);
 	});
 
-	it("adds the fast extension only for allowlisted native models", () => {
+	it("adds the fast extension only for native OpenAI-Codex models", () => {
 		const launch = {
 			host: "parent" as const,
 			cwd: process.cwd(),
@@ -1806,11 +1780,12 @@ Do work
 			childIndex: 0,
 			fast: true,
 		};
-		const allowed = buildInProcessChildLaunch({ ...launch, model: "openai-codex/gpt-5.6-luna:low" });
+		const allowed = buildInProcessChildLaunch({ ...launch, model: "openai-codex/gpt-6-sol:low" });
 
 		assert.ok(allowed.toolPlan.runtimeExtensions.some((extensionPath) => extensionPath.endsWith("fast-mode-extension.ts")));
 		assert.deepEqual(allowed.session.hooks.map((hook) => hook.name), ["pi-subagents:prompt-runtime", "pi-subagents:fast-mode"]);
 		assert.throws(() => buildInProcessChildLaunch({ ...launch, model: "anthropic/claude-sonnet-4" }), /fast mode supports only/);
+		assert.throws(() => buildInProcessChildLaunch({ ...launch, model: "openai/gpt-6-sol" }), /fast mode supports only/);
 	});
 });
 
@@ -1902,7 +1877,7 @@ Do work
 			const expectedTools = {
 				worker: ["read", "grep", "find", "ls", "bash", "edit", "write", "contact_supervisor"],
 				delegate: ["read", "grep", "find", "ls", "bash", "edit", "write", "contact_supervisor"],
-				reviewer: ["read", "grep", "find", "ls", "contact_supervisor"],
+				reviewer: ["read", "grep", "find", "ls", "watchdog_diff", "contact_supervisor"],
 				scout: ["read", "grep", "find", "ls", "bash", "write", "contact_supervisor"],
 				researcher: ["read", "write", "web_explore"],
 			};

package/dist/extensions/pi-subagents/test/unit/agent-global-root-override.test.ts

@@ -0,0 +1,86 @@
+import assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { after, before, it } from "node:test";
+import { clearAgentDiscoveryCache, discoverAgentSnapshot, discoverAgents } from "../../src/agents/agents.ts";
+
+const temp = fs.mkdtempSync(path.join(os.tmpdir(), "pi-agent-global-root-"));
+const fixtureRoot = path.join(temp, "quote's & space");
+const previous = Object.fromEntries(["HOME", "USERPROFILE", "APPDATA", "SELESAI_CODING_AGENT_DIR", "PI_OFFLINE", "PATH"].map((key) => [key, process.env[key]]));
+const project = path.join(fixtureRoot, "project");
+const rootA = path.join(fixtureRoot, "prefix-a", "lib", "node_modules");
+const rootB = path.join(fixtureRoot, "prefix-b", "lib", "node_modules");
+const invocationFile = path.join(fixtureRoot, "npm-invocations");
+
+function writeAgent(file: string, name: string): void {
+	fs.mkdirSync(path.dirname(file), { recursive: true });
+	fs.writeFileSync(file, `---\nname: ${name}\ndescription: ${name}\n---\n\n${name}\n`);
+}
+
+function writePackage(root: string, name: string): void {
+	const pkg = path.join(root, name);
+	fs.mkdirSync(pkg, { recursive: true });
+	fs.writeFileSync(path.join(pkg, "package.json"), JSON.stringify({ name, "pi-subagents": { agents: ["agents"] } }));
+	writeAgent(path.join(pkg, "agents", `${name}.md`), name);
+}
+
+before(() => {
+	process.env.HOME = path.join(temp, "home");
+	process.env.USERPROFILE = process.env.HOME;
+	process.env.APPDATA = path.join(temp, "missing-appdata");
+	process.env.SELESAI_CODING_AGENT_DIR = path.join(temp, "home", ".selesai", "agent");
+	delete process.env.PI_OFFLINE;
+	writeAgent(path.join(project, ".selesai", "agents", "local.md"), "local-only");
+	writePackage(rootA, "global-a");
+	writePackage(rootB, "global-b");
+	const bin = path.join(fixtureRoot, "bin");
+	fs.mkdirSync(bin);
+	fs.writeFileSync(path.join(bin, "fake-npm.cjs"), `const fs = require("node:fs");
+fs.appendFileSync(${JSON.stringify(invocationFile)}, "x");
+process.stdout.write(${JSON.stringify(`${rootA}\n`)});
+`);
+	const npm = path.join(bin, process.platform === "win32" ? "npm.cmd" : "npm");
+	fs.writeFileSync(npm, process.platform === "win32"
+		? `@echo off\r\n"${process.execPath}" "%~dp0fake-npm.cjs" %*\r\n`
+		: `#!/bin/sh\nexec "${process.execPath}" "$(dirname "$0")/fake-npm.cjs" "$@"\n`);
+	if (process.platform !== "win32") fs.chmodSync(npm, 0o755);
+	process.env.PATH = `${bin}${path.delimiter}${previous.PATH ?? ""}`;
+	clearAgentDiscoveryCache();
+});
+
+after(() => {
+	clearAgentDiscoveryCache();
+	for (const [key, value] of Object.entries(previous)) {
+		if (value === undefined) delete process.env[key];
+		else process.env[key] = value;
+	}
+	fs.rmSync(temp, { recursive: true, force: true });
+});
+
+it("explicit null skips global lookup while retaining local agents and does not poison later roots", () => {
+	const pending = discoverAgentSnapshot(project, "both", undefined, { includeChains: false, globalNpmRoot: null });
+	assert.equal(pending.effective.agents.some((agent) => agent.name === "local-only"), true);
+	assert.equal(pending.effective.agents.some((agent) => agent.name === "global-a"), false);
+	assert.equal(pending.all.package.some((agent) => agent.name === "global-a"), false);
+	assert.equal(fs.existsSync(invocationFile), false);
+
+	const completed = discoverAgentSnapshot(project, "both", undefined, { includeChains: false, globalNpmRoot: rootA });
+	assert.equal(completed.effective.agents.some((agent) => agent.name === "global-a"), true);
+	assert.equal(completed.all.package.some((agent) => agent.name === "global-a"), true);
+	assert.equal(fs.existsSync(invocationFile), false);
+});
+
+it("preserves synchronous custom-prefix lookup without an override", () => {
+	const result = discoverAgents(project, "both");
+	assert.equal(result.agents.some((agent) => agent.name === "global-a" && agent.source === "package"), true);
+	assert.equal(fs.readFileSync(invocationFile, "utf8").trim(), "x");
+});
+
+it("different explicit roots cannot reuse stale cached package sources", () => {
+	const changed = discoverAgents(project, "both", undefined, { globalNpmRoot: rootB });
+	assert.equal(changed.agents.some((agent) => agent.name === "global-b"), true);
+	assert.equal(changed.agents.some((agent) => agent.name === "global-a"), false);
+	assert.equal(discoverAgents(project, "user", undefined, { globalNpmRoot: rootB }).agents.some((agent) => agent.name === "global-b"), true);
+	assert.equal(fs.readFileSync(invocationFile, "utf8").trim(), "x");
+});