@selesai/code 0.8.3 → 0.8.5

package/dist/extensions/pi-subagents/src/extension/index.ts

@@ -1,11 +1,11 @@
 /**
  * Subagent Tool
  *
- * Full-featured subagent with foreground and async modes.
- * - Foreground: Streams output, renders markdown, and waits for the child result
- * - Async (default): Runs in the background and emits events when done
+ * Full-featured subagent with sync and async modes.
+ * - Sync (default): Streams output, renders markdown, tracks usage
+ * - Async: Background execution, emits events when done
  *
- * Public execution modes: single (agent + task) and workflow (workflowScript)
+ * Public execution mode: workflow (workflowScript)
  * Toggle: async parameter (default: true; set asyncByDefault:false in config.json to opt out)
  *
  * Config file: ~/.selesai/agent/extensions/subagent/config.json
@@ -27,9 +27,11 @@ import { cleanupOldChainDirs } from "../shared/settings.ts";
 import { clearLegacyResultAnimationTimer, renderSubagentResult, renderSubagentSummary } from "../tui/render.ts";
 import { openSubagentFleet } from "../tui/fleet.ts";
 import { SubagentFleetStatus, resolveFleetViewPlacement } from "../tui/fleet-status.ts";
-import { SubagentParams } from "./schemas.ts";
+import { createSubagentParamsSchema } from "./schemas.ts";
+import { validateChainInput } from "./chain-validation.ts";
 import { createSubagentExecutor, type SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
 import { createAsyncJobTracker } from "../runs/background/async-job-tracker.ts";
+import { getActiveAsyncCapacitySnapshot, resolveMaxActiveAsyncRunsPerSession } from "../runs/background/active-async-capacity.ts";
 import { createResultWatcher } from "../runs/background/result-watcher.ts";
 import { createScheduledRunManager } from "../runs/background/scheduled-runs.ts";
 import { registerSlashCommands } from "../slash/slash-commands.ts";
@@ -37,13 +39,12 @@ import { registerPromptTemplateDelegationBridge } from "../slash/prompt-template
 import { registerMainWatchdog } from "../watchdog/register-main.ts";
 import { registerSlashSubagentBridge } from "../slash/slash-bridge.ts";
 import { createNativeSupervisorChannel } from "../intercom/native-supervisor-channel.ts";
-import { registerHerdrStatusBridge } from "../integrations/herdr-status.ts";
+import { registerHerdrStatusBridge, type HerdrStatusRun } from "../integrations/herdr-status.ts";
 import { registerSubagentRpcBridge } from "./rpc.ts";
 import { clearSlashSnapshots, getSlashRenderableSnapshot, resolveSlashMessageDetails, restoreSlashFinalSnapshots, type SlashMessageDetails } from "../slash/slash-live-state.ts";
 import { inspectSubagentStatus } from "../runs/background/run-status.ts";
 import { resolveWaitToolConfig } from "../runs/background/subagent-wait.ts";
 import { registerWaitTool } from "../runs/background/wait-tool.ts";
-import { validateChainInput } from "./chain-validation.ts";
 import { createWaitSubscriptionManager } from "../runs/background/wait-subscriptions.ts";
 import { drainOutstandingWork } from "../runs/background/auto-drain.ts";
 import registerSubagentNotify, { parseSubagentNotifyContent, type SubagentNotifyDetails } from "../runs/background/notify.ts";
@@ -51,9 +52,12 @@ import { formatSteeringNotice, handleSubagentSteeringNotice, SUBAGENT_STEERING_M
 import { SUBAGENT_CHILD_ENV, SUBAGENT_PARENT_SESSION_ENV } from "../runs/shared/pi-args.ts";
 import { resolveCurrentSubagentCapabilityCeiling } from "../runs/shared/capability-ceiling.ts";
 import { formatDuration, shortenPath } from "../shared/formatters.ts";
-import { loadConfig, resolveAsyncByDefault } from "./config.ts";
+import { loadConfig, resolveAsyncByDefault, resolveScheduledStoreRoot } from "./config.ts";
 import { buildSubagentToolDescription } from "./tool-description.ts";
-import { syncMissionFromAsyncCompletion } from "../missions/lifecycle.ts";
+import { collectGoalContinuationNotices } from "../missions/goal-driver.ts";
+import { restoreForegroundRunHistory } from "../runs/foreground/foreground-history.ts";
+import { resolveMissionStoreLocation } from "../missions/store.ts";
+import { listRetainedChildren } from "../runs/background/retained-children.ts";
 import {
 	type Details,
 	type SubagentState,
@@ -63,6 +67,7 @@ import {
 	SLASH_TEXT_RESULT_TYPE,
 	SUBAGENT_ASYNC_COMPLETE_EVENT,
 	SUBAGENT_ASYNC_STARTED_EVENT,
+	SUBAGENT_PROCESS_TERMINAL_EVENT,
 	SUBAGENT_CONTROL_EVENT,
 	SUBAGENT_STEERING_NOTICE_EVENT,
 	WIDGET_KEY,
@@ -230,14 +235,18 @@ function expandTilde(p: string): string {
 	return p.startsWith("~/") ? path.join(os.homedir(), p.slice(2)) : p;
 }
 
-function isSlashResultRunning(result: { details?: Details }): boolean {
+function isSlashResultRunning(result: { details?: Details; isError?: boolean }): boolean {
+	if (result.isError) return false;
 	return result.details?.progress?.some((entry) => entry.status === "running")
 		|| result.details?.results.some((entry) => entry.progress?.status === "running")
+		|| (result.details?.mode === "workflow" && result.details?.workflow?.value === undefined)
 		|| false;
 }
 
-function isSlashResultError(result: { details?: Details }): boolean {
-	return result.details?.results.some((entry) => entry.exitCode !== 0 && entry.progress?.status !== "running") || false;
+function isSlashResultError(result: { details?: Details; isError?: boolean }): boolean {
+	return result.isError === true
+		|| result.details?.results.some((entry) => entry.exitCode !== 0 && entry.progress?.status !== "running")
+		|| false;
 }
 
 function isStaleExtensionContextError(error: unknown): boolean {
@@ -307,6 +316,36 @@ class SubagentControlNoticeComponent implements Component {
 	}
 }
 
+export function projectActiveHerdrRuns(state: SubagentState): HerdrStatusRun[] {
+	const active = (status: string) => status === "queued" || status === "running";
+	const foregroundChildrenByWorkflow = new Map<string, Array<{ agent: string; needsAttention: boolean }>>();
+	for (const control of state.foregroundControls.values()) {
+		if (!control.parentWorkflowRunId) continue;
+		const children = control.activeChildren?.size
+			? [...control.activeChildren.values()].map((child) => ({
+				agent: child.agent,
+				needsAttention: child.currentActivityState === "needs_attention",
+			}))
+			: control.currentAgent
+				? [{ agent: control.currentAgent, needsAttention: control.currentActivityState === "needs_attention" }]
+				: [];
+		if (children.length === 0) continue;
+		const existing = foregroundChildrenByWorkflow.get(control.parentWorkflowRunId) ?? [];
+		existing.push(...children);
+		foregroundChildrenByWorkflow.set(control.parentWorkflowRunId, existing);
+	}
+	return [...state.asyncJobs.values()]
+		.filter((job) => active(job.status))
+		.map((job) => {
+			const children = job.mode === "workflow" ? foregroundChildrenByWorkflow.get(job.asyncId) : undefined;
+			return {
+				id: job.asyncId,
+				agents: children?.length ? children.map((child) => child.agent) : job.agents,
+				needsAttention: job.activityState === "needs_attention" || children?.some((child) => child.needsAttention),
+			};
+		});
+}
+
 export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	if (process.env[SUBAGENT_CHILD_ENV] === "1") {
 		return;
@@ -334,7 +373,8 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	const asyncWidgetEnabled = config.asyncWidget !== false;
 	const summaryInlineToolDisplay = config.inlineToolDisplay === "summary";
 	const tempArtifactsDir = getArtifactsDir(null);
-	cleanupAllArtifactDirs(DEFAULT_ARTIFACT_CONFIG.cleanupDays);
+	const artifactCleanupDays = config.artifactConfig?.cleanupDays ?? DEFAULT_ARTIFACT_CONFIG.cleanupDays;
+	cleanupAllArtifactDirs(artifactCleanupDays);
 
 	const state: SubagentState = {
 		baseCwd: "",
@@ -351,6 +391,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 			granted: 0,
 			grantHistory: [],
 		},
+		activeAsyncCapacity: { used: 0, limit: resolveMaxActiveAsyncRunsPerSession(config.maxActiveAsyncRunsPerSession) ?? 0 },
 		asyncJobs: new Map(),
 		fleetJobs: new Map(),
 		foregroundRuns: new Map(),
@@ -360,6 +401,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		lastUiContext: null,
 		poller: null,
 		completionSeen: new Map(),
+		widgetsSuspended: false,
 		watcher: null,
 		watcherRestartTimer: null,
 		resultFileCoalescer: {
@@ -376,12 +418,15 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		? new SubagentFleetStatus(state, async (itemKey) => {
 			const ctx = state.lastUiContext;
 			if (!ctx?.hasUI) return;
-			await openSubagentFleet(ctx, state, { initialKey: itemKey, asyncDirRoot: DIRS.async, resultsDir: DIRS.results });
+			await openSubagentFleet(ctx, state, { initialKey: itemKey, asyncDirRoot: DIRS.async, resultsDir: DIRS.results, fleetKeybindings: config.fleetKeybindings });
 		}, { placement: fleetViewPlacement })
 		: undefined;
 	let executorScheduled: ((id: string, params: SubagentParamsLike, signal: AbortSignal, ctx: ExtensionContext) => Promise<AgentToolResult<Details>>) | undefined;
+	let goalTurnId = 0;
+	const scheduledStoreRoot = config.scheduledRuns?.storeRoot === undefined ? undefined : resolveScheduledStoreRoot(config.scheduledRuns.storeRoot);
 	const scheduledRunManager = createScheduledRunManager({
 		config,
+		storeRoot: scheduledStoreRoot,
 		launch: (params, ctx, signal) => {
 			if (!executorScheduled) {
 				return Promise.resolve({
@@ -394,6 +439,9 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		},
 		resolveCapabilityCeiling: (sessionId) => resolveCurrentSubagentCapabilityCeiling(sessionId),
 	});
+	const { ensurePoller, refreshWidget, handleStarted, handleComplete, resetJobs, restoreActiveJobs, dispose: disposeAsyncJobTracker } = createAsyncJobTracker(pi, state, DIRS.async, {
+		widgetEnabled: asyncWidgetEnabled,
+	});
 	const { startResultWatcher, primeExistingResults, stopResultWatcher } = createResultWatcher(
 		pi,
 		state,
@@ -402,6 +450,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		{
 			notifier: completionNotifier,
 			observeCompletion: (result) => scheduledRunManager.handleAsyncCompletion(result),
+			observedCompletionRunIds: () => scheduledRunManager.observedCompletionRunIds(),
 			deliverIntercomResults: config.intercomBridge?.resultDelivery === true,
 		},
 	);
@@ -415,16 +464,10 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		supervisorChannel.dispose();
 		waitSubscriptionManager.dispose();
 		fleetStatus?.dispose();
-		if (state.poller) {
-			clearInterval(state.poller);
-			state.poller = null;
-		}
+		disposeAsyncJobTracker();
 	};
 	globalStore[runtimeCleanupStoreKey] = runtimeCleanup;
 
-	const { ensurePoller, refreshWidget, handleStarted, handleComplete, resetJobs, restoreActiveJobs } = createAsyncJobTracker(pi, state, DIRS.async, {
-		widgetEnabled: asyncWidgetEnabled,
-	});
 	const executor = createSubagentExecutor({
 		pi,
 		state,
@@ -502,7 +545,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 
 	const executeSubagentCollapsed = (id: string, params: SubagentParamsLike, signal: AbortSignal, onUpdate: ((result: AgentToolResult<Details>) => void) | undefined, ctx: ExtensionContext) => {
 		if (ctx.hasUI) ctx.ui.setToolsExpanded(false);
-		return executor.execute(id, params, signal, onUpdate, ctx);
+		return executor.executePublic(id, params, signal, onUpdate, ctx);
 	};
 
 	const slashBridge = registerSlashSubagentBridge({
@@ -526,23 +569,20 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	const rpcBridge = registerSubagentRpcBridge({
 		events: pi.events,
 		getContext: () => state.lastUiContext,
-		execute: (id, params, signal, onUpdate, ctx) => executor.execute(id, params, signal, onUpdate, ctx),
+		execute: (id, params, signal, onUpdate, ctx) => executor.executePublic(id, params, signal, onUpdate, ctx),
 		state,
 	});
 
 
-	const tool: ToolDefinition<typeof SubagentParams, Details> = {
+	const parameters = createSubagentParamsSchema(config);
+	const tool: ToolDefinition<typeof parameters, Details> = {
 		name: "subagent",
 		label: "Subagent",
 		description: buildSubagentToolDescription(config),
-		parameters: SubagentParams,
+		parameters,
 
 		execute(id, params, signal, onUpdate, ctx) {
-			const input = params as SubagentParamsLike;
-			if (input.tasks !== undefined || input.chain !== undefined || input.concurrency !== undefined || input.chainDir !== undefined || (input.worktree !== undefined && !(input.worktree === true && input.agent))) {
-				return Promise.resolve({ content: [{ type: "text", text: "Legacy top-level chain and parallel inputs were removed; use workflowScript." }], isError: true, details: { mode: "management", results: [] } });
-			}
-			return executeSubagentCollapsed(id, input, signal ?? new AbortController().signal, onUpdate, ctx);
+			return executeSubagentCollapsed(id, params as SubagentParamsLike, signal ?? new AbortController().signal, onUpdate, ctx);
 		},
 
 		renderCall(args, theme) {
@@ -555,11 +595,11 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 			}
 			if (args.workflowScript)
 				return new Text(
-					`${theme.fg("toolTitle", theme.bold("subagent "))}${formatWorkflowManifest(args.workflowScript, args.async, args.clarify)}`,
+					`${theme.fg("toolTitle", theme.bold("subagent "))}${formatWorkflowManifest(args.workflowScript, args.async, false)}`,
 					0,
 					0,
 				);
-			const asyncLabel = args.async === true && args.clarify !== true ? theme.fg("warning", " [async]") : "";
+			const asyncLabel = args.async === true ? theme.fg("warning", " [async]") : "";
 			return new Text(
 				`${theme.fg("toolTitle", theme.bold("subagent "))}${theme.fg("accent", args.agent || "?")}${asyncLabel}`,
 				0,
@@ -576,6 +616,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		},
 
 	};
+
 	Object.assign(tool, {
 		prepareArguments(args: unknown) {
 			validateChainInput(args);
@@ -588,11 +629,27 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	registerWaitTool(pi, state, waitToolConfig.enabled, waitSubscriptionManager);
 
 	pi.on("agent_end", async (_event, ctx) => {
-		if (ctx.hasUI) return;
-		await drainOutstandingWork({ state, events: pi.events });
+		if (!ctx.hasUI) await drainOutstandingWork({ state, events: pi.events });
+		const ownerSessionId = state.currentSessionId;
+		if (!ownerSessionId) return;
+		goalTurnId += 1;
+		try {
+			const location = resolveMissionStoreLocation({ projectRoot: state.baseCwd, ...(config.missions ? { config: config.missions } : {}) });
+			const retainedChildren = listRetainedChildren(DIRS.async, ownerSessionId);
+			for (const notice of collectGoalContinuationNotices({ location, ownerSessionId, retainedChildren, turnId: goalTurnId })) {
+				handleSubagentControlNotice({
+					pi,
+					state,
+					visibleControlNotices: new Set(),
+					details: { source: "goal", event: notice.event, noticeText: notice.message },
+				});
+			}
+		} catch (error) {
+			console.error("Failed to evaluate goal missions:", error);
+		}
 	});
 
-	registerSlashCommands(pi, state);
+	registerSlashCommands(pi, state, { fleetKeybindings: config.fleetKeybindings });
 
 	const eventUnsubscribeStoreKey = "__piSubagentEventUnsubscribes";
 	const controlNoticeSeenStoreKey = "__piSubagentVisibleControlNotices";
@@ -610,13 +667,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	const existingVisibleControlNotices = globalStore[controlNoticeSeenStoreKey];
 	const visibleControlNotices = existingVisibleControlNotices instanceof Set ? existingVisibleControlNotices as Set<string> : new Set<string>();
 	globalStore[controlNoticeSeenStoreKey] = visibleControlNotices;
-	const activeHerdrRuns = () => [...state.asyncJobs.values()]
-		.filter((job) => job.status === "queued" || job.status === "running")
-		.map((job) => ({
-			id: job.asyncId,
-			agents: job.agents,
-			needsAttention: job.activityState === "needs_attention",
-		}));
+	const activeHerdrRuns = () => projectActiveHerdrRuns(state);
 	const herdrStatusBridge = registerHerdrStatusBridge({
 		events: pi.events,
 		getRuns: activeHerdrRuns,
@@ -641,17 +692,17 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	};
 	const asyncCompleteHandler = (payload: unknown) => {
 		handleComplete(payload);
+		refreshActiveAsyncCapacity();
 		scheduledRunManager.handleAsyncCompletion(payload);
-		try {
-			syncMissionFromAsyncCompletion(payload);
-		} catch (error) {
-			console.error("Failed to update mission from async completion:", error);
-		}
 		fleetStatus?.refresh();
 	};
 	const eventUnsubscribes = [
 		pi.events.on(SUBAGENT_ASYNC_STARTED_EVENT, asyncStartedHandler),
 		pi.events.on(SUBAGENT_ASYNC_COMPLETE_EVENT, asyncCompleteHandler),
+		pi.events.on(SUBAGENT_PROCESS_TERMINAL_EVENT, () => {
+			refreshActiveAsyncCapacity();
+			fleetStatus?.refresh();
+		}),
 		pi.events.on(SUBAGENT_CONTROL_EVENT, controlEventHandler),
 		pi.events.on(SUBAGENT_STEERING_NOTICE_EVENT, steeringNoticeHandler),
 		herdrStatusBridge.dispose,
@@ -676,15 +727,43 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		try {
 			const sessionFile = ctx.sessionManager.getSessionFile();
 			if (sessionFile) {
-				cleanupOldArtifacts(getArtifactsDir(sessionFile), DEFAULT_ARTIFACT_CONFIG.cleanupDays);
+				cleanupOldArtifacts(getArtifactsDir(sessionFile), artifactCleanupDays);
 			}
 		} catch {
 			// Cleanup failures should not block session lifecycle events.
 		}
 	};
 
+	const suspendWidgetsForCompaction = () => {
+		if (state.widgetsSuspended) return;
+		state.widgetsSuspended = true;
+		if (state.lastUiContext?.hasUI) state.lastUiContext.ui.setWidget(WIDGET_KEY, undefined);
+		fleetStatus?.refresh();
+	};
+	const resumeWidgetsAfterCompaction = () => {
+		if (!state.widgetsSuspended) return;
+		state.widgetsSuspended = false;
+		const ctx = state.lastUiContext;
+		if (ctx?.hasUI) refreshWidget(ctx);
+		fleetStatus?.refresh();
+	};
+
+	const refreshActiveAsyncCapacity = () => {
+		if (!state.currentSessionId) {
+			state.activeAsyncCapacity = { used: 0, limit: resolveMaxActiveAsyncRunsPerSession(config.maxActiveAsyncRunsPerSession) ?? 0 };
+			return;
+		}
+		state.activeAsyncCapacity = getActiveAsyncCapacitySnapshot(
+			state.currentSessionId,
+			resolveMaxActiveAsyncRunsPerSession(config.maxActiveAsyncRunsPerSession),
+			{ liveWorkflowRunIds: new Set(state.workflowControllers?.keys() ?? []) },
+		);
+	};
+
 	const resetSessionState = (ctx: ExtensionContext, recovering: boolean) => {
+		state.widgetsSuspended = false;
 		state.baseCwd = ctx.cwd;
+		goalTurnId = 0;
 		state.currentSessionId = resolveCurrentSessionId(ctx.sessionManager);
 		state.parentSessionFile = ctx.sessionManager.getSessionFile();
 		state.subagentSpawns = {
@@ -706,10 +785,12 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 			}
 		}
 		state.lastUiContext = ctx;
+		refreshActiveAsyncCapacity();
 		cleanupSessionArtifacts(ctx);
 		state.foregroundControls.clear();
 		state.lastForegroundControlId = null;
 		resetJobs(ctx);
+		restoreForegroundRunHistory(state, { resultsDir: DIRS.results });
 		restoreActiveJobs(ctx);
 		scheduledRunManager.bindSession(ctx);
 		restoreSlashFinalSnapshots(ctx.sessionManager.getEntries());
@@ -720,9 +801,18 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	};
 
 	pi.on("agent_start", () => {
+		resumeWidgetsAfterCompaction();
 		herdrStatusBridge.agentStarted();
 	});
 
+	pi.on("agent_settled", () => {
+		resumeWidgetsAfterCompaction();
+	});
+
+	pi.on("session_before_compact", (event) => {
+		if (event.reason !== "manual") suspendWidgetsForCompaction();
+	});
+
 	pi.on("session_compact", () => {
 		const hasActiveAsyncWork = [...state.asyncJobs.values()].some((job) => job.status === "queued" || job.status === "running");
 		if (!hasActiveAsyncWork || state.lastUiContext?.hasUI !== true) return;
@@ -748,6 +838,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	});
 
 	pi.on("session_shutdown", async () => {
+		state.widgetsSuspended = false;
 		stopResultWatcher();
 		state.currentSessionId = null;
 		state.parentSessionFile = null;
@@ -764,8 +855,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 			delete globalStore[eventUnsubscribeStoreKey];
 		}
 		scheduledRunManager.stop();
-		if (state.poller) clearInterval(state.poller);
-		state.poller = null;
+		disposeAsyncJobTracker();
 		for (const timer of state.cleanupTimers.values()) {
 			clearTimeout(timer);
 		}

package/dist/extensions/pi-subagents/src/extension/public-execution.ts

@@ -0,0 +1,77 @@
+export interface PublicSubagentExecutionParams {
+	action?: unknown;
+	agent?: unknown;
+	task?: unknown;
+	step?: unknown;
+	tasks?: unknown;
+	chain?: unknown;
+	parallel?: unknown;
+	concurrency?: unknown;
+	chainDir?: unknown;
+	workflowScript?: unknown;
+	resume?: unknown;
+	clarify?: unknown;
+	runFanoutBudget?: unknown;
+	runFanoutAdmitted?: unknown;
+}
+
+export type PublicSubagentExecutionMode = "workflow" | "management";
+
+export type PublicSubagentExecutionNormalization<T> =
+	| { ok: true; params: T }
+	| { ok: false; error: string; mode: PublicSubagentExecutionMode };
+
+/**
+ * Normalize public execution requests before they reach the executor. All four
+ * execution modes (SINGLE, CHAIN, PARALLEL, SCRIPTED WORKFLOW) are first-class;
+ * only malformed or contradictory shapes are rejected. Internal runs.run
+ * children and structured owned delegation bypass this boundary.
+ */
+export function normalizePublicSubagentExecution<T extends PublicSubagentExecutionParams>(params: T): PublicSubagentExecutionNormalization<T> {
+	if (params.runFanoutBudget !== undefined || params.runFanoutAdmitted !== undefined) {
+		return { ok: false, error: "Public execution does not accept internal run fan-out fields.", mode: params.workflowScript !== undefined ? "workflow" : "management" };
+	}
+	const action = params.action;
+	if (action !== undefined && (typeof action !== "string" || !action.trim())) {
+		return { ok: false, error: "action must be a non-empty management/control action, or omit action and execute directly.", mode: "management" };
+	}
+	const normalizedAction = typeof action === "string" ? action.trim() : undefined;
+	if (params.clarify === true && params.workflowScript !== undefined) {
+		return { ok: false, error: "Public workflowScript execution does not support clarify UI.", mode: "workflow" };
+	}
+	if (params.resume !== undefined) {
+		return { ok: false, error: "Top-level resume execution is not available. Put resume on a workflowScript runs.run/runs.all item.", mode: "workflow" };
+	}
+	if (normalizedAction !== undefined) {
+		const legacyAction = normalizedAction.toLowerCase();
+		if (legacyAction === "single" || legacyAction === "parallel" || legacyAction === "tasks" || legacyAction === "chain") {
+			return { ok: false, error: `action '${normalizedAction}' is not a management action; use the direct execution fields ({ agent, task }, { chain: [...] }, { tasks: [...] }).`, mode: "workflow" };
+		}
+		if (normalizedAction === "schedule.create") {
+			if (typeof params.workflowScript === "string" && params.workflowScript.trim()) {
+				return { ok: true, params: { ...params, action: normalizedAction } };
+			}
+			if (params.agent === undefined && params.task === undefined && params.step === undefined && params.tasks === undefined && params.chain === undefined) {
+				return { ok: false, error: "schedule.create requires a non-empty workflowScript or direct execution fields (agent, task, tasks, or chain).", mode: "management" };
+			}
+			return { ok: true, params: { ...params, action: normalizedAction } };
+		}
+		if (params.workflowScript !== undefined) {
+			return { ok: false, error: "workflowScript execution must omit action; only schedule.create accepts action with workflowScript.", mode: "management" };
+		}
+		return { ok: true, params: { ...params, action: normalizedAction } };
+	}
+	if (typeof params.workflowScript === "string" && params.workflowScript.trim()) {
+		return { ok: true, params };
+	}
+	if (params.chain !== undefined) {
+		return { ok: true, params };
+	}
+	if (params.tasks !== undefined) {
+		return { ok: true, params };
+	}
+	if (params.agent !== undefined || params.task !== undefined || params.step !== undefined) {
+		return { ok: true, params };
+	}
+	return { ok: false, error: "Execution requires one mode: { agent, task? }, { chain: [...] }, { tasks: [...] }, or { workflowScript }.", mode: "workflow" };
+}

