@selesai/code 0.13.2 → 0.13.4

package/dist/extensions/pi-subagents/src/agents/agent-management.ts

@@ -32,9 +32,10 @@ import { toModelInfo } from "../shared/model-info.ts";
 import { resolveSubagentModelOverride, type ParentModel } from "../runs/shared/model-fallback.ts";
 import { validateToolBudgetConfig } from "../runs/shared/tool-budget.ts";
 import { validateAcceptanceInput } from "../runs/shared/acceptance.ts";
-import { CODE_OWNED_EXTERNAL_CLI_ADAPTER_LABEL, isCodeOwnedExternalCliAdapterId, validateCodeOwnedProfileRunner } from "../runs/shared/external-cli-contract.ts";
-import type { AcceptanceInput, Details, ExtensionConfig, ToolBudgetConfig } from "../shared/types.ts";
+import { CODE_OWNED_EXTERNAL_CLI_ADAPTER_LABEL, isCodeOwnedExternalCliAdapterId, resolveExternalCliRunnerStatus, validateCodeOwnedProfileRunner } from "../runs/shared/external-cli-contract.ts";
+import type { AcceptanceInput, AgentCapabilitiesSnapshot, AgentCapabilityRow, Details, ExtensionConfig, ToolBudgetConfig } from "../shared/types.ts";
 import { getProjectConfigDir } from "../shared/utils.ts";
+import { previewDisplayText } from "../shared/display-text.ts";
 import { capabilityCeilingAgentRestrictionSources, isAgentAllowedByCapabilityCeiling, resolveCurrentSubagentCapabilityCeiling } from "../runs/shared/capability-ceiling.ts";
 import { listRuntimeAgentConfigs, mergeRuntimeAgents, type RuntimeAgentOwner } from "./runtime-agent-registry.ts";
 import { listExternalJobProviders } from "../api/external-job-provider.ts";
@@ -47,11 +48,21 @@ interface ManagementParams {
 	action?: string;
 	agent?: string;
 	agentScope?: unknown;
+	capabilities?: unknown;
 	config?: unknown;
 }
 
