@selesai/code 0.5.27 → 0.5.29

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/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-frontmatter.test.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-"));
@@ -603,6 +644,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,6 +1310,27 @@ Do work
 		}
 	});
 
+	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 includes the child-facing 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-"));

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

@@ -3,7 +3,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { afterEach, beforeEach, describe, it } from "node:test";
-import { buildBuiltinOverrideConfig, discoverAgents, discoverAgentsAll, removeBuiltinAgentOverride } from "../../src/agents/agents.ts";
+import { buildBuiltinOverrideConfig, discoverAgents, discoverAgentsAll, removeBuiltinAgentOverride, saveBuiltinAgentOverride } from "../../src/agents/agents.ts";
 
 let tempHome = "";
 let tempProject = "";
@@ -178,6 +178,22 @@ describe("builtin agent overrides", () => {
 		assert.equal(agents.find((agent) => agent.name === "architect-copy")?.model, "deepseek-v4-flash");
 	});
 
+	it("overrides builtin and custom agent descriptions from settings", () => {
+		writeJson(path.join(tempHome, ".selesai", "agent", "settings.json"), {
+			subagents: {
+				agentOverrides: {
+					commentator: { description: " Priced commentator " },
+					implementer: { description: "Priced implementer" },
+				},
+			},
+		});
+		writeProjectAgent(tempProject, "implementer", `---\nname: implementer\ndescription: Original implementer\n---\n\nImplement it.\n`);
+
+		const agents = discoverAgents(tempProject, "both").agents;
+		assert.equal(agents.find((agent) => agent.name === "commentator")?.description, "Priced commentator");
+		assert.equal(agents.find((agent) => agent.name === "implementer")?.description, "Priced implementer");
+	});
+
 	it("applies user settings overrides to builtin agents", () => {
 		writeJson(path.join(tempHome, ".selesai", "agent", "settings.json"), {
 			subagents: {
@@ -625,6 +641,22 @@ describe("builtin agent overrides", () => {
 		);
 	});
 
+	it("surfaces malformed description override values", () => {
+		const settingsPath = path.join(tempHome, ".selesai", "agent", "settings.json");
+		for (const description of ["", 42]) {
+			writeJson(settingsPath, {
+				subagents: { agentOverrides: { commentator: { description } } },
+			});
+			assert.throws(
+				() => discoverAgents(tempProject, "both"),
+				(error: unknown) => error instanceof Error
+					&& error.message.includes(settingsPath)
+					&& error.message.includes("commentator")
+					&& error.message.includes("description"),
+			);
+		}
+	});
+
 	it("surfaces malformed completion guard override values", () => {
 		const settingsPath = path.join(tempHome, ".selesai", "agent", "settings.json");
 		writeJson(settingsPath, {
@@ -646,9 +678,10 @@ describe("builtin agent overrides", () => {
 		);
 	});
 
-	it("builds false sentinels when an override clears builtin fields", () => {
+	it("builds description changes and false sentinels when an override clears builtin fields", () => {
 		const override = buildBuiltinOverrideConfig(
 			{
+				description: "Base description",
 				model: "openai-codex/gpt-5.4-mini",
 				fallbackModels: ["openai/gpt-5-mini"],
 				thinking: "high",
@@ -665,6 +698,7 @@ describe("builtin agent overrides", () => {
 				completionGuard: false,
 			},
 			{
+				description: "Override description",
 				model: undefined,
 				fallbackModels: undefined,
 				thinking: undefined,
@@ -683,6 +717,7 @@ describe("builtin agent overrides", () => {
 		);
 
 		assert.deepEqual(override, {
+			description: "Override description",
 			model: false,
 			fallbackModels: false,
 			thinking: false,
@@ -695,5 +730,15 @@ describe("builtin agent overrides", () => {
 			subagentOnlyExtensions: false,
 			completionGuard: true,
 		});
+		assert.ok(override);
+		fs.mkdirSync(path.join(tempProject, ".selesai"), { recursive: true });
+		saveBuiltinAgentOverride(tempProject, "commentator", "project", override);
+		assert.equal(discoverAgents(tempProject, "both").agents.find((agent) => agent.name === "commentator")?.description, "Override description");
+
+		const whitespaceDescription = buildBuiltinOverrideConfig(
+			{ description: "Base description" },
+			{ description: "   " } as Parameters<typeof buildBuiltinOverrideConfig>[1],
+		);
+		assert.equal(whitespaceDescription, undefined);
 	});
 });

package/dist/extensions/pi-subagents/test/unit/async-recovery-descriptor.test.ts

@@ -0,0 +1,60 @@
+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 { describe, it } from "node:test";
+import { readAsyncRecoveryDescriptor } from "../../src/runs/background/async-resume.ts";
+
+describe("async recovery descriptor", () => {
+	it("accepts launchContractDigest written by async execution", () => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-async-recovery-digest-"));
+		try {
+			const digest = "launch-contract-digest";
+			fs.writeFileSync(path.join(root, "recovery-descriptor.json"), JSON.stringify({
+				version: 1,
+				launchContractDigest: digest,
+				sourceRunId: "run-digest",
+				agent: "worker",
+				cwd: root,
+				systemPromptMode: "replace",
+				inheritProjectContext: false,
+				inheritSkills: false,
+				outputMode: "inline",
+				maxSubagentDepth: 2,
+				share: false,
+			}), "utf-8");
+
+			const descriptor = readAsyncRecoveryDescriptor(root);
+
+			assert.equal(descriptor?.launchContractDigest, digest);
+		} finally {
+			fs.rmSync(root, { recursive: true, force: true });
+		}
+	});
+
+	it("rejects malformed launchContractDigest values", () => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-async-recovery-bad-digest-"));
+		try {
+			fs.writeFileSync(path.join(root, "recovery-descriptor.json"), JSON.stringify({
+				version: 1,
+				launchContractDigest: {},
+				sourceRunId: "run-digest",
+				agent: "worker",
+				cwd: root,
+				systemPromptMode: "replace",
+				inheritProjectContext: false,
+				inheritSkills: false,
+				outputMode: "inline",
+				maxSubagentDepth: 2,
+				share: false,
+			}), "utf-8");
+
+			assert.throws(
+				() => readAsyncRecoveryDescriptor(root),
+				/launchContractDigest must be a non-empty string/,
+			);
+		} finally {
+			fs.rmSync(root, { recursive: true, force: true });
+		}
+	});
+});