package/dist/extensions/pi-subagents/src/extension/rpc.ts

@@ -2,6 +2,7 @@ import * as path from "node:path";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import type { ExtensionContext } from "@selesai/code";
 import { Compile } from "typebox/compile";
+import { validateChainInput } from "./chain-validation.ts";
 import { resolveAsyncRunLocation } from "../runs/background/async-resume.ts";
 import { deliverStopRequest } from "../runs/background/control-channel.ts";
 import { reconcileAsyncRun } from "../runs/background/stale-run-reconciler.ts";
@@ -16,10 +17,10 @@ import {
 	SUBAGENT_PROCESS_TERMINAL_EVENT,
 	SUBAGENT_LIFECYCLE_ARTIFACT_VERSION,
 } from "../shared/types.ts";
+import { sanitizeDisplayText, truncateDisplayText } from "../shared/display-text.ts";
 import { readStatus } from "../shared/utils.ts";
 import { SubagentParams } from "./schemas.ts";
-import { validateChainInput } from "./chain-validation.ts";
-import { formatWorkflowJsonPreview } from "../workflows/scripted-workflow.ts";
+import { normalizePublicSubagentExecution } from "./public-execution.ts";
 
 export const SUBAGENT_RPC_PROTOCOL_VERSION = 1;
 export const SUBAGENT_RPC_REQUEST_EVENT = "subagents:rpc:v1:request";
