@selesai/code 0.8.3 → 0.8.5

package/dist/extensions/pi-subagents/test/unit/scheduled-runs.test.ts

@@ -130,7 +130,7 @@ describe("schedule helpers", () => {
 describe("project schedule management", () => {
 	it("creates a project one-shot schedule and restores it in another session", async () => {
 		const first = harness();
-		const result = await first.manager.handleToolCall({ action: "schedule.create", id: "night-review", name: "Night review", at: "+10m", agent: "commentator", task: "Review the diff" }, first.ctx);
+		const result = await first.manager.handleToolCall({ action: "schedule.create", id: "night-review", name: "Night review", at: "+10m", workflowScript: "return runs.run('main', { agent: 'reviewer', task: 'Review the diff' })" }, first.ctx);
 		assert.equal(result.isError, undefined);
 		assert.match(text(result), /Created schedule night-review/);
 		assert.equal(first.timers.values.size, 1);
@@ -159,26 +159,66 @@ describe("project schedule management", () => {
 		fs.mkdirSync(target);
 		h.manager.bindSession(context(target, "target-session"));
 		h.manager.bindSession(h.ctx);
-		await h.manager.handleToolCall({ action: "schedule.create", id: "other", cwd: target, every: "1h", agent: "builder" }, h.ctx);
+		await h.manager.handleToolCall({ action: "schedule.create", id: "other", cwd: target, every: "1h", workflowScript: "return runs.run('main', { agent: 'worker' })" }, h.ctx);
 		assert.equal(listScheduledRunSummaries(h.ctx.cwd, path.join(h.root, "stores")).length, 0);
 		assert.equal(listScheduledRunSummaries(target, path.join(h.root, "stores"))[0]?.cwd, target);
 		const listed = await h.manager.handleToolCall({ action: "schedule.list", cwd: target }, h.ctx);
 		assert.match(text(listed), /other/);
 	});
 
+	it("rejects direct schedule targets and requires workflowScript", async () => {
+		const h = harness();
+		const result = await h.manager.handleToolCall({ action: "schedule.create", id: "direct", every: "1h", agent: "worker", task: "Review" }, h.ctx);
+		assert.equal(result.isError, true);
+		assert.match(text(result), /requires workflowScript/);
+	});
+
+	it("fails closed on persisted legacy agent targets", () => {
+		const h = harness();
+		h.manager.stop();
+		const root = scheduledRunStorePath(h.ctx.cwd, undefined, path.join(h.root, "stores"));
+		const dir = path.join(root, "legacy");
+		fs.mkdirSync(dir, { recursive: true });
+		fs.writeFileSync(path.join(dir, "schedule.json"), JSON.stringify({
+			schemaVersion: 1,
+			id: "legacy",
+			name: "Legacy direct target",
+			cwd: h.ctx.cwd,
+			trigger: { kind: "interval", every: "1h", everyMs: 3_600_000, anchorAt: new Date(h.clock.now).toISOString(), nextRunAt: new Date(h.clock.now + 3_600_000).toISOString() },
+			target: { agent: "worker", task: "Review backlog" },
+			overlap: "skip",
+			catchUp: "latest",
+			paused: false,
+			createdAt: new Date(h.clock.now).toISOString(),
+			updatedAt: new Date(h.clock.now).toISOString(),
+		}), "utf-8");
+		const manager = createScheduledRunManager({
+			config: { scheduledRuns: { enabled: true } },
+			storeRoot: path.join(h.root, "stores"),
+			now: () => h.clock.now,
+			timers: h.timers,
+			launch: async () => ({ content: [{ type: "text", text: "unused" }], details: { mode: "management", results: [] } }),
+		});
+
+		assert.throws(() => manager.bindSession(context(h.ctx.cwd, "session-b")), /removed legacy agent target.*target\.workflowScript/i);
+	});
+
 	it("supports workflowScript targets and rejects unsafe or deferred shapes", async () => {
 		const h = harness();
-		const workflow = await h.manager.handleToolCall({ action: "schedule.create", id: "workflow", every: "6h", workflowScript: "return await runs.run('review', {agent:'commentator'})" }, h.ctx);
+		const workflow = await h.manager.handleToolCall({ action: "schedule.create", id: "workflow", every: "6h", workflowScript: "return await runs.run('review', {agent:'reviewer'})" }, h.ctx);
 		assert.equal(workflow.isError, undefined);
-		assert.match(text(workflow), /workflowScript/);
+		assert.match(text(workflow), /workflowScript -> agent reviewer/);
+		const dynamic = await h.manager.handleToolCall({ action: "schedule.create", id: "dynamic", every: "6h", workflowScript: "const agent = 'worker'; return runs.run('main', { agent })" }, h.ctx);
+		assert.equal(dynamic.isError, undefined);
+		assert.match(text(dynamic), /workflowScript \(dynamic\)/);
 		for (const params of [
-			{ action: "schedule.create", id: "../escape", every: "1h", agent: "builder" },
-			{ action: "schedule.create", id: "both", at: "+1h", every: "1h", agent: "builder" },
-			{ action: "schedule.create", id: "calendar", every: "day", at: "09:00", timezone: "UTC", agent: "builder" },
-			{ action: "schedule.create", id: "two-targets", every: "1h", agent: "builder", workflowScript: "return 1" },
-			{ action: "schedule.create", id: "fork", every: "1h", agent: "builder", context: "fork" },
-			{ action: "schedule.create", id: "mission-id", every: "1h", agent: "builder", missionId: "mission-1" },
-			{ action: "schedule.create", id: "mission-off", every: "1h", agent: "builder", mission: false },
+			{ action: "schedule.create", id: "../escape", every: "1h", workflowScript: "return runs.run('main', { agent: 'worker' })" },
+			{ action: "schedule.create", id: "both", at: "+1h", every: "1h", workflowScript: "return runs.run('main', { agent: 'worker' })" },
+			{ action: "schedule.create", id: "calendar", every: "day", at: "09:00", timezone: "UTC", workflowScript: "return runs.run('main', { agent: 'worker' })" },
+			{ action: "schedule.create", id: "two-targets", every: "1h", agent: "worker", workflowScript: "return 1" },
+			{ action: "schedule.create", id: "fork", every: "1h", workflowScript: "return runs.run('main', { agent: 'worker' })", context: "fork" },
+			{ action: "schedule.create", id: "mission-id", every: "1h", workflowScript: "return runs.run('main', { agent: 'worker' })", missionId: "mission-1" },
+			{ action: "schedule.create", id: "mission-off", every: "1h", workflowScript: "return runs.run('main', { agent: 'worker' })", mission: false },
 		] as const) {
 			const result = await h.manager.handleToolCall(params, h.ctx);
 			assert.equal(result.isError, true, JSON.stringify(params));
@@ -187,7 +227,7 @@ describe("project schedule management", () => {
 
 	it("pauses, resumes, lists, and deletes an inactive schedule", async () => {
 		const h = harness();
-		await h.manager.handleToolCall({ action: "schedule.create", id: "maintenance", every: "1h", agent: "builder" }, h.ctx);
+		await h.manager.handleToolCall({ action: "schedule.create", id: "maintenance", every: "1h", workflowScript: "return runs.run('main', { agent: 'worker' })" }, h.ctx);
 		assert.match(text(await h.manager.handleToolCall({ action: "schedule.list" }, h.ctx)), /maintenance/);
 		assert.match(text(await h.manager.handleToolCall({ action: "schedule.pause", id: "maintenance" }, h.ctx)), /Paused/);
 		assert.equal(h.timers.values.size, 0);
@@ -215,7 +255,7 @@ describe("project schedule management", () => {
 		fs.mkdirSync(root, { recursive: true });
 		fs.mkdirSync(outside);
 		fs.symlinkSync(outside, path.join(root, "escaped"), process.platform === "win32" ? "junction" : "dir");
-		const result = await h.manager.handleToolCall({ action: "schedule.create", id: "escaped", every: "1h", agent: "builder" }, h.ctx);
+		const result = await h.manager.handleToolCall({ action: "schedule.create", id: "escaped", every: "1h", workflowScript: "return runs.run('main', { agent: 'worker' })" }, h.ctx);
 		assert.equal(result.isError, true);
 		assert.match(text(result), /must be a real directory/);
 		assert.equal(fs.existsSync(path.join(outside, "schedule.json")), false);
@@ -234,9 +274,10 @@ describe("project schedule management", () => {
 			launch: async () => ({ content: [{ type: "text", text: "unused" }], details: { mode: "management", results: [] } }),
 		});
 		manager.bindSession(ctx);
+		fs.mkdirSync(path.join(project, ".selesai"));
 		fs.symlinkSync(outside, path.join(project, ".pi-subagents"), process.platform === "win32" ? "junction" : "dir");
 
-		const result = await manager.handleToolCall({ action: "schedule.create", id: "escaped-root", every: "1h", agent: "builder" }, ctx);
+		const result = await manager.handleToolCall({ action: "schedule.create", id: "escaped-root", every: "1h", workflowScript: "return runs.run('main', { agent: 'worker' })" }, ctx);
 		assert.equal(result.isError, true);
 		assert.match(text(result), /resolves outside the real project/);
 		assert.equal(fs.existsSync(path.join(outside, "schedules")), false);
@@ -246,12 +287,12 @@ describe("project schedule management", () => {
 describe("recurring schedule execution", () => {
 	it("launches a fixed interval from its planned time and records durable history/events", async () => {
 		const h = harness();
-		await h.manager.handleToolCall({ action: "schedule.create", id: "hourly", every: "1h", agent: "builder", task: "Maintain backlog" }, h.ctx);
+		await h.manager.handleToolCall({ action: "schedule.create", id: "hourly", every: "1h", workflowScript: "return runs.run('main', { agent: 'worker', task: 'Maintain backlog' })" }, h.ctx);
 		h.clock.now += 3_600_000;
 		h.timers.fireAll();
 		assert.equal(h.launches.length, 1);
-		assert.deepEqual(h.launches[0]?.params, { agent: "builder", task: "Maintain backlog", async: true, clarify: false, context: "fresh", cwd: h.ctx.cwd, mission: false });
-		h.launches[0]!.resolve({ content: [{ type: "text", text: "Async builder" }], details: { mode: "single", results: [], asyncId: "async-1", asyncDir: "/tmp/async-1" } });
+		assert.deepEqual(h.launches[0]?.params, { workflowScript: "return runs.run('main', { agent: 'worker', task: 'Maintain backlog' })", async: true, context: "fresh", cwd: h.ctx.cwd, mission: false });
+		h.launches[0]!.resolve({ content: [{ type: "text", text: "Async worker" }], details: { mode: "single", results: [], asyncId: "async-1", asyncDir: "/tmp/async-1" } });
 		await flush();
 
 		let history = await h.manager.handleToolCall({ action: "schedule.history", id: "hourly" }, h.ctx);
@@ -272,7 +313,7 @@ describe("recurring schedule execution", () => {
 
 	it("run-due launches the latest missed occurrence while catchUp none records a miss", async () => {
 		const latest = harness();
-		await latest.manager.handleToolCall({ action: "schedule.create", id: "latest", every: "1h", catchUp: "latest", agent: "builder" }, latest.ctx);
+		await latest.manager.handleToolCall({ action: "schedule.create", id: "latest", every: "1h", catchUp: "latest", workflowScript: "return runs.run('main', { agent: 'worker' })" }, latest.ctx);
 		latest.manager.stop();
 		latest.clock.now += 3 * 3_600_000;
 		latest.manager.bindSession(latest.ctx);
@@ -284,7 +325,7 @@ describe("recurring schedule execution", () => {
 		assert.match(text(await latest.manager.handleToolCall({ action: "schedule.history", id: "latest" }, latest.ctx)), /2030-01-01T03:00:00.000Z/, "latest catch-up selects the latest missed slot");
 
 		const none = harness();
-		await none.manager.handleToolCall({ action: "schedule.create", id: "none", every: "1h", catchUp: "none", agent: "builder" }, none.ctx);
+		await none.manager.handleToolCall({ action: "schedule.create", id: "none", every: "1h", catchUp: "none", workflowScript: "return runs.run('main', { agent: 'worker' })" }, none.ctx);
 		none.manager.stop();
 		none.clock.now += 3 * 3_600_000;
 		none.manager.bindSession(none.ctx);
@@ -294,7 +335,7 @@ describe("recurring schedule execution", () => {
 
 	it("keeps project timers, contexts, and completion ownership across session_start bindings", async () => {
 		const h = harness();
-		await h.manager.handleToolCall({ action: "schedule.create", id: "project-a", every: "1h", agent: "builder" }, h.ctx);
+		await h.manager.handleToolCall({ action: "schedule.create", id: "project-a", every: "1h", workflowScript: "return runs.run('main', { agent: 'worker' })" }, h.ctx);
 
 		const projectB = path.join(h.root, "project-b");
 		fs.mkdirSync(projectB);
@@ -305,7 +346,7 @@ describe("recurring schedule execution", () => {
 		sourceSessionManager.getSessionId = () => "session-b";
 		sourceSessionManager.getSessionFile = () => path.join(projectB, "session-b.jsonl");
 		h.manager.bindSession(projectBCtx);
-		await h.manager.handleToolCall({ action: "schedule.create", id: "project-b", every: "1h", agent: "builder" }, projectBCtx);
+		await h.manager.handleToolCall({ action: "schedule.create", id: "project-b", every: "1h", workflowScript: "return runs.run('main', { agent: 'worker' })" }, projectBCtx);
 		assert.equal(h.timers.values.size, 2, "both project timers remain armed after session_start binds project B");
 
 		h.clock.now += 3_600_000;
@@ -335,14 +376,14 @@ describe("recurring schedule execution", () => {
 		const h = harness();
 		const target = path.join(h.root, "explicit-target");
 		fs.mkdirSync(target);
-		const unbound = await h.manager.handleToolCall({ action: "schedule.create", id: "targeted", cwd: target, every: "1h", agent: "builder" }, h.ctx);
+		const unbound = await h.manager.handleToolCall({ action: "schedule.create", id: "targeted", cwd: target, every: "1h", workflowScript: "return runs.run('main', { agent: 'worker' })" }, h.ctx);
 		assert.equal(unbound.isError, true);
 		assert.match(text(unbound), /until that project has been opened/);
 
 		const targetCtx = context(target, "target-session");
 		h.manager.bindSession(targetCtx);
 		h.manager.bindSession(h.ctx);
-		await h.manager.handleToolCall({ action: "schedule.create", id: "targeted", cwd: target, every: "1h", agent: "builder" }, h.ctx);
+		await h.manager.handleToolCall({ action: "schedule.create", id: "targeted", cwd: target, every: "1h", workflowScript: "return runs.run('main', { agent: 'worker' })" }, h.ctx);
 		h.clock.now += 3_600_000;
 		h.timers.fireAll();
 		await flush();
@@ -374,7 +415,7 @@ describe("recurring schedule execution", () => {
 		});
 		manager.bindSession(badCtx);
 		manager.bindSession(ownerCtx);
-		await manager.handleToolCall({ action: "schedule.create", id: "owner", every: "1h", agent: "builder" }, ownerCtx);
+		await manager.handleToolCall({ action: "schedule.create", id: "owner", every: "1h", workflowScript: "return runs.run('main', { agent: 'worker' })" }, ownerCtx);
 		const manual = manager.handleToolCall({ action: "schedule.run", id: "owner" }, ownerCtx);
 		await flush();
 		launches[0]!.resolve({ content: [{ type: "text", text: "Async" }], details: { mode: "single", results: [], asyncId: "owner-async" } });
@@ -401,7 +442,7 @@ describe("recurring schedule execution", () => {
 
 	it("reconciles a terminal async status after a new session binds", async () => {
 		const h = harness();
-		await h.manager.handleToolCall({ action: "schedule.create", id: "restart", every: "1h", agent: "builder" }, h.ctx);
+		await h.manager.handleToolCall({ action: "schedule.create", id: "restart", every: "1h", workflowScript: "return runs.run('main', { agent: 'worker' })" }, h.ctx);
 		h.clock.now += 3_600_000;
 		h.timers.fireAll();
 		const asyncDir = path.join(h.root, "async-restart");
@@ -427,7 +468,7 @@ describe("recurring schedule execution", () => {
 
 	it("records elapsed overlap and catch-up-none slots without an immediate rerun", async () => {
 		const latest = harness();
-		await latest.manager.handleToolCall({ action: "schedule.create", id: "overlap", every: "1h", catchUp: "latest", agent: "builder" }, latest.ctx);
+		await latest.manager.handleToolCall({ action: "schedule.create", id: "overlap", every: "1h", catchUp: "latest", workflowScript: "return runs.run('main', { agent: 'worker' })" }, latest.ctx);
 		latest.clock.now += 3_600_000;
 		latest.timers.fireAll();
 		latest.launches[0]!.resolve({ content: [{ type: "text", text: "Async" }], details: { mode: "single", results: [], asyncId: "long-run" } });
@@ -442,7 +483,7 @@ describe("recurring schedule execution", () => {
 		assert.match(text(await latest.manager.handleToolCall({ action: "schedule.show", id: "overlap" }, latest.ctx)), /2030-01-01T05:00:00.000Z/);
 
 		const none = harness();
-		await none.manager.handleToolCall({ action: "schedule.create", id: "none-overlap", every: "1h", catchUp: "none", agent: "builder" }, none.ctx);
+		await none.manager.handleToolCall({ action: "schedule.create", id: "none-overlap", every: "1h", catchUp: "none", workflowScript: "return runs.run('main', { agent: 'worker' })" }, none.ctx);
 		none.clock.now += 3_600_000;
 		none.timers.fireAll();
 		none.launches[0]!.resolve({ content: [{ type: "text", text: "Async" }], details: { mode: "single", results: [], asyncId: "none-long-run" } });
@@ -470,7 +511,7 @@ describe("recurring schedule execution", () => {
 
 	it("distinguishes failed launch from failed async completion", async () => {
 		const h = harness();
-		await h.manager.handleToolCall({ action: "schedule.create", id: "failures", every: "1h", agent: "builder" }, h.ctx);
+		await h.manager.handleToolCall({ action: "schedule.create", id: "failures", every: "1h", workflowScript: "return runs.run('main', { agent: 'worker' })" }, h.ctx);
 		const first = h.manager.handleToolCall({ action: "schedule.run", id: "failures" }, h.ctx);
 		await flush();
 		h.launches[0]!.resolve({ content: [{ type: "text", text: "spawn failed" }], details: { mode: "management", results: [] }, isError: true });

package/dist/extensions/pi-subagents/test/unit/scheduled-store-root.test.ts

@@ -0,0 +1,67 @@
+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 { afterEach, beforeEach, describe, it } from "node:test";
+import { getConfigPath, loadConfig, resolveScheduledStoreRoot, saveConfig, updateConfig } from "../../src/extension/config.ts";
+
+const AGENT_DIR_ENV = "SELESAI_CODING_AGENT_DIR";
+const HOME_ENV = "HOME";
+const USERPROFILE_ENV = "USERPROFILE";
+let agentDir: string;
+let homeDir: string;
+let previousAgentDir: string | undefined;
+let previousHome: string | undefined;
+let previousUserProfile: string | undefined;
+
+beforeEach(() => {
+	previousAgentDir = process.env[AGENT_DIR_ENV];
+	previousHome = process.env[HOME_ENV];
+	previousUserProfile = process.env[USERPROFILE_ENV];
+	agentDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-schedule-store-root-"));
+	homeDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-schedule-home-"));
+	process.env[AGENT_DIR_ENV] = agentDir;
+	process.env[HOME_ENV] = homeDir;
+	process.env[USERPROFILE_ENV] = homeDir;
+});
+
+afterEach(() => {
+	if (previousAgentDir === undefined) delete process.env[AGENT_DIR_ENV];
+	else process.env[AGENT_DIR_ENV] = previousAgentDir;
+	if (previousHome === undefined) delete process.env[HOME_ENV];
+	else process.env[HOME_ENV] = previousHome;
+	if (previousUserProfile === undefined) delete process.env[USERPROFILE_ENV];
+	else process.env[USERPROFILE_ENV] = previousUserProfile;
+	fs.rmSync(agentDir, { recursive: true, force: true });
+	fs.rmSync(homeDir, { recursive: true, force: true });
+});
+
+describe("config.scheduledRuns.storeRoot", () => {
+	it("accepts an absolute path and expands a ~/ path", () => {
+		const absolute = path.join(os.tmpdir(), "pi-subagents-schedules");
+		assert.equal(resolveScheduledStoreRoot(absolute), path.normalize(absolute));
+		assert.equal(resolveScheduledStoreRoot("~/pi-subagents/schedules"), path.join(homeDir, "pi-subagents", "schedules"));
+	});
+
+	it("rejects project-relative paths during config load", () => {
+		saveConfig({ scheduledRuns: { storeRoot: "schedules" } });
+		const originalError = console.error;
+		console.error = () => {};
+		try {
+			assert.deepEqual(loadConfig(), {});
+		} finally {
+			console.error = originalError;
+		}
+	});
+
+	it("rejects project-relative paths during config update", () => {
+		assert.throws(() => updateConfig(() => ({ scheduledRuns: { storeRoot: "./schedules" } })), /absolute path/);
+		assert.equal(fs.existsSync(getConfigPath()), false);
+	});
+
+	it("preserves a configured store root", () => {
+		const storeRoot = path.join(os.tmpdir(), "pi-subagents-schedules");
+		saveConfig({ scheduledRuns: { storeRoot } });
+		assert.equal(loadConfig().scheduledRuns?.storeRoot, storeRoot);
+	});
+});

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

@@ -175,6 +175,7 @@ describe("SubagentParams schema", { skip: !schemasAvailable ? "typebox not avail
 		assert.equal(workflowScript?.type, "string");
 		assert.equal(workflowScript?.minLength, 1);
 		assert.match(String(workflowScript?.description ?? ""), /runs\.run/);
+		assert.match(String(workflowScript?.description ?? ""), /sequential and parallel phases dynamically/i);
 		assert.match(String(workflowScript?.description ?? ""), /worktree:true/i);
 		assert.match(String(workflowScript?.description ?? ""), /no filesystem, shell, Pi tools, or host globals/i);
 		const chatProgress = SubagentParams?.properties?.chatProgress;
@@ -183,14 +184,31 @@ describe("SubagentParams schema", { skip: !schemasAvailable ? "typebox not avail
 		assert.match(String(chatProgress?.description ?? ""), /same Git repository/i);
 		const worktree = SubagentParams?.properties?.worktree;
 		assert.equal(worktree?.type, "boolean");
-		assert.match(String(worktree?.description ?? ""), /direct single child/i);
+		assert.match(String(worktree?.description ?? ""), /each workflow child/i);
+		const gate = SubagentParams?.properties?.gate;
+		assert.equal(gate?.type, "string");
+		assert.equal(gate?.minLength, 1);
+		assert.match(String(gate?.description ?? ""), /cannot be combined with acceptance/i);
+		const properties = SubagentParams?.properties as Record<string, unknown> | undefined;
+		assert.ok(properties?.task, "task should be model-facing for SINGLE mode");
+		assert.ok(properties?.clarify, "clarify should be model-facing for the clarify TUI");
+		assert.ok(properties?.chain, "chain should be model-facing for CHAIN mode");
+		assert.ok(properties?.tasks, "tasks should be model-facing for PARALLEL mode");
+		assert.ok(properties?.output, "output remains a workflow child default");
 	});
 
-	it("removes legacy top-level orchestration parameters", () => {
-		for (const name of ["tasks", "chain", "concurrency", "chainDir"]) {
-			assert.equal((SubagentParams?.properties as Record<string, unknown> | undefined)?.[name], undefined, `${name} should not be public`);
+	it("includes chain controls by default and trims them when legacyChainControls is false", () => {
+		for (const name of ["tasks", "chain", "task", "clarify"]) {
+			assert.ok((SubagentParams?.properties as Record<string, unknown> | undefined)?.[name], `${name} should be public by default`);
 		}
-		const stepSchema = (SubagentParams?.properties as Record<string, JsonSchemaNode> | undefined)?.step;
+
+		const trimmed = (schemas.createSubagentParamsSchema as (options?: { legacyChainControls?: boolean }) => SubagentParamsSchema)({ legacyChainControls: false });
+		assert.equal(trimmed.properties?.step, undefined);
+		assert.doesNotMatch(JSON.stringify(trimmed), /append-step/);
+		assert.ok(trimmed.properties?.chain, "chain stays model-facing even in the trimmed schema");
+
+		const full = (schemas.createSubagentParamsSchema as (options: { legacyChainControls: boolean }) => SubagentParamsSchema)();
+		const stepSchema = (full.properties as Record<string, JsonSchemaNode> | undefined)?.step;
 		assert.equal(stepSchema?.type, "object");
 		assert.match(String(stepSchema?.description ?? ""), /append-step.*only/i);
 	});
@@ -199,16 +217,17 @@ describe("SubagentParams schema", { skip: !schemasAvailable ? "typebox not avail
 		const actionSchema = SubagentParams?.properties?.action;
 		assert.ok(actionSchema, "action schema should exist");
 		assert.equal(actionSchema.type, "string");
+		assert.equal(actionSchema.minLength, 1);
 		assert.equal(actionSchema.enum, undefined);
 		const description = String(actionSchema.description ?? "");
 		assert.match(description, /Optional management\/control action/);
-		assert.match(description, /Omit this field entirely for execution\/delegation/);
-		assert.match(description, /\{agent, task\} or \{workflowScript\}/);
+		assert.match(description, /Omit this field for workflowScript execution/);
+		assert.doesNotMatch(description, /\{agent, task\}/);
 		assert.match(description, /use it only for management\/control actions/);
 		assert.doesNotMatch(description, /orchestration\./);
 	});
 
-	it("includes foreground timeout aliases and turn budget", () => {
+	it("documents workflow timeout aliases and turn budget", () => {
 		const timeoutSchema = SubagentParams?.properties?.timeoutMs;
 		const maxRuntimeSchema = SubagentParams?.properties?.maxRuntimeMs;
 		const turnBudgetSchema = SubagentParams?.properties?.turnBudget;
@@ -217,10 +236,14 @@ describe("SubagentParams schema", { skip: !schemasAvailable ? "typebox not avail
 		assert.ok(maxRuntimeSchema, "maxRuntimeMs schema should exist");
 		assert.equal(timeoutSchema.minimum, 1);
 		assert.equal(maxRuntimeSchema.minimum, 1);
-		assert.match(String(timeoutSchema.description ?? ""), /foreground and async\/background/i);
+		assert.match(String(timeoutSchema.description ?? ""), /foreground and single async runs/i);
+		assert.match(String(timeoutSchema.description ?? ""), /use config timeoutMs, else 30m/i);
+		assert.match(String(timeoutSchema.description ?? ""), /async composites have no default parent deadline/i);
 		assert.doesNotMatch(String(timeoutSchema.description ?? ""), /foreground-only/i);
 		assert.match(String(maxRuntimeSchema.description ?? ""), /timeoutMs/i);
-		assert.match(String(maxRuntimeSchema.description ?? ""), /foreground and async\/background/i);
+		assert.match(String(maxRuntimeSchema.description ?? ""), /foreground and single async runs/i);
+		assert.match(String(maxRuntimeSchema.description ?? ""), /use config timeoutMs, else 30m/i);
+		assert.match(String(maxRuntimeSchema.description ?? ""), /async composites have no default parent deadline/i);
 		assert.equal(turnBudgetSchema?.properties?.maxTurns?.minimum, 1);
 		assert.equal(turnBudgetSchema?.properties?.graceTurns?.minimum, 0);
 		assert.equal(toolBudgetSchema?.properties?.soft?.minimum, 1);
@@ -356,12 +379,12 @@ describe("SubagentParams schema", { skip: !schemasAvailable ? "typebox not avail
 		assert.ok(SubagentParams, "SubagentParams schema should exist");
 		const schema = SubagentParams as unknown as JsonSchemaNode;
 		const serialized = JSON.stringify(schema);
-		// Mission, inspector, and inline workflow fields intentionally expanded the public tool surface.
-		assert.ok(serialized.length < 17_000, `expected compact schema under 17k chars, got ${serialized.length}`);
+		// Mission, inspector, inline workflow, and guide fields intentionally expanded the public tool surface.
+		assert.ok(serialized.length < 27_000, `expected compact schema under 27k chars, got `);
 		assert.equal(serialized.includes('"$ref"'), false);
 		assert.equal(serialized.includes('"$defs"'), false);
 		assert.equal(serialized.split("Optional acceptance policy.").length - 1, 1);
-		assert.match(String((schema.properties as Record<string, JsonSchemaNode> | undefined)?.agent?.description ?? ""), /SINGLE mode/);
+		assert.match(String((schema.properties as Record<string, JsonSchemaNode> | undefined)?.agent?.description ?? ""), /management actions/);
 		const acceptanceDescription = String((schema.properties as Record<string, JsonSchemaNode> | undefined)?.acceptance?.description ?? "");
 		assert.match(acceptanceDescription, /acceptance policy/);
 		assert.match(acceptanceDescription, /Supported evidence kinds:/);
@@ -369,6 +392,10 @@ describe("SubagentParams schema", { skip: !schemasAvailable ? "typebox not avail
 		assert.match(acceptanceDescription, /changed-files/);
 		assert.match(acceptanceDescription, /manual-notes/);
 		assert.match(acceptanceDescription, /\{ level: "checked", evidence: \["commands-run", "changed-files"\] \}/);
+		const missionDescription = String((schema.properties as Record<string, JsonSchemaNode> | undefined)?.mission?.description ?? "");
+		assert.match(missionDescription, /exactly one non-empty title or summary/);
+		assert.match(missionDescription, /goal may only be true/);
+		assert.match(missionDescription, /requires budget\.tokens/);
 
 		const nestedDescriptionPaths: string[] = [];
 		const stack: Array<{ path: string; value: unknown }> = [{ path: "SubagentParams", value: schema }];
@@ -467,7 +494,7 @@ describe("SubagentParams schema", { skip: !schemasAvailable ? "typebox not avail
 		const reviewedRecoveryBranch = acceptanceStringBranches.find((branch) => Array.isArray(branch.enum) && branch.enum.includes("reviewed"));
 		assert.deepEqual(reviewedRecoveryBranch?.enum, ["reviewed"]);
 		assert.equal(reviewedRecoveryBranch?.deprecated, true);
-		assert.match(String(acceptanceSchema.description ?? ""), /commentator\/read-only calls, omit acceptance/i);
+		assert.match(String(acceptanceSchema.description ?? ""), /reviewer\/read-only calls, omit acceptance/i);
 		assert.match(String(acceptanceSchema.description ?? ""), /acceptance\.review\.required/);
 		const acceptanceObjectBranch = anyOfBranches(acceptanceSchema).find((branch) => branch.type === "object");
 		assert.ok(acceptanceObjectBranch, "acceptance should support object config");
@@ -487,49 +514,38 @@ describe("SubagentParams schema", { skip: !schemasAvailable ? "typebox not avail
 		const validator = CompileSchema(SubagentParams);
 		const validValues = [
 			{ skill: "review" },
-			{ workflowScript: "return await runs.run(\"one\", {agent: \"commentator\", task: \"check\"})" },
-			{ action: "append-step", id: "run-1", step: { agent: "commentator", task: "Continue" } },
+			{ workflowScript: "return await runs.run(\"one\", {agent: \"reviewer\", task: \"check\"})" },
+			{ action: "append-step", id: "run-1", step: { agent: "reviewer", task: "Continue" } },
 			{ skill: false },
-			{ agent: "builder", task: "Fix", acceptance: false },
-			{ agent: "builder", task: "Fix", timeoutMs: 1000 },
+			{ action: "get", agent: "worker" },
+			{ workflowScript: "return runs.run('main', { agent: 'worker', task: 'Fix', acceptance: false })", timeoutMs: 1000 },
 			{ action: "steer", id: "run-1", message: "focus on tests" },
 			{ action: "steer", id: "run-1", index: 0, message: "focus on tests" },
-			{ action: "single", agent: "builder", task: "Fix" },
 			{ action: "not-a-real-action" },
-			{ agent: "builder", task: "Fix", acceptance: "checked" },
-			{ agent: "builder", task: "Fix", acceptance: "reviewed" },
-			{ agent: "builder", task: "Fix", acceptance: { level: "verified", verify: [{ id: "tests", command: "npm test" }] } },
-			{ agent: "builder", task: "Fix", acceptance: { level: "none", reason: "parent will verify manually" } },
-			{ agent: "builder", task: "Fix", acceptance: { level: "checked", review: false } },
-			{ config: { name: "commentator", description: "Review things" } },
-			{ config: JSON.stringify({ name: "commentator", description: "Review things" }) },
-			{ agent: "builder", task: "Fix", turnBudget: { maxTurns: 5, graceTurns: 1 } },
-			{ agent: "builder", task: "Fix", turnBudget: { maxTurns: 1 } },
-			{ agent: "builder", task: "Fix", turnBudget: { maxTurns: 3, graceTurns: 0 } },
-			{ agent: "builder", task: "Fix", toolBudget: { soft: 5, hard: 8, block: ["read", "grep"] } },
-			{ agent: "builder", task: "Fix", toolBudget: { hard: 8, block: "*" } },
+			{ config: { name: "reviewer", description: "Review things" } },
+			{ config: JSON.stringify({ name: "reviewer", description: "Review things" }) },
 		];
 		const invalidValues = [
 			{ skill: 123 },
-			{ agent: "builder", task: "Fix", acceptance: "none" },
-			{ agent: "builder", task: "Fix", acceptance: "verified" },
+			{ agent: "worker", task: "Fix", acceptance: "none" },
+			{ agent: "worker", task: "Fix", acceptance: "verified" },
 			{ skill: [123] },
 			{ output: 123 },
 			{ timeoutMs: 0 },
 			{ maxRuntimeMs: -1 },
-			{ agent: "builder", task: "Fix", acceptance: true },
+			{ agent: "worker", task: "Fix", acceptance: true },
 			{ config: [] },
 			{ config: null },
-			{ agent: "builder", task: "Fix", turnBudget: { maxTurns: 0 } },
-			{ agent: "builder", task: "Fix", turnBudget: { maxTurns: 5, graceTurns: -1 } },
-			{ agent: "builder", task: "Fix", turnBudget: { maxTurns: 1.5 } },
-			{ agent: "builder", task: "Fix", turnBudget: { graceTurns: 1 } },
-			{ agent: "builder", task: "Fix", turnBudget: { maxTurns: 5, graceTurns: 1, extra: true } },
-			{ agent: "builder", task: "Fix", toolBudget: { hard: 0 } },
-			{ agent: "builder", task: "Fix", toolBudget: { hard: 3, soft: 0 } },
-			{ agent: "builder", task: "Fix", toolBudget: { hard: 3, block: [123] } },
-			{ agent: "builder", task: "Fix", toolBudget: { hard: 3, block: [] } },
-			{ agent: "builder", task: "Fix", toolBudget: { hard: 3, block: "read" } },
+			{ agent: "worker", task: "Fix", turnBudget: { maxTurns: 0 } },
+			{ agent: "worker", task: "Fix", turnBudget: { maxTurns: 5, graceTurns: -1 } },
+			{ agent: "worker", task: "Fix", turnBudget: { maxTurns: 1.5 } },
+			{ agent: "worker", task: "Fix", turnBudget: { graceTurns: 1 } },
+			{ agent: "worker", task: "Fix", turnBudget: { maxTurns: 5, graceTurns: 1, extra: true } },
+			{ agent: "worker", task: "Fix", toolBudget: { hard: 0 } },
+			{ agent: "worker", task: "Fix", toolBudget: { hard: 3, soft: 0 } },
+			{ agent: "worker", task: "Fix", toolBudget: { hard: 3, block: [123] } },
+			{ agent: "worker", task: "Fix", toolBudget: { hard: 3, block: [] } },
+			{ agent: "worker", task: "Fix", toolBudget: { hard: 3, block: "read" } },
 		];
 
 		for (const value of validValues) {