@selesai/code 0.5.28 → 0.6.1

package/dist/extensions/pi-subagents/test/integration/slash-commands.test.ts

@@ -520,10 +520,10 @@ describe("slash command custom message delivery", { skip: !available ? "slash-co
 
 		const ctx = createCommandContext({ sessionManager });
 		registerSlashCommands!(pi, createState(process.cwd()));
-		await commands.get("run")!.handler("scout", ctx);
+		await commands.get("run")!.handler("explorer", ctx);
 		await new Promise<void>((resolve) => setImmediate(resolve));
 
-		assert.deepEqual(requestedParams, { agent: "scout", task: "", clarify: false, agentScope: "both" });
+		assert.deepEqual(requestedParams, { agent: "explorer", task: "", clarify: false, agentScope: "both" });
 		assert.equal(requestedCtx, ctx);
 		assert.equal(sent.length, 2);
 		assert.equal((sent[0] as { display?: boolean }).display, true);
@@ -565,7 +565,7 @@ describe("slash command custom message delivery", { skip: !available ? "slash-co
 		};
 
 		registerSlashCommands!(pi, createState(process.cwd()));
-		await commands.get("run")!.handler("scout inspect this", createCommandContext({
+		await commands.get("run")!.handler("explorer inspect this", createCommandContext({
 			hasUI: true,
 			setStatus: (_key, text) => {
 				log.push(`status:${text ?? "clear"}`);
@@ -615,7 +615,7 @@ describe("slash command custom message delivery", { skip: !available ? "slash-co
 		};
 
 		registerSlashCommands!(pi, createState(process.cwd()));
-		await commands.get("run")!.handler("scout inspect this", createCommandContext({
+		await commands.get("run")!.handler("explorer inspect this", createCommandContext({
 			hasUI: true,
 			setToolsExpanded: (expanded) => log.push(`expanded:${String(expanded)}`),
 		}));
@@ -655,7 +655,7 @@ describe("slash command custom message delivery", { skip: !available ? "slash-co
 		};
 
 		registerSlashCommands!(pi, createState(process.cwd()));
-		await commands.get("run")!.handler("scout inspect this", createCommandContext({
+		await commands.get("run")!.handler("explorer inspect this", createCommandContext({
 			hasUI: true,
 			setStatus: (_key, text) => {
 				log.push(`status:${text ?? "clear"}`);
@@ -706,10 +706,10 @@ describe("slash command custom message delivery", { skip: !available ? "slash-co
 		};
 
 		registerSlashCommands!(pi, createState(process.cwd()));
-		await commands.get("parallel")!.handler("scout[output=x.md,outputMode=file-only,reads=a.md+b.md,progress] -- Review", createCommandContext());
+		await commands.get("parallel")!.handler("explorer[output=x.md,outputMode=file-only,reads=a.md+b.md,progress] -- Review", createCommandContext());
 
 		assert.deepEqual(requestedParams, {
-			tasks: [{ agent: "scout", task: "Review", output: "x.md", outputMode: "file-only", reads: ["a.md", "b.md"], progress: true }],
+			tasks: [{ agent: "explorer", task: "Review", output: "x.md", outputMode: "file-only", reads: ["a.md", "b.md"], progress: true }],
 			clarify: false,
 			agentScope: "both",
 		});
@@ -746,7 +746,7 @@ describe("slash command custom message delivery", { skip: !available ? "slash-co
 		};
 
 		registerSlashCommands!(pi, createState(process.cwd()));
-		const args = Array.from({ length: 9 }, (_, index) => `scout \"task ${index + 1}\"`).join(" -> ");
+		const args = Array.from({ length: 9 }, (_, index) => `explorer \"task ${index + 1}\"`).join(" -> ");
 		await commands.get("parallel")!.handler(args, createCommandContext());
 		await new Promise<void>((resolve) => setImmediate(resolve));
 
@@ -1271,8 +1271,8 @@ describe("subagents-models slash command", { skip: !available ? "slash-commands.
 	});
 
 	it("passes an optional builtin filter", async () => {
-		const { params } = await captureSlashCommandParams("subagents-models", "scout", process.cwd());
-		assert.deepEqual(params, { action: "models", agent: "scout" });
+		const { params } = await captureSlashCommandParams("subagents-models", "explorer", process.cwd());
+		assert.deepEqual(params, { action: "models", agent: "explorer" });
 	});
 
 	it("rejects invalid builtin filters without launching", async () => {
@@ -1294,8 +1294,8 @@ describe("subagents-models slash command", { skip: !available ? "slash-commands.
 			};
 
 			registerSlashCommands!(pi, createState(process.cwd()));
-			const completions = commands.get("subagents-models")!.getArgumentCompletions!("sc") as Array<{ value: string; label: string }>;
-			assert.deepEqual(completions.map((completion) => completion.value), ["scout"]);
+			const completions = commands.get("subagents-models")!.getArgumentCompletions!("ex") as Array<{ value: string; label: string }>;
+			assert.deepEqual(completions.map((completion) => completion.value), ["explorer"]);
 		});
 	});
 });
@@ -1421,7 +1421,7 @@ describe("subagent profiles slash commands", { skip: !available ? "slash-command
 			const profilesDir = path.join(process.env.HOME!, ".selesai", "agent", "profiles", "pi-subagents");
 			fs.mkdirSync(profilesDir, { recursive: true });
 			fs.writeFileSync(path.join(profilesDir, "openai-codex.quota.json"), JSON.stringify({
-				subagents: { agentOverrides: { worker: { model: "gpt-5.4:high" } } },
+				subagents: { agentOverrides: { builder: { model: "gpt-5.4:high" } } },
 			}, null, 2));
 			const sent: unknown[] = [];
 			const commands = new Map<string, RegisteredSlashCommand>();
@@ -1593,7 +1593,7 @@ describe("subagents admin slash command", { skip: !available ? "slash-commands.t
 					notify: (message) => notifications.push(message),
 				}));
 
-				await commands.get("subagents")!.handler("worker model", createCommandContext({
+				await commands.get("subagents")!.handler("builder model", createCommandContext({
 					cwd: root,
 					hasUI: true,
 					modelRegistry: { getAvailable: () => [{ provider: "test", id: "new-model", reasoning: true }] },
@@ -1611,13 +1611,13 @@ describe("subagents admin slash command", { skip: !available ? "slash-commands.t
 	it("reports duplicate names as ambiguous without UI", async () => {
 		await withIsolatedHome(async () => {
 			await withTempProject("pi-subagents-admin-ambiguous-", async (root) => {
-				fs.writeFileSync(path.join(root, ".selesai", "agents", "worker.md"), "---\nname: worker\ndescription: Project worker\n---\n\nWork.\n", "utf-8");
+				fs.writeFileSync(path.join(root, ".selesai", "agents", "builder.md"), "---\nname: builder\ndescription: Project builder\n---\n\nWork.\n", "utf-8");
 				const sent: unknown[] = [];
 				const commands = registerAdmin(sent);
-				await commands.get("subagents")!.handler("worker", createCommandContext({ cwd: root }));
+				await commands.get("subagents")!.handler("builder", createCommandContext({ cwd: root }));
 				assert.equal(sent.length, 1);
 				const content = (sent[0] as { content?: string }).content ?? "";
-				assert.match(content, /Subagent 'worker' is ambiguous/);
+				assert.match(content, /Subagent 'builder' is ambiguous/);
 				assert.match(content, /project:/);
 				assert.match(content, /builtin:/);
 			});
@@ -1729,7 +1729,7 @@ describe("subagents admin slash command", { skip: !available ? "slash-commands.t
 				fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
 				fs.writeFileSync(settingsPath, JSON.stringify({ subagents: { disableThinking: true } }, null, 2), "utf-8");
 				const commands = registerAdmin([]);
-				await commands.get("subagents")!.handler("worker model", createCommandContext({
+				await commands.get("subagents")!.handler("builder model", createCommandContext({
 					cwd: root,
 					hasUI: true,
 					modelRegistry: { getAvailable: () => [{ provider: "test", id: "new-model", reasoning: true }] },
@@ -1738,7 +1738,7 @@ describe("subagents admin slash command", { skip: !available ? "slash-commands.t
 
 				assert.deepEqual(JSON.parse(fs.readFileSync(settingsPath, "utf-8")).subagents, {
 					disableThinking: true,
-					agentOverrides: { worker: { model: "test/new-model" } },
+					agentOverrides: { builder: { model: "test/new-model" } },
 				});
 			});
 		});
@@ -2063,7 +2063,7 @@ describe("subagents-doctor slash command", { skip: !available ? "slash-commands.
 
 		assert.equal(opened, 2);
 		assert.match(rendered, /Subagent fleet/);
-		assert.match(rendered, /inspection only/);
+		assert.match(rendered, /live controls/);
 	});
 
 	it("routes subagents-stop with an id directly to the stop action", async () => {
@@ -2071,6 +2071,66 @@ describe("subagents-doctor slash command", { skip: !available ? "slash-commands.
 		assert.deepEqual(params, { action: "stop", id: "run-123" });
 	});
 
+	it("detaches the latest active foreground single run without terminating it", async () => {
+		const commands = new Map<string, RegisteredSlashCommand>();
+		const sent: unknown[] = [];
+		const state = createState(process.cwd());
+		let detached = 0;
+		state.foregroundControls.set("foreground-single", {
+			runId: "foreground-single",
+			mode: "single",
+			startedAt: 1,
+			updatedAt: 2,
+			detach: () => { detached++; return true; },
+		});
+		state.foregroundControls.set("newer-parallel", {
+			runId: "newer-parallel",
+			mode: "parallel",
+			startedAt: 2,
+			updatedAt: 3,
+		});
+		state.lastForegroundControlId = "newer-parallel";
+		registerSlashCommands!({
+			events: createEventBus(),
+			registerCommand(name: string, spec: RegisteredSlashCommand) { commands.set(name, spec); },
+			registerShortcut() {},
+			sendMessage(message: unknown) { sent.push(message); },
+		}, state);
+
+		await commands.get("subagents-detach")!.handler("", createCommandContext());
+
+		assert.equal(detached, 1);
+		const content = String((sent[0] as { content?: unknown }).content ?? "");
+		assert.match(content, /Detached foreground run foreground-single without terminating its child/);
+		assert.match(content, /does not daemonize the process or guarantee survival across Pi reload\/restart/);
+	});
+
+	it("reports missing and unsupported foreground detach targets", async () => {
+		const commands = new Map<string, RegisteredSlashCommand>();
+		const notifications: string[] = [];
+		const state = createState(process.cwd());
+		state.foregroundControls.set("parallel-run", {
+			runId: "parallel-run",
+			mode: "parallel",
+			startedAt: 1,
+			updatedAt: 1,
+			detach: () => true,
+		});
+		registerSlashCommands!({
+			events: createEventBus(),
+			registerCommand(name: string, spec: RegisteredSlashCommand) { commands.set(name, spec); },
+			registerShortcut() {},
+			sendMessage() {},
+		}, state);
+		const ctx = createCommandContext({ notify: (message) => notifications.push(message) });
+
+		await commands.get("subagents-detach")!.handler("missing", ctx);
+		await commands.get("subagents-detach")!.handler("parallel", ctx);
+
+		assert.match(notifications[0] ?? "", /No active foreground run found for 'missing'/);
+		assert.match(notifications[1] ?? "", /currently supports single-subagent runs only/);
+	});
+
 	it("prints exact stop commands when subagents-stop has no UI", async () => {
 		await withIsolatedHome(async () => {
 			const runId = `slash-stop-${Date.now().toString(36)}`;
@@ -2162,6 +2222,17 @@ describe("subagents-doctor slash command", { skip: !available ? "slash-commands.
 					cwd: root,
 					sessionId: "session-test",
 					jobs: [{
+						id: "job-1",
+						name: "early scout",
+						schedule: "+5m",
+						runAt: Date.now() + 300_000,
+						state: "scheduled",
+						createdAt: Date.now(),
+						updatedAt: Date.now(),
+						cwd: root,
+						sessionId: "session-test",
+						params: { agent: "scout", task: "soon", async: true },
+					}, {
 						id: "job-2",
 						name: "delayed worker",
 						schedule: "+10m",
@@ -2200,9 +2271,27 @@ describe("subagents-doctor slash command", { skip: !available ? "slash-commands.
 				await commands.get("subagents-stop")!.handler("", createCommandContext({
 					cwd: root,
 					hasUI: true,
-					custom: async () => ({
-						confirmed: true,
-						target: { kind: "scheduled", id: "job-2", label: "job-2", detail: "scheduled", actionLabel: "cancel scheduled run" },
+					custom: async (...args: unknown[]) => new Promise((resolve) => {
+						const factory = args[0] as (
+							tui: { requestRender(): void },
+							theme: { fg(key: string, text: string): string; bold(text: string): string },
+							keybindings: unknown,
+							done: (result: unknown) => void,
+						) => { handleInput(data: string): void; render(width: number): string[] };
+						const component = factory(
+							{ requestRender() {} },
+							{ fg(_key, text) { return text; }, bold(text) { return text; } },
+							{},
+							resolve,
+						);
+						assert.match(component.render(84).join("\n"), /↑↓\/jk select/);
+						component.handleInput("j");
+						assert.ok(component.render(84).some((line) => line.startsWith("›") && line.includes("job-2")));
+						component.handleInput("k");
+						assert.ok(component.render(84).some((line) => line.startsWith("›") && line.includes("job-1")));
+						component.handleInput("j");
+						component.handleInput("\r");
+						component.handleInput("y");
 					}),
 				}));
 

package/dist/extensions/pi-subagents/test/support/mock-pi-script.mjs

@@ -185,6 +185,14 @@ function writeStructuredOutputCapture(response) {
 	fs.writeFileSync(outputPath, JSON.stringify(response.structuredOutputCapture), "utf-8");
 }
 
+function writeRuntimeAcknowledgedExtensions(response) {
+	if (!Object.prototype.hasOwnProperty.call(response, "runtimeAcknowledgedExtensions")) return;
+	const outputPath = process.env.SELESAI_SUBAGENT_RUNTIME_ACKNOWLEDGED_EXTENSIONS;
+	if (!outputPath) return;
+	fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+	fs.writeFileSync(outputPath, JSON.stringify(response.runtimeAcknowledgedExtensions), "utf-8");
+}
+
 function writeToolDiagnostic(response) {
 	if (!Array.isArray(response.missingTools) || response.missingTools.length === 0) return;
 	const diagnosticPath = process.env.SELESAI_SUBAGENT_TOOL_DIAGNOSTIC_PATH;
@@ -327,11 +335,10 @@ async function main() {
 	}
 	writeSessionFile(args);
 	writeToolDiagnostic(response);
-	fs.writeFileSync(
-		path.join(queueDir, `call-${Date.now()}-${process.pid}-${Math.random().toString(16).slice(2)}.json`),
-		JSON.stringify({ args, systemPrompts: readSystemPromptRecords(args) }),
-		"utf-8",
-	);
+	const callPath = path.join(queueDir, `call-${Date.now()}-${process.pid}-${Math.random().toString(16).slice(2)}.json`);
+	const callTempPath = `${callPath}.tmp-${process.pid}-${Date.now()}`;
+	fs.writeFileSync(callTempPath, JSON.stringify({ args, systemPrompts: readSystemPromptRecords(args) }), "utf-8");
+	fs.renameSync(callTempPath, callPath);
 
 	if (typeof response.delay === "number" && response.delay > 0) {
 		await new Promise((resolve) => setTimeout(resolve, response.delay));
@@ -346,6 +353,7 @@ async function main() {
 
 	writeDeclaredFiles(response);
 	writeStructuredOutputCapture(response);
+	writeRuntimeAcknowledgedExtensions(response);
 
 	if (Array.isArray(response.steps) && response.steps.length > 0) {
 		for (const step of response.steps) {
@@ -384,6 +392,10 @@ async function main() {
 		await new Promise((resolve) => setTimeout(resolve, response.keepAliveAfterFinalMessageMs));
 	}
 
+	if (typeof response.signal === "string") {
+		process.kill(process.pid, response.signal);
+		return;
+	}
 	exitAfterFlush(typeof response.exitCode === "number" ? response.exitCode : 0);
 }
 

package/dist/extensions/pi-subagents/test/support/mock-pi.ts

@@ -7,6 +7,7 @@ interface MockPiResponse {
 	output?: string;
 	stderr?: string;
 	exitCode?: number;
+	signal?: NodeJS.Signals;
 	delay?: number;
 	waitForPath?: string;
 	keepAliveAfterFinalMessageMs?: number;
@@ -28,6 +29,7 @@ interface MockPiResponse {
 	writeFiles?: Array<{ path: string; content: string }>;
 	/** Writes the structured-output capture file without emitting a structured_output tool event. */
 	structuredOutputCapture?: unknown;
+	runtimeAcknowledgedExtensions?: unknown;
 }
 
 export interface MockPi {

package/dist/extensions/pi-subagents/test/support/real-session-runner.ts

@@ -1,4 +1,4 @@
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -47,6 +47,21 @@ export function subagentCall(args: Record<string, unknown>, id = "call-subagent-
 	return fauxToolCall("subagent", args, { id });
 }
 
+function resolvedSubagentResultText(resultText: string): string {
+	// Reference-first completion: the tool result carries "Output saved to:
+	// <path> (…)". Resolve the durable file so the scripted parent can relay the
+	// exact child output.
+	if (!resultText.includes("Output saved to: ")) return resultText;
+	const rest = resultText.split("Output saved to: ")[1];
+	if (!rest) return resultText;
+	const outputPath = rest.split(" (")[0];
+	try {
+		return readFileSync(outputPath, "utf-8");
+	} catch {
+		return resultText;
+	}
+}
+
 export function routeParentThroughSubagent(input: {
 	childMarker: string;
 	subagentArgs: Record<string, unknown>;
@@ -56,7 +71,8 @@ export function routeParentThroughSubagent(input: {
 		if (!isParent) return "Unexpected non-parent model call.";
 		const resultText = latestSubagentToolResultText(context.messages as Array<{ role?: string; toolName?: string; content?: unknown }>);
 		if (resultText !== undefined) {
-			return `Parent relays: ${resultText.includes(input.childMarker) ? input.childMarker : "CHILD_MISSING"}`;
+			const resolved = resolvedSubagentResultText(resultText);
+			return `Parent relays: ${resolved.includes(input.childMarker) ? input.childMarker : "CHILD_MISSING"}`;
 		}
 		return subagentCall(input.subagentArgs);
 	};

package/dist/extensions/pi-subagents/test/support/register-loader.mjs

@@ -1,13 +1,13 @@
 /**
  * Register the .js → .ts loader hook for integration tests.
  *
- * Usage: node --experimental-transform-types --import ./test/support/register-loader.mjs --test test/integration/*.test.ts
+ * Usage: node --experimental-strip-types --import ./test/support/register-loader.mjs --test test/integration/*.test.ts
  *
  * Handles two issues:
  * 1. Source files use .js import extensions (TypeScript ESM convention) but
  *    files on disk are .ts — the loader rewrites .js → .ts at resolve time.
- * 2. Some source files use TypeScript parameter properties (constructor(private x: T))
- *    which require --experimental-transform-types (not just strip-types).
+ * 2. Source stays within Node's erasable TypeScript syntax so the supported
+ *    --experimental-strip-types path is sufficient.
  */
 
 import { register } from "node:module";

package/dist/extensions/pi-subagents/test/unit/acceptance.test.ts

@@ -1046,7 +1046,9 @@ describe("acceptance gates", () => {
 			{ id: "release check", must: "second" },
 		] }).join("\n"), /acceptance\.criteria\[1\]\.id duplicates normalized criterion id 'release-check'/);
 		assert.match(validateAcceptanceInput({ criteria: [123] }).join("\n"), /acceptance\.criteria\[0\] must be a string or an object/);
-		assert.match(validateAcceptanceInput({ evidence: ["bogus"] }).join("\n"), /acceptance\.evidence\[0\] is not a supported evidence kind/);
+		assert.match(validateAcceptanceInput({ evidence: "commands-run" }).join("\n"), /acceptance\.evidence must be an array.*Supported evidence kinds:.*commands-run.*changed-files/s);
+		assert.match(validateAcceptanceInput({ evidence: ["bogus"] }).join("\n"), /acceptance\.evidence\[0\] "bogus" is not a supported evidence kind.*Supported evidence kinds:.*manual-notes.*Example:/s);
+		assert.match(validateAcceptanceInput({ criteria: [{ id: "ship", must: "ship", evidence: ["commands_run"] }] }).join("\n"), /acceptance\.criteria\[0\]\.evidence\[0\] "commands_run" is not a supported evidence kind.*Supported evidence kinds:/s);
 		assert.match(validateAcceptanceInput({ review: true }).join("\n"), /acceptance\.review must be false or an object/);
 		assert.match(validateAcceptanceInput({ review: { required: "yes" } }).join("\n"), /acceptance\.review\.required must be a boolean/);
 		assert.match(validateAcceptanceInput({ stopRules: [123] }).join("\n"), /acceptance\.stopRules\[0\] must be a string/);

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

@@ -177,7 +177,7 @@ describe("builtin agent disabling", () => {
 			{ cwd: tempProject, modelRegistry: { getAvailable: () => [] } },
 		));
 
-		assert.match(text, /Executable agents:\n- helper \(project\): Helper/);
+		assert.match(text, /Executable agents:\n- helper \(project, context: fresh\): Helper/);
 		assert.doesNotMatch(text, /Disabled builtins:/);
 		for (const name of disabledBuiltinNames) {
 			assert.doesNotMatch(text, new RegExp(`^- ${name} \\(builtin`, "m"));

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

@@ -6,7 +6,7 @@ import { afterEach, describe, it } from "node:test";
 import { handleManagementAction } from "../../src/agents/agent-management.ts";
 import { serializeAgent } from "../../src/agents/agent-serializer.ts";
 import { parseChain, serializeChain } from "../../src/agents/chain-serializer.ts";
-import { discoverAgents, discoverAgentsAll, type AgentConfig } from "../../src/agents/agents.ts";
+import { BUILTIN_AGENT_NAMES, discoverAgents, discoverAgentsAll, type AgentConfig } from "../../src/agents/agents.ts";
 import { parseFrontmatter } from "../../src/agents/frontmatter.ts";
 import { buildPiArgs } from "../../src/runs/shared/pi-args.ts";
 import { THINKING_LEVELS } from "../../src/shared/model-info.ts";
@@ -153,6 +153,47 @@ body`);
 	}));
 });
 
+describe("agent aliases", () => {
+	it("parses and serializes agent aliases", () => withTempHome(() => {
+		const project = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-alias-agent-"));
+		tempDirs.push(project);
+		writeAgent(path.join(project, ".selesai", "agents", "worker.md"), `---
+name: worker
+description: Worker
+aliases: shipper, tester, worker
+---
+body`);
+
+		const worker = discoverAgents(project, "both").agents.find((agent) => agent.name === "worker")!;
+		assert.deepEqual(worker.aliases, ["shipper", "tester"]);
+		assert.match(serializeAgent(worker), /^aliases: shipper, tester$/m);
+
+		const ctx = { cwd: project, modelRegistry: { getAvailable: () => [] } };
+		assert.match(handleManagementAction("list", {}, ctx).content[0]?.text ?? "", /aliases: shipper, tester/);
+		assert.match(handleManagementAction("get", { agent: "shipper" }, ctx).content[0]?.text ?? "", /Agent: worker/);
+	}));
+
+	it("reports management alias collisions as ambiguous", () => withTempHome(() => {
+		const project = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-alias-collision-"));
+		tempDirs.push(project);
+		writeAgent(path.join(project, ".selesai", "agents", "review-agent.md"), `---
+name: review-agent
+description: Custom reviewer
+aliases: developer
+---
+body`);
+
+		const ctx = { cwd: project, modelRegistry: { getAvailable: () => [] } };
+		const getResult = handleManagementAction("get", { agent: "developer" }, ctx);
+		assert.equal(getResult.isError, true);
+		assert.match(getResult.content[0]?.text ?? "", /Ambiguous agent alias or name 'developer': builder, review-agent|Ambiguous agent alias or name 'developer': review-agent, builder/);
+
+		const disableResult = handleManagementAction("disable", { agent: "developer" }, ctx);
+		assert.equal(disableResult.isError, true);
+		assert.match(disableResult.content[0]?.text ?? "", /Ambiguous agent alias 'developer': builder, review-agent|Ambiguous agent alias 'developer': review-agent, builder/);
+	}));
+});
+
 describe("agent simple-scalar list frontmatter", () => {
 	it("discovers newline block lists for all list fields and routes MCP tools", () => {
 		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-agent-block-list-frontmatter-"));
@@ -316,14 +357,54 @@ Do work
 		assert.equal(worker?.defaultContext, "fork");
 	});
 
-	it("loads packaged architect and recapper with fork defaultContext", () => {
+	it("loads builtin agents with the authoritative six-agent defaultContext map", () => {
 		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-builtin-default-context-"));
 		tempDirs.push(dir);
 		const agents = discoverAgentsAll(dir).builtin;
 
-		for (const name of ["architect", "recapper"]) {
+		const expected: Record<string, "fresh" | "fork"> = {
+			architect: "fork",
+			recapper: "fork",
+			builder: "fresh",
+			commentator: "fresh",
+			explorer: "fresh",
+			researcher: "fresh",
+		};
+		assert.deepEqual(
+			agents.map((agent) => agent.name).sort(),
+			[...BUILTIN_AGENT_NAMES].sort(),
+		);
+		for (const [name, context] of Object.entries(expected)) {
 			const agent = agents.find((candidate) => candidate.name === name);
-			assert.equal(agent?.defaultContext, "fork", `${name} should default to fork context`);
+			assert.equal(agent?.defaultContext, context, `${name} should default to ${context} context`);
+		}
+	});
+});
+
+describe("bundled agent descriptions and acceptance roles", () => {
+	it("survives discovery with declared descriptions and acceptance roles", () => {
+		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-bundled-catalog-roles-"));
+		tempDirs.push(dir);
+		const agents = discoverAgentsAll(dir).builtin;
+
+		const expected: Record<string, { description: string; acceptanceRole: "read-only" | "writer" }> = {
+			architect: { description: "Read-only architecture and implementation planning", acceptanceRole: "read-only" },
+			builder: { description: "Mutation-capable scoped implementation", acceptanceRole: "writer" },
+			commentator: { description: "Read-only evidence-based review", acceptanceRole: "read-only" },
+			explorer: { description: "Read-only local codebase reconnaissance", acceptanceRole: "read-only" },
+			recapper: { description: "Read-only handoff and context synthesis", acceptanceRole: "read-only" },
+			researcher: { description: "Read-only external and code-first research", acceptanceRole: "read-only" },
+		};
+
+		assert.deepEqual(
+			agents.map((agent) => agent.name).sort(),
+			[...BUILTIN_AGENT_NAMES].sort(),
+		);
+		for (const [name, expectedEntry] of Object.entries(expected)) {
+			const agent = agents.find((candidate) => candidate.name === name);
+			assert.ok(agent, `bundled agent ${name} not discovered`);
+			assert.equal(agent.description, expectedEntry.description, `${name} description`);
+			assert.equal(agent.acceptanceRole, expectedEntry.acceptanceRole, `${name} acceptanceRole`);
 		}
 	});
 });
@@ -603,6 +684,72 @@ Review nested project work.
 		assert.equal(agent.filePath, path.join(packageRoot, "agents", "reviewer.md"));
 	}));
 
+	it("keeps nearest project root discovery by default when a nested .pi exists", () => withTempHome(() => {
+		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-nearest-root-default-"));
+		tempDirs.push(dir);
+		const nested = path.join(dir, "packages", "app", "src");
+		const nestedConfigDir = path.join(dir, "packages", "app", ".selesai");
+		const packageRoot = path.join(dir, ".selesai", "npm", "node_modules", "outer-workflow");
+		fs.mkdirSync(nested, { recursive: true });
+		fs.mkdirSync(nestedConfigDir, { recursive: true });
+		fs.mkdirSync(path.join(dir, ".git"), { recursive: true });
+		writeJson(path.join(packageRoot, "package.json"), {
+			name: "outer-workflow",
+			"pi-subagents": { agents: ["./agents"] },
+		});
+		writeAgent(path.join(packageRoot, "agents", "planner.md"), `---
+name: planner
+package: outer-workflow
+description: Plan from the outer project package.
+---
+
+Plan outer project work.
+`);
+
+		const agent = discoverAgents(nested, "both").agents.find((candidate) => candidate.name === "outer-workflow.planner");
+		assert.equal(agent, undefined);
+	}));
+
+	it("can resolve project packages and overrides from the git root", () => withTempHome(() => {
+		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-git-root-resolution-"));
+		tempDirs.push(dir);
+		const nested = path.join(dir, "packages", "app", "src");
+		const nestedConfigDir = path.join(dir, "packages", "app", ".selesai");
+		const packageRoot = path.join(dir, ".selesai", "npm", "node_modules", "outer-workflow");
+		fs.mkdirSync(nested, { recursive: true });
+		fs.mkdirSync(nestedConfigDir, { recursive: true });
+		fs.writeFileSync(path.join(dir, ".git"), "gitdir: ../.git/worktrees/app\n", "utf-8");
+		writeJson(path.join(dir, ".selesai", "settings.json"), {
+			subagents: {
+				projectRootResolution: "git-root",
+				agentOverrides: {
+					commentator: { model: "openai/gpt-5.4" },
+				},
+			},
+		});
+		writeJson(path.join(packageRoot, "package.json"), {
+			name: "outer-workflow",
+			"pi-subagents": { agents: ["./agents"] },
+		});
+		writeAgent(path.join(packageRoot, "agents", "planner.md"), `---
+name: planner
+package: outer-workflow
+description: Plan from the outer project package.
+---
+
+Plan outer project work.
+`);
+
+		const agents = discoverAgents(nested, "both").agents;
+		const packageAgent = agents.find((candidate) => candidate.name === "outer-workflow.planner");
+		assert.ok(packageAgent);
+		assert.equal(packageAgent.source, "package");
+		assert.equal(packageAgent.filePath, path.join(packageRoot, "agents", "planner.md"));
+		const commentator = agents.find((candidate) => candidate.name === "commentator");
+		assert.equal(commentator?.model, "openai/gpt-5.4");
+		assert.equal(commentator?.override?.path, path.join(dir, ".selesai", "settings.json"));
+	}));
+
 	it("does not register legacy skill files from broad package agent roots", () => withTempHome(() => {
 		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-broad-package-skills-"));
 		tempDirs.push(dir);
@@ -1203,7 +1350,28 @@ Do work
 		}
 	});
 
-	it("builder includes the child-facing supervisor tool", () => {
+	it("keeps the bundled architect read-only for repository tools", () => {
+		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-builtin-architect-tools-"));
+		const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-builtin-architect-home-"));
+		tempDirs.push(dir, homeDir);
+		const previousHome = process.env.HOME;
+		const previousUserProfile = process.env.USERPROFILE;
+		try {
+			process.env.HOME = homeDir;
+			process.env.USERPROFILE = homeDir;
+			const architect = discoverAgentsAll(dir).builtin.find((candidate) => candidate.name === "architect");
+			assert.ok(architect);
+			assert.deepEqual(architect.tools, ["read", "grep", "find", "ls"]);
+			assert.equal(architect.acceptanceRole, "read-only");
+		} 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("builder builtin tools exclude the bridge-injected supervisor tool", () => {
 		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-builtin-supervisor-tool-"));
 		const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-builtin-supervisor-tool-home-"));
 		tempDirs.push(dir);
@@ -1216,7 +1384,31 @@ Do work
 			process.env.USERPROFILE = homeDir;
 			const agent = discoverAgentsAll(dir).builtin.find((candidate) => candidate.name === "builder");
 			assert.ok(agent, "builder builtin should be discovered");
-			assert.deepEqual(agent?.tools, ["read", "grep", "find", "ls", "bash", "edit", "write", "contact_supervisor"]);
+			assert.deepEqual(agent?.tools, ["read", "grep", "find", "ls", "bash", "edit", "write"]);
+			assert.equal(agent?.tools?.includes("contact_supervisor"), false);
+		} 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("researcher builtin routes grep.app tools into mcpDirectTools", () => {
+		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-builtin-researcher-tools-"));
+		const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-builtin-researcher-tools-home-"));
+		tempDirs.push(dir);
+		tempDirs.push(homeDir);
+		const previousHome = process.env.HOME;
+		const previousUserProfile = process.env.USERPROFILE;
+
+		try {
+			process.env.HOME = homeDir;
+			process.env.USERPROFILE = homeDir;
+			const agent = discoverAgentsAll(dir).builtin.find((candidate) => candidate.name === "researcher");
+			assert.ok(agent, "researcher builtin should be discovered");
+			assert.deepEqual(agent?.tools, ["read", "web_explore"]);
+			assert.deepEqual(agent?.mcpDirectTools, ["grep_app_search", "grep_app_fetch"]);
 		} finally {
 			if (previousHome === undefined) delete process.env.HOME;
 			else process.env.HOME = previousHome;