@@ -90,6 +91,7 @@ export interface SubagentRpcFleetStatus {
 	entries: SubagentRpcFleetEntry[];
 	/** Total active children before the bounded entries window. */
 	totalActive: number;
+	topLevelAsyncCapacity: { used: number; limit: number };
 	omitted: number;
 }
 
@@ -101,12 +103,8 @@ const MAX_METADATA_LENGTH = 128;
 
 function displayText(value: unknown, maxLength: number): string | undefined {
 	if (typeof value !== "string") return undefined;
-	// Strip complete CSI/OSC/DCS/APC/PM strings and C1 controls before collapsing
-	// whitespace; never leave CSI parameters behind after removing ESC.
-	const normalized = value.slice(0, 4_096)
-		.replace(/\x1b\[[0-?]*[ -/]*[@-~]|\x9b[0-?]*[ -/]*[@-~]|\x1b][\s\S]*?(?:\x07|\x1b\\)|\x1b[PX^_][\s\S]*?\x1b\\|[\u0000-\u001f\u007f-\u009f]/g, " ")
-		.replace(/\s+/g, " ").trim();
-	return normalized ? normalized.slice(0, maxLength) : undefined;
+	const normalized = sanitizeDisplayText(value.slice(0, 4_096));
+	return normalized ? truncateDisplayText(normalized, maxLength) : undefined;
 }
 
 function publicTokens(value: unknown): { input: number; output: number; total: number } {
@@ -157,7 +155,7 @@ function buildFleetStatus(
 	}
 	if (!state || !authoritativeSessionId || state.currentSessionId !== authoritativeSessionId) {
 		keyState.keys.clear();
-		return { version: 1, entries: [], totalActive: 0, omitted: 0 };
+		return { version: 1, entries: [], totalActive: 0, topLevelAsyncCapacity: { used: 0, limit: 0 }, omitted: 0 };
 	}
 
 	let totalActive = 0;
@@ -176,7 +174,6 @@ function buildFleetStatus(
 				effort: child.thinking,
 				startedAt: child.startedAt,
 				tokens: { input: child.inputTokens ?? 0, output: child.outputTokens ?? 0, total: child.tokens ?? 0 },
-				goal: child.description ?? control.description,
 			});
 		} else {
 			addCandidate({
@@ -186,7 +183,6 @@ function buildFleetStatus(
 				effort: control.thinking,
 				startedAt: control.startedAt,
 				tokens: { input: control.inputTokens ?? 0, output: control.outputTokens ?? 0, total: control.tokens ?? 0 },
-				goal: control.description,
 			});
 		}
 	}
