pi-subagents 0.46.0 → 0.47.0

package/src/runs/foreground/subagent-executor.ts

@@ -4,7 +4,7 @@ import * as path from "node:path";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { resolveAgentName, type AgentConfig, type AgentScope } from "../../agents/agents.ts";
-import { getArtifactsDir, getChainRunsDir, getProjectArtifactPackagingWarning } from "../../shared/artifacts.ts";
+import { getArtifactsDir, getChainRunsDir, getProjectArtifactPackagingWarning, getProjectSubagentsDir } from "../../shared/artifacts.ts";
 import { writeAtomicJson } from "../../shared/atomic-json.ts";
 import { ChainClarifyComponent, type ChainClarifyResult } from "./chain-clarify.ts";
 import { resolveEffectiveThinking, toModelInfo, type ModelInfo } from "../../shared/model-info.ts";
@@ -39,6 +39,7 @@ import {
 	isParallelStep,
 	isDynamicParallelStep,
 	resolveChainPath,
+	resolveExistingReadPaths,
 	resolveStepBehavior,
 	suppressProgressForReadOnlyTask,
 	taskDisallowsFileUpdates,
@@ -51,7 +52,7 @@ import {
 	type StepOverrides,
 } from "../../shared/settings.ts";
 import { discoverAvailableSkills, normalizeSkillInput } from "../../agents/skills.ts";
-import { buildAsyncRunnerSteps, executeAsyncChain, executeAsyncSingle, formatAsyncStartedMessage, isAsyncAvailable, workflowAwaitedAsyncResultPath } from "../background/async-execution.ts";
+import { buildAsyncRunnerSteps, DEFAULT_ASYNC_TIMEOUT_MS, executeAsyncChain, executeAsyncSingle, formatAsyncStartedMessage, isAsyncAvailable, workflowAwaitedAsyncResultPath } from "../background/async-execution.ts";
 import { isScheduledRunAction, type ScheduledRunAction } from "../background/scheduled-runs.ts";
 import { enqueueChainAppendRequest, readPendingChainAppendRequests, runnerStepOutputNames } from "../background/chain-append.ts";
 import { ChainOutputValidationError, validateChainOutputBindingsWithContext } from "../shared/chain-outputs.ts";
@@ -84,6 +85,13 @@ import { applySteeringRecoveryAgentConfig, buildRevivedAsyncTask, resolveAsyncRe
 import { deliverCheckpointDecisionRequest, deliverInterruptRequest, readRevivalBriefs, requestAsyncSteer, type SteerDeliveryMode } from "../background/control-channel.ts";
 import { updateSteeringTarget, waitForSteeringAction } from "../background/steering.ts";
 import { steerAsyncRun } from "./async-steering-action.ts";
+import {
+	removeWorkflowForegroundSteeringRoute,
+	resolveWorkflowForegroundSteeringTarget,
+	steerWorkflowForegroundTarget,
+	workflowForegroundSteeringDir,
+	workflowForegroundSteeringLaunchOptions,
+} from "./workflow-foreground-steering.ts";
 import { stopAsyncRun } from "./async-stop-action.ts";
 import { reconcileAsyncRun } from "../background/stale-run-reconciler.ts";
 import { resolveAsyncRootResultPath, waitForImportedAsyncRoot } from "../background/chain-root-attachment.ts";
@@ -403,6 +411,7 @@ function resolveRequestedCwd(runtimeCwd: string, requestedCwd: string | undefine
 function removeForegroundControlIfIdle(state: SubagentState, runId: string): boolean {
 	const control = state.foregroundControls.get(runId);
 	if (control && (!foregroundSchedulingSettled(control) || (control.activeChildren?.size ?? 0) > 0)) return false;
+	if (control) removeWorkflowForegroundSteeringRoute(control);
 	state.foregroundControls.delete(runId);
 	if (state.lastForegroundControlId === runId) state.lastForegroundControlId = null;
 	return true;
@@ -1450,7 +1459,7 @@ async function resumeAsyncRun(input: {
 		inheritProjectContext: recoveryDescriptor.inheritProjectContext,
 		inheritSkills: recoveryDescriptor.inheritSkills,
 		source: "project",
-		filePath: recoveryDescriptor.agentFilePath ?? path.join(recoveryDescriptor.cwd, ".pi-subagents-recovery-agent"),
+		filePath: recoveryDescriptor.agentFilePath ?? path.join(getProjectSubagentsDir(recoveryDescriptor.cwd), "recovery-agent"),
 	} : undefined);
 	if (!agentConfig) {
 		return {
@@ -2096,7 +2105,17 @@ function applySingleAgentLaunchDefaults(params: SubagentParamsLike, agents: Agen
 
 export const DEFAULT_FOREGROUND_TIMEOUT_MS = 30 * 60 * 1000;
 
-function resolveForegroundTimeout(params: SubagentParamsLike, defaultTimeoutMs?: number): { timeoutMs?: number; error?: string } {
+// Async single-agent runs also need a wall-clock backstop: a child whose bash
+// tool blocks forever (e.g. a background process inheriting the terminal with
+// no bash `timeout` arg) would otherwise hang the parent indefinitely with
+// zero signal. Same generous default as foreground; explicit timeoutMs/
+// maxRuntimeMs and agent-level defaultTimeoutMs remain authoritative.
+//
+// Deliberately NOT applied at the workflow level: async scripted workflows
+// stay unbounded as a whole, while each runner child has its own deadline.
+export { DEFAULT_ASYNC_TIMEOUT_MS };
+
+export function resolveForegroundTimeout(params: SubagentParamsLike, defaultTimeoutMs?: number): { timeoutMs?: number; error?: string } {
 	const rawTimeout = params.timeoutMs;
 	const rawMaxRuntime = params.maxRuntimeMs;
 	if (rawTimeout === undefined && rawMaxRuntime === undefined) {
@@ -2115,6 +2134,21 @@ function resolveForegroundTimeout(params: SubagentParamsLike, defaultTimeoutMs?:
 	return timeoutMs === undefined ? {} : { timeoutMs };
 }
 
+/**
+ * Resolve the effective launch timeout for a single-agent run, applying the
+ * async/foreground default when neither the caller nor the agent set one.
+ *
+ * The async default is deliberately applied only to plain single-agent
+ * launches. Composite launches keep their top-level execution unbounded when
+ * no timeout is set; their runner children resolve separate deadlines.
+ * Exported so the executor wiring is directly testable.
+ */
+export function resolveSingleAgentLaunchTimeout(params: SubagentParamsLike, async: boolean): { timeoutMs?: number; error?: string } {
+	const isComposite = (params.chain?.length ?? 0) > 0 || (params.tasks?.length ?? 0) > 0 || params.workflowScript !== undefined;
+	const defaultTimeoutMs = !async ? DEFAULT_FOREGROUND_TIMEOUT_MS : isComposite ? undefined : DEFAULT_ASYNC_TIMEOUT_MS;
+	return resolveForegroundTimeout(params, defaultTimeoutMs);
+}
+
 function resolveToolBudget(
 	raw: unknown,
 	label = "toolBudget",
@@ -3155,6 +3189,7 @@ async function runForegroundParallelTasks(input: ForegroundParallelRunInput): Pr
 		const result = await runSync(input.ctx.cwd, input.agents, task.agent, taskText, compactOptional<Parameters<typeof runSync>[4]>({
 			permissions: input.permissions,
 			parentSessionId: input.ctx.sessionManager.getSessionId() ?? undefined,
+			...workflowForegroundSteeringLaunchOptions(input.foregroundControl, index),
 			context: input.contextPolicy.contextForAgent(task.agent),
 			cwd: taskCwd,
 			signal: input.signal,
@@ -3830,8 +3865,9 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 	// Reads: caller override > agent defaultReads > none. `~`/`~/` expand to home;
 	// absolute paths pass through; relative paths resolve against the child cwd.
 	const reads = readsOverride !== undefined ? readsOverride : agentConfig.defaultReads ?? false;
-	const readsInstruction = Array.isArray(reads) && reads.length > 0
-		? `[Read from: ${reads.map((f) => resolveChainPath(f, effectiveCwd)).join(", ")}]\n\n`
+	const readPaths = Array.isArray(reads) ? resolveExistingReadPaths(reads, effectiveCwd) : [];
+	const readsInstruction = readPaths.length > 0
+		? `[Read from: ${readPaths.join(", ")}]\n\n`
 		: "";
 	task = readsInstruction + task;
 	task = injectSingleOutputInstruction(task, outputPath, agentConfig);
@@ -3875,6 +3911,7 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 		r = await runSync(ctx.cwd, agents, params.agent!, task, compactOptional<Parameters<typeof runSync>[4]>({
 			permissions: deps.config.permissions,
 			parentSessionId: ctx.sessionManager.getSessionId() ?? undefined,
+			...workflowForegroundSteeringLaunchOptions(foregroundControl, 0),
 			context: data.contextPolicy.contextForAgent(params.agent!),
 			cwd: effectiveCwd,
 			signal,
@@ -4483,10 +4520,24 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 				void Promise.resolve().then(async () => {
 					const workflowResults: SingleResult[] = [];
 					const { action: _action, agent: _agent, task: _task, resume: _resume, tasks: _tasks, chain: _chain, concurrency: _concurrency, foregroundOnly: _foregroundOnly, clarify: _clarify, timeoutMs: _timeoutMs, maxRuntimeMs: _maxRuntimeMs, usageBudget: _usageBudget, missionId: _missionId, mission: _mission, ...workflowChildDefaults } = workflowRequest;
+					const workflowSteps = new Map<string, NonNullable<AsyncStatus["steps"]>[number]>();
+					let projectedTraceLength = 0;
+					let projectedTraceTail: NonNullable<Details["workflow"]>["trace"][number] | undefined;
 					const updateTrace = (trace: NonNullable<Details["workflow"]>["trace"]) => {
 						status.workflow = { ...(status.workflow ?? { emits: [], console: [] }), trace };
-						for (const entry of trace.filter((candidate) => candidate.operation === "run")) {
-							const existing = status.steps?.find((step) => step.workflowKey === entry.key);
+						const rebuild = trace.length < projectedTraceLength
+							|| (projectedTraceLength > 0 && trace[projectedTraceLength - 1] !== projectedTraceTail);
+						if (rebuild) {
+							workflowSteps.clear();
+							for (const step of status.steps ?? []) {
+								if (step.workflowKey) workflowSteps.set(step.workflowKey, step);
+							}
+							projectedTraceLength = 0;
+						}
+						for (let index = projectedTraceLength; index < trace.length; index += 1) {
+							const entry = trace[index]!;
+							if (entry.operation !== "run") continue;
+							const existing = workflowSteps.get(entry.key);
 							if (entry.state === "reused" && existing) continue;
 							const mapped = entry.state === "started" || entry.state === "reused" ? "running" : entry.state === "completed" ? "completed" : "failed";
 							if (existing) {
@@ -4497,9 +4548,13 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 								if (entry.durationMs === undefined) delete existing.durationMs;
 								else existing.durationMs = entry.durationMs;
 							} else {
-								status.steps?.push({ agent: entry.agent ?? entry.key, label: entry.key, workflowKey: entry.key, parentWorkflowRunId: workflowRunId, status: mapped, startedAt: Date.now() });
+								const step: NonNullable<AsyncStatus["steps"]>[number] = { agent: entry.agent ?? entry.key, label: entry.key, workflowKey: entry.key, parentWorkflowRunId: workflowRunId, status: mapped, startedAt: Date.now() };
+								status.steps?.push(step);
+								workflowSteps.set(entry.key, step);
 							}
 						}
+						projectedTraceLength = trace.length;
+						projectedTraceTail = trace.at(-1);
 						projectWorkflowActivity();
 						persist();
 						appendWorkflowEvent({ type: "subagent.workflow.trace", trace });
@@ -5089,6 +5144,12 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 					try {
 						const location = resolveAsyncRunLocation(paramsWithResolvedCwd, DIRS.async, DIRS.results);
 						const runId = location.resolvedId ?? targetRunId ?? path.basename(location.asyncDir ?? paramsWithResolvedCwd.dir);
+						const directoryStatus = location.asyncDir ? readStatus(location.asyncDir) : null;
+						if (directoryStatus?.mode === "workflow") {
+							const route = resolveWorkflowForegroundSteeringTarget({ state: deps.state, workflowRunId: directoryStatus.runId || runId, asyncDirRoot: DIRS.async });
+							if (!route.ok) return { content: [{ type: "text", text: route.message }], isError: true, details: { mode: "management", results: [] } };
+							return steerWorkflowForegroundTarget({ target: route.target, message, mode: paramsWithResolvedCwd.mode, index: paramsWithResolvedCwd.index, signal });
+						}
 						if (location.asyncDir) {
 							const unsupported = externalRunnerControlError(location.asyncDir, "steer");
 							if (unsupported) return unsupported;
@@ -5124,8 +5185,18 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 					return { content: [{ type: "text", text }], isError: true, details: { mode: "management", results: [] } };
 				}
 				if (resolved?.kind === "nested") return steerNestedRun(omitUndefinedProperties({ target: resolved, message, mode: paramsWithResolvedCwd.mode, index: paramsWithResolvedCwd.index, signal }));
-				if (resolved?.kind === "foreground") return { content: [{ type: "text", text: "action='steer' currently supports live async Pi child sessions only; use action='interrupt' or action='resume' for foreground runs." }], isError: true, details: { mode: "management", results: [] } };
+				if (resolved?.kind === "foreground") {
+					const route = resolveWorkflowForegroundSteeringTarget({ state: deps.state, childRunId: resolved.id, asyncDirRoot: DIRS.async });
+					if (!route.ok) return { content: [{ type: "text", text: route.message }], isError: true, details: { mode: "management", results: [] } };
+					return steerWorkflowForegroundTarget({ target: route.target, message, mode: paramsWithResolvedCwd.mode, index: paramsWithResolvedCwd.index, signal });
+				}
 				if (resolved?.kind !== "async") return { content: [{ type: "text", text: `No async run found for '${targetRunId}'.` }], isError: true, details: { mode: "management", results: [] } };
+				const resolvedStatus = resolved.location.asyncDir ? readStatus(resolved.location.asyncDir) : null;
+				if (resolvedStatus?.mode === "workflow") {
+					const route = resolveWorkflowForegroundSteeringTarget({ state: deps.state, workflowRunId: resolvedStatus.runId || resolved.id, asyncDirRoot: DIRS.async });
+					if (!route.ok) return { content: [{ type: "text", text: route.message }], isError: true, details: { mode: "management", results: [] } };
+					return steerWorkflowForegroundTarget({ target: route.target, message, mode: paramsWithResolvedCwd.mode, index: paramsWithResolvedCwd.index, signal });
+				}
 				if (resolved.location.asyncDir) {
 					const unsupported = externalRunnerControlError(resolved.location.asyncDir, "steer");
 					if (unsupported) return unsupported;
@@ -5432,9 +5503,9 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 		if (externalAgent && (!effectiveAsync || effectiveParams.foregroundOnly === true)) {
 			return buildRequestedModeError(effectiveParams, `Agent '${externalAgent.name}' uses runner.type='external-cli', which currently supports async/background execution only. Omit async or pass async:true; clarify and foregroundOnly are unsupported.`);
 		}
-		const foregroundTimeout = resolveForegroundTimeout(
+		const foregroundTimeout = resolveSingleAgentLaunchTimeout(
 			effectiveParams,
-			effectiveAsync ? undefined : DEFAULT_FOREGROUND_TIMEOUT_MS,
+			effectiveAsync,
 		);
 		if (foregroundTimeout.error) return buildRequestedModeError(effectiveParams, foregroundTimeout.error);
 		const controlConfig = resolveControlConfig(deps.config.control, effectiveParams.control);
@@ -5584,6 +5655,17 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 		const foregroundDescription = effectiveParams.task?.trim()
 			|| effectiveParams.tasks?.[0]?.task?.trim()
 			|| (effectiveParams.chain ? firstRawChainTask(effectiveParams.chain)?.trim() : undefined);
+		const parentWorkflowStatus = effectiveParams.workflowParentRunId
+			? readStatus(path.join(DIRS.async, effectiveParams.workflowParentRunId))
+			: null;
+		const workflowSteeringDir = effectiveParams.workflowParentRunId
+			&& requestSessionId
+			&& deps.state.workflowControllers?.has(effectiveParams.workflowParentRunId)
+			&& parentWorkflowStatus?.mode === "workflow"
+			&& (parentWorkflowStatus.state === "running" || parentWorkflowStatus.state === "queued")
+			&& parentWorkflowStatus.sessionId === requestSessionId
+			? workflowForegroundSteeringDir(DIRS.async, effectiveParams.workflowParentRunId, runId)
+			: undefined;
 		const foregroundControl: ForegroundRunControl | undefined = effectiveAsync
 			? undefined
 			: compactOptional<ForegroundRunControl>({
@@ -5592,6 +5674,7 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 				mode: foregroundMode,
 				...(effectiveParams.workflowParentRunId ? { parentWorkflowRunId: effectiveParams.workflowParentRunId } : {}),
 				...(effectiveParams.workflowKey ? { workflowKey: effectiveParams.workflowKey } : {}),
+				workflowSteeringDir,
 				startedAt: Date.now(),
 				updatedAt: Date.now(),
 				cwd: effectiveCwd,

package/src/runs/foreground/workflow-foreground-steering.ts

@@ -0,0 +1,187 @@
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { Details, ForegroundRunControl, SubagentState } from "../../shared/types.ts";
+import { readStatus } from "../../shared/utils.ts";
+import {
+	consumeSteerAckFromDir,
+	readSteerCapability,
+	steerAcksDir,
+	steerCapabilityPath,
+	stepSteerInboxDir,
+	writeSteerRequestToExistingDir,
+	type SteerDeliveryMode,
+	type SteerRequest,
+} from "../background/control-channel.ts";
+
+export interface WorkflowForegroundSteeringTarget {
+	control: ForegroundRunControl;
+	workflowRunId: string;
+	sourceRunId: string;
+}
+
+export type WorkflowForegroundSteeringResolution =
+	| { ok: true; target: WorkflowForegroundSteeringTarget }
+	| { ok: false; message: string };
+
+function activeWorkflowError(state: SubagentState, workflowRunId: string, asyncDirRoot: string): string | undefined {
+	if (!state.currentSessionId) return "Workflow steering requires an active parent session.";
+	if (!state.workflowControllers?.has(workflowRunId)) return `Workflow '${workflowRunId}' has no live foreground child.`;
+	const status = readStatus(path.join(asyncDirRoot, workflowRunId));
+	if (!status || status.mode !== "workflow" || (status.state !== "running" && status.state !== "queued")) {
+		return `Workflow '${workflowRunId}' has no live foreground child.`;
+	}
+	if (status.sessionId !== state.currentSessionId) return `Workflow '${workflowRunId}' was not found in the active session.`;
+	return undefined;
+}
+
+function controlIsLiveInWorkflow(control: ForegroundRunControl, workflowRunId: string, sessionId: string): boolean {
+	return control.parentWorkflowRunId === workflowRunId
+		&& control.sessionId === sessionId
+		&& Boolean(control.workflowSteeringDir)
+		&& (control.activeChildren?.size ?? 0) > 0;
+}
+
+export function resolveWorkflowForegroundSteeringTarget(input: {
+	state: SubagentState;
+	childRunId?: string;
+	workflowRunId?: string;
+	asyncDirRoot: string;
+}): WorkflowForegroundSteeringResolution {
+	const { state, childRunId, asyncDirRoot } = input;
+	if (childRunId) {
+		const control = state.foregroundControls.get(childRunId);
+		if (!control?.parentWorkflowRunId) return { ok: false, message: `Foreground run '${childRunId}' is not a live workflow-owned child.` };
+		const workflowRunId = control.parentWorkflowRunId;
+		const workflowError = activeWorkflowError(state, workflowRunId, asyncDirRoot);
+		if (workflowError) return { ok: false, message: workflowError };
+		if (!controlIsLiveInWorkflow(control, workflowRunId, state.currentSessionId!)) {
+			return { ok: false, message: `Foreground run '${childRunId}' is not a live workflow-owned child in the active session.` };
+		}
+		return { ok: true, target: { control, workflowRunId, sourceRunId: childRunId } };
+	}
+
+	const workflowRunId = input.workflowRunId;
+	if (!workflowRunId) return { ok: false, message: "Workflow steering requires a workflow or child run id." };
+	const workflowError = activeWorkflowError(state, workflowRunId, asyncDirRoot);
+	if (workflowError) return { ok: false, message: workflowError };
+	const controls = [...state.foregroundControls.values()].filter((control) => controlIsLiveInWorkflow(control, workflowRunId, state.currentSessionId!));
+	if (controls.length === 0) return { ok: false, message: `Workflow '${workflowRunId}' has no live foreground child.` };
+	if (controls.length > 1) return { ok: false, message: `Workflow '${workflowRunId}' has ${controls.length} live foreground children; steer a child run id instead.` };
+	return { ok: true, target: { control: controls[0]!, workflowRunId, sourceRunId: workflowRunId } };
+}
+
+function managementError(message: string): AgentToolResult<Details> {
+	return { content: [{ type: "text", text: message }], isError: true, details: { mode: "management", results: [] } };
+}
+
+export async function steerWorkflowForegroundTarget(input: {
+	target: WorkflowForegroundSteeringTarget;
+	message: string;
+	mode?: SteerDeliveryMode;
+	index?: number;
+	signal?: AbortSignal;
+	ackTimeoutMs?: number;
+}): Promise<AgentToolResult<Details>> {
+	const { control, sourceRunId } = input.target;
+	const routeDir = control.workflowSteeringDir;
+	if (!routeDir || !fs.existsSync(routeDir)) return managementError(`Foreground run '${control.runId}' has no live workflow steering route.`);
+	const activeIndexes = [...(control.activeChildren?.keys() ?? [])].sort((left, right) => left - right);
+	const index = input.index ?? (activeIndexes.length === 1 ? activeIndexes[0] : undefined);
+	if (index === undefined) {
+		return managementError(activeIndexes.length === 0
+			? `Foreground run '${control.runId}' has no live child session.`
+			: `Foreground run '${control.runId}' has ${activeIndexes.length} live child sessions; provide index.`);
+	}
+	if (!activeIndexes.includes(index)) return managementError(`Foreground run '${control.runId}' child ${index} is not live.`);
+	const capability = readSteerCapability(routeDir, index);
+	if (capability?.supported === false) return managementError(`Foreground run '${control.runId}' child ${index} does not support steering.`);
+
+	const request: SteerRequest = {
+		type: "steer",
+		id: randomUUID(),
+		ts: Date.now(),
+		message: input.message.trim(),
+		...(input.mode && input.mode !== "steer" ? { mode: input.mode } : {}),
+		targetIndex: index,
+		source: "steer-action",
+	};
+	try {
+		writeSteerRequestToExistingDir(stepSteerInboxDir(routeDir, index), request);
+	} catch (error) {
+		if (typeof error === "object" && error !== null && "code" in error && (error as NodeJS.ErrnoException).code === "ENOENT") {
+			return managementError(`Foreground run '${control.runId}' has no live workflow steering route.`);
+		}
+		return managementError(`Failed to queue steering for foreground run ${control.runId}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+
+	const deadline = Date.now() + (input.ackTimeoutMs ?? 3_000);
+	let ack;
+	let routeRemoved = false;
+	while (Date.now() <= deadline) {
+		ack = consumeSteerAckFromDir(steerAcksDir(routeDir, index), request.id);
+		if (ack || input.signal?.aborted) break;
+		if (!fs.existsSync(routeDir)) {
+			routeRemoved = true;
+			break;
+		}
+		await new Promise<void>((resolve) => setTimeout(resolve, Math.min(50, Math.max(1, deadline - Date.now()))));
+	}
+	if (routeRemoved || (!ack && !input.signal?.aborted && !fs.existsSync(routeDir))) {
+		return managementError(`Foreground run '${control.runId}' has no live child session.`);
+	}
+	const target = ack?.state === "delivered"
+		? { index, state: "delivered" as const, deliveredAt: ack.ts }
+		: ack?.state === "queued"
+			? { index, state: "queued" as const }
+			: ack?.state === "failed"
+				? { index, state: "failed" as const, reason: ack.message }
+				: { index, state: "pending" as const };
+	const steering = {
+		requestId: request.id,
+		state: ack?.state === "delivered" ? "delivered" as const : ack?.state === "failed" ? "failed" as const : "pending" as const,
+		deliveryStatus: ack?.state === "delivered" ? "delivered" as const : "queued" as const,
+		sourceRunId,
+		targets: [target],
+	};
+	if (input.signal?.aborted) {
+		return { content: [{ type: "text", text: `Steering pending for foreground run ${control.runId} (request ${request.id}); caller aborted before acknowledgment.` }], details: { mode: "management", results: [], steering } };
+	}
+	if (ack?.state === "delivered") {
+		return { content: [{ type: "text", text: `Steering delivered for foreground run ${control.runId} (request ${request.id}).` }], details: { mode: "management", results: [], steering } };
+	}
+	if (ack?.state === "queued") {
+		return { content: [{ type: "text", text: `Steering queued for foreground run ${control.runId} (request ${request.id}).` }], details: { mode: "management", results: [], steering } };
+	}
+	if (ack?.state === "failed") {
+		return { content: [{ type: "text", text: `Steering failed for foreground run ${control.runId} (request ${request.id}): ${ack.message}` }], isError: true, details: { mode: "management", results: [], steering } };
+	}
+	return { content: [{ type: "text", text: `Steering pending for foreground run ${control.runId} (request ${request.id}); no acknowledgment was received.` }], details: { mode: "management", results: [], steering } };
+}
+
+export function workflowForegroundSteeringDir(asyncDirRoot: string, workflowRunId: string, childRunId: string): string {
+	return path.join(asyncDirRoot, workflowRunId, "control", "workflow-foreground", childRunId);
+}
+
+export function removeWorkflowForegroundSteeringRoute(control: ForegroundRunControl): void {
+	if (!control.workflowSteeringDir) return;
+	try {
+		fs.rmSync(control.workflowSteeringDir, { recursive: true, force: true });
+	} catch (error) {
+		console.warn(`[pi-subagents] Failed to remove workflow foreground steering route '${control.workflowSteeringDir}': ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+
+export function workflowForegroundSteeringLaunchOptions(control: ForegroundRunControl | undefined, index: number): Pick<import("../../shared/types.ts").RunSyncOptions, "steerInboxDir" | "steerCapabilityPath" | "steerAckDir"> {
+	if (!control?.workflowSteeringDir) return {};
+	const steerInboxDir = stepSteerInboxDir(control.workflowSteeringDir, index);
+	const steerAckDir = steerAcksDir(control.workflowSteeringDir, index);
+	fs.mkdirSync(steerInboxDir, { recursive: true });
+	fs.mkdirSync(steerAckDir, { recursive: true });
+	return {
+		steerInboxDir,
+		steerCapabilityPath: steerCapabilityPath(control.workflowSteeringDir, index),
+		steerAckDir,
+	};
+}

package/src/runs/shared/dynamic-fanout.ts

@@ -49,7 +49,7 @@ const DYNAMIC_EXPAND_FROM_KEYS = new Set(["output", "path"]);
 const DYNAMIC_PARALLEL_KEYS = new Set(["agent", "task", "phase", "label", "outputSchema", "cwd", "output", "outputMode", "reads", "progress", "skill", "model", "toolBudget", "acceptance", "agentContract", "gateOn"]);
 const RUNNER_DYNAMIC_PARALLEL_KEYS = new Set([
 	...DYNAMIC_PARALLEL_KEYS,
-	"outputName", "structured", "inheritProjectContext", "inheritSkills", "skills", "outputPath", "namespaceOutputPath", "maxSubagentDepth", "waitToolEnabled",
+	"outputName", "structured", "inheritProjectContext", "inheritSkills", "skills", "outputPath", "namespaceOutputPath", "maxSubagentDepth", "timeoutMs", "waitToolEnabled",
 	"structuredOutput", "structuredOutputSchema", "tools", "extensions", "subagentOnlyExtensions", "mcpDirectTools", "capabilityCeiling", "completionGuard", "systemPrompt",
 	"systemPromptMode", "thinking", "modelCandidates", "sessionFile", "effectiveAcceptance", "acceptanceInput", "acceptanceRole", "parentSessionId", "launchResolvedExtensions",
 ]);

package/src/runs/shared/model-fallback.ts

@@ -191,7 +191,8 @@ function defaultScopeWarn(violation: ModelScopeViolation): void {
  *
  * An explicitly requested model string is resolved via {@link resolveModelCandidate}.
  * When `options.scope.enforce` is on, an out-of-scope resolved model throws for
- * an explicit (`source: "explicit"`) request and warns for an inherited one.
+ * an explicit (`source: "explicit"`) request and warns for an inherited one,
+ * unless strict scope enforcement makes inherited violations hard errors.
  */
 export function resolveSubagentModelOverride(
 	requestedModel: string | boolean | undefined,
@@ -245,7 +246,7 @@ export function resolveEffectiveSubagentModel(
 }
 
 export interface BuildModelCandidatesOptions {
-	/** Fallback models are inherited agent config and warn, rather than error, when out of scope. */
+	/** Fallback models warn by default and throw when strict scope enforcement is enabled. */
 	scope?: ModelScopeConfig;
 	onWarn?: (violation: ModelScopeViolation) => void;
 }
@@ -265,9 +266,12 @@ export function buildModelCandidates(
 		if (!raw) continue;
 		const normalized = resolveModelCandidate(raw.trim(), availableModels, preferredProvider);
 		if (!normalized || seen.has(normalized)) continue;
-		if (index > 0 && options?.scope?.enforce) {
+		if ((index > 0 || options?.scope?.strict === true) && options?.scope?.enforce) {
 			const violation = checkModelScope(normalized, options.scope, "inherited");
-			if (violation) (options.onWarn ?? defaultScopeWarn)(violation);
+			if (violation) {
+				if (violation.severity === "error") throw new Error(violation.message);
+				(options.onWarn ?? defaultScopeWarn)(violation);
+			}
 		}
 		seen.add(normalized);
 		candidates.push(normalized);

package/src/runs/shared/model-scope.ts

@@ -6,7 +6,8 @@
  * where the model came from: an explicit caller-supplied model (`--model`,
  * tool-call `model`, or a TUI clarify pick) is a hard error, while a model
  * inherited from agent frontmatter / `defaultModel` / the parent session only
- * emits a warning so existing configurations keep working.
+ * emits a warning so existing configurations keep working. Optional strict
+ * enforcement makes inherited models hard errors too.
  *
  * The decision logic ({@link checkModelScope}) is a pure function of its
  * inputs so it can be unit-tested without touching the filesystem or config.
@@ -16,6 +17,8 @@ import { splitKnownThinkingSuffix } from "../../shared/model-info.ts";
 
 export interface ModelScopeConfig {
 	enforce?: boolean;
+	/** Reject inherited and fallback models outside the allowlist instead of warning. */
+	strict?: boolean;
 	/** Glob-style allow patterns (only `*` is special), matched against `provider/id`. */
 	allow?: string[];
 }
@@ -67,7 +70,7 @@ export function checkModelScope(
 	if (allow.some((pattern) => matchesScopePattern(model, pattern))) return undefined;
 
 	const baseModel = stripThinkingSuffix(model);
-	const severity: ModelScopeViolation["severity"] = source === "explicit" ? "error" : "warn";
+	const severity: ModelScopeViolation["severity"] = source === "explicit" || scope.strict === true ? "error" : "warn";
 	return {
 		model: baseModel,
 		severity,
@@ -102,6 +105,13 @@ export function parseModelScopeConfig(
 		config.enforce = input.enforce;
 	}
 
+	if ("strict" in input) {
+		if (typeof input.strict !== "boolean") {
+			throw new Error(`Subagent settings in '${meta.filePath}' have invalid 'modelScope.strict'; expected a boolean.`);
+		}
+		config.strict = input.strict;
+	}
+
 	if ("allow" in input) {
 		if (!Array.isArray(input.allow)) {
 			throw new Error(`Subagent settings in '${meta.filePath}' have invalid 'modelScope.allow'; expected an array of strings.`);

package/src/runs/shared/parallel-utils.ts

@@ -40,6 +40,7 @@ export interface RunnerSubagentStep {
 	outputMode?: "inline" | "file-only";
 	sessionFile?: string;
 	maxSubagentDepth?: number;
+	timeoutMs?: number;
 	waitToolEnabled?: boolean;
 	structuredOutput?: {
 		schema: import("../../shared/types.ts").JsonSchemaObject;

package/src/runs/shared/worktree.ts

@@ -3,6 +3,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { resolveAuthorityDecision, type AuthorityPolicyConfig } from "../../policy/authority.ts";
+import { PROJECT_SUBAGENTS_RELATIVE_DIR } from "../../shared/artifacts.ts";
 
 export interface WorktreeSetup {
 	cwd: string;
@@ -135,9 +136,9 @@ function resolveRepoState(cwd: string): RepoState {
 	const cwdRelative = resolveRepoCwdRelative(cwd);
 	const toplevel = runGitChecked(cwd, ["rev-parse", "--show-toplevel"]).trim();
 
-	// pi-subagents writes durable runtime state under .pi-subagents/ by default;
+	// pi-subagents writes durable runtime state under .pi/subagents/ by default;
 	// that state must not make managed isolation unusable for later runs.
-	const status = runGitChecked(toplevel, ["status", "--porcelain", "--", ":!.pi-subagents"]);
+	const status = runGitChecked(toplevel, ["status", "--porcelain", "--", `:!${PROJECT_SUBAGENTS_RELATIVE_DIR}`]);
 	if (status.trim().length > 0) {
 		throw new Error("worktree isolation requires a clean git working tree. Commit or stash changes first.");
 	}

package/src/shared/artifacts.ts

@@ -3,19 +3,19 @@ import * as path from "node:path";
 import { CHAIN_RUNS_DIR, TEMP_ARTIFACTS_DIR, type ArtifactPaths, type ArtifactDirPreference } from "./types.ts";
 import { getAgentDir } from "./utils.ts";
 const CLEANUP_MARKER_FILE = ".last-cleanup";
-const PROJECT_ARTIFACT_ROOT = ".pi-subagents";
+export const PROJECT_SUBAGENTS_RELATIVE_DIR = ".pi/subagents";
 
 const PROJECT_ARTIFACT_PATHS = [
-	`${PROJECT_ARTIFACT_ROOT}/artifacts/output.md`,
-	`${PROJECT_ARTIFACT_ROOT}/artifacts/run_worker_input.md`,
-	`${PROJECT_ARTIFACT_ROOT}/artifacts/run_worker_output.md`,
-	`${PROJECT_ARTIFACT_ROOT}/artifacts/run_worker.jsonl`,
-	`${PROJECT_ARTIFACT_ROOT}/artifacts/run_worker_transcript.jsonl`,
-	`${PROJECT_ARTIFACT_ROOT}/artifacts/run_worker_meta.json`,
-	`${PROJECT_ARTIFACT_ROOT}/artifacts/progress/run/progress.md`,
-	`${PROJECT_ARTIFACT_ROOT}/artifacts/outputs/output.md`,
-	`${PROJECT_ARTIFACT_ROOT}/artifacts/outputs/run/output.md`,
-	`${PROJECT_ARTIFACT_ROOT}/chain-runs/run.json`,
+	`${PROJECT_SUBAGENTS_RELATIVE_DIR}/artifacts/output.md`,
+	`${PROJECT_SUBAGENTS_RELATIVE_DIR}/artifacts/run_worker_input.md`,
+	`${PROJECT_SUBAGENTS_RELATIVE_DIR}/artifacts/run_worker_output.md`,
+	`${PROJECT_SUBAGENTS_RELATIVE_DIR}/artifacts/run_worker.jsonl`,
+	`${PROJECT_SUBAGENTS_RELATIVE_DIR}/artifacts/run_worker_transcript.jsonl`,
+	`${PROJECT_SUBAGENTS_RELATIVE_DIR}/artifacts/run_worker_meta.json`,
+	`${PROJECT_SUBAGENTS_RELATIVE_DIR}/artifacts/progress/run/progress.md`,
+	`${PROJECT_SUBAGENTS_RELATIVE_DIR}/artifacts/outputs/output.md`,
+	`${PROJECT_SUBAGENTS_RELATIVE_DIR}/artifacts/outputs/run/output.md`,
+	`${PROJECT_SUBAGENTS_RELATIVE_DIR}/chain-runs/run.json`,
 ];
 
 function globMatchesPath(pattern: string, filePath: string): boolean {
@@ -59,7 +59,7 @@ function normalizePattern(pattern: string): string {
 
 function patternMatchesArtifactPath(pattern: string, artifactPath: string): boolean {
 	const normalized = normalizePattern(pattern);
-	return normalized === PROJECT_ARTIFACT_ROOT
+	return normalized === PROJECT_SUBAGENTS_RELATIVE_DIR
 		|| normalized === "*"
 		|| artifactPath.startsWith(`${normalized}/`)
 		|| globMatchesPath(normalized, artifactPath);
@@ -127,11 +127,11 @@ export function getProjectArtifactPackagingWarning(cwd: string): string | undefi
 	const ignorePath = fs.existsSync(npmIgnorePath) ? npmIgnorePath : path.join(cwd, ".gitignore");
 	if (filesIncludeArtifacts === undefined && ignoreFileExcludesProjectArtifacts(ignorePath)) return undefined;
 
-	return "Project-scoped subagent artifacts can be included when this package is published. Add '.pi-subagents/' to .npmignore, restrict package.json files, or set artifactDir to 'session' or 'temp'.";
+	return "Project-scoped subagent artifacts can be included when this package is published. Add '.pi/subagents/' to .npmignore, restrict package.json files, or set artifactDir to 'session' or 'temp'.";
 }
 
 export function getProjectSubagentsDir(cwd: string): string {
-	return path.join(cwd, PROJECT_ARTIFACT_ROOT);
+	return path.join(cwd, PROJECT_SUBAGENTS_RELATIVE_DIR);
 }
 
 export function getProjectArtifactsDir(cwd: string): string {