pi-subagents 0.47.1 → 0.48.0

package/src/runs/shared/run-fanout-budget.ts

@@ -0,0 +1,280 @@
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS, waitForFileSystemRetry } from "../../shared/file-system-retry.ts";
+import {
+	TEMP_ROOT_DIR,
+	type RunFanoutBudgetDescriptor,
+	type RunFanoutBudgetSnapshot,
+	type RunFanoutRejection,
+} from "../../shared/types.ts";
+
+export const RUN_FANOUT_BUDGET_ENV = "PI_SUBAGENT_RUN_FANOUT_BUDGET";
+const RUN_FANOUT_ROOT = path.join(TEMP_ROOT_DIR, "run-fanout-budgets");
+
+interface ManifestV1 {
+	version: 1;
+	rootRunId: string;
+	limit: number;
+	createdAt: number;
+}
+
+interface ClaimV1 {
+	version: 1;
+	claimId: string;
+	path: string;
+	claimedAt: number;
+}
+
+export class RunFanoutLimitError extends Error {
+	readonly rejection: RunFanoutRejection;
+	readonly snapshot: RunFanoutBudgetSnapshot;
+
+	constructor(rejection: RunFanoutRejection) {
+		super(formatRunFanoutRejection(rejection));
+		this.name = "RunFanoutLimitError";
+		this.rejection = rejection;
+		this.snapshot = { used: rejection.used, limit: rejection.limit, remaining: rejection.remaining };
+	}
+}
+
+function safeRootRunId(rootRunId: string): string {
+	return rootRunId.replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 120) || randomUUID();
+}
+
+function parseManifest(value: unknown): ManifestV1 | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const manifest = value as Partial<ManifestV1>;
+	if (manifest.version !== 1 || typeof manifest.rootRunId !== "string" || !manifest.rootRunId
+		|| !Number.isInteger(manifest.limit) || (manifest.limit ?? 0) <= 0
+		|| typeof manifest.createdAt !== "number" || !Number.isFinite(manifest.createdAt)) return undefined;
+	return manifest as ManifestV1;
+}
+
+function readManifest(directory: string): ManifestV1 {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(fs.readFileSync(path.join(directory, "manifest.json"), "utf-8"));
+	} catch (error) {
+		throw new Error(`Run fan-out budget manifest is unreadable at '${directory}': ${error instanceof Error ? error.message : String(error)}`);
+	}
+	const manifest = parseManifest(parsed);
+	if (!manifest) throw new Error(`Run fan-out budget manifest is invalid at '${directory}'.`);
+	return manifest;
+}
+
+function validateDirectory(directory: string): string {
+	let realDirectory: string;
+	let realRoot: string;
+	try {
+		realDirectory = fs.realpathSync(path.resolve(directory));
+		realRoot = fs.realpathSync(path.resolve(RUN_FANOUT_ROOT));
+	} catch (error) {
+		throw new Error(`Run fan-out budget directory is unavailable: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (realDirectory !== realRoot && !realDirectory.startsWith(`${realRoot}${path.sep}`)) {
+		throw new Error("Run fan-out budget directory resolves outside the managed budget root.");
+	}
+	return realDirectory;
+}
+
+export function createRunFanoutBudget(rootRunId: string, limit: number): RunFanoutBudgetDescriptor {
+	if (!Number.isInteger(limit) || limit <= 0) throw new Error("Run fan-out limit must be a positive integer.");
+	fs.mkdirSync(RUN_FANOUT_ROOT, { recursive: true, mode: 0o700 });
+	let directory: string;
+	do directory = path.join(RUN_FANOUT_ROOT, `${safeRootRunId(rootRunId)}-${randomUUID()}`);
+	while (fs.existsSync(directory));
+	fs.mkdirSync(path.join(directory, "claims"), { recursive: true, mode: 0o700 });
+	const manifest: ManifestV1 = { version: 1, rootRunId, limit, createdAt: Date.now() };
+	fs.writeFileSync(path.join(directory, "manifest.json"), `${JSON.stringify(manifest)}\n`, { mode: 0o600, flag: "wx" });
+	return { version: 1, rootRunId, directory, limit };
+}
+
+export function validateRunFanoutBudgetDescriptor(value: unknown): RunFanoutBudgetDescriptor {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Run fan-out budget descriptor is missing or invalid.");
+	const descriptor = value as Partial<RunFanoutBudgetDescriptor>;
+	if (descriptor.version !== 1 || typeof descriptor.rootRunId !== "string" || !descriptor.rootRunId
+		|| typeof descriptor.directory !== "string" || !descriptor.directory
+		|| !Number.isInteger(descriptor.limit) || (descriptor.limit ?? 0) <= 0
+		|| (descriptor.parentPath !== undefined && typeof descriptor.parentPath !== "string")) {
+		throw new Error("Run fan-out budget descriptor is invalid.");
+	}
+	const directory = validateDirectory(descriptor.directory);
+	const manifest = readManifest(directory);
+	if (manifest.rootRunId !== descriptor.rootRunId || manifest.limit !== descriptor.limit) {
+		throw new Error("Run fan-out budget descriptor does not match its manifest.");
+	}
+	return { version: 1, rootRunId: descriptor.rootRunId, directory, limit: descriptor.limit, ...(descriptor.parentPath ? { parentPath: descriptor.parentPath } : {}) };
+}
+
+export function writeRunFanoutBudgetDescriptor(asyncDir: string, descriptor: RunFanoutBudgetDescriptor): void {
+	const valid = validateRunFanoutBudgetDescriptor(descriptor);
+	fs.mkdirSync(asyncDir, { recursive: true });
+	fs.writeFileSync(path.join(asyncDir, "run-fanout-budget.json"), `${JSON.stringify(valid)}\n`, { mode: 0o600 });
+}
+
+export function readRunFanoutBudgetDescriptor(asyncDir: string | undefined): RunFanoutBudgetDescriptor | undefined {
+	if (!asyncDir) return undefined;
+	const descriptorPath = path.join(asyncDir, "run-fanout-budget.json");
+	if (!fs.existsSync(descriptorPath)) return undefined;
+	try {
+		return validateRunFanoutBudgetDescriptor(JSON.parse(fs.readFileSync(descriptorPath, "utf-8")));
+	} catch (error) {
+		throw new Error(`Invalid persisted run fan-out budget '${descriptorPath}': ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+
+export function encodeRunFanoutBudgetDescriptor(descriptor: RunFanoutBudgetDescriptor): string {
+	return Buffer.from(JSON.stringify(validateRunFanoutBudgetDescriptor(descriptor)), "utf-8").toString("base64url");
+}
+
+export function decodeRunFanoutBudgetDescriptor(encoded: string | undefined): RunFanoutBudgetDescriptor | undefined {
+	if (!encoded) return undefined;
+	try {
+		return validateRunFanoutBudgetDescriptor(JSON.parse(Buffer.from(encoded, "base64url").toString("utf-8")));
+	} catch (error) {
+		throw new Error(`Invalid inherited run fan-out budget: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+
+interface AdmissionLockOwner {
+	pid: number;
+	token: string;
+}
+
+const ADMISSION_LOCK_STALE_MS = 60_000;
+
+function readAdmissionLockOwner(lockPath: string): AdmissionLockOwner | undefined {
+	try {
+		const owner = JSON.parse(fs.readFileSync(path.join(lockPath, "owner.json"), "utf-8")) as Partial<AdmissionLockOwner>;
+		if (Number.isSafeInteger(owner.pid) && (owner.pid ?? 0) > 0 && typeof owner.token === "string" && owner.token) return owner as AdmissionLockOwner;
+	} catch {}
+	return undefined;
+}
+
+function admissionLockIsStale(lockPath: string): boolean {
+	const owner = readAdmissionLockOwner(lockPath);
+	if (owner) {
+		try {
+			process.kill(owner.pid, 0);
+			return false;
+		} catch (error) {
+			return (error as NodeJS.ErrnoException).code !== "EPERM";
+		}
+	}
+	try { return Date.now() - fs.statSync(lockPath).mtimeMs > ADMISSION_LOCK_STALE_MS; }
+	catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+		throw error;
+	}
+}
+
+function withAdmissionLock<T>(directory: string, operation: () => T): T {
+	const lockPath = path.join(directory, "admission.lock");
+	const owner: AdmissionLockOwner = { pid: process.pid, token: randomUUID() };
+	for (let attempt = 0; ; attempt++) {
+		try {
+			fs.mkdirSync(lockPath, { mode: 0o700 });
+			try { fs.writeFileSync(path.join(lockPath, "owner.json"), JSON.stringify(owner), { mode: 0o600 }); }
+			catch (error) {
+				fs.rmSync(lockPath, { recursive: true, force: true });
+				throw error;
+			}
+			break;
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+			if (admissionLockIsStale(lockPath)) {
+				const stalePath = path.join(directory, `admission.stale-${randomUUID()}`);
+				try {
+					fs.renameSync(lockPath, stalePath);
+					fs.rmSync(stalePath, { recursive: true, force: true });
+					continue;
+				} catch (reclaimError) {
+					if ((reclaimError as NodeJS.ErrnoException).code !== "ENOENT") throw reclaimError;
+				}
+			}
+			const delay = DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS[attempt];
+			if (delay === undefined) throw new Error(`Timed out acquiring run fan-out admission lock at '${directory}'.`);
+			waitForFileSystemRetry(delay);
+		}
+	}
+	try { return operation(); }
+	finally {
+		if (readAdmissionLockOwner(lockPath)?.token === owner.token) fs.rmSync(lockPath, { recursive: true, force: true });
+	}
+}
+
+function claimCount(directory: string): number {
+	const claimsDir = path.join(directory, "claims");
+	let entries: fs.Dirent[];
+	try { entries = fs.readdirSync(claimsDir, { withFileTypes: true }); }
+	catch (error) {
+		throw new Error(`Run fan-out claims directory is unreadable at '${claimsDir}': ${error instanceof Error ? error.message : String(error)}`);
+	}
+	return entries.filter((entry) => /^\d{6}\.json$/.test(entry.name)).length;
+}
+
+export function getRunFanoutBudgetSnapshot(descriptor: RunFanoutBudgetDescriptor): RunFanoutBudgetSnapshot {
+	const valid = validateRunFanoutBudgetDescriptor(descriptor);
+	const used = claimCount(valid.directory);
+	return { used, limit: valid.limit, remaining: Math.max(0, valid.limit - used) };
+}
+
+function qualifyRunFanoutPaths(descriptor: RunFanoutBudgetDescriptor, paths: string[]): string[] {
+	const prefix = descriptor.parentPath?.trim();
+	return paths.map((item) => prefix ? `${prefix}/${item}` : item);
+}
+
+function commitRunFanoutBatch<T>(descriptor: RunFanoutBudgetDescriptor, paths: string[], commit: (snapshot: RunFanoutBudgetSnapshot) => T): T {
+	const valid = validateRunFanoutBudgetDescriptor(descriptor);
+	if (paths.length === 0) return commit(getRunFanoutBudgetSnapshot(valid));
+	const qualified = qualifyRunFanoutPaths(valid, paths);
+	return withAdmissionLock(valid.directory, () => {
+		const before = getRunFanoutBudgetSnapshot(valid);
+		if (qualified.length > before.remaining) {
+			throw new RunFanoutLimitError({ code: "RUN_FANOUT_LIMIT", path: qualified[before.remaining] ?? qualified[0]!, requested: qualified.length, ...before });
+		}
+		const created: string[] = [];
+		try {
+			for (const claimPath of qualified) {
+				for (let slot = 0; slot < valid.limit; slot++) {
+					const slotPath = path.join(valid.directory, "claims", `${String(slot).padStart(6, "0")}.json`);
+					try {
+						const fd = fs.openSync(slotPath, "wx", 0o600);
+						created.push(slotPath);
+						try {
+							const claim: ClaimV1 = { version: 1, claimId: randomUUID(), path: claimPath, claimedAt: Date.now() };
+							fs.writeFileSync(fd, `${JSON.stringify(claim)}\n`, "utf-8");
+						} finally { fs.closeSync(fd); }
+						break;
+					} catch (error) {
+						if ((error as NodeJS.ErrnoException).code === "EEXIST") continue;
+						throw error;
+					}
+				}
+			}
+			return commit(getRunFanoutBudgetSnapshot(valid));
+		} catch (error) {
+			for (const slotPath of created) {
+				try { fs.unlinkSync(slotPath); } catch {}
+			}
+			throw error;
+		}
+	});
+}
+
+export function claimRunFanoutBatch(descriptor: RunFanoutBudgetDescriptor, paths: string[]): RunFanoutBudgetSnapshot {
+	return commitRunFanoutBatch(descriptor, paths, (snapshot) => snapshot);
+}
+
+export function claimRunFanoutBatchWithCommit<T>(descriptor: RunFanoutBudgetDescriptor, paths: string[], commit: () => T): T {
+	return commitRunFanoutBatch(descriptor, paths, commit);
+}
+
+export function formatRunFanoutBudget(snapshot: RunFanoutBudgetSnapshot): string {
+	return `Run fan-out: ${snapshot.used}/${snapshot.limit} used, ${snapshot.remaining} remaining`;
+}
+
+function formatRunFanoutRejection(rejection: RunFanoutRejection): string {
+	return `Run fan-out limit reached at ${rejection.path} (${rejection.used}/${rejection.limit} used; ${rejection.requested} requested, ${rejection.remaining} remaining). No children from this admission group were started. Start a new top-level run or raise config.maxSubagentSpawnsPerRun.`;
+}

package/src/runs/shared/single-output.ts

@@ -214,17 +214,19 @@ export function finalizeSingleOutput(params: {
 	outputPath?: string;
 	outputMode?: OutputMode;
 	exitCode: number;
+	/** Keep the saved-output reference when a post-run acceptance gate rejects an otherwise completed child. */
+	preserveSavedOutput?: boolean;
 	savedPath?: string;
 	outputReference?: SavedOutputReference;
 	saveError?: string;
 }): { displayOutput: string; savedPath?: string; outputReference?: SavedOutputReference; saveError?: string } {
 	let displayOutput = params.truncatedOutput || params.fullOutput;
-	if (params.exitCode === 0 && params.savedPath) {
+	if ((params.exitCode === 0 || params.preserveSavedOutput) && params.savedPath) {
 		const outputReference = params.outputReference ?? formatSavedOutputReference(params.savedPath, params.fullOutput);
 		if (params.outputMode === "file-only") {
 			return { displayOutput: outputReference.message, savedPath: params.savedPath, outputReference };
 		}
-		displayOutput += `\n\n${outputReference.message}`;
+		if (!displayOutput.includes(outputReference.message)) displayOutput += `\n\n${outputReference.message}`;
 		return { displayOutput, savedPath: params.savedPath, outputReference };
 	}
 	if (params.exitCode === 0 && params.saveError && params.outputPath) {

package/src/runs/shared/task-intent.ts

@@ -70,6 +70,18 @@ const RESEARCH_AGENT_PATTERNS = [
 	/\bresearch(?:er)?\b/i,
 ];
 
+// Review/severity vocabulary like "must-fix items" or "should-fix tests" is not
+// the verb. Rather than dash-guarding every pattern (which would also suppress
+// CLI flags like "--fix" and genuine clause-level dashes like "branch—fix it"),
+// strip the known severity compounds (must|should|needs + dash + verb) from the
+// task text before matching. Dash coverage: ASCII hyphen + U+2010..U+2015.
+const SEVERITY_COMPOUND_PATTERN = /\b(?:must|should|needs)[\-\u2010-\u2015](?:fix|edit|update|add|remove|replace|create|apply|make|do|implement|modify|delete|patch)\b/gi;
+
+function stripSeverityCompounds(task: string): string {
+	return task.replace(SEVERITY_COMPOUND_PATTERN, " ");
+}
+export { stripSeverityCompounds };
+
 const FIX_OR_PATCH_IMPLEMENTATION_PATTERN = /\b(?:fix|patch)\s+(?:(?:it|this|that|them|each|any|all|these|those)\b|(?:(?:a|an|the|any|all)\s+)?(?:(?:failing|failed|broken|flaky|red|cold|start|current|existing|reported|approved|known|regression|unit|integration|e2e|source|typescript|type-?script|ts|type-?check|compiler)\s+)*(?:bug|defect|issues?|problems?|failures?|regressions?|tests?|errors?|items?|typos?|code|source|implementation|component|function|module|class|method|logic|file|files|readme|docs?|changelog|package\.json|config|manifest|extension|prompt|command|lint(?:ing)?|build|ci|type-?check|type\s+checking)\b)/i;
 
 const WORKER_IMPLEMENTATION_PATTERNS = [
@@ -146,7 +158,7 @@ function hasImplementationIntent(agent: string, taskText: string): boolean {
 }
 
 export function classifyTaskMutationIntent(agent: string, task: string): TaskMutationIntent {
-	const taskText = stripFrameworkInstructions(task);
+	const taskText = stripSeverityCompounds(stripFrameworkInstructions(task));
 	const taskTextWithoutScopedConstraints = stripPatterns(taskText, SCOPED_NO_EDIT_CONSTRAINT_PATTERNS);
 	const prohibitions = analyzeNoEditProhibitions(taskTextWithoutScopedConstraints);
 	if (prohibitions.present) {
@@ -164,7 +176,11 @@ export function expectsImplementationMutation(agent: string, task: string): bool
 	return classifyTaskMutationIntent(agent, task).kind === "implementation";
 }
 
-/** Bare write verbs that make a task write-capable for acceptance inference. */
+/** Bare write verbs that make a task write-capable for acceptance inference.
+ * Severity compounds ("must-fix items") are stripped before matching, so they
+ * are not write imperatives, while CLI flags ("--fix", "-w"), clause-level
+ * dashes ("branch—fix it"), and hyphenated imperatives ("hot-fix the bug")
+ * all stay write-capable. */
 const MAY_MUTATE_VERB_PATTERN = /\b(?:fix|implement|update|write|edit|modify|migrate|delete|remove|refactor|commit)\b/i;
 
 /**
@@ -174,7 +190,7 @@ const MAY_MUTATE_VERB_PATTERN = /\b(?:fix|implement|update|write|edit|modify|mig
  * does.
  */
 export function taskMayMutate(task: string): boolean {
-	const taskText = stripPatterns(stripFrameworkInstructions(task), SCOPED_NO_EDIT_CONSTRAINT_PATTERNS);
+	const taskText = stripPatterns(stripSeverityCompounds(stripFrameworkInstructions(task)), SCOPED_NO_EDIT_CONSTRAINT_PATTERNS);
 	const prohibitions = analyzeNoEditProhibitions(taskText);
 	if (prohibitions.blanket) return false;
 	return MAY_MUTATE_VERB_PATTERN.test(stripPatterns(prohibitions.strippedText, READ_ONLY_DELIVERABLE_PATTERNS));

package/src/runs/shared/worktree.ts

@@ -4,6 +4,7 @@ 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";
+import { getAgentDir } from "../../shared/utils.ts";
 
 export interface WorktreeSetup {
 	cwd: string;
@@ -149,11 +150,17 @@ function resolveRepoState(cwd: string): RepoState {
 
 function normalizeComparableCwd(cwd: string): string {
 	const resolved = path.resolve(cwd);
-	try {
-		return fs.realpathSync(resolved);
-	} catch {
-		// Use the unresolved absolute path when realpath resolution is unavailable.
-		return resolved;
+	let existing = resolved;
+	const missingSegments: string[] = [];
+	while (true) {
+		try {
+			return path.join(fs.realpathSync(existing), ...missingSegments.reverse());
+		} catch {
+			const parent = path.dirname(existing);
+			if (parent === existing) return resolved;
+			missingSegments.push(path.basename(existing));
+			existing = parent;
+		}
 	}
 }
 
@@ -196,6 +203,11 @@ function resolveWorktreeBaseDir(configuredBaseDir: string | undefined, repoRoot:
 
 	const expanded = trimmed.startsWith("~/") ? path.join(os.homedir(), trimmed.slice(2)) : trimmed;
 	const resolved = path.isAbsolute(expanded) ? expanded : path.resolve(repoRoot, expanded);
+	const extensionsDir = normalizeComparableCwd(path.join(getAgentDir(), "extensions"));
+	const relativeToExtensions = path.relative(extensionsDir, normalizeComparableCwd(resolved));
+	if (!relativeToExtensions || (!relativeToExtensions.startsWith(`..${path.sep}`) && relativeToExtensions !== ".." && !path.isAbsolute(relativeToExtensions))) {
+		throw new Error(`worktree base directory cannot be inside Pi extensions directory: ${extensionsDir}. Choose a directory outside it.`);
+	}
 	try {
 		fs.mkdirSync(resolved, { recursive: true });
 	} catch (error) {

package/src/shared/types.ts

@@ -328,6 +328,7 @@ export interface FileMutationEffect {
 	expected: boolean;
 	attempted: boolean;
 	message?: string;
+	resolvedBy?: "llm-intent-arbiter";
 }
 
 export interface EffectsProjection {
@@ -343,6 +344,7 @@ export type ProcessTerminalReason =
 	| "runner-candidate-missing"
 	| "runner-instance-mismatch"
 	| "writer-close-unverified"
+	| "process-tree-unverified"
 	| "canonical-session-unavailable"
 	| "canonical-session-lease-active"
 	| "canonical-session-release-unverified"
@@ -357,6 +359,19 @@ export interface RunnerProcessInstanceExitV1 {
 	signal: string | null;
 }
 
+export type ProcessTreeTerminalV1 =
+	| {
+		state: "observed";
+		mechanism: "posix-process-group";
+		processGroupId: number;
+		verifiedAt: number;
+	}
+	| {
+		state: "unknown";
+		reason: "unsupported-platform" | "signal-failed" | "verification-failed";
+		diagnostic?: string;
+	};
+
 export interface PiWriterProcessInstanceExitV1 {
 	processInstanceId: string;
 	kind: "pi-writer";
@@ -364,6 +379,7 @@ export interface PiWriterProcessInstanceExitV1 {
 	closeObservedAt: number;
 	exitCode: number | null;
 	signal: string | null;
+	processTree: ProcessTreeTerminalV1;
 }
 
 export type ProcessInstanceExitV1 = RunnerProcessInstanceExitV1 | PiWriterProcessInstanceExitV1;
@@ -462,9 +478,30 @@ export interface SteeringNotice {
 	currentSessionId?: string;
 }
 
+export interface RunFanoutBudgetDescriptor {
+	version: 1;
+	rootRunId: string;
+	directory: string;
+	limit: number;
+	parentPath?: string;
+}
+
+export interface RunFanoutBudgetSnapshot {
+	used: number;
+	limit: number;
+	remaining: number;
+}
+
+export interface RunFanoutRejection extends RunFanoutBudgetSnapshot {
+	code: "RUN_FANOUT_LIMIT";
+	path: string;
+	requested: number;
+}
+
 export interface SteeringRecoveryDescriptor {
 	version: 1;
 	launchContractDigest?: string;
+	runFanoutBudget: RunFanoutBudgetDescriptor;
 	sourceRunId: string;
 	agentContract?: AgentContract;
 	agent: string;
@@ -1024,6 +1061,9 @@ export interface Details {
 	// Aggregated cost across all agents in the run
 	totalCost?: CostSummary;
 	spawnBudget?: SpawnBudgetSnapshot;
+	runFanoutBudget?: RunFanoutBudgetSnapshot;
+	runFanoutRejection?: RunFanoutRejection;
+	activeAsyncCapacity?: ActiveAsyncCapacitySnapshot;
 	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
 	capabilityAudit?: SubagentCapabilityAudit;
 	parallelHandoff?: ParallelHandoffReference;
@@ -1323,6 +1363,8 @@ export interface AsyncStatus {
 	workflowGraph?: WorkflowGraphSnapshot;
 	checkpoint?: ChainCheckpointState;
 	processTerminal?: ProcessTerminalV1;
+	runFanoutBudget?: RunFanoutBudgetSnapshot;
+	runFanoutBudgetDescriptor?: RunFanoutBudgetDescriptor;
 	launchContractDigest?: string;
 	launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
 	runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
@@ -1342,6 +1384,10 @@ export interface AsyncStatus {
 		phase?: string;
 		label?: string;
 		workflowKey?: string;
+		/** Child run identity for workflow capacity reconciliation. */
+		runId?: string;
+		/** True only when this workflow child owns a detached async runner. */
+		async?: boolean;
 		parentWorkflowRunId?: string;
 		outputName?: string;
 		structured?: boolean;
@@ -1574,6 +1620,12 @@ export interface ForegroundRunControl {
 	toolCount?: number;
 	/** Independently tracked children for foreground parallel work and fleet inspection. */
 	activeChildren?: Map<number, ForegroundChildControl>;
+	/** Live Prompt Audit redo callback. It is current-session memory only. */
+	promptAuditRedo?: (index: number, guidance: string) => Promise<{ text: string; isError?: boolean }>;
+	/** Memory-only source run for Prompt Audit redo. */
+	sourceRunId?: string;
+	/** Memory-only replacement run started by Prompt Audit redo. */
+	supersededByRunId?: string;
 	/** Scheduling owners that may still launch another child. Removal is safe only at zero. */
 	schedulingOwners?: number;
 	nestedRoute?: NestedRouteInfo;
@@ -1593,6 +1645,12 @@ export interface WaitSubscriptionRecord {
 	expiresAt: number;
 }
 
+export interface ActiveAsyncCapacitySnapshot {
+	used: number;
+	/** Zero means the opt-in cap is disabled. */
+	limit: number;
+}
+
 export interface SubagentState {
 	baseCwd: string;
 	currentSessionId: string | null;
@@ -1613,6 +1671,8 @@ export interface SubagentState {
 		granted?: number;
 		grantHistory?: SpawnBudgetGrant[];
 	};
+	/** Current-session top-level async capacity projection. */
+	activeAsyncCapacity?: ActiveAsyncCapacitySnapshot;
 	asyncJobs: Map<string, AsyncJobState>;
 	/** Current-session active and recent async runs for the native fleet inspector. */
 	fleetJobs?: Map<string, AsyncJobState>;
@@ -1730,9 +1790,12 @@ export interface RunSyncOptions {
 	/** Effective parent wait-tool setting propagated to the child runtime. */
 	waitToolEnabled?: boolean;
 	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
+	runFanoutBudget?: RunFanoutBudgetDescriptor;
 	nestedRoute?: NestedRouteInfo;
 	/** Override the agent's default model (format: "provider/id" or just "id") */
 	modelOverride?: string;
+	/** LLM intent arbiter for the completion mutation guard (rescues read-only review runs). */
+	llmIntentArbiter?: import("../runs/shared/llm-intent-arbiter.ts").TaskMutationArbiter;
 	/** Override the agent's default thinking level for this run */
 	thinkingOverride?: AgentConfig["thinking"];
 	/** Registry models available for heuristic bare-model resolution */
@@ -1756,6 +1819,8 @@ export interface RunSyncOptions {
 		dynamic?: boolean;
 		dynamicGroup?: boolean;
 	};
+	/** Private live callback for the exact child prompt after runtime acceptance injection. */
+	onEffectivePrompt?: (prompt: string) => void;
 }
 
 export type IntercomBridgeMode = "off" | "fork-only" | "always";
@@ -1840,8 +1905,22 @@ export interface ExtensionConfig {
 	maxSubagentDepth?: number;
 	/** Optional cumulative session cap. Unset or 0 means unlimited. */
 	maxSubagentSpawnsPerSession?: number;
+	/** Cumulative logical-child cap for one top-level run tree. Defaults to 64. */
+	maxSubagentSpawnsPerRun?: number;
+	/** Optional active top-level async run cap per parent session. Unset or 0 means unlimited. */
+	maxActiveAsyncRunsPerSession?: number;
 	/** Global cap on simultaneously-running subagent tasks within a single run. Defaults to 20. */
 	globalConcurrencyLimit?: number;
+	/**
+	 * Global default runtime deadline in milliseconds. It replaces the built-in
+	 * 30-minute backstop for single, parallel, and chain launches (foreground, plus
+	 * plain single-agent async runs) when neither the call (`timeoutMs`/`maxRuntimeMs`)
+	 * nor the selected agent provides a timeout. Explicit call values and agent
+	 * frontmatter defaults still win. Composite async runs (chain/parallel/workflow)
+	 * stay unbounded at the top level by design — their children are bounded individually.
+	 * Must be a positive integer; invalid values are ignored.
+	 */
+	timeoutMs?: number;
 	control?: ControlConfig;
 	completionBatch?: CompletionBatchConfig;
 	turnBudget?: TurnBudgetConfig;
@@ -2057,6 +2136,19 @@ export function resolveMaxSubagentSpawnsPerSession(configMaxSpawns?: number): nu
 	return configuredMaxSpawns === 0 ? undefined : configuredMaxSpawns;
 }
 
+export const DEFAULT_MAX_SUBAGENT_SPAWNS_PER_RUN = 64;
+
+export function normalizeMaxSubagentSpawnsPerRun(value: unknown): number | undefined {
+	const normalized = normalizeNonNegativeInteger(value);
+	return normalized !== undefined && normalized > 0 ? normalized : undefined;
+}
+
+export function resolveMaxSubagentSpawnsPerRun(configMaxSpawns?: number): number {
+	return normalizeMaxSubagentSpawnsPerRun(process.env.PI_SUBAGENT_MAX_SPAWNS_PER_RUN)
+		?? normalizeMaxSubagentSpawnsPerRun(configMaxSpawns)
+		?? DEFAULT_MAX_SUBAGENT_SPAWNS_PER_RUN;
+}
+
 // ============================================================================
 // Utility Functions
 // ============================================================================

package/src/shared/utils.ts

@@ -17,6 +17,7 @@ import type { AgentProgress, AsyncStatus, Details, DisplayItem, ErrorInfo, Neste
 const DEFAULT_CONFIG_DIR_NAME = ".pi";
 const PI_CODING_AGENT_PACKAGE_NAME = "@earendil-works/pi-coding-agent";
 export const PI_CODING_AGENT_PACKAGE_ROOT_ENV = "PI_SUBAGENTS_PI_CODING_AGENT_PACKAGE_ROOT";
+export const PROMPT_REDACTED = "[prompt redacted]";
 
 export function resolveWatchPath(
 	watchPath: string,
@@ -354,7 +355,7 @@ function compactCompletedProgress(progress: AgentProgress): AgentProgress {
 		agent: progress.agent,
 		status: progress.status,
 		activityState: progress.activityState,
-		task: progress.task,
+		task: "[prompt redacted]",
 		skills: progress.skills,
 		toolCount: progress.toolCount,
 		tokens: progress.tokens,
@@ -428,6 +429,7 @@ export function compactForegroundResult(result: SingleResult): SingleResult {
 	const toolCalls = result.toolCalls?.length ? result.toolCalls : extractToolCallSummaries(result.messages);
 	return {
 		...result,
+		task: "[prompt redacted]",
 		messages: undefined,
 		progress: undefined,
 		toolCalls: toolCalls.length ? toolCalls : undefined,

package/src/tui/fleet-status.ts

@@ -318,7 +318,7 @@ export class SubagentFleetStatus {
 			this.clearWidget();
 			return;
 		}
-		if (this.entries.length === 0) {
+		if (this.entries.length === 0 && !(this.state.activeAsyncCapacity?.used)) {
 			this.active = false;
 			this.selectedKey = "main";
 			this.lastRenderKey = "";
@@ -413,10 +413,13 @@ export class SubagentFleetStatus {
 	}
 
 	render(width: number, theme: Theme): string[] {
-		if (this.entries.length === 0) return [];
+		if (this.entries.length === 0 && !(this.state.activeAsyncCapacity?.used)) return [];
 		if (!this.active) {
 			const tokens = this.entries.reduce((total, entry) => total + entry.tokens, 0);
-			const label = `${this.entries.length} active ${this.entries.length === 1 ? "agent" : "agents"}`;
+			const capacity = this.state.activeAsyncCapacity;
+			const asyncRuns = capacity ? `Async runs ${capacity.used}/${capacity.limit || "∞"}` : "";
+			const agents = this.entries.length > 0 ? `${this.entries.length} active ${this.entries.length === 1 ? "agent" : "agents"}` : "";
+			const label = [agents, asyncRuns].filter(Boolean).join(" · ");
 			return [truncateToWidth(`  ${theme.fg("muted", label)} · ${theme.fg("dim", `${formatFleetTokens(tokens)} · ↓/← to inspect`)}`, width)];
 		}
 		const roster = this.rosterKeys();
@@ -444,9 +447,8 @@ export class SubagentFleetStatus {
 	}
 
 	private renderEntry(rosterIndex: number, selectedIndex: number, entry: FleetStatusEntry, width: number, theme: Theme): string {
-		const description = entry.description?.replace(/\s+/g, " ").trim();
 		const agent = entry.modelThinking ? `${entry.agent} (${entry.modelThinking})` : entry.agent;
-		const left = `  ${this.bullet(rosterIndex, selectedIndex, theme)} ${theme.fg("muted", agent)} · ${entry.state}${description ? `  ${description}` : ""}`;
+		const left = `  ${this.bullet(rosterIndex, selectedIndex, theme)} ${theme.fg("muted", agent)} · ${entry.state}`;
 		const elapsed = Date.now() - entry.startedAt;
 		const right = theme.fg("dim", `${formatFleetElapsed(elapsed)} · ${formatFleetTokens(entry.tokens)}`);
 		return rightAlign(left, right, width);