@@ -194,13 +190,11 @@ function buildFleetStatus(
 		if (job.sessionId !== authoritativeSessionId || !activeState(job.status)) continue;
 		const startedAt = job.startedAt ?? job.updatedAt;
 		if (job.mode === "workflow") {
-			const latestEmit = job.workflow?.emits?.length ? formatWorkflowJsonPreview(job.workflow.emits.at(-1), 120) : undefined;
 			addCandidate({
 				internalKey: `async:${job.asyncId}`,
 				agent: "workflow",
 				startedAt,
 				tokens: job.totalTokens,
-				goal: latestEmit !== undefined ? `latest emit: ${latestEmit}` : job.description,
 			});
 			continue;
 		}
@@ -217,7 +211,6 @@ function buildFleetStatus(
 				agent: job.mode ?? "subagent",
 				startedAt,
 				tokens: job.totalTokens,
-				goal: job.description,
 			});
 			continue;
 		}
@@ -233,7 +226,6 @@ function buildFleetStatus(
 				effort: step.thinking,
 				startedAt: step.startedAt ?? startedAt,
 				tokens: step.tokens ?? (steps.length === 1 ? job.totalTokens : undefined),
-				goal: job.description,
 			});
 		}
 	}
@@ -274,7 +266,7 @@ function buildFleetStatus(
 		if (!activeKeys.has(internalKey)) keyState.keys.delete(internalKey);
 	}
 	const omitted = Math.max(0, totalActive - entries.length);