-function result(text: string, isError = false): AgentToolResult<Details> {
-	return { content: [{ type: "text", text }], isError, details: { mode: "management", results: [] } };
+function result(text: string, isError = false, details?: Partial<Details>): AgentToolResult<Details> {
+	return { content: [{ type: "text", text }], isError, details: { mode: "management", results: [], ...details } };
+}
+
+function jsonDetails<T>(value: T): T {
+	return JSON.parse(JSON.stringify(value)) as T;
+}
+
+function presentDetails<T extends Record<string, unknown>>(value: T): T | undefined {
+	const cleaned = jsonDetails(value);
+	return Object.keys(cleaned).length > 0 ? cleaned : undefined;
 }
 
 function parseCsv(value: string): string[] {
@@ -645,18 +656,135 @@ function runnerListBadge(agent: AgentConfig, providerNames: Set<string> | undefi
 	return undefined;
 }
 
-function formatAgentListLine(agent: AgentConfig, providerNames: Set<string> | undefined): string {
+function agentListMetadata(agent: AgentConfig, providerNames: Set<string> | undefined): string {
 	const source = agent.source === "package" ? packageSourceLabel(agent) : agent.source;
-	const parts = [
+	return [
 		source,
 		runnerListBadge(agent, providerNames),
 		agent.defaultContext ? `context: ${agent.defaultContext}` : undefined,
 		agent.aliases?.length ? `aliases: ${agent.aliases.join(", ")}` : undefined,
-	].filter((part): part is string => Boolean(part));
-	return `- ${agent.name} (${parts.join(", ")}): ${agent.description}`;
+	].filter((part): part is string => Boolean(part)).join(", ");
+}
+
+function formatAgentListLine(agent: AgentConfig, providerNames: Set<string> | undefined): string {
+	return `- ${agent.name} (${agentListMetadata(agent, providerNames)}): ${agent.description}`;
+}
+
+function formatAgentCapabilitiesLine(agent: AgentConfig, providerNames: Set<string> | undefined): string {
+	const declaredTools = [
+		...(agent.tools ?? []),
+		...(agent.mcpDirectTools ?? []).map((tool) => `mcp:${tool}`),
+	];
+	let tools = "none";
+	if (agent.tools === undefined && agent.mcpDirectTools === undefined) {
+		tools = "default/ambient";
+	} else if (declaredTools.length > 0) {
+		tools = declaredTools.join(", ");
+	}
+	let model = "inherits current session";
+	if (agent.model !== undefined) {
+		model = agent.model;
+		if (agent.modelProvider && !agent.model.includes("/")) model = `${agent.modelProvider}/${agent.model}`;
+	}
+	const thinking = agent.thinking === false ? "off" : agent.thinking ?? "default";
+	return `- ${agent.name} (${agentListMetadata(agent, providerNames)}): Description: ${previewDisplayText(agent.description, 240)}; Tools: ${tools}; Model: ${model}; Thinking: ${thinking}`;
+}
+
+const EXTERNAL_JOB_CAPABILITIES = { stop: false, steer: false, resume: false, structuredOutput: false, toolEvents: false } as const;
+const PI_AGENT_RUNNER = { type: "pi" } as const;
+
+function listOrEmpty<T>(values: T[] | undefined): T[] {
+	return values ?? [];
+}
+
+function agentCapabilityRunner(agent: AgentConfig, providerNames: Set<string> | undefined): AgentCapabilityRow["runner"] {
+	const runner = agent.runner;
+	if (!runner || runner.type === "pi") return PI_AGENT_RUNNER;
+	if (runner.type === "external-cli") return { type: "external-cli", adapter: runner.adapter, capabilities: resolveExternalCliRunnerStatus(runner).capabilities };
+	return { type: "external-job", provider: runner.provider, available: providerNames?.has(runner.provider), capabilities: EXTERNAL_JOB_CAPABILITIES };
+}
+
+function agentCapabilityTools(agent: AgentConfig): AgentCapabilityRow["tools"] {
+	return {
+		ambient: agent.tools === undefined && agent.mcpDirectTools === undefined,
+		names: listOrEmpty(agent.tools),
+		mcpDirectTools: listOrEmpty(agent.mcpDirectTools),
+		mutationTools: agent.mutationTools,
+	};
+}
+
+function agentCapabilityRow(agent: AgentConfig, options: { executable: boolean; providerNames?: Set<string>; restrictionSources?: string[] }): AgentCapabilityRow {
+	return {
+		name: agent.name,
+		description: previewDisplayText(agent.description, 1000),
+		source: agent.source,
+		executable: options.executable,
+		restrictionSources: options.executable ? undefined : options.restrictionSources ?? [],
+		aliases: agent.aliases ? [...agent.aliases] : undefined,
+		runner: agentCapabilityRunner(agent, options.providerNames),
+		tools: agentCapabilityTools(agent),
+		model: presentDetails({ value: agent.model, fallbackModels: agent.fallbackModels, thinking: agent.thinking }),
+		execution: presentDetails({ defaultAsync: agent.defaultAsync, timeoutMs: agent.defaultTimeoutMs }),
+		output: presentDetails({ path: agent.output, mode: agent.outputMode }),
+		extensions: presentDetails({ names: agent.extensions, subagentOnly: agent.subagentOnlyExtensions, skills: agent.skills }),
+	};
 }
 
-function formatAgentListSections(agents: AgentConfig[], providerNames: Set<string> | undefined): string[] {
+function agentCapabilitiesSnapshot(input: { agents: AgentConfig[]; restrictedAgents: AgentConfig[]; providerNames?: Set<string>; restrictedSources?: string[] }): AgentCapabilitiesSnapshot {
+	return {
+		agents: [
+			...input.agents.map((agent) => agentCapabilityRow(agent, { executable: true, providerNames: input.providerNames })),
+			...input.restrictedAgents.map((agent) => agentCapabilityRow(agent, { executable: false, providerNames: input.providerNames, restrictionSources: input.restrictedSources })),
+		],
+		restrictedCount: input.restrictedAgents.length,
+		...(input.restrictedSources?.length ? { capabilityCeilingSources: [...input.restrictedSources] } : {}),
+	};
+}
+
+function providerNames(status: ExternalJobProviderStatus): Set<string> | undefined {
+	return status.ok ? status.names : undefined;
+}
+
+function appendRestrictedAgentLines(input: { lines: string[]; agents: AgentConfig[]; sources?: string[]; providerNames?: Set<string>; formatLine: (agent: AgentConfig, providerNames: Set<string> | undefined) => string }): void {
+	if (input.agents.length === 0) return;
+	input.lines.push(
+		"",
+		`Restricted agents (not executable in this session${input.sources?.length ? `; capability ceiling: ${input.sources.join(", ")}` : ""}):`,
+		...input.agents.map((agent) => input.formatLine(agent, input.providerNames)),
+	);
+}
+
+function appendExternalJobRegistryLine(lines: string[], agents: AgentConfig[], status: ExternalJobProviderStatus): void {
+	if (status.ok || !agents.some((agent) => agent.runner?.type === "external-job")) return;
+	lines.push("", `External-job provider registry unavailable: ${status.error}`);
+}
+
+function appendAgentDiagnosticLines(lines: string[], diagnostics: AgentDiscoveryDiagnostic[] | undefined): void {
+	if (!diagnostics?.length) return;
+	lines.push(
+		"",
+		"Invalid agent definitions:",
+		...diagnostics.map((diagnostic) => `- ${diagnostic.name ?? diagnostic.filePath} (${diagnostic.source}): ${diagnostic.error}`),
+	);
+}
+
+function agentCapabilityDetails(input: { capabilityMode: boolean; agents: AgentConfig[]; restrictedAgents: AgentConfig[]; providerNames?: Set<string>; restrictedSources?: string[] }): Partial<Details> | undefined {
+	if (!input.capabilityMode) return undefined;
+	return {
+		agentCapabilities: jsonDetails(agentCapabilitiesSnapshot({
+			agents: input.agents,
+			restrictedAgents: input.restrictedAgents,
+			providerNames: input.providerNames,
+			restrictedSources: input.restrictedSources,
+		})),
+	};
+}
+
+function formatAgentListSections(
+	agents: AgentConfig[],
+	providerNames: Set<string> | undefined,
+	formatLine: (agent: AgentConfig, providerNames: Set<string> | undefined) => string = formatAgentListLine,
+): string[] {
 	if (agents.length === 0) return ["- (none)"];
 	const sections: Array<[AgentSource, string]> = [
 		["package", "Package agents"],
@@ -670,7 +798,7 @@ function formatAgentListSections(agents: AgentConfig[], providerNames: Set<strin
 		const matches = agents.filter((agent) => agent.source === source);
 		if (matches.length === 0) continue;
 		if (lines.length > 0) lines.push("");
-		lines.push(label, ...matches.map((agent) => formatAgentListLine(agent, providerNames)));
+		lines.push(label, ...matches.map((agent) => formatLine(agent, providerNames)));
 	}
 	return lines;
 }
@@ -758,23 +886,24 @@ export function handleList(params: ManagementParams, ctx: ManagementContext): Ag
 		discoverAvailableSkills: () => discoverAvailableSkills(ctx.cwd),
 	});
 	const providerStatus = registeredExternalJobProviderStatus();
+	const providerNameSet = providerNames(providerStatus);
+	const capabilityMode = params.capabilities === true;
+	const formatLine = capabilityMode ? formatAgentCapabilitiesLine : formatAgentListLine;
 	const lines = [
-		"Executable agents:",
-		...formatAgentListSections(agents, providerStatus.ok ? providerStatus.names : undefined),
-		...(restrictedAgents.length ? [
-			"",
-			`Restricted agents (not executable in this session${restrictedSources?.length ? `; capability ceiling: ${restrictedSources.join(", ")}` : ""}):`,
-			...restrictedAgents.map((a) => formatAgentListLine(a, providerStatus.ok ? providerStatus.names : undefined)),
-		] : []),
-		...(!providerStatus.ok && [...agents, ...restrictedAgents].some((agent) => agent.runner?.type === "external-job") ? ["", `External-job provider registry unavailable: ${providerStatus.error}`] : []),
-		...(d.agentDiagnostics?.length ? [
-			"",
-			"Invalid agent definitions:",
-			...d.agentDiagnostics.map((diagnostic) => `- ${diagnostic.name ?? diagnostic.filePath} (${diagnostic.source}): ${diagnostic.error}`),
-		] : []),
-		...(proactiveSuggestions.length ? ["", ...proactiveSuggestions] : []),
+		capabilityMode ? "Executable agents (capabilities):" : "Executable agents:",
+		...formatAgentListSections(agents, providerNameSet, formatLine),
 	];
-	return result(lines.join("\n"));
+	appendRestrictedAgentLines({ lines, agents: restrictedAgents, sources: restrictedSources, providerNames: providerNameSet, formatLine });
+	appendExternalJobRegistryLine(lines, [...agents, ...restrictedAgents], providerStatus);
+	appendAgentDiagnosticLines(lines, d.agentDiagnostics);
+	if (proactiveSuggestions.length) lines.push("", ...proactiveSuggestions);
+	return result(lines.join("\n"), false, agentCapabilityDetails({
+		capabilityMode,
+		agents,
+		restrictedAgents,
+		providerNames: providerNameSet,
+		restrictedSources,
+	}));
 }
 
 function formatModelSource(agent: AgentConfig, currentModel: ParentModel | undefined): string {
@@ -1066,7 +1195,7 @@ function handleDisable(params: ManagementParams, ctx: ManagementContext): AgentT
 	const scope = parsedScope.scope!;
 	const d = discoverAgentsAll(ctx.cwd);
 	if (scope === "project" && d.projectSettingsPath === null) {
-		return result("Project override is not available here: no project config root (.pi or .agents) was found above the cwd. Use agentScope: 'user' or run from inside a project.", true);
+		return result("Project override is not available here: no project config root (.selesai or .agents) was found above the cwd. Use agentScope: 'user' or run from inside a project.", true);
 	}
 	const effective = resolveEffectiveAgent(d, raw);
 	if (effective.error) return result(effective.error, true);
@@ -1090,7 +1219,7 @@ function handleEnable(params: ManagementParams, ctx: ManagementContext): AgentTo
 	const scope = parsedScope.scope!;
 	const d = discoverAgentsAll(ctx.cwd);
 	if (scope === "project" && d.projectSettingsPath === null) {
-		return result("Project override is not available here: no project config root (.pi or .agents) was found above the cwd. Use agentScope: 'user' or run from inside a project.", true);
+		return result("Project override is not available here: no project config root (.selesai or .agents) was found above the cwd. Use agentScope: 'user' or run from inside a project.", true);
 	}
 	const effective = resolveEffectiveAgent(d, raw);
 	if (effective.error) return result(effective.error, true);
@@ -1119,7 +1248,7 @@ function handleReset(params: ManagementParams, ctx: ManagementContext): AgentToo
 	const scope = parsedScope.scope!;
 	const d = discoverAgentsAll(ctx.cwd);
 	if (scope === "project" && d.projectSettingsPath === null) {
-		return result("Project override is not available here: no project config root (.pi or .agents) was found above the cwd. Use agentScope: 'user' or run from inside a project.", true);
+		return result("Project override is not available here: no project config root (.selesai or .agents) was found above the cwd. Use agentScope: 'user' or run from inside a project.", true);
 	}
 	const bundled = [...d.package, ...d.builtin].find((a) => a.name === raw || a.name === sanitized);
 	if (!bundled) {

package/dist/extensions/pi-subagents/src/api/shared-types.ts

@@ -5,6 +5,8 @@ export {
 	type AcceptanceInput,
 	type AcceptanceLedger,
 	type AcceptanceLevel,
+	type AgentCapabilitiesSnapshot,
+	type AgentCapabilityRow,
 	type AsyncStartedEvent,
 	type ControlEvent,
 	type Details,

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

@@ -1,5 +1,6 @@
 export interface PublicSubagentExecutionParams {
 	action?: unknown;
+	capabilities?: unknown;
 	mode?: unknown;
 	repo?: unknown;
 	planId?: unknown;

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

@@ -282,6 +282,7 @@ const SubagentParamProperties = {
 	action: Type.Optional(Type.String({ minLength: 1,
 		description: "Optional management/control action. Use action='validate' with workflowScript or workflowScriptPath for offline checks. Omit this field for structured single-child or workflow execution; otherwise, use it only for management/control actions."
 	})),
+	capabilities: Type.Optional(Type.Boolean({ description: "For action='list', return compact capability rows and structured details without system prompts." })),
 	name: Type.Optional(Type.String({ description: "Human-readable name for action='schedule.create'." })),
 	id: Type.Optional(Type.String({
 		description: "Run id/prefix for status/debug.run, interrupt, steer, or mission.attach-run."

package/dist/extensions/pi-subagents/src/extension/tool-description.ts

@@ -9,7 +9,9 @@ const EXTERNAL_CLI_RUNNER_GUIDANCE = "External CLI agents (codex-exec, codex-exe
 const WORKFLOW_RESUME_KEY_GUIDANCE = "Each workflow key identifies one result lane: use a new stable workflow key for every distinct retained resume pass; same-key calls are reused only when launch parameters are identical, and incompatible parameters are rejected.";
 const WORKFLOW_OUTPUT_BINDING_GUIDANCE = "For durable workflow child files, set output on runs.run/runs.all; task filename prose is not an output declaration, and return the child's outputReference, outputPathMapping, or artifactPaths instead of inventing a literal path.";
 const WORKFLOW_LANES_GUIDANCE = "For bounded parallel sequential chains, use runs.lanes([{key,stages:[{key,agent,task},{key,resume:'previous',task},...]}]); first stages run together, later stages sequence per lane, and the bounded board reports lane-local failures. Only an explicit structuredOutput.verdict === 'blocked' blocks a successful stage; reviewer prose is not parsed.";
-const WORKFLOW_HOST_GUIDANCE = "For one non-interactive operator-owned command, await runs.host(key,{kind:'command',command,timeoutMs,output?,role?,provider?}). v1 supports only command steps; output is bounded and command failure fails the workflow.";
+const WORKFLOW_SCRIPT_PORTABILITY_GUIDANCE = "workflowScript rejects nested async function, arrow, and method helpers; use top-level await, plain helper functions that return runs.run(...), or explicit Promise chains instead.";
+const WORKFLOW_HOST_GUIDANCE = "For one non-interactive operator-owned command, await runs.host(key,{kind:'command',command,timeoutMs,output?,role?,provider?}). runs.host has no per-step cwd: commands and relative output paths use the workflow cwd; set cwd on the outer subagent request instead (for example, {cwd:'/path/to/worktree',workflowScript:'...'}), or put a trusted directory change in the command (for example, 'cd /path/to/worktree && npm test'). v1 supports only command steps; output is bounded and command failure fails the workflow.";
+const AGENT_CAPABILITY_GUIDANCE = "For capability selection, use { action: \"list\", capabilities: true } for compact prompt-free rows.";
 
 export const SUBAGENT_SAFETY_GUIDANCE = `SAFETY-CRITICAL SUBAGENT GUIDANCE:
 • Use { action: "list" } before execution and only run executable/non-disabled agents.
@@ -66,6 +68,7 @@ ASYNC / SAFETY:
 • Omitted async follows asyncByDefault config; set async:true explicitly when async behavior matters. Continue independent work only until its next dependency barrier; consume the result before work that depends on it. Do not sleep or poll merely to wait; use subagent_wait only when this turn must receive results.
 • ${WORKFLOW_RESUME_KEY_GUIDANCE}
 • ${WORKFLOW_OUTPUT_BINDING_GUIDANCE}
+• ${WORKFLOW_HOST_GUIDANCE}
 • Ordinary children are not orchestrators. Keep one writer per cwd/worktree and use fresh read-only reviewers for independent checks.
 • Oracle/advisor consultations use available supervisor dialogue for material unknowns; request one-shot when desired.
 • Status and artifacts live under asyncId/asyncDir with status.json, events.jsonl, output logs, and {action:"status",id:"..."}.`;

package/dist/extensions/pi-subagents/src/runs/background/async-execution.ts

@@ -20,6 +20,7 @@ import { buildChainInstructions, isDynamicParallelStep, isParallelStep, resolveE
 import type { RunnerStep } from "../shared/parallel-utils.ts";
 import type { ContextMode } from "../shared/context-mode.ts";
 import { resolvePiPackageRoot } from "../shared/pi-spawn.ts";
+import { backgroundProcessOptions } from "../shared/background-process-options.ts";
 import { preflightLaunchCwd } from "../shared/launch-cwd.ts";
 import { resolveNodeExecutable } from "../../shared/node-executable.ts";
 import { buildSkillInjection, normalizeSkillInput, resolveSkillsWithFallback } from "../../agents/skills.ts";
@@ -562,9 +563,8 @@ function spawnRunner(cfg: object, suffix: string, cwd: string, initialStatus: Om
 		}
 		const proc = spawn(nodeCommand, [jitiCliPath, runner, cfgPath], {
 			cwd,
-			detached: true,
+			...backgroundProcessOptions(),
 			stdio: ["ignore", stdoutFd ?? "ignore", stderrFd ?? "ignore"],
-			windowsHide: true,
 			env: {
 				...omitExtensionBindingsEnv(process.env),
 				...(piPackageRoot ? { [SELESAI_CODING_AGENT_PACKAGE_ROOT_ENV]: piPackageRoot } : {}),

package/dist/extensions/pi-subagents/src/runs/background/async-job-tracker.ts

@@ -146,6 +146,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 			chainStepCount: run.chainStepCount,
 			parallelGroups: groups,
 			hostSteps: run.hostSteps,
+			...(run.mode === "workflow" && run.workflowGraph ? { workflowGraph: run.workflowGraph } : {}),
 			preflight: run.preflight,
 			steps: visibleSteps,
 			stepsTotal: visibleSteps.length,
@@ -401,6 +402,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 				job.workflowKey = status.workflowKey ?? job.workflowKey;
 				job.lane = status.lane ?? job.lane;
 				job.workflow = status.workflow ?? job.workflow;
+				if (status.mode === "workflow") job.workflowGraph = status.workflowGraph ?? job.workflowGraph;
 				job.hostSteps = validHostStepNodes(status.workflowGraph);
 				const workflowChildren = parseWorkflowChildSummary(status.workflowChildren);
 				if (workflowChildren && workflowChildren.workflowRunId !== status.runId) throw new Error("workflowChildren.workflowRunId does not match async status runId.");
@@ -627,6 +629,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 			turnBudget: info.turnBudget,
 			parentWorkflowRunId: info.parentWorkflowRunId,
 			workflowKey: info.workflowKey,
+			...(info.mode === "workflow" && info.workflowGraph ? { workflowGraph: info.workflowGraph } : {}),
 			controlEventCursor: 0,
 		});
 		const job = state.asyncJobs.get(info.id)!;

package/dist/extensions/pi-subagents/src/runs/background/async-status.ts

@@ -1,8 +1,9 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { formatDuration, formatModelThinking, formatTokens, shortenPath } from "../../shared/formatters.ts";
+import { previewDisplayText } from "../../shared/display-text.ts";
 import { formatActivityLabel, formatParallelOutcome } from "../../shared/status-format.ts";
-import { type ActivityState, type AsyncJobStep, type AsyncParallelGroupStatus, type AsyncStatus, type CostSummary, type Details, type HostStepNodeV1, type HostStepState, type LaunchResolvedChildExtensionsV1, type RuntimeAcknowledgedChildExtensionsV1, type NestedRunSummary, type SteeringStatus, type SubagentRunMode, type TokenUsage, type TurnBudgetState, type UsageBudgetState, type WorkflowPreflightV1 } from "../../shared/types.ts";
+import { type ActivityState, type AsyncJobStep, type AsyncParallelGroupStatus, type AsyncStatus, type CostSummary, type Details, type HostStepNodeV1, type HostStepState, type LaunchResolvedChildExtensionsV1, type RuntimeAcknowledgedChildExtensionsV1, type NestedRunSummary, type SteeringStatus, type SubagentRunMode, type TimeoutRecoveryProjection, type TokenUsage, type TurnBudgetState, type UsageBudgetState, type WorkflowPreflightV1, type WorkflowGraphSnapshot } from "../../shared/types.ts";
 import type { ResolvedSubagentCapabilityCeiling, SubagentCapabilityAudit } from "../shared/capability-ceiling.ts";
 import { readStatus } from "../../shared/utils.ts";
 import { attachRootChildrenToSteps, buildNestedRouteIndex, findNestedRouteForRootId, type NestedRoute, projectNestedEvents } from "../shared/nested-events.ts";
@@ -21,6 +22,8 @@ import { assertWorkflowGraphHostSteps, hostStepReportName, hostStepVerdictLabel,
 import { projectAsyncWorkflowRows } from "../shared/async-status-projection.ts";
 import { validateAsyncStatusLaneMetadata } from "../shared/lane-metadata.ts";
 import { formatWorkflowPreflightPlanSummary, formatWorkflowPreflightWarningSummary } from "../../workflows/workflow-preflight.ts";
+import { workflowGraphStageNodes } from "../shared/workflow-graph.ts";
+import { formatTimeoutRecoveryLines, projectTimeoutRecovery } from "../shared/mutation-evidence.ts";
 
 interface AsyncRunStepSummary {
 	index: number;
@@ -75,6 +78,7 @@ interface AsyncRunStepSummary {
 	review?: AsyncJobStep["review"];
 	effects?: AsyncJobStep["effects"];
 	processTerminal?: AsyncJobStep["processTerminal"];
+	timeoutRecovery?: TimeoutRecoveryProjection;
 	launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
 	runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
 	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
@@ -116,6 +120,7 @@ export interface AsyncRunSummary {
 	pendingAppends?: number;
 	parallelGroups?: AsyncParallelGroupStatus[];
 	hostSteps?: HostStepNodeV1[];
+	workflowGraph?: AsyncStatus["workflowGraph"];
 	steps: AsyncRunStepSummary[];
 	sessionDir?: string;
 	outputFile?: string;
@@ -282,6 +287,7 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
 	const summarizedSteps = steps.map((step, index) => {
 		const stepActivityState = step.activityState;
 		const stepLastActivityAt = step.lastActivityAt;
+		const timeoutRecovery = projectTimeoutRecovery(step.timeoutRecovery);
 		return {
 			index,
 			childId: asyncStatusChildIdentity(step, index),
@@ -341,6 +347,7 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
 			...(step.effects ? { effects: step.effects } : {}),
 			...(step.watchdog ? { watchdog: step.watchdog } : {}),
 			...(step.processTerminal ? { processTerminal: sanitizeProcessTerminal(step.processTerminal, { runId: status.runId, runnerProcessInstanceId: step.processTerminal.runnerProcessInstanceId }, `${path.join(asyncDir, "status.json")} step ${index}`) } : {}),
+			...(timeoutRecovery ? { timeoutRecovery } : {}),
 			...(step.capabilityCeiling ? { capabilityCeiling: step.capabilityCeiling } : {}),
 			...(step.capabilityAudit ? { capabilityAudit: step.capabilityAudit } : {}),
 			...(step.children?.length ? { children: step.children } : {}),
@@ -381,6 +388,7 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
 		...(status.pendingAppends !== undefined ? { pendingAppends: status.pendingAppends } : {}),
 		...(parallelGroups.length ? { parallelGroups } : {}),
 		...(hostSteps.length ? { hostSteps } : {}),
+		...(status.mode === "workflow" && status.workflowGraph ? { workflowGraph: status.workflowGraph } : {}),
 		steps: summarizedSteps,
 		...(nestedChildren.length ? { nestedChildren } : {}),
 		...(nestedWarnings.length ? { nestedWarnings } : {}),
@@ -575,12 +583,41 @@ function formatHostStepLine(row: ReturnType<typeof projectAsyncWorkflowRows>[num
 	return `host ${row.kind}: ${row.name} | ${state}${details.length ? ` | ${details.join(" | ")}` : ""}`;
 }
 
+function workflowStageStateLabel(status: WorkflowGraphSnapshot["nodes"][number]["status"]): string {
+	switch (status) {
+		case "completed":
+			return "complete";
+		case "detached":
+			return "paused";
+		default:
+			return status;
+	}
+}
+
+export function formatWorkflowStageLine(node: WorkflowGraphSnapshot["nodes"][number], index: number, total: number): string {
+	const state = workflowStageStateLabel(node.status);
+	const id = previewDisplayText(node.id, 160);
+	const label = node.label ? previewDisplayText(node.label, 160) : "";
+	const display = label && label !== id ? ` | ${label}` : "";
+	const agent = node.agent ? ` | ${previewDisplayText(node.agent, 80)}` : "";
+	const error = node.error ? ` | ${previewDisplayText(node.error, 240)}` : "";
+	return `stage ${index + 1}/${total}: ${id}${display}${agent} | ${state}${error}`;
+}
+
 export function formatAsyncRunOutputPath(run: Pick<AsyncRunSummary, "asyncDir" | "outputFile">): string | undefined {
 	if (!run.outputFile) return undefined;
 	return path.isAbsolute(run.outputFile) ? run.outputFile : path.join(run.asyncDir, run.outputFile);
 }
 
-export function formatAsyncRunProgressLabel(run: Pick<AsyncRunSummary, "mode" | "state" | "currentStep" | "chainStepCount" | "parallelGroups" | "steps">): string {
+export function formatAsyncRunProgressLabel(run: Pick<AsyncRunSummary, "mode" | "state" | "currentStep" | "chainStepCount" | "parallelGroups" | "steps"> & { workflowGraph?: WorkflowGraphSnapshot }): string {
+	const graphStages = run.mode === "workflow" ? workflowGraphStageNodes(run.workflowGraph) : [];
+	if (graphStages.length > 0) {
+		const currentNode = graphStages.find((node) => node.id === run.workflowGraph?.currentNodeId);
+		if (currentNode && currentNode.status !== "completed") return `stage ${graphStages.indexOf(currentNode) + 1}/${graphStages.length}`;
+		const activeNode = graphStages.find((node) => node.status === "running") ?? graphStages.find((node) => node.status !== "completed");
+		if (activeNode) return `stage ${graphStages.indexOf(activeNode) + 1}/${graphStages.length}`;
+		return `stage ${graphStages.length}/${graphStages.length}`;
+	}
 	const stepCount = run.steps.length || 1;
 	const chainStepCount = run.chainStepCount ?? stepCount;
 	const groups = normalizeParallelGroups(run.parallelGroups, run.steps.length, chainStepCount);
@@ -622,8 +659,14 @@ export function formatAsyncRunList(runs: AsyncRunSummary[], heading = "Active as
 		if (preflightWarning) lines.push(preflightWarning);
 		for (const step of run.steps) {
 			lines.push(`  ${formatStepLine(step)}`);
+			lines.push(...formatTimeoutRecoveryLines(step.timeoutRecovery, "    "));
 			lines.push(...formatNestedRunStatusLines(step.children, { indent: "    ", maxLines: 12 }));
 		}
+		const loadedWorkflowKeys = new Set(run.steps.flatMap((step) => step.workflowKey ? [step.workflowKey] : []));
+		const graphStages = run.mode === "workflow" ? workflowGraphStageNodes(run.workflowGraph) : [];
+		for (const [index, node] of graphStages.entries()) {
+			if (!loadedWorkflowKeys.has(node.id)) lines.push(`  ${formatWorkflowStageLine(node, index, graphStages.length)}`);
+		}
 		for (const row of projectAsyncWorkflowRows([], run.hostSteps)) {
 			const line = formatHostStepLine(row);
 			if (line) lines.push(`  ${line}`);

package/dist/extensions/pi-subagents/src/runs/background/control-channel.ts

@@ -1,8 +1,9 @@
 /**
  * Cross-OS control channel for async subagent runs.
  *
- * Background runs are detached OS processes. The original control path delivered
- * an interrupt with `process.kill(pid, SIGUSR2|SIGBREAK)`, but Windows cannot
+ * Background runs use child processes. Unix detaches them from the parent process.
+ * The original control path delivered an interrupt with
+ * `process.kill(pid, SIGUSR2|SIGBREAK)`, but Windows cannot
  * deliver those signals cross-process via `process.kill` and throws `ENOSYS`,
  * which left async runs uninterruptible (no stop, no live steer) on Windows.
  *

package/dist/extensions/pi-subagents/src/runs/background/run-status.ts

@@ -2,7 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import { safeTerminalText } from "../../shared/display-text.ts";
-import { formatAsyncRunList, formatAsyncRunOutputPath, formatAsyncRunProgressLabel, listAsyncRuns } from "./async-status.ts";
+import { formatAsyncRunList, formatAsyncRunOutputPath, formatAsyncRunProgressLabel, formatWorkflowStageLine, listAsyncRuns } from "./async-status.ts";
 import { formatAsyncResultTranscript, formatAsyncRunTranscript, formatNestedRunTranscript, inspectSubagentFleet } from "./fleet-view.ts";
 import { formatNestedRunStatusLines } from "../shared/nested-render.ts";
 import { formatModelThinking } from "../../shared/formatters.ts";
@@ -25,7 +25,9 @@ import { formatWorkflowJsonPreview } from "../../workflows/scripted-workflow.ts"
 import { parseWorkflowChildSummary } from "../../workflows/workflow-child-summary.ts";
 import { formatWorkflowPreflightPlanSummary, formatWorkflowPreflightWarningSummary } from "../../workflows/workflow-preflight.ts";
 import { formatRunFanoutBudget, getRunFanoutBudgetSnapshot, readRunFanoutBudgetDescriptor } from "../shared/run-fanout-budget.ts";
+import { workflowGraphStageNodes } from "../shared/workflow-graph.ts";
 import { getExternalJobProvider } from "../../api/external-job-provider.ts";
+import { formatTimeoutRecoveryLines } from "../shared/mutation-evidence.ts";
 
 interface RunStatusParams {
 	action?: string;
@@ -481,6 +483,7 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 				currentStep: status.currentStep,
 				chainStepCount: status.chainStepCount,
 				parallelGroups: status.parallelGroups,
+				workflowGraph: status.workflowGraph,
 				steps: (status.steps ?? []).map((step, index) => ({ index, agent: step.agent, status: step.status })),
 			});
 			const started = new Date(status.startedAt).toISOString();
@@ -548,6 +551,7 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 				const display = runStatusStepDisplayName(step);
 				const phase = step.phase ? `[${step.phase}] ` : "";
 				lines.push(`${stepLineLabel(status, index)}: ${phase}${display} ${step.status}${modelText}${stepActivityText ? `, ${stepActivityText}` : ""}${steeringSuffix}${acceptanceText}${budgetText}${errorText}`);
+				lines.push(...formatTimeoutRecoveryLines(step.timeoutRecovery, "  "));
 				if (step.runner?.type === "external-cli") {
 					const runner = normalizeExternalCliRunnerStatus(step.runner);
 					if (runner) {
@@ -593,6 +597,11 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 					lines.push("  Steer: unavailable; external runners do not accept live messages.");
 				}
 			}
+			const loadedWorkflowKeys = new Set((status.steps ?? []).flatMap((step) => step.workflowKey ? [step.workflowKey] : []));
+			const graphStages = status.mode === "workflow" ? workflowGraphStageNodes(status.workflowGraph) : [];
+			for (const [index, node] of graphStages.entries()) {
+				if (!loadedWorkflowKeys.has(node.id)) lines.push(`  ${formatWorkflowStageLine(node, index, graphStages.length)}`);
+			}
 			const attached = new Set((status.steps ?? []).flatMap((step) => step.children?.map((child) => child.id) ?? []));
 			const unattached = nestedChildren.filter((child) => !attached.has(child.id));
 			lines.push(...formatNestedRunStatusLines(unattached, { indent: "", commandHints: true, maxLines: 20 }));
@@ -632,7 +641,7 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 		}
 		try {
 			const raw = fs.readFileSync(resultPath, "utf-8");
-			const data = JSON.parse(raw) as { id?: string; runId?: string; toolCallId?: string; agent?: string; success?: boolean; summary?: string; output?: string; exitCode?: number; state?: string; stopped?: boolean; timedOut?: boolean; turnBudgetExceeded?: boolean; processSignal?: string | null; sessionFile?: string; parallelHandoff?: { path?: string }; results?: Array<{ agent?: string; sessionName?: string; runId?: string; workflowKey?: string; output?: string; summary?: string; sessionFile?: string; state?: string; success?: boolean; exitCode?: number | null; stopped?: boolean; timedOut?: boolean; turnBudgetExceeded?: boolean; interrupted?: boolean; processSignal?: string | null }> };
+			const data = JSON.parse(raw) as { id?: string; runId?: string; toolCallId?: string; agent?: string; success?: boolean; summary?: string; output?: string; exitCode?: number; state?: string; stopped?: boolean; timedOut?: boolean; turnBudgetExceeded?: boolean; processSignal?: string | null; sessionFile?: string; timeoutRecovery?: unknown; parallelHandoff?: { path?: string }; results?: Array<{ agent?: string; sessionName?: string; runId?: string; workflowKey?: string; output?: string; summary?: string; sessionFile?: string; state?: string; success?: boolean; exitCode?: number | null; stopped?: boolean; timedOut?: boolean; turnBudgetExceeded?: boolean; interrupted?: boolean; processSignal?: string | null; timeoutRecovery?: unknown }> };
 			if (params.view === "transcript") {
 				try {
 					return { content: [{ type: "text", text: formatAsyncResultTranscript(data, resultPath, { index: params.index, lines: params.lines }) }], details: { mode: "single", results: [] } };
@@ -660,6 +669,8 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 			const lines = [`Run: ${runId}`, data.toolCallId ? `Tool call: ${data.toolCallId}` : undefined, `State: ${status}`, `Result: ${resultPath}`].filter((line): line is string => Boolean(line));
 			if (data.parallelHandoff?.path) lines.push(`Parallel handoff: ${data.parallelHandoff.path}`);
 			const children = Array.isArray(data.results) ? data.results : data.agent ? [{ agent: data.agent, sessionFile: data.sessionFile }] : [];
+			lines.push(...formatTimeoutRecoveryLines(data.timeoutRecovery, "  "));
+			for (const child of children) lines.push(...formatTimeoutRecoveryLines(child.timeoutRecovery, "  "));
 			lines.push(formatResumeGuidance(runId, children, data.sessionFile, { stopped: status === "stopped" }));
 			if (data.summary) lines.push("", data.summary);
 			const workflowChildren = parseWorkflowChildSummary((data as unknown as Record<string, unknown>).workflowChildren);

package/dist/extensions/pi-subagents/src/runs/background/subagent-runner.ts

@@ -75,7 +75,7 @@ import {
 	DEFAULT_GLOBAL_CONCURRENCY_LIMIT,
 	Semaphore,
 } from "../shared/parallel-utils.ts";
-import { applyThinkingSuffix, buildPiArgs, cleanupTempDir, projectLaunchResolvedChildExtensions, resolvePiLaunchToolPlan, type SubagentTaskDelivery } from "../shared/pi-args.ts";
+import { applyThinkingSuffix, buildPiArgs, cleanupTempDir, deriveForkPromptCacheKey, projectLaunchResolvedChildExtensions, resolvePiLaunchToolPlan, type SubagentTaskDelivery } from "../shared/pi-args.ts";
 import { deriveChildSessionName } from "../../shared/child-session-name.ts";
 import { readRuntimeAcknowledgedExtensions } from "../shared/runtime-acknowledged-extensions.ts";
 import { outputEntryFromAsyncResult, resolveOutputReferences } from "../shared/chain-outputs.ts";
@@ -1641,6 +1641,7 @@ async function runSingleStepInner(
 	let writerAttemptCount = 0;
 	const attemptNotes: string[] = [];
 	const eventsPath = path.join(path.dirname(ctx.outputFile), "events.jsonl");
+	let finalRequiredOutputMissing: boolean | undefined;
 	let finalResult: RunPiStreamingResult | undefined;
 	let finalOutputSnapshot: SingleOutputSnapshot | undefined;
 	let structuredAcceptanceReport: unknown;
@@ -1698,6 +1699,7 @@ async function runSingleStepInner(
 			: undefined;
 		const { args, env, tempDir, toolDiagnosticPath, runtimeAcknowledgedExtensionsPath, capabilityAudit: attemptCapabilityAudit, warnings } = buildPiArgs(omitUndefinedProperties({
 			parentSessionId: step.parentSessionId,
+			forkCacheKey: step.context === "fork" ? deriveForkPromptCacheKey(step.parentSessionId) : undefined,
 			baseArgs: ["--mode", "json", "-p"],
 			task: attemptTask,
 			taskDelivery: taskDeliveryOverride,
@@ -1930,6 +1932,7 @@ async function runSingleStepInner(
 				? { kind: "structured" as const, path: effectiveStructuredOutput.outputPath, missing: !fs.existsSync(effectiveStructuredOutput.outputPath) }
 			: undefined;
 		const missingRequiredOutputError = formatRequiredOutputError(requiredOutput);
+		finalRequiredOutputMissing = requiredOutput?.missing;
 		const missingRequiredOutputAfterMutation = Boolean(missingRequiredOutputError) && (mutationAttemptObserved || Boolean(mutationEvidence.changedFiles.length));
 		const effectiveExitCode = toolAvailabilityError || completionEvidence.legacyFailureError || midToolExitError || structuredError || emptyOutputError || missingRequiredOutputError
 			? 1
@@ -2117,6 +2120,7 @@ async function runSingleStepInner(
 		? buildTimeoutRecoverySummary({
 			termination: "timed-out",
 			evidence: finalMutationEvidence,
+			requiredOutputMissing: finalRequiredOutputMissing,
 			currentTool: finalResult?.currentTool,
 			currentToolArgs: finalResult?.currentToolArgs,
 			currentPath: finalResult?.currentPath,

package/dist/extensions/pi-subagents/src/runs/background/subagent-wait.ts

@@ -62,6 +62,7 @@ import {
 	type WaitCompletion,
 } from "../../shared/types.ts";
 import { formatDuration, shortenPath } from "../../shared/formatters.ts";
+import { formatTimeoutRecoveryLines } from "../shared/mutation-evidence.ts";
 import { toAgentToolUsage } from "../../shared/utils.ts";
 import { collectWaitCompletions } from "./wait-completions.ts";
 import { formatResumeFirstFailedRunsNote } from "./resume-guidance.ts";
@@ -349,6 +350,12 @@ function result(text: string, isError = false, completions?: WaitCompletion[]):
 	};
 }
 
+function formatCompletionRecovery(completions: WaitCompletion[] | undefined): string {
+	const lines = (completions ?? []).flatMap((completion) =>
+		(completion.results ?? []).flatMap((child) => formatTimeoutRecoveryLines(child.timeoutRecovery)));
+	return lines.length > 0 ? `\n${lines.join("\n")}` : "";
+}
+
 function windowElapsedResult(
 	text: string,
 	activeRunIds: string[],
@@ -685,6 +692,7 @@ export async function waitForSubagents(
 		+ providerActive.filter((item) => initialProviderIds.has(backgroundWorkIdentity(item))).length;
 	const elapsed = formatDuration(now() - startedAt);
 	const outcome = terminalSummary ? ` Outcome: ${terminalSummary}.` : "";
+	const recoveryNote = formatCompletionRecovery(completions);
 
 	if (waitForAll) {
 		const scope = params.id
@@ -694,7 +702,7 @@ export async function waitForSubagents(
 				: `${initialAsyncIds.size} async run(s) and ${initialProviderIds.size} provider item(s)`;
 		const status = relevantAttention.length > 0 ? "attention required" : "done";
 		return result(
-			`Waited ${elapsed} for ${scope}; ${status}.${outcome}${resumeGuidance}${attentionNote} Completion/control events have been observed; inspect status if a notification is not visible yet.`,
+			`Waited ${elapsed} for ${scope}; ${status}.${outcome}${recoveryNote}${resumeGuidance}${attentionNote} Completion/control events have been observed; inspect status if a notification is not visible yet.`,
 			(deps.failOnFailedRuns === true && failedAsyncCount > 0) || (deps.failOnAttention === true && relevantAttention.length > 0),
 			completions,
 		);
@@ -711,7 +719,7 @@ export async function waitForSubagents(
 		? `${relevantAttention.length} of ${initialCount} ${subject} need attention`
 		: `${finishedCount} of ${initialCount} ${subject} finished`;
 	return result(
-		`Waited ${elapsed}; ${progress}.${outcome}${resumeGuidance}${attentionNote}${remainder} Relevant completion/control events have been observed; inspect status if a notification is not visible yet.`,
+		`Waited ${elapsed}; ${progress}.${outcome}${recoveryNote}${resumeGuidance}${attentionNote}${remainder} Relevant completion/control events have been observed; inspect status if a notification is not visible yet.`,
 		(deps.failOnFailedRuns === true && failedAsyncCount > 0) || (deps.failOnAttention === true && relevantAttention.length > 0),
 		completions,
 	);