@selesai/code 0.9.11 → 0.9.12

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

@@ -178,6 +178,42 @@ describe("builtin agent overrides", () => {
 		assert.equal(worker.model, "deepseek-v4-pro");
 	});
 
+	it("applies default providers with per-agent overrides", () => {
+		fs.mkdirSync(path.join(tempProject, ".selesai"), { recursive: true });
+		writeJson(path.join(tempHome, ".selesai", "agent", "settings.json"), {
+			subagents: {
+				defaultModel: "llama-3",
+				defaultProvider: "gpu-a",
+				agentOverrides: {
+					worker: { defaultProvider: "gpu-b" },
+					reviewer: { defaultProvider: false },
+				},
+			},
+		});
+		writeJson(path.join(tempProject, ".selesai", "settings.json"), {
+			subagents: { defaultProvider: "gpu-project" },
+		});
+
+		const builtins = discoverAgentsAll(tempProject).builtin;
+		const scout = builtins.find((agent) => agent.name === "scout");
+		assert.equal(scout?.model, "llama-3");
+		assert.equal(scout?.modelProvider, "gpu-project");
+		assert.equal(scout?.modelSource?.defaultProvider, "gpu-project");
+		assert.equal(builtins.find((agent) => agent.name === "worker")?.modelProvider, "gpu-b");
+		assert.equal(builtins.find((agent) => agent.name === "reviewer")?.modelProvider, undefined);
+	});
+
+	it("applies default providers to custom agent frontmatter models", () => {
+		writeJson(path.join(tempHome, ".selesai", "agent", "settings.json"), {
+			subagents: { defaultProvider: "gpu-a" },
+		});
+		writeProjectAgent(tempProject, "worker", `---\nname: worker\ndescription: Project worker\nmodel: llama-3\n---\n\nWork.\n`);
+
+		const worker = discoverAgents(tempProject, "both").agents.find((agent) => agent.name === "worker");
+		assert.equal(worker?.model, "llama-3");
+		assert.equal(worker?.modelProvider, "gpu-a");
+	});
+
 	it("applies subagents.defaultThinking only when thinking is unset", () => {
 		writeJson(path.join(tempHome, ".selesai", "agent", "settings.json"), {
 			subagents: {
@@ -239,6 +275,27 @@ describe("builtin agent overrides", () => {
 		}
 	});
 
+	it("surfaces malformed default provider settings", () => {
+		const settingsPath = path.join(tempHome, ".selesai", "agent", "settings.json");
+		for (const defaultProvider of ["", 42]) {
+			writeJson(settingsPath, { subagents: { defaultProvider } });
+			assert.throws(
+				() => discoverAgents(tempProject, "both"),
+				(error: unknown) => error instanceof Error
+					&& error.message.includes(settingsPath)
+					&& error.message.includes("defaultProvider"),
+			);
+		}
+		writeJson(settingsPath, { subagents: { agentOverrides: { worker: { defaultProvider: "" } } } });
+		assert.throws(
+			() => discoverAgents(tempProject, "both"),
+			(error: unknown) => error instanceof Error
+				&& error.message.includes(settingsPath)
+				&& error.message.includes("worker")
+				&& error.message.includes("defaultProvider"),
+		);
+	});
+
 	it("applies subagents.defaultModel to custom agents without a frontmatter model", () => {
 		writeJson(path.join(tempHome, ".selesai", "agent", "settings.json"), {
 			subagents: {
@@ -277,9 +334,10 @@ describe("builtin agent overrides", () => {
 	it("applies user settings overrides to builtin agents", () => {
 		writeJson(path.join(tempHome, ".selesai", "agent", "settings.json"), {
 			subagents: {
-				agentOverrides: {
+					agentOverrides: {
 					reviewer: {
 						model: "openai/gpt-5.4",
+						fast: true,
 						thinking: "xhigh",
 						systemPromptMode: "replace",
 						inheritProjectContext: true,
@@ -296,6 +354,7 @@ describe("builtin agent overrides", () => {
 		assert.ok(reviewer);
 		assert.equal(reviewer.source, "builtin");
 		assert.equal(reviewer.model, "openai/gpt-5.4");
+		assert.equal(reviewer.fast, true);
 		assert.equal(reviewer.thinking, "xhigh");
 		assert.equal(reviewer.systemPromptMode, "replace");
 		assert.equal(reviewer.inheritProjectContext, true);
@@ -420,6 +479,86 @@ describe("builtin agent overrides", () => {
 		assert.equal(reviewer.override?.path, path.join(tempProject, ".selesai", "settings.json"));
 	});
 
+	it("layers a project override on top of a user override for a custom agent instead of discarding it", () => {
+		// Regression test: a custom agent (e.g. a reviewer persona shipped as a .md
+		// file with no model/thinking/fallbackModels in frontmatter) that gets its
+		// model pin exclusively from a *user*-scope agentOverrides entry must keep
+		// that pin when a *project*-scope override adds an unrelated field (here:
+		// subagentOnlyExtensions). Previously the project override for this agent
+		// name replaced the user override wholesale, silently dropping model /
+		// thinking / fallbackModels with no error.
+		writeJson(path.join(tempHome, ".selesai", "agent", "settings.json"), {
+			subagents: {
+				agentOverrides: {
+					"persona-reviewer": {
+						model: "anthropic/claude-opus-4-8",
+						thinking: "high",
+						fallbackModels: ["anthropic/claude-sonnet-4-6"],
+					},
+				},
+			},
+		});
+		fs.mkdirSync(path.join(tempProject, ".selesai"), { recursive: true });
+		writeJson(path.join(tempProject, ".selesai", "settings.json"), {
+			subagents: {
+				agentOverrides: {
+					"persona-reviewer": {
+						subagentOnlyExtensions: ["./tools/child-only.ts"],
+					},
+				},
+			},
+		});
+		writeUserAgent(tempHome, "persona-reviewer", `---\nname: persona-reviewer\ndescription: Shared review persona\n---\n\nReview the diff.\n`);
+
+		const reviewer = discoverAgents(tempProject, "both").agents.find((agent) => agent.name === "persona-reviewer");
+		assert.ok(reviewer);
+		assert.equal(reviewer.model, "anthropic/claude-opus-4-8");
+		assert.equal(reviewer.thinking, "high");
+		assert.deepEqual(reviewer.fallbackModels, ["anthropic/claude-sonnet-4-6"]);
+		assert.deepEqual(reviewer.subagentOnlyExtensions, ["./tools/child-only.ts"]);
+		assert.equal(reviewer.override?.scope, "project");
+	});
+
+	it("lets a project override flip `disabled` on a custom agent even after a user override already set it", () => {
+		// Regression test for a bug caught in review of the layering fix above:
+		// applyCustomAgentOverride's `disabled` handling used a stray
+		// `agent.disabled === undefined` guard (a no-op before layering existed,
+		// since this function only ever ran once against the pristine base
+		// agent). Once user-then-project layering was introduced, that guard
+		// silently blocked the project override from ever changing `disabled`
+		// once the user override had already set it — breaking this PR's own
+		// "project wins" precedence for that one field. Cover both directions.
+		writeJson(path.join(tempHome, ".selesai", "agent", "settings.json"), {
+			subagents: {
+				agentOverrides: {
+					"disable-flip-a": { disabled: true },
+					"disable-flip-b": { disabled: false },
+				},
+			},
+		});
+		fs.mkdirSync(path.join(tempProject, ".selesai"), { recursive: true });
+		writeJson(path.join(tempProject, ".selesai", "settings.json"), {
+			subagents: {
+				agentOverrides: {
+					"disable-flip-a": { disabled: false },
+					"disable-flip-b": { disabled: true },
+				},
+			},
+		});
+		writeUserAgent(tempHome, "disable-flip-a", `---\nname: disable-flip-a\ndescription: User disables, project re-enables\n---\n\nBody.\n`);
+		writeUserAgent(tempHome, "disable-flip-b", `---\nname: disable-flip-b\ndescription: User enables, project disables\n---\n\nBody.\n`);
+
+		// discoverAgents filters out agents whose final `.disabled` resolves to
+		// true (agents.ts: `.filter((agent) => agent.disabled !== true)`), so
+		// presence/absence in the returned list is the observable signal here,
+		// not a `.disabled` property on the result.
+		const agents = discoverAgents(tempProject, "both").agents;
+		const flipA = agents.find((agent) => agent.name === "disable-flip-a");
+		const flipB = agents.find((agent) => agent.name === "disable-flip-b");
+		assert.ok(flipA, "project override (disabled: false) must win over user override (disabled: true), so the agent stays enabled and listed");
+		assert.equal(flipB, undefined, "project override (disabled: true) must win over user override (disabled: false), so the agent ends up disabled and unlisted");
+	});
+
 	it("applies acceptance role precedence and false clearing to builtin and custom agents", () => {
 		writeJson(path.join(tempHome, ".selesai", "agent", "settings.json"), {
 			subagents: {
@@ -510,8 +649,12 @@ describe("builtin agent overrides", () => {
 			subagents: {
 				agentOverrides: {
 					implementer: {
+						output: "artifacts/implementer.md",
+						outputMode: "file-only",
+						defaultReads: ["CONTEXT.md", "docs/spec.md"],
 						model: "anthropic/claude-sonnet-4-6",
 						fallbackModels: ["openai/gpt-5-mini"],
+						fast: true,
 						thinking: "high",
 						systemPromptMode: "append",
 						inheritProjectContext: true,
@@ -531,8 +674,12 @@ describe("builtin agent overrides", () => {
 		const implementer = discoverAgents(tempProject, "both").agents.find((agent) => agent.name === "implementer");
 		assert.ok(implementer);
 		assert.equal(implementer.source, "project");
+		assert.equal(implementer.output, "artifacts/implementer.md");
+		assert.equal(implementer.outputMode, "file-only");
+		assert.deepEqual(implementer.defaultReads, ["CONTEXT.md", "docs/spec.md"]);
 		assert.equal(implementer.model, "anthropic/claude-sonnet-4-6");
 		assert.deepEqual(implementer.fallbackModels, ["openai/gpt-5-mini"]);
+		assert.equal(implementer.fast, true);
 		assert.equal(implementer.thinking, "high");
 		assert.equal(implementer.systemPromptMode, "append");
 		assert.equal(implementer.inheritProjectContext, true);
@@ -577,16 +724,18 @@ describe("builtin agent overrides", () => {
 	it("prefers project agentOverrides over user agentOverrides on a custom project agent", () => {
 		fs.mkdirSync(path.join(tempProject, ".selesai"), { recursive: true });
 		writeJson(path.join(tempHome, ".selesai", "agent", "settings.json"), {
-			subagents: { agentOverrides: { implementer: { model: "anthropic/claude-sonnet-4-6" } } },
+			subagents: { agentOverrides: { implementer: { model: "anthropic/claude-sonnet-4-6", output: "user.md", defaultReads: ["user.md"] } } },
 		});
 		writeJson(path.join(tempProject, ".selesai", "settings.json"), {
-			subagents: { agentOverrides: { implementer: { model: "openai/gpt-5.4" } } },
+			subagents: { agentOverrides: { implementer: { model: "openai/gpt-5.4", output: "project.md", defaultReads: ["project.md"] } } },
 		});
 		writeProjectAgent(tempProject, "implementer", `---\nname: implementer\ndescription: TDD implementer\n---\n\nDrive the failing test first.\n`);
 
 		const implementer = discoverAgents(tempProject, "both").agents.find((agent) => agent.name === "implementer");
 		assert.ok(implementer);
 		assert.equal(implementer.model, "openai/gpt-5.4");
+		assert.equal(implementer.output, "project.md");
+		assert.deepEqual(implementer.defaultReads, ["project.md"]);
 		assert.equal(implementer.override?.scope, "project");
 	});
 
@@ -596,7 +745,11 @@ describe("builtin agent overrides", () => {
 			subagents: {
 				agentOverrides: {
 					implementer: {
+						output: "artifacts/override.md",
+						outputMode: "file-only",
+						defaultReads: ["override.md"],
 						model: "anthropic/claude-sonnet-4-6",
+						fast: true,
 						thinking: "high",
 						tools: ["bash"],
 						skills: ["override-skill"],
@@ -608,11 +761,15 @@ describe("builtin agent overrides", () => {
 				},
 			},
 		});
-		writeProjectAgent(tempProject, "implementer", `---\nname: implementer\ndescription: TDD implementer\nmodel: google/gemini-3-pro\nthinking: medium\ntools: read, mcp:local_tool\nskills: agent-skill\ninheritProjectContext: false\ndefaultContext: fresh\nacceptanceRole: read-only\ncompletionGuard: false\n---\n\nDrive the failing test first.\n`);
+		writeProjectAgent(tempProject, "implementer", `---\nname: implementer\ndescription: TDD implementer\noutput: artifacts/explicit.md\noutputMode: inline\ndefaultReads: explicit.md\nmodel: google/gemini-3-pro\nfast: false\nthinking: medium\ntools: read, mcp:local_tool\nskills: agent-skill\ninheritProjectContext: false\ndefaultContext: fresh\nacceptanceRole: read-only\ncompletionGuard: false\n---\n\nDrive the failing test first.\n`);
 
 		const implementer = discoverAgents(tempProject, "both").agents.find((agent) => agent.name === "implementer");
 		assert.ok(implementer);
+		assert.equal(implementer.output, "artifacts/explicit.md");
+		assert.equal(implementer.outputMode, "inline");
+		assert.deepEqual(implementer.defaultReads, ["explicit.md"]);
 		assert.equal(implementer.model, "google/gemini-3-pro");
+		assert.equal(implementer.fast, false);
 		assert.equal(implementer.thinking, "medium");
 		assert.deepEqual(implementer.tools, ["read"]);
 		assert.deepEqual(implementer.mcpDirectTools, ["local_tool"]);
@@ -624,6 +781,28 @@ describe("builtin agent overrides", () => {
 		assert.equal(implementer.override, undefined);
 	});
 
+	it("keeps explicit output and defaultReads frontmatter when overrides clear them", () => {
+		fs.mkdirSync(path.join(tempProject, ".selesai"), { recursive: true });
+		writeJson(path.join(tempProject, ".selesai", "settings.json"), {
+			subagents: { agentOverrides: { implementer: { output: false, defaultReads: false } } },
+		});
+		writeProjectAgent(tempProject, "implementer", `---\nname: implementer\ndescription: TDD implementer\noutput: explicit.md\ndefaultReads: explicit.md\n---\n\nDrive the failing test first.\n`);
+
+		const implementer = discoverAgents(tempProject, "both").agents.find((agent) => agent.name === "implementer");
+		assert.equal(implementer?.output, "explicit.md");
+		assert.deepEqual(implementer?.defaultReads, ["explicit.md"]);
+	});
+
+	it("keeps an explicit empty defaultReads override distinct from false", () => {
+		writeJson(path.join(tempHome, ".selesai", "agent", "settings.json"), {
+			subagents: { agentOverrides: { implementer: { defaultReads: [] } } },
+		});
+		writeProjectAgent(tempProject, "implementer", `---\nname: implementer\ndescription: TDD implementer\n---\n\nDrive the failing test first.\n`);
+
+		const implementer = discoverAgents(tempProject, "both").agents.find((agent) => agent.name === "implementer");
+		assert.deepEqual(implementer?.defaultReads, []);
+	});
+
 	it("leaves a custom agent untouched when no agentOverrides entry matches its name", () => {
 		writeJson(path.join(tempHome, ".selesai", "agent", "settings.json"), {
 			subagents: { agentOverrides: { reviewer: { model: "openai/gpt-5.4" } } },
@@ -758,10 +937,71 @@ describe("builtin agent overrides", () => {
 		);
 	});
 
+	it("rejects unsupported outputMode override values", () => {
+		const settingsPath = path.join(tempHome, ".selesai", "agent", "settings.json");
+		for (const outputMode of ["artifact-only", false]) {
+			writeJson(settingsPath, {
+				subagents: {
+					agentOverrides: {
+						reviewer: { outputMode },
+					},
+				},
+			});
+
+			assert.throws(
+				() => discoverAgents(tempProject, "both"),
+				(error: unknown) => error instanceof Error
+					&& error.message.includes(settingsPath)
+					&& error.message.includes("reviewer")
+					&& error.message.includes("outputMode"),
+			);
+		}
+	});
+
+	it("applies output and defaultReads overrides to bundled and package agents and supports false clears", () => {
+		const packageRoot = path.join(tempProject, "package-agents");
+		fs.mkdirSync(path.join(packageRoot, "agents"), { recursive: true });
+		writeJson(path.join(packageRoot, "package.json"), { "pi-subagents": { agents: ["agents"] } });
+		fs.writeFileSync(path.join(packageRoot, "agents", "package-scout.md"), `---\nname: package-scout\ndescription: Package scout\n---\n\nScout the package.\n`, "utf-8");
+		writeJson(path.join(tempProject, ".selesai", "settings.json"), {
+			packages: [packageRoot],
+			subagents: { agentOverrides: { "package-scout": { output: "package.md", defaultReads: ["PACKAGE.md"] } } },
+		});
+		writeJson(path.join(tempHome, ".selesai", "agent", "settings.json"), {
+			subagents: {
+				agentOverrides: {
+					scout: { output: "research-scout-results.md", defaultReads: ["AGENTS.md"] },
+					reviewer: { output: false, defaultReads: false },
+				},
+			},
+		});
+
+		const agents = discoverAgents(tempProject, "both").agents;
+		assert.equal(agents.find((agent) => agent.name === "scout")?.output, "research-scout-results.md");
+		assert.deepEqual(agents.find((agent) => agent.name === "scout")?.defaultReads, ["AGENTS.md"]);
+		assert.equal(agents.find((agent) => agent.name === "reviewer")?.output, undefined);
+		assert.equal(agents.find((agent) => agent.name === "reviewer")?.defaultReads, undefined);
+		assert.equal(agents.find((agent) => agent.name === "package-scout")?.output, "package.md");
+		assert.deepEqual(agents.find((agent) => agent.name === "package-scout")?.defaultReads, ["PACKAGE.md"]);
+	});
+
+	it("surfaces malformed output and defaultReads override values", () => {
+		const settingsPath = path.join(tempHome, ".selesai", "agent", "settings.json");
+		for (const [field, value] of [["output", 42], ["output", ""], ["output", "  "], ["defaultReads", ["ok", 42]]] as const) {
+			writeJson(settingsPath, { subagents: { agentOverrides: { reviewer: { [field]: value } } } });
+			assert.throws(
+				() => discoverAgents(tempProject, "both"),
+				(error: unknown) => error instanceof Error && error.message.includes(settingsPath) && error.message.includes("reviewer") && error.message.includes(field),
+			);
+		}
+	});
+
 	it("builds description changes and false sentinels when an override clears builtin fields", () => {
 		const override = buildBuiltinOverrideConfig(
 			{
 				description: "Base description",
+				output: "base-output.md",
+				defaultReads: ["base-read.md"],
 				model: "openai-codex/gpt-5.4-mini",
 				fallbackModels: ["openai/gpt-5-mini"],
 				thinking: "high",
@@ -779,6 +1019,8 @@ describe("builtin agent overrides", () => {
 			},
 			{
 				description: "Override description",
+				output: undefined,
+				defaultReads: undefined,
 				model: undefined,
 				fallbackModels: undefined,
 				thinking: undefined,
@@ -798,6 +1040,8 @@ describe("builtin agent overrides", () => {
 
 		assert.deepEqual(override, {
 			description: "Override description",
+			output: false,
+			defaultReads: false,
 			model: false,
 			fallbackModels: false,
 			thinking: false,
@@ -813,8 +1057,16 @@ describe("builtin agent overrides", () => {
 		assert.ok(override);
 		fs.mkdirSync(path.join(tempProject, ".selesai"), { recursive: true });
 		saveBuiltinAgentOverride(tempProject, "reviewer", "project", override);
+		const savedOverride = JSON.parse(fs.readFileSync(path.join(tempProject, ".selesai", "settings.json"), "utf-8"));
+		assert.equal(savedOverride.subagents.agentOverrides.reviewer.output, false);
+		assert.equal(savedOverride.subagents.agentOverrides.reviewer.defaultReads, false);
 		assert.equal(discoverAgents(tempProject, "both").agents.find((agent) => agent.name === "reviewer")?.description, "Override description");
 
+		saveBuiltinAgentOverride(tempProject, "scout", "project", { output: "research.md", defaultReads: ["CONTEXT.md"] });
+		const scout = discoverAgents(tempProject, "both").agents.find((agent) => agent.name === "scout");
+		assert.equal(scout?.output, "research.md");
+		assert.deepEqual(scout?.defaultReads, ["CONTEXT.md"]);
+
 		const whitespaceDescription = buildBuiltinOverrideConfig(
 			{ description: "Base description" },
 			{ description: "   " } as Parameters<typeof buildBuiltinOverrideConfig>[1],

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

@@ -11,7 +11,7 @@ import {
 	getProjectChainRunsDir,
 	getProjectSubagentsDir,
 } from "../../src/shared/artifacts.ts";
-import { CHAIN_RUNS_DIR } from "../../src/shared/types.ts";
+import { CHAIN_RUNS_DIR, TEMP_ARTIFACTS_DIR } from "../../src/shared/types.ts";
 
 describe("project-local artifact paths", () => {
 	const tempDirs: string[] = [];
@@ -32,7 +32,7 @@ describe("project-local artifact paths", () => {
 		assert.match(getProjectArtifactPackagingWarning(packageDir({ name: "unsafe" })) ?? "", /\.npmignore/);
 		assert.equal(getProjectArtifactPackagingWarning(packageDir({ name: "gitignored" }, { name: ".gitignore", content: ".pi-subagents/\n" })), undefined);
 		assert.equal(getProjectArtifactPackagingWarning(packageDir({ name: "globignored" }, { name: ".npmignore", content: "**/.pi-subagents/**\n" })), undefined);
-		assert.equal(getProjectArtifactPackagingWarning(packageDir({ name: "classignored" }, { name: ".npmignore", content: "[.]pi-subagents/**\n" })), undefined);
+		assert.equal(getProjectArtifactPackagingWarning(packageDir({ name: "classignored" }, { name: ".npmignore", content: "[.]pi/subagents/**\n" })), undefined);
 		assert.match(getProjectArtifactPackagingWarning(packageDir({ name: "explicit-files-over-ignore", files: [".pi-subagents/**"] }, { name: ".npmignore", content: ".pi-subagents/\n" })) ?? "", /artifactDir/);
 		assert.equal(getProjectArtifactPackagingWarning(packageDir({ name: "restricted", files: ["src/**"] })), undefined);
 		assert.equal(getProjectArtifactPackagingWarning(packageDir({ name: "malformed-pattern", files: ["[z-a]"] })), undefined);
@@ -53,24 +53,26 @@ describe("project-local artifact paths", () => {
 		assert.match(getProjectArtifactPackagingWarning(packageDir({ name: "chain-runs-directory-included", files: [".pi-subagents/chain-runs"] })) ?? "", /artifactDir/);
 	});
 
-	it("places generated subagent files under .pi-subagents for a project cwd", () => {
+	it("keeps project-scoped paths available as an explicit opt-in", () => {
 		const cwd = path.join("tmp", "repo");
 		assert.equal(getProjectSubagentsDir(cwd), path.join(cwd, ".pi-subagents"));
 		assert.equal(getProjectArtifactsDir(cwd), path.join(cwd, ".pi-subagents", "artifacts"));
 		assert.equal(getProjectChainRunsDir(cwd), path.join(cwd, ".pi-subagents", "chain-runs"));
-		assert.equal(getArtifactsDir(null, cwd), path.join(cwd, ".pi-subagents", "artifacts"));
+		assert.equal(getArtifactsDir(null, cwd, "project"), path.join(cwd, ".pi-subagents", "artifacts"));
 	});
 
 	it("routes chain scratch files according to the artifact preference", () => {
 		const cwd = path.join("tmp", "repo");
-		assert.equal(getChainRunsDir(cwd), getProjectChainRunsDir(cwd));
+		assert.equal(getChainRunsDir(cwd), CHAIN_RUNS_DIR);
 		assert.equal(getChainRunsDir(cwd, "project"), getProjectChainRunsDir(cwd));
 		assert.equal(getChainRunsDir(cwd, "session"), CHAIN_RUNS_DIR);
 		assert.equal(getChainRunsDir(cwd, "temp"), CHAIN_RUNS_DIR);
 	});
 
-	it("keeps the session artifact fallback when no project cwd is available", () => {
+	it("defaults artifacts to the session directory and falls back to temp", () => {
+		const cwd = path.join("tmp", "repo");
 		const sessionFile = path.join("tmp", "sessions", "parent.jsonl");
-		assert.equal(getArtifactsDir(sessionFile), path.join("tmp", "sessions", "subagent-artifacts"));
+		assert.equal(getArtifactsDir(sessionFile, cwd), path.join("tmp", "sessions", "subagent-artifacts"));
+		assert.equal(getArtifactsDir(null, cwd), path.join(TEMP_ARTIFACTS_DIR));
 	});
 });

package/dist/extensions/pi-subagents/test/unit/async-interrupt-action.test.ts

@@ -4,10 +4,10 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { describe, it } from "node:test";
 import { acquireActiveAsyncCapacity } from "../../src/runs/background/active-async-capacity.ts";
-import { consumeSteerRequests, consumeSteerRequestsFromDir, stepSteerInboxDir, writeSteerAck } from "../../src/runs/background/control-channel.ts";
+import { consumeSteerRequests, consumeSteerRequestsFromDir, consumeStopRequestPayload, stepSteerInboxDir, writeSteerAck } from "../../src/runs/background/control-channel.ts";
 import { listAsyncRuns } from "../../src/runs/background/async-status.ts";
 import { inspectSubagentStatus } from "../../src/runs/background/run-status.ts";
-import { createSubagentExecutor } from "../../src/runs/foreground/subagent-executor.ts";
+import { createSubagentExecutor, steerWorkflowChildByKey } from "../../src/runs/foreground/subagent-executor.ts";
 import { steerWorkflowForegroundTarget, workflowForegroundSteeringDir } from "../../src/runs/foreground/workflow-foreground-steering.ts";
 import { ASYNC_DIR, RESULTS_DIR, type SubagentState } from "../../src/shared/types.ts";
 
@@ -215,11 +215,108 @@ describe("async interrupt action", () => {
 			assert.equal(result.details.steering?.state, "delivered");
 			assert.equal(result.details.steering?.sourceRunId, childRunId);
 			assert.equal(request.message, "Focus on the failing test.");
+			assert.match(text(result), /Message: "Focus on the failing test\."/);
 		} finally {
 			cleanup(workflowRunId, asyncDir);
 		}
 	});
 
+	it("steers a foreground workflow child by stable key", async () => {
+		const state = createState();
+		const workflowRunId = `workflow-key-foreground-${Date.now().toString(36)}`;
+		const childRunId = `${workflowRunId}-writer`;
+		const asyncDir = createRunningAsync(state, workflowRunId, { track: false, mode: "workflow" });
+		const routeDir = createWorkflowForegroundControl(state, workflowRunId, childRunId);
+		try {
+			const action = steerWorkflowChildByKey({ state, workflowRunId, key: childRunId, message: "Focus on the contract.", options: { ackTimeoutMs: 500 } });
+			const request = await waitUntil(() => {
+				const inbox = stepSteerInboxDir(routeDir, 0);
+				const entry = fs.readdirSync(inbox).find((name) => name.endsWith(".json"));
+				return entry ? JSON.parse(fs.readFileSync(path.join(inbox, entry), "utf-8")) as { id: string } : undefined;
+			});
+			writeSteerAck(routeDir, { requestId: request.id, index: 0, ts: Date.now(), state: "delivered", message: "accepted" });
+			assert.equal((await action).state, "delivered");
+		} finally {
+			cleanup(workflowRunId, asyncDir);
+		}
+	});
+
+	it("routes a stable key to async steering without recovery", async () => {
+		const state = createState();
+		const workflowRunId = `workflow-key-async-${Date.now().toString(36)}`;
+		const childRunId = `${workflowRunId}-child`;
+		const workflowDir = createRunningAsync(state, workflowRunId, { track: false, mode: "workflow" });
+		const childDir = createRunningAsync(state, childRunId, { track: false });
+		const childStatus = JSON.parse(fs.readFileSync(path.join(childDir, "status.json"), "utf-8"));
+		childStatus.pid = process.pid;
+		writeJson(path.join(childDir, "status.json"), childStatus);
+		const workflowStatus = JSON.parse(fs.readFileSync(path.join(workflowDir, "status.json"), "utf-8"));
+		workflowStatus.steps = [];
+		writeJson(path.join(workflowDir, "status.json"), workflowStatus);
+		const controller = new AbortController();
+		try {
+			const action = steerWorkflowChildByKey({ state, workflowRunId, key: "writer", message: "Use the new API.", options: { ackTimeoutMs: 500 }, signal: controller.signal, resolveRunId: () => childRunId });
+			await waitUntil(() => consumeSteerRequests(childDir)[0] ? true : undefined);
+			controller.abort();
+			assert.equal((await action).state, "queued");
+			assert.equal(fs.existsSync(path.join(childDir, "control", "steer-recovery")), false);
+		} finally {
+			cleanup(workflowRunId, workflowDir);
+			cleanup(childRunId, childDir);
+		}
+	});
+
+	it("returns missed when a terminal keyed child cannot accept a retained follow-up", async () => {
+		const state = createState();
+		const workflowRunId = `workflow-key-terminal-${Date.now().toString(36)}`;
+		const childRunId = `${workflowRunId}-child`;
+		const workflowDir = createRunningAsync(state, workflowRunId, { track: false, mode: "workflow" });
+		const childDir = createRunningAsync(state, childRunId, { track: false });
+		const workflowStatus = JSON.parse(fs.readFileSync(path.join(workflowDir, "status.json"), "utf-8"));
+		workflowStatus.steps = [{ agent: "worker", status: "completed", workflowKey: "writer", runId: childRunId, async: true }];
+		writeJson(path.join(workflowDir, "status.json"), workflowStatus);
+		const sessionFile = path.join(childDir, "child.jsonl");
+		fs.writeFileSync(sessionFile, "", "utf-8");
+		const childStatus = JSON.parse(fs.readFileSync(path.join(childDir, "status.json"), "utf-8"));
+		childStatus.state = "complete";
+		childStatus.parentWorkflowRunId = workflowRunId;
+		childStatus.steps = [{ agent: "worker", status: "complete", sessionFile }];
+		writeJson(path.join(childDir, "status.json"), childStatus);
+		try {
+			const result = await steerWorkflowChildByKey({ state, workflowRunId, key: "writer", message: "Too late.", options: { mode: "follow_up", index: 1, ackTimeoutMs: 20 } });
+			assert.equal(result.state, "missed");
+			assert.match(result.error ?? "", /is complete/);
+			assert.doesNotMatch(JSON.stringify(result), new RegExp(childRunId));
+			assert.equal(consumeSteerRequests(childDir).length, 0);
+			assert.equal(fs.existsSync(path.join(childDir, "control", "revival-briefs")), false);
+		} finally {
+			cleanup(workflowRunId, workflowDir);
+			cleanup(childRunId, childDir);
+		}
+	});
+
+	it("returns missed when a keyed child's raw running status reconciles terminal", async () => {
+		const state = createState();
+		const workflowRunId = `workflow-key-reconciled-${Date.now().toString(36)}`;
+		const childRunId = `${workflowRunId}-child`;
+		const workflowDir = createRunningAsync(state, workflowRunId, { track: false, mode: "workflow" });
+		const childDir = createRunningAsync(state, childRunId, { track: false });
+		const workflowStatus = JSON.parse(fs.readFileSync(path.join(workflowDir, "status.json"), "utf-8"));
+		workflowStatus.steps = [{ agent: "worker", status: "completed", workflowKey: "writer", runId: childRunId, async: true }];
+		writeJson(path.join(workflowDir, "status.json"), workflowStatus);
+		writeJson(path.join(RESULTS_DIR, `${childRunId}.json`), { runId: childRunId, mode: "single", success: false, error: "terminal", results: [] });
+		try {
+			const result = await steerWorkflowChildByKey({ state, workflowRunId, key: "writer", message: "Too late.", options: { ackTimeoutMs: 20 } });
+			assert.equal(result.state, "missed");
+			assert.match(result.error ?? "", /is failed/);
+			assert.doesNotMatch(JSON.stringify(result), new RegExp(childRunId));
+			assert.equal(consumeSteerRequests(childDir).length, 0);
+		} finally {
+			cleanup(workflowRunId, workflowDir);
+			cleanup(childRunId, childDir);
+		}
+	});
+
 	it("rejects a steer request when its workflow foreground route is already removed", async () => {
 		const state = createState();
 		const workflowRunId = `workflow-missing-route-${Date.now().toString(36)}`;
@@ -489,25 +586,27 @@ describe("async interrupt action", () => {
 		}
 	});
 
-	it("rejects interrupt for a running external CLI run without writing a pause request", async () => {
-		const state = createState();
-		const runId = `interrupt-external-${Date.now().toString(36)}`;
-		const asyncDir = createRunningAsync(state, runId, { track: false });
-		const statusPath = path.join(asyncDir, "status.json");
-		const status = JSON.parse(fs.readFileSync(statusPath, "utf-8"));
-		status.steps[0].runner = { type: "external-cli" };
-		fs.writeFileSync(statusPath, JSON.stringify(status), "utf-8");
-		try {
-			const result = await executorWithKill(state, () => {
-				throw new Error("external interrupt should not signal the runner");
-			}).execute("interrupt", { action: "interrupt", id: runId }, new AbortController().signal, undefined, ctx());
+	it("rejects interrupt for a running external runner without writing a pause request", async () => {
+		for (const runner of [{ type: "external-cli" }, { type: "external-job", provider: "surf-oracle", options: {} }]) {
+			const state = createState();
+			const runId = `interrupt-external-${runner.type}-${Date.now().toString(36)}`;
+			const asyncDir = createRunningAsync(state, runId, { track: false });
+			const statusPath = path.join(asyncDir, "status.json");
+			const status = JSON.parse(fs.readFileSync(statusPath, "utf-8"));
+			status.steps[0].runner = runner;
+			fs.writeFileSync(statusPath, JSON.stringify(status), "utf-8");
+			try {
+				const result = await executorWithKill(state, () => {
+					throw new Error("external interrupt should not signal the runner");
+				}).execute("interrupt", { action: "interrupt", id: runId }, new AbortController().signal, undefined, ctx());
 
-			assert.equal(result.isError, true);
-			assert.match(text(result), /Interrupt is unsupported for one-shot external CLI async run/);
-			assert.equal(fs.existsSync(path.join(asyncDir, "control", "interrupt.json")), false);
-			assert.equal(JSON.parse(fs.readFileSync(statusPath, "utf-8")).state, "running");
-		} finally {
-			cleanup(runId, asyncDir);
+				assert.equal(result.isError, true);
+				assert.match(text(result), new RegExp(`Interrupt is unsupported for external async run ${runId}; use stop instead\\.`));
+				assert.equal(fs.existsSync(path.join(asyncDir, "control", "interrupt.json")), false);
+				assert.equal(JSON.parse(fs.readFileSync(statusPath, "utf-8")).state, "running");
+			} finally {
+				cleanup(runId, asyncDir);
+			}
 		}
 	});
 
@@ -525,13 +624,44 @@ describe("async interrupt action", () => {
 
 			assert.equal(result.isError, undefined);
 			assert.match(text(result), new RegExp(`Stop requested for async run ${runId}`));
-			assert.equal(fs.existsSync(path.join(asyncDir, "control", "stop.json")), true);
+			assert.equal(consumeStopRequestPayload(asyncDir)?.type, "stop");
 			assert.deepEqual(kills, [{ pid: 12345, signal: 0 }]);
 		} finally {
 			cleanup(runId, asyncDir);
 		}
 	});
 
+	it("writes child-scoped stop requests for a running async run", async () => {
+		const state = createState();
+		state.currentSessionId = "session";
+		const runId = `stop-child-${Date.now().toString(36)}`;
+		const asyncDir = createRunningAsync(state, runId, { track: false, sessionId: "session" });
+		try {
+			const statusPath = path.join(asyncDir, "status.json");
+			writeJson(statusPath, {
+				...JSON.parse(fs.readFileSync(statusPath, "utf-8")),
+				steps: [
+					{ agent: "first", status: "running", runId: "child-a", startedAt: 100 },
+					{ agent: "second", status: "running", workflowKey: "review", startedAt: 100 },
+				],
+			});
+
+			const result = await executorWithKill(state, () => true)
+				.execute("stop-child", { action: "stop", id: runId, childId: "review" }, new AbortController().signal, undefined, ctx());
+
+			assert.equal(result.isError, undefined);
+			assert.match(text(result), /Stop requested for child review/);
+			const request = consumeStopRequestPayload(asyncDir);
+			assert.equal(request?.type, "stop");
+			assert.equal(request?.source, "stop-action");
+			assert.equal(request?.targetIndex, 1);
+			assert.equal(request?.childId, "review");
+			assert.equal(typeof request?.ts, "number");
+		} finally {
+			cleanup(runId, asyncDir);
+		}
+	});
+
 	it("dismisses only a reload-recovered running workflow without terminating work", async () => {
 		const state = createState();
 		state.currentSessionId = "session";
@@ -725,7 +855,7 @@ describe("async interrupt action", () => {
 
 			assert.equal(result.isError, undefined);
 			assert.match(text(result), new RegExp(`Stop requested for async run ${runId}`));
-			assert.equal(fs.existsSync(path.join(asyncDir, "control", "stop.json")), true);
+			assert.equal(consumeStopRequestPayload(asyncDir)?.type, "stop");
 		} finally {
 			cleanup(runId, asyncDir);
 		}