-	return { version: 1, entries, totalActive, omitted };
+	return { version: 1, entries, totalActive, topLevelAsyncCapacity: state.activeAsyncCapacity ?? { used: 0, limit: 0 }, omitted };
 }
 
 interface RegisterSubagentRpcBridgeOptions {
@@ -426,19 +418,15 @@ async function executeChecked(
 
 function spawnParams(params: unknown): SubagentParamsLike {
 	const input = assertRecordParams(params, "spawn");
-	if (input.tasks !== undefined || input.chain !== undefined || input.concurrency !== undefined || input.chainDir !== undefined || (input.worktree !== undefined && !(input.worktree === true && input.agent))) {
-		throw new SubagentRpcError("invalid_params", "RPC spawn no longer accepts top-level chain or parallel inputs; use workflowScript.");
-	}
-	if (input.action !== undefined) {
+	const normalized = normalizePublicSubagentExecution(input);
+	if (!normalized.ok) throw new SubagentRpcError("invalid_params", normalized.error);
+	if (normalized.params.action !== undefined) {
 		throw new SubagentRpcError("invalid_params", "RPC spawn does not accept management/control actions. Use status or interrupt RPC methods instead.");
 	}
 	if (input.async === false) {
 		throw new SubagentRpcError("invalid_params", "RPC spawn only supports detached async launches; omit async or set async: true.");
 	}
-	if (input.clarify === true) {
-		throw new SubagentRpcError("invalid_params", "RPC spawn cannot open the clarify UI; omit clarify or set clarify: false.");
-	}
-	return { ...(input as SubagentParamsLike), async: true, clarify: false };
+	return { ...(normalized.params as SubagentParamsLike), async: true };
 }
 
 function steerParams(params: unknown): SubagentParamsLike {
@@ -447,10 +435,12 @@ function steerParams(params: unknown): SubagentParamsLike {
 		throw new SubagentRpcError("invalid_params", "RPC steer requires a non-empty message.");
 	const target = normalizeTargetParams(input, "steer");
 	if (!target.id && !target.runId && !target.dir) throw new SubagentRpcError("invalid_params", "RPC steer requires id, runId, or dir.");
+	if (input.mode !== undefined && input.mode !== "steer" && input.mode !== "follow_up" && input.mode !== "auto") throw new SubagentRpcError("invalid_params", "RPC steer mode must be steer, follow_up, or auto.");
 	return {
 		action: "steer",
 		...target,
 		message: input.message.trim(),
+		...(typeof input.mode === "string" ? { mode: input.mode as "steer" | "follow_up" | "auto" } : {}),
 		steeringRecovery: false,
 	};
 }
@@ -500,6 +490,10 @@ function stopAsyncRun(
 		throw new SubagentRpcError("not_found", `Async run '${initialRunId}' was not found in the active session.`);
 	}
 
+	if (initialStatus.mode === "workflow" && initialStatus.state === "running") {
+		throw new SubagentRpcError("invalid_state", `Workflow ${initialRunId} is not controlled by this extension runtime; reload recovery cannot stop it safely.`);
+	}
+
 	let status;
 	try {
 		status = reconcileAsyncRun(location.asyncDir, { resultsDir, kill: options.kill, now: options.now